GTS

Why GTS?

GTS is built around four durable format choices. It uses CBOR all the way down, including deterministic encoding, native byte strings, and CBOR Sequences so append is cheap and readers need only a CBOR library. Payloads carry stackable transform chains from a durable catalog, separating structural durability from compression, density, and confidentiality. Every frame has a BLAKE3 self-hash and predecessor link, so verification can be parallel and a segment head commits transitively to its history. A decoded payload is just bytes, and a GTS file is just bytes, so a complete signed GTS document can ride recursively inside another frame.

GTS is explicitly not a database, query engine, reasoner, or mutation protocol. Random-access query, SPARQL, analytics, and deep traversal belong to transform targets such as N-Quads, SQLite, DuckDB, Parquet, or graph stores. GTS is the durable, self-describing interchange container that gets graphs and referenced data there intact.

Use GTS without GMEOW

GMEOW is a primary downstream consumer and reference profile family for GTS artifacts. The dependency direction is one-way: GMEOW rides on GTS; GTS does not require GMEOW.

A baseline reader needs the GTS wire-format rules, codec catalog, and RDF term/fold semantics. It does not need a GMEOW ontology checkout, GMEOW-specific vocabulary, music-domain profile knowledge, or agent-memory conventions. Domain profiles can add validation rules above the transport layer, but they do not change the core parse, verification, or fold path.

Format core

GTS is a small, stable narrow waist: generic graphs, evidence, archives, images, media packages, GMEOW, or agent memory above it; filesystems, HTTP range, object storage, artifact registries, or message buses below it.

Applications

GTS supports several use cases without making any one of them the whole project frame.

• Dataset and ontology distribution: publish a verifiable graph package with the binary assets it names.
• GMEOW distribution: ship GMEOW ontology packages and profiles as GTS artifacts.
• Archives and file manifests: package directory trees with graph-native metadata and content-addressed blobs.
• Evidence and custody chains: append observations, signatures, and sealed payloads without rewriting prior history.
• Local-first graph synchronization: concatenate independently produced segments and fold the value-union.
• Agent memory: model belief revision with suppression frames while preserving the original signed history.
• Graph database interchange: hand the folded graph state to N-Quads, SQLite, DuckDB, Parquet, or another transform target.

Install

GTS ships as four interoperable engines, all gated by one frozen, byte-exact conformance corpus.

Quick start

Every engine exposes the same shape: read bytes into a graph, verify the chain, fold to a value, and project to N-Quads, plus writer APIs for producing files.

Python

import gts
from pathlib import Path

graph = gts.read(Path("package.gts").read_bytes())
print(gts.to_nquads(graph))

w = gts.Writer(profile="dist")
w.add_terms([
    gts.Term(gts.TermKind.IRI, "https://example.org/Cat"),
    gts.Term(gts.TermKind.IRI, "http://www.w3.org/2000/01/rdf-schema#label"),
    gts.Term(gts.TermKind.LITERAL, "Cat", lang="en"),
])
w.add_quads([(0, 1, 2, None)])
Path("cat.gts").write_bytes(w.to_bytes())

pip install 'gmeow-gts[rdf]' adds optional rdflib interop.

Rust

use std::fs;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let bytes = fs::read("package.gts")?;
    let graph = gmeow_gts::reader::read(&bytes, false, None);
    println!("{}", gmeow_gts::nquads::to_nquads(&graph));
    Ok(())
}

Add gmeow-gts = "0.9.0" to Cargo.toml, or use Cargo feature flags for advanced adapters, proof, encryption/signing, and database export surfaces.

Go

package main

import (
    "fmt"
    "os"

    "go.blackcatinformatics.ca/gts/nquads"
    "go.blackcatinformatics.ca/gts/reader"
)

func main() {
    data, _ := os.ReadFile("package.gts")
    g := reader.Read(data, false, nil)
    fmt.Print(nquads.ToNQuads(g))
}

TypeScript

import { Read, toNQuads } from "@blackcatinformatics/gmeow-gts";
import { readFileSync } from "node:fs";

const graph = Read(readFileSync("package.gts"), false);
console.log(toNQuads(graph));

Runtime support intentionally follows current toolchains: Python >=3.13, Node.js >=22.16.0, and Go 1.26.4.

Command-line surface

All four engines share the common gts command shape; Python and Rust also add SQLite, DuckDB, and Parquet export extensions.

Exit codes are stable across engines: 0 for clean execution, 1 for diagnostics or refused input, and 2 for usage or IO errors. The cat verb is validating raw byte concatenation: it refuses dirty inputs, contributes-nothing segments, and compositions whose suppressions hide every folded quad.

Engine feature matrix

The frozen vector corpus is the compatibility oracle. The matrix summarizes public package surfaces; conformance claims still name corpus revisions, vector subsets, tiers, and read/verify modes.

