eric/ConfigKit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Settle sequence identity declarations without values

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-23 00:04:55 +00:00
parent 8a54cecd1d
commit 58f4c39d6f
1 changed files with 44 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files

98
docs/roadmap/sequences.md
View File

@@ -1,9 +1,8 @@
# Sequence Identity And Combination
Status: feature roadmap with OD-1 through OD-11 settled. A whole-roadmap review
identified the remaining policy-lifetime clarification in OD-12 below. Resolve it
and review the completed roadmap before preparing a staged implementation plan.
This is not an implementation plan or an implemented contract.
Status: feature roadmap with OD-1 through OD-12 settled and ready for a staged
implementation plan. No open design decisions remain in this roadmap. This is
not an implementation plan or an implemented contract.
## Motivation
@@ -261,13 +260,15 @@ records, including uniqueness within each contribution.
#### Replacement And Policy Lifetime
YAML-owned identity follows the collection that survives an operation:
YAML-owned identity follows the collection that survives an operation. OD-12
also permits declarations pending at absent or non-sequence destinations.
| Operation | Effective YAML-owned identity |
| --- | --- |
| Append | Retain or establish the agreed identity |
| Replacement by identity | Retain or establish the agreed identity |
| Whole-sequence replacement | Use the replacing tier's declaration and discard the lower collection's YAML-only identity |
| Replacement by null or another non-sequence value | Discard the lower YAML-only identity; retain any identity explicitly declared by the replacing tier under OD-12 |
Without an application constraint, whole-sequence replacement may introduce a
different identity, such as replacing an `id`-keyed collection with a `name`-keyed
@@ -277,8 +278,9 @@ removal directive is needed.
Application registrations continue to constrain the replacement collection.
If the application requires `id`, declaring `name` is invalid under every mode.
The policy reset above applies when a sequence is actually replaced; effects of
absent contributions, null collections, and kind mismatches are settled in OD-6.
The policy reset above applies when the collection value is actually replaced.
OD-6 defines the value effects of absence, null, and kind mismatches; OD-12
defines the corresponding declaration-only and identity-lifetime rules.
YAML-only identity declarations receive assembly-time enforcement, as settled
in OD-1 below.
@@ -525,8 +527,10 @@ At a collection's precedence boundary:
| Explicit `[]` | Clear the sequence | Contribute no records |
| Explicit null or another non-sequence value | Ordinary replacement, subject to application schema | Error: the operation requires a sequence |
A declaration alone does not clear a collection. An optional import selecting
nothing contributes nothing; it does not erase records supplied elsewhere.
A declaration alone does not clear a collection. OD-12 defines how a key-only
declaration validates a retained sequence or remains pending when no sequence
exists. An optional import selecting nothing contributes nothing; it does not
erase records supplied elsewhere.
An absent lower collection can be initialized by an incoming sequence under
any mode, subject to identity requirements. An explicitly null or other
non-sequence lower value is distinct from absence: append and upsert against it
@@ -827,6 +831,35 @@ removed. This preserves OD-9's persistence rule for applicable explicit modes
without retaining declarations owned by discarded records. The implementation
plan should choose the bookkeeping needed to preserve these distinctions.
### Identity Declarations Without Sequence Values
**OD-12: settled.**
Allow identity declarations without accompanying records. Apply a declaration to
an existing retained sequence immediately, checking identity agreement and
validating its records. Do not recombine earlier tiers. For example, if a lower
tier supplies an unkeyed `prompts` sequence and a higher tier only declares
`destination: [prompts], key: id`, the retained records must satisfy that identity
at this boundary.
If the collection is absent, retain the declaration in its owning scope for later
contributions without requiring the collection to exist. An otherwise empty
underlay can therefore establish identity for main-tier fragments under OD-10.
Item-local declarations remain subject to OD-11's ownership rules.
Merely declaring replace without supplying a replacement value does not authorize
changing a retained collection's identity. Actual replacement of the collection
by null or another non-sequence value discards the lower YAML-only identity,
retains any identity explicitly declared by the replacing tier, and preserves
application constraints. This extends OD-3's replacement rule to non-sequence
values.
An explicit identity declaration can remain pending at an absent or non-sequence
destination without independently imposing a shape requirement. OD-6 still
governs whether an attempted operation on a non-sequence value fails. These rules
allow baseline policy declarations while keeping identity removal tied to actual
replacement. Explicit mode persistence remains governed by OD-9.
## Architectural Direction
The settled collection declaration gives imported and inline records at the same
@@ -865,50 +898,7 @@ architecture policy before implementation. The current ADR and contracts remain
authoritative until that decision is made. This draft neither changes them nor
selects migration machinery.
A staged implementation plan should follow resolution of the open decisions
below and review of the completed roadmap.
It should cover ordinary and layered loading, item-local scopes, source-version
The settled roadmap is ready for a staged implementation plan.
The plan should cover ordinary and layered loading, item-local scopes, source-version
processing, identity validation, precedence, inheritance, and inspection together.
Public API design and test sequencing belong to that later plan.
## Open Decisions
### OD-12. Identity Declarations Without Sequence Values
OD-9 defines a mode-only declaration without accompanying records. Clarify the
corresponding behavior for `key`, including a declaration made before any sequence
exists, and complete OD-3's identity-lifetime rule for non-sequence replacement.
These cases must have defined results before the implementation plan chooses how
to store collection policy.
For example, a lower tier supplies an unkeyed `prompts` sequence and a higher tier
only declares `destination: [prompts], key: id`. Does this validate and identify
the retained sequence immediately? Can a declaration in an otherwise empty
underlay establish identity for main-tier fragments under OD-10? Conversely, if
an identified sequence is replaced by null, does its old YAML identity disappear?
OD-6 specifies the resulting values but does not fully specify these policy effects.
**Recommendation:** Allow identity declarations without accompanying records.
Apply the declaration to a retained sequence immediately, checking identity
agreement and validating its records; do not recombine earlier tiers. If the
collection is absent, retain the declaration in its owning scope for later
contributions without requiring the collection to exist. Merely declaring replace
without supplying a replacement value does not authorize changing a retained
collection's identity. Extend OD-3's replacement rule to any actual replacement
of the collection by a non-sequence value: discard the lower YAML-only identity,
retain any identity explicitly declared by the replacing tier, and preserve
application constraints. An explicit declaration can remain pending at an absent
or non-sequence destination without independently imposing a shape requirement;
OD-6 still governs whether an attempted operation on a non-sequence value fails.
These rules allow baseline policy declarations while keeping identity removal
tied to actual replacement. Explicit mode persistence remains governed by OD-9.
**Alternative:** Require a YAML identity declaration to have a sequence in the
same tier. This keeps YAML identity attached only to concrete sequence values
and reduces pending-policy cases, but prevents policy-only baseline files and
requires authors to repeat declarations beside later contributions. It also
makes identity declarations less flexible than the settled mode declarations.
For non-sequence replacement, retaining the lower YAML identity until another
sequence appears is another viable choice; it supports persistent schema-like
policy, but conflicts with the current distinction between collection-owned
YAML identity and application-owned constraints and would require revisiting OD-3.