@tpsdev-ai/flair 0.28.0 → 0.30.0

package/schemas/memory.graphql

@@ -44,13 +44,17 @@ type Memory @table(database: "flair") {
   usageCount: Int              # flair#683: verified-USE signal, distinct from retrievalCount (a
                                # search HIT). Additive/nullable — absent reads as 0, existing rows
                                # unaffected. NEVER auto-incremented on search/retrieval; the ONLY
-                               # writer is the dedicated usage-feedback endpoint (resources/
-                               # MemoryUsage.ts), which does a targeted patchRecord increment on
-                               # this field alone (never through Memory.put() — see that
-                               # resource's module doc for why: usage-feedback writes to ANOTHER
-                               # agent's memory, and Memory's ownership check would 403 every
-                               # legit call). Drives usageBoost in resources/scoring.ts, which
-                               # replaces retrievalBoost in compositeScore (retrievalCount was the
+                               # writer is resources/usage-recording.ts's recordUsageContribution()
+                               # — the shared ledger core behind BOTH usage surfaces: POST
+                               # /RecordUsage (resources/RecordUsage.ts) and citation-on-write
+                               # (resources/Memory.ts post()/put() → recordCitations(), which also
+                               # validates each cited id against the writer's read scope,
+                               # flair#775). It does a targeted get-then-put increment on this
+                               # field alone (never through Memory.put() — see RecordUsage.ts's
+                               # module doc for why: usage feedback writes to ANOTHER agent's
+                               # memory, and Memory's ownership check would 403 every legit
+                               # call). Drives usageBoost in resources/scoring.ts, which replaces
+                               # retrievalBoost in compositeScore (retrievalCount was the
                                # contaminated "retrieval counted as usage" signal root-caused in
                                # flair#623).
   promotionStatus: String   # null | "pending" | "approved" | "rejected"
@@ -155,9 +159,12 @@ type MemoryGrant @table(database: "flair") @export {
 # contributed to this memory's usageCount" is a single point-lookup, not a
 # query. This is what makes the anti-gaming dedup rule ("each (agent, memory)
 # pair contributes at most 1 to usageCount" — Sherlock) enforceable: the
-# dedicated endpoint (resources/MemoryUsage.ts) only bumps Memory.usageCount
-# when a NEW row is created here; a repeat call from the same agent for the
-# same memory is a no-op against a row that already exists.
+# shared ledger core (resources/usage-recording.ts's recordUsageContribution(),
+# reached via POST /RecordUsage and via citation-on-write's recordCitations())
+# only bumps Memory.usageCount when a NEW row is created here; a repeat call
+# from the same agent for the same memory is a no-op against a row that
+# already exists. resources/MemoryUsage.ts guards this table's own HTTP
+# surface (it is not the writer).
 #
 # `attribution` is OPAQUE — never parsed, never fed to an LLM, never rendered
 # — a free-text "what used this" hint the caller supplies, sanitized
@@ -172,7 +179,7 @@ type MemoryUsage @table(database: "flair") {
 }
 
 # MemoryCandidate — staged distillations from the FLAIR-NIGHTLY-REM cycle.
-# Per specs/FLAIR-NIGHTLY-REM.md § 7. Slice 1 of ops-2qq adds the schema +
+# Per docs/rem.md. Slice 1 of ops-2qq adds the schema +
 # `flair rem candidates` listing command. Future slices wire the nightly
 # cycle that populates this table and the promote/reject endpoints.
 #
@@ -181,7 +188,15 @@ type MemoryUsage @table(database: "flair") {
 # that requires both --rationale and --to (soul|memory). Rejected candidates
 # retain their decision history so recurring false-positives become visible
 # via the `supersedes` chain.
-type MemoryCandidate @table(database: "flair") {
+#
+# flair#849: this type shipped WITHOUT @export, so it had no REST surface at
+# all — `flair rem candidates`/`promote`/`reject` 404'd on every call, a
+# clean-room dogfood blocker. @export alone would have reopened the exact P0
+# leak the memory-soul-read-gate family fix closed for every other
+# agent-facing table (anonymous read/write of every row); see
+# resources/MemoryCandidate.ts for the paired identity-gated, owner-scoped
+# resource class that makes @export here safe.
+type MemoryCandidate @table(database: "flair") @export {
   id: ID @primaryKey
   agentId: String! @indexed
   claim: String!                   # distilled lesson text