@moretea-labs/forge 1.7.2 → 1.8.1

package/packages/workflow-runtime/application/interpreter.ts

@@ -0,0 +1,342 @@
+import { createHash } from 'crypto';
+import {
+  validateWorkflowAsset,
+  type WorkflowAssetDefinition,
+  type WorkflowDeterministicScript,
+  type WorkflowJsonValue,
+  type WorkflowStepDefinition,
+  type WorkflowPublicationReceipt,
+} from '../domain/workflow-asset';
+
+export interface WorkflowRunBinding {
+  workId: string;
+  runId: string;
+}
+
+export interface WorkflowStepExecutionResult {
+  outcome: 'succeeded' | 'failed' | 'outcome_unknown';
+  receiptRef?: string;
+  output?: Record<string, unknown>;
+  error?: { code: string; message: string };
+}
+
+export interface WorkflowStepReceipt {
+  stepId: string;
+  outcome: WorkflowStepExecutionResult['outcome'];
+  receiptRef?: string;
+  recordedAt: string;
+}
+
+export interface WorkflowCheckpoint {
+  schemaVersion: 1;
+  binding: WorkflowRunBinding;
+  workflowId: string;
+  version: string;
+  contentDigest: string;
+  status: 'running' | 'reconcile_required' | 'failed' | 'succeeded';
+  nextStepIndex: number;
+  receipts: WorkflowStepReceipt[];
+  reconcileStepId?: string;
+  reconcileWithCapabilityId?: string;
+  outputs: Record<string, Record<string, unknown>>;
+  publicationReceipt?: WorkflowPublicationReceipt;
+  /** Written before dispatch; restart must consult the effect owner before replay. */
+  inFlightStepId?: string;
+}
+
+export interface WorkflowRuntimePorts {
+  executeCapability(input: {
+    binding: WorkflowRunBinding;
+    asset: WorkflowAssetDefinition;
+    step: Extract<WorkflowStepDefinition, { kind?: 'capability' }>;
+    arguments: Record<string, WorkflowJsonValue>;
+  }): Promise<WorkflowStepExecutionResult>;
+  executeScript(input: {
+    binding: WorkflowRunBinding;
+    asset: WorkflowAssetDefinition;
+    step: Extract<WorkflowStepDefinition, { kind: 'script' }>;
+    script: WorkflowDeterministicScript;
+    arguments: Record<string, WorkflowJsonValue>;
+  }): Promise<WorkflowStepExecutionResult>;
+  /** Revalidate retained success against the canonical effect/process authority. Checkpoints never self-authenticate. */
+  validateRetainedStep?(input: {
+    binding: WorkflowRunBinding;
+    asset: WorkflowAssetDefinition;
+    step: WorkflowStepDefinition;
+    receipt: WorkflowStepReceipt;
+    output: Record<string, unknown>;
+  }): Promise<void> | void;
+  checkpoint?(checkpoint: WorkflowCheckpoint): Promise<void> | void;
+  now?: () => Date;
+}
+
+export interface ExecuteWorkflowInput {
+  asset: WorkflowAssetDefinition;
+  binding: WorkflowRunBinding;
+  inputs?: Record<string, WorkflowJsonValue>;
+  startStepIndex?: number;
+  retainedReceipts?: WorkflowStepReceipt[];
+  retainedOutputs?: Record<string, Record<string, unknown>>;
+}
+
+export type WorkflowRunResult = WorkflowCheckpoint & { outputs: Record<string, Record<string, unknown>> };
+
+function requiredText(value: string, code: string): string {
+  const trimmed = value.trim();
+  if (!trimmed || trimmed.length > 256) throw new Error(code);
+  return trimmed;
+}
+
+/** Reject lossy JSON coercions (NaN, getters, Date, undefined, cycles) before checkpointing. */
+function assertJsonValue(value: unknown, depth = 0, ancestors = new Set<object>()): void {
+  if (depth > 32) throw new Error('WORKFLOW_JSON_DEPTH_LIMIT');
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return;
+  if (typeof value === 'number' && Number.isFinite(value)) return;
+  if (typeof value !== 'object' || ancestors.has(value)) throw new Error('WORKFLOW_JSON_VALUE_INVALID');
+  if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) throw new Error('WORKFLOW_JSON_VALUE_INVALID');
+  ancestors.add(value);
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  if (Reflect.ownKeys(value).some(key => typeof key === 'symbol')) throw new Error('WORKFLOW_JSON_VALUE_INVALID');
+  if (Array.isArray(value) && Object.keys(value).length !== value.length) throw new Error('WORKFLOW_JSON_VALUE_INVALID');
+  for (const [key, descriptor] of Object.entries(descriptors)) {
+    if (Array.isArray(value) && key === 'length') continue;
+    if (!descriptor.enumerable || !('value' in descriptor)) throw new Error('WORKFLOW_JSON_VALUE_INVALID');
+    assertJsonValue(descriptor.value, depth + 1, ancestors);
+  }
+  ancestors.delete(value);
+}
+
+export function validateWorkflowRunInputs(
+  asset: WorkflowAssetDefinition,
+  provided: Record<string, WorkflowJsonValue> = {},
+): Record<string, WorkflowJsonValue> {
+  assertJsonValue(provided);
+  const contract = asset.inputContract ?? {};
+  const unknown = Object.keys(provided).filter((key) => !Object.prototype.hasOwnProperty.call(contract, key));
+  if (unknown.length > 0) throw new Error(`WORKFLOW_INPUT_UNKNOWN: ${unknown.sort().join(',')}`);
+  const resolved: Record<string, WorkflowJsonValue> = {};
+  for (const [name, definition] of Object.entries(contract)) {
+    const value = Object.hasOwn(provided, name) ? provided[name] : definition.default;
+    if (value === undefined) {
+      if (definition.required) throw new Error(`WORKFLOW_INPUT_REQUIRED: ${name}`);
+      continue;
+    }
+    const valid = definition.type === 'json'
+      || (definition.type === 'string' && typeof value === 'string')
+      || (definition.type === 'number' && typeof value === 'number' && Number.isFinite(value))
+      || (definition.type === 'boolean' && typeof value === 'boolean');
+    if (!valid) throw new Error(`WORKFLOW_INPUT_TYPE_MISMATCH: ${name}:${definition.type}`);
+    assertJsonValue(value);
+    resolved[name] = value;
+  }
+  return resolved;
+}
+
+function refValue(asset: WorkflowAssetDefinition, inputs: Record<string, WorkflowJsonValue>, namespace: string, key: string): WorkflowJsonValue | undefined {
+  if (namespace === 'input') return inputs[key];
+  if (namespace === 'prompt') return asset.prompts?.[key];
+  if (namespace === 'template') return asset.templates?.[key];
+  if (namespace === 'selector') return asset.selectors?.[key];
+  if (namespace === 'resource') return asset.resources?.[key];
+  return undefined;
+}
+
+function resolveString(asset: WorkflowAssetDefinition, inputs: Record<string, WorkflowJsonValue>, source: string): WorkflowJsonValue {
+  const exact = source.match(/^\{\{(input|prompt|template|selector|resource)\.([A-Za-z0-9._-]+)\}\}$/);
+  if (exact) {
+    const value = refValue(asset, inputs, exact[1]!, exact[2]!);
+    if (value === undefined) throw new Error(`WORKFLOW_REFERENCE_MISSING: ${exact[1]}.${exact[2]}`);
+    return value;
+  }
+  return source.replace(/\{\{(input|prompt|template|selector|resource)\.([A-Za-z0-9._-]+)\}\}/g, (_match, namespace, key) => {
+    const value = refValue(asset, inputs, namespace, key);
+    if (value === undefined) throw new Error(`WORKFLOW_REFERENCE_MISSING: ${namespace}.${key}`);
+    return typeof value === 'string' ? value : JSON.stringify(value);
+  });
+}
+
+export function resolveWorkflowValue(
+  asset: WorkflowAssetDefinition,
+  inputs: Record<string, WorkflowJsonValue>,
+  value: WorkflowJsonValue,
+  outputs: Record<string, Record<string, unknown>> = {},
+): WorkflowJsonValue {
+  if (typeof value === 'string') {
+    const reference = value.match(/^\{\{output\.([A-Za-z0-9_-]+)\.([A-Za-z0-9_-]+)\}\}$/);
+    if (reference) {
+      const output = outputs[reference[1]!];
+      if (!output || !Object.hasOwn(output, reference[2]!)) throw new Error(`WORKFLOW_OUTPUT_REFERENCE_MISSING: ${reference[1]}.${reference[2]}`);
+      return output[reference[2]!] as WorkflowJsonValue;
+    }
+    if (value.includes('{{output.')) throw new Error('WORKFLOW_OUTPUT_REFERENCE_MUST_BE_EXACT');
+    return resolveString(asset, inputs, value);
+  }
+  if (Array.isArray(value)) return value.map((entry) => resolveWorkflowValue(asset, inputs, entry, outputs));
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, resolveWorkflowValue(asset, inputs, entry, outputs)]));
+  }
+  return value;
+}
+
+function resolvedArguments(
+  asset: WorkflowAssetDefinition,
+  inputs: Record<string, WorkflowJsonValue>,
+  step: WorkflowStepDefinition,
+  outputs: Record<string, Record<string, unknown>>,
+): Record<string, WorkflowJsonValue> {
+  return Object.fromEntries(Object.entries(step.input ?? {}).map(([key, value]) => [key, resolveWorkflowValue(asset, inputs, value, outputs)]));
+}
+
+export function retainWorkflowOutput(step: WorkflowStepDefinition, output: Record<string, unknown> = {}): Record<string, unknown> {
+  const selected: Record<string, unknown> = {};
+  for (const [key, contract] of Object.entries(step.outputContract ?? {})) {
+    const value = Object.hasOwn(output, key) ? output[key] : undefined;
+    if (value === undefined && !contract.required) continue;
+    if (value === undefined || contract.type !== 'json' && (typeof value !== contract.type || contract.type === 'number' && !Number.isFinite(value))) throw new Error(`WORKFLOW_OUTPUT_TYPE_MISMATCH: ${step.stepId}.${key}`);
+    assertJsonValue(value);
+    selected[key] = value;
+  }
+  const encoded = JSON.stringify(selected);
+  if (Buffer.byteLength(encoded, 'utf8') > 16 * 1024) throw new Error('WORKFLOW_OUTPUT_BYTE_LIMIT');
+  return JSON.parse(encoded) as Record<string, unknown>;
+}
+
+
+function publicationOutput(outputs: Record<string, Record<string, unknown>>, ref: { stepId: string; field: string }, label: string): string {
+  const value = outputs[ref.stepId]?.[ref.field];
+  if (typeof value !== 'string' || !value.trim()) throw new Error(`WORKFLOW_PUBLICATION_${label}_MISSING`);
+  return value.trim();
+}
+
+export function buildWorkflowPublicationReceipt(
+  asset: WorkflowAssetDefinition,
+  inputs: Record<string, WorkflowJsonValue>,
+  checkpoint: Pick<WorkflowCheckpoint, 'status' | 'receipts' | 'outputs'>,
+): WorkflowPublicationReceipt | undefined {
+  const contract = asset.publication;
+  if (!contract) return undefined;
+  if (checkpoint.status !== 'succeeded') throw new Error('WORKFLOW_PUBLICATION_WORKFLOW_NOT_SUCCEEDED');
+  const account = inputs[contract.accountInput];
+  if (typeof account !== 'string' || !account.trim()) throw new Error('WORKFLOW_PUBLICATION_ACCOUNT_MISSING');
+  const effect = checkpoint.receipts.find(receipt => receipt.stepId === contract.effectStepId && receipt.outcome === 'succeeded');
+  if (!effect?.receiptRef) throw new Error('WORKFLOW_PUBLICATION_EFFECT_RECEIPT_MISSING');
+  const verificationEvidenceRefs = contract.verificationStepIds.map((stepId) => {
+    const receipt = checkpoint.receipts.find(candidate => candidate.stepId === stepId && candidate.outcome === 'succeeded');
+    if (!receipt?.receiptRef) throw new Error(`WORKFLOW_PUBLICATION_VERIFICATION_RECEIPT_MISSING: ${stepId}`);
+    return receipt.receiptRef;
+  });
+  const postUrl = publicationOutput(checkpoint.outputs, contract.postUrlOutput, 'POST_URL');
+  const parsed = new URL(postUrl);
+  if (parsed.protocol !== 'https:' || parsed.username || parsed.password) throw new Error('WORKFLOW_PUBLICATION_POST_URL_INVALID');
+  const postId = publicationOutput(checkpoint.outputs, contract.postIdOutput, 'POST_ID');
+  const contentDigest = publicationOutput(checkpoint.outputs, contract.contentDigestOutput, 'CONTENT_DIGEST');
+  if (!/^sha256:[a-f0-9]{64}$/.test(contentDigest)) throw new Error('WORKFLOW_PUBLICATION_CONTENT_DIGEST_INVALID');
+  const identity = {
+    workflowId: asset.workflowId,
+    channel: contract.channel,
+    account: account.trim(),
+    postId,
+    postUrl: parsed.toString(),
+    contentDigest,
+    publishedAt: effect.recordedAt,
+    effectReceiptRef: effect.receiptRef,
+    verificationEvidenceRefs,
+  };
+  return {
+    schemaVersion: 1,
+    receiptId: `workflow-publication-${createHash('sha256').update(JSON.stringify(identity)).digest('hex')}`,
+    ...identity,
+    timeSource: 'effect_receipt_recorded_at',
+  };
+}
+
+async function persist(ports: WorkflowRuntimePorts, checkpoint: WorkflowCheckpoint): Promise<void> {
+  await ports.checkpoint?.(checkpoint);
+}
+
+export async function executeWorkflow(
+  input: ExecuteWorkflowInput,
+  ports: WorkflowRuntimePorts,
+): Promise<WorkflowRunResult> {
+  const asset = validateWorkflowAsset(input.asset);
+  const binding = {
+    workId: requiredText(input.binding.workId, 'WORKFLOW_RUN_WORK_ID_REQUIRED'),
+    runId: requiredText(input.binding.runId, 'WORKFLOW_RUN_ID_REQUIRED'),
+  };
+  const inputs = validateWorkflowRunInputs(asset, input.inputs);
+  const receipts = [...(input.retainedReceipts ?? [])];
+  const outputs: Record<string, Record<string, unknown>> = structuredClone(input.retainedOutputs ?? {});
+  const startStepIndex = input.startStepIndex ?? 0;
+  if (!Number.isInteger(startStepIndex) || startStepIndex < 0 || startStepIndex > asset.steps.length) throw new Error('WORKFLOW_RUN_START_STEP_INVALID');
+  const retainedStepIds = new Set(asset.steps.slice(0, startStepIndex).map(step => step.stepId));
+  for (const receipt of receipts) if (!retainedStepIds.has(receipt.stepId)) throw new Error('WORKFLOW_FUTURE_RECEIPT_REFUSED');
+  for (let index = 0; index < startStepIndex; index++) {
+    const step = asset.steps[index]!;
+    const succeeded = receipts.filter(receipt => receipt.stepId === step.stepId && receipt.outcome === 'succeeded');
+    if (succeeded.length !== 1 || !succeeded[0]!.receiptRef?.trim()) throw new Error('WORKFLOW_RETAINED_RECEIPT_REQUIRED');
+    outputs[step.stepId] = retainWorkflowOutput(step, outputs[step.stepId]);
+    await ports.validateRetainedStep?.({ binding, asset, step, receipt: succeeded[0]!, output: outputs[step.stepId]! });
+  }
+  for (const stepId of Object.keys(outputs)) if (!retainedStepIds.has(stepId)) throw new Error('WORKFLOW_FUTURE_OUTPUT_REFUSED');
+
+  let checkpoint: WorkflowCheckpoint = {
+    schemaVersion: 1,
+    binding,
+    workflowId: asset.workflowId,
+    version: asset.version,
+    contentDigest: asset.contentDigest,
+    status: 'running',
+    nextStepIndex: startStepIndex,
+    receipts,
+    outputs,
+  };
+  await persist(ports, checkpoint);
+
+  for (let index = startStepIndex; index < asset.steps.length; index += 1) {
+    const step = asset.steps[index]!;
+    const args = resolvedArguments(asset, inputs, step, outputs);
+    checkpoint = { ...checkpoint, inFlightStepId: step.stepId };
+    await persist(ports, checkpoint);
+    let execution: WorkflowStepExecutionResult;
+    try {
+      execution = step.kind === 'script'
+        ? await ports.executeScript({ binding, asset, step, script: asset.scripts![step.scriptRef]!, arguments: args })
+        : await ports.executeCapability({ binding, asset, step, arguments: args });
+      if (execution.outcome === 'succeeded') outputs[step.stepId] = retainWorkflowOutput(step, execution.output);
+    } catch (error) {
+      execution = { outcome: step.idempotency === 'non_idempotent' ? 'outcome_unknown' : 'failed', error: { code: 'WORKFLOW_STEP_INTERRUPTED', message: error instanceof Error ? error.message : String(error) } };
+    }
+    const receipt: WorkflowStepReceipt = {
+      stepId: step.stepId,
+      outcome: execution.outcome,
+      receiptRef: execution.receiptRef,
+      recordedAt: (ports.now?.() ?? new Date()).toISOString(),
+    };
+    receipts.push(receipt);
+
+    if (execution.outcome === 'outcome_unknown') {
+      checkpoint = {
+        ...checkpoint,
+        status: 'reconcile_required',
+        nextStepIndex: index,
+        receipts: [...receipts],
+        reconcileStepId: step.stepId,
+        reconcileWithCapabilityId: step.reconcileWithCapabilityId,
+        outputs: structuredClone(outputs),
+      };
+      await persist(ports, checkpoint);
+      return { ...checkpoint, outputs };
+    }
+    if (execution.outcome === 'failed') {
+      checkpoint = { ...checkpoint, status: 'failed', nextStepIndex: index, receipts: [...receipts], inFlightStepId: undefined, outputs: structuredClone(outputs) };
+      await persist(ports, checkpoint);
+      return { ...checkpoint, outputs };
+    }
+    checkpoint = { ...checkpoint, status: 'running', nextStepIndex: index + 1, receipts: [...receipts], inFlightStepId: undefined, outputs: structuredClone(outputs) };
+    await persist(ports, checkpoint);
+  }
+  checkpoint = { ...checkpoint, status: 'succeeded', nextStepIndex: asset.steps.length, receipts: [...receipts], outputs: structuredClone(outputs) };
+  checkpoint = { ...checkpoint, publicationReceipt: buildWorkflowPublicationReceipt(asset, inputs, checkpoint) };
+  await persist(ports, checkpoint);
+  return { ...checkpoint, outputs };
+}

