@staix/agent-mem 0.20.2 → 0.21.0

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

@@ -0,0 +1,153 @@
+import { validatePlacementProfile, validatePlacementShards } from "./sync-placement-format.ts";
+import { assertPlacementViewAdvance } from "./sync-placement-active.ts";
+import { readPlacementRuntimeMarkers } from "./sync-placement-guard.ts";
+import { types } from "node:util";
+import { randomBytes } from "node:crypto";
+import { canonicalJSON, hashJSON } from "./generation.ts";
+import { acquireMutation, type MutationHandle } from "./mutation.ts";
+import { memoryPolicySnapshot } from "./policy.ts";
+import { outboundPolicyEvaluator, type RowScreen } from "./sync-screen.ts";
+import { assertPlacementRuntime } from "./sync-placement-guard.ts";
+import { PLACEMENT_FORMAT } from "./sync-placement-format.ts";
+import { planSyncPlacementActivation, validatePlacementPlan, validateSyncPlacementActivation, type SyncPlacementActivationPlan } from "./sync-placement-plan.ts";
+import { captureSyncPlacementContext, type PlacementCapturePort, type PlacementCapture } from "./sync-placement-capture.ts";
+import { PLACEMENT_EPOCH_SCHEMA, placementEpochHash, placementKeyId, validatePlacementEpoch, validatePlacementKey, validatePlacementEvent,
+  SyncPlacementJournalError, type PlacementEpoch, type PlacementKey, type PlacementCommittedOutcome, type PlacementAmbiguousOutcome } from "./sync-placement-journal-format.ts";
+import { rebuildPlacementProjection } from "./sync-placement-projection.ts";
+import { preparePlacementEpoch, readPlacementJournal, appendPlacementEvent } from "./sync-placement-journal-storage.ts";
+
+export interface PlacementJournalPreview { epoch: PlacementEpoch; plan: SyncPlacementActivationPlan }
+export interface PlacementAuthorizationBinding {
+  action: "prepare" | "hold" | "release"; seal: string;
+  epochHash?: string; key?: PlacementKey; expectedHead?: string; policyHash?: string;
+}
+export interface PlacementJournalPort extends PlacementCapturePort {
+  /** Person intent is authenticated by the host. Data/seals/session markers grant no authority. */
+  authorize(binding: Readonly<PlacementAuthorizationBinding>): boolean;
+  screen?: RowScreen;
+}
+function fail(code: "invalid" | "changed" | "authorization" | "policy" | "local" | "conflict" | "pending" | "busy" = "invalid"): never { throw new SyncPlacementJournalError(code); }
+function protectedCall<T>(work: () => T): T {
+  try { return work(); } catch (error) { if (error && typeof error === "object" && !types.isProxy(error) && error instanceof SyncPlacementJournalError) throw error; return fail("changed"); }
+}
+function person(port: PlacementJournalPort, action: "prepare" | "hold" | "release", seal: string, details: Omit<PlacementAuthorizationBinding, "action" | "seal"> = {}): void {
+  let authorized = false;
+  try { authorized = port.authorize(Object.freeze({ action, seal, ...details })) === true; } catch { fail("authorization"); }
+  if (!authorized) fail("authorization");
+}
+function fenced<T>(capture: PlacementCapture, work: (homeMutation: MutationHandle) => T): T {
+  const handles: MutationHandle[] = [];
+  try {
+    let homeMutation: MutationHandle | undefined;
+    for (const dir of capture.directories) {
+      const handle = acquireMutation(dir); if (!handle) fail("busy");
+      handles.push(handle); if (dir === capture.home) homeMutation = handle;
+    }
+    capture.assertCurrent(); if (!homeMutation) fail();
+    return work(homeMutation);
+  } finally { for (const release of handles.reverse()) release(); }
+}
+/** Read-only concrete preview. Preparing it still requires a fresh capture and explicit person authorization. */
+export function planPlacementJournal(home: string, port: PlacementCapturePort): PlacementJournalPreview {
+  return protectedCall(() => {
+    assertPlacementRuntime(home);
+    const capture = captureSyncPlacementContext(home, port); if (capture.activeHead) fail("conflict");
+    const epoch = validatePlacementEpoch({ schema: PLACEMENT_EPOCH_SCHEMA, publicationFormat: PLACEMENT_FORMAT,
+      generation: (capture.context.profile as { generation: string }).generation, homeHash: capture.context.homeHash,
+      contextHash: hashJSON(capture.context), nonce: randomBytes(16).toString("hex") });
+    const plan = planSyncPlacementActivation(capture.context, placementEpochHash(epoch));
+    capture.assertCurrent(); return { epoch, plan };
+  });
+}
+/** Creates only an empty private epoch on v2; never writes profile/shards/formats markers or enables transport. */
+export function preparePlacementJournal(home: string, preview: PlacementJournalPreview, port: PlacementJournalPort): { activated: false; epochHash: string } {
+  return protectedCall(() => {
+    const copied = memoryPolicySnapshot(preview); if (!copied || Object.keys(copied).sort().join() !== "epoch,plan") fail();
+    assertPlacementRuntime(home);
+    const epoch = validatePlacementEpoch(copied.epoch), plan = validatePlacementPlan(copied.plan), epochHash = placementEpochHash(epoch);
+    const capture = captureSyncPlacementContext(home, port);
+    if (capture.activeHead || epoch.homeHash !== capture.context.homeHash || epoch.contextHash !== hashJSON(capture.context)
+      || epoch.generation !== plan.generation || epochHash !== plan.targetProfile.placementHead) fail("changed");
+    validateSyncPlacementActivation(plan, { current: () => { capture.assertCurrent(); return capture.context; },
+      authorize: binding => { person(port, "prepare", binding.seal); return true; } });
+    fenced(capture, mutation => preparePlacementEpoch(capture.home, epoch, plan, { mutation, assertCurrent: capture.assertCurrent }));
+    return { activated: false, epochHash };
+  });
+}
+export interface PlacementEffectRequest { epochHash: string; expectedHead: string; requestId: string; key: PlacementKey }
+function request(input: PlacementEffectRequest): PlacementEffectRequest {
+  const value = memoryPolicySnapshot(input);
+  if (!value || Object.keys(value).sort().join() !== "epochHash,expectedHead,key,requestId"
+    || ![value.epochHash, value.expectedHead, value.requestId].every(x => typeof x === "string" && x.length === 64 && /^[a-f0-9]+$/.test(x))) fail();
+  return { epochHash: value.epochHash, expectedHead: value.expectedHead, requestId: value.requestId, key: validatePlacementKey(value.key) };
+}
+function active(home: string, input: PlacementEffectRequest, port: PlacementCapturePort) {
+  const capture = captureSyncPlacementContext(home, port), journal = readPlacementJournal(capture.home, input.epochHash);
+  if (capture.activeHead !== input.epochHash || journal.epoch.homeHash !== capture.context.homeHash
+    || journal.epoch.generation !== (capture.context.profile as { generation: string }).generation
+    || journal.activation.targetProfile.placementHead !== input.epochHash
+    || canonicalJSON(capture.context.writers) !== canonicalJSON(journal.activation.writers)
+    || canonicalJSON(capture.context.realms.map(({ bindingHash: _hash, ...identity }) => identity))
+      !== canonicalJSON(journal.activation.realms.map(({ bindingHash: _hash, ...identity }) => identity))) fail("changed");
+  const markers = readPlacementRuntimeMarkers(capture.home), profile = validatePlacementProfile(markers.profile);
+  assertPlacementViewAdvance(capture.home, journal.activation, profile, validatePlacementShards(markers.shards, profile));
+  const projection = rebuildPlacementProjection(journal.epoch, journal.records);
+  const source = capture.rows.get(placementKeyId(input.key)); if (!source) fail("changed");
+  return { capture, journal, projection, source };
+}
+type Decision = { kind: "hold"; mode: "policy" | "person" } | { kind: "release" }
+  | { kind: "publication-committed"; outcome: PlacementCommittedOutcome; verify(binding: Readonly<{ effectHash: string; outcome: PlacementCommittedOutcome }>): boolean }
+  | { kind: "publication-ambiguous"; outcome: PlacementAmbiguousOutcome };
+function effect(home: string, raw: PlacementEffectRequest, port: PlacementJournalPort, decision: Decision) {
+  return protectedCall(() => {
+    const input = request(raw), { capture, source } = active(home, input, port);
+    if (port.screen && !port.policyVersion) fail("policy");
+    const fields = { requestId: input.requestId, key: input.key, sourcePlacement: source.sourcePlacement };
+    let partial: Record<string, unknown>;
+    if (decision.kind === "hold") {
+      if (decision.mode === "person") partial = { ...fields, kind: "hold", reason: "person-local" };
+      else {
+        const verdict = outboundPolicyEvaluator(capture.home, port.screen)(source.row as unknown as Record<string, unknown>);
+        if (verdict.ok) fail("policy");
+        partial = { ...fields, kind: "hold", reason: verdict.category };
+      }
+    } else if (decision.kind === "release") {
+      if (source.intrinsicLocal) fail("local");
+      if (!outboundPolicyEvaluator(capture.home, port.screen)(source.row as unknown as Record<string, unknown>).ok) fail("policy");
+      partial = { ...fields, kind: "release" };
+    } else partial = { ...fields, kind: decision.kind, outcome: decision.outcome };
+    const effectHash = hashJSON({ event: partial, expectedHead: input.expectedHead, markerHash: capture.markerHash, contextHash: hashJSON(capture.context) });
+    const event = validatePlacementEvent({ ...partial, effectHash });
+    if (decision.kind === "release" || decision.kind === "hold" && decision.mode === "person") person(port, decision.kind, effectHash, { epochHash: input.epochHash, key: Object.freeze({ ...input.key, realm: Object.freeze({ ...input.key.realm }) }),
+      expectedHead: input.expectedHead, policyHash: capture.context.policyHash });
+    if (decision.kind === "publication-committed") {
+      let verified = false;
+      try { verified = decision.verify(Object.freeze({ effectHash, outcome: structuredClone(decision.outcome) })) === true; } catch { fail("authorization"); }
+      if (!verified) fail("authorization");
+    }
+    capture.assertCurrent();
+    return fenced(capture, mutation => appendPlacementEvent(capture.home, input.epochHash, event, input.expectedHead,
+      { mutation, assertCurrent: capture.assertCurrent }));
+  });
+}
+/** Sticky local placement. Retrying or loosening a policy never invokes the release path. */
+export const holdPlacementRow = (home: string, input: PlacementEffectRequest, port: PlacementJournalPort, mode: "policy" | "person" = "policy") => effect(home, input, port, { kind: "hold", mode });
+export const releasePlacementHold = (home: string, input: PlacementEffectRequest, port: PlacementJournalPort) => effect(home, input, port, { kind: "release" });
+/** Records verified evidence only. This API performs no publication, fetch, git or network operation. */
+export function recordPlacementPublication(home: string, input: PlacementEffectRequest, port: PlacementJournalPort,
+  outcome: PlacementCommittedOutcome, verify: (binding: Readonly<{ effectHash: string; outcome: PlacementCommittedOutcome }>) => boolean) {
+  const copied = memoryPolicySnapshot(outcome); if (!copied) return fail();
+  return effect(home, input, port, { kind: "publication-committed", outcome: copied, verify });
+}
+export function recordPlacementAmbiguity(home: string, input: PlacementEffectRequest, port: PlacementJournalPort, outcome: PlacementAmbiguousOutcome) {
+  const copied = memoryPolicySnapshot(outcome); if (!copied) return fail();
+  return effect(home, input, port, { kind: "publication-ambiguous", outcome: copied });
+}
+/** Rebuilds solely from the private journal, not from any index flag. Pending writes never yield a complete empty result. */
+export function readPlacementProjection(home: string, epochHash: string) {
+  return protectedCall(() => {
+    const journal = readPlacementJournal(home, epochHash); if (journal.pending) fail("pending");
+    const projection = rebuildPlacementProjection(journal.epoch, journal.records);
+    return { epochHash: projection.epochHash, headHash: projection.headHash, sequence: projection.sequence, states: projection.states() };
+  });
+}

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

