ferrycat 0.3.2 → 0.4.0

package/dist/demo.js

@@ -0,0 +1,340 @@
+/**
+ * FerryCat Zero-Config Sandbox Demo (REQ-EXP-01).
+ *
+ * Runs a complete contract lifecycle — dispatch -> claim -> supervised execution -> TOCTOU
+ * re-verification -> COMPLETED — entirely inside an isolated temporary sandbox, so a brand-new
+ * user can see the deterministic handoff loop without configuring a single MCP server.
+ *
+ * Design constraints:
+ *  - Zero pollution: every artifact (sample source, handler script, SQLite database) lives under
+ *    `os.tmpdir()/ferrycat-demo-*`. The user's real workspace and `~/.ferrycat/mesh.db` are never touched.
+ *  - No simulation shortcuts on the engine path: the demo drives the exact same public APIs a real
+ *    daemon uses (`dispatchContract` / `pollNextTask` / `executeTaskAndFulfill` / `verifyContract`),
+ *    so a green demo is genuine evidence rather than a puppet show.
+ *  - Machine-readable mode: with `json: true` the function writes nothing to stdout and returns a
+ *    plain object, keeping CI/upstream automation parseable.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { FerryCatEngine } from './engine.js';
+import { executeTaskAndFulfill } from './supervisor.js';
+const TOTAL_STEPS = 4;
+const SAMPLE_REL_PATH = 'src/calc.ts';
+/**
+ * Sample source under review. Deliberately contains exactly one advisory-level defect
+ * (`==` instead of `===`) so the demo handler has something real to find and the verdict
+ * is deterministic across runs and platforms.
+ */
+const SAMPLE_SOURCE = `export function add(a: number, b: number): number {
+  return a + b;
+}
+
+export function divide(a: number, b: number): number {
+  if (b == 0) {
+    throw new Error('Division by zero');
+  }
+  return a / b;
+}
+
+export const VERSION = '1.0.0';
+`;
+/**
+ * Handler script written into the sandbox. It reads the contract from stdin (same protocol as
+ * scripts/review-handler.js), inspects the real pointer file on disk, then emits a delivery
+ * envelope on stdout. `execDelayMs` keeps the child alive long enough for the supervisor
+ * heartbeat ticker to fire at least once, so the demo can prove lease renewal is live.
+ */
+function buildHandlerScript(execDelayMs) {
+    return `/**
+ * FerryCat demo handler (generated by \`ferrycat-cli demo\`).
+ * Reads the contract JSON from stdin, inspects the pointer file, prints a delivery envelope.
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+
+const EXEC_DELAY_MS = ${execDelayMs};
+
+function inspect(workspaceRoot, pointers) {
+  const issues = [];
+  for (const pointer of pointers || []) {
+    const absPath = path.resolve(workspaceRoot, pointer.path);
+    if (!fs.existsSync(absPath)) {
+      issues.push(pointer.path + ': file is missing on disk');
+      continue;
+    }
+    const lines = fs.readFileSync(absPath, 'utf8').split(/\\r?\\n/);
+    lines.forEach((line, idx) => {
+      // Loose equality on a numeric/string guard is the classic review catch.
+      if (/(^|[^=!<>])==([^=]|$)/.test(line)) {
+        issues.push(pointer.path + ':' + (idx + 1) + " uses '==' instead of '===' (strict equality)");
+      }
+    });
+  }
+  return issues;
+}
+
+function main() {
+  const raw = fs.readFileSync(0, 'utf8');
+  if (!raw.trim()) {
+    console.error('demo handler: no contract payload received on stdin');
+    process.exit(1);
+  }
+  const contract = JSON.parse(raw);
+  const workspaceRoot = process.env.FERRYCAT_WORKSPACE_ROOT || process.cwd();
+  const issues = inspect(workspaceRoot, contract.pointers);
+
+  const finish = () => {
+    process.stdout.write(
+      JSON.stringify({
+        ok: true,
+        summary:
+          'Reviewed ' + (contract.pointers || []).length + ' file(s) for contract ' +
+          contract.contract_id + '; ' + issues.length + ' advisory finding(s).',
+        structured_output: {
+          passed: true,
+          issues,
+        },
+      }) + '\\n'
+    );
+  };
+
+  if (EXEC_DELAY_MS > 0) {
+    setTimeout(finish, EXEC_DELAY_MS);
+  } else {
+    finish();
+  }
+}
+
+main();
+`;
+}
+function makePainter(enabled) {
+    const wrap = (code) => (text) => enabled ? `\u001b[${code}m${text}\u001b[0m` : text;
+    return {
+        bold: wrap('1'),
+        dim: wrap('2'),
+        green: wrap('32'),
+        cyan: wrap('36'),
+        yellow: wrap('33'),
+        magenta: wrap('35'),
+        gray: wrap('90'),
+        red: wrap('31'),
+    };
+}
+function shortSha(sha) {
+    return sha.length <= 12 ? sha : `${sha.slice(0, 8)}...${sha.slice(-4)}`;
+}
+function removeSandbox(sandbox) {
+    // Windows keeps WAL/SHM handles briefly after close(); retries absorb that window.
+    fs.rmSync(sandbox, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
+}
+export async function runDemo(options = {}) {
+    const startedAt = Date.now();
+    const execDelayMs = Math.max(0, options.execDelayMs ?? 1900);
+    const execTtlSec = Math.max(2, options.execTtlSec ?? 5);
+    const human = !options.json;
+    const colorOn = options.color ?? (human && Boolean(process.stdout.isTTY) && !process.env.NO_COLOR);
+    const paint = makePainter(colorOn);
+    const write = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const say = (line = '') => {
+        if (human)
+            write(line);
+    };
+    const sandbox = fs.mkdtempSync(path.join(os.tmpdir(), 'ferrycat-demo-'));
+    let engine;
+    let succeeded = false;
+    const steps = [];
+    const warnings = [];
+    let heartbeatRenewals = 0;
+    let contractId = '';
+    let claimToken = '';
+    let status = 'UNKNOWN';
+    let verdict = 'PASSED';
+    let issues = [];
+    let dirtyFiles = 0;
+    const record = (index, title, fields) => {
+        steps.push({ index, total: TOTAL_STEPS, title, fields });
+        say('');
+        say(`  ${paint.green('✔')} ${paint.bold(`[${index}/${TOTAL_STEPS}] ${title}`)}`);
+        for (const [key, value] of Object.entries(fields)) {
+            say(`    ${paint.gray(key.padEnd(10))}${value}`);
+        }
+    };
+    try {
+        // ---------------------------------------------------------------------
+        // Sandbox scaffolding (isolated workspace + handler + SQLite database)
+        // ---------------------------------------------------------------------
+        const srcDir = path.join(sandbox, 'src');
+        fs.mkdirSync(srcDir, { recursive: true });
+        fs.writeFileSync(path.join(sandbox, SAMPLE_REL_PATH), SAMPLE_SOURCE, 'utf8');
+        const handlerPath = path.join(sandbox, 'demo-handler.cjs');
+        fs.writeFileSync(handlerPath, buildHandlerScript(execDelayMs), 'utf8');
+        engine = new FerryCatEngine({ dbPath: path.join(sandbox, 'demo-mesh.db') });
+        say('');
+        say(paint.bold('⚡ FerryCat Zero-Config Sandbox Demo ⚡'));
+        say(`${paint.gray('Sandbox:')} ${sandbox}`);
+        say(paint.gray('No MCP config. No daemon. Your real workspace and mesh.db are untouched.'));
+        // ---------------------------------------------------------------------
+        // [1/4] Dispatch — Antigravity locks the pointer fingerprint
+        // ---------------------------------------------------------------------
+        const dispatchRes = engine.dispatchContract({
+            requester_agent: 'antigravity',
+            target_agent: 'workbuddy',
+            task_type: 'code_review',
+            title: 'Review calc.ts for correctness and strict-equality hygiene',
+            context_summary: 'Sandbox demo contract. Inspect src/calc.ts and report any correctness or ' +
+                'strict-equality violations. This contract is generated by `ferrycat-cli demo`.',
+            workspace_root: sandbox,
+            pointers: [{ path: SAMPLE_REL_PATH }],
+            contract_schema: {
+                type: 'object',
+                properties: {
+                    passed: { type: 'boolean' },
+                    issues: { type: 'array', items: { type: 'string' } },
+                },
+                required: ['passed', 'issues'],
+                additionalProperties: false,
+            },
+            exec_ttl_sec: execTtlSec,
+        });
+        contractId = dispatchRes.contract_id;
+        const lockedFile = dispatchRes.files[0];
+        if (dispatchRes.warning) {
+            warnings.push(dispatchRes.warning);
+        }
+        record(1, 'Contract Dispatched', {
+            ID: contractId,
+            Actor: `antigravity -> workbuddy ${paint.dim('(task: code_review)')}`,
+            Locked: `${lockedFile.path} ${paint.dim(`(sha256: ${shortSha(lockedFile.sha256)})`)}`,
+            Status: `${paint.cyan('SUBMITTED')} ${paint.dim('-> queue')}`,
+        });
+        // ---------------------------------------------------------------------
+        // [2/4] Claim — WorkBuddy polls, verifies fingerprints, wins the CAS lease
+        // ---------------------------------------------------------------------
+        const pollRes = await engine.pollNextTask({ agent_id: 'workbuddy' });
+        if (!pollRes.has_task || !pollRes.contract || pollRes.status !== 'CLAIMED') {
+            throw new Error(`Demo claim failed: expected CLAIMED, got has_task=${pollRes.has_task} status=${pollRes.status ?? 'undefined'}. ` +
+                `${pollRes.message ?? ''}`.trim());
+        }
+        claimToken = pollRes.contract.claim_token ?? '';
+        const claimed = pollRes.contract;
+        record(2, 'Contract Claimed', {
+            Holder: claimed.target_agent,
+            Lease: claimToken || paint.yellow('(none)'),
+            Status: `${paint.dim('SUBMITTED ->')} ${paint.yellow('CLAIMED')}`,
+            Verify: `${paint.green('fingerprints matched')} ${paint.dim('(0 dirty files)')}`,
+        });
+        // ---------------------------------------------------------------------
+        // [3/4] Supervised execution — real child process, heartbeat, schema gate
+        // ---------------------------------------------------------------------
+        const execResult = await executeTaskAndFulfill(engine, claimed, { execFile: handlerPath }, {
+            onEvent: (event) => {
+                if (event.event === 'HEARTBEAT_RENEWED') {
+                    heartbeatRenewals += 1;
+                }
+            },
+        });
+        if (!execResult.ok) {
+            throw new Error(`Supervised execution failed: ${execResult.error ?? execResult.status}`);
+        }
+        // The authoritative delivery lives on the row, not on the fulfill ack.
+        const finalState = engine.inspectMeshState({ contract_id: contractId });
+        const finalRow = finalState.contracts[0] ?? {};
+        status = String(finalRow.status ?? 'UNKNOWN');
+        const structured = finalRow.structured_output;
+        if (structured && Array.isArray(structured.issues)) {
+            issues = structured.issues.map((item) => String(item));
+        }
+        verdict = issues.length > 0 ? 'CHANGES_REQUESTED' : 'PASSED';
+        record(3, 'Execution & Schema Check', {
+            Handler: `${path.basename(handlerPath)} ${paint.dim('(sandboxed child process)')}`,
+            Schema: `${paint.green('passed Ajv validation')}`,
+            Heartbeat: heartbeatRenewals > 0
+                ? `${paint.green(`${heartbeatRenewals} lease renewal(s)`)}`
+                : paint.dim('no renewal needed (short task)'),
+            Verdict: verdict === 'PASSED'
+                ? paint.green('PASSED')
+                : paint.yellow(`CHANGES_REQUESTED ${paint.dim(`(${issues.length} advisory)`)}`),
+        });
+        // ---------------------------------------------------------------------
+        // [4/4] Delivery — second TOCTOU pass then terminal COMPLETED
+        // ---------------------------------------------------------------------
+        const verifyRes = engine.verifyContract({
+            contract_id: contractId,
+            agent_id: 'workbuddy',
+        });
+        dirtyFiles = verifyRes.dirty_files.length;
+        if (!verifyRes.valid) {
+            throw new Error(`Demo TOCTOU re-verification failed: ${verifyRes.dirty_files.length} dirty file(s).`);
+        }
+        if (status !== 'COMPLETED') {
+            throw new Error(`Demo expected terminal status COMPLETED, got ${status}.`);
+        }
+        record(4, 'Contract Completed', {
+            TOCTOU: `${paint.green(`fingerprints matched (${dirtyFiles} dirty files)`)}`,
+            Final: `${paint.green(paint.bold('COMPLETED'))} ${paint.dim(`(elapsed: ${Date.now() - startedAt}ms)`)}`,
+            Findings: issues.length === 0
+                ? paint.dim('none')
+                : issues.map((item) => paint.dim(item)).join(`\n${' '.repeat(14)}`),
+        });
+        succeeded = true;
+        return {
+            ok: true,
+            sandbox,
+            sandbox_kept: Boolean(options.keep),
+            contract_id: contractId,
+            claim_token: claimToken,
+            status,
+            verdict,
+            issues,
+            dirty_files: dirtyFiles,
+            heartbeat_renewals: heartbeatRenewals,
+            elapsed_ms: Date.now() - startedAt,
+            steps,
+            warnings,
+        };
+    }
+    finally {
+        if (engine) {
+            try {
+                engine.close();
+            }
+            catch {
+                // Closing is best-effort; the sandbox removal below is the real cleanup contract.
+            }
+        }
+        const retainSandbox = Boolean(options.keep || !succeeded);
+        if (retainSandbox) {
+            if (options.keep) {
+                say('');
+                say(`${paint.gray('Sandbox kept at:')} ${sandbox}`);
+                say(paint.gray('  Inspect it with: sqlite3 "<sandbox>/demo-mesh.db" ".tables"'));
+            }
+        }
+        else {
+            try {
+                removeSandbox(sandbox);
+            }
+            catch (err) {
+                warnings.push(`Sandbox cleanup failed (${err instanceof Error ? err.message : String(err)}); remove "${sandbox}" manually.`);
+            }
+        }
+        if (succeeded) {
+            say('');
+            say(paint.green(paint.bold('  🎉 End-to-end multi-agent handoff verified successfully!')));
+            say('');
+            say(paint.bold('  Next steps:'));
+            say(`    ${paint.gray('•')} Add to your IDE:  ${paint.cyan('npx -y ferrycat')} ${paint.dim('(MCP server entry in mcpServers)')}`);
+            say(`    ${paint.gray('•')} Inspect contracts: ${paint.cyan('npx ferrycat inspect --target workbuddy')}`);
+            say(`    ${paint.gray('•')} Keep a sandbox:    ${paint.cyan('npx ferrycat demo --keep')}`);
+            say(`    ${paint.gray('•')} Full CLI help:     ${paint.cyan('npx ferrycat --help')}`);
+        }
+        else {
+            say('');
+            say(paint.red('  ✖ Demo did not reach a terminal COMPLETED state.'));
+            say(paint.gray(`    Sandbox retained for debugging: ${sandbox}`));
+        }
+    }
+}
+//# sourceMappingURL=demo.js.map

package/dist/demo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"demo.js","sourceRoot":"","sources":["../src/demo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,qBAAqB,EAAwB,MAAM,iBAAiB,CAAC;AAE9E,MAAM,WAAW,GAAG,CAAC,CAAC;AAEtB,MAAM,eAAe,GAAG,aAAa,CAAC;AAEtC;;;;GAIG;AACH,MAAM,aAAa,GAAG;;;;;;;;;;;;CAYrB,CAAC;AAEF;;;;;GAKG;AACH,SAAS,kBAAkB,CAAC,WAAmB;IAC7C,OAAO;;;;;;;wBAOe,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsDlC,CAAC;AACF,CAAC;AAwCD,SAAS,WAAW,CAAC,OAAgB;IACnC,MAAM,IAAI,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,IAAY,EAAE,EAAE,CAC9C,OAAO,CAAC,CAAC,CAAC,UAAU,IAAI,IAAI,IAAI,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC;IACrD,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC;QACf,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC;QACd,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC;QACjB,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC;QAChB,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC;QAClB,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC;QACnB,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC;QAChB,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC;KAChB,CAAC;AACJ,CAAC;AAED,SAAS,QAAQ,CAAC,GAAW;IAC3B,OAAO,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC1E,CAAC;AAED,SAAS,aAAa,CAAC,OAAe;IACpC,mFAAmF;IACnF,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC,CAAC;AACtF,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,UAAuB,EAAE;IACrD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC7B,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,WAAW,IAAI,IAAI,CAAC,CAAC;IAC7D,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,UAAU,IAAI,CAAC,CAAC,CAAC;IACxD,MAAM,KAAK,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC;IAC5B,MAAM,OAAO,GACX,OAAO,CAAC,KAAK,IAAI,CAAC,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACrF,MAAM,KAAK,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;IACnC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC,IAAY,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC;IACrF,MAAM,GAAG,GAAG,CAAC,IAAI,GAAG,EAAE,EAAE,EAAE;QACxB,IAAI,KAAK;YAAE,KAAK,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC,CAAC;IAEF,MAAM,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,gBAAgB,CAAC,CAAC,CAAC;IACzE,IAAI,MAAkC,CAAC;IACvC,IAAI,SAAS,GAAG,KAAK,CAAC;IAEtB,MAAM,KAAK,GAAqB,EAAE,CAAC;IACnC,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,IAAI,iBAAiB,GAAG,CAAC,CAAC;IAC1B,IAAI,UAAU,GAAG,EAAE,CAAC;IACpB,IAAI,UAAU,GAAG,EAAE,CAAC;IACpB,IAAI,MAAM,GAAG,SAAS,CAAC;IACvB,IAAI,OAAO,GAAmC,QAAQ,CAAC;IACvD,IAAI,MAAM,GAAa,EAAE,CAAC;IAC1B,IAAI,UAAU,GAAG,CAAC,CAAC;IAEnB,MAAM,MAAM,GAAG,CAAC,KAAa,EAAE,KAAa,EAAE,MAA8B,EAAE,EAAE;QAC9E,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;QACzD,GAAG,CAAC,EAAE,CAAC,CAAC;QACR,GAAG,CAAC,KAAK,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,WAAW,KAAK,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;QACjF,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAClD,GAAG,CAAC,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,EAAE,CAAC,CAAC;QACnD,CAAC;IACH,CAAC,CAAC;IAEF,IAAI,CAAC;QACH,wEAAwE;QACxE,uEAAuE;QACvE,wEAAwE;QACxE,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACzC,EAAE,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1C,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,eAAe,CAAC,EAAE,aAAa,EAAE,MAAM,CAAC,CAAC;QAC7E,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAAC;QAC3D,EAAE,CAAC,aAAa,CAAC,WAAW,EAAE,kBAAkB,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,CAAC;QAEvE,MAAM,GAAG,IAAI,cAAc,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,EAAE,CAAC,CAAC;QAE5E,GAAG,CAAC,EAAE,CAAC,CAAC;QACR,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,uCAAuC,CAAC,CAAC,CAAC;QACzD,GAAG,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,OAAO,EAAE,CAAC,CAAC;QAC5C,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,0EAA0E,CAAC,CAAC,CAAC;QAE5F,wEAAwE;QACxE,6DAA6D;QAC7D,wEAAwE;QACxE,MAAM,WAAW,GAAG,MAAM,CAAC,gBAAgB,CAAC;YAC1C,eAAe,EAAE,aAAa;YAC9B,YAAY,EAAE,WAAW;YACzB,SAAS,EAAE,aAAa;YACxB,KAAK,EAAE,4DAA4D;YACnE,eAAe,EACb,2EAA2E;gBAC3E,gFAAgF;YAClF,cAAc,EAAE,OAAO;YACvB,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC;YACrC,eAAe,EAAE;gBACf,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;oBAC3B,MAAM,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE;iBACrD;gBACD,QAAQ,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC;gBAC9B,oBAAoB,EAAE,KAAK;aAC5B;YACD,YAAY,EAAE,UAAU;SACzB,CAAC,CAAC;QACH,UAAU,GAAG,WAAW,CAAC,WAAW,CAAC;QACrC,MAAM,UAAU,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QACxC,IAAI,WAAW,CAAC,OAAO,EAAE,CAAC;YACxB,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QACrC,CAAC;QAED,MAAM,CAAC,CAAC,EAAE,qBAAqB,EAAE;YAC/B,EAAE,EAAE,UAAU;YACd,KAAK,EAAE,4BAA4B,KAAK,CAAC,GAAG,CAAC,qBAAqB,CAAC,EAAE;YACrE,MAAM,EAAE,GAAG,UAAU,CAAC,IAAI,IAAI,KAAK,CAAC,GAAG,CAAC,YAAY,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE;YACrF,MAAM,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE;SAC9D,CAAC,CAAC;QAEH,wEAAwE;QACxE,2EAA2E;QAC3E,wEAAwE;QACxE,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC,CAAC;QACrE,IAAI,CAAC,OAAO,CAAC,QAAQ,IAAI,CAAC,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC3E,MAAM,IAAI,KAAK,CACb,qDAAqD,OAAO,CAAC,QAAQ,WAAW,OAAO,CAAC,MAAM,IAAI,WAAW,IAAI;gBAC/G,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CACpC,CAAC;QACJ,CAAC;QACD,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC,WAAW,IAAI,EAAE,CAAC;QAChD,MAAM,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC;QAEjC,MAAM,CAAC,CAAC,EAAE,kBAAkB,EAAE;YAC5B,MAAM,EAAE,OAAO,CAAC,YAAY;YAC5B,KAAK,EAAE,UAAU,IAAI,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC;YAC3C,MAAM,EAAE,GAAG,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE;YACjE,MAAM,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,sBAAsB,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC,EAAE;SACjF,CAAC,CAAC;QAEH,wEAAwE;QACxE,0EAA0E;QAC1E,wEAAwE;QACxE,MAAM,UAAU,GAAG,MAAM,qBAAqB,CAC5C,MAAM,EACN,OAAqC,EACrC,EAAE,QAAQ,EAAE,WAAW,EAAE,EACzB;YACE,OAAO,EAAE,CAAC,KAA8B,EAAE,EAAE;gBAC1C,IAAI,KAAK,CAAC,KAAK,KAAK,mBAAmB,EAAE,CAAC;oBACxC,iBAAiB,IAAI,CAAC,CAAC;gBACzB,CAAC;YACH,CAAC;SACF,CACF,CAAC;QAEF,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CAAC,gCAAgC,UAAU,CAAC,KAAK,IAAI,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC;QAC3F,CAAC;QAED,uEAAuE;QACvE,MAAM,UAAU,GAAG,MAAM,CAAC,gBAAgB,CAAC,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC,CAAC;QACxE,MAAM,QAAQ,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAC/C,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,IAAI,SAAS,CAAC,CAAC;QAC9C,MAAM,UAAU,GAAG,QAAQ,CAAC,iBAA+D,CAAC;QAC5F,IAAI,UAAU,IAAI,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YACnD,MAAM,GAAI,UAAU,CAAC,MAAoB,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;QACxE,CAAC;QACD,OAAO,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,QAAQ,CAAC;QAE7D,MAAM,CAAC,CAAC,EAAE,0BAA0B,EAAE;YACpC,OAAO,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,2BAA2B,CAAC,EAAE;YAClF,MAAM,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,uBAAuB,CAAC,EAAE;YACjD,SAAS,EAAE,iBAAiB,GAAG,CAAC;gBAC9B,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,iBAAiB,mBAAmB,CAAC,EAAE;gBAC3D,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,gCAAgC,CAAC;YAC/C,OAAO,EAAE,OAAO,KAAK,QAAQ;gBAC3B,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC;gBACvB,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,qBAAqB,KAAK,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC,MAAM,YAAY,CAAC,EAAE,CAAC;SAClF,CAAC,CAAC;QAEH,wEAAwE;QACxE,8DAA8D;QAC9D,wEAAwE;QACxE,MAAM,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC;YACtC,WAAW,EAAE,UAAU;YACvB,QAAQ,EAAE,WAAW;SACtB,CAAC,CAAC;QACH,UAAU,GAAG,SAAS,CAAC,WAAW,CAAC,MAAM,CAAC;QAC1C,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CACb,uCAAuC,SAAS,CAAC,WAAW,CAAC,MAAM,iBAAiB,CACrF,CAAC;QACJ,CAAC;QAED,IAAI,MAAM,KAAK,WAAW,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,gDAAgD,MAAM,GAAG,CAAC,CAAC;QAC7E,CAAC;QAED,MAAM,CAAC,CAAC,EAAE,oBAAoB,EAAE;YAC9B,MAAM,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,yBAAyB,UAAU,eAAe,CAAC,EAAE;YAC5E,KAAK,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,aAAa,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,KAAK,CAAC,EAAE;YACvG,QAAQ,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC;gBAC3B,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC;gBACnB,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;SACtE,CAAC,CAAC;QAEH,SAAS,GAAG,IAAI,CAAC;QACjB,OAAO;YACL,EAAE,EAAE,IAAI;YACR,OAAO;YACP,YAAY,EAAE,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC;YACnC,WAAW,EAAE,UAAU;YACvB,WAAW,EAAE,UAAU;YACvB,MAAM;YACN,OAAO;YACP,MAAM;YACN,WAAW,EAAE,UAAU;YACvB,kBAAkB,EAAE,iBAAiB;YACrC,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;YAClC,KAAK;YACL,QAAQ;SACT,CAAC;IACJ,CAAC;YAAS,CAAC;QACT,IAAI,MAAM,EAAE,CAAC;YACX,IAAI,CAAC;gBACH,MAAM,CAAC,KAAK,EAAE,CAAC;YACjB,CAAC;YAAC,MAAM,CAAC;gBACP,kFAAkF;YACpF,CAAC;QACH,CAAC;QAED,MAAM,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC;QAC1D,IAAI,aAAa,EAAE,CAAC;YAClB,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;gBACjB,GAAG,CAAC,EAAE,CAAC,CAAC;gBACR,GAAG,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,kBAAkB,CAAC,IAAI,OAAO,EAAE,CAAC,CAAC;gBACpD,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,+DAA+D,CAAC,CAAC,CAAC;YACnF,CAAC;QACH,CAAC;aAAM,CAAC;YACN,IAAI,CAAC;gBACH,aAAa,CAAC,OAAO,CAAC,CAAC;YACzB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,QAAQ,CAAC,IAAI,CACX,2BAA2B,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,cAAc,OAAO,aAAa,CAC9G,CAAC;YACJ,CAAC;QACH,CAAC;QAED,IAAI,SAAS,EAAE,CAAC;YACd,GAAG,CAAC,EAAE,CAAC,CAAC;YACR,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,4DAA4D,CAAC,CAAC,CAAC,CAAC;YAC3F,GAAG,CAAC,EAAE,CAAC,CAAC;YACR,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC;YACjC,GAAG,CAAC,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,sBAAsB,KAAK,CAAC,IAAI,CAAC,iBAAiB,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,kCAAkC,CAAC,EAAE,CAAC,CAAC;YAClI,GAAG,CAAC,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,uBAAuB,KAAK,CAAC,IAAI,CAAC,yCAAyC,CAAC,EAAE,CAAC,CAAC;YAC1G,GAAG,CAAC,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,uBAAuB,KAAK,CAAC,IAAI,CAAC,0BAA0B,CAAC,EAAE,CAAC,CAAC;YAC3F,GAAG,CAAC,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,uBAAuB,KAAK,CAAC,IAAI,CAAC,qBAAqB,CAAC,EAAE,CAAC,CAAC;QACxF,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,EAAE,CAAC,CAAC;YACR,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,oDAAoD,CAAC,CAAC,CAAC;YACrE,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,uCAAuC,OAAO,EAAE,CAAC,CAAC,CAAC;QACpE,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/engine.d.ts

@@ -1,4 +1,4 @@
-import type { DispatchContractInput, DispatchContractResult, ExtendTtlInput, ExtendTtlResult, FailContractInput, FailContractResult, FulfillContractInput, FulfillContractResult, InspectMeshStateInput, PollNextTaskInput, PollNextTaskResult, ReleaseContractInput, ReleaseContractResult, TaskType, VerifyContractInput, VerifyContractResult } from './types.js';
+import type { AcquireDaemonLeaseInput, AcquireDaemonLeaseResult, DaemonLockRow, DispatchContractInput, DispatchContractResult, ExtendTtlInput, ExtendTtlResult, FailContractInput, FailContractResult, FulfillContractInput, FulfillContractResult, InspectMeshStateInput, PollNextTaskInput, PollNextTaskResult, ReleaseContractInput, ReleaseContractResult, ReleaseDaemonLeaseInput, ReleaseDaemonLeaseResult, RenewDaemonLeaseInput, RenewDaemonLeaseResult, TaskType, VerifyContractInput, VerifyContractResult } from './types.js';
 /** Default queue window (SUBMITTED) in seconds. */
 export declare const DEFAULT_QUEUE_TTL_SEC = 1800;
 /**
@@ -85,6 +85,30 @@ export declare class FerryCatEngine {
      * (created_at + LIFETIME_QUEUE_TTL_MULTIPLIER * queue_ttl_sec).
      */
     extendTtl(input: ExtendTtlInput, nowMs?: number): ExtendTtlResult;
+    /**
+     * Read-only lease snapshot used by the execution supervisor (Phase 3 Step 0, CK-03) to
+     * re-read row state after an optimistic-lock conflict instead of crashing the worker.
+     * Never mutates state.
+     */
+    getLeaseSnapshot(contractId: string): {
+        status: string;
+        claim_token: string | null;
+        claimed_at: number | null;
+        exec_ttl_sec: number;
+        extend_count: number;
+    } | null;
+    /**
+     * Persist partial worker output into salvaged_result_json WITHOUT any status transition
+     * (Phase 3 Step 0, CK-07 / CK-09). Allowed for the lease holder while CLAIMED, and also
+     * right after the window closed (TIMED_OUT) so produced output is never silently dropped.
+     * Returns false when the caller no longer owns the lease (no write happens).
+     */
+    recordSalvage(input: {
+        contract_id: string;
+        agent_id?: string;
+        claim_token?: string;
+        salvage: Record<string, unknown>;
+    }): boolean;
     /**
      * CLAIMED -> FAILED (terminal). Lets the holder close the loop explicitly instead of
      * leaving the requester waiting for the execution TTL to expire.
@@ -103,5 +127,9 @@ export declare class FerryCatEngine {
         total_returned: number;
         contracts: Array<Record<string, unknown>>;
     };
+    acquireDaemonLease(input: AcquireDaemonLeaseInput): AcquireDaemonLeaseResult;
+    renewDaemonLease(input: RenewDaemonLeaseInput): RenewDaemonLeaseResult;
+    releaseDaemonLease(input: ReleaseDaemonLeaseInput): ReleaseDaemonLeaseResult;
+    inspectDaemonLease(lockId?: string): DaemonLockRow | null;
     close(): void;
 }