Design Goals

1. Knowledge conflicts are type errors, detected at build time.
2. Federation across projects is CUE unification, not a service call.
3. Every rejected approach MUST record a constructive alternative, preventing re-exploration of known dead ends.
4. Schema evolution is a quality ratchet: adding a required field makes every existing entry without it a validation error.
5. W3C vocabulary projections enable interoperability without replacing CUE as the source of truth.

Intended Audience

This specification is intended for:

• Developers implementing .kg/ knowledge graphs in their projects.
• Tool authors building editors, linters, or query interfaces for quicue-kg data.
• Platform engineers integrating knowledge graph data into autonomous software agents or development workflows.

Conformance Classes

Module Declaration

The .kg/cue.mod/module.cue file MUST declare a CUE module. The module name SHOULD follow the pattern {project-domain}/.kg but MAY use any valid CUE module identifier.

// .kg/cue.mod/module.cue
module: ""
language: version: "v0.11.0"

Schema Dependency

The quicue-kg schemas MUST be available to the CUE evaluator. This MAY be achieved through any of the following mechanisms, in order of preference:

1. CUE Central Registry — cue mod tidy resolves the quicue.ca/kg@v0 dependency automatically.
2. OCI Registry (GHCR) — set CUE_REGISTRY='quicue.ca=ghcr.io/quicue/cue-modules,registry.cue.works' and run cue mod tidy.
3. Local symlink — create a symlink at .kg/cue.mod/pkg/quicue.ca/kg/ pointing to a local checkout of the quicue-kg repository.

Package Declaration

Every .cue file at the root of the .kg/ directory MUST declare package kg. Files MUST NOT be placed in subdirectories, as CUE treats each directory as a separate package scope.

package kg

import "quicue.ca/kg/core@v0"

decisions: {
    "ADR-001": core.#Decision & {
        // ...
    }
}

File Organization

Within the flat .kg/ directory, entries SHOULD be organized by type into separate files for readability. The RECOMMENDED file organization is:

A conforming knowledge graph MAY combine all entries into a single file. The file boundaries are not semantically significant — CUE evaluates all files in a package as a single logical unit.

Decision (#Decision)

A Decision records an architecture decision with mandatory rationale, following the Architecture Decision Record ([[ADR]]) methodology. Status transitions follow a defined lifecycle: proposed → accepted → deprecated | superseded.

import "quicue.ca/kg/core@v0"

decisions: {
    "ADR-001": core.#Decision & {
        id:     "ADR-001"
        title:  "Use CUE for configuration"
        status: "accepted"
        date:   "2026-02-15"

        context:   "Need a type-safe configuration language."
        decision:  "Use CUE for all configuration and schema definitions."
        rationale: "CUE provides compile-time validation, unification, and a lattice-based type system."
        consequences: [
            "All config files are .cue, validated with cue vet",
        ]
    }
}

Insight (#Insight)

An Insight records a validated discovery worth preserving. Every insight MUST include at least one piece of evidence and an explicit confidence level, ensuring that knowledge is grounded in observable facts rather than assumption.

import "quicue.ca/kg/core@v0"

insights: {
    "INSIGHT-001": core.#Insight & {
        id:        "INSIGHT-001"
        statement: "CUE graph validation performance depends on topology, not node count"
        evidence: [
            "18-node/27-edge NHCF graph validates in 3.8 seconds",
            "17-node/25-edge greener-homes graph validates without issues",
            "Wide fan-in (high edge density) is the bottleneck, not node count",
        ]
        method:     "experiment"
        confidence: "high"
        discovered: "2026-02-10"

        implication: "Graph complexity should be managed by reducing fan-in, not by capping node count."
        action_items: [
            "Profile edge density before optimizing graph size",
        ]
    }
}

The confidence field is subject to the CUE lattice property: it can only be narrowed over time. An insight at "low" confidence MAY be updated to "medium" or "high" as evidence accumulates, but the type system prevents broadening a specific confidence back to a less specific value.

Rejected (#Rejected)

A Rejected entry documents an approach that was tried and failed, or was evaluated and dismissed. The alternative field is REQUIRED — every rejection MUST be constructive, pointing toward what to do instead. This design prevents the "we tried that and it didn't work" conversation loop by ensuring that dead ends always include a signpost to viable paths.

import "quicue.ca/kg/core@v0"

rejected: {
    "REJ-001": core.#Rejected & {
        id:          "REJ-001"
        approach:    "Use SPARQL for cross-project knowledge querying"
        reason:      "Requires external infrastructure (triple store, query engine). Adds deployment complexity."
        date:        "2026-02-15"
        alternative: "Use CUE unification for federation. Zero infrastructure, conflict detection is free."
        related: {"ADR-002": true}
    }
}

