@tikoci/centrs 0.1.9-next.0 → 0.1.9-next.22

package/src/core/cmr.ts

@@ -4,6 +4,7 @@
  */
 
 import { CentrsError } from "../errors.ts";
+import type { ProtocolAdapter } from "../protocols/adapter.ts";
 import type { Warning } from "./envelope.ts";
 
 /** The controller command that runs a script on CMR clients. */
@@ -102,3 +103,80 @@ export function cmrScriptWarnings(script: string): Warning[] {
 		? [clientScriptNotValidated]
 		: [];
 }
+
+/** The policies CMR gives every `run-script` script on a client (manual; 7.26beta1). */
+export const CMR_SCRIPT_POLICIES = ["read", "write", "test", "reboot"] as const;
+
+/** The controller login's own group and its granted policies. */
+export interface CmrCallerPolicy {
+	username: string;
+	group: string;
+	/** Granted policy names; `!name` entries are dropped. */
+	policy: readonly string[];
+}
+
+/**
+ * Read the session user's group policy on the controller, or `undefined` when
+ * it cannot be read (a RADIUS login has no `/user` row). Grounded on
+ * 7.26beta1 over REST and native API: a login with only `read` and `api`
+ * (`!sensitive !policy` too) can read its own `/user` row and `/user/group`.
+ */
+export async function readCmrCallerPolicy(
+	adapter: Pick<ProtocolAdapter, "apiRequest">,
+	username: string,
+): Promise<CmrCallerPolicy | undefined> {
+	const first = async (path: string, name: string) => {
+		const result = await adapter.apiRequest({
+			verb: "print",
+			path,
+			query: [`name=${name}`],
+		});
+		return Array.isArray(result.data)
+			? (result.data[0] as Record<string, string> | undefined)
+			: undefined;
+	};
+	try {
+		const group = (await first("/user", username))?.["group"];
+		if (!group) return undefined;
+		const policy = (await first("/user/group", group))?.["policy"];
+		if (policy === undefined) return undefined;
+		return {
+			username,
+			group,
+			policy: policy
+				.split(",")
+				.map((name) => name.trim())
+				.filter((name) => name.length > 0 && !name.startsWith("!")),
+		};
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * #456: RouterOS does not hold a CMR fleet command to the caller's policy. On
+ * 7.26beta1 `run-script` needs only `read` + `api` on the controller login,
+ * yet the script runs on each client (the controller's own row included) with
+ * {@link CMR_SCRIPT_POLICIES}. A "reader" login wrote and rebooted clients
+ * through it. Warn when the login lacks a policy the command will run with,
+ * so a caller does not take the login for the limit; centrs' own write gate
+ * is the only one. MikroTik says 7.26beta2 refuses this for a `read` group
+ * (forum topic 273582, post 139); not yet checked on a beta2 build.
+ */
+export function cmrCallerPolicyWarning(
+	caller: CmrCallerPolicy,
+	runsWith: readonly string[],
+): Warning | undefined {
+	const missing = runsWith.filter((name) => !caller.policy.includes(name));
+	if (missing.length === 0) return undefined;
+	return {
+		code: "cmr/caller-policy-not-enforced",
+		message: `The controller login \`${caller.username}\` (group \`${caller.group}\`) lacks ${missing.join(", ")}, but CMR runs this on the clients with ${runsWith.join(", ")}. RouterOS 7.26beta1 does not check the caller's policy here, so the login does not limit what a CMR command can change (MikroTik says 7.26beta2 will).`,
+		context: {
+			username: caller.username,
+			group: caller.group,
+			missing,
+			runsWith: [...runsWith],
+		},
+	};
+}

package/src/core/envelope.ts

@@ -15,6 +15,10 @@
  * - `meta` is invariant across commands. Only `data` and `meta.operation` vary
  *   per command. Do not add command-specific keys beside `target`/`via`/
  *   `settings`/`validation`/`timing`/`truncated`; put them in `meta.operation`.
+ * - Shared meta is written once (#461, #462, #473). A fan-out target omits
+ *   what its outer envelope already says ({@link FanoutMemberOperation}); a
+ *   stream's data lines between `started` and `summary` carry only their
+ *   `meta.operation` ({@link StreamLineEnvelope}).
  * - CLI render must be lossless against the JSON envelope; `--format json|yaml`
  *   select serialization, not different shapes. Omit `undefined`; use `null`
  *   only where absence is meaningful and must round-trip (e.g. `via: null` when
@@ -112,10 +116,10 @@ export interface EnvelopeTargetMeta {
 	/**
 	 * `execute --cmr`: the CMR client this result belongs to, as the controller
 	 * knows it. `id` is the controller's `/cmr/device` row; `deviceKey` is the
-	 * device half of its `ids`. The client is never dialed directly.
+	 * device half of its `ids`. The client is never dialed directly; the
+	 * controller is the fan-out's outer `meta.target`.
 	 */
 	cmr?: {
-		controller: string;
 		id: string;
 		deviceKey?: string;
 		address?: string;
@@ -287,9 +291,34 @@ export interface FanoutSummary {
 	failed: number;
 }
 
+/**
+ * A fan-out target's `meta.operation`. `request` and `auth` are omitted when
+ * they equal the outer `meta.operation`'s, and the target's `meta.settings`
+ * keeps only the keys whose source differs from the outer `meta.settings`, so
+ * a reader takes `target ?? outer` (per key for settings).
+ */
+export type FanoutMemberOperation<Operation> = Omit<
+	Operation,
+	"request" | "auth"
+> &
+	Partial<Pick<Operation, Extract<keyof Operation, "request" | "auth">>>;
+
 export interface FanoutData<Data = unknown, Operation = unknown> {
 	summary: FanoutSummary;
-	targets: readonly CentrsEnvelope<Data, Operation>[];
+	targets: readonly CentrsEnvelope<Data, FanoutMemberOperation<Operation>>[];
+}
+
+/**
+ * A stream data line that carries only its own `meta.operation`; the rest of
+ * its meta is on the stream's `started` and `summary` lines (and `synced` for
+ * `retrieve --follow`).
+ */
+export interface StreamLineEnvelope<Data = unknown, Operation = unknown> {
+	ok: true;
+	data: Data;
+	warnings: readonly Warning[];
+	tips: readonly Tip[];
+	meta: { operation: Operation };
 }
 
 /** Normalize an optional warnings list to a readonly array. */

package/src/core/error-catalog.ts

@@ -55,11 +55,13 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 	},
 	{
 		code: "cdb/empty-group",
-		summary: "The named CDB group contains no records.",
+		summary:
+			"The named CDB group contains no records: a warning for a read, an error for a write-shaped fan-out.",
 	},
 	{
 		code: "cdb/empty-selection",
-		summary: "The target selection matched no CDB records.",
+		summary:
+			"The target selection matched no CDB records: a warning for a read, an error for a write-shaped fan-out.",
 	},
 	{
 		code: "cdb/file-exists",
@@ -268,6 +270,11 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		summary:
 			"The operation was cancelled before the command was sent to a CMR client.",
 	},
+	{
+		code: "cmr/caller-policy-not-enforced",
+		summary:
+			"Warning: the controller login lacks a policy the CMR command runs with on the clients, and RouterOS does not check it.",
+	},
 	{
 		code: "cmr/client-script-not-validated",
 		summary:
@@ -281,7 +288,7 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 	{
 		code: "cmr/empty-selection",
 		summary:
-			"Warning: the `--labels` expression matched no CMR device on the controller.",
+			"The CMR selection matched no device on the controller: for `--cmr`, a warning for a read and an error for a write; for a fleet command such as `/cmr/vlan/add`, a warning.",
 	},
 	{
 		code: "cmr/membership-changed",
@@ -313,6 +320,16 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		summary:
 			"A CMR client refused a statement because CMR scripts run without the policy it needs; earlier statements already ran.",
 	},
+	{
+		code: "cmr/rule-selects-every-device",
+		summary:
+			"Warning: a CMR rule command has no device `labels` (and, for VLAN, no `port-labels`), so the rule applies to every device, the controller included.",
+	},
+	{
+		code: "cmr/selection-includes-controller",
+		summary:
+			"Warning: a CMR fleet command selects the controller's own row as well as its clients.",
+	},
 	{
 		code: "cmr/selection-incomplete",
 		summary:
@@ -611,6 +628,11 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		code: "usage/conflicting-flags",
 		summary: "Two or more supplied flags conflict.",
 	},
+	{
+		code: "usage/flag-after-separator",
+		summary:
+			"A centrs flag was written after `--`, where every token is RouterOS input.",
+	},
 	{
 		code: "usage/invalid-concurrency",
 		summary: "The --concurrency value must be an integer >= 1.",

package/src/core/execute-command.ts

@@ -101,7 +101,7 @@ export function canonicalizeExecuteCommand(
 
 export function isWriteShaped(command: CanonicalExecuteCommand): boolean {
 	if (command.mode === "structured") {
-		if (FILE_OUTPUT_ATTRIBUTE in command.attributes) {
+		if (Object.keys(command.attributes).some(isFileOutputAttribute)) {
 			return true;
 		}
 		return !READ_ONLY_EXECUTE_VERBS.has(command.verb.toLowerCase());
@@ -110,21 +110,35 @@ export function isWriteShaped(command: CanonicalExecuteCommand): boolean {
 }
 
 /**
- * The attribute that turns an otherwise read-only verb into a device write.
+ * The attributes that turn an otherwise read-only command into a device write.
  *
  * RouterOS routes command output to a file on the device when `file=` is
  * supplied, so a read verb creates a file: `/ip/address/export file=address`
  * writes `address.rsc`, and `/file/print file=test` writes `test.txt` (both
  * from the RouterOS manual — "Configuration Export" and "Scripting Tips and
  * Tricks", where that idiom is the documented way to create a file and needs
- * the script `write` policy). The verb allowlist cannot see that, so the
- * attribute is checked independently of it.
+ * the script `write` policy). `:serialize` spells it `file-name=` (its
+ * `/console/inspect` arguments, 7.13.5 through 7.26beta1). The verb and
+ * directive allowlists cannot see either, so they are checked independently.
  */
-const FILE_OUTPUT_ATTRIBUTE = "file";
+const FILE_OUTPUT_ATTRIBUTES: readonly string[] = ["file", "file-name"];
 
-/** True for a `file=<name>` token — the write-shaping output redirect. */
+/**
+ * RouterOS accepts argument prefixes (`fi=`, `file-n=`), including on
+ * `:serialize` (CHR 7.26beta1). An ambiguous prefix stays write-shaped too:
+ * only the device can disambiguate it, so the local gate fails closed.
+ */
+function isFileOutputAttribute(name: string): boolean {
+	return (
+		name.length > 0 &&
+		FILE_OUTPUT_ATTRIBUTES.some((full) => full.startsWith(name))
+	);
+}
+
+/** True for an output-file argument, including its abbreviated spellings. */
 function isFileOutputToken(token: string): boolean {
-	return token.startsWith(`${FILE_OUTPUT_ATTRIBUTE}=`);
+	const separator = token.indexOf("=");
+	return separator > 0 && isFileOutputAttribute(token.slice(0, separator));
 }
 
 /**
@@ -193,27 +207,59 @@ const WRITE_SHAPED_SCRIPT_DIRECTIVES: ReadonlySet<string> = new Set([
 /**
  * Script directives that are safe to run without device-write confirmation:
  * output, control flow and pure value functions, all members of `explain`'s
- * grounded root-cmd vocabulary (`ROOT_CMDS` in `src/explain/write.ts`). A
- * directive's `do={…}` or `[…]` body is its own command head and is checked on
- * its own. Deliberately absent: `:execute` and `:parse` (run built code),
- * `:global` and `:set` (outlive the script), and `:import`, `:password`,
- * `:undo`, `:redo` (configuration changes).
+ * grounded root-cmd vocabulary (`ROOT_CMDS` in `src/explain/write.ts`) and
+ * present on 7.26beta1. A directive's `do={…}` or `[…]` body is its own
+ * command head and is checked on its own. That holds because a script-typed
+ * argument (`:do command=`, `:if do=`, `:retry command=`, `:time`, `:onerror
+ * in=`) runs only a `{…}` block: RouterOS refuses a quoted string or a variable
+ * holding one there as an invalid value (CHR 7.24.5 and 7.26beta1, #458), so
+ * no body can hide in text the gate blanks. The value functions (#458) take
+ * only values; `:serialize` alone can write, through `file-name=` (it creates
+ * the file on 7.26beta1), which the file-output check catches.
+ *
+ * Deliberately absent: `:execute` and `:parse` (run built code), `:global` and
+ * `:set` (outlive the script), and `:import`, `:password`, `:undo`, `:redo`
+ * (configuration changes). A directive missing here costs `--yes`; one wrongly
+ * here bypasses the gate.
  */
 const READ_ONLY_SCRIPT_DIRECTIVES: ReadonlySet<string> = new Set([
 	":break",
 	":continue",
+	":convert",
+	":delay",
+	":deserialize",
 	":do",
 	":error",
+	":find",
 	":for",
 	":foreach",
 	":if",
+	":jobname",
 	":len",
 	":local",
+	":nothing",
 	":onerror",
 	":pick",
 	":put",
+	":range",
+	":retry",
 	":return",
+	":rndnum",
+	":rndstr",
+	":serialize",
+	":time",
+	":timestamp",
+	":toarray",
+	":tobool",
+	":tocrlf",
+	":toid",
+	":toip",
+	":toip6",
+	":tolf",
+	":tonsec",
+	":tonum",
 	":tostr",
+	":totime",
 	":typeof",
 	":while",
 ]);
@@ -249,7 +295,11 @@ function scriptContainsWriteShapedCommand(input: string): boolean {
 		// Every command the statement runs must be proven read-only, not just the
 		// first: `:foreach i in=[/ip address find] do={/user expire-password $i}`
 		// reads with `find` and writes with an unlearned mutator.
-		if (!commandHeads(statement).every(isReadOnlyCommand)) {
+		if (
+			!commandHeads(statement).every(
+				(head) => !head.spacedFileOutput && isReadOnlyCommand(head.words),
+			)
+		) {
 			return true;
 		}
 	}
@@ -264,12 +314,23 @@ function scriptContainsWriteShapedCommand(input: string): boolean {
  * expressions, not commands, so they do not start one. Each head reads only up
  * to the next opener, which begins its own head.
  */
-function commandHeads(statement: string): string[][] {
-	const heads: string[][] = [];
+function commandHeads(
+	statement: string,
+): { words: string[]; spacedFileOutput: boolean }[] {
+	const heads: { words: string[]; spacedFileOutput: boolean }[] = [];
 	const starts = [0];
+	// Match group ends once. Each command can then skip its nested bodies
+	// without walking them again; deeply nested reads stay linear in input size.
+	const closes = new Map<number, number>();
+	const open: number[] = [];
 	for (let index = 0; index < statement.length; index += 1) {
-		const char = statement[index];
+		const char = statement[index] ?? "";
 		if (char === "[" || char === "{") starts.push(index + 1);
+		if ("[{(".includes(char)) open.push(index);
+		else if ("]})".includes(char)) {
+			const start = open.pop();
+			if (start !== undefined) closes.set(start, index);
+		}
 	}
 	for (const start of starts) {
 		const nextOpener = statement.slice(start).search(/[[{(]/);
@@ -282,11 +343,58 @@ function commandHeads(statement: string): string[][] {
 		if (head === undefined) continue;
 		const words = commandWords(head, tokens.slice(1));
 		// A lone closer (`}` ending a multi-line block) runs nothing.
-		if (words.length > 0) heads.push(words);
+		if (words.length > 0)
+			heads.push({
+				words,
+				spacedFileOutput: hasSpacedFileOutput(statement, start, words, closes),
+			});
 	}
 	return heads;
 }
 
+/**
+ * RouterOS also accepts `file value` / `file-name value` without `=`. These
+ * belong to print/export/serialize, not a loop variable or a pure function's
+ * value. Read the command's own tokens, skipping nested expressions and
+ * blocks: `:serialize value=[:tostr file] file-n "out"` has one file argument
+ * after its nested read. Quoted text is already masked by the statement split.
+ * Grounded on CHR 7.26beta1, with export also checked on long-term.
+ */
+function hasSpacedFileOutput(
+	statement: string,
+	start: number,
+	words: readonly string[],
+	closes: ReadonlyMap<number, number>,
+): boolean {
+	let commandWords: number;
+	if (words[0] === ":serialize") {
+		commandWords = 1;
+	} else {
+		const depth = menuDepth(words);
+		if (words[depth] !== "print" && words[depth] !== "export") return false;
+		commandWords = depth + 1;
+	}
+	let own = "";
+	for (let index = start; index < statement.length; index += 1) {
+		const char = statement[index] ?? "";
+		if ("[{(".includes(char)) {
+			own += " ";
+			index = closes.get(index) ?? statement.length;
+		} else if ("]})".includes(char)) {
+			break;
+		} else own += char;
+	}
+	let consumed = 0;
+	for (const token of tokenizeRouterOsCli(own)) {
+		if (consumed < commandWords) {
+			consumed += token.split("/").filter(Boolean).length;
+			continue;
+		}
+		if (!token.includes("=") && isFileOutputAttribute(token)) return true;
+	}
+	return false;
+}
+
 /**
  * The path segments and verb of one command, from its head token and the bare
  * words after it. The space-separated spelling puts menu segments and the verb
@@ -299,6 +407,19 @@ function commandWords(head: string, following: readonly string[]): string[] {
 	const words: string[] = [];
 	const headWord = trimGroupingPunctuation(head);
 	if (headWord.startsWith(":")) return [headWord];
+	// `/serialize …` is the root command `:serialize`: at statement start the
+	// sigil is optional and `/` binds the root vocabulary (CHR 7.23.2, see
+	// `src/explain/symbols.ts`). Only the absolute one-segment form is read
+	// this way. A bare `delay` may be a relative menu command after earlier
+	// navigation, so it keeps the menu-verb rule and fails closed.
+	const root = /^\/([A-Za-z0-9-]+)$/.exec(headWord)?.[1]?.toLowerCase();
+	if (
+		root !== undefined &&
+		READ_ONLY_SCRIPT_DIRECTIVES.has(`:${root}`) &&
+		!isKnownMenuPath([root])
+	) {
+		return [`:${root}`];
+	}
 	words.push(...headWord.split("/").filter(Boolean));
 	if (headWord !== head) return words;
 	for (const token of following) {
@@ -325,12 +446,16 @@ function commandWords(head: string, following: readonly string[]): string[] {
 function isReadOnlyCommand(words: readonly string[]): boolean {
 	const head = words[0] ?? "";
 	if (head.startsWith(":")) return READ_ONLY_SCRIPT_DIRECTIVES.has(head);
+	const verb = words[menuDepth(words)];
+	return verb !== undefined && READ_ONLY_EXECUTE_VERBS.has(verb.toLowerCase());
+}
+
+function menuDepth(words: readonly string[]): number {
 	let depth = 0;
 	while (depth < words.length && isKnownMenuPath(words.slice(0, depth + 1))) {
 		depth += 1;
 	}
-	const verb = words[depth];
-	return verb !== undefined && READ_ONLY_EXECUTE_VERBS.has(verb.toLowerCase());
+	return depth;
 }
 
 function trimGroupingPunctuation(value: string): string {

package/src/core/fanout.ts

@@ -20,7 +20,9 @@ import type {
 	CommonSettingsMeta,
 	EnvelopeTargetMeta,
 	FanoutData,
+	FanoutMemberOperation,
 	FanoutSummary,
+	SettingSource,
 	ValidationTrace,
 	Warning,
 } from "./envelope.ts";
@@ -310,29 +312,151 @@ export function commonVia(
 	return via ?? null;
 }
 
+/** The part of an outer fan-out `operation` its targets may share. */
+interface SharedOperation {
+	request?: unknown;
+	auth?: unknown;
+}
+
+/**
+ * Write shared meta once (#461): the outer envelope keeps the run's settings,
+ * request and auth, and each target keeps only what differs from them. A
+ * settings key the outer envelope lacks, and the `auth`, move out when every
+ * target that reached an operation agrees on them. A target's `settings`
+ * keeps the keys whose source differs from the outer key's; its
+ * `request`/`auth` are dropped when equal to the outer ones.
+ */
+export function compactFanoutTargets<Data, Op, OuterOp extends object>(
+	settings: CommonSettingsMeta,
+	operation: OuterOp,
+	targets: readonly CentrsEnvelope<Data, Op>[],
+): {
+	settings: CommonSettingsMeta;
+	operation: OuterOp;
+	targets: CentrsEnvelope<Data, FanoutMemberOperation<Op>>[];
+} {
+	// A target that failed before it had an operation (a resolve failure)
+	// has no settings or auth to agree or disagree with.
+	const reached = targets.flatMap((target) => {
+		const inner = target.meta.operation as SharedOperation | undefined;
+		return inner ? [{ settings: target.meta.settings, auth: inner.auth }] : [];
+	});
+	const agreed = (value: (member: (typeof reached)[number]) => unknown) => {
+		const first = reached[0] && value(reached[0]);
+		return first !== undefined &&
+			reached.every((member) => Bun.deepEquals(value(member), first))
+			? first
+			: undefined;
+	};
+	const outerSettings: CommonSettingsMeta = { ...settings };
+	for (const key of Object.keys(reached[0]?.settings ?? {})) {
+		if (outerSettings[key] !== undefined) continue;
+		const source = agreed((member) => member.settings[key]);
+		if (source !== undefined) outerSettings[key] = source as SettingSource;
+	}
+	const outer = operation as SharedOperation;
+	const auth = outer.auth === undefined ? agreed((m) => m.auth) : undefined;
+	const shared: SharedOperation =
+		auth === undefined ? outer : { ...outer, auth };
+	return {
+		settings: outerSettings,
+		operation: shared as OuterOp,
+		targets: targets.map((target) => {
+			const own: CommonSettingsMeta = {};
+			// An `undefined` source is never written: JSON drops it, so a direct
+			// and a serialized reader would disagree on what the target inherits.
+			for (const [key, source] of Object.entries(target.meta.settings)) {
+				if (source !== undefined && !Bun.deepEquals(source, outerSettings[key]))
+					own[key] = source;
+			}
+			const meta = { ...target.meta, settings: own };
+			const inner = target.meta.operation as
+				| (Record<string, unknown> & SharedOperation)
+				| undefined;
+			if (inner) {
+				const { request, auth, ...rest } = inner;
+				// `auth` is shared only when every reached target has the same
+				// defined one, and every inner operation type requires `request`,
+				// so an omitted field always means "equal to the outer one".
+				const differs = (value: unknown, outer: unknown) =>
+					value !== undefined && !Bun.deepEquals(value, outer);
+				meta.operation = {
+					...rest,
+					...(differs(request, shared.request) ? { request } : {}),
+					...(differs(auth, shared.auth) ? { auth } : {}),
+				} as Op;
+			}
+			return { ...target, meta } as CentrsEnvelope<
+				Data,
+				FanoutMemberOperation<Op>
+			>;
+		}),
+	};
+}
+
+/**
+ * The inverse of {@link compactFanoutTargets}: a target's full meta, read as
+ * `target ?? outer` (per key for settings). A target that failed before it
+ * had an operation gets no operation.
+ */
+export function expandFanoutTarget<Data, Op>(
+	outer: { meta: { settings: CommonSettingsMeta; operation?: unknown } },
+	target: CentrsEnvelope<Data, FanoutMemberOperation<Op>>,
+): CentrsEnvelope<Data, Op> {
+	const shared = (outer.meta.operation ?? {}) as SharedOperation;
+	const inner = target.meta.operation as
+		| (Record<string, unknown> & SharedOperation)
+		| undefined;
+	const settings: CommonSettingsMeta = { ...outer.meta.settings };
+	for (const [key, source] of Object.entries(target.meta.settings)) {
+		if (source !== undefined) settings[key] = source;
+	}
+	const operation = inner && {
+		...inner,
+		...(inner.request === undefined && shared.request !== undefined
+			? { request: shared.request }
+			: {}),
+		...(inner.auth === undefined && shared.auth !== undefined
+			? { auth: shared.auth }
+			: {}),
+	};
+	return {
+		...target,
+		meta: { ...target.meta, settings, ...(operation ? { operation } : {}) },
+	} as CentrsEnvelope<Data, Op>;
+}
+
 /**
  * Assemble the locked fan-out success envelope: `data = { summary, targets }`,
  * outer `ok: true` = orchestration succeeded. The command owns its outer
- * `operation` meta shape and passes it in.
+ * `operation` meta shape and passes it in; shared meta is hoisted out of the
+ * targets by {@link compactFanoutTargets}. `target` is the outer target, set
+ * only when the fan-out runs through one router (a CMR controller).
  */
-export function buildFanoutEnvelope<Data, Op, OuterOp>(input: {
+export function buildFanoutEnvelope<Data, Op, OuterOp extends object>(input: {
 	summary: FanoutSummary;
 	targets: readonly CentrsEnvelope<Data, Op>[];
 	warnings: readonly Warning[];
 	settings: CommonSettingsMeta;
 	via: RouterOsProtocol | null;
 	operation: OuterOp;
+	target?: EnvelopeTargetMeta;
 }): CentrsSuccessEnvelope<FanoutData<Data, Op>, OuterOp> {
+	const { settings, operation, targets } = compactFanoutTargets(
+		input.settings,
+		input.operation,
+		input.targets,
+	);
 	return {
 		ok: true,
-		data: { summary: input.summary, targets: input.targets },
+		data: { summary: input.summary, targets },
 		warnings: input.warnings,
 		tips: [],
 		meta: {
-			target: {},
+			target: input.target ?? {},
 			via: input.via,
-			settings: input.settings,
-			operation: input.operation,
+			settings,
+			operation,
 		},
 	};
 }

package/src/errors.ts

@@ -265,11 +265,12 @@ export function serializeUnknownError(error: unknown): unknown {
 		return serializeCentrsError(error);
 	}
 
+	// No `stack`: it is raw exception text with local install paths, and the
+	// constitution summarizes those rather than embedding them (#476).
 	if (error instanceof Error) {
 		return {
 			name: error.name,
 			message: error.message,
-			stack: error.stack,
 			code: extractErrorCode(error),
 		};
 	}