@staix/agent-mem 0.20.3 → 0.22.0

package/src/memory/candidates.ts

@@ -1,7 +1,7 @@
 import { assertFormatFloor } from "./formats.ts";
 import { Database } from "bun:sqlite";
 import { createHash } from "node:crypto";
-import { chmodSync, mkdirSync } from "node:fs";
+import { chmodSync, lstatSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { CANDIDATE_SHOWN_GRACE_MS, hasShownColumn } from "./candidate-pending.ts";
 import { oneLine } from "./note-add.ts";
@@ -130,6 +130,72 @@ function retryLocked(work: () => void): void {
   }
 }
 
+type CandidateRow = { id: string; payload: string; at: number; status: CandidateStatus; note_id: string | null };
+/** Canonical persisted decoding shared by the writer and its read-only inbox port. */
+function decodeCandidate(row: CandidateRow, unknownKind: () => void): Candidate | undefined {
+  const input = JSON.parse(row.payload) as CandidateInput;
+  if (input && typeof input === "object" && !KINDS.includes(input.kind)) { unknownKind(); return undefined; }
+  validate(input);
+  if (hash({ schema: "agent-mem.candidate/v1", input }) !== row.id) throw new Error("candidate content hash mismatch");
+  return { id: row.id, createdAt: new Date(row.at).toISOString(), status: row.status, input, acceptedNoteId: row.note_id };
+}
+const CANDIDATE_EXPIRED_SQL = "at <= ? AND (status IN ('accepted', 'rejected') OR (shown_at IS NOT NULL AND shown_at <= ?))";
+const CANDIDATE_PRIORITY_SQL = "CASE WHEN status IN ('pending', 'accepting') AND shown_at IS NULL THEN 2 WHEN status IN ('pending', 'accepting') THEN 1 ELSE 0 END DESC, at DESC";
+export interface PendingCandidateReader { projects(): string[]; list(projects: readonly string[]): Candidate[]; nextExpiry(): number | null }
+/** Internal inbox read port. It neither creates/migrates a database nor prunes or stamps any row.
+ * The port is valid only during the synchronous callback. No immutable fallback may hide current WAL frames. */
+export function withPendingCandidates<T>(memoryDir: string, run: (reader: PendingCandidateReader) => T): T {
+  assertFormatFloor(memoryDir, "candidates");
+  const file = join(memoryDir, "candidates.db"), stat = lstatSync(file, { throwIfNoEntry: false });
+  if (!stat) {
+    let closed = false;
+    const assertOpen = () => { if (closed) throw new Error("pending candidate reader is closed"); };
+    try { return run({ projects() { assertOpen(); return []; }, list(projects) {
+      assertOpen(); if (!Array.isArray(projects) || projects.some(project => !text(project, 400))) throw new Error("invalid candidate project scope"); return [];
+    }, nextExpiry() { assertOpen(); return null; } }); } finally { closed = true; }
+  }
+  if (!stat.isFile() || stat.isSymbolicLink()) throw new Error("pending candidates unavailable");
+  const db = new Database(file, { readonly: true }); let closed = false;
+  try {
+    const shown = hasShownColumn(db), now = Date.now();
+    const live = (scope: boolean) => `WITH raw AS (SELECT rowid AS candidate_rowid, id, project, kind, payload, at, status, note_id, ${shown ? "shown_at" : "NULL AS shown_at"} FROM candidates${scope ? " WHERE project IN (SELECT value FROM json_each(?))" : ""}),
+      live AS (SELECT * FROM raw WHERE NOT (${CANDIDATE_EXPIRED_SQL})),
+      retained AS (SELECT *, row_number() OVER (PARTITION BY project ORDER BY ${CANDIDATE_PRIORITY_SQL}, candidate_rowid DESC) AS retention_rank FROM live)`;
+    const assertOpen = () => { if (closed) throw new Error("pending candidate reader is closed"); };
+    return run({
+      nextExpiry() {
+        assertOpen(); if (!shown) return null;
+        const row = db.query(`${live(false)} SELECT min(expiry) AS expiry FROM (
+          SELECT max(at + ?, shown_at + ?) AS expiry FROM retained WHERE retention_rank <= ? AND status = 'pending'
+            AND shown_at IS NOT NULL AND kind IN (SELECT value FROM json_each(?))) WHERE expiry > ?`)
+          .get(now - CANDIDATE_RETENTION.ageMs, now - CANDIDATE_SHOWN_GRACE_MS, CANDIDATE_RETENTION.ageMs,
+            CANDIDATE_SHOWN_GRACE_MS, CANDIDATE_RETENTION.count, JSON.stringify(KINDS), now) as { expiry: number | null };
+        if (row.expiry !== null && (!Number.isFinite(row.expiry) || row.expiry <= now)) throw new Error("pending candidate expiry unavailable");
+        return row.expiry;
+      },
+      projects() {
+        assertOpen();
+        const rows = db.query(`${live(false)} SELECT DISTINCT project FROM retained WHERE retention_rank <= ? AND status = 'pending' AND kind IN (SELECT value FROM json_each(?)) ORDER BY project`)
+          .all(now - CANDIDATE_RETENTION.ageMs, now - CANDIDATE_SHOWN_GRACE_MS, CANDIDATE_RETENTION.count, JSON.stringify(KINDS)) as { project: string }[];
+        if (rows.some(row => !text(row.project, 400))) throw new Error("pending candidate project unavailable");
+        return rows.map(row => row.project);
+      },
+      list(projects) {
+        assertOpen();
+        if (!Array.isArray(projects) || projects.some(project => !text(project, 400))) throw new Error("invalid candidate project scope");
+        if (!projects.length) return [];
+        const rows = db.query(`${live(true)} SELECT * FROM retained WHERE retention_rank <= ? AND status = 'pending' AND kind IN (SELECT value FROM json_each(?)) ORDER BY at DESC, candidate_rowid DESC LIMIT ?`)
+          .all(JSON.stringify([...new Set(projects)]), now - CANDIDATE_RETENTION.ageMs, now - CANDIDATE_SHOWN_GRACE_MS, CANDIDATE_RETENTION.count, JSON.stringify(KINDS), CANDIDATE_RETENTION.count) as (CandidateRow & { project: string })[];
+        return rows.flatMap(row => {
+          const candidate = decodeCandidate(row, () => {});
+          if (candidate && candidate.input.project !== row.project) throw new Error("candidate project binding mismatch");
+          return candidate ? [candidate] : [];
+        });
+      },
+    });
+  } finally { closed = true; db.close(); }
+}
+
 /** The queue holds the cap's worth of candidates nobody has seen. Named so a caller (the MCP tool) can map it. */
 export class CandidateQueueFull extends Error {
   readonly code = "candidate_queue_full";
@@ -184,20 +250,16 @@ export class CandidateStore {
       this.retainConsolidationReviews();
       // Candidates (AC4, no candidate expires unshown): by age only a decided one, or a pending one that was shown and has had its grace period, goes. By count three tiers decide who is
       // kept: unshown pending first, then shown pending, then decided, so a cap eviction takes decided rows before a shown one (which is owed its grace) and shown ones before an unseen one.
-      this.db.query("DELETE FROM candidates WHERE at <= ? AND (status IN ('accepted', 'rejected') OR (shown_at IS NOT NULL AND shown_at <= ?))").run(now - CANDIDATE_RETENTION.ageMs, now - CANDIDATE_SHOWN_GRACE_MS);
-      this.db.query(`DELETE FROM candidates WHERE rowid IN (SELECT rowid FROM (SELECT rowid, row_number() OVER (PARTITION BY project ORDER BY CASE WHEN status IN ('pending', 'accepting') AND shown_at IS NULL THEN 2 WHEN status IN ('pending', 'accepting') THEN 1 ELSE 0 END DESC, at DESC, rowid DESC) AS rank FROM candidates) WHERE rank > ?)`).run(CANDIDATE_RETENTION.count);
+      this.db.query(`DELETE FROM candidates WHERE ${CANDIDATE_EXPIRED_SQL}`).run(now - CANDIDATE_RETENTION.ageMs, now - CANDIDATE_SHOWN_GRACE_MS);
+      this.db.query(`DELETE FROM candidates WHERE rowid IN (SELECT rowid FROM (SELECT rowid, row_number() OVER (PARTITION BY project ORDER BY ${CANDIDATE_PRIORITY_SQL}, rowid DESC) AS rank FROM candidates) WHERE rank > ?)`).run(CANDIDATE_RETENTION.count);
       this.db.query("DELETE FROM counters WHERE at <= ?").run(now - COUNTER_RETENTION.ageMs);
       this.db.query("DELETE FROM counters WHERE rowid IN (SELECT rowid FROM (SELECT rowid, row_number() OVER (PARTITION BY project ORDER BY at DESC, rowid DESC) AS rank FROM counters) WHERE rank > ?)").run(COUNTER_RETENTION.count);
     }).immediate();
   }
   /** #199: rows of a kind this version does not know (a newer writer's) are skipped and counted here, never thrown. */
   skippedUnknownKinds = 0;
