@wildo-ai/saas-models 1.1.3 → 1.1.5

package/dist/esm/config/frontend/chart-registration-alignment.shared.js

@@ -8,10 +8,66 @@
  *     the backend `ChartRegistry` so `POST /charts/:ref/data` can execute.
  *
  * A frontend chartView whose `chartDefinition.ref` has NO backend registration
- * produces a silent runtime 404 (`chart_not_found`) — the host renders but the
- * data fetch fails. This module is the pure, framework-general comparator that a
+ * produces a runtime 404 (`chart_not_found`) — the host renders but the data
+ * fetch fails. This module is the pure, framework-general comparator that a
  * build-time / CLI guard uses to catch that drift before it ships.
  *
+ * ## The failure is LOUD but LATE, and the distinction decides what this guard is for
+ * Earlier revisions of this file, the CLI verb and the CI workflow all called that 404
+ * "silent". Measured on the runtime path, it is not: `ChartView` renders `ChartErrorState`
+ * (an error card with a retry action), a standalone chart page also raises the global error
+ * toast (`localErrorOnly` is only set by EMBEDDED hosts), and the backend answers a NOT_FOUND
+ * whose context names the resolved ref.
+ *
+ * So this guard does not exist to make an invisible failure visible. It exists because the
+ * failure is only visible to whoever OPENS the chart — a chart on a rarely-visited surface
+ * ships broken and is discovered by a user. Everything here moves that discovery to authoring
+ * time. Do not restate "silent"; it overstates the defect and misdescribes what is being fixed.
+ *
+ * ## Why this is a comparator and not a boot refusal
+ * Neither runtime process can perform this join, so there is no boot to refuse at:
+ *   - the BACKEND cannot see `chartViews` — it lives on `ResourceUIBehaviorConfig` in `.tsx`
+ *     ui-behavior modules the backend cannot import, which is why the dev companion needs a
+ *     dedicated introspection SUBPROCESS to materialize it (and why the backend module slot
+ *     exists as a second wiring in the first place);
+ *   - the FRONTEND has `chartViews` but never receives the backend's registered set — nothing
+ *     serializes `ChartRegistry.getRegisteredChartRefs()` into any boot payload.
+ * The only process that sees both is the companion, which is where every channel that runs
+ * this comparator lives: `POST /api/companion/charts/audit`, `wildo charts audit`, and the CI
+ * gate. The BACKEND-visible half of chart wiring — a chart naming a resource type that does
+ * not exist — is refused at boot by `ChartRegistryBackendService.registerChart`.
+ *
+ * ## The backend set has TWO possible sources, and only ONE of them is the answer
+ * `ApplicationInitializationConfig.chartDefinitions` — the array `StartApplicationBackendService`
+ * actually registers — is assembled as
+ * `overrides.chartDefinitions ?? input.backendRegistry.chartDefinitions`
+ * (`buildApplicationInitializationConfigFromModules`). That is a REPLACE, not a merge. So an
+ * application supplying `overrides.chartDefinitions` makes the module DECLARATIONS an arbitrary set
+ * with no relation to what registers: it may drop a declared chart (a comparison built on the
+ * declarations then reports ALIGNED while the chart 404s) and it may add one that is not declared
+ * (the same comparison then reports a false FAIL).
+ *
+ * Hence {@link ChartRegistrationBackendRefsProvenance}. A caller must say WHICH set it brought, and
+ * a comparison built on the declarations yields
+ * {@link ChartRegistrationAlignmentVerdict.CANNOT_VOUCH} — never `ALIGNED`. A guard that says "I
+ * cannot answer" beats one that answers about a different population; that is the same class as a
+ * green report read off a stale artifact
+ * (`.claude/rules/staleness-presents-as-a-logic-defect.md`).
+ *
+ * ## The effective set IS reachable — no contract change is needed
+ * An earlier note on `ChartRegistryBackendService.getRegisteredChartRefs` said closing this "needs
+ * the overrides to reach the companion, which the `companion-exports` contract does not currently
+ * carry". **That was wrong, and the contract had already answered it**:
+ * `BackendCompanionExports.buildApplicationInitializationConfig()` is REQUIRED, is the same pure
+ * builder backend startup uses, starts nothing, and its JSDoc says in as many words that "tooling
+ * must not reconstruct selected runtime capabilities from lower-level registries". Composing the
+ * backend side from `mergeBackendDomainModules(...)` was exactly that reconstruction.
+ *
+ * Residual, stated rather than hidden: the companion calls the builder with NO host overrides, so it
+ * sees the set the APPLICATION declares. A HOST that passed `chartDefinitions` in its own overrides
+ * would diverge — neither dogfood host does (both pass only `customControllers`, `container`,
+ * `serviceIdentifier`, `providerRuntime`), and a host-level chart override has no use case today.
+ *
  * ## Join key
  * The comparison key is `chartView.chartDefinition.ref` (the execution ref the
  * frontend runtime sends), NOT the outer `chartView.ref` (the view identity).
@@ -30,6 +86,50 @@
 export function normalizeChartExecutionRef(rawRef) {
     return rawRef.trim();
 }
