@staix/agent-mem 0.20.3 → 0.22.0

package/src/memory/sync-placement-capture.ts

@@ -0,0 +1,373 @@
+import type { PlacementPublicationSource } from "./sync-placement-publication-plan.ts";
+import { validatePlacementKey, type PlacementRealm } from "./sync-placement-journal-format.ts";
+import { types } from "node:util";
+import { createHash } from "node:crypto";
+import { closeSync, constants, fstatSync, lstatSync, openSync, opendirSync, readSync, type BigIntStats } from "node:fs";
+import { join } from "node:path";
+import { canonicalJSON, generationDescriptor, hashJSON, validateVaultLinkRow, type BoundProfile, type VaultLinkRow } from "./generation.ts";
+import { validatePlacementBaseV2, validatePlacementProfile, validatePlacementShards, PLACEMENT_PROFILE_SCHEMA } from "./sync-placement-format.ts";
+import { planSyncPlacementActivation, type SyncPlacementActivationContext, type SyncPlacementWriterAttestation } from "./sync-placement-plan.ts";
+import { readPublicPruneViewForActivation, PUBLIC_PRUNE_INTENT } from "./public-prune-view.ts";
+import { realPath, DENY_NAMES, DENY_SEGMENTS } from "./platform.ts";
+import { loadAmemConfig } from "./config.ts";
+import { memoryPolicySnapshot } from "./policy.ts";
+import { SegmentReader, SegmentReadBudgetError, checkedEntry, completeLines } from "./bridge.ts";
+import { readShardLegacySnapshot } from "./shard-bridge.ts";
+import { coalesceGenerationSource } from "./generation-index.ts";
+import { validatePruneRow, type PruneSourceRow, type PruneRow } from "./prune.ts";
+import { shardKeyHash, SHARD_SCHEMA } from "./shard.ts";
+import { SyncPlacementJournalError, placementKeyId, type PlacementKey } from "./sync-placement-journal-format.ts";
+import type { Entry } from "./store.ts";
+import { assertPlacementRuntime } from "./sync-placement-guard.ts";
+import { activationSourceMarkers, assertPlacementActivationOwner, type PlacementActivationOwner, type PlacementActivationCaptureProof } from "./sync-placement-activation-proof.ts";
+import { readEffectiveSyncPlacementWriters, writerBoundPlacementContextHash, writerInventoryEvidence, type EffectiveSyncPlacementWriters } from "./sync-placement-effective-writers.ts";
+import { SharedWriterRevisionError } from "./sync-placement-writer-revision-format.ts";
+
+/** Host authentication/compatibility facts are re-read at every effect boundary, never inferred from a session marker. */
+export interface PlacementCapturePort {
+  attest(): { writers: readonly SyncPlacementWriterAttestation[]; legacySyncQuiesced: true };
+  /** Required when a caller adds a policy callback; must change whenever its policy changes. */
+  policyVersion?(): string;
+}
+/** Internal actual-transport proof, admitted only after the native pending plan and fetched original were validated. */
+export interface PlacementPendingSource { realm: PlacementRealm; pathHash: string; offset: number; prefixHash: string; line: string }
+export interface PlacementSourceRow { key: PlacementKey; row: Entry; sourcePlacement: "local" | "synced"; intrinsicLocal: boolean }
+export interface PlacementSpecialSourceRow { key: PlacementKey; row: PruneRow | VaultLinkRow; sourcePlacement: "local" | "synced"; intrinsicLocal: boolean }
+export interface PlacementCapture {
+  home: string; context: SyncPlacementActivationContext; activeHead?: string;
+  markerHash: string; fingerprint: string; directories: string[]; prefixes: PlacementPublicationSource[]; rows: Map<string, PlacementSourceRow>;
+  /** Diagnostic inventory only; these rows never enter the ordinary transport/capture row map implicitly. */
+  specialRows: Map<string, PlacementSpecialSourceRow>;
+  sourceRowsByRealm: Map<string, readonly PruneSourceRow[]>;
+  writerInventory?:EffectiveSyncPlacementWriters;
+  assertCurrent(): void;
+  /** Under live writer fences, inode/ctime/size checks protect the already-hashed prefixes across callbacks without reparsing rows. */
+  assertUnchanged(): void;
+}
+export function placementCaptureContextHash(capture:Pick<PlacementCapture,"context"|"writerInventory">):string{return writerBoundPlacementContextHash(capture.context,capture.writerInventory);}
+export interface PlacementActivationMarkerSnapshot {
+  profileText: string; shardsText: string; profileStamp: [string,string,string,string,string]; shardsStamp: [string,string,string,string,string];
+}
+/** Source facts only: no writer attestation, quiescence claim or effect authority. */
+export interface PlacementSourcePreview {
+  home: string; base: Omit<SyncPlacementActivationContext, "writers" | "legacySyncQuiesced">;
+  activeHead?: string; markerHash: string; markers: PlacementActivationMarkerSnapshot; directories: string[]; prefixes: PlacementPublicationSource[];
+  rows: Map<string, PlacementSourceRow>; specialRows: Map<string, PlacementSpecialSourceRow>;
+  sourceRowsByRealm: Map<string, readonly PruneSourceRow[]>; assertSourcesUnchanged(): void;
+}
+function fail(code: "changed" | "invalid" | "bound" = "changed"): never { throw new SyncPlacementJournalError(code); }
+const digest = (bytes: Uint8Array | string) => createHash("sha256").update(bytes).digest("hex");
+const stamp = (s: BigIntStats) => [s.dev, s.ino, s.size, s.mtimeNs, s.ctimeNs].map(String);
+const same = (a: BigIntStats, b: BigIntStats) => canonicalJSON(stamp(a)) === canonicalJSON(stamp(b));
+function ownedDirectory(dir: string): BigIntStats {
+  const s = lstatSync(dir, { bigint: true });
+  if (!s.isDirectory() || s.isSymbolicLink() || s.uid !== BigInt(process.getuid!()) || (s.mode & 0o022n) !== 0n) fail();
+  return s;
+}
+/** ponytail: capture is capped at 256 metadata objects and 8 MiB/20000 source rows across all realms.
+ * Larger homes need a reviewed chunked activation proof; no input is silently omitted at this ceiling. */
+function sourcePreview(homeInput: string, selected?: readonly PlacementRealm[], pending: readonly PlacementPendingSource[] = [], policyVersion?: string, ownerProof?: PlacementActivationCaptureProof, sourceOwner?:PlacementActivationOwner): PlacementSourcePreview {
+  let selection: PlacementRealm[] | undefined;
+  if (selected !== undefined) {
+    if (!Array.isArray(selected) || types.isProxy(selected) || selected.length > 256) fail("bound");
+    const copied = memoryPolicySnapshot(selected); if (!copied) fail();
+    selection = copied.map(realm => validatePlacementKey({ realm, id: "0".repeat(32), rowHash: "0".repeat(64) }).realm);
+    if (!selection.length || new Set(selection.map(realm => canonicalJSON(realm))).size !== selection.length) fail();
+  }
+  const home = realPath(homeInput), root = ownedDirectory(home);
+  if(sourceOwner)assertPlacementActivationOwner(sourceOwner,home);
+  let metadataObjects = 0, metadataBytes = 0;
+  const facts: unknown[] = [], sourceChecks: (() => void)[] = [];
+  const pendingByPath = new Map(pending.map(item => [canonicalJSON(item.realm)+":"+item.pathHash,item]));
+  if (pendingByPath.size !== pending.length) fail();
+  const directoryFact = (dir: string) => {
+    const stat = ownedDirectory(dir); facts.push([dir, "directory", String(stat.dev), String(stat.ino), String(stat.uid)]);
+    sourceChecks.push(() => { const now=ownedDirectory(dir); if(now.dev!==stat.dev||now.ino!==stat.ino) fail(); });
+  };
+  const bytes = (file: string, optional = false): Buffer | undefined => {
+    const before = lstatSync(file, { bigint: true, throwIfNoEntry: false });
+    if (!before) { if (!optional) fail(); facts.push([file, null]); sourceChecks.push(() => { if(lstatSync(file,{throwIfNoEntry:false})) fail(); }); return undefined; }
+    if (++metadataObjects > 256 || before.size > 262144n || metadataBytes + Number(before.size) > 8 * 1024 * 1024) fail("bound");
+    if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1n || before.uid !== root.uid || (before.mode & 0o022n) !== 0n) fail();
+    const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+      const opened = fstatSync(fd, { bigint: true }); if (!same(before, opened)) fail();
+      const out = Buffer.alloc(Number(opened.size)); let at = 0;
+      while (at < out.length) { const count = readSync(fd, out, at, out.length - at, at); if (!count) fail(); at += count; }
+      const after = lstatSync(file, { bigint: true }); if (!same(opened, fstatSync(fd, { bigint: true })) || !same(opened, after)) fail();
+      metadataBytes += out.length; facts.push([file, stamp(opened), digest(out)]);
+      sourceChecks.push(() => { const now=lstatSync(file,{bigint:true}); if(!now.isFile()||now.isSymbolicLink()||now.nlink!==1n||!same(opened,now)) fail(); }); return out;
+    } finally { closeSync(fd); }
+  };
+  const json = (file: string, optional = false): any => {
+    const input = bytes(file, optional); if (!input) return undefined;
+    return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(input));
+  };
+  const markerStart = facts.length;
+  const profileBytes = bytes(join(home, "profile.json"))!, shardsBytes = bytes(join(home, "shards.json"))!;
+  const actualMarkers: PlacementActivationMarkerSnapshot = { profileText: profileBytes.toString("utf8"), shardsText: shardsBytes.toString("utf8"),
+    profileStamp: [...(facts[markerStart] as [string,PlacementActivationMarkerSnapshot["profileStamp"],string])[1]], shardsStamp: [...(facts[markerStart+1] as [string,PlacementActivationMarkerSnapshot["shardsStamp"],string])[1]] };
+  const markers = ownerProof ? activationSourceMarkers(ownerProof,home,actualMarkers) : actualMarkers;
+  if (ownerProof) {
+    facts[markerStart] = [join(home,"profile.json"),markers.profileStamp,digest(Buffer.from(markers.profileText))];
+    facts[markerStart+1] = [join(home,"shards.json"),markers.shardsStamp,digest(Buffer.from(markers.shardsText))];
+  }
+  const decodeMarker = (text: string): unknown => JSON.parse(new TextDecoder("utf-8",{fatal:true}).decode(Buffer.from(text)));
+  const rawProfile = decodeMarker(markers.profileText) as { schema?: string }, rawShards = decodeMarker(markers.shardsText);
+  let activeHead: string | undefined;
+  let base: ReturnType<typeof validatePlacementBaseV2>;
+  if (rawProfile?.schema === PLACEMENT_PROFILE_SCHEMA) {
+    const profile = validatePlacementProfile(rawProfile), shards = validatePlacementShards(rawShards, profile);
+    activeHead = profile.placementHead;
+    const { publicationFormat: _pf, placementHead: _ph, ...p } = profile;
+    const profile2 = { ...p, schema: "agent-mem.profile/v2" };
+    const { publicationFormat: _sf, placementHead: _sh, ...s } = shards;
+    base = validatePlacementBaseV2(profile2, { ...s, schema: "agent-mem.shards/v2", selectorRevision: hashJSON(profile2) });
+  } else base = validatePlacementBaseV2(rawProfile, rawShards);
+  const markerHash = hashJSON({ profile: rawProfile, shards: rawShards });
+  bytes(join(home, "public-prune-input-sets", `${base.profile.pruneInputSetHash}.json`));
+  readPublicPruneViewForActivation(home, base.profile.pruneInputSetHash, base.profile.generation);
+  const aliases = bytes(join(home, "aliases.jsonl"), true);
+  bytes(join(home, "amem.config.json"), true);
+  const machine = json(join(home, "machine.json"));
+  if (machine?.id !== base.shards.machine.id) fail();
+  // An in-flight migration/prune is never accepted as a stable placement source.
+  for (const name of ["profile.lock", PUBLIC_PRUNE_INTENT]) {
+    if (name === "profile.lock" && ownerProof) continue; // The module-private proof validated this exact live owner and sealed intent.
+    if(name==="profile.lock"&&sourceOwner){assertPlacementActivationOwner(sourceOwner,home);continue;}
+    if (lstatSync(join(home,name),{throwIfNoEntry:false})) fail();
+  }
+  const reader = new SegmentReader(16 * 1024 * 1024, { maxSourceBytes: 8 * 1024 * 1024, maxRows: 20000 });
+  const rows = new Map<string, PlacementSourceRow>(), specialRows = new Map<string, PlacementSpecialSourceRow>(), sourceRowsByRealm = new Map<string, readonly PruneSourceRow[]>();
+  const directories = [home], prefixes: PlacementPublicationSource[] = [];
+  const realms: SyncPlacementActivationContext["realms"][number][] = [];
+  const listing = (dir: string, optional = false): string[] => {
+    const s = lstatSync(dir, { throwIfNoEntry: false });
+    if (!s) { if (!optional) fail(); facts.push([dir, null]); sourceChecks.push(() => {if(lstatSync(dir,{throwIfNoEntry:false}))fail();}); return []; }
+    directoryFact(dir); const listStamp = lstatSync(dir,{bigint:true});
+    sourceChecks.push(() => { if(!same(listStamp,lstatSync(dir,{bigint:true}))) fail(); });
+    const iterator = opendirSync(dir), names: string[] = [];
+    try { for (;;) { const item = iterator.readSync(); if (!item) break; if (names.length >= 256) fail("bound"); names.push(item.name); } }
+    finally { iterator.closeSync(); }
+    names.sort(); facts.push([dir, names]); return names;
+  };
+  const realm = (dir: string, identity: PlacementKey["realm"], project?: string) => {
+    directories.push(dir);
+    const beforeFacts = facts.length; directoryFact(dir);
+    if (project !== undefined) {
+      const descriptor = json(join(dir, "project.json"));
+      if (descriptor?.schema !== SHARD_SCHEMA || descriptor.key !== project || typeof descriptor.local !== "boolean") fail();
+    }
+    const descriptor = json(join(dir, "generation.json")), sources = json(join(dir, "migration-sources.json")), seal = json(join(dir, "generation-seal.json"));
+    if (canonicalJSON(descriptor) !== canonicalJSON(generationDescriptor(base.profile.generation)) || !Array.isArray(sources?.sources)
+      || sources.schema !== "agent-mem.migration-sources/v1" || seal?.schema !== "agent-mem.generation-seal/v1"
+      || seal.generation !== base.profile.generation || seal.descriptorHash !== hashJSON(descriptor)
+      || seal.sourceDigest !== hashJSON({ sources: sources.sources, legacyCommit: sources.legacyCommit })
+      || json(join(dir, "machine.json"))?.id !== machine.id) fail();
+    const hasMain = !!lstatSync(join(dir, "legacy-main"), { throwIfNoEntry: false });
+    const profile: BoundProfile = { kind: "generation", home, dir, generation: base.profile.generation, selectorRevision: hashJSON(base.profile),
+      sharded: true, legacyHome: join(dir, "legacy"), ...(hasMain ? { legacyMainHome: join(dir, "legacy-main") } : {}) };
+    for (const root of [profile.legacyHome!, ...(hasMain ? [profile.legacyMainHome!] : [])]) {
+      directoryFact(root); bytes(join(root, "machine.json"), true);
+      for(const folder of ["log","local"]) {
+        const file=join(root,folder), s=lstatSync(file,{bigint:true,throwIfNoEntry:false});
+        sourceChecks.push(() => { const now=lstatSync(file,{bigint:true,throwIfNoEntry:false}); if(s ? !now||!same(s,now) : now!==undefined) fail(); });
+      }
+    }
+    const segments = readShardLegacySnapshot(profile, { reader });
+    for (const folder of ["log", "local"]) {
+      directoryFact(join(dir, folder));
+      const folderPath=join(dir,folder), folderStamp=lstatSync(folderPath,{bigint:true});
+      sourceChecks.push(() => { if(!same(folderStamp,lstatSync(folderPath,{bigint:true}))) fail(); });
+      if(folder === "local") bytes(join(dir,folder,`publisher-boundary-${machine.id}.json`),true);
+      for (const name of reader.listFiles(join(dir, folder))) {
+        if (!name.endsWith(".jsonl")) continue;
+        if ( !/^[A-Za-z0-9][A-Za-z0-9._-]*\.jsonl$/.test(name)) fail();
+        segments.push({ ...reader.read(join(dir, folder, name), undefined, true), source: "generation", path: `${folder}/${name}`, local: folder === "local" });
+      }
+    }
+    const presence = new Map<string, PruneSourceRow>();
+    const special = new Map<string, PlacementSpecialSourceRow>();
+    const retainSpecial = (row: PruneRow | VaultLinkRow, local: boolean) => {
+      const key = { realm: identity, id: row.id, rowHash: hashJSON(row) }, prior = special.get(row.id);
+      if (prior && (prior.key.rowHash !== key.rowHash || prior.sourcePlacement !== (local ? "local" : "synced"))) fail();
+      special.set(row.id, { key, row, sourcePlacement: local ? "local" : "synced", intrinsicLocal: row.op === "vault_link" });
+    };
+    for (const segment of segments) {
+      const file = join(segment.source === "generation" ? dir : segment.source === "legacy-main" ? profile.legacyMainHome! : profile.legacyHome!, segment.path);
+      const fileStat = lstatSync(file);
+      if (!fileStat.isFile() || fileStat.isSymbolicLink() || fileStat.nlink !== 1 || fileStat.uid !== process.getuid?.() || (fileStat.mode & 0o022) !== 0) fail();
+      let sourceHash = segment.hash, sourceLength = segment.offset;
+      if (segment.tailBytes) {
+        const proof = pendingByPath.get(canonicalJSON(identity)+":"+digest(segment.path));
+        if (segment.source !== "generation" || !proof || proof.offset !== segment.offset || proof.prefixHash !== segment.hash
+          || segment.tailBytes >= Buffer.byteLength(proof.line) || segment.tailBytes > 16384) fail();
+        const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        try {
+          const opened = fstatSync(fd, { bigint: true });
+          if (canonicalJSON(stamp(opened)) !== segment.stamp) fail();
+          const tail = Buffer.alloc(segment.tailBytes); let at = 0;
+          while (at < tail.length) { const n = readSync(fd, tail, at, tail.length-at, segment.offset+at); if (!n) fail(); at+=n; }
+          if (!tail.equals(Buffer.from(proof.line).subarray(0,tail.length)) || !same(opened,fstatSync(fd,{bigint:true})) || !same(opened,lstatSync(file,{bigint:true}))) fail();
+          sourceHash = createHash("sha256").update(segment.bytes).update(tail).digest("hex"); sourceLength += tail.length;
+        } finally { closeSync(fd); }
+      }
+      facts.push([dir, segment.source, segment.path, sourceLength, sourceHash, segment.stamp]);
+      const fileStamp=lstatSync(file,{bigint:true});
+      if(canonicalJSON(stamp(fileStamp))!==segment.stamp) fail();
+      sourceChecks.push(() => { const now=lstatSync(file,{bigint:true}); if(now.isSymbolicLink()||!now.isFile()||now.nlink!==1n||!same(fileStamp,now)) fail(); });
+      if (!segment.stamp || !["generation", "legacy-local", "legacy-main"].includes(segment.source)) fail();
+      const physical: unknown = JSON.parse(segment.stamp);
+      if (!Array.isArray(physical) || physical.length !== 5 || !physical.every(value => typeof value === "string" && /^[0-9]+$/.test(value))) fail();
+      prefixes.push({ realm: identity, source: segment.source as PlacementPublicationSource["source"], pathHash: digest(segment.path),
+        dev: physical[0] as string, ino: physical[1] as string, byteLength: sourceLength, hash: sourceHash,
+        mtimeNs: physical[3] as string, ctimeNs: physical[4] as string });
+      for (const line of completeLines(segment.bytes)) {
+        if (!line.length) continue;
+        const parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(line));
+        if (segment.source === "generation" && parsed?.op === "prune") {
+          const row = validatePruneRow(parsed, profile.generation, segment.local ? "local" : "synced");
+          if (segment.path !== `${segment.local ? "local" : "log"}/${row.machine}.jsonl`) fail();
+          retainSpecial(row, segment.local);
+          continue;
+        }
+        if (segment.source === "generation" && parsed?.op === "vault_link") {
+          const row = validateVaultLinkRow(parsed, profile.generation, segment.local ? "local" : "synced");
+          if (segment.path !== `local/${row.machine}.jsonl`) fail();
+          retainSpecial(row, true);
+          continue;
+        }
+        const entry = checkedEntry(parsed);
+        presence.set(entry.id, coalesceGenerationSource(presence.get(entry.id), entry, segment));
+      }
+    }
+    for (const source of special.values()) {
+      if (presence.has(source.key.id)) fail();
+      specialRows.set(placementKeyId(source.key), source);
+    }
+    sourceRowsByRealm.set(canonicalJSON(identity), [...presence.values()]);
+    for (const source of presence.values()) {
+      const key = { realm: identity, id: source.row.id, rowHash: hashJSON(source.row) };
+      rows.set(placementKeyId(key), { key, row: source.row, sourcePlacement: source.placement,
+        intrinsicLocal: source.row.op === "settle" || source.row.op === "note" && source.row.tier === "short" });
+    }
+    const bindingHash = hashJSON(facts.slice(beforeFacts));
+    realms.push({ ...identity, bindingHash });
+  };
+  if (!selection || selection.some(item => item.scope === "user")) realm(join(home, "user"), { scope: "user" });
+  for (const name of listing(join(home, "projects"), true)) {
+    if (!/^[a-f0-9]{16}$/.test(name)) fail();
+    if (selection && !selection.some(item => item.scope === "project" && item.keyHash.slice(0,16) === name)) continue;
+    const dir = join(home, "projects", name), project = json(join(dir, "project.json"));
+    if (typeof project?.key !== "string" || shardKeyHash(project.key) !== name) fail();
+    // Capture scaffolds are not curated realms, but their identity still binds this inventory.
+    if (!lstatSync(join(dir, "generation.json"), { throwIfNoEntry: false })) continue;
+    const keyHash = digest(project.key);
+    if (selection && !selection.some(item => item.scope === "project" && item.keyHash === keyHash)) fail();
+    realm(dir, { scope: "project", keyHash }, project.key);
+  }
+  if (selection && realms.length !== selection.length) fail();
+  const defaults = memoryPolicySnapshot({ names: DENY_NAMES, segments: DENY_SEGMENTS }); if (!defaults) fail();
+  const configuration = loadAmemConfig(home).config;
+  const contextBase: PlacementSourcePreview["base"] = { ...base,
+    homeHash: hashJSON([home, String(root.dev), String(root.ino), String(root.uid)]), sourceHash: hashJSON(facts),
+    aliasesHash: digest(aliases ?? Buffer.alloc(0)), policyHash: hashJSON({ config: configuration, defaults, policyVersion }), realms };
+  // ponytail: passive checks rely on native inode/size/ctime identity for the hashed prefixes.
+  // Immutable descriptor-bound source blocks are the upgrade path for hostile same-user raw writers.
+  const assertSourcesUnchanged = () => {
+    try {
+      const currentDefaults = memoryPolicySnapshot({ names: DENY_NAMES, segments: DENY_SEGMENTS });
+      if (!currentDefaults || hashJSON({ config: configuration, defaults: currentDefaults, policyVersion }) !== contextBase.policyHash) fail();
+      const now = ownedDirectory(home); if (now.dev !== root.dev || now.ino !== root.ino) fail();
+      for (const check of sourceChecks) check();
+      if (ownerProof) activationSourceMarkers(ownerProof,home,actualMarkers);
+      if(sourceOwner)assertPlacementActivationOwner(sourceOwner,home);
+    } catch { fail(); }
+  };
+  return { home, base: contextBase, assertSourcesUnchanged, ...(activeHead ? { activeHead } : {}), markerHash, markers,
+    directories: directories.sort(), prefixes, rows, specialRows, sourceRowsByRealm };
+}
+/** Read-only preview shares the source collector, without fabricating a quiescence attestation. */
+export function previewSyncPlacementSources(home: string): PlacementSourcePreview {
+  return previewSources(home);
+}
+/** Internal renewal inventory under the exact live home/profile/mutation owner; no marker virtualization. */
+export function previewOwnedSyncPlacementSources(home:string,owner:PlacementActivationOwner):PlacementSourcePreview {
+  assertPlacementActivationOwner(owner,home);return previewSources(home,owner);
+}
+function previewSources(home:string,owner?:PlacementActivationOwner):PlacementSourcePreview {
+  try { assertPlacementRuntime(home); const preview = sourcePreview(home,undefined,[],undefined,undefined,owner); preview.assertSourcesUnchanged(); return preview; }
+  catch (error) {
+    if (error && typeof error === "object" && !types.isProxy(error)) {
+      if (error instanceof SyncPlacementJournalError) throw error;
+      if (error instanceof SegmentReadBudgetError) return fail("bound");
+    }
+    return fail();
+  }
+}
+function capture(home: string, port: PlacementCapturePort, selected?: readonly PlacementRealm[], pending: readonly PlacementPendingSource[] = [], ownerProof?: PlacementActivationCaptureProof): Omit<PlacementCapture, "assertCurrent"> {
+  // All host callouts precede filesystem capture, including the final passive proof.
+  const attestation = memoryPolicySnapshot(port.attest()), policyVersion = port.policyVersion?.();
+  if (!attestation || port.policyVersion && typeof policyVersion !== "string") fail();
+  const source = sourcePreview(home, selected, pending, policyVersion, ownerProof);
+  const context: SyncPlacementActivationContext = { ...source.base, writers: attestation.writers, legacySyncQuiesced: attestation.legacySyncQuiesced };
+  const validated = planSyncPlacementActivation(context, "0".repeat(64));
+  context.writers = validated.writers; context.realms = validated.realms;
+  const writerInventory=source.activeHead&&writerInventoryEvidence(source.home,source.activeHead)?readEffectiveSyncPlacementWriters(source.home):undefined;
+  if(writerInventory&&canonicalJSON(context.writers)!==canonicalJSON(writerInventory.writers))fail();
+  const assertUnchanged = () => {
+    try {
+      const currentAttestation = memoryPolicySnapshot(port.attest()), currentVersion = port.policyVersion?.();
+      if (!currentAttestation) fail();
+      const checked = planSyncPlacementActivation({ ...context, writers: currentAttestation.writers, legacySyncQuiesced: currentAttestation.legacySyncQuiesced }, "0".repeat(64));
+      if (canonicalJSON(checked.writers) !== canonicalJSON(context.writers) || currentVersion !== policyVersion) fail();
+      writerInventory?.assertCurrent();
+      if(source.activeHead&&!writerInventory&&writerInventoryEvidence(source.home,source.activeHead))fail();
+      source.assertSourcesUnchanged();
+    } catch { fail(); }
+  };
+  return { home: source.home, context, assertUnchanged, ...(source.activeHead ? { activeHead: source.activeHead } : {}),
+    ...(writerInventory?{writerInventory}:{}),markerHash: source.markerHash, fingerprint: hashJSON({ context, markerHash: source.markerHash,...(writerInventory?.revisionSequence?{writerRevisionHash:writerInventory.revisionHash}:{}) }), directories: source.directories,
+    prefixes: source.prefixes, rows: source.rows, specialRows: source.specialRows, sourceRowsByRealm: source.sourceRowsByRealm };
+}
+
+export function captureSyncPlacementContext(home: string, port: PlacementCapturePort, selected?: readonly PlacementRealm[], pendingInput: readonly PlacementPendingSource[] = []): PlacementCapture {
+  try {
+    const selection = selected === undefined ? undefined : memoryPolicySnapshot(selected);
+    if (selected !== undefined && !selection) fail();
+    if (!Array.isArray(pendingInput) || types.isProxy(pendingInput) || pendingInput.length > 20000) fail("bound");
+    const pending = pendingInput.map(item => {
+      if (!item || typeof item !== "object" || types.isProxy(item)) fail();
+      const fields = Object.getOwnPropertyDescriptors(item);
+      if (Object.keys(fields).sort().join() !== "line,offset,pathHash,prefixHash,realm" || Object.values(fields).some(field => !("value" in field) || !field.enumerable)) fail();
+      const realm = validatePlacementKey({realm:fields.realm!.value,id:"0".repeat(32),rowHash:"0".repeat(64)}).realm;
+      const line: unknown = fields.line!.value, offset: unknown = fields.offset!.value, pathHash: unknown = fields.pathHash!.value, prefixHash: unknown = fields.prefixHash!.value;
+      if (typeof line !== "string" || Buffer.byteLength(line)>16384 || !line.endsWith("\n") || typeof offset!=="number" || !Number.isSafeInteger(offset) || offset<0
+        || typeof pathHash!=="string" || pathHash.length!==64 || !/^[a-f0-9]+$/.test(pathHash) || typeof prefixHash!=="string" || prefixHash.length!==64 || !/^[a-f0-9]+$/.test(prefixHash)) fail();
+      return {realm,line,offset,pathHash,prefixHash};
+    });
+    const before = capture(home, port, selection, pending);
+    return { ...before, assertCurrent: () => { try { if (capture(home, port, selection, pending).fingerprint !== before.fingerprint) fail(); } catch { fail(); } } };
+  } catch (error) {
+    if (error && typeof error === "object" && !types.isProxy(error)) {
+      if(error instanceof SharedWriterRevisionError){const code=Object.getOwnPropertyDescriptor(error,"code")?.value;if(code==="staging"||code==="pending")throw new SharedWriterRevisionError(code);}
+      if (error instanceof SyncPlacementJournalError) throw error;
+      if (error instanceof SegmentReadBudgetError) return fail("bound");
+    }
+    return fail();
+  }
+}
+
+/** Internal initial-activation capture only. Tokens require the actual profile owner, live home mutation and exact durable intent. */
+export function captureSyncPlacementActivationContext(home: string, port: PlacementCapturePort, proof: PlacementActivationCaptureProof): PlacementCapture {
+  try {
+    const before = capture(home,port,undefined,[],proof);
+    return { ...before, assertCurrent: () => { if (capture(home,port,undefined,[],proof).fingerprint !== before.fingerprint) fail(); } };
+  } catch (error) {
+    if (error && typeof error === "object" && !types.isProxy(error)) {
+      if (error instanceof SyncPlacementJournalError) throw error;
+      if (error instanceof SegmentReadBudgetError) return fail("bound");
+    }
+    return fail();
+  }
+}

