@oxygen-agent/cli 1.1011.322 → 1.1011.405

package/node_modules/@oxygen/shared/dist/decision-ledger-parser.js

@@ -0,0 +1,303 @@
+// Parser for the routing program's decision ledger (docs/gtm-program/decisions.md).
+//
+// Registry seeds cite ledger ids, and staff surfaces explain a provider choice
+// by them, so the ledger is read as data rather than prose. The parser keys on
+// the three table sections and their exact header rows and throws on anything
+// else: a reshaped ledger has to break the generator, not lose decisions.
+//
+// This module imports nothing, not even a sibling, so
+// scripts/docs/generate-decision-ledger.mjs can load it through Node's own type
+// stripping without a build, and so it stays browser-safe. Consumers read the
+// parsed entries through @oxygen/shared/decision-ledger.
+const TABLE_LAYOUTS = [
+    { table: "ratified", heading: /^Ratified$/, columns: ["#", "Decision", "Ratified answer", "Shipped / lands"] },
+    { table: "open", heading: /^Open$/, columns: ["#", "Decision", "Status", "Owner / forcing function"] },
+    { table: "proposed", heading: /^Proposed\b/, columns: ["#", "Decision", "Proposed answer", "Status"] },
+];
+const DECISION_ID = String.raw `D\d+[a-z]?(?:\([a-z]\))?`;
+const DECISION_ID_LIST = String.raw `${DECISION_ID}(?:(?:\s*,\s*(?:and\s+|or\s+)?|\s*[/&]\s*|\s+(?:and|or)\s+)${DECISION_ID})*`;
+// "Superseded by D26", "Superseded by D55/D56" — this row is replaced.
+const SUPERSEDED_BY = new RegExp(String.raw `\b[Ss]uperseded\s+by\s+(${DECISION_ID_LIST})`, "g");
+// "Supersedes D24(a)", "Supersedes only D19(a)'s clause", "Supersedes the D32 chain".
+const SUPERSEDES = new RegExp(String.raw `\b[Ss]upersedes\s+(only\s+|the\s+)?(${DECISION_ID_LIST})`, "g");
+// What follows a superseded id when only part of it is replaced: a possessive
+// ("D55's company half"), a capacity ("D18(a) as a routing posture") or "in
+// part", optionally after the date the row records ("D29 (2026-07-25) as a …").
+const PARTIAL_SCOPE = /^\s*(?:\([^)]*\)\s*)?(?:['\u2019]s\b|as\s+an?\s|in\s+part\b)/;
+// "Partially superseded by D40": the row itself says only part of it went.
+const PARTIAL_PREFIX = /\b(?:[Pp]artially|[Pp]artly)\s+$/;
+// A decision id with an optional attached letter (D34a) and an optional answer
+// option in parentheses (D19(a)); the option names a clause, not a decision.
+const ID_MENTION = /\bD(\d+)([a-z]?)(?:\([a-z]\))?(?![\w(])/g;
+const ID_RANGE = /\bD(\d+)\s*[–—-]\s*D(\d+)\b/g;
+/** Parse the ledger markdown into entries sorted by decision id. */
+export function parseDecisionLedger(markdown) {
+    const lines = markdown.split(/\r?\n/);
+    const rows = [];
+    const events = [];
+    const tablesSeen = new Set();
+    let section = null;
+    let index = 0;
+    while (index < lines.length) {
+        const line = lines[index] ?? "";
+        const heading = /^##\s+(.+?)\s*#*\s*$/.exec(line);
+        if (heading) {
+            const title = plainText(heading[1] ?? "");
+            section = { title, layout: TABLE_LAYOUTS.find((layout) => layout.heading.test(title)) ?? null, hasTable: false };
+            index += 1;
+            continue;
+        }
+        if (/^\s*\|/.test(line)) {
+            const where = section ? `"## ${section.title}"` : "the preamble";
+            if (!section?.layout) {
+                throw new Error(`Decision ledger line ${index + 1}: a table under ${where}. The parser reads only the Ratified, Open and Proposed tables and will not guess what this one holds; extend parseDecisionLedger first.`);
+            }
+            if (section.hasTable || tablesSeen.has(section.layout.table)) {
+                throw new Error(`Decision ledger line ${index + 1}: a second ${section.layout.table} table under ${where}.`);
+            }
+            section.hasTable = true;
+            tablesSeen.add(section.layout.table);
+            index = readTable(lines, index, section, section.layout, rows);
+            continue;
+        }
+        if (section === null) {
+            // Preamble: "- **2026-06-10 (T0 build):** D7, D11, ...", possibly wrapped.
+            const event = /^\s*[-*+]\s+\*\*(\d{4}-\d{2}-\d{2})\b[^*]*\*\*(.*)$/.exec(line);
+            if (event) {
+                let text = event[2] ?? "";
+                while (index + 1 < lines.length && /^\s+\S/.test(lines[index + 1] ?? "") && !/^\s*[-*+]\s/.test(lines[index + 1] ?? "")) {
+                    index += 1;
+                    text += ` ${lines[index] ?? ""}`;
+                }
+                events.push({ date: event[1] ?? "", text });
+            }
+        }
+        index += 1;
+    }
+    if (rows.length === 0)
+        throw new Error("Decision ledger has no Ratified, Open or Proposed table rows.");
+    return buildEntries(rows, events);
+}
+function readTable(lines, start, section, layout, rows) {
+    const header = splitRow(lines[start] ?? "").map(plainText);
+    if (header.join(" | ") !== layout.columns.join(" | ")) {
+        throw new Error(`The "## ${section.title}" table (line ${start + 1}) has columns "${header.join(" | ")}"; the parser expects "${layout.columns.join(" | ")}". Update parseDecisionLedger for the new layout rather than letting it guess.`);
+    }
+    const delimiter = splitRow(lines[start + 1] ?? "");
+    if (delimiter.length !== header.length || !delimiter.every((cell) => /^:?-{3,}:?$/.test(cell))) {
+        throw new Error(`The "## ${section.title}" table (line ${start + 2}) has no delimiter row under its header.`);
+    }
+    let index = start + 2;
+    while (index < lines.length && /^\s*\|/.test(lines[index] ?? "")) {
+        const cells = splitRow(lines[index] ?? "");
+        if (cells.length !== header.length) {
+            throw new Error(`Decision ledger row ${plainText(cells[0] ?? "") || "?"} in the ${layout.table} table (line ${index + 1}) has ${cells.length} cells; its header has ${header.length}.`);
+        }
+        rows.push({ table: layout.table, cells, line: index + 1 });
+        index += 1;
+    }
+    return index;
+}
+/** Split a GFM table row on unescaped pipes; `\|` stays escaped for plainText. */
+function splitRow(line) {
+    let body = line.trim();
+    if (body.startsWith("|"))
+        body = body.slice(1);
+    if (body.endsWith("|") && !body.endsWith("\\|"))
+        body = body.slice(0, -1);
+    const cells = [];
+    let current = "";
+    for (let position = 0; position < body.length; position += 1) {
+        const char = body[position];
+        if (char === "\\" && body[position + 1] === "|") {
+            current += "\\|";
+            position += 1;
+        }
+        else if (char === "|") {
+            cells.push(current.trim());
+            current = "";
+        }
+        else {
+            current += char;
+        }
+    }
+    cells.push(current.trim());
+    return cells;
+}
+/**
+ * Markdown inline text to plain text: code spans keep their content verbatim,
+ * emphasis and strikethrough markers go, links keep their text, escapes resolve,
+ * whitespace collapses. Intraword underscores (find_email) are never emphasis.
+ */
+function plainText(markdown) {
+    const held = [];
+    const hold = (value) => `\u0000${held.push(value) - 1}\u0000`;
+    let text = markdown
+        // GFM resolves `\|` inside a table cell before any inline parsing, code spans included.
+        .replace(/\\\|/g, "|")
+        .replace(/(`+)([\s\S]*?[^`])\1(?!`)/g, (_match, _ticks, code) => hold(code.length > 2 && code.startsWith(" ") && code.endsWith(" ") ? code.slice(1, -1) : code))
+        .replace(/\\([!-/:-@[-`{-~])/g, (_match, char) => hold(char))
+        .replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1")
+        .replace(/<((?:https?|mailto):[^>\s]+)>/g, "$1");
+    for (;;) {
+        const next = text
+            .replace(/\*\*(?=\S)([\s\S]*?\S)\*\*/g, "$1")
+            .replace(/(^|\W)__(?=\S)([\s\S]*?\S)__(?!\w)/g, "$1$2")
+            .replace(/(^|[^\w*])\*(?=[^\s*])([\s\S]*?[^\s*])\*(?![\w*])/g, "$1$2")
+            .replace(/(^|\W)_(?=[^\s_])([\s\S]*?[^\s_])_(?!\w)/g, "$1$2")
+            .replace(/~~(?=\S)([\s\S]*?\S)~~/g, "$1");
+        if (next === text)
+            break;
+        text = next;
+    }
+    return text
+        .replace(/\u0000(\d+)\u0000/g, (_match, slot) => held[Number(slot)] ?? "")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/** Sentences of plain text; a period followed by a lowercase word ("i.e. we") does not split. */
+function sentences(text) {
+    return text.split(/(?<=[.!?])\s+(?=[A-Z0-9("'`])/);
+}
+/** Decision ids mentioned in text, as `D<n>` plus any attached letter; "D19(a)" is "D19". */
+function mentionedIds(text, options = {}) {
+    const ids = [];
+    if (options.expandRanges) {
+        for (const range of text.matchAll(ID_RANGE)) {
+            const from = Number(range[1]);
+            const to = Number(range[2]);
+            if (to < from || to - from > 500)
+                continue;
+            for (let number = from; number <= to; number += 1)
+                ids.push(`D${number}`);
+        }
+    }
+    for (const mention of text.matchAll(ID_MENTION))
+        ids.push(`D${mention[1]}${mention[2] ?? ""}`);
+    return ids;
+}
+/** Exact id first ("D34a"), then the base id for an option-lettered mention ("D19a" -> "D19"). */
+function resolveId(mention, known) {
+    if (known.has(mention))
+        return mention;
+    const base = /^(D\d+)[a-z]$/.exec(mention)?.[1];
+    return base && known.has(base) ? base : null;
+}
+function compareIds(left, right) {
+    const a = /^D(\d+)([a-z]?)$/.exec(left);
+    const b = /^D(\d+)([a-z]?)$/.exec(right);
+    const byNumber = Number(a?.[1] ?? 0) - Number(b?.[1] ?? 0);
+    if (byNumber !== 0)
+        return byNumber;
+    return (a?.[2] ?? "").localeCompare(b?.[2] ?? "");
+}
+function nullIfEmpty(text) {
+    return text.length > 0 ? text : null;
+}
+/** The status cell of a Proposed-table row: "Proposed" or "Ratified in chat <date> (<who>); <lands>". */
+function readProposedStatus(id, line, cell) {
+    const ratified = /^Ratified in chat (\d{4}-\d{2}-\d{2})\b(?:\s*\([^)]*\))?\s*(?:[;,.:—–-]\s*)?(.*)$/i.exec(cell);
+    if (ratified)
+        return { status: "ratified", ratifiedOn: ratified[1] ?? null, lands: nullIfEmpty(ratified[2] ?? "") };
+    const proposed = /^Proposed\b\s*(?:[;,.:—–-]\s*)?(.*)$/i.exec(cell);
+    if (proposed)
+        return { status: "proposed", ratifiedOn: null, lands: nullIfEmpty(proposed[1] ?? "") };
+    throw new Error(`Decision ${id} (line ${line}) has a Proposed-table status the parser does not recognise: "${cell}". Expected "Proposed" or "Ratified in chat YYYY-MM-DD".`);
+}
+function buildEntries(rows, events) {
+    const entries = [];
+    const lineById = new Map();
+    const searchText = new Map();
+    for (const row of rows) {
+        const [idCell = "", titleCell = "", answerCell = "", lastCell = ""] = row.cells.map(plainText);
+        if (!/^D\d+[a-z]?$/.test(idCell)) {
+            throw new Error(`Decision ledger line ${row.line}: "${idCell}" is not a decision id (D<number>, optionally one letter).`);
+        }
+        const firstLine = lineById.get(idCell);
+        if (firstLine !== undefined) {
+            throw new Error(`Decision ${idCell} appears more than once in the ledger (lines ${firstLine} and ${row.line}); ids are never reused.`);
+        }
+        lineById.set(idCell, row.line);
+        const base = {
+            id: idCell,
+            title: titleCell,
+            answer: answerCell,
+            table: row.table,
+            supersededBy: [],
+            partlySupersededBy: [],
+        };
+        if (row.table === "proposed") {
+            entries.push({ ...base, ...readProposedStatus(idCell, row.line, lastCell) });
+        }
+        else {
+            entries.push({ ...base, status: row.table, ratifiedOn: null, lands: nullIfEmpty(lastCell) });
+        }
+        searchText.set(idCell, [titleCell, answerCell, lastCell].join(" "));
+    }
+    const known = new Set(entries.map((entry) => entry.id));
+    // Ratification events date the Ratified table. A sentence that records a
+    // supersession ("D15 ... superseded in place") is not a ratification.
+    const eventDates = new Map();
+    for (const event of events) {
+        for (const sentence of sentences(plainText(event.text))) {
+            if (/supersed/i.test(sentence))
+                continue;
+            for (const mention of mentionedIds(sentence, { expandRanges: true })) {
+                const id = resolveId(mention, known);
+                if (!id)
+                    continue;
+                const current = eventDates.get(id);
+                if (current === undefined || event.date < current)
+                    eventDates.set(id, event.date);
+            }
+        }
+    }
+    for (const entry of entries) {
+        if (entry.table !== "ratified")
+            continue;
+        // Otherwise the row's own clause: "Ratified 2026-07-25 (moved from Open)", "Closed 2026-07-25".
+        const rowDate = /\b(?:Ratified|Closed)\b[^.;:]*?(\d{4}-\d{2}-\d{2})/.exec(entry.answer)?.[1];
+        entry.ratifiedOn = eventDates.get(entry.id) ?? rowDate ?? null;
+    }
+    // Supersession, both directions: "Superseded by D26" on the row itself, and
+    // "Supersedes D24(a)" on the row that replaced it. A statement that names a
+    // part ("only", a possessive, "as a …") replaces only that part.
+    const replaced = { whole: new Map(), partly: new Map() };
+    const record = (superseded, by, partly) => {
+        if (superseded === by)
+            return;
+        const target = partly ? replaced.partly : replaced.whole;
+        const set = target.get(superseded) ?? new Set();
+        set.add(by);
+        target.set(superseded, set);
+    };
+    const resolveOrThrow = (mention, owner, verb) => {
+        const id = resolveId(mention, known);
+        if (!id)
+            throw new Error(`Decision ${owner} says it ${verb} ${mention}, which the ledger does not define.`);
+        return id;
+    };
+    const after = (text, match) => text.slice((match.index ?? 0) + match[0].length);
+    for (const entry of entries) {
+        const text = searchText.get(entry.id) ?? "";
+        for (const match of text.matchAll(SUPERSEDED_BY)) {
+            const partly = PARTIAL_PREFIX.test(text.slice(0, match.index ?? 0)) || PARTIAL_SCOPE.test(after(text, match));
+            for (const mention of mentionedIds(match[1] ?? "")) {
+                record(entry.id, resolveOrThrow(mention, entry.id, "is superseded by"), partly);
+            }
+        }
+        for (const match of text.matchAll(SUPERSEDES)) {
+            const partly = (match[1] ?? "").trim() === "only" || PARTIAL_SCOPE.test(after(text, match));
+            for (const mention of mentionedIds(match[2] ?? "")) {
+                record(resolveOrThrow(mention, entry.id, "supersedes"), entry.id, partly);
+            }
+        }
+    }
+    for (const entry of entries) {
+        const whole = replaced.whole.get(entry.id) ?? new Set();
+        entry.supersededBy = [...whole].sort(compareIds);
+        // One unqualified statement settles it: a decision a row calls replaced is replaced.
+        entry.partlySupersededBy = [...(replaced.partly.get(entry.id) ?? [])].filter((id) => !whole.has(id)).sort(compareIds);
+    }
+    return entries.sort((left, right) => compareIds(left.id, right.id));
+}

package/node_modules/@oxygen/shared/dist/decision-ledger.d.ts

@@ -0,0 +1,10 @@
+import type { DecisionLedgerEntry } from "./decision-ledger-parser.js";
+export { parseDecisionLedger, type DecisionLedgerEntry, type DecisionLedgerStatus } from "./decision-ledger-parser.js";
+/**
+ * The ledger entry for a decision id. An exact id wins ("D34a" is its own
+ * decision); otherwise an answer-option suffix resolves to its base decision
+ * ("D19a" and "D19(a)" are D19's option (a)).
+ */
+export declare function getDecision(id: string): DecisionLedgerEntry | null;
+/** Every ledger entry, sorted by decision id. */
+export declare function listDecisions(): readonly DecisionLedgerEntry[];

package/node_modules/@oxygen/shared/dist/decision-ledger.generated.d.ts

@@ -0,0 +1,2 @@
+import type { DecisionLedgerEntry } from "./decision-ledger-parser.js";
+export declare const DECISION_LEDGER_ENTRIES: readonly DecisionLedgerEntry[];