gnomonlearn
Docs/RFC-0039/Reference catalog

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.

← Read the authored RFC

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

TermMeaning
ExportsDeclared outputs the template produces. exports.root is mandatory and names the primary created resource.
Idempotency keyAn expression evaluated once per execution; when present, resources without explicit external_id get derived ids and upsert semantics.
ImportsDeclared inputs the template needs at execution time: scalar values (as: value) or resource references (as: resource).
ObjectsThe body of the template: a named map of resource templates, statement templates, and nested template calls.
Reference resolverThe component that evaluates expressions in template bodies, resolving $ref, $resourceRef, $fn, and other compound forms.
TemplateA named, parameterized declaration that produces a set of resources and statements when executed.
Two-pass executionThe executor runs in two ordered passes — resources (and nested calls) first, statements second — so statement endpoints can reference resources by name.
VisibilityThe cross-module access scope of a template: public, protected (descendants of the declaring namespace), or private (declaring module only).

Diagnostics

CodeSeverityDescription
M39001ErrorRequired import has no value at invocation time
M39002Errorexports..from references a key not present in objects
M39003ErrorCross-module template call violates visibility (protected from non-descendant, or private from another module)
M39010Error$fn references a function not registered in the runtime’s templateFunctions
M39011Error$resourceRef names an object not declared in this template (or not yet executed in the current pass)
M39012Error$ref traversal failed — path does not resolve in the execution context
M39020Errorfor_each declared on a resource template (only permitted on statement templates)
M39030ErrorTemplate execution timed out before completion
M39031ErrorStatement endpoint resolution failed (subject or object did not resolve to a resource id)
M39040Errorpermissions: shorthand entry references a predicate that is not declared in any imported module
M39050WarningTemplate execution returned errors non-empty under continueOnError: true; partial result is being committed
M39060ErrorIdempotency-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

  1. Cross-module template calls MUST respect the declared visibility (public/protected/private) and produce M39003 on violation. (enforced by: compile-time)
  2. Idempotency-key external_id derivation is exactly ’:’; implementations MUST NOT vary the format. (enforced by: runtime)
  3. Required imports without a value at invocation time MUST produce M39001 at the call site. (enforced by: compile-time)
  4. Templates MUST execute Pass 1 (resources), Pass 1.5 (nested calls), then Pass 2 (statements) without interleaving. (enforced by: runtime)
  5. Templates execute within a single transaction; failures roll back all writes. (enforced by: runtime)
  6. The (namespace, external_id) resolver cache is per-execution-context and MUST be invalidated at execution end. (enforced by: runtime)
  7. The expression language is the canonical form from expression-framework; host extensions are limited to the templateFunctions map. (enforced by: compile-time + runtime)
  8. The permissions shorthand expands into predicate_policy declarations at compile time, not at execution time. (enforced by: compile-time)
  9. exports.root is mandatory and MUST reference a key present in the template’s objects map. (enforced by: parse-time)
  10. 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

  1. MUST_NOT — Implementations vary the idempotency-key derivation form. (proof citation: rfc0039_b6_grounded; verification pending)

Expression Language

  1. MUST — Conforming runtimes support the minimum builtin set: now, uuid, uniqueId, hash. (proof citation: rfc0039_b17_grounded; verification pending)
  2. MUST — Implementations evaluate expressions left-to-right and short-circuit $and / $or.
  3. MUST — Map keys are DnsLabel; $-prefixed keys are reserved for compound forms.
  4. MUST_NOT — Reference resolution has side effects; it is a pure read against the execution context. (proof citation: rfc0039_b8_grounded; verification pending)
  5. MUST — Templates referencing an unregistered $fn function produce M39010 at execution time. (proof citation: rfc0039_b19_grounded; verification pending)
  6. MUST — Unresolved $resourceRef names throw M39011. (proof citation: rfc0039_b13_grounded; verification pending)

Invariants

  1. MUST_NOT — Implementations vary the idempotency-key derivation format from ”:”. (proof citation: rfc0039_b27_grounded; verification pending)
  2. MUST — Pass 1 -> Pass 1.5 -> Pass 2 execution order is preserved.
  3. MUST — Templates execute within a single transaction; failures roll back all writes.
  4. MUST — exports.root is mandatory and references an object key.

Object Body

  1. MUST — A statement predicate path resolves to a registered Predicate at execution time. (proof citation: rfc0039_b21_grounded; verification pending)
  2. MUST — Statement subject and object expressions resolve to resource IDs. (proof citation: rfc0039_b34_grounded; verification pending)

Storage and Discovery

  1. MUST — A TemplateContext exposes graph, resolveTemplate, templateFunctions, and imports as fields.
  2. MUST — Templates are content-addressed (hash-keyed) so re-execution with the same inputs produces the same result.

Template Document Envelope

  1. MUST — Cross-module template calls that violate visibility produce M39003 at compile time. (proof citation: rfc0039_b2_grounded; verification pending)
  2. MUST — Exports pointing to nonexistent object keys produce M39002 at parse time. (proof citation: rfc0039_b30_grounded; verification pending)
  3. MUST — Required imports without a corresponding argument at invocation time produce M39001 at the call site. (proof citation: rfc0039_b23_grounded; verification pending)
  4. SHOULD — Templates that do not produce a single primary resource are expressed as multiple smaller templates rather than as a rootless template.
  5. 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

  1. MUST — Authors needing iteration over resource creations express it via nested template calls.
  2. MUST — Cache misses round-trip to the backend. (proof citation: rfc0039_b37_grounded; verification pending)
  3. MUST_NOT — Implementations interleave statements and resources except through the for_each mechanism.
  4. 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)
  5. MUST — The executor populates errors and short-circuits unless continueOnError is set.
  6. 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.
  7. MUST — for_each on a resource template is rejected with M39020 at parse time. (proof citation: rfc0039_b0_grounded; verification pending)

Linked References

DirectionTarget
Depends onRFC-0006
Depends onRFC-0007
Depends onRFC-0036
Depends onRFC-0037
Depends onRFC-0038
Extended byRFC-0040
Extended byRFC-0041
Extended byRFC-0043