flowviant 0.102.2 → 0.104.0

package/bin/lib/knowledge.mjs

@@ -6,7 +6,7 @@
  * files uploaded once and a standing Instructions text, read by every turn on
  * the project. The server holds the bytes; the roster carries a MANIFEST
  * (`knowledge: { rev, instructions, files: [{ id, name, bytes, sha256 }] }`);
- * this module makes `<checkout>/.flowviant/knowledge/` match it, and the turn
+ * the daemon makes `<checkout>/.flowviant/knowledge/` match it, and the turn
  * prompts name that directory. Nothing here reads a file's CONTENTS for any
  * purpose but writing it — the only brain is the CLI, reading off a disk.
  *
@@ -55,780 +55,25 @@
  * permanent for that rev, skipped with a warning, and the rest of the library
  * is written.
  *
- * ── THE KEPT LIBRARY (2026-09-23, 0.97.0) ──
+ * ── WHERE EACH PART LIVES (2026-09-26, SOLID SRP, F049) ──
  *
- * The manifest may carry `library: { items: [...] }` — the designs and
- * write-ups the project KEPT when a person accepted them — and each item lands
- * at its own relative path, `designs/<slug>-v<N>.html` or
- * `research/<slug>-v<N>.md`, with a generated `LIBRARY.md` at the root naming
- * every one (path, title, kind, the card that asked for it, the date, what it
- * supersedes). So "implement design A" is an agent opening LIBRARY.md, finding
- * design A, and reading the page. At 0.99.0 a kept design is one folder,
- * including its original relative sidecar paths and measured preview.
- *
- * SUBDIRECTORIES, AND EXACTLY TWO. The safe-name rule for a knowledge file
- * forbids every separator; a library item is the one thing allowed ONE, and
- * only after one of the two literal prefixes, with a stem that is already
- * safe and the extension its kind hands back. `..`, a third segment, another
- * prefix, a leading dot — refused, never rewritten, because a rewritten path
- * could collide with another item's real one. The two directories are OURS the
- * way the library directory is: a symlink or a file planted there is removed
- * (the link, never its target) and a real directory made.
- *
- * ABSENT MEANS "LEAVE IT ALONE", the same rule the whole key keeps: a manifest
- * with no `library` key is an older server, and `designs/`, `research/` and
- * `LIBRARY.md` are neither synced nor swept. `library: { items: [] }` is the
- * emptied catalog, SAID — both directories and the catalog go.
+ * This module is the ROSTER DRIVER alone: the rev held in memory, the
+ * serialised sync, the backoff. The pure naming, path and catalog rules —
+ * including the kept library's two subdirectories — are knowledgeLibrary.mjs;
+ * the disk (the sync itself, the marker, `knowledgeDirFor`) is
+ * knowledgeFiles.mjs; the `/fleet/knowledge` and `/fleet/library` download is
+ * knowledgeFetch.mjs. Callers import the owner they need.
  */
 
