@tikoci/centrs 0.1.9-next.23 → 0.1.9-next.24

package/src/explain.ts

@@ -70,9 +70,9 @@
  *     separate optional homes but no offline producer. Each fact has its own
  *     provenance; no hint validates a value or becomes a diagnostic. The
  *     decision and the probe matrix are #225; `op` is deliberately not a shape
- *     hint — `(> …)` abstains offline and is reported only as a live
- *     `observedType` because identical syntax can be `op` or `array` and
- *     `:parse` IL cannot distinguish them (#288). This module is deliberately
+ *     hint — `(> …)` abstains offline AND live, because identical syntax can
+ *     be `op` or `array` and only `:typeof`, which live explain never sends,
+ *     distinguishes them (#288, #225). This module is deliberately
  *     type-blind, which is why a verdict that looks wrong around a value is a
  *     type-axis question before it is a lexical one.
  *   - **`runtimeAcceptance` is always `"not-proven"`**, offline and live alike.
@@ -101,7 +101,12 @@ import type {
 	CommonSettingsMeta,
 	EnvelopeMeta,
 } from "./core/envelope.ts";
-import { buildTip, type Tip, type Warning } from "./core/envelope.ts";
+import {
+	buildTip,
+	type EnvelopeValidationMeta,
+	type Tip,
+	type Warning,
+} from "./core/envelope.ts";
 import {
 	type CanonicalExecuteCommand,
 	canonicalizeExecuteCommand,
@@ -172,7 +177,12 @@ import {
 	type ExplainTransport,
 } from "./explain/transport.ts";
 import { valueSpans } from "./explain/value-tokens.ts";
-import { type ValueShape, valueShapeHints } from "./explain/values.ts";
+import {
+	type ObservedValueType,
+	type SchemaValueType,
+	type ValueShape,
+	valueShapeHints,
+} from "./explain/values.ts";
 import {
 	type DocumentVerbSplit,
 	resolveVerb,
@@ -460,15 +470,21 @@ export interface ExplainStructure {
  *
  * The vocabulary is centrs-owned (the ratified decision): consumers depend on
  * it rather than on raw RouterOS `highlight` classes, so cross-version drift in
- * those classes is centrs's problem to absorb. For these five the two names
- * currently coincide, which is a convenience, not the contract.
+ * those classes is centrs's problem to absorb. Name-coincident classes keep
+ * their spelling; live classes outside this vocabulary remain unclassified
+ * here and are preserved in the raw highlight observation.
  */
 export type ExplainSpanClass =
 	| "comment"
 	| "variable-local"
 	| "variable-global"
 	| "variable-auto"
-	| "variable-parameter";
+	| "variable-parameter"
+	| "dir"
+	| "cmd"
+	| "arg"
+	| "escaped"
+	| "unclassified";
 
 export interface ExplainSpan extends ExplainSpanRange {
 	class: ExplainSpanClass;
@@ -620,8 +636,34 @@ export interface ExplainValueShapeFact {
 	ev: string;
 }
 
+/**
+ * A type the device's parser visibly converted a bare literal to (#225).
+ *
+ * Only a conversion is evidence: `:parse` prints a string unquoted, so an
+ * unchanged rendering (`123`, `1.1.1.1`, `"2.2"`) proves nothing and the fact
+ * is absent. See `src/explain-live-types.ts`.
+ */
 export interface ExplainValueTypeFact {
-	value: string;
+	value: ObservedValueType;
+	/** The device's own rendering of the literal (`2.2` → `2.0.0.2`). */
+	rendered: string;
+	ev: string;
+}
+
+/**
+ * An argument's declared type, normalized from a schema source (#225).
+ *
+ * `values` are the leaf types the declaration mentions, not alternatives of
+ * one value: `gateway` (`Address[%Interface][@VRF]`) lists `ip`, `ip6` and
+ * `enum`, because inspect prints the interface names like keywords. `declared` is the source's own top-level term, verbatim,
+ * so a consumer can tell a live `/console/inspect` declaration from a CLI
+ * Reference `Type` cell by `ev` and still read the original.
+ */
+export interface ExplainSchemaTypeFact {
+	values: SchemaValueType[];
+	/** Present only when the declaration spells a repetition; absence is not a claim. */
+	list?: true;
+	declared: string;
 	ev: string;
 }
 
@@ -629,7 +671,7 @@ export interface ExplainValueTypeFact {
 export interface ExplainValueFacts {
 	shapeHints?: ExplainValueShapeFact;
 	observedType?: ExplainValueTypeFact;
-	schemaType?: ExplainValueTypeFact;
+	schemaType?: ExplainSchemaTypeFact;
 }
 
 export interface ExplainValueOccurrence {
@@ -670,18 +712,14 @@ export interface ExplainDiagnostic {
 }
 
 /**
- * Where a derived fact came from — the OFFLINE SUBSET of the contract.
- *
- * The spec's evidence entry also carries `source: "live-inspect"` and a
- * RouterOS version stamp per probe, neither of which phase 1 can produce: no
- * probe runs and there is no device to stamp. The type says only what offline
- * emits rather than pre-declaring variants with no producer, so a consumer
- * cannot narrow on a `source` that never appears; phase 2 widens the union and
- * adds the stamp, which is an ADDITION to the shape a caller reads today.
+ * Where an analysis fact came from.
+ *
+ * Live probes add version, observation time, input identity and coverage. Their
+ * outcome describes acquisition, never runtime acceptance.
  */
 export interface ExplainEvidence {
 	id: string;
-	source: "canonicalizer";
+	source: "canonicalizer" | "live-inspect";
 	/** The analyzer that produced the facts citing this entry. */
 	probe: string;
 	/**
@@ -692,7 +730,157 @@ export interface ExplainEvidence {
 	 * drawn from live responses.
 	 */
 	basis: "direct" | "heuristic" | "derived";
-	outcome: "ok" | "empty" | "timeout" | "transport-error";
+	outcome:
+		| "ok"
+		| "empty"
+		| "timeout"
+		| "transport-error"
+		| "auth-error"
+		| "unsupported"
+		| "skipped"
+		| "interrupted"
+		| "invalid-response";
+	/** Live observation provenance; absent on canonicalizer evidence. */
+	version?: string;
+	observedAt?: string;
+	statementIds?: string[];
+	path?: string;
+	coverage?: ExplainSpanRange;
+	inputSha256?: string;
+	normalization?: "original-utf8" | "sub-per-non-ascii-byte";
+	reason?: string;
+	errorCode?: CentrsError["code"];
+	/**
+	 * The facet a live probe served; an `empty` facet answer is not a warning.
+	 * `types` is the value-type probes (#225), which run on every live call.
+	 */
+	facet?: "schema" | "complete" | "types";
+}
+
+/** One `request=syntax` row, verbatim: the device's declared help for one argument. */
+export interface ExplainSyntaxRow {
+	symbol: string;
+	/** RouterOS `symbol-type` (`definition`, `explanation`, …). */
+	kind: string;
+	text: string;
+	/** RouterOS `nested` depth. */
+	depth: number;
+}
+
+/** A menu or verb under a described menu, with counts when it was expanded. */
+export interface ExplainSchemaChild {
+	name: string;
+	verbs?: number;
+	menus?: number;
+	arguments?: number;
+	ev?: string;
+}
+
+export interface ExplainSchemaArgument {
+	name: string;
+	/** Argument-level `syntax` rows, present when within the probe budget. */
+	syntax?: ExplainSyntaxRow[];
+	ev?: string;
+}
+
+/**
+ * `--schema`: what the device declares at one path (#492). `child` decides
+ * the node; a menu lists verbs and submenus, a command its arguments, `print`
+ * also its `.proplist`. Declared facts only — never print rows or state.
+ */
+export interface ExplainSchema {
+	/** The `child` probe on the described path. */
+	ev: string;
+	path: string;
+	statementId?: string;
+	node: "menu" | "command" | "argument" | "unknown";
+	verbs?: ExplainSchemaChild[];
+	menus?: ExplainSchemaChild[];
+	arguments?: ExplainSchemaArgument[];
+	/** Output-field names a `print` can show; not print rows. */
+	proplist?: {
+		ev: string;
+		source: "print-proplist" | "get-value-name";
+		names: string[];
+	};
+	/** Argument node only: its `syntax` rows. */
+	syntax?: ExplainSyntaxRow[];
+	/** Full sizes as the device reported them, before any list was cut. */
+	counts: {
+		verbs?: number;
+		menus?: number;
+		arguments?: number;
+		proplist?: number;
+	};
+	/** A list was cut or children were left unexpanded. */
+	truncated: boolean;
+	/** Narrower inputs that expand what this result left out. */
+	next: string[];
+	reason?: string;
+}
+
+export interface ExplainCompletionCandidate {
+	text: string;
+	/** `variable`: a name in a `where` clause, which RouterOS scopes as a variable. */
+	kind: "menu" | "verb" | "argument" | "variable" | "value";
+	/** `exact` when the typed prefix already spells the whole candidate. */
+	match: "partial" | "exact";
+	/** The input-completion probe that offered it. */
+	ev: string;
+}
+
+/**
+ * `--complete`: what may follow at the cursor (#492). Every candidate is an
+ * observation: the device's input completion, cited by `ev`. It is never a
+ * closed set, and a value may reflect configuration state (interface names).
+ * Declared facts (`child`, argument `syntax`) live in {@link ExplainSchema}.
+ */
+export interface ExplainCompletion {
+	/** Analyzed byte offset; equals the device's UTF-8 byte offset. */
+	cursor: number;
+	/** The cursor in the original document: 0-based line, UTF-16 character. */
+	at: { line: number; character: number };
+	statementId?: string;
+	context: "path" | "argument-name" | "variable" | "value" | "unsupported";
+	/** Bytes a chosen candidate replaces; `end` is the cursor. */
+	replace: ExplainSpanRange;
+	prefix: string;
+	/** The command at the cursor, when known (argument-name and value contexts). */
+	path?: string;
+	/** Value context: the argument (or `where` property) whose value is being completed. */
+	argument?: string;
+	/** Exact argument name: whether the device offers `=` at the cursor. */
+	takesValue?: boolean;
+	candidates: ExplainCompletionCandidate[];
+	/** Argument value context: argument-level `syntax` rows (type information). */
+	syntax?: ExplainSyntaxRow[];
+	count: number;
+	truncated: boolean;
+	reason?: string;
+}
+
+export interface ExplainLiveData {
+	environment?: {
+		ev: string;
+		version: string;
+		architecture?: string;
+		board?: string;
+	};
+	/** Exact parse output; absent when empty, skipped or unavailable. */
+	parse?: {
+		ev: string;
+		output: string;
+		rejected: boolean;
+		position?: { line: number; column: number };
+	};
+	/** Raw device classes, retained separately from the centrs span vocabulary. */
+	highlight?: { ev: string; classes: string[] };
+	arguments: {
+		ev: string;
+		path: string;
+		statementIds: string[];
+		names: string[];
+	}[];
 }
 
 export interface ExplainData {
@@ -703,6 +891,12 @@ export interface ExplainData {
 	symbols: ExplainSymbols;
 	values: ExplainValues;
 	spans: ExplainSpan[];
+	/** Read-only device observations, present only on live calls. */
+	live?: ExplainLiveData;
+	/** Live `--schema` only. */
+	schema?: ExplainSchema;
+	/** Live `--complete` only. */
+	completion?: ExplainCompletion;
 	/**
 	 * Total, gapless token partition of `[0, input.bytes)`.
 	 *
@@ -725,8 +919,8 @@ export interface ExplainData {
 
 export interface ExplainOperationMeta {
 	command: "explain";
-	/** `offline` is the only mode phase 1 has; live evidence is phase 2. */
-	mode: "offline";
+	/** Whether a target was consulted for read-only evidence. */
+	mode: "offline" | "live";
 	statementCount: number;
 	verdict: ExplainVerdict;
 }
@@ -1271,11 +1465,24 @@ export function buildTokens(
 	return out;
 }
 
+/** Source order, with the most severe finding first at the same byte. */
+export function compareExplainDiagnostics(
+	a: ExplainDiagnostic,
+	b: ExplainDiagnostic,
+): number {
+	return (
+		a.span.start - b.span.start ||
+		severityRank(b.severity) - severityRank(a.severity)
+	);
+}
+
 function severityRank(s: ExplainSeverity): number {
 	return s === "error" ? 2 : s === "warning" ? 1 : 0;
 }
 
-function verdictOf(diagnostics: readonly ExplainDiagnostic[]): ExplainVerdict {
+export function verdictOf(
+	diagnostics: readonly ExplainDiagnostic[],
+): ExplainVerdict {
 	let worst = 0;
 	for (const d of diagnostics)
 		worst = Math.max(worst, severityRank(d.severity));
@@ -1479,7 +1686,11 @@ export function explainCommand(
 		}),
 		...braceDiagnostics,
 		...groupFaultDiagnostics(
-			findGroupFaults(analyzed, analyzedRange.masked),
+			findGroupFaults(
+				analyzed,
+				analyzedRange.masked,
+				defects.find(({ defect }) => defect.code === "bom")?.defect.end,
+			),
 			braceDiagnostics,
 		),
 		...separators.flatMap((runs) => runs.map(missingSeparatorDiagnostic)),
@@ -1487,11 +1698,7 @@ export function explainCommand(
 			pairs.filter((pair) => pair.valueShaped).map(spacedArgumentDiagnostic),
 		),
 		...statements.flatMap((s) => diagnosticsForStatement(s)),
-	].sort(
-		(a, b) =>
-			a.span.start - b.span.start ||
-			severityRank(b.severity) - severityRank(a.severity),
-	);
+	].sort(compareExplainDiagnostics);
 
 	const valueFacts = valuesOf(
 		verbs.splits,
@@ -2134,6 +2341,18 @@ function spacedArgumentDiagnostic(pair: SpacedPair): ExplainDiagnostic {
 const INVALID_COMMAND_BRACE =
 	"brace arrays are not valid in command arguments — use a parenthesized comma list such as `(1,2)`, or a bare comma list where the argument schema accepts one";
 
+/**
+ * A `name={` with a script-like body that is not a proven script slot (#525).
+ *
+ * `warning`, not `error`: `down={ :beep }` lowers to `down-script=` on CHR
+ * 7.24.5 and 7.23.8, while `comment={ :beep }` is a `syntax error` there, and
+ * telling them apart needs the command's argument list, which is schema. The
+ * brace is read as a body; the device decides the slot.
+ */
+function possibleScriptBodyMessage(name: string): string {
+	return `possible script-body abbreviation: \`${name}=\` with a \`{…}\` body may be a script-valued argument or abbreviate one; offline has no per-command argument list to confirm the slot, so the brace is read as a script body — device validation decides`;
+}
+
 /**
  * The group faults as diagnostics (#505, #509, #511, #512).
  *
@@ -2198,9 +2417,35 @@ function groupFaultMessage(f: GroupFault): string {
 			return '`$` must be followed by a variable name (letters and digits) or `"name"`, and RouterOS rejects it here (`syntax error`) — quote a literal dollar (`"\\$"`)';
 		case "invalid-name":
 			return 'a variable name is letters and digits only, and RouterOS rejects any other byte in it (`expected end of command`) — quote the name (`:local "a_b"`) to use other characters';
+		case "unquoted-non-ascii":
+		case "unquoted-reserved-byte":
+			return unquotedByteMessage(f);
 	}
 }
 
+/**
+ * The unquoted-byte faults (#358, #371). The remedy follows the site: a value
+ * can be quoted, an argument name must be corrected, and a path, command or
+ * `$name` must lose the byte (a variable name may be quoted, `$"café"`).
+ */
+function unquotedByteMessage(f: GroupFault): string {
+	const what =
+		f.code === "unquoted-non-ascii"
+			? "a non-ASCII character outside a string"
+			: f.detail === "="
+				? "a second `=` in a bare argument"
+				: `an unquoted \`${f.detail}\``;
+	if (f.site === "argument-name")
+		return `${what} in an argument name: RouterOS rejects the name at its first byte (\`expected end of command\`) — correct the argument name; no RouterOS argument name holds this byte`;
+	if (f.site === "head-word")
+		return `${what} in a path or command word: RouterOS rejects it (\`expected command name\` or \`expected end of command\`) — remove or retype the byte (a \`?\` is the console's help key, and a pasted non-breaking space or curly quote only looks like ASCII); a variable name may be quoted (\`$"café"\`)`;
+	if (f.code === "unquoted-non-ascii")
+		return `${what}: RouterOS reads only ASCII in a bare word, name or value, and rejects it (\`expected end of command\`) — quote it (\`name="café"\`, \`$"café"\`), or retype a pasted non-breaking space, curly quote or ellipsis`;
+	return f.detail === "="
+		? `${what} value: RouterOS rejects it (\`expected end of command\`) — quote the value (\`comment="a=b"\`), as a base64 key ending in \`=\` needs`
+		: `${what} is never part of a bare word, and RouterOS rejects it (\`expected end of command\`) — quote the value (\`url="http://x/a?b"\`)`;
+}
+
 function invalidCommandBraceDiagnostics(
 	splits: readonly DocumentVerbSplit[],
 	analyzed: string,
@@ -2212,12 +2457,15 @@ function invalidCommandBraceDiagnostics(
 		const { start, end } = split.span;
 		const text = analyzed.slice(start, end);
 		if (text !== split.text) continue;
-		// The verb splitter cannot yet flatten every relative nested menu block.
-		// Do not reinterpret a known submenu's leading `{` as an argument value,
-		// but retain diagnostics for rejected braces later in the same split.
-		// Require evidence that the brace actually opens a menu container
-		// (body starts with a submenu name), so `/ip/route/print {1;2}` and
-		// `/ip { firewall/filter/print {1;2} }` still diagnose the `{1;2}` array.
+		// The segmenter flattens a relative submenu block only where the source
+		// alone names the menu (#351, `menuBlockPath`): not after a navigation
+		// statement (`/ip⏎address { … }`), and not for an abbreviated or
+		// digit-led menu word. Those still reach here as one split. Do not
+		// reinterpret a known submenu's leading `{` as an argument value, but
+		// retain diagnostics for rejected braces later in the same split.
+		// Require evidence that the brace actually opens a menu container, so
+		// `/ip/route/print {1;2}` and `/ip { firewall/filter/print {1;2} }` still
+		// diagnose the `{1;2}` array.
 		//
 		// A verb the vocabulary or the catalog names is no menu, so its leading
 		// brace is a positional operand: `/system/script add { :beep }` and
@@ -2284,18 +2532,28 @@ function invalidCommandBraceDiagnostics(
 				}
 			}
 		}
-		for (const at of invalidCommandBraceOffsets(
+		for (const finding of invalidCommandBraceOffsets(
 			text,
 			split.argsAt,
 			split.path === "/" ? split.verb : undefined,
 			nestedRange(analyzedRange, start, end),
 		)) {
-			if (at === menuBraceAt) continue;
+			if (finding.at === menuBraceAt) continue;
+			if (finding.ambiguous) {
+				out.push({
+					code: "explain/canonicalizer/possible-script-body-abbreviation",
+					severity: "warning",
+					message: possibleScriptBodyMessage(finding.name ?? "name"),
+					span: { start: start + finding.at, end: start + finding.at + 1 },
+					ev: EV.values,
+				});
+				continue;
+			}
 			out.push({
 				code: "explain/canonicalizer/invalid-command-brace",
 				severity: "error",
 				message: INVALID_COMMAND_BRACE,
-				span: { start: start + at, end: start + at + 1 },
+				span: { start: start + finding.at, end: start + finding.at + 1 },
 				ev: EV.values,
 			});
 		}
@@ -2611,7 +2869,7 @@ export function explainEnvelope(
 		buildTip(
 			"tip/explain-offline-only",
 			"No router was given, so this is the canonicalizer's reading alone.",
-			"Completion, schema, and `:parse` evidence come from a live target (`centrs explain <router> '<input>'`), which is phase 2 and not accepted yet.",
+			"Add a router (`centrs explain <router> '<input>'`) for read-only parse, highlight and argument-name evidence; `--schema` and `--complete` then describe paths and complete at the cursor.",
 		),
 		...(options.tips ?? []),
 	];
@@ -2620,7 +2878,7 @@ export function explainEnvelope(
 		target: {},
 		via: null,
 		settings: settingsMeta(options.format),
-		validation: { enabled: false, result: "skipped" },
+		validation: explainValidationMeta(),
 		operation: {
 			command: "explain",
 			mode: "offline",
@@ -2645,7 +2903,7 @@ export function buildExplainFacetTip(facets: readonly string[]): Tip {
 	return buildTip(
 		"tip/explain-live-facets",
 		`${named} enumerate what a device accepts, and no router was given — so nothing is enumerated here.`,
-		"Name a router once live evidence lands (phase 2); until then use `rosetta` for documented RouterOS schema facts.",
+		"Name a router (`centrs explain <router> '<input>' --schema`) to ask the device; use `rosetta` for documented RouterOS schema facts.",
 	);
 }
 
@@ -2779,10 +3037,23 @@ export function buildExplainErrorEnvelope(
 		error: serializeCentrsError(centrs),
 		warnings: [],
 		tips,
-		meta: { target: {}, via: null, settings: settingsMeta(format) },
+		meta: {
+			target: {},
+			via: null,
+			settings: settingsMeta(format),
+			validation: explainValidationMeta(),
+		},
 	};
 }
 
+/**
+ * explain is not a gate: it never runs the input, so there is no gate verdict
+ * to report, offline or live. Its verdict is `data.verdict` (#535).
+ */
+export function explainValidationMeta(): EnvelopeValidationMeta {
+	return { enabled: false };
+}
+
 export function renderExplainEnvelope(
 	envelope: ExplainEnvelope | ExplainErrorEnvelope,
 	format: ExplainOutputFormat,
@@ -2844,7 +3115,85 @@ function renderValue(occurrence: ExplainValueOccurrence): string {
 	const shapes = occurrence.facts.shapeHints?.values.join("|") ?? "unknown";
 	const parent =
 		occurrence.parent === undefined ? "" : ` in=${occurrence.parent}`;
-	return `${occurrence.kind.padEnd(10)}${name}${parent} shapes=${shapes}`;
+	const observed = occurrence.facts.observedType;
+	const schema = occurrence.facts.schemaType;
+	const live = `${observed ? ` observed=${observed.value}(${observed.rendered})` : ""}${schema ? ` schema=${schema.values.join("|")}${schema.list ? "[list]" : ""}` : ""}`;
+	return `${occurrence.kind.padEnd(10)}${name}${parent} shapes=${shapes}${live}`;
+}
+
+function renderLiveSummary(live: ExplainLiveData): string {
+	const device = live.environment
+		? `${live.environment.version}${live.environment.architecture ? ` ${live.environment.architecture}` : ""}`
+		: "device unavailable";
+	const parse = live.parse
+		? `parse ${live.parse.rejected ? "rejected" : "accepted"}${live.parse.position ? ` at ${live.parse.position.line}:${live.parse.position.column}` : ""}`
+		: "parse unavailable";
+	const highlight = live.highlight
+		? `highlight ${live.highlight.classes.length} byte(s)`
+		: "highlight unavailable";
+	const names = live.arguments.reduce(
+		(total, entry) => total + entry.names.length,
+		0,
+	);
+	return `live: ${device} · ${parse} · ${highlight} · arguments ${live.arguments.length} path(s), ${names} name(s)`;
+}
+
+/** Names only, at most a dozen per line; `--json` keeps every fact. */
+function renderSchemaSummary(schema: ExplainSchema): string[] {
+	const list = (label: string, names: readonly string[], total?: number) =>
+		`  ${label} (${total ?? names.length}): ${names.slice(0, 12).join(", ")}${(total ?? names.length) > Math.min(names.length, 12) ? ", …" : ""}`;
+	const lines = [
+		`schema: ${schema.path} is ${schema.node === "unknown" ? "unknown to the device" : `a ${schema.node}`}${schema.truncated ? " (truncated)" : ""}${schema.reason ? ` — ${schema.reason}` : ""}`,
+	];
+	if (schema.verbs)
+		lines.push(
+			list(
+				"verbs",
+				schema.verbs.map((v) => v.name),
+				schema.counts.verbs,
+			),
+		);
+	if (schema.menus?.length)
+		lines.push(
+			list(
+				"menus",
+				schema.menus.map((m) => m.name),
+				schema.counts.menus,
+			),
+		);
+	if (schema.arguments)
+		lines.push(
+			list(
+				"arguments",
+				schema.arguments.map((a) => a.name),
+				schema.counts.arguments,
+			),
+		);
+	if (schema.proplist)
+		lines.push(list("proplist", schema.proplist.names, schema.counts.proplist));
+	if (schema.syntax)
+		for (const row of schema.syntax)
+			lines.push(`  ${row.symbol ? `${row.symbol}: ` : ""}${row.text}`);
+	return lines;
+}
+
+function renderCompletionSummary(completion: ExplainCompletion): string {
+	const head = `complete @${completion.cursor}: ${completion.context}${completion.argument ? ` ${completion.argument}=` : ""}${completion.prefix ? ` "${completion.prefix}"` : ""}`;
+	if (completion.reason && completion.candidates.length === 0)
+		return `${head} — ${completion.reason}`;
+	const shown = completion.candidates
+		.slice(0, 12)
+		.map((c) => (c.match === "exact" ? `${c.text}*` : c.text));
+	const value =
+		completion.takesValue === undefined
+			? ""
+			: completion.takesValue
+				? " (takes a value: `=`)"
+				: " (flag, no value)";
+	const syntax = completion.syntax?.length
+		? ` [${completion.syntax.map((row) => row.text || row.symbol).join("; ")}]`
+		: "";
+	return `${head} → ${completion.count === 0 ? "no candidates" : `${shown.join(", ")}${completion.count > shown.length ? ", …" : ""}`}${value}${syntax}`;
 }
 
 /**
@@ -2874,6 +3223,9 @@ function renderExplainText(
 		`gate: ${canonical.mode}${canonical.path ? ` ${canonical.path}` : ""}${canonical.verb ? ` ${canonical.verb}` : ""} · ${argCount} arg(s)${canonical.writeShaped ? " · write-shaped" : ""}`,
 	);
 	lines.push(`write: ${structure.containsWrite}`);
+	if (data.live) lines.push(renderLiveSummary(data.live));
+	if (data.schema) lines.push(...renderSchemaSummary(data.schema));
+	if (data.completion) lines.push(renderCompletionSummary(data.completion));
 	if (data.input.normalized)
 		lines.push(
 			`input: ${data.input.bytes} byte(s), normalized (non-ASCII stood in for one-for-one)`,

package/src/index.ts

@@ -480,6 +480,7 @@ export {
 	type ExplainEvidence,
 	type ExplainFailOn,
 	type ExplainInput,
+	type ExplainLiveData,
 	type ExplainMenuReading,
 	type ExplainOperationMeta,
 	type ExplainOutputFormat,
@@ -514,6 +515,11 @@ export {
 	explainOutputFormats,
 	renderExplainEnvelope,
 } from "./explain.ts";
+export {
+	EXPLAIN_LIVE_LIMITS,
+	type ExplainLiveRequest,
+	explainLiveEnvelope,
+} from "./explain-live.ts";
 export {
 	assertOfflineSyntax,
 	isOfflineGateRejection,