@tpsdev-ai/flair 0.44.11 → 0.44.12

package/dist/resources/Memory.js

@@ -7,6 +7,7 @@ import { scanFields, isStrictMode } from "./content-safety.js";
 import { invalidEntitiesResponse } from "./entity-vocab.js";
 import { checkRateLimit, rateLimitResponse } from "./rate-limiter.js";
 import { assertValidVisibility } from "./memory-visibility.js";
+import { assertValidDurability } from "./memory-durability.js";
 import { DEDUP_COSINE_THRESHOLD_DEFAULT, DEDUP_LEXICAL_THRESHOLD_DEFAULT, DEDUP_MIN_CONTENT_LENGTH, computeMatchConfidence, cosineSimilarity, isConservativeMatch, } from "./dedup.js";
 import { buildProvenance, makeAuthGate, makeReadScope, makeByIdReadGate, makeScopedSearch, resolveAuthGate, stampAttribution, FORBIDDEN, UNAUTH, } from "./record-type-kit.js";
 import { RECORD_TYPES } from "./record-types.js";
@@ -599,6 +600,19 @@ export class Memory extends databases.flair.Memory {
         const usedMemoryIds = content?.usedMemoryIds;
         if (content && typeof content === "object")
             delete content.usedMemoryIds;
+        // ── flair#1238: refuse an unrecognised durability BEFORE defaulting ──
+        // defaultVisibilityForDurability treats any non-permanent/persistent string
+        // as the private branch, so an unknown durability via raw REST (or a future
+        // non-Python adapter) is silently accepted and lands on the narrower private
+        // branch by accident — fail-safe, but unvalidated by contract. Refusing at
+        // the schema boundary makes it safe by construction (mirrors the visibility
+        // guard below). Absent durability is accepted and defaulted to "standard".
+        {
+            const durabilityError = assertValidDurability(content.durability);
+            if (durabilityError) {
+                return new Response(JSON.stringify({ error: "invalid_durability", message: durabilityError }), { status: 400, headers: { "content-type": "application/json" } });
+            }
+        }
         content.durability ||= "standard";
         content.createdAt = new Date().toISOString();
         content.updatedAt = content.createdAt;
@@ -789,6 +803,17 @@ export class Memory extends databases.flair.Memory {
         const usedMemoryIds = content?.usedMemoryIds;
         if (content && typeof content === "object")
             delete content.usedMemoryIds;
+        // ── flair#1238: refuse an unrecognised durability (mirrors post()) ──
+        // put() is the other HTTP-reachable write path (fresh create via CLI, and
+        // the update/patch path). Same guard as post(): a present-but-unknown
+        // durability is refused with 400; absent is accepted (no default stamped
+        // here — put() leaves durability untouched for updates).
+        {
+            const durabilityError = assertValidDurability(content.durability);
+            if (durabilityError) {
+                return new Response(JSON.stringify({ error: "invalid_durability", message: durabilityError }), { status: 400, headers: { "content-type": "application/json" } });
+            }
+        }
         const now = new Date().toISOString();
         content.updatedAt = now;
         // Set defaults that post() sets — put() is also used for new records via CLI

package/dist/resources/MemoryBootstrap.js

@@ -142,6 +142,35 @@ const MAX_COLLISION_ENTRIES = 10;
 // null` (no relevance score to band), which is CORRECT (Kern's #1220 ruling),
 // never a scoring failure — see the `matchQualityNote` in the response tail.
 const LIFECYCLE_SECTIONS = new Set(["permanent", "recent", "predicted"]);
+// flair#1199 trust-admission — build the EXACT trust entry that ships for one
+// included memory (id + section + block + the conditional matchQualityNote), so
+// the admission loop can charge its REAL serialized cost at the same moment it
+// charges the content cost. Single source of truth: the response tail reuses
+// this same builder, so the charged size and the shipped size can never drift
+// (the #1226 "charge what ships" principle, extended to the per-item trust
+// block). The block is assembled purely for SIZING + the response — its content
+// never enters any authority/scope/attribution/dedup decision (the #735/#744
+// zero-authority invariant).
+//
+// flair#1225 — Kern ruled (on #1220) that a null `matchQuality` on an own-recent
+// (lifecycle) entry is CORRECT: lifecycle sections (permanent/recent/predicted)
+// are a window LOAD, not a retrieval surface, so there is no similarity to band
+// — the null means "not scored here", never a scoring failure on the caller's
+// own records (the #1201 misread: own-recent null beside a teammate band).
+// Behavior is unchanged (per Kern); the matchQualityNote only makes the null
+// self-describing in the payload — Fix 3's "any absent field says why" — so a
+// connector reads it right without knowing the #1201 contract.
+function buildTrustEntry(m, section) {
+    const block = buildTrustBlock(m);
+    const matchQualityNote = block.matchQuality === null
+        ? (LIFECYCLE_SECTIONS.has(section)
+            ? `matchQuality is null because '${section}' is a lifecycle-window section, not a retrieval `
+                + `surface — there is no relevance score to band. This is correct (per flair#1225), not a scoring failure.`
+            : "matchQuality is null because no semantic similarity was attached to this result "
+                + "(e.g. a by-id read or a keyword-only degraded match).")
+        : undefined;
+    return { id: m.id, section, ...block, ...(matchQualityNote ? { matchQualityNote } : {}) };
+}
 // flair#1199/#1206 — the default cap on how many org events bootstrap ships.
 // Overridable per-request via `maxEvents`. Event slots are scarce AND (as of
 // #1199) token-charged, so this bounds both the count and the spend; the shared
@@ -670,12 +699,17 @@ export class BootstrapMemories extends Resource {
             // on the REST path); see contentCost. #1207 stays honored: on the prose
             // path this is still the prose-line cost, so REST recall is unchanged.
             const cost = contentCost(struct, line);
-            if (cost <= tokenBudget) {
+            // flair#1199 trust-admission — charge the trust block's real serialized
+            // cost at the same moment as the content cost (per-item trust is CONTENT,
+            // not fixed scaffolding; see buildTrustEntry).
+            const trustEntry = includeTrust ? buildTrustEntry(m, "permanent") : null;
+            const trustCost = trustEntry ? estimateTokens(JSON.stringify(trustEntry)) : 0;
+            if (cost + trustCost <= tokenBudget) {
                 sections.permanent.push(line);
                 includedOwnMemories.push(struct);
-                if (includeTrust)
-                    includedTrustMemories.push({ m, section: "permanent" });
-                tokenBudget -= cost;
+                if (trustEntry)
+                    includedTrustMemories.push(trustEntry);
+                tokenBudget -= cost + trustCost;
                 includedOwnIds.add(m.id); // #1207 — count by unique own-memory id
             }
             else {
@@ -743,16 +777,20 @@ export class BootstrapMemories extends Resource {
             const line = formatMemory(m, agentId);
             const struct = leanMemory(m, "recent");
             const cost = contentCost(struct, line); // #1199 (0.44.11) — charge what ships; see contentCost
-            if (recentSpent + cost > recentBudget) {
+            // flair#1199 trust-admission — charge the trust block's real serialized
+            // cost against BOTH the recent sub-budget and the shared tokenBudget.
+            const trustEntry = includeTrust ? buildTrustEntry(m, "recent") : null;
+            const trustCost = trustEntry ? estimateTokens(JSON.stringify(trustEntry)) : 0;
+            if (recentSpent + cost + trustCost > recentBudget) {
                 truncatedOwnIds.add(m.id); // #1207 — budget-skip; may still be admitted later via the task-relevant loop (deduped at the end)
                 continue;
             }
             sections.recent.push(line);
             includedOwnMemories.push(struct);
-            if (includeTrust)
-                includedTrustMemories.push({ m, section: "recent" });
-            recentSpent += cost;
-            tokenBudget -= cost;
+            if (trustEntry)
+                includedTrustMemories.push(trustEntry);
+            recentSpent += cost + trustCost;
+            tokenBudget -= cost + trustCost;
             includedOwnIds.add(m.id); // #1207 — count by unique own-memory id
         }
         // --- 3b. Subject-predicted context ---
@@ -787,16 +825,20 @@ export class BootstrapMemories extends Resource {
                 const line = formatMemory(m, agentId);
                 const struct = leanMemory(m, "predicted");
                 const cost = contentCost(struct, line); // #1199 (0.44.11) — charge what ships; see contentCost
-                if (predictedSpent + cost > predictedBudget) {
+                // flair#1199 trust-admission — charge the trust block's real serialized
+                // cost against BOTH the predicted sub-budget and the shared tokenBudget.
+                const trustEntry = includeTrust ? buildTrustEntry(m, "predicted") : null;
+                const trustCost = trustEntry ? estimateTokens(JSON.stringify(trustEntry)) : 0;
+                if (predictedSpent + cost + trustCost > predictedBudget) {
                     truncatedOwnIds.add(m.id); // #1207 — budget-skip (deduped against inclusions at the end)
                     continue;
                 }
                 sections.predicted.push(line);
                 includedPredicted.push(struct);
-                if (includeTrust)
-                    includedTrustMemories.push({ m, section: "predicted" });
-                predictedSpent += cost;
-                tokenBudget -= cost;
+                if (trustEntry)
+                    includedTrustMemories.push(trustEntry);
+                predictedSpent += cost + trustCost;
+                tokenBudget -= cost + trustCost;
                 includedOwnIds.add(m.id); // #1207 — count by unique own-memory id; also the task-relevant loop's exclusion set (no predicted→relevant double-admit)
             }
         }
@@ -985,7 +1027,13 @@ export class BootstrapMemories extends Resource {
                         }
                         : leanMemory(m, "relevant");
                     const cost = contentCost(struct, line);
-                    if (cost > tokenBudget) {
+                    // flair#1199 trust-admission — charge the trust block's real serialized
+                    // cost at the same moment as the content cost. The section (teammate vs
+                    // relevant) is decided by `m._source`, so build the entry with the right
+                    // section before the budget check.
+                    const trustEntry = includeTrust ? buildTrustEntry(m, m._source ? "teammate" : "relevant") : null;
+                    const trustCost = trustEntry ? estimateTokens(JSON.stringify(trustEntry)) : 0;
+                    if (cost + trustCost > tokenBudget) {
                         // flair#1207 — a size-skip in the score-ordered task-relevant loop
                         // is no longer silent: record it on the denominator matching the
                         // record's origin (own → truncatedOwnIds, teammate → the separate
@@ -1006,9 +1054,9 @@ export class BootstrapMemories extends Resource {
                         // memoriesIncluded — that different-denominator mix is what let
                         // included exceed available.
                         includedTeammateFindings.push(struct);
-                        if (includeTrust)
-                            includedTrustMemories.push({ m, section: "teammate" });
-                        tokenBudget -= cost;
+                        if (trustEntry)
+                            includedTrustMemories.push(trustEntry);
+                        tokenBudget -= cost + trustCost;
                         teammateFindingsIncluded++;
                     }
                     else {
@@ -1016,9 +1064,9 @@ export class BootstrapMemories extends Resource {
                         // flair#1182 — own task-relevant records join the `memories`
                         // container.
                         includedOwnMemories.push(struct);
-                        if (includeTrust)
-                            includedTrustMemories.push({ m, section: "relevant" });
-                        tokenBudget -= cost;
+                        if (trustEntry)
+                            includedTrustMemories.push(trustEntry);
+                        tokenBudget -= cost + trustCost;
                         includedOwnIds.add(m.id); // #1207 — count by unique own-memory id
                     }
                 }
@@ -1346,28 +1394,12 @@ export class BootstrapMemories extends Resource {
         // caller's own records. flair#1225 (0.44.11) — the null on a lifecycle
         // section is now SELF-EXPLAINING (matchQualityNote below), not just legible
         // via `section`.
-        const trust = includeTrust
-            ? includedTrustMemories.map(({ m, section }) => {
-                const block = buildTrustBlock(m);
-                // flair#1225 — Kern ruled (on #1220) that a null `matchQuality` on an
-                // own-recent (lifecycle) entry is CORRECT: lifecycle sections
-                // (permanent/recent/predicted) are a window LOAD, not a retrieval
-                // surface, so there is no similarity to band — the null means "not
-                // scored here", never a scoring failure on the caller's own records
-                // (the #1201 misread: own-recent null beside a teammate band). Behavior
-                // is unchanged (per Kern); this only makes the null self-describing in
-                // the payload — Fix 3's "any absent field says why" — so a connector
-                // reads it right without knowing the #1201 contract.
-                const matchQualityNote = block.matchQuality === null
-                    ? (LIFECYCLE_SECTIONS.has(section)
-                        ? `matchQuality is null because '${section}' is a lifecycle-window section, not a retrieval `
-                            + `surface — there is no relevance score to band. This is correct (per flair#1225), not a scoring failure.`
-                        : "matchQuality is null because no semantic similarity was attached to this result "
-                            + "(e.g. a by-id read or a keyword-only degraded match).")
-                    : undefined;
-                return { id: m.id, section, ...block, ...(matchQualityNote ? { matchQualityNote } : {}) };
-            })
-            : undefined;
+        // flair#1199 trust-admission — the trust entries were built (and their real
+        // serialized cost charged) at admission time via buildTrustEntry, so the
+        // response tail just ships them as-is. The #1225 matchQualityNote logic now
+        // lives in buildTrustEntry (single source of truth — the charged size and
+        // the shipped size can never drift).
+        const trust = includeTrust ? includedTrustMemories : undefined;
         // flair#744 slice 2 — opt-in abstention verdict for the task-relevance
         // surface. Present ONLY when `abstain` is requested (byte-identical to
         // pre-slice-2 otherwise); scoped to whether any memory covered

package/dist/resources/memory-durability.js

@@ -0,0 +1,40 @@
+/**
+ * ─── The single "is this a valid durability" writer-intent guard ────────────
+ *
+ * Mirror of resources/memory-visibility.ts's assertValidVisibility, for the
+ * durability enum. Same asymmetry, same reason:
+ *
+ *   - READING an unknown durability must be permissive. A row written before a
+ *     tier existed (or by a non-Python adapter) may hold anything, and the read
+ *     side must keep resolving it exactly as before — defaultVisibilityForDurability
+ *     treats any non-permanent/persistent string as the private branch, and that
+ *     fail-safe must not change.
+ *   - WRITING an unknown durability must be refused. Today an unknown value via
+ *     raw REST (or a future non-Python adapter) is silently accepted and lands on
+ *     the narrower private branch by accident — fail-safe, but unvalidated by
+ *     contract. Refusing at the schema boundary makes it safe by construction and
+ *     makes adk-flair's "validated server-side" claim true as written (flair#1238,
+ *     from Sherlock's #1237 review).
+ *
+ * Deliberately has ZERO imports — same load-bearing reason as memory-visibility.ts:
+ * this module is a pure function + constant that any caller can import without
+ * dragging in "harper".
+ */
+/** The only values a WRITER may supply. */
+export const WRITABLE_DURABILITIES = ["permanent", "persistent", "standard", "ephemeral"];
+/**
+ * Reject a durability a writer supplied that is not one of the four valid values.
+ * Returns an error message, or null when the value is acceptable.
+ *
+ * `undefined`/`null` are accepted: omitting the field is how a caller asks for
+ * the default ("standard"), and that is a documented, intentional path.
+ */
+export function assertValidDurability(durability) {
+    if (durability === undefined || durability === null)
+        return null;
+    if (typeof durability === "string" && WRITABLE_DURABILITIES.includes(durability)) {
+        return null;
+    }
+    return (`durability must be ${WRITABLE_DURABILITIES.map((v) => `"${v}"`).join(" or ")} ` +
+        `(got: ${JSON.stringify(durability)}). Omit it to use the default "standard".`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.44.11",
+  "version": "0.44.12",
   "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",