Example Knowledge Facets: Horizon, Voyage, and Implementation

1. Status

This decision is Accepted. Every published example follows this three-facet structure, enforced by builders/core’s example pipeline.

2. Context

An Ocean example serves at least three different readers with different needs: someone deciding whether the example is relevant to them at all, someone following along to build something similar, and tooling that needs to validate and run the example as a real system. A single document trying to serve all three tends to either bury the orientation under implementation detail, or bury the runnable model under narrative explanation.

example-info/example-info.html already exists as a cross-system artifact: Ocean UI (in Ocean-Lab) uses it to present an example inside the application, independently of Ocean-Atlas. Ocean-Atlas needed a way to both publish that shared explanation and hold its own canonical knowledge identity (a stable ID, type, area, status, and typed relationships to other Ocean-Atlas knowledge) for the same example, without editing that shared file to fit Atlas-specific conventions.

3. Decision

Every example is published as three distinct modeled facets rather than one combined document. Horizon and Voyage remain separate sections in the shared explanation file, while Implementation is assembled from the runnable project files:

ocean-examples/<slug>/
├── example.md                        Atlas facet
│   (ID, type, area, status, relationships — the canonical descriptor)
├── example-info/example-info.html    Explanation facet
│   ├── OCEAN-EXAMPLE-META            (catalog metadata: level, tags, time)
│   ├── <section id="horizon">        Horizon — concise orientation
│   └── <section id="voyage">         Voyage — guided walkthrough
└── *.ocn, config, fixtures, …        Implementation facet
    (the actual runnable Ocean project)

Horizon answers “is this relevant, and what does it model?” — the scenario, architecture, demonstrated Ocean concepts, and expected result, described independently of implementation technology.

Voyage answers “how and why was this built?” — requirements, source structure, modeling decisions, technology selection, validation, generation, execution, and verification.

Implementation is the executable evidence: the .ocn sources and supporting files a reader can inspect, validate, and run.

Horizon: system model
        ↓
Voyage: technology selection and configuration
        ↓
Implementation: concrete, runnable system

example.md is Ocean-Atlas’s own facet: the stable ID, metadata, and relationships that let an example participate in the same knowledge graph as concepts, DSL references, and patterns, without requiring example-info.html — a file also consumed by Ocean UI — to adopt Atlas-specific conventions.

4. Alternatives Considered

4.1 One combined Markdown document per example

Rejected. Mixing orientation, narrative walkthrough, and implementation listing in one document makes each harder to keep independently correct, and forces every reader to scroll past content meant for a different audience.

4.2 Fold example.md into example-info.html

Rejected. example-info.html is shared with Ocean UI and structured for that consumer’s rendering needs (OCEAN-EXAMPLE-META, Horizon/Voyage HTML sections). Requiring it to also carry Ocean-Atlas’s canonical metadata and typed relationships would couple two independent consumers’ formats together.

4.3 Generate example.md automatically from example-info.html

Considered for later. Today, example.md’s identity fields are authored explicitly and cross-checked against example-info.html’s OCEAN-EXAMPLE-META block (descriptor.metadata.id must equal examples.<usage.id>). Full generation was deferred to avoid adding a code-generation step before the two-facet split had proven itself.

4.4 Treat Horizon and Voyage as separate files instead of sections

Rejected. Horizon and Voyage describe one example from two angles, not two different examples; keeping them as sections of one example-info.html preserves the file Ocean UI already reads as a single unit, while Ocean-Atlas extracts each section independently.

5. Consequences

Benefits

• A reader can stop after Horizon if that’s all they need, without reading a full walkthrough.
• Voyage can go deep on technology-specific decisions without contaminating Horizon’s technology-independent orientation.
• example-info.html keeps working for Ocean UI without any Atlas-specific requirement leaking into it beyond the existing Horizon/Voyage sections.
• Implementation stays the single source of executable truth; Horizon and Voyage explain it but never replace it.

Trade-offs

• Three facets can drift out of sync — a Voyage step that no longer matches the current .ocn files, or a Horizon claim the implementation no longer supports — and nothing but review and the “Example Quality” guidance in examples.index catches that today.
• Authors must maintain both example.md and example-info.html for the same example, with an explicit ID cross-check between them.
• Extracting Horizon and Voyage from HTML sections (rather than, say, dedicated Markdown files) ties that extraction to example-info-template.html’s HTML structure.

6. Implementation Implications

• builders/core/src/examples.ts’s extractExampleSection locates the <section id="horizon"> and <section id="voyage"> elements in example-info.html; changing that template’s section IDs is a breaking change for every published example.
• normalizeExample enforces that example.md’s ID equals examples.<usage.id> from OCEAN-EXAMPLE-META, and that Type is Example and Area is Examples; this is the only place identity is cross-checked between the two facets.
• The Implementation facet is inventoried, not interpreted: inventoryFiles records each project file outside example.md and the example-info/ explanation directory, including its kind, media type, content hash, and readable content where supported. builders/core does not compile or run the DSL it finds there.

7. Validation and Compliance Rules

• Publishing an example requires example.md to exist; a source directory without it is skipped entirely, not partially published.
• example-info.html must contain a well-formed OCEAN-EXAMPLE-META JSON block and both a horizon and a voyage section, or example normalization fails.
• An example must contain at least one .ocn file, or example validation fails — Horizon and Voyage without a runnable Implementation are not a complete example.
• example.md’s ID must match examples.<usage.id> exactly, or normalization fails with the mismatch.

8. Related Knowledge

• adr.external-examples-repository — why these three facets live in the separate ocean-examples submodule rather than in Ocean-Atlas directly.
• examples.index — the full authoring guidance for Horizon, Voyage, and the technology boundary between them.

These semantic relationships are declared in the document metadata.