@openrig/cli 0.1.12 → 0.3.0

package/daemon/dist/domain/workflow-runtime.js

@@ -0,0 +1,150 @@
+// PL-004 Phase D: workflow runtime facade.
+//
+// Coordinates spec cache + validator + instance store + projector +
+// trail log into the four high-level operations:
+//   - validate(specPath)
+//   - instantiate(specPath, rootObjective, createdBySession)
+//   - project(...)  (delegates to projector)
+//   - continue(instanceId)  (idempotent advance; v1 = read-only inspector)
+//
+// Pattern mirrors Phase B's ProjectClassifier facade shape.
+import { WorkflowInstanceStore, WorkflowInstanceError, } from "./workflow-instance-store.js";
+import { WorkflowProjector, WorkflowProjectorError, } from "./workflow-projector.js";
+import { WorkflowSpecCache, WorkflowSpecError } from "./workflow-spec-cache.js";
+import { WorkflowStepTrailLog } from "./workflow-step-trail-log.js";
+import { WorkflowValidator, } from "./workflow-validator.js";
+export class WorkflowRuntime {
+    specCache;
+    instanceStore;
+    trailLog;
+    validator;
+    projector;
+    db;
+    eventBus;
+    queueRepo;
+    now;
+    constructor(deps) {
+        this.db = deps.db;
+        this.eventBus = deps.eventBus;
+        this.queueRepo = deps.queueRepo;
+        this.now = deps.now ?? (() => new Date());
+        this.specCache = new WorkflowSpecCache(this.db, this.now);
+        this.instanceStore = new WorkflowInstanceStore(this.db, this.now);
+        this.trailLog = new WorkflowStepTrailLog(this.db);
+        this.validator = new WorkflowValidator();
+        this.projector = new WorkflowProjector(this.db, this.eventBus, this.queueRepo, this.instanceStore, this.trailLog, this.specCache, this.now);
+    }
+    validate(specPath, seatLivenessCheck) {
+        const specRow = this.specCache.readThrough(specPath);
+        return this.validator.validate(specRow.spec, seatLivenessCheck);
+    }
+    /**
+     * Create a workflow instance + first-step qitem. The entry qitem is
+     * created in the same transaction as the instance row; subscribers
+     * see the workflow.instantiated + queue.created events together.
+     */
+    async instantiate(input) {
+        const specRow = this.specCache.readThrough(input.specPath);
+        const validation = this.validator.validate(specRow.spec);
+        if (!validation.ok) {
+            throw new WorkflowProjectorError("spec_invalid", `cannot instantiate: spec ${specRow.name}@${specRow.version} has ${validation.issues.filter((i) => i.severity === "error").length} validation error(s); run validate to inspect`, { specPath: input.specPath, issues: validation.issues });
+        }
+        const entryStep = specRow.spec.steps[0];
+        if (!entryStep) {
+            throw new WorkflowProjectorError("spec_no_steps", `cannot instantiate: spec ${specRow.name}@${specRow.version} has no steps[]`, { specPath: input.specPath });
+        }
+        const entryRole = specRow.spec.roles?.[entryStep.actor_role];
+        const entryOwner = input.entryOwnerSession ?? entryRole?.preferred_targets?.[0] ?? null;
+        if (!entryOwner) {
+            throw new WorkflowProjectorError("entry_owner_unresolved", `cannot instantiate: entry step "${entryStep.id}" (role "${entryStep.actor_role}") has no preferred_targets and no entryOwnerSession was supplied`, { specPath: input.specPath, entryStepId: entryStep.id, entryRole: entryStep.actor_role });
+        }
+        const createdAt = this.now().toISOString();
+        let entryQitemId;
+        let entryQitemDestinationSession;
+        let entryQitemNudge;
+        let instanceId;
+        const persistedEvents = [];
+        const txn = this.db.transaction(() => {
+            const instance = this.instanceStore.create({
+                workflowName: specRow.name,
+                workflowVersion: specRow.version,
+                createdBySession: input.createdBySession,
+                initialFrontier: [],
+                // R2 fix: set durable current_step_id at instantiate so the
+                // projector resolves the correct step on the first project()
+                // call without any trail-based inference.
+                currentStepId: entryStep.id,
+            });
+            instanceId = instance.instanceId;
+            // Create entry qitem in the same txn.
+            const created = this.queueRepo.createWithinTransaction({
+                sourceSession: input.createdBySession,
+                destinationSession: entryOwner,
+                body: workflowInstantiateBody({
+                    spec: specRow.spec,
+                    instanceId: instance.instanceId,
+                    entryStep,
+                    rootObjective: input.rootObjective,
+                }),
+                priority: "routine",
+                tier: "mode2",
+                tags: ["workflow", "entry", `workflow:${specRow.name}`, `instance:${instance.instanceId}`],
+            });
+            entryQitemId = created.qitemId;
+            entryQitemDestinationSession = created.destinationSession;
+            entryQitemNudge = created.nudge;
+            persistedEvents.push(created.persistedEvent);
+            this.instanceStore.updateFrontier(instance.instanceId, [created.qitemId], "active");
+            persistedEvents.push(this.eventBus.persistWithinTransaction({
+                type: "workflow.instantiated",
+                instanceId: instance.instanceId,
+                workflowName: specRow.name,
+                workflowVersion: specRow.version,
+                createdBy: input.createdBySession,
+            }));
+        });
+        txn();
+        for (const e of persistedEvents)
+            this.eventBus.notifySubscribers(e);
+        if (entryQitemId && entryQitemDestinationSession) {
+            await this.queueRepo.maybeNudge(entryQitemId, entryQitemDestinationSession, entryQitemNudge);
+        }
+        const finalInstance = this.instanceStore.getByIdOrThrow(instanceId);
+        return {
+            instance: finalInstance,
+            spec: specRow,
+            entryQitemId: entryQitemId,
+            entryOwnerSession: entryOwner,
+        };
+    }
+    async project(input) {
+        return this.projector.project(input);
+    }
+    /**
+     * Continue: idempotent inspector for the current frontier of an
+     * instance. v1 is read-only — returns the current state. POC's
+     * mechanical advance is folded into project() for v1; continue() is
+     * the audit/inspect entrypoint.
+     */
+    continue(instanceId) {
+        const instance = this.instanceStore.getByIdOrThrow(instanceId);
+        const trail = this.trailLog.listForInstance(instanceId);
+        return { instance, trail };
+    }
+}
+function workflowInstantiateBody(input) {
+    const lines = [
+        `### Workflow entry: ${input.spec.id}@${input.spec.version} step ${input.entryStep.id}`,
+        "",
+        `Workflow instance: ${input.instanceId}`,
+        `Entry step: ${input.entryStep.id} (${input.entryStep.actor_role})`,
+        "",
+        `Root objective: ${input.rootObjective}`,
+    ];
+    if (input.entryStep.objective) {
+        lines.push("", `Step objective: ${input.entryStep.objective}`);
+    }
+    return lines.join("\n");
+}
+export { WorkflowInstanceError, WorkflowProjectorError, WorkflowSpecError, };
+//# sourceMappingURL=workflow-runtime.js.map

