@nac3/forge-cli 1.19.4 → 1.20.0

package/dist/urazuke/gates_data.d.ts

@@ -0,0 +1,219 @@
+import { type UrazukeArtifact, type UrazukeTramo, type UrazukeForm, type UrazukeMandatory } from './catalog.js';
+import { type GatesSource } from './ruleset.js';
+/** Where the method publishes it. Only `fetchPublishedGates` reads this,
+ *  and only the explicit pull calls that. */
+export declare const DEFAULT_GATES_URL = "https://yujin.app/urazuke/api/gates.json";
+/** The frozen copy, inside the project. Next to the prompt overrides
+ *  (`.forge/urazuke-prompts.json`) on purpose: the two halves of the same
+ *  freeze belong together, and a reader looking for one finds the other.
+ *
+ *  This file is meant to be COMMITTED. The prevailing convention for
+ *  `.forge/` in a project is local state -- `workflow-config.json` is in
+ *  .gitignore -- and the freeze has to break that convention to mean
+ *  anything: a copy that does not travel with the repository is a freeze
+ *  that thaws on the next clone and on every CI run, where no copy is found
+ *  and the newest definition answers instead. A lock that only closes on one
+ *  laptop. See docs/PROPUESTA_URAZUKE_VERSION_POR_PROYECTO_2026_10_22.md. */
+export declare const GATES_FROZEN_REL: string;
+export declare function frozenGatesPath(projectRoot: string): string;
+/** The highest published schema this Forge knows how to read. A file that
+ *  declares more than this is not refused -- the schema is append-only by
+ *  the method's own rule -- but what it adds is reported as unread rather
+ *  than silently dropped. */
+export declare const MAX_SCHEMA_VERSION = 2;
+/** One evaluator a step asks for. `required` decides the compatibility
+ *  branch when this installation does not implement it. */
+export interface PublishedEvaluatorRef {
+    name: string;
+    since_schema?: number;
+    required?: boolean;
+}
+/** An artifact rule as published. Same fields as the compiled
+ *  `UrazukeArtifact` plus the schema marker the method uses to tell the
+ *  frozen base apart from what it added afterwards. */
+export interface PublishedArtifact extends UrazukeArtifact {
+    since_schema?: number;
+    anchor?: number;
+}
+export interface PublishedStep {
+    num: number;
+    id: string;
+    tramo?: string;
+    title: string;
+    summary?: string;
+    form?: string;
+    mandatory?: string;
+    prompt_key: string;
+    prompt_indexes?: number[];
+    inputs?: PublishedArtifact[];
+    artifacts?: PublishedArtifact[];
+    verify?: unknown[];
+    evaluators?: PublishedEvaluatorRef[];
+}
+export interface PublishedContentHash {
+    algo: string;
+    encoding: string;
+    canonical_form: string;
+    covers: string[];
+    excludes: string[];
+    value: string;
+    note?: string;
+}
+export interface PublishedGatesFile {
+    schema_version: number;
+    catalog_version: string;
+    content_hash: PublishedContentHash;
+    evaluators?: {
+        name: string;
+        since_schema?: number;
+        checks?: string;
+    }[];
+    compatibility?: Record<string, string>;
+    steps: PublishedStep[];
+    stations: PublishedStep[];
+    /** Everything else the method publishes (tramos, heuristics, adapters,
+     *  project_config, languages, loop_entry, ...). Kept verbatim: the hash
+     *  covers it, so dropping a key on the way in would break the seal. */
+    [key: string]: unknown;
+}
+/** The payload the declared hash covers, in the order the file declares.
+ *  Built from `content_hash.covers` and not from a list of our own: the
+ *  method owns which keys bear the requirement, and a consumer that keeps
+ *  its own list stops agreeing the day the method adds one. */
+export declare function coveredPayload(file: PublishedGatesFile): Record<string, unknown>;
+export interface HashVerdict {
+    ok: boolean;
+    declared: string;
+    recomputed: string;
+    /** Top-level keys the file neither covers nor excludes. Not a detail: a
+     *  key outside both lists is content nobody is protecting, and a frozen
+     *  copy altered exactly there would still match its hash. The method
+     *  raises its own error for this; we check it rather than trust it. */
+    uncovered: string[];
+}
+/** Recompute the content hash over the canonicalised covered payload and
+ *  compare. The canonical form is the one the method declares
+ *  (`json_sorted_keys_codepoint_no_whitespace_utf8`, sha256, hex lower),
+ *  which is also the one `ruleset.ts` uses -- so one implementation serves
+ *  both the seal and this check, and the two sides cannot drift apart. */
+export declare function verifyContentHash(file: PublishedGatesFile): HashVerdict;
+export interface ValidationResult {
+    ok: boolean;
+    file?: PublishedGatesFile;
+    problems: string[];
+    /** The hash verdict, when the shape was good enough to compute one. */
+    hash?: HashVerdict;
+    /** The file declares a schema this Forge does not fully know. Not a
+     *  refusal: the schema is append-only, so an older reader stays correct
+     *  about what it does read. It IS reported, because what it adds may
+     *  carry requirements, and silence there is the silent damage. */
+    newer_schema?: number;
+}
+/** Validate a payload that claims to be a published gate definition.
+ *
+ *  Refuses on: a broken shape, or a hash that does not recompute. The second
+ *  one is the whole point of Pieza 2 -- a definition we cannot verify is not
+ *  a definition we may enforce, because the only thing that makes a frozen
+ *  copy trustworthy offline is that its content reproduces its own seal. */
+export declare function validatePublishedGates(raw: unknown): ValidationResult;
+export interface ResolvedEvaluator {
+    name: string;
+    required: boolean;
+    since_schema: number;
+}
+/** One step or station, in the one shape `gate.ts` evaluates -- whether it
+ *  came from the compiled catalogue or from a published file. */
+export interface ResolvedGateStep {
+    num: number;
+    id: string;
+    title: string;
+    tramo?: UrazukeTramo | string;
+    summary?: string;
+    form?: UrazukeForm | string;
+    mandatory?: UrazukeMandatory | string;
+    prompt_key: string;
+    inputs: UrazukeArtifact[];
+    artifacts: UrazukeArtifact[];
+    verify: string[];
+    evaluators: ResolvedEvaluator[];
+}
+export interface ResolvedGates {
+    source: GatesSource;
+    version: string;
+    /** Recomputed here. For `compiled` it is the requirement hash of
+     *  catalog.ts; for a file, its verified content hash. The two are
+     *  different domains and must not be compared across sources -- the
+     *  source is part of the identity, which is why the stamp carries both. */
+    hash: string;
+    schema_version: number;
+    steps: ResolvedGateStep[];
+    stations: ResolvedGateStep[];
+    /** The evaluator vocabulary the definition declares. Informative: what
+     *  decides is whether THIS Forge implements each name. */
+    declared_evaluators: string[];
+    /** Things the reader wants said out loud: a refused frozen copy, a schema
+     *  newer than this reader, a definition with no artifacts. Never swallowed
+     *  -- a resolution that quietly fell back is the bug this module exists
+     *  to prevent. */
+    notices: string[];
+}
+/** The published definition, in the resolved shape. */
+export declare function publishedToResolved(file: PublishedGatesFile, source: GatesSource, hash: string): ResolvedGates;
+/** Forge's own compiled catalogue, in the same resolved shape.
+ *
+ *  This is the BASE: what Forge enforced before the method took ownership,
+ *  and what a project freezes when it is started by a Forge that has not
+ *  pulled a published definition. Every step declares exactly one evaluator
+ *  and every one of them is required -- the compiled catalogue has no notion
+ *  of an optional evaluator, which is correct, because it also has no
+ *  evaluator it cannot measure. */
+export declare function compiledGatesResolved(): ResolvedGates;
+export interface FrozenReadResult {
+    /** The definition, when the file was there AND verified. */
+    gates?: ResolvedGates;
+    /** No file: the normal case for a project that has not been frozen. */
+    absent: boolean;
+    /** The file was there and was REFUSED. The reason is for the owner, not
+     *  for a log nobody reads: a refused freeze means the project is being
+     *  judged by the compiled rule and not by the one it thought it froze. */
+    refused?: string[];
+}
+export declare function readFrozenGates(projectRoot: string): Promise<FrozenReadResult>;
+/** Write the frozen copy. Atomic (tmp + rename) for the same reason the
+ *  prompt overrides are: a half-written definition read by the next turn is
+ *  a project with no rule at all. */
+export declare function writeFrozenGates(projectRoot: string, file: PublishedGatesFile): Promise<void>;
+/** Serialise the compiled catalogue INTO the published shape, sealed with a
+ *  hash computed the published way, so a frozen copy of the base is read
+ *  back by exactly the same path as a frozen copy of the portal's.
+ *
+ *  This is what "freeze every existing project with what it reads today"
+ *  writes: the base, unchanged, with nothing added. The first day the
+ *  difference is exactly zero and it can be demonstrated -- that is the
+ *  criterion the whole proposal rests on. */
+export declare function compiledAsPublishedFile(): PublishedGatesFile;
+/** WHICH gate definition is in force for this project.
+ *
+ *  Precedence: the project's frozen copy, then the compiled catalogue. The
+ *  portal is deliberately absent -- see rule 1 at the top of this file. A
+ *  refused frozen copy does NOT promote the portal and does not fail the
+ *  read: it falls back to the compiled catalogue, which is the safe state
+ *  (nothing can tighten without an install), and it says so. */
+export declare function resolveGates(projectRoot?: string): Promise<ResolvedGates>;
+export interface FetchGatesOptions {
+    fetchImpl?: typeof fetch;
+    url?: string;
+    timeout_ms?: number;
+}
+/** Bring the published definition over the network.
+ *
+ *  NOT part of `resolveGates`, on purpose and by decision: the owner asked
+ *  that a project start and finish on the same version of the method, so
+ *  the only legitimate caller is the explicit double lock (Pieza 4), which
+ *  has to show how many green steps would turn red BEFORE it writes
+ *  anything. A validated file or nothing -- an unverifiable definition is
+ *  never handed back. */
+export declare function fetchPublishedGates(opts?: FetchGatesOptions): Promise<ValidationResult>;
+/** One line for a report or the CLI. */
+export declare function renderGatesSource(g: ResolvedGates): string;
+//# sourceMappingURL=gates_data.d.ts.map

