@tpsdev-ai/flair 0.51.2 → 0.53.0

package/dist/resources/mcp-tools.js

@@ -13,7 +13,7 @@
  * via one of these 14 semantic tools.
  *
  *   memory_search · memory_store · memory_update · memory_get · memory_delete ·
- *   memory_basement · memory_restore ·
+ *   memory_basement · memory_restore · skill_store · skill_search · skill_get ·
  *   bootstrap · soul_set · soul_get · flair_workspace_set · flair_orgevent ·
  *   attention · record_usage
  *
@@ -36,9 +36,26 @@
  * version bump + a new FlairClient method, out of scope for this query-only
  * slice.
  */
+/**
+ * The delegated handler classes, held in a mutable registry, LAZILY loaded on
+ * first use. Two reasons for the indirection:
+ *
+ *   1. Tests inject capture doubles via `__setHandlers` WITHOUT `mock.module`-ing
+ *      the shared `resources/*.ts` files (a process-global bun mock that leaks
+ *      into every other test file).
+ *   2. The handler classes statically `import { Resource, databases } from
+ *      "harper"`. Importing them lazily (dynamic import on first tool
+ *      call, not at module top) keeps `mcp-tools`/`mcp-handler` free of a
+ *      top-level Harper link, so importing the /mcp handler in a unit test never
+ *      requires the full Harper module surface up front.
+ *
+ * Prod: first tool call loads the real classes against a fully-real Harper.
+ */
+import { AUTHORITY_FIELDS } from "./authority-field-guard.js";
 import { resolveVersion } from "./version.js";
 import { agentContext, adminContext, collectionResource } from "./in-process.js";
 import { RECORD_USAGE_ID_MERGE_CONTRACT, unionUsageMemoryIds } from "./usage-ids.js";