package/daemon/dist/domain/workflow-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-runtime.js","sourceRoot":"","sources":["../../src/domain/workflow-runtime.ts"],"names":[],"mappings":"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"}

package/daemon/dist/domain/workflow-spec-cache.d.ts

@@ -0,0 +1,42 @@
+import type Database from "better-sqlite3";
+import type { WorkflowSpec, WorkflowSpecRow } from "./workflow-types.js";
+export declare class WorkflowSpecError extends Error {
+    readonly code: string;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(code: string, message: string, details?: Record<string, unknown> | undefined);
+}
+/**
+ * Parse a workflow spec from raw YAML content. The POC fixture shape
+ * wraps everything under a top-level `workflow:` key:
+ *
+ *   workflow:
+ *     id: ...
+ *     version: ...
+ *     roles: { ... }
+ *     steps: [ ... ]
+ *
+ * Returns the parsed spec or throws WorkflowSpecError on malformed
+ * YAML / missing required fields.
+ */
+export declare function parseWorkflowSpec(rawYaml: string, sourcePath: string): WorkflowSpec;
+export declare class WorkflowSpecCache {
+    private readonly db;
+    private readonly now;
+    constructor(db: Database.Database, now?: () => Date);
+    /**
+     * Read a workflow spec from disk through the cache. Returns the
+     * cached row (re-caching if source_hash differs OR if the spec was
+     * not previously cached).
+     */
+    readThrough(sourcePath: string): WorkflowSpecRow;
+    getByNameVersion(name: string, version: string): WorkflowSpecRow | null;
+    /**
+     * Lists every cached spec, ordered by name then version. Used by the
+     * `GET /api/workflow/specs` endpoint. Cheap —
+     * the workflow_specs table is bounded by the number of operator-
+     * authored + built-in starter specs (single-host MVP).
+     */
+    listAll(): WorkflowSpecRow[];
+    getByIdOrThrow(specId: string): WorkflowSpecRow;
+}
+//# sourceMappingURL=workflow-spec-cache.d.ts.map

