@miadi/inquiry-weave 0.8.3 → 0.9.0

package/dist/mint.js

@@ -0,0 +1,743 @@
+/**
+ * The episode door — mint, land, relate, author lineage, redeem a receipt —
+ * for a caller that never touches the filesystem: the HTTP route and the MCP
+ * server both call these and nothing else.
+ *
+ * The vessel manifest written here is passages' mkepisode shape
+ * (packages/passages/js/lib/mkepisode.js buildManifestYaml), lifted into this
+ * package so the app, which already depends on @miadi/inquiry-weave, has a
+ * typed writer without a process boundary. Byte parity is tested against
+ * passages' own function. scaffoldEpisode() keeps writing its thinner
+ * `status: scaffold` record for the callers it already has.
+ *
+ * Ref: jgwill/Miadi#621, jgwill/Miadi#584, jgwill/Miadi#501.
+ */
+import { mkdir, readdir, readFile, rename, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, relative } from "node:path";
+import { parse } from "yaml";
+import { relate } from "./relate.js";
+import { syncArtefact } from "./sync.js";
+import { resolveArtefact } from "./artefact.js";
+import { registerEpisode } from "./register.js";
+import { appendLineageEdge, } from "./lineage.js";
+import { projectLineageEdge } from "./lineage-edge.js";
+import { DEFAULT_MW_URL, resolveEnv } from "./env.js";
+import { hasEpisodeManifest, localDateStamp, missingManifestRemedy, resolveEpisode, } from "./episode.js";
+import { episodeNodeId, registerEpisodeNode } from "./episode-node.js";
+import { readEpisodeWeave } from "./weave.js";
+import { chronicleGitRoot, integrateOrigin, landPaths, originTreeNames, preflightChronicle, withChronicleLock, } from "./git-landing.js";
+import { closingIsProven, MW_RECEIPT_BASENAME, proveEpisodeClosing, refusePoisonedWheel, WHEEL_PROBE_TIMEOUT_MS, } from "./closing.js";
+export class EpisodeServiceError extends Error {
+    code;
+    detail;
+    constructor(code, message, detail) {
+        super(message);
+        this.code = code;
+        this.detail = detail;
+        this.name = "EpisodeServiceError";
+    }
+}
+// ── Manifest (mkepisode shape) ──────────────────────────────────────────────
+export function normalizeSlug(title) {
+    return title
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+const PLAIN_SCALAR = /^[A-Za-z][A-Za-z0-9 ._-]*$/;
+const YAML_RESERVED = /^(true|false|null|~|yes|no|on|off)$/i;
+export function yamlScalar(value) {
+    const text = String(value);
+    if (PLAIN_SCALAR.test(text) && !YAML_RESERVED.test(text))
+        return text;
+    return JSON.stringify(text);
+}
+/** Byte-identical to passages' mkepisode buildManifestYaml(). */
+export function buildVesselManifestYaml(vessel) {
+    const lines = [
+        `episode: ${vessel.number}`,
+        `title: ${yamlScalar(vessel.title)}`,
+        `slug: ${yamlScalar(vessel.slug)}`,
+        `date: '${vessel.date}'`,
+        "series: miadi-chronicle",
+        `status: ${yamlScalar(vessel.status ?? "vessel")}`,
+        "type: chronicle-episode",
+        `goal: ${yamlScalar(vessel.goal)}`,
+        "references:",
+        ...vessel.references.map((reference) => `  - ${yamlScalar(reference)}`),
+    ];
+    return `${lines.join("\n")}\n`;
+}
+const ISSUE_REF = /^[\w.-]+\/[\w.-]+#\d+$/;
+export function findSourceIssue(references) {
+    return references.find((reference) => ISSUE_REF.test(reference));
+}
+// ── Context ─────────────────────────────────────────────────────────────────
+/** `MIADI_CHRONICLE_MW_URL` is the wheel variable of record (chronicle commit 1900c1b, 2026-09-04). */
+export function chronicleWheelUrl(env = process.env) {
+    const url = env.MIADI_CHRONICLE_MW_URL?.trim() || env.MW_API_URL?.trim() || DEFAULT_MW_URL;
+    return url.replace(/\/+$/, "");
+}
+export function resolveDoorContext(options = {}, env = process.env) {
+    const weave = resolveEnv({ chronicleRoot: options.chronicleRoot, inquiryRoot: options.inquiryRoot }, env);
+    return {
+        chronicleRoot: weave.chronicleRoot,
+        inquiryRoot: weave.inquiryRoot,
+        wheelUrl: options.wheelUrl ?? chronicleWheelUrl(env),
+        gitRoot: options.gitRoot,
+        now: options.now,
+        fetchImpl: options.fetchImpl,
+    };
+}
+async function gitRootOf(context) {
+    if (context.gitRoot)
+        return context.gitRoot;
+    context.gitRoot = await chronicleGitRoot(context.chronicleRoot);
+    return context.gitRoot;
+}
+function nowOf(context) {
+    return context.now ? context.now() : new Date();
+}
+async function wheelEpisodeNames(context) {
+    const fetchImpl = context.fetchImpl ?? fetch;
+    const url = `${context.wheelUrl}/api/nodes?kind=chronicle_episode&parent_id=${encodeURIComponent("chronicle:miadi-chronicle")}&limit=5000`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), WHEEL_PROBE_TIMEOUT_MS);
+    try {
+        const response = await fetchImpl(url, { signal: controller.signal });
+        if (!response.ok)
+            return { ok: false, names: [], observed: `GET ${url}: HTTP ${response.status}` };
+        const body = (await response.json());
+        const names = (body.nodes ?? [])
+            .map((node) => (typeof node.id === "string" ? node.id.replace(/^chronicle:/, "") : ""))
+            .filter(Boolean);
+        const truncated = body.truncated === true ? " (TRUNCATED — the wheel did not return every card)" : "";
+        return { ok: true, names, observed: `${names.length} wheel cards${truncated}` };
+    }
+    catch (error) {
+        return { ok: false, names: [], observed: `wheel unreachable at ${url}: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function knownNames(context, gitRoot) {
+    let disk = [];
+    try {
+        disk = await readdir(context.chronicleRoot);
+    }
+    catch {
+        disk = [];
+    }
+    const subdir = relative(gitRoot, context.chronicleRoot);
+    const origin = await originTreeNames(gitRoot, subdir);
+    const wheel = await wheelEpisodeNames(context);
+    return {
+        disk,
+        origin: origin.names,
+        wheel: wheel.names,
+        originAnswered: origin.ok,
+        wheelAnswered: wheel.ok,
+        originObserved: origin.observed,
+        wheelObserved: wheel.observed,
+    };
+}
+function numberPattern(number) {
+    return new RegExp(`-episode-0*${number}-`);
+}
+const EPISODE_NUMBER = /episode-(\d+)/;
+function maxNumber(names) {
+    let max = 0;
+    for (const name of names) {
+        const match = EPISODE_NUMBER.exec(name);
+        if (match)
+            max = Math.max(max, Number(match[1]));
+    }
+    return max;
+}
+/**
+ * Is `number` free everywhere the chronicle is known? Fetches origin first
+ * (jgwill/Miadi#501) and lists the wheel (jgwill/Miadi#584). Read-only.
+ */
+export async function checkEpisodeNumber(context, number, options = {}) {
+    const gitRoot = await gitRootOf(context);
+    if (!options.skipFetch)
+        await integrateOrigin(gitRoot, { dryRun: true });
+    const known = await knownNames(context, gitRoot);
+    const pattern = numberPattern(number);
+    const existing = [];
+    for (const name of known.disk)
+        if (pattern.test(name))
+            existing.push({ name, seen: "disk" });
+    for (const name of known.origin)
+        if (pattern.test(name) && !existing.some((e) => e.name === name))
+            existing.push({ name, seen: "origin" });
+    for (const name of known.wheel)
+        if (pattern.test(name) && !existing.some((e) => e.name === name))
+            existing.push({ name, seen: "wheel" });
+    const union = new Set([...known.disk, ...known.origin]);
+    const blind = [
+        known.originAnswered ? "" : `origin unreadable (${known.originObserved})`,
+        known.wheelAnswered ? "" : `wheel unreadable (${known.wheelObserved})`,
+    ].filter(Boolean);
+    const observed = existing.length
+        ? `episode ${number} already resolves: ${existing.map((e) => `${e.name} [${e.seen}]`).join(", ")}`
+        : `episode ${number} is free over ${union.size} names (disk ∪ origin/main) and ${known.wheel.length} wheel cards` +
+            (blind.length ? `; ${blind.join("; ")}` : "");
+    return {
+        number,
+        taken: existing.length > 0,
+        existing,
+        observed,
+        originAnswered: known.originAnswered,
+        wheelAnswered: known.wheelAnswered,
+    };
+}
+/**
+ * max(disk ∪ origin/main ∪ wheel) + 1. Never fills a hole. Refuses when the
+ * wheel does not answer: an allocation blind to the wheel is the #584 defect.
+ */
+export async function previewAllocation(context, options = {}) {
+    const gitRoot = await gitRootOf(context);
+    if (!options.skipFetch)
+        await integrateOrigin(gitRoot, { dryRun: true });
+    const known = await knownNames(context, gitRoot);
+    if (!known.wheelAnswered) {
+        throw new EpisodeServiceError("number_unverifiable", `cannot allocate a number while the wheel does not answer (${known.wheelObserved}); pass an explicit number or retry`);
+    }
+    const max = maxNumber([...known.disk, ...known.origin, ...known.wheel]);
+    return {
+        next: max + 1,
+        max,
+        observed: `max ${max} over ${known.disk.length} disk names, ${known.origin.length} origin/main names, ${known.wheel.length} wheel cards` +
+            (known.originAnswered ? "" : `; origin unreadable (${known.originObserved})`),
+        originAnswered: known.originAnswered,
+        wheelAnswered: known.wheelAnswered,
+    };
+}
+async function registerAndReceipt(context, episode, card, options) {
+    const node_id = episodeNodeId(episode.name);
+    if (options.dryRun) {
+        return { state: "would-register", node_id, url: context.wheelUrl, receiptWritten: false };
+    }
+    let outcome;
+    try {
+        outcome = await registerEpisodeNode(context.wheelUrl, {
+            episodeName: episode.name,
+            name: `Episode ${episode.number} — ${card.title}`,
+            description: card.goal,
+            sourceIssue: card.sourceIssue,
+        }, { fetchImpl: context.fetchImpl });
+    }
+    catch (error) {
+        outcome = { state: "pending", node_id, error: error instanceof Error ? error.message : String(error) };
+    }
+    const receipt = {
+        state: outcome.state,
+        node_id: outcome.node_id,
+        timestamp: nowOf(context).toISOString(),
+        url: context.wheelUrl,
+    };
+    if (outcome.error)
+        receipt.error = outcome.error;
+    let receiptWritten = false;
+    try {
+        await writeFile(join(episode.dir, MW_RECEIPT_BASENAME), `${JSON.stringify(receipt, null, 2)}\n`, "utf8");
+        receiptWritten = true;
+    }
+    catch {
+        receiptWritten = false;
+    }
+    return { state: outcome.state, node_id: outcome.node_id, url: context.wheelUrl, error: outcome.error, receiptWritten };
+}
+/**
+ * The files the door itself knows to be the vessel's, relative to the git root:
+ * manifest, receipt, the weave record, and each synced artefact copy. Never the
+ * whole directory — a chapter someone is drafting there is not the door's.
+ */
+export async function vesselPaths(gitRoot, episode) {
+    const rel = relative(gitRoot, episode.dir);
+    const paths = [`${rel}/episode.yaml`, `${rel}/${MW_RECEIPT_BASENAME}`, `${rel}/inquiry/weave.yaml`];
+    try {
+        const weave = await readEpisodeWeave(episode.dir);
+        for (const entry of weave?.inquiries ?? [])
+            paths.push(`${rel}/inquiry/${entry.artefact}`);
+    }
+    catch {
+        // an unreadable weave file is reported by status, not by landing
+    }
+    return paths.filter((path) => existsSync(join(gitRoot, path)));
+}
+async function readManifestSummary(episode) {
+    const path = join(episode.dir, "episode.yaml");
+    if (!existsSync(path))
+        return { present: false };
+    try {
+        const parsed = parse(await readFile(path, "utf8"));
+        return {
+            present: true,
+            status: typeof parsed?.status === "string" ? parsed.status : undefined,
+            title: typeof parsed?.title === "string" ? parsed.title : undefined,
+            goal: typeof parsed?.goal === "string" ? parsed.goal : undefined,
+            references: Array.isArray(parsed?.references) ? parsed.references.map(String) : undefined,
+        };
+    }
+    catch {
+        return { present: true };
+    }
+}
+async function closingFor(context, folder) {
+    return proveEpisodeClosing({ chronicleRoot: context.chronicleRoot, gitRoot: await gitRootOf(context), wheelUrl: context.wheelUrl, fetchImpl: context.fetchImpl }, folder);
+}
+async function requirePreflight(gitRoot) {
+    const preflight = await preflightChronicle(gitRoot);
+    if (!preflight.ok)
+        throw new EpisodeServiceError(preflight.code, preflight.message);
+}
+function commitBody(lead, references) {
+    const issue = findSourceIssue(references);
+    const lines = [lead, ""];
+    if (issue)
+        lines.push(`Ref: ${issue}`);
+    for (const reference of references)
+        if (reference !== issue)
+            lines.push(`Reference: ${reference}`);
+    lines.push("", "Minted-By: miadi-api");
+    return lines.join("\n");
+}
+// ── Resolve with the door's error taxonomy ──────────────────────────────────
+export function parseEpisodeRef(raw) {
+    const ref = typeof raw === "string" ? raw.trim() : "";
+    if (!ref)
+        throw new EpisodeServiceError("invalid_ref", "episode reference is required (a number, epNNN, or a directory name)");
+    if (ref.includes("/") || ref.includes("\\") || ref === "." || ref === "..") {
+        throw new EpisodeServiceError("invalid_ref", `episode reference '${ref}' looks like a path — the door resolves numbers, epNNN, or directory names only`);
+    }
+    return ref;
+}
+export async function resolveDoorEpisode(context, ref) {
+    // EpisodeResolutionError / AmbiguousEpisodeError pass through untouched so
+    // the route maps them to 404 / 409 exactly as the attention door does.
+    return resolveEpisode(context.chronicleRoot, parseEpisodeRef(ref));
+}
+export async function episodeDoorStatus(context, ref) {
+    const identity = await resolveDoorEpisode(context, ref);
+    const report = await closingFor(context, identity.name);
+    return { ...report, identity, manifest: await readManifestSummary(identity), ok: closingIsProven(report) };
+}
+async function landIdentity(context, identity, input, defaults) {
+    const gitRoot = await gitRootOf(context);
+    await requirePreflight(gitRoot);
+    const files = await vesselPaths(gitRoot, identity);
+    const landing = await landPaths({
+        gitRoot,
+        paths: files,
+        subject: input.subject?.trim() || defaults.subject,
+        body: input.body?.trim() || defaults.body,
+        dryRun: input.dryRun,
+        push: input.push,
+    });
+    const report = await closingFor(context, identity.name);
+    return {
+        ok: closingIsProven(report),
+        dryRun: input.dryRun === true,
+        identity,
+        files,
+        landing,
+        closing: report.closing,
+        drift: report.drift,
+        owedActions: report.owedActions,
+    };
+}
+export async function landEpisode(context, ref, input = {}) {
+    const identity = await resolveDoorEpisode(context, ref);
+    const manifest = await readManifestSummary(identity);
+    const gitRoot = await gitRootOf(context);
+    return withChronicleLock(gitRoot, () => landIdentity(context, identity, input, {
+        subject: `ep${identity.number ?? "?"}: ${manifest.title ?? identity.slug ?? identity.name}`,
+        body: commitBody("Vessel landed through POST /api/chronicle/episodes/{ref}/land.", manifest.references ?? []),
+    }));
+}
+export function parseLineageField(raw) {
+    switch (raw) {
+        case "continues_from":
+        case "continues-from":
+            return "continues_from";
+        case "relates_to":
+        case "relates-to":
+        case "related-to":
+            return "relates_to";
+        default:
+            throw new EpisodeServiceError("invalid_field", `field must be continues_from or relates_to (got '${String(raw)}')`);
+    }
+}
+async function authorEdges(context, from, edges, options) {
+    if (!hasEpisodeManifest(from.dir)) {
+        throw new EpisodeServiceError("manifest_missing", missingManifestRemedy(from.dir));
+    }
+    const reports = [];
+    for (const edge of edges) {
+        const to = await resolveDoorEpisode(context, edge.to);
+        if (!hasEpisodeManifest(to.dir) && edge.reverse !== undefined) {
+            throw new EpisodeServiceError("manifest_missing", missingManifestRemedy(to.dir));
+        }
+        const pairs = [
+            { field: edge.field, a: from, b: to, relation: edge.relation },
+        ];
+        if (edge.reverse !== undefined)
+            pairs.push({ field: "relates_to", a: to, b: from, relation: edge.reverse });
+        for (const pair of pairs) {
+            const manifest = await appendLineageEdge({
+                episodeYamlPath: join(pair.a.dir, "episode.yaml"),
+                field: pair.field,
+                target: { episode: pair.b.number, path: pair.b.path },
+                relation: pair.relation,
+                dryRun: options.dryRun,
+            });
+            const wheel = await projectLineageEdge(context.wheelUrl, {
+                fromNodeId: episodeNodeId(pair.a.path),
+                toNodeId: episodeNodeId(pair.b.path),
+                relationshipType: pair.field,
+                description: pair.relation,
+            }, { dryRun: options.dryRun, fetchImpl: context.fetchImpl });
+            const { before: _before, after: _after, ...rest } = manifest;
+            reports.push({ field: pair.field, from: pair.a.name, to: pair.b.name, manifest: rest, wheel });
+        }
+    }
+    return reports;
+}
+export async function authorEpisodeLineage(context, ref, input) {
+    const relation = input.relation?.trim();
+    if (!relation)
+        throw new EpisodeServiceError("identity_required", "a lineage edge needs field, to, and a non-empty relation");
+    const field = parseLineageField(input.field);
+    parseEpisodeRef(input.to);
+    const identity = await resolveDoorEpisode(context, ref);
+    const gitRoot = await gitRootOf(context);
+    return withChronicleLock(gitRoot, async () => {
+        const edges = await authorEdges(context, identity, [{ ...input, field, relation }], { dryRun: input.dryRun });
+        let landing;
+        if (input.land !== false) {
+            const targets = edges.map((edge) => edge.to).filter((name, index, all) => all.indexOf(name) === index);
+            landing = await landIdentity(context, identity, { dryRun: input.dryRun }, {
+                subject: `ep${identity.number ?? "?"}: lineage ${input.field} -> ${input.to}`,
+                body: commitBody(`Lineage authored through POST /api/chronicle/episodes/{ref}/lineage.\n\nEdges: ${edges.map((e) => `${e.from} ${e.field} ${e.to}`).join("; ")}`, []),
+            });
+            // A reverse edge lives in the target's manifest; land that file too.
+            if (input.reverse !== undefined && !input.dryRun) {
+                for (const name of targets) {
+                    const target = await resolveDoorEpisode(context, name);
+                    await landIdentity(context, target, { dryRun: false }, {
+                        subject: `ep${target.number ?? "?"}: lineage relates_to -> ${identity.name}`,
+                        body: commitBody("Reverse lineage authored through POST /api/chronicle/episodes/{ref}/lineage.", []),
+                    });
+                }
+            }
+        }
+        const report = await closingFor(context, identity.name);
+        return {
+            ok: closingIsProven(report) && edges.every((edge) => edge.wheel.state !== "pending"),
+            dryRun: input.dryRun === true,
+            identity,
+            edges,
+            landing,
+            closing: report.closing,
+            drift: report.drift,
+            owedActions: report.owedActions,
+        };
+    });
+}
+export function parseArtefactName(raw) {
+    const name = typeof raw === "string" ? raw.trim().replace(/\/+$/, "") : "";
+    if (!name)
+        throw new EpisodeServiceError("identity_required", "artefact is required (a directory name under the inquiry root)");
+    if (name.includes("/") || name.includes("\\") || name.startsWith(".")) {
+        throw new EpisodeServiceError("invalid_artefact", `artefact '${name}' must be a bare directory name under the inquiry root, not a path`);
+    }
+    return name;
+}
+async function weaveInquiry(context, identity, input) {
+    const name = parseArtefactName(input.artefact);
+    if (input.issue !== undefined && !ISSUE_REF.test(input.issue.trim())) {
+        throw new EpisodeServiceError("invalid_reference", `issue '${input.issue}' must be owner/repo#N`);
+    }
+    let artefact;
+    try {
+        artefact = resolveArtefact(context.inquiryRoot, name);
+    }
+    catch (error) {
+        throw new EpisodeServiceError("invalid_artefact", error instanceof Error ? error.message : String(error));
+    }
+    const related = await relate({
+        artefact,
+        episode: identity,
+        issue: input.issue?.trim(),
+        now: context.now,
+        dryRun: input.dryRun,
+    });
+    const synced = await syncArtefact(artefact.dir, identity.dir, {
+        dryRun: input.dryRun,
+        allowUnrelated: input.dryRun,
+        now: context.now,
+    });
+    let registered;
+    let registerError;
+    if (!input.dryRun) {
+        try {
+            registered = await registerEpisode({ chronicleRoot: context.chronicleRoot, inquiryRoot: context.inquiryRoot, mwUrl: context.wheelUrl, repo: resolveEnv().repo }, identity, { now: context.now });
+        }
+        catch (error) {
+            registerError = error instanceof Error ? error.message : String(error);
+        }
+    }
+    return {
+        related,
+        synced,
+        registered,
+        registerError,
+        artefactSide: input.dryRun
+            ? "not written (dry run)"
+            : `written under ${artefact.dir} (.weave.yaml, AGENTS.md) — another repository; not committed by this door`,
+    };
+}
+export async function weaveEpisodeInquiry(context, ref, input) {
+    const identity = await resolveDoorEpisode(context, ref);
+    const gitRoot = await gitRootOf(context);
+    return withChronicleLock(gitRoot, async () => {
+        const inquiry = await weaveInquiry(context, identity, input);
+        let landing;
+        if (input.land !== false) {
+            landing = await landIdentity(context, identity, { dryRun: input.dryRun }, {
+                subject: `ep${identity.number ?? "?"}: weave ${inquiry.related.artefact}`,
+                body: commitBody("Inquiry woven and synced through POST /api/chronicle/episodes/{ref}/inquiry.", inquiry.related.issue ? [inquiry.related.issue] : []),
+            });
+        }
+        const report = await closingFor(context, identity.name);
+        return {
+            ok: closingIsProven(report) && !inquiry.registerError,
+            dryRun: input.dryRun === true,
+            identity,
+            inquiry,
+            landing,
+            closing: report.closing,
+            drift: report.drift,
+            owedActions: report.owedActions,
+        };
+    });
+}
+export async function redeemEpisodeRegistration(context, ref, input = {}) {
+    refusePoisonedWheelOrThrow(context.wheelUrl);
+    const identity = await resolveDoorEpisode(context, ref);
+    if (!hasEpisodeManifest(identity.dir)) {
+        throw new EpisodeServiceError("manifest_missing", missingManifestRemedy(identity.dir));
+    }
+    const manifest = await readManifestSummary(identity);
+    const gitRoot = await gitRootOf(context);
+    return withChronicleLock(gitRoot, async () => {
+        const registration = await registerAndReceipt(context, identity, {
+            title: manifest.title ?? identity.slug ?? identity.name,
+            goal: manifest.goal ?? "",
+            sourceIssue: findSourceIssue(manifest.references ?? []),
+        }, { dryRun: input.dryRun });
+        let landing;
+        if (input.land !== false) {
+            landing = await landIdentity(context, identity, { dryRun: input.dryRun }, {
+                subject: `ep${identity.number ?? "?"}: registration receipt ${registration.state}`,
+                body: commitBody("Receipt redeemed through POST /api/chronicle/episodes/{ref}/register.", manifest.references ?? []),
+            });
+        }
+        const report = await closingFor(context, identity.name);
+        return {
+            ok: closingIsProven(report),
+            dryRun: input.dryRun === true,
+            identity,
+            registration,
+            landing,
+            closing: report.closing,
+            drift: report.drift,
+            owedActions: report.owedActions,
+        };
+    });
+}
+function refusePoisonedWheelOrThrow(wheelUrl) {
+    try {
+        refusePoisonedWheel(wheelUrl);
+    }
+    catch (error) {
+        throw new EpisodeServiceError("wheel_refused", error instanceof Error ? error.message : String(error));
+    }
+}
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+function validateMintInput(input) {
+    const title = typeof input.title === "string" ? input.title.trim() : "";
+    const goal = typeof input.goal === "string" ? input.goal.trim() : "";
+    const references = Array.isArray(input.references)
+        ? input.references.map((reference) => (typeof reference === "string" ? reference.trim() : "")).filter(Boolean)
+        : [];
+    if (!title || !goal || references.length === 0) {
+        throw new EpisodeServiceError("identity_required", "title, goal, and at least one reference are required");
+    }
+    const slug = normalizeSlug(title);
+    if (!slug)
+        throw new EpisodeServiceError("identity_required", `title '${title}' yields an empty slug`);
+    const status = typeof input.status === "string" && input.status.trim() ? input.status.trim() : "vessel";
+    if (input.date !== undefined && (typeof input.date !== "string" || !DATE.test(input.date))) {
+        throw new EpisodeServiceError("invalid_date", "date must be YYYY-MM-DD");
+    }
+    let number;
+    if (input.number !== undefined && input.number !== null) {
+        if (typeof input.number !== "number" || !Number.isSafeInteger(input.number) || input.number < 1) {
+            throw new EpisodeServiceError("invalid_number", "number must be a positive integer");
+        }
+        number = input.number;
+    }
+    const lineage = [];
+    for (const edge of input.lineage ?? []) {
+        if (typeof edge?.relation !== "string" || !edge.relation.trim()) {
+            throw new EpisodeServiceError("identity_required", "each lineage edge needs field, to, and a non-empty relation");
+        }
+        lineage.push({
+            field: parseLineageField(edge.field),
+            to: parseEpisodeRef(edge.to),
+            relation: edge.relation.trim(),
+            reverse: typeof edge.reverse === "string" && edge.reverse.trim() ? edge.reverse.trim() : undefined,
+        });
+    }
+    if (input.inquiry)
+        parseArtefactName(input.inquiry.artefact);
+    return { title, slug, goal, references, status, date: input.date, number, lineage };
+}
+export async function mintEpisode(context, input) {
+    const vessel = validateMintInput(input);
+    const dryRun = input.dryRun === true;
+    const register = input.register !== false;
+    if (register)
+        refusePoisonedWheelOrThrow(context.wheelUrl);
+    const gitRoot = await gitRootOf(context);
+    return withChronicleLock(gitRoot, async () => {
+        await requirePreflight(gitRoot);
+        // Integrate first so the disk sees what origin has (jgwill/Miadi#501). In a
+        // dry run the fetch happens and the tree is left alone.
+        const integration = await integrateOrigin(gitRoot, { dryRun });
+        if (integration.state === "refused") {
+            throw new EpisodeServiceError("chronicle_integration_refused", integration.observed, integration);
+        }
+        let number;
+        let numberObserved;
+        let source;
+        if (vessel.number !== undefined) {
+            const check = await checkEpisodeNumber(context, vessel.number, { skipFetch: true });
+            if (check.taken) {
+                throw new EpisodeServiceError("number_taken", check.observed, { existing: check.existing });
+            }
+            number = vessel.number;
+            numberObserved = check.observed;
+            source = "explicit";
+        }
+        else {
+            const allocation = await previewAllocation(context, { skipFetch: true });
+            number = allocation.next;
+            numberObserved = `allocated ${number}: ${allocation.observed}`;
+            source = "allocated";
+        }
+        const date = vessel.date ?? localDateStamp(nowOf(context));
+        const name = `${date}-episode-${String(number).padStart(3, "0")}-${vessel.slug}`;
+        const dir = join(context.chronicleRoot, name);
+        const identity = { number, slug: vessel.slug, date, name, dir, path: name };
+        const manifest = buildVesselManifestYaml({ ...vessel, number, date });
+        const sourceIssue = findSourceIssue(vessel.references);
+        const rel = relative(gitRoot, dir);
+        if (dryRun) {
+            const lineage = vessel.lineage.length
+                ? await authorEdges(context, { ...identity }, vessel.lineage, { dryRun: true }).catch((error) => {
+                    // The vessel does not exist yet in a dry run; the manifest check refuses.
+                    if (error instanceof EpisodeServiceError && error.code === "manifest_missing")
+                        return [];
+                    throw error;
+                })
+                : [];
+            const report = await closingFor(context, name);
+            return {
+                ok: false,
+                dryRun: true,
+                identity,
+                number: { source, observed: numberObserved },
+                manifest,
+                files: [`${rel}/episode.yaml`, ...(register ? [`${rel}/${MW_RECEIPT_BASENAME}`] : [])],
+                lineage,
+                inquiry: null,
+                registration: {
+                    state: register ? "would-register" : "skipped",
+                    node_id: episodeNodeId(name),
+                    url: context.wheelUrl,
+                    receiptWritten: false,
+                },
+                landing: null,
+                integration,
+                closing: report.closing,
+                drift: report.drift,
+                owedActions: report.owedActions,
+            };
+        }
+        // mkdir without recursive: EEXIST is the atomicity primitive between the
+        // number check and the write (mkepisode.js uses `wx` for the same reason).
+        try {
+            await mkdir(dir);
+        }
+        catch (error) {
+            throw new EpisodeServiceError("number_taken", `episode directory appeared between the check and the write: ${dir} (${error instanceof Error ? error.message : String(error)})`);
+        }
+        const manifestPath = join(dir, "episode.yaml");
+        const temporary = join(dir, `.episode.yaml.mint-${process.pid}`);
+        await writeFile(temporary, manifest, { encoding: "utf8", flag: "wx" });
+        await rename(temporary, manifestPath);
+        const lineage = vessel.lineage.length ? await authorEdges(context, identity, vessel.lineage, { dryRun: false }) : [];
+        const inquiry = input.inquiry ? await weaveInquiry(context, identity, { ...input.inquiry, dryRun: false }) : null;
+        const registration = register
+            ? await registerAndReceipt(context, identity, { title: vessel.title, goal: vessel.goal, sourceIssue }, { dryRun: false })
+            : { state: "skipped", node_id: episodeNodeId(name), url: context.wheelUrl, receiptWritten: false };
+        const files = await vesselPaths(gitRoot, identity);
+        for (const edge of lineage) {
+            // A reverse edge changed the target's manifest; that file lands in the same commit.
+            if (edge.from !== identity.name) {
+                const targetPath = `${relative(gitRoot, join(context.chronicleRoot, edge.from))}/episode.yaml`;
+                if (!files.includes(targetPath))
+                    files.push(targetPath);
+            }
+        }
+        let landing = null;
+        if (input.land !== false) {
+            landing = await landPaths({
+                gitRoot,
+                paths: files,
+                subject: `ep${number}: ${vessel.title}`,
+                body: commitBody("Vessel minted through POST /api/chronicle/episodes.", vessel.references),
+                dryRun: false,
+            });
+        }
+        const report = await closingFor(context, name);
+        return {
+            ok: closingIsProven(report),
+            dryRun: false,
+            identity,
+            number: { source, observed: numberObserved },
+            manifest,
+            files,
+            lineage,
+            inquiry,
+            registration,
+            landing,
+            integration,
+            closing: report.closing,
+            drift: report.drift,
+            owedActions: report.owedActions,
+        };
+    });
+}
+/** Map library errors to the door's codes; anything unknown passes through. */
+export function isDoorError(error) {
+    return error instanceof EpisodeServiceError;
+}
+//# sourceMappingURL=mint.js.map