@hominis/fireforge 0.45.0 → 0.46.1

package/dist/src/core/patch-lock.js

@@ -16,12 +16,12 @@ const PATCH_DIRECTORY_LOCK = '.fireforge-patches.lock';
  * session lock's progress line so operators read one shape for both locks.
  */
 function formatWaitProgressLine(waitedMs, timeoutMs, holder) {
-    const progress = `${String(Math.round(waitedMs / 1000))}s of up to ${String(Math.round(timeoutMs / 1000))}s`;
+    const progress = `${Math.round(waitedMs / 1000)}s of up to ${Math.round(timeoutMs / 1000)}s`;
     if (holder === undefined) {
         return `Waiting for the FireForge patch directory lock — ${progress}.`;
     }
     const details = holder.metadata.length > 0 ? ` (${holder.metadata.join(', ')})` : '';
-    return `Waiting for the FireForge patch directory lock held by PID ${String(holder.pid)}${details} — ${progress}.`;
+    return `Waiting for the FireForge patch directory lock held by PID ${holder.pid}${details} — ${progress}.`;
 }
 /**
  * Asserts that this process is inside {@link withPatchDirectoryLock} for the
@@ -34,7 +34,7 @@ function formatWaitProgressLine(waitedMs, timeoutMs, holder) {
  * is held, so an unlocked caller silently reintroduces the interleaving the
  * lock exists to prevent.
  *
- * Fail-open on an unreadable owner record, deliberately: `withFileLock`
+ * Fail-open on an unreadable owner record, on purpose: `withFileLock`
  * treats writing that record as non-fatal, so a live holder can legitimately
  * have no readable PID and asserting on its presence would fire on a lock we
  * really do hold.
@@ -47,7 +47,7 @@ export async function assertPatchDirectoryLockHeld(patchesDir, context) {
     const status = await readLockStatus(join(patchesDir, PATCH_DIRECTORY_LOCK));
     assert(status.held, () => `patch directory lock is held before ${context}`);
     assert(status.holder === undefined || status.holder.pid === process.pid, () => `patch directory lock is owned by this process before ${context} ` +
-        `(held by PID ${String(status.holder?.pid)}, we are ${String(process.pid)})`);
+        `(held by PID ${status.holder?.pid}, we are ${process.pid})`);
 }
 /**
  * Runs a patch directory mutation while holding an exclusive filesystem lock.
@@ -56,7 +56,7 @@ export async function assertPatchDirectoryLockHeld(patchesDir, context) {
 export async function withPatchDirectoryLock(patchesDir, operation, options = {}) {
     const lockDir = join(patchesDir, PATCH_DIRECTORY_LOCK);
     const { waitLockSeconds, command } = options;
-    // Tag whatever the BODY throws so the catch below can tell it apart from a
+    // Tag whatever the body throws so the catch below can tell it apart from a
     // lock-acquire/release failure. Narrowing by origin rather than by error
     // shape is what "the rewrap is for lock I/O" actually means: an errno test
     // would still reclassify an EACCES raised while the body writes a .patch
@@ -90,10 +90,10 @@ export async function withPatchDirectoryLock(patchesDir, operation, options = {}
             : {}),
         // Reason first, remedy second. The remedy is waiting, not deleting: bulk
         // exports/re-exports legitimately hold this lock for minutes, and
-        // FireForge reaps genuinely stale locks on its own — advice to `rm -rf`
-        // while a holder is alive destroys a live lock. The leading sentence is
-        // a message contract; extend, do not reword. withFileLock appends the
-        // holder identification.
+        // FireForge reaps genuinely stale locks on its own, and advice to
+        // `rm -rf` while a holder is alive destroys a live lock. The leading
+        // sentence is a message contract. Extend, do not reword. withFileLock
+        // appends the holder identification.
         onTimeoutMessage: `Timed out waiting for another FireForge command mutating ${patchesDir}.\n` +
             `Pass --wait-lock [seconds] to wait longer (bare --wait-lock waits up to 60 seconds). ` +
             `FireForge removes genuinely stale locks automatically; only if no other fireforge ` +
@@ -105,7 +105,7 @@ export async function withPatchDirectoryLock(patchesDir, operation, options = {}
         // reports an EACCES writing patches.json, a postcondition failure from
         // renumberPatchesInManifest, or a plain TypeError from a FireForge bug
         // as a "Patch Error" carrying three fixed remedies about Firefox-version
-        // compatibility and `fireforge reset` — none of which apply. Worse,
+        // compatibility and `fireforge reset`, none of which apply. Worse,
         // src/cli.ts prints a stack only for non-FireForgeError throwables, so
         // the rewrap moves real bugs into the branch that discards their stack.
         if (bodyThrew && error === bodyFailure) {
@@ -114,7 +114,7 @@ export async function withPatchDirectoryLock(patchesDir, operation, options = {}
         if (error instanceof FireForgeError) {
             throw error;
         }
-        // CommandError is the one class in src/errors/ that does NOT extend
+        // CommandError is the one class in src/errors/ that does not extend
         // FireForgeError: it is the sentinel carrying an already-rendered exit
         // code to the entrypoint. The `instanceof FireForgeError` guard above
         // misses it, so without this the exit code was replaced by PATCH_ERROR.

package/dist/src/core/patch-manifest-consistency.d.ts

@@ -20,7 +20,7 @@ export declare function validatePatchesManifestConsistency(patchesDir: string):
  *
  * Drift that is only in `filesAffected` is a derived value disagreeing with
  * the diff it describes, and the narrow repair fixes exactly that. Naming the
- * whole-manifest rebuild for it — as this hint used to, unconditionally — puts
+ * whole-manifest rebuild for it (as this hint used to, unconditionally) puts
  * an operator one keystroke from rewriting every row in the manifest to
  * correct one list.
  */