@@ -0,0 +1,149 @@
+/** Shared internal row materialization. All source/transport authority and effect boundaries belong to the caller. */
+import { createHash } from "node:crypto";
+import { canonicalJSON, hashJSON } from "./generation.ts";
+import { SYNC_SCREEN_MAX_BYTES, SYNC_SCREEN_MAX_ROWS, type OutboundVerdict } from "./sync-screen.ts";
+import type { PlacementCapture } from "./sync-placement-capture.ts";
+import { compilePlacementDependencies, type DependencySource, type VerifiedDependencyEndpoint } from "./sync-placement-dependencies.ts";
+import { compilePlacementGitObjects, type PlannedGitObject } from "./sync-placement-git.ts";
+import { PLACEMENT_DESCRIPTOR_SCHEMA, PLACEMENT_FORMAT } from "./sync-placement-format.ts";
+import { placementKeyId, SyncPlacementJournalError, type PlacementKey, type PlacementRealm } from "./sync-placement-journal-format.ts";
+import type { PlacementProjection } from "./sync-placement-projection.ts";
+import type { PlacementPublicationBundle, PlacementPublicationDecision, PlacementPublicationObject, PlacementPublicationTarget } from "./sync-placement-publication-plan.ts";
+import type { ShardHistory } from "./shard-sync-history.ts";
+import { decodeShardPack, encodeShardPacks, encodeShardManifest, shardSyncRef, type ShardSyncRow, type ShardSyncRealm } from "./shard-sync-format.ts";
+import { verifyPublicPruneWitness, type PublicPruneWitnessV1, type PublicPruneLineage } from "./public-prune-witness.ts";
+import type { Entry } from "./store.ts";
+import type { PruneRow } from "./prune.ts";
+
+export interface PlacementMaterializeTarget {
+  realm: ShardSyncRealm; generation: string; remote?: string; local?: string;
+  fetched: ReadonlySet<string>; localPrunes: ReadonlyMap<string, PruneRow>; pruned: ReadonlySet<string>;
+}
+export interface PlacementMaterializeInput {
+  capture: Pick<PlacementCapture, "rows">; projection: PlacementProjection; generation: string;
+  targets: readonly PlacementMaterializeTarget[]; old: readonly (ShardHistory | undefined)[];
+  verifiedPrunes: ReadonlySet<string>; evaluate(row: unknown): OutboundVerdict;
+  readTree(index: number, head: string): Promise<string>;
+  publisherLineages(index: number, rows: readonly PruneRow[]): ReadonlyMap<string, PublicPruneLineage>;
+  createdUnixSeconds: number; frozen?: PlacementPublicationBundle;
+}
+export interface PlacementMaterializeTargetResult { candidate: ShardHistory; objects: PlannedGitObject[]; commit?: string }
+export interface PlacementMaterializeResult {
+  decisions: PlacementPublicationDecision[]; targets: PlacementMaterializeTargetResult[];
+  plannedTargets: PlacementPublicationTarget[]; objects: PlacementPublicationObject[];
+}
+const digest = (value: Uint8Array | string) => createHash("sha256").update(value).digest("hex");
+const sameRealm = (a: PlacementRealm, b: PlacementRealm) => canonicalJSON(a) === canonicalJSON(b);
+const physical = (target: Pick<PlacementMaterializeTarget, "realm">): PlacementRealm => target.realm.scope === "user" ? {scope:"user"} : {scope:"project",keyHash:digest(target.realm.key)};
+const keyFor = (target: Pick<PlacementMaterializeTarget, "realm">, row: ShardSyncRow): PlacementKey => ({realm:physical(target),id:row.id,rowHash:hashJSON(row)});
+function refuse(): never { throw new Error("placement sync unavailable"); }
+export interface PlacementPruneProofTarget {
+  realm: ShardSyncRealm; generation: string; rows: ReadonlyMap<string, ShardSyncRow>; fetched: ReadonlySet<string>; lineageIds?: ReadonlySet<string>;
+}
+/** Pure predicate only: fetched/lineage membership must already be independently verified by the caller. */
+export function verifiedPlacementPrunes(targets: readonly PlacementPruneProofTarget[]): Set<string> {
+  const verified = new Set<string>();
+  for (const target of targets) for (const row of target.rows.values()) {
+    if (row.op !== "prune" || row.generation !== target.generation) continue;
+    const complete = row.targets.every(item => [item,item.basis].every(ref => target.fetched.has(ref.id) && hashJSON(target.rows.get(ref.id)) === ref.rowHash));
+    if (complete && (target.fetched.has(row.id) || target.lineageIds?.has(row.id))) verified.add(placementKeyId(keyFor(target,row)));
+  }
+  return verified;
+}
+export async function materializePlacementRows(input: PlacementMaterializeInput): Promise<PlacementMaterializeResult> {
+  const {capture,projection,old,frozen,createdUnixSeconds}=input;
+  const workTargets = input.targets.map(target => ({...target,objects:[] as PlannedGitObject[],commit:undefined as string|undefined,candidate:undefined as ShardHistory|undefined}));
+    const sources: DependencySource[] = [], blocked = new Set<string>(), verified = input.verifiedPrunes;
+    let sourceBytes=0;
+    const admit=(row:unknown)=>{const bytes=Buffer.byteLength(canonicalJSON(row));if(sources.length>=SYNC_SCREEN_MAX_ROWS||sourceBytes+bytes>SYNC_SCREEN_MAX_BYTES)throw new SyncPlacementJournalError("bound");sourceBytes+=bytes;};
+    const prunedByTarget = new Map(workTargets.map(target => [target, target.pruned]));
+    for (const source of capture.rows.values()) {
+      const target = workTargets.find(target => sameRealm(physical(target), source.key.realm)); if (!target) refuse();
+      const pruned = prunedByTarget.get(target)!.has(source.key.id) && !target.fetched.has(source.key.id);
+      if (pruned) blocked.add(placementKeyId(source.key));
+      admit(source.row); sources.push({ key: source.key, row: source.row, sourcePlacement: source.sourcePlacement, policy: input.evaluate(source.row), held: !!projection.get(source.key)?.held || !!pruned });
+    }
+    for (const target of workTargets) for (const row of target.localPrunes.values()) {
+      const key = keyFor(target,row); if (sources.some(source => placementKeyId(source.key) === placementKeyId(key))) continue;
+      admit(row); sources.push({ key, row, sourcePlacement: "synced", policy: input.evaluate(row), held: !!projection.get(key)?.held });
+    }
+    // Incoming verified occurrences are selected immutable originals too. Classify them before import so a private
+    // remote goal cannot temporarily authorize a new dependent, and exposure/holds are durable in this same attempt.
+    const seenSources=new Set(sources.map(source=>placementKeyId(source.key)));
+    for(const [index,target]of workTargets.entries())for(const row of old[index]?.rows.values()??[])if(row.op!=="prune"||row.generation===target.generation){
+      const key=keyFor(target,row),id=placementKeyId(key);if(seenSources.has(id))continue;seenSources.add(id);
+      admit(row); sources.push({key,row,sourcePlacement:"synced",policy:input.evaluate(row),held:!!projection.get(key)?.held});
+    }
+    // Strong endpoints are already in sources and current holds cannot be bypassed by past publication. Only
+    // deletion/prune exceptions need a second verified occurrence fact; do not duplicate every historical body.
+    const publicNeeded=new Set<string>();
+    for(const source of sources){const row=source.row as ShardSyncRow;
+      if(row.op==="forget"||row.op==="demote")publicNeeded.add(row.target);
+      if(row.op==="prune")for(const target of row.targets)for(const ref of [target,target.basis])publicNeeded.add(ref.id);
+    }
+    const endpoints: VerifiedDependencyEndpoint[] = workTargets.flatMap((target,index) => [...(old[index]?.rows.values() ?? [])].filter((row): row is Entry => row.op !== "prune"&&publicNeeded.has(row.id)).map(row => ({ key: keyFor(target,row), row })));
+    const descriptorVerdicts = workTargets.map(target => input.evaluate({ schema: PLACEMENT_DESCRIPTOR_SCHEMA, ...target.realm, publicationFormat: PLACEMENT_FORMAT }));
+    const publishes = workTargets.map(() => false);
+    for (const source of sources) {
+      const index = workTargets.findIndex(target => sameRealm(physical(target),source.key.realm));
+      if (!descriptorVerdicts[index]!.ok) source.policy = descriptorVerdicts[index]!;
+    }
+    const sourceMap = new Map(sources.map(source => [placementKeyId(source.key), source]));
+    let decisions: PlacementPublicationDecision[] = [];
+    for (let pass = 0; pass < 2; pass++) {
+      decisions = compilePlacementDependencies({ generation: input.generation, selectedRealms: workTargets.map(physical), rows:sources, publicEndpoints:endpoints,
+        verifiedPrunes:sources.filter(source => verified.has(placementKeyId(source.key))).map(source => source.key) }).map(decision => {
+          const source = sourceMap.get(placementKeyId(decision.key))!;
+          const index=workTargets.findIndex(target=>sameRealm(physical(target),decision.key.realm));
+          const original=old[index]?.rows.get(decision.key.id), published=!!original&&hashJSON(original)===decision.key.rowHash;
+          const reason=blocked.has(placementKeyId(decision.key)) && !projection.get(decision.key)?.held ? "related-local" : decision.reason ?? null;
+          return { ...decision, sourcePlacement:source.sourcePlacement, reason,
+            hold:!decision.eligible&&(reason!=="source-local"||published)&&!projection.get(decision.key)?.held };
+        });
+      let rejected = false;
+      for (const [index,target] of workTargets.entries()) {
+        const files = new Map(old[index]?.files), eligible = new Set(decisions.filter(decision => decision.eligible && sameRealm(decision.key.realm,physical(target))).map(decision => decision.key.id));
+        const publish = descriptorVerdicts[index]!.ok && (!!old[index] || eligible.size > 0); publishes[index] = publish;
+        if (publish) files.set("shard.json", Buffer.from(canonicalJSON({schema:PLACEMENT_DESCRIPTOR_SCHEMA,...target.realm,publicationFormat:PLACEMENT_FORMAT})+"\n"));
+        const additions = sources.filter(source => sameRealm(source.key.realm,physical(target)) && eligible.has(source.key.id) && !old[index]?.rows.has(source.key.id)).map(source => source.row as ShardSyncRow);
+        for (const [path,bytes] of encodeShardPacks(additions)) { const prior = files.get(path); if (prior && !prior.equals(bytes)) refuse(); files.set(path,bytes); }
+        const manifests = new Map(old[index]?.manifests), occurrences = new Map<string,{pack:string;blob:string}>();
+        for (const [path,bytes] of files) if (path.startsWith("rows/")) for (const row of decodeShardPack(path,bytes,target.realm,target.generation))
+          if (!occurrences.has(row.id)) occurrences.set(row.id,{pack:path,blob:createHash("sha1").update(`blob ${bytes.length}\0`).update(bytes).digest("hex")});
+        const native = additions.filter((row):row is PruneRow => row.op==="prune" && row.generation===target.generation);
+        if (native.length) {
+          const lineages = input.publisherLineages(index,native);
+          for (const row of native) {
+            const lineage = lineages.get(row.id), own = occurrences.get(row.id); if (!lineage || !own) refuse();
+            const needed = new Map<string,string>(); for (const item of row.targets) for (const ref of [item,item.basis]) needed.set(ref.id,ref.rowHash);
+            const witnesses = [...needed].sort(([a],[b])=>a.localeCompare(b)).map(([id,rowHash])=>{ const place=occurrences.get(id); if(!place)refuse(); return{id,rowHash,...place}; });
+            const value:PublicPruneWitnessV1={schema:"agent-mem.public-prune-witness/v1",realm:target.realm,prune:row,lineage,pruneOccurrence:own,witnesses};
+            const encoded=encodeShardManifest(value), packs=new Map([own,...witnesses].map(ref=>[ref.pack,{pack:ref.pack,blob:ref.blob,bytes:files.get(ref.pack)!}]));
+            if(verifyPublicPruneWitness(value,{realm:target.realm,packs:[...packs.values()]}).status!=="verified")refuse();
+            const verdict=input.evaluate(value);
+            if(!verdict.ok){const source=sources.find(source=>source.key.id===row.id&&sameRealm(source.key.realm,physical(target)))!;source.policy=verdict;rejected=true;continue;}
+            files.set(encoded.path,encoded.bytes); manifests.set(encoded.path,{path:encoded.path,bytes:encoded.bytes,value,row,eligible:true,commit:"0".repeat(40),blob:createHash("sha1").update(`blob ${encoded.bytes.length}\0`).update(encoded.bytes).digest("hex")});
+          }
+        }
+        target.objects=[];
+        if(publish){
+          const previous=old[index]&&target.remote?{tree:await input.readTree(index,frozen?.root.targets[index]?.expectedRemoteHead??target.remote!),commit:frozen?.root.targets[index]?.expectedRemoteHead??target.remote!}:undefined;
+          const objects=compilePlacementGitObjects(files,frozen?.root.targets[index]?.expectedRemoteHead??target.remote??null,createdUnixSeconds,previous);target.objects=objects.objects;target.commit=objects.commit;
+          for(const [path,manifest]of manifests)if(manifest.commit==="0".repeat(40))manifests.set(path,{...manifest,commit:objects.commit});
+        }else target.commit=target.remote;
+        const rows=new Map(old[index]?.rows);for(const row of additions)rows.set(row.id,row);
+        target.candidate={rows,files,origins:new Map(old[index]?.origins),version:publish?"v3":old[index]?.version??"v3",manifests};
+      }
+      if(!rejected)break;if(pass===1)refuse();
+    }
+    const plannedTargets:PlacementPublicationTarget[]=workTargets.map((target,index)=>{
+      const publish=publishes[index]!,descriptor=target.candidate?.files.get("shard.json");
+      return{realm:physical(target),publish,refHash:digest(shardSyncRef(target.realm)),expectedRemoteHead:frozen?.root.targets[index]?.expectedRemoteHead??target.remote??null,
+        expectedCacheHead:frozen?.root.targets[index]?.expectedCacheHead??target.local??null,descriptorHash:digest(descriptor??Buffer.alloc(0)),
+        exportSetHash:hashJSON([...target.candidate!.rows.values()].map(row=>({id:row.id,rowHash:hashJSON(row)})).sort((a,b)=>a.id.localeCompare(b.id))),
+        tree:publish?target.objects.find(object=>object.type==="tree"&&object.path==="")!.oid:target.remote?frozen?.root.targets[index]?.tree??null:null,commit:target.commit??null};
+    });
+    for(const [index,target]of workTargets.entries())if(!plannedTargets[index]!.publish&&target.remote)plannedTargets[index]!.tree=await input.readTree(index,target.remote);
+    const objects:PlacementPublicationObject[]=workTargets.flatMap((target,targetIndex)=>target.objects.map(object=>({targetIndex,type:object.type,path:object.path === "" ? null : object.path,oid:object.oid,sha256:digest(object.bytes),size:object.bytes.length})));
+    return {decisions,targets:workTargets.map(target=>({candidate:target.candidate!,objects:target.objects,commit:target.commit})),plannedTargets,objects};
+}

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

