ai-workflow-logic 0.1.5 → 0.1.6

package/src/checkpoint-store.ts

@@ -11,6 +11,21 @@ import type {
 } from 'ai-workflow-contract';
 import type { WorkCtrlFlowSnapshot, WorkCtrlFlowStore } from 'work-ctrl-flow-contract';
 import { normalizeFlowRunCheckpoint } from './run-checkpoint.js';
+import {
+  FlowRunCheckpointTransitionError,
+  FlowRunCheckpointVersionConflictError,
+} from './errors.js';
+import {
+  validateCheckpointAgainstFrozenProfile,
+  type FlowRunCheckpointAdmissionRuntime,
+} from './checkpoint-profile.js';
+
+export {
+  FlowRunCheckpointTransitionError,
+  FlowRunCheckpointVersionConflictError,
+} from './errors.js';
+
+const compareCodeUnits = (left: string, right: string): number => left < right ? -1 : left > right ? 1 : 0;
 
 export interface WorkCtrlFlowCheckpointStoreOptions {
   readonly instanceId: string;
@@ -110,23 +125,6 @@ export function createWorkCtrlFlowCheckpointStore(
   };
 }
 
-export class FlowRunCheckpointVersionConflictError extends Error {
-  constructor(
-    public readonly expectedVersion: number | null,
-    public readonly actualVersion: number | null,
-  ) {
-    super(`Flow run checkpoint version conflict: expected ${String(expectedVersion)}, actual ${String(actualVersion)}`);
-    this.name = 'FlowRunCheckpointVersionConflictError';
-  }
-}
-
-export class FlowRunCheckpointTransitionError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = 'FlowRunCheckpointTransitionError';
-  }
-}
-
 function checkpointKey(key: FlowRunCheckpointKey): string {
   return JSON.stringify([key.instanceId, key.runId]);
 }
@@ -552,15 +550,71 @@ export function validateFlowRunCheckpointTransition(
       next as AIWorkflowFlowRunCheckpoint & { readonly profile: { readonly kind: 'AIDataWorkflow'; readonly runGraph: FlowClosedObject } },
     );
   }
+  validateStepExtensionTransition(current, next);
   validateAgentStateTransition(current, next);
 }
 
