@bevel-software/platform-shared 0.14.0 → 0.19.0

package/src/git/types.ts

@@ -68,9 +68,21 @@ export interface ValidationReport {
   rawOutput: string;
 }
 
+/** What `IGitService.syncFromRemote` observed under its one hold of the clone. */
+export interface RemoteSyncPullResult {
+  /** HEAD before the pull; null when the clone had no commits yet. */
+  before: string | null;
+  /** HEAD after the pull; null only when origin is still empty too. */
+  after: string | null;
+  /** Whether the working tree's CONTENT differs — tree ids, not commit ids. */
+  treeChanged: boolean;
+  /** Repo-relative paths whose content changed; empty unless `treeChanged`. */
+  changedPaths: string[];
+}
+
 export interface IGitService {
   status(workspaceId: string): Promise<WorkingTreeStatus>;
-  listBranches(workspaceId: string, opts?: { freshFetch?: boolean }): Promise<BranchInfo[]>;
+  listBranches(workspaceId: string, opts?: { freshFetch?: boolean; strictFetch?: boolean }): Promise<BranchInfo[]>;
   createBranch(
     workspaceId: string,
     name: string,
@@ -129,7 +141,39 @@ export interface IGitService {
     },
   ): Promise<void>;
   fetch(workspaceId: string): Promise<void>;
-  pull(workspaceId: string): Promise<void>;
+  /**
+   * `treeChanged` is whether the pull left the working tree holding different
+   * CONTENT than before the call — tree ids compared, not commit ids, so a
+   * pull that only moves HEAD across content-identical commits (an empty
+   * commit, a rebase that replays to the same result) reports false. Only the
+   * pull itself can answer that (it holds the workspace mutex across the
+   * rebase; any before/after probe a caller ran around it would race), and
+   * callers that announce "this tree changed" to the rest of the process need
+   * the distinction: an "already up to date" pull that broadcast anyway would
+   * drop every catalog cache and reload every attached browser for nothing.
+   */
+  pull(workspaceId: string): Promise<{ treeChanged: boolean }>;
+  /**
+   * The remote sync's pull, observed as ONE serialized operation: where HEAD
+   * was, the pull, where HEAD is, and which repo-relative paths changed
+   * (rename-aware: both ends). `pull` bracketed by separate reads would let a
+   * concurrent save land between them and be announced as the sync's own.
+   *
+   * Tolerant of an unborn HEAD (a clone of an empty upstream): `before` is
+   * null, and paths are diffed against the empty tree. Throws the typed
+   * pull-conflict error like `pull`, and a typed "remote branch gone" error
+   * when origin no longer has the branch — including for an unborn clone,
+   * once origin has any branch at all. The one exception: an unborn clone
+   * against an origin with NO branches (a fresh deployment nobody has pushed
+   * to) resolves to `after: null`, since there is nothing to sync and nothing
+   * stale.
+   */
+  syncFromRemote(workspaceId: string): Promise<RemoteSyncPullResult>;
+  /**
+   * Whether origin still has `branch` right now (`ls-remote`). Used to
+   * revalidate that a clone is still stale before it is retired.
+   */
+  remoteBranchExists(workspaceId: string, branch: string): Promise<boolean>;
   diffStat(workspaceId: string, base?: string): Promise<string[]>;
   /**
    * Paths in the working tree that the next commit would include — the set
@@ -205,6 +249,40 @@ export interface IGitService {
    * Just the repo-relative paths a change request touches (three-dot diff,
    * no statuses, no patches): the cheap form behind change-request list
    * summaries and owner routing.
+   *
+   * `fetch: false` skips the per-request fetch of the two refs — for a caller
+   * that has just refreshed the whole clone's remote-tracking refs in one
+   * round trip, which is what a LIST does rather than paying one fetch per
+   * request. Pass it only when that is true; otherwise the diff can describe
+   * a stale head. It is a skip, not a promise: a branch the clone does not
+   * have yet is fetched anyway, since there is nothing to diff without it —
+   * so a list's first sight of a new request still costs one round trip.
+   */
+  changedPathsForPr(
+    workspaceId: string,
+    baseBranch: string,
+    headBranch: string,
+    opts?: { fetch?: boolean },
+  ): Promise<string[]>;
+
+  /**
+   * A change request's fork point (merge base of the two resolved commits)
+   * and whether the target has commits the proposal does not contain. No
+   * fetch: `at` is what `resolvePrShas` just returned.
+   */
+  forkPointForPr(
+    workspaceId: string,
+    at: { baseSha: string; headSha: string },
+  ): Promise<{ mergeBaseSha: string | null; behind: boolean }>;
+
+  /**
+   * A file's content at a change request's fork point — a commit that must
+   * be on `baseBranch`'s history. `null` when the path did not exist there.
    */
-  changedPathsForPr(workspaceId: string, baseBranch: string, headBranch: string): Promise<string[]>;
+  readFileAtForkPoint(
+    workspaceId: string,
+    baseBranch: string,
+    sha: string,
+    relativePath: string,
+  ): Promise<string | null>;
 }

