gnomonlearn
Docs/Graph/RFC-0039

RFC-0039 · Graph Templates

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.

Status Draft corpus. Reference catalogs and RDF projections have generation drift checks; Gnomon proofs and projection semantics remain unverified for release.

View the generated reference catalog →

Read design questions and decisions →


Reference catalog: the diagnostics, linked-RFC graph, defined terms, and normative-rule index for this RFC are in the reference catalog, generated from the structured Lean module. This document carries the prose: design rationale, entity-shape definitions in context, and migration notes.


1. Purpose

A graph template is a parameterized, reusable fragment of graph structure: a set of resources and statements with imports, exports, and idempotency. Templates are the unit of composition for higher-level constructs:

  • Modules instantiate templates at install time (RFC-0041) to provision their initial graph state.
  • Operations invoke templates at request time (RFC-0043) via the template.compose effect.
  • Templates can call other templates, building dense abstractions out of low-level primitives.

This RFC specifies the template document envelope, the two-pass execution model, the expression language used in template bodies, the idempotency-key contract, the visibility rules that gate cross-module template imports, and the shorthand permissions form that compiles to predicate policies (RFC-0042).

This is a faithful codification of the executor at /Volumes/Workspace/savvi-studio-full/packages/graph-template-engine/executor.ts and the model at /Volumes/Workspace/savvi-studio-full/packages/graph-template-model/.


2. Definitions

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

3. Template Document Envelope

A template is a standalone document with a Kubernetes-style envelope:

apiVersion: gnomon/v1
kind:       Template
metadata:
  namespace:   <ltree path>     // declaring module's namespace
  name:        <DnsLabel>       // unique within the module
  version:     <semver>
  description: <text>
imports:
  <name>:
    as:        value | resource
    type:      <type-expr>      // for value imports
    required:  boolean           // default true
exports:
  root:                          // required
    as:   resource | value
    from: <object-name>          // key in objects map
  <other>:
    as:   resource | value | template
    from: <object-name>
objects:
  <name>:
    type: resource | statement | <qualified-template-call>
    ...
idempotency:                     // optional
  key: <expression>
permissions:                     // optional shorthand
  <predicate-ref>: <permission-level>
visibility: public | protected | private    // default public

3.1 Imports

Imports declare what the template needs at execution time. The grammar is:

import-decl ::= IDENT ":" "{" import-body "}"
import-body ::= "as"        ":" ("value" | "resource") NEWLINE
                "type"      ":" type-expr NEWLINE                  (* required if as: value *)
                ["required" ":" BOOL NEWLINE]                       (* default true *)
                ["description" ":" STRING NEWLINE]

When as: value, the import accepts a scalar or structured value (string, number, boolean, object). When as: resource, the import accepts a resource ID (bigint).

Required imports without a corresponding argument at invocation time MUST produce M39001 at the call site.

3.2 Exports

exports.root is mandatory. Its from field MUST reference a key in objects, and the referenced object MUST be a resource (or, for value-form templates, an evaluable expression). Templates that do not produce a single primary resource SHOULD be expressed as multiple smaller templates rather than as a rootless template.

Additional exports MAY be declared for secondary resources, derived values, or re-exported template references. Exports that point to nonexistent object keys MUST produce M39002 at parse time.

3.3 Visibility

ValueImportable from
public (default)Any module
protectedThe declaring module and any module whose namespace descends from the declaring module’s namespace (ltree subtree match)
privateThe declaring module only

A cross-module template call that violates visibility MUST produce M39003 at compile time.

3.4 Permissions shorthand

The permissions: map is a compile-time shorthand that expands into predicate_policy module objects (RFC-0042). The mapping is:

permissions:
  <predicate-ref>: <permission-level>

becomes one predicate_policy per entry, with:

  • predicate = resolved ltree path (unqualified names are prefixed with the declaring module’s namespace; qualified names are used as-is)
  • permissionLevel = the named level from the shorthand
  • resourceKind = <declaring-module>.<template-name>
  • matchMode = subtree

This expansion is performed by RFC-0040 §module compile pipeline and RFC-0044 §permissions transform.


4. Object Body

The objects section is a named map. Each entry has a type discriminant:

objects-entry ::= IDENT ":" "{" object-body "}"
object-body   ::= type-discriminant "{" slot-assigns "}"
type-discriminant ::= "type" ":" ("resource" | "statement" | qualified-template-name)
qualified-template-name ::= IDENT ("." IDENT)+ | IDENT ":" IDENT      (* e.g. core.type, rdfs.class, schema:name *)

4.1 Resource template

type: resource
namespace:    <ltree-path | expression>
external_id:  <expression>?
upsert:       boolean?
data:         <object | expression>?
condition:    <expression>?
  • namespace is required. It MAY be an expression that evaluates to an ltree path at execution time (e.g., { $ref: "kind" }).
  • external_id is optional. When present, the resource is upsertable by (namespace, external_id).
  • upsert: true requests find-or-update semantics: if a resource with the same (namespace, external_id) exists, return its id and merge data.
  • data is the JSON object payload. Its shape is constrained by the resource_type declaration for namespace.
  • condition, when present, is evaluated to a boolean; when false, the object is skipped (no resource is created).

4.2 Statement template

type: statement
subject:    <expression>      // resolves to a resource id
predicate:  <ltree-path | expression>
object:     <expression>
data:       <object>?
for_each:   <expression>?      // iterate, creating one statement per item
valid_from: <expression>?
valid_to:   <expression>?
condition:  <expression>?
  • subject and object MUST resolve to resource IDs. The reference resolver supports plain object names (refers to a resource declared in the same template), { $resourceRef: "name" } (explicit form), and bare { $ref: "name" } (which is resolved as a resource reference if a name match exists).
  • predicate is either an ltree path string or an expression that evaluates to one. The path MUST resolve to a registered Predicate (RFC-0036 §4.3) at execution time.
  • for_each, when present, evaluates to an array; one statement is emitted per element. Within the iterating expression, $item refers to the current element.
  • valid_from / valid_to set the bitemporal interval of the edge (RFC-0036 §4.2).
  • condition skips the statement when false.

4.3 Nested template call

Any object whose type is a qualified name (containing . or : and not starting with . or /) is interpreted as a nested template invocation:

type: <module-alias>.<template-name>
with:
  <import-name>: <expression>
  ...

Examples: core.type, rdfs.class, schema:name. The qualified name is resolved through the declaring module’s templates import (RFC-0040 §templates).

The nested call’s exports are accessible as a resource reference via the call’s object name. For example:

objects:
  user:
    type: identity.user-identity
    with:
      user-key:     { $ref: "userId" }
      email:        { $ref: "email" }
      display-name: { $ref: "name" }
  user_membership:
    type: statement
    subject: user                        # resource ref to the nested template's root
    predicate: org.member
    object: { $ref: "orgId" }

5. Expression Language

Expressions appear in namespace, external_id, data, subject, predicate, object, for_each, valid_from, valid_to, and condition slots. The grammar is normative and is shared with the broader Gnomon runtime via @savvi-studio/expression-framework.

5.1 Expression forms

FormShapeMeaning
Literalstring | number | boolean | nullConstant value. Note: literal null is permitted in expressions but null-coercion at the data-write boundary applies (RFC-0036 §7.2).
List[ <expr>, ... ]Array of values.
Map{ <key>: <expr>, ... }Object with expression-valued fields. Keys MUST be DnsLabel; $-prefixed keys are reserved for compound forms.
Reference{ $ref: "<dot.path>" }Resolves to a value in the execution context. Dot-path traverses imports, with args, and runtime fields.
Resource reference{ $resourceRef: "<object-name>" }Resolves to the bigint id of a resource declared earlier in this template.
Function call{ $fn: "<name>" } or { $fn: { name: "<name>", args: [<expr>, ...] } }Invokes a builtin or host-registered function.
Conditional{ $exists: "<dot.path>" }, { $notEmpty: "<dot.path>" }Boolean conditions.
Logical{ $and: [<expr>, ...] }, { $or: [<expr>, ...] }Combine boolean expressions.
Item{ $item: <expr> }Within for_each, refers to the iteration’s current element.

