@staix/agent-mem 0.20.2 → 0.21.0

package/src/memory/sync-policy-inspection.ts

@@ -0,0 +1,126 @@
+import { createHash } from "node:crypto";
+import { lstatSync } from "node:fs";
+import { types } from "node:util";
+import { join } from "node:path";
+import { SegmentReadBudgetError } from "./bridge.ts";
+import { DENY_NAMES, DENY_SEGMENTS } from "./platform.ts";
+import { memoryPolicySnapshot } from "./policy.ts";
+import { loadAmemConfig } from "./config.ts";
+import { canonicalJSON, readProfileJSON, selectorRevision } from "./generation.ts";
+import { assertFormatFloor } from "./formats.ts";
+import type { MemoryStore } from "./store.ts";
+import { shardSyncBinding } from "./sync-binding.ts";
+import { outboundPolicyEvaluator, visitOwnSegment, SYNC_SCREEN_MAX_BYTES, SYNC_SCREEN_MAX_ROWS, type RowScreen, type SyncPolicyCategory } from "./sync-screen.ts";
+
+export type { SyncPolicyCategory } from "./sync-screen.ts";
+export interface SyncPolicyInspectionOptions {
+  /** Narrows the machine policy, over the same canonical content projection as SyncOptions.screen. */
+  screen?: RowScreen;
+  /** Optional host epoch, as in SyncOptions.policyVersion. A change makes the inspection incomplete. */
+  policyVersion?: () => string;
+}
+export interface SyncPolicyDeclinedRow { id: string; categories: SyncPolicyCategory[] }
+export type SyncPolicyInspection = {
+  complete: true;
+  declined: SyncPolicyDeclinedRow[];
+  counts: { scanned: number; declined: number; byCategory: Record<SyncPolicyCategory, number> };
+  /** SHA-256 over the sorted complete declined IDs/categories, never over private content or policy patterns. */
+  fingerprint: string;
+} | { complete: false; reason: "input-unavailable" | "input-bound" | "input-changed" | "binding-changed" | "policy-unavailable" };
+
+const hash = (value: unknown) => createHash("sha256").update(canonicalJSON(value)).digest("hex");
+
+/** Bounded, read-only inspection of exactly the opened sync targets. No refresh, rebind, publication or transport. */
+export function inspectSyncPolicy(store: MemoryStore, options: SyncPolicyInspectionOptions = {}): SyncPolicyInspection {
+  let failure: Extract<SyncPolicyInspection, {complete: false}>["reason"] = "input-unavailable";
+  try {
+    assertFormatFloor(store.profile.home, "sync");
+    const targets = [...store.openedSyncTargets()];
+    const metadata = [...new Set([join(store.profile.home, "profile.json"), join(store.profile.home, "shards.json"), join(store.profile.home, "aliases.jsonl"), join(store.profile.home, "amem.config.json"), join(store.profile.home, "machine.json"), ...targets.flatMap(target => [join(target.dir, "machine.json"), join(target.dir, "project.json"), ...(target.profile.kind === "generation" ? [join(target.dir, "generation.json"), join(target.dir, "generation-seal.json"), join(target.dir, "migration-sources.json")] : [])])])];
+    const stamps = () => metadata.map(file => {
+      const stat = lstatSync(file, { bigint: true, throwIfNoEntry: false });
+      if (!stat) return "absent";
+      if (!stat.isFile() || stat.isSymbolicLink() || stat.size > BigInt(SYNC_SCREEN_MAX_BYTES)) throw new Error("metadata unavailable");
+      return [stat.dev, stat.ino, stat.size, stat.mtimeNs, stat.ctimeNs].map(String);
+    });
+    const binding = () => hash({
+      stamps: stamps(),
+      root: store.profile,
+      selector: selectorRevision(store.profile.home),
+      ...(store.profile.sharded ? { shards: shardSyncBinding(store) } : {}),
+      targets: targets.map(target => ({ profile: target.profile, machine: target.machine,
+        selector: selectorRevision(target.profile.home),
+        machineFile: readProfileJSON(join(target.dir, "machine.json"), 4096),
+        ...(target.profile.kind === "generation" ? {
+          generation: readProfileJSON(join(target.dir, "generation.json"), 4096),
+          seal: readProfileJSON(join(target.dir, "generation-seal.json")),
+        } : {}),
+      })),
+    });
+    // Stale handles are not silently rebound, including a monotone selector change supported by sync itself.
+    if (targets.some(target => selectorRevision(target.profile.home) !== target.profile.selectorRevision)) return { complete: false, reason: "binding-changed" };
+    if (targets.some(target => (readProfileJSON(join(target.dir, "machine.json"), 4096) as {id?: unknown} | undefined)?.id !== target.machine.id)) return { complete: false, reason: "binding-changed" };
+    const epoch = binding();
+    failure = "policy-unavailable";
+    const policyVersion = options.policyVersion?.();
+    if (options.policyVersion !== undefined && typeof policyVersion !== "string") throw new Error("host policy unavailable");
+    const defaults = () => {
+      const value = memoryPolicySnapshot({ names: DENY_NAMES, segments: DENY_SEGMENTS });
+      if (!value) throw new Error("policy unavailable");
+      return hash(value);
+    };
+    const defaultEpoch = defaults();
+    const policy = () => hash({ config: loadAmemConfig(store.profile.home).config, defaults: defaults() });
+    failure = "policy-unavailable";
+    const policyEpoch = policy(), evaluate = outboundPolicyEvaluator(store.profile.home, options.screen);
+    const assertCurrent = () => {
+      failure = "binding-changed";
+      if (binding() !== epoch || canonicalJSON(store.openedSyncTargets().map(target => [target.dir, target.machine.id])) !== canonicalJSON(targets.map(target => [target.dir, target.machine.id]))) throw new Error("binding changed");
+      failure = "policy-unavailable";
+      if (policy() !== policyEpoch || options.policyVersion?.() !== policyVersion) throw new Error("policy changed");
+    };
+    const ids = new Map<string, { hash: string; categories: Set<SyncPolicyCategory> }>();
+    let scanned = 0;
+    const visit = (row: Record<string, unknown>) => {
+      failure = "input-bound";
+      if (++scanned > SYNC_SCREEN_MAX_ROWS) throw new Error("row bound");
+      failure = "input-unavailable";
+      if (typeof row.id !== "string" || !/^[a-f0-9]{32}$/.test(row.id)) throw new Error("row id unavailable");
+      const rowHash = hash(row), prior = ids.get(row.id);
+      if (prior && prior.hash !== rowHash) throw new Error("row identity changed");
+      failure = "policy-unavailable";
+      if (defaults() !== defaultEpoch) throw new Error("default policy changed");
+      const verdict = evaluate(row);
+      if (defaults() !== defaultEpoch) throw new Error("default policy changed");
+      const item = prior ?? { hash: rowHash, categories: new Set<SyncPolicyCategory>() };
+      if (!verdict.ok) item.categories.add(verdict.category);
+      ids.set(row.id, item);
+      if (options.policyVersion?.() !== policyVersion) { failure = "policy-unavailable"; throw new Error("host policy changed"); }
+    };
+    const checks: (() => void)[] = [];
+    for (const target of targets) {
+      assertCurrent(); failure = "input-unavailable";
+      if (target.profile.kind === "generation") checks.push(target.inspectOutboundRows(visit, { maxBytes: SYNC_SCREEN_MAX_BYTES, maxRows: SYNC_SCREEN_MAX_ROWS }));
+      else checks.push(visitOwnSegment(target.dir, target.machine.id, visit));
+      assertCurrent();
+    }
+    for (const check of checks) { failure = "input-changed"; check(); }
+    assertCurrent();
+    const declined = [...ids].filter(([, item]) => item.categories.size > 0).sort(([a], [b]) => a.localeCompare(b))
+      .map(([id, item]) => ({ id, categories: [...item.categories].sort() }));
+    const byCategory: Record<SyncPolicyCategory, number> = { secret: 0, "personal-data": 0, "deny-path": 0, "private-or-invalid": 0, host: 0 };
+    for (const row of declined) for (const category of row.categories) byCategory[category]++;
+    return { complete: true, declined, counts: { scanned, declined: declined.length, byCategory }, fingerprint: hash(declined) };
+  } catch (error) {
+    let reason: Extract<SyncPolicyInspection, { complete: false }>["reason"] = failure;
+    // Caller errors are not trusted diagnostics: never read message, getters or proxy properties.
+    try {
+      if (error && typeof error === "object" && !types.isProxy(error)) {
+        const code = Object.getOwnPropertyDescriptor(error, "code")?.value;
+        if (["input-unavailable", "input-bound", "input-changed"].includes(code)) reason = code;
+        else if (error instanceof SegmentReadBudgetError) reason = "input-bound";
+      }
+    } catch { /* An exotic caller exception cannot escape as a data-bearing error. */ }
+    return { complete: false, reason };
+  }
+}

