Blue Language Specification 1.0

§PART I — THE LANGUAGE (1–14)

Scope of Part I. Defines Blue’s content model, typing, resolution, schema, identity (BlueId), expansion and minimization. No runtime/contract processing is defined here (that is Part II). Where Part I references types like Text, Integer, List, Boolean, etc., their canonical definitions (with BlueIds) are in Appendix A.

§1. Scope & Goals

Goal. Blue is a universal, deterministic content language with:

• a strict, mergeable type system and resolution rules, and
• a content address called BlueId that is stable across equivalent authoring forms (minimal, expanded, resolved).

Out of scope. Runtime/workflow semantics, policies, operations, and processors (colloquially “contracts”) are not defined here. They live in Blue Contracts & Processor Model.

§2. Core Data Model

A Blue node is exactly one of:

• Scalar (string, number, boolean)
• List (array)
• Object (map of fields → nodes)

Reserved keys (language keywords) that MAY appear in any object node:

1name, description, type, itemType, keyType, valueType,
2value, items, blueId, blue, schema, mergePolicy, contracts

There is no properties field in the language. An “object” node is written as regular fields under that node. (properties may exist internally in some libraries; it MUST NOT appear in documents.)

2.1 Wrapper Equivalence (normative)

To improve ergonomics, Blue admits two equivalent authoring forms for scalars and lists:

• Scalar: x: 1 ≡ x: { value: 1 } (equivalent only if the wrapper has no other keys)
• List: x: [a, b] ≡ x: { items: [a, b] } (equivalent only if the wrapper has no other keys)

Object nodes are written directly:

1x:
2  a: 1
3  b: 2

A node MUST NOT combine payload kinds: a node may have either value or items or child fields (object) — never more than one. (Authors MAY rely on preprocessing to normalize forms; see §7.)

§3. name / description — Identity vs Field Semantics

3.1 Meaning and neutrality (normative)

• name and description are content on the node; they do affect BlueId.
• They are node-local (document identity or field label).
• They MUST be ignored by:
  • type conformance checks,
  • subtype compatibility checks,
  • structural/shape matchers (including resolution matchers).

(Matcher Neutrality.) Matchers MUST ignore name, description.

3.2 Document identity vs field semantics (normative)

• Document-level identity. A node “of type T” is not T; it is a new entity. The resolved node’s top-level name/description come only from the instance and MUST NOT be inherited from type. The embedded type object may carry its own name/description inside node.type.
• Field-level semantics. When a type materializes fields/items into the instance, those child nodes carry the type’s name/description until the instance explicitly overrides them on those child paths.

3.3 Expansion (node references) (normative)

Dereferencing { blueId: X } to materialize the node may copy the referenced node’s name/description onto that node (because the node itself is being materialized). This is not inheritance from type and does not violate §3.2.

3.4 Equality (normative)

• Identity equality (BlueId) includes name/description.
• Structural/type equality ignores name/description.

§4. Types — Schema and Overlay (Uniform Model)

4.1 Any node can be a type (normative)

There is no “schema vs instance” bifurcation. Any node can appear under type. If T is used in type: T, T contributes:

• structure (fields/items),
• nested type chains,
• schema constraints (§5),
• fixed values (become invariants).

Fixed-value invariant. A concrete value in a type is immutable in descendants at that path.

4.2 Subtyping & Liskov (normative)

When resolving, descendants MUST satisfy:

1. No fixed-value override (immutable values).
2. Type compatibility (equal or subtype of inherited type).
3. Additive structure (cannot remove guaranteed fields).
4. Collections maintain itemType, keyType, valueType compatibility.

Liskov. Every instance of a subtype MUST be substitutable for its parent.

4.3 Instance-as-type (overlay)

Nodes representing individuals can be used as types:

• Alice may be type: Person.
• Alice Smith may be type: Alice.

All fixed values in Alice become invariants in Alice Smith. Alice’s name/description do not flow to Alice Smith (§3.2).

§5. schema — Constraint Keywords (complete list)

Attach schema to any node. All constraints accumulate along the type chain; stricter wins. Irreconcilable constraints MUST fail resolution (§11).

5.1 Presence

• required: true — the field must be present in resolved descendants.

5.2 For lists

• minItems: <non-negative integer>
• maxItems: <non-negative integer> (≥ minItems)
• uniqueItems: true|false (uniqueness by BlueId of items)

5.3 For objects (maps)

• minFields: <non-negative integer>
• maxFields: <non-negative integer> (≥ minFields)

(Rationale: “fields” reflects there is no properties key in the language.)

5.4 Numerics (applies to numeric scalars)

• minimum: number
• maximum: number (≥ minimum if both present)
• exclusiveMinimum: number (strictly less than value)
• exclusiveMaximum: number (strictly greater than value)
• multipleOf: number (> 0). If multiple appear in the chain, use LCM.

5.5 Strings

• minLength: <non-negative integer>
• maxLength: <non-negative integer> (≥ minLength)
• pattern: <ECMA-262 regex string>

5.6 Enumerations

• enum: [ v1, v2, … ] (values are scalars; equality by canonical JSON)

Note. There is no separate const keyword; a fixed value in the type (i.e., the type sets value or a concrete subtree value) already enforces a constant.

§6. Resolution Semantics

Goal. Produce a fully validated, resolved snapshot from authoring/overlay input.

6.1 Algorithm (normative)

Given a source node S:

1. Preprocess blue (§7).
2. Resolve type chain: if S.type exists, recursively resolve it (following blueId via a provider) to produce ancestor A.
3. Merge A into target T, then merge S into T:

• Values: copy if absent; if both present, must be equal.
• Types: assign/propagate under §4.2.
• Schema: accumulate (§5).
• Object fields: merge recursively; child must remain compatible.
• Lists: see §6.3.

4. Validate all schema constraints.
5. Finalize the resolved snapshot (implementations SHOULD freeze it; §10).

6.2 Requirement Overlays (normative)

An ancestor may partially constrain a subtree (overlay obligations) without binding a concrete type at that path:

1# Parent
2name: A
3prop1:
4  x: 1           # requirement overlay at /prop1 (no type)
5  schema: { ... }  # optional constraints

A descendant may later set prop1.type: Some only if the merged result still satisfies all overlay obligations (fixed values and schema). If the overlay had a type, the descendant’s type must be equal or a subtype.

Conflicts (e.g., overlay forces x = 1 but Some forces x = 2) MUST fail resolution.

6.3 Lists at authoring time (normative)

• Refinement of an inherited index is allowed if the element remains subtype-compatible with the inherited element.
• Append is allowed.
• Deletion/reorder within the inherited prefix MUST fail resolution.

6.4 Limits (normative)

Resolvers SHOULD support path/depth limits to bound expansion of large graphs. Limits affect only materialization, not meaning.

§7. Preprocessing — the blue Directive (normative)

The root MAY contain blue (string or object). Preprocessing:

• runs before hashing & resolution,
• normalizes authoring (type aliases → blueId, type inference, renamings),
• MUST remove the blue directive afterward (it never affects BlueId).

7.1 Required baseline transforms

1. Type aliases → blueId (per configured mappings).
2. Primitive inference for bare scalars (assign Text, Integer, Double, Boolean).
3. Optional attribute/case/date normalizations (profile-dependent).

7.2 Security

Remote fetch of transforms is DISABLED by default (opt-in only).

§8. BlueId (Content Address)

8.1 Definition (normative)

BlueId = Base58( SHA-256( RFC 8785-canonical-JSON(node) ) ) computed bottom-up (children before parents).

8.2 Cleaning & Shape Normalization (normative)

Before producing RFC 8785 canonical JSON, implementations MUST normalize nodes as follows. The aims are to remove non-meaningful artifacts, ensure a single canonical shape, and preserve identity-relevant content.

8.2.1 Global cleaning

1. Remove null at any depth.• In lists, null elements are removed (i.e., [a, null, b] → [a, b]).• In objects, fields with null values are removed.
2. Remove empty maps {} at any depth (including within lists).• Cascading removal is permitted (a parent map may become {} and then be removed itself).
3. Preserve empty lists []. A present-empty list is not the same as an absent field.

Note: This “cleaning” is applied recursively across the entire tree before hashing.

8.2.2 Canonical shape: wrapped form is official

Blue’s official canonical representation is the wrapped form. Authoring sugar MUST be normalized to wrapped form prior to hashing:

• ScalarsAuthoring sugar:

1x: 1

• Canonical wrapped form:

1x:
2  value: 1

• ListsAuthoring sugar:

1x: [a, b]

• Canonical wrapped form:

1x:
2  items: [a, b]

A node MUST NOT combine payload kinds (value, items, or object fields). After normalization, each node is exactly one of:

• scalar wrapper { value: … },
• list wrapper { items: […] }, or
• plain object (map of fields → nodes).

Equivalence guarantee: Even if an implementation hashes authoring sugar directly, the hasher MUST treat x: 1 and x: { value: 1 } (and likewise x: [a,b] vs x: { items: [a,b] }) as identical (§ 8.3, § 8.4 ensure this by inlining value and domain-separating list folds).

8.2.3 List control forms (see § 12)

Reserved list item forms are not content (except $empty) and MUST be handled specially before hashing:

• $pos overlays — consumed by normalization/merge; they do not appear in the hashed content list.
• $previous anchors — never content. Hashers either:(a) seed the list fold with the provided prior list BlueId iff the resolved prefix is unchanged (§ 12.5.2), or(b) recompute from id([]) (§ 8.4, § 12.5.1) if the prefix changed or no valid anchor is present.
• $empty: true — is content and remains as a real element; it hashes like any other object element (§ 12.4).

These forms are recognized only at the top level of items for nodes whose type is List.

8.2.4 Object shape

After normalization, an object node is a plain map of field → node.

There is no properties field in the language; that is an internal detail in some libraries and MUST NOT appear in documents. Key order is irrelevant (RFC 8785 canonicalization defines ordering).

8.2.5 Examples (informative)

• Nulls inside a list (removed):

1list: [a, null, b]

→ canonical wrapped content:

1list:
2  items: [a, b]

• Scalar sugar normalized:

1x: 1

→

1x:
2  value: 1

• List sugar normalized:

1x: [a, b]

→

1x:
2  items: [a, b]

• $empty is content (preserved):

1list:
2  items: [a, { $empty: true }, b]

• $pos consumed before hashing:

1list:
2  items:
3    - $pos: 0
4      value: a'
5    - b

→ normalized content before hashing:

1list:
2  items: [a', b]

• $previous as anchor (not content):

1list:
2  items:
3    - $previous: { blueId: P }
4    - c

• → if prefix truly matches P, hasher seeds fold with P and folds only c; otherwise recomputes from id([]).

8.3 Map hashing (normative)

If and only if the map is exactly { "blueId": "<id>" }, return <id> (pure reference short-circuit).

Otherwise, build a helper map H in lexicographic key order:

• For name, description, and value: inline their values.
• For every other key k with value v: include k: { "blueId": id(v) }.

Then RFC 8785-canonicalize H and hash.

This rule ensures scalar wrappers { value: S } are treated as scalars for hashing, and that all nested structure contributes by BlueId, not by byte shape.

8.4 List hashing (normative)

Use a domain-separated streaming fold over element BlueIds:

• Empty list seed:

1id([]) = H({ "$list": "empty" })

• Fold step:

1fold(prevId, x) =
2  H({
3    "$listCons": {
4      "prev": { "blueId": prevId },
5      "elem": { "blueId": id(x) }
6    }
7  })

• Whole list:

1id([a₁,…,aₙ]) = fold( fold( … fold( id([]), a₁ ) … , aₙ ) )

Properties:

• Order is significant; multiplicity is preserved.
• No flattening ([[1,2],3] ≠ [1,2,3]).
• Singleton is distinct ([A] ≠ A).
• Appends can be O(Δ) when seeded by a valid $previous (§ 12.5.2).

Seeding with $previous: If the final resolved list’s prefix exactly equals the list whose BlueId is provided by $previous, start the fold from that BlueId and only fold appended elements. Otherwise ignore the anchor and recompute from id([]).

8.5 Scalars (normative)

Hash the RFC 8785 canonical JSON representation of the scalar value.

8.6 Storage rule (normative)

A node MUST NOT store its own BlueId as authoritative content. Using { "blueId": "…" } to reference other nodes is permitted and encouraged.

§9. Expansion

Expansion materializes content referenced by blueId without changing identity. It is distinct from Resolution (§6).

9.1 What expansion does (normative)

Given p: { blueId: X }, expansion fetches content for X and materializes it in place (or side-by-side) within limits (§9.3), allowing nested references to expand recursively.

9.2 Identity invariance (normative)

Expansion MUST NOT change BlueId. Pure references hash to their blueId (short-circuit), and materialized subtrees contribute the same id(subtree) because map hashing replaces structure with { blueId: … } under the hood.

9.3 Limits (normative)

Implementations SHOULD support path/depth limits to avoid runaway traversal of large graphs. Limits affect only materialization, not identity.

§10. Minimization (Normalizing Back to Authoring Form)

Minimization produces a minimal authoring view that, when re-resolved, yields the same resolved snapshot and the same BlueId.

10.1 Rules (normative)

Given a resolved snapshot R, minimize(R) MUST:

• Remove any fields fully re-derivable from the type chain (structure brought solely by types, defaulted values that are fixed by types).
• Replace materialized types with their canonical type: { blueId: … } forms when available.
• Optionally collapse large subtrees to { blueId: … } when the subtree equals a known blueId (this is an allowed minimization, not required).
• Preserve instance-level name/description on the node.
• Never remove instance-fixed values that are not derivable from the type chain.

§11. Circular References (Combined BlueId for Direct Cycles)

Some authoring graphs contain direct cycles across documents (e.g., Person ↔ Dog). Blue supports a combined BlueIdwith per-document suffixes.

11.1 Authoring placeholders (normative)

During save/serialization of a cyclic set:

• Temporarily replace each direct cyclic blueId reference with a placeholder 0×44 (forty-four ASCII '0' characters) — ZERO_BLUEID sentinel that never appears as a valid BlueId.
• Calculate preliminary BlueIds for each document in isolation (with placeholders).
• Sort documents lexicographically by their preliminary BlueIds and assign positions #0..#(n-1).

Rewrite placeholders:

• For each internal cyclic reference that points to another document in the set, place blueId: "this#k" where k is the assigned position of the target.

11.2 Master & final BlueIds (normative)

• Build a list L = [doc#0, doc#1, …, doc#(n-1)] with the this#k references in place and compute its BlueId → MASTER.
• Each document’s final BlueId becomes: MASTER#i where i is the document’s position.

These final BlueIds are stable, content-addressed identities for the cyclic set.

Example.

1# Person (#1 before sorting)
2name: Person
3pet:
4  type: { blueId: 'this#1' }
5
6# Dog (#0 before sorting)
7name: Dog
8owner:
9  type: { blueId: 'this#0' }
10breed:
11  type: Text

If MASTER = "12345...", the final identities are Dog = "12345...#0", Person = "12345...#1".

§§12 — Lists (authoring, merge, hashing)

12.1 Authoring model

A list field SHOULD be authored in typed form:

1<field>:
2  type: List
3  itemType: <Type>                  # RECOMMENDED
4  mergePolicy: append-only | positional
5  items:
6    - ...elements...

A surface list (e.g., tags: [a, b, c]) is permitted for simple cases; the typed form is REQUIRED when mergePolicy, anchors, or overlays are used.

12.2 Allowed element forms inside items

Each item MUST be exactly one of:

1. Normal element (content)

1- <scalar | object (optionally with type) | { blueId: "…" }>

2. Append anchor (fast append / immutability proof — reserved)

1- $previous:
2    blueId: <PrevListBlueId>

• Only allowed as the first item.
• Shape MUST be exactly as shown (single top-level $previous key whose value is an object with a single blueIdstring).

3. Positional overlay (refine by index — reserved; mergePolicy: positional only)

Map overlay (best for object elements):

1- $pos: 1
2  ...overlay fields merged into parent element at index 1...

Scalar/list overlay (when overlay isn’t a map):

1- $pos: 1
2  value: <scalar | list | { blueId: "…" }>

Constraints:

• $pos MUST be a non-negative integer (0-based).
• Only valid when mergePolicy: positional.

4. Placeholder element (reserved; content)

1- $empty: true

• A real element that occupies a position (a meaningful “hole”).
• Distinct from null (ignored) and from [] (present-empty list at that node).

Scope of reserved attributes. The special keys $previous, $pos, $empty are recognized only as top-level keys of items within items of a node whose type: List. They have no special meaning elsewhere.

12.3 Default policy

If mergePolicy is omitted, processors MUST assume positional. For histories/ledgers/timelines, authors MUST specify append-only explicitly.

12.4 Semantics of null, {}, [], and $empty

• null — ignored (no information).
• Empty object {} — ignored.
• Empty list [] — preserved (present-empty ≠ absent) and hashes differently from either null or absent.
• $empty: true — content; remains for hashing.

12.5 Merge semantics

Let parent list be the resolved list from the parent type/instance; let child overlay be the child’s items.

12.5.1 append-only

• Disallow any modification/removal of indices < parentLength. No $pos allowed.
• Allow appends (normal items after the parent prefix).
• Optional append anchor (first item only):

1- $previous: { blueId: <PrevListBlueId> }

• Errors:
  • Any $pos overlay in an append-only list.
  • $previous not first, malformed, or repeated.

12.5.2 positional

• Refine any index i (0 ≤ i < parentLength) via $pos: i:
  • Map overlay: field-wise merge, subject to type/constraint compatibility.
  • Scalar/list overlay: replace with value, subject to compatibility.
• Append new elements by listing normal items after overlays (no $pos on appends).
• Forbid reordering/removal/gaps within the inherited prefix.
• Errors:
  • $pos missing or non-integer; out of range; duplicate overlays for the same i.
  • Type/constraint incompatibility at i.
  • Attempted reordering/removal of parent elements.

12.6 BlueId calculation for lists

The list hasher uses a domain-separated streaming fold:

• id([]) = H({ "$list": "empty" })
• For list [e1, e2, …, en]:
  • acc := id([])
  • For each element e in order:

1acc := H({
2  "$listCons": {
3    "prev": { "blueId": acc },
4    "elem": { "blueId": id(e) }
5  }
6})

• • Return acc.

Control forms:

• $pos overlays are consumed by merge/normalization before hashing (not content).
• $previous can be used as an optimization: if and only if the effective prefix exactly equals the prior list with BlueId P = $previous.blueId, hashers MAY seed acc := P and fold only the appended elements. If the prefix differs, seed from id([]) and recompute fully.
• $empty: true is content and hashes like any other element (it is an object node with a boolean field).

Properties guaranteed:

• Order & multiplicity preserved.
• No flattening: [[A,B],C] ≠ [A,B,C].
• Singleton preserved: [A] ≠ A.
• [] hashes differently from null/absent.
• O(Δ) appends are possible when $previous is valid.

12.7 Conformance checklist (must-pass)

• id([]) defined and id([]) ≠ id(null/absent).
• [A] hashes differently from A.
• [[A,B],C] hashes differently from [A,B,C].
• $previous recognized only as first item; ignored when prefix changed.
• append-only: $pos causes error; normal appends succeed.
• positional: $pos applies; duplicates/out-of-range cause error; appended items appear after parent prefix in author order.
• $empty: true remains as content and affects BlueId.
• Cleaning removes null/{} but not [].

12.8 Worked examples (informative)

Present-empty vs absent

1# Absent
2doc: { }
3
4# Present-empty
5doc:
6  list:
7    type: List
8    items: []

blueId(present-empty) != blueId(absent).

Append-only timeline (fast append, immutable prefix)

1# Parent
2entries:
3  type: List
4  itemType: Timeline Entry
5  mergePolicy: append-only
6  items:
7    - { type: Timeline Entry, ts: 2025-09-01T12:00:00Z, message: A }
8    - { type: Timeline Entry, ts: 2025-09-01T12:05:00Z, message: B }
9
10# Child (append C)
11entries:
12  type: List
13  itemType: Timeline Entry
14  mergePolicy: append-only
15  items:
16    - $previous: { blueId: PrevId }   # PrevId = id(parent entries)
17    - { type: Timeline Entry, ts: 2025-09-01T12:10:00Z, message: C }

Hasher seeds from PrevId and folds only the new element(s).

Positional hole and refinement

1# Parent
2entries:
3  type: List
4  mergePolicy: positional
5  items:
6    - A
7    - $empty: true
8    - C
9
10# Child
11entries:
12  type: List
13  mergePolicy: positional
14  items:
15    - $pos: 1
16      value: B
17# Resolved: [A, B, C]

Positional refine + append

1# Parent
2items:
3  type: List
4  itemType: PhoneOrAccessory
5  mergePolicy: positional
6  items:
7    - { type: Phone, os: any }
8    - { type: Accessory }
9
10# Child
11items:
12  type: List
13  mergePolicy: positional
14  items:
15    - $pos: 0
16      type: iPhone
17      os: iOS
18    - { type: Warranty, months: 24 }
19
20# Resolved:
21# - { type: iPhone,   os: iOS }
22# - { type: Accessory }
23# - { type: Warranty, months: 24 }

§13. Conformance

A Blue Language 1.0 implementation:

• MUST implement preprocessing, resolution, schema validation (Sections 5–7, 11).
• MUST implement BlueId exactly (Section 8), including wrapper normalization (§8.2).
• MUST treat name/description as neutral for structural/type checks (§3).
• SHOULD provide Expansion with limits (Section 9).
• SHOULD provide Minimization (Section 10).
• SHOULD expose frozen resolved snapshots (implementation guidance in §10).

Profiles (recommended):

• BlueId-Only — §8.
• Resolver-Core — §§5–7, 8, 11.
• Language-Full — §§3–12.

§14. Worked Examples (informative)

14.1 Content-addressable types (Alice / Simple Amount)

1name: Simple Amount
2amount:  { type: Double }
3currency:{ type: Text }
4# => blueId: FgHZjS...
5
6name: Person
7age:    { type: Integer }
8spent:  { type: { blueId: FgHZjS... } }    # Simple Amount
9# => blueId: GRwTYs...

Instance:

1name: Alice
2type: { blueId: GRwTYs... } # Person
3age: 25
4spent:
5  amount: 27.15
6  currency: USD
7# => blueId: 3JTd8s...

Fully expanded (type chain materialized) has the same BlueId (Expansion & Resolution do not change identity).

14.2 Blue directive (aliases & inference)

1blue: 5j04jf...
2name: Alice
3type: Person
4age: 25
5spent:
6  amount: 27.15
7  currency: USD

Preprocessing replaces Person with its blueId and may infer basic types for scalars. The blue key is removed before hashing.

14.3 “Same image, different meaning”

1# A
2name: Person to Avoid
3description: This guy will kill you today
4type: Image
5image: { blueId: 123..456 }
6
7# B
8name: Family Member
9description: Trust this person
10type: Image
11image: { blueId: 123..456 }

Different BlueIds (identity content differs), but structural/type checks ignore labels (§3).

14.4 Requirement Overlay → later type binding

1# Parent
2name: A
3prop1:
4  x: 1                # overlay (no type)
5  schema: { /* optional constraints */ }
6
7# Child
8name: B
9type: A
10prop1:
11  type: Some          # legal only if merged result preserves x = 1 (and schema)

If Some would force x = 2, resolution fails (§6.2).

14.5 Lists: refine + append

1# Parent
2name: Trip
3segments:
4  itemType: Flight Segment
5  # (direct list form)
6  - { type: Flight Segment, carrier: BA }
7
8# Child
9name: Trip LHR->SFO
10type: Trip
11segments:
12  - { type: Flight Segment, carrier: BA, from: LHR, to: JFK } # refine index 0
13  - { type: Flight Segment, carrier: BA, from: JFK, to: SFO } # append

Reorder/delete of inherited prefix elements is invalid; append is valid.

14.6 Expansion with limits

Start from:

1blueId: 3JTd8s... # Alice

Expanding /spent/* hydrates only spent:

1name: Alice
2type: { blueId: GRwTYs... }
3age: 25
4spent:
5  amount: 27.15
6  currency: USD

BlueId remains unchanged (§9).

14.7 Minimization

From a resolved snapshot with fully materialized type subtrees, minimize():

• collapses type objects to { blueId: … } when available,
• removes structure derivable from the type chain,
• may collapse large subtrees to { blueId: … } when exact matches are known.

The minimized authoring form re-resolves to the same snapshot and BlueId.

14.8 Circular-set BlueId

1# Authoring (placeholders after algorithm determines positions)
2# Dog (#0)
3name: Dog
4owner: { type: { blueId: 'this#1' } }
5
6# Person (#1)
7name: Person
8pet:   { type: { blueId: 'this#0' } }

The ordered list [Dog, Person] yields MASTER. Final identities: Dog = MASTER#0, Person = MASTER#1.

Part II — Contracts & Document Processing (normative)

Purpose. Part II defines how a Blue document changes state when an event arrives. The processor is a deterministic function:

1PROCESS(document, event) → (new_doc, triggered_events, total_gas)
2

• new_doc — the updated document after all work (including cascades, bridging, and FIFO drains).
• triggered_events — the root-scope events emitted during the run, including lifecycle items (e.g., Document Processing Initiated, any terminal Document Processing Fatal Error), whether or not they were handled.
• total_gas — a deterministic tally of gas units consumed during the run (handlers, cascades, and drains).

Events are Blue nodes. Channels interpret Blue nodes by type/shape (and, where relevant, local routing context).

§15. Contracts: how documents become executable

Every object node MAY contain a contracts dictionary:

1contracts: { <key: Text> → <value: Contract> }   # see Appendix A (“Contract”)
2

Contracts tell the processor what to do with a node. Each contract is identified by a type BlueId (published elsewhere in the registry). A processor either supports a contract’s type BlueId or returns a must-understand failure (see §22.1).

Contract roles (types in Appendix A):

• Channels — where events may arrive. A channel advertises which events it accepts and may adapt/reshape external payloads into channelized form for handlers (see Channel, plus concrete channels in Appendix A §A.4).
• Handlers — logic bound to exactly one channel (same scope). A handler may (i) request document changes (list of Json Patch Entry, Appendix A), (ii) emit new events (Blue nodes), (iii) consumeGas(units: Integer), and (iv) terminate(cause, reason?). No other side effects are permitted. (See Handler in Appendix A.)
• Markers — informative state & policy. Markers never run logic; they carry rules or state the processor obeys (e.g., Process Embedded, Processing Initialized Marker, Processing Terminated Marker, Channel Event Checkpoint; all in Appendix A).

Matching rule (normative).
Handlers MUST only match channelized events produced by channels in the same scope (the node whose contracts map contains them). There is no engine-level “channel flag”; channels define their own recognition (by payload type/shape and, when needed, scope context).

Ordering (normative).
When multiple contracts match, the processor sorts channels, and then handlers within each channel, by:

1. order (number; missing = 0), then
2. key (the contract map key, lexicographic).
   This yields a deterministic run order.

Reserved processor keys under a contracts map (normative).

• embedded — Process Embedded (Appendix A)
• initialized— Processing Initialized Marker (Appendix A)
• terminated — Processing Terminated Marker (Appendix A)
• checkpoint — Channel Event Checkpoint (Appendix A)

These keys are reserved for the processor’s own use. If any exist with an incompatible type, processing MUST terminate as runtime fatal (§22.2).

Write-protection of reserved keys (normative).
Contracts (handlers or channels) MUST NOT patch any reserved key path (/…/contracts/(embedded|initialized|terminated|checkpoint) or descendants). Attempting to add/replace/remove a reserved key path from a handler/channel is a deterministic runtime fatal at that scope (§22.2). Processor writes to these keys are permitted only as specified in §§20, 22, 23 and via Direct Writes (§19.1).

Read-only contract inputs (normative).
Contracts (channels and handlers) MUST treat delivered event objects as read-only. A contract MUST NOT mutate payload objects it receives; all document changes MUST occur only via explicit patch operations (Appendix A: Json Patch Entry).
Implementation note (non-normative): Processors MAY enforce this by cloning or freezing payloads, or by relying on contract implementations to obey the rule; this specification does not require cloning.

Channel vs Handler capability surface (normative).

• Channels may: decide event acceptance; read/update the scope’s Channel Event Checkpoint (Appendix A) for their channel key; consumeGas(units); terminate(cause, reason?).
• Handlers may: apply JSON patches; emit events; consumeGas(units); terminate(cause, reason?).

No other effects are permitted.

(Validated by: T2, T3, T15, T23–T25; reserved-key tamper tests SHOULD be added.)

§16. Embedded sub-documents & isolation

Some subtrees are independent documents processed alongside the parent.

16.1 Process Embedded (marker)

A Process Embedded marker (Appendix A) under contracts/embedded declares embedded children:

1contracts:
2  embedded:
3    # (type defined in Appendix A)
4    paths:
5      - /payment
6      - /shipping
7      # Absolute JSON Pointers within the current scope
8

Normative behavior.

• Dynamic list. The processor reads paths before processing each child and re-reads it after each child finishes; additions/removals/reorderings take effect immediately for the next child.
• Single presence. There MUST be at most one Process Embedded per contracts map. Multiple → runtime fatal (§22.2).
• Single document model. All scopes share the same in-memory document. An embedded child patches its subtree in place; parents and ancestors observe changes via Document Update cascades (§17, §21).

16.2 Isolation & boundary rule

Let the current scope be absolute pointer S (e.g., /, /payment, /a/b). Let E be the set of embedded child roots declared by S’s Process Embedded.

A patch applied while executing in scope S is permitted iff:

• patch.path starts with S, and
• patch.path is not strictly inside any other embedded domain X ∈ E where X ≠ S.

“Strictly inside” means below the child boundary:

1IS_STRICTLY_INSIDE(path, X) = path starts with (X + "/")
2

Implications (normative).

• A parent may add/replace/remove an embedded child root as a whole (e.g., add /payment, remove /payment), but MUST NOT reach inside it (e.g., replace /payment/amount).
• Children may freely patch inside their own subtree (paths of the form S + "/...").
• Self-root mutation is forbidden. While executing in scope S, a handler or channel MUST NOT target exactly Swith add, replace, or remove. Only ancestors may add/replace/remove a child root. Violations → runtime fatal (§22.2).
• Root patch target is forbidden. No contract at any scope may target "/" (§21.2).

Rationale. “Cutting/replacing the balloon” is a parent-only operation; scopes only mutate strict descendants of themselves.

(Validated by: T2, T23–T25.)

§17. Processor-managed channels (indispensable)

The processor MUST support (and is the only entity that feeds) these channel families (definitions in Appendix A):

• Document Update Channel.
  Trigger. When a patch is applied, the processor emits one Document Update per scope participating in the cascade: origin → each ancestor → root.
  Match. Subtree semantics: match if the absolute changed path equals or is a descendant of ABS(scope, path) (see §21.3).
  Payload. Scope-relative Document Update (Appendix A): op (add|replace|remove), path (relative), and before/after snapshots. Payload content is uniform within a scope; channels do not reshape processor-managed payloads.
• Triggered Event Channel.
  Delivers events enqueued by handlers into the scope’s FIFO.
  Drain timing (normative): exactly once per scope at Phase 5 (§19). Never drains during cascades.
• Lifecycle Event Channel.
  Delivers lifecycle nodes at a scope (e.g., Document Processing Initiated, Document Processing Terminated). Lifecycle handlers may patch/emit; emissions are enqueued and later drained per §19. Lifecycle nodes themselves are also bridgeable upward (see below).
• Embedded Node Channel.
  Bridges a child scope’s emissions (Triggered events and lifecycle nodes) into the parent after the child finishes, if the parent configured an Embedded Node Channel for that child’s path.

Helper notation used in this Part (§21.3):
ABS(S, P) — absolute pointer for a channel path P declared at scope S.
relativize_pointer(S, ABS) — path relative to S (returns "/" when ABS == S).
relativize_snapshot(S, node) — subtree content as observed at S (clone or read-only view).

(Validated by: T4–T7, T14–T16, T28.)

§18. External contracts (extensibility)

Beyond the processor-managed channels, authors may define custom channels, handlers, and markers.

Normative requirements.

• Must-understand. If a document contains a contract type the processor does not support, the processor MUST NOT run; it returns a must-understand failure (§22.1).
• External channels must clearly define what they accept (by type/shape) and how they match.
• Determinism. Handlers must be deterministic. Their only effects are: changeDocument (list of Json Patch Entry), emitEvent (Blue node), consumeGas(units), and terminate(cause, reason?). No other side effects are permitted.
• Markers may set policies; where the spec mandates, the processor MUST obey them.

(Validated by: T8–T10, T20–T22.)

§19. The PROCESS Algorithm (applied at root and at each embedded scope)

Signature. PROCESS(doc, event) → (new_doc, triggered_events, total_gas)
Events are Blue nodes. There is no envelope.

Important timings (normative):

• Cascades queue, never drain. Document Update cascades execute handlers immediately at each scope; any Triggered emissions are enqueued to that scope’s persistent FIFO and not delivered during the cascade.
• Bridge then drain. A parent bridges child emissions (if configured) before it drains its own FIFO.
• One drain per scope. A scope’s FIFO is drained once at the end of that scope’s _PROCESS (Phase 5).

Top-level wrapper

1function PROCESS(doc, event):
2    RUN.root_events      = []
3    RUN.total_gas        = 0
4    RUN.emitted_by_scope = {}   # scope → [bridgeable node] (Triggered + lifecycle)
5    RUN.fifo_by_scope    = {}   # scope → FIFO (persistent for the run)
6    RUN.terminated_scopes= {}   # scope → true when terminated
7    try:
8        (_doc, _scope_emitted) = _PROCESS(doc, event, scope="/")
9        return (doc, RUN.root_events, RUN.total_gas)
10    except TERMINAL_FAILURE:
11        # A fatal termination at root ends the run.
12        return (doc, RUN.root_events, RUN.total_gas)
13

Core routine (applied at every scope)

1function _PROCESS(doc, event, scope):
2    scope_bucket = ensure_bucket(RUN.emitted_by_scope, scope)  # bridgeable emissions (Triggered + lifecycle)
3    scope_fifo   = ensure_fifo(RUN.fifo_by_scope, scope)       # persistent FIFO for THIS scope
4
5    # PHASE 1 — Process embedded children (recursive, dynamic)
6    processed_paths = insertion_ordered_set()
7    loop:
8        paths = read_process_embedded_paths(doc, scope)  # validates contracts/embedded is Process Embedded (Appendix A)
9        next_path = first p in paths where p ∉ processed_paths
10        if next_path is None:
11            break
12        if node_exists(doc, next_path):
13            (doc, _) = _PROCESS(doc, event, scope=next_path)  # single document model
14        processed_paths.add(next_path)
15        # Re-reads 'paths' after each child: adds/removes/reorders take effect for the next child.
16        # Stabilization: once a child path enters processed_paths, it will NOT be processed again in this run,
17        # even if removed then re-added later ("no resurrection" within a run).
18
19    # Early-out if this scope was terminated by a child-side cascade or lifecycle
20    if RUN.terminated_scopes.get(scope, false):
21        return (doc, RUN.emitted_by_scope[scope])
22
23    # PHASE 2 — Initialize this scope (first run only)
24    if not has_initialization_marker(doc, scope):
25        pre_init_id = compute_blue_id_at_scope(doc, scope)
26
27        # 2.A Lifecycle: Document Processing Initiated (Appendix A)
28        lifecycle_node = make_initiated_event(pre_init_id)  # payload defined in Appendix A
29        doc = DELIVER_LIFECYCLE(doc, scope, lifecycle_node)
30
31        # 2.B Add Processing Initialized Marker under reserved key 'initialized' (Appendix A)
32        ensure_reserved_empty_or_compatible(doc, scope, "initialized", "Processing Initialized Marker")
33        doc = APPLY_PATCH_WITH_CASCADE(doc, origin_scope=scope,
34              patch = json_patch_add( scope + "/contracts/initialized",
35                                     make_initialized_marker(pre_init_id) ))  # marker definition in Appendix A
36
37    if RUN.terminated_scopes.get(scope, false):
38        return (doc, RUN.emitted_by_scope[scope])
39
40    # PHASE 3 — Match channels; run handlers for the external event
41    channels = sort_by_order_then_key( find_matching_channels(doc, scope, event) )
42    for ch in channels:
43        if RUN.terminated_scopes.get(scope, false):
44            break
45
46        if is_external_channel(ch):  # processor-fed families are NOT gated
47            # Lazy checkpoint creation: if missing, create empty before newness evaluation
48            if not has_checkpoint_marker(doc, scope):
49                DIRECT_WRITE(doc, scope + "/contracts/checkpoint", make_empty_checkpoint())
50            ckpt = read_checkpoint(doc, scope)  # must exist now
51            if not checkpoint_is_new(ckpt, ch.key, event):
52                continue
53
54        handlers = sort_by_order_then_key( find_handlers_for_channel(doc, scope, ch) )
55        for h in handlers:
56            res = execute_handler(h, context_for(scope, event, scope_fifo))
57            RUN.total_gas += res.gas_consumed
58
59            # 3.A Apply patches; each applied patch triggers a bottom-up Document Update cascade
60            for p in res.patches:
61                if boundary_violation(doc, scope, p):  # includes "self-root", "root target", reserved-key write
62                    ENTER_TERMINAL_TERMINATION(doc, scope, "Boundary violation at " + p.path)
63                doc = APPLY_PATCH_WITH_CASCADE(doc, origin_scope=scope, patch=p)
64
65            # 3.B Record & enqueue Triggered emissions
66            for t in res.triggered_events:
67                EMIT_TO_SCOPE(scope, t)
68
69            # 3.C Optional termination from handler
70            if res.terminated:
71                ENTER_GRACEFUL_TERMINATION(doc, scope, res.termination_reason)
72
73        if is_external_channel(ch) and not RUN.terminated_scopes.get(scope, false):
74            # After successful channel processing, update checkpoint for ch.key with the entire event node
75            ckpt2 = read_checkpoint(doc, scope)  # exists
76            DIRECT_WRITE(doc, scope + "/contracts/checkpoint", checkpoint_update(ckpt2, ch.key, event))
77
78    if RUN.terminated_scopes.get(scope, false):
79        return (doc, RUN.emitted_by_scope[scope])
80
81    # PHASE 4 — Parent-only: bridge each child's emissions via Embedded Node
82    # Bridge FIRST (may enqueue many items into THIS scope’s FIFO).
83    for child_path in iteration_order(processed_paths):
84        embedded_ch = find_embedded_node_channel(doc, scope, child_path)
85        if not embedded_ch:
86            continue
87        child_events = RUN.emitted_by_scope.get(child_path, [])
88        if child_events.is_empty():
89            continue
90        emb_handlers = sort_by_order_then_key( find_handlers_for_channel(doc, scope, embedded_ch) )
91        for ev in child_events:
92            for h in emb_handlers:
93                res = execute_handler(h, context_for(scope, ev, scope_fifo))
94                RUN.total_gas += res.gas_consumed
95                for p in res.patches:
96                    if boundary_violation(doc, scope, p):
97                        ENTER_TERMINAL_TERMINATION(doc, scope, "Boundary violation at " + p.path)
98                    doc = APPLY_PATCH_WITH_CASCADE(doc, origin_scope=scope, patch=p)
99                for t in res.triggered_events:
100                    EMIT_TO_SCOPE(scope, t)
101
102    if RUN.terminated_scopes.get(scope, false):
103        return (doc, RUN.emitted_by_scope[scope])
104
105    # PHASE 5 — Drain THIS scope’s Triggered FIFO (if channel exists)
106    if has_triggered_event_channel(doc, scope):
107        doc = DRAIN_TRIGGERED_QUEUE(doc, scope)  # drains once
108
109    return (doc, RUN.emitted_by_scope[scope])
110

Notes.

• Balloon cut-off. If a parent removes a child mid-run, that child’s current handler finishes; no further work (no extra handlers, no FIFO drain) occurs for that scope in this run. Already recorded emissions are preserved and will be bridged to the parent (including Document Processing Terminated on fatal). Re-adding the same path later in the run does not schedule it again (“no resurrection” within a run).
• Direct Write is defined in §19.1.

Emit & record helpers

1# Records a Triggered node as emitted by 'scope' and enqueues it for local delivery.
2# - Appends to RUN.emitted_by_scope[scope] (for parent bridging)
3# - Enqueues to RUN.fifo_by_scope[scope]
4# - If scope is root, also appends to RUN.root_events (returned even if handled)
5function EMIT_TO_SCOPE(scope, node):
6    bucket = ensure_bucket(RUN.emitted_by_scope, scope)
7    fifo   = ensure_fifo(RUN.fifo_by_scope, scope)
8    bucket.append(node)
9    fifo.enqueue(node)
10    if scope == "/":
11        RUN.root_events.append(node)
12
13# Records a lifecycle node for bridging ONLY (no local Triggered delivery).
14function RECORD_BRIDGEABLE(scope, node):
15    bucket = ensure_bucket(RUN.emitted_by_scope, scope)
16    bucket.append(node)
17    if scope == "/":
18        RUN.root_events.append(node)
19

Apply patch + immediate bottom-up cascades

1function APPLY_PATCH_WITH_CASCADE(doc, origin_scope, patch):
2    before = snapshot_at(doc, patch.path)   # before mutation
3    doc    = apply_json_patch(doc, patch)   # §21.2 (absolute pointers, array bounds, auto-materialization)
4    after  = snapshot_at(doc, patch.path)   # after mutation (null for remove)
5
6    for scope in ancestors_including_self_up_to_root(origin_scope):   # e.g., /a/b → [/a/b, /a, /]
7        channels = sort_by_order_then_key(
8                     filter_subtree_matches_by_absolute_path(
9                        find_document_update_channels(doc, scope),
10                        changed_abs_path = patch.path))
11
12        if channels.is_empty():
13            continue
14
15        # One immutable payload object per scope (same for all handlers in S)
16        event = make_document_update_event(scope, patch.op, patch.path, before, after)  # Appendix A “Document Update”
17
18        fifo = ensure_fifo(RUN.fifo_by_scope, scope)
19        for ch in channels:
20            handlers = sort_by_order_then_key( find_handlers_for_channel(doc, scope, ch) )
21            for h in handlers:
22                res = execute_handler(h, context_for(scope, event, fifo))
23                RUN.total_gas += res.gas_consumed
24                for nested in res.patches:
25                    if boundary_violation(doc, scope, nested):  # includes reserved-key write-protection
26                        ENTER_TERMINAL_TERMINATION(doc, scope, "Boundary violation at " + nested.path)
27                    doc = APPLY_PATCH_WITH_CASCADE(doc, origin_scope=scope, patch=nested)
28                for emitted in res.triggered_events:
29                    EMIT_TO_SCOPE(scope, emitted)
30
31    return doc
32

Drain a scope’s Triggered FIFO

1function DRAIN_TRIGGERED_QUEUE(doc, scope):
2    trig_ch = get_triggered_event_channel(doc, scope)
3    if not trig_ch:
4        return doc
5
6    fifo = ensure_fifo(RUN.fifo_by_scope, scope)
7    while not fifo.is_empty():
8        ev = fifo.dequeue()
9        handlers = sort_by_order_then_key( find_handlers_for_channel(doc, scope, trig_ch) )
10        for h in handlers:
11            res = execute_handler(h, context_for(scope, ev, fifo))
12            RUN.total_gas += res.gas_consumed
13            for p in res.patches:
14                if boundary_violation(doc, scope, p):
15                    ENTER_TERMINAL_TERMINATION(doc, scope, "Boundary violation at " + p.path)
16                doc = APPLY_PATCH_WITH_CASCADE(doc, origin_scope=scope, patch=p)
17            for t in res.triggered_events:
18                EMIT_TO_SCOPE(scope, t)
19    return doc
20

Deliver Lifecycle at a scope

1function DELIVER_LIFECYCLE(doc, scope, lifecycle_node):
2    # Record lifecycle node for bridging (always)
3    RECORD_BRIDGEABLE(scope, lifecycle_node)
4
5    life_channels = sort_by_order_then_key( find_lifecycle_channels(doc, scope) )
6    fifo = ensure_fifo(RUN.fifo_by_scope, scope)
7    for ch in life_channels:
8        handlers = sort_by_order_then_key( find_handlers_for_channel(doc, scope, ch) )
9        for h in handlers:
10            res = execute_handler(h, context_for(scope, lifecycle_node, fifo))
11            RUN.total_gas += res.gas_consumed
12            for p in res.patches:
13                if boundary_violation(doc, scope, p):
14                    ENTER_TERMINAL_TERMINATION(doc, scope, "Boundary violation at " + p.path)
15                doc = APPLY_PATCH_WITH_CASCADE(doc, origin_scope=scope, patch=p)
16            for t in res.triggered_events:
17                EMIT_TO_SCOPE(scope, t)
18    return doc
19

§19.1 Direct Writes (normative)

A Direct Write is a processor mutation that does not produce a Document Update cascade and does not schedule any cascade work. It is used only for:

• Writing the Processing Terminated Marker (Appendix A) at a scope on termination (§22).
• Creating a Channel Event Checkpoint (Appendix A) at a scope lazily when an external channel is first evaluated and no checkpoint exists (§23).
• Updating the checkpoint’s lastEvents[channelKey] after successful external channel processing (§23).

Direct Writes are visible to subsequent logic in the same run and persist in new_doc. They appear only under reserved keys (e.g., /…/contracts/terminated, /…/contracts/checkpoint). Handlers/channels cannot perform Direct Writes; they are processor-internal (§15, §23).

§20. Initialization (first-run)

On the first processing of a scope:

1. Compute the pre-init BlueId of the scope’s subtree.
2. Publish Document Processing Initiated (Appendix A) via the scope’s Lifecycle Event Channel (root also records it in triggered_events).
3. Add Processing Initialized Marker (Appendix A) under contracts/initialized (this patch MUST cause a Document Update cascade).

Reserved keys are listed in §15; incompatible presence is fatal (§22.2).

No eager checkpoint creation. The processor MUST NOT create contracts/checkpoint during initialization solely to satisfy presence. The checkpoint is created lazily per §23 when an external channel is first evaluated at this scope.

(Validated by: T3, T15.)

§21. Document Updates & JSON Patch semantics

21.1 Document Update cascades (immediate & bottom-up)

One patch → a cascade of deliveries. When a handler’s patch applies successfully, the processor:

• captures before/after snapshots at the patch’s absolute path,
• delivers exactly one Document Update (Appendix A) per scope along the chain: origin → each ancestor → root, in that order.

At each scope S:

• Matching uses the patch’s absolute changed path vs ABS(S, P) with subtree semantics (equal or descendant).
• Delivered event has uniform content within S. All handlers at S see the same op and the same before/aftersnapshots; the path is scope-relative to S. Contracts MUST treat this event as read-only (§15).
• Handlers may patch/emit/consumeGas/terminate.
• No drain during cascades (normative). Triggered emissions produced during a cascade are enqueued to S’s persistent FIFO and MUST NOT be delivered during the cascade. S’s FIFO is drained once, at the end of S’s _PROCESS (Phase 5 in §19).

(Validated by: T4, T5, T14, T17.)

21.2 JSON Patch semantics (normative)

Handlers emit Json Patch Entry objects (Appendix A). The processor applies each patch immediately to the shared document, then performs the Document Update cascade (§21.1). Blue supports a practical, deterministic subset of RFC 6902:

• Supported operations: add, replace (upsert semantics), remove.
  Other ops (move, copy, test, …) → deterministic runtime fatal.

Pointer evaluation.

• Patch path values are absolute JSON Pointers (must begin with /); segments are interpreted literally.
• Numeric segments are allowed (arrays).
• - is accepted (array append).
• Escaped tokens (e.g., ~1) are treated verbatim (per JSON Pointer).
• Pointers resolve against the current document state, after earlier patches in the same run.

Root-document target forbidden (normative).
The target path MUST NOT be "/" (document root). Replacing/removing the entire document is forbidden.

Object auto-materialization.
Missing intermediate objects are materialized as empty objects before applying the patch. Auto-created containers are part of the same patch; the Document Update describes the final requested path.

Object targets.
add inserts a new member or replaces an existing member.
replace behaves as upsert.
remove deletes a member. Removing a non-existent member → deterministic runtime fatal.

Array targets.
Segments may be numeric indices or -.
add with index inserts at that position (shifting).
add with - appends.
replace overwrites element at index (index must exist).
remove deletes the element at index (shifts left; index must exist).
Out-of-range indices (for replace/remove) → deterministic runtime fatal.

Boundary enforcement.
Every patch is validated against embedded-scope isolation (§16). Any attempt to modify another scope’s interior → deterministic runtime fatal. A parent may add/replace/remove a child root (e.g., /payment), but MUST NOT reach inside it (e.g., /payment/amount). A child MAY NOT target its own scope root S (self-root mutation forbidden).

These rules let authors grow deep structures and manipulate arrays predictably while preserving the one-patch → one-cascade guarantee and determinism.

21.3 Helper notation (normative)

ABS(S, P) — the absolute JSON Pointer for a channel path P declared at scope S (normalized concatenation of S and P).
relativize_pointer(S, ABS) — the relative pointer from scope S’s root to ABS (returns "/" when ABS == S).
relativize_snapshot(S, node) — a read-only view or clone of node as observed at S. Nodes carry no path context; the relative path provides the location for handlers.

§22. Failure & termination semantics

22.1 Capability failure (must-understand)

If the document contains a contract type the processor does not support, the processor MUST return a must-understand failure and MUST NOT mutate the document or emit lifecycle fatals. (T9.)

22.2 Termination (graceful or fatal)

A channel or handler may invoke terminate(cause, reason?), and the processor may terminate a scope fatally for deterministic runtime errors (e.g., boundary violation).

When a scope terminates (either cause):

1. Direct Write contracts/terminated with a Processing Terminated Marker (Appendix A), setting:

• cause: "graceful" or "fatal"
• reason: <optional Text>

2. Publish Document Processing Terminated at that scope (Appendix A; Lifecycle Event Channel).

• Lifecycle is also recorded for bridging via RECORD_BRIDGEABLE (§19).

3. Deactivate the scope for the rest of the run: mark RUN.terminated_scopes[scope]=true and drop its FIFO; further patch/emit from that scope are no-ops.

Escalation rules.

• Non-root fatal → scope-terminal only: preserve already recorded emissions for parent bridging; continue elsewhere.
• Root fatal → run-terminal: additionally append Document Processing Fatal Error (Appendix A) to the root run result (outbox-only; never routed) and abort the run (raise TERMINAL_FAILURE).
• Non-root graceful → scope ends normally; parent may still bridge the scope’s emissions (including the Terminatedlifecycle) if configured.

(Validated by: T23–T30.)

Termination helpers (informative pseudocode).

1function ENTER_GRACEFUL_TERMINATION(doc, scope, reason?):
2    DIRECT_WRITE(doc, scope + "/contracts/terminated",
3                 make_terminated_marker(cause="graceful", reason=reason))
4    term_ev = make_terminated_event(cause="graceful", reason=reason)  # Appendix A
5    doc = DELIVER_LIFECYCLE(doc, scope, term_ev)
6    RUN.terminated_scopes[scope] = true
7    clear_fifo(RUN.fifo_by_scope, scope)
8    if scope == "/":
9        # Root graceful ends the run after current call stack unwinds
10        raise TERMINAL_FAILURE_GRACEFUL
11    return doc
12
13function ENTER_TERMINAL_TERMINATION(doc, scope, reason):
14    DIRECT_WRITE(doc, scope + "/contracts/terminated",
15                 make_terminated_marker(cause="fatal", reason=reason))
16    term_ev = make_terminated_event(cause="fatal", reason=reason)  # Appendix A
17    doc = DELIVER_LIFECYCLE(doc, scope, term_ev)
18    RUN.terminated_scopes[scope] = true
19    clear_fifo(RUN.fifo_by_scope, scope)
20    if scope == "/":
21        # Outbox-only fatal lifecycle
22        RUN.root_events.append(make_fatal_outbox(reason))  # Appendix A
23        raise TERMINAL_FAILURE
24    return doc
25

§23. Channel Event Checkpoints

Purpose. A Channel Event Checkpoint records, per external channel key, the last processed event node (entire node, not just an id), enabling idempotent and ordered processing for external sources. (Type in Appendix A.)

Presence & lazy creation.
A scope may lack contracts/checkpoint until it first evaluates an external channel. When an external channel at scope S is evaluated and contracts/checkpoint is absent, the processor MUST DIRECT_WRITE(S + "/contracts/checkpoint", make_empty_checkpoint()) before applying the newness test. From that point on, the scope has exactly one checkpoint. Multiple checkpoints in a scope are a deterministic runtime fatal.

Gating rule (external channels only).
For a matched external channel at scope S:

• The processor consults the scope’s checkpoint to decide whether the incoming event is newer than lastEvents[channelKey] (deterministic policy).
• If not newer, the channel is skipped (no handlers run).
• If newer and the channel completes successfully, the processor MUST DIRECT_WRITE an update setting lastEvents[channelKey] to the entire event node (no Document Update is emitted).

Not gated. Processor-managed families (Document Update, Triggered, Lifecycle, Embedded Node) are never subject to checkpoint gating.

Tamper resistance. Reserved keys are write-protected (§15). Any handler attempt to patch contracts/checkpoint (or descendants) is a deterministic runtime fatal.

(Validated by: T8, T18 (lazy creation), T19–T22.)

§24. Gas accounting

24.1 Philosophy & unit (normative)

Purpose. Gas accounting prevents resource-exhaustion while remaining proportional to actual work.

Unit. Gas is an abstract deterministic unit. Processors MUST NOT base gas on wall-clock, CPU model, memory, or I/O. (Informative calibration: profiles MAY document a human-readable mapping; conformance depends solely on the formulas below.)

24.2 What is charged and when (normative)

Processors MUST add the following charges to RUN.total_gas at the exact points indicated. Charges apply in addition to any explicit consumeGas(units) from channels/handlers.

24.2.1 Scope management

depth = number of embedded edges from root (/→0; /a/b→2).

24.2.2 Matching & routing

24.2.3 Patches & cascades

bytes = UTF-8 length of the canonical JSON of the patch val after Part I §8.2 cleaning/normalization (RFC 8785).

24.2.4 Event emission, bridging & draining

bytes = canonical JSON size of the emitted event node.

24.2.5 Checkpoints & direct writes

Direct Write is defined in §19.1; it never triggers Document Update.

24.2.6 Lifecycle & termination

Fatal termination total for the termination step: 150 gas (= marker 20 + lifecycle 30 + fatal overhead 100), plus any prior work already charged. Graceful termination step: 50 gas (= marker 20 + lifecycle 30).

24.3 Accumulation & determinism (normative)

RUN.total_gas MUST include:

• all processor charges from §24.2, and
• all explicit consumeGas(units) calls made by channels/handlers.

Gas MUST be computed solely from:

• operation counts (handlers run, events enqueued/dequeued/bridged, scopes in cascade),
• structural properties (scope depth, cascade length),
• measurable sizes (canonical JSON byte length).

Gas MUST NOT depend on:

• wall-clock time, CPU speed/architecture, memory pressure,
• network/IO latency, OS scheduler effects.

Given the same input document and event, all conforming processors MUST return the same total_gas.

24.4 Policies & overruns (normative)

Accounting only. Part II defines gas accounting, not enforcement. Gas is recorded to RUN.total_gas for transparency and diagnostics. Absent an active policy, the processor MUST NOT modify behavior or terminate due to gas usage; it simply continues and returns the measured total.

Policy‐driven enforcement (external). Budgets/limits MAY be defined by separate, document-authored policies (markers/contracts outside this Part). Such policies may specify what budgets exist, when/how measurements are compared to budgets, and the exact behavior on overrun (e.g., graceful/fatal termination per §22, skipping work, emitting signals, etc.). The processor MUST implement any present policy it claims to support exactly. If a policy type is present but unsupported, the processor MUST return a must-understand failure (§22.1).

Determinism. Policies MUST be deterministic and base decisions only on data available within the run (including the gas totals defined in §24), to preserve cross-implementation consistency.

24.5 Validation examples (informative)

• Simple replace at root (~4 bytes) — Matching (1×5) + handler overhead (50) + patch replace (20) + cascade (1×10) → 85 gas (+ any handler consumeGas).
• Deep scope entry (depth=10) first run, small patch — Entry (50+100) + init (1000) + handler (50) + replace (~100B → 21) + cascade (2×10) → 1231 gas (+ handler consumeGas).
• 2 KB replace across 5 scopes — Replace (20+20) + cascade (5×10) + handler overhead (5×50) → 340 gas (+ handler logic at each scope).
• Emit 500×1 KB events — Emissions (500×(20+10)) + drain (500×10) + handler overhead (500×50) → 45 000 gas(+ handler consumeGas).

Sizes use canonical JSON per Part I §8.2.

24.6 Implementation hooks (informative)

Where to add charges in the algorithm (§19):

• _PROCESS entry: scope-entry charge.
• §20 init path: init charge; lifecycle delivery charge; if a checkpoint marker is created, do not charge gas for this creation.
• Phase 3: per channel match attempt; per handler overhead; per patch boundary check + op charge + cascade charge (count scopes actually receiving Document Update); per emitted event charge.
• Phase 4: per bridged node charge (before running handlers).
• Phase 5: per dequeued event charge (before handler overhead).
• §22 termination: termination marker Direct Write, lifecycle delivery, and fatal overhead (if fatal).

Bytes measurement: apply Part I §8.2 cleaning & RFC 8785 canonicalization; use UTF-8 length of the canonical JSON string; use ceil(bytes/100) in formulas.

§25. Processor vs Feeder (division of responsibility)

Feeder (out of scope here) — collects external events, orders/deduplicates them per the application’s policy (scheduler, vector clocks, chain logs…). The feeder may deliver stale/out-of-order items; Channel Event Checkpoint ensures scopes ignore stale external events.

Processor (this Part) — given (document, event), executes exactly the rules in this Part (initialization, matching, cascades, bridging, FIFO drains, failures/termination) to produce (new_doc, triggered_events, total_gas).

§26. Conformance checklist (normative)

A compliant processor MUST:

Embedded traversal

• Read Process Embedded paths dynamically, re-reading after each child, and process each existing child at most once per run in first-seen order (no resurrection within a run).
• Enforce the boundary rule (§16): the parent can add/replace/remove the child root, but MUST NOT patch strictly inside another active embedded subtree.
• Enforce self-root mutation forbidden and root "/" target forbidden.

Contract capabilities

• Enforce must-understand: any unsupported contract type → capability failure (no mutation, no lifecycle fatals).
• Use deterministic sorting for channels and handlers: (order, key) at every scope.
• Treat delivered payloads as immutable (§15).
• Enforce write-protection of reserved keys (§15).

Initialization

• On first run at a scope: publish Document Processing Initiated and add Processing Initialized Marker (patch → Document Update).
• Do not create a checkpoint at init time; create lazily per §23.

Patch & cascade semantics

• After every applied patch, emit exactly one Document Update per scope in the cascade: origin → ancestors → root.
• Match Document Update channels by absolute changed path vs ABS(S,P) with subtree semantics.
• Deliver a scope-relative payload; all handlers at a scope MUST see the same Document Update payload object for a given patch.
• Maintain a per-scope Triggered FIFO; never drain during cascades; drain once at the end of the scope’s _PROCESS(Phase 5).
• Record every emission at its scope; append root-scope emissions and root lifecycle items to the run’s triggered_events.

JSON Patch subset

• Implement supported ops: add, replace (upsert), remove. Reject other RFC 6902 ops.
• Pointers are absolute; support numeric indices and - for append.
• Do not allow the document root "/" as a patch target.
• Auto-materialize missing intermediate objects.
• Enforce array bounds and object existence (out-of-range / remove-missing → deterministic runtime fatal).

Checkpoint presence & behavior

• Exactly one Channel Event Checkpoint per scope after first external evaluation (Appendix A). Duplicate → runtime fatal.
• For external channels, gate using the checkpoint’s newness rule; skip stale/duplicate events.
• After successful channel processing, Direct Write lastEvents[channelKey] = <entire event node> (no Document Update).
• Processor-managed families are not gated.

Failure/termination

• On termination, Direct Write Processing Terminated Marker with cause (fatal/graceful), publish Document Processing Terminated, and deactivate the scope for the remainder of the run.
• On root fatal, also append Document Processing Fatal Error to the root run result and abort the run.

Run result

• Return (new_doc, triggered_events, total_gas) exactly as defined in §15/§19.

§27. Test vectors (normative, behavior-defining)

T1 — Dynamic embedded list
Root declares paths: [/a, /b]. While processing /a, a root handler removes /b and adds /c.
Then: After /a, the processor re-reads paths and visits /c; /b is skipped (no longer exists).

T2 — Boundary enforcement
Root attempts replace /a/x while /a is an active embedded child.
Then: Fatal termination at root; contracts/terminated is written with Processing Terminated Marker (cause: fatal), a Document Processing Fatal Error is appended to the root run result; run aborts.

T3 — Initialization once
First run at /a writes Processing Initialized Marker (patch) and publishes Document Processing Initiated.
Then: The patch triggers a Document Update cascade; lifecycle may trigger additional work at /a.

T4 — Update cascades (absolute match & relative payload)
A handler at /a applies replace /a/z/k. Root has a Document Update Channel watching /a/z.
Then: At scope /a, payload path="/z/k"; at root, "/a/z/k". Matching uses absolute paths; each scope sees the same payload content relative to itself.

T5 — Cascade emissions are enqueued (not delivered)
Patch at /a/b causes a Document Update handler at /a to emit E.
Then: E is recorded under /a and enqueued; it is delivered later in /a’s Phase 5 (not during the cascade).

T6 — Triggered FIFO (deterministic order)
A handler at /a emits E1, E2. /a has a Triggered Event Channel.
Then: /a drains FIFO (E1 then E2); further emissions during drain append to the tail and are processed deterministically.

T7 — Bridging child emissions
Child /x emits events during its run. Parent has an Embedded Node Channel for /x.
Then: After parent completes external handling, it bridges /x’s emissions (patches cascade), then drains the parent FIFO once.

T8 — Checkpoint gating (external only)
A scope checkpoint exists. Two external channels match the event; one is stale, one is new.
Then: The stale one is skipped; the new one runs; checkpoint updates via Direct Write.

T9 — Capability failure (must-understand)
Document contains unknown contract type.
Then: Processor returns must-understand failure; no patches; no lifecycle fatals.

T10 — No-match
No channel matches anywhere.
Then: Processor returns unchanged document, empty triggered_events, measured total_gas.

T11 — Object auto-materialization
A handler applies add /a/b/c {…} where /a exists but /a/b does not.
Then: Processor creates /a/b as {} then writes /a/b/c; one cascade runs.

T12 — Array append and insert
Given /a/items: ["x","y"].
add /a/items/- "z" → ["x","y","z"] (append).
add /a/items/1 "q" → ["x","q","y"] (insert).
Then: Each patch triggers one cascade; out-of-range indices → fatal (T13).

T13 — Deterministic runtime fatals (arrays & objects)
replace /a/items/7 "z" when length < 8 → fatal.
remove /a/missingKey → fatal.
Then: The failing scope gets contracts/terminated with Processing Terminated Marker (cause: fatal); root fatal only if the scope is root.

T14 — Scope-relative payload
Patch at /a/b to replace /a/b/x.
Then: At /a/b: path="/x", at /a: "/b/x", at root: "/a/b/x". Same op, before, after; only path is scope-relative.

T15 — Root lifecycle inclusion
First processing at root publishes Document Processing Initiated; later, a fatal elsewhere.
Then: Root run result includes both lifecycle items in triggered_events.

T16 — Local delivery depends on Triggered Channel presence
During a cascade at /a, a handler emits E. /a lacks a Triggered Event Channel.
Then: E is recorded as emitted by /a (bridgeable upward if parent configured) but is not delivered locally at /a.

T17 — Uniform event per scope
Multiple Document Update Channels at /a match the same patch.
Then: All handlers at /a see the same Document Update payload object; differences arise only from channel/handler order/matching.

T18 — Lazy checkpoint creation
A scope processes an external event and contracts/checkpoint is absent.
Then: Before newness evaluation, the processor DIRECT_WRITEs an empty checkpoint at /…/contracts/checkpoint(lastEvents = {}). Newness evaluates as “no prior”; if handlers succeed, lastEvents[channelKey] becomes the entire event node by Direct Write. No Document Update is emitted for either write.

T19 — Duplicate checkpoint
A scope contains two Channel Event Checkpoint markers.
Then: Runtime fatal (only one is permitted).

T20 — Stale external event is gated
lastEvents.testEventsChannel holds E_old; incoming E_new is not newer.
Then: Channel is skipped; checkpoint unchanged.

T21 — Checkpoint updated after success
A new external event on testEventsChannel is processed successfully.
Then: lastEvents.testEventsChannel = <entire event node> via Direct Write (no Document Update).

T22 — Multiple external channels at a scope
Two external channels match the same event and both are “newer.”
Then: Both run in (order, key) order; each updates its own key in lastEvents.

T23 — Self-root mutation is forbidden
While executing at /a, a contract attempts remove /a (or replace /a, add /a).
Then: Fatal termination at /a.

T24 — Root-document mutation is forbidden
Any contract attempts to target "/" with any op.
Then: Fatal termination at the executing scope (root fatal ends the run).

T25 — Balloon cut-off on child removal
While /b is being processed, a parent watcher removes /b.
Then: The current /b handler finishes; no further work (no extra handlers, no drain) occurs for /b; already recorded /b emissions (including Terminated on fatal) are bridgeable; re-adding /b in this run does not schedule it again.

T26 — Termination is final
A scope terminates gracefully; later in the same run a handler at that scope attempts to emit or patch.
Then: No-op; scope is inactive for the remainder of the run.

T27 — Child fatal does not escalate by default
/a terminates fatally.
Then: /a is marked terminated; parent continues; child emissions (including Terminated) are bridgeable if parent configured Embedded Node Channel.

T28 — Child graceful termination bridges lifecycle
/a terminates gracefully.
Then: Parent may observe Document Processing Terminated via Embedded Node Channel if configured.

T29 — Root graceful termination ends run
Root terminates gracefully.
Then: Run ends; root outbox includes Document Processing Terminated.

T30 — Root fatal termination ends run with fatal outbox
Root terminates fatally.
Then: Run ends; root outbox includes Document Processing Terminated and Document Processing Fatal Error.

Appendix A — Core Primitive & Collection Types

§A.1 Core Primitive

1name: Text
2description: >
3  Core primitive scalar representing Unicode text (a JSON string).
4
5  - Authoring & wrappers:
6      detail: >
7        Instances may be authored as scalar sugar (myField: "hello") or as the
8        wrapped form (myField: { value: "hello" }). Canonical hashing uses the
9        wrapped form (§8.2.2). This type itself does NOT declare a `value`
10        field: `value` is the language wrapper for instance payloads (§2.1);
11        putting `value` on the type would fix a concrete payload on the type
12        object (a fixed-value invariant, §4.1), which is not intended.
13
14  - Length semantics:
15      detail: >
16        minLength/maxLength count Unicode code points, not bytes and not UTF-16
17        code units. A character outside the BMP (e.g., "𝄞") counts as 1.
18        A CRLF pair counts as 2 code points ("\r" + "\n").
19
20  - Regex dialect:
21      detail: >
22        `pattern` uses ECMA-262 syntax. Matching is not implicitly anchored; use
23        ^…$ for whole-string matches.
24
25  - Canonical JSON vs content:
26      detail: >
27        RFC 8785 canonicalization affects only JSON encoding (escapes, key
28        ordering of parent objects). It NEVER changes the underlying code-point
29        sequence. Equality (including `enum`) compares the parsed scalar value.
30
31  - Unicode normalization:
32      detail: >
33        Processors MUST NOT normalize Text by default (no NFC/NFD folding).
34        The exact code-point sequence is preserved. Any optional normalization
35        may occur only via profile-specific preprocessing in `blue` (§7.1).
36
37  - Case/locale:
38      detail: >
39        No case folding or locale-sensitive collation is implied in Part I.
40        Perform such transforms explicitly during preprocessing (profile-
41        dependent) or in higher-level contracts (Part II).
42
43  - Empty string:
44      detail: >
45        The empty string "" is valid unless restricted by schema (e.g., minLength > 0).
46
47  - Escapes & line breaks:
48      detail: >
49        JSON escapes (\uXXXX, \" \\ \n \r \t \b \f) are authoring/encoding
50        details only; after parsing they contribute their code points to length
51        and pattern checks.
52
53  - Applicable schema:
54      detail: >
55        §5.5 string constraints: minLength, maxLength, pattern.

1name: Integer
2description: >
3  Primitive numeric scalar for mathematical integers (ℤ).
4
5  - Domain & arithmetic:
6      detail: >
7        Represents …, -2, -1, 0, 1, 2, … with arbitrary precision. There is no
8        fixed bit width and no overflow. Arithmetic is exact; operations may
9        fail only due to resource exhaustion.
10
11  - Authoring & wrappers:
12      detail: >
13        Scalar sugar (x: 1) and wrapped form (x: { value: 1 }) are equivalent
14        for authoring; canonical hashing uses the wrapped form (§8.2.2). The
15        type does NOT declare `value` because that wrapper belongs to instances;
16        declaring it on the type would fix a payload on the type object (§2.1, §4.1).
17
18  - Canonical textual form:
19      detail: >
20        Optional leading "-" for negatives, followed by one or more decimal
21        digits; no leading zeros except the single digit "0".
22
23  - Schema & combination:
24      detail: >
25        §5.4 numeric constraints apply: minimum, maximum, exclusiveMinimum,
26        exclusiveMaximum, multipleOf (> 0). If multiple `multipleOf` appear in a
27        type chain, combine via least common multiple (LCM) as specified.
28
29  - Equality & enums:
30      detail: >
31        Equality (incl. `enum`) compares the parsed scalar value in canonical JSON terms.

1name: Double
2description: >
3  Primitive numeric scalar for floating-point real numbers.
4
5  - Semantics:
6      detail: >
7        Computation aligns with IEEE 754 binary64 ("double precision").
8        JSON permits only finite numbers; NaN and ±Infinity are invalid Blue nodes.
9
10  - Authoring & wrappers:
11      detail: >
12        Scalar sugar (x: 1.25) and wrapped form (x: { value: 1.25 }) are
13        equivalent for authoring; canonical hashing uses the wrapped form
14        (§8.2.2). The type does NOT declare `value` (instance wrapper); putting
15        it on the type would fix an instance payload (§2.1, §4.1).
16
17  - Canonical textual form:
18      detail: >
19        RFC 8785 canonical-JSON number: base-10 notation, no leading zeros, no
20        leading "+", optional exponent with lower-case "e", and no unnecessary
21        trailing zeros or decimal point.
22
23  - Precision & comparison:
24      detail: >
25        Processors should be aware of binary64 rounding when performing numeric
26        operations. Schema comparisons use the numeric value (per §5.4). Equality
27        and `enum` compare by canonical JSON value semantics, not by byte shape.
28
29  - Schema:
30      detail: >
31        §5.4 numeric constraints apply: minimum, maximum, exclusiveMinimum,
32        exclusiveMaximum, multipleOf (> 0).

1name: Boolean
2description: >
3  Primitive scalar with exactly two values: true and false.
4
5  - Authoring & wrappers:
6      detail: >
7        Scalar sugar (x: true) and wrapped form (x: { value: true }) are
8        equivalent; canonical hashing uses the wrapped form (§8.2.2). The type
9        does NOT declare `value` because it is an instance-level wrapper; adding
10        it to the type would fix a payload on the type object (§2.1, §4.1).
11
12  - Semantics:
13      detail: >
14        No truthiness beyond the two literals; only `true` and `false` are valid.
15
16  - Equality & enums:
17      detail: >
18        Equality (incl. `enum`) compares the parsed boolean value; canonical JSON
19        atoms are lower-case `true` / `false`.

1name: Dictionary
2description: >
3  Object map from keys to values (a plain Blue object node).
4
5  - Object shape (no properties field):
6      detail: >
7        Blue objects are plain maps of field → node; there is no `properties`
8        key in the language (§2, §8.2.4). Dictionary is just an object with
9        typing constraints for its keys/values.
10
11  - Why not `value`/`items`:
12      detail: >
13        Dictionary is neither a scalar nor a list wrapper; `value`/`items` are
14        instance wrappers for scalars/lists (§2.1). They do not apply to maps.
15
16  - Key typing & serialization:
17      detail: >
18        Keys are serialized using the `keyType`'s canonical textual form. Because
19        JSON member names are strings, non-Text keys are converted to strings
20        (e.g., Integer 42 → "42", Double 1.0 → "1"). Distinct values that map to
21        the same canonical string will collide; authors SHOULD choose a `keyType`
22        that avoids ambiguity for their domain.
23
24  - Defaults & compatibility:
25      detail: >
26        `keyType` and `valueType` are OPTIONAL. If `keyType` is omitted, it
27        defaults to Text. If `valueType` is omitted, values may be any Blue node.
28        Subtyping/compatibility must be preserved for both keyType and valueType
29        when present (§4.2).
30
31  - Ordering & equality:
32      detail: >
33        Key order is irrelevant for identity (RFC 8785 canonicalization).
34        Equality compares by canonical JSON / BlueId rules.
35
36  - Applicable schema:
37      detail: >
38        §5.3 object constraints: minFields, maxFields.
39keyType:
40  description: >
41    OPTIONAL. Type for keys. Allowed: Text, Integer, Double, Boolean.
42    Defaults to Text when omitted. Keys serialize via the keyType's canonical
43    textual form.
44valueType:
45  description: >
46    OPTIONAL. Type constraint for values. If omitted, values are unconstrained
47    (any Blue node). If present, each value MUST be equal to or a subtype of
48    valueType (§4.2).

§A.2 Collection Types

1name: List
2description: >
3  Ordered collection (array) of elements.
4
5  - Authoring & wrappers:
6      detail: >
7        Surface array (x: [a, b]) and wrapped form (x: { items: [a, b] }) are
8        equivalent for authoring; canonical hashing uses the wrapped form
9        (§8.2.2). The type itself does NOT declare `items`: `items` is the
10        instance payload container. Declaring it on the type would install a
11        concrete element array on the type object (a fixed invariant, §4.1) and
12        conflate constraints with payload.
13
14  - Order, multiplicity, identity:
15      detail: >
16        Order and multiplicity are preserved. List hashing is a domain-separated
17        streaming fold over element BlueIds (§8.4). [A] ≠ A; [[] , A] ≠ [A].
18
19  - Control item forms (reserved):
20      detail: >
21        Recognized only at the top level of items when the node's type is List:
22        $previous (append anchor), $pos (positional overlay), and $empty (content
23        placeholder). $pos is consumed before hashing; $previous is an optimization
24        seed only; $empty is content (§12.2–§12.6).
25
26  - Present-empty vs absent & null cleaning:
27      detail: >
28        Present empty list [] is preserved and hashes differently from null or
29        absent. Nulls inside items are removed during cleaning (§8.2.1, §8.2.2).
30
31  - Uniqueness:
32      detail: >
33        uniqueItems compares by element BlueId (§5.2), not by textual rendering.
34
35  - Merge policy:
36      detail: >
37        If `mergePolicy` is omitted, assume "positional" (§12.3). "append-only"
38        forbids changes to the inherited prefix (no $pos); "positional" allows
39        $pos overlays within the inherited prefix. Refinements must remain type-
40        compatible with inherited elements (§4.2, §12.5).
41
42  - Applicable schema:
43      detail: >
44        §5.2 list constraints: minItems, maxItems, uniqueItems.
45itemType:
46  description: >
47    OPTIONAL. Type applied to each element. If omitted, elements are not
48    constrained by itemType (still subject to overlays and type chain). Subtype
49    compatibility MUST be preserved across refinements (§4.2, §12.5).
50mergePolicy:
51  type: Text
52  description: >
53    OPTIONAL. Authoring/merge policy. If omitted, processors MUST assume
54    "positional" (§12.3). Allowed values: "append-only", "positional".
55  schema:
56    enum: [append-only, positional]

Appendix B — Contract & Processor Type Catalog

§B.1 Base Types

1name: Contract
2description: >
3  Core type of Blue Language v1.0.
4  Base for all contracts (channels, handlers, markers). Contracts live under a
5  scope’s `contracts` map (keyed by Text). At runtime (Part II), contract
6  processors execute deterministically and only through explicit operations;
7  there are no implicit side effects.
8order:
9  type: Integer
10  description: Deterministic sort key within a scope; missing ≡ 0.
11

1name: Json Patch Entry
2description: >
3  Core type of Blue Language v1.0.
4  Deterministic subset of RFC 6902 used by handlers to request document changes
5  (Part II §21.2). NOTE: field is named `val` (not `value`) because `value`
6  has special meaning as Blue’s scalar wrapper in Part I; using `val` prevents
7  shape collisions with wrapper equivalence.
8op:
9  type: Text
10  schema:
11    required: true
12    enum: [add, replace, remove]
13path:
14  type: Text
15  description: >
16    Absolute JSON Pointer within the document (must begin with "/").
17    Runtime forbids targeting "/" (root) as a patch destination (Part II §21.2).
18  schema:
19    required: true
20val:
21  description: >
22    Payload for `add` and `replace` (any Blue node). Omitted for `remove`.
23

§B.2 Contract Subtypes (abstract)

1name: Channel
2type: Contract
3description: >
4  Core type of Blue Language v1.0.
5  Abstract base for event entry points within a scope. Channels decide whether
6  an incoming event matches at this scope (Part II). External channels may also
7  use the scope’s checkpoint to gate duplicates/stale events.
8event:
9  description: >
10    Optional matcher payload used by the channel's processor to
11    further restrict which incoming events it accepts at this scope.
12

1name: Handler
2type: Contract
3description: >
4  Core type of Blue Language v1.0.
5  Abstract base for logic bound to exactly one channel (same scope). At runtime
6  (Part II), a handler may: (1) apply patches (list of Json Patch Entry),
7  (2) emit events (Blue nodes), (3) consume gas via `consumeGas(units: Integer)`,
8  and (4) terminate (gracefully or fatally). No other effects are permitted.
9channel:
10  type: Text
11  description: >
12    The contracts-map key of the channel this handler binds to (same scope).
13  schema:
14    required: true
15event:
16  description: >
17    Optional matcher payload used by the handler’s processor to further restrict
18    which channelized events it will handle. IMPORTANT: the matching strategy
19    (shape checks, field tests, etc.) is defined by the specific handler
20    processor, not by this base schema.
21

1name: Marker
2type: Contract
3description: >
4  Core type of Blue Language v1.0.
5  Abstract base for informational/policy contracts. Markers do not run logic;
6  they carry state/policy enforced by the processor (Part II).
7

§B.3 Required Markers

1name: Process Embedded
2type: Marker
3description: >
4  Core type of Blue Language v1.0.
5  Declares embedded child scopes beneath the current scope (Part II §16).
6  The processor reads this list dynamically and re-reads after each child finishes.
7paths:
8  type: List
9  itemType:
10    type: Text
11  description: >
12    Scope-relative absolute pointers to child roots (strings beginning with "/",
13    resolved against the current scope).
14  schema:
15    required: true
16    uniqueItems: true
17

1name: Processing Initialized Marker
2type: Marker
3description: >
4  Core type of Blue Language v1.0.
5  Recorded exactly once at a scope on first processing; stores the pre-init
6  BlueId of the scope’s subtree (Part II §20). Writing this marker is a patch
7  that triggers a Document Update cascade.
8documentId:
9  type: BlueId
10  schema:
11    required: true
12

1name: Processing Terminated Marker
2type: Marker
3description: >
4  Core type of Blue Language v1.0.
5  Final state for a scope (either graceful or fatal). Once present, the scope
6  becomes permanently inactive both for the remainder of the current run and in
7  subsequent runs until explicitly replaced by a parent. Written as a Direct
8  Write (no Document Update) when termination occurs (Part II §22).
9cause:
10  type: Text
11  schema:
12    required: true
13    enum: [fatal, graceful]
14reason:
15  type: Text
16  description: Optional human-readable explanation.
17

1name: Channel Event Checkpoint
2type: Marker
3description: >
4  Core type of Blue Language v1.0.
5  Stores last-seen events per external channel at this scope to enable
6  idempotent processing and ordering (Part II §23). Updates are Direct Writes
7  (no Document Update).
8lastEvents:
9  name: Last Events
10  description: >
11    Map of channelKey (the contracts key of an external channel in this scope)
12    to the entire last event node seen for that channel. Values are unconstrained
13    (any Blue node) to allow channel-specific shapes.
14  type: Dictionary
15  keyType:
16    type: Text
17  # valueType intentionally omitted → any Blue node
18  schema:
19    required: true
20

§B.4 Processor‑Fed Channels

1name: Document Update Channel
2type: Channel
3description: >
4  Core type of Blue Language v1.0.
5  Fires on successful patches with immediate bottom-up cascade
6  (origin → ancestors → root). Matching uses subtree semantics against
7  ABS(scope, path). Payload is the processor-emitted 'Document Update' event
8  with scope-relative path (Part II §17, §21.1).
9path:
10  type: Text
11  description: >
12    Scope-relative absolute pointer (begins with "/") defining the watched
13    subtree. Match iff the absolute changed path equals or is a descendant
14    of ABS(scope, path).
15  schema:
16    required: true
17

1name: Triggered Event Channel
2type: Channel
3description: >
4  Core type of Blue Language v1.0.
5  Delivers events previously enqueued by handlers into the scope’s FIFO.
6  One drain per scope at the end of scope processing; never drains during
7  cascades (Part II §17, §19).
8

1name: Lifecycle Event Channel
2type: Channel
3description: >
4  Core type of Blue Language v1.0.
5  Delivers processor lifecycle notifications at this scope, e.g.,
6  'Document Processing Initiated' and 'Document Processing Terminated'
7  (Part II §17, §20, §22).
8

1name: Embedded Node Channel
2type: Channel
3description: >
4  Core type of Blue Language v1.0.
5  Bridges a child scope’s emissions (including lifecycle nodes) into the parent
6  after the child finishes (Part II §17, §19).
7childPath:
8  type: Text
9  description: >
10    Scope-relative absolute pointer to the child root to bridge.
11  schema:
12    required: true
13

§B.5 Processor‑Emitted Events

1name: Document Update
2description: >
3  Core type of Blue Language v1.0.
4  Emitted once per participating scope for each successful patch
5  (bottom-up delivery). 'op' uses lower-case enum; 'path' is scope-relative
6  for the receiving scope. 'before' and 'after' are snapshots (immutable views)
7  (Part II §21.1).
8op:
9  type: Text
10  schema:
11    required: true
12    enum: [add, replace, remove]
13path:
14  type: Text
15  description: >
16    Scope-relative pointer. "/" when the receiving scope’s root was affected.
17  schema:
18    required: true
19before:
20  description: Snapshot before the patch at this path (may be null).
21after:
22  description: Snapshot after the patch at this path (may be null; often null for remove).
23

1name: Document Processing Initiated
2description: >
3  Core type of Blue Language v1.0.
4  Published once at a scope on first processing (before writing the
5  Processing Initialized Marker). At root, it is also included in the run’s
6  'triggered_events' outbox (Part II §20).
7documentId:
8  type: BlueId
9  schema:
10    required: true
11

1name: Document Processing Terminated
2description: >
3  Core type of Blue Language v1.0.
4  Published at the terminating scope when processing ends, either gracefully
5  or fatally. Bridgeable to the parent via Embedded Node Channel if configured
6  (Part II §22).
7cause:
8  type: Text
9  schema:
10    required: true
11    enum: [fatal, graceful]
12reason:
13  type: Text
14  description: Optional explanation.
15