@@ -0,0 +1,171 @@
+import { types } from "node:util";
+import { canonicalJSON, hashJSON, LOCAL_METADATA_MAX_BYTES } from "./generation.ts";
+import {
+  PLACEMENT_FORMAT, PLACEMENT_PROFILE_SCHEMA, PLACEMENT_SHARDS_SCHEMA,
+  validatePlacementBaseV2, validatePlacementProfile, validatePlacementShards, validatePlacementMarkerTransition,
+  type PlacementProfile,
+} from "./sync-placement-format.ts";
+
+// ponytail: each preview inventory caps writers/realms at 256; larger inventories need a reviewed chunked-plan format before this ceiling is raised.
+const INVENTORY_MAX = 256;
+export const PLACEMENT_ACTIVATION_PLAN_SCHEMA = "agent-mem.sync-placement-activation-plan/v1";
+export interface SyncPlacementWriterAttestation {
+  writerId: string; version: string; pin: string; publicationFormat: typeof PLACEMENT_FORMAT; compatible: true;
+}
+export type SyncPlacementRealmBinding = { scope: "user"; bindingHash: string }
+  | { scope: "project"; keyHash: string; bindingHash: string };
+/** Data-only capture port. Stage 2 must obtain these facts from authoritative inputs again before any effect. */
+export interface SyncPlacementActivationContext {
+  profile: unknown; shards: unknown;
+  homeHash: string; sourceHash: string; aliasesHash: string; policyHash: string;
+  realms: readonly SyncPlacementRealmBinding[];
+  writers: readonly SyncPlacementWriterAttestation[];
+  legacySyncQuiesced: true;
+}
+export interface SyncPlacementActivationPlan {
+  schema: typeof PLACEMENT_ACTIVATION_PLAN_SCHEMA; generation: string; contextHash: string;
+  previousProfileHash: string; previousShardsHash: string; targetProfile: PlacementProfile; targetShardsHash: string;
+  realms: SyncPlacementRealmBinding[]; writers: SyncPlacementWriterAttestation[]; legacySyncQuiesced: true; seal: string;
+}
+export interface SyncPlacementPersonAuthorization {
+  current(): SyncPlacementActivationContext;
+  /** The host authenticates person intent. Neither this callback's binding nor an actor/session string authenticates a caller. */
+  authorize(binding: Readonly<{ seal: string; generation: string; homeHash: string }>): boolean;
+}
+export type SyncPlacementPlanErrorCode = "invalid" | "bound" | "base" | "attestation" | "authorization" | "changed";
+const messages: Record<SyncPlacementPlanErrorCode, string> = {
+  invalid: "sync placement plan is invalid; create and review a new complete plan before continuing",
+  bound: "sync placement plan exceeds supported metadata bounds; use a supported bounded migration before continuing",
+  base: "sync placement activation requires an active v2 public-prune shard base; run the person-authorized migrations first",
+  attestation: "sync placement activation requires compatible exact-pinned writers and quiesced legacy sync; upgrade and attest every sharing writer first",
+  authorization: "sync placement activation validation requires explicit person authorization; review the plan through an authenticated person port",
+  changed: "sync placement activation bindings changed or are unavailable; capture and review a fresh plan before continuing",
+};
+export class SyncPlacementPlanError extends Error {
+  constructor(readonly code: SyncPlacementPlanErrorCode) { super(messages[code]); this.name = "SyncPlacementPlanError"; }
+}
+const fail = (code: SyncPlacementPlanErrorCode = "invalid"): never => { throw new SyncPlacementPlanError(code); };
+const hex = (value: unknown, length = 64): value is string => typeof value === "string" && value.length === length && /^[a-f0-9]+$/.test(value);
+function object(value: unknown, keys: readonly string[]): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value) || types.isProxy(value)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(value)) || Object.getOwnPropertySymbols(value).length) return fail();
+  const fields = Object.getOwnPropertyDescriptors(value);
+  if (Object.keys(fields).length !== keys.length || keys.some(key => !Object.hasOwn(fields, key))) return fail();
+  const result: Record<string, unknown> = {};
+  for (const key of keys) {
+    const field = fields[key]!;
+    if (!("value" in field) || !field.enumerable) return fail();
+    result[key] = field.value;
+  }
+  return result;
+}
+function list(value: unknown): unknown[] {
+  if (!Array.isArray(value) || types.isProxy(value) || Object.getPrototypeOf(value) !== Array.prototype || value.length > INVENTORY_MAX || Object.getOwnPropertySymbols(value).length) return fail("bound");
+  const fields = Object.getOwnPropertyDescriptors(value);
+  if (Object.keys(fields).length !== value.length + 1) return fail();
+  const result: unknown[] = [];
+  for (let at = 0; at < value.length; at++) {
+    const field = fields[String(at)];
+    if (!field || !("value" in field) || !field.enumerable) return fail();
+    result.push(field.value);
+  }
+  return result;
+}
+function bounded(value: unknown): void { if (Buffer.byteLength(canonicalJSON(value)) > LOCAL_METADATA_MAX_BYTES) fail("bound"); }
+function realms(value: unknown): SyncPlacementRealmBinding[] {
+  const result = list(value).map(item => {
+    // Inspect scope without invoking a getter before selecting its closed shape.
+    if (!item || typeof item !== "object" || types.isProxy(item)) return fail();
+    const scope = Object.getOwnPropertyDescriptor(item, "scope")?.value;
+    const row = object(item, scope === "user" ? ["scope", "bindingHash"] : ["scope", "keyHash", "bindingHash"]);
+    if (!hex(row.bindingHash)) return fail();
+    if (row.scope === "user") return { scope: "user" as const, bindingHash: row.bindingHash };
+    if (row.scope !== "project" || !hex(row.keyHash)) return fail();
+    return { scope: "project" as const, keyHash: row.keyHash, bindingHash: row.bindingHash };
+  });
+  const key = (row: SyncPlacementRealmBinding) => row.scope === "user" ? "user" : `project:${row.keyHash}`;
+  result.sort((a,b) => key(a).localeCompare(key(b)));
+  if (new Set(result.map(key)).size !== result.length) return fail();
+  return result;
+}
+function writers(value: unknown): SyncPlacementWriterAttestation[] {
+  const result = list(value).map(item => {
+    const row = object(item, ["writerId", "version", "pin", "publicationFormat", "compatible"]);
+    if (!hex(row.writerId) || !hex(row.pin) || typeof row.version !== "string" || row.version.length > 64
+      || /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/.exec(row.version)?.[0] !== row.version
+      || row.publicationFormat !== PLACEMENT_FORMAT || row.compatible !== true) return fail("attestation");
+    return { writerId: row.writerId, version: row.version, pin: row.pin, publicationFormat: PLACEMENT_FORMAT as typeof PLACEMENT_FORMAT, compatible: true as const };
+  }).sort((a,b) => a.writerId.localeCompare(b.writerId));
+  if (!result.length || new Set(result.map(row => row.writerId)).size !== result.length) return fail("attestation");
+  return result;
+}
+function context(value: unknown) {
+  const row = object(value, ["profile", "shards", "homeHash", "sourceHash", "aliasesHash", "policyHash", "realms", "writers", "legacySyncQuiesced"]);
+  let base: ReturnType<typeof validatePlacementBaseV2>;
+  try { base = validatePlacementBaseV2(row.profile, row.shards); } catch { return fail("base"); }
+  if (![row.homeHash, row.sourceHash, row.aliasesHash, row.policyHash].every(value => hex(value))) return fail();
+  if (row.legacySyncQuiesced !== true) return fail("attestation");
+  const result = { profile: base.profile, shards: base.shards, homeHash: row.homeHash as string, sourceHash: row.sourceHash as string,
+    aliasesHash: row.aliasesHash as string, policyHash: row.policyHash as string, realms: realms(row.realms), writers: writers(row.writers), legacySyncQuiesced: true as const };
+  bounded(result); return result;
+}
+/** Pure preview builder. A sealed data plan is not a bearer capability and performs no activation. */
+export function planSyncPlacementActivation(input: SyncPlacementActivationContext, placementHead: string): SyncPlacementActivationPlan {
+  const before = context(input);
+  if (!hex(placementHead)) return fail();
+  const targetProfile = validatePlacementProfile({ ...before.profile, schema: PLACEMENT_PROFILE_SCHEMA, publicationFormat: PLACEMENT_FORMAT, placementHead });
+  const targetShards = validatePlacementShards({ ...before.shards, schema: PLACEMENT_SHARDS_SCHEMA, selectorRevision: hashJSON(targetProfile), publicationFormat: PLACEMENT_FORMAT, placementHead }, targetProfile);
+  validatePlacementMarkerTransition(before.profile, before.shards, targetProfile, targetShards);
+  const body: Omit<SyncPlacementActivationPlan, "seal"> = { schema: PLACEMENT_ACTIVATION_PLAN_SCHEMA, generation: targetProfile.generation, contextHash: hashJSON(before),
+    previousProfileHash: hashJSON(before.profile), previousShardsHash: hashJSON(before.shards), targetProfile, targetShardsHash: hashJSON(targetShards),
+    realms: before.realms, writers: before.writers, legacySyncQuiesced: true as const };
+  const plan = { ...body, seal: hashJSON(body) }; bounded(plan); return plan;
+}
+/** Validate only the closed plan/seal. Source/authentication facts must be re-proved through the port below. */
+export function validatePlacementPlan(value: unknown): SyncPlacementActivationPlan {
+  const row = object(value, ["schema", "generation", "contextHash", "previousProfileHash", "previousShardsHash", "targetProfile", "targetShardsHash", "realms", "writers", "legacySyncQuiesced", "seal"]);
+  if (row.schema !== PLACEMENT_ACTIVATION_PLAN_SCHEMA || !hex(row.generation, 32)
+    || ![row.contextHash, row.previousProfileHash, row.previousShardsHash, row.targetShardsHash, row.seal].every(value => hex(value)) || row.legacySyncQuiesced !== true) return fail();
+  let targetProfile: PlacementProfile;
+  try { targetProfile = validatePlacementProfile(row.targetProfile); } catch { return fail(); }
+  if (targetProfile.generation !== row.generation) return fail();
+  const body: Omit<SyncPlacementActivationPlan, "seal"> = { schema: PLACEMENT_ACTIVATION_PLAN_SCHEMA, generation: row.generation, contextHash: row.contextHash as string,
+    previousProfileHash: row.previousProfileHash as string, previousShardsHash: row.previousShardsHash as string, targetProfile,
+    targetShardsHash: row.targetShardsHash as string, realms: realms(row.realms), writers: writers(row.writers), legacySyncQuiesced: true as const };
+  if (hashJSON(body) !== row.seal) return fail();
+  const plan = { ...body, seal: row.seal as string }; bounded(plan); return plan;
+}
+/** Person-port validation only: activated:false is intentional. No marker, journal, transport or filesystem effect exists in stage 1. */
+export function validateSyncPlacementActivation(value: unknown, port: SyncPlacementPersonAuthorization): { validated: true; activated: false; plan: SyncPlacementActivationPlan } {
+  const plan = validatePlacementPlan(value);
+  let callbacks: Record<string, unknown>;
+  try { callbacks = object(port, ["current", "authorize"]); } catch { return fail("authorization"); }
+  if (typeof callbacks.current !== "function" || typeof callbacks.authorize !== "function") return fail("authorization");
+  const current = () => { try { return context((callbacks.current as () => unknown)()); } catch { return fail("changed"); } };
+  const before = current(), expected = planSyncPlacementActivation(before, plan.targetProfile.placementHead);
+  if (canonicalJSON(expected) !== canonicalJSON(plan)) return fail("changed");
+  const binding = Object.freeze({ seal: plan.seal, generation: plan.generation, homeHash: before.homeHash });
+  let authorized = false;
+  try { authorized = (callbacks.authorize as (scope: typeof binding) => unknown)(binding) === true; } catch { return fail("authorization"); }
+  if (!authorized) return fail("authorization");
+  if (canonicalJSON(current()) !== canonicalJSON(before)) return fail("changed");
+  return { validated: true, activated: false, plan };
+}
+/** Byte-bound and canonical framing precede parsing; the result still grants no effect authority. */
+export function decodePlacementPlan(bytes: Uint8Array): SyncPlacementActivationPlan {
+  try {
+    if (types.isProxy(bytes) || !types.isUint8Array(bytes)) return fail();
+    const prototype = Object.getPrototypeOf(Uint8Array.prototype);
+    const intrinsic = (key: string) => Object.getOwnPropertyDescriptor(prototype, key)!.get!.call(bytes);
+    const size = intrinsic("byteLength") as number;
+    if (size > LOCAL_METADATA_MAX_BYTES) return fail("bound");
+    const view = new Uint8Array(intrinsic("buffer") as ArrayBuffer, intrinsic("byteOffset") as number, size);
+    const text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(view);
+    const plan = validatePlacementPlan(JSON.parse(text));
+    if (canonicalJSON(plan) + "\n" !== text) return fail();
+    return plan;
+  } catch (error) {
+    if (error instanceof SyncPlacementPlanError) throw error;
+    return fail();
+  }
+}

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

