@1agh/maude 0.60.3 → 0.60.5

package/apps/studio/sync/file-membership.ts

@@ -0,0 +1,290 @@
+// The file plane's WHOLE membership policy — one positive classifier.
+//
+// Sync's unit used to be a canvas, and a file travelled iff some canvas
+// claimed it by name. A fresh link of a real project delivered 79/79 canvases
+// and lost 103 files — the design system's assets, its token stylesheets,
+// `_brand-css.ts` (→ `TypeError: Importing a module script failed`), both
+// docs (RCA: issue-fresh-link-gets-canvases-but-not-the-design-system). Every
+// fix so far added a per-file-kind lane; the growth was the bug. This module
+// replaces the taxonomy: membership in the manifest-driven file plane
+// (Plane B) is decided HERE, positively, and nowhere else.
+//
+// BREAKER's honest test, from the binding debate
+// (kg: maude/sync-two-plane-manifest-architecture): "That manifest collapses
+// into whole-folder with extra steps — if the classifier ends up as
+// everything-except-the-exclusion-regex, I have paid a manifest complexity
+// for zero safety. The honest test before building: can the team enumerate
+// the versioned classes POSITIVELY?" This module IS that enumeration:
+//
+//   canvas-owned   → Plane A (the per-canvas Yjs CRDT docs), NEVER Plane B.
+//                    A canvas body (`.tsx` inside a canvas group) and its
+//                    named sidecars (`.meta.json`, the same-named sibling
+//                    `.css`, `.annotations.svg`). Plane disjointness is
+//                    enforced at the SOURCE — these never enter a manifest —
+//                    and tested, because a second transport under a CRDT lane
+//                    is how a converged edit gets clobbered by a stale copy.
+//   inert-media    → images / fonts / video / audio / svg. Flows freely.
+//   companion-text → css / md. Flows freely.
+//   code-module    → ts / tsx / js / mjs outside canvas bodies. Flows ONLY
+//                    through the owner-hub gate: the receiver admits it when
+//                    its STORED hub record says `role === 'owner'` (or the
+//                    hub is the loopback cell pairing) — never on a
+//                    hub-supplied claim.
+//   never          → `config.json` at the design root (it names the hub URL
+//                    and the canvas groups — a synced config is a hub
+//                    rewriting its own trust anchors), everything the DDR-115
+//                    runtime-state taxonomy matches, and EVERYTHING not
+//                    positively claimed above. Default-closed: an extension
+//                    not listed here does not travel.
+//
+// THE RECEIVER RE-VALIDATES EVERY PATH (ATTACKER's invariant, same debate):
+// a hub-supplied `class` field is a hint for reporting, never authority —
+// each side classifies against its OWN tree and config before a byte moves.
+//
+// ⚠ MIRRORED in `apps/hub/src/file-membership.mjs` (the doc-namespace
+// precedent). The hub image installs frozen against its own bun.lock and must
+// not reach into apps/studio, so the logic is duplicated rather than shared,
+// and the two are pinned to each other by
+// `test/sync-file-membership.test.ts`, which imports the hub's `.mjs` and
+// asserts both agree over an adversarial corpus. Change one, change the other.
+//
+// ⚠ FOURTH COPY, WITH A TRIPWIRE. `isRuntimeStateRel` below replicates
+// `git/service.ts` `isMaudeRuntimeState` instead of importing it — importing
+// would drag the git surface into the hub mirror's parity story. Three copies
+// of the DDR-115 list already exist (git/service.ts, cli/lib/
+// gitignore-block.mjs, the repo .gitignore) and they have drifted silently
+// before; this copy is pinned by a test that imports BOTH and asserts
+// agreement on a fixture list, which turns the drift into a unit-testable
+// bug. The debate accepted the 4th copy knowingly, on that condition.
+
+/** A `canvasGroups[]` entry, as loose as the config actually is — mirrors
+ *  `canvas-path.ts`'s `CanvasGroupLike` (declared locally so this module,
+ *  like its hub mirror, is dependency-free). */
+export interface CanvasGroupLike {
+  path?: string;
+}
+
+export type FileClass = 'canvas-owned' | 'inert-media' | 'companion-text' | 'code-module' | 'never';
+
+/** The classes the file plane actually carries. `canvas-owned` is Plane A's;
+ *  `never` is nobody's. */
+export const FILE_PLANE_CLASSES = ['inert-media', 'companion-text', 'code-module'] as const;
+export type FilePlaneClass = (typeof FILE_PLANE_CLASSES)[number];
+
+export function isFilePlaneClass(c: FileClass): c is FilePlaneClass {
+  return c === 'inert-media' || c === 'companion-text' || c === 'code-module';
+}
+
+/** Max relative-path length (matches the hub's checkout shape cap). */
+export const MAX_REL_LEN = 512;
+
+/** Max designRoot-relative depth (matches the hub's 8-segment cap). */
+export const MAX_SEGMENTS = 8;
+
+// The positive extension enumerations. Everything is lowercase; the lookup
+// lowercases first — a DS legitimately ships `…P1020428.JPG`.
+const INERT_MEDIA_EXTS = new Set([
+  'png',
+  'jpg',
+  'jpeg',
+  'webp',
+  'gif',
+  'avif',
+  'svg',
+  'mp4',
+  'webm',
+  'mov',
+  'm4v',
+  'mp3',
+  'wav',
+  'm4a',
+  'aac',
+  'ogg',
+  'woff2',
+  'woff',
+  'ttf',
+  'otf',
+]);
+const COMPANION_TEXT_EXTS = new Set(['css', 'md', 'srt']);
+const CODE_MODULE_EXTS = new Set(['ts', 'tsx', 'js', 'mjs']);
+
+/**
+ * Maude's OWN sidecar vocabulary, positively enumerated by full suffix —
+ * never bare `.json` (that stays default-closed; a manifest must not be able
+ * to land arbitrary json, least of all a config). Found by the Task-12
+ * acceptance run on the real alligators tree: `assets/<sha8>.photo.json`
+ * (non-destructive photo edits) and `assets/<sha8>.audio.json` are versioned
+ * content (DDR-115 does not ignore them), and without a lane the second
+ * machine silently loses every photo edit — the exact bug class this module
+ * exists to end.
+ */
+const COMPANION_SIDECAR_SUFFIXES = ['.photo.json', '.audio.json'];
+
+/**
+ * A DIRECTORY segment must start alphanumeric — the same rule as the hub's
+ * `checkoutRelShape`, and the rule that keeps every `_*` runtime DIRECTORY
+ * (`_history/`, `_untrusted/`, `_trash/`, …) out structurally, before the
+ * explicit runtime-state check even runs.
+ */
+const DIR_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9 ._-]*$/;
+
+/**
+ * The FINAL segment may additionally start with `_` — this is the one
+ * deliberate relaxation over `checkoutRelShape`, and the reason the paired
+ * refusal below (`isRuntimeStateRel`) lands in the same module, same commit:
+ * real versioned FILES like `_brand-css.ts` and `preview/_layout.css` start
+ * with an underscore, and refusing the underscore wholesale is exactly the
+ * DDR-115 shape accident that left them laneless. A leading dot stays
+ * refused — `.DS_Store` and dotfiles are not project content.
+ */
+const FILE_SEGMENT = /^[A-Za-z0-9_][A-Za-z0-9 ._-]*$/;
+
+/**
+ * Maude's own per-machine runtime state — the DDR-115 taxonomy, replicated
+ * byte-for-byte from `git/service.ts` `isMaudeRuntimeState` (see the 4th-copy
+ * tripwire note in the header; the parity test imports both and asserts
+ * agreement). These never travel in EITHER direction, no matter what their
+ * extension says.
+ */
+export function isRuntimeStateRel(p: string): boolean {
+  return (
+    /(^|\/)_(?:server|active|sync|preflight|locator|export-history|generate-history)(?:\.[A-Za-z0-9_-]{1,64})?\.json$/.test(
+      p
+    ) ||
+    /(^|\/)_server\.(?:lock|log)$/.test(p) ||
+    /(^|\/)_(?:history|trash|draw|photo|smoke|reports|canvas-state|state|chat|comments|untrusted|export-jobs)(?:\/|$)/.test(
+      p
+    ) ||
+    /(^|\/)\.kgai(?:\/|$)/.test(p)
+  );
+}
+
+export interface ClassifyOptions {
+  /** Declared canvas groups. Absent ⇒ the same `['system', 'ui']` default the
+   *  canvas-path receiver uses — the two halves of sync must agree on what a
+   *  group is, or a body one lane owns leaks into the other. */
+  canvasGroups?: readonly CanvasGroupLike[];
+  /**
+   * Presence probe over the SAME tree `rel` came from. Powers the ONE
+   * sibling-dependent split: a `.css` inside a canvas group is canvas-owned
+   * when `<same-name>.tsx` exists (it is that canvas's Yjs css lane), and
+   * companion-text when it does not (`brand.css`, `_layout.css` — the RCA's
+   * missing stylesheets). This cannot be decided from the path alone, and
+   * both misreadings are wrong: "all group css is canvas-owned" re-loses the
+   * RCA's five files, "all group css flows" double-transports a CRDT lane.
+   * Absent ⇒ companion-text (the flowing side) — safe because every RECEIVER
+   * passes its own disk probe and re-refuses what its tree shows is a
+   * sidecar.
+   */
+  hasFile?: (rel: string) => boolean;
+}
+
+/**
+ * Classify one designRoot-relative path. Total: every input gets a class, and
+ * every malformed input gets `never` — shape refusal and policy refusal are
+ * deliberately the same answer, so no caller can tell them apart and leak an
+ * oracle.
+ *
+ * Shape gates (all refusals → `never`): relative, `/`-separated, ≤ 8
+ * segments, ≤ 512 chars, no `..`/`.`/empty segment, no backslash, no drive
+ * letter, no control characters, no trailing-space segment, no
+ * `node_modules`, directory segments start alphanumeric, the final segment
+ * may start with `_`.
+ */
+export function classifyProjectFile(rel: string, opts: ClassifyOptions = {}): FileClass {
+  const parts = relShape(rel);
+  if (parts === null) return 'never';
+
+  // The design root's own `config.json` names the linked hub and the canvas
+  // groups — a peer that syncs it hands naming authority to the hub.
+  if (rel === 'config.json') return 'never';
+  if (isRuntimeStateRel(rel)) return 'never';
+
+  const last = parts[parts.length - 1] ?? '';
+  const lowerLast = last.toLowerCase();
+  const lowerRel = rel.toLowerCase();
+  const inGroup = normalizedGroups(opts.canvasGroups).some((g) =>
+    lowerRel.startsWith(`${g.toLowerCase()}/`)
+  );
+
+  if (inGroup) {
+    // The canvas body and its NAMED sidecars — Plane A's, by construction.
+    if (lowerLast.endsWith('.tsx')) return 'canvas-owned';
+    if (lowerLast.endsWith('.meta.json')) return 'canvas-owned';
+    if (lowerLast.endsWith('.annotations.svg')) return 'canvas-owned';
+    if (lowerLast.endsWith('.css') && opts.hasFile) {
+      const sibling = `${rel.slice(0, -'.css'.length)}.tsx`;
+      if (opts.hasFile(sibling)) return 'canvas-owned';
+    }
+  }
+
+  if (COMPANION_SIDECAR_SUFFIXES.some((s) => lowerLast.endsWith(s))) return 'companion-text';
+
+  const dot = lowerLast.lastIndexOf('.');
+  const ext = dot < 0 ? '' : lowerLast.slice(dot + 1);
+  if (INERT_MEDIA_EXTS.has(ext)) return 'inert-media';
+  if (COMPANION_TEXT_EXTS.has(ext)) return 'companion-text';
+  if (CODE_MODULE_EXTS.has(ext)) return 'code-module';
+
+  // Default-closed. Not an error — the answer.
+  return 'never';
+}
+
+/**
+ * The shape gate alone — true when `rel` could name a project file at all.
+ *
+ * Exposed for surfaces that must parse BEFORE they can classify: the hub's
+ * PUT route parses the URL before it knows the checkout's canvas groups, and
+ * a parse-stage refusal there is final (the request falls through), so it may
+ * refuse only what NO configuration could ever admit — the shape.
+ */
+export function isProjectFileShape(rel: string): boolean {
+  return relShape(rel) !== null;
+}
+
+/** The segment shape rules alone — split parts, or null on refusal. */
+function relShape(rel: unknown): string[] | null {
+  if (typeof rel !== 'string' || rel.length === 0 || rel.length > MAX_REL_LEN) return null;
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: refusing them is the point.
+  if (/[\u0000-\u001f\u007f]/.test(rel)) return null;
+  if (rel.startsWith('/') || rel.includes('\\') || /^[A-Za-z]:/.test(rel)) return null;
+  const parts = rel.split('/');
+  if (parts.length > MAX_SEGMENTS) return null;
+  for (let i = 0; i < parts.length; i++) {
+    const p = parts[i] ?? '';
+    if (!p || p === '.' || p === '..') return null;
+    if (p === 'node_modules') return null;
+    if (/ $/.test(p)) return null;
+    if (!(i === parts.length - 1 ? FILE_SEGMENT : DIR_SEGMENT).test(p)) return null;
+  }
+  return parts;
+}
+
+/**
+ * Declared group paths, normalised — the same semantics (and the same
+ * `['system', 'ui']` fallback) as `canvas-path.ts`'s private helper, re-typed
+ * here because this module must load dependency-free in the hub's plain-Node
+ * runtime through its `.mjs` mirror.
+ */
+function normalizedGroups(canvasGroups?: readonly CanvasGroupLike[]): string[] {
+  const out: string[] = [];
+  for (const g of canvasGroups ?? []) {
+    const p = normalizeGroup(g?.path);
+    if (p && !out.includes(p)) out.push(p);
+  }
+  return out.length > 0 ? out : ['system', 'ui'];
+}
+
+/** One group path, or null when unusable as a containment prefix (stricter is
+ *  the safe direction — an escaping group is dropped, not clamped). */
+function normalizeGroup(raw: unknown): string | null {
+  if (typeof raw !== 'string') return null;
+  const p = raw.replace(/\\/g, '/').replace(/^\/+|\/+$/g, '');
+  if (!p) return null;
+  if (/^[A-Za-z]:/.test(p)) return null;
+  for (const part of p.split('/')) {
+    if (!part || part === '.' || part === '..') return null;
+    if (!/^[A-Za-z0-9_-][A-Za-z0-9 _-]*(?![\s\S])/.test(part)) return null;
+  }
+  return p;
+}

