@tpsdev-ai/flair 0.47.1 → 0.48.0

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.47.1",
-  "commit": "2a5259e318163710b73490fb6b6abc5f25aac967",
-  "builtAt": "2026-08-22T14:43:00.927Z",
+  "version": "0.48.0",
+  "commit": "a6cc5ad0f58d9b2549ffd6214028120955c87349",
+  "builtAt": "2026-08-22T19:11:54.849Z",
   "builder": "tsc"
 }

package/dist/resources/Memory.js

@@ -614,8 +614,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 +672,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);

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

package/package.json

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

package/schemas/memory.graphql

@@ -85,6 +85,19 @@ type Memory @table(database: "flair") {
                                # stamped by the ORIGINATING instance itself and preserved (never re-stamped) as the record flows through
                                # sync merges. @indexed for the later sync push-query filter (per-record signature verification and the
                                # classifier org-gate are separate, later slices — not built here).
+  metadata: String             # JSON blob (flair#1332/#1202): ADK custom_metadata, store-and-return. CLIENT-WRITABLE
+                               # (unlike provenance above, which is server-stamped) and OPAQUE TO THE SERVER by
+                               # contract: stored verbatim, returned verbatim, never parsed server-side, never
+                               # queryable (Harper cannot query into a JSON blob), and NO key inside this blob
+                               # ever influences any server decision — visibility, read-scope, durability,
+                               # expiry, federation, ranking, nothing. A blob carrying {"visibility":"shared"}
+                               # leaves the record's ACTUAL visibility at its default (contract-tested in
+                               # packages/adk-flair/tests/test_metadata_and_list.py). If a specific key ever
+                               # needs to be filterable, promote THAT key to its own @indexed scalar column
+                               # (the #1202-documented add-on pattern; `subject` below is the first example) —
+                               # never parse this blob. Size/shape caps are enforced at the writing client
+                               # (adk-flair: 64KB serialized, depth ≤ 16, ≤ 512 keys). Nullable/additive —
+                               # existing rows read null, unchanged behavior (clean-upgrade-path gate).
   entities: [String] @indexed  # attention-plane vocabulary strings (flair#675). Added in v1 (not v2) per K&S
                                # verdict on FLAIR-ATTENTION-PLANE.md — gives the future attention query
                                # uniform index pushdown across Memory/WorkspaceState/OrgEvent instead of a