@staix/agent-mem 0.20.3 → 0.21.0

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)));
+}

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

@@ -0,0 +1,182 @@
+import { types } from "node:util";
+import { canonicalJSON, hashJSON } from "./generation.ts";
+import { SHARDED_V2_FIELDS } from "./shard.ts";
+import type { SourcePrefix } from "./migrate.ts";
+import type { ShardSyncRealm } from "./shard-sync-format.ts";
+
+export const PLACEMENT_FORMAT = "agent-mem.sync-placement/v1";
+export const PLACEMENT_PROFILE_SCHEMA = "agent-mem.profile/v3";
+export const PLACEMENT_SHARDS_SCHEMA = "agent-mem.shards/v3";
+export const PLACEMENT_DESCRIPTOR_SCHEMA = "agent-mem.shard-sync/v3";
+const FOREIGN_FORMAT = "agent-mem.public-prune-witness/v1", METADATA_MAX = 256 * 1024, WIRE_MAX = 64 * 1024, SOURCES_MAX = 20_000;
+
+export class SyncPlacementFormatError extends Error {
+  readonly code = "sync_placement_format";
+  constructor() {
+    super("Sync placement metadata is invalid, unsupported or exceeds its bound. Inspect the saved activation plan and use compatible writers before retrying.");
+    this.name = "SyncPlacementFormatError";
+  }
+}
+export interface PlacementProfile {
+  schema: typeof PLACEMENT_PROFILE_SCHEMA; kind: "generation"; generation: string;
+  foreignPruneFormat: typeof FOREIGN_FORMAT; pruneInputSetHash: string;
+  publicationFormat: typeof PLACEMENT_FORMAT; placementHead: string;
+}
+export interface PlacementShardsFields {
+  generation: string; phase: "active"; selectorRevision: string;
+  sourceGeneration?: string; sources: SourcePrefix[]; machine: { id: string; label: string };
+  legacyCommit?: string; deadLeasesRemoved?: { lease: string; at: string }[];
+}
+export interface PlacementShards extends PlacementShardsFields {
+  schema: typeof PLACEMENT_SHARDS_SCHEMA; publicationFormat: typeof PLACEMENT_FORMAT; placementHead: string;
+}
+export interface PlacementBaseV2 {
+  profile: { schema: "agent-mem.profile/v2"; kind: "generation"; generation: string; foreignPruneFormat: typeof FOREIGN_FORMAT; pruneInputSetHash: string };
+  shards: PlacementShardsFields & { schema: "agent-mem.shards/v2" };
+}
+export type PlacementDescriptor = { schema: typeof PLACEMENT_DESCRIPTOR_SCHEMA; publicationFormat: typeof PLACEMENT_FORMAT }
+  & ({ scope: "user" } | { scope: "project"; key: string });
+export interface PlacementMarkers { profile: PlacementProfile; shards: PlacementShards }
+const fail = (): never => { throw new SyncPlacementFormatError(); };
+const hex = (value: unknown, width: number): value is string => typeof value === "string" && value.length === width && new RegExp(`^[a-f0-9]{${width}}$`).test(value);
+const has = (value: Record<string, unknown>, key: string): boolean => Object.hasOwn(value, key);
+function record(value: unknown, required: readonly string[], optional: readonly string[] = []): Record<string, unknown> {
+  if (!value || typeof value !== "object" || types.isProxy(value) || Array.isArray(value)) return fail();
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null || Object.getOwnPropertySymbols(value).length) return fail();
+  const keys = Object.getOwnPropertyNames(value), allowed = new Set([...required, ...optional]);
+  if (keys.length < required.length || keys.length > allowed.size || required.some(key => !Object.hasOwn(value, key))) return fail();
+  const copy: Record<string, unknown> = Object.create(null);
+  for (const key of keys) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!allowed.has(key) || !descriptor || !("value" in descriptor) || !descriptor.enumerable) return fail();
+    copy[key] = descriptor.value;
+  }
+  return copy;
+}
+function text(value: unknown, maximum = METADATA_MAX): string {
+  if (typeof value !== "string" || Buffer.byteLength(value) > maximum) return fail();
+  return value;
+}
+function integer(value: unknown): number { if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) return fail(); return value; }
+function bounded<T>(value: T, maximum = METADATA_MAX): T { if (Buffer.byteLength(canonicalJSON(value) + "\n") > maximum) return fail(); return value; }
+function list(value: unknown, maximum: number): unknown[] {
+  if (types.isProxy(value) || !Array.isArray(value) || Object.getPrototypeOf(value) !== Array.prototype || Object.getOwnPropertySymbols(value).length) return fail();
+  const length = Object.getOwnPropertyDescriptor(value, "length")?.value;
+  if (!Number.isSafeInteger(length) || length < 0 || length > maximum || Object.getOwnPropertyNames(value).length !== length + 1) return fail();
+  const result: unknown[] = [];
+  for (let index = 0; index < length; index++) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+    if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) return fail();
+    result.push(descriptor.value);
+  }
+  return result;
+}
+function sourcePrefixes(value: unknown): SourcePrefix[] {
+  const result: SourcePrefix[] = [], seen = new Set<string>(); let bytes = 2;
+  for (const input of list(value, SOURCES_MAX)) {
+    const row = record(input, ["source", "path", "offset", "hash", "tailBytes"], ["commit", "stamp"]);
+    if (typeof row.source !== "string" || !["legacy-local", "legacy-main", "generation"].includes(row.source)) return fail();
+    const path = text(row.path);
+    if (/^(log|local)\/[A-Za-z0-9][A-Za-z0-9._-]*\.jsonl$/.exec(path)?.[0] !== path || row.source === "legacy-main" && !path.startsWith("log/")) return fail();
+    if (!hex(row.hash, 64) || (row.source === "legacy-main" ? !hex(row.commit, 40) : has(row, "commit"))) return fail();
+    const source: SourcePrefix = { source: row.source, path, offset: integer(row.offset), hash: row.hash as string, tailBytes: integer(row.tailBytes) };
+    if (has(row, "commit")) source.commit = row.commit as string;
+    if (has(row, "stamp")) { source.stamp = text(row.stamp); if (source.stamp.length > 1024) return fail(); }
+    const key = `${source.source}:${source.path}`; if (seen.has(key)) return fail(); seen.add(key);
+    bytes += Buffer.byteLength(canonicalJSON(source)) + 1; if (bytes > METADATA_MAX) return fail(); result.push(source);
+  }
+  return result;
+}
+function shardFields(value: Record<string, unknown>, profile: { generation: string }): PlacementShardsFields {
+  if (value.phase !== "active" || value.generation !== profile.generation || !hex(value.selectorRevision, 64)) return fail();
+  const machine = record(value.machine, ["id", "label"]); if (!hex(machine.id, 16)) return fail();
+  const result: PlacementShardsFields = { generation: profile.generation, phase: "active", selectorRevision: value.selectorRevision,
+    sources: sourcePrefixes(value.sources), machine: { id: machine.id, label: text(machine.label) } };
+  if (has(value, "sourceGeneration")) { if (value.sourceGeneration !== profile.generation) return fail(); result.sourceGeneration = profile.generation; }
+  if (has(value, "legacyCommit")) { if (!hex(value.legacyCommit, 40)) return fail(); result.legacyCommit = value.legacyCommit; }
+  if (has(value, "deadLeasesRemoved")) {
+    const audits: { lease: string; at: string }[] = []; let bytes = 2;
+    for (const input of list(value.deadLeasesRemoved, 128)) {
+      const audit = record(input, ["lease", "at"]), lease = text(audit.lease), at = text(audit.at);
+      if (/^[1-9][0-9]*-[a-f0-9]{64}\.json$/.exec(lease)?.[0] !== lease || !Number.isFinite(Date.parse(at)) || new Date(at).toISOString() !== at) return fail();
+      const row = { lease, at }; bytes += Buffer.byteLength(canonicalJSON(row)) + 1; if (bytes > METADATA_MAX) return fail(); audits.push(row);
+    }
+    result.deadLeasesRemoved = audits;
+  }
+  return result;
+}
+function checked<T>(work: () => T): T { try { return work(); } catch { return fail(); } }
+export function validatePlacementProfile(value: unknown): PlacementProfile {
+  return checked<PlacementProfile>(() => {
+    const row = record(value, ["schema", "kind", "generation", "foreignPruneFormat", "pruneInputSetHash", "publicationFormat", "placementHead"]);
+    if (row.schema !== PLACEMENT_PROFILE_SCHEMA || row.kind !== "generation" || !hex(row.generation, 32) || row.foreignPruneFormat !== FOREIGN_FORMAT || !hex(row.pruneInputSetHash, 64) || row.publicationFormat !== PLACEMENT_FORMAT || !hex(row.placementHead, 64)) return fail();
+    return bounded({ schema: PLACEMENT_PROFILE_SCHEMA, kind: "generation", generation: row.generation, foreignPruneFormat: FOREIGN_FORMAT,
+      pruneInputSetHash: row.pruneInputSetHash, publicationFormat: PLACEMENT_FORMAT, placementHead: row.placementHead });
+  });
+}
+export function validatePlacementShards(value: unknown, profile: PlacementProfile): PlacementShards {
+  return checked<PlacementShards>(() => {
+    const bound = validatePlacementProfile(profile), row = record(value, ["schema", "generation", "phase", "selectorRevision", "sources", "machine", "publicationFormat", "placementHead"], ["sourceGeneration", "legacyCommit", "deadLeasesRemoved"]);
+    if (row.schema !== PLACEMENT_SHARDS_SCHEMA || row.publicationFormat !== PLACEMENT_FORMAT || row.placementHead !== bound.placementHead || row.selectorRevision !== hashJSON(bound)) return fail();
+    return bounded({ ...shardFields(row, bound), schema: PLACEMENT_SHARDS_SCHEMA, publicationFormat: PLACEMENT_FORMAT, placementHead: bound.placementHead });
+  });
+}
+export function validatePlacementDescriptor(value: unknown, expectedRealm?: ShardSyncRealm): PlacementDescriptor {
+  return checked<PlacementDescriptor>(() => {
+    const row = record(value, ["schema", "scope", "publicationFormat"], ["key"]);
+    if (row.schema !== PLACEMENT_DESCRIPTOR_SCHEMA || row.publicationFormat !== PLACEMENT_FORMAT) return fail();
+    let result: PlacementDescriptor;
+    if (row.scope === "user" && !has(row, "key")) result = { schema: PLACEMENT_DESCRIPTOR_SCHEMA, scope: "user", publicationFormat: PLACEMENT_FORMAT };
+    else if (row.scope === "project" && typeof row.key === "string" && row.key.length) result = { schema: PLACEMENT_DESCRIPTOR_SCHEMA, scope: "project", key: text(row.key, WIRE_MAX), publicationFormat: PLACEMENT_FORMAT };
+    else return fail();
+    if (expectedRealm !== undefined) {
+      const expected = record(expectedRealm, ["scope"], ["key"]);
+      if (expected.scope !== result.scope || result.scope === "user" && has(expected, "key") || result.scope === "project" && expected.key !== result.key) return fail();
+    }
+    return bounded(result, WIRE_MAX);
+  });
+}
+export function validatePlacementBaseV2(profile: unknown, shards: unknown): PlacementBaseV2 {
+  return checked<PlacementBaseV2>(() => {
+    const p = record(profile, ["schema", "kind", "generation", "foreignPruneFormat", "pruneInputSetHash"]);
+    if (p.schema !== "agent-mem.profile/v2" || p.kind !== "generation" || !hex(p.generation, 32) || p.foreignPruneFormat !== FOREIGN_FORMAT || !hex(p.pruneInputSetHash, 64)) return fail();
+    const normalized: PlacementBaseV2["profile"] = { schema: "agent-mem.profile/v2", kind: "generation", generation: p.generation, foreignPruneFormat: FOREIGN_FORMAT, pruneInputSetHash: p.pruneInputSetHash };
+    // Read imported constants inside the function: generation/shard guard imports may form a module cycle.
+    const s = record(shards, ["schema", "generation", "phase", "selectorRevision", "sources", "machine"], SHARDED_V2_FIELDS.filter(key => !["schema", "generation", "phase", "selectorRevision", "sources", "machine"].includes(key)));
+    if (s.schema !== "agent-mem.shards/v2" || s.selectorRevision !== hashJSON(normalized)) return fail();
+    return { profile: bounded(normalized), shards: bounded({ ...shardFields(s, normalized), schema: "agent-mem.shards/v2" }) };
+  });
+}
+/** Placement upgrade only. Shape/authority checks remain the responsibility of the exact marker-pair validator. */
+export function validatePlacementVersionTransition(fromSchema: unknown, toSchema: unknown): void {
+  const families = ["agent-mem.profile", "agent-mem.shards", "agent-mem.shard-sync"];
+  for (const family of families) if (toSchema === `${family}/v3` && [1, 2, 3].some(version => fromSchema === `${family}/v${version}`)) return;
+  fail();
+}
+export function validatePlacementMarkerTransition(oldProfile: unknown, oldShards: unknown, newProfile: unknown, newShards: unknown): PlacementMarkers {
+  return checked<PlacementMarkers>(() => {
+    const base = validatePlacementBaseV2(oldProfile, oldShards), profile = validatePlacementProfile(newProfile), shards = validatePlacementShards(newShards, profile);
+    const { schema: _p, publicationFormat: _pf, placementHead: _ph, ...profileRest } = profile;
+    const { schema: _bp, ...baseProfileRest } = base.profile;
+    const { schema: _s, selectorRevision: _sr, publicationFormat: _sf, placementHead: _sh, ...shardsRest } = shards;
+    const { schema: _bs, selectorRevision: _bsr, ...baseShardsRest } = base.shards;
+    if (canonicalJSON(profileRest) !== canonicalJSON(baseProfileRest) || canonicalJSON(shardsRest) !== canonicalJSON(baseShardsRest)) return fail();
+    return { profile, shards };
+  });
+}
+function decode<T>(bytes: Uint8Array, maximum: number, validate: (value: unknown) => T): T {
+  return checked(() => {
+    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 || size > maximum) return fail();
+    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), result = validate(JSON.parse(text));
+    if (canonicalJSON(result) + "\n" !== text) return fail(); return result;
+  });
+}
+export const decodePlacementProfile = (bytes: Uint8Array): PlacementProfile => decode(bytes, METADATA_MAX, validatePlacementProfile);
+export const decodePlacementShards = (bytes: Uint8Array, profile: PlacementProfile): PlacementShards => decode(bytes, METADATA_MAX, value => validatePlacementShards(value, profile));
+export const decodePlacementDescriptor = (bytes: Uint8Array, expectedRealm?: ShardSyncRealm): PlacementDescriptor => decode(bytes, WIRE_MAX, value => validatePlacementDescriptor(value, expectedRealm));

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

