Query-plan V3 wire format¶
V3 is an ordered, schema-checked read/write program encoded as canonical UTF-8 JSON. A producer can construct these bytes without Rust. SDKs delegate encoding and validation to Rust. This document specifies the format, its TypeQL lowering, the shared builder and batch-split rules, and the staged remote envelope that carries ordered stacks of plans.
Root object¶
Required members are format, bindings, inputs, functions, pipeline,
output, operation, managed_semantics, and required_capabilities.
format is exactly typebridge.query-plan/v3. Optional given_rows and
compatibility members are omitted when absent. Empty required arrays remain
present. Unknown fields, duplicate keys, unknown tags and forged capability
claims are rejected. The schema is provided separately to the decoder; the
embedded managed fingerprint is an expected identity, not schema authority.
Execution must compare it with the receiving authority before sending a query.
| Member | Shape |
|---|---|
bindings |
Ordered [{"id":0,"variable":"item"},...] |
inputs |
Ordered [{"id":0,"optional":false,"public_name":"item_id","value_type":"string"},...] |
functions |
Ordered local function declarations or [] |
pipeline |
Nonempty ordered stage array |
output |
Rows or documents, below |
operation |
Terminal operation, below |
managed_semantics |
Managed schema fingerprint object |
required_capabilities |
Sorted duplicate-free array of derived strings |
Binding IDs and input IDs are separate dense zero-based unsigned sequences.
Bindings number at most 256. Variables and public names are unique identifiers matching
[a-z][a-z0-9_]*, at most 128 UTF-8 bytes. Array order and variable spelling
are part of identity.
A type is {"kind":"entity","label":"account"}, with kind entity,
relation or attribute. An attribute is a label string. A role is
{"declaring_relation":"membership","label":"member"}. An ownership is
{"attribute":"score","owner":{"kind":"entity","label":"account"}}.
Labels are at most 255 UTF-8 bytes: first character _ or Unicode XID_Start,
then Unicode XID_Continue or -. The exact reserved labels are with, given,
match, fetch, update, define, undefine, redefine, insert, put,
delete, end, entity, relation, attribute, role, asc, desc, struct,
fun, return, alias, sub, owns, as, plays, relates, iid, isa,
links, has, is, or, not, try, in, true, false, of, from,
first, last. Function-call names additionally exclude builtin spellings
abs, ceil, floor, iid, label, len, max, min, round.
The common serialized semantic identity ceiling is 512 bytes.
Fingerprints contain algorithm (sha256), canonicalization, digest (64
lowercase hex digits), domain, and an optional semantic_profile. The managed
fingerprint uses domain typebridge.schema.managed-semantic, canonicalization
typebridge.managed-semantic/v1, and the provider profile. Its digest is opaque
and cannot be derived from plan bytes.
Scalars, operands and expressions¶
| Domain | Wire value |
|---|---|
| string | {"kind":"string","value":"text"} |
| long | {"kind":"long","value":"-42"}; signed 64-bit decimal string |
| double | {"bits":"3ff0000000000000","kind":"double"}; finite binary64 bits, 16 lowercase hex digits |
| boolean | {"kind":"boolean","value":true} |
| decimal | {"kind":"decimal","value":"1.25"} |
| date | {"kind":"date","value":"2026-10-15"} |
| datetime | {"kind":"datetime","value":"2026-10-15T12:00:00"} |
| datetime_tz | {"kind":"datetime_tz","value":{"effective_offset_seconds":0,"local":"2026-10-15T12:00:00","zone":{"kind":"utc"}}} |
| duration | {"kind":"duration","value":"P1DT7200S"} |
Longs have no leading plus or redundant zeros. Decimal strings have no exponent,
dec suffix or redundant leading/trailing zeros; zero is 0. At most 19
fractional digits are accepted. The whole part fits signed 64-bit; the negative
minimum cannot have a nonzero fractional part. Double bits
preserve negative zero; NaN and infinity fail. Dates are Gregorian in years -262143 through 262142, with four year digits for
0..9999, a leading plus for larger positive years and a minus for negative
years. Month/day are two digits. Datetimes append T and HH:MM:SS, optionally
1..9 fractional second digits with no trailing zero; hours are 0..23 and minutes
and seconds 0..59. There are no leap seconds.
Datetime-tz's value is an object with local, zone and
effective_offset_seconds. Zone is {"kind":"utc"} (effective offset zero),
{"kind":"offset_seconds","seconds":3600} (same nonzero effective offset),
or {"kind":"named","name":"Europe/London"} with provider-resolved effective
offset. Absolute offsets are at most 86399 seconds. A named zone is 1..255 ASCII
bytes from letters, digits, /, _, -, +; the producer supplies the
resolved offset without relying on receiver timezone-database versions.
Duration spelling is optional -, P, optional unsigned months plus M,
optional unsigned days plus D, then optional T seconds plus S. Seconds may
have 1..9 fractional digits with no trailing zero. Components are u64; omit zero
components and use PT0S for zero, never negative zero. There are no year/week/
hour/minute components in canonical bytes; convert those to months/days/seconds.
Operands have exactly one of these shapes:
{"binding":0,"kind":"binding"}
{"kind":"literal","value":{"kind":"long","value":"1"}}
{"column":0,"kind":"input"}
Expressions use adjacent kind / value tags:
| Kind | value |
|---|---|
operand |
One operand |
arith |
{"op":"sub","lhs":expression,"rhs":expression} |
call |
{"func":"abs","args":[expression,...]} |
Arithmetic operators are add, sub, mul, div, mod, pow. Both arguments
must be numeric. Add/sub/mul promote double over decimal over long. Div/pow
always return double. Mod returns long for two longs and double otherwise.
These rules match TypeDB 3.13.6.
| Builtin | Arguments | Result |
|---|---|---|
| abs | One numeric | Same domain |
| ceil, floor, round | One decimal or double | Long |
| min, max | Exactly two numerics of the same domain | Same domain |
| length | One string | Long |
Binding operands must be present scalar bindings with schema-inferred attribute or function-return domains. Input operands must reference required columns. Write assignments require the exact target attribute domain: arithmetic promotion does not implicitly cast its result back to that domain.
Match patterns¶
A match is {"kind":"match","patterns":[...]}. Patterns form a conjunction.
In the table, B is a binding ID, T a type, R a role, O an operand, P a pattern.
Member names are literal wire names, and each listed member is required.
kind |
Additional members |
|---|---|
| isa | binding:B, type_id:T, include_subtypes:boolean |
| has | owner:B, attribute:B, attribute_id:string |
| links | relation:B, relation_id:T, players:[{"player":B,"role":R},...] |
| value | left:O, comparator:string, right:O |
| or | branches:[[P,...],...] |
| not, try | patterns:[P,...] |
| reachable | source:B, target:B, relation:T, role_from:R, role_to:R, min_depth:integer, max_depth:integer |
| function_call | assigned:B, function:string, arguments:[O,...] |
| let | binding:B, expr:expression |
| iid | binding:B, iid:string |
Comparators are equal, not_equal, less, less_or_equal, greater,
greater_or_equal. Boolean branches are nonempty. Reachability bounds satisfy
0 <= min_depth <= max_depth <= 64 (the receiver's predicate-depth limit),
with root-only reachability and expanded-hop node-budget checks. Functions use checked declarations and
argument/return types. Nested boolean bodies and local functions retain the
released read-pattern vocabulary: let and iid are V3 root-match patterns.
An iid pattern names a canonical thing IID (0x followed by 1..256
hexadecimal digits) and constrains a mandatory binding that positive patterns
of the same match type only as entities or relations; it adds
query.pattern.iid.
Let assigns a fresh declared scalar binding in source order. It cannot overwrite an earlier let, concept, attribute or function result, including one produced in only one disjunction arm. Forward/cyclic expression references fail. Positive matches establish mandatory bindings; disjunction exports the intersection of mandatory bindings. Try-only bindings are optional; negated bindings do not escape. Every write target must be mandatory and alive.
Local functions have name, bindings, parameters, body, returns.
Parameters are ordered label strings. Bindings use an independent dense scope.
Returns is {"input":0,"reducer":"count","value_type":"long"}. Local returns
admit only count (long) and sum (numeric), total on empty streams. Bodies are
flat isa/has/links/value patterns; parameters declare leading bindings by schema
type label. Undeclared or recursive calls are invalid. Pipeline reducers also
admit max, min, mean, median, std under the read contract's domain and
empty-stream checks.
Stages and output¶
The first stage is match, insert or put. Match can occur only first. Writes may follow in any order before the read tail. Write stage payloads are nonempty.
kind |
Additional members |
|---|---|
| insert, put | things:[Thing,...] |
| update | sets:[Set,...] |
| delete | items:[Delete,...] |
| attach | items:[Attach,...] |
| fetch | thing:B, roles:[{"role":R,"required":boolean},...] |
A Thing has binding, type_id, fields, players. Fields are ordered pairs
[[ownership,operand],...]; players are ordered pairs [[role,binding],...].
Absent fields/players use empty arrays. Insert/put bind fresh variables of
concrete declared entity/relation types; attribute types are refused. Relations
require at least one role player, and a player may be created in the same stage. Ownership, relates and plays facts
must be declared, including inherited declarations.
A Set is {"kind":"field","owner":B,"field":ownership,"operand":O} or
{"kind":"link","relation":B,"role":R,"player":B}. Key ownerships cannot
be updated, including keys declared on any descendant of a subtype-inclusive
match. Descendants are enumerated from the declared subtype facts. A Delete is {"kind":"thing","binding":B},
{"kind":"has","owner":B,"field":ownership}, or
{"kind":"links","relation":B,"role":R,"player":B}, or
{"kind":"players","relation":B,"role":R}. A players deletion removes every
player of one declared role, as an ownership deletion removes every value;
every possible type of the relation binding must descend from the role's
declaring relation. Followed by an attach, it replaces a multi-player role.
Thing deletion ends its binding lifetime after that stage (all thing
deletions of a stage end together at its boundary, not in item order);
scalar let/function results are not thing deletion targets; later
stages/output cannot refer to it.
Ownership/link/players deletion leaves the owner/relation alive. All inferred possible
owner/player types must satisfy the requested fact; inference is conservative.
An Attach is {"kind":"has","owner":B,"field":ownership,"operand":O} or
{"kind":"links","relation":B,"role":R,"player":B}. It adds a value or a
player to a bound thing and keeps the existing ones, which update (a
replacement, valid only up to one value) cannot do for multi-valued
ownerships and roles. Key ownerships cannot be attached. Targets, operands
and roles are checked as for update. An attach adds query.write.attach.
A fetch is {"kind":"fetch","thing":B,"roles":[{"required":true,"role":R},...]}
and must be the last stage. It answers one hydration document per row for a
present (mandatory, not optional) binding typed only as entities or
relations, so the operation is rows or write returning rows, and the
declared output is {"kind":"rows","columns":[]}. Each listed role must be
declared, every possible type of the thing must descend from the role's
declaring relation, and a role is listed once. Document keys are fixed:
_iid, _type (the exact type label), attributes (every owned attribute),
and for the role at position N: _role_N_iid, _role_N_type,
_role_N_attributes. A required role must be filled (an unfilled one drops
the row); an optional role's keys are absent when it is unfilled; several
players of a role give one document per player combination. A fetch adds
query.fetch.thing.
query.write.attach and query.fetch.thing are derived from the plan but
not advertised yet: they are absent from the V3 capability vocabulary that
the staged advertisement publishes (see Capabilities), so a
staged request carrying an attach or a fetch fails capability admission with
unsupported_required_capability. The fixtures attach.json,
replace_players.json (players deletion then attach), fetch_entity.json
and fetch_relation.json in tests/contracts/plan_v3 show their canonical
bytes.
The read tail is an ordered subsequence of this list, each stage at most once:
kind |
Additional members |
|---|---|
| select, require | bindings:[B,...] |
| distinct | None |
| reduce | assignments:[{"assigned":B,"input":B,"reducer":"count"},...], groups:[B,...] |
| sort | terms:[{"binding":B,"direction":"ascending"},...] |
| offset, limit | rows:unsigned_integer |
Sort directions are ascending/descending. Select restricts scope; require
makes visible optional bindings mandatory. Reduce exposes grouping bindings
and fresh reduction results. Output and ordering must respect the resulting
scope. Duplicate selected/output bindings and sort terms fail. Offset and limit require
an explicit preceding sort. A sort term on a duration binding fails
(query_plan_sort_unordered_value), and a value pattern that orders a
duration operand with less, less_or_equal, greater or
greater_or_equal fails (query_plan_duration_range): TypeDB 3.14 refuses
both, so the builder refuses them on every profile before any server sees
them. Equality on durations stays admitted.
Rows output is {"kind":"rows","columns":[B,...]}. Documents output is
{"kind":"documents","fields":[{"key":"item","source":{"kind":"binding","binding":0}}]}.
A source may instead be
{"kind":"attribute_list","owner":0,"attribute":"tag"}. Document keys
are unique validated output names.
Operations are {"kind":"rows"}, {"kind":"count"}, {"kind":"exists"},
{"kind":"write","returns":"matched"}, or
{"kind":"write","returns":"rows"}. Write requires a write stage; read
operations reject write stages. Rows/write-rows require a projection;
write-matched requires {"kind":"rows","columns":[]}. Count/exists allow
empty rows output. Write-matched counts matched pipeline rows, not individual
field changes. Write-rows projects the same pipeline after the writes.
Given rows¶
Optional given_rows is a nonempty array of positional rows. Each row contains
exactly one canonical scalar or null per input column. Domains must match;
null is permitted only for optional columns. Supplied rows require nonempty
input declarations. The ceiling is 4,096 rows and 4 MiB canonical row-array
bytes. Bound rows participate in the plan fingerprint.
Omission preserves a reusable template. A template with inputs must be bound before execution. User values, including literals, become typed given parameters; they are never interpolated into TypeQL text.
Batch splitting¶
A batch is one plan over all of its rows as given and fires once. It is
split only when its rows would pass a limit, into same-shape plans that run
in the same transaction, so the batch stays all-or-nothing. Every language
binding and the proxy call the one pure function
type_bridge_contract::split::split, so they split identically.
The input is the encoded plan size and an ordered list of units. A unit is
the given rows one input row produces, with their encoded bytes; it is
never divided. SplitLimits::CANONICAL is 4,096 rows and the 32 MiB
envelope; SplitLimits::new lets a caller tighten them. Each chunk holds at most
max_rows rows and at most max_bytes minus the plan bytes of row bytes.
Chunks are contiguous, order-preserving ranges of unit indexes, filled
greedily: a batch within the limits is exactly one range, the result depends
only on its inputs, and an empty batch yields no ranges. For example, 10,000
one-row units give 0..4096, 4096..8192, 8192..10000. The split is
refused with PlanTooLarge when the plan leaves no byte budget for rows, and
with UnitTooLarge (naming the first such unit) when one unit alone exceeds
the row or byte budget.
Canonicalization and fingerprint¶
Canonical JSON is compact UTF-8, without BOM, whitespace or terminal newline.
Object keys are lexicographically sorted by Unicode scalar value. Array order
is retained. Escape quote, backslash and controls using JSON's short control
escapes where available, otherwise lowercase \u00xx. Do not escape / or
printable Unicode, or normalize Unicode. IDs/counts/bounds are minimal unsigned
JSON integers; scalar longs are strings and doubles are bits. Required members
are not omitted just because their value is empty or false.
Decode, validate, re-encode and require exact byte equality. Whitespace, noncanonical key order, alternate scalar spelling and incorrect capability lists therefore fail.
| Ceiling | Value |
|---|---|
| Complete canonical artifact | 16 MiB |
| JSON depth (root = 1) | 64 |
| Members in one collection | 65,536 |
| One string/key | 1 MiB |
| Bindings / output slots | 256 / 16 |
| Predicate/expression nodes / depth | 4,096 / 64 |
| Boolean children / order terms | 256 / 64 |
| Cross-join pairs | 1,024 |
| Given rows / canonical row bytes | 4,096 / 4 MiB |
JSON depth may reject a tree before its semantic depth ceiling. Receivers can choose tighter supported limits; limits are local policy and not hashed. Diagnostics contain stable bounded metadata without user values or fragments.
The plan fingerprint uses domain typebridge.query.plan, canonicalization
typebridge.query-plan-c14n/v3, SHA-256 and no outer semantic profile. Define
frame(x) as an unsigned 64-bit big-endian byte length followed by x. Hash:
UTF8("typebridge.fingerprint/v1") || 0x00
|| frame(UTF8("typebridge.query.plan"))
|| frame(UTF8("typebridge.query-plan-c14n/v3"))
|| 0x00
|| frame(canonical_plan_bytes)
Render the digest as 64 lowercase hex digits. The managed fingerprint already carries its profile inside the hashed bytes. Operation and bound row changes produce a different plan digest.
Capabilities¶
Recompute the sorted union from syntax. V3 includes query.plan.v3; released
read syntax also derives query.plan. New stages add query.write.insert,
query.write.put, query.write.update, query.write.delete,
query.write.attach and query.fetch.thing. Let adds query.let; an iid
pattern adds query.pattern.iid; expression operators/builtins add
query.expr. plus their exact wire name, including query.expr.length.
The retained read vocabulary is query.pattern.isa, query.pattern.isa-subtypes,
query.pattern.has, query.pattern.links, query.pattern.value,
query.pattern.negation, query.pattern.disjunction, query.pattern.try,
query.pattern.function-call, query.pattern.reachable, query.function.local,
query.input.columns, query.stage.select, query.stage.require,
query.stage.distinct, query.stage.reduce, query.stage.sort,
query.stage.offset, query.stage.limit, query.output.rows, and
query.output.documents. Each construct contributes its corresponding feature.
Inputs or any literal/input operand add query.input.given-rows. Lifted
compatibility syntax additionally retains its V2 capability derivation.
Providers must advertise every required feature.
Derivation and advertisement are separate. query_plan_v3_capability_vocabulary()
is the V2 vocabulary (which includes query.pattern.iid) plus
query.plan.v3, the insert/update/delete/put write capabilities, query.let
and every query.expr.* name. The staged advertisement at
GET /v3/capabilities is the V2 advertisement's capabilities, that
vocabulary, query.remote.envelope-v3 and query.remote.write.
query.write.attach and query.fetch.thing are
derived but not advertised yet, so staged requests refuse plans that need
them.
Plan builder¶
query_plan::v3::PlanBuilder is the one rule set every SDK builder calls, so
the same program gives the same canonical bytes in every language:
- Binding IDs are dense and follow creation order; input column IDs follow
inputcall order. exact,subtypes,field,links,compareandlet_add to the plan's single leadingmatch, in call order. A plan with no such call has no match stage.- Write calls append stages in call order. Consecutive calls of the same kind
share one stage:
update/update_playerone update,insertone insert,putone put, anddelete/delete_field/delete_playerone delete.thing_fieldandthing_playerextend an inserted or put thing. rowappends a given row; with no rows the plan is a template.
Derived variable names come from labels. exact, subtypes, insert and
put use the type label's stem: ASCII letters are lowercased, digits and _
are kept, every other character becomes _, and a stem not starting with a
lowercase letter gains a v prefix (purchase-id gives purchase_id).
field uses {owner variable}_{attribute stem} (item_stock). A stem is cut
to 120 bytes; if it is taken, _2, _3, ... is appended, using the first
unused suffix (a second item is item_2). Explicit names (input, let_)
are used as given and must be fresh; bindings and inputs share one
namespace.
build chooses the operation. A plan with write stages answers
{"kind":"write","returns":"matched"}, or "rows" when returning named
columns; a read answers rows, or count/exists with empty output
columns. Every method is infallible: the first invalid call is kept and
returned by build, which then runs full plan validation. Builder codes are
query_plan_builder_duplicate_name, query_plan_builder_binding_limit,
query_plan_builder_untyped_relation (links needs a relation bound by
exact/subtypes), query_plan_builder_not_created (fields and players on
a thing that was not inserted or put) and query_plan_builder_write_operation
(a write plan that asked for count or exists). The builder has no attach,
players-deletion, iid or fetch call; such plans are constructed as a
PlanSpec and validated by QueryPlanV3::new.
TypeQL lowering¶
Lower stages in order into one pipeline in one transaction. Generate hygienic variables, resolve labels through checked identities and bind values. These are illustrative forms, not a snapshot read followed by a separate mutation.
| Construct | TypeQL form |
|---|---|
| isa / has / links | $x isa account; / $x has score $s; / $r links (member: $x); |
| value | $s >= $minimum; and corresponding comparator symbols |
| or / not / try | { ... } or { ... }; / not { ... }; / try { ... }; |
| let | let $next = $stock - $one; |
| iid | $x iid 0x1e00000000000000000001; |
| arithmetic | Parenthesized +, -, *, /, %, ^ expressions |
| builtins | Same names except length becomes len($text) |
| insert / put | insert $o isa order, has order-id $id; / put $o isa! order, has order-id $id; (put matches the exact declared type) |
| field / role update | update $x has score == $next; / update $r links (member: $new); |
| attach | insert $x has tag == $value; / insert $r links (member: $p); over bound variables |
| delete thing / ownership / link | delete $x; / delete has $old_score of $x; / delete links (member: $old) of $r; |
| delete players | try { $r links (member: $p); }; then delete try { links (member: $p) of $r; }; |
| select / require / distinct | select $x; / require $x; / distinct; |
| fetch | match $x isa! $T; $x links (member: $P0); $P0 isa! $P0T; (optional roles inside try), then fetch { "_iid": iid($x), "_type": label($T), "attributes": { $x.* }, "_role_0_iid": iid($P0), "_role_0_type": label($P0T), "_role_0_attributes": { $P0.* } }; |
| reduce | reduce $n = count($x) groupby $group; |
| sort / offset / limit | sort $x asc; / offset 10; / limit 10; |
| output / operation | Resolve the declared rows, documents, count, presence or write result from that pipeline |
Ownership deletion first binds every value of the ownership (for example,
$x has score $old_score) in a preceding optional (try) match of that same
pipeline, then deletes that ownership using the attribute variable inside an
optional delete. It does not render a field label as a deletable. Owners
without a value keep their row, so later stages and matched still see them;
each additional value of a multi-valued ownership adds one row. A players
deletion binds and deletes every player of the role the same way.
Bounded reachability uses a checked local function over declared roles; function
calls use checked let assignments and definitions. Given rows seed that same
pipeline. A touch assigns the matched value back to its field, retaining a
write conflict edge. Relation reassignment deletes the old role link before
assigning the new player. Write-row projection follows mutation in that same
pipeline. The ORM executor (type-bridge-core/crates/orm/src/query_plan_exec.rs)
implements this lowering. Its deletion and fetch helper variables
(PlanHas{stage}x{index}, PlanPlayers{stage}x{index}, PlanFetchType,
PlanFetchRole{N}) start uppercase, so they cannot collide with validated
lowercase plan variables.
Versioning¶
V1/V2 bytes and fingerprints are frozen. QueryPlan::to_v3(&schema) revalidates
against declared schema with the original plan's limits and returns a result.
It preserves bindings,
inputs, ordered read stages, output, local functions, managed semantics and V2
compatibility. It chooses rows operation and omits given rows. Bind invocation
rows and choose count/exists explicitly as needed. The new discriminator,
capabilities and c14n version produce a V3 fingerprint, not the old digest.
Native V3 producers normally omit compatibility. Lifted plans preserve the
released object containing allowed_cross_joins, nullable model_query and
nullable predicate under the V2 contract.
V3 does not reinterpret those model-query predicates or terminal shapes.
A changed tag, required field, validation meaning, canonical encoding, numeric promotion, capability derivation or stage semantics requires a new format and canonicalization version. New closed constructs require V4; a V3 receiver rejects unknown syntax instead of silently losing meaning.
Worked canonical examples¶
The following are exact files from tests/contracts/plan_v3, without the
Markdown line terminator. A Rust test validates them under the separate
schema.json, compares fixture bytes and recomputes the displayed fingerprints.
Their managed fingerprint identifies fixture authority, not a production schema.
purchase¶
Match one item and buyer, check stock and balance, compute decrements, update both and insert the purchase relation with buyer and item players, then return it.
{"bindings":[{"id":0,"variable":"item"},{"id":1,"variable":"buyer"},{"id":2,"variable":"stock"},{"id":3,"variable":"balance"},{"id":4,"variable":"price"},{"id":5,"variable":"next_stock"},{"id":6,"variable":"next_balance"},{"id":7,"variable":"purchase"},{"id":8,"variable":"item_key"},{"id":9,"variable":"buyer_key"}],"format":"typebridge.query-plan/v3","functions":[],"given_rows":[[{"kind":"string","value":"purchase-1"},{"kind":"string","value":"item-1"},{"kind":"string","value":"buyer-1"}]],"inputs":[{"id":0,"optional":false,"public_name":"new_purchase_id","value_type":"string"},{"id":1,"optional":false,"public_name":"expected_item_id","value_type":"string"},{"id":2,"optional":false,"public_name":"expected_buyer_id","value_type":"string"}],"managed_semantics":{"algorithm":"sha256","canonicalization":"typebridge.managed-semantic/v1","digest":"4cafd679447c7f0dd1a99a702ebb9e7bf2b70c2eb3f44ab5ad5fac6e7b858a07","domain":"typebridge.schema.managed-semantic","semantic_profile":"typedb-3.13.6/v1"},"operation":{"kind":"write","returns":"rows"},"output":{"columns":[7],"kind":"rows"},"pipeline":[{"kind":"match","patterns":[{"binding":0,"include_subtypes":false,"kind":"isa","type_id":{"kind":"entity","label":"item"}},{"binding":1,"include_subtypes":false,"kind":"isa","type_id":{"kind":"entity","label":"account"}},{"attribute":2,"attribute_id":"stock","kind":"has","owner":0},{"attribute":3,"attribute_id":"balance","kind":"has","owner":1},{"attribute":4,"attribute_id":"price","kind":"has","owner":0},{"attribute":8,"attribute_id":"item-id","kind":"has","owner":0},{"attribute":9,"attribute_id":"id","kind":"has","owner":1},{"comparator":"equal","kind":"value","left":{"binding":8,"kind":"binding"},"right":{"column":1,"kind":"input"}},{"comparator":"equal","kind":"value","left":{"binding":9,"kind":"binding"},"right":{"column":2,"kind":"input"}},{"comparator":"greater","kind":"value","left":{"binding":2,"kind":"binding"},"right":{"kind":"literal","value":{"kind":"long","value":"0"}}},{"comparator":"greater_or_equal","kind":"value","left":{"binding":3,"kind":"binding"},"right":{"binding":4,"kind":"binding"}},{"binding":5,"expr":{"kind":"arith","value":{"lhs":{"kind":"operand","value":{"binding":2,"kind":"binding"}},"op":"sub","rhs":{"kind":"operand","value":{"kind":"literal","value":{"kind":"long","value":"1"}}}}},"kind":"let"},{"binding":6,"expr":{"kind":"arith","value":{"lhs":{"kind":"operand","value":{"binding":3,"kind":"binding"}},"op":"sub","rhs":{"kind":"operand","value":{"binding":4,"kind":"binding"}}}},"kind":"let"}]},{"kind":"update","sets":[{"field":{"attribute":"stock","owner":{"kind":"entity","label":"item"}},"kind":"field","operand":{"binding":5,"kind":"binding"},"owner":0},{"field":{"attribute":"balance","owner":{"kind":"entity","label":"account"}},"kind":"field","operand":{"binding":6,"kind":"binding"},"owner":1}]},{"kind":"insert","things":[{"binding":7,"fields":[[{"attribute":"purchase-id","owner":{"kind":"relation","label":"purchase"}},{"column":0,"kind":"input"}]],"players":[[{"declaring_relation":"purchase","label":"buyer"},1],[{"declaring_relation":"purchase","label":"item"},0]],"type_id":{"kind":"relation","label":"purchase"}}]}],"required_capabilities":["query.expr.sub","query.input.columns","query.input.given-rows","query.let","query.output.rows","query.pattern.has","query.pattern.isa","query.pattern.value","query.plan","query.plan.v3","query.write.insert","query.write.update"]}
Fingerprint: ceeed10049398f899726749f1f28beb547d93201d04d3f3799790c49cdb81c09.
touch¶
Match a doctor and its on-call value, then assign that value back and return the doctor.
{"bindings":[{"id":0,"variable":"account"},{"id":1,"variable":"peer"},{"id":2,"variable":"total"}],"format":"typebridge.query-plan/v3","functions":[],"inputs":[],"managed_semantics":{"algorithm":"sha256","canonicalization":"typebridge.managed-semantic/v1","digest":"4cafd679447c7f0dd1a99a702ebb9e7bf2b70c2eb3f44ab5ad5fac6e7b858a07","domain":"typebridge.schema.managed-semantic","semantic_profile":"typedb-3.13.6/v1"},"operation":{"kind":"write","returns":"rows"},"output":{"columns":[0],"kind":"rows"},"pipeline":[{"kind":"match","patterns":[{"binding":0,"include_subtypes":false,"kind":"isa","type_id":{"kind":"entity","label":"doctor"}},{"attribute":1,"attribute_id":"on-call","kind":"has","owner":0}]},{"kind":"update","sets":[{"field":{"attribute":"on-call","owner":{"kind":"entity","label":"doctor"}},"kind":"field","operand":{"binding":1,"kind":"binding"},"owner":0}]}],"required_capabilities":["query.output.rows","query.pattern.has","query.pattern.isa","query.plan","query.plan.v3","query.write.update"]}
Fingerprint: 820cec8799b567f4a182d52014290ae2b00edab1d671be36592c7ea71d08166e.
relation_assign¶
Remove the old member link and assign the new account in the same pipeline.
{"bindings":[{"id":0,"variable":"account"},{"id":1,"variable":"peer"},{"id":2,"variable":"total"}],"format":"typebridge.query-plan/v3","functions":[],"inputs":[],"managed_semantics":{"algorithm":"sha256","canonicalization":"typebridge.managed-semantic/v1","digest":"4cafd679447c7f0dd1a99a702ebb9e7bf2b70c2eb3f44ab5ad5fac6e7b858a07","domain":"typebridge.schema.managed-semantic","semantic_profile":"typedb-3.13.6/v1"},"operation":{"kind":"write","returns":"rows"},"output":{"columns":[1],"kind":"rows"},"pipeline":[{"kind":"match","patterns":[{"binding":0,"include_subtypes":false,"kind":"isa","type_id":{"kind":"entity","label":"account"}},{"binding":1,"include_subtypes":false,"kind":"isa","type_id":{"kind":"relation","label":"membership"}},{"binding":2,"include_subtypes":false,"kind":"isa","type_id":{"kind":"entity","label":"account"}}]},{"items":[{"kind":"links","player":0,"relation":1,"role":{"declaring_relation":"membership","label":"member"}}],"kind":"delete"},{"kind":"update","sets":[{"kind":"link","player":2,"relation":1,"role":{"declaring_relation":"membership","label":"member"}}]}],"required_capabilities":["query.output.rows","query.pattern.isa","query.plan","query.plan.v3","query.write.delete","query.write.update"]}
Fingerprint: 0d0f3e56c870c31aa254c8819235eef9a9bb96196c7d5a167cd000691bc20117.
batch¶
Two given rows insert accounts using typed ID and score columns, returning matched rows.
{"bindings":[{"id":0,"variable":"account"},{"id":1,"variable":"peer"},{"id":2,"variable":"total"}],"format":"typebridge.query-plan/v3","functions":[],"given_rows":[[{"kind":"string","value":"account-1"},{"kind":"long","value":"1"}],[{"kind":"string","value":"account-2"},{"kind":"long","value":"2"}]],"inputs":[{"id":0,"optional":false,"public_name":"new_id","value_type":"string"},{"id":1,"optional":false,"public_name":"new_score","value_type":"long"}],"managed_semantics":{"algorithm":"sha256","canonicalization":"typebridge.managed-semantic/v1","digest":"4cafd679447c7f0dd1a99a702ebb9e7bf2b70c2eb3f44ab5ad5fac6e7b858a07","domain":"typebridge.schema.managed-semantic","semantic_profile":"typedb-3.13.6/v1"},"operation":{"kind":"write","returns":"matched"},"output":{"columns":[],"kind":"rows"},"pipeline":[{"kind":"insert","things":[{"binding":0,"fields":[[{"attribute":"id","owner":{"kind":"entity","label":"account"}},{"column":0,"kind":"input"}],[{"attribute":"score","owner":{"kind":"entity","label":"account"}},{"column":1,"kind":"input"}]],"players":[],"type_id":{"kind":"entity","label":"account"}}]}],"required_capabilities":["query.input.columns","query.input.given-rows","query.output.rows","query.plan","query.plan.v3","query.write.insert"]}
Fingerprint: c3a2e9bc496a9807ae6a32cb73c43f1f1601e066deec384dee1470369a89e5c0.
Staged remote envelope V3¶
A staged transaction uses typebridge.query-remote-request/v3, independently
of the plan version. Requests remain unsigned. Write execution requires an
authenticated transport identity or explicit server policy; possessing an
advertisement or reply-signing public key does not authorize a write. This
section defines the codec. The standalone server executes it at
POST /v3/staged and advertises the staged capabilities at
GET /v3/capabilities; requests bind to that advertisement, not to the
unchanged /v2/capabilities one. A write transaction opens only when an
interceptor vouches for the caller (Interceptor::on_v3_write_authority
answers StagedWriteAuthority::Authenticated) or [v2] sets
allow_unauthenticated_staged_writes = true; otherwise the signed reply fails
with staged_write_not_authorized. Before each plan stages,
Interceptor::on_v3_plan sees its index, required capabilities, touched
types and operation, but no row values unless the policy returns true from
wants_v3_plan_rows; a refusal fails the signed reply with
query_remote_policy_rejected, stages nothing further and commits nothing.
Once the outcome is known, the observe-only Interceptor::on_v3_commit sees
committed, the diagnostic code, the commit certainty and the typed provider
failure (such as an STC2 conflict). Staged replies carry no documents: a
plan whose rows or write-rows operation projects documents output is
refused with query_remote_v3_documents_unsupported, and a fetch plan fails
capability admission earlier because query.fetch.thing is not advertised
yet. Execution enforces the
advertised answer ceilings, tightened by the request's max_items,
max_bytes and deadline, while answers are read. Once admitted, a request
finishes in a detached task: a client that disconnects mid-commit still has
its outcome committed and observed.
Request¶
| Member | Wire shape |
|---|---|
format |
typebridge.query-remote-request/v3 |
advertisement |
Lowercase 64-hex digest of the exact executor advertisement |
prepared_at_unix_ms |
Unsigned Unix millisecond timestamp |
expires_at_unix_ms |
Preparation time plus the selected deadline |
nonce |
16..128 ASCII letters, digits, hyphens or underscores |
kind |
Optional read, write or schema |
limits |
Complete budget object below |
plans |
Nonempty ordered array of {"plan_bytes":"...","rows":[...]} |
Omit an absent kind; explicit null is not canonical. Each
plan_bytes is the lowercase hexadecimal encoding of exact canonical V3 plan
bytes. It is opaque bytes, not TypeQL or a host-reserialized plan object. Rows
are positional canonical scalar/null arrays under that plan's input columns.
A bound plan's rows must exactly equal the envelope rows. For an unbound
template, the envelope rows must satisfy its declared columns. A plan without
columns has rows:[]. Execution materializes the same validated values through
given; no value interpolation is permitted.
Kind defaults to write if any plan writes, otherwise read. Explicit read refuses writes; explicit write permits reads. Schema refuses query plans. The request is a stack, not an open transaction or a collection of separately committed requests. Its answers resolve together after the transaction outcome.
Every request requires query.remote.envelope-v3, and every writing stack
adds query.remote.write.
The union of all plan capabilities is also required. The receiver checks every
plan under its own schema and the minimum of its query limits and the advertised
query limits. Sender metadata cannot widen receiver limits.
Deadline omission means 30,000 ms; explicit deadlines range from 1 to 300,000 ms. Expiry equals preparation plus that duration, with checked arithmetic. Execution must reject an expired request or a preparation timestamp more than 60,000 ms in the future. Archival decoding is separate from this wall-clock freshness check.
Aggregate budgets¶
The complete limits object always includes these fields, including defaults:
| Member | Default | Supported range |
|---|---|---|
deadline_ms |
null | null, or 1..300,000 |
max_bytes |
33,554,432 | 1..33,554,432 signed successful reply bytes |
max_items |
65,536 | 1..65,536 aggregate answer items |
max_staged_plans |
64 | 1..64 |
max_read_statements |
192 | 1..4,096 |
max_write_statements |
256 | 1..4,096 |
Read and write provider statements are separate dimensions; the frozen V2 three-statement limit is unchanged. Request validation checks the minimum of one statement per plan against the corresponding budget. Execution must charge all actual statements, including any necessary split queries, before they fire and refuse exceeding a budget inside the same transaction. The codec does not execute or estimate an arbitrary provider's split strategy.
The request and signed reply retain the 32 MiB envelope ceiling. Embedded plans retain their independent canonical plan ceilings, and each row batch retains its 4,096-row/4 MiB input ceiling. Opaque plan-byte hex strings may use the envelope budget; decoded plan strings and scalar values still retain their own 1 MiB ceiling. Hex framing consumes envelope bytes: a plan near its standalone limit may not fit in an envelope. One answer row/document counts as an item; count, exists and matched answers each count as one. A failed reply does not consume the successful-data byte budget, allowing a small caller budget to receive a diagnostic. Diagnostics remain capped at 65,536 bytes.
Replies and failure vocabulary¶
The unsigned payload has required format, nonce, request, outcome and
answers. Its format is typebridge.query-remote-response/v3; request is the
exact request fingerprint digest, and the nonce must equal that request's. A successful outcome is
{"kind":"committed"}. A failed outcome is
{"kind":"failed","diagnostic":SDK_DIAGNOSTIC_JSON} and has answers:[].
No partial answers escape a rejected or indeterminate transaction. A successful
read transaction is closed, with committed denoting a final successful stack;
execution does not try to commit a TypeDB read transaction.
The public authoring outcome is non-exhaustive and uses the existing
SdkExecutionDiagnostic, not a second failure model. Failure details follow the
SDK diagnostic vocabulary: version, category, sdk_category, query_category,
code, message, path and typed details. Typed failure details (retry_safe,
phase, code, rejection, lock_kind, annotation, and the staged index in
the path) join this same vocabulary when present; the released codes stay as
they are, and bindings whose released ABI fixes the detail set (C ABI 1.6) do
not see them. The client rebuilds the typed failure from these signed details
only when they name a complete, consistent failure in the closed vocabulary, so
a refusal over the proxy is typed exactly as the same direct commit would be.
commit_outcome_unknown remains indeterminate; a failed outcome alone never
implies a safe retry. SDK messages stay implementation-owned static text during
authoring. Authentication precedes interpretation of their bounded host-JSON
wire projection, which does not weaken the in-memory SDK diagnostic contract.
Committed answers have exactly one entry per plan, in stack order:
| Answer | Shape |
|---|---|
| rows | {"kind":"rows","rows":[[REMOTE_VALUE,...],...]} |
| documents | {"kind":"documents","documents":[{"field":REMOTE_FIELD_VALUE},...]} |
| count | {"kind":"count","value":1} |
| exists | {"kind":"exists","value":true} |
| matched | {"kind":"matched","value":2} |
Read rows and write/rows select rows or documents according to their output;
count/exists require their corresponding answer. Write/matched requires matched.
Widths, document keys, instance identity/type shape, total items and byte budgets
are checked against the stack. Remote values retain V1's tagged thing
(iid, type_id), attribute (type_id, value), value (value) and absent
forms. Remote field values are tagged scalar (value), list (values) or
absent. Successful byte and failed-diagnostic byte ceilings are checked using
borrowed authenticated payload fragments before allocating owned evidence.
Fingerprint and signature¶
The request uses the same framed SHA-256 algorithm as plan fingerprints, with
domain typebridge.query.remote-request, canonicalization
typebridge.query-remote-request/v3, no semantic profile and the complete
canonical request bytes. This binds all plans, rows, limits, times, kind,
advertisement and nonce.
Replies use the unchanged typebridge.query-remote-signed-reply/v1 outer object:
advertisement, format, key, key_id, payload, signature. Advertisement
is its digest; key is 32-byte Ed25519 public-key hex; signature is 64-byte hex.
Key ID is SHA-256 of UTF8("typebridge.query.remote-reply-key-id/v1"), a zero
byte and the raw public key. Let U be the canonical outer object with signature
omitted, including the complete V3 payload. Sign the 32-byte SHA-256 digest of
UTF8("typebridge.query.remote-reply-signature/v1") || 0x00 || U using Ed25519.
The receiver supplies the trusted public key, checks its advertisement binding,
authenticates the outer envelope and only then interprets/correlates the V3
payload. Unknown fields/tags and noncanonical reconstruction are refused.
Rust's genuine Ed25519 golden fixtures are in
type-bridge-core/crates/contract/tests/fixtures/query-remote-v3/: advertisement,
request, request fingerprint, committed reply and failed reply. Existing V2
envelope and V2/V3 plan fixtures remain byte-for-byte unchanged.
Replays and unknown outcomes¶
The server keeps no replies. POST /v3/staged authenticates the transport,
decodes against the advertisement, checks freshness, authorizes the write and
runs plan policy; it then reserves the request's nonce for the request's whole
lifetime, executes once, signs and replies. The same bytes again never execute
again: a read is refused with query_remote_replay, and a write answers
commit_outcome_unknown, because its first copy may have committed. Every
other signed refusal applied nothing.
A reply that is lost or fails verification leaves the outcome unknown; the application reconciles by reading the database, as after a lost direct commit. A server restart forgets spent nonces, and its executor epoch and advertisement change, so a request bound to the old advertisement is refused. TypeBridge reports the outcome; retries, locks and concurrency limits are the application's policy.