Contract spine

@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 @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 '@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 '@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.

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 '@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 '@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 '@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.

Related

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