agentic-workflow-manager 9.19.0 → 9.20.0

package/dist/src/core/changes/render.js

@@ -0,0 +1,178 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderSkeleton = renderSkeleton;
+exports.refreshDerived = refreshDerived;
+const util_1 = require("util");
+const js_yaml_1 = __importDefault(require("js-yaml"));
+const parse_1 = require("./parse");
+const text_safety_1 = require("./text-safety");
+const types_1 = require("./types");
+// CORE_SCHEMA on both sides: the validator parses with it, so what is dumped here is exactly what it will read back.
+const DUMP = { lineWidth: -1, noRefs: true, sortKeys: false, schema: js_yaml_1.default.CORE_SCHEMA };
+const REPLACED = [...types_1.DERIVED_KEYS, 'verification'];
+const isBareKeyChar = (c) => /^[\w.-]$/.test(c);
+const bare = (line) => (line.endsWith('\r') ? line.slice(0, -1) : line);
+/**
+ * The record skeleton: derived fields and verification are real, every narrative field and body section holds the pending marker.
+ * Returns null when the input cannot be dumped, or when the dump does not read back as the same data. Never throws.
+ */
+function renderSkeleton(input) {
+    try {
+        if (!(0, text_safety_1.isObj)(input) || typeof input.id !== 'string' || !(0, text_safety_1.isObj)(input.fields) || !(0, text_safety_1.isObj)(input.verification))
+            return null;
+        const front = {
+            schema: types_1.RECORD_SCHEMA,
+            id: input.id,
+            title: types_1.PENDING_MARKER,
+            summary_short: types_1.PENDING_MARKER,
+            ...Object.fromEntries(types_1.DERIVED_KEYS.map((k) => [k, input.fields[k]])),
+        };
+        if ((0, text_safety_1.isObj)(input.links) && Object.keys(input.links).length > 0)
+            front.links = input.links;
+        front.verification = input.verification;
+        front.manual_validation = [{ step: types_1.PENDING_MARKER, expected: types_1.PENDING_MARKER }];
+        front.risks = [types_1.PENDING_MARKER];
+        front.rollback = types_1.PENDING_MARKER;
+        if ((0, text_safety_1.isObj)(input.provenance) && Object.keys(input.provenance).length > 0)
+            front.provenance = input.provenance;
+        const dumped = js_yaml_1.default.dump(front, DUMP);
+        const back = (0, parse_1.loadFrontmatter)(dumped.replace(/\n$/, ''));
+        if (!back.ok || !(0, util_1.isDeepStrictEqual)(back.value, front))
+            return null;
+        const body = types_1.BODY_HEADINGS.map((h) => `${h}\n\n${types_1.PENDING_MARKER}\n`).join('\n');
+        return `---\n${dumped}---\n\n${body}`;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The key of a top-level `key: ...` line, or null when the line does not start a mapping entry the scan understands. Accepted
+ * spellings: bare (`type:`), double- or single-quoted on one line, each with optional spaces or tabs before the colon. A quoted
+ * key that needs unescaping (`\"`, `\u0074`, `''`) returns its raw text, which never equals a derived key name: such an
+ * entry is kept as it is, and a record that only spells a derived key that way fails the "every key seen" check instead.
+ * A single left-to-right index scan: linear in the line, no regular expression over file text.
+ */
+function topKey(line) {
+    let i = 0;
+    let key;
+    const first = line.charAt(0);
+    if (first === '"' || first === "'") {
+        for (i = 1;; i++) {
+            if (i >= line.length)
+                return null;
+            const c = line[i];
+            if (first === '"' && c === '\\') {
+                i++;
+                continue;
+            }
+            if (c === first) {
+                if (first === "'" && line[i + 1] === "'") {
+                    i++;
+                    continue;
+                }
+                break;
+            }
+        }
+        key = line.slice(1, i);
+        i++;
+    }
+    else {
+        if (!/^[A-Za-z_]$/.test(first))
+            return null;
+        for (i = 1; i < line.length && isBareKeyChar(line[i]); i++)
+            ;
+        key = line.slice(0, i);
+    }
+    while (line[i] === ' ' || line[i] === '\t')
+        i++;
+    if (line[i] !== ':')
+        return null;
+    const after = line[i + 1];
+    if (after !== undefined && after !== ' ' && after !== '\t' && after !== '\r')
+        return null;
+    return key;
+}
+/** Blank lines and comments after a block's last content line belong to what follows, not to the value. */
+const isFiller = (line) => {
+    const t = bare(line).trim();
+    return t === '' || t.startsWith('#');
+};
+function splice(raw, fields, verification) {
+    if (typeof raw !== 'string' || !(0, text_safety_1.isObj)(fields) || !(0, text_safety_1.isObj)(verification))
+        return null;
+    const split = (0, parse_1.splitRecord)(raw);
+    if (!split.ok)
+        return null;
+    const loaded = (0, parse_1.loadFrontmatter)(split.frontmatterText);
+    if (!loaded.ok || !(0, text_safety_1.isObj)(loaded.value))
+        return null;
+    const before = loaded.value;
+    const fresh = { ...Object.fromEntries(types_1.DERIVED_KEYS.map((k) => [k, fields[k]])), verification };
+    // Work on the raw lines, not on the normalized text: each line keeps its own terminator (CRLF, LF or mixed).
+    const lines = raw.split('\n');
+    const close = lines.findIndex((l, i) => i > 0 && bare(l) === '---');
+    if (bare(lines[0]) !== '---' || close < 1 || close >= lines.length - 1)
+        return null;
+    const starts = [];
+    const keys = [];
+    for (let i = 1; i < close; i++) {
+        const key = topKey(lines[i]);
+        if (key !== null) {
+            starts.push(i);
+            keys.push(key);
+        }
+    }
+    if (starts.length === 0)
+        return null;
+    const seen = new Set();
+    const out = lines.slice(0, starts[0]);
+    starts.forEach((start, n) => {
+        const end = starts[n + 1] ?? close;
+        const key = keys[n];
+        if (!REPLACED.includes(key)) {
+            out.push(...lines.slice(start, end));
+            return;
+        }
+        seen.add(key);
+        let last = end - 1;
+        while (last > start && isFiller(lines[last]))
+            last--;
+        const cr = lines[start].endsWith('\r') ? '\r' : '';
+        const dumped = js_yaml_1.default.dump({ [key]: fresh[key] }, DUMP).replace(/\n$/, '').split('\n').map((l) => l + cr);
+        out.push(...dumped, ...lines.slice(last + 1, end));
+    });
+    out.push(...lines.slice(close));
+    if (!REPLACED.every((k) => seen.has(k)))
+        return null;
+    const next = out.join('\n');
+    // Fail closed: the result must parse and hold, for every key of the original, the fresh value (replaced keys) or the old one
+    // (all the others). Anything the line scan misjudged (odd YAML layouts) ends here instead of in a corrupted record.
+    const reread = (0, parse_1.splitRecord)(next);
+    if (!reread.ok)
+        return null;
+    const after = (0, parse_1.loadFrontmatter)(reread.frontmatterText);
+    if (!after.ok || !(0, text_safety_1.isObj)(after.value))
+        return null;
+    for (const key of Object.keys(before)) {
+        if (!(0, util_1.isDeepStrictEqual)(after.value[key], REPLACED.includes(key) ? fresh[key] : before[key]))
+            return null;
+    }
+    return next;
+}
+/**
+ * R3.11: replaces only the top-level blocks of the derived keys and `verification`; every other byte (comments, blank lines,
+ * other keys, the body, each line's own line ending) is preserved. Null when the record is unparseable, a replaced key is
+ * missing, the input is unusable, or the result would not read back as intended. Never throws.
+ */
+function refreshDerived(raw, fields, verification) {
+    try {
+        return splice(raw, fields, verification);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/src/core/changes/text-safety.js

@@ -0,0 +1,116 @@
+"use strict";
+// The one place that defines which characters are unsafe in record text (R1.4) and how attacker-controlled text is
+// echoed in diagnostics (R1.8). Pure: imports nothing from this module's siblings.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cleanText = exports.isWellFormed = exports.isObj = exports.escapeBidi = exports.isSafeMultiline = exports.isSingleLine = exports.MAX_MESSAGE = exports.NON_STRING = void 0;
+exports.escapeText = escapeText;
+exports.sliceNoSplit = sliceNoSplit;
+exports.esc = esc;
+exports.isSafeRelativePath = isSafeRelativePath;
+exports.isCanonicalIso = isCanonicalIso;
+exports.isHttpsUrl = isHttpsUrl;
+exports.clipMessage = clipMessage;
+// Control characters are C0 (includes \t \n \r), DEL and C1 (includes U+0085). U+2028/U+2029 are line breaks but not controls.
+const CONTROL_CLASS = '\\u0000-\\u001f\\u007f-\\u009f';
+const SINGLE_LINE_UNSAFE = new RegExp(`[${CONTROL_CLASS}\\u2028\\u2029]`);
+// What an echo of untrusted text escapes: the above plus the bidirectional controls (marks, embeddings, isolates), which would
+// reorder what a terminal shows around them. They are escaped, not rejected: isSingleLine and friends are about controls only.
+const BIDI = '\\u061c\\u200e\\u200f\\u202a-\\u202e\\u2066-\\u2069';
+const ESCAPE_ALL = new RegExp(`[${CONTROL_CLASS}\\u2028\\u2029${BIDI}]`, 'g');
+const BIDI_ALL = new RegExp(`[${BIDI}]`, 'g');
+const MULTILINE_UNSAFE = new RegExp(`[${CONTROL_CLASS}]`);
+/** Stand-in returned by the escaping and clipping helpers for non-string input (they never throw). */
+exports.NON_STRING = '<non-string>';
+exports.MAX_MESSAGE = 300;
+const MAX_ECHO_CODE_POINTS = 80;
+const MAX_ECHO_ESCAPED = 240;
+/** A string with no line break and no control character. */
+const isSingleLine = (text) => typeof text === 'string' && !SINGLE_LINE_UNSAFE.test(text);
+exports.isSingleLine = isSingleLine;
+/** A string whose only control characters are `\n` and `\t`. */
+const isSafeMultiline = (text) => typeof text === 'string' && !MULTILINE_UNSAFE.test(text.replace(/[\n\t]/g, ''));
+exports.isSafeMultiline = isSafeMultiline;
+const unicodeEscape = (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`;
+/** Bidirectional controls written as \\uXXXX (nothing else is touched). */
+const escapeBidi = (text) => text.replace(BIDI_ALL, unicodeEscape);
+exports.escapeBidi = escapeBidi;
+/** JSON-string escaping (without the quotes) plus the line breaks and controls JSON leaves alone. Does not clip. */
+function escapeText(text) {
+    if (typeof text !== 'string')
+        return exports.NON_STRING;
+    return JSON.stringify(text).slice(1, -1).replace(ESCAPE_ALL, unicodeEscape);
+}
+/** Cuts at `maxUnits` UTF-16 units, dropping a trailing high surrogate so a pair is never split. The only cut of untrusted text by unit count. */
+function sliceNoSplit(text, maxUnits) {
+    // Non-string text, or a limit that is not a finite number of at least 1, yields '' (never throws); fractions are floored.
+    if (typeof text !== 'string' || typeof maxUnits !== 'number' || !Number.isFinite(maxUnits))
+        return '';
+    const limit = Math.floor(maxUnits);
+    if (limit < 1)
+        return '';
+    if (text.length <= limit)
+        return text;
+    const last = text.charCodeAt(limit - 1);
+    return text.slice(0, last >= 0xd800 && last <= 0xdbff ? limit - 1 : limit);
+}
+/** Attacker-controlled text made safe to embed in a diagnostic: bounded, JSON-escaped, never containing a raw line break or control. */
+function esc(text) {
+    if (typeof text !== 'string')
+        return exports.NON_STRING;
+    const points = [...text];
+    const clipped = points.length > MAX_ECHO_CODE_POINTS ? `${points.slice(0, MAX_ECHO_CODE_POINTS).join('')}…` : text;
+    const escaped = escapeText(clipped);
+    return escaped.length > MAX_ECHO_ESCAPED ? `${sliceNoSplit(escaped, MAX_ECHO_ESCAPED)}…` : escaped;
+}
+const MAX_RELATIVE_PATH = 1024;
+/**
+ * A repo-relative path a record, a pathspec or a module name can safely hold: single line (no control character, no
+ * U+2028/U+2029), 1..1024 UTF-16 units, not padded with whitespace, no backslash, not absolute (a leading `/` is an empty
+ * segment, `C:` a drive letter; backslashes are refused), and no empty, `.` or `..` segment. Linear time; never throws.
+ */
+function isSafeRelativePath(p) {
+    if (!(0, exports.isSingleLine)(p) || p.length === 0 || p.length > MAX_RELATIVE_PATH || p !== p.trim())
+        return false;
+    if (/^[A-Za-z]:/.test(p) || p.includes('\\'))
+        return false;
+    return p.split('/').every((s) => s !== '' && s !== '.' && s !== '..');
+}
+/** A plain object (not null, not an array). */
+const isObj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+exports.isObj = isObj;
+/** Round-trips through UTF-8: false for a lone surrogate, which would not survive being written to a file. */
+const isWellFormed = (s) => typeof s === 'string' && Buffer.from(s, 'utf8').toString('utf8') === s;
+exports.isWellFormed = isWellFormed;
+/** A canonical ISO-8601 instant: exactly what `Date.prototype.toISOString` prints (UTC, milliseconds, `Z`). Never throws. */
+function isCanonicalIso(v) {
+    if (typeof v !== 'string')
+        return false;
+    const time = Date.parse(v);
+    return !Number.isNaN(time) && new Date(time).toISOString() === v;
+}
+/**
+ * An https URL a record can hold: one line, no whitespace, `https://` followed by a real authority (the first character is not
+ * `/ ? # \ @`), parseable by WHATWG URL with a host. Linear time; never throws.
+ */
+function isHttpsUrl(v, opts) {
+    if (!(0, exports.isSingleLine)(v) || /\s/.test(v) || !/^https:\/\/[^/?#\\@]/.test(v))
+        return false;
+    if (opts.maxLength !== undefined && v.length > opts.maxLength)
+        return false;
+    try {
+        const u = new URL(v);
+        return u.hostname.length > 0 && (opts.allowCredentials || (u.username === '' && u.password === ''));
+    }
+    catch {
+        return false;
+    }
+}
+/** Escapes any remaining raw line break, control character or bidi control (no quoting, no clipping). */
+const cleanText = (text) => (typeof text === 'string' ? text.replace(ESCAPE_ALL, unicodeEscape) : exports.NON_STRING);
+exports.cleanText = cleanText;
+/** Clips to MAX_MESSAGE UTF-16 units including the ellipsis. */
+function clipMessage(message) {
+    if (typeof message !== 'string')
+        return exports.NON_STRING;
+    return message.length <= exports.MAX_MESSAGE ? message : `${sliceNoSplit(message, exports.MAX_MESSAGE - 1)}…`;
+}

package/dist/src/core/changes/trailers.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.optsOut = optsOut;
+exports.hasOptOut = hasOptOut;
+const git_1 = require("./git");
+const OPT_OUT_TRAILER = 'Change-Record';
+// Raw messages (%B), NUL-terminated by -z: a message cannot contain NUL, so one commit is exactly one record. Git's own
+// %(trailers) is not used: it honours trailer.separators and trailer.<token>.key from the user's config, so what counts as
+// an opt-out would differ per machine. Messages are untrusted and unbounded, so everything below is an index scan: no regex
+// that can backtrack over a long run of blanks.
+const FORMAT = '--format=%B';
+const KEY = `${OPT_OUT_TRAILER}:`.toLowerCase();
+const VALUE = 'none';
+const COUNT_RE = /^-\d{1,4}$/;
+const MAX_ARGS = 16;
+const isBlank = (c) => c === ' ' || c === '\t';
+/** True when every character of `line` is a space, tab or CR (a blank line separating paragraphs). */
+function isBlankLine(line) {
+    for (let i = 0; i < line.length; i++)
+        if (!isBlank(line[i]) && line[i] !== '\r')
+            return false;
+    return true;
+}
+/** `Change-Record:` + optional spaces/tabs + `none` + optional spaces/tabs (+ the CR of a CRLF), key and value case-insensitive. */
+function isOptOutLine(line) {
+    let end = line.length;
+    if (end > 0 && line[end - 1] === '\r')
+        end--;
+    if (end < KEY.length + VALUE.length || line.slice(0, KEY.length).toLowerCase() !== KEY)
+        return false;
+    let i = KEY.length;
+    while (i < end && isBlank(line[i]))
+        i++;
+    if (line.slice(i, i + VALUE.length).toLowerCase() !== VALUE)
+        return false;
+    i += VALUE.length;
+    while (i < end && isBlank(line[i]))
+        i++;
+    return i === end;
+}
+/** DD-6: a line of the final paragraph (never the subject's) that is exactly `Change-Record: none`. No folding, no other separator. */
+function optsOut(message) {
+    const lines = message.split('\n');
+    let paragraphs = 0;
+    let start = 0;
+    let inside = false;
+    for (let i = 0; i < lines.length; i++) {
+        if (isBlankLine(lines[i]))
+            inside = false;
+        else if (!inside) {
+            inside = true;
+            start = i;
+            paragraphs++;
+        }
+    }
+    if (paragraphs < 2)
+        return false;
+    for (let i = start; i < lines.length; i++)
+        if (isOptOutLine(lines[i]))
+            return true;
+    return false;
+}
+/**
+ * True when any commit selected by `revArgs` (e.g. ['a..b'] or ['-1', sha]) carries `Change-Record: none`.
+ * Only a commit count (`-N`) and safe revisions are accepted; anything else, and any git failure, is `false`.
+ */
+function hasOptOut(root, revArgs) {
+    if (!Array.isArray(revArgs) || revArgs.length === 0 || revArgs.length > MAX_ARGS)
+        return false;
+    const counts = revArgs.filter((a) => typeof a === 'string' && COUNT_RE.test(a));
+    const revs = revArgs.filter((a) => !counts.includes(a));
+    if (counts.length > 1 || revs.length === 0 || !revs.every(git_1.isSafeRevision))
+        return false;
+    const out = (0, git_1.runGit)(root, ['log', ...git_1.LOG_SAFETY_ARGS, '-z', FORMAT, ...counts, '--end-of-options', ...revs, '--']);
+    return out !== null && out.split('\0').some(optsOut);
+}

package/dist/src/core/changes/types.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSensorName = exports.isSensorStatus = exports.isOverall = exports.isCommitId = exports.COMMIT_ID = exports.MAX_SENSOR_NAME = exports.OVERALLS = exports.SENSOR_STATUSES = exports.DERIVED_KEYS = exports.BODY_HEADINGS = exports.MAX_DIAGNOSTICS = exports.MAX_RECORD_BYTES = exports.RECORD_DIR = exports.PENDING_MARKER = exports.RECORD_SCHEMA = void 0;
+const text_safety_1 = require("./text-safety");
+exports.RECORD_SCHEMA = 'awm.change-record/v1';
+exports.PENDING_MARKER = '<!-- awm:pending -->';
+exports.RECORD_DIR = 'docs/changes';
+exports.MAX_RECORD_BYTES = 64 * 1024;
+exports.MAX_DIAGNOSTICS = 50;
+exports.BODY_HEADINGS = ['## Qué se hizo', '## Qué se probó', '## Qué falta validar', '## Riesgos y rollback'];
+exports.DERIVED_KEYS = ['type', 'scope', 'semver', 'breaking', 'modules'];
+// The ONE definition of what a receipt (receipt.ts), a record's verification block (validate-shape.ts) and git (git.ts) may hold.
+exports.SENSOR_STATUSES = ['pass', 'fail', 'inconclusive', 'skipped'];
+exports.OVERALLS = ['pass', 'fail', 'skipped', 'not_certified'];
+exports.MAX_SENSOR_NAME = 128;
+/** A full commit id: SHA-1 (40) or SHA-256 (64) lowercase hex characters. */
+exports.COMMIT_ID = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+const isCommitId = (v) => typeof v === 'string' && exports.COMMIT_ID.test(v);
+exports.isCommitId = isCommitId;
+const isOverall = (v) => typeof v === 'string' && exports.OVERALLS.includes(v);
+exports.isOverall = isOverall;
+const isSensorStatus = (v) => typeof v === 'string' && exports.SENSOR_STATUSES.includes(v);
+exports.isSensorStatus = isSensorStatus;
+/** A sensor name: one line, 1 to 128 code points. */
+const isSensorName = (v) => (0, text_safety_1.isSingleLine)(v) && [...v].length >= 1 && [...v].length <= exports.MAX_SENSOR_NAME;
+exports.isSensorName = isSensorName;

package/dist/src/core/changes/validate-shape.js

@@ -0,0 +1,219 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateRecordShape = validateRecordShape;
+const parse_1 = require("./parse");
+const fs_safe_1 = require("./fs-safe");
+const text_safety_1 = require("./text-safety");
+const types_1 = require("./types");
+const TOP_KEYS = ['schema', 'id', 'title', 'summary_short', 'type', 'scope', 'semver', 'breaking', 'modules', 'links', 'verification', 'manual_validation', 'risks', 'rollback', 'provenance'];
+const REQUIRED_KEYS = TOP_KEYS.filter((k) => k !== 'links' && k !== 'provenance');
+const PROVENANCE_KEYS = ['agent', 'model', 'session', 'started_at', 'finished_at'];
+const SEMVER = ['major', 'minor', 'patch', 'none'];
+const DIGEST_RE = /^sha256:[0-9a-f]{64}$/;
+const nonEmpty = (v) => typeof v === 'string' && v.trim().length > 0;
+/** Last line of defense for R1.8: single-line message/field, bounded length, at most MAX_DIAGNOSTICS entries. */
+function finalize(list) {
+    const clean = list.map((d) => {
+        const message = (0, text_safety_1.cleanText)(d.message);
+        const base = { code: d.code, message: (0, text_safety_1.clipMessage)(message) };
+        return d.field === undefined ? base : { ...base, field: (0, text_safety_1.cleanText)(d.field) };
+    });
+    if (clean.length <= types_1.MAX_DIAGNOSTICS)
+        return { diagnostics: clean };
+    const kept = clean.slice(0, types_1.MAX_DIAGNOSTICS - 1);
+    const omitted = clean.length - kept.length;
+    return { diagnostics: [...kept, { code: 'diagnostics-truncated', message: `${omitted} more diagnostics omitted` }], omitted };
+}
+// ---- Value predicates ----
+function isModulePath(m) {
+    return m === '.' || (0, text_safety_1.isSafeRelativePath)(m);
+}
+function containsPendingString(value) {
+    if (typeof value === 'string')
+        return value.includes(types_1.PENDING_MARKER);
+    if (Array.isArray(value))
+        return value.some(containsPendingString);
+    if ((0, text_safety_1.isObj)(value))
+        return Object.entries(value).some(([k, val]) => k.includes(types_1.PENDING_MARKER) || containsPendingString(val));
+    return false;
+}
+// ---- Diagnostic helpers ----
+function unknownKeys(obj, allowed, prefix, out) {
+    for (const key of Object.keys(obj)) {
+        if (!allowed.includes(key)) {
+            const field = prefix + (0, text_safety_1.esc)(key);
+            out.push({ code: 'unknown-field', field, message: `unknown field "${field}"` });
+        }
+    }
+}
+function bad(out, field, message) {
+    out.push({ code: 'field-invalid', field, message });
+}
+// ---- Body ----
+function checkBody(body, out) {
+    const lines = body.split('\n');
+    const headingIdx = lines.map((l, i) => (l.startsWith('## ') ? i : -1)).filter((i) => i >= 0);
+    let cursor = -1;
+    for (const heading of types_1.BODY_HEADINGS) {
+        const at = headingIdx.find((i) => i > cursor && lines[i].trimEnd() === heading);
+        if (at === undefined) {
+            out.push({ code: 'body-section-missing', message: `missing or out-of-order section "${heading}"` });
+            return;
+        }
+        const next = headingIdx.find((i) => i > at) ?? lines.length;
+        if (lines.slice(at + 1, next).join('\n').trim().length === 0) {
+            out.push({ code: 'body-section-missing', message: `section "${heading}" is empty` });
+            return;
+        }
+        cursor = at;
+    }
+}
+// ---- Frontmatter sections ----
+function checkIdentity(fm, fileName, out) {
+    if (fm.schema !== types_1.RECORD_SCHEMA)
+        bad(out, 'schema', `schema must be ${types_1.RECORD_SCHEMA}`);
+    if (fm.id !== fileName.replace(/\.md$/, ''))
+        bad(out, 'id', 'id must equal the file name without .md');
+    if (!nonEmpty(fm.title) || !(0, text_safety_1.isSingleLine)(fm.title) || [...fm.title].length > 120)
+        bad(out, 'title', 'title must be 1-120 characters on one line');
+    if (!nonEmpty(fm.summary_short) || !(0, text_safety_1.isSingleLine)(fm.summary_short) || [...fm.summary_short].length > 280)
+        bad(out, 'summary_short', 'summary_short must be 1-280 characters on one line');
+    if (typeof fm.type !== 'string' || !/^[a-z]+$/.test(fm.type))
+        bad(out, 'type', 'type must be a lowercase conventional-commit type');
+    if (!(fm.scope === null || (nonEmpty(fm.scope) && (0, text_safety_1.isSingleLine)(fm.scope))))
+        bad(out, 'scope', 'scope must be a single-line string or null');
+    if (!SEMVER.includes(fm.semver))
+        bad(out, 'semver', `semver must be one of ${SEMVER.join('|')}`);
+    if (typeof fm.breaking !== 'boolean')
+        bad(out, 'breaking', 'breaking must be a boolean');
+}
+function checkModules(fm, out) {
+    const mods = fm.modules;
+    if (!Array.isArray(mods) || !mods.every(isModulePath) || JSON.stringify([...new Set(mods)].sort()) !== JSON.stringify(mods)) {
+        bad(out, 'modules', 'modules must be a sorted, unique array of repo-relative directories');
+    }
+}
+function checkLinks(fm, root, out) {
+    if (fm.links === undefined)
+        return;
+    if (!(0, text_safety_1.isObj)(fm.links)) {
+        bad(out, 'links', 'links must be a mapping');
+        return;
+    }
+    unknownKeys(fm.links, ['plan', 'issue'], 'links.', out);
+    const { plan, issue } = fm.links;
+    if (plan !== undefined) {
+        if (!(0, text_safety_1.isSafeRelativePath)(plan))
+            bad(out, 'links.plan', 'links.plan must be a safe single-line repo-relative path');
+        else if (root !== undefined && !(0, fs_safe_1.isRegularFileInside)(root, plan))
+            bad(out, 'links.plan', `links.plan "${(0, text_safety_1.esc)(plan)}" does not exist as a regular file`);
+    }
+    if (issue !== undefined && !(0, text_safety_1.isHttpsUrl)(issue, { allowCredentials: false }))
+        bad(out, 'links.issue', 'links.issue must be an https URL without credentials');
+}
+function checkVerification(fm, out) {
+    const v = fm.verification;
+    if (!(0, text_safety_1.isObj)(v)) {
+        bad(out, 'verification', 'verification must be a mapping');
+        return;
+    }
+    unknownKeys(v, ['commit', 'overall', 'sensors', 'receipt_digest'], 'verification.', out);
+    if (!(0, types_1.isCommitId)(v.commit))
+        bad(out, 'verification.commit', 'verification.commit must be 40 or 64 lowercase hex characters');
+    if (!types_1.OVERALLS.includes(v.overall))
+        bad(out, 'verification.overall', `overall must be one of ${types_1.OVERALLS.join('|')}`);
+    if (!(0, text_safety_1.isObj)(v.sensors) || !Object.entries(v.sensors).every(([k, s]) => (0, types_1.isSensorName)(k) && (0, types_1.isSensorStatus)(s))) {
+        bad(out, 'verification.sensors', 'sensors must map sensor names to pass|fail|inconclusive|skipped');
+    }
+    if (typeof v.receipt_digest !== 'string' || !DIGEST_RE.test(v.receipt_digest))
+        bad(out, 'verification.receipt_digest', 'receipt_digest must be sha256:<64 hex>');
+}
+const isNarrative = (v) => nonEmpty(v) && (0, text_safety_1.isSafeMultiline)(v);
+function checkNarrative(fm, out) {
+    const mv = fm.manual_validation;
+    if (Array.isArray(mv)) {
+        if (mv.length === 0)
+            bad(out, 'manual_validation', 'manual_validation must not be empty; use {none: <reason>}');
+        mv.forEach((item, i) => {
+            if (!(0, text_safety_1.isObj)(item)) {
+                bad(out, `manual_validation.${i}`, 'item must be a mapping');
+                return;
+            }
+            unknownKeys(item, ['step', 'expected'], `manual_validation.${i}.`, out);
+            if (!isNarrative(item.step) || !isNarrative(item.expected))
+                bad(out, `manual_validation.${i}`, 'step and expected must be non-empty strings without control characters');
+        });
+    }
+    else if ((0, text_safety_1.isObj)(mv)) {
+        unknownKeys(mv, ['none'], 'manual_validation.', out);
+        if (!isNarrative(mv.none))
+            bad(out, 'manual_validation.none', 'none must state a non-empty reason without control characters');
+    }
+    else
+        bad(out, 'manual_validation', 'manual_validation must be a list or {none: <reason>}');
+    if (!Array.isArray(fm.risks) || !fm.risks.every(isNarrative))
+        bad(out, 'risks', 'risks must be an array of non-empty strings without control characters');
+    if (!isNarrative(fm.rollback))
+        bad(out, 'rollback', 'rollback must be a non-empty string without control characters');
+}
+function checkProvenance(fm, out) {
+    if (fm.provenance === undefined)
+        return;
+    if (!(0, text_safety_1.isObj)(fm.provenance)) {
+        bad(out, 'provenance', 'provenance must be a mapping');
+        return;
+    }
+    unknownKeys(fm.provenance, PROVENANCE_KEYS, 'provenance.', out);
+    for (const [k, val] of Object.entries(fm.provenance)) {
+        if (!PROVENANCE_KEYS.includes(k))
+            continue;
+        const field = `provenance.${(0, text_safety_1.esc)(k)}`;
+        if (!nonEmpty(val) || !(0, text_safety_1.isSingleLine)(val))
+            bad(out, field, `${field} must be a non-empty single-line string`);
+        else if ((k === 'started_at' || k === 'finished_at') && !(0, text_safety_1.isCanonicalIso)(val))
+            bad(out, field, `${field} must be canonical ISO-8601`);
+    }
+}
+/** `omitted` is the number of diagnostics the MAX_DIAGNOSTICS cap dropped (absent when none were); the last diagnostic is then `diagnostics-truncated`. */
+function validateRecordShape(fileName, raw, opts = {}) {
+    if (typeof fileName !== 'string' || typeof raw !== 'string') {
+        return { diagnostics: [{ code: 'input-invalid', message: 'fileName and raw must both be strings' }] };
+    }
+    if (Buffer.byteLength(raw, 'utf8') > types_1.MAX_RECORD_BYTES) {
+        return { diagnostics: [{ code: 'record-too-large', message: `record exceeds ${types_1.MAX_RECORD_BYTES} bytes` }] };
+    }
+    const root = typeof opts?.root === 'string' ? opts.root : undefined;
+    const out = [];
+    if (!(0, parse_1.isValidRecordFileName)(fileName))
+        out.push({ code: 'name-invalid', message: `file name "${(0, text_safety_1.esc)(fileName)}" must be YYYY-MM-DD-<slug>.md with a valid date and slug of at most 64 chars` });
+    const stop = (...more) => finalize([...out, ...more]);
+    const split = (0, parse_1.splitRecord)(raw);
+    if (!split.ok)
+        return stop(split.diagnostic);
+    if (split.frontmatterText.includes(types_1.PENDING_MARKER) || split.body.includes(types_1.PENDING_MARKER)) {
+        out.push({ code: 'pending-content', message: 'record still contains <!-- awm:pending --> placeholders' });
+    }
+    checkBody(split.body, out);
+    const loaded = (0, parse_1.loadFrontmatter)(split.frontmatterText);
+    if (!loaded.ok)
+        return stop(loaded.diagnostic);
+    const fm = loaded.value;
+    if (!(0, text_safety_1.isObj)(fm))
+        return stop({ code: 'not-an-object', message: 'frontmatter must be a mapping' });
+    if (!out.some((d) => d.code === 'pending-content') && containsPendingString(fm)) {
+        out.push({ code: 'pending-content', message: 'record still contains <!-- awm:pending --> placeholders' });
+    }
+    unknownKeys(fm, TOP_KEYS, '', out);
+    for (const key of REQUIRED_KEYS)
+        if (!(key in fm))
+            bad(out, key, `missing required field "${key}"`);
+    checkIdentity(fm, fileName, out);
+    checkModules(fm, out);
+    checkLinks(fm, root, out);
+    checkVerification(fm, out);
+    checkNarrative(fm, out);
+    checkProvenance(fm, out);
+    if (out.length === 0)
+        return { record: fm, diagnostics: [] };
+    return finalize(out);
+}