package/src/memory/sync-screen.ts

@@ -1,7 +1,12 @@
-import { closeSync, constants, fstatSync, openSync, readFileSync } from "node:fs";
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, type BigIntStats } from "node:fs";
+import { createHash } from "node:crypto";
+import { types } from "node:util";
 import { join } from "node:path";
+import { OP_CONTRACTS } from "./ops-contract.ts";
+import { SUGGESTED } from "./store.ts";
+import { checkedEntry } from "./bridge.ts";
 import { loadAmemConfig } from "./config.ts";
-import { createStandalonePolicy } from "./policy.ts";
+import { createStandalonePolicy, type StandalonePolicyDecline } from "./policy.ts";
 import type { MemoryStore } from "./store.ts";
 
 /**
@@ -19,7 +24,8 @@ import type { MemoryStore } from "./store.ts";
  * ponytail: a person clears a declined entry by removing the offending pattern or editing the policy; sync does not skip a row, and `amem forget` is an
  * append-only op that leaves the original row in the log. Upgrade: a per-row placement that keeps a declined note local without refusing the sync.
  */
-const MAX_BYTES = 8 * 1024 * 1024, MAX_ROWS = 20_000;
+export const SYNC_SCREEN_MAX_BYTES = 8 * 1024 * 1024, SYNC_SCREEN_MAX_ROWS = 20_000;
+const MAX_BYTES = SYNC_SCREEN_MAX_BYTES, MAX_ROWS = SYNC_SCREEN_MAX_ROWS;
 
 export type SyncScreen = { ok: true } | { ok: false; reason: string };
 