The full Zod schema is canonical at /Volumes/Workspace/savvi-studio-full/packages/expression-framework/expression.ts.

5.2 Builtin functions

The minimum builtin set MUST be supported by every conforming runtime:

NameSignatureReturns
now() => DateThe current instant.
uuid() => stringA version-4 UUID.
uniqueId() => string | Promise<string>An implementation-chosen unique id.
hash(value, ...) => Promise<string>A stable hash of the supplied values; canonical algorithm SHA-256 hex.

Hosts MAY register additional functions via templateFunctions on the execution context. Templates that reference an unregistered function MUST produce M39010 at execution time.

5.3 Reference resolution semantics

Reference resolution is a pure read against the execution context — it MUST NOT have side effects:

  • { $ref: path } traverses path (dot-separated) starting from a context object that includes:
    • The template’s imports and the caller’s with arguments
    • The currently iterated $item (within for_each)
  • { $resourceRef: name } looks up name in the resource id map populated by Pass 1 (§6.1). Unresolved names MUST throw M39011.
  • Function calls evaluate their args first (left to right), then invoke the function with the resolved argument list.

Implementations MUST evaluate expressions left-to-right and short-circuit $and / $or.


6. Two-Pass Execution

6.1 Pass ordering

Templates execute in three sub-phases, all within a single transaction:

Pass 1   — Resources
Pass 1.5 — Nested template calls (recursive)
Pass 2   — Statements

This ordering exists because:

  • Resource creations populate the resource-id map that $resourceRef reads in subsequent expressions.
  • Nested template calls return a root-resource id, which acts like a top-level resource for the purposes of subsequent statement endpoints.
  • Statements depend on their subject and object resources existing first.

Implementations MUST NOT interleave statements and resources except through the for_each mechanism (§6.4).

6.2 Idempotency key

When the template declares idempotency.key, the executor:

  1. Evaluates the key expression once at the start of execution. The result is coerced to a string.
  2. For every resource template without an explicit external_id, derives external_id = "<key>:<object-name>" and treats the resource as upsert: true.
  3. Looks up the derived (namespace, external_id) in the backend; if found, returns that resource’s id and updates its data (merge); if not found, creates the resource with the derived id.

The string concatenation form is fixed (<key>:<object-name>) for stability. Templates that need a different derivation MUST set explicit external_id expressions on their resources.

6.3 Resolver caching

Within a single template execution, the executor MUST cache (namespace, external_id) → resource-id lookups. The cache is per-execution-context and MUST be invalidated when the template execution ends (success or failure). Cache misses MUST round-trip to the backend.

6.4 for_each semantics

Statement templates with for_each evaluate the iterating expression to an array, then emit one statement per element. Within the body of the statement, $ref: "$item" (or shorthand { $item: ... }) refers to the current element.

Resources are emitted only in Pass 1. for_each on a resource template MUST be rejected with M39020 at parse time. Authors who need iteration over resource creations MUST express it via nested template calls (Pass 1.5).

6.5 Execution result

A successful execution returns:

TemplateExecutionResult {
  resourceIds:      Map<String, bigint>     // by object name
  statementIds:     Map<String, bigint[]>   // by object name; arrays support for_each
  rootResourceName: String | null           // exports.root.from value
  rootResourceId:   bigint | null
  errors:           String[]                // empty on success
  duration:         number                  // milliseconds
}

The executor MUST populate errors as it encounters failures and short-circuit unless continueOnError is set. The duration field is for observability (RFC-0047) and is informational.

6.6 Timeout