@@ -30,19 +30,19 @@ export declare function recommendManifestRepair(issues: readonly PatchManifestCo
  * lists patches whose manifest entry was reconstructed from filename,
  * mtime, and diff alone (no pre-existing manifest entry to preserve).
  * These entries carry generic descriptions and mtime-based
- * timestamps; callers like `doctor --repair-patches-manifest` surface
+ * timestamps. Callers like `doctor --repair-patches-manifest` surface
  * a per-patch review warning so operators know which metadata was
  * invented vs which was restored.
  */
 export interface RebuildPatchesManifestResult {
     /**
      * Rebuilt manifest, ready to be re-applied by callers. Persisted unless
-     * the run was a dry run — see {@link RebuildPatchesManifestResult.written}.
+     * the run was a dry run. See {@link RebuildPatchesManifestResult.written}.
      */
     manifest: PatchesManifest;
     /**
      * Filenames whose manifest entry had no pre-existing metadata to
-     * preserve — every descriptive field on these entries is inferred.
+     * preserve. Every descriptive field on these entries is inferred.
      */
     recoveredFilenames: string[];
     /**
@@ -59,7 +59,7 @@ export interface RebuildPatchesManifestOptions extends PatchDirectoryLockOptions
     /**
      * Proceed even when patches.json exists but cannot be parsed, in which case
      * there is no existing metadata to preserve and every descriptive field on
-     * every entry is invented. Refused without this flag — see
+     * every entry is invented. Refused without this flag. See
      * {@link rebuildPatchesManifest}.
      */
     allowMetadataLoss?: boolean;
@@ -69,7 +69,7 @@ export interface RebuildPatchesManifestOptions extends PatchDirectoryLockOptions
 /**
  * Rebuilds patches.json from the patch files currently present on disk.
  *
- * This is a MERGE, not a from-scratch rebuild: only `filesAffected` and
+ * This is a merge, not a from-scratch rebuild: only `filesAffected` and
  * `order` are recomputed from the patch files, and every other field on an
  * existing entry is carried forward untouched. Entries with no pre-existing
  * metadata are recovered from filename structure, patch contents, and file
@@ -82,7 +82,7 @@ export interface RebuildPatchesManifestOptions extends PatchDirectoryLockOptions
  * @param patchesDir - Path to the patches directory
  * @param fallbackSourceEsrVersion - source version to use for recovered legacy entries
  * @param options - Lock options plus `allowMetadataLoss` / `dryRun`
- * @returns {@link RebuildPatchesManifestResult} — the rebuilt manifest, the
+ * @returns {@link RebuildPatchesManifestResult}: the rebuilt manifest, the
  *   filenames that were reconstructed from generic defaults, and the rows
  *   dropped because their patch file is gone.
  */

package/dist/src/core/patch-manifest-consistency.js

@@ -86,7 +86,7 @@ export async function validatePatchesManifestConsistency(patchesDir) {
  *
  * Drift that is only in `filesAffected` is a derived value disagreeing with
  * the diff it describes, and the narrow repair fixes exactly that. Naming the
- * whole-manifest rebuild for it — as this hint used to, unconditionally — puts
+ * whole-manifest rebuild for it (as this hint used to, unconditionally) puts
  * an operator one keystroke from rewriting every row in the manifest to
  * correct one list.
  */
@@ -103,7 +103,7 @@ export function recommendManifestRepair(issues) {
 /**
  * Rebuilds patches.json from the patch files currently present on disk.
  *
- * This is a MERGE, not a from-scratch rebuild: only `filesAffected` and
+ * This is a merge, not a from-scratch rebuild: only `filesAffected` and
  * `order` are recomputed from the patch files, and every other field on an
  * existing entry is carried forward untouched. Entries with no pre-existing
  * metadata are recovered from filename structure, patch contents, and file
@@ -116,7 +116,7 @@ export function recommendManifestRepair(issues) {
  * @param patchesDir - Path to the patches directory
  * @param fallbackSourceEsrVersion - source version to use for recovered legacy entries
  * @param options - Lock options plus `allowMetadataLoss` / `dryRun`
- * @returns {@link RebuildPatchesManifestResult} — the rebuilt manifest, the
+ * @returns {@link RebuildPatchesManifestResult}: the rebuilt manifest, the
  *   filenames that were reconstructed from generic defaults, and the rows
  *   dropped because their patch file is gone.
  */
@@ -125,7 +125,7 @@ export async function rebuildPatchesManifest(patchesDir, fallbackSourceEsrVersio
     // patch-directory lock (invariant 2, docs/lifecycle-invariants.md):
     // manifest writes serialize on this lock, so without it a repair racing a
     // concurrent export/reorder can clobber the other writer's manifest. Not
-    // reentrant — callers must not already hold it.
+    // reentrant: callers must not already hold it.
     //
     // A dry run takes the lock too: it reads the same manifest and patch bodies
     // a real run would, and a projection computed against a queue being
@@ -136,9 +136,9 @@ async function rebuildPatchesManifestUnderLock(patchesDir, fallbackSourceEsrVers
     const manifestState = await loadPatchesManifestState(patchesDir);
     const existingEntries = new Map();
     // An unparseable manifest yields `manifest: null`, which the merge below
-    // cannot distinguish from "no manifest at all" — every entry would be
+    // cannot distinguish from "no manifest at all". Every entry would be
     // treated as new and every descriptive field reinvented. `filesAffected`
-    // is the only field a .patch body can yield; `stagedDependencies`,
+    // is the only field a .patch body can yield. `stagedDependencies`,
     // `lintIgnore`, `tier`, `description`, `category`, `createdAt` and the
     // source version cannot be reconstructed from a diff at all. Refuse rather
     // than write that, since the write is what makes it unrecoverable on a
@@ -187,21 +187,20 @@ async function rebuildPatchesManifestUnderLock(patchesDir, fallbackSourceEsrVers
             // callers can warn the operator per-patch. A missing entry means every
             // descriptive field (`description`, `createdAt`, `category`) was
             // invented rather than preserved, and FireForge patch files carry no
-            // header metadata that could carry a human description forward — so
+            // header metadata that could carry a human description forward, so
             // visibility is the best available, and silent overwrites of
             // human-written descriptions during a recovery run are the failure to
             // avoid.
             recoveredFilenames.push(patch.filename);
         }
-        // The rebuild OWNS exactly two fields — `filesAffected` (recomputed from
+        // The rebuild owns exactly two fields: `filesAffected` (recomputed from
         // the patch body) and `order` (from the filename ordinal). Everything
         // else on an existing entry is carried forward by the spread, so a field
-        // a .patch cannot express — `stagedDependencies`, `lintIgnore`, `tier`,
-        // and whatever is added to PatchMetadata next — survives a repair by
-        // construction rather than by someone remembering to list it here. It was
-        // an enumerated literal until `stagedDependencies` was dropped from every
-        // entry that had one, which is the failure this shape prevents from
-        // recurring.
+        // a .patch cannot express (`stagedDependencies`, `lintIgnore`, `tier`,
+        // and whatever is added to PatchMetadata next) survives a repair without
+        // anyone remembering to list it here. It was an enumerated literal until
+        // `stagedDependencies` was dropped from every entry that had one, which
+        // is the failure this shape prevents from recurring.
         const rebuilt = {
             ...(existing ?? {}),
             filename: patch.filename,
@@ -228,9 +227,9 @@ async function rebuildPatchesManifestUnderLock(patchesDir, fallbackSourceEsrVers
         patches: rebuiltPatches,
     };
     // Whatever is left in the map had a manifest row but no patch file, so the
-    // rebuild drops it. That is the correct outcome — the file is the source of
-    // truth — but dropping rows without naming them is indistinguishable from
-    // never having had them.
+    // rebuild drops it. That is the correct outcome, since the file is the
+    // source of truth, but dropping rows without naming them is
+    // indistinguishable from never having had them.
     const droppedFilenames = [...existingEntries.keys()].sort((left, right) => left.localeCompare(right));
     if (options.dryRun === true) {
         return {

package/dist/src/core/patch-manifest-files-affected.d.ts

@@ -1,5 +1,5 @@
 /**
- * Narrow repair for `filesAffected` — the one manifest field a `.patch` body
+ * Narrow repair for `filesAffected`, the one manifest field a `.patch` body
  * can actually yield.
  *
  * A `files-affected-mismatch` is pure derived-value drift: the manifest's list

package/dist/src/core/patch-manifest-files-affected.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Narrow repair for `filesAffected` — the one manifest field a `.patch` body
+ * Narrow repair for `filesAffected`, the one manifest field a `.patch` body
  * can actually yield.
  *
  * A `files-affected-mismatch` is pure derived-value drift: the manifest's list
@@ -47,7 +47,7 @@ async function repairPatchesFilesAffectedUnderLock(patchesDir, filenames, option
         const row = rowByFilename.get(filename);
         if (patchPath === undefined || !row) {
             // A missing patch file or a missing row is a different consistency
-            // issue with a different remedy; this repair reports it rather than
+            // issue with a different remedy. This repair reports it rather than
             // inventing a row or deleting one.
             skippedFilenames.push(filename);
             continue;
@@ -63,7 +63,7 @@ async function repairPatchesFilesAffectedUnderLock(patchesDir, filenames, option
         return { repairs, skippedFilenames, written: false };
     }
     const correctedByFilename = new Map(repairs.map((repair) => [repair.filename, repair.after]));
-    // Row-scoped mutation, so every untouched entry keeps its exact JSON shape —
+    // Row-scoped mutation, so every untouched entry keeps its exact JSON shape:
     // no re-sorted `filesAffected` lists and no reader-only fallback fields
     // serialized into rows this repair has no business touching.
     await mutatePatchRowsInManifest(patchesDir, [...correctedByFilename.keys()], (existing) => {

package/dist/src/core/patch-manifest-io.d.ts

@@ -39,10 +39,10 @@ export declare function loadPatchesManifestState(patchesDir: string): Promise<Lo
 /**
  * Loads the patches manifest if it exists.
  *
- * READ-ONLY callers only: this collapses "absent" and "corrupt" into null.
- * Any code path that will WRITE the manifest (or delete patch files based
- * on its content) must use {@link loadPatchesManifestForWrite} instead —
- * treating a corrupt manifest as empty and then saving destroys every
+ * Read-only callers only: this collapses "absent" and "corrupt" into null.
+ * Any code path that writes the manifest (or deletes patch files based
+ * on its content) must use {@link loadPatchesManifestForWrite} instead.
+ * Treating a corrupt manifest as empty and then saving destroys every
  * existing patch's metadata.
  *
  * @param patchesDir - Path to the patches directory
@@ -52,7 +52,7 @@ export declare function loadPatchesManifest(patchesDir: string): Promise<Patches
 /**
  * Loads the patches manifest for a mutating operation.
  *
- * Returns null only when the manifest genuinely does not exist; a manifest
+ * Returns null only when the manifest genuinely does not exist. A manifest
  * that exists but fails to parse/validate throws
  * {@link PatchManifestCorruptError} so the caller aborts instead of
  * rebuilding an empty queue over the top of the corrupt file.
@@ -80,11 +80,11 @@ export declare function mutatePatchRowsInManifest(patchesDir: string, filenames:
 export declare function addPatchToManifest(patchesDir: string, metadata: PatchMetadata, removeFilenames?: string[]): Promise<void>;
 /**
  * Removes a single patch entry from the manifest by filename. Leaves the
- * ordinal gap in place — callers wanting to close the gap must use
+ * ordinal gap in place. Callers wanting to close the gap must use
  * {@link renumberPatchesInManifest} explicitly. This matches the spec: delete
  * is a row removal, not a resequencing.
  *
- * Not atomic with any on-disk patch file deletion; callers are expected to
+ * Not atomic with any on-disk patch file deletion. Callers are expected to
  * remove the .patch file separately under the same lock.
  *
  * @param patchesDir - Path to the patches directory
@@ -99,7 +99,7 @@ export declare function removePatchFromManifest(patchesDir: string, filename: st
 export interface PatchRenameEntry {
     /** New filename (e.g. `005-ui-sidebar.patch`). */
     newFilename: string;
-    /** New numeric order — must match the prefix of `newFilename`. */
+    /** New numeric order. Must match the prefix of `newFilename`. */
     newOrder: number;
 }
 /**
@@ -129,7 +129,7 @@ export declare function rewriteStagedDependencyOwners(patch: PatchMetadata, rena
  * orders. Failure semantics:
  *
  *   - **Phase 1 (stage)**: rolls back by renaming staged files back to
- *     their originals. Manifest is untouched. Best-effort — a rollback
+ *     their originals. Manifest is untouched. Best-effort: a rollback
  *     rename failure is warned but not re-thrown.
  *   - **Phase 2 (stage → final)**: rolls back to the pre-operation state
  *     by reversing every partial step: files already at their final
@@ -138,13 +138,13 @@ export declare function rewriteStagedDependencyOwners(patch: PatchMetadata, rena
  *     the rollback itself fails midway, the thrown error is augmented
  *     with a description of the residue so the operator can inspect.
  *   - **Phase 3 (manifest write)**: by this point all files are on disk
- *     at their new names; a manifest write failure will roll the files
+ *     at their new names. A manifest write failure will roll the files
  *     back to their original names before re-throwing so the directory
  *     and manifest stay in agreement. A rollback failure at this stage
  *     is warned (manifest was never mutated) and the original error is
  *     re-thrown.
  *
- * Does not sort the rename map for the caller — the map is the authoritative
+ * Does not sort the rename map for the caller. The map is the authoritative
  * plan. Entries not present in the map keep their existing filename and
  * order.
  *
@@ -154,7 +154,7 @@ export declare function rewriteStagedDependencyOwners(patch: PatchMetadata, rena
 export declare function renumberPatchesInManifest(patchesDir: string, renameMap: Map<string, PatchRenameEntry>): Promise<void>;
 /**
  * Thrown when {@link removePatchFileAndManifest} cannot complete the file
- * delete AND cannot restore the manifest row afterward, so the on-disk
+ * delete and cannot restore the manifest row afterward, so the on-disk
  * state and manifest state are known to disagree. Carries both the
  * primary delete error and the rollback error so the caller (and the
  * operator) can see the full failure chain instead of only the original
@@ -162,7 +162,7 @@ export declare function renumberPatchesInManifest(patchesDir: string, renameMap:
  *
  * Extends {@link FireForgeError} so the CLI top-level handler routes it
  * through the rich-error formatter rather than the generic unexpected-error
- * path; the dedicated `.name` is kept so programmatic callers and tests
+ * path. The dedicated `.name` is kept so programmatic callers and tests
  * can still distinguish it with `instanceof PatchDeleteRollbackError`.
  */
 export declare class PatchDeleteRollbackError extends FireForgeError {
@@ -174,7 +174,7 @@ export declare class PatchDeleteRollbackError extends FireForgeError {
 }
 /**
  * Deletes both a patch file on disk and its manifest row under the caller's
- * lock. This is a convenience for the `patch delete` command; callers that
+ * lock. This is a convenience for the `patch delete` command. Callers that
  * need different ordering (e.g. deleting the file first without touching the
  * manifest) should call the primitives separately.
  *

package/dist/src/core/patch-manifest-io.js

@@ -50,10 +50,10 @@ export async function loadPatchesManifestState(patchesDir) {
 /**
  * Loads the patches manifest if it exists.
  *
- * READ-ONLY callers only: this collapses "absent" and "corrupt" into null.
- * Any code path that will WRITE the manifest (or delete patch files based
- * on its content) must use {@link loadPatchesManifestForWrite} instead —
- * treating a corrupt manifest as empty and then saving destroys every
+ * Read-only callers only: this collapses "absent" and "corrupt" into null.
+ * Any code path that writes the manifest (or deletes patch files based
+ * on its content) must use {@link loadPatchesManifestForWrite} instead.
+ * Treating a corrupt manifest as empty and then saving destroys every
  * existing patch's metadata.
  *
  * @param patchesDir - Path to the patches directory
@@ -66,7 +66,7 @@ export async function loadPatchesManifest(patchesDir) {
 /**
  * Loads the patches manifest for a mutating operation.
  *
- * Returns null only when the manifest genuinely does not exist; a manifest
+ * Returns null only when the manifest genuinely does not exist. A manifest
  * that exists but fails to parse/validate throws
  * {@link PatchManifestCorruptError} so the caller aborts instead of
  * rebuilding an empty queue over the top of the corrupt file.
@@ -98,17 +98,18 @@ export async function mutatePatchRowsInManifest(patchesDir, filenames, mutator)
     if (!(await pathExistsStrict(manifestPath)))
         return null;
     const rawManifest = await readJson(manifestPath);
+    // `validatePatchesManifest` has already rejected a manifest that is not an
+    // object with an array of object rows (it throws the corruption error the
+    // caller expects), so the shape re-checks below are FireForge's own
+    // invariants, not input validation: failing them means the validator and
+    // this walker disagree about the manifest schema, which is a bug here.
     const beforeManifest = validatePatchesManifest(rawManifest);
-    if (!isObject(rawManifest) || !isArray(rawManifest['patches'])) {
-        throw new Error('patches.json must be a JSON object with a patches array');
-    }
+    assert(isObject(rawManifest) && isArray(rawManifest['patches']), 'validated patches.json is a JSON object with a patches array');
     const filenameSet = new Set(filenames);
     if (filenameSet.size === 0)
         return [];
-    const rawPatches = rawManifest['patches'].map((entry) => {
-        if (!isObject(entry)) {
-            throw new Error('patches.json patches entries must be objects');
-        }
+    const rawPatches = rawManifest['patches'].map((entry, index) => {
+        assert(isObject(entry), () => `validated patches.json row ${index} is an object`);
         return { ...entry };
     });
     const changedIndexes = [];
@@ -174,11 +175,11 @@ export async function addPatchToManifest(patchesDir, metadata, removeFilenames)
 }
 /**
  * Removes a single patch entry from the manifest by filename. Leaves the
- * ordinal gap in place — callers wanting to close the gap must use
+ * ordinal gap in place. Callers wanting to close the gap must use
  * {@link renumberPatchesInManifest} explicitly. This matches the spec: delete
  * is a row removal, not a resequencing.
  *
- * Not atomic with any on-disk patch file deletion; callers are expected to
+ * Not atomic with any on-disk patch file deletion. Callers are expected to
  * remove the .patch file separately under the same lock.
  *
  * @param patchesDir - Path to the patches directory
@@ -209,7 +210,7 @@ export async function removePatchFromManifest(patchesDir, filename) {
  * sorted ascending (readers take manifest order as apply order without
  * re-sorting).
  *
- * Contiguity itself is deliberately NOT checked: `patchPolicy.ranges`
+ * Contiguity itself is not checked, on purpose: `patchPolicy.ranges`
  * reserves gaps on purpose, so a hole is a legitimate queue shape.
  *
  * @param patches - The manifest rows about to be written
@@ -287,7 +288,7 @@ export function rewriteStagedDependencyOwners(patch, renameLookup) {
  * orders. Failure semantics:
  *
  *   - **Phase 1 (stage)**: rolls back by renaming staged files back to
- *     their originals. Manifest is untouched. Best-effort — a rollback
+ *     their originals. Manifest is untouched. Best-effort: a rollback
  *     rename failure is warned but not re-thrown.
  *   - **Phase 2 (stage → final)**: rolls back to the pre-operation state
  *     by reversing every partial step: files already at their final
@@ -296,13 +297,13 @@ export function rewriteStagedDependencyOwners(patch, renameLookup) {
  *     the rollback itself fails midway, the thrown error is augmented
  *     with a description of the residue so the operator can inspect.
  *   - **Phase 3 (manifest write)**: by this point all files are on disk
- *     at their new names; a manifest write failure will roll the files
+ *     at their new names. A manifest write failure will roll the files
  *     back to their original names before re-throwing so the directory
  *     and manifest stay in agreement. A rollback failure at this stage
  *     is warned (manifest was never mutated) and the original error is
  *     re-thrown.
  *
- * Does not sort the rename map for the caller — the map is the authoritative
+ * Does not sort the rename map for the caller. The map is the authoritative
  * plan. Entries not present in the map keep their existing filename and
  * order.
  *
@@ -359,7 +360,7 @@ export async function renumberPatchesInManifest(patchesDir, renameMap) {
             await rename(join(patchesDir, staged), targetPath);
             // Postcondition assert: confirm the target actually exists on disk
             // before marking the rename complete. A silent rename failure leaves
-            // the manifest and the filesystem disagreeing — manifest rewritten to
+            // the manifest and the filesystem disagreeing: manifest rewritten to
             // new filenames while the old files stay on disk. If the assert fires,
             // the Phase 2 rollback undoes prior moves before re-throwing.
             if (!(await pathExistsStrict(targetPath))) {
@@ -369,7 +370,7 @@ export async function renumberPatchesInManifest(patchesDir, renameMap) {
         }
     }
     catch (error) {
-        // Phase 2 rollback — reverse both the partial final-name moves and
+        // Phase 2 rollback: reverse both the partial final-name moves and
         // the phase-1 staging. This collapses the directory back to its
         // pre-operation filenames so the manifest (which was never
         // touched) remains consistent with what is on disk. If any
@@ -403,7 +404,7 @@ export async function renumberPatchesInManifest(patchesDir, renameMap) {
         throw error;
     }
     // Phase 3: rewrite the manifest rows. Any entry without a rename keeps its
-    // existing metadata; entries in the map get their filename + order
+    // existing metadata. Entries in the map get their filename + order
     // updated. Sort by the new order so the manifest remains ordered.
     const filenameUpdates = new Map();
     for (const [oldFilename, entry] of renameMap) {
@@ -427,13 +428,13 @@ export async function renumberPatchesInManifest(patchesDir, renameMap) {
     try {
         // Phase 3 is the one write that makes the renumber visible. Every file
         // has already moved on disk, so a manifest that disagrees with the new
-        // filenames is the worst outcome available here — the queue would apply
-        // in an order nothing on disk reflects. The callers compute the rename
-        // map (compact, reorder, export placement) and each maintains contiguity
-        // on its own; this checks the property they are all supposed to produce,
-        // at the single point where it becomes durable. Inside the try, so a
-        // violation unwinds through the Phase 3 rollback that puts the filenames
-        // back.
+        // filenames is the worst outcome available here, because the queue
+        // would apply in an order nothing on disk reflects. The callers compute
+        // the rename map (compact, reorder, export placement) and each maintains
+        // contiguity on its own. This checks the property they are all supposed
+        // to produce, at the single point where it becomes durable. Inside the
+        // try, so a violation unwinds through the Phase 3 rollback that puts the
+        // filenames back.
         assertRenumberedOrderIsWellFormed(updatedPatches);
         await savePatchesManifest(patchesDir, {
             ...manifest,
@@ -444,7 +445,7 @@ export async function renumberPatchesInManifest(patchesDir, renameMap) {
         // Phase 3 rollback: reverse every completed rename. The manifest
         // save failed before it could be persisted, so the on-disk state
         // must match what the manifest still records. Best-effort: any
-        // individual step that fails gets warned; the original save
+        // individual step that fails gets warned. The original save
         // error is always re-thrown so the caller sees the real cause.
         for (const completed of completedFinalRenames) {
             try {
@@ -459,7 +460,7 @@ export async function renumberPatchesInManifest(patchesDir, renameMap) {
 }
 /**
  * Thrown when {@link removePatchFileAndManifest} cannot complete the file
- * delete AND cannot restore the manifest row afterward, so the on-disk
+ * delete and cannot restore the manifest row afterward, so the on-disk
  * state and manifest state are known to disagree. Carries both the
  * primary delete error and the rollback error so the caller (and the
  * operator) can see the full failure chain instead of only the original
@@ -467,7 +468,7 @@ export async function renumberPatchesInManifest(patchesDir, renameMap) {
  *
  * Extends {@link FireForgeError} so the CLI top-level handler routes it
  * through the rich-error formatter rather than the generic unexpected-error
- * path; the dedicated `.name` is kept so programmatic callers and tests
+ * path. The dedicated `.name` is kept so programmatic callers and tests
  * can still distinguish it with `instanceof PatchDeleteRollbackError`.
  */
 export class PatchDeleteRollbackError extends FireForgeError {
@@ -489,7 +490,7 @@ export class PatchDeleteRollbackError extends FireForgeError {
 }
 /**
  * Deletes both a patch file on disk and its manifest row under the caller's
- * lock. This is a convenience for the `patch delete` command; callers that
+ * lock. This is a convenience for the `patch delete` command. Callers that
  * need different ordering (e.g. deleting the file first without touching the
  * manifest) should call the primitives separately.
  *
@@ -507,8 +508,8 @@ export class PatchDeleteRollbackError extends FireForgeError {
 export async function removePatchFileAndManifest(patchesDir, filename) {
     await assertPatchDirectoryLockHeld(patchesDir, 'deleting a patch and its manifest row');
     const patchPath = join(patchesDir, filename);
-    // ForWrite: deleting the patch FILE while a corrupt manifest still
-    // references it would strand the queue; abort on corruption instead.
+    // ForWrite: deleting the patch file while a corrupt manifest still
+    // references it would strand the queue. Abort on corruption instead.
     const originalManifest = await loadPatchesManifestForWrite(patchesDir);
     const removedFromManifest = await removePatchFromManifest(patchesDir, filename);
     try {

package/dist/src/core/patch-manifest-query.d.ts

@@ -45,7 +45,7 @@ export declare function validatePatchIntegrity(patchesDir: string, engineDir: st
  *
  * Acquires the shared patch-directory lock for the read-modify-write, so a
  * concurrent export/reorder/metadata update cannot interleave with the stamp.
- * The lock is not reentrant — callers must NOT invoke this while already
+ * The lock is not reentrant: callers must not invoke this while already
  * holding {@link withPatchDirectoryLock} on the same patches directory.
  *
  * @param patchesDir - Path to the patches directory

package/dist/src/core/patch-manifest-query.js

@@ -80,9 +80,9 @@ export async function validatePatchIntegrity(patchesDir, engineDir) {
     const issues = [];
     const patches = await discoverPatches(patchesDir);
     // Collect every modification target first, then resolve HEAD existence in
-    // ONE batched ls-tree pass (chunked for ARG_MAX). The per-file
+    // one batched ls-tree pass (chunked for ARG_MAX). The per-file
     // fileExistsInHead fan-out spawned one git process per (patch × target) on
-    // every import — a 56-file branding patch alone cost ~56 spawns before a
+    // every import: a 56-file branding patch alone cost ~56 spawns before a
     // single patch was applied.
     const modificationTargets = [];
     for (const patch of patches) {
@@ -90,7 +90,7 @@ export async function validatePatchIntegrity(patchesDir, engineDir) {
         const patchContent = await readText(patch.path);
         const targetFiles = await getAllTargetFilesFromPatch(patch.path);
         for (const targetFile of targetFiles) {
-            // Skip new-file sections — they don't need to exist in HEAD
+            // Skip new-file sections. They don't need to exist in HEAD
             if (isNewFileInPatch(patchContent, targetFile))
                 continue;
             modificationTargets.push({ filename: patch.filename, targetFile });
@@ -114,7 +114,7 @@ export async function validatePatchIntegrity(patchesDir, engineDir) {
  *
  * Acquires the shared patch-directory lock for the read-modify-write, so a
  * concurrent export/reorder/metadata update cannot interleave with the stamp.
- * The lock is not reentrant — callers must NOT invoke this while already
+ * The lock is not reentrant: callers must not invoke this while already
  * holding {@link withPatchDirectoryLock} on the same patches directory.
  *
  * @param patchesDir - Path to the patches directory

package/dist/src/core/patch-manifest-resolve.d.ts

@@ -2,12 +2,12 @@ import type { PatchMetadata } from '../types/commands/index.js';
 /**
  * Resolves a patch identifier to its manifest entry. Accepts:
  *
- *   1. An ordinal number (e.g. `2`) — matches `PatchMetadata.order`.
- *   2. A full filename with `.patch` suffix (e.g. `002-ui-foo.patch`) —
- *      matches `PatchMetadata.filename`.
- *   3. A filename without the `.patch` suffix — the command appends it
+ *   1. An ordinal number (e.g. `2`), matching `PatchMetadata.order`.
+ *   2. A full filename with `.patch` suffix (e.g. `002-ui-foo.patch`),
+ *      matching `PatchMetadata.filename`.
+ *   3. A filename without the `.patch` suffix. The command appends it
  *      before matching (e.g. `002-ui-foo`).
- *   4. The manifest `name` field (e.g. `furnace-token-override`) — the short
+ *   4. The manifest `name` field (e.g. `furnace-token-override`), the short
  *      logical handle the export workflow stamps onto the patch and the
  *      natural identifier an operator keeps in their notes. The CLI help
  *      says `<name>`, so rejecting it forces the operator to copy the full