Resolve extensible glossary entry content fields
This commit is contained in:
@@ -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.
|
||||||
|
|
||||||
|
|||||||
@@ -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
|
||||||
|
|||||||
Reference in New Issue
Block a user