Quipu

The Quipu stack is built around a governed, bitemporal knowledge store: shared facts, decisions and work history your agents can query. Quipu can check writes against your rules, records where each fact came from, and answers what was true when.

Quipu is that store. Bitemporal means keeping both when a fact was recorded and, when supplied, when it was true.

A quipu is the Andean knotted-cord record: cords are entities, knots are facts.

See it

Datalinks — a 3D explorer, live in your browser, over Alpha Centauri’s technology tree: 374 entities, 329 prerequisite edges, 17 ranks. Height is longest-path depth, so position is derived and stable rather than emergent. Select a node and the lattice re-lights by personalized PageRank seeded on it. No server — the graph is a baked Quipu export.

Explore this repository’s graph — Quipu’s own code and docs as a knowledge graph, 61k triples shipped with every release, imported and queried by Quipu itself compiled to WebAssembly. The pack is verified against its manifest, its shapes are adopted, and it is staged and promoted in your tab before you can query it: the receiving half of the sharing story below, running rather than described. Then edit it — add, change and retract facts through the real write path — and export the result as a pack that quipu import <archive> --db your.db stages against your local shapes. Still no server.

What is Quipu?

An embeddable Rust library and server for building knowledge graphs with:

• Immutable bitemporal fact log — time-travel, contradiction detection, full audit trail
• RDF data model — IRIs, blank nodes, typed literals via oxrdf
• SPARQL 1.1 query engine — SELECT, CONSTRUCT, ASK, DESCRIBE with property paths, aggregates, RDFS inference
• SHACL validation — configurable write checks with structured, agent-friendly feedback
• Hybrid search — SPARQL + vector similarity in a single query
• Episode ingestion — structured write path for agent-extracted knowledge
• Bulk import + promote — load or migrate a whole dataset validated in a staging graph, then admit it in one transaction (guide)
• Graph projection — materialize subgraphs into petgraph for centrality, components, shortest-path algorithms
• “SQLite energy” — single process, no server required

Three Ways to Use It

Who Is This For?

This book is organized around four personas — pick the one that fits you:

New to SPARQL? Start with SPARQL from Zero — it builds up from a single triple to aggregates and temporal queries using concrete examples.

Quick Taste

# Load some facts
quipu knot data.ttl --db my.db

# Query with SPARQL
quipu read "SELECT ?name WHERE { ?s <http://example.org/name> ?name }" --db my.db

# Start the server
quipu-server --db my.db --bind 0.0.0.0:3030

# Query over HTTP
curl -s localhost:3030/query -X POST \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 5"}'

Architecture at a Glance

graph TD
    A[Turtle / Episodes / API] --> B[SHACL Validation]
    B --> C[EAVT Fact Log]
    C --> D[SPARQL Engine]
    C --> E[Vector Search]
    D --> F[Query Results]
    E --> F
    C --> G[Graph Projection]
    G --> H[petgraph Algorithms]

Facts enter through validation, land in the immutable log, and are queryable through SPARQL, vector similarity, or graph algorithms. Every fact has a transaction timestamp and an optional valid-time window — you can always time-travel to see the state at any point.

Why Quipu

Quipu stores structured knowledge, validates writes against your rules, and lets agents query and share that knowledge through its CLI, REST API and MCP server.

Sharing & Federation

A Quipu store can hand its knowledge to another store, and compose another store’s knowledge, without either one having to trust the other by default. Every step is explicit, hash-verified, and labelled with where it came from — so you never absorb someone else’s knowledge by accident.

Before exporting, load an identifier-policy catalogue and the shapes governing your data. Outward sharing is the default: a missing block-tier catalogue refuses with exit 2; a matched identifier refuses with exit 1.

quipu share --output ./share            # a git-native bundle: facts + shapes + lineage
quipu import ./their-share              # verifies hashes, lands in QUARANTINE, not ROOT
quipu import promote <share-id>         # a named operator's explicit act
quipu status ./share && quipu merge ./share   # diverged? three-way; conflict exits 2

Quipu does not merge on receipt, and it does not take a peer’s word for how trustworthy that peer is: trust is declared by the local operator, never read from the member itself. Federated rows carry _provider, _trust and _freshness, and a partial answer is reported as partial rather than arriving as a short one.

SPARQL SERVICE is supported, restricted to endpoints the operator has configured — variable endpoints are refused and unconfigured hosts are unreachable. That is narrower than SPARQL 1.1’s open federation by design, and Quipu makes no SERVICE conformance claim.

→ Sharing & Federation — the primitive in full, every claim citing the command or symbol that proves it.

Explore this repository’s graph, in your browser

Every release ships a knowledge pack of this repository — its modules, symbols, documents and sections as RDF — and the book has a page that opens it with Quipu itself compiled to WebAssembly. GitHub cannot run scripts in a README, so here is a picture; the page is one click away.

scbrown.github.io/quipu/explore — 61k triples imported and queried in a tab. No server.

It is the receiving half of the sharing story above, running rather than described: the manifest is verified against the exact payload bytes, the bundled shapes are adopted as a deliberate act, and the graph is staged and then promoted — the same share_transport → share_import → promote path quipu import takes, because it is that code, compiled for a different target. Then you get a SPARQL box, a module and document browser, a type distribution and a neighbourhood graph, all of it derived from queries the page will show you. It takes any Quipu pack, not just this one.

And it is not read-only. Add, change or retract facts on any node — through the real tool_set / tool_retract / tool_episode, the same functions the REST API exposes, with the closed-vocabulary gate still enforcing what the sender’s shapes allow. The views update as you go, and you can take the result with you: the edited store exports as a genuine .pendant.tar.gz, built by the same share_payload the CLI uses and declaring the pack it came from as its parent. Import it directly with quipu import <archive> --db your.db to stage it against your database’s loaded shapes; promotion is a separate step. Without --db, archive verification stays in memory. Or download export.nt and diff it — it is line-oriented and canonically ordered, so a change is a reviewable diff.

The bundle is a release asset (quipu-<tag>-wasm.tar.gz), so nothing here is committed and the Pages build needs no Rust.

See It In Action

The built-in explorer at /ui — the whole graph in one request, drawn on canvas.
Run it yourself with just demo (examples/demo-graph).

$ quipu knot infrastructure.ttl --shapes aegis-schema.ttl --db ops.db
Ingested 847 triples in transaction 1 (SHACL: 0 violations)

$ quipu read "SELECT ?svc ?host WHERE {
    ?svc a <http://example.org/WebApplication> ;
         <http://example.org/runsOn> ?host .
  }" --db ops.db

| svc       | host   |
|-----------|--------|
| gateway   | host-a |
| git       | host-b |
| metrics   | host-a |
3 results

$ quipu episode - --db ops.db <<'JSON'
{"name": "host-b-rebuild", "source": "ops/agent",
 "nodes": [{"name": "host-b", "type": "ComputeNode",
            "properties": {"status": "recovered"}}],
 "edges": [{"source": "host-b", "target": "host-a", "relation": "rebuilt_on"}]}
JSON
Ingested 6 triples in transaction 2

$ quipu unravel --valid-at "2026-03-15T00:00:00Z" --db ops.db
# See the world as it was two weeks ago

$ quipu stats --db ops.db
Facts: 853 | Entities: 127 | Predicates: 34

Why Quipu?

This comparison is a self-assessment, not a measurement. Some cells are contestable (Jena, for example, ships a rule reasoner). For measured numbers, see SPARQL 1.1 conformance, where quipu and other stores are scored by the same harness.

Named products in a cell qualify the grouped column: the capability is not being attributed to every member. Graphiti documents explicit bi-temporal tracking, and Stardog’s semantic search compares vector embeddings.

Traditional RDF stores demand too much ceremony. AI-native stores have no structure. Quipu’s thesis: start strict, use agents to bear the cost of strictness.

Features

🏛️ Knowledge Graph Core

• Immutable bitemporal fact log — every fact has transaction time and valid time. Time-travel to any point. Full audit trail. Contradiction detection.
• RDF data model — IRIs, blank nodes, typed literals via oxrdf. Import/export Turtle, N-Triples, JSON-LD, RDF/XML. Exports are stably ordered and can be scoped to ROOT, one named graph, an episode provenance group, or a SPARQL CONSTRUCT result; server exports use the read pool rather than blocking writers.
• Git-native knowledge shares — quipu share writes canonical export.nt, shapes.ttl, and a lineage-aware manifest.json; unchanged graph state produces byte-identical files and stable hashes for meaningful git diffs. Remote consumers use read-only POST /share to receive that exact manifest and file set without access to the server filesystem. When the store carries block-tier InternalIdentifierPattern rules, the producer refuses matching outbound bytes before publishing anything and never rewrites entity IRIs.
• Shape-aware reconnect — quipu status previews base/ROOT/incoming divergence, while quipu merge unions multi-valued RDF and emits structured decisions for sh:maxCount conflicts before any write.
• SPARQL 1.1 — SELECT, ASK, CONSTRUCT, DESCRIBE. BGP, JOIN, UNION, FILTER, OPTIONAL, VALUES, ORDER BY, GROUP BY, aggregates, HAVING, property paths, IN/NOT IN, RDFS subclass inference, and named-graph scoping (GRAPH, FROM, FROM NAMED).
• SHACL validation — strict schema enforcement at write time. Structured feedback with severity, focus node, component, path, and message.
• Graph labels & kinds — graphs carry declared labels on five axes (freshness, trust, policy, durability, dataKind); datasets compose them without ever widening, and every query answer reports the composed label. Opt-in floors can refuse queries that fall below a declared bar.
• Deep freeze — relocate a graph’s full history into a verified read-only archive pack (quipu graph freeze). The graph keeps its IRI and stays queryable — by name, via the urn:quipu:dataset:frozen dataset, or by include_kinds: ["archive"] on a query; quipu graph thaw restores it for writes. GET /graphs lists every registered graph with kind and lifecycle.

🤖 AI-Native Features

• Episode ingestion — structured write path for agent-extracted knowledge. Typed nodes, edges, and provenance tracking (prov:wasGeneratedBy). A node name may appear only once per episode: repeated entries are rejected before any triples are written, since merging them would silently append a second description to the same entity.
• Hybrid search — SPARQL filters candidates, vector similarity ranks them. Combine structured queries with semantic meaning in one call. Type constraints are pushed down into the vector index for O(log n) filtered search with LanceDB.
• Dual vector backends — default SQLite (brute-force cosine similarity), plus a LanceDB backend (ANN with predicate pushdown, Arrow columnar storage) behind --features lancedb. vector.backend in config selects it in-binary: the CLI and server install the configured backend at open, so choosing LanceDB no longer requires an embedder to call Store::set_local_vector_backend by hand.
• Context pipeline — unified knowledge context shaped for agent consumption. Text search + link expansion with configurable depth and budget.
• Agent-friendly feedback — validation errors include what failed, where, why, and what the valid alternatives are.

🧠 Reasoning Engine

• Datalog over EAVT — forward-chaining rules in Turtle DSL, evaluated by datafrog with semi-naive fixpoint. Supports stratified negation-as-failure; variables in negated atoms must be bound by positive atoms, and negation cycles are rejected. Derived facts are first-class triples with provenance.
• Reactive evaluation — TransactObserver re-runs affected rules on every write. Delta-aware: only changed predicates trigger re-evaluation. Behind the non-default reactive-reasoner feature; reason --reactive errors without it.
• Counterfactual queries — Store::speculate() forks a hypothetical view via SQLite SAVEPOINT. Answer “what if we remove X?” without mutation.
• Impact analysis — BFS walk over entity edges with configurable depth and predicate filters. CLI (quipu impact), REST (POST /impact), and MCP tool.

⚙️ Infrastructure

• Git-native composition — quipu import <share-dir> verifies the v1 manifest and payload hashes, resolves exact entity matches, surfaces fuzzy candidates for review, validates against local SHACL shapes, and stages each source in a named graph. Off-vocabulary or non-conforming shares remain quarantined; only quipu import promote <share-id> explicitly admits an eligible graph to ROOT.

• Graph projection — materialize subgraphs into petgraph for centrality, connected components, shortest path algorithms.

• Federation — a GraphProvider trait for multi-source queries, with a RemoteProvider (behind the remote feature) built from federation.remotes config. The server health-checks every configured remote at startup, and POST /query with "federated": true fans out through the federated provider, reporting which members answered. Remotes carry declared trust labels at the federation edge, so a federated answer composes the labels of every member that contributed rather than silently inheriting the caller’s. Federation config is read-side only: adding a remote never turns it into an outbound replication target or bypasses the share scrub/import boundary.

• Graph explorer — the web UI draws the whole node-link view from a single POST /graph payload (nodes plus index-addressed edges), laid out with a Barnes-Hut force simulation on canvas. No CDN, so it renders on an air-gapped deploy.

• Four interfaces — Rust crate (embed), CLI (quipu), REST API (quipu-server), and built-in web UI with embeddable web components. Plus 77 MCP tools for agent integration (79 with the owl feature).

• “SQLite energy” — single process, no server required, inspect with sqlite3, back up with cp.

• Automated releases — release-plz bumps versions from conventional commits, generates changelogs via git-cliff, and creates GitHub releases. Version discovery is git_only = true: the baseline comes from this repository’s tags, never the unrelated quipu crate on crates.io. CI runs fmt, clippy, tests, and markdown lint on every push. /version also reports the deployed git SHA, which matters because a deployment can legitimately sit AHEAD of the newest tag — the SHA, not the version string, identifies what is actually running.

Tour: the library, the CLI, the server and the reasoner

As a Rust Library

[dependencies]
quipu = { package = "quipu-ai", git = "https://github.com/scbrown/quipu" }

#![allow(unused)]
fn main() {
use quipu::store::Store;
use quipu::rdf::ingest_rdf;
use quipu::sparql;
use oxrdfio::RdfFormat;

let mut store = Store::open_in_memory()?;

let turtle = r#"
@prefix ex: <http://example.org/> .
ex:alice a ex:Person ; ex:name "Alice" ; ex:knows ex:bob .
ex:bob a ex:Person ; ex:name "Bob" .
"#;
ingest_rdf(&mut store, turtle.as_bytes(), RdfFormat::Turtle,
           None, "2026-04-04", None, None)?;

let result = sparql::query(&store,
    "SELECT ?name WHERE { ?s a <http://example.org/Person> . ?s <http://example.org/name> ?name }")?;
}

From the Command Line

git clone https://github.com/scbrown/quipu && cd quipu
cargo build --release

# Load, query, explore
quipu knot data.ttl --db my.db
quipu read "SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10" --db my.db
quipu repl --db my.db

# Governance: check an agent's enforcement trace against the policy set
quipu audit trace.jsonl --db my.db          # T ⊨ Σ — exits 1 on a violation
quipu audit inventory --db my.db            # which tool classes are ungoverned
quipu audit namespace --db my.db            # which minted predicates no shape mentions
quipu audit replay trace.jsonl --db my.db   # advise → enforce readiness, per rule

REST API & Web UI

# quipu-server needs `onnx` (the embedding runtime) AND `server` (axum/tokio —
# the HTTP stack is feature-gated so the library does not carry a web server).
# Neither is on by default, and an unmet required-feature SKIPS the binary
# silently rather than erroring, so build the `full` bundle releases ship:
cargo build --release --features full

quipu-server --db my.db --bind 0.0.0.0:3030

# Open the interactive graph explorer in your browser
open http://localhost:3030

# Or use the REST API directly
curl localhost:3030/query -X POST \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 5"}'

The built-in web UI provides:

• Graph Explorer — force-directed visualization with type-based coloring, entity search, and detail panel
• SPARQL Workbench — syntax-highlighted editor with time-travel parameters and tabular/JSON results
• Episode Timeline — chronological view of ingested episodes with extracted entities
• Schema Inspector — type distribution, SHACL shape browser, and validation runner

Embeddable web components (<quipu-graph>, <quipu-sparql>, <quipu-entity>, <quipu-timeline>, <quipu-schema>) let you drop Quipu panels into any page:

<script src="http://localhost:3030/quipu-components.js"></script>
<quipu-graph endpoint="http://localhost:3030"></quipu-graph>

Semantic Web APIs for interoperability:

• Spotlight — entity recognition/disambiguation (POST /spotlight)
• Triple Pattern Fragments — LDF-compatible pagination (GET /fragments)
• OpenRefine Reconciliation — data cleaning integration (POST /reconcile)
• Content Negotiation — GET /entity/{iri} returns JSON-LD, Turtle, or HTML based on Accept header

Reasoner

# Impact analysis — what depends on this entity?
quipu impact http://example.org/gateway --db ops.db

# Counterfactual — what breaks if we remove it?
quipu impact http://example.org/gateway --remove --db ops.db

# Run Datalog rules over the fact log
quipu reason --rules rules.ttl --db ops.db

The reasoner adds forward-chaining inference over the EAVT fact log:

• Datalog rule engine — rules written in Turtle DSL, evaluated with semi-naive datafrog. Supports stratified negation-as-failure over materialized facts, including derived predicates from lower strata; unsafe negation and negation cycles are rejected. Derived facts written back via Store::transact() with full provenance.
• Reactive evaluation — TransactObserver keeps derived facts fresh as base facts change. Delta-aware: only affected rules re-run. Optional reactive-reasoner feature.
• Counterfactual queries — Store::speculate() forks a view (SQLite SAVEPOINT) to answer “what if?” without mutation.
• Impact analysis — BFS walk over entity edges with configurable hop depth and predicate filters. Available as CLI, REST endpoint (POST /impact), and MCP tool.

Architecture

                    ┌──────────────────────────────┐
                    │    Agent / CLI / Bobbin       │
                    └──────────┬───────────────────┘
                               │
              ┌────────────────┼────────────────┐
              │                │                │
        ┌─────┴─────┐   ┌─────┴─────┐   ┌──────┴──────┐
        │ MCP Tools  │   │ REST API  │   │  Rust API   │
        │ (77 tools) │   │ + Web UI  │   │  (crate)    │
        └─────┬─────┘   └─────┬─────┘   └──────┬──────┘
              └────────────────┼────────────────┘
                               │
     ┌─────────────────────────┼─────────────────────────┐
     │                         │                         │
┌────┴────┐  ┌────┴─────┐  ┌──┴───────┐  ┌──────────────┴──────────────┐
│ SPARQL  │  │  SHACL   │  │ Reasoner │  │   KnowledgeVectorStore      │
│ Engine  │  │ Validator│  │ (Datalog)│  │         (trait)             │
└────┬────┘  └────┬─────┘  └──┬───────┘  └──────┬─────────┬───────────┘
     │             │           │                 │         │
     └─────┬───────┴───────────┘          ┌──────┴───┐ ┌───┴──────┐
           │                              │  SQLite  │ │ LanceDB  │
           │                              │ (default)│ │(optional)│
     ┌─────┴──────────────┐               └──────────┘ └──────────┘
     │   EAVT Fact Log    │
     │   (SQLite)         │
     │                    │
     │  facts + terms +   │
     │  shapes + rules    │
     └────────────────────┘

Bobbin Integration

Quipu is designed as a Bobbin subsystem. Bobbin holds the thread (code context); Quipu ties knots of structured meaning into it.

Through Quipu’s own MCP server (quipu mcp, or quipu-server at /mcp), agents get 77 MCP tools (79 with the owl feature). The two most commonly used for knowledge-aware context:

quipu_context — unified knowledge discovery. Bobbin merges the result with its own code search to give agents both code and knowledge in one response.

{
  "tool": "quipu_context",
  "input": { "query": "gateway reverse proxy", "max_entities": 10 }
}
// Returns ranked entities with facts, types, and relevance scores

quipu_episode — save agent-extracted structured knowledge with full provenance tracking.

{
  "tool": "quipu_episode",
  "input": {
    "name": "deploy-v3",
    "source": "aegis/ellie",
    "nodes": [{"name": "gateway", "type": "WebApplication",
               "properties": {"version": "3.0"}}],
    "edges": [{"source": "gateway", "target": "host-a", "relation": "runs_on"}]
  }
}

Embeddings are shared: Bobbin’s ONNX pipeline (all-MiniLM-L6-v2) provides 384-dimensional vectors to both its code search and Quipu’s knowledge search, enabling hybrid queries that span both domains.

Agent access

When Quipu MCP tools are configured, agents should use them first so structured inputs, validation feedback, and provenance stay in the tool contract. Use the native quipu CLI second for local databases and offline work. Raw HTTP is the portability fallback; endpoint shapes and authentication are in the REST API reference.

Named graphs are first-class query scopes, and named datasets are reusable sets of graphs. ROOT remains the default until a caller explicitly selects a graph or dataset with SPARQL FROM / FROM NAMED, the query graph field, or the query tool’s graph field. This permits an application to ground a request in one declared plane without silently widening into every graph. See Named Graphs for the registration, write, and trust-label rules.

Feature Matrix

Legend: ✅ available in the shipped quipu CLI / quipu-server · 🔩 library primitive only, not reachable from the shipped binaries · 🔜 planned.

Installation

As a Rust Dependency

Add to your Cargo.toml:

[dependencies]
quipu = { package = "quipu-ai", git = "https://github.com/scbrown/quipu" }

To use SHACL validation (enabled by default):

[dependencies]
quipu = { package = "quipu-ai", git = "https://github.com/scbrown/quipu", features = ["shacl"] }

To exclude SHACL (smaller binary, faster compile):

[dependencies]
quipu = { package = "quipu-ai", git = "https://github.com/scbrown/quipu", default-features = false }

From Source

qp is the preferred command name; quipu remains supported. Install both names plus the companion server with:

just install
# Optional destination directory:
just install "$HOME/.local/bin"
qp --version
quipu --version

qp is a relative symlink to quipu, so both execute the same binary after upgrades. The installer refuses an existing conflicting qp in the destination or on PATH. It never replaces another tool’s command name. Release archives also carry this relative link beside both binaries.

To add the command name to an existing installation without opening a store:

quipu install-alias --check
quipu install-alias

git clone https://github.com/scbrown/quipu
cd quipu
cargo build --release --features full

This produces two binaries:

• target/release/quipu – CLI tool
• target/release/quipu-server – REST API server

quipu-server requires both onnx (the embedding runtime it uses to auto-embed queries) and server (axum, tower-http and tokio — the HTTP stack is feature-gated so the library does not carry a web server; server also implies remote, the federation client). The full bundle is what releases are built with and enables both. Neither is a default feature, so a plain cargo build --release produces only the quipu CLI and silently omits the server (cargo skips a bin whose required-features are off). If you only want the CLI, cargo build --release is enough. Verify the server built:

ls target/release/quipu-server

Keep the CLI and server from the same build beside each other for quipu mcp. Both quipu --version and quipu-server --version report git_sha and git_dirty without opening a database or loading configuration. A source archive without Git metadata reports git_sha: unknown; a dirty build reports git_dirty: true. The HTTP /version response retains its existing format.

With Cargo

Cargo installs the executable targets; finish the installation with the alias command to provide both supported names:

cargo install --git https://github.com/scbrown/quipu --locked --features full
quipu install-alias
qp --version

install-alias uses the directory containing the running Quipu executable, including Cargo’s --root destination. It refuses conflicting qp names and verifies the same inode and exact version output. --check only checks for collisions and does not create the link.

just install resolves its root as QUIPU_INSTALL_ROOT, then CARGO_INSTALL_ROOT, then $HOME/.local, and installs into that root’s bin directory. Its optional directory argument overrides this resolution.

The Full Stack (caboodle)

To install Quipu as part of the whole knowledge stack — caboodle interviews, plans, applies, and verifies the installation of every stack tool — use the wrapper script:

# Phase one: install caboodle if absent, write a reviewable plan, STOP.
scripts/install-stack.sh --profile kg

# Phase two: after reviewing caboodle-plan.toml, apply + verify,
# then verify and load knowledge packs into the target store.
scripts/install-stack.sh --profile kg --yes \
  --pendant domain.pendant.db --db my.db

The two-phase gate is deliberate and mirrors caboodle’s own doctrine: nothing installs until the written plan has been reviewed (or --yes given explicitly). Every --pendant is checked with quipu pack --verify before quipu unpack — a content-hash mismatch refuses the pack rather than installing silently corrupted knowledge. --dry-run prints every command the script would run and executes nothing; --profile selects the caboodle profile (default kg).

Python Client

The REST API has a thin, zero-dependency Python client under python/:

pip install ./python

See the Python Client reference.

Requirements

• Rust 1.85+ (edition 2024)
• SQLite is bundled via rusqlite – no system dependency needed
• Python >= 3.11 for the optional Python client (stdlib only)

Quick Start

Rust Library

use quipu::store::Store;
use quipu::rdf::ingest_rdf;
use quipu::sparql;
use oxrdfio::RdfFormat;

fn main() -> quipu::error::Result<()> {
    // Open a persistent store (or use open_in_memory() for testing)
    let mut store = Store::open("my-knowledge.db")?;

    // Ingest Turtle data
    let data = r#"
    @prefix ex: <http://example.org/> .
    @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

    ex:alice a ex:Person ;
        ex:name "Alice" ;
        ex:age "30"^^xsd:integer ;
        ex:knows ex:bob .

    ex:bob a ex:Person ;
        ex:name "Bob" ;
        ex:age "25"^^xsd:integer .
    "#;

    let (tx_id, count) = ingest_rdf(
        &mut store,
        data.as_bytes(),
        RdfFormat::Turtle,
        None,
        "2026-04-04T00:00:00Z",
        Some("demo"),
        Some("quick-start"),
    )?;
    println!("Ingested {count} triples in transaction {tx_id}");

    // Query with SPARQL
    let result = sparql::query(
        &store,
        r#"SELECT ?name ?age WHERE {
            ?s a <http://example.org/Person> .
            ?s <http://example.org/name> ?name .
            ?s <http://example.org/age> ?age .
            FILTER(?age >= 28)
        }"#,
    )?;

    println!("People aged 28+:");
    for row in result.rows() {
        println!("  {:?} age {:?}", row.get("name"), row.get("age"));
    }

    Ok(())
}

CLI

# Build
cargo build --release

# Load data
quipu knot data.ttl --db my.db

# Query
quipu read "SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10" --db my.db

# Interactive REPL
quipu repl --db my.db

REST API Server

# Build the server with the full bundle. quipu-server has
# required-features = ["shacl", "onnx", "server"], and cargo SILENTLY SKIPS a
# binary whose required features are missing — a plain `cargo build --release`
# (or a partial feature list) builds only the `quipu` CLI and you'd never know.
cargo build --release --features full

# Start
quipu-server --db my.db --bind 0.0.0.0:3030

# Health check
curl localhost:3030/health

# Query
curl -s localhost:3030/query -X POST \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 5"}'

# Ingest an episode
curl -s localhost:3030/episode -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "name": "test-episode",
    "nodes": [
      {"name": "alice", "type": "Person", "description": "Test user"}
    ],
    "edges": []
  }'

MCP (Agent Integration)

Run quipu mcp --db <path> (stdio) or quipu-server (/mcp over HTTP), and agents get Quipu’s tools:

{
  "tool": "quipu_query",
  "input": {
    "query": "SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 5"
  }
}

See the MCP Tools Reference for all available tools.

Configuration

Quipu is configured via .bobbin/config.toml in your project directory or ~/.config/bobbin/config.toml for global defaults.

Config File

[quipu]
# Path to the SQLite triple store
store_path = ".bobbin/quipu/quipu.db"

# Base namespace new IRIs are minted under (optional; default is the aegis
# ontology namespace). A non-aegis deployment MUST set this before its first
# write — an IRI namespace is data identity and cannot be changed afterwards
# without re-ingesting every episode.
base_ns = "http://example.org/kb/"

[quipu.server]
# Enable the REST API server
enabled = false
# Bind address
bind = "127.0.0.1:3030"
# Require this bearer on write endpoints.
# auth_token = "current-token"
# During a credential rotation only, accept the old bearer for at most 24h.
# Use an absolute deadline so restarting cannot renew the old bearer.
# previous_auth_token = "old-token"
# previous_auth_token_expires_at_epoch_secs = 2000000000

[quipu.events]
# Event-log retention. Unset (the default) keeps every event forever.
# When set, the server hourly deletes events older than this many days —
# but never an event a registered consumer has not yet committed past, so
# a lagging consumer's replay is never broken (its backlog just stays on
# disk). A consumer registering AFTER a prune replays from the retained
# prefix, not from genesis.
# retention_days = 90

# Read-only databases mounted alongside the store. Each block is one layer:
# a knowledge pack, a shared reference database, a frozen archive someone
# handed you. Their named graphs become readable by `GRAPH <iri>` / `FROM <iri>`
# without changing what any existing query returns.
# [[quipu.attachments]]
# alias = "reference"
# path = "/srv/quipu/reference.pendant.db"

Config Fields

Every key below is wired — src/config.rs carries a test (config_knobs_are_wired_or_listed_unwired) that fails if a documented knob stops being read.

Zero-downtime bearer rotation

Quipu captures bearer configuration at startup. To rotate without a write freeze, configure the new value as server.auth_token, the old value as server.previous_auth_token, and a short server.previous_auth_token_expires_at_epoch_secs, then restart quipu-server. Both bearers authenticate writes until the grace deadline; request telemetry records authenticated_current or authenticated_previous without recording either secret.

After consumers have switched, remove both previous_auth_token fields and restart again. That explicitly invalidates the old bearer immediately. If the cleanup restart is delayed, the old bearer still expires at the configured absolute deadline, and a restart never extends it. On restart, an expired previous bearer is dropped with a warning; the current bearer remains required and valid. Forgotten cleanup cannot cause a delayed startup outage. Invalid pairs, identical bearers, and deadlines over 24 hours away still make startup fail closed.

Attachments

[[quipu.attachments]] mounts other SQLite databases alongside your store, so their named graphs are readable in the same query as your own. Both binaries honour it at open — every quipu subcommand and quipu-server alike.

[[quipu.attachments]]
alias = "reference"
path = "/srv/quipu/reference.pendant.db"

[[quipu.attachments]]
alias = "tenant_a"
path = "packs/tenant-a.db"

What to expect:

• Nothing silently changes. The default dataset stays your own ROOT alone, so an attachment is visible only to a query that names one of its graphs — GRAPH <iri>, FROM <iri>, or a dataset that includes it.
• Mounts are read-only, always. There is no read_only = false: cross-database writes are permanently out of scope, so the key would be an affordance for something the store refuses anyway.
• A bad declaration refuses the open — it never degrades into fewer rows. A missing file, an invalid or duplicate alias, a file with no g column (it predates named graphs), or one whose term space collides with yours all fail at startup, naming the alias and the remedy. A term-space collision is fixed with quipu db respace.
• The packs you already build are attachable. quipu pack --space N ships a pack in its own term space, which is exactly what a collision-free mount needs.

See what is actually mounted — including deep freeze’s archives, which no config declares:

quipu db attach --list --db my.db

quipu-server prints the same list to stderr at startup.

Choosing a vector backend

[quipu.vector] backend selects the store’s vector backend at open, for both binaries: search, entity resolution, auto-embedding and the MCP/REST search tools all go through the selected one.

[quipu.vector]
backend = "lancedb"
lancedb_path = ".bobbin/quipu/quipu-vectors"

lancedb requires a binary built with the lancedb feature, and the release binaries are not. The feature drags in protoc and the whole datafusion tree, which most deployments do not need. A binary that lacks it refuses backend = "lancedb" at startup and names the rebuild — it does not fall back to the SQLite table, because a deployment that has run quipu migrate-vectors would then have every search answered out of the store it migrated away from.

Move existing embeddings across with quipu migrate-vectors --from sqlite --to lancedb. See LanceDB Vector Backend.

Configuration coverage

Every documented key above is read by the shipped binaries. unwired_warnings() reports any configured key that parses but is not acted on, so an inert setting produces a warning.

Priority Order

Configuration is resolved in this order (highest priority first):

1. CLI flags (--db, --bind)
2. Project config (.bobbin/config.toml in working directory)
3. Global config (~/.config/bobbin/config.toml)
4. Built-in defaults

CLI Overrides

CLI flags always take precedence:

quipu read "SELECT ..." --db /tmp/test.db    # Overrides store_path
quipu-server --bind 0.0.0.0:8080             # Overrides server.bind

Read-only follower serving

A file-level replication operator can serve a changing follower with:

[quipu.server.replica]
primary_url = "https://primary.example"

Start quipu-server --read-only --db /path/to/follower.db from that configuration directory. Keep --read-only in the service invocation: it refuses startup if neither config nor --primary-url URL supplies a valid primary, even if the config file disappears. --primary-url URL overrides the configured primary. This is an opt-in serving role, separate from the older server.read_only HTTP-only access-control flag. The default primary serving role is unchanged. Server startup now refuses invalid or unreadable existing configuration instead of silently falling back to defaults. Replica mode opens only existing SQLite databases read-only, with no schema setup or migration. Every read connection explicitly waits up to one second for short apply locks. It never falls back to opening a writable database. SQLite may create WAL/SHM sidecars; the directory must support the follower’s locking protocol. Do not use immutable=1 for a database that replication updates.

The replica does not initialize a keyword index, materialize OWL, register write observers, load a signing identity, reset/checkpoint WAL, deliver subscriptions, refresh graph-count snapshots, or prune events. Read policies (namespace, search limits, labels and resolution) are still configured. Keyword search requires an index already present on the primary. Attachments and external vector backends currently refuse startup rather than silently dropping configured providers. Graph-count metrics remain unavailable until an independent read-only refresh contract is implemented; they must not be interpreted as healthy zeros.

Mutating HTTP routes return 503 with reason: "read_only_replica" and the configured primary URL. Writes are never forwarded or redirected, including signed writes: the refusal occurs before credential/nonce settlement. SQLite’s read-only handle independently refuses a planted writer that bypasses HTTP. This role does not provision, replicate, promote or fail over a database.

Lag observations

GET /watermark returns the serving store’s store_id and watermark_tx using indexed reads. A replica polls that endpoint on its configured primary every 15 seconds, with a two-second HTTP timeout, no redirects and a bounded response. This is its only background task and performs no database writes.

Responses include X-Quipu-Replica-Lag-Tx. The metrics are:

• quipu_replica_lag_transactions: primary minus follower transaction IDs; -1 means UNKNOWN.
• quipu_replica_lag_known: 1 only for a successful observation no older than 30 seconds; otherwise 0.

A failed request, malformed response, mismatched store lineage, primary behind the follower, unavailable local connection, or stale observation gives UNKNOWN, not zero. Values describe the most recent bounded observation, not an atomic cross-host snapshot, elapsed seconds or proof of identical contents. The replication operator must establish the same primary lineage and common-prefix contract before interpreting transaction distance. A primary without /watermark yields UNKNOWN until upgraded; no expensive fallback query runs.

just replica-test /path/to/quipu-server /path/to/quipu checks a scratch follower: 100 positive reads, unchanged main DB hash/counter/mtime across start and stop, 503 write responses, lag failure handling and a pending-subscription trap that must never deliver. Library/server tests also plant a write against the actual read-only connection. The scratch test does not change or probe production.

Private bounded query specimen

server.query_capture is omitted by default. An omitted configuration or enabled = false creates no capture worker, file or capture-state log. An operator can explicitly configure enabled, an exact lowercase query_sha256, query_bytes (1–4096), a unique alphanumeric/underscore/hyphen window_id, and absolute start_epoch_secs/end_epoch_secs. The window is at most five minutes; startup refuses an expired window or a start more than fifteen minutes ahead. A parsed selector/window that fails validation disables the diagnostic without changing normal query results; malformed configuration still follows normal strict configuration-loading errors. There is no HTTP endpoint to arm it.

Only the first matching Seeds-category POST /query request can consume the claim. Eligibility is the intersection of the absolute UTC window and its startup-pinned monotonic start/end, so clock jumps cannot extend or start it early. At startup the server exclusively claims query-captures/<window_id>.json beside the canonical store file, using a same-owner private directory and descriptor-relative, no-follow exclusive creation. Existing claims are never overwritten, including empty files left by a crash: restarting cannot renew the attempt. Unsupported platforms refuse enabled capture. Operators retain and adjudicate these private artifacts; the server does not delete or retry them.

A capacity-one worker writes at most 16 KiB outside store locks. The record contains exact raw SPARQL, bounded planning options, UTC, build identity and the existing request/process/query/input digests. Headers, response bodies and unknown JSON fields are excluded; omitted fields are explicitly flagged. Raw query literals can be sensitive, and a digest is not anonymization. The Seeds client category is an unauthenticated attribution label, not proof of caller identity. Serialization overflow consumes the attempt and records refusal without a truncated query. File failures leave an UNKNOWN partial or empty claim; no request is retried. Default-off source deployment does not authorize arming: use a separately approved window and flag-off rollback, then read back that the flag is off.

Triples and the Knowledge Graph

Everything in Quipu is a triple: a subject, a predicate, and an object.

<korimako>  <runs>  <traefik>
 subject  predicate  object

This triple says “korimako runs traefik.” Three triples can encode a complete service dependency:

@prefix hw: <http://example.org/homelab/> .

hw:korimako    a               hw:Host .
hw:korimako    hw:runs         hw:traefik .
hw:traefik  hw:dependsOn    hw:pihole .

