@revisium/orchestrator 0.0.0

package/dist/control-plane/definitions.js

@@ -0,0 +1,120 @@
+import { ControlPlaneError } from './errors.js';
+import { createClientTransport } from './client-transport.js';
+/** Fail-safe defaults — preserve pre-0008 behavior when the routing_policy row is absent. */
+export const DEFAULT_PIPELINE_POLICY = {
+    maxReviewIterations: 3,
+    maxAttempts: 3,
+    budgetUsd: 0,
+    budgetTokens: 0,
+};
+const VALID_MODEL_LEVELS = ['cheap', 'standard', 'deep'];
+function toModelLevel(raw) {
+    const s = toStr(raw) || 'standard';
+    if (!VALID_MODEL_LEVELS.includes(s)) {
+        throw new ControlPlaneError('VALIDATION_FAILURE', `Invalid model_level "${s}": expected one of ${VALID_MODEL_LEVELS.join(', ')}`);
+    }
+    return s;
+}
+function toStr(v) {
+    if (typeof v === 'string')
+        return v;
+    if (typeof v === 'number')
+        return String(v);
+    return '';
+}
+function parseJsonField(value) {
+    if (value === '' || value === null || value === undefined)
+        return {};
+    if (typeof value !== 'string')
+        return value;
+    return JSON.parse(value);
+}
+/** Coerce to a positive integer, else the fallback (for policy/role numeric fields). */
+function toPosInt(value, fallback) {
+    const n = typeof value === 'number' ? value : Number(value);
+    return Number.isFinite(n) && Number.isInteger(n) && n > 0 ? n : fallback;
+}
+/** Coerce to a non-negative number, else the fallback (for budgets — 0 = unlimited). */
+function toNonNegNum(value, fallback) {
+    const n = typeof value === 'number' ? value : Number(value);
+    return Number.isFinite(n) && n >= 0 ? n : fallback;
+}
+/** Optional positive-integer field — undefined when absent/invalid (role timeout). */
+function toOptPosInt(value) {
+    const n = typeof value === 'number' ? value : Number(value);
+    return Number.isFinite(n) && Number.isInteger(n) && n > 0 ? n : undefined;
+}
+/** True for a "row not found" error — ControlPlaneError ROW_NOT_FOUND or any 404-shaped error. */
+function isRowNotFound(err) {
+    if (err instanceof ControlPlaneError)
+        return err.code === 'ROW_NOT_FOUND';
+    const status = err?.statusCode;
+    return status === 404;
+}
+export async function loadRole(name, transport) {
+    const t = transport ?? createClientTransport('head');
+    const row = await t.getRow('roles', name);
+    const d = row.data ?? {};
+    return {
+        name: toStr(d.name) || name,
+        systemPrompt: toStr(d.system_prompt),
+        modelLevel: toModelLevel(d.model_level),
+        effort: toStr(d.effort),
+        runner: (toStr(d.runner) || 'claude-code'),
+        allowedTools: Array.isArray(d.allowed_tools) ? d.allowed_tools.map(toStr) : [],
+        scopeRules: parseJsonField(d.scope_rules),
+        playbookId: toStr(d.playbook_id) || undefined,
+        playbookRoleId: toStr(d.playbook_role_id) || undefined,
+        sourcePath: toStr(d.source_path) || undefined,
+        sourceHash: toStr(d.source_hash) || undefined,
+        surface: toStr(d.surface) || undefined,
+        rights: toStr(d.rights) || undefined,
+        timeoutMs: toOptPosInt(d.timeout_ms),
+        permissionMode: toStr(d.permission_mode) || undefined,
+    };
+}
+/**
+ * loadPipelinePolicy — read pipeline limits from the routing_policy table (0008 #5).
+ *
+ * Reads row `rowId` (default 'pipeline'); parses its `rule` JSON for max_review_iterations,
+ * max_attempts, budget_usd, budget_tokens. Falls back to DEFAULT_PIPELINE_POLICY when the row
+ * is absent (routing_policy starts EMPTY) so the pipeline keeps working before the seed lands.
+ */
+export async function loadPipelinePolicy(transport, rowId = 'pipeline') {
+    const t = transport ?? createClientTransport('head');
+    // Default ONLY when the policy row is absent (routing_policy starts EMPTY). A transport failure
+    // or MALFORMED rule JSON must NOT silently disable the budget/limits — rethrow those so a typo in
+    // the budget config surfaces loudly instead of falling back to "unlimited" (codex 0008 finding).
+    let row;
+    try {
+        row = await t.getRow('routing_policy', rowId);
+    }
+    catch (err) {
+        if (isRowNotFound(err))
+            return { ...DEFAULT_PIPELINE_POLICY };
+        throw err;
+    }
+    // parseJsonField may throw on malformed JSON — intentionally NOT caught (see above).
+    const parsed = parseJsonField(row.data?.rule);
+    const rule = parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+    return {
+        maxReviewIterations: toPosInt(rule.max_review_iterations, DEFAULT_PIPELINE_POLICY.maxReviewIterations),
+        maxAttempts: toPosInt(rule.max_attempts, DEFAULT_PIPELINE_POLICY.maxAttempts),
+        budgetUsd: toNonNegNum(rule.budget_usd, DEFAULT_PIPELINE_POLICY.budgetUsd),
+        budgetTokens: toNonNegNum(rule.budget_tokens, DEFAULT_PIPELINE_POLICY.budgetTokens),
+    };
+}
+export async function loadModelProfile(level, transport) {
+    const t = transport ?? createClientTransport('head');
+    const row = await t.getRow('model_profiles', level);
+    const d = row.data ?? {};
+    return {
+        level: (toStr(d.level) || level),
+        provider: toStr(d.provider),
+        modelId: toStr(d.model_id),
+        params: parseJsonField(d.params),
+        costPerInput: Number(d.cost_per_input ?? 0),
+        costPerOutput: Number(d.cost_per_output ?? 0),
+    };
+}
+//# sourceMappingURL=definitions.js.map

