@canonical/pragma-cli 0.38.0 → 0.42.0

package/src/kernel/packs/collect.ts

@@ -28,9 +28,11 @@ import type { ConfigLayers } from "../config/index.js";
 import { PragmaError } from "../error/index.js";
 import type { PackStoryRecord } from "../runtime/graphpack/stories.js";
 import type { CapabilityModule } from "../spec/index.js";
-import { compileStoryModule } from "./compile.js";
+import { compileStoryModule, storyOf } from "./compile.js";
 import { parsePackDefinition } from "./schema.js";
-import type { PackDefinition, PackEntry } from "./types.js";
+import { nounsNamed } from "./storyRules.js";
+import type { NounLookups, PackDefinition, PackEntry } from "./types.js";
+import { VERB_PATH_PATTERN } from "./types.js";
 import { assertUniqueVerbs } from "./uniqueness.js";
 
 /** One package-declared story that could not be used, and why. */
@@ -83,10 +85,14 @@ export function validateStories(
   const problems: StoryProblem[] = [];
   for (const record of records) {
     try {
-      const definition = parsePackDefinition(
-        JSON.parse(record.content),
-        record.source,
-      );
+      const migrated = migrateLegacyRecoveries(JSON.parse(record.content));
+      for (const hint of migrated.dropped) {
+        problems.push({
+          source: record.source,
+          message: `its story is kept, but its emptyRecovery.cli hint "${hint}" is not a verb path and was dropped; the key is now emptyRecovery.call.`,
+        });
+      }
+      const definition = parsePackDefinition(migrated.raw, record.source);
       if (reserved.has(definition.noun)) {
         problems.push({
           source: record.source,
@@ -112,6 +118,55 @@ export function validateStories(
   return { entries: [...byNoun.values()], problems };
 }
 
+/**
+ * Carry a PACKAGE story written against the old grammar forward.
+ *
+ * `emptyRecovery.cli: "sources update"` became `emptyRecovery.call: { verb }`. A
+ * project's own config gets the hard error that names the change — its author
+ * can fix it. A package is third-party data, often already built into a pack on
+ * disk, and refusing the key would cost the user the whole noun for the sake of
+ * a hint. So the old string becomes a call when it IS a verb path, and
+ * otherwise only the hint is dropped, reported once under `doctor`.
+ *
+ * @param raw - The parsed story JSON (untrusted; returned unchanged when it
+ *   carries no legacy key).
+ * @returns The story to validate, and the legacy hints that could not be kept.
+ */
+export function migrateLegacyRecoveries(raw: unknown): {
+  raw: unknown;
+  dropped: string[];
+} {
+  const dropped: string[] = [];
+  const migrateHalf = (half: unknown): unknown => {
+    const recovery = (
+      half as { emptyRecovery?: Record<string, unknown> } | null
+    )?.emptyRecovery;
+    if (typeof recovery?.cli !== "string") return half;
+    const { cli, ...rest } = recovery;
+    const keep = VERB_PATH_PATTERN.test(cli);
+    if (!keep) dropped.push(cli);
+    return {
+      ...(half as object),
+      emptyRecovery:
+        keep && rest.call === undefined
+          ? { ...rest, call: { verb: cli } }
+          : rest,
+    };
+  };
+  if (typeof raw !== "object" || raw === null) return { raw, dropped };
+  const story = raw as { list?: unknown; verbs?: unknown };
+  return {
+    raw: {
+      ...story,
+      ...(story.list === undefined ? {} : { list: migrateHalf(story.list) }),
+      ...(Array.isArray(story.verbs)
+        ? { verbs: story.verbs.map(migrateHalf) }
+        : {}),
+    },
+    dropped,
+  };
+}
+
 /**
  * The PROJECT's config-declared stories, weakest tier first.
  *
@@ -147,8 +202,8 @@ function projectStoryTiers(layers: ConfigLayers): readonly unknown[][] {
  *   carries (see {@link validateStories}); weaker than either config tier.
  * @returns The effective modules, uniqueness-checked.
  * @throws PragmaError CONFIG_ERROR on an invalid CONFIG story, a config story
- *   claiming an authored non-story noun, or a duplicate noun within one config
- *   tier. Package stories were already screened and never throw here.
+ *   claiming an authored non-story noun, a duplicate noun within one config
+ *   tier, or a config or shipped story naming a noun no story declares. Package stories were already screened and never throw here.
  */
 export function assembleEffectiveModules(
   staticModules: readonly CapabilityModule[],
@@ -171,6 +226,19 @@ export function assembleEffectiveModules(
   // Keyed by noun so the stronger tier REPLACES the weaker one — declaring a
   // story both on its pack and at the top level is a refinement, not an error.
   const dynamic = new Map<string, CapabilityModule>();
+  // The EFFECTIVE lookup of a noun, for shipped and project stories alike.
+  // Read at run time, so it sees every tier whatever order they compile in.
+  const nouns: NounLookups = (noun) => {
+    const module =
+      dynamic.get(noun) ?? staticModules.find((m) => m.name === noun);
+    const story = module && storyOf(module);
+    if (story && !story.definition.lookup) {
+      throw PragmaError.configError(
+        `The "${noun}" story in ${story.source.label} declares no lookup, so a filter that takes a ${noun} cannot resolve its value. Add a lookup to that story.`,
+      );
+    }
+    return story?.definition.lookup;
+  };
   for (const entry of packageStories) {
     dynamic.set(
       entry.definition.noun,
@@ -178,6 +246,7 @@ export function assembleEffectiveModules(
         entry.definition,
         { label: entry.source, origin: "package" },
         prefixes,
+        nouns,
       ),
     );
   }
@@ -205,6 +274,7 @@ export function assembleEffectiveModules(
           definition,
           { label: "config", origin: "config" },
           prefixes,
+          nouns,
         ),
       );
     }
@@ -212,12 +282,79 @@ export function assembleEffectiveModules(
 
   // Drop the static module for any noun a config story overrides, then append
   // the dynamic modules.
-  const kept = staticModules.filter((module) => !dynamic.has(module.name));
+  const kept = staticModules
+    .filter((module) => !dynamic.has(module.name))
+    // Recompiled so a shipped filter naming an overridden noun resolves
+    // through the project's lookup, as the project's own stories do.
+    .map((module) => {
+      const story = storyOf(module);
+      return story
+        ? compileStoryModule(
+            story.definition,
+            story.source,
+            story.prefixes,
+            nouns,
+          )
+        : module;
+    });
   const effective = [...kept, ...dynamic.values()];
+  // A noun some story declares without a lookup is refused when a filter on it
+  // is used, not here: only a noun NO story declares is a declaration error.
+  // Package stories never throw; {@link screenPackageStories} drops them.
+  for (const module of effective) {
+    const story = storyOf(module);
+    const unknown =
+      story && story.source.origin !== "package"
+        ? undeclaredNoun(story.definition, effective)
+        : undefined;
+    if (story && unknown) {
+      throw PragmaError.configError(
+        `Invalid story in ${story.source.label}: "${module.name}" names the noun "${unknown}", and no story declares it.`,
+      );
+    }
+  }
   assertUniqueVerbs(effective.flatMap((module) => [...module.verbs]));
   return effective;
 }
 
+/** The first noun a story names that no effective story declares. */
+function undeclaredNoun(
+  definition: PackDefinition,
+  effective: readonly CapabilityModule[],
+): string | undefined {
+  return nounsNamed(definition).find(
+    (noun) => !effective.some((m) => m.name === noun && storyOf(m)),
+  );
+}
+
+/**
+ * Drop each PACKAGE story naming a noun no effective story declares, reporting
+ * it — judged over the assembled set, so the order of declaration is nothing.
+ *
+ * @param effective - The assembled modules.
+ * @returns The modules kept, and one problem per story dropped.
+ */
+export function screenPackageStories(effective: readonly CapabilityModule[]): {
+  readonly modules: readonly CapabilityModule[];
+  readonly problems: readonly StoryProblem[];
+} {
+  const problems: StoryProblem[] = [];
+  const modules = effective.filter((module) => {
+    const story = storyOf(module);
+    const unknown =
+      story?.source.origin === "package"
+        ? undeclaredNoun(story.definition, effective)
+        : undefined;
+    if (!story || unknown === undefined) return true;
+    problems.push({
+      source: story.source.label,
+      message: `it names the noun "${unknown}", and no story declares it.`,
+    });
+    return false;
+  });
+  return { modules: problems.length === 0 ? effective : modules, problems };
+}
+
 /**
  * Load the effective modules for a real invocation: read the layered config and
  * the answering pack's carried stories, and merge both into the static
@@ -252,8 +389,11 @@ export async function loadEffectiveModules(
     activeStories(resolveSources(layers, cwd)),
     staticModules,
   );
+  const screened = screenPackageStories(
+    assembleEffectiveModules(staticModules, layers, entries),
+  );
   return {
-    modules: assembleEffectiveModules(staticModules, layers, entries),
-    problems,
+    modules: screened.modules,
+    problems: [...problems, ...screened.problems],
   };
 }

package/src/kernel/packs/compile.test.ts

@@ -12,6 +12,7 @@ import { RECOVERY_CLI_PREFIX } from "../../constants.js";
 import { buildFixtureRuntime } from "../../testing/helpers/packRuntime.js";
 import { PragmaError } from "../error/index.js";
 import type { PragmaRuntime } from "../runtime/types.js";
+import { declareVerbs } from "../spec/call.js";
 import { kebabCase } from "../spec/emitSurface.js";
 import type { VerbSpec } from "../spec/types.js";
 import { compileListable, compilePack, compileStoryModule } from "./compile.js";
@@ -362,19 +363,28 @@ describe("the grammar rejects what the compiler cannot build (PROTECTED)", () =>
     );
   });
 
-  it("rejects an emptyRecovery.cli that names a binary, and names the change", () => {
-    // The hint is rendered as `<consuming distribution> <cli>`, so a story
-    // carrying the old prefixed form would render `pragma pragma sources
-    // update`. Third-party packs are third-party DATA: they get an error that
-    // names the grammar change, not a silently doubled string.
-    const withCli = (cli: string) => ({
+  it("rejects the retired emptyRecovery.cli and a call that is a command line, naming the change", () => {
+    // A recovery names a CALL — a verb path and a param bag — and the consuming
+    // distribution spells it per surface. Third-party packs are third-party
+    // DATA: the old `cli` string gets an error that names the grammar change,
+    // and a command line in `verb` would render `pragma pragma sources update`.
+    const withRecovery = (recovery: Record<string, unknown>) => ({
       noun: "widget",
-      list: { ...listShape, emptyRecovery: { message: "None.", cli } },
+      list: { ...listShape, emptyRecovery: { message: "None.", ...recovery } },
     });
-    expect(parse(withCli(`${RECOVERY_CLI_PREFIX}sources update`))).toThrow(
-      /WITHOUT the binary name/,
+    expect(parse(withRecovery({ cli: "sources update" }))).toThrow(
+      /emptyRecovery\.cli is now emptyRecovery\.call/,
     );
-    expect(parse(withCli("sources update"))).not.toThrow();
+    expect(
+      parse(
+        withRecovery({
+          call: { verb: `${RECOVERY_CLI_PREFIX}sources update` },
+        }),
+      ),
+    ).toThrow(/a call names a verb path/);
+    expect(
+      parse(withRecovery({ call: { verb: "sources update" } })),
+    ).not.toThrow();
   });
 });
 
@@ -387,6 +397,11 @@ describe("pack compiler — SPARQL fetch path (PROTECTED)", () => {
       prefixes: PREFIXES,
       detail: "detailed",
     }));
+    // A miss recovers to `widget list`; the suite checks every call it renders
+    // against the declared verbs, and a fixture's are not the distribution's.
+    declareVerbs(
+      compilePack(WIDGET_PACK, distributionSource("bundled:widget"), PREFIXES),
+    );
   });
 
   afterAll(async () => {
@@ -563,6 +578,88 @@ describe("pack compiler — SPARQL fetch path (PROTECTED)", () => {
  * once, for the name resolve, and the resource listing reads that same
  * declaration. Nothing to keep in sync because there is nothing written twice.
  */
+describe("a lookup that declares no disclosure can still be asked for less", () => {
+  /** The widget lookup with every trace of disclosure removed. */
+  const BARE_PACK: PackDefinition = {
+    noun: "widget",
+    lookup: {
+      source: "sparql",
+      by: "ex:name",
+      type: "ex:Widget",
+      fields: [{ name: "description", property: "ex:description" }],
+      expand: [
+        {
+          name: "parts",
+          relation: "ex:hasPart",
+          select: [{ name: "name", property: "ex:name" }],
+        },
+      ],
+    },
+  };
+  const lookupVerb = compilePack(
+    BARE_PACK,
+    distributionSource("bundled:widget"),
+    PREFIXES,
+  ).find((v) => verbKey(v.path) === "widget lookup") as VerbSpec;
+
+  const lookupAt = async (options: {
+    detail?: "summary" | "standard" | "detailed";
+    configDetail?: "summary";
+  }) => {
+    const { rt } = await buildFixtureRuntime({
+      ttl: TTL,
+      prefixes: PREFIXES,
+      ...(options.detail ? { detail: options.detail } : {}),
+      ...(options.configDetail
+        ? { configDetail: options.configDetail, detailOrigin: "project" }
+        : {}),
+    });
+    try {
+      const out = (await lookupVerb.run(
+        { name: ["Button"] },
+        rt,
+      )) as LookupOutput;
+      return out.results.at(0);
+    } finally {
+      (await rt.store.get()).store.dispose();
+    }
+  };
+
+  it("advertises the canonical levels, defaulting to the fullest", () => {
+    expect(lookupVerb.disclosure).toEqual({
+      levels: ["summary", "standard", "detailed"],
+      default: "detailed",
+    });
+  });
+
+  it("answers exactly as before when nothing is asked for", async () => {
+    expect(await lookupAt({})).toEqual(await lookupAt({ detail: "detailed" }));
+    expect((await lookupAt({}))?.parts).toEqual([{ name: "Label" }]);
+  });
+
+  it("is the fields alone at summary, and everything from standard", async () => {
+    const summary = await lookupAt({ detail: "summary" });
+    expect(summary).toMatchObject({ description: "A button." });
+    expect(summary).not.toHaveProperty("parts");
+    expect(await lookupAt({ detail: "standard" })).toHaveProperty("parts");
+  });
+
+  it("follows a configured detail, as a declared disclosure always did", async () => {
+    expect(await lookupAt({ configDetail: "summary" })).not.toHaveProperty(
+      "parts",
+    );
+  });
+
+  it("leaves a declared disclosure exactly as its author wrote it", () => {
+    const declared = compilePack(
+      WIDGET_PACK,
+      distributionSource("bundled:widget"),
+      PREFIXES,
+    ).find((v) => verbKey(v.path) === "widget lookup");
+    expect(declared?.disclosure?.default).toBe("summary");
+  });
+});
+
 describe("declared listing (derived from the lookup's types)", () => {
   it("derives one collection per declared type, unweighted types at 1", () => {
     expect(

package/src/kernel/packs/compile.ts

@@ -14,7 +14,7 @@
  * facade).
  */
 
-import { BIN_NAME } from "../../constants.js";
+import { BIN_NAME, DETAIL_LEVELS } from "../../constants.js";
 import { PragmaError } from "../error/index.js";
 import { compactUri, DEFAULT_PREFIX_MAP } from "../render/index.js";
 import type { PragmaRuntime } from "../runtime/index.js";
@@ -42,8 +42,10 @@ import {
 import { storyIssues } from "./storyRules.js";
 import {
   EVERY_TIER,
+  type NounLookups,
   type PackDefinition,
   type PackFilter,
+  type PackGuidance,
   type PackList,
   type PackLookup,
   type PackPage,
@@ -74,17 +76,22 @@ const READ_CAPABILITY = {
  * @param definition - A validated pack definition.
  * @param source - Where the definition came from, for diagnostics.
  * @param prefixes - The merged prefix map used for display compaction.
+ * @param nouns - The other stories' lookups, which a filter naming a noun
+ *   resolves its values through. Read at run time only.
  * @returns The compiled verbs (list, extra verbs, lookup, sample), in order.
  */
 export function compilePack(
   definition: PackDefinition,
   source: StorySource,
   prefixes: Readonly<Record<string, string>>,
+  nouns?: NounLookups,
 ): VerbSpec[] {
   const { noun } = definition;
   const verbs: VerbSpec[] = [];
 
   const tierScope = definition.tierScope;
+  // A story may declare a lookup alone; a miss must not point at a `list` it lacks.
+  const hasList = definition.list !== undefined;
 
   if (definition.list) {
     verbs.push(
@@ -93,8 +100,10 @@ export function compilePack(
         verb: "list",
         summary: definition.description ?? `List ${noun} entries.`,
         doc: definition.toolDescription,
+        ...guidanceOf(definition),
         source,
         prefixes,
+        ...(nouns ? { nouns } : {}),
         ...(tierScope ? { tierScope } : {}),
       }),
     );
@@ -107,19 +116,24 @@ export function compilePack(
         verb: verb.verb,
         summary: verb.description ?? `List ${noun} ${verb.verb}.`,
         doc: verb.toolDescription,
+        ...guidanceOf(verb),
         source,
         prefixes,
+        ...(nouns ? { nouns } : {}),
         ...(tierScope ? { tierScope } : {}),
       }),
     );
   }
 
   if (definition.lookup) {
+    // Normalised ONCE, here, so the lookup verb, its run body, both fetch lanes
+    // and the sample all read the same declaration.
+    const lookup = withDisclosure(definition.lookup);
     verbs.push(
-      compileLookupVerb(definition.lookup, noun, source, prefixes, tierScope),
+      compileLookupVerb(lookup, noun, source, prefixes, hasList, tierScope),
     );
-    if (definition.lookup.sample) {
-      verbs.push(compileSampleVerb(definition.lookup, noun, source, prefixes));
+    if (lookup.sample) {
+      verbs.push(compileSampleVerb(lookup, noun, source, prefixes, hasList));
     }
   }
 
@@ -195,6 +209,7 @@ export function compileListable(
  * @param definition - A validated pack definition.
  * @param source - Where the definition came from, for diagnostics.
  * @param prefixes - The merged prefix map used for display compaction.
+ * @param nouns - As {@link compilePack}.
  * @returns The module: the compiled verbs plus the story's module-level data.
  * @throws PragmaError CONFIG_ERROR when the definition cannot be compiled,
  *   naming the field and the rule.
@@ -203,6 +218,7 @@ export function compileStoryModule(
   definition: PackDefinition,
   source: StorySource,
   prefixes: Readonly<Record<string, string>>,
+  nouns?: NounLookups,
 ): CapabilityModule {
   const issue = storyIssues(definition)[0];
   if (issue) {
@@ -211,17 +227,47 @@ export function compileStoryModule(
     );
   }
   const listable = compileListable(definition);
-  return {
+  const module: CapabilityModule = {
     name: definition.noun,
     story: true,
-    verbs: compilePack(definition, source, prefixes),
+    verbs: compilePack(definition, source, prefixes, nouns),
     colophon: definition.colophon,
     ...(listable ? { mcpListable: listable } : {}),
   };
+  compiledFrom.set(module, { definition, source, prefixes });
+  return module;
+}
+
+/** What each story module was compiled from. */
+const compiledFrom = new WeakMap<
+  CapabilityModule,
+  {
+    readonly definition: PackDefinition;
+    readonly source: StorySource;
+    readonly prefixes: Readonly<Record<string, string>>;
+  }
+>();
+
+/**
+ * The story a module was compiled from by {@link compileStoryModule}, with the
+ * source and prefixes it was compiled under; `undefined` for any other module.
+ */
+export function storyOf(
+  module: CapabilityModule,
+): ReturnType<(typeof compiledFrom)["get"]> {
+  return compiledFrom.get(module);
+}
+
+/** Carry a story half's declared guidance onto its verb, omitting what is absent. */
+function guidanceOf(half: PackGuidance): Pick<VerbSpec, "useWhen" | "example"> {
+  return {
+    ...(half.useWhen ? { useWhen: half.useWhen } : {}),
+    ...(half.example ? { example: half.example } : {}),
+  };
 }
 
 /** Presentation facts for one compiled list-shaped verb. */
-interface ListVerbMeta {
+interface ListVerbMeta extends PackGuidance {
   readonly noun: string;
   readonly verb: string;
   readonly summary: string;
@@ -229,6 +275,8 @@ interface ListVerbMeta {
   readonly doc?: string;
   readonly source: StorySource;
   readonly prefixes: Readonly<Record<string, string>>;
+  /** The other stories' lookups, for a filter that names a noun. */
+  readonly nouns?: NounLookups;
   /** The noun's declared tier hierarchy, when its entities are tiered. */
   readonly tierScope?: PackTierScope;
 }
@@ -246,6 +294,7 @@ function compileListVerb(shape: PackList, meta: ListVerbMeta): VerbSpec {
     path: [meta.noun, meta.verb],
     summary: meta.summary,
     ...(meta.doc ? { doc: meta.doc } : {}),
+    ...guidanceOf(meta),
     params,
     output: {
       formatters: listFormatters(shape, {
@@ -272,6 +321,8 @@ function compileListVerb(shape: PackList, meta: ListVerbMeta): VerbSpec {
       runBodies().then((m) =>
         m.makeListRun(shape, {
           source: meta.source,
+          prefixes: meta.prefixes,
+          ...(meta.nouns ? { nouns: meta.nouns } : {}),
           ...(meta.tierScope ? { tierScope: meta.tierScope } : {}),
         })(params, rt),
       ),
@@ -285,6 +336,7 @@ function compileLookupVerb(
   noun: string,
   source: StorySource,
   prefixes: Readonly<Record<string, string>>,
+  hasList: boolean,
   tierScope?: PackTierScope,
 ): VerbSpec {
   // Derive-by-default: every lookup completes its `<name>` from the pack index
@@ -319,6 +371,7 @@ function compileLookupVerb(
     summary:
       lookup.description ?? `Look up ${noun} details by name, IRI, or glob.`,
     ...(lookup.toolDescription ? { doc: lookup.toolDescription } : {}),
+    ...guidanceOf(lookup),
     params: [nameParam, ...tierParams(tierScope)],
     output: { formatters: lookupFormatters(lookup, prefixes) },
     examples: [
@@ -332,13 +385,18 @@ function compileLookupVerb(
           ]
         : []),
     ],
-    ...(lookup.disclosure
-      ? { disclosure: disclosureSpec(lookup.disclosure) }
-      : {}),
+    disclosure: disclosureSpec(lookup.disclosure),
     capability: READ_CAPABILITY,
     run: (params: Record<string, unknown>, rt: PragmaRuntime) =>
       runBodies().then((m) =>
-        m.makeLookupRun(lookup, noun, source, prefixes, tierScope)(params, rt),
+        m.makeLookupRun(
+          lookup,
+          noun,
+          source,
+          prefixes,
+          hasList,
+          tierScope,
+        )(params, rt),
       ),
   };
   return asVerb(verb);
@@ -374,6 +432,7 @@ function compileSampleVerb(
   noun: string,
   source: StorySource,
   prefixes: Readonly<Record<string, string>>,
+  hasList: boolean,
 ): VerbSpec {
   const defaultCount = sampleDefaultCount(lookup);
   const config = lookup.sample === true ? undefined : lookup.sample;
@@ -396,6 +455,7 @@ function compileSampleVerb(
       config?.description ??
       `Return randomly selected complete ${noun} entries as exemplars.`,
     ...(config?.toolDescription ? { doc: config.toolDescription } : {}),
+    ...guidanceOf(config ?? {}),
     params: countParam,
     output: { formatters: sampleFormatters(lookup, noun, prefixes) },
     examples: [
@@ -411,12 +471,41 @@ function compileSampleVerb(
           source,
           prefixes,
           defaultCount,
+          hasList,
         )(params, rt),
       ),
   };
   return asVerb(verb);
 }
 
+/**
+ * Give a lookup that declares no disclosure the canonical ladder: default
+ * `detailed` (so its default answer is unchanged) and untagged expands from
+ * `standard` (so `summary` is the fields alone, and `standard` equals
+ * `detailed`). A declared disclosure is returned as written.
+ */
+function withDisclosure(lookup: PackLookup): PackLookup {
+  if (lookup.disclosure) return lookup;
+  return {
+    ...lookup,
+    disclosure: { levels: [...DETAIL_LEVELS], default: IMPUTED_DEFAULT_LEVEL },
+    ...(lookup.expand
+      ? {
+          expand: lookup.expand.map((expand) => ({
+            ...expand,
+            level: expand.level ?? IMPUTED_EXPAND_LEVEL,
+          })),
+        }
+      : {}),
+  };
+}
+
+/** The level an imputed disclosure answers at when none is asked for: all of it. */
+const IMPUTED_DEFAULT_LEVEL = "detailed";
+
+/** The level from which an imputed disclosure shows an untagged expand. */
+const IMPUTED_EXPAND_LEVEL = "standard";
+
 /** Normalize a pack disclosure into a {@link DisclosureSpec} (default → base). */
 function disclosureSpec(disclosure: PackLookup["disclosure"]): DisclosureSpec {
   const levels = disclosure?.levels ?? [];