That’s it. No tables to design, no schema migrations. You add facts incrementally and query them with SPARQL.

IRIs: Naming Things

Every entity and predicate is identified by an IRI (Internationalized Resource Identifier) — a globally unique name like a URL:

http://example.org/homelab/korimako

Prefixes keep things readable. Instead of writing the full IRI every time:

@prefix hw: <http://example.org/homelab/> .

hw:korimako  hw:runs  hw:traefik .

hw:korimako expands to http://example.org/homelab/korimako.

Objects: References vs Literals

The object of a triple can be either:

• A reference to another entity (another IRI)
• A literal value (a string, number, boolean, or date)

hw:korimako  hw:runs      hw:traefik .          # reference → another entity
hw:korimako  hw:hostname  "korimako.example" .          # literal → a string
hw:korimako  hw:cpuCores  "4"^^xsd:integer .     # literal → a typed number

How Quipu Stores Triples

Under the hood, Quipu stores triples as EAVT facts in an immutable log:

Every fact also carries a valid-time window (valid_from, valid_to), so you can model when facts were true in the real world — not just when they were recorded. See The Temporal Model for details.

The RDF Data Model

Quipu uses the RDF data model, which means:

• Facts are interoperable with any RDF tool
• You can ingest data in Turtle, N-Triples, JSON-LD, RDF/XML, or TriG
• You query with SPARQL — the standard RDF query language
• You validate with SHACL — the standard RDF constraint language

You don’t need to know RDF theory to use Quipu. If you can read subject predicate object . you’re ready to go.

Loading Triples

From a Turtle file:

quipu knot homelab.ttl --db homelab.db

From the REST API:

curl -s localhost:3030/knot -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "turtle": "@prefix hw: <http://example.org/homelab/> .\nhw:korimako a hw:Host ; hw:hostname \"korimako.example\" ."
  }'

From an episode (structured agent input):

curl -s localhost:3030/episode -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "name": "homelab-inventory",
    "nodes": [
      {"name": "korimako", "type": "Host", "properties": {"hostname": "korimako.example"}},
      {"name": "traefik", "type": "WebApp"}
    ],
    "edges": [
      {"source": "korimako", "target": "traefik", "relation": "runs"}
    ]
  }'

What’s Next

• The Temporal Model — how time-travel works
• SPARQL from Zero — querying your triples
• SHACL Validation — enforcing structure

The Temporal Model

Every fact in Quipu has two time dimensions:

1. Transaction time — when the fact was recorded in the database
2. Valid time — when the fact was true in the real world

This is called a bitemporal model, and it means you can always answer:

• “What did we know at time T?” (transaction time)
• “What was true at time T?” (valid time)
• “What did we know at time T1 about what was true at T2?” (both)

Why Bitemporality Matters

Say you record on April 1 that korimako has 4 CPU cores:

quipu knot - --db homelab.db --timestamp 2026-04-01 <<'EOF'
@prefix hw: <http://example.org/homelab/> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
hw:korimako hw:cpuCores "4"^^xsd:integer .
EOF

On April 3 you upgrade to 8 cores and record the change:

quipu retract "http://example.org/homelab/korimako" \
  --predicate "http://example.org/homelab/cpuCores" \
  --db homelab.db --timestamp 2026-04-03

quipu knot - --db homelab.db --timestamp 2026-04-03 <<'EOF'
@prefix hw: <http://example.org/homelab/> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
hw:korimako hw:cpuCores "8"^^xsd:integer .
EOF

Now you can time-travel:

# What's the current state?
quipu read "SELECT ?cores WHERE {
  <http://example.org/homelab/korimako> <http://example.org/homelab/cpuCores> ?cores
}" --db homelab.db
# → 8

# What was true on April 2?
quipu read "SELECT ?cores WHERE {
  <http://example.org/homelab/korimako> <http://example.org/homelab/cpuCores> ?cores
}" --db homelab.db --valid-at 2026-04-02
# → 4

The EAVT Fact Log

Under the hood, facts are stored as immutable rows:

Nothing is deleted. Retractions close the valid_to window on old facts and add a new retraction record. The full history is always available.

Transaction Time vs Valid Time

Transaction time is monotonic and system-controlled. Valid time is user-supplied and can refer to the past or future.

Querying Through Time

Current state (default)

SELECT ?host ?cores WHERE {
  ?host <http://example.org/homelab/cpuCores> ?cores .
}

Returns only currently-asserted facts (op=Assert, valid_to is null).

Valid-time travel

quipu read "SELECT ?host ?cores WHERE {
  ?host <http://example.org/homelab/cpuCores> ?cores
}" --db homelab.db --valid-at 2026-04-02

Returns facts that were valid at the specified point in time.

Transaction-time travel

quipu read "SELECT ?host ?cores WHERE {
  ?host <http://example.org/homelab/cpuCores> ?cores
}" --db homelab.db --tx 1

Returns only facts recorded up to transaction 1 — what the database knew at that point, regardless of valid-time windows.

REST API

curl -s localhost:3030/query -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT ?host ?cores WHERE { ?host <http://example.org/homelab/cpuCores> ?cores }",
    "valid_at": "2026-04-02"
  }'

Contradiction Detection

If two facts for the same entity+attribute have overlapping valid-time windows, Quipu flags a contradiction. This prevents conflicting states from silently coexisting:

#![allow(unused)]
fn main() {
let issues = store.detect_contradictions()?;
// Returns pairs of facts with overlapping intervals
}

Design Principles

• Append-only: Facts are never mutated or deleted
• Full audit trail: Every change is a transaction with metadata
• Time-travel by default: Any query can add a temporal context
• Contradiction-aware: Overlapping valid-time windows are surfaced

Named Graphs, Overlays & Datasets

Implementation status: ✅ Built on the sanctioned surfaces — the g column and graphs registry, overlay create/write/compose, GRAPH / FROM / FROM NAMED evaluation, the graph query param, and named datasets, and (since 2026-08-21) a strict graph param on POST /knot that accepts only already-registered committed-class graphs. Deliberately not built: property paths under GRAPH ?g (explicitly refused, never a silent ROOT read). See docs/design/named-graphs.md for the full design.

Every fact in quipu’s EAVT store carries a graph coordinate on top of (entity, attribute, value) and the two time axes — the store is really a quad store. The g column says which subgraph a fact lives in, orthogonal to when it holds (valid_from/valid_to) and when the store learned it (tx). Retraction, time-travel, and contradiction detection all scope within a graph: a retraction in graph A never touches graph B.

• g = 0 is the reserved ROOT graph — the default committed graph, the source of truth.
• A named graph’s g is the interned term id of its graph IRI, so resolving GRAPH <iri> is a single term lookup.
• The graphs registry keeps one row per graph with an enforced class: committed (a durable branch; ROOT is the seeded, self-rooted one) or overlay (a layer over a committed parent). A graph’s class is fixed at create.

Querying: GRAPH, FROM, and the graph param

SPARQL reads are ROOT-scoped by default. The default graph is ROOT alone, not an all-graph union — silence must never expose another tenant’s overlay. A query widens its dataset only by saying so:

• GRAPH <iri> { … } scopes the enclosed patterns to one named graph. An unknown IRI matches nothing.
• ROOT is the default graph, not a named graph. GRAPH <urn:quipu:graph:root> is refused with an error naming the default-graph form. Read ROOT without a GRAPH clause, or explicitly use FROM <urn:quipu:graph:root>.
• GRAPH ?g { … } ranges over the active named graphs, binding ?g to each match’s graph IRI. Property paths under GRAPH ?g are refused with an explicit error rather than silently reading ROOT.
• FROM <g…> makes the default graph the RDF merge (union) of those graphs. An unknown graph contributes nothing; an all-unknown FROM set yields an empty default graph — never a fall-through to ROOT.
• FROM NAMED <g…> restricts which named graphs a GRAPH clause can see. A query with FROM but no FROM NAMED activates no named graphs (per SPARQL 1.1), so GRAPH matches nothing.

SELECT ?s ?title
FROM <http://example.org/graphs/derived>
WHERE { ?s <http://example.org/title> ?title }

/set and /retract operate only on ROOT and leave named-graph facts intact. They refuse a supplied graph field, including null, before changing facts. For a named graph, use the explicitly scoped /update endpoint instead.

POST /query and the quipu_query MCP tool also take a graph request param — a convenience that scopes the query’s default graph to one named graph without writing a FROM or GRAPH clause:

{"query": "SELECT ?s ?o WHERE { ?s <http://example.org/p> ?o }",
 "graph": "http://example.org/graphs/derived"}

Omitting it keeps the ROOT default; an unknown IRI gives an empty default graph; a FROM clause in the query text overrides the param. The param also resolves dataset names: passing a dataset IRI scopes the query to that dataset’s members, so FROM <dataset> and "graph": "<dataset>" mean the same thing. The same graph param on quipu_export / POST /export exports one named graph’s facts instead of ROOT.

Search has a broader default than SPARQL

On a new store, POST /search and quipu_search default to ROOT plus registered named graphs. Existing stores retain ROOT until explicitly broadened with [quipu.search] default_graph_scope = "all". When that setting is omitted, the store persists its default; read-only legacy stores use ROOT without migration. Coverage reports the effective default and its source. This policy is local to the receiving store: importing a share does not replace it with the sender’s choice. A whole-file backup retains the store’s policy. For example, a work tracker can keep its records in its own project graph: those records need not be copied into ROOT to be discoverable. This covers graphs registered in the local store, including attached layers registered there; it does not query remote federation endpoints automatically.

Configure retrieval policy under [quipu.search]:

default_graph_scope = "all"
exclude_graphs = ["urn:example:quarantine", "urn:example:private-work"]

Use default_graph_scope = "root" for the previous implicit scope. Requests can select graph: "urn:quipu:graph:root", one named graph IRI, graphs: [iri, iri], or all_graphs: true. Configured exclusions apply to all selections; a selection emptied by exclusions refuses. These controls are retrieval policy, not access control. Deployments needing tenant isolation must enforce authorization separately. Configure exclusions before exposing a store containing scratch or quarantine graphs to general search.

Every successful search returns search_scope: selected graph IRIs, configured exclusions, whether selection was explicit, named-vector enablement, and the fact that index completeness is not certified. Result graph provenance does not promote a fact or make its source authoritative. Similarity and context admission still apply; an empty search does not prove a graph contains no facts.

Semantic retrieval uses one vector per entity. An entity with ROOT text keeps that representation; a named-only entity combines its named-graph facts. Selecting a graph filters membership, not the vector’s text provenance. For assertion-level literal matching within one graph, use keyword search. This distinction is why listing selected graphs does not certify complete indexing.

Semantic search across named graphs still requires named_graphs = true. Prepare existing named-only vectors using bounded /embed_backfill_graph calls before enabling it; an unprepared default all-graph request refuses instead of silently reporting ROOT as complete coverage. Keyword search needs its enabled, backfilled lexical index, but no embedding provider or named-vector flag. ROOT-only content ranking, anchor traversal, and structured search refuse a broader scope. See the search API.

Querying and promotion are separate operations

To inspect one graph, use GRAPH <iri> or the /query graph parameter above. To join graph contents deliberately, use FROM <a> FROM <b> or a registered dataset. Search scope never changes these SPARQL defaults or writes facts.

Promotion admits reviewed content into ROOT; it is not required merely to find or query named-graph data. For bulk material, use the producer’s share, then import to stage and validate it, inspect the admission result, and use import promote <share-id> only when eligible and authorized. Do not replace promotion with a loop of episode or update writes. See bulk loads and migrations for exact commands, shape admission, and fork rollback. A search hit from a staging graph is still staged content until that governed promotion succeeds.

Property paths follow a fixed graph scope without crossing it: a GRAPH <iri> closure stays inside that graph, a FROM <a> FROM <b> path traverses their merge. A path never crosses a graph boundary — half a path in an overlay and half in ROOT is not a fact either graph asserts.

Overlays

An overlay is a scratch layer over a committed parent branch: hypotheses go in the overlay, the committed base is never mutated. Two write primitives, one uniform read:

• Create (quipu_overlay_create / POST /overlay/create) registers an overlay-class graph bound once to its committed parent branch (ROOT by default). Idempotent; rebinding to a different parent is an error — the binding is unforgeable.
• Write (quipu_overlay_write / POST /overlay/write) takes one of three ops: assert and retract are graph-scoped writes into the overlay; tombstone marks a specific (e, a, v) from the parent as absent in the overlay’s composed view, without touching the parent.
• Compose (quipu_overlay_compose / POST /overlay/compose) resolves the stack [overlay > parent-branch-root] with a single rule: a triple is present iff asserted and not tombstoned, nearest-overlay-wins. Overlay asserts shadow the parent; overlay tombstones hide parent triples; everything else falls through.
• Governed precedence ("precedence": "governed" on the same tool / endpoint) inverts who wins, for reading a quarantine plane over a governed graph (quipu-e61, adopted from Spanner’s statically-defined-properties-win-over-dynamic rule): the parent’s facts are always present — an overlay value on a same-subject-same-predicate slot the parent claims is suppressed, and an overlay tombstone cannot mask a parent fact (it still masks the overlay’s own contributions). A low-trust plane may extend the governed graph but never alter what it says; promotion out of quarantine remains an explicit governed write, never a precedence flip.

Many tenants can extend the same base independently this way, and a committed read never sees any of them unless the query names the overlay. Overlays are one sanctioned write path for named graphs. POST /episode accepts a graph field for ingestion into a named graph, and POST /knot accepts a graph field under a strict contract: the target must already be a registered committed-class graph (created via graph_create, where authority checks live). An unknown IRI is an error and is never interned — a typo’d plane name must not become a writable target as a side effect of being rejected — and overlay-class graphs are refused (write through overlay_write). The class invariant the earlier “no graph on /knot” refusal protected survives because registration remains the only way to mint a target. The semantic event taxonomy (episode.ingested, entity.*, edge.*, type.new, predicate.new) emits for ROOT-graph commits only; named-graph writes — overlay staging and committed-class targets alike — do not emit it. Gate refusals, however, are recorded as write.refused events for any destination graph (the payload names the graph IRI), and registry changes (shapes.loaded, fork.*) emit their own events.

Datasets

A dataset is a name for an arbitrary set of graphs, queryable as one unit — the reusable form of a FROM a b c clause, so a graph set can be labelled, governed, and handed to another agent. Managed via the quipu_datasets MCP tool or POST /datasets (create / list / show / remove).

curl -s localhost:3030/datasets -X POST \
  -H "Content-Type: application/json" \
  -d '{"action": "create", "name": "http://example.org/datasets/hot",
       "members": ["http://example.org/graphs/a", "http://example.org/graphs/b"]}'

• FROM <dataset-iri> (and the graph query param) expands to the dataset’s members at resolve time; everything downstream reads the expanded set.
• A dataset is never implicitly active — the ROOT-alone default is untouched; you get a dataset’s graphs only by naming it. Creating a dataset with a member that names no registered graph is refused, and the refusal names that member.
• urn:quipu:graph:root is a valid member and reads the default graph, the same as FROM <urn:quipu:graph:root>. A dataset of ROOT plus a named graph is how a stored query reads the default graph AND that graph, without hardcoding either in the query text.
• Members may carry a declared ordering ({"graph": …, "ord": N}); duplicate ranks are refused rather than tiebroken silently. An empty dataset is refused.
• Datasets are mirrored into the meta-graph as quipu:Dataset / quipu:includesGraph facts, so they are queryable and governed like any other fact. Datasets are orthogonal to the overlay branch tree: the branch tree is compose’s resolution root, datasets are overlapping named sets.
• The labels of a query’s active dataset compose across its member graphs — see Graph Labels for how freshness/trust/policy labels fold over the graphs a query actually reads.

Related