+function validateStepExtensionTransition(
+  current: AIWorkflowFlowRunCheckpoint,
+  next: AIWorkflowFlowRunCheckpoint,
+): void {
+  const before = current.stepExtensions;
+  const after = next.stepExtensions;
+  if (before === undefined || after === undefined) {
+    if (before !== after) {
+      throw new FlowRunCheckpointTransitionError('Run step extension membership is immutable after checkpoint version zero.');
+    }
+    return;
+  }
+  const beforeSteps = Object.keys(before.byStepId).sort(compareCodeUnits);
+  const afterSteps = Object.keys(after.byStepId).sort(compareCodeUnits);
+  if (!sameClosedValue(beforeSteps, afterSteps)) {
+    throw new FlowRunCheckpointTransitionError('Run step extension step membership is immutable.');
+  }
+  let changed = 0;
+  for (const stepId of beforeSteps) {
+    const beforeKinds = Object.keys(before.byStepId[stepId]).sort(compareCodeUnits);
+    const afterKinds = Object.keys(after.byStepId[stepId]).sort(compareCodeUnits);
+    if (!sameClosedValue(beforeKinds, afterKinds)) {
+      throw new FlowRunCheckpointTransitionError(`Run step extension kind membership is immutable for ${stepId}.`);
+    }
+    for (const kind of beforeKinds) {
+      const prior = before.byStepId[stepId][kind];
+      const candidate = after.byStepId[stepId][kind];
+      if (prior.schemaRef !== candidate.schemaRef) {
+        throw new FlowRunCheckpointTransitionError(`Run step extension schema is immutable for ${stepId}/${kind}.`);
+      }
+      if (sameClosedValue(prior, candidate)) continue;
+      changed += 1;
+      if (candidate.revision !== prior.revision + 1) {
+        throw new FlowRunCheckpointTransitionError(`Run step extension revision must advance exactly once for ${stepId}/${kind}.`);
+      }
+      if (sameClosedValue(prior.value, candidate.value)) {
+        throw new FlowRunCheckpointTransitionError(`Run step extension ${stepId}/${kind} cannot advance without a value change.`);
+      }
+    }
+  }
+  if (changed > 1) {
+    throw new FlowRunCheckpointTransitionError('One checkpoint transition may mutate at most one run step extension fact.');
+  }
+}
+
 /** In-memory semantic owner used to validate the port before physical CAS is introduced. */
 export class InMemoryFlowRunCheckpointStore implements FlowRunCheckpointStore<FlowRunProfileState> {
   readonly #checkpoints = new Map<string, AIWorkflowFlowRunCheckpoint>();
+  readonly #admission: FlowRunCheckpointAdmissionRuntime;
+
+  constructor(options: Partial<FlowRunCheckpointAdmissionRuntime> = {}) {
+    this.#admission = Object.freeze({
+      ...(options.profileAuthority === undefined ? {} : { profileAuthority: options.profileAuthority }),
+      extensionCodecs: options.extensionCodecs ?? Object.freeze({ resolve: () => undefined }),
+    });
+  }
 
   async load(key: FlowRunCheckpointKey): Promise<AIWorkflowFlowRunCheckpoint | undefined> {
-    return this.#checkpoints.get(checkpointKey(key));
+    const checkpoint = this.#checkpoints.get(checkpointKey(key));
+    if (checkpoint) validateCheckpointAgainstFrozenProfile(checkpoint, this.#admission);
+    return checkpoint;
   }
 
   async commit(input: FlowRunCheckpointCommit<FlowRunProfileState>): Promise<AIWorkflowFlowRunCheckpoint> {
@@ -572,6 +626,7 @@ export class InMemoryFlowRunCheckpointStore implements FlowRunCheckpointStore<Fl
       throw new FlowRunCheckpointVersionConflictError(input.expectedVersion, actualVersion);
     }
     validateFlowRunCheckpointTransition(current, checkpoint);
+    validateCheckpointAgainstFrozenProfile(checkpoint, this.#admission);
     this.#checkpoints.set(key, checkpoint);
     return checkpoint;
   }

package/src/errors.ts

@@ -13,3 +13,20 @@ export class AIWorkflowResourceProjectionError extends AIWorkflowFoundationError
     this.name = 'AIWorkflowResourceProjectionError';
   }
 }
+
+export class FlowRunCheckpointVersionConflictError extends Error {
+  constructor(
+    public readonly expectedVersion: number | null,
+    public readonly actualVersion: number | null,
+  ) {
+    super(`Flow run checkpoint version conflict: expected ${String(expectedVersion)}, actual ${String(actualVersion)}`);
+    this.name = 'FlowRunCheckpointVersionConflictError';
+  }
+}
+
+export class FlowRunCheckpointTransitionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'FlowRunCheckpointTransitionError';
+  }
+}

package/src/index.ts

@@ -66,6 +66,24 @@ export {
   projectFlowRunCheckpoint,
 } from './checkpoint-store.js';
 export type { WorkCtrlFlowCheckpointStoreOptions } from './checkpoint-store.js';