package/src/index.ts

@@ -6,10 +6,16 @@ export * from './chat/types.js';
 
 // Workspace
 export * from './workspace/types.js';
+export * from './workspace/agent-preamble.js';
 export * from './workspace/filename.js';
+export * from './workspace/entry-exists.js';
 export * from './workspace/kb-layout.js';
 export * from './workspace/join-request.js';
 export * from './workspace/frontmatter.js';
+export * from './workspace/placeholder.js';
+export * from './workspace/frontmatter-carriers.js';
+export * from './workspace/platform-files.js';
+export * from './workspace/access-verbs.js';
 
 // Git
 export * from './git/types.js';

package/src/workflow/events.ts

@@ -132,6 +132,13 @@ export interface GitSyncFailedEvent {
   branch: string;
   /** Sanitised git error — safe to display, tokens already redacted. */
   reason: string;
+  /**
+   * Present when the failure is a REMOTE-SYNC CONFLICT (`POST /api/sync`
+   * found Hexis-side commits that contradict what landed on the host): the
+   * repo-relative files a person has to reconcile. Unlike a failing push,
+   * this is the author's to act on, so the banner offers to open them.
+   */
+  conflictedPaths?: string[];
 }
 
 /**
@@ -214,6 +221,28 @@ export interface ChangeRequestRejectedEvent {
   number: number;
 }
 
+/**
+ * An apply did NOT land, announced to EVERY session — the counterpart of the
+ * user-scoped `change-request-merge-failed` below, which only the clicker gets.
+ *
+ * The request stays open, so everyone who can see it (its author waiting on
+ * the verdict, another owner, another admin) needs to learn that the attempt
+ * failed and why. The reason is deliberately NOT carried here: it is persisted
+ * on the request (`PullRequestSummary.lastApplyFailure`) and read back through
+ * the list and detail endpoints the viewer already uses, so the broadcast puts
+ * no error text in front of every session, and a session that missed the event
+ * reads the same answer on its next fetch.
+ *
+ * Also sent when a recorded refusal is CLEARED because a change made it
+ * obsolete (an approval for a gate refusal, a moved source head for any):
+ * either way the request's `lastApplyFailure` changed, and every viewer
+ * re-reads it.
+ */
+export interface ChangeRequestApplyFailedEvent {
+  kind: 'change-request-apply-failed';
+  number: number;
+}
+
 /**
  * A merge the caller triggered did NOT land — either the gate refused it, the
  * branch needs conflict resolution, or `gh pr merge` failed. The merge route
@@ -221,9 +250,10 @@ export interface ChangeRequestRejectedEvent {
  * gateway timeout), so this is how the failure reaches the UI that kicked it
  * off. Success travels on `change-request-merged` instead.
  *
- * User-scoped (`forUserId`, no `workspaceId`) — a failed merge changes no
- * shared state; only the user who clicked needs the reason, so we don't
- * broadcast the error string to every session.
+ * User-scoped (`forUserId`, no `workspaceId`) — the clicker's immediate
+ * answer, which also routes a conflict into the resolution flow. Everyone else
+ * learns of the failure from `change-request-apply-failed`, which carries no
+ * error string; the reason itself is persisted on the request.
  */
 export interface ChangeRequestMergeFailedEvent {
   kind: 'change-request-merge-failed';
@@ -236,6 +266,12 @@ export interface ChangeRequestMergeFailedEvent {
    * The UI routes to the agent resolution flow instead of showing an error.
    */
   conflicts: boolean;
+  /**
+   * When the attempt failed (ISO) — the same instant persisted as
+   * `lastApplyFailure.at` when the refusal is recorded, so the clicker's tab
+   * can tell its own refusal from a later one somebody else's attempt made.
+   */
+  at?: string;
 }
 
 /**
@@ -289,6 +325,7 @@ export type WorkflowEventPayload =
   | ChangeRequestMergedEvent
   | ChangeRequestRejectedEvent
   | ChangeRequestMergeFailedEvent
+  | ChangeRequestApplyFailedEvent
   | ApprovalChangedEvent
   | HeartbeatEvent
   | ResyncEvent;

package/src/workflow/interface.ts

@@ -18,9 +18,11 @@
  */
 
 import type { AuthUser } from '../auth/types.js';
+import type { ChangeRequestApplyFailureKind } from '../git/pr.types.js';
 import type {
   AcquireLockResult,
   Branch,
+  BranchSyncOutcome,
   BranchWorkspaceStatus,
   CancelChangeRequestResult,
   Change,
@@ -32,6 +34,9 @@ import type {
   ChangedFile,
   FileApproval,
   FileLock,
+  FolderChangeRequest,
+  FolderChangeRequestRemoval,
+  MergeBranchOutcome,
   MergeChangeRequestOutcome,
   OpenChangeRequestInput,
   PostChangeRequestCommentInput,
@@ -40,11 +45,18 @@ import type {
 export interface IWorkflowService {
   // ── Branches ──────────────────────────────────────────────────────────────
 
-  listBranches(workspaceId: string, opts?: { freshFetch?: boolean }): Promise<Branch[]>;
+  /**
+   * `freshFetch` bypasses the fetch TTL; `strictFetch` makes a failed fetch
+   * throw instead of serving the stale refs — for a caller that uses the
+   * list to prove a branch ABSENT (a stale list proves nothing).
+   */
+  listBranches(workspaceId: string, opts?: { freshFetch?: boolean; strictFetch?: boolean }): Promise<Branch[]>;
   /**
    * Create a new unprotected branch. Protected branches cannot be created
    * via the workflow — the protected set is bootstrapped from the KB repo's
-   * initial state and never grown at runtime.
+   * initial state and never grown at runtime. Holds the branch-lifecycle
+   * lock for `name`, so creation is serialised with the branch's deletion
+   * and with the retirement of a stale clone under that name.
    */
   createBranch(workspaceId: string, name: string, fromBase?: string): Promise<Branch>;
   /**
@@ -101,6 +113,31 @@ export interface IWorkflowService {
    * `user` when provided (falls back to the recovery bot).
    */
   updateFromRemote(workspaceId: string, user?: AuthUser): Promise<void>;
+  /**
+   * The remote-sync step for ONE branch's clone, driven by a git host's
+   * webhook or a pipeline rather than by a person's save. Pulls with the same
+   * rebase-and-autostash `updateFromRemote` uses and, when HEAD moved,
+   * announces the new tree (`fs-tree-changed`, one `file-changed` per path)
+   * so open browsers, agents and the catalogues see it at once.
+   *
+   * On a conflict it does what `updateFromRemote` does — the divergence goes
+   * to the same background recovery ladder (attributed to the recovery bot,
+   * since no person triggered the sync) — and, because that is not resolved
+   * at request time, reports it as a `conflict` outcome naming the files, so
+   * the caller can fail and a person can step in if recovery does not clear
+   * it. Never throws for a per-branch failure; every failure is an outcome.
+   */
+  syncWorkspaceFromRemote(workspaceId: string): Promise<BranchSyncOutcome>;
+  /**
+   * Retire the clone of a branch the host has deleted (a `remote-gone`
+   * outcome). Runs under the branch-lifecycle lock — the one `createBranch`
+   * and `deleteBranch` hold, so no Hexis operation can recreate the branch
+   * while the clone is examined and removed — revalidates against origin
+   * first, and backs off while a clone of the branch is being bootstrapped.
+   * A branch recreated in the meantime therefore keeps its clone. Returns
+   * whether the clone was removed.
+   */
+  retireRemoteGoneClone(workspaceId: string): Promise<boolean>;
   /**
    * Hard-reset the workspace's checked-out branch to `origin/<branch>` (fetch
    * first), discarding any local divergence. Break-glass primitive for
@@ -189,9 +226,38 @@ export interface IWorkflowService {
     path: string,
     sha: string,
   ): Promise<{ baseline: string | null; current: string | null }>;
+  /**
+   * One file as it stood at a change request's fork point (`sha`, which must
+   * lie on the target branch's history) — the "before" side of the request
+   * dialog's diff. `null` when the path did not exist there. Access is the
+   * caller's to check.
+   */
+  fileAtForkPoint(
+    workspaceId: string,
+    baseBranch: string,
+    sha: string,
+    path: string,
+  ): Promise<string | null>;
+  /**
+   * A change request's current fork point: the merge base of the freshly
+   * fetched target and source branches, or `null` when they share no history.
+   */
+  changeRequestForkPoint(
+    workspaceId: string,
+    baseBranch: string,
+    headBranch: string,
+  ): Promise<string | null>;
 
   // ── File locks (new — currently NotImplementedWorkflowError) ──────────────
 
+  // Every lock method below coordinates on ONE canonical identity per file:
+  // `x/a.md`, `./x/a.md` and `x//a.md` name the same lock, so a lock acquired
+  // under any of them is contended, heartbeated, checkpointed, released and
+  // read under any other. A path that escapes the workspace, or that only
+  // becomes relative by being laundered, is refused with the same status the
+  // file verbs answer for that input: 400 for an unusable path, 403 for one
+  // that resolves outside the workspace.
+
   /**
    * Try to acquire an edit lock on `(branch, path)` for the caller. Returns
    * `{ acquired: true, lock }` on success; `{ acquired: false, lock }` if
@@ -213,13 +279,37 @@ export interface IWorkflowService {
    * `releaseLockUntouched`) — `releaseLock` rejects rather than ever enqueue
    * a commit for a hold that was never allowed to write. Internal callers
    * only; never plumbed from a route.
+   *
+   * Every non-coordination acquire also passes the READ-BEFORE-WRITE gate, on
+   * every branch: the caller must be able to read the path (for a new path,
+   * where it lands), or the path must start a new folder directly under one
+   * of the three roots (knowledge, skills, plugins). Nothing is created,
+   * changed or removed where its author cannot see it, whatever write rules
+   * say; a refusal is an `AccessDeniedError` whose `access.unreadable` names
+   * the place. A write that passed only as a platform-file restore is not
+   * asked — that rescue exists for a destination whose rules deny the admin
+   * making it.
+   *
+   * `opts.platformRestore` CLAIMS that this acquire is the destination side of
+   * an admin putting a misplaced platform file back (`access.md`, `roles.yaml`,
+   * `.bevelignore`, the agent guide), and names the move's `source` — the path the
+   * file is coming FROM, in the same spelling as `path`.
+   *
+   * It is a claim, not an authorisation. The implementation re-asks both
+   * halves of it: that source→path is a restore at all (a misplaced copy
+   * going back under its own name, never the root's own copy coming out —
+   * `isPlatformRestoreShape`), and that the access module
+   * (`canRestorePlatformFile`) lets this caller land this exact path. Only
+   * both yeses let the acquire past the write gate, so a caller that omits or
+   * fakes the source gains nothing: the gate never takes the route's word for
+   * which move this is.
    */
   acquireLock(
     workspaceId: string,
     branch: string,
     path: string,
     user: AuthUser,
-    opts?: { coordination?: boolean },
+    opts?: { coordination?: boolean; platformRestore?: { source: string } },
   ): Promise<AcquireLockResult>;
   /** Heartbeat to keep an acquired lock alive past its current TTL. */
   heartbeatLock(workspaceId: string, branch: string, path: string, user: AuthUser): Promise<FileLock>;
@@ -361,9 +451,12 @@ export interface IWorkflowService {
   ): Promise<ChangeRequestDetail>;
 
   /**
-   * Re-run `targetBranch → sourceBranch` merge on an existing change request.
-   * Used when the target has advanced since the change request was opened.
-   * Throws `NotImplementedWorkflowError` until the backing merge path lands.
+   * Re-run `targetBranch → sourceBranch` merge on an existing change request
+   * and push it — the request dialog's Update, offered when the target has
+   * advanced since the request was opened. Only the request's author or
+   * someone who may apply it (`viewerCanUpdate`) may run it (403 otherwise).
+   * A conflicting merge is aborted, leaving the branch exactly as it was, and
+   * surfaces as `ChangeRequestConflictsError` (409).
    */
   updateFromTarget(workspaceId: string, user: AuthUser, number: number): Promise<ChangeRequestDetail>;
 
@@ -421,6 +514,22 @@ export interface IWorkflowService {
    */
   closeEmptyChangeRequest(number: number, user: AuthUser): Promise<boolean>;
 
+  /**
+   * The open change requests proposing files under a KB-repo-relative
+   * folder, each with whether the caller may take those files out of it
+   * (their own request, they are an admin, or they may write every file it
+   * proposes under the folder).
+   */
+  changeRequestsUnderFolder(folder: string, user: AuthUser): Promise<FolderChangeRequest[]>;
+
+  /**
+   * Take every file under the folder out of every open change request
+   * proposing one; a request left empty is withdrawn. All or nothing: refused
+   * (403), with nothing touched, when the caller may not act on even one of
+   * them.
+   */
+  removeFolderFromChangeRequests(folder: string, user: AuthUser): Promise<FolderChangeRequestRemoval[]>;
+
   /**
    * Close every open change request either of whose branches no longer exists
    * — source or target, since a proposal needs both ends. Such a request
@@ -477,4 +586,51 @@ export interface IWorkflowService {
     workspaceId: string,
     opts?: { bypass?: boolean },
   ): Promise<MergeChangeRequestOutcome>;
+
+  /** Start an apply attempt on a request; the token scopes `recordApplyFailure`. */
+  beginApplyAttempt(number: number): number;
+
+  /** End an attempt `beginApplyAttempt` started, whatever its outcome. */
+  endApplyAttempt(number: number, attempt: number): void;
+
+  /**
+   * Persist why an apply did not land on the (still open) request, and
+   * announce `change-request-apply-failed` to every session so the author and
+   * other viewers re-read it — not only the user who clicked. Resolves false,
+   * recording and announcing nothing, when `attempt` is no longer the latest
+   * or the request is no longer open.
+   */
+  recordApplyFailure(
+    number: number,
+    failure: { reason: string; kind: ChangeRequestApplyFailureKind; at?: Date },
+    user: AuthUser,
+    attempt: number,
+  ): Promise<boolean>;
+
+  /**
+   * Merge `sourceBranch` into `targetBranch` directly, authored as `user`,
+   * and publish the target. The agent path for merging branches — it never
+   * lands a change request:
+   *
+   *   - refused (`OpenChangeRequestBlocksMergeError`, naming the request) when
+   *     a change request from `sourceBranch` into `targetBranch` is open; a
+   *     person merges that one in the app. The reverse direction — the target
+   *     into the source, the sync that keeps a draft current — is allowed.
+   *   - refused (`WorkflowDomainError`, `kind: 'protected-merge-target'`,
+   *     status 403, listing the denied paths) when `targetBranch` is protected
+   *     and `user` could not commit every file the merge changes directly to
+   *     it. Decided against the target commit the merge is built on, not a
+   *     workspace `HEAD` that may be behind it.
+   *   - refused (`WorkflowDomainError`, `kind: 'protected-merge-changes-roles'`,
+   *     status 403) when `targetBranch` is protected and the merge would
+   *     change its `roles.yaml` — whoever the caller is. Roles never change
+   *     through a merge; a change request's merge restores the target's copy
+   *     first, and this path refuses instead. Roles are changed in the app.
+   *   - refused (`WorkflowDomainError`, `kind: 'merge-target-busy'`, status
+   *     409) when `targetBranch`'s workspace still holds unshared edits: the
+   *     merge resets it to the published tip, which would discard them.
+   *
+   * Conflicts write nothing and come back as `conflicts-need-resolution`.
+   */
+  mergeBranch(user: AuthUser, sourceBranch: string, targetBranch: string): Promise<MergeBranchOutcome>;
 }

package/src/workflow/types.ts

@@ -133,6 +133,40 @@ export type CancelChangeRequestResult = CancelPrResult;
 export type ChangeRequestComment = PrReviewComment;
 export type PostChangeRequestCommentInput = PostPrCommentInput;
 
+/**
+ * One open change request proposing files under a folder, as a folder delete
+ * lists it. `mayRemove`: the caller may take those files out of it (their own,
+ * they are an admin, or they may write every file it proposes under the
+ * folder); a refusal always says why.
+ */
+export type FolderChangeRequest = {
+  number: number;
+  title: string;
+  authorName: string | null;
+  /** The caller authored it. */
+  mine: boolean;
+  /** KB-repo-relative paths it proposes under the folder. */
+  paths: string[];
+} & ({ mayRemove: true } | { mayRemove: false; reason: string });
+
+/** What removing a folder's files did to one change request. */
+export interface FolderChangeRequestRemoval {
+  number: number;
+  removedPaths: string[];
+  /** The request proposed nothing else, so it was withdrawn. */
+  withdrawn: boolean;
+  /**
+   * Files under the folder it still proposes: added while the removal ran,
+   * so never judged, and left alone.
+   */
+  stillProposed: string[];
+  /**
+   * It proposes nothing now but was kept open, because a save to its branch
+   * was still landing — withdrawing would have deleted that save.
+   */
+  keptForSaves: boolean;
+}
+
 /**
  * Input for opening a new change request. The workflow auto-merges
  * `targetBranch` into `sourceBranch` as part of opening, so callers don't
@@ -163,3 +197,39 @@ export interface OpenChangeRequestInput {
 export type MergeChangeRequestOutcome =
   | { kind: 'merged'; result: MergeChangeRequestResult }
   | { kind: 'conflicts-need-resolution'; conflictedPaths: string[] };
+
+/**
+ * What a direct branch-to-branch merge (`mergeBranch`) did: landed as `sha`
+ * on the target (the target's own tip when it already contained the source),
+ * or stopped on conflicts, nothing written.
+ */
+export type MergeBranchOutcome =
+  | { kind: 'merged'; sha: string }
+  | { kind: 'conflicts-need-resolution'; conflictedPaths: string[] };
+
+/**
+ * What a remote sync did to one branch's clone. One entry per branch in the
+ * `POST /api/sync` response, so a pipeline can read exactly which branch
+ * moved, which was already current, and which needs a person.
+ *
+ *  - `updated`     — the clone moved from `from` (null when it had no commits
+ *                    yet) to `to`.
+ *  - `up-to-date`  — origin had nothing new; `to` is the unchanged HEAD.
+ *  - `not-cloned`  — Hexis has no clone of this branch, so there is nothing
+ *                    to refresh (the first visit clones it fresh).
+ *  - `remote-gone` — the branch no longer exists on the host; the stale clone
+ *                    is removed. Not a failure: a deleted branch has nothing
+ *                    to sync.
+ *  - `conflict`    — Hexis-side commits contradict what landed on the host.
+ *                    The clone is untouched; `error` is the message to show
+ *                    and `conflictedPaths` the files a person must reconcile.
+ *  - `error`       — the pull failed for another reason (origin unreachable,
+ *                    credential refused); `error` is the sanitised message.
+ */
+export type BranchSyncOutcome =
+  | { branch: string; outcome: 'updated'; from: string | null; to: string }
+  | { branch: string; outcome: 'up-to-date'; to: string }
+  | { branch: string; outcome: 'not-cloned' }
+  | { branch: string; outcome: 'remote-gone' }
+  | { branch: string; outcome: 'conflict'; conflictedPaths: string[]; error: string }
+  | { branch: string; outcome: 'error'; error: string };

package/src/workspace/access-verbs.ts

@@ -0,0 +1,124 @@
+/**
+ * The access verbs and the ONE dependency graph between them.
+ *
+ * Shared so that everything that folds verbs — the resolver in core-backend,
+ * the eligible lists it serves, and the share dialog in core-frontend that
+ * renders and edits them — reads the same table. A second fold written out by
+ * hand somewhere else is how the sheet comes to show "Owner" for someone the
+ * resolver refuses, or writes a `read:` line under an `owner:` it just granted.
+ *
+ * `read` controls who may VIEW a path. It is default-deny: a path with no
+ * effective grant of any verb is not readable. `write` is editing (and, with
+ * it, approval rights), `download` is saving a copy, `owner` is the contact
+ * point for the node and the right to manage its access.
+ */
+
+/**
+ * Verbs an `access.md` frontmatter can grant, each a list of principals
+ * optionally prefixed with `deny `. `AccessFile.entries` in the backend is
+ * statically keyed on this union; keep `Verb` and `KNOWN_VERBS` in lockstep.
+ */
+export const KNOWN_VERBS = ['read', 'write', 'download', 'owner'] as const;
+export type Verb = (typeof KNOWN_VERBS)[number];
+
+/**
+ * THE DEPENDENCY GRAPH — what holding each verb presupposes, declared once.
+ * `owner` presupposes `write` and `download`; `write` and `download` each
+ * presuppose `read`; `read` presupposes nothing. Everything about how verbs
+ * fold into one another is DERIVED from this table, in both directions:
+ *
+ *   - a GRANT confers, downwards, every verb the granted one presupposes
+ *     (`sourceVerbsFor`, `effectiveVerbs`): an owner may edit, save and open;
+ *     an editor may open; someone trusted with a copy may open it;
+ *   - a DENIAL strips, upwards, every verb that presupposes the denied one
+ *     (`requiredVerbsFor`): nobody owns what they may not edit, and nobody
+ *     edits or saves what they may not open.
+ *
+ * Neither converse is implied: a `deny write` says nothing about `read`, and a
+ * `read` grant confers no `write`. `write` and `download` are independent of
+ * each other. Add a verb, or change what one presupposes, HERE and nowhere
+ * else; every list and fold below follows.
+ */
+export const VERB_REQUIRES: Readonly<Record<Verb, readonly Verb[]>> = {
+  read: [],
+  write: ['read'],
+  download: ['read'],
+  owner: ['write', 'download'],
+};
+
+/** `verb` and everything it presupposes, transitively. */
+function presupposedBy(verb: Verb): ReadonlySet<Verb> {
+  const out = new Set<Verb>();
+  const visit = (v: Verb) => {
+    if (out.has(v)) return;
+    out.add(v);
+    for (const dep of VERB_REQUIRES[v]) visit(dep);
+  };
+  visit(verb);
+  return out;
+}
+
+/**
+ * Verbs whose GRANT confers `verb`, target verb first: `verb` itself, then
+ * every verb that presupposes it, in `KNOWN_VERBS` order.
+ */
+export function sourceVerbsFor(verb: Verb): Verb[] {
+  return [verb, ...KNOWN_VERBS.filter((v) => v !== verb && presupposedBy(v).has(verb))];
+}
+
+/**
+ * Verbs whose DENIAL strips `verb`, target verb first: `verb` itself, then
+ * every verb it presupposes, in `KNOWN_VERBS` order.
+ */
+export function requiredVerbsFor(verb: Verb): Verb[] {
+  const needs = presupposedBy(verb);
+  return [verb, ...KNOWN_VERBS.filter((v) => v !== verb && needs.has(v))];
+}
+
+/**
+ * The verbs in the order a change to a principal's set has to be APPLIED:
+ * broadest first, so every verb comes before the verbs it presupposes (ties in
+ * `KNOWN_VERBS` order). Lowering must start at the top — denying `write` while
+ * an `owner:` grant still stands in the same file is refused as ineffective,
+ * since owner confers write; stripping owner first removes what was conferring
+ * it. Raising reads the same order for the opposite reason: granting `owner`
+ * first satisfies the rest in one line.
+ */
+export const VERBS_BROADEST_FIRST: readonly Verb[] = [...KNOWN_VERBS].sort(
+  (a, b) =>
+    presupposedBy(b).size - presupposedBy(a).size || KNOWN_VERBS.indexOf(a) - KNOWN_VERBS.indexOf(b),
+);
+
+/** One flag per verb: what a principal holds, or what a form has ticked. */
+export type VerbSet = Record<Verb, boolean>;
+/** A partial set — flags left out read as not held. */
+export type VerbFlags = Partial<Record<Verb, boolean>>;
+
+/**
+ * The grant fold, as a whole set: what a principal EFFECTIVELY holds given the
+ * verbs they are granted. Each verb is held when it, or any verb that
+ * presupposes it, is in `held`. Idempotent on an already-folded set.
+ */
+export function effectiveVerbs(held: VerbFlags): VerbSet {
+  const out = {} as VerbSet;
+  for (const verb of KNOWN_VERBS) out[verb] = sourceVerbsFor(verb).some((w) => held[w] === true);
+  return out;
+}
+
+/**
+ * True when some OTHER verb in `held` confers `verb` — it is implied, not
+ * chosen, which is what a form renders as checked-and-disabled.
+ */
+export function conferredByOthers(held: VerbFlags, verb: Verb): boolean {
+  return sourceVerbsFor(verb).some((w) => w !== verb && held[w] === true);
+}
+
+/**
+ * The fewest grant lines that produce `held`: every held verb that no other
+ * held verb confers, broadest first. `{ owner }` is one line; `{ write, read,
+ * download }` is `write` and `download` (read rides on either); `{ read,
+ * download }` is `download` alone. A flag left out is not granted.
+ */
+export function minimalGrantVerbs(held: VerbFlags): Verb[] {
+  return VERBS_BROADEST_FIRST.filter((verb) => held[verb] === true && !conferredByOthers(held, verb));
+}