@tpsdev-ai/flair 0.47.1 → 0.49.0

package/dist/lib/mcp-enable.js

@@ -555,12 +555,57 @@ function opsBaseUrl(opsPortOrUrl) {
 function basicAuthHeader(adminUser, adminPass) {
     return `Basic ${Buffer.from(`${adminUser}:${adminPass}`).toString("base64")}`;
 }
+/** The resolver's own predicate, verbatim (resources/mcp-handler.ts
+ *  `resolveAgentFromSub`): a credential is resolvable unless it is explicitly
+ *  revoked. The linking layer MUST use the same test — a credential the linker
+ *  considers inactive but the resolver would still serve is exactly the
+ *  invisible-duplicate hole #1317 is about. */
+function isResolvableCredential(cred) {
+    return cred?.status !== "revoked";
+}
 /**
  * Map the operator's IdP subject to their principal via `Credential(kind:
  * "idp")` — the SAME credential surface resources/mcp-handler.ts's
- * `resolveAgentFromSub` reads at request time. Idempotent: an existing
- * mapping for (provider, subject) is reused (lastUsedAt bumped) rather than
- * duplicated; the principal Agent is created only if missing.
+ * `resolveAgentFromSub` reads at request time.
+ *
+ * ## The uniqueness constraint (flair#1317, K&S ruling 2026-08-21)
+ *
+ * **At most one ACTIVE `Credential(kind:"idp", idpSubject:<sub>)` exists at a
+ * time, regardless of `idpProvider`.** This function is where that invariant is
+ * enforced, because it is the only supported writer of the mapping.
+ *
+ * It used to dedup on `(kind, idpProvider, idpSubject)` while the resolver read
+ * `(kind, idpSubject)`. A re-link under a different provider name therefore
+ * matched nothing, INSERTED a second active credential, and left
+ * `resolveAgentFromSub` picking whichever row its search iterator served first
+ * — identity resolution by iteration order, on a security-relevant mapping.
+ *
+ * The resolver's key is the correct one and does not change: an IdP subject is
+ * an identity, and "who is this subject?" has exactly one answer. `idpProvider`
+ * stays on the row as audit/diagnostic metadata, but it does not participate in
+ * uniqueness. So:
+ *
+ *   - same provider, existing active credential → RE-POINT it (`credentialReused`);
+ *   - any OTHER active credential for the subject → SUPERSEDE it: terminal
+ *     `status: "revoked"`, never a soft flag a later path could flip back
+ *     (revoked rows are never reused here — a re-link after a revoke mints a
+ *     fresh credential);
+ *   - the re-point/insert and every revocation go out as ONE ops-API `upsert`
+ *     batch, so there is no observable window with two active credentials or
+ *     zero. If the batch fails, nothing is claimed and the call throws;
+ *   - after the write the invariant is RE-READ and asserted. A store that
+ *     somehow holds ≠1 active credential for the subject is a hard error, not a
+ *     silent nondeterministic mapping.
+ *
+ * The principal Agent is created only if missing.
+ *
+ * RESIDUAL RISK, by design (Sherlock, #1317): whoever can call this for a
+ * subject can revoke that subject's prior credential. If two genuinely
+ * different people ever shared a subject string across providers, one's link
+ * kills the other's mapping. IdP subjects are opaque per-IdP identifiers so the
+ * collision is remote, and the alternative — duplicate active credentials with
+ * order-dependent resolution — is strictly worse. `credentialSuperseded` exists
+ * so the operator is told, not so the event is hidden.
  */
 export async function provisionIdpIdentityMapping(params, deps = {}) {
     const fetchImpl = deps.fetchImpl ?? fetch;
@@ -628,26 +673,43 @@ export async function provisionIdpIdentityMapping(params, deps = {}) {
         }
         principalCreated = true;
     }
-    // Reuse an existing Credential(kind:idp, provider, subject) mapping if present.
-    const searchCredRes = await fetchImpl(opsUrl, {
-        method: "POST",
-        headers: { "Content-Type": "application/json", Authorization: authHeader },
-        body: JSON.stringify({
-            operation: "search_by_conditions",
-            database: "flair",
-            table: "Credential",
-            operator: "and",
-            conditions: [
-                { search_attribute: "kind", search_type: "equals", search_value: "idp" },
-                { search_attribute: "idpProvider", search_type: "equals", search_value: params.idpProvider },
-                { search_attribute: "idpSubject", search_type: "equals", search_value: params.idpSubject },
-            ],
-            get_attributes: ["id", "principalId"],
-        }),
-    });
-    const existingCreds = searchCredRes.ok ? await searchCredRes.json().catch(() => []) : [];
-    const existing = Array.isArray(existingCreds) ? existingCreds[0] : undefined;
-    const credentialId = existing?.id ?? `cred_idp_${params.idpProvider}_${randomBytes(6).toString("hex")}`;
+    // ── flair#1317: look SUBJECT-WIDE, not (provider, subject) ─────────────────
+    // The resolver's key is (kind, idpSubject); anything narrower here leaves
+    // credentials that dedup cannot see but resolution can.
+    const findCredentialsForSubject = async () => {
+        const res = await fetchImpl(opsUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Authorization: authHeader },
+            body: JSON.stringify({
+                operation: "search_by_conditions",
+                database: "flair",
+                table: "Credential",
+                operator: "and",
+                conditions: [
+                    { search_attribute: "kind", search_type: "equals", search_value: "idp" },
+                    { search_attribute: "idpSubject", search_type: "equals", search_value: params.idpSubject },
+                ],
+                get_attributes: ["id", "principalId", "idpProvider", "idpSubject", "status", "label", "createdAt"],
+            }),
+        });
+        const body = res.ok ? await res.json().catch(() => []) : [];
+        return Array.isArray(body) ? body : [];
+    };
+    const subjectCreds = await findCredentialsForSubject();
+    const activeCreds = subjectCreds.filter(isResolvableCredential);
+    // Survivor: an ACTIVE same-provider credential is re-pointed (the idempotent
+    // re-run and the documented same-provider link). A revoked one is never
+    // resurrected — a re-link after a revoke mints a fresh credential.
+    const reused = activeCreds.find((c) => c?.idpProvider === params.idpProvider && c?.id);
+    const credentialId = reused?.id ?? `cred_idp_${params.idpProvider}_${randomBytes(6).toString("hex")}`;
+    // Everything else active for this subject is superseded. Under the old
+    // (provider, subject) key these rows were simply invisible; they are what made
+    // resolution order-dependent.
+    const superseded = activeCreds.filter((c) => c?.id && c.id !== credentialId);
+    // ONE batched write: the survivor first, then the revocations. A single
+    // ops-API operation is the strongest atomicity this surface can express, and
+    // ordering the survivor first means even a partially-applied batch can never
+    // leave the subject with ZERO resolvable credentials (the fail-open denial).
     const upsertRes = await fetchImpl(opsUrl, {
         method: "POST",
         headers: { "Content-Type": "application/json", Authorization: authHeader },
@@ -664,9 +726,25 @@ export async function provisionIdpIdentityMapping(params, deps = {}) {
                     status: "active",
                     idpProvider: params.idpProvider,
                     idpSubject: params.idpSubject,
-                    createdAt: existing ? undefined : now,
+                    createdAt: reused ? undefined : now,
                     lastUsedAt: now,
                 },
+                // Retained, not deleted: the revocation stays legible in storage and in
+                // Harper's table audit log (which records the full record image of
+                // every write). Identifying fields are echoed back so the row survives
+                // as a well-formed, revoked credential whichever merge semantics the
+                // ops API applies.
+                ...superseded.map((c) => ({
+                    id: c.id,
+                    principalId: c.principalId,
+                    kind: "idp",
+                    label: c.label,
+                    status: "revoked",
+                    idpProvider: c.idpProvider,
+                    idpSubject: params.idpSubject,
+                    createdAt: c.createdAt,
+                    updatedAt: now,
+                })),
             ],
         }),
     });
