2.1 Conformance scopes

This specification separates the following conformance scopes:

• Wire-format conformance covers the byte-level CBOR Sequence structure, deterministic CBOR encoding, header and frame grammar, content-id preimages, and segment boundaries.
• Reader conformance covers parsing, chain verification, payload resolution, fold behavior, diagnostics, opaque-node handling, and resource-bound behavior.
• Writer conformance covers deterministic output, valid headers and frames, correct content identifiers, codec declarations, and signature/hash preimages.
• Tool conformance covers command-line or library policy that is stricter than local file validity, such as validating composition, extraction, publication, or archive operations.
• Profile conformance covers profile-specific vocabulary, validation, capability, and trust rules layered above the core format.
• Deployment conformance covers serving and distribution behavior such as media type, caching, range requests, and byte-preservation across HTTP or artifact hosting.

The conformance classes below define reader and writer behavior. Tool, profile, and deployment requirements are scoped explicitly in the sections that define them.

Baseline reader/writer conformance is independent of profile validation, CLI verbs, transform targets, and HTTP deployment behavior. A locally valid GTS file remains locally valid when it declares an unsupported profile; a reader records the profile declaration and folds the bytes according to its reader class, while a profile-aware tool MAY apply additional checks in the profile conformance scope.

Profiles, tools, and deployments MUST NOT change header or frame grammar, segment-boundary detection, content-id or signature/hash preimages, transform-catalog resolution, or the core fold semantics in §7. A stricter profile MAY reject an otherwise valid artifact only as a profile-level validation failure, not by redefining core GTS validity.

2.2 Reader and writer conformance classes

• A Baseline Reader MUST: parse the CBOR sequence; verify the id/prev chain (§9.1); fold terms, quads, reifies, annot, blob, suppress, meta, and snapshot frames; support the identity, gzip, and zstd codecs; and surface any frame it cannot decode as an opaque node (§7.6). It MAY ignore signatures and encryption.
• A Streaming Reader is a Baseline Reader that processes frames one at a time and emits to a sink without materialising the whole graph: it maintains only the term dictionary (and a running chain check), plus the maximum decoded frame size and validation sidecar state, giving O(distinct terms + maximum decoded frame size + validation sidecar state) retained memory rather than O(triples + blobs) (§7.7). The gts → duckdb/sqlite transforms (§14) are Streaming Reader-shaped when implemented through a non-materializing sink.
• A Full Reader additionally verifies COSE signatures, decrypts COSE-encrypted frames for which it holds keys, MAY recurse into nested GTS blobs (§12.1), and MAY use the optional index frame (§6.2) for parallel verification and random access.
• A Writer MUST emit deterministic CBOR (§4) for any bytes that are hashed or signed, and MUST compute each frame’s "id" self-hash and set "prev" to the previous item’s "id".

2.3 Baseline reader API shape

A Baseline Reader SHOULD expose at least:

open(bytes|path)            -> Graph          # parse + verify chain + fold
Graph.quads()               -> iterator[(s,p,o,g)]   # term ids resolved to terms
Graph.term(id)              -> Term
Graph.annotations(reifier)  -> iterator[(prop, value)]
Graph.blob(digest)          -> bytes | OpaqueRef
Graph.opaque()              -> iterator[OpaqueNode]
Graph.to_nquads(out)        # §14

This API shape is intentionally small: it exposes the folded tables, diagnostics, and common projection path without requiring an RDF text parser, prefix resolver, query engine, or reasoner. The cross-language API and CLI parity contract is maintained in GTS-API-CLI-PARITY.md.

2.4 Reader diagnostics

Readers surface machine-observable diagnostics with these canonical classes (an implementation MAY map them to error returns or structured warnings):

3.1 Multi-segment files (cat-append composition)

A GTS file is one or more segments, each a complete, self-contained header *frame log. The defining property: byte-concatenation of valid GTS files is a valid GTS file —

cat music.gts >> core.gts        # core.gts is now a valid two-segment GTS

• Boundary detection (normative). A reader that has consumed at least one frame and encounters a data item that is a map containing the key "gts" and lacking the key "t" MUST treat it as the Header of a new segment (the optional self-describe tag 55799 MAY tag that header; writers SHOULD emit the tag on every segment header to make boundaries human-recognizable). The tag is attached to the segment header, so byte-concatenation of independently valid tagged segments remains byte-concatenation of CBOR Sequence items, not a nested whole-file wrapper. Any other non-frame item remains malformed input (§17).
• Independent integrity. Each segment has its own genesis (its header "id"), its own id/prev chain, its own signatures, and its own optional index (an index covers ONLY its segment). The file’s composite identity is the ordered list of segment head ids. A third-party segment carries its own signer; concatenation rewrites nothing (a cat cannot rewrite an earlier segment’s header without breaking its self-hash — by design).
• Identity across segments. Term-ids are segment-scoped (§7.2); the ONLY cross-segment identity is the term value (IRI, literal, quoted-triple structure). Blank-node labels are segment-local and MUST NOT be merged across segments (the §12.1 nested-GTS rule, applied at the top level).
• Profiles union. The file’s effective profile/requirement set is the union of the segment headers’ "prof" values (and any profile requirements carried in segment metadata). A reader lacking the capabilities a segment requires degrades that segment’s frames to opaque nodes (§7.6) — “this data needs the gmeow-music profile” is a header read, not an error.
• Relationship to nesting. Nested GTS (§12.1) composes by containment (a sealed, independently-shippable subgraph); segments compose by concatenation (open, tool-free aggregation). Both yield a union fold; choose nesting when the part must travel or seal independently, segments when plain cat must work.

3.2 Streaming and progressive enhancement

The append-only log makes streaming a property of the format, not a feature of a tool. Three facts compose, and conformant implementations MUST preserve all three:

• Prefix-fold validity (normative). Every byte prefix of a valid GTS file that ends on a data-item boundary is itself a valid GTS file, and a reader MUST fold it to exactly the state it would reach folding those same items inside the complete file. A live stream in flight is therefore indistinguishable from a file with a torn append (§3): the partial trailing item means “not yet arrived”, and a consumer MAY keep reading as bytes land (tail -f semantics) — every intermediate fold is a real, usable graph state, never a half-parsed error state.
• Monotone refinement. Appended frames only ever add knowledge: quads accumulate (§7.8 set semantics), a reifier binding is first-wins so an established rendering never changes under it, and suppression is an additive display overlay (§11) — arrival of a suppress frame refines presentation without invalidating any prior fold. The chain check is likewise incremental: O(1) state (the expected "prev") verifies each frame as it arrives.
• Chunk-safe framing. CBOR Sequence items are self-delimiting, so item boundaries are safe re-chunking points for relays and proxies, and resumption is content-addressed: a receiver that states the last frame "id" it verified can be resumed from the next byte with no negotiation beyond that hash.

Progressive enhancement. Producers SHOULD order content most-significant-first so an early prefix is maximally useful: within a segment, terms/quads (the graph) before bulky blob frames, and small or preview manifestations before large ones; across a file, segments ARE the enhancement layers — a base segment (core graph + thumbnails) followed by enhancement segments (full-resolution blobs, computed projections) gives a receiver a complete, verifiable package at every segment boundary, §3.1’s composition rules applied as a delivery schedule. Checkpoint index frames (§6.2) emitted periodically give a streaming consumer intermediate truncation anchors ("head"), random-access offsets for ranged re-fetch, and a manifest of what has arrived; the index remains an accelerator, never a dependency (§3, §6.2).

The manifest is the graph. GTS needs no table-of-contents structure, because the frames that describe content can precede the frames that carry it: a producer SHOULD emit the quads naming each upcoming manifestation — its content digest, media type, size, role — before the blob frames whose bytes they promise. The fold of an early prefix then contains the delivery schedule as ordinary knowledge: every digest the graph names but the stream has not yet delivered is a content-addressed IOU, so “stop here”, “skip ahead” and “range-fetch only the RAW file” are informed consumer decisions, taken against a verifiable catalog rather than a guess. (A blob that never arrives in this file is simply an external blob, §12 — the reference degrades gracefully to “bytes live elsewhere”.)

Worked delivery schedule — a photograph as a progressive stream; a consumer may stop at any item boundary with a complete, verified package of everything above its stopping point:

header                          profile, codec catalog
terms/quads                     the catalog: Work + every manifestation below,
                                each with digest, mt, size, role (the IOUs)
blob  image/webp        ~20 KB  thumbnail — first paint
blob  image/jxl         ~8 MB   full-resolution render
terms/quads                     scene description (what is IN the image)
blob  image/x-raw       ~80 MB  RAW sensor dump
meta/quads                      full camera metadata
terms/quads/annot               AI analysis as RDF, statement-level provenance
terms/quads/annot               opinions — standpoint-qualified claims
terms/quads                     processing-pipeline provenance
index                           footer: offsets, head anchor, MMR (§6.2)