• REST API — /query, /export, /overlay/*, /datasets
• MCP Tools — quipu_query, quipu_export, quipu_overlay_*, quipu_datasets
• Graph Labels — labels on graphs and their composition over datasets
• Design doc: docs/design/named-graphs.md

Create and use a named graph through MCP

Use a local scratch store for this recipe. Install the CLI and sibling server, then configure your MCP client with quipu mcp --db ./tutorial.db. Local MCP opens no HTTP listener. A configured protected server needs its existing write credential; an actor field declares provenance and never grants permission. See MCP connection setup.

Each JSON block below is an MCP tools/call parameter object. Send the blocks in order. Inspect isError before reading content; an error is not an empty result. These exact blocks are exercised by the fresh-store acceptance test. The timestamps are sample transaction times; use current UTC in your own work.

1. Create a committed graph

{
  "name": "quipu_graph_create",
  "arguments": {
    "graph": "urn:example:graph:job-search",
    "actor": "urn:example:agent:researcher",
    "timestamp": "2026-10-14T12:00:00Z"
  }
}

Expect created: true and creation containing the original timestamp and declared actor. Repeating create returns created: false and preserves that provenance. An already interned IRI still needs registration.

2. Declare its labels

{
  "name": "quipu_graph_label",
  "arguments": {
    "graph": "urn:example:graph:job-search",
    "timestamp": "2026-10-14T12:00:00Z",
    "actor": "urn:example:agent:researcher",
    "kind": "operational",
    "freshness": "fresh"
  }
}

3. Load the new class vocabulary

{
  "name": "quipu_shapes",
  "arguments": {
    "action": "load",
    "name": "job-search",
    "timestamp": "2026-10-14T12:00:00Z",
    "turtle": "@prefix sh: <http://www.w3.org/ns/shacl#> . @prefix ex: <https://example.org/> . @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> . ex:JobShape a sh:NodeShape ; sh:targetClass ex:Job ; sh:property [ sh:path rdfs:label ; sh:minCount 1 ] ."
  }
}

This loads the vocabulary into the local store; supplying a type name on a write does not create or govern that class. Shape changes on a shared server need that server’s normal schema authority.

4. Check the loaded vocabulary

{
  "name": "quipu_shapes",
  "arguments": {
    "action": "vocabulary"
  }
}

Expect https://example.org/Job in classes. Use this exact class IRI in your RDF.

5. Write one job into the graph

{
  "name": "quipu_knot",
  "arguments": {
    "graph": "urn:example:graph:job-search",
    "timestamp": "2026-10-14T12:00:00Z",
    "actor": "urn:example:agent:researcher",
    "turtle": "@prefix ex: <https://example.org/> . @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> . ex:job1 a ex:Job ; rdfs:label \"Research engineer\" ."
  }
}

6. Query this graph explicitly

{
  "name": "quipu_query",
  "arguments": {
    "graph": "urn:example:graph:job-search",
    "query": "SELECT ?label WHERE { <https://example.org/job1> <http://www.w3.org/2000/01/rdf-schema#label> ?label }"
  }
}

Expect count: 1 and label Research engineer. Omitting graph queries ROOT; it must return no matching job in this fresh store.

7. List registered graphs and their provenance

{
  "name": "quipu_graph_list",
  "arguments": {}
}

Find the exact graph IRI, committed class, operational/fresh labels, and the same creation provenance from step 1. A ROOT row may also be present; compare the target row rather than assuming a total count.

Fix common errors

• Unknown graph / interned but not registered: call quipu_graph_create with the exact graph IRI before quipu_knot. The error includes that call and the equivalent quipu graph create '<iri>' --db <path> command.
• Unknown rdf:type / off-vocabulary class: load a SHACL shape with sh:targetClass matching that exact class IRI using quipu_shapes, then check action: vocabulary before repeating the rejected write. On a shared store, propose the shape through its governed schema lane instead of changing somebody else’s vocabulary without authority. A similarly spelled label or namespace is not a match.
• SHACL validation failure: supply the required label; do not disable validation. The recipe’s Job shape requires rdfs:label.
• Overlay graph: use quipu_overlay_write; committed graph registration does not reclassify an overlay.

Creation provenance records caller-declared metadata. It is not proof that the caller owned the actor IRI. Older or imported graphs may have an unknown actor; repeating create never invents an original creator.

Compose knowledge packs

quipu compose loads verified local share directories or archives into one store, retaining each pack as a named graph and naming their union as a dataset. ROOT remains unchanged, including when validation passes. Composition is an inspection operation; it does not grant foreign content trust.

quipu compose ./operations-pack ./repository-pack \
  --shapes-from ./operations-pack --db composed.db > composition.json

The command returns JSON and exits 0 for an admitted union, 2 for a retained, quarantined union, or 1 for a refusal. Exit 2 means the composition is available for inspection in quarantine, not that no data was written. Integrity and shape-selection errors refuse the whole operation. Internal shares require explicit --destination internal, as on the import path.

Identity and provenance

Exact IRIs denote one entity across packs. Matching labels never merge entities. An explicit owl:sameAs assertion supplies an auditable identity link; consumers can follow it while the original names remain in the source graphs. Blank node identifiers are scoped to the pack even when independent exports both use c14n0.

The result names the dataset and each source graph. Query the dataset explicitly:

SELECT ?item ?name FROM <urn:quipu:composition:HASH>
WHERE { ?item a <https://example.org/Item>; <https://example.org/name> ?name }

For a fact’s source membership, name the source graphs from the result:

SELECT ?pack
FROM NAMED <urn:quipu:composition:pack:FIRST_SHARE_HASH>
FROM NAMED <urn:quipu:composition:pack:SECOND_SHARE_HASH>
WHERE { GRAPH ?pack { <https://example.org/item> <https://example.org/name> "Item" } }

A fact supplied by both packs has two source memberships. The dataset’s RDF union suppresses duplicate triples. urn:quipu:composition:metadata records JSON manifests under urn:quipu:composition:manifest, including source references, share and store identities, transaction anchors, original manifests, attestation status, and validation results. Records describe observed compositions; they are not an automatically maintained validation certificate.

Shape authority and partial snapshots

Without --shapes-from, every input must carry an identical shape bundle. Different bundles are refused with their share IDs and hashes. Explicit selection chooses that pack’s complete bundle for this composition. It never silently unions conflicting constraints or installs foreign shapes as global policy.

Validation examines the union: another pack can supply a required field. Loaded local shapes control admission when present, including when an incoming bundle declares a conflicting policy. Without local shapes, explicit --shapes-from selection authorizes that bundle’s quipu:onViolation "emit" policy. Default identical bundles validate the union but do not implicitly authorize emit admission. Missing policies mean reject; unknown or conflicting values refuse.

Admission parses policy by RDF subject, so compact Turtle, alternate prefixes, comments and string literals cannot route a neighboring reject shape into emit. Both validator graphs preserve all constraints and shared RDF-list dependencies; only inactive independent targets are removed, including implicit class targets. Policy on a nested property does not downgrade its enclosing reject shape. The four core target kinds are supported; custom SHACL-AF targets refuse when emit partitioning is requested. Canonical and legacy annotation IRIs are checked together, so conflicting declarations cannot choose their own precedence.

conforms retains strict SHACL meaning: any diagnostic, including an advisory Violation or Warning, makes it false. Admission uses blocking separately. Emit-policy diagnostics appear in advisory_results; reject-policy Violations still quarantine the union. The report records admission_policy with its source, shape hash and emit authorization. The existing shapes_authority field identifies the selected input bundle.

The report preserves violation counts and counts by source shape. Its results preview contains at most 40 diagnostics; when truncated, complete_results contains every diagnostic and results_total records their count. Types outside the authoritative vocabulary are reported separately as off_vocabulary and also quarantine the union. Neither an admitted union nor an emit policy promotes data to ROOT or grants foreign content trust.

The snapshot vector remains visible. Different source stores’ transaction anchors are incomparable. Mixed dates are permitted and reported; composition does not claim that snapshots were taken together, every referenced entity has arrived, or missing facts represent upstream deletion. Pack selection is explicit. Loading a different snapshot names another composition without replacing an earlier dataset.

Retractions and replay

Reloading a share reuses its source graph rather than refilling it. Attested shares still obey the ordinary signature and nonce-replay checks. A local retraction in that graph survives reload of the same snapshot. Validation on replay examines the current local union, so removing a required field changes the outcome to quarantine. Source graph edits affect every dataset that includes that graph.

A distinct historical snapshot is a separate inspection graph, not a restoration of ROOT or an automatic replacement of the selected dataset. Historical source membership records what a snapshot contained, not whether its facts remain current. Retract in the graph whose view you intend to change.

A stable name per repository

Each composition gets a new dataset name, so an agent has nothing stable to ask for “this repository’s knowledge now”. Repository mode gives it one:

quipu compose --repo scbrown/demo packs/main=./main.pendant packs/ops=./ops.pendant \
  --db store.db

Each input is <pack-key>=<path>. The pack key (its path in the repository, for example) is what makes two commits of a pack the same pack, so it is supplied, never inferred from the bytes. An admitted composition moves two datasets:

• urn:quipu:repo:<repo>:current names the latest admitted snapshot.
• urn:quipu:repo:<repo>:previous names the snapshot before it.

A quarantined composition stays inspectable under its own urn:quipu:repo:<repo>:snapshot:HASH dataset, but it never moves CURRENT. Recomposing the snapshot CURRENT already names moves nothing.

SELECT ?item ?name FROM <urn:quipu:repo:scbrown/demo:current>
WHERE { ?item <https://example.org/name> ?name }

Pack graphs in this mode are scoped to the repository (urn:quipu:repo:<repo>:pack:<key>:SHARE_HASH). Two repositories composing identical bytes therefore get two graphs, and a retraction in one never shows through the other. Older snapshot graphs that neither pointer names are dropped: their facts are retracted and the graph is unregistered, and history stays bitemporal. A graph that another dataset still names is kept and reported under retained_shared.

Local retractions carry forward. Before each composition, statements retracted locally in this repository’s pack graphs are recorded as tombstones for that pack key. They are removed from every later snapshot of the pack before validation, so validation sees the union an agent will actually query. This holds across a version where the statement is absent, a version where it returns, retention pruning and rollback. Blank nodes are renamed per snapshot, so a retraction of a blank-node statement cannot be matched later. That case refuses the composition and names the statement; re-assert it, or give the node an IRI in the pack.

Roll back by moving the pointer:

quipu compose --repo scbrown/demo --rollback --db store.db

This swaps CURRENT and previous, and first applies any tombstone recorded since previous was current. The whole operation is one transaction: a failure at any step leaves both pointers, the graphs and the caches as they were.

Undo a local retraction

Revoke one carried-forward suppression explicitly, without editing SQLite:

quipu compose --repo scbrown/demo --pack-key packs/main \
  --revoke-tombstone '<https://example.org/alice> <https://example.org/name> "Alice" .' \
  --reason 'Undo an accidental local retraction' --db store.db

The statement must be exactly one N-Triples triple, with no blank nodes. A nonblank reason is required. This operation takes no packs and cannot be combined with rollback. It restores only matching, previously asserted composition facts that are retracted in this repository’s owned graphs for the exact pack key, then removes their carried-forward tombstone in the same transaction. The receipt reports revoked and graphs_restored. Repeating a successful reversal returns revoked: false; a missing statement never invents a fact.

Replaying or rolling back an already-stripped graph stays stripped. A tombstone may have removed the statement before that graph was first stored, so there is no historical assertion there to restore. Recovery is a fresh composition from a newly published source-pendant snapshot containing the fact (a distinct share ID), after revocation. Replaying the same stripped snapshot does not refill its graph. The operation never fabricates omitted facts from the requested statement alone.

CURRENT and PREVIOUS do not move, but restored facts become visible immediately in their graphs, including retained older graphs. Any other dataset referencing those same graphs sees the restoration too. Other repositories, other pack keys, unrelated statements and ROOT are unchanged. Recomposition and rollback do not recreate the revoked suppression; a later explicit local retraction can create it again. A failed operation rolls back both restoration and the ledger update.

Deleting a tombstone row by hand does not have these semantics: retracted facts in a retained graph would be harvested again on the next composition.

Pack pointers on first use

A manifest’s kind = "pack" pointers remain declarations at checkout and ordinary composition. A consumer follows only the graph it needs, using share_pointer_load::LazyPacks::use_graph or the native first-use command:

quipu compose --use-pointer urn:project:api \
  --declaration repository.pendant.tar.gz \
  --authority local-policy.pendant.tar.gz \
  --repo-remote https://github.com/example/project.git \
  --pointer-cache ./verified-archives --db ./inspection.db

The receiver supplies the repository remote and local authority. The command runs caboodle packs trust check against that repository and the pointed archive hash before reading the cache or fetching. A missing trust tool or a refused decision stops the operation. Foreign bundles never become global shape policy, and nothing is promoted into ROOT. Use the returned dataset in an explicit SPARQL FROM clause. This command does not move repository CURRENT.

The archive sha256 and the enclosed manifest’s share_id, graph, shapes and query hashes are verified independently. Cache keys use the archive digest; reads reverify the bytes and recheck trust. Cached archives work offline. A corrupt cache entry refuses rather than silently fetching a replacement. Fetch, integrity and validation failures name the requested pointer and leave no partial composition. Nested pointers are reported, not recursively loaded. The download limit is 16 MiB and the expanded archive limit is 64 MiB.

Library consumers supply their own trust and transport callbacks plus an ArchiveCache. Construction performs no network access. Invoke use_graph when a graph is first requested, rather than scanning and following every pointer. DirectoryCache provides atomic native archive writes.

Browser consumers

The explorer wasm bundle exports PointerExplorer. Supply the declaration archive and an authority archive chosen by the receiving application. The separate wasm/explorer/runtime/pointers.mjs helper provides bounded Fetch and optional CacheStorage persistence:

const engine = new PointerExplorer(declarationBytes, localAuthorityBytes);
const cache = await caches.open('project-pointer-archives');
const result = await usePointerGraph(engine, 'urn:project:api', authorize, { cache });
const rows = engine.query(`SELECT ?s ?p ?o FROM <${result.dataset}> WHERE { ?s ?p ?o }`);

authorize(pointer) is the receiving application’s policy decision, such as a Caboodle policy exported by its trusted host. It must return the literal boolean true; the archive cannot supply consent. The helper checks it before cache or network access. Rust checks trust and both integrity layers before composition, using the same implementation as native. Browser requests omit credentials and refuse redirects. Cached archives can be used by a fresh instance offline. This is a read-only named dataset; it does not use the ordinary explorer’s separate ROOT promotion ceremony.

Graph Labels & the Trust Lattice

Implementation status: 🟨 Substantially built. The axes (Freshness, Trust, PolicyClass, Durability, DataKind), the meet/join algebra in src/lattice.rs / src/lattice_kind.rs, label storage (set_graph_label / label_of, the reserved meta-graph, cache columns), dataset labels on the query path, label floors, expiring declarations, and derivation methods are all implemented. Statement-level labels (quipu #73) remain design-only. See docs/design/graph-labels.md for the full design.

Named graphs partition the store, but on their own they cannot say anything about a graph: how current its contents are, how far they should be trusted, or what policy governs them. Every consumer of Quipu was hand-rolling that missing layer differently. Graph labels make it a store primitive: labels on graphs, drawn from ordered value sets, composing under one invariant.

The one invariant: composition never widens

When graphs are combined into a dataset, the composed label may never claim more than any member does. The operator flips direction by axis, but the invariant holds both ways:

• Freshness, trust, and durability compose by meet — a union of graphs is only as fresh, as trusted, and as durable as its weakest member.
• Policy obligations and kinds compose by join — a union of graphs carries the union of their restrictions, so one no-export graph taints the set, and the union of their declared kinds, so a dataset touching an archive graph says so.

The axes

Four things to know about these values:

• Trust is not a hardcoded enum. Trust values are IRIs and the ordering is data: smac:canonical quipu:trustRank 40 ; quipu:inChain smac:ruleTierChain. Ranks are only comparable within a declared chain — comparing across chains is refused, never silently compared as integers.
• Durability answers an owner-facing question the belief axes do not: which facts would be lost if this store were lost? backed is persisted elsewhere, reproducible is re-derivable from a source that still exists, soleRecord means loss is permanent. A derived fact is only as durable as its least durable input, so it composes by meet.
• Nothing is ever synthesized. A producer declares labels; Quipu never observes staleness or infers backed because a backup ran once. Related but distinct: quipu:derivedBy records how to re-derive a fact (system, query, parameters). It is a per-fact value, not a lattice axis — two methods do not meet into a third. derivedBy says how to recover a fact; durability says whether you must.
• Kind is categorical, not ordered. quipu:dataKind declares what sort of data a graph holds — the token space is lexically open ([a-z][a-z0-9-]*), parsed strictly, and never ranked, so it composes by union rather than by weakest member. It also drives fetch-time scope widening (include_kinds) and the deep-freeze lifecycle — see Graph Kinds & Deep Freeze.

Undeclared is not a lattice value

Every pre-existing graph is unlabelled, so the default matters. Defaulting to top would fail-open trust; defaulting to bottom would drag every existing query to the floor. Instead a composed label is a pair: the fold over the declared labels, plus a coverage (full, partial, none) saying how much of the dataset declared anything. An unlabelled graph reads as undeclared, never as a fabricated fresh. Declarations can also expire (set_graph_label_until); past their valid_to they simply become undeclared again.

Labels on the query path

The composed label is a property of the query’s dataset, computed once per query — not per row. A dataset containing a stale graph is labelled stale even if no returned row came from it; conservative cannot overstate. /query and quipu_query responses carry a top-level labels key beside truncated:

{
  "rows": ["..."],
  "truncated": false,
  "labels": {
    "freshness": { "value": "stale", "coverage": "full" },
    "durability": { "value": "soleRecord", "coverage": "partial" },
    "trust": { "value": "smac:canonical", "chain": "smac:ruleTierChain", "coverage": "full" },
    "policy": { "value": ["no-export"], "coverage": "full" },
    "kind": { "value": ["knowledge", "archive"], "coverage": "full" }
  }
}

The key is always present: null means nothing was declared, and a fold refusal (member graphs trusted in different chains) is reported as {"error": …} while the query still returns its rows. Old clients ignore the extra key. Per-row label columns exist only where the graph is already bound per row — under GRAPH ?g, opt-in.

Label floors

An opt-in enforcement floor in configuration:

[quipu.labels]
min_freshness = "fresh"
min_trust_rank = 30
min_trust_chain = "https://quipu.dev/ontology/defaultTrustChain"
deny_policy_tokens = ["no-export"]
deny_data_kinds = ["archive"]

When a dataset’s label falls below the floor, the query is refused, and the refusal names the graph that dragged the label down. Undeclared fails a configured floor — fail-safe at enforcement, honest at reporting. The one deliberate exception is deny_data_kinds, which is a blocklist, not a minimum: an undeclared kind passes, because kind is categorical and failing every unlabelled graph the moment the key is set would be a different (and unasked-for) migration. All keys are unset by default, and unset means zero behaviour change: no query is ever refused by a store that has not configured a floor, and the unconfigured path does no label work at all.

⚠ Label floors are NOT access control. A floor refuses a query; it does not hide rows, and nothing stops a caller who names a graph directly from reading it. aegis:authorityOver gates writes only; a read-side authority check does not exist and is not built here. Presenting trust labels as a confidentiality boundary would repeat the group_id mistake this stack already documents.

One governance consequence worth knowing: labels live as ordinary facts in the reserved meta-graph urn:quipu:graph:meta, so relabelling a graph requires authority over the meta-graph, not over the graph being labelled — otherwise a tenant could relabel itself attested.

Built vs designed

Built: the five axes and the fold, graph-label storage with the RDF meta-graph as source of truth and cache columns checked by quipu doctor labels, dataset labels on the query path, label floors, expiring declarations, durability and derivation. Design-only: statement-level labels (#73) — the same vocabulary attached to individual statements, with downward-only override.

Related

• Named Graphs — the substrate labels attach to
• Graph Kinds & Deep Freeze — the dataKind axis in use
• Configuration — the labels.* floor keys
• REST API — the /query response shape
• Design: docs/design/graph-labels.md

Graph Kinds & Deep Freeze

Implementation status: ✅ Built on the sanctioned surfaces — the quipu:dataKind label axis, GET /graphs, include_kinds on /query, and quipu graph freeze|thaw|list. See docs/design/graph-kinds-and-deep-freeze.md for the full design.

The kind axis

quipu:dataKind declares what sort of data a graph holds — a fifth label axis beside freshness, durability, trust and policy. Categorical, not ordered: a dataset composes to the union of its members’ kinds, so an answer that touched cold data says so in its labels.kind.

Conventioned values (the space is lexically open — [a-z][a-z0-9-]*):

• knowledge — durable semantic content;
• operational — high-churn workflow/run/ticket state, written into time-windowed graphs (e.g. …/shuttle/runs/2026-08);
• identity — principals and verifier registrations, split out so freezing a window never strands the keys that verify its signatures;
• archive — frozen read-only history; set by the freeze operation.

Declare it like any label:

curl -s localhost:3030/graph/label -X POST -H "Content-Type: application/json" \
  -d '{"graph": "urn:app:runs/2026-08", "kind": "operational",
       "timestamp": "2026-08-24T00:00:00Z"}'

[quipu.labels] deny_data_kinds = ["archive"] refuses queries that implicitly compose the named kinds — a blocklist (undeclared passes), not a minimum, and like every floor it is not access control.

Deep freeze

quipu graph freeze <iri> relocates a whole graph’s full history — retracted rows and transactions included — into a read-only archive pack, verifies the copy by content hash, deletes the local rows, and re-attaches the pack. The graph keeps its IRI and stays queryable; its durability genuinely becomes backed. Writes to it are refused, naming quipu graph thaw.

Compose frozen graphs back in, explicitly (silence never widens):

1. GRAPH <iri> or FROM <iri> — by name;
2. FROM <urn:quipu:dataset:frozen> — the auto-maintained dataset of every frozen graph;
3. "include_kinds": ["archive"] on POST /query — by kind, so new frozen windows join automatically.

Known cost: as_of_tx time travel is refused while archives are attached (the pre-existing rule for any attachment); valid-time queries survive. quipu graph thaw <iri> restores the history byte-for-byte and reopens the graph for writes — the pack file stays on disk, and the freeze registry row is closed, never deleted.

Freezing and semantic search

Freezing costs the freezing store nothing here. Freeze deletes the graph’s fact rows; it never touches the vectors table, so the embeddings of a frozen graph’s entities stay in place and semantic search answers as it did before.

The archive carries them too. A freeze pack holds embeddings for the graph’s own subjects, re-keyed by IRI, and both quipu graph thaw and quipu graph import restore them — so a window handed to another store, or thawed into a store rebuilt from packs, arrives with its semantic index rather than needing a re-embed. Freeze and thaw report the count; the restore is idempotent.

Two limits worth knowing:

• A delegated or LanceDB vector backend cannot be enumerated, so nothing can be re-keyed out of it. The freeze still succeeds — relocating history is not a vector operation — but it warns on stderr and stamps vectors_omitted into the pack manifest, so an incomplete archive never reads as “this graph had no embeddings”. A thaw in the other direction refuses: restoring rows into a store whose live backend is not the built-in one would put them where nothing reads them. Run quipu migrate-vectors first.
• An attached archive’s embeddings are not searched from the pack. Vector search reads the local store only, deliberately — one index per question. Nothing is lost by it, because the local rows were never removed.

Governance: Policies, Verdicts & the Write Gate

Implementation status (2026-08-12): ✅ Built — the Phase-A write gate (src/governance/guard.rs, wired through stage_and_guard in src/store/ops.rs), the seven governance/overlay MCP tools (src/mcp/governance.rs), v1 verdict signing (src/signing.rs, src/governance/verdict_facts.rs), authority intersection, and the audit/replay machinery. ⬜ Not built: the hank-side structural-policy projection (Phase B), boundary:"transition" enforcement, the workflow half of require-approval, and everything from §5 of the signing-plane design (shared signing crate, bitemporal key registry, task signing).

Quipu carries a declarative governance vocabulary and an engine that binds it to the write path. A policy is a fact in the graph like any other; whether it enforces is a runtime decision, and every enforced decision leaves a signed, auditable verdict behind.

The vocabulary

An aegis:Policy (shapes/governance.ttl) names four things: what it governs, what compliance means, where it binds, and what happens on failure.

@prefix aegis: <http://aegis.gastown.local/ontology/> .

aegis:todo-needs-ticket a aegis:Policy ;
    aegis:targets  "aegis:CodeComment" ;
    aegis:claim    "ASK { $target aegis:citesTicket ?t }" ;
    aegis:boundary "action" ;
    aegis:effect   "deny" .

• targets — the entity type the policy applies to.
• claim — a SPARQL ASK stating the compliant condition; $target is bound to the entity under evaluation. Satisfied = good.
• boundary — action (pre-edit/pre-write) or transition (workflow step; declared but not yet enforced).
• effect — allow | warn | require-approval | deny | escalate | record.
• appliesTo (optional) — repo-relative path globs scoping where an action-boundary policy binds. Genuinely multi-valued: a policy scoped to three globs carries three values, and a consumer accumulates them rather than keeping whichever arrived first. Absent means unscoped. Declared with rdfs:range only — no rdfs:domain, so the same term reads identically on a future TextRule or Directive.

An optional aegis:evidenceProbe (another ASK: “does evidence exist yet?”) lets the evaluator distinguish unknown from unsatisfied — no evidence is a different fact from failing evidence, and neither is collapsed into the other.

Tripwires: path-boundary policies

A policy carrying aegis:appliesTo and no selector or predicate is a tripwire: touching the path is the crossing, so the claim needs no evidence beyond the action’s own target. shapes/policies/tripwire.ttl ships the catalog — the governed twin of yupana’s local [[yupana.policy.tripwires]], with quipu as the canonical store and yupana holding only a projected cache. Placement follows SARC Table 3, not convenience: the deny wire is hard at the PAG (admissibility is decided before dispatch — the edit must never land), and the throttle wire is soft at the PAA with a declared aegis:backoffFormula (it prices a completed crossing and backs off the actions after it, never the crossing itself). That formula is not optional decoration: under validate_placement the write gate refuses any policy declaring effect "throttle" without an aegis:backoffFormula — a throttle with no backoff is a response nobody can compile, so the consumer records the crossing and applies no throttle, an armed-looking wire that prices nothing. There is no soft-at-the-gate wire — a soft constraint has nothing to price before the action lands. Re-scoping a wire is amending the policy: the write gate treats an appliesTo write as governance-defining and invalidates the cached policy registry.

The write-path gate

The single write choke point is Store::transact_to_graph. Inside the open savepoint — datums staged, nothing committed — stage_and_guard (src/store/ops.rs) hands the pending post-state to the policy guard (PolicyRegistry::build + evaluate_write, src/governance/guard.rs). On a blocking verdict the savepoint rolls back and the write never lands; the store is byte-identical to before the call.

The registry is built once and cached: every active boundary:"action" policy, indexed by target type. A write’s touched entities are intersected with the governed-type set first, so a write touching no governed type runs zero ASKs; the cache invalidates itself when a transaction writes a governance-defining fact. Effects split into blocking — deny, require-approval, escalate block when the claim is unsatisfied (a gate with no approval channel fails closed rather than passing silently; escalate additionally mints an aegis:DecisionRequest for the escalation router) — and advisory — allow, warn, record never block.

Enforcement is opt-in:

[quipu.governance]
enforce_on_write = false   # the default

Default off: existing deployments are unchanged, and turning the gate on is a deliberate configuration act, not a side effect of upgrading. validate_placement (definition-time class↔placement conformance) and enforce_authority (below) are separate flags with the same opt-in posture.

On-demand evaluation: quipu_policy_check

The read-only half. Given a policy IRI (or an inline claim) and a target, it evaluates the claim over the committed graph and returns a Verdict:

{
  "predicate_id": "aegis:todo-needs-ticket",
  "target_ref": "ex:comment-42",
  "outcome": "unsatisfied",
  "evidence_hash": "fnv1a:9c2a41d07be3f118",
  "tier": "committed",
  "verifier": "quipu",
  "verifier_authorized": true,
  "signed": true,
  "signature": "…hex…"
}

outcome is satisfied | unsatisfied | unknown, bound to a reproducible evidence_hash over (predicate, target, valid_at, bound claim) — any verifier re-runs the same ASK over the same committed evidence and must get the same verdict. Checked, not trusted. valid_at/tx make the evaluation as-of.

Verdict signing

Verdicts are attestations, not claims. If the store holds a signing identity (ed25519 via ring, host-file key custody — explicitly v1), it signs the canonical message v1|predicate|target|outcome|evidenceHash|tier|verifier (src/signing.rs). No signing identity means no persisted verdict, never an unsigned one — a bare satisfied fact is forgeable by anyone who can write.

Write-gate verdicts are persisted as bitemporal aegis:Verdict facts (src/governance/verdict_facts.rs), staged during evaluation and flushed after the savepoint resolves — so a denied write still records its verdict, and unknown is recorded rather than skipped. Their evidence hash seals attribution: sha256 over predicate|target|outcome|writer|chain, binding the aegis:attributedWriter and aegis:principalChain into the signed seal. It is deliberately not a hash of graph state, which has no stable serialisation.

Linking a verdict to the judged transaction

The shipped governance shape permits an optional aegis:gatedTx: one xsd:integer greater than or equal to one. It identifies the committed transaction whose delta was judged, not the later transaction that persists the verdict. Transaction IDs are local to their originating store; cross-store audits must retain that store’s provenance.

Refused or rolled-back attempts omit gatedTx. Their attempted transaction row is rolled back, so its provisional ID is not a durable identity and must never be predicted or reused as the link. Use a durable write.refused event identity for a refusal correlation when the producer provides one. This shape does not introduce that event link. Historical verdicts may also omit gatedTx; absence means the transaction join is unavailable, not that the verdict was a refusal. Do not guess a backfill from timestamps or matching predicate/target pairs.

This is the schema contract, not automatic producer support. A producer adding gatedTx must bind it into the signed evidence and verdict identity: changing the judged transaction must change the seal and identity. Otherwise identical outcomes can collapse to one verdict with several transaction IDs, and the link itself is not authenticated. SHACL checks cardinality and datatype; it does not prove that the referenced transaction exists or that the signature binds it.

Replaying a refusal: the denial quarantine

A denied write is rolled back, so its verdict survives and the evidence behind it does not. From the governed graph alone a refusal can only be attested — the rules it cites were in force at the instant — never re-derived, because the post-state the gate judged is gone. The denial quarantine (src/governance/quarantine.rs) keeps that evidence outside the governed graph: two plain tables, not facts, that no SPARQL pattern, search, or fact read can reach. Refused content still never enters the graph.

For each verdict of a refused write, the gate records — while its savepoint still holds the post-state — a hash of the attempted delta (the writer’s datums, canonical, IRIs rather than term ids), a digest of the post-state it evaluated, a digest of the rule set in force, and the transaction the pre-state ended at. The entry is keyed by the verdict and sealed with the store’s signing key. That is the default, digest-only: nothing refused is retained. A graph opted into full retention also keeps the attempted delta itself, sealed.

[quipu.governance.quarantine]
enabled = true                                   # the default
retain_full = ["urn:quipu:graph:root"]          # or ["*"]; default []

quipu audit replay <verdict> rebuilds the store as of the refusal in a throwaway in-memory copy, applies the attempt — the sealed one, or one presented with --delta and checked against the digest first — and runs the real write path with the gate on. A refusal re-derives when the write is refused again with the same outcome, under the same rule-set digest, over the same post-state digest. A later rule change does not move the answer: the replay reads the rules as of the refusal, not today’s. A verdict whose write committed replays from that write’s transaction.

quipu audit quarantine purge erases sealed deltas by graph or by age and keeps each entry’s digests and seal, so the audit can still say “refused, content purged” and can still verify a delta someone presents. Full packs carry the digests (they back verdicts that travel) and never the sealed deltas.

Limits, stated. The post-state digest is over this store’s term ids, so a respaced copy replays its refusals as “post-state differs”. A refusal inside a multi-graph batch judged a post-state that held the batch’s earlier graphs, which no entry carries; its replay reports the divergence. The digest costs one scan of the live facts per denial (never per write) — about 2.4 s per million facts in a debug build.

The Phase-0 root of trust

Trust concentrates in a small, human-owned surface: aegis:VerifierRegistration facts carry each verifier’s name, hex aegis:publicKey, and the predicates it aegis:attests. A human registers a verifier; quipu never self-registers.

• quipu_verifier_authorized — may this verifier attest this predicate?
• quipu_verdict_verify — verify a signed verdict’s fields against the registry. Returns signature_valid, verifier_registered, verifier_authorized, and trusted = signature_valid AND verifier_authorized — the one property a consumer should gate on.

Verification is currently latest-only; the bitemporal key registry (rotation with as-of re-verification) is designed but not built.

Transition signatures at the write gate

Shuttle signs every workflow transition with the performing agent’s ed25519 key over the canonical message shuttle-transition-v1|{run}|{step}|{from}|{to}|{at}|{agent} and exports the signature as an ordinary aegis:signature fact on the aegis:TransitionEvent — re-derivable from the exported facts alone, so consumers can re-check it (shuttle verify). Under [quipu.governance] verify_transitions (default off), quipu re-checks it at the write gate (src/governance/transition.rs): a write landing a TransitionEvent that is unsigned, signed by an agent with no aegis:VerifierRegistration, or whose signature does not verify over the staged fields under any of the agent’s registered keys is refused before it commits — forged and tampered transitions become unwritable rather than merely detectable. The registry read spans every graph (shuttle’s convention keeps registrations in a never-frozen dataKind=identity named graph); protecting the registry itself from unauthorized writes is enforce_authority’s job, exactly as for signed decisions.

Authority over graphs

aegis:Principal facts hold aegis:authorityOver graph IRIs (or *). A call chain’s effective authority is the intersection of every link’s, so delegation only narrows and an empty intersection refuses (src/governance/authority.rs). Gated by enforce_authority (default off) and inert for callers that present no principal chain. This gates writes only — it is not a read-side confidentiality boundary.

The authority reader accepts both legacy and Quechua vocabulary spellings for Principal, principalId, and authorityOver, including mixed spellings. Identical aliases collapse; conflicting identity values grant no authority. Graph grants remain set-valued, and the reader retains its committed root-graph scope. This compatibility does not change principal identities or grant writers.

Audit & replay

The rest of src/governance/ closes the loop after the fact: quipu_audit_check (audit.rs) mechanically checks a recorded trace against the policy spec — coverage, class↔placement, outcome consistency, attribution — deterministically, never an LLM call. denial_replay.rs re-derives one recorded gate decision as of its transaction (see the quarantine above). replay.rs measures whether an advisory rule is ready for promotion to enforcement (liveness, both outcomes, recoverability). router.rs queues require-approval escalations as DecisionRequests with expiry (only an approval permits; a rejection outranks an approval); tree.rs, inventory.rs, and inheritance.rs reconstruct attribution, check dispatch-graph coverage, and detect constraint laundering under delegation.

See also

• MCP tools reference — the seven governance and overlay tools.
• REST API reference — the mirrored HTTP routes.
• docs/design/policy-edit-hooks.md — the write-gate design and its backlog.
• docs/design/signing-plane.md — where signing goes next (proposed).

Post-commit reactions and firing records

shapes/aegis-ontology.shapes.ttl defines aegis:Reaction and aegis:ReactionFiring for Chaski. These describe post-commit or scheduled reactions. Loading the schema does not start an evaluator, install a graph sink, or deliver an alert.

A reaction has one rdfs:label, triggerKind (event or schedule), condition (SPARQL SELECT ?focus), severity (info, warning, critical or page), and string owner. It requests one or more action values: alert, page, bead, or webhook. The existing string properties severity, owner, and schedule are reused.

Event reactions use a comma-separated eventTypes string; scheduled reactions use an ISO-8601 duration string in schedule, such as PT5M. Chaski’s current consumer supports time durations expressed with hours, minutes and seconds. enabled is an optional boolean; Chaski treats omission as enabled. The graph does not assert that default. A single rdfs:comment can explain the rule. SHACL checks the declared field types, cardinalities and enums. The consumer must also validate the trigger-specific configuration and query: the shape alone does not parse SPARQL or duration strings.

A firing records a transition, never each evaluation. It has exactly one firedBy link to a typed Reaction, one IRI focus, and one xsd:dateTime startedAt. Its stable IRI identifies the machine-emitted record; it does not require an rdfs:label. The rule and its durable firing record are BFO continuants, separate from the execution that produced the record. resolvedAt is absent while active and set once via /set when the condition resolves. A failed or timed-out query is unknown and must not resolve an existing firing. A later firing after resolution is a new occurrence. SHACL does not enforce these temporal rules or timestamp ordering.

Stable delivery identity

ReactionFiring optionally carries one string eventId. When present, derive the firing IRI deterministically from (reaction label, eventId) using an unambiguous encoding, for example a hash of a JSON array containing both strings. The event ID identifies an item and transition; including the stable reaction label separates reactions receiving the same event. If an adapter’s event ID does not uniquely identify its focus, it must include that focus in the identity input too. Do not substitute a send-time random ID.

For a Chaski outbox event, take startedAt from the frozen payload’s observed_at, never the retry time. Persist the graph-sink payload before its first send and reuse it unchanged after a crash. Stable identity alone does not provide idempotence when timestamps or descriptions change between attempts. Verify receiver state after an uncertain write; an unchanged response alone is not a presence check. Test send-then-crash replay at the sink. This schema does not itself implement an idempotent receiver or guarantee exactly-once external actions.

For an adapter that evaluates whether work has become unblocked, condition selects candidate WorkItems with aegis:blockedOn; the adapter decides their verdict. State that interpretation in the reaction’s rdfs:comment. Ordinary scheduled transition firings may omit eventId and retain a durable occurrence identity for each transition of the (reaction, focus) pair.

Knowledge Packs

Implementation status (2026-08-12): ✅ Built. src/pack.rs — Manifest, pack, pack_turtle, unpack, verify, content_hash — with the quipu pack / quipu pack --verify / quipu unpack CLI, and the stored-query registry packs draw from (src/store/queries.rs). --space <term-space> on pack export is built too (2026-08-25). Still open: the design’s retrieval-policy block (quipu:defaultDataset / quipu:recommendsFloor) — a pack today carries the graph’s labels but not the fuller policy vocabulary. See docs/design/knowledge-packs.md.

A binary pack is an internal graph artifact: one graph’s current facts, plus the shapes, stored queries, and labels that make it usable, in a single file you can version, hand to another agent or environment, verify, and import. The artifact format is the database format — a pack is an ordinary Quipu SQLite store with a one-row pack_manifest table describing itself.

For publication in a git repository, a pendant is the text share directory (named for the khipu’s pendant cords, each a self-contained record hanging from the primary cord; see Pendants). The artifact was called a qpack before; .qpack names still load for one release. The binary .pendant.db is internal plumbing, not the published artifact. A share is the canonical, line-oriented interchange surface that makes review and three-way history meaningful:

First prepare the store’s identifier-policy catalogue and load the shapes governing its data. These outward-share examples assume both prerequisites are present in the selected store:

quipu share --output graph-share
quipu share --output project-share --group-id project-a --shapes project-shapes --turtle

Every share contains normative, sorted export.nt, a non-empty shapes.ttl, and manifest.json. By default all loaded shape sets are included; repeat --shapes to select a subset. A store with no loaded shapes is refused unless the producer deliberately requests a shapes-free bundle with --no-shapes. The manifest records the stable store id, transaction anchor, graph and shapes hashes, scope, and optional parent-share hash. --turtle adds a derived export.ttl for people; it is not the graph identity. Stored queries registered against the scope travel as a sealed queries.ttl (select with --queries, omit with --no-queries) and install in the receiver’s registry under a pack namespace — see Stored queries. The anchored transaction timestamp—not the wall clock—is used for created_at, so exporting unchanged state with the same options is byte-identical. Use --parent-share sha256:... when continuing a lineage.

Before any bundle is returned or its output directory is published, Quipu evaluates every block-tier InternalIdentifierPattern present in the local ROOT and named graphs against the exact graph, shapes, and optional Turtle bytes. A hit refuses the entire share and leaves no partial directory. The gate never rewrites a match: IRIs are entity identity, so replacing a private-looking IRI would silently create a different graph. Warning-tier rules do not block. Rules must be complete within one graph; statements split across graphs are not combined into a rule. Duplicate rules are checked once. Catalogue location does not change the selected share payload scope.

An empty block-tier catalogue refuses outward sharing: the CLI exits 2 (cannot verify), distinct from exit 1 for a matched identifier and exit 0 for a checked, clean share. Load a catalogue before sharing outward. The explicit --destination internal path remains available for internal transfers.

Remote callers can request the identical artifact without access to the server’s filesystem using POST /share. The response is {"manifest": {...}, "files": {"manifest.json": "...", "export.nt": "...", "shapes.ttl": "..."}}; export.ttl is also present when turtle_view is true. Request fields mirror the CLI options: scope, shapes, no_shapes, parent_share, and turtle_view. An optional max_bytes may lower the server’s 8 MiB response cap. Every string in files is the exact UTF-8 file content, so consumers reconstruct the directory without reimplementing manifest canonicalization, hashes, or share IDs.

JSON-LD is deliberately not a share payload in v1. Quipu’s JSON-LD endpoint is an entity-oriented negotiated view, not a canonical RDF-dataset serializer; adding it would create bytes whose ordering and identity contract are weaker than the sorted N-Triples producer. export.nt remains normative and export.ttl remains the optional human-readable derived view.

What goes in a pack

• Facts — the current facts of the source graph, written through the ordinary transaction path so term ids are correct by construction (a raw row copy would carry the producer’s private id assignment; a pack never does).
• Shapes — named explicitly with --shapes, since shapes are global and carry no graph linkage. The selection is recorded in the manifest.
• Stored queries — named with --queries, so a domain layer ships the competency questions that make it usable on arrival, not just its triples.
• Labels — the graph’s freshness/trust/policy label travels with the pack, so a consumer can compose it without a side channel.
• Vectors (optional, --with-vectors) — embeddings re-keyed by IRI. Restricted to the built-in SQLite vector backend; a delegated or LanceDB backend cannot be enumerated, so the flag is refused rather than silently producing a pack with no vectors.
• The manifest — pack format, name, producer-declared semver, term space, content hash, creation time, source graph, producer identity, and row counts.

Creating a pack

Omit the graph argument to pack the ROOT default graph, or explicitly use urn:quipu:graph:root. The manifest records that IRI and defaults the name to root. ROOT packs contain only current ROOT facts, excluding named graphs and materialized inference graphs. --with-vectors carries embeddings for terms in the pack. ROOT uses its own graph-label row, without borrowing labels from an interned term with the same IRI. Verification and Turtle export use the same scope. Unpacking defaults to ROOT for these packs; --into <iri> selects a named graph.

quipu pack --out root.pendant.db --with-vectors

quipu pack urn:example:graph --out domain.pendant.db --name "domain" --version 1.0.0
quipu pack urn:example:graph --out domain.pendant.db --shapes s --queries q --with-vectors

The output is a single clean file — the build goes through VACUUM INTO, so no -wal/-shm siblings ride along beside the file you actually copy.

--format turtle emits an interop bundle instead: a directory of graph.ttl, shapes.ttl, queries.json, and manifest.json, for consumers that are not Quipu. It is export-only — nothing unpacks it — but it carries the same content hash as the .pendant.db form, because the hash is computed from canonical content, not from the emitted bytes.

Unpacking

quipu unpack domain.pendant.db --into urn:local:domain --db my.db

unpack materializes the pack’s facts into a local graph (defaulting to the pack’s own graph IRI) and installs its shapes and stored queries through the versioned write paths — never an overwrite of registries the consumer already has. The report states what arrived: facts, shapes, queries.

Verification

quipu pack --verify domain.pendant.db

Verification recomputes the pack’s content hash and compares it to the manifest. The hash is sha256 over the lexically sorted, deduplicated N-Triples of the graph plus the packed shapes, queries, and labels — sorted because the store’s own emission order depends on term-id assignment, and the hash must describe the content, not the producer. Two stores holding the same triples hash the same.

This makes the hash the pack’s citable version reference: pin it in an environment, promote the same hash-verified file dev → staging → prod, roll back by re-attaching the prior pack. Never re-pack between environments — that creates a different artifact and defeats the hash as the promotion identity. There are no signatures; verification is integrity, not provenance.

Use cases

• Shipping a distilled derived layer — pack a curated or derived graph with its shapes and competency queries, and hand consumers a verifiable artifact instead of access to the producing store.
• Small, portable subsets — cut a wasm-sized slice of a larger graph for embedded or edge deployment, where a single self-describing file matters.
• Environment promotion — one artifact, one hash, attached identically in each environment.

Built vs designed

Built: quipu pack, quipu unpack, quipu pack --verify, the Turtle interop bundle, vector export on the SQLite backend, the stored-query registry, and --space <term-space> on export — the pack is built in space 0 and shipped through the same respace machinery as quipu db respace, so a consumer can attach it as-is without an id collision (.pendant.db packs only; a Turtle bundle carries IRIs, not term ids, so --space does not apply there). Designed but not yet built: the retrieval-policy block (default-dataset and recommended-floor facts a consumer could SPARQL), and delta/diff packs — v1 packs are whole-layer, read-only artifacts.

Related

• CLI reference — the quipu pack / quipu unpack flags in full.
• docs/design/knowledge-packs.md — the full design, including the retrieval-policy vocabulary and the promotion workflow.

Explore the contributor constellation

Open Explore to follow the ideas behind Quipu into the code. The repository pack includes the vision, source-backed episodes, design decisions, a trust directive, and the book’s chapter order alongside indexed code and docs. The vision remains an aspiration; each decision links to its own evidence and implementation. These narratives are extracted from repository documents, not imported from an operational knowledge graph.

A phone walkthrough

At a 390px-wide viewport:

1. In Knowledge constellation, search for vision, then select Quipu vision.
2. In its card, tap guides: Federation has explicit boundaries.
3. Read the decision and its source excerpt. Tap governs: src/provider/mod.rs to reach the actual indexed code module.
4. Follow another related entity. Each click centers that entity in the map. The card shows its types, with Properties and Provenance disclosures. Read the source opens the repository file; Inspect facts & edit opens its local facts. SPARQL, export and the propose-as-PR flow remain available.

Related entities come from queries against the whole loaded graph. Arrows mark outgoing (→) and incoming (←) links, and every link names its predicate. The list includes entities outside the initial contributor overview, such as types and provenance sources. An engine-truncated answer is explicitly marked incomplete. The URL’s entity parameter identifies the selection: browser back and forward, reloading, or opening that URL in another tab restores it in the map.

The main cord joins five pendant cords: vision/book, decisions/rules, episodes, code, and reading trail. These are deterministic topic/type groups, not inferred Louvain communities. Entity IRIs sort the knots along each pendant; following a link can add entities beyond the initial overview. Drag or use arrow keys to pan; pinch, use the mouse wheel or the zoom buttons to zoom. All clusters fits the reading map; tap a cluster to enter it. At that overview scale, cluster controls replace individual node controls. Overview cords show up to eight actual knots in IRI order at reduced scale. Visible node targets and controls are at least 44 CSS pixels, independent of zoom. The node card and search results provide text navigation without hovering or precise graph taps.

Knot size and relation details

Knot radius is 5 + min(13, 3 × sqrt(degree)) CSS pixels. Degree counts distinct incoming and outgoing (subject, predicate, object) links in the currently loaded map, including newly explored neighbors. It is local view importance, not global PageRank. Selection changes highlighting, never importance size. The on-screen legend states the metric. Geometry is static; no force simulation or animation is needed, and reduced-motion preferences disable transitions.

Click a relation line, focus it and press Enter/Space, or use Relation details in the entity card. The panel names the predicate, subject, and object as full IRIs, with buttons to inspect each endpoint or the predicate itself. Subject provenance properties are labeled as subject-level evidence, not edge provenance.

Fact history, valid time & transaction time shows the receiving store’s assertions/retractions, valid intervals, transaction IDs/timestamps, sources and actors. Relation history filters by the exact predicate and IRI object. Entity history covers its outgoing facts in ROOT, matching this map’s dataset. History is capped at 2,000 facts and explicitly marked incomplete at the cap. It is not an all-graph or producer audit view. A static RDF share does not carry the original producer transaction log: receiver import time must never be presented as original author time. Episode/source properties retain whatever the pack actually states. An older browser bundle without factHistory displays an unavailable message; it never fabricates history from current SPARQL rows. The query and edit paths still wait for the normal native verification ceremony, including saved previews.

Ask the same question with SPARQL

The canned How does the vision guide code? query follows two explicit edges and checks the indexed module’s path. It does not infer that a similarly named file implements a decision.

PREFIX q: <https://quipu.dev/knowledge/>
SELECT ?decision ?module WHERE {
  q:vision q:guides ?decision .
  ?decision q:governs ?module .
  ?module a ?type .
}

Keep the released knowledge current

The release producer runs scripts/build-contributor-knowledge.mjs after Bobbin indexes the repository. Its curated registry is docs/knowledge/contributor-stories.json. Each story names a source passage and code witnesses; generation refuses a missing passage, missing file, or private identifier in the curated text. The book order comes from SUMMARY.md.

The producer includes this projection in its ordinary CONSTRUCT share scope, then adopts shapes, imports and promotes into a fresh receiver. The contributor proof requires all six knowledge classes, four source-backed episodes, and vision → decision → typed code paths. A code-only pack cannot pass that proof. The release workflow ships that same output as its repository pendant asset.

Use just contributor generate to inspect the deterministic projection. QUIPU_BIN=/path/to/quipu just contributor pack /tmp/repository-share runs the full producer and receiver proof. The output directory must not already exist. The page consumes the released artifact when the documentation build stages it; a source change alone does not change the pack already on the site.

The browser’s delta producer uses the same 128 MiB payload budget as its full export, so adding contributor knowledge does not disable proposing an edit. The default remote delta budget remains 8 MiB. During release publication, docs allow missing, not-yet-staged assets for 30 minutes. Once staged, every asset must be published byte-for-byte; beyond the grace a missing asset fails.

SHACL Validation

SHACL (Shapes Constraint Language) lets you define what valid data looks like and enforce it at write time. When an agent or user tries to add facts that violate a shape, Quipu rejects the write and returns structured feedback explaining exactly what’s wrong.

Why Validate?

Without validation, agents can write anything:

hw:korimako hw:cpuCores "lots" .   # Should be an integer
hw:korimako a hw:Host .            # Missing required hostname

With SHACL shapes loaded, Quipu catches these problems before they enter the fact log.

Class targets and subclasses

A sh:targetClass selects instances of that class and of its subclasses, following the data graph’s rdfs:subClassOf edges transitively. For example, if the validation data declares ex:Step rdfs:subClassOf ex:Action, an entity typed only ex:Step must satisfy a shape targeting ex:Action. Cycles and multiple inheritance do not duplicate a focus node within the same shape. This follows SHACL class-based targets.

Target selection leaves asserted data unchanged. It does not manufacture rdf:type ex:Action values for a constraint such as sh:hasValue on rdf:type. An explicit-type requirement still needs an explicit assertion. Subclass declarations present only in the shapes graph are not merged into the validation data by this mechanism. Write vocabulary admission remains a separate check against loaded shapes.

Defining a Shape

A shape declares constraints for a class of entities. Here’s a shape that says “every Host must have exactly one hostname (a string) and at least one cpuCores (an integer)”:

@prefix sh:  <http://www.w3.org/ns/shacl#> .
@prefix hw:  <http://example.org/homelab/> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

hw:HostShape
    a sh:NodeShape ;
    sh:targetClass hw:Host ;
    sh:property [
        sh:path hw:hostname ;
        sh:datatype xsd:string ;
        sh:minCount 1 ;
        sh:maxCount 1 ;
    ] ;
    sh:property [
        sh:path hw:cpuCores ;
        sh:datatype xsd:integer ;
        sh:minCount 1 ;
    ] .

Loading Shapes

CLI

quipu shapes load --name homelab --file shapes/homelab.shapes.ttl --db homelab.db

REST API

curl -s localhost:3030/shapes -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "action": "load",
    "name": "homelab",
    "turtle": "@prefix sh: <http://www.w3.org/ns/shacl#> .\n@prefix hw: <http://example.org/homelab/> .\nhw:HostShape a sh:NodeShape ; sh:targetClass hw:Host ; sh:property [ sh:path hw:hostname ; sh:minCount 1 ] ."
  }'

Listing loaded shapes

quipu shapes list --db homelab.db

Declaring ontology classes and properties

The bundled governance shape set sanctions named ontology resources typed rdfs:Class and rdf:Property. Load that set before an adapter imports its ontology declarations through /knot. These declarations require IRI subjects.

Declaring <urn:example:Task> a rdfs:Class in the data graph does not authorize instances of urn:example:Task. The write vocabulary still comes from loaded shape sets; add and load a shape targeting the intended class before writing its instances. Unknown types continue to be refused.

Demoted derivation records

shapes/demoted-derivation.ttl defines the product evidence schema in http://quipu.local/graph#, matching the truth-maintenance runtime vocabulary. Ship and load this set together with the compatible demotion runtime.

A DemotedDerivation is an IRI identifying an rdf:Statement. It retains exactly one rdf:subject, rdf:predicate, rdf:object, premiseGraph, deriverSource, promotionTx, invalidationTx, and prov:invalidatedAtTime. Subject, predicate and premise graph are IRIs; the object may be any RDF term. The source is a string, transaction IDs are integers at least one, and the invalidation time is an xsd:dateTime.

derivationState must be exactly one string: unsupported or resolved. Resolution preserves the evidence record. Extra annotations are allowed. The shape rejects missing or ambiguous fields and incorrect RDF term kinds. It does not establish atomic demotion, deterministic identity, exclusion from premise evaluation, or authorization to promote; those are runtime guarantees. Loading the shape does not repair data or promote unsupported evidence.

Validation in Action

Recorded text-rule cases

The bundled aegis-ontology shapes allow aegis:mustMatch and aegis:mustNotMatch on TextRule and InternalIdentifierPattern. Each property accepts zero or more xsd:string values: example text that should trigger the rule, or should stay silent, respectively. Existing rules without cases remain valid. IRIs, language-tagged strings and numeric literals are not case text.

Schema validity does not establish enforcement readiness. A readiness checker must require at least one case of each polarity and execute every case through the rule engine against a current projection. Missing cases or indeterminate execution must not pass. These text-only examples do not prove path or repository exemptions; contextual cases require a separate model. Recording cases does not change a rule’s enforcement tier.

Rejected writes

Try to add a Host without a hostname:

quipu knot - --db homelab.db --shapes shapes/homelab.shapes.ttl <<'EOF'
@prefix hw: <http://example.org/homelab/> .
hw:badhost a hw:Host .
EOF

Quipu rejects it with structured feedback:

{
  "conforms": false,
  "violations": 1,
  "issues": [
    {
      "severity": "Violation",
      "focus_node": "http://example.org/homelab/badhost",
      "path": "http://example.org/homelab/hostname",
      "component": "MinCountConstraintComponent",
      "message": "Less than 1 values for hw:hostname",
      "source_shape": "http://example.org/homelab/HostShape"
    }
  ]
}

This feedback is designed for agents — structured JSON with enough detail to fix the problem automatically.

Value sets across writes

A valid delta can still violate a stored upper bound. For example, writing ex:item ex:value "A" and later ex:item ex:value "B" must not bypass sh:maxCount 1 just because each request carries one value.

Write admission checks predicate and inverse-predicate sh:maxCount, sh:uniqueLang true, sh:disjoint, sh:lessThan, and sh:lessThanOrEquals against the staged current facts inside the same SQLite savepoint as the write. The second distinct value is rejected and rolled back. Split writes cannot bypass language-tag uniqueness or comparisons between the stored values of two properties. Reasserting an identical RDF term remains idempotent; retracting the old value and asserting its replacement in one transaction is valid. Historical facts remain available.

This check covers CLI knot --shapes, the knot and SPARQL Update entrypoints, inline episode shapes, conditional writes with loaded shapes, and configured validate_on_write transactions. It preserves each entrypoint’s existing reject/advisory policy. Low-level transactions without explicit shapes or write validation configured do not acquire an implicit shape policy.

Value-set validation uses each destination graph’s own values. ROOT type and subclass context can select targets in a named graph; ROOT property values and unrelated third graphs do not contribute to its sets. The context is bounded to touched subjects and referenced objects, with at most 100,000 facts and 1,024 classes. Exceeding these limits, or encountering another complex value-set property path, refuses admission with cannot verify rather than accepting partial evidence.

Capability and incoming-context obligations use the batch validator’s compiled shape graph. Its deactivation flags suppress obligations for inactive node shapes and their solely dependent properties. A shared property still imposes its obligations when another active shape or its own target reaches it; logical and qualified shape references retain that conservative check. Unsupported active paths still refuse.

Other constraints retain payload validation and contextual type/required-field repair. This is not whole-store conformance checking or automatic revalidation of every dependent node after changing a schema, class hierarchy, or target relation. Standalone validate remains a check of the supplied data only.

Supported Constraints

Quipu supports the full SHACL Core specification via the rudof library.

Dry-Run Validation

Validate data without writing it to the store:

quipu validate --shapes shapes/homelab.shapes.ttl --data data.ttl

curl -s localhost:3030/validate -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "shapes": "@prefix sh: ... shapes turtle ...",
    "data": "@prefix hw: ... data turtle ..."
  }'

Domain shapes in practice

Domain constraints belong to their domain producer. The staged Camayoc domain profiles separate infrastructure, personal media and software production. The worked example explains their compatibility and rollout. The transition retains the existing bundled Aegis shapes until destination publication, pinning, loading and validation have been verified. They cover:

• LXCContainer, ProxmoxNode, BareMetalHost — compute resources
• SystemdService, WebApplication, Database — services
• CommandDiskImpactObservation — one privacy-preserving command/filesystem measurement. diskDeltaBytes is signed: positive values mean space consumed and negative values mean space freed. Command and filesystem identity use canonical classes rather than raw arguments or paths; aggregate counts and quantiles belong in a separate summary entity.
• ConfigFile — optional migration-safe configPath and contentSha256 facts support exact drift lookups. When present, each is single-valued and the digest must be a full lowercase SHA-256 hexadecimal string.
• CiJob and LocalCommand — map a CI job to at most one typed local equivalent, the repository paths it gates, and the command text used to run that equivalent before push.
• Common properties: hostname, ipAddress, memoryMB, cpuCores, dependsOn

An offline check can use the producer-owned file:

quipu validate --shapes ../camayoc/shapes/aegis/homelab-infra.shapes.ttl --data example.ttl

Best Practices

• Load shapes before data — shapes must be present to validate incoming writes
• One shape set per domain — group related constraints (e.g., “homelab”, “code”)
• Start permissive, tighten later — begin with minCount constraints, add datatype checks as your ontology stabilizes
• Use validation feedback — the structured JSON is designed for automated remediation by agents

Episode provenance activities

The shipped shapes/provenance.ttl includes a minimal prov:Activity profile for episode provenance. It requires a string rdfs:label, which the episode producer emits. Body and source fields remain optional so historical episodes remain valid, and multiple retained comments are permitted. This profile does not authorize a new write path or change import/promotion checks. A receiver must load its reviewed shapes and verify the loaded vocabulary before importing activity facts; a source file alone does not establish runtime governance.

Write-time shape pre-parsing uses the batch validator’s fallback base IRI for relative Turtle identifiers, including relative manifest references in shape documents. An explicit Turtle base still takes precedence. This compatibility does not relax cross-write constraint checks or the atomic refusal of invalid post-state data.

Domain shapes in practice

Quipu enforces engine contracts: provenance, historical evaluation, admission, content-bound verdicts, certification, trust roots and single-use nonces. A domain producer defines what a host, a media record or a work item means. Those are separate responsibilities even when the same validator checks both.

The Camayoc domain example stages three domain files:

• homelab-infra.shapes.ttl: hosts, networking, services and storage.
• personal-media.shapes.ttl: people, accounts, libraries and entertainment.
• software-factory.shapes.ttl: crew and software production.

Camayoc records the exact upstream source and each shape’s destination. Existing IRIs remain unchanged. A separate compatibility payload retains the original bytes while the source transition is reviewed. The destination’s union/parity tests detect a lost constraint; class competency queries have populated positive and missing-label negative fixtures. Neither test claims production acceptance.

Vocabulary before custom classes

Quechua’s trim decisions already distinguish reusable governance terms, public replacements and infrastructure-specific vocabulary. Keep those decisions: a domain-specific class does not become a new public Quechua term merely because it moved files. Public replacements are explicit profile changes, not namespace renames or automatic rewrites of existing data.

Work uses the Seeds profile

Seeds owns its work-item profile. Camayoc references its pinned source rather than maintaining another WorkItem gate. New records use schema:Action; historical WorkItem/Bead names remain deprecated compatibility vocabulary. The existing replacement/subclass chain does not itself rewrite stored types.

An iCalendar Vtodo remains a separate node linked through skos:exactMatch, as Seeds’ profile specifies. Do not replace that relation with owl:sameAs or claim that the records share an IRI.

A transition without a validation gap

1. Review and publish the producer’s destination packs and competency queries.
2. Propose exact released source pins through the deployment repository.
3. Load destination bytes before removing original source ownership, preserving the existing loaded-set naming/count contract and classification guard.
4. Revalidate existing data with no new violations and prove the intended alias queries, using the deployment’s bounded, authorized reader.
5. Only then remove compatibility source copies. Retain prior pins and the prior engine artifact for the normal scoped rollback.

This chapter describes the source transition. It grants no load, unload, private data migration or deployment authority. The original Quipu copies remain until the destination gates have been measured.

Warning-first propagation

The source CI compares immutable RDF snapshots, including anonymous constraints, against a revision-scoped term/CQ catalogue. It retains a JSON report and warns about unresolved entries. Read and parse failures remain failures. Gaps become blocking only after the October backfill and a separate enforcement decision. Anonymous node shapes, including the four standard target forms, are compared as a multiset of canonical constraint components. Their report-local key _:anonymous-NodeShapes identifies that collection, not a production IRI. Evidence for it must match the complete collection digest. Blank-node spelling and declaration order do not change it; changed constraints and duplicate components do. Typed node shapes without targets are included as well. An event receiver must deduplicate by exact merge identity and retain uncertain writes for native readback; source CI alone does not create a task or change a pin.

Warning check in the existing CI target

The existing Pre-commit checks job runs the shape-propagation hook on every invocation. Its Python environment pins rdflib 7.6.0, runs the RDF and CI counterexamples, resolves the exact event base and checked-out head, and reads Quechua/Camayoc inputs at fixed commits. Shallow CI checkouts explicitly fetch source history. Execution and input-read errors fail; evidence gaps remain WARN. The complete delimited JSON report is retained in the job log, including source commits and input hashes. This replaces the earlier proposed separate workflow steps and report artifact; the workflow files themselves are unchanged.

For an offline local check, set QUIPU_PROPAGATION_QUECHUA_REPO and QUIPU_PROPAGATION_CAMAYOC_REPO to existing source repositories. That mode reads the pinned Git objects rather than working files, never fetches, and refuses a missing object without falling back to network. With neither set, public source reads have byte and timeout limits. No service credential or shape write is used.

Schema Evolution

Quipu enforces strict ontology rules via SHACL shapes. When an agent writes data that fails validation because the schema is too restrictive or missing a class/property, it can propose a schema change instead of asking a human to edit shapes manually.

The Proposal Workflow

Agent writes data → SHACL rejects it → Agent submits proposal → Approver accepts/rejects

Proposals follow a simple lifecycle: pending → accepted or pending → rejected. Every proposal requires an explicit approver — there is no auto-accept.

Proposal Kinds

MCP Tools

Submit a Proposal

{
  "kind": "shape",
  "target": "PersonShape",
  "diff": "@prefix sh: ... ex:PersonShape a sh:NodeShape ; ...",
  "rationale": "Need email property for contact info",
  "proposer": "agent/data-enricher",
  "trigger_ref": "validation-failure-42"
}

Tool: quipu_propose_schema_change

List Proposals

{ "status": "pending" }

Tool: quipu_list_proposals

Accept a Proposal

{ "id": 1, "decided_by": "reviewer-1", "note": "Looks good" }

Tool: quipu_accept_proposal

When a shape proposal is accepted, Quipu:

1. Validates the Turtle diff is syntactically correct
2. Verifies it parses as valid SHACL
3. Writes the shape to the shapes table
4. Records the approver and timestamp

If the Turtle is invalid, the proposal stays pending and an error is returned.

Reject a Proposal

{ "id": 1, "note": "Too permissive — would allow unconstrained strings" }

Tool: quipu_reject_proposal

CLI

# List all pending proposals
quipu propose list --status pending

# Submit a proposal from a Turtle file
quipu propose submit shape PersonShape shape.ttl --proposer agent/enricher

# Accept
quipu propose accept 1 --note "Approved"

# Reject
quipu propose reject 1 --note "Needs tighter cardinality"

Validation Hints

When quipu_knot rejects data due to SHACL violations, the response includes a hint field pointing to quipu_propose_schema_change. When validate_or_reject fails, the error message includes the same hint. This gives agents a clear remediation path instead of a dead-end error.

Design Notes

• The proposals table uses a text diff column so that SHACL shape diffs and future OWL axiom diffs can coexist. The kind column disambiguates.
• Proposals only mutate shape/ontology definitions — they never touch the EAVT fact store directly.
• Over MCP and REST there is no default approver: accept and reject refuse a request without decided_by. The quipu propose accept|reject CLI takes --decided-by <id> (or --decided-by=<id>); without the flag the CLI records cli:<QUIPU_AGENT or USER>, and with neither set it refuses rather than record an anonymous decision. A flag given with no usable value also refuses; it never falls back to the environment. A capability-based authorization system (quipu.schema.approve) is a future concern.

OWL Ontology Layer

Quipu supports OWL 2 RL reasoning through a built-in ontology engine. OWL ontologies define class hierarchies, property characteristics, and constraints that Quipu uses to materialize inferred facts, and — when owl.validate_on_write is enabled — enforces at write time.

Loading an Ontology

Ontologies are OWL axioms expressed in Turtle format. Load one via the CLI or MCP tool:

quipu ontology load aegis-ontology ontology.ttl --db quipu.db

Or via the MCP quipu_load_ontology tool:

{
  "action": "load",
  "name": "aegis-ontology",
  "turtle": "@prefix owl: <http://www.w3.org/2002/07/owl#> ...",
  "timestamp": "2026-04-13T00:00:00Z"
}

On load, Quipu:

1. Parses the Turtle and extracts OWL/RDFS axioms
2. Persists the ontology in SQLite (like SHACL shapes)
3. Materializes entailments into the fact log

Supported Axioms

owl:TransitiveProperty and owl:equivalentProperty were parsed and counted but not materialized before 2026-08-27 — the same silently-dropped shape rdfs:subPropertyOf had before aegis-qfncf. Loading one reported success and derived nothing.

owl:sameAs: identity comes from your DATA, not from the ontology

Every other axiom in the table is read from the ontology document you load. owl:sameAs is not — it is read from the graph itself, because identity between individuals is asserted as ordinary data (the quipu align verbs and /knot both write it). You do not declare owl:sameAs in an ontology; you assert it about two things, and materialization picks it up:

ex:dolt owl:sameAs ex:doltLan .
ex:dolt ex:hosts   ex:beads .

After materialization ex:doltLan ex:hosts ex:beads is entailed, and the identity itself is closed both ways and through chains: with a sameAs b and b sameAs c, facts about a reach c.

⚠️ Predicates are not rewritten. If you assert owl:sameAs between two PROPERTIES, the identity itself is closed, but facts are not restated under the co-referent property — ex:box ex:hosts ex:svc with ex:hosts owl:sameAs ex:runs does not entail ex:box ex:runs ex:svc. This is OWL 2 RL’s eq-rep-p, and it is not implemented: the rule language (reasoner/ast.rs) can only put variables in argument position, so a rule quantifying over the predicate is not expressible. Use owl:equivalentProperty instead, which IS materialized and is the right axiom for saying two properties mean the same thing. Tracked as the named gap on aegis-yro9m.

Materialization

Materialized facts are written with source = "owl:materialize" into ROOT’s companion inferred graph (urn:quipu:graph:root#inferred, quipu-0b6) — quarantined by placement, composed back in with FROM <urn:quipu:graph:root> FROM <urn:quipu:graph:root#inferred>. When an ontology changes, derived facts can be re-materialized.

Materialization runs to fixpoint across axiom families: a type introduced by rdfs:range feeds the subclass closure of the next pass, and passes repeat until one derives nothing new. Each pass derives only facts not already present, so re-running materialization at fixpoint is a no-op and the report counts stay honest.

Materialization can also stay live: with [quipu.owl] reactive_materialize = true (requires the owl and reactive-reasoner features — release full builds have both), the server re-runs materialization whenever a committed write touches vocabulary the loaded ontologies mention, so the closure extends as members arrive instead of going stale after load. This setting defaults to true; set it to false to disable the per-write materialization cost.

ex:fido a ex:Dog .
ex:Dog rdfs:subClassOf ex:Mammal .
ex:Mammal rdfs:subClassOf ex:Animal .

After materialization, ASK FROM <urn:quipu:graph:root> FROM <urn:quipu:graph:root#inferred> { ex:fido a ex:Animal } returns true — a plain ASK does not, because the entailment lives in the companion, not beside its premises.

Write-Time Validation

Two OWL constraints are enforced at write time by default when built with the owl feature. Set owl.validate_on_write = false only for an explicitly informal deployment. Before adopting new axioms, measure the existing graph: turning an incompatible declaration into live policy can reject future writes that touch historical drift.

Disjoint classes: If ex:Person owl:disjointWith ex:Robot, then an entity cannot be typed as both. Attempting to assert ex:alice a ex:Robot when ex:alice a ex:Person already exists returns a structured error and the write is rolled back.

Functional properties: If ex:ssn a owl:FunctionalProperty, an entity can have at most one current value. A later value supersedes the earlier one while preserving history; two competing values in one batch are rejected because the write provides no ordering.

Both reject the whole transaction: the constraint runs inside the write’s savepoint, so a violating batch commits nothing. Violations are reported together rather than one per round-trip.

Constraints are evaluated against the union of all loaded ontologies, and a load or remove through POST /ontology takes effect on the next write.

Feature Flag

OWL support is behind the owl feature flag:

cargo build --features owl
cargo test --features owl

The shacl feature continues to work independently.

The Reasoner

Raw facts tell you what is. The reasoner tells you what follows.

Quipu’s reasoner is a stratified Datalog engine that reads the EAVT fact log, applies rules, and writes derived facts into the store. Derived facts are quarantined by placement (quipu-0b6, 2026-08-27): they live in the premise graph’s companion inferred graph — <graph>#inferred, with ROOT’s at urn:quipu:graph:root#inferred — never beside the facts they were derived from. A plain query sees asserted facts only; a query that wants the closure composes it explicitly:

ASK FROM <urn:quipu:graph:root> FROM <urn:quipu:graph:root#inferred>
    { <traefik> <runsOn> <korimako> }

Within the companion, derived facts behave like any other fact — SPARQL, SHACL, time travel all work — their source tag traces to the rule that produced them, and the graph itself carries aegis:sourceKind "inferred" and a quipu:derivedAsOfTx freshness note (the premise-side transaction head the closure last reflected). The #inferred suffix is reserved: external writes to a companion are refused, so entailments cannot be forged by hand. Pre-regime stores move their legacy-placed derivations across with quipu db migrate-inferred.

Why Derive Facts?

Consider a homelab with containers running on hosts. You’ve recorded:

traefik  runsOn  webproxy
webproxy runsOn  korimako

A human reads this and concludes “traefik transitively runs on korimako.” But SPARQL doesn’t know that unless you either:

1. Query-time: write a property path (runsOn+) every time you ask
2. Write-time: materialise the transitive closure once and query it directly

Option 1 works for simple cases. But as your graph grows — services depending on packages, packages installed in containers, containers running on hosts — the property paths get unwieldy, slow, and duplicated across queries. Option 2 is what the reasoner does: derive the facts once, keep them fresh, and let every query benefit.

Rules as Horn Clauses

A rule says “if these conditions hold, then this fact is true”:

runsOn(?svc, ?host) :- runsOn(?svc, ?container), runsOn(?container, ?host).

Read this as: “if service S runs on container C, and container C runs on host H, then service S runs on host H.” The part before :- is the head (what gets derived). The parts after are the body (what must already be true).

Rules in Quipu are written in Turtle files using a simple vocabulary:

ex:runs_on_transitive a rule:Rule ;
    rule:id "runs_on_transitive" ;
    rule:head "runsOn(?svc, ?host)" ;
    rule:body "runsOn(?svc, ?container), runsOn(?container, ?host)" .

The head and body are string literals that the reasoner parses. Bare predicate names like runsOn are expanded using a configurable prefix, so you don’t need to write full IRIs inside the rule strings.

Stratification: Layered Evaluation

When rules depend on each other, the reasoner needs to evaluate them in the right order. This is called stratification.

Consider two rules:

dependsOn(?a, ?c)  :- dependsOn(?a, ?b), dependsOn(?b, ?c).
affects(?pkg, ?svc) :- installedIn(?pkg, ?c), runsService(?c, ?svc).

The first rule is self-recursive — it reads and writes dependsOn. The second reads installedIn and runsService (which no rule produces) and writes affects. These rules are independent and could run in either order.

The stratifier builds a dependency graph between predicates and groups rules into strata (layers):

• Stratum 0: Base facts — predicates that appear only in rule bodies (installedIn, runsService). No rules to evaluate here.
• Stratum 1: Rules that only depend on base facts (affects).
• Stratum 2: Rules that depend on stratum 1 results.
• And so on.

Rules within the same stratum can be positively recursive (like transitive dependsOn). The evaluator handles this with semi-naive iteration: it keeps applying the rule until no new facts are derived, using only the newly-derived facts from the previous round to avoid redundant work.

What the stratifier won’t allow is a negation cycle — rule A negates a predicate that rule B produces, and rule B negates something rule A produces. This would make evaluation non-deterministic, so the reasoner rejects it at load time with an error naming the offending predicates.

The Evaluation Cycle

Each time the reasoner runs, it performs a full re-derive-and-diff:

1. Stratify the ruleset (this is cheap — just graph analysis)
2. Load the current world: read all relevant facts from the store
3. Evaluate each stratum in order, running rules to fixpoint
4. Diff each rule’s new derivations against its old ones
5. Write asserts for new facts, retracts for stale ones

Step 4 is the key insight. Rather than tracking which base facts changed and propagating deltas (truth maintenance), the reasoner re-derives everything and compares. At the target scale of ~50K facts, this is fast enough to complete in milliseconds and dramatically simpler to get correct.

Every derived fact is written through Store::transact() with a source tag like reasoner:depends_on_transitive, so you can always tell which rule produced a fact and when.

Reactive Evaluation

Running quipu reason manually works, but you’d have to remember to run it after every change. Reactive evaluation automates this: the reasoner registers as a TransactObserver on the store and fires automatically after every commit.

When a transaction lands, the reactive reasoner:

1. Checks which predicates changed
2. Finds the rules whose bodies reference those predicates
3. Follows the dependency chain to find transitively affected rules
4. Re-evaluates only the affected strata
5. Writes any new asserts or retracts

This means derived facts stay fresh without explicit invocation. Add a new runsOn edge, and the transitive closure updates in the same transaction boundary.

The reactive reasoner is smart enough to skip its own output — when it sees a transaction with source = "reasoner:...", it doesn’t re-trigger. This prevents infinite loops.

Speculate: “What If?” Queries

Sometimes you want to explore hypothetical changes without committing them. The speculate() API does exactly this:

#![allow(unused)]
fn main() {
let report = store.speculate(&hypothetical_datums, timestamp, |store| {
    // Inside here, the store contains the hypothetical facts.
    // Run the reasoner, query the results, whatever you need.
    evaluate(store, &ruleset, timestamp)
})?;
// Here the hypothetical facts are gone — the store is unchanged.
}

Under the hood, speculate() opens a SQLite savepoint, applies the hypothetical facts, runs your closure, then rolls back. The store is never modified. This lets you answer questions like:

• “What would change if I remove this package from this container?”
• “If korimako goes down, which derived dependencies break?”
• “What’s the blast radius of upgrading this library?”

Provenance: Tracing Derived Facts

Every derived fact carries metadata that traces it back to its source:

You can query derived facts by their provenance:

PREFIX ont: <http://aegis.gastown.local/ontology/>

SELECT ?entity ?attr ?value
WHERE {
  ?entity ?attr ?value .
  # Filter to only reasoner-derived facts
  FILTER(STRSTARTS(STR(?source), "reasoner:"))
}

Or from the Rust API, filter on the source field of returned facts.

The datafrog Engine

Under the hood, evaluation is powered by datafrog, a ~1500-line Rust crate used by the Rust compiler itself for borrow checking. It implements semi-naive evaluation with no runtime dependencies, no services to manage, and no allocation overhead worth measuring at homelab scale.

You never interact with datafrog directly — it’s an implementation detail. The reasoner compiles your Horn clause rules into datafrog join plans and runs them inside while iteration.changed() loops.

What’s Next

• The Rule Builder — write your first rules
• Reasoner Reference — rule syntax, CLI, API, errors
• Impact Analysis — put the reasoner to work

Four-valued rule answers

rule-query reads two explicit evidence predicates for one grounded claim. It does not change SPARQL ASK, Datalog negation-as-failure, or materialization. The support bits are independent:

Only complete scoped reads can establish neither. A failed read, missing purpose profile, cap, invalid judgment, or unsupported scope produces status: unknown with truth: null. Transport failures are also UNKNOWN to a consumer. A successful health check cannot establish evidence completeness. Configured ROOT label floors remain enforced; a quality refusal is UNKNOWN, not a filtered empty evidence set. Label floors are not access control.

Request and interfaces

CLI: quipu rule-query request.json --db existing.db. HTTP: POST /rule_query. MCP: quipu_rule_query. All use the same native query implementation and response types.

{
  "subject": "urn:claim",
  "positive_predicate": "urn:supported-by",
  "negative_predicate": "urn:refuted-by",
  "object": {"iri": "urn:evidence"},
  "judgment_policy": "urn:policy:referee",
  "witness_limit": 64
}

Version 1 supports IRI and plain-string objects ({"str":"text"}), current primary ROOT only. Predicates must differ. IRIs must be absolute. Unknown fields, named graphs, temporal selectors, and unsupported term variants refuse instead of selecting another scope. Attached/composed stores are unsupported. The CLI opens an existing database read-only and does not create or migrate it. Only ROOT assertions participate. The normal reasoner/OWL companion inferred graph is not folded into this scope, and the query does not run an engine or certify derived closure. Use an explicitly composed SPARQL dataset when that different scope is required.

CLI and direct HTTP JSON decoding reject duplicate fields. MCP arguments have already become a JSON object in the upstream protocol parser; this tool cannot recover duplicate keys discarded before its invocation. All adapters reject undeclared fields in the object they receive.

Response and completeness

The protocol is quipu.rule-answer/v1. A complete response contains evidence and judgment. Evidence includes typed truth, positive_supported, negative_supported, positive/negative witness arrays, stable store_id, transaction watermark, ROOT graph IRI, and scope current_primary_root_all_physical_assertions. claim_context binds the exact grounded claim, its digest, and the expected judgment policy to the response, so retained results do not depend on an out-of-band request to identify what was checked.

Each witness retains the asserting transaction, valid-from spelling, and nullable source. Sources are historical or caller-declared metadata, not authenticated authority. Physical source owners and legacy string representations participate; the witness cap (1–256 per side) is conservative across them. Exceeding it yields UNKNOWN, never a truncated answer. A missing source remains explicit. Metadata is also bounded before loading strings: 16 KiB per field and 64 KiB per support side. Exceeding either byte bound yields UNKNOWN.

Support and judgment reads share one SQLite read transaction. Reads do not intern missing terms, materialize facts, admit verdicts, or modify the ledger. Witnesses and admitted verdict identifiers have deterministic order. Removing one side of both leaves the other; unrelated claims are unaffected.

Every response says action_authority: not_granted. There is no boolean conversion. Before adopting this answer in a boolean consumer, define and review an explicit policy for conflict, neither, deferral, and UNKNOWN.

Separate judgment disposition

Judgment is none_recorded, deferred, or resolved. It is not a fifth truth value. none_recorded means absence from the complete supported current ledger scope, not absence of judgments elsewhere. An unresolved or unverifiable ledger is UNKNOWN. Deferral and resolution preserve the support bits, including both. The response names the judgment scope current_root_records_with_retained_marker_history. Retained historical markers locate withdrawn or altered judgments; retracting a marker cannot turn a deferral into none_recorded. Those records must still verify in their current state or the answer is UNKNOWN. This is not a certificate of history outside the retained primary store, and it does not provide historical snapshot selection.

The purpose profile in shapes/rule-answers.ttl targets only Decisions carrying http://quipu.local/rule#judgmentClaim. It reuses the governed Decision class; legacy Decisions outside that marker remain outside the profile. The reviewed profile must be loaded as rule-answers with exact source bytes before the query can establish judgment completeness. Source presence alone does not load it. Normal schema review and delivery are required; this query never promotes it.

The marker is SHA256 (lowercase hex) of UTF-8 JSON serialized in this field order: subject, positive_predicate, negative_predicate, object, graph. The graph is urn:quipu:graph:root; object uses the request’s externally tagged IRI/plain-string form. Native serialization defines the exact escaping. This is not a claim of JSON Canonicalization Scheme conformance. Policy and witness cap are excluded, so a record with a mismatching policy is detected rather than disappearing into absence.

The Decision’s rdf:value is strict quipu.rule-judgment/v1 JSON with protocol, the full claim above, named authority, nonempty reason, disposition (deferred/resolved), and nullable predecessor. The existing decisionPolicy must match the request. Resolution’s predecessor names the earlier admitted verdict and exact decision_digest (sha256:...). Earlier records remain. The existing Decision carrier also retains outcome: approve, by equal to the named authority, and evidenceHash: sha256:<claim-digest>. Its ordinary approve option endorses the sealed disposition record. These fields satisfy the existing Decision shape; the new purpose profile does not replace it.

Only an existing admitted sealed Decision counts: the normal seal verifier checks content, signature, historical registered HumanTier policy authorization, expiry at admission, and the native nonce-spend/verdict transaction binding. The named authority must match that verifier. The admitted outcome must be approve; deferred/resolved comes from the sealed JSON, never from an unsealed label. A copied signature or caller’s authorization assertion cannot supply this proof. No signer registration or authority policy is added.

The reader bounds records, entity bytes and references before invoking the seal verifier. The purpose profile supports scalar sealed Decision fields, avoiding unbounded blank-node CBD traversal. Unsupported fields, missing predecessors, tampering, mismatched policy/claim/authority, orphan resolution, and competing lifecycle heads yield UNKNOWN. Version 1 supports one deferral and its retained resolution, not arbitrary judgment histories or reopening.

Standards comparison

RIF-FLD Second Edition, sections 3.2 and 3.6 permits multiple truth values and distinguishes symmetric negation from NAF. The two-bit wire envelope here is an implementation contract, not an asserted RIF dialect or a RIF-prescribed JSON format.

LegalRuleML 1.0, sections 4.2.1 and 4.3.4 discusses conflicting defeasible conclusions and named authority metadata. This foundation reports both supports; superiority and defeasible adjudication are separate. Named metadata is distinct from local seal authorization. Neither standard prescribes this envelope or its judgment lifecycle.

Embeddings and Semantic Search

Quipu answers two different kinds of question. Lexical retrieval (SPARQL, CONTAINS, exact match) needs nothing but the fact log. Semantic retrieval (/context, quipu_hybrid_search, /search) needs vectors, and vectors need an embedding provider you configure yourself.

Automatic embedding is enabled by default when a provider is configured. No model is downloaded automatically. Without model and tokenizer paths, lexical graph operations still work and the loader reports that semantic indexing is unavailable. Set auto_embed = false to disable automatic vector writes. This does not disable model initialization, explicit semantic queries, or existing import identity resolution, which may also use the provider.

Writes and staged imports

Native CLI writes (knot, ingest, episodes) and server writes use the configured provider. A share import indexes eligible, uniquely owned entities in its staging graph. It does not adopt the graph into ROOT or turn on named-graph semantic search. Explicit search scope and search policy still apply.

Import responses include embedding.state, candidate/indexed counts, the local provider recipe when available, and an explanatory message. ready certifies indexing for eligible staged entities; partial preserves entities already owned by ROOT or another graph. pending, unavailable, failed, disabled, external, and quarantined must not be described as searchable completion. Vector-index inference uses bounded batches outside the server’s global writer lock. Existing import identity resolution remains a separate admission step; this indexing status does not certify that step’s lock latency.

A share may declare manifest.embedding with an ONNX basename, model_sha256, tokenizer_sha256 (lowercase SHA-256), and dimension. These fields participate in the share identity. The native provider hashes its actual files and validates the model output dimension. Import with an available mismatched provider refuses before staging. Legacy shares without this recipe remain importable; local indexing does not attest which model the publisher intended. Re-importing with a real provider recomputes eligible vectors instead of treating matching text as proof of model identity.

Existing graph data can still use the explicit startup --embed-backfill or bounded POST /embed_backfill_graph operations when needed.

Browser explorer boundary

The explorer uses its separate JavaScript ONNX adapter and self-hosted model assets. It loads the runtime on the first semantic query and rebuilds its in-memory vectors when the ROOT label/comment snapshot changes. It does not copy staged named graphs into that index. Native import readiness does not certify browser indexing or browser model-byte identity; the current browser adapter does not validate manifest.embedding against its JavaScript model. A loaded pendant alone must not be presented as browser semantic readiness.

Configuring a provider

Two things are required, and having one without the other is the common failure:

1. The runtime. Build with --features onnx. This supplies the ONNX runtime only. It does not supply a model, and a build with the feature on is not a build that can embed.
2. A model on disk, plus the paths to it in .bobbin/config.toml:

[quipu.embedding]
auto_embed = true
model_path = "models/all-MiniLM-L6-v2/onnx/model.onnx"
tokenizer_path = "models/all-MiniLM-L6-v2/tokenizer.json"
dimension = 384

The model files are fetched separately (for example from the sentence-transformers/all-MiniLM-L6-v2 repository on Hugging Face). Sandboxed environments may not have network access to a model host, in which case the files have to be provisioned into the image or volume ahead of time.

dimension must match the model. Both model_path and tokenizer_path must be set. A partial or invalid configuration is an error; omitting both produces a visible unavailable status. The same setup is used by native CLI loaders and the server.

Telling whether it worked

Three signals, in the order you will meet them.

At startup, a loaded provider announces itself:

embedding provider ready (dim=384, auto_embed=true)

--embed-backfill is fatal when it cannot run. The flag is an explicit request for a capability, so a server that cannot honour it exits non-zero rather than starting up without it. The error names the configuration it needs. Drop the flag if you deliberately want to serve without embeddings.

Every retrieval response carries its own status. /context, quipu_unified_search, and quipu_hybrid_search all report:

{
  "entities": [],
  "summary": {
    "total_entities": 0,
    "direct_hits": 0,
    "embeddings": { "configured": false, "embedded_entities": 0 }
  }
}

Read it as:

That last row is the point of the field: without it, an empty entities list means either “nothing matched” or “this was never going to work”, and the two are indistinguishable from the response alone.

What degrades without a provider

Only the semantic half. Everything lexical keeps working:

• Works: SPARQL (including exact-match grounding), /query, /knot, /context text search, link expansion, SHACL, the reasoner.
• Empty or refused: vector similarity in /search and quipu_hybrid_search, the Semantic relevance hits inside /context.

quipu_hybrid_search called with a query string and no provider returns an error naming the missing configuration, rather than an empty result set. You can also bypass the provider entirely by passing a pre-computed embedding array.

SPARQL from Zero

This tutorial teaches SPARQL using a concrete homelab dataset. Every query has sample data, the query itself, and the results table — so you can follow along by loading the data into Quipu and running the queries yourself.

The Sample Dataset

Save this as homelab.ttl:

@prefix hw:   <http://example.org/homelab/> .
@prefix xsd:  <http://www.w3.org/2001/XMLSchema#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix rdf:  <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .

# --- Hosts ---
hw:korimako      a hw:Host ;
    rdfs:label      "korimako" ;
    hw:hostname     "korimako.example" ;
    hw:cpuCores     "8"^^xsd:integer ;
    hw:memoryMB     "32768"^^xsd:integer ;
    hw:role         "hypervisor" .

hw:palau      a hw:Host ;
    rdfs:label      "palau" ;
    hw:hostname     "palau.example" ;
    hw:cpuCores     "4"^^xsd:integer ;
    hw:memoryMB     "16384"^^xsd:integer ;
    hw:role         "storage" .

hw:yap        a hw:Host ;
    rdfs:label      "yap" ;
    hw:hostname     "yap.example" ;
    hw:cpuCores     "4"^^xsd:integer ;
    hw:memoryMB     "8192"^^xsd:integer ;
    hw:role         "edge" .

# --- Services ---
hw:traefik    a hw:WebApp ;
    rdfs:label      "traefik" ;
    hw:runsOn       hw:korimako ;
    hw:port         "443"^^xsd:integer ;
    hw:dependsOn    hw:pihole .

hw:pihole     a hw:Service ;
    rdfs:label      "pihole" ;
    hw:runsOn       hw:korimako ;
    hw:port         "53"^^xsd:integer .

hw:grafana    a hw:WebApp ;
    rdfs:label      "grafana" ;
    hw:runsOn       hw:korimako ;
    hw:port         "3000"^^xsd:integer ;
    hw:dependsOn    hw:prometheus .

hw:prometheus a hw:Service ;
    rdfs:label      "prometheus" ;
    hw:runsOn       hw:palau ;
    hw:port         "9090"^^xsd:integer .

hw:minio      a hw:Service ;
    rdfs:label      "minio" ;
    hw:runsOn       hw:palau ;
    hw:port         "9000"^^xsd:integer .

hw:nginx      a hw:WebApp ;
    rdfs:label      "nginx" ;
    hw:runsOn       hw:yap ;
    hw:port         "80"^^xsd:integer ;
    hw:dependsOn    hw:minio .

# --- Type hierarchy ---
hw:WebApp     rdfs:subClassOf hw:Service .

Load it:

quipu knot homelab.ttl --db homelab.db

1. Your First Query: SELECT

A SPARQL query matches patterns against the graph. The simplest pattern is a single triple with a variable:

SELECT ?host
WHERE {
  ?host a <http://example.org/homelab/Host> .
}

This says “find every ?host that has type hw:Host.” The a keyword is shorthand for rdf:type.

Run it:

quipu read "SELECT ?host WHERE { ?host a <http://example.org/homelab/Host> }" \
  --db homelab.db

2. Multiple Patterns: JOIN

Add more patterns to narrow results. Patterns in the same WHERE block are joined — every pattern must match:

SELECT ?host ?cores
WHERE {
  ?host a <http://example.org/homelab/Host> .
  ?host <http://example.org/homelab/cpuCores> ?cores .
}

3. Using Prefixes

Full IRIs are verbose. SPARQL supports PREFIX declarations (without the @ and trailing . that Turtle uses):

PREFIX hw: <http://example.org/homelab/>

SELECT ?host ?cores
WHERE {
  ?host a hw:Host .
  ?host hw:cpuCores ?cores .
}

The results are identical. Use prefixes in every query from here on.

4. FILTER: Narrowing Results

FILTER applies conditions to bound variables:

PREFIX hw:  <http://example.org/homelab/>
PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>

SELECT ?host ?mem
WHERE {
  ?host a hw:Host .
  ?host hw:memoryMB ?mem .
  FILTER(?mem > 10000)
}

String filters

PREFIX hw: <http://example.org/homelab/>

SELECT ?svc ?label
WHERE {
  ?svc a hw:Service .
  ?svc <http://www.w3.org/2000/01/rdf-schema#label> ?label .
  FILTER(CONTAINS(?label, "pi"))
}

Available filter functions: =, !=, <, >, <=, >=, &&, ||, !, BOUND(), CONTAINS(), REGEX(), LCASE(), isIRI().

5. OPTIONAL: Left Joins

Not every service has a dependsOn edge. OPTIONAL includes the match if it exists, but doesn’t exclude the row if it doesn’t:

PREFIX hw: <http://example.org/homelab/>

SELECT ?svc ?dep
WHERE {
  ?svc a hw:Service .
  OPTIONAL { ?svc hw:dependsOn ?dep . }
}

Services without dependencies appear with an empty ?dep column.

6. UNION: Combining Patterns

UNION matches rows from either branch:

PREFIX hw: <http://example.org/homelab/>

SELECT ?thing ?label
WHERE {
  {
    ?thing a hw:Host .
    ?thing <http://www.w3.org/2000/01/rdf-schema#label> ?label .
  }
  UNION
  {
    ?thing a hw:WebApp .
    ?thing <http://www.w3.org/2000/01/rdf-schema#label> ?label .
  }
}

Returns all hosts and web apps.

7. ORDER BY, LIMIT, OFFSET

Sort and paginate results:

PREFIX hw: <http://example.org/homelab/>

SELECT ?host ?mem
WHERE {
  ?host a hw:Host .
  ?host hw:memoryMB ?mem .
}
ORDER BY DESC(?mem)
LIMIT 2

OFFSET 1 LIMIT 1 would skip korimako and return only palau.

An explicit ORDER BY … LIMIT k OFFSET n retains the best k + n solutions when only column projection separates the limit from the sort and keys are constants or consistently typed variables. Mixed incomparable values, non-finite numbers, and computed keys retain the full-sort path. Response-provenance columns also keep the full relation until projection, so metadata present only outside the requested page cannot disappear from headers. It still evaluates the complete input: this optimization does not push a scan limit through filters, joins, DISTINCT, or aggregates. Equal sort keys preserve input order, and each sort expression is evaluated once per solution.

Native complete sorts above 4,096 input rows use private temporary-file runs; smaller sorts retain the in-memory path. The existing 65,536-key-entry and 8 MiB retained-key guards are unchanged. Spill runs use a 2 MiB key budget, at most 128 initial runs, a 1 MiB encoded-record limit, and a cumulative 256 MiB write quota including merge passes. Files contain evaluated keys and row positions, are private to the process, and are removed when closed. Disk errors, quota exhaustion, oversized keys, and deadlines return errors; they never return a silently shortened sorted result. WebAssembly keeps the explicit in-memory refusal because it has no native temporary-file backend.

These limits bound sorting keys and temporary storage. Earlier query operators may already have materialized the input rows, so they are not a bound on total query memory. A small LIMIT also cannot make an expensive input scan cheap.

8. Aggregates: COUNT, SUM, AVG

Group and aggregate with GROUP BY:

PREFIX hw: <http://example.org/homelab/>

SELECT ?host (COUNT(?svc) AS ?serviceCount)
WHERE {
  ?svc hw:runsOn ?host .
}
GROUP BY ?host
ORDER BY DESC(?serviceCount)

Total resources

PREFIX hw: <http://example.org/homelab/>

SELECT (SUM(?cores) AS ?totalCores) (SUM(?mem) AS ?totalMem)
WHERE {
  ?host a hw:Host .
  ?host hw:cpuCores ?cores .
  ?host hw:memoryMB ?mem .
}

HAVING: Filter on aggregates

PREFIX hw: <http://example.org/homelab/>

SELECT ?host (COUNT(?svc) AS ?n)
WHERE {
  ?svc hw:runsOn ?host .
}
GROUP BY ?host
HAVING(?n > 1)

9. RDFS Subclass Inference

Remember that hw:WebApp rdfs:subClassOf hw:Service. A constant type form infers; a variable type form does not. The two spellings answer different questions, and the response says which one you got.

PREFIX hw: <http://example.org/homelab/>

SELECT ?svc
WHERE {
  ?svc a hw:Service .
}

This returns every service including those asserted only as hw:WebApp, because a constant type form is expanded over rdfs:subClassOf. Quipu’s formal default is reasoning-on.

Two spellings, two questions

# INFERS — a constant type is expanded over rdfs:subClassOf.  -> 6
SELECT (COUNT(DISTINCT ?s) AS ?n) WHERE { ?s a hw:Service }

# ASSERTED ONLY — a VARIABLE type plus a filter is not expanded.  -> 3
SELECT (COUNT(DISTINCT ?s) AS ?n) WHERE { ?s a ?t . FILTER(?t = hw:Service) }

On this tutorial’s dataset that is 6 against 3: three entities are asserted hw:Service (pihole, prometheus, minio) and three are asserted hw:WebApp (traefik, grafana, nginx), which the constant form folds in.

⚠️ A hit on the constant form does not prove direct typing. An entity typed only as hw:WebApp satisfies ?s a hw:Service. If you are checking that something carries a type — a governance gate, an ingest read-back — the constant form will pass on a subclass and tell you nothing was wrong. Use the variable form plus a filter, or read the marker below.

The explicit path form remains available and is unaffected by the default:

SELECT (COUNT(DISTINCT ?s) AS ?n) WHERE { ?s a/rdfs:subClassOf* hw:Service }

The marker: what was folded in

Ambiguity here is expensive: both spellings return HTTP 200 and both counts are individually plausible, so a number answering the other question does not look wrong. Quipu therefore reports the expansion, on exactly the queries whose answer it could have changed:

{
  "count": 6,
  "inference": {
    "applied": true,
    "expandedTypes": [
      {"type": "http://example.org/homelab/Service",
       "subclasses": ["http://example.org/homelab/WebApp"]}
    ],
    "note": "RDFS subclass expansion was applied to the constant rdf:type pattern; use a variable type plus FILTER for an asserted-only census"
  }
}

The field is absent when the query was not expanded, so its presence is the signal. The subclasses are named because “inference happened” is not actionable on its own — the reader needs to know that Service swallowed WebApp. A leaf type is never reported: with no subclasses there is nothing to fold in.

Every result shape carries it — including ASK

The marker is not a SELECT feature. ASK is the shape most in need of it:

ASK { hw:postgres a hw:Service }     # -> {"result": true, "inference": {...}}

If hw:postgres is typed as hw:DatabaseService and that class is a subclass of hw:Service, the constant-type ASK includes it through subclass expansion. The inference marker identifies that expansion. CONSTRUCT and DESCRIBE results also carry the marker when their query patterns expand.

What the marker claims. It reports the type expansion applied to this query. A marked ASK can also match a directly asserted fact; the marker alone cannot prove how a particular row matched. To inspect asserted types, ask:

SELECT ?t WHERE { hw:postgres a ?t }    # what is it ACTUALLY typed as?

Standard result formats: the marker moves to a header

If you request a W3C shape with Accept (application/sparql-results+json, application/sparql-results+xml, text/turtle), the body is fixed by spec and has nowhere to put the marker. It travels as a response header instead, naming the affected type constants:

x-quipu-inference: applied: http://example.org/homelab/Service

The header is absent when no type expansion was applied. The body is untouched and stays conformant, so a standard parser is unaffected — but a client that ignores headers gets no signal, which is a reason to prefer the default JSON shape when the distinction matters. Full expandedTypes detail is available in the default JSON response.

Standard HTTP responses also carry X-Quipu-Truncated: true when the server row ceiling removed results, or false when the result is complete. This header applies to SPARQL JSON/XML, CSV/TSV and RDF graph output; browser clients can read it through CORS. Check it before treating a result as a complete answer. A result exactly at the ceiling is complete if no extra row was removed. The default JSON format continues to report its existing truncated field.

10. Property Paths

SPARQL 1.1 property paths let you traverse edges without binding intermediate variables.

Sequence (/)

“What hosts do web apps’ dependencies run on?”

PREFIX hw: <http://example.org/homelab/>

SELECT ?app ?depHost
WHERE {
  ?app a hw:WebApp .
  ?app hw:dependsOn/hw:runsOn ?depHost .
}

hw:dependsOn/hw:runsOn means: follow dependsOn, then follow runsOn.

Transitive closure (* and +)

If you had a chain like A dependsOn B dependsOn C, you could traverse the full dependency chain:

PREFIX hw: <http://example.org/homelab/>

SELECT ?svc ?transitiveDep
WHERE {
  ?svc hw:dependsOn+ ?transitiveDep .
}

+ means “one or more hops.” * means “zero or more” (includes the starting node itself).

Alternative (|)

Match either predicate:

PREFIX hw: <http://example.org/homelab/>

SELECT ?thing ?name
WHERE {
  ?thing (hw:hostname|<http://www.w3.org/2000/01/rdf-schema#label>) ?name .
}

Reverse (^)

“What services does korimako host?” using reverse traversal:

PREFIX hw: <http://example.org/homelab/>

SELECT ?svc
WHERE {
  hw:korimako ^hw:runsOn ?svc .
}

^hw:runsOn means “follow runsOn edges backwards.”

11. Temporal Queries

Every SPARQL query in Quipu can include a temporal context.

Valid-time travel

“What did the homelab look like on March 15?”

quipu read "PREFIX hw: <http://example.org/homelab/>
SELECT ?host ?cores WHERE {
  ?host a hw:Host .
  ?host hw:cpuCores ?cores .
}" --db homelab.db --valid-at 2026-03-15

Via REST:

curl -s localhost:3030/query -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "query": "PREFIX hw: <http://example.org/homelab/> SELECT ?host ?cores WHERE { ?host a hw:Host . ?host hw:cpuCores ?cores }",
    "valid_at": "2026-03-15"
  }'

Transaction-time travel

“What did the database know after the first 5 transactions?”

quipu read "SELECT ?s ?p ?o WHERE { ?s ?p ?o }" --db homelab.db --tx 5

12. Other Query Forms

ASK: Yes/No Questions

PREFIX hw: <http://example.org/homelab/>

ASK { hw:korimako a hw:Host }

Returns true or false.

CONSTRUCT: Build New Triples

PREFIX hw: <http://example.org/homelab/>

CONSTRUCT {
  ?svc hw:colocatedWith ?other .
}
WHERE {
  ?svc hw:runsOn ?host .
  ?other hw:runsOn ?host .
  FILTER(?svc != ?other)
}

Returns triples showing which services share a host.

DESCRIBE: Entity Details

PREFIX hw: <http://example.org/homelab/>

DESCRIBE hw:korimako

Returns all triples where korimako is the subject.

Cheat Sheet

What’s Next

• Homelab Operator Tutorial — model a full infrastructure
• Temporal Model — deep dive on time-travel
• REST API Reference — every endpoint

The Homelab Operator

“I want to know what breaks if korimako goes down.”

You run a homelab — a handful of machines with dozens of services, wired together with reverse proxies, DNS, and hope. You need a way to track what runs where, what depends on what, and what the blast radius is when a host goes down.

This tutorial walks through modeling your infrastructure as a knowledge graph, querying dependencies with SPARQL, and ingesting changes from monitoring agents.

Step 1: Model Your Infrastructure

Create homelab.ttl with your hosts and services:

@prefix hw:   <http://example.org/homelab/> .
@prefix xsd:  <http://www.w3.org/2001/XMLSchema#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .

# Type hierarchy
hw:WebApp     rdfs:subClassOf hw:Service .
hw:Database   rdfs:subClassOf hw:Service .

# Hosts
hw:korimako a hw:Host ;
    rdfs:label   "korimako" ;
    hw:hostname  "korimako.example" ;
    hw:cpuCores  "8"^^xsd:integer ;
    hw:memoryMB  "32768"^^xsd:integer .

hw:palau a hw:Host ;
    rdfs:label   "palau" ;
    hw:hostname  "palau.example" ;
    hw:cpuCores  "4"^^xsd:integer ;
    hw:memoryMB  "16384"^^xsd:integer .

# Services
hw:traefik a hw:WebApp ;
    rdfs:label    "traefik" ;
    hw:runsOn     hw:korimako ;
    hw:port       "443"^^xsd:integer ;
    hw:dependsOn  hw:pihole .

hw:pihole a hw:Service ;
    rdfs:label  "pihole" ;
    hw:runsOn   hw:korimako ;
    hw:port     "53"^^xsd:integer .

hw:grafana a hw:WebApp ;
    rdfs:label    "grafana" ;
    hw:runsOn     hw:korimako ;
    hw:dependsOn  hw:prometheus ;
    hw:dependsOn  hw:postgres .

hw:prometheus a hw:Service ;
    rdfs:label  "prometheus" ;
    hw:runsOn   hw:palau .

hw:postgres a hw:Database ;
    rdfs:label  "postgres" ;
    hw:runsOn   hw:palau ;
    hw:port     "5432"^^xsd:integer .

hw:nginx a hw:WebApp ;
    rdfs:label    "nginx" ;
    hw:runsOn     hw:palau ;
    hw:dependsOn  hw:postgres .

Load it:

quipu knot homelab.ttl --db homelab.db

Step 2: Query — What Runs on Each Host?

PREFIX hw: <http://example.org/homelab/>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>

SELECT ?host ?svc
WHERE {
  ?svc hw:runsOn ?host .
  ?host rdfs:label ?hostLabel .
  ?svc rdfs:label ?svcLabel .
}
ORDER BY ?hostLabel

quipu read "PREFIX hw: <http://example.org/homelab/>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
SELECT ?hostLabel ?svcLabel WHERE {
  ?svc hw:runsOn ?host .
  ?host rdfs:label ?hostLabel .
  ?svc rdfs:label ?svcLabel .
} ORDER BY ?hostLabel ?svcLabel" --db homelab.db

Step 3: Impact Analysis — What Breaks if Korimako Goes Down?

This is the killer query. Find all services on korimako, then find everything that depends on them (directly or transitively):

PREFIX hw: <http://example.org/homelab/>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>

SELECT ?affected ?label
WHERE {
  ?affected hw:dependsOn+/hw:runsOn hw:korimako .
  ?affected rdfs:label ?label .
}

The property path hw:dependsOn+/hw:runsOn means: follow one or more dependsOn edges, then one runsOn edge, and check if it lands on korimako.

Traefik depends on pihole, which runs on korimako. But traefik itself also runs on korimako — so if korimako goes down, you lose traefik, pihole, and grafana (all locally hosted), plus anything that transitively depends on them.

A more complete impact query — services that run on korimako OR depend on services running on korimako:

PREFIX hw: <http://example.org/homelab/>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>

SELECT DISTINCT ?svc ?label
WHERE {
  {
    ?svc hw:runsOn hw:korimako .
  }
  UNION
  {
    ?svc hw:dependsOn+/hw:runsOn hw:korimako .
  }
  ?svc rdfs:label ?label .
}

Step 4: Enforce Structure with SHACL

Prevent malformed data from entering the graph. Create homelab.shapes.ttl:

@prefix sh:   <http://www.w3.org/ns/shacl#> .
@prefix hw:   <http://example.org/homelab/> .
@prefix xsd:  <http://www.w3.org/2001/XMLSchema#> .

hw:HostShape a sh:NodeShape ;
    sh:targetClass hw:Host ;
    sh:property [
        sh:path hw:hostname ;
        sh:datatype xsd:string ;
        sh:minCount 1 ;
        sh:maxCount 1 ;
    ] ;
    sh:property [
        sh:path hw:cpuCores ;
        sh:datatype xsd:integer ;
        sh:minCount 1 ;
    ] .

hw:ServiceShape a sh:NodeShape ;
    sh:targetClass hw:Service ;
    sh:property [
        sh:path hw:runsOn ;
        sh:class hw:Host ;
        sh:minCount 1 ;
        sh:maxCount 1 ;
    ] .

Load shapes and validate:

quipu shapes load --name homelab --file homelab.shapes.ttl --db homelab.db

Now any new service without a runsOn edge is rejected.

Step 5: Ingest from Monitoring Agents

When an agent discovers new infrastructure, it can push episodes:

curl -s localhost:3030/episode -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prometheus-discovery-2026-04-04",
    "source": "prometheus-sd",
    "nodes": [
      {"name": "redis", "type": "Service", "description": "Cache layer"},
      {"name": "yap", "type": "Host", "properties": {"hostname": "yap.example"}}
    ],
    "edges": [
      {"source": "redis", "target": "yap", "relation": "runsOn"},
      {"source": "nginx", "target": "redis", "relation": "dependsOn"}
    ]
  }'

The episode creates entities and relationships in a single transaction, with provenance tracking back to the discovery agent.

Step 6: Time-Travel After Changes

After adding redis, query what the graph looked like before:

quipu read "PREFIX hw: <http://example.org/homelab/>
SELECT ?svc WHERE { ?svc a hw:Service }" --db homelab.db --tx 1

Transaction 1 only had the original six services. The current state includes redis.

Useful Queries for Operators

Services with no dependencies (leaf nodes)

PREFIX hw: <http://example.org/homelab/>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>

SELECT ?svc ?label
WHERE {
  ?svc a hw:Service .
  ?svc rdfs:label ?label .
  FILTER NOT EXISTS { ?svc hw:dependsOn ?dep }
}

Hosts sorted by service count

PREFIX hw: <http://example.org/homelab/>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>

SELECT ?hostLabel (COUNT(?svc) AS ?n)
WHERE {
  ?svc hw:runsOn ?host .
  ?host rdfs:label ?hostLabel .
}
GROUP BY ?hostLabel
ORDER BY DESC(?n)

Resource utilization summary

PREFIX hw: <http://example.org/homelab/>

SELECT (SUM(?cores) AS ?totalCores) (SUM(?mem) AS ?totalMB)
       (COUNT(?host) AS ?hostCount)
WHERE {
  ?host a hw:Host .
  ?host hw:cpuCores ?cores .
  ?host hw:memoryMB ?mem .
}

Step 7: Materialise Dependencies with the Reasoner

The property path queries above (dependsOn+, runsOn+) re-derive transitive chains every time you run them. For a graph you query often, the reasoner can materialise those chains once and keep them fresh.

Create infra-rules.ttl:

@prefix rule: <http://quipu.local/rule#> .
@prefix ex:   <http://example.org/rules/> .

ex:homelab a rule:RuleSet ;
    rule:defaultPrefix "http://example.org/homelab/" .

ex:depends_on_transitive a rule:Rule ;
    rule:id "depends_on_transitive" ;
    rule:head "dependsOn(?a, ?c)" ;
    rule:body "dependsOn(?a, ?b), dependsOn(?b, ?c)" .

ex:runs_on_transitive a rule:Rule ;
    rule:id "runs_on_transitive" ;
    rule:head "runsOn(?svc, ?host)" ;
    rule:body "runsOn(?svc, ?mid), runsOn(?mid, ?host)" .

Run it:

quipu reason --rules infra-rules.ttl --db homelab.db

Now the “what breaks if korimako goes down?” query simplifies — no property paths needed:

PREFIX hw: <http://example.org/homelab/>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>

SELECT DISTINCT ?svc ?label
WHERE {
  ?svc hw:runsOn hw:korimako .
  ?svc rdfs:label ?label .
}

This returns both directly-hosted services AND services that transitively run on korimako via containers, because the reasoner already computed the transitive closure.

Stay Fresh with Reactive Evaluation

Enable reactive mode so derived facts update whenever you add or remove infrastructure:

quipu reason --reactive --rules infra-rules.ttl --db homelab.db

Now when a monitoring agent reports a new container on korimako, the transitive runsOn edges update automatically in the same transaction.

“What If?” Before You Change

Before decommissioning a host, ask the reasoner what would break:

#![allow(unused)]
fn main() {
// Hypothetical: retract all runsOn edges to korimako
let report = store.speculate(&koror_retractions, timestamp, |s| {
    evaluate(s, &ruleset, timestamp)
})?;
println!("Decommissioning korimako would retract {} derived facts", report.retracted);
}

The store remains unchanged — you see the impact without making the change. See The Rule Builder for a complete walkthrough.

What’s Next

• The Rule Builder — write custom rules step by step
• Impact Analysis Recipe — more impact patterns
• SPARQL from Zero — full SPARQL reference tutorial
• Knowledge Gardener — maintain ontology quality

The AI Agent Builder

“I want my agents to share structured knowledge.”

You’re building AI agents that observe the world and need to share what they learn. One agent monitors deployments, another reads incident reports, a third answers questions. They need a shared knowledge layer — structured, validated, and queryable.

Quipu gives agents three things:

1. Episodes — structured write path for agent observations
2. MCP tools — native integration for LLM tool-use
3. Temporal queries — “what did the system look like yesterday?”

Step 1: Agent Writes an Episode

An agent observes a deployment and records it as an episode — a batch of nodes and edges with provenance:

curl -s localhost:3030/episode -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "name": "deploy-v2.3",
    "source": "deploy-agent",
    "episode_body": "Deployed v2.3 of the API service to production",
    "group_id": "deployments",
    "nodes": [
      {
        "name": "api-v2.3",
        "type": "Deployment",
        "description": "API service version 2.3",
        "properties": {
          "version": "2.3.0",
          "environment": "production",
          "replicas": 3
        }
      },
      {
        "name": "api-service",
        "type": "Service",
        "description": "Core API service"
      }
    ],
    "edges": [
      {"source": "api-v2.3", "target": "api-service", "relation": "deploys"}
    ]
  }'

Response:

{"tx_id": 1, "count": 12}

The episode created 12 triples in a single transaction: entities with types, labels, descriptions, properties, relationships, and provenance metadata.

Step 2: Another Agent Queries It

A Q&A agent needs to answer “what was deployed recently?” It uses the MCP tool quipu_query:

{
  "tool": "quipu_query",
  "input": {
    "query": "PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#> PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> SELECT ?name ?desc WHERE { ?d a <http://aegis.gastown.local/ontology/Deployment> . ?d rdfs:label ?name . ?d rdfs:comment ?desc }"
  }
}

Response:

{
  "variables": ["name", "desc"],
  "rows": [
    {"name": "api-v2.3", "desc": "API service version 2.3"}
  ],
  "count": 1
}

Step 3: Search by Meaning, Not Just Structure

Agents don’t always know the exact IRI to query. The quipu_search_nodes tool does natural language entity search:

{
  "tool": "quipu_search_nodes",
  "input": {
    "query": "API deployment",
    "max_results": 5
  }
}

Response:

{
  "nodes": [
    {
      "name": "api-v2.3",
      "entity_type": "Deployment",
      "description": "API service version 2.3",
      "score": 0.87
    }
  ],
  "count": 1
}

For relationship search, use quipu_search_facts:

{
  "tool": "quipu_search_facts",
  "input": {
    "query": "deploys",
    "max_results": 10
  }
}

Step 4: Temporal Queries — What Changed?

An incident-response agent needs to see what the graph looked like before a problem started. Add valid_at to any query:

{
  "tool": "quipu_query",
  "input": {
    "query": "PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#> SELECT ?name WHERE { ?d a <http://aegis.gastown.local/ontology/Deployment> . ?d rdfs:label ?name }",
    "valid_at": "2026-04-03"
  }
}

This returns only deployments that existed as of April 3 — before today’s deploy. The agent can diff the two result sets to see what changed.

Step 5: Validate Agent Output

Agents make mistakes. SHACL shapes catch them before they pollute the graph.

Define what a valid Deployment looks like:

@prefix sh:  <http://www.w3.org/ns/shacl#> .
@prefix ont: <http://aegis.gastown.local/ontology/> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

ont:DeploymentShape a sh:NodeShape ;
    sh:targetClass ont:Deployment ;
    sh:property [
        sh:path <http://www.w3.org/2000/01/rdf-schema#label> ;
        sh:minCount 1 ;
        sh:datatype xsd:string ;
    ] ;
    sh:property [
        sh:path <http://www.w3.org/2000/01/rdf-schema#comment> ;
        sh:minCount 1 ;
    ] .

Load the shapes, then include them in episode ingestion:

curl -s localhost:3030/episode -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "name": "bad-deploy",
    "nodes": [{"name": "oops", "type": "Deployment"}],
    "edges": [],
    "shapes": "@prefix sh: <http://www.w3.org/ns/shacl#> ..."
  }'

If the episode data violates the shapes, the write is rejected with structured feedback the agent can parse and fix.

MCP Tool Reference

See MCP Tools Reference for full parameter details.

Patterns for Multi-Agent Systems

Shared ontology, independent episodes

Each agent writes episodes with its own source and group_id. The shared ontology (types, relationships) is defined once via SHACL shapes. Any agent can query the full graph.

Agent as knowledge gardener

One agent periodically validates the graph against shapes, finds violations, and either fixes them or files issues. See The Knowledge Gardener.

Provenance tracking

Every episode records which agent wrote it. Query provenance:

PREFIX prov: <http://www.w3.org/ns/prov#>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>

SELECT ?entity ?episode
WHERE {
  ?entity prov:wasGeneratedBy ?ep .
  ?ep rdfs:label ?episode .
}

Step 6: Derived Knowledge with the Reasoner

Agents write raw facts — “traefik runs on webproxy”, “webproxy runs on korimako”. But other agents need to query derived facts — “traefik runs on korimako” (transitively). Instead of making every consuming agent write property path queries, use the reasoner to materialise derived facts that every agent can query directly.

Rules as Shared Infrastructure

Define rules once, and every agent benefits:

@prefix rule: <http://quipu.local/rule#> .
@prefix ex:   <http://aegis.gastown.local/rules/> .

ex:agent_rules a rule:RuleSet ;
    rule:defaultPrefix "http://aegis.gastown.local/ontology/" .

# If A depends on B and B depends on C, then A depends on C
ex:depends_on_transitive a rule:Rule ;
    rule:id "depends_on_transitive" ;
    rule:head "dependsOn(?a, ?c)" ;
    rule:body "dependsOn(?a, ?b), dependsOn(?b, ?c)" .

Reactive: Derive on Write

With reactive evaluation enabled, derived facts update every time an agent writes an episode:

quipu reason --reactive --rules agent-rules.ttl --db knowledge.db

Now when the deploy agent writes a new dependsOn edge, the transitive closure updates in the same transaction. The Q&A agent’s next query sees the full dependency chain without any property paths.

Pre-Flight Checks with Speculate

Before a deploy agent pushes a change, it can ask “what would this break?” without actually modifying the graph:

#![allow(unused)]
fn main() {
// Hypothetical: remove the old service version
let report = store.speculate(&removal_datums, timestamp, |s| {
    evaluate(s, &ruleset, timestamp)
})?;

if report.retracted > 0 {
    println!("WARNING: removing old version would retract {} derived facts", report.retracted);
    // Agent can decide to proceed or alert a human
}
// Store is unchanged — safe to inspect before committing
}

This is especially powerful in multi-agent systems: one agent proposes a change, the reasoner evaluates the impact, and a separate agent decides whether to approve it.

Provenance for Derived Facts

Derived facts carry source tags like reasoner:depends_on_transitive. Agents can distinguish raw observations from derived knowledge:

PREFIX ont: <http://aegis.gastown.local/ontology/>

SELECT ?a ?b
WHERE {
  ?a ont:dependsOn ?b .
  # This returns BOTH direct and transitively-derived dependencies
}

The provenance is in the fact metadata — agents that need to distinguish can filter on the source field.

What’s Next

• The Rule Builder — write custom rules step by step
• MCP Tools Reference — full tool docs
• Knowledge Ingestion Recipe — batch patterns
• REST API Reference — all HTTP endpoints

The Code Archaeologist

“I want to understand how this codebase evolved.”

You’re investigating a codebase — not just what the code does now, but what decisions shaped it. Which commit caused that outage? What design rationale lives only in someone’s memory? Quipu, paired with Bobbin, links code symbols to knowledge entities and lets you search across both.

Step 1: Model Code as Knowledge

Code entities (modules, functions, types) become nodes in the graph:

curl -s localhost:3030/episode -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "name": "code-index-2026-04-04",
    "source": "bobbin-indexer",
    "group_id": "code-symbols",
    "nodes": [
      {
        "name": "sparql-engine",
        "type": "CodeModule",
        "description": "SPARQL 1.1 query evaluation engine",
        "properties": {"path": "src/sparql/mod.rs", "language": "rust"}
      },
      {
        "name": "property-path-eval",
        "type": "CodeSymbol",
        "description": "Evaluates SPARQL property path expressions",
        "properties": {"path": "src/sparql/property_path.rs", "symbol": "eval_path"}
      },
      {
        "name": "store-transact",
        "type": "CodeSymbol",
        "description": "Core transaction write path for the fact log",
        "properties": {"path": "src/store/ops.rs", "symbol": "transact"}
      }
    ],
    "edges": [
      {"source": "property-path-eval", "target": "sparql-engine", "relation": "partOf"},
      {"source": "store-transact", "target": "sparql-engine", "relation": "usedBy"}
    ]
  }'

Step 2: Link Decisions to Code

Record architectural decisions as knowledge entities linked to code:

curl -s localhost:3030/episode -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "name": "adr-eavt-design",
    "source": "human",
    "group_id": "decisions",
    "nodes": [
      {
        "name": "adr-001-eavt",
        "type": "Decision",
        "description": "Chose Datomic-style EAVT fact log over traditional triple store for bitemporal support and append-only safety"
      },
      {
        "name": "adr-002-property-paths",
        "type": "Decision",
        "description": "Implemented custom SPARQL property path evaluator instead of using existing library for tighter integration with temporal model"
      }
    ],
    "edges": [
      {"source": "adr-001-eavt", "target": "store-transact", "relation": "influences"},
      {"source": "adr-002-property-paths", "target": "property-path-eval", "relation": "influences"}
    ]
  }'

Step 3: Hybrid Search — Code AND Decisions

Search for entities by meaning, not just name:

curl -s localhost:3030/search/nodes -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "query": "how does the transaction write path work",
    "max_results": 5
  }'

This returns both the store-transact code symbol and the adr-001-eavt decision that influenced it — answering “what” and “why” in one search.

SPARQL for precise queries

PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
PREFIX ont: <http://aegis.gastown.local/ontology/>

SELECT ?decision ?description
WHERE {
  ?decision a ont:Decision .
  ?decision ont:influences ?code .
  ?code rdfs:label "store-transact" .
  ?decision rdfs:comment ?description .
}

Step 4: Incident Correlation

When something breaks, link the incident to code and time:

curl -s localhost:3030/episode -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "name": "incident-2026-04-02-query-timeout",
    "source": "incident-agent",
    "group_id": "incidents",
    "nodes": [
      {
        "name": "inc-2026-04-02",
        "type": "Incident",
        "description": "SPARQL queries timing out after property path merge",
        "properties": {
          "severity": "P2",
          "started": "2026-04-02T14:30:00Z",
          "resolved": "2026-04-02T16:00:00Z",
          "commit": "abc123"
        }
      }
    ],
    "edges": [
      {"source": "inc-2026-04-02", "target": "property-path-eval", "relation": "causedBy"},
      {"source": "inc-2026-04-02", "target": "sparql-engine", "relation": "affected"}
    ]
  }'

Now you can query: “What code has caused incidents?”

PREFIX ont: <http://aegis.gastown.local/ontology/>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>

SELECT ?code ?codePath ?incident ?description
WHERE {
  ?incident a ont:Incident .
  ?incident ont:causedBy ?code .
  ?incident rdfs:comment ?description .
  ?code rdfs:label ?codePath .
}

Step 5: Time-Travel for Context

Combine temporal queries with code knowledge:

“What did we know about the SPARQL engine before the incident?”

curl -s localhost:3030/query -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "query": "PREFIX ont: <http://aegis.gastown.local/ontology/> PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#> SELECT ?entity ?desc WHERE { ?entity ont:partOf <http://aegis.gastown.local/ontology/sparql-engine> . ?entity rdfs:comment ?desc }",
    "valid_at": "2026-04-01"
  }'

Step 6: Graph Projection — Dependency Analysis

Visualize module dependencies using graph projection:

curl -s localhost:3030/project -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "type_filter": "http://aegis.gastown.local/ontology/CodeModule"
  }'

This returns a petgraph-compatible adjacency structure. Use it for:

• Centrality: Which modules are most depended upon?
• Components: Which modules form independent clusters?
• Shortest path: How are two modules connected?

curl -s localhost:3030/project -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "predicate_filter": "http://aegis.gastown.local/ontology/usedBy"
  }'

Patterns for Code Archaeology

Link commits to knowledge changes

When a significant commit lands, create an episode with the commit hash, affected code symbols, and a description of intent. Over time, the graph becomes a searchable record of why the code looks the way it does.

Cross-reference documentation

Store doc sections as entities linked to the code they describe. When code changes, search for linked docs that may need updating.

Build a decision log

ADRs (Architecture Decision Records) stored as entities with influences edges to code. When someone asks “why did we do it this way?”, the graph has the answer — queryable by code symbol, by date, or by topic.

Step 7: Derive Influence Chains with the Reasoner

You’ve recorded influences edges between decisions and code symbols. But influence is transitive — if decision A influences module M, and module M is used by module N, then decision A indirectly influences module N. The reasoner can materialise these chains.

Create archaeology-rules.ttl:

@prefix rule: <http://quipu.local/rule#> .
@prefix ex:   <http://aegis.gastown.local/rules/> .

ex:archaeology a rule:RuleSet ;
    rule:defaultPrefix "http://aegis.gastown.local/ontology/" .

# Transitive influence: if A influences B and B is usedBy C, A influences C
ex:influence_through_usage a rule:Rule ;
    rule:id "influence_through_usage" ;
    rule:head "influences(?decision, ?downstream)" ;
    rule:body "influences(?decision, ?code), usedBy(?code, ?downstream)" .

# Transitive partOf: if A is partOf B and B is partOf C, A is partOf C
ex:part_of_transitive a rule:Rule ;
    rule:id "part_of_transitive" ;
    rule:head "partOf(?a, ?c)" ;
    rule:body "partOf(?a, ?b), partOf(?b, ?c)" .

Run it:

quipu reason --rules archaeology-rules.ttl --db knowledge.db

Now you can answer “which decisions influenced this module?” across any depth of the dependency graph, with a flat query:

PREFIX ont: <http://aegis.gastown.local/ontology/>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>

SELECT ?decision ?description
WHERE {
  ?decision ont:influences <http://aegis.gastown.local/ontology/sparql-engine> .
  ?decision a ont:Decision .
  ?decision rdfs:comment ?description .
}

Blast Radius for Code Changes

Before refactoring a module, use speculate() to see what derived relationships would break:

#![allow(unused)]
fn main() {
// Hypothetical: remove the usedBy edge from store-transact to sparql-engine
let report = store.speculate(&retractions, timestamp, |s| {
    evaluate(s, &ruleset, timestamp)
})?;
println!("Decoupling these modules would affect {} derived influence chains",
    report.retracted);
}

This tells you which architectural decisions and incident correlations would lose their path to downstream code — before you make the change.

What’s Next

• The Rule Builder — write custom rules step by step
• Incident Correlation Recipe — more patterns
• SPARQL from Zero — learn query patterns
• Graph Projection — API details

The Knowledge Gardener

“I want to curate and validate our ontology.”

You’re responsible for the quality of your knowledge graph. Entities drift, agents write messy data, and over time the graph accumulates orphan nodes, stale edges, and schema violations. Your job is to define what valid data looks like and keep the garden tidy.

Step 1: Define Your Ontology with SHACL

Start by declaring what types of entities exist and what properties they must have. Create ontology.shapes.ttl:

@prefix sh:   <http://www.w3.org/ns/shacl#> .
@prefix ont:  <http://aegis.gastown.local/ontology/> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix xsd:  <http://www.w3.org/2001/XMLSchema#> .

# Every entity must have a label
ont:LabeledShape a sh:NodeShape ;
    sh:targetSubjectsOf rdfs:label ;
    sh:property [
        sh:path rdfs:label ;
        sh:datatype xsd:string ;
        sh:minCount 1 ;
    ] .

# Hosts must have hostname and cpuCores
ont:HostShape a sh:NodeShape ;
    sh:targetClass ont:Host ;
    sh:property [
        sh:path ont:hostname ;
        sh:datatype xsd:string ;
        sh:minCount 1 ;
        sh:maxCount 1 ;
    ] ;
    sh:property [
        sh:path ont:cpuCores ;
        sh:datatype xsd:integer ;
        sh:minCount 1 ;
    ] ;
    sh:property [
        sh:path ont:memoryMB ;
        sh:datatype xsd:integer ;
    ] .

# Services must reference a valid Host
ont:ServiceShape a sh:NodeShape ;
    sh:targetClass ont:Service ;
    sh:property [
        sh:path ont:runsOn ;
        sh:class ont:Host ;
        sh:minCount 1 ;
        sh:maxCount 1 ;
    ] .

# Dependencies must point to Services
ont:DependencyShape a sh:NodeShape ;
    sh:targetSubjectsOf ont:dependsOn ;
    sh:property [
        sh:path ont:dependsOn ;
        sh:class ont:Service ;
    ] .

Load the shapes:

quipu shapes load --name ontology --file ontology.shapes.ttl --db knowledge.db

Step 2: Validate Existing Data

Run a dry-run validation against your current graph:

quipu validate --shapes ontology.shapes.ttl --data <(quipu export --db knowledge.db)

Or via REST:

# Export current data
DATA=$(curl -s localhost:3030/query -X POST \
  -H "Content-Type: application/json" \
  -d '{"query": "CONSTRUCT { ?s ?p ?o } WHERE { ?s ?p ?o }"}' | jq -r '.triples')

# Validate
curl -s localhost:3030/validate -X POST \
  -H "Content-Type: application/json" \
  -d "{
    \"shapes\": \"$(cat ontology.shapes.ttl)\",
    \"data\": \"$DATA\"
  }"

The response tells you exactly what’s wrong:

{
  "conforms": false,
  "violations": 3,
  "warnings": 0,
  "issues": [
    {
      "severity": "Violation",
      "focus_node": "http://aegis.gastown.local/ontology/orphan-svc",
      "path": "http://aegis.gastown.local/ontology/runsOn",
      "component": "MinCountConstraintComponent",
      "message": "Less than 1 values for ont:runsOn"
    }
  ]
}

Step 3: Find Orphan Nodes

Entities with no incoming or outgoing relationships are usually noise:

PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>

SELECT ?entity ?label
WHERE {
  ?entity rdfs:label ?label .
  FILTER NOT EXISTS { ?entity ?anyPred ?anyObj . FILTER(?anyPred != rdfs:label && ?anyPred != <http://www.w3.org/1999/02/22-rdf-syntax-ns#type>) }
  FILTER NOT EXISTS { ?other ?rel ?entity }
}

Step 4: Find Stale Edges

Edges to entities that no longer exist (were retracted):

PREFIX ont: <http://aegis.gastown.local/ontology/>

SELECT ?source ?rel ?target
WHERE {
  ?source ?rel ?target .
  FILTER(isIRI(?target))
  FILTER NOT EXISTS { ?target a ?type }
  FILTER(?rel != <http://www.w3.org/1999/02/22-rdf-syntax-ns#type>)
}

This finds triples where the object is an IRI but has no type — likely a reference to a retracted or never-created entity.

Step 5: Progressive Schema Tightening

Start with loose shapes and tighten as your ontology stabilizes:

Phase 1: Required types and labels

ont:BasicShape a sh:NodeShape ;
    sh:targetSubjectsOf <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> ;
    sh:property [
        sh:path rdfs:label ;
        sh:minCount 1 ;
    ] .

Phase 2: Add datatype constraints

ont:HostShape a sh:NodeShape ;
    sh:targetClass ont:Host ;
    sh:property [
        sh:path ont:cpuCores ;
        sh:datatype xsd:integer ;    # Was accepting any literal
        sh:minCount 1 ;
    ] .

Phase 3: Add referential integrity

ont:ServiceShape a sh:NodeShape ;
    sh:targetClass ont:Service ;
    sh:property [
        sh:path ont:runsOn ;
        sh:class ont:Host ;          # Must reference a Host entity
        sh:minCount 1 ;
    ] .

Phase 4: Add logical constraints

ont:ServiceShape
    sh:property [
        sh:path ont:dependsOn ;
        sh:not [
            sh:equals ont:runsOn ;    # Can't depend on your own host
        ] ;
    ] .

Step 6: Automated Gardening

Set up an agent to periodically validate and report:

{
  "tool": "quipu_validate",
  "input": {
    "shapes": "@prefix sh: ... your shapes ...",
    "data": "@prefix ont: ... current data ..."
  }
}

The structured feedback is machine-readable — an agent can:

1. Parse violations
2. Attempt automated fixes (e.g., add missing labels from entity names)
3. File issues for violations it can’t fix
4. Report on graph health trends over time

Step 7: Manage Multiple Shape Sets

Different domains can have different shapes:

# Infrastructure shapes
quipu shapes load --name infra --file infra.shapes.ttl --db knowledge.db

# Code entity shapes
quipu shapes load --name code --file code.shapes.ttl --db knowledge.db

# List all loaded shapes
quipu shapes list --db knowledge.db

# Remove outdated shapes
quipu shapes remove --name old-shapes --db knowledge.db

All loaded shapes are combined during validation — a write must satisfy all applicable shapes.

Gardening Queries Cheat Sheet

Step 8: Derived Relationships as Garden Health

The reasoner doesn’t just derive facts for operators — it’s a gardening tool. Materialised transitive closures reveal structural properties of your graph that are hard to see from raw facts alone.

Completeness Checks via Derived Facts

Define a rule that derives “this service is reachable from at least one host” by closing the runsOn chain:

@prefix rule: <http://quipu.local/rule#> .
@prefix ex:   <http://aegis.gastown.local/rules/> .

ex:garden a rule:RuleSet ;
    rule:defaultPrefix "http://aegis.gastown.local/ontology/" .

ex:runs_on_transitive a rule:Rule ;
    rule:id "runs_on_transitive" ;
    rule:head "runsOn(?svc, ?host)" ;
    rule:body "runsOn(?svc, ?mid), runsOn(?mid, ?host)" .

After running the reasoner, query for services that don’t transitively reach any host:

PREFIX ont: <http://aegis.gastown.local/ontology/>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>

SELECT ?svc ?label
WHERE {
  ?svc a ont:Service .
  ?svc rdfs:label ?label .
  FILTER NOT EXISTS {
    ?svc ont:runsOn ?host .
    ?host a ont:Host .
  }
}

These are services with incomplete runsOn chains — either they reference a container that doesn’t exist, or the chain breaks somewhere. This is a data quality signal: the garden needs tending.

Reactive Gardening

With reactive evaluation enabled, derived facts update as agents write new data. You can run validation checks after the reasoner fires to catch problems immediately:

1. Agent writes a new service with runsOn pointing to a container
2. Reactive reasoner fires, tries to derive the transitive runsOn to a host
3. If the container doesn’t have its own runsOn edge, no transitive fact is derived
4. Your gardening query finds the gap

This turns the reasoner into an early warning system: gaps in the transitive closure signal incomplete data at the source.

Monitoring Derived Fact Counts

Track the health of your derived facts over time. After each reasoner run, the EvalReport tells you how many facts were asserted and retracted. A sudden spike in retractions might mean an agent is writing bad data that broke a dependency chain. A plateau in assertions might mean your rules have converged and the ontology is stable.

quipu reason --rules garden-rules.ttl --db knowledge.db
# reasoner: 3 rules across 2 strata — asserted 0, retracted 0
# ^ All derived facts are up to date — the garden is healthy

What’s Next

• The Rule Builder — write custom rules step by step
• SHACL Validation — constraint reference
• SPARQL from Zero — query patterns
• Knowledge Ingestion Recipe — bulk loading

The Rule Builder

“I don’t want to write the same SPARQL property path in every query. I want the graph to know that traefik transitively runs on korimako.”

You have a knowledge graph full of infrastructure facts. You’ve been writing SPARQL queries with dependsOn+ and runsOn+ property paths to chase transitive chains, and it works — but every query re-derives the same relationships from scratch. You want the graph to materialise those relationships once, keep them current, and let you query them directly.

This tutorial walks you through writing Datalog rules, running the reasoner, enabling reactive evaluation, and asking counterfactual “what if?” questions.

Prerequisites

You need a Quipu store with some infrastructure data. If you followed The Homelab Operator, you already have one. If not, create a quick test store:

quipu knot - --db lab.db <<'EOF'
@prefix hw: <http://example.org/homelab/> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .

hw:korimako a hw:Host ;
    rdfs:label "korimako" .

hw:webproxy a hw:Container ;
    rdfs:label "webproxy" ;
    hw:runsOn hw:korimako .

hw:traefik a hw:WebApp ;
    rdfs:label "traefik" ;
    hw:runsOn hw:webproxy ;
    hw:dependsOn hw:pihole .

hw:pihole a hw:Service ;
    rdfs:label "pihole" ;
    hw:runsOn hw:korimako .

hw:grafana a hw:WebApp ;
    rdfs:label "grafana" ;
    hw:runsOn hw:webproxy ;
    hw:dependsOn hw:prometheus .

hw:prometheus a hw:Service ;
    rdfs:label "prometheus" ;
    hw:runsOn hw:korimako ;
    hw:dependsOn hw:postgres .

hw:postgres a hw:Database ;
    rdfs:label "postgres" ;
    hw:runsOn hw:korimako .
EOF

Step 1: Your First Rule — Transitive runsOn

Traefik runs on webproxy, and webproxy runs on korimako. You want to materialise the fact that traefik runs on korimako without writing a property path query every time.

Create my-rules.ttl:

@prefix rule: <http://quipu.local/rule#> .
@prefix ex:   <http://example.org/rules/> .

ex:homelab a rule:RuleSet ;
    rule:defaultPrefix "http://example.org/homelab/" .

ex:runs_on_transitive a rule:Rule ;
    rule:id "runs_on_transitive" ;
    rule:head "runsOn(?svc, ?host)" ;
    rule:body "runsOn(?svc, ?mid), runsOn(?mid, ?host)" .

Let’s unpack this:

• rule:RuleSet with rule:defaultPrefix tells the parser that bare names like runsOn expand to http://example.org/homelab/runsOn.
• rule:id is the provenance tag — every derived fact will carry source = "reasoner:runs_on_transitive" so you know where it came from.
• rule:head is what gets derived: runsOn(?svc, ?host).
• rule:body is the condition: if ?svc runs on ?mid, and ?mid runs on ?host, then ?svc runs on ?host.

The shared variable ?mid is the join key — it’s the container in the middle of the chain.

Step 2: Run the Reasoner

quipu reason --rules my-rules.ttl --db lab.db

Output:

reasoner: 1 rules across 1 strata — asserted 3, retracted 0

per-rule contributions:
  runs_on_transitive    3

Three new facts were derived. The reasoner found that traefik, grafana, and prometheus all transitively run on korimako (via webproxy or directly).

Query the derived facts:

quipu read "PREFIX hw: <http://example.org/homelab/>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
SELECT ?svc ?host WHERE {
  ?svc hw:runsOn ?host .
  ?host a hw:Host .
  ?svc rdfs:label ?label .
}" --db lab.db

The transitive runsOn edges are now first-class facts — no property paths needed. Every SPARQL query, every API call, and every agent context lookup benefits.

Step 3: Add a Join Rule — Cross-Predicate Derivation

A single-predicate transitive closure is useful, but the real power is joining across predicates. Add a second rule that derives “this service is affected by this host going down”:

ex:affected_by_host a rule:Rule ;
    rule:id "affected_by_host" ;
    rule:head "affectedByHost(?svc, ?host)" ;
    rule:body "runsOn(?svc, ?container), runsOn(?container, ?host)" .

Wait — that’s the same rule as runs_on_transitive. Let’s do something more interesting. Suppose you also track package dependencies:

quipu knot - --db lab.db <<'EOF'
@prefix hw: <http://example.org/homelab/> .

hw:nginx_pkg a hw:Package ;
    hw:installedIn hw:webproxy .

hw:traefik hw:usesPackage hw:nginx_pkg .
EOF

Now add a rule that derives “service S is affected by package P”:

ex:affected_by_package a rule:Rule ;
    rule:id "affected_by_package" ;
    rule:head "affectedByPackage(?svc, ?pkg)" ;
    rule:body "usesPackage(?svc, ?pkg), installedIn(?pkg, ?container)" .

This joins across usesPackage and installedIn via the shared variable ?pkg. The head projects the service and package, dropping the container (which was only needed for the join condition).

Add both rules to my-rules.ttl and run again:

quipu reason --rules my-rules.ttl --db lab.db

Step 4: Transitive Dependencies

The most common pattern is transitive closure over dependsOn. Add:

ex:depends_on_transitive a rule:Rule ;
    rule:id "depends_on_transitive" ;
    rule:head "dependsOn(?a, ?c)" ;
    rule:body "dependsOn(?a, ?b), dependsOn(?b, ?c)" .

This rule is positively recursive — it reads and writes the same predicate (dependsOn). The reasoner handles this correctly: it keeps applying the rule until no new facts are derived (fixpoint), using semi-naive evaluation to avoid redundant work.

After running the reasoner, you can find the full transitive blast radius of any service with a simple flat query:

quipu read "PREFIX hw: <http://example.org/homelab/>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
SELECT ?affected ?label WHERE {
  ?affected hw:dependsOn <http://example.org/homelab/postgres> .
  ?affected rdfs:label ?label .
}" --db lab.db

No property paths, no dependsOn+ — the transitive closure is already in the store.

Step 5: Understanding Stratification

Let’s look at what happens when you have multiple rules that depend on each other. Your complete ruleset now has:

1. depends_on_transitive — reads and writes dependsOn
2. runs_on_transitive — reads and writes runsOn
3. affected_by_package — reads usesPackage and installedIn, writes affectedByPackage

The reasoner stratifies these automatically:

• Stratum 0: Base facts (usesPackage, installedIn) — no rules produce these, so they’re treated as ground truth.
• Stratum 1: All three rules. Rules 1 and 2 are self-recursive (they read their own output), but there are no cross-rule dependencies, so the stratifier groups them together.

The important principle: positive recursion is fine within a stratum. The evaluator runs all rules in a stratum to fixpoint together. What isn’t allowed is negation within a cycle — but since none of these rules use negation, stratification is straightforward.

If you had a rule like:

# NOT YET SUPPORTED at eval time, but parsed and stratified
ex:orphan a rule:Rule ;
    rule:id "orphan" ;
    rule:head "orphan(?svc)" ;
    rule:body "service(?svc), not dependsOn(?other, ?svc)" .

The stratifier would place orphan in a higher stratum than depends_on_transitive, because it needs the complete dependsOn relation (including derived transitive edges) before it can evaluate the negation. This is stratification at work — it ensures negation only reads “finished” relations.

Step 6: Go Reactive

Running quipu reason manually is fine for batch processing, but in a live system you want derived facts to update automatically when base facts change.

Enable reactive evaluation:

quipu reason --reactive --rules my-rules.ttl --db lab.db

Now the reasoner registers as an observer on the store. Any subsequent transact() call — whether from the CLI, the REST API, an episode ingestion, or an MCP tool — triggers automatic re-derivation of affected rules.

Add a new dependency:

quipu knot - --db lab.db <<'EOF'
@prefix hw: <http://example.org/homelab/> .
hw:grafana hw:dependsOn hw:traefik .
EOF

The reactive reasoner:

1. Sees that dependsOn changed
2. Finds depends_on_transitive uses dependsOn in its body
3. Re-evaluates that rule
4. Derives new transitive edges (grafana now transitively depends on pihole, via traefik)

All of this happens in the same transaction boundary — by the time the knot command returns, the derived facts are already updated.

How the Reactive Reasoner Avoids Loops

When the reactive reasoner writes derived facts, those writes are also transactions. To prevent infinite recursion, the observer checks the source field of every incoming transaction. If it starts with "reasoner:", the observer skips it. This is simple, correct, and zero-cost.

Step 7: Ask “What If?” with Speculate

The most powerful feature of the reasoner is counterfactual reasoning. Instead of actually removing a host from your graph, you can ask “what would happen if I removed it?” and get a precise answer.

From the Rust API:

#![allow(unused)]
fn main() {
use quipu::reasoner::{evaluate, parse_rules};
use quipu::store::Store;
use quipu::types::{Datum, Op, Value};

let mut store = Store::open("lab.db")?;
let ruleset = parse_rules(&std::fs::read_to_string("my-rules.ttl")?, None)?;

// Hypothetical: retract all runsOn edges to korimako
let koror_id = store.lookup("http://example.org/homelab/korimako")?.unwrap();
let runs_on_id = store.lookup("http://example.org/homelab/runsOn")?.unwrap();

let retractions: Vec<Datum> = store
    .current_facts()?
    .iter()
    .filter(|f| f.attribute == runs_on_id && f.value == Value::Ref(koror_id))
    .map(|f| Datum {
        entity: f.entity,
        attribute: f.attribute,
        value: f.value.clone(),
        valid_from: "2026-04-04T00:00:00Z".into(),
        valid_to: None,
        op: Op::Retract,
    })
    .collect();

// Ask "what if?"
let report = store.speculate(&retractions, "2026-04-04T00:00:00Z", |s| {
    evaluate(s, &ruleset, "2026-04-04T00:00:00Z")
})?;

println!("If korimako went down: {} facts retracted", report.retracted);
}

The store is unchanged after speculate() returns. The hypothetical facts were applied inside a SQLite savepoint and rolled back. You get the evaluation report without any side effects.

This is ideal for:

• Pre-change impact assessment: “What breaks if I decommission this host?”
• Capacity planning: “What if I move these containers to a new host?”
• Incident simulation: “What’s the blast radius of this failure?”

Step 8: Debugging Rules

Common Errors and Fixes

“head variable ?z is not bound in the body”

Every variable in the head must appear in at least one positive body atom. If your head mentions ?z, make sure ?z appears in a body atom (not just under negation).

# Bad: ?host not in body
rule:head "runsOn(?svc, ?host)" ;
rule:body "service(?svc)" .

# Good: ?host bound by second body atom
rule:head "runsOn(?svc, ?host)" ;
rule:body "service(?svc), assignedTo(?svc, ?host)" .

Historical errors you will no longer see (lifted 2026-08-27, quipu-923): "two-atom body must share exactly one variable" and "body with more than 2 atoms". Bodies of any length now compile to a join pipeline — p(?a, ?b), q(?b, ?c), r(?c, ?d) works directly, atoms may share zero, one, or both variables, and not q(?x, ?y) applies stratified negation. Decomposing a long body into intermediate predicates (the old workaround) still works and remains useful when an intermediate relation is worth naming or reusing.

“rule set is not stratifiable: negation cycle through […]”

Your rules have a cycle through negation. Rule A negates something rule B produces, and rule B negates something rule A produces. The fix is to restructure so negation only flows in one direction (from higher strata to lower ones).

Inspecting Derived Facts

Derived facts live in the companion inferred graph (quipu-0b6), so select it — or compose it with the base — explicitly:

quipu read "SELECT ?e ?a ?v FROM <urn:quipu:graph:root#inferred> WHERE { ?e ?a ?v }" \
  --db lab.db

To re-run the reasoner and see what changed:

quipu reason --rules my-rules.ttl --db lab.db

If the report shows asserted 0, retracted 0, the derived facts are already up to date — nothing changed since the last run.

Your Complete Ruleset

Here’s the full my-rules.ttl from this tutorial:

@prefix rule: <http://quipu.local/rule#> .
@prefix ex:   <http://example.org/rules/> .

ex:homelab a rule:RuleSet ;
    rule:defaultPrefix "http://example.org/homelab/" .

# Transitive dependency closure
ex:depends_on_transitive a rule:Rule ;
    rule:id "depends_on_transitive" ;
    rule:head "dependsOn(?a, ?c)" ;
    rule:body "dependsOn(?a, ?b), dependsOn(?b, ?c)" .

# Transitive runsOn closure
ex:runs_on_transitive a rule:Rule ;
    rule:id "runs_on_transitive" ;
    rule:head "runsOn(?svc, ?host)" ;
    rule:body "runsOn(?svc, ?mid), runsOn(?mid, ?host)" .

# Package impact: which services are affected by a package?
ex:affected_by_package a rule:Rule ;
    rule:id "affected_by_package" ;
    rule:head "affectedByPackage(?svc, ?pkg)" ;
    rule:body "usesPackage(?svc, ?pkg), installedIn(?pkg, ?container)" .

What’s Next

• The Reasoner — how it works under the hood
• Reasoner Reference — complete rule syntax and API
• Impact Analysis — more patterns for blast radius queries
• The Homelab Operator — model your infrastructure from scratch

CLI Commands

The quipu binary provides a command-line interface for all operations.

Global Flags

Build identity

quipu --version (also -V or version) reports build identity without loading configuration or opening a database:

quipu <version>
git_sha: <build-commit>
git_dirty: <true-or-false>

The first line retains the version-only format for existing parsers. The second line identifies the source commit, or unknown when built without Git metadata. The third reports the build-time working-tree dirty flag. quipu-server --version (and -V) exposes the same fields with a quipu-server first-line prefix. Compare known build commits to detect differences between releases; equal version strings alone do not establish that two binaries contain the same code.

Commands

quipu knot <file.ttl>

Load RDF facts from a Turtle file.

quipu knot data.ttl --db my.db
quipu knot data.ttl --shapes schema.ttl --db my.db  # With SHACL validation
quipu knot data.ttl --timestamp 2026-03-15T00:00:00Z --db my.db  # Source-true valid-time

Alias: load

quipu read "<sparql>"

Execute a SPARQL query.

quipu read "SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10" --db my.db
quipu read "SELECT ?s WHERE { ?s a <http://ex.org/Person> }" --valid-at "2026-03-01"

Alias: query

quipu cord

List entities, optionally filtered by type.

quipu cord --db my.db
quipu cord --type "http://example.org/Person" --limit 50 --db my.db

quipu unravel

Time-travel query: view facts at a past point.

quipu unravel --tx 5 --db my.db
quipu unravel --valid-at "2026-03-15T00:00:00Z" --db my.db

Requires at least one of --tx or --valid-at.

quipu episode <file.json>

Ingest a structured episode from a JSON file.

quipu episode deploy.json --db my.db
echo '{"name": "test", "nodes": []}' | quipu episode - --db my.db  # stdin
quipu episode deploy.json --base-ns "https://quarterdeck.internal/ontology#" --db my.db
quipu episode deploy.json --timestamp 2026-03-15T00:00:00Z --db my.db

quipu retract <entity-IRI>

Retract facts for an entity.

quipu retract "http://example.org/old-service" --db my.db
quipu retract "http://example.org/alice" --predicate "http://example.org/email" --db my.db

quipu shapes

Manage persistent SHACL shapes.

quipu shapes load person-shape schema/person.ttl --db my.db
quipu shapes list --db my.db
quipu shapes remove person-shape --db my.db

Loaded shapes automatically validate all future writes.

quipu validate

Dry-run SHACL validation without writing.

quipu validate --shapes schema.ttl --data test-data.ttl
quipu validate --shapes schema.ttl --data test-data.ttl --format json

--format json prints one JSON object with conforms, violations, warnings and every result (severity, focus node, component, path, value, source shape, message), in the order the engine reported them and without deduplication. The text form prints only the counts on a conforming run and omits the shape, component and value. The exit status is the same in both forms: 0 when the data conforms, 1 otherwise or on an error.

quipu export

Export deterministic RDF from ROOT or one explicit scope.

quipu export --db my.db                        # N-Triples (default)
quipu export --format turtle --db my.db        # Turtle
quipu export --group-id project-a --db my.db   # provenance group
quipu export --construct 'CONSTRUCT { ?s ?p ?o } WHERE { ?s ?p ?o }' --db my.db

The three scope flags are mutually exclusive. Omit all three for ROOT.

quipu share

Write a deterministic directory intended for git storage and interchange. First load an identifier-policy catalogue and your data’s shapes into the same store. The examples below assume that setup. Outward shares refuse with exit 2 when no block-tier catalogue is available, exit 1 when a rule matches, and exit 0 when the checked payload is clean.

quipu share --output knowledge-share --db my.db
quipu share --output project-share --group-id project-a --shapes project-shapes --turtle
quipu share --output next-share --parent-share sha256:abc123 --db my.db

The three scope flags are mutually exclusive and default to ROOT. By default, the share includes every loaded shape set. An explicit --shapes selection narrows that set. If no shapes are loaded, the command refuses to produce a silent empty bundle unless --no-shapes is supplied. Required payloads are export.nt, shapes.ttl, and manifest.json. The graph payload is sorted and duplicate-free; the manifest hashes the exact payload bytes and uses the anchored transaction timestamp, so unchanged state produces byte-identical output.

quipu status and quipu merge

Compare an incoming share with local ROOT using the snapshot named by its parent_share, then reconnect the two histories with an RDF-aware three-way merge:

quipu status shares/alice-next --db my.db
quipu merge shares/alice-next --actor reviewer --db my.db

The base snapshot must exist exactly once beneath the incoming share’s parent directory. Missing or ambiguous lineage is refused. status reports additions, removals, divergence, and the same structured DecisionRecord conflicts that merge would encounter.

Unconstrained multi-valued predicates use set union. A predicate governed by sh:maxCount becomes a conflict when the merged cardinality exceeds its bound; a delete racing a replacement on sh:maxCount 1 is also a conflict. Conflicted slots are held at their base values and merge exits 2 without writing ROOT. A clean merge applies assertions and retractions atomically, with both the local graph hash and incoming share_id recorded as provenance parents.

quipu stats

Show store statistics.

quipu stats --db my.db

Output: fact count, entity count, predicate count.

quipu reason

Run the Datalog reasoner to derive facts from rules.

quipu reason --db my.db
quipu reason --rules custom-rules.ttl --db my.db
# --reactive needs a non-default feature (see below):
quipu reason --reactive --db my.db   # requires: cargo build --features reactive-reasoner

Output shows asserted/retracted counts per rule. Derived facts are written with source = "reasoner:<rule-id>" provenance.

See Reasoner Reference for full details on rule syntax and the evaluation model.

quipu demotions

List unsupported Datalog demotions in a premise graph’s companion:

quipu demotions --db my.db
quipu demotions --graph urn:example:premises --db my.db

The JSON rows identify the retained record, subject, predicate, object, premise graph, deriver source, promotion transaction and invalidation transaction. --graph defaults to ROOT. The command installs the shipped unsupported_demotions stored query if missing; a fresh store returns no rows. After the companion is initialized, HTTP clients can call POST /ask with {"name":"unsupported_demotions"}; for a named companion, add "params":{"graph":"urn:example:premises#inferred"}.

Support loss removes the original triple from first-class standing and retains one quipu:DemotedDerivation reification record. Datalog, OWL and RDFS materializers exclude plane bookkeeping from premises. Ordinary graph queries can still inspect the record; it does not assert the reified triple. Restored support marks it resolved and recreates the derivation only in the companion. Resolved records remain available through graph queries but leave this list. This is truth maintenance, not a promotion or automatic-promotion API. Load the product evidence schema alongside the application’s other shapes:

quipu shapes load demoted-derivations shapes/demoted-derivation.ttl --db my.db

Demotion does not load shapes automatically: installing the first shape set would activate the vocabulary gate for unrelated writes in an ungoverned store.

quipu impact <entity-IRI>

Bounded BFS over entity edges: what is downstream of this entity? With --remove, speculatively retracts the entity (SQLite savepoint, no mutation), re-runs the reasoner inside the fork, and walks the result — “what would break if I removed this?”.

quipu impact http://example.org/traefik --hops 3 --db my.db
quipu impact http://example.org/traefik --remove --db my.db

quipu project

Run graph algorithms over the projected knowledge graph: stats, in_degree, pagerank/ppr, components, louvain, shortest_path.

quipu project --algorithm pagerank --limit 10 --db my.db
quipu project --algorithm pagerank --seed http://example.org/alice --db my.db  # PPR
quipu project --algorithm shortest_path --from <IRI> --to <IRI> --db my.db

quipu render

Render markdown and byte-addressed includes from a stored specification or an ad-hoc query into an owned destination. Supports single-file and per-entity hierarchies, --valid-at, a no-write destination dry-run and local/remote reads. See the render reference for the command, manifest and refusal contract. A remote server prepares bytes; only the client publishes files.

quipu report

Graph health report: hub entities (god-nodes), surprising connections, and suggested competency questions.

quipu report --hubs 10 --surprises 5 --db my.db

quipu repl

Interactive SPARQL prompt.

quipu repl --db my.db

Type SPARQL queries at the prompt. Use :quit or :q to exit.

quipu audit <trace.jsonl>

Check an enforcement trace against the constraint specification in the store — SARC’s T ⊨ Σ.

quipu audit ~/.local/state/hank/metrics.jsonl --db my.db
quipu audit trace.jsonl --json --db my.db

Exit code 1 when the trace contradicts the spec, 0 otherwise — so a CI job can gate on it without parsing anything.

Four passes run over every record: coverage (is every constraint the trace cites actually in Σ, and does every refusal name one), placement (was each constraint evaluated at a point its class can be enforced at, does the record agree with Σ about its class, and does the layer that actually evaluated it match the aegis:hostedAtLayer the policy claims — SARC I6), outcome (does the response taken match the one declared, at the recorded mode), and attribution (does the record say who is answerable). Every pass is a comparison between two declared values; none of them calls a model.

The I6 check is one-directional. A policy claiming "tool" while a hook in the agent’s own loop evaluated it is a violation — it reads as enforced somewhere an agent cannot route around while being enforced somewhere an agent can. A policy claiming "orchestration" while something stronger enforced it is silent: understating your own robustness misleads nobody in a direction that costs them.

Findings come in two severities and only one of them fails the gate:

• violation — the trace contradicts Σ. A soft constraint that blocked, a declared deny that only warned under enforce, a record whose declared principal chain disagrees with the process that ran.
• incompleteness — the trace does not say enough to decide. No principal chain, no declared class, a constraint Σ declares that this window never exercised.

Incompleteness never changes the exit code. A checker that failed the build over a missing planner would be switched off within a week, and then the violations would stop being caught too.

Two limits worth stating before reading a T ⊨ Σ result as reassurance. Coverage is checked in the direction quipu can decide — nothing is cited that Σ does not define — because the other direction, was every constraint that applied evaluated, means re-running the selector against the file as it stood, and quipu has neither by default. The opt-in Git and Yupana passes below supply that evidence. The report counts lines it could not read rather than skipping them, so N line(s) unreadable is always part of the summary: conformance over a window that was only partly read is not conformance.

Git path-policy backstop

quipu audit trace.jsonl --repo . --from BASE --to HEAD --json --db my.db

All three Git flags are required together. BASE is exclusive; HEAD is inclusive. Both resolve to full immutable commit ids before enumeration. The base must be an ancestor. Shallow repositories and ancestry grafts are refused; replacement objects are ignored. The git object reports those ids, commits and changed paths checked, path-policy count, and unresolved coverage. An empty policy catalogue is unproven, not a clean scan.

The additional git-coverage pass reads ROOT’s current action policies with appliesTo path globs. Globs use the same glob::Pattern matching as Yupana tripwires. It checks each commit, not just the window’s net diff: a crossing followed by a revert is still visible. Renames check both old and new paths. The window includes side-branch commits. A merge only contributes paths whose committed state differs from every parent (including mode changes and deletions): inherited content is audited where it was introduced, while new merge content still needs its own evaluation. This also handles octopus merges; comparing against just one parent would either duplicate evidence or miss a new merge change. Policy scope is the supplied repository; use a store containing the policies intended for that repository. Policies introduced after the audited commits also apply: this is a current-policy retrospective audit, not historical policy reconstruction.

A changed matching path needs a conclusive evaluation with the exact policy id, repository-relative path, and full git_commit id in the trace record. Missing evidence produces a bypassed enforcement violation. A path-only deny crossing produces a violation even with a recorded evaluation: a claim that it was blocked cannot excuse the committed crossing. The report includes the commit author and declared Co-Authored-By, Claude-Session, and SHANTY_AGENT metadata for investigation.

Existing pre-edit spools do not emit git_commit; they remain valid for the trace-only checker but do not establish Git coverage. A trusted producer must bind an evaluation to its actual commit; do not backfill every old path record with the current tip. This reader does not authenticate such bindings.

Git mode exits 1 for a violation, 2 when Git coverage cannot be verified (including malformed trace lines, invalid refs/globs, no path policies, or unsupported selector replay without another violation), and 0 otherwise. Trace-only incompleteness retains its original semantics. Without --yupana, selector/predicate policies with matching appliesTo are unresolved and selectors without path scope remain outside the path-only pass.

Replay tree-sitter policies at each commit

quipu audit trace.jsonl --repo . --from BASE --to HEAD --db my.db \
  --yupana /trusted/path/to/yupana --json

The explicit executable must provide Yupana’s audit-rule JSON interface, schema version 1. Quipu loads each policy’s current selector and predicate from ROOT and supplies the exact regular-file blob from each commit to that parser. It never reads the working tree’s contents or follows committed symlinks. Unscoped structural policies are included in this mode; Yupana’s own path-to-language classifier decides language applicability. appliesTo still narrows a policy when present.

A replayed unsatisfied claim is a violation even if its trace claims success. Successful replay does not erase a missing enforcement record. The git object reports selectors_checked separately from paths and commits. Deleted paths, non-UTF-8 or oversized blobs, malformed/ambiguous selector definitions, unsupported grammars, invalid syntax, a missing executable, and protocol or process failures are unresolved. A pure path policy still covers deletions. Source blobs are limited to 8 MiB; each evaluator invocation has a 10-second limit and a 1-MiB output limit. Only tree-sitter selector definitions with regex predicates are supported; entity-grounding and other selector tiers remain unresolved.

This is an agent-invoked audit library/CLI, not an installed scheduler or forge gate. Select and pin a trusted Yupana build: invoking a caller-selected executable does not authenticate that executable or the response it produces.

This catches only changes reaching the selected Git window. Uncommitted edits, ignored files and writes outside the repository remain invisible. Authors, trailers and trace evidence can be forged: this is an audit backstop, not a server-side enforcement boundary. Human edits are audited too, because an absent agent trailer does not prove a human author. Signed exception verdicts and a required forge check are not implemented by this command.

quipu audit inventory

Check the dispatch graph rather than a trace — SARC I7, enforcement completeness.

quipu audit inventory --db my.db
quipu knot shapes/dispatch-inventory.ttl --db my.db   # load the shipped seed first

I7 is a property of the dispatch graph, not of any one constraint: a harness exposes N classes of tool call, and completeness is the question of whether every class that can change state passes through a point where a constraint could stop it. aegis:ToolClass declares each class, whether it is executable, and which governedAt points it traverses.

Findings, in the same two severities:

• violation — an executable class that traverses no enforcement point and has no aegis:ungovernedReason. An unknown hole.
• incompleteness — an executable class that traverses nothing but says why: an acknowledged bypass surface. Reported on every run, because a bypass surface an operator has stopped seeing is one they have stopped weighing. Also: a class that does not declare aegis:executable, since whether it needs a point is then undecidable.
• violation, the other direction — a constraint in Σ placed at a point no declared executable class traverses. It reads as governance in the catalog and can never fire in the deployment.
• incompleteness, the zero-trust boundary — a class declaring aegis:importsUntrustedState brings content into the agent’s context that has not been through this deployment’s constraints (a sub-agent’s response, an MCP server’s output, retrieved documents). Reported whether or not the class is governed: governedAt says its own actions traverse a point and says nothing about what it returned. No trust predicate evaluates imported content today, so this is an open boundary reported on every run rather than a closed gap. A class that imports and declares no aegis:untrustedOrigin is a violation — an import channel nobody can describe is one nobody can weigh.

An empty inventory is reported as an incompleteness, never as a pass: an unwritten dispatch graph is not an empty one.

shapes/dispatch-inventory.ttl ships the seed for this stack — the edit path and quipu’s own write gate as governed, reads as non-executable, and Bash, Task, CI pipelines, cron, remote shells, a sibling session’s VCS index and a hostile agent as acknowledged surfaces with where each is enforced instead. Nothing derives it from the harness’s actual tool registry, so it can drift from reality the way a prose list does; the difference is that a drifted declaration is a wrong answer to a question something asks rather than a paragraph nobody re-reads.

quipu audit namespace

List the base-namespace predicates episode ingest minted that no loaded shape mentions — namespace drift, in the same shape as quipu audit inventory.

quipu audit namespace --db my.db
quipu audit namespace --graph urn:example:tenant --json --db my.db

Exits 0 whatever it finds, and refuses nothing. Every key in an episode node’s properties map becomes a predicate in the base namespace via sanitize_iri_local, with no shape governing which keys are admissible, so agents writing free-form properties mint predicates indefinitely and nothing reported the drift. A gate here would reject writes every deployment is already making — the ontology in the store today was grown by exactly this path — so it would be switched off within a day and the drift would go back to being invisible. A report an operator reads beats a gate nobody leaves on.

Per ungoverned predicate: the IRI, how many current facts use it, how many distinct episode-written subjects carry it, and the window it has been in use.

namespace: 2 ungoverned predicate(s), 1 governed, minted by episode ingest over
2 episode-written subject(s) in urn:quipu:graph:root against 1 loaded shape(s)

UNGOVERNED http://aegis.gastown.local/ontology/rackUnit: 1 fact(s) on 1 subject(s),
in use 2026-01-01T00:00:00Z .. 2026-01-01T00:00:00Z

What counts as minted here. A predicate is reported when its subject carries prov:wasGeneratedBy pointing at a {base}episode_… activity, the predicate is in the configured base namespace, and the object is a literal. That last condition is what separates the properties map from the edge path: edge relations resolve to node references and already pass through resolve_edge_predicate, which is a fence. The two predicates episode ingest emits structurally — aegis:groupId and aegis:contentHash — are excluded by name, because the writer’s own vocabulary reported as agent drift would put a permanent floor under every report.

What “no shape mentions it” means. A predicate is treated as governed if its IRI appears anywhere in any loaded shape’s graph — as an sh:path, a target, or any other position. That is the widest reading of “mentions”, chosen deliberately: this is a report an operator acts on, and a false alarm costs more here than a missed one.

What the seen window honestly is. first_seen / last_seen are the earliest and latest valid_from among the facts using the predicate. The store keeps no separate mint timestamp, so this answers “since when has this predicate been in use”, not “when was this IRI first interned” — and a fact re-asserted with an older valid time genuinely moves first_seen backwards.

Scans the ROOT graph by default; --graph <iri> scans one named graph instead. A graph IRI that names no graph is an error, not an empty result — “no drift in the graph you named” and “there is no such graph” are different answers and only one should let an operator stop looking.

quipu audit replay <trace.jsonl>

Re-check a recorded window against the current Σ and report what promoting each rule from advise to enforce would do.

quipu audit replay ~/.local/state/hank/metrics.jsonl --db my.db
quipu audit replay trace.jsonl --json --db my.db

Exits 0 whatever it finds. Replay reports readiness, and readiness is a judgement an operator makes: failing a build because a rule has not yet fired would turn “we have not measured this” into “this is broken”, which are different states needing different responses.

Per rule, five gates — each a reason not to promote:

Nothing is re-evaluated. The predicate needed the file as it stood and that file is gone, so this is deterministic arithmetic over records rather than a simulation.

Three limits, printed with every summary rather than kept in a footnote. It measures only traffic that happened, so a rule that would block a kind of edit nobody attempted shows zero new blocks and is not therefore safe. It counts false-positive candidates and never false positives — a block is wrong only if the action was legitimate, and no record carries that judgement. And it bounds no false negatives at all: actions a rule let through without firing look exactly like actions it correctly approved.

quipu audit replay <verdict>

Re-derive one recorded gate decision against the store as of its transaction. When the argument is not a file, it is a verdict IRI (or its local verdict_… name).

quipu audit replay verdict_3f9a… --db my.db
quipu audit replay verdict_3f9a… --delta attempt.json --json --db my.db

A refused write replays from its quarantine entry: the store is rebuilt as of the refusal in memory, the attempt applied, and the gate re-run. It re-derives when the write is refused again with the same outcome, the same rule-set digest and the same post-state digest. Under digest-only retention, present the attempt with --delta (a quipu-refused-delta/v1 JSON document); a delta whose canonical hash matches no quarantined attempt is refused as not the delta the gate judged. A verdict whose write committed replays from that write’s transaction.

Exits 1 only when a replay contradicts the record — a different outcome, rule set or post-state, or a broken seal. “Attestation only” (content purged, or digest-only with nothing presented) exits 0: it is incomplete evidence, not contrary evidence.

quipu audit quarantine

quipu audit quarantine --db my.db                          # list entries
quipu audit quarantine list --verdict <iri> --json --db my.db
quipu audit quarantine purge --graph urn:quipu:graph:root --db my.db
quipu audit quarantine purge --older-than 90 --db my.db

purge erases the sealed attempts matching --graph, --before <ts> or --older-than <days> (or --all, which must be named) and keeps each entry’s digests and seal, and the verdict facts untouched.

quipu audit tree <trace.jsonl>

Reassemble the dispatch forest from the principal chains a trace carries.

quipu audit tree trace.jsonl
quipu audit tree trace.jsonl --json

Needs no store — the tree is a property of the trace alone — and exits 0 always. A shape is not a verdict; the findings that are verdicts (a laundered chain, a partial attribution tuple) belong to quipu audit <trace>.

SARC §9.5’s attribution dilution is what this addresses: an orchestrator dispatches, a worker acts, and a flat record cannot say which link was answerable. The trace this stack emits is a sequence, so the tree here is reconstructed rather than structural, and the output says so in three places:

• Unattributed records are not placed. A record with no chain is counted and left out. Attaching it to whichever root happened to be first would invent an answer to the question the tree exists to answer.
• Implied dispatch nodes are flagged. A chain [orchestrator, worker] proves an orchestrator exists; it does not prove the orchestrator’s own actions are in this window. “This agent did nothing” and “this agent’s actions were not recorded” are different facts and only one is good news.
• Collapsed nodes get a note. Two separate dispatches of the same worker by the same caller produce the same chain and land on one node. Not an error — one agent legitimately does many things — but the reader must not be told the tree is unambiguous when it is not.

quipu audit inheritance <trace.jsonl>

Check whether a constraint declared aegis:inheritedByDelegates stopped applying under delegation — SARC §9.5’s constraint laundering.

quipu audit inheritance trace.jsonl --db my.db

Exits 1 on a violation, like quipu audit <trace>.

An orchestrator is bound by a constraint, dispatches a sub-agent, and the constraint is not re-applied at the deeper layer. Nobody decided to drop it; it simply was not carried, and the record looks exactly like a constraint that legitimately did not apply.

Two findings at deliberately different severities, because one has evidence and the other has a question:

• Violation. Constraint C decided on target T under chain [orchestrator], and a deeper action on the same target under [orchestrator, worker] did not evaluate it. C proved it could decide for T, so its absence deeper is a drop.
• Incompleteness. C was evaluated at a dispatch node and never anywhere in its subtree. That might be laundering and might be a selector that legitimately matched nothing deeper; deciding needs the files as they stood, which quipu does not have.

Reporting both as violations would make the strong one unfindable.

aegis:onUndecidable admits only "escalate" — the same shape as aegis:onTimeout admitting only "deny". That is the decidability rescue: evaluate at the deepest layer where the constraint still decides, or hand it to a human. A constraint that silently stops applying where it cannot be checked is one an agent escapes by dispatching into a context where the evidence is absent.

A Σ where no constraint declares inheritedByDelegates reports an incompleteness, never a clean pass: “nothing is inherited” and “nothing has said whether anything is inherited” are different states.

quipu propose

Schema-change proposal queue: submit a shapes/ontology change for review rather than applying it directly.

quipu propose list --status pending --db my.db
quipu propose submit shape ex:PersonShape new-shape.ttl --proposer agent-1 --rationale "tighten cardinality"
quipu propose accept 3 --note "LGTM" --db my.db
quipu propose reject 4 --note "breaks existing data" --db my.db

quipu policy

Policy by example: draft a placement-aimed advisory policy from an exemplar, then replay it over recorded history before anything is created. The ordering is the point — draft, backtest, read the hit list, and only then quipu knot the file, at which point the definition-time placement check still runs and can still refuse.

quipu policy draft --exemplar http://example.org/verdict/17 --name no-bare-secrets \
  --label "never commit a bare secret again" \
  --targets http://example.org/CodeEdit \
  --claim 'ASK { FILTER NOT EXISTS { $target ex:containsSecret true } }' \
  --out draft.ttl
quipu policy backtest draft.ttl --last-txs 500 --db my.db
quipu knot draft.ttl --db my.db

draft flags:

A drafted policy is born advisory — aegis:effect "warn" is a constant, not a flag. Promotion to enforcement goes through the existing advisory→enforcing gates over recorded traffic.

backtest flags:

Output is one line per hit (tx <id> (<timestamp>): would have fired on <target>) followed by a summary. The summary distinguishes “0 hits” from “cannot evaluate”, and the command exits 1 when nothing could be measured so a script that knots on success cannot read an unevaluable candidate as clean.

quipu gate shadow

Judge a candidate policy set over recorded history before any of it is created, and report which committed writes it would refuse that the governing set admitted (and the reverse). Never writes.

sqlite3 live.db ".backup copy.db"      # a quiescent copy, never the live store
quipu gate shadow --rules candidate.ttl --db copy.db --since 7d
quipu gate shadow --rules candidate.ttl --db copy.db --from-tx 1000 --to-tx 2000 --json

Each transaction is judged by the write gate’s own evaluator against the post-state it saw, with the router read as of that transaction’s time. The baseline is the policy set in force at that transaction, so a policy change inside the window is reported as a boundary and never attributed to the candidate.

Refusals, not advice. The command refuses the configured live store and any path with a -wal, -shm or -journal sidecar (an open connection, or a copy taken mid-write): it reads with SQLite immutable=1, which ignores locks and the WAL and could see torn state on a live file.

Limits it reports rather than hides: refused writes are rolled back and cannot be replayed, so they are counted, not judged; recorded verdicts are joined by aegis:gatedTx when present and otherwise by the next-transaction convention, with the match rate printed (and UNMEASURED when nothing joined); and a baseline that would refuse a committed write is counted as the fidelity signal (enforcement off then, an approval, or a reconstruction gap).

quipu path

Golden-path analysis over recorded trajectories: the provenance cone, the backtest, and a grammar draft. All three are reads; draft prints Turtle for a human to review and load. See the golden paths design.

quipu path cone http://example.org/traj/42 --via http://example.org/derivedFrom --hops 6 --db my.db
quipu path backtest http://example.org/traj/42 --omit http://example.org/step/3 --json --db my.db
quipu path draft http://example.org/traj/42 --name fast-review --label "the short path" \
  --via http://example.org/derivedFrom \
  --omit http://example.org/step/3 --by http://example.org/decision/9 --db my.db

The trajectory IRI is the first positional argument to every subcommand.

cone verdicts are IN-CONE (load-bearing; pruning needs a human Decision), OUT-OF-CONE (mechanically prunable) or CANNOT-EVALUATE (no derivation edges recorded — never silently prunable). draft refuses when the count of --omit flags does not match the count of --by flags: a human cut without its Decision is a silent edit of history.

quipu ontology

Manage stored OWL ontologies (versioned: re-loading a name closes the prior version). Requires the owl feature.

quipu ontology load my-domain domain.ttl --db my.db
quipu ontology list --db my.db
quipu ontology remove my-domain --db my.db

quipu doctor labels

Diagnose graph-label state: which graphs carry freshness/trust/policy labels and which are undeclared.

quipu doctor labels --db my.db

quipu pack / quipu unpack

Knowledge packs: export one named graph as a self-describing, attachable .pendant.db artifact (facts, manifest, shapes, stored queries, optionally vectors), verify one, or import one into a local graph.

quipu pack urn:example:graph --out domain.pendant.db --name "domain" --version 1.0.0
quipu pack urn:example:graph --out domain.pendant.db --shapes s.ttl --queries q.json --with-vectors
quipu pack urn:example:graph --out domain.pendant.db --space 7
quipu pack --verify domain.pendant.db
quipu pack urn:example:repo --out repo.pendant.db --repo scbrown/example --repo-sha "$BASE_SHA" --model-id all-MiniLM-L6-v2 --model-version 1
quipu unpack repo.pendant.db --expect-repo scbrown/example --head-sha "$(git rev-parse HEAD)" --into urn:local:domain --db my.db

Repository packs should be attached to a GitHub release, not committed to the repository, once they exceed 10 MiB. A loader must download to a temporary path, run quipu pack --verify, and delete a failed download before opening the destination. quipu unpack repeats verification before every load. After a successful load, ingest repository changes over repository_sha..head_sha; future setup runs are incremental because the destination records the verified content hash and returns unchanged for the same asset.

quipu pack --full --format text

A lossless whole-store pack rendered as text. --full on its own is lossless but binary (a VACUUM INTO copy); quipu share is text but carries only current facts. This is the artifact that is both: git-friendly and reconstructing.

quipu pack --full --format text --destination internal --out store-pack/ --db my.db
quipu restore store-pack/ --db restored.db

It writes a directory, not a file:

store-pack/
  manifest.json     what the pack claims, including its content hash
  schema.sql        DDL for every object, applied before any row
  data/<table>.sql  canonical INSERTs, one file per table

Rows are emitted as one INSERT each, ordered by the row text itself. That ordering is what makes the format git-friendly: a row moving on disk produces no diff, so a pack committed to a repository only changes when its contents do.

restore accepts either form. For a text pack it rebuilds the store, checks referential integrity, and then refuses unless the reconstruction hashes identically to what the manifest claims — nothing is written to the destination until that holds. A dump missing a file, a table, or a single row is rejected rather than installed as a quietly smaller store.

A text pack does not carry derived data (vectors), because hex-encoded embeddings would make it gigabytes. It records the row count and the embedding recipe instead, and restore prints a REGENERATE: line so an incomplete store cannot be mistaken for a complete one. At pack time, omitted vector rows with a missing model name or SHA-256 digest make packing refuse with exit code 1 before writing the destination. To explicitly accept a backup without reproducible vectors, pass --allow-missing-embedding-recipe; this succeeds with a WARNING: on stderr and preserves the incomplete recipe honestly. Set [quipu.embedding] model_path to the original readable model file and repack to record its name, digest, and configured dimension. A recorded recipe identifies the configured model; it does not verify that this model produced the source vectors. An empty vector table needs no warning. Binary pack --full retains vectors and does not require a regeneration recipe.

Like --full, this refuses an outward destination: it carries the event log and every operational table, and publishing one is the operator’s decision.

quipu graph

The graph-registry commands: offline import, and the deep-freeze lifecycle (see Graph Kinds & Deep Freeze).

quipu graph import other.db --as urn:app:imported --db my.db
quipu graph freeze urn:app:runs/2026-07 --out /var/quipu/archive --db my.db
quipu graph thaw urn:app:runs/2026-07 --db my.db
quipu graph list --kind operational --db my.db
quipu graph list --frozen --db my.db

freeze exports the graph’s full history to a .pendant.db archive, verifies it by content hash, deletes the local rows and re-attaches the pack read-only; the graph stays queryable at the same IRI and refuses writes until thaw. list prints iri class kind lifecycle source per graph.

quipu import

Stage a git-native share directory without touching ROOT:

quipu import ./share --source https://example.org/alice --db my.db
quipu import promote sha256:0123... --actor reviewer --db my.db

The first command reads manifest.json, export.nt, and shapes.ttl, verifies their hashes, resolves exact local identities, surfaces fuzzy review candidates, and quarantines facts that fail local vocabulary or SHACL checks. The second is the separate, explicit ROOT-admission step and only accepts eligible staged shares. Both print the same JSON fields as the REST endpoints.

quipu fork

Persistent named forks (quipu-gp5): fork ROOT as of any transaction into an independent committed-class named graph (urn:quipu:fork:<name>), read it exactly like the main line, diff it, then drop it or promote it. Promotion re-enters through the SHACL + policy write gates — a refused promotion writes nothing and the fork stays open. Fork ergonomics are never a gate bypass.

quipu fork 42 --name experiment --db my.db     # fork ROOT as of tx 42
quipu fork list --db my.db
quipu read "SELECT ?s ?p ?o WHERE { ?s ?p ?o }" --fork experiment --db my.db
quipu fork diff main experiment --db my.db     # each side: a fork name, or 'main'
quipu fork promote experiment --db my.db       # delta re-enters via the gates
quipu fork drop experiment --db my.db          # terminal; the name is not reusable

Reads: --fork <name> on quipu read, or the fork field on POST /query / quipu_query. Unknown and dropped forks are refused loudly — never a silent fall-through to ROOT.

quipu db attach --list

List the databases mounted alongside this store — the [[quipu.attachments]] layers (see Configuration) and deep freeze’s archives, which no config declares.

quipu db attach --list --db my.db

Output is alias, path, and mount mode (always ro), tab-separated. A declared layer that could not be mounted refuses the open instead of appearing here, so everything listed is genuinely composed.

quipu db respace

Move a store into a fresh term space so it can be attached to another store without id collisions. Reads the source read-only; writes a new file.

quipu db respace --into 7 --out respace.db --db my.db

quipu events refusals

Count refused writes by gate (shacl | policy | authority | owl | placement) — the incident-rate denominator. Reads the write.refused events the write gates record; the raw events are served by GET /events?types=write.refused. See the REST API reference for what a refusal event records (metadata only, never the refused bodies) and the speculate exclusion.

quipu events refusals --db my.db

quipu graph import <db>

Import another quipu database’s ROOT graph as a named graph in this store.

quipu graph import other.db --as urn:import:other --db my.db

quipu migrate-vectors

Migrate stored embeddings between vector backends (requires the lancedb feature).

quipu migrate-vectors --from sqlite --to lancedb --dry-run --db my.db

quipu hook session-capture and quipu hooks

quipu ships one agent hook: a Stop hook that asks the agent, once per session, whether the session produced durable knowledge worth writing as an episode. The agent may act or reply skip; the hook never blocks a second stop.

quipu hooks bundle                      # print the hook bundle (schema st.hook-bundle/1)
quipu hooks install --harness claude    # merge into ~/.claude/settings.json
quipu hooks install --harness codex     # merge into $CODEX_HOME/config.toml (default ~/.codex)
quipu hooks status                      # exit 1 unless every harness has the hook
quipu hooks uninstall                   # remove only quipu's hook

With no --harness, both harnesses are written. --project writes ./.claude/settings.json or ./.codex/config.toml instead. Install is idempotent, leaves every other hook in place, and keeps the previous file as <file>.bak-quipu. When a shantytown registry answers (st ops hooks list), install and uninstall register the bundle with st instead, which renders it into every role’s settings; pass --no-st to write the harness config directly.

The hook itself, quipu hook session-capture, reads the Stop-hook JSON on stdin and prints at most one response. It always exits 0, and every failure is silence rather than a malformed response. Its guards, in order:

1. Scope. The crew comes from GT_CREW, else from a .../crew/<name>/... working directory. An unidentified crew is never interrupted. QUIPU_HOOK_CREWS (space-separated, default *) narrows the scope.
2. Loop guard. stop_hook_active: true means the hook already fired this turn, so it stays silent.
3. Once per session. A solicited-<session_id> marker in the state directory. Markers older than two days are reaped.
4. Durable denominator. Each solicitation appends {ts, session_id, crew} to solicit-log.jsonl before it is sent. If that append fails the hook stays silent, so the log can never undercount.

The message prefers authenticated Quipu MCP tools or the deployment’s gated graph-extract helper. For HTTP fallback, /search stays open, but /shapes vocabulary reads require a bearer just like /episode and /propose. The agent resolves a non-empty QUIPU_AUTH_TOKEN, then QUIPU_AUTH_TOKEN_FILE or the configured client token file. A missing credential stops the request before HTTP; it is not a reason to send an unauthenticated probe. Credentials stay server-side where possible and must never be printed. Requests carry X-Quipu-Client: session-capture. The act rate is episodes whose source carries the session id / lines in solicit-log.jsonl.

Create and label named graphs

quipu graph create urn:example:jobs --actor urn:example:agent --db tutorial.db
quipu graph label urn:example:jobs --label '{"kind":"operational","freshness":"fresh"}' --db tutorial.db
quipu graph list --json --db tutorial.db

Both verbs call the same handlers as MCP/REST. --timestamp <RFC3339> pins the creation/declaration time; otherwise current UTC is used. --actor is declared provenance, not authorization. Create is idempotent and preserves the original provenance. Label fields match quipu_graph_label, including trust, policy, durability and validity bounds. JSON listing exposes creation and all labels; the existing tab-separated listing remains the default.

graph overlay-create, graph overlay-write, and graph overlay-compose accept --input '<JSON object>' using the corresponding MCP tool input fields. For the complete new-class write recipe, see named graphs through MCP.

CLI: sharing, import and legacy packs

Reference for the commands behind Sharing & Federation. Every flag here is checked against quipu --help by tests/cli_doc_drift.rs, so this page cannot quietly fall behind the binary.

A note on vocabulary: the share is the portable artifact. quipu share writes its standard text files directly; releases may carry the same files in a deterministic .pendant.tar.gz archive. The older pack and unpack commands remain for local SQLite compatibility, but a .pendant.db is not the published interchange format.

quipu share — produce a share

Prerequisite: load the identifier-policy catalogue and the shapes governing your data. The default destination is outward. An empty block-tier catalogue exits 2 (cannot verify); a matching identifier exits 1; a checked, clean share exits 0. --no-shapes does not bypass this check.

quipu share --output <dir> [--graph IRI|--group-id ID|--construct QUERY]
            [--shapes NAME]... [--no-shapes] [--queries NAME]... [--no-queries]
            [--parent-share ID] [--since <parent-reference>] [--turtle]
            [--destination internal]

Writes a deterministic, git-native share into <dir>: RDFC-1.0 canonical export.nt (the facts), shapes.ttl (the constraints they were validated against), queries.ttl (the stored queries that answer questions about them, when there are any), and JSON plus PROV-O/DCAT/SPDX Turtle manifests.

The outward scrub, and --destination internal

Every share is checked against the store’s own aegis:InternalIdentifierPattern catalogue — the rules tiered block — and refused if the payload matches one. Nothing is rewritten: an internal hostname or an RFC1918 address is entity identity, and silently editing it would produce a share that says something the store never said.

That is the right default for a share bound for a public remote, and the wrong one for a share bound for an internal forge, where those identifiers are the point. --destination internal is the single explicit way to say so:

quipu share --output pendant/today --destination internal

It does three things, and the third is what makes the first two safe:

1. Skips the outward scrub entirely. Not a per-pattern exception, not an allowlist — the check does not run.
2. Stamps destination: "internal" into manifest.json, and quipu:destination "internal" into manifest.ttl. The exemption travels with the bytes instead of living in the shell history of whoever produced them.
3. Binds that stamp into share_id. Unlike attestation, the field is not stripped before the manifest is hashed. Deleting it to launder the payload onward leaves a manifest that no longer hashes to the id it carries, and every consumer’s verification refuses it.

There is no environment variable and no config setting. A share that says nothing is scrubbed, including every share produced over HTTP: POST /share cannot select a destination, because a caller who could would be turning the guard off on a server they do not own.

What the marker buys you downstream. quipu import of a stamped share runs the scrub the producer skipped. If the payload passes it imports normally — a share marked internal out of caution is not quarantined for it. If the payload fails, the import is refused unless the operator repeats the declaration with quipu import <dir> --destination internal. So internal facts cannot enter a store silently and then leave it in someone else’s outward share.

Deltas are scrubbed separately, and they have to be. delta.ru is not built from the store: its DELETE clause is lifted verbatim from the parent’s export.nt. An identifier retracted from the graph yesterday is still quoted in today’s delta — and the parent is usually the very internal share that was allowed to carry it. A full outward share of the same store passes cleanly while that delta does not, which is exactly why the delta document gets its own check rather than riding on the result share’s.

--since compares the current share with the referenced parent. Its default 8 MiB limit applies to the serialized delta file map (update, shapes and manifests), not to the full result graph. A large unchanged graph can therefore produce a small delta; a large insertion or deletion can still exceed the limit. The producer still materializes the full result internally, so this transport limit is not a memory bound. Use --parent-share to record an identity without computing a delta.

--parent-share is what makes quipu merge possible later. A share without a parent cannot be three-way merged — merge refuses with “incoming share has no parent_share; three-way merge has no base” — so record it at production time, when you know it, rather than trying to reconstruct it at reconnect time.

Stored queries (queries.ttl)

A share carries the stored queries quipu_ask answers by name, so a pendant ships its competency questions beside its data. Each query is described as RDF in queries.ttl; the manifest seals that file’s SHA-256 as queries_hash and it takes part in the share_id, so changing one query’s text changes the share’s identity. A share with no queries has no queries.ttl and a manifest byte-identical to one produced before the member existed.

@prefix dct: <http://purl.org/dc/terms/> .
@prefix quipu: <https://quipu.dev/ontology/> .

<urn:quipu:query:members-of> a quipu:StoredQuery ;
  quipu:queryName "members-of" ;
  quipu:queryForm "SELECT" ;
  dct:description "Who belongs to a team" ;
  quipu:parameter [ a quipu:QueryParameter ; quipu:parameterName "team" ;
    quipu:parameterIndex 0 ; quipu:parameterKind "iri" ; quipu:required true ] ;
  quipu:sparqlTemplate """SELECT ?p WHERE { ?p <http://example.org/memberOf> <{team}> }""" .

quipu:targetsClass lists every constant rdf:type object in the template’s patterns. The vocabulary is governed by shapes/stored-queries.ttl, which the producer and the importer both apply.

Which queries a share carries by default. A query is registered against the shared graph when quipu_ask would answer it from that graph: an unscoped query (no dataset) belongs to a ROOT share and to --group-id and --construct slices of ROOT; a dataset-scoped query belongs to a --graph <IRI> share whose IRI is a member of its dataset, and to nothing else. The dataset IRI itself is producer-local and is not carried.

A carried query is data, not code. Only SELECT, CONSTRUCT, ASK and DESCRIBE travel. The form is decided by parsing the template with Quipu’s SPARQL parser — at share time and again at import — and a SPARQL Update is refused at both ends. Import evaluates nothing: a query runs only when somebody asks for it, under the receiver’s normal read policy and timeouts.

Import namespaces and never overwrites. Carried queries install in the receiver’s registry as <namespace>/<name>. The namespace defaults to pack-<12 hex> derived from the producer’s store identity, so newer shares of the same pack land on the same names; --query-namespace chooses one. A local query with the same name is never touched. A different definition already at a pack-scoped name is reported under queries.collisions and left in place, and a pack-scoped query the share no longer carries is reported as stale. --replace-queries replaces the differing ones and closes the stale ones (closed, never deleted — the prior version stays queryable). A query that targets a class the receiver’s loaded shapes do not sanction adds the blocker query_off_vocabulary: the pack is quarantined and none of its queries is installed. A full share installs its queries when it stages, before promotion, so run quipu import promote before asking questions of the staged data in ROOT.

A delta share carries the resulting share’s complete queries.ttl, like its shapes, so queries added, replaced or removed since the parent arrive as what the member now says, sealed by the result manifest’s queries_hash.

quipu import — receive a share, into quarantine

quipu import <share-dir|archive|URL> [--source <uri>] [--actor <id>]
            [--destination internal] [--query-namespace NS]
            [--replace-queries] [--db <path>]
quipu import delta <parent-share> <delta-share> [--actor <id>]
            [--query-namespace NS]

Verifies the manifest and payload hashes, then stages a local directory in its selected store. Archives and URLs are fetched under fixed size limits and materialized in a fresh in-memory store by default, so no downloaded artifact or database is left behind. With an explicit --db <path>, archives and URLs stage in that database using its loaded shapes and registered identities, just like a directory. Carried shapes are not automatically adopted: a receiver without a matching local vocabulary still quarantines the typed data. Import never touches ROOT without promotion. A hash mismatch is refused outright:

share graph hash mismatch: manifest=… actual=…

import delta verifies the full parent and the delta’s lineage, hashes and restricted DELETE DATA / INSERT DATA operations, materializes the declared result, then sends that result through the same verified in-memory import path.

Loaded local shapes determine admission. Their explicit quipu:onViolation "emit" diagnostics are advisory; reject-policy Violations quarantine the share. Missing policies mean reject, and unknown or conflicting policy values refuse. Carried shapes cannot downgrade a local reject policy. The report keeps strict conforms separate from blocking, with complete diagnostics and advisory_results. An emit-only Violation can therefore produce conforms: false with blocking: false. Vocabulary, integrity, trust and explicit promotion requirements still apply.

quipu import promote — admit a staged share into ROOT

quipu import promote <share-id> [--actor <id>] [--db <path>]

The second, separate verb. Nothing reaches ROOT because a file arrived; it reaches ROOT because someone ran this. Keeping admission in its own command is the point rather than an inconvenience — see the primitive.

The project graph: quipu share --project and quipu load

quipu share --project [<id>] [--no-shapes] [--destination internal] [--db <path>]
quipu load <bundle-dir> [--destination internal] [--actor <id>] [--db <path>]

A repository commits its project’s graph under .quipu/, tool-neutral:

share --project <id> names the project once (it is then committed) and re-shares the graph into .quipu/graph/. Re-running it replaces the bundle; it never re-points a repository at a different id. The outward scrub applies exactly as for any share, because the repository may be public; use --destination internal only for a private one.

load <dir>, on a directory holding a share manifest, is the one command a fresh clone needs:

git clone <repo> && cd <repo>
quipu load .quipu/graph --db .quipu/local.db

It runs the ordinary import, with every gate import has, and then promotes into the bundle’s own graph instead of ROOT, as a diff. A re-load after git pull changes only what changed; an unchanged bundle opens no transaction. A quarantined import loads nothing. load <file.ttl> still means knot.

The server equivalent is POST /import of the same bundle, which stages it.

quipu status — has this share diverged?

quipu status <share-dir> [--db <path>]

Reports divergence between the local store and the share’s parent, as JSON. Read it before merge to see what a reconnect would have to decide.

quipu merge — three-way reconnect

quipu merge <share-dir> [--actor <id>] [--db <path>]

Locates the common base through parent_share, merges shape-aware (SHACL cardinalities decide what is a conflict), and on conflict keeps the base value and records a decision rather than guessing.

Exit 2 is a distinct code precisely so a script can tell “needs a decision” from “went wrong”.

Resolving conflicts: emit, propose, decide, apply

quipu merge <share-dir> --emit-decisions <file.json> [--slot-scoped] [--propose] [--db <path>]
quipu merge <share-dir> --decisions <file.json> --reviewer <who> [--dry-run] [--actor <id>] [--db <path>]

The same split as quipu align: a merge that cannot auto-merge is finished by a person, with the evidence in front of them.

1. Emit. --emit-decisions writes one row per conflict to a JSON file and changes nothing. Each row has the slot (subject, predicate, max_count), the base / ours / theirs values, and each side’s provenance: ROOT’s current facts with their valid_from, transaction, actor and source; the incoming and base shares’ id, created_at, producer store and whether they are attested. For a person reading it, each row also has a kind (max_count_exceeded or delete_replace) and a rule in words (“sh:maxCount 1 on status: ours and theirs together hold 2 values”), and the file carries labels: one rdfs:label per IRI it mentions. Default emission stays v1, strictly bound to all ROOT changes. Explicit --slot-scoped (REST/MCP: slot_scoped: true) emits v2. These files bind each reviewed slot’s current values, local provenance and last-modifying ROOT transaction (including retractions) through local_slot_hash, plus the incoming share and base identities. Unrelated ROOT writes can survive an apply; the clean merge is recomputed against current ROOT. A slot changed and restored is stale, including empty -> value -> empty. Legacy v1 files and files with blank-node conflict subjects retain the conservative whole-ROOT binding. Older clients refuse v2 files; re-emit with the client that will apply the decisions.
2. Propose (agent). --propose also fills each row’s proposal (choose plus evidence) from mechanical evidence: a side unchanged from base, the newer side, an attested share. It never sets decision.
3. Decide (operator, or any tool that edits the file). A tool may also set decided_by and decided_at per row; apply echoes them back. They are a claim made by that tool. The attested record is the transaction’s reviewer and the decisions file’s hash. Set each row’s decision to {"choose": "ours"}, {"choose": "theirs"}, {"choose": "base"}, or {"values": ["\"an edited value\""]} (N-Triples terms).
4. Apply. --decisions commits the clean part of the merge plus every decided slot in one transaction. Its source records both parents, the reviewer and the SHA-256 of the decisions file, and the output lists each applied row.

Apply refuses, and writes nothing, when:

--dry-run runs every check above and reports the counts that apply would assert and retract, without writing anything. A CI check uses it to validate a decided file before merge.

Plain quipu merge without these flags behaves as before.

quipu pack / quipu unpack — legacy SQLite compatibility

quipu pack <graph-iri> --out <file.pendant.db> [--name N] [--version V] [--space N]
           [--shapes S]... [--queries Q]... [--with-vectors] [--format turtle]
quipu pack --verify <file.pendant.db>
quipu unpack <file.pendant.db> [--into <graph-iri>] [--db <path>]

--verify answers whether a legacy SQLite pack is intact before loading it. New repository and release workflows use share and import; they do not publish .pendant.db files.

quipu pack --full / quipu restore — whole-store packs

A --full pack is a different artifact from everything above: not a graph, but the whole store, carried losslessly for internal backup. share carries current facts; --full carries facts as whole rows — g, tx, valid_from, valid_to, op, retracted_tx — so history, including what was retracted, travels with it.

quipu pack --full [--format text] --destination internal --out <path> [--db <path>]
quipu restore <file.pendant | text-pack-dir> [--force] [--db <path>]

Both forms refuse an outward destination, and that refusal is atomic — no output is left behind. A full pack carries the event log and every operational table that is not explicitly excluded, so publishing one is the operator’s decision rather than something this command may acquire by convenience.

--format text does not transport the declared regenerated set. Today that is vectors: embeddings are derived data, roughly 2.2 GB of floats at homelab scale, and quote() renders a BLOB as X'<hex>' — so inlining them would produce a 4–5 GB “git-friendly” artifact, which is not one. The manifest instead records what was left out, how many rows it was, and the recipe to rebuild it (embedding model name, its SHA-256, and the dimension), and restore prints a REGENERATE: line naming them. A restore from a text pack is therefore complete in facts, history and provenance, and not complete in derived data until those are rebuilt — which is why it says so rather than reporting plain success.

The binary --full pack still transports vectors: a backup that forces a re-embed on restore is a poor backup. The two whole-store packs therefore carry different content by design, and their content hashes are not comparable to each other.

--format text writes manifest.json, schema.sql, and data/<table>.sql. Rows are emitted one INSERT per line, ordered by the row text itself, so a row moving on disk produces no diff and a committed pack changes only when its contents do. restore rebuilds the store, checks referential integrity, and refuses unless the reconstruction hashes identically to what the manifest claims — nothing reaches the destination until that holds, so a dump missing a file, a table or a single row is rejected rather than installed as a quietly smaller store.

restore REPLACES; to merge a published pack into an existing store use unpack. Each verb refuses the other’s format by name rather than reporting an intact artifact as corrupt.

quipu knot — assert facts, including identity across stores

quipu knot <file.ttl> [--graph <iri>] [--shapes <shapes.ttl>]
           [--timestamp <ISO-8601>] [--db <path>]

Asserts Turtle into the store, validated against shapes. In the sharing context this is how owl:sameAs between two stores’ IRIs gets written — identity is a fact in the graph, visible and retractable, not a string-matching heuristic.

quipu load is an alias for knot.

Archives

quipu graph freeze <iri> [--out <dir>] [--actor <who>] [--db <path>]
quipu graph thaw <iri> [--actor <who>] [--db <path>]
quipu graph list [--kind <token>] [--frozen] [--db <path>]

Deep freeze produces read-only, full-history graphs. See Graph Kinds & Deep Freeze.

Producer attestation and the three trust tiers

A share can carry a signed statement of who produced it. Every import reports the tier it reached, and the three are genuinely different claims — not degrees of the same one.

Minting a share with an attestation

quipu share --output <dir> ... --attest \
  --attest-agent <agent> --attest-session <session> --attest-introducer <who> \
  --attest-issued-at <epoch> --attest-nonce <32 hex chars> \
  [--attest-key <path>] [--attest-ttl <secs>]

--attest-issued-at is required rather than defaulted to the wall clock: two runs over one pinned dataset must produce the same signed bytes, or the share is not re-derivable. --attest-nonce must be 32 lowercase hex characters and is checked at mint time — a share minted with any other nonce is refused by every importer.

The key comes from --attest-key, else $QUIPU_SIGNING_KEY, else .quipu/verifier.pk8, created 0600 on first use. That is v1 host-file custody, the same the governance plane uses; it is not an HSM.

Registering a producer, out of band

quipu attest register --agent <a> --session <s> --public-key <hex> \
  --introducer <who> --issued-at <epoch> --expires-at <epoch> [--allow-write] [--db <path>]
quipu attest allow-write|deny-write <session> [--db <path>]
quipu attest revoke <session> [--db <path>]
quipu attest list [--db <path>]

A binding is share-only unless an operator grants it write (--allow-write at registration, or allow-write later). Only then may its key sign HTTP writes. list prints each binding’s allow_write, expires_at and revoked, so the scope a key holds is visible without reading the store. revoke keeps the row: a revoked binding refuses as revoked, which is a different finding from an unbound key. Rotation is a new binding plus a revoke of the old one.

To set up an agent end to end (its own user, sd key init, enrollment, verification and revocation), follow CABOODLE’s agent identity and write access guide.

Importing a share never registers its producer. This is the point, not an omission: a key that vouches for the bundle it arrived in vouches for nothing, and an attacker substituting the whole bundle would substitute the key with it. Registration is a separate act by the consumer, using a key obtained some other way — the same rule the governance plane states as quipu never self-registers.

So a first import from an unknown producer reports claimed, and reports it honestly. Reaching attested requires someone to decide that this key is that producer.

Automated callers should require attested. Accepting claimed is reasonable, but it should be a deliberate choice by a caller who says so, not the effect of a tier that merely does not read as failure.

Keeping this page honest

tests/cli_doc_drift.rs reconciles three surfaces: the dispatch arms in src/main.rs, the --help text, and this page. Checking any two is not enough — when that test was written, --help documented share, status, merge and unpack but not import, so a page-versus-help check would have passed while the verb that receives a share stayed undiscoverable.

quipu share diff — what changed between two packs

quipu share diff <old> <new> [--format text|markdown|json]

Each side is a pack directory (the standard artifact’s payload.nq, else a legacy share’s export.nt) or a single N-Triples/N-Quads file. Like the Git transport commands below, it reads files only and opens no store.

The diff compares facts, not lines, and groups them by subject entity:

~ Alice (people/alice)
  ~ age: "30"^^xsd:integer -> "31"^^xsd:integer
  - nickname: "Al"
+ Carol (people/carol)
  + rdfs:label: "Carol"
  + role: "designer"
2 entities: 1 changed, 2 added, 1 removed facts

That is the whole output for the fixture pair in tests/fixtures/share-diff/, whose raw line diff is 11 lines of full IRIs and blank-node labels: Alice’s address is a blank node that RDFC relabelled (_:b0 to _:c14n7) without any change to its content, and it contributes nothing.

• An entity is shown by its rdfs:label with a compact name beside it; an unlabelled IRI is shown compactly (prefix:local for well-known vocabularies, otherwise its last two path segments). Predicates show their label or local name. When two distinct predicates under one entity would show the same name (ex:name and schema:name both labelled “name”, or two IRIs ending /name), each carries its compact IRI — name (ex/name), name (schema:name) — or its full IRI if even those collide. Compaction depends only on the IRI, never on the data, so both sides of a diff name things the same way.
• ~ predicate: old -> new is reported only when the slot (subject, predicate, graph) holds exactly one value on both sides. A multi-valued slot shows its removed and added values separately.
• Blank nodes are matched by structure, not label. RDFC-1.0 can relabel every blank node between two versions of a payload; a pure relabel is zero lines. A blank node referenced from another node is shown inline ([ city "Paris" ; zip "75001" ]) as part of the referencing fact, so an edit inside it is a change of that fact. Structurally identical blank nodes on one slot are one fact with a count: cardinality matters to shapes (sh:maxCount), so adding a second copy is shown as ~ p: [ r "v" ] x1 -> [ r "v" ] x2, and the textconv marks a fact asserted more than once with xN. Limits: identical values nested inside an inlined blank node still collapse; a blank node referenced only from inside a blank-node cycle has no named root and is not shown; a blank graph name is keyed by its label.
• --format markdown suits a PR comment; --format json is the same structure (entities[].changed/added/removed, plus totals) for tools.

quipu share diff --report — the pull-request review

quipu share diff <old> <new> --report [--format markdown|json]
    [--old-shapes <ttl>] [--new-shapes <ttl>] [--decisions <json>]
    [--fail-on-introduced]

The report a reviewer reads when a pull request changes a pack. When <old> and <new> are pack directories, each side’s shapes.ttl and the new side’s decisions.json are picked up from the directory; the flags name them explicitly otherwise. The repository’s pendant review workflow (.github/workflows/pendant-review.yml) runs it for every pack a pull request touches and publishes the result as the check’s job summary.

Reading the PR report

Sections always appear in this order:

1. Facts. The quipu share diff output above: per-entity changed, added and removed facts, by label.
2. SHACL violations introduced. Old data is validated against the old pack’s shapes, new data against the new pack’s shapes, and the report lists the violations that occur more often in new than in old, keyed by focus node, path, constraint component and value. A violation already present before the change is counted as pre-existing, never as introduced; the count of violations the change resolves is shown beside it. When the shapes change, a row whose old data already fails the NEW shapes is marked shapes change: the data did not move, the rules did, and the pack still stops conforming. If the new pack ships no shapes, or the binary was built without the shacl feature, the section says NOT CHECKED. That is not a zero, and --fail-on-introduced refuses (exit 1) on a build without SHACL rather than pass. A surviving pack with missing new shapes also refuses this gate. Whole pack deletion is distinguished by the workflow only when every artifact file is absent at the head; incomplete surviving packs refuse. No new-head validation is claimed for a proven deletion. Blank-node labels are collapsed when matching, because RDFC may relabel every blank node between versions.
3. Merge decisions. When the change carries a decisions.json sidecar from quipu git-merge (see below), each conflict is listed with its subject, predicate, the constraint that made it a conflict (sh:maxCount 1), the base/ours/theirs values and the recorded resolution, or UNRESOLVED. Alias proposals recorded by the driver are listed the same way. The CI script renders a sidecar only when the pull request adds or changes it.
4. Alias caveat. Always present. A triple-level diff, merge or validation cannot see two different IRIs minted for one real entity; such a pair looks like two healthy entities. Below the caveat are advisory candidates: an entity ADDED by the change whose normalized label is at least 0.90 Jaro-Winkler-similar to a same-type entity in the old pack, or to another added entity. This is the merge driver’s proposer, reused. No candidates is not evidence of no aliases.
5. Summary. The report’s last line, used as the check annotation title:

pendant review: 1 entity changed (1 changed, 0 added, 0 removed facts); SHACL 0 introduced; no merge decisions; 0 alias candidates

--format json carries the same structure (diff, shacl, decisions, alias_candidates, summary). With --fail-on-introduced the exit status is 3 when at least one violation is introduced; the report is printed in full first.

The check is red only when a pack introduces a SHACL violation or its report cannot be computed. Everything else is information for the reviewer. A pack, for the workflow, is a directory holding export.nt or payload.nq together with manifest.json or manifest.ttl; the two versions compared are the merge-base version and the pull request head. The workflow runs with a read-only token. It can also keep one sticky PR comment up to date, but only when the repository variable QPACK_REVIEW_COMMENT is true: that job needs pull-requests: write, and granting it is a security-posture decision, so it is off by default.

High-stakes (class-B) DecisionRecords are not settled by approving the pull request. They are resolved through the hardware-signed human verdict tracked as aegis-kzt0ql.9; the report only shows them.

quipu diff-textconv — readable git diff for pack files

quipu diff-textconv <file>

Prints one payload file as stable, labelled, entity-grouped text: one header per entity (sorted by IRI, so a relabel never reorders the file), one predicate: value line per fact, blank nodes inline. Git’s textconv runs it on both sides of a diff, so an ordinary git diff, git log -p or git show reads like this instead of two lines of full IRIs:

@@ -1,5 +1,5 @@
 AAA Tracking (ability/aaa-tracking)
-  abbrev: "AAA"
+  abbrev: "AAA CHANGED"
   effectText: "x2 vs. air attacks"

Setup, once per clone (the attribute is already in this repository’s .gitattributes; add it to your own):

printf '*.nt diff=quipu\n*.nq diff=quipu\n' >> .gitattributes
git config diff.quipu.textconv "quipu diff-textconv"

Without the git config line the attribute is inert and Git diffs raw lines. git diff --no-textconv shows the raw form on demand. A file that does not parse (a working copy with merge conflict markers, say) is printed unchanged, so git diff never fails on it. Textconv affects display only: merges, hashes and pendant-check still operate on the canonical bytes.

Git transport: driver, decisions, and CI

These commands operate on repository files and immutable Git snapshots. They do not open a Quipu store. Use a build with the shacl feature (the default).

They shell out to the git executable found on PATH (the wrapper, the driver’s snapshot reads, the shapes three-way merge, and pendant-check all do). If git cannot be found, the command exits 1 with `git` executable not found on PATH and writes nothing.

quipu git-merge <ref>
quipu merge-driver <base-file> <ours-file> <theirs-file> <path>
quipu pendant-resolve <base-ref> <ours-ref> <theirs-ref> <dir> <key> <choice>
quipu pendant-check <base-ref> <ours-ref> <theirs-ref> <result-ref>

Version attributes for each share directory (adjust pendant to your layout):

pendant/export.nt merge=quipu
pendant/shapes.ttl merge=quipu
pendant/manifest.json merge=quipu
pendant/manifest.ttl merge=quipu

Start at the repository root with a clean index and worktree. Save the branch tips for later checks:

ours=$(git rev-parse HEAD)
theirs=$(git rev-parse topic)
base=$(git merge-base "$ours" "$theirs")
quipu git-merge "$theirs"

git-merge supplies a command-local merge.quipu.driver definition and the three immutable commit IDs to its child Git process. Nothing is installed in global Git configuration. This context matters: Git does not promise to merge shapes.ttl before export.nt. The driver reads and merges shapes from the three commits first, rather than trusting whichever working file happens to exist. Directly invoking the low-level driver without context refuses. Overlapping shape edits refuse before the wrapper changes the worktree; resolve those edits on the branches first. Criss-cross bases and incompatible store/scope/destination/layout metadata also refuse.

The graph operator is the same one used by store-level quipu merge. Functional conflicts retain the base value and create entries in decisions.json. No Git conflict markers are written to N-Triples. New entities from opposite branches with a common type are compared locally: whitespace-normalized, lowercase labels, Jaro-Winkler similarity at least 0.90, top five candidates per new entity. These are proposals, never automatic identity assertions. No paid model or network call is used. This baseline can miss aliases and can propose false matches; the decision belongs to the reviewer.

Exit 2 means decisions or Git conflicts remain. Inspect the sidecar, then choose:

quipu pendant-resolve "$base" "$ours" "$theirs" pendant conflict:0 ours
quipu pendant-resolve "$base" "$ours" "$theirs" pendant alias:0 reject

Conflict choices are base, ours, or theirs; alias choices are accept (add an explicit owl:sameAs) or reject (keep identities distinct). Resolution reconstructs the operator result from Git and refuses stale or altered proposal records. The last resolution must pass SHACL. It rewrites canonical export.nt, regenerates both manifests, drops old attestations and the optional derived export.ttl, and records parent_share=ours plus both IDs in merge_parents. Input tx_anchor and created_at remain the ours snapshot’s metadata; a Git merge does not fabricate a store transaction. Each file is replaced atomically; the directory is not a multi-file transaction, so the hash gate must pass before use. Review and stage the complete directory, then commit:

git add pendant
git commit
quipu pendant-check "$base" "$ours" "$theirs" HEAD

The wrapper always stops before commit, including clean merges. It reconciles whole pendants after Git because Git may skip individual drivers when one file is unchanged. Blank-node graphs currently refuse divergent merges: canonical blank labels are not stable identities across snapshots. Skolemize those nodes first.

CI is required even when local driver use is documented. A clone with no driver definition, a forge merge button, or a rebase can fall back to text merge. The repository’s SHACL test job runs scripts/ci/pendant-merge-check.py with full history and the PR’s synthetic merge commit. It also replays two-parent merges introduced on the topic branch, then reconstructs base/ours/theirs, requires recorded resolutions, compares the committed graph, shapes and manifest with the operator result, and validates SHACL. A hand-rehashed unsafe result still fails. Push/nightly runs validate the committed packs too; a squash commit alone cannot reconstruct the original branch pair, so the PR check remains load-bearing. Keep the SHACL test check required in branch protection.

Known gap: an administrator bypasses the gate. The replay that can actually fail is the PR check. On a push event the final replay is trivially (base, ours, theirs) = (before, before, result): a fast-forward of the previous tip, so it re-validates the committed packs but cannot reconstruct a merge that happened elsewhere. This repository’s main protection uses strict status checks, so a squash merge’s tree equals the synthetic merge commit the PR check tested. It does not enforce protection for administrators, so an admin’s direct push, or an admin merge that skips pending or failing checks, lands a pendant that no merge replay has verified. Treat an admin bypass as unverified and run quipu pendant-check on the original base/ours/theirs yourself, or enable “include administrators” if that gap is unacceptable.

Measured on the repository’s real Datalinks pendant, replacing the same functional value on both branches produces a text conflict, not a clean double. Git writes three marker lines into the RDF. Separate new IRIs with identical labels merge cleanly without an identity decision; disjoint additions merge cleanly and correctly. tests/git_qpack_merge.rs exercises those cases, decision resolution, and the driver-absent CI refusals using actual Git repositories.

Carry alignment evidence

quipu share --alignments FILE --output DIR carries an optional, hash-sealed alignments.ttl. Input is bounded UTF-8 Turtle; an explicit empty carrier is valid. The manifest seals its exact bytes and fixed filename in the share ID. Missing, altered, misnamed or undeclared evidence is refused before import stages data. Legacy shares without this member retain their existing identity.

This is evidence transport, not identity adoption. Imported bytes are retained separately; neither import nor ROOT promotion applies the mappings or loads their shapes. Use the existing alignment propose/decide/apply workflow for curation. The browser reader uses the same verification, and Explorer export preserves the imported carrier. A release needs a compatible engine and actual asset readback; source configuration alone does not establish availability.

Render graph data into owned files

qp render produces markdown locally from a stored specification or an ad-hoc query. A remote server prepares a read-only plan; the client writes the files. Templates have no file loader, network access or nondeterministic functions.

mkdir -p output
qp render --query 'SELECT ?title WHERE { VALUES ?title { "Example" } }' \
  --template '# {{ rows[0].title }}' --dest output/report --db private.db
qp render --query 'SELECT ?title WHERE { VALUES ?title { "Example" } }' \
  --template '# {{ rows[0].title }}' --dest output/report --db private.db --dry-run

The second command reports a no-op. Both the file and manifest retain their bytes and modification times. Dry-run prints the complete file list and the content/mode diff without creating directories, lockfiles, manifests or events. The destination’s parent must already exist.

Store the specification as data

@prefix render: <urn:quipu:render:> .
<urn:example:report> a render:RenderSpec ;
    render:query "SELECT ?title WHERE { VALUES ?title { 'Example' } }" ;
    render:format "markdown" ;
    render:layout "single" ;
    render:path "report.md" ;
    render:template "# {{ rows[0].title }}" .

Validate this file against the supplied shapes/render.ttl when importing it, then render <urn:example:report>:

qp knot report.ttl --shapes shapes/render.ttl --db private.db
qp render urn:example:report --dest output/stored --db private.db

A specification carries its query, layout, path, optional template, includes and optional provenance footer. markdown is the first format; the renderer trait leaves room for other document formats. Binary postprocessing is outside core. Stored specifications and included byte literals travel in a pendant. Normal share/export scrub and destination rules still apply.

Hierarchies and byte-exact includes

Use per-entity layout and a path such as {scope}/{slug}/SKILL.md. Each row has its own row context; single-file templates receive all sorted rows. The small deterministic template language supports loops, conditionals and the upper and lower filters on bounded strings. Fields, indexes, scalar literals, comparisons and boolean conditions are supported. Allocation operators (~, +, *, **), reassignment, captures, recursive loops, function calls and dynamic container literals are refused before template compilation. Templates are capped at 256 KiB and 4096 tokens; final files share one incremental 16 MiB budget. Undefined variables, path collisions, traversal, case aliases and incomplete queries refuse before publication.

Includes are a JSON literal in render:includes, or an includes column on per-entity rows. Each entry has a relative path, sha256: content address, base64 bytes and a mode of 0644 or 0755. Raw markdown templates can copy row.content without parsing or rewriting YAML front matter. Includes preserve executable modes and are verified against their hashes.

Render skills into their own root outside the harness’s skills directory, then let the existing tooling projection mount individual skill names. A scoped query can select internal skills. The renderer does not overwrite unrelated harness entries or manage those mounts.

Ownership, time and publication

.quipu-render.json records the specification, source_tx, valid_at, the render timestamp and every managed file’s hash/mode. The complete plan is prepared within one SQLite read snapshot. Present reads pin that transaction; historical --valid-at reads use the same snapshot without changing the native mixed-clock guard. A write committed during rendering cannot change the plan.

qp render urn:example:report --valid-at 2026-01-15T00:00:00Z \
  --dest output/historical --db private.db
qp render urn:example:report --dest output/remote --server https://graph.example

Remote /render requests require an accepted bearer even on a read-only server. The client follows the documented credential order: nonempty QUIPU_AUTH_TOKEN, then QUIPU_AUTH_TOKEN_FILE, then ~/.config/quipu/token. Credentials are never passed as arguments or printed. Without a configured credential, remote rendering refuses; local rendering requires no bearer.

Only manifest-owned files can be updated or removed. Unknown files, edited managed bytes, changed modes, symlinks and a changed destination refuse. The client stages a complete directory and atomically publishes it on Linux/macOS. New roots are private (0700); updates preserve the existing root mode. The manifest is private (0600). Parent directories are opened component by component with no-follow capabilities. Unchanged files retain their inode and modification time across an update. A failed or indeterminate publication is not permission to retry blindly; inspect the retained destination and any reported staging directory first.

The manifest is the receipt for the current render, not a disk-to-graph sync or an append-only audit history. Historical graph access, installed CLI identity, shape projection and a real consumer run are separate from source tests.

Recorded CLI demonstration

docs/probes/pr-demos/render/reproduce.py invokes the actual candidate CLI against a private temporary local store. The recorded result is:

{
  "target": "candidate CLI / private local store",
  "before": "destination absent",
  "first_files": [
    "report.md"
  ],
  "after_utf8": "# Example",
  "repeat_noop": true,
  "repeat_same_bytes_mtime_inode": true,
  "unknown_file_refused_and_preserved": true,
  "running_installation": "not invoked"
}

The absent destination becomes one markdown file; the repeated render preserves bytes, inodes and modification times. An unknown file is refused and preserved. This recording makes no installed-service or deployment claim.

REST API

Request logs distinguish caller-declared host and agent from the receiver’s observed network hop. Direct HTTP requests include transport_peer and transport_peer_source: "socket"; unavailable transport context is null with source "unavailable". A proxy’s socket identifies that proxy, not the originating agent. Internal MCP or stdio dispatch may have no socket context. Forwarded headers do not establish this observation, and neither a socket address nor a declared agent authenticates a writer. Credentials and request bodies are not included in these fields. Existing authorization outcomes remain separate.

Write-route logs also include the bounded declaration class in request_provenance and missing required field names in request_provenance_missing. These describe requests, including refusals; they do not assert that a transaction committed and must not replace committed write-coverage metrics. Model and session values are not added to logs.

The quipu-server binary exposes all Quipu operations over HTTP (Axum).

Versioned file-memory RPCs

These JSON operations are disabled by default. To use them, a deployment must register the graph and configure quipu.memory_files.enabled, graph, deployment and project. They create neither graphs nor credentials. An owner is the exact deployment, project and crew IRI tuple; labels and caller actor fields do not authenticate it.

Commit intents include owner, relative path, UTF-8 text, expected snapshot and file revisions, idempotency key, harness and opaque account label. Null text is an explicit tombstone. Receipt lookup precedes stale-parent rejection: replay the exact intent and key after an indeterminate result, rather than generating a new write. Stale new intents return HTTP 409; denied ownership returns 403. Disabled or invalid configuration refuses instead of accepting memory writes.

Requests are bounded to 1 MiB; a file is at most 256 KiB and an owner snapshot contains at most 128 entries and 4 MiB of live text. Existing graph, vocabulary, SHACL and write-policy checks remain in force. Projection reads data; it does not select or overwrite a native memory directory. See versioned file memory for the lossless envelope, local CLI workflow, public export boundary and filesystem/harness guarantees.

Queued write timeouts

When a request budget expires before a tool write starts, the server returns HTTP 503, Retry-After: 1, and a JSON error with code: "write_not_started", write_started: false, and waited_ms. This covers write admission and the first writer acquisition of the tool endpoints, including /episode and /set. The check runs before signed nonce settlement. The tool did not run, so the caller can retry after the indicated delay.

A real query timeout still returns 408 with query-specific advice. Do not infer that a write was unrun merely from a 408, a zero elapsed time, a transport failure, or a gateway error. A timeout after execution begins may have committed; verify the requested facts and preserve the same payload before retrying. These diagnostics do not change the configured request budget or bound direct protocol handlers that bypass tool-write admission.

Unrecognized request fields

Successful tool-backed JSON endpoints report unrecognized top-level request keys in a sorted ignored_fields array. Requests containing only recognized keys omit that field. The accepted keys come from the tool’s input schema, with HTTP adapter fields accounted for separately. /reason, /subscriptions, /graph/create, and /graph/label also report unrecognized keys. Errors retain their existing status and response body.

This is reporting, not rejection or a preview mode. For example, a successful POST /knot containing "dry_run": true still writes and includes "ignored_fields": ["dry_run"]. /knot does not support dry runs.

POST /export and /query responses negotiated as standard SPARQL results or RDF preserve their standard bodies and report the JSON array in the X-Quipu-Ignored-Fields response header instead. /search/nodes reports verbose as ignored; the separate /search_nodes endpoint supports it.

Reporting covers undeclared top-level fields, not nested keys, value types, or whether a recognized option applies to a particular action. It does not cover non-tool endpoints such as /share, /import, /import/promote, entity GETs, SPARQL protocol form fields, or direct Rust library calls. An absent warning on those surfaces is not evidence that every supplied field was used.

Starting the Server

quipu-server --db my.db --bind 0.0.0.0:3030

GET /.well-known/void

Returns a live VoID and SPARQL 1.1 Service Description projection. The default representation is Turtle; send Accept: application/ld+json for JSON-LD. The document advertises the query endpoint, exact dataset and named-graph counts, used vocabulary namespaces, executable result formats, and compiled entailment features. Quipu’s share manifest.json remains the integrity contract.

Read Concurrency

Reads are served from a pool of read-only connections; writes keep the single FIFO-fair writer connection. WAL already permits N concurrent readers alongside one writer — before the pool, every read took the writer’s mutex, so that capability was present and unused.

[quipu.server]
read_pool_size = 4    # 0 disables the pool; every read then serialises

MEASURED on a 160k-fact store, same binary, pool the only variable (server-CPU divided by wall time, so it counts cores actually used rather than inferring them):

quipu_store_wait_seconds_total — time spent acquiring, exported on /metrics — falls to 0.000s with the pool on. That is the number to watch: a rising wait means readers are queueing again.

Wall-clock speedup is smaller than the core count because each query costs more CPU when eight run at once (2.6x for a full scan, 1.4x for an index lookup — shared-cache contention, not a lock). The pool removes the serialisation; it cannot make a memory-bandwidth-bound scan free.

Two cases where the pool disables itself, both announced on stderr at startup:

• an in-memory store — each :memory: connection is its own empty database, so a pool there would not be slow, it would be wrong;
• a configured vector delegate or local vector backend — those are not shareable with a read-only connection, and several pooled handlers (/search_nodes, /search_facts, /unified_search, /ask) are vector-backed. Rather than answer the same question from two different indexes depending on which connection took it, the pool stands down.

read_pool_size = 0 is the rollback, and it is runtime config — no redeploy.

Authentication

Legacy migration profile: reads are open; writes need a bearer token. When required session keys are disabled and an auth token is configured, write endpoints require:

Authorization: Bearer <token>

In that legacy profile, reads such as /query, /search, entity lookups, /health and /version need no credential. /identity always requires a signed session identity.

A bearer refusal returns HTTP 401 with a JSON reason of missing_or_invalid_bearer_token, credential_type: "bearer", the endpoint, and provisioning guidance. Clients should configure a matching QUIPU_AUTH_TOKEN or QUIPU_AUTH_TOKEN_FILE; retrying an absent or rejected credential does not repair it. Signed authentication uses the existing protected registry with a registered, unexpired identity and write scope; read routes also accept that signature. Signed mutations remain restricted to the four audited routes, and signed requests cannot carry URL query strings.

Set [quipu.server] session_keys = { required = true, onboarding_read_paths = [] } only after completing the client and distinct-OS-user migration. This policy requires signed keys even for reads; a shared or named bearer is insufficient. The optional onboarding list admits only unique exact /health and /version GET/HEAD paths. Other paths, wildcards and duplicates fail startup validation. Strict mode refuses OPTIONS outside CORS, requiring a same-origin client or an authenticated broker. This option is default OFF and performs no enrollment.

Provision a client credential

The server administrator issues credentials through the deployment’s approved secret distribution channel. For a shared bearer, the supplied value must match an active server bearer. For a named credential, the administrator registers its verifier and activates the validated registry before supplying the plaintext to the client. Installing an arbitrary token on a client cannot grant access.

Shantytown and CABOODLE use ~/.config/quipu/token as the default credential file. A nonempty QUIPU_AUTH_TOKEN overrides QUIPU_AUTH_TOKEN_FILE, which overrides this default. Files are read at request time. This is a client convention; the server neither reads your home directory nor distributes secrets.

install -d -m 700 "$HOME/.config/quipu" && install -m 400 /secure/issued-token "$HOME/.config/quipu/token"
st ops doctor quipu --no-latest
# Or, on a CABOODLE host:
caboodle doctor

Keep an existing explicit file override until provisioning and rotation move together. Do not create independent copies that can diverge at rotation. Never put a token value in command arguments, logs, issues, or version control.

The doctor check POSTs an empty object to /episode. Authentication and read-only policy run before episode parsing: an accepted request receives HTTP 400 with invalid episode JSON: missing field ..., and stores nothing. HTTP 401 means a missing or rejected bearer; HTTP 403 with reason: server_is_read_only means no credential can permit the write. Network failures and unexpected responses leave authorization unproven. This check proves access to the write handler, not a successful storage commit.

Additive named credentials

[quipu.server].crew_credentials_file optionally points to a local JSON registry of SHA-256 verifiers for administrator-issued, high-entropy bearer tokens. Keep auth_token in place: named credentials are additional identities and do not replace the current or previous shared bearer. Public reads and read-only mode retain their behavior. An unconfigured registry changes nothing.

The file has version: 1 and a credentials array. Each entry contains credential_id (a unique non-secret identifier), principal (an absolute crew IRI), audience (exactly quipu), and token_sha256 (64 lowercase hex digits, the SHA-256 of the presented token string). Issue at least 32 cryptographically random bytes per credential and encode them for transport; this fast verifier is not suitable for human passwords. The issuer must verify that the principal is an existing crew identity. Parsing a registry checks syntax, not graph membership. No bearer plaintext belongs in this file or in the graph.

Loading captures an immutable policy at startup. Invalid optional registries are reported without their contents; shared authentication remains available. Validate and atomically install a complete registry before provisioning clients. A restart with an invalid registry will not activate its named credentials; preserve the last validated file and verify candidate configuration before a rollout. This initial implementation provides no issuance, rotation, revocation, or hot reload.

Named writes produce authenticated_request_start and authenticated_request_complete JSON audit events with credential ID, principal, method, route, and a process-local correlation ID. Missing completion is indeterminate. The credential principal is independent of declared actor, task, and source values. Import/promotion and RDF graph-store transactions use the registry principal through their existing authenticated-actor paths. Locally created fact transactions also retain separate authenticated evidence, exposed as authenticated by /transactions. Generic handlers preserve caller-declared actor and source; neither can replace this credential evidence.

The evidence is inserted inside the fact transaction’s savepoint, including fork materialization and overlay tombstones. Rollback removes it. Owned request context crosses blocking dispatch and deferred snapshot promotion, and is restored before a worker thread is reused. Schema/registry operations without a fact transaction retain request-level audit only. Library/CLI writes without an HTTP identity and copied historical transactions have null local authentication evidence; a foreign actor is not proof of possession of a local credential. End-to-end MCP attribution requires the proxy to select the corresponding downstream Quipu credential. The shared bearer remains legacy-shared-bearer, including if a registry entry accidentally duplicates its verifier.

For a coherent, pinned source receipt, use POST /acquire for a single file, or POST /acquire/composed for qualified MAIN scope with fenced immutable providers. The latter uses a separate version-gated contract and refuses unsupported required attached or derived scope; see atomic acquisition for its versioned contract. POST /acquire/eligibility answers only whether each named graph would pass that admission and the configured label floor at the current head, from graph metadata alone; it is an observation, not a receipt (see eligibility observation).

POST /share is also read-only. It returns the canonical Git-share manifest and exact file contents in one JSON response, allowing a proxy on another host to forward Quipu’s own canonicalization, hashes, and share ID instead of reproducing them. The body accepts scope, shapes, no_shapes, parent_share, turtle_view, and an optional max_bytes that can lower (but not raise) the 8 MiB server cap.

The authoritative list is http_auth::WRITE_ENDPOINTS in src/http_auth.rs, not this page. It is enforced: write_endpoints_cover_every_route fails the build if any registered route is unclassified, so the code cannot drift from itself — but this page can drift from the code, so treat it as a summary and the constant as the answer.

Two entries surprise people, and both are deliberate:

A refusal is never silent. Both refusals return a JSON body naming the cause, so curl -s cannot render an auth failure as an empty result:

{"endpoint":"/project","reason":"missing_or_invalid_bearer_token","error":"unauthorized: ..."}
{"endpoint":"/knot","reason":"server_is_read_only","error":"read-only mode: ..."}

reason is the stable field to branch on; error is prose and may be reworded.

Request Attribution

Callers can attach two optional headers to every endpoint:

Both values appear in request start/completion logs. The client, task, and route-template dimensions are also exported by quipu_http_client_requests_total and quipu_http_client_request_seconds_total. Client and task identities have independent cardinality budgets; excess caller-controlled values fold into a visible other bucket instead of growing the registry without bound. Use increase(...[window]) for counter comparisons so process restarts do not invalidate the result.

Endpoints

All POST endpoints accept Content-Type: application/json.

GET /watermark

A bounded, read-only metadata endpoint for replication observers. Returns {"store_id":"<store lineage>","watermark_tx":123} using the indexed latest transaction ID. It does not enumerate facts, advance a cursor or create a transaction. A shared store ID establishes lineage, not proof that two copies have identical contents.

Opt-in read-only followers poll their configured primary every 15 seconds (two-second HTTP timeout). Their responses carry X-Quipu-Replica-Lag-Tx: primary minus follower transaction IDs from the last fresh observation, or unknown. Metrics quipu_replica_lag_transactions (-1 for unknown) and quipu_replica_lag_known expose the same bounded observation. Failure, stale metadata or mismatched lineage never means zero lag. Replica writes return 503 naming the primary; they are not forwarded.

GET /health

Health check.

curl localhost:3030/health

Response: {"status": "ok"}

POST /identity

Requires an existing session-attestation signature. Returns the principal, public key ID and session selected from the protected binding, with authenticated: true and auth_class: "attested_session". A bearer or unkeyed request returns 401. Agent/session declaration headers (X-Quipu-Agent, X-Quipu-Session) are declared provenance. They must match the verified binding only when session keys are required ([quipu.server.session_keys] required = true); with it off, a differing declaration is admitted and the returned principal is still the binding’s. Replay, expired/revoked bindings and wrong keys refuse. No private key is returned. Use sd identity --json with an enrolled own key; plain curl without a signed envelope cannot produce the authenticated result.

GET /stats

Store statistics.

curl localhost:3030/stats

Response: {"facts": 1234, "entities": 56, "predicates": 12}

GET /query and POST /query

Execute a SPARQL query. Quipu implements the SPARQL 1.1 Query Protocol GET and direct-query POST transports, while retaining its JSON POST extension:

# Standard GET (request target limited to 8 KiB)
curl -G localhost:3030/query \
  -H 'Accept: application/sparql-results+json' \
  --data-urlencode 'query=SELECT ?s WHERE { ?s ?p ?o } LIMIT 5'

# Standard direct-query POST (body limited to 1 MiB)
curl localhost:3030/query -X POST \
  -H 'Content-Type: application/sparql-query' \
  -H 'Accept: text/turtle' \
  --data 'CONSTRUCT { ?s ?p ?o } WHERE { ?s ?p ?o } LIMIT 5'

# Quipu JSON extension
curl -s localhost:3030/query -X POST \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 5"}'

For SELECT and ASK, request application/sparql-results+json or application/sparql-results+xml, text/csv, or text/tab-separated-values. CSV and TSV follow the SPARQL 1.1 Results formats, including term spelling and escaping. For CONSTRUCT and DESCRIBE, request text/turtle or application/n-triples. All transports share the configured query deadline and return HTTP 408 when evaluation exceeds it.

POST /update

Execute SPARQL 1.1 Update using either application/sparql-update or an application/x-www-form-urlencoded body containing exactly one update parameter. The endpoint requires write authentication when a bearer is configured. Protocol using-graph-uri and using-named-graph-uri parameters scope a DELETE/INSERT WHERE; mixing them with an in-body USING clause is rejected. Every affected graph passes through Quipu’s normal authority and governance gates, and the request commits atomically across graphs.

curl localhost:3030/update -X POST \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/sparql-update' \
  --data 'INSERT DATA { <http://example/s> <http://example/p> "value" }'

A successful update returns 200 with what it committed:

{"tx": 4182, "asserted": 1, "retracted": 0,
 "graphs": [{"graph": null, "tx": 4182, "asserted": 1, "retracted": 0}]}

asserted and retracted count the triples the update changed, so a conditional DELETE/INSERT ... WHERE used as a compare-and-swap (claim if unassigned, release if still mine) can tell whether it won without a read-back: both zero means the WHERE matched nothing, or the update changed nothing, and tx is null. Each graph with changes commits its own transaction (graph is null for the default graph); tx is the last of them, usable with --at / tx reads. The SPARQL 1.1 Protocol leaves this body to the implementation.

Attribute a write with the optional actor and source query parameters (or form fields beside update=), each at most once, 1–256 characters, no control characters: POST /update?actor=agent:wu&source=seeds:claim. They are recorded on the transaction as declared, like /knot’s fields; the verified caller is recorded separately as its authenticated principal. Without actor the transaction’s actor is unknown (null); source defaults to sparql-update.

Quipu’s JSON extension compacts result IRIs to CURIEs by default using prefixes declared by the currently loaded shape sets; unknown namespaces remain full IRIs. Pass "verbose": true in a JSON request, or ?verbose=1 on GET, to return full IRIs. Standards result formats always retain their prescribed RDF term representation.

Optional fields: valid_at (ISO-8601), tx (integer), graph (a named-graph IRI or dataset name that scopes the query’s default graph without writing a FROM/GRAPH clause — an unknown IRI yields an empty default graph, never a silent ROOT fall-through), and fork (a fork name registered by quipu fork; unknown or dropped forks are refused loudly; mutually exclusive with graph).

include_kinds (array of dataKind tokens, e.g. ["archive"]) widens the default graph set with every registered graph declaring one of those kinds — the explicit opt-in for composing cold/frozen graphs into a hot read. Silence never widens: absent or empty means the scope is unchanged, a FROM clause in the query text still overrides the request-level scope, and fork + include_kinds is refused (one scope authority). The response’s composed labels.kind then honestly reports every kind that contributed.

With "federated": true the whole query text fans out through the federated provider — the local store plus every [[quipu.federation.remotes]] — and the response adds a per-member providers list (each carrying the remote’s operator-declared label) and a complete flag, with every row _provider-tagged and, for declared remotes, _trust/_freshness-stamped. The composed dataset labels fold the remotes in as members, and configured [quipu.labels] floors refuse a federated query exactly as a local one — an undeclared remote fails a configured freshness/trust floor (quipu-fd1). The temporal/graph fields are refused on a federated query (they only shape the local evaluator’s context). See Federation.

POST /knot

Assert facts from Turtle data.

curl -s localhost:3030/knot -X POST \
  -H "Content-Type: application/json" \
  -d '{"turtle": "@prefix ex: <http://example.org/> . ex:alice a ex:Person ."}'

Optional fields: shapes (SHACL Turtle), timestamp, valid_from, actor, source, replace_snapshot + snapshot (diffed replacement of a producer’s prior facts under a stable key), and graph (a named-graph IRI that must already be registered committed-class via POST /graph/create; unknown IRIs error, overlay-class targets are refused, omitted means ROOT).

timestamp is transaction time (when this store came to believe the facts, queried with tx/as_of_tx); valid_from is valid time (when they became true of the world, queried with valid_at). Omitting valid_from reuses timestamp for both, which is the historical behaviour. valid_from is RFC 3339 and is normalised to YYYY-MM-DDTHH:MM:SSZ — valid-time is compared as text, so an un-normalised offset sorts wrongly rather than merely looking untidy. A malformed value is refused before anything is written.

# a commit authored in March, ingested tonight
curl -s localhost:3030/knot -X POST \
  -H "Content-Type: application/json" \
  -d '{"turtle": "@prefix ex: <http://example.org/> . ex:c1 a ex:Commit .",
       "valid_from": "2026-03-04T09:15:00+01:00"}'

Response: {"tx_id": 1, "count": 2, "conforms": true, "valid_from": "2026-03-04T08:15:00Z"} — the echoed valid_from is the normalised key the facts were actually stored under.

Resumable snapshot promotion and cancellation

POST /knot/stage stores inert, content-addressed parts. Transport parts are limited to 512 KiB; the assembled upload is limited to 128 MiB and 512 parts. Those are byte limits, not a bound on promotion memory. Promotion still validates and replaces the complete producer snapshot atomically.

Start or poll with POST /knot/promote and {"upload_id":"sha256:..."}. A pending response includes "state":"running" and "lease_seconds":30. Poll regularly (for example once per second) using the same authenticated identity. Each live poll renews the lease. Bound the heartbeat request timeout and retry sequence below the lease (for example a five-second timeout with three attempts). A 30-second request timeout can itself exhaust this lease; a network partition can therefore cancel a still-running client. If the producer stops polling, its lease expires and the worker cooperatively cancels before committing the snapshot. A late poll cannot revive an expired lease. Only one promotion per store is admitted at a time; another upload receives an admission refusal.

For an explicit stop, send the same upload ID to POST /knot/cancel, using the identity that started promotion. Caller-declared actor is not authority. "cancellation_requested":true acknowledges the request, not worker exit. Poll /knot/promote until {"pending":false,"state":"cancelled","cancelled":true} confirms the worker has exited without committing its snapshot replacement. The previous snapshot and other producers’ facts remain active. Durable policy and refusal audit records are preserved; validation advisories from the aborted payload are discarded. Inert staged bytes and dictionary terms can remain until their normal cleanup; cancellation is not deletion of staging or an undo of an earlier successful promotion.

Cancellation competes with a single final commit claim. If commit wins, /knot/cancel reports "cancellation_requested":false and "state":"committing" or "complete"; the client must read the final promotion result. Once committed, deferred embedding may still be finishing and cannot be undone by cancellation. Checks run between upload parts, RDF rows, retraction comparisons and staged fact writes, and before commit. This is cooperative cancellation, not a promise that every validation or individual SQLite statement can be interrupted within 30 seconds. Measure stop latency and peak memory for the intended workload before admitting a larger publication; raising memory limits is not a substitute.

Terminal receipts are retained for an hour in a bounded process-local cache. Cancelled jobs stay terminal while their receipt is retained; polling does not restart them. To deliberately resume after confirmed terminal cancellation, the same identity can send {"upload_id":"sha256:...","retry_cancelled":true} to /knot/promote. This flag cannot restart a still-running worker, a failed job with an indeterminate commit, or a completed job. A fresh server process does not retain these receipts. After a restart or an indeterminate response, verify snapshot contents before starting another promotion. Staging remains content-addressed and independently expires.

POST /cord

List entities.

curl -s localhost:3030/cord -X POST \
  -H "Content-Type: application/json" \
  -d '{"type": "http://example.org/Person", "limit": 50}'

POST /unravel

Time-travel query.

curl -s localhost:3030/unravel -X POST \
  -H "Content-Type: application/json" \
  -d '{"tx": 5}'

POST /episode

Ingest an episode.

curl -s localhost:3030/episode -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "name": "deploy-v2",
    "nodes": [{"name": "myapp", "type": "WebApplication"}],
    "edges": [{"source": "myapp", "target": "kotare", "relation": "runs_on"}]
  }'

A bare node type such as WebApplication names a class under the store’s base_ns. To name a class in the public Quechua vocabulary instead, prefix it: "type": "quechua:WorkItem" asserts <https://scbrown.github.io/quechua/ns#WorkItem>. The prefix changes only the class. The node’s own IRI is still minted under base_ns. Like any other type, a Quechua class is refused until a loaded shape sanctions it. No other prefix is accepted.

Set "replace_snapshot": true for producers whose payload is the complete current state of an inventory. Facts previously asserted by the same episode name but absent from the new payload are retracted atomically with the new assertions. The default is false, preserving additive knowledge-ingestion semantics. Reusing a stable episode name is required for replacement.

outcome: what the ingest DID — branch on this, never on count

/episode is idempotent. The activity IRI is derived from the episode name and stamped with a content hash, so re-posting identical content is a no-op and retrying after a lost response is SAFE.

The response says which of three things happened:

Why this field exists. Before it, the idempotent no-op returned count: 0, tx_id: 0 — byte-for-byte what a write that achieved nothing returns — while the documented success check for callers of this API was “HTTP 200 with count > 0”. So a successful retry reported as a failure. The natural recovery from “my episode did not land” is to re-post it under a different name or with re-worded nodes, and that mints duplicate entities. The safe mechanism was steering callers into the unsafe action.

So the success check is:

# right: the facts are in the store for all three outcomes
curl -s .../episode -X POST ... | jq -e '.outcome' >/dev/null

# WRONG: reports a successful idempotent retry as a failure
curl -s .../episode -X POST ... | jq -e '.count > 0'

count > 0 remains a useful “did this call write anything” question. It was never a “did the write land” question, and only looked like one because the first post and the only post were usually the same post.

Two things it does not promise, both still on the caller:

• outcome describes THIS episode name. Re-posting the same knowledge under a different name is a new episode and will be created — idempotency is keyed on the name plus content hash, not on meaning.
• A 200 still is not proof of retrievability. A node filed under a type nobody queries is created and unreachable. Ask it back the way a reader would.