Contract spine

@hellmai/lumenflow-control-plane-sdk (WU-3516, INIT-091 phase 2) publishes five small, digest-comparable modules that together form the cross-repo contract spine: the shared vocabulary a Cloud consumer pins against without needing repository access to this codebase.

Each module’s only runtime dependency is zod (the SDK’s license boundary) — none of the five import any other @hellmai/lumenflow-* package at runtime, so a Cloud consumer’s build never pulls in dev-repo internals.

Compatibility manifest

compatibility-manifest.ts pins the exact released version of the dev tooling, runner, pack, and API a given SDK build was cut against, plus the protocol revisions that build speaks:

import {
  CONTROL_PLANE_COMPATIBILITY_MANIFEST_V1,
  CONTROL_PLANE_COMPATIBILITY_MANIFEST_V1_DIGEST,
  isFullyVerifiedCompatibilityManifest,
} from '@hellmai/lumenflow-control-plane-sdk';

Every pin (dev, runner, pack, api) must resolve to an immutable semver release — the schema’s regex structurally rejects 'main', 'HEAD', 'latest', 'workspace:*', or any other non-semver string, so a consumer’s accidental branch-head resolution fails loudly instead of silently drifting.

At authoring time (before this package has gone through release control), every pin carries release_status: 'awaiting_release_control' and release_reference: null. Release tooling flips a pin to verified with a real tag/SHA when a release is actually cut; until then, isFullyVerifiedCompatibilityManifest returns false for the published fixture, which is the honest state of an unreleased build.

Error taxonomy

error-taxonomy.ts publishes the canonical mapping every dev-side typed domain error crosses the wire as: an error class (deterministic — operator must fix, retrying cannot help — or transient — environment or timing, a retry may succeed), a retryable boolean, and a stable reason_code.

import { classifyControlPlaneErrorCode } from '@hellmai/lumenflow-control-plane-sdk';

classifyControlPlaneErrorCode('GIT_COMMAND_FAILED');
// { error_class: 'transient', retryable: true, domain_source: 'GitError', ... }

classifyControlPlaneErrorCode('SOME_UNPUBLISHED_CODE'); // undefined

An unrecognized wire code returns undefined rather than a guessed classification — a typo or a future addition not yet mirrored here must be visibly unclassified, not silently treated as retryable or not.

Adoption note: additive error codes

Adopting this taxonomy adds a stable code field to error response bodies; it does not remove or rename the existing status, message, or detail fields. That is backward-compatible for clients that tolerate additive fields. Exact object equality assertions will observe the new field, however, so update those tests to include code or assert the fields the client contract actually consumes.

Protocol capability registry

protocol-capability-registry.ts declares which wire protocol revisions this SDK release understands (kernel event envelopes, private MCP execution authority) and negotiates a shared revision between a client and a server:

import { negotiateProtocolCapability } from '@hellmai/lumenflow-control-plane-sdk';

negotiateProtocolCapability({
  protocol: 'kernel_events',
  clientRevisions: ['1', '2'],
  serverRevisions: ['1'],
});
// { compatible: true, selected_revision: '1' }

Negotiation is explicit refusal, never a best-effort fallback: an unknown protocol or a revision set with no overlap returns { compatible: false, reason } rather than guessing a revision to speak.

This is a different registry from the pack-capability registry (capability_factory augmentations a pack manifest declares) shipped earlier — this one is about wire protocol revisions, independent of which packs either side has installed.

Evidence index

evidence-index.ts enumerates every evidence artifact a release’s contract spine produced — the compatibility manifest, the error taxonomy, the protocol capability registry, and the WU-status mapping below — each with a canonical digest, plus a top-level digest over the whole set:

import { verifyReleaseEvidenceIndexV1 } from '@hellmai/lumenflow-control-plane-sdk';

verifyReleaseEvidenceIndexV1(fetchedIndex); // pure recomputation, no repo access needed

verifyReleaseEvidenceIndexV1 is a pure structural recomputation — no filesystem or network access — so a Cloud consumer can verify a fetched index without checking out this repository.

WU status to Work Graph state mapping

work-graph-state-mapping.ts publishes, as data, the mapping between this repo’s WU status vocabulary and the cross-repo Work Graph state model:

import { mapWuStatusToWorkGraphState } from '@hellmai/lumenflow-control-plane-sdk';

mapWuStatusToWorkGraphState('in_progress'); // 'running'
mapWuStatusToWorkGraphState('blocked'); // 'waiting'
mapWuStatusToWorkGraphState('not_a_real_status'); // undefined

Dev WU status	Work Graph state
`todo`, `backlog`	`proposed`
`ready`	`admitted`
`in_progress`	`running`
`blocked`, `waiting`	`waiting`
`done`, `completed`	`completed`
`failed`	`failed`
`cancelled`, `abandoned`, `deferred`, `closed`, `superseded`	`cancelled`

A status outside this published vocabulary resolves to undefined rather than a guessed default, so an unrecognized status is visibly unmapped instead of silently miscategorized.

Control-plane SDK — the package this contract spine ships from.
Connected Compute — the generalised assignment/result contract that reuses this taxonomy for error classification.