RFC-0039 · Reference catalog
Versioned draft snapshot
RFCs, reference catalogs, and evidence reflect Spec 3b2e3e7a114fb826b1445d39a48756b8fff629cd. Counts and pending/status notes belong to that snapshot. Read the dated project update for later progress.
Source repositories are private during staging. Links marked “repository access required” need access to the linked repository.
Generated reference catalog. This page renders structured Lean data for RFC-0039: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in
RFC-0039.This page is generated from the
lean/Gnomon/Spec/module for RFC-0039. Edit that source and regenerate this catalog.
Title: Graph Templates
Status: draft
Owners: Graph Platform, Module Platform
Diagnostic range: M39000-M39099
Depends on: RFC-0006, RFC-0007, RFC-0036, RFC-0037, RFC-0038
Extended by: RFC-0040, RFC-0041, RFC-0043
Proof citations in source: 14 / 14. Standalone proof verification is pending.
Definitions
| Term | Meaning |
|---|---|
| Exports | Declared outputs the template produces. exports.root is mandatory and names the primary created resource. |
| Idempotency key | An expression evaluated once per execution; when present, resources without explicit external_id get derived ids and upsert semantics. |
| Imports | Declared inputs the template needs at execution time: scalar values (as: value) or resource references (as: resource). |
| Objects | The body of the template: a named map of resource templates, statement templates, and nested template calls. |
| Reference resolver | The component that evaluates expressions in template bodies, resolving $ref, $resourceRef, $fn, and other compound forms. |
| Template | A named, parameterized declaration that produces a set of resources and statements when executed. |
| Two-pass execution | The executor runs in two ordered passes — resources (and nested calls) first, statements second — so statement endpoints can reference resources by name. |
| Visibility | The cross-module access scope of a template: public, protected (descendants of the declaring namespace), or private (declaring module only). |
Diagnostics
| Code | Severity | Description |
|---|---|---|
M39001 | Error | Required import has no value at invocation time |
M39002 | Error | exports. |
M39003 | Error | Cross-module template call violates visibility (protected from non-descendant, or private from another module) |
M39010 | Error | $fn references a function not registered in the runtime’s templateFunctions |
M39011 | Error | $resourceRef names an object not declared in this template (or not yet executed in the current pass) |
M39012 | Error | $ref traversal failed — path does not resolve in the execution context |
M39020 | Error | for_each declared on a resource template (only permitted on statement templates) |
M39030 | Error | Template execution timed out before completion |
M39031 | Error | Statement endpoint resolution failed (subject or object did not resolve to a resource id) |
M39040 | Error | permissions: shorthand entry references a predicate that is not declared in any imported module |
M39050 | Warning | Template execution returned errors non-empty under continueOnError: true; partial result is being committed |
M39060 | Error | Idempotency-key expression evaluated to a value that cannot be coerced to a non-empty string |
Dependency neighborhood
graph LR
nRFC_0039["RFC-0039"]
nRFC_0006["RFC-0006"]
nRFC_0039 --> nRFC_0006
nRFC_0007["RFC-0007"]
nRFC_0039 --> nRFC_0007
nRFC_0036["RFC-0036"]
nRFC_0039 --> nRFC_0036
nRFC_0037["RFC-0037"]
nRFC_0039 --> nRFC_0037
nRFC_0038["RFC-0038"]
nRFC_0039 --> nRFC_0038
nRFC_0040["RFC-0040"]
nRFC_0040 --> nRFC_0039
nRFC_0041["RFC-0041"]
nRFC_0041 --> nRFC_0039
nRFC_0043["RFC-0043"]
nRFC_0043 --> nRFC_0039
Invariants
- Cross-module template calls MUST respect the declared visibility (public/protected/private) and produce M39003 on violation. (enforced by: compile-time)
- Idempotency-key external_id derivation is exactly ’
: ’; implementations MUST NOT vary the format. (enforced by: runtime) - Required imports without a value at invocation time MUST produce M39001 at the call site. (enforced by: compile-time)
- Templates MUST execute Pass 1 (resources), Pass 1.5 (nested calls), then Pass 2 (statements) without interleaving. (enforced by: runtime)
- Templates execute within a single transaction; failures roll back all writes. (enforced by: runtime)
- The (namespace, external_id) resolver cache is per-execution-context and MUST be invalidated at execution end. (enforced by: runtime)
- The expression language is the canonical form from expression-framework; host extensions are limited to the templateFunctions map. (enforced by: compile-time + runtime)
- The permissions shorthand expands into predicate_policy declarations at compile time, not at execution time. (enforced by: compile-time)
- exports.root is mandatory and MUST reference a key present in the template’s objects map. (enforced by: parse-time)
- for_each is permitted only on statement templates; resource templates MUST reject it with M39020. (enforced by: parse-time)
Normative Statements
Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.
Compatibility and Migration
- MUST_NOT — Implementations vary the idempotency-key derivation form. (proof citation:
rfc0039_b6_grounded; verification pending)
Expression Language
- MUST — Conforming runtimes support the minimum builtin set: now, uuid, uniqueId, hash. (proof citation:
rfc0039_b17_grounded; verification pending) - MUST — Implementations evaluate expressions left-to-right and short-circuit $and / $or.
- MUST — Map keys are DnsLabel; $-prefixed keys are reserved for compound forms.
- MUST_NOT — Reference resolution has side effects; it is a pure read against the execution context. (proof citation:
rfc0039_b8_grounded; verification pending) - MUST — Templates referencing an unregistered $fn function produce M39010 at execution time. (proof citation:
rfc0039_b19_grounded; verification pending) - MUST — Unresolved $resourceRef names throw M39011. (proof citation:
rfc0039_b13_grounded; verification pending)
Invariants
- MUST_NOT — Implementations vary the idempotency-key derivation format from ”
: ”. (proof citation: rfc0039_b27_grounded; verification pending) - MUST — Pass 1 -> Pass 1.5 -> Pass 2 execution order is preserved.
- MUST — Templates execute within a single transaction; failures roll back all writes.
- MUST — exports.root is mandatory and references an object key.
Object Body
- MUST — A statement predicate path resolves to a registered Predicate at execution time. (proof citation:
rfc0039_b21_grounded; verification pending) - MUST — Statement subject and object expressions resolve to resource IDs. (proof citation:
rfc0039_b34_grounded; verification pending)
Storage and Discovery
- MUST — A TemplateContext exposes graph, resolveTemplate, templateFunctions, and imports as fields.
- MUST — Templates are content-addressed (hash-keyed) so re-execution with the same inputs produces the same result.
Template Document Envelope
- MUST — Cross-module template calls that violate visibility produce M39003 at compile time. (proof citation:
rfc0039_b2_grounded; verification pending) - MUST — Exports pointing to nonexistent object keys produce M39002 at parse time. (proof citation:
rfc0039_b30_grounded; verification pending) - MUST — Required imports without a corresponding argument at invocation time produce M39001 at the call site. (proof citation:
rfc0039_b23_grounded; verification pending) - SHOULD — Templates that do not produce a single primary resource are expressed as multiple smaller templates rather than as a rootless template.
- MUST — exports.root.from references a key in objects, and the referenced object is a resource (or evaluable expression for value-form templates).
Two-Pass Execution
- MUST — Authors needing iteration over resource creations express it via nested template calls.
- MUST — Cache misses round-trip to the backend. (proof citation:
rfc0039_b37_grounded; verification pending) - MUST_NOT — Implementations interleave statements and resources except through the for_each mechanism.
- MUST — The executor caches (namespace, external_id) -> resource-id lookups within a single template execution and invalidates the cache at execution end. (proof citation:
rfc0039_b15_grounded; verification pending) - MUST — The executor populates errors and short-circuits unless continueOnError is set.
- MUST — When a timeout is set, the entire execution completes within it; otherwise the executor raises a timeout error and the enclosing transaction is rolled back.
- MUST — for_each on a resource template is rejected with M39020 at parse time. (proof citation:
rfc0039_b0_grounded; verification pending)
Linked References
| Direction | Target |
|---|---|
| Depends on | RFC-0006 |
| Depends on | RFC-0007 |
| Depends on | RFC-0036 |
| Depends on | RFC-0037 |
| Depends on | RFC-0038 |
| Extended by | RFC-0040 |
| Extended by | RFC-0041 |
| Extended by | RFC-0043 |