Design Goals

1. Knowledge conflicts are type errors, detected at build time.
2. Federation across projects requires no shared infrastructure.
3. Every rejected approach MUST record a constructive alternative.
4. Schema evolution is a quality ratchet: adding a required field makes every existing entry without it a validation error.

Conformance Classes

CUE Concepts Used in This Specification

This section is non-normative. It summarizes CUE language features that are essential to understanding this specification. Readers familiar with CUE may skip this section. For a complete reference, see [[CUE]].

Types are values.

CUE has no separate type system. A definition like #Decision is itself a value — a partially-specified struct. Writing core.#Decision & {id: "ADR-001", ...} is not "instantiating a type" but unifying two values. The result must satisfy all constraints from both sides. This is why schema validation and data authoring are the same operation.

Definitions (#).

Identifiers prefixed with # are definitions. By default, definitions are closed: they reject undeclared fields. However, adding ... makes a definition open — it accepts additional fields beyond those declared in the schema. The quicue-kg core types are open: required fields are validated, but users may add domain-specific fields freely. Definitions are not emitted during export (cue export). Regular identifiers are open and are emitted.

Hidden fields (_).

Identifiers prefixed with _ are hidden — not emitted during export. The index uses _index as a hidden field so that cue export .kg/ doesn't dump the entire aggregation. To export it, use cue export .kg/ -e _index.summary.

Disjunctions as enums.

"proposed" | "accepted" | "deprecated" | "superseded" is a disjunction — the value must be exactly one of the listed options. This is how CUE expresses enumerated types. Any value outside the set is a validation error.

Constraint composition.

CUE uses & (unification) to compose constraints: string & !="" means "a string that is not empty." [...string] & [_, ...] means "a list of strings with at least one element" (_ matches any value). =~"^ADR-\\d{3}$" constrains a string by regex.

Monotonic refinement.

CUE's value lattice only narrows. A field constrained to "high" | "medium" | "low" can later be refined to "high" but can never be widened to accept "maybe". This is the mechanism behind progressive refinement: knowledge accumulates, it cannot silently disappear.

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: "local.project/kg"
language: version: "v0.15.4"
source: kind: "self"

Schema Dependency

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

1. OCI Registry (GHCR) — set CUE_REGISTRY='quicue.ca=ghcr.io/quicue/cue-modules,registry.cue.works' and run cue mod tidy.
2. 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.

package kg

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

d001: core.#Decision & {
    id:     "ADR-001"
    title:  "Use CUE for configuration"
    // ...
}

File Organization

Entries SHOULD be organized by type into separate files for readability.

A conforming knowledge graph MAY combine all entries into a single file. 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 and consequences. Decisions follow a status lifecycle from proposed through accepted to eventual deprecated or superseded.

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

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

Insight (#Insight)

An Insight records a validated discovery with mandatory evidence and an explicit confidence level. The method field tracks how the insight was discovered, supporting reproducibility.

Rejected (#Rejected)

A Rejected [=entry=] records an approach that was tried and abandoned. The alternative field is REQUIRED — every rejection must suggest what to do instead. This prevents the "we tried that" conversation loop by turning dead ends into redirects.

Pattern (#Pattern)

A Pattern captures a reusable problem/solution pair with cross-project usage tracking. The used_in field uses the struct-as-set idiom, which means federating two projects that both use the same pattern automatically produces the union of their used_in sets.

Discovery

A conforming processor discovers knowledge graphs by walking the filesystem looking for .kg/cue.mod/module.cue:

1. Walk from a set of root directories.
2. For each directory, check for .kg/cue.mod/module.cue.
3. If found, validate the .kg/ directory with cue vet.
4. If validation passes, include in the federation set.

# Discover all .kg/ directories under ~/projects/
kg fed ~/projects/

# Load specific directories
kg --dir ~/api/.kg --dir ~/web/.kg --dir ~/infra/.kg index

Merging

Federation merging follows CUE unification semantics:

• Entries with different IDs are combined into one namespace.
• Entries with the same ID and compatible values unify — set-valued fields (related, used_in) merge via union.
• Entries with the same ID and conflicting values produce an error, surfacing the contradiction explicitly.

Conflicts are features, not bugs. A type error during federation means two projects assert contradictory facts. The error requires explicit human resolution — no silent last-write-wins.

Remote Sources

A conforming processor MAY support remote sources specified as git URLs. Remote sources are shallow-cloned, the .kg/ directory is located, and entries are loaded and merged as with local sources.

# Local + remote
kg --dir .kg --dir https://github.com/org/other-project.git search "caching"

# The --dir flag is repeatable. All commands support it.
kg --dir ~/a/.kg --dir ~/b/.kg --dir ~/c/.kg serve

Write operations (add) target the first --dir value only.

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:

• .kg/ directories in version control inherit the repository's access control. If the repository is public, all entries are public.
• The context and rationale fields of #Decision entries may inadvertently expose threat models or security assumptions.

Credential Prohibition

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

Federation Metadata Exposure

Federation exposes project metadata across organizational boundaries:

• 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.