@tpsdev-ai/flair 0.22.0 → 0.23.0

package/dist/resources/mcp-tools.js

@@ -123,13 +123,20 @@ async function memoryStore(agent, args) {
     // agentId is the RESOLVED agent — Memory.post also re-checks ownership via
     // resolveAgentAuth, so a mismatched body agentId would 403 anyway; we set it
     // to the verified id so the write is correctly owned.
-    return unwrap(await h.post({
+    const body = {
         agentId: agent.agentId,
         content: args?.content,
         type: args?.type ?? "session",
         durability: args?.durability ?? "standard",
         tags: args?.tags,
-    }));
+    };
+    // flair#718 authorship-provenance: forward the resolved OAuth client_id
+    // (never a tool argument — no forging) as claimedClient; Memory.post()
+    // folds it into provenance.claimed.client and strips it from the row.
+    // Omitted entirely when the token carried no client_id.
+    if (agent.clientId)
+        body.claimedClient = agent.clientId;
+    return unwrap(await h.post(body));
 }
 /**
  * memory_update — id-targeted, dedup-BYPASSED overwrite/version path (memory-
@@ -175,12 +182,20 @@ async function memoryUpdate(agent, args) {
         delete record.validFrom;
         delete record.validTo;
         delete record.archivedAt;
+        // flair#718 authorship-provenance — see memoryStore's comment: forward
+        // the resolved OAuth client_id (never forgeable via args) so the NEW
+        // version's provenance records which client authored this update.
+        if (agent.clientId)
+            record.claimedClient = agent.clientId;
         h.isCollection = true;
         return unwrap(await h.post(record));
     }
     const merged = { ...existing, content, updatedAt: new Date().toISOString() };
     delete merged.embedding;
     delete merged.embeddingModel;
+    // flair#718 authorship-provenance — see memoryStore's comment above.
+    if (agent.clientId)
+        merged.claimedClient = agent.clientId;
     return unwrap(await h.put(merged));
 }
 async function memoryGet(agent, args) {
@@ -287,6 +302,38 @@ async function recordUsage(agent, args) {
         : typeof args?.memoryId === "string" ? [args.memoryId] : undefined;
     return unwrap(await h.post({ memoryIds, attribution: args?.attribution }));
 }
+/**
+ * Verb→tool-name overrides — the three naming quirks where the shipped tool
+ * name isn't record-types.ts's default `${toolPrefix}_${verb}` shape (see
+ * that module's `mcp` header doc, and RECORD_TYPES.<Table>.mcp itself,
+ * record-types slice 3, flair#520). Keyed by table name + verb; consumed by
+ * `mcpToolName()` below and by test/unit/mcp-surface-tripwire.test.ts to
+ * compute the expected tool name for every declared registry verb.
+ *
+ * Placement here (not in record-types.ts) is deliberate — per Kern/
+ * Sherlock's unanimous slice-3 verdict, the registry declares WHAT is
+ * exposed (capability: toolPrefix + verbs); this map declares HOW that
+ * capability's tool is actually named (presentation). Coupling names into
+ * the registry would mix the policy layer with the presentation layer,
+ * exactly what the registry's separation is meant to avoid.
+ */
+export const TOOL_NAME_OVERRIDES = {
+    Soul: { store: "soul_set" },
+    WorkspaceState: { store: "flair_workspace_set" },
+    OrgEvent: { store: "flair_orgevent" },
+};
+/**
+ * Resolve the actual `TOOLS` key for a declared (table, verb) pair: the
+ * `TOOL_NAME_OVERRIDES` entry if one exists, else the default
+ * `${toolPrefix}_${verb}` shape. `toolPrefix` is passed in (rather than
+ * looked up from RECORD_TYPES here) so this stays a pure naming function —
+ * both this module and the tripwire test call it with the registry's own
+ * `toolPrefix` value, keeping the naming rule in exactly one place.
+ */
+export function mcpToolName(table, toolPrefix, verb) {
+    const override = TOOL_NAME_OVERRIDES[table]?.[verb];
+    return override ?? `${toolPrefix}_${verb}`;
+}
 export const TOOLS = {
     memory_search: {
         def: {
@@ -489,7 +536,7 @@ export const TOOLS = {
         impl: recordUsage,
     },
 };
-/** The tool definitions for a tools/list response (exactly the 9 curated tools). */
+/** The tool definitions for a tools/list response (exactly the 12 curated tools). */
 export function listToolDefs() {
     return Object.values(TOOLS).map((t) => t.def);
 }

package/dist/resources/migrations/runner.js

@@ -70,7 +70,6 @@ function resolveDeps(deps) {
         ledgerDeps: deps.ledgerDeps ?? {},
         batchDelayMs: deps.batchDelayMs ?? resolveTestBatchDelayMs() ?? 100,
         initiator: deps.initiator ?? "auto",
-        headroomFloor: deps.headroomFloor,
     };
 }
 // ─── space/snapshot sizing heuristics (overridable via RunnerDeps in future if ever needed) ──
@@ -256,11 +255,11 @@ async function runOneMigration(migration, envelope, deps, lock) {
     }
     const estSnapshot = estimateSnapshotBytes(posture.snapshotScope, initialRemaining);
     const estWorkingSet = estimateWorkingSetBytes(migration.riskClass, initialRemaining);
-    let space = checkSpace({ dataDir: deps.dataDir, estimatedSnapshotBytes: estSnapshot, estimatedWorkingSetBytes: estWorkingSet, headroomFloor: deps.headroomFloor }, deps.spaceProbe);
+    let space = checkSpace({ dataDir: deps.dataDir, estimatedSnapshotBytes: estSnapshot, estimatedWorkingSetBytes: estWorkingSet }, deps.spaceProbe);
     if (!space.ok) {
         // ── Ladder step 2: prune snapshots, then retry ──
         pruneMigrationSnapshots(deps.snapshotRoot);
-        space = checkSpace({ dataDir: deps.dataDir, estimatedSnapshotBytes: estSnapshot, estimatedWorkingSetBytes: estWorkingSet, headroomFloor: deps.headroomFloor }, deps.spaceProbe);
+        space = checkSpace({ dataDir: deps.dataDir, estimatedSnapshotBytes: estSnapshot, estimatedWorkingSetBytes: estWorkingSet }, deps.spaceProbe);
     }
     if (!space.ok) {
         // ── Ladder step 5: no safe path → halt-don't-brick ──

package/dist/resources/migrations/space.js

@@ -13,9 +13,60 @@
  * `estimateWorkingSetBytes` below is the caller's job (the runner computes
  * it per risk class); this module just evaluates the estimate against real
  * (or test-overridden) disk free/total space.
+ *
+ * flair#720 rewrote the rule this module enforces. The original shape
+ * (`projectedUsedFraction <= 0.9`, measured against TOTAL disk size) was
+ * designed for a flair-dedicated volume, but on a general-purpose machine
+ * — a personal Mac especially, where APFS purgeable space makes
+ * `statfs.bavail` understate real availability — the system volume
+ * routinely sits above 90% used already, so the fraction test failed
+ * before a single byte was written, regardless of how trivially the
+ * migration's own footprint fit (flair#720: 220 KB needed, 18.6 GB free,
+ * halted anyway). The fix keeps invariant III's "never fill past a
+ * cushion" intent but measures the migration's OWN impact plus an
+ * absolute reserve, instead of the disk's pre-existing fullness:
+ * `ok = neededBytes <= freeBytes AND (freeBytes - neededBytes) >= reserve`.
+ * See `RESERVE_MIN_BYTES` / `RESERVE_MAX_BYTES` / `RESERVE_FRACTION` below
+ * for how `reserve` is derived.
  */
 import { statfsSync } from "node:fs";