A casual viewer stops after the thumbnail; an archivist takes everything; an editor range-fetches the RAW by digest after reading only the catalog. Same bytes, same chain, three consumers.

A reader streams items until end of input. Trailing partial bytes (a torn append) MUST be detected and ignored with a diagnostic: a reader attempts to decode each successive CBOR item, and if the decoder signals an incomplete item or unexpected EOF at end-of-file, it MUST treat the trailing bytes as a torn append, ignore that incomplete item, and surface a machine-observable diagnostic (e.g. a TornAppendError warning). In particular, if a crash occurred while writing an index frame (§6.2) the trailing index is torn: a reader MUST ignore it and fall back to an earlier intact index or to a plain sequential scan, so every surviving frame remains recoverable. The optional index is an accelerator, never a dependency.

Every property above holds for any frame order; what a producer chooses as the order is a separate, named concern: a segment is in one of two layout states — accretive (append-ordered) or streamable (delivery-ordered) — defined next (§3.3).

3.3 Layout states: accretive and streamable

A GTS segment is always valid and always prefix-foldable (§3.2), but it lives in one of two layout states:

• Accretive — append-optimized. Frames land in arrival order (live capture, agent memory accrual, evidence accrual). Writes are cheap forever and the stream is consumable as it lands, but significance is not front-loaded and the catalog may trail the bytes it describes. This is the default state; it is never declared.
• Streamable — delivery-ordered. The catalog presages the payload: a leading streaming index (ordinary terms/quads frames in the stream vocabulary, §13.3 — one stream:Manifestation per promised blob, carrying digest, media type, size, role, and intended order) precedes every blob frame, blobs follow most-significant-first, and a trailing offset index (§6.2) closes the covered region as the random-access footer.

Append-friendly and stream-optimal are different layouts of the same content (precedent: mp4 faststart, zip central-directory rewrites, LSM compaction). A one-pass writer cannot produce the second state, so conversion is an explicit rewrite — streamable compaction (§10.1), exposed as gts compact --streamable (§14.1).

The claim (normative). A segment declares the streamable state with the optional header key "layout": "streamable" (§5). The claim is per-segment (each segment has its own header, §3.1) and tamper-evident (the header self-hash covers it). Streamability is a declared-vs-computed claim in the sense of §14.1 — refuse-don’t-trust:

• The covered region of a claimed segment is the prefix delimited by the segment’s last intact index frame: "count" frames, ending at the frame whose "id" equals the index’s "head". The footer MUST immediately follow the frames it covers ("count" = the index’s own frame position − 1) — otherwise frames could sit between the covered prefix and the footer, counted neither as covered nor as accretive tail. A claimed segment with no intact index frame, whose last index is not immediately adjacent to its covered prefix, or whose "head" does not equal the id of frame "count", is in violation.
• Within the covered region, every inline blob frame MUST be preceded by a quads frame that describes its digest via stream:digest (§13.3) — catalog-before-payload. A covered blob delivered before its description is in violation.
• A reader encountering a violation MUST surface a StreamableLayoutError diagnostic (§2.3); a verifying tool treats it as an error (§14.1). The claim can never rot against the bytes.

Appends after compaction are legal and foldable. Frames after the last index are simply unpresaged: they are the segment’s accretive tail, carry no ordering obligation, and trigger no diagnostic. The segment is then “streamable through frame N, accretive after” — tooling SHOULD report the boundary (§14.1). Re-compact to re-streamline. Likewise, a segment appended by cat makes no claim unless its own header claims.

In-flight prefixes. A prefix of a streamable segment cut before the trailing index has, by construction, a claim and no footer yet; a streaming consumer MUST NOT treat the missing footer as a lie while input may still be arriving — the missing-footer violation applies to a complete file. The catalog-before-payload rule, by contrast, is prefix-stable: a violation observed in any prefix is a violation of the whole file.

6.1 Payload resolution

To obtain a frame’s logical payload:

1. If "x" is absent, the payload is "d" directly (structured CBOR) — equivalent to a single identity transform; a chain resolving to only identity likewise leaves "d" unchanged.
2. If "x" is present, "d" MUST be a byte string and every codec-id MUST resolve through the header "cat"; apply the reverse of each codec, last to first. Each step requires a capability (§8.3). On any missing capability (unknown codec or missing key), stop and treat the frame as opaque (§7.6).
3. The fully-decoded bytes are a CBOR item; decode them to the type-specific structure (§7).

6.2 Index frame (optional)

A writer MAY append an index frame — a footer that accelerates large files without raising the simple-reader floor (a Baseline Reader ignores it). Because the log is append-only, a fresh index MAY be appended after more frames; the last index wins.

index-payload = {
  "count"  : uint,                        ; frames covered
  "head"   : content-id,                  ; "id" of the last covered frame (truncation anchor)
  ? "off"  : [+ uint],                    ; byte offset of each frame (random access; parallel verify)
  ? "ti"   : { * frame-type => [+ uint] },; frame indices by type
  ? "dict" : [+ uint],                    ; indices of "terms" frames (dictionary locator; §7.7)
  ? "mmr"  : content-id,                  ; Merkle-Mountain-Range root over frame ids (§9.1)
}

Given "off", a Full Reader dispatches frame-hash verification across threads and seeks to any frame; given "dict", a Streaming Reader loads only the dictionary (§7.7); given "head"/ "mmr", it detects truncation and produces O(log n) inclusion proofs. A checkpoint index is simply an index emitted periodically rather than only as a footer; an earlier index MAY still serve as a recovery anchor even though the last intact index is preferred for acceleration. Current package support and deferrals for off/ti, dict, mmr, proof verbs, range fetch, and replication workflows are tracked in GTS-ADVANCED-PRIMITIVES.md.

The mmr root uses a Merkle-Mountain-Range over the ordered frame ids covered by the index. The index frame itself is not covered by its own mmr; a later index may cover an earlier index frame like any other earlier frame. Peaks are built left-to-right by appending one leaf per frame id and repeatedly merging the two rightmost peaks while their heights match. The root for count = 0 is the root preimage with an empty peak list.

All MMR preimages use deterministic CBOR (§4) and BLAKE3-256:

leaf(index, frame_id) =
  BLAKE3-256(deterministic-CBOR(["gts-mmr-leaf-v1", index, frame_id]))

parent(parent_height, left_hash, right_hash) =
  BLAKE3-256(deterministic-CBOR(["gts-mmr-parent-v1",
                                 parent_height, left_hash, right_hash]))

root(count, peaks) =
  BLAKE3-256(deterministic-CBOR(["gts-mmr-root-v1",
                                 count,
                                 [[peak_height, peak_hash], ...]]))

A detached proof JSON object has this stable shape:

{
  "schema": "gts-mmr-proof-v1",
  "hash": "blake3-256",
  "preimage": "gts-mmr-v1",
  "count": 4,
  "leaf_index": 2,
  "frame_id": "<32-byte frame id hex>",
  "root": "<32-byte mmr root hex>",
  "peak_index": 0,
  "peaks": [{"height": 2, "hash": "<32-byte peak hex>"}],
  "path": [
    {"side": "right", "parent_height": 1, "hash": "<32-byte sibling hex>"}
  ]
}

verify-proof MUST reject a proof unless the peak heights match count, leaf_index belongs to peak_index, every hash field is 32 bytes, the path reconstructs the selected peak, and the peaks reconstruct root. Proof verification does not require the original .gts file.

7.1 Terms (terms frame)

Payload: an ordered array of terms. Ids are assigned by append order within the current segment dictionary (or within a snapshot dictionary before it is shifted into the enclosing segment).

terms-payload = [+ term]
term = {
  "k"   : 0 / 1 / 2 / 3,   ; 0=IRI 1=literal 2=bnode 3=quoted-triple
  ? "v" : tstr,            ; IRI string | literal lexical form | bnode label
  ? "dt": term-id,         ; literal datatype IRI (a term)
  ? "l" : tstr,            ; literal language tag (BCP 47)
  ? "rf": term-id,         ; quoted-triple: the reifier (§7.3) whose triple this term denotes
}

Literal datatype defaulting (normative). For a k:1 (literal) term: if "l" (language tag) is present and "dt" is absent, the datatype is rdf:langString; if both "l" and "dt" are absent, the datatype is xsd:string.

Blank-node labels (normative). A k:2 (blank node) term’s non-empty "v" label is local to the current blank-node scope: the segment for ordinary frames, the snapshot dictionary for a snapshot, or the nested GTS file for recursive composition (§12.1). It MUST NOT be treated as a globally stable identifier and MUST NOT be merged with the same label in another segment or nested GTS. If "v" is absent or the empty string, the term is anonymous and denotes a fresh blank node for that term entry within the scope. Transforms MAY relabel blank nodes while preserving blank-node isomorphism and scope separation.

