Skip to content

feat: Phase 1 knowledge graph closure and SHACL validation - #265

Merged
geekgonecrazy merged 19 commits into
devfrom
feat/semweb-knowledge-graph
Oct 26, 2026
Merged

geekgonecrazy merged 19 commits into
devfrom
feat/semweb-knowledge-graph

Conversation

@graywolf336

@graywolf336 graywolf336 commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • Add canonical workflow ontology, project identities/IRIs, generation-fenced KG projection, and PurRDF validation.
  • Route new KG inspection and reindex access through RPC and the shared connection opener.
  • Include acceptance harness, upgrade docs, and CI/toolchain updates. Merge latest dev; keep branch-added vault artifacts local.

Validation

Core/repository and CLI suites, local/reactor RPC integration, KG harness, Rust 1.90 library checks, clippy, and formatting passed.

Before ready

Independent review found three reproducible projection bugs: cross-intent evidence overwrite, unresolved references after late change import, and case-folded canonical IRI collisions. Fix these, refresh the author attestation, and complete full triage.

graywolf336 and others added 13 commits October 22, 2026 14:40
Add the knowledge-graph closure RFC (intent → session → turn →
provenance → change → resource, with an OWL 2 RL ontology and SHACL
shapes) and a Phase 1 plan based on a survey of the current KG code.

The plan covers the canonical IRI and identity model, the full
old-to-new term replacement table, seven milestones (ontology, project
identity, storage generation, projectors with unified reconcile,
in-house RL reasoner, validation, consumer cutover), acceptance tests,
and eleven resolved design decisions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…tity on clone

- Phase 1 now covers clean up plus using the common language: the KG
  producers are rewritten to emit canonical terms and project-qualified
  IRIs, and every consumer moves onto them (new §1.6, milestone M3).
  The storage prerequisites (typed predicate API, kg_types, one-time
  KG_GENERATION rebuild, capability fence) move with it; SHACL becomes M4.
- AST edges leave the KG, so `query callers` and triage blast radius
  switch to live atomic-semantic parsing (they read KG CALLS/DEFINES
  edges today).
- Split atomic:explainedBy into turnExplainedBy and changeExplainedBy:
  a SessionTurn domain on the chain-derived property would infer every
  Change to be a SessionTurn.
- Clones keep the origin's identity: only the `atomic init` command
  mints (clone calls Repository::init before pulling), pulls never
  change a populated identity, the first push binds the Atomic storage
  project, and mismatched pushes are rejected.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Plan updates:
- Restore a "Current code (starting point)" section with file:line
  references to the KG storage, producers, vocabulary, identity
  problems, overloaded relations, unprojected facts, and consumers.
- Defer clone/pull/push identity transport until atomic-storage
  implements it (clone is HTTP-only, so all three depend on the
  server); Phase 1 covers local identity work only. Acceptance
  criterion 6 marks the transport checks as deferred.
- Add implementation rules: uppercase identifiers with strict URN
  parsers, old-layout intents resolved via the manifest or a finding,
  attestation-to-turn mapping only on a unique match, MAC attestations
  recorded as Unverifiable, and atom: terms translated at projection
  time without rewriting signed documents.

New docs/knowledge-graph-phase1-proposals.md, for approval: the
complete LEGACY_TERMS mapping, missing ontology terms (including a
status/priority domain bug), the ProjectIdentity context and hash
construction, and two open questions (PurRDF's Rust 1.98 requirement,
MAC signers vs. the publication profile).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Publication requires an atomic identity DID signer; MAC-signed
  attestations never satisfy the publication profile (decided by Lee).
  Applied to plan §1.4 and the attestation projector row in §1.6.
- Rust 1.98: CI's `cargo clippy --workspace -- -D warnings` passes with
  rust-version = "1.98" on 1.98.1. A workspace-wide bump would break
  atomic-storage (Docker images pin rust:1.94) and sherpa-server
  (declares 1.94), since every crate inherits the workspace
  rust-version. Recommend a scoped bump: PurRDF in its own crate at
  1.98 used only by atomic-cli, shared library crates stay at 1.90.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Lee approved the proposals; merge them and delete the review doc.

- §1.5: the complete LEGACY_TERMS mapping (all 81 old constants,
  each exactly once); coverage test now includes prefix constants.