@@ -674,7 +752,26 @@ export async function provisionIdpIdentityMapping(params, deps = {}) {
         const text = await upsertRes.text().catch(() => "");
         throw new Error(`Identity mapping: failed to write Credential(kind:idp) mapping (HTTP ${upsertRes.status}): ${text}`);
     }
-    return { principalCreated, credentialId, credentialReused: Boolean(existing) };
+    // ── The invariant, RE-READ ────────────────────────────────────────────────
+    // Asserting what we intended to write proves nothing. This asks the store.
+    // ≠1 active credential means the resolver's answer for this subject is
+    // order-dependent, so this fails LOUDLY rather than returning a mapping the
+    // operator would reasonably believe is deterministic.
+    const afterCreds = (await findCredentialsForSubject()).filter(isResolvableCredential);
+    if (afterCreds.length !== 1 || afterCreds[0]?.id !== credentialId) {
+        const seen = afterCreds.map((c) => `${c?.id} → ${c?.principalId} (provider '${c?.idpProvider}')`).join("; ") || "none";
+        throw new Error(`Identity mapping: the uniqueness invariant does not hold after the write — subject '${params.idpSubject}' ` +
+            `has ${afterCreds.length} active Credential(kind:idp) row(s) [${seen}], expected exactly 1 (${credentialId}). ` +
+            `Runtime resolution for this subject would be iteration-order-dependent (flair#1317). ` +
+            `Inspect the Credential table for kind:"idp" idpSubject:"${params.idpSubject}" and revoke the rows that should not resolve.`);
+    }
+    return {
+        principalCreated,
+        credentialId,
+        credentialReused: Boolean(reused),
+        credentialSuperseded: superseded.length > 0,
+        supersededCredentialIds: superseded.map((c) => String(c.id)),
+    };
 }
 // ─── Restart only ────────────────────────────────────────────────────────────
 /** `restart` only — used by `disableMcp` (flag off + restart, no config
@@ -1069,10 +1166,21 @@ export async function enableMcp(params, deps = {}) {
         // and the one silent failure mode this surface has is discovering that
         // via an empty bootstrap. So the step that creates the mapping states it
         // plainly, names the link remedy, and points at the runtime diagnostic.
+        // flair#1317 — a cross-provider re-link REVOKES the subject's prior
+        // credential (one active credential per subject is the invariant). That is
+        // a credential dying, so it is stated as such, by id: an operator must
+        // never discover it later from something that stopped working.
+        const supersedeNote = mapping.credentialSuperseded
+            ? ` SUPERSEDED: ${mapping.supersededCredentialIds.length} prior Credential(kind:idp) row(s) for this subject ` +
+                `were REVOKED, not de-duplicated — ${mapping.supersededCredentialIds.join(", ")}. ` +
+                `They no longer resolve, and anything relying on them stops working. ` +
+                `Exactly one active credential per (kind, idpSubject) is the invariant that keeps resolution deterministic.`
+            : "";
         push(true, `connector identity: sub '${params.idpSubject}' (provider '${idpProvider}') resolves to Agent '${principal}' — ` +
             `every /mcp call reads and writes AS '${principal}'. ` +
             `principal ${mapping.principalCreated ? "created" : "already existed"}; ` +
-            `Credential(kind:idp) ${mapping.credentialReused ? "re-pointed" : "created"} (${mapping.credentialId}). ` +
+            `Credential(kind:idp) ${mapping.credentialReused ? "re-pointed" : "created"} (${mapping.credentialId}).` +
+            `${supersedeNote} ` +
             `If your CLI signs as a DIFFERENT agent id, the connector sees that agent's DISTINCT memory scope (by design) — ` +
             `re-run with --principal <your-agent-id> to link them. ` +
             `Diagnostic: the bootstrap tool's agentId/scope fields always say who the server resolved you to.`);

package/dist/resources/AgentSeed.js

@@ -19,6 +19,7 @@
 import { Resource, databases } from "harper";
 import { isAdmin, allowAdmin, invalidateAdminCache } from "./agent-auth.js";
 import { reconcileAdminFields } from "./agent-admin.js";
+import { noteMemoryUpsert } from "./bm25-index-service.js";
 const DEFAULT_SOUL_KEYS = (agentId, displayName, role, now) => ({
     name: displayName,
     role,
@@ -124,6 +125,7 @@ export class AgentSeed extends Resource {
                     archived: false,
                 };
                 await databases.flair.Memory.put(record);
+                noteMemoryUpsert(record);
                 memories.push(record);
             }
         } // end !hasOnboardingMemory

package/dist/resources/Memory.js

@@ -13,6 +13,7 @@ import { buildProvenance, makeAuthGate, makeReadScope, makeByIdReadGate, makeSco
 import { RECORD_TYPES } from "./record-types.js";
 import { attachTrust } from "./trust-block.js";
 import { recordCitations } from "./usage-recording.js";
+import { noteMemoryUpsert, noteMemoryDelete } from "./bm25-index-service.js";
 /**
  * flair#744 slice 1 — read the opt-in `includeTrust` flag for a by-id get.
  * Two entry shapes: an in-process caller (resources/mcp-tools.ts's memory_get)
@@ -306,7 +307,11 @@ async function closeSupersededRecord(ctx, oldId, patch) {
     if (!existing) {
         throw new Error(`supersede-close: record ${oldId} not found`);
     }
-    await withDetachedTxn(ctx, () => databases.flair.Memory.put({ ...existing, ...patch }));
+    const closed = { ...existing, ...patch };
+    await withDetachedTxn(ctx, () => databases.flair.Memory.put(closed));
+    // flair#1357 — a supersede-close sets `validTo`, which the retrieval filters
+    // read, so the lexical index has to see it as eagerly as a content write.
+    noteMemoryUpsert(closed);
 }
 /** Does an agent hold a "write" grant from `ownerId`? Same MemoryGrant lookup
  *  pattern as Memory.search()/SemanticSearch.ts (read/search scopes) — reused
@@ -614,8 +619,22 @@ export class Memory extends databases.flair.Memory {
             }
         }
         content.durability ||= "standard";
-        content.createdAt = new Date().toISOString();
-        content.updatedAt = content.createdAt;
+        // ── flair#1336: honor a caller-supplied createdAt (parity with put()) ──
+        // put() — the other HTTP-reachable create path — has always preserved the
+        // caller's createdAt (`content.createdAt ?? now`), and adk-flair's
+        // add_memory forwards MemoryEntry.timestamp through it for historical
+        // imports. When #1336 moved client creates onto POST, this line's
+        // unconditional re-stamp silently discarded those timestamps (caught by
+        // the #1334 list-pagination live test: rows written with backdated
+        // timestamps came back stamped "now"). Honoring the caller grants no new
+        // capability — PUT already accepted arbitrary createdAt from the same
+        // principals. validFrom below keys off createdAt and follows it, exactly
+        // as on the put() path; updatedAt stays the true write moment; the
+        // ephemeral expiresAt stamp keys off Date.now(), so a backdated create
+        // cannot stretch the #1257 exposure window.
+        const nowIso = new Date().toISOString();
+        content.createdAt = content.createdAt ?? nowIso;
+        content.updatedAt = nowIso;
         content.archived = content.archived ?? false;
         // ─── Default visibility (durability-keyed) — Layer 1, part A ────────────
         // post() only ever creates a NEW record — patchRecord/supersede-close/
@@ -658,9 +677,13 @@ export class Memory extends databases.flair.Memory {
         if (content.visibility === undefined || content.visibility === null) {
             content.visibility = defaultVisibilityForDurability(content.durability);
         }
-        // Validate derivedFrom source IDs exist (best-effort, non-blocking)
+        // Validate derivedFrom source IDs exist (best-effort, non-blocking).
+        // lastReflected keys off updatedAt (the write moment), NOT createdAt —
+        // since #1336 a create may carry a backdated caller createdAt, and the
+        // reflection bookkeeping must record when the derivation actually ran.
+        // (Pre-#1336 the two were always identical here.)
         if (Array.isArray(content.derivedFrom) && content.derivedFrom.length > 0) {
-            const now = content.createdAt;
+            const now = content.updatedAt;
             for (const sourceId of content.derivedFrom) {
                 try {
                     const src = await databases.flair.Memory.get(sourceId);
@@ -748,6 +771,11 @@ export class Memory extends databases.flair.Memory {
         await stampOriginatorInstanceId(content);
         // ── Write the new record FIRST ──────────────────────────────────────────
         const result = await super.post(content);
+        // flair#1357 — read-your-write for the lexical leg. The table change feed
+        // (resources/bm25-index-service.ts) is the CORRECTNESS mechanism; this
+        // synchronous hook is what makes a store immediately searchable rather
+        // than searchable-after-the-feed-turns.
+        noteMemoryUpsert(content);
         // ── THEN close the superseded record ────────────────────────────────────
         // Write-new-BEFORE-close-old: the previous order (close-old via a fire-
         // and-forget `.catch(()=>{})` BEFORE the new write) could tombstone the
@@ -789,7 +817,9 @@ export class Memory extends databases.flair.Memory {
                 });
             }
             delete content._reindex;
-            return super.put(content);
+            const reindexed = await super.put(content);
+            noteMemoryUpsert(content);
+            return reindexed;
         }
         // Create/update ownership (same rule as post): a non-admin agent may only
         // write memories it owns, via resolveAgentAuth (gate annotation), not
@@ -1025,6 +1055,8 @@ export class Memory extends databases.flair.Memory {
         await stampOriginatorInstanceId(content);
         // ── Write the new/updated record FIRST ──────────────────────────────────
         const result = await super.put(content);
+        // flair#1357 — read-your-write for the lexical leg (see post()).
+        noteMemoryUpsert(content);
         // ── THEN close the superseded record (see post()) ───────────────────────
         await closeSupersededIfNeeded(ctx, content, "put");
         // flair#744 slice A: citation-on-write — POST-COMMIT, fully
@@ -1049,8 +1081,11 @@ export class Memory extends databases.flair.Memory {
         // before the read-gate fix — the read-scoping override must not leak
         // into delete()'s internal record lookup.
         const record = await super.get(id);
-        if (!record)
-            return super.delete(id);
+        if (!record) {
+            const gone = await super.delete(id);
+            noteMemoryDelete(id);
+            return gone;
+        }
         if (record.durability === "permanent") {
             // Middleware already guards this for non-admins, but belt-and-suspenders
             const ctx = this.getContext?.();
@@ -1063,6 +1098,8 @@ export class Memory extends databases.flair.Memory {
                 });
             }
         }
-        return super.delete(id);
+        const deleted = await super.delete(id);
+        noteMemoryDelete(id);
+        return deleted;
     }
 }

package/dist/resources/MemoryFeed.js

@@ -4,6 +4,7 @@ import { computeContentHash, findExistingMemoryByContentHash } from "./memory-fe
 import { FORBIDDEN, UNAUTH, stampAttribution } from "./record-type-kit.js";
 import { assertValidVisibility, assertVisibilityAllowedForDurability, PRIVATE_VISIBILITY } from "./memory-visibility.js";
 import { assertValidDurability } from "./memory-durability.js";
+import { noteMemoryUpsert } from "./bm25-index-service.js";
 export class FeedMemories extends Resource {
     // Self-authorize via the Ed25519 agent verify (the auth reshape removes the
     // gate's admin elevation).
@@ -125,6 +126,8 @@ export class FeedMemories extends Resource {
             record.visibility = PRIVATE_VISIBILITY;
         }
         await databases.flair.Memory.put(record);
+        // flair#1357 — raw-table write: hook it explicitly (see bm25-index-service).
+        noteMemoryUpsert(record);
         return record;
     }
     async *connect(target, incomingMessages) {

package/dist/resources/MemoryMaintenance.js

@@ -18,6 +18,7 @@
  */
 import { Resource, databases } from "harper";
 import { isAdmin } from "./agent-auth.js";
