gsd-pi 2.79.0-dev.579e14e9b → 2.79.0-dev.bbb2f88ce

package/src/resources/extensions/gsd/tests/uok-contracts.test.ts

@@ -1,5 +1,10 @@
+// GSD2 UOK Contract Versioning and DB Authority Tests
+
 import test from "node:test";
 import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 
 import type {
   AuditEventEnvelope,
@@ -11,8 +16,17 @@ import type {
   WriteRecord,
   WriterToken,
 } from "../uok/contracts.ts";
-import { buildAuditEnvelope } from "../uok/audit.ts";
+import {
+  CURRENT_UOK_CONTRACT_VERSION,
+  normalizeAuditEvent,
+  validateAuditEvent,
+  validateDispatchEnvelope,
+  validateTurnResult,
+} from "../uok/contracts.ts";
+import { buildAuditEnvelope, emitUokAuditEvent } from "../uok/audit.ts";
 import { buildDispatchEnvelope, explainDispatch } from "../uok/dispatch-envelope.ts";
+import { buildTurnTimeline } from "../uok/timeline.ts";
+import { _getAdapter, closeDatabase, openDatabase } from "../gsd-db.ts";
 
 test("uok contracts serialize/deserialize turn envelopes", () => {
   const contract: TurnContract = {
@@ -37,6 +51,7 @@ test("uok contracts serialize/deserialize turn envelopes", () => {
   };
 
   const result: TurnResult = {
+    version: CURRENT_UOK_CONTRACT_VERSION,
     traceId: contract.traceId,
     turnId: contract.turnId,
     iteration: contract.iteration,
@@ -56,8 +71,10 @@ test("uok contracts serialize/deserialize turn envelopes", () => {
 
   const roundTrip = JSON.parse(JSON.stringify(result)) as TurnResult;
   assert.equal(roundTrip.turnId, "turn-1");
+  assert.equal(roundTrip.version, CURRENT_UOK_CONTRACT_VERSION);
   assert.equal(roundTrip.gateResults?.[0]?.gateId, "Q3");
   assert.equal(roundTrip.phaseResults.length, 3);
+  assert.equal(validateTurnResult(roundTrip).ok, true);
 });
 
 test("uok contracts include required DAG node kinds", () => {
@@ -84,9 +101,11 @@ test("uok audit envelope includes trace/turn/causality fields", () => {
   });
 
   assert.equal(event.traceId, "trace-xyz");
+  assert.equal(event.version, CURRENT_UOK_CONTRACT_VERSION);
   assert.equal(event.turnId, "turn-xyz");
   assert.equal(event.causedBy, "turn-start");
   assert.equal(event.payload.status, "completed");
+  assert.equal(validateAuditEvent(event).ok, true);
 });
 
 test("uok dispatch envelope carries scheduler reason and constraints", () => {
@@ -107,9 +126,98 @@ test("uok dispatch envelope carries scheduler reason and constraints", () => {
   });
 
   assert.equal(envelope.nodeKind, "unit");
+  assert.equal(envelope.version, CURRENT_UOK_CONTRACT_VERSION);
   assert.equal(envelope.reason.reasonCode, "dependency");
   assert.deepEqual(envelope.constraints?.dependsOn, ["plan-gate"]);
   assert.ok(explainDispatch(envelope).includes("execute-task M001/S01/T01"));
+  assert.equal(validateDispatchEnvelope(envelope).ok, true);
+});
+
+test("uok contracts normalize legacy records without losing payload fields", () => {
+  const legacy = {
+    eventId: "event-legacy",
+    traceId: "trace-legacy",
+    category: "orchestration",
+    type: "turn-result",
+    ts: new Date().toISOString(),
+    payload: { status: "completed", extra: "preserved" },
+  } as AuditEventEnvelope;
+
+  const normalized = normalizeAuditEvent(legacy);
+  assert.equal(normalized.version, "0");
+  assert.equal(normalized.payload.extra, "preserved");
+  assert.equal(validateAuditEvent(legacy).ok, true);
+});
+
+test("uok audit emission writes DB as authoritative before jsonl projection", (t) => {
+  const basePath = mkdtempSync(join(tmpdir(), "gsd-uok-db-audit-"));
+  mkdirSync(join(basePath, ".gsd"), { recursive: true });
+  t.after(() => {
+    closeDatabase();
+    rmSync(basePath, { recursive: true, force: true });
+  });
+
+  assert.equal(openDatabase(join(basePath, ".gsd", "gsd.db")), true);
+  emitUokAuditEvent(
+    basePath,
+    buildAuditEnvelope({
+      traceId: "trace-db",
+      turnId: "turn-db",
+      category: "orchestration",
+      type: "turn-start",
+      payload: { unitType: "execute-task" },
+    }),
+  );
+
+  const row = _getAdapter()!.prepare(
+    "SELECT payload_json FROM audit_events WHERE trace_id = 'trace-db' AND turn_id = 'turn-db'",
+  ).get() as { payload_json: string } | undefined;
+  assert.ok(row, "DB audit row should be written");
+  assert.equal(JSON.parse(row.payload_json).contractVersion, CURRENT_UOK_CONTRACT_VERSION);
+
+  const projection = readFileSync(join(basePath, ".gsd", "audit", "events.jsonl"), "utf-8");
+  assert.ok(projection.includes("trace-db"), "jsonl projection should still be written");
+});
+
+test("uok timeline prefers DB records over jsonl projection when DB is available", (t) => {
+  const basePath = mkdtempSync(join(tmpdir(), "gsd-uok-timeline-"));
+  const auditDir = join(basePath, ".gsd", "audit");
+  mkdirSync(auditDir, { recursive: true });
+  writeFileSync(
+    join(auditDir, "events.jsonl"),
+    `${JSON.stringify({
+      version: CURRENT_UOK_CONTRACT_VERSION,
+      eventId: "jsonl-only",
+      traceId: "trace-timeline",
+      turnId: "turn-timeline",
+      category: "orchestration",
+      type: "jsonl-projection",
+      ts: "2026-01-01T00:00:00.000Z",
+      payload: {},
+    })}\n`,
+  );
+  t.after(() => {
+    closeDatabase();
+    rmSync(basePath, { recursive: true, force: true });
+  });
+
+  assert.equal(openDatabase(join(basePath, ".gsd", "gsd.db")), true);
+  emitUokAuditEvent(
+    basePath,
+    buildAuditEnvelope({
+      traceId: "trace-timeline",
+      turnId: "turn-timeline",
+      category: "orchestration",
+      type: "db-authoritative",
+      payload: {},
+    }),
+  );
+
+  const timeline = buildTurnTimeline(basePath, { traceId: "trace-timeline", turnId: "turn-timeline" });
+  assert.equal(timeline.authoritative, "db");
+  assert.equal(timeline.degraded, false);
+  assert.ok(timeline.entries.some((entry) => entry.type === "db-authoritative"));
+  assert.equal(timeline.entries.some((entry) => entry.type === "jsonl-projection"), false);
 });
 
 test("uok writer records serialize sequence metadata", () => {

package/src/resources/extensions/gsd/tests/uok-loop-adapter-writer.test.ts

@@ -63,3 +63,101 @@ test("uok turn observer adds writer sequence metadata to audit events", (t) => {
   assert.equal(payloads[1]?.writeSequence, 2);
   assert.equal(typeof payloads[0]?.writerTokenId, "string");
 });
+
+test("uok turn observer releases writer token when validation throws", (t) => {
+  const basePath = mkdtempSync(join(tmpdir(), "gsd-uok-loop-writer-throw-"));
+  resetWriterTokensForTests();
+  t.after(() => {
+    resetWriterTokensForTests();
+    rmSync(basePath, { recursive: true, force: true });
+  });
+
+  const observer = createTurnObserver({
+    basePath,
+    gitAction: "status-only",
+    gitPush: false,
+    enableAudit: false,
+    enableGitops: false,
+  });
+
+  observer.onTurnStart({
+    basePath,
+    traceId: "trace-throw",
+    turnId: "turn-throw",
+    iteration: 1,
+    unitType: "execute-task",
+    unitId: "M001/S01/T01",
+    startedAt: new Date().toISOString(),
+  });
+  assert.equal(hasActiveWriterToken(basePath, "turn-throw"), true);
+
+  // Invalid payload (missing required fields like status/finishedAt) should
+  // trigger validateTurnResult to fail and throw.
+  assert.throws(() => {
+    observer.onTurnResult({
+      traceId: "trace-throw",
+      turnId: "turn-throw",
+      // @ts-expect-error intentionally invalid for test
+      iteration: "not-a-number",
+      unitType: "execute-task",
+      unitId: "M001/S01/T01",
+      status: "completed",
+      failureClass: "none",
+      phaseResults: [],
+      startedAt: new Date().toISOString(),
+      finishedAt: new Date().toISOString(),
+    });
+  }, /Invalid UOK turn result/);
+
+  // Cleanup must run in finally — token released, no leaked state.
+  assert.equal(hasActiveWriterToken(basePath, "turn-throw"), false);
+});
+
+test("uok turn observer falls back to cached phaseResults when result.phaseResults is missing", (t) => {
+  const basePath = mkdtempSync(join(tmpdir(), "gsd-uok-loop-writer-missing-"));
+  resetWriterTokensForTests();
+  t.after(() => {
+    resetWriterTokensForTests();
+    rmSync(basePath, { recursive: true, force: true });
+  });
+
+  const observer = createTurnObserver({
+    basePath,
+    gitAction: "status-only",
+    gitPush: false,
+    enableAudit: false,
+    enableGitops: false,
+  });
+
+  observer.onTurnStart({
+    basePath,
+    traceId: "trace-missing",
+    turnId: "turn-missing",
+    iteration: 1,
+    unitType: "execute-task",
+    unitId: "M001/S01/T01",
+    startedAt: new Date().toISOString(),
+  });
+
+  // Without the Array.isArray guard, accessing result.phaseResults.length on a
+  // payload where phaseResults is undefined would throw TypeError before
+  // validateTurnResult could surface a structured error. The guard must defer
+  // to the cached phaseResults fallback so the turn completes cleanly.
+  assert.doesNotThrow(() => {
+    observer.onTurnResult({
+      traceId: "trace-missing",
+      turnId: "turn-missing",
+      iteration: 1,
+      unitType: "execute-task",
+      unitId: "M001/S01/T01",
+      status: "completed",
+      failureClass: "none",
+      // @ts-expect-error intentionally missing for test
+      phaseResults: undefined,
+      startedAt: new Date().toISOString(),
+      finishedAt: new Date().toISOString(),
+    });
+  });
+
+  assert.equal(hasActiveWriterToken(basePath, "turn-missing"), false);
+});

package/src/resources/extensions/gsd/uok/audit.ts

@@ -1,3 +1,5 @@
+// GSD2 UOK Audit Events and DB-First Projection Writes
+
 import { appendFileSync, closeSync, existsSync, mkdirSync, openSync } from "node:fs";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
@@ -6,7 +8,7 @@ import { isStaleWrite } from "../auto/turn-epoch.js";
 import { withFileLockSync } from "../file-lock.js";
 import { gsdRoot } from "../paths.js";
 import { isDbAvailable, insertAuditEvent } from "../gsd-db.js";
-import type { AuditEventEnvelope } from "./contracts.js";
+import { CURRENT_UOK_CONTRACT_VERSION, validateAuditEvent, type AuditEventEnvelope } from "./contracts.js";
 
 function auditLogPath(basePath: string): string {
   return join(gsdRoot(basePath), "audit", "events.jsonl");
@@ -25,6 +27,7 @@ export function buildAuditEnvelope(args: {
   payload?: Record<string, unknown>;
 }): AuditEventEnvelope {
   return {
+    version: CURRENT_UOK_CONTRACT_VERSION,
     eventId: randomUUID(),
     traceId: args.traceId,
     turnId: args.turnId,
@@ -39,6 +42,26 @@ export function buildAuditEnvelope(args: {
 export function emitUokAuditEvent(basePath: string, event: AuditEventEnvelope): void {
   // Drop writes from a turn superseded by timeout recovery / cancellation.
   if (isStaleWrite("uok-audit")) return;
+  const validation = validateAuditEvent(event);
+  if (!validation.ok) {
+    throw new Error(`Invalid UOK audit event: ${validation.issues.map((issue) => `${issue.path}: ${issue.message}`).join("; ")}`);
+  }
+  const canonical = validation.value;
+
+  if (isDbAvailable()) {
+    try {
+      insertAuditEvent({
+        ...canonical,
+        payload: {
+          ...canonical.payload,
+          contractVersion: canonical.version ?? CURRENT_UOK_CONTRACT_VERSION,
+        },
+      });
+    } catch (err) {
+      throw new Error(`DB authoritative audit write failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
   try {
     ensureAuditDir(basePath);
     const path = auditLogPath(basePath);
@@ -52,18 +75,11 @@ export function emitUokAuditEvent(basePath: string, event: AuditEventEnvelope):
     withFileLockSync(
       path,
       () => {
-        appendFileSync(path, `${JSON.stringify(event)}\n`, "utf-8");
+        appendFileSync(path, `${JSON.stringify(canonical)}\n`, "utf-8");
       },
       { onLocked: "skip" },
     );
   } catch {
     // Best-effort: audit writes must never break orchestration.
   }
-
-  if (!isDbAvailable()) return;
-  try {
-    insertAuditEvent(event);
-  } catch {
-    // Projection failures are non-fatal while legacy readers are still active.
-  }
 }

package/src/resources/extensions/gsd/uok/contracts.ts

@@ -1,3 +1,9 @@
+// GSD2 UOK Contract Types and Versioning
+
+export const CURRENT_UOK_CONTRACT_VERSION = "1" as const;
+
+export type UokContractVersion = "0" | typeof CURRENT_UOK_CONTRACT_VERSION;
+
 export type FailureClass =
   | "none"
   | "policy"
@@ -77,6 +83,7 @@ export interface TurnCloseoutRecord {
 }
 
 export interface TurnResult {
+  version?: UokContractVersion;
   traceId: string;
   turnId: string;
   iteration: number;
@@ -109,6 +116,7 @@ export interface DispatchExplanation {
 }
 
 export interface UokDispatchEnvelope {
+  version?: UokContractVersion;
   action: "dispatch" | "stop" | "skip";
   nodeKind?: UokNodeKind;
   unitType?: string;
@@ -130,6 +138,7 @@ export interface UokDispatchEnvelope {
 }
 
 export interface AuditEventEnvelope {
+  version?: UokContractVersion;
   eventId: string;
   traceId: string;
   turnId?: string;
@@ -199,3 +208,99 @@ export interface UokTurnObserver {
   ): void;
   onTurnResult(result: TurnResult): void;
 }
+
+export interface ContractValidationIssue {
+  path: string;
+  message: string;
+}
+
+export interface ContractValidationResult<T> {
+  ok: boolean;
+  value: T;
+  issues: ContractValidationIssue[];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function normalizeVersion(value: unknown): UokContractVersion {
+  return value === CURRENT_UOK_CONTRACT_VERSION ? CURRENT_UOK_CONTRACT_VERSION : "0";
+}
+
+function requireString(
+  value: Record<string, unknown>,
+  key: string,
+  issues: ContractValidationIssue[],
+): void {
+  if (typeof value[key] !== "string" || value[key] === "") {
+    issues.push({ path: key, message: `${key} must be a non-empty string` });
+  }
+}
+
+function requireRecord(
+  value: Record<string, unknown>,
+  key: string,
+  issues: ContractValidationIssue[],
+): void {
+  if (!isRecord(value[key])) {
+    issues.push({ path: key, message: `${key} must be an object` });
+  }
+}
+
+export function normalizeTurnResult(value: TurnResult): TurnResult {
+  return { ...value, version: normalizeVersion(value.version) };
+}
+
+export function normalizeDispatchEnvelope(value: UokDispatchEnvelope): UokDispatchEnvelope {
+  return { ...value, version: normalizeVersion(value.version) };
+}
+
+export function normalizeAuditEvent(value: AuditEventEnvelope): AuditEventEnvelope {
+  return { ...value, version: normalizeVersion(value.version) };
+}
+
+export function validateTurnResult(value: TurnResult): ContractValidationResult<TurnResult> {
+  const normalized = normalizeTurnResult(value);
+  const record = normalized as unknown as Record<string, unknown>;
+  const issues: ContractValidationIssue[] = [];
+  requireString(record, "traceId", issues);
+  requireString(record, "turnId", issues);
+  if (!Number.isInteger(record.iteration)) {
+    issues.push({ path: "iteration", message: "iteration must be an integer" });
+  }
+  requireString(record, "status", issues);
+  requireString(record, "failureClass", issues);
+  if (!Array.isArray(record.phaseResults)) {
+    issues.push({ path: "phaseResults", message: "phaseResults must be an array" });
+  }
+  requireString(record, "startedAt", issues);
+  requireString(record, "finishedAt", issues);
+  return { ok: issues.length === 0, value: normalized, issues };
+}
+
+export function validateDispatchEnvelope(value: UokDispatchEnvelope): ContractValidationResult<UokDispatchEnvelope> {
+  const normalized = normalizeDispatchEnvelope(value);
+  const record = normalized as unknown as Record<string, unknown>;
+  const issues: ContractValidationIssue[] = [];
+  requireString(record, "action", issues);
+  requireRecord(record, "reason", issues);
+  if (isRecord(record.reason)) {
+    requireString(record.reason, "reasonCode", issues);
+    requireString(record.reason, "summary", issues);
+  }
+  return { ok: issues.length === 0, value: normalized, issues };
+}
+
+export function validateAuditEvent(value: AuditEventEnvelope): ContractValidationResult<AuditEventEnvelope> {
+  const normalized = normalizeAuditEvent(value);
+  const record = normalized as unknown as Record<string, unknown>;
+  const issues: ContractValidationIssue[] = [];
+  requireString(record, "eventId", issues);
+  requireString(record, "traceId", issues);
+  requireString(record, "category", issues);
+  requireString(record, "type", issues);
+  requireString(record, "ts", issues);
+  requireRecord(record, "payload", issues);
+  return { ok: issues.length === 0, value: normalized, issues };
+}

package/src/resources/extensions/gsd/uok/dispatch-envelope.ts

@@ -1,3 +1,5 @@
+// GSD2 UOK Dispatch Envelope Builder
+
 import type {
   DispatchExplanation,
   DispatchReasonCode,
@@ -5,6 +7,7 @@ import type {
   UokDispatchEnvelope,
   UokGraphNode,
 } from "./contracts.js";
+import { CURRENT_UOK_CONTRACT_VERSION } from "./contracts.js";
 
 export interface BuildDispatchEnvelopeInput {
   action: UokDispatchEnvelope["action"];
@@ -22,6 +25,7 @@ export interface BuildDispatchEnvelopeInput {
 
 export function buildDispatchEnvelope(input: BuildDispatchEnvelopeInput): UokDispatchEnvelope {
   return {
+    version: CURRENT_UOK_CONTRACT_VERSION,
     action: input.action,
     nodeKind: input.node?.kind,
     unitType: input.unitType,

package/src/resources/extensions/gsd/uok/loop-adapter.ts

@@ -1,9 +1,12 @@
+// GSD2 UOK Turn Observer and DB-Backed Lifecycle Emission
+
 import type {
   TurnCloseoutRecord,
   TurnContract,
   TurnResult,
   UokTurnObserver,
 } from "./contracts.js";
+import { CURRENT_UOK_CONTRACT_VERSION, validateTurnResult } from "./contracts.js";
 import { buildAuditEnvelope, emitUokAuditEvent } from "./audit.js";
 import { writeTurnCloseoutGitRecord, writeTurnGitTransaction } from "./gitops.js";
 import { acquireWriterToken, nextWriteRecord, releaseWriterToken } from "./writer.js";
@@ -142,56 +145,68 @@ export function createTurnObserver(options: CreateTurnObserverOptions): UokTurnO
     },
 
     onTurnResult(result): void {
-      const merged: TurnResult = {
-        ...result,
-        phaseResults: result.phaseResults.length > 0 ? result.phaseResults : [...phaseResults],
+      const cleanup = (): void => {
+        if (writerToken) {
+          releaseWriterToken(options.basePath, writerToken);
+        }
+        writerToken = null;
+        current = null;
+        phaseResults.length = 0;
       };
 
-      if (options.enableAudit) {
-        emitUokAuditEvent(
-          options.basePath,
-          buildAuditEnvelope({
-            traceId: merged.traceId,
-            turnId: merged.turnId,
-            category: "orchestration",
-            type: "turn-result",
-            payload: nextSequenceMetadata("audit", "append", {
-              unitType: merged.unitType,
-              unitId: merged.unitId,
-              status: merged.status,
-              failureClass: merged.failureClass,
-              error: merged.error,
-              phaseCount: merged.phaseResults.length,
-            }),
-          }),
-        );
-      }
-
-      if (options.enableGitops) {
-        const closeout: TurnCloseoutRecord = merged.closeout ?? {
-          traceId: merged.traceId,
-          turnId: merged.turnId,
-          unitType: merged.unitType,
-          unitId: merged.unitId,
-          status: merged.status,
-          failureClass: merged.failureClass,
-          gitAction: options.gitAction,
-          gitPushed: options.gitPush,
-          finishedAt: merged.finishedAt,
+      try {
+        const merged: TurnResult = {
+          ...result,
+          version: CURRENT_UOK_CONTRACT_VERSION,
+          phaseResults: Array.isArray(result.phaseResults) && result.phaseResults.length > 0 ? result.phaseResults : [...phaseResults],
         };
-        writeTurnCloseoutGitRecord(
-          options.basePath,
-          closeout,
-          nextSequenceMetadata("gitops", "update", { action: "record" }),
-        );
-      }
+        const validation = validateTurnResult(merged);
+        if (!validation.ok) {
+          throw new Error(`Invalid UOK turn result: ${validation.issues.map((issue) => `${issue.path}: ${issue.message}`).join("; ")}`);
+        }
 
-      if (writerToken) {
-        releaseWriterToken(options.basePath, writerToken);
+        if (options.enableAudit) {
+          emitUokAuditEvent(
+            options.basePath,
+            buildAuditEnvelope({
+              traceId: validation.value.traceId,
+              turnId: validation.value.turnId,
+              category: "orchestration",
+              type: "turn-result",
+              payload: nextSequenceMetadata("audit", "append", {
+                contractVersion: validation.value.version,
+                unitType: validation.value.unitType,
+                unitId: validation.value.unitId,
+                status: validation.value.status,
+                failureClass: validation.value.failureClass,
+                error: validation.value.error,
+                phaseCount: validation.value.phaseResults.length,
+              }),
+            }),
+          );
+        }
+
+        if (options.enableGitops) {
+          const closeout: TurnCloseoutRecord = merged.closeout ?? {
+            traceId: merged.traceId,
+            turnId: merged.turnId,
+            unitType: merged.unitType,
+            unitId: merged.unitId,
+            status: merged.status,
+            failureClass: merged.failureClass,
+            gitAction: options.gitAction,
+            gitPushed: options.gitPush,
+            finishedAt: merged.finishedAt,
+          };
+          writeTurnCloseoutGitRecord(
+            options.basePath,
+            closeout,
+            nextSequenceMetadata("gitops", "update", { action: "record" }),
+          );
+        }
+      } finally {
+        cleanup();
       }
-      writerToken = null;
-      current = null;
-      phaseResults.length = 0;
     },
   };
 }