@@ -0,0 +1,79 @@
+import { types } from "node:util";
+import { canonicalJSON } from "./generation.ts";
+import {
+  SyncPlacementJournalError, PLACEMENT_JOURNAL_MAX_RECORDS, placementEpochHash, placementKeyId,
+  validatePlacementEpoch, validatePlacementKey, validatePlacementRecord,
+  type PlacementEpoch, type PlacementKey, type PlacementRecord, type PlacementHoldReason,
+  type PlacementAmbiguousOutcome, type PlacementCommittedOutcome,
+} from "./sync-placement-journal-format.ts";
+
+export type PlacementAttemptState = (PlacementAmbiguousOutcome & { status: "ambiguous" }) | (PlacementCommittedOutcome & { status: "committed" });
+export interface PlacementProjectedState {
+  key: PlacementKey; sourcePlacement: "local" | "synced"; held: boolean; reasons: PlacementHoldReason[];
+  exposure: "unknown" | "published"; attempts: PlacementAttemptState[];
+}
+const copy = (value: PlacementProjectedState): PlacementProjectedState => ({ ...value, key: validatePlacementKey(value.key), reasons: [...value.reasons], attempts: value.attempts.map(attempt => ({ ...attempt })) });
+const identity = (key: PlacementKey) => canonicalJSON([key.realm, key.id]);
+/** Data projection only. Journal fields and committed-outcome syntax are not person or remote-proof credentials. */
+export class PlacementProjection {
+  readonly #epochHash: string;
+  #sequence = 0;
+  #headHash: string;
+  readonly #states = new Map<string, PlacementProjectedState>();
+  readonly #rowHashes = new Map<string, string>();
+  readonly #requests = new Map<string, PlacementRecord>();
+  constructor(epoch: PlacementEpoch) { this.#epochHash = placementEpochHash(validatePlacementEpoch(epoch)); this.#headHash = this.#epochHash; }
+  get epochHash(): string { return this.#epochHash; }
+  get sequence(): number { return this.#sequence; }
+  get headHash(): string { return this.#headHash; }
+  request(requestId: string): PlacementRecord | undefined { const record = this.#requests.get(requestId); return record ? validatePlacementRecord(record) : undefined; }
+  get(key: PlacementKey): PlacementProjectedState | undefined {
+    const normalized = validatePlacementKey(key), priorHash = this.#rowHashes.get(identity(normalized));
+    if (priorHash !== undefined && priorHash !== normalized.rowHash) throw new SyncPlacementJournalError("conflict");
+    const state = this.#states.get(placementKeyId(normalized)); return state ? copy(state) : undefined;
+  }
+  states(): PlacementProjectedState[] { return [...this.#states].sort(([a], [b]) => a.localeCompare(b)).map(([, state]) => copy(state)); }
+  apply(value: unknown): void {
+    const record = validatePlacementRecord(value);
+    if (record.epochHash !== this.#epochHash) throw new SyncPlacementJournalError("corrupt");
+    if (this.#requests.has(record.requestId)) throw new SyncPlacementJournalError("conflict");
+    if (record.sequence !== this.#sequence + 1 || record.previousHash !== this.#headHash) throw new SyncPlacementJournalError("corrupt");
+    const id = placementKeyId(record.key), rowIdentity = identity(record.key), oldHash = this.#rowHashes.get(rowIdentity);
+    if (oldHash !== undefined && oldHash !== record.key.rowHash) throw new SyncPlacementJournalError("conflict");
+    const prior = this.#states.get(id), next: PlacementProjectedState = prior ? copy(prior) : {
+      key: record.key, sourcePlacement: record.sourcePlacement, held: false, reasons: [], exposure: "unknown", attempts: [],
+    };
+    next.sourcePlacement = record.sourcePlacement;
+    if (record.kind === "hold") next.reasons = [...new Set([...next.reasons, record.reason])].sort();
+    else if (record.kind === "release") next.reasons = [];
+    else {
+      const outcome = record.outcome, at = next.attempts.findIndex(attempt => attempt.attemptHash === outcome.attemptHash), known = next.attempts[at];
+      if (known && (known.remoteHash !== outcome.remoteHash || known.refHash !== outcome.refHash)) throw new SyncPlacementJournalError("conflict");
+      if (record.kind === "publication-committed") {
+        if (known?.status === "committed" && (known.commit !== record.outcome.commit || known.proofHash !== record.outcome.proofHash)) throw new SyncPlacementJournalError("conflict");
+        const committed: PlacementAttemptState = { ...record.outcome, status: "committed" };
+        if (at < 0) next.attempts.push(committed); else next.attempts[at] = committed;
+        next.exposure = "published";
+      } else if (known?.status !== "committed") {
+        const ambiguous: PlacementAttemptState = { ...record.outcome, status: "ambiguous" };
+        if (at < 0) next.attempts.push(ambiguous); else next.attempts[at] = ambiguous;
+      }
+      next.attempts.sort((a, b) => a.attemptHash.localeCompare(b.attemptHash));
+    }
+    next.held = next.reasons.length > 0;
+    // All format/chain/request/source/outcome checks precede mutation: a rejected record never advances the frontier.
+    this.#states.set(id, next); this.#rowHashes.set(rowIdentity, record.key.rowHash); this.#requests.set(record.requestId, record);
+    this.#sequence = record.sequence; this.#headHash = record.seal;
+  }
+}
+export function rebuildPlacementProjection(epoch: PlacementEpoch, records: readonly unknown[]): PlacementProjection {
+  if (types.isProxy(records) || !Array.isArray(records) || Object.getPrototypeOf(records) !== Array.prototype || Object.getOwnPropertySymbols(records).length || records.length > PLACEMENT_JOURNAL_MAX_RECORDS) throw new SyncPlacementJournalError("bound");
+  if (Object.getOwnPropertyNames(records).length !== records.length + 1) throw new SyncPlacementJournalError("invalid");
+  const result = new PlacementProjection(epoch);
+  for (let index = 0; index < records.length; index++) {
+    const descriptor = Object.getOwnPropertyDescriptor(records, String(index));
+    if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) throw new SyncPlacementJournalError("invalid");
+    result.apply(descriptor.value);
+  }
+  return result;
+}