+export {
+  createInitialRunStepExtensions,
+  validateCheckpointAgainstFrozenProfile,
+} from './checkpoint-profile.js';
+export type {
+  FlowRunCheckpointAdmissionRuntime,
+  FlowRunProfileAuthorityPort,
+  FlowRunProfileAuthorityRequest,
+  FrozenFlowRunProfileAuthority,
+  FrozenRunStepExtensionDefinition,
+} from './checkpoint-profile.js';
+export { mutateRunStepExtension } from './step-extension.js';
+export type {
+  RunStepExtensionMutationConfig,
+  RunStepExtensionMutationInvocation,
+  RunStepExtensionMutationRuntime,
+  RunStepExtensionSelector,
+} from './step-extension.js';
 
 export class AIWorkflowEffectHandlerNotFoundError extends AIWorkflowFoundationError {
   constructor(

package/src/run-checkpoint.ts

@@ -65,7 +65,7 @@ export function normalizeFlowRunCheckpoint(value: unknown): AIWorkflowFlowRunChe
       'nodeSidecars',
       'profile',
     ],
-    [],
+    ['stepExtensions'],
     'checkpoint',
   );
   const schemaVersion = dataField(record, 'schemaVersion', 'checkpoint.schemaVersion');
@@ -88,6 +88,9 @@ export function normalizeFlowRunCheckpoint(value: unknown): AIWorkflowFlowRunChe
     dataField(record, 'nodeSidecars', 'checkpoint.nodeSidecars'),
     'checkpoint.nodeSidecars',
   );
+  const stepExtensions = Object.prototype.hasOwnProperty.call(record, 'stepExtensions')
+    ? normalizeRunStepExtensions(dataField(record, 'stepExtensions', 'checkpoint.stepExtensions'))
+    : undefined;
   const profile = normalizeProfile(dataField(record, 'profile', 'checkpoint.profile'), runId);
   validateProfileProjection(profile, { input, state, output, controllerSidecars, nodeSidecars });
   return Object.freeze({
@@ -102,10 +105,49 @@ export function normalizeFlowRunCheckpoint(value: unknown): AIWorkflowFlowRunChe
     output,
     controllerSidecars,
     nodeSidecars,
+    ...(stepExtensions === undefined ? {} : { stepExtensions }),
     profile,
   });
 }
 
