8.4 KiB
id, ticket, title, created, tags
| id | ticket | title | created | tags | ||||||
|---|---|---|---|---|---|---|---|---|---|---|
| LSN-0098 | canonical-documentation-migration | One specification tree and stable installed reference IDs | 2026-10-28 |
|
One specification tree and stable installed reference IDs
Worker: Lesson Worker. Owner: compiler/general.
Propagation: compiler/pbs, packer, studio and cross-domain navigation.
DSC-0095 executed accepted DEC-0082 through PLN-0160. These are historical
workflow identifiers; the durable entry point is the
specification guide.
Original problem
Compiler contracts were split between docs/specs and docs/compiler.
The earlier generic-struct implementation exposed contradictory constructor
descriptions across those surfaces. That semantic choice had already been
settled explicitly, but separate document roots still encouraged competing
authority, incomplete navigation and filename-derived installed IDs.
The user explicitly chose consolidation into docs/specs, reversing the
initial migration proposal. Updating paths also required updating AGENTS.md
routing, the PBS knowledge build, consumers and historical navigation.
Consolidated decision and final result
There is one specification tree with distinct owners:
| Owner | Canonical reading guide |
|---|---|
compiler/general |
Shared compiler contracts |
compiler/pbs |
PBS source, SDK and projections |
packer |
Packer contracts |
studio |
Studio contracts |
All 14 specifications formerly under docs/compiler were incorporated as
numbered chapters. Existing chapter numbers remained unchanged. Packer and
Studio retained their established directories; their affected navigation was
corrected. The replaced source tree was removed, and the PBS build consumes
only docs/specs/compiler-languages/pbs.
General compiler additions are 24: Runtime Catalog Support and 25: Typed Registry and PBX v0. PBS additions and their retained published aliases are:
Filename part of the published pbs:spec:<filename> ID |
Canonical chapter ID |
|---|---|
typed-arrays-and-optional-execution.md |
pbs:spec:14 |
first-class-functions-and-captures.md |
pbs:spec:15 |
generic-contracts.md |
pbs:spec:16 |
generic-structs-and-free-functions.md |
pbs:spec:17 |
input-and-existing-type-runtime-alignment.md |
pbs:spec:18 |
service-constants-and-runtime-math.md |
pbs:spec:19 |
runtime-random-integration.md |
pbs:spec:20 |
sdk-list-and-cursor.md |
pbs:spec:21 |
sdk-linked-and-cursor.md |
pbs:spec:22 |
sdk-set-and-identity.md |
pbs:spec:23 |
sdk-map-and-keyval.md |
pbs:spec:24 |
sdk-stack-and-queue.md |
pbs:spec:25 |
The content verification map preserves every exact source/destination path, original and final fingerprints, and the result of comparing all 14 contract bodies while excluding changed link destinations, owner/status/scope metadata, added authority sections and whitespace. All 14 bodies matched under that normalization. No source contract was dropped.
Preserve identity independently of editorial filenames
Previously, substringBefore(". ") produced chapter IDs for numbered files and
whole-filename IDs for unnumbered files. A rename could therefore change a
published reference without changing its actual contract.
The build now emits an explicit compatibility catalog. For example:
pbs:spec:generic-contracts.md -> pbs-knowledge/specs/16. Generic Contracts Specification.md
pbs:spec:16 -> pbs-knowledge/specs/16. Generic Contracts Specification.md
Both entries use the same resource and SHA-256. The old ID still resolves, while the editor can follow the existing numbered-document pattern. There is one canonical resource, not two source documents. The former unnumbered resource path is replaced; reference clients resolve IDs through the catalog instead of constructing filenames. Duplicate IDs and missing alias targets fail generation.
PbsDocumentationTest checks all 12 published aliases against their numbered
counterparts, including text, kind, resource and hash. The installed probe repeats
the identity checks using actual installed JARs in a process outside the checkout.
The normal quickstart, previous chapter IDs, SDK and example IDs remain available.
Consolidate authority without changing semantics
Thematic chapters own complete feature contracts. Base chapters retain distinct syntax, AST, diagnostic and lowering requirements and refer to those owners for shared detail. Static-semantics feature summaries were reduced to owner references; unique spans, error codes, substitution and runtime-hook requirements were retained.
Editorial alignment also removed stale descriptions already superseded by
accepted contracts: nominal callback/bind forms are retired in favor of structural
Fn, numeric as conversions retain their value-alignment contract, and reserved
service constants retain their supported BuiltinConst form. The existing
explicit constructor initialization rule
continues to cover ordinary/generic constructors and opaque Random fields.
Runtime reference defaults do not exempt PBS source constructors.
The migration does not redesign APIs or infer a new solution to substantive normative disagreement. A future unresolved conflict still requires an explicit decision rather than an editorial compromise.
Navigation and provenance need different treatment
Rebase a moved file's relative links from its original location and then map the target to its new location. A global text replacement cannot distinguish general compiler, language, packer and provider ownership or different path depths. The migration also repaired Studio-to-packer links and links to completed workflow artifacts, using completed lessons or explicit historical citations.
Obsolete local hardware/bytecode authority pointers were replaced with provider references and the mirror policy. Retired PBS drafts are historical context, not a competing normative source.
Architecture/ISA mirrors retain byte-exact provider content. Their relative links belong to the original runtime context; changing them inside the mirror would invalidate byte identity. The navigation checker resolves those links against that context when a runtime checkout is supplied. It performs no runtime writes. The 65 pre-existing evidence/mirror files recorded in the verification map retained their exact hashes. Updated lesson links do not imply that historical executions were repeated or newly qualified.
Validation and common pitfalls
The final normal Gradle suite and installed-knowledge gate passed: 1,099 normal test cases, zero failures/errors, 13 skipped; two installed tests passed. The final JAR contains 79 references, 12 compatibility aliases and 28 canonical spec resources, each byte-identical to its final source. The installed examples compile outside the checkout. No runtime repository changes were required.
Avoid these failure modes:
- Moving files without updating the generated knowledge index or root locators.
- Letting a filename rename silently break a public reference ID.
- Preserving compatibility with a second editable spec tree or source fallback.
- Replacing shared text with links while dropping unique AST/diagnostic requirements.
- Editing mirrored provider bytes just to repair provider-relative links.
- Rewriting historical fingerprints or linking to workflow artifacts already removed.
Run python3 tools/documentation/verify.py for local navigation. Add
--runtime ../runtime to verify provider references against a read-only checkout;
ordinary builds do not require it. Run the existing installed-knowledge gate after
source changes because a passing checkout read does not prove packaged delivery.
Validation evidence records commands, results, fingerprints and the complete migration map. Completed workflow artifacts are disposed of through the local discussion CLI.