Resolve extensible glossary entry content fields

This commit is contained in:
2026-11-09 03:28:30 +00:00
parent 1b76a426cc
commit 77995b7a2c
2 changed files with 64 additions and 34 deletions

View File

@@ -1,6 +1,6 @@
# ConfigKit Adoption Outline # ConfigKit Adoption Outline
**Updated:** 2026-11-08 **Updated:** 2026-11-09
**Status:** Initial outline. The [master roadmap](library-adoption.md) owns the **Status:** Initial outline. The [master roadmap](library-adoption.md) owns the
agreed adoption policy, reviewed versions, shared sequencing, and completion. agreed adoption policy, reviewed versions, shared sequencing, and completion.
@@ -135,10 +135,11 @@ file remain terminal.
Supply its [optional default glossary sources](glossary-stages.md#default-sources-and-explicit-configuration--resolved) Supply its [optional default glossary sources](glossary-stages.md#default-sources-and-explicit-configuration--resolved)
in one underlay, with higher-priority explicit main configuration. in one underlay, with higher-priority explicit main configuration.
Register its [collection-scoped entry IDs](glossary-stages.md#entry-identity--resolved) Register its [collection-scoped entry IDs](glossary-stages.md#entry-identity--resolved)
through native sequence identity registration. through native sequence identity registration. Apply its
[extensible entry content contract](glossary-stages.md#entry-content-fields--resolved)
using native typed fields and inline extension data.
Complete its required durable decision record. The glossary roadmap owns Complete its required durable decision record. The glossary roadmap owns
the remaining rich-field, runtime-view, the remaining runtime-view, selection-input, and attribution decisions. This
selection-input, and attribution decisions. This
application scope model does not change native source composition or application scope model does not change native source composition or
sibling-inheritance semantics. sibling-inheritance semantics.

View File

@@ -1,11 +1,11 @@
# Stage-Specific Glossary Inputs # Stage-Specific Glossary Inputs
**Updated:** 2026-11-08 **Updated:** 2026-11-09
**Status:** Accepted feature scope, ownership, and stage-selection semantics for **Status:** Accepted feature scope, ownership, and stage-selection semantics for
the next Audita major release, including named collections and recursive import the next Audita major release, including named collections and recursive import
placement, optional default sources, and collection-scoped entry IDs. Rich fields, placement, optional default sources, collection-scoped entry IDs, and extensible
remaining design decisions, and implementation are pending. The entry content fields. Remaining design decisions and implementation are pending. The
[master roadmap](library-adoption.md) owns sequencing and release completion. [master roadmap](library-adoption.md) owns sequencing and release completion.
## Baseline and Target ## Baseline and Target
@@ -27,8 +27,8 @@ CLI, standalone parser, and file schema do not constrain the target design.
Finalize the glossary representation with the agreed Finalize the glossary representation with the agreed
[version-3 application schema](configkit.md#application-schema-version--resolved) [version-3 application schema](configkit.md#application-schema-version--resolved)
so operators migrate once. Collection placement and named selection are selected; so operators migrate once. Collection placement and named selection are selected;
default import sources, their tier, and entry identity are also selected. Rich default import sources, their tier, entry identity, and content fields are also
fields, runtime ambiguity, and remaining selection details are open below. selected. Runtime ambiguity and remaining selection details are open below.
## Glossary Configuration Ownership — Resolved ## Glossary Configuration Ownership — Resolved
@@ -90,11 +90,14 @@ party:
- id: merrin - id: merrin
name: Merrin name: Merrin
category: character category: character
summary: The party's wizard. description: The party's wizard.
player: Alex
class: wizard
level: 5
``` ```
The `party`/`entries` nesting and explicit `id` are selected. The rich fields in The entry follows the [selected content contract](#entry-content-fields--resolved).
this illustration remain provisional pending the content-field decision below. Its additional campaign fields remain available for other consumers.
Keep collection identity in document keys. ConfigKit does not infer keys from Keep collection identity in document keys. ConfigKit does not infer keys from
filenames or subdirectories; all matches of the declaration receive the same filenames or subdirectories; all matches of the declaration receive the same
@@ -138,6 +141,43 @@ whole matching record. Do not treat an identified list as a mapping that merges
individual fields of matching records. The selected ordinary stage-selection individual fields of matching records. The selected ordinary stage-selection
lists remain separate from these definition collections. lists remain separate from these definition collections.
### Entry Content Fields — Resolved
Require `id`, `name`, and `category` as nonempty strings. The collection-scoped
identity contract above governs `id`; `name` is the canonical term, and `category`
is free-form text rather than an Audita-defined enumeration.
Support these optional fields:
| Field | Contract |
| --- | --- |
| `description` | String providing contextual guidance; omission or an empty string requires no filler text. |
| `aliases` | List of nonempty strings representing alternate names or spellings. |
| `plural` | Nonempty string when supplied, providing an explicit plural form. |
Allow and preserve additional ordinary entry fields, including nested mappings,
lists, and scalar values. A campaign's party roster can therefore also carry
player names, classes, levels, affiliations, or data for other applications.
Preservation applies to the effective result of native composition; it does not
change whole-record replacement semantics.
Use typed Go fields for the Audita contract and ConfigKit's native inline
string-keyed map of dynamic values for unmatched fields. Its
[schema binding rules](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/config.md#advanced-type-and-field-rules)
cover decoding and inspection without a custom decoder. Keep additional data in
the resolved Go configuration and native inspection. ConfigKit still owns its
reserved syntax and supported value shapes; extensibility does not mean
accepting arbitrary YAML. Audita validates its known fields without imposing
campaign-specific rules on additional fields. A misspelled optional field may
therefore be retained as additional data; do not add a separate typo-detection
mechanism.
Build the rich LLM projection deliberately from Audita's known glossary fields,
including `description` when present. Do not automatically forward additional
fields to the LLM. Derive protected vocabulary from names, aliases, and plurals;
unrelated metadata does not contribute vocabulary. These consumer projections
leave the complete resolved entry intact.
### Default Sources and Explicit Configuration — Resolved ### Default Sources and Explicit Configuration — Resolved
Audita supplies one glossary underlay with two optional native imports: Audita supplies one glossary underlay with two optional native imports:
@@ -280,7 +320,7 @@ for its consumers, preserving traceability to configured entries and selections:
| Consumer | Derived representation | | Consumer | Derived representation |
| --- | --- | | --- | --- |
| Glossary module LLM | Rich entries with terms, categories, descriptive comments/context when present, and other relevant configured fields. | | Glossary module LLM | Rich entries projected from known glossary fields, including names, categories, descriptions, aliases, and plurals when present. |
| Protected-term validator | Deduplicated recognized vocabulary prepared for deterministic matching. | | Protected-term validator | Deduplicated recognized vocabulary prepared for deterministic matching. |
| Glossary-stage protection | Selected protected vocabulary minus the active glossary vocabulary. | | Glossary-stage protection | Selected protected vocabulary minus the active glossary vocabulary. |
| Diagnostics and inspection | Resolved definitions and selections with their configuration origins, distinguished from derived runtime views. | | Diagnostics and inspection | Resolved definitions and selections with their configuration origins, distinguished from derived runtime views. |
@@ -292,7 +332,8 @@ latter to suppress configuration conflicts or rewrite the resolved definitions.
Rich prompt data need not lose distinct definitions merely because their text Rich prompt data need not lose distinct definitions merely because their text
matches in the protection view. Audita owns matching, transcript-specific matches in the protection view. Audita owns matching, transcript-specific
validation, and the selected stage-specific transformations. Detailed handling validation, and the selected stage-specific transformations. Detailed handling
of ambiguous identities and rich-entry payloads remains open below. of ambiguous identities, repeated membership, and rich-entry ordering remains
open below.
## Root Defaults and Stage Overrides — Resolved ## Root Defaults and Stage Overrides — Resolved
@@ -608,9 +649,9 @@ requirement visible during library design without expanding those migrations
into feature implementation. into feature implementation.
1. Apply named collection selection, default file/directory underlay imports, 1. Apply named collection selection, default file/directory underlay imports,
and recursive placement. Settle entry schema, CLI selection syntax, and remaining recursive placement, and the extensible entry content contract. Settle CLI
domain decisions below. Preserve the selected scope, clearing, CLI precedence, selection syntax and remaining domain decisions below. Preserve the selected
and fallback semantics in version 3. scope, clearing, CLI precedence, and fallback semantics in version 3.
2. Adopt ConfigKit loading for glossary configuration. Register the selected 2. Adopt ConfigKit loading for glossary configuration. Register the selected
collection identities, supply domain validation, and deliver final typed collection identities, supply domain validation, and deliver final typed
definitions and selections before transcript processing. Remove the redundant definitions and selections before transcript processing. Remove the redundant
@@ -677,6 +718,11 @@ Allow the same ID in different collections and the same displayed name on distin
records. Verify that changing a term or description while retaining its ID targets records. Verify that changing a term or description while retaining its ID targets
the same collection record, and that runtime spelling deduplication does not the same collection record, and that runtime spelling deduplication does not
collapse distinct configuration identities. Cover exact case-sensitive ID matching. collapse distinct configuration identities. Cover exact case-sensitive ID matching.
Verify required name/category validation and the optional description, aliases,
and plural contracts, including invalid types and empty values where prohibited.
Cover additional scalar, nested mapping, and list fields surviving native loading
and inspection; extension data must not mask invalid known fields. Verify that
unrelated extra fields affect neither the LLM projection nor protected vocabulary.
Exercise native glossary composition, inheritance, collection identity checks, Exercise native glossary composition, inheritance, collection identity checks,
and supported explicit layering with reusable party/spells fixtures. Cover source and supported explicit layering with reusable party/spells fixtures. Cover source
origins, strict decoding failures, and domain validation failures before processing. origins, strict decoding failures, and domain validation failures before processing.
@@ -721,23 +767,6 @@ guidance are in place before declaring this feature complete.
The recommendations below are proposals, not selected contracts. The recommendations below are proposals, not selected contracts.
### Entry Content Fields
**Recommendation:** retain `name`, `category`, `summary`, `aliases`, and `plural`
as the rich entry fields, with required name/category and optional descriptive
summary, aliases, and explicit plural. This keeps descriptive context available
without requiring filler text for obvious terms. Confirm field validation and
how each consumer uses optional values; the optional-summary contract would be
a deliberate change from the current glossary format. Identity is already
settled independently through `id`.
**Alternative:** rename the descriptive field to `comment` (or another selected
name) and revise requiredness as part of the major-release schema. This can align
the field with optional operator guidance rather than a formal definition, but
requires agreeing on its meaning and updating all authoring examples. Avoid
parallel interchangeable fields or an unnecessary legacy alias; compatibility
with the old format is not a constraint on the choice.
### Runtime Vocabulary and Identity Ambiguity ### Runtime Vocabulary and Identity Ambiguity
**Recommendation:** deduplicate recognized spellings for protection using the **Recommendation:** deduplicate recognized spellings for protection using the