@opengsd/gsd-core 1.18.0 → 1.20.0

package/gsd-core/bin/lib/markdown-sectionizer.cjs

@@ -25,8 +25,13 @@ exports.updateBullet = updateBullet;
 exports.updateHeading = updateHeading;
 exports.extractTaggedBlocks = extractTaggedBlocks;
 exports.stripTaggedBlocks = stripTaggedBlocks;
+exports.editOutsideTaggedBlocks = editOutsideTaggedBlocks;
+exports.maskFences = maskFences;
+exports.editOutsideFences = editOutsideFences;
 exports.replaceSection = replaceSection;
 exports.withSection = withSection;
+exports.headingSliceRange = headingSliceRange;
+exports.editHeadingSlice = editHeadingSlice;
 exports.deleteSection = deleteSection;
 exports.extractXmlTagBodies = extractXmlTagBodies;
 const pattern_cjs_1 = require("./pattern.cjs");
@@ -850,6 +855,116 @@ function stripTaggedBlocks(content, tagName, allowAttributes = false, caseSensit
         return content;
     return content.replace(taggedBlockPattern(tagName, caseSensitive ? 'g' : 'gi', allowAttributes), '');
 }
+/**
+ * Run `edit` over `content` with every `<tagName>…</tagName>` block hidden from
+ * it, then put the blocks back byte-for-byte (#5543). The blocks are swapped for
+ * one-line placeholder comments, so `edit` sees the rest of the document in its
+ * original order and cannot touch, or be captured by, a block's contents.
+ *
+ * Same hardened block pattern as `stripTaggedBlocks` (exact `<tag>` opener, so
+ * `<details open>` stays visible to `edit`). If `edit` returns a non-string, or
+ * drops a placeholder, the original `content` is returned unchanged rather than
+ * a document with a block missing.
+ *
+ * Nested blocks are NOT supported, exactly as for `extractTaggedBlocks` and
+ * `stripTaggedBlocks`: the first `</tag>` closes the block. Every ROADMAP reader
+ * that strips shipped milestones shares that grammar, so this writer sees the
+ * same blocks those readers do.
+ */
+function editOutsideTaggedBlocks(content, tagName, edit, allowAttributes = false, caseSensitive = false) {
+    if (typeof content !== 'string' || content.length === 0)
+        return content;
+    if (typeof tagName !== 'string' || tagName.length === 0)
+        return edit(content);
+    const blocks = [];
+    let nonce = 0;
+    while (content.includes(`<!-- gsd-masked-${tagName}-${nonce}-`))
+        nonce += 1;
+    const placeholder = (i) => `<!-- gsd-masked-${tagName}-${nonce}-${i} -->`;
+    const masked = content.replace(taggedBlockPattern(tagName, caseSensitive ? 'g' : 'gi', allowAttributes), (block) => {
+        blocks.push(block);
+        return placeholder(blocks.length - 1);
+    });
+    if (blocks.length === 0)
+        return edit(content);
+    const edited = edit(masked);
+    if (typeof edited !== 'string')
+        return content;
+    let restored = edited;
+    for (let i = 0; i < blocks.length; i++) {
+        const marker = placeholder(i);
+        const at = restored.indexOf(marker);
+        if (at === -1 || restored.indexOf(marker, at + marker.length) !== -1)
+            return content;
+        restored = restored.slice(0, at) + blocks[i] + restored.slice(at + marker.length);
+    }
+    return restored;
+}
+/**
+ * Hide every fenced code block from a line-oriented edit. State-transition writers locate their
+ * target with `/^Field:.*$/m`-style patterns; those match a fenced EXAMPLE of the field as readily
+ * as the live line, so the example got the new value and the live line stayed stale. Masking each
+ * block to a single `<!-- gsd-masked-fence-… -->` line lets the same pattern see only live lines;
+ * `restore` splices the blocks back byte-for-byte (CRLF included — the original line text is kept).
+ * The fence grammar is `scanFencedBlocks`' (the one every reader here uses), and an unterminated
+ * fence masks to the end of the content, as `stripFencedCode` treats it.
+ */
+function maskFences(content) {
+    const identity = { masked: content, restore: (edited) => edited };
+    if (typeof content !== 'string' || content.length === 0)
+        return identity;
+    const lines = content.split('\n');
+    const blocks = scanFencedBlocks(lines);
+    if (blocks.length === 0)
+        return identity;
+    let nonce = 0;
+    while (content.includes(`<!-- gsd-masked-fence-${nonce}-`))
+        nonce += 1;
+    const placeholder = (i) => `<!-- gsd-masked-fence-${nonce}-${i} -->`;
+    const kept = [];
+    const originals = [];
+    let cursor = 0;
+    for (const block of blocks) {
+        const end = block.closeLineIdx === -1 ? lines.length - 1 : block.closeLineIdx;
+        for (; cursor < block.openLineIdx; cursor++)
+            kept.push(lines[cursor]);
+        originals.push(lines.slice(block.openLineIdx, end + 1).join('\n'));
+        kept.push(placeholder(originals.length - 1));
+        cursor = end + 1;
+    }
+    for (; cursor < lines.length; cursor++)
+        kept.push(lines[cursor]);
+    return {
+        masked: kept.join('\n'),
+        restore(edited) {
+            if (typeof edited !== 'string')
+                return null;
+            let restored = edited;
+            for (let i = 0; i < originals.length; i++) {
+                const marker = placeholder(i);
+                const at = restored.indexOf(marker);
+                if (at === -1 || restored.indexOf(marker, at + marker.length) !== -1)
+                    return null;
+                restored = restored.slice(0, at) + originals[i] + restored.slice(at + marker.length);
+            }
+            return restored;
+        },
+    };
+}
+/**
+ * Run `edit` over `content` with every fenced code block hidden from it (see `maskFences`).
+ * Content without a fence is edited as given. An edit that returns a non-string, or that loses a
+ * placeholder, returns the original content unchanged.
+ */
+function editOutsideFences(content, edit) {
+    if (typeof content !== 'string' || content.length === 0)
+        return content;
+    const mask = maskFences(content);
+    const edited = edit(mask.masked);
+    if (typeof edited !== 'string')
+        return content;
+    return mask.restore(edited) ?? content;
+}
 // ─── replaceSection ───────────────────────────────────────────────────────────
 /**
  * Splice `newBody` in place of a section's body and return the resulting
@@ -922,6 +1037,29 @@ function withSection(content, target, edit, opts = {}) {
         return content;
     return replaceSection(content, section, newBody);
 }
+/**
+ * Range of the slice that starts at `headings[index]` and runs to the next
+ * heading of level <= `maxLevel` (fence-aware: `headings` comes from
+ * `tokenizeHeadings`). Unlike `collectSection` it keeps the heading line and
+ * every trailing byte, so a caller that edits the slice can splice it back
+ * byte-exact (#5762).
+ */
+function headingSliceRange(content, headings, index, maxLevel = 2) {
+    const next = headings.slice(index + 1).find((h) => h.level <= maxLevel);
+    return { start: headings[index].offset, end: next ? next.offset : content.length };
+}
+/**
+ * Run `edit` on `content.slice(range.start, end)` and splice the result back,
+ * where `end` excludes the single newline that precedes the next heading — the
+ * slice the pre-owner writers cut with `search(/\n#{1,2}[ \t]/)` — so a row
+ * inserted at the end of a table keeps the blank line before that heading.
+ */
+function editHeadingSlice(content, range, edit) {
+    const end = range.end < content.length && range.end > range.start && content[range.end - 1] === '\n'
+        ? range.end - 1
+        : range.end;
+    return content.slice(0, range.start) + edit(content.slice(range.start, end)) + content.slice(end);
+}
 // ─── deleteSection ────────────────────────────────────────────────────────────
 /**
  * Delete an entire section — the matching heading line ITSELF plus its body —
@@ -952,6 +1090,8 @@ function withSection(content, target, edit, opts = {}) {
  * double-blank gap accumulates where the section used to sit. Content
  * elsewhere in the document is never touched.
  *
+ * `endOffset` adds an optional caller-owned maximum boundary. It never widens
+ * the heading-level range, and callers that omit it retain the legacy bytes.
  * Returns `content` unchanged when no heading matches `headingPredicate`
  * (bounded no-op, mirroring `withSection`'s miss behaviour).
  */
