@futurelastic/colab-handbook 1.12.0-rc.64 → 1.12.0-rc.65

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -32,5 +32,5 @@
32
32
  "engines": {
33
33
  "node": ">=18"
34
34
  },
35
- "version": "1.12.0-rc.64"
35
+ "version": "1.12.0-rc.65"
36
36
  }
package/tools/colab CHANGED
@@ -3715,7 +3715,11 @@ ROLE-TAGGED GRANTS (#397). --role defaults to \`human\` — the grant above, unc
3715
3715
  --role ${migrationGrant.REVIEWER_ROLE} the comment is a \`${migrationGrant.REVIEW_GRANT_MARK}\` instead:
3716
3716
  it names the declared reviewer and carries a REVIEW RECORD (a \`\`\`${migrationGrant.REVIEW_RECORD_FENCE}
3717
3717
  block — verdict, checklist result, the escalation condition checked, the CI round-trip result, and
3718
- the reviewed HEAD sha). A reviewer grant is bound to that HEAD: any new commit on the branch voids it.
3718
+ the reviewed HEAD sha, and — #508 — \`migrations\`, a content id over the branch's migration files at
3719
+ that HEAD, computed here, never a flag). A reviewer grant is bound to that CONTENT: a commit that
3720
+ leaves every migration file byte-identical (the trunk sync ship requires) keeps it; editing, adding,
3721
+ removing or renaming a migration voids it. A branch with no migration file gets no id and is bound to
3722
+ its HEAD alone, as is every record minted before #508.
3719
3723
  It is minted only when ALL of these hold, checked before any network call:
3720
3724
  - the record is well-formed AND passing (approve · checklist pass · escalation clear · CI pass) —
3721
3725
  a grant carrying a failing review is a contradiction, so it is refused, not recorded;
@@ -3730,8 +3734,9 @@ Then, read from CI after the tracker read and before anything is written (#457):
3730
3734
  COLAB_HUMAN=1 is still required for every role. The reviewer identity is DECLARED, not attested.
3731
3735
  \`colab ship\` honours a reviewer grant only when ALL of (#401): P the target's project.yml says
3732
3736
  \`migration-grant: reviewer\` · M this record is live, trusted and passing · HEAD its head is the
3733
- branch's exact remote head · R the live "${migrationGrant.ROUNDTRIP_JOB_PREFIX}" CI job passed on that
3734
- HEAD (re-read by ship, never taken from the record). Any condition failing → a human runs Phase B.
3737
+ branch's exact remote head, or its \`migrations\` id equals the id at that head · R the live
3738
+ "${migrationGrant.ROUNDTRIP_JOB_PREFIX}" CI job passed on the SHIPPED head (re-read by ship, never
3739
+ taken from the record). Any condition failing → a human runs Phase B.
3735
3740
 
3736
3741
  Options:
3737
3742
  --branch <branch> required for --branch grants; a grant is never inferred from HEAD
@@ -3850,11 +3855,22 @@ function migrationGrantReviewRecord(repoAbs, opts) {
3850
3855
  throw new UserError(`--head ${String(opts.head).slice(0, 12)} is not origin's tip of "${opts.branch}" (${tip.slice(0, 12)}) — the review covers a commit the grant would not bind; re-review the tip`);
3851
3856
  }
3852
3857
 
3858
+ // #508: bind what was reviewed — the branch's migration files at the tip, by content. Same path
3859
+ // rule the ship gate fires on (newMigrations), against origin's trunk. A branch with no migration
3860
+ // to review gets no id and stays HEAD-bound.
3861
+ const trunk = resolveTrunk(repoAbs, projectDoc(repoAbs));
3862
+ const remote = git.remoteInfo(repoAbs).name || 'origin';
3863
+ let base = trunk ? `${remote}/${trunk}` : null;
3864
+ if (base && !git.git(['rev-parse', '--verify', '--quiet', `${base}^{commit}`], repoAbs).ok) base = trunk;
3865
+ const migrations = base ? newMigrations(repoAbs, base, tip) : [];
3866
+ const contentId = migrationContentAt(repoAbs, migrations, tip);
3867
+
3853
3868
  const rec = {
3854
3869
  v: '1', role, reviewer: opts.reviewer, head: tip,
3855
3870
  verdict: opts.verdict, checklist: opts.checklist, 'checklist-items': opts.checklistItems,
3856
3871
  escalation: opts.escalation, 'escalation-result': opts.escalationResult,
3857
3872
  'ci-roundtrip': opts.ciRoundtrip, 'ci-run': opts.ciRun,
3873
+ migrations: contentId || undefined,
3858
3874
  };
3859
3875
  for (const k of Object.keys(rec)) if (rec[k] === undefined) delete rec[k];
3860
3876
  const v = migrationGrant.validateReviewRecord(rec);
@@ -3937,7 +3953,11 @@ function cmdMigrationGrantCreate(repoAbs, num, opts) {
3937
3953
 
3938
3954
  if (opts.reviewRecord) {
3939
3955
  print(`Recorded a ${migrationGrant.REVIEWER_ROLE} grant on #${num} in ${shortRepo(repoAbs)} — reviewer "${opts.reviewRecord.reviewer}", branch "${opts.branch}" @ ${opts.reviewRecord.head.slice(0, 12)}.`);
3940
- print(' Bound to that HEAD: any new commit voids it. It expires the moment the issue closes.');
3956
+ if (opts.reviewRecord.migrations) {
3957
+ print(` Bound to the reviewed migration content ${opts.reviewRecord.migrations.slice(0, 12)}: a commit that leaves every migration file byte-identical (a trunk sync) keeps it, any change to one voids it. It expires the moment the issue closes.`);
3958
+ } else {
3959
+ print(' Bound to that HEAD: any new commit voids it. It expires the moment the issue closes.');
3960
+ }
3941
3961
  print(` colab ship honours it only while the "${migrationGrant.ROUNDTRIP_JOB_PREFIX}" CI job has passed on that HEAD and the policy still says reviewer.`);
3942
3962
  print(` Revoke any time: colab migration-grant ${num} --revoke`);
3943
3963
  return 0;
@@ -9616,6 +9636,19 @@ function newMigrations(mainRoot, trunk, branch) {
9616
9636
  return r.stdout.split('\n').filter(Boolean).filter((f) => migrationPaths.isMigrationPath(f, declared));
9617
9637
  }
9618
9638
 
9639
+ /**
9640
+ * #508 — the content id (migration-grant.js migrationContentId) of `paths` — the branch's migration
9641
+ * files, newMigrations' list — as they stand at `sha`: one `git ls-tree` for their blob ids, a path
9642
+ * the commit no longer has counting as deleted. null when the tree cannot be read or there is
9643
+ * nothing to bind; null never matches a recorded id, so an unreadable tree fails the binding closed.
9644
+ */
9645
+ function migrationContentAt(repoAbs, paths, sha) {
9646
+ if (!sha || !Array.isArray(paths) || paths.length === 0) return null;
9647
+ const r = git.git(['ls-tree', '-z', sha, '--', ...paths], repoAbs);
9648
+ if (!r.ok) return null;
9649
+ return migrationGrant.migrationContentId(migrationGrant.migrationEntriesFromLsTree(r.stdout, paths));
9650
+ }
9651
+
9619
9652
  /**
9620
9653
  * The `no new migrations` row, whole (#98, #401) — the ONE function every ship path calls:
9621
9654
  * `ship --dry`, a real or auto-trunk `ship` (both cmdShip), and `ship --dry --json` (cmdShipDryJson,
@@ -9633,6 +9666,8 @@ function newMigrations(mainRoot, trunk, branch) {
9633
9666
  * evaluateShipSet ctx: the policy (P) from project.yml AT THE TARGET TIP — what the branch merges
9634
9667
  * into, not a working file the branch could have edited; the HEAD — the branch's remote head (what
9635
9668
  * CI ran), which must equal the local ref (what the squash takes), or no reviewer grant can bind;
9669
+ * the migration content id at that HEAD (#508), which a content-bound grant matches instead of
9670
+ * the reviewed HEAD — so the merge-of-trunk sync ship itself demands does not void the grant;
9636
9671
  * and R lazily — every job of every run at that HEAD, read only once some issue clears P+M+HEAD.
9637
9672
  */
9638
9673
  function shipMigrationGate(repoAbs, gh, target, branch, issues) {
@@ -9646,7 +9681,7 @@ function shipMigrationGate(repoAbs, gh, target, branch, issues) {
9646
9681
  } else {
9647
9682
  const records = {};
9648
9683
  for (const n of issues) records[n] = git.ghIssueView(repoAbs, n, ['state', 'labels', 'comments']);
9649
- ctx = shipMigrationCtx(repoAbs, gh, target, branch);
9684
+ ctx = shipMigrationCtx(repoAbs, gh, target, branch, migrations);
9650
9685
  grants = migrationGrant.evaluateShipSet(issues, records, branch, labels.MIGRATION_GRANT_LABEL, ctx);
9651
9686
  }
9652
9687
  return { migrations, ok: grants.ok, ...migDetail(migrations, grants, target, branch, ctx) };
@@ -9654,7 +9689,7 @@ function shipMigrationGate(repoAbs, gh, target, branch, issues) {
9654
9689
 
9655
9690
  /** P, HEAD and the R thunk for shipMigrationGate. The thunk memoises its one verdict on the ctx
9656
9691
  * (`roundtripResult`) so the payload can report what R saw without a second read. */
9657
- function shipMigrationCtx(repoAbs, gh, target, branch) {
9692
+ function shipMigrationCtx(repoAbs, gh, target, branch, migrations) {
9658
9693
  const policy = migrationGrant.parseGrantPolicy(projectDocAt(repoAbs, target)).policy;
9659
9694
  const remote = git.remoteInfo(repoAbs).name || 'origin';
9660
9695
  const ls = git.git(['ls-remote', remote, `refs/heads/${branch}`], repoAbs);
@@ -9666,7 +9701,9 @@ function shipMigrationCtx(repoAbs, gh, target, branch) {
9666
9701
  else if (localSha && localSha !== remoteSha) headNote = `local ${branch} is ${localSha.slice(0, 7)}, ${remote} is ${remoteSha.slice(0, 7)} — push or pull until they agree`;
9667
9702
  else headSha = remoteSha;
9668
9703
  const trust = trustAt(repoAbs, target);
9669
- const ctx = { policy, headSha, headNote, roundtripResult: null, trust,
9704
+ // #508: what the branch's migration files ARE at the shipped head, for a content-bound grant.
9705
+ const contentId = headSha ? migrationContentAt(repoAbs, migrations, headSha) : null;
9706
+ const ctx = { policy, headSha, contentId, headNote, roundtripResult: null, trust,
9670
9707
  labelActors: (n) => git.ghIssueLabelActors(repoAbs, n, labels.MIGRATION_GRANT_LABEL) };
9671
9708
  ctx.roundtrip = () => {
9672
9709
  const d = git.git(['diff', '--name-only', `${target}...${branch}`], repoAbs);
@@ -9700,16 +9737,17 @@ function migDetail(migrations, grants, target, branch, ctx) {
9700
9737
  branch, files: [...migrations],
9701
9738
  policy: ctx ? ctx.policy : null,
9702
9739
  headSha: ctx ? ctx.headSha : null,
9740
+ contentId: ctx ? ctx.contentId || null : null,
9703
9741
  // #407: the human list as read from the TARGET — null when undeclared (association class).
9704
9742
  trustHumans: ctx && ctx.trust && ctx.trust.declared ? [...ctx.trust.humans] : null,
9705
9743
  roundtrip: ctx && ctx.roundtripResult ? { ok: ctx.roundtripResult.ok, reason: ctx.roundtripResult.reason } : null,
9706
9744
  granted: grants.granted.map((g) => ({ issue: g.issue, role: g.role || 'human', by: g.by, at: g.at,
9707
- ...(g.role === 'reviewer' ? { reviewer: g.reviewer, head: g.head } : {}) })),
9745
+ ...(g.role === 'reviewer' ? { reviewer: g.reviewer, head: g.head, via: g.via || 'head', migrations: g.migrations || null } : {}) })),
9708
9746
  missing: grants.missing.map((m) => ({ issue: m.issue, failed: m.failed || null,
9709
9747
  reason: m.failed === 'head' && ctx && ctx.headNote ? `${m.reason} (${ctx.headNote})` : m.reason })),
9710
9748
  };
9711
9749
  if (grants.ok) {
9712
- const by = grants.granted.map((g) => (g.role === 'reviewer' ? `#${g.issue} (reviewer ${g.reviewer} @ ${String(g.head).slice(0, 7)}, CI round-trip passed)` : '#' + g.issue)).join(' ');
9750
+ const by = grants.granted.map((g) => (g.role === 'reviewer' ? `#${g.issue} (reviewer ${g.reviewer} @ ${String(g.head).slice(0, 7)}${g.via === 'content' ? `, migration content ${String(g.migrations).slice(0, 12)} unchanged since` : ''}, CI round-trip passed)` : '#' + g.issue)).join(' ');
9713
9751
  const roles = [...new Set(grants.granted.map((g) => g.role || 'human'))].join('+');
9714
9752
  return { text: `${migrations.length} present, exempted by a ${roles} grant on ${by} for branch "${branch}" — ${files}`, payload };
9715
9753
  }
@@ -24,6 +24,10 @@ export const REVIEW_RECORD_FENCE: 'migration-review';
24
24
  export const REVIEW_RECORD_VERSION: '1';
25
25
  export interface ReviewRecordField { key: string; required: boolean; values?: string[]; re?: RegExp; hint?: string; }
26
26
  export const REVIEW_RECORD_FIELDS: ReadonlyArray<ReviewRecordField>;
27
+ /** Canonical tail of a HEAD-bound reviewer grant (a record with no `migrations` content id). */
28
+ export const REVIEW_GRANT_TAIL: string;
29
+ /** Canonical tail of a content-bound reviewer grant (#508 — the record names `migrations`). */
30
+ export const REVIEW_GRANT_CONTENT_TAIL: string;
27
31
 
28
32
  export interface DecodedReviewGrant {
29
33
  role: string; reviewer: string; branch: string;
@@ -60,6 +60,14 @@ const REVIEW_GRANT_MARK = '🔎 Migration review grant';
60
60
  const REVIEWER_ROLE = 'migration-reviewer';
61
61
  const REVIEW_GRANT_RE = /^🔎 Migration review grant — role `([^`]*)` · reviewer `([^`]*)` · branch `([^`]*)` · head `([^`]*)` · host `([^`]*)` · (\S+)/;
62
62
  const REVIEW_GRANT_TAIL = ' — bound to this HEAD: any new commit voids it; expires when this issue closes.';
63
+ /** #508 — the canonical tail of a grant whose record carries `migrations` (a content id): it binds
64
+ * what was reviewed, so a commit that leaves the migration files byte-identical keeps it. */
65
+ const REVIEW_GRANT_CONTENT_TAIL = ' — bound to the reviewed migration content: a change to any migration file voids it; expires when this issue closes.';
66
+ /** The tail a record of this shape gets by default — content-bound when it names a content id. */
67
+ function reviewGrantTail(record) {
68
+ return record && record.migrations !== undefined && record.migrations !== null && String(record.migrations) !== ''
69
+ ? REVIEW_GRANT_CONTENT_TAIL : REVIEW_GRANT_TAIL;
70
+ }
63
71
  /** The fenced block's info string — the record is found by it, never by position. */
64
72
  const REVIEW_RECORD_FENCE = 'migration-review';
65
73
  const REVIEW_RECORD_VERSION = '1';
@@ -67,6 +75,7 @@ const REVIEW_RECORD_VERSION = '1';
67
75
  const SHA40_RE = /^[0-9a-f]{40}$/;
68
76
  const REVIEWER_ID_RE = /^[A-Za-z0-9._@-]+$/;
69
77
  const CONDITION_ID_RE = /^[a-z0-9][a-z0-9-]*$/;
78
+ const SHA256_RE = /^[0-9a-f]{64}$/;
70
79
 
71
80
  /** Every key a v1 record may carry, and what each accepts. `required: false` keys may be absent.
72
81
  * Order here is the order `encodeReviewGrant` writes them in — part of the wire format. */
@@ -82,6 +91,9 @@ const REVIEW_RECORD_FIELDS = Object.freeze([
82
91
  { key: 'escalation-result', required: true, values: ['clear', 'escalated'] },
83
92
  { key: 'ci-roundtrip', required: true, values: ['pass', 'fail', 'pending'] },
84
93
  { key: 'ci-run', required: false, re: /^\S+$/, hint: 'a run id or URL, no spaces' },
94
+ // #508 — the content id of the migration files the review covered (migration-grant.js
95
+ // migrationContentId). Optional: a record without it is bound to `head` alone, as before.
96
+ { key: 'migrations', required: false, re: SHA256_RE, hint: 'a 64-hex sha256 content id of the reviewed migration files' },
85
97
  ]);
86
98
 
87
99
  /**
@@ -92,7 +104,7 @@ const REVIEW_RECORD_FIELDS = Object.freeze([
92
104
  */
93
105
  function encodeReviewGrant({ role, reviewer, branch, head, host, at, tail, record } = {}) {
94
106
  const marker = withTail(`${REVIEW_GRANT_MARK} — role \`${role}\` · reviewer \`${reviewer}\` · branch \`${branch}\``
95
- + ` · head \`${head}\` · host \`${host}\` · ${at}`, tail, REVIEW_GRANT_TAIL);
107
+ + ` · head \`${head}\` · host \`${host}\` · ${at}`, tail, reviewGrantTail(record));
96
108
  return `${marker}\n\n${fencedRecord(REVIEW_RECORD_FENCE, REVIEW_RECORD_FIELDS, record)}`;
97
109
  }
98
110
 
@@ -111,8 +123,11 @@ function decodeReviewGrant(body) {
111
123
  const line = nl === -1 ? text : text.slice(0, nl);
112
124
  const t = line.slice(m[0].length);
113
125
  const out = { role: m[1], reviewer: m[2], branch: m[3], head: m[4], host: m[5], at: m[6],
114
- tail: t === REVIEW_GRANT_TAIL ? null : t, record: null, problems: [] };
115
- return readFencedRecord(text, REVIEW_RECORD_FENCE, out);
126
+ tail: t, record: null, problems: [] };
127
+ readFencedRecord(text, REVIEW_RECORD_FENCE, out);
128
+ // The canonical tail depends on the record's shape (#508), so it is judged once the record is read.
129
+ if (t === reviewGrantTail(out.record)) out.tail = null;
130
+ return out;
116
131
  }
117
132
 
118
133
  /** Find the FIRST fenced block whose info string is exactly `fence` and read its `key: value`
@@ -244,6 +259,7 @@ module.exports = {
244
259
  MIGRATION_GRANT_MARK, MIGRATION_REVOKE_MARK, MIGRATION_GRANT_RE, MIGRATION_REVOKE_RE,
245
260
  encodeMigrationGrant, decodeMigrationGrant, encodeMigrationRevoke, decodeMigrationRevoke,
246
261
  REVIEW_GRANT_MARK, REVIEW_GRANT_RE, REVIEWER_ROLE, REVIEW_RECORD_FENCE, REVIEW_RECORD_VERSION, REVIEW_RECORD_FIELDS,
262
+ REVIEW_GRANT_TAIL, REVIEW_GRANT_CONTENT_TAIL,
247
263
  encodeReviewGrant, decodeReviewGrant,
248
264
  CI_GRANT_MARK, CI_REVOKE_MARK, CI_GRANT_RE, CI_REVOKE_RE,
249
265
  encodeCiGrant, decodeCiGrant, encodeCiRevoke, decodeCiRevoke,
@@ -45,6 +45,7 @@
45
45
  // codec/grants.js (#498, epic #496). Re-exported below under the names this module always had.
46
46
  // Mark design (distinct leading emoji, so neither regex can match the other mark's body) is
47
47
  // documented there; the grant-revoke-mark-collision test still pins it here.
48
+ const crypto = require('crypto');
48
49
  const codec = require('./codec/grants');
49
50
  const GRANT_MARK = codec.MIGRATION_GRANT_MARK;
50
51
  const REVOKE_MARK = codec.MIGRATION_REVOKE_MARK;
@@ -194,13 +195,15 @@ function evaluateIssue(record, branch, issueNum, labelName, opts) {
194
195
  * read (the caller's job, not this function's — see tools/colab's shipMigrationGate).
195
196
  *
196
197
  * `ctx` (#401) — OPTIONAL, and absent means exactly the pre-#401 behaviour (human grants only,
197
- * byte-identical output). Given, it is `{ policy, headSha, roundtrip }` and the ONE rule every
198
+ * byte-identical output). Given, it is `{ policy, headSha, contentId, roundtrip }` and the ONE rule every
198
199
  * ship path shares (`--dry`, `--dry --json`, a real/auto-trunk ship, and batch — which reads
199
200
  * through `--dry --json`) — so no path can accept a grant another refuses. Per issue:
200
201
  * 1. a live human grant passes, unchanged — it wins where both roles exist;
201
202
  * 2. otherwise a reviewer grant passes only when ALL of: P policy is `reviewer` · M a valid,
202
- * passing, trusted, branch-bound reviewer marker + record · HEAD the record's head equals
203
- * `headSha` · R `roundtrip()` says the live CI round-trip passed on that HEAD.
203
+ * passing, trusted, branch-bound reviewer marker + record · HEAD the grant binds the shipped
204
+ * head — the record's head equals `headSha`, or (#508) the record's migration content id
205
+ * equals `contentId`, the id at `headSha` · R `roundtrip()` says the live CI round-trip passed
206
+ * on the SHIPPED head (never the reviewed one).
204
207
  * R is a THUNK, called at most once per set and only once some issue has cleared P, M and HEAD —
205
208
  * so a no-migration, human-granted or already-failing ship pays for no CI read. A thunk returning
206
209
  * anything but `{ ok: true }` (including `null`, a failed read) fails R closed.
@@ -238,23 +241,23 @@ function evaluateShipSet(issues, records, branch, labelName, ctx) {
238
241
  reason: policy === 'reviewer' ? `${h.reason}, and no live reviewer grant either` : h.reason });
239
242
  continue;
240
243
  }
241
- const r = evaluateReviewerGrant(rec, { branch, headSha: ctx.headSha, issueNum: n, labelName, policy });
244
+ const r = evaluateReviewerGrant(rec, { branch, headSha: ctx.headSha, contentId: ctx.contentId, issueNum: n, labelName, policy });
242
245
  if (!r.ok) {
243
246
  const failed = !r.checks.policy ? 'policy' : !r.checks.marker ? 'marker' : 'head';
244
247
  missing.push({ issue: n, failed, reason: `reviewer grant [${SHIP_CONDITION_TAG[failed]}]: ${r.reason}` });
245
248
  continue;
246
249
  }
247
- pending.push({ n, g: r.grant });
250
+ pending.push({ n, g: r.grant, via: r.via });
248
251
  }
249
252
  if (pending.length > 0) {
250
253
  let rt = null;
251
254
  try { rt = typeof ctx.roundtrip === 'function' ? ctx.roundtrip() : null; } catch (_) { rt = null; }
252
255
  const ok = !!rt && rt.ok === true;
253
256
  const why = rt && rt.reason ? rt.reason : 'the CI round-trip could not be read — an unread result is never a pass';
254
- for (const { n, g } of pending) {
257
+ for (const { n, g, via } of pending) {
255
258
  if (ok) {
256
- granted.push({ issue: n, role: 'reviewer', reviewer: g.reviewer, head: g.head,
257
- branch: g.branch, by: g.login, at: g.at });
259
+ granted.push({ issue: n, role: 'reviewer', reviewer: g.reviewer, head: g.head, via,
260
+ migrations: (g.record && g.record.migrations) || null, branch: g.branch, by: g.login, at: g.at });
258
261
  } else {
259
262
  missing.push({ issue: n, failed: 'roundtrip',
260
263
  reason: `reviewer grant [${SHIP_CONDITION_TAG.roundtrip}]: #${n}: ${why}` });
@@ -586,22 +589,76 @@ function liveGrantRecords(comments) {
586
589
  }
587
590
 
588
591
  /**
589
- * HEAD binding. A human grant is branch-bound, not HEAD-bound (unchanged since #98) → unbound, ok.
590
- * A reviewer grant covers exactly the commit it reviewed: ok only when `branchHeadSha` is a full
591
- * 40-hex sha equal (case-insensitively) to the grant's head. A short or missing sha is NOT ok —
592
- * "could not confirm the HEAD" is never read as "the HEAD matches", and never a prefix match.
592
+ * #508 — the CONTENT ID of a branch's migration files: what a reviewer actually reviewed. Pure:
593
+ * `entries` is `[{ path, blob }]`, one per migration path the branch changes against its base
594
+ * (tools/colab newMigrations — the same rule the gate fires on), `blob` the git blob id of that
595
+ * path at the head, or null when the head deletes it. The id is a sha256 over the SORTED
596
+ * `path<TAB>blob` lines, so it is independent of listing order and of everything outside those
597
+ * files: a merge-of-trunk sync, or any commit that leaves every migration byte-identical, keeps
598
+ * it; editing, adding, removing or renaming a migration changes it. Returns null for an empty or
599
+ * unreadable set — there is nothing to bind, and null never equals a recorded id.
593
600
  */
594
- function grantHeadBinding(grant, branchHeadSha) {
595
- if (!grant || grant.role === 'human' || grant.role === undefined) return { bound: false, ok: true, reason: '' };
601
+ function migrationContentId(entries) {
602
+ if (!Array.isArray(entries) || entries.length === 0) return null;
603
+ const lines = [];
604
+ for (const e of entries) {
605
+ if (!e || typeof e.path !== 'string' || e.path === '') return null;
606
+ const blob = e.blob == null ? '-' : String(e.blob).toLowerCase();
607
+ if (blob !== '-' && !/^[0-9a-f]{40}([0-9a-f]{24})?$/.test(blob)) return null;
608
+ lines.push(`${e.path}\t${blob}\n`);
609
+ }
610
+ lines.sort();
611
+ return crypto.createHash('sha256').update(lines.join('')).digest('hex');
612
+ }
613
+
614
+ /**
615
+ * #508 — `git ls-tree -z <sha> -- <paths…>` output → migrationContentId's entries, one per path in
616
+ * `paths` (a path the tree lacks is a deletion: blob null). Pure, so the parse is testable without
617
+ * the CLI; tools/colab migrationContentAt runs the git half.
618
+ */
619
+ function migrationEntriesFromLsTree(stdout, paths) {
620
+ const blobs = new Map();
621
+ for (const rec of String(stdout || '').split('\0')) {
622
+ const m = rec.match(/^\d+ blob ([0-9a-f]+)\t([\s\S]+)$/);
623
+ if (m) blobs.set(m[2], m[1]);
624
+ }
625
+ return (paths || []).map((p) => ({ path: p, blob: blobs.get(p) || null }));
626
+ }
627
+
628
+ const SHA256_RE = /^[0-9a-f]{64}$/;
629
+
630
+ /**
631
+ * The binding of a grant to what the branch now is. A human grant is branch-bound, not HEAD-bound
632
+ * (unchanged since #98) → unbound, ok. A reviewer grant needs `branchHeadSha` to be a full 40-hex
633
+ * sha (R reads CI there; "could not confirm the HEAD" is never read as a match, never a prefix
634
+ * match), and then binds one of two ways:
635
+ * - its record names `migrations` (#508) → CONTENT-bound: ok when the head IS the reviewed head,
636
+ * or when `contentId` — migrationContentId at the head — equals the recorded id. A sync that
637
+ * only merges trunk in keeps the grant; any change to a migration file voids it.
638
+ * - no `migrations` (a record minted before #508) → HEAD-bound, exactly as before: only the
639
+ * reviewed commit itself.
640
+ * Returns { bound, ok, via: 'head' | 'content' | null, reason }.
641
+ */
642
+ function grantHeadBinding(grant, branchHeadSha, contentId) {
643
+ if (!grant || grant.role === 'human' || grant.role === undefined) return { bound: false, ok: true, via: null, reason: '' };
596
644
  const want = String(grant.head || '').toLowerCase();
597
645
  const have = String(branchHeadSha || '').toLowerCase();
598
646
  if (!SHA40_RE.test(have)) {
599
- return { bound: true, ok: false, reason: `cannot confirm the branch HEAD (${have ? `"${have}" is not a full sha` : 'no sha given'}) — a reviewer grant is bound to one commit` };
647
+ return { bound: true, ok: false, via: null, reason: `cannot confirm the branch HEAD (${have ? `"${have}" is not a full sha` : 'no sha given'}) — a reviewer grant is judged at one commit` };
648
+ }
649
+ if (want === have) return { bound: true, ok: true, via: 'head', reason: '' };
650
+ const recorded = grant.record && grant.record.migrations ? String(grant.record.migrations).toLowerCase() : '';
651
+ if (!recorded) {
652
+ return { bound: true, ok: false, via: null, reason: `reviewer grant is bound to ${want.slice(0, 7)}, branch is at ${have.slice(0, 7)} — a new commit voids it (the record names no migration content id, so it binds the HEAD alone)` };
653
+ }
654
+ const now = String(contentId || '').toLowerCase();
655
+ if (!SHA256_RE.test(now)) {
656
+ return { bound: true, ok: false, via: null, reason: `reviewer grant covers migration content ${recorded.slice(0, 12)}, and the content at ${have.slice(0, 7)} could not be read — an unread id is never a match` };
600
657
  }
601
- if (want !== have) {
602
- return { bound: true, ok: false, reason: `reviewer grant is bound to ${want.slice(0, 7)}, branch is at ${have.slice(0, 7)} — a new commit voids it` };
658
+ if (now !== recorded) {
659
+ return { bound: true, ok: false, via: null, reason: `reviewer grant covers migration content ${recorded.slice(0, 12)} (reviewed at ${want.slice(0, 7)}), the branch at ${have.slice(0, 7)} carries ${now.slice(0, 12)} — a migration file changed since the review, which voids it` };
603
660
  }
604
- return { bound: true, ok: true, reason: '' };
661
+ return { bound: true, ok: true, via: 'content', reason: '' };
605
662
  }
606
663
 
607
664
  /** `migration-grant:` values, in project.yml (#398). Absent = human, today's behaviour. */
@@ -630,7 +687,8 @@ function parseGrantPolicy(doc) {
630
687
 
631
688
  /**
632
689
  * The reviewer-grant verdict for one issue — P, M and HEAD of the ship rule; evaluateShipSet()
633
- * (#401) calls it and adds R. `ctx` = { branch, headSha, issueNum, labelName, policy } where
690
+ * (#401) calls it and adds R. `ctx` = { branch, headSha, contentId, issueNum, labelName, policy } where
691
+ * `contentId` (#508) is migrationContentId at `headSha` (grantHeadBinding), and
634
692
  * `policy` is parseGrantPolicy(...).policy. Checks, cheapest/most-fundamental first, each with its
635
693
  * own reason: read failed · not open · no label · policy not `reviewer` · no live reviewer grant ·
636
694
  * branch mismatch · untrusted author · record invalid · record not passing · HEAD binding.
@@ -658,10 +716,10 @@ function evaluateReviewerGrant(record, ctx) {
658
716
  if (!g.valid) return no(`#${issue}'s reviewer grant has an invalid review record: ${(g.problems || []).join('; ') || 'unreadable'}`, g);
659
717
  if (!g.passing) return no(`#${issue}'s review record does not pass: ${reviewRecordFailure(g.record)}`, g);
660
718
  checks.marker = true;
661
- const hb = grantHeadBinding(g, c.headSha);
719
+ const hb = grantHeadBinding(g, c.headSha, c.contentId);
662
720
  if (!hb.ok) return no(`#${issue}: ${hb.reason}`, g);
663
721
  checks.head = true;
664
- return { issue, ok: true, grant: g, reason: '', checks };
722
+ return { issue, ok: true, grant: g, via: hb.via, reason: '', checks };
665
723
  }
666
724
 
667
725
  module.exports = {
@@ -674,6 +732,8 @@ module.exports = {
674
732
  REVIEW_RECORD_FENCE, REVIEW_RECORD_FIELDS,
675
733
  validateReviewRecord, reviewRecordFailure, reviewGrantCommentBody, parseReviewGrant,
676
734
  liveGrantRecords, grantHeadBinding, evaluateReviewerGrant,
735
+ // #508 — bind to the reviewed migration content, not the HEAD
736
+ migrationContentId, migrationEntriesFromLsTree,
677
737
  // #398 — repo policy
678
738
  GRANT_POLICIES, parseGrantPolicy,
679
739
  // #401 — ship honours a reviewer grant