+/**
+ * WHERE a caller's `backendRegisteredRefs` came from — the input that decides whether this
+ * comparison is about the population that actually registers.
+ *
+ * A closed vocabulary with a named home rather than a boolean, because the two members are not
+ * "good/bad": each names a concrete assembly step, and the reason one of them cannot be vouched for
+ * is a specific line of code (`overrides.chartDefinitions ?? input.backendRegistry.chartDefinitions`)
+ * that a `trusted: false` flag could never carry.
+ */
+export var ChartRegistrationBackendRefsProvenance;
+(function (ChartRegistrationBackendRefsProvenance) {
+    /**
+     * From `BackendCompanionExports.buildApplicationInitializationConfig().chartDefinitions` — the
+     * exact array `StartApplicationBackendService` registers, with any
+     * `ApplicationInitializationOverrides.chartDefinitions` already applied. The only provenance that
+     * supports a vouched verdict.
+     */
+    ChartRegistrationBackendRefsProvenance["EFFECTIVE_INITIALIZATION_CONFIG"] = "effective-initialization-config";
+    /**
+     * From `mergeBackendDomainModules(...).chartDefinitions` — what the modules DECLARE. Equal to the
+     * effective set only while no application supplies `overrides.chartDefinitions`; nothing in this
+     * set records whether one does, which is why a caller supplying it gets `CANNOT_VOUCH` rather
+     * than a verdict.
+     *
+     * This is also what an ABSENT provenance means. The permissive reading was deliberately NOT
+     * chosen for the default: a caller that has not thought about which set it brought has, by
+     * definition, brought the one it could reach without asking.
+     */
+    ChartRegistrationBackendRefsProvenance["MODULE_DECLARATIONS"] = "module-declarations";
+})(ChartRegistrationBackendRefsProvenance || (ChartRegistrationBackendRefsProvenance = {}));
+/** What the comparison is entitled to conclude, given where its backend set came from. */
+export var ChartRegistrationAlignmentVerdict;
+(function (ChartRegistrationAlignmentVerdict) {
+    /** Every frontend chartView resolves against the set that actually registers. */
+    ChartRegistrationAlignmentVerdict["ALIGNED"] = "aligned";
+    /** At least one frontend chartView has no registration in the set that actually registers. */
+    ChartRegistrationAlignmentVerdict["MISALIGNED"] = "misaligned";
+    /**
+     * The comparison ran and its channels are populated, but the backend set was not the effective
+     * one — so NEITHER a clean nor a dirty result may be reported as fact. Report the channels as
+     * evidence; do not report alignment.
+     */
+    ChartRegistrationAlignmentVerdict["CANNOT_VOUCH"] = "cannot-vouch";
+})(ChartRegistrationAlignmentVerdict || (ChartRegistrationAlignmentVerdict = {}));
 /**
  * Compare the set of frontend chartView refs against the set of backend-registered
  * chart refs. Both sides are normalized via {@link normalizeChartExecutionRef}
@@ -43,14 +143,61 @@ export function computeChartRegistrationAlignment(params) {
     const orphanBackendCharts = [
         ...new Set(normalizedBackend.filter((ref) => !frontendSet.has(ref))),
     ];
-    return { unregisteredFrontendCharts, orphanBackendCharts };
+    const backendRefsProvenance = params.backendRefsProvenance ?? ChartRegistrationBackendRefsProvenance.MODULE_DECLARATIONS;
+    const verdict = backendRefsProvenance !== ChartRegistrationBackendRefsProvenance.EFFECTIVE_INITIALIZATION_CONFIG
+        ? ChartRegistrationAlignmentVerdict.CANNOT_VOUCH
+        : unregisteredFrontendCharts.length > 0
+            ? ChartRegistrationAlignmentVerdict.MISALIGNED
+            : ChartRegistrationAlignmentVerdict.ALIGNED;
+    return { backendRefsProvenance, verdict, unregisteredFrontendCharts, orphanBackendCharts };
+}
+/**
+ * Render the provenance caveat, or `undefined` when the report may be taken at face value.
+ *
+ * Exists so the two surfaces a person reads — the CLI's summary line and the thrown gate message —
+ * cannot word this differently, or one of them forget it. A caveat that appears on one surface is
+ * the state this whole change is repairing.
+ */
+export function describeChartRegistrationVerdictCaveat(report) {
+    if (report.verdict !== ChartRegistrationAlignmentVerdict.CANNOT_VOUCH)
+        return undefined;
+    return ('This comparison used the module DECLARATIONS '
+        + `(provenance: ${report.backendRefsProvenance}), not the set the backend registers. `
+        + 'An application supplying `ApplicationInitializationOverrides.chartDefinitions` REPLACES the '
+        + 'declared array, so a dropped chart would read as aligned here and 404 at runtime. '
+        + 'Fix: take the backend refs from '
+        + '`backendCompanionExports.buildApplicationInitializationConfig().chartDefinitions` and pass '
+        + `backendRefsProvenance: ${ChartRegistrationBackendRefsProvenance.EFFECTIVE_INITIALIZATION_CONFIG}.`);
 }
 /**
  * Throw a verbose, locatable error if any frontend chartView is unregistered
  * backend-side. Only the FAIL channel throws; `orphanBackendCharts` (WARN) never
  * throws. Use in the `--strict` path of the CLI audit / a CI gate.
+ *
+ * ## `requireVouchedVerdict` defaults to `true`, and that is the point of the parameter
+ *
+ * A clean FAIL channel is only evidence of alignment when the backend set was the EFFECTIVE one — a
+ * chart dropped by an `ApplicationInitializationOverrides.chartDefinitions` override is registered
+ * nowhere and declared everywhere, so a comparison against the DECLARATIONS reports ALIGNED about a
+ * population the application does not run. So this refuses a
+ * {@link ChartRegistrationAlignmentVerdict.CANNOT_VOUCH} report rather than returning quietly, and a
+ * caller has to say deliberately that it does not want that.
+ *
+ * It shipped defaulting to `false` (2026-09-09) for one turn, because the companion's own CI-gate
+ * test still composed its backend set from `mergeBackendDomainModules(...)` and defaulting to `true`
+ * would have turned a green gate red with no hand able to repair it. That caller was fixed the same
+ * day and the default flipped with it. The permissive default is gone deliberately: it protected one
+ * known caller and would have silently absolved every future one.
+ *
+ * Pass `false` only where the verdict is being REPORTED rather than gated — a summary line that
+ * prints {@link describeChartRegistrationVerdictCaveat} beside it is honest; a gate that returns
+ * quietly is not.
  */