-  private decode(row: { id: string; payload: string; at: number; status: CandidateStatus; note_id: string | null }): Candidate | undefined {
-    const input = JSON.parse(row.payload) as CandidateInput;
-    if (input && typeof input === "object" && !KINDS.includes(input.kind)) { this.skippedUnknownKinds++; return undefined; }
-    validate(input);
-    if (hash({ schema: "agent-mem.candidate/v1", input }) !== row.id) throw new Error("candidate content hash mismatch");
-    return { id: row.id, createdAt: new Date(row.at).toISOString(), status: row.status, input, acceptedNoteId: row.note_id };
+  private decode(row: CandidateRow): Candidate | undefined {
+    return decodeCandidate(row, () => { this.skippedUnknownKinds++; });
   }
   put(rawInput: CandidateInput, verdict: CandidateVerdict): string {
     // `<private>` spans are never stored: dropped before the input is validated, hashed (so the id) or written.

package/src/memory/commands.ts

@@ -206,11 +206,12 @@ export async function rawMemoryCommand(args: string[], cwd: string, opts: Memory
         const r = await syncMemory(store, { ...opts.sync, ...(remote ? { remote } : {}) });
         if (json) return JSON.stringify(r, null, 2);
         if (!r.ok) fail(`${names.memory} sync: ${r.error}`);
+        const placement = r.placementPublication, placementText = placement ? `; placement ${placement.outcome}, ${placement.exported} exported, ${placement.withheld} withheld this attempt` : "";
         if (r.pruneApplication) {
           const a = r.pruneApplication;
-          return `synced${r.pushed ? " and pushed" : ""}: ${r.entries} long-term entries transported; ${a.proofComplete} prune proofs complete, ${a.projectionActive ?? "pending"} foreign projections active, ${a.nativeApplied ?? "pending"} native prunes applied, ${a.held} held${r.warning ? `\nnote: ${r.warning}` : ""}`;
+          return `synced${r.pushed ? " and pushed" : ""}: ${r.entries} long-term entries transported; ${a.proofComplete} prune proofs complete, ${a.projectionActive ?? "pending"} foreign projections active, ${a.nativeApplied ?? "pending"} native prunes applied, ${a.held} held${placementText}${r.warning ? `\nnote: ${r.warning}` : ""}`;
         }
-        return `synced${r.pushed ? " and pushed" : ""}: ${r.entries} long-term entries visible here${r.warning ? `\nnote: ${r.warning}` : ""}`;
+        return `synced${r.pushed ? " and pushed" : ""}: ${r.entries} long-term entries visible here${placementText}${r.warning ? `\nnote: ${r.warning}` : ""}`;
       }
       case "dedupe": {
         const apply = rest.includes("--apply");

package/src/memory/generation-index.ts

@@ -6,8 +6,8 @@ import type { Database } from "bun:sqlite";
 import { createHash } from "node:crypto";
 import { closeSync, constants, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, unlinkSync, writeSync } from "node:fs";
 import { join } from "node:path";
-import { canonicalJSON, hashJSON, fsyncDirectory, readProfileJSON, selectorRevision, writeProfileJSON, type BoundProfile, validateVaultLinkRow, type VaultLink, rebindPublicPruneProfile } from "./generation.ts";
-import { legacyEntries, legacyHead, readLegacySnapshot, SegmentReader, type LegacyCheckpoint, type LegacySegment } from "./bridge.ts";
+import { canonicalJSON, hashJSON, fsyncDirectory, readProfileJSON, selectorRevision, writeProfileJSON, type BoundProfile, generationDescriptor, readSelector, validateVaultLinkRow, type VaultLink, rebindPublicPruneProfile } from "./generation.ts";
+import { checkedEntry, completeLines, legacyEntries, legacyHead, readLegacySnapshot, SegmentReader, SegmentReadBudgetError, type LegacyCheckpoint, type LegacySegment } from "./bridge.ts";
 import { reducePruneRows, validatePruneRow, type PrunePlan, type PruneRow, type PruneSnapshot, type PruneSourceRow, type PruneStorePort } from "./prune.ts";
 import { PROMOTED_KINDS, type Entry } from "./store.ts";
 
@@ -89,33 +89,33 @@ export class GenerationIndex {
     if (!(db.query("PRAGMA table_info(generation_segments)").all() as { name: string }[]).some(row => row.name === "stamp")) db.run("ALTER TABLE generation_segments ADD COLUMN stamp TEXT");
     db.run("CREATE TABLE IF NOT EXISTS generation_state (key TEXT PRIMARY KEY, value TEXT NOT NULL)");
   }
-  private ownSegments(reader: SegmentReader = this.reader): LegacySegment[] {
+  private ownSegments(reader: SegmentReader = this.reader, full = this.fullCapture): LegacySegment[] {
     const prior = this.options.db.query("SELECT source,path,offset,hash,commit_id,stamp FROM generation_segments WHERE source='generation'").all() as (LegacyCheckpoint & { stamp: string | null })[];
     return ["log", "local"].flatMap(folder => {
       const dir = join(this.profile.dir, folder);
       if (lstatSync(dir).isSymbolicLink() || !lstatSync(dir).isDirectory()) return fail();
-      return readdirSync(dir).sort().filter(name => name.endsWith(".jsonl")).map(name => {
+      return reader.listFiles(dir).filter(name => name.endsWith(".jsonl")).map(name => {
         if (!/^[A-Za-z0-9][A-Za-z0-9._-]*\.jsonl$/.test(name)) return fail();
         const path = `${folder}/${name}`, checkpoint = prior.find(row => row.path === path);
-        const data = reader.read(join(dir, name), checkpoint ? { ...checkpoint, stamp: checkpoint.stamp ?? undefined } : undefined, this.fullCapture);
+        const data = reader.read(join(dir, name), checkpoint ? { ...checkpoint, stamp: checkpoint.stamp ?? undefined } : undefined, full);
         return { ...data, source: "generation", path, local: folder === "local" };
       });
     });
   }
   /** Authoring handles cannot read or append a partially resumed split; migration index bootstraps use captured limits. */
-  private shardFrontier(): string | undefined {
+  private shardFrontier(readOnly = false): string | undefined {
     if (!this.profile.sharded || this.options.limits !== undefined) return undefined;
-    for (let attempt = 0; attempt < 6; attempt++) {
-      rebindPublicPruneProfile(this.profile);
+    for (let attempt = 0; attempt < (readOnly ? 1 : 6); attempt++) {
+      if (!readOnly) rebindPublicPruneProfile(this.profile);
       const value = readProfileJSON(join(this.profile.home, "shards.json")) as { schema?: unknown; phase?: unknown; generation?: unknown; selectorRevision?: unknown } | undefined;
       if (selectorRevision(this.profile.home) !== this.profile.selectorRevision) { if (this.profile.foreignPruneFormat) continue; return fail(); }
-      if (!value || value.schema !== (this.profile.foreignPruneFormat ? SHARDED_V2_SCHEMA : SHARDED_SCHEMA) || value.phase !== "active" || value.generation !== this.profile.generation || value.selectorRevision !== this.profile.selectorRevision) return fail();
+      if (!value || value.schema !== (this.profile.publicationFormat ? "agent-mem.shards/v3" : this.profile.foreignPruneFormat ? SHARDED_V2_SCHEMA : SHARDED_SCHEMA) || value.phase !== "active" || value.generation !== this.profile.generation || value.selectorRevision !== this.profile.selectorRevision) return fail();
       return hashJSON(value);
     }
     return fail();
   }
-  private capture(reader: SegmentReader = this.reader): { segments: LegacySegment[]; commit?: string } {
-    const shardBefore = this.shardFrontier();
+  private capture(reader: SegmentReader = this.reader, readOnly = false): { segments: LegacySegment[]; commit?: string } {
+    const shardBefore = this.shardFrontier(readOnly), full = this.fullCapture || readOnly;
     const db = this.options.db;
     const previous = db.query("SELECT source,path,offset,hash,commit_id,stamp FROM generation_segments WHERE source != 'generation'").all() as (LegacyCheckpoint & { commit_id: string | null; stamp: string | null })[];
     const initial = readProfileJSON(join(this.profile.dir, "migration-sources.json")) as { sources?: LegacyCheckpoint[]; legacyCommit?: string } | undefined;
@@ -124,19 +124,23 @@ export class GenerationIndex {
     const checkpoints = [...bySource.values()];
     const persisted = new Set(previous.map(row => `${row.source}:${row.path}`));
     const completeFrontier = checkpoints.every(row => persisted.has(`${row.source}:${row.path}`));
-    const prior = (db.query("SELECT value FROM generation_state WHERE key='legacyCommit'").get() as { value: string } | null)?.value ?? initial?.legacyCommit;
+    const indexedCommit = (db.query("SELECT value FROM generation_state WHERE key='legacyCommit'").get() as { value: string } | null)?.value;
+    const prior = indexedCommit ?? initial?.legacyCommit;
     const legacyHome = this.profile.legacyHome ?? this.profile.home;
     const generation = this.profile.sharded ? undefined : this.profile.generation;
-    const commit = this.options.commit ?? (generation ? legacyHead(legacyHome, generation) : undefined);
+    const commit = this.options.commit ?? (generation ? legacyHead(legacyHome, generation, readOnly ? reader.sourceByteLimit : undefined, readOnly ? reader.sourceFileLimit : undefined) : undefined);
+    // ponytail: read-only inspection accepts the indexed archived frontier only, without an ancestry walk.
+    // Reopen after ordinary refresh, or add a bounded read-only ancestry witness to support a newer frontier.
+    if (readOnly && (commit !== indexedCommit || checkpoints.some(row => row.source === "legacy-main" && row.commit !== commit))) return fail();
     const legacy = this.profile.sharded
-      ? readShardLegacySnapshot(this.profile, { checkpoints, ...(this.options.limits ? { limits: this.options.limits } : {}), reader, incremental: !this.fullCapture && !this.options.limits && completeFrontier })
-      : readLegacySnapshot(legacyHome, { ...(generation ? { generation } : {}), ...(commit ? { commit } : {}), checkpoints, ...(generation && prior ? { previousCommit: prior } : {}), ...(this.options.limits ? { limits: this.options.limits } : {}), reader, incremental: !this.fullCapture && !this.options.limits && completeFrontier });
-    const own = this.ownSegments(reader);
+      ? readShardLegacySnapshot(this.profile, { checkpoints, ...(this.options.limits ? { limits: this.options.limits } : {}), reader, incremental: !full && !this.options.limits && completeFrontier })
+      : readLegacySnapshot(legacyHome, { ...(generation ? { generation } : {}), ...(commit ? { commit } : {}), checkpoints, ...(generation && prior ? { previousCommit: prior } : {}), ...(this.options.limits ? { limits: this.options.limits } : {}), reader, incremental: !full && !this.options.limits && completeFrontier });
+    const own = this.ownSegments(reader, full);
     for (const old of db.query("SELECT path,offset,hash FROM generation_segments WHERE source='generation'").all() as { path: string; offset: number; hash: string }[]) {
       const segment = own.find(s => s.path === old.path);
       if (!segment || segment.offset < old.offset) fail();
     }
-    if (this.shardFrontier() !== shardBefore) { if (this.profile.foreignPruneFormat) throw new PublicPruneViewChanged(); return fail(); }
+    if (this.shardFrontier(readOnly) !== shardBefore) { if (this.profile.foreignPruneFormat) throw new PublicPruneViewChanged(); return fail(); }
     return { segments: [...legacy, ...own], ...(commit ? { commit } : {}) };
   }
   private index(captured: { segments: LegacySegment[]; commit?: string }): void {
@@ -193,7 +197,7 @@ export class GenerationIndex {
       return;
     }
     if (!this.foreignCache || this.foreignCache.set !== set) this.foreignCache = { set, load: createPublicPruneReplayCache({ dir: profile.dir,
-      realm: profile.shardUser ? { scope: "user" } : { scope: "project", key: profile.shardKey! }, receivingGeneration: profile.generation, inputSetHash: set }) };
+      realm: profile.shardUser ? { scope: "user" } : { scope: "project", key: profile.shardKey! }, receivingGeneration: profile.generation, inputSetHash: set, ...(profile.publicationFormat ? {publicationFormat:profile.publicationFormat} : {}) }) };
     const proof = this.foreignCache.load();
     if (validateRows || this.foreignStamp !== set) for (const item of db.query("SELECT id,line FROM generation_rows").all() as {id:string;line:string}[]) {
       const expected = proof.rowHashes.get(item.id); if (expected && hashJSON(JSON.parse(item.line)) !== expected) return fail();
@@ -253,6 +257,79 @@ export class GenerationIndex {
     this.replayProvenance = false;
     this.retainedTail = input.segments.some(segment => segment.tailBytes > 0);
   }
+  /** Inspect canonical outbound sources without refreshing/rebinding the derived index.
+   * The returned check must run before the caller declares the whole opened-target inspection complete.
+   * Each capture accepts <=8MiB source bytes, <=20000 physical nonblank rows and <=16MiB segment reads.
+   * A fresh final capture verifies the same source again (<=32MiB segment verification I/O over both captures).
+   */
+  inspectOutboundRows(visit: (row: Record<string, unknown>) => void, limits: { maxBytes: number; maxRows: number }): () => void {
+    const unavailable = (budget = false): never => { throw Object.assign(new Error("outbound generation input unavailable"), { code: budget ? "input-bound" : "input-unavailable" }); };
+    if (!Number.isSafeInteger(limits.maxBytes) || limits.maxBytes < 0 || limits.maxBytes > 8 * 1024 * 1024
+      || !Number.isSafeInteger(limits.maxRows) || limits.maxRows < 0 || limits.maxRows > 20_000) return unavailable(true);
+    if (this.profile.kind !== "generation" || !this.profile.generation || this.options.limits !== undefined) return unavailable();
+    const profile = canonicalJSON(this.profile);
+    const stamp = (file: string): string | undefined => {
+      const stat = lstatSync(file, { bigint: true, throwIfNoEntry: false });
+      if (!stat) return undefined;
+      if (!stat.isFile() || stat.isSymbolicLink()) return fail();
+      return canonicalJSON([String(stat.dev), String(stat.ino), String(stat.size), String(stat.mtimeNs), String(stat.ctimeNs)]);
+    };
+    const epoch = (): string => {
+      if (canonicalJSON(this.profile) !== profile) return fail();
+      const selected = readSelector(this.profile.home);
+      if (selected.revision !== this.profile.selectorRevision || !this.profile.sharded && (selected.selector?.kind !== "generation" || selected.selector.generation !== this.profile.generation)) return fail();
+      const shards = this.shardFrontier(true);
+      if (!this.profile.sharded && readProfileJSON(join(this.profile.home, "shards.json")) !== undefined) return fail();
+      if (canonicalJSON(readProfileJSON(join(this.profile.dir, "generation.json"))) !== canonicalJSON(generationDescriptor(this.profile.generation!))) return fail();
+      const paths = [join(this.profile.home, "profile.json"), join(this.profile.home, "shards.json"), join(this.profile.dir, "generation.json"),
+        join(this.profile.dir, "migration-sources.json"), join(this.profile.dir, "project.json"), join(this.profile.legacyHome ?? this.profile.home, "machine.json"),
+        ...(this.profile.legacyMainHome ? [join(this.profile.legacyMainHome, "machine.json")] : [])];
+      return canonicalJSON({ shards, metadata: [...new Set(paths)].map(file => {
+        const before = stamp(file), value = readProfileJSON(file);
+        if (stamp(file) !== before) return fail();
+        return [file, before, hashJSON(value ?? null)];
+      }) });
+    };
+    const protectedRead = <T>(read: () => T): T => {
+      try { return read(); } catch (error) { return unavailable(error instanceof SegmentReadBudgetError); }
+    };
+    const before = protectedRead(epoch);
+    const capture = () => {
+      if (epoch() !== before) return fail();
+      const reader = new SegmentReader(2 * limits.maxBytes, { maxSourceBytes: limits.maxBytes, maxRows: limits.maxRows });
+      const input = this.capture(reader, true);
+      if (input.segments.some(segment => segment.tailBytes !== 0) || epoch() !== before) return fail();
+      const identity = canonicalJSON({ commit: input.commit, segments: input.segments.map(({ bytes: _bytes, local, ...segment }) => ({ ...segment, local })), metrics: reader.inspectionMetrics() });
+      return { input, identity };
+    };
+    const captured = protectedRead(capture);
+    const rows = protectedRead(() => {
+      const rows = new Map<string, PruneSourceRow>();
+      for (const segment of captured.input.segments) for (const bytes of completeLines(segment.bytes)) {
+        if (!bytes.length) continue;
+        const line = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+        if (!line.trim()) { if (segment.source === "generation") return fail(); continue; }
+        const parsed: unknown = JSON.parse(line);
+        const op = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? (parsed as { op?: unknown }).op : undefined;
+        if (segment.source === "generation" && op === "prune") {
+          const row = validatePruneRow(parsed, this.profile.generation!, segment.local ? "local" : "synced");
+          if (segment.path !== `${segment.local ? "local" : "log"}/${row.machine}.jsonl`) return fail();
+          continue;
+        }
+        if (segment.source === "generation" && op === "vault_link") {
+          const row = validateVaultLinkRow(parsed, this.profile.generation!, segment.local ? "local" : "synced");
+          if (segment.path !== `local/${row.machine}.jsonl`) return fail();
+          continue;
+        }
+        const row = checkedEntry(parsed);
+        rows.set(row.id, coalesceGenerationSource(rows.get(row.id), row, segment));
+      }
+      return [...rows.values()].filter(row => row.placement === "synced" && (row.own || row.legacy)).sort((left, right) => left.row.id.localeCompare(right.row.id));
+    });
+    for (const source of rows) visit(structuredClone(source.row) as unknown as Record<string, unknown>);
+    return () => { protectedRead(() => { if (capture().identity !== captured.identity) return fail(); }); };
+  }
+
   vaultWitnesses(ids: readonly string[]): Map<string, string> {
     if (ids.length > 5000) throw new Error("vault scan budget exceeded");
     return new Map((this.options.db.query("SELECT id,line FROM generation_rows WHERE id IN (SELECT value FROM json_each(?))").all(JSON.stringify(ids)) as { id: string; line: string }[])

package/src/memory/generation-sync.ts

@@ -1,3 +1,4 @@
+import { placementRuntimeRefusal } from "./sync-placement-guard.ts";
 import { randomBytes } from "node:crypto";
 import { closeSync, existsSync, lstatSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
@@ -74,6 +75,8 @@ function validatePublic(bytes: string, generation: string, path: string, checkPr
 
 /** Separate generation repository, fixed refs and a one-way legacy cache; failures are bounded result receipts. */
 export async function syncGenerationMemory(store: MemoryStore, opts: SyncOptions = {}): Promise<SyncResult> {
+  const placementRefusal = placementRuntimeRefusal(store.profile.home, store.profile);
+  if (placementRefusal) return { ok: false, pushed: false, entries: 0, error: placementRefusal };
   let pushed = false, releaseMutation: (() => void) | undefined, releaseSync: (() => void) | undefined;
   const result = (error: string): SyncResult => ({ ok: false, pushed, entries: 0, error });
   const profile = store.profile, generation = profile.generation, dir = store.dir;

package/src/memory/generation.ts

@@ -1,3 +1,5 @@
+import { validatePlacementProfile, type PlacementProfile } from "./sync-placement-format.ts";
+import { placementSelectorRefusal, SyncPlacementRuntimeError } from "./sync-placement-guard.ts";
 import { assertNoPublicPruneIntent, readPublicPruneView, waitForPublicPruneWriter, PUBLIC_PRUNE_INTENT } from "./public-prune-view.ts";
 import { createHash, randomBytes } from "node:crypto";
 import { types } from "node:util";
@@ -23,12 +25,15 @@ export interface BoundProfile {
   /** Public legacy witnesses stay distinct from same-machine private bridge input. */
   legacyMainHome?: string;
   sharded?: boolean;
+  publicationFormat?: "agent-mem.sync-placement/v1";
+  placementHead?: string;
   shardKey?: string;
   shardUser?: boolean;
 }
 export type ProfileInput = "shared-v1" | { generation: string };
 export type ProfileSelector = { schema: "agent-mem.profile/v1"; kind: "shared-v1" | "generation"; generation?: string }
-  | { schema: "agent-mem.profile/v2"; kind: "generation"; generation: string; foreignPruneFormat: "agent-mem.public-prune-witness/v1"; pruneInputSetHash: string };
+  | { schema: "agent-mem.profile/v2"; kind: "generation"; generation: string; foreignPruneFormat: "agent-mem.public-prune-witness/v1"; pruneInputSetHash: string }
+  | PlacementProfile;
 export interface GenerationDescriptor { schema: "agent-mem.generation/v1"; generation: string; legacySchema: "agent-hub.memory/v1" }
 export interface GenerationSeal { schema: "agent-mem.generation-seal/v1"; generation: string; descriptorHash: string; sourceDigest: string }
 export const PROFILE_LOCK_TIMEOUT_MS = 3000;
@@ -51,23 +56,33 @@ export function readProfileJSON(path: string, limit = LOCAL_METADATA_MAX_BYTES):
   } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined; return unavailable(); }
 }
 function keys(value: object, allowed: string[]): boolean { return Object.keys(value).every(key => allowed.includes(key)); }
+/** Pure legacy marker shape, shared with the stage1 placement preflight; no selector effects. */
+export function legacyProfileMarkerShape(value: unknown): value is ProfileSelector | undefined {
+  if (value === undefined) return true;
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const selector = value as ProfileSelector;
+  if (selector.schema === "agent-mem.profile/v2") return Object.keys(selector).length === 5 && keys(selector, ["schema", "kind", "generation", "foreignPruneFormat", "pruneInputSetHash"])
+    && selector.kind === "generation" && validGeneration(selector.generation) && selector.generation.length === 32 && selector.foreignPruneFormat === "agent-mem.public-prune-witness/v1"
+    && typeof selector.pruneInputSetHash === "string" && selector.pruneInputSetHash.length === 64 && /^[a-f0-9]{64}$/.test(selector.pruneInputSetHash);
+  return selector.schema === "agent-mem.profile/v1" && keys(selector, ["schema", "kind", "generation"])
+    && ["shared-v1", "generation"].includes(selector.kind) && (selector.kind === "generation" ? validGeneration(selector.generation) : selector.generation === undefined);
+}
 function selectorSnapshot(memoryDir: string, deadline: number): { selector?: ProfileSelector; revision: string } {
+  const initialRefusal = placementSelectorRefusal(memoryDir);
+  if (initialRefusal) throw new SyncPlacementRuntimeError(initialRefusal);
   assertNoPublicPruneIntent(memoryDir, deadline);
+  // Legacy v2 readers still choose their snapshot after the existing writer wait, never its earlier preflight pair.
+  const refusal = placementSelectorRefusal(memoryDir);
+  if (refusal) throw new SyncPlacementRuntimeError(refusal);
   const value = readProfileJSON(join(memoryDir, "profile.json"));
   if (value === undefined) return { revision: "absent" };
-  if (!value || typeof value !== "object" || Array.isArray(value)) return unavailable();
-  const selector = value as ProfileSelector;
-  if (selector.schema === "agent-mem.profile/v2") {
-    if (Object.keys(selector).length !== 5 || !keys(selector, ["schema", "kind", "generation", "foreignPruneFormat", "pruneInputSetHash"])
-      || selector.kind !== "generation" || !validGeneration(selector.generation) || selector.generation.length !== 32
-      || selector.foreignPruneFormat !== "agent-mem.public-prune-witness/v1" || typeof selector.pruneInputSetHash !== "string"
-      || selector.pruneInputSetHash.length !== 64 || !/^[a-f0-9]+$/.test(selector.pruneInputSetHash)) return unavailable();
+  const selector: ProfileSelector = (value as {schema?:unknown})?.schema === "agent-mem.profile/v3"
+    ? validatePlacementProfile(value) : legacyProfileMarkerShape(value) ? value! : unavailable();
+  if (selector.schema === "agent-mem.profile/v2" || selector.schema === "agent-mem.profile/v3") {
     const shard = readProfileJSON(join(memoryDir, "shards.json")) as Record<string, unknown> | undefined;
-    if (!shard || shard.schema !== "agent-mem.shards/v2" || shard.phase !== "active" || shard.generation !== selector.generation || shard.selectorRevision !== hashJSON(selector)) return unavailable();
+    if (!shard || shard.schema !== (selector.schema === "agent-mem.profile/v3" ? "agent-mem.shards/v3" : "agent-mem.shards/v2") || shard.phase !== "active" || shard.generation !== selector.generation || shard.selectorRevision !== hashJSON(selector)) return unavailable();
     readPublicPruneView(memoryDir, selector.pruneInputSetHash, selector.generation, deadline);
-  } else if (selector.schema !== "agent-mem.profile/v1" || !keys(selector, ["schema", "kind", "generation"])
-    || !["shared-v1", "generation"].includes(selector.kind) || (selector.kind === "generation" ? !validGeneration(selector.generation) : selector.generation !== undefined)) return unavailable();
-  else if ((readProfileJSON(join(memoryDir, "shards.json")) as {schema?:unknown}|undefined)?.schema === "agent-mem.shards/v2") return unavailable();
+  } else if ((readProfileJSON(join(memoryDir, "shards.json")) as {schema?:unknown}|undefined)?.schema === "agent-mem.shards/v2") return unavailable();
   return { selector, revision: hashJSON(selector) };
 }
 
@@ -81,6 +96,7 @@ export function readSelector(memoryDir: string, absoluteDeadline?: number): { se
       const current = readProfileJSON(join(memoryDir, "profile.json"));
       if (result.revision === (current === undefined ? "absent" : hashJSON(current))) return result;
     } catch (error) {
+      if (error instanceof SyncPlacementRuntimeError) throw error;
       if (error instanceof Error && error.message === "public prune view unavailable") throw error; // A spent wait budget is never restarted.
       if (!lstatSync(join(memoryDir, PUBLIC_PRUNE_INTENT), { throwIfNoEntry: false }) && !lstatSync(join(memoryDir, "profile.lock"), { throwIfNoEntry: false })) throw error;
       waitForPublicPruneWriter(memoryDir, deadline);
@@ -97,8 +113,10 @@ export function rebindPublicPruneProfile(profile: BoundProfile): void {
   for (let attempt = 0; attempt < 6; attempt++) {
     const current = readSelector(profile.home), selector = current.selector;
     if (current.revision === profile.selectorRevision) return;
+    if (selector?.schema !== "agent-mem.profile/v2" && selector?.schema !== "agent-mem.profile/v3") return unavailable();
     if (!profile.sharded || profile.kind !== "generation" || !profile.generation || !profile.pruneInputSetHash
-      || selector?.schema !== "agent-mem.profile/v2" || selector.generation !== profile.generation || selector.foreignPruneFormat !== profile.foreignPruneFormat) return unavailable();
+      || (profile.publicationFormat ? selector.schema !== "agent-mem.profile/v3" || selector.publicationFormat !== profile.publicationFormat || selector.placementHead !== profile.placementHead : selector.schema !== "agent-mem.profile/v2")
+      || selector.generation !== profile.generation || selector.foreignPruneFormat !== profile.foreignPruneFormat) return unavailable();
     const previous = readPublicPruneView(profile.home, profile.pruneInputSetHash, profile.generation);
     const next = readPublicPruneView(profile.home, selector.pruneInputSetHash, profile.generation);
     if (!Object.keys(previous.realms).every(key => Object.hasOwn(next.realms, key))) return unavailable();
@@ -143,9 +161,9 @@ export function validateGeneration(memoryDir: string, generation: string): strin
 export function resolveProfile(memoryDir: string, explicit?: ProfileInput): BoundProfile {
   const home = existsSync(memoryDir) ? realPath(memoryDir) : canonicalPath(memoryDir), selected = readSelector(home);
   if (explicit !== undefined && explicit !== "shared-v1" && (!explicit || typeof explicit !== "object" || !keys(explicit, ["generation"]) || !validGeneration(explicit.generation))) return unavailable();
-  if (selected.selector?.schema === "agent-mem.profile/v2" && explicit !== undefined) return unavailable();
+  if ((selected.selector?.schema === "agent-mem.profile/v2" || selected.selector?.schema === "agent-mem.profile/v3") && explicit !== undefined) return unavailable();
   const generation = explicit === "shared-v1" ? undefined : explicit?.generation ?? (selected.selector?.kind === "generation" ? selected.selector.generation : undefined);
-  return generation ? { kind: "generation", home, dir: validateGeneration(home, generation), generation, selectorRevision: selected.revision, ...(selected.selector?.schema === "agent-mem.profile/v2" ? { foreignPruneFormat: selected.selector.foreignPruneFormat, pruneInputSetHash: selected.selector.pruneInputSetHash } : {}) }
+  return generation ? { kind: "generation", home, dir: validateGeneration(home, generation), generation, selectorRevision: selected.revision, ...((selected.selector?.schema === "agent-mem.profile/v2" || selected.selector?.schema === "agent-mem.profile/v3") ? { foreignPruneFormat: selected.selector.foreignPruneFormat, pruneInputSetHash: selected.selector.pruneInputSetHash, ...(selected.selector.schema === "agent-mem.profile/v3" ? { publicationFormat: selected.selector.publicationFormat, placementHead: selected.selector.placementHead } : {}) } : {}) }
     : { kind: "shared-v1", home, dir: home, selectorRevision: selected.revision };
 }
 

package/src/memory/platform.ts

@@ -1,7 +1,7 @@
 // Single-source platform helpers. Hub, local and Pi modules re-export these functions unchanged.
 import { realpathSync } from "node:fs";
 import { basename, dirname, join, resolve, sep } from "node:path";
-import type { SpawnSyncOptionsWithStringEncoding, SpawnSyncReturns } from "node:child_process";
+import type { SpawnSyncOptions, SpawnSyncOptionsWithBufferEncoding, SpawnSyncOptionsWithStringEncoding, SpawnSyncReturns } from "node:child_process";
 import { createRequire } from "node:module";
 const require = createRequire(import.meta.url);
 let processes: typeof import("node:child_process") | undefined;
@@ -91,8 +91,14 @@ export const memoryGitArgv = (args: string[], opts: { credentials?: boolean } =
   ["git", "--no-pager", ...SAFE_CONFIG.filter((c) => !opts.credentials || !CREDENTIAL_KEYS.has(c)).flatMap((c) => ["-c", c]), ...args];
 
 /** The caller's env plus the no-prompt switch; existing keys (childEnv, GIT_OPTIONAL_LOCKS=0) pass through. */
-export function memoryGitEnv(env: NodeJS.ProcessEnv = process.env, options: { repositoryIsolation?: boolean } = {}): NodeJS.ProcessEnv {
+export function memoryGitEnv(env: NodeJS.ProcessEnv = process.env, options: { repositoryIsolation?: boolean; readOnlyDiagnostic?: boolean } = {}): NodeJS.ProcessEnv {
   const result: NodeJS.ProcessEnv = { ...env, GIT_TERMINAL_PROMPT: "0" };
+  if (options.readOnlyDiagnostic) {
+    // Fixed diagnostic commands must not inherit tracing/test/config switches that can write or lazily fetch.
+    // This is an environment projection, not permission to execute arbitrary Git commands.
+    for (const key of Object.keys(result)) if (key.startsWith("GIT_")) delete result[key];
+    Object.assign(result, { GIT_TERMINAL_PROMPT: "0", GIT_NO_LAZY_FETCH: "1", GIT_OPTIONAL_LOCKS: "0", GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: "/dev/null" });
+  }
   if (options.repositoryIsolation) {
     for (const key of Object.keys(result)) if (["GIT_DIR", "GIT_COMMON_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE", "GIT_OBJECT_DIRECTORY", "GIT_ALTERNATE_OBJECT_DIRECTORIES", "GIT_NAMESPACE", "GIT_PREFIX", "GIT_SHALLOW_FILE", "GIT_GRAFT_FILE", "GIT_REPLACE_REF_BASE", "GIT_CONFIG_COUNT", "GIT_CONFIG_PARAMETERS"].includes(key) || /^GIT_CONFIG_(KEY|VALUE)_/.test(key)) delete result[key];
     result.GIT_NO_REPLACE_OBJECTS = "1";
@@ -101,7 +107,9 @@ export function memoryGitEnv(env: NodeJS.ProcessEnv = process.env, options: { re
 }
 
 /** spawnSync form of the same call: the env option is merged with memoryGitEnv, everything else passes through. */
-export function memoryGitSync(args: string[], options: SpawnSyncOptionsWithStringEncoding): SpawnSyncReturns<string> {
+export function memoryGitSync(args: string[], options: SpawnSyncOptionsWithStringEncoding): SpawnSyncReturns<string>;
+export function memoryGitSync(args: string[], options: SpawnSyncOptionsWithBufferEncoding): SpawnSyncReturns<Buffer>;
+export function memoryGitSync(args: string[], options: SpawnSyncOptions): SpawnSyncReturns<string | Buffer> {
   const argv = memoryGitArgv(args);
   const timeout = gitTimeoutContext?.getStore();
   return childProcess().spawnSync(argv[0]!, argv.slice(1), { ...(timeout !== undefined ? { timeout, killSignal: "SIGKILL" as const } : {}), ...options, env: memoryGitEnv(options.env ?? process.env) });
@@ -134,8 +142,35 @@ export function processSignature(pid: number): string | undefined {
   } catch { return undefined; }
 }
 
+/** Nonblocking counterpart of the exact same pinned ps identity contract, for request-serving hosts. */
+function processFieldAsync(pid: number, fields: string): Promise<string | undefined> {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return Promise.resolve(undefined);
+  return new Promise(resolve => {
+    try {
+      childProcess().execFile("ps", ["-p", String(pid), "-o", fields], { encoding: "utf8", timeout: 500, killSignal: "SIGKILL", maxBuffer: 16 * 1024,
+        env: { ...process.env, LC_ALL: "C", TZ: "UTC" } }, (error, text) => resolve(error ? undefined : text.trim() || undefined));
+    } catch { resolve(undefined); }
+  });
+}
+export async function processSignatureAsync(pid: number): Promise<string | undefined> {
+  const text = await processFieldAsync(pid, "lstart=,comm=");
+  return text ? createHash("sha256").update(text).digest("hex") : undefined;
+}
+export async function processGroupIdAsync(pid: number): Promise<number | undefined> {
+  const text = await processFieldAsync(pid, "pgid=");
+  const group = text && /^[0-9]+$/.test(text) ? Number(text) : undefined;
+  return group !== undefined && Number.isSafeInteger(group) && group > 0 ? group : undefined;
+}
+
 export type Liveness = "live" | "gone" | "unknown";
 
+/** Observation only, never authority to signal an old group. Zombies/unreadable groups are not gone. */
+export function processGroupLiveness(group: unknown): Liveness {
+  if (typeof group !== "number" || !Number.isSafeInteger(group) || group <= 0) return "unknown";
+  try { process.kill(-group, 0); return "live"; }
+  catch (error) { return (error as NodeJS.ErrnoException).code === "ESRCH" ? "gone" : "unknown"; }
+}
+
 /**
  * #226: the one ownership check behind every recorded pid (hub manifest, registry claim, recovery runner, manager
  * owner, launcher records). With a recorded `signature` the identity decides: equal is live, different is gone (the

package/src/memory/policy.ts

@@ -6,6 +6,7 @@ import { nodePath, pathCandidates } from "./project.ts";
 
 /** True means the complete value is public. Hosts may narrow, never replace, standalone policy. */
 export interface MemoryPolicy { screen(value: unknown): Promise<boolean> }
+export type StandalonePolicyDecline = "secret" | "personal-data" | "deny-path" | "private-or-invalid";
 /**
  * The standalone policy. `screenStandalone` is its own part only (secrets, default PII, configured PII patterns and deny paths) as a synchronous
  * answer, for callers that cannot await (the store's promotion screen); it never asks the host, so a caller with a host uses `screen`.
@@ -18,6 +19,11 @@ export interface StandalonePolicy extends MemoryPolicy {
    */
   declinesPersonal(text: string): boolean;
 }
+/** Additive inspection surface; existing StandalonePolicy implementations need no new method. */
+export interface InspectableStandalonePolicy extends StandalonePolicy {
+  /** Safe standalone classification only; no input, configured literal or host verdict is returned. */
+  inspectStandalone(value: unknown): { ok: true } | { ok: false; category: StandalonePolicyDecline };
+}
 export interface StandalonePolicyOptions {
   denyPaths?: readonly string[];
   /** Case-insensitive literal substrings, not executable regular expressions. */
@@ -153,7 +159,7 @@ function mayNeedPathCheck(text: string, probe: DefaultPathProbe | undefined, den
 }
 
 /** No filesystem, model, network or storage work occurs while constructing or screening this policy. */
-export function createStandalonePolicy(options: StandalonePolicyOptions = {}): StandalonePolicy {
+export function createStandalonePolicy(options: StandalonePolicyOptions = {}): InspectableStandalonePolicy {
   if (!options || typeof options !== "object" || types.isProxy(options) || Object.getPrototypeOf(options) !== Object.prototype || Object.getOwnPropertySymbols(options).length) throw new Error("invalid standalone policy options");
   const descriptors = Object.getOwnPropertyDescriptors(options);
   for (const [key, descriptor] of Object.entries(descriptors)) if (!["denyPaths", "piiPatterns", "host"].includes(key) || !("value" in descriptor)) throw new Error("invalid standalone policy options");
@@ -163,34 +169,34 @@ export function createStandalonePolicy(options: StandalonePolicyOptions = {}): S
   if (host !== undefined && (!host || typeof host.screen !== "function")) throw new Error("invalid host policy");
   // ponytail: retain at most 512 exact strings / 64 KiB per immutable policy configuration.
   // Evict the batch when full; a measured need for better hit rates can upgrade this to an LRU.
-  const textChecks = new Map<string, boolean>(); let textBytes = 0;
+  const textChecks = new Map<string, StandalonePolicyDecline | null>(); let textBytes = 0;
   let defaultDenyRevision = "";
   // ponytail: the negative probe supports at most 64 dense default entries and 256-character simple name sources.
   // Everything else falls back; extend the grammar only with differential proof, never an approximate verdict.
   let pathProbe: DefaultPathProbe | undefined;
   let defaultsWerePlain = false;
-  const publicText = (text: string): boolean => {
+  const textDecline = (text: string): StandalonePolicyDecline | null => {
     const cached = textChecks.get(text);
     if (cached !== undefined) return cached;
     const check = () => {
-      if (looksSecret(text)) return false;
+      if (looksSecret(text)) return "secret" as const;
       const unquoted = text.replace(/["']/g, "");
-      if (unquoted !== text && looksSecret(unquoted)) return false;
+      if (unquoted !== text && looksSecret(unquoted)) return "secret" as const;
       const normalized = fold(text);
-      if (defaultPii(normalized) || pii.some(pattern => normalized.includes(pattern))) return false;
-      if (!mayNeedPathCheck(normalized, pathProbe, deny)) return true;
+      if (defaultPii(normalized) || pii.some(pattern => normalized.includes(pattern))) return "personal-data" as const;
+      if (!mayNeedPathCheck(normalized, pathProbe, deny)) return null;
       const candidates = normalized.includes("/") || /\.[a-z]/.test(normalized) ? pathCandidates(normalized) : [];
       const paths = [normalized, nodePath(normalized), ...candidates, ...normalized.split(/[\s"'`(){}\[\],;:=<>]+/)];
-      return ![...new Set(paths)].some(path => path && isDenied(posix.normalize(path), deny));
+      return [...new Set(paths)].some(path => path && isDenied(posix.normalize(path), deny)) ? "deny-path" as const : null;
     };
-    const allowed = check(), bytes = Buffer.byteLength(text);
+    const category = check(), bytes = Buffer.byteLength(text);
     if (bytes <= 1024) {
       if (textChecks.size >= 512 || textBytes + bytes > 64 * 1024) { textChecks.clear(); textBytes = 0; }
-      textChecks.set(text, allowed); textBytes += bytes;
+      textChecks.set(text, category); textBytes += bytes;
     }
-    return allowed;
+    return category;
   };
-  const standalone = (value: unknown): { ok: boolean; value?: unknown } => {
+  const standalone = (value: unknown): { ok: true; value: unknown } | { ok: false; category: StandalonePolicyDecline } => {
     try {
       // The exported default lists can be tightened by a host between calls.
       // A getter can change behavior without changing its first serialized value: validate shape every time.
@@ -202,12 +208,15 @@ export function createStandalonePolicy(options: StandalonePolicyOptions = {}): S
       else if (changed || !defaultsWerePlain) pathProbe = defaultPathProbe();
       defaultsWerePlain = defaultsPlain;
       const complete = snapshot(value);
-      if (!complete) return { ok: false };
+      if (!complete) return { ok: false, category: "private-or-invalid" };
       // Only pure text checks are reused. Shape/bounds/private flags and the host's detached
       // snapshot are fresh on every call; no row or host verdict is cached.
-      for (const text of complete.texts) if (!publicText(text)) return { ok: false };
+      for (const text of complete.texts) {
+        const category = textDecline(text);
+        if (category !== null) return { ok: false, category };
+      }
       return { ok: true, value: complete.value };
-    } catch { return { ok: false }; }
+    } catch { return { ok: false, category: "private-or-invalid" }; }
   };
   const personal = (text: string): boolean => {
     const normalized = fold(text);
@@ -218,6 +227,10 @@ export function createStandalonePolicy(options: StandalonePolicyOptions = {}): S
   };
   return {
     screenStandalone: value => standalone(value).ok,
+    inspectStandalone: value => {
+      const result = standalone(value);
+      return result.ok ? { ok: true } : { ok: false, category: result.category };
+    },
     declinesPersonal: text => personal(text),
     async screen(value: unknown): Promise<boolean> {
       try {