canopycms 0.0.67-int.90 → 0.0.67

package/dist/authorization/protected-branch.d.ts

@@ -1,12 +1,11 @@
 /**
- * Protected base branch predicate.
+ * Protected base branch predicate: the single source of truth other modules
+ * key off of — do not re-derive the comparison elsewhere.
  *
- * The base branch (the PR base — usually `main`) can never be submitted for
- * review (both modes: submitting it would push straight to itself, bypassing
- * review) and is read-only in the editor in prod (dev needs the base branch
- * editable since the developer always lands there — see ARCHITECTURE.md
- * "Protected Base Branch"). This is the single source of truth other modules
- * key off of; do not re-derive the comparison elsewhere.
+ * The base branch (the PR base, usually `main`) can never be submitted for
+ * review in either mode, since submitting it would push straight to itself and
+ * bypass review, and is read-only in the editor in prod only — dev needs it
+ * editable (see ARCHITECTURE.md "Protected Base Branch").
  */
 import type { CanopyConfig } from '../config/index.js';
 import type { BranchStatus } from '../types.js';
@@ -28,7 +27,7 @@ export interface BranchWriteProtection extends BranchProtection {
     /**
      * True when content writes must be rejected, for ANY of three reasons: the
      * branch is the read-only protected base branch, its workflow status has
-     * moved past `'editing'` (locked while a reviewer looks at its PR), or its
+     * moved past `'editing'` (locked while its PR is under review), or its
      * status could not be read at all.
      */
     writeBlocked: boolean;
@@ -40,74 +39,46 @@ export interface BranchWriteProtection extends BranchProtection {
      * `writeBlocked` does: `status !== 'editing'` is true when `status` is
      * `undefined`).
      *
-     * DELIBERATELY NOT named `submitBlocked` on this type, even though it
-     * replaces the naive re-derivation of the same conjunction client-side.
-     * `BranchProtection.submitBlocked` (the field this interface inherits) means
-     * ONLY "this is the base branch" -- `api/guards.ts`'s `submittableBranch`
-     * guard reads exactly that, narrow, meaning, and must keep reading it: the
-     * guard's whole point is to refuse the base branch regardless of status. If
-     * this wider, compound answer had reused the same field name on the
-     * subtype, the two meanings would be one property access apart and
-     * indistinguishable at every call site -- a future edit anywhere near the
-     * guard could silently start reading the wide answer where the narrow one
-     * is required (or vice versa) and no type error would catch it, because
-     * both are `boolean`. The verbose name is the guard against that: nobody
-     * writes `submitBlockedIncludingStatus` by accident.
+     * NOT named `submitBlocked`: `BranchProtection.submitBlocked`, the field
+     * this type inherits, means ONLY "this is the base branch", and
+     * `api/guards.ts`'s `submittableBranch` guard depends on that narrow
+     * meaning, so the compound answer gets a distinct name.
      *
-     * Also worth noting the asymmetry with `writeBlocked` above:
-     * `writeBlocked` is built from `readOnly` (protected base branch, PROD
-     * ONLY) plus the status clause, while this is built from `isProtected` /
-     * `submitBlocked` (protected base branch, BOTH MODES) plus the same status
-     * clause. They are not two spellings of one rule -- in dev, the base branch
-     * is writable (`readOnly` is false there, so `writeBlocked` can be false)
-     * but still never submittable (`isProtected` is true regardless of mode, so
-     * this stays true). A branch can be `writeBlocked: false,
-     * submitBlockedIncludingStatus: true` in dev's base branch specifically;
-     * collapsing the two fields into one would lose that state.
+     * It also differs from `writeBlocked`: in dev the base branch is writable
+     * but never submittable, so the two fields disagree there.
      */
     submitBlockedIncludingStatus: boolean;
 }
 /**
- * Determine whether `branchName` is the protected base branch for `config`.
+ * Whether `branchName` is the protected base branch for `config`.
  *
- * Comparison is sanitization-aware: branch metadata names are sanitized
- * (`sanitizeBranchName`) but `config.defaultBaseBranch` holds the raw git
- * name, so both sides are sanitized before comparing.
+ * The comparison is sanitization-aware: branch metadata names are sanitized but
+ * `config.defaultBaseBranch` holds the raw git name, so both sides go through
+ * `sanitizeBranchName` first.
  *
- * `recordedBaseBranch` (a branch's own `baseBranch` field, i.e. its recorded
- * fork point) is an additional, independent protection clause: a branch whose
- * fork point equals its own name IS a base workspace, regardless of what
- * `config.defaultBaseBranch` says right now. This matters because in dev
- * mode, `config.defaultBaseBranch` tracks live git HEAD (`refreshActiveBranch`)
- * and can drift to a different branch after the base workspace was created --
- * without this clause, that drift would silently un-protect the branch the
- * base workspace was actually forked from. The clause is purely additive: it
- * only ever adds protection the config clause didn't already grant, so a
- * normal editing branch (`baseBranch !== name`) is never falsely protected.
+ * `recordedBaseBranch` (a branch's own recorded fork point) is a second, purely
+ * additive clause: a branch whose fork point equals its own name IS a base
+ * workspace whatever `config.defaultBaseBranch` says now. In dev that config
+ * value tracks live git HEAD (`refreshActiveBranch`) and can drift, and without
+ * this clause the drift would silently un-protect the branch the base workspace
+ * was forked from; a normal branch (`baseBranch !== name`) is never falsely
+ * protected.
  *
- * This answers base-branch questions only (submit/delete/ACL rails). To
- * authorize a content write or render a lock, use
- * {@link getBranchWriteProtection}, which also accounts for workflow status.
+ * Answers base-branch questions only (submit/delete/ACL rails). To authorize a
+ * content write or render a lock, use {@link getBranchWriteProtection}, which
+ * also accounts for workflow status.
  */
 export declare function getBranchProtection(config: Pick<CanopyConfig, 'mode' | 'defaultBaseBranch'>, branchName: string, recordedBaseBranch?: string): BranchProtection;
 /**
- * {@link getBranchProtection} plus the write decision: writes are blocked on the
- * read-only base branch, and on any branch whose status has left `'editing'`.
- * This is the single expression of the "which statuses lock editing" rule --
- * the API guard, the branches-list wire flag, and the editor all read it here.
+ * {@link getBranchProtection} plus the write decision: writes are blocked on
+ * the read-only base branch and on any branch whose status has left
+ * `'editing'` -- the single expression of that rule, read by the API guard, the
+ * branches-list wire flag and the editor.
  *
- * `status` is REQUIRED, and deliberately typed to admit `undefined`, because a
- * missing status must FAIL CLOSED. `branch.json` is read with a bare
- * `JSON.parse(...) as BranchMetadataFile` (branch-metadata.ts) with no schema
- * validation, so a hand-repaired or partially-written file can yield
- * `status: undefined` at runtime even though the type says otherwise -- and
- * malformed branch metadata is a real, handled condition here (see the
- * corrupt-metadata quarantine in branch-registry/branch-health). A branch whose
- * review state cannot be determined must not be writable.
- *
- * Requiring the parameter is the point: an optional one would make "caller
- * omitted it" and "the file had no status" indistinguishable, and the safe
- * answer differs between them. Callers that genuinely don't care about status
- * call {@link getBranchProtection} instead and get no `writeBlocked` at all.
+ * `status` is REQUIRED and admits `undefined` because a missing status must
+ * FAIL CLOSED: `branch.json` is read with a bare `JSON.parse(...) as
+ * BranchMetadataFile` (branch-metadata.ts), so it can be absent at runtime.
+ * Required, not optional, so "argument omitted" and "file had no status" stay
+ * distinguishable -- the safe answer differs.
  */
 export declare function getBranchWriteProtection(config: Pick<CanopyConfig, 'mode' | 'defaultBaseBranch'>, branchName: string, recordedBaseBranch: string | undefined, status: BranchStatus | undefined): BranchWriteProtection;

package/dist/authorization/protected-branch.js

@@ -1,38 +1,34 @@
 /**
- * Protected base branch predicate.
+ * Protected base branch predicate: the single source of truth other modules
+ * key off of — do not re-derive the comparison elsewhere.
  *
- * The base branch (the PR base — usually `main`) can never be submitted for
- * review (both modes: submitting it would push straight to itself, bypassing
- * review) and is read-only in the editor in prod (dev needs the base branch
- * editable since the developer always lands there — see ARCHITECTURE.md
- * "Protected Base Branch"). This is the single source of truth other modules
- * key off of; do not re-derive the comparison elsewhere.
+ * The base branch (the PR base, usually `main`) can never be submitted for
+ * review in either mode, since submitting it would push straight to itself and
+ * bypass review, and is read-only in the editor in prod only — dev needs it
+ * editable (see ARCHITECTURE.md "Protected Base Branch").
  */
 // branch-name, NOT branch: this module is client-reachable (editor bundle →
 // api/guards.ts → here), and paths/branch.ts drags node:fs into the graph,
 // which breaks adopters' production `next build`.
 import { sanitizeBranchName } from '../paths/branch-name.js';
 /**
- * Determine whether `branchName` is the protected base branch for `config`.
+ * Whether `branchName` is the protected base branch for `config`.
  *
- * Comparison is sanitization-aware: branch metadata names are sanitized
- * (`sanitizeBranchName`) but `config.defaultBaseBranch` holds the raw git
- * name, so both sides are sanitized before comparing.
+ * The comparison is sanitization-aware: branch metadata names are sanitized but
+ * `config.defaultBaseBranch` holds the raw git name, so both sides go through
+ * `sanitizeBranchName` first.
  *
- * `recordedBaseBranch` (a branch's own `baseBranch` field, i.e. its recorded
- * fork point) is an additional, independent protection clause: a branch whose
- * fork point equals its own name IS a base workspace, regardless of what
- * `config.defaultBaseBranch` says right now. This matters because in dev
- * mode, `config.defaultBaseBranch` tracks live git HEAD (`refreshActiveBranch`)
- * and can drift to a different branch after the base workspace was created --
- * without this clause, that drift would silently un-protect the branch the
- * base workspace was actually forked from. The clause is purely additive: it
- * only ever adds protection the config clause didn't already grant, so a
- * normal editing branch (`baseBranch !== name`) is never falsely protected.
+ * `recordedBaseBranch` (a branch's own recorded fork point) is a second, purely
+ * additive clause: a branch whose fork point equals its own name IS a base
+ * workspace whatever `config.defaultBaseBranch` says now. In dev that config
+ * value tracks live git HEAD (`refreshActiveBranch`) and can drift, and without
+ * this clause the drift would silently un-protect the branch the base workspace
+ * was forked from; a normal branch (`baseBranch !== name`) is never falsely
+ * protected.
  *
- * This answers base-branch questions only (submit/delete/ACL rails). To
- * authorize a content write or render a lock, use
- * {@link getBranchWriteProtection}, which also accounts for workflow status.
+ * Answers base-branch questions only (submit/delete/ACL rails). To authorize a
+ * content write or render a lock, use {@link getBranchWriteProtection}, which
+ * also accounts for workflow status.
  */
 export function getBranchProtection(config, branchName, recordedBaseBranch) {
     const sanitizedName = sanitizeBranchName(branchName);
@@ -45,24 +41,16 @@ export function getBranchProtection(config, branchName, recordedBaseBranch) {
     };
 }
 /**
- * {@link getBranchProtection} plus the write decision: writes are blocked on the
- * read-only base branch, and on any branch whose status has left `'editing'`.
- * This is the single expression of the "which statuses lock editing" rule --
- * the API guard, the branches-list wire flag, and the editor all read it here.
+ * {@link getBranchProtection} plus the write decision: writes are blocked on
+ * the read-only base branch and on any branch whose status has left
+ * `'editing'` -- the single expression of that rule, read by the API guard, the
+ * branches-list wire flag and the editor.
  *
- * `status` is REQUIRED, and deliberately typed to admit `undefined`, because a
- * missing status must FAIL CLOSED. `branch.json` is read with a bare
- * `JSON.parse(...) as BranchMetadataFile` (branch-metadata.ts) with no schema
- * validation, so a hand-repaired or partially-written file can yield
- * `status: undefined` at runtime even though the type says otherwise -- and
- * malformed branch metadata is a real, handled condition here (see the
- * corrupt-metadata quarantine in branch-registry/branch-health). A branch whose
- * review state cannot be determined must not be writable.
- *
- * Requiring the parameter is the point: an optional one would make "caller
- * omitted it" and "the file had no status" indistinguishable, and the safe
- * answer differs between them. Callers that genuinely don't care about status
- * call {@link getBranchProtection} instead and get no `writeBlocked` at all.
+ * `status` is REQUIRED and admits `undefined` because a missing status must
+ * FAIL CLOSED: `branch.json` is read with a bare `JSON.parse(...) as
+ * BranchMetadataFile` (branch-metadata.ts), so it can be absent at runtime.
+ * Required, not optional, so "argument omitted" and "file had no status" stay
+ * distinguishable -- the safe answer differs.
  */
 export function getBranchWriteProtection(config, branchName, recordedBaseBranch, status) {
     const protection = getBranchProtection(config, branchName, recordedBaseBranch);

package/dist/authorization/settings-file-store.d.ts

@@ -1,64 +1,30 @@
 /**
- * Cross-host layered locking for settings JSON files (permissions.json,
- * groups.json) in the settings workspace — a single global orphan-git-branch
+ * Cross-host layered locking for the settings JSON files (permissions.json,
+ * groups.json) in the settings workspace — one global orphan-git-branch
  * checkout at `{settingsRoot}` shared by every branch (see
  * `api/settings-helpers.ts`'s `getSettingsBranchContext`).
  *
- * Without this helper, the write path is a classic unprotected TOCTOU: load
- * -> compare -> mutate -> write with no lock spanning the cycle, so two warm
- * Lambda containers (separate NFS clients on EFS) can each read the same
- * pre-mutation file and have the second write silently clobber the first.
- * `mutateSettingsJsonFile` closes that with the standard 3-layer recipe from
- * docs/concurrency.md, structured identically to {@link CommentStore}'s
- * `withMutation` (see comment-store.ts) and `BranchMetadataFileManager.save()`
- * (see branch-metadata.ts):
+ * `mutateSettingsJsonFile` composes the three layers docs/concurrency.md owns
+ * ("The four layers"; the settings-files row of "Who uses what"): `withLock`
+ * on the resolved path, then `withOccFileLock`, then `withOccRetry` around
+ * `writeOccJsonFile`, which reloads the file on every attempt. Without all
+ * three the write path is an unprotected TOCTOU: two warm Lambda containers
+ * are separate NFS clients on EFS, so both can read the same pre-mutation file
+ * and the second write silently wins.
  *
- * 1. {@link withLock} - an in-process FIFO mutex keyed by the resolved file
- *    path. Deterministic same-process serialization.
- * 2. {@link withOccFileLock} - a server-enforced, cross-process/cross-host
- *    lock (proper-lockfile, mkdir-based), immune to NFS client dentry/
- *    attribute caching. This is the actual fix for a lost permission/group
- *    edit across two warm Lambda containers on EFS.
- * 3. {@link withOccRetry} around {@link writeOccJsonFile} - version/writeId
- *    based optimistic concurrency control, reloading the file fresh on
- *    EVERY retry attempt. With layers 1-2 in place this is defense-in-depth
- *    (e.g. a stale process from a rolling deploy writing without the lock),
- *    not the primary safety mechanism.
+ * What that doc and `utils/occ-json-write.ts` do not cover:
  *
- * `writeOccJsonFile`'s managed `version`/`writeId` pair is now THE single
- * counter for these files: the old hand-rolled `version: 1` format literal
- * and the separate `contentVersion` field are gone. A pre-existing file on
- * disk that still says `"version": 1` simply reads as OCC version 1 and
- * continues incrementing from there; a leftover `contentVersion` key is
- * silently stripped by the (non-strict, extra-keys-stripped) zod parse.
- *
- * Three caveats specific to these files, on top of the generic guarantee
- * documented on `utils/occ-json-write.ts`:
- *
- * (a) UNLIKE comments.json/branch.json (which never leave the branch
- *     workspace), permissions.json/groups.json are git-committed on the
- *     settings orphan branch. `commitSettings()` (api/settings-helpers.ts)
- *     calls `commitToSettingsBranch`, whose `pullCurrentBranch()` merge runs
- *     AFTER this helper has released its lock, and that merge can rewrite
- *     the file's `version` from upstream. So, unlike branch.json, `version`
- *     here is NOT guaranteed monotonic — it remains a correctness aid (it
- *     still catches the common same-host and short-window cross-host races)
- *     but is advisory/defense-in-depth, not a hard guarantee. The LOCKFILE
- *     (layer 2) is the actual cross-host correctness mechanism.
- * (b) The git commit+push deliberately happens OUTSIDE this lock (mirrors
- *     branch-metadata.ts keeping registry invalidation outside the lock it
- *     protects): committing/pushing is comparatively slow network/process
- *     I/O, and holding a mkdir-based lock across it would serialize
- *     unrelated requests behind that I/O for no correctness gain — only the
- *     write to the working tree needs the lock.
- * (c) Because commit+push is outside the lock, two writers' save-then-commit
- *     sequences can interleave (A saves+commits+pushes, B's save lands and
- *     commits before A's push is visible, or similar), and the second
- *     `git commit` can run against an already-clean tree. Verified benign
- *     with simple-git 3.36: its task-error detection depends on stderr
- *     output, and a clean-tree `git commit` exits 1 with "nothing to
- *     commit" on STDOUT only, so `git.commit()` resolves rather than
- *     throwing. Re-verify this on any simple-git upgrade.
+ * (a) These files are git-committed, so `version` is NOT monotonic here --
+ *     `commitSettings()` (api/settings-helpers.ts) calls
+ *     `commitToSettingsBranch`, whose `pullCurrentBranch()` merge runs after
+ *     this helper releases its lock and can rewrite `version` from upstream.
+ *     The lockfile (layer 2) is the cross-host guarantee; OCC is defense.
+ * (b) The git commit+push deliberately runs OUTSIDE this lock: it is slow
+ *     network I/O, and only the working-tree write needs the lock.
+ * (c) So two writers' save-then-commit sequences can interleave and the second
+ *     `git commit` can hit an already-clean tree. Benign with simple-git 3.36,
+ *     whose task-error detection reads stderr while a clean-tree commit exits
+ *     1 with "nothing to commit" on stdout only. Re-verify on upgrade.
  */
 import { type OccWriteResult } from '../utils/occ-json-write.js';
 /**
@@ -70,23 +36,19 @@ export declare class SettingsFileConflictError extends Error {
     constructor(message?: string);
 }
 /**
- * Thrown by a caller's `mutate` callback when an app-level
- * `expectedContentVersion` sent by a client doesn't match the file's current
- * `version`. A different concern from {@link SettingsFileConflictError}:
- * this is a real edit conflict the user must resolve by reloading, not
- * transient lock contention a retry can fix — and indeed it never IS
- * retried, since {@link withOccRetry} only recognizes
- * {@link OccWriteConflictError} as retryable, so this propagates on the
- * very first attempt.
+ * Thrown by a caller's `mutate` when a client-supplied
+ * `expectedContentVersion` doesn't match the file's current `version`: a real
+ * edit conflict the user resolves by reloading, not the transient contention
+ * behind {@link SettingsFileConflictError}. It is never retried —
+ * {@link withOccRetry} only retries {@link OccWriteConflictError} — so it
+ * propagates on the first attempt.
  */
 export declare class SettingsVersionConflictError extends Error {
     constructor(message?: string);
 }
 /**
- * Structural shape `mutateSettingsJsonFile` needs from a parsed settings
- * file: just enough to read the OCC version off it without resorting to
- * `any`. Concrete file types (e.g. `PermissionsFile`, `GroupsFile`) satisfy
- * this automatically since `version` is optional on both.
+ * Just enough of a parsed settings file to read its OCC version without `any`.
+ * `PermissionsFile` and `GroupsFile` satisfy it — `version` is optional on both.
  */
 interface VersionedSettingsFile {
     version?: number;
@@ -97,13 +59,11 @@ export interface MutateSettingsFileOptions<TFile extends VersionedSettingsFile>
     /** JSON.parse + zod-parse the raw file contents. Throws propagate untouched (never retried). */
     parse: (raw: string) => TFile;
     /**
-     * Compute the next payload from the current parsed file (`null` on
-     * ENOENT) and the version to write it under. Return `null` for a
-     * deliberate no-op — the write is skipped entirely. Called once per
-     * retry attempt against freshly reloaded state, so it must be safe to
-     * call more than once; anything it throws (besides the retried
-     * `OccWriteConflictError`, which it should never throw itself) propagates
-     * out of `mutateSettingsJsonFile` untouched.
+     * Compute the next payload from the current parsed file (`null` on ENOENT)
+     * and the version to write it under; return `null` for a deliberate no-op.
+     * Called once per retry attempt against freshly reloaded state, so it must be
+     * safe to call more than once. Anything it throws propagates out untouched,
+     * and it must never throw `OccWriteConflictError` itself.
      */
     mutate: (current: TFile | null, version: number) => Record<string, unknown> | null | Promise<Record<string, unknown> | null>;
     /** Forwarded to writeOccJsonFile. Pass 0 in tests. */
@@ -112,15 +72,12 @@ export interface MutateSettingsFileOptions<TFile extends VersionedSettingsFile>
     maxAttempts?: number;
 }
 /**
- * Run a load -> mutate -> write cycle for a settings JSON file under the
- * full lock + OCC-retry stack described in the module doc comment above. A
- * conflict that survives every retry surfaces as
+ * Run one load -> mutate -> write cycle under the full lock + OCC-retry stack
+ * described in the module doc. A conflict surviving every retry surfaces as
  * {@link SettingsFileConflictError}; everything else — including
  * {@link SettingsVersionConflictError} thrown by `mutate`, and any
- * parse/validation error — propagates untouched.
- *
- * Returns the `writeOccJsonFile` result, or `null` if `mutate` chose a
- * no-op (no write happened).
+ * parse/validation error — propagates untouched. Returns the
+ * `writeOccJsonFile` result, or `null` if `mutate` chose a no-op.
  */
 export declare function mutateSettingsJsonFile<TFile extends VersionedSettingsFile>(opts: MutateSettingsFileOptions<TFile>): Promise<OccWriteResult | null>;
 export {};

package/dist/authorization/settings-file-store.js

@@ -1,64 +1,30 @@
 /**
- * Cross-host layered locking for settings JSON files (permissions.json,
- * groups.json) in the settings workspace — a single global orphan-git-branch
+ * Cross-host layered locking for the settings JSON files (permissions.json,
+ * groups.json) in the settings workspace — one global orphan-git-branch
  * checkout at `{settingsRoot}` shared by every branch (see
  * `api/settings-helpers.ts`'s `getSettingsBranchContext`).
  *
- * Without this helper, the write path is a classic unprotected TOCTOU: load
- * -> compare -> mutate -> write with no lock spanning the cycle, so two warm
- * Lambda containers (separate NFS clients on EFS) can each read the same
- * pre-mutation file and have the second write silently clobber the first.
- * `mutateSettingsJsonFile` closes that with the standard 3-layer recipe from
- * docs/concurrency.md, structured identically to {@link CommentStore}'s
- * `withMutation` (see comment-store.ts) and `BranchMetadataFileManager.save()`
- * (see branch-metadata.ts):
+ * `mutateSettingsJsonFile` composes the three layers docs/concurrency.md owns
+ * ("The four layers"; the settings-files row of "Who uses what"): `withLock`
+ * on the resolved path, then `withOccFileLock`, then `withOccRetry` around
+ * `writeOccJsonFile`, which reloads the file on every attempt. Without all
+ * three the write path is an unprotected TOCTOU: two warm Lambda containers
+ * are separate NFS clients on EFS, so both can read the same pre-mutation file
+ * and the second write silently wins.
  *
- * 1. {@link withLock} - an in-process FIFO mutex keyed by the resolved file
- *    path. Deterministic same-process serialization.
- * 2. {@link withOccFileLock} - a server-enforced, cross-process/cross-host
- *    lock (proper-lockfile, mkdir-based), immune to NFS client dentry/
- *    attribute caching. This is the actual fix for a lost permission/group
- *    edit across two warm Lambda containers on EFS.
- * 3. {@link withOccRetry} around {@link writeOccJsonFile} - version/writeId
- *    based optimistic concurrency control, reloading the file fresh on
- *    EVERY retry attempt. With layers 1-2 in place this is defense-in-depth
- *    (e.g. a stale process from a rolling deploy writing without the lock),
- *    not the primary safety mechanism.
+ * What that doc and `utils/occ-json-write.ts` do not cover:
  *
- * `writeOccJsonFile`'s managed `version`/`writeId` pair is now THE single
- * counter for these files: the old hand-rolled `version: 1` format literal
- * and the separate `contentVersion` field are gone. A pre-existing file on
- * disk that still says `"version": 1` simply reads as OCC version 1 and
- * continues incrementing from there; a leftover `contentVersion` key is
- * silently stripped by the (non-strict, extra-keys-stripped) zod parse.
- *
- * Three caveats specific to these files, on top of the generic guarantee
- * documented on `utils/occ-json-write.ts`:
- *
- * (a) UNLIKE comments.json/branch.json (which never leave the branch
- *     workspace), permissions.json/groups.json are git-committed on the
- *     settings orphan branch. `commitSettings()` (api/settings-helpers.ts)
- *     calls `commitToSettingsBranch`, whose `pullCurrentBranch()` merge runs
- *     AFTER this helper has released its lock, and that merge can rewrite
- *     the file's `version` from upstream. So, unlike branch.json, `version`
- *     here is NOT guaranteed monotonic — it remains a correctness aid (it
- *     still catches the common same-host and short-window cross-host races)
- *     but is advisory/defense-in-depth, not a hard guarantee. The LOCKFILE
- *     (layer 2) is the actual cross-host correctness mechanism.
- * (b) The git commit+push deliberately happens OUTSIDE this lock (mirrors
- *     branch-metadata.ts keeping registry invalidation outside the lock it
- *     protects): committing/pushing is comparatively slow network/process
- *     I/O, and holding a mkdir-based lock across it would serialize
- *     unrelated requests behind that I/O for no correctness gain — only the
- *     write to the working tree needs the lock.
- * (c) Because commit+push is outside the lock, two writers' save-then-commit
- *     sequences can interleave (A saves+commits+pushes, B's save lands and
- *     commits before A's push is visible, or similar), and the second
- *     `git commit` can run against an already-clean tree. Verified benign
- *     with simple-git 3.36: its task-error detection depends on stderr
- *     output, and a clean-tree `git commit` exits 1 with "nothing to
- *     commit" on STDOUT only, so `git.commit()` resolves rather than
- *     throwing. Re-verify this on any simple-git upgrade.
+ * (a) These files are git-committed, so `version` is NOT monotonic here --
+ *     `commitSettings()` (api/settings-helpers.ts) calls
+ *     `commitToSettingsBranch`, whose `pullCurrentBranch()` merge runs after
+ *     this helper releases its lock and can rewrite `version` from upstream.
+ *     The lockfile (layer 2) is the cross-host guarantee; OCC is defense.
+ * (b) The git commit+push deliberately runs OUTSIDE this lock: it is slow
+ *     network I/O, and only the working-tree write needs the lock.
+ * (c) So two writers' save-then-commit sequences can interleave and the second
+ *     `git commit` can hit an already-clean tree. Benign with simple-git 3.36,
+ *     whose task-error detection reads stderr while a clean-tree commit exits
+ *     1 with "nothing to commit" on stdout only. Re-verify on upgrade.
  */
 import fs from 'node:fs/promises';
 import path from 'node:path';
@@ -77,14 +43,12 @@ export class SettingsFileConflictError extends Error {
     }
 }
 /**
- * Thrown by a caller's `mutate` callback when an app-level
- * `expectedContentVersion` sent by a client doesn't match the file's current
- * `version`. A different concern from {@link SettingsFileConflictError}:
- * this is a real edit conflict the user must resolve by reloading, not
- * transient lock contention a retry can fix — and indeed it never IS
- * retried, since {@link withOccRetry} only recognizes
- * {@link OccWriteConflictError} as retryable, so this propagates on the
- * very first attempt.
+ * Thrown by a caller's `mutate` when a client-supplied
+ * `expectedContentVersion` doesn't match the file's current `version`: a real
+ * edit conflict the user resolves by reloading, not the transient contention
+ * behind {@link SettingsFileConflictError}. It is never retried —
+ * {@link withOccRetry} only retries {@link OccWriteConflictError} — so it
+ * propagates on the first attempt.
  */
 export class SettingsVersionConflictError extends Error {
     constructor(message = 'Settings were modified by another user. Please reload and try again.') {
@@ -93,17 +57,15 @@ export class SettingsVersionConflictError extends Error {
     }
 }
 /**
- * Reload the file fresh and report the version to feed both `mutate()` and
+ * Reload the file fresh and report the version fed to both `mutate()` and
  * `writeOccJsonFile`'s `expectedVersion`.
  *
- * ENOENT is the ONLY case that maps to a `null` `occExpectedVersion` (the
- * create-via-link path in {@link writeOccJsonFile}): an EXISTING file —
- * even one hand-written without a `version` field — maps to `0` and takes
- * the rename-based update path instead. Conflating the two would make
- * `writeOccJsonFile` attempt a `link()` create against a file that already
- * exists, spuriously failing with EEXIST instead of doing a normal
- * versioned update. (Same contract as `CommentStore`'s `loadWithVersion` in
- * comment-store.ts.)
+ * ENOENT is the ONLY case mapping to a `null` `occExpectedVersion` (the
+ * create-via-link path in {@link writeOccJsonFile}); an existing file, even one
+ * hand-written with no `version` field, maps to `0` and takes the rename-based
+ * update path. Conflating them makes `writeOccJsonFile` attempt a `link()`
+ * create over a file that exists and fail with EEXIST. (Same contract as
+ * `CommentStore`'s `loadWithVersion` in comment-store.ts.)
  */
 async function loadCurrent(filePath, parse) {
     let raw;
@@ -120,15 +82,12 @@ async function loadCurrent(filePath, parse) {
     return { current: parsed, occExpectedVersion: parsed.version ?? 0 };
 }
 /**
- * Run a load -> mutate -> write cycle for a settings JSON file under the
- * full lock + OCC-retry stack described in the module doc comment above. A
- * conflict that survives every retry surfaces as
+ * Run one load -> mutate -> write cycle under the full lock + OCC-retry stack
+ * described in the module doc. A conflict surviving every retry surfaces as
  * {@link SettingsFileConflictError}; everything else — including
  * {@link SettingsVersionConflictError} thrown by `mutate`, and any
- * parse/validation error — propagates untouched.
- *
- * Returns the `writeOccJsonFile` result, or `null` if `mutate` chose a
- * no-op (no write happened).
+ * parse/validation error — propagates untouched. Returns the
+ * `writeOccJsonFile` result, or `null` if `mutate` chose a no-op.
  */
 export async function mutateSettingsJsonFile(opts) {
     const resolved = path.resolve(opts.filePath);

package/dist/authorization/types.d.ts

@@ -1,54 +1,32 @@
 /**
- * Authorization types for CanopyCMS
- *
- * This module exports all types related to authorization including
- * branch access, path permissions, and content access results.
- */
-import type { CanopyUserId, CanopyGroupId } from '../types.js';
-export type { CanopyUserId, CanopyGroupId };
-/**
- * A path used in permission rules.
- * SECURITY CRITICAL: Always validated to prevent path traversal.
- * Example: "content/posts" or "content/settings/config"
+ * A path used in permission rules, e.g. "content/posts".
+ * SECURITY CRITICAL: always validated to prevent path traversal.
  */
 export type PermissionPath = string & {
     readonly __brand: 'PermissionPath';
 };
-/**
- * Result of checking branch-level access
- */
 export interface BranchAccessResult {
     allowed: boolean;
     reason: 'privileged' | 'base_branch' | 'creator' | 'allowed_by_acl' | 'denied_by_acl' | 'no_acl';
 }
-/**
- * Result of checking path-level permissions
- */
 export interface PathPermissionResult {
     allowed: boolean;
     matchedRule?: import('../config/index.js').PathPermission;
     reason?: string;
 }
-/**
- * Combined result of checking both branch and path access
- */
 export interface ContentAccessResult {
     allowed: boolean;
     branch: BranchAccessResult;
     path: PathPermissionResult;
 }
-/**
- * Dependencies for content access checking
- */
 export interface ContentAccessDeps {
     checkBranchAccess: (context: import('../types.js').BranchContext, user: import('../user.js').CanopyUser) => BranchAccessResult;
     loadPathPermissions: (branchRoot: string, mode: import('../operating-mode/index.js').OperatingMode) => Promise<import('../config/index.js').PathPermission[]>;
     defaultPathAccess: import('../config/index.js').DefaultPathAccess;
     mode: import('../operating-mode/index.js').OperatingMode;
     /**
-     * Get the settings branch root path for loading centralized permissions.
-     * Used in modes with a separate settings branch.
-     * Must throw if settings branch cannot be loaded.
+     * Settings branch root for loading centralized permissions, in modes with a
+     * separate settings branch. Must throw if it cannot be loaded.
      */
     getSettingsBranchRoot?: () => Promise<string>;
 }

package/dist/authorization/types.js

@@ -1,7 +1 @@
-/**
- * Authorization types for CanopyCMS
- *
- * This module exports all types related to authorization including
- * branch access, path permissions, and content access results.
- */
 export {};