-export function assertChartRegistrationAligned(report, errorPrefix = 'ChartRegistrationAlignment') {
+export function assertChartRegistrationAligned(report, errorPrefix = 'ChartRegistrationAlignment', requireVouchedVerdict = true) {
+    if (requireVouchedVerdict && report.verdict === ChartRegistrationAlignmentVerdict.CANNOT_VOUCH) {
+        throw new Error(`${errorPrefix}: refusing to report alignment. `
+            + describeChartRegistrationVerdictCaveat(report));
+    }
     if (report.unregisteredFrontendCharts.length === 0)
         return;
     const lines = report.unregisteredFrontendCharts.map((r) => `  - ${r.resourceType}.${r.chartViewRef} → chartDefinition.ref '${r.chartDefinitionRef}' has no backend chartDefinitions registration`);

package/dist/esm/config/frontend/chart-registration-alignment.shared.js.map

@@ -1 +1 @@
-{"version":3,"file":"chart-registration-alignment.shared.js","sourceRoot":"","sources":["../../../../../src/config/frontend/chart-registration-alignment.shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;oEAqBoE;AAEpE;;;;;;GAMG;AACH,MAAM,UAAU,0BAA0B,CAAC,MAAc;IACvD,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC;AACvB,CAAC;AA2BD;;;;GAIG;AACH,MAAM,UAAU,iCAAiC,CAAC,MAGjD;IACC,MAAM,iBAAiB,GAAG,MAAM,CAAC,qBAAqB,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAC;IACvF,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAC9C,MAAM,WAAW,GAAG,IAAI,GAAG,CACzB,MAAM,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,0BAA0B,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CACtF,CAAC;IAEF,MAAM,0BAA0B,GAAG,MAAM,CAAC,iBAAiB,CAAC,MAAM,CAChE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CACzE,CAAC;IAEF,MAAM,mBAAmB,GAAG;QAC1B,GAAG,IAAI,GAAG,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;KACrE,CAAC;IAEF,OAAO,EAAE,0BAA0B,EAAE,mBAAmB,EAAE,CAAC;AAC7D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,8BAA8B,CAC5C,MAAwC,EACxC,WAAW,GAAG,4BAA4B;IAE1C,IAAI,MAAM,CAAC,0BAA0B,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAC3D,MAAM,KAAK,GAAG,MAAM,CAAC,0BAA0B,CAAC,GAAG,CACjD,CAAC,CAAC,EAAE,EAAE,CACJ,OAAO,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC,YAAY,2BAA2B,CAAC,CAAC,kBAAkB,gDAAgD,CACzI,CAAC;IACF,MAAM,IAAI,KAAK,CACb,GAAG,WAAW,KAAK,MAAM,CAAC,0BAA0B,CAAC,MAAM,0HAA0H;QACnL,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;QACvB,gGAAgG,CACnG,CAAC;AACJ,CAAC","sourcesContent":["/** ──────────────────────────────────────────────────────────────\n * Chart registration alignment (drift guard)\n *\n * A resource-owned chart must be wired on BOTH sides:\n *   - FRONTEND: authored in `ResourceUIBehaviorConfig.chartViews[].chartDefinition`\n *     (frontend-only — the backend cannot import it), and\n *   - BACKEND: registered via `BackendDomainModule.chartDefinitions`, which feeds\n *     the backend `ChartRegistry` so `POST /charts/:ref/data` can execute.\n *\n * A frontend chartView whose `chartDefinition.ref` has NO backend registration\n * produces a silent runtime 404 (`chart_not_found`) — the host renders but the\n * data fetch fails. This module is the pure, framework-general comparator that a\n * build-time / CLI guard uses to catch that drift before it ships.\n *\n * ## Join key\n * The comparison key is `chartView.chartDefinition.ref` (the execution ref the\n * frontend runtime sends), NOT the outer `chartView.ref` (the view identity).\n *\n * This module is import-safe (pure functions + types, no frontend-lib /\n * backend-lib deps) so it can run from the companion subprocess, a CLI audit,\n * and unit tests alike.\n * ────────────────────────────────────────────────────────────── */\n\n/**\n * Normalize a chart execution reference to its canonical registry key. This is\n * the SINGLE source of truth for ref normalization, shared by the backend\n * `ChartRegistry` (registration + lookup) and this alignment guard, so the two\n * can never diverge on whitespace and silently disagree about whether a chart is\n * registered.\n */\nexport function normalizeChartExecutionRef(rawRef: string): string {\n  return rawRef.trim();\n}\n\n/** One frontend chartView's registration identity (the drift-guard input). */\nexport interface FrontendChartRegistrationRef {\n  /** `chartView.chartDefinition.ref` — the execution/registry join key. */\n  chartDefinitionRef: string;\n  /** The resource type whose ui-behavior authored this chartView. */\n  resourceType: string;\n  /** `chartView.ref` — the view identity (for a precise, locatable error). */\n  chartViewRef: string;\n}\n\n/** The two-channel drift report. */\nexport interface ChartRegistrationAlignmentReport {\n  /**\n   * Frontend chartViews whose `chartDefinition.ref` has NO backend registration.\n   * FAIL channel — each one is a guaranteed runtime 404.\n   */\n  unregisteredFrontendCharts: FrontendChartRegistrationRef[];\n  /**\n   * Backend-registered chart refs referenced by NO frontend chartView. WARN\n   * channel — a backend-only chart is valid (e.g. a programmatic/API-only chart\n   * consumed directly via `/charts/:ref/data`), so this is never a hard failure.\n   */\n  orphanBackendCharts: string[];\n}\n\n/**\n * Compare the set of frontend chartView refs against the set of backend-registered\n * chart refs. Both sides are normalized via {@link normalizeChartExecutionRef}\n * before comparison so whitespace never causes a phantom mismatch.\n */\nexport function computeChartRegistrationAlignment(params: {\n  frontendChartRefs: FrontendChartRegistrationRef[];\n  backendRegisteredRefs: string[];\n}): ChartRegistrationAlignmentReport {\n  const normalizedBackend = params.backendRegisteredRefs.map(normalizeChartExecutionRef);\n  const backendSet = new Set(normalizedBackend);\n  const frontendSet = new Set(\n    params.frontendChartRefs.map((r) => normalizeChartExecutionRef(r.chartDefinitionRef)),\n  );\n\n  const unregisteredFrontendCharts = params.frontendChartRefs.filter(\n    (r) => !backendSet.has(normalizeChartExecutionRef(r.chartDefinitionRef)),\n  );\n\n  const orphanBackendCharts = [\n    ...new Set(normalizedBackend.filter((ref) => !frontendSet.has(ref))),\n  ];\n\n  return { unregisteredFrontendCharts, orphanBackendCharts };\n}\n\n/**\n * Throw a verbose, locatable error if any frontend chartView is unregistered\n * backend-side. Only the FAIL channel throws; `orphanBackendCharts` (WARN) never\n * throws. Use in the `--strict` path of the CLI audit / a CI gate.\n */\nexport function assertChartRegistrationAligned(\n  report: ChartRegistrationAlignmentReport,\n  errorPrefix = 'ChartRegistrationAlignment',\n): void {\n  if (report.unregisteredFrontendCharts.length === 0) return;\n  const lines = report.unregisteredFrontendCharts.map(\n    (r) =>\n      `  - ${r.resourceType}.${r.chartViewRef} → chartDefinition.ref '${r.chartDefinitionRef}' has no backend chartDefinitions registration`,\n  );\n  throw new Error(\n    `${errorPrefix}: ${report.unregisteredFrontendCharts.length} chart view(s) reference a chart that is NOT registered backend-side (each would 404 with chart_not_found at runtime):\\n` +\n      `${lines.join('\\n')}\\n` +\n      `Fix: add the shared ChartDefinition to the owning backend module's \\`chartDefinitions\\` array.`,\n  );\n}\n"]}
+{"version":3,"file":"chart-registration-alignment.shared.js","sourceRoot":"","sources":["../../../../../src/config/frontend/chart-registration-alignment.shared.ts"],"names":[],"mappings":"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","sourcesContent":["/** ──────────────────────────────────────────────────────────────\n * Chart registration alignment (drift guard)\n *\n * A resource-owned chart must be wired on BOTH sides:\n *   - FRONTEND: authored in `ResourceUIBehaviorConfig.chartViews[].chartDefinition`\n *     (frontend-only — the backend cannot import it), and\n *   - BACKEND: registered via `BackendDomainModule.chartDefinitions`, which feeds\n *     the backend `ChartRegistry` so `POST /charts/:ref/data` can execute.\n *\n * A frontend chartView whose `chartDefinition.ref` has NO backend registration\n * produces a runtime 404 (`chart_not_found`) — the host renders but the data\n * fetch fails. This module is the pure, framework-general comparator that a\n * build-time / CLI guard uses to catch that drift before it ships.\n *\n * ## The failure is LOUD but LATE, and the distinction decides what this guard is for\n * Earlier revisions of this file, the CLI verb and the CI workflow all called that 404\n * \"silent\". Measured on the runtime path, it is not: `ChartView` renders `ChartErrorState`\n * (an error card with a retry action), a standalone chart page also raises the global error\n * toast (`localErrorOnly` is only set by EMBEDDED hosts), and the backend answers a NOT_FOUND\n * whose context names the resolved ref.\n *\n * So this guard does not exist to make an invisible failure visible. It exists because the\n * failure is only visible to whoever OPENS the chart — a chart on a rarely-visited surface\n * ships broken and is discovered by a user. Everything here moves that discovery to authoring\n * time. Do not restate \"silent\"; it overstates the defect and misdescribes what is being fixed.\n *\n * ## Why this is a comparator and not a boot refusal\n * Neither runtime process can perform this join, so there is no boot to refuse at:\n *   - the BACKEND cannot see `chartViews` — it lives on `ResourceUIBehaviorConfig` in `.tsx`\n *     ui-behavior modules the backend cannot import, which is why the dev companion needs a\n *     dedicated introspection SUBPROCESS to materialize it (and why the backend module slot\n *     exists as a second wiring in the first place);\n *   - the FRONTEND has `chartViews` but never receives the backend's registered set — nothing\n *     serializes `ChartRegistry.getRegisteredChartRefs()` into any boot payload.\n * The only process that sees both is the companion, which is where every channel that runs\n * this comparator lives: `POST /api/companion/charts/audit`, `wildo charts audit`, and the CI\n * gate. The BACKEND-visible half of chart wiring — a chart naming a resource type that does\n * not exist — is refused at boot by `ChartRegistryBackendService.registerChart`.\n *\n * ## The backend set has TWO possible sources, and only ONE of them is the answer\n * `ApplicationInitializationConfig.chartDefinitions` — the array `StartApplicationBackendService`\n * actually registers — is assembled as\n * `overrides.chartDefinitions ?? input.backendRegistry.chartDefinitions`\n * (`buildApplicationInitializationConfigFromModules`). That is a REPLACE, not a merge. So an\n * application supplying `overrides.chartDefinitions` makes the module DECLARATIONS an arbitrary set\n * with no relation to what registers: it may drop a declared chart (a comparison built on the\n * declarations then reports ALIGNED while the chart 404s) and it may add one that is not declared\n * (the same comparison then reports a false FAIL).\n *\n * Hence {@link ChartRegistrationBackendRefsProvenance}. A caller must say WHICH set it brought, and\n * a comparison built on the declarations yields\n * {@link ChartRegistrationAlignmentVerdict.CANNOT_VOUCH} — never `ALIGNED`. A guard that says \"I\n * cannot answer\" beats one that answers about a different population; that is the same class as a\n * green report read off a stale artifact\n * (`.claude/rules/staleness-presents-as-a-logic-defect.md`).\n *\n * ## The effective set IS reachable — no contract change is needed\n * An earlier note on `ChartRegistryBackendService.getRegisteredChartRefs` said closing this \"needs\n * the overrides to reach the companion, which the `companion-exports` contract does not currently\n * carry\". **That was wrong, and the contract had already answered it**:\n * `BackendCompanionExports.buildApplicationInitializationConfig()` is REQUIRED, is the same pure\n * builder backend startup uses, starts nothing, and its JSDoc says in as many words that \"tooling\n * must not reconstruct selected runtime capabilities from lower-level registries\". Composing the\n * backend side from `mergeBackendDomainModules(...)` was exactly that reconstruction.\n *\n * Residual, stated rather than hidden: the companion calls the builder with NO host overrides, so it\n * sees the set the APPLICATION declares. A HOST that passed `chartDefinitions` in its own overrides\n * would diverge — neither dogfood host does (both pass only `customControllers`, `container`,\n * `serviceIdentifier`, `providerRuntime`), and a host-level chart override has no use case today.\n *\n * ## Join key\n * The comparison key is `chartView.chartDefinition.ref` (the execution ref the\n * frontend runtime sends), NOT the outer `chartView.ref` (the view identity).\n *\n * This module is import-safe (pure functions + types, no frontend-lib /\n * backend-lib deps) so it can run from the companion subprocess, a CLI audit,\n * and unit tests alike.\n * ────────────────────────────────────────────────────────────── */\n\n/**\n * Normalize a chart execution reference to its canonical registry key. This is\n * the SINGLE source of truth for ref normalization, shared by the backend\n * `ChartRegistry` (registration + lookup) and this alignment guard, so the two\n * can never diverge on whitespace and silently disagree about whether a chart is\n * registered.\n */\nexport function normalizeChartExecutionRef(rawRef: string): string {\n  return rawRef.trim();\n}\n\n/** One frontend chartView's registration identity (the drift-guard input). */\nexport interface FrontendChartRegistrationRef {\n  /** `chartView.chartDefinition.ref` — the execution/registry join key. */\n  chartDefinitionRef: string;\n  /** The resource type whose ui-behavior authored this chartView. */\n  resourceType: string;\n  /** `chartView.ref` — the view identity (for a precise, locatable error). */\n  chartViewRef: string;\n}\n\n/**\n * WHERE a caller's `backendRegisteredRefs` came from — the input that decides whether this\n * comparison is about the population that actually registers.\n *\n * A closed vocabulary with a named home rather than a boolean, because the two members are not\n * \"good/bad\": each names a concrete assembly step, and the reason one of them cannot be vouched for\n * is a specific line of code (`overrides.chartDefinitions ?? input.backendRegistry.chartDefinitions`)\n * that a `trusted: false` flag could never carry.\n */\nexport enum ChartRegistrationBackendRefsProvenance {\n  /**\n   * From `BackendCompanionExports.buildApplicationInitializationConfig().chartDefinitions` — the\n   * exact array `StartApplicationBackendService` registers, with any\n   * `ApplicationInitializationOverrides.chartDefinitions` already applied. The only provenance that\n   * supports a vouched verdict.\n   */\n  EFFECTIVE_INITIALIZATION_CONFIG = 'effective-initialization-config',\n  /**\n   * From `mergeBackendDomainModules(...).chartDefinitions` — what the modules DECLARE. Equal to the\n   * effective set only while no application supplies `overrides.chartDefinitions`; nothing in this\n   * set records whether one does, which is why a caller supplying it gets `CANNOT_VOUCH` rather\n   * than a verdict.\n   *\n   * This is also what an ABSENT provenance means. The permissive reading was deliberately NOT\n   * chosen for the default: a caller that has not thought about which set it brought has, by\n   * definition, brought the one it could reach without asking.\n   */\n  MODULE_DECLARATIONS = 'module-declarations',\n}\n\n/** What the comparison is entitled to conclude, given where its backend set came from. */\nexport enum ChartRegistrationAlignmentVerdict {\n  /** Every frontend chartView resolves against the set that actually registers. */\n  ALIGNED = 'aligned',\n  /** At least one frontend chartView has no registration in the set that actually registers. */\n  MISALIGNED = 'misaligned',\n  /**\n   * The comparison ran and its channels are populated, but the backend set was not the effective\n   * one — so NEITHER a clean nor a dirty result may be reported as fact. Report the channels as\n   * evidence; do not report alignment.\n   */\n  CANNOT_VOUCH = 'cannot-vouch',\n}\n\n/** The two-channel drift report. */\nexport interface ChartRegistrationAlignmentReport {\n  /** Echoed so a consumer renders, logs or gates on the same answer the comparison used. */\n  backendRefsProvenance: ChartRegistrationBackendRefsProvenance;\n  /** What this comparison is entitled to conclude. See {@link ChartRegistrationAlignmentVerdict}. */\n  verdict: ChartRegistrationAlignmentVerdict;\n  /**\n   * Frontend chartViews whose `chartDefinition.ref` has NO backend registration.\n   * FAIL channel — each one is a guaranteed runtime 404.\n   */\n  unregisteredFrontendCharts: FrontendChartRegistrationRef[];\n  /**\n   * Backend-registered chart refs referenced by NO frontend chartView. WARN\n   * channel — a backend-only chart is valid (e.g. a programmatic/API-only chart\n   * consumed directly via `/charts/:ref/data`), so this is never a hard failure.\n   */\n  orphanBackendCharts: string[];\n}\n\n/**\n * Compare the set of frontend chartView refs against the set of backend-registered\n * chart refs. Both sides are normalized via {@link normalizeChartExecutionRef}\n * before comparison so whitespace never causes a phantom mismatch.\n */\nexport function computeChartRegistrationAlignment(params: {\n  frontendChartRefs: FrontendChartRegistrationRef[];\n  backendRegisteredRefs: string[];\n  /**\n   * WHERE `backendRegisteredRefs` came from. Optional so that adding it did not red-line an\n   * existing caller this change could not reach — absence is read as\n   * {@link ChartRegistrationBackendRefsProvenance.MODULE_DECLARATIONS}, i.e. the answer that\n   * yields `CANNOT_VOUCH`, never the permissive one.\n   */\n  backendRefsProvenance?: ChartRegistrationBackendRefsProvenance;\n}): ChartRegistrationAlignmentReport {\n  const normalizedBackend = params.backendRegisteredRefs.map(normalizeChartExecutionRef);\n  const backendSet = new Set(normalizedBackend);\n  const frontendSet = new Set(\n    params.frontendChartRefs.map((r) => normalizeChartExecutionRef(r.chartDefinitionRef)),\n  );\n\n  const unregisteredFrontendCharts = params.frontendChartRefs.filter(\n    (r) => !backendSet.has(normalizeChartExecutionRef(r.chartDefinitionRef)),\n  );\n\n  const orphanBackendCharts = [\n    ...new Set(normalizedBackend.filter((ref) => !frontendSet.has(ref))),\n  ];\n\n  const backendRefsProvenance =\n    params.backendRefsProvenance ?? ChartRegistrationBackendRefsProvenance.MODULE_DECLARATIONS;\n\n  const verdict =\n    backendRefsProvenance !== ChartRegistrationBackendRefsProvenance.EFFECTIVE_INITIALIZATION_CONFIG\n      ? ChartRegistrationAlignmentVerdict.CANNOT_VOUCH\n      : unregisteredFrontendCharts.length > 0\n        ? ChartRegistrationAlignmentVerdict.MISALIGNED\n        : ChartRegistrationAlignmentVerdict.ALIGNED;\n\n  return { backendRefsProvenance, verdict, unregisteredFrontendCharts, orphanBackendCharts };\n}\n\n/**\n * Render the provenance caveat, or `undefined` when the report may be taken at face value.\n *\n * Exists so the two surfaces a person reads — the CLI's summary line and the thrown gate message —\n * cannot word this differently, or one of them forget it. A caveat that appears on one surface is\n * the state this whole change is repairing.\n */\nexport function describeChartRegistrationVerdictCaveat(\n  report: ChartRegistrationAlignmentReport,\n): string | undefined {\n  if (report.verdict !== ChartRegistrationAlignmentVerdict.CANNOT_VOUCH) return undefined;\n  return (\n    'This comparison used the module DECLARATIONS '\n    + `(provenance: ${report.backendRefsProvenance}), not the set the backend registers. `\n    + 'An application supplying `ApplicationInitializationOverrides.chartDefinitions` REPLACES the '\n    + 'declared array, so a dropped chart would read as aligned here and 404 at runtime. '\n    + 'Fix: take the backend refs from '\n    + '`backendCompanionExports.buildApplicationInitializationConfig().chartDefinitions` and pass '\n    + `backendRefsProvenance: ${ChartRegistrationBackendRefsProvenance.EFFECTIVE_INITIALIZATION_CONFIG}.`\n  );\n}\n\n/**\n * Throw a verbose, locatable error if any frontend chartView is unregistered\n * backend-side. Only the FAIL channel throws; `orphanBackendCharts` (WARN) never\n * throws. Use in the `--strict` path of the CLI audit / a CI gate.\n *\n * ## `requireVouchedVerdict` defaults to `true`, and that is the point of the parameter\n *\n * A clean FAIL channel is only evidence of alignment when the backend set was the EFFECTIVE one — a\n * chart dropped by an `ApplicationInitializationOverrides.chartDefinitions` override is registered\n * nowhere and declared everywhere, so a comparison against the DECLARATIONS reports ALIGNED about a\n * population the application does not run. So this refuses a\n * {@link ChartRegistrationAlignmentVerdict.CANNOT_VOUCH} report rather than returning quietly, and a\n * caller has to say deliberately that it does not want that.\n *\n * It shipped defaulting to `false` (2026-09-09) for one turn, because the companion's own CI-gate\n * test still composed its backend set from `mergeBackendDomainModules(...)` and defaulting to `true`\n * would have turned a green gate red with no hand able to repair it. That caller was fixed the same\n * day and the default flipped with it. The permissive default is gone deliberately: it protected one\n * known caller and would have silently absolved every future one.\n *\n * Pass `false` only where the verdict is being REPORTED rather than gated — a summary line that\n * prints {@link describeChartRegistrationVerdictCaveat} beside it is honest; a gate that returns\n * quietly is not.\n */\nexport function assertChartRegistrationAligned(\n  report: ChartRegistrationAlignmentReport,\n  errorPrefix = 'ChartRegistrationAlignment',\n  requireVouchedVerdict = true,\n): void {\n  if (requireVouchedVerdict && report.verdict === ChartRegistrationAlignmentVerdict.CANNOT_VOUCH) {\n    throw new Error(\n      `${errorPrefix}: refusing to report alignment. `\n      + describeChartRegistrationVerdictCaveat(report),\n    );\n  }\n  if (report.unregisteredFrontendCharts.length === 0) return;\n  const lines = report.unregisteredFrontendCharts.map(\n    (r) =>\n      `  - ${r.resourceType}.${r.chartViewRef} → chartDefinition.ref '${r.chartDefinitionRef}' has no backend chartDefinitions registration`,\n  );\n  throw new Error(\n    `${errorPrefix}: ${report.unregisteredFrontendCharts.length} chart view(s) reference a chart that is NOT registered backend-side (each would 404 with chart_not_found at runtime):\\n` +\n      `${lines.join('\\n')}\\n` +\n      `Fix: add the shared ChartDefinition to the owning backend module's \\`chartDefinitions\\` array.`,\n  );\n}\n"]}

package/dist/esm/config/frontend/navigation.shared.schemas.d.ts

@@ -153,7 +153,7 @@ export declare enum NavigationZoneName {
     SECONDARY = "secondary",
     /**
      * Persistent supplementary content. Reference panels, docs, notes, threads.
-     * Only exists if declared in config. Usually hidden by default (`defaultVisible: false`).
+     * Only exists if declared in config, and starts hidden.
      * Activated by `split` with `persistent: true` or explicit user toggle.
      * Typical use: Slack thread panel, VS Code terminal, documentation sidebar.
      */
@@ -414,10 +414,25 @@ export type ZoneAppearance = z.infer<typeof ZoneAppearanceSchema>;
  * which transition fires for each operation, how content appears,
  * and how the zone responds to viewport changes.
  *
- * Note: `minWidth`, `maxWidth`, `defaultVisible`, `onEmpty`,
- * and `responsiveCollapse` are only meaningful for secondary and companion zones.
- * Primary never collapses, never empties, and takes remaining space.
+ * Note: `minWidth`, `maxWidth`, `onEmpty` and `responsiveCollapse` are only meaningful for
+ * secondary and companion zones. Primary never collapses, never empties, and takes remaining space.
  * Setting these on primary has no effect.
+ *
+ * ## Every field here is READ by the runtime, and that was checked rather than assumed (#211)
+ *
+ * | field | the reader |
+ * |---|---|
+ * | `contentModel` | `NavigationContentAreas.tsx` (TABBED detection) + `zone-visible-entry.ts` |
+ * | `transitions` | `navigation-policy-resolver.service.ts` |
+ * | `appearance` | `useNavigationController.ts` (`appearance.split`) + the policy resolver |
+ * | `minWidth` / `maxWidth` | `NavigationContentAreas.tsx` drag constraints, both split branches |
+ * | `onEmpty` | `zone-empty-behavior.ts` |
+ * | `responsiveCollapse` | `navigation-policy-resolver.service.ts` |
+ *
+ * `defaultVisible` was REMOVED by that audit: nothing read it, and its only documented meaning was
+ * "defaults to `true` when `split.autoSplit` is `true`" — a field defined in terms of another field
+ * that was also dead. What it was reaching for is `onEmpty`, which every current layout already uses
+ * (`zoneOccupiesSpaceWhenEmpty`) and which the runtime genuinely reads.
  */
 export declare const ZoneConfigSchema: z.ZodObject<{
     contentModel: z.ZodDefault<z.ZodEnum<typeof NavigationZoneContentModel>>;
@@ -436,7 +451,6 @@ export declare const ZoneConfigSchema: z.ZodObject<{
     }, z.core.$strip>>;
     minWidth: z.ZodOptional<z.ZodNumber>;
     maxWidth: z.ZodOptional<z.ZodNumber>;
-    defaultVisible: z.ZodOptional<z.ZodBoolean>;
     onEmpty: z.ZodOptional<z.ZodEnum<typeof ZoneEmptyBehavior>>;
     responsiveCollapse: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof ResponsiveCollapseMode>, z.ZodRecord<z.ZodEnum<typeof ViewportBreakpoint> & z.core.$partial, z.ZodEnum<typeof ResponsiveCollapseMode>>]>>;
 }, z.core.$strip>;
@@ -516,7 +530,6 @@ export type FromOverlayConfig = z.infer<typeof FromOverlayConfigSchema>;
  */
 export declare const CompanionSplitConfigSchema: z.ZodObject<{
     ratio: z.ZodDefault<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
-    orientation: z.ZodDefault<z.ZodEnum<typeof DisplayDirection>>;
     resizable: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
 export type CompanionSplitConfig = z.infer<typeof CompanionSplitConfigSchema>;
@@ -528,25 +541,21 @@ export type CompanionSplitConfig = z.infer<typeof CompanionSplitConfigSchema>;
  *
  * @example
  * split: {
- *   autoSplit: true,                                    // LIST pre-splits when primary.read = NavigationTransition.SPLIT
  *   ratio: [40, 60],                                    // 40% primary, 60% secondary
  *   orientation: DisplayDirection.VERTICAL,              // side-by-side
  *   resizable: true,                                     // divider is draggable
  *   companion: {
  *     ratio: [70, 30],                                   // companion takes 30%
- *     orientation: DisplayDirection.HORIZONTAL,         // bottom panel
- *     resizable: true,
+ *     resizable: true,                                   // its own divider is draggable
  *   },
  * }
  */
 export declare const SplitConfigSchema: z.ZodObject<{
-    autoSplit: z.ZodDefault<z.ZodBoolean>;
     ratio: z.ZodDefault<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
     orientation: z.ZodDefault<z.ZodEnum<typeof DisplayDirection>>;
     resizable: z.ZodDefault<z.ZodBoolean>;
     companion: z.ZodOptional<z.ZodObject<{
         ratio: z.ZodDefault<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
-        orientation: z.ZodDefault<z.ZodEnum<typeof DisplayDirection>>;
         resizable: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
@@ -603,7 +612,7 @@ export type ViewportOverride = z.infer<typeof ViewportOverrideSchema>;
  *   },
  *   appLevel: { transitions: { list: NavigationTransition.REPLACE, create: NavigationTransition.OVERLAY } },
  *   fromOverlay: { transitions: { read: NavigationTransition.PROMOTE } },
- *   split: { autoSplit: true, ratio: [40, 60] },
+ *   split: { ratio: [40, 60] },
  *   maxDepth: 2,
  * };
  */
@@ -674,7 +683,6 @@ export declare const NavigationLayoutSchema: z.ZodObject<{
             }, z.core.$strip>>;
             minWidth: z.ZodOptional<z.ZodNumber>;
             maxWidth: z.ZodOptional<z.ZodNumber>;
-            defaultVisible: z.ZodOptional<z.ZodBoolean>;
             onEmpty: z.ZodOptional<z.ZodEnum<typeof ZoneEmptyBehavior>>;
             responsiveCollapse: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof ResponsiveCollapseMode>, z.ZodRecord<z.ZodEnum<typeof ViewportBreakpoint> & z.core.$partial, z.ZodEnum<typeof ResponsiveCollapseMode>>]>>;
         }, z.core.$strip>;
@@ -695,7 +703,6 @@ export declare const NavigationLayoutSchema: z.ZodObject<{
             }, z.core.$strip>>;
             minWidth: z.ZodOptional<z.ZodNumber>;
             maxWidth: z.ZodOptional<z.ZodNumber>;
-            defaultVisible: z.ZodOptional<z.ZodBoolean>;
             onEmpty: z.ZodOptional<z.ZodEnum<typeof ZoneEmptyBehavior>>;
             responsiveCollapse: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof ResponsiveCollapseMode>, z.ZodRecord<z.ZodEnum<typeof ViewportBreakpoint> & z.core.$partial, z.ZodEnum<typeof ResponsiveCollapseMode>>]>>;
         }, z.core.$strip>>;
