148 lines
9.1 KiB
Markdown
148 lines
9.1 KiB
Markdown
# Complete authored-name occurrences: private successor contract
|
|
|
|
Accepted bounded design, 2026-09-24, based on private source
|
|
`93eb6117f95353d25d594d59780018f197c51672`, after parent source inspection,
|
|
[seam research](analysis-ordinary-index-20260924/source-map.md) and
|
|
[independent critique](analysis-ordinary-index-20260924/critique.md).
|
|
Issue 7 owns work status. This does not alter prerelease source `715036e`.
|
|
|
|
The user requires complete graphical/text/API parity. This dependency adds
|
|
ordinary name occurrences to the accepted typed index, followed by a separately
|
|
specified rename compositor. It does not redefine parity as renaming, activate
|
|
public source8 or claim scalar/structural editing support.
|
|
|
|
## Chosen capability and alternatives
|
|
|
|
Consume `IndexedMixedProject` into an opaque private owner that retains it and
|
|
one ordinary occurrence map. The owner provides read-only views of original
|
|
bundle/files, complete Project, warnings, existing typed maps and new ordinary
|
|
records. No mutable replacement state, legacy Index/updater conversion, public
|
|
factory from loose parts or independently transferable edit authority.
|
|
|
|
Use physical keys `(canonical file, alias-token start, alias-token end)` for the
|
|
new map. Each inline value contains owning declaration ID, global target ID,
|
|
Header/Reference role and the original full occurrence extent. For headers the
|
|
extent is the alias token; for references it includes `@` and intervening trivia.
|
|
These are snapshot keys, not persistent semantic identities. Preserve the richer
|
|
retained position trees for subsequent structural work. Do not force ordinary
|
|
keys into typed expression `Field`/`Child` types.
|
|
|
|
This materialized map makes complete coverage inspectable before edit authority
|
|
is added. A fused traversal/rename planner could avoid retained map slots, but
|
|
would combine still-uncertain ownership coverage with intent/diff/output logic.
|
|
Revisit that tradeoff only after evidence demonstrates a useful simplification.
|
|
Owned structural key paths would duplicate retained metadata without a current
|
|
consumer and introduce extra string/path/drop accounting; defer them. Whole-word
|
|
source scans and public `SyntaxUpdate` are unsuitable: the former cannot identify
|
|
reference roles; the latter reparses, formats and later applies structural edits
|
|
in transformed coordinates.
|
|
|
|
## Complete scope
|
|
|
|
Add exactly one project alias header, each ordinary declaration alias header,
|
|
and every actual `EditKind::Reference` leaf in every ordinary declaration field
|
|
tree. Include scalar and nested/list references, repeated targets, routes/view
|
|
options, artifact/trace endpoints and references from ordinary syntax into typed
|
|
globals. Resolve only through `Target::Global` names in the existing complete
|
|
catalog; scoped calculation parameters never enter this reverse lookup.
|
|
|
|
Exclude comments, descriptions, display names, string literals, enum words,
|
|
include paths, identity strings and `HistoricalUuid` leaves. Do not exclude a
|
|
whole field by name merely because some fields use historical references.
|
|
Implicit lexical parenting has no authored alias token; explicit `parent @x`
|
|
does. Preserve the existing restriction against typed declarations nested in
|
|
ordinary bodies. Do not use `active_references`: it only meters selected ordered
|
|
model-step references and is not an alias occurrence selector.
|
|
|
|
Typed occurrences stay unchanged. Across both families, every global declaration
|
|
header appears once and no physical alias token has two owners. Parameters keep
|
|
their existing calculation-scoped identity even when UUIDs coincide with globals.
|
|
|
|
## Construction and verification
|
|
|
|
Reuse sealed `FileSyntax.positions`, ordinary AST and original significant
|
|
tokens. No reparse, fragment lexer, source mask, model copy or formatter.
|
|
|
|
1. Iterate canonical files and their ordinary declaration/position pairs. Check
|
|
matching IDs, owner and header containment against that declaration occurrence.
|
|
Nested declaration spans overlap: their parent range cannot determine ownership.
|
|
2. Project header lacks a role map. Project only its alias from retained tokens
|
|
anchored at `SourceHeader.span.start`: require `project`, the following complete
|
|
Word token, containment in that header and exact admitted project spelling.
|
|
Ordinary header alias spans already exist; verify complete Word identity and
|
|
the corresponding global declaration before insertion.
|
|
3. Walk Record/List values iteratively. The synthetic root `fields` span includes
|
|
braces (`body.start-1..body.end+1`); do not require it inside the body interior.
|
|
Actual field/value/reference spans must remain within their justified parent
|
|
and owning declaration. Nested declarations are separate flat occurrences,
|
|
not children discovered through broad span scans.
|
|
4. For a Reference, require a valid original UTF-8 extent and a significant `@`
|
|
token at its start. The next significant token must be a whole Word whose end
|
|
equals the retained Reference end, spelling equals the retained reference,
|
|
and global catalog target agrees. Store only that Word as the alias location,
|
|
retaining the full extent inline. Comments/whitespace between marker and Word
|
|
remain outside replacement authority.
|
|
5. Reject duplicate physical alias tokens across ordinary and typed families,
|
|
repeated declaration headers, wrong owners/files/targets, partial or malformed
|
|
tokens, and absent global headers. Full-token validation makes separate
|
|
overlapping partial-token ownership invalid before insertion.
|
|
6. Failure drops the consumed attempt with no partial owner. Preserve known
|
|
canonical file attribution. Invalid file keys or invalid UTF-8 spans use the
|
|
explicit safe diagnostic fallback already established by the typed constructor.
|
|
|
|
Completeness relies on exhaustive traversal of the sealed parser projection,
|
|
checked against independent full-set oracles. Do not add another AST/position
|
|
emitter merely to claim runtime detection of arbitrary coordinated corruption.
|
|
Per-record validation does not prove arbitrary omissions from trusted emission;
|
|
name this boundary accurately in tests and documentation.
|
|
|
|
## Storage and depth
|
|
|
|
Retain the entire inherited ledger, typed maps/paths, raw arenas, syntax and
|
|
warnings. With D ordinary declarations and A reference leaves, the one-map design
|
|
adds exactly **N = 1 + D + A entry slots**, zero lowerer occurrence slots and zero
|
|
owned-name bytes. IDs, roles and two spans are inline. Added retained containers
|
|
or copied strings would require a revised explicit accounting decision.
|
|
|
|
Count the borrowed reverse global map G, typed physical-location lookup T and
|
|
all live iterative work slots W as scratch entries. A header-seen flag can live
|
|
in each reverse-map value; avoid an uncounted extra set. New-map membership
|
|
handles ordinary duplicates. Conservative coexistence is inherited baseline plus
|
|
`N + G + T + W`; tests must hand-count actual phase peaks, not assume this upper
|
|
bound is always simultaneously reached. Reserve before growth, and release only
|
|
after the corresponding allocation is dropped.
|
|
|
|
Do not recharge parsed bytes/tokens/entries/references, Exact work, raw lowerer
|
|
occurrences or model-step counters. The ordinary tree already satisfies its
|
|
depth-64 parser policy. This iterative reference walk introduces no new
|
|
`Budget::frame` interpretation or raised limit; parsed Usage remains unchanged.
|
|
Workspace stack/lifecycle guarantees remain bounded by actual tested cases.
|
|
|
|
## Acceptance before subsequent edits
|
|
|
|
Independently enumerate complete header/reference records for small OA and SA
|
|
mixed bundles, including both reference directions, nested ordinary declarations,
|
|
explicit/implicit parents, noncanonical include traversal, coincident cross-file
|
|
offsets, Unicode/CRLF, marker comments and alias-like prose. Extend the accepted
|
|
rich fixture and separately cover ordinary categories absent from it: relation
|
|
endpoints, contextual chains, routes/view options, artifacts and traces, including
|
|
historical UUIDs equal to live identities. Expected maps must not derive from the
|
|
index, formatter or lowerer.
|
|
|
|
Require targeted corruptions to reach the intended marker/token/target/owner/file,
|
|
physical uniqueness and safe diagnostic checks. Hand-count retained and peak
|
|
storage with typed baseline still live; isolate exact-cap/cap-minus-one failures
|
|
from earlier parsing. Preserve complete Project, bundle identity/bytes/entry,
|
|
canonical file keys, warnings, static admission metadata and parse/numeric usage.
|
|
Exercise success and late failure on the existing bounded-stack harness. Retain
|
|
all prior typed-index outcomes and explicitly report inherited full-suite/format
|
|
failures. No public API or source8 activation is part of this change.
|
|
|
|
The next separate contract must gate a complete independent target Project to
|
|
allowed global/scoped renames only, validate final namespaces simultaneously,
|
|
produce both families' complete nonoverlapping edits in original coordinates,
|
|
preflight combined storage/output including untouched files, emit each file once,
|
|
then parse/resolve/admit actual output and compare the whole Project to intent.
|
|
Scalar changes, structural moves, insertion/removal, reidentity, stabilization,
|
|
migration, history/checked save and UI/API parity remain required later work.
|