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.composeeffect. - 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
| Term | Meaning |
|---|---|
| Template | A named, parameterized declaration that produces a set of resources and statements when executed. |
| Imports | Declared inputs the template needs at execution time: scalar values (as: value) or resource references (as: resource). |
| Exports | Declared outputs the template produces. exports.root is mandatory and names the primary created resource. |
| Objects | The body of the template: a named map of resource templates, statement templates, and nested template calls. |
| Idempotency key | An expression evaluated once per execution; when present, resources without explicit external_id get derived ids and upsert semantics. |
| Visibility | The cross-module access scope of a template: public, protected (descendants of the declaring namespace), or private (declaring module only). |
| Two-pass execution | The executor runs in two ordered passes — resources (and nested calls) first, statements second — so that statement endpoints can reference resources by name. |
| Reference resolver | The 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
| Value | Importable from |
|---|---|
public (default) | Any module |
protected | The declaring module and any module whose namespace descends from the declaring module’s namespace (ltree subtree match) |
private | The 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 shorthandresourceKind=<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>?
namespaceis required. It MAY be an expression that evaluates to an ltree path at execution time (e.g.,{ $ref: "kind" }).external_idis optional. When present, the resource is upsertable by(namespace, external_id).upsert: truerequests find-or-update semantics: if a resource with the same(namespace, external_id)exists, return its id and mergedata.datais the JSON object payload. Its shape is constrained by theresource_typedeclaration fornamespace.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>?
subjectandobjectMUST 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).predicateis 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,$itemrefers to the current element.valid_from/valid_toset the bitemporal interval of the edge (RFC-0036 §4.2).conditionskips 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
| Form | Shape | Meaning |
|---|---|---|
| Literal | string | number | boolean | null | Constant 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:
| Name | Signature | Returns |
|---|---|---|
now | () => Date | The current instant. |
uuid | () => string | A 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 }traversespath(dot-separated) starting from a context object that includes:- The template’s
importsand the caller’switharguments - The currently iterated
$item(withinfor_each)
- The template’s
{ $resourceRef: name }looks upnamein the resource id map populated by Pass 1 (§6.1). Unresolved names MUST throw M39011.- Function calls evaluate their
argsfirst (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
$resourceRefreads 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:
- Evaluates the key expression once at the start of execution. The result is coerced to a string.
- For every resource template without an explicit
external_id, derivesexternal_id = "<key>:<object-name>"and treats the resource asupsert: true. - Looks up the derived
(namespace, external_id)in the backend; if found, returns that resource’s id and updates itsdata(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 kind | Purpose |
|---|---|
file | Local filesystem (development; bundle-time loading) |
url | Network-fetched (registry, CDN) |
memory | In-memory cache (testing; programmatic seeding) |
inline | Embedded 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 lookuptemplateFunctions: Map<String, Function>— host-registered builtins (§5.2)- Imports as fields on the context object — the reference resolver reads them via
$ref
8. Invariants
exports.rootis mandatory and MUST reference an object key (§3.2).- Required imports without a value at invocation time MUST produce M39001 (§3.1).
- Visibility violations on cross-module template calls MUST produce M39003 (§3.3).
- The execution order Pass 1 → Pass 1.5 → Pass 2 MUST be preserved (§6.1).
- Idempotency-key derivation is exactly
"<key>:<object-name>"(§6.2); implementations MUST NOT vary the format. for_eachis permitted only on statement templates (§6.4); resource templates MUST reject it.- Resource-id cache is per-execution-context and MUST be invalidated at execution end (§6.3).
- The expression language is the canonical form from
expression-framework(§5); host extensions are limited to thetemplateFunctionsmap. - Templates execute within a single transaction; failures roll back all writes (RFC-0038 §3.4).
- The
permissions:shorthand expands topredicate_policydeclarations 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 file | This 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:
conditionis normative on resource and statement templates. The legacy executor honors aconditionexpression 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_eachban 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.