@@ -0,0 +1,95 @@
+/** Pure Git object planning. Bytes are unchanged object bodies; no object is installed or published here. */
+import { createHash } from "node:crypto";
+import { types } from "node:util";
+import { PUBLIC_PRUNE_REPLAY_MAX_BYTES } from "./public-prune-input-chain.ts";
+import { decodePlacementTransportDescriptor, decodeShardManifest, isShardManifestPath, SHARD_PACK_MAX_BYTES, type ShardSyncRealm } from "./shard-sync-format.ts";
+
+export interface PlannedGitObject { type: "blob" | "tree" | "commit"; oid: string; bytes: Buffer; path: string | null }
+export interface PlacementGitObjects { objects: PlannedGitObject[]; tree: string; commit: string }
+export class PlacementGitObjectError extends Error {
+  constructor() { super("Sync placement Git objects are invalid or exceed supported bounds; rebuild the exact verified publication plan."); this.name = "PlacementGitObjectError"; }
+}
+function fail(): never { throw new PlacementGitObjectError(); }
+const oid = (v: unknown): v is string => typeof v === "string" && v.length === 40 && /^[a-f0-9]+$/.test(v);
+const PACK = /^rows\/([a-f0-9]{64})\/([a-f0-9]{64})\.jsonl$/;
+const hash = (v: Uint8Array) => createHash("sha256").update(v).digest("hex");
+const typedArrayPrototype = Object.getPrototypeOf(Uint8Array.prototype);
+const getBuffer = Object.getOwnPropertyDescriptor(typedArrayPrototype, "buffer")!.get!;
+const getOffset = Object.getOwnPropertyDescriptor(typedArrayPrototype, "byteOffset")!.get!;
+const getLength = Object.getOwnPropertyDescriptor(typedArrayPrototype, "byteLength")!.get!;
+const mapSize = Object.getOwnPropertyDescriptor(Map.prototype, "size")!.get!;
+interface TreeNode { directories: Map<string, TreeNode>; blobs: Map<string, string> }
+function node(): TreeNode { return { directories: new Map(), blobs: new Map() }; }
+function object(type: PlannedGitObject["type"], bytes: Buffer, path: string | null): PlannedGitObject {
+  return { type, oid: createHash("sha1").update(`${type} ${bytes.length}\0`).update(bytes).digest("hex"), bytes, path };
+}
+/** Exact Git object bodies and identities, with frozen commit metadata and no-op tree reuse.
+ * Retained public bytes share the existing replay bound; new source's separate 8MiB allowance is the caller's proof. */
+export function compilePlacementGitObjects(files: ReadonlyMap<string, Uint8Array>, parent: string | null, createdUnixSeconds: number,
+  previous?: { tree: string; commit: string }): PlacementGitObjects {
+  try { return compile(files, parent, createdUnixSeconds, previous); } catch { return fail(); }
+}
+function compile(files: ReadonlyMap<string, Uint8Array>, parent: string | null, createdUnixSeconds: number,
+  previous?: { tree: string; commit: string }): PlacementGitObjects {
+  if (!files || typeof files !== "object" || types.isProxy(files) || Object.getPrototypeOf(files) !== Map.prototype
+    || !Number.isSafeInteger(createdUnixSeconds) || createdUnixSeconds < 0 || parent !== null && !oid(parent)) return fail();
+  const count = mapSize.call(files);
+  if (!Number.isSafeInteger(count) || count < 1 || count > 20000) return fail();
+  if (previous !== undefined) {
+    if (!previous || typeof previous !== "object" || types.isProxy(previous) || Object.getOwnPropertySymbols(previous).length) return fail();
+    const fields = Object.getOwnPropertyDescriptors(previous);
+    if (Object.keys(fields).sort().join() !== "commit,tree" || !fields.tree || !fields.commit || !("value" in fields.tree) || !("value" in fields.commit)
+      || !oid(fields.tree.value) || !oid(fields.commit.value)) return fail();
+    previous = { tree: fields.tree.value, commit: fields.commit.value };
+  }
+  const entries: { path: string; bytes: Buffer }[] = []; let total = 0;
+  for (const [path, value] of Map.prototype.entries.call(files) as Iterable<[unknown, unknown]>) {
+    if (typeof path !== "string" || types.isProxy(value) || !(value instanceof Uint8Array)) return fail();
+    const pack = PACK.exec(path), validPack = pack?.[0] === path;
+    if (path !== "shard.json" && !validPack && !isShardManifestPath(path)) return fail();
+    const length = getLength.call(value) as number, maximum = validPack ? SHARD_PACK_MAX_BYTES : 64 * 1024;
+    if (length < 1 || length > maximum || (total += length) > PUBLIC_PRUNE_REPLAY_MAX_BYTES) return fail();
+    const bytes = Buffer.from(Buffer.from(getBuffer.call(value) as ArrayBuffer, getOffset.call(value) as number, length));
+    if (bytes.at(-1) !== 10 || validPack && hash(bytes) !== pack![2]) return fail();
+    if (isShardManifestPath(path)) decodeShardManifest(path, bytes);
+    if (path === "shard.json") {
+      const parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)) as Record<string, unknown>;
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return fail();
+      const realm: ShardSyncRealm = parsed.scope === "user" ? { scope: "user" }
+        : parsed.scope === "project" && typeof parsed.key === "string" ? { scope: "project", key: parsed.key } : fail();
+      decodePlacementTransportDescriptor(bytes, realm);
+    }
+    entries.push({ path, bytes });
+  }
+  if (entries.length !== count || !entries.some(entry => entry.path === "shard.json")) return fail();
+  entries.sort((a,b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+  const objects: PlannedGitObject[] = [], trees: PlannedGitObject[] = [], root = node();
+  for (const entry of entries) {
+    const blob = object("blob", entry.bytes, entry.path); objects.push(blob);
+    const parts = entry.path.split("/"); let target = root;
+    for (const name of parts.slice(0, -1)) { if (target.blobs.has(name)) return fail(); let next = target.directories.get(name); if (!next) target.directories.set(name, next = node()); target = next; }
+    const name = parts.at(-1)!; if (target.directories.has(name) || target.blobs.has(name)) return fail(); target.blobs.set(name, blob.oid);
+  }
+  const buildTree = (tree: TreeNode, path: string): string => {
+    const children: { name: string; oid: string; directory: boolean }[] = [...tree.blobs].map(([name, id]) => ({ name, oid: id, directory: false }));
+    for (const [name, directory] of [...tree.directories].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0))
+      children.push({ name, oid: buildTree(directory, path ? `${path}/${name}` : name), directory: true });
+    children.sort((a,b) => Buffer.compare(Buffer.from(a.name + (a.directory ? "/" : "")), Buffer.from(b.name + (b.directory ? "/" : ""))));
+    let length = 0; const chunks: Buffer[] = [];
+    for (const child of children) {
+      const prefix = Buffer.from(`${child.directory ? "40000" : "100644"} ${child.name}\0`);
+      length += prefix.length + 20; if (length > SHARD_PACK_MAX_BYTES) return fail(); chunks.push(prefix, Buffer.from(child.oid, "hex"));
+    }
+    const result = object("tree", Buffer.concat(chunks, length), path); trees.push(result); return result.oid;
+  };
+  const tree = buildTree(root, "");
+  trees.sort((a,b) => (b.path ? b.path.split("/").length : 0) - (a.path ? a.path.split("/").length : 0)
+    || (a.path! < b.path! ? -1 : a.path! > b.path! ? 1 : 0));
+  objects.push(...trees);
+  if (previous?.tree === tree) return { objects, tree, commit: previous.commit };
+  const identity = `agent-mem <agent-mem@sync.invalid> ${createdUnixSeconds} +0000`;
+  const body = Buffer.from(`tree ${tree}\n${parent === null ? "" : `parent ${parent}\n`}author ${identity}\ncommitter ${identity}\n\nmemory: placement shard append\n`);
+  if (body.length > 64 * 1024) return fail();
+  const commit = object("commit", body, null); objects.push(commit);
+  return { objects, tree, commit: commit.oid };
+}