package/dist/urazuke/gates_data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gates_data.d.ts","sourceRoot":"","sources":["../../src/urazuke/gates_data.ts"],"names":[],"mappings":"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"}

package/dist/urazuke/gates_data.js

@@ -0,0 +1,441 @@
+/**
+ * THE GATE DEFINITION AS DATA -- reading the gates the method publishes
+ * (PND-165, Pieza 2).
+ *
+ * Until 2026-10-23 the mechanical definition of the gates lived compiled
+ * inside Forge (`catalog.ts`): 24 steps, 8 stations, one evaluator each. On
+ * that day the method took ownership of it and started publishing it as
+ * data (D-050), the same way it already published the prompts. So a
+ * requirement of the method no longer waits for a Forge release -- which is
+ * the point -- and a project can now be re-read under a rule that did not
+ * exist when its evidence was produced, which is the danger. The owner's
+ * decision bounds that: a project starts and finishes on the same version of
+ * the method unless somebody presses the double lock.
+ *
+ * This module is the READ side of that decision. Three rules it enforces,
+ * each one because its absence turns the freeze into a label:
+ *
+ *   1. PRECEDENCE: the copy frozen in the project wins over everything.
+ *      Second, and only second, Forge's own compiled catalogue. The portal
+ *      is NOT on this path -- `fetchPublishedGates` exists for the explicit
+ *      pull (Pieza 4) and nothing here calls it. A read that can reach the
+ *      network is a read that can change a project's rule between two
+ *      turns, and no decision asked for that.
+ *
+ *   2. THE HASH IS RECOMPUTED, NEVER READ. A frozen copy edited by hand or
+ *      truncated by a merge has to be detectable without the network. A
+ *      stamp that only repeats what the file claims about itself is a
+ *      rotulo, not a seal (adenda 2). A frozen copy whose recomputed hash
+ *      disagrees with its own declared value is REFUSED, loudly, and the
+ *      compiled catalogue answers instead -- a tampered rule must never be
+ *      the rule in force.
+ *
+ *   3. AN UNKNOWN EVALUATOR IS NOT A GREEN AND NOT AN APPROXIMATION. The
+ *      published catalogue already declares twelve evaluators and this
+ *      Forge implements eight. The method's own compatibility clause says
+ *      what to do: a REQUIRED evaluator this installation cannot measure is
+ *      reported as "declared, not measured by this installation", naming it,
+ *      and the step does not advance. Approximating with the closest
+ *      evaluator, or ignoring the block, is forbidden. Zero silent damage.
+ *
+ * What this module does NOT do: evaluate. It resolves WHICH definition is in
+ * force and hands it over in one shape, whatever its source. `gate.ts`
+ * measures.
+ *
+ * ASCII-only.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { URAZUKE_STEPS, URAZUKE_LEGACY_STATIONS, } from './catalog.js';
+import { canonicalJson, sha256Hex, compiledGatesHash, FORGE_COMPILED_GATES_VERSION, } from './ruleset.js';
+/** Where the method publishes it. Only `fetchPublishedGates` reads this,
+ *  and only the explicit pull calls that. */
+export const DEFAULT_GATES_URL = 'https://yujin.app/urazuke/api/gates.json';
+/** The frozen copy, inside the project. Next to the prompt overrides
+ *  (`.forge/urazuke-prompts.json`) on purpose: the two halves of the same
+ *  freeze belong together, and a reader looking for one finds the other.
+ *
+ *  This file is meant to be COMMITTED. The prevailing convention for
+ *  `.forge/` in a project is local state -- `workflow-config.json` is in
+ *  .gitignore -- and the freeze has to break that convention to mean
+ *  anything: a copy that does not travel with the repository is a freeze
+ *  that thaws on the next clone and on every CI run, where no copy is found
+ *  and the newest definition answers instead. A lock that only closes on one
+ *  laptop. See docs/PROPUESTA_URAZUKE_VERSION_POR_PROYECTO_2026_10_22.md. */
+export const GATES_FROZEN_REL = path.join('.forge', 'urazuke-gates.json');
+export function frozenGatesPath(projectRoot) {
+    return path.join(projectRoot, GATES_FROZEN_REL);
+}
+/** The highest published schema this Forge knows how to read. A file that
+ *  declares more than this is not refused -- the schema is append-only by
+ *  the method's own rule -- but what it adds is reported as unread rather
+ *  than silently dropped. */
+export const MAX_SCHEMA_VERSION = 2;
+/* ---------------- the hash ---------------- */
+/** The payload the declared hash covers, in the order the file declares.
+ *  Built from `content_hash.covers` and not from a list of our own: the
+ *  method owns which keys bear the requirement, and a consumer that keeps
+ *  its own list stops agreeing the day the method adds one. */
+export function coveredPayload(file) {
+    const out = {};
+    for (const k of file.content_hash.covers)
+        out[k] = file[k];
+    return out;
+}
+/** Recompute the content hash over the canonicalised covered payload and
+ *  compare. The canonical form is the one the method declares
+ *  (`json_sorted_keys_codepoint_no_whitespace_utf8`, sha256, hex lower),
+ *  which is also the one `ruleset.ts` uses -- so one implementation serves
+ *  both the seal and this check, and the two sides cannot drift apart. */
+export function verifyContentHash(file) {
+    const recomputed = sha256Hex(canonicalJson(coveredPayload(file)));
+    const accounted = new Set([...file.content_hash.covers, ...file.content_hash.excludes]);
+    const uncovered = Object.keys(file).filter((k) => !accounted.has(k)).sort();
+    return {
+        ok: recomputed === file.content_hash.value && uncovered.length === 0,
+        declared: file.content_hash.value,
+        recomputed,
+        uncovered,
+    };
+}
+/* ---------------- validation ---------------- */
+function isArtifactArray(x) {
+    return Array.isArray(x) && x.every((a) => a && typeof a === 'object' && typeof a.path === 'string');
+}
+function validStepArray(x, label, problems) {
+    if (!Array.isArray(x) || !x.length) {
+        problems.push(label + ': missing or empty');
+        return false;
+    }
+    let ok = true;
+    for (const s of x) {
+        if (!s || typeof s !== 'object') {
+            problems.push(label + ': a non-object entry');
+            ok = false;
+            continue;
+        }
+        if (typeof s.id !== 'string' || !s.id) {
+            problems.push(label + ': an entry with no id');
+            ok = false;
+        }
+        if (typeof s.num !== 'number') {
+            problems.push(label + ' ' + s.id + ': num is not a number');
+            ok = false;
+        }
+        if (typeof s.title !== 'string') {
+            problems.push(label + ' ' + s.id + ': title is not a string');
+            ok = false;
+        }
+        if (s.inputs !== undefined && !isArtifactArray(s.inputs)) {
+            problems.push(label + ' ' + s.id + ': inputs is not a list of artifacts');
+            ok = false;
+        }
+        if (s.artifacts !== undefined && !isArtifactArray(s.artifacts)) {
+            problems.push(label + ' ' + s.id + ': artifacts is not a list of artifacts');
+            ok = false;
+        }
+        if (s.evaluators !== undefined) {
+            if (!Array.isArray(s.evaluators) || !s.evaluators.every((e) => e && typeof e.name === 'string')) {
+                problems.push(label + ' ' + s.id + ': evaluators is not a list of {name}');
+                ok = false;
+            }
+        }
+    }
+    return ok;
+}
+/** Validate a payload that claims to be a published gate definition.
+ *
+ *  Refuses on: a broken shape, or a hash that does not recompute. The second
+ *  one is the whole point of Pieza 2 -- a definition we cannot verify is not
+ *  a definition we may enforce, because the only thing that makes a frozen
+ *  copy trustworthy offline is that its content reproduces its own seal. */
+export function validatePublishedGates(raw) {
+    const problems = [];
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return { ok: false, problems: ['not a JSON object'] };
+    }
+    const f = raw;
+    if (typeof f.schema_version !== 'number')
+        problems.push('schema_version missing or not a number');
+    if (typeof f.catalog_version !== 'string' || !f.catalog_version)
+        problems.push('catalog_version missing');
+    const ch = f.content_hash;
+    if (!ch || typeof ch !== 'object' || typeof ch.value !== 'string'
+        || !Array.isArray(ch.covers) || !Array.isArray(ch.excludes)) {
+        problems.push('content_hash missing or incomplete (needs value + covers + excludes)');
+    }
+    else {
+        if (ch.algo && ch.algo !== 'sha256')
+            problems.push('content_hash.algo is ' + ch.algo + ', and this reader only does sha256');
+        if (ch.canonical_form && ch.canonical_form !== 'json_sorted_keys_codepoint_no_whitespace_utf8') {
+            problems.push('content_hash.canonical_form is ' + ch.canonical_form + ', not the form this reader canonicalises to');
+        }
+    }
+    validStepArray(f.steps, 'steps', problems);
+    validStepArray(f.stations, 'stations', problems);
+    if (problems.length)
+        return { ok: false, problems };
+    const hash = verifyContentHash(f);
+    if (!hash.ok) {
+        if (hash.recomputed !== hash.declared) {
+            problems.push('content hash does not recompute: declared ' + hash.declared.slice(0, 16)
+                + ', recomputed ' + hash.recomputed.slice(0, 16)
+                + ' -- the content and its seal disagree, so this definition cannot be trusted');
+        }
+        if (hash.uncovered.length) {
+            problems.push('top-level key(s) neither covered nor excluded by content_hash: ' + hash.uncovered.join(', ')
+                + ' -- content nobody protects, so an edit there would still match the seal');
+        }
+        return { ok: false, problems, hash };
+    }
+    const res = { ok: true, file: f, problems, hash };
+    if (f.schema_version > MAX_SCHEMA_VERSION)
+        res.newer_schema = f.schema_version;
+    return res;
+}
+function artifactsOf(xs) {
+    return (xs ?? []).map((a) => ({
+        path: a.path,
+        ...(a.must_contain ? { must_contain: [...a.must_contain] } : {}),
+        ...(a.should_contain ? { should_contain: [...a.should_contain] } : {}),
+        ...(a.min_bytes != null ? { min_bytes: a.min_bytes } : {}),
+        ...(a.fresh_days != null ? { fresh_days: a.fresh_days } : {}),
+        ...(a.label ? { label: a.label } : {}),
+    }));
+}
+/** `verify` entries are strings in the base and objects with `{text,
+ *  since_schema, anchor}` in what the method added. Both are owner prose;
+ *  flatten to text so a consumer does not have to know the difference. */
+function verifyOf(xs) {
+    const out = [];
+    for (const v of xs ?? []) {
+        if (typeof v === 'string')
+            out.push(v);
+        else if (v && typeof v === 'object' && typeof v.text === 'string') {
+            out.push(v.text);
+        }
+    }
+    return out;
+}
+function evaluatorsOf(xs) {
+    return (xs ?? []).map((e) => ({
+        name: e.name,
+        required: e.required !== false,
+        since_schema: e.since_schema ?? 1,
+    }));
+}
+function publishedStepToResolved(s) {
+    return {
+        num: s.num,
+        id: s.id,
+        title: s.title,
+        ...(s.tramo ? { tramo: s.tramo } : {}),
+        ...(s.summary ? { summary: s.summary } : {}),
+        ...(s.form ? { form: s.form } : {}),
+        ...(s.mandatory ? { mandatory: s.mandatory } : {}),
+        prompt_key: s.prompt_key,
+        inputs: artifactsOf(s.inputs),
+        artifacts: artifactsOf(s.artifacts),
+        verify: verifyOf(s.verify),
+        evaluators: evaluatorsOf(s.evaluators),
+    };
+}
+/** The published definition, in the resolved shape. */
+export function publishedToResolved(file, source, hash) {
+    const notices = [];
+    if (file.schema_version > MAX_SCHEMA_VERSION) {
+        notices.push('the definition declares schema ' + file.schema_version + ' and this Forge reads up to '
+            + MAX_SCHEMA_VERSION + ': what schema ' + file.schema_version + ' adds is not read here. '
+            + 'Nothing is approximated -- an evaluator this installation does not implement is reported as declared, not measured.');
+    }
+    const declared = (file.evaluators ?? []).map((e) => e.name).filter((n) => typeof n === 'string').sort();
+    return {
+        source,
+        version: file.catalog_version,
+        hash,
+        schema_version: file.schema_version,
+        steps: file.steps.map(publishedStepToResolved),
+        stations: (file.stations ?? []).map(publishedStepToResolved),
+        declared_evaluators: declared,
+        notices,
+    };
+}
+/** Forge's own compiled catalogue, in the same resolved shape.
+ *
+ *  This is the BASE: what Forge enforced before the method took ownership,
+ *  and what a project freezes when it is started by a Forge that has not
+ *  pulled a published definition. Every step declares exactly one evaluator
+ *  and every one of them is required -- the compiled catalogue has no notion
+ *  of an optional evaluator, which is correct, because it also has no
+ *  evaluator it cannot measure. */
+export function compiledGatesResolved() {
+    const one = (name) => [{ name, required: true, since_schema: 1 }];
+    return {
+        source: 'compiled',
+        version: FORGE_COMPILED_GATES_VERSION,
+        hash: compiledGatesHash(),
+        schema_version: 1,
+        steps: URAZUKE_STEPS.map((s) => ({
+            num: s.num, id: s.id, title: s.title, tramo: s.tramo, summary: s.summary,
+            form: s.form, mandatory: s.mandatory, prompt_key: s.prompt_key,
+            inputs: s.inputs.map((a) => ({ ...a })),
+            artifacts: s.artifacts.map((a) => ({ ...a })),
+            verify: [...s.verify],
+            evaluators: one(s.evaluator),
+        })),
+        stations: URAZUKE_LEGACY_STATIONS.map((s) => ({
+            num: s.num, id: s.id, title: s.title, summary: s.summary, prompt_key: s.prompt_key,
+            inputs: [],
+            artifacts: s.artifacts.map((a) => ({ ...a })),
+            verify: [...s.verify],
+            evaluators: one(s.evaluator),
+        })),
+        declared_evaluators: [...new Set([
+                ...URAZUKE_STEPS.map((s) => s.evaluator),
+                ...URAZUKE_LEGACY_STATIONS.map((s) => s.evaluator),
+            ])].sort(),
+        notices: [],
+    };
+}
+export async function readFrozenGates(projectRoot) {
+    let text;
+    try {
+        text = await fs.readFile(frozenGatesPath(projectRoot), 'utf8');
+    }
+    catch {
+        return { absent: true };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (e) {
+        return { absent: false, refused: ['the frozen copy is not valid JSON: ' + e.message] };
+    }
+    const v = validatePublishedGates(raw);
+    if (!v.ok || !v.file || !v.hash)
+        return { absent: false, refused: v.problems };
+    return { absent: false, gates: publishedToResolved(v.file, 'project', v.hash.recomputed) };
+}
+/** Write the frozen copy. Atomic (tmp + rename) for the same reason the
+ *  prompt overrides are: a half-written definition read by the next turn is
+ *  a project with no rule at all. */
+export async function writeFrozenGates(projectRoot, file) {
+    const f = frozenGatesPath(projectRoot);
+    await fs.mkdir(path.dirname(f), { recursive: true });
+    const tmp = f + '.tmp';
+    await fs.writeFile(tmp, JSON.stringify(file, null, 2) + '\n', 'utf8');
+    await fs.rename(tmp, f);
+}
+/** Serialise the compiled catalogue INTO the published shape, sealed with a
+ *  hash computed the published way, so a frozen copy of the base is read
+ *  back by exactly the same path as a frozen copy of the portal's.
+ *
+ *  This is what "freeze every existing project with what it reads today"
+ *  writes: the base, unchanged, with nothing added. The first day the
+ *  difference is exactly zero and it can be demonstrated -- that is the
+ *  criterion the whole proposal rests on. */
+export function compiledAsPublishedFile() {
+    const r = compiledGatesResolved();
+    const body = {
+        schema_version: 1,
+        catalog_version: FORGE_COMPILED_GATES_VERSION,
+        evaluators: r.declared_evaluators.map((name) => ({ name, since_schema: 1 })),
+        steps: r.steps.map((s) => ({
+            num: s.num, id: s.id, tramo: s.tramo, title: s.title, summary: s.summary,
+            form: s.form, mandatory: s.mandatory, prompt_key: s.prompt_key,
+            inputs: s.inputs, artifacts: s.artifacts, verify: s.verify,
+            evaluators: s.evaluators.map((e) => ({ name: e.name, since_schema: e.since_schema, required: e.required })),
+        })),
+        stations: r.stations.map((s) => ({
+            num: s.num, id: s.id, title: s.title, summary: s.summary, prompt_key: s.prompt_key,
+            artifacts: s.artifacts, verify: s.verify,
+            evaluators: s.evaluators.map((e) => ({ name: e.name, since_schema: e.since_schema, required: e.required })),
+        })),
+    };
+    const covers = ['schema_version', 'catalog_version', 'evaluators', 'steps', 'stations'];
+    const excludes = ['content_hash', 'what', 'frozen_at', 'frozen_from'];
+    const payload = {};
+    for (const k of covers)
+        payload[k] = body[k];
+    const file = {
+        what: 'The gate definition frozen for this project (PND-165). Forge reads THIS'
+            + ' before its own compiled catalogue and before the portal. It is meant to be'
+            + ' committed: a copy that does not travel with the repository thaws on the next'
+            + ' clone. Replaced only by the explicit double lock, never on its own.',
+        ...body,
+        content_hash: {
+            algo: 'sha256',
+            encoding: 'hex_lower',
+            canonical_form: 'json_sorted_keys_codepoint_no_whitespace_utf8',
+            covers,
+            excludes,
+            value: sha256Hex(canonicalJson(payload)),
+            note: 'Recomputed on every read, never trusted as read: that is what makes a'
+                + ' hand-edited or merge-truncated copy detectable without the network.',
+        },
+    };
+    return file;
+}
+/* ---------------- resolution ---------------- */
+/** WHICH gate definition is in force for this project.
+ *
+ *  Precedence: the project's frozen copy, then the compiled catalogue. The
+ *  portal is deliberately absent -- see rule 1 at the top of this file. A
+ *  refused frozen copy does NOT promote the portal and does not fail the
+ *  read: it falls back to the compiled catalogue, which is the safe state
+ *  (nothing can tighten without an install), and it says so. */
+export async function resolveGates(projectRoot) {
+    if (projectRoot) {
+        const frozen = await readFrozenGates(projectRoot);
+        if (frozen.gates)
+            return frozen.gates;
+        if (frozen.refused?.length) {
+            const base = compiledGatesResolved();
+            return {
+                ...base,
+                notices: [
+                    'the frozen gate definition of this project was REFUSED and the compiled catalogue is'
+                        + ' judging instead: ' + frozen.refused.join('; ')
+                        + '. Until it is restored, this project is not being measured by the version it froze.',
+                    ...base.notices,
+                ],
+            };
+        }
+    }
+    return compiledGatesResolved();
+}
+/** Bring the published definition over the network.
+ *
+ *  NOT part of `resolveGates`, on purpose and by decision: the owner asked
+ *  that a project start and finish on the same version of the method, so
+ *  the only legitimate caller is the explicit double lock (Pieza 4), which
+ *  has to show how many green steps would turn red BEFORE it writes
+ *  anything. A validated file or nothing -- an unverifiable definition is
+ *  never handed back. */
+export async function fetchPublishedGates(opts = {}) {
+    const url = opts.url ?? process.env['YF_URAZUKE_GATES_URL'] ?? DEFAULT_GATES_URL;
+    const impl = opts.fetchImpl ?? fetch;
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), opts.timeout_ms ?? 10000);
+    try {
+        const r = await impl(url, { signal: ctrl.signal });
+        if (!r.ok)
+            return { ok: false, problems: ['GET ' + url + ' answered ' + r.status] };
+        return validatePublishedGates(await r.json());
+    }
+    catch (e) {
+        return { ok: false, problems: ['GET ' + url + ' failed: ' + e.message] };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/* ---------------- what this installation can measure ---------------- */
+/** One line for a report or the CLI. */
+export function renderGatesSource(g) {
+    return g.version + ' [' + g.source + '] schema ' + g.schema_version
+        + ' hash ' + g.hash.slice(0, 12)
+        + ' -- ' + g.steps.length + ' steps, ' + g.stations.length + ' stations';
+}
+//# sourceMappingURL=gates_data.js.map