@tpsdev-ai/flair 0.31.0 → 0.32.0

package/dist/resources/record-owner-guard.js

@@ -0,0 +1,149 @@
+/**
+ * record-owner-guard.ts — ONE enforcement point for "you may not modify a
+ * record you do not own".
+ *
+ * ─── The defect this deletes ─────────────────────────────────────────────────
+ *
+ * Harper's REST layer maps verbs to resource methods ONE-TO-ONE (see
+ * harper/dist/server/REST.js's method switch): GET→get, POST→post, PUT→put,
+ * PATCH→patch, DELETE→delete. There is no fallback — `patch()` does NOT route
+ * through `put()`. So an ownership rule written inside a resource's `put()` is
+ * enforced on PUT and on nothing else, and a resource with no `patch()` override
+ * reaches the table with only its `allow*` gate, which is typically
+ * `allowVerified()` — "any verified agent".
+ *
+ * Almost every flair resource wrote its per-record rules in `put()`. That is not
+ * a mistake anyone made once; it is what the resource model invites, because
+ * `put()` is where the write logic naturally goes and nothing anywhere says the
+ * other verbs exist. Fixing it resource-by-resource would mean N hand-written
+ * guards — N chances to get one subtly wrong — and would still leave the NEXT
+ * resource broken by default, because its author would have to know this file
+ * exists to be safe. So the rule lives here instead, once, on the path every
+ * HTTP request already takes.
+ *
+ * ─── The rule, and why it is this narrow ─────────────────────────────────────
+ *
+ *   On a record that ALREADY EXISTS, a non-admin caller whose agent id does not
+ *   match the record's stored owner is refused — on every mutating verb.
+ *
+ * It deliberately says nothing about creation. Over-blocking is the failure mode
+ * a security fix reaches for, and a blunter rule ("the caller must own whatever
+ * it names") would break real flows: Presence heartbeats arrive at the
+ * collection with no record yet, credential provisioning creates rows for other
+ * principals, and a MemoryGrant's `granteeId` is SUPPOSED to be someone else.
+ * Restricting this to records that exist means the guard can only ever narrow
+ * mutation of another agent's data. It cannot break a create, and it cannot
+ * break an agent writing its own record.
+ *
+ * ─── Owner is read from STORED STATE, never from the request body ────────────
+ *
+ * The guards this replaces compared the owner field in the request BODY — the
+ * owner the CALLER CLAIMS — and denied only when that field was present and
+ * mismatched. A body that simply omitted it was compared against nothing and
+ * passed, whatever record the URL named. Harper binds the write to the URL's id,
+ * not to the body, so body-derived authorization was answering a question nobody
+ * asked. That is the same defect as the verb gap wearing different clothes: an
+ * authorization decision made against attacker-supplied data instead of stored
+ * state. Both are closed here, together, because closing one leaves the other
+ * reachable.
+ *
+ * Per-resource body checks (no-forge attribution on CREATE) still belong in the
+ * resources — they answer a different question, "may you attribute a NEW record
+ * to someone else", which this guard does not address.
+ *
+ * ─── Keeping this honest as the codebase grows ───────────────────────────────
+ *
+ * OWNER_FIELDS below is static and PR-reviewed, matching the posture of
+ * resources/record-types.ts. A static map alone would rot, so
+ * test/unit/record-owner-guard-coverage.test.ts parses `schemas/*.graphql` and
+ * FAILS when a table declares an owner-shaped column and is neither listed here
+ * nor exempted with a stated reason. A table added later enters that test's
+ * scope the moment it declares the column — nobody has to know this file exists.
+ */
+/**
+ * Table → the attribute naming the principal that owns a row.
+ *
+ * Derived from the columns actually declared in `schemas/*.graphql`, and pinned
+ * against them by the coverage test. Tables with no resource class are listed
+ * anyway: costing nothing when the route does not exist is much better than
+ * being absent on the day someone adds one.
+ */
+export const OWNER_FIELDS = Object.freeze({
+    Credential: "principalId",
+    Integration: "agentId",
+    Memory: "agentId",
+    MemoryCandidate: "agentId",
+    MemoryGrant: "ownerId",
+    MemoryUsage: "agentId",
+    OAuthAuthCode: "principalId",
+    OAuthToken: "principalId",
+    OrgEvent: "authorId",
+    Presence: "agentId",
+    Relationship: "agentId",
+    Soul: "agentId",
+    WorkspaceState: "agentId",
+});
+/**
+ * Tables that declare an owner-shaped column but are deliberately NOT guarded
+ * here, each with the reason. The coverage test accepts these and rejects
+ * anything else, so an omission has to be argued rather than merely happen.
+ */
+export const OWNER_GUARD_EXEMPT = Object.freeze({
+    // The principal table's own rule is "the record IS the caller", not "the
+    // record has an owner column" — a principal may edit itself, and only an
+    // admin may change anyone's admin status. That is enforced in
+    // resources/Agent.ts's shared write-authorization helper, which both its
+    // put() and its patch() route through.
+    Agent: "self-ownership by primary key; enforced in resources/Agent.ts for every verb",
+});
+/** The verbs that can mutate a record, and therefore need the rule applied. */
+export const MUTATING_METHODS = Object.freeze(["POST", "PUT", "PATCH", "DELETE"]);
+export function isMutatingMethod(method) {
+    return MUTATING_METHODS.includes(method.toUpperCase());
+}
+/**
+ * Resolve a request path to the guarded table and record id it addresses, or
+ * null when the path is not a guarded single-record route.
+ *
+ * Matches `/<Table>/<id>` ONLY. A collection path (`/<Table>`) addresses no
+ * existing record, so there is nothing to own and nothing to check — that is the
+ * "creation is untouched" property, expressed as a parse rather than a special
+ * case. The table segment is matched EXACTLY so `/SoulFeed/x` can never be read
+ * as a `Soul` route.
+ */
+export function resolveGuardedRecord(pathname) {
+    const parts = pathname.split("/").filter(Boolean);
+    if (parts.length < 2)
+        return null;
+    const table = parts[0];
+    const ownerField = OWNER_FIELDS[table];
+    if (!ownerField)
+        return null;
+    let id;
+    try {
+        id = decodeURIComponent(parts[1]);
+    }
+    catch {
+        return null; // malformed percent-encoding addresses no record we can resolve
+    }
+    if (!id)
+        return null;
+    return { table, ownerField, id };
+}
+/**
+ * Decide whether a caller may mutate an already-stored record.
+ *
+ * Pure, so the decision is testable without a Harper instance — the middleware
+ * supplies the record it loaded. A record that does not exist, or that carries
+ * no owner value, is NOT refused here: the first is a create (or a 404 the
+ * resource will produce), and the second is a row with nothing to own, neither
+ * of which this rule is about.
+ */
+export function isForbiddenOwnerMutation(record, ownerField, callerAgentId) {
+    if (!record)
+        return false;
+    const owner = record[ownerField];
+    if (owner == null || owner === "")
+        return false;
+    return owner !== callerAgentId;
+}