package/daemon/dist/domain/workflow-spec-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-spec-cache.d.ts","sourceRoot":"","sources":["../../src/domain/workflow-spec-cache.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAG3C,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAgBzE,qBAAa,iBAAkB,SAAQ,KAAK;aAExB,IAAI,EAAE,MAAM;aAEZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBAFjC,IAAI,EAAE,MAAM,EAC5B,OAAO,EAAE,MAAM,EACC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAAA;CAKpD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,YAAY,CAuEnF;AAED,qBAAa,iBAAiB;IAE1B,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,GAAG;gBADH,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,GAAG,GAAE,MAAM,IAAuB;IAGrD;;;;OAIG;IACH,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,eAAe;IAkGhD,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI;IAOvE;;;;;OAKG;IACH,OAAO,IAAI,eAAe,EAAE;IAO5B,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe;CAahD"}

package/daemon/dist/domain/workflow-spec-cache.js

@@ -0,0 +1,218 @@
+// PL-004 Phase D: workflow spec cache (read-through from markdown/YAML
+// to SQLite workflow_specs).
+//
+// Workflow specs are workspace-surface (markdown/YAML files on disk;
+// human-authored). Daemon reads them lazily and caches in
+// workflow_specs for fast lookup. Cache invalidation: source_hash on
+// the spec file content; on next read, if the hash differs, re-cache.
+//
+// Workspace-surface reconciliation contract (per PRD § Workspace-
+// surface reconciliation): valid operator edits to spec files win
+// at next read; the cache is never the source of truth.
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { ulid } from "ulid";
+import { parse as parseYaml } from "yaml";
+export class WorkflowSpecError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = "WorkflowSpecError";
+    }
+}
+/**
+ * Parse a workflow spec from raw YAML content. The POC fixture shape
+ * wraps everything under a top-level `workflow:` key:
+ *
+ *   workflow:
+ *     id: ...
+ *     version: ...
+ *     roles: { ... }
+ *     steps: [ ... ]
+ *
+ * Returns the parsed spec or throws WorkflowSpecError on malformed
+ * YAML / missing required fields.
+ */
+export function parseWorkflowSpec(rawYaml, sourcePath) {
+    let parsed;
+    try {
+        parsed = parseYaml(rawYaml);
+    }
+    catch (err) {
+        throw new WorkflowSpecError("spec_yaml_invalid", `workflow spec at ${sourcePath} could not be parsed as YAML: ${err instanceof Error ? err.message : err}`, { sourcePath });
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new WorkflowSpecError("spec_shape_invalid", `workflow spec at ${sourcePath} must be a YAML mapping with a top-level 'workflow:' key`, { sourcePath });
+    }
+    const root = parsed;
+    const wf = root.workflow;
+    if (!wf || typeof wf !== "object" || Array.isArray(wf)) {
+        throw new WorkflowSpecError("spec_shape_invalid", `workflow spec at ${sourcePath} is missing the top-level 'workflow:' key`, { sourcePath });
+    }
+    if (typeof wf.id !== "string" || wf.id.length === 0) {
+        throw new WorkflowSpecError("spec_field_missing", `workflow spec at ${sourcePath} is missing required field workflow.id`, { sourcePath, field: "workflow.id" });
+    }
+    if (wf.version === undefined || wf.version === null) {
+        throw new WorkflowSpecError("spec_field_missing", `workflow spec at ${sourcePath} is missing required field workflow.version`, { sourcePath, field: "workflow.version" });
+    }
+    if (!Array.isArray(wf.steps) || wf.steps.length === 0) {
+        throw new WorkflowSpecError("spec_field_missing", `workflow spec at ${sourcePath} requires at least one step in workflow.steps[]`, { sourcePath, field: "workflow.steps" });
+    }
+    if (!wf.roles || typeof wf.roles !== "object" || Array.isArray(wf.roles)) {
+        throw new WorkflowSpecError("spec_field_missing", `workflow spec at ${sourcePath} requires a workflow.roles mapping`, { sourcePath, field: "workflow.roles" });
+    }
+    return {
+        id: wf.id,
+        version: String(wf.version),
+        objective: typeof wf.objective === "string" ? wf.objective : undefined,
+        target: wf.target,
+        entry: wf.entry,
+        roles: wf.roles,
+        steps: wf.steps,
+        invariants: wf.invariants,
+        closure: wf.closure,
+        loop_guards: wf.loop_guards,
+        coordination_terminal_turn_rule: typeof wf.coordination_terminal_turn_rule === "string"
+            ? wf.coordination_terminal_turn_rule
+            : undefined,
+    };
+}
+export class WorkflowSpecCache {
+    db;
+    now;
+    constructor(db, now = () => new Date()) {
+        this.db = db;
+        this.now = now;
+    }
+    /**
+     * Read a workflow spec from disk through the cache. Returns the
+     * cached row (re-caching if source_hash differs OR if the spec was
+     * not previously cached).
+     */
+    readThrough(sourcePath) {
+        if (!existsSync(sourcePath)) {
+            throw new WorkflowSpecError("spec_file_missing", `workflow spec file not found at ${sourcePath}`, { sourcePath });
+        }
+        const raw = readFileSync(sourcePath, "utf-8");
+        const sourceHash = createHash("sha256").update(raw).digest("hex");
+        const spec = parseWorkflowSpec(raw, sourcePath);
+        const existing = this.db
+            .prepare(`SELECT * FROM workflow_specs WHERE name = ? AND version = ?`)
+            .get(spec.id, spec.version);
+        if (existing && existing.source_hash === sourceHash) {
+            // readThrough is file-authoritative: return the freshly parsed
+            // file spec so validation sees non-column metadata such as
+            // workflow.entry and workflow.invariants.
+            return rowToWorkflowSpec(existing, spec);
+        }
+        const cachedAt = this.now().toISOString();
+        const purpose = spec.objective ?? null;
+        const targetRig = spec.target?.rig ?? null;
+        const rolesJson = JSON.stringify(spec.roles);
+        const stepsJson = JSON.stringify(spec.steps);
+        const coordinationTerminalTurnRule = spec.coordination_terminal_turn_rule ?? "hot_potato";
+        if (existing) {
+            // Update in place (same name+version, content changed).
+            this.db
+                .prepare(`UPDATE workflow_specs SET
+             purpose = ?, target_rig = ?, roles_json = ?, steps_json = ?,
+             coordination_terminal_turn_rule = ?, source_path = ?,
+             source_hash = ?, cached_at = ?
+           WHERE spec_id = ?`)
+                .run(purpose, targetRig, rolesJson, stepsJson, coordinationTerminalTurnRule, sourcePath, sourceHash, cachedAt, existing.spec_id);
+            return rowToWorkflowSpec({
+                ...existing,
+                purpose,
+                target_rig: targetRig,
+                roles_json: rolesJson,
+                steps_json: stepsJson,
+                coordination_terminal_turn_rule: coordinationTerminalTurnRule,
+                source_path: sourcePath,
+                source_hash: sourceHash,
+                cached_at: cachedAt,
+            }, spec);
+        }
+        const specId = ulid();
+        this.db
+            .prepare(`INSERT INTO workflow_specs (
+           spec_id, name, version, purpose, target_rig,
+           roles_json, steps_json, coordination_terminal_turn_rule,
+           source_path, source_hash, cached_at
+         ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(specId, spec.id, spec.version, purpose, targetRig, rolesJson, stepsJson, coordinationTerminalTurnRule, sourcePath, sourceHash, cachedAt);
+        return rowToWorkflowSpec({
+            spec_id: specId,
+            name: spec.id,
+            version: spec.version,
+            purpose,
+            target_rig: targetRig,
+            roles_json: rolesJson,
+            steps_json: stepsJson,
+            coordination_terminal_turn_rule: coordinationTerminalTurnRule,
+            source_path: sourcePath,
+            source_hash: sourceHash,
+            cached_at: cachedAt,
+        }, spec);
+    }
+    getByNameVersion(name, version) {
+        const row = this.db
+            .prepare(`SELECT * FROM workflow_specs WHERE name = ? AND version = ?`)
+            .get(name, version);
+        return row ? rowToWorkflowSpec(row) : null;
+    }
+    /**
+     * Lists every cached spec, ordered by name then version. Used by the
+     * `GET /api/workflow/specs` endpoint. Cheap —
+     * the workflow_specs table is bounded by the number of operator-
+     * authored + built-in starter specs (single-host MVP).
+     */
+    listAll() {
+        const rows = this.db
+            .prepare(`SELECT * FROM workflow_specs ORDER BY name, version`)
+            .all();
+        return rows.map((row) => rowToWorkflowSpec(row));
+    }
+    getByIdOrThrow(specId) {
+        const row = this.db
+            .prepare(`SELECT * FROM workflow_specs WHERE spec_id = ?`)
+            .get(specId);
+        if (!row) {
+            throw new WorkflowSpecError("spec_not_found", `workflow spec ${specId} not found in cache`, { specId });
+        }
+        return rowToWorkflowSpec(row);
+    }
+}
+function rowToWorkflowSpec(row, parsedSpec) {
+    const roles = JSON.parse(row.roles_json);
+    const steps = JSON.parse(row.steps_json);
+    const spec = parsedSpec
+        ? {
+            ...parsedSpec,
+            coordination_terminal_turn_rule: parsedSpec.coordination_terminal_turn_rule ?? row.coordination_terminal_turn_rule,
+        }
+        : {
+            id: row.name,
+            version: row.version,
+            objective: row.purpose ?? undefined,
+            target: row.target_rig ? { rig: row.target_rig } : undefined,
+            roles,
+            steps,
+            coordination_terminal_turn_rule: row.coordination_terminal_turn_rule,
+        };
+    return {
+        specId: row.spec_id,
+        name: row.name,
+        version: row.version,
+        purpose: row.purpose,
+        targetRig: row.target_rig,
+        spec,
+        coordinationTerminalTurnRule: row.coordination_terminal_turn_rule,
+        sourcePath: row.source_path,
+        sourceHash: row.source_hash,
+        cachedAt: row.cached_at,
+    };
+}
+//# sourceMappingURL=workflow-spec-cache.js.map

package/daemon/dist/domain/workflow-spec-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-spec-cache.js","sourceRoot":"","sources":["../../src/domain/workflow-spec-cache.ts"],"names":[],"mappings":"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"}

package/daemon/dist/domain/workflow-step-trail-log.d.ts

@@ -0,0 +1,27 @@
+import type Database from "better-sqlite3";
+import type { WorkflowExitKind, WorkflowStepTrailEntry } from "./workflow-types.js";
+export interface WorkflowStepTrailRecordInput {
+    instanceId: string;
+    stepId: string;
+    stepRole: string;
+    closedAt: string;
+    closureReason: WorkflowExitKind;
+    closureEvidence?: Record<string, unknown> | null;
+    actorSession: string;
+    /** null for terminal closures (`done`, `failed`, `waiting`). */
+    nextQitemId?: string | null;
+    priorQitemId: string;
+}
+export declare class WorkflowStepTrailLog {
+    private readonly db;
+    constructor(db: Database.Database);
+    /**
+     * Append a step trail entry. Returns the persisted entry. Designed
+     * to compose inside an outer caller-managed transaction (used by
+     * workflow-projector for the transactional-scribe contract).
+     */
+    record(input: WorkflowStepTrailRecordInput): WorkflowStepTrailEntry;
+    listForInstance(instanceId: string, limit?: number): WorkflowStepTrailEntry[];
+    countForInstance(instanceId: string): number;
+}
+//# sourceMappingURL=workflow-step-trail-log.d.ts.map

package/daemon/dist/domain/workflow-step-trail-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-step-trail-log.d.ts","sourceRoot":"","sources":["../../src/domain/workflow-step-trail-log.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAE3C,OAAO,KAAK,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAEpF,MAAM,WAAW,4BAA4B;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,gBAAgB,CAAC;IAChC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACjD,YAAY,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,YAAY,EAAE,MAAM,CAAC;CACtB;AAeD,qBAAa,oBAAoB;IACnB,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,QAAQ,CAAC,QAAQ;IAElD;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,4BAA4B,GAAG,sBAAsB;IAoCnE,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,sBAAsB,EAAE;IAUzE,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;CAM7C"}

package/daemon/dist/domain/workflow-step-trail-log.js

@@ -0,0 +1,73 @@
+// PL-004 Phase D: workflow step trail log (append-only).
+//
+// Owns inserts into workflow_step_trails. Append-only at the API
+// surface: only `record()` is exposed. UPDATE/DELETE/remove are not
+// methods — direct SQL could mutate but is a contract violation
+// enforced at this domain boundary (per PRD § L4 Workflow Runtime).
+//
+// Pattern mirrors Phase C's WatchdogHistoryLog and Phase A's
+// QueueTransitionLog.
+import { ulid } from "ulid";
+export class WorkflowStepTrailLog {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Append a step trail entry. Returns the persisted entry. Designed
+     * to compose inside an outer caller-managed transaction (used by
+     * workflow-projector for the transactional-scribe contract).
+     */
+    record(input) {
+        const trailId = ulid();
+        this.db
+            .prepare(`INSERT INTO workflow_step_trails (
+           trail_id, instance_id, step_id, step_role, closed_at,
+           closure_reason, closure_evidence_json, actor_session,
+           next_qitem_id, prior_qitem_id
+         ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(trailId, input.instanceId, input.stepId, input.stepRole, input.closedAt, input.closureReason, input.closureEvidence ? JSON.stringify(input.closureEvidence) : null, input.actorSession, input.nextQitemId ?? null, input.priorQitemId);
+        return {
+            trailId,
+            instanceId: input.instanceId,
+            stepId: input.stepId,
+            stepRole: input.stepRole,
+            closedAt: input.closedAt,
+            closureReason: input.closureReason,
+            closureEvidence: input.closureEvidence ?? null,
+            actorSession: input.actorSession,
+            nextQitemId: input.nextQitemId ?? null,
+            priorQitemId: input.priorQitemId,
+        };
+    }
+    listForInstance(instanceId, limit = 50) {
+        const rows = this.db
+            .prepare(`SELECT * FROM workflow_step_trails WHERE instance_id = ?
+         ORDER BY closed_at DESC, rowid DESC LIMIT ?`)
+            .all(instanceId, limit);
+        return rows.map(rowToEntry);
+    }
+    countForInstance(instanceId) {
+        const row = this.db
+            .prepare(`SELECT COUNT(*) AS n FROM workflow_step_trails WHERE instance_id = ?`)
+            .get(instanceId);
+        return row.n;
+    }
+}
+function rowToEntry(row) {
+    return {
+        trailId: row.trail_id,
+        instanceId: row.instance_id,
+        stepId: row.step_id,
+        stepRole: row.step_role,
+        closedAt: row.closed_at,
+        closureReason: row.closure_reason,
+        closureEvidence: row.closure_evidence_json
+            ? JSON.parse(row.closure_evidence_json)
+            : null,
+        actorSession: row.actor_session,
+        nextQitemId: row.next_qitem_id,
+        priorQitemId: row.prior_qitem_id,
+    };
+}
+//# sourceMappingURL=workflow-step-trail-log.js.map

package/daemon/dist/domain/workflow-step-trail-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-step-trail-log.js","sourceRoot":"","sources":["../../src/domain/workflow-step-trail-log.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,EAAE;AACF,iEAAiE;AACjE,oEAAoE;AACpE,gEAAgE;AAChE,oEAAoE;AACpE,EAAE;AACF,6DAA6D;AAC7D,sBAAsB;AAGtB,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AA6B5B,MAAM,OAAO,oBAAoB;IACF;IAA7B,YAA6B,EAAqB;QAArB,OAAE,GAAF,EAAE,CAAmB;IAAG,CAAC;IAEtD;;;;OAIG;IACH,MAAM,CAAC,KAAmC;QACxC,MAAM,OAAO,GAAG,IAAI,EAAE,CAAC;QACvB,IAAI,CAAC,EAAE;aACJ,OAAO,CACN;;;;iDAIyC,CAC1C;aACA,GAAG,CACF,OAAO,EACP,KAAK,CAAC,UAAU,EAChB,KAAK,CAAC,MAAM,EACZ,KAAK,CAAC,QAAQ,EACd,KAAK,CAAC,QAAQ,EACd,KAAK,CAAC,aAAa,EACnB,KAAK,CAAC,eAAe,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,IAAI,EACpE,KAAK,CAAC,YAAY,EAClB,KAAK,CAAC,WAAW,IAAI,IAAI,EACzB,KAAK,CAAC,YAAY,CACnB,CAAC;QACJ,OAAO;YACL,OAAO;YACP,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,aAAa,EAAE,KAAK,CAAC,aAAa;YAClC,eAAe,EAAE,KAAK,CAAC,eAAe,IAAI,IAAI;YAC9C,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,IAAI;YACtC,YAAY,EAAE,KAAK,CAAC,YAAY;SACjC,CAAC;IACJ,CAAC;IAED,eAAe,CAAC,UAAkB,EAAE,KAAK,GAAG,EAAE;QAC5C,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE;aACjB,OAAO,CACN;qDAC6C,CAC9C;aACA,GAAG,CAAC,UAAU,EAAE,KAAK,CAAe,CAAC;QACxC,OAAO,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAC9B,CAAC;IAED,gBAAgB,CAAC,UAAkB;QACjC,MAAM,GAAG,GAAG,IAAI,CAAC,EAAE;aAChB,OAAO,CAAC,sEAAsE,CAAC;aAC/E,GAAG,CAAC,UAAU,CAAkB,CAAC;QACpC,OAAO,GAAG,CAAC,CAAC,CAAC;IACf,CAAC;CACF;AAED,SAAS,UAAU,CAAC,GAAa;IAC/B,OAAO;QACL,OAAO,EAAE,GAAG,CAAC,QAAQ;QACrB,UAAU,EAAE,GAAG,CAAC,WAAW;QAC3B,MAAM,EAAE,GAAG,CAAC,OAAO;QACnB,QAAQ,EAAE,GAAG,CAAC,SAAS;QACvB,QAAQ,EAAE,GAAG,CAAC,SAAS;QACvB,aAAa,EAAE,GAAG,CAAC,cAAkC;QACrD,eAAe,EAAE,GAAG,CAAC,qBAAqB;YACxC,CAAC,CAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,qBAAqB,CAA6B;YACpE,CAAC,CAAC,IAAI;QACR,YAAY,EAAE,GAAG,CAAC,aAAa;QAC/B,WAAW,EAAE,GAAG,CAAC,aAAa;QAC9B,YAAY,EAAE,GAAG,CAAC,cAAc;KACjC,CAAC;AACJ,CAAC"}

package/daemon/dist/domain/workflow-types.d.ts

@@ -0,0 +1,108 @@
+export type WorkflowExitKind = "handoff" | "waiting" | "done" | "failed";
+export interface WorkflowRoleSpec {
+    /** Skill identifiers that an agent in this role implements. */
+    skill_refs?: string[];
+    /** Operator-supplied preferred session targets for this role. */
+    preferred_targets?: string[];
+}
+export interface WorkflowStepSpec {
+    /** Stable step identifier within the workflow (e.g., "produce"). */
+    id: string;
+    /** Role name; resolved against `roles` map. */
+    actor_role: string;
+    /** Human description of the step's intent. */
+    objective?: string;
+    /** Allowed exit kinds for this step. Subset of WorkflowExitKind values. */
+    allowed_exits?: WorkflowExitKind[];
+    /** Next-hop hint structure (informs projection). */
+    next_hop?: {
+        mode?: "prefer" | "require" | "forbid";
+        suggested_roles?: string[];
+    };
+    /** Named gates the step depends on (graduation; not enforced in v1). */
+    gates?: string[];
+}
+export interface WorkflowInvariants {
+    continuation_required?: boolean;
+    allowed_exits?: WorkflowExitKind[];
+    preserve_lineage?: boolean;
+    closure_required?: boolean;
+}
+export interface WorkflowClosureMessages {
+    success?: string;
+    degraded?: string;
+    failed?: string;
+}
+export interface WorkflowLoopGuards {
+    /** Maximum total step transitions an instance may execute. */
+    max_hops?: number;
+    /** Maximum number of dynamically-spawned sub-instances. */
+    spawn_budget?: number;
+}
+export interface WorkflowSpec {
+    id: string;
+    version: string;
+    objective?: string;
+    target?: {
+        rig?: string;
+    };
+    entry?: {
+        role?: string;
+    };
+    roles: Record<string, WorkflowRoleSpec>;
+    steps: WorkflowStepSpec[];
+    invariants?: WorkflowInvariants;
+    closure?: WorkflowClosureMessages;
+    loop_guards?: WorkflowLoopGuards;
+    /** Coordination terminal-turn rule; defaults to "hot_potato". */
+    coordination_terminal_turn_rule?: string;
+}
+export type WorkflowInstanceStatus = "active" | "waiting" | "completed" | "failed";
+export interface WorkflowInstance {
+    instanceId: string;
+    workflowName: string;
+    workflowVersion: string;
+    createdBySession: string;
+    createdAt: string;
+    status: WorkflowInstanceStatus;
+    /** qitem_ids that are currently active step packets. */
+    currentFrontier: string[];
+    /**
+     * R2 fix: durable current-step binding (which step the active
+     * frontier packet represents). Set on instantiate (entry step) and
+     * on handoff (next step). Cleared on terminal closure. Read by
+     * WorkflowProjector instead of inferring from trail order — fixes
+     * the waiting-resume "skip a step" bug. v1 supports a single active
+     * frontier packet.
+     */
+    currentStepId: string | null;
+    hopCount: number;
+    fallbackSynthesis: string | null;
+    lastContinuationDecision: Record<string, unknown> | null;
+    completedAt: string | null;
+}
+export interface WorkflowStepTrailEntry {
+    trailId: string;
+    instanceId: string;
+    stepId: string;
+    stepRole: string;
+    closedAt: string;
+    closureReason: WorkflowExitKind;
+    closureEvidence: Record<string, unknown> | null;
+    actorSession: string;
+    nextQitemId: string | null;
+    priorQitemId: string;
+}
+export interface WorkflowSpecRow {
+    specId: string;
+    name: string;
+    version: string;
+    purpose: string | null;
+    targetRig: string | null;
+    spec: WorkflowSpec;
+    coordinationTerminalTurnRule: string;
+    sourcePath: string;
+    sourceHash: string;
+    cachedAt: string;
+}
+//# sourceMappingURL=workflow-types.d.ts.map