Complete authored-name occurrences: private successor contract

Accepted bounded design, 2026-09-24, based on private source 93eb6117f95353d25d594d59780018f197c51672, after parent source inspection, seam research and independent critique. 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.

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.
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.
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.
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.
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.
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.

9.1 KiB Raw Blame History