Specification and conformance

The specification is a working draft: wire-format major version 1, document version 0.9-draft, dated 2026-06-18. Package releases are versioned separately; the current four-engine package version is 0.9.0.

• GTS-SPEC.md - normative wire-format specification.
• GTS-CONFORMANCE.md - conformance tiers, vector manifest, and diagnostics registry.
• GTS-API-CLI-PARITY.md - cross-language API and command parity contract.
• GTS-THIRD-PARTY-IMPLEMENTER-GUIDE.md - build order and conformance-claim template for independent readers.

The file format in one minute

A GTS file is a CBOR Sequence of one or more segments. Published artifacts use application/vnd.blackcat.gts+cbor-seq; the suffix records that the file is a CBOR Sequence, not a single CBOR item. Each segment is a header map followed by zero or more frame maps. Headers identify segment version, profile set, codec catalog, optional layout, dictionary, metadata, and header id. Frames carry type, optional transform/public/recipient/payload fields, predecessor link, frame id, and optional signature.

GTS file (CBOR Sequence)
|-- segment 0
|   |-- header {gts, v, prof, cat, layout?, dct?, meta?, id}
|   |-- frame  {t, x?, pub?, to?, d?, prev, id, sig?}
|   `-- frame  {t, x?, pub?, to?, d?, prev, id, sig?}
`-- segment 1 (appended via cat)
    |-- header {gts, v, prof, cat, layout?, dct?, meta?, id}
    `-- frame  {t, x?, pub?, to?, d?, prev, id, sig?}

fold(file) = value-union of all segment graphs

Frame ids are computed as BLAKE3-256 over deterministic CBOR frame content with id and sig excluded. Each prev names the previous frame id in the segment. Payloads carry stackable codec chains; unknown codecs or held-back keys degrade a frame to an opaque node rather than failing the read.

Conformance corpus

The repository's vectors/ directory holds the frozen, language-neutral conformance corpus: one canonical .gts file and one oracle .expected.json per case, covering minimal files, zstd/gzip frames, unknown-codec fallback, damaged frames, torn appends, suppression, multi-segment unions, streamable compaction, and related behavior.

The Python reference implementation is the source of truth for regenerating the committed corpus, and all four engines must fold identical bytes to identical expectations. The manifest check proves the committed vector metadata and validator guards without stamping a release revision.

Repository layout and building from source

gmeow-gts/
|-- rust/        # Rust crate gmeow-gts and gts binary
|-- python/      # Python package gmeow-gts, module gts, and corpus generator
|-- go/          # Go module go.blackcatinformatics.ca/gts
|-- ts/          # TypeScript package @blackcatinformatics/gmeow-gts
|-- visual-hashing/ # emojihash and randomart crate
|-- vectors/     # frozen conformance corpus
|-- docs/        # GTS-SPEC.md and companion documentation
`-- .github/     # CI and per-language release workflows

cd rust   && cargo test
cd go     && go test ./...
cd ts     && npm ci && npm test
cd python && uv sync --extra rdf && uv run pytest

The repo-wide justfile covers all-engine tests, linting, formatting, vector regeneration, vector-manifest checks, interop, fuzzing, audits, and wasm checks. CI runs all four engines on Linux, macOS, and Windows, plus live cross-engine interop, fuzzing, and per-ecosystem supply-chain scanning.

Versioning and releases

Each release workflow verifies that the tag matches the manifest version before publishing. Python wheels carry GitHub build-provenance attestations and an SPDX SBOM; downloaded artifacts can be verified with gh attestation verify against the Blackcat-Informatics/gmeow-gts repository.

Specification and docs

• GTS-SPEC.md - normative wire-format specification.
• GTS-SPEC publication record - BII publication metadata using the Crossref work-id plus integer-version DOI suffix policy.
• GTS-GOVERNANCE.md - GIP process, registry policies, compatibility rules, and the v1.0 release-candidate path.
• GTS-V1-RC1-CHECKLIST.md - runnable blocker review, dry-run, release-note, and artifact-verification checklist.
• GTS-ADVANCED-PRIMITIVES.md - streaming sink, index/MMR/proof, replication, range-fetch, and benchmark contracts.
• GTS-ECOSYSTEM-INTEGRATIONS.md - RDF, data, browser, service, and object-store integration contracts.
• GTS-SECURITY-POLICY.md - trust/profile-policy separation, nested-GTS budgets, and v1 crypto deferrals.
• gts-reference.md - Python reference-implementation guide.

Contributing and license

Issues and pull requests are handled through the gmeow-gts repository. Before opening a pull request, contributors are expected to run the relevant engine tests and the repository's pre-commit checks.

The source files carry SPDX MIT OR Apache-2.0 headers. The software is offered under MIT or Apache-2.0, at the user's option, with a separate commercial/proprietary license available from Blackcat Informatics.

Publication identity