@lumenflow/control-plane-sdk

Control plane sync contracts and adapters for LumenFlow runtime.

What It Provides

• HTTP transport for control plane synchronization
• Policy sync, approval flows, and evidence upload contracts
• Adapter interfaces for custom control plane implementations
• Machine-readable orchestration plan / launch / status contracts shared by local CLI and lumenflow.cloud

Orchestration State Contract

The SDK publishes a transport-friendly orchestration contract so humans, local agents, and hosted control-plane launchers can exchange the same initiative state without vendor-specific prompt parsing.

The contract is deliberately split into three documents:

• OrchestrationPlanDocument Dependency-driven logical waves for an initiative.
• OrchestrationLaunchDocument Launch receipts for a specific launch_attempt.
• OrchestrationStatusDocument Reconciled live execution state, including next_safe_actions.

Key fields:

• logical_wave The dependency-graph wave for a WU or wave group.
• launch_attempt The specific orchestration attempt that wrote launch artifacts.
• orchestration_state Shared execution state such as eligible, active, worker_returned, ready_for_finish, awaiting_merge, contaminated, and done.
• claimed_mode Distinguishes local worktree execution from branch-pr / cloud execution.

The status contract is rich enough to represent:

• local worktree execution and completion
• branch-pr / cloud awaiting_merge state
• explicit blockers and contamination paths
• capacity-driven queuing via queued_by_capacity
• orchestrator next steps via next_safe_actions

Parsing and Normalization

Use the parser helpers when reading JSON from local artifacts or cloud APIs:

import {
  parseOrchestrationLaunchDocument,
  parseOrchestrationPlanDocument,
  parseOrchestrationStatusDocument,
} from '@lumenflow/control-plane-sdk';

const plan = parseOrchestrationPlanDocument(rawPlanJson);
const launch = parseOrchestrationLaunchDocument(rawLaunchJson);
const status = parseOrchestrationStatusDocument(rawStatusJson);

The parsers preserve backward compatibility with older payloads that still omit optional orchestration fields. For example, legacy ready status values are normalized to the shared eligible state, and omitted logical_waves, capacity values, or next_safe_actions are derived or defaulted safely.

License

LumenFlow Proprietary. See LICENSE.