@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/src/journal.ts

@@ -1,765 +0,0 @@
-/**
- * Sync journal — tracks per-file state (hash, size, last-synced direction) so
- * sync/share can detect local edits that would be clobbered by a blind pull.
- *
- * ADR-0001 Phase 5: the journal is sharded by company slug and lives in
- * `~/.hq/`, not inside the HQ content root. One monolithic journal per HQ
- * install conflates state across companies and forces every runner to
- * serialize through the same file — splitting it lets `hq-sync-runner
- * --companies` fan out without contention, and a corrupted shard only affects
- * one company.
- *
- * Path: `{stateDir}/sync-journal.{slug}.json`, where `stateDir` resolves to
- * `HQ_STATE_DIR` (if set) or `~/.hq`.
- */
-
-import * as fs from "fs";
-import * as os from "os";
-import * as path from "path";
-import * as crypto from "crypto";
-import type { SyncJournal, JournalEntry, PullRecord, V3JournalState, V3JournalWalPayload } from "./types.js";
-import { toPosixKey } from "./s3.js";
-import { StateStore } from "./sync/state-store.js";
-
-/** Tombstone retention. 30 days in milliseconds — roughly two release cycles. */
-export const TOMBSTONE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
-
-/** Current journal schema version written by all v2-aware writers. */
-export const JOURNAL_VERSION_CURRENT = "2" as const;
-
-/**
- * Retain bounded pull history per company. Scope-shrink logic only needs the
- * newest record, but a small tail keeps diagnostics useful without letting
- * long-running sync loops grow journals forever.
- */
-export const MAX_PULLS_PER_COMPANY = 50;
-
-const JOURNAL_FILE_PREFIX = "sync-journal.";
-const JOURNAL_FILE_SUFFIX = ".json";
-const JOURNAL_LAST_GOOD_SUFFIX = ".last-good";
-const JOURNAL_WAL_RECORD_TYPE = 1;
-
-
-/**
- * Where per-company journals are stored. Honors `HQ_STATE_DIR` for tests and
- * non-standard installs; otherwise falls back to `~/.hq`.
- */
-export function getStateDir(): string {
-  return process.env.HQ_STATE_DIR ?? path.join(os.homedir(), ".hq");
-}
-
-/**
- * Filename-safe form of a slug. Slugs from vault-service are already
- * URL-safe, but this guards against paths, dots, or anything the filesystem
- * might interpret. Empty-or-invalid slugs throw rather than silently writing
- * to a shared "sync-journal..json" file.
- */
-function sanitizeSlug(slug: string): string {
-  if (!slug) {
-    throw new Error("journal: slug is required (empty or undefined)");
-  }
-  const cleaned = slug.replace(/[^a-zA-Z0-9_-]/g, "_");
-  if (!cleaned || /^[_-]+$/.test(cleaned)) {
-    throw new Error(`journal: slug "${slug}" sanitizes to an empty identifier`);
-  }
-  return cleaned;
-}
-
-export function getJournalPath(slug: string): string {
-  return path.join(
-    getStateDir(),
-    `${JOURNAL_FILE_PREFIX}${sanitizeSlug(slug)}${JOURNAL_FILE_SUFFIX}`,
-  );
-}
-
-/**
- * Reserved journal slug for the personal-vault fanout slot in the `--companies`
- * runner. The vault slot uploads the whole HQ overlay (`.claude/`, `core/`,
- * `personal/`, …) and journals hq-root-relative keys; its `syncRoot` is the HQ
- * root itself.
- *
- * It MUST NOT share a journal with any real cloud company. Previously the slot
- * used the literal slug `"personal"`, which collided with the
- * `companies/personal` company (whose entity slug is also `"personal"`). The
- * two targets have different sync roots, so the company's whole-tree
- * `computeDeletePlan` walked the shared `sync-journal.personal.json`, resolved
- * the vault's hq-root keys against `hqRoot/companies/personal` (where they
- * don't exist), tombstoned them as "remote already 404", and dropped them from
- * the journal — only for the vault slot to re-upload them next cycle. ~190
- * `.claude/skills/*` files churned every sync.
- *
- * This sentinel value can never be produced by a real company slug from the
- * entity service (which yields URL-safe lowercase slugs without leading
- * underscores), and it survives `sanitizeSlug` unchanged (only `[a-zA-Z0-9_-]`
- * chars; the embedded letters keep it off the all-`[_-]` reject path).
- */
-export const PERSONAL_VAULT_JOURNAL_SLUG = "__hq_personal_vault__";
-
-/**
- * One-time seed migration for the personal-vault journal slug.
- *
- * Before this fix the personal-vault slot journaled under the slug
- * `"personal"`. After the fix it journals under
- * `PERSONAL_VAULT_JOURNAL_SLUG`. Without a seed, the first run under the new
- * slug would start from an empty journal and re-upload the entire HQ overlay.
- *
- * To avoid that mass re-upload, this copies the legacy `sync-journal.personal.json`
- * to `sync-journal.__hq_personal_vault__.json` exactly once: only when the new
- * file does NOT exist and the legacy file DOES. Idempotent — a no-op when the
- * new file already exists or the legacy file is absent.
- *
- * The legacy `personal` journal is left untouched (it is still the journal for
- * the real `companies/personal` company). After the seed, both journals
- * converge after one cleanup cycle: the legacy `personal` journal tombstones
- * the now-foreign hq-root keys once; the new vault journal tombstones any
- * companies/personal-relative keys once. That single convergence pass is
- * expected and harmless.
- */
-export function migratePersonalVaultJournal(): void {
-  const newPath = getJournalPath(PERSONAL_VAULT_JOURNAL_SLUG);
-  if (fs.existsSync(newPath)) return;
-  const legacyPath = getJournalPath("personal");
-  if (!fs.existsSync(legacyPath)) return;
-  const legacy = readJournal("personal");
-  writeJournal(PERSONAL_VAULT_JOURNAL_SLUG, legacy);
-}
-
-/**
- * Read a per-company journal from disk.
- *
- * Back-compat (US-005, v1 → v2): a v1 file on disk is returned as-is with
- * `version: "1"` and no `pulls` field. The in-place migration to v2 happens
- * the first time `writeJournal` runs — `migrateToV2` ensures any journal
- * passed to the writer carries `version: "2"`, `pulls: []`, and the rest of
- * the v2 shape. This keeps `readJournal` deterministic + cheap and confines
- * the side effect (schema bump on disk) to writes.
- *
- * When the file doesn't exist, we return a fresh v2 journal directly — new
- * installs never pass through v1 on disk.
- */
-export function readJournal(slug: string): SyncJournal {
-  if (StateStore.exists(getStateDir(), journalScopeId(slug))) {
-    return openJournalStore(slug, emptyJournal()).getState().journal;
-  }
-  const journalPath = getJournalPath(slug);
-  let legacy: SyncJournal;
-  if (fs.existsSync(journalPath)) {
-    legacy = readJournalFileWithLastGood(journalPath);
-  } else {
-    legacy = emptyJournal();
-  }
-  migrateToV2(legacy);
-  return openJournalStore(slug, legacy).getState().journal;
-}
-
-function emptyJournal(): SyncJournal {
-  return { version: JOURNAL_VERSION_CURRENT, lastSync: "", files: {}, pulls: [] };
-}
-
-function journalScopeId(slug: string): string {
-  return `journal:${sanitizeSlug(slug)}`;
-}
-
-function openJournalStore(slug: string, initialJournal: SyncJournal): StateStore<V3JournalState> {
-  return StateStore.open({
-    rootDir: getStateDir(),
-    scopeId: journalScopeId(slug),
-    initialState: { journal: initialJournal },
-    reduce: (state, record) => {
-      if (record.type !== JOURNAL_WAL_RECORD_TYPE) {
-        throw new Error(`journal: unexpected v3 WAL record type ${record.type}`);
-      }
-      const payload = record.payload as Partial<V3JournalWalPayload>;
-      if (!payload || typeof payload !== "object" || !isJournal(payload.journal)) {
-        throw new Error("journal: v3 WAL record has an invalid journal payload");
-      }
-      return { ...state, journal: payload.journal };
-    },
-  });
-}
-
-function isJournal(value: unknown): value is SyncJournal {
-  return typeof value === "object" && value !== null &&
-    ((value as SyncJournal).version === "1" || (value as SyncJournal).version === "2") &&
-    typeof (value as SyncJournal).lastSync === "string" &&
-    typeof (value as SyncJournal).files === "object" &&
-    (value as SyncJournal).files !== null;
-}
-
-function parseJournalContent(content: string): SyncJournal {
-  if (content.length === 0) {
-    throw new SyntaxError("journal JSON is empty");
-  }
-  return JSON.parse(content) as SyncJournal;
-}
-
-function isCorruptJournalJson(err: unknown): boolean {
-  return err instanceof SyntaxError;
-}
-
-function readJournalFileWithLastGood(journalPath: string): SyncJournal {
-  let primaryErr: unknown;
-  try {
-    return parseJournalContent(fs.readFileSync(journalPath, "utf-8"));
-  } catch (err) {
-    if (!isCorruptJournalJson(err)) throw err;
-    primaryErr = err;
-  }
-
-  try {
-    return parseJournalContent(
-      fs.readFileSync(lastGoodJournalPath(journalPath), "utf-8"),
-    );
-  } catch {
-    throw primaryErr;
-  }
-}
-
-/** One enumerated journal shard: its recovered slug, on-disk path, contents. */
-export interface JournalSummary {
-  /**
-   * Slug recovered from the `sync-journal.<slug>.json` filename — the
-   * sanitized form the engine wrote (e.g. a company slug,
-   * `PERSONAL_VAULT_JOURNAL_SLUG`, or the legacy `"personal"`).
-   */
-  slug: string;
-  /** Absolute path to the journal file. */
-  path: string;
-  /** Parsed journal contents. */
-  journal: SyncJournal;
-}
-
-/**
- * Enumerate every sync journal present in the state dir.
- *
- * The engine SHARDS journals by slug (ADR-0001 Phase 5): the personal-vault
- * fanout slot under `PERSONAL_VAULT_JOURNAL_SLUG`, one shard per cloud company,
- * and the legacy `"personal"` shard. A caller that reads a single fixed path
- * therefore only ever sees one scope — and a caller that mistakes a non-slug
- * value for a slug (e.g. `hq sync status` passing the HQ-root PATH, which
- * `sanitizeSlug` mangles into `_Users_<user>_hq`) sees a slug the engine never
- * writes, and reports "no journal" right after a successful sync. Any surface
- * that wants the COMPLETE local sync picture must read ALL shards via this
- * helper rather than reconstructing a path.
- *
- * Slugs are recovered from each filename. A shard that fails to read or parse
- * is skipped rather than thrown — one corrupt shard must not blind the caller
- * to the healthy ones. Results are sorted by slug for deterministic output.
- */
-export function listJournals(): JournalSummary[] {
-  const dir = getStateDir();
-  let names: string[];
-  try {
-    names = fs.readdirSync(dir);
-  } catch {
-    return []; // state dir absent → no journals yet
-  }
-  const out: JournalSummary[] = [];
-  for (const name of names) {
-    if (
-      !name.startsWith(JOURNAL_FILE_PREFIX) ||
-      !name.endsWith(JOURNAL_FILE_SUFFIX)
-    ) {
-      continue;
-    }
-    const slug = name.slice(
-      JOURNAL_FILE_PREFIX.length,
-      name.length - JOURNAL_FILE_SUFFIX.length,
-    );
-    if (!slug) continue; // guard against a stray "sync-journal..json"
-    const filePath = path.join(dir, name);
-    try {
-      // Prefer the v3 store when this legacy filename is only its immutable
-      // compatibility locator; otherwise this performs the v2 last-good read.
-      const journal = readJournal(slug);
-      out.push({ slug, path: filePath, journal });
-    } catch (err) {
-      if (!isCorruptJournalJson(err)) throw err;
-      // Corrupt shard with no usable last-good — skip; don't blind the caller
-      // to the rest. Genuine IO/permission failures surface to the caller.
-    }
-  }
-  out.sort((a, b) => a.slug.localeCompare(b.slug));
-  return out;
-}
-
-/**
- * Defuse the pre-5.47.2 Windows backslash-key landmine in a journal's `files`
- * map. Such clients stamped keys with the OS path separator ("\\"), e.g.
- * `projects\\forecast-development\\x.csv`. A backslash key is a live data-loss
- * hazard for the cross-machine delete planner (Bug #9): it never matches the
- * forward-slash remote LIST, so the planner classifies the still-present local
- * file as remote-deleted, and `path.join(companyRoot, key)` collapses the
- * backslashes back onto the REAL POSIX file — which the executor then unlinks
- * (ridge incident, feedback_b8d09d0f: a single pull deleted ~36 live files,
- * with 587 backslash keys left in the journal as a recurring landmine).
- *
- * Rewriting every key to its canonical POSIX form on load removes the hazard
- * idempotently — a clean (all-POSIX) journal is returned untouched. Merge rule:
- * if a key's POSIX twin already exists, the POSIX entry is authoritative (it
- * round-tripped through an up-to-date client) and the malformed duplicate is
- * dropped; otherwise the entry is moved to its POSIX key. Returns the number of
- * keys rewritten (0 for a clean journal) for telemetry and test assertions.
- */
-export function normalizeJournalKeys(journal: SyncJournal): number {
-  if (!journal.files) return 0;
-  let rewritten = 0;
-  // Snapshot keys up front — we mutate journal.files during the walk.
-  for (const key of Object.keys(journal.files)) {
-    const posix = toPosixKey(key);
-    if (posix === key) continue; // already canonical (no backslash)
-    const entry = journal.files[key];
-    delete journal.files[key];
-    rewritten++;
-    // POSIX twin already present → it wins; drop the malformed duplicate.
-    if (!(posix in journal.files)) {
-      journal.files[posix] = entry;
-    }
-  }
-  return rewritten;
-}
-
-/**
- * Coerce any-version journal into a v2 shape. Idempotent for v2 inputs.
- * Mutates the input and returns it for chainable use. Call this immediately
- * after `readJournal` if your code-path needs the v2 fields.
- *
- * v1 → v2 contract: every existing `files[]` entry is preserved as-is; no
- * tombstone fields are inserted (legacy entries are NOT scope-shrink
- * tombstones). `pulls` becomes `[]` (empty history → treat last scope as
- * "all" in the scope-shrink algorithm).
- */
-export function migrateToV2(journal: SyncJournal): SyncJournal {
-  // Backslash-key normalization runs UNCONDITIONALLY — a poisoned journal can
-  // already carry version "2" (the landmine predates the schema bump), so this
-  // must precede the v2 early-return or already-v2 journals stay poisoned.
-  normalizeJournalKeys(journal);
-  if (journal.version === "2" && Array.isArray(journal.pulls)) {
-    return journal;
-  }
-  journal.version = JOURNAL_VERSION_CURRENT;
-  if (!Array.isArray(journal.pulls)) journal.pulls = [];
-  return journal;
-}
-
-/**
- * Write a journal to disk, migrating to the current schema version in-place.
- * `migrateToV2` mutates the passed-in object — callers that hold a reference
- * after the write will see the v2 shape.
- */
-export function writeJournal(slug: string, journal: SyncJournal): void {
-  migrateToV2(journal);
-  const store = openJournalStore(slug, journal);
-  // The initial v2 → v3 migration is a durable snapshot. Every normal write
-  // thereafter is one framed append + fdatasync, never a whole-journal rewrite.
-  if (store.wasCreated) {
-    writeLegacyJournalMirror(slug, journal);
-  } else {
-    store.append(JOURNAL_WAL_RECORD_TYPE, { journal });
-    // The JSON file remains a compatibility mirror for shipped CLI/status
-    // consumers that have not moved to StateStore yet. It is never used for
-    // recovery once a v3 generation exists; the framed WAL above is the sole
-    // authority and hot path. Keep the mirror current so those consumers do
-    // not observe stale sync state during the phased migration.
-    writeLegacyJournalMirror(slug, journal);
-  }
-}
-
-/**
- * Keep the v2-shaped filename as a compatibility mirror for older CLI/status
- * surfaces. The v3 state store is authoritative after migration; this mirror
- * is atomically replaced only to preserve existing readers until their owner
- * migrates them. WAL recovery never consults it once a v3 generation exists.
- */
-function writeLegacyJournalMirror(slug: string, journal: SyncJournal): void {
-  const journalPath = getJournalPath(slug);
-  fs.mkdirSync(path.dirname(journalPath), { recursive: true });
-  const temporary = path.join(
-    path.dirname(journalPath),
-    `.${path.basename(journalPath)}.${process.pid}.${crypto.randomBytes(6).toString("hex")}.tmp`,
-  );
-  let fd: number | undefined;
-  try {
-    fd = fs.openSync(temporary, "wx");
-    fs.writeFileSync(fd, JSON.stringify(journal));
-    fs.fdatasyncSync(fd);
-    fs.closeSync(fd);
-    fd = undefined;
-    fs.renameSync(temporary, journalPath);
-  } catch (error) {
-    try { fs.rmSync(temporary, { force: true }); } catch { /* preserve mirror write failure */ }
-    throw new Error(`journal: failed to update v3 compatibility mirror ${journalPath}`, { cause: error });
-  } finally {
-    if (fd !== undefined) fs.closeSync(fd);
-  }
-}
-
-function lastGoodJournalPath(journalPath: string): string {
-  return `${journalPath}${JOURNAL_LAST_GOOD_SUFFIX}`;
-}
-
-
-export function hashFile(filePath: string): string {
-  const content = fs.readFileSync(filePath);
-  return crypto.createHash("sha256").update(content).digest("hex");
-}
-
-/**
- * Marker prepended to a symlink's target string before hashing for the
- * journal. Mirrors the wire-side `SYMLINK_BODY_PREFIX` constant in
- * `s3.ts` — same purpose, different namespace.
- *
- * Without this marker, a symlink to `real.md` and a regular file whose
- * contents are exactly the bytes `real.md` produce identical journal
- * hashes (both `sha256("real.md")`). When `skipUnchanged` is enabled,
- * the planner would treat a regular-file → symlink replacement as
- * "no change" and never upload the new symlink, leaving the remote
- * representation stale forever — the pull side would then also see no
- * drift via ETag and never repair.
- *
- * Hashing `sha256(prefix + target)` makes the two representations
- * structurally inequal in journal-hash space, so skip-unchanged can
- * never confuse them. The hash always varies with the target string,
- * so target rewrites still re-fire uploads as expected.
- */
-export const SYMLINK_HASH_PREFIX = "hq-symlink:";
-
-/**
- * Compute the journal hash for a symlink. Always use this helper
- * (never inline `crypto.createHash` with the raw target) so the
- * push side, the pull-planner, and the post-download stamp stay in
- * lockstep on the prefixed-hash convention.
- */
-export function hashSymlinkTarget(target: string): string {
-  return crypto
-    .createHash("sha256")
-    .update(SYMLINK_HASH_PREFIX + target)
-    .digest("hex");
-}
-
-/**
- * Record a per-file journal entry after a transfer.
- *
- * `direction` (`"up"` = pushed / locally authored, `"down"` = pulled) is what
- * lets scope-shrink tell your own work apart from a mirror of someone else's.
- * It underpins the US-006 push-only sessions contract: a session transcript
- * this machine authored and pushed is stamped `direction:"up"`, so even though
- * `sessions/` is excluded from every pull scope, `buildScopeShrinkPlan` skips
- * `direction:"up"` entries and never orphans it. (Sessions fetched on demand
- * via `hq files get` are pulled — `direction:"down"` — but ride the pin union
- * in the caller's inclusion prefixSet, so they are likewise never pruned.)
- */
-/**
- * Thrown when a caller tries to journal a path that is not on disk.
- *
- * Deliberately loud rather than a silent skip: a caller reaching this has a
- * real ordering bug, and swallowing it would reintroduce exactly the silent
- * drift this guard exists to prevent.
- */
-export class PrematureJournalEntryError extends Error {
-  constructor(readonly relativePath: string, readonly absolutePath: string) {
-    super(
-      `refusing to journal '${relativePath}': no file at '${absolutePath}'. ` +
-        `A journal entry must be written only AFTER its file is on disk.`,
-    );
-    this.name = "PrematureJournalEntryError";
-  }
-}
-
-/**
- * Optional fields of a journal entry.
- *
- * These are an OBJECT rather than trailing positional parameters because they
- * were four adjacent optionals, two of them `string`, and callers drifted:
- * two conflict-resolution sites in `cli/sync.ts` passed their `"file" |
- * "symlink"` value into the `createdBySub` slot, so `entry.kind` was silently
- * never set on any conflict-resolved entry. That is not cosmetic — `entry.kind`
- * gates delete-intent minting (`markLocalDeleteIntent` requires it to match,
- * and the watcher skips any entry without one), so a file that had ever been
- * through conflict resolution could never be deleted, even with a live watcher.
- * Named fields make that class of mistake unrepresentable.
- */
-export interface UpdateEntryOptions {
-  remoteEtag?: string;
-  mtimeMs?: number;
-  /** Object's `created-by-sub` S3 metadata. Download path only. */
-  createdBySub?: string;
-  kind?: "file" | "symlink";
-}
-
-/**
- * Record a journal entry for a file that is CONFIRMED present on disk.
- *
- * `verifyAbsolutePath` is required, and the entry is written only after an
- * `lstat` proves the file exists. This is a load-bearing invariant, not a
- * defensive nicety: a journal entry says "this key was synced and the local
- * copy is at this hash". Once delete propagation authorizes on ETag currency
- * alone (no watcher-minted intent), an entry whose file was never actually
- * written becomes indistinguishable from "the user deleted this file" — and
- * the next push issues a remote DeleteObject for a file that was only ever
- * premature bookkeeping.
- *
- * Every existing caller already had a `fs.lstatSync` in hand and passed values
- * derived from it, so this makes an existing convention structural. The point
- * is that a FUTURE caller cannot get it wrong: with the check inside this
- * function there is no longer a way to add a call site that records an entry
- * for a file that is not there.
- *
- * `lstat` (not `stat`) so a dangling symlink still counts as present — the
- * link itself is the synced object, and its target may legitimately be absent.
- *
- * @throws PrematureJournalEntryError when nothing exists at `verifyAbsolutePath`.
- */
-export function updateEntry(
-  journal: SyncJournal,
-  relativePath: string,
-  hash: string,
-  size: number,
-  direction: "up" | "down",
-  verifyAbsolutePath: string,
-  opts: UpdateEntryOptions = {},
-): void {
-  try {
-    fs.lstatSync(verifyAbsolutePath);
-  } catch {
-    throw new PrematureJournalEntryError(relativePath, verifyAbsolutePath);
-  }
-  const { remoteEtag, mtimeMs, createdBySub, kind } = opts;
-  const entry: JournalEntry = {
-    hash,
-    size,
-    syncedAt: new Date().toISOString(),
-    direction,
-  };
-  if (remoteEtag !== undefined && remoteEtag !== "") {
-    entry.remoteEtag = normalizeEtag(remoteEtag);
-  }
-  if (mtimeMs !== undefined) {
-    entry.mtimeMs = mtimeMs;
-  }
-  // Authorship (scope-shrink guard input). Stamped from the object's
-  // `created-by-sub` S3 metadata on download. Only persisted when present so
-  // legacy journals and author-less uploads stay byte-identical.
-  if (createdBySub !== undefined && createdBySub !== "") {
-    entry.createdBySub = createdBySub;
-  }
-  if (kind !== undefined) {
-    entry.kind = kind;
-  }
-  journal.files[relativePath] = entry;
-  journal.lastSync = new Date().toISOString();
-}
-
-/**
- * S3 returns ETags wrapped in literal double-quotes (e.g. `"d41d8cd9..."`).
- * Strip them so equality comparisons across HEAD / GET / PUT responses are
- * stable regardless of which AWS SDK call surfaced the value.
- */
-export function normalizeEtag(etag: string): string {
-  if (!etag) return "";
-  return etag.replace(/^"|"$/g, "");
-}
-
-export function getEntry(
-  journal: SyncJournal,
-  relativePath: string,
-): JournalEntry | undefined {
-  return journal.files[relativePath];
-}
-
-export function removeEntry(
-  journal: SyncJournal,
-  relativePath: string,
-): void {
-  delete journal.files[relativePath];
-}
-
-// ─── Journal v2 (US-005): pulls, tombstones, GC ─────────────────────────────
-
-/** Crockford base32 alphabet (ULID-compatible). */
-const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
-
-/**
- * Generate a ULID-shaped 26-char identifier without adding a runtime dep.
- * Format: 10-char base32 of the current millisecond timestamp + 16-char
- * base32 of random bytes. Lexically sortable, time-prefixed — same property
- * that makes ULIDs useful for `pulls[]` ordering.
- *
- * We don't need full ULID spec compliance (monotonic counter, randomness
- * spec) — just sortable + collision-resistant enough that two pulls
- * issued in the same millisecond by different processes don't clash.
- * 80 bits of randomness is plenty.
- */
-export function generatePullId(now: number = Date.now()): string {
-  let time = now;
-  const timeChars: string[] = [];
-  for (let i = 0; i < 10; i++) {
-    timeChars.unshift(CROCKFORD[time % 32]!);
-    time = Math.floor(time / 32);
-  }
-  const randBytes = crypto.randomBytes(10); // 80 bits
-  const randChars: string[] = [];
-  // Encode 10 random bytes (80 bits) into 16 base32 chars.
-  let buf = 0;
-  let bits = 0;
-  for (let i = 0; i < randBytes.length; i++) {
-    buf = (buf << 8) | randBytes[i]!;
-    bits += 8;
-    while (bits >= 5) {
-      bits -= 5;
-      randChars.push(CROCKFORD[(buf >> bits) & 0x1f]!);
-    }
-  }
-  if (bits > 0) {
-    randChars.push(CROCKFORD[(buf << (5 - bits)) & 0x1f]!);
-  }
-  return timeChars.join("") + randChars.slice(0, 16).join("");
-}
-
-/**
- * Find the most-recent `PullRecord` for a company in the journal. Returns
- * `undefined` when no record exists — scope-shrink callers treat that as
- * "no prior scope; nothing to shrink".
- *
- * Order by `completedAt` descending — `pullId` is lexically sortable but
- * `completedAt` is what semantically represents "most recent successful
- * pull state at last close".
- */
-export function lastPullRecord(
-  journal: SyncJournal,
-  companyUid: string,
-): PullRecord | undefined {
-  if (!journal.pulls || journal.pulls.length === 0) return undefined;
-  let best: PullRecord | undefined;
-  for (const p of journal.pulls) {
-    if (p.companyUid !== companyUid) continue;
-    if (!best || p.completedAt > best.completedAt) best = p;
-  }
-  return best;
-}
-
-function trimPullRecords(journal: SyncJournal): void {
-  const pulls = journal.pulls;
-  if (!pulls || pulls.length === 0) return;
-
-  const byCompany = new Map<string, Array<{ record: PullRecord; index: number }>>();
-  pulls.forEach((record, index) => {
-    const entries = byCompany.get(record.companyUid);
-    if (entries) entries.push({ record, index });
-    else byCompany.set(record.companyUid, [{ record, index }]);
-  });
-
-  const keep = new Set<number>();
-  for (const entries of byCompany.values()) {
-    entries
-      .sort((a, b) => {
-        const byCompletedAt = b.record.completedAt.localeCompare(
-          a.record.completedAt,
-        );
-        return byCompletedAt === 0 ? b.index - a.index : byCompletedAt;
-      })
-      .slice(0, MAX_PULLS_PER_COMPANY)
-      .forEach((entry) => keep.add(entry.index));
-  }
-
-  journal.pulls = pulls.filter((_, index) => keep.has(index));
-}
-
-/** Append a `PullRecord` (mutates `journal.pulls`) and cap retained history. */
-export function appendPullRecord(
-  journal: SyncJournal,
-  record: PullRecord,
-): void {
-  migrateToV2(journal);
-  journal.pulls!.push(record);
-  trimPullRecords(journal);
-}
-
-/**
- * Write a journal tombstone entry for `relativePath`. Used by the scope-
- * shrink algorithm (US-005) and by `hq sync narrow --apply` (US-007).
- *
- * Tombstones intentionally keep the old `hash` / `size` / `syncedAt` /
- * `direction` so a recovery flow could see what was there before pruning.
- * They are GC'd after `TOMBSTONE_TTL_MS` via `gcTombstones`.
- */
-export function tombstoneEntry(
-  journal: SyncJournal,
-  relativePath: string,
-  reason: "scope_shrink" | "narrow_apply" | "manual" | "local-delete",
-  now: string = new Date().toISOString(),
-): void {
-  const entry = journal.files[relativePath];
-  if (!entry) return;
-  entry.removedAt = now;
-  entry.removedReason = reason;
-}
-
-/**
- * Mark a journal entry for a user-authorized local delete. Callers must
- * capture the local hash and kind before removing the object; an absent path
- * alone is never deletion intent.
- */
-export function markLocalDeleteIntent(
-  journal: SyncJournal,
-  relativePath: string,
-  localHash: string,
-  localKind: "file" | "symlink",
-  expectedRemoteEtag: string,
-): boolean {
-  const entry = journal.files[relativePath];
-  if (
-    !entry?.remoteEtag ||
-    entry.remoteEtag !== normalizeEtag(expectedRemoteEtag) ||
-    entry.hash !== localHash ||
-    entry.kind !== localKind
-  ) {
-    return false;
-  }
-  entry.localDeleteIntent = {
-    version: 1,
-    remoteEtag: entry.remoteEtag,
-    localHash,
-    localKind,
-  };
-  return true;
-}
-
-/** Invalidate a prior delete authorization after a watcher-observed recreate. */
-export function clearLocalDeleteIntent(
-  journal: SyncJournal,
-  relativePath: string,
-): boolean {
-  const entry = journal.files[relativePath];
-  if (!entry?.localDeleteIntent) return false;
-  delete entry.localDeleteIntent;
-  return true;
-}
-
-/** True if the entry is a tombstone (set by `tombstoneEntry`). */
-export function isTombstone(entry: JournalEntry | undefined): boolean {
-  return !!entry && typeof entry.removedAt === "string";
-}
-
-/**
- * Garbage-collect tombstones older than `TOMBSTONE_TTL_MS` from
- * `journal.files`. Returns the number removed. Cheap — single pass over
- * the files map, no I/O. Safe to call at the start AND end of every
- * `pullAll` per-company leg; both runs are idempotent.
- */
-export function gcTombstones(
-  journal: SyncJournal,
-  now: number = Date.now(),
-): number {
-  let removed = 0;
-  for (const [path, entry] of Object.entries(journal.files)) {
-    if (!entry.removedAt) continue;
-    const removedTime = Date.parse(entry.removedAt);
-    if (Number.isNaN(removedTime)) continue;
-    if (now - removedTime > TOMBSTONE_TTL_MS) {
-      delete journal.files[path];
-      removed++;
-    }
-  }
-  return removed;
-}