Files
prometeu-studio/discussion/lessons/DSC-0095-canonical-documentation-migration/LSN-0098-one-spec-tree-and-stable-installed-reference-ids.md
T

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.