+import { noteMemoryUpsert, noteMemoryDelete } from "./bm25-index-service.js";
 export class MemoryMaintenance extends Resource {
     /** POST requires auth — either an agent acting on its own memories, or admin. */
     allowCreate() {
@@ -65,6 +66,9 @@ export class MemoryMaintenance extends Resource {
                     if (!dryRun) {
                         try {
                             await databases.flair.Memory.delete(record.id);
+                            // flair#1357 — ephemeral expiry removes the row from what the
+                            // lexical leg may score.
+                            noteMemoryDelete(record.id);
                             stats.expired++;
                         }
                         catch {
@@ -88,11 +92,16 @@ export class MemoryMaintenance extends Resource {
                     if (ageDays > 30) {
                         if (!dryRun) {
                             try {
-                                await databases.flair.Memory.update(record.id, {
+                                const archivedRow = {
                                     ...record,
                                     archived: true,
                                     archivedAt: now.toISOString(),
-                                });
+                                };
+                                await databases.flair.Memory.update(record.id, archivedRow);
+                                // flair#1357 — an `archived` flip changes what the retrieval
+                                // conditions (`archived not_equal true`) admit, so the lexical
+                                // index has to see it, not just content writes.
+                                noteMemoryUpsert(archivedRow);
                                 stats.archived++;
                             }
                             catch {

package/dist/resources/SemanticSearch.js

@@ -61,7 +61,7 @@ export class SemanticSearch extends Resource {
         // recall-harness (test/bench/recall-harness/run.ts) and `recall-eval.mjs`
         // before reconsidering this default if the compositeScore formula or
         // corpus changes.
-        const { agentId: bodyAgentId, q, queryEmbedding, tag, subject, subjects, limit = 10, includeSuperseded = false, scoring = "raw", minScore = 0, since, asOf, includeTrust = false, abstain = false, explain = false } = data || {};
+        const { agentId: bodyAgentId, q, queryEmbedding, tag, subject, subjects, limit = 10, includeSuperseded = false, scoring = "raw", minScore = 0, since, asOf, includeTrust = false, includeMetadata = false, abstain = false, explain = false } = data || {};
         // Authenticated identity lives on the Harper Resource context (getContext().request).
         // `this.request` is NOT populated on Harper v5 Resources — prior reads here
         // silently returned undefined and the defense-in-depth scope check below
@@ -234,7 +234,20 @@ export class SemanticSearch extends Resource {
             // default projection omits. Widen the select ONLY when the caller opts
             // in — passing undefined otherwise keeps the default (no `provenance`)
             // so a non-trust recall response stays byte-identical.
-            select: includeTrust ? [...DEFAULT_SELECT, "provenance"] : undefined,
+            //
+            // flair#1332: same idiom for the client-writable `metadata` JSON blob
+            // (ADK custom_metadata store-and-return). DEFAULT_SELECT deliberately
+            // does NOT grow it (K&S projection ruling — the shared retrieval core
+            // serves every consumer, and none of the others should pay result-size
+            // for an opaque blob they never read); adk-flair opts in per-request
+            // with `includeMetadata: true`. `subject` needs no widening — it is
+            // already in DEFAULT_SELECT. Neither flag ⇒ select stays undefined ⇒
+            // response bytes unchanged.
+            select: (includeTrust || includeMetadata)
+                ? [...DEFAULT_SELECT,
+                    ...(includeTrust ? ["provenance"] : []),
+                    ...(includeMetadata ? ["metadata"] : [])]
+                : undefined,
             // flair#744 slice 2 + confidence-band refinement: attach the absolute
             // per-result cosine confidence when the caller opts into abstention OR
             // the trust block — abstention reads the best of it for its verdict, and