@tpsdev-ai/flair 0.23.0 → 0.25.0

package/dist/resources/trust-block.js

@@ -0,0 +1,187 @@
+/**
+ * trust-block.ts — the opt-in, inline trust-evidence block surfaced on recall
+ * results (flair#744 slice 1: "surface what we already record at the point of
+ * decision").
+ *
+ * ─── What this is ────────────────────────────────────────────────────────────
+ * A PURE, Harper-free assembler: `buildTrustBlock(record)` maps a single
+ * Memory record's ALREADY-STORED fields into a compact, self-contained trust
+ * block that `search` (SemanticSearch), `get` (Memory.get), and `bootstrap`
+ * (BootstrapMemories) attach to each result WHEN THE CALLER OPTS IN. No new
+ * computation, no cross-record lookups, no DB access — every field below is
+ * read straight off the record the recall path already resolved. That is the
+ * whole point of slice 1: the memory layer already records per-fact trust
+ * evidence at write time; this surfaces it at read time, where the consuming
+ * agent actually decides what to repeat.
+ *
+ * ─── The zero-authority invariant (flair#744 Sherlock condition 2 / #735) ────
+ * The trust block INFORMS THE READER ONLY. It is assembled AFTER read-scope
+ * resolution, purely for the response, and MUST NEVER enter an authority /
+ * scope / attribution / dedup decision anywhere — the same discipline as the
+ * `claimed.*` zero-authority guard (flair#735). Two things keep that true:
+ *   1. This module is pure and side-effect-free: buildTrustBlock NEVER mutates
+ *      its input record (it only reads), so assembling a block can never alter
+ *      a record a later decision reads.
+ *   2. No authority-decision module imports it. That is structurally enforced
+ *      by test/unit/trust-block-zero-authority-tripwire.test.ts (the #735-style
+ *      source scan): record-type-kit.ts, memory-read-scope.ts, Memory.ts's
+ *      dedup gates, RecordUsage.ts, mcp-handler.ts, and the retrieval/scoping
+ *      core (semantic-retrieval-core.ts) never reference the trust block — it
+ *      is assembled strictly DOWNSTREAM of scope resolution, in the response
+ *      tail of each recall wrapper.
+ *
+ * ─── `claimed.*` is surfaced as a BOOLEAN only ──────────────────────────────
+ * `hasClaimedProvenance` reports only WHETHER the record carries a self-
+ * reported `claimed` sub-object — never its content. Raw `claimed.model` /
+ * `claimed.client` values are self-reported and unverified (resources/
+ * provenance.ts); exposing them as authoritative trust evidence would defeat
+ * the verified-vs-claimed distinction the block exists to draw. The advisory
+ * "there is a self-report here" bit is enough for the reader to weight it.
+ *
+ * ─── Tier is DEFERRED to a later slice (flair#744 Sherlock condition 1) ─────
+ * The block deliberately does NOT carry a derived trust `tier`. A tier is not
+ * a field on the Memory record — it lives on the AUTHOR's Agent/OAuthClient
+ * principal record (`defaultTrustTier`), so surfacing it would require a
+ * per-author lookup on the hot recall path (exactly the read-path cost the
+ * flair#744 design round ruled out) AND the scope-gate Sherlock's condition 1
+ * mandates ("include tier only when reader.scope == author.scope"). That
+ * scope-gate needs an org/scope boundary primitive that does not yet exist in
+ * flair's single-tenant "open-within-org" read model. Both are more than
+ * trivial for slice 1, so per the spec's explicit allowance the tier field is
+ * deferred whole — the scope-gate ships WITH it, when it ships. Everything
+ * else in the block (provenance, author principal, usage, freshness,
+ * supersession) is on the Memory record itself and ships now.
+ *
+ * ─── `matchQuality` confidence band (flair#744 refinement) ──────────────────
+ * When the recall path attached an absolute semantic similarity to the result
+ * (`_semSimilarity`, cosine in [0,1] — attached only on the retrieval surface,
+ * when the caller opts into the block or into abstention), the block labels it
+ * with a confidence band — strong / moderate / breadcrumb — so a weak-but-
+ * present match is TAKEN FOR WHAT IT IS, not mistaken for a confident one (the
+ * hallucination risk is undifferentiated weak matches, not weak matches per se).
+ * Derived PURELY from that one number against the global band cut-points in
+ * resources/abstention.ts (single source of truth with the abstention floor —
+ * see classifyMatchQuality). When there is no similarity to judge (a by-id
+ * `get`, or a keyword-only degraded search — no `_semSimilarity`), the band is
+ * `null`: an honest "we couldn't classify this one", never a false label.
+ */
+import { ABSTENTION_THRESHOLD, MODERATE_BAND, STRONG_BAND } from "./abstention.js";
+const MS_PER_DAY = 86_400_000;
+/**
+ * Classify a result's absolute semantic similarity (`_semSimilarity`, cosine in
+ * [0,1]) into a confidence band. PURE: its ONLY input is that one number — no
+ * principal / agentId / tier / scope — so the band is GLOBAL and can never be
+ * varied per principal (Sherlock; structurally guarded by
+ * test/unit/abstention-no-per-principal-tripwire.test.ts, same spine as the
+ * abstention decision).
+ *
+ *   sim >= STRONG_BAND            → "strong"
+ *   MODERATE_BAND <= sim < STRONG → "moderate"
+ *   ABSTENTION_THRESHOLD <= sim   → "breadcrumb"  (bottom of breadcrumb IS the
+ *                                                   abstention floor — one
+ *                                                   shared constant, no dup)
+ *   sim < ABSTENTION_THRESHOLD    → "breadcrumb"  (a result present below the
+ *                                                   abstention floor — abstention
+ *                                                   off, or it slipped in — is
+ *                                                   still the WEAKEST present
+ *                                                   band; there is NO 4th band)
+ *   not a finite number (null/undefined/NaN) → null  (no signal to classify;
+ *                                                      never a false label)
+ *
+ * The breadcrumb floor references ABSTENTION_THRESHOLD directly (Kern BINDING
+ * condition 1): the band cut-points and the abstention floor are one source of
+ * truth (resources/abstention.ts) and cannot drift — if recall-bench moves the
+ * abstention floor, breadcrumb's floor moves with it.
+ */
+export function classifyMatchQuality(semSimilarity) {
+    if (typeof semSimilarity !== "number" || !Number.isFinite(semSimilarity))
+        return null;
+    if (semSimilarity >= STRONG_BAND)
+        return "strong";
+    if (semSimilarity >= MODERATE_BAND)
+        return "moderate";
+    if (semSimilarity >= ABSTENTION_THRESHOLD)
+        return "breadcrumb";
+    // Present below the abstention floor (abstention off, or a straggler): still
+    // the weakest present band — breadcrumb, never a 4th band.
+    return "breadcrumb";
+}
+function parseTime(value) {
+    if (typeof value !== "string" || value.length === 0)
+        return NaN;
+    return Date.parse(value);
+}
+/**
+ * Assemble the trust block for one Memory record. Pure: reads only, NEVER
+ * mutates `record`. `now` is injectable for deterministic tests (defaults to
+ * the current wall clock).
+ */
+export function buildTrustBlock(record, now = Date.now()) {
+    // ── Provenance (verified vs claimed) ──────────────────────────────────────
+    let verifiedAuthor = null;
+    let verifiedAt = null;
+    let hasClaimedProvenance = false;
+    if (typeof record.provenance === "string" && record.provenance.length > 0) {
+        try {
+            const p = JSON.parse(record.provenance);
+            if (p && typeof p === "object") {
+                if (p.verified && typeof p.verified === "object") {
+                    verifiedAuthor = typeof p.verified.agentId === "string" ? p.verified.agentId : null;
+                    verifiedAt = typeof p.verified.timestamp === "string" ? p.verified.timestamp : null;
+                }
+                // Boolean only — the self-reported content is deliberately NOT surfaced.
+                hasClaimedProvenance = p.claimed != null && typeof p.claimed === "object";
+            }
+        }
+        catch {
+            // Malformed provenance → treated as unattributed, never throws.
+        }
+    }
+    // ── Freshness / validity ──────────────────────────────────────────────────
+    const validFrom = typeof record.validFrom === "string" ? record.validFrom : null;
+    const validTo = typeof record.validTo === "string" ? record.validTo : null;
+    const createdAt = typeof record.createdAt === "string" ? record.createdAt : null;
+    const validToMs = parseTime(validTo);
+    const validFromMs = parseTime(validFrom);
+    let validityStatus = "valid";
+    if (Number.isFinite(validToMs) && validToMs <= now) {
+        validityStatus = "expired";
+    }
+    else if (Number.isFinite(validFromMs) && validFromMs > now) {
+        validityStatus = "future";
+    }
+    const createdMs = parseTime(createdAt);
+    const ageDays = Number.isFinite(createdMs)
+        ? Math.max(0, Math.floor((now - createdMs) / MS_PER_DAY))
+        : null;
+    return {
+        author: typeof record.agentId === "string" ? record.agentId : null,
+        provenanceStatus: verifiedAuthor ? "verified" : "unattributed",
+        verifiedAuthor,
+        verifiedAt,
+        hasClaimedProvenance,
+        usageCount: typeof record.usageCount === "number" ? record.usageCount : null,
+        validityStatus,
+        validFrom,
+        validTo,
+        createdAt,
+        ageDays,
+        supersedes: typeof record.supersedes === "string" ? record.supersedes : null,
+        // flair#744 refinement — confidence band from the result's absolute
+        // similarity (null when there is no signal to judge). Pure, global,
+        // score-only: classifyMatchQuality sees ONLY the number.
+        matchQuality: classifyMatchQuality(record._semSimilarity),
+    };
+}
+/**
+ * Opt-in attach: the single primitive `search`/`get` use to layer the trust
+ * block onto a result. `includeTrust === false` (the default) returns the
+ * EXACT SAME record reference untouched — the clean-migration guarantee that a
+ * consumer who doesn't request the block sees a byte-identical response. When
+ * true, returns a shallow copy with `trust` added (never mutates the input).
+ */
+export function attachTrust(record, includeTrust, now) {
+    if (!includeTrust)
+        return record;
+    return { ...record, trust: buildTrustBlock(record, now) };
+}

