Repository navigation
Replies: 6 comments
Revision 1: kind attributes move into YAML frontmatter, parsed by a real YAML parserThis revises Definition format. The fenced WhyThe JSON block worked around the parser instead of fixing it.
Fixing the parser helps every vault kind, not only custom ones, and it puts the schema where readers expect metadata to be. Definition format (replaces the previous section)---
name: adr
specVersion: 1
title: Architecture Decision Record
fields:
status:
type: enum
values: [proposed, accepted, superseded]
required: true
default: proposed
supersedes:
type: ref[]
target: [adr]
edge: SUPERSEDES
intent:
type: ref
target: [intent]
edge: IMPLEMENTS
body:
required: true
embed: true
context: true
---
Use an ADR for any decision that constrains future code: storage formats,
crypto choices, protocol changes. One decision per record. Link the intent
that prompted it.
Instances use the same parser, so Parser change (new M0 prerequisite)Replace
Compatibility. Built-in kinds hash their lifted frontmatter. A file that parses differently would change its substance hash, which lapses attestations, and would show as modified on the first deflate after upgrading. These are the known differences between the two parsers:
Plan:
As a smoke check, the six files in this repository's own The crate is open; see decision 8. Other sections affected
|
Reference implementation: draft PR #278#278 implements tier A, milestones M0–M2, with Revision 1 (schema in YAML frontmatter, read by a real YAML 1.2 parser). Each open decision takes the default proposed above. It exists so the proposal can be judged against working code; it isn't meant to merge as is. The PR description maps each assumed decision to the code that would change if the ruling goes the other way. What running it showed about the claims above:
|
|
@leefaus I drafted a PR so you could play around with it while reviewing the proposal. If the proposal is accepted, the PR could be marked ready or I could break it into smaller PRs if that would be preferred. I'm also planning to keep it up to date with any feedback on this proposal so that way its always available for testing |
|
@Zaba505 awesome! Just getting caught up after ATO. Great meeting you there! Ok so still love this idea. Being able to store ADRs or RFC's in the graph is the absolute perfect example of the ways I can see people wanting to extend out the kinds here. So I think you might need to run back through with #265 's changes. This was a big pivot. Likely some changed IRI's and reserved names in the ontology. |
Revision 2: running it back through #265@geekgonecrazy you called it: IRIs and reserved names both changed, and the table below is the direct answer. The bigger change is that this proposal's premise, "the KG is already open", is gone. #265 closed the vocabulary, so the KG half had to be redesigned, not renamed. The reference implementation is rebuilt on dev at
If there is time for only three, decisions 1, 2 and 9 below matter most. The costs, stated firstThis design changes nothing in
What #265 changed for this proposal
Knowledge-graph projectionThis replaces the Storage and identity bullets on instance identity, edge kinds and reserved names. A node and an edge, from the walkthrough in the next comment, with the project id shortened to {
"id": "urn:atomic:project:<pid>:concept:adr.01M6PW2HH3GHBW1TX7BQ8SFP3K",
"types": [
"https://atomic.dev/ns/workflow#Concept"
],
"label": "Rotate signing keys quarterly",
"summary": "Rotate signing keys quarterly",
"source": "vault",
"metadata": {
"created_at": "2026-11-05T22:08:07.204130208+00:00",
"derived_from_vault_path": "kinds/adr/01M6PW2HH3GHBW1TX7BQ8SFP3K.md",
"field.status": "accepted",
"kind_name": "adr",
"uid": "01M6PW2HH3GHBW1TX7BQ8SFP3K",
"updated_at": "2026-11-05T22:08:07.204130208+00:00",
"vault_path": "kinds/adr/01M6PW2HH3GHBW1TX7BQ8SFP3K.md"
}
}{
"from_id": "urn:atomic:project:<pid>:concept:adr.01M6PW2HH3GHBW1TX7BQ8SFP3K",
"to_id": "urn:atomic:project:<pid>:concept:adr.01M6PW2HE6VNDFMRCZYHHF95XT",
"kind": "https://atomic.dev/ns/workflow#references",
"metadata": {
"derived_from_vault_path": "kinds/adr/01M6PW2HH3GHBW1TX7BQ8SFP3K.md",
"edges": [
"supersedes"
],
"fields": [
"supersedes"
]
}
}The hook is one
What this gives up:
The query surface as it behaves, each row run:
A Reserved namesRule: a kind name is reserved when, lowercased with
The label collision, and what it means for decision 4
The mechanics: a label's stub has no metadata, so it lands only while the IRI is free. An owned node always upserts ( One real failure. An instance goes inert (its spec breaks) while an The fix. An inert row owns a bare node while a label names it: a What remains. A label spelling a kind node still links to it, with no Finding: $ atomic vault sync # after adding an intent with labels: [kind.adr]
Synced 1 vault file(s).
$ atomic query neighbors "$HUB"
Nodes (5):
[atomic:FeatureIntent] urn:atomic:project:<pid>:intent:01JD8ZK3M6W2Q4V7X9B5N1C3TV Labelled
...
[atomic:Concept] urn:atomic:project:<pid>:concept:kind.adr Architecture Decision Record
Edges (4):
...
urn:atomic:project:<pid>:intent:01JD8ZK3M6W2Q4V7X9B5N1C3TV →[https://atomic.dev/ns/workflow#hasLabel]→ urn:atomic:project:<pid>:concept:kind.adr
Validation (reframes decision 2)The conflict is the one in the costs section. The case for the validator, for you to weigh:
The old claim "1:1 with SHACL-Core" was false. The gate and the KG are not the same check. The gate is per view and from files. The projection is repository-wide and from stored rows. Review found the gate passing a ref to an instance with no
Withdrawn
New and rewritten risks
Decisions needed (replaces the list)Numbers 1-8 keep their subjects, with 1 and 2 reframed for #265, and 9-13 are new. Each item lists the default the reference implementation takes, so "agree with N" is enough. 1, 2 and 9 matter most.
Reference implementationDraft #278 is rebuilt, and its description maps each decision to the code that changes if the ruling goes the other way. It is 36 commits on On the final commit, on Linux: 10,923 tests passed, 0 failed, 19 ignored. Dev at The dev-to-branch-to-dev compatibility test was re-run against a real macOS and Windows have not run. #278 shows no CI checks, so nothing here has run on them. The new symlink, FIFO and permission tests are Unix-only, and the regular-file check was not exercised on Windows. Questions for you
|
Revision 2, part 2: evidence and errataThis is the supporting material for the previous comment: the observed SHACL mapping, what running the code showed, the rest of the proposal's sections that change, and a real end-to-end walkthrough. The decisions are all in the previous comment. SHACL mapping, as observedThe old claim "1:1 with SHACL-Core" was false, and this replaces it.
Three more results from the same file:
Limits on what this proves:
What running it showedThe tests ran at The cost of whole-vault re-projection. This is the result that changes the proposal, because it changes decision 12. Each store re-projects the whole vault ( Machine: AMD Ryzen 9 5950X, 31 GiB, Linux, repository on tmpfs, single-threaded, one run per size. Build: release with LTO off and 16 codegen units, not the shipping profile. The probes are
What I take from it:
Claims re-run on this base:
Corrected or narrower than I expected:
Alternatives consideredAdd these rows:
Reword the Replace "CB-only validation" with "PurRDF-only validation", which is 2(b). Other sections affected
WalkthroughUnlike the proposal's example, this is a transcript. Every command ran in the order shown, on one new repository named $ atomic init
$ atomic view create adrs --draft --parent dev --switch
✓ Switched to view: adrs (0 files updated)
✓ Created view: adrs
$ atomic kind init adr
Created .vault/kinds/adr/_kind.md
Edit the fields, then check the definition:
atomic kind validate adr
Record it as its own change before creating instances:
atomic add .vault/kinds/adr/_kind.md
atomic record -m "feat: add adr kind" .vault/kinds/adr/_kind.mdEdit ---
name: adr
specVersion: 1
title: Architecture Decision Record
fields:
status:
type: enum
values: [proposed, accepted, superseded]
required: true
default: proposed
supersedes:
type: ref[]
target: [adr]
edge: supersedes
intent:
type: ref
target: [intent]
edge: implements
body:
required: true
embed: true
context: true
---
Use an ADR for any decision that constrains future code: storage formats,
crypto choices, protocol changes. One decision per record. Link the intent
that prompted it.$ atomic kind validate adr
✗ .vault/kinds/adr/_kind.md: fields.status: unknown key "pattern"
(adr stays unregistered until this is fixed)
✗ 1 kind (0 registered), 0 instances in the working copy: 1 problem
✗ Invalid argument: kind validation failed in the working copy (1 problem(s))
# exit 2Remove the line and record the definition as its own change. $ atomic kind validate adr
✓ adr: 3 fields, edges implements, supersedes; no instances
✓ 1 kind (1 registered), 0 instances in the working copy: all valid
$ atomic add .vault/kinds/adr/_kind.md
$ atomic record -m "feat: add adr kind" .vault/kinds/adr/_kind.md
[adrs 1/CKYYMTNKMSNA] feat: add adr kind
.vault/kinds/adr/_kind.md
$ atomic intent new "Sign every change"
Created intent: DEMO::alice::1
file: .vault/intents/01M6PW2H0DFVD6F61W7XH7XWE0/intent.md
template: feature
kind: feature
$ atomic kind new adr --title "Sign changes with Ed25519" --set status=maybe
✗ status: "maybe" is not one of: proposed, accepted, superseded
Nothing was written.
✗ Invalid argument: the new adr instance does not conform (1 problem(s))
# exit 2
$ atomic kind new adr --title "Sign changes with Ed25519" --set intent=1 --body-file d1.md
Created .vault/kinds/adr/01M6PW2H50KT41W46Y1G37FVQ5.md (adr:01M6PW2H50KT41W46Y1G37FVQ5)
KG id: …concept:adr.01M6PW2H50KT41W46Y1G37FVQ5
$ cat .vault/kinds/adr/01M6PW2H50KT41W46Y1G37FVQ5.md
---
intent: DEMO::alice::1
status: proposed
title: Sign changes with Ed25519
uid: 01M6PW2H50KT41W46Y1G37FVQ5
---
We sign change headers with Ed25519 because the key material is small and the
verification path has no configuration.
$ atomic add .vault/kinds/adr/01M6PW2H50KT41W46Y1G37FVQ5.md
$ atomic record -m "docs: ADR for change signing" .vault/kinds/adr/01M6PW2H50KT41W46Y1G37FVQ5.md
[adrs 1/NQVA344AVCJ6] docs: ADR for change signing
.vault/kinds/adr/01M6PW2H50KT41W46Y1G37FVQ5.md
$ atomic change NQVA344AVCJ6D7Q4V7FX3ND7IEXSZLR6FEPZHGIDXGXZRO4RO24A --show-deps
change NQVA344AVCJ6
├── Metadata
│ └── Date: 2026-11-05 17:08:06
├── Message
│ └── docs: ADR for change signing
├── Dependencies (1)
│ └── CKYYMTNKMSNA — feat: add adr kind
├── Graph: +10 vertices, ~0 edges, 260 bytes
└── Files changed: 1
└── .vault/
└── kinds/
└── adr/
└── 01M6PW2H50KT41W46Y1G37FVQ5.md [modified]
$ atomic kind new adr --title "Rotate signing keys yearly" --set status=accepted --body-file d2.md --json
{"file":".vault/kinds/adr/01M6PW2HE6VNDFMRCZYHHF95XT.md","kg_id":"…concept:adr.01M6PW2HE6VNDFMRCZYHHF95XT","kind":"adr","uid":"01M6PW2HE6VNDFMRCZYHHF95XT","written":true}
$ atomic kind new adr --title "Rotate signing keys quarterly" --set status=accepted --set supersedes=01M6PW2HE6VNDFMRCZYHHF95XT --body-file d3.md --json
{"file":".vault/kinds/adr/01M6PW2HH3GHBW1TX7BQ8SFP3K.md","kg_id":"…concept:adr.01M6PW2HH3GHBW1TX7BQ8SFP3K","kind":"adr","uid":"01M6PW2HH3GHBW1TX7BQ8SFP3K","written":true}
$ atomic add .vault/kinds/adr/01M6PW2HE6VNDFMRCZYHHF95XT.md .vault/kinds/adr/01M6PW2HH3GHBW1TX7BQ8SFP3K.md
$ atomic record -m "docs: key rotation ADRs" .vault/kinds/adr/01M6PW2HE6VNDFMRCZYHHF95XT.md .vault/kinds/adr/01M6PW2HH3GHBW1TX7BQ8SFP3K.md
[adrs 1/6BCWKBXKWSCW] docs: key rotation ADRs
.vault/kinds/adr/01M6PW2HE6VNDFMRCZYHHF95XT.md
.vault/kinds/adr/01M6PW2HH3GHBW1TX7BQ8SFP3K.md
$ atomic kind list adr
UID TITLE STATUS INTENT
───────── ───────────────────────────── ──────── ──────────────
01M6PW2H… Sign changes with Ed25519 proposed DEMO::alice::1
01M6PW2H… Rotate signing keys yearly accepted -
01M6PW2H… Rotate signing keys quarterly accepted -
$ atomic kind validate adr
✓ adr: 3 fields, edges implements, supersedes; 3 instances conform
✓ 1 kind (1 registered), 3 instances in the working copy: all validThe KG needs no manual reindex. Here $ atomic query neighbors "$HUB"
Nodes (4):
[atomic:Concept] …concept:kind.adr Architecture Decision Record
[atomic:Concept] …concept:adr.01M6PW2HH3GHBW1TX7BQ8SFP3K Rotate signing keys quarterly
[atomic:Concept] …concept:adr.01M6PW2H50KT41W46Y1G37FVQ5 Sign changes with Ed25519
[atomic:Concept] …concept:adr.01M6PW2HE6VNDFMRCZYHHF95XT Rotate signing keys yearly
Edges (3):
…concept:adr.01M6PW2H50KT41W46Y1G37FVQ5 →[https://atomic.dev/ns/workflow#references @kind]→ …concept:kind.adr
…concept:adr.01M6PW2HE6VNDFMRCZYHHF95XT →[https://atomic.dev/ns/workflow#references @kind]→ …concept:kind.adr
…concept:adr.01M6PW2HH3GHBW1TX7BQ8SFP3K →[https://atomic.dev/ns/workflow#references @kind]→ …concept:kind.adr
$ atomic query neighbors …concept:adr.01M6PW2HH3GHBW1TX7BQ8SFP3K
Nodes (3):
[atomic:Concept] …concept:adr.01M6PW2HE6VNDFMRCZYHHF95XT Rotate signing keys yearly
[atomic:Concept] …concept:adr.01M6PW2HH3GHBW1TX7BQ8SFP3K Rotate signing keys quarterly
[atomic:Concept] …concept:kind.adr Architecture Decision Record
Edges (2):
…concept:adr.01M6PW2HH3GHBW1TX7BQ8SFP3K →[https://atomic.dev/ns/workflow#references supersedes]→ …concept:adr.01M6PW2HE6VNDFMRCZYHHF95XT
…concept:adr.01M6PW2HH3GHBW1TX7BQ8SFP3K →[https://atomic.dev/ns/workflow#references @kind]→ …concept:kind.adr
$ atomic query neighbors …concept:adr.01M6PW2H50KT41W46Y1G37FVQ5
Nodes (3):
[atomic:Concept] …concept:adr.01M6PW2H50KT41W46Y1G37FVQ5 Sign changes with Ed25519
[atomic:FeatureIntent] …intent:01M6PW2H0DFVD6F61W7XH7XWE0 Sign every change
[atomic:Concept] …concept:kind.adr Architecture Decision Record
Edges (2):
…concept:adr.01M6PW2H50KT41W46Y1G37FVQ5 →[https://atomic.dev/ns/workflow#references @kind]→ …concept:kind.adr
…concept:adr.01M6PW2H50KT41W46Y1G37FVQ5 →[https://atomic.dev/ns/workflow#references implements]→ …intent:01M6PW2H0DFVD6F61W7XH7XWE0
$ atomic query neighbors adr:01M6PW2HH3GHBW1TX7BQ8SFP3K # the handle is not an IRI
No neighbors found for 'adr:01M6PW2HH3GHBW1TX7BQ8SFP3K'.
$ atomic query neighbors "$HUB" --json | jq -c '[.nodes[] | select(.metadata["field.status"] == "accepted") | .label]'
["Rotate signing keys quarterly","Rotate signing keys yearly"]
$ atomic query search rotate -t https://atomic.dev/ns/workflow#Concept --json | jq -c '[.[]|select(.metadata.kind_name=="adr")|.label]'
["Rotate signing keys yearly","Rotate signing keys quarterly"]
$ atomic query graph rotate --kinds adr --json | jq -c '[.nodes[]|.label]'
[]
$ atomic query validate
SHACL Projection: conforms
Snapshot: SHFFGROCBPMYOSCKGSBWLKLYHMVDYNAXQ7TB77ESQTQQU3YVD4AA
Profile: fc62f21b3313894df5498ffb79b85cb846eba5bdddda0ee73076f1a2b719aa84
https://atomic.dev/ns/shapes/projection/1.0.0#ChangeAvailability: 5 evaluated / 5 applicable
https://atomic.dev/ns/shapes/projection/1.0.0#FullHashIdentity: 6 evaluated / 6 applicable
https://atomic.dev/ns/shapes/projection/1.0.0#GeneratedChange: 0 evaluated / 0 applicable
https://atomic.dev/ns/shapes/projection/1.0.0#ReferencedResource: 32 evaluated / 32 applicable
Phase 1 conformance is not complete publication/audit evidence; inspect coverage and historical-gap findings.A hand-written instance that breaks the spec, at ---
uid: 01JD8ZK3M6W2Q4V7X9B5N1C3T0
title: Hand-written and wrong
status: maybe
---
Body.Deflate does not block. The gate fails, the node stays visible with a Finding, and $ atomic vault sync
Synced 1 vault file(s).
$ atomic kind validate adr
✓ adr: 3 fields, edges implements, supersedes; 1 of 4 instances do not conform
✗ .vault/kinds/adr/01JD8ZK3M6W2Q4V7X9B5N1C3T0.md: status: "maybe" is not one of: proposed, accepted, superseded
✗ 1 kind (1 registered), 4 instances in the working copy: 1 problem
✗ Invalid argument: kind validation failed in the working copy (1 problem(s))
# exit 2
$ atomic query neighbors …concept:adr.01JD8ZK3M6W2Q4V7X9B5N1C3T0
Nodes (3):
[atomic:Concept] …concept:kind.adr Architecture Decision Record
[atomic:Finding] …finding:KindViolation:GQQPZXH47AEPTJOI7NYEHP3JPUFFHSWBHILBP3LGWMX7PYAKXSPQ adr 01JD8ZK3M6W2Q4V7X9B5N1C3T0 does not conform...
[atomic:Concept] …concept:adr.01JD8ZK3M6W2Q4V7X9B5N1C3T0 Hand-written and wrong
Edges (2):
…concept:adr.01JD8ZK3M6W2Q4V7X9B5N1C3T0 →[https://atomic.dev/ns/workflow#references @kind]→ …concept:kind.adr
…finding:KindViolation:GQQPZXH47AEPTJOI7NYEHP3JPUFFHSWBHILBP3LGWMX7PYAKXSPQ →[https://atomic.dev/ns/workflow#aboutResource]→ …concept:adr.01JD8ZK3M6W2Q4V7X9B5N1C3T0With that file moved aside and synced: reserved names, the unrecord refusal, and insert with its closure. $ atomic vault sync
Synced 1 vault file(s).
$ atomic kind init tool-result
✗ Invalid argument: kind name "tool-result" is reserved
# exit 2
$ atomic unrecord CKYYMTNKMSNAA6DJSR6MLG7NEHA5NB23WLDJZIQPLGHRXHRR2UVA
✗ Internal error: atomic:REPOSITORY: Unrecord error: Cannot unrecord CKYYMTNKMSNAA6DJSR6MLG7NEHA5NB23WLDJZIQPLGHRXHRR2UVA: change 6BCWKBXKWSCW3OOFLERO4LR5MKRX77SSZUJ4EMK5YFOORU5N463Q in the dependency closure of view 'adrs' depends on it; unrecord dependent changes first
# exit 128
$ atomic insert NQVA344AVCJ6D7Q4V7FX3ND7IEXSZLR6FEPZHGIDXGXZRO4RO24A --to dev
ℹ Inserting change NQVA344AVCJ6D7Q4V7FX3ND7IEXSZLR6FEPZHGIDXGXZRO4RO24A...
✓ Inserted 2 change(s)
New state: T2NSSOTD67VGEGDRU3KO47SGNYICFQRT57WUUDUCO7OWJ3P4MUYQ
$ atomic kind validate --view dev
✓ adr: 3 fields, edges implements, supersedes; 1 instance conform
✓ 1 kind (1 registered), 1 instance in the view dev: all validInserting one ADR brought the definition with it: 2 changes. |
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Summary
Let a repository define its own vault kinds, such as ADRs, RFCs, runbooks or incident reports, as tracked data. This works the way a Kubernetes CustomResourceDefinition adds a resource type to a cluster. A kind is defined by a
.vault/kinds/<name>/_kind.mdfile, and its instances live next to it. Atomic validates instances against the definition, projects them into the knowledge graph as typed nodes, and exposes them through one genericatomic kindcommand.No new storage or transport is needed. Vault files are already ordinary tracked content in the patch graph. Definitions and instances therefore get history, view filtering, push/pull/clone, insert with dependency closure and unrecord guards today, with zero new code. Kinds exist only in the derived layers (
VAULT_ENTRIES, the manifest, the KG and embeddings). The work is a registry made of tracked data, a small fail-closed validator, and a handful of routing fixes in those derived layers.The MVP (M0–M2 below) is estimated at 8–11 engineer-days. M0 can start now. M1 needs owner rulings on the first three decisions. Permissions, meaning who may define a kind, are out of scope.
Problem
The kind set is hard-coded in about six registries that share no common source: the
VaultEntryTypeenum, path routing, init defaults, the manifest, KG projection and embedding policy.1fa92ca) touched 55 files and about 10.7k lines.decision(63e2d16) touched 5 files, and older binaries reject that value when it syncs in.Scratch. Kind is inferred only from the path prefix (vault.rs). An unknown prefix becomes Scratch, which is stored, synced and embedded but never gets a KG node (vault_triples.rs). A team that wants ADRs today gets files that are untyped, unvalidated and not queryable by kind.Roughly 60–70% of the touch-points for a new kind are declarative boilerplate that a spec could replace. The rest is real behavior (lifecycle, substance-hash lapse, human keys, triage, context ranking), and this proposal does not try to make that data-driven.
Why this is tractable
pipeline.rs). If a definition's change creates.vault/kinds/<k>/, every later instance depends on it. Insert then brings the definition along, and unrecording it fails withHasDependents(unrecord.rs). That is the "CRD before CR" ordering Kubernetes leaves to the operator.KgNode.kindandKgEdge.kindare free strings, andquery --kindsandvault_kg_search_by_kindalready filter on arbitrary strings.VaultEntry.frontmatter_jsonaccepts any keys, so instances need no schema change.derived_from_vault_path), so it doesn't depend on kind.atomic memory kindsalready renders registry text for models (kinds.rs).Proposal
There are two tiers. This proposal covers tier A only.
@typeand no signing. This covers most real needs and reopens the fewest owner decisions.Layout
The
_prefix can never collide with a Crockford ULID.A definition is keyed by its path (its name), not by a ULID. If two views define the same name, both land on one path, so patch theory either merges them or raises a conflict. With ULID keys, two incompatible definitions could coexist silently, which is the same failure class as the existing intent human-key collision. Not yet runtime-tested: what happens when two views independently add the same path. This needs a test before we rely on it.
Definition format
Flat frontmatter plus exactly one fenced
jsonblock:deny_unknown_fields. An unknownspecVersionor construct rejects the whole definition, and the kind stays unregistered. It fails closed and is never partially enforced.DIRECTIVE_NAMESregistry, and the directive parser silently drops bare attribute tokens such asrequired(directive.rs).Spec language v1
The spec language is a closed allowlist. Each construct maps one-to-one onto SHACL-Core, so a later
.ttlexport for Circuit Breaker (CB) is mechanical.requiredsh:minCount 1[]sh:maxCount 1string/integer/booleansh:datatype xsd:*enum+valuessh:inref+target(built-inintent/memory, or a custom kind)sh:class, plus an existence check in the viewsh:closed true: undeclared keys are violationsbody.requiredv1 has no regex, no CEL and no
sh:sparql.Storage and identity
VaultEntryType::Scratch, with no new enum variant.list_vault_entriespropagates any postcard decode error (read.rs). A single row with a new variant would make an older binary on a shared redb fail the entire listing. That covers linked worktrees, downgrades and stale daemons. Add a variant only after skip-and-warn decoding ships behind arequired-capabilityrow.kinds/**is excluded fromvault_materialize_all, so stale redb state is never rendered back over view files.urn:atomic:<kind>:<ULID>, and the KG id is<kind>:<ULID>withKgNode.kind = <kind>. Friendly display keys can reuse the intent per-author alias scheme, but they stay aliases. Instances are indexed by ULID.<kind>.<EDGE>. This is a safety requirement, not style.delete_intent_child_nodesruns on every subject re-index. It deletes the target node of any outgoingHAS_TASK,HAS_ACCEPTANCE_CRITERION,HAS_SCOPE_*orHAS_CONSTRAINTedge, and it matches on edge kind alone (vault_triples.rs). A custom field declaringedge: HAS_TASKthat points at an intent would delete that intent from the KG.intent memory goal skill change task ac scope constraint session tool attestation file module entity concept kind). Spine keys (uid,title) and stripped system keys are reserved field names.Instance lifecycle
atomic kind new <k> --set f=v [--body-file]mints a ULID and applies write-timedefaults. Defaults are written into the file, never applied at read time, so the hash never depends on the spec. It runs the gate fail-closed before writing, then writes the file and records it.atomic kind validate [<k>] [--view V] [--json]checks namespace closure, spec validity, every instance and reference existence. It rejects conflict-marker lines. A non-zero exit makes it usable in CI and CB.vault_extract_kg, plusentry_subject/path_to_subject: a node, scalar metadata, aconformsflag and namespaced ref edges.embedflag, applied the same way by auto-index and byvault_embed_all. (Today those two disagree: one uses a deny-list, the other an allow-list.)kind delete-instancecomes later. GC is path-derived, so it works even after the spec is gone.CLI and agents
atomic kind {list, show, init, new, validate}. We don't generate a clap tree per kind, which would repeat the copied memory CLI. Sugar likeatomic adrs newwould need a new mechanism (allow_external_subcommandsisn't used today) and is deferred.atomic kind show <k> --guidanceandkind list --guidance, following thememory kindsprecedent. Spec prose is untrusted repository data. It is rendered as delimited, quoted data with length caps and the author shown, and never spliced into skills or system prompts.Versioning through patch theory
kinds/<k>/.RecordOptions::extra_dependencies, so each instance change depends on the definition frontier: the visible changes that introduced the current spec file's edges. Insert closure then carries the exact spec revision.specVersion: optional fields, new enum values and relaxed cardinality are allowed. Narrowing needs a new versioned kind (tier B). Hand edits can bypass the check inkind apply, sokind validatereportsDEFINITION_NARROWED.kind migraterewrites them as one reviewable change that can be unrecorded.Built-in kinds stay compiled in
Intent and Memory are not re-expressed as specs. Byte-identical hashes,
deny_unknown_fieldsstructs and rules beyond SHACL-Core (rollup, EvidenceShape) would make a spec-driven lift a long tail of quirks. We follow Kubernetes instead: compiled-in built-ins plus an extension tier. Later, we could optionally ship descriptive compiled-in specs for the built-ins. These would feedkind list, the reserved-name list and a generatedctx.jsonld, while the hand-coded gates stay authoritative. Skill is the first real migration candidate: about 12 sites, no behavior and no canonical hash.Out of scope: who may define a kind
This proposal doesn't restrict who can create or change a kind definition. Custom kinds work without that restriction, and permissions are better designed once for the whole vault than for one directory, so they belong in a separate proposal.
The gap exists today. Sandbox grants include
vault.writeby default (sandbox.rs), and the sandbox gate treats all of.vault/as one capability (services_sandbox.rs), so an agent can add a_kind.md. That is the absorption the closed vocabulary warns about: "An agent being able to invent:::whateverand have it lift to a node is how the graph rots" (recording-the-why.md). Until permissions land, kind definitions are protected only by review.One option raised in early review is to enforce permissions at the graph-ops level. An atomic server would reject a submitted change from an agent identity if its graph operations create or modify a kind definition. The agent could still write the file locally; the change is rejected only when it is submitted. Points for that follow-up:
_kind.mdfrom agent auto-add would avoid that.Example (illustrative)
All commands and output below are made up, following the design above.
Edit it to:
The prose is guidance for people and agents and is never validated. The JSON block is the schema.
The resulting file:
status: proposedcame from the definition's default and was written into the file, so the stored text, and therefore its hash, never depends on the definition. The ADR's change automatically depends on the change that created.vault/kinds/adr/, which is the definition.atomic insert <adr-change> --to-view mainbrings the definition along through dependency closure, somaincan't end up with ADRs it can't interpret.adr:nodes."deprecated"tostatusis a widening and passes. Makingsupersedesrequired is reported asDEFINITION_NARROWED, along with the instances that lack it.atomic kind validatein CI is the backstop.Phased plan
atomic-canonicalspec parser + path rules; subject rules; Scratch-arm projection with namespaced edges; spec-change re-index hook; embed policyquery --kinds adr); correct GC; no hash, schema or proto changesatomic kind validate --view --json;conformsmetadatakind list/show/init/new(gate before write, file first); skipkinds/**in materialize-all; agent guidance in the vault skill docextra_dependencies+ frontier pinning; widen-only check;kind migrateattest_valuewith a pinnedconformsTospec hash; parameterizedsubstance_view; guardedstatetransitions;.ttlexport for CBctx.jsonld; migrate Skillctx.jsonlddriftThe MVP (M0–M2) is about 8–11 days and 1.7–2.4k lines including tests. That is less than adding Memory as a built-in kind cost.
Decisions needed
The central question is the scope and authority of a kind definition. Decisions 1–3 are facets of it. The remaining facet, who may define a kind, is out of scope. Each item lists the default this proposal assumes, so it's enough to reply with "agree with N" or argue for an alternative.
Is "closed per view, relative to registered specs" an acceptable reading of the closed vocabulary? Built-in
vocab.rsclosure is untouched (vocab.rs). Custom kinds form a separate tier that is also closed: undeclared kinds, fields, values and edges are gate errors. But the set becomes repository data, so the answer to "what is valid" depends on the view.Proposed: yes.
May a small data-driven validator run in the binary? This reinterprets the 2026-07-06 decision that SHACL validation runs as a CB workflow and that atomic keeps a hand-coded tier-1 gate (
shacl-oxirs-spike-findings.md). It also forces a choice between that direction and the unmergedfeat/semweb-knowledge-graphdirection (PurRDF in a CLI-only crate, shapes in.atomic/shapes/*.ttl). Note that.atomicis always ignored, so those shapes never sync.Proposed: yes, scoped to custom kinds only: about eight SHACL-Core constructs, fail-closed, no SPARQL, and a
.ttlexport so CB remains the full validator. Fallback if no: the binary enforces registration only, CB validates, and custom kinds stay second-class.Registry scope: per view or project-wide? Spec files live in the graph, so they are naturally per view. The semweb plan and the single
vaultref indocs/vault-sync-design.mdlean project-wide.Proposed: per view.
Naming and namespacing.
kind:, memory kinds andinit --kind. Wouldschemaortyperead better?Proposed: no default. This draft uses
kindand a reserved list as placeholders.Spec evolution contract. Widen-only in place, with versioned kinds for narrowing? Must tier-B attestations pin the spec hash permanently? That would forbid GC of any spec revision an attestation references.
Proposed: widen-only plus versioned kinds; the pinning question is open.
Should built-in value sets (
INTENT_KIND,MEMORY_KIND) become repo-extensible instead? This is cheaper and removes the release behind commits like63e2d16. But it makes the built-in gate's verdict depend on repository data, which is a bigger closure concession than a separate custom tier.Proposed: no. Keep built-in sets binary-defined and let custom kinds absorb the need.
Should the vault index's authority problems be fixed first? These predate custom kinds, and custom kinds would multiply their effects:
tables.rs:779vspull/command.rs:936);Proposed: open.
Alternatives considered
VaultEntryTypevariantlist_vault_entrieson any older binary sharing the redb::property{…}).atomic/shapes/*.ttl(semweb branch).atomicis always ignored, so shapes are per clone and never syncKnown risks and mitigations
<kind>.<EDGE>namespacing, plus a test that a customHAS_TASKcan't delete an intent.conformsTohash in tier B.": ", so the frontmatter parser skips them, and keys from both sides land in one map with the last key winning. (This comes from reading the code and hasn't been runtime-tested.) Mitigation:kind validaterejects marker lines, and M3 adds a deflate guard that benefits every vault kind.extra_dependenciesfrontier pinning (M3), and an ordering check inkind new.vault_deletecan leave a stale<k>:<ULID>node. Mitigation: an orphan sweep invault_reindex_kg.@typeis never validated, lift errors are swallowed with.ok(), and verification value sets go unchecked. These should be fixed before tier B so the generic path doesn't copy fail-open behavior.OperationKind. Spec activation is only a derived effect of recorded changes, soop undoof the record is the undo path.Prior art: Kubernetes CRD → Atomic mapping
.vault/kinds/<name>/_kind.md(tracked, view-filtered)metadata.namespec.groupnames.kind/plural/singular/shortNamesname= KG kind = URN segment = directoryscopeNamespaced/Clusterversions[],served,storagespecVersion(language version) now; served/storage kind versions in tier Bconversion: Nonekind migrateproduces one recorded changeopenAPIV3Schema(structural)x-kubernetes-preserve-unknown-fields/ pruningdefaultx-kubernetes-validationsadditionalPrinterColumnskind listcolumns from scalar fieldssubresources.statusstatefields excluded from the substance hash; guarded transitionsHasDependents; guarded deleteEstablished, …)kind show: Registered / Invalid / Conflicted / instance countmetadata.uidurn:atomic:<kind>:<ULID>resourceVersion/ optimistic concurrencykubectl explainatomic kind show --guidanceFeedback wanted
All reactions