- §1.1: missing ontology terms (parent and inverse properties,
  verificationResult and VerificationStatus, Project/ProjectIdentity
  terms, reused PROV and literal terms, turnNumber) and remove the
  WorkIntent domain from status/priority.
- §1.3: ProjectIdentity uses an inline @context and a type-prefixed
  hash, blake3("atomic.project-identity.v1" || 0x00 || JCS).
- §1.4/M4: scoped Rust 1.98 bump. PurRDF goes in its own atomic-shacl
  crate used only by atomic-cli; shared library crates stay at 1.90 so
  sibling repos that build them by path keep working.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Three cold-read reviews by agents without prior context; the third
found no blockers. Changes:

- Identity: every repository mints (Created for init/git import,
  Upgrade otherwise, replaceable later by transport) through one
  ensure_project_identity() called from init/import, full writable
  opens, and every KG write path (covers clone and git import, which
  enrich without reopening). IRI schemes for every node kind; identity
  object storage, signing, and crate placement; CLI renamed to
  `atomic repo identity`.
- Shortcuts: producers assert implements, changeExplainedBy, and
  attestedBy in Phase 1; per-change findings explain missing ones and
  the projection shape accepts them. attestedBy is the inverse of
  coversChange.
- Attestations: always link to their session (attestsSession); link
  to a turn only on a unique non-empty match. Verification looks up
  the signer's public key by DID from the local identity store, then
  a signer-key cache filled from Atomic storage; fetched keys must
  match the DID fingerprint. Notes the storage fix needed: by-key must
  match did:atomic: fingerprints, not decode them as raw keys.
- Ontology: linkedGoal domain and informedBy range removed; term enums
  cover external terms and datatype ranges; RL allow-list test.
- Specs: which opens mint/rebuild, producers skip writes on an
  old-generation KG, legacy URN resolution, ManagedIntent, encoding
  set, metadata-to-RDF mapping, query callers argument, whole-view
  triage parsing, lint scope, lockfile checks, corrected references.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@graywolf336
graywolf336 force-pushed the feat/semweb-knowledge-graph branch from c7ccd8e to 5907609 Compare October 22, 2026 19:47
graywolf336 and others added 5 commits October 22, 2026 21:16
Preserve authoritative vault child evidence, repair late-arrival references
and dependency facts, and resolve canonical resource IRIs exactly.

Analyze change impact from recorded syntax in the requested Atomic view,
including TypeScript imports and public-visibility changes. Update typed
fixtures, closure CI coverage, and deterministic transport/watcher tests.

Validated on macOS with the full workspace CI test command, all-target
Check and Clippy, rustdoc, formatting, packaging tests, CLI harnesses
09/14/46, and scoped Rust-version checks.