7.2 Term-id assignment (normative)

Term ids are unsigned integers assigned in append order, per segment, starting at 0 at each segment’s header, and are frozen within their segment: a term minted while folding frame N keeps its id for the rest of that segment. A quads, annot, or reifies frame at position N MUST only reference term-ids introduced at positions 0..N-1 of the same segment (such frames introduce no terms of their own). This makes writing pure-append, reading single-pass, and concatenation sound: term-ids are compression artifacts, never identity — cross-segment identity is the term value only (§3.1), exactly as a snapshot’s dictionary already restarts at 0 (§10). An implementation that applied file-global ids to a multi-segment file would misfold silently; the boundary rule (§3.1) and vector 17 (§19) exist to make that failure loud instead.

7.3 Quoted triples and reifiers (reifies frame)

RDF 1.2 lets a triple be the subject or object of another. GTS keeps quoted triples in the id domain: a reifier is an ordinary IRI/bnode term; a reifies frame binds it to the triple it quotes.

reifies-payload = { * term-id => [term-id, term-id, term-id] }  ; reifier => (s, p, o)

A quoted triple used as a node is a term with "k": 3 and "rf" pointing at its reifier.

RDF dataset mapping (normative). A folded GTS graph maps to an RDF 1.2 dataset as follows: each quads row (S,P,O,G?) asserts the RDF triple (S,P,O) in the default graph when G is absent, or in the named graph G when G is present. A reifies binding R => (S,P,O) asserts the triple R rdf:reifies <<( S P O )>> in the default graph. A k:3 term denotes that triple term, reached through its reifier R. Each annot row (R, P', V') asserts the triple R P' V' in the default graph. Profiles MAY define additional graph-placement conventions for projection, but the core mapping above is the interoperable baseline.

Quotation does not imply assertion (normative). Referencing a triple term, either via a reifier or a k:3 term, does NOT assert the base triple (S P O). The base triple is asserted iff it also appears in a quads frame.

RDF 1.1 degradation (informative). RDF 1.1 has no quoted triple term. A lossy RDF 1.1 projection MAY replace a quoted triple term with its reifier resource and emit ordinary reification-style triples such as R rdf:subject S, R rdf:predicate P, and R rdf:object O, or carry R rdf:reifies as an extension predicate understood by the consumer. Such a projection MUST NOT assert (S P O) merely because the GTS file quoted it, and tooling SHOULD label the projection as lossy whenever a triple term was present.

7.4 Quads and annotations

quads-payload = [+ [term-id, term-id, term-id, ? term-id]]  ; s, p, o, (g; default graph if absent)
annot-payload = [+ [term-id, term-id, term-id]]             ; reifier, predicate, value

Statement-level metadata (confidence, validity interval, standpoint/vantage, modality, …) is expressed as annot rows on a reifier. Contested claims coexist: several annot rows on one reifier, or several reifiers over one (s,p,o), are all retained — none is privileged. Annotations are an ordered multiset in the folded GTS state: readers MUST preserve row order within each segment and concatenate segment annotation rows in file order. Exact duplicate annotation rows are retained in the GTS fold; an RDF dataset projection MAY collapse identical emitted RDF triples because RDF datasets are set-valued.

Position constraints (normative). In a quads row the predicate p MUST be an IRI (k:0); the subject s MUST be an IRI, blank node, or quoted triple (k:0|2|3); the object o MAY be any term; and the graph name g, when present, MUST be an IRI or blank node (k:0|2) — never a literal or quoted triple. A reifies triple (S,P,O) obeys the same subject/predicate/object constraints. In an annot row the predicate MUST be an IRI.

7.5 Fold algorithm (normative)

result := empty file state
          (terms, quads, reifiers, annotations, blobs, blob_meta, meta,
           suppressions, opaque, signatures, diagnostics, segment ledger)
for segment in file order:                      # §3.1; single-segment files: one iteration
  verify each frame's id (self-hash) and prev-link within the segment;
  record sig status if "sig" present
  terms := []   graph := {}   reif := {}   annot := []
  blobs := {}   blob_meta := {}   meta := {}   suppressed := []   opaque := []
  diagnostics := []
  for frame in segment log order:
    P := resolve payload (§6.1); if undecodable -> add opaque node (§7.6); continue
    switch frame.t:
      "terms"    : append each term (assign next id); each "dt"/"rf" MUST name an
                   already-introduced term-id (no forward references)
      "quads"    : add each (s,p,o,g) value tuple to graph
      "reifies"  : bind reifier to (s,p,o), keeping the first non-conflicting binding (§7.8)
      "annot"    : append (reifier, predicate, value)
      "blob"     : if "d" present -> blobs[BLAKE3(decoded "d")] := bytes (inline);
                   else -> register external blob by "pub".digest;
                   shallow-merge "pub" into blob_meta[digest]
      "suppress" : append directive to `suppressed` (display contract; §11)
      "snapshot" : load a self-contained fold wholesale (§10)
      "meta"     : shallow-merge map into segment meta (later keys overwrite earlier)
      "opaque"   : add explicit opaque node
  union segment fold into result BY TERM VALUE     # ids resolve locally, never cross segments;
                                                   # bnodes keep their scope (§3.1, §12.1)
result

The fold is deterministic: the same intact log yields the same value state in every conformant reader. Within a segment, meta accumulates as a shallow union over one map — a later frame’s keys replace earlier ones; values are not concatenated. Across segments, each segment’s folded meta is exposed per segment (keyed by segment head id) AND shallow-merged in file order into a file-level view — a later segment’s keys win, but the per-segment originals remain addressable (a third-party segment’s metadata is never silently absorbed).

7.6 Opaque nodes

When a frame’s payload cannot be decoded — an unknown codec, or a cose-encrypt codec for which the reader holds no key — the reader MUST NOT drop it. It MUST add an opaque node to the graph carrying everything still in cleartext:

opaque-node = {
  "id"      : content-id,      ; the frame's self-hash
  "type"    : frame-type,      ; declared "t"
  ? "pub"   : any,             ; the cleartext public envelope, if any
  ? "to"    : [+ recipient],   ; declared recipients
  "sigstat" : "none" / "valid" / "invalid" / "unverified",
  "reason"  : "unknown-codec" / "missing-key" / "damaged",
}

Most opaque nodes are produced by a reader at decode time; a writer MAY also emit an explicit opaque frame (e.g. a redaction placeholder) whose payload is the structure above, in which case "sigstat" is omitted (a reader determines it). A damaged frame (failed self-hash, or absent) is isolated and folded as an opaque node too (§9.1): a reader MAY surface its cleartext fields as untrusted diagnostic metadata, but MUST set "sigstat" to invalid/unverified and "reason": "damaged" — the bytes are not trustworthy. The frame still participates in the id/prev chain, so it cannot be silently stripped.

7.7 Streaming fold and bounded memory

A graph need not be materialised to be transformed. A Streaming Reader (§2.1) processes frames in order and emits to a sink, holding only the term dictionary, the current decoded frame or blob, and the running id/prev and validation state:

• gts → duckdb/sqlite (§14) keep the integer-id model: stream terms deltas into a terms table and quads/reifies/annot deltas into id-valued tables, bulk-inserting as frames arrive. No term resolution and no graph materialisation occur — memory is bounded by the dictionary, the largest decoded frame, and validation sidecar state rather than by triples or blobs. The relational join that resolves ids is the engine’s job, later.
• gts → ttl/nq must resolve ids to emit text. If the dictionary exceeds memory, the reader uses the index "dict" locator (§6.2) to load (or memory-map, or spill to an on-disk kv) only the terms frames first, then streams the quads.

Even O(distinct terms + maximum decoded frame size + validation sidecar state) can exceed memory for pathologically irregular graphs (e.g. a crawl dumping millions of unique UUID IRIs, or a single very large inline blob). A Streaming Reader therefore MAY flush its in-memory dictionary to a temporary on-disk key-value store when a memory limit is reached, trading RAM for a local spill file; correctness is unaffected because term-ids are append-order and frozen (§7.2). The gts → duckdb/sqlite transforms get this for free — the target table is the spill.

The package-level streaming-sink claim boundary and memory benchmark helper are maintained in GTS-ADVANCED-PRIMITIVES.md.

A multi-gigabyte log thus transforms to an operating substrate in bounded memory — the resolve-and-materialise OOM failure mode is avoided by construction.

7.8 Duplicates and conflicts (normative)

All duplicate and conflict behavior is defined here so frame handlers do not invent local policy:

8.1 Classes

Every catalog entry declares a class:

8.2 Stacking

"x" is applied in array order on encode and reversed on decode. Example: [zstd, cose-encrypt] means compress, then encrypt; a reader decrypts (if keyed) then decompresses.

8.3 Capability model and graceful degradation

