ensemble-review 1.0.35 → 1.0.37

package/dist/db/schema.sqlite.js

@@ -185,6 +185,12 @@ export const repos = sqliteTable('repos', {
     // from GitHub (a nulled selection leaves it as it was); `checked_at` stamps every attempt.
     usesGithubIssues: integer('uses_github_issues', { mode: 'boolean' }),
     githubIssuesCheckedAt: integer('github_issues_checked_at', { mode: 'timestamp' }),
+    // ---- TAGS (migration 0195; docs/RELEASES.md) ----
+    // What the last COMPLETE tag read saw, as `tagSignature` (sync/repo-tags.ts): the tag count plus
+    // the newest tag's name and target. The settle sweep reads the same three facts for ~nothing and
+    // starts a tag sync when they differ — a tag push is updatedAt-silent. NULL = never read.
+    tagsSignature: text('tags_signature'),
+    tagsSyncedAt: integer('tags_synced_at', { mode: 'timestamp' }),
 }, (t) => ({
     // Composite uniques so two accounts can watch the same GitHub repo (each
     // gets its own row). The upsert conflict targets these.
@@ -408,8 +414,17 @@ export const pullRequests = sqliteTable('pull_requests', {
     linearLinks: text('linear_links', { mode: 'json' }).$type(),
     linearLinksRoot: text('linear_links_root'),
     linearLinksCheckedAt: integer('linear_links_checked_at', { mode: 'timestamp' }),
+    // ---- RELEASES (migration 0195; docs/RELEASES.md) ----
+    // The commit this PR landed as on its base branch (GraphQL `mergeCommit { oid }`): the squash
+    // commit, the merge commit, or the last rebased commit. A version tag's range maps the commits
+    // between two tags to PRs through it (sync/tag-ranges.ts). ⚠ Cleared only on a positive
+    // statement: an oid is written when one arrives; null only for a PR GitHub says is NOT merged
+    // (sync/upsert.ts `mergeCommitOidToWrite`). NULL on a merged PR = not observed yet.
+    mergeCommitOid: text('merge_commit_oid'),
 }, (t) => ({
     repoIdx: index('pr_repo_idx').on(t.repoId),
+    // The tag range's commit → PR lookup (sync/tag-ranges.ts), a batch of shas within one repo.
+    mergeCommitIdx: index('pr_account_repo_merge_commit_idx').on(t.accountId, t.repoId, t.mergeCommitOid),
     openedIdx: index('pr_opened_idx').on(t.openedAt),
     accountIdx: index('pr_account_idx').on(t.accountId),
     // Drives getUserStats (the contributor popover) from the person rather than the account.
@@ -2113,6 +2128,13 @@ export const workspaces = sqliteTable('workspaces', {
     // `AI_REVIEWS_FIRST_LOOK_DAYS` days). Never moves back. The ONE reader/writer is
     // db/ai-reviews-seen.ts.
     aiReviewsSeenAt: integer('ai_reviews_seen_at', { mode: 'timestamp' }),
+    // RELEASES (migration 0195; docs/RELEASES.md § Terms and settings): the RELEASE suffix (a
+    // release tag is `<version tag><release suffix>`) and the HOTFIX suffix (a hotfix tag ends in
+    // it). NULL = not set, and there is NO default: the Releases tab and the hotfix option do
+    // nothing until BOTH are set. Validated by shared `validateReleaseSettings`; the ONE reader /
+    // writer is db/release-settings.ts. Per workspace, no inheritance.
+    releaseSuffix: text('release_suffix'),
+    hotfixSuffix: text('hotfix_suffix'),
     createdAt: integer('created_at', { mode: 'timestamp' })
         .notNull()
         .default(sql `(unixepoch())`),
@@ -4217,6 +4239,10 @@ export const storyBuilds = sqliteTable('story_builds', {
     endToEnd: integer('end_to_end', { mode: 'boolean' }).notNull().default(false),
     e2eTicketClaimedAt: integer('e2e_ticket_claimed_at', { mode: 'timestamp' }),
     e2eTicketJson: text('e2e_ticket_json', { mode: 'json' }).$type(),
+    // HOTFIX (migration 0196; docs/STORY-BUILD.md § Hotfix builds): "Treat as a hotfix" at Start. Each repository
+    // with a latest release is fixed there and the fix PORTED to the default branch; the review loop and
+    // "Build end to end" are refused for it.
+    hotfix: integer('hotfix', { mode: 'boolean' }).notNull().default(false),
     createdAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql `(unixepoch())`),
     startedAt: integer('started_at', { mode: 'timestamp' }),
     completedAt: integer('completed_at', { mode: 'timestamp' }),
@@ -4282,6 +4308,35 @@ export const storyBuildRepos = sqliteTable('story_build_repos', {
     loopPushedTree: text('loop_pushed_tree'),
     loopPushedAt: integer('loop_pushed_at', { mode: 'timestamp' }),
     loopEnded: text('loop_ended'),
+    // HOTFIX (migration 0196; docs/STORY-BUILD.md § Hotfix builds). `hotfix_tag` = the latest release the
+    // release checkout starts at (NULL on an ordinary build and on a read-only repository); `read_only` = no
+    // release yet, its changes are refused at extraction. `main_*` = THE MAIN FIX (the default-branch checkout
+    // in the same sandbox): its base, path, patch and push record, beside the row's own (the RELEASE FIX).
+    hotfixTag: text('hotfix_tag'),
+    readOnly: integer('read_only', { mode: 'boolean' }).notNull().default(false),
+    mainBaseRef: text('main_base_ref'),
+    mainBaseSha: text('main_base_sha'),
+    mainSandboxPath: text('main_sandbox_path'),
+    mainPatch: text('main_patch'),
+    mainPatchSha: text('main_patch_sha'),
+    mainStatJson: text('main_stat_json', { mode: 'json' }).$type(),
+    mainFilesChangedJson: text('main_files_changed_json', { mode: 'json' }).$type(),
+    mainCommitMessage: text('main_commit_message'),
+    // NULL (not built yet) | 'ready' | 'skipped' (no change) | 'failed' | 'pushed'.
+    mainStatus: text('main_status'),
+    mainError: text('main_error'),
+    mainPushedBranch: text('main_pushed_branch'),
+    mainPushedPrNumber: integer('main_pushed_pr_number'),
+    mainPushedPrUrl: text('main_pushed_pr_url'),
+    mainPushedCommitSha: text('main_pushed_commit_sha'),
+    mainPushedAt: integer('main_pushed_at', { mode: 'timestamp' }),
+    mainPushError: text('main_push_error'),
+    mainPushErrorCode: text('main_push_error_code'),
+    // Push's record of `hotfix/<tag>` (shared StoryBuildHotfixBranch): created or found, moved, the PRs on it.
+    hotfixBranchJson: text('hotfix_branch_json', { mode: 'json' }).$type(),
+    // THE PORT REPORT (migration 0198): the agent's claim for this repository (same | adapted | not_needed,
+    // the reason, the evidence), as the host checked and clipped it; NULL = no report. Untrusted model text.
+    portReportJson: text('port_report_json', { mode: 'json' }).$type(),
     provider: text('provider'),
     model: text('model'),
     effort: text('effort'),
@@ -4853,4 +4908,195 @@ export const limnActions = sqliteTable('limn_actions', {
         foreignColumns: [pullRequests.id, pullRequests.accountId],
     }).onDelete('cascade'),
 }));
+// ---- RELEASES (migration 0195; docs/RELEASES.md) ------------------------------------------------
+//
+// FIVE tables, all account-scoped with composite FKs (tenancy as a constraint), all in
+// `accountScopedTables()` and erased explicitly; the repo-anchored ones in `deleteRepo` too.
+//
+//   repo_tags                one row per (account, repo, tag name): what the tag points at.
+//   repo_tag_ranges          one row per (account, repo, tag name): the PRs between the tag and the
+//                            tag before it on the default branch, computed once per (tag sha, base sha).
+//   releases                 one row per reader press of "Create release…".
+//   release_items            one row per (release, repo): the release tag and the pre-release.
+//   release_ticket_comments  one row per (release, ticket): the tracker comment.
+// The repo's git tags, synced as part of the default-branch snapshot step (sync/repo-tags.ts) —
+// STRICTLY NON-FATAL, the newest REPO_TAGS_READ_CAP by the tagged commit's date. A tag PUSH is
+// updatedAt-silent, so the settle sweep notices it (`repos.tags_signature`).
+//   sha             the COMMIT the tag points at (an annotated tag is peeled one level).
+//   tag_object_oid  the annotated tag object's oid; NULL for a lightweight tag.
+//   committed_at    the tagged commit's date — the order "newest version tag" means.
+//   tagged_at       the annotated tag's tagger date (the tie-break "by tag creation"); NULL for a
+//                   lightweight tag.
+//   on_default_branch  the tagged commit is an ancestor of (or equal to) the default branch head.
+//                   NULL = not known yet. `ancestry_head_sha` is the head it was checked against:
+//                   true is final for that sha (until the tag moves); false is re-checked when the
+//                   head moves.
+//   previous_sha / moved_at  the tag was MOVED to another commit (re-pushed with --force): the sha
+//                   it pointed at before, and when Ensemble saw the move.
+export const repoTags = sqliteTable('repo_tags', {
+    id: integer('id').primaryKey({ autoIncrement: true }),
+    accountId: integer('account_id')
+        .notNull()
+        .references(() => accounts.id, { onDelete: 'cascade' }),
+    repoId: integer('repo_id').notNull(),
+    name: text('name').notNull(),
+    sha: text('sha').notNull(),
+    tagObjectOid: text('tag_object_oid'),
+    committedAt: integer('committed_at', { mode: 'timestamp' }),
+    taggedAt: integer('tagged_at', { mode: 'timestamp' }),
+    onDefaultBranch: integer('on_default_branch', { mode: 'boolean' }),
+    ancestryHeadSha: text('ancestry_head_sha'),
+    previousSha: text('previous_sha'),
+    movedAt: integer('moved_at', { mode: 'timestamp' }),
+    firstSeenAt: integer('first_seen_at', { mode: 'timestamp' }).notNull(),
+    lastSeenAt: integer('last_seen_at', { mode: 'timestamp' }).notNull(),
+}, (t) => ({
+    nameUx: uniqueIndex('repo_tags_account_repo_name').on(t.accountId, t.repoId, t.name),
+    shaIdx: index('repo_tags_account_repo_sha_idx').on(t.accountId, t.repoId, t.sha),
+    repoAccountFk: foreignKey({
+        name: 'repo_tags_repo_account_fk',
+        columns: [t.repoId, t.accountId],
+        foreignColumns: [repos.id, repos.accountId],
+    }).onDelete('cascade'),
+}));
+// A tag's range INCREMENT (sync/tag-ranges.ts): the PRs merged into the default branch in
+// (base, tag], where base is the tag before it on the default branch (by committed date, then
+// name). Suffix-free on purpose — the release check sums increments from the baseline up to a
+// version tag, so a new release (a new baseline) or a changed suffix needs no recompute.
+//   base_tag_name / base_sha  NULL for the OLDEST tag Ensemble knows: its range is every PR in the
+//                   synced history merged into the default branch no later than the tag's commit
+//                   (method 'history'), so older PRs are not checked.
+//   method          'compare' (REST compare base...tag) | 'history' (no base: the stored PRs).
+//   pr_numbers      the PRs, by NUMBER (a PR the walk has not stored yet still counts). Resolved to
+//                   local ids within (account, repo) on read (db/repo-tags.ts).
+//   commit_count / unmatched_commits  commits in the range, and how many matched no PR (direct pushes).
+//   truncated       the compare had more commits than Ensemble reads (TAG_RANGE_MAX_COMMITS).
+//   moved_from_sha  the tag MOVED since the last computation: the sha the old range was for.
+// Recomputed only when the tag's sha or its base's sha changes.
+export const repoTagRanges = sqliteTable('repo_tag_ranges', {
+    id: integer('id').primaryKey({ autoIncrement: true }),
+    accountId: integer('account_id')
+        .notNull()
+        .references(() => accounts.id, { onDelete: 'cascade' }),
+    repoId: integer('repo_id').notNull(),
+    tagName: text('tag_name').notNull(),
+    sha: text('sha').notNull(),
+    baseTagName: text('base_tag_name'),
+    baseSha: text('base_sha'),
+    method: text('method', { enum: ['compare', 'history'] }).notNull(),
+    prNumbers: text('pr_numbers', { mode: 'json' }).$type().notNull(),
+    commitCount: integer('commit_count').notNull().default(0),
+    unmatchedCommits: integer('unmatched_commits').notNull().default(0),
+    truncated: integer('truncated', { mode: 'boolean' }).notNull().default(false),
+    movedFromSha: text('moved_from_sha'),
+    computedAt: integer('computed_at', { mode: 'timestamp' }).notNull(),
+}, (t) => ({
+    tagUx: uniqueIndex('repo_tag_ranges_account_repo_tag').on(t.accountId, t.repoId, t.tagName),
+    repoAccountFk: foreignKey({
+        name: 'repo_tag_ranges_repo_account_fk',
+        columns: [t.repoId, t.accountId],
+        foreignColumns: [repos.id, repos.accountId],
+    }).onDelete('cascade'),
+}));
+// One row per press of "Create release…" (docs/RELEASES.md § Releases tab). `notes_markdown` is the
+// whole document (a section per repo); `release_suffix` the suffix in force when it was made.
+//   state  'writing' (the writes are running) · 'done' (every step worked) · 'partial' (some
+//          failed) · 'failed' (nothing was written) · 'stopped' (Confirm's re-check found a change).
+export const releases = sqliteTable('releases', {
+    id: integer('id').primaryKey({ autoIncrement: true }),
+    accountId: integer('account_id')
+        .notNull()
+        .references(() => accounts.id, { onDelete: 'cascade' }),
+    workspaceId: integer('workspace_id').notNull(),
+    createdByUserId: integer('created_by_user_id').references(() => users.id),
+    createdByLogin: text('created_by_login'),
+    createdAt: integer('created_at', { mode: 'timestamp' }).notNull(),
+    releaseSuffix: text('release_suffix').notNull(),
+    notesMarkdown: text('notes_markdown').notNull().default(''),
+    state: text('state', { enum: ['writing', 'done', 'partial', 'failed', 'stopped'] }).notNull(),
+    finishedAt: integer('finished_at', { mode: 'timestamp' }),
+}, (t) => ({
+    workspaceIdx: index('releases_account_workspace_idx').on(t.accountId, t.workspaceId, t.createdAt),
+    // The PARENT KEY of the two child tables' composite FKs (the `repos_id_account` trick).
+    idAccountUx: uniqueIndex('releases_id_account').on(t.id, t.accountId),
+    workspaceAccountFk: foreignKey({
+        name: 'releases_workspace_account_fk',
+        columns: [t.workspaceId, t.accountId],
+        foreignColumns: [workspaces.id, workspaces.accountId],
+    }).onDelete('cascade'),
+}));
+// One row per (release, repo). Two GitHub writes, each CLAIMED (compare-and-set on its state)
+// BEFORE the call and NEVER retried: the annotated release tag, then the pre-release on it.
+//   *_state  'pending' → 'claimed' → 'done' | 'failed'; a tag whose name already exists is
+//            'refused' (never moved); a pre-release whose tag did not land is 'skipped'.
+// ⚠ UNIQUE (account, repo, release_tag_name) across releases: a second press can never write the
+// same tag again — the claim is the row.
+export const releaseItems = sqliteTable('release_items', {
+    id: integer('id').primaryKey({ autoIncrement: true }),
+    accountId: integer('account_id')
+        .notNull()
+        .references(() => accounts.id, { onDelete: 'cascade' }),
+    releaseId: integer('release_id').notNull(),
+    repoId: integer('repo_id').notNull(),
+    versionTag: text('version_tag').notNull(),
+    sha: text('sha').notNull(),
+    releaseTagName: text('release_tag_name').notNull(),
+    notesMarkdown: text('notes_markdown').notNull().default(''),
+    tagState: text('tag_state', { enum: ['pending', 'claimed', 'done', 'failed', 'refused'] })
+        .notNull()
+        .default('pending'),
+    tagObjectOid: text('tag_object_oid'),
+    prereleaseState: text('prerelease_state', {
+        enum: ['pending', 'claimed', 'done', 'failed', 'skipped'],
+    })
+        .notNull()
+        .default('pending'),
+    githubReleaseId: integer('github_release_id'),
+    githubReleaseUrl: text('github_release_url'),
+    error: text('error'),
+    updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull(),
+}, (t) => ({
+    releaseRepoUx: uniqueIndex('release_items_account_release_repo').on(t.accountId, t.releaseId, t.repoId),
+    // ⚠ The tag-name UNIQUE is PARTIAL — only a live row (pending / claimed / done) holds the name, so
+    // a failed or refused write does not block a later press. It lives in migration 0197 ONLY
+    // (`release_items_account_repo_tag_live`); this is its plain lookup index.
+    tagNameIdx: index('release_items_account_repo_tag_idx').on(t.accountId, t.repoId, t.releaseTagName),
+    releaseAccountFk: foreignKey({
+        name: 'release_items_release_account_fk',
+        columns: [t.releaseId, t.accountId],
+        foreignColumns: [releases.id, releases.accountId],
+    }).onDelete('cascade'),
+    repoAccountFk: foreignKey({
+        name: 'release_items_repo_account_fk',
+        columns: [t.repoId, t.accountId],
+        foreignColumns: [repos.id, repos.accountId],
+    }).onDelete('cascade'),
+}));
+// One row per (release, ticket): the tracker comment on a shipped ticket (a ticket whose repos ALL
+// tagged). CLAIMED before the tracker write, NEVER retried.
+//   state  'pending' → 'claimed' → 'posted' | 'failed'; 'skipped' when the ticket did not ship
+//          whole or the tracker cannot take a comment yet (`error` says which).
+export const releaseTicketComments = sqliteTable('release_ticket_comments', {
+    id: integer('id').primaryKey({ autoIncrement: true }),
+    accountId: integer('account_id')
+        .notNull()
+        .references(() => accounts.id, { onDelete: 'cascade' }),
+    releaseId: integer('release_id').notNull(),
+    ticketKey: text('ticket_key').notNull(),
+    trackerKind: text('tracker_kind'),
+    state: text('state', { enum: ['pending', 'claimed', 'posted', 'failed', 'skipped'] })
+        .notNull()
+        .default('pending'),
+    commentId: text('comment_id'),
+    error: text('error'),
+    claimedAt: integer('claimed_at', { mode: 'timestamp' }),
+    postedAt: integer('posted_at', { mode: 'timestamp' }),
+}, (t) => ({
+    releaseTicketUx: uniqueIndex('release_ticket_comments_account_release_ticket').on(t.accountId, t.releaseId, t.ticketKey),
+    releaseAccountFk: foreignKey({
+        name: 'release_ticket_comments_release_account_fk',
+        columns: [t.releaseId, t.accountId],
+        foreignColumns: [releases.id, releases.accountId],
+    }).onDelete('cascade'),
+}));
 //# sourceMappingURL=schema.sqlite.js.map

package/dist/github/mutations.js

@@ -964,6 +964,73 @@ async function setReactionNow(token, subjectNodeId, content, add) {
         viewerCanReact: subject.viewerCanReact === true,
     };
 }
+// ---- Release tags and pre-releases (docs/RELEASES.md § Releases tab 6) ----
+//
+// The READER's Confirm (releases/create.ts) — the caller claims each write first and never retries.
+// `createAnnotatedReleaseTag` makes the annotated tag object on the commit, then its ref; it NEVER moves
+// a ref (no PATCH): a 422 on the ref (the name exists) is reported as `exists`. Errors carry GitHub's
+// `status` (ghRest), which the caller turns into a short sentence.
+export async function createAnnotatedReleaseTag(token, args, origin) {
+    return limnWrite(origin, 'release_tag', {}, async () => {
+        const seg = encodeURIComponent;
+        const obj = await ghRestPostFor(token, `/repos/${seg(args.owner)}/${seg(args.name)}/git/tags`, {
+            tag: args.tag,
+            message: args.message,
+            object: args.sha,
+            type: 'commit',
+        });
+        if (typeof obj.sha !== 'string')
+            throw Object.assign(new Error('GitHub returned no tag object'), { status: 422, stage: 'object' });
+        try {
+            await ghRestPostFor(token, `/repos/${seg(args.owner)}/${seg(args.name)}/git/refs`, { ref: `refs/tags/${args.tag}`, sha: obj.sha });
+        }
+        catch (err) {
+            throw Object.assign(err instanceof Error ? err : new Error(String(err)), { stage: 'ref' });
+        }
+        return { tagObjectOid: obj.sha };
+    }, () => ({ detail: args.tag }));
+}
+// HOTFIX (docs/STORY-BUILD.md § Hotfix builds): `hotfix/<tag>` made at the release commit, on the reader's Push.
+// A NEW ref only (POST git/refs): it never moves one. GitHub's 422 ("Reference already exists") comes back as
+// `exists`, so the caller re-reads the branch instead of guessing.
+export async function createHotfixBranch(token, args, origin) {
+    return limnWrite(origin, 'hotfix_branch', {}, async () => {
+        const seg = encodeURIComponent;
+        try {
+            await ghRestPostFor(token, `/repos/${seg(args.owner)}/${seg(args.name)}/git/refs`, { ref: `refs/heads/${args.branch}`, sha: args.sha });
+            return { outcome: 'created' };
+        }
+        catch (err) {
+            if (err?.status === 422)
+                return { outcome: 'exists' };
+            throw err;
+        }
+    }, () => ({ detail: args.branch }));
+}
+/** The OPEN pull requests whose base is `branch` (a hotfix branch that moved past its release: the tab names
+ *  them). A read; at most 30, newest first. Throws on a failed read. */
+export async function fetchOpenPrsOnBase(token, owner, name, branch) {
+    const seg = encodeURIComponent;
+    const rows = await ghRestGetFor(token, `/repos/${seg(owner)}/${seg(name)}/pulls?state=open&base=${seg(branch)}&sort=created&direction=desc&per_page=30`);
+    return (Array.isArray(rows) ? rows : [])
+        .filter((p) => typeof p.number === 'number')
+        .map((p) => ({ number: p.number, title: typeof p.title === 'string' ? p.title : '', url: typeof p.html_url === 'string' ? p.html_url : null }));
+}
+export async function createGithubPrerelease(token, args, origin) {
+    return limnWrite(origin, 'prerelease', {}, async () => {
+        const seg = encodeURIComponent;
+        const r = await ghRestPostFor(token, `/repos/${seg(args.owner)}/${seg(args.name)}/releases`, {
+            tag_name: args.tag,
+            name: args.title,
+            body: args.body,
+            prerelease: true,
+            draft: false,
+        });
+        if (typeof r.id !== 'number' || typeof r.html_url !== 'string')
+            throw Object.assign(new Error('GitHub returned no release'), { status: 422 });
+        return { id: r.id, url: r.html_url };
+    }, (r) => ({ detail: r.url }));
+}
 // ---- Git data writes (the Implement build claim's placeholder branch) ----
 // Raw git-data REST writes live here, with the other guarded writes (write-origin.test.ts). The
 // placeholder belongs to the reader's Implement build, so its caller passes the reader's origin.

package/dist/github/queries.js

@@ -141,6 +141,11 @@ const PR_NODE_FIELDS = /* GraphQL */ `
   # another open PR's head branch in THIS repo, and a fork's branch name says nothing about a branch
   # here — so a parent must be proven same-repo. A Boolean! scalar on a node already fetched.
   isCrossRepository
+  # The commit this PR landed as (docs/RELEASES.md): a version tag's range maps commits to PRs
+  # through it. A nullable OBJECT, not a connection — no nodes, no cost.
+  mergeCommit {
+    oid
+  }
   mergeable
   mergeStateStatus
   # ---- merge verdict (cluster A: the merge surface) ------------------------------------

package/dist/github/settle-query.js

@@ -4,7 +4,8 @@
 // enough to tell whether our stored row is still right about the things GitHub changes WITHOUT
 // bumping `updatedAt`: the head commit, its CI rollup, the review-thread resolutions — plus
 // `updatedAt` itself, so a PR the walk missed is noticed too, and the default branch's head, so a
-// trunk move (which silently re-decides every open PR's merge state) is noticed.
+// trunk move (which silently re-decides every open PR's merge state) is noticed, and the newest
+// tag + tag count (`refs(first: 1)`, one node), so a tag push is noticed (sync/tags-step.ts).
 //
 // COST — MEASURED 2026-10-28 (`rateLimit { cost }`, read-only, on a real 9-repo workspace): 9
 // points for 9 aliased repos, i.e. ~1 point per repo. GitHub prices a query by the requests its
@@ -65,6 +66,15 @@ export function buildSettleSweepQuery(count) {
           oid
         }
       }
+      tags: refs(refPrefix: "refs/tags/", first: 1, orderBy: { field: TAG_COMMIT_DATE, direction: DESC }) {
+        totalCount
+        nodes {
+          name
+          target {
+            oid
+          }
+        }
+      }
       pullRequests(
         states: [OPEN]
         first: ${SETTLE_PR_PAGE}

package/dist/github/tag-queries.js

@@ -0,0 +1,101 @@
+// TAGS (docs/RELEASES.md) — READ only: the repo's tags (GraphQL), the commits between two commits
+// (REST compare), and the PRs a handful of commits came from (GraphQL, the fallback for a commit
+// no stored PR's `merge_commit_oid` names).
+//
+// COST.
+//   • REPO_TAGS_QUERY: one `refs(first: 100)` connection with no child connection ⇒ 1 point.
+//   • The settle sweep adds `refs(first: 1)` per repo to its own query (github/settle-query.ts):
+//     one node, no measurable change to its ~1 point per repo.
+//   • compareCommits: REST (the core REST budget, not GraphQL points), one call per page of 100
+//     commits; ancestry asks for ONE commit (per_page=1).
+//   • buildCommitPrsQuery: ≤ COMMIT_PRS_ALIAS_CAP aliases × associatedPullRequests(first: 3) ⇒
+//     ≤ 150 nodes ⇒ 2 points.
+//
+// Nullability: everything a tolerant partial (`graphqlTolerant`) can null is optional below.
+import { ghRestGetFor, withGithubRetry } from './client.js';
+/** Tags read per sync, newest by the tagged commit's date. Past this the read is incomplete. */
+export const REPO_TAGS_READ_CAP = 100;
+export const REPO_TAGS_QUERY = /* GraphQL */ `
+  query RepoTags($owner: String!, $name: String!, $first: Int!) {
+    rateLimit {
+      cost
+      remaining
+      resetAt
+    }
+    repository(owner: $owner, name: $name) {
+      defaultBranchRef {
+        name
+        target {
+          oid
+        }
+      }
+      refs(refPrefix: "refs/tags/", first: $first, orderBy: { field: TAG_COMMIT_DATE, direction: DESC }) {
+        totalCount
+        nodes {
+          name
+          target {
+            __typename
+            oid
+            ... on Commit {
+              committedDate
+            }
+            ... on Tag {
+              tagger {
+                date
+              }
+              target {
+                __typename
+                oid
+                ... on Commit {
+                  committedDate
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+`;
+// ---- REST compare -------------------------------------------------------------------------------
+const SHA_RE = /^[0-9a-fA-F]{7,64}$/;
+/** One page of `GET /repos/{owner}/{name}/compare/{base}...{head}`. Throws as ghRestGetFor does. */
+export async function fetchComparePage(token, args) {
+    if (!SHA_RE.test(args.base) || !SHA_RE.test(args.head))
+        throw new Error('compare: not a commit sha');
+    const path = `/repos/${encodeURIComponent(args.owner)}/${encodeURIComponent(args.name)}` +
+        `/compare/${args.base}...${args.head}?per_page=${args.perPage}&page=${args.page}`;
+    return withGithubRetry(() => ghRestGetFor(token, path));
+}
+// ---- The commit → PR fallback -------------------------------------------------------------------
+/** Commits asked about in one request. */
+export const COMMIT_PRS_ALIAS_CAP = 50;
+/** One aliased `object(oid:)` per commit sha; the shas travel as VARIABLES (`s<i>`). */
+export function buildCommitPrsQuery(count) {
+    const vars = Array.from({ length: count }, (_, i) => `$s${i}: GitObjectID!`).join(', ');
+    const aliases = Array.from({ length: count }, (_, i) => `      c${i}: object(oid: $s${i}) {
+        ... on Commit {
+          associatedPullRequests(first: 3) {
+            nodes {
+              number
+              merged
+              baseRefName
+              repository {
+                nameWithOwner
+              }
+            }
+          }
+        }
+      }`).join('\n');
+    return `query CommitPrs($owner: String!, $name: String!${count > 0 ? `, ${vars}` : ''}) {
+    rateLimit {
+      cost
+      remaining
+      resetAt
+    }
+    repository(owner: $owner, name: $name) {
+${aliases}
+    }
+  }`;
+}
+//# sourceMappingURL=tag-queries.js.map