@@ -716,7 +723,6 @@ export declare const NavigationLayoutSchema: z.ZodObject<{
             }, z.core.$strip>>;
             minWidth: z.ZodOptional<z.ZodNumber>;
             maxWidth: z.ZodOptional<z.ZodNumber>;
-            defaultVisible: z.ZodOptional<z.ZodBoolean>;
             onEmpty: z.ZodOptional<z.ZodEnum<typeof ZoneEmptyBehavior>>;
             responsiveCollapse: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof ResponsiveCollapseMode>, z.ZodRecord<z.ZodEnum<typeof ViewportBreakpoint> & z.core.$partial, z.ZodEnum<typeof ResponsiveCollapseMode>>]>>;
         }, z.core.$strip>>;
@@ -748,13 +754,11 @@ export declare const NavigationLayoutSchema: z.ZodObject<{
         }>>, unknown>>;
     }, z.core.$strip>>;
     split: z.ZodOptional<z.ZodObject<{
-        autoSplit: z.ZodDefault<z.ZodBoolean>;
         ratio: z.ZodDefault<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
         orientation: z.ZodDefault<z.ZodEnum<typeof DisplayDirection>>;
         resizable: z.ZodDefault<z.ZodBoolean>;
         companion: z.ZodOptional<z.ZodObject<{
             ratio: z.ZodDefault<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
-            orientation: z.ZodDefault<z.ZodEnum<typeof DisplayDirection>>;
             resizable: z.ZodDefault<z.ZodBoolean>;
         }, z.core.$strip>>;
     }, z.core.$strip>>;

