@gitkraken/core-gitlens 0.6.0 → 0.7.0

package/dist/git/models/graph.js

@@ -1,29 +1,33 @@
+//#region ../git/src/models/graph.ts
 /**
- * Compact, host-computed flags for a commit/stash row, shipped instead of the bulky serialized
- * `contexts.row`/`contexts.avatar` blobs (which duplicated sha/message/repoPath already on the row).
- * The webview reconstructs the full webview-item contexts from these flags + row fields + repoPath.
- * Bit 0: reachable-from-HEAD (`+current`); Bit 1: unique-to-one-local-branch (`+unique`);
- * Bit 2: has-children — set ONLY on undo-eligible tip rows (active HEAD + worktree HEADs) that have a
- * child, to gate Undo Commit to leaf tips (undoing a commit other work is stacked on is unsafe). It is
- * NOT a general has-children signal: non-tip rows never carry it (the host only computes it for tips);
- * Bit 3: unpushed/ahead-of-upstream (`+unpublished`).
- * Bit 4: history-rewriteable (`+rewriteable`) — on the first-parent chain from HEAD up to (excluding)
- * the first merge commit, so a plain (non-`--rebase-merges`) interactive rebase can safely rewrite it;
- * gates squash/drop/reword/modify. Strictly narrower than `+current` (reachable-from-HEAD includes a
- * merge's other-parent ancestry, which is NOT safely rewriteable).
- * Bit 5: unpulled/behind-the-upstream — the exact mirror of bit 3: on HEAD's upstream tip but NOT on HEAD
- * (i.e. `HEAD..@{u}`). Drives the graph's read-only unpulled indicator; it has no `webviewItem` segment
- * (no command gates on it). Mutually exclusive with `Unpublished` by construction.
- * (`+HEAD` derives from `row.heads[].isCurrentHead`; contributor `+current` from `row.isCurrentUser`.)
- */
-export var GitGraphRowContextFlags;
-(function (GitGraphRowContextFlags) {
-    GitGraphRowContextFlags[GitGraphRowContextFlags["None"] = 0] = "None";
-    GitGraphRowContextFlags[GitGraphRowContextFlags["ReachableFromHead"] = 1] = "ReachableFromHead";
-    GitGraphRowContextFlags[GitGraphRowContextFlags["UniqueToBranch"] = 2] = "UniqueToBranch";
-    GitGraphRowContextFlags[GitGraphRowContextFlags["HasChildren"] = 4] = "HasChildren";
-    GitGraphRowContextFlags[GitGraphRowContextFlags["Unpublished"] = 8] = "Unpublished";
-    GitGraphRowContextFlags[GitGraphRowContextFlags["RewriteableFromHead"] = 16] = "RewriteableFromHead";
-    GitGraphRowContextFlags[GitGraphRowContextFlags["Unpulled"] = 32] = "Unpulled";
-})(GitGraphRowContextFlags || (GitGraphRowContextFlags = {}));
+* Compact, host-computed flags for a commit/stash row, shipped instead of the bulky serialized
+* `contexts.row`/`contexts.avatar` blobs (which duplicated sha/message/repoPath already on the row).
+* The webview reconstructs the full webview-item contexts from these flags + row fields + repoPath.
+* Bit 0: reachable-from-HEAD (`+current`); Bit 1: unique-to-one-local-branch (`+unique`);
+* Bit 2: has-children — set ONLY on undo-eligible tip rows (active HEAD + worktree HEADs) that have a
+* child, to gate Undo Commit to leaf tips (undoing a commit other work is stacked on is unsafe). It is
+* NOT a general has-children signal: non-tip rows never carry it (the host only computes it for tips);
+* Bit 3: unpushed/ahead-of-upstream (`+unpublished`).
+* Bit 4: history-rewriteable (`+rewriteable`) — on the first-parent chain from HEAD up to (excluding)
+* the first merge commit, so a plain (non-`--rebase-merges`) interactive rebase can safely rewrite it;
+* gates squash/drop/reword/modify. Strictly narrower than `+current` (reachable-from-HEAD includes a
+* merge's other-parent ancestry, which is NOT safely rewriteable).
+* Bit 5: unpulled/behind-the-upstream — the exact mirror of bit 3: on HEAD's upstream tip but NOT on HEAD
+* (i.e. `HEAD..@{u}`). Drives the graph's read-only unpulled indicator; it has no `webviewItem` segment
+* (no command gates on it). Mutually exclusive with `Unpublished` by construction.
+* (`+HEAD` derives from `row.heads[].isCurrentHead`; contributor `+current` from `row.isCurrentUser`.)
+*/
+let GitGraphRowContextFlags = /* @__PURE__ */ function(GitGraphRowContextFlags) {
+	GitGraphRowContextFlags[GitGraphRowContextFlags["None"] = 0] = "None";
+	GitGraphRowContextFlags[GitGraphRowContextFlags["ReachableFromHead"] = 1] = "ReachableFromHead";
+	GitGraphRowContextFlags[GitGraphRowContextFlags["UniqueToBranch"] = 2] = "UniqueToBranch";
+	GitGraphRowContextFlags[GitGraphRowContextFlags["HasChildren"] = 4] = "HasChildren";
+	GitGraphRowContextFlags[GitGraphRowContextFlags["Unpublished"] = 8] = "Unpublished";
+	GitGraphRowContextFlags[GitGraphRowContextFlags["RewriteableFromHead"] = 16] = "RewriteableFromHead";
+	GitGraphRowContextFlags[GitGraphRowContextFlags["Unpulled"] = 32] = "Unpulled";
+	return GitGraphRowContextFlags;
+}({});
+//#endregion
+export { GitGraphRowContextFlags };
+
 //# sourceMappingURL=graph.js.map

package/dist/git/models/graph.js.map

@@ -1 +1 @@
-{"version":3,"file":"graph.js","sourceRoot":"","sources":["../../../src/git/models/graph.ts"],"names":[],"mappings":"AA2EA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAN,IAAkB,uBAQjB;AARD,WAAkB,uBAAuB;IACxC,qEAAQ,CAAA;IACR,+FAA0B,CAAA;IAC1B,yFAAuB,CAAA;IACvB,mFAAoB,CAAA;IACpB,mFAAoB,CAAA;IACpB,oGAA4B,CAAA;IAC5B,8EAAiB,CAAA;AAClB,CAAC,EARiB,uBAAuB,KAAvB,uBAAuB,QAQxC"}
+{"version":3,"file":"graph.js","names":[],"sources":["../../../../git/src/models/graph.ts"],"sourcesContent":["import type { GitCommitReachability } from '../providers/commits.js';\nimport type { GitBranch } from './branch.js';\nimport type { GitStashCommit } from './commit.js';\nimport type { GitRemote } from './remote.js';\nimport type { GkProviderId } from './repositoryIdentities.js';\nimport type { GitWorktree } from './worktree.js';\n\nexport type GitGraphRowKind = 'commit' | 'merge' | 'stash' | 'workdir';\n\nexport interface GitGraphRowHead {\n\t/**\n\t * Stable ref id. **Its presence is the provider-tier marker** — the one signal separating a ref that\n\t * can be acted on from a lean, name-only one, now that neither carries a serialized context.\n\t *\n\t * The CLI provider stamps an id on every ref it emits (`git-cli/providers/graph.ts:781`, `:805`,\n\t * `:836`); the GitHub provider never does, because it has no branch metadata to key\n\t * (`git-github/providers/github/graph.ts:231`, `:239`). So `id == null` means \"this ref came from a\n\t * provider that computes nothing beyond a name\", and every id-keyed feature — ref metadata, exclusions,\n\t * pinning, PR/issue lookup — must degrade rather than guess. Consumers already do this; it is written\n\t * down here because until now it was an accident of two providers rather than a stated contract.\n\t *\n\t * ⚠ An id means the ref is **identifiable and actionable** — it does NOT mean its enrichment is\n\t * complete. The CLI resolves branches, remotes and worktrees with `Promise.allSettled`\n\t * (`git-cli/providers/graph.ts:546`) and still synthesizes ids when any of those settle rejected, so an\n\t * id-bearing ref can carry a missing `starred`/`upstream` that means \"not computed\" rather than \"no\".\n\t * Treat every optional field as enrichment that may be absent, and never report a capability from its\n\t * absence. If a consumer ever needs to tell \"unavailable\" from \"false\", that wants one graph-level\n\t * completeness flag, not a per-ref field on every row.\n\t */\n\tid?: string;\n\tname: string;\n\tisCurrentHead: boolean;\n\t/**\n\t * The tracked upstream. `missing`/`state` are optional here while {@link GitTrackingUpstream} makes\n\t * them required, and the difference is meaningful: absent means the producer did NOT compute them\n\t * (the GitHub provider has no branch metadata at all), NOT \"present and false/zero\". Consumers must\n\t * treat `undefined` as unknown rather than folding it into the negative case.\n\t */\n\tupstream?: { name: string; id: string; missing?: boolean; state?: { ahead: number; behind: number } };\n\t/** Starred (a GitKraken branch disposition). Structured so `+starred` stops being baked into the\n\t *  serialized context at row-build time, where starring a branch left the label stale. */\n\tstarred?: boolean;\n\t/** Set when this branch is checked out in ANY worktree, including the default one. Grouped so\n\t *  producers can't half-populate id-without-path or vice versa. Consumers that mean \"checked out\n\t *  somewhere other than here\" — the ref-ordering tier and the worktree glyph — must test\n\t *  `isDefault` too; the default worktree's checkout is the ordinary case, not a worktree badge.\n\t *  Note `isDefault` here describes the WORKTREE; the sibling `isDefault` below describes the BRANCH. */\n\tworktree?: { id: string; path: string; isDefault: boolean };\n\t/** True when this head is the repository's default branch. */\n\tisDefault?: boolean;\n}\n\nexport interface GitGraphRowRemoteHead {\n\t/** Stable ref id; see {@link GitGraphRowHead.id} — its presence is the provider-tier marker. */\n\tid?: string;\n\tname: string;\n\turl?: string;\n\towner: string;\n\tavatarUrl?: string;\n\tcurrent?: boolean;\n\t/** True when this remote ref IS the repository's default branch and no local branch tracks it (no\n\t *  local checkout) — so the default-branch tier still applies for remote-only defaults. */\n\tisDefault?: boolean;\n\thostingServiceType?: GkProviderId;\n\t/** See {@link GitGraphRowHead.starred}. */\n\tstarred?: boolean;\n}\n\nexport interface GitGraphRowTag {\n\t/** Stable ref id; see {@link GitGraphRowHead.id} — its presence is the provider-tier marker. */\n\tid?: string;\n\tname: string;\n\tannotated: boolean;\n}\n\n/**\n * Compact, host-computed flags for a commit/stash row, shipped instead of the bulky serialized\n * `contexts.row`/`contexts.avatar` blobs (which duplicated sha/message/repoPath already on the row).\n * The webview reconstructs the full webview-item contexts from these flags + row fields + repoPath.\n * Bit 0: reachable-from-HEAD (`+current`); Bit 1: unique-to-one-local-branch (`+unique`);\n * Bit 2: has-children — set ONLY on undo-eligible tip rows (active HEAD + worktree HEADs) that have a\n * child, to gate Undo Commit to leaf tips (undoing a commit other work is stacked on is unsafe). It is\n * NOT a general has-children signal: non-tip rows never carry it (the host only computes it for tips);\n * Bit 3: unpushed/ahead-of-upstream (`+unpublished`).\n * Bit 4: history-rewriteable (`+rewriteable`) — on the first-parent chain from HEAD up to (excluding)\n * the first merge commit, so a plain (non-`--rebase-merges`) interactive rebase can safely rewrite it;\n * gates squash/drop/reword/modify. Strictly narrower than `+current` (reachable-from-HEAD includes a\n * merge's other-parent ancestry, which is NOT safely rewriteable).\n * Bit 5: unpulled/behind-the-upstream — the exact mirror of bit 3: on HEAD's upstream tip but NOT on HEAD\n * (i.e. `HEAD..@{u}`). Drives the graph's read-only unpulled indicator; it has no `webviewItem` segment\n * (no command gates on it). Mutually exclusive with `Unpublished` by construction.\n * (`+HEAD` derives from `row.heads[].isCurrentHead`; contributor `+current` from `row.isCurrentUser`.)\n */\nexport const enum GitGraphRowContextFlags {\n\tNone = 0,\n\tReachableFromHead = 1 << 0,\n\tUniqueToBranch = 1 << 1,\n\tHasChildren = 1 << 2,\n\tUnpublished = 1 << 3,\n\tRewriteableFromHead = 1 << 4,\n\tUnpulled = 1 << 5,\n}\n\n/** Context data attached to graph rows for command/menu handling. */\nexport interface GitGraphRowContexts {\n\t/** Compact replacement for the serialized commit `row`/`avatar` contexts; see {@link GitGraphRowContextFlags}. */\n\tflags?: GitGraphRowContextFlags;\n\t/**\n\t * Index into the per-graph `GraphReachabilityTable.sets` for this row's reachable-refs set,\n\t * shipped instead of the per-row `reachability` object (which dominated the graph payload). The\n\t * webview rebuilds `row.reachability` from the shared table. Absent ⇒ no reachability for this row.\n\t */\n\treachabilityIndex?: number;\n\t/** Serialized right-click context. Built here only for stash rows; commit rows ship {@link flags}\n\t *  instead and have theirs rebuilt on demand (see `rowContext.utils`). */\n\trow?: string | object;\n\t/** Serialized context per grouped-ref name, for the group's own menu. */\n\trefGroups?: Record<string, string | object>;\n}\n\nexport interface GitGraphRowStats {\n\tfiles: number;\n\tadditions: number;\n\tdeletions: number;\n}\n\n/**\n * Wire encoding for per-row reachability, shipped once per graph payload instead of inline on every\n * row. Git reachability is monotone (adjacent commits share ref-sets), so the rows collapse to a\n * relatively small number of distinct sets over the repo's ref universe — `dictionary` (the shared\n * ref list) + `sets` (distinct membership bitmaps, base64; bit i ⇒ `dictionary[i]` reachable) + a\n * per-row index (`GitGraphRowContexts.reachabilityIndex`) reconstructs every row's `reachability`\n * client-side for a fraction of the bytes the inline objects cost. `current` is a per-ref property\n * (the checked-out HEAD branch) and lives in the dictionary entry.\n *\n * The table is append-only within a graph generation, so the host ships only the entries appended\n * since its last push (a delta) on same-generation pagination and the full table on a new generation;\n * `id` lets the webview tell the two apart (same `id` ⇒ append the delta, new `id` ⇒ replace + reset\n * its decode cache). A fresh `getGraph` walk mints a new `id`; `more()` keeps the same one.\n */\nexport interface GraphReachabilityTable {\n\t/** Generation id — stable across `more()` pagination, new per fresh graph walk. */\n\treadonly id: number;\n\treadonly dictionary: GitCommitReachability['refs'];\n\t/** Distinct ref-membership bitmaps, base64-encoded `Uint8Array` of `ceil(dictionary.length/8)` bytes. */\n\treadonly sets: string[];\n}\n\n/** Library-owned graph row type. */\nexport interface GitGraphRow {\n\tsha: string;\n\tparents: string[];\n\tauthor: string;\n\temail: string;\n\tdate: number;\n\tcommitDate?: number;\n\tmessage: string;\n\tkind: GitGraphRowKind;\n\theads?: GitGraphRowHead[];\n\tremotes?: GitGraphRowRemoteHead[];\n\ttags?: GitGraphRowTag[];\n\tcontexts?: GitGraphRowContexts;\n\tstats?: GitGraphRowStats;\n\t/** Stash rows only: the `{n}` of `stash@{n}`, so consumers stop parsing it back out of the message. */\n\tstashNumber?: string;\n\t/**\n\t * Transient, set only for the duration of {@link GraphRowProcessor.processRow} (the row processor's\n\t * `+unique` decision reads it). The provider strips it before pushing the row and records the\n\t * reachable-ref set into the shared {@link GitGraph.reachability} table instead (see\n\t * {@link GitGraphRowContexts.reachabilityIndex}), so emitted rows do NOT retain the per-row arrays.\n\t */\n\treachability?: GitCommitReachability;\n\tisCurrentUser?: boolean;\n}\n\nexport interface GitGraph {\n\treadonly repoPath: string;\n\t/** A map of all avatar urls */\n\treadonly avatars: Map<string, string>;\n\t/** A set of all \"seen\" commit ids */\n\treadonly ids: Set<string>;\n\treadonly includes: { stats?: boolean } | undefined;\n\treadonly branches: ReadonlyMap<string, GitBranch>;\n\treadonly remotes: ReadonlyMap<string, GitRemote>;\n\treadonly downstreams: ReadonlyMap<string, string[]>;\n\treadonly stashes: ReadonlyMap<string, GitStashCommit> | undefined;\n\treadonly worktrees: ReadonlyArray<GitWorktree> | undefined;\n\treadonly worktreesByBranch: ReadonlyMap<string, GitWorktree> | undefined;\n\n\t/** SHAs reachable from HEAD (for enrichment: marking commits on the current branch) */\n\treadonly reachableFromHEAD?: ReadonlySet<string>;\n\n\t/**\n\t * Ref tips as of this walk: canonical refname (`refs/heads/…`, `refs/remotes/…`, `refs/tags/…`) →\n\t * PEELED tip sha (annotated tags map to the commit their badge sits on). Captured so the host can seed\n\t * the NEXT rebuild's {@link GraphIncrementalSeed.tips} — the map the R6b fast path diffs against to find\n\t * the structural changes that force a full fallback. The CLI provider populates it on both paths (full\n\t * walk + fast path); the GitHub provider leaves it undefined.\n\t */\n\treadonly refTips?: ReadonlyMap<string, string>;\n\n\t/**\n\t * Fingerprint of every SIDE INPUT row construction embeds into row decorations as of this walk —\n\t * default branch, per-branch upstreams, HEAD's upstream, remote urls/providers, worktree assignments,\n\t * and the current user. These can all change WITHOUT moving any ref tip (`git remote set-head`,\n\t * `branch --set-upstream-to`, `worktree add`, remote/user config edits), and the R6b fast path reuses\n\t * prior rows wholesale (only flags/reachability are re-derived) — so it must compare this against the\n\t * seed's and fall back to a full walk on ANY change. The CLI provider populates it on both paths; the\n\t * GitHub provider leaves it undefined.\n\t */\n\treadonly decorationFingerprint?: string;\n\n\t/** Canonical shallow boundary OIDs for this window. Empty means complete history; undefined means\n\t *  unknown (or unsupported by the provider), so a CLI refresh cannot reuse ancestry-dependent data. */\n\treadonly shallowBoundary?: string;\n\n\t/**\n\t * SHAs on the first-parent chain from HEAD up to (excluding) the first merge commit — i.e. the\n\t * commits a plain interactive rebase can safely rewrite. Empty when HEAD itself is a merge. Used by\n\t * the graph's history-rewriting commands (squash/drop/reword/modify) to validate selections.\n\t */\n\treadonly rewriteableFromHEAD?: ReadonlySet<string>;\n\n\t/**\n\t * Shared, append-only reachability table for the loaded rows (the primary representation — rows\n\t * carry only a {@link GitGraphRowContexts.reachabilityIndex} into it, not per-row ref arrays).\n\t * Grows monotonically across {@link more} pagination within a graph session: indices already\n\t * assigned never change, so consumers can decode any row on demand and cache by index. Absent ⇒\n\t * no row in the graph has reachability. See {@link GraphReachabilityTable}.\n\t */\n\treadonly reachability?: GraphReachabilityTable;\n\n\t/** The rows for the set of commits requested */\n\treadonly rows: GitGraphRow[];\n\treadonly id?: string;\n\n\treadonly rowsStats?: GitGraphRowsStats;\n\treadonly rowsStatsDeferred?: { isLoaded: () => boolean; promise: Promise<void> };\n\n\treadonly paging?: {\n\t\treadonly limit: number | undefined;\n\t\treadonly startingCursor: string | undefined;\n\t\treadonly hasMore: boolean;\n\t};\n\n\t/**\n\t * Loads more commits for the graph.\n\t *\n\t * @param limit - The number of commits to load (page size)\n\t * @param id - Optional SHA to find\n\t * @param cancellation - Cancellation token\n\t *\n\t * **Behavior based on parameters:**\n\t *\n\t * - **`id` provided + `limit > 0`**: Find the commit with the given SHA, then ensure at least `limit` commits are loaded.\n\t *   - If SHA is found early (e.g., at position 100), continues loading to reach `limit` total commits.\n\t *   - If SHA is found late (e.g., at position 2000 when limit is 1000), loads all commits up to and including the SHA.\n\t *   - This ensures the target commit is included AND provides a full page of context.\n\t *\n\t * - **`id` provided + `limit === 0`**: Find the commit with the given SHA and stop immediately.\n\t *   - Loads only as many commits as needed to reach the target SHA.\n\t *   - Used when you want to find a specific commit without loading extra commits.\n\t *\n\t * - **No `id` + `limit > 0`**: Load exactly `limit` commits (normal pagination).\n\t *   - Standard page-based loading without a specific target.\n\t *\n\t * - **No `id` + `limit === 0`**: Load all remaining commits.\n\t *   - Loads everything from the current position to the end of history.\n\t *   - Use with caution as this can load a large number of commits.\n\t *\n\t * @example\n\t * // Load next page of 1000 commits\n\t * await graph.more(1000);\n\t *\n\t * @example\n\t * // Find a specific commit and ensure a full page is loaded\n\t * await graph.more(1000, 'abc123');\n\t *\n\t * @example\n\t * // Find a specific commit and stop (minimal loading)\n\t * await graph.more(0, 'abc123');\n\t */\n\tmore?(limit: number, id?: string, cancellation?: AbortSignal): Promise<GitGraph | undefined>;\n}\n\nexport type GitGraphRowsStats = Map<string, GitGraphRowStats>;\n\n/**\n * Seed for the R6b incremental head-walk fast path. Carries the prior generation's walk artifacts so a\n * repo-change rebuild can walk ONLY the changed head region, stitch the cached tail, and re-derive\n * flags/reachability in memory — instead of re-walking every loaded row.\n *\n * The CLI provider consumes this on its incremental fast path, degrading to the full ordered walk\n * whenever any gate below rejects the seed. The GitHub provider ignores it structurally (it never\n * lists the option).\n */\nexport interface GraphIncrementalSeed {\n\t/**\n\t * Prior generation's emitted rows, in walk order. R6b stitches the unchanged tail from these once the\n\t * streamed head region CONVERGES with them (K consecutive shas aligned at a stable offset), and reads\n\t * their parent lists to re-derive reachability/flags in memory (no git) over the stitched window.\n\t */\n\treadonly rows: readonly GitGraphRow[];\n\t/**\n\t * Ref tips as of the prior walk: canonical refname (e.g. `refs/heads/main`, `refs/remotes/origin/main`,\n\t * `refs/tags/v1`) → tip sha. R6b enumerates the new commits via `git log --all --not <these shas>`\n\t * (cheap, exact) and diffs this map against the current tips to detect the structural changes that force\n\t * a full fallback: any ref DELETION (key gone) or a NON-fast-forward move (old tip not an ancestor of the\n\t * new tip).\n\t */\n\treadonly tips: ReadonlyMap<string, string>;\n\t/**\n\t * Ordering the prior rows were walked in. The convergence + date-boundary reasoning R6b relies on is only\n\t * sound for `date` order in v1; a seed whose ordering is `author-date`/`topo`, or that disagrees with the\n\t * current walk's ordering, is discarded (full fallback).\n\t */\n\treadonly ordering: 'date' | 'author-date' | 'topo';\n\t/**\n\t * Prior generation's reachability table, to CONTINUE (same role as the sub-provider's `reachabilitySeed`)\n\t * so rows retained across the rebuild keep stable {@link GitGraphRowContexts.reachabilityIndex} values and\n\t * only appended entries ship. R6b decides whether the stitched window extends this builder or needs a\n\t * fresh generation; see `createReachabilityTableBuilder`.\n\t */\n\treadonly reachability?: GraphReachabilityTable;\n\t/**\n\t * Prior generation's per-sha stats. With unchanged ancestry the deferred query recomputes only new\n\t * shas; shallow-boundary or replacement changes invalidate the seed — same role as `rowsStatsSeed`.\n\t */\n\treadonly rowsStats?: GitGraphRowsStats;\n\t/**\n\t * Whether the prior generation had more rows below its loaded window (`paging.hasMore`). The fast path\n\t * can only reconstruct rows the seed carries; when the seed was a partial (paged) load and no new commit\n\t * pushes the window past its limit, `hasMore` must still be reported so the caller keeps paging. Absent ⇒\n\t * treated as `false` (the seed loaded the full history).\n\t */\n\treadonly hasMore?: boolean;\n\t/**\n\t * The `graph.onlyFollowFirstParent` setting the prior rows were walked under. When first-parent is on the\n\t * emitted rows carry sliced (first-parent-only) parents, which the in-memory re-derivation can't expand\n\t * back to the full parent set the walk propagates reachability through — so a seed built under (or a\n\t * current config of) first-parent forces a full fallback. Absent ⇒ treated as `false`.\n\t */\n\treadonly onlyFollowFirstParent?: boolean;\n\t/** The prior window's shallow boundary. Compare contents, since partial deepening stays shallow. */\n\treadonly shallowBoundary?: string;\n\t/**\n\t * {@link GitGraph.decorationFingerprint} of the prior walk. R6b falls back to a full walk on ANY change:\n\t * reused rows keep their embedded decorations (upstream/worktree/default/remote/user metadata), so a\n\t * metadata-only change — one that moves no ref tip — would otherwise ship stale pills indefinitely.\n\t * Optional because providers without the incremental machinery (e.g. GitHub) never populate it; absent ⇒\n\t * never matches ⇒ safe full fallback.\n\t */\n\treadonly decorationFingerprint?: string;\n\t/**\n\t * HEAD's tracking upstream (e.g. `origin/main`) as of the prior walk — carried separately from\n\t * {@link decorationFingerprint} so a session REBIND can neutralize it: moving HEAD to another\n\t * worktree's branch changes the fingerprint even though nothing in the repo did, so recomputing the\n\t * seed-comparable fingerprint from this value (old repoPath, everything else current) cancels exactly\n\t * that perspective move. Sound because it feeds only `remotes[].current` on a reused row, which the\n\t * rebind re-derives in memory. Absent compares as \"no upstream\", so an older seed with a real upstream\n\t * compares unequal ⇒ safe full fallback.\n\t */\n\treadonly headRefUpstreamName?: string;\n}\n\n/**\n * Which path a seeded {@link GitGraphSubProvider.getGraph} call took: the R6b incremental head-walk fast\n * path, or a full ordered walk (with the gate/boundary `reason` that forced it). Reported via the\n * `onIncrementalResult` option so the host can log it and the equivalence harness can assert it. Purely\n * observational — it never changes the returned graph.\n */\nexport interface IncrementalGraphOutcome {\n\treadonly path: 'fast' | 'fallback';\n\treadonly reason?: IncrementalGraphFallbackReason;\n\t/** Fast path only: how many NEW commit rows the incremental enumeration added at the head. */\n\treadonly added?: number;\n}\n\nexport type IncrementalGraphFallbackReason =\n\t| 'no-row-processor'\n\t| 'ordering-not-date'\n\t| 'rev-outside-seed'\n\t| 'first-parent'\n\t| 'limit-exceeds-seed'\n\t| 'ref-deleted'\n\t| 'ref-non-fast-forward'\n\t| 'replace-refs-changed'\n\t| 'shallow-changed'\n\t| 'stash-changed'\n\t| 'stash-window-conflict'\n\t| 'date-boundary'\n\t// A decoration side input changed without moving any ref tip (default branch, an upstream, a worktree\n\t// assignment, a remote's url/provider, the current user) — reused rows would keep stale embedded\n\t// decorations, so the walk must rebuild them. See `GitGraph.decorationFingerprint`.\n\t| 'metadata-changed'\n\t// The fast path threw (spawn/arg limits on huge ref sets, queue overflow, transient git errors) —\n\t// never an eligibility gate. The fast path must never fail where the full walk it accelerates\n\t// would succeed, so any unexpected error degrades to the full walk (cancellation still propagates).\n\t| 'error';\n\n/**\n * Processes a single graph row — mutates the row in place.\n *\n * Sets `row.contexts` and `row.message` (e.g., emojified), and resolves `remoteHead.avatarUrl`.\n * Also populates `context.avatars` with email → URL mappings.\n *\n * Per-ref contexts are NOT serialized here. The webview builds them from the structured ref fields\n * (`webviews/apps/plus/graph/utils/refContext.utils.ts`), where live state the host would have baked in\n * stale — whether a branch is starred, which ref is pinned — is actually visible. What remains here needs\n * something the webview cannot reach: the extension's asset URIs, or the whole-row grouping.\n *\n * Called inline during graph row iteration in the library's row-building\n * loop, once per row. Because it runs inside the loop, `more()` pagination\n * automatically gets processing for free — no wrapping needed.\n */\nexport interface GraphRowProcessor {\n\tprocessRow(row: GitGraphRow, context: GraphContext): void;\n\t/**\n\t * Rebuild a reused row's HOST-SERIALIZED contexts (`contexts.refGroups`, a stash row's `contexts.row`)\n\t * for a session rebind. The row's ref ids are already re-stamped by the walk (`restampGraphRowIds`)\n\t * before this runs — since this processor is optional, implementations must read ids as already\n\t * correct and must NOT touch them again, nor message/author (not idempotent).\n\t */\n\trestampRow?(row: GitGraphRow, context: GraphContext): void;\n}\n\nexport interface GraphContext {\n\treadonly repoPath: string;\n\treadonly useAvatars: boolean;\n\treadonly branches: ReadonlyMap<string, GitBranch>;\n\treadonly remotes: ReadonlyMap<string, GitRemote>;\n\treadonly worktreesByBranch: ReadonlyMap<string, GitWorktree> | undefined;\n\treadonly branchIdOfMainWorktree: string | undefined;\n\treadonly stashes: ReadonlyMap<string, GitStashCommit> | undefined;\n\treadonly reachableFromHEAD: ReadonlySet<string>;\n\t/** SHAs on the first-parent chain from HEAD up to (excluding) the first merge commit — the commits\n\t *  a plain interactive rebase can safely rewrite. Empty when HEAD is a merge. Sets the\n\t *  {@link GitGraphRowContextFlags.RewriteableFromHead} flag, gating squash/drop/reword/modify. */\n\treadonly rewriteableFromHEAD: ReadonlySet<string>;\n\t/** The subset of undo-eligible tip shas (active HEAD + worktree HEADs) that have at least one\n\t *  child — i.e. are NOT leaves. Scoped to tips (not all commits) for performance; do not treat as\n\t *  a general has-children signal. Sets the {@link GitGraphRowContextFlags.HasChildren} flag, which\n\t *  gates Undo Commit to leaf tips. */\n\treadonly tipShasWithChildren: ReadonlySet<string>;\n\t/** SHAs reachable from HEAD's tracking-upstream tip, or `undefined` when HEAD has no upstream.\n\t * A commit reachable from HEAD but NOT from this set is unpushed (`+unpublished`); `undefined`\n\t * means there's no upstream to be ahead of, so nothing is flagged. */\n\treadonly reachableFromHeadUpstream: ReadonlySet<string> | undefined;\n\treadonly avatars: Map<string, string>;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AA6FA,IAAkB,0BAAX,yBAAA,yBAAA;CACN,wBAAA,wBAAA,UAAA,KAAA;CACA,wBAAA,wBAAA,uBAAA,KAAA;CACA,wBAAA,wBAAA,oBAAA,KAAA;CACA,wBAAA,wBAAA,iBAAA,KAAA;CACA,wBAAA,wBAAA,iBAAA,KAAA;CACA,wBAAA,wBAAA,yBAAA,MAAA;CACA,wBAAA,wBAAA,cAAA,MAAA;;AACD,EAAA,CAAA,CAAA"}

package/dist/git/models/graphSearch.d.ts

@@ -1,48 +1,50 @@
-import type { SearchQuery, SearchQueryFilters } from './search.js';
+import { SearchQuery, SearchQueryFilters } from "./search.js";
+//#region ../git/src/models/graphSearch.d.ts
 export interface GitGraphSearchResultData {
-    readonly date: number;
-    readonly i: number;
-    readonly files?: ReadonlyArray<Readonly<{
-        readonly path: string;
-    }>>;
+  readonly date: number;
+  readonly i: number;
+  readonly files?: ReadonlyArray<Readonly<{
+    readonly path: string;
+  }>>;
 }
 export type GitGraphSearchResults = Map<string, GitGraphSearchResultData>;
 export interface GitGraphSearchProgress {
-    readonly repoPath: string;
-    readonly query: SearchQuery;
-    readonly queryFilters: SearchQueryFilters;
-    readonly comparisonKey: string;
-    /** Whether there are more results available beyond the current limit */
-    readonly hasMore: boolean;
-    /** New results since the last progress update */
-    readonly results: GitGraphSearchResults;
-    /** Total count of all results accumulated so far */
-    readonly runningTotal: number;
+  readonly repoPath: string;
+  readonly query: SearchQuery;
+  readonly queryFilters: SearchQueryFilters;
+  readonly comparisonKey: string;
+  /** Whether there are more results available beyond the current limit */
+  readonly hasMore: boolean;
+  /** New results since the last progress update */
+  readonly results: GitGraphSearchResults;
+  /** Total count of all results accumulated so far */
+  readonly runningTotal: number;
 }
 export interface CliGitGraphSearchCursorState {
-    readonly iterations: number;
-    readonly totalSeen: number;
-    readonly sha: string;
-    readonly skip: number;
+  readonly iterations: number;
+  readonly totalSeen: number;
+  readonly sha: string;
+  readonly skip: number;
 }
 export type GitGraphSearchCursorState = CliGitGraphSearchCursorState | string;
 export interface GitGraphSearchCursor {
-    readonly search: SearchQuery;
-    readonly state: GitGraphSearchCursorState;
+  readonly search: SearchQuery;
+  readonly state: GitGraphSearchCursorState;
 }
 export interface GitGraphSearch {
-    readonly repoPath: string;
-    readonly query: SearchQuery;
-    readonly queryFilters: SearchQueryFilters;
-    readonly comparisonKey: string;
-    /** Whether there are more results available beyond the current limit */
-    readonly hasMore: boolean;
-    /** Complete set of results up to the current limit */
-    readonly results: GitGraphSearchResults;
-    readonly paging?: {
-        readonly limit: number | undefined;
-        readonly cursor?: GitGraphSearchCursor;
-    };
-    more?(limit: number): Promise<GitGraphSearch>;
+  readonly repoPath: string;
+  readonly query: SearchQuery;
+  readonly queryFilters: SearchQueryFilters;
+  readonly comparisonKey: string;
+  /** Whether there are more results available beyond the current limit */
+  readonly hasMore: boolean;
+  /** Complete set of results up to the current limit */
+  readonly results: GitGraphSearchResults;
+  readonly paging?: {
+    readonly limit: number | undefined;
+    readonly cursor?: GitGraphSearchCursor;
+  };
+  more?(limit: number): Promise<GitGraphSearch>;
 }
+//#endregion
 //# sourceMappingURL=graphSearch.d.ts.map

package/dist/git/models/graphSearch.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=graphSearch.js.map

package/dist/git/models/graphSession.d.ts

@@ -1,4 +1,5 @@
-import type { GitGraph, GitGraphRow, IncrementalGraphFallbackReason } from './graph.js';
+import { GitGraph, GitGraphRow, IncrementalGraphFallbackReason } from "./graph.js";
+//#region ../git/src/models/graphSession.d.ts
 /**
  * A provider-owned, stateful graph window for a single repo. It is the canonical accumulated window and
  * the single builder of the incremental rebuild seed — the host no longer mirrors loaded rows, stamps
@@ -11,47 +12,70 @@ import type { GitGraph, GitGraphRow, IncrementalGraphFallbackReason } from './gr
  * and {@link current} mirrors today's `GitGraph` result shape so the publisher/wire semantics stay
  * byte-identical. R7b (refresh-result-driven channel marking) extends this without breaking —
  * {@link refresh} returns a result object, never a bare `GitGraph`.
+ *
+ * CONCURRENCY — the session is SINGLE-WRITER: {@link refresh}, {@link rebind} and {@link more} serialize
+ * in call order, so `repoPath` and every row in `window` always describe the last completed operation,
+ * never a torn mix of two. A page queued when a refresh/rebind REPLACES the window it targets is refused
+ * (`more` answers `'superseded'`) rather than spliced onto a cursor that no longer fits — see {@link more}.
+ *
+ * READS are not serialized: a caller that must not observe a half-rebuilt window gates its own read.
  */
 export interface GitGraphSession {
-    readonly repoPath: string;
-    /** Canonical accumulated window (the FULL loaded rows, never page-scoped after pagination). */
-    readonly window: readonly GitGraphRow[];
-    /**
-     * Last-operation view mirroring today's `GitGraph` result shape: page-scoped `rows` after a
-     * {@link more}, the full window after a {@link refresh}. Keeps the publisher's `getRows`/`getPaging`
-     * and every graph-level read (`branches`, `remotes`, `stashes`, `ids`, `avatars`, `rowsStats`, …)
-     * exactly as they read `_graph` today.
-     */
-    readonly current: GitGraph;
-    /**
-     * Re-walk the repo, accumulating the fresh full window. Internally seeds the incremental head-walk
-     * fast path from the prior window/tips/artifacts (same shape gating as the host did) and falls back
-     * to a full walk on any structural change; the result surfaces which path ran so a later stage can
-     * mark channels precisely.
-     */
-    refresh(options?: GitGraphSessionRefreshOptions, cancellation?: AbortSignal): Promise<GitGraphSessionRefreshResult>;
-    /**
-     * Page more rows into the window (accumulates; `current` becomes the page view). Returns `false` when
-     * there was nothing to add or a concurrent {@link refresh} superseded the page.
-     */
-    more(limit?: number, targetId?: string, cancellation?: AbortSignal): Promise<boolean>;
-    dispose(): void;
+  /** The CURRENT bound path — the repo the session was opened for, or the worktree it was last
+   *  {@link rebind}-ed onto. */
+  readonly repoPath: string;
+  /** Canonical accumulated window (the FULL loaded rows, never page-scoped after pagination). */
+  readonly window: readonly GitGraphRow[];
+  /**
+   * True while {@link window}/{@link current} are known CORRUPT from a walk that failed part-way through
+   * mutating them in place. Clears on the next (forced) rebuild. A caller that would SERVE these rows
+   * must check this first — reads bypass the write queue, so nothing else enforces it.
+   */
+  readonly tainted: boolean;
+  /**
+   * Last-operation view mirroring today's `GitGraph` result shape: page-scoped `rows` after a
+   * {@link more}, the full window after a {@link refresh}. Keeps the publisher's `getRows`/`getPaging`
+   * and every graph-level read (`branches`, `remotes`, `stashes`, `ids`, `avatars`, `rowsStats`, …)
+   * exactly as they read `_graph` today.
+   */
+  readonly current: GitGraph;
+  /**
+   * Re-walk the repo, accumulating the fresh full window. Internally seeds the incremental head-walk
+   * fast path from the prior window/tips/artifacts (same shape gating as the host did) and falls back
+   * to a full walk on any structural change; the result surfaces which path ran so a later stage can
+   * mark channels precisely.
+   */
+  refresh(options?: GitGraphSessionRefreshOptions, cancellation?: AbortSignal): Promise<GitGraphSessionRefreshResult>;
+  /**
+   * Page more rows into the window (accumulates; `current` becomes the page view). See
+   * {@link GitGraphSessionMoreResult} — a caller MUST distinguish `'superseded'` (retry) from `'none'`
+   * (don't).
+   */
+  more(limit?: number, targetId?: string, cancellation?: AbortSignal): Promise<GitGraphSessionMoreResult>;
+  /**
+   * Re-perspective the session onto another worktree of the SAME repo family without discarding
+   * the accumulated window. Rides the incremental fast path: unchanged tips, HEAD endpoints
+   * refetched, flags/reachability replayed, ref ids re-stamped to the new path. Falls back to a
+   * full walk only when a genuine structural/metadata change happened concurrently.
+   */
+  rebind(repoPath: string, cancellation?: AbortSignal): Promise<GitGraphSessionRefreshResult>;
+  dispose(): void;
 }
 export interface GitGraphSessionRefreshOptions {
-    /** Rebuild anchor / find target — the loaded window's bottom sha (pins the walk's bottom boundary),
-     *  or a selection/centering hint. Mirrors the `rev` the host passed to `getGraph` today. */
-    rev?: string;
-    limit?: number;
-    include?: {
-        stats?: boolean;
-    };
-    /**
-     * Force a FULL walk (skip the incremental seed) so every row's decorations — including the
-     * host-serialized webview-item contexts reused rows otherwise keep — are rebuilt from fresh inputs.
-     * For host-known invalidations the provider can't observe (pinned-ref changes, integration
-     * connections); rare events, so the full-walk cost is acceptable.
-     */
-    rebuild?: boolean;
+  /** Rebuild anchor / find target — the loaded window's bottom sha (pins the walk's bottom boundary),
+   *  or a selection/centering hint. Mirrors the `rev` the host passed to `getGraph` today. */
+  rev?: string;
+  limit?: number;
+  include?: {
+    stats?: boolean;
+  };
+  /**
+   * Force a FULL walk (skip the incremental seed) so every row's decorations — including the
+   * host-serialized webview-item contexts reused rows otherwise keep — are rebuilt from fresh inputs.
+   * For host-known invalidations the provider can't observe (pinned-ref changes, integration
+   * connections); rare events, so the full-walk cost is acceptable.
+   */
+  rebuild?: boolean;
 }
 /**
  * Outcome of a {@link GitGraphSession.refresh}. `path` is `'fast'` only when the incremental head-walk
@@ -61,36 +85,104 @@ export interface GitGraphSessionRefreshOptions {
  * otherwise).
  */
 export interface GitGraphSessionRefreshResult {
-    readonly path: 'fast' | 'full';
-    /** Present only on a SEEDED refresh that fell back to the full walk — the gate/boundary that forced it. */
-    readonly reason?: IncrementalGraphFallbackReason;
-    /** Fast path only: how many NEW commit rows the incremental enumeration added at the head. */
-    readonly added?: number;
-    /**
-     * Which rows-plane channels this refresh actually changed, so the host marks the publisher precisely
-     * instead of dirtying all six on every refresh. Filled by BOTH paths: the full path reports every
-     * channel changed (a fresh walk replaces all); the fast path derives each honestly from its own work.
-     * Correctness rule: a false negative is data loss, so a channel is reported `false` only when it
-     * PROVABLY didn't change — never merely when uncertain. Excludes `refsMetadata`, which the session
-     * doesn't produce (the host marks it via its own dedicated enrichment path).
-     */
-    readonly changed: GitGraphSessionChangedChannels;
+  readonly path: 'fast' | 'full';
+  /** Present only on a SEEDED refresh that fell back to the full walk — the gate/boundary that forced it. */
+  readonly reason?: IncrementalGraphFallbackReason;
+  /** Fast path only: how many NEW commit rows the incremental enumeration added at the head. */
+  readonly added?: number;
+  /**
+   * Which rows-plane channels this refresh actually changed, so the host marks the publisher precisely
+   * instead of dirtying all six on every refresh. Filled by BOTH paths: the full path reports every
+   * channel changed (a fresh walk replaces all); the fast path derives each honestly from its own work.
+   * Correctness rule: a false negative is data loss, so a channel is reported `false` only when it
+   * PROVABLY didn't change — never merely when uncertain. Excludes `refsMetadata`, which the session
+   * doesn't produce (the host marks it via its own dedicated enrichment path).
+   */
+  readonly changed: GitGraphSessionChangedChannels;
 }
 /** Per-channel change flags a {@link GitGraphSession.refresh} reports (see {@link GitGraphSessionRefreshResult.changed}). */
 export interface GitGraphSessionChangedChannels {
-    /** The loaded rows window — always `true` on a refresh (a head-walk reshapes it; the publisher's ledger
-     *  diff derives the precise splice, including reused-row flag/reachability-index changes). */
-    readonly rows: boolean;
-    /** The shared reachability table grew (new dictionary/set entries appended) or started a new generation. */
-    readonly reachability: boolean;
-    /** New commit shas were introduced whose stats will be (re)queried. */
-    readonly rowsStats: boolean;
-    /** Full fallbacks that rewrite parents (unshallow / replace-ref change) recompute stats whose
-     *  values may differ for already-shipped shas — the host must resend, not just append. */
-    readonly rowsStatsRecomputed?: boolean;
-    /** New avatar emails appeared in the map (value replacements ride the host's dedicated avatar path). */
-    readonly avatars: boolean;
-    /** The downstreams map (upstream name → tracking branch names) changed. */
-    readonly downstreams: boolean;
+  /** The loaded rows window — always `true` on a refresh (a head-walk reshapes it; the publisher's ledger
+   *  diff derives the precise splice, including reused-row flag/reachability-index changes). */
+  readonly rows: boolean;
+  /** The shared reachability table grew (new dictionary/set entries appended) or started a new generation. */
+  readonly reachability: boolean;
+  /** New commit shas were introduced whose stats will be (re)queried. */
+  readonly rowsStats: boolean;
+  /** A refresh invalidated stats for already-shipped shas because ancestry changed
+   *  (shallow boundary / replace refs), or asynchronous error recovery could observe different ancestry.
+   *  The host must replace rows and stats together with a snapshot: same-sha row reuse can retain
+   *  stale parents, and stats deduplication can retain stale values. */
+  readonly rowsStatsRecomputed?: boolean;
+  /** New avatar emails appeared in the map (value replacements ride the host's dedicated avatar path). */
+  readonly avatars: boolean;
+  /** The downstreams map (upstream name → tracking branch names) changed. */
+  readonly downstreams: boolean;
+}
+/**
+ * The outcome of a {@link GitGraphSession.more}. Three states, not a boolean, because the caller's correct
+ * response to two of them differs: a page that was REFUSED must be retried, while a page that found
+ * nothing must not (retrying it spins).
+ */
+export type GitGraphSessionMoreResult =
+/** Rows were paged in — `current` is the page view and `window` grew. */
+'added' |
+/** Nothing to add: history is exhausted, or the walk came back empty. Terminal for this request. */
+'none' |
+/**
+ * REFUSED, having walked nothing and changed nothing: a {@link GitGraphSession.refresh} or
+ * {@link GitGraphSession.rebind} replaced the window this page targeted while it was queued. The
+ * caller must RE-REQUEST against the current window (re-deriving cursor/limit) rather than treat this
+ * as terminal — the rows are still there to page.
+ */
+'superseded';
+/**
+ * The concurrency contract every {@link GitGraphSession} implementation shares — compose it
+ * (`private readonly writes = new GraphSessionWriteQueue()`) rather than reimplementing it, so the two
+ * implementations cannot drift apart.
+ *
+ * {@link run} makes every mutating op single-writer: no interleaving, no torn window. {@link generation}
+ * (via {@link runPage}) separately answers whether a QUEUED page still targets the window that exists,
+ * since queueing alone can't. READS are not covered — `current`/`window` are plain getters, readable at
+ * any time including mid-walk; a caller that must not observe a half-rebuilt window gates its own read.
+ *
+ * DEADLOCK-FREEDOM requires the function handed to {@link run} to await only its own walk, never a
+ * promise a caller might be waiting on — sequencing waits belong strictly BEFORE the op enters the queue.
+ */
+export declare class GraphSessionWriteQueue {
+  /** Tail of the queue. Starts settled so the first op runs immediately. */
+  private _tail;
+  private _generation;
+  private _tainted;
+  /**
+   * The window is known-CORRUPT and must not be served until a rebuild repairs it — see {@link taint}.
+   * Consulted by readers, which is the point: the queue keeps writers apart, but a reader of `current`
+   * never enters it, so the only way a corrupt window can be kept off screen is for the reader to ask.
+   */
+  get tainted(): boolean;
+  /** Monotonic id of the CURRENT window. See {@link invalidate}. */
+  get generation(): number;
+  /**
+   * Call when the window has been REPLACED (a full/incremental rebuild), never when merely extended —
+   * appending a page leaves every held cursor valid. Also the REPAIR for a tainted window, so it clears
+   * {@link tainted}.
+   */
+  invalidate(): void;
+  /**
+   * Call when a walk failed PART-WAY THROUGH mutating the window in place, leaving some rows re-stamped
+   * and some not. Advances the generation, same as {@link invalidate}, so a queued page is refused rather
+   * than appended to a corrupt window — and additionally raises {@link tainted}, since refusing pages
+   * doesn't stop a reader from serving the window directly.
+   */
+  taint(): void;
+  /** Runs `op` after every op queued before it has settled. */
+  run<T>(op: () => Promise<T>): Promise<T>;
+  /**
+   * Runs a PAGE. Captures {@link generation} synchronously HERE, before queueing, and refuses the page
+   * without running `op` if the window has been replaced by the time it reaches the front — the
+   * `'superseded'` half of {@link GitGraphSessionMoreResult}.
+   */
+  runPage(op: () => Promise<GitGraphSessionMoreResult>): Promise<GitGraphSessionMoreResult>;
 }
+//#endregion
 //# sourceMappingURL=graphSession.d.ts.map

package/dist/git/models/graphSession.js

@@ -1,2 +1,73 @@
-export {};
+//#region ../git/src/models/graphSession.ts
+/**
+* The concurrency contract every {@link GitGraphSession} implementation shares — compose it
+* (`private readonly writes = new GraphSessionWriteQueue()`) rather than reimplementing it, so the two
+* implementations cannot drift apart.
+*
+* {@link run} makes every mutating op single-writer: no interleaving, no torn window. {@link generation}
+* (via {@link runPage}) separately answers whether a QUEUED page still targets the window that exists,
+* since queueing alone can't. READS are not covered — `current`/`window` are plain getters, readable at
+* any time including mid-walk; a caller that must not observe a half-rebuilt window gates its own read.
+*
+* DEADLOCK-FREEDOM requires the function handed to {@link run} to await only its own walk, never a
+* promise a caller might be waiting on — sequencing waits belong strictly BEFORE the op enters the queue.
+*/
+var GraphSessionWriteQueue = class {
+	/** Tail of the queue. Starts settled so the first op runs immediately. */
+	_tail = Promise.resolve();
+	_generation = 0;
+	_tainted = false;
+	/**
+	* The window is known-CORRUPT and must not be served until a rebuild repairs it — see {@link taint}.
+	* Consulted by readers, which is the point: the queue keeps writers apart, but a reader of `current`
+	* never enters it, so the only way a corrupt window can be kept off screen is for the reader to ask.
+	*/
+	get tainted() {
+		return this._tainted;
+	}
+	/** Monotonic id of the CURRENT window. See {@link invalidate}. */
+	get generation() {
+		return this._generation;
+	}
+	/**
+	* Call when the window has been REPLACED (a full/incremental rebuild), never when merely extended —
+	* appending a page leaves every held cursor valid. Also the REPAIR for a tainted window, so it clears
+	* {@link tainted}.
+	*/
+	invalidate() {
+		this._generation++;
+		this._tainted = false;
+	}
+	/**
+	* Call when a walk failed PART-WAY THROUGH mutating the window in place, leaving some rows re-stamped
+	* and some not. Advances the generation, same as {@link invalidate}, so a queued page is refused rather
+	* than appended to a corrupt window — and additionally raises {@link tainted}, since refusing pages
+	* doesn't stop a reader from serving the window directly.
+	*/
+	taint() {
+		this._generation++;
+		this._tainted = true;
+	}
+	/** Runs `op` after every op queued before it has settled. */
+	run(op) {
+		const next = this._tail.catch(() => void 0).then(op);
+		this._tail = next;
+		return next;
+	}
+	/**
+	* Runs a PAGE. Captures {@link generation} synchronously HERE, before queueing, and refuses the page
+	* without running `op` if the window has been replaced by the time it reaches the front — the
+	* `'superseded'` half of {@link GitGraphSessionMoreResult}.
+	*/
+	runPage(op) {
+		const generation = this._generation;
+		return this.run(() => {
+			if (this._tainted || this._generation !== generation) return Promise.resolve("superseded");
+			return op();
+		});
+	}
+};
+//#endregion
+export { GraphSessionWriteQueue };
+
 //# sourceMappingURL=graphSession.js.map

package/dist/git/models/graphSession.js.map

@@ -1 +1 @@
-{"version":3,"file":"graphSession.js","sourceRoot":"","sources":["../../../src/git/models/graphSession.ts"],"names":[],"mappings":""}
+{"version":3,"file":"graphSession.js","names":[],"sources":["../../../../git/src/models/graphSession.ts"],"sourcesContent":["import type { GitGraph, GitGraphRow, IncrementalGraphFallbackReason } from './graph.js';\n\n/**\n * A provider-owned, stateful graph window for a single repo. It is the canonical accumulated window and\n * the single builder of the incremental rebuild seed — the host no longer mirrors loaded rows, stamps\n * ref tips, or hand-assembles the {@link GraphIncrementalSeed}; the session owns its own walk shape and\n * cannot be handed a lying seed.\n *\n * R7a is a behavior-neutral ownership move: {@link refresh} is a facade over the provider's existing\n * `getGraph` incremental machinery (it internally builds the seed from the accumulated window, tips, and\n * prior artifacts, with the same shape gating), {@link more} delegates to the prior result's `more()`,\n * and {@link current} mirrors today's `GitGraph` result shape so the publisher/wire semantics stay\n * byte-identical. R7b (refresh-result-driven channel marking) extends this without breaking —\n * {@link refresh} returns a result object, never a bare `GitGraph`.\n *\n * CONCURRENCY — the session is SINGLE-WRITER: {@link refresh}, {@link rebind} and {@link more} serialize\n * in call order, so `repoPath` and every row in `window` always describe the last completed operation,\n * never a torn mix of two. A page queued when a refresh/rebind REPLACES the window it targets is refused\n * (`more` answers `'superseded'`) rather than spliced onto a cursor that no longer fits — see {@link more}.\n *\n * READS are not serialized: a caller that must not observe a half-rebuilt window gates its own read.\n */\nexport interface GitGraphSession {\n\t/** The CURRENT bound path — the repo the session was opened for, or the worktree it was last\n\t *  {@link rebind}-ed onto. */\n\treadonly repoPath: string;\n\n\t/** Canonical accumulated window (the FULL loaded rows, never page-scoped after pagination). */\n\treadonly window: readonly GitGraphRow[];\n\n\t/**\n\t * True while {@link window}/{@link current} are known CORRUPT from a walk that failed part-way through\n\t * mutating them in place. Clears on the next (forced) rebuild. A caller that would SERVE these rows\n\t * must check this first — reads bypass the write queue, so nothing else enforces it.\n\t */\n\treadonly tainted: boolean;\n\n\t/**\n\t * Last-operation view mirroring today's `GitGraph` result shape: page-scoped `rows` after a\n\t * {@link more}, the full window after a {@link refresh}. Keeps the publisher's `getRows`/`getPaging`\n\t * and every graph-level read (`branches`, `remotes`, `stashes`, `ids`, `avatars`, `rowsStats`, …)\n\t * exactly as they read `_graph` today.\n\t */\n\treadonly current: GitGraph;\n\n\t/**\n\t * Re-walk the repo, accumulating the fresh full window. Internally seeds the incremental head-walk\n\t * fast path from the prior window/tips/artifacts (same shape gating as the host did) and falls back\n\t * to a full walk on any structural change; the result surfaces which path ran so a later stage can\n\t * mark channels precisely.\n\t */\n\trefresh(options?: GitGraphSessionRefreshOptions, cancellation?: AbortSignal): Promise<GitGraphSessionRefreshResult>;\n\n\t/**\n\t * Page more rows into the window (accumulates; `current` becomes the page view). See\n\t * {@link GitGraphSessionMoreResult} — a caller MUST distinguish `'superseded'` (retry) from `'none'`\n\t * (don't).\n\t */\n\tmore(limit?: number, targetId?: string, cancellation?: AbortSignal): Promise<GitGraphSessionMoreResult>;\n\n\t/**\n\t * Re-perspective the session onto another worktree of the SAME repo family without discarding\n\t * the accumulated window. Rides the incremental fast path: unchanged tips, HEAD endpoints\n\t * refetched, flags/reachability replayed, ref ids re-stamped to the new path. Falls back to a\n\t * full walk only when a genuine structural/metadata change happened concurrently.\n\t */\n\trebind(repoPath: string, cancellation?: AbortSignal): Promise<GitGraphSessionRefreshResult>;\n\n\tdispose(): void;\n}\n\nexport interface GitGraphSessionRefreshOptions {\n\t/** Rebuild anchor / find target — the loaded window's bottom sha (pins the walk's bottom boundary),\n\t *  or a selection/centering hint. Mirrors the `rev` the host passed to `getGraph` today. */\n\trev?: string;\n\tlimit?: number;\n\tinclude?: { stats?: boolean };\n\t/**\n\t * Force a FULL walk (skip the incremental seed) so every row's decorations — including the\n\t * host-serialized webview-item contexts reused rows otherwise keep — are rebuilt from fresh inputs.\n\t * For host-known invalidations the provider can't observe (pinned-ref changes, integration\n\t * connections); rare events, so the full-walk cost is acceptable.\n\t */\n\trebuild?: boolean;\n}\n\n/**\n * Outcome of a {@link GitGraphSession.refresh}. `path` is `'fast'` only when the incremental head-walk\n * fast path ran; a seeded fallback and an unseeded full walk both report `'full'` — a seeded fallback\n * additionally carries `reason` (an unseeded full walk carries none), so a consumer can distinguish the\n * two exactly as the host's `[graph] incremental walk` log did (log on `'fast'` or a `reason`, silent\n * otherwise).\n */\nexport interface GitGraphSessionRefreshResult {\n\treadonly path: 'fast' | 'full';\n\t/** Present only on a SEEDED refresh that fell back to the full walk — the gate/boundary that forced it. */\n\treadonly reason?: IncrementalGraphFallbackReason;\n\t/** Fast path only: how many NEW commit rows the incremental enumeration added at the head. */\n\treadonly added?: number;\n\t/**\n\t * Which rows-plane channels this refresh actually changed, so the host marks the publisher precisely\n\t * instead of dirtying all six on every refresh. Filled by BOTH paths: the full path reports every\n\t * channel changed (a fresh walk replaces all); the fast path derives each honestly from its own work.\n\t * Correctness rule: a false negative is data loss, so a channel is reported `false` only when it\n\t * PROVABLY didn't change — never merely when uncertain. Excludes `refsMetadata`, which the session\n\t * doesn't produce (the host marks it via its own dedicated enrichment path).\n\t */\n\treadonly changed: GitGraphSessionChangedChannels;\n}\n\n/** Per-channel change flags a {@link GitGraphSession.refresh} reports (see {@link GitGraphSessionRefreshResult.changed}). */\nexport interface GitGraphSessionChangedChannels {\n\t/** The loaded rows window — always `true` on a refresh (a head-walk reshapes it; the publisher's ledger\n\t *  diff derives the precise splice, including reused-row flag/reachability-index changes). */\n\treadonly rows: boolean;\n\t/** The shared reachability table grew (new dictionary/set entries appended) or started a new generation. */\n\treadonly reachability: boolean;\n\t/** New commit shas were introduced whose stats will be (re)queried. */\n\treadonly rowsStats: boolean;\n\t/** A refresh invalidated stats for already-shipped shas because ancestry changed\n\t *  (shallow boundary / replace refs), or asynchronous error recovery could observe different ancestry.\n\t *  The host must replace rows and stats together with a snapshot: same-sha row reuse can retain\n\t *  stale parents, and stats deduplication can retain stale values. */\n\treadonly rowsStatsRecomputed?: boolean;\n\t/** New avatar emails appeared in the map (value replacements ride the host's dedicated avatar path). */\n\treadonly avatars: boolean;\n\t/** The downstreams map (upstream name → tracking branch names) changed. */\n\treadonly downstreams: boolean;\n}\n\n/**\n * The outcome of a {@link GitGraphSession.more}. Three states, not a boolean, because the caller's correct\n * response to two of them differs: a page that was REFUSED must be retried, while a page that found\n * nothing must not (retrying it spins).\n */\nexport type GitGraphSessionMoreResult =\n\t/** Rows were paged in — `current` is the page view and `window` grew. */\n\t| 'added'\n\t/** Nothing to add: history is exhausted, or the walk came back empty. Terminal for this request. */\n\t| 'none'\n\t/**\n\t * REFUSED, having walked nothing and changed nothing: a {@link GitGraphSession.refresh} or\n\t * {@link GitGraphSession.rebind} replaced the window this page targeted while it was queued. The\n\t * caller must RE-REQUEST against the current window (re-deriving cursor/limit) rather than treat this\n\t * as terminal — the rows are still there to page.\n\t */\n\t| 'superseded';\n\n/**\n * The concurrency contract every {@link GitGraphSession} implementation shares — compose it\n * (`private readonly writes = new GraphSessionWriteQueue()`) rather than reimplementing it, so the two\n * implementations cannot drift apart.\n *\n * {@link run} makes every mutating op single-writer: no interleaving, no torn window. {@link generation}\n * (via {@link runPage}) separately answers whether a QUEUED page still targets the window that exists,\n * since queueing alone can't. READS are not covered — `current`/`window` are plain getters, readable at\n * any time including mid-walk; a caller that must not observe a half-rebuilt window gates its own read.\n *\n * DEADLOCK-FREEDOM requires the function handed to {@link run} to await only its own walk, never a\n * promise a caller might be waiting on — sequencing waits belong strictly BEFORE the op enters the queue.\n */\nexport class GraphSessionWriteQueue {\n\t/** Tail of the queue. Starts settled so the first op runs immediately. */\n\tprivate _tail: Promise<unknown> = Promise.resolve();\n\tprivate _generation = 0;\n\tprivate _tainted = false;\n\n\t/**\n\t * The window is known-CORRUPT and must not be served until a rebuild repairs it — see {@link taint}.\n\t * Consulted by readers, which is the point: the queue keeps writers apart, but a reader of `current`\n\t * never enters it, so the only way a corrupt window can be kept off screen is for the reader to ask.\n\t */\n\tget tainted(): boolean {\n\t\treturn this._tainted;\n\t}\n\n\t/** Monotonic id of the CURRENT window. See {@link invalidate}. */\n\tget generation(): number {\n\t\treturn this._generation;\n\t}\n\n\t/**\n\t * Call when the window has been REPLACED (a full/incremental rebuild), never when merely extended —\n\t * appending a page leaves every held cursor valid. Also the REPAIR for a tainted window, so it clears\n\t * {@link tainted}.\n\t */\n\tinvalidate(): void {\n\t\tthis._generation++;\n\t\tthis._tainted = false;\n\t}\n\n\t/**\n\t * Call when a walk failed PART-WAY THROUGH mutating the window in place, leaving some rows re-stamped\n\t * and some not. Advances the generation, same as {@link invalidate}, so a queued page is refused rather\n\t * than appended to a corrupt window — and additionally raises {@link tainted}, since refusing pages\n\t * doesn't stop a reader from serving the window directly.\n\t */\n\ttaint(): void {\n\t\tthis._generation++;\n\t\tthis._tainted = true;\n\t}\n\n\t/** Runs `op` after every op queued before it has settled. */\n\trun<T>(op: () => Promise<T>): Promise<T> {\n\t\t// `.catch` BEFORE `.then` so a rejected predecessor can't wedge the queue — without it every later\n\t\t// op would inherit the rejection and never run its body at all.\n\t\tconst next = this._tail.catch(() => undefined).then(op);\n\t\t// The caller's promise IS the tail, so a rejection the caller handles is never ALSO an unhandled\n\t\t// rejection on a derived promise nobody holds a reference to.\n\t\tthis._tail = next;\n\t\treturn next;\n\t}\n\n\t/**\n\t * Runs a PAGE. Captures {@link generation} synchronously HERE, before queueing, and refuses the page\n\t * without running `op` if the window has been replaced by the time it reaches the front — the\n\t * `'superseded'` half of {@link GitGraphSessionMoreResult}.\n\t */\n\trunPage(op: () => Promise<GitGraphSessionMoreResult>): Promise<GitGraphSessionMoreResult> {\n\t\tconst generation = this._generation;\n\t\treturn this.run(() => {\n\t\t\t// Two ways a page can go stale by now, both answering `'superseded'`: the window it was cut from\n\t\t\t// was REPLACED (generation moved), or it's TAINTED — generation alone can't catch the latter, since\n\t\t\t// a page requested AFTER the corruption still sees a stable generation.\n\t\t\tif (this._tainted || this._generation !== generation) return Promise.resolve('superseded' as const);\n\n\t\t\treturn op();\n\t\t});\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;AAiKA,IAAa,yBAAb,MAAoC;;CAEnC,QAAkC,QAAQ,QAAQ;CAClD,cAAsB;CACtB,WAAmB;;;;;;CAOnB,IAAI,UAAmB;EACtB,OAAO,KAAK;CACb;;CAGA,IAAI,aAAqB;EACxB,OAAO,KAAK;CACb;;;;;;CAOA,aAAmB;EAClB,KAAK;EACL,KAAK,WAAW;CACjB;;;;;;;CAQA,QAAc;EACb,KAAK;EACL,KAAK,WAAW;CACjB;;CAGA,IAAO,IAAkC;EAGxC,MAAM,OAAO,KAAK,MAAM,YAAY,KAAA,CAAS,CAAC,CAAC,KAAK,EAAE;EAGtD,KAAK,QAAQ;EACb,OAAO;CACR;;;;;;CAOA,QAAQ,IAAkF;EACzF,MAAM,aAAa,KAAK;EACxB,OAAO,KAAK,UAAU;GAIrB,IAAI,KAAK,YAAY,KAAK,gBAAgB,YAAY,OAAO,QAAQ,QAAQ,YAAqB;GAElG,OAAO,GAAG;EACX,CAAC;CACF;AACD"}