@miadi/inquiry-weave 0.16.6 → 0.17.1

package/dist/mint.js

@@ -32,6 +32,16 @@ import { existingReviewRelation, fetchPublicReview, projectEpisodeReview, requir
 import { readEpisodeReviews, reviewNodeId, reviewReference } from "@miadi/episodic-memory-schema";
 import { DEFAULT_FOUNDATION_RELATION, episodeFoundationPath, foundationNodeId, readEpisodeFoundations, } from "@miadi/episodic-memory-schema";
 import { existingFoundationRelation, FoundationError, foundationLookupFromDir, foundationLookupFromFront, projectEpisodeFoundation, readEpisodePacket, requireFoundationSlug, upsertEpisodeFoundation, } from "./foundation.js";
+import { NotebookError, existingNotebookRelation, projectEpisodeNotebook, readNotebookFolder, requireNotebookRef, upsertEpisodeNotebook, } from "./notebook.js";
+import { PrototypeError, existingPrototypeRelation, optionalEditorUrl, assertDistinctPrototypeAddresses, projectEpisodePrototype, prototypeEditorUrl, requirePrototypeSlug, requirePrototypeUrl, upsertEpisodePrototype, } from "./prototype.js";
+import { TracingError, existingTracingRelation, optionalUiUrl, projectEpisodeTracing, requireTracingRef, tracingProviderName, tracingUiUrl, upsertEpisodeTracing, } from "./tracing.js";
+import { PdeError, readEpisodePdeFolder, requirePdeUuid, upsertEpisodePde } from "./pde.js";
+import { DEFAULT_PDE_RELATION, PDE_ENTRY_KEYS, isRelativePdePath, readEpisodePdes } from "@miadi/episodic-memory-schema";
+import { RispecError, existingRispecRelation, projectEpisodeRispec, requireRiseRef, upsertEpisodeRispec } from "./rispec.js";
+import { DEFAULT_RISPEC_RELATION, readEpisodeRispecs, riseNodeId, riseReference } from "@miadi/episodic-memory-schema";
+import { defaultTracingRelation, readEpisodeTracing, tracingKey, tracingNodeId, } from "@miadi/episodic-memory-schema";
+import { DEFAULT_PROTOTYPE_RELATION, prototypeNodeId, readEpisodePrototypes, } from "@miadi/episodic-memory-schema";
+import { DEFAULT_NOTEBOOK_RELATION, notebookNodeId, readEpisodeNotebooks, } from "@miadi/episodic-memory-schema";
 import { closingIsProven, MW_RECEIPT_BASENAME, proveEpisodeClosing, refusePoisonedWheel, WHEEL_PROBE_TIMEOUT_MS, } from "./closing.js";
 export class EpisodeServiceError extends Error {
     code;
@@ -794,6 +804,70 @@ function asFoundationDoorError(error) {
     }
     throw error;
 }
+function asNotebookDoorError(error) {
+    if (error instanceof NotebookError) {
+        const code = error.code === "notebook_manifest_conflict" ? "invalid_field" : error.code;
+        throw new EpisodeServiceError(code, error.message);
+    }
+    throw error;
+}
+function asPrototypeDoorError(error) {
+    if (error instanceof PrototypeError) {
+        const code = error.code === "prototype_manifest_conflict" ? "invalid_field" : error.code;
+        throw new EpisodeServiceError(code, error.message);
+    }
+    throw error;
+}
+function asTracingDoorError(error) {
+    if (error instanceof TracingError) {
+        const code = error.code === "tracing_manifest_conflict" ? "invalid_field" : error.code;
+        throw new EpisodeServiceError(code, error.message);
+    }
+    throw error;
+}
+function asRispecDoorError(error) {
+    if (error instanceof RispecError) {
+        const code = error.code === "rispec_manifest_conflict" ? "invalid_field" : error.code;
+        throw new EpisodeServiceError(code, error.message);
+    }
+    throw error;
+}
+function parseRispecRelation(raw) {
+    if (raw === undefined || raw === null || raw === "")
+        return undefined;
+    const relation = typeof raw === "string" ? raw.trim() : "";
+    if (!/^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$/.test(relation) || relation.length > 80) {
+        throw new EpisodeServiceError("invalid_field", `relation '${String(raw)}' must be a kebab-case phrase completing "Episode <relation> Spec", e.g. is-specified-in or revises`);
+    }
+    return relation;
+}
+function parseTracingRelation(raw) {
+    if (raw === undefined || raw === null || raw === "")
+        return undefined;
+    const relation = typeof raw === "string" ? raw.trim() : "";
+    if (!/^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$/.test(relation) || relation.length > 80) {
+        throw new EpisodeServiceError("invalid_field", `relation '${String(raw)}' must be a kebab-case phrase completing "Episode <relation> Resource", e.g. is-traced-in`);
+    }
+    return relation;
+}
+function parsePrototypeRelation(raw) {
+    if (raw === undefined || raw === null || raw === "")
+        return undefined;
+    const relation = typeof raw === "string" ? raw.trim() : "";
+    if (!/^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$/.test(relation) || relation.length > 80) {
+        throw new EpisodeServiceError("invalid_field", `relation '${String(raw)}' must be a kebab-case phrase completing "Episode <relation> Prototype", e.g. is-prototyped-in`);
+    }
+    return relation;
+}
+function parseNotebookRelation(raw) {
+    if (raw === undefined || raw === null || raw === "")
+        return undefined;
+    const relation = typeof raw === "string" ? raw.trim() : "";
+    if (!/^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$/.test(relation) || relation.length > 80) {
+        throw new EpisodeServiceError("invalid_field", `relation '${String(raw)}' must be a kebab-case phrase completing "Episode <relation> Notebook", e.g. cites`);
+    }
+    return relation;
+}
 function parseFoundationRelation(raw) {
     if (raw === undefined || raw === null || raw === "")
         return undefined;
@@ -904,6 +978,497 @@ export async function listEpisodeFoundations(context, ref) {
     }
     return { identity, foundations: readEpisodeFoundations(manifest) };
 }
+/**
+ * Hold a notebook in an episode: the manifest entry (filling only what a
+ * hand-written entry lacks), the `notebook:<uuid>` node and the episode→notebook
+ * edge on the wheel, and the landing. The folder under `captures/` is read for
+ * its files and title when the episode keeps one; nothing is written there.
+ */
+export async function attachEpisodeNotebook(context, ref, input) {
+    let notebook;
+    try {
+        notebook = requireNotebookRef(input.notebook);
+    }
+    catch (error) {
+        asNotebookDoorError(error);
+    }
+    const asked = parseNotebookRelation(input.relation);
+    const identity = await resolveDoorEpisode(context, ref);
+    if (!hasEpisodeManifest(identity.dir)) {
+        throw new EpisodeServiceError("manifest_missing", missingManifestRemedy(identity.dir));
+    }
+    const folder = await readNotebookFolder(identity.dir, notebook.id);
+    const gitRoot = await gitRootOf(context);
+    return withChronicleLock(gitRoot, async () => {
+        const manifestPath = join(identity.dir, "episode.yaml");
+        const nodeEpisode = episodeNodeId(identity.path);
+        const nodeId = notebookNodeId(notebook.id);
+        let previous;
+        try {
+            previous = readEpisodeNotebooks(parse(await readFile(manifestPath, "utf8"))).find((entry) => entry.id === notebook.id);
+        }
+        catch {
+            previous = undefined;
+        }
+        // One ordered pair is one edge on the wheel; a hand-made edge keeps its relation.
+        const onWheel = await existingNotebookRelation(context.wheelUrl, nodeEpisode, nodeId, { fetchImpl: context.fetchImpl });
+        const relation = onWheel ?? previous?.relation ?? asked ?? DEFAULT_NOTEBOOK_RELATION;
+        const relationNote = asked && asked !== relation
+            ? `asked for '${asked}', kept '${relation}': ${onWheel ? "the wheel already holds that edge" : "the episode already recorded that relation"}`
+            : undefined;
+        const sources = input.sources?.map((s) => s.trim()).filter(Boolean);
+        const upserted = await upsertEpisodeNotebook({
+            episodeYamlPath: manifestPath,
+            entry: {
+                id: notebook.id,
+                url: notebook.url,
+                ...(folder.path ? { path: folder.path } : {}),
+                relation,
+                ...(input.made_by?.trim() ? { made_by: input.made_by.trim() } : {}),
+                ...(sources?.length ? { sources } : {}),
+                ...(folder.files.length ? { files: folder.files } : {}),
+                added: nowOf(context).toISOString(),
+            },
+            dryRun: input.dryRun,
+        }).catch(asNotebookDoorError);
+        const wheel = await projectEpisodeNotebook(context.wheelUrl, { episodeNodeId: nodeEpisode, episodeFolder: identity.name, entry: upserted.entry, title: folder.title, relation: upserted.entry.relation ?? relation }, { dryRun: input.dryRun, fetchImpl: context.fetchImpl });
+        let landing;
+        if (input.land !== false) {
+            landing = await landIdentity(context, identity, { dryRun: input.dryRun }, {
+                subject: `ep${identity.number ?? "?"}: notebook ${folder.title ?? notebook.id.slice(0, 8)}`,
+                body: commitBody(`Notebook held through POST /api/chronicle/episodes/{ref}/notebooks.\n\nNotebook: ${notebook.url}`, []),
+            });
+        }
+        const closing = await closingFor(context, identity.name);
+        return {
+            ok: closingIsProven(closing) && wheel.node.state !== "pending" && wheel.edge.state !== "pending",
+            dryRun: input.dryRun === true,
+            identity,
+            entry: upserted.entry,
+            manifest: { created: upserted.created, filled: upserted.filled, wrote: upserted.wrote },
+            wheel,
+            ...(relationNote ? { relationNote } : {}),
+            landing,
+            closing: closing.closing,
+            drift: closing.drift,
+            owedActions: closing.owedActions,
+        };
+    });
+}
+/** The notebooks an episode holds, as its manifest records them. */
+export async function listEpisodeNotebooks(context, ref) {
+    const identity = await resolveDoorEpisode(context, ref);
+    let manifest = null;
+    try {
+        manifest = parse(await readFile(join(identity.dir, "episode.yaml"), "utf8"));
+    }
+    catch {
+        manifest = null;
+    }
+    return { identity, notebooks: readEpisodeNotebooks(manifest) };
+}
+/**
+ * Hold a prototype in an episode: the manifest entry (published address and
+ * what the episode knows), the `prototype:<slug>` node with the editing
+ * address in its metadata only, the episode→prototype edge, and the landing.
+ */
+export async function attachEpisodePrototype(context, ref, input) {
+    let slug;
+    let url;
+    let editor;
+    try {
+        slug = requirePrototypeSlug(input.prototype);
+        url = requirePrototypeUrl(input.url);
+        editor = optionalEditorUrl(input.editor);
+        assertDistinctPrototypeAddresses(url, editor);
+    }
+    catch (error) {
+        asPrototypeDoorError(error);
+    }
+    const asked = parsePrototypeRelation(input.relation);
+    const identity = await resolveDoorEpisode(context, ref);
+    if (!hasEpisodeManifest(identity.dir)) {
+        throw new EpisodeServiceError("manifest_missing", missingManifestRemedy(identity.dir));
+    }
+    const gitRoot = await gitRootOf(context);
+    return withChronicleLock(gitRoot, async () => {
+        const manifestPath = join(identity.dir, "episode.yaml");
+        const nodeEpisode = episodeNodeId(identity.path);
+        const nodeId = prototypeNodeId(slug);
+        let previous;
+        try {
+            previous = readEpisodePrototypes(parse(await readFile(manifestPath, "utf8"))).find((entry) => entry.id === slug);
+        }
+        catch {
+            previous = undefined;
+        }
+        const onWheel = await existingPrototypeRelation(context.wheelUrl, nodeEpisode, nodeId, { fetchImpl: context.fetchImpl });
+        const relation = onWheel ?? previous?.relation ?? asked ?? DEFAULT_PROTOTYPE_RELATION;
+        const relationNote = asked && asked !== relation
+            ? `asked for '${asked}', kept '${relation}': ${onWheel ? "the wheel already holds that edge" : "the episode already recorded that relation"}`
+            : undefined;
+        const text = (value) => (value?.trim() ? value.trim() : undefined);
+        const reads = input.reads?.map((r) => r.trim()).filter(Boolean);
+        const upserted = await upsertEpisodePrototype({
+            episodeYamlPath: manifestPath,
+            entry: {
+                id: slug,
+                ...(text(input.title) ? { title: text(input.title) } : {}),
+                url,
+                ...(text(input.made_with) ? { made_with: text(input.made_with) } : {}),
+                ...(text(input.source) ? { source: text(input.source) } : {}),
+                ...(text(input.commit) ? { commit: text(input.commit) } : {}),
+                ...(text(input.issue) ? { issue: text(input.issue) } : {}),
+                relation,
+                ...(reads?.length ? { reads } : {}),
+                added: nowOf(context).toISOString(),
+            },
+            dryRun: input.dryRun,
+        }).catch(asPrototypeDoorError);
+        const wheel = await projectEpisodePrototype(context.wheelUrl, { episodeNodeId: nodeEpisode, episodeFolder: identity.name, entry: upserted.entry, editor, relation: upserted.entry.relation ?? relation }, { dryRun: input.dryRun, fetchImpl: context.fetchImpl });
+        let landing;
+        if (input.land !== false) {
+            landing = await landIdentity(context, identity, { dryRun: input.dryRun }, {
+                subject: `ep${identity.number ?? "?"}: prototype ${upserted.entry.title ?? slug}`,
+                body: commitBody(`Prototype held through POST /api/chronicle/episodes/{ref}/prototypes.\n\nPrototype: miadi-prototype:${slug} (${url})`, upserted.entry.issue ? [upserted.entry.issue] : []),
+            });
+        }
+        const closing = await closingFor(context, identity.name);
+        return {
+            ok: closingIsProven(closing) && wheel.node.state !== "pending" && wheel.edge.state !== "pending",
+            dryRun: input.dryRun === true,
+            identity,
+            entry: upserted.entry,
+            manifest: { created: upserted.created, filled: upserted.filled, wrote: upserted.wrote },
+            wheel,
+            ...(relationNote ? { relationNote } : {}),
+            landing,
+            closing: closing.closing,
+            drift: closing.drift,
+            owedActions: closing.owedActions,
+        };
+    });
+}
+/**
+ * The prototypes an episode holds. With `includeEditor`, each one's editing
+ * address is read from its wheel node; the caller has checked the viewer
+ * before asking, because that address is for people who may edit the episode.
+ */
+export async function listEpisodePrototypes(context, ref, options = {}) {
+    const identity = await resolveDoorEpisode(context, ref);
+    let manifest = null;
+    try {
+        manifest = parse(await readFile(join(identity.dir, "episode.yaml"), "utf8"));
+    }
+    catch {
+        manifest = null;
+    }
+    const held = readEpisodePrototypes(manifest);
+    if (!options.includeEditor)
+        return { identity, prototypes: held };
+    const prototypes = [];
+    for (const entry of held) {
+        const editor = await prototypeEditorUrl(context.wheelUrl, entry.id, { fetchImpl: context.fetchImpl });
+        prototypes.push(editor ? { ...entry, editor } : entry);
+    }
+    return { identity, prototypes };
+}
+function asPdeDoorError(error) {
+    if (error instanceof PdeError) {
+        throw new EpisodeServiceError(error.code === "pde_manifest_conflict" ? "invalid_field" : "invalid_pde", error.message);
+    }
+    throw error;
+}
+const KEBAB = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const REPO_NAME = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+/**
+ * Hold a PDE in an episode under `pdes:`. A PDE inside the episode's own
+ * `.pde/` is held without this; declaring it adds what the folder does not say
+ * (a title, an issue, the relation). A PDE kept in a repository needs its repo
+ * and its path in that repository. No wheel node is written yet.
+ */
+export async function attachEpisodePde(context, ref, input) {
+    const text = (value) => (value?.trim() ? value.trim() : undefined);
+    let uuid;
+    try {
+        uuid = requirePdeUuid(input.pde);
+        if (text(input.repo) && !REPO_NAME.test(text(input.repo)))
+            throw new PdeError("invalid_pde", `repo '${input.repo}' must be owner/repo`);
+        if (text(input.repo) && !text(input.path))
+            throw new PdeError("invalid_pde", "a PDE kept in a repository needs its path in that repository");
+        if (text(input.path) && !isRelativePdePath(text(input.path)))
+            throw new PdeError("invalid_pde", `path '${input.path}' must be relative to its repository or to the episode folder`);
+        if (text(input.relation) && !KEBAB.test(text(input.relation)))
+            throw new PdeError("invalid_pde", `relation '${input.relation}' must be a kebab-case phrase completing "Episode <relation> PDE"`);
+    }
+    catch (error) {
+        asPdeDoorError(error);
+    }
+    const identity = await resolveDoorEpisode(context, ref);
+    if (!hasEpisodeManifest(identity.dir)) {
+        throw new EpisodeServiceError("manifest_missing", missingManifestRemedy(identity.dir));
+    }
+    const gitRoot = await gitRootOf(context);
+    return withChronicleLock(gitRoot, async () => {
+        const manifestPath = join(identity.dir, "episode.yaml");
+        const upserted = await upsertEpisodePde({
+            episodeYamlPath: manifestPath,
+            entry: {
+                uuid,
+                ...(text(input.title) ? { title: text(input.title) } : {}),
+                ...(text(input.repo) ? { repo: text(input.repo) } : {}),
+                ...(text(input.path) ? { path: text(input.path).replace(/^(\.\/)+/, "").replace(/\/+$/, "") } : {}),
+                ...(text(input.commit) ? { commit: text(input.commit) } : {}),
+                ...(text(input.engine) ? { engine: text(input.engine) } : {}),
+                ...(text(input.model) ? { model: text(input.model) } : {}),
+                ...(text(input.session) ? { session: text(input.session) } : {}),
+                ...(text(input.issue) ? { issue: text(input.issue) } : {}),
+                relation: text(input.relation) ?? DEFAULT_PDE_RELATION,
+                added: nowOf(context).toISOString(),
+            },
+            dryRun: input.dryRun,
+        }).catch(asPdeDoorError);
+        let landing;
+        if (input.land !== false) {
+            landing = await landIdentity(context, identity, { dryRun: input.dryRun }, {
+                subject: `ep${identity.number ?? "?"}: decomposition ${upserted.entry.title ?? uuid.slice(0, 8)}`,
+                body: commitBody(`Decomposition held through POST /api/chronicle/episodes/{ref}/pdes.\n\nPDE: miadi-pde:${uuid}${upserted.entry.repo ? ` (${upserted.entry.repo}:${upserted.entry.path})` : ""}`, upserted.entry.issue ? [upserted.entry.issue] : []),
+            });
+        }
+        const closing = await closingFor(context, identity.name);
+        return {
+            ok: closingIsProven(closing),
+            dryRun: input.dryRun === true,
+            identity,
+            entry: upserted.entry,
+            manifest: { created: upserted.created, filled: upserted.filled, wrote: upserted.wrote },
+            landing,
+            closing: closing.closing,
+            drift: closing.drift,
+            owedActions: closing.owedActions,
+        };
+    });
+}
+/**
+ * The PDEs an episode holds: every one in its own `.pde/` (parents before
+ * children, oldest first), each enriched by what the manifest declares for the
+ * same uuid, then the ones only the manifest names.
+ */
+export async function listEpisodePdes(context, ref) {
+    const identity = await resolveDoorEpisode(context, ref);
+    let manifest = null;
+    try {
+        manifest = parse(await readFile(join(identity.dir, "episode.yaml"), "utf8"));
+    }
+    catch {
+        manifest = null;
+    }
+    const declared = new Map(readEpisodePdes(manifest).map((entry) => [entry.uuid, entry]));
+    const pdes = [];
+    for (const found of await readEpisodePdeFolder(identity.dir)) {
+        const listed = { ...found, held: "folder" };
+        const named = declared.get(found.uuid);
+        if (named) {
+            declared.delete(found.uuid);
+            // The folder says what was made; the manifest adds what a person said about it, and its title wins.
+            const into = listed;
+            for (const key of PDE_ENTRY_KEYS)
+                if (named[key] !== undefined && (key === "title" || into[key] === undefined))
+                    into[key] = named[key];
+            listed.declared = named.declared;
+        }
+        pdes.push(listed);
+    }
+    for (const named of declared.values()) {
+        const { declared: where, ...entry } = named;
+        pdes.push({ ...entry, held: "declared", declared: where });
+    }
+    return { identity, pdes };
+}
+/**
+ * Hold a tracing resource in an episode: the manifest entry (domain, resource,
+ * id, name, version, label, session, relation, backstage), the
+ * `tracing:<domain>/<resource>/<id>` node with the provider and, when given,
+ * the provider's page in its metadata, the episode→resource edge, the landing.
+ */
+export async function attachEpisodeTracing(context, ref, input) {
+    let target;
+    let uiUrl;
+    try {
+        target = requireTracingRef(input);
+        uiUrl = optionalUiUrl(input.ui_url);
+    }
+    catch (error) {
+        asTracingDoorError(error);
+    }
+    const asked = parseTracingRelation(input.relation);
+    const identity = await resolveDoorEpisode(context, ref);
+    if (!hasEpisodeManifest(identity.dir)) {
+        throw new EpisodeServiceError("manifest_missing", missingManifestRemedy(identity.dir));
+    }
+    const gitRoot = await gitRootOf(context);
+    return withChronicleLock(gitRoot, async () => {
+        const manifestPath = join(identity.dir, "episode.yaml");
+        const nodeEpisode = episodeNodeId(identity.path);
+        const nodeId = tracingNodeId(target.domain, target.resource, target.id);
+        const key = tracingKey(target.domain, target.resource, target.id);
+        let previous;
+        try {
+            previous = readEpisodeTracing(parse(await readFile(manifestPath, "utf8"))).find((entry) => tracingKey(entry.domain, entry.resource, entry.id) === key);
+        }
+        catch {
+            previous = undefined;
+        }
+        const onWheel = await existingTracingRelation(context.wheelUrl, nodeEpisode, nodeId, { fetchImpl: context.fetchImpl });
+        const relation = onWheel ?? previous?.relation ?? asked ?? defaultTracingRelation(target.resource);
+        const relationNote = asked && asked !== relation
+            ? `asked for '${asked}', kept '${relation}': ${onWheel ? "the wheel already holds that edge" : "the episode already recorded that relation"}`
+            : undefined;
+        const text = (value) => (value?.trim() ? value.trim() : undefined);
+        const backstage = input.backstage?.map((b) => b.trim()).filter(Boolean);
+        const upserted = await upsertEpisodeTracing({
+            episodeYamlPath: manifestPath,
+            entry: {
+                domain: target.domain,
+                resource: target.resource,
+                id: target.id,
+                ...(text(input.name) && text(input.name) !== target.id ? { name: text(input.name) } : {}),
+                ...(target.version !== undefined ? { version: target.version } : {}),
+                ...(text(input.label) ? { label: text(input.label) } : {}),
+                ...(text(input.session) ? { session: text(input.session) } : {}),
+                relation,
+                ...(backstage?.length ? { backstage } : {}),
+                added: nowOf(context).toISOString(),
+            },
+            dryRun: input.dryRun,
+        }).catch(asTracingDoorError);
+        const wheel = await projectEpisodeTracing(context.wheelUrl, { episodeNodeId: nodeEpisode, episodeFolder: identity.name, entry: upserted.entry, provider: tracingProviderName(), uiUrl, relation: upserted.entry.relation ?? relation }, { dryRun: input.dryRun, fetchImpl: context.fetchImpl });
+        let landing;
+        if (input.land !== false) {
+            landing = await landIdentity(context, identity, { dryRun: input.dryRun }, {
+                subject: `ep${identity.number ?? "?"}: ${target.resource} ${upserted.entry.name ?? target.id} (${target.domain})`,
+                body: commitBody(`Tracing resource held through POST /api/chronicle/episodes/{ref}/tracing.\n\nResource: miadi-tracing:${key}`, []),
+            });
+        }
+        const closing = await closingFor(context, identity.name);
+        return {
+            ok: closingIsProven(closing) && wheel.node.state !== "pending" && wheel.edge.state !== "pending",
+            dryRun: input.dryRun === true,
+            identity,
+            entry: upserted.entry,
+            manifest: { created: upserted.created, filled: upserted.filled, wrote: upserted.wrote },
+            wheel,
+            ...(relationNote ? { relationNote } : {}),
+            landing,
+            closing: closing.closing,
+            drift: closing.drift,
+            owedActions: closing.owedActions,
+        };
+    });
+}
+/** The tracing resources an episode holds. With `includeLinks`, each one's provider page is read from its node. */
+export async function listEpisodeTracing(context, ref, options = {}) {
+    const identity = await resolveDoorEpisode(context, ref);
+    let manifest = null;
+    try {
+        manifest = parse(await readFile(join(identity.dir, "episode.yaml"), "utf8"));
+    }
+    catch {
+        manifest = null;
+    }
+    const held = readEpisodeTracing(manifest);
+    const provider = tracingProviderName();
+    if (!options.includeLinks)
+        return { identity, tracing: held, provider };
+    const tracing = [];
+    for (const entry of held) {
+        const ui = await tracingUiUrl(context.wheelUrl, entry, { fetchImpl: context.fetchImpl });
+        tracing.push(ui ? { ...entry, ui_url: ui } : entry);
+    }
+    return { identity, tracing, provider };
+}
+/** Hold a RISE specification in an episode: the manifest entry, the `rise:` node, the edge, the landing. */
+export async function attachEpisodeRispec(context, ref, input) {
+    let spec;
+    try {
+        spec = requireRiseRef(input.spec);
+    }
+    catch (error) {
+        asRispecDoorError(error);
+    }
+    const asked = parseRispecRelation(input.relation);
+    const identity = await resolveDoorEpisode(context, ref);
+    if (!hasEpisodeManifest(identity.dir)) {
+        throw new EpisodeServiceError("manifest_missing", missingManifestRemedy(identity.dir));
+    }
+    const gitRoot = await gitRootOf(context);
+    return withChronicleLock(gitRoot, async () => {
+        const manifestPath = join(identity.dir, "episode.yaml");
+        const nodeEpisode = episodeNodeId(identity.path);
+        const nodeId = riseNodeId(spec);
+        const address = riseReference(spec.owner, spec.repo, spec.path);
+        let previous;
+        try {
+            previous = readEpisodeRispecs(parse(await readFile(manifestPath, "utf8"))).find((entry) => entry.ref === address);
+        }
+        catch {
+            previous = undefined;
+        }
+        const onWheel = await existingRispecRelation(context.wheelUrl, nodeEpisode, nodeId, { fetchImpl: context.fetchImpl });
+        const relation = onWheel ?? previous?.relation ?? asked ?? DEFAULT_RISPEC_RELATION;
+        const relationNote = asked && asked !== relation
+            ? `asked for '${asked}', kept '${relation}': ${onWheel ? "the wheel already holds that edge" : "the episode already recorded that relation"}`
+            : undefined;
+        const text = (value) => (value?.trim() ? value.trim() : undefined);
+        const upserted = await upsertEpisodeRispec({
+            episodeYamlPath: manifestPath,
+            entry: {
+                ref: address,
+                ...(text(input.title) ? { title: text(input.title) } : {}),
+                ...(text(input.commit) ?? spec.commit ? { commit: text(input.commit) ?? spec.commit } : {}),
+                relation,
+                ...(text(input.derived_from) ? { derived_from: text(input.derived_from) } : {}),
+                ...(text(input.system) ? { system: text(input.system) } : {}),
+                added: nowOf(context).toISOString(),
+            },
+            dryRun: input.dryRun,
+        }).catch(asRispecDoorError);
+        const wheel = await projectEpisodeRispec(context.wheelUrl, { episodeNodeId: nodeEpisode, episodeFolder: identity.name, ref: spec, entry: upserted.entry, relation: upserted.entry.relation ?? relation }, { dryRun: input.dryRun, fetchImpl: context.fetchImpl });
+        let landing;
+        if (input.land !== false) {
+            landing = await landIdentity(context, identity, { dryRun: input.dryRun }, {
+                subject: `ep${identity.number ?? "?"}: spec ${upserted.entry.title ?? spec.path}`,
+                body: commitBody(`Specification held through POST /api/chronicle/episodes/{ref}/rispecs.\n\nSpec: ${address}${upserted.entry.commit ? `@${upserted.entry.commit}` : ""}`, []),
+            });
+        }
+        const closing = await closingFor(context, identity.name);
+        return {
+            ok: closingIsProven(closing) && wheel.node.state !== "pending" && wheel.edge.state !== "pending",
+            dryRun: input.dryRun === true,
+            identity,
+            entry: upserted.entry,
+            manifest: { created: upserted.created, filled: upserted.filled, wrote: upserted.wrote },
+            wheel,
+            ...(relationNote ? { relationNote } : {}),
+            landing,
+            closing: closing.closing,
+            drift: closing.drift,
+            owedActions: closing.owedActions,
+        };
+    });
+}
+/** The specs an episode holds, as its manifest records them. */
+export async function listEpisodeRispecs(context, ref) {
+    const identity = await resolveDoorEpisode(context, ref);
+    let manifest = null;
+    try {
+        manifest = parse(await readFile(join(identity.dir, "episode.yaml"), "utf8"));
+    }
+    catch {
+        manifest = null;
+    }
+    return { identity, rispecs: readEpisodeRispecs(manifest) };
+}
 /** The screenwalks an episode holds (`captures/screenwalk-<id>/`), for the door's GET. */
 export async function listEpisodeScreenwalks(context, ref) {
     const identity = await resolveDoorEpisode(context, ref);