@forgeax/engine-ddc 0.1.2 → 0.1.4

package/src/publication.ts

@@ -0,0 +1,444 @@
+import { createHash } from 'node:crypto';
+import type {
+  AssetPublicationEnvelope,
+  AssetPublicationExternalEvidence,
+  AssetPublicationFailure,
+  AssetPublicationLocator,
+  AssetPublicationOutput,
+  AssetPublicationRecovery,
+  Result,
+} from '@forgeax/engine-types';
+import { err, ok } from '@forgeax/engine-types';
+
+export interface ScriptablePackPublicationSnapshot {
+  readonly current?: AssetPublicationEnvelope;
+  readonly lastKnownGood?: AssetPublicationEnvelope;
+  readonly failure?: AssetPublicationFailure;
+}
+
+export interface ScriptablePackPublicationError extends AssetPublicationFailure {
+  readonly recovery: AssetPublicationRecovery;
+  readonly current?: AssetPublicationLocator;
+  readonly lastKnownGood?: AssetPublicationLocator;
+}
+
+export interface AcceptedPublicationCandidate {
+  readonly envelope: AssetPublicationEnvelope;
+  readonly cancelled?: boolean;
+}
+
+export interface ScriptablePackPublicationBuildInput {
+  readonly sourcePath: string;
+  readonly sourceRevision: string;
+  /** Optional caller generation; the DDC owner derives one when omitted. */
+  readonly generation?: number;
+  readonly digest: string;
+  readonly packageUrl: string;
+  readonly inputFingerprint: string;
+  readonly outputs: readonly AssetPublicationOutput[];
+  readonly externalEvidence: readonly AssetPublicationExternalEvidence[];
+}
+
+/**
+ * DDC-owned publication authority for source keyed producers.  Transport
+ * adapters may stage bytes, but they do not retain current/LKG or generation
+ * state themselves.
+ */
+export interface AcceptedPublicationStore {
+  observe(sourcePath: string): ScriptablePackPublicationSnapshot;
+  stage(
+    sourcePath: string,
+    candidate: AcceptedPublicationCandidate,
+  ): Result<void, ScriptablePackPublicationError>;
+  commit(
+    sourcePath: string,
+    candidate: AcceptedPublicationCandidate,
+    commitRoute: () => Promise<void> | void,
+  ): Promise<Result<ScriptablePackPublicationSnapshot, ScriptablePackPublicationError>>;
+  discard(sourcePath: string, candidate: AssetPublicationEnvelope): void;
+  restore(sourcePath: string, snapshot: ScriptablePackPublicationSnapshot): void;
+}
+
+function stable(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stable).join(',')}]`;
+  if (value !== null && typeof value === 'object') {
+    const record = value as Record<string, unknown>;
+    return `{${Object.keys(record)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${stable(record[key])}`)
+      .join(',')}}`;
+  }
+  return JSON.stringify(value) ?? 'null';
+}
+
+function digest(value: unknown): string {
+  return `sha256:${createHash('sha256').update(stable(value)).digest('hex')}`;
+}
+
+export function scriptablePackOutputSetDigest(outputs: readonly AssetPublicationOutput[]): string {
+  return digest(
+    outputs.map((output) => ({
+      guid: output.guid.toLowerCase(),
+      sourceKey: output.sourceKey,
+      kind: output.kind,
+      digest: output.digest,
+      refs: [...output.refs].map((guid) => guid.toLowerCase()),
+    })),
+  );
+}
+
+/** Derive a stable positive generation from the accepted publication tuple. */
+export function scriptablePackPublicationGeneration(input: {
+  readonly sourceRevision: string;
+  readonly digest: string;
+  readonly outputSetDigest: string;
+}): number {
+  const hash = createHash('sha256')
+    .update(input.sourceRevision)
+    .update('\n')
+    .update(input.digest)
+    .update('\n')
+    .update(input.outputSetDigest)
+    .digest('hex');
+  const generation = Number.parseInt(hash.slice(0, 8), 16);
+  return generation > 0 ? generation : 1;
+}
+
+/** Build the complete producer-owned tuple after the package route is finalized. */
+export function createAcceptedPublication(
+  input: ScriptablePackPublicationBuildInput,
+): AssetPublicationEnvelope {
+  const outputSetDigest = scriptablePackOutputSetDigest(input.outputs);
+  const publicationGeneration =
+    input.generation ??
+    scriptablePackPublicationGeneration({
+      sourceRevision: input.sourceRevision,
+      digest: input.digest,
+      outputSetDigest,
+    });
+  return {
+    schemaVersion: 'asset-publication/1',
+    sourcePath: input.sourcePath,
+    sourceRevision: input.sourceRevision,
+    generation: publicationGeneration,
+    digest: input.digest,
+    outputSetDigest,
+    outputs: input.outputs,
+    receipt: {
+      schemaVersion: 'asset-publication-receipt/1',
+      sourcePath: input.sourcePath,
+      sourceRevision: input.sourceRevision,
+      inputFingerprint: input.inputFingerprint,
+      outputDigest: input.digest,
+      outputSetDigest,
+      externalEvidence: input.externalEvidence,
+    },
+    externalEvidence: input.externalEvidence,
+    current: {
+      generation: publicationGeneration,
+      digest: input.digest,
+      outputSetDigest,
+      packageUrl: input.packageUrl,
+      receiptKey: input.inputFingerprint,
+    },
+  };
+}
+
+function locatorFor(envelope: AssetPublicationEnvelope): AssetPublicationLocator {
+  return {
+    generation: envelope.generation,
+    digest: envelope.digest,
+    outputSetDigest: envelope.outputSetDigest,
+    packageUrl: envelope.current?.packageUrl ?? '',
+    receiptKey: envelope.receipt.inputFingerprint,
+  };
+}
+
+function recoveryFor(retryable: boolean, useLastKnownGood: boolean): AssetPublicationRecovery {
+  return {
+    retryable,
+    preserveCurrent: true,
+    useLastKnownGood,
+    actions: retryable
+      ? ['inspect-publication-failure', 'retry-rebuild', 'continue-last-known-good']
+      : ['inspect-publication-failure', 'edit-source', 'continue-last-known-good'],
+  };
+}
+
+function failure(
+  envelope: AssetPublicationEnvelope,
+  code: string,
+  stage: AssetPublicationFailure['stage'],
+  reason: string,
+  retryable: boolean,
+  current: AssetPublicationEnvelope | undefined,
+  lastKnownGood: AssetPublicationEnvelope | undefined,
+): ScriptablePackPublicationError {
+  return {
+    code,
+    stage,
+    sourcePath: envelope.sourcePath,
+    sourceRevision: envelope.sourceRevision,
+    generation: envelope.generation,
+    reason,
+    recovery: recoveryFor(retryable, lastKnownGood !== undefined),
+    ...(current === undefined ? {} : { current: locatorFor(current) }),
+    ...(lastKnownGood === undefined ? {} : { lastKnownGood: locatorFor(lastKnownGood) }),
+  };
+}
+
+function validateOutputs(
+  envelope: AssetPublicationEnvelope,
+  current: AssetPublicationEnvelope | undefined,
+  lastKnownGood: AssetPublicationEnvelope | undefined,
+): ScriptablePackPublicationError | undefined {
+  const guids = new Set<string>();
+  const sourceKeys = new Set<string>();
+  for (const output of envelope.outputs) {
+    const guid = output.guid.toLowerCase();
+    if (guids.has(guid) || sourceKeys.has(output.sourceKey)) {
+      return failure(
+        envelope,
+        'asset-publication-output-duplicate',
+        'output',
+        'publication output GUIDs and sourceKeys must be unique',
+        false,
+        current,
+        lastKnownGood,
+      );
+    }
+    guids.add(guid);
+    sourceKeys.add(output.sourceKey);
+  }
+  if (
+    envelope.outputs.length === 0 ||
+    scriptablePackOutputSetDigest(envelope.outputs) !== envelope.outputSetDigest
+  ) {
+    return failure(
+      envelope,
+      'asset-publication-output-set-mismatch',
+      'receipt',
+      'receipt outputSetDigest does not match the complete output tuple',
+      false,
+      current,
+      lastKnownGood,
+    );
+  }
+  return undefined;
+}
+
+function validateReceipt(
+  envelope: AssetPublicationEnvelope,
+  current: AssetPublicationEnvelope | undefined,
+  lastKnownGood: AssetPublicationEnvelope | undefined,
+): ScriptablePackPublicationError | undefined {
+  const receipt = envelope.receipt;
+  if (
+    receipt.schemaVersion !== 'asset-publication-receipt/1' ||
+    receipt.sourcePath !== envelope.sourcePath ||
+    receipt.sourceRevision !== envelope.sourceRevision ||
+    receipt.outputSetDigest !== envelope.outputSetDigest ||
+    receipt.outputDigest !== envelope.digest ||
+    stable(receipt.externalEvidence) !== stable(envelope.externalEvidence)
+  ) {
+    return failure(
+      envelope,
+      'asset-publication-receipt-mismatch',
+      'receipt',
+      'publication receipt does not match the candidate output tuple',
+      false,
+      current,
+      lastKnownGood,
+    );
+  }
+  return undefined;
+}
+
+function validateEnvelope(
+  envelope: AssetPublicationEnvelope,
+  current: AssetPublicationEnvelope | undefined,
+  lastKnownGood: AssetPublicationEnvelope | undefined,
+): ScriptablePackPublicationError | undefined {
+  if (envelope.schemaVersion !== 'asset-publication/1') {
+    return failure(
+      envelope,
+      'asset-publication-schema-invalid',
+      'receipt',
+      'publication envelope schemaVersion is not supported',
+      false,
+      current,
+      lastKnownGood,
+    );
+  }
+  if (!Number.isSafeInteger(envelope.generation) || envelope.generation < 1) {
+    return failure(
+      envelope,
+      'asset-publication-generation-invalid',
+      'receipt',
+      'publication generation must be a positive integer',
+      false,
+      current,
+      lastKnownGood,
+    );
+  }
+  const outputError = validateOutputs(envelope, current, lastKnownGood);
+  if (outputError !== undefined) return outputError;
+  const receiptError = validateReceipt(envelope, current, lastKnownGood);
+  if (receiptError !== undefined) return receiptError;
+  // Re-running a deterministic producer (for example a cold cook after a
+  // rebuild) can yield the exact same publication tuple.  That is an
+  // idempotent request, not a late result: rejecting it here makes the
+  // editor's retry/cold-cook operation fail even though the published asset is
+  // already the requested content.  A same-generation tuple with any changed
+  // source/digest/output-set fact remains stale and is rejected below.
+  const sameTuple =
+    current !== undefined &&
+    envelope.generation === current.generation &&
+    envelope.sourcePath === current.sourcePath &&
+    envelope.sourceRevision === current.sourceRevision &&
+    envelope.digest === current.digest &&
+    envelope.outputSetDigest === current.outputSetDigest;
+  if (sameTuple) return undefined;
+  if (current !== undefined && envelope.generation <= current.generation) {
+    return failure(
+      envelope,
+      'asset-publication-stale',
+      'cancelled',
+      `candidate generation ${envelope.generation} is not newer than current ${current.generation}`,
+      true,
+      current,
+      lastKnownGood,
+    );
+  }
+  return undefined;
+}
+
+interface PublicationState {
+  snapshot: ScriptablePackPublicationSnapshot;
+  readonly staged: Map<string, AssetPublicationEnvelope>;
+}
+
+function validateCandidate(
+  state: PublicationState,
+  candidate: AcceptedPublicationCandidate,
+  cancelledReason: string,
+): ScriptablePackPublicationError | undefined {
+  const current = state.snapshot.current;
+  const lastKnownGood = state.snapshot.lastKnownGood ?? current;
+  if (candidate.cancelled === true) {
+    return failure(
+      candidate.envelope,
+      'asset-publication-cancelled',
+      'cancelled',
+      cancelledReason,
+      true,
+      current,
+      lastKnownGood,
+    );
+  }
+  return validateEnvelope(candidate.envelope, current, lastKnownGood);
+}
+
+async function publishCandidate(
+  state: PublicationState,
+  candidate: AcceptedPublicationCandidate,
+  commitRoute: () => Promise<void> | void,
+): Promise<Result<ScriptablePackPublicationSnapshot, ScriptablePackPublicationError>> {
+  const current = state.snapshot.current;
+  const lastKnownGood = state.snapshot.lastKnownGood ?? current;
+  const invalid = validateCandidate(
+    state,
+    candidate,
+    'publication request was cancelled before route commit',
+  );
+  if (invalid !== undefined) {
+    state.snapshot = { ...state.snapshot, failure: invalid };
+    return err(invalid);
+  }
+  try {
+    await commitRoute();
+  } catch (error) {
+    const failed = failure(
+      candidate.envelope,
+      'asset-publication-route-failed',
+      'route',
+      error instanceof Error ? error.message : String(error),
+      true,
+      current,
+      lastKnownGood,
+    );
+    state.snapshot = { ...state.snapshot, failure: failed };
+    return err(failed);
+  }
+  const published = {
+    ...candidate.envelope,
+    current: locatorFor(candidate.envelope),
+    ...(current === undefined ? {} : { lastKnownGood: locatorFor(current) }),
+    recovery: recoveryFor(false, current !== undefined),
+  };
+  state.snapshot = {
+    current: published,
+    ...(current === undefined ? {} : { lastKnownGood: current }),
+  };
+  return ok(state.snapshot);
+}
+
+/** Create the one DDC publication authority shared by dev attempts. */
+export function createAcceptedPublicationStore(): AcceptedPublicationStore {
+  const states = new Map<string, PublicationState>();
+  function stateFor(sourcePath: string): PublicationState {
+    const existing = states.get(sourcePath);
+    if (existing !== undefined) return existing;
+    const created: PublicationState = { snapshot: {}, staged: new Map() };
+    states.set(sourcePath, created);
+    return created;
+  }
+  function candidateKey(candidate: AssetPublicationEnvelope): string {
+    return `${candidate.generation}\0${candidate.digest}\0${candidate.outputSetDigest}`;
+  }
+  return {
+    observe(sourcePath) {
+      return stateFor(sourcePath).snapshot;
+    },
+    stage(sourcePath, candidate) {
+      const invalid = validateCandidate(
+        stateFor(sourcePath),
+        candidate,
+        'publication request was cancelled before DDC commit',
+      );
+      if (invalid !== undefined) return err(invalid);
+      stateFor(sourcePath).staged.set(candidateKey(candidate.envelope), candidate.envelope);
+      return ok(undefined);
+    },
+    async commit(sourcePath, candidate, commitRoute) {
+      const key = candidateKey(candidate.envelope);
+      const state = stateFor(sourcePath);
+      if (!state.staged.has(key)) {
+        const current = state.snapshot.current;
+        const lastKnownGood = state.snapshot.lastKnownGood ?? current;
+        return err(
+          failure(
+            candidate.envelope,
+            'asset-publication-cancelled',
+            'cancelled',
+            'publication candidate was discarded before DDC commit',
+            true,
+            current,
+            lastKnownGood,
+          ),
+        );
+      }
+      const result = await publishCandidate(state, candidate, commitRoute);
+      state.staged.delete(key);
+      return result;
+    },
+    discard(sourcePath, candidate) {
+      stateFor(sourcePath).staged.delete(candidateKey(candidate));
+    },
+    restore(sourcePath, snapshot) {
+      const state = stateFor(sourcePath);
+      state.staged.clear();
+      state.snapshot = snapshot;
+    },
+  };
+}