An optional timeout (milliseconds) MAY be passed at invocation time. When set, the entire execution (all passes) MUST complete within the timeout; otherwise the executor MUST raise a timeout error and the enclosing transaction MUST be rolled back.


7. Storage and Discovery

Templates are persisted via the storage backends defined in @savvi-studio/graph-template-storage. The four supported sources are:

Source kindPurpose
fileLocal filesystem (development; bundle-time loading)
urlNetwork-fetched (registry, CDN)
memoryIn-memory cache (testing; programmatic seeding)
inlineEmbedded in module manifest (RFC-0040 inline templates)

The executor’s GraphTemplateContext carries a resolveTemplate(source) → Template function that the runtime injects. Templates MUST be content-addressed (hash-keyed) so that re-execution with the same inputs and the same resolved template produces the same result.

A TemplateContext MUST expose:

  • graph: TransactionalGraphClient — the write surface (RFC-0038)
  • resolveTemplate(source): Promise<Template> — registry lookup
  • templateFunctions: Map<String, Function> — host-registered builtins (§5.2)
  • Imports as fields on the context object — the reference resolver reads them via $ref

8. Invariants

  1. exports.root is mandatory and MUST reference an object key (§3.2).
  2. Required imports without a value at invocation time MUST produce M39001 (§3.1).
  3. Visibility violations on cross-module template calls MUST produce M39003 (§3.3).
  4. The execution order Pass 1 → Pass 1.5 → Pass 2 MUST be preserved (§6.1).
  5. Idempotency-key derivation is exactly "<key>:<object-name>" (§6.2); implementations MUST NOT vary the format.
  6. for_each is permitted only on statement templates (§6.4); resource templates MUST reject it.
  7. Resource-id cache is per-execution-context and MUST be invalidated at execution end (§6.3).
  8. The expression language is the canonical form from expression-framework (§5); host extensions are limited to the templateFunctions map.
  9. Templates execute within a single transaction; failures roll back all writes (RFC-0038 §3.4).
  10. The permissions: shorthand expands to predicate_policy declarations at compile time, not at execution time (§3.4).

9. Compatibility and Migration

9.1 From legacy graph-template-model and graph-template-engine

This RFC is a faithful codification:

Legacy fileThis RFC
graph-template-model/model/template.ts (envelope)§3
graph-template-model/model/objects.ts (resource/statement/call)§4
graph-template-model/model/expression.ts (re-exported from expression-framework)§5
graph-template-engine/executor.ts (two-pass execution, idempotency)§6
graph-template-engine/reference-resolver.ts§5.3
graph-template-engine/functions/{now,uuid,uniqueId,hash}.ts§5.2
graph-template-storage/{file,url,memory}.ts§7

9.2 Inline template object in module manifests

Templates MAY appear inline in a module manifest’s objects section as template-typed entries. The shape is identical to the standalone template document but the metadata.namespace and metadata.name are injected by the bundler at compile time from the manifest’s namespace and the object’s map key. RFC-0040 specifies the bundler behavior.

9.3 Behavior changes

This RFC introduces the following changes vs. the legacy implementation:

  • condition is normative on resource and statement templates. The legacy executor honors a condition expression but does not document it in the schema. This RFC makes it part of the normative envelope (§4.1, §4.2).
  • Idempotency-key derivation form is locked. The legacy code uses ${key}:${objectName}; this RFC fixes that as the canonical derivation. Implementations MUST NOT vary it.
  • The for_each ban on resource templates is normative. The legacy code does not formally reject it; this RFC specifies M39020.

Diagnostics

The diagnostic catalog for this RFC is authored in the structured Lean module and rendered in reference catalog § Diagnostics. Inline mentions in the prose above (e.g., “rejected with MNNxxx”) cross-link to the catalog at render time.

Linked References

The cross-RFC dependency graph is rendered in reference catalog § Linked References. Out-of-KG pointers to legacy code or external resources, when present, remain in this document under “Source-tree references” below.