@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/src/scope-shrink.ts

@@ -1,481 +0,0 @@
-/**
- * Scope-shrink detection + classification + clean removal (US-005).
- *
- * Implements the "hybrid scope-change contract" decided in US-000 Task 3
- * (see companies/indigo/projects/hq-sync-browse-vs-sync/references.md):
- *
- *   - Compare the current pull's `prefixSet` against the last `PullRecord`'s
- *     `prefixSet` for the same company. Files in the journal covered by the
- *     previous scope but NOT covered by the new scope are **orphans**.
- *   - Classify each orphan **clean** (safe to silently delete) or **dirty**
- *     (locally modified — sacred, never silently delete).
- *   - The remote-pull caller drives:
- *       * default mode: abort the leg if any dirty orphan exists;
- *       * `--force-scope-shrink`: continue, leave dirty files on disk,
- *         tombstone their journal entries.
- *
- * The pure-detection layer here intentionally does NOT touch disk for the
- * tombstone write — that lives in `journal.ts`. It DOES touch disk for the
- * orphan classification (hash + stat) because cleanliness is a function of
- * the file's current on-disk state vs the journal.
- *
- * PUSH-ONLY PREFIXES ARE NEVER PRUNED HERE (US-006). Session transcripts under
- * `sessions/{personUid}/...` are push-only: pushed into the vault, then
- * subtracted from every pull scope (incl. `all`/owner) via
- * `resolvePullScope().excludePrefixes`. That exclude set is applied ONLY to the
- * download filter (`computePullPlan`) and is DELIBERATELY NOT passed into this
- * module's `currentPrefixSet`. So a session file that was authored locally rides
- * the `direction:"up"` skip below, and one materialized on demand (`hq files
- * get`) rides the pin union already folded into the caller's inclusion
- * `prefixSet` — either way it is never pulled AND never orphaned. Feeding the
- * exclude set into `currentPrefixSet` would prune exactly those files; callers
- * must not.
- */
-
-import * as fs from "fs";
-import * as path from "path";
-import type {
-  JournalEntry,
-  PullRecord,
-  SyncJournal,
-} from "./types.js";
-import { hashFile, tombstoneEntry } from "./journal.js";
-import { localPathForVaultKey } from "./local-path-codec.js";
-import {
-  isCoveredByAny,
-  type ScopePrefixInput,
-} from "./prefix-coalesce.js";
-
-export interface OrphanClassification {
-  /** Relative path (journal key). */
-  path: string;
-  /** Journal entry as of last sync. */
-  entry: JournalEntry;
-  /** True iff the local file is provably unchanged since last sync. */
-  clean: boolean;
-  /** Why we called it dirty — surfaced in the abort error for operators. */
-  dirtyReason?:
-    | "modified-after-sync"
-    | "hash-mismatch"
-    | "stat-error";
-}
-
-export interface ScopeShrinkPlan {
-  /** Set of files covered by `lastPrefixSet` but not by `currentPrefixSet`. */
-  orphans: OrphanClassification[];
-  /** Subset of `orphans` with `clean === true`. */
-  clean: OrphanClassification[];
-  /** Subset of `orphans` with `clean === false`. */
-  dirty: OrphanClassification[];
-  /** True iff at least one orphan was found. */
-  scopeChangeDetected: boolean;
-}
-
-export interface BuildScopeShrinkPlanInput {
-  journal: SyncJournal;
-  hqRoot: string;
-  /** Coalesced prefixes used by the LAST pull for this company. */
-  lastPrefixSet: readonly ScopePrefixInput[];
-  /** Coalesced prefixes the CURRENT pull will use. */
-  currentPrefixSet: readonly ScopePrefixInput[];
-  /**
-   * The caller's own Cognito `sub`. When set, a file the caller authored
-   * (`entry.createdBySub === callerSub`) is NEVER orphaned by a scope shrink —
-   * regardless of mode. This is the core of the authorship contract: sync mode
-   * governs whether you mirror *other people's* files; it must never disown
-   * your own work. Owners hold their whole vault by role-bypass, so without
-   * this guard a `shared`/`custom` scope would treat their own un-granted
-   * content as "someone else's file I happen to see" and prune it.
-   */
-  callerSub?: string;
-  /**
-   * When `true`, an orphan whose authorship is unknown (`createdBySub`
-   * undefined — a legacy entry predating author stamping, or an object
-   * uploaded without author metadata) is also retained rather than pruned.
-   * The automatic background pull sets this so a routine sync never makes a
-   * destructive guess about pre-stamp content; the explicit `hq sync narrow`
-   * ritual (which carries its own confirmation + dirty gate) leaves it off so
-   * a deliberately-confirmed narrow can still reclaim legacy files.
-   */
-  protectUnknownAuthors?: boolean;
-}
-
-/**
- * Build a scope-shrink plan: find orphans, classify each clean/dirty.
- * Pure given the journal + filesystem state — no network, no journal
- * mutation.
- *
- * **Tombstone-aware:** journal entries that already carry a `removedAt`
- * marker are skipped — they represent a prior scope-shrink prune and must
- * not be re-flagged as orphans on each subsequent pull (that's the whole
- * point of the tombstone retention window).
- *
- * **Direction-aware:** only `direction: "down"` entries (and pre-ETag
- * legacy entries without an explicit direction marker) participate in
- * shrink detection. Push-only files (`direction: "up"`) represent local
- * authorship — they aren't in scope-as-pulled, so a scope change doesn't
- * orphan them.
- */
-export function buildScopeShrinkPlan(
-  input: BuildScopeShrinkPlanInput,
-): ScopeShrinkPlan {
-  const { journal, hqRoot, lastPrefixSet, currentPrefixSet } = input;
-  const { callerSub, protectUnknownAuthors } = input;
-  const orphans: OrphanClassification[] = [];
-
-  for (const [relPath, entry] of Object.entries(journal.files)) {
-    if (entry.removedAt) continue; // tombstone — already pruned
-    if (entry.direction !== "down") continue;
-    if (!isCoveredByAny(relPath, lastPrefixSet)) continue;
-    if (isCoveredByAny(relPath, currentPrefixSet)) continue;
-    // Authorship guard: sync mode decides whether you mirror OTHER people's
-    // files — it must never disown your own. A file the caller authored is
-    // sacred and never orphaned, even out of the current prefix scope. When
-    // `protectUnknownAuthors` is set (the automatic pull path), a legacy
-    // entry with no recorded author is also retained — a routine background
-    // sync should never make a destructive guess about pre-stamp content.
-    if (callerSub && entry.createdBySub === callerSub) continue;
-    if (protectUnknownAuthors && entry.createdBySub === undefined) continue;
-    orphans.push(classifyOrphan(relPath, entry, hqRoot));
-  }
-
-  const clean = orphans.filter((o) => o.clean);
-  const dirty = orphans.filter((o) => !o.clean);
-  return {
-    orphans,
-    clean,
-    dirty,
-    scopeChangeDetected: orphans.length > 0,
-  };
-}
-
-/**
- * Classify a single orphan:
- *
- *   - **Clean** when:
- *       * the local file is missing (already removed by the user — harmless), OR
- *       * `sha256(localFile) === entry.hash` AND `stat.mtime ≤ entry.syncedAt`.
- *   - **Dirty** otherwise.
- *
- * Symlinks: we don't re-hash with the symlink-target convention here —
- * the safer default is to treat any symlink whose lstat exists but whose
- * target hash doesn't match `entry.hash` (via `hashFile` reading the
- * target) as dirty. In practice symlinks materialize through the same
- * code path as files; a stale-target symlink is correctly flagged dirty
- * and the operator-facing message points at the path either way.
- */
-function classifyOrphan(
-  relPath: string,
-  entry: JournalEntry,
-  hqRoot: string,
-): OrphanClassification {
-  const absPath = localPathForVaultKey(hqRoot, relPath);
-  let stat: fs.Stats;
-  try {
-    stat = fs.lstatSync(absPath);
-  } catch (err) {
-    const code = (err as NodeJS.ErrnoException).code;
-    if (code === "ENOENT") {
-      return { path: relPath, entry, clean: true };
-    }
-    return {
-      path: relPath,
-      entry,
-      clean: false,
-      dirtyReason: "stat-error",
-    };
-  }
-
-  // mtime guard: a local edit moves mtime past syncedAt. We use ≤ because
-  // a download stamps syncedAt at the close of the write; mtime is set by
-  // the OS before that, so an unmodified pulled file has mtime ≤ syncedAt.
-  const mtimeMs = stat.mtimeMs;
-  const syncedAtMs = Date.parse(entry.syncedAt);
-  if (!Number.isNaN(syncedAtMs) && mtimeMs > syncedAtMs + 1000) {
-    // 1s grace for filesystem clock jitter.
-    return {
-      path: relPath,
-      entry,
-      clean: false,
-      dirtyReason: "modified-after-sync",
-    };
-  }
-
-  // Hash check — final word. If the content matches the journaled hash,
-  // the file is provably what the last pull left there.
-  let actualHash: string;
-  try {
-    actualHash = hashFile(absPath);
-  } catch {
-    return {
-      path: relPath,
-      entry,
-      clean: false,
-      dirtyReason: "stat-error",
-    };
-  }
-  if (actualHash !== entry.hash) {
-    return {
-      path: relPath,
-      entry,
-      clean: false,
-      dirtyReason: "hash-mismatch",
-    };
-  }
-  return { path: relPath, entry, clean: true };
-}
-
-/**
- * Where a scope-shrink error is going to be rendered, so the structured error
- * can carry advice that is ACTUALLY FOLLOWABLE from that entry point.
- *
- *   - `"cli"`    — a human at a terminal running `hq sync pull|now`. They can
- *                  re-run with `--force-scope-shrink` or run the guided
- *                  `hq sync narrow --apply` ritual.
- *   - `"runner"` — the menubar's `hq-sync-runner`. It accepts NO such flag
- *                  (DEV-1768 fix #2: the old "pass --force-scope-shrink" advice
- *                  was impossible to follow from here), so the only followable
- *                  action is to open a terminal and run `hq sync narrow --apply`.
- *                  In practice the runner pulls with `scopeShrinkPolicy:
- *                  "auto-recover"` and never throws this — but the context keeps
- *                  the message honest if it ever surfaces.
- *   - `"engine"` — unknown/library caller; generic advice.
- */
-export type ScopeShrinkAdviceContext = "cli" | "runner" | "engine";
-
-/** Followable next-step advice for a blocked scope shrink, per entry point. */
-function scopeShrinkAdvice(ctx: ScopeShrinkAdviceContext): string {
-  switch (ctx) {
-    case "cli":
-      return (
-        "Re-run with `--force-scope-shrink` to disown them now (dirty files " +
-        "are KEPT on disk, only un-tracked from sync), or run " +
-        "`hq sync narrow --apply` to migrate with a confirmation prompt."
-      );
-    case "runner":
-      return (
-        "The menubar sync cannot take this flag — open a terminal and run " +
-        "`hq sync narrow --apply` to migrate this membership (you confirm the " +
-        "file list), or `hq sync now --force-scope-shrink` once to proceed " +
-        "(dirty files are KEPT on disk, only un-tracked)."
-      );
-    default:
-      return (
-        "Run `hq sync narrow --apply` to migrate with confirmation, or pass " +
-        "`forceScopeShrink` (dirty files are kept on disk, only un-tracked)."
-      );
-  }
-}
-
-/**
- * Structured error thrown when the engine refuses to proceed because a scope
- * shrink would orphan dirty files. The CLI catches this and renders the
- * operator-facing message; the engine never prints directly.
- *
- * `adviceContext` makes the message FOLLOWABLE from each entry point — the old
- * fixed "pass --force-scope-shrink" line was impossible to act on from the
- * menubar runner, which rejects that flag (DEV-1768 fix #2).
- */
-export class ScopeShrinkBlockedError extends Error {
-  readonly code = "SCOPE_SHRINK_BLOCKED";
-  constructor(
-    public readonly companyUid: string,
-    public readonly fromMode: PullRecord["syncMode"] | "unknown",
-    public readonly toMode: PullRecord["syncMode"],
-    public readonly dirty: OrphanClassification[],
-    public readonly clean: OrphanClassification[],
-    public readonly adviceContext: ScopeShrinkAdviceContext = "engine",
-  ) {
-    super(
-      `Sync scope shrank for ${companyUid} (${fromMode} → ${toMode}); ` +
-        `${dirty.length} locally-modified file(s) outside the new scope ` +
-        `would be un-tracked from sync. ${scopeShrinkAdvice(adviceContext)}`,
-    );
-    this.name = "ScopeShrinkBlockedError";
-  }
-}
-
-/**
- * Structured error thrown when an AUTOMATIC scope shrink would prune more
- * CLEAN local files than the configured safety cap in a single pull. This is
- * the bulk-delete guard: a routine background sync should never silently
- * delete a large local tree — whether from a deliberate-but-abrupt first
- * narrow, a server bug returning an unexpectedly small grant set, or a
- * mis-resolved scope. The operator runs the explicit `hq sync narrow` ritual
- * (which has its own confirmation + dirty gate) or passes `--force-scope-shrink`
- * to proceed. The engine never deletes anything when it throws this.
- */
-export class ScopeShrinkLargePruneError extends Error {
-  readonly code = "SCOPE_SHRINK_LARGE_PRUNE";
-  constructor(
-    public readonly companyUid: string,
-    public readonly toMode: PullRecord["syncMode"],
-    public readonly cleanCount: number,
-    public readonly cap: number,
-    public readonly adviceContext: ScopeShrinkAdviceContext = "engine",
-  ) {
-    super(
-      `Refusing to auto-move ${cleanCount} local file(s) for ${companyUid} ` +
-        `(${toMode} scope) in one sync — exceeds the safety cap of ${cap}. ` +
-        `Raise HQ_SYNC_MAX_AUTO_PRUNE, or ${scopeShrinkAdvice(adviceContext)}`,
-    );
-    this.name = "ScopeShrinkLargePruneError";
-  }
-}
-
-/**
- * Disposition for CLEAN orphans (files provably unchanged since the last sync)
- * that fall outside the new scope:
- *
- *   - `"delete"`     — `unlink` the local file. The legacy behavior; reserved
- *                      for the explicit `hq sync narrow --apply` ritual, which
- *                      already confirms the file list with the operator.
- *   - `"quarantine"` — MOVE the file into `quarantineRoot` instead of deleting
- *                      it, so it stays recoverable. The conservative default
- *                      for the automatic pull path: a background sync must
- *                      never silently PURGE local files (DEV-1768 fix #3).
- */
-export type CleanOrphanDisposition = "delete" | "quarantine";
-
-export interface ApplyScopeShrinkInput {
-  journal: SyncJournal;
-  plan: ScopeShrinkPlan;
-  hqRoot: string;
-  /**
-   * When `true`, dirty files are LEFT ON DISK and their journal entries are
-   * tombstoned anyway. When `false` (default), the caller should have
-   * already aborted on dirty orphans — this function still tombstones any
-   * dirty entries handed to it, on the assumption the caller knows what
-   * it's doing.
-   */
-  forceScopeShrink: boolean;
-  reason?: "scope_shrink" | "narrow_apply" | "manual";
-  /**
-   * How to dispose of CLEAN orphans. Defaults to `"delete"` so existing
-   * callers (and the confirmed `narrow --apply` ritual) keep their behavior;
-   * the automatic pull path passes `"quarantine"`.
-   */
-  cleanDisposition?: CleanOrphanDisposition;
-  /**
-   * Absolute directory clean orphans are relocated into when
-   * `cleanDisposition === "quarantine"`. Each orphan moves to
-   * `<quarantineRoot>/<orphan.path>` (parent dirs created). REQUIRED when
-   * quarantining; if absent, the function falls back to `"delete"` so it can
-   * never get stuck unable to make progress.
-   */
-  quarantineRoot?: string;
-}
-
-export interface ApplyScopeShrinkResult {
-  /** Clean orphans `unlink`ed from disk (only when disposition is `delete`). */
-  cleanRemoved: number;
-  /** Clean orphans MOVED to quarantine (only when disposition is `quarantine`). */
-  cleanQuarantined: number;
-  /** Dirty orphans tombstoned in the journal (file LEFT on disk). */
-  dirtyTombstoned: number;
-  /** Named paths deleted — for explicit, non-silent operator reporting. */
-  removedPaths: string[];
-  /** Named paths moved to quarantine — for explicit reporting. */
-  quarantinedPaths: string[];
-  /** Named dirty paths un-tracked but KEPT on disk — for explicit reporting. */
-  dirtyKeptPaths: string[];
-  /** Absolute quarantine directory used (when anything was quarantined). */
-  quarantineRoot?: string;
-}
-
-/**
- * Move a clean orphan from the working tree into the quarantine tree,
- * preserving its relative path. Same-device `rename` first (cheap, atomic);
- * cross-device falls back to copy+unlink. A missing source is a no-op (the
- * user already removed it — harmless). Returns true iff the file was relocated
- * (or was already absent), false only on an unexpected error the caller should
- * surface.
- */
-function quarantineOrphan(
-  srcAbs: string,
-  destAbs: string,
-): void {
-  fs.mkdirSync(path.dirname(destAbs), { recursive: true });
-  try {
-    fs.renameSync(srcAbs, destAbs);
-  } catch (err) {
-    const code = (err as NodeJS.ErrnoException).code;
-    if (code === "ENOENT") return; // source already gone — nothing to move
-    if (code === "EXDEV") {
-      // Cross-device move: copy then unlink. cpSync handles files + symlinks.
-      fs.cpSync(srcAbs, destAbs, { recursive: true, verbatimSymlinks: true });
-      fs.rmSync(srcAbs, { recursive: true, force: true });
-      return;
-    }
-    throw err;
-  }
-}
-
-/**
- * Apply a scope-shrink plan: dispose of clean orphans (delete OR quarantine)
- * + tombstone their journal entries. With `forceScopeShrink: true`, dirty
- * orphans are PRESERVED on disk and only their journal entries are tombstoned
- * (so they stop being re-flagged on every pull — the idempotent recovery seam).
- *
- * Returns counts AND named paths so the caller can report exactly what moved /
- * was un-tracked — never a silent purge (DEV-1768 fix #3).
- */
-export function applyScopeShrink(
-  input: ApplyScopeShrinkInput,
-): ApplyScopeShrinkResult {
-  const { journal, plan, hqRoot, forceScopeShrink } = input;
-  const reason = input.reason ?? "scope_shrink";
-  // Quarantine only when explicitly asked AND a destination is provided;
-  // otherwise fall back to delete so we always make progress.
-  const quarantining =
-    input.cleanDisposition === "quarantine" && !!input.quarantineRoot;
-  let cleanRemoved = 0;
-  let cleanQuarantined = 0;
-  let dirtyTombstoned = 0;
-  const removedPaths: string[] = [];
-  const quarantinedPaths: string[] = [];
-  const dirtyKeptPaths: string[] = [];
-
-  for (const orphan of plan.clean) {
-    const absPath = localPathForVaultKey(hqRoot, orphan.path);
-    if (quarantining) {
-      const destAbs = localPathForVaultKey(input.quarantineRoot!, orphan.path);
-      quarantineOrphan(absPath, destAbs);
-      tombstoneEntry(journal, orphan.path, reason);
-      cleanQuarantined++;
-      quarantinedPaths.push(orphan.path);
-    } else {
-      try {
-        fs.unlinkSync(absPath);
-      } catch (err) {
-        const code = (err as NodeJS.ErrnoException).code;
-        if (code !== "ENOENT") throw err; // missing-on-disk is fine; anything else escalates
-      }
-      tombstoneEntry(journal, orphan.path, reason);
-      cleanRemoved++;
-      removedPaths.push(orphan.path);
-    }
-  }
-
-  if (forceScopeShrink) {
-    for (const orphan of plan.dirty) {
-      // Do NOT delete the file — keep dirty content on disk, prune only the
-      // journal entry so it stops being re-flagged as an orphan on each pull.
-      tombstoneEntry(journal, orphan.path, reason);
-      dirtyTombstoned++;
-      dirtyKeptPaths.push(orphan.path);
-    }
-  }
-
-  return {
-    cleanRemoved,
-    cleanQuarantined,
-    dirtyTombstoned,
-    removedPaths,
-    quarantinedPaths,
-    dirtyKeptPaths,
-    ...(quarantining && quarantinedPaths.length > 0
-      ? { quarantineRoot: input.quarantineRoot }
-      : {}),
-  };
-}