package/src/session.ts

@@ -0,0 +1,254 @@
+import type { DdcEntry, StagedDdcEntry } from './entry-store.js';
+import { DdcEntryStore } from './entry-store.js';
+import type { DdcCommitResult, DdcHead, DdcLease } from './lifecycle.js';
+import { DdcLifecycle } from './lifecycle.js';
+
+export interface DdcSessionOptions {
+  readonly generation: number;
+  readonly leaseTtlMs?: number;
+}
+
+export interface DdcGenerationCandidate {
+  readonly generation: number;
+  readonly lease: DdcLease;
+  readonly previousHead: DdcHead;
+}
+
+export interface DdcGenerationEntryCandidate extends DdcGenerationCandidate {
+  readonly staged: StagedDdcEntry;
+}
+
+export interface DdcSessionMetrics {
+  readonly hitCount: number;
+  readonly missCount: number;
+  readonly corruptCount: number;
+  readonly writeFailureCount: number;
+}
+
+type MutableDdcGenerationCandidate = Omit<DdcGenerationCandidate, 'lease'> & {
+  lease: DdcLease;
+};
+
+type MutableDdcGenerationEntryCandidate = Omit<DdcGenerationEntryCandidate, 'lease'> & {
+  lease: DdcLease;
+};
+
+type HeartbeatTimer = ReturnType<typeof setTimeout>;
+
+interface MutableMetrics {
+  hitCount: number;
+  missCount: number;
+  corruptCount: number;
+  writeFailureCount: number;
+}
+
+export class DdcGenerationSession {
+  public readonly generation: number;
+  private readonly lifecycle: DdcLifecycle;
+  private readonly entries: DdcEntryStore;
+  private readonly candidates = new Map<string, MutableDdcGenerationCandidate>();
+  private readonly heartbeatTimers = new Map<string, HeartbeatTimer>();
+  private readonly counters: MutableMetrics = {
+    hitCount: 0,
+    missCount: 0,
+    corruptCount: 0,
+    writeFailureCount: 0,
+  };
+  private accepting = true;
+
+  public constructor(root: string, options: DdcSessionOptions) {
+    if (!Number.isSafeInteger(options.generation) || options.generation < 1) {
+      throw new TypeError('DDC generation must be a positive safe integer');
+    }
+    this.generation = options.generation;
+    this.lifecycle = new DdcLifecycle(
+      root,
+      options.leaseTtlMs === undefined ? undefined : { leaseTtlMs: options.leaseTtlMs },
+    );
+    this.entries = new DdcEntryStore(root);
+  }
+
+  public async beginCandidate(guid: string, desiredKey: string): Promise<DdcGenerationCandidate> {
+    const head = await this.inspect(guid, desiredKey);
+    const lease = await this.lifecycle.begin(guid, desiredKey);
+    const candidate: MutableDdcGenerationCandidate = {
+      generation: this.generation,
+      lease,
+      previousHead: head,
+    };
+    this.candidates.set(lease.attempt, candidate);
+    this.scheduleHeartbeat(candidate);
+    return candidate;
+  }
+
+  public async stageEntry(entry: DdcEntry): Promise<DdcGenerationEntryCandidate> {
+    this.assertOpen();
+    const candidate = (await this.beginCandidate(
+      entry.guid,
+      entry.key,
+    )) as MutableDdcGenerationCandidate;
+    try {
+      const staged = await this.entries.stage(entry);
+      const entryCandidate: MutableDdcGenerationEntryCandidate = Object.assign(candidate, {
+        staged,
+      });
+      this.candidates.set(candidate.lease.attempt, entryCandidate);
+      return entryCandidate;
+    } catch (error) {
+      await this.lifecycle.fail(candidate.lease, {
+        code: 'ddc-entry-stage-failed',
+        detail: error instanceof Error ? error.message : String(error),
+      });
+      this.stopHeartbeat(candidate);
+      this.candidates.delete(candidate.lease.attempt);
+      this.counters.writeFailureCount += 1;
+      throw error;
+    }
+  }
+
+  public async inspect(guid: string, desiredKey: string): Promise<DdcHead> {
+    this.assertOpen();
+    const head = await this.lifecycle.inspect(guid, desiredKey);
+    if (head.state === 'current') this.counters.hitCount += 1;
+    else this.counters.missCount += 1;
+    return head;
+  }
+
+  public async commitCandidate(
+    candidate: DdcGenerationCandidate,
+    validatedKey: string,
+  ): Promise<DdcCommitResult> {
+    const registered = this.assertCandidate(candidate);
+    try {
+      const result = await this.lifecycle.commit(registered.lease, validatedKey);
+      if (result.result === 'invalid') this.counters.corruptCount += 1;
+      this.stopHeartbeat(registered);
+      this.candidates.delete(registered.lease.attempt);
+      return result;
+    } catch (error) {
+      this.stopHeartbeat(registered);
+      this.counters.writeFailureCount += 1;
+      throw error;
+    }
+  }
+
+  public async commitEntry(
+    candidate: DdcGenerationEntryCandidate,
+    validatedKey: string,
+  ): Promise<DdcCommitResult> {
+    const registered = this.assertCandidate(candidate);
+    try {
+      await this.entries.publish(candidate.staged);
+      const result = await this.lifecycle.commit(registered.lease, validatedKey);
+      this.stopHeartbeat(registered);
+      this.candidates.delete(registered.lease.attempt);
+      return result;
+    } catch (error) {
+      this.stopHeartbeat(registered);
+      await this.lifecycle.fail(registered.lease, {
+        code: 'ddc-entry-publish-failed',
+        detail: error instanceof Error ? error.message : String(error),
+      });
+      await this.entries.discard(candidate.staged).catch(() => {});
+      this.candidates.delete(registered.lease.attempt);
+      this.counters.writeFailureCount += 1;
+      throw error;
+    }
+  }
+
+  public async discardCandidate(candidate: DdcGenerationCandidate): Promise<void> {
+    const registered = this.candidates.get(candidate.lease.attempt);
+    if (registered === undefined) return;
+    try {
+      this.stopHeartbeat(registered);
+      await this.lifecycle.discard(registered.lease);
+      this.candidates.delete(registered.lease.attempt);
+    } catch (error) {
+      this.counters.writeFailureCount += 1;
+      throw error;
+    }
+  }
+
+  public async discardEntry(candidate: DdcGenerationEntryCandidate): Promise<void> {
+    await Promise.all([this.discardCandidate(candidate), this.entries.discard(candidate.staged)]);
+  }
+
+  public async restoreEntry(candidate: DdcGenerationEntryCandidate): Promise<void> {
+    const registered = this.candidates.get(candidate.lease.attempt);
+    let restoreError: unknown;
+    try {
+      await this.lifecycle.restore(candidate.previousHead);
+    } catch (error) {
+      restoreError = error;
+    } finally {
+      await this.entries.discard(candidate.staged).catch(() => {});
+      if (registered !== undefined) {
+        this.stopHeartbeat(registered);
+        this.candidates.delete(registered.lease.attempt);
+      }
+    }
+    if (restoreError !== undefined) throw restoreError;
+  }
+
+  public metrics(): DdcSessionMetrics {
+    return { ...this.counters };
+  }
+
+  public async close(): Promise<void> {
+    if (!this.accepting) return;
+    this.accepting = false;
+    for (const timer of this.heartbeatTimers.values()) clearTimeout(timer);
+    this.heartbeatTimers.clear();
+    const pending = [...this.candidates.values()];
+    for (const candidate of pending) {
+      try {
+        await this.lifecycle.discard(candidate.lease);
+      } catch {
+        this.counters.writeFailureCount += 1;
+      }
+    }
+    this.candidates.clear();
+  }
+
+  private assertOpen(): void {
+    if (!this.accepting) throw new Error('DDC generation session is closed');
+  }
+
+  private assertCandidate(candidate: DdcGenerationCandidate): MutableDdcGenerationCandidate {
+    this.assertOpen();
+    const registered = this.candidates.get(candidate.lease.attempt);
+    if (candidate.generation !== this.generation || registered === undefined) {
+      throw new Error('DDC candidate belongs to another generation session');
+    }
+    return registered;
+  }
+
+  private scheduleHeartbeat(candidate: MutableDdcGenerationCandidate): void {
+    const attempt = candidate.lease.attempt;
+    this.stopHeartbeat(candidate);
+    const delay = Math.max(1, Math.floor((candidate.lease.expiresAt - Date.now()) / 2));
+    const timer = setTimeout(() => {
+      this.heartbeatTimers.delete(attempt);
+      if (!this.accepting || this.candidates.get(attempt) !== candidate) return;
+      void this.lifecycle
+        .heartbeat(candidate.lease)
+        .then((lease) => {
+          if (!this.accepting || this.candidates.get(attempt) !== candidate) return;
+          candidate.lease = lease;
+          this.scheduleHeartbeat(candidate);
+        })
+        .catch(() => {
+          this.stopHeartbeat(candidate);
+        });
+    }, delay);
+    timer.unref?.();
+    this.heartbeatTimers.set(attempt, timer);
+  }
+
+  private stopHeartbeat(candidate: DdcGenerationCandidate): void {
+    const timer = this.heartbeatTimers.get(candidate.lease.attempt);
+    if (timer === undefined) return;
+    clearTimeout(timer);
+    this.heartbeatTimers.delete(candidate.lease.attempt);
+  }
+}