package/dist/esm/config/frontend/navigation.shared.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"navigation.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../../src/config/frontend/navigation.shared.schemas.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"navigation.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../../src/config/frontend/navigation.shared.schemas.ts"],"names":[],"mappings":"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"}

package/dist/esm/config/frontend/navigation.shared.schemas.js

@@ -158,7 +158,7 @@ export var NavigationZoneName;
     NavigationZoneName["SECONDARY"] = "secondary";
     /**
      * Persistent supplementary content. Reference panels, docs, notes, threads.
-     * Only exists if declared in config. Usually hidden by default (`defaultVisible: false`).
+     * Only exists if declared in config, and starts hidden.
      * Activated by `split` with `persistent: true` or explicit user toggle.
      * Typical use: Slack thread panel, VS Code terminal, documentation sidebar.
      */
@@ -435,10 +435,25 @@ export const ZoneAppearanceSchema = z.object({
  * which transition fires for each operation, how content appears,
  * and how the zone responds to viewport changes.
  *
- * Note: `minWidth`, `maxWidth`, `defaultVisible`, `onEmpty`,
- * and `responsiveCollapse` are only meaningful for secondary and companion zones.
- * Primary never collapses, never empties, and takes remaining space.
+ * Note: `minWidth`, `maxWidth`, `onEmpty` and `responsiveCollapse` are only meaningful for
+ * secondary and companion zones. Primary never collapses, never empties, and takes remaining space.
  * Setting these on primary has no effect.
+ *
+ * ## Every field here is READ by the runtime, and that was checked rather than assumed (#211)
+ *
+ * | field | the reader |
+ * |---|---|
+ * | `contentModel` | `NavigationContentAreas.tsx` (TABBED detection) + `zone-visible-entry.ts` |
+ * | `transitions` | `navigation-policy-resolver.service.ts` |
+ * | `appearance` | `useNavigationController.ts` (`appearance.split`) + the policy resolver |
+ * | `minWidth` / `maxWidth` | `NavigationContentAreas.tsx` drag constraints, both split branches |
+ * | `onEmpty` | `zone-empty-behavior.ts` |
+ * | `responsiveCollapse` | `navigation-policy-resolver.service.ts` |
+ *
+ * `defaultVisible` was REMOVED by that audit: nothing read it, and its only documented meaning was
+ * "defaults to `true` when `split.autoSplit` is `true`" — a field defined in terms of another field
+ * that was also dead. What it was reaching for is `onEmpty`, which every current layout already uses
+ * (`zoneOccupiesSpaceWhenEmpty`) and which the runtime genuinely reads.
  */
 export const ZoneConfigSchema = z.object({
     /**
@@ -454,29 +469,38 @@ export const ZoneConfigSchema = z.object({
     appearance: ZoneAppearanceSchema.optional(),
     /**
      * Minimum pixel width when resizing. Constrains how far this side of the
-     * split divider can be dragged. Only meaningful for secondary and companion zones.
-     * Works in conjunction with `SplitConfigSchema.resizable`.
+     * split divider can be dragged. Only meaningful for secondary and companion zones, and only when
+     * that zone is resizable — `SplitConfigSchema.resizable` for secondary, `split.companion.resizable`
+     * for companion (independent flags).
+     *
+     * The pixel value is converted to a share of the content area and clamped to 5–70%. When OMITTED on
+     * a resizable zone the floor is 25% of the content area — or the zone's own ratio share, if that is
+     * smaller — never zero. A pane is never collapsed by dragging it: closing a pane is navigation.
+     *
+     * A declared `maxWidth` narrower than this floor lowers the floor to it. When the shown side panes ask
+     * for more than primary's 25% leaves, they shrink in proportion and none opens below its floor (a
+     * non-resizable pane's floor is 25%, or its own ratio share if smaller); primary opens at exactly 25%.
+     * The floors are pixels, so at a narrow window they may not fit together at all — they then give way
+     * to each other in proportion, and the smaller floor a pane opens at is its drag floor. Primary never
+     * gives way.
      */
     minWidth: z.number().positive().optional(),
     /**
      * Maximum pixel width when resizing. Constrains how far this side of the
-     * split divider can be dragged. Only meaningful for secondary and companion zones.
-     * Works in conjunction with `SplitConfigSchema.resizable`.
+     * split divider can be dragged. Only meaningful for secondary and companion zones, and only when
+     * that zone is resizable — `SplitConfigSchema.resizable` for secondary, `split.companion.resizable`
+     * for companion (independent flags).
+     *
+     * The pixel value is converted to a share of the content area and clamped to 5–70%. When OMITTED on
+     * a resizable zone the ceiling is whatever leaves the primary zone 25% of the content area.
      */
     maxWidth: z.number().positive().optional(),
     /**
-     * Whether this zone is visible on first render (before any transition targets it).
-     * - Primary: always visible (this field is ignored).
-     * - Secondary: defaults to `true` when `split.autoSplit` is `true`, `false` otherwise.
-     * - Companion: defaults to `false` (hidden until a `split` transition targets it or user toggles).
-     */
-    defaultVisible: z.boolean().optional(),
-    /**
-     * What happens when this zone's last content is dismissed (stack empty, last tab closed).
-     * - `ZoneEmptyBehavior.COLLAPSE` (default): zone hides, adjacent zones expand to fill.
-     * - `ZoneEmptyBehavior.EMPTY_STATE`: zone stays visible with placeholder ("Select an item to view details").
-     * Only meaningful for secondary and companion zones. Primary never empties.
-     */
+   * What happens when this zone's last content is dismissed (stack empty, last tab closed).
+   * - `ZoneEmptyBehavior.COLLAPSE` (default): zone hides, adjacent zones expand to fill.
+   * - `ZoneEmptyBehavior.EMPTY_STATE`: zone stays visible with placeholder ("Select an item to view details").
+   * Only meaningful for secondary and companion zones. Primary never empties.
+   */
     onEmpty: z.enum(ZoneEmptyBehavior).optional(),
     /**
      * Responsive collapse rules: what happens when viewport shrinks below the zone's breakpoint.
@@ -560,13 +584,6 @@ export const CompanionSplitConfigSchema = z.object({
      * @default [70, 30]
      */
     ratio: z.tuple([z.number(), z.number()]).default([70, 30]),
-    /**
-     * How the companion is positioned relative to the main area.
-     * - `DisplayDirection.VERTICAL`: companion on the side (left/right)
-     * - `DisplayDirection.HORIZONTAL`: companion below (bottom panel, e.g. VS Code terminal)
-     * @default DisplayDirection.VERTICAL
-     */
-    orientation: z.enum(DisplayDirection).default(DisplayDirection.VERTICAL),
     /**
      * Whether the companion split boundary is user-draggable.
      * When `true`, a draggable divider appears between the main area and the companion zone.
@@ -574,7 +591,17 @@ export const CompanionSplitConfigSchema = z.object({
      * @default false
      */
     resizable: z.boolean().default(false),
-});
+}); /*
+ * `orientation` was REMOVED here by the #211 audit, and it is the one removal that took a
+ * capability with it. It claimed the companion could sit BELOW the main area ("bottom panel, e.g.
+ * VS Code terminal") and nothing read it: all three zones share ONE `ResizablePanelGroup` whose
+ * `direction` comes from `split.orientation`, so an author writing HORIZONTAL here got a side panel
+ * and no diagnostic. Honouring it needs a NESTED panel group, with its own sizes, autoSaveId, drag
+ * constraints and responsive-collapse behaviour — a feature, not a field fix. Left as a declared
+ * lie it was worse than absent: it ships to application builders in the compiled
+ * `config-navigation` skill and answers with silence. Build the nested group first; the field comes
+ * back when something reads it.
+ */
 /**
  * Top-level split geometry — describes the physical relationship between zones.
  *
@@ -583,25 +610,16 @@ export const CompanionSplitConfigSchema = z.object({
  *
  * @example
  * split: {
- *   autoSplit: true,                                    // LIST pre-splits when primary.read = NavigationTransition.SPLIT
  *   ratio: [40, 60],                                    // 40% primary, 60% secondary
  *   orientation: DisplayDirection.VERTICAL,              // side-by-side
  *   resizable: true,                                     // divider is draggable
  *   companion: {
  *     ratio: [70, 30],                                   // companion takes 30%
- *     orientation: DisplayDirection.HORIZONTAL,         // bottom panel
- *     resizable: true,
+ *     resizable: true,                                   // its own divider is draggable
  *   },
  * }
  */
 export const SplitConfigSchema = z.object({
-    /**
-     * Whether the primary zone pre-splits on initial load.
-     * When `true` and `primary.transitions.read === NavigationTransition.SPLIT`, the secondary zone
-     * appears immediately with the first list item selected (or empty state).
-     * @default false
-     */
-    autoSplit: z.boolean().default(false),
     /**
      * Primary-to-secondary width/height ratio. Defines the initial proportion.
      * When `resizable` is `true`, user drag overrides this (persisted to localStorage).
@@ -676,7 +694,7 @@ export const ViewportOverrideSchema = z.object({
  *   },
  *   appLevel: { transitions: { list: NavigationTransition.REPLACE, create: NavigationTransition.OVERLAY } },
  *   fromOverlay: { transitions: { read: NavigationTransition.PROMOTE } },
- *   split: { autoSplit: true, ratio: [40, 60] },
+ *   split: { ratio: [40, 60] },
  *   maxDepth: 2,
  * };
  */
@@ -759,7 +777,7 @@ export const NavigationLayoutSchema = z.object({
      * Prevents overlay nesting — typically everything pushes within the overlay stack.
      */
     fromOverlay: FromOverlayConfigSchema.optional(),
-    /** Split geometry: ratios, orientations, autoSplit. */
+    /** Split geometry: ratios, orientation, resizability. */
     split: SplitConfigSchema.optional(),
     /**
      * Maximum push depth before the framework escalates to overlay.