Pattern (#Pattern)

A Pattern captures a reusable problem/solution pair in the tradition of Christopher Alexander's pattern language. The used_in field tracks which projects employ the pattern, using the struct-as-set idiom for O(1) membership testing and clean unification when federating across project boundaries.

import "quicue.ca/kg/core@v0"

patterns: {
    "struct-as-set": core.#Pattern & {
        name:     "Struct-as-Set"
        category: "data-modeling"
        problem:  "CUE arrays allow duplicates and lack O(1) membership testing."
        solution: "Use {[string]: true} for set-valued fields."
        context:  "Any field representing set membership (related, used_in, depends_on)."
        used_in: {
            "quicue-kg":       true
            "quicue-proxmox":  true
            "energy-retrofit": true
        }
    }
}

Derivation (#Derivation)

A Derivation records the provenance of a data pipeline output: what worker produced it, from what inputs, and how trustworthy the output is relative to canonical source data. This type supports audit trails for data engineering workflows where the distinction between original and computed data is significant.

Context (#Context)

A Context entry is a project's identity card. It declares what the project is, what CUE module it belongs to, what patterns it uses, and what concepts it knows about. When projected to W3C vocabularies, a Context maps to a dcat:Dataset (see DCAT Projection).

import "quicue.ca/kg/ext@v0"

project: ext.#Context & {
    "@id":        "https://quicue.ca/project/quicue-kg"
    name:         "quicue-kg"
    description:  "CUE-native knowledge graph framework"
    module:       "quicue.ca/kg@v0"
    status:       "active"
    license:      "Apache-2.0"
    cue_version:  "v0.15.3"
}

Workspace (#Workspace)

A Workspace maps the physical layout of a multi-repository project. Components describe each repository or directory with filesystem paths, symlinks, git remotes, and branch information. This type enables tooling to understand the topology of projects that span multiple repositories.

Each component within components has the following fields:

Components are open structs — additional domain-specific fields are permitted.

KGIndex (#KGIndex)

The KGIndex is the primary aggregation type. It collects all entries by type, computes summary counts, and derives cross-cutting views such as decisions grouped by status and insights grouped by confidence level.

package kg

import "quicue.ca/kg/aggregate@v0"

index: aggregate.#KGIndex & {
    project: "my-project"

    decisions: decisions   // references from decisions.cue
    insights:  insights    // references from insights.cue
    rejected:  rejected    // references from rejected.cue
    patterns:  patterns    // references from patterns.cue
}

// Export: cue export .kg/ -e index.summary --out json

All fields within summary, by_status, and by_confidence are derived via CUE comprehensions. Adding an entry to the input maps automatically updates all computed views.

KGLint (#KGLint)

The KGLint type computes structural quality checks on a knowledge graph. It takes a populated #KGIndex as input and produces a list of lint results at varying severity levels.

Each #LintResult contains:

The #KGLint type handles structural checks via CUE comprehensions (e.g., referential integrity of all known IDs). Temporal and heuristic checks (e.g., stale proposals older than 90 days, confidence level upgrade suggestions) are implemented in the CLI layer using jq over exported JSON.

PROV-O Projection (#Provenance)

The provenance projection maps knowledge graph entries to the [[PROV-O]] ontology, producing a machine-navigable audit trail of decisions.

cue export .kg/ -e _provenance.graph --out json

The projection uses the following JSON-LD context:

{
  "prov":    "http://www.w3.org/ns/prov#",
  "dcterms": "http://purl.org/dc/terms/",
  "rdfs":    "http://www.w3.org/2000/01/rdf-schema#",
  "xsd":     "http://www.w3.org/2001/XMLSchema#",
  "kg":      "https://quicue.ca/kg#"
}

Web Annotation Projection (#Annotations)

The annotation projection maps insights and rejected approaches to the [[WEB-ANNOTATION]] data model. The two entry types map to different annotation motivations:

cue export .kg/ -e _annotations.graph --out json

DCAT Projection (#DatasetEntry, #FederatedCatalog)

The catalog projection maps knowledge graph metadata to the [[DCAT]] vocabulary. Each project with a .kg/ directory becomes a dcat:Dataset, and federation results become a dcat:Catalog.

# Single project dataset
cue export .kg/ -e _catalog.dataset --out json

# Federated catalog
kg fed ~/project-a/.kg/ ~/project-b/.kg/ --format dcat

N-Triples Projection (#NTriples)

The N-Triples projection produces the simplest possible RDF serialization: one <subject> <predicate> <object> . triple per line, with fully expanded IRIs (no prefixes). This format is greppable, sortable, and diffable — ideal for unix pipeline processing and bulk loading into any triplestore.

cue export .kg/ -e _ntriples.triples --out text

# Count triples by type
cue export .kg/ -e _ntriples.triples --out text | grep 'rdf-syntax-ns#type' | sort | uniq -c

# Find all provenance activities
cue export .kg/ -e _ntriples.triples --out text | grep 'prov#Activity'

Turtle Projection (#Turtle)

The Turtle projection produces human-readable RDF with @prefix declarations and subject grouping. It uses the same mappings as N-Triples but with compact prefixed names. The output is compatible with existing Turtle files in infra-ontology and can be loaded directly into Oxigraph or any SPARQL endpoint.

The document is organized by section: decisions, insights, patterns, sources, collection protocols, pipeline runs, and derivations. Each section uses standard RDF vocabularies (prov:, dcterms:, skos:, rdfs:) alongside the kg: namespace.

cue export .kg/ -e _turtle.document --out text

SKOS Taxonomy (#SKOSTaxonomy)

The SKOS projection maps the project's pattern categories to a skos:ConceptScheme and individual patterns to skos:Concept instances. Categories are top concepts; patterns are narrower concepts within their category. This produces a browsable taxonomy of the project's pattern language.

The projection outputs both JSON-LD (_taxonomy.graph) and Turtle (_taxonomy.turtle). It also produces a summary with concept and category counts.

# JSON-LD concept scheme
cue export .kg/ -e _taxonomy.graph --out json

# Turtle for compatibility with existing SKOS files
cue export .kg/ -e _taxonomy.turtle --out text

Prolog Projection (#Prolog)

The Prolog projection generates facts and inference rules from knowledge graph entries. Unlike RDF projections that describe data, the Prolog projection makes knowledge computable: you can query transitive provenance chains, determine trust levels, and discover shared patterns across projects.

Facts are generated for each entry type. Rules encode inference logic:

# Export Prolog program
cue export .kg/ -e _prolog.program --out text > kb.pl

# Query in SWI-Prolog
swipl -l kb.pl -g "shared_pattern(P, A, B), writef('%w shared by %w and %w\n', [P, A, B]), fail."

Datalog Projection (#Datalog)

The Datalog projection generates Soufflé-compatible Datalog programs. Unlike Prolog, Datalog always terminates — there are no function symbols, no cuts, no negation-as-failure cycles. This makes it safe for automated infrastructure queries at scale.

The program includes .decl relation declarations, .output directives for derived relations, facts from the knowledge graph, and the same inference rules as the Prolog projection. Soufflé compiles these to native C++ for high-performance evaluation.

# Export Soufflé-compatible Datalog
cue export .kg/ -e _datalog.program --out text > kb.dl

# Evaluate with Soufflé
souffle kb.dl

# Results are written to .csv files (one per .output relation)

JSON-LD Context

The kg: namespace resolves to https://quicue.ca/kg#. The full JSON-LD context document is defined in vocab/context.cue and SHOULD be served at https://quicue.ca/kg with content type application/ld+json.

The JSON-LD context provides the following mappings:

The context also declares RDFS class hierarchy relationships:

• kg:Decision — rdfs:subClassOf prov:Activity
• kg:Insight — rdfs:subClassOf prov:Entity
• kg:Rejected — rdfs:subClassOf oa:Annotation
• kg:Derivation — rdfs:subClassOf prov:Activity
• kg:Context — rdfs:subClassOf dcat:Dataset
• kg:Pattern — no W3C superclass (domain-specific)
• kg:Workspace — no W3C superclass (domain-specific)

cue export ./vocab -e context --out json > kg-context.jsonld

Discovery

A conforming processor discovers knowledge graphs by performing a filesystem walk looking for the presence of .kg/cue.mod/module.cue. The discovery algorithm is:

1. Walk the filesystem from a set of root directories.
2. For each directory, check for the existence of .kg/cue.mod/module.cue.
3. If found, the parent directory contains a knowledge graph.
4. Validate the .kg/ directory with cue vet.
5. If validation passes, include the knowledge graph in the federation set.

kg fed ~/project-a/.kg/ ~/project-b/.kg/ ~/project-c/.kg/

Merging

Federation merging uses CUE unification. When two knowledge graphs are unified:

• Entries with different IDs are combined into a single namespace.
• Entries with the same ID and compatible values unify to the most specific value satisfying both constraints.
• Entries with the same ID and conflicting values produce a CUE type error, surfacing the conflict explicitly.

The struct-as-set idiom ensures that set-valued fields (e.g., used_in, related) merge cleanly: the union of two sets {"a": true} and {"b": true} unifies to {"a": true, "b": true}.

Conflicts are features, not bugs. A type error during federation means two projects assert contradictory facts. The error message identifies the conflicting entries, requiring explicit human resolution.

Export

Federation results MAY be exported as a [[DCAT]] catalog using the #FederatedCatalog type. Each federated knowledge graph becomes a dcat:Dataset entry within a dcat:Catalog.

{
  "@context": {
    "dcat":    "http://www.w3.org/ns/dcat#",
    "dcterms": "http://purl.org/dc/terms/",
    "kg":      "https://quicue.ca/kg#"
  },
  "@type": "dcat:Catalog",
  "dcterms:title": "quicue Knowledge Graph Federation",
  "dcterms:description": "Federated catalog of CUE-native knowledge graphs",
  "dcat:dataset": [
    { "@type": "dcat:Dataset", "dcterms:title": "project-a", ... },
    { "@type": "dcat:Dataset", "dcterms:title": "project-b", ... }
  ]
}

Tool Interface

A conforming processor targeting agent integration SHOULD expose the following tool operations. Each operation corresponds to a kg CLI command and returns structured JSON.

Session Initialization

When an autonomous software agent begins a session in a project containing a .kg/ directory, the agent's runtime SHOULD automatically inject knowledge graph context. The RECOMMENDED initialization sequence is:

1. Detect the presence of .kg/cue.mod/module.cue in the project.
2. Run kg index to retrieve the current knowledge graph state.
3. Run kg rejected to load all rejected approaches.
4. Include the rejected approaches in the agent's working context.

This ensures the agent begins work with awareness of prior decisions and known dead ends, reducing the likelihood of proposing previously rejected solutions.

Anti-Hallucination Protocol

To prevent autonomous software agents from proposing solutions that have already been tried and rejected, the following protocol is RECOMMENDED:

1. Before proposing a solution, the agent MUST query kg_rejected.
2. If the proposed approach matches a rejected entry's approach field, the agent MUST acknowledge the prior rejection and explain why the new proposal differs or why circumstances have changed.
3. If the agent cannot differentiate its proposal from a prior rejection, it SHOULD follow the alternative field from the rejected entry instead.

The rejected approach database functions as institutional memory. Its value scales with project age: a mature project may have dozens of documented dead ends that prevent cyclic re-exploration by both human developers and software agents.

Sensitive Architectural Information

Knowledge graph entries MAY contain sensitive architectural decisions, such as security architecture choices, authentication strategy rationale, or infrastructure topology information. Implementors SHOULD consider the following:

• .kg/ directories committed to version control inherit the repository's access control. If the repository is public, all knowledge graph entries are public.
• The context and rationale fields of #Decision entries may inadvertently expose threat models or security assumptions.
• #Workspace entries expose filesystem paths, git remote URLs, and deployment topology — information useful for reconnaissance.

Credential Prohibition

Knowledge graph entries MUST NOT contain credentials, secrets, API keys, tokens, or other authentication material. The .kg/ directory is designed for structural and architectural knowledge, not operational secrets.

A conforming processor SHOULD warn if entry content appears to contain credential-like patterns (e.g., strings matching common API key formats).

Federation Metadata Exposure

The federation protocol exposes project metadata across organizational boundaries. When federating knowledge graphs:

• Project names, descriptions, and status information are shared.
• Decision context and rationale cross project boundaries.
• Pattern used_in fields reveal which projects use which patterns.

Organizations SHOULD establish federation policies that define which projects may be federated and with whom. The #Context.status field MAY be used to control federation eligibility (e.g., only federate "active" projects).

Media Type

The CUE source format used by .kg/ directories uses file extension .cue. As of publication, the CUE language does not have an IANA-registered media type. This specification uses application/cue as an informational media type identifier in DCAT distribution entries.

When exporting to JSON-LD, the standard media type application/ld+json SHOULD be used.

Namespace URI

The kg: namespace is bound to the URI https://quicue.ca/kg#. The JSON-LD context document SHOULD be served at https://quicue.ca/kg with content negotiation:

• Accept: application/ld+json → the JSON-LD context document.
• Accept: text/html → this specification document.