77 lines
4.1 KiB
Markdown
77 lines
4.1 KiB
Markdown
|
# Catalog Extension Examples
|
||
|
|
|
||
|
|
Concrete worked examples of the four catalog `kind`s admitted by
|
||
|
|
[ADR-034](../../.ontoref/adrs/adr-034-catalog-extensibility-beyond-rust.ncl):
|
||
|
|
|
||
|
|
| Path | Kind | Status | When to use |
|
||
|
|
| --- | --- | --- | --- |
|
||
|
|
| [`01-rust/`](01-rust/) | `'Rust` | Executable today (default) | Piloto ops co-developed with the daemon |
|
||
|
|
| [`02-sidecar/`](02-sidecar/) | `'Sidecar` | Phase A — implementable today | Shared-domain Level-3 instances (ADR-030 mechanism #6) |
|
||
|
|
| [`03-ncl-transform/`](03-ncl-transform/) | `'NclTransform` | Phase B — declarable, exec deferred | Trivial CRUD ops once the interpreter backend lands |
|
||
|
|
| [`04-wasm/`](04-wasm/) | `'Wasm` | Phase B — declarable, exec deferred | Non-Rust authors, sandboxed ops (T3/T4/T5 triggers) |
|
||
|
|
|
||
|
|
## What this folder demonstrates
|
||
|
|
|
||
|
|
Each subfolder contains one minimal, self-contained example for a single
|
||
|
|
`kind`. The catalog declarations typecheck against
|
||
|
|
[`schema-future.ncl`](schema-future.ncl) — a forward-looking copy of the
|
||
|
|
post-migration-0025 schema co-located with the examples so all four
|
||
|
|
paths verify today even though migrations 0024 and 0025 are still
|
||
|
|
`'Proposed` at the protocol level.
|
||
|
|
|
||
|
|
## Forward-looking schema
|
||
|
|
|
||
|
|
[`schema-future.ncl`](schema-future.ncl) models the contract that
|
||
|
|
`.ontoref/catalog/schema.ncl` will adopt once migration 0025 lands. It
|
||
|
|
declares:
|
||
|
|
|
||
|
|
- `OpKind = [| 'Rust, 'NclTransform, 'Wasm, 'Sidecar |]`
|
||
|
|
- Per-kind body shapes (`NclTransformBody`, `WasmBody`, `SidecarBody`)
|
||
|
|
- The `OndaodPreRequired` contract enforcing that non-Rust ops include
|
||
|
|
`evaluate_ondaod` in `constraints.pre`
|
||
|
|
- The extended `OperationDecl` admitting `kind` and `body`
|
||
|
|
|
||
|
|
After migration 0025 is applied to your project, replace
|
||
|
|
`import "../../schema-future.ncl"` with
|
||
|
|
`import "../../../.ontoref/catalog/schema.ncl"` and the examples keep
|
||
|
|
working.
|
||
|
|
|
||
|
|
## Verify all examples typecheck
|
||
|
|
|
||
|
|
```sh
|
||
|
|
nickel typecheck examples/catalog-extension/01-rust/greet_actor.ncl --import-path examples/catalog-extension
|
||
|
|
nickel typecheck examples/catalog-extension/02-sidecar/catalog/send_email_notification.ncl --import-path examples/catalog-extension
|
||
|
|
nickel typecheck examples/catalog-extension/03-ncl-transform/rename_ontology_node.ncl --import-path examples/catalog-extension
|
||
|
|
nickel typecheck examples/catalog-extension/04-wasm/render_provisioning_report.ncl --import-path examples/catalog-extension
|
||
|
|
```
|
||
|
|
|
||
|
|
All four MUST pass; the `'Rust` example passes without `evaluate_ondaod`
|
||
|
|
in pre-validators (Rust ops can synthesise the ondaod context inline);
|
||
|
|
the other three include `"evaluate_ondaod"` in `constraints.pre` per
|
||
|
|
[ADR-034 constraint
|
||
|
|
`non-rust-kinds-require-ondaod-pre`](../../.ontoref/adrs/adr-034-catalog-extensibility-beyond-rust.ncl).
|
||
|
|
|
||
|
|
## Runtime status
|
||
|
|
|
||
|
|
| Kind | Daemon dispatches today? | Awaits |
|
||
|
|
| --- | --- | --- |
|
||
|
|
| `'Rust` | Yes (inventory + `#[onto_operation]`) | — |
|
||
|
|
| `'Sidecar` | Soon (ADR-030 Phase A, ~80 LOC proxy handler) | Mechanism #6 land |
|
||
|
|
| `'NclTransform` | No — returns HTTP 501 | ADR-030 T-trigger: expressive-power proof for ≥3 real ops |
|
||
|
|
| `'Wasm` | No — returns HTTP 501 | ADR-030 T3/T4/T5 trigger |
|
||
|
|
|
||
|
|
A daemon built without the corresponding executive feature flag returns
|
||
|
|
501 Not Implemented when a non-`'Rust` op is invoked. See ADR-034
|
||
|
|
constraint `non-rust-kinds-declarable-not-executable-without-flag`.
|
||
|
|
|
||
|
|
## References
|
||
|
|
|
||
|
|
- [ADR-024 — Operations Layer](../../.ontoref/adrs/adr-024-operations-layer-agent-action-boundary.ncl)
|
||
|
|
- [ADR-026 — Three-planes validation](../../.ontoref/adrs/adr-026-validation-architecture-three-planes-sla-per-op.ncl)
|
||
|
|
- [ADR-028 — Ontology-Layer Separation](../../.ontoref/adrs/adr-028-ontology-layer-separation-from-project-layer.ncl)
|
||
|
|
- [ADR-029 — Tier coexistence permanent](../../.ontoref/adrs/adr-029-tier-coexistence-as-permanent-design.ncl)
|
||
|
|
- [ADR-030 — Catalog discovery cross-project](../../.ontoref/adrs/adr-030-catalog-discovery-cross-project.ncl)
|
||
|
|
- [ADR-034 — Catalog extensibility beyond Rust](../../.ontoref/adrs/adr-034-catalog-extensibility-beyond-rust.ncl)
|
||
|
|
- [`reflection/qa.ncl::ontoref-catalog-extension-howto`](../../.ontoref/reflection/qa.ncl)
|
||
|
|
- [`reflection/qa.ncl::ontoref-catalog-discovery-shared-domain`](../../.ontoref/reflection/qa.ncl)
|