// CV22.DS7.US7 plateau 5 — the `explore` front-door route. // // Dispatch only: every behavior it reaches was ported and graded in plateaus // 1-4. What this module owns is the argv shape, the exit codes, the refusals, // and the one call into the projection seam. // // `explore` is the first family with a NESTED subparser, so the allowlist in // `routing.ts` is two levels deep: `explore ` and `explore story // `. A single-level allowlist would claim `explore story ` // and answer an argv shape this route has never implemented — the // `conversations append` defect (RS009/CR055), which exited 0 and discarded the // caller's data. // // `story promote` arrived here at US8 plateau 7, having waited on Python by name // since US7: `cmd_story_promote` ends by calling Builder `load`, which US8 owns. // Its tail is therefore a real session start — providers, close tail, clone-role // guard — wired by `buildLoadRuntime.ts`, which plateau 8's `build` route reuses // so the two cannot disagree about which transport answered. import { runBuildLoad } from "#builder/load.ts"; import type { WritableDatabase } from "#db/database.ts"; import { type HandoffConversationSource, type HandoffSourceMessage, writeBuilderHandoffArtifacts, } from "#explorer/handoff.ts"; import { renderAttractorsEmerging, renderBuilderHandoffProposed, renderExperimentProposal, renderExploratoryStoryOpened, renderExploratoryStoryResumed, renderExplorerStoryArchived, renderExplorerStoryList, renderMissingExploratoryStory, renderNarrativeFieldSnapshot, renderNoBuilderHandoff, renderStoryThickened, } from "#explorer/render.ts"; import { archiveExplorerStory, clearExplorerStory, type ExplorerStory, ExplorerStoryError, getExplorerStory, listExplorerStories, markExplorerStoryPromoted, renderExplorerStoryContext, type Settable, type StoryClock, type StoryMutation, setExplorerAttractors, setExplorerBuilderHandoff, setExplorerExperimentProposal, setExplorerSourceConversations, UNSET, updateExplorerStory, } from "#explorer/story.ts"; import { renderExplorerModeTransition } from "#explorer/transition.ts"; import { getIdentityContent } from "#identity/identityRead.ts"; import { getProjectPath } from "#journey/journeyStatus.ts"; import { loadMirrorContext } from "#mirror/context.ts"; import { persistStickyDefaults } from "#mirror/orchestration.ts"; import { environmentSessionId, resolveRuntimeSessionId } from "#mirror/runtimeSession.ts"; import { activateOperatingMode, deactivateOperatingMode } from "#mode/operatingMode.ts"; import { newId, nowIso } from "#util/pyGenerators.ts"; import { optionValue, stripOptionWithValue } from "./args.ts"; import type { BuildLoadRuntime } from "./buildLoadRuntime.ts"; /** Python's argparse subcommands for `explore`, by name. */ export const EXPLORE_SUBCOMMANDS = ["load", "deactivate", "story"] as const; /** Python's argparse actions under `explore story`, by name. */ export const EXPLORE_STORY_ACTIONS = [ "show", "list", "archive", "update", "clear", "open", "thicken", "snapshot", "attractors", "experiment", "handoff", "promote", ] as const; const OPTIONS_WITH_VALUES = [ "--mirror-home", "--db-path", "--session-id", "--story", "--summary", "--last-card", "--changed", "--attractor", "--description", "--status", "--title", "--editorial-synthesis", "--source-conversation", ]; const FLAGS = ["--include-full-conversation"]; const EXPLORER_GUIDANCE = `=== Explorer Mode guidance === Explorer Mode is active and ready for durable exploration, story thickening, attractors, experiments, and Builder handoff. Explorer preserves uncertainty. Builder executes commitment. While Explorer Mode is active: - Treat new substantive material as part of the current Exploratory Story unless the user asks for a clear operational action. - Preserve tensions, hypotheses, corrections, and emerging story shape. - Update the in-session story when new material changes the accumulated story. - Render Story Thickened when new material changes the accumulated story. - Do not promote to Builder or Delivery without explicit user confirmation. `; const EXPLORER_DEACTIVATED_SURFACE = `Mirror ╭────────────────────────────────────────────────────────╮ │ △ EXPLORER MODE DEACTIVATED │ │ │ │ current lens │ │ ◌ Mirror Mode │ │ │ │ context │ │ Journey context remains available when it is sticky. │ │ │ │ boundary │ │ Explorer lens ended. Uncertainty was not promoted. │ ╰────────────────────────────────────────────────────────╯ `; function positionals(args: readonly string[]): string[] { const withoutFlags = args.filter((arg) => !FLAGS.includes(arg)); return OPTIONS_WITH_VALUES.reduce( (remaining, option) => stripOptionWithValue(remaining, option), withoutFlags, ); } /** Python's `_required_surface` marker protocol, byte for byte. */ function requiredSurface(surfaceId: string, rendered: string): string { return `[[MIRROR_REQUIRED_SURFACE_BEGIN:${surfaceId}]]\n${rendered}\n[[MIRROR_REQUIRED_SURFACE_END:${surfaceId}]]`; } function write(text: string): number { process.stdout.write(`${text}\n`); return 0; } function fail(message: string): number { process.stderr.write(`Error: ${message}\n`); return 1; } /** argparse's own exit for an unknown subcommand or a missing required argument. */ function usageError(message: string): number { process.stderr.write(`${message}\n`); return 2; } export interface ExploreRouteDeps { clock: StoryClock; readMessages: (db: WritableDatabase, conversationId: string) => HandoffSourceMessage[]; /** * `story promote`'s Builder tail. * * Injected rather than built here so this route stays free of the provider * seam, and so the promote tests can run a session start without one. */ buildLoadRuntime?: () => Promise; } export function defaultExploreRouteDeps(): ExploreRouteDeps { return { clock: { now: nowIso, uuid: newId }, readMessages: (db, conversationId) => db .prepare("SELECT role, content FROM messages WHERE conversation_id = ? ORDER BY rowid") .all(conversationId) as unknown as HandoffSourceMessage[], }; } /** * The story write, unwrapped. * * Until CV22.DS10.TS1 this asked Python to publish `.mirror/projections` when a * mutation changed the projected fields. The subsystem retired with the Python * core, so a mutation is now just a mutation. */ function afterMutation(mutation: StoryMutation): ExplorerStory { return mutation.story; } export async function runExploreRoute( db: WritableDatabase, argv: readonly string[], deps: ExploreRouteDeps, ): Promise { const rawArgs = argv.slice(1); const args = positionals(rawArgs); const sub = args[0]; const option = (name: string) => optionValue(rawArgs, name); try { switch (sub) { case "load": { const slug = args[1]; if (!slug) return usageError("explore load requires a journey slug"); // Awaited inside the try: returning the promise would carry a // rejection past the catch that turns ExplorerStoryError into exit 1. return await runLoad(db, slug, option("--session-id")); } case "deactivate": { deactivateOperatingMode(db, resolveRuntimeSessionId(db, option("--session-id")), nowIso()); return write(EXPLORER_DEACTIVATED_SURFACE); } // Awaited for the same reason `load` is: `story promote` runs a Builder // session start, and an unawaited rejection would sail past the catch // below that turns ExplorerStoryError into exit 1. case "story": return await runStory(db, args, option, rawArgs, deps); default: return usageError(`explore: unknown subcommand ${sub ?? ""}`); } } catch (error) { if (error instanceof ExplorerStoryError) return fail(error.message); throw error; } } // No `deps`: `load` activates the mode and renders, but never mutates the // story, so it cannot change the projection and never reaches the seam. async function runLoad( db: WritableDatabase, slug: string, sessionId: string | null, ): Promise { const journeyContent = getIdentityContent(db, "journey", slug); if (!journeyContent) { process.stderr.write(`Error: journey '${slug}' not found.\n`); return 1; } const resolved = resolveRuntimeSessionId(db, sessionId); const now = nowIso(); activateOperatingMode(db, { mode: "Explorer Mode", journey: slug, sessionId: resolved }, now); // Python's `cmd_load` reaches into `memory.skills.mirror`'s PRIVATE sticky // writer; the port calls the public one and does not reproduce the violation. persistStickyDefaults(db, null, slug, now); // The activation banner goes to stderr, as Python's does: stdout carries the // surfaces a runtime must render verbatim. process.stderr.write(`\u001b[38;5;183m△ Explorer Mode active — journey: ${slug}\u001b[0m\n`); write(renderExplorerModeTransition(slug)); write(await loadMirrorContext(db, { journey: slug })); const story = getExplorerStory(db, slug); if (story) { write( `\n${requiredSurface("exploratory_story_resumed", renderExploratoryStoryResumed(story))}`, ); write(`\n${renderExplorerStoryContext(story)}`); } write(`\n${EXPLORER_GUIDANCE}`); return 0; } async function runStory( db: WritableDatabase, args: readonly string[], option: (name: string) => string | null, rawArgs: readonly string[], deps: ExploreRouteDeps, ): Promise { const action = args[1]; const slug = args[2]; if (!action) return usageError("explore story requires an action"); if (!slug) return usageError(`explore story ${action} requires a journey slug`); // A settable scalar is present-or-absent, never nullish: `--story` given with // an empty value CLEARS, while omitting it keeps. `optionValue` returns null // for both, so presence is read from argv. const settable = (name: string): Settable => rawArgs.includes(name) ? (option(name) ?? "") : UNSET; switch (action) { case "show": { const story = getExplorerStory(db, slug); if (!story) return write(`No Exploratory Story for journey: ${slug}`); return write(renderExplorerStoryContext(story)); } case "list": return write( requiredSurface( "exploratory_stories", renderExplorerStoryList(slug, listExplorerStories(db, slug)), ), ); case "archive": { const { story } = archiveExplorerStory(db, slug, deps.clock); return write( requiredSurface("exploratory_story_archived", renderExplorerStoryArchived(story, slug)), ); } case "clear": clearExplorerStory(db, slug, deps.clock); return write(`Exploratory Story cleared for journey: ${slug}`); case "update": { const story = afterMutation(updateStory(db, slug, settable, deps)); return write(renderExplorerStoryContext(story)); } case "open": { const story = afterMutation(updateStory(db, slug, settable, deps)); return write( requiredSurface("exploratory_story_opened", renderExploratoryStoryOpened(story)), ); } case "thicken": { const story = afterMutation(updateStory(db, slug, settable, deps)); return write( requiredSurface("story_thickened", renderStoryThickened(story, option("--changed"))), ); } case "snapshot": { const story = getExplorerStory(db, slug); if (!story) { return write(requiredSurface("no_exploratory_story", renderMissingExploratoryStory(slug))); } return write( requiredSurface("narrative_field_snapshot", renderNarrativeFieldSnapshot(story)), ); } case "attractors": { const label = option("--attractor"); if (label === null) { return usageError( "explore story attractors: the following arguments are required: --attractor", ); } const story = afterMutation( setExplorerAttractors(db, slug, deps.clock, [ { label, description: option("--description"), status: option("--status") ?? "proposed", }, ]), ); return write(requiredSurface("attractors_emerging", renderAttractorsEmerging(story))); } case "experiment": { const title = option("--title"); if (title === null) { return usageError( "explore story experiment: the following arguments are required: --title", ); } const story = afterMutation( setExplorerExperimentProposal(db, slug, deps.clock, { title, description: option("--description"), status: option("--status") ?? "proposed", }), ); return write(requiredSurface("experiment_proposal", renderExperimentProposal(story))); } case "handoff": return runHandoff(db, slug, option, rawArgs, deps); case "promote": return runPromote(db, slug, deps); default: return usageError(`explore story: unknown action ${action}`); } } /** * Python `cmd_story_promote`: confirm the handoff, mark the story promoted, and * enter Builder. * * The ORDER is the behavior, and one detail decides whether a half-run is * recoverable: the Builder tail is resolved BEFORE either write. Python's * promote is not idempotent — once the story is promoted it is no longer * active, so a second run finds no story and renders `no_builder_handoff` — so * a port that mutated first and only then discovered it could not finish would * leave the journey in a state neither engine can complete. */ async function runPromote( db: WritableDatabase, slug: string, deps: ExploreRouteDeps, ): Promise { // The read comes first, and the refusal needs no provider at all: Python's // `cmd_story_promote` returns before `cmd_load` when there is no handoff. const story = getExplorerStory(db, slug); if (!story?.builderHandoff) { return write(requiredSurface("no_builder_handoff", renderNoBuilderHandoff(slug))); } const runtime = await deps.buildLoadRuntime?.(); if (!runtime) { // Unreachable through the front door, which always wires the runtime. Loud // rather than silent, because a promote with no Builder load behind it // would strand a half-promoted story. throw new Error("explore story promote reached its route with no Builder load runtime wired"); } // Field by field, as Python rebuilds it: only `readiness` changes, and every // artifact path the handoff recorded survives the confirmation. const handoff = story.builderHandoff; afterMutation( setExplorerBuilderHandoff(db, slug, deps.clock, { title: handoff.title, summary: handoff.summary, readiness: "confirmed", artifactDir: handoff.artifactDir, indexPath: handoff.indexPath, exploratoryStoryPath: handoff.exploratoryStoryPath, handoffInfoPath: handoff.handoffInfoPath, productDesignProposalPath: handoff.productDesignProposalPath, fullConversationPath: handoff.fullConversationPath, }), ); markExplorerStoryPromoted(db, slug, deps.clock); // Python calls `cmd_load(slug)` with no session id, so the session comes from // the environment or the active runtime row — never from `explore`'s own // `--session-id`, which its promote parser does not even accept. const result = await runBuildLoad( db, { slug, environmentSessionId: environmentSessionId(process.env) }, runtime.deps, ); process.stderr.write(result.stderr); process.stdout.write(result.stdout); return result.exitCode; } function updateStory( db: WritableDatabase, slug: string, settable: (name: string) => Settable, deps: ExploreRouteDeps, ): StoryMutation { const fields: { currentExploratoryStory?: Settable; narrativeFieldSummary?: Settable; lastStoryCard?: Settable; } = {}; const story = settable("--story"); const summary = settable("--summary"); const lastCard = settable("--last-card"); if (story !== UNSET) fields.currentExploratoryStory = story; if (summary !== UNSET) fields.narrativeFieldSummary = summary; if (lastCard !== UNSET) fields.lastStoryCard = lastCard; return updateExplorerStory(db, slug, deps.clock, fields); } function runHandoff( db: WritableDatabase, slug: string, option: (name: string) => string | null, rawArgs: readonly string[], deps: ExploreRouteDeps, ): number { const title = option("--title"); if (title === null) { return usageError("explore story handoff: the following arguments are required: --title"); } const story = getExplorerStory(db, slug); if (!story) { return write(requiredSurface("no_exploratory_story", renderMissingExploratoryStory(slug))); } const includeFullConversation = rawArgs.includes("--include-full-conversation"); const sources = loadHandoffSources( db, collectRepeated(rawArgs, "--source-conversation"), includeFullConversation, deps, ); let current = story; if (sources.length > 0) { current = afterMutation( setExplorerSourceConversations( db, slug, deps.clock, sources.map((source) => ({ conversationId: source.conversationId, title: source.title, role: source.role, })), ), ); } const projectPath = getProjectPath(db, slug); const handoff = projectPath ? writeBuilderHandoffArtifacts(projectPath, current, { title, summary: option("--summary"), editorialSynthesis: option("--editorial-synthesis"), sourceConversations: sources, includeFullConversation, }) : { title, summary: option("--summary"), readiness: "proposed" as const, artifactDir: null, indexPath: null, exploratoryStoryPath: null, handoffInfoPath: null, productDesignProposalPath: null, fullConversationPath: null, }; const updated = afterMutation(setExplorerBuilderHandoff(db, slug, deps.clock, handoff)); return write(requiredSurface("builder_handoff_proposed", renderBuilderHandoffProposed(updated))); } /** `action="append"`: every occurrence, in order. */ function collectRepeated(args: readonly string[], name: string): string[] { const values: string[] = []; for (let index = 0; index < args.length; index += 1) { if (args[index] === name && index + 1 < args.length) values.push(args[index + 1] as string); } return values; } /** Python `_parse_source_conversation_arg`: `id` or `id:role`. */ function parseSourceConversationArg(value: string): { id: string; role: string } { const separator = value.indexOf(":"); if (separator === -1) return { id: value.trim(), role: "source evidence" }; return { id: value.slice(0, separator).trim(), role: value.slice(separator + 1).trim() || "source evidence", }; } /** Python `_load_handoff_sources`: id, then id-prefix; an unknown id is skipped. */ function loadHandoffSources( db: WritableDatabase, raw: readonly string[], includeMessages: boolean, deps: ExploreRouteDeps, ): HandoffConversationSource[] { const sources: HandoffConversationSource[] = []; for (const value of raw) { const { id, role } = parseSourceConversationArg(value); const conversation = (db.prepare("SELECT id, title FROM conversations WHERE id = ?").get(id) as | { id: string; title: string | null } | undefined) ?? (db .prepare("SELECT id, title FROM conversations WHERE id LIKE ? ORDER BY id LIMIT 1") .get(`${id}%`) as { id: string; title: string | null } | undefined); if (!conversation) continue; sources.push({ conversationId: conversation.id, title: conversation.title ?? null, role, messages: includeMessages ? deps.readMessages(db, conversation.id) : [], }); } return sources; }