@tpsdev-ai/flair 0.22.1 → 0.24.0

package/dist/resources/Soul.js

@@ -1,24 +1,32 @@
 import { databases } from "@harperfast/harper";
-import { resolveAgentAuth, allowVerified } from "./agent-auth.js";
+import { resolveAgentAuth } from "./agent-auth.js";
 import { localInstanceId } from "./instance-identity.js";
-const FORBIDDEN = (msg) => new Response(JSON.stringify({ error: msg }), { status: 403, headers: { "Content-Type": "application/json" } });
-const UNAUTH = () => new Response(JSON.stringify({ error: "authentication required" }), { status: 401, headers: { "Content-Type": "application/json" } });
+import { makeAuthGate, stampAttribution, UNAUTH } from "./record-type-kit.js";
+import { RECORD_TYPES } from "./record-types.js";
 /**
  * Deny anonymous; enforce per-agent write ownership for non-admin agents.
  * The previous header-based check only fired when an agent WAS present (it read
  * x-tps-agent), so an anonymous request — which carries no x-tps-agent — slipped
  * through. With the non-rejecting gate, each write path self-enforces (resolveAgentAuth
  * distinguishes internal/agent/anonymous). Mirrors the WorkspaceState pattern.
+ *
+ * No-forge attribution — mode/field drawn from RECORD_TYPES.Soul (record-
+ * types slice 2, flair#520) rather than hand-typed literals. "validate-
+ * truthy" (see record-type-kit.ts's stampAttribution doc) — rejects a
+ * PRESENT, mismatched agentId; passes through untouched when absent. Same
+ * idiom as Memory.post()/put().
  */
 async function enforceWriteAuth(self, data) {
     const auth = await resolveAgentAuth(self.getContext?.());
     if (auth.kind === "anonymous")
         return UNAUTH();
-    if (auth.kind === "agent" && !auth.isAdmin && data?.agentId && data.agentId !== auth.agentId) {
-        return FORBIDDEN("forbidden: agentId must match authenticated agent");
-    }
-    return null;
+    const attr = stampAttribution(auth, data, RECORD_TYPES.Soul.ownerField, RECORD_TYPES.Soul.attribution.post, "forbidden: agentId must match authenticated agent");
+    return attr.denied ?? null;
 }
