@tpsdev-ai/flair 0.51.2 → 0.52.0

package/dist/resources/MemoryDedupStats.js

@@ -54,6 +54,7 @@
  */
 import { Resource, databases } from "harper";
 import { mkdirSync, writeFileSync } from "node:fs";
+import { setImmediate as yieldToRequests } from "node:timers/promises";
 import { dirname } from "node:path";
 import { allowAdmin } from "./agent-auth.js";
 import { retrieveCandidates } from "./semantic-retrieval-core.js";
@@ -82,11 +83,19 @@ async function computeAndPersist(ctx, opts) {
     // exactly what this stat is for). Bounded to the most-recently-created
     // maxMemories when the instance exceeds the safety cap (see
     // dedup-cluster.ts's doc on why this is a defensive bound, not sampling).
+    let yieldAt = performance.now() + 10;
     const all = [];
     for await (const record of databases.flair.Memory.search({
-        conditions: NOT_ARCHIVED,
-        select: ["id", "embedding", "createdAt"],
+        // Harper 5.2.8 starts a standalone not_equal index scan at true,
+        // skipping false/missing archive keys. Filter the primary scan instead.
+        select: ["id", "embedding", "createdAt", "archived"],
     })) {
+        if (performance.now() >= yieldAt) {
+            await yieldToRequests();
+            yieldAt = performance.now() + 10;
+        }
+        if (record.archived === true)
+            continue;
         if (!record?.id || !Array.isArray(record.embedding) || record.embedding.length === 0)
             continue;
         all.push({ id: record.id, embedding: record.embedding, createdAt: record.createdAt });
@@ -110,6 +119,12 @@ async function computeAndPersist(ctx, opts) {
     // at the documented annK, rather than silently examining annK-1.
     const edges = [];
     for (const memory of sweepSet) {
+        // Awaiting cached table reads can keep draining microtasks indefinitely.
+        // Give the HTTP event loop a turn between bounded chunks of ANN work.
+        if (performance.now() >= yieldAt) {
+            await yieldToRequests();
+            yieldAt = performance.now() + 10;
+        }
         let neighbors;
         try {
             neighbors = await retrieveCandidates({

package/dist/resources/MemoryFeed.js

@@ -2,8 +2,10 @@ import { Resource, databases } from "harper";
 import { allowVerified, resolveAgentAuth } from "./agent-auth.js";
 import { computeContentHash, findExistingMemoryByContentHash } from "./memory-feed-lib.js";
 import { FORBIDDEN, UNAUTH, stampAttribution } from "./record-type-kit.js";
+import { guardAuthorityFields, stripAuthorityFields } from "./authority-field-guard.js";
 import { assertValidVisibility, assertVisibilityAllowedForDurability, PRIVATE_VISIBILITY } from "./memory-visibility.js";
 import { assertValidDurability } from "./memory-durability.js";
+import { enforceSkillDurability, skillScanGate } from "./skill-write.js";
 import { noteMemoryUpsert } from "./bm25-index-service.js";
 export class FeedMemories extends Resource {
     // Self-authorize via the Ed25519 agent verify (the auth reshape removes the
@@ -56,6 +58,20 @@ export class FeedMemories extends Resource {
                 headers: { "Content-Type": "application/json" },
             });
         }
+        // ── flair#1542: skill-tagged writes are gated (SkillScan + forced durability) ──
+        // This endpoint writes via the RAW table object below — NOT Memory.post()/
+        // put() — so a caller could spread tags:["skill"] + trigger into the raw
+        // put and land an unscanned, 30-day-reapable (durability=standard) skill.
+        // Run the SAME gate Memory.post() runs, BEFORE the durability default is
+        // computed so a forced "persistent" flows into the tier rule below.
+        {
+            const skillScanDenial = skillScanGate(content);
+            if (skillScanDenial)
+                return skillScanDenial;
+            const skillDurabilityDenial = enforceSkillDurability(content);
+            if (skillDurabilityDenial)
+                return skillDurabilityDenial;
+        }
         // ── Write-side durability/visibility validation (#1009/#1238/#1257) ─────
         // This endpoint writes via the RAW table object below — NOT the exported
         // Memory resource — so it inherits NONE of Memory.post()/put()'s write
@@ -96,6 +112,19 @@ export class FeedMemories extends Resource {
                 });
             }
         }
+        // ── Authority-field guard (#1524 leftover) ────────────────────────────
+        // Same raw-table bypass as the durability/visibility block above:
+        // guardAuthorityFields sits on Memory.put/patch/post, not the raw
+        // handle. A verified agent could POST {promotionStatus:"approved"}
+        // here and land a forged verdict. Refuse a body that sets or changes
+        // a stamp, then unconditionally strip before the raw put so even
+        // stamps the guard would restore onto an omitted-field update cannot
+        // ride a feed write (feed ingest is not a promotion-stamp path).
+        {
+            const authorityDenial = await guardAuthorityFields(() => content?.id ? databases.flair.Memory.get(content.id) : undefined, content, "Memory");
+            if (authorityDenial)
+                return authorityDenial;
+        }
         const now = new Date().toISOString();
         const contentHash = computeContentHash(agentId, body);
         const existing = await findExistingMemoryByContentHash(databases.flair.Memory.search(), agentId, contentHash);
@@ -125,6 +154,7 @@ export class FeedMemories extends Resource {
         if (record.durability === "ephemeral" && (record.visibility === undefined || record.visibility === null)) {
             record.visibility = PRIVATE_VISIBILITY;
         }
+        stripAuthorityFields(record, "Memory");
         await databases.flair.Memory.put(record);
         // flair#1357 — raw-table write: hook it explicitly (see bm25-index-service).
         noteMemoryUpsert(record);

package/dist/resources/MemoryGrant.js

@@ -1,5 +1,6 @@
 import { databases } from "harper";
 import { resolveAgentAuth, allowVerified } from "./agent-auth.js";
+import { guardOwnerFieldImmutable } from "./owner-field-guard.js";
 const FORBIDDEN = (msg) => new Response(JSON.stringify({ error: msg }), { status: 403, headers: { "Content-Type": "application/json" } });
 const UNAUTH = () => new Response(JSON.stringify({ error: "authentication required" }), { status: 401, headers: { "Content-Type": "application/json" } });
 const NOT_FOUND = () => new Response(JSON.stringify({ error: "not found" }), { status: 404, headers: { "Content-Type": "application/json" } });
@@ -93,7 +94,20 @@ export class MemoryGrant extends databases.flair.MemoryGrant {
         content.createdAt ||= new Date().toISOString();
         return super.post(content, context);
     }
+    // PATCH routes past put(), so ownerId immutability is enforced on both verbs
+    // via the one shared delegate. Only the owner may modify a grant, and not even
+    // the owner may re-point ownerId at another principal (a grantee never could —
+    // the middleware ownership guard refuses a non-owner mutation first).
+    async patch(content, query) {
+        const denial = await guardOwnerFieldImmutable(this, () => super.get(), content, "ownerId");
+        if (denial)
+            return denial;
+        return super.patch(content, query);
+    }
     async put(content, context) {
+        const denial = await guardOwnerFieldImmutable(this, () => super.get(), content, "ownerId");
+        if (denial)
+            return denial;
         const denied = await this._enforceOwnerWrite(content);
         if (denied)
             return denied;

package/dist/resources/MemoryReflect.js

@@ -11,7 +11,8 @@
  *   agentId      string   — which agent to reflect on
  *   scope        string   — "recent" | "tagged" | "all" (default: "recent")
  *   since        string?  — ISO timestamp lower bound (default: 24h ago)
- *   maxMemories  number?  — cap (default: 50)
+ *   maxMemories  number?  — cap (default: 50, env FLAIR_REM_MAX_MEMORIES,
+ *                            hard ceiling 200). Oldest-unreflected first.
  *   focus        string?  — "lessons_learned" | "patterns" | "decisions" | "errors" | "continuity"
  *                            (default: "lessons_learned"; a continuity-tag run — scope="tagged" with an
  *                            adk:continuity:* tag — always uses "continuity", flair#1257 slice 3)
@@ -42,9 +43,19 @@
  */
 import { Resource, databases, models, logger } from "harper";
 import { randomBytes } from "node:crypto";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { homedir } from "node:os";
+import { setImmediate as yieldToRequests } from "node:timers/promises";
 import { isAdmin, allowVerified } from "./agent-auth.js";
 import { patchRecordSilent } from "./table-helpers.js";
-import { buildReflectionPrompt, buildExecutePrompt, resolveReflectActor, generateCandidates, dedupeCandidates, memoryMatchesReflectScope, buildStagedCandidateRow, isContinuityScopeTag, filterStaleSessionIntentCandidates, resolveCandidateVisibilityRuling, DEFAULT_STALE_INTENT_HORIZON_MS, } from "./memory-reflect-lib.js";
+import { buildReflectionPrompt, buildExecutePrompt, resolveReflectActor, generateCandidates, dedupeCandidates, memoryMatchesReflectScope, buildStagedCandidateRow, isContinuityScopeTag, filterStaleSessionIntentCandidates, resolveCandidateVisibilityRuling, considerForOldestUnreflectedCap, isRemAbortRequested, resolveMaxMemoriesPerRun, shouldStampLastReflected, DEFAULT_STALE_INTENT_HORIZON_MS, REM_GATHER_YIELD_BUDGET_MS, } from "./memory-reflect-lib.js";
+/** Same path `flair rem pause` writes. Duplicated across the src/ boundary. */
+const REM_PAUSE_FLAG = resolve(homedir(), ".flair", "rem.paused");
+const GATHER_SELECT = [
+    "id", "agentId", "archived", "durability", "expiresAt", "tags",
+    "createdAt", "lastReflected", "content",
+];
 export class ReflectMemories extends Resource {
     // Self-authorize via the Ed25519 agent verify (auth reshape removes the gate's
     // admin elevation). Any verified agent may reflect; the isAdmin checks in post()
@@ -53,7 +64,7 @@ export class ReflectMemories extends Resource {
         return allowVerified(this.getContext?.());
     }
     async post(data) {
-        const { agentId: bodyAgentId, scope = "recent", since, maxMemories = 50, focus = "lessons_learned", tag, execute = false, } = data || {};
+        const { agentId: bodyAgentId, scope = "recent", since, maxMemories, focus = "lessons_learned", tag, execute = false, } = data || {};
         // Authenticated identity comes from getContext().request, not this.request
         // (see SemanticSearch / MemoryBootstrap for the same bug class). The prior
         // check was silently bypassed — bob could reflect on alice's memories and
@@ -72,8 +83,26 @@ export class ReflectMemories extends Resource {
         const agentId = actorResolution.agentId;
         const sinceDate = since ? new Date(since) : new Date(Date.now() - 24 * 3600_000);
         const gatherNow = new Date();
+        const maxN = resolveMaxMemoriesPerRun(typeof maxMemories === "number" ? maxMemories : undefined);
+        // #1515: do not take the first N search hits. Scan eligible rows (yielding
+        // so /Health keeps serving), keep oldest-unreflected first up to maxN
+        // (already-reflected fill leftover slots), and abort if the operator
+        // paused mid-run. Embeddings are excluded from the select — loading 3k
+        // vectors just to strip them pegs the main thread.
         const memories = [];
-        for await (const record of databases.flair.Memory.search()) {
+        let unreflectedSeen = 0;
+        let yieldAt = performance.now() + REM_GATHER_YIELD_BUDGET_MS;
+        for await (const record of databases.flair.Memory.search({ select: GATHER_SELECT })) {
+            if (performance.now() >= yieldAt) {
+                if (isRemAbortRequested(process.env, existsSync, REM_PAUSE_FLAG)) {
+                    return new Response(JSON.stringify({
+                        error: "rem_aborted",
+                        detail: "REM distillation aborted (pause sentinel or FLAIR_REM_PAUSE=1). Resume with: flair rem resume",
+                    }), { status: 503 });
+                }
+                await yieldToRequests();
+                yieldAt = performance.now() + REM_GATHER_YIELD_BUDGET_MS;
+            }
             if (record.agentId !== agentId)
                 continue;
             if (record.archived)
@@ -94,26 +123,29 @@ export class ReflectMemories extends Resource {
             // never cite another user's memory.
             if (!memoryMatchesReflectScope(record, { scope, tag, sinceDate }))
                 continue;
-            const { embedding, ...rest } = record;
-            memories.push(rest);
-            if (memories.length >= maxMemories)
-                break;
+            if (record.lastReflected == null || record.lastReflected === "")
+                unreflectedSeen++;
+            const { embedding: _embedding, ...rest } = record;
+            considerForOldestUnreflectedCap(memories, rest, maxN);
+        }
+        if (isRemAbortRequested(process.env, existsSync, REM_PAUSE_FLAG)) {
+            return new Response(JSON.stringify({
+                error: "rem_aborted",
+                detail: "REM distillation aborted (pause sentinel or FLAIR_REM_PAUSE=1). Resume with: flair rem resume",
+            }), { status: 503 });
         }
-        memories.sort((a, b) => (a.createdAt ?? "").localeCompare(b.createdAt ?? ""));
         // Collect tags present in source memories
         const tagSet = new Set();
         for (const m of memories) {
             for (const t of m.tags ?? [])
                 tagSet.add(t);
         }
-        // Update lastReflected on source memories (read-modify-write to preserve
-        // embeddings). Unconditional for both modes — calling /ReflectMemories at
-        // all means these memories were considered, regardless of what happens next.
-        const nowISO = new Date().toISOString();
-        for (const m of memories) {
-            patchRecordSilent(databases.flair.Memory, m.id, { lastReflected: nowISO });
-        }
-        const promptInputs = memories.map((m) => ({ id: m.id, createdAt: m.createdAt, content: m.content }));
+        const promptInputs = memories.map((m) => ({
+            id: m.id,
+            createdAt: m.createdAt,
+            content: typeof m.content === "string" ? m.content : "",
+        }));
+        const gatherMeta = { gathered: memories.length, unreflected: unreflectedSeen, maxMemories: maxN };
         if (!execute) {
             const prompt = buildReflectionPrompt({ agentId, focus, scope, sinceISO: sinceDate.toISOString(), memories: promptInputs });
             return {
@@ -121,6 +153,17 @@ export class ReflectMemories extends Resource {
                 prompt,
                 suggestedTags: [...tagSet].slice(0, 20),
                 count: memories.length,
+                ...gatherMeta,
+            };
+        }
+        // #1515: empty gather → no generate() call. A fully-reflected (or empty)
+        // set must not spend a model turn or hold the main thread.
+        if (promptInputs.length === 0) {
+            return {
+                candidates: [],
+                count: 0,
+                model: process.env.FLAIR_REM_MODEL || "default",
+                ...gatherMeta,
             };
         }
         // ── execute mode (spec §3A) ─────────────────────────────────────────────
@@ -184,7 +227,12 @@ export class ReflectMemories extends Resource {
         }
         // Dedup against this agent's existing pending candidates (spec §3A item 4).
         const existingPendingClaims = [];
+        yieldAt = performance.now() + REM_GATHER_YIELD_BUDGET_MS;
         for await (const c of databases.flair.MemoryCandidate.search({})) {
+            if (performance.now() >= yieldAt) {
+                await yieldToRequests();
+                yieldAt = performance.now() + REM_GATHER_YIELD_BUDGET_MS;
+            }
             if (c.agentId !== agentId)
                 continue;
             if (c.status !== "pending")
@@ -225,6 +273,15 @@ export class ReflectMemories extends Resource {
             await databases.flair.MemoryCandidate.put(row);
             staged.push(row);
         }
+        // Stamp after a successful generate on execute runs only. Prompt-only
+        // and 502/503/abort leave lastReflected unset so the next night retries
+        // the same sources instead of permanently skipping them (#1515 Bugbot).
+        if (shouldStampLastReflected({ execute, generateSucceeded: true })) {
+            const now = new Date().toISOString();
+            for (const memory of memories) {
+                patchRecordSilent(databases.flair.Memory, memory.id, { lastReflected: now });
+            }
+        }
         // Response omits rationalePrompt (spec §3A item 5: "no prompt field") —
         // it's identical across every row in this batch and already persisted
         // for audit on the MemoryCandidate row itself; echoing it back per
@@ -235,6 +292,7 @@ export class ReflectMemories extends Resource {
             candidates: responseCandidates,
             count: responseCandidates.length,
             model: resolvedModel,
+            ...gatherMeta,
             // flair#1257 slice 3: continuity-run observability — how many candidates
             // the stale-intent post-filter dropped (0 for non-continuity runs).
             ...(isContinuityRun ? { droppedStaleIntent: staleIntentResult.droppedStaleIntent.length } : {}),

package/dist/resources/Message.js

@@ -0,0 +1,190 @@
+/**
+ * Message.ts — Flair Relay S1 resource surface (point-to-point, single host).
+ *
+ * A signed, principal-addressed, durably-queued message with an explicit ack
+ * and a VISIBLE dead-letter — a DIFFERENT primitive from memory and OrgEvent
+ * (whose expiresAt is a silent dead-letter). See relay-ops.ts for the
+ * orchestration and relay-lib.ts for the pure primitives; this file is the thin
+ * Harper adapter that resolves auth and injects the real table accessors.
+ *
+ * Auth (self-enforced, mirroring OrgEvent/MemoryGrant now that the global gate
+ * is non-rejecting): reads gated to verified agents; every write path resolves
+ * the three-way verdict and fails closed on anonymous. Direct REST mutation of
+ * the table (PUT/DELETE) is admin/internal only — agents SEND via post() and
+ * ACK via MessageAck, never by writing state fields directly. relay-ops' own
+ * writes use the static table accessor and bypass these instance gates (the
+ * same raw-put seam Federation.ts relies on).
+ */
+import { Resource, databases } from "harper";
+import { resolveAgentAuth, allowVerified } from "./agent-auth.js";
+import { makeAuthGate, makeScopedSearch, FORBIDDEN, UNAUTH, NOT_FOUND } from "./record-type-kit.js";
+import { localInstanceId } from "./instance-identity.js";
+import { relaySend, relayInbox, relayConsume, relayDeadLetters, relaySweepDeadlines, } from "./relay-ops.js";
+function relayDeps() {
+    return {
+        messages: databases.flair.Message,
+        agents: databases.flair.Agent,
+        resolveOrg: localInstanceId,
+    };
+}
+function ctxOf(self) {
+    return self.getContext?.();
+}
+function pathId(pathInfo) {
+    const id = (typeof pathInfo === "object" && pathInfo !== null ? pathInfo.id : undefined) ??
+        (typeof pathInfo === "string" ? pathInfo : undefined);
+    return id ? String(id) : undefined;
+}
+// ─── Message table resource — post() sends a message ────────────────────────
+const messageAuthGate = makeAuthGate();
+// P0-1 collection read-scope: a non-admin agent's collection read is limited to
+// the messages it is a PARTY to — `from === self` OR `to === self`. Composed as
+// the OUTERMOST `and` block (makeScopedSearch) so a caller-supplied
+// `operator: "or"` cannot boolean-inject past the scope — the exact
+// injection-safe shape Memory.search() uses. Without this, super.get() on a
+// collection returns EVERY row in the table to any verified agent (the
+// cross-principal read leak Kern P0-1 flagged). Admin/internal are unfiltered.
+const messageScopedSearch = makeScopedSearch(async (agentId) => ({
+    condition: {
+        operator: "or",
+        conditions: [
+            { attribute: "from", comparator: "equals", value: agentId },
+            { attribute: "to", comparator: "equals", value: agentId },
+        ],
+    },
+    isAllowed: (r) => !!r && (r.from === agentId || r.to === agentId),
+}));
+export class Message extends databases.flair.Message {
+    allowRead() {
+        return messageAuthGate.call(this);
+    }
+    /** Send (POST) self-authorizes for any verified agent: Harper authorizes
+     *  BEFORE post() runs, so without this a de-elevated flair_agent 403s on the
+     *  create before relaySend is ever reached (Kern P0-2). Per-send ownership
+     *  (no-forge `from`, signature) is enforced inside relaySend. */
+    async allowCreate() {
+        return allowVerified(ctxOf(this));
+    }
+    async post(content) {
+        const auth = await resolveAgentAuth(ctxOf(this));
+        return relaySend(relayDeps(), auth, content ?? {});
+    }
+    /** Scope a non-admin agent's collection read to the messages it is a party
+     *  to (from/to === self); admin/internal unfiltered; anonymous denied. Reached
+     *  via get()'s collection branch, the same way Memory.get delegates collection
+     *  reads to Memory.search. */
+    async search(query) {
+        const auth = await resolveAgentAuth(ctxOf(this));
+        if (auth.kind === "anonymous")
+            return UNAUTH();
+        if (auth.kind === "internal" || (auth.kind === "agent" && auth.isAdmin))
+            return super.search(query);
+        return messageScopedSearch(auth.agentId, query, (q) => super.search(q));
+    }
+    /** By-id read is scoped to the two parties (from/to); anyone else gets 404,
+     *  so ids can't be enumerated. Collection reads route to the party-scoped
+     *  search() above (P0-1) — NOT super.get, which returns the whole table. */
+    async get(target) {
+        if (!target || (typeof target === "object" && target.isCollection)) {
+            return this.search(target);
+        }
+        const auth = await resolveAgentAuth(ctxOf(this));
+        if (auth.kind === "anonymous")
+            return NOT_FOUND();
+        if (auth.kind === "internal" || (auth.kind === "agent" && auth.isAdmin))
+            return super.get(target);
+        const record = await super.get(target);
+        if (!record)
+            return NOT_FOUND();
+        if (record.from !== auth.agentId && record.to !== auth.agentId)
+            return NOT_FOUND();
+        return record;
+    }
+    /** Direct table writes are admin/internal only — see the file header. */
+    async put(content, context) {
+        const auth = await resolveAgentAuth(ctxOf(this));
+        if (auth.kind === "anonymous")
+            return UNAUTH();
+        if (auth.kind === "agent" && !auth.isAdmin) {
+            return FORBIDDEN("forbidden: send via POST and ack via MessageAck; direct writes are not permitted");
+        }
+        return super.put(content, context);
+    }
+    /** PATCH is a distinct Harper verb (Resource.patch → type:update → TableResource.patch
+     *  runs update()+save(), NEVER Message.put()), so without this override a de-elevated
+     *  agent with an `update` grant could mutate ANY message — set state, rewrite
+     *  body/from/to on a row it is not a party to — bypassing put()'s guard and
+     *  relayConsume's recipient-only check (Kern P0). The `update:false` grant now closes
+     *  this at the platform gate; this mirrors put()'s guard as defense-in-depth for the
+     *  verb surface (admin/internal only). Agents ack via MessageAck, never a direct PATCH. */
+    async patch(content, context) {
+        const auth = await resolveAgentAuth(ctxOf(this));
+        if (auth.kind === "anonymous")
+            return UNAUTH();
+        if (auth.kind === "agent" && !auth.isAdmin) {
+            return FORBIDDEN("forbidden: ack via MessageAck; direct writes are not permitted");
+        }
+        return super.patch(content, context);
+    }
+    async delete(id, context) {
+        const auth = await resolveAgentAuth(ctxOf(this));
+        if (auth.kind === "anonymous")
+            return UNAUTH();
+        if (auth.kind === "agent" && !auth.isAdmin) {
+            return FORBIDDEN("forbidden: direct deletes are not permitted");
+        }
+        return super.delete(id, context);
+    }
+}
+// ─── /MessageInbox/{to}? — the caller's unconsumed inbox, sorted by seq ──────
+export class MessageInbox extends Resource {
+    async allowRead() {
+        const auth = await resolveAgentAuth(ctxOf(this));
+        return auth.kind !== "anonymous";
+    }
+    async get(pathInfo) {
+        const auth = await resolveAgentAuth(ctxOf(this));
+        return relayInbox(relayDeps(), auth, pathId(pathInfo));
+    }
+}
+// ─── /MessageAck  (POST {id}) — recipient acks a message ────────────────────
+export class MessageAck extends Resource {
+    async allowRead() {
+        const auth = await resolveAgentAuth(ctxOf(this));
+        return auth.kind !== "anonymous";
+    }
+    /** Ack (POST) self-authorizes for any verified agent: a bare Resource
+     *  subclass defaults allowCreate to super_user, which 403s every de-elevated
+     *  flair_agent — the ack, the core primitive, would be admin-only as shipped
+     *  (Kern P0-2). Recipient-only ownership is enforced inside relayConsume. */
+    async allowCreate() {
+        return allowVerified(ctxOf(this));
+    }
+    async post(content) {
+        const auth = await resolveAgentAuth(ctxOf(this));
+        const id = content && typeof content === "object" ? String(content.id ?? "") : "";
+        return relayConsume(relayDeps(), auth, id);
+    }
+}
+// ─── /MessageDeadLetter/{from}? — the sender's visible failures ──────────────
+export class MessageDeadLetter extends Resource {
+    async allowRead() {
+        const auth = await resolveAgentAuth(ctxOf(this));
+        return auth.kind !== "anonymous";
+    }
+    async get(pathInfo) {
+        const auth = await resolveAgentAuth(ctxOf(this));
+        return relayDeadLetters(relayDeps(), auth, pathId(pathInfo));
+    }
+}
+// ─── /MessageSweep  (POST) — admin/internal deadline sweep ───────────────────
+export class MessageSweep extends Resource {
+    async allowRead() {
+        const auth = await resolveAgentAuth(ctxOf(this));
+        return auth.kind === "internal" || (auth.kind === "agent" && auth.isAdmin);
+    }
+    async post() {
+        const auth = await resolveAgentAuth(ctxOf(this));
+        return relaySweepDeadlines(relayDeps(), auth);
+    }
+}

package/dist/resources/OrgEvent.js

@@ -12,6 +12,7 @@
  */
 import { databases } from "harper";
 import { resolveAgentAuth } from "./agent-auth.js";
+import { guardOwnerFieldImmutable } from "./owner-field-guard.js";
 import { invalidEntitiesResponse } from "./entity-vocab.js";
 import { makeAuthGate, resolveAuthGate, stampAttribution, FORBIDDEN, UNAUTH, } from "./record-type-kit.js";
 import { RECORD_TYPES } from "./record-types.js";
@@ -55,7 +56,18 @@ export class OrgEvent extends databases.flair.OrgEvent {
         // Harper 5: table resources use put() for create/upsert (post() removed).
         return databases.flair.OrgEvent.put(content);
     }
+    // PATCH routes past put(), so authorId immutability is enforced on both verbs
+    // via the one shared delegate.
+    async patch(content, query) {
+        const denial = await guardOwnerFieldImmutable(this, () => super.get(), content, "authorId");
+        if (denial)
+            return denial;
+        return super.patch(content, query);
+    }
     async put(content) {
+        const __ownerDenial = await guardOwnerFieldImmutable(this, () => super.get(), content, "authorId");
+        if (__ownerDenial)
+            return __ownerDenial;
         const auth = await this._auth();
         if (auth.kind === "anonymous")
             return UNAUTH();

package/dist/resources/PromoteMemoryCandidate.js

@@ -0,0 +1,76 @@
+import { Resource, databases } from "harper";
+import { randomUUID } from "node:crypto";
+import { resolveAgentAuth } from "./agent-auth.js";
+import { Memory } from "./Memory.js";
+import { MemoryCandidate } from "./MemoryCandidate.js";
+import { stampMemoryPromotionIsolated } from "./promotion-stamp.js";
+import { derivePromotedTags, derivePromotedVisibility, validateHumanReviewerId } from "../src/rem/promote-policy.js";
+const error = (status, message) => new Response(JSON.stringify({ error: message }), {
+    status, headers: { "content-type": "application/json" },
+});
+/** Human/agent review of a pending candidate. The request names the decision;
+ * content, owner, lineage and the resulting verdict come from stored state. */
+export class PromoteMemoryCandidate extends Resource {
+    async allowCreate() {
+        return (await resolveAgentAuth(this.getContext?.())).kind !== "anonymous";
+    }
+    async post(data) {
+        const ctx = this.getContext?.();
+        const auth = await resolveAgentAuth(ctx);
+        if (auth.kind === "anonymous")
+            return error(401, "authentication required");
+        if (typeof data?.candidateId !== "string" || !data.candidateId)
+            return error(400, "candidateId required");
+        if (typeof data.rationale !== "string" || !data.rationale.trim())
+            return error(400, "rationale required");
+        const candidate = await MemoryCandidate.get(data.candidateId, ctx);
+        if (!candidate || candidate instanceof Response)
+            return error(404, "candidate not found");
+        if (auth.kind === "agent" && !auth.isAdmin && candidate.agentId !== auth.agentId)
+            return error(403, "cannot promote another agent's candidate");
+        if (candidate.status !== "pending")
+            return error(409, "candidate is not pending");
+        const actorId = auth.kind === "agent" ? auth.agentId : "admin";
+        const reviewerId = data.reviewerId ?? actorId;
+        if (typeof reviewerId !== "string" || !reviewerId.trim())
+            return error(400, "reviewerId required");
+        if (auth.kind === "agent" && !auth.isAdmin && reviewerId !== actorId)
+            return error(403, "cannot impersonate another reviewer");
+        const reviewerError = validateHumanReviewerId(reviewerId);
+        if (reviewerError)
+            return error(400, reviewerError);
+        const sourceFetches = [];
+        const scopeTag = typeof candidate.scopeTag === "string" && candidate.scopeTag ? candidate.scopeTag : undefined;
+        if (!scopeTag) {
+            for (const id of Array.isArray(candidate.sourceMemoryIds) ? candidate.sourceMemoryIds : []) {
+                try {
+                    const memory = await Memory.get(String(id), ctx);
+                    sourceFetches.push(memory && !(memory instanceof Response)
+                        ? { ok: true, tags: Array.isArray(memory.tags) ? memory.tags : [] } : { ok: false });
+                }
+                catch {
+                    sourceFetches.push({ ok: false });
+                }
+            }
+        }
+        const tags = derivePromotedTags(candidate.id, sourceFetches, scopeTag);
+        if (!tags.ok)
+            return error(400, tags.reason);
+        const visibility = derivePromotedVisibility(candidate);
+        const decidedAt = new Date().toISOString();
+        const memoryId = `${candidate.agentId}-promoted-${randomUUID()}`;
+        const written = await Memory.put({
+            id: memoryId, agentId: candidate.agentId, content: candidate.claim, durability: "persistent",
+            ...(visibility ? { visibility } : {}), tags: tags.tags,
+            derivedFrom: candidate.sourceMemoryIds ?? [], createdAt: decidedAt,
+        }, ctx);
+        if (written instanceof Response && !written.ok)
+            return written;
+        await stampMemoryPromotionIsolated(memoryId, reviewerId, decidedAt);
+        await databases.flair.MemoryCandidate.put({
+            ...candidate, status: "promoted", target: "memory", reviewerId,
+            reviewRationale: data.rationale, decidedAt,
+        });
+        return { memoryId, candidateId: candidate.id, reviewerId, decidedAt };
+    }
+}

package/dist/resources/RecordUsage.js

@@ -4,7 +4,7 @@
  * A generic "record that a memory was actually used" surface: an agent that
  * grounded an answer or decision on a recalled memory reports it here.
  * Distinct from — and NEVER wired to — retrieval: `Memory.retrievalCount`
- * (bumped on every SemanticSearch hit, resources/SemanticSearch.ts:~551) is
+ * (bumped on every SemanticSearch hit, resources/hit-tracking.ts) is
  * the WEAK, self-reinforcing signal root-caused in flair#623 ("a search hit
  * counted as usage"); `Memory.usageCount` (this endpoint's only writer) is
  * the STRONG signal driving `usageBoost` in resources/scoring.ts, which

package/dist/resources/Relationship.js

@@ -1,5 +1,6 @@
 import { databases } from "harper";
 import { resolveAgentAuth } from "./agent-auth.js";
+import { guardOwnerFieldImmutable } from "./owner-field-guard.js";
 import { checkRateLimit, rateLimitResponse } from "./rate-limiter.js";
 import { localInstanceId } from "./instance-identity.js";
 import { buildProvenance, makeAuthGate, makeReadScope, makeByIdReadGate, resolveAuthGate, stampAttribution, FORBIDDEN, UNAUTH, } from "./record-type-kit.js";
@@ -120,7 +121,18 @@ export class Relationship extends databases.flair.Relationship {
      *   HTTP caller and a true internal call, so an internal caller would have
      *   been wrongly 401'd too. resolveAgentAuth distinguishes the two.
      */
+    // PATCH routes past put(), so agentId immutability is enforced on both verbs
+    // via the one shared delegate.
+    async patch(content, query) {
+        const denial = await guardOwnerFieldImmutable(this, () => super.get(), content, "agentId");
+        if (denial)
+            return denial;
+        return super.patch(content, query);
+    }
     async put(content) {
+        const __ownerDenial = await guardOwnerFieldImmutable(this, () => super.get(), content, "agentId");
+        if (__ownerDenial)
+            return __ownerDenial;
         const ctx = this.getContext?.();
         const auth = await resolveAgentAuth(ctx);
         if (auth.kind === "anonymous") {