package/docs/deployment-shapes.md

@@ -0,0 +1,35 @@
+# Which Flair deployment shape are you in?
+
+Flair runs in one of three shapes. Pick yours and follow only that path.
+
+| You want to... | Shape | Start here |
+|---|---|---|
+| Run Flair on your own machine or VPS. `flair init` installs Harper, creates your agent identity, and you're running. | **Standalone local** | [standalone-local.md](standalone-local.md) |
+| Run Flair on [Harper Fabric](https://www.harperdb.io/) — managed hosting, multi-region replication, no shell on the node. You deploy a component; agents connect over HTTPS. | **Hosted on Fabric** | [hosted-on-fabric.md](hosted-on-fabric.md) |
+| Load Flair into a Harper instance you already run. In-process calls — no HTTP, no second process, no key to distribute. Over HTTP it is one memory API among many. | **Embedded in a Harper app** | [embedding-in-a-harper-app.md](embedding-in-a-harper-app.md) |
+
+---
+
+## What changes across shapes
+
+Not everything is the same. The critical differences:
+
+### Identity
+
+- **Standalone local & Fabric (over HTTP):** Agents authenticate with Ed25519-signed requests. Each agent holds a private key and signs `agentId:timestamp:nonce:METHOD:/path` on every request. The server verifies the signature against the agent's registered public key.
+- **Embedded (in-process):** Identity is **asserted**, not verified. You pass the agent id via the call context — `agentContext("mybot")` — and Flair acts as that agent. No key, no signature, no `Agent`-table lookup. Co-location *is* the trust boundary: a caller inside the same Harper instance could write the storage tables directly anyway, so demanding a signature from same-process code would be theatre. **Never build the context from request data** — that is privilege escalation with no error and no trace.
+
+### Upgrade
+
+- **Standalone local:** `flair upgrade` — install, restart, verify, rollback-on-failure in one step.
+- **Hosted on Fabric:** `flair upgrade --target <fabric-url>` — resolves the target version, stages a clean deployable, and pushes it. Fabric has no `flair upgrade` equivalent to the local path; redeploy the component.
+- **Embedded:** Flair follows your host app's dependency lifecycle. When you update `@tpsdev-ai/flair` in your app's `package.json` and redeploy, Flair upgrades with the rest. There is no `flair upgrade` — it's a component, not a standalone process.
+
+### Federation
+
+- **Standalone local & Fabric:** Available. Hub-and-spoke sync with pairing tokens, signed requests, and originator enforcement. The CLI drives pairing (`flair federation pair`).
+- **Embedded:** Pairing is **CLI-only** today — it requires shell access on the node ([flair#947](https://github.com/tpsdev-ai/flair/issues/947)). If your deployment has no shell, federation is not available.
+
+### `@export`
+
+`@export` on a GraphQL schema means **REST exposure only** — it does not mean replication. `Memory` has no `@export` and still replicates in a Harper Fabric cluster (replication is per-database, not per-export). This is a genuine and easily-inverted trap: do not assume `@export` controls sync or that the absence of `@export` means "not replicated."

package/docs/deployment.md

@@ -192,10 +192,10 @@ Set these in the Flair process environment (`~/Library/LaunchAgents/ai.tpsdev.fl
 
 ```bash
 # Backup all data (agents, memories, souls)
-flair backup > ~/flair-backup-$(date +%Y%m%d).json
+flair backup --output ~/flair-backup-$(date +%Y%m%d).json --admin-pass-file ~/.flair/admin-pass
 
 # Restore to a fresh instance
-flair restore < ~/flair-backup-20260405.json
+flair restore ~/flair-backup-20260405.json
 ```
 
 Always backup before upgrades.

package/docs/embedding-in-a-harper-app.md

@@ -18,86 +18,86 @@ Embedding *adds* the in-process path; `rest: true` keeps serving MCP clients and
 
 **1. Add Flair to your instance.** Deploy `@tpsdev-ai/flair` as a component the way you deploy your own — Fabric's component deploy, Studio, or your pipeline. Its tables are declared `@table(database: "flair")`, so they never collide with yours.
 
-**2. Resolve the resource and write a memory.**
+**2. Import the facade and write a memory.**
 
 ```javascript
-import { server } from "harper";
-// Flair ships these two helpers so you do not have to get either of them right
-// by hand. They are the whole in-process contract.
-import { agentContext, internalContext, collectionResource } from "@tpsdev-ai/flair/dist/resources/in-process.js";
+import { Flair } from "@tpsdev-ai/flair";
 
-// The RESOURCE — carries auth, scoping, visibility, embedding.
-// NOT databases.flair.Memory: that is the raw table, and enforces none of it.
-// Keys carry NO leading slash: get("Memory"), never get("/Memory").
-const flair = (path) => server.resources.get(path).Resource;
+const flair = new Flair(server);
+const planner = flair.as("planner");
 
-export async function remember(agentId, content, opts = {}) {
-  // A create needs a COLLECTION-bound instance. `new Cls(...)` does not give
-  // you one, and cannot be made to — see the note below.
-  const h = await collectionResource(flair("Memory"), agentContext(agentId));
-  return h.post({
-    agentId,                                // required — an absent one is never filled in
-    content,
-    durability: opts.durability ?? "standard",
-  });
-}
+await planner.memory.write("deploy runs at 0200 UTC", { durability: "standard" });
 ```
 
-> ### Why `collectionResource`, and not `new Memory()`
->
-> A resource's `post()` only works on an instance Harper has marked as a **collection**, and that mark is a *private* field only Harper's own `getResource()` can set. The public `isCollection` is a getter with no setter, so the obvious spelling fails two different ways, neither of which names the cause:
->
-> ```javascript
-> const h = new (flair("Memory"))(undefined, agentContext(agentId));
-> h.isCollection = true;   // TypeError: Cannot set property isCollection ... which has only a getter
-> h.post({ ... });         // without the line above: 405 "The Memory does not have a post method implemented"
-> ```
->
-> `collectionResource(Cls, context)` is a two-line wrapper over the supported call — `Cls.getResource({}, context, { isCollection: true })` — and exists so this is written once. **Reads do not need it:** `Cls.get(id, context)` and `Cls.search(query, context)` thread the context themselves.
-
-> ### ⚠️ A resource with no context is an administrator
->
-> A resource built without a context resolves to Flair's trusted `internal` verdict and runs **unfiltered** — every read unscoped, every write unowned. Silently. No error, no warning, no trace.
->
-> Measured, not inferred: a context-less `Memory.search()` returns every agent's `private` records, and so does a context-less `SemanticSearch`.
->
-> Correct for Flair's own maintenance passes. In your app it is a data leak you find months later.
->
-> **Make `agentId` a required argument, as above.** Never export a version that defaults it.
+That is the whole API. No deep import, no `server.resources`, no `.Resource`, no `collectionResource()`, no double-passing `agentId`. The facade stamps `agentId` from the handle's context onto the body internally — you pass it once, at `flair.as(id)`.
 
 **3. Read it back, scoped to that agent.**
 
 ```javascript
-export async function recall(agentId, query, limit = 5) {
-  const h = await collectionResource(flair("SemanticSearch"), agentContext(agentId));
-  return h.post({ q: query, limit });
-}
+const hits = await planner.recall("deploy schedule", { limit: 5 });
+const record = await planner.memory.get(hits[0].id);
 ```
 
-**4. Verify it worked, still in-process.**
+**4. Register an agent, no CLI.**
 
 ```javascript
-await remember("agent-alpha", "deploy runs at 0200 UTC");
-console.log(await recall("agent-alpha", "deploy schedule"));
+await flair.admin.registerAgent("planner", { publicKey: "pending" });
+```
+
+> **`flair.admin` is a root shell.** Every call site is greppable via `git grep "flair.admin"`. Use for provisioning and maintenance only, never as a request handler's default.
+
+**5. Verify it worked.**
+
+```javascript
+console.log(await planner.memory.search({ limit: 10 }));
 console.log([...server.resources.keys()].sort());   // what Flair registered
 ```
 
-> ### What we measured, so you do not have to
->
-> Run end to end on **Harper 5.1.22**, from a second component loaded into the same instance — the exact shape above. `test/integration/in-process-agents.test.ts` in the Flair repo is that run, and `test/fixtures/inproc-app` is the component it drives.
->
-> | Claim | Result |
-> |---|---|
-> | `server.resources.get("Memory")` from another component | Returns an **entry object** `{ Resource, path, exportTypes, hasSubPaths, relativeURL }` — `.Resource` is required, it is not the class itself |
-> | `.Resource` is Flair's resource, not the raw table | Confirmed: prototype chain `Memory → Memory → Resource`, and it is **not** `databases.flair.Memory` |
-> | Key format | **No leading slash.** `get("Memory")` hits; `get("/Memory")` returns `undefined` |
-> | `getMatch` | `getMatch("Memory")` hits. **`getMatch("/Memory")` misses** — do not use the slashed form |
-> | When the lookup becomes valid | Flair's resources were already registered at the app component's **module top level** (55 entries, `Memory` and `Agent` present). The only entry missing at that moment was the app's *own*, still mid-registration. Resolving lazily, as above, is still the advice — it costs nothing and does not depend on component load order |
-> | Per-agent scoping through `SemanticSearch` | Holds. Querying as `agent-beta` for a topic only `agent-alpha` has written returns **beta's own** memory, never alpha's private one — with real 768-dim embeddings attached, not a degraded path |
-> | Cross-agent by-id read | `Memory.get(<beta's private id>)` as alpha returns **404**, never 403 — a denied caller cannot enumerate ids |
-> | Context-less call | Unfiltered across all agents, via both `search` and `SemanticSearch` (see the warning above) |
+---
 
-Handlers return a `Response` for `401`/`403`/`400` rather than throwing — check for one. `Memory.post()` is in-process only; over HTTP the schema exposes `PUT`.
+## The facade
+
+### `new Flair(server)`
+
+One handle per Harper instance. Resolves resources lazily on first use — no lookup at construction time.
+
+### `flair.as(agentId)`
+
+Returns an `AgentHandle` scoped to that agent. The `agentId` is runtime-validated: missing, empty, blank, or non-string throws `InProcessContextError`.
+
+```javascript
+const planner = flair.as("planner");
+planner.agentId;  // "planner"
+```
+
+**Security:** In-process identity is asserted, not verified — co-location IS the grant. Build the `agentId` from your own server-side state, never from request data. If an agent id can reach `flair.as()` from user input — a body field, a query param, a header you did not verify yourself — that is privilege escalation with **no error, no 403 and no trace**.
+
+### `AgentHandle`
+
+| Method | Description |
+|---|---|
+| `handle.memory.write(content, opts?)` | Write a memory as this agent. `agentId` is stamped from the handle — the caller never passes it. |
+| `handle.memory.get(id)` | Read a memory by id, scoped to this agent. |
+| `handle.memory.search(opts?)` | Search memories scoped to this agent. |
+| `handle.recall(query, opts?)` | Semantic search scoped to this agent. |
+
+### `flair.admin`
+
+Admin operations — unfiltered reads, cross-agent writes. Every call site is greppable via `git grep "flair.admin"`.
+
+| Method | Description |
+|---|---|
+| `flair.admin.registerAgent(id, opts?)` | Register an agent through the Agent resource (full Principal shape). |
+| `flair.admin.memory.get(id)` | Read any memory by id, unfiltered. |
+| `flair.admin.memory.write(asAgentId, content, opts?)` | Write a memory attributed to another agent. |
+
+### `flair.internal`
+
+Trusted, unattributed, unfiltered operations — Flair's `internal` verdict. Every call site is greppable via `git grep "flair.internal"`.
+
+| Method | Description |
+|---|---|
+| `flair.internal.agentTable.put(record)` | Write directly to the Agent resource (bypasses admin gate). |
 
 ---
 
@@ -107,7 +107,8 @@ Handlers return a `Response` for `401`/`403`/`400` rather than throwing — chec
 
 ```javascript
 for (const id of ["planner", "researcher", "reviewer"]) {
-  await remember(id, `${id} came online`);
+  const agent = flair.as(id);
+  await agent.memory.write(`${id} came online`);
 }
 ```
 
@@ -115,25 +116,23 @@ for (const id of ["planner", "researcher", "reviewer"]) {
 
 ### Registering agents, no CLI
 
-Go through the `Agent` **resource**, with no context — provisioning is infrastructure work your app has already authorised, and `Agent.post()` fills in the whole Principal shape for you:
+Go through `flair.admin.registerAgent()` — it goes through the `Agent` **resource**, which fills in the whole Principal shape for you:
 
 ```javascript
-export async function registerAgent(id, { publicKey = "pending", admin = false } = {}) {
-  const h = await collectionResource(flair("Agent"), internalContext());   // provisioning is infrastructure, not an agent's write
-  return h.post({
-    id, name: id, displayName: id,
-    publicKey,                            // a placeholder is fine — see below
-    runtime: "headless",
-    ...(admin ? { role: "admin", admin: true } : {}),   // role is what actually grants admin
-  });
-}
+await flair.admin.registerAgent("researcher", {
+  publicKey: "pending",
+  displayName: "Research Agent",
+  admin: false,
+});
 ```
 
 Verified against a real instance: that lands `kind: "agent"`, `status: "active"`, `displayName`, `admin: false`, `defaultTrustTier: "unverified"`, `type: "agent"`, `createdAt`/`updatedAt` and the federation `originatorInstanceId` stamp — without you naming any of them.
 
 > **Prefer this to `databases.flair.Agent.put()`.** The raw table applies **no** defaults, so a hand-written literal has to reproduce every field above and then stay in step with Flair as the Principal model grows. Records written that way are missing `kind`/`status`/`defaultTrustTier` and read as under-specified Principals in the admin surfaces.
 
-> **`isAdmin()` reads `role === "admin"`, not the `admin` boolean.** They are separate fields and only `role` grants admin rights; set both to keep the record self-consistent. Admin lookups are cached for 60 seconds, so a newly-created admin is not effective immediately.
+> **Admin is one meaning with one answer.** `role === "admin"` is the authority; the `admin` boolean is a mirror of it that the server maintains. Write **either** through the `Agent` resource and both are set — you no longer have to know which one is real, and a record cannot be stored saying one thing in one field and the opposite in the other. Nothing reads the mirror to make an authorization decision, and a promotion applied through the resource takes effect on the next request rather than after the 60-second admin-lookup cache expires.
+>
+> A record written straight to the table (`databases.flair.Agent.put()`, an ops-API insert, a federation merge) skips that reconciliation and can still carry a mismatch. `flair principal show` and the admin dashboard flag such a record rather than silently picking a side; re-issuing the grant repairs it.
 
 `publicKey` is non-nullable in the schema, but it does not have to be a real key. An agent that only ever acts in-process never authenticates, and Flair's own paths write placeholders — `"pending"` when seeding, `mcp-oauth:<sub>` for token-authenticated agents. Give an agent a real key only if it must also authenticate **over HTTP**, which your app can do without any CLI:
 
@@ -142,7 +141,7 @@ import { generateKeyPairSync } from "node:crypto";
 
 const { publicKey, privateKey } = generateKeyPairSync("ed25519");
 const raw = publicKey.export({ format: "der", type: "spki" }).subarray(-32);
-await registerAgent("remote-worker", { publicKey: raw.toString("hex") });
+await flair.admin.registerAgent("remote-worker", { publicKey: raw.toString("hex") });
 // keep `privateKey` in your own secret store — Flair never sees it
 ```
 
@@ -294,6 +293,106 @@ A `SyncLog` row reads `direction: "pull"` — the receiver's label for a push it
 
 ---
 
+## Appendix: the primitives layer
+
+The facade wraps a lower-level API that is still available for callers who need direct access. Import it from `@tpsdev-ai/flair/server`:
+
+```javascript
+import { agentContext, adminContext, internalContext, collectionResource } from "@tpsdev-ai/flair/server";
+```
+
+This is the same seam Flair's own MCP handler and internal tooling use. You should not need it for ordinary agent operations — the facade covers those. Use the primitives when you are building your own abstraction on top of Flair's resources.
+
+### Resolving a resource
+
+```javascript
+// The RESOURCE — carries auth, scoping, visibility, embedding.
+// NOT databases.flair.Memory: that is the raw table, and enforces none of it.
+// Keys carry NO leading slash: get("Memory"), never get("/Memory").
+const flair = (path) => server.resources.get(path).Resource;
+```
+
+### Writing a memory (primitives)
+
+```javascript
+export async function remember(agentId, content, opts = {}) {
+  // A create needs a COLLECTION-bound instance. `new Cls(...)` does not give
+  // you one, and cannot be made to — see the note below.
+  const h = await collectionResource(flair("Memory"), agentContext(agentId));
+  return h.post({
+    agentId,                                // required — an absent one is never filled in
+    content,
+    durability: opts.durability ?? "standard",
+  });
+}
+```
+
+> ### Why `collectionResource`, and not `new Memory()`
+>
+> A resource's `post()` only works on an instance Harper has marked as a **collection**, and that mark is a *private* field only Harper's own `getResource()` can set. The public `isCollection` is a getter with no setter, so the obvious spelling fails two different ways, neither of which names the cause:
+>
+> ```javascript
+> const h = new (flair("Memory"))(undefined, agentContext(agentId));
+> h.isCollection = true;   // TypeError: Cannot set property isCollection ... which has only a getter
+> h.post({ ... });         // without the line above: 405 "The Memory does not have a post method implemented"
+> ```
+>
+> `collectionResource(Cls, context)` is a two-line wrapper over the supported call — `Cls.getResource({}, context, { isCollection: true })` — and exists so this is written once. **Reads do not need it:** `Cls.get(id, context)` and `Cls.search(query, context)` thread the context themselves.
+>
+> They do still need the **context**. Only the collection binding is unnecessary for a read, never the identity — `Cls.search(query)` with the second argument left off resolves to the trusted `internal` verdict when it runs outside a request scope (a boot hook, a timer, a queue worker, a detached promise) and returns every agent's private records. On that path the resource's `allow*` gate is not consulted at all. Pass the context to every call, read and write.
+
+> ### ⚠️ A resource with no context is an administrator
+>
+> A resource built without a context resolves to Flair's trusted `internal` verdict and runs **unfiltered** — every read unscoped, every write unowned. Silently. No error, no warning, no trace.
+>
+> Measured, not inferred: a context-less `Memory.search()` returns every agent's `private` records, and so does a context-less `SemanticSearch`.
+>
+> Correct for Flair's own maintenance passes. In your app it is a data leak you find months later.
+>
+> **Make `agentId` a required argument, as above.** Never export a version that defaults it.
+
+### Reading back (primitives)
+
+```javascript
+export async function recall(agentId, query, limit = 5) {
+  const h = await collectionResource(flair("SemanticSearch"), agentContext(agentId));
+  return h.post({ q: query, limit });
+}
+```
+
+### Registering agents (primitives)
+
+```javascript
+export async function registerAgent(id, { publicKey = "pending", admin = false } = {}) {
+  const h = await collectionResource(flair("Agent"), internalContext());   // provisioning is infrastructure, not an agent's write
+  return h.post({
+    id, name: id, displayName: id,
+    publicKey,                            // a placeholder is fine — see below
+    runtime: "headless",
+    ...(admin ? { admin: true } : {}),    // sets role:"admin" too — see below
+  });
+}
+```
+
+### What we measured, so you do not have to
+
+Run end to end on **Harper 5.1.22**, from a second component loaded into the same instance — the exact shape above. `test/integration/in-process-agents.test.ts` in the Flair repo is that run, and `test/fixtures/inproc-app` is the component it drives.
+
+| Claim | Result |
+|---|---|
+| `server.resources.get("Memory")` from another component | Returns an **entry object** `{ Resource, path, exportTypes, hasSubPaths, relativeURL }` — `.Resource` is required, it is not the class itself |
+| `.Resource` is Flair's resource, not the raw table | Confirmed: prototype chain `Memory → Memory → Resource`, and it is **not** `databases.flair.Memory` |
+| Key format | **No leading slash.** `get("Memory")` hits; `get("/Memory")` returns `undefined` |
+| `getMatch` | `getMatch("Memory")` hits. **`getMatch("/Memory")` misses** — do not use the slashed form |
+| When the lookup becomes valid | Flair's resources were already registered at the app component's **module top level** (55 entries, `Memory` and `Agent` present). The only entry missing at that moment was the app's *own*, still mid-registration. Resolving lazily, as above, is still the advice — it costs nothing and does not depend on component load order |
+| Per-agent scoping through `SemanticSearch` | Holds. Querying as `agent-beta` for a topic only `agent-alpha` has written returns **beta's own** memory, never alpha's private one — with real 768-dim embeddings attached, not a degraded path |
+| Cross-agent by-id read | `Memory.get(<beta's private id>)` as alpha returns **404**, never 403 — a denied caller cannot enumerate ids |
+| Context-less call | Unfiltered across all agents, via both `search` and `SemanticSearch` (see the warning above) |
+
+Handlers return a `Response` for `401`/`403`/`400` rather than throwing — check for one. `Memory.post()` is in-process only; over HTTP the schema exposes `PUT`.
+
+---
+
 ## See also
 
 [Integrations](integrations.md) · [Deployment](deployment.md) · [Federation](federation.md) · [Auth](auth.md) · [Architecture](../DESIGN.md)