+import { isKnowledgeManifest, libraryItemsOf } from './knowledgeLibrary.mjs';
 import {
-  existsSync,
-  lstatSync,
-  mkdirSync,
-  readdirSync,
-  readFileSync,
-  renameSync,
-  rmSync,
-  unlinkSync,
-  writeFileSync,
-} from 'node:fs';
-import { createHash } from 'node:crypto';
-import { join } from 'node:path';
-
-/** Relative to the checkout, under `.flowviant/` beside the turn uploads and
- *  the artifacts — see `FLOWVIANT_OWN_PATHS` for why that is NOT one exclude
- *  line covering all three. */
-export const KNOWLEDGE_DIR = '.flowviant/knowledge';
-
-/**
- * THE PATHS UNDER `.flowviant/` THAT ARE OURS, and the exclude file names these
- * and nothing wider (2026-09-23).
- *
- * The first cut excluded `/.flowviant/` whole, from every place a turn spawns
- * in — the attachment fetch's line, which until this release was written only
- * in repos somebody had attached a file in. But `.flowviant/` is not only ours:
- * the repo DECLARES `.flowviant/check.json` and `.flowviant/deploy.json` there,
- * committed like any other file. An exclude line never hides a TRACKED file,
- * so an existing one was safe — and a NEW one was not: an agent asked to "add a
- * check command" writes `.flowviant/check.json`, its `git add -A` skips it as
- * ignored, the commit lands without it, and `git status` shows nothing to
- * explain why. Writing that line into every worktree on every turn would have
- * made the product's own configuration uncommittable by the product's own
- * agents. So the exclude names the four things this daemon writes there, and a
- * repo's own `.flowviant/*.json` stays ordinary, committable work.
- *
- * (A repo that already carries the old `/.flowviant/` line keeps it — it is in
- * the user's own exclude file, and removing a line we cannot prove we alone
- * wrote is not ours to do.)
- */
-export const FLOWVIANT_OWN_PATHS = [
-  '.flowviant/knowledge/',
-  '.flowviant/knowledge.rev*',
-  '.flowviant/artifacts/',
-  '.flowviant/uploads/',
-];
-/** The generated catalog of the kept library, at the knowledge root. Reserved
- *  like INSTRUCTIONS.md: a person's file of that name is suffixed, because the
- *  prompt tells the CLI this one is the catalog. */
-export const LIBRARY_FILE = 'LIBRARY.md';
-/** The two subdirectories a kept item may live in, by kind. */
-export const LIBRARY_DIRS = { design: 'designs', research: 'research' };
-const LIBRARY_EXT = { design: ['.html', '.htm', '.gltf', '.obj', '.glb', '.bin'], research: ['.md'] };
-/** The server caps a library at 200 items; a longer manifest is cut. */
-const MAX_LIBRARY_ITEMS = 256;
-
-/** The person's standing brief, written from the manifest's `instructions`.
- *  A RESERVED name: a library FILE called this gets a suffix, because the
- *  prompt tells the CLI to read this one first and a stranger's file must
- *  never be able to stand in for the person's own words. */
-export const INSTRUCTIONS_FILE = 'INSTRUCTIONS.md';
-/** The rev last materialised — OUTSIDE the directory the prompt hands the CLI,
- *  so the agent listing its library sees only the library. */
-const MARKER = '.flowviant/knowledge.rev';
-/** The server's per-file ceiling (`KNOWLEDGE_FILE_MAX_BYTES`), re-checked here:
- *  this is somebody's disk, and one place checking is one deploy away from
- *  zero places — the attachment fetch's own rule. */
-export const KNOWLEDGE_FILE_MAX_BYTES = 10 * 1024 * 1024;
-export const KNOWLEDGE_BINARY_MODEL_MAX_BYTES = 20 * 1024 * 1024;
-const knowledgeMaxFor = (name, base) => /\.(glb|bin)$/i.test(name)
-  ? Math.max(base, KNOWLEDGE_BINARY_MODEL_MAX_BYTES) : base;
-/** The manifest is capped at the server (25 files); a manifest longer than
- *  this is not one the product produced, and is cut rather than trusted. */
-const MAX_FILES = 64;
-
-/** FNV-1a, 32-bit, as 8 hex — deterministic, so the same long name always maps
- *  to the same stored name. Verbatim against the server's `fnv1a8`
- *  (apps/api/src/routes/sessionsAttachments.routes.ts). */
-function fnv1a8(s) {
-  let h = 0x811c9dc5;
-  for (let i = 0; i < s.length; i++) {
-    h ^= s.charCodeAt(i);
-    h = Math.imul(h, 0x01000193);
-  }
-  return (h >>> 0).toString(16).padStart(8, '0');
-}
-/** What counts as an extension worth keeping through a cut. */
-const SAFE_EXT_RE = /^[A-Za-z0-9]{1,10}$/;
-const SAFE_NAME_MAX = 80;
-
-/**
- * `safeFileName`, verbatim (apps/api/src/routes/sessionsAttachments.routes.ts):
- * drops every path separator, never starts with a dot or a dash, and — since
- * 2026-09-24 — THE EXTENSION SURVIVES A CUT. A bare `slice(0, 80)` truncated
- * an over-long name mid-extension (an 84-character `….html` mockup stored as
- * `….` with an unrecognised type and its bytes discarded), so a long name's
- * stem is now cut and an 8-hex FNV-1a hash of the WHOLE sanitised name is
- * appended before the extension: stable across calls, at most 80 characters,
- * idempotent over its own output, and — the reason it is re-applied here
- * rather than trusted to the server's own pass — byte-identical to what
- * `safeFileName` computes there, so a knowledge file synced under this name
- * and one requested by name later never disagree over the cut.
- */
-export function safeKnowledgeName(raw) {
-  const clean = String(raw ?? '')
-    .split(/[\\/]/)
-    .pop()
-    .replace(/[^A-Za-z0-9._-]/g, '_')
-    .replace(/^[.-]+/, '');
-  if (!clean) return 'file';
-  if (clean.length <= SAFE_NAME_MAX) return clean;
-  const dot = clean.lastIndexOf('.');
-  const ext = dot > 0 && SAFE_EXT_RE.test(clean.slice(dot + 1)) ? clean.slice(dot + 1) : '';
-  const stem = ext ? clean.slice(0, dot) : clean;
-  const tag = `-${fnv1a8(clean)}`;
-  const room = SAFE_NAME_MAX - tag.length - (ext ? ext.length + 1 : 0);
-  return `${stem.slice(0, room)}${tag}${ext ? `.${ext}` : ''}`;
-}
-
-/**
- * The LOCAL name each manifest entry is written under, in manifest order.
- * Collisions get a numeric suffix (`spec.md`, `spec-2.md`) — two files a
- * person uploaded with one name are two files, and silently writing one over
- * the other loses one. Deterministic in the manifest's order, so the same
- * manifest always yields the same names and a re-sync never renames a file.
- * `INSTRUCTIONS.md` is reserved (compared case-insensitively — macOS and
- * Windows disks are).
- */
-export function planKnowledgeNames(files) {
-  // The catalog's name and the two library directories are reserved beside
-  // the brief (0.97.0): a person's `LIBRARY.md` or a file called `designs`
-  // must never stand where the catalog or a directory has to.
-  const taken = new Set([
-    INSTRUCTIONS_FILE.toLowerCase(),
-    LIBRARY_FILE.toLowerCase(),
-    ...Object.values(LIBRARY_DIRS),
-  ]);
-  const out = [];
-  for (const f of files) {
-    const name = safeKnowledgeName(f.name);
-    const dot = name.lastIndexOf('.');
-    const stem = dot > 0 ? name.slice(0, dot) : name;
-    const ext = dot > 0 ? name.slice(dot) : '';
-    let candidate = name;
-    for (let n = 2; taken.has(candidate.toLowerCase()); n++) candidate = `${stem}-${n}${ext}`;
-    taken.add(candidate.toLowerCase());
-    out.push({ ...f, local: candidate });
-  }
-  return out;
-}
-
-const sha256Of = (buf) => createHash('sha256').update(buf).digest('hex');
-
-/** A regular file's sha256, or null for anything else (missing, a directory, a
- *  symlink — a symlink is never followed, so it is never "the same file"). */
-function localSha(path) {
-  try {
-    const st = lstatSync(path);
-    if (!st.isFile()) return null;
-    return sha256Of(readFileSync(path));
-  } catch {
-    return null;
-  }
-}
-
-/** Write through a temp name and rename, so a CLI reading the library mid-sync
- *  sees the old file or the new one, never half of one. Anything already at
- *  the path that is NOT a regular file (a symlink planted there) is removed
- *  first — `writeFileSync` would otherwise follow it and write wherever it
- *  pointed. */
-function writeAtomic(path, data) {
-  try {
-    const st = lstatSync(path);
-    if (!st.isFile()) rmSync(path, { recursive: true, force: true });
-  } catch {
-    /* absent — the ordinary case */
-  }
-  const tmp = `${path}.fvtmp`;
-  // THE TEMP NAME IS CHECKED TOO (2026-09-23). The first cut guarded the
-  // destination and then wrote straight through `<name>.fvtmp` — a link planted
-  // THERE would have been followed, the library's bytes written wherever it
-  // pointed, and the link renamed into place. Unlinked first, then created
-  // EXCLUSIVELY (`wx`): if anything reappears at the name between the two, the
-  // write throws into the caller's catch rather than following it.
-  rmSync(tmp, { recursive: true, force: true });
-  writeFileSync(tmp, data, { flag: 'wx' });
-  renameSync(tmp, path);
-}
-
-/**
- * Is `<checkout>/.flowviant` a real directory, or absent? Anything else — a
- * symlink, a regular file — REFUSES the sync rather than being touched.
- *
- * `.flowviant/` is not only ours: a repo declares `.flowviant/check.json` and
- * `.flowviant/deploy.json` there, and an operator may have arranged it however
- * they like. Deleting a file or a link at that path to make room for a library
- * would be Flowviant destroying something it did not create; following a link
- * would land downloads, and the emptied library's `rm -r`, wherever it points.
- * So the parent is checked, never repaired.
- */
-function flowviantDirOk(checkoutDir) {
-  try {
-    const st = lstatSync(join(checkoutDir, '.flowviant'));
-    return st.isDirectory() && !st.isSymbolicLink();
-  } catch {
-    return true; // absent — ours to create
-  }
-}
-
-/** The library directory, as a real directory. The PARENT is checked by the
- *  caller; the library path itself is OURS, so a symlink or a file planted
- *  there is removed (unlinked — the link, never its target) rather than
- *  followed. */
-function ensureDir(checkoutDir) {
-  const dir = join(checkoutDir, KNOWLEDGE_DIR);
-  try {
-    const st = lstatSync(dir);
-    if (st.isSymbolicLink() || !st.isDirectory()) unlinkSync(dir);
-  } catch {
-    /* absent */
-  }
-  mkdirSync(dir, { recursive: true });
-  return dir;
-}
-
-/**
- * THE MARKER SAYS WHICH REV WAS WRITTEN, AND WHETHER THE LIBRARY WAS PART OF
- * IT (2026-09-23): `<rev>` or `<rev>:lib`.
- *
- * The rev alone could not tell an upgrade from a sync. A 0.96.0 box wrote the
- * marker for rev N while ignoring the manifest's `library` key (it did not
- * know one); updated to 0.97.0 with `knowledge_rev` still N, it read "N",
- * matched the roster, and never synced the library — then the server handed
- * `task.references` naming `designs/x-v1.html` and the agent was told to read
- * a file that was not there. `:lib` records that THIS rev's sync carried a
- * library key, so the upgrade case is one string compare and re-syncs at
- * once. An older daemon reading `N:lib` sees NaN and re-syncs once, which is
- * the harmless direction.
- */
-function parseMarker(checkoutDir) {
-  try {
-    const m = /^(\d+)(:lib)?$/.exec(readFileSync(join(checkoutDir, MARKER), 'utf8').trim());
-    if (!m) return null;
-    const n = Number(m[1]);
-    return Number.isSafeInteger(n) ? { rev: n, lib: Boolean(m[2]) } : null;
-  } catch {
-    return null;
-  }
-}
-
-export function readKnowledgeMarker(checkoutDir) {
-  return parseMarker(checkoutDir)?.rev ?? null;
-}
-
-/** Did the sync that wrote the marker carry a `library` key? */
-export function knowledgeMarkerHasLibrary(checkoutDir) {
-  return parseMarker(checkoutDir)?.lib ?? false;
-}
-
-function writeKnowledgeMarker(checkoutDir, rev, lib = false) {
-  try {
-    mkdirSync(join(checkoutDir, '.flowviant'), { recursive: true });
-    writeAtomic(join(checkoutDir, MARKER), `${rev}${lib ? ':lib' : ''}\n`);
-  } catch {
-    /* a lost marker costs one re-sync after a restart — every file already on
-       disk matches by sha and is not downloaded again */
-  }
-}
-
-/**
- * A kept item's relative path, or null when it is not EXACTLY
- * `<designs|research>/<safe stem>.<its kind's extension>` — see the header.
- * Refused rather than rewritten: a rewritten path is one the server never
- * named, and it could land on another item's real one.
- */
-export function safeLibraryPath(name, kind) {
-  if (typeof name !== 'string' || !(kind in LIBRARY_DIRS)) return null;
-  const parts = name.split('/');
-  if (parts.length !== 2 && !(kind === 'design' && parts.length >= 3 && parts.length <= 7)) return null;
-  const [dir, ...rest] = parts;
-  const file = rest.at(-1);
-  if (dir !== LIBRARY_DIRS[kind]) return null;
-  if (rest.length >= 2 && !/^[a-z0-9-]+-v[1-9][0-9]*$/.test(rest[0])) return null;
-  if (rest.slice(1, -1).some((p) => !safeBundleSegment(p))) return null;
-  if (!file || (rest.length === 1 ? file !== safeKnowledgeName(file) : !safeBundleSegment(file))) return null;
-  if (!LIBRARY_EXT[kind].some((ext) => file.toLowerCase().endsWith(ext) && file.length > ext.length)) return null;
-  return name;
-}
-
-function safeBundleSegment(part) {
-  return typeof part === 'string' && part.length > 0 && part.length <= 80 &&
-    /^[A-Za-z0-9][A-Za-z0-9._ -]*$/.test(part) && !part.endsWith('.');
-}
-
-function safeBundleFile(path, rootDir) {
-  if (typeof path !== 'string' || !path.startsWith(`${rootDir}/`)) return null;
-  const relative = path.slice(rootDir.length + 1);
-  if (relative === 'preview.png') return null;
-  const parts = relative.split('/');
-  if (!parts.length || parts.some((p) => !safeBundleSegment(p))) return null;
-  if (!/\.(gltf|obj|glb|bin|png|jpg|jpeg|gif|webp|svg|json)$/i.test(relative)) return null;
-  return path;
-}
-
-/** The manifest's library items that are safe to write, in manifest order, or
- *  null when the key is ABSENT (an older server — leave everything alone). */
-function libraryItemsOf(manifest) {
-  const lib = manifest?.library;
-  if (lib === undefined || lib === null) return null;
-  if (typeof lib !== 'object' || !Array.isArray(lib.items)) return null;
-  const out = [];
-  const seen = new Set();
-  for (const it of lib.items.slice(0, MAX_LIBRARY_ITEMS)) {
-    if (!it || typeof it.id !== 'string' || !/^[0-9a-f-]{8,64}$/i.test(it.id)) continue;
-    const path = safeLibraryPath(it.name, it.kind);
-    if (!path || seen.has(path.toLowerCase())) continue;
-    seen.add(path.toLowerCase());
-    const bundleDir = path.split('/').length >= 3 ? path.split('/').slice(0, 2).join('/') : null;
-    const expectedPreview = bundleDir ? `${bundleDir}/preview.png` : it.name.replace(/\.html$/, '.png');
-    const previewPath = it.kind === 'design' && it.preview && it.preview.name === expectedPreview ? expectedPreview : null;
-    const files = bundleDir && Array.isArray(it.files) ? it.files.map((f, index) => ({ ...f,
-      index, path: safeBundleFile(f.name, bundleDir),
-    })).filter((f) => f.path && !seen.has(f.path.toLowerCase())) : [];
-    for (const f of files) seen.add(f.path.toLowerCase());
-    out.push({ ...it, path, files, previewPath, previewUnknown: it.kind === 'design' && path.endsWith('.html') && it.preview === undefined });
-  }
-  return out;
-}
-
-/** One line of the catalog: server strings are made single-line and capped —
- *  they are a person's card title and an artifact's name, headed into a file
- *  an agent reads, so they may not carry a line break that forges a second
- *  entry. */
-const catalogText = (v, max) =>
-  String(v ?? '')
-    .replace(/[\r\n\t]+/g, ' ')
-    .replace(/\s+/g, ' ')
-    .trim()
-    .slice(0, max);
-
-/**
- * THE CATALOG, generated whole from the manifest on every sync:
- *
- *   - designs/landing-v2.html — Landing mockup (design, from card "Redesign
- *     landing page", 2026-09-23, supersedes designs/landing-v1.html)
- *
- * (one line per item, oldest first — the server's order — so a sync that adds
- * one item adds one line and moves nothing). Null when there are no items, in
- * which case the file is removed rather than written empty.
- */
-export function renderLibraryCatalog(items) {
-  if (!items || items.length === 0) return null;
-  const lines = items.map((it) => {
-    const facts = [it.kind === 'research' ? 'research' : 'design'];
-    const card = catalogText(it.taskTitle, 200);
-    if (card) facts.push(`from card "${card.replace(/"/g, "'")}"`);
-    const day = typeof it.createdAt === 'string' ? it.createdAt.slice(0, 10) : '';
-    if (/^\d{4}-\d{2}-\d{2}$/.test(day)) facts.push(day);
-    const sup = typeof it.supersedes === 'string' ? catalogText(it.supersedes, 200) : '';
-    if (sup) facts.push(`supersedes ${sup}`);
-    const title = catalogText(it.title, 200) || it.path;
-    return `- ${it.path} — ${title} (${facts.join(', ')})`;
-  });
-  return (
-    '# Library\n\n' +
-    'The designs and research this project kept. Paths are relative to this directory;\n' +
-    'a newer version supersedes an older one of the same name.\n\n' +
-    `${lines.join('\n')}\n`
-  );
-}
-
-/** A library subdirectory as a real directory — ours, like the library's own
- *  path: a symlink or a file planted there is removed, never followed. */
-function ensureSubdir(dir, name) {
-  const path = join(dir, name);
-  try {
-    const st = lstatSync(path);
-    if (st.isSymbolicLink() || !st.isDirectory()) unlinkSync(path);
-  } catch {
-    /* absent */
-  }
-  mkdirSync(path, { recursive: true });
-  return path;
-}
-
-function ensureLibraryParents(dir, relativePath) {
-  const parts = relativePath.split('/');
-  let at = dir;
-  for (const part of parts.slice(0, -1)) at = ensureSubdir(at, part);
-}
-
-function sweepLibraryTree(dir, sub, wanted, result) {
-  const walk = (at, prefix = '') => {
-    let entries;
-    try { entries = readdirSync(at); } catch { return; }
-    for (const name of entries) {
-      const rel = prefix ? `${prefix}/${name}` : name;
-      const path = join(at, name);
-      let st;
-      try { st = lstatSync(path); } catch { continue; }
-      if (st.isDirectory() && !st.isSymbolicLink()) {
-        walk(path, rel);
-        try { if (readdirSync(path).length === 0) rmSync(path, { recursive: true, force: true }); } catch { /* next sync */ }
-      } else if (!wanted.has(rel)) {
-        try { rmSync(path, { recursive: true, force: true }); result.removed.push(`${sub}/${rel}`); } catch { /* next sync */ }
-      }
-    }
-  };
-  walk(join(dir, sub));
-};
-
-/** Does this manifest look like one the server produced? Anything else is
- *  ignored whole rather than half-applied. */
-export function isKnowledgeManifest(k) {
-  return (
-    !!k &&
-    typeof k === 'object' &&
-    Number.isInteger(k.rev) &&
-    k.rev >= 0 &&
-    (k.instructions === null || k.instructions === undefined || typeof k.instructions === 'string') &&
-    Array.isArray(k.files)
-  );
-}
-
-/**
- * Make `<checkoutDir>/.flowviant/knowledge/` match `manifest`.
- *
- * `fetchFile(id)` returns the file's bytes as a Buffer, or throws. Injected so
- * the sync is testable against a temp directory and a fake server; the daemon
- * hands the `/fleet/knowledge/:id` fetch.
- *
- * @returns {{ ok: boolean, wrote: string[], removed: string[], refused: string[], failed: string[] }}
- *   `ok` is false when any download FAILED (to be retried); a file REFUSED for
- *   size is permanent for this rev and does not clear `ok`.
- */
-export async function syncKnowledge({ checkoutDir, manifest, fetchFile, maxBytes = KNOWLEDGE_FILE_MAX_BYTES }) {
-  const result = { ok: true, wrote: [], removed: [], refused: [], failed: [] };
-  const dirPath = join(checkoutDir, KNOWLEDGE_DIR);
-  const files = (manifest.files ?? [])
-    .filter((f) => f && typeof f.id === 'string' && /^[0-9a-f-]{8,64}$/i.test(f.id))
-    .slice(0, MAX_FILES);
-  const instructions =
-    typeof manifest.instructions === 'string' && manifest.instructions.trim()
-      ? manifest.instructions
-      : null;
-  // null = the key is ABSENT (leave the library's paths alone); [] = emptied.
-  const library = libraryItemsOf(manifest);
-
-  if (!flowviantDirOk(checkoutDir)) {
-    // Not a failure to retry every poll — nothing changes until a person
-    // changes it — but not a success either: the rev must not advance over a
-    // library that was never written.
-    result.ok = false;
-    result.failed.push('.flowviant (not a directory — left untouched)');
-    return result;
-  }
-
-  // EMPTIED: the directory goes, and the prompt paragraph with it — unless the
-  // library key is ABSENT and a synced library is on disk, which an older
-  // server's emptied shelf has no say over.
-  const libraryOnDisk =
-    library === null &&
-    [LIBRARY_FILE, ...Object.values(LIBRARY_DIRS)].some((n) => existsSync(join(dirPath, n)));
-  if (files.length === 0 && !instructions && (library === null ? !libraryOnDisk : library.length === 0)) {
-    if (existsSync(dirPath)) {
-      try {
-        const st = lstatSync(dirPath);
-        if (st.isSymbolicLink()) unlinkSync(dirPath);
-        else rmSync(dirPath, { recursive: true, force: true });
-        result.removed.push(KNOWLEDGE_DIR);
-      } catch {
-        result.ok = false;
-      }
-    }
-    return result;
-  }
-
-  const dir = ensureDir(checkoutDir);
-  const planned = planKnowledgeNames(files);
-  const keep = new Set(planned.map((p) => p.local));
-  if (instructions) keep.add(INSTRUCTIONS_FILE);
-  // ABSENT library key: its paths are neither synced nor swept.
-  if (library === null) {
-    keep.add(LIBRARY_FILE);
-    for (const d of Object.values(LIBRARY_DIRS)) keep.add(d);
-  }
-
-  for (const f of planned) {
-    const path = join(dir, f.local);
-    const fileMax = knowledgeMaxFor(f.name, maxBytes);
-    if (Number(f.bytes) > fileMax) {
-      // Permanent for this rev, and NOT a reason to delete the rest. Any stale
-      // local copy under this name goes, because it is not the file the
-      // manifest now names.
-      result.refused.push(f.local);
-      keep.delete(f.local);
-      continue;
-    }
-    if (typeof f.sha256 === 'string' && localSha(path) === f.sha256.toLowerCase()) continue;
-    try {
-      const buf = await fetchFile(f.id);
-      if (!Buffer.isBuffer(buf) || buf.byteLength > fileMax) {
-        result.refused.push(f.local);
-        keep.delete(f.local);
-        continue;
-      }
-      // The bytes must BE the file the manifest names. A mismatch is a
-      // failure to retry, never a file to trust.
-      if (typeof f.sha256 === 'string' && sha256Of(buf) !== f.sha256.toLowerCase()) {
-        throw new Error('sha256 mismatch');
-      }
-      writeAtomic(path, buf);
-      result.wrote.push(f.local);
-    } catch {
-      result.ok = false;
-      result.failed.push(f.local);
-      // Keep whatever copy is there: a stale file is better than a missing one
-      // until the retry lands.
-    }
-  }
-
-  if (instructions) {
-    const path = join(dir, INSTRUCTIONS_FILE);
-    const body = instructions.endsWith('\n') ? instructions : `${instructions}\n`;
-    let same = false;
-    try {
-      same = lstatSync(path).isFile() && readFileSync(path, 'utf8') === body;
-    } catch {
-      /* absent */
-    }
-    if (!same) {
-      writeAtomic(path, body);
-      result.wrote.push(INSTRUCTIONS_FILE);
-    }
-  }
-
-  if (library !== null) {
-    await syncLibrary({ dir, items: library, fetchFile, maxBytes, keep, result });
-  }
-
-  // Everything the manifest no longer names — files, stray temp names, and
-  // anything that is not a regular file — leaves.
-  let entries = [];
-  try {
-    entries = readdirSync(dir);
-  } catch {
-    entries = [];
-  }
-  for (const name of entries) {
-    if (keep.has(name)) continue;
-    try {
-      rmSync(join(dir, name), { recursive: true, force: true });
-      result.removed.push(name);
-    } catch {
-      /* best-effort; the next sync tries again */
-    }
-  }
-  return result;
-}
-
-/**
- * THE KEPT LIBRARY'S HALF OF A SYNC: each item into its subdirectory (fetched
- * only when its sha differs, written atomically, the bytes checked against the
- * manifest), every other entry in the two subdirectories removed, and
- * `LIBRARY.md` regenerated from the items that are on disk. A download that
- * fails keeps whatever copy was there and clears `ok`, the file rule; an item
- * over the cap is refused for this rev and left out of the catalog.
- */
-async function syncLibrary({ dir, items, fetchFile, maxBytes, keep, result }) {
-  const wanted = { designs: new Set(), research: new Set() };
-  const onDisk = [];
-  for (const kind of Object.keys(LIBRARY_DIRS)) {
-    if (items.some((it) => it.kind === kind)) {
-      ensureSubdir(dir, LIBRARY_DIRS[kind]);
-      keep.add(LIBRARY_DIRS[kind]);
-    }
-  }
-  for (const it of items) {
-    const [sub, ...tail] = it.path.split('/');
-    const file = tail.join('/');
-    const path = join(dir, ...it.path.split('/'));
-    ensureLibraryParents(dir, it.path);
-    const itemMax = knowledgeMaxFor(it.path, maxBytes);
-    wanted[sub].add(file);
-    if (it.previewPath) wanted[sub].add(it.previewPath.split('/').slice(1).join('/'));
-    if (it.previewUnknown) {
-      const oldPng = file.includes('/') ? `${file.slice(0, file.lastIndexOf('/'))}/preview.png` : file.replace(/\.html$/, '.png');
-      if (localSha(join(dir, sub, ...oldPng.split('/'))) !== null) wanted[sub].add(oldPng);
-    }
-    if (Number(it.bytes) > itemMax) {
-      result.refused.push(it.path);
-      wanted[sub].delete(file);
-      continue;
-    }
-    if (typeof it.sha256 === 'string' && localSha(path) === it.sha256.toLowerCase()) {
-      onDisk.push(it);
-    } else {
-      try {
-        const buf = await fetchFile(it.id, { library: true });
-        if (!Buffer.isBuffer(buf) || buf.byteLength > itemMax) {
-          result.refused.push(it.path);
-          wanted[sub].delete(file);
-          continue;
-        }
-        if (typeof it.sha256 === 'string' && sha256Of(buf) !== it.sha256.toLowerCase()) {
-          throw new Error('sha256 mismatch');
-        }
-        ensureLibraryParents(dir, it.path);
-        writeAtomic(path, buf);
-        result.wrote.push(it.path);
-        onDisk.push(it);
-      } catch {
-        result.ok = false;
-        result.failed.push(it.path);
-        if (localSha(path) !== null) onDisk.push(it);
-      }
-    }
-    if (it.previewPath && it.preview?.sha256) {
-      ensureLibraryParents(dir, it.previewPath);
-      const previewFile = join(dir, ...it.previewPath.split('/'));
-      if (localSha(previewFile) !== it.preview.sha256.toLowerCase()) {
-        try {
-          const buf = await fetchFile(it.id, { library: true, preview: true });
-          if (!Buffer.isBuffer(buf) || buf.byteLength > 2 * 1024 * 1024 || sha256Of(buf) !== it.preview.sha256.toLowerCase()) throw new Error('preview mismatch');
-          ensureLibraryParents(dir, it.previewPath);
-          writeAtomic(previewFile, buf);
-          result.wrote.push(it.previewPath);
-        } catch {
-          result.ok = false;
-          result.failed.push(it.previewPath);
-        }
-      }
-    }
-    for (const f of it.files ?? []) {
-      ensureLibraryParents(dir, f.path);
-      const rel = f.path.split('/').slice(1).join('/');
-      wanted[sub].add(rel);
-      const filePath = join(dir, ...f.path.split('/'));
-      const fileMax = knowledgeMaxFor(f.path, maxBytes);
-      if (Number(f.bytes) > fileMax) { result.refused.push(f.path); wanted[sub].delete(rel); continue; }
-      if (localSha(filePath) === String(f.sha256).toLowerCase()) continue;
-      try {
-        const buf = await fetchFile(it.id, { library: true, fileIndex: f.index });
-        if (!Buffer.isBuffer(buf) || buf.byteLength > fileMax) { result.refused.push(f.path); wanted[sub].delete(rel); continue; }
-        if (sha256Of(buf) !== String(f.sha256).toLowerCase()) throw new Error('sha256 mismatch');
-        ensureLibraryParents(dir, f.path);
-        writeAtomic(filePath, buf);
-        result.wrote.push(f.path);
-      } catch { result.ok = false; result.failed.push(f.path); }
-    }
-  }
-  // Each subdirectory holds exactly what the manifest names.
-  for (const sub of Object.values(LIBRARY_DIRS)) {
-    const subPath = join(dir, sub);
-    try { if (!lstatSync(subPath).isDirectory()) continue; } catch { continue; }
-    sweepLibraryTree(dir, sub, wanted[sub], result);
-    // An emptied subdirectory leaves with its last item.
-    if (wanted[sub].size === 0) keep.delete(sub);
-  }
-  const catalog = renderLibraryCatalog(onDisk);
-  if (catalog) {
-    keep.add(LIBRARY_FILE);
-    const path = join(dir, LIBRARY_FILE);
-    let same = false;
-    try {
-      same = lstatSync(path).isFile() && readFileSync(path, 'utf8') === catalog;
-    } catch {
-      /* absent */
-    }
-    if (!same) {
-      writeAtomic(path, catalog);
-      result.wrote.push(LIBRARY_FILE);
-    }
-  }
-}
-
-/**
- * The absolute library path, or null when there is nothing there for a turn
- * to read. The prompt paragraph is rendered only when this is non-null, so a
- * project with no library costs the prompt nothing.
- */
-export function knowledgeDirFor(checkoutDir) {
-  if (!checkoutDir || !flowviantDirOk(checkoutDir)) return null;
-  const dir = join(checkoutDir, KNOWLEDGE_DIR);
-  try {
-    if (!lstatSync(dir).isDirectory()) return null;
-    return readdirSync(dir).length > 0 ? dir : null;
-  } catch {
-    return null;
-  }
-}
-
-/** Does the manifest name something the disk no longer has a directory for?
- *  An EMPTIED manifest over no directory is the synced state, not a loss. */
-function libraryMissing(checkoutDir, manifest) {
-  const named =
-    (Array.isArray(manifest.files) && manifest.files.length > 0) ||
-    (typeof manifest.instructions === 'string' && manifest.instructions.trim() !== '') ||
-    (Array.isArray(manifest.library?.items) && manifest.library.items.length > 0);
-  if (!named) return false;
-  try {
-    lstatSync(join(checkoutDir, KNOWLEDGE_DIR));
-    return false;
-  } catch {
-    return true;
-  }
-}
-
-/**
- * Does the manifest name LIBRARY items the disk no longer holds — or a library
- * this box never synced at all? The same-rev skip's second question, beside
- * `libraryMissing`'s "is the directory there".
- *
- * `synced` is the marker's `:lib` (or the driver's memory of it): false means
- * the rev on the marker was written by a sync that ignored the library, the
- * 0.96.0-to-0.97.0 upgrade. Otherwise every named item's path AND `LIBRARY.md`
- * must be regular files — a hand-deleted `designs/`, or one item removed, is a
- * re-sync, and the files still on disk match by hash and are not fetched
- * again. Items the manifest itself puts over the cap, and items this driver
- * already saw refused for this rev, are not expected: a refusal is permanent
- * for the rev, and expecting it would re-fetch ten megabytes every poll.
- * An ABSENT `library` key expects nothing (an older server has no say).
- */
-function libraryStale(checkoutDir, manifest, { synced, refused }) {
-  const items = libraryItemsOf(manifest);
-  if (items === null) return false;
-  if (!synced) return true;
-  const expected = items.filter((it) => !(Number(it.bytes) > knowledgeMaxFor(it.path, KNOWLEDGE_FILE_MAX_BYTES)) && !refused.has(it.path));
-  if (expected.length === 0) return false;
-  const dir = join(checkoutDir, KNOWLEDGE_DIR);
-  const isFile = (p) => {
-    try {
-      let parent = dir;
-      for (const part of p.slice(dir.length + 1).split('/').slice(0, -1)) {
-        parent = join(parent, part);
-        const st = lstatSync(parent);
-        if (st.isSymbolicLink() || !st.isDirectory()) return false;
-      }
-      return lstatSync(p).isFile();
-    } catch {
-      return false;
-    }
-  };
-  if (!isFile(join(dir, LIBRARY_FILE))) return true;
-  return expected.some((it) => !isFile(join(dir, ...it.path.split('/'))) ||
-    (it.previewPath && !refused.has(it.previewPath) && !isFile(join(dir, ...it.previewPath.split('/')))) ||
-    (it.files ?? []).some((f) => !refused.has(f.path) && !isFile(join(dir, ...f.path.split('/')))));
-}
+  knowledgeMarkerHasLibrary,
+  libraryMissing,
+  libraryStale,
+  readKnowledgeMarker,
+  syncKnowledge,
+  writeKnowledgeMarker,
+} from './knowledgeFiles.mjs';
 
 /**
  * The per-process driver: called with every roster's `knowledge` key.
@@ -938,31 +183,3 @@ export function createKnowledgeSync({
     },
   };
 }
-
-/**
- * The `/fleet/knowledge/:id` download, in the attachment fetch's own shape:
- * the machine credential as a bearer, a 60s ceiling, and the size checked on
- * the header AND on the bytes (a lying header must not decide the cap). The
- * URL is derived from the roster URL the way every `/fleet/*` path is, so a
- * self-hosted `FLOWVIANT_FLEET_URL` is honoured.
- */
-export function knowledgeFetcher({ fleetUrl, token, userAgent, maxBytes = KNOWLEDGE_BINARY_MODEL_MAX_BYTES }) {
-  const base = String(fleetUrl).replace(/\/agents\/?$/, '/knowledge');
-  // A kept library item (0.97.0) is its sibling, `GET /fleet/library/:id` —
-  // the same credential, the same shape, the same caps.
-  const libraryBase = String(fleetUrl).replace(/\/agents\/?$/, '/library');
-  return async (id, { library = false, preview = false, fileIndex = null } = {}) => {
-    const suffix = preview ? '/preview' : Number.isSafeInteger(fileIndex) && fileIndex >= 0 ? `/file/${fileIndex}` : '';
-    const res = await fetch(`${library ? libraryBase : base}/${encodeURIComponent(id)}${suffix}`, {
-      headers: { Authorization: `Bearer ${token}`, 'User-Agent': userAgent },
-      signal: AbortSignal.timeout(60_000),
-    });
-    if (!res.ok) throw new Error(`HTTP ${res.status}`);
-    if (Number(res.headers.get('content-length') ?? '0') > maxBytes) {
-      // Returned rather than thrown: over the cap is a REFUSAL, permanent for
-      // this rev, not a failure the backoff should keep retrying.
-      return Buffer.alloc(maxBytes + 1);
-    }
-    return Buffer.from(await res.arrayBuffer());
-  };
-}