@tpsdev-ai/flair 0.22.1 → 0.24.0

package/dist/probe.js

@@ -64,27 +64,40 @@ export async function probeInstance(baseUrl, opts = {}) {
             version: null,
             versionMatch: null,
             ok: false,
+            authFailureKind: null,
             error: `instance did not answer ${base}/Health within ${timeoutMs}ms` +
                 (lastHealthError ? ` (last error: ${lastHealthError})` : ""),
         };
     }
     if (!authedGet) {
-        return { healthy: true, authenticated: null, version: null, versionMatch: null, ok: true };
+        return { healthy: true, authenticated: null, version: null, versionMatch: null, ok: true, authFailureKind: null };
     }
     let version = null;
     let authError;
+    let authFailureKind = null;
     try {
         const body = await authedGet(versionPath);
         version = typeof body?.version === "string" ? body.version : null;
     }
     catch (err) {
         authError = err?.message ?? String(err);
+        // flair#741: classify the failure so callers can tell "server responded,
+        // credentials rejected" (liveness proven) from "can't tell what state
+        // this instance is in". Duck-typed on `.status` — any authedGet
+        // implementation can opt in by throwing an error with a numeric status;
+        // api() (src/cli.ts) does via ApiHttpError. No recognizable status (a
+        // plain network error, or an authedGet that doesn't set one) stays
+        // conservative and lands in "server".
+        const status = typeof err?.status === "number" ? err.status : null;
+        authFailureKind = status === 401 || status === 403 ? "credentials" : "server";
     }
     const authenticated = authError === undefined;
     let versionMatch = null;
     if (authenticated && expectVersion !== undefined) {
         versionMatch = version === expectVersion;
     }