Decoding a chain requires every capability it names. A missing capability is uniform whether it is a library (unknown-codec) or a key (missing-key): the frame becomes an opaque node (§7.6). This single mechanism yields in-file content negotiation — a logical object MAY appear as several frames in different codecs/formats (e.g. a high-fidelity representation a reader can’t decode and a widely-supported fallback it can), and the reader uses the best frame for which it holds the capabilities.

8.4 Mandatory core set and durability

A Baseline Reader MUST implement identity, gzip, and zstd — so a conformant reader’s full dependency set is CBOR + BLAKE3 + gzip + zstd. Writers targeting maximum longevity SHOULD restrict to the core set. Density-oriented writers MAY use lzma2 with an in-band dictionary. All core codecs are stable, widely deployed primitives.

Rsyncable codecs. A compress-class codec MAY be rsyncable: it periodically synchronizes (resets) its compression state so that a local change in the uncompressed input only affects a bounded neighborhood of the compressed output. This improves delta-transfer tools (e.g. rsync) and version-control delta compression (e.g. Git packfiles) at the cost of a small compression-ratio overhead. The only rsyncable codec defined in this revision is zstd-rsyncable (§8.5).

8.5 Canonical codec registry (v1)

Catalog entries are referenced by integer id within a file (§5), but each entry’s "name" MUST be a canonical identifier from this registry so writers interoperate:

A reader MUST match codecs by canonical "name", not by catalog id (ids are file-local). Later spec versions register new codecs by canonical name; an unknown name degrades to an opaque node (§8.3).

9.1 Per-frame self-hash and content-id chain (mandatory)

Each frame’s "id" is the BLAKE3-256 of its own content (every key except "id" and "sig"), so a frame is content-addressed and independently verifiable. Each frame’s "prev" names the previous frame’s "id"; because "prev" is part of the hashed content, the chain is a git-style content-addressed list in which the head id transitively commits to all history.

• Parallel verification. Every "id" is a hash of a self-contained byte range; with the index "off" table (§6.2) all frame hashes are recomputed concurrently, followed by a trivial O(n) "prev"-equality pass. No accumulating dependency forces single-threaded reading. (The only inherently sequential step is discovering frame boundaries in a bare CBOR sequence — a cheap length-scan the index removes.)
• Damage isolation and recovery. A corrupt frame fails its own "id", so damage is independently detectable. Recovery of subsequent frames, however, is guaranteed only when their byte offsets are known — from an intact index "off" table, a checkpoint frame, external framing, or the storage layer. In a bare CBOR Sequence (no per-frame length) arbitrary byte corruption can desynchronise the decoder: a reader with offsets skips the bad frame and folds the survivors (reason: "damaged"), while a reader without offsets MAY be unable to resynchronise past the damage. evidence writers SHOULD emit periodic checkpoint indexes (§13) so recovery is robust.
• Tamper-evidence. Any insertion, reordering, or mutation breaks a "prev" link or a self- hash. Truncation (dropping trailing frames) is detected only against a head commitment — a signature over the head "id", the index "head"/"mmr" root (§6.2), or an out-of-band anchor. Opaque frames are part of the chain, so confidential frames cannot be stripped undetectably.

A Merkle-Mountain-Range (MMR) root over the frame ids (optional, carried in the index) is a single whole-file commitment that is itself parallel to compute and supports O(log n) inclusion proofs — proving a frame is in the log without shipping the log.

9.2 Signatures (optional, algorithm-agile)

A frame MAY carry "sig", a COSE_Sign1 (RFC 9052) over the frame’s "id". Because "id" is the self-hash of the whole content — "pub", "d" (the ciphertext, if encrypted), and "prev" (the chain position) — one signature over "id" binds the public claims to the sealed payload and to the chain position, and signing the head "id" thereby anchors all prior history (§9.1). The signing algorithm is declared in the COSE header (e.g. EdDSA/Ed25519, ES256); readers MUST honour the declared algorithm. The evidence and opaque profiles (§13) REQUIRE signatures. Key discovery and trust anchoring (which keys are authentic, which signers are authorised) are profile/deployment policy, not core GTS: sigstat: "valid" means a signature is cryptographically valid under a resolved key, not that the key is trusted.

9.3 Encryption (optional)

An encrypt-class codec wraps the payload as COSE_Encrypt/COSE_Encrypt0. Recipients are listed in cleartext "to" by key identifier only — never the key material. Multiple recipients MAY share one sealed payload (each unwraps the content-encryption key with its own key). Key escrow, rotation, and revocation are the issuer’s responsibility and are out of scope; a payload encrypted to a retired key MAY become permanently opaque.

This draft’s v1 conformance surface implements and tests COSE_Encrypt0 for one direct recipient. Multi-recipient COSE_Encrypt envelopes and ECDH key-wrap are deferred outside v1 until dedicated vectors, key-management policy, and cross-engine interop tests exist; see GTS-SECURITY-POLICY.md.

The deferred cose-encrypt contract is pinned as a future Full Reader capability, not as a v1 implementation claim. A future implementation that claims it MUST consume a CBOR-tagged COSE_Encrypt envelope whose content encryption uses A256GCM and whose recipient array contains one entry per declared recipient in the frame’s cleartext "to" list. The initially defined key-management mode is ECDH-ES+A256KW: each recipient entry carries the information needed to derive a key-encryption key and unwrap the same 256-bit content-encryption key with A256KW. A conforming future reader tries only recipients for which it holds the corresponding private key material.

Deferred failure modes are:

• no held key matches any recipient kid: emit MissingKey and preserve the frame as an opaque node with reason:"missing-key";
• ECDH recipient metadata is malformed, the derived key-encryption key cannot unwrap the content key, or AES-KW authentication fails: emit KeyWrapFailed and preserve the frame as opaque with reason:"missing-key";
• content-authentication failure after a successful unwrap is a damaged encrypted payload and MUST NOT expose plaintext.

