@cef-ai/testing 3.5.4 → 4.0.0

package/dist/harness/memory-bank.d.ts

@@ -1,90 +1,163 @@
 /**
- * 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.
+ */
+import { type CefBuildInfo } from "@cef-ai/agent-sdk/runtime";
+import type { MemoryHandle, MemoryPrivacy } from "@cef-ai/agent-sdk";
+/** `record`'s columns (ddc-node memory migrations 0001, 0002, 0007; C3 §1.4). */
+export declare const RECORD_COLUMNS: readonly ["id", "type", "title", "body", "scope", "privacy", "created_at", "updated_at", "domain", "status", "version", "props", "reviewed_by", "reviewed_at"];
+/** `relation`'s columns (0001, 0002). */
+export declare const RELATION_COLUMNS: readonly ["id", "in_id", "out_id", "type", "scope", "privacy", "created_at", "updated_at", "domain"];
+/** `record_metric`'s columns (0002). */
+export declare const RECORD_METRIC_COLUMNS: readonly ["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.
  */
-/** A record as the bank stores it. */
+export declare const PENDING_COLUMNS: Record<string, readonly string[]>;
+/** A record as the bank stores it. `props` is JSON text, as in the bank. */
 export interface BankRecord {
     id: string;
     type: string;
     title: string;
     body: string;
     scope: string;
-    privacy: string;
-    /** The record's structured facts. Absent until a write sends some. */
-    props?: Record<string, unknown>;
-    /** When what the record describes happened (RFC 3339), named as the bank's column is. */
-    created_at?: string;
-    /** The subject facet. */
-    domain?: string;
+    privacy: MemoryPrivacy;
+    created_at: string;
+    updated_at: string;
+    domain: string;
+    status: BankStatus;
+    version: number;
+    props: string;
+    reviewed_by: string | null;
+    reviewed_at: string | null;
 }
-/** A typed edge between two records. */
-export interface BankEdge {
-    in: string;
-    out: string;
+export interface BankRelation {
+    id: string;
+    in_id: string;
+    out_id: string;
     type: string;
     scope: string;
-    privacy: string;
-    /** The subject facet. */
-    domain?: string;
+    privacy: MemoryPrivacy;
+    created_at: string;
+    updated_at: string;
+    domain: string;
+}
+export type BankStatus = "proposed" | "accepted" | "rejected" | "superseded";
+export type BankPolicy = "allow" | "curators";
+export type BankRole = "harvester" | "analyzer" | "embedder" | null;
+/** One connection's gate, as vault-api derives it for an agent. */
+export interface BankConnection {
+    /** Scopes it reads and writes. `"*"` = every scope (convenient; not a real grant). */
+    scopes: readonly string[] | "*";
+    /** Its run initiator's privacy ceiling. */
+    ceiling: MemoryPrivacy;
+    role?: BankRole;
+    /** False = a run with no initiator: reads empty, writes 403. Default true. */
+    initiator?: boolean;
+}
+export interface FakeBankOptions {
+    /** Default `"curators"` (D1; what devnet runs). */
+    policy?: BankPolicy;
+    /** The connection every caller without its own entry gets. Default: every scope, `restricted`, no role. */
+    connection?: Partial<BankConnection>;
+    /** Per agent id. */
+    connections?: Record<string, Partial<BankConnection>>;
+    /** Default true: vault-api with contract C3 (see the header). */
+    c3?: boolean;
 }
 export interface FakeBank {
+    /** Records by id, as stored. */
     records: Map<string, BankRecord>;
-    edges: BankEdge[];
-    /** Everything filed, oldest first — for assertions that read like a story. */
+    /** Every relation, oldest first. */
+    relations: BankRelation[];
+    /** record id → key → value */
+    metrics: Map<string, Map<string, number>>;
+    /** Every record, oldest first — for assertions that read like a story. */
     all(): BankRecord[];
-    refuseWrite?: (record: BankRecord) => boolean;
+    /** A record's props, parsed. */
+    props(id: string): Record<string, unknown> | undefined;
+    /** The options in force; mutable between calls. */
+    options: Required<Pick<FakeBankOptions, "policy" | "c3">> & Pick<FakeBankOptions, "connection" | "connections">;
+    /**
+     * Decide which writes the bank swallows: return true and the write is acked
+     * (204) and kept nowhere, as a scope the gate does not admit does.
+     */
+    refuseWrite?: (record: {
+        id: string;
+        type: string;
+        scope: string;
+        privacy: string;
+    }) => boolean;
+    /** A person files a record directly, as sent (status defaults to accepted). */
+    seed(record: Partial<BankRecord> & {
+        id: string;
+        type: string;
+        scope: string;
+        privacy: MemoryPrivacy;
+        props?: unknown;
+    }): BankRecord;
+    /** A person accepts a record: status `accepted`, review stamp set (C3 §1.4). */
+    accept(id: string, opts?: {
+        by?: string;
+    }): void;
+    /** A person rejects a record: status `rejected`, review stamp set. */
+    reject(id: string, opts?: {
+        by?: string;
+    }): void;
+    /** Status `superseded`; the stamp is kept. */
+    supersede(id: string): void;
+    /** The door: `POST <base>/<tool>`. The caller is named by the `x-agent-id` header. */
+    fetch: typeof fetch;
+    /** `…/vaults/<vaultId>/memory` */
+    base: string;
+    /** The agent-sdk `ctx.memory` handle, over this door, as one agent. */
+    handle(self?: {
+        agentId?: string;
+        jobId?: string;
+    }, build?: CefBuildInfo): MemoryHandle;
+    /** Every request the door served, oldest first: tool, body, and the agent that sent it. */
+    requests: {
+        tool: string;
+        body: Record<string, unknown>;
+        agentId: string;
+    }[];
 }
-/**
- * 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".
- */
-export declare function fakeMemoryBank(): {
-    memory: Record<string, unknown>;
-    bank: FakeBank;
-};
+export declare function fakeMemoryBank(opts?: FakeBankOptions): FakeBank;
 //# sourceMappingURL=memory-bank.d.ts.map

package/dist/harness/memory-bank.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory-bank.d.ts","sourceRoot":"","sources":["../../src/harness/memory-bank.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,sCAAsC;AACtC,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,yFAAyF;IACzF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yBAAyB;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wCAAwC;AACxC,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,yBAAyB;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACjC,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,8EAA8E;IAC9E,GAAG,IAAI,UAAU,EAAE,CAAC;IAcpB,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC;CAC/C;AAwBD;;;;;;GAMG;AACH,wBAAgB,cAAc,IAAI;IAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAqHpF"}
+{"version":3,"file":"memory-bank.d.ts","sourceRoot":"","sources":["../../src/harness/memory-bank.ts"],"names":[],"mappings":"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"}