GitHub publication snapshot for ATOM::bradley::1; independent Atomic
re-review and hook-recorded candidate coverage remain separate.
@graywolf336
graywolf336 marked this pull request as ready for review October 25, 2026 08:00
@graywolf336
graywolf336 added this pull request to stack #287 October 26, 2026 11:22
@geekgonecrazy
geekgonecrazy merged commit 8fd487a into dev Oct 26, 2026
8 checks passed
@geekgonecrazy
geekgonecrazy deleted the feat/semweb-knowledge-graph branch October 26, 2026 17:11
@geekgonecrazy
geekgonecrazy restored the feat/semweb-knowledge-graph branch October 26, 2026 17:24
geekgonecrazy added a commit that referenced this pull request Oct 26, 2026
The workflow only triggered for PRs targeting dev, so stacked PRs
(e.g. the project-identity transport on top of #265) never ran CI.
Add the feature base branch to the trigger list.

🤖 Generated with [OpenCode](https://opencode.dev)

Co-Authored-By: OpenCode <noreply@opencode.dev>
geekgonecrazy added a commit that referenced this pull request Oct 26, 2026
…ciles, push binds (#288)

* feat(identity): project-identity transport — clone adopts, pull reconciles, push binds

Implements the atomic half of ProjectIdentity transport, stacked on
#265 and paired with the atomic-storage PR of the same branch name:

- atomic-remote: GET/POST /code?project-identity=1 client methods.
  Old servers answer the project-info ping (no 'bound' field) or 404/405 —
  both degrade to 'unsupported' so every flow keeps its pre-transport
  behavior. No new endpoints are required from old servers and none of
  the binary sync structs changed, so no protocol version bump.
- atomic-core/atomic-repository: MintReason::Adopted + a transactional
  adopt that (a) inserts when the repository has no identity, (b) replaces
  the transport-replaceable Upgrade mint, (c) never overwrites an
  established Created/Adopted identity (reported as Diverged instead).
  Re-adopting the same document is a no-op. Adoption always recomputes the
  canonical hash, verifies a DID proof when the signer key resolves locally
  (cached signer keys, then the local default identity), and invalidates
  the derived KG on replacement so it re-projects under the adopted id.
- libatomic: shared reconcile/bind orchestration (fetch is async, repo
  writes stay in blocking tasks), wired into clone, pull (local + daemon),
  and push (local + daemon). Pulls and clones never fail on adoption
  trouble — divergence is a loud warning; a push to a remote bound to a
  different identity refuses before any object moves.
- tests: adoption matrix (5), wire tests against a scripted server (6),
  and harness 47 (live-server E2E: push binds, clone adopts, delete +
  reclone restores the same identity, a second user's clone shares it;
  skips cleanly without a server).

Closes the 'every clone mints its own project id' gap: once the storage
PR lands, a clone carries its origin's identity, delete + reclone is
stable, and mismatched pushes are refused at the namespace boundary.

🤖 Generated with [OpenCode](https://opencode.dev)

Co-Authored-By: OpenCode <noreply@opencode.dev>

* feat(identity): divergence remediation — repo identity adopt/fork

A diverged project identity (local lineage differs from the remote
binding) previously had no CLI escape hatch: pull kept the local
identity with a warning, push refused, and the only manual remedy was
deleting .atomic and re-cloning — losing local-only work. Worse, the
push error told users to 'pull to adopt', which the Diverged guard
correctly refuses for established identities.

- atomic repo identity adopt [--remote N] — fetch the remote binding
  and force-adopt it over ANY local identity, then rebuild the derived
  KG under the adopted id. The project identity is only the KG
  namespace (canonical data uses intrinsic ids), so this preserves all
  local-only work. The document is hash-verified; DID proofs verified
  when the signer key resolves locally.
- atomic repo identity fork — the explicit fork action: mint a fresh
  (default-identity-signed) lineage, abandoning the previous one.
  Remotes bound to the old id refuse pushes; create a new project.
- force_write_project_identity txn + Repository::force_adopt_remote_identity
  / fork_identity; verification shared with plain adoption.
- pull/clone divergence warnings and the push-conflict error now name
  the real remediation instead of the dead-end advice.
- tests: force-adopt replaces established + forces rebuild, force-adopt
  still verifies, fork mints distinct signed lineages and refuses plain
  re-adoption of the abandoned one (8 total in the transport suite).

🤖 Generated with [OpenCode](https://opencode.dev)

Co-Authored-By: OpenCode <noreply@opencode.dev>

* ci: run checks for PRs stacked on the KG feature branch

The workflow only triggered for PRs targeting dev, so stacked PRs
(e.g. the project-identity transport on top of #265) never ran CI.
Add the feature base branch to the trigger list.

🤖 Generated with [OpenCode](https://opencode.dev)

Co-Authored-By: OpenCode <noreply@opencode.dev>

* fix(tests): drop an unused mut that is fatal under CI's -D warnings

🤖 Generated with [OpenCode](https://opencode.dev)

Co-Authored-By: OpenCode <noreply@opencode.dev>

---------

Co-authored-by: OpenCode <noreply@opencode.dev>
geekgonecrazy added a commit that referenced this pull request Oct 26, 2026
#265 and #289 both land via dev; the feature-branch trigger entry was
only needed while the transport PR was stacked on an unmerged base.

🤖 Generated with [OpenCode](https://opencode.dev)

Co-Authored-By: OpenCode <noreply@opencode.dev>
Zaba505 added a commit to Zaba505/atomic that referenced this pull request Nov 6, 2026
Add `kind_spec`, the open-world extension tier beside the closed `vocab`
registry. A kind's definition frontmatter (`kinds/<k>/_kind.md`) is parsed
into a `KindSpec` with every problem collected and path-qualified, and
instances are validated against it with stable violation codes, ref
resolution through a caller-supplied `RefResolver`, and namespaced edges
(`<kind>.<EDGE>`) for projection. Also adds write-time helpers
(`apply_defaults`, `parse_set_value`) and a SHACL-Core summary for display.

Picked from 7b5c539. The self-reference test's edge fixture changes from
`CHILD_OF`, a term atomicdotdev#265 retired, to `PARENT_OF_ADR`, so the KG vocabulary
lint stays green.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Zaba505 added a commit to Zaba505/atomic that referenced this pull request Nov 6, 2026
New `repository::kinds` module for user-defined vault kinds:

- `KindSource` (working copy or a named view) and `KindFiles`, a reader
  that lists `kinds/**`, checks existence and reads files from disk or
  from a view's tracked graph content. Never reads redb VAULT_ENTRIES.
- `KindRegistry` built from definitions (`kinds/<k>/_kind.md`); a missing
  frontmatter block, a YAML error, conflict markers or any spec error makes
  the kind Invalid (fail closed). `KindRegistry::load_kind` reads a single
  definition for per-instance lookups. View registries are cached on
  `Repository` by the view's Merkle folded with its ancestors'.
- `KindRefResolver` resolving custom-kind instances and memory files
  against the same source and intents through `vault_intent_path`.
- `Repository::kind_validate` producing a serde-serializable report with
  UNREGISTERED_KIND, KIND_INVALID, STRAY_FILE, FRONTMATTER_INVALID and
  CONFLICT_MARKER problems plus per-instance violations.
- Helpers for the CLI: `kinds_dir`, `mint_kind_uid`, `kind_definition_path`,
  `kind_instance_path`, `KindPath::classify`, `check_instance`.

`split_frontmatter` becomes `pub(crate)` so the module can reuse it.

Rewritten from 9bc650a for atomicdotdev#265. `entry_subject` no longer exists, so the
resolver answers intent and memory refs with the target's vault path, an
opaque id, rather than a KG subject. `Repository` construction merges with
dev's `semantic_closure_memo`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Zaba505 added a commit to Zaba505/atomic that referenced this pull request Nov 6, 2026
…ze_all

A kind instance is embedded iff its kind is registered with `embed: true`,
identically in `vault_auto_index` and `vault_embed_all`. A deflate batch
that touches a definition re-applies the policy to every entry of that
kind, because an entry is otherwise embedded only as it is stored.

`vault_materialize_all` no longer writes `kinds/` files: they are
authoritative on disk and their redb rows are only a projection.

Rewritten from 8bf2c9b, keeping its non-KG half. atomicdotdev#265 replaced the KG this
commit used to project into, so dev's `vault_triples.rs` and whole-vault
`vault_reindex_kg` stand unchanged here and no kind KG hook lands. The
projection of kinds into the KG comes later in this series, through
`VaultProjection`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Zaba505 added a commit to Zaba505/atomic that referenced this pull request Nov 6, 2026
…rebuild the reserved lists

The kind spec language still spoke the graph vocabulary atomicdotdev#265 retired:
`<k>.<EDGE>` edge kinds, `<k>:<ULID>` node ids and `urn:atomic:<k>:<ULID>`.
None of them survive. `namespaced_edge`, `instance_kg_id`, `instance_urn`,
`KindSpec::summary_rows` and `ShaclRow` are gone, `lift::as_urn` is private
again, and `kind show` no longer prints a SHACL table its rows could not back
up. Its behaviour against SHACL gets a test of its own later in this series.

`edge:` now names a label on a relation, so its grammar becomes
`^[a-z][a-zA-Z0-9_]*$`, and `edges()` and `ResolvedRef.edge` carry the bare
label. Upper-case terms can no longer be spelled in a spec.

A kind name is now reserved when, lowercased with `-` and `_` dropped, it is
the local name of an ontology class or one of `intent`, `kind`, `kinds`, `urn`
and `did`. That is 33 names, and it catches `tool-result`, `finding` and
`project`, which the old 51-entry list missed. `module`, `entity`, `layer`,
`content`, `test` and `agent` become legal. `atomic-canonical` cannot depend
on `atomic-core`, so a test in `atomic-repository/tests/it/kg_kinds.rs` holds
the list equal to `Class::ALL`. A second test there replaces the old
identifier test: generated instance and hub names round-trip through
`parse_concept`, and no other `iri::parse_*` accepts them.

Only `uid`, `title`, `entry_type`, `content_hash` and the timestamps stay
reserved field names, since the KG metadata names no longer need protecting.

`KindRefResolver` now answers every target with a vault path, which is what
it already did for intents and memories. `kind new` keeps printing the
`<k>:<ULID>` handle but drops `kg_id` from its JSON until a real IRI exists.

Also update `kind_view_test`'s `Dependencies: 1` to `Dependencies (1)`, the
form atomicdotdev#265's `change --show-deps` renderer prints. The test had been red since
it was replayed onto dev.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Zaba505 added a commit to Zaba505/atomic that referenced this pull request Nov 6, 2026
This is a rewrite, not a port. It replaces the KG half of 8bf2c9b, 4361e76
and fda76b8 from the pre-atomicdotdev#265 branch: `vault_extract_kind_kg`,
`KindRefResolver::stored`, `KindBatchContext`, `kg_incoming_edge_owners`,
`kind_instances_referring_to`, `kind_instance_nonconforming` and the KG half
of `vault_reindex_kind`, none of which were replayed. Dev's whole-vault
re-resolve on every store makes those hooks unnecessary: spec edits, target
arrival and target deletion now converge with no kind-specific code. Only
`vault_reembed_changed_kinds` survives, because `vault_auto_index` embeds only
the stored path. `vault_triples.rs` and `kg_rebuild.rs` have no diff from dev.

`rebuild_kg`, `project_vault_kg` and `vault_extract_kg` all reach kinds through
one new `Scratch` arm in `VaultProjection`, as every other vault row does:

- An instance is one `atomic:Concept` at `concept:<k>.<ULID>`, a definition one
  at `concept:kind.<k>`. Membership is an `atomic:references` edge to the hub
  labelled `@kind`, plus `metadata.kind_name`.
- A resolved ref with an `edge:` is an `atomic:references` edge with `fields`
  and `edges` in its metadata, merged per target as the last step, because edge
  identity is `(from, to, predicate)` and two fields on one target would
  otherwise overwrite each other. A `[[memory]]` link in the body is labelled
  `@body`.
- Declared field values go under `field.<name>`, which no adapter key or GC key
  can collide with, so a field cannot reach RDF or claim ownership of a row.
- A non-conforming instance stays visible with a `KindViolation` finding, and an
  invalid definition keeps its hub with a `KindDefinitionInvalid` one. A row
  failing the arm predicate stays inert, for `kind validate` to report.

Projection cannot fail on content. `extract_kind_entry` returns no `Result` and
has no `expect` or `unwrap`, and a ref resolves only to a subject this projection
emits a node for, so `rebuild_kg`'s closure check holds. `rebuild_kg` runs under
`?` in writable open, so anything less could lock a user out of a repository.
`no_repository_content_can_fail_projection_or_writable_open` runs malformed
instances, invalid specs, dangling refs, refs to malformed instances and
instances of unregistered kinds through an expired-generation writable open.

Labels share this namespace: `iri::mint_concept(project, label)` means an intent
labelled `kind.adr` or `adr.<ULID>` names a kind node's exact IRI. The owned node
wins in every write order, since a label's stub has no owner and lands only while
the IRI is free. The one failure was an instance going inert under a label on a
row that sorts before `kinds/`: the stub did not land, then the row deleted its
old node, and `del_kg_node` took the label's edge with it, which a rebuild keeps.
Such a row now owns a bare node while a label names it. No repository without
`kinds/` rows changes: `a_repository_with_no_kinds_projects_as_it_did_before_kinds`
pins a digest computed by running that same fixture on dev at 5c31fae.

Unlike built-ins, kinds do not project file mentions from the body. A File stub
has no owner, so it would outlive the last row that mentions it until a rebuild.
Every unowned stub on dev does this today (a removed label, assignee or file
mention leaves an orphan node), but this keeps kinds out of that class, so an
instance's life cycle always ends where a rebuild does.

The behaviour tests of 4cdfde7 and 4361e76 are ported to `tests/it/kg_kinds.rs`
with no hook behind them, along with an `#[ignore]` timing probe. Dropped because
what they guard is gone: `test_kind_custom_has_task_edge_cannot_delete_intent_children`,
`test_vault_reindex_kind_rejects_invalid_name`, `test_kind_subjects`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Zaba505 added a commit to Zaba505/atomic that referenced this pull request Nov 12, 2026
Add `kind_spec`, the open-world extension tier beside the closed `vocab`
registry. A kind's definition frontmatter (`kinds/<k>/_kind.md`) is parsed
into a `KindSpec` with every problem collected and path-qualified, and
instances are validated against it with stable violation codes, ref
resolution through a caller-supplied `RefResolver`, and namespaced edges
(`<kind>.<EDGE>`) for projection. Also adds write-time helpers
(`apply_defaults`, `parse_set_value`) and a SHACL-Core summary for display.

Picked from 7b5c539. The self-reference test's edge fixture changes from
`CHILD_OF`, a term atomicdotdev#265 retired, to `PARENT_OF_ADR`, so the KG vocabulary
lint stays green.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Zaba505 added a commit to Zaba505/atomic that referenced this pull request Nov 12, 2026
New `repository::kinds` module for user-defined vault kinds:

- `KindSource` (working copy or a named view) and `KindFiles`, a reader
  that lists `kinds/**`, checks existence and reads files from disk or
  from a view's tracked graph content. Never reads redb VAULT_ENTRIES.
- `KindRegistry` built from definitions (`kinds/<k>/_kind.md`); a missing
  frontmatter block, a YAML error, conflict markers or any spec error makes
  the kind Invalid (fail closed). `KindRegistry::load_kind` reads a single
  definition for per-instance lookups. View registries are cached on
  `Repository` by the view's Merkle folded with its ancestors'.
- `KindRefResolver` resolving custom-kind instances and memory files
  against the same source and intents through `vault_intent_path`.
- `Repository::kind_validate` producing a serde-serializable report with
  UNREGISTERED_KIND, KIND_INVALID, STRAY_FILE, FRONTMATTER_INVALID and
  CONFLICT_MARKER problems plus per-instance violations.
- Helpers for the CLI: `kinds_dir`, `mint_kind_uid`, `kind_definition_path`,
  `kind_instance_path`, `KindPath::classify`, `check_instance`.

`split_frontmatter` becomes `pub(crate)` so the module can reuse it.

Rewritten from 9bc650a for atomicdotdev#265. `entry_subject` no longer exists, so the
resolver answers intent and memory refs with the target's vault path, an
opaque id, rather than a KG subject. `Repository` construction merges with
dev's `semantic_closure_memo`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Zaba505 added a commit to Zaba505/atomic that referenced this pull request Nov 12, 2026
…ze_all

A kind instance is embedded iff its kind is registered with `embed: true`,
identically in `vault_auto_index` and `vault_embed_all`. A deflate batch
that touches a definition re-applies the policy to every entry of that
kind, because an entry is otherwise embedded only as it is stored.

`vault_materialize_all` no longer writes `kinds/` files: they are
authoritative on disk and their redb rows are only a projection.

Rewritten from 8bf2c9b, keeping its non-KG half. atomicdotdev#265 replaced the KG this
commit used to project into, so dev's `vault_triples.rs` and whole-vault
`vault_reindex_kg` stand unchanged here and no kind KG hook lands. The
projection of kinds into the KG comes later in this series, through
`VaultProjection`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Zaba505 added a commit to Zaba505/atomic that referenced this pull request Nov 12, 2026
…rebuild the reserved lists

The kind spec language still spoke the graph vocabulary atomicdotdev#265 retired:
`<k>.<EDGE>` edge kinds, `<k>:<ULID>` node ids and `urn:atomic:<k>:<ULID>`.
None of them survive. `namespaced_edge`, `instance_kg_id`, `instance_urn`,
`KindSpec::summary_rows` and `ShaclRow` are gone, `lift::as_urn` is private
again, and `kind show` no longer prints a SHACL table its rows could not back
up. Its behaviour against SHACL gets a test of its own later in this series.

`edge:` now names a label on a relation, so its grammar becomes
`^[a-z][a-zA-Z0-9_]*$`, and `edges()` and `ResolvedRef.edge` carry the bare
label. Upper-case terms can no longer be spelled in a spec.

A kind name is now reserved when, lowercased with `-` and `_` dropped, it is
the local name of an ontology class or one of `intent`, `kind`, `kinds`, `urn`
and `did`. That is 33 names, and it catches `tool-result`, `finding` and
`project`, which the old 51-entry list missed. `module`, `entity`, `layer`,
`content`, `test` and `agent` become legal. `atomic-canonical` cannot depend
on `atomic-core`, so a test in `atomic-repository/tests/it/kg_kinds.rs` holds
the list equal to `Class::ALL`. A second test there replaces the old
identifier test: generated instance and hub names round-trip through
`parse_concept`, and no other `iri::parse_*` accepts them.

Only `uid`, `title`, `entry_type`, `content_hash` and the timestamps stay
reserved field names, since the KG metadata names no longer need protecting.

`KindRefResolver` now answers every target with a vault path, which is what
it already did for intents and memories. `kind new` keeps printing the
`<k>:<ULID>` handle but drops `kg_id` from its JSON until a real IRI exists.

Also update `kind_view_test`'s `Dependencies: 1` to `Dependencies (1)`, the
form atomicdotdev#265's `change --show-deps` renderer prints. The test had been red since
it was replayed onto dev.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Zaba505 added a commit to Zaba505/atomic that referenced this pull request Nov 12, 2026
This is a rewrite, not a port. It replaces the KG half of 8bf2c9b, 4361e76
and fda76b8 from the pre-atomicdotdev#265 branch: `vault_extract_kind_kg`,
`KindRefResolver::stored`, `KindBatchContext`, `kg_incoming_edge_owners`,
`kind_instances_referring_to`, `kind_instance_nonconforming` and the KG half
of `vault_reindex_kind`, none of which were replayed. Dev's whole-vault
re-resolve on every store makes those hooks unnecessary: spec edits, target
arrival and target deletion now converge with no kind-specific code. Only
`vault_reembed_changed_kinds` survives, because `vault_auto_index` embeds only
the stored path. `vault_triples.rs` and `kg_rebuild.rs` have no diff from dev.

`rebuild_kg`, `project_vault_kg` and `vault_extract_kg` all reach kinds through
one new `Scratch` arm in `VaultProjection`, as every other vault row does:

- An instance is one `atomic:Concept` at `concept:<k>.<ULID>`, a definition one
  at `concept:kind.<k>`. Membership is an `atomic:references` edge to the hub
  labelled `@kind`, plus `metadata.kind_name`.
- A resolved ref with an `edge:` is an `atomic:references` edge with `fields`
  and `edges` in its metadata, merged per target as the last step, because edge
  identity is `(from, to, predicate)` and two fields on one target would
  otherwise overwrite each other. A `[[memory]]` link in the body is labelled
  `@body`.
- Declared field values go under `field.<name>`, which no adapter key or GC key
  can collide with, so a field cannot reach RDF or claim ownership of a row.
- A non-conforming instance stays visible with a `KindViolation` finding, and an
  invalid definition keeps its hub with a `KindDefinitionInvalid` one. A row
  failing the arm predicate stays inert, for `kind validate` to report.

Projection cannot fail on content. `extract_kind_entry` returns no `Result` and
has no `expect` or `unwrap`, and a ref resolves only to a subject this projection
emits a node for, so `rebuild_kg`'s closure check holds. `rebuild_kg` runs under
`?` in writable open, so anything less could lock a user out of a repository.
`no_repository_content_can_fail_projection_or_writable_open` runs malformed
instances, invalid specs, dangling refs, refs to malformed instances and
instances of unregistered kinds through an expired-generation writable open.

Labels share this namespace: `iri::mint_concept(project, label)` means an intent
labelled `kind.adr` or `adr.<ULID>` names a kind node's exact IRI. The owned node
wins in every write order, since a label's stub has no owner and lands only while
the IRI is free. The one failure was an instance going inert under a label on a
row that sorts before `kinds/`: the stub did not land, then the row deleted its
old node, and `del_kg_node` took the label's edge with it, which a rebuild keeps.
Such a row now owns a bare node while a label names it. No repository without
`kinds/` rows changes: `a_repository_with_no_kinds_projects_as_it_did_before_kinds`
pins a digest computed by running that same fixture on dev at 5c31fae.

Unlike built-ins, kinds do not project file mentions from the body. A File stub
has no owner, so it would outlive the last row that mentions it until a rebuild.
Every unowned stub on dev does this today (a removed label, assignee or file
mention leaves an orphan node), but this keeps kinds out of that class, so an
instance's life cycle always ends where a rebuild does.

The behaviour tests of 4cdfde7 and 4361e76 are ported to `tests/it/kg_kinds.rs`
with no hook behind them, along with an `#[ignore]` timing probe. Dropped because
what they guard is gone: `test_kind_custom_has_task_edge_cannot_delete_intent_children`,
`test_vault_reindex_kind_rejects_invalid_name`, `test_kind_subjects`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants