@tpsdev-ai/flair 0.51.2 → 0.53.0

package/dist/resources/relay-ops.js

@@ -0,0 +1,294 @@
+/**
+ * relay-ops.ts — Flair Relay S1 orchestration (send / inbox / consume / sweep /
+ * dead-letter). Pure of Harper: every external dependency (the Message table,
+ * the Agent table, org resolution) is INJECTED, so the full behavioural surface
+ * is unit-testable with plain mocks and real ed25519 keys — no Harper instance,
+ * and none of the bun-single-process superclass-capture hazard that mocking the
+ * `harper` module invites. resources/Message.ts wires the real accessors in.
+ *
+ * All authorization decisions are made here against an already-resolved auth
+ * verdict; the resource layer only resolves the verdict and forwards the call.
+ */
+import { capDecision, computeContentHash, isUnconsumed, LOCAL_ORG_SENTINEL, reconcileState, sweepDecision, verifyMessageSignature, } from "./relay-lib.js";
+// ─── HTTP responses (Response is a web global, not a Harper import) ──────────
+const json = (status, obj) => new Response(JSON.stringify(obj), { status, headers: { "Content-Type": "application/json" } });
+const UNAUTH = () => json(401, { error: "authentication required" });
+const FORBIDDEN = (error) => json(403, { error });
+const NOT_FOUND = () => json(404, { error: "not found" });
+const BAD_REQUEST = (error) => json(400, { error });
+/** A per-(from, threadId) sequence conflict — the seq is not strictly ahead of
+ *  the thread's last message (Sherlock P1 seq monotonicity). */
+const CONFLICT = (error) => json(409, { error, reason: "seq_conflict" });
+/** Over-cap: a synchronous 4xx that names the reason — backpressure that fails loud. */
+const INBOX_FULL = (scope) => json(429, { error: "inbox full", reason: "inbox_full", scope });
+// ─── Helpers ────────────────────────────────────────────────────────────────
+/**
+ * Materialize a table.search() result (async iterable | iterable | promise) to
+ * an array. `conditions` are passed to search() so a real Harper backend uses
+ * the @indexed columns (`to`/`from`/`threadId`/`state` in schemas/message.graphql)
+ * instead of a full-table scan — the Sherlock P0 fix: the cap-counter is the
+ * DoS-preventer, so it must not itself be O(table). The in-code filters at each
+ * call site remain the correctness guarantee (the unit-test table double ignores
+ * the query and returns every row); the conditions are the production index hint.
+ */
+async function queryRows(table, conditions = []) {
+    const query = conditions.length > 0
+        ? { operator: "and", conditions: conditions.map((c) => ({ attribute: c.attribute, comparator: "equals", value: c.value })) }
+        : undefined;
+    const res = table.search(query);
+    const iter = res && typeof res.then === "function" ? await res : res;
+    const out = [];
+    for await (const row of iter)
+        out.push(row);
+    return out;
+}
+// `from` is REQUIRED: it is inside the SIGNED body, so it must be present BEFORE
+// signature verification and can never be server-mutated first (Sherlock P1 —
+// a mutated `from` would be signed-without / verified-with). A non-admin agent's
+// `from` is enforced-equal to its authenticated id (no overwrite), not defaulted.
+const REQUIRED_SEND_FIELDS = ["id", "from", "to", "threadId", "kind", "body", "createdAt", "signature"];
+/** The stable "accepted" projection — identical whether or not `to` exists. */
+function acceptedView(row) {
+    return {
+        id: row.id,
+        orgScope: row.orgScope,
+        from: row.from,
+        to: row.to,
+        threadId: row.threadId,
+        seq: row.seq,
+        kind: row.kind,
+        createdAt: row.createdAt,
+        contentHash: row.contentHash,
+        state: row.state,
+        deliveredAt: row.deliveredAt,
+    };
+}
+// ─── send ───────────────────────────────────────────────────────────────────
+/**
+ * post(msg). Verifies the sender signature, resolves orgScope server-side,
+ * enforces the no-forge `from`, dedups retries, enforces the inbox cap + the
+ * per-sender sub-cap, and delivers. Returns the accepted envelope — the SAME
+ * shape regardless of whether `to` exists (no existence oracle): the only
+ * principal ever looked up is the sender (needed for its public key), which is
+ * the authenticated caller and therefore always present.
+ */
+export async function relaySend(deps, auth, content) {
+    if (auth.kind === "anonymous")
+        return UNAUTH();
+    for (const f of REQUIRED_SEND_FIELDS) {
+        if (content[f] === undefined || content[f] === null || content[f] === "") {
+            return BAD_REQUEST(`missing required field: ${f}`);
+        }
+    }
+    if (typeof content.seq !== "number" || !Number.isInteger(content.seq) || content.seq < 0) {
+        return BAD_REQUEST("seq must be a non-negative integer");
+    }
+    // Validate `deadline` as a parseable ISO-8601 timestamp at send time. Left
+    // unvalidated, a garbage string yields NaN in sweepDecision, `NaN > now` is
+    // false, and the row sweeps to failed/deadline IMMEDIATELY (Kern nit). Absent
+    // is fine (no deadline); present-but-unparseable is a 400.
+    if (content.deadline !== undefined && content.deadline !== null) {
+        if (typeof content.deadline !== "string" || Number.isNaN(new Date(content.deadline).getTime())) {
+            return BAD_REQUEST("deadline must be a valid ISO-8601 timestamp");
+        }
+    }
+    // No-forge `from`: a non-admin agent can only send AS itself. `from` is a
+    // REQUIRED, SIGNED field — we ENFORCE equality (never overwrite, which would
+    // invalidate the signature) and NEVER mutate it before verification (a
+    // server-set `from` would be signed-without / verified-with — Sherlock P1).
+    if (auth.kind === "agent" && !auth.isAdmin && content.from !== auth.agentId) {
+        return FORBIDDEN("forbidden: `from` must match the authenticated agent");
+    }
+    // orgScope is server-resolved from the auth/pairing context and NEVER trusted
+    // from the body. It is inside the signed body, so the caller must have signed
+    // the correct org; any other value is a forged/foreign scope and is rejected.
+    const resolvedOrg = (await deps.resolveOrg()) ?? LOCAL_ORG_SENTINEL;
+    if (content.orgScope !== resolvedOrg) {
+        return FORBIDDEN("forbidden: orgScope is server-resolved, not settable from the body");
+    }
+    // Verify the sender's signature against the sender's pinned public key.
+    // `from` is guaranteed present by REQUIRED_SEND_FIELDS above (String() only
+    // narrows the optional type — it can never be undefined here).
+    const sender = await Promise.resolve(deps.agents.get(String(content.from))).catch(() => null);
+    if (!sender?.publicKey)
+        return FORBIDDEN("forbidden: unknown sender principal");
+    const verdict = verifyMessageSignature(content, String(sender.publicKey));
+    if (!verdict.ok)
+        return BAD_REQUEST(`signature: ${verdict.reason}`);
+    // Store the server-recomputed canonical hash (verified equal above).
+    content.contentHash = computeContentHash(content);
+    // Retry-dedup: an identical resend — same primary id, or the same content
+    // hash from this sender to this recipient — returns the already-accepted
+    // envelope. No second row, and (critically) no second charge against the cap.
+    const existingById = await Promise.resolve(deps.messages.get(String(content.id))).catch(() => null);
+    if (existingById)
+        return acceptedView(existingById);
+    // The recipient's inbox — queried by the @indexed `to`, never the whole table
+    // (Sherlock P0). Serves both dedup (same content from this sender) and the cap.
+    const recipientRows = await queryRows(deps.messages, [{ attribute: "to", value: content.to }]);
+    const dup = recipientRows.find((r) => r.from === content.from && r.to === content.to && r.contentHash === content.contentHash);
+    if (dup)
+        return acceptedView(dup);
+    // Seq monotonicity per (from, threadId): a distinct new message must be
+    // STRICTLY ahead of the thread's last seq (Sherlock P1). Checked AFTER dedup so
+    // a legitimate retry (same content, caught above) is never rejected. Queried by
+    // the @indexed `threadId`, then filtered to this sender in-code.
+    const threadRows = await queryRows(deps.messages, [{ attribute: "threadId", value: content.threadId }]);
+    let prevMaxSeq = -1;
+    for (const r of threadRows) {
+        if (r.from !== content.from || r.threadId !== content.threadId)
+            continue;
+        if (typeof r.seq === "number" && r.seq > prevMaxSeq)
+            prevMaxSeq = r.seq;
+    }
+    if (content.seq <= prevMaxSeq) {
+        return CONFLICT(`seq ${content.seq} is not ahead of the last seq (${prevMaxSeq}) for this (from, threadId)`);
+    }
+    // Inbox cap + per-sender sub-cap — AFTER dedup, so a retry is never rejected.
+    const counts = { recipientUnconsumed: 0, senderUnconsumed: 0 };
+    for (const r of recipientRows) {
+        if (r.to !== content.to || !isUnconsumed(r.state))
+            continue;
+        counts.recipientUnconsumed++;
+        if (r.from === content.from)
+            counts.senderUnconsumed++;
+    }
+    const cap = capDecision(counts);
+    if (!cap.ok)
+        return INBOX_FULL(cap.scope);
+    // Strip client-supplied lifecycle fields from the stored row: they are NOT
+    // under the signature (SIGNED_BODY_FIELDS excludes them), so a caller could
+    // pre-set `state`/`consumedAt`/`failureReason` and have them persist. `state`
+    // and `deliveredAt` are overwritten below regardless; consumedAt/failureReason
+    // are dropped here (Kern nit — hygiene, no injection today but no drift later).
+    const { state: _s, consumedAt: _c, failureReason: _f, deliveredAt: _d, ...clean } = content;
+    const now = (deps.now ?? (() => new Date()))().toISOString();
+    const row = {
+        ...clean,
+        kind: content.kind ?? "message",
+        state: "delivered",
+        deliveredAt: now,
+    };
+    await deps.messages.put(row);
+    return acceptedView(row);
+}
+// ─── inbox ──────────────────────────────────────────────────────────────────
+/**
+ * inbox(to). Unconsumed messages addressed to a principal, sorted by `seq`
+ * (per §12 P1-5 — createdAt collides at ms). A non-admin agent may only read
+ * its OWN inbox; admin/internal may read any.
+ */
+export async function relayInbox(deps, auth, requestedTo) {
+    if (auth.kind === "anonymous")
+        return UNAUTH();
+    const to = resolveSelfScope(auth, requestedTo);
+    if (to instanceof Response)
+        return to;
+    // Queried by the @indexed `to` — bounded by this inbox, not the table (Sherlock P0).
+    const rows = await queryRows(deps.messages, [{ attribute: "to", value: to }]);
+    return rows
+        .filter((r) => r.to === to && isUnconsumed(r.state))
+        .sort((a, b) => (a.seq ?? 0) - (b.seq ?? 0));
+}
+// ─── consume / ack ────────────────────────────────────────────────────────
+/**
+ * consume(id). Marks a message consumed. Only the RECIPIENT may consume its own
+ * message; a missing id or another principal's message is an indistinguishable
+ * 404 (no enumeration). `consumed` is absorbing — consuming an already-consumed
+ * message is an idempotent no-op that returns the row, never a regression.
+ */
+export async function relayConsume(deps, auth, id) {
+    if (auth.kind === "anonymous")
+        return UNAUTH();
+    if (!id)
+        return BAD_REQUEST("missing message id");
+    const row = await Promise.resolve(deps.messages.get(id)).catch(() => null);
+    if (!row)
+        return NOT_FOUND();
+    const isRecipient = auth.kind === "agent" && !auth.isAdmin ? row.to === auth.agentId : true;
+    if (!isRecipient)
+        return NOT_FOUND();
+    if (row.state === "consumed")
+        return row; // absorbing — idempotent
+    const now = (deps.now ?? (() => new Date()))().toISOString();
+    const updated = { ...row, state: reconcileState(row.state, "consumed"), consumedAt: now };
+    await deps.messages.put(updated);
+    return updated;
+}
+// ─── dead-letter ────────────────────────────────────────────────────────────
+/**
+ * The visible dead-letter: `failed` messages queryable by the SENDER (from ===
+ * caller), each carrying its failureReason. A non-admin sees only its own
+ * failures; admin/internal may query any sender.
+ */
+export async function relayDeadLetters(deps, auth, requestedFrom) {
+    if (auth.kind === "anonymous")
+        return UNAUTH();
+    const from = resolveSelfScope(auth, requestedFrom);
+    if (from instanceof Response)
+        return from;
+    // Queried by the @indexed `from` + `state` — the sender's failed rows only,
+    // never a full-table scan (Sherlock P0).
+    const rows = await queryRows(deps.messages, [
+        { attribute: "from", value: from },
+        { attribute: "state", value: "failed" },
+    ]);
+    return rows
+        .filter((r) => r.from === from && r.state === "failed")
+        .sort((a, b) => (a.createdAt ?? "").localeCompare(b.createdAt ?? ""));
+}
+// ─── deadline sweep ─────────────────────────────────────────────────────────
+/**
+ * Deadline sweep. Unconsumed past-deadline messages transition to a VISIBLE
+ * `failed`/`deadline` state (the inverse of OrgEvent's silent expiry). Consumed
+ * rows are NEVER regressed (absorbing). Admin/internal only — it is a
+ * maintenance operation over the whole table.
+ */
+export async function relaySweepDeadlines(deps, auth) {
+    if (auth.kind === "anonymous")
+        return UNAUTH();
+    if (auth.kind === "agent" && !auth.isAdmin) {
+        return FORBIDDEN("forbidden: deadline sweep is an administrative operation");
+    }
+    const now = (deps.now ?? (() => new Date()))();
+    // Only UNCONSUMED rows can sweep to failed — query the two unconsumed states
+    // by the @indexed `state` and union by id, instead of scanning the whole table
+    // (Sherlock P0). The id-dedup also makes this correct if a backend (or the
+    // test double) returns overlapping rows across the two state queries.
+    const byId = new Map();
+    for (const st of ["submitted", "delivered"]) {
+        for (const r of await queryRows(deps.messages, [{ attribute: "state", value: st }])) {
+            if (r?.id != null)
+                byId.set(String(r.id), r);
+        }
+    }
+    const rows = [...byId.values()];
+    let failed = 0;
+    for (const row of rows) {
+        const outcome = sweepDecision(row, now);
+        if (!outcome.fail)
+            continue;
+        // reconcileState guards the absorbing rule a second time: even if `row`
+        // were consumed, "failed" could never win — belt and suspenders.
+        const next = reconcileState(row.state, "failed");
+        if (next !== "failed")
+            continue;
+        await deps.messages.put({ ...row, state: "failed", failureReason: outcome.failureReason });
+        failed++;
+    }
+    return { failed };
+}
+// ─── shared scoping ─────────────────────────────────────────────────────────
+/** A non-admin is pinned to its own id; admin/internal may target any id. */
+function resolveSelfScope(auth, requested) {
+    if (auth.kind === "agent" && !auth.isAdmin) {
+        if (requested && requested !== auth.agentId) {
+            return FORBIDDEN("forbidden: can only act on your own messages");
+        }
+        return auth.agentId;
+    }
+    // admin or internal
+    if (!requested)
+        return FORBIDDEN("forbidden: a target principal id is required");
+    return requested;
+}

package/dist/resources/skill-write.js

@@ -0,0 +1,120 @@
+/**
+ * skill-write.ts — the WRITE-side skill policy (flair#1542 components 1-3).
+ *
+ * A skill is a Memory tagged "skill" (reuse the substrate — no new table).
+ * This module centralizes the three write-side rules that make a skill-tagged
+ * Memory behave like a skill:
+ *
+ *   1. Embedding source: a skill-tagged row embeds from `trigger` (the
+ *      "when to use" text), NOT from `content` (the full procedure). The
+ *      recall signal is "when does this skill apply", so the vector must
+ *      represent the trigger. Non-skill rows are untouched — `skillEmbedText`
+ *      returns `content` for them, byte-identical to the pre-slice behavior.
+ *
+ *   2. SkillScan gate: every skill-tagged write is statically scanned
+ *      (resources/scan/skill-scanner.ts) BEFORE the embedding is computed.
+ *      Fail-closed on high/critical risk (a rejected write pays no embed);
+ *      allow-with-flag on medium (the findings are recorded on the row's
+ *      `_safetyFlags` so the write is auditable, but it is not blocked).
+ *
+ *   3. Forced durability: a skill MUST be durability=persistent. The 30-day
+ *      reaper would archive a default-written ("standard") skill, and an
+ *      ephemeral/session skill is a contradiction in terms — ephemeral/session
+ *      are rejected outright, and every other value is forced to "persistent".
+ *
+ * Deliberately ZERO Harper imports — pure functions + constants, so the
+ * coverage-gate test and unit tests can import this module without the
+ * runtime (same load-bearing reason as memory-durability.ts /
+ * memory-visibility.ts).
+ */
+import { scanSkillContent } from "./scan/skill-scanner.js";
+/** The tag that marks a Memory as a skill. */
+export const SKILL_TAG = "skill";
+/** Is this write a skill-tagged Memory? */
+export function isSkillWrite(content) {
+    return Array.isArray(content?.tags) && content.tags.includes(SKILL_TAG);
+}
+/**
+ * The text a row embeds from. Skill-tagged rows embed from `trigger` (the
+ * recall signal); every other row embeds from `content`. Returns `undefined`
+ * only when there is no usable text at all.
+ */
+export function skillEmbedText(content) {
+    if (isSkillWrite(content) && typeof content.trigger === "string" && content.trigger.length > 0) {
+        return content.trigger;
+    }
+    return content.content;
+}
+/**
+ * Force a skill-tagged write to durability=persistent. Rejects an explicit
+ * ephemeral/session durability (a skill that expires is a contradiction);
+ * every other value — including the "standard" default and "permanent" — is
+ * forced to "persistent" so the 30-day reaper never archives a skill.
+ *
+ * Returns a 400 Response to short-circuit the write, or null to proceed.
+ * `content.durability` is mutated to "persistent" on the proceed path.
+ */
+export function enforceSkillDurability(content) {
+    if (!isSkillWrite(content))
+        return null;
+    const d = content.durability;
+    if (d === "ephemeral" || d === "session") {
+        return new Response(JSON.stringify({
+            error: "skill_durability",
+            message: "skill memories must be durability=persistent; ephemeral/session rejected",
+        }), { status: 400, headers: { "content-type": "application/json" } });
+    }
+    content.durability = "persistent";
+    return null;
+}
+/**
+ * Reject a skill-tagged write on a path that does NOT run the SkillScan gate
+ * or forced durability (patch, seed, etc.). Skills are written ONLY via
+ * skill_store (→ Memory.post) or Memory.put — every other verb rejects a
+ * skill-tagged write rather than land it unscanned (the #1537 raw-writer
+ * lesson: gate EVERY verb, not just post/put).
+ *
+ * Returns a 400 Response to short-circuit the write, or null to proceed.
+ */
+export function rejectSkillWritePath(content) {
+    if (!isSkillWrite(content))
+        return null;
+    return new Response(JSON.stringify({
+        error: "skill_write_path",
+        message: "skill memories must be written via skill_store (or Memory post/put); this path does not gate skill writes",
+    }), { status: 400, headers: { "content-type": "application/json" } });
+}
+/**
+ * SkillScan gate — run BEFORE the embedding is computed. Scans the combined
+ * `trigger` + `content` text (a dangerous shell/network payload in EITHER is
+ * a rejection). Fail-closed on high/critical risk; allow-with-flag on medium
+ * (findings appended to `_safetyFlags`); a clean scan is a no-op.
+ *
+ * Returns a 400 Response to short-circuit the write, or null to proceed.
+ */
+export function skillScanGate(content) {
+    if (!isSkillWrite(content))
+        return null;
+    const parts = [content.trigger, content.content].filter((s) => typeof s === "string" && s.length > 0);
+    if (parts.length === 0)
+        return null;
+    const result = scanSkillContent(parts.join("\n\n"));
+    if (result.riskLevel === "high" || result.riskLevel === "critical") {
+        return new Response(JSON.stringify({
+            error: "skill_scan_rejected",
+            riskLevel: result.riskLevel,
+            violations: result.violations,
+            message: "skill content failed SkillScan (fail-closed on high/critical risk)",
+        }), { status: 400, headers: { "content-type": "application/json" } });
+    }
+    if (result.riskLevel === "medium") {
+        // allow-with-flag: record the findings so the write is auditable, but do
+        // not block it. `_safetyFlags` is the existing content-safety flag column;
+        // skill findings are namespaced `skill:<type>` so they never collide with
+        // the content-safety flags that may already be present.
+        const flags = result.violations.map((v) => `skill:${v.type}`);
+        const existing = Array.isArray(content._safetyFlags) ? content._safetyFlags : [];
+        content._safetyFlags = [...existing, ...flags];
+    }
+    return null;
+}

package/dist/resources/soul-adk-guard.js

@@ -0,0 +1,68 @@
+import { ADK_SCOPE_TAG_PREFIX } from "../src/rem/promote-policy.js";
+/** Soul is agentId-scoped and cannot carry a per-user `adk:` tag. Writing an
+ *  ADK-sourced claim there leaks that user's distilled text to every other
+ *  user of the shared agentId. CLI refusal is not enough — a scripted
+ *  PUT /Soul must hit the same door.
+ *
+ *  This vendor-string match is a dated rollout bridge only. Soul authorization
+ *  is the deny-by-default operator/internal allowlist in soul-write-policy.ts;
+ *  runtime denial does not depend on `adk:`. Remove this module after
+ *  ADK_SOUL_REFUSE_KILL_DATE once classified writers are deployed (#1540). */
+export const ADK_SOUL_REFUSAL = "adk_sourced_claim_cannot_be_written_to_soul";
+/** Calendar date (UTC) after which this `adk:` bridge must be removed. */
+export const ADK_SOUL_REFUSE_KILL_DATE = "2026-10-31";
+export function tagLooksAdk(tag) {
+    return typeof tag === "string" && tag.toLowerCase().startsWith(ADK_SCOPE_TAG_PREFIX);
+}
+/** Request body carries an ADK scope tag (promotion leftover or forged). */
+export function bodyCarriesAdkScope(content) {
+    if (tagLooksAdk(content?.scopeTag))
+        return true;
+    const tags = content?.tags;
+    return Array.isArray(tags) && tags.some(tagLooksAdk);
+}
+export function rowLooksAdkSourced(row) {
+    if (!row)
+        return false;
+    if (tagLooksAdk(row.scopeTag))
+        return true;
+    return Array.isArray(row.tags) && row.tags.some(tagLooksAdk);
+}
+function adkForbidden() {
+    return new Response(JSON.stringify({ error: ADK_SOUL_REFUSAL }), {
+        status: 403,
+        headers: { "Content-Type": "application/json" },
+    });
+}
+async function* searchByAgentId(tableName, agentId) {
+    const { databases } = await import("harper");
+    const table = databases.flair?.[tableName];
+    if (!table?.search)
+        return;
+    const query = { conditions: [{ attribute: "agentId", comparator: "equals", value: agentId }] };
+    yield* table.search(query);
+}
+/** Refuse a Soul write whose value is an ADK-sourced claim. Body tags are
+ *  sufficient; otherwise match stored MemoryCandidate.claim / Memory.content
+ *  that already carries an `adk:` scope tag. */
+export async function refuseAdkSourcedSoulWrite(content, lookup = {}) {
+    if (bodyCarriesAdkScope(content))
+        return adkForbidden();
+    const value = typeof content?.value === "string" ? content.value : "";
+    const agentId = typeof content?.agentId === "string" ? content.agentId : "";
+    if (!value || !agentId)
+        return null;
+    const candidates = lookup.searchCandidates
+        ?? ((id) => searchByAgentId("MemoryCandidate", id));
+    for await (const row of candidates(agentId)) {
+        if (row?.claim === value && rowLooksAdkSourced(row))
+            return adkForbidden();
+    }
+    const memories = lookup.searchMemories
+        ?? ((id) => searchByAgentId("Memory", id));
+    for await (const row of memories(agentId)) {
+        if (row?.content === value && rowLooksAdkSourced(row))
+            return adkForbidden();
+    }
+    return null;
+}

package/dist/resources/soul-write-policy.js

@@ -0,0 +1,63 @@
+import { resolveAgentAuth } from "./agent-auth.js";
+import { FORBIDDEN, UNAUTH } from "./record-type-kit.js";
+import { buildProvenance } from "./provenance.js";
+import { databases } from "harper";
+import { refuseAdkSourcedSoulWrite } from "./soul-adk-guard.js";
+// Role is not source: an admin agent key or delegated OAuth identity is still
+// a runtime credential. Only verified Basic admin auth enters the operator path.
+// Callers cannot choose this class via body fields or connector-supplied labels.
+export function soulWriteSource(context, auth) {
+    const request = context?.request ?? context;
+    // Internal path needs a deliberate __flairInternal marker; a contextless call is refused.
+    if (auth.kind === "internal" && context?.__flairInternal === true && !request?.headers)
+        return "internal";
+    const header = request?.headers?.get?.("authorization") ?? request?.headers?.asObject?.authorization ?? "";
+    if (auth.kind === "agent" && auth.isAdmin && /^Basic\s/i.test(header))
+        return "operator";
+    return null;
+}
+export async function authorizeSoulWrite(context) {
+    const auth = await resolveAgentAuth(context);
+    const source = soulWriteSource(context, auth);
+    const denied = auth.kind === "anonymous" ? UNAUTH()
+        : source ? null : FORBIDDEN("soul_write_requires_operator: use authenticated operator credentials");
+    return { auth, source, denied };
+}
+export function soulProvenance(auth, source, now) {
+    const provenance = JSON.parse(buildProvenance(auth, now, {}));
+    provenance.verified.sourceClass = source;
+    return JSON.stringify(provenance);
+}
+export async function refuseLearnedSoulWrite(content) {
+    // Generic content-provenance backstop. Stored artifacts need no vendor tag —
+    // an exact owner-scoped Memory / MemoryCandidate match is enough.
+    if (typeof content?.value !== "string" || !content.value)
+        return null;
+    if (typeof content.agentId !== "string" || !content.agentId)
+        return FORBIDDEN("soul_owner_required");
+    for (const [name, field] of [["MemoryCandidate", "claim"], ["Memory", "content"]]) {
+        const table = databases.flair[name];
+        // Missing tables or failed reads throw before any write, rather than
+        // treating unavailable provenance as proof of operator-authored content.
+        for await (const row of table.search({
+            conditions: [
+                { attribute: "agentId", comparator: "equals", value: content.agentId },
+                { attribute: field, comparator: "equals", value: content.value },
+            ],
+            select: ["agentId", field],
+            limit: 1,
+        })) {
+            if (row.agentId === content.agentId && row[field] === content.value)
+                return FORBIDDEN("soul_value_is_learned_content");
+        }
+    }
+    return null;
+}
+/** Content guards after source authorization: dated vendor-tag bridge, then the
+ *  generic learned-content backstop. New connectors need no Soul-side branch. */
+export async function refuseSoulWriteContent(content) {
+    const adk = await refuseAdkSourcedSoulWrite(content);
+    if (adk)
+        return adk;
+    return refuseLearnedSoulWrite(content);
+}

package/dist/resources/table-helpers.js

@@ -4,6 +4,8 @@
  * Harper's `put()` is FULL RECORD REPLACEMENT. If you pass a partial
  * object, all missing fields (including embeddings!) are permanently
  * deleted. This helper ensures you always read the full record first.
+ * It does not promise atomic counters — search hit-tracking uses
+ * `resources/hit-tracking.ts` (MemoryHitStat) instead of this helper.
  *
  * Usage:
  *   import { patchRecord } from "./table-helpers.js";

package/dist/resources/usage-recording.js

@@ -75,10 +75,10 @@ export const MAX_USAGE_IDS_PER_CALL = 20;
  * patchRecord() helper, which would combine both into one un-safe wrap.
  *
  * The final get-then-put for the increment is a best-effort (non-atomic)
- * read-modify-write, same class of race already accepted elsewhere in
- * this codebase for count fields (e.g. retrievalCount's bump in
- * SemanticSearch.ts) — a concurrent contribution from a DIFFERENT agent
+ * read-modify-write — a concurrent contribution from a DIFFERENT agent
  * landing between this call's read and write could lose one increment.
+ * Search hit-tracking is no longer this class of race (flair#1528;
+ * resources/hit-tracking.ts coalesces MemoryHitStat increments).
  * Re-fetching immediately before the write (rather than reusing the
  * earlier existence-check read) narrows, without eliminating, that
  * window. Not solved here: bounded, low-severity (an undercount, never an