package/packages/workflow-runtime/domain/workflow-asset.ts

@@ -0,0 +1,223 @@
+import { createHash } from 'crypto';
+
+export const WORKFLOW_ASSET_SCHEMA_VERSION = 1 as const;
+export const WORKFLOW_CONTENT_DIGEST_PREFIX = 'sha256:' as const;
+
+export type WorkflowJsonValue = null | boolean | number | string | WorkflowJsonValue[] | { [key: string]: WorkflowJsonValue };
+
+export interface WorkflowCredentialReference {
+  /** Existing credential authority reference. Never inline a secret value here. */
+  credentialRef: string;
+}
+
+export interface WorkflowDeterministicScript {
+  runtime: 'shell' | 'node' | 'python';
+  body: string;
+  deterministic: true;
+  /** Declares how Process stdout is decoded. It is not replay or side-effect authority. */
+  outputFormat?: 'text' | 'json';
+}
+
+export interface WorkflowInputContract {
+  type: 'string' | 'number' | 'boolean' | 'json';
+  required?: boolean;
+  default?: WorkflowJsonValue;
+}
+
+interface WorkflowStepBase {
+  stepId: string;
+  input?: Record<string, WorkflowJsonValue>;
+  idempotency?: 'idempotent' | 'non_idempotent';
+  reconcileWithCapabilityId?: string;
+  /** Optional read/observation arguments for the declared reconciliation capability. */
+  reconciliationInput?: Record<string, WorkflowJsonValue>;
+  /** Declared fields are the only outputs retained or available to later steps. */
+  outputContract?: Record<string, WorkflowInputContract>;
+}
+
+export interface WorkflowCapabilityStepDefinition extends WorkflowStepBase {
+  kind?: 'capability';
+  capabilityId: string;
+}
+
+export interface WorkflowScriptStepDefinition extends WorkflowStepBase {
+  kind: 'script';
+  scriptRef: string;
+}
+
+export type WorkflowStepDefinition = WorkflowCapabilityStepDefinition | WorkflowScriptStepDefinition;
+
+export interface WorkflowPublicationContract {
+  channel: string;
+  accountInput: string;
+  effectStepId: string;
+  contentDigestOutput: { stepId: string; field: string };
+  postIdOutput: { stepId: string; field: string };
+  postUrlOutput: { stepId: string; field: string };
+  verificationStepIds: string[];
+}
+
+export interface WorkflowPublicationReceipt {
+  schemaVersion: 1;
+  receiptId: string;
+  workflowId: string;
+  channel: string;
+  account: string;
+  postId: string;
+  postUrl: string;
+  contentDigest: string;
+  publishedAt: string;
+  timeSource: 'effect_receipt_recorded_at';
+  effectReceiptRef: string;
+  verificationEvidenceRefs: string[];
+}
+
+export interface WorkflowAssetDefinition {
+  schemaVersion: typeof WORKFLOW_ASSET_SCHEMA_VERSION;
+  workflowId: string;
+  version: string;
+  title?: string;
+  description?: string;
+  inputs?: Record<string, WorkflowJsonValue>;
+  inputContract?: Record<string, WorkflowInputContract>;
+  credentialRefs?: Record<string, WorkflowCredentialReference>;
+  requiredCapabilities?: string[];
+  steps: WorkflowStepDefinition[];
+  prompts?: Record<string, string>;
+  scripts?: Record<string, WorkflowDeterministicScript>;
+  templates?: Record<string, string>;
+  selectors?: Record<string, string>;
+  resources?: Record<string, string>;
+  publication?: WorkflowPublicationContract;
+  contentDigest: string;
+}
+
+export type WorkflowAssetDraft = Omit<WorkflowAssetDefinition, 'contentDigest'>;
+
+const ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const VERSION_PATTERN = /^[A-Za-z0-9][A-Za-z0-9.+_-]{0,63}$/;
+const DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/;
+
+function canonical(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (!value || typeof value !== 'object') return value;
+  return Object.fromEntries(Object.entries(value as Record<string, unknown>)
+    .filter(([, entry]) => entry !== undefined)
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([key, entry]) => [key, canonical(entry)]));
+}
+
+function requireBoundedId(value: string, label: string, pattern = ID_PATTERN): void {
+  if (!pattern.test(value)) throw new Error(`WORKFLOW_ASSET_${label.toUpperCase()}_INVALID: ${value}`);
+}
+
+function requireRecordStrings(value: Record<string, string> | undefined, label: string): void {
+  if (!value) return;
+  for (const [key, entry] of Object.entries(value)) {
+    requireBoundedId(key, `${label}_key`);
+    if (typeof entry !== 'string') throw new Error(`WORKFLOW_ASSET_${label.toUpperCase()}_VALUE_INVALID: ${key}`);
+  }
+}
+
+export function workflowAssetContentDigest(asset: WorkflowAssetDraft | WorkflowAssetDefinition): string {
+  const { contentDigest: _ignored, ...content } = asset as WorkflowAssetDefinition;
+  const json = JSON.stringify(canonical(content));
+  return `${WORKFLOW_CONTENT_DIGEST_PREFIX}${createHash('sha256').update(json).digest('hex')}`;
+}
+
+export function validateWorkflowAsset(asset: WorkflowAssetDefinition): WorkflowAssetDefinition {
+  if (asset.schemaVersion !== WORKFLOW_ASSET_SCHEMA_VERSION) throw new Error('WORKFLOW_ASSET_SCHEMA_VERSION_UNSUPPORTED');
+  requireBoundedId(asset.workflowId, 'workflow_id');
+  requireBoundedId(asset.version, 'version', VERSION_PATTERN);
+  if (!DIGEST_PATTERN.test(asset.contentDigest)) throw new Error('WORKFLOW_ASSET_CONTENT_DIGEST_INVALID');
+  if (workflowAssetContentDigest(asset) !== asset.contentDigest) throw new Error('WORKFLOW_ASSET_CONTENT_DIGEST_MISMATCH');
+  if (!Array.isArray(asset.steps) || asset.steps.length === 0) throw new Error('WORKFLOW_ASSET_STEPS_REQUIRED');
+  if (asset.steps.length > 128) throw new Error('WORKFLOW_ASSET_STEP_LIMIT');
+
+  const stepIds = new Set<string>();
+  for (const step of asset.steps) {
+    requireBoundedId(step.stepId, 'step_id');
+    if (stepIds.has(step.stepId)) throw new Error(`WORKFLOW_ASSET_STEP_DUPLICATE: ${step.stepId}`);
+    stepIds.add(step.stepId);
+    if (step.kind === 'script') {
+      requireBoundedId(step.scriptRef, 'script_ref');
+      if (!asset.scripts?.[step.scriptRef]) throw new Error(`WORKFLOW_ASSET_SCRIPT_REFERENCE_MISSING: ${step.scriptRef}`);
+      if (step.idempotency === 'non_idempotent') throw new Error(`WORKFLOW_ASSET_SCRIPT_NON_IDEMPOTENT_FORBIDDEN: ${step.stepId}`);
+    } else {
+      requireBoundedId(step.capabilityId, 'capability_id');
+      if (step.idempotency === 'non_idempotent' && !step.reconcileWithCapabilityId) {
+        throw new Error(`WORKFLOW_ASSET_NON_IDEMPOTENT_RECONCILIATION_REQUIRED: ${step.stepId}`);
+      }
+    }
+    if (step.reconcileWithCapabilityId) requireBoundedId(step.reconcileWithCapabilityId, 'reconcile_capability_id');
+    if (step.reconciliationInput && !step.reconcileWithCapabilityId) throw new Error(`WORKFLOW_ASSET_RECONCILIATION_INPUT_WITHOUT_CAPABILITY: ${step.stepId}`);
+    for (const [name, contract] of Object.entries(step.outputContract ?? {})) {
+      requireBoundedId(name, 'output_contract_key');
+      if (!contract || !['string', 'number', 'boolean', 'json'].includes(contract.type)) throw new Error('WORKFLOW_OUTPUT_CONTRACT_INVALID');
+    }
+  }
+
+  for (const [name, contract] of Object.entries(asset.inputContract ?? {})) {
+    requireBoundedId(name, 'input_contract_key');
+    if (!contract || !['string', 'number', 'boolean', 'json'].includes(contract.type)) throw new Error(`WORKFLOW_ASSET_INPUT_CONTRACT_INVALID: ${name}`);
+  }
+  for (const capabilityId of asset.requiredCapabilities ?? []) requireBoundedId(capabilityId, 'required_capability_id');
+  for (const [name, ref] of Object.entries(asset.credentialRefs ?? {})) {
+    requireBoundedId(name, 'credential_ref_key');
+    if (!ref || typeof ref.credentialRef !== 'string' || !ref.credentialRef.trim() || ref.credentialRef.length > 512) {
+      throw new Error(`WORKFLOW_ASSET_CREDENTIAL_REFERENCE_INVALID: ${name}`);
+    }
+  }
+  for (const [name, script] of Object.entries(asset.scripts ?? {})) {
+    requireBoundedId(name, 'script_key');
+    if (!script || script.deterministic !== true || !['shell', 'node', 'python'].includes(script.runtime) || typeof script.body !== 'string'
+      || (script.outputFormat !== undefined && !['text', 'json'].includes(script.outputFormat))) {
+      throw new Error(`WORKFLOW_ASSET_SCRIPT_INVALID: ${name}`);
+    }
+  }
+  requireRecordStrings(asset.prompts, 'prompt');
+  requireRecordStrings(asset.templates, 'template');
+  requireRecordStrings(asset.selectors, 'selector');
+  requireRecordStrings(asset.resources, 'resource');
+  if (asset.publication) {
+    const publication = asset.publication;
+    requireBoundedId(publication.channel, 'publication_channel');
+    requireBoundedId(publication.accountInput, 'publication_account_input');
+    if (!asset.inputContract?.[publication.accountInput]) throw new Error('WORKFLOW_ASSET_PUBLICATION_ACCOUNT_INPUT_MISSING');
+    const byId = new Map(asset.steps.map((step, index) => [step.stepId, { step, index }] as const));
+    const effect = byId.get(publication.effectStepId);
+    if (!effect || effect.step.kind === 'script' || effect.step.idempotency !== 'non_idempotent') throw new Error('WORKFLOW_ASSET_PUBLICATION_EFFECT_STEP_INVALID');
+    const refs = [publication.contentDigestOutput, publication.postIdOutput, publication.postUrlOutput];
+    for (const ref of refs) {
+      const source = byId.get(ref.stepId);
+      if (!source || !source.step.outputContract?.[ref.field]) throw new Error('WORKFLOW_ASSET_PUBLICATION_OUTPUT_REF_INVALID');
+      if (source.index <= effect.index) throw new Error('WORKFLOW_ASSET_PUBLICATION_OUTPUT_BEFORE_EFFECT');
+    }
+    if (!Array.isArray(publication.verificationStepIds) || publication.verificationStepIds.length < 1 || publication.verificationStepIds.length > 16) throw new Error('WORKFLOW_ASSET_PUBLICATION_VERIFICATION_INVALID');
+    for (const stepId of publication.verificationStepIds) {
+      const verification = byId.get(stepId);
+      if (!verification || verification.index <= effect.index) throw new Error('WORKFLOW_ASSET_PUBLICATION_VERIFICATION_INVALID');
+    }
+  }
+  return asset;
+}
+
+export function materializeWorkflowAsset(draft: WorkflowAssetDraft): WorkflowAssetDefinition {
+  const asset: WorkflowAssetDefinition = { ...draft, contentDigest: workflowAssetContentDigest(draft) };
+  return validateWorkflowAsset(asset);
+}
+
+export interface WorkflowContentIdentity {
+  workflowId: string;
+  version: string;
+  contentDigest: string;
+}
+
+export function workflowContentIdentity(asset: WorkflowAssetDefinition): WorkflowContentIdentity {
+  validateWorkflowAsset(asset);
+  return { workflowId: asset.workflowId, version: asset.version, contentDigest: asset.contentDigest };
+}
+
+export function sameWorkflowContentIdentity(left: WorkflowContentIdentity, right: WorkflowContentIdentity): boolean {
+  return left.workflowId === right.workflowId && left.version === right.version && left.contentDigest === right.contentDigest;
+}