package/dist/control-plane/definitions.js.map

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

package/dist/control-plane/errors.js

@@ -0,0 +1,13 @@
+export class ControlPlaneError extends Error {
+    code;
+    status;
+    details;
+    constructor(code, message, options = {}) {
+        super(message);
+        this.name = 'ControlPlaneError';
+        this.code = code;
+        this.status = options.status;
+        this.details = options.details;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/control-plane/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/control-plane/errors.ts"],"names":[],"mappings":"AAQA,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACjC,IAAI,CAAwB;IAC5B,MAAM,CAAU;IAChB,OAAO,CAAW;IAE3B,YAAY,IAA2B,EAAE,OAAe,EAAE,UAAkD,EAAE;QAC5G,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IACjC,CAAC;CACF"}

package/dist/control-plane/inbox.js

@@ -0,0 +1,261 @@
+/**
+ * inbox.ts — PURE Revisium-table inbox verbs. NO DBOS imports anywhere in this file.
+ *
+ * Covers: pushInbox, listInbox, getInbox, resolveInbox.
+ *
+ * RESUMABILITY guarantee (G9): resolveInbox COMPLETES idempotently on every call.
+ * A crash between the inbox patch and the step patch is repaired by a retry — the
+ * retry re-reads the already-resolved inbox row, takes the stored answer (stored
+ * answer wins; first resolver is authoritative), and idempotently drives the step
+ * from awaiting_approval → ready. Calling resolveInbox twice converges to:
+ *   inbox resolved + step unblocked exactly once.
+ *
+ * KNOWN LIMITATION (G5 residual): data-access.ts patchRow is a plain write — no
+ * CAS. Two truly-concurrent first-time resolvers can both pass the `pending` read
+ * before either writes, and both proceed (each re-flips the step — harmless
+ * idempotent duplicate writes, but no CAS prevents dual entry). In practice the
+ * inbox has a single human resolver, so this is acceptable for 0002. A full
+ * conditional pending→resolved transition is a data-access-seam enhancement
+ * (add CAS/conditional write to data-access.ts) and is out of scope for 0002.
+ * Do NOT "fix" this by adding DBOS or hand-rolling a lock.
+ */
+import { randomUUID } from 'node:crypto';
+import { ControlPlaneError } from './errors.js';
+import { compactStamp } from './steps.js'; // NOT from ./index.js — compactStamp is not re-exported there
+// ─── secret redaction ────────────────────────────────────────
+const SECRET_PATTERN = /(?:password|secret|token|key|credential|auth|api_key|apikey)/i;
+/**
+ * Recursively strip obvious secret-shaped keys from a value before persisting.
+ * - Plain objects: redact matching keys at ANY depth, recurse into non-secret values.
+ * - Arrays: recurse into each element.
+ * - Primitives / null: return as-is.
+ * Full policy can firm up later; this covers the common cases.
+ */
+export function redactSecrets(value) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (Array.isArray(value)) {
+        return value.map(redactSecrets);
+    }
+    const result = {};
+    for (const [k, v] of Object.entries(value)) {
+        result[k] = SECRET_PATTERN.test(k) ? '[REDACTED]' : redactSecrets(v);
+    }
+    return result;
+}
+// ─── row mapping ─────────────────────────────────────────────
+function str(v) {
+    return typeof v === 'string' ? v : '';
+}
+function mapInboxRow(rowId, data) {
+    return {
+        id: rowId,
+        kind: str(data.kind),
+        runId: str(data.run_id),
+        taskId: str(data.task_id),
+        stepId: str(data.step_id),
+        projectId: str(data.project_id),
+        title: str(data.title),
+        context: data.context ?? null,
+        options: Array.isArray(data.options) ? data.options.map(str) : [],
+        status: str(data.status),
+        answer: data.answer ?? null,
+        resolvedBy: str(data.resolved_by),
+        createdAt: str(data.created_at),
+        resolvedAt: str(data.resolved_at),
+    };
+}
+// ─── exported verbs ──────────────────────────────────────────
+/**
+ * pushInbox — insert an inbox row; set the originating step to awaiting_approval
+ * (branch stops, siblings continue). Returns the inbox id.
+ *
+ * G10: seeds answer: null, resolved_by: '', resolved_at: '' so that the resolveInbox
+ * `replace` patches hit present paths (serializeData omits undefined fields, leaving
+ * absent paths that Revisium's patch handler rejects for `replace`).
+ *
+ * G1 (0004): accepts `opts.id` — when present, used VERBATIM (bypassing compactStamp+suffix).
+ * This is the fully-deterministic path used by gate pushes in the workflow body.
+ * Legacy callers pass no `id` → timestamp+suffix path is unchanged (backward-compatible).
+ *
+ * G1 idempotency: wraps createRow in a ROW_CONFLICT catch (mirrors append-event.ts:69-72).
+ * On a workflow-body replay the row already exists → swallows the conflict and returns the
+ * same id (no-op, no duplicate). Gate rows carry no stepId, so the step-park branch is moot
+ * on ROW_CONFLICT; we return before it.
+ *
+ * Redacts secrets in context before writing (contract line 163).
+ */
+export async function pushInbox(da, item, opts) {
+    await da.assertReady();
+    // CR-C (0004 CR): avoid computing non-deterministic values on the deterministic gate path.
+    // When opts.id is present, we do NOT call new Date() until we are inside the actual insert —
+    // at which point ROW_CONFLICT makes the row exactly-once (first write wins; any replayed
+    // new Date() is discarded by the conflict and never persisted). The timestamp is a real wall-
+    // clock value on the FIRST insert and is irrelevant on replay. Only the legacy path (no
+    // opts.id) needs now for the id itself, so it is computed first in that branch only.
+    let id;
+    let now;
+    if (opts?.id === undefined) {
+        // Legacy path: timestamp is part of the id — must be computed before createRow.
+        now = opts?.now ?? new Date();
+        const suffix = opts?.idSuffix ?? randomUUID().replaceAll('-', '').slice(0, 8);
+        id = `inbox_${compactStamp(now)}_${suffix}`;
+    }
+    else {
+        // Deterministic gate path: id is caller-supplied verbatim; timestamp is only needed
+        // for created_at in the insert — evaluated lazily inside the try block below.
+        id = opts.id;
+        // Use opts.now if provided (test-seeded), otherwise defer new Date() to the insert.
+        now = opts?.now ?? new Date();
+    }
+    const safeContext = redactSecrets(item.context);
+    try {
+        await da.createRow('inbox', id, {
+            id,
+            kind: item.kind,
+            run_id: item.runId ?? '',
+            task_id: item.taskId ?? '',
+            step_id: item.stepId ?? '',
+            project_id: item.projectId ?? '',
+            title: item.title,
+            context: safeContext,
+            options: item.options ?? [],
+            status: 'pending',
+            // G10 — seed every later-patched optional column as a present value (never undefined).
+            // serializeData (json-fields.ts:38) omits undefined fields; an absent path causes
+            // Revisium's patch handler to reject a replace → resolveInbox patches would fail.
+            // answer: null is serialized by json-fields as JSON null → 'null' string on the JSON field.
+            answer: null,
+            resolved_by: '',
+            resolved_at: '',
+            // On the opts.id (gate) path, created_at uses `now` computed above. On a workflow-body
+            // replay, ROW_CONFLICT fires BEFORE this value is persisted — so a different now per
+            // replay is harmless (it is discarded). The FIRST insert's timestamp is the real one.
+            created_at: now.toISOString(),
+        });
+    }
+    catch (e) {
+        // Idempotent on workflow-body replay (mirror append-event.ts:69-72). Same row already exists → no-op.
+        // Gate rows carry no stepId, so the step-park branch below is moot on conflict; return early.
+        if (e instanceof ControlPlaneError && e.code === 'ROW_CONFLICT')
+            return id;
+        throw e;
+    }
+    // Park the originating step (bare path — G6):
+    if (item.stepId) {
+        await da.patchRow('steps', item.stepId, [
+            { op: 'replace', path: 'status', value: 'awaiting_approval' },
+        ]);
+    }
+    return id;
+}
+/**
+ * listInbox — read the inbox table, optionally filtered.
+ * Draft read; consumers never see Revisium types (returns InboxItem[]).
+ */
+export async function listInbox(da, filter) {
+    await da.assertReady();
+    const rows = await da.listRows('inbox', { first: filter?.limit ?? 500 });
+    let items = rows.map((row) => mapInboxRow(row.rowId, row.data));
+    if (filter?.status)
+        items = items.filter((i) => i.status === filter.status);
+    if (filter?.runId)
+        items = items.filter((i) => i.runId === filter.runId);
+    return items;
+}
+/**
+ * getInbox — read a single inbox row.
+ * G12: intentionally returns InboxItem | null (maps da.getRow's null-on-missing path),
+ * superseding repo-layer-contract.md:172's non-null signature. Null is the safer shape.
+ */
+export async function getInbox(da, id) {
+    await da.assertReady();
+    const row = await da.getRow('inbox', id);
+    if (!row)
+        return null;
+    return mapInboxRow(row.rowId, row.data);
+}
+/**
+ * resolveInbox — pure status flip + step unblock. NO DBOS signal (that is 0004).
+ *
+ * G2 (0004): now returns the STORED decision `{ status, answer }` so the caller (CLI gate path)
+ * can signal WHAT IS RECORDED, never the raw flag passed to this call.
+ *   - `status` is the row's status BEFORE this call: 'pending' ⇒ just resolved; 'resolved' ⇒ already was.
+ *   - `answer` is the EFFECTIVE stored answer (first-resolver wins; retry returns stored, not its arg).
+ *
+ * Existing 0002 callers (non-gate resolve, run cancel CLI) ignore the return — backward-compatible.
+ *
+ * RESUMABLE + idempotent (G9): COMPLETES on every call.
+ *   - If inbox is pending: patch to resolved, then unblock the step.
+ *   - If inbox is already resolved (retry / double-resolve): skip the inbox re-patch
+ *     (stored answer wins), but STILL drive the step unblock from the stored answer.
+ *   - This means a crash between the inbox patch and the step patch is repaired by a
+ *     retry — the parked step is NEVER left stuck.
+ *
+ * CURRENT-STATE-SAFE (G5):
+ *   - pending → resolved only (else VALIDATION_FAILURE).
+ *   - Resurrection guard: if the step is no longer awaiting_approval (cancelled /
+ *     re-driven / gone), console.warn and skip the step flip without throwing.
+ *   - Deterministic continuation: step_cont_${itemId} so a re-run collides on the
+ *     same id rather than creating a duplicate.
+ *
+ * KNOWN LIMITATION: no CAS (see module doc-comment above).
+ */
+export async function resolveInbox(da, itemId, answer, resolvedBy, opts) {
+    await da.assertReady();
+    // (1) READ. getRow returns null for a missing inbox row.
+    const inbox = await da.getRow('inbox', itemId);
+    if (!inbox) {
+        throw new ControlPlaneError('ROW_NOT_FOUND', `inbox item not found: ${itemId}`);
+    }
+    // (2) STATE GUARD. Only pending or resolved are valid states to act on.
+    const status = inbox.data.status;
+    if (status !== 'pending' && status !== 'resolved') {
+        throw new ControlPlaneError('VALIDATION_FAILURE', `inbox ${itemId} cannot be resolved from status '${String(status)}'`);
+    }
+    const now = opts?.now ?? new Date();
+    // (3) IDEMPOTENT INBOX WRITE.
+    //   pending  → patch to resolved carrying answer / resolved_by / resolved_at.
+    //   resolved → SKIP the re-patch. The stored answer wins (first resolver is authoritative).
+    if (status === 'pending') {
+        await da.patchRow('inbox', itemId, [
+            { op: 'replace', path: 'status', value: 'resolved' }, // BARE paths (G6)
+            { op: 'replace', path: 'answer', value: answer },
+            { op: 'replace', path: 'resolved_by', value: resolvedBy },
+            { op: 'replace', path: 'resolved_at', value: now.toISOString() },
+        ]);
+    }
+    // C2 (0004 review): the effective answer is ALWAYS the STORED (persisted) value — re-read
+    // from the row. On the already-resolved path the pre-read row carries the stored answer.
+    // On the first-resolve path, re-read after patching so we return what is durably recorded
+    // (guards against JSON-field round-trip canonicalization differences and concurrent resolvers).
+    // Both paths converge to: signal what is recorded, never the raw caller argument.
+    const resolvedInbox = status === 'pending' ? await da.getRow('inbox', itemId) : inbox;
+    const effectiveAnswer = resolvedInbox?.data.answer ?? answer;
+    // (4) ALWAYS-RUN STEP COMPLETION (the resumable part).
+    // Runs on every call once inbox is known-resolved.
+    const stepId = typeof inbox.data.step_id === 'string' ? inbox.data.step_id : '';
+    if (!stepId) {
+        // alert-kind / step-less item (including gate rows): inbox flip is the whole resolve.
+        return { status, answer: effectiveAnswer };
+    }
+    // Re-read the originating step and idempotently complete the unblock.
+    const step = await da.getRow('steps', stepId);
+    if (step && step.data.status === 'awaiting_approval') {
+        // Still parked → flip to ready carrying the stored answer. Bare paths (G6).
+        await da.patchRow('steps', stepId, [
+            { op: 'replace', path: 'status', value: 'ready' },
+            { op: 'replace', path: 'input', value: effectiveAnswer },
+        ]);
+        return { status, answer: effectiveAnswer };
+    }
+    // step already ready (done state) → clean NO-OP (no warn, no duplicate).
+    if (step && step.data.status === 'ready') {
+        return { status, answer: effectiveAnswer };
+    }
+    // step is null OR in an unexpected state (cancelled / re-driven / superseded) →
+    // RESURRECTION GUARD: do NOT flip it. Leave the inbox resolved and console.warn.
+    console.warn(`resolveInbox: step ${stepId} no longer awaiting_approval; skipping unblock`);
+    return { status, answer: effectiveAnswer };
+}
+//# sourceMappingURL=inbox.js.map

package/dist/control-plane/inbox.js.map

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

package/dist/control-plane/index.js

@@ -0,0 +1,6 @@
+export { ControlPlaneError } from './errors.js';
+export { createControlPlaneDataAccess, createControlPlaneDataAccessForTransport, } from './data-access.js';
+export { runtimeTables } from './tables.js';
+export { claimNextStep, startAttempt, writeResult, createSteps, failStep, recoverInFlight, fnv1a64Hex, } from './steps.js';
+export { loadRole, loadModelProfile } from './definitions.js';
+//# sourceMappingURL=index.js.map

package/dist/control-plane/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/control-plane/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAA8B,MAAM,aAAa,CAAC;AAC5E,OAAO,EACL,4BAA4B,EAC5B,wCAAwC,GAQzC,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAqB,MAAM,aAAa,CAAC;AAC/D,OAAO,EACL,aAAa,EACb,YAAY,EACZ,WAAW,EACX,WAAW,EACX,QAAQ,EACR,eAAe,EACf,UAAU,GAKX,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAgC,MAAM,kBAAkB,CAAC"}

package/dist/control-plane/json-fields.js

@@ -0,0 +1,68 @@
+import { ControlPlaneError } from './errors.js';
+const jsonFields = {
+    steps: ['input', 'output'],
+    events: ['payload'],
+    inbox: ['context', 'answer'],
+};
+function fieldsFor(table) {
+    return jsonFields[table] ?? [];
+}
+function pathRoot(path) {
+    return path.replace(/^\/+/, '').split(/[/.]/, 1)[0] ?? '';
+}
+function pathIsNestedJsonField(table, path) {
+    const normalized = path.replace(/^\/+/, '');
+    return fieldsFor(table).some((field) => normalized.startsWith(`${field}.`) || normalized.startsWith(`${field}/`));
+}
+export function serializeData(table, rowId, data) {
+    if (typeof data.id === 'string' && data.id !== rowId) {
+        throw new ControlPlaneError('VALIDATION_FAILURE', `data.id must match rowId for ${table}/${rowId}`, {
+            details: { table, rowId, field: 'id', value: data.id },
+        });
+    }
+    const serialized = {};
+    for (const [key, value] of Object.entries({ ...data, id: data.id ?? rowId })) {
+        if (value === undefined)
+            continue;
+        serialized[key] = fieldsFor(table).includes(key) ? JSON.stringify(value) : value;
+    }
+    return serialized;
+}
+export function deserializeData(table, rowId, data) {
+    const deserialized = { ...data };
+    for (const field of fieldsFor(table)) {
+        const value = deserialized[field];
+        if (value === undefined || value === '') {
+            deserialized[field] = null;
+            continue;
+        }
+        if (typeof value !== 'string') {
+            throw new ControlPlaneError('VALIDATION_FAILURE', `Expected serialized JSON string at ${table}/${rowId}.${field}`, {
+                details: { table, rowId, field, value },
+            });
+        }
+        try {
+            deserialized[field] = JSON.parse(value);
+        }
+        catch (error) {
+            throw new ControlPlaneError('VALIDATION_FAILURE', `Invalid stored JSON at ${table}/${rowId}.${field}`, {
+                details: { table, rowId, field, value, error },
+            });
+        }
+    }
+    return deserialized;
+}
+export function serializePatches(table, patches) {
+    return patches.map((patch) => {
+        const root = pathRoot(patch.path);
+        if (pathIsNestedJsonField(table, patch.path)) {
+            throw new ControlPlaneError('VALIDATION_FAILURE', `Nested JSON field patches are not supported: ${patch.path}`, {
+                details: { table, path: patch.path },
+            });
+        }
+        if (!fieldsFor(table).includes(root) || !('value' in patch) || patch.value === undefined)
+            return { ...patch };
+        return { ...patch, value: JSON.stringify(patch.value) };
+    });
+}
+//# sourceMappingURL=json-fields.js.map

package/dist/control-plane/json-fields.js.map

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

package/dist/control-plane/resolve-cwd.js

@@ -0,0 +1,75 @@
+/**
+ * resolve-cwd.ts — shared B1 contract for resolving the working directory from a repo_ref.
+ *
+ * B1 CONTRACT — the resolved working directory MUST be an existing directory. We accept:
+ *   • '' or '.'                  → base (the workspace cwd)
+ *   • an ABSOLUTE existing dir   → that dir (the external target repo — the MVP case)
+ *   • a relative path under base → resolve(base, ref), if it stays under base AND exists
+ * We REJECT (throw a lesson-bearing error):
+ *   • a non-existent path        → never launch claude in a directory that isn't there
+ *   • a path that is not a dir   → never launch claude against a file
+ *   • a relative '../…' escape   → traversal guard (only relative refs are guarded; an ABSOLUTE
+ *                                   ref is taken as the literal target repo, existence-checked).
+ */
+import { resolve, isAbsolute, relative, sep } from 'node:path';
+import { existsSync, realpathSync, statSync } from 'node:fs';
+import { toStr } from './steps.js';
+/** Resolve a repo_ref string to an absolute, existing directory path. */
+export async function resolveRepoCwdFromRef(repoRef, base) {
+    if (repoRef === '' || repoRef === '.')
+        return base;
+    const resolved = isAbsolute(repoRef) ? resolve(repoRef) : resolve(base, repoRef);
+    if (!isAbsolute(repoRef) && resolved !== base && !resolved.startsWith(base + sep)) {
+        throw new Error(`resolveCwd: relative repo_ref ${JSON.stringify(repoRef)} escapes the workspace base ` +
+            `${JSON.stringify(base)} — refusing to launch`);
+    }
+    if (!existsSync(resolved) || !statSync(resolved).isDirectory()) {
+        throw new Error(`resolveCwd: repo path ${JSON.stringify(resolved)} does not exist or is not a directory ` +
+            `— refusing to launch claude`);
+    }
+    // Symlink escape guard: canonicalize via realpathSync and re-check containment.
+    // This prevents a symlink inside the allowed base from pointing outside it.
+    // Only applied when the ref is relative (absolute refs designate an external target repo
+    // and are accepted as-is — their real path IS the intended target).
+    if (!isAbsolute(repoRef)) {
+        let realTarget;
+        let realBase;
+        try {
+            realTarget = realpathSync(resolved);
+            realBase = realpathSync(base);
+        }
+        catch {
+            // realpathSync throws on non-existent paths — treat as non-existent (same as above check).
+            throw new Error(`resolveCwd: repo path ${JSON.stringify(resolved)} does not exist or is not a directory ` +
+                `— refusing to launch claude`);
+        }
+        const rel = relative(realBase, realTarget);
+        if (rel.startsWith('..') || isAbsolute(rel)) {
+            throw new Error(`resolveCwd: relative repo_ref ${JSON.stringify(repoRef)} escapes the workspace base ` +
+                `${JSON.stringify(base)} via symlink — refusing to launch`);
+        }
+    }
+    return resolved;
+}
+async function readRepoRef(da, taskId) {
+    const task = await da.getRow('tasks', taskId);
+    if (task === null) {
+        throw new Error(`resolveCwd: task ${taskId} not found — cannot resolve a working directory`);
+    }
+    return toStr(task.data.repo_ref);
+}
+/**
+ * STEP-level resolver (M3) — shape expected by claude runner: (step: Step) => Promise<string>.
+ * Reads tasks.repo_ref for the step's taskId via the data-access layer.
+ */
+export function makeResolveCwd(da, base = process.cwd()) {
+    return async (step) => resolveRepoCwdFromRef(await readRepoRef(da, step.taskId), base);
+}
+/**
+ * TASK-level resolver (M3) — shape expected by the integrator + live preflight: (taskId: string) => Promise<string>.
+ * Uses the same core as makeResolveCwd over one shared readRepoRef.
+ */
+export function makeResolveTaskCwd(da, base = process.cwd()) {
+    return async (taskId) => resolveRepoCwdFromRef(await readRepoRef(da, taskId), base);
+}
+//# sourceMappingURL=resolve-cwd.js.map

package/dist/control-plane/resolve-cwd.js.map

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