package/apps/studio/sync/file-pull.ts

@@ -0,0 +1,330 @@
+// The file plane's downward half — manifest-driven replication of every
+// project file the canvas lanes do not own (feature-sync-file-plane, binding
+// decision maude/sync-two-plane-manifest-architecture).
+//
+// WHAT THIS REPLACES, AND WHY THE HEADER OF `asset-pull.ts` STILL MATTERS.
+// The asset pull derives its wants LOCALLY (it fetches only names its own
+// files reference), so a hostile hub can never place a file nobody asked for.
+// That invariant is exactly what made the 103-file gap unfixable: a fresh
+// link REFERENCES nothing, so it can want nothing, so the design system that
+// makes the canvases render never arrives (RCA
+// issue-fresh-link-gets-canvases-but-not-the-design-system). The manifest
+// DELIBERATELY replaces reference-derivation for the gated classes — and what
+// stands in for it is the receiver-side discipline below, which is stronger
+// than a reference scan, not weaker:
+//
+//   1. EVERY entry is RE-CLASSIFIED against this peer's OWN tree and config
+//      (`classifyProjectFile` — the positive, default-closed classifier). The
+//      hub's `class` field is a HINT for reporting; a disagreement drops the
+//      entry with one warn (ATTACKER's invariant from the binding debate: the
+//      receiver re-validates every path; naming authority is never handed to
+//      the hub).
+//   2. Per-class admission: `inert-media` and `companion-text` flow;
+//      `code-module` lands ONLY when this peer's STORED record for the hub
+//      says `role === 'owner'`, or the hub is this machine's own loopback
+//      cell pairing — decided from local state, never from the wire.
+//   3. Deletion does NOT propagate. A vanished manifest entry means "no
+//      longer offered", never "delete yours" (scope cut: the branch-switch-
+//      as-mass-delete hazard is dodged structurally).
+//   4. Conflicts never lose work silently: on a hash mismatch the newer
+//      `mtimeMs` wins, and a losing LOCAL copy parks in
+//      `_trash/<rel>-conflict-<ts>` (`quarantineFile` — the tombstone lane's
+//      quarantine-never-delete posture). If parking fails, the overwrite is
+//      refused.
+//
+// CODE MODULES AND THE BUILD. A pulled `code-module` lands in the live tree,
+// so this lane's admission is paired with the canvas build's import
+// allowlist being unconditional (`restrictImportsTo: designRoot` at every
+// build site — Task 9 of the same feature, landed with it): what a module
+// can reach is bounded by the design root on every runtime, so a pulled file
+// cannot turn the build into a read of the wider filesystem.
+//
+// MISSING-ONLY IS THE STEADY STATE: equal hash → skip (echo-guard by
+// construction), so a converged project costs one manifest fetch per poll.
+
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+import {
+  type CanvasGroupLike,
+  classifyProjectFile,
+  type FileClass,
+  isFilePlaneClass,
+} from './file-membership.ts';
+import { quarantineFile } from './tombstone-apply.ts';
+
+/** How long to wait for the manifest. Same figure as the doc listing. */
+const MANIFEST_TIMEOUT_MS = 6000;
+
+/** How long to wait for one file. Generous — these run to videos. */
+const GET_TIMEOUT_MS = 120_000;
+
+/** Refuse an implausible body outright rather than streaming it to disk. */
+const MAX_PULL_BYTES = 512 * 1024 * 1024;
+
+/** How many files one pass will fetch — the loud cap, same reasoning as
+ *  every other lane: one answer must not land thousands, and the remainder
+ *  is picked up by the next pass. */
+const MAX_FILES_PER_PASS = 200;
+
+/** One entry as the hub offers it. Everything here is UNTRUSTED input. */
+export interface RemoteFileEntry {
+  path: string;
+  sha256: string;
+  size: number;
+  mtimeMs: number;
+  /** The hub's claimed class — a reporting hint, never authority. */
+  class: string;
+}
+
+export interface FilePullConflict {
+  rel: string;
+  winner: 'local' | 'hub';
+  /** Set when the hub won and the local copy was parked. */
+  trashedTo?: string;
+}
+
+export interface FilePullResult {
+  pulled: string[];
+  /** Present with an equal hash — the converged steady state. */
+  skipped: number;
+  conflicts: FilePullConflict[];
+  /** Refused by re-classification or per-class admission. */
+  dropped: { rel: string; reason: string }[];
+  failed: { rel: string; reason: string }[];
+}
+
+/**
+ * Fetch the manifest, never fatally: null means unreachable, refused, or a
+ * hub without the route — sync continues either way, we ask again later
+ * (the `fetchRemoteListing` posture). Entries are filtered to the expected
+ * SHAPE here; the classifier judges the paths themselves at pull time.
+ */
+export async function fetchFileManifest(
+  hubUrl: string,
+  token: string,
+  fetchImpl: typeof fetch = fetch
+): Promise<RemoteFileEntry[] | null> {
+  try {
+    const base = hubUrl.replace(/\/+$/, '');
+    const res = await fetchImpl(`${base}/api/files`, {
+      headers: { authorization: `Bearer ${token}` },
+      signal: AbortSignal.timeout(MANIFEST_TIMEOUT_MS),
+    });
+    if (!res.ok) return null;
+    const body = (await res.json()) as { files?: unknown };
+    if (!Array.isArray(body?.files)) return null;
+    return body.files
+      .filter(
+        (f): f is RemoteFileEntry =>
+          !!f &&
+          typeof (f as RemoteFileEntry).path === 'string' &&
+          (f as RemoteFileEntry).path.length > 0 &&
+          typeof (f as RemoteFileEntry).sha256 === 'string' &&
+          /^[0-9a-f]{64}$/.test((f as RemoteFileEntry).sha256)
+      )
+      .map((f) => ({
+        path: f.path,
+        sha256: f.sha256,
+        size: Number(f.size) || 0,
+        mtimeMs: Number(f.mtimeMs) || 0,
+        class: String(f.class ?? ''),
+      }));
+  } catch {
+    return null;
+  }
+}
+
+export interface PullFilesOptions {
+  designRoot: string;
+  hubUrl: string;
+  /** Read at call time — silent renewal swaps the credential in place. */
+  token: () => string;
+  /** Declared canvas groups — the same config the canvas receiver honours. */
+  canvasGroups?: readonly CanvasGroupLike[];
+  /**
+   * Whether `code-module` entries may land: the STORED record for this hub
+   * vouches `role === 'owner'`, or the hub is this machine's own loopback
+   * cell pairing. Computed by the caller from LOCAL state (hubs.json /
+   * cell-pairing) — never from anything the hub sent.
+   */
+  allowCodeModules: boolean;
+  fetchImpl?: typeof fetch;
+  log?: Pick<Console, 'log' | 'warn'>;
+  now?: () => number;
+}
+
+/**
+ * One downward pass: manifest → re-classify → admit → reconcile → fetch.
+ * Sequential on purpose (the asset lanes' reasoning — don't starve the
+ * handshakes); never throws — a failure is a line in `failed` and a free
+ * retry on the next poll.
+ */
+export async function pullFiles(opts: PullFilesOptions): Promise<FilePullResult> {
+  const { designRoot, hubUrl } = opts;
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const log = opts.log ?? console;
+  const now = opts.now ?? Date.now;
+  const base = hubUrl.replace(/\/+$/, '');
+  const out: FilePullResult = { pulled: [], skipped: 0, conflicts: [], dropped: [], failed: [] };
+
+  const manifest = await fetchFileManifest(hubUrl, opts.token(), fetchImpl);
+  if (manifest === null) return out;
+
+  // Decide the whole pass from the manifest first, then move bytes: a local
+  // win costs no fetch at all, and the loud cap counts only real transfers.
+  const classifyOpts = {
+    canvasGroups: opts.canvasGroups,
+    hasFile: (r: string) => existsSync(path.join(designRoot, r)),
+  };
+  const wanted: { entry: RemoteFileEntry; abs: string; conflict: FilePullConflict | null }[] = [];
+
+  for (const entry of manifest) {
+    const rel = entry.path;
+    // 1. THIS peer's own verdict on the path — shape and class in one call.
+    const localClass: FileClass = classifyProjectFile(rel, classifyOpts);
+    if (!isFilePlaneClass(localClass)) {
+      drop(out, log, rel, `classifies '${localClass}' here`);
+      continue;
+    }
+    // The hub's class is a hint; a disagreement is a drop, not a negotiation.
+    if (entry.class !== localClass) {
+      drop(out, log, rel, `hub says '${entry.class}', this peer says '${localClass}'`);
+      continue;
+    }
+    // 2. Per-class admission — the owner-hub gate, from LOCAL state only.
+    if (localClass === 'code-module' && !opts.allowCodeModules) {
+      drop(out, log, rel, 'code modules replicate only from an owner-vouched or loopback hub');
+      continue;
+    }
+    if (entry.size > MAX_PULL_BYTES) {
+      drop(out, log, rel, `implausible size (${entry.size} B)`);
+      continue;
+    }
+
+    // 3. Reconcile against the local copy.
+    const abs = path.join(designRoot, rel);
+    const resolved = path.resolve(abs);
+    const root = path.resolve(designRoot);
+    if (resolved !== root && !resolved.startsWith(root + path.sep)) {
+      // Unreachable while the classifier holds (no `..`, no absolutes) —
+      // belt and braces for the one lane where a hub NAME becomes a path.
+      drop(out, log, rel, 'escapes the design root');
+      continue;
+    }
+    let st: ReturnType<typeof statSync> | null = null;
+    try {
+      st = statSync(abs);
+    } catch {
+      st = null;
+    }
+    if (st !== null) {
+      if (!st.isFile()) {
+        drop(out, log, rel, 'a non-file sits at this path locally');
+        continue;
+      }
+      let localSha: string;
+      try {
+        localSha = createHash('sha256').update(readFileSync(abs)).digest('hex');
+      } catch (err) {
+        out.failed.push({ rel, reason: `unreadable local copy: ${(err as Error).message}` });
+        continue;
+      }
+      if (localSha === entry.sha256) {
+        out.skipped += 1;
+        continue;
+      }
+      // LWW by mtime. The local file wins ties: overwriting a person's disk
+      // needs the remote to be STRICTLY newer.
+      if (!(entry.mtimeMs > st.mtimeMs)) {
+        out.conflicts.push({ rel, winner: 'local' });
+        continue;
+      }
+      wanted.push({ entry, abs, conflict: { rel, winner: 'hub' } });
+      continue;
+    }
+    wanted.push({ entry, abs, conflict: null });
+  }
+
+  const batch = wanted.slice(0, MAX_FILES_PER_PASS);
+  if (batch.length < wanted.length) {
+    // Named loudly — a silent cap reads as "sync is broken" with no cause.
+    log.warn(
+      `[sync/files] the project offers ${wanted.length} files this peer is missing; taking ${batch.length} this pass.`
+    );
+  }
+
+  for (const { entry, abs, conflict } of batch) {
+    const rel = entry.path;
+    try {
+      const res = await fetchImpl(
+        `${base}/_project-file/${rel.split('/').map(encodeURIComponent).join('/')}`,
+        {
+          headers: { authorization: `Bearer ${opts.token()}` },
+          signal: AbortSignal.timeout(GET_TIMEOUT_MS),
+        }
+      );
+      if (!res.ok) {
+        out.failed.push({ rel, reason: `HTTP ${res.status}` });
+        continue;
+      }
+      const body = new Uint8Array(await res.arrayBuffer());
+      if (body.byteLength > MAX_PULL_BYTES) {
+        out.failed.push({ rel, reason: `implausible size (${body.byteLength} B)` });
+        continue;
+      }
+      // The manifest named a hash; the bytes must BE that hash. A mismatch is
+      // usually a write racing the poll — a free retry, never a landing.
+      const gotSha = createHash('sha256').update(body).digest('hex');
+      if (gotSha !== entry.sha256) {
+        out.failed.push({ rel, reason: 'content hash mismatch (racing a write?)' });
+        continue;
+      }
+      if (conflict) {
+        const trashedTo = quarantineFile({
+          designRoot,
+          rel,
+          now: now(),
+          log: (line) => log.log(line),
+        });
+        if (trashedTo === null) {
+          // Could not park the loser ⇒ the overwrite is refused. Never
+          // silent loss — the local copy stays, the conflict is reported.
+          out.conflicts.push({ rel, winner: 'local' });
+          continue;
+        }
+        conflict.trashedTo = trashedTo;
+        out.conflicts.push(conflict);
+      }
+      mkdirSync(path.dirname(abs), { recursive: true });
+      // Write beside the target and rename, so a reader never sees a
+      // half-written file.
+      const tmpAbs = `${abs}.part`;
+      writeFileSync(tmpAbs, body);
+      renameSync(tmpAbs, abs);
+      out.pulled.push(rel);
+    } catch (err) {
+      out.failed.push({ rel, reason: (err as Error).message });
+    }
+  }
+
+  if (out.pulled.length > 0 || out.conflicts.length > 0) {
+    log.log(
+      `[sync/files] pulled ${out.pulled.length} project file(s) down (${out.skipped} already here, ${out.conflicts.length} conflict(s), ${out.failed.length} failed).`
+    );
+  }
+  return out;
+}
+
+/** One warn per (reason-class) flood is the caller's job; here every drop is
+ *  one line — drops are refusals of UNTRUSTED input and deserve a trace. */
+function drop(
+  out: FilePullResult,
+  log: Pick<Console, 'log' | 'warn'>,
+  rel: string,
+  reason: string
+): void {
+  out.dropped.push({ rel, reason });
+  log.warn(`[sync/files] dropped '${rel}': ${reason}`);
+}