-export const DEFAULT_HEADROOM_FLOOR = 0.9; // never project past 90% used
+/**
+ * Reserve floor: on any disk, no migration may leave less than this much
+ * free afterward, even on a tiny volume where 5% of total would be less.
+ * 256 MiB is comfortably more than any single migration's own working set
+ * in this codebase (the largest estimate is embedding/HNSW rebuild
+ * overhead, a few KB per row) — it exists to leave room for Harper's own
+ * ordinary operation (WAL, temp files, log growth), not the migration
+ * itself.
+ */
+export const RESERVE_MIN_BYTES = 256 * 1024 * 1024; // 256 MiB
+/**
+ * Reserve cap: on a large disk, 5% of total would be an unreasonably large
+ * cushion to demand (e.g. 50 GB on a 1 TB drive) for what is, worst case,
+ * a few GB of migration working set. 2 GiB caps the reserve so the rule
+ * stays proportionate to what migrations actually need, not the disk's
+ * raw size.
+ */
+export const RESERVE_MAX_BYTES = 2 * 1024 * 1024 * 1024; // 2 GiB
+/**
+ * Between the floor and the cap, the reserve scales with disk size: 5% of
+ * total. This is the "proportionate cushion" middle ground — big enough to
+ * matter on a mid-size disk, small enough not to dominate on either
+ * extreme (RESERVE_MIN_BYTES / RESERVE_MAX_BYTES clamp the two ends).
+ */
+export const RESERVE_FRACTION = 0.05;
+/**
+ * Production escape hatch for constrained deployments (flair#720) — e.g. a
+ * small dedicated volume where even the 256 MiB floor is more cushion than
+ * the operator can spare. When set to a finite, non-negative number, this
+ * overrides the computed reserve entirely (including the floor/cap clamp
+ * — set it to 0 to disable the reserve check outright, keeping only the
+ * `neededBytes <= freeBytes` fit test). Invalid values (non-numeric,
+ * negative, NaN, Infinity) are ignored and the computed reserve is used
+ * instead — mirrors TEST_FREE_BYTES_ENV's validation below. Unset (the
+ * default) in every normal deployment.
+ */
+export const RESERVE_BYTES_ENV = "FLAIR_MIGRATION_RESERVE_BYTES";
 /**
  * Test-only escape hatch: when set, overrides the real statfs-reported free
  * byte count. Used by the halt-on-blocked-space integration test (real
@@ -45,29 +96,72 @@ export const defaultSpaceProbe = {
     getTotalBytes: realGetTotalBytes,
 };
 /**
- * Evaluates the pre-flight space check. Fails (ok:false) if the needed
- * bytes don't fit in free space OR if consuming them would project disk
- * usage past the headroom floor — matching invariant III's "never fill past
- * ~90%" rule exactly (a technically-fitting migration that would still push
- * the disk to 95% full is refused, same as one that doesn't fit at all).
+ * Resolves the absolute reserve a migration must leave free afterward:
+ * `RESERVE_BYTES_ENV` if set to a valid (finite, >= 0) value, else
+ * `clamp(RESERVE_FRACTION * totalBytes, RESERVE_MIN_BYTES, RESERVE_MAX_BYTES)`.
+ * Exported so tests can exercise the clamp/override logic directly without
+ * going through a full `checkSpace` call.
+ */
+export function resolveReserveBytes(totalBytes, env = process.env) {
+    const override = env[RESERVE_BYTES_ENV];
+    if (override !== undefined) {
+        const n = Number(override);
+        if (Number.isFinite(n) && n >= 0)
+            return n;
+    }
+    const fractional = totalBytes * RESERVE_FRACTION;
+    return Math.min(RESERVE_MAX_BYTES, Math.max(RESERVE_MIN_BYTES, fractional));
+}
+/**
+ * Bytes → human readable (binary-based thresholds, decimal labels — same
+ * convention as src/render.ts's `humanBytes`, which this module can't
+ * import: resources/**\/*.ts and src/**\/*.ts are separate TypeScript
+ * project boundaries (tsconfig.json vs tsconfig.cli.json/tsconfig.check.src.json)
+ * — resources/ is Harper-loaded component code and never imports from the
+ * CLI's src/ tree. Small enough to duplicate locally rather than restructure
+ * the module boundary for one formatter.
+ */
+export function humanBytes(n) {
+    if (!Number.isFinite(n) || n < 0)
+        return "—";
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    if (n < 1024 * 1024 * 1024)
+        return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+    return `${(n / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+}
+/**
+ * Evaluates the pre-flight space check (flair#720's rule): fails (ok:false)
+ * if the needed bytes don't fit in free space outright, OR if spending them
+ * would leave less than `reserveBytes` free afterward. Unlike the rule this
+ * replaced, fullness that already exists on the disk before the migration
+ * runs is irrelevant — only the migration's OWN impact on free space is
+ * judged, against an absolute (not fraction-of-total) cushion.
  */
 export function checkSpace(input, probe = defaultSpaceProbe) {
-    const floor = input.headroomFloor ?? DEFAULT_HEADROOM_FLOOR;
     const freeBytes = probe.getFreeBytes(input.dataDir);
     const totalBytes = probe.getTotalBytes(input.dataDir);
     const neededBytes = input.estimatedSnapshotBytes + input.estimatedWorkingSetBytes;
-    const usedBytesNow = Math.max(0, totalBytes - freeBytes);
-    const projectedUsedBytes = usedBytesNow + neededBytes;
-    const projectedUsedFraction = totalBytes > 0 ? projectedUsedBytes / totalBytes : 1;
+    const reserveBytes = resolveReserveBytes(totalBytes);
     const fits = neededBytes <= freeBytes;
-    const withinFloor = projectedUsedFraction <= floor;
-    const ok = fits && withinFloor;
+    const remainingAfter = freeBytes - neededBytes;
+    const withinReserve = fits && remainingAfter >= reserveBytes;
+    const ok = fits && withinReserve;
     let reason;
-    if (!ok) {
+    if (!fits) {
+        reason =
+            `need ${humanBytes(neededBytes)} free (snapshot + migration working set), have ${humanBytes(freeBytes)} — ` +
+                `short by ${humanBytes(neededBytes - freeBytes)}. Set ${RESERVE_BYTES_ENV} to lower the required post-migration ` +
+                `reserve on constrained deployments (this won't help here — the migration doesn't fit even before any reserve)`;
+    }
+    else if (!withinReserve) {
         reason =
-            `need ${neededBytes} bytes free (snapshot + migration working set), have ${freeBytes}; ` +
-                `proceeding would exceed the ${Math.round(floor * 100)}% disk headroom floor — ` +
-                `prune old snapshots (flair keeps last-3/30-day) or set FLAIR_SNAPSHOT_DIR to a volume with more room`;
+            `need ${humanBytes(neededBytes)} free (snapshot + migration working set); have ${humanBytes(freeBytes)}, ` +
+                `which covers it but would leave only ${humanBytes(remainingAfter)} free afterward — short of the ` +
+                `${humanBytes(reserveBytes)} minimum reserve required post-migration. Set ${RESERVE_BYTES_ENV} to a lower ` +
+                `byte count to shrink the required reserve on constrained deployments`;
     }
-    return { ok, freeBytes, totalBytes, neededBytes, projectedUsedFraction, reason };
+    return { ok, freeBytes, totalBytes, neededBytes, reserveBytes, reason };
 }

package/dist/resources/provenance.js

@@ -1,5 +1,36 @@
 /**
- * ─── Write-time provenance stamp (memory-provenance slice 1) ────────────────
+ * Sanitize an optional, unverified `claimed.*` passthrough value (memory-
+ * provenance slice 1 + flair#718 authorship-provenance). Shared by BOTH
+ * `claimed.model` and `claimed.client` — same authority level, same
+ * discipline, one implementation so they can't drift:
+ *
+ *   1. Must be a `string` — anything else (number, object, array) is dropped.
+ *   2. Control characters (C0 + DEL, `\x00`-`\x1F`,`\x7F`) are stripped —
+ *      this is caller-supplied, unverified data landing in a stored JSON
+ *      blob; no newlines/nulls smuggled into logs or downstream renders.
+ *   3. Trimmed.
+ *   4. Length-capped at 200 chars (truncated, not rejected — a label this
+ *      long is almost certainly malformed, but the write must never fail
+ *      because of it).
+ *   5. Dropped (returns `undefined`) if empty after the above — an
+ *      all-control-chars or all-whitespace input is treated as absent, not
+ *      stamped as `""`.
+ *
+ * Sherlock flair#718 review: `claimed.model` previously had only a
+ * truthiness check (no cap, no sanitize) — folded into this same function
+ * "while touching the same code" per that review's non-blocking recommendation.
+ */
+function sanitizeClaim(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const cleaned = value.replace(/[\x00-\x1F\x7F]/g, "").trim();
+    if (cleaned.length === 0)
+        return undefined;
+    return cleaned.length > 200 ? cleaned.slice(0, 200) : cleaned;
+}
+/**
+ * ─── Write-time provenance stamp (memory-provenance slice 1; claimed.client
+ * added by flair#718 authorship-provenance) ──────────────────────────────────
  *
  * Foundational capture for an emergent-trust model: every write gets a
  * structured, versioned `provenance` JSON blob recording what the server can
@@ -8,7 +39,7 @@
  *
  *   { v: 1,
  *     verified: { agentId: <string|null>, timestamp: <ISO string> },
- *     claimed?: { model: <string> } }
+ *     claimed?: { model?: <string>, client?: <string> } }
  *
  * - `verified.agentId` comes from the ALREADY-RESOLVED auth verdict
  *   (resolveAgentAuth) — never from anything the caller can forge on the
@@ -23,10 +54,25 @@
  *   `embeddingModel = getModelId()` stamp in resources/Memory.ts.
  * - `claimed.model` is an OPTIONAL, UNVERIFIED passthrough: included only
  *   when the incoming write payload itself already carries a non-empty
- *   string `model` field. No client/CLI sets one today — this just means the
- *   server won't discard it if/when a future write path does. Never
- *   invented, never defaulted, and the `claimed` key is omitted entirely
- *   (not stamped as `{}`) when absent.
+ *   string `model` field (sanitized via sanitizeClaim above). Never
+ *   invented, never defaulted.
+ * - `claimed.client` (flair#718) is the SAME kind of OPTIONAL, UNVERIFIED
+ *   passthrough, sourced from `content.claimedClient` (a deliberately
+ *   distinct body-field name from the output key — see the write paths in
+ *   resources/Memory.ts / resources/Relationship.ts, which strip this field
+ *   from the row after calling buildProvenance so it is NEVER persisted
+ *   outside this provenance blob). Records WHICH CLIENT authored a write
+ *   under one shared principal (the personal deployment shape — see
+ *   docs/auth.md "Deployment shapes"). `claimed` — never `verified` —
+ *   because this is self-reported by an authenticated principal, not
+ *   independently corroborated: it MUST grant zero authority anywhere
+ *   (never read for access control, attribution weighting, or dedup
+ *   decisions — Sherlock flair#718 binding refinement). On the native /mcp
+ *   OAuth path, the caller is required to source this from the verified
+ *   `client_id` token claim, never the user-controlled `client_name` — see
+ *   resources/mcp-handler.ts's handleToolCall for that stamp site.
+ * - The `claimed` key is omitted entirely (not stamped as `{}`) when both
+ *   `model` and `client` are absent.
  *
  * Originally introduced in resources/Memory.ts (Memory.post()/Memory.put());
  * extracted here so Relationship.ts (and any future write path) can reuse the
@@ -43,8 +89,14 @@ export function buildProvenance(auth, createdAt, content) {
             timestamp: createdAt,
         },
     };
-    if (typeof content?.model === "string" && content.model.length > 0) {
-        provenance.claimed = { model: content.model };
+    const model = sanitizeClaim(content?.model);
+    const client = sanitizeClaim(content?.claimedClient);
+    if (model !== undefined || client !== undefined) {
+        provenance.claimed = {};
+        if (model !== undefined)
+            provenance.claimed.model = model;
+        if (client !== undefined)
+            provenance.claimed.client = client;
     }
     return JSON.stringify(provenance);
 }

package/dist/resources/record-type-kit.js

@@ -0,0 +1,253 @@
+/**
+ * record-type-kit.ts — shared, parameterized building blocks for a flair
+ * table's agent-identity / read-scope / no-forge-attribution machinery
+ * (record-types slice 1: kit extraction, flair#520).
+ *
+ * ─── What this is ────────────────────────────────────────────────────────
+ * Five flair-owned tables — Memory, Relationship, WorkspaceState, OrgEvent,
+ * Soul — each independently hand-copied ~150-250 lines of near-identical
+ * auth/scoping code: call resolveAgentAuth(getContext()), branch on the
+ * three-way verdict (internal / agent / anonymous), 404 a non-owner by-id
+ * read (never 403, so ids can't be enumerated), stamp agentId/authorId from
+ * the verified identity rather than the request body ("no-forge
+ * attribution"). Every allowRead() docstring in those five files literally
+ * says "same pattern as X.ts" — this module makes that pattern real code
+ * instead of a comment convention that can drift.
+ *
+ * ─── What this is NOT (scope discipline for slice 1) ─────────────────────
+ * This is a PURE REFACTOR extracting what is IDENTICAL across the five
+ * existing tables today. It is deliberately conservative, not the full
+ * `applyRecordTypeKit(policy)` composition sketched in the record-types
+ * design doc's §5 (that shape is for slice 2/3's registry, generating a
+ * COMPLETE {allowRead, get, search, post, put, delete} bundle for a
+ * brand-new consumer type with no bespoke logic). The five EXISTING tables
+ * genuinely diverge in real, load-bearing ways that must be preserved
+ * byte-for-byte, not papered over by a one-size bundle:
+ *   - search()'s query-merge shape differs per table (Memory detaches the
+ *     transaction and falls through differently on a bare query object than
+ *     WorkspaceState's in-place mutation than Relationship's nested-wrap);
+ *   - the no-forge attribution idiom differs not just per table but per
+ *     METHOD within a table (WorkspaceState.post() unconditionally stamps
+ *     with no mismatch check at all, while WorkspaceState.put() rejects a
+ *     mismatch and never stamps — see stampAttribution's mode doc below);
+ *   - delete() diverges the most: Memory.delete() doesn't even use
+ *     resolveAgentAuth (raw tpsAgent + isAdmin(), gated on the `permanent`
+ *     durability flag, no ownership check at all for non-permanent rows);
+ *     Soul has no delete() override; the other three each fetch the
+ *     pre-existing record with a different super.get() call signature.
+ *   - OrgEvent and Soul have NO get()/search() overrides at all (org events
+ *     and souls are readable by any verified agent, unscoped by owner) —
+ *     this module does not force them into a scope they never had.
+ * Each of those divergences stays inline in its resource file as visible,
+ * type-specific business logic. What THIS module extracts is only the
+ * genuinely-identical primitives underneath: the auth-gate three-way
+ * dispatch, the two read-scope condition/predicate shapes, the no-forge
+ * attribution idioms (named and parameterized, not merged into one), and
+ * the canonical error-response builders.  `buildProvenance` itself
+ * (./provenance.ts) is already table-agnostic and is reused as-is — this
+ * module does not wrap it, it re-exports it for a single import surface.
+ *
+ * Design lineage: flair#520 design draft (issue comment, 2026-07-13),
+ * Kern's DESIGN REVIEW ("the makeAuthGate/makeReadScope/buildProvenance
+ * as-is extraction is the right factoring... each class keeps its
+ * type-specific business logic visibly, loses only the copied
+ * boilerplate"). `stampEmbedding` (the design's 4th cut-line) is OUT of
+ * scope here — no table this module composes writes an embedding today
+ * (only Memory does, and Memory's embedding logic is dedup-gate-entangled,
+ * not part of the five-table auth/scope/provenance duplication this slice
+ * targets); it belongs to the registry/new-capability slice.
+ */
+import { resolveAgentAuth, allowVerified } from "./agent-auth.js";
+import { resolveReadScope } from "./memory-read-scope.js";
+import { buildProvenance } from "./provenance.js";
+export { buildProvenance };
+// ─── Canonical error responses ─────────────────────────────────────────────
+// Byte-for-byte the same bodies every one of the five files hand-rolled
+// (Memory/Relationship/WorkspaceState/OrgEvent each defined their own
+// FORBIDDEN/UNAUTH/NOT_FOUND consts identically; Soul only needed
+// FORBIDDEN/UNAUTH). Header-key casing is normalized here to "Content-Type"
+// — HTTP header names are case-insensitive (and Harper/undici's Headers
+// object normalizes on read), so this is not an observable behavior change
+// from the two files (Memory.ts, Relationship.ts) whose inline copies used
+// a lowercase "content-type" key.
+export const FORBIDDEN = (msg) => new Response(JSON.stringify({ error: msg }), { status: 403, headers: { "Content-Type": "application/json" } });
+export const UNAUTH = () => new Response(JSON.stringify({ error: "authentication required" }), { status: 401, headers: { "Content-Type": "application/json" } });
+export const NOT_FOUND = () => new Response(JSON.stringify({ error: "not found" }), { status: 404, headers: { "Content-Type": "application/json" } });
+// ─── (a) Identity gating — makeAuthGate ────────────────────────────────────
+/**
+ * Produces the `allowRead()` override every one of the five tables hand-
+ * wrote identically:
+ *   `allowRead() { return allowVerified((this as any).getContext?.()); }`
+ * Self-authorizes now that the global gate is non-rejecting (the
+ * memory-soul-read-gate family fix): Harper routes `GET /<Table>/<id>` to
+ * get() and the collection describe (`GET /<Table>`) to a path outside
+ * search(), so neither was gated before that fix landed — closes the same
+ * P0 leak (an anonymous caller getting a 200 with full record content) for
+ * every table that composes this. Per-record/collection scoping is still
+ * each table's own get()/search() responsibility below this gate.
+ *
+ * `allowVerified()` itself (permit verified agents, admins/super_user, and
+ * trusted internal calls; deny anonymous HTTP) already lives in
+ * ./agent-auth.ts and is reused unmodified — this factory exists only to
+ * remove the identical one-line method body duplicated five times, not to
+ * change what it does.
+ *
+ * MUST be composed as a genuine prototype method, never a class-field
+ * assignment (`allowRead = makeAuthGate();`). Harper's Table.js has a code
+ * path (`relatedTable.prototype.allowRead.call(null, user, property,
+ * context)`, used when a query's `select` traverses a GraphQL relationship
+ * into one of these tables under Harper's native attribute-level RBAC) that
+ * reads `allowRead` off the CLASS PROTOTYPE directly, not off a resource
+ * instance. A class field is an own-instance property — invisible to that
+ * lookup — so a class-field assignment would silently fall back to Harper's
+ * default RBAC-based `allowRead` for that one relationship-traversal path
+ * while every direct/primary call (`this.allowRead(...)`, always
+ * instance-invoked) kept working, making the gap easy to miss. Every
+ * caller of this factory MUST wire it as `allowRead() { return
+ * gate.call(this); }` (see Memory.ts/Relationship.ts/WorkspaceState.ts/
+ * OrgEvent.ts/Soul.ts for the exact pattern), not `allowRead =
+ * makeAuthGate();`.
+ */
+export function makeAuthGate() {
+    return function allowRead() {
+        return allowVerified(this.getContext?.());
+    };
+}
+export async function resolveAuthGate(ctx, denyResponse) {
+    const auth = await resolveAgentAuth(ctx);
+    if (auth.kind === "anonymous")
+        return { kind: "denied", response: denyResponse };
+    if (auth.kind === "internal" || (auth.kind === "agent" && auth.isAdmin))
+        return { kind: "unfiltered" };
+    return { kind: "scoped", agentId: auth.agentId };
+}
+/** owner-only: `agentId === authAgentId`, full stop — the model
+ *  Relationship.ts and WorkspaceState.ts hand-rolled identically for their
+ *  get()/search() overrides (`{attribute: ownerField, comparator: "equals",
+ *  value: authAgentId}` / `record[ownerField] !== authAgentId`). No
+ *  visibility field, no org-open exception — a real, legitimate read-scope
+ *  shape in its own right (per Kern/Sherlock's review), not a lesser
+ *  version of Memory's model. */
+function ownerOnlyReadScope(ownerField) {
+    return async (authAgentId) => ({
+        condition: { attribute: ownerField, comparator: "equals", value: authAgentId },
+        isAllowed: (record) => !!record && record[ownerField] === authAgentId,
+    });
+}
+/**
+ * Resolve the read-scope resolver for a table, by mode:
+ *   - "owner-only": own records only, scoped on `ownerField` (defaults to
+ *     "agentId" — every current owner-only caller uses that field; the
+ *     parameter exists so a future owner-only type using a different field,
+ *     the way OrgEvent's WRITE path uses "authorId", isn't hardcoded out).
+ *   - "open-within-org": delegates to the EXACT existing
+ *     resolveReadScope()/PRIVATE_VISIBILITY semantics in
+ *     ./memory-read-scope.ts — Memory's own module, untouched, not
+ *     reimplemented here. `ownerField` is ignored for this mode:
+ *     resolveReadScope() is hardcoded to "agentId" (the only table that
+ *     uses this mode today), matching the task's instruction to delegate to
+ *     that module "as the exact existing" implementation rather than
+ *     generalizing it in this slice.
+ *
+ * The returned resolver is tagged with its own `.mode`/`.ownerField` (record-
+ * types slice 2, flair#520) — harmless own-properties on the function object,
+ * never read by any caller of the resolver itself in production. Pinned by
+ * test/unit/record-type-kit.test.ts directly (mock-free — this primitive
+ * touches no `databases` mock). The registry's own drift tripwire
+ * (test/unit/record-types-registry.test.ts) verifies the five resource files
+ * draw their kit parameters from RECORD_TYPES via a source-text scan instead
+ * of importing them (see that test file's header for why — importing
+ * multiple of Memory.ts/Relationship.ts/WorkspaceState.ts together risks a
+ * cross-file Harper-mock module-cache collision); this tagging exists so a
+ * FUTURE single-resource-file behavior test (the pattern every existing
+ * table's own read-gate test already uses in isolation) can also assert
+ * `<table>ReadScope.mode === RECORD_TYPES.<Table>.readScope` directly against
+ * a live, exported resolver without re-deriving it.
+ */
+export function makeReadScope(mode, ownerField = "agentId") {
+    const resolve = mode === "open-within-org"
+        ? (authAgentId) => resolveReadScope(authAgentId)
+        : ownerOnlyReadScope(ownerField);
+    return Object.assign(resolve, { mode, ownerField });
+}
+/**
+ * By-id read-gate factory for get() overrides that scope a single-record
+ * read the same way search() scopes a collection read (Memory.ts,
+ * Relationship.ts, WorkspaceState.ts — NOT OrgEvent/Soul, which have no
+ * get() override at all and are intentionally left alone, see file header).
+ * Never distinguishes "doesn't exist" from "exists but not yours" — both
+ * return 404, never 403, so a denied caller can't use get() to enumerate
+ * other agents' record ids.
+ *
+ * `superGet` is a caller-supplied closure so the class's own `super.get()`
+ * (which cannot be referenced from outside the class body) stays exactly
+ * where it was.
+ */
+export function makeByIdReadGate(readScope) {
+    return async function byIdReadGate(target, superGet) {
+        // Collection / query reads arrive as a RequestTarget with
+        // `isCollection === true`, and are governed by search() (same owner
+        // scoping). Only a genuine by-id get is ownership-checked below.
+        if (!target || (typeof target === "object" && target.isCollection)) {
+            return this.search(target);
+        }
+        const ctx = this.getContext?.();
+        const auth = await resolveAgentAuth(ctx);
+        // Anonymous by-id read is already blocked at the allowRead() gate (403);
+        // this is defense-in-depth if get() is ever reached directly.
+        if (auth.kind === "anonymous")
+            return NOT_FOUND();
+        // Trusted internal call or admin agent — unfiltered, unchanged behavior.
+        if (auth.kind === "internal" || (auth.kind === "agent" && auth.isAdmin)) {
+            return superGet(target);
+        }
+        // Non-admin agent: scoped per the table's own read-scope model.
+        const record = await superGet(target);
+        if (!record)
+            return NOT_FOUND();
+        const scope = await readScope(auth.agentId);
+        if (!scope.isAllowed(record))
+            return NOT_FOUND();
+        return record;
+    };
+}
+export function stampAttribution(auth, content, field, mode, forbiddenMessage) {
+    if (auth.kind !== "agent")
+        return {}; // internal → always passthrough
+    if (auth.isAdmin) {
+        if (mode === "stamp-default")
+            content[field] ||= auth.agentId;
+        // every other mode: admin passthrough, untouched
+        return {};
+    }
+    // non-admin agent
+    switch (mode) {
+        case "validate-truthy":
+            if (content?.[field] && content[field] !== auth.agentId) {
+                return { denied: FORBIDDEN(forbiddenMessage) };
+            }
+            return {};
+        case "validate-strict":
+            if (content[field] !== auth.agentId) {
+                return { denied: FORBIDDEN(forbiddenMessage) };
+            }
+            return {};
+        case "stamp-default":
+            content[field] = auth.agentId;
+            return {};
+        case "stamp-strict":
+            if (content?.[field] && content[field] !== auth.agentId) {
+                return { denied: FORBIDDEN(forbiddenMessage) };
+            }
+            content[field] = auth.agentId;
+            return {};
+    }
+}
+// ─── (d) Provenance wiring ──────────────────────────────────────────────────
+// buildProvenance itself is already table-agnostic (./provenance.ts) and is
+// re-exported above, unmodified, for a single kit import surface. Per
+// Kern/Sherlock's DESIGN REVIEW verdict (Q4): stamp the identical shape
+// everywhere it's wired, never a table-specific format — and per this
+// slice's explicit behavior-preservation bar, do NOT wire it onto
+// WorkspaceState/OrgEvent, which don't stamp it today (only Memory and
+// Relationship do). See Memory.ts/Relationship.ts for the call sites.