@bevel-software/platform-core-backend 0.15.1 → 0.19.0

package/src/shared/canonical-file-identity.ts

@@ -0,0 +1,92 @@
+/**
+ * ONE canonical identity for a workspace file, plus the refusals the file
+ * verbs already answer with, as a single throwing call.
+ *
+ * `canonicalRelativePath` (in `@bevel-software/platform-shared`) collapses the
+ * spellings of one file: `x/a.md`, `./x/a.md` and `x//a.md` are the same file
+ * and all three become `x/a.md`. What it deliberately does NOT do is launder:
+ * a path it cannot canonicalise comes back UNCHANGED, so every gate downstream
+ * still sees what the caller actually sent. That leaves the caller holding an
+ * un-refused path, which is fine for `PUT /file` (the workspace service's own
+ * guards run right after) and wrong for anything that coordinates on the path
+ * WITHOUT ever touching disk. The file-lock service is exactly that: nothing
+ * below it resolves the path against a workspace directory, so a spelling that
+ * escapes or launders would quietly become a lock row of its own.
+ *
+ * This helper is therefore the canonicaliser AND the refusal, in the order the
+ * file verbs run them, so both surfaces answer the same thing for the same
+ * input:
+ *
+ *   1. `validateRelativePath` refuses `.` and `..` segments, backslashes and
+ *      an empty path. Repeated slashes it does NOT refuse: `x//a.md` is a
+ *      spelling of `x/a.md`, and the canonicaliser has already collapsed it by
+ *      the time the validator runs. `WorkspaceService.withPathTurn` runs the
+ *      same check first (via the shared `assertValidRelativePath`) and its
+ *      `Invalid path: ...` message is what `workspace.routes.sendError` turns
+ *      into a 400. Same message here, raised as a 400 `WorkflowValidationError`.
+ *   2. Containment. `withPathTurn` then resolves the path against the
+ *      workspace directory and refuses anything landing outside it, which
+ *      `sendError` turns into a 403. Step 1 has already rejected every `..`,
+ *      so the only spelling that can still escape is an absolute one, and
+ *      that is the whole of what this step refuses. It is refused AS absolute
+ *      rather than by resolving it against a stand-in root: `/workspace/a.md`
+ *      would resolve to inside any stand-in named `/workspace` and read as
+ *      contained, while the real workspace directory is `<workspacesRoot>/<id>`
+ *      and never literally `/workspace`, so the file verbs resolve that same
+ *      path outside their workspace and answer 403. With `..` gone and
+ *      absolute refused, every remaining spelling is relative and cannot
+ *      leave whatever directory it is resolved against — there is nothing
+ *      left for a resolve-and-compare to decide, so there is none here.
+ *
+ * Case is left alone, for the reason `canonicalRelativePath` documents: the
+ * deployment target is Linux, where `Foo.md` and `foo.md` are two files.
+ *
+ * What this deliberately does NOT answer is whether the path reaches its file
+ * through a symbolic link. That question is about what is on disk, not about
+ * how the path is spelled, and it is answered where the disk is:
+ * `WorkspaceService.assertNotThroughLink`, on the verbs that read and write
+ * bytes. A lock row is a coordination key and the lock service holds no
+ * workspace directory to resolve against, so a link can only change which
+ * bytes a WRITE touches, and that write is refused by the verb that performs
+ * it while the lock is merely held.
+ */
+
+import { canonicalRelativePath, validateRelativePath } from '@bevel-software/platform-shared';
+import { PathTraversalError, WorkflowValidationError } from './domain-errors.js';
+
+/**
+ * The canonical spelling of `targetPath`, or a throw carrying the status the
+ * file verbs answer with for that same input.
+ *
+ * @throws {WorkflowValidationError} 400, when the path is not a usable
+ *   workspace-relative path (not a string at all, a `.` or `..` segment, a
+ *   backslash, empty).
+ * @throws {PathTraversalError} 403, when the path resolves outside the
+ *   workspace (an absolute path).
+ */
+export function canonicalFileIdentity(targetPath: string): string {
+  // A JSON body can hold anything and the lock routes' own guard only tests
+  // falsiness, so a truthy non-string (`{"path": 123}`) arrives here. The
+  // canonicaliser calls `.startsWith` on it and throws a bare `TypeError`,
+  // which `toHttpError` can only read as a 500 — for what is a client
+  // mistake. `PUT /file` answers 400 for that same body (its `requestPath`
+  // type-guards before canonicalising), and this surface answers what that one
+  // answers. The message is the validator's own for a non-string, so the two
+  // 400s read identically as well.
+  if (typeof targetPath !== 'string') {
+    throw new WorkflowValidationError('Invalid path: Path is required');
+  }
+  const canonical = canonicalRelativePath(targetPath);
+  const reason = validateRelativePath(canonical);
+  if (reason) throw new WorkflowValidationError(`Invalid path: ${reason}`);
+  // `validateRelativePath` ACCEPTS `/workspace/a.md` (its leading empty
+  // segment is filtered out, leaving two ordinary segments), so absolute is
+  // refused here, on its own terms: a workspace-relative path is never
+  // absolute, and the file verbs treat one as the escape it is. This is the
+  // only containment refusal there is — see step 2 in the header for why a
+  // resolve-and-compare against a stand-in root would decide nothing more.
+  if (canonical.startsWith('/')) {
+    throw new PathTraversalError();
+  }
+  return canonical;
+}