package/src/memory/sync-placement-dependencies.ts

@@ -0,0 +1,255 @@
+import { types } from "node:util";
+import { checkedEntry } from "./bridge.ts";
+import { canonicalJSON, hashJSON, validateVaultLinkRow } from "./generation.ts";
+import { OP_CONTRACTS } from "./ops-contract.ts";
+import { validatePruneRow } from "./prune.ts";
+import { SUGGESTED } from "./store.ts";
+import { placementKeyId, validatePlacementKey, type PlacementKey, type PlacementRealm } from "./sync-placement-journal-format.ts";
+import type { OutboundVerdict, SyncPolicyCategory } from "./sync-screen.ts";
+
+export interface DependencySource {
+  key: PlacementKey; row: unknown; sourcePlacement: "local" | "synced"; policy: OutboundVerdict; held: boolean;
+}
+/** Trusted input only after the caller independently verifies the exact public occurrence.
+ * Neither source placement nor a journal exposure flag constitutes this proof. */
+export interface VerifiedDependencyEndpoint { key: PlacementKey; row: unknown }
+export interface PlacementDependencyInput {
+  generation: string; selectedRealms: readonly PlacementRealm[]; rows: readonly DependencySource[];
+  publicEndpoints?: readonly VerifiedDependencyEndpoint[];
+  /** Exact original prune keys whose complete realm/generation/target/basis witness graph the caller verified. */
+  verifiedPrunes?: readonly PlacementKey[];
+}
+export type DependencyHoldReason = SyncPolicyCategory | "journal-hold" | "source-local" | "related-local" | "unsupported-reference" | "unverified-prune";
+export interface DependencyDecision { key: PlacementKey; eligible: boolean; reason?: DependencyHoldReason; dependencies: PlacementKey[] }
+export class PlacementDependencyInputError extends Error {
+  constructor() { super("Sync placement dependency inputs are invalid, incomplete or exceed supported bounds; capture and verify the selected sources again."); this.name = "PlacementDependencyInputError"; }
+}
+function fail(): never { throw new PlacementDependencyInputError(); }
+const fullId = (v: unknown): v is string => typeof v === "string" && v.length === 32 && /^[a-f0-9]+$/.test(v);
+const realmId = (v: PlacementRealm) => canonicalJSON(v);
+const categories: readonly string[] = ["secret", "personal-data", "deny-path", "private-or-invalid", "host"];
+interface Reference { id: string; op?: "note" | "goal" | "suggest"; hash?: string; publicHeld?: boolean; sameRealm?: boolean }
+interface Node {
+  key: PlacementKey; row: Record<string, unknown>; output: boolean; sourcePlacement: "local" | "synced";
+  policy: OutboundVerdict; held: boolean; public: boolean; reason?: DependencyHoldReason; syntaxValid: boolean; refs: Reference[];
+}
+/** Descriptor-only bounded JSON copy, including private flags: those are data for the mandatory verdict,
+ * never a reason to invoke getters or silently omit a source. */
+// Check physical cardinality and canonical source bytes before constructing any copied source collection.
+function preflight(raw: unknown): void {
+  const descriptors = (value: unknown, array = false) => {
+    if (!value || typeof value !== "object" || types.isProxy(value) || Array.isArray(value) !== array || Object.getOwnPropertySymbols(value).length) return fail();
+    const proto = Object.getPrototypeOf(value);
+    if (array ? proto !== Array.prototype : proto !== Object.prototype && proto !== null) return fail();
+    return Object.getOwnPropertyDescriptors(value);
+  };
+  const fields = descriptors(raw);
+  const arrayFields = (value: unknown, max: number) => {
+    if (!value || typeof value !== "object" || types.isProxy(value) || !Array.isArray(value)) return fail();
+    const length = Object.getOwnPropertyDescriptor(value, "length")?.value;
+    if (!Number.isSafeInteger(length) || length > max) return fail();
+    const own = descriptors(value, true);
+    if (Object.keys(own).length !== length + 1) return fail();
+    for (let i = 0; i < length; i++) if (!own[String(i)] || !("value" in own[String(i)]!) || !own[String(i)]!.enumerable) fail();
+    return { own, length: length as number };
+  };
+  for (const [key, field] of Object.entries(fields)) if (!("value" in field) || !field.enumerable || !["generation", "selectedRealms", "rows", "publicEndpoints", "verifiedPrunes"].includes(key)) fail();
+  arrayFields(fields.selectedRealms?.value, 256);
+  const sources = arrayFields(fields.rows?.value, 20000);
+  let bytes = 0, nodes = 0;
+  const seen = new Set<object>();
+  const size = (v: unknown, depth: number): number => {
+    if (++nodes > 1_000_000 || depth > 64) return fail();
+    if (v === null) return 4;
+    if (typeof v === "boolean") return v ? 4 : 5;
+    if (typeof v === "number") { if (!Number.isFinite(v)) return fail(); return String(v).length; }
+    if (typeof v === "string") { if (Buffer.byteLength(v) > 8 * 1024 * 1024) return fail(); return Buffer.byteLength(JSON.stringify(v)); }
+    if (!v || typeof v !== "object" || types.isProxy(v) || seen.has(v)) return fail();
+    seen.add(v);
+    try {
+      if (Array.isArray(v)) {
+        const { own, length } = arrayFields(v, 20000); let total = 2 + Math.max(0, length - 1);
+        for (let i = 0; i < length; i++) { total += size(own[String(i)]!.value, depth + 1); if (total > 8 * 1024 * 1024) fail(); }
+        return total;
+      }
+      const own = descriptors(v); let total = 2, count = 0;
+      for (const [key, field] of Object.entries(own)) {
+        if (!("value" in field) || !field.enumerable) fail();
+        total += size(key, depth + 1) + 1 + size(field.value, depth + 1) + Number(count++ > 0);
+        if (total > 8 * 1024 * 1024) fail();
+      }
+      return total;
+    } finally { seen.delete(v); }
+  };
+  for (let i = 0; i < sources.length; i++) {
+    const source = descriptors(sources.own[String(i)]!.value), row = source.row;
+    if (!row || !("value" in row)) return fail();
+    bytes += size(row.value, 0) + 1;
+    if (bytes > 8 * 1024 * 1024) fail();
+  }
+  for (const key of ["publicEndpoints", "verifiedPrunes"]) if (fields[key]) arrayFields(fields[key]!.value, 20000);
+}
+/** ponytail: descriptor-only JSON safety stops at depth64, one million nodes and16MiB including supplied evidence.
+ * A reviewed chunked endpoint interface is required before larger proofs can enter this compiler. */
+function copyInput(value: unknown): unknown {
+  let bytes = 0, nodes = 0;
+  const seen = new Set<object>();
+  const visit = (v: unknown, depth: number): unknown => {
+    if (++nodes > 1_000_000 || depth > 64) fail();
+    if (v === null || typeof v === "boolean") { bytes += 5; return v; }
+    if (typeof v === "number") { if (!Number.isFinite(v)) fail(); bytes += 24; return v; }
+    if (typeof v === "string") { bytes += Buffer.byteLength(v); if (bytes > 16 * 1024 * 1024) fail(); return v; }
+    if (!v || typeof v !== "object" || types.isProxy(v) || seen.has(v) || Object.getOwnPropertySymbols(v).length) fail();
+    const array = Array.isArray(v), proto = Object.getPrototypeOf(v);
+    if (array ? proto !== Array.prototype : proto !== Object.prototype && proto !== null) fail();
+    const fields = Object.getOwnPropertyDescriptors(v); seen.add(v);
+    try {
+      if (array) {
+        const length = fields.length?.value;
+        if (!Number.isSafeInteger(length) || length > 20000 || Object.keys(fields).length !== length + 1) fail();
+        const out: unknown[] = [];
+        for (let i = 0; i < length; i++) { const field = fields[String(i)]; if (!field || !("value" in field) || !field.enumerable) fail(); out.push(visit(field.value, depth + 1)); }
+        return out;
+      }
+      const out: Record<string, unknown> = Object.create(null);
+      for (const [key, field] of Object.entries(fields)) { if (!("value" in field) || !field.enumerable) fail(); bytes += Buffer.byteLength(key); out[key] = visit(field.value, depth + 1); }
+      return out;
+    } finally { seen.delete(v); }
+  };
+  return visit(value, 0);
+}
+function object(value: unknown): Record<string, unknown> { if (!value || typeof value !== "object" || Array.isArray(value)) return fail(); return value as Record<string, unknown>; }
+function keys(value: Record<string, unknown>, required: string[], optional: string[] = []): void {
+  if (required.some(k => !Object.hasOwn(value, k)) || Object.keys(value).some(k => !required.includes(k) && !optional.includes(k))) fail();
+}
+function realm(value: unknown): PlacementRealm { return validatePlacementKey({ realm: value, id: "0".repeat(32), rowHash: "0".repeat(64) }).realm; }
+function syntax(node: Node, generation: string): boolean {
+  const row = node.row;
+  try {
+    // Existing validators require a plain JSON object, not our safe null-prototype copy.
+    const plain = JSON.parse(canonicalJSON(row));
+    if (row.op === "prune") validatePruneRow(plain, generation, node.sourcePlacement);
+    else if (row.op === "vault_link") validateVaultLinkRow(plain, generation, "local");
+    else if (typeof row.op === "string" && Object.hasOwn(OP_CONTRACTS, row.op)) checkedEntry(plain);
+    else return false;
+    return true;
+  } catch { return false; }
+}
+function utc(value: unknown): boolean { return typeof value === "string" && Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value; }
+function suggestion(row: Record<string, unknown>): { from: string; to: string } | undefined {
+  if (row.op !== "suggest" || !fullId(row.target) || typeof row.by !== "string") return;
+  const match = /^([^:]+):([a-f0-9]{32})$/.exec(row.by);
+  if (!match || match[0] !== row.by || !(SUGGESTED as readonly string[]).includes(match[1]!) || row.target === match[2]) return;
+  return { from: row.target, to: match[2]! };
+}
+function visible(from: Node, to: Node): boolean {
+  // Shared/user facts must not acquire a dependency on a private project endpoint.
+  const sharedEndpoint = to.key.realm.scope === "user" && (to.row.scope === undefined || to.row.scope === "shared");
+  if (from.key.realm.scope === "user" || from.row.scope === "shared") return sharedEndpoint;
+  return sharedEndpoint
+    || from.key.realm.scope === "project" && to.key.realm.scope === "project" && from.key.realm.keyHash === to.key.realm.keyHash;
+}
+/** Pure, body-free dependency decisions. The caller supplies authoritative coalesced physical rows and
+ * mandatory policy/journal verdicts; this function performs no screening, hydration, I/O or publication. */
+export function compilePlacementDependencies(raw: PlacementDependencyInput): DependencyDecision[] {
+  try { return compile(raw); } catch (error) { if (error instanceof PlacementDependencyInputError) throw error; return fail(); }
+}
+function compile(raw: PlacementDependencyInput): DependencyDecision[] {
+  preflight(raw);
+  const input = object(copyInput(raw)); keys(input, ["generation", "selectedRealms", "rows"], ["publicEndpoints", "verifiedPrunes"]);
+  if (!fullId(input.generation) || !Array.isArray(input.selectedRealms) || input.selectedRealms.length > 256 || !Array.isArray(input.rows)
+    || input.rows.length > 20000 || input.publicEndpoints !== undefined && !Array.isArray(input.publicEndpoints)
+    || input.verifiedPrunes !== undefined && !Array.isArray(input.verifiedPrunes)) return fail();
+  const selected = new Set(input.selectedRealms.map(x => realmId(realm(x)))); if (!selected.size || selected.size !== input.selectedRealms.length) fail();
+  const nodes: Node[] = [], byKey = new Map<string, Node>(), byId = new Map<string, Node[]>(), hashes = new Map<string, string>();
+  let sourceBytes = 0;
+  const add = (value: unknown, output: boolean): void => {
+    const item = object(value); keys(item, output ? ["key", "row", "sourcePlacement", "policy", "held"] : ["key", "row"]);
+    const key = validatePlacementKey(item.key), row = object(item.row), id = placementKeyId(key);
+    if (!selected.has(realmId(key.realm)) || row.id !== key.id || hashJSON(row) !== key.rowHash) fail();
+    if (hashes.has(key.id) && hashes.get(key.id) !== key.rowHash) fail(); hashes.set(key.id, key.rowHash);
+    if (output && (sourceBytes += Buffer.byteLength(canonicalJSON(row) + "\n")) > 8 * 1024 * 1024) fail();
+    let policy: OutboundVerdict = { ok: true };
+    if (output) {
+      const verdict = object(item.policy); keys(verdict, ["ok"], ["category"]);
+      if (verdict.ok === false && typeof verdict.category === "string" && categories.includes(verdict.category)) policy = { ok: false, category: verdict.category as SyncPolicyCategory };
+      else if (verdict.ok !== true || Object.hasOwn(verdict, "category")) fail();
+      if (!["local", "synced"].includes(item.sourcePlacement as string) || typeof item.held !== "boolean") fail();
+    }
+    const old = byKey.get(id);
+    if (old) { if (output || old.public) fail(); old.public = true; return; }
+    const node: Node = { key, row, output, sourcePlacement: output ? item.sourcePlacement as "local" | "synced" : "synced", policy,
+      held: output ? item.held as boolean : false, public: !output, syntaxValid: false, refs: [] };
+    nodes.push(node); byKey.set(id, node); byId.set(key.id, [...(byId.get(key.id) ?? []), node]);
+  };
+  for (const value of input.rows) add(value, true);
+  const endpoints = input.publicEndpoints as unknown[] | undefined;
+  if ((endpoints?.length ?? 0) > 20000) fail(); for (const value of endpoints ?? []) add(value, false);
+  const proofs = input.verifiedPrunes as unknown[] | undefined;
+  if ((proofs?.length ?? 0) > 20000) fail();
+  const verified = new Set((proofs ?? []).map(value => { const key = validatePlacementKey(value); if (!selected.has(realmId(key.realm))) fail(); return placementKeyId(key); }));
+  const heldIds = new Set(nodes.filter(node => node.held).map(node => node.key.id));
+  const policyHolds = new Map<string, SyncPolicyCategory>();
+  for (const node of nodes) if (!node.policy.ok) policyHolds.set(node.key.id, node.policy.category);
+  const refs = (node: Node, ids: unknown[], op?: Reference["op"], publicHeld = false): boolean => {
+    if (ids.some(id => !fullId(id))) return false;
+    node.refs.push(...ids.map(id => ({ id: id as string, ...(op ? { op } : {}), ...(publicHeld ? { publicHeld: true } : {}) }))); return true;
+  };
+  for (const node of nodes) {
+    const row = node.row;
+    node.syntaxValid = syntax(node, input.generation);
+    if (!node.syntaxValid) { node.reason = "unsupported-reference"; continue; }
+    if (node.sourcePlacement === "local" || row.op === "settle" || row.op === "vault_link" || row.op === "note" && row.tier === "short") node.reason = "source-local";
+    else if (heldIds.has(node.key.id)) node.reason = "journal-hold";
+    else if (policyHolds.has(node.key.id)) node.reason = policyHolds.get(node.key.id)!;
+    let valid = true;
+    switch (row.op) {
+      case "note": break; // Both ancestry fields are weak; never fetch or export their originals.
+      case "goal": valid = Array.isArray(row.dependsOn) && refs(node, row.dependsOn, "goal"); break;
+      case "supersede": valid = row.target !== row.by && refs(node, [row.target, row.by], "note"); break;
+      case "goal_state": valid = ["open", "active", "blocked", "done", "dropped"].includes(row.by as string) && refs(node, [row.target], "goal"); break;
+      case "goal_link": valid = typeof row.by === "string" && row.by.length > 0 && refs(node, [row.target], "goal"); break;
+      case "lease": case "lease_force": valid = utc(row.by) && refs(node, [row.target], "goal"); break;
+      case "suggest": { const edge = suggestion(row); valid = !!edge && refs(node, [edge.from, edge.to], "note"); break; }
+      case "confirm": case "reject": {
+        valid = refs(node, [row.target], "suggest");
+        const suggestions = fullId(row.target) ? byId.get(row.target) ?? [] : [];
+        const edge = suggestions.map(n => suggestion(n.row)).find(Boolean);
+        valid = valid && !!edge && refs(node, [edge.from, edge.to], "note"); break;
+      }
+      case "forget": valid = refs(node, [row.target], "note", true); break;
+      case "demote": valid = utc(row.by) && refs(node, [row.target], "note", true); break;
+      case "prune":
+        if (!verified.has(placementKeyId(node.key))) node.reason ??= "unverified-prune";
+        for (const target of row.targets as { id: string; rowHash: string; basis: { id: string; rowHash: string } }[]) {
+          node.refs.push({ id: target.id, hash: target.rowHash, sameRealm: true, publicHeld: true }, { id: target.basis.id, hash: target.basis.rowHash, sameRealm: true, publicHeld: true });
+        }
+        break;
+      case "settle": case "vault_link": break;
+      default: valid = false;
+    }
+    if (!valid) node.reason ??= "unsupported-reference";
+  }
+  const candidates = (from: Node, ref: Reference): Node[] => (byId.get(ref.id) ?? []).filter(to => visible(from, to)
+    && (!ref.op || to.row.op === ref.op) && (!ref.hash || to.key.rowHash === ref.hash)
+    && (!ref.sameRealm || realmId(from.key.realm) === realmId(to.key.realm)));
+  const usable = (from: Node, ref: Reference): Node | undefined => candidates(from, ref).find(to => {
+    if (to.public && ref.publicHeld && to.syntaxValid) return true;
+    return !heldIds.has(to.key.id) && !policyHolds.has(to.key.id) && !to.reason;
+  });
+  const reverse = new Map<string, Set<Node>>();
+  for (const node of nodes) for (const ref of node.refs) {
+    let dependents = reverse.get(ref.id); if (!dependents) reverse.set(ref.id, dependents = new Set()); dependents.add(node);
+  }
+  const queue = [...nodes];
+  for (let at = 0; at < queue.length; at++) {
+    const node = queue[at]!; if (node.reason) continue;
+    const endpoints = node.refs.map(ref => usable(node, ref));
+    let good = endpoints.every(Boolean);
+    if (good && node.row.op === "supersede") good = endpoints[0]!.row.scope !== "shared" || endpoints[1]!.row.scope === "shared";
+    if (!good) { node.reason = "related-local"; for (const dependent of reverse.get(node.key.id) ?? []) queue.push(dependent); }
+  }
+  return nodes.filter(node => node.output).map(node => ({ key: validatePlacementKey(node.key), eligible: !node.reason,
+    ...(node.reason ? { reason: node.reason } : {}), dependencies: [...new Map(node.refs.flatMap(ref => candidates(node, ref).map(to => [placementKeyId(to.key), to.key] as const))).values()].sort((a,b) => placementKeyId(a).localeCompare(placementKeyId(b))).map(validatePlacementKey) }))
+    .sort((a,b) => placementKeyId(a.key).localeCompare(placementKeyId(b.key)));
+}