@cef-ai/testing 3.5.3 → 4.0.0

package/dist/harness/memory-bank.js

@@ -1,191 +1,645 @@
 /**
- * A memory bank you can run a workflow against.
+ * THE FAKE MEMORY BANK — vault-api's memory door, in memory (contract C2 §5).
  *
- * WHY THIS HAD TO EXIST. `ctx.memory` was a stub that threw — nine tools, one
- * message saying to assert on it through a fetch mock. That was defensible
- * while memory was something an agent occasionally reached for. It stopped
- * being defensible when `remember`, `relate` and `recall` became NODES: the
- * runner now executes them itself, inline, and a workflow's durable output goes
- * through this path. A runner feature with no simulator is a runner feature
- * whose tests can only assert that it was ATTEMPTED.
+ * A JS model of the bank's own columns (the parity test diffs them against a
+ * SHA-pinned copy of ddc-node's DDL, `fixtures/vault-memory-ddl.sql`), served
+ * behind a fetch-level copy of the REST door: `POST <base>/<tool>` with the
+ * real request bodies, the real `{columns, rows}` projections, 204 writes, and
+ * vault-api's `{"error":{"code","message"}}` refusals. The agent-sdk's own
+ * `ctx.memory` shim runs against it unmodified — the fake is no longer a
+ * parallel object with method signatures of its own.
  *
- * That gap has a bill attached. WF1 reported "done · 6 of 8 steps ran" with
- * nothing persisted, twice, for two different reasons — a runner that walked
- * past unknown kinds in silence, and inline steps that left no trace — and
- * neither was caught by a unit test, because no unit test could reach the
- * write.
+ * FAITHFUL ON PURPOSE, where the old fake was not:
+ *  - Reads are gated: scope ∈ the connection's scopes, privacy ≤ its ceiling.
+ *    A hidden record and an absent one look the same.
+ *  - Statuses: a new row with no status lands `accepted`; reads return
+ *    accepted rows unless `statuses` says otherwise; `statuses` with `status`
+ *    or `include_unaccepted` is a 400.
+ *  - The write policy. The default is `curators` (the D1 target, and devnet):
+ *    an ordinary connection's write is a 403; a harvester's upsert is forced
+ *    to `proposed` and never rewrites a decided row; an analyzer writes only
+ *    `metric:`/`obs:` ids and metric keys the rule admits.
+ *  - A write is acked alike whether or not it landed: a hidden target, an edge
+ *    to an invisible end, a metric on a decided record all answer 204 and
+ *    change nothing.
+ *  - Per platform, never a module singleton.
  *
- * FAITHFUL WHERE IT MATTERS, AND SMALL EVERYWHERE ELSE. Three behaviours are
- * real because workflows depend on them:
+ * APPROXIMATED, and said so: search is case-insensitive term matching over
+ * id, type, title and body (all terms, a trailing `*` makes a prefix), not
+ * FTS5 with stemming and bm25. `rank` is the negated hit count.
  *
- *   UPSERT ON ID. `record_upsert` is idempotent on the record id, which is the
- *   whole safety property of the store: events redeliver, and a bank where one
- *   candidate appears four times makes every report over it quietly wrong. A
- *   fake that appended would let a double-write pass.
- *
- *   PRIVACY IS REFUSED AT THE DOOR, not defaulted. The real bank rejects a
- *   write that does not classify itself, and these records are about real
- *   people. A fake that accepted one would let a workflow ship that the store
- *   then rejects in production.
- *
- *   SEARCH NEEDS A TERM. The index is FTS5, so an empty match matches NOTHING
- *   rather than everything. A fake that returned everything for "" would make
- *   a node that silently reads nothing look like it works.
- *
- * Matching is substring rather than FTS5, with a trailing `*` tolerated, which
- * is close enough to test a graph and not close enough to test a query.
- *
- * PROPS, CREATED_AT AND DOMAIN follow the bank's rules too, because a view
- * that draws records reads them: props must be one object, a date may not be
- * in the future, and a write that leaves either out keeps what the record
- * already has (a new record is stamped now). Domain is the exception: the bank
- * overwrites it from every write, so leaving it out clears it. A read returns props as JSON
- * text, as the bank's own row does, so a workflow that parses them in
- * production parses them here; `bank.records` holds the object, for
- * assertions.
+ * `c3` (default true) models vault-api with contract C3: `id_prefix`,
+ * `domains` on `record_list`, the review stamp, the analyzer key rule, the
+ * `involves` harvester edge, and a 403 for a write above the writer's ceiling.
+ * `c3: false` models the vault-api deployed before it: those facets are
+ * IGNORED (as Go's JSON decoder ignores an unknown field), analyzer keys are
+ * the nine of the old allow-list, and an insert above the ceiling lands where
+ * its writer cannot see it.
  */