package/src/shared/domain-errors.ts

@@ -18,6 +18,7 @@
  */
 
 import type { ValidationReport } from '@bevel-software/platform-shared';
+import { sanitizedPath } from './printable.js';
 
 export class WorkflowDomainError extends Error {
   readonly status: number;
@@ -166,11 +167,36 @@ export class PullRebaseConflictError extends WorkflowDomainError {
   }
 }
 
+/**
+ * The platform has never heard of this branch: nothing it has cloned, and
+ * nothing any listing of origin's branches has mentioned. Distinct from
+ * `RemoteBranchGoneError`, which is the SAME git failure about a branch the
+ * platform did know — and answering that for a name nobody ever pushed told
+ * the reader their typo "no longer exists on the remote", which implies it
+ * once did. 404, and the message names the branch and nothing else: no git
+ * output, no remote URL.
+ */
+export class BranchNotFoundError extends WorkflowDomainError {
+  readonly kind = 'branch-not-found' as const;
+  constructor(readonly branch: string) {
+    super(`There is no branch named ${branch}.`, 404, {
+      kind: 'branch-not-found',
+      branch,
+    });
+    this.name = 'BranchNotFoundError';
+  }
+}
+
 /**
  * The clone's branch no longer exists on origin: the fetch that refreshes
  * `refs/remotes/origin/<branch>` found no such ref. Distinct from an
  * unreachable remote — the host answered, and the answer was "gone" — so a
  * caller can treat the clone as stale rather than the sync as failed. 410.
+ *
+ * Only for a branch the platform KNEW: a clone of it, or a listing that named
+ * it. For a name it has never heard of, the same git failure is a
+ * `BranchNotFoundError` — see `WorkspaceService.hasHeardOfBranch`. A sync
+ * always has the clone in hand, so it is always this one.
  */
 export class RemoteBranchGoneError extends WorkflowDomainError {
   readonly kind = 'remote-branch-gone' as const;
@@ -195,6 +221,44 @@ export function isMissingRemoteBranchFailure(message: string): boolean {
   return /Remote branch .* not found in upstream|couldn't find remote ref/i.test(message);
 }
 
+/**
+ * The caller named a path that resolves outside the workspace it was asked
+ * for. In practice that means an absolute path: a `..` climb is refused one
+ * step earlier, as an invalid path, by the same validator the file verbs run
+ * first.
+ *
+ * 403 carrying the exact message the file verbs answer, because
+ * `WorkspaceService.assertWithinWorkspace` throws a bare `Error` with this
+ * text and `workspace.routes.sendError` maps that text to 403. The lock
+ * service raises this instead of a bare `Error`, because `toHttpError` on the
+ * workflow routes reads the status off the class and would otherwise call it
+ * a 500. Both surfaces then answer identically for the same input. See
+ * `canonicalFileIdentity`.
+ */
+export class PathTraversalError extends WorkflowDomainError {
+  readonly kind = 'path-traversal' as const;
+  constructor() {
+    super('Path traversal detected', 403, { kind: 'path-traversal' });
+    this.name = 'PathTraversalError';
+  }
+}
+
+/**
+ * The caller named a path inside the repository's internal git folder: any
+ * `.git` segment, in any case, however it was spelled or reached (see
+ * `shared/git-internals.ts`). One message for every such path, whether or not
+ * anything is there, so the refusal is not an existence oracle.
+ */
+export const GIT_INTERNALS_MESSAGE = "That path is inside the repository's internal git data and is not available.";
+
+export class GitInternalsError extends WorkflowDomainError {
+  readonly kind = 'git-internals' as const;
+  constructor() {
+    super(GIT_INTERNALS_MESSAGE, 403, { kind: 'git-internals' });
+    this.name = 'GitInternalsError';
+  }
+}
+
 /**
  * Generic 400 for workflow-input validation (malformed branch names, missing
  * fields, etc.). Carries an optional payload so callers can attach typed
@@ -208,6 +272,69 @@ export class WorkflowValidationError extends WorkflowDomainError {
   }
 }
 
+/**
+ * The next step a missing path always offers, in one sentence.
+ *
+ * Lives HERE, the layer with no module imports, because both surfaces that
+ * answer a missing path need it and they sit on opposite sides of a module
+ * boundary: this class (raised by services, rendered by the HTTP routes) and
+ * `modules/workspace/not-found.ts` (the file tools), which re-exports the
+ * constant under its own name. One sentence, written once, so the two cannot
+ * drift apart.
+ */
+export const NOT_FOUND_NEXT_STEP = 'Check the path with list_files.';
+
+/**
+ * Nothing is at the path the caller named.
+ *
+ * Raised by a SERVICE that probed the path itself, where the file tools' own
+ * `not-found` helper (modules/workspace/not-found.ts) cannot reach: the zip
+ * reader, for instance, answers "ADM-ZIP: Invalid filename" for a missing
+ * archive, which is not a filesystem error at all and would otherwise be
+ * dressed up as an unreadable archive. The helper recognises this class and
+ * the raw `ENOENT`/`ENOTDIR` shapes alike, so both end as the one 404.
+ *
+ * 404 with a `not_found` kind and the requested path, which is also what the
+ * HTTP routes answer — a path that is not there gets one answer whichever
+ * surface asked. The MESSAGE AND THE PAYLOAD ARE BUILT HERE, not by whoever
+ * catches it, because not every surface catches it: the tools pass through
+ * `orDeclaredNotFound`, which re-renders the same three parts, but
+ * `POST /workspace/:id/unzip` sends this error straight to `domainErrorBody`.
+ * Sanitizing the path and appending the next step in the constructor is what
+ * makes those two answers the same answer.
+ */
+export class PathNotFoundError extends WorkflowDomainError {
+  readonly kind = 'not_found' as const;
+  /** The requested path, sanitized — never the path on disk. */
+  readonly path: string;
+  constructor(path: string) {
+    const safe = sanitizedPath(path);
+    super(
+      `There is no file or directory at "${safe}" in this workspace. ${NOT_FOUND_NEXT_STEP}`,
+      404,
+      { kind: 'not_found', path: safe },
+    );
+    this.name = 'PathNotFoundError';
+    this.path = safe;
+  }
+}
+
+/**
+ * An archive the caller uploaded that the zip reader cannot open. 422, not
+ * 400: the request is well-formed and the path is fine — the BYTES are not a
+ * readable zip, which is the caller's to fix but not their spelling's.
+ *
+ * A type, because the route used to recognise this by the `Could not read zip
+ * file` prefix its message happens to start with, and a reworded message
+ * would silently have turned it into a 500.
+ */
+export class UnreadableArchiveError extends WorkflowDomainError {
+  constructor(reason: string) {
+    super(`Could not read zip file: ${reason}`, 422, { kind: 'unreadable-archive' });
+    this.name = 'UnreadableArchiveError';
+  }
+}
+
 /**
  * The draft branch doesn't share history with the target branch, so GitHub
  * would reject the change request with `no history in common`. Surfaced as
@@ -304,6 +431,28 @@ export class ChangeRequestConflictsError extends WorkflowDomainError {
   }
 }
 
+/**
+ * A direct branch merge was asked to do what an open change request is
+ * waiting for a person to do: merge `sourceBranch` into `targetBranch`.
+ * Carries the request's number so the caller can point the person at it.
+ */
+export class OpenChangeRequestBlocksMergeError extends WorkflowDomainError {
+  readonly kind = 'open-change-request-blocks-merge' as const;
+  constructor(
+    readonly sourceBranch: string,
+    readonly targetBranch: string,
+    readonly number: number,
+  ) {
+    super(
+      `Change request #${number} proposes merging "${sourceBranch}" into "${targetBranch}" and is still open. ` +
+        `A change request is merged by a person: ask the user to review #${number} in the app.`,
+      409,
+      { kind: 'open-change-request-blocks-merge', sourceBranch, targetBranch, number },
+    );
+    this.name = 'OpenChangeRequestBlocksMergeError';
+  }
+}
+
 /**
  * Caller tried to open a change request for a `(source, target)` pair that
  * already has one open. Spec rule: A→B blocks A→B (B→A is allowed). Carries

package/src/shared/email-identity.ts

@@ -0,0 +1,38 @@
+import { createHash } from 'node:crypto';
+
+/**
+ * THE canonical spelling of an email address: trimmed, lowercased.
+ *
+ * Everything that compares two addresses, keys a row by one, or hashes one
+ * has to agree on this — a grant written `Mia@x.io` and a caller arriving as
+ * `mia@x.io ` are the same person, and any reader that decides otherwise
+ * denies access the knowledge base plainly gives. The rule was written out
+ * inline in a dozen places (`user.email.trim().toLowerCase()`) and named
+ * once in the access grammar; this is the one place it lives now, and the
+ * grammar's `canonicalEmail` is this function.
+ *
+ * Deliberately NOT full RFC normalization: no dot-folding, no plus-tag
+ * stripping, no IDN mapping. Those differ per provider, and a rule that
+ * guessed would silently merge two identities the operator's directory
+ * treats as distinct.
+ */
+export function canonicalEmail(email: string): string {
+  return email.trim().toLowerCase();
+}
+
+/**
+ * Canonical user-identity hash: SHA-256 over the {@link canonicalEmail} form,
+ * returned as hex. Used wherever Bevel needs a stable email-derived identifier
+ * without storing the raw email — PR author-id markers, self-approval
+ * detection, the reverse lookup behind `findEmailByHash`.
+ *
+ * All callers MUST use this single function, and it must normalise exactly as
+ * `canonicalEmail` does: a drift between the two would silently de-attribute
+ * every PR the bot opens, because the hash embedded in the PR body would no
+ * longer match the hash computed at lookup time. That is not hypothetical —
+ * the access resolver carried its own copy of this expression, used by the
+ * very lookup that has to agree with it.
+ */
+export function hashEmail(email: string): string {
+  return createHash('sha256').update(canonicalEmail(email)).digest('hex');
+}

package/src/shared/fs.contract.ts

@@ -0,0 +1,225 @@
+/**
+ * The contracts for READING the disk without locks: walking a tree, honouring
+ * `.bevelignore`, and probing a path. Nothing here touches the disk — the one
+ * implementation is `NodeFs` in `modules/kb-fs`, wired once by the
+ * composition root and injected into every module that reads the disk, so no
+ * module carries a `readdir` loop, an `exists()` or an errno check of its own.
+ *
+ * THE directory walk ({@link ITreeWalker.walk}). Every reader of a tree — the
+ * access resolver looking for rules, plugin discovery looking for manifests,
+ * the explorer building its tree, the diff baseline mirroring a checkout, a
+ * template seeding a repository — used to carry a recursive `readdir` loop of
+ * its own, each with its own skip list, its own idea of what an unreadable
+ * folder means and its own visiting order. Two loops that disagree on one of
+ * those are two answers to "what is in the tree", and every such disagreement
+ * was a bug. So there is one loop, and what differs between readers is SAID
+ * in its {@link TreeWalkOptions}, never re-implemented:
+ *
+ *   - WHAT IS SKIPPED: `skip` — names that are never reported nor entered;
+ *     `ignore` — whether the `.bevelignore` files on the way down are
+ *     honoured; `leaf` — a folder that is reported and then left alone (a
+ *     skill folder, a plugin).
+ *   - IN WHAT ORDER: each folder's entries in `comparePathComponents` order
+ *     (see `shared/path-order.ts`), always, so "first by path" means the same
+ *     thing to every reader.
+ *   - WHAT A HOLE IS: a folder that exists but could not be listed is either
+ *     reported — as an event and in the result — and walked around, or the
+ *     walk's own error (`unreadable: 'throw'`). Never silently skipped. A
+ *     folder that vanished between listing and visiting is not a hole, and a
+ *     missing root is an empty tree.
+ *   - WHAT AN ENTRY IS: a file or a folder. Anything else (a symlink, a
+ *     socket) is never entered and never a file — it is told to `onOther`,
+ *     so a reader that must say so (or delete it) can.
+ *
+ * Listeners see the same events in the same order; what each makes of them
+ * is its own business.
+ */
+
+/** The ignore file's own name — every reader that names it agrees on the spelling. */
+export const IGNORE_FILENAME = '.bevelignore';
+
+/**
+ * The knowledge-base walk's skip list: dot-entries (`.git`, a parked delete)
+ * and vendored dependencies are never seen — by {@link ITreeWalker.walkKb},
+ * and by any reader listing one folder of a checkout on its own.
+ */
+export function isSkippedEntry(name: string): boolean {
+  return name.startsWith('.') || name === 'node_modules';
+}
+
+/**
+ * THE definition of absence: whether a filesystem error means "there is no
+ * such path". ENOENT is nothing at the name; ENOTDIR is nothing that could be
+ * there, because a parent segment is a file (`notes.md/deeper`). Those two are
+ * the one failure a reader may treat as an ordinary answer.
+ *
+ * Everything else (permissions, I/O, a loop) is a failure to READ what is
+ * there, and a caller that folds it into absence turns an outage into a wrong
+ * answer: an unreadable `access.md` read as "no rules" grants what it would
+ * have denied, and an unreadable file read as "not there" lets a write
+ * destroy bytes nothing ever saw.
+ *
+ * A PURE predicate over a value, like {@link isSkippedEntry} — it touches no
+ * disk, so it is a function every reader imports rather than a method on
+ * {@link IFsProbe}. The probes below all apply it; a reader catching its own
+ * error calls it directly.
+ */
+export function isAbsence(err: unknown): boolean {
+  const code = (err as { code?: unknown } | null)?.code;
+  return code === 'ENOENT' || code === 'ENOTDIR';
+}
+
+/** What a probe says of an entry: what it is, and nothing about the disk that said so. */
+export interface EntryStat {
+  isFile(): boolean;
+  isDirectory(): boolean;
+  isSymbolicLink(): boolean;
+}
+
+/** A directory entry as the walk presents it: a name and what it is. */
+export interface WalkedEntry extends EntryStat {
+  name: string;
+}
+
+/**
+ * A stack of `.bevelignore` rule sets, layered like git: each file applies
+ * beneath the folder it lives in, deeper files extend — and can override,
+ * `!pattern` included — shallower ones. Immutable: extending returns a new
+ * stack.
+ */
+export interface IgnoreRules {
+  /**
+   * The rules in force inside `dir`: these plus `dir`'s own file. No file is
+   * no change. A file that is there but cannot be read is NOT — the rules
+   * are unknown — and that error is the caller's (the walk makes it a hole).
+   */
+  extendedWith(dir: string): Promise<IgnoreRules>;
+  /** Whether the entry at `absolutePath` is hidden. `isDirectory` lets `foo/`-style rules match folders only. */
+  isIgnored(absolutePath: string, isDirectory: boolean): boolean;
+}
+
+/** A folder the walk is in. */
+export interface WalkedDir {
+  /** Repo-relative, `''` for the root. */
+  rel: string;
+  abs: string;
+  /** Everything the folder holds — files and folders, skipped names removed, in walk order — BEFORE its ignore rules. */
+  listed: readonly WalkedEntry[];
+  /** The `.bevelignore` rules in force inside this folder; empty when the walk does not honour them. */
+  ignore: IgnoreRules;
+}
+
+export interface TreeWalkOptions {
+  /** Entries left out of every listing — never reported, never entered. Default: nothing. */
+  skip?: (entry: WalkedEntry) => boolean;
+  /**
+   * Honour the `.bevelignore` files on the way down: each folder's rules
+   * extend its parent's, and an entry a rule names is neither reported nor
+   * entered (a listener can still see it in `WalkedDir.listed`). `true`
+   * starts with no rules above the root; a stack starts with the rules in
+   * force there. OFF by default — the explorer honours the files, the access
+   * resolver must not — so every reader says which it is.
+   */
+  ignore?: boolean | IgnoreRules;
+  /** A folder whose listing satisfies this is reported, then left alone: nothing beneath it is visited. */
+  leaf?: (dir: WalkedDir, entries: readonly WalkedEntry[]) => boolean;
+  /** Checked before every listing and every entry: once true, the walk ends. For a reader that stops at its first find. */
+  until?: () => boolean;
+  /**
+   * What a folder that exists but cannot be listed is: a `'hole'` (default —
+   * told to `onHole`, named in the result, walked around) or the walk's error.
+   */
+  unreadable?: 'hole' | 'throw';
+}
+
+export interface WalkListener {
+  /** A folder was listed. `rel` is repo-relative (`''` for the root); `entries` are its children, skipped and ignored ones removed, in walk order. */
+  onDir?(rel: string, entries: readonly WalkedEntry[], dir: WalkedDir): void | Promise<void>;
+  /** A file was seen. `dir` is its folder (`''` for the root), `name` its basename. */
+  onFile?(dir: string, name: string): void | Promise<void>;
+  /** An entry that is neither a file nor a folder (a symlink, a socket) — never entered, never a file. */
+  onOther?(dir: string, entry: WalkedEntry): void | Promise<void>;
+  /** A folder that exists but could not be listed. */
+  onHole?(rel: string, err: unknown): void | Promise<void>;
+}
+
+export interface WalkResult {
+  /** Every folder that could not be listed, repo-relative (`''` for the root). */
+  holes: string[];
+}
+
+/** A strict listing's refusal: the directory (relative to the root, `''` for the root itself) it could not list. */
+export class WalkError extends Error {
+  constructor(
+    readonly relDir: string,
+    readonly cause: unknown,
+  ) {
+    super(`${relDir || '.'} could not be listed — ${cause instanceof Error ? cause.message : String(cause)}`);
+    this.name = 'WalkError';
+  }
+}
+
+export interface ITreeWalker {
+  /**
+   * Walk the tree at `root`, driving every listener from one traversal.
+   * A missing root is an empty tree. Listener errors propagate untouched.
+   */
+  walk(root: string, options: TreeWalkOptions, listeners: readonly WalkListener[]): Promise<WalkResult>;
+  /**
+   * The walk of a knowledge-base checkout: {@link walk} with the checkout's
+   * skip list — dot-entries (`.git`, a parked delete) and vendored
+   * dependencies are never seen. Nothing else is pruned by default; a reader
+   * that honours `.bevelignore`, has a leaf of its own, or must stop at a
+   * hole says so in `options`.
+   */
+  walkKb(root: string, listeners: readonly WalkListener[], options?: Omit<TreeWalkOptions, 'skip'>): Promise<WalkResult>;
+  /**
+   * The file listing catalog scanners want, on top of {@link walkKb}:
+   * relative (`/`-separated) paths of files under `root` whose basename
+   * matches, in walk order. A missing root yields `[]`; skipped entries are
+   * never entered. A directory that cannot be listed is SKIPPED by default —
+   * right for a catalog, which shows what it can. A caller that must see
+   * EVERYTHING or nothing passes `strict`, and the listing throws a
+   * {@link WalkError} naming the directory instead.
+   */
+  walkFiles(root: string, match: (basename: string) => boolean, opts?: { strict?: boolean }): Promise<string[]>;
+}
+
+/**
+ * Probing a single path. Every `OrNull`/`exists` below answers null/false for
+ * {@link isAbsence} and lets every other error out, so no reader has to
+ * decide what a failed probe meant.
+ */
+export interface IFsProbe {
+  /** Whether SOMETHING is at `p` — a link included, followed or not. */
+  exists(p: string): Promise<boolean>;
+  /** What is at `p`, links followed; null when nothing is there. */
+  statOrNull(p: string): Promise<EntryStat | null>;
+  /** What is at `p` itself, a link as a link; null when nothing is there. */
+  lstatOrNull(p: string): Promise<EntryStat | null>;
+  /** Whether the entry at `p` is itself a directory (a link to one is not). */
+  isDirectory(p: string): Promise<boolean>;
+  /**
+   * ONE folder's own entries — files, folders and the rest — in walk order,
+   * nothing skipped; null when there is no such folder. Any other failure to
+   * list it is the error: a listing with a hole is not a listing.
+   */
+  listDir(p: string): Promise<WalkedEntry[] | null>;
+  /** The JSON object in the file at `p`; null when the file is absent, not JSON, or not an object. */
+  readJsonObject(p: string): Promise<Record<string, unknown> | null>;
+  /**
+   * The file at `p` as UTF-8 text. THROWS as the filesystem does — absence
+   * included — because a caller that can stand in for a missing file must say
+   * so itself (`isAbsence`), and one that cannot should fail. The sibling
+   * above answers `null` instead because "not JSON" and "not there" are the
+   * same non-answer to it; there is no such collapse for raw text.
+   */
+  readTextFile(p: string): Promise<string>;
+  /**
+   * Bytes still writable on the volume holding `p`, as an unprivileged process
+   * sees them; null when the volume cannot say. The one question the readiness
+   * answer asks of the disk: a volume that fills turns every git write into a
+   * failure, and the queue behind those writes stops moving.
+   */
+  freeBytes(p: string): Promise<number | null>;
+}