feat: support tab-wide recording and release notes

scripts/build-manifest.mjs

@@ -34,8 +34,13 @@ function artifactFingerprint(artifacts) {
 }
 
 function toVersionEntry(entry) {
+  if (!Array.isArray(entry.notes) || entry.notes.length === 0
+      || entry.notes.some((note) => typeof note !== 'string' || note.trim() === '')) {
+    throw new Error(`release ${entry.version} must contain non-empty notes`);
+  }
   return {
     version: entry.version,
+    notes: entry.notes,
     published_at: entry.built_at,
     commit: entry.commit ?? null,
     artifacts: entry.artifacts.map((a) => ({
@@ -65,6 +70,11 @@ function validate(manifest) {
     if (!Array.isArray(versionEntry.artifacts) || versionEntry.artifacts.length === 0) {
       throw new Error(`version ${versionEntry.version} has no artifacts`);
     }
+    if (versionEntry.notes !== undefined
+        && (!Array.isArray(versionEntry.notes) || versionEntry.notes.length === 0
+          || versionEntry.notes.some((note) => typeof note !== 'string' || note.trim() === ''))) {
+      throw new Error(`version ${versionEntry.version} has invalid notes`);
+    }
     const variants = new Set();
     for (const artifact of versionEntry.artifacts) {
       if (variants.has(artifact.variant)) throw new Error(`duplicate variant ${artifact.variant} in version ${versionEntry.version}`);
@@ -103,8 +113,10 @@ if (args['existing-manifest']) {
 const newEntry = toVersionEntry(entry);
 const idx = versions.findIndex((v) => v.version === entry.version);
 if (idx >= 0 && artifactFingerprint(versions[idx].artifacts) === artifactFingerprint(entry.artifacts)) {
-  // Idempotent rerun: keep the original entry (published_at stays stable).
-  console.log(`version ${entry.version} already in manifest with identical artifacts; kept as-is`);
+  // An idempotent rerun may backfill release notes without changing immutable
+  // artifacts or their original publication metadata.
+  versions[idx] = { ...versions[idx], notes: newEntry.notes };
+  console.log(`version ${entry.version} already in manifest with identical artifacts; release notes synchronized`);
 } else {
   if (idx >= 0) {
     versions.splice(idx, 1);

scripts/package-release.mjs

@@ -65,6 +65,11 @@ const distDir = resolve(root, String(args.dist ?? 'dist'));
 
 const pkg = JSON.parse(await readFile(resolve(root, 'package.json'), 'utf8'));
 const { version } = pkg;
+const notesByVersion = JSON.parse(await readFile(resolve(root, 'release-notes.json'), 'utf8'));
+const notes = notesByVersion[version]?.map((note) => String(note).trim()).filter(Boolean);
+if (!Array.isArray(notes) || notes.length === 0) {
+  throw new Error(`release-notes.json must contain at least one note for version ${version}`);
+}
 
 let commit = null;
 try {
@@ -138,6 +143,6 @@ for (const target of VARIANTS) {
   console.log(`packaged ${filename} (${size} bytes, sha256 ${sha256.slice(0, 12)}…)`);
 }
 
-const entry = { version, commit, built_at: new Date().toISOString(), artifacts };
+const entry = { version, notes, commit, built_at: new Date().toISOString(), artifacts };
 await writeFile(resolve(distDir, 'release-entry.json'), `${JSON.stringify(entry, null, 2)}\n`);
 console.log(`release entry written: ${resolve(distDir, 'release-entry.json').slice(root.length + 1)} (version ${version})`);

scripts/verify-public.mjs

@@ -89,6 +89,8 @@ const manifest = JSON.parse(manifestBytes.toString('utf8'));
 assert(manifest.latest === entry.version, `manifest.latest ${manifest.latest} != ${entry.version}`);
 const versionEntry = manifest.versions.find((v) => v.version === entry.version);
 assert(versionEntry, `manifest has no entry for version ${entry.version}`);
+assert(JSON.stringify(versionEntry.notes) === JSON.stringify(entry.notes),
+  `manifest release notes do not match release entry for ${entry.version}`);
 assert(versionEntry.artifacts.length === entry.artifacts.length,
   `manifest artifacts count ${versionEntry.artifacts.length} != ${entry.artifacts.length}`);
 for (const artifact of entry.artifacts) {