Select optional glossary file and directory underlay imports

2026-11-09 02:41:11 +00:00
parent 6908dcd206
commit 607fefac47
2 changed files with 84 additions and 52 deletions
--- a/docs/roadmap/configkit.md
+++ b/docs/roadmap/configkit.md
@@ -132,8 +132,10 @@ file remain terminal.
   runtime views from that result and removes its separate glossary YAML loader.
   Use its [named collections and recursive import placement](glossary-stages.md#named-collections-and-recursive-imports--resolved),
   retaining native discovery, source context, and tier semantics.
+   Supply its [optional default glossary sources](glossary-stages.md#default-sources-and-explicit-configuration--resolved)
+   in one underlay, with higher-priority explicit main configuration.
   Complete its required durable decision record. The glossary roadmap owns
-   the remaining entry schema, import provisioning, identity, runtime-view,
+   the remaining entry schema, identity, runtime-view,
   selection-input, and attribution decisions. This
   application scope model does not change native source composition or
   sibling-inheritance semantics.
--- a/docs/roadmap/glossary-stages.md
+++ b/docs/roadmap/glossary-stages.md
@@ -4,8 +4,8 @@

 **Status:** Accepted feature scope, ownership, and stage-selection semantics for
 the next Audita major release, including named collections and recursive import
-placement. Entry schema, import provisioning, remaining design decisions, and
-implementation are pending. The
+placement and optional default sources. Entry schema, remaining design decisions,
+and implementation are pending. The
 [master roadmap](library-adoption.md) owns sequencing and release completion.

 ## Baseline and Target
@@ -27,7 +27,8 @@ CLI, standalone parser, and file schema do not constrain the target design.
 Finalize the glossary representation with the agreed
 [version-3 application schema](configkit.md#application-schema-version--resolved)
 so operators migrate once. Collection placement and named selection are selected;
-entry identity, rich fields, and remaining import/selection details are open below.
+default import sources and their tier are also selected. Entry identity, rich
+fields, and remaining selection details are open below.

 ## Glossary Configuration Ownership — Resolved

@@ -51,8 +52,8 @@ Retain native source attribution through application resolution. A glossary
 filename is a configuration source, not an application-data file for a second
 post-handoff loader. Choose the source arrangement through ConfigKit's public
 composition APIs; a string in an application field does not automatically cause
-ConfigKit to load another document. Use the selected import placement below;
-the provision of the import declaration and its source tier remain open.
+ConfigKit to load another document. Use the selected import placement and
+application-supplied underlay below.

 ### Named Collections and Recursive Imports — Resolved

@@ -63,20 +64,13 @@ An omitted stage selection inherits the root selection; an explicit list replace
 it, and `[]` selects none. Report unknown collection names during configuration
 validation. Selection order determines runtime traversal, not source precedence.

-Use ConfigKit's recursive directory imports mounted at `glossary_collections`,
-with each imported file declaring its collection name. The following main-file
-example illustrates the native import declaration and stage selections; automatic
-provision of that declaration is a separate open decision:
+Mount glossary inputs at `glossary_collections`, with each imported file
+declaring its collection name. The default underlay below supplies native file
+and recursive directory imports, keeping the main configuration focused on
+selection and stages:

 ```yaml
 version: 3
-config:
-  imports:
-    - dir: glossaries
-      recursive: true
-      pattern: ["*.yml", "*.yaml"]
-      destination: [glossary_collections]
-
 glossaries: [party, spells]
 pipeline:
  stages:
@@ -100,8 +94,7 @@ party:
 ```

 The `party`/`entries` nesting is selected. Entry identity and rich fields in this
-illustration remain provisional pending the entry-schema decision below. The
-`glossaries` directory is an example declaration, not a selected implicit default.
+illustration remain provisional pending the entry-schema decision below.

 Keep collection identity in document keys. ConfigKit does not infer keys from
 filenames or subdirectories; all matches of the declaration receive the same
@@ -115,13 +108,59 @@ a directory walker, filename-to-key conversion, or YAML preprocessing in Audita.
 Imports in the same tier are strict peers; their discovery order does not create
 an override priority. Intentional overrides use upstream layering semantics.

-An application-supplied declaration may provide this same import behavior, but
-an underlay does not set a universal destination for imports in other documents.
-Import defaults can supply recursive/pattern policies; they neither discover
-sources themselves nor supply destinations. A supplied declaration must have the
-appropriate filesystem context, and an underlay places its contributions in a
-lower-priority tier. Resolve that provisioning choice below without changing
-ConfigKit's import semantics.
+### Default Sources and Explicit Configuration — Resolved
+
+Audita supplies one glossary underlay with two optional native imports:
+
+```yaml
+config:
+  imports:
+    - path: glossary.yml
+      required: false
+      destination: [glossary_collections]
+    - dir: glossary
+      required: false
+      recursive: true
+      pattern: ["*.yml", "*.yaml"]
+      destination: [glossary_collections]
+```
+
+Both locations are relative to the invocation's working directory: `./glossary.yml`
+and recursively `./glossary/`. Supply the appropriate host filesystem context for
+the underlay declaration through ConfigKit's public input APIs. This base is
+independent of the main configuration file's location and also applies when no
+main file is found. Do not attempt host discovery through an unrelated embedded
+filesystem or add an application-owned directory walker.
+
+Load both sources when present; this is composition, not first-match discovery.
+Missing optional sources contribute nothing. Present sources retain ConfigKit's
+normal parse, access, and composition errors; absence does not remove the domain
+requirement for a glossary-correction stage to select usable vocabulary.
+
+The file and directory contributions compose as strict peers in the same
+underlay tier. Neither overrides the other by declaration or discovery order.
+Main configuration and its imports have higher priority and can supplement or
+replace definitions according to native mapping and collection policies. An
+identified-list upsert replaces the whole matched record; details depend on the
+entry identity and collection policy selected below.
+
+Operators can put small inline collections in `glossary.yml`, organize larger
+libraries below `glossary/`, or use both. Nested imports retain native relative
+path and destination inheritance. A nested import from mounted `glossary.yml`
+inherits the `glossary_collections` destination unless it explicitly extends it.
+Do not repeat that destination unnecessarily in a manifest.
+
+With both defaults enabled, use the file for inline collections or imports of
+other sources, rather than a manifest that also imports the files discovered
+under `glossary/`. Repeated inclusion within the tier retains ConfigKit's native
+error; Audita does not silently deduplicate the import graph.
+
+Explicit main-file imports supplement the underlay's sources; they do not cancel
+its import declarations. In particular, main-file `config.imports: []` does not
+disable default loading. An underlay does not set a universal destination for
+unrelated explicit imports. Changing or disabling default discovery, if added
+later, would require a load-time choice before ConfigKit processes the underlay;
+ordinary resolved application values cannot retroactively change those imports.

 ### Shared Libraries and Campaign Vocabulary — Resolved

@@ -147,7 +186,8 @@ One practical project layout is:
 ```text
 campaign/
  audita.yml
-  glossaries/
+  glossary.yml
+  glossary/
    shared/
      dnd5e/
        spells.yml
@@ -160,8 +200,10 @@ campaign/
      places.yml
 ```

-The recursive import above discovers both groups through ConfigKit. A vendored
-library release or pinned checkout inside the configuration tree lets each
+Run from the campaign directory to use the default sources. `glossary.yml` can
+contain small inline collections; the default recursive directory import discovers
+the shared and campaign subtrees through ConfigKit. A vendored library release
+or pinned checkout inside the configuration tree lets each
 campaign adopt shared updates deliberately and independently. Library distribution
 and revision management remain outside Audita; it consumes local configuration
 sources through native imports. This layout fits the native import-root model
@@ -533,10 +575,10 @@ adopted configuration and CLI conventions and avoids adapting it twice. Keep the
 requirement visible during library design without expanding those migrations
 into feature implementation.

-1. Apply named collection selection and recursive directory placement. Settle
-   entry schema, import provisioning, CLI selection syntax, and remaining domain
-   decisions below. Preserve the selected
-   scope, clearing, CLI precedence, and fallback semantics in version 3.
+1. Apply named collection selection, default file/directory underlay imports,
+   and recursive placement. Settle entry schema, CLI selection syntax, and remaining
+   domain decisions below. Preserve the selected scope, clearing, CLI precedence,
+   and fallback semantics in version 3.
 2. Adopt ConfigKit loading for glossary configuration. Register the selected
   collection identities, supply domain validation, and deliver final typed
   definitions and selections before transcript processing. Remove the redundant
@@ -583,6 +625,13 @@ lists, independent empty-list clearing, a glossary stage with no override using
 both inputs, and a collection selected only on a stage not entering root protection.
 Verify that modules and validators receive their respective effective selections
 and recorded source origins. Cover repeated modules and an empty stage list.
+Cover default-source loading with only `glossary.yml`, only `glossary/`, both,
+and neither present. Verify invocation-directory resolution even with a main file
+elsewhere or no main file, optional absence, and normal errors for invalid present
+sources. Verify strict-peer conflicts within the underlay, higher-priority main
+configuration additions/replacements under the selected native policies, nested
+import destination inheritance, and repeated inclusion within the default tier.
+Confirm that an empty main-file import list does not cancel the underlay imports.
 Exercise recursive directory imports with nested files, both YAML extensions,
 explicit collection names, and native placement/source attribution. Verify that
 file relocation within the imported tree preserves collection selection, and
@@ -633,25 +682,6 @@ guidance are in place before declaring this feature complete.

 The recommendations below are proposals, not selected contracts.

-### Import Provisioning and Default Directory
-
-**Recommendation:** initially express the recursive directory import in the main
-configuration through native `config.imports`, as illustrated above. This keeps
-its location, filesystem context, and strict-peer relationship visible and avoids
-new automatic discovery conventions. It costs a small import declaration in the
-main file. The directory path remains operator-selected rather than a fixed
-implicit location.
-
-**Alternative:** have Audita supply a native configuration input that declares
-the directory import, potentially as an underlay. This removes repeated main-file
-boilerplate and can offer a standard directory convention, but requires choosing
-how its directory is configured, its filesystem context, and its precedence tier.
-An underlay is lower priority, not merely a hidden main-file import. Define its
-behavior when no main file exists and preserve native optional/required import
-semantics. Do not scan a host directory through an unrelated embedded filesystem
-or build an application-owned import resolver. This choice remains open; the
-recursive mapping destination and file-declared collection names are settled.
-
 ### Entry Identity and Rich Fields

 **Recommendation:** use explicit stable entry IDs independent of displayed terms,