agents-relay 2.0.31 → 2.0.33

package/dist/projection-outbox.js

@@ -0,0 +1,268 @@
+export const SCHEMA_VERSION = 5;
+const UNSAFE_QUEUED_KEY_SUFFIX = /:(?:queued|lost):\d+$/;
+/** Logical operation key recovered from a possibly queued/lost idempotency key. */
+export function logicalOperationKey(idempotencyKey) {
+    return idempotencyKey.replace(UNSAFE_QUEUED_KEY_SUFFIX, '');
+}
+export function rowToProjection(row) {
+    return {
+        id: Number(row.id),
+        idempotencyKey: row.idempotency_key,
+        operationKey: row.operation_key ?? logicalOperationKey(row.idempotency_key),
+        coalesceKey: row.coalesce_key,
+        operation: row.operation,
+        payload: JSON.parse(row.payload_json),
+        priority: Number(row.priority),
+        attempts: Number(row.attempts),
+        nextAttemptAt: row.next_attempt_at,
+        lastError: row.last_error,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+export function rowToConflict(row) {
+    const evidence = row.conflict_evidence_json ? JSON.parse(row.conflict_evidence_json) : {};
+    const resolution = row.conflict_resolution_json ? JSON.parse(row.conflict_resolution_json) : null;
+    const operationKey = row.operation_key ?? logicalOperationKey(row.idempotency_key);
+    return {
+        id: Number(row.id),
+        status: (row.status ?? 'conflict'),
+        operation: row.operation,
+        operationKey,
+        attempts: Number(row.attempts),
+        diagnostic: {
+            kind: evidence.kind ?? 'task',
+            jobId: String(evidence.jobId ?? ''),
+            subjectId: String(evidence.subjectId ?? ''),
+            operation: row.operation,
+            operationKey,
+            localDefinition: row.conflict_definition_json ? JSON.parse(row.conflict_definition_json) : null,
+            remoteDefinition: evidence.remoteDefinition ?? null,
+            divergingFields: Array.isArray(evidence.divergingFields) ? evidence.divergingFields.map(String) : [],
+            detectedAt: row.conflict_detected_at ?? row.updated_at,
+            message: String(evidence.message ?? row.last_error ?? 'projection definition conflict'),
+        },
+        resolution,
+    };
+}
+const OUTBOX_COLUMNS = 'id,idempotency_key,operation_key,coalesce_key,operation,payload_json,priority,status,attempts,next_attempt_at,last_error,created_at,updated_at,conflict_definition_json,conflict_evidence_json,conflict_detected_at,conflict_disposition,conflict_resolution_json';
+/**
+ * Durable projection outbox persistence.
+ *
+ * Owns the schema, pending/processing/conflict/dead state machine storage, coalescing,
+ * claiming, retry/backoff bookkeeping, deterministic-conflict diagnostics, and explicit repair.
+ * It is deliberately independent of Job/Task/Plan semantics: callers persist domain state
+ * separately and enqueue one projection request.
+ */
+export class ProjectionOutbox {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    static createTableSql(table = 'projection_outbox') {
+        return `CREATE TABLE IF NOT EXISTS ${table} (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        idempotency_key TEXT NOT NULL UNIQUE,
+        operation_key TEXT,
+        coalesce_key TEXT,
+        operation TEXT NOT NULL,
+        payload_json TEXT NOT NULL,
+        priority INTEGER NOT NULL DEFAULT 0,
+        status TEXT NOT NULL DEFAULT 'pending' CHECK(status IN ('pending','processing','conflict','dead')),
+        attempts INTEGER NOT NULL DEFAULT 0,
+        next_attempt_at TEXT,
+        last_error TEXT,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        conflict_definition_json TEXT,
+        conflict_evidence_json TEXT,
+        conflict_detected_at TEXT,
+        conflict_disposition TEXT,
+        conflict_resolution_json TEXT
+      );`;
+    }
+    static createIndexSql() {
+        return `
+      CREATE INDEX IF NOT EXISTS projection_due_idx ON projection_outbox(status, next_attempt_at, priority DESC, id);
+      CREATE INDEX IF NOT EXISTS projection_coalesce_idx ON projection_outbox(coalesce_key, status);
+    `;
+    }
+    /** Rebuild a pre-v5 outbox, backfill logical operation keys, and classify legacy dead conflicts. */
+    static upgrade(db, previousVersion) {
+        const schema = db.prepare("SELECT sql FROM sqlite_master WHERE type='table' AND name='projection_outbox'").get();
+        const sql = schema?.sql ?? '';
+        const needsRebuild = sql.length > 0 && (!sql.includes("'conflict'") || !sql.includes('operation_key'));
+        db.exec('BEGIN IMMEDIATE');
+        try {
+            if (needsRebuild) {
+                db.exec(`
+          DROP INDEX IF EXISTS projection_due_idx;
+          DROP INDEX IF EXISTS projection_coalesce_idx;
+          ALTER TABLE projection_outbox RENAME TO projection_outbox_legacy;
+          ${ProjectionOutbox.createTableSql()}
+          INSERT INTO projection_outbox(id,idempotency_key,coalesce_key,operation,payload_json,priority,status,attempts,next_attempt_at,last_error,created_at,updated_at)
+          SELECT id,idempotency_key,coalesce_key,operation,payload_json,priority,status,attempts,next_attempt_at,last_error,created_at,updated_at FROM projection_outbox_legacy;
+          DROP TABLE projection_outbox_legacy;
+        `);
+            }
+            db.exec(ProjectionOutbox.createIndexSql());
+            db.prepare(`
+        UPDATE projection_outbox
+        SET operation_key = CASE
+          WHEN operation_key IS NOT NULL AND operation_key<>'' THEN operation_key
+          WHEN idempotency_key GLOB '*:queued:*' THEN substr(idempotency_key, 1, instr(idempotency_key, ':queued:') - 1)
+          ELSE idempotency_key END
+        WHERE operation_key IS NULL OR operation_key=''
+      `).run();
+            const diagnostics = db.prepare(`
+        SELECT id,operation,idempotency_key,last_error,attempts,updated_at FROM projection_outbox
+        WHERE status='dead' AND last_error LIKE '%already exists with a different definition%'
+      `).all();
+            const promote = db.prepare(`
+        UPDATE projection_outbox
+        SET status='conflict', conflict_detected_at=?, conflict_disposition='classified_on_migration',
+            conflict_evidence_json=?, conflict_definition_json=COALESCE(conflict_definition_json, payload_json)
+        WHERE id=?
+      `);
+            for (const row of diagnostics) {
+                const evidence = JSON.stringify({ kind: row.operation === 'append_plan' ? 'plan' : 'task', subjectId: '', jobId: '', divergingFields: [], message: row.last_error ?? 'legacy deterministic projection conflict', migratedFromAttempts: Number(row.attempts), recoveredFromSchema: previousVersion });
+                promote.run(row.updated_at, evidence, row.id);
+            }
+            db.exec('COMMIT');
+        }
+        catch (error) {
+            db.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    resetProcessing(now) {
+        this.db.prepare("UPDATE projection_outbox SET status='pending', updated_at=? WHERE status='processing'").run(now);
+    }
+    enqueue(request, now) {
+        const operationKey = logicalOperationKey(request.idempotencyKey);
+        if (request.coalesceKey) {
+            this.db.prepare(`
+        DELETE FROM projection_outbox
+        WHERE coalesce_key=? AND status='pending' AND operation_key<>?
+      `).run(request.coalesceKey, operationKey);
+        }
+        const existing = this.db.prepare('SELECT status FROM projection_outbox WHERE operation_key=? ORDER BY id DESC LIMIT 1')
+            .get(operationKey);
+        // A writer may be applying this key outside the transaction, or a deterministic
+        // conflict may already be recorded for it. Never rewrite that row's payload: its
+        // completion must only remove its own row, and a recorded conflict must stay the
+        // classification evidence until explicitly repaired. New mutations queue beside it.
+        const nextId = Number(this.db.prepare('SELECT COALESCE(MAX(id),0)+1 AS next_id FROM projection_outbox').get().next_id ?? 1);
+        const collides = existing?.status === 'processing' || existing?.status === 'conflict' || existing?.status === 'dead';
+        const idempotencyKey = collides ? `${operationKey}:queued:${nextId}` : operationKey;
+        this.db.prepare(`
+      INSERT INTO projection_outbox(
+        idempotency_key,operation_key,coalesce_key,operation,payload_json,priority,status,
+        attempts,next_attempt_at,last_error,created_at,updated_at
+      ) VALUES(?,?,?,?,?,?,'pending',0,NULL,NULL,?,?)
+      ON CONFLICT(idempotency_key) DO UPDATE SET
+        operation_key=excluded.operation_key,
+        coalesce_key=excluded.coalesce_key,
+        operation=excluded.operation,
+        payload_json=excluded.payload_json,
+        priority=MAX(projection_outbox.priority,excluded.priority),
+        status='pending',
+        next_attempt_at=NULL,
+        last_error=NULL,
+        updated_at=excluded.updated_at
+    `).run(idempotencyKey, operationKey, request.coalesceKey ?? null, request.operation, JSON.stringify(request.payload), request.priority ?? 0, now, now);
+    }
+    claimDue(limit, now) {
+        const observedAt = now.toISOString();
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const rows = this.db.prepare(`
+        SELECT ${OUTBOX_COLUMNS}
+        FROM projection_outbox
+        WHERE status='pending' AND (next_attempt_at IS NULL OR next_attempt_at<=?)
+        ORDER BY priority DESC, id ASC
+        LIMIT ?
+      `).all(observedAt, Math.max(1, Math.floor(limit)));
+            const mark = this.db.prepare("UPDATE projection_outbox SET status='processing', updated_at=? WHERE id=? AND status='pending'");
+            const claimed = [];
+            for (const row of rows) {
+                const result = mark.run(observedAt, row.id);
+                if (Number(result.changes) === 1)
+                    claimed.push({ ...row, updated_at: observedAt });
+            }
+            this.db.exec('COMMIT');
+            return claimed.map(rowToProjection);
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    complete(id) {
+        this.db.prepare('DELETE FROM projection_outbox WHERE id=?').run(id);
+    }
+    retry(id, error, nextAttemptAt) {
+        this.db.prepare(`
+      UPDATE projection_outbox
+      SET status='pending', attempts=attempts+1, next_attempt_at=?, last_error=?, updated_at=?
+      WHERE id=?
+    `).run(nextAttemptAt.toISOString(), error, new Date().toISOString(), id);
+    }
+    deadLetter(id, error) {
+        this.db.prepare(`
+      UPDATE projection_outbox
+      SET status='dead', attempts=attempts+1, next_attempt_at=NULL, last_error=?, updated_at=?
+      WHERE id=?
+    `).run(error, new Date().toISOString(), id);
+    }
+    recordConflict(id, diagnostic) {
+        const evidence = JSON.stringify({
+            kind: diagnostic.kind,
+            jobId: diagnostic.jobId,
+            subjectId: diagnostic.subjectId,
+            remoteDefinition: diagnostic.remoteDefinition,
+            divergingFields: diagnostic.divergingFields,
+            message: diagnostic.message,
+        });
+        this.db.prepare(`
+      UPDATE projection_outbox
+      SET status='conflict', attempts=attempts+1, next_attempt_at=NULL, last_error=?,
+          conflict_definition_json=?, conflict_evidence_json=?, conflict_detected_at=?,
+          conflict_disposition='awaiting_repair', conflict_resolution_json=NULL, updated_at=?
+      WHERE id=? AND status NOT IN ('conflict','dead')
+    `).run(diagnostic.message, JSON.stringify(diagnostic.localDefinition), evidence, diagnostic.detectedAt, diagnostic.detectedAt, id);
+    }
+    listConflicts() {
+        const rows = this.db.prepare(`
+      SELECT ${OUTBOX_COLUMNS} FROM projection_outbox WHERE status='conflict' ORDER BY id ASC
+    `).all();
+        return rows.map(rowToConflict);
+    }
+    /** Explicit repair: requeue the original projection, or discard the blocked local mutation for a fresh one. */
+    resolveConflict(id, resolution) {
+        const now = new Date().toISOString();
+        const record = this.db.prepare('SELECT status FROM projection_outbox WHERE id=?').get(id);
+        if (!record || record.status !== 'conflict')
+            return false;
+        const resolutionJson = JSON.stringify({ action: resolution.action, resolvedAt: now, ...(resolution.note ? { note: resolution.note } : {}) });
+        if (resolution.action === 'requeue') {
+            this.db.prepare(`
+        UPDATE projection_outbox
+        SET status='pending', attempts=0, next_attempt_at=NULL, conflict_disposition='requeued',
+            conflict_resolution_json=?, updated_at=?
+        WHERE id=? AND status='conflict'
+      `).run(resolutionJson, now, id);
+        }
+        else {
+            this.db.prepare('DELETE FROM projection_outbox WHERE id=? AND status=?').run(id, 'conflict');
+        }
+        return true;
+    }
+    conflictCount() { return this.count("status='conflict'"); }
+    pendingCount() { return this.count("status IN ('pending','processing')"); }
+    terminalCount() { return this.count("status='dead'"); }
+    count(where) {
+        const row = this.db.prepare(`SELECT COUNT(*) AS count FROM projection_outbox WHERE ${where}`).get();
+        return Number(row?.count ?? 0);
+    }
+}

package/dist/relay-store.js

@@ -2,7 +2,7 @@ import { DatabaseSync } from 'node:sqlite';
 import { dirname } from 'node:path';
 import { mkdirSync } from 'node:fs';
 import { readdir } from 'node:fs/promises';
-const SCHEMA_VERSION = 4;
+import { ProjectionOutbox, SCHEMA_VERSION, } from './projection-outbox.js';
 function newerRecord(local, remote) {
     if (!local)
         return structuredClone(remote);
@@ -30,24 +30,10 @@ export function mergeInboundJobSnapshot(local, remote) {
     }
     return base;
 }
-function rowToProjection(row) {
-    return {
-        id: Number(row.id),
-        idempotencyKey: row.idempotency_key,
-        coalesceKey: row.coalesce_key,
-        operation: row.operation,
-        payload: JSON.parse(row.payload_json),
-        priority: Number(row.priority),
-        attempts: Number(row.attempts),
-        nextAttemptAt: row.next_attempt_at,
-        lastError: row.last_error,
-        createdAt: row.created_at,
-        updatedAt: row.updated_at,
-    };
-}
 export class SQLiteRelayStore {
     path;
     db;
+    outbox;
     constructor(path) {
         this.path = path;
         if (path !== ':memory:')
@@ -55,8 +41,8 @@ export class SQLiteRelayStore {
         this.db = new DatabaseSync(path);
         this.db.exec('PRAGMA journal_mode=WAL; PRAGMA synchronous=NORMAL; PRAGMA busy_timeout=5000; PRAGMA foreign_keys=ON;');
         this.migrate();
-        this.db.prepare("UPDATE projection_outbox SET status='pending', updated_at=? WHERE status='processing'")
-            .run(new Date().toISOString());
+        this.outbox = new ProjectionOutbox(this.db);
+        this.outbox.resetProcessing(new Date().toISOString());
     }
     migrate() {
         this.db.exec(`
@@ -87,60 +73,15 @@ export class SQLiteRelayStore {
         sequence INTEGER,
         received_at TEXT NOT NULL
       );
-      CREATE TABLE IF NOT EXISTS projection_outbox (
-        id INTEGER PRIMARY KEY AUTOINCREMENT,
-        idempotency_key TEXT NOT NULL UNIQUE,
-        coalesce_key TEXT,
-        operation TEXT NOT NULL,
-        payload_json TEXT NOT NULL,
-        priority INTEGER NOT NULL DEFAULT 0,
-        status TEXT NOT NULL DEFAULT 'pending' CHECK(status IN ('pending','processing','dead')),
-        attempts INTEGER NOT NULL DEFAULT 0,
-        next_attempt_at TEXT,
-        last_error TEXT,
-        created_at TEXT NOT NULL,
-        updated_at TEXT NOT NULL
-      );
-      CREATE INDEX IF NOT EXISTS projection_due_idx
-        ON projection_outbox(status, next_attempt_at, priority DESC, id);
-      CREATE INDEX IF NOT EXISTS projection_coalesce_idx
-        ON projection_outbox(coalesce_key, status);
+      ${ProjectionOutbox.createTableSql()}
+      ${ProjectionOutbox.createIndexSql()}
     `);
         const current = this.db.prepare("SELECT value FROM relay_meta WHERE key='schema_version'").get();
         const version = current?.value ? Number(current.value) : 0;
         if (version > SCHEMA_VERSION)
             throw new Error(`Relay store schema ${version} is newer than supported ${SCHEMA_VERSION}`);
-        if (version < 4) {
-            const schema = this.db.prepare("SELECT sql FROM sqlite_master WHERE type='table' AND name='projection_outbox'").get();
-            if (schema?.sql && !schema.sql.includes("'dead'")) {
-                this.db.exec(`
-          BEGIN IMMEDIATE;
-          DROP INDEX IF EXISTS projection_due_idx;
-          DROP INDEX IF EXISTS projection_coalesce_idx;
-          ALTER TABLE projection_outbox RENAME TO projection_outbox_v3;
-          CREATE TABLE projection_outbox (
-            id INTEGER PRIMARY KEY AUTOINCREMENT,
-            idempotency_key TEXT NOT NULL UNIQUE,
-            coalesce_key TEXT,
-            operation TEXT NOT NULL,
-            payload_json TEXT NOT NULL,
-            priority INTEGER NOT NULL DEFAULT 0,
-            status TEXT NOT NULL DEFAULT 'pending' CHECK(status IN ('pending','processing','dead')),
-            attempts INTEGER NOT NULL DEFAULT 0,
-            next_attempt_at TEXT,
-            last_error TEXT,
-            created_at TEXT NOT NULL,
-            updated_at TEXT NOT NULL
-          );
-          INSERT INTO projection_outbox(id,idempotency_key,coalesce_key,operation,payload_json,priority,status,attempts,next_attempt_at,last_error,created_at,updated_at)
-          SELECT id,idempotency_key,coalesce_key,operation,payload_json,priority,status,attempts,next_attempt_at,last_error,created_at,updated_at FROM projection_outbox_v3;
-          DROP TABLE projection_outbox_v3;
-          CREATE INDEX projection_due_idx ON projection_outbox(status, next_attempt_at, priority DESC, id);
-          CREATE INDEX projection_coalesce_idx ON projection_outbox(coalesce_key, status);
-          COMMIT;
-        `);
-            }
-        }
+        if (version < SCHEMA_VERSION)
+            ProjectionOutbox.upgrade(this.db, version);
         this.db.prepare("INSERT INTO relay_meta(key,value) VALUES('schema_version',?) ON CONFLICT(key) DO UPDATE SET value=excluded.value")
             .run(String(SCHEMA_VERSION));
     }
@@ -257,11 +198,14 @@ export class SQLiteRelayStore {
     `).run(eventId, stream, sequence, new Date().toISOString());
         return Number(result.changes) === 1;
     }
+    enqueueProjectionInTransaction(request, now) {
+        this.outbox.enqueue(request, now);
+    }
     async enqueueProjection(request) {
         const now = new Date().toISOString();
         this.db.exec('BEGIN IMMEDIATE');
         try {
-            this.enqueueProjectionInTransaction(request, now);
+            this.outbox.enqueue(request, now);
             this.db.exec('COMMIT');
         }
         catch (error) {
@@ -269,90 +213,24 @@ export class SQLiteRelayStore {
             throw error;
         }
     }
-    enqueueProjectionInTransaction(request, now) {
-        if (request.coalesceKey) {
-            this.db.prepare(`
-        DELETE FROM projection_outbox
-        WHERE coalesce_key=? AND status='pending' AND idempotency_key<>?
-      `).run(request.coalesceKey, request.idempotencyKey);
-        }
-        const existing = this.db.prepare('SELECT status FROM projection_outbox WHERE idempotency_key=?').get(request.idempotencyKey);
-        // A writer may be applying this key outside the transaction. Never rewrite its
-        // payload: its completion must only remove its own row, not a newer mutation.
-        const nextId = Number(this.db.prepare('SELECT COALESCE(MAX(id),0)+1 AS next_id FROM projection_outbox').get().next_id ?? 1);
-        const idempotencyKey = existing?.status === 'processing' || existing?.status === 'dead'
-            ? `${request.idempotencyKey}:queued:${nextId}`
-            : request.idempotencyKey;
-        this.db.prepare(`
-      INSERT INTO projection_outbox(
-        idempotency_key,coalesce_key,operation,payload_json,priority,status,
-        attempts,next_attempt_at,last_error,created_at,updated_at
-      ) VALUES(?,?,?,?,?,'pending',0,NULL,NULL,?,?)
-      ON CONFLICT(idempotency_key) DO UPDATE SET
-        coalesce_key=excluded.coalesce_key,
-        operation=excluded.operation,
-        payload_json=excluded.payload_json,
-        priority=MAX(projection_outbox.priority,excluded.priority),
-        status='pending',
-        next_attempt_at=NULL,
-        last_error=NULL,
-        updated_at=excluded.updated_at
-    `).run(idempotencyKey, request.coalesceKey ?? null, request.operation, JSON.stringify(request.payload), request.priority ?? 0, now, now);
-    }
     async claimDueProjections(limit = 50, now = new Date()) {
-        const observedAt = now.toISOString();
-        this.db.exec('BEGIN IMMEDIATE');
-        try {
-            const rows = this.db.prepare(`
-        SELECT id,idempotency_key,coalesce_key,operation,payload_json,priority,
-               attempts,next_attempt_at,last_error,created_at,updated_at
-        FROM projection_outbox
-        WHERE status='pending' AND (next_attempt_at IS NULL OR next_attempt_at<=?)
-        ORDER BY priority DESC, id ASC
-        LIMIT ?
-      `).all(observedAt, Math.max(1, Math.floor(limit)));
-            const mark = this.db.prepare("UPDATE projection_outbox SET status='processing', updated_at=? WHERE id=? AND status='pending'");
-            const claimed = [];
-            for (const row of rows) {
-                const result = mark.run(observedAt, row.id);
-                if (Number(result.changes) === 1)
-                    claimed.push({ ...row, updated_at: observedAt });
-            }
-            this.db.exec('COMMIT');
-            return claimed.map(rowToProjection);
-        }
-        catch (error) {
-            this.db.exec('ROLLBACK');
-            throw error;
-        }
-    }
-    async completeProjection(id) {
-        this.db.prepare('DELETE FROM projection_outbox WHERE id=?').run(id);
-    }
-    async retryProjection(id, error, nextAttemptAt) {
-        this.db.prepare(`
-      UPDATE projection_outbox
-      SET status='pending', attempts=attempts+1, next_attempt_at=?, last_error=?, updated_at=?
-      WHERE id=?
-    `).run(nextAttemptAt.toISOString(), error, new Date().toISOString(), id);
-    }
-    async deadLetterProjection(id, error) {
-        this.db.prepare(`
-      UPDATE projection_outbox
-      SET status='dead', attempts=attempts+1, next_attempt_at=NULL, last_error=?, updated_at=?
-      WHERE id=?
-    `).run(error, new Date().toISOString(), id);
-    }
-    async pendingProjectionCount() {
-        const row = this.db.prepare("SELECT COUNT(*) AS count FROM projection_outbox WHERE status IN ('pending','processing')").get();
-        return Number(row?.count ?? 0);
-    }
-    async terminalProjectionCount() {
-        const row = this.db.prepare("SELECT COUNT(*) AS count FROM projection_outbox WHERE status='dead'").get();
-        return Number(row?.count ?? 0);
+        return this.outbox.claimDue(limit, now);
     }
+    async completeProjection(id) { this.outbox.complete(id); }
+    async retryProjection(id, error, nextAttemptAt) { this.outbox.retry(id, error, nextAttemptAt); }
+    async deadLetterProjection(id, error) { this.outbox.deadLetter(id, error); }
+    async recordProjectionConflict(id, diagnostic) { this.outbox.recordConflict(id, diagnostic); }
+    async listProjectionConflicts() { return this.outbox.listConflicts(); }
+    async resolveProjectionConflict(id, resolution) { return this.outbox.resolveConflict(id, resolution); }
+    async conflictProjectionCount() { return this.outbox.conflictCount(); }
+    async pendingProjectionCount() { return this.outbox.pendingCount(); }
+    async terminalProjectionCount() { return this.outbox.terminalCount(); }
     close() { this.db.close(); }
 }
+/** Canonical on-disk Relay Store location for one managed GitHub pull request. */
+export function relayStorePath(directory, repository, prNumber) {
+    return directory + '/' + `${repository.replace('/', '_')}-${prNumber}.db`;
+}
 export async function discoverLocalRelayStoreSnapshots(directory) {
     let names;
     try {

package/dist/relayd.js

@@ -10,10 +10,11 @@ import { RepositoryWorkerPool, aggregateManagedGitHubJobs } from './pool.js';
 import { Reconciler } from './reconciler.js';
 import { dashboardManagedJobs, GitHubStore, InMemoryStore, loadManagedGitHubPullRequestSnapshotGraphql, withGitHubRequestContext } from './store.js';
 import { ProjectedDurableStore } from './projected-store.js';
-import { discoverLocalRelayStoreSnapshots, SQLiteRelayStore } from './relay-store.js';
+import { discoverLocalRelayStoreSnapshots, relayStorePath, SQLiteRelayStore } from './relay-store.js';
 import { githubAuthContext } from './github-auth.js';
 import { dashboardJobAction, isEntrypoint, runtimePlanner, runtimeReviewer, startService, SERVICE_DEFAULTS } from './cli.js';
 import { eventBusResolutionMessage, publishOrchestratorTaskCompletion, resolveEventBus } from './cli-support.js';
+import { eventFor } from './events.js';
 import { applyJobActivateAction } from './job-actions.js';
 import { applyOrchestratorCompleteAction } from './task-actions.js';
 import { dashboardJobSetState, dashboardTaskAction, dashboardTaskSetState } from './dashboard-actions.js';
@@ -63,6 +64,13 @@ Legacy single-job mode also accepts --repo OWNER/REPO --pr NUMBER --id JOB_ID.
 Examples:
   npx agents-relayd --repo OWNER/REPO
   npx agents-relayd --workspace ~/Workspace`;
+function firstStageChoices(decisionInput) {
+    const stages = decisionInput?.stages;
+    if (!Array.isArray(stages) || stages.length === 0)
+        return [];
+    const contract = stages[0].contract;
+    return Array.isArray(contract?.choices) ? contract.choices.filter((item) => typeof item === 'string') : [];
+}
 function value(args, name, fallback = '') { const index = args.indexOf(name); return index >= 0 ? args[index + 1] ?? fallback : fallback; }
 export function normalizeDaemonArguments(argv) {
     const repository = value(argv, '--repo') || null;
@@ -140,11 +148,17 @@ export async function runDaemon(argv) {
         const key = `${repository}#${prNumber}`;
         let relay = relayStores.get(key);
         if (!relay) {
-            relay = new SQLiteRelayStore(join(homedir(), '.agents-relay', 'stores', `${repository.replace('/', '_')}-${prNumber}.db`));
+            relay = new SQLiteRelayStore(relayStorePath(join(homedir(), '.agents-relay', 'stores'), repository, prNumber));
             relayStores.set(key, relay);
         }
         const github = new GitHubStore(client, repository, prNumber, trusted, seed);
-        const projected = new ProjectedDurableStore(relay, github, seed ?? null, (relatedRepository, relatedPrNumber) => runtimeStore(relatedRepository, relatedPrNumber));
+        const projected = new ProjectedDurableStore(relay, github, seed ?? null, (relatedRepository, relatedPrNumber) => runtimeStore(relatedRepository, relatedPrNumber), conflict => {
+            process.stderr.write(`projection conflict for ${repository}#${prNumber}: ${conflict.message} (fields: ${conflict.data.divergingFields.join(', ') || 'unknown'}; repair with agents-relay projection resolve)\n`);
+            if (bus) {
+                const jobId = conflict.data.jobId || conflictJobId(repository, prNumber);
+                void Promise.resolve().then(() => bus.publish(eventFor(jobId, 'projection', null, 'projection.conflict', 'blocked', conflict.message, 'orchestrator', { ...conflict.data, repository, prNumber }))).catch(() => undefined);
+            }
+        });
         projectionWriters.set(key, projected.projection);
         return projected;
     };
@@ -412,6 +426,9 @@ export async function runDaemon(argv) {
                 providers: usage.providers,
                 credits: usage.credits,
             },
+            effectiveChoices: result.audit?.contract?.effectiveChoices ?? [],
+            routingInstruction: result.audit?.contract?.routingInstruction ?? '',
+            mergedChoices: firstStageChoices(result.audit?.decision_input),
             decisionInput: result.audit?.decision_input ?? null,
             gates: result.audit?.gate_results ?? [],
         };
@@ -473,3 +490,6 @@ export async function runDaemon(argv) {
 }
 if (isEntrypoint(import.meta.url))
     runDaemon(process.argv.slice(2)).catch(error => { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; });
+function conflictJobId(repository, prNumber) {
+    return `${repository}#${prNumber}`;
+}

package/dist/router-evals.js

@@ -65,11 +65,11 @@ export async function runRouterEvals(engine, rulesPath) {
             user_input_rules: rules.text,
             runtime: { chatgpt_running: testCase.chatgptRunning ?? 0, preferred_chatgpt_concurrency: 10 },
             worker_candidates: workerCandidates,
-            routing_instruction: 'For each selected provider, use its default model and reasoning unless user_input_rules explicitly provides another model/reasoning option.',
+            routing_instruction: 'Choose one route from the merged choice list. Profile defaults and explicit [choices] have already been merged and hard-gated; do not invent additional routes.',
         }));
         const decision = await engine.decide({ facts }, {
             type: 'choice',
-            question: 'Choose one legal route. Each provider default is available. Additional model/reasoning routes exist only when explicitly provided by user_input_rules. Use context, code-plan quota, runtime load, and user_input_rules.',
+            question: 'Choose one legal route from the merged choice list. Each provider default is available; extra model/reasoning routes appear only when explicitly listed in [choices]. Use context, code-plan quota, runtime load, and routing_instruction.',
             choices,
         });
         if (decision.type !== 'choice')