import { BUILD_LOAD_COMPOSITION, CONSULT_ASK_TRANSPORT, CONSULT_CREDITS_TRANSPORT, CONVERSATION_TAIL_TRANSPORT, type ComposedProviderTransportSpec, CULTIVATION_APPLY_TRANSPORT, CULTIVATION_SCAN_TRANSPORT, DESCRIPTOR_TRANSPORT, JOURNAL_TRANSPORT, mirrorQueryTransportFor, type ProviderTransportSpec, resolveComposedProviderTransport, resolveProviderTransport, SEARCH_TRANSPORT, SOUL_HARVEST_TRANSPORT, WEEK_PLAN_TRANSPORT, } from "#providers/transport.ts"; import { buildUsageSynopsis } from "./buildArgSpecs.ts"; import { COMMAND_SYNOPSES } from "./commandHelp.ts"; import { RUNTIME_SUBCOMMANDS, TS_RUNTIME_READ_SUBCOMMANDS, TS_RUNTIME_UPDATE_SUBCOMMANDS, } from "./runtimeRoute.ts"; import { FRONT_DOOR_COMMANDS, isHelpFlag, isVersionFlag, type UsageRequest } from "./usage.ts"; /** * The engine a routed command answers from. One member since CV22.DS10.TS5: * `"python"` left with the fallback it named, and every site that still * reached for it stopped compiling -- which is how the last of them were found. */ export type FrontDoorEngine = "ts"; /** * A surface CV22.DS10 removed rather than ported. * * Until TS4 a retired name was simply unclaimed: it fell through to Python, * which answered `Unknown command: ` with its usage block. That answer * belongs to the engine TS5 deletes, and it names commands DS10 has already * removed. These entries let the front door say *removed* itself, in one line, * pointing at the cutoff that explains what to do instead. * * `matches` reads argv by NAME. Nothing here is matched by inheritance: a verb * a retired family never had keeps its family's existing answer (the CR055 * lesson `conversations append` paid for). */ export interface RetiredSurface { /** The shape as a user types it, e.g. `journey export-registry`. */ readonly surface: string; /** Heading anchor in `docs/releases/pending-cutoffs.md`. A CONSTANT. */ readonly anchor: string; readonly matches: (argv: readonly string[]) => boolean; } export type RouteDecision = | { command: string | null; engine: FrontDoorEngine; reason: string; } | { command: string | null; engine: "retired"; reason: string; /** The retired shape, from the matched entry -- never from argv. */ surface: string; /** The cutoff anchor, from the matched entry -- never from argv. */ anchor: string; } | { command: string | null; /** * CV22.DS10.TS5 (D2): a name the front door does not answer. Rendered by * `usage.ts` before dispatch, like `retired` -- nothing opened, nothing * read from stdin, nothing spawned. */ engine: "usage"; reason: string; request: UsageRequest; }; /** * A family was named and its subcommand is not one it answers (D2). * * `choices` is the allowlist the family ALREADY routes by, so the usage line a * user sees cannot drift from what the build answers. */ function unknownSubcommand( command: string, choices: Iterable, given: string | undefined, program: string = command, ): RouteDecision { const name = given ?? ""; return { command, engine: "usage", reason: name === "" ? `${program} needs a subcommand` : `unknown ${program} subcommand: ${name}`, request: { scope: "family", program, choices: [...choices], given: name }, }; } /** A top-level name nothing answers, or no command at all (D2). */ function unknownCommand(given: string | null): RouteDecision { return { // Whatever the caller typed is not a command name, so the log records none. command: null, engine: "usage", reason: given === null ? "no command" : `unknown command: ${given}`, request: { scope: "top-level", given }, }; } const TS_READ_COMMANDS = new Set(["detect-persona", "journeys"]); // The Conversation Metadata Lifecycle (ES-001) flags on `conversations`. // CR068 found the whole family unowned: DS7.US1 called it "own slice" and no // slice claimed it. DS7.US11 splits it three ways by what each flag actually // needs, rather than treating them as one block. // // READS -- pure, over the engine DS7.US10 already ported. const TS_LIFECYCLE_READ_FLAGS = [ "--metadata-lifecycle-dry-run", "--metadata-lifecycle-preview-at-message", ]; // WRITES -- both need `apply_metadata_lifecycle`, ~80 lines of unported // decision logic (`closeTail.ts` carries the same refusal), and `demo` calls // `apply`. Refused BY NAME and assigned to DS7.TS4 by Navigator decision // 2026-09-09, rather than silently inheriting a route or being reported as // ported. const TS4_LIFECYCLE_WRITE_FLAGS = ["--metadata-lifecycle-apply", "--metadata-lifecycle-demo"]; // One-shot backfill of pre-ES-001 rows, retired by CV22.DS10.TS4 with a // documented cutoff. Named here ONLY for the retired entries below: those match // before any family, so a family branch naming these flags would be dead code // (TS5 deleted the one that was -- `retiredRouteShadows.ts` keeps it deleted). const DS10_BACKFILL_FLAGS = ["--metadata-backfill-preview", "--metadata-backfill-apply"]; // CV22.DS7.TS4: the extension catalog family, allowlisted by NAME. // // `extensions` and `inspect` are claimed commands with subcommands Python may // grow, and this family has already paid for inheritance once: `conversations` // grew `append` after DS7.US1 claimed the command, and the new subcommand // silently rendered a listing and discarded the caller's messages. So every // verb TS answers is listed here, and anything else stays Python's. export const TS4_EXTENSIONS_VERBS = new Set([ "list", "validate", "sync", "install", "uninstall", "expose-claude", "clean-claude", ]); const TS4_INSPECT_TARGETS = new Set([ "extension", "runtime-catalog", "llm-calls", "embedding-provenance", ]); /** * `ext`'s two levels, exported as the AUDITED denominator rather than as a * filter. * * Level one is every head `cmd_ext` recognises as a verb; level two is the four * built-in verbs that follow an id. Everything else — ``, ` `, * ` ` — is the dynamic leaf, whose subcommand belongs to an * extension Mirror does not own and therefore cannot be enumerated. * * Because the route cannot refuse an unknown head (Python reads it as an id), * these sets are checked against `cli/ext.py` itself by a route test. That is * what keeps the inheritance honest: the day Python grows a verb beside * `list`, the test fails instead of the user silently getting `extension not * installed: .../doctor`. */ export const TS4_EXT_TOP_LEVEL_VERBS = new Set(["list", "--help", "-h", "help"]); export const TS4_EXT_BUILTIN_VERBS = new Set(["bind", "unbind", "bindings", "migrate"]); // CV22.DS7.US8 plateau 8: the 27 Builder leaves ported in plateaus 1–7, plus `show` // (CR067 with CR020), the one leaf written new in TypeScript rather than ported. // Exported so the route tests can prove that the allowlist and its audited // denominator stay the same. The two legacy Workbench groups are deliberately // absent: their twenty leaves retire unported in DS10. export const TS_BUILD_SUBCOMMANDS = new Set([ "load", "inspect-method", "adopt", "prepare-templates", "sync-cursor", "pull-candidates", "pull-item", "prepare-item", "plan-item", "approve-plan", "cancel-plan-preauthorization", "check-implementation", "show", "validate-item", "review-item", "coherence-item", "done-item", "set-flow-unit", "plan-delivery-story", "approve-delivery-story-plan", "cancel-delivery-story-plan-preauthorization", "validate-delivery-story", "review-delivery-story", "coherence-delivery-story", "done-delivery-story", "set-cadence", "release-intent", "continue-lifecycle", ]); export const TS_BUILD_WORKBENCH_ACTIONS = { "refinement-story": new Set([ "create", "overview", "pull", "review", "coherence", "close", "park", ]), "change-request": new Set([ "capture", "attach", "discard", "select", "confirm", "resume", "plan", "mark-implemented", "validate", "done", "park", "reject", "promote", ]), } as const; /** * The surfaces CV22.DS10.TS4 removed, each with the cutoff that explains it. * * A LIST OF PREDICATES, not a map keyed by command: the six shapes are four * different matchers (whole command; command + verb; command + flag; command + * subcommand + verb), and a map would push those differences into ad-hoc string * checks inside `routeMemoryCommand`. * * The surfaces TS1, US1, and TS3 retired are deliberately NOT here. Their * stories are closed, and the post-Python answer for every unclaimed name is * TS5's to shape at once -- adding them now would reopen three done packages * for a cosmetic change. (Naming them here would also trip their own * retired-surface rows, which is the guard working.) */ export const RETIRED_SURFACES: readonly RetiredSurface[] = [ { surface: "migrate-legacy", anchor: "legacy-migration", matches: (argv) => argv[0] === "migrate-legacy", }, { surface: "journey export-registry", anchor: "journey-admin-verbs", matches: (argv) => argv[0] === "journey" && argv[1] === "export-registry", }, { surface: "journey mutate", anchor: "journey-admin-verbs", matches: (argv) => argv[0] === "journey" && argv[1] === "mutate", }, { surface: "conversations --metadata-backfill-preview", anchor: "conversation-metadata-backfill", matches: (argv) => argv[0] === "conversations" && argv.includes(DS10_BACKFILL_FLAGS[0]), }, { surface: "conversations --metadata-backfill-apply", anchor: "conversation-metadata-backfill", matches: (argv) => argv[0] === "conversations" && argv.includes(DS10_BACKFILL_FLAGS[1]), }, // CV22.DS10.US2 (D1): the release chain leaves the PRODUCT surface. These // two were offered to every installed user and need a git checkout, a clean // tree, tags, and push rights -- none of which an installed user has. They // are maintainer tooling now, reached through `npm run release:*`, so the // old names answer with their cutoff rather than being ported. { surface: "runtime release-doctor", anchor: "release-tooling-leaves-the-product-command-surface", matches: (argv) => argv[0] === "runtime" && argv[1] === "release-doctor", }, { surface: "runtime release-promote", anchor: "release-tooling-leaves-the-product-command-surface", matches: (argv) => argv[0] === "runtime" && argv[1] === "release-promote", }, ...( [ "refinement-story", "change-request", ] as const satisfies readonly (keyof typeof TS_BUILD_WORKBENCH_ACTIONS)[] ).flatMap((family) => [...TS_BUILD_WORKBENCH_ACTIONS[family]].map((verb) => ({ surface: `build ${family} ${verb}`, anchor: "the-sqlite-refinement-workbench", matches: (argv: readonly string[]) => argv[0] === "build" && argv[1] === family && argv[2] === verb, })), ), ]; /** The matched entry, or `null` when nothing this story retired was named. */ function retiredSurfaceFor(argv: readonly string[]): RetiredSurface | null { return RETIRED_SURFACES.find((entry) => entry.matches(argv)) ?? null; } /** * The one line a caller sees. No traceback, no usage block, no partial output. * * Every substitution comes from the matched entry, never from argv: a caller * cannot push text into this message, and a path passed to a retired command * cannot reach a terminal, a log, or a screen recording through it. */ export function retiredRefusal(decision: RouteDecision & { engine: "retired" }): string { return ( `Mirror: '${decision.surface}' was removed in the CV22 migration. ` + `See docs/releases/pending-cutoffs.md#${decision.anchor}.\n` ); } // A type alias rather than an interface: aliases get an implicit index // signature, which is what lets the named variables below still be passed to // `resolveProviderTransport`, whose families name their variables as data. // // Only what still CHOOSES something is here: the replay fixtures, which choose // a test transport, and `MEMORY_RECEPTION`. The `MIRROR_TS_` revert // gates chose an engine, and left with it (CV22.DS10.TS5, D3). A value left in // someone's `.env` changes no route; `runtime diagnose` names it inert. export type RouteEnvironment = { MIRROR_TS_SEARCH_EMBEDDING_REPLAY?: string; MIRROR_TS_CONSULT_LLM_REPLAY?: string; MIRROR_TS_CREDITS_REPLAY?: string; MIRROR_TS_CULTIVATION_LLM_REPLAY?: string; MIRROR_TS_CULTIVATION_EMBEDDING_REPLAY?: string; MIRROR_TS_MIRROR_LLM_REPLAY?: string; MIRROR_TS_MIRROR_EMBEDDING_REPLAY?: string; MIRROR_TS_CONVERSATION_LLM_REPLAY?: string; MIRROR_TS_CONVERSATION_EMBEDDING_REPLAY?: string; MIRROR_TS_SOUL_EMBEDDING_REPLAY?: string; MIRROR_TS_BUILD_LLM_REPLAY?: string; MIRROR_TS_BUILD_EMBEDDING_REPLAY?: string; MIRROR_TS_JOURNAL_LLM_REPLAY?: string; MIRROR_TS_JOURNAL_EMBEDDING_REPLAY?: string; MIRROR_TS_WEEK_LLM_REPLAY?: string; MIRROR_TS_DESCRIPTOR_LLM_REPLAY?: string; MEMORY_RECEPTION?: string; }; // CV22.DS7.US5 slice A, extended by CV22.DS7.US10 slice F. These // `conversation-logger` subcommands are deterministic end to end and route to // TS under the family switch alone. const TS_CONVERSATION_LOGGER_SUBCOMMANDS = new Set([ "mute", "unmute", "status", "log-user", "log-assistant", "user-prompt", // CV21.DS2.US8: the Stop hook's reply, deterministic like user-prompt. "stop", "discard-current", // US10 slice F, group 2 (need slice E): diagnose and dry-run repair. (The // Codex import routed here too, until CV21.DS4.TS5 retired it with the // v0.32.1 Codex wrapper.) "diagnose-journeys", "repair-journeys", ]); // CV22.DS7.US10 slice F. These reach Python's `end_conversation`, which runs // extraction and close-time metadata finalization through the LLM. They route // to TS only under the replay transport; an unconfigured install keeps the // Python fallback, which is the live-cutover boundary DS8 owns. Flipped in the // plan's dependency order: `switch`, `session-end-pi`, `session-end` first // (they need slice C' only), then `session-start` and `session-maintenance` // (they compose the close tail with slices D and E). const TS_CONVERSATION_LOGGER_LLM_SUBCOMMANDS = new Set([ "switch", "session-end-pi", "session-end", "session-start", "session-maintenance", ]); // CV22.DS8.US2 staged the live cutover in the order US10 proved and flipped // these in: group 1 (`switch`, `session-end-pi`, `session-end`) first, because // `session-end` fires unattended from the Pi hook; then group 2 // (`session-start` full, `session-maintenance`), which composes the close tail // WITH backfill and orphan handling and can close several conversations in one // run, multiplying any defect. // // Group 1 was observed live on the real home on 2026-09-11 -- a full close // tail with extraction_status=ok, six memories at 1536 dims, and every ledger // row priced with bodies withheld -- so the staging has served its purpose and // all five subcommands now share one live decision. /** Python's `main()`: strip `--mirror-home X` and `--session-id X`, then `args[0]`. */ function conversationLoggerSubcommand(argv: readonly string[]): string | undefined { const args = [...argv.slice(1)]; for (const option of ["--mirror-home", "--session-id"]) { const index = args.indexOf(option); if (index !== -1) args.splice(index, 2); } return args[0]; } /** * One decision for every provider-backed leaf (CV22.DS8.US3). * * `MIRROR_TS_EXTERNAL_ROUTES` is GONE, not merely unused. It was DS5's safety * catch while replay was the PRODUCTION route for these leaves: requiring an * extra opt-in made sense when "routed to TS" meant "answered from a fixture". * After the live cutover replay is a test transport, so the gate would only * add a second thing to set in CI and a stale value to trip over in a shell. * A leftover `=1` or `=0` is inert, and a test pins that. */ function providerRoute( command: string | null, env: RouteEnvironment, spec: ProviderTransportSpec | ComposedProviderTransportSpec, leaf?: string, ): RouteDecision { // A composition resolves three specs at once (`build load` and the one leaf // whose tail it is, `explore story promote`); a plain spec resolves one. Both // yield the same decision shape, so the reason below is written once. const transport = "owner" in spec ? resolveComposedProviderTransport(env, spec) : resolveProviderTransport(env, spec); const reason = leaf ? `${transport.reason} (${leaf})` : transport.reason; // Every transport answers from TypeScript, `incomplete_replay` included: the // route refuses it by name before any provider is built. Until CV22.DS10.TS5 // a PLAIN family sent it to Python instead -- which has no replay transport // and would have called the live provider, the silent spend CR077 made // compositions refuse. return { command, engine: "ts", reason }; } export function routeMemoryCommand( argv: readonly string[], env: RouteEnvironment = process.env, ): RouteDecision { // Retired surfaces are matched FIRST, before any family claims the command. // This is what closes CR089: `journey export-registry` and `journey mutate` // can no longer fall into the `journey` status read and be treated as slugs // -- a wrong answer with exit 0 on a read, and a silent no-op on a write. const retired = retiredSurfaceFor(argv); if (retired) { return { command: argv[0] ?? null, engine: "retired", reason: `${retired.surface} retired in CV22.DS10.TS4`, surface: retired.surface, anchor: retired.anchor, }; } // CR215: a help flag after a command is answered here, before any family // claims the argv, so it never reaches a route that would run. After the // retired match, so a removed surface still says it was removed. return helpDecisionFor(argv) ?? routeByFamily(argv, env); } /** * The `conversation-logger` subcommands a runtime's hooks call. Their argv * carries the user's own text (`log-user `) or runs on every * turn, so a word there that looks like help is the user's, not a request. */ const HOOK_LOGGER_SUBCOMMANDS = new Set([ "log-user", "log-assistant", "user-prompt", "stop", "session-start", "session-end", "session-end-pi", "session-maintenance", ]); /** `conversations` subcommands that answer `--help` themselves, or take a payload. */ const CONVERSATIONS_OWN_ARGV = new Set(["append", "imported", "skill-turns"]); /** * The argv shapes a help flag does not intercept (CR215), named one by one. * * The hook path, because the hooks of four runtimes put the user's prompt in * argv: `mirror doorman --prompt ` on Claude Code, Antigravity, and Pi, * and `conversation-logger log-user `. A user whose whole * prompt is `--help` asked a question; answering it with a usage line would put * that line into the model's context instead of Mirror's. `welcome * --status-line` and `conversations append` are machine calls too. * * And the commands that answer help themselves: `ext` hands the rest of its * argv to an extension's own CLI, and `conversations imported` and * `conversations skill-turns` print their own usage. */ function keepsItsOwnArgv(argv: readonly string[]): boolean { const command = argv[0]; if (command === "ext") return true; if (command === "mirror") return argv[1] === "doorman"; if (command === "conversation-logger") { return HOOK_LOGGER_SUBCOMMANDS.has(conversationLoggerSubcommand(argv) ?? ""); } if (command === "welcome") return argv.includes("--status-line"); if (command === "conversations") return CONVERSATIONS_OWN_ARGV.has(argv[1] ?? ""); return false; } const FRONT_DOOR_COMMAND_NAMES = new Set(FRONT_DOOR_COMMANDS.map(([name]) => name)); /** * CR215: the answer to `-h` or `--help` anywhere after a known command. * * Before this, only the word in the subcommand's place was read as help, and a * help flag anywhere else reached the subcommand, which dropped it or took it * as an argument and ran: `tasks delete --help` deleted the task. Now the * usage engine answers it, before anything is opened, read, or spawned. * * The answer is the subcommand's own line where one exists, and otherwise the * family's, which lists its subcommands. A help flag in the command's own place * (`mirror --help`) is the top-level usage, answered as before. */ export function helpDecisionFor(argv: readonly string[]): RouteDecision | null { const command = argv[0]; if (command === undefined || !FRONT_DOOR_COMMAND_NAMES.has(command)) return null; if (!argv.slice(1).some(isHelpFlag)) return null; if (keepsItsOwnArgv(argv)) return null; const family = HELP_FAMILIES.get(command); if (family === undefined) { const synopsis = COMMAND_SYNOPSES.get(command); return synopsis === undefined ? null : commandHelp(command, synopsis); } const subcommand = family.subcommand(argv); if (subcommand === undefined || !family.choices.includes(subcommand)) { return familyHelp(command, family.choices); } if (command === "explore" && subcommand === "story") { const action = exploreStoryAction(argv) ?? ""; const program = `explore story ${action}`; const synopsis = COMMAND_SYNOPSES.get(program); return synopsis === undefined ? familyHelp(command, [...TS_EXPLORE_STORY_ACTIONS], "explore story") : commandHelp(program, synopsis, command); } const program = `${command} ${subcommand}`; const synopsis = command === "build" ? buildUsageSynopsis(subcommand) : COMMAND_SYNOPSES.get(program); return synopsis === undefined || synopsis === null ? familyHelp(command, family.choices) : commandHelp(program, synopsis, command); } /** A command's own usage line. The reason names the table key, never argv. */ function commandHelp(program: string, synopsis: string, command: string = program): RouteDecision { return { command, engine: "usage", reason: `help: ${program}`, request: { scope: "command", program, synopsis }, }; } /** A family's usage line, the one an unknown subcommand gets, answered as help. */ function familyHelp( command: string, choices: readonly string[], program: string = command, ): RouteDecision { return { command, engine: "usage", reason: `help: ${program}`, request: { scope: "family", program, choices, given: "--help" }, }; } /** * The family routes, WITHOUT the retired-surface match in front of them. * * Exported for one reader: the guard that proves no family branch still names * a shape a retired entry already answers (CV22.DS10.TS5, inventory F2). A * branch like that is dead code nothing can observe -- the retired match wins * before it is reached -- so every front-door test passes over it, which is * exactly how TS4 left two of them behind. The front door itself always calls * `routeMemoryCommand`. */ export function routeByFamily( argv: readonly string[], env: RouteEnvironment = process.env, ): RouteDecision { const command = argv[0] ?? null; if (!command) return unknownCommand(null); // `mirror --version` / `-V`: the version of the running tree, a read that opens nothing. // Before this it fell through to "Unknown command" (issue #58). if (isVersionFlag(command)) { return { command, engine: "ts", reason: "version flag" }; } if (TS_READ_COMMANDS.has(command)) { return { command, engine: "ts", reason: "DS2 read command ported to TS" }; } if (command === "memories") { if (argv.includes("--search")) { // CV22.DS8.US1: fresh semantic search reaches the live provider from TS // by default; a replay fixture wins for CI and the smokes. One // precedence, shared with every provider-backed family. return providerRoute(command, env, SEARCH_TRANSPORT); } return { command, engine: "ts", reason: "DS2 memory listing read ported to TS" }; } if (command === "consult") { // Per leaf, because the fixtures are: `credits` needs the credits fixture // alone, `ask` needs the chat fixture too. With only the credits one set, // `credits` replays and `ask` refuses rather than going half-live. return argv[1] === "credits" ? providerRoute(command, env, CONSULT_CREDITS_TRANSPORT, "credits") : providerRoute(command, env, CONSULT_ASK_TRANSPORT, "ask"); } if (command === "identity") { // `set` (DS4), `list`/`get` (DS7.US1), and `edit` (DS7.TS4's editor seam). if (argv[1] === "set") { return { command, engine: "ts", reason: "DS4 identity set write ported to TS" }; } if (argv[1] === "list" || argv[1] === "get") { return { command, engine: "ts", reason: "DS7.US1 identity list/get read ported to TS" }; } if (argv[1] === "edit") { return { command, engine: "ts", reason: "DS7.TS4 identity edit ported to TS" }; } // Allowlisted by name rather than inherited: `identity` grew `edit` after // `set` claimed the command. return unknownSubcommand(command, IDENTITY_SUBCOMMANDS, argv[1]); } if (command === "extensions") { const verb = argv[1] ?? "list"; if (!TS4_EXTENSIONS_VERBS.has(verb)) { return unknownSubcommand(command, TS4_EXTENSIONS_VERBS, verb); } return { command, engine: "ts", reason: `DS7.TS4 extensions ${verb} ported to TS` }; } if (command === "ext") { // No verb allowlist is possible here, and saying so is better than writing // one that accepts everything: `cmd_ext` treats EVERY head that is not // `list` or a help flag as an extension id, so TS must too. The exposure // that creates is real and named — a new top-level verb beside `list` // would be read as an id and answered `extension not installed` — and it // is guarded by a test that reads `cli/ext.py` and fails when that set of // literals changes, rather than by a set duplicated here that nothing // checks. return { command, engine: "ts", reason: "DS7.TS4 ext dispatcher ported to TS" }; } if (command === "init") { return { command, engine: "ts", reason: "DS7.US1 Slice B init (filesystem bootstrap) ported to TS", }; } if (command === "seed") { return { command, engine: "ts", reason: "DS7.US1 Slice B seed write ported to TS" }; } if (command === "recall") { return { command, engine: "ts", reason: "DS7.US1 recall read ported to TS" }; } if (command === "conversations") { // The plain listing (DS7.US1) and `append` (DS7.US10) are ported; the // metadata-lifecycle/backfill writes are not. // // `append` (v0.31.13) arrived on main after DS7.US1 claimed this command, // and the entry matched every argv shape: the append request routed to TS, // rendered a listing, exited 0, and silently discarded the caller's // messages. Subcommands of a claimed family must be allowlisted, never // inherited -- which is why `append` gets its own explicit entry below // even now that it points at TS. if (argv[1] === "append") { return { command, engine: "ts", reason: "DS7.US10 conversations append boundary ported to TS", }; } // CR154: allowlisted by name for the same reason, before it shipped. Its // apply is named apart, so the front-door log tells a removal from a look. if (argv[1] === "imported") { const applying = argv[2] === "remove" && argv.includes("--apply"); return { command, engine: "ts", reason: applying ? "CR154 conversations imported remove --apply" : "CR154 conversations imported", }; } // CR160: allowlisted by name like CR154's, its apply named apart. if (argv[1] === "skill-turns") { return { command, engine: "ts", reason: argv.includes("--apply") ? "CR160 conversations skill-turns --apply" : "CR160 conversations skill-turns", }; } const writeFlag = TS4_LIFECYCLE_WRITE_FLAGS.find((flag) => argv.includes(flag)); if (writeFlag) { return { command, engine: "ts", reason: `DS7.TS4 ${writeFlag} ported to TS` }; } const readFlag = TS_LIFECYCLE_READ_FLAGS.find((flag) => argv.includes(flag)); if (readFlag) { return { command, engine: "ts", reason: `DS7.US11 ${readFlag} ported to TS`, }; } return { command, engine: "ts", reason: "DS7.US1 conversations listing read ported to TS" }; } if (command === "inspect") { // `persona` (DS7.US1) is a deterministic identity read. The other four // targets are DS7.TS4's: `extension`/`runtime-catalog` share the catalog // machinery, `llm-calls`/`embedding-provenance` read the ledger. if (argv[1] === "persona") { return { command, engine: "ts", reason: "DS7.US1 inspect persona read ported to TS" }; } if (TS4_INSPECT_TARGETS.has(argv[1] ?? "")) { return { command, engine: "ts", reason: `DS7.TS4 inspect ${argv[1]} ported to TS` }; } return unknownSubcommand(command, ["persona", ...TS4_INSPECT_TARGETS], argv[1]); } if (command === "list") { // `personas`/`journeys` (DS7.US1) are deterministic identity reads; // `extensions` and `all` (which is also the no-target default) touch the // extension catalog and belong to DS7.TS4. if (argv[1] === "personas") { return { command, engine: "ts", reason: "DS7.US1 list personas read ported to TS" }; } if (argv[1] === "journeys") { return { command, engine: "ts", reason: "DS7.US1 list journeys read ported to TS" }; } const listTarget = argv[1] ?? "all"; if (listTarget === "extensions" || listTarget === "all") { return { command, engine: "ts", reason: `DS7.TS4 list ${listTarget} ported to TS` }; } return unknownSubcommand(command, LIST_TARGETS, listTarget); } if (command === "descriptor") { // `list` (DS7.US1) is a deterministic read; `generate` calls the LLM // (generate_descriptor) and stays on Python as the DS7↔DS8 live seam. if (argv[1] === "list") { return { command, engine: "ts", reason: "DS7.US1 descriptor list read ported to TS" }; } if (argv[1] === "generate") { return providerRoute(command, env, DESCRIPTOR_TRANSPORT, "generate"); } return unknownSubcommand(command, DESCRIPTOR_SUBCOMMANDS, argv[1]); } if (command === "tasks") { // `list` (and the bare `tasks` default) is a read; `add/done/doing/block/ // delete` are the deterministic writes ported in DS7.US2 slice 3a; // `import/sync/sync-config` (which also touch the journey sync-file/ // project-path metadata subsystem) are ported in slice 3c. // // A LEADING OPTION IS NOT A LIST ANY MORE (CV22.DS10.TS5, F5). The rule // here used to read `tasks --anything ...` as `list`, which is how // `tasks --mirror-home H add "x"` printed the list and wrote nothing. The // options the oracle accepts before the subcommand are now moved after it // by `argvShape.ts` before routing runs, so one that is still here is one // the oracle's parser rejected too -- or `-h`. const sub = argv[1]; if (sub === undefined || sub === "list") { return { command, engine: "ts", reason: "DS7.US2 tasks list read ported to TS" }; } if (TASKS_SUBCOMMANDS.includes(sub)) { return { command, engine: "ts", reason: "DS7.US2 tasks write ported to TS" }; } return unknownSubcommand(command, TASKS_SUBCOMMANDS, sub); } if (command === "week") { // `view` (and the bare `week` default) is a deterministic read ported in // DS7.US2. CR068 corrected this family's accounting: US2 sent `plan` and // `save` to US5, US5 was re-scoped without them, and nothing inherited the // work -- and the reason recorded here claimed BOTH were "LLM-gated", // which is false for `save`. `save_week_items` reads the pending file and // calls `add_task`; it crosses no provider seam. Only `plan` calls a model. const sub = argv[1]; if (sub === undefined || sub === "view") { return { command, engine: "ts", reason: "DS7.US2 week view read ported to TS" }; } if (sub === "save") { return { command, engine: "ts", reason: "DS7.US11 week save (deterministic) ported to TS" }; } if (sub === "plan") { // One model call, no embedding -- so it needs the LLM replay fixture // only, unlike `journal` which crosses the seam twice. return providerRoute(command, env, WEEK_PLAN_TRANSPORT, "plan"); } return unknownSubcommand(command, WEEK_SUBCOMMANDS, sub); } if (command === "consolidate") { // `list`/`reject` are deterministic reads/writes -- always TS (DS7.US3). // `apply` is gated as a WHOLE on the embedding replay config: its action // is read from the DB, not argv, so the routing decision (made before any // DB is opened) cannot special-case identity_update/shadow_candidate -- // the entire command routes together, same principle as `scan`. const sub = argv[1]; if (sub === "list" || sub === "reject") { return { command, engine: "ts", reason: "DS7.US3 consolidate list/reject ported to TS" }; } // `apply` sends NO prompt: a merge embeds the merged content and an // identity_update makes no provider call at all. So it is not blocked by // TS2, unlike `scan`. Gated as a whole because its action is read from the // DB, not argv, and the routing decision precedes any DB open. if (sub === "apply") { return providerRoute(command, env, CULTIVATION_APPLY_TRANSPORT, "apply"); } if (sub === "scan") { return providerRoute(command, env, CULTIVATION_SCAN_TRANSPORT, "scan"); } return unknownSubcommand(command, CONSOLIDATE_SUBCOMMANDS, sub); } if (command === "shadow") { // `list`/`show`/`reject`/`apply` are all deterministic -- `apply`'s write // is a hardcoded-layer identity append, no LLM/embedding call, unlike // consolidate's `apply` (which may need to embed a merge). const sub = argv[1]; if (sub === "list" || sub === "show" || sub === "reject" || sub === "apply") { return { command, engine: "ts", reason: "DS7.US3 shadow list/show/reject/apply ported to TS", }; } if (sub === "scan") { return providerRoute(command, env, CULTIVATION_SCAN_TRANSPORT, "shadow scan"); } return unknownSubcommand(command, SHADOW_SUBCOMMANDS, sub); } if (command === "mirror") { const sub = argv[1]; // CV9.DS8.TS2: the doorman decides before it resolves a provider, and a // `nothing` turn resolves none -- but a `full` turn is `load --query`, so // the route answers for the doorman exactly as it answers for that. if (sub === "load" || sub === "doorman") { const hasQuery = sub === "doorman" || argv.includes("--query"); if (!hasQuery) { return { command, engine: "ts", reason: "DS7.US4 deterministic mirror load ported to TS" }; } // `MEMORY_RECEPTION=0` skips the classifier, so the chat fixture stops // being required for a replay run; the embedding half still is, because // the query still searches attachments and journeys. return providerRoute( command, env, mirrorQueryTransportFor(env), sub === "doorman" ? "doorman" : "load --query", ); } if (sub === "deactivate" || sub === "log" || sub === "journeys") { return { command, engine: "ts", reason: `DS7.US4 mirror ${sub} ported to TS` }; } return unknownSubcommand(command, MIRROR_SUBCOMMANDS, sub); } if (command === "conversation-logger") { // CV22.DS7.US5 slice A: flipped 2026-09-02 after the seven-point checklist // went green (goldens, real-DB-copy write parity, hook-inclusive E2E, // regression pass, redaction, revertibility, ledger). const sub = conversationLoggerSubcommand(argv); if (sub === "repair-journeys" && argv.includes("--apply")) { // The mutating repair takes the dated zip backup (DS7.TS1) before it // writes -- the route itself refuses without it. return { command, engine: "ts", reason: "DS7.TS1 conversation-logger repair-journeys --apply ported to TS", }; } if (sub && TS_CONVERSATION_LOGGER_SUBCOMMANDS.has(sub)) { return { command, engine: "ts", reason: `DS7.US5 conversation-logger ${sub} ported to TS`, }; } if (sub === "session-start" && argv.includes("--fast")) { // Unmute and reorient only: no close tail, so no gate. return { command, engine: "ts", reason: "DS7.US10 conversation-logger session-start --fast ported to TS", }; } if (sub && TS_CONVERSATION_LOGGER_LLM_SUBCOMMANDS.has(sub)) { return providerRoute(command, env, CONVERSATION_TAIL_TRANSPORT, sub); } // The oracle answered an unknown logger subcommand with NOTHING, exit 0 -- // a silent success for a hook that named a subcommand that does not exist. // It now gets the family's answer like every other family (D2, F6). return unknownSubcommand( command, [...TS_CONVERSATION_LOGGER_SUBCOMMANDS, ...TS_CONVERSATION_LOGGER_LLM_SUBCOMMANDS], sub, ); } if (command === "mode") { const sub = argv.find((value, index) => index > 0 && MODE_SUBCOMMANDS.includes(value)); return sub ? { command, engine: "ts", reason: "DS7.US4 operating mode lifecycle ported to TS" } : unknownSubcommand(command, MODE_SUBCOMMANDS, modeGivenSubcommand(argv)); } if (command === "journey") { // `set-path` (DS4), `update` (DS7.US1 Slice B), and the status read // (DS7.US1 Slice A) are all ported. Everything besides `set-path`/ // `update` -- `status [slug]`, a bare slug, or no argument at all -- is a // status read in the real Python dispatch (see render/journeyStatus.ts's // slug-resolution quirk), so it all routes to the same TS status handler. if (argv[1] === "set-path") { return { command, engine: "ts", reason: "DS4 journey set-path write ported to TS" }; } if (argv[1] === "update") { return { command, engine: "ts", reason: "DS7.US1 Slice B journey update write ported to TS" }; } return { command, engine: "ts", reason: "DS7.US1 journey status read ported to TS" }; } if (command === "backup") { return { command, engine: "ts", reason: "DS7.TS1 backup ported to TS" }; } if (command === "repair-encoding") { return { command, engine: "ts", reason: "DS7.TS1 repair-encoding ported to TS" }; } if (command === "welcome") { return { command, engine: "ts", reason: "DS7.TS3 welcome ported to TS" }; } if (command === "runtime") { const subcommand = argv[1] ?? ""; // Allowlist, not blocklist: a subcommand this build has never heard of // must not acquire a TS route because `runtime` already has one. if (!TS_RUNTIME_READ_SUBCOMMANDS.has(subcommand)) { // CV22.DS10.US2: the updater family. const reason = TS_RUNTIME_UPDATE_SUBCOMMANDS.get(subcommand); if (reason !== undefined) return { command, engine: "ts", reason }; // CV22.DS10.US2 made the unknown answer TypeScript's own, rendered by // the runtime route; CV22.DS10.TS5 moved it to the shared usage answer // (D2), which renders the same bytes for every family. return unknownSubcommand(command, RUNTIME_SUBCOMMANDS, subcommand); } return { command, engine: "ts", reason: `DS7.TS3 runtime ${subcommand} ported to TS` }; } if (command === "soul") { const subcommand = argv[1] ?? ""; // Allowlist by NAME, like `runtime`, and for the same reason: a subcommand // the route never implemented must not inherit it because the family is // claimed. That is the `conversations append` defect (RS009/CR055), which // exited 0 and discarded the caller's payload. if (!TS_SOUL_SUBCOMMANDS.has(subcommand)) { return unknownSubcommand(command, TS_SOUL_SUBCOMMANDS, subcommand); } // `harvest save` is the one leaf that crosses the provider seam, through // the embedding alone. if (subcommand === "harvest" && soulHarvestAction(argv) === "save") { return providerRoute(command, env, SOUL_HARVEST_TRANSPORT, "harvest save"); } return { command, engine: "ts", reason: `DS7.US6 soul ${subcommand} ported to TS` }; } if (command === "explore") { const subcommand = argv[1] ?? ""; // TWO levels, because `explore` is the first family with a nested // subparser. A single-level allowlist would claim `explore story // ` and answer an argv shape this route has never implemented. if (!TS_EXPLORE_SUBCOMMANDS.has(subcommand)) { return unknownSubcommand(command, TS_EXPLORE_SUBCOMMANDS, subcommand); } if (subcommand === "story") { const action = exploreStoryAction(argv); if (!TS_EXPLORE_STORY_ACTIONS.has(action ?? "")) { return unknownSubcommand(command, TS_EXPLORE_STORY_ACTIONS, action, "explore story"); } } // `story promote` ends in a Builder session start (`cmd_story_promote` // calls `cmd_load`), so it answers to the SAME composed transport decision // `build load` does -- resolved here rather than inside the route because // promote's writes are not idempotent, so a half-configured replay harness // must be refused before the first mutation, not after. if (subcommand === "story" && exploreStoryAction(argv) === "promote") { return providerRoute(command, env, BUILD_LOAD_COMPOSITION, "story promote"); } return { command, engine: "ts", reason: `DS7.US7 explore ${subcommand} ported to TS` }; } if (command === "build") { const subcommand = argv[1] ?? ""; // `refinement-story` and `change-request` are not build subcommands: the // twenty verbs they had are answered by the retired table before this // line, and anything else under them is an unknown build subcommand -- // what the oracle itself has answered since TS4 deleted the groups. if (!TS_BUILD_SUBCOMMANDS.has(subcommand)) { return unknownSubcommand(command, TS_BUILD_SUBCOMMANDS, subcommand); } // `load` composes the search and conversation-tail provider families. Its // transport must be decided before the banner or any surface is printed. if (subcommand === "load") { return providerRoute(command, env, BUILD_LOAD_COMPOSITION, "load"); } return { command, engine: "ts", reason: `DS7.US8 build ${subcommand} ported to TS` }; } if (command === "journal") { return providerRoute(command, env, JOURNAL_TRANSPORT); } if (command === "mcp") { // CV22.DS10.TS5 (F9): the server DS9 ported, reached through the front // door as the oracle's `mcp` was. The plugin launches it directly; this is // the same server, not a second one. return { command, engine: "ts", reason: "DS9 MCP server, launched through the front door" }; } return unknownCommand(command); } // The subcommands of families whose routes above test them one by one. Named // here so the usage answer lists exactly what the routes answer. const IDENTITY_SUBCOMMANDS = ["list", "get", "set", "edit"]; const LIST_TARGETS = ["personas", "journeys", "extensions", "all"]; const DESCRIPTOR_SUBCOMMANDS = ["generate", "list"]; const TASKS_SUBCOMMANDS = [ "list", "add", "done", "doing", "block", "import", "delete", "sync", "sync-config", ]; const WEEK_SUBCOMMANDS = ["view", "plan", "save"]; const CONSOLIDATE_SUBCOMMANDS = ["scan", "apply", "reject", "list"]; const SHADOW_SUBCOMMANDS = ["scan", "apply", "reject", "list", "show"]; const MIRROR_SUBCOMMANDS = ["load", "deactivate", "log", "journeys", "doorman"]; const MODE_SUBCOMMANDS = ["activate", "deactivate", "status"]; /** `mode`'s first positional, past the two options its parser declares; "" when none. */ function modeGivenSubcommand(argv: readonly string[]): string { const args = [...argv.slice(1)]; for (const option of ["--mirror-home", "--session-id"]) { const index = args.indexOf(option); if (index !== -1) args.splice(index, 2); } return args[0] ?? ""; } // Python's argparse subcommands for `soul`, by name. const TS_SOUL_SUBCOMMANDS = new Set([ "load", "listen", "rite", "close", "review", "propose", "apply", "fruit", "harvest", "prompt", ]); // Python's argparse subcommands for `explore`, by name. const TS_EXPLORE_SUBCOMMANDS = new Set(["load", "deactivate", "story"]); // Python's `explore story` actions, by name. // // `promote` joined at CV22.DS7.US8 plateau 7, having waited on Python by name // since US7 because `cmd_story_promote` ends by calling Builder `load`. It is // the one action here whose engine also depends on the provider composition; // see the decision above. const TS_EXPLORE_STORY_ACTIONS = new Set([ "promote", "show", "list", "archive", "update", "clear", "open", "thicken", "snapshot", "attractors", "experiment", "handoff", ]); /** `explore story `, skipping the options argparse strips first. */ function exploreStoryAction(argv: readonly string[]): string | undefined { const args = [...argv.slice(2)]; for (const option of ["--mirror-home", "--db-path", "--session-id"]) { const index = args.indexOf(option); if (index !== -1) args.splice(index, 2); } return args[0]; } /** `soul harvest `, skipping the options argparse strips first. */ function soulHarvestAction(argv: readonly string[]): string | undefined { const args = [...argv.slice(2)]; for (const option of ["--mirror-home", "--db-path", "--session-id", "--journey"]) { const index = args.indexOf(option); if (index !== -1) args.splice(index, 2); } return args[0]; } /** A family's subcommands, and where in argv its route reads which one was given. */ interface HelpFamily { readonly choices: readonly string[]; readonly subcommand: (argv: readonly string[]) => string | undefined; } const SECOND_WORD = (argv: readonly string[]): string | undefined => argv[1]; /** * CR215: every family with subcommands, from the SAME allowlists the routes * above answer by and the unknown-subcommand answer lists. A family absent * from here answers help with its one line in `COMMAND_SYNOPSES`. */ const HELP_FAMILIES: ReadonlyMap = new Map([ ["identity", { choices: IDENTITY_SUBCOMMANDS, subcommand: SECOND_WORD }], ["extensions", { choices: [...TS4_EXTENSIONS_VERBS], subcommand: SECOND_WORD }], ["inspect", { choices: ["persona", ...TS4_INSPECT_TARGETS], subcommand: SECOND_WORD }], ["list", { choices: LIST_TARGETS, subcommand: SECOND_WORD }], ["descriptor", { choices: DESCRIPTOR_SUBCOMMANDS, subcommand: SECOND_WORD }], ["tasks", { choices: TASKS_SUBCOMMANDS, subcommand: SECOND_WORD }], ["week", { choices: WEEK_SUBCOMMANDS, subcommand: SECOND_WORD }], ["consolidate", { choices: CONSOLIDATE_SUBCOMMANDS, subcommand: SECOND_WORD }], ["shadow", { choices: SHADOW_SUBCOMMANDS, subcommand: SECOND_WORD }], ["mirror", { choices: MIRROR_SUBCOMMANDS, subcommand: SECOND_WORD }], [ "conversation-logger", { choices: [...TS_CONVERSATION_LOGGER_SUBCOMMANDS, ...TS_CONVERSATION_LOGGER_LLM_SUBCOMMANDS], subcommand: conversationLoggerSubcommand, }, ], [ "mode", { choices: MODE_SUBCOMMANDS, subcommand: (argv) => argv.find((value, index) => index > 0 && MODE_SUBCOMMANDS.includes(value)), }, ], ["runtime", { choices: RUNTIME_SUBCOMMANDS, subcommand: SECOND_WORD }], ["soul", { choices: [...TS_SOUL_SUBCOMMANDS], subcommand: SECOND_WORD }], ["explore", { choices: [...TS_EXPLORE_SUBCOMMANDS], subcommand: SECOND_WORD }], ["build", { choices: [...TS_BUILD_SUBCOMMANDS], subcommand: SECOND_WORD }], ]); /** The families help answers by subcommand, for the test that walks every one. */ export function helpFamilies(): ReadonlyMap { return new Map([...HELP_FAMILIES].map(([name, family]) => [name, family.choices])); }