@tpsdev-ai/flair 0.22.1 → 0.24.0

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.

package/dist/resources/record-types.js

@@ -0,0 +1,363 @@
+/**
+ * record-types.ts — the RecordType registry (record-types slice 2, flair#520).
+ *
+ * ─── What this is ────────────────────────────────────────────────────────
+ * The declared, PR-reviewed policy layer over resources/record-type-kit.ts
+ * (slice 1, flair#729): a static `RECORD_TYPES` map naming, for every
+ * flair-owned table, WHICH read-scope model it uses, WHICH no-forge
+ * attribution idiom it stamps on writes, whether it stamps provenance,
+ * whether it carries an embedding column, and whether it participates in
+ * federation — the five capabilities the flair#520 design draft's §4 laid
+ * out (identity / read-scope / provenance / semantic recall / REM), plus
+ * the attribution split slice 1 surfaced (four named idioms, not one) and
+ * the federation/MCP-shape refinements Kern and Sherlock's DESIGN REVIEW
+ * landed on the issue thread.
+ *
+ * This module is DATA, not a framework: `RecordTypePolicy` is a plain
+ * interface, `RECORD_TYPES` is a plain object literal. It does not derive
+ * MCP tools (that is slice 3 — see the `mcp` field's own doc below for why
+ * its SHAPE lands now without any consumer reading it yet), does not wire
+ * embeddings (Memory's embedding logic stays exactly where slice 1 left it
+ * — dedup-gate-entangled inline code in resources/Memory.ts, not routed
+ * through this registry), and does not change what Federation.ts/src/cli.ts
+ * actually sync (their hardcoded table lists are untouched — see the
+ * `federation` field's doc). Every field on every one of the five entries
+ * below documents CURRENT shipped behavior; none of them CHANGE it.
+ *
+ * ─── The static-registry invariant (non-negotiable) ───────────────────────
+ * Per §3 of the flair#520 design draft and Sherlock/Kern's unanimous
+ * verdict: this registry is STATIC, COMPILED, and PR-REVIEWED — never
+ * runtime-populated. A new entry lands via a PR to THIS file, same trust
+ * level as an entry in resources/mcp-tools.ts's TOOLS map. No component,
+ * consumer, or plugin can add itself to `RECORD_TYPES` at boot. This is the
+ * structural rejection of the exact failure mode Sherlock's review closed
+ * for cause on flair#541: Harper's native-MCP application profile
+ * auto-exposing every resource as a tool, with no allow/deny, at runtime.
+ * A dynamic `RECORD_TYPES` would reproduce that failure one layer up. If
+ * this ever needs to become an out-of-tree-extensible SDK (flair#520 §9
+ * calls that "a plausible later shape, not v1"), the review bar for that
+ * relaxation must be at least as high as the original #520/#541 decision.
+ *
+ * ─── Field-by-field rationale ─────────────────────────────────────────────
+ *
+ * `identity` — always "gated" for all five entries today. `makeAuthGate()`
+ * (record-type-kit.ts) only implements the "gated" posture (resolveAgentAuth
+ * + allowVerified — verified agents, admins, and trusted internal calls
+ * pass; anonymous HTTP is denied). "internal-only" is reserved for a future
+ * system table with no agent-facing surface at all — nothing wires it yet;
+ * a table setting it today would be a registry error, not a live capability.
+ *
+ * `readScope` — three values, not the two the original §4 draft proposed.
+ * "owner-only" and "open-within-org" are the two K&S-approved models
+ * (Relationship/WorkspaceState vs. Memory). The THIRD value, "none", names
+ * a real state that already ships and that record-type-kit.ts's own file
+ * header calls out explicitly: OrgEvent and Soul have NO get()/search()
+ * override at all — any verified agent (past the identity gate) reads
+ * every row, unscoped by owner, with no visibility field in play. That is
+ * neither "owner-only" (it is strictly broader — no ownership filter at
+ * all) nor "open-within-org" (there is no visibility-based private
+ * exception — nothing is excluded). Labeling OrgEvent/Soul "owner-only" to
+ * force them into the K&S-approved binary would be a FALSE registry entry —
+ * exactly the kind of drift a policy registry exists to prevent, and worse
+ * than just leaving the gap undocumented. This is a deliberate, disclosed
+ * extension of the flair#520 design draft's §4 shape (flagged in the
+ * slice-2 report for K&S to weigh in on), not a silent reinterpretation of
+ * their "owner-only | open-within-org" verdict.
+ *
+ * `readScope` narrowing is a BREAKING CHANGE, not covered by the
+ * additive-only discipline the design draft's §8 states for every other
+ * field. Per Sherlock's DESIGN REVIEW comment (explicitly concurred by
+ * Kern): flipping `open-within-org` → `owner-only`, or `none` → either
+ * narrower model, would retroactively hide rows other agents could already
+ * read — the same class of scrutiny as any other access-narrowing decision,
+ * called out separately here because it is easy to mis-file as "just
+ * editing a registry constant." WIDENING (owner-only → open-within-org, or
+ * either → none) is a normal, reviewable capability-addition PR. NARROWING
+ * requires the review bar of a genuine access-removal change: confirm
+ * nothing currently depends on the wider read, and treat it with the same
+ * weight as shipping a new private-visibility default.
+ *
+ * Review-gate tiering (Kern/Sherlock DESIGN REVIEW, Q1): a new entry with
+ * `readScope: "owner-only"` ships on the standard architecture-review bar.
+ * `readScope: "open-within-org"` (or, by the same logic, `"none"` — an even
+ * wider grant than open-within-org for records with no visibility concept
+ * at all) requires Sherlock's explicit security sign-off on the read-scope
+ * decision specifically, the same scrutiny Memory's own visibility work
+ * got. This registry's job is to make that decision a single reviewable
+ * line per type; the review-bar tiering itself is a process discipline for
+ * whoever reviews the PR, not something this module enforces in code.
+ *
+ * `attribution` — the four named `AttributionMode` idioms from
+ * record-type-kit.ts (`validate-truthy` / `validate-strict` /
+ * `stamp-default` / `stamp-strict`), keyed per WRITE METHOD
+ * (`post`/`put`), not one mode per type. This is the concrete thing slice 1
+ * surfaced that the original §4 draft did not anticipate: WorkspaceState
+ * and OrgEvent use a DIFFERENT idiom on post() (`stamp-default` — silent
+ * unconditional overwrite, never rejects) than on put()
+ * (`validate-strict` — rejects a mismatch, including an absent field).
+ * Collapsing that to one type-level `attributionMode` field would either be
+ * wrong for one of the two methods or would require silently converging
+ * post() onto put()'s stricter idiom — a real behavior change flagged but
+ * explicitly deferred by Flint's post-slice-1 comment on #520 ("Sherlock
+ * flagging stamp-default → stamp-strict convergence... Registry slice
+ * follows" — convergence is a FUTURE decision, not made here). Each
+ * sub-field is optional because not every table's write path calls
+ * `stampAttribution` on both methods: Relationship has no post() override
+ * at all (only `put`), so `attribution.post` is absent, not a placeholder.
+ * The stamped attribute name is always `ownerField` above — no type uses a
+ * different field for attribution vs. ownership scoping.
+ *
+ * `provenance` — true only for Memory and Relationship (the two tables that
+ * call `buildProvenance()` today and carry a nullable `provenance: String`
+ * schema field). WorkspaceState/OrgEvent/Soul are `false`: not an oversight
+ * — nobody wired it, and none of the three declare the schema field, so
+ * flipping this to `true` without a schema migration would be a lie the
+ * registry tells about what actually gets stamped.
+ *
+ * `embedding` — set only for Memory (`content` is the embedded field; the
+ * type has its own exposed semantic-search tool today — `memory_search` /
+ * resources/SemanticSearch.ts — hence `exposedSearch: true`). Declared for
+ * documentation ONLY in this slice: Memory's actual embedding logic stays
+ * exactly where slice 1's kit-extraction doc said it would stay — inline in
+ * resources/Memory.ts, dedup-gate-entangled, NOT routed through this
+ * registry or through a `stampEmbedding()` kit helper. Wiring is a later
+ * slice's job; this field exists so that slice doesn't need a breaking
+ * schema change to the policy shape when it lands (same reserved-flag
+ * pattern as `remEligible`).
+ *
+ * `remEligible` — MUST be `false` for every entry in v1 (typed as the
+ * literal `false`, not `boolean`, so a stray `true` is a compile error, not
+ * just a runtime policy mistake). REM's nightly gather step
+ * (specs/FLAIR-NIGHTLY-REM.md §11) is hardcoded to `GET /Memory?agentId=…`
+ * — single table, single agent, by construction. There is no multi-table
+ * distillation input path to opt into yet; the field exists so a future
+ * REM generalization doesn't require a breaking schema change to every
+ * existing entry.
+ *
+ * `federation` — "included" or "excluded", naming whether the type's rows
+ * currently CAN leave this instance via federation sync at all. This is
+ * DECLARATIVE ONLY in this slice, same discipline as `embedding` above:
+ * Federation.ts's `FederationSync.post()` table map and src/cli.ts's
+ * `runFederationSyncOnce`'s push table list are the actual, unchanged,
+ * hardcoded source of truth (`["Memory", "Soul", "Agent", "Relationship"]`)
+ * — this field documents what that hardcoded list already does per type,
+ * it does not drive it. Memory/Relationship/Soul are "included" because
+ * they are already in both lists (Memory's push additionally excludes
+ * `private`-visibility rows via classifyRecord — a finer-grained rule this
+ * boolean-ish field does not attempt to express). WorkspaceState/OrgEvent
+ * are "excluded" because they are in neither list today — org events and
+ * workspace state never leave the instance.
+ *
+ * For any FUTURE (non-core, consumer-defined) type, `federation` MUST be
+ * `"excluded"` — per Sherlock's DESIGN REVIEW (Q6, Kern concurring):
+ * DESIGN.md sequenced Memory's own open-within-org read AFTER federation
+ * hardening specifically so within-instance openness wouldn't outrun the
+ * one hard cross-instance boundary it depends on. A new type's registration
+ * must not silently inherit whatever Federation.ts's push filter does or
+ * doesn't already exclude — the filter does not know about new tables at
+ * all. Opting a new type into federation requires updating that filter
+ * FIRST, in its own reviewed PR, never the other order. This registry does
+ * not enforce that sequencing in code (there is no derivation from this
+ * field yet — see above); it is a review-time invariant for whoever adds
+ * the next entry.
+ *
+ * `mcp` — DECLARED AND ENFORCED as of slice 3 (flair#520 design review
+ * round 2, issue comment 2026-07-18 — Kern APPROVE all four asks, Sherlock
+ * APPROVE with one refinement, both unanimous). This field is the reviewed
+ * DECLARATION of the MCP surface, not a runtime generator: resources/
+ * mcp-tools.ts's hand-written `TOOLS` map stays the actual dispatch table.
+ * The slice-3 design round audited all 12 shipped tools and found only 5
+ * are simple table-verb wrappers (memory_get/store/delete, soul_get/set —
+ * and even the soul pair does bespoke `agentId:key` id synthesis); the rest
+ * are composite or bespoke (bootstrap, attention, memory_search,
+ * memory_update, record_usage) and cannot be generated from a registry
+ * entry without either losing schema/behavior specifics or duplicating the
+ * handler. Generating the 5 simple tools would also touch the
+ * security-critical `/mcp` dispatch path for zero behavior change, and
+ * runtime derivation from a registry is structurally the same failure
+ * flair#541 closed for cause (Harper's native-MCP auto-exposing every
+ * resource as a tool) one layer up. What declare-and-enforce buys instead:
+ * any PR that adds or removes an MCP tool must now also touch a policy
+ * chokepoint — either a `RECORD_TYPES.<Table>.mcp` declaration (table-verb
+ * tools) or the `COMPOSITE_MCP_TOOLS` allowlist below (everything else) —
+ * enforced bidirectionally by test/unit/mcp-surface-tripwire.test.ts, or CI
+ * fails. Declaring a verb here does not create a tool; it documents (and,
+ * via the tripwire, locks in) a tool resources/mcp-tools.ts already
+ * implements.
+ *
+ * Per Kern's DESIGN REVIEW refinement (Sherlock's Q5, Kern concurring): NOT
+ * a flat `verbs` array. `readVerbs` (get/search — same review bar as adding
+ * the type itself, since they exercise the same `readScope` the REST
+ * surface already exposes) is structurally separate from `writeVerbs`
+ * (store/delete/update — a write/delete/update surface over MCP, requiring
+ * its own explicit line-item sign-off). `"update"` was added to the
+ * `writeVerbs` union in slice 3 — APPROVED by both Kern and Sherlock as
+ * documenting `memory_update`'s already-shipped two-branch
+ * read-modify-write (in-place overwrite, or a `supersedes`-linked new
+ * version), not a new capability.
+ *
+ * Backfilled on FOUR of the five core entries below, documenting the
+ * CURRENT shipped surface exactly (slice-2 discipline: registration, not
+ * behavior change) — Memory (`get`/`search` reads; `store`/`delete`/
+ * `update` writes), Soul (`get` read; `store` write), WorkspaceState (no
+ * reads; `store` write), OrgEvent (no reads; `store` write). Relationship
+ * stays `mcp`-absent: it has no MCP tool today, and absent means no
+ * exposure, exactly as slice 2 defined.
+ *
+ * Verb→tool-name mapping (default `${toolPrefix}_${verb}`, with three
+ * overrides — `(Soul, store)` → `soul_set`, `(WorkspaceState, store)` →
+ * `flair_workspace_set`, `(OrgEvent, store)` → `flair_orgevent`) lives in
+ * resources/mcp-tools.ts's `TOOL_NAME_OVERRIDES`, not here. Per Kern/
+ * Sherlock's unanimous verdict: the registry declares WHAT is exposed
+ * (capability); mcp-tools.ts owns HOW (names, defaults, routing, input
+ * schema). Keeping presentation out of this file is what keeps
+ * `RecordTypeMcp` a pure capability declaration.
+ *
+ * See `COMPOSITE_MCP_TOOLS` below for the second — and only other —
+ * reviewed chokepoint: tools that are cross-table, aggregate, or otherwise
+ * cannot map to a single table + verb (`bootstrap`, `attention`,
+ * `record_usage`). Sherlock's slice-3 refinement (Kern concurring on the
+ * relocation) put that allowlist HERE, in record-types.ts, rather than in
+ * mcp-tools.ts — so the FULL MCP surface (table-verb tools and composites
+ * alike) is reviewable in this one file, not split across two.
+ *
+ * Design lineage: flair#520 design draft (issue comment, 2026-07-13) §4;
+ * Sherlock's Security Review (readScope narrowing, mandatory-vs-optional
+ * content-safety — NOT added here per Kern's Q3 verdict below —, structural
+ * readVerbs/writeVerbs split, federation-excluded default); Kern's DESIGN
+ * REVIEW (tiered review gate, readVerbs/writeVerbs, federation-excluded
+ * default, provenance-stamp-identical-shape); slice 1 kit extraction
+ * (flair#729, merged) whose file header first named the four attribution
+ * idioms and the OrgEvent/Soul unscoped-read state this module's `readScope`
+ * type makes explicit.
+ *
+ * Deliberately NOT added in this slice (Kern's DESIGN REVIEW Q3 verdict,
+ * explicit): a `contentSafety`/`scanFields` field. Sherlock proposed making
+ * content-safety scanning mandatory for any free-text field; Kern's verdict
+ * (which this implementation follows, per the task's explicit slice-2 scope)
+ * was NOT mandatory in v1 — generalizing `scanFields()` beyond Memory's
+ * hand-wired `content`/`summary` call needs its own design pass, and making
+ * it a blocking registration requirement would slow the easy win (data-layer
+ * -only registration with no MCP exposure). Left as a documented follow-up,
+ * not a silently-dropped field.
+ */
+// ─── The registry ───────────────────────────────────────────────────────────
+//
+// `as const satisfies Record<string, RecordTypePolicy>`: `satisfies` checks
+// every entry against `RecordTypePolicy` (catching an invalid readScope
+// value, a missing required field, etc. at compile time) WITHOUT widening
+// the expression's inferred type the way a `: Record<string,
+// RecordTypePolicy>` annotation would — so `RECORD_TYPES.Memory.readScope`
+// keeps its literal type `"open-within-org"`, not the widened union
+// `RecordTypeReadScopeMode`. That literal-preservation is what lets the five
+// resource classes below pass `RECORD_TYPES.<Table>.<field>` straight into
+// `makeReadScope()`/`stampAttribution()` (which expect the narrow literal
+// unions, not the wide ones) with no runtime cast or non-null assertion.
+export const RECORD_TYPES = {
+    Memory: {
+        table: "Memory",
+        ownerField: "agentId",
+        identity: "gated",
+        readScope: "open-within-org",
+        attribution: { post: "validate-truthy", put: "validate-truthy" },
+        provenance: true,
+        embedding: { field: "content", exposedSearch: true },
+        remEligible: false,
+        federation: "included",
+        mcp: { toolPrefix: "memory", readVerbs: ["get", "search"], writeVerbs: ["store", "delete", "update"] },
+    },
+    Relationship: {
+        table: "Relationship",
+        ownerField: "agentId",
+        identity: "gated",
+        readScope: "owner-only",
+        // No `post` — Relationship.ts has no post() override at all; only
+        // put() (upsert) calls stampAttribution.
+        attribution: { put: "stamp-strict" },
+        provenance: true,
+        remEligible: false,
+        federation: "included",
+    },
+    WorkspaceState: {
+        table: "WorkspaceState",
+        ownerField: "agentId",
+        identity: "gated",
+        readScope: "owner-only",
+        attribution: { post: "stamp-default", put: "validate-strict" },
+        provenance: false,
+        remEligible: false,
+        federation: "excluded",
+        mcp: { toolPrefix: "flair_workspace", readVerbs: [], writeVerbs: ["store"] },
+    },
+    OrgEvent: {
+        table: "OrgEvent",
+        ownerField: "authorId",
+        identity: "gated",
+        // No get()/search() override — any verified agent reads every org
+        // event, unscoped. See this module's header doc's `readScope` section.
+        readScope: "none",
+        attribution: { post: "stamp-default", put: "validate-strict" },
+        provenance: false,
+        remEligible: false,
+        federation: "excluded",
+        mcp: { toolPrefix: "flair_orgevent", readVerbs: [], writeVerbs: ["store"] },
+    },
+    Soul: {
+        table: "Soul",
+        ownerField: "agentId",
+        identity: "gated",
+        // No get()/search() override — souls are identity/discovery data,
+        // intentionally readable by any verified agent. See header doc.
+        readScope: "none",
+        attribution: { post: "validate-truthy", put: "validate-truthy" },
+        provenance: false,
+        remEligible: false,
+        federation: "included",
+        mcp: { toolPrefix: "soul", readVerbs: ["get"], writeVerbs: ["store"] },
+    },
+};
+// ─── Composite MCP tools (the second, and only other, reviewed chokepoint) ─
+//
+// Tools that do not map to a single table + verb — cross-table aggregates,
+// bespoke resources, or multi-source composites. These cannot be expressed
+// via `RECORD_TYPES.<Table>.mcp` (there is no single `table` to attach them
+// to), so slice 3's design round (Sherlock's refinement, Kern concurring —
+// see the `mcp` header doc above) makes this array the SECOND reviewed
+// chokepoint for the MCP surface: test/unit/mcp-surface-tripwire.test.ts
+// requires every tool name in resources/mcp-tools.ts's `TOOLS` map to be
+// either derived from a declared `RECORD_TYPES.<Table>.mcp` verb OR listed
+// here. A PR adding a new composite MCP tool (or renaming/removing one of
+// these three) must touch this array — same review bar as touching a
+// table's `mcp` field.
+//
+//   bootstrap    — Soul + Memory + predicted-context composite (BootstrapMemories)
+//   attention    — cross-table aggregate query (AttentionQuery.ts), not a table verb
+//   record_usage — usage-signal resource (RecordUsage.ts), not a table verb
+//
+export const COMPOSITE_MCP_TOOLS = ["bootstrap", "attention", "record_usage"];
+// ─── Runtime immutability ───────────────────────────────────────────────────
+// Belt-and-suspenders backstop for the "static, compiled" invariant (see
+// header doc). TypeScript's `as const satisfies` already gives compile-time
+// readonly types, but that alone does not stop a runtime consumer (a
+// resource file, a test, a hypothetical future dynamic-registration attempt)
+// from mutating a nested object in place — `RECORD_TYPES.Memory.readScope =
+// "owner-only"` is a type error at compile time but would silently SUCCEED
+// at runtime without this. Deep-freezing every entry and every nested
+// sub-object (attribution/embedding/mcp) makes an attempted mutation throw
+// (every .ts file in this repo compiles as an ES module, which is always
+// strict mode) instead of silently desyncing the registry from what a
+// resource file already composed at its own module-load time. Same
+// treatment for `COMPOSITE_MCP_TOOLS` — it is the second reviewed MCP-surface
+// chokepoint (see its own doc above) and gets the same static-registry
+// guarantee as RECORD_TYPES itself.
+function deepFreeze(value) {
+    if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+        for (const key of Object.getOwnPropertyNames(value)) {
+            deepFreeze(value[key]);
+        }
+        Object.freeze(value);
+    }
+    return value;
+}
+deepFreeze(RECORD_TYPES);
+deepFreeze(COMPOSITE_MCP_TOOLS);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.22.1",
+  "version": "0.24.0",
   "description": "Identity, memory, and soul for AI agents. Cryptographic identity (Ed25519), semantic memory with local embeddings, and persistent personality — all in a single process.",
   "type": "module",
   "license": "Apache-2.0",
