@tiphys/kernel 0.0.0 → 0.2.0

package/dist/src/modes.js

@@ -0,0 +1,258 @@
+/**
+ * READING THE SHIPPED ASSURANCE MODE DEFINITIONS (kernel plan M3, M3-P3
+ * step 5).
+ *
+ * `assurance-modes.yaml` ships at the package root, beside `gate-registry.yaml`
+ * and the `schemas/` directory. This module locates it, decodes it, and
+ * answers one question: what does a declared mode require. Nothing here
+ * RESOLVES a mode into behaviour and nothing here enforces one. M3 never
+ * executes `direct-pr` or `local-only`, and building an enforcement engine for
+ * a mode this milestone never enters is the M1-P3 failure the plan is trying
+ * not to repeat.
+ *
+ * NO VALIDATION HAPPENS HERE, deliberately. `tiphys validate --type
+ * assurance-modes` is the command that says whether the document is
+ * well-formed, and duplicating its rules in a reader would produce a second
+ * opinion to keep in sync. This module reads what is there and reports what it
+ * cannot find.
+ */
+import { readdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { decodeDocument, readOperatorPath } from "./validate.js";
+/** The shipped document's basename, at the package root. */
+export const MODES_FILENAME = "assurance-modes.yaml";
+/**
+ * Locate the package root by walking UP from this module and testing for the
+ * shipped document.
+ *
+ * The depth differs between the two layouts this code runs in: from source it
+ * is `src/` and the root is one level up, and from the built entry it is
+ * `dist/src/` and the root is two levels up. Counting `..` would be right in
+ * exactly one of them, which is the layout-dependent break
+ * `schemasDirectory()` already documents. Walking up and TESTING is right in
+ * both, and in a relocated copy as well.
+ */
+export function packageRoot() {
+    let directory = dirname(fileURLToPath(import.meta.url));
+    for (let depth = 0; depth < 8; depth += 1) {
+        try {
+            if (readdirSync(directory).includes(MODES_FILENAME)) {
+                return directory;
+            }
+        }
+        catch {
+            /* not readable here; keep walking */
+        }
+        const parent = dirname(directory);
+        if (parent === directory) {
+            break;
+        }
+        directory = parent;
+    }
+    throw new Error(`the shipped ${MODES_FILENAME} was not found above this module; the installation is incomplete`);
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function strings(record, key) {
+    const value = record[key];
+    return Array.isArray(value)
+        ? value.filter((entry) => typeof entry === "string")
+        : [];
+}
+function optionalStrings(record, key) {
+    return record[key] === undefined ? undefined : strings(record, key);
+}
+/** Read and decode the shipped document, or say why it could not be read. */
+export function readModes(path = join(packageRoot(), MODES_FILENAME)) {
+    const read = readOperatorPath(path);
+    if (!read.ok) {
+        return { ok: false, reason: read.reason };
+    }
+    const decoded = decodeDocument(read.body, path);
+    if (!decoded.ok) {
+        return { ok: false, reason: decoded.reason };
+    }
+    const document = asRecord(decoded.value);
+    if (document === undefined) {
+        return { ok: false, reason: `${path} does not decode to a mapping` };
+    }
+    const raw = document["modes"];
+    if (!Array.isArray(raw)) {
+        return { ok: false, reason: `${path} declares no modes list` };
+    }
+    const modes = [];
+    for (const entry of raw) {
+        const record = asRecord(entry);
+        if (record === undefined) {
+            continue;
+        }
+        modes.push({
+            id: String(record["id"] ?? ""),
+            declaredBy: String(record["declared-by"] ?? ""),
+            pipeline: strings(record, "pipeline"),
+            skips: strings(record, "skips"),
+            gateSets: strings(record, "gate-sets"),
+            mergeAuthority: String(record["merge-authority"] ?? ""),
+            grantedBy: typeof record["granted-by"] === "string" ? record["granted-by"] : undefined,
+            conditions: optionalStrings(record, "conditions"),
+            reviewContracts: optionalStrings(record, "review-contracts"),
+            escalationBounds: asRecord(record["escalation-bounds"]),
+        });
+    }
+    return { ok: true, path, raw: decoded.value, modes };
+}
+/**
+ * The id blueprint section 8 gives the un-downgraded process BY NAME: "The
+ * current proven process is the definition of `full`."
+ *
+ * SIBLING LITERAL, named so neither site can drift unnoticed:
+ * `REFERENCE_MODE_ID` at src/checks.ts:275 is the same string, used as the
+ * reference pipeline every other mode's omissions are measured against. The two
+ * are pinned from opposite directions by registered tests: the checks-side
+ * literal by the assertion that deleting `full` produces `no mode declares id
+ * full` (test/assurance-modes.test.ts:314), and this one by the assertion that
+ * the mode `mode show` annotates as un-downgraded is the mode named `full`.
+ */
+const UNDOWNGRADED_MODE_ID = "full";
+/**
+ * The execution status of one mode, DERIVED rather than looked up in a list of
+ * ids (CR-004 item 2, DR-0020).
+ *
+ * Two facts are available and both are checkable by the reader: whether this is
+ * the kernel's own document, and whether this mode IS the one blueprint section
+ * 8 names as the un-downgraded process, "The current proven process is the
+ * definition of `full`. Downgrades are declared, never improvised."
+ *
+ * WHY THE NAME AND NOT THE SKIP COUNT (CR-002, round 9). This function used
+ * `mode.skips.length === 0` as its proxy for "this is the un-downgraded mode".
+ * The proxy held only because `full` happened to be the only mode with an empty
+ * list, nothing enforced that, and `skips[]` is shipped DATA. Two measured
+ * consequences, both at exit 0 with every registry gate green: giving `full` one
+ * bogus `skips[]` entry made this function say that no phase of the tiphys
+ * project had ever been delivered under `full`, which is false about the mode
+ * this project has delivered every phase under; and giving `direct-pr` an empty
+ * `skips[]` made a mode nobody has ever entered claim to be the one the project
+ * follows, with `merge-authority: owner` printed beneath it, which is not the
+ * regime in force (DR-0015). Blueprint section 8 defines `full` BY NAME, so the
+ * name is the primary fact and the skip count is a consequence of it.
+ *
+ * THE COUNT IS STILL REPORTED, as a fact about the mode rather than as the
+ * ground of the claim. That distinction is the whole finding: a number may be
+ * shown without being believed.
+ *
+ * WHAT MAKES THE `full` SENTENCE TRUE IS DATA, AND IT IS GUARDED IN TWO PLACES
+ * THAT COVER DIFFERENT DOCUMENTS. Keying off the name moves the burden: the
+ * claim is only as good as the `full` in the document being served genuinely
+ * being un-downgraded.
+ *
+ * The VALIDATOR carries it for EVERY document (round 10, CRB9-02).
+ * `mode-no-undeclared-downgrade` rejects a `skips[]` entry that the same mode's
+ * pipeline runs, and also one that the reference does not run; on the reference
+ * those two exhaust the cases, so a `full` declaring any skipped stage at all is
+ * refused and this sentence is never printed over it. Until that second part
+ * existed, a `full` whose stage had MOVED from `pipeline` into `skips` was an
+ * HONEST downgrade that validated at exit 0, and `tiphys mode show --mode full`
+ * printed this sentence about fifteen lines above a `skips: deploy-verify` row.
+ *
+ * A REGISTERED TEST carries it for THIS repository's own document, asserting the
+ * shipped `full` declares no skipped stage. It is kept rather than superseded:
+ * a test guards the document, the check guards every other document, and the
+ * failure this pair exists to prevent is a property asserted where it is stated
+ * and not enforced where it is consumed.
+ *
+ * WHAT THIS DELIBERATELY DOES NOT SAY. It does not say that tiphys runs
+ * anything: nothing runs on tiphys before M4. The un-downgraded mode of the
+ * kernel's own document is the process the tiphys PROJECT follows for its own
+ * delivery; the downgraded ones have never been entered at all. And for a
+ * document that is not the kernel's own, the answer is that tiphys does not
+ * know, because it does not.
+ */
+export function executionStatus(mode, context) {
+    if (!context.shippedDocument) {
+        return ("not determinable here. This is not the kernel's own assurance-modes.yaml, " +
+            "so nothing tiphys ships records whether any phase has been delivered under " +
+            "this mode (DR-0020).");
+    }
+    if (mode.id === UNDOWNGRADED_MODE_ID) {
+        return (`this mode is ${UNDOWNGRADED_MODE_ID}, which blueprint section 8 defines by name as the ` +
+            "un-downgraded process, and it is the one the tiphys project follows for its own delivery.");
+    }
+    return (`DECLARED AND VALIDATED, NEVER EXERCISED. This mode is not ${UNDOWNGRADED_MODE_ID}, which ` +
+        "blueprint section 8 defines by name as the un-downgraded process, so no phase of the " +
+        `tiphys project has ever been delivered under it. It declares ${String(mode.skips.length)} ` +
+        "skipped stage(s). Its pipeline and its gate selection are checked by validation only " +
+        "(DR-0020).");
+}
+/**
+ * The standing limits of this release, printed on every invocation.
+ *
+ * IT SAYS ONLY WHAT THE SHIPPED SCHEMAS DO. The vocabularies really are closed
+ * enums, so "a document naming any other id is rejected" is the enum's own
+ * behaviour and not a claim about intent. The M4 sentence is attributed to
+ * DR-0020 rather than stated as a property of the code.
+ */
+export const RELEASE_LIMITS = "limits: the mode, stage and role vocabularies in the shipped schemas are this " +
+    "repository's own closed enums, so a document naming any other id is rejected and a " +
+    "consuming project cannot extend them at v0.1.0; whether to open them is an M4 question " +
+    "(DR-0020). This command SHOWS a declared mode: nothing in this release resolves a " +
+    "project into a mode, enforces one, or runs one.";
+/**
+ * Render one mode for a human or for a brief.
+ *
+ * THE SHAPE IS PART OF THE CONTRACT, because criterion 2 asserts over it: a
+ * section is a line ending in a colon at column zero, and its items are the
+ * lines indented by exactly two spaces beneath it. That makes "prints exactly
+ * the twelve stage ids in order" something a test can extract rather than
+ * something a reader has to eyeball.
+ */
+export function renderMode(mode, context) {
+    const lines = [`mode: ${mode.id}`];
+    /* SECOND LINE, not a footnote. CR-004 measured that `mode show` printed a
+       never-exercised mode with exactly the confidence of the exercised one, and
+       that the only disclosure lived in `delivery/`, which the package excludes. */
+    lines.push(`execution-status: ${executionStatus(mode, context)}`);
+    lines.push(`merge-authority: ${mode.mergeAuthority}`);
+    if (mode.grantedBy !== undefined) {
+        lines.push(`granted-by: ${mode.grantedBy}`);
+    }
+    const section = (name, items) => {
+        if (items === undefined) {
+            return;
+        }
+        lines.push(`${name}:`);
+        if (items.length === 0) {
+            lines.push("  (none)");
+            return;
+        }
+        for (const item of items) {
+            lines.push(`  ${item}`);
+        }
+    };
+    section("pipeline", mode.pipeline);
+    section("skips", mode.skips);
+    section("gate-sets", mode.gateSets);
+    section("review-contracts", mode.reviewContracts);
+    if (mode.escalationBounds !== undefined) {
+        /* CR-004 item 3. The bounds are DATA an orchestrator brief cites. Nothing
+           in this release counts a fix round or detects a recurrence, so a bare
+           `escalation-bounds:` header invites the reader to assume an enforcement
+           engine that does not exist. */
+        lines.push("escalation-bounds (data an orchestrator brief cites; nothing in this release counts fix rounds, detects recurrence, or enforces these):");
+        for (const key of Object.keys(mode.escalationBounds).sort()) {
+            lines.push(`  ${key}: ${String(mode.escalationBounds[key])}`);
+        }
+    }
+    if (mode.conditions !== undefined) {
+        lines.push("conditions:");
+        for (const condition of mode.conditions) {
+            lines.push(`  ${condition.replace(/\s+/g, " ").trim()}`);
+        }
+    }
+    lines.push(`declared-by: ${mode.declaredBy.replace(/\s+/g, " ").trim()}`);
+    lines.push(RELEASE_LIMITS);
+    return lines;
+}

package/dist/src/path-identity.d.ts

@@ -0,0 +1,34 @@
+/** Compare two existing paths by their canonical filesystem identity. */
+export declare function pathsIdentifySameObject(left: string, right: string): boolean;
+/**
+ * Decide whether two paths NAME THE SAME filesystem object when at least
+ * one of them was produced by ANOTHER PROGRAM rather than composed here.
+ *
+ * THE MECHANISM THIS EXISTS FOR, measured 2026-09-16 on the macOS smoke
+ * job of pull request #155. `path.resolve` normalizes `.`, `..` and
+ * relative segments and does NOT resolve symlinks, so two spellings of one
+ * directory stay unequal as strings. Programs the kernel shells out to do
+ * not preserve the caller's spelling: git canonicalizes every worktree
+ * path it records (`git worktree add /link/wt` then `git worktree list
+ * --porcelain` reports `/real/wt`, measured on Linux), and node reports
+ * the canonical path of a test file in its reporter's `file` field. So a
+ * kernel-composed path compared by string against such a value answers
+ * "different object" for the same object, silently, and every decision
+ * taken on that answer is wrong in the direction that does nothing.
+ *
+ * On macOS the symlink is supplied by the platform and needs no unusual
+ * setup: `/tmp` is a symlink to `/private/tmp` and `os.tmpdir()` returns a
+ * path under `/var/folders`, where `/var` is a symlink to `/private/var`.
+ * The CLI is accidentally immune because `process.cwd()` is already
+ * canonical, so only a caller that hands a path in makes this reachable,
+ * which is exactly what a library consumer does.
+ *
+ * The string comparison is tried FIRST and kept, rather than replaced, for
+ * two reasons: it answers without touching the filesystem in the common
+ * case, and it still gives the right answer for two paths that do not
+ * exist, where `realpathSync` can only raise. This function therefore says
+ * "same" strictly more often than `resolve(left) === resolve(right)` does,
+ * and never says "same" about two objects that are genuinely different:
+ * equal canonical paths ARE one object.
+ */
+export declare function pathsNameSameObject(left: string, right: string): boolean;

package/dist/src/path-identity.js

@@ -0,0 +1,48 @@
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+/** Compare two existing paths by their canonical filesystem identity. */
+export function pathsIdentifySameObject(left, right) {
+    try {
+        return realpathSync(left) === realpathSync(right);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Decide whether two paths NAME THE SAME filesystem object when at least
+ * one of them was produced by ANOTHER PROGRAM rather than composed here.
+ *
+ * THE MECHANISM THIS EXISTS FOR, measured 2026-09-16 on the macOS smoke
+ * job of pull request #155. `path.resolve` normalizes `.`, `..` and
+ * relative segments and does NOT resolve symlinks, so two spellings of one
+ * directory stay unequal as strings. Programs the kernel shells out to do
+ * not preserve the caller's spelling: git canonicalizes every worktree
+ * path it records (`git worktree add /link/wt` then `git worktree list
+ * --porcelain` reports `/real/wt`, measured on Linux), and node reports
+ * the canonical path of a test file in its reporter's `file` field. So a
+ * kernel-composed path compared by string against such a value answers
+ * "different object" for the same object, silently, and every decision
+ * taken on that answer is wrong in the direction that does nothing.
+ *
+ * On macOS the symlink is supplied by the platform and needs no unusual
+ * setup: `/tmp` is a symlink to `/private/tmp` and `os.tmpdir()` returns a
+ * path under `/var/folders`, where `/var` is a symlink to `/private/var`.
+ * The CLI is accidentally immune because `process.cwd()` is already
+ * canonical, so only a caller that hands a path in makes this reachable,
+ * which is exactly what a library consumer does.
+ *
+ * The string comparison is tried FIRST and kept, rather than replaced, for
+ * two reasons: it answers without touching the filesystem in the common
+ * case, and it still gives the right answer for two paths that do not
+ * exist, where `realpathSync` can only raise. This function therefore says
+ * "same" strictly more often than `resolve(left) === resolve(right)` does,
+ * and never says "same" about two objects that are genuinely different:
+ * equal canonical paths ARE one object.
+ */
+export function pathsNameSameObject(left, right) {
+    if (resolve(left) === resolve(right)) {
+        return true;
+    }
+    return pathsIdentifySameObject(left, right);
+}

package/dist/src/plan.d.ts

@@ -0,0 +1,73 @@
+/**
+ * THE PHASE-DECLARATION PROJECTION (kernel plan M3, M3-P1 step 2; D-M3-18).
+ *
+ * The M2-P4 scope auditor reads one document per phase from
+ * `delivery/plan/phase-declarations/<phase-id-lowercased>.json`, out of the
+ * MERGE BASE of the audited branch. Until now that document was a SECOND
+ * HAND-AUTHORED SOURCE beside the plan, and two hand-authored sources of the
+ * same fact drift. This module makes it a GENERATED VIEW of the plan, so the
+ * plan is the one source and the auditor's input is derived from it.
+ *
+ * WHAT THE PROJECTION EMITS, taken from the DELIVERED
+ * `src/gates/schemas/phase-declaration.schema.json` rather than from a
+ * description of it. The delivered schema sets `additionalProperties: false`,
+ * so an extra property is a REJECTION and not an ignored field, and the
+ * emitted key set is exactly these five, camelCase:
+ *
+ *   id, branch, filesToTouch, declaredExtras, citations
+ *
+ * TWO VOCABULARIES MEET HERE AND NOWHERE ELSE. The plan spells the same
+ * fields `files-to-touch` and `extras`, because the plan is a document
+ * authored for people. This projector is the single translation point, and
+ * that is D-M3-18's whole value.
+ *
+ * THE GLOSS IS STRIPPED HERE OR NOWHERE (M2R-016). The auditor matches a
+ * declared path as a literal string or as a directory prefix and interprets
+ * nothing, so a plan entry written as
+ *
+ *   `src/cli.ts` (edit only if step 4 requires it)
+ *
+ * must project to `src/cli.ts`. A projector that passed the glossed form
+ * through would emit a declaration under which every real change is
+ * undeclared, and the auditor would be right to reject it.
+ */
+/** The five properties the delivered phase-declaration schema requires. */
+export interface PhaseDeclaration {
+    id: string;
+    branch: string;
+    filesToTouch: string[];
+    declaredExtras: string[];
+    citations: string[];
+}
+export declare function stripGloss(entry: string): string;
+/**
+ * Is this a literal path the scope auditor can match?
+ *
+ * The auditor compares strings exactly or as a directory prefix and
+ * interprets nothing, so an entry still carrying whitespace after the gloss
+ * strip is prose. The projector REFUSES rather than emitting it: an emitted
+ * prose entry is a declaration nobody can satisfy, and the failure would
+ * surface as an unrelated scope-gate red on some later branch.
+ */
+export declare function isLiteralPath(entry: string): boolean;
+export interface ProjectionResult {
+    ok: true;
+    declaration: PhaseDeclaration;
+    /** `m3-p1.json`, the filename the auditor looks for. */
+    filename: string;
+}
+export interface ProjectionFailure {
+    ok: false;
+    reason: string;
+}
+/**
+ * Project one phase of a decoded plan into its declaration.
+ *
+ * The filename is the phase id LOWERCASED, because CI derives `--phase` from
+ * the branch with a lowercase regex and the auditor looks the declaration up
+ * by that name. An uppercase filename is a declaration the auditor never
+ * finds, which reads exactly like a phase with no declaration at all.
+ */
+export declare function projectPhase(plan: unknown, phaseId: string): ProjectionResult | ProjectionFailure;
+/** The declaration as the auditor reads it: JSON, one trailing newline. */
+export declare function renderDeclaration(declaration: PhaseDeclaration): string;

package/dist/src/plan.js

@@ -0,0 +1,153 @@
+/**
+ * THE PHASE-DECLARATION PROJECTION (kernel plan M3, M3-P1 step 2; D-M3-18).
+ *
+ * The M2-P4 scope auditor reads one document per phase from
+ * `delivery/plan/phase-declarations/<phase-id-lowercased>.json`, out of the
+ * MERGE BASE of the audited branch. Until now that document was a SECOND
+ * HAND-AUTHORED SOURCE beside the plan, and two hand-authored sources of the
+ * same fact drift. This module makes it a GENERATED VIEW of the plan, so the
+ * plan is the one source and the auditor's input is derived from it.
+ *
+ * WHAT THE PROJECTION EMITS, taken from the DELIVERED
+ * `src/gates/schemas/phase-declaration.schema.json` rather than from a
+ * description of it. The delivered schema sets `additionalProperties: false`,
+ * so an extra property is a REJECTION and not an ignored field, and the
+ * emitted key set is exactly these five, camelCase:
+ *
+ *   id, branch, filesToTouch, declaredExtras, citations
+ *
+ * TWO VOCABULARIES MEET HERE AND NOWHERE ELSE. The plan spells the same
+ * fields `files-to-touch` and `extras`, because the plan is a document
+ * authored for people. This projector is the single translation point, and
+ * that is D-M3-18's whole value.
+ *
+ * THE GLOSS IS STRIPPED HERE OR NOWHERE (M2R-016). The auditor matches a
+ * declared path as a literal string or as a directory prefix and interprets
+ * nothing, so a plan entry written as
+ *
+ *   `src/cli.ts` (edit only if step 4 requires it)
+ *
+ * must project to `src/cli.ts`. A projector that passed the glossed form
+ * through would emit a declaration under which every real change is
+ * undeclared, and the auditor would be right to reject it.
+ */
+/**
+ * Reduce one plan `files-to-touch` entry to the bare path.
+ *
+ * THIS FUNCTION FEEDS THE GATE THAT EXISTS TO PREVENT SCOPE WIDENING, so an
+ * over-eager strip here is worse than no strip at all.
+ *
+ * MEASURED DEFECT, fix round 1 (B-001, high). The first version truncated at
+ * the FIRST `(` and produced:
+ *
+ *   "src/app/(marketing)/page.tsx"  ->  "src/app/"
+ *   "src/(lib)/util.ts"             ->  "src/"
+ *
+ * `src/gates/scope.ts` treats a trailing slash as a DIRECTORY PREFIX GRANT, so
+ * each of those turned one declared file into an entire tree. Parenthesised
+ * path segments are ordinary in real projects (Next.js route groups are the
+ * obvious case), so this is not a corner.
+ *
+ * THE RULE NOW, and each clause is load-bearing:
+ *
+ *   1. A gloss is stripped only when it is TRAILING and the whole of it is
+ *      parenthesised: `<path> (anything)` with the closing paren at the end.
+ *   2. It is stripped only when WHITESPACE separates it from the path. A path
+ *      whose own last segment is parenthesised, `src/app/(marketing)`, has no
+ *      such whitespace and is left alone.
+ *   3. What precedes the gloss must be ONE non-whitespace token, which is what
+ *      a literal path is. That is the "plausible path" test, and it is why an
+ *      interior `(` can never trigger a strip: the interior case never matches
+ *      the trailing form at all.
+ *
+ * Anything the rule does not recognise is returned UNCHANGED and rejected
+ * loudly by `projectPhase`, because a prose entry that reaches the auditor as
+ * a literal string fails visibly, while a silently truncated one grants a
+ * tree.
+ */
+const TRAILING_GLOSS = /^(\S+)\s+\([\s\S]*\)$/;
+export function stripGloss(entry) {
+    let text = entry.trim();
+    const trailing = TRAILING_GLOSS.exec(text);
+    if (trailing !== null) {
+        text = trailing[1].trim();
+    }
+    /* Backticks are markdown, never part of a path. Stripped AFTER the gloss,
+       because the plan writes `` `path` (gloss) `` and the backticks close
+       before the gloss opens. */
+    text = text.replace(/^`+/, "").replace(/`+$/, "").trim();
+    /* A trailing comma survives a list written inline. */
+    text = text.replace(/,+$/, "").trim();
+    return text;
+}
+/**
+ * Is this a literal path the scope auditor can match?
+ *
+ * The auditor compares strings exactly or as a directory prefix and
+ * interprets nothing, so an entry still carrying whitespace after the gloss
+ * strip is prose. The projector REFUSES rather than emitting it: an emitted
+ * prose entry is a declaration nobody can satisfy, and the failure would
+ * surface as an unrelated scope-gate red on some later branch.
+ */
+export function isLiteralPath(entry) {
+    return entry !== "" && !/\s/.test(entry);
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function stringArray(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === "string")
+        : [];
+}
+/**
+ * Project one phase of a decoded plan into its declaration.
+ *
+ * The filename is the phase id LOWERCASED, because CI derives `--phase` from
+ * the branch with a lowercase regex and the auditor looks the declaration up
+ * by that name. An uppercase filename is a declaration the auditor never
+ * finds, which reads exactly like a phase with no declaration at all.
+ */
+export function projectPhase(plan, phaseId) {
+    const document = asRecord(plan);
+    if (document === undefined) {
+        return { ok: false, reason: "the plan document is not a mapping" };
+    }
+    const phases = Array.isArray(document["phases"]) ? document["phases"] : [];
+    const phase = asRecord(phases.find((candidate) => asRecord(candidate)?.["id"] === phaseId));
+    if (phase === undefined) {
+        return { ok: false, reason: `the plan contains no phase ${phaseId}` };
+    }
+    const filesToTouch = stringArray(phase["files-to-touch"])
+        .map(stripGloss)
+        .filter((path) => path !== "");
+    const declaredExtras = stringArray(phase["extras"])
+        .map(stripGloss)
+        .filter((path) => path !== "");
+    const prose = [...filesToTouch, ...declaredExtras].filter((path) => !isLiteralPath(path));
+    if (prose.length > 0) {
+        return {
+            ok: false,
+            reason: `phase ${phaseId} declares an entry that is not a literal path and ` +
+                `cannot be projected: ${prose.map((p) => JSON.stringify(p)).join(", ")}`,
+        };
+    }
+    const declaration = {
+        id: String(phase["id"]),
+        branch: String(phase["branch"]),
+        filesToTouch,
+        declaredExtras,
+        citations: stringArray(phase["citations"]),
+    };
+    return {
+        ok: true,
+        declaration,
+        filename: `${phaseId.toLowerCase()}.json`,
+    };
+}
+/** The declaration as the auditor reads it: JSON, one trailing newline. */
+export function renderDeclaration(declaration) {
+    return `${JSON.stringify(declaration, undefined, 2)}\n`;
+}