@@ -27,19 +33,55 @@ export type SyncScreen = { ok: true } | { ok: false; reason: string };
  * What a row says: everything except the fields the library itself generates (ids, hashes, times, the op and enum names, machine and actor ids). Left IN on purpose
  * are `project`, `peer`, `task`, `about`, `title`, `text`, `milestones` and any field this file has never heard of: an unknown text field must be screened, never skipped.
  */
-const GENERATED = new Set(["id", "schema", "op", "at", "machine", "actor", "target", "promotedFrom", "supersedes", "expires", "by", "tier", "scope", "kind", "source"]);
-function textOf(row: Record<string, unknown>): Record<string, unknown> {
-  const out: Record<string, unknown> = {};
-  for (const [key, value] of Object.entries(row)) if (!GENERATED.has(key)) out[key] = value;
+const GENERATED = new Set(["id", "schema", "op", "at", "machine", "actor", "promotedFrom", "supersedes", "expires", "tier", "scope", "kind", "source"]);
+/** Only a known operation's validated id/enum/time operand is generated metadata.
+ * A task key, an unknown operand field or an unsupported operand shape remains content. */
+function generatedOperand(operation: unknown, key: string, value: unknown): boolean {
+  if (key !== "target" && key !== "by" || typeof operation !== "string" || !Object.hasOwn(OP_CONTRACTS, operation)) return false;
+  const field = OP_CONTRACTS[operation]?.payloadSchema?.fields[key];
+  if (typeof value !== "string" || !field) return false;
+  if (field.format === "id") return /^[a-f0-9]{32}$/.test(value);
+  if (field.format === "utc") return Number.isFinite(Date.parse(value));
+  if (field.values) return field.values.includes(value);
+  // Suggestion operands are a closed relation enum plus an immutable entry id, not task text.
+  if (operation === "suggest" && key === "by") {
+    const match = /^([^:]+):[a-f0-9]{32}$/.exec(value);
+    return match !== null && (SUGGESTED as readonly string[]).includes(match[1]!);
+  }
+  return false;
+}
+
+export function syncOutboundContent(row: unknown): Record<string, unknown> {
+  if (!row || typeof row !== "object" || Array.isArray(row) || types.isProxy(row) || Object.getOwnPropertySymbols(row).length) throw new Error("outbound row unavailable");
+  const out: Record<string, unknown> = {}, descriptors = Object.getOwnPropertyDescriptors(row);
+  const operation = descriptors.op?.value;
+  for (const [key, descriptor] of Object.entries(descriptors)) {
+    if (GENERATED.has(key) || generatedOperand(operation, key, descriptor.value)) continue;
+    if (!("value" in descriptor) || !descriptor.enumerable) throw new Error("outbound row unavailable");
+    Object.defineProperty(out, key, { value: descriptor.value, enumerable: true, writable: true, configurable: true });
+  }
   return out;
 }
 
 /** A row passes when the machine's configured policy and the caller's extra screen (if any) both accept its text. */
 export type RowScreen = (row: Record<string, unknown>) => boolean;
-export function outboundScreen(home: string, extra?: RowScreen): RowScreen {
+export type SyncPolicyCategory = StandalonePolicyDecline | "host";
+export type OutboundVerdict = { ok: true } | { ok: false; category: SyncPolicyCategory };
+/** One evaluator for actual sync and public inspection, with the same projection and AND composition. */
+export function outboundPolicyEvaluator(home: string, extra?: RowScreen): (row: Record<string, unknown>) => OutboundVerdict {
   const { config } = loadAmemConfig(home);
   const policy = createStandalonePolicy({ denyPaths: config.denyPaths, piiPatterns: config.piiPatterns });
-  return row => { const text = textOf(row); return policy.screenStandalone(text) && (extra?.(text) ?? true); };
+  return row => {
+    const text = syncOutboundContent(row), own = policy.inspectStandalone(text);
+    if (!own.ok) return own;
+    const accepted = extra === undefined ? true : extra(text);
+    if (typeof accepted !== "boolean") throw new Error("outbound policy unavailable");
+    return accepted ? { ok: true } : { ok: false, category: "host" };
+  };
+}
+export function outboundScreen(home: string, extra?: RowScreen): RowScreen {
+  const evaluate = outboundPolicyEvaluator(home, extra);
+  return row => evaluate(row).ok;
 }
 const refusal = (declined: string[]): SyncScreen => declined.length ? { ok: false, reason: `the configured privacy policy declines ${declined.length} long-term entr${declined.length === 1 ? "y" : "ies"} (${declined.slice(0, 8).join(", ")}${declined.length > 8 ? ", ..." : ""}); fix the entry or the policy, then sync again` } : { ok: true };
 const idOf = (row: Record<string, unknown>) => typeof row.id === "string" ? row.id.slice(0, 8) : "(no id)";
@@ -48,39 +90,92 @@ const idOf = (row: Record<string, unknown>) => typeof row.id === "string" ? row.
 export function screenOutboundRows(store: MemoryStore, pass: RowScreen): SyncScreen {
   const declined: string[] = [];
   let rows = 0;
-  let snapshot: ReturnType<ReturnType<MemoryStore["prunePort"]>["snapshot"]>;
-  // A bootstrap-only handle has no snapshot: that is a refusal like any unreadable source, never an exception out of sync (which promises a result).
-  try { snapshot = store.prunePort().snapshot(); } catch { return { ok: false, reason: "this store's long-term rows cannot be read, so they were not screened" }; }
-  for (const source of snapshot.rows) {
-    if (source.placement !== "synced" || !(source.own || source.legacy)) continue;
-    if (++rows > MAX_ROWS) return { ok: false, reason: `more than ${MAX_ROWS} long-term rows, so they were not screened` };
-    if (!pass(source.row as unknown as Record<string, unknown>)) declined.push(idOf(source.row as unknown as Record<string, unknown>));
-  }
+  // Actual sync retains its existing canonical refresh/recovery snapshot. Public inspection uses the read-only
+  // source visitor instead, so it never performs this derived-state mutation or adopts a torn prune recovery tail.
+  try {
+    const snapshot = store.prunePort().snapshot();
+    for (const source of snapshot.rows) {
+      if (source.placement !== "synced" || !(source.own || source.legacy)) continue;
+      if (++rows > MAX_ROWS) return { ok: false, reason: `more than ${MAX_ROWS} long-term rows, so they were not screened` };
+      if (!pass(source.row as unknown as Record<string, unknown>)) declined.push(idOf(source.row as unknown as Record<string, unknown>));
+    }
+  } catch { return { ok: false, reason: "this store's long-term rows cannot be read, so they were not screened; inspect the local inputs and reopen the store before retrying" }; }
   return refusal(declined);
 }
 
-/** Screen one machine's own long-term segment under `dir`. */
-export function screenOwnSegment(dir: string, machineId: string, pass: RowScreen): SyncScreen {
-  const file = join(dir, "log", `${machineId}.jsonl`);
+export class SyncScreenInputError extends Error {
+  constructor(readonly code: "input-unavailable" | "input-bound" | "input-changed", readonly bound?: "bytes" | "rows") { super(code); }
+}
+const sameStat = (a: BigIntStats, b: BigIntStats) => a.dev === b.dev && a.ino === b.ino && a.size === b.size && a.mtimeNs === b.mtimeNs && a.ctimeNs === b.ctimeNs;
+
+/** One bounded physical segment. The returned check pins it across the other opened targets and host callbacks too. */
+export function visitOwnSegment(dir: string, machineId: string, visit: (row: Record<string, unknown>) => void): () => void {
+  const parent = join(dir, "log"), parentStat = lstatSync(parent, { bigint: true, throwIfNoEntry: false });
+  if (parentStat && (!parentStat.isDirectory() || parentStat.isSymbolicLink())) throw new SyncScreenInputError("input-unavailable");
+  const checkParent = () => {
+    const now = lstatSync(parent, { bigint: true, throwIfNoEntry: false });
+    if (parentStat ? !now || !now.isDirectory() || now.isSymbolicLink() || now.dev !== parentStat.dev || now.ino !== parentStat.ino : now !== undefined) throw new SyncScreenInputError("input-changed");
+  };
+  const file = join(parent, `${machineId}.jsonl`);
   let fd: number;
   try { fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); }
   catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") return { ok: true };   // nothing authored here: nothing to push
-    return { ok: false, reason: "this machine's long-term segment cannot be read, so it was not screened" };
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return () => {
+      checkParent();
+      if (lstatSync(file, { throwIfNoEntry: false })) throw new SyncScreenInputError("input-changed");
+    };
+    throw new SyncScreenInputError("input-unavailable");
   }
   try {
-    const stat = fstatSync(fd);
-    if (!stat.isFile() || stat.size > MAX_BYTES) return { ok: false, reason: `this machine's long-term segment is not a plain file within ${MAX_BYTES} bytes, so it was not screened` };
-    const declined: string[] = [];
-    let rows = 0;
-    for (const line of readFileSync(fd, "utf8").split("\n")) {
+    const stat = fstatSync(fd, { bigint: true });
+    if (!stat.isFile() || stat.nlink !== 1n) throw new SyncScreenInputError("input-unavailable");
+    if (stat.size > BigInt(MAX_BYTES)) throw new SyncScreenInputError("input-bound", "bytes");
+    const check = () => {
+      checkParent();
+      const named = lstatSync(file, { bigint: true });
+      if (!named.isFile() || named.isSymbolicLink() || !sameStat(stat, named)) throw new SyncScreenInputError("input-changed");
+    };
+    check();
+    // No whole-file string/split array: the stat bound precedes allocation; the row bound precedes parsing each row.
+    const bytes = Buffer.alloc(Number(stat.size));
+    let at = 0;
+    while (at < bytes.length) { const n = readSync(fd, bytes, at, bytes.length - at, at); if (!n) throw new SyncScreenInputError("input-changed"); at += n; }
+    if (bytes.length && bytes.at(-1) !== 10) throw new SyncScreenInputError("input-unavailable");
+    let start = 0, rows = 0;
+    const decoder = new TextDecoder("utf-8", { fatal: true });
+    for (let end = 0; end < bytes.length; end++) {
+      if (bytes[end] !== 10) continue;
+      if (start === end) { start = end + 1; continue; }
+      const line = decoder.decode(bytes.subarray(start, end)); start = end + 1;
       if (!line.trim()) continue;
-      if (++rows > MAX_ROWS) return { ok: false, reason: `more than ${MAX_ROWS} long-term rows, so they were not screened` };
-      let row: Record<string, unknown>;
-      try { row = JSON.parse(line) as Record<string, unknown>; } catch { return { ok: false, reason: "a line of this machine's long-term segment does not parse, so it was not screened" }; }
-      // Every row kind is read, not only notes: a goal's title and milestones sync too, and so does any text an op adds later (see `textOf`).
-      if (!pass(row)) declined.push(idOf(row));
+      if (++rows > MAX_ROWS) throw new SyncScreenInputError("input-bound", "rows");
+      let row: unknown;
+      try { row = checkedEntry(JSON.parse(line)); } catch { throw new SyncScreenInputError("input-unavailable"); }
+      visit(row as Record<string, unknown>);
     }
-    return refusal(declined);
+    const expected = createHash("sha256").update(bytes).digest("hex"), digest = createHash("sha256"), buffer = Buffer.alloc(65_536);
+    at = 0;
+    while (at < bytes.length) { const n = readSync(fd, buffer, 0, Math.min(buffer.length, bytes.length - at), at); if (!n) throw new SyncScreenInputError("input-changed"); digest.update(buffer.subarray(0, n)); at += n; }
+    if (expected !== digest.digest("hex") || !sameStat(stat, fstatSync(fd, { bigint: true }))) throw new SyncScreenInputError("input-changed");
+    check(); return check;
   } finally { closeSync(fd); }
 }
+
+/** Screen one machine's own long-term segment under `dir`, using the inspector's same bounded reader. */
+export function screenOwnSegment(dir: string, machineId: string, pass: RowScreen): SyncScreen {
+  const declined: string[] = [];
+  try { visitOwnSegment(dir, machineId, row => { if (!pass(row)) declined.push(idOf(row)); })(); }
+  catch (error) {
+    let code: unknown, bound: unknown;
+    if (error && typeof error === "object" && !types.isProxy(error)) {
+      code = Object.getOwnPropertyDescriptor(error, "code")?.value;
+      bound = Object.getOwnPropertyDescriptor(error, "bound")?.value;
+    }
+    const inspect = "; inspect the local input and reopen the store before retrying";
+    if (code === "input-bound" && bound === "rows") return { ok: false, reason: `more than ${MAX_ROWS} long-term rows, so they were not screened${inspect}` };
+    if (code === "input-bound" && bound === "bytes") return { ok: false, reason: `this machine's long-term segment exceeds ${MAX_BYTES} bytes, so it was not screened${inspect}` };
+    if (code === "input-changed") return { ok: false, reason: "this machine's long-term segment changed while being screened, so it was not screened; wait for writers to finish and retry" };
+    return { ok: false, reason: "this machine's long-term segment is not readable as complete valid rows, so it was not screened" + inspect };
+  }
+  return refusal(declined);
+}

package/src/memory/sync.ts

@@ -1,13 +1,16 @@
+import { syncPlacementMemory } from "./sync-placement-transport.ts";
+import type { PlacementCapturePort } from "./sync-placement-capture.ts";
+import { placementRuntimeRefusal } from "./sync-placement-guard.ts";
 import { assertFormatFloor } from "./formats.ts";
-import { closeSync, constants, existsSync, fstatSync, lstatSync, openSync, readFileSync, readSync, rmSync, writeFileSync, writeSync, type BigIntStats } from "node:fs";
-import { createHash } from "node:crypto";
-import { dirname, join, relative, sep } from "node:path";
+import { closeSync, constants, existsSync, openSync, readFileSync, rmSync, writeFileSync, writeSync } from "node:fs";
+import { join } from "node:path";
 import { rebindPublicPruneProfile } from "./generation.ts";
 import { memoryGitArgv, memoryGitEnv, processLiveness, processSignature } from "./platform.ts";
 import { acquireMutation } from "./mutation.ts";
 import type { MemoryStore } from "./store.ts";
 import { syncGenerationMemory } from "./generation-sync.ts";
 import { outboundScreen, screenOutboundRows, screenOwnSegment, type RowScreen } from "./sync-screen.ts";
+import { shardSyncBinding } from "./sync-binding.ts";
 
 /**
  * #258 phase 2: hub memory between a person's machines through a git remote they configure. The memory directory is a
@@ -16,6 +19,8 @@ import { outboundScreen, screenOutboundRows, screenOwnSegment, type RowScreen }
  */
 export type Visibility = "public" | "private" | "unknown";
 export interface SyncResult { ok: boolean; pushed: boolean; entries: number; warning?: string; error?: string;
+  placementPublication?: { attemptHash?: string; outcome: "committed" | "unknown" | "not-needed"; withheld: number; exported: number;
+    lastPolicyHash?: string; lastPolicyCheckUnixMs?: number; policyCheckSource?: "live" | "durable-intent"; policyCeiling: "last-positive-check-before-in-flight-push"; recovered?: boolean };
   pruneApplication?: {transport:"durable"|"unconfirmed";proofComplete:number;projectionActive:number|null;nativeApplied:number|null;held:number;phase:"preflight"|"prepared"|"active"|"complete"};
 }
 
@@ -214,6 +219,8 @@ function lock(dir: string): (() => void) | undefined {
 }
 
 export interface SyncOptions {
+  /** Fresh compatibility facts for an already activated v3 profile; never activates a legacy profile or bypasses policy. */
+  placementAttestation?: PlacementCapturePort["attest"];
   /** Set (or replace) the remote first: a person's choice. */
   remote?: string;
   visibility?: (url: string) => Promise<Visibility>;
@@ -225,67 +232,13 @@ export interface SyncOptions {
   signal?: AbortSignal;
 }
 
-/** Metadata-only sharded sync epoch. Hash complete source bytes, never notes or unopened shards. */
-export function shardSyncBinding(store: MemoryStore): string { return captureShardSyncBinding(store, true); }
-/** Selection bytes may change only after this sync commits; source/policy identity remains pinned across that commit. */
-export function shardSyncSourceBinding(store: MemoryStore): string { return captureShardSyncBinding(store, false); }
-function captureShardSyncBinding(store: MemoryStore, selection: boolean): string {
-  const unavailable = (): never => { throw new Error("sharded sync binding unavailable"); };
-  if (!store.profile.sharded) return unavailable();
-  const uid = process.getuid?.(); if (uid === undefined) return unavailable();
-  const same = (a: BigIntStats, b: BigIntStats) => a.dev === b.dev && a.ino === b.ino && a.size === b.size && a.mtimeNs === b.mtimeNs && a.ctimeNs === b.ctimeNs;
-  const owned = (stat: BigIntStats, directory: boolean, privateMode = true) => {
-    if (stat.isSymbolicLink() || (directory ? !stat.isDirectory() : !stat.isFile() || stat.nlink !== 1n)
-      || stat.uid !== BigInt(uid) || privateMode && (stat.mode & 0o077n) !== 0n) unavailable();
-  };
-  const home = store.profile.home, digest = createHash("sha256"), directories = new Map<string, BigIntStats>(), checks: (() => void)[] = [];
-  const emit = (value: unknown) => { digest.update(JSON.stringify(value) + "\n"); };
-  const directory = (dir: string): void => {
-    if (directories.has(dir)) return;
-    const rel = relative(home, dir); if (rel === ".." || rel.startsWith(".." + sep)) unavailable();
-    if (dir !== home) directory(dirname(dir));
-    const before = lstatSync(dir, { bigint: true }); owned(before, true); directories.set(dir, before);
-    emit(["directory", dir, String(before.dev), String(before.ino)]);
-    checks.push(() => { const now = lstatSync(dir, { bigint: true }); owned(now, true); if (!same(before, now)) unavailable(); });
-  };
-  // Policy config keeps its established file modes inside this already-private owned home. Its complete bytes/inode still bind the epoch.
-  const source = (file: string, privateMode = true): void => {
-    directory(dirname(file));
-    let before: BigIntStats;
-    try { before = lstatSync(file, { bigint: true }); }
-    catch (error) {
-      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
-      emit(["source", file, "absent"]);
-      checks.push(() => { if (lstatSync(file, { bigint: true, throwIfNoEntry: false }) !== undefined) unavailable(); }); return;
-    }
-    owned(before, false, privateMode);
-    const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
-    try {
-      const opened = fstatSync(fd, { bigint: true }); owned(opened, false, privateMode); if (!same(before, opened)) unavailable();
-      const content = createHash("sha256"), buffer = Buffer.allocUnsafe(65_536); let bytes = 0n;
-      for (;;) { const n = readSync(fd, buffer, 0, buffer.length, null); if (!n) break; content.update(buffer.subarray(0, n)); bytes += BigInt(n); }
-      const after = fstatSync(fd, { bigint: true }); owned(after, false, privateMode);
-      if (bytes !== before.size || !same(before, after) || !same(before, lstatSync(file, { bigint: true }))) unavailable();
-      emit(["source", file, "present", String(before.dev), String(before.ino), String(before.size), String(before.mtimeNs), String(before.ctimeNs), content.digest("hex")]);
-    } finally { closeSync(fd); }
-    checks.push(() => { const now = lstatSync(file, { bigint: true }); owned(now, false, privateMode); if (!same(before, now)) unavailable(); });
-  };
-  try {
-    directory(home);
-    for (const name of [...(selection ? ["profile.json", "shards.json"] : []), "aliases.jsonl", "amem.config.json", "machine.json"]) source(join(home, name), name !== "amem.config.json");
-    const targets = [...store.openedSyncTargets()].sort((a, b) => a.dir.localeCompare(b.dir));
-    for (const target of targets) {
-      directory(target.dir);
-      emit(["target", target.dir, target.profile.generation ?? null, target.machine.id, target.profile.shardUser ?? false, target.profile.shardKey ?? null]);
-      for (const name of ["project.json", "generation.json", "generation-seal.json", "machine.json"]) source(join(target.dir, name));
-    }
-    for (const check of checks) check();
-    return digest.digest("hex");
-  } catch { return unavailable(); }
-}
+export { shardSyncBinding, shardSyncSourceBinding } from "./sync-binding.ts";
 
 export async function syncMemory(store: MemoryStore, opts: SyncOptions = {}): Promise<SyncResult> {
   assertFormatFloor(store.profile.home, "sync");
+  const placementRefusal = placementRuntimeRefusal(store.profile.home, store.profile);
+  if (placementRefusal) return { ok: false, pushed: false, entries: 0, error: placementRefusal };
+  if (store.profile.publicationFormat === "agent-mem.sync-placement/v1") return syncPlacementMemory(store, opts);
   if (store.profile.sharded) {
     try {
       // Refresh only through the existing proved monotone profile rebind before pinning this attempt.
@@ -297,20 +250,23 @@ export async function syncMemory(store: MemoryStore, opts: SyncOptions = {}): Pr
       assertBinding();
       const screen = outboundScreen(store.profile.home, opts.screen);
       const pass: RowScreen = row => { assertBinding(); const accepted = screen(row); assertBinding(); if (typeof accepted !== "boolean") throw new Error("invalid screen result"); return accepted; };
+      const errors: string[] = [];
       for (const target of store.openedSyncTargets()) {
         const screened = screenOutboundRows(target, pass); assertBinding();
-        if (!screened.ok) return { ok: false, pushed: false, entries: 0, error: screened.reason };
+        if (!screened.ok) errors.push(screened.reason);
       }
+      if (errors.length) return { ok: false, pushed: false, entries: 0, error: errors.join("; ") };
       const transport = await import("./shard-sync.ts"); assertBinding();
       return transport.syncShardedMemory(store, opts);
     } catch { return { ok: false, pushed: false, entries: 0, error: "sharded sync binding or policy unavailable or changed" }; }
   }
   // F4: before anything is staged or pushed, this machine's own long-term notes pass the person's configured policy (every profile: single log, generation, shards).
-  const pass = outboundScreen(store.profile.home, opts.screen);
+  const pass = outboundScreen(store.profile.home, opts.screen), errors: string[] = [];
   for (const target of store.openedSyncTargets()) {
     const screened = target.profile.kind === "generation" ? screenOutboundRows(target, pass) : screenOwnSegment(target.dir, target.machine.id, pass);
-    if (!screened.ok) return { ok: false, pushed: false, entries: 0, error: screened.reason };
+    if (!screened.ok) errors.push(screened.reason);
   }
+  if (errors.length) return { ok: false, pushed: false, entries: 0, error: errors.join("; ") };
   if (store.profile.kind === "generation") return syncGenerationMemory(store, opts);
   const dir = store.dir;
   const fail = (error: string): SyncResult => ({ ok: false, pushed: false, entries: 0, error });