159 lines
8.4 KiB
Markdown
159 lines
8.4 KiB
Markdown
---
|
|
id: LSN-0098
|
|
ticket: canonical-documentation-migration
|
|
title: One specification tree and stable installed reference IDs
|
|
created: 2026-10-28
|
|
tags: [compiler, compiler-pbs, packer, studio, documentation, migration]
|
|
---
|
|
|
|
# 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](../../../docs/specs/README.md).
|
|
|
|
## 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](../../../docs/specs/compiler/README.md) |
|
|
| `compiler/pbs` | [PBS source, SDK and projections](../../../docs/specs/compiler-languages/pbs/README.md) |
|
|
| `packer` | [Packer contracts](../../../docs/specs/packer/README.md) |
|
|
| `studio` | [Studio contracts](../../../docs/specs/studio/README.md) |
|
|
|
|
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](../../../docs/specs/compiler/24.%20Runtime%20Catalog%20Support%20Specification.md)
|
|
and [25: Typed Registry and PBX v0](../../../docs/specs/compiler/25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.md).
|
|
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](evidence/content-verification.json) 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:
|
|
|
|
```text
|
|
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](../../../docs/specs/compiler-languages/pbs/17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md#construction-and-expected-types)
|
|
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](../../../docs/vm-arch/README.md). 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](evidence/README.md) records commands, results, fingerprints
|
|
and the complete migration map. Completed workflow artifacts are disposed of
|
|
through the local discussion CLI.
|