@@ -55,10 +55,10 @@
   },
   "dependencies": {
     "@harperfast/harper": "5.1.17",
-    "@harperfast/oauth": "2.2.0",
+    "@harperfast/oauth": "2.4.0",
     "@types/js-yaml": "4.0.9",
     "commander": "14.0.3",
-    "harper-fabric-embeddings": "^0.3.0",
+    "harper-fabric-embeddings": "^0.5.0",
     "jose": "6.2.2",
     "js-yaml": "4.1.1",
     "node-llama-cpp": "3.18.1",

package/schemas/memory.graphql

@@ -53,7 +53,7 @@ type Memory @table(database: "flair") {
   validFrom: String @indexed   # ISO timestamp — when this fact became true
   validTo: String @indexed     # ISO timestamp — when this fact stopped being true (null = still valid)
   _safetyFlags: [String]       # content safety flags from scanContent()
-  provenance: String           # JSON blob (memory-provenance slice 1): { v, verified: { agentId, timestamp }, claimed?: { model } }
+  provenance: String           # JSON blob (memory-provenance slice 1; claimed.client added by flair#718): { v, verified: { agentId, timestamp }, claimed?: { model, client } }
                                # Nullable by design — existing rows read back provenance = null, unchanged behavior (clean-upgrade-path gate).
                                # Same idiom as Soul.metadata below. Stamped server-side in resources/Memory.ts; never client-writable.
   originatorInstanceId: String @indexed  # federation-edge-hardening slice 1: WRITE-TIME instance identity, stamped server-side in
@@ -99,7 +99,7 @@ type Relationship @table(database: "flair") {
                                     # for the full contract (write-time stamp, nullable, preserved across sync merges).
                                     # Stamped server-side in resources/Relationship.ts's put().
   provenance: String                # JSON blob (relationship-write-path, folded K&S refinement): SAME shape as
-                                    # Memory.provenance above — { v, verified: { agentId, timestamp }, claimed?: { model } }
+                                    # Memory.provenance above — { v, verified: { agentId, timestamp }, claimed?: { model, client } }
                                     # — via the shared resources/provenance.ts buildProvenance(), never a
                                     # Relationship-specific format. Nullable by design — pre-existing rows read back
                                     # provenance = null, unchanged behavior (migration-equivalence gate, same