+    if (authenticated)
+        authFailureKind = null;
     const ok = healthy && authenticated && versionMatch !== false;
     let error;
     if (!authenticated) {
@@ -93,5 +106,5 @@ export async function probeInstance(baseUrl, opts = {}) {
     else if (versionMatch === false) {
         error = `version mismatch: expected ${expectVersion}, instance reports ${version ?? "unknown"}`;
     }
-    return { healthy, authenticated, version, versionMatch, ok, error };
+    return { healthy, authenticated, version, versionMatch, ok, error, authFailureKind };
 }

package/dist/resources/Memory.js

@@ -1,29 +1,44 @@
 import { databases } from "@harperfast/harper";
 import { patchRecord, withDetachedTxn } from "./table-helpers.js";
-import { isAdmin, resolveAgentAuth, allowVerified } from "./agent-auth.js";
+import { isAdmin, resolveAgentAuth } from "./agent-auth.js";
 import { localInstanceId } from "./instance-identity.js";
 import { getEmbedding, getModelId } from "./embeddings-provider.js";
 import { scanFields, isStrictMode } from "./content-safety.js";
 import { invalidEntitiesResponse } from "./entity-vocab.js";
 import { checkRateLimit, rateLimitResponse } from "./rate-limiter.js";
-import { resolveReadScope } from "./memory-read-scope.js";
 import { DEDUP_COSINE_THRESHOLD_DEFAULT, DEDUP_LEXICAL_THRESHOLD_DEFAULT, DEDUP_MIN_CONTENT_LENGTH, computeMatchConfidence, cosineSimilarity, isConservativeMatch, } from "./dedup.js";
-import { buildProvenance } from "./provenance.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 { buildProvenance, makeAuthGate, makeReadScope, makeByIdReadGate, resolveAuthGate, stampAttribution, FORBIDDEN, UNAUTH, } from "./record-type-kit.js";
+import { RECORD_TYPES } from "./record-types.js";
 /**
- * Owner ids a non-admin agent may READ (resolveAllowedOwners) and the full
- * read-scope condition + private-exclusion predicate (resolveReadScope) now
- * live in ./memory-read-scope.ts — the ONE centralized helper every
- * cross-agent Memory read path (search()/get() here, SemanticSearch.ts,
- * MemoryBootstrap.ts, auth-middleware.ts's by-id guard) resolves its scope
- * through, so the scoping rule cannot drift per-path again (a
- * SemanticSearch inline `visibility === "office"` OR-clause leaked office
- * memories to any authenticated agent because the rule had scattered). See
- * that module's doc for the migration invariant (no-visibility-field reads
- * as "shared", never "private").
+ * Owner ids a non-admin agent may READ (resolveAllowedOwners) live in
+ * ./memory-read-scope.ts — still exported/used elsewhere (admin tooling).
+ * The full read-scope condition + private-exclusion predicate is now
+ * consumed through ./record-type-kit.ts's makeReadScope(), parameterized
+ * from RECORD_TYPES.Memory (record-types slice 2, flair#520) rather than a
+ * hand-typed "open-within-org" literal — the registry is now the single
+ * source of truth this class draws its read-scope mode from. makeReadScope
+ * delegates "open-within-org" to ./memory-read-scope.ts's resolveReadScope()
+ * UNCHANGED — the ONE centralized helper every cross-agent Memory read path
+ * (search()/get() here, SemanticSearch.ts, MemoryBootstrap.ts, auth-
+ * middleware.ts's by-id guard) resolves its scope through, so the scoping
+ * rule cannot drift per-path again (a SemanticSearch inline
+ * `visibility === "office"` OR-clause leaked office memories to any
+ * authenticated agent because the rule had scattered). See memory-read-
+ * scope.ts's doc for the migration invariant (no-visibility-field reads as
+ * "shared", never "private").
+ *
+ * Exported (not just a module-local const) solely so
+ * test/unit/record-types-registry.test.ts's drift tripwire can introspect
+ * the composed resolver's tagged `.mode`/`.ownerField` (see makeReadScope's
+ * doc in record-type-kit.ts) against RECORD_TYPES.Memory — not for any
+ * other runtime consumer.
  */
+export const memoryReadScope = makeReadScope(RECORD_TYPES.Memory.readScope, RECORD_TYPES.Memory.ownerField);
+const memoryByIdReadGate = makeByIdReadGate(memoryReadScope);
+// 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 memoryAuthGate = makeAuthGate();
 /**
  * ─── Server-side conservative-duplicate gate (memory-integrity fix) ──────────
  *
@@ -276,8 +291,26 @@ async function hasWriteGrant(granteeId, ownerId) {
  * requires a "write" MemoryGrant from the target's owner (reuses the existing
  * agent-auth/grant machinery — no parallel auth logic). Returns a Response to
  * short-circuit with (400/403), or null to continue.
+ *
+ * flair#704: an explicit `supersedes: null` — the shape most JSON writers
+ * produce for an unset optional field (`JSON.stringify({supersedes: undefined})`
+ * drops the key, but plenty of writers instead do `{supersedes: x ?? null}`)
+ * — must be treated identically to the key being OMITTED, per the
+ * additive-schema convention (flair#695: an explicit null on an
+ * optional/nullable field reads as absent, not as a distinct value). Fixed by
+ * deleting the key BEFORE the type check below, so (a) the check never
+ * rejects it, and (b) `super.put()`/`super.post()` — Harper full-record
+ * replacement, see table-helpers.ts's header comment — never persists a
+ * literal `null` where "absent" was intended: the stored row ends up
+ * byte-for-byte identical to the omitted-key case, so every downstream
+ * `!content.supersedes` / `content.supersedes &&` check below (and in
+ * closeSupersededIfNeeded) already treats it as unset with no further
+ * changes needed.
  */
 async function validateAndAuthorizeSupersedes(content, auth) {
+    if (content.supersedes === null) {
+        delete content.supersedes;
+    }
     if (content.supersedes !== undefined && typeof content.supersedes !== "string") {
         return new Response(JSON.stringify({ error: "supersedes must be a string (memory ID)" }), {
             status: 400, headers: { "Content-Type": "application/json" },
@@ -335,14 +368,16 @@ function defaultVisibilityForDurability(durability) {
 /**
  * ─── Write-time provenance stamp (memory-provenance slice 1) ────────────────
  *
- * `buildProvenance` itself now lives in ./provenance.ts (imported above) —
+ * `buildProvenance` itself lives in ./provenance.ts, re-exported unmodified
+ * via ./record-type-kit.ts (imported above) for a single kit import surface —
  * extracted so resources/Relationship.ts's write path can reuse the EXACT
  * same `{v, verified, claimed?}` shape (the relationship-write-path spec's
  * "reuse buildProvenance as-is" contract) instead of a hand-copied format
  * that could drift. See that module for the full field-by-field rationale
  * (verified.agentId from the auth verdict never the body, verified.timestamp
- * = the server-computed createdAt, optional unverified claimed.model
- * passthrough). Deliberately NOT implemented in this slice: a
+ * = the server-computed createdAt, optional unverified claimed.model /
+ * claimed.client passthroughs — the latter added by flair#718 authorship-
+ * provenance). Deliberately NOT implemented in this slice: a
  * context-fingerprint field — bootstrap doesn't return the IDs a fingerprint
  * would need, so it requires client cooperation that's out of scope here.
  */
@@ -394,13 +429,15 @@ export class Memory extends databases.flair.Memory {
      * unverified, risks regressing owner writes/deletes on a P0 security fix
      * that is scoped to the read leak — left as-is on purpose.
      */
-    allowRead() { return allowVerified(this.getContext?.()); }
+    allowRead() { return memoryAuthGate.call(this); }
     /**
      * Override get() to scope by-id reads the same way search() scopes
      * collection reads (memory-soul-read-gate 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'
-     * memory ids.
+     * memory ids. Wired through record-type-kit.ts's makeByIdReadGate, scoped
+     * with Memory's own "open-within-org" read-scope resolver above — same
+     * dispatch shape Relationship.ts/WorkspaceState.ts's get() overrides use.
      */
     async get(target) {
         // Collection / query reads — the `GET /Memory/?<query>` form and the bare
@@ -412,31 +449,13 @@ export class Memory extends databases.flair.Memory {
         // authenticated self-query would 404 (regression caught by the auth-
         // middleware e2e "TPS-Ed25519 on GET /Memory/?agentId=X → 200"). A by-id
         // get (RequestTarget with isCollection false, or a bare id) falls through.
+        // makeByIdReadGate re-applies this same guard internally (delegating to
+        // this.search via `.call(this, ...)`) — kept here too as documentation of
+        // the invariant at the call site, harmless no-op double-check.
         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 super.get(target);
-        }
-        // Non-admin agent: only its own memories (any visibility), or a granted
-        // owner's SHARED memories — never that owner's private ones (Layer 1
-        // private-exclusion). Centralized in resolveReadScope() so this
-        // and search() below cannot drift.
-        const record = await super.get(target);
-        if (!record)
-            return NOT_FOUND();
-        const scope = await resolveReadScope(auth.agentId);
-        if (!scope.isAllowed(record))
-            return NOT_FOUND();
-        return record;
+        return memoryByIdReadGate.call(this, target, (t) => super.get(t));
     }
     /**
      * Override search() to scope collection GETs by authenticated agent.
@@ -451,23 +470,24 @@ export class Memory extends databases.flair.Memory {
     async search(query) {
         // Access request context via Harper's Resource instance context.
         const ctx = this.getContext?.();
-        const auth = await resolveAgentAuth(ctx);
         // Anonymous HTTP must NOT read memories. (Previously `!authAgent` was treated
         // as unfiltered — the anonymous-read leak once the gate stops rejecting.)
-        if (auth.kind === "anonymous") {
-            return new Response(JSON.stringify({ error: "authentication required" }), {
-                status: 401, headers: { "content-type": "application/json" },
-            });
-        }
         // Trusted internal call (no request context) or admin agent — unfiltered.
-        if (auth.kind === "internal" || (auth.kind === "agent" && auth.isAdmin)) {
+        // Non-admin agent: scoped below. Dispatch shape shared via
+        // record-type-kit.ts's resolveAuthGate — same three-way branch
+        // Relationship.ts/WorkspaceState.ts's search() use.
+        const gate = await resolveAuthGate(ctx, UNAUTH());
+        if (gate.kind === "denied")
+            return gate.response;
+        if (gate.kind === "unfiltered")
             return super.search(query);
-        }
         // Non-admin agent: scope to own (any visibility) + granted owners' SHARED
         // memories only (Layer 1 private-exclusion). Centralized in
-        // resolveReadScope() so get() above and search() here cannot drift.
-        const authAgent = auth.agentId;
-        const scope = await resolveReadScope(authAgent);
+        // memoryReadScope (record-type-kit.ts's makeReadScope(), parameterized
+        // from RECORD_TYPES.Memory — see this file's header — delegating
+        // "open-within-org" to memory-read-scope.ts's resolveReadScope()
+        // unchanged) so get() above and search() here cannot drift.
+        const scope = await memoryReadScope(gate.agentId);
         const agentIdCondition = scope.condition;
         // Harper passes `query` as a RequestTarget (extends URLSearchParams) or a
         // conditions array. For URL-based GET /Memory?... calls, URL params are no
@@ -509,9 +529,14 @@ export class Memory extends databases.flair.Memory {
             if (auth.kind === "anonymous") {
                 return UNAUTH();
             }
-            if (auth.kind === "agent" && !auth.isAdmin && content?.agentId && content.agentId !== auth.agentId) {
-                return FORBIDDEN("forbidden: cannot write memory owned by another agent");
-            }
+            // No-forge attribution — mode/field drawn from RECORD_TYPES.Memory
+            // (record-types slice 2, flair#520) rather than a hand-typed literal.
+            // "validate-truthy" (see record-type-kit.ts's stampAttribution doc):
+            // reject a PRESENT, mismatched agentId; never stamp when absent (the
+            // caller is expected to have set it).
+            const attr = stampAttribution(auth, content, RECORD_TYPES.Memory.ownerField, RECORD_TYPES.Memory.attribution.post, "forbidden: cannot write memory owned by another agent");
+            if (attr.denied)
+                return attr.denied;
         }
         content.durability ||= "standard";
         content.createdAt = new Date().toISOString();
@@ -605,6 +630,12 @@ export class Memory extends databases.flair.Memory {
         // buildProvenance's doc above. Stamped last, right before persist, so it
         // reflects the final resolved `content.createdAt`.
         content.provenance = buildProvenance(auth, content.createdAt, content);
+        // flair#718 authorship-provenance: `claimedClient` is a WRITE-BODY-ONLY
+        // passthrough — buildProvenance above already folded it into
+        // `provenance.claimed.client` (sanitized/capped). Strip it from the row
+        // itself so it is NEVER persisted as a second, undeclared/unsanitized
+        // top-level field — authorship lives in the provenance JSON only.
+        delete content.claimedClient;
         // Write-time originatorInstanceId stamp (federation-edge-hardening slice
         // 1) — see stampOriginatorInstanceId's doc above. No-op if already set
         // (never fires for a genuine local write — no client sets this field).
@@ -652,9 +683,12 @@ export class Memory extends databases.flair.Memory {
             if (auth.kind === "anonymous") {
                 return UNAUTH();
             }
-            if (auth.kind === "agent" && !auth.isAdmin && content?.agentId && content.agentId !== auth.agentId) {
-                return FORBIDDEN("forbidden: cannot write memory owned by another agent");
-            }
+            // No-forge attribution — mode/field drawn from RECORD_TYPES.Memory,
+            // same rule as post(). "validate-truthy" (see record-type-kit.ts's
+            // stampAttribution doc).
+            const attr = stampAttribution(auth, content, RECORD_TYPES.Memory.ownerField, RECORD_TYPES.Memory.attribution.put, "forbidden: cannot write memory owned by another agent");
+            if (attr.denied)
+                return attr.denied;
         }
         const now = new Date().toISOString();
         content.updatedAt = now;
@@ -771,6 +805,10 @@ export class Memory extends databases.flair.Memory {
         // always gets a freshly-stamped provenance reflecting the CURRENT
         // authenticated actor performing this write.
         content.provenance = buildProvenance(auth, content.createdAt, content);
+        // flair#718 authorship-provenance — see post()'s identical comment above:
+        // strip the write-body-only `claimedClient` passthrough now that it's
+        // folded into `provenance.claimed.client`. Never persisted as a row field.
+        delete content.claimedClient;
         // Write-time originatorInstanceId stamp (federation-edge-hardening slice
         // 1) — see stampOriginatorInstanceId's doc above post(). No-op if
         // already set: an update/patch of an existing local record carries its

package/dist/resources/OrgEvent.js

@@ -11,12 +11,16 @@
  * distinguishes internal/agent/anonymous explicitly.
  */
 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" } });
+import { makeAuthGate, resolveAuthGate, stampAttribution, FORBIDDEN, UNAUTH, } from "./record-type-kit.js";
+import { RECORD_TYPES } from "./record-types.js";
+// 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 orgEventAuthGate = makeAuthGate();
 export class OrgEvent extends databases.flair.OrgEvent {
-    allowRead() { return allowVerified(this.getContext?.()); }
+    allowRead() { return orgEventAuthGate.call(this); }
     _auth() {
         return resolveAgentAuth(this.getContext?.());
     }
@@ -24,19 +28,21 @@ export class OrgEvent extends databases.flair.OrgEvent {
         const auth = await this._auth();
         if (auth.kind === "anonymous")
             return UNAUTH();
-        // No-forge attribution: a non-admin agent's events are ALWAYS attributed to
-        // its authenticated identity (from the Ed25519 signature), never the body —
-        // an agent can only publish AS itself. We overwrite `authorId` rather than
-        // 403'ing a mismatch so a CLI client never has to echo its own id into the
-        // body (mirrors A2A message/send's "sender must match params.agentId" guard
-        // and Presence's "agentId from signature, NOT from body"). Admin agents may
-        // publish on behalf of another agent (body authorId honored, else their own).
-        if (auth.kind === "agent" && !auth.isAdmin) {
-            content.authorId = auth.agentId;
-        }
-        else if (auth.kind === "agent" && auth.isAdmin) {
-            content.authorId ||= auth.agentId;
-        }
+        // No-forge attribution — mode/field drawn from RECORD_TYPES.OrgEvent
+        // (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 events are ALWAYS attributed to its authenticated
+        // identity (from the Ed25519 signature), never the body — an agent can
+        // only publish AS itself. We overwrite `authorId` rather than 403'ing a
+        // mismatch so a CLI client never has to echo its own id into the body
+        // (mirrors A2A message/send's "sender must match params.agentId" guard
+        // and Presence's "agentId from signature, NOT from body"). Admin agents
+        // may publish on behalf of another agent (body authorId honored, else
+        // their own).
+        // "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.OrgEvent.ownerField, RECORD_TYPES.OrgEvent.attribution.post, "forbidden: unreachable for stamp-default");
         if (!content.id)
             content.id = `${content.authorId}-${new Date().toISOString()}`;
         content.createdAt = new Date().toISOString();
@@ -53,9 +59,13 @@ export class OrgEvent extends databases.flair.OrgEvent {
         const auth = await this._auth();
         if (auth.kind === "anonymous")
             return UNAUTH();
-        if (auth.kind === "agent" && !auth.isAdmin && content.authorId !== auth.agentId) {
-            return FORBIDDEN("forbidden: authorId must match authenticated agent");
-        }
+        // No-forge attribution — mode/field drawn from RECORD_TYPES.OrgEvent.
+        // "validate-strict" (see record-type-kit.ts's stampAttribution doc):
+        // rejects a mismatch INCLUDING when authorId is absent (a bare `!==`
+        // compare, no truthy guard).
+        const attr = stampAttribution(auth, content, RECORD_TYPES.OrgEvent.ownerField, RECORD_TYPES.OrgEvent.attribution.put, "forbidden: authorId must match authenticated agent");
+        if (attr.denied)
+            return attr.denied;
         // attention-plane vocabulary gate (flair#675) — same as post() above.
         const entitiesError = invalidEntitiesResponse(content.entities);
         if (entitiesError)
@@ -63,16 +73,17 @@ export class OrgEvent extends databases.flair.OrgEvent {
         return databases.flair.OrgEvent.put(content);
     }
     async delete(id, context) {
-        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/WorkspaceState.ts use.
+        const gate = await resolveAuthGate(this.getContext?.(), UNAUTH());
+        if (gate.kind === "denied")
+            return gate.response;
+        if (gate.kind === "unfiltered")
             return super.delete(id, context);
-        }
         const record = await this.get(id);
         if (!record)
             return super.delete(id, context);
-        if (record.authorId !== auth.agentId) {
+        if (record.authorId !== gate.agentId) {
             return FORBIDDEN("forbidden: cannot delete events authored by another agent");
         }
         return super.delete(id, context);

package/dist/resources/Presence.js

@@ -32,7 +32,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 import { resolveAgentAuth, verifyAgentRequest } 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";
 // ─── Constants ────────────────────────────────────────────────────────────────
 const CURRENT_TASK_MAX_LENGTH = 200;
 const VALID_ACTIVITIES = new Set(["coding", "reviewing", "planning", "debugging", "idle"]);
@@ -409,11 +409,11 @@ export class Presence extends databases.flair.Presence {
             agentId = middlewareAgent;
         }
         else {
-            const m = authHeader.match(/^TPS-Ed25519\s+([^:]+):(\d+):([^:]+):(.+)$/);
-            if (!m) {
+            const parsed = parseTpsEd25519Header(authHeader);
+            if (!parsed) {
                 return new Response(JSON.stringify({ error: "Ed25519 agent auth required for heartbeat" }), { status: 401, headers: { "Content-Type": "application/json" } });
             }
-            const [, headerAgentId, tsRaw, nonce, sigB64] = m;
+            const { agentId: headerAgentId, tsRaw, nonce, signatureB64: sigB64 } = parsed;
             const ts = Number(tsRaw);
             const now = Date.now();
             if (!Number.isFinite(ts) || Math.abs(now - ts) > WINDOW_MS) {

package/dist/resources/Relationship.js

@@ -1,11 +1,22 @@
 import { databases } from "@harperfast/harper";
-import { resolveAgentAuth, allowVerified } from "./agent-auth.js";
+import { resolveAgentAuth } from "./agent-auth.js";
 import { checkRateLimit, rateLimitResponse } from "./rate-limiter.js";
 import { localInstanceId } from "./instance-identity.js";
-import { buildProvenance } from "./provenance.js";
-const NOT_FOUND = () => new Response(JSON.stringify({ error: "not found" }), { status: 404, headers: { "Content-Type": "application/json" } });
-const UNAUTH = () => new Response(JSON.stringify({ error: "authentication required" }), { status: 401, headers: { "Content-Type": "application/json" } });
-const FORBIDDEN = (msg) => new Response(JSON.stringify({ error: msg }), { status: 403, headers: { "Content-Type": "application/json" } });
+import { buildProvenance, makeAuthGate, makeReadScope, makeByIdReadGate, resolveAuthGate, stampAttribution, FORBIDDEN, UNAUTH, } from "./record-type-kit.js";
+import { RECORD_TYPES } from "./record-types.js";
+// Parameterized from RECORD_TYPES.Relationship (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.Relationship — not for any other
+// runtime consumer.
+export const relationshipReadScope = makeReadScope(RECORD_TYPES.Relationship.readScope, RECORD_TYPES.Relationship.ownerField);
+const relationshipByIdReadGate = makeByIdReadGate(relationshipReadScope);
+// 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 relationshipAuthGate = makeAuthGate();
 /**
  * Relationship resource — entity-to-entity relationships with temporal validity.
  *
@@ -28,13 +39,14 @@ export class Relationship extends databases.flair.Relationship {
      * ownership scoping happens in get() below; the collection scope is still
      * in search().
      */
-    allowRead() { return allowVerified(this.getContext?.()); }
+    allowRead() { return relationshipAuthGate.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'
-     * relationship ids.
+     * relationship ids. Wired through record-type-kit.ts's makeByIdReadGate,
+     * scoped "owner-only" — same dispatch shape Memory.ts's get() uses.
      */
     async get(target) {
         // Collection / query reads arrive as a RequestTarget with
@@ -47,39 +59,23 @@ export class Relationship extends databases.flair.Relationship {
         if (!target || (typeof target === "object" && target.isCollection)) {
             return this.search(target);
         }
-        const auth = await resolveAgentAuth(this.getContext?.());
-        // 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 relationships.
-        const record = await super.get(target);
-        if (!record)
-            return NOT_FOUND();
-        if (record.agentId !== auth.agentId)
-            return NOT_FOUND();
-        return record;
+        return relationshipByIdReadGate.call(this, target, (t) => super.get(t));
     }
     async search(query) {
-        const auth = await resolveAgentAuth(this.getContext?.());
+        const ctx = this.getContext?.();
         // Anonymous HTTP must NOT read relationships (previously `!authAgent` was
-        // treated as unfiltered — the anonymous-read leak).
-        if (auth.kind === "anonymous") {
-            return new Response(JSON.stringify({ error: "authentication required" }), {
-                status: 401, headers: { "content-type": "application/json" },
-            });
-        }
-        // Trusted internal call or admin agent → unfiltered.
-        if (auth.kind === "internal" || (auth.kind === "agent" && auth.isAdmin)) {
+        // treated as unfiltered — the anonymous-read leak). Trusted internal call
+        // or admin agent → unfiltered. Dispatch shape shared via
+        // record-type-kit.ts's resolveAuthGate — same three-way branch Memory.ts/
+        // WorkspaceState.ts's search() use.
+        const gate = await resolveAuthGate(ctx, UNAUTH());
+        if (gate.kind === "denied")
+            return gate.response;
+        if (gate.kind === "unfiltered")
             return super.search(query);
-        }
         // Non-admin agent: scope to own relationships.
-        const agentCondition = { attribute: "agentId", comparator: "equals", value: auth.agentId };
+        const scope = await relationshipReadScope(gate.agentId);
+        const agentCondition = scope.condition;
         if (!query?.conditions) {
             return super.search({ conditions: [agentCondition], ...(query || {}) });
         }
@@ -130,16 +126,15 @@ export class Relationship extends databases.flair.Relationship {
         if (auth.kind === "anonymous") {
             return UNAUTH();
         }
-        if (auth.kind === "agent") {
-            if (!auth.isAdmin) {
-                if (content?.agentId && content.agentId !== auth.agentId) {
-                    return FORBIDDEN("cannot write a relationship owned by another agent");
-                }
-                content.agentId = auth.agentId;
-            }
-            // admin: content.agentId left as provided (unfiltered) — see doc above.
-        }
-        // internal: content.agentId left as provided (unfiltered) — see doc above.
+        // No-forge attribution — mode/field drawn from RECORD_TYPES.Relationship
+        // (record-types slice 2, flair#520) rather than a hand-typed literal.
+        // "stamp-strict" (see record-type-kit.ts's stampAttribution doc): reject
+        // a PRESENT, mismatched agentId, else unconditionally stamp with the
+        // verified identity. Admin/internal: content.agentId left as provided
+        // (unfiltered) — see doc above.
+        const attr = stampAttribution(auth, content, RECORD_TYPES.Relationship.ownerField, RECORD_TYPES.Relationship.attribution.put, "cannot write a relationship owned by another agent");
+        if (attr.denied)
+            return attr.denied;
         if (!content.agentId || typeof content.agentId !== "string") {
             return new Response(JSON.stringify({ error: "agentId is required" }), {
                 status: 400, headers: { "content-type": "application/json" },
@@ -190,6 +185,11 @@ export class Relationship extends databases.flair.Relationship {
         // pre-existing row with no provenance field reads back `undefined`,
         // unchanged behavior (migration-equivalence gate).
         content.provenance = buildProvenance(auth, content.createdAt, content);
+        // flair#718 authorship-provenance — same contract as resources/Memory.ts's
+        // post()/put(): `claimedClient` is a write-body-only passthrough, already
+        // folded into `provenance.claimed.client` above. Strip it so it is NEVER
+        // persisted as a row field.
+        delete content.claimedClient;
         // Write-time originatorInstanceId stamp (federation-edge-hardening slice
         // 1) — see resources/Memory.ts's stampOriginatorInstanceId doc for the
         // full contract. No-op if already set (never fires for a genuine local
@@ -214,17 +214,16 @@ export class Relationship extends databases.flair.Relationship {
      */
     async delete(_) {
         const ctx = this.getContext?.();
-        const auth = await resolveAgentAuth(ctx);
-        if (auth.kind === "anonymous") {
-            return UNAUTH();
-        }
-        // Trusted internal call or admin agent — unfiltered, unchanged behavior.
-        if (auth.kind === "internal" || (auth.kind === "agent" && auth.isAdmin)) {
+        // Dispatch shape shared via record-type-kit.ts's resolveAuthGate — same
+        // three-way branch put()/get()/search() above use.
+        const gate = await resolveAuthGate(ctx, UNAUTH());
+        if (gate.kind === "denied")
+            return gate.response;
+        if (gate.kind === "unfiltered")
             return super.delete(_);
-        }
         // Non-admin agent: verify ownership before delete.
         const existing = await super.get();
-        if (existing?.agentId && existing.agentId !== auth.agentId) {
+        if (existing?.agentId && existing.agentId !== gate.agentId) {
             return FORBIDDEN("cannot delete another agent's relationship");
         }
         return super.delete(_);