Stable Knowledge Identity Independent of Filesystem Layout

1. Status

This decision is Accepted. Every canonical document’s ## Metadata block must declare a stable ID, and builders/core validates it as described in atlas.identity-and-relationships.

2. Context

Ocean-Atlas knowledge is reorganized over time: files move between directories, titles are rewritten for clarity, and the site’s navigation structure changes. Relationships between knowledge items — a DSL reference pointing to the concept it implements, a pattern pointing to the example that demonstrates it — need to survive all of that reorganization without every related document needing an edit each time something moves.

If relationships referenced a file path or a rendered URL directly, moving or renaming one file would silently break every other document that pointed to it, with no validation step to catch the break.

3. Decision

Every independently addressable knowledge item declares a stable ID in its ## Metadata block:

id: dsl.api

The ID is a hierarchical, dotted, lowercase identifier (<namespace>.<identifier>, for example dsl.api, concept.bundle, pattern.entity-backed-fsm, adr.atlas-builder-boundary). It represents the identity of the knowledge itself and is kept conceptually distinct from two other, related values builders/core also tracks for the same document:

Stable ID    dsl.api                  — assigned by the author, never derived
Source path  dsl/api.md               — the file's location in the repository
Route        /dsl/api                 — derived from the source path for
                                         presentation

All relationships — Relationships: entries in metadata, and every cross-reference builders/core validates — reference the stable ID, never a file path or a route. An ID must not change merely because a document is renamed, moved, or reworded; per atlas.identity-and-relationships, a new ID is only appropriate when the knowledge’s identity itself fundamentally changes, in which case supersedes / superseded-by relationships preserve the historical connection.

The route is still mechanically derived from the current source path (see deriveRoute in builders/core), so moving a file does change its published URL. Stable identity protects the knowledge graph — relationship targets, citations, and cross-references by ID — not the URL; that narrower guarantee is deliberate and is why the ID/path/route distinction above is tracked as three separate values rather than one.

4. Alternatives Considered

4.1 Reference documents by file path

Rejected. A file path changes whenever a document is reorganized, and nothing would signal every other document that referenced the old path. Relationships would silently rot instead of failing the build.

4.2 Reference documents by rendered URL

Rejected for the same reason as file paths, and additionally couples canonical relationships to one presentation adapter’s routing convention — exactly the coupling adr.atlas-builder-boundary rules out.

4.3 Auto-generate IDs from title or path at build time

Rejected. A generated ID would change whenever its input (title or path) changed, which is precisely the instability this decision exists to avoid. IDs must be assigned once, by the author, and then left alone.

4.4 A separate ID-mapping table decoupled from the document itself

Considered. An external mapping (path → ID) would work but adds an indirection layer contributors must keep in sync by hand. Declaring the ID inside the document’s own metadata keeps identity and content in the same file, reviewed in the same pull request.

5. Consequences

Benefits

• Reorganizing directories, renaming files, or rewriting titles does not require touching every document that links to the one being changed.
• Relationships are validated mechanically: builders/core rejects a relationship whose target ID does not resolve, catching broken references at build time instead of as a silent dead link.
• IDs can be cited stably by external consumers — search results, agents, future RAG — independent of where the site currently renders that content.

Trade-offs

• IDs are one more thing contributors must get right by hand; a typo’d or duplicated ID fails the build with a validation error rather than silently working.
• The route is not protected by this decision — moving a file still changes its published URL, so external links into the rendered site can still break even though internal relationships do not.
• Choosing a good, lasting ID up front requires judgment; a namespace or identifier picked poorly is expensive to change later precisely because IDs are meant to be stable.

6. Implementation Implications

• builders/core’s validateDocuments rejects duplicate IDs and duplicate routes across the whole canonical set, and rejects any relationship whose target ID is not a known canonical ID.
• Presentation adapters map IDs to routes through the normalized model; they must not invent their own identity scheme or link by path.
• Renaming a file is a safe, ID-preserving operation as long as the id: field in its metadata is left unchanged; changing the id: field is an identity change and requires the supersession relationships described in atlas.identity-and-relationships.

7. Validation and Compliance Rules

• Every canonical document must declare a non-empty id field, or the build fails.
• No two canonical documents may share an ID; no two may resolve to the same route — both are validated by builders/core and fail the build on the first collision found.
• Every relationship target must resolve to a known canonical (or, for examples, canonical-or-example) ID, or the build fails with the source path and the unresolved target.
• An ID must follow the lowercase, dotted-namespace format defined in atlas.identity-and-relationships.

8. Related Knowledge

• adr.atlas-builder-boundary — establishes that Core, not any presentation adapter, owns route derivation and relationship validation.
• atlas.identity-and-relationships — the complete ID format, naming, and immutability rules this decision summarizes.
• adr.search-today-structured-retrieval-tomorrow — stable IDs are what future retrieval results and citations depend on.

These semantic relationships are declared in the document metadata.