@tpsdev-ai/flair 0.51.1 → 0.52.0

package/docs/integrations.md

@@ -90,13 +90,13 @@ n8n still uses Harper admin Basic auth — it is not this path. See [n8n.md](n8n
 
 No install step needed — every snippet below uses `npx -y @tpsdev-ai/flair-mcp`, which fetches and runs the server on demand (zero-install). The fastest path is `flair init`, which detects and wires these clients for you. To wire by hand, drop the relevant snippet into each tool's MCP config:
 
-**Claude Code** (`~/.config/claude-code/config.toml` or per-project `.claude/config.toml`):
-```toml
-[mcp.servers.flair]
-command = "npx"
-args = ["-y", "@tpsdev-ai/flair-mcp"]
-env = { FLAIR_AGENT_ID = "claude-code" }
+**Claude Code** (user scope lives in `~/.claude.json` — the file `claude mcp add`, `flair init`, and `flair doctor` all read and write):
+```bash
+claude mcp add flair --scope user \
+  -e FLAIR_AGENT_ID=claude-code \
+  -- npx -y @tpsdev-ai/flair-mcp
 ```
+Or, for a project-scoped server checked into the repo, add the same `mcpServers.flair` block (Cursor's shape below) to `.mcp.json`.
 
 **Cursor** (`~/.cursor/mcp.json`):
 ```json

package/docs/mcp-clients.md

@@ -284,7 +284,7 @@ Twelve tools, kept deliberately small:
 | `memory_delete` | Remove a memory |
 | `relationship_store` | Record a subject-predicate-object relationship triple (e.g. "nathan manages flair") |
 | `bootstrap` | Get session-start context: soul + recent memories + predicted-relevant context |
-| `soul_set` | Set a personality/project/standards entry — included in every bootstrap |
+| `soul_set` | Runtime writes are refused; use operator credentials through `flair soul set` |
 | `soul_get` | Get a soul entry |
 | `flair_workspace_set` | Set your agent's current workspace state (ref/branch, phase, task) in the Office Space |
 | `flair_orgevent` | Publish an org-wide coordination event (claim/release/status) to the Office Space |
@@ -355,3 +355,18 @@ Future MCP-capable agent CLIs (and there are more landing every month) will work
 **Tool calls succeed but the agent doesn't see results in subsequent turns.** Check that the CLI is actually invoking `bootstrap` at session start — most CLIs need an explicit prompt nudge ("call the bootstrap tool now") on first use. Subsequent turns should pick up automatically once the CLI sees the schema.
 
 For deeper issues see [`troubleshooting.md`](troubleshooting.md) and the [`@tpsdev-ai/flair-mcp` repo](https://github.com/tpsdev-ai/flair/tree/main/packages/flair-mcp).
+
+
+### Task-aware bootstrap budgets
+
+Pass `currentTask` when the session's task is known. Bootstrap reserves 30% of
+`maxTokens` for task-relevant memories after Soul admission, protecting recall
+from large pinned sets. Task retrieval can also spend any other remaining space;
+unused space returns to pinned memories. This changes admission priority, not
+retrieval ranking or visibility. Individual records still must fit, including
+trust metadata when requested. A record larger than the available allowance
+can still be omitted.
+
+Without a task (including blank text), bootstrap retains its existing admission
+policy. `taskRetrievalHint`, when present, explains unavailable embeddings, an
+empty candidate pool, exhausted budget, or candidates already included/too large.

package/docs/releasing.md

@@ -87,14 +87,17 @@ tag you pushed is the trigger). Watch the run; when it's green, the packages are
 but **not yet live**.
 
 In parallel — and **independent of the npm staging approval** — a `github-release` job
-auto-cuts a [GitHub release](https://github.com/tpsdev-ai/flair/releases) for the tag,
-using the matching `## [X.Y.Z]` section of `CHANGELOG.md` as the release notes (extracted
-by `scripts/changelog-extract.mjs`). It is idempotent: re-running the workflow or
-re-pushing the tag updates the existing release rather than failing. The GitHub release
-documents the tagged commit immediately; it does not wait on the npm 2FA gate. If the
-CHANGELOG has no section for the version, this job fails loudly rather than cutting an
-empty release — which is why phase 1's fragment assembly refuses to produce an empty
-section rather than letting the failure surface here, after the tag is already pushed.
+auto-cuts a [GitHub release](https://github.com/tpsdev-ai/flair/releases) for the tag.
+Release notes are a **lede + links** rendering of the matching `## [X.Y.Z]` section
+(`scripts/changelog-release-notes.mjs`): each entry keeps its bold lede, up to three
+issue links, and any `> **Heads-up:**` operator lines. The deep record stays in
+`CHANGELOG.md` and is linked from the footer at that tag. It is idempotent: re-running
+the workflow or re-pushing the tag updates the existing release rather than failing.
+The GitHub release documents the tagged commit immediately; it does not wait on the
+npm 2FA gate. If the CHANGELOG has no section for the version, this job fails loudly
+rather than cutting an empty release — which is why phase 1's fragment assembly
+refuses to produce an empty section rather than letting the failure surface here,
+after the tag is already pushed.
 
 > `workflow_dispatch` with a `version` input remains as a manual fallback (needs
 > `Actions: write`), but the tag push is the normal path.

package/docs/rem.md

@@ -52,28 +52,46 @@ Selects which `models.generative.<logicalName>` entry a REM call uses. Unset →
 
 `flair rem nightly enable` installs a platform-native timer (launchd / systemd) **on the host it runs on**. In a multi-node or Fabric deploy, enabling it on every node would run the cycle N times and scatter N sets of pre-cycle snapshots. The v1 rule: **exactly one node gets the timer** — pick it deliberately, the same way you'd pick a cron owner for any single-writer job. This is a v1 constraint, not a permanent one; see #709 for the roadmap toward a coordinated multi-node story.
 
-Snapshot locality follows from this: a nightly cycle's pre-run snapshot (`~/.flair/snapshots/<agent>/`) lands on **the node that ran that cycle** — `flair rem restore <date>` and `flair rem snapshot list` only see local snapshots. If you move which node owns the timer, snapshot history doesn't move with it.
+Snapshot locality follows from this: a nightly cycle's pre-run snapshot (`~/.flair/snapshots/<agent>/`) lands on **the node that ran that cycle** — `flair rem restore <date>` and `flair rem snapshot list` only see local snapshots. If you move which node owns the timer, snapshot history doesn't move with it. Live replay (`flair rem restore <date> --apply`) rewrites Soul with operator credentials (`--admin-pass` / `--admin-pass-file`); an agent key is refused. Leftover MemoryCandidate rows for that agent are deleted first so their claim text cannot block Soul restore.
 
 ## Interactive vs nightly
 
 - **Interactive (`flair rem rapid`):** one bounded, synchronous distillation call — gather cap 50 memories, bounded output tokens, seconds not minutes. Executes by default, staging candidates and printing a summary; `--prompt-only` returns the reflection prompt instead, for the bring-your-own-model handoff.
 - **Nightly (`flair rem nightly enable` / `run-once`):** fully detached — the scheduler runs the full cycle (snapshot → maintenance → distillation), candidates land as pending rows, and an audit row lands in `~/.flair/logs/rem-nightly.jsonl`. The operator reviews in the morning via `flair rem candidates`.
 
+### Safety bounds (a large backlog must not take the instance down)
+
+A first run over thousands of unreflected memories used to hold the Harper main thread long enough that `/Health` and search timed out. Nightly distillation is now bounded:
+
+- **Refuse to start** when `GET /Health` cannot be served within 2 seconds. The cycle logs `status: "refused"` and prints the reason; the scheduler will try again next night. Restore `/Health` before retrying, or `flair rem pause` to stop the timer.
+- **Per-run cap** — at most 50 memories per `/ReflectMemories` call (`FLAIR_REM_MAX_MEMORIES`, hard ceiling 200), oldest-unreflected first so a 3k backlog drains across nights instead of one blocking run. Already-reflected rows fill leftover slots only when fewer than N unreflected matches remain. Nightly uses `scope: "all"` for ordinary (non-ADK) agents so the cap sees the whole backlog, not only the last 24 hours.
+- **Yield + abort** — the gather scan yields so `/Health` and reads keep serving. `flair rem pause` (or `flair rem abort`) writes `~/.flair/rem.paused`; an in-flight gather on the same host stops at the next yield without restarting Harper.
+
+`flair rem rapid` uses the same gather cap, oldest-unreflected selection, yield, and abort checks. It still defaults to `scope: "recent"` (last 24 hours) unless you pass `--since` / a wider scope.
+
 Either path, the review loop is the same: `flair rem candidates` lists pending rows, `flair rem promote <id> --rationale "<why>"` / `flair rem reject <id> --reason "<why>"` decide them. Nothing self-promotes except the narrow ADK per-user path ([Auto-promote](#auto-promote-adk-only)) — see [`docs/notes/rem-ux.md`](notes/rem-ux.md) for why that gate is load-bearing and how the surface is expected to evolve.
 
 ### ADK agents — per-user (per-tag) distillation
 
 adk-flair collapses every `(app, user)` into **one** Flair agentId, separating users only by a per-user tag `adk:<app>:<user>`. Distilling such an agentId with the default `scope:"recent"` would mix every user's sessions into shared claims — cross-user bleed. The nightly cycle therefore detects the agent's active `adk:<app>:<user>` tags (from the memories it already loads for the snapshot, with a recency cutoff that skips idle users and is scoped to the agent's own records) and runs distillation **once per tag** under `scope:"tagged"`, so each user's candidates come only from that user's own sessions. Agents with no `adk:` tags distill agentId-wide exactly as before.
 
+Memory promotion runs through `POST /PromoteMemoryCandidate` with `candidateId` and a nonempty `rationale`. The server reads the candidate and its lineage, writes the persistent memory through the normal safety/provenance path, and stamps `promotionStatus`, `promotedAt` and `promotedBy`. Direct Memory writes cannot create, change or clear these workflow fields, including administrator REST writes. Full-row updates may echo unchanged stamps; omitted stamps are preserved. Creating a successor with `memory_update(preserveHistory=true)` leaves the verdict on the predecessor; the new content starts without an approval stamp. Non-admin reviewers are attributed to their authenticated identity; only administrators may name another reviewer. `flair rem promote --to memory` uses this endpoint and requires an updated server; it does not fall back to direct verdict writes.
+
 A candidate distilled under a tag records that tag in its `scopeTag` field. `flair rem promote` reads `scopeTag` as the authoritative per-user lineage tag and propagates it onto the promoted memory — so the promoted claim stays in that user's retrieval scope even if the source episodes are later archived or deleted. The single-node timer rule above is unchanged; the per-tag loop runs inside the one cycle on the one node. The non-thinking-model requirement (above) still holds — the per-tag path calls the same `models.generate()` route.
 
 #### Auto-promote (ADK only)
 
 For ADK agents, the nightly cycle **auto-promotes** these `scopeTag`-bearing candidates to the user's own persistent memory immediately after distillation — the one place REM does not wait for a human `rem promote`. The safety argument is blast-radius, not identity: the claim is distilled from a user's own sessions into that same user's own tag scope, so no cross-agent or Soul trust boundary is crossed. The promotion is enforced entirely server-side (`POST /AutoPromoteCandidates`), never by a CLI flag a compromised agent key could flip, and holds four invariants:
 
-- **Memory only, never Soul.** The target is hard-locked to `memory`; there is no Soul code path (Soul is agentId-scoped and cannot carry a per-user tag, so an ADK-sourced Soul promotion would be cross-user by construction).
+- **Memory only, never Soul.** The target is hard-locked to `memory`; there is no Soul code path (Soul is agentId-scoped and cannot carry a per-user tag, so an ADK-sourced Soul promotion would be cross-user by construction). Soul mutations require operator credentials and refuse values matching any stored Memory or MemoryCandidate. This also prevents scripted promotion of learned claims, regardless of connector. See [Soul authorship](auth.md#soul-authorship).
 - **Fail-closed tag lineage.** A candidate is promoted only if it carries an authoritative `adk:<app>:<user>` scope tag, which the promoted memory then carries. The promoted memory is written `visibility:"private"` (owner-only) — not the org-open `shared` default a `persistent` write would otherwise get — so it is reachable only through the app agent's own tag-filtered search (which re-verifies the tag), invisible both to another user's tag filter and to every other agent on the instance. A candidate whose scope tag is absent or blank is left pending, never promoted tagless into the shared agentId namespace.
 - **Content-safety, strict.** The claim is scanned for prompt injection and refused on a flag regardless of `FLAIR_CONTENT_SAFETY` — an unattended write does not fall back to warn-and-tag.
 - **Non-impersonating reviewer.** The promoted memory and its candidate record `machine:adk-auto-promote`, never a value mistakable for a human or agent reviewer.
 
 Anything ineligible (no scope tag, flagged content, already decided) is left pending for the human `rem promote` path. The step is bounded per cycle and non-fatal; `flair rem nightly run-once` reports the count auto-promoted. **Non-ADK candidates never auto-promote** — the human review gate below is unchanged for them.
+
+## Memory retention and deletion
+
+Durability is owner-controlled, including `permanent`: owners may create, change, archive and delete their own memories at every tier. Administrators may delete any owner’s memory. The permanent tier controls retention and bootstrap priority; it does not prevent an explicit owner deletion.
+
+Soul is operator-authored identity, not a promotion target for learned candidates. `flair rem promote --to soul` is refused for stored candidate text even with operator credentials; promote learned claims to Memory instead.

package/docs/upgrade.md

@@ -8,8 +8,9 @@ target version before upgrading anything you depend on in production.
 
 There are two things you might be upgrading:
 
-1. **A local npm install** — the common case: `flair` running on your own machine or a
-   VPS, installed via `npm install -g @tpsdev-ai/flair`.
+1. **A local install** — the common case: `flair` on your own machine or a VPS,
+   either via `npm install -g @tpsdev-ai/flair` or a plain extracted tree
+   (`npm pack` + `npm install --omit=dev` under systemd).
 2. **A Flair component deployed to a Harper Fabric cluster** — a different mechanism
    (`flair deploy` / `flair upgrade --target`), covered separately below.
 
@@ -43,6 +44,48 @@ transitive dependency). **Other integrations upgrade in their own ecosystem, not
 `flair upgrade`:** `pi-flair` (pi's plugin manager), `langgraph-flair` / `hermes-flair`
 (pip / your Python package manager), `n8n-nodes-flair` (n8n's Community Nodes UI).
 
+If the running instance's exec path is a **plain extracted tree** (npm pack +
+`npm install --omit=dev`, typically under systemd — no git checkout, not the
+npm-global prefix), `flair upgrade` takes that lane: it fetches the published
+tarball, swaps the tree in place, keeps operator launchers that are not in the
+pack, and restarts the systemd unit that points at the tree (or `flair restart`
+when no unit is found). Pass `--tree <dir>` to select the tree explicitly;
+`--flair-version <semver>` pins the tarball.
+
+A leftover npm-global relic next to a tree that is **not** a packed install
+still gets the mismatch warning: the listing is the npm-global surface and the
+warning names both paths so the relic is not reported as "the" install. Git
+checkouts and source trees are never tarball-swapped.
+
+### Plain-tree / npm-pack install
+
+Spokes that extract the published tarball and run `npm install --omit=dev`
+under a systemd unit — no git checkout, no `npm install -g` — use the same
+command. `flair upgrade` detects the serving tree (or takes `--tree <dir>`)
+and:
+
+1. Fetches `@tpsdev-ai/flair@<version>` with `npm pack`
+2. Extracts it next to the live tree and runs `npm install --omit=dev`
+3. Copies operator files at the tree root that are **not** in the published
+   pack (a `flair` wrapper, `.env`, anything else you added)
+4. Renames the live tree to `<tree>.upgrade-prev` and the staging dir into
+   place
+5. Restarts the systemd unit whose `WorkingDirectory` / `ExecStart` names the
+   tree (`FLAIR_SYSTEMD_UNIT=flair.service` adds an explicit unit). If no unit
+   is found, it falls back to `flair restart`
+6. Verifies, then removes `.upgrade-prev`. On a failed restart or verify the
+   previous tree is swapped back
+
+```bash
+flair upgrade --check --tree /opt/flair
+flair upgrade --tree /opt/flair
+flair upgrade --tree /opt/flair --flair-version 0.50.0
+```
+
+`--check` prints the plan (versions, preserved names, which unit will restart)
+without touching the tree. A git checkout or a path that *is* the npm-global
+install is refused rather than overwritten.
+
 ### Upgrade is a transaction
 
 As of flair#635, `flair upgrade` is install → restart → verify →
@@ -557,3 +600,5 @@ you haven't personally tested.
   shows up when it does.
 - [`docs/deployment.md`](deployment.md) — initial install / deployment, as opposed to
   upgrading an existing one.
+- [`docs/api-reference.md`](api-reference.md) — HTTP endpoints, auth per resource, and
+  the Presence / Memory / Soul / Agent / Federation schemas.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.51.1",
+  "version": "0.52.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",
@@ -50,7 +50,8 @@
     "build": "tsc -p tsconfig.json --noCheck && node scripts/write-build-info.mjs",
     "build:cli": "tsc -p tsconfig.cli.json --noCheck && node scripts/write-build-info.mjs",
     "prepublishOnly": "npm run build && npm run build:cli",
-    "test": "bun test",
+    "test": "bun run test:unit",
+    "test:unit": "bun scripts/test-unit.ts",
     "test:e2e": "playwright test",
     "release": "./scripts/release.sh",
     "postinstall": "node -e \"try{require('./dist/postinstall.cjs')}catch(e){}\""
@@ -65,10 +66,10 @@
     "@harperfast/oauth": "2.5.0",
     "@types/js-yaml": "4.0.9",
     "commander": "14.0.3",
-    "harper": "5.2.7",
+    "harper": "5.2.8",
     "harper-fabric-embeddings": "^0.5.0",
     "jose": "6.2.2",
-    "js-yaml": "^4.3.1",
+    "js-yaml": "^4.3.2",
     "tar": "^7.5.22",
     "tweetnacl": "1.0.3"
   },
@@ -76,15 +77,19 @@
     "react-native-fs": "npm:empty-npm-package@1.0.0",
     "brace-expansion": "^5.0.9",
     "undici": "^8.9.0",
-    "fast-uri": "^4.1.2",
-    "hono": "^4.12.34",
-    "js-yaml": "^4.3.1",
+    "fast-uri": "^4.1.3",
+    "hono": "^4.13.5",
+    "js-yaml": "^4.3.2",
     "adm-zip": "^0.6.0",
     "@opentelemetry/core": "^2.8.0",
     "uuid": "^11.1.1",
     "tar": "^7.5.22",
     "@tootallnate/once": "^2.0.1",
-    "form-data": "^4.0.6"
+    "form-data": "^4.0.6",
+    "mysql2": "^3.22.0",
+    "mariadb": "~3.4.7",
+    "qs": "^6.16.0",
+    "fastify": "^5.12.1"
   },
   "devDependencies": {
     "@playwright/test": "1.59.1",

package/schemas/memory.graphql

@@ -3,6 +3,12 @@ type Memory @table(database: "flair") {
   agentId: String! @indexed
   content: String!
   contentHash: String @indexed
+  trigger: String @indexed   # flair#1542: the "when to use" text for a skill-tagged row. Skill-tagged
+                               # rows embed from `trigger` (the recall signal), NOT from `content` (the full
+                               # procedure) — see resources/skill-write.ts's skillEmbedText. Nullable/additive:
+                               # non-skill rows carry no trigger and embed from `content` exactly as before
+                               # (clean-upgrade-path gate). @indexed so the later skill recall tools can filter
+                               # by trigger without a full-corpus scan.
   visibility: String
   embedding: [Float] @indexed(type: "HNSW", M: 16)   # M:16 is Harper's own HNSW default
                                # (HierarchicalNavigableSmallWorld M default) — declaring it explicitly is a
@@ -39,8 +45,11 @@ type Memory @table(database: "flair") {
   createdAt: String! @indexed
   updatedAt: String
   expiresAt: String @indexed
-  retrievalCount: Int
-  lastRetrieved: String
+  retrievalCount: Int          # Observable search-hit counter. Authoritative increments live on
+                               # MemoryHitStat (resources/hit-tracking.ts, flair#1528); GET/search
+                               # overlay that row so this field still reads as it always has.
+                               # The Memory row itself is no longer rewritten per hit.
+  lastRetrieved: String        # Overlay companion to retrievalCount — see MemoryHitStat.
   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
@@ -149,6 +158,7 @@ type Soul @table(database: "flair") {
   value: String!
   priority: String              # critical | high | standard | low (skill governance)
   metadata: String              # JSON blob (skill governance: source, version, hash, etc.)
+  provenance: String            # Server-derived operator/internal source class and authenticated author.
   durability: String @indexed
   createdAt: String!
   updatedAt: String
@@ -191,6 +201,26 @@ type MemoryUsage @table(database: "flair") {
   createdAt: String!
 }
 
+# MemoryHitStat — search hit-tracking ledger (flair#1528 remaining slice).
+# SemanticSearch used to patchRecord the full Memory row per returned hit so
+# retrievalCount/lastRetrieved stayed on the memory itself. That is a full-row
+# Harper put (embeddings included), feeds BM25/HNSW, and loses increments when
+# concurrent searches read-modify-write the same five hits (Dex: 310 vs 320).
+#
+# This table is the increment target: one small row per memory id, coalesced
+# per-id so concurrent hits add rather than race. No @export — no REST surface.
+# resources/hit-tracking.ts is the only writer. Readers that expose the
+# historical Memory.retrievalCount / lastRetrieved contract overlay this row
+# (Memory.get/search, AdminMemory detail, MemoryConsolidate). Existing Memory
+# field values seed the first increment so a store that already had counts
+# does not reset. Agents have no role grant; internal raw-table writes bypass
+# the flair_agent role the same way usage-recording writes MemoryUsage.
+type MemoryHitStat @table(database: "flair") {
+  id: ID @primaryKey           # Memory.id
+  retrievalCount: Int
+  lastRetrieved: String
+}
+
 # MemoryCandidate — staged distillations from the FLAIR-NIGHTLY-REM cycle.
 # Per docs/rem.md. Slice 1 of ops-2qq adds the schema +
 # `flair rem candidates` listing command. Future slices wire the nightly
@@ -245,3 +275,22 @@ type MemoryCandidate @table(database: "flair") @export {
                                    # visibilityRuling — the auditable "why shared" recorded on the candidate.
                                    # Nullable/additive, same clean-upgrade contract as scopeTag above.
 }
+
+# Asset — binary blobs (screenshots, images) stored out-of-record via Harper's
+# Blob type, referenced from a Memory by `memoryId`. Slice 1: storage only
+# (no MCP exposure). owner-only + identity-gated + federation "excluded" per
+# resources/record-types.ts (RECORD_TYPES.Asset) — a new type must not enter
+# federation sync (Federation.ts's table list is unchanged).
+# Lifecycle: retained until the owner deletes the Asset row. Deleting the
+# parent Memory does not sweep linked blobs (no GC this slice). Slice 2
+# serving 404s dangling refs; GC + memoryId exist-and-owned check deferred.
+# updatedAt is nullable/additive so a later sweep can key on recency.
+type Asset @table(database: "flair") @export {
+  id: ID @primaryKey
+  agentId: String! @indexed        # owner (no-forge attribution / read scope)
+  memoryId: String @indexed        # the Memory record this asset belongs to
+  contentType: String              # MIME type, e.g. image/jpeg
+  data: Blob                       # binary content, stored out-of-record
+  createdAt: String! @indexed
+  updatedAt: String                # stamped on write; later sweep key (nullable/additive)
+}

package/schemas/message.graphql

@@ -0,0 +1,74 @@
+# Message table — Flair Relay S1 (point-to-point signed messaging).
+#
+# A message is a DIFFERENT primitive from memory and from OrgEvent: it is
+# addressed to a recipient PRINCIPAL, ordered per-sender, durably queued, and
+# explicitly acked, with a VISIBLE dead-letter the sender can see. OrgEvent's
+# `expiresAt` is a silent dead-letter; Message never drops silently.
+#
+# The FULL envelope lands in S1 (not just the fields S1 exercises) so that S2
+# (cross-host) is not a schema migration — `orgScope`, `seq` and `contentHash`
+# are covered by the signature and S2's cross-host correctness needs them.
+# See the Flair Relay S1 design (flair#1521) §4.2 and §12.
+type Message @table(database: "flair") @export {
+  id: ID @primaryKey
+
+  # Server-resolved from the auth/pairing context, never trusted from the body
+  # (single host: the instance IS the org). Inside the signed canonical body.
+  orgScope: String @indexed
+
+  # Owning principal = the SENDER. Stamped from the authenticated identity
+  # (no-forge), and the per-table federation owner field (federation-classify).
+  from: String @indexed
+  to: String @indexed
+
+  # Sender-minted, principal-prefixed, globally unique (↔ A2A contextId later).
+  threadId: String @indexed
+  # Per (from, threadId), monotonic, SIGNED. The recipient sorts by seq at read
+  # (createdAt collides at ms resolution). See §12 P1-5.
+  seq: Int
+
+  # "message" for S1 (the degenerate one-shot). "task"/"task-update" are S3.
+  kind: String
+  # Opaque to Flair.
+  body: String
+
+  # Reply linkage (design §4.2). Lands in S1 so S2/S3 are not a schema
+  # migration, though "understood" reply semantics are S3. Both are CONTENT —
+  # covered by contentHash AND the signature (relay-lib SIGNED_BODY_FIELDS) —
+  # never trusted unsigned. `inReplyTo` is the parent message id; the redundant
+  # `parentContentHash` binds the reply to the parent's exact content.
+  inReplyTo: String
+  parentContentHash: String
+
+  createdAt: String @indexed
+  # Sender-set fail-by. When it passes on an UNCONSUMED message the row goes to
+  # a VISIBLE `failed` state (reason "deadline") — the inverse of a silent drop.
+  deadline: String
+
+  # submitted -> delivered -> consumed | failed. `consumed` is ABSORBING —
+  # no later write (including a deadline sweep) regresses it (§12 P0-3).
+  state: String @indexed
+  deliveredAt: String
+  consumedAt: String @indexed
+  # Dead-letter reason on a `failed` row ("deadline" | "inbox_full" | ...),
+  # queryable by the sender.
+  failureReason: String
+
+  # Over the signed canonical CONTENT — retry-send dedup + a second integrity
+  # check under the signature (§12 P0-4).
+  contentHash: String
+
+  # Provenance (shared with flair#1520) — "which model sent this".
+  senderModel: String
+  senderProvider: String
+  senderRunId: String
+
+  # Ed25519 over the canonical SIGNED body — the single source of truth is
+  # resources/relay-lib.ts SIGNED_BODY_FIELDS; keep this list in sync with it.
+  # It COVERS: the content (from, to, threadId, seq, kind, body, orgScope,
+  # deadline, inReplyTo, parentContentHash, senderModel/Provider/RunId) PLUS
+  # id, createdAt and contentHash. It EXCLUDES the mutable server/lifecycle
+  # fields (state, deliveredAt, consumedAt, failureReason) and this `signature`
+  # field itself. (Not "every field above" — the lifecycle fields are NOT signed.)
+  signature: String
+}