-const str = (v) => (typeof v === "string" ? v : "");
-/** How far ahead of now a sent date may be, as the bank allows for clock skew. */
-const CREATED_AT_SKEW_MS = 5 * 60 * 1000;
-/** A sent props value, refused as the bank refuses it: it must be one object. */
-const propsOf = (v) => {
-    if (v === undefined || v === null)
-        return undefined;
-    if (typeof v !== "object" || Array.isArray(v))
-        throw new Error("[bank] props must be a JSON object");
-    return v;
-};
-/** A sent date, refused as the bank refuses it: RFC 3339 and not in the future. */
-const createdAtOf = (v) => {
-    const at = str(v);
-    if (!at)
-        return undefined;
-    const ms = Date.parse(at);
-    if (Number.isNaN(ms))
-        throw new Error(`[bank] created_at must be an RFC 3339 timestamp (got "${at}")`);
-    if (ms > Date.now() + CREATED_AT_SKEW_MS)
-        throw new Error(`[bank] created_at must not be in the future (got "${at}")`);
-    return at;
+import { createMemoryHandle } from "@cef-ai/agent-sdk/runtime";
+/* -------------------------------------------------------------------------- */
+/* the model — named and ordered as the bank's own columns                    */
+/* -------------------------------------------------------------------------- */
+/** `record`'s columns (ddc-node memory migrations 0001, 0002, 0007; C3 §1.4). */
+export const RECORD_COLUMNS = [
+    "id", "type", "title", "body", "scope", "privacy", "created_at", "updated_at",
+    "domain", "status", "version", "props", "reviewed_by", "reviewed_at",
+];
+/** `relation`'s columns (0001, 0002). */
+export const RELATION_COLUMNS = [
+    "id", "in_id", "out_id", "type", "scope", "privacy", "created_at", "updated_at", "domain",
+];
+/** `record_metric`'s columns (0002). */
+export const RECORD_METRIC_COLUMNS = ["record_id", "key", "value"];
+/**
+ * Columns the model carries ahead of the pinned DDL because an approved
+ * contract adds them and the migration is not merged yet. The parity test
+ * fails when one of these appears in the DDL, so the list is emptied the day
+ * the fixture is refreshed past that migration.
+ */
+export const PENDING_COLUMNS = {
+    record: ["reviewed_by", "reviewed_at"], // C3 §1.4 review stamp, memory schema v9
 };
+/* -------------------------------------------------------------------------- */
+/* rules mirrored from vault-api (ddc-node handlers/memory.go, memory/*.go)    */
+/* -------------------------------------------------------------------------- */
+const PRIVACIES = ["public", "internal", "private", "restricted"];
+const rank = (p) => PRIVACIES.indexOf(p);
+const STATUSES = ["proposed", "accepted", "rejected", "superseded"];
+const PLATFORM_EDGES = ["used", "produced", "ran_by", "caused_by"];
+const HARVESTER_EDGES_PRE_C3 = ["derived_from", "supersedes", "about"];
+const HARVESTER_EDGES_C3 = [...HARVESTER_EDGES_PRE_C3, "involves"];
+const ANALYZER_EDGES = ["derived_from", "about"];
+const ANALYZER_KEYS_PRE_C3 = ["n", "decided", "hits", "hit_rate", "base_rate", "lift", "window_days", "config_version", "dropped"];
+const ANALYZER_KEY_RULE = /^[a-z][a-z0-9_]{0,62}$/;
+const LEDGER_KEYS = ["a2a_cost", "a2a_tokens", "duration_ms"];
+const MAX_LIMIT = 500;
+const DEFAULT_LIMIT = 50;
+const DEFAULT_BODY_CHARS = 4000;
+const MAX_BODY_CHARS = 20000;
+const MAX_PROPS_BYTES = 16 * 1024;
+const CREATED_AT_SKEW_MS = 5 * 60 * 1000;
+const WORKFLOW_AGENT_REFUSAL = "memory: workflow agents write to cubbies; only harvester connections write to the "
+    + "memory bank — write this run's output to a cubby, or ask the vault owner to mark this connection as a harvester";
+const NO_INITIATOR = "memory: this run holds no privacy ceiling, so it can write nothing — an agent's ceiling is "
+    + "its job initiator's, and this job has no initiator (no person published the event that started it, directly "
+    + "or through the agents that led to it)";
 /**
- * The nine tools `ctx.memory` wraps, over a Map.
- *
- * Returns the bank alongside so a test can assert on what is IN it, which is
- * the question worth asking: "the step did not throw" is not the same claim as
- * "the record is there, with that classification".
+ * record_list's cursor, as this fake mints it. A cursor that does not decode is
+ * the door's 400 (ddc-node memory/cursor.go decodeCursorTuple), never a thrown
+ * SyntaxError out of the fetch.
  */
-export function fakeMemoryBank() {
+function decodeListCursor(cursor) {
+    let parts;
+    try {
+        parts = JSON.parse(Buffer.from(cursor, "base64url").toString());
+    }
+    catch {
+        throw new Refusal(400, "BAD_REQUEST", "memory: record_list: cursor does not decode");
+    }
+    if (!Array.isArray(parts) || parts.length !== 2 || parts.some((x) => typeof x !== "string")) {
+        throw new Refusal(400, "BAD_REQUEST", "memory: record_list: cursor is the wrong tuple for this tool");
+    }
+    return parts;
+}
+/** "a, b and c" — how vault-api lists edge types in a refusal. */
+function andList(xs) {
+    return xs.length < 2 ? xs.join("") : `${xs.slice(0, -1).join(", ")} and ${xs[xs.length - 1]}`;
+}
+class Refusal extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+const bad = (msg) => new Refusal(400, "BAD_REQUEST", msg);
+const denied = (msg) => new Refusal(403, "SCOPE_DENIED", msg);
+const str = (v) => (typeof v === "string" ? v : "");
+const strList = (v) => Array.isArray(v) ? v.map((x) => String(x)) : undefined;
+/* -------------------------------------------------------------------------- */
+export function fakeMemoryBank(opts = {}) {
     const records = new Map();
-    const edges = [];
-    const classify = (privacy, what) => {
-        const p = str(privacy);
-        // The real bank refuses at the door. Defaulting here would hide the one
-        // mistake this check exists to catch.
-        if (!p)
-            throw new Error(`[bank] ${what} without a privacy classification`);
-        return p;
+    const relations = [];
+    const metrics = new Map();
+    const requests = [];
+    const base = "http://fake-vault/api/v1/vaults/v-test/memory";
+    // A clock that never repeats, so `updated_at DESC` is a total order.
+    let last = 0;
+    const now = () => {
+        last = Math.max(Date.now(), last + 1);
+        return new Date(last).toISOString();
     };
-    // Built before `memory` so the tools can consult it — refuseWrite is a knob a
-    // test turns, and upsert has to read it at call time, not at construction.
-    const bank = { records, edges, all: () => [...records.values()] };
-    const memory = {
-        upsert: async (r) => {
-            const id = str(r.id);
-            if (!id)
-                throw new Error("[bank] a record needs an id");
-            const privacy = classify(r.privacy, "record");
-            const props = propsOf(r.props);
-            const createdAt = createdAtOf(r.createdAt);
-            const existing = records.get(id);
+    const bank = {
+        records,
+        relations,
+        metrics,
+        requests,
+        base,
+        options: { policy: opts.policy ?? "curators", c3: opts.c3 ?? true, connection: opts.connection, connections: opts.connections },
+        all: () => [...records.values()],
+        props: (id) => {
+            const r = records.get(id);
+            return r ? JSON.parse(r.props) : undefined;
+        },
+        seed(r) {
+            const at = now();
             const row = {
-                id,
-                type: str(r.type) || "record",
-                title: str(r.title) || id,
-                body: str(r.body),
-                scope: str(r.scope),
-                privacy,
-                // Left out, each keeps what the record has — see the note above.
-                ...(props ?? existing?.props ? { props: props ?? existing?.props } : {}),
-                created_at: createdAt ?? existing?.created_at ?? new Date().toISOString(),
-                // Domain is NOT kept: the bank overwrites it from every write, so a
-                // write that leaves it out clears it.
-                ...(str(r.domain) ? { domain: str(r.domain) } : {}),
+                title: "", body: "", domain: "", status: "accepted", version: 1,
+                created_at: at, updated_at: at, reviewed_by: null, reviewed_at: null,
+                ...r,
+                props: r.props === undefined ? "{}" : typeof r.props === "string" ? r.props : JSON.stringify(r.props),
             };
-            // The ack is the same either way — see FakeBank.refuseWrite.
-            if (bank.refuseWrite?.(row))
-                return { id };
-            // UPSERT, NOT APPEND — see the note above.
-            records.set(id, row);
-            return { id };
-        },
-        update: async (r) => {
-            const id = str(r.id);
-            const existing = records.get(id);
-            if (!existing)
-                throw new Error(`[bank] no record ${id}`);
-            records.set(id, { ...existing, ...r, id });
-            return { id };
-        },
-        setPrivacy: async (r) => {
-            const id = str(r.id);
-            const existing = records.get(id);
-            if (!existing)
-                throw new Error(`[bank] no record ${id}`);
-            records.set(id, { ...existing, privacy: classify(r.privacy, "record") });
-            return { id };
+            records.set(row.id, row);
+            return row;
         },
-        delete: async (r) => {
-            records.delete(str(r.id));
-            return {};
+        accept: (id, o) => decide(id, "accepted", o?.by),
+        reject: (id, o) => decide(id, "rejected", o?.by),
+        supersede(id) {
+            const r = must(id);
+            r.status = "superseded";
+            r.updated_at = now();
         },
-        relation: async (e) => {
-            const from = str(e.in);
-            const to = str(e.out);
-            if (!from || !to)
-                throw new Error("[bank] a relation needs both ends");
-            edges.push({
-                in: from,
-                out: to,
-                type: str(e.type) || "related",
-                scope: str(e.scope),
-                // An edge carries its own: gating only the endpoints would leak that
-                // the relationship exists.
-                privacy: classify(e.privacy, "relation"),
-                ...(str(e.domain) ? { domain: str(e.domain) } : {}),
+        fetch: (async (input, init) => {
+            const url = String(input instanceof Request ? input.url : input);
+            const tool = url.slice(url.lastIndexOf("/") + 1);
+            const headers = new Headers(init?.headers);
+            const agentId = headers.get("x-agent-id") ?? "";
+            let body;
+            try {
+                body = JSON.parse(String(init?.body ?? "{}"));
+            }
+            catch {
+                return refusal(new Refusal(400, "BAD_REQUEST", "memory: bad body"));
+            }
+            requests.push({ tool, body, agentId });
+            try {
+                const out = serve(tool, body, connectionOf(agentId));
+                if (out === null)
+                    return new Response(null, { status: 204 });
+                return new Response(JSON.stringify(out), { status: 200, headers: { "content-type": "application/json" } });
+            }
+            catch (e) {
+                if (e instanceof Refusal)
+                    return refusal(e);
+                throw e;
+            }
+        }),
+        handle(self = {}, build) {
+            return createMemoryHandle({
+                base,
+                headers: self.agentId ? { "x-agent-id": self.agentId } : {},
+                fetch: bank.fetch,
+                self,
+                build: build ?? { agent: (self.agentId ?? "test-agent").split(":").pop(), version: "0.0.0-test" },
             });
-            return {};
         },
-        search: async (match, opts) => {
-            // FTS5: an empty term matches NOTHING, not everything.
-            const term = str(match).replace(/\*+$/, "").trim().toLowerCase();
-            if (!term)
-                return [];
-            const hit = (r) => `${r.id} ${r.type} ${r.title} ${r.body}`.toLowerCase().includes(term);
-            return [...records.values()].filter(hit).slice(0, opts?.limit ?? 50);
-        },
-        get: async (id) => {
-            const row = records.get(str(id));
-            if (!row)
+    };
+    function must(id) {
+        const r = records.get(id);
+        if (!r)
+            throw new Error(`[fake bank] no record ${id}`);
+        return r;
+    }
+    function decide(id, status, by = "0xperson") {
+        const r = must(id);
+        r.status = status;
+        r.updated_at = now();
+        if (bank.options.c3) {
+            r.reviewed_by = by;
+            r.reviewed_at = r.updated_at;
+        }
+    }
+    function refusal(e) {
+        return new Response(JSON.stringify({ error: { code: e.code, message: e.message, retryable: false } }), {
+            status: e.status,
+            headers: { "content-type": "application/json" },
+        });
+    }
+    function connectionOf(agentId) {
+        const c = { ...(bank.options.connection ?? {}), ...(bank.options.connections?.[agentId] ?? {}) };
+        return { scopes: c.scopes ?? "*", ceiling: c.ceiling ?? "restricted", role: c.role ?? null, initiator: c.initiator ?? true };
+    }
+    /* --------------------------------- gate --------------------------------- */
+    const inScope = (c, scope) => c.scopes === "*" || c.scopes.includes(scope);
+    const visible = (c, r) => !!r && c.initiator !== false && inScope(c, r.scope) && rank(r.privacy) <= rank(c.ceiling);
+    /* -------------------------------- reads --------------------------------- */
+    function statusFilter(b) {
+        const statuses = strList(b.statuses);
+        if (statuses && statuses.length > 0) {
+            if (b.status || b.include_unaccepted)
+                throw bad("memory: send statuses, or status / include_unaccepted, not both");
+            for (const s of statuses)
+                if (!STATUSES.includes(s))
+                    throw bad(`memory: unknown status "${s}"`);
+            return (r) => statuses.includes(r.status);
+        }
+        if (b.status) {
+            if (!STATUSES.includes(b.status))
+                throw bad(`memory: unknown status "${String(b.status)}"`);
+            return (r) => r.status === b.status;
+        }
+        if (b.include_unaccepted)
+            return () => true;
+        return (r) => r.status === "accepted";
+    }
+    function facets(b, list) {
+        const preds = [statusFilter(b)];
+        const types = strList(b.types);
+        if (b.type && types)
+            throw bad("memory: send type or types, not both");
+        if (types && types.length > 10)
+            throw bad(`memory: types may name at most 10 values (got ${types.length})`);
+        if (b.type)
+            preds.push((r) => r.type === b.type);
+        if (types && types.length > 0)
+            preds.push((r) => types.includes(r.type));
+        if (b.scope)
+            preds.push((r) => r.scope === b.scope);
+        if (b.privacy)
+            preds.push((r) => r.privacy === b.privacy);
+        const domains = strList(b.domains);
+        // record_search has always taken domains; record_list only with C3 (A2).
+        const domainsKnown = !list || bank.options.c3;
+        if (domains && domainsKnown) {
+            if (b.domain)
+                throw bad("memory: send domain or domains, not both");
+            if (domains.length > 20)
+                throw bad(`memory: domains may name at most 20 values (got ${domains.length})`);
+            preds.push((r) => domains.includes(r.domain));
+        }
+        if (b.domain)
+            preds.push((r) => r.domain === b.domain);
+        if (b.id_prefix !== undefined && bank.options.c3) {
+            const p = str(b.id_prefix);
+            if (p.length < 1 || p.length > 128)
+                throw bad("memory: id_prefix must be 1 to 128 characters");
+            preds.push((r) => r.id.startsWith(p));
+        }
+        return (r) => preds.every((f) => f(r));
+    }
+    function includeCols(b) {
+        const inc = strList(b.include) ?? [];
+        const known = ["body", "props", "created_at", "updated_at", "domain", "status", "version", ...(bank.options.c3 ? ["review"] : [])];
+        for (const i of inc)
+            if (!known.includes(i))
+                throw bad(`memory: include may name ${known.join(", ")} (got "${i}")`);
+        let chars = DEFAULT_BODY_CHARS;
+        if (b.body_chars !== undefined) {
+            if (!inc.includes("body"))
+                throw bad('memory: body_chars needs include ["body"]');
+            chars = Number(b.body_chars);
+            if (!Number.isInteger(chars) || chars < 1 || chars > MAX_BODY_CHARS) {
+                throw bad(`memory: body_chars must be between 1 and ${MAX_BODY_CHARS} (got ${String(b.body_chars)})`);
+            }
+        }
+        const names = [];
+        const getters = [];
+        if (inc.includes("body")) {
+            names.push("body");
+            getters.push((r) => r.body.slice(0, chars));
+        }
+        if (inc.includes("props")) {
+            names.push("props");
+            getters.push((r) => r.props);
+        }
+        if (inc.includes("review")) {
+            names.push("reviewed_by", "reviewed_at");
+            getters.push((r) => r.reviewed_by, (r) => r.reviewed_at);
+        }
+        return { names, value: (r) => getters.map((g) => g(r)) };
+    }
+    const limitOf = (b) => {
+        const n = b.limit === undefined ? DEFAULT_LIMIT : Number(b.limit);
+        return Math.min(Math.max(Number.isFinite(n) && n > 0 ? Math.floor(n) : DEFAULT_LIMIT, 1), MAX_LIMIT);
+    };
+    function search(b, c) {
+        const match = str(b.match).trim();
+        if (!match && !b.query)
+            throw bad("memory: record_search needs match or query");
+        const terms = match.split(/\s+/).filter((t) => t && t.toUpperCase() !== "OR").map((t) => t.replace(/^"|"$/g, "").toLowerCase());
+        const any = /\sOR\s/.test(match);
+        const hits = (r) => {
+            const text = `${r.id} ${r.type} ${r.title} ${r.body}`.toLowerCase();
+            const each = terms.map((t) => (t.endsWith("*") ? text.includes(t.slice(0, -1)) : text.includes(t)));
+            return each.filter(Boolean).length;
+        };
+        const f = facets(b, false);
+        const inc = includeCols(b);
+        const rows = [...records.values()]
+            .filter((r) => visible(c, r) && f(r))
+            .map((r) => ({ r, n: hits(r) }))
+            .filter(({ n }) => (any ? n > 0 : n === terms.length))
+            .sort((a, z) => z.n - a.n || a.r.id.localeCompare(z.r.id))
+            .slice(0, limitOf(b));
+        return {
+            columns: ["id", "type", "title", "scope", "privacy", "rank", "snippet", "domain", "status", "version", ...inc.names],
+            rows: rows.map(({ r, n }) => [r.id, r.type, r.title, r.scope, r.privacy, -n, r.title, r.domain, r.status, r.version, ...inc.value(r)]),
+        };
+    }
+    function list(b, c) {
+        const f = facets(b, true);
+        const inc = includeCols(b);
+        let rows = [...records.values()]
+            .filter((r) => visible(c, r) && f(r))
+            .sort((a, z) => z.updated_at.localeCompare(a.updated_at) || a.id.localeCompare(z.id));
+        if (b.cursor) {
+            const [at, id] = decodeListCursor(str(b.cursor));
+            rows = rows.filter((r) => r.updated_at < at || (r.updated_at === at && r.id > id));
+        }
+        const limit = limitOf(b);
+        const page = rows.slice(0, limit);
+        const lastRow = page[page.length - 1];
+        const cursor = rows.length > limit && lastRow
+            ? Buffer.from(JSON.stringify([lastRow.updated_at, lastRow.id])).toString("base64url")
+            : undefined;
+        return {
+            columns: ["id", "type", "title", "scope", "privacy", "updated_at", "domain", "status", "version", "created_at", ...inc.names],
+            rows: page.map((r) => [r.id, r.type, r.title, r.scope, r.privacy, r.updated_at, r.domain, r.status, r.version, r.created_at, ...inc.value(r)]),
+            ...(cursor ? { cursor } : {}),
+        };
+    }
+    function get(b, c) {
+        const r = records.get(str(b.id));
+        const columns = ["id", "type", "title", "body", "scope", "privacy", "created_at", "updated_at", "domain", "status", "version", "props",
+            ...(bank.options.c3 ? ["reviewed_by", "reviewed_at"] : [])];
+        if (!visible(c, r))
+            return { columns, rows: [] };
+        return {
+            columns,
+            rows: [[r.id, r.type, r.title, r.body, r.scope, r.privacy, r.created_at, r.updated_at, r.domain, r.status, r.version, r.props,
+                    ...(bank.options.c3 ? [r.reviewed_by, r.reviewed_at] : [])]],
+        };
+    }
+    function neighbours(b, c) {
+        const id = str(b.id);
+        const dir = str(b.direction) || "both";
+        if (!["in", "out", "both"].includes(dir))
+            throw bad(`record_neighbours: direction must be one of in, out, both (got "${dir}")`);
+        const statuses = bank.options.c3 ? strList(b.statuses) : undefined;
+        const columns = ["id", "type", "title", "scope", "privacy", "type", "domain", "status", "version"];
+        if (!visible(c, records.get(id)))
+            return { columns, rows: [] };
+        const rows = [];
+        for (const e of relations) {
+            const touches = dir === "out" ? e.in_id === id : dir === "in" ? e.out_id === id : e.in_id === id || e.out_id === id;
+            if (!touches || (b.edge_type && e.type !== b.edge_type) || !visible(c, e))
+                continue;
+            const far = records.get(e.in_id === id ? e.out_id : e.in_id);
+            if (!far || !visible(c, far) || (statuses && !statuses.includes(far.status)))
+                continue;
+            rows.push([far.id, far.type, far.title, far.scope, far.privacy, e.type, far.domain, far.status, far.version]);
+        }
+        rows.sort((a, z) => String(a[0]).localeCompare(String(z[0])));
+        return { columns, rows: rows.slice(0, limitOf(b)) };
+    }
+    function recordMetrics(b, c) {
+        const ids = strList(b.ids);
+        if (ids && bank.options.c3) {
+            if (b.id)
+                throw bad("memory: send id or ids, not both");
+            if (ids.length > 50)
+                throw bad("memory: ids may name at most 50 records");
+            const rows = [];
+            for (const id of [...ids].sort()) {
+                if (!visible(c, records.get(id)))
+                    continue;
+                for (const [k, v] of [...(metrics.get(id) ?? new Map())].sort())
+                    rows.push([id, k, v]);
+            }
+            return { columns: ["record_id", "key", "value"], rows };
+        }
+        const id = str(b.id);
+        if (!visible(c, records.get(id)))
+            return { columns: ["key", "value"], rows: [] };
+        return { columns: ["key", "value"], rows: [...(metrics.get(id) ?? new Map())].sort() };
+    }
+    function countByType(b, c) {
+        const n = new Map();
+        for (const r of records.values()) {
+            if (!visible(c, r) || r.status !== "accepted" || (b.scope && r.scope !== b.scope) || (b.domain && r.domain !== b.domain))
+                continue;
+            n.set(r.type, (n.get(r.type) ?? 0) + 1);
+        }
+        return { columns: ["type", "n"], rows: [...n].sort() };
+    }
+    /* -------------------------------- writes -------------------------------- */
+    function writeGate(tool, b, c, scope, privacy) {
+        if (c.initiator === false)
+            throw denied(NO_INITIATOR);
+        if (!scope)
+            throw bad("memory: scope is required");
+        if (!PRIVACIES.includes(privacy)) {
+            throw bad("memory: privacy must be one of public, internal, private, restricted");
+        }
+        if (!inScope(c, scope)) {
+            const writable = c.scopes === "*" ? "every scope" : c.scopes.join(", ") || "none";
+            throw denied(`memory: not a scope you may write to: "${scope}"`
+                + (writable === "none" ? " — you hold no writable scope in this vault" : ` — you may write to: ${writable}`));
+        }
+        if (bank.options.c3 && rank(privacy) > rank(c.ceiling)) {
+            throw new Refusal(403, "PRIVACY_ABOVE_CEILING", `memory: you may write at most ${c.ceiling} here (got ${privacy}); `
+                + "a record above your own ceiling would be invisible to you — for an agent, the ceiling is its job initiator's");
+        }
+        if (bank.options.policy !== "curators")
+            return;
+        if (c.role === "embedder")
+            throw denied("memory: an embedder writes only record vectors (record_vec_upsert) — records, edges and metrics are other roles' writes");
+        if (c.role === "harvester") {
+            if (!["record_upsert", "relation_upsert"].includes(tool))
+                throw denied(`memory: a harvester may not call ${tool} — it files proposals and draws derived_from, supersedes, about and "
+          + "involves edges; promoting, rewriting, reclassifying and deleting are a person's acts`);
+            if (tool === "record_upsert" && b.status && b.status !== "proposed") {
+                throw denied(`memory: a harvester writes proposals — status must be proposed or omitted (got "${String(b.status)}"); `
+                    + "a person accepts a proposal into the bank");
+            }
+            return;
+        }
+        if (c.role === "analyzer") {
+            if (!["record_upsert", "relation_upsert", "record_metric_upsert"].includes(tool)) {
+                throw denied(`memory: an analyzer may not call ${tool} — it files proposed metric: and obs: records, draws derived_from `
+                    + "and about edges, and attaches counts to its own proposed metric: records");
+            }
+            const id = str(b.id);
+            if (tool !== "relation_upsert" && !id.startsWith("metric:") && !(tool === "record_upsert" && id.startsWith("obs:"))) {
+                throw denied(tool === "record_metric_upsert"
+                    ? `memory: an analyzer attaches counts only to metric: records (got id "${id}")`
+                    : `memory: an analyzer writes only metric: and obs: records (got id "${id}")`);
+            }
+            return;
+        }
+        throw denied(WORKFLOW_AGENT_REFUSAL);
+    }
+    function upsert(b, c) {
+        const id = str(b.id);
+        if (!id)
+            throw bad("memory: a record needs an id");
+        if (!str(b.type))
+            throw bad("memory: type is required");
+        if (id.startsWith("run:"))
+            throw new Refusal(403, "PLATFORM_RESERVED", "memory: run: records are the platform's");
+        if (b.status !== undefined && !STATUSES.includes(b.status))
+            throw bad(`memory: unknown status "${String(b.status)}"`);
+        let props;
+        if (b.props !== undefined && b.props !== null) {
+            if (typeof b.props !== "object" || Array.isArray(b.props))
+                throw bad("memory: props must be a JSON object");
+            props = JSON.stringify(b.props);
+            if (new TextEncoder().encode(props).length > MAX_PROPS_BYTES)
+                throw bad("memory: props over 16 KiB");
+        }
+        const createdAt = str(b.created_at);
+        if (createdAt) {
+            const ms = Date.parse(createdAt);
+            if (Number.isNaN(ms))
+                throw bad(`memory: created_at must be RFC 3339 (got "${createdAt}")`);
+            if (ms > Date.now() + CREATED_AT_SKEW_MS)
+                throw bad(`memory: created_at must not be in the future (got "${createdAt}")`);
+        }
+        const scope = str(b.scope);
+        const privacy = str(b.privacy);
+        writeGate("record_upsert", b, c, scope, privacy);
+        if (bank.refuseWrite?.({ id, type: str(b.type), scope, privacy }))
+            return null;
+        const prev = records.get(id);
+        const curator = bank.options.policy === "curators" && (c.role === "harvester" || c.role === "analyzer");
+        if (prev) {
+            // The conflict arm is gated: a row the writer cannot see is not touched,
+            // and the ack says nothing (the existence oracle is closed).
+            if (!visible(c, prev))
                 return null;
-            // Props travel as JSON text, as the bank's own row carries them.
-            return row.props ? { ...row, props: JSON.stringify(row.props) } : row;
-        },
-        neighbours: async (id) => {
-            const me = str(id);
-            return edges
-                .filter((e) => e.in === me || e.out === me)
-                .map((e) => {
-                const far = e.in === me ? e.out : e.in;
-                return { ...(records.get(far) ?? { id: far }), edgeType: e.type };
+            // The proposal builder rewrites only a row that is still proposed.
+            if (curator && prev.status !== "proposed")
+                return null;
+        }
+        const at = now();
+        const status = curator ? "proposed" : b.status ?? prev?.status ?? "accepted";
+        const changed = prev && prev.status !== status;
+        records.set(id, {
+            id,
+            type: str(b.type),
+            title: str(b.title),
+            body: str(b.body),
+            scope,
+            privacy: privacy,
+            created_at: createdAt || prev?.created_at || at,
+            updated_at: at,
+            // Overwritten on every write: omitting it clears it.
+            domain: str(b.domain),
+            status,
+            version: Math.max(prev?.version ?? 1, Number(b.version) || 1),
+            props: props ?? prev?.props ?? "{}",
+            // C3 §1.4: a person naming accepted/rejected stamps; any other status change clears.
+            reviewed_by: changed ? null : prev?.reviewed_by ?? null,
+            reviewed_at: changed ? null : prev?.reviewed_at ?? null,
+        });
+        // An insert above the writer's ceiling (pre-C3) lands, invisible to it.
+        return null;
+    }
+    function relationUpsert(b, c) {
+        const from = str(b.in);
+        const to = str(b.out);
+        const type = str(b.type);
+        if (!from || !to || !type)
+            throw bad("memory: a relation needs in, out and type");
+        if (PLATFORM_EDGES.includes(type))
+            throw new Refusal(403, "PLATFORM_RESERVED", `memory: "${type}" edges are the platform's`);
+        const scope = str(b.scope);
+        const privacy = str(b.privacy);
+        writeGate("relation_upsert", b, c, scope, privacy);
+        if (bank.options.policy === "curators") {
+            const allowed = c.role === "analyzer" ? ANALYZER_EDGES : bank.options.c3 ? HARVESTER_EDGES_C3 : HARVESTER_EDGES_PRE_C3;
+            if (!allowed.includes(type))
+                throw denied(`memory: ${c.role === "analyzer" ? "an" : "a"} ${c.role} may draw only ${andList(allowed)} edges (got "${type}")`);
+        }
+        // Both ends must be visible, or nothing is drawn — and the ack is the same.
+        if (!visible(c, records.get(from)) || !visible(c, records.get(to)))
+            return null;
+        const existing = relations.find((e) => e.in_id === from && e.out_id === to && e.type === type);
+        const at = now();
+        if (existing) {
+            Object.assign(existing, { scope, privacy, domain: str(b.domain), updated_at: at });
+        }
+        else {
+            relations.push({
+                id: `rel:${relations.length + 1}`, in_id: from, out_id: to, type, scope,
+                privacy: privacy, created_at: at, updated_at: at, domain: str(b.domain),
             });
-        },
-        countByType: async () => {
-            const n = new Map();
-            for (const r of records.values())
-                n.set(r.type, (n.get(r.type) ?? 0) + 1);
-            return [...n].map(([type, count]) => ({ type, n: count }));
-        },
-    };
-    return { memory, bank };
+        }
+        return null;
+    }
+    function metricUpsert(b, c) {
+        const id = str(b.id);
+        const key = str(b.metric_key);
+        const value = Number(b.metric_value);
+        if (!id || !key)
+            throw bad("memory: record_metric_upsert needs id and metric_key");
+        if (!Number.isFinite(value) || Math.abs(value) > 1e15)
+            throw bad("memory: metric_value must be finite, |v| ≤ 1e15");
+        const r = records.get(id);
+        writeGate("record_metric_upsert", b, c, r?.scope ?? "", r?.privacy ?? "internal");
+        if (bank.options.policy === "curators" && c.role === "analyzer") {
+            const ok = bank.options.c3
+                ? ANALYZER_KEY_RULE.test(key) && !LEDGER_KEYS.includes(key)
+                : ANALYZER_KEYS_PRE_C3.includes(key);
+            if (!ok) {
+                throw denied(bank.options.c3
+                    ? "memory: an analyzer metric key must be lower_snake_case, at most 63 characters, and not one of the platform's run keys "
+                        + `a2a_cost, a2a_tokens or duration_ms (got "${key}")`
+                    : `memory: an analyzer may write only the keys ${ANALYZER_KEYS_PRE_C3.join(", ")} (got "${key}")`);
+            }
+            if (!visible(c, r) || r.status !== "proposed")
+                return null;
+        }
+        else if (!visible(c, r)) {
+            return null;
+        }
+        const m = metrics.get(id) ?? new Map();
+        m.set(key, value);
+        metrics.set(id, m);
+        return null;
+    }
+    function personOnly(tool, b, c, apply) {
+        const r = records.get(str(b.id));
+        writeGate(tool, b, c, r?.scope ?? (c.scopes === "*" ? "x" : c.scopes[0] ?? ""), r?.privacy ?? "public");
+        if (r && visible(c, r))
+            apply(r);
+        return null;
+    }
+    function serve(tool, b, c) {
+        switch (tool) {
+            case "record_search": return search(b, c);
+            case "record_list": return list(b, c);
+            case "record_get": return get(b, c);
+            case "record_neighbours": return neighbours(b, c);
+            case "record_metrics": return recordMetrics(b, c);
+            case "record_count_by_type": return countByType(b, c);
+            case "record_upsert": return upsert(b, c);
+            case "relation_upsert": return relationUpsert(b, c);
+            case "record_metric_upsert": return metricUpsert(b, c);
+            case "record_update":
+                return personOnly(tool, b, c, (r) => {
+                    if (b.title !== undefined)
+                        r.title = str(b.title);
+                    if (b.body !== undefined)
+                        r.body = str(b.body);
+                    r.updated_at = now();
+                });
+            case "record_set_privacy":
+                if (!PRIVACIES.includes(b.privacy))
+                    throw bad("memory: privacy must be one of public, internal, private, restricted");
+                return personOnly(tool, b, c, (r) => { r.privacy = b.privacy; r.updated_at = now(); });
+            case "record_set_status":
+                if (!STATUSES.includes(b.status))
+                    throw bad(`memory: unknown status "${String(b.status)}"`);
+                return personOnly(tool, b, c, (r) => { r.status = b.status; r.updated_at = now(); r.reviewed_by = null; r.reviewed_at = null; });
+            case "record_delete":
+                return personOnly(tool, b, c, (r) => { records.delete(r.id); });
+        }
+        throw new Refusal(404, "BAD_REQUEST", "unknown memory tool");
+    }
+    return bank;
 }
 //# sourceMappingURL=memory-bank.js.map