package/dist/resources/usage-recording.js

@@ -0,0 +1,160 @@
+/**
+ * usage-recording.ts — shared usage-ledger recording core (flair#744 slice A,
+ * "citation-on-write"; extracted from RecordUsage.ts's flair#683 signal so
+ * there is exactly ONE implementation of the ledger logic, not two that can
+ * drift).
+ *
+ * Two callers share this core, both crediting the SAME deduped,
+ * principal-bound `MemoryUsage` ledger + the targeted `Memory.usageCount`
+ * bump:
+ *   - `POST /RecordUsage` (resources/RecordUsage.ts) — an agent explicitly
+ *     reports "I used this memory" as a standalone call.
+ *   - Citation-on-write (resources/Memory.ts's post()/put(), via
+ *     `recordCitations()` below) — an agent cites `usedMemoryIds` inline on a
+ *     memory WRITE; each cited id is credited the same way, post-commit and
+ *     failure-isolated from the write itself.
+ *
+ * `recordUsageContribution()` is an EXACT extraction of what was
+ * RecordUsage.ts's private `_recordOne()` — see its doc below for the
+ * ledger-then-count ordering, the individually-wrapped `withDetachedTxn`
+ * discipline, and the accepted best-effort race on the final
+ * read-modify-write. This move changes WHERE the logic lives, not what it
+ * does — behavior is byte-identical for RecordUsage.ts's existing callers.
+ *
+ * `recordCitations()` is the NEW batch helper citation-on-write uses: the
+ * same agent-required / cap / dedup / per-id failure-isolation shape as
+ * RecordUsage.post()'s loop, parameterized so Memory.ts can drive it from a
+ * write body instead of a dedicated POST body. It NEVER reads the ledger for
+ * authority — it only writes contributions; `usedMemoryIds` must never enter
+ * an access/scope/attribution/dedup decision (flair#744 slice A invariant 3).
+ */
+import { databases } from "@harperfast/harper";
+import { withDetachedTxn } from "./table-helpers.js";
+/**
+ * Per-call cap on ids credited in one batch — shared by RecordUsage.post()'s
+ * validated `memoryIds` body (rejects a batch over the cap with a 400) and
+ * recordCitations()'s advisory `usedMemoryIds` (silently slices instead —
+ * see that function's doc for why the two differ here).
+ */
+export const MAX_USAGE_IDS_PER_CALL = 20;
+/**
+ * One (agentId, memoryId) contribution — the shared ledger-write core.
+ *
+ * Ledger-row-create FIRST, THEN the Memory.usageCount bump — so a crash
+ * between the two leaves the SAFE failure state (ledger row exists, count
+ * not yet bumped: a later retry just re-checks and no-ops) rather than the
+ * reverse (count bumped, no ledger row → a retry would double-count).
+ *
+ * Every discrete Harper call is wrapped INDIVIDUALLY in its own
+ * withDetachedTxn — never one wrap around a multi-step helper. A request
+ * that reads/writes MULTIPLE tables (or the same table twice) in sequence
+ * can otherwise inherit a closed transaction from a prior call's drained
+ * chain (table-helpers.ts's withDetachedTxn doc); resources/Memory.ts's
+ * closeSupersededRecord documents exactly why a single wrap around a
+ * multi-await async function does NOT protect a later call inside it —
+ * this mirrors that function's literal shape (get wrapped, then a
+ * SEPARATE put wrapped) rather than delegating to the generic
+ * 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
+ * landing between this call's read and write could lose one increment.
+ * 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
+ * inflation), and orthogonal to the anti-gaming properties the cap/floor
+ * and dedup ledger actually defend.
+ *
+ * Called by RecordUsage.post() (explicit usage feedback) and by
+ * recordCitations() below (citation-on-write) — identical ledger semantics
+ * regardless of which surface triggered the contribution.
+ */
+export async function recordUsageContribution(ctx, agentId, memoryId, attribution, now) {
+    const ledgerId = `${agentId}:${memoryId}`;
+    // Bypasses resources/MemoryUsage.ts's own auth wrapper by design — this
+    // IS the trusted internal caller that resource's module doc describes
+    // (same "raw table object" pattern resources/Memory.ts uses for
+    // MemoryGrant).
+    const existingContribution = await withDetachedTxn(ctx, () => databases.flair.MemoryUsage.get(ledgerId)).catch(() => null);
+    if (existingContribution)
+        return; // already counted by this agent — silent no-op
+    const memoryExists = await withDetachedTxn(ctx, () => databases.flair.Memory.get(memoryId)).catch(() => null);
+    if (!memoryExists)
+        return; // no such memory — silent no-op (no enumeration)
+    const ledgerRecord = { id: ledgerId, agentId, memoryId, createdAt: now };
+    if (attribution)
+        ledgerRecord.attribution = attribution;
+    // .put(), not .post(): Harper's raw TableResource has no default post()
+    // implementation for a static-style (non-`isCollection`-instantiated)
+    // call — confirmed live ("The MemoryUsage does not have a post method
+    // implemented", statusCode 405) — the SAME class of gotcha
+    // resources/Memory.ts documents for HTTP POST, but here it bites even
+    // this in-process call. Irrelevant anyway: ledgerId is already a
+    // deterministic composite key, so this is a create-with-explicit-id —
+    // exactly what PUT (upsert) is for, not an auto-generated-id insert.
+    await withDetachedTxn(ctx, () => databases.flair.MemoryUsage.put(ledgerRecord));
+    // Targeted usageCount-ONLY bump: read-full-record, merge just this one
+    // field, write — against the RAW Memory table, NEVER Memory.put() (the
+    // resource class): that would 403 this cross-agent write via its
+    // ownership check, and bypassing that check directly would risk letting
+    // this write path smuggle OTHER field changes through instead of just the
+    // count (RecordUsage.ts module doc's "WHY THIS IS ITS OWN ENDPOINT").
+    const fresh = await withDetachedTxn(ctx, () => databases.flair.Memory.get(memoryId)).catch(() => null);
+    if (!fresh)
+        return; // deleted between the checks above and now — no-op
+    await withDetachedTxn(ctx, () => databases.flair.Memory.put({ ...fresh, usageCount: (fresh.usageCount ?? 0) + 1 }));
+}
+/**
+ * Batch citation helper — credits every id in `usedMemoryIds` through
+ * `recordFn` (the real `recordUsageContribution` by default), one contribution
+ * per unique id, capped at `MAX_USAGE_IDS_PER_CALL`.
+ *
+ * Called by Memory.ts's post()/put() POST-COMMIT, wrapped in its own
+ * try/catch at the call site — this function itself never throws (every
+ * per-id failure is caught and logged below), but callers still isolate the
+ * call as a second line of defense so a write can never be affected by
+ * citation recording (flair#744 slice A invariant 1).
+ *
+ *   - `auth.kind !== "agent"` ⇒ return immediately, no-op. Internal/admin/
+ *     anonymous writes have no agent identity to attribute a contribution
+ *     TO — same rule RecordUsage.post() applies ("usage feedback requires a
+ *     verified agent identity").
+ *   - `usedMemoryIds` not a non-empty array of non-empty strings ⇒ no-op
+ *     (advisory field, never a validated request body — a malformed value
+ *     is silently ignored, never a 400).
+ *   - Deduped within the call (`[...new Set(...)]`), THEN capped at
+ *     MAX_USAGE_IDS_PER_CALL by slicing — a citation list is advisory, not a
+ *     validated request body, so an oversized list is trimmed rather than
+ *     rejected (unlike RecordUsage.post()'s validated `memoryIds`, which
+ *     400s over the same cap).
+ *   - Each id is credited independently: one id throwing never stops the
+ *     rest, and the failure is logged server-side, never surfaced to the
+ *     caller (the write already committed by the time this runs).
+ *
+ * `agentId` passed to `recordFn` is ALWAYS `auth.agentId` — the resolved
+ * auth context, never anything derived from `usedMemoryIds` or any other
+ * caller-supplied input (flair#744 slice A invariant 4: no forging on
+ * behalf of another identity).
+ */
+export async function recordCitations(ctx, auth, usedMemoryIds, now, recordFn = recordUsageContribution) {
+    if (auth.kind !== "agent")
+        return;
+    if (!Array.isArray(usedMemoryIds) ||
+        usedMemoryIds.length === 0 ||
+        !usedMemoryIds.every((id) => typeof id === "string" && id.length > 0)) {
+        return;
+    }
+    const ids = [...new Set(usedMemoryIds)].slice(0, MAX_USAGE_IDS_PER_CALL);
+    for (const id of ids) {
+        try {
+            await recordFn(ctx, auth.agentId, id, undefined, now);
+        }
+        catch (err) {
+            // Never let one bad id stop the batch — same no-op-on-error discipline
+            // as RecordUsage.post()'s loop, log server-side only.
+            console.error("recordCitations: failed to credit (no-op)", { memoryId: id, err });
+        }
+    }
+}

package/package.json

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