wyrm-mcp 7.2.0 → 7.2.2

package/dist/daemon-write-endpoint.js

@@ -1,290 +1 @@
-/**
- * Daemon-as-writer endpoint logic (v7 F2, T012) — the `POST /write` op surface.
- *
- * When a client process runs with WYRM_DAEMON_WRITES=1 (src/daemon-writer.ts),
- * its CANONICAL WRITES are routed over loopback HTTP to the running daemon
- * (http-fast), which executes them here against ITS database connection —
- * funneling a fleet's writes through one process instead of N contending ones.
- * Reads always stay local to the client.
- *
- * Extracted from http-fast.ts in the readonly-gate.ts style: DB-parameterized
- * and side-effect-free at module load, so the op surface is unit-testable
- * without booting the HTTP server.
- *
- * Article VII — minimal request surface, validated at the boundary:
- * - ONE endpoint, a CLOSED op allowlist (DAEMON_WRITE_OPS). Unknown ops are
- *   rejected; there is deliberately no generic "run this SQL/method" escape.
- * - Each op calls the SAME domain method the client's direct path would call
- *   (db.insertData / failures.record / truths.set / artifacts.add /
- *   db.addQuest), so row shapes are identical in both modes.
- * - `project_id` is a plain integer id: client and daemon share the same
- *   database file, so ids are stable across the loopback hop. Project-path
- *   resolution (a read) happens client-side.
- * - Enum-ish fields (scope/severity/kind/...) are NOT re-validated here beyond
- *   type checks: the domain methods + the schema CHECK constraints are the
- *   single source of truth for value validation in BOTH modes — re-implementing
- *   the lists here would let the two paths drift. A CHECK/FK violation comes
- *   back to the client as the rejected `{e}` shape (see handleDaemonWrite's
- *   error mapping), never a generic 500 the client would have to treat as
- *   commit-state-unknown.
- *
- * Attribution (v7 F2 review fix): the caller's FULL envelope rides in the
- * request body as `actor: {agent_id, run_id}` — the `Wyrm-Actor` header
- * grammar (`agent_id[;run_id]`) cannot express a run-only envelope, so a
- * header-only hop silently dropped run attribution and let the DAEMON's own
- * env (http-fast's env-level resolution) stamp the caller's row — flipping
- * the T014 quarantine tier (a run-quarantined failure could land
- * project-wide, or an unattributed write could be quarantined to an
- * unrelated run). When the body carries `actor`, it is AUTHORITATIVE: the
- * write runs inside that exact envelope ('param' level), and both-null is an
- * EXPLICIT legacy envelope (columns stay NULL) — the daemon's env can never
- * bleed in. Bodies without `actor` (pre-fix clients) keep the ambient
- * header/env semantics.
- *
- * Idempotency (v7 F2 review fix): the client mints a ULID `write_id` per
- * logical write. Committed write_ids are remembered in an in-memory ledger
- * with TIME-BASED retention (DEDUP_TTL_MS — sized to the realistic caller
- * retry horizon: the instructed retry round-trips through an LLM agent whose
- * next turn is seconds to minutes away, NOT a protocol-bounded window); a
- * duplicate write_id inside the horizon REPLAYS the committed result instead
- * of re-executing — so the client's timeout re-send / instructed retry cannot
- * land a second row (the at-least-once duplicate the adversarial review
- * confirmed). The count cap (DEDUP_CAP) is a memory backstop only — under a
- * sustained fleet burst it, not time, may evict first. Documented residual
- * at-least-once windows: a daemon RESTART loses the ledger, and a retry
- * arriving past the retention horizon (TTL or backstop eviction) re-executes
- * — a VISIBLE fresh execution, never a silent stale replay.
- *
- * Privacy: ops write through the normal domain methods, so the Live Memory
- * surface is unchanged — failure events stay reference-only (is_shared=0).
- *
- * @copyright 2026 Ghost Protocol (Pvt) Ltd.
- * @license AGPL-3.0-or-later — dual-licensed; commercial terms: ghosts.lk@proton.me. See LICENSE.
- */
-import { isSqliteConstraintError } from './sqlite-busy.js';
-import { LEGACY_ENVELOPE, runWithActor, sanitizeActorId, } from './handlers/boundary.js';
-/**
- * The closed op allowlist — the four canonical write paths of spec FR-1
- * (data-lake insert, failure_record, truth_set, capture), where `capture`
- * decomposes into the three writes wyrm_capture can perform (quest_add /
- * truth_set / artifact_add). Anything else stays on the client's direct path.
- */
-export const DAEMON_WRITE_OPS = [
-    'data_insert',
-    'failure_record',
-    'truth_set',
-    'artifact_add',
-    'quest_add',
-];
-export function isDaemonWriteOp(value) {
-    return typeof value === 'string' && DAEMON_WRITE_OPS.includes(value);
-}
-/** Boundary check: a finite positive integer id (project ids are rowids). */
-function asProjectId(value) {
-    return typeof value === 'number' && Number.isInteger(value) && value > 0 ? value : null;
-}
-function asString(value) {
-    return typeof value === 'string' && value.length > 0 ? value : null;
-}
-// ── idempotency ledger (v7 F2 review fix) ───────────────────────────────────
-// write_id → the committed result, replayed on duplicate delivery. Retention
-// is TIME-based: the caller-level instructed retry round-trips through an LLM
-// agent (seconds to minutes — retry_after_ms is advice, not a bound), so a
-// count-FIFO sized to "seconds-scale" gets evicted from under a live retry by
-// any >cap fleet burst in that gap — re-executing a committed write_id, a
-// duplicate with no daemon crash. Entries live DEDUP_TTL_MS; expired entries
-// are swept on insert (insertion order is commit order, so they cluster at
-// the front). DEDUP_CAP remains only as a memory backstop ({ulid, small row}
-// entries are tiny). Only SUCCESSFUL (committed) results are remembered — a
-// rejected/thrown write left nothing behind, so re-executing it is correct.
-export const DEDUP_TTL_MS = 10 * 60_000;
-const DEDUP_CAP = 4096;
-const committedWrites = new Map();
-/** Test hook: clear the idempotency ledger between cases. */
-export function _resetDaemonWriteDedupForTests() {
-    committedWrites.clear();
-}
-/** Test hook: age every ledger entry by `ms` (drives TTL eviction without a clock). */
-export function _ageDaemonWriteDedupForTests(ms) {
-    for (const entry of committedWrites.values())
-        entry.committedAt -= ms;
-}
-function rememberCommitted(writeId, result) {
-    const now = Date.now();
-    // Age sweep first: retention is the TTL; the count cap below is only the
-    // memory backstop. committedAt is non-decreasing in insertion order, so the
-    // sweep stops at the first fresh entry.
-    for (const [id, entry] of committedWrites) {
-        if (now - entry.committedAt < DEDUP_TTL_MS)
-            break;
-        committedWrites.delete(id);
-    }
-    if (!committedWrites.has(writeId) && committedWrites.size >= DEDUP_CAP) {
-        const oldest = committedWrites.keys().next().value;
-        if (oldest !== undefined)
-            committedWrites.delete(oldest);
-    }
-    committedWrites.set(writeId, { result, committedAt: now });
-}
-/** Boundary check for the client-minted idempotency key (a 26-char ULID; the
- * bound mirrors sanitizeActorId's 64-char ceiling). Absent/invalid → no dedup
- * (the pre-fix client shape). */
-function asWriteId(value) {
-    return typeof value === 'string' && value.length > 0 && value.length <= 64 ? value : null;
-}
-/**
- * Execute one allowlisted write op. Returns the written row on success or a
- * compact `{ e }` error (the house wire format for http-fast routes).
- *
- * Error mapping by what the throw PROVES about the commit:
- * - SQLITE_CONSTRAINT family (CHECK/FK/UNIQUE/NOT NULL) → the rejected `{e}`
- *   shape carrying the real constraint message. Every op is a single
- *   statement or one IMMEDIATE transaction, so a constraint throw proves the
- *   rollback — the client safely fails direct and the local path surfaces
- *   the same deterministic error to the caller. Without this, a generic 500
- *   reads as commit-state-unknown and the same inputs re-violate forever.
- * - Everything else (SQLITE_BUSY → http-fast's structured 503; SQLITE_FULL,
- *   a post-commit throw, ...) propagates — the dispatcher catch owns
- *   transport mapping, and a non-constraint throw does NOT prove no commit,
- *   so it must never claim the rejected shape.
- */
-export function handleDaemonWrite(deps, args) {
-    const op = args.op;
-    if (!isDaemonWriteOp(op))
-        return { e: 'unknown op' };
-    const input = (args.input ?? {});
-    const projectId = asProjectId(args.project_id);
-    // Idempotent replay: this write_id already committed — the response was
-    // lost in flight. Hand back the SAME row; never execute twice. No age check
-    // on read: an old committed result is still the truth (the TTL governs
-    // memory retention, not correctness).
-    const writeId = asWriteId(args.write_id);
-    if (writeId !== null) {
-        const replay = committedWrites.get(writeId);
-        if (replay !== undefined)
-            return replay.result;
-    }
-    // Body-supplied attribution is authoritative for the forwarded write (see
-    // the module header): sanitize at the boundary, run the op inside that
-    // exact envelope. Both-null → the EXPLICIT legacy envelope (NULL columns) —
-    // never the daemon's own env. No `actor` field at all → pre-fix client:
-    // keep the ambient (header/env) semantics unchanged.
-    let result;
-    try {
-        const actorRaw = args.actor;
-        if (actorRaw !== undefined && actorRaw !== null && typeof actorRaw === 'object') {
-            const a = actorRaw;
-            const agent = sanitizeActorId(a.agent_id);
-            const run = sanitizeActorId(a.run_id);
-            const envelope = agent === null && run === null
-                ? LEGACY_ENVELOPE
-                : { agent_id: agent, run_id: run, source: 'param' };
-            result = runWithActor(envelope, () => executeDaemonOp(deps, op, projectId, args.project_id, input));
-        }
-        else {
-            result = executeDaemonOp(deps, op, projectId, args.project_id, input);
-        }
-    }
-    catch (err) {
-        // Deterministic domain rejection — provably rolled back (see the function
-        // doc). Carry the real message so the caller's direct-path retry of the
-        // same inputs reproduces a NAMED error, not a mystery 500.
-        if (isSqliteConstraintError(err)) {
-            return { e: err instanceof Error ? err.message : String(err) };
-        }
-        // BUSY (the structured 503 contract) and anything that might have
-        // committed stay on the throw path — never claim "no commit" for them.
-        throw err;
-    }
-    // Remember only COMMITTED outcomes (post-commit by construction: the domain
-    // method returned synchronously above).
-    if (writeId !== null && 'ok' in result && result.ok === true) {
-        rememberCommitted(writeId, result);
-    }
-    return result;
-}
-function executeDaemonOp(deps, op, projectId, rawProjectId, input) {
-    switch (op) {
-        case 'data_insert': {
-            if (projectId === null)
-                return { e: 'project_id required' };
-            const category = asString(input.category);
-            const key = asString(input.key);
-            const value = asString(input.value);
-            if (!category || !key || !value)
-                return { e: 'category, key, value required' };
-            // value arrives client-prepared (sanitized + maybeEncrypt'ed): the
-            // encryption key stays in the CLIENT process (Article VII — the daemon
-            // never needs WYRM_ENCRYPTION_KEY to serve writes).
-            const row = deps.db.insertData(projectId, category, key, value, input.metadata);
-            return { ok: true, op, row };
-        }
-        case 'failure_record': {
-            // project_id may be null here: global (cross-project) failures are legal.
-            if (rawProjectId != null && projectId === null)
-                return { e: 'project_id must be an integer' };
-            const target = asString(input.target);
-            const description = asString(input.description);
-            const scope = asString(input.scope);
-            if (!scope || !target || !description)
-                return { e: 'scope, target, description required' };
-            const row = deps.failures.record({
-                project_id: projectId,
-                scope: scope,
-                target,
-                description,
-                why_failed: typeof input.why_failed === 'string' ? input.why_failed : undefined,
-                severity: typeof input.severity === 'string' ? input.severity : undefined,
-            });
-            return { ok: true, op, row };
-        }
-        case 'truth_set': {
-            if (projectId === null)
-                return { e: 'project_id required' };
-            const category = asString(input.category);
-            const key = asString(input.key);
-            const value = asString(input.value);
-            if (!category || !key || !value)
-                return { e: 'category, key, value required' };
-            const row = deps.truths.set(projectId, {
-                category, key, value,
-                rationale: typeof input.rationale === 'string' ? input.rationale : undefined,
-                source: typeof input.source === 'string' ? input.source : undefined,
-                confidence: typeof input.confidence === 'number' ? input.confidence : undefined,
-                ttl_days: typeof input.ttl_days === 'number' ? input.ttl_days : undefined,
-            });
-            return { ok: true, op, row };
-        }
-        case 'artifact_add': {
-            if (projectId === null)
-                return { e: 'project_id required' };
-            const kind = asString(input.kind);
-            const problem = asString(input.problem);
-            if (!kind || !problem)
-                return { e: 'kind, problem required' };
-            const row = deps.artifacts.add(projectId, {
-                kind, problem,
-                constraints: typeof input.constraints === 'string' ? input.constraints : undefined,
-                validatedFix: typeof input.validatedFix === 'string' ? input.validatedFix : undefined,
-                whyItWorked: typeof input.whyItWorked === 'string' ? input.whyItWorked : undefined,
-                outcome: typeof input.outcome === 'string' ? input.outcome : undefined,
-                sourceSessionId: typeof input.sourceSessionId === 'number' ? input.sourceSessionId : undefined,
-                tags: Array.isArray(input.tags) ? input.tags.filter((t) => typeof t === 'string') : undefined,
-                confidence: typeof input.confidence === 'number' ? input.confidence : undefined,
-                createdBy: typeof input.createdBy === 'string' ? input.createdBy : undefined,
-                needsReview: typeof input.needsReview === 'number' ? input.needsReview : undefined,
-            });
-            return { ok: true, op, row };
-        }
-        case 'quest_add': {
-            if (projectId === null)
-                return { e: 'project_id required' };
-            const title = asString(input.title);
-            if (!title)
-                return { e: 'title required' };
-            const row = deps.db.addQuest(projectId, title, typeof input.description === 'string' ? input.description : undefined, (typeof input.priority === 'string' ? input.priority : 'medium'), typeof input.tags === 'string' ? input.tags : undefined);
-            return { ok: true, op, row };
-        }
-    }
-}
-//# sourceMappingURL=daemon-write-endpoint.js.map
+import{isSqliteConstraintError as _}from"./sqlite-busy.js";import{LEGACY_ENVELOPE as g,runWithActor as k,sanitizeActorId as y}from"./handlers/boundary.js";const w=["data_insert","failure_record","truth_set","artifact_add","quest_add"];function h(t){return typeof t=="string"&&w.includes(t)}function b(t){return typeof t=="number"&&Number.isInteger(t)&&t>0?t:null}function d(t){return typeof t=="string"&&t.length>0?t:null}const D=10*6e4,q=4096,f=new Map;function S(){f.clear()}function P(t){for(const i of f.values())i.committedAt-=t}function x(t,i){const s=Date.now();for(const[a,e]of f){if(s-e.committedAt<D)break;f.delete(a)}if(!f.has(t)&&f.size>=q){const a=f.keys().next().value;a!==void 0&&f.delete(a)}f.set(t,{result:i,committedAt:s})}function W(t){return typeof t=="string"&&t.length>0&&t.length<=64?t:null}function F(t,i){const s=i.op;if(!h(s))return{e:"unknown op"};const a=i.input??{},e=b(i.project_id),o=W(i.write_id);if(o!==null){const r=f.get(o);if(r!==void 0)return r.result}let n;try{const r=i.actor;if(r!=null&&typeof r=="object"){const c=r,u=y(c.agent_id),l=y(c.run_id);n=k(u===null&&l===null?g:{agent_id:u,run_id:l,source:"param"},()=>m(t,s,e,i.project_id,a))}else n=m(t,s,e,i.project_id,a)}catch(r){if(_(r))return{e:r instanceof Error?r.message:String(r)};throw r}return o!==null&&"ok"in n&&n.ok===!0&&x(o,n),n}function m(t,i,s,a,e){switch(i){case"data_insert":{if(s===null)return{e:"project_id required"};const o=d(e.category),n=d(e.key),r=d(e.value);if(!o||!n||!r)return{e:"category, key, value required"};const c=t.db.insertData(s,o,n,r,e.metadata);return{ok:!0,op:i,row:c}}case"failure_record":{if(a!=null&&s===null)return{e:"project_id must be an integer"};const o=d(e.target),n=d(e.description),r=d(e.scope);if(!r||!o||!n)return{e:"scope, target, description required"};const c=t.failures.record({project_id:s,scope:r,target:o,description:n,why_failed:typeof e.why_failed=="string"?e.why_failed:void 0,severity:typeof e.severity=="string"?e.severity:void 0});return{ok:!0,op:i,row:c}}case"truth_set":{if(s===null)return{e:"project_id required"};const o=d(e.category),n=d(e.key),r=d(e.value);if(!o||!n||!r)return{e:"category, key, value required"};const c=t.truths.set(s,{category:o,key:n,value:r,rationale:typeof e.rationale=="string"?e.rationale:void 0,source:typeof e.source=="string"?e.source:void 0,confidence:typeof e.confidence=="number"?e.confidence:void 0,ttl_days:typeof e.ttl_days=="number"?e.ttl_days:void 0});return{ok:!0,op:i,row:c}}case"artifact_add":{if(s===null)return{e:"project_id required"};const o=d(e.kind),n=d(e.problem);if(!o||!n)return{e:"kind, problem required"};const r=t.artifacts.add(s,{kind:o,problem:n,constraints:typeof e.constraints=="string"?e.constraints:void 0,validatedFix:typeof e.validatedFix=="string"?e.validatedFix:void 0,whyItWorked:typeof e.whyItWorked=="string"?e.whyItWorked:void 0,outcome:typeof e.outcome=="string"?e.outcome:void 0,sourceSessionId:typeof e.sourceSessionId=="number"?e.sourceSessionId:void 0,tags:Array.isArray(e.tags)?e.tags.filter(c=>typeof c=="string"):void 0,confidence:typeof e.confidence=="number"?e.confidence:void 0,createdBy:typeof e.createdBy=="string"?e.createdBy:void 0,needsReview:typeof e.needsReview=="number"?e.needsReview:void 0});return{ok:!0,op:i,row:r}}case"quest_add":{if(s===null)return{e:"project_id required"};const o=d(e.title);if(!o)return{e:"title required"};const n=t.db.addQuest(s,o,typeof e.description=="string"?e.description:void 0,typeof e.priority=="string"?e.priority:"medium",typeof e.tags=="string"?e.tags:void 0);return{ok:!0,op:i,row:n}}}}export{w as DAEMON_WRITE_OPS,D as DEDUP_TTL_MS,P as _ageDaemonWriteDedupForTests,S as _resetDaemonWriteDedupForTests,F as handleDaemonWrite,h as isDaemonWriteOp};