+// See makeAuthGate's doc (record-type-kit.ts): must be wired as a genuine
+// prototype method below, never a class-field assignment — Harper's
+// relationship-traversal RBAC path reads allowRead off the prototype.
+const soulAuthGate = makeAuthGate();
 export class Soul extends databases.flair.Soul {
     /**
      * Self-authorize now that the global gate is non-rejecting. Closes the P0
@@ -30,7 +38,7 @@ export class Soul extends databases.flair.Soul {
      * verified agent — same posture as Agent.ts's allowRead. Write ownership
      * is unaffected — enforceWriteAuth() below already gates post()/put().
      */
-    allowRead() { return allowVerified(this.getContext?.()); }
+    allowRead() { return soulAuthGate.call(this); }
     async post(content, context) {
         const denied = await enforceWriteAuth(this, content);
         if (denied)

package/dist/resources/WorkspaceState.js

@@ -8,11 +8,23 @@
  * Use this.getContext() to access request context (tpsAgent, tpsAgentIsAdmin).
  */
 import { databases } from "@harperfast/harper";
-import { resolveAgentAuth, allowVerified } from "./agent-auth.js";
+import { resolveAgentAuth } from "./agent-auth.js";
 import { invalidEntitiesResponse } from "./entity-vocab.js";
-const FORBIDDEN = (msg) => new Response(JSON.stringify({ error: msg }), { status: 403, headers: { "Content-Type": "application/json" } });
-const UNAUTH = () => new Response(JSON.stringify({ error: "authentication required" }), { status: 401, headers: { "Content-Type": "application/json" } });
-const NOT_FOUND = () => new Response(JSON.stringify({ error: "not found" }), { status: 404, headers: { "Content-Type": "application/json" } });
+import { makeAuthGate, makeReadScope, makeByIdReadGate, resolveAuthGate, stampAttribution, FORBIDDEN, UNAUTH, } from "./record-type-kit.js";
+import { RECORD_TYPES } from "./record-types.js";
+// Parameterized from RECORD_TYPES.WorkspaceState (record-types slice 2,
+// flair#520) rather than a hand-typed "owner-only" literal — the registry is
+// now the single source of truth this class draws its read-scope mode from.
+// Exported solely so test/unit/record-types-registry.test.ts's drift
+// tripwire can introspect the composed resolver's tagged `.mode`/
+// `.ownerField` against RECORD_TYPES.WorkspaceState — not for any other
+// runtime consumer.
+export const workspaceReadScope = makeReadScope(RECORD_TYPES.WorkspaceState.readScope, RECORD_TYPES.WorkspaceState.ownerField);
+const workspaceByIdReadGate = makeByIdReadGate(workspaceReadScope);
+// See makeAuthGate's doc (record-type-kit.ts): must be wired as a genuine
+// prototype method below, never a class-field assignment — Harper's
+// relationship-traversal RBAC path reads allowRead off the prototype.
+const workspaceAuthGate = makeAuthGate();
 export class WorkspaceState extends databases.flair.WorkspaceState {
     /** Auth verdict from the request context. internal = trusted in-process call;
      *  agent = verified Ed25519; anonymous = HTTP with no valid agent → deny. */
@@ -29,13 +41,15 @@ export class WorkspaceState extends databases.flair.WorkspaceState {
      * full record content. Per-record ownership scoping happens in get() below;
      * the collection scope is still in search().
      */
-    allowRead() { return allowVerified(this.getContext?.()); }
+    allowRead() { return workspaceAuthGate.call(this); }
     /**
      * Override get() to scope by-id reads the same way search() scopes
      * collection reads (memory-soul-read-gate family fix). 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'
-     * workspace-state ids.
+     * workspace-state ids. Wired through record-type-kit.ts's
+     * makeByIdReadGate, scoped "owner-only" — same dispatch shape
+     * Memory.ts/Relationship.ts's get() use.
      */
     async get(target) {
         // Collection / query reads — the `GET /WorkspaceState/?<query>` form and
@@ -49,23 +63,7 @@ export class WorkspaceState extends databases.flair.WorkspaceState {
         if (!target || (typeof target === "object" && target.isCollection)) {
             return this.search(target);
         }
-        const auth = await this._auth();
-        // 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 super.get(target);
-        }
-        // Non-admin agent: only its own workspace-state records.
-        const record = await super.get(target);
-        if (!record)
-            return NOT_FOUND();
-        if (record.agentId !== auth.agentId)
-            return NOT_FOUND();
-        return record;
+        return workspaceByIdReadGate.call(this, target, (t) => super.get(t));
     }
     /**
      * Override search() to scope collection GETs to the authenticated agent's own
@@ -73,13 +71,15 @@ export class WorkspaceState extends databases.flair.WorkspaceState {
      * (previously `!authAgent` was treated as unfiltered — the anonymous-read leak).
      */
     async search(query) {
-        const auth = await this._auth();
-        if (auth.kind === "anonymous")
-            return UNAUTH();
-        if (auth.kind === "internal" || (auth.kind === "agent" && auth.isAdmin)) {
+        // Dispatch shape shared via record-type-kit.ts's resolveAuthGate — same
+        // three-way branch Memory.ts/Relationship.ts's search() use.
+        const gate = await resolveAuthGate(this.getContext?.(), UNAUTH());
+        if (gate.kind === "denied")
+            return gate.response;
+        if (gate.kind === "unfiltered")
             return super.search(query);
-        }
-        const agentIdCondition = { attribute: "agentId", comparator: "equals", value: auth.agentId };
+        const scope = await workspaceReadScope(gate.agentId);
+        const agentIdCondition = scope.condition;
         // Harper passes `query` as a request target object (pathname, id, isCollection…).
         // Inject the scope condition into its `.conditions` array.
         if (query && typeof query === "object" && !Array.isArray(query)) {
@@ -100,19 +100,20 @@ export class WorkspaceState extends databases.flair.WorkspaceState {
         // there was no authenticated agent, so anonymous could write any record).
         if (auth.kind === "anonymous")
             return UNAUTH();
-        // No-forge: a non-admin agent's workspace record is ALWAYS attributed to the
-        // authenticated identity (from the Ed25519 signature), never the body. We do
-        // NOT trust `content.agentId` — overwriting it (rather than 403'ing a
-        // mismatch) mirrors Presence.post(): "agentId from signature, NOT from body".
-        // An admin may write on behalf of another agent (content.agentId honored if
-        // present, else defaults to the admin's own id). Internal in-process callers
-        // keep whatever agentId they pass.
-        if (auth.kind === "agent" && !auth.isAdmin) {
-            content.agentId = auth.agentId;
-        }
-        else if (auth.kind === "agent" && auth.isAdmin) {
-            content.agentId ||= auth.agentId;
-        }
+        // No-forge attribution — mode/field drawn from RECORD_TYPES.WorkspaceState
+        // (record-types slice 2, flair#520) rather than hand-typed literals.
+        // "stamp-default" (see record-type-kit.ts's stampAttribution doc): a
+        // non-admin agent's workspace record is ALWAYS attributed to the
+        // authenticated identity (from the Ed25519 signature), never the body.
+        // We do NOT trust `content.agentId` — overwriting it (rather than
+        // 403'ing a mismatch) mirrors Presence.post(): "agentId from signature,
+        // NOT from body". An admin may write on behalf of another agent
+        // (content.agentId honored if present, else defaults to the admin's own
+        // id). Internal in-process callers keep whatever agentId they pass.
+        // "stamp-default" never denies (no rejection branch for non-admin) —
+        // the forbiddenMessage arg is dead for this mode, passed for signature
+        // completeness only.
+        stampAttribution(auth, content, RECORD_TYPES.WorkspaceState.ownerField, RECORD_TYPES.WorkspaceState.attribution.post, "forbidden: unreachable for stamp-default");
         content.createdAt = new Date().toISOString();
         content.timestamp ||= content.createdAt;
         // attention-plane vocabulary gate (flair#675): `entities`, if present,
@@ -127,9 +128,13 @@ export class WorkspaceState extends databases.flair.WorkspaceState {
         const auth = await this._auth();
         if (auth.kind === "anonymous")
             return UNAUTH();
-        if (auth.kind === "agent" && !auth.isAdmin && content.agentId !== auth.agentId) {
-            return FORBIDDEN("forbidden: cannot write workspace state for another agent");
-        }
+        // No-forge attribution — mode/field drawn from RECORD_TYPES.WorkspaceState.
+        // "validate-strict" (see record-type-kit.ts's stampAttribution doc):
+        // rejects a mismatch INCLUDING when agentId is absent (a bare `!==`
+        // compare, no truthy guard).
+        const attr = stampAttribution(auth, content, RECORD_TYPES.WorkspaceState.ownerField, RECORD_TYPES.WorkspaceState.attribution.put, "forbidden: cannot write workspace state for another agent");
+        if (attr.denied)
+            return attr.denied;
         // attention-plane vocabulary gate (flair#675) — same as post() above.
         const entitiesError = invalidEntitiesResponse(content.entities);
         if (entitiesError)
@@ -137,15 +142,14 @@ export class WorkspaceState extends databases.flair.WorkspaceState {
         return super.put(content);
     }
     async delete(id) {
-        const auth = await this._auth();
-        // Anonymous must NOT delete (previously `!agentId → super.delete` let anonymous
-        // delete any record).
-        if (auth.kind === "anonymous")
-            return UNAUTH();
-        if (auth.kind === "internal" || (auth.kind === "agent" && auth.isAdmin)) {
+        // Dispatch shape shared via record-type-kit.ts's resolveAuthGate — same
+        // three-way branch get()/search() above use.
+        const gate = await resolveAuthGate(this.getContext?.(), UNAUTH());
+        if (gate.kind === "denied")
+            return gate.response;
+        if (gate.kind === "unfiltered")
             return super.delete(id);
-        }
-        // Use super.get(id), NOT this.get(id): the new get() override above 404s
+        // Use super.get(id), NOT this.get(id): the get() override above 404s
         // (a truthy Response) for a non-owner id, which would otherwise defeat
         // the `if (!record)` check below and mis-route a genuinely-missing
         // record into the FORBIDDEN branch instead of a clean super.delete(id)
@@ -153,7 +157,7 @@ export class WorkspaceState extends databases.flair.WorkspaceState {
         const record = await super.get(id);
         if (!record)
             return super.delete(id);
-        if (record.agentId !== auth.agentId) {
+        if (record.agentId !== gate.agentId) {
             return FORBIDDEN("forbidden: cannot delete workspace state for another agent");
         }
         return super.delete(id);

package/dist/resources/agent-auth.js

@@ -16,7 +16,7 @@
  * 30s timestamp window + a per-(agent,nonce) seen-set pruned to that window.
  */
 import { databases } from "@harperfast/harper";
-import { WINDOW_MS, isNonceReplay, recordNonce, importEd25519Key, b64ToArrayBuffer } from "./ed25519-auth.js";
+import { WINDOW_MS, isNonceReplay, recordNonce, importEd25519Key, b64ToArrayBuffer, parseTpsEd25519Header } from "./ed25519-auth.js";
 /**
  * Shared Harper user that verified Ed25519 agents resolve to (least-privilege
  * `flair_agent` role), replacing the old admin super_user elevation. Single
@@ -56,15 +56,14 @@ async function getAdminAgents() {
 export async function isAdmin(agentId) {
     return (await getAdminAgents()).has(agentId);
 }
-const HEADER_RE = /^TPS-Ed25519\s+([^:]+):(\d+):([^:]+):(.+)$/;
 async function doVerify(request) {
     const header = request?.headers?.get?.("authorization") ??
         request?.headers?.asObject?.authorization ??
         "";
-    const m = HEADER_RE.exec(header);
-    if (!m)
+    const parsed = parseTpsEd25519Header(header);
+    if (!parsed)
         return null;
-    const [, agentId, tsRaw, nonce, signatureB64] = m;
+    const { agentId, tsRaw, nonce, signatureB64 } = parsed;
     const ts = Number(tsRaw);
     const now = Date.now();
     if (!Number.isFinite(ts) || Math.abs(now - ts) > WINDOW_MS)

package/dist/resources/auth-middleware.js

@@ -2,7 +2,7 @@ import { patchRecord } from "./table-helpers.js";
 import { server, databases } from "@harperfast/harper";
 import { getEmbedding } from "./embeddings-provider.js";
 import { isAdmin, FLAIR_AGENT_USERNAME } from "./agent-auth.js";
-import { WINDOW_MS, isNonceReplay, recordNonce, importEd25519Key, b64ToArrayBuffer } from "./ed25519-auth.js";
+import { WINDOW_MS, isNonceReplay, recordNonce, importEd25519Key, b64ToArrayBuffer, parseTpsEd25519Header } from "./ed25519-auth.js";
 import { resolveReadScope } from "./memory-read-scope.js";
 // --- Admin credentials ---
 // Admin auth is sourced exclusively from Harper's own environment variables
@@ -230,8 +230,8 @@ server.http(async (request, nextLayer) => {
         return nextLayer(request);
     }
     // ── Ed25519 agent auth ────────────────────────────────────────────────────
-    const m = header.match(/^TPS-Ed25519\s+([^:]+):(\d+):([^:]+):(.+)$/);
-    if (!m) {
+    const parsed = parseTpsEd25519Header(header);
+    if (!parsed) {
         // For browser-accessible admin pages, emit `WWW-Authenticate: Basic` so
         // the browser shows a native auth dialog instead of a bare 401 page.
         // JSON API endpoints don't get this — they should keep the structured
@@ -260,7 +260,7 @@ server.http(async (request, nextLayer) => {
         catch { /* frozen headers — annotation on the request object still applies */ }
         return nextLayer(request);
     }
-    const [, agentId, tsRaw, nonce, signatureB64] = m;
+    const { agentId, tsRaw, nonce, signatureB64 } = parsed;
     const ts = Number(tsRaw);
     const now = Date.now();
     if (!Number.isFinite(ts) || Math.abs(now - ts) > WINDOW_MS)

package/dist/resources/ed25519-auth.js

@@ -42,6 +42,43 @@ export { b64ToArrayBuffer };
  * stated "plugin-shaped, config via env" design intent.
  */
 export const WINDOW_MS = Number(process.env.FLAIR_AGENT_AUTH_WINDOW_MS) || 30_000;
+// ─── Auth header parsing (single shared implementation) ────────────────────
+//
+// One parser for the `Authorization: TPS-Ed25519 <id>:<ts>:<nonce>:<sig>`
+// header, used by all 3 call sites (auth-middleware.ts, agent-auth.ts,
+// Presence.ts) so the grammar and its input bounds can't drift.
+/**
+ * Upper bound on the accepted Authorization header length. A well-formed
+ * TPS-Ed25519 header (`TPS-Ed25519 <id>:<ts>:<nonce>:<sig>`) is a few hundred
+ * chars at most; anything materially larger is malformed. The header is
+ * untrusted client input, so we cap its length before running the regex,
+ * keeping parse cost bounded regardless of the input's shape.
+ */
+export const MAX_AUTH_HEADER_LEN = 4096;
+/**
+ * TPS-Ed25519 auth header grammar.
+ *
+ * The two colon-delimited text captures use `[^:\s]+` (not `[^:]+`) so they are
+ * disjoint from the preceding `\s+`: with no character shared between the two
+ * adjacent quantifiers there is exactly one way to split any input, so matching
+ * is linear-time on every input (including long, degenerate ones). A real
+ * agentId / nonce / signature never contains whitespace, so excluding it is
+ * behavior-preserving for well-formed headers.
+ */
+export const TPS_ED25519_HEADER_RE = /^TPS-Ed25519\s+([^:\s]+):(\d+):([^:\s]+):(.+)$/;
+/**
+ * Parse a TPS-Ed25519 `Authorization` header value into its fields, or return
+ * null if it is over `MAX_AUTH_HEADER_LEN` or doesn't match the grammar.
+ * Callers treat null exactly as a header that carries no valid agent auth.
+ */
+export function parseTpsEd25519Header(header) {
+    if (!header || header.length > MAX_AUTH_HEADER_LEN)
+        return null;
+    const m = TPS_ED25519_HEADER_RE.exec(header);
+    if (!m)
+        return null;
+    return { agentId: m[1], tsRaw: m[2], nonce: m[3], signatureB64: m[4] };
+}
 // ─── Replay guard (single shared instance) ─────────────────────────────────
 //
 // nonceSeen is the ONE module-level singleton — the whole point of this

package/dist/resources/embeddings-boot.js

@@ -87,6 +87,41 @@
 import { resolveModelsDir } from "./embeddings-provider.js";
 const LOGICAL_NAME = "default";
 const MODEL_NAME = "nomic-embed-text";
+/**
+ * Pooling declaration (HFE 0.5.0+, harper-fabric-embeddings' `init()`
+ * `pooling` option). Verification, not override: the native addon has no
+ * pooling knob of its own — llama.cpp always pools by whatever the GGUF's
+ * own `<arch>.pooling_type` metadata says. Declaring the expectation makes
+ * HFE assert it at init and fail loudly on absent/mismatched metadata,
+ * instead of a metadata-less or mismatched conversion silently pooling the
+ * wrong way (see node_modules/harper-fabric-embeddings/README.md's `init()`
+ * table for the exact contract this PR bumps to).
+ *
+ * "mean" is nomic-embed-text-v1.5's actual pooling type — NOT assumed from
+ * the model's reputation, directly confirmed against the shipped GGUF:
+ * `node_modules/.bin/node-llama-cpp inspect gguf
+ * ~/.flair/data/models/nomic-embed-text-v1.5.Q4_K_M.gguf` reports
+ * `"nomic-bert": { pooling_type: 1 }`, and llama.cpp's
+ * `enum llama_pooling_type` maps 1 -> `LLAMA_POOLING_TYPE_MEAN` (0 = none,
+ * 1 = mean, 2 = cls, 3 = last, 4 = rank). nomic-embed-text is a
+ * NomicBertModel architecture, not Qwen3 (last-token) — flair registers no
+ * Qwen3-class embedding model today (the Qwen3-Reranker-0.6B in
+ * resources/rerank-provider.ts is a SEPARATE code path that calls
+ * node-llama-cpp directly for generative yes/no scoring, never goes through
+ * HFE's register()/init(), and has no embedding-pooling context at all — see
+ * that file's header). If a Qwen3-class (last-token-pooling) embedding model
+ * is ever registered here, it must declare `pooling: "last"`, not "mean".
+ *
+ * Applies to the bench-only `modelPath` override too (`benchModelPathOverride()`
+ * below): `FLAIR_RECALL_HARNESS_MODEL_PATH` lets an operator point this
+ * registration at an arbitrary GGUF for a Q4/Q8 bakeoff, and this constant
+ * assumes whatever file lands there is still nomic-family (mean-pooling) —
+ * true for every bakeoff run to date (same base model, different quant).
+ * HFE 0.5.0's verification is exactly the safety net that turns "someone
+ * points --model-file at a non-nomic, non-mean-pooling GGUF" into a loud
+ * boot-time failure instead of a silently-wrong pooling pass.
+ */
+const EMBEDDING_POOLING = "mean";
 /**
  * BENCH-ONLY escape hatch — NOT a production feature flag, never documented
  * as an operator setting, and never read anywhere else in this codebase.
@@ -131,7 +166,9 @@ export async function registerEmbeddingsBackend() {
         await register({
             logicalName: LOGICAL_NAME,
             kind: "embedding",
-            config: modelPath ? { modelPath } : { modelName: MODEL_NAME, modelsDir: resolveModelsDir() },
+            config: modelPath
+                ? { modelPath, pooling: EMBEDDING_POOLING }
+                : { modelName: MODEL_NAME, modelsDir: resolveModelsDir(), pooling: EMBEDDING_POOLING },
         });
     }
     catch (err) {

package/dist/resources/mcp-handler.js

@@ -65,12 +65,21 @@ function jitProvisionEnabled() {
  * XAA's ID-JAG path uses (resources/XAA.ts resolveOrCreatePrincipal) — one
  * identity model, keyed on the IdP subject.
  *
+ * `clientId` (flair#718 authorship-provenance) is NOT part of sub resolution —
+ * it rides along from the verified token's `client_id` claim (see
+ * handleToolCall's stamp-site comment for why `client_id` and never
+ * `client_name`) and is copied onto the resolved agent unchanged so downstream
+ * write tools (memory_store/memory_update) can thread it into `claimedClient`.
+ * Omitted from the returned object entirely when absent — never stamped as
+ * `undefined` — so existing callers/tests that don't pass one see the exact
+ * same `{ agentId, isAdmin }` shape as before this field existed.
+ *
  * Returns:
- *   - `{ agentId, isAdmin }` when a Credential maps the sub to an Agent.
+ *   - `{ agentId, isAdmin, clientId? }` when a Credential maps the sub to an Agent.
  *   - null when no Credential maps the sub AND JIT-provisioning is disabled or
  *     failed → the handler denies the tool call (sub is unresolvable).
  */
-export async function resolveAgentFromSub(sub) {
+export async function resolveAgentFromSub(sub, clientId) {
     if (!sub)
         return null;
     // 1. Existing IdP credential → its principalId is the Agent id.
@@ -87,7 +96,10 @@ export async function resolveAgentFromSub(sub) {
                     await databases.flair.Credential.put({ ...cred, lastUsedAt: new Date().toISOString() });
                 }
                 catch { /* non-fatal */ }
-                return { agentId: String(cred.principalId), isAdmin: await isAgentAdmin(cred.principalId) };
+                const resolved = { agentId: String(cred.principalId), isAdmin: await isAgentAdmin(cred.principalId) };
+                if (clientId)
+                    resolved.clientId = clientId;
+                return resolved;
             }
         }
     }
@@ -98,7 +110,10 @@ export async function resolveAgentFromSub(sub) {
     try {
         const principalId = await jitProvisionPrincipal(sub);
         // A JIT-provisioned principal is a fresh, non-admin agent by construction.
-        return { agentId: principalId, isAdmin: false };
+        const resolved = { agentId: principalId, isAdmin: false };
+        if (clientId)
+            resolved.clientId = clientId;
+        return resolved;
     }
     catch {
         return null;
@@ -221,7 +236,16 @@ async function handleToolCall(request, id, params) {
     if (!sub) {
         return rpcError(id, -32001, "unauthorized: no verified token subject");
     }
-    const agent = await resolveAgentFromSub(String(sub));
+    // flair#718 authorship-provenance, Sherlock's binding refinement: source
+    // the authorship stamp from `client_id` (the server-generated
+    // `flair_cl_...` machine id — resources/OAuth.ts, an RS256-verified JWT
+    // claim, not a secret) — NEVER `client_name` (a free-text label the client
+    // supplied at Dynamic Client Registration time and fully controls). Do NOT
+    // "helpfully" switch this to `client_name` for a prettier label; that would
+    // turn a server-verified, stable id into caller-forgeable data landing in
+    // stored provenance. Absent/non-string client_id → omitted, not invented.
+    const clientId = typeof request?.mcp?.client_id === "string" ? request.mcp.client_id : undefined;
+    const agent = await resolveAgentFromSub(String(sub), clientId);
     if (!agent) {
         // Sub verified by the AS but not mapped to a flair Agent (and JIT disabled /
         // failed). Deny — do NOT fall back to anonymous or admin.

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/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);
 }