The descriptor vectors in vectors/crypto-deferred/*.json pin the two-recipient shape and the wrong-key, missing-key, and failed-unwrap opacity cases until byte-level COSE_Encrypt vectors replace the placeholders.

9.4 The opacity invariant (normative)

Opacity hides content — never existence, provenance, or position.

For every frame, {"id", "prev", "t", "x", "to", "pub", "sig"} MUST remain in cleartext (the transform chain "x" is cleartext so a reader knows which codecs to reverse). A reader without the relevant key therefore still learns that the frame exists, what kind it is, who it is sealed for, who signed it, and where it sits in the chain. This is what makes selective disclosure safe: a holder can carry — and a verifier can authenticate the position of — data neither can read.

10.1 Streamable compaction (ordering-only)

Streamable compaction converts an accretive segment (or multi-segment file) into one delivery-ordered segment in the streamable layout state (§3.3). Unlike snapshot compaction above, it is a re-authoring of the ORDERING, and only the ordering: the folded graph, the inline blobs, and every content-addressed fact are preserved. Three signature subjects behave differently under the rewrite, and a compactor MUST honour all three:

• Content signatures (subject = a content digest: a blob’s BLAKE3, a statement or claim hash — “this is true, signed by Bob”) are ordinary quads/annotations about digests. They are compaction-invariant and survive fully intact: nothing they attest to has changed.
• Frame signatures (a COSE_Sign1 over a frame "id", which commits to "prev", §9.2) become detached, not broken: they verify against the original frame id forever. A compactor MUST carry every source frame signature in compaction provenance — one stream:DetachedSignature node per signature, recording the original frame id (stream:sourceFrame) and the original COSE bytes (stream:cose), plus one stream:sourceHead per source segment head (§13.3) — so each remains a checkable claim about the original log.
• Ordering commitments (a signed head, an index "mmr" root) are the only layout-bound attestations. They cannot survive a reordering; the compactor re-issues the ordering commitment (the new trailing index with its "head", §6.2) and thereby becomes the sole attester of the new ordering. A compactor MAY additionally COSE-sign the new head.

A compactor MUST record the rewrite itself as provenance quads in the output — a stream:Compaction node carrying the acting tool (stream:agent), the time (stream:timestamp), and the source segment heads (stream:sourceHead) — the §10 provenance MUST, given concrete vocabulary by §13.3.

Profiles demanding pristine third-party chain attestation. For an evidence segment the original signed chain is the artifact; a compactor MUST refuse it — unless it seals the original log verbatim as a nested GTS blob (§12.1) inside the streamable rewrite (role "source", referenced from the provenance node via stream:sealedSource). The original bytes, chain, and signatures stay byte-intact and independently verifiable inside; the outer layout is delivery-ordered; one content digest binds them.

Refusals for publication tools (§14.1). A compactor MUST refuse: input that does not verify cleanly (any diagnostic); and input whose fold carries a frame-addressed suppression (kind: "frame", §11) — the rewrite assigns new frame ids, so a frame-digest target would silently dangle. Digest-addressed blob suppressions are carried forward verbatim (content-addressing is layout-independent); id-addressed suppressions are carried forward value-wise (§11).

12.1 Nested GTS (recursive composition)

A blob whose media type is application/vnd.blackcat.gts+cbor-seq is itself a complete GTS file. Because a payload after transform reversal is opaque bytes, any frame payload MAY carry a nested GTS, wrapped in any transform chain — [zstd], [cose-encrypt], or both. The normative carrier is a blob whose "pub".mt is application/vnd.blackcat.gts+cbor-seq.

• Fold semantics. A Full Reader MAY recurse: decode the blob (subject to §6.1 capability rules), then fold the inner bytes as an independent GTS, exposing its result as a subgraph the parent graph references by the blob’s digest. A Baseline Reader MAY treat a nested GTS as an ordinary blob (no recursion).
• Blank-node scope. The inner GTS has an independent blank-node scope. If a Full Reader exposes the inner fold beside the parent fold, it MUST relabel or scope inner blank nodes so labels cannot collide with the parent or with sibling nested GTS files.
• Independent integrity. The inner GTS has its own header, id/prev chain, and signatures. The outer chain proves the nested blob is present and intact at its position; the inner chain proves the nested log is intact. The two guarantees compose but do not depend on each other.
• Composed opacity. If the nested GTS is reached through an encrypt-class transform and the reader lacks the key, the entire subgraph — including its inner header — is an opaque node (§7.6): the holder can carry and prove the position of a whole sealed graph it cannot read. This is the matryoshka case (“a whole GTS inside an encrypted field”).
• Bounded recursion. Readers MUST enforce a maximum nesting depth and total decoded-size budget (§18).

This composition needs no new frame type: nesting is “a blob that happens to be a GTS.” The v1 Full Reader helper and negative security vectors for recursion limits are tracked in GTS-SECURITY-POLICY.md.

13.1 Language-tag discipline (profile-level normative)

This subsection defines a profile/projection-writer rule, not a Baseline Reader requirement.

A producer’s graph payload MAY carry internal private-use language tags (e.g. GMEOW’s x-gmeow-*): the payload of a dist or ai-package segment is the canonical form, and canonical forms keep their internal tags. Every projection section — docs blobs, derived views, down-projected representations, anything generated for an external consumer — MUST carry public BCP 47 tags only; a producer that leaks private-use tags into a projection section MUST fail at write time, not warn (vector 20). The boundary is per role, not per file: one package legitimately carries a canonical payload with internal tags beside public-tagged docs sections. (This mirrors the GMEOW generator framework’s internal-tag leak gate; the reference producer reuses its retag machinery at the section boundary.)

13.2 The files profile (optional-standard)

The files profile is an optional-standard, content-addressed archive of a file tree. It is the GTS answer to tar’s c/x/d: pack a directory into a single-segment GTS, unpack it later, and diff it against a directory without byte comparison. The rules below are profile-level conformance requirements for files writers and validators; a Baseline Reader folds the graph without implementing archive tooling.

Namespace. The profile owns a small, spec-defined vocabulary at https://w3id.org/gts/files# (prefix files). GTS independence means an unpacker MUST NOT require GMEOW, schema.org, or any other ontology to read the archive; the vocabulary is authored in the spec and carried as literal IRIs in the graph.

Quad shape. Each file in the archive is described by one blank-node FileEntry:

_:entry a files:FileEntry ;
    files:path "relative/path.txt" ;
    files:digest "blake3:<hex>" ;
    files:size 1234 ;
    files:mode 33204 ;
    files:modified "2026-06-10T20:00:00Z"^^xsd:dateTime ;
    files:mediaType "text/plain" .

Determinism. A files archive MUST be byte-reproducible for the same input tree:

• Paths are sorted lexicographically by their UTF-8 byte sequence before emission.
• Stored paths use / separators and MUST be non-empty relative paths. Writers, unpackers, and diff tools MUST refuse absolute paths, Windows drive-relative paths, .. components, . components, empty components, and backslash separators before touching file bytes.
• Modification times are normalised to UTC and serialised as xsd:dateTime with second precision. Fractional seconds MUST be truncated before emission.
• Only POSIX mode and mtime are recorded; ownership, uid/gid, xattrs, and ACLs are deliberately excluded — they are tar’s portability tarpit.
• Symlinks are deliberately excluded. pack and diff MUST refuse symlink entries rather than following them; unpack MUST also refuse any destination escape through an existing symlink below the output directory.

Inline and external blobs. A file’s bytes MAY be carried as an inline blob frame ("d" present, digest = BLAKE3(decoded "d")) or as an external blob ("d" absent, pub.digest names bytes held elsewhere, §12). Identical bytes appearing under multiple paths are stored once by convention. The standard gts pack command emits inline blobs only. Implementations MAY add an explicit external-blob mode, but it MUST be opt-in and documented. gts unpack MUST refuse an unsuppressed FileEntry whose inline blob is absent; gts diff MAY compare by files:digest without fetching external bytes.

Suppression. A blob-targeted suppression (§11) hides matching file bytes from default extraction. gts unpack and gts extract skip/refuse suppressed blobs by default and expose an explicit --include-suppressed override when the operator intentionally wants retained history.

Relationship to other vocabularies. The profile is deliberately self-contained, but the terms align by reference to common surface vocabularies: files:size ↔︎ schema.org contentSize, files:mediaType ↔︎ schema.org encodingFormat, files:modified ↔︎ NFO fileLastModified, files:path ↔︎ NFO fileName. These alignments live in GMEOW’s mapping DSL; the files profile itself does not depend on them.

13.3 The stream vocabulary (optional-standard)

The streamable layout state (§3.3) and streamable compaction (§10.1) use a small, optional-standard vocabulary at https://w3id.org/gts/stream# (prefix stream) — the same independence decision as the files profile (§13.2): no GMEOW or external ontology is required to stream a photo archive; the terms are authored here and carried as literal IRIs in the graph. The vocabulary is deliberately distinct from files# (the two compose: a files archive that is also streamable describes each file once as a files:FileEntry and once as a stream:Manifestation — the profile check (§14.1) and the layout check (§3.3) stay independent).

Streaming-index terms — one stream:Manifestation per promised blob, emitted in the leading streaming index before any blob frame (§3.3):

Compaction-provenance terms — the concrete vocabulary for §10/§10.1’s provenance MUST:

Quad shape (a compacted segment’s streaming index, then provenance):

_:m0 a stream:Manifestation ;
    stream:digest "blake3:<hex>" ;
    stream:mediaType "image/webp" ;
    stream:size 20480 ;
    stream:role "primary" ;
    stream:order 0 .
_:c a stream:Compaction ;
    stream:agent "gts-compact" ;
    stream:timestamp "2026-01-01T00:00:00Z"^^xsd:dateTime ;
    stream:sourceHead "blake3:<hex>" .
_:s0 a stream:DetachedSignature ;
    stream:sourceFrame "blake3:<hex>" ;
    stream:cose "<base64url>" .

Claim coupling (normative). Use of stream# terms in a segment that does NOT claim "layout": "streamable" is a warning, not an error (§14.1): provenance quads legitimately survive gts → nq → gts round trips and re-accretion after appends. The error class is reserved for the opposite rot — a claimed layout the bytes contradict (§3.3).

13.4 Domain profile example: music-package (informative)

This subsection is an informative example of a domain-specific profile. A Baseline Reader, Writer, or verifier is not required to implement GMEOW vocabulary, music-domain rules, notation projection rules, or the music-package validator to be conformant with core GTS.

The music-package profile can be defined as a single-segment GTS that carries frame-relative musical content: a MusicalWork/MusicalExpression, its Voices and MusicalSegments, TuningSystem and MusicalTimeFrame reference frames, atomic ToneEvents, DegreeOfFreedom declarations, and standpoint-indexed analysis claims. It is the canonical transport form for the GMEOW music slice and the input to notation projections.

Namespace. The profile reuses the GMEOW music vocabulary (https://blackcatinformatics.ca/gmeow/). A music-package is not required to be a dist profile: it may carry only the musical content graph plus any projection blobs, and it MAY rely on an external dist snapshot for vocabulary definitions.

Header. A music-package segment declares "prof": "music-package". The profile can be append-only for new claims; existing triples are not deleted, only superseded by statement-layer provenance (§7.3).

Example quad shape. A minimal package can contain:

@prefix gmeow: <https://blackcatinformatics.ca/gmeow/> .
@prefix xsd:   <http://www.w3.org/2001/XMLSchema#> .

:piece a gmeow:MusicalExpression ;
    gmeow:hasVoice :voice1 .

:voice1 a gmeow:Voice ;
    gmeow:voiceTuningFrame :tuning12EDO ;
    gmeow:voiceTimeFrame :timeGrid .

:tuning12EDO a gmeow:TuningSystem .
:timeGrid a gmeow:MusicalTimeFrame .

:event1 a gmeow:ToneEvent ;
    gmeow:segmentOf :voice1 ;
    gmeow:toneEventPitchValue :pitchC4 ;
    gmeow:segmentSpan :span1 .

:span1 a gmeow:MusicalTimeSpan ;
    gmeow:hasMusicalTimeFrame :timeGrid ;
    gmeow:timeStartNumerator 0 ;
    gmeow:timeStartDenominator 1 ;
    gmeow:timeDurationNumerator 1 ;
    gmeow:timeDurationDenominator 4 .

Time and pitch are frame-relative: toneEventPitchValue points to a PitchValue interpreted under the event’s voice tuning frame, and offsets/durations are rational values interpreted under the voice time frame.

Projections. A music-package can contain blob frames whose bytes are down-projected representations (MusicXML, MEI, ABC, LilyPond, Humdrum **kern, MIDI, Scala .scl, tablature, mensural, graphic notation). A music-package profile validator can require each projection to be accompanied by a declared-loss manifest that lists the NotationProjectionProfile used, the MusicalParameters it can represent, and the ProjectionLosses it incurs. The manifest can be a Turtle sidecar or an embedded header/comment and is considered part of the projection, not the canonical graph.

Bundle profile coupling. A bundle profile (§12.1) whose blobs are music-package segments provides the multi-movement / multi-version transport case. Each nested segment keeps its own profile declaration; the outer bundle does not impose additional conventions.

Verification. A music-package-aware verifier can check that every NotationSystem referenced by a projection blob has a corresponding NotationProjectionProfile, and that the profile accounts for every MusicalParameter declared in the music slice (no silent omissions). Baseline gts verify is not required to implement this profile; it can report the unsupported profile without failing wire-format validity.

14.1 Composition tooling requirements (normative for conformant tools)

This section defines tool conformance only. A Baseline Reader or Writer need not ship these CLI verbs, transform targets, archive commands, or publication policies to be core-conformant. Profile-aware tools enforce only the profile validators they claim to support; unsupported profiles are surfaced as diagnostics or metadata unless the user explicitly requested that profile’s validation.

Raw cat always works (§3.1); a conformant validating composer (gts cat) and verifier (gts verify) add the refuse-don’t-trust posture:

• gts cat MUST refuse degenerate inputs: an input that is not a valid GTS, a segment whose fold yields zero quads and zero blobs (almost always a wiring bug, never a real package), or an output in which a suppress-only segment would hide every prior frame. Publish-class tools never trust a pathological state to be intentional.
• gts verify MUST check declared-vs-computed requirements for supported profiles: a segment whose graph uses a supported profile’s vocabulary without declaring the profile is an error; a declared-but-unused supported profile is a warning. Declarations a tool reads (the CLI dependency report, §13) must not be able to rot against the content they describe.
• gts verify SHOULD report per-segment: head id, signer set, profile, term/quad counts, opaque-node count with reasons — the composition ledger of the file.
• gts verify MUST check the layout claim (§3.3): a segment claiming "layout": "streamable" whose covered region violates delivery ordering, or whose index footer is missing or contradicts the frames it covers, is an error (StreamableLayoutError, §2.3); stream# vocabulary in an unclaimed segment is a warning (§13.3). gts info and gts verify SHOULD report the streamable boundary of a claimed segment — “streamable through frame N, accretive tail of M frame(s)”.
• gts compact --streamable <in> -o <out> is the layout rewrite (§10.1). It MUST refuse input that does not verify cleanly, input carrying frame-addressed suppressions, and evidence input without the seal-the-original option (--seal-original, §10.1); it MUST emit a single claimed segment in the normative streamable shape (§3.3) with compaction provenance and detached signatures (§13.3), and its output MUST be byte-deterministic for the same input and parameters (blobs ordered by ascending decoded size, ties broken by ascending digest; the rewrite timestamp is a parameter, not ambient time).
• Deterministic graph authoring mode is the reproducible-build writer surface for a folded graph. It emits one ordinary segment and MUST remap local term ids before writing: terms are sorted by semantic value (IRI string; literal lexical form plus effective datatype IRI plus language tag; blank-node label, with anonymous blank nodes using their input occurrence as a tiebreaker; quoted triple resolved to its subject/predicate/object value). It then emits authorable frames in this fixed order: terms, quads, reifies, annot, blob, meta, suppress. Quads, reifier bindings, annotations, blobs, metadata keys, and suppression frames are sorted by the remapped deterministic-CBOR representation. The mode does not replay reader observations (opaque, signatures, diagnostics, or segment ledgers); publication tools that need to preserve those observations must use a profile-specific rewrite such as streamable compaction or seal the original bytes as evidence.
• Blob extraction is verification, never conversion (gts ls, gts extract): blobs are addressed by content digest (frame indices are physical accidents that shift under cat); extraction re-hashes the bytes against the requested digest; a blob suppressed by digest (§11) is refused by default (suppression is a display contract and extraction is display) with an explicit override; a media-type flag is an assertion against the blob’s declared pub.mt — a validating publication tool refuses a mismatch rather than transcoding.

14.2 Archive tooling (files profile)

The files profile adds three validating publication commands. They share the refuse-don’t-trust posture of §14.1: raw byte operations are always valid GTS, but a tool refuses pathological states rather than trusting them to be intentional.

• gts pack <dir|file>... -o out.gts Produce a single-segment GTS whose header declares "prof": "files". Each argument is archived: a file is added under its basename; a directory is added recursively. The resulting archive contains, in order, the terms and quads describing every files:FileEntry, followed by the inline blob frames for the file contents. The command MUST refuse:
  • inputs that contain unsafe stored paths: absolute paths, drive-relative paths, .., ., empty components, or backslash separators;
  • symlinks;
  • inputs that are not readable or that disappear during the walk.
• gts unpack <archive> [-C dir] Write every files:FileEntry in the archive to the destination directory (default current working directory). The command MUST:
  • refuse to write outside the destination directory (.., absolute paths, or symlinks that escape it);
  • re-hash each written file and verify it matches files:digest;
  • restore the file’s declared modification time and permissions (subject to the host OS);
  • skip entries whose digest is suppressed (§11) by default, with an explicit --include-suppressed override.
• gts diff <archive> <dir> Compare the archive’s files:FileEntry set to the current state of <dir> by content digest. Report added, removed, and modified paths. Exit 0 if the directory matches the archive exactly; exit 1 if any path differs or if the input is refused. No byte comparison is needed: content addressing makes the operation O(read) on the directory.

Archive workflow comparison.

The value proposition is not compression ratio. Use a compression transform or an outer transport when size dominates. The files profile is for graph-native manifests, digest-addressed deduplication, append composition, and consistent safety policy across engines.

15.1 Minimal distribution snapshot (dist)

55799(                                   / self-describe magic /
  { "gts": "GTS1", "v": 1, "prof": "dist",
    "cat": { 0: {"name":"identity","cls":"encode"},
             4: {"name":"zstd","cls":"compress"} },
    "id": h'…header.id…' }
)
{ "t": "terms", "prev": h'…header.id…', "id": h'…terms.id…',
  "d": [ {"k":0,"v":"https://example.org/Cat"},          / id 0 /
         {"k":0,"v":"http://www.w3.org/2000/01/rdf-schema#label"},  / id 1 /
         {"k":1,"v":"Cat","l":"en"} ] }                  / id 2 /
{ "t": "quads", "prev": h'…terms.id…', "id": h'…', "x": [4],
  "d": h'…zstd([[0,1,2]])…' }                            / Cat rdfs:label "Cat"@en /

Term 2 is a literal with a language tag and no "dt", so its datatype is rdf:langString (§7.1).

15.2 Evidence: image + signed accrual (evidence)

{ "t": "blob", "prev": h'…header.id…', "id": h'…',
  "pub": {"mt":"image/jp2"}, "d": h'…image bytes…',      / digest = blake3(d) /
  "sig": h'COSE_Sign1 by did:photographer' }
{ "t": "annot", "prev": h'…blob.id…', "id": h'…',
  "d": [[10,11,12]],                                     / reifier 10: capturedAt … /
  "sig": h'COSE_Sign1 by did:photographer' }
{ "t": "annot", "prev": h'…prev.id…', "id": h'…',        / later custody transfer, separate signer /
  "pub": {"event":"custody-transfer"},
  "d": [[13,11,14]], "sig": h'COSE_Sign1 by did:evidence-clerk' }

Nothing is rewritten; every accrual is hash-linked and independently signed.

15.3 Notary: partially-opaque frame (opaque)

{ "t": "annot", "prev": h'…prev.id…', "id": h'…',
  "pub": { "claim": "I hereby notarized this document.",
           "notary": "did:notary:jane", "ts": "2026-06-09T12:00:00Z" },
  "x": [4, 7],                                            / 7 = cose-encrypt /
  "to": [ {"kid":"anon:7f3a…","alg":"ECDH-ES+A256KW"} ],  / pseudonymous kid (opaque profile, §18) /
  "d": h'COSE_Encrypt(verified ID record + provenance)',
  "sig": h'COSE_Sign1 by did:notary:jane' }

Anyone verifies the public notarization and its signature; only the court key decrypts the sealed record; the signature binds the two (§9.2). A reader without the court key folds this to an opaque node with reason:"missing-key", pub intact, sigstat:"valid".

15.4 Graceful degradation (image, content negotiation)

{ "t": "blob", "prev": h'…', "id": h'…', "pub": {"mt":"image/vnd.djvu","rep":"master"}, "x":[9], "d": h'…' }
{ "t": "blob", "prev": h'…', "id": h'…', "pub": {"mt":"image/jpeg","rep":"fallback"}, "d": h'…' }

A reader lacking codec 9 (djvu) folds the master to an opaque node and uses the JPEG fallback — both are present, both are hash-linked.

15.5 Matryoshka: a whole signed GTS sealed inside a frame (bundle / opaque)

{ "t": "blob", "prev": h'…', "id": h'…',
  "pub": { "rep": "sealed-evidence-graph", "mt": "application/vnd.blackcat.gts+cbor-seq" },
  "x": [4, 7],                                            / zstd then cose-encrypt /
  "to": [ {"kid":"did:court:registry"} ],
  "d": h'COSE_Encrypt( zstd( <a complete, independently-signed GTS file> ) )' }

Without the court key this folds to one opaque node — a whole subgraph the holder carries but cannot read, yet whose presence and position the outer chain proves. With the key, a Full Reader recurses (§12.1) and folds the inner GTS — header, chain, signatures and all — into a verifiable subgraph.

16.1 Media type and file extension (normative)

• Media type: application/vnd.blackcat.gts+cbor-seq (registration template in §20.1). GTS uses the +cbor-seq structured-syntax suffix because a GTS file is a CBOR Sequence ([RFC 8742]) of segment headers and frames, not a single CBOR data item. The earlier provisional application/vnd.blackcat.gts+cbor spelling is obsolete; deployments MUST emit application/vnd.blackcat.gts+cbor-seq. Readers MAY accept the obsolete spelling as a legacy alias, but MUST NOT emit it in newly written metadata.
• File extension: .gts.
• Magic bytes: the CBOR self-describe tag 55799 (0xd9 0xd9 0xf7) at the start of the first segment’s Header when the first segment is tagged. A reader MAY use these three bytes as one signal while identifying a candidate GTS file, but MUST confirm the Header shape before treating the bytes as GTS.

Servers that do not recognise application/vnd.blackcat.gts+cbor-seq SHOULD fall back to application/octet-stream rather than a wrong text type; clients SHOULD inspect the first CBOR data item when the media type is missing or generic.

16.2 File identification algorithm (normative)

Media type metadata is authoritative when it is available. When a reader must identify bytes without trusted metadata, it MUST use this algorithm:

1. Treat .gts and application/octet-stream as hints only; neither proves nor disproves GTS.
2. If the first three bytes are 0xd9 0xd9 0xf7, parse the first CBOR item as a tagged item and unwrap tag 55799. Otherwise parse the first CBOR item from byte offset 0.
3. The unwrapped first item MUST be a Header map containing "gts": "GTS1" and lacking frame key "t". A mismatch is not a GTS file.
4. A positive identification is still only an identification result. Complete validity requires parsing the whole observed byte stream as a CBOR Sequence (§3), applying segment-boundary rules (§3.1), and validating ids, chains, profiles, and capabilities as required by the selected conformance class.
5. Implementations MUST NOT require a whole-file CBOR wrapper, a total item count, or a length prefix. Independently valid tagged segments may be concatenated, so later 55799 tags identify later segment headers, not nested whole-file objects.

16.3 HTTP serving semantics (normative)

A GTS package is served like any other immutable binary release, with three extra requirements:

1. Accept-Ranges: bytes MUST be sent for every .gts response. The format is designed for partial, streaming consumption (§3.2): a consumer can fold the header and a prefix of frames without downloading the whole file. Clients choose byte ranges from discovered CBOR item offsets, indexes, or other trusted manifests; HTTP range support does not by itself validate or repair local file bytes.
2. No transforms at the edge. Because the bytes are a content-addressed chain, proxies and servers MUST NOT apply compression, minification, or any byte-altering transform. The frames are already compressed by the writer’s chosen codec; re-compressing at the transport layer breaks content hashes and signatures.
3. CORS. A public vocabulary/dataset package is expected to be cross-origin readable. Responses SHOULD include Access-Control-Allow-Origin: * for the served .gts origin.

16.4 Immutability-aware caching (normative)

Published GTS releases are immutable; a GTS package URL names one exact byte sequence.

• Versioned URLs (…/gmeow/1.2.3/gmeow.gts, …/packages/music/2026-06-18/music.gts, or any URL that contains a version/date/head identifier) MUST be served with:

  Cache-Control: public, max-age=31536000, immutable
  ETag: "<last-segment-head>"

  The natural ETag is the hex of the file’s last segment head id (§3.1), because it transitively commits to every byte of the file. The immutable directive tells caches they need not revalidate for the one-year lifetime.

• latest / conneg aliases (URLs that resolve to the current release and may change) MUST NOT be cached as a single variant:

  Cache-Control: private, no-store
  Vary: Accept

  The Vary: Accept prevents conneg-cache poisoning when the same path negotiates to HTML, Turtle, or the GTS package. This is the same cache-poisoning class addressed for slice IRIs by the Apache generator.

Profile selection remains URL-shaped in v0.2: one URL per package. RFC 6906 / Accept-Profile is noted as a possible future extension, not required for v0.2 conformance.

20.1 Media type registration: application/vnd.blackcat.gts+cbor-seq

• Type name: application
• Subtype name: vnd.blackcat.gts+cbor-seq
• Required parameters: none
• Optional parameters: none
• Encoding considerations: binary. A GTS file is a CBOR Sequence ([RFC 8742]) and is not restricted to 7-bit or 8-bit text; transports that are not 8-bit clean MUST apply a content-transfer-encoding (e.g. base64).
• Security considerations: see §18 of this specification. In summary: the content-id chain provides integrity but not confidentiality; truncation is undetectable without a head commitment; decompression and nested-GTS recursion MUST be bounded; and signatures attest a signer over bytes, not the truth of claims.
• Interoperability considerations: the +cbor-seq structured-syntax suffix ([RFC 8742]) signals that the payload is a CBOR Sequence, so generic sequence tooling can inspect the ordered data items before applying GTS-specific rules. The self-describe tag 55799 ([RFC 8949] §3.4.6) MAY tag each segment header as a magic number. Conformance is defined by the shared test-vector corpus (§19).
• Published specification: this document (GTS — Graph Transport Substrate — Specification).
• Applications that use this media type: content-addressed RDF 1.2 graph transport and archival; signed agent-memory and provenance artifacts; package distribution where the payload bundles a graph and the binaries it references.
• Fragment identifier considerations: none.
• Additional information:
  • Magic number(s): 0xd9 0xd9 0xf7 (the CBOR self-describe tag 55799) when present at the start of the file (§16.1). This prefix is OPTIONAL because the first segment header MAY be untagged.
  • File extension(s): .gts
  • Macintosh file type code(s): none
• Person & email address to contact for further information: Patrick Audley paudley@blackcatinformatics.ca
• Intended usage: COMMON
• Restrictions on usage: none
• Author / Change controller: Blackcat Informatics® Inc.

21.1 Sequence grammar

A GTS file is a CBOR Sequence, not one enclosing CBOR item. CDDL describes the individual items in that sequence; the sequence grammar is defined in English and ABNF-like notation:

gts-file = 1*segment
segment  = [ self-describe-tag ] header *frame

self-describe-tag is CBOR tag 55799 applied to the header item only. It is a wire-level magic hint, not a member of the Header map, and it is not part of the Header "id" preimage (§22). Each segment begins with a Header and then zero or more frame items until the next Header or EOF (§3.1).

21.2 Copyable CDDL

; GTS v1 item grammar. The top-level file is a CBOR Sequence (§21.1).

gts-item = header-item / frame
header-item = header / self-described-header
self-described-header = #6.55799(header)

term-id = uint
frame-index = uint
codec-id = uint
digest = bstr .size 32
content-id = digest
blake3-uri = tstr                  ; "blake3:" + 64 lowercase hex characters
digest-ref = digest / blake3-uri
profile-name = tstr
layout-state = "streamable" / tstr
extension-key = tstr               ; any text key not defined by that map shape

header = {
  "gts": "GTS1",
  "v": 1,
  "prof": profile-name,
  "cat": { * codec-id => codec },
  ? "layout": layout-state,
  ? "dct": { * tstr => bstr },
  ? "meta": any,
  "id": content-id,
  * extension-key => any,
}

codec = {
  "name": tstr,
  "cls": "encode" / "compress" / "encrypt",
  ? "dct": tstr,
  ? "p": any,
  * extension-key => any,
}

frame = {
  "t": frame-type,
  ? "x": [+ codec-id],
  ? "pub": any,
  ? "to": [+ recipient],
  ? "d": frame-payload / bstr,
  "prev": content-id,
  "id": content-id,
  ? "sig": cose-sign1,
  * extension-key => any,
}

frame-type = "terms" / "quads" / "reifies" / "annot" / "blob" / "suppress"
/ "snapshot" / "meta" / "index" / "opaque"

recipient = {
  "kid": tstr,
  ? "alg": tstr,
  * extension-key => any,
}

cose-sign1 = bstr                  ; serialized COSE_Sign1, detached payload = frame "id"

frame-payload = terms-payload / quads-payload / reifies-payload / annot-payload
/ blob-payload / suppress-payload / snapshot-payload / meta-payload
/ index-payload / opaque-node

terms-payload = [+ term]
term = {
  "k": 0 / 1 / 2 / 3,              ; 0=IRI, 1=literal, 2=bnode, 3=quoted triple
  ? "v": tstr,
  ? "dt": term-id,
  ? "l": tstr,
  ? "rf": term-id,
  * extension-key => any,
}

triple-row = [term-id, term-id, term-id]
quad-row = [term-id, term-id, term-id] / [term-id, term-id, term-id, term-id]

quads-payload = [+ quad-row]
reifies-payload = { * term-id => triple-row }
annot-payload = [+ triple-row]

blob-payload = bstr
blob-pub = {
  ? "mt": tstr,
  ? "rep": tstr,
  ? "digest": digest-ref,
  * extension-key => any,
}

suppress-payload = {
  "targets": [+ suppress-target],
  ? "reason": tstr,
  ? "by": term-id,
  * extension-key => any,
}

suppress-target = suppress-frame / suppress-blob / suppress-term
/ suppress-quad / suppress-reifier
suppress-frame = { "kind": "frame", "id": digest-ref, * extension-key => any }
suppress-blob = { "kind": "blob", "digest": digest-ref, * extension-key => any }
suppress-term = { "kind": "term", "id": term-id, * extension-key => any }
suppress-quad = { "kind": "quad", "q": quad-row, * extension-key => any }
suppress-reifier = { "kind": "reifier", "id": term-id, * extension-key => any }

snapshot-payload = {
  "terms": terms-payload,
  ? "quads": quads-payload,
  ? "reifies": reifies-payload,
  ? "annot": annot-payload,
  ? "blobs": { * digest-ref => bstr },
  ? "meta": any,
  * extension-key => any,
}

meta-payload = any

index-payload = {
  "count": uint,
  "head": content-id,
  ? "off": [+ uint],
  ? "ti": { * frame-type => [+ frame-index] },
  ? "dict": [+ frame-index],
  ? "mmr": content-id,
  * extension-key => any,
}

opaque-node = {
  "id": content-id,
  "type": frame-type,
  ? "pub": any,
  ? "to": [+ recipient],
  ? "sigstat": sig-status,
  "reason": opaque-reason,
  * extension-key => any,
}

sig-status = "none" / "valid" / "invalid" / "unverified"
opaque-reason = "unknown-codec" / "missing-key" / "damaged"
/ "unknown-frame-type"

diagnostic = {
  "code": diagnostic-code,
  "detail": tstr,
  ? "frame_index": frame-index,
  * extension-key => any,
}

diagnostic-code = "EmptyFile"
/ "TornAppendError" / "DamagedFrame" / "BrokenChain"
/ "TruncatedLog" / "UnknownCodec" / "MissingKey"
/ "KeyWrapFailed" / "ConflictingReifier" / "RecursionLimit"
/ "StreamableLayoutError" / "PositionConstraint"
/ "ForwardReference" / "SegmentBoundary" / "IndexMmrError"
/ "UnknownFrameType" / tstr

profile-status = "core-required" / "optional-standard" / "experimental"
/ "domain-specific"
profile-registration = {
  "name": profile-name,
  "status": profile-status,
  ? "owner": tstr,
  ? "spec": tstr,
  ? "namespace": [+ tstr],
  ? "requires": any,
  ? "validation": any,
  ? "security": any,
  * extension-key => any,
}

When "x" is present and non-empty, the frame "d" value is a byte string carrying the encoded/compressed/encrypted payload. After reversing the transform chain (§6.1), those bytes decode to the frame-type-specific payload above, except blob, whose decoded payload is raw bytes. When "x" is absent, "d" carries the frame-type-specific payload directly.

blob-pub is the conventional shape of a blob frame’s "pub" map; the frame envelope keeps "pub" typed as any so profiles can layer additional public metadata without changing the core frame grammar. digest-ref accepts both the raw 32-byte digest and the blake3:<hex> text form used by the reference engines.

22.1 Preimage and subject table

22.2 Unknown extension-key behavior

An extension key is a text-string map key not defined by that map’s CDDL production. Defined reserved keys such as "id", "sig", "prev", "t", "d", "x", "pub", and "to" are not extension keys and MUST NOT be repurposed by profiles.

Readers MUST include unknown extension keys when recomputing Header and frame preimages. A reader MUST NOT reject a Header, frame, codec, recipient, term, payload, opaque-node, diagnostic, or profile-registration map solely because it contains an unknown extension key. Unknown keys have no core fold semantics unless a supported profile or extension defines them.

Re-emit behavior depends on the operation:

• Byte-preserving operations such as raw cat, copying, mirroring, or serving preserve unknown keys naturally because they preserve the original bytes.
• A tool that decodes and re-emits a Header or frame while claiming to preserve the same logical item MUST copy unknown extension keys verbatim before recomputing "id" values.
• A tool that cannot preserve unknown extension keys MUST treat the operation as lossy re-authoring, MUST recompute affected "id" and "prev" values, and MUST NOT claim existing frame signatures remain attached to the rewritten frames.
• A compactor or other re-authoring tool MAY preserve old frame signatures only as detached provenance (§10.1), where the old frame id remains the explicit signature subject.

Because extension keys participate in preimages, extension authors can add tamper-evident metadata without changing core GTS grammar. They cannot change header/frame grammar, hash preimages, signature subjects, or fold semantics (§2.1, §13).

23.1 Normative references

• [RFC 2119] Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, March 1997.
• [RFC 8174] Leiba, B., “Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words”, BCP 14, May 2017.
• [RFC 8949] Bormann, C. and P. Hoffman, “Concise Binary Object Representation (CBOR)”, STD 94, December 2020.
• [RFC 8742] Bormann, C., “Concise Binary Object Representation (CBOR) Sequences”, February 2020.
• [RFC 9052] Schaad, J., “CBOR Object Signing and Encryption (COSE): Structures and Process”, STD 96, August 2022.
• [RFC 9053] Schaad, J., “CBOR Object Signing and Encryption (COSE): Initial Algorithms”, August 2022.
• [RFC 9277] Bormann, C. and M. Nottingham, “On the Use of Structured Suffixes in Media Types”, June 2022.
• [RFC 6838] Freed, N., Klensin, J., and T. Hansen, “Media Type Specifications and Registration Procedures”, BCP 13, January 2013.
• [RFC 3339] Klyne, G. and C. Newman, “Date and Time on the Internet: Timestamps”, July 2002.
• [BCP 47] Phillips, A. and M. Davis, “Tags for Identifying Languages”, September 2009.
• [BLAKE3] O’Connor, J., Aumasson, J-P., Neves, S., and Z. Wilcox-O’Hearn, “BLAKE3: one function, fast everywhere” (256-bit output used here).
• [RDF 1.2] W3C, “RDF 1.2 Concepts and Abstract Data Model”, Candidate Recommendation Snapshot, 07 April 2026, https://www.w3.org/TR/2026/CR-rdf12-concepts-20260407/ — the RDF terms, dataset model, triple-term, and rdf:reifies substrate imported by §7.

23.2 Informative references

• [RFC 7049] Bormann, C. and P. Hoffman, “Concise Binary Object Representation (CBOR)”, October 2013 (obsoleted by [RFC 8949]; cited only for its legacy length-first “canonical” ordering, §4).
• [RFC 8610] Birkholz, H., Vigano, C., and C. Bormann, “Concise Data Definition Language (CDDL)”, June 2019.
• [RFC 9111] Fielding, R., Nottingham, M., and J. Reschke, “HTTP Caching”, June 2022 (the caching directives of §16.4).
• [RFC 6906] Wilde, E., “The ‘profile’ Link Relation Type”, March 2013 (the Accept-Profile future extension noted in §16.4).

GTS is intentionally a transport format, not an ontology or graph store. A conforming implementation preserves the append-only, content-addressed fold so independent projections can be regenerated from the same bytes.