+import { SKILL_TAG, isSkillWrite } from "./skill-write.js";
 const H = {};
 const LOADERS = {
     SemanticSearch: async () => (await import("./SemanticSearch.js")).SemanticSearch,
@@ -253,6 +270,157 @@ async function memoryStore(agent, args) {
     // tool ever inlines the vector. No-op when the response carries none.
     return stripInternalFields(await unwrap(await h.post(body)));
 }
+/**
+ * skill_store — write a skill-tagged Memory (flair#1542 component 2).
+ *
+ * A skill is a Memory tagged "skill" (reuse the substrate — no new table).
+ * This tool is a thin wrapper over the SAME Memory.post() write path as
+ * memory_store — it re-implements NO business logic. The three skill-specific
+ * rules (embed from `trigger`, SkillScan gate before the embed, forced
+ * durability=persistent) are enforced SERVER-SIDE in resources/Memory.ts /
+ * resources/skill-write.ts, so this wrapper only shapes the body:
+ *
+ *   - `trigger` → Memory.trigger (the "when to use" text — the recall signal)
+ *   - `content` → Memory.content (the full procedure)
+ *   - `tags`    → Memory.tags (with "skill" prepended)
+ *   - `name`/`description` → folded into Memory.metadata (opaque JSON blob,
+ *     store-and-return, never parsed server-side) so the later skill recall
+ *     tools can surface them.
+ *
+ * durability is NOT set here — the server forces it to "persistent" for any
+ * skill-tagged write (and rejects an explicit ephemeral/session), so a caller
+ * cannot accidentally write a reaped skill.
+ */
+async function skillStore(agent, args) {
+    const Cls = await handler("Memory");
+    const h = await collectionResource(Cls, delegationContext(agent));
+    const body = {
+        agentId: agent.agentId,
+        content: args?.content,
+        trigger: args?.trigger,
+        tags: ["skill", ...(Array.isArray(args?.tags) ? args.tags : [])],
+    };
+    // flair#718 authorship-provenance — same claimedClient passthrough as
+    // memory_store (never a tool argument; sourced from the resolved token).
+    if (agent.clientId)
+        body.claimedClient = agent.clientId;
+    // name/description are SKILL.md frontmatter fields with no dedicated Memory
+    // column; fold them into the opaque metadata blob.
+    const meta = {};
+    if (typeof args?.name === "string" && args.name.length > 0)
+        meta.name = args.name;
+    if (typeof args?.description === "string" && args.description.length > 0)
+        meta.description = args.description;
+    if (Object.keys(meta).length > 0)
+        body.metadata = JSON.stringify(meta);
+    return stripInternalFields(await unwrap(await h.post(body)));
+}
+/**
+ * flair#1546 — the lightweight skill CATALOG card. skill_search is progressive
+ * disclosure: it returns "which skill applies", never the full procedure. A card
+ * carries ONLY id/name/trigger/description/tags/agentId — enough to choose a
+ * skill — and the caller then skill_get's the chosen id for the procedure.
+ *
+ * `name`/`description` are SKILL.md frontmatter with no dedicated Memory column;
+ * skill_store folds them into the opaque `metadata` JSON blob, so this parses
+ * them back out defensively (a corrupt/absent blob simply yields no name/desc).
+ * `content` (the procedure) and the raw embedding are DELIBERATELY absent — the
+ * skill_search contract forbids them on each card.
+ */
+function projectSkillCard(r) {
+    let name;
+    let description;
+    if (typeof r?.metadata === "string" && r.metadata.length > 0) {
+        try {
+            const m = JSON.parse(r.metadata);
+            if (m && typeof m === "object") {
+                if (typeof m.name === "string")
+                    name = m.name;
+                if (typeof m.description === "string")
+                    description = m.description;
+            }
+        }
+        catch { /* opaque/corrupt metadata → no name/description on the card */ }
+    }
+    return {
+        id: r?.id,
+        name,
+        trigger: r?.trigger,
+        description,
+        tags: r?.tags,
+        agentId: r?.agentId,
+    };
+}
+/**
+ * skill_search — recall skill-tagged Memories for a task (flair#1546 component 1).
+ *
+ * The core recall tool, and a THIN wrapper over the SAME SemanticSearch handler
+ * as memory_search — it re-implements NO retrieval or scoping logic. It rides:
+ *   - a tags-equals seek for the "skill" tag (only skill rows are candidates);
+ *   - the HNSW leg over the stored embedding — which for a skill row IS the
+ *     `trigger` embedding (#1543), so the task is ranked against "when to use";
+ *   - the 'query' inputType SemanticSearch already applies to the task string;
+ *   - resolveReadScope (own any-visibility + every non-private row) — NEVER
+ *     another agent's private skill.
+ * Identity is the RESOLVED agent; no body agentId is forwarded, so a caller can
+ * never widen scope past its own read-scope (the SemanticSearch cross-agent
+ * guard would 403 a mismatch anyway).
+ *
+ * The drawer / working-set scope named in the spec is Deliverable B and does
+ * NOT exist yet (see resources/MemoryArchive.ts / memory_restore's doc) — there
+ * is no working-set layer to compose with, so scope today is exactly
+ * resolveReadScope's open-within-org read. When drawers land, this rides
+ * whatever scope SemanticSearch resolves, for free.
+ */
+async function skillSearch(agent, args) {
+    const Cls = await handler("SemanticSearch");
+    const h = new Cls(undefined, delegationContext(agent));
+    const res = await unwrap(await h.post({
+        q: args?.task,
+        tag: SKILL_TAG,
+        limit: args?.limit ?? 5,
+        // name/description live in the metadata blob; trigger is not in
+        // DEFAULT_SELECT — opt both into the projection so the card can carry them.
+        includeMetadata: true,
+        includeTrigger: true,
+    }));
+    // A guard/error Response unwraps to `{ error, status }` (no `results`) — pass
+    // it through untouched so the caller sees the structured refusal.
+    if (!res || typeof res !== "object" || !Array.isArray(res.results))
+        return res;
+    // Progressive disclosure: return the CATALOG (lightweight cards), never the
+    // full procedure. `_warning` / any other top-level keys pass through.
+    return { ...res, results: res.results.map(projectSkillCard) };
+}
+/**
+ * skill_get — the full skill by id (flair#1546 component 2).
+ *
+ * A thin wrapper over Memory.get() — the SAME by-id read as memory_get, under
+ * the SAME read-scope gate (makeByIdReadGate → resolveReadScope): a non-owner
+ * cannot read another agent's PRIVATE skill (it 404s), exactly as a private
+ * memory does. skill_get is the disclosure step after skill_search's catalog:
+ * it returns the full procedure (`content`) + trigger + metadata.
+ *
+ * It is a SKILL tool, not a general reader: a readable id that is NOT a skill
+ * returns the same 404 as an unreadable id. Returning it would (a) make
+ * skill_get an alias for memory_get, and (b) reveal a readable non-skill
+ * memory's existence through a skill-shaped call; a uniform 404 does neither.
+ * The embedding fields are stripped by default, same as memory_get.
+ */
+async function skillGet(agent, args) {
+    const Cls = await handler("Memory");
+    // flair#1181 — by-id reads use the STATIC `Cls.get(id, context)` form (see
+    // memoryGet for the full rationale). Read-scope is enforced inside Memory.get.
+    const result = await unwrap(await Cls.get(args?.id, delegationContext(agent)));
+    // A NOT_FOUND / unreadable id unwraps to `{ error, status }` — pass it through.
+    if (!result || typeof result !== "object" || result.error != null)
+        return result;
+    // Skill-only: a readable non-skill row is reported as not found rather than
+    // returned (see the doc above).
+    if (!isSkillWrite(result))
+        return { error: "skill not found", status: 404 };
+    return args?.includeEmbedding === true ? result : stripInternalFields(result);
+}
 /**
  * memory_update — id-targeted, dedup-BYPASSED overwrite/version path (memory-
  * integrity fix). Mirrors flair-client's MemoryApi.update() (packages/
@@ -311,6 +479,10 @@ async function memoryUpdate(agent, args) {
         delete record.validFrom;
         delete record.validTo;
         delete record.archivedAt;
+        // A successor contains new, unreviewed content; keep the verdict on its
+        // predecessor instead of claiming that the new version was approved.
+        for (const field of AUTHORITY_FIELDS.Memory)
+            delete record[field];
         // flair#1189 — retrievalCount and lastRetrieved are RECORD-scoped, not
         // lineage-scoped: a brand-new successor record has no retrieval history of
         // its OWN, so it must start with none. Inheriting them from the superseded
@@ -319,8 +491,9 @@ async function memoryUpdate(agent, args) {
         // existed"), silently corrupting any recency/usage-based ranking that reads
         // these fields. Reset both here, at succession construction — NOT server-
         // side, because `supersedes` is a PERMANENT property of every successor and
-        // legitimate later retrievalCount bumps route through put() on a record that
-        // still carries it. Usage/citation-ledger counters (usageCount, the #1147
+        // legitimate later retrievalCount bumps route through MemoryHitStat
+        // (resources/hit-tracking.ts) on the successor's own id. Usage/citation-
+        // ledger counters (usageCount, the #1147
         // citation ledger) are a SEPARATE, arguably lineage-scoped question and are
         // deliberately left untouched here (#1147's usage loop is currently inert).
         record.retrievalCount = 0;
@@ -742,6 +915,97 @@ export const TOOLS = {
             errorShape: { trigger: "an unrecognized visibility value (e.g. \"prvate\")", fields: ["error", "status"], mustNotLeak: INTERNAL_MEMORY_FIELDS },
         },
     },
+    skill_store: {
+        def: {
+            name: "skill_store",
+            description: "Write a skill (a reusable capability/procedure) as a skill-tagged memory. " +
+                "The `trigger` text is what the skill embeds from (the recall signal — 'when to use this'), " +
+                "and `content` is the full procedure. Skills are forced durability=persistent and are " +
+                "SkillScan-gated before the embed (a dangerous shell/network payload is rejected).",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    content: { type: "string", description: "The full procedure (markdown body of the SKILL.md)" },
+                    trigger: { type: "string", description: "The 'when to use' text — the recall signal the skill embeds from" },
+                    name: { type: "string", description: "Skill name (SKILL.md frontmatter; stored in metadata)" },
+                    description: { type: "string", description: "Skill description (SKILL.md frontmatter; stored in metadata)" },
+                    tags: { type: "array", items: { type: "string" }, description: "Additional tags (the 'skill' tag is added automatically)" },
+                },
+                required: ["content"],
+            },
+        },
+        impl: skillStore,
+        contract: {
+            summary: "Write echo { id, written:true, deduplicated } for the skill-tagged memory. No internal embedding fields; round-trips via memory_get.",
+            requiredFields: ["id", "written"],
+            fieldTypes: { id: "string", written: "boolean", deduplicated: "boolean" },
+            forbiddenFields: INTERNAL_MEMORY_FIELDS,
+            invariants: { fullyResolved: true },
+            errorShape: { trigger: "a skill whose trigger/content fails SkillScan (high/critical risk)", fields: ["error", "status"], mustNotLeak: INTERNAL_MEMORY_FIELDS },
+        },
+    },
+    skill_search: {
+        def: {
+            name: "skill_search",
+            description: "Find skills (reusable capabilities/procedures) that apply to a task. " +
+                "Ranks skill-tagged memories by their `trigger` ('when to use') against your task text. " +
+                "Returns a lightweight CATALOG — id, name, trigger, description, tags, agentId — NOT the full " +
+                "procedure (fetch that with skill_get). Scoped to your own + shared skills; another agent's " +
+                "private skill is never returned.",
+            annotations: { readOnlyHint: true },
+            inputSchema: {
+                type: "object",
+                properties: {
+                    task: { type: "string", description: "The task/context to match skills against — natural language; ranked against each skill's trigger" },
+                    limit: { type: "number", description: "Max skills to return (default 5)" },
+                },
+                required: ["task"],
+            },
+        },
+        impl: skillSearch,
+        contract: {
+            summary: "{ results: SkillCard[] } — the skill catalog (lightweight id/name/trigger/description/tags/agentId, " +
+                "ranked by trigger match); the full procedure and the raw embedding are never on a card. Scoped to the " +
+                "caller's own + non-private skills; another agent's private skill is never returned.",
+            requiredFields: ["results"],
+            fieldTypes: { results: "array" },
+            invariants: {
+                selfDescribingEmpty: [{ path: "results", type: "array" }],
+                // Each card carries id, and NEVER the full procedure (`content`) or the
+                // raw embedding — the progressive-disclosure guarantee.
+                containerRules: [{ container: "results", requiredFields: ["id"], forbiddenFields: [...INTERNAL_MEMORY_FIELDS, "content"] }],
+                fullyResolved: true,
+            },
+        },
+    },
+    skill_get: {
+        def: {
+            name: "skill_get",
+            description: "Retrieve a full skill by ID — the complete procedure (`content`) plus trigger and metadata. " +
+                "The disclosure step after skill_search's catalog. Read-scoped: you can only get your own or a " +
+                "shared skill, never another agent's private skill. A non-skill id returns not-found.",
+            annotations: { readOnlyHint: true },
+            inputSchema: {
+                type: "object",
+                properties: {
+                    id: { type: "string", description: "Skill (memory) ID" },
+                    includeEmbedding: { type: "boolean", description: "Include the raw embedding vector (large, rarely useful). Default false." },
+                },
+                required: ["id"],
+            },
+        },
+        impl: skillGet,
+        contract: {
+            summary: "The full skill record { id, agentId, content, trigger, tags, durability, metadata, createdAt, ... } for a " +
+                "skill readable under the caller's read-scope — embedding + embeddingModel stripped by default. A non-owner " +
+                "cannot read another agent's private skill, and a readable non-skill id is not found (both 404).",
+            requiredFields: ["id", "agentId", "content", "createdAt"],
+            fieldTypes: { id: "string", agentId: "string", content: "string" },
+            forbiddenFields: INTERNAL_MEMORY_FIELDS,
+            invariants: { fullyResolved: true },
+            errorShape: { trigger: "get a non-skill / unreadable / another agent's private id (404)", fields: ["error", "status"] },
+        },
+    },
     memory_update: {
         def: {
             name: "memory_update",
@@ -855,9 +1119,9 @@ export const TOOLS = {
         },
         impl: memoryDelete,
         contract: {
-            summary: "Deletes the caller's own memory (success echo is thin). The permanent-memory guard returns { error, status:403 } for a non-admin; the row round-trips as gone via memory_get.",
+            summary: "Deletes the caller's own memory at any durability tier (success echo is thin). Cross-owner deletion returns { error, status:403 } for a non-admin; a deleted row round-trips as gone via memory_get.",
             invariants: { fullyResolved: true },
-            errorShape: { trigger: "a non-admin deletes a permanent memory", fields: ["error", "status"] },
+            errorShape: { trigger: "a non-admin deletes another agent's memory", fields: ["error", "status"] },
         },
     },
     bootstrap: {
@@ -1000,7 +1264,7 @@ export const TOOLS = {
     soul_set: {
         def: {
             name: "soul_set",
-            description: "Set a personality or project context entry. Included in every bootstrap.",
+            description: "Soul changes require operator credentials through the REST API or CLI; runtime tool calls are refused.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -1012,8 +1276,9 @@ export const TOOLS = {
         },
         impl: soulSet,
         contract: {
-            summary: "Writes a soul entry keyed `${agentId}:${key}`, attributed to the caller. Correctness is proven by the soul_get round-trip — this is the write flair#1181 broke on the connector path.",
+            summary: "Refuses runtime Soul writes, including admin-agent delegation, with { error, status:403 }. Operators use the authenticated REST or CLI path.",
             invariants: { fullyResolved: true },
+            errorShape: { trigger: "a runtime attempts to write Soul", fields: ["error", "status"] },
         },
     },
     soul_get: {

package/dist/resources/memory-reflect-lib.js

@@ -19,6 +19,24 @@
  * to be reviewed for promotion, not raw source data.
  */
 export const MAX_CANDIDATES_PER_RUN = 10;
+/**
+ * Per-run gather cap for distillation input (#1515). Tens, not thousands —
+ * a 3k backlog must drain across nights instead of one blocking run.
+ * Duplicated by value in src/rem/runner.ts (npm-packaging boundary).
+ */
+export const DEFAULT_MAX_MEMORIES_PER_RUN = 50;
+/**
+ * Hard ceiling on FLAIR_REM_MAX_MEMORIES / request maxMemories. An operator
+ * who sets 3000 would recreate the outage this cap exists to prevent.
+ * Duplicated by value in src/rem/runner.ts.
+ */
+export const ABSOLUTE_MAX_MEMORIES_PER_RUN = 200;
+/**
+ * Event-loop yield budget (ms) during the gather scan. Same convention as
+ * MemoryDedupStats: after this much synchronous work, await setImmediate
+ * so /Health and reads can run. Not a throughput claim.
+ */
+export const REM_GATHER_YIELD_BUDGET_MS = 10;
 /**
  * Max characters per candidate claim. Candidates are meant to be atomic,
  * single-insight lessons (matches the "Keep each memory atomic" instruction
@@ -554,3 +572,96 @@ export function buildStagedCandidateRow(params) {
     }
     return row;
 }
+/** A memory is unreflected when lastReflected is missing or blank. */
+export function isUnreflectedMemory(record) {
+    return record.lastReflected == null || record.lastReflected === "";
+}
+/**
+ * Resolve the per-run gather cap: explicit override > FLAIR_REM_MAX_MEMORIES
+ * (positive, finite) > DEFAULT_MAX_MEMORIES_PER_RUN, then clamp to
+ * ABSOLUTE_MAX_MEMORIES_PER_RUN. Exported for tests and the nightly runner's
+ * duplicated resolver (kept in sync by value).
+ */
+export function resolveMaxMemoriesPerRun(override, env = process.env) {
+    let resolved = DEFAULT_MAX_MEMORIES_PER_RUN;
+    if (typeof override === "number" && Number.isFinite(override) && override > 0) {
+        resolved = Math.floor(override);
+    }
+    else {
+        const fromEnv = Number(env.FLAIR_REM_MAX_MEMORIES);
+        if (Number.isFinite(fromEnv) && fromEnv > 0)
+            resolved = Math.floor(fromEnv);
+    }
+    return Math.min(resolved, ABSOLUTE_MAX_MEMORIES_PER_RUN);
+}
+/**
+ * Stamp `lastReflected` only after generateCandidates succeeds on an
+ * execute run. Prompt-only (`execute: false`) and failed generate/abort
+ * must leave the pointer unset so the next night can retry (#1515 Bugbot).
+ */
+export function shouldStampLastReflected(opts) {
+    return opts.execute === true && opts.generateSucceeded === true;
+}
+/** Oldest createdAt first. Missing timestamps sort last (never "oldest"). */
+export function compareOldestCreatedAtFirst(a, b) {
+    const ac = a.createdAt ?? "";
+    const bc = b.createdAt ?? "";
+    if (!ac && !bc)
+        return 0;
+    if (!ac)
+        return 1;
+    if (!bc)
+        return -1;
+    return ac.localeCompare(bc);
+}
+/**
+ * Unreflected first, then oldest createdAt. Nightly uses this so a backlog
+ * of never-reflected rows drains before anything is re-distilled.
+ */
+export function compareOldestUnreflectedFirst(a, b) {
+    const aU = isUnreflectedMemory(a) ? 0 : 1;
+    const bU = isUnreflectedMemory(b) ? 0 : 1;
+    if (aU !== bU)
+        return aU - bU;
+    return compareOldestCreatedAtFirst(a, b);
+}
+/**
+ * Keep at most `maxN` records, oldest-unreflected first. Already-reflected
+ * rows lose to any unreflected row (so a 3k backlog drains) but still fill
+ * leftover slots when fewer than `maxN` unreflected matches exist — a
+ * tagged/recent gather after a prior reflect must not go empty.
+ * Mutates `pool` and returns it (bounded insert, O(N) with N ≤ 200).
+ */
+export function considerForOldestUnreflectedCap(pool, record, maxN) {
+    if (maxN <= 0)
+        return pool;
+    if (pool.length < maxN) {
+        pool.push(record);
+        pool.sort(compareOldestUnreflectedFirst);
+        return pool;
+    }
+    const worstKept = pool[pool.length - 1];
+    if (compareOldestUnreflectedFirst(record, worstKept) < 0) {
+        pool[pool.length - 1] = record;
+        pool.sort(compareOldestUnreflectedFirst);
+    }
+    return pool;
+}
+/**
+ * True when an operator asked REM to stop: FLAIR_REM_PAUSE=1 or the pause
+ * sentinel exists. MemoryReflect checks this between gather yields so
+ * `flair rem pause` aborts an in-flight scan without restarting Harper.
+ * `existsSync` is injected so unit tests do not touch the real home directory.
+ */
+export function isRemAbortRequested(env = process.env, existsSyncImpl, pauseFlagPath) {
+    if (env.FLAIR_REM_PAUSE === "1")
+        return true;
+    if (!existsSyncImpl || !pauseFlagPath)
+        return false;
+    try {
+        return existsSyncImpl(pauseFlagPath);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/resources/migrations/embedding-stamp.js

@@ -127,6 +127,7 @@
  */
 import { databases } from "harper";
 import { getModelId } from "../embeddings-provider.js";
+import { currentSpaceRawForms, isCurrentSpaceStamp } from "../embedding-space-guard.js";
 function defaultMemoryTable() {
     return databases.flair.Memory;
 }
@@ -192,11 +193,28 @@ export function createEmbeddingStampMigration(getTable = defaultMemoryTable, get
         // reads the live record directly. Reverting this to "not_equal" would
         // reopen #807 on any store where the embeddingModel index lags the
         // on-disk value.
+        // embedding-space-guard slice 1: getModelId() now stamps the
+        // ENGINE-QUALIFIED id (`gguf:<base>[+searchprefix]`). Today's corpus is
+        // stamped with the BARE name, which denotes the SAME space — so a row is
+        // current-space iff its stamp is EITHER the qualified id OR its bare
+        // equivalent. `currentSpaceRawForms()` returns both; stale = matches
+        // NEITHER (an AND of `not_equals`), so a legacy bare row is NOT re-embedded
+        // (which would loop forever — Memory.put re-stamps it qualified, still
+        // "!= bare" under a single-value check). Each leg stays the `not_equals`
+        // PREFIX form (flair#807: resolves to a negated-equals leaf that bypasses a
+        // possibly-stale secondary index and reads the live record).
+        const forms = currentSpaceRawForms(getCurrentModelId());
+        const notCurrentSpace = forms.length === 1
+            ? { attribute: "embeddingModel", comparator: "not_equals", value: forms[0] }
+            : {
+                operator: "and",
+                conditions: forms.map((f) => ({ attribute: "embeddingModel", comparator: "not_equals", value: f })),
+            };
         return [
             {
                 operator: "or",
                 conditions: [
-                    { attribute: "embeddingModel", comparator: "not_equals", value: getCurrentModelId() },
+                    notCurrentSpace,
                     { attribute: "embeddingModel", comparator: "equals", value: null },
                 ],
             },
@@ -235,8 +253,8 @@ export function createEmbeddingStampMigration(getTable = defaultMemoryTable, get
                 const existing = await table.get(id);
                 if (!existing)
                     continue; // deleted since the search above — nothing to fix
-                if (existing.embeddingModel === current)
-                    continue; // already stamped by a concurrent runner — idempotent skip
+                if (isCurrentSpaceStamp(existing.embeddingModel, current))
+                    continue; // already current-space (incl. bare equivalent) — idempotent skip
                 const ok = await regen(id, existing);
                 if (ok)
                     touchedIds.push(id);
@@ -273,7 +291,7 @@ export function createEmbeddingStampMigration(getTable = defaultMemoryTable, get
                 // A row that vanished since the search, OR whose live embeddingModel
                 // still doesn't match current, is a GENUINE pending row (or a
                 // concurrent delete) — never counted as a false positive.
-                if (existing && existing.embeddingModel === current)
+                if (existing && isCurrentSpaceStamp(existing.embeddingModel, current))
                     falsePositives++;
             }
             return { sampled: ids.length, falsePositives };

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

@@ -0,0 +1,62 @@
+/**
+ * owner-field-guard.ts — the single resource-layer delegate that enforces
+ * owner-field immutability for principal-owning tables.
+ *
+ * ─── Why this is at the resource layer, not the middleware ────────────────────
+ *
+ * The shared record-ownership guard (record-owner-guard.ts, applied by
+ * auth-middleware.ts) already refuses a non-owner mutating a stored row, on
+ * every verb, reading ownership from stored state. What it CANNOT do is decide
+ * whether a write CHANGES the owner field, because that needs the request body —
+ * and Harper's middleware Request exposes no parsed body (no `.json()`, no
+ * `.clone()`; `.body` is a single-consumption stream). So this rule lives one
+ * layer down, where Harper hands the resource its parsed `content`.
+ *
+ * That is exactly why resources/Agent.ts enforces its analogous rule (a
+ * principal's admin status) in the resource and not the middleware. This file is
+ * the generalisation of that pattern for the ordinary owner field, kept in ONE
+ * place so the per-resource put()/patch() overrides are a thin delegation rather
+ * than N hand-written checks that could drift apart.
+ *
+ * ─── The rule ────────────────────────────────────────────────────────────────
+ *
+ *   A non-admin caller may not write a value into a stored record's owner field
+ *   that differs from the value already there.
+ *
+ * Admin and internal callers pass through. A create (no stored record yet) is
+ * not this rule's business — no-forge attribution on creation is each resource's
+ * own job. The decision itself is the pure `isForbiddenOwnerFieldChange`
+ * (record-owner-guard.ts), so it is unit-tested without a Harper instance.
+ */
+import { resolveAgentAuth } from "./agent-auth.js";
+import { isForbiddenOwnerFieldChange } from "./record-owner-guard.js";
+/**
+ * Enforce owner-field immutability for one write.
+ *
+ * @param self        the resource instance (`this`)
+ * @param getExisting a thunk that returns the STORED record — pass `() => super.get()`
+ *                    so the raw base-table read is used rather than any get() override
+ * @param content     the write content (the caller's claim)
+ * @param ownerField  the column naming the owning principal for this table
+ * @returns a 403 Response to send, or null to proceed
+ */
+export async function guardOwnerFieldImmutable(self, getExisting, content, ownerField) {
+    const auth = await resolveAgentAuth(self.getContext?.());
+    if (auth.kind === "internal" || (auth.kind === "agent" && auth.isAdmin))
+        return null;
+    // Any caller that is not a resolved agent (anonymous, or an identity that did
+    // not resolve) has no owner identity to match against, so it may not proceed
+    // on an owner-bearing write path — fail closed. The denial is 401, not 403:
+    // an unresolved caller is unauthenticated, which is the same contract every
+    // principal-owning resource already returns for anonymous writes, and the
+    // owner-field rule only applies to a caller that HAS an owner identity. This
+    // also narrows `auth` to the agent variant, so `auth.agentId` below is typed.
+    if (auth.kind !== "agent") {
+        return new Response(JSON.stringify({ error: "authentication required" }), { status: 401, headers: { "content-type": "application/json" } });
+    }
+    const existing = (await Promise.resolve(getExisting()).catch(() => null));
+    if (isForbiddenOwnerFieldChange(existing, content, ownerField, auth.agentId)) {
+        return new Response(JSON.stringify({ error: "forbidden: the owner of a record cannot be changed" }), { status: 403, headers: { "content-type": "application/json" } });
+    }
+    return null;
+}

package/dist/resources/promotion-stamp.js

@@ -0,0 +1,29 @@
+import { withDetachedTxn } from "./table-helpers.js";
+import { databases } from "harper";
+import { noteMemoryUpsert } from "./bm25-index-service.js";
+// Called only after the promotion workflow has authorized and written a Memory
+// through its resource (safety, embedding, ownership and provenance still run).
+// Auto-promotion supplies its enumeration context: its Memory write used a
+// separate agentContext, so that enumeration snapshot cannot see the new row.
+// Manual promotion keeps the stamp in its own write transaction.
+export async function stampMemoryPromotion(id, reviewerId, decidedAt, enumerationContext) {
+    const table = databases.flair.Memory;
+    const stored = await withDetachedTxn(enumerationContext, () => table.get(id));
+    if (!stored)
+        throw new Error(`Promotion memory ${id} was not written`);
+    const row = { ...stored, promotionStatus: "approved", promotedBy: reviewerId, promotedAt: decidedAt };
+    await withDetachedTxn(enumerationContext, () => table.put(row));
+    noteMemoryUpsert(row);
+}
+/** Stamp after a successful Memory write. Failures must not abort a sweep or
+ * leave a candidate pending (that re-writes the same claim next cycle). */
+export async function stampMemoryPromotionIsolated(id, reviewerId, decidedAt, enumerationContext) {
+    try {
+        await stampMemoryPromotion(id, reviewerId, decidedAt, enumerationContext);
+        return true;
+    }
+    catch (err) {
+        console.warn(`stampMemoryPromotion failed for ${id}: ${err?.message ?? err}`);
+        return false;
+    }
+}