package/packages/workflow-runtime/index.ts

@@ -0,0 +1 @@
+export * from './api/index';

package/scripts/activate-source-baseline.ts

@@ -6,13 +6,13 @@ import {
   existsSync,
   mkdirSync,
   openSync,
-  readFileSync,
   renameSync,
   writeFileSync,
 } from 'fs';
 import { dirname, join, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { resolveRepoPreferredControllerHome } from '../src/cli/repositories/controller-home';
+import { findRegisteredRepositoryByCheckoutRoot } from '../src/cli/repositories/registry';
 import { cleanupTerminalWork } from '../src/runtime/control-plane/execution/work-terminal-cleanup';
 import { listWorkHandles, type WorkTerminalOutcome } from '../src/runtime/control-plane/execution/work-handle-store';
 import { runProcess } from '../src/effects/process-runner';
@@ -114,13 +114,12 @@ function assertCleanMain(repoRoot: string, expectedHead?: string): string {
   return head;
 }
 
-function repositoryId(repoRoot: string): string {
-  const configPath = join(repoRoot, '.ai', 'harness', 'repository.json');
-  const parsed = JSON.parse(readFileSync(configPath, 'utf8')) as { repoId?: unknown };
-  if (typeof parsed.repoId !== 'string' || !parsed.repoId.trim()) {
+function repositoryId(repoRoot: string, controllerHome: string): string {
+  const repository = findRegisteredRepositoryByCheckoutRoot(repoRoot, controllerHome);
+  if (!repository?.repoId?.trim()) {
     throw new Error('SOURCE_BASELINE_REPOSITORY_ID_UNAVAILABLE');
   }
-  return parsed.repoId.trim();
+  return repository.repoId.trim();
 }
 
 function statePath(controllerHome: string, requestId: string): string {
@@ -194,7 +193,7 @@ async function request(args: string[]): Promise<void> {
   const controllerHome = resolveRepoPreferredControllerHome(repoRoot, option(args, '--controller-home'));
   const requestId = safeId(option(args, '--request-id'));
   const expectedHead = assertCleanMain(repoRoot, option(args, '--expected-head'));
-  const repoId = repositoryId(repoRoot);
+  const repoId = repositoryId(repoRoot, controllerHome);
   const requestedAt = new Date().toISOString();
   let state: SourceBaselineState = {
     schemaVersion: 1,
@@ -251,7 +250,7 @@ async function run(args: string[]): Promise<void> {
   const requestId = safeId(option(args, '--request-id'));
   const expectedHead = option(args, '--expected-head');
   if (!expectedHead) throw new Error('SOURCE_BASELINE_EXPECTED_HEAD_REQUIRED');
-  const repoId = repositoryId(repoRoot);
+  const repoId = repositoryId(repoRoot, controllerHome);
   const requestedAt = new Date().toISOString();
   let state: SourceBaselineState = {
     schemaVersion: 1,
@@ -301,7 +300,6 @@ async function run(args: string[]): Promise<void> {
       const result = await cleanupTerminalWork({
         controllerHome,
         handle,
-        targetBranch: 'main',
         deleteBranch: true,
         terminalOutcome: terminalOutcome(handle),
         failureReason: handle.failureReason ?? 'source baseline terminal cleanup reconciliation',

package/scripts/assemble-template.ts

@@ -153,7 +153,7 @@ const FALLBACK_TEMPLATE_VARIABLES: Record<string, string> = {
   EVALUATION_PROFILE: "browser-qa",
   HANDOFF_PROFILE: "artifact-aware",
   RECOVERY_PROFILE: "hybrid",
-  STATE_PROFILE: "file-backed",
+  STATE_PROFILE: "controller-home",
   CONTEXT_PROFILE: "stable-root-progressive-subdir",
   AI_NATIVE_PROFILE: "none",
   AI_NATIVE_PROFILE_LABEL: "None",

package/scripts/bootstrap-runtime-maintenance-recovery.sh

@@ -5,7 +5,10 @@ REPO_ROOT="${1:-$PWD}"
 REPO_ID="${FORGE_REPO_ID:-}"
 MIN_AGE_MINUTES="${FORGE_RECOVERY_MIN_AGE_MINUTES:-0}"
 CANCEL_PENDING="${FORGE_RECOVERY_CANCEL_PENDING_APPROVALS:-false}"
-CONTROLLER_HOME="${FORGE_CONTROLLER_HOME:-$REPO_ROOT/_ops/controller-home}"
+CONTROLLER_HOME="${FORGE_CONTROLLER_HOME:-${XDG_STATE_HOME:-${HOME:?HOME is required}/.local/state}/forge/controller}"
+if [[ -z "${FORGE_CONTROLLER_HOME:-}" && -z "${XDG_STATE_HOME:-}" ]]; then
+  CONTROLLER_HOME="${HOME:?HOME is required}/.forge/controller"
+fi
 
 cd "$REPO_ROOT"