+function normalizeRunStepExtensions(value: unknown) {
+  const root = exactRecord(value, ['schemaVersion', 'byStepId'], [], 'checkpoint.stepExtensions');
+  if (dataField(root, 'schemaVersion', 'checkpoint.stepExtensions.schemaVersion') !== 'depa.flow-run-step-extensions/v1') {
+    invalid('FLOW_RUN_STEP_EXTENSIONS_SCHEMA_INVALID', 'checkpoint.stepExtensions.schemaVersion', 'Step extension state schema is invalid.');
+  }
+  const byStepIdValue = plainRecord(dataField(root, 'byStepId', 'checkpoint.stepExtensions.byStepId'), 'checkpoint.stepExtensions.byStepId');
+  const byStepId: Record<string, Record<string, { readonly schemaRef?: string; readonly revision: number; readonly value: FlowClosedValue }>> = {};
+  for (const stepId of stringDataKeys(byStepIdValue, 'checkpoint.stepExtensions.byStepId').sort(compareCodeUnits)) {
+    canonicalIdentity(stepId, `checkpoint.stepExtensions.byStepId.${stepId}`);
+    const extensionsValue = plainRecord(dataField(byStepIdValue, stepId, `checkpoint.stepExtensions.byStepId.${stepId}`), `checkpoint.stepExtensions.byStepId.${stepId}`);
+    const extensionFacts: Record<string, { readonly schemaRef?: string; readonly revision: number; readonly value: FlowClosedValue }> = {};
+    for (const kind of stringDataKeys(extensionsValue, `checkpoint.stepExtensions.byStepId.${stepId}`).sort(compareCodeUnits)) {
+      canonicalIdentity(kind, `checkpoint.stepExtensions.byStepId.${stepId}.${kind}`);
+      const location = `checkpoint.stepExtensions.byStepId.${stepId}.${kind}`;
+      const fact = exactRecord(dataField(extensionsValue, kind, location), ['revision', 'value'], ['schemaRef'], location);
+      const schemaRef = Object.prototype.hasOwnProperty.call(fact, 'schemaRef')
+        ? canonicalIdentity(dataField(fact, 'schemaRef', `${location}.schemaRef`), `${location}.schemaRef`)
+        : undefined;
+      extensionFacts[kind] = Object.freeze({
+        ...(schemaRef === undefined ? {} : { schemaRef }),
+        revision: nonNegativeSafeInteger(dataField(fact, 'revision', `${location}.revision`), `${location}.revision`),
+        value: cloneClosedValue(dataField(fact, 'value', `${location}.value`), `${location}.value`),
+      });
+    }
+    if (Object.keys(extensionFacts).length === 0) {
+      invalid('FLOW_RUN_STEP_EXTENSIONS_EMPTY_STEP', `checkpoint.stepExtensions.byStepId.${stepId}`, 'Extension step entries cannot be empty.');
+    }
+    byStepId[stepId] = Object.freeze(extensionFacts);
+  }
+  if (Object.keys(byStepId).length === 0) {
+    invalid('FLOW_RUN_STEP_EXTENSIONS_EMPTY', 'checkpoint.stepExtensions.byStepId', 'Empty extension state must be omitted.');
+  }
+  return Object.freeze({
+    schemaVersion: 'depa.flow-run-step-extensions/v1' as const,
+    byStepId: Object.freeze(byStepId),
+  });
+}
+
 function validateProfileProjection(
   profile: FlowRunProfileState,
   envelope: {

package/src/step-extension.ts

@@ -0,0 +1,121 @@
+import type {
+  FlowClosedValue,
+  FlowRunCheckpointRuntime,
+  FlowRunStepExtensions,
+} from 'ai-workflow-contract';
+import type { DefinitionStepExtensionCodecRegistryPort } from 'flow-step-space-contract';
+import {
+  validateCheckpointAgainstFrozenProfile,
+  type FlowRunProfileAuthorityPort,
+} from './checkpoint-profile.js';
+import { normalizeFlowClosedValue } from './run-checkpoint.js';
+
+export interface RunStepExtensionMutationRuntime extends FlowRunCheckpointRuntime {
+  readonly profileAuthority: FlowRunProfileAuthorityPort;
+  readonly extensionCodecs: DefinitionStepExtensionCodecRegistryPort;
+}
+
+export interface RunStepExtensionSelector {
+  readonly instanceId: string;
+  readonly runId: string;
+  readonly stepId: string;
+  readonly kind: string;
+}
+
+export interface RunStepExtensionMutationInvocation {
+  readonly expectedRevision: number;
+  readonly value: FlowClosedValue;
+}
+
+export interface RunStepExtensionMutationConfig {}
+
+/** Targeted Processor: output = fn(runtime, selector, invocation, config). */
+export async function mutateRunStepExtension(
+  runtime: RunStepExtensionMutationRuntime,
+  selector: RunStepExtensionSelector,
+  invocation: RunStepExtensionMutationInvocation,
+  config: RunStepExtensionMutationConfig,
+) {
+  exactOwnData(config, [], 'config');
+  const selectorRecord = exactOwnData(selector, ['instanceId', 'runId', 'stepId', 'kind'], 'selector');
+  const normalizedSelector = Object.fromEntries(['instanceId', 'runId', 'stepId', 'kind'].map((name) => [
+    name,
+    ownDataValue(selectorRecord, name, `selector.${name}`),
+  ])) as unknown as RunStepExtensionSelector;
+  for (const [name, value] of Object.entries(normalizedSelector)) {
+    if (typeof value !== 'string' || !value || value !== value.trim()) throw new Error(`Run step extension selector ${name} is invalid.`);
+  }
+  const invocationRecord = exactOwnData(invocation, ['expectedRevision', 'value'], 'invocation');
+  const expectedRevision = ownDataValue(invocationRecord, 'expectedRevision', 'invocation.expectedRevision');
+  const invocationValue = ownDataValue(invocationRecord, 'value', 'invocation.value') as FlowClosedValue;
+  if (!Number.isSafeInteger(expectedRevision) || (expectedRevision as number) < 0) {
+    throw new Error('Run step extension expectedRevision is invalid.');
+  }
+  const checkpoint = await runtime.checkpointStore.load({
+    instanceId: normalizedSelector.instanceId,
+    runId: normalizedSelector.runId,
+  });
+  if (!checkpoint) throw new Error(`Run ${normalizedSelector.runId} does not exist.`);
+  const normalized = checkpoint;
+  const authority = validateCheckpointAgainstFrozenProfile(normalized, runtime);
+  if (!authority) throw new Error('Run step extension mutation requires frozen profile authority.');
+  const definition = authority.extensionsByStepId[normalizedSelector.stepId]?.[normalizedSelector.kind];
+  const fact = normalized.stepExtensions?.byStepId[normalizedSelector.stepId]?.[normalizedSelector.kind];
+  if (!definition || !fact) throw new Error(`Run step extension ${normalizedSelector.stepId}/${normalizedSelector.kind} is not admitted.`);
+  if (fact.revision !== expectedRevision) {
+    throw new Error(`Run step extension revision conflict: expected ${String(expectedRevision)}, actual ${fact.revision}.`);
+  }
+  const registration = runtime.extensionCodecs.resolve(normalizedSelector.kind);
+  if (!registration?.codec || registration.schemaRef !== definition.schemaRef) {
+    throw new Error(`Run step extension codec is unavailable for ${normalizedSelector.stepId}/${normalizedSelector.kind}.`);
+  }
+  const value = normalizeFlowClosedValue(registration.codec.normalize(invocationValue as never, {
+    kind: normalizedSelector.kind,
+    ...(definition.schemaRef === undefined ? {} : { schemaRef: definition.schemaRef }),
+    sourceRef: `frozen-step://${normalizedSelector.stepId}/${normalizedSelector.kind}`,
+    stepId: normalizedSelector.stepId,
+  }), `runStepExtension.${normalizedSelector.stepId}.${normalizedSelector.kind}`);
+  const stepExtensions: FlowRunStepExtensions = {
+    schemaVersion: 'depa.flow-run-step-extensions/v1',
+    byStepId: {
+      ...normalized.stepExtensions!.byStepId,
+      [normalizedSelector.stepId]: {
+        ...normalized.stepExtensions!.byStepId[normalizedSelector.stepId],
+        [normalizedSelector.kind]: {
+          ...(definition.schemaRef === undefined ? {} : { schemaRef: definition.schemaRef }),
+          revision: fact.revision + 1,
+          value,
+        },
+      },
+    },
+  };
+  return runtime.checkpointStore.commit({
+    expectedVersion: normalized.version,
+    checkpoint: {
+      ...normalized,
+      version: normalized.version + 1,
+      stepExtensions,
+    },
+  });
+}
+
+function exactOwnData(value: unknown, fields: readonly string[], label: string): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${label} must be a plain own-data object.`);
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) throw new Error(`${label} must be a plain own-data object.`);
+  const keys = Reflect.ownKeys(value);
+  if (keys.some((key) => typeof key !== 'string')) throw new Error(`${label} contains a symbol field.`);
+  const actual = (keys as string[]).sort(compareCodeUnits);
+  const expected = [...fields].sort(compareCodeUnits);
+  if (JSON.stringify(actual) !== JSON.stringify(expected)) throw new Error(`${label} fields are invalid.`);
+  for (const key of actual) ownDataValue(value as Record<string, unknown>, key, `${label}.${key}`);
+  return value as Record<string, unknown>;
+}
+
+function ownDataValue(record: Record<string, unknown>, key: string, label: string): unknown {
+  const descriptor = Object.getOwnPropertyDescriptor(record, key);
+  if (!descriptor || !descriptor.enumerable || !('value' in descriptor)) throw new Error(`${label} must be an enumerable own-data field.`);
+  return descriptor.value;
+}
+
+const compareCodeUnits = (left: string, right: string): number => left < right ? -1 : left > right ? 1 : 0;