@@ -990,7 +1130,13 @@ function deleteSection(content, headingPredicate, opts = {}) {
     }
     const eofOffset = acc;
     const sectionStart = lineOffsets[target.line - 1]; // start of the target heading LINE itself
-    const sectionEnd = stopLine <= lines.length ? lineOffsets[stopLine - 1] : eofOffset;
+    const headingBoundedEnd = stopLine <= lines.length ? lineOffsets[stopLine - 1] : eofOffset;
+    const explicitEnd = typeof opts.endOffset === 'number' && Number.isFinite(opts.endOffset)
+        ? Math.max(0, Math.min(content.length, opts.endOffset))
+        : headingBoundedEnd;
+    const sectionEnd = Math.min(headingBoundedEnd, explicitEnd);
+    if (sectionEnd <= sectionStart)
+        return content;
     const before = content.slice(0, sectionStart);
     const after = content.slice(sectionEnd);
     // Collapse a resulting blank-line seam to at most one blank line (2 newlines).

package/gsd-core/bin/lib/markdown-table.cjs

@@ -25,6 +25,7 @@ exports.escapeCell = escapeCell;
 exports.appendQuickTaskRow = appendQuickTaskRow;
 exports.migrateQuickTasksTable = migrateQuickTasksTable;
 exports.resetQuickTaskRows = resetQuickTaskRows;
+exports.updateTraceabilityCell = updateTraceabilityCell;
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
 // ─── Schema registry ──────────────────────────────────────────────────────────
 /**
@@ -978,5 +979,27 @@ function resetQuickTaskRows(stateContent) {
     const content = (0, markdown_sectionizer_cjs_1.replaceSection)(stateContent, section, newBody);
     return { ok: true, value: { content, cleared, variant: match.label } };
 }
+/**
+ * `updateTableCell` scoped to REQUIREMENTS.md's `## Traceability` (or
+ * `## Traceability Status`) section (#2245 F1, #5762): `updateTableCell` binds
+ * to the first table it finds, and the shipped template puts an `## Out of
+ * Scope` table (`Feature | Reason`, no `Status` column) before Traceability, so
+ * an unscoped call never reaches the real rows. The ONE copy of this slice
+ * (it used to live in both milestone.cts and phase.cts); the heading rule is
+ * the Progress owner's — first level-2 heading outside fenced code, running to
+ * the next level-1/2 heading. No such heading: the whole text, as before.
+ */
+function updateTraceabilityCell(text, match, column, newValue) {
+    const headings = (0, markdown_sectionizer_cjs_1.tokenizeHeadings)(text);
+    const index = headings.findIndex((h) => h.level === 2 && /^Traceability(?:[ \t]+Status)?\b/i.test(h.text));
+    if (index === -1)
+        return updateTableCell(text, match, column, newValue);
+    let result = { ok: false, reason: 'no matching row' };
+    const edited = (0, markdown_sectionizer_cjs_1.editHeadingSlice)(text, (0, markdown_sectionizer_cjs_1.headingSliceRange)(text, headings, index, 2), (scoped) => {
+        result = updateTableCell(scoped, match, column, newValue);
+        return result.ok ? result.value : scoped;
+    });
+    return result.ok ? { ok: true, value: edited } : result;
+}
 // Consumers: require('../gsd-core/bin/lib/markdown-table.cjs')
 // Named CJS exports are the canonical surface (ADR-457 .cts → .cjs build-at-publish).

package/gsd-core/bin/lib/mcp-server.cjs

@@ -109,10 +109,10 @@ const TOOLS = [
             type: 'object',
             properties: {
                 family: { type: 'string', description: 'Command family (e.g. "query", "state", "phase").' },
-                subcommand: { type: 'string', description: 'Subcommand name.' },
+                subcommand: { type: 'string', description: 'Subcommand name, if the command takes one. Omit or leave empty for family-only commands.' },
                 args: { type: 'array', items: {}, description: 'Positional args.' },
             },
-            required: ['family', 'subcommand'],
+            required: ['family'],
         },
     },
     {
@@ -182,10 +182,13 @@ function callTool(name, args, ctx) {
         if (name === 'gsd_invoke_command') {
             const family = asString(a.family);
             const subcommand = asString(a.subcommand);
-            if (!family || !subcommand) {
-                return { isError: true, content: [{ type: 'text', text: 'gsd_invoke_command requires string "family" and "subcommand".' }] };
+            if (!family) {
+                return { isError: true, content: [{ type: 'text', text: 'gsd_invoke_command requires a non-empty string "family".' }] };
             }
-            const res = dispatchGsdCommand({ family, subcommand, args: Array.isArray(a.args) ? a.args : [], cwd });
+            if (a.subcommand !== undefined && subcommand === null) {
+                return { isError: true, content: [{ type: 'text', text: 'gsd_invoke_command requires string "subcommand" when provided.' }] };
+            }
+            const res = dispatchGsdCommand({ family, subcommand: subcommand ?? undefined, args: Array.isArray(a.args) ? a.args : [], cwd });
             if (!res.ok) {
                 return { isError: true, content: [{ type: 'text', text: res.stderr || res.stdout || `dispatch failed (exit ${res.code})` }] };
             }

package/gsd-core/bin/lib/milestone-lock.cjs

@@ -57,6 +57,7 @@ exports.releaseMilestonePhase = releaseMilestonePhase;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const clock_cjs_1 = require("./clock.cjs");
+const git_info_exclude_cjs_1 = require("./git-info-exclude.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-workspace.cjs is an export= CommonJS module
 const planningWorkspace = require("./planning-workspace.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- active-workstream-store.cjs is an export= CommonJS module
@@ -122,7 +123,13 @@ function readClaim(cwd) {
 }
 function writeClaim(cwd, claim) {
     ensureClaimDir(cwd);
-    node_fs_1.default.writeFileSync(milestoneLockPath(cwd), JSON.stringify(claim, null, 2) + '\n');
+    const lockPath = milestoneLockPath(cwd);
+    node_fs_1.default.writeFileSync(lockPath, JSON.stringify(claim, null, 2) + '\n');
+    // #5551: the claim is per-machine state, never project content. Keep it out
+    // of `git status` (the ship preflight refuses a dirty tree). Every write, not
+    // only the first, so a claim file that predates this fix is covered too; the
+    // helper is idempotent and best-effort.
+    (0, git_info_exclude_cjs_1.excludeFromGit)(node_path_1.default.dirname(lockPath), exports.MILESTONE_LOCK_FILENAME);
 }
 // planningWorkspace.planningDir targets .planning (or the workstream-scoped
 // variant); the parent is created by every GSD command that gets this far, but

package/gsd-core/bin/lib/milestone-release-map.cjs

@@ -0,0 +1,244 @@
+"use strict";
+/**
+ * Milestone Release Map — validation, rendering and archive read-back for the
+ * per-repository release record `milestone complete --release-map` persists
+ * (#5706, phase 2 of epic #3628, docs/adr/3628-milestone-release-mapping.md).
+ *
+ * A release map is the caller-supplied record of what each repository shipped
+ * for a milestone. It is data: this module never resolves a repository to a
+ * directory, never consults `planning.sub_repos`, and never creates a tag. The
+ * map is archived by recorded value, so a repository that later leaves
+ * `planning.sub_repos` does not change an already-archived map.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RELEASE_MAP_TAG_STATES = exports.RELEASE_MAP_STATUSES = exports.MAX_RELEASE_MAP_FILE_BYTES = exports.MAX_RELEASE_MAP_FIELD_LENGTH = exports.MAX_RELEASE_MAP_ENTRIES = void 0;
+exports.validateReleaseMap = validateReleaseMap;
+exports.renderReleaseMapMarkdown = renderReleaseMapMarkdown;
+exports.releaseMapArchivePath = releaseMapArchivePath;
+exports.serializeReleaseMapArchive = serializeReleaseMapArchive;
+exports.loadReleaseMapFile = loadReleaseMapFile;
+exports.readArchivedReleaseMap = readArchivedReleaseMap;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const security_cjs_1 = require("./security.cjs");
+/** Maximum number of entries a single release map may carry. */
+exports.MAX_RELEASE_MAP_ENTRIES = 256;
+/** Maximum length (UTF-16 code units) of any single string field in an entry. */
+exports.MAX_RELEASE_MAP_FIELD_LENGTH = 200;
+/** Maximum size in bytes of a `--release-map` input file. */
+exports.MAX_RELEASE_MAP_FILE_BYTES = 1048576;
+/** Allowed values of an entry's `status`. */
+exports.RELEASE_MAP_STATUSES = Object.freeze(['released', 'deployed', 'unreleased']);
+/** Allowed values of an entry's `tag`. */
+exports.RELEASE_MAP_TAG_STATES = Object.freeze(['created', 'already_tagged', 'skipped', 'none']);
+const OPTIONAL_STRING_FIELDS = ['release', 'reference', 'environment'];
+const ENTRY_FIELDS = Object.freeze(['repo', ...OPTIONAL_STRING_FIELDS, 'status', 'tag']);
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function describeType(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+/**
+ * Validate a release map (an array of entries) and return the normalized
+ * entries. Every problem is reported in one pass so a caller fixes the file
+ * once. Strict on shape: unknown fields are an error, not silently dropped.
+ */
+function validateReleaseMap(input) {
+    if (!Array.isArray(input)) {
+        return { ok: false, errors: [`release map must be an array of entries (got ${describeType(input)})`] };
+    }
+    const errors = [];
+    if (input.length > exports.MAX_RELEASE_MAP_ENTRIES) {
+        errors.push(`release map has ${input.length} entries; the maximum is ${exports.MAX_RELEASE_MAP_ENTRIES}`);
+    }
+    const map = [];
+    const seenRepos = new Set();
+    const limit = Math.min(input.length, exports.MAX_RELEASE_MAP_ENTRIES);
+    for (let i = 0; i < limit; i++) {
+        const raw = input[i];
+        const label = `entries[${i}]`;
+        if (!isPlainObject(raw)) {
+            errors.push(`${label} must be an object (got ${describeType(raw)})`);
+            continue;
+        }
+        let entryOk = true;
+        for (const key of Object.keys(raw)) {
+            if (!ENTRY_FIELDS.includes(key)) {
+                errors.push(`${label} has unknown field "${key.slice(0, exports.MAX_RELEASE_MAP_FIELD_LENGTH)}"`);
+                entryOk = false;
+            }
+        }
+        const repo = raw['repo'];
+        if (typeof repo !== 'string' || repo.trim() === '') {
+            errors.push(`${label}.repo must be a non-blank string`);
+            entryOk = false;
+        }
+        else if (repo.length > exports.MAX_RELEASE_MAP_FIELD_LENGTH) {
+            errors.push(`${label}.repo exceeds ${exports.MAX_RELEASE_MAP_FIELD_LENGTH} characters`);
+            entryOk = false;
+        }
+        else if (seenRepos.has(repo)) {
+            errors.push(`${label}.repo is a duplicate of an earlier entry`);
+            entryOk = false;
+        }
+        else {
+            seenRepos.add(repo);
+        }
+        const optional = {};
+        for (const field of OPTIONAL_STRING_FIELDS) {
+            const value = raw[field];
+            if (value === undefined || value === null) {
+                optional[field] = null;
+            }
+            else if (typeof value !== 'string') {
+                errors.push(`${label}.${field} must be a string or null (got ${describeType(value)})`);
+                entryOk = false;
+            }
+            else if (value.length > exports.MAX_RELEASE_MAP_FIELD_LENGTH) {
+                errors.push(`${label}.${field} exceeds ${exports.MAX_RELEASE_MAP_FIELD_LENGTH} characters`);
+                entryOk = false;
+            }
+            else {
+                optional[field] = value;
+            }
+        }
+        const status = raw['status'];
+        if (typeof status !== 'string' || !exports.RELEASE_MAP_STATUSES.includes(status)) {
+            errors.push(`${label}.status must be one of: ${exports.RELEASE_MAP_STATUSES.join(', ')}`);
+            entryOk = false;
+        }
+        const tag = raw['tag'];
+        if (typeof tag !== 'string' || !exports.RELEASE_MAP_TAG_STATES.includes(tag)) {
+            errors.push(`${label}.tag must be one of: ${exports.RELEASE_MAP_TAG_STATES.join(', ')}`);
+            entryOk = false;
+        }
+        if (entryOk) {
+            map.push({
+                repo: repo,
+                release: optional['release'] ?? null,
+                reference: optional['reference'] ?? null,
+                environment: optional['environment'] ?? null,
+                status: status,
+                tag: tag,
+            });
+        }
+    }
+    if (errors.length > 0)
+        return { ok: false, errors };
+    return { ok: true, map };
+}
+/**
+ * Escape one value for a GFM table cell: a pipe, newline, backtick, angle
+ * bracket or other markdown control character in recorded data can neither
+ * end the cell, start a new row, nor inject structure (headings, HTML).
+ */
+function escapeCell(value) {
+    if (value === null)
+        return '-';
+    const flattened = value.replace(/[\u0000-\u001f\u007f\u2028\u2029]+/g, ' ').trim();
+    if (flattened === '')
+        return '-';
+    const escaped = flattened.replace(/[\\|`*_[\]<>&~#!]/g, (ch) => {
+        if (ch === '<')
+            return '&lt;';
+        if (ch === '>')
+            return '&gt;';
+        if (ch === '&')
+            return '&amp;';
+        return `\\${ch}`;
+    });
+    return escaped;
+}
+/**
+ * Render a validated release map as the `**Release mapping:**` markdown block
+ * appended to a MILESTONES.md entry. One table row per entry, always six cells.
+ */
+function renderReleaseMapMarkdown(map) {
+    const lines = [
+        '**Release mapping:**',
+        '',
+        '| Repository | Release | Reference | Environment | Status | Tag |',
+        '| --- | --- | --- | --- | --- | --- |',
+    ];
+    for (const entry of map) {
+        lines.push(`| ${escapeCell(entry.repo)} | ${escapeCell(entry.release)} | ${escapeCell(entry.reference)} | ${escapeCell(entry.environment)} | ${escapeCell(entry.status)} | ${escapeCell(entry.tag)} |`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+/** Path of the archived release map for a milestone version. */
+function releaseMapArchivePath(milestonesDir, version) {
+    return node_path_1.default.join(milestonesDir, `${version}-RELEASE-MAP.json`);
+}
+/** Serialize the archive document `{ version, entries }`. */
+function serializeReleaseMapArchive(version, map) {
+    return `${JSON.stringify({ version, entries: map }, null, 2)}\n`;
+}
+/**
+ * Read and validate a caller-supplied `--release-map` file. Refuses anything
+ * that is not a regular file (directory, FIFO, device), anything over 1 MiB and
+ * anything unreadable or unparseable, without ever opening a non-regular file.
+ */
+function loadReleaseMapFile(filePath) {
+    let stat;
+    try {
+        stat = node_fs_1.default.statSync(filePath);
+    }
+    catch (err) {
+        const code = err.code ?? 'unknown';
+        return { ok: false, errors: [`release map file cannot be read (${code}): ${node_path_1.default.basename(filePath)}`] };
+    }
+    if (!stat.isFile()) {
+        return { ok: false, errors: [`release map path is not a regular file: ${node_path_1.default.basename(filePath)}`] };
+    }
+    if (stat.size > exports.MAX_RELEASE_MAP_FILE_BYTES) {
+        return { ok: false, errors: [`release map file is ${stat.size} bytes; the maximum is ${exports.MAX_RELEASE_MAP_FILE_BYTES}`] };
+    }
+    let text;
+    try {
+        text = node_fs_1.default.readFileSync(filePath, 'utf-8');
+    }
+    catch (err) {
+        const code = err.code ?? 'unknown';
+        return { ok: false, errors: [`release map file cannot be read (${code}): ${node_path_1.default.basename(filePath)}`] };
+    }
+    const parsed = (0, security_cjs_1.safeJsonParse)(text, { maxLength: exports.MAX_RELEASE_MAP_FILE_BYTES, label: 'release map' });
+    if (!parsed.ok) {
+        return { ok: false, errors: [parsed.error ?? 'release map: invalid JSON'] };
+    }
+    return validateReleaseMap(parsed.value);
+}
+/**
+ * Read a milestone's archived release map back by recorded value. A milestone
+ * archived without a map yields `{ ok: true, map: null }` ("no map"), never an
+ * error; a present-but-corrupt archive is reported, not guessed at.
+ */
+function readArchivedReleaseMap(milestonesDir, version) {
+    const file = releaseMapArchivePath(milestonesDir, version);
+    let text;
+    try {
+        text = node_fs_1.default.readFileSync(file, 'utf-8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return { ok: true, map: null };
+        return { ok: false, error: `release map archive cannot be read: ${node_path_1.default.basename(file)}` };
+    }
+    const parsed = (0, security_cjs_1.safeJsonParse)(text, { maxLength: exports.MAX_RELEASE_MAP_FILE_BYTES, label: 'release map archive' });
+    if (!parsed.ok)
+        return { ok: false, error: parsed.error ?? 'release map archive: invalid JSON' };
+    const doc = parsed.value;
+    if (!isPlainObject(doc))
+        return { ok: false, error: 'release map archive: expected an object' };
+    const validated = validateReleaseMap(doc['entries']);
+    if (!validated.ok)
+        return { ok: false, error: validated.errors.join('; ') };
+    return { ok: true, map: validated.map };
+}