From 6e5739ee4cd8611606481821929c74f9984fe784 Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Sat, 24 Oct 2026 10:40:36 +0000 Subject: [PATCH 1/2] docs: disambiguate concern Octad from VeriSimDB's Octad and Tier 2 overlays Add ADR-0014 (modality vocabulary) and align the docs with it: * unqualified "Octad" is VeriSimiser's fixed eight-concern model (`OctadDimension`); upstream is always "VeriSimDB's Octad" (its named eight-modality API/model) * Tier 2 is a fixed six-member overlay modality set, not an octad; upstream's Temporal/Provenance modalities are Tier 1 concerns here * "modality profile" is not adopted: verisimdb#299 defines it as a versioned, implementation-specific selection with explicit cardinality, which the unversioned `[tier2]` booleans are not. Docs use "enabled overlays" for the per-manifest selection. Manifest review fixes (docs only, no field renames): * README documented the legacy `[verisimiser]`/`[tier1]`/`[tier2]` shape as canonical, including `[tier1]` keys that `Tier1Config` does not have and nested `[tier1.provenance]`/`[tier2.vector]` tables that fail to parse. Canonical `[project]`/`[database]`/`[octad]`/ `[sidecar]`/`[retention]` now comes first; the legacy shape is shown accurately and marked parsed-but-inert. * README now states that Tier 2 overlays are stubs and `[tier2]` flags are not yet acted on. Comment/help-text only in src/ (`OctadDimension` doc comment, `tier2/mod.rs` header, `verisimiser octad` help and banner) -- no schema, CLI, or manifest field is renamed. Refs #213, verisimdb#299. Co-authored-by: arena-agent <297053741+arena-agent@users.noreply.github.com> --- 0-AI-MANIFEST.a2ml | 15 +- CHANGELOG.adoc | 9 + CONTRIBUTING-DEV.adoc | 23 +- README.adoc | 209 +++++++++++++----- ROADMAP.adoc | 3 +- TOPOLOGY.adoc | 13 +- docs/architecture/THREAT-MODEL.adoc | 11 +- docs/architecture/TOPOLOGY.adoc | 7 +- docs/decisions/0004-octad-ontology.adoc | 21 ++ docs/decisions/0014-modality-vocabulary.adoc | 210 +++++++++++++++++++ docs/decisions/ADR-0001-octad-ontology.adoc | 6 + src/abi/mod.rs | 15 +- src/main.rs | 9 +- src/tier2/mod.rs | 18 +- 14 files changed, 486 insertions(+), 83 deletions(-) create mode 100644 docs/decisions/0014-modality-vocabulary.adoc diff --git a/0-AI-MANIFEST.a2ml b/0-AI-MANIFEST.a2ml index 282223e..d9f1b2e 100644 --- a/0-AI-MANIFEST.a2ml +++ b/0-AI-MANIFEST.a2ml @@ -12,10 +12,13 @@ This is the AI manifest for **verisimiser**. It declares: - Critical invariants (rules that must NEVER be violated) - Repository structure and organization -**verisimiser** augments existing databases with VeriSimDB octad capabilities. -It wraps PostgreSQL, SQLite, MongoDB, Redis, and other backends to add eight -octad dimensions (data, metadata, provenance, lineage, constraints, access -control, temporal, simulation) without requiring database migration. +**verisimiser** augments existing databases with its fixed eight-concern +Octad (ADR-0004/ADR-0014), drawing capability from VeriSimDB's upstream +eight-modality Octad model. It wraps PostgreSQL, SQLite, MongoDB, Redis, and +other backends to add those eight concerns (data, metadata, provenance, +lineage, constraints, access control, temporal, simulation) without requiring +database migration. "Octad" unqualified means the concern Octad; upstream's +is written *VeriSimDB's Octad*. ## CANONICAL LOCATIONS (UNIVERSAL RULE) @@ -93,9 +96,9 @@ Policy enforcement contracts (k9, dust, lust, must, trust). ## VERISIMISER-SPECIFIC INVARIANTS -- **Octad dimensions**: data, metadata, provenance, lineage, constraints, access-control, temporal, simulation +- **Concern Octad** (ADR-0004): data, metadata, provenance, lineage, constraints, access-control, temporal, simulation -- fixed arity, not the upstream modality Octad - **Tier 1 (piggybacks)**: drift detection, provenance tracking, temporal versioning -- sidecar-only -- **Tier 2 (overlays)**: graph, vector, tensor, semantic, document, spatial -- additional storage +- **Tier 2 (overlays)**: graph, vector, tensor, semantic, document, spatial -- six-member overlay modality set (not an octad); per-manifest enabled-overlay selection (ADR-0014) - **Supported backends**: PostgreSQL, SQLite, MongoDB, Redis (extensible) - **VQL-UT**: Type-safe query interface for octad queries diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index 4aef737..b7f167f 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -70,6 +70,15 @@ fields (#88) ==== Documentation +* docs(adr): 0014-modality-vocabulary — unqualified *Octad* is +VeriSimiser's concern Octad; upstream is always *VeriSimDB's Octad*; +Tier 2 is a six-member overlay modality set with per-manifest enabled +overlays, not a "modality profile" (closes #213) +* docs(readme): vocabulary table for the three octad/modality models; +manifest section corrected to the canonical `[project]`/`[database]`/ +`[octad]`/`[sidecar]`/`[retention]` schema, with the legacy +`[verisimiser]`/`[tier1]`/`[tier2]` shape documented as parsed-but-inert; +Tier 2 subset and stub status called out (#213) * docs(readme): rewrite around concerns octad (V-L1-A2) (#99) * docs(adr): 0009-build-path — cargo + Containerfile canonical; rest experimental (#97) diff --git a/CONTRIBUTING-DEV.adoc b/CONTRIBUTING-DEV.adoc index f57ef9f..b5a9010 100644 --- a/CONTRIBUTING-DEV.adoc +++ b/CONTRIBUTING-DEV.adoc @@ -85,9 +85,11 @@ threshold. == Adding a Tier 2 overlay -Tier 2 overlays require additional storage alongside the target database -(graph, vector, tensor, semantic, …). New overlays are not the same as -new backends. +Tier 2 overlays require additional storage alongside the target database. +The overlay modality set is fixed at six (graph, vector, tensor, +semantic, document, spatial) per ADR-0014; a seventh is an ontology +change, not a config edit. New overlays are not the same as new +backends. [%interactive] * [ ] Add a boolean field to `Tier2Config` in `src/manifest/mod.rs` (and @@ -100,11 +102,22 @@ new backends. queries to the overlay. * [ ] Add a round-trip test in `src/codegen/overlay.rs::tests` covering the flag both on and off. -* [ ] Update `README.adoc`'s *Octad: Eight Modalities* table to reflect - the new overlay's tier and storage. +* [ ] Update the `README.adoc` <> + section (overlay modality set, storage, status) and the vocabulary + table in the README (anchor `octad-vocabulary`). The README no + longer has an "Octad: Eight Modalities" table. Note that + a *new* overlay changes the set's membership and so needs an ADR, + not just a README edit (ADR-0014 §14.3). == Style notes +* **Vocabulary** (ADR-0014): unqualified `Octad` means VeriSimiser's + fixed eight-concern model; write `VeriSimDB's Octad` for the upstream + eight-modality API/model. Tier 2 uses *overlay modality set* for the + fixed six and *enabled overlays* for a manifest's selection — not + "modality profile". Do not rename schema, CLI, or manifest fields to + match a doc change; that needs its own compatibility decision. + * Treat `cargo clippy --all-targets -- -D warnings` as part of `cargo build`. The crate has no blanket `#![allow(...)]` blocks (`docs/decisions/0001` and 0002 keep the surface clean). diff --git a/README.adoc b/README.adoc index d3fe94b..b073d9a 100644 --- a/README.adoc +++ b/README.adoc @@ -33,9 +33,11 @@ Each entity in a VeriSimiser-augmented database is enriched along **eight concerns** — properties you want to know or enforce about the data, independent of how it is stored. The concerns octad is canonical per `docs/decisions/0004-octad-ontology.adoc` (ADR-0004). The earlier -"Eight Modalities" framing (graph, vector, tensor, …) is reframed as a -set of **Tier 2 overlay representations**, not the top-level identity; -see <> below. +"Eight Modalities" framing (graph, vector, tensor, …) is reframed as the +six-member **Tier 2 overlay modality set**, not the top-level identity; +see <> below and +<> for how that differs from +VeriSimDB's Octad. [cols="1,2,1,1,1"] |=== @@ -94,6 +96,46 @@ see <> below. The canonical Rust enumeration of these is `abi::OctadDimension`. The CLI's `verisimiser octad` subcommand prints this set with descriptions. +[[octad-vocabulary]] +=== Three things called "octad" + +"Octad" names two different eight-element models in two different +projects, and VeriSimiser's Tier 2 overlays are a third, non-octad +thing. Per `docs/decisions/0014-modality-vocabulary.adoc` (ADR-0014): + +[cols="1,3,3",options="header"] +|=== +| Term | What it denotes | What it does *not* denote + +| **Octad** (unqualified, in this repo) +| VeriSimiser's fixed eight-**concern** model — the table above. +| Never the upstream modality list; never the Tier 2 overlays. + +| **`OctadDimension`** +| The Rust enum with exactly eight concern variants (Data … Simulation). +| It has no `Graph`, `Vector`, `Tensor`, `Semantic`, `Document`, or `Spatial` variant. + +| **VeriSimDB's Octad** (upstream) +| VeriSimDB's named eight-**modality** API and model — graph, vector, tensor, semantic, document, temporal, provenance, spatial. +| Not a VeriSimiser type, field, or enum; VeriSimiser does not implement all eight of its modalities natively. + +| **Tier 2 overlay modality set** +| The six overlay modalities an entity can additionally be projected into: graph, vector, tensor, semantic, document, spatial. +| Not "the Octad" — it has six members, not eight. Upstream's Temporal and Provenance members are Tier 1 *concerns* here. + +| **Enabled overlays** +| Per-manifest selection from that six-member set (any subset, 0–6 members; all six default to `false`). +| Not a versioned "modality profile" — see below. +|=== + +VeriSimiser docs do not call an enabled-overlay selection a +**modality profile**: upstream +https://github.com/hyperpolymath/verisimdb/issues/299[verisimdb#299] +proposes that term for a *versioned, implementation-specific* selection +of supported modalities, and `[tier2]` flags are unversioned enablement +booleans with derived, undeclared cardinality. Adopting the term here +would need a manifest-schema change first (ADR-0014 §14.5). + == Tier 1: True Piggybacks These work like PostGIS — they add capability without replacing @@ -150,13 +192,13 @@ Prefix-typed principals (`user:`, `group:`, `role:`) and an against the same row that flows through the read-path. See ADR-0007 for the model. -=== Drift detection: symptoms of Constraints violation across modalities +=== Drift detection: symptoms of Constraints violation across representations Drift detection is **what the Constraints concern observes** when the same entity is represented in more than one form and the forms disagree. -Once a Tier 2 overlay (graph, vector, tensor, …) is enabled alongside -the primary Data, the representations can fall out of sync — at which -point the Constraints concern reports the symptom. +Once a Tier 2 overlay modality (graph, vector, tensor, …) is enabled +alongside the primary Data, the representations can fall out of sync — +at which point the Constraints concern reports the symptom. ADR-0003 fixes each drift category as a triple of (input, distance function, default threshold). All categories produce a score in `[0, 1]` @@ -167,7 +209,7 @@ categories: |=== | Category | What it compares | Default threshold -| **Temporal** | `MAX(version)` per modality for the same entity | `0.10` +| **Temporal** | `MAX(version)` per representation for the same entity | `0.10` | **Structural** | Schema fingerprint (sorted `(field, type)` pairs) | `0.05` | **Semantic** | Free-text labels via sentence embeddings (cosine) | `0.20` | **Statistical** | Distributions over the same field (1-Wasserstein) | `0.15` @@ -191,12 +233,15 @@ doesn't modify them. Safe to add, safe to remove, no data dependency. Tier 2 capabilities require additional storage alongside your database. They are honest about being "VeriSimDB modalities with your database as -the primary store." This is still valuable — it's how you get octad -capabilities incrementally — but it's not a bolt-on. - -Tier 2 modalities are **overlay representations** — alternative shapes -the same entity is projected into for a specific query workload. A user -enables `vector` because they want similarity search; they enable +the primary store" — but only a six-member subset of VeriSimDB's Octad +(graph, vector, tensor, semantic, document, spatial). Upstream's Octad +also lists Temporal and Provenance; here those are Tier 1 *concerns* +(see above), not overlays. So Tier 2 is not "the Octad": it is the +**Tier 2 overlay modality set**. + +Tier 2 overlay modalities are **overlay representations** — alternative +shapes the same entity is projected into for a specific query workload. +A user enables `vector` because they want similarity search; they enable `spatial` because they want geofencing. Enabling an overlay is independent of which concerns are active. @@ -212,43 +257,83 @@ independent of which concerns are active. * **Spatial overlay** — geospatial coordinates. Stored in an R-tree sidecar. -Each Tier 2 overlay has its own storage and can be enabled -independently via `[tier2]` in the manifest. Your primary database -remains the source of truth for its native data. When an overlay -diverges from the primary Data, the Constraints concern reports the -symptom via the relevant drift category (see above). +The six-member set is fixed by `Tier2Config` in `src/manifest/mod.rs`; +what a manifest chooses is an **enabled-overlay selection** — any +subset of the six, cardinality 0–6, all defaulting to `false`. Your +primary database remains the source of truth for its native data. When +an overlay diverges from the primary Data, the Constraints concern +reports the symptom via the relevant drift category (see above). + +**Status**: the Tier 2 modules are stubs today (`src/tier2/mod.rs`). +The `[tier2]` flags are parsed but not yet acted on — no overlay index, +overlay DDL, or query routing ships yet, so enabling an overlay is a +declaration of intent rather than an active capability. Overlay codegen +is tracked as V-L1-F/G/H. + +The selection is not a versioned "modality profile" in the sense of +verisimdb#299; see <> and +ADR-0014 before introducing that term anywhere. == The Manifest +The canonical (Phase 1) shape is `[project]`, `[database]`, `[octad]`, +`[sidecar]`, `[retention]`. `[octad]` configures the concern Octad +above; only its six togglable concerns appear, because Data and +Metadata are always on: + [source,toml] ---- -[verisimiser] +[project] name = "my-augmented-db" +version = "0.1.0" [database] -target-db = "postgresql" -connection-string = "postgres://localhost/mydb" +backend = "postgresql" # postgresql | sqlite | mongodb +connection-string-env = "DATABASE_URL" +# schema-source = "schema.sql" + +# The concern Octad (ADR-0004) — six togglable concerns, not modalities +[octad] +enable-provenance = true # SHA-256 hash-chain audit trail +enable-lineage = true # acyclic derivation DAG (ADR-0005) +enable-constraints = true # invariant enforcement / drift reports +enable-access-control = true # row/column policies (ADR-0007) +enable-temporal = true # automatic version history +enable-simulation = false # what-if branches (ADR-0006) -# Tier 1: concerns layered onto your DB without altering its storage -[tier1] -provenance = true # SHA-256 hash-chain audit trail -lineage = true # acyclic derivation DAG (ADR-0005) -constraints = true # invariant enforcement / drift reports -access-control = true # row/column policies (ADR-0007) -temporal-versioning = true # automatic version history -drift-detection = true # cross-modal observer (Constraints symptom) +[sidecar] +storage = "sqlite" # sqlite | postgres | json (ADR-0012) +path = ".verisim/sidecar.db" -[tier1.provenance] -sidecar = "sqlite" # sqlite | postgres | json (V-L2-F3 / ADR-0012) -sidecar-path = ".verisimiser/provenance.db" +[retention] +temporal-days = 90 # purged by `verisimiser gc` +# provenance-days = 0 # 0 = keep forever +# lineage-days = 0 +---- -[tier1.temporal] -sidecar = "sqlite" +`[retention]` keys are `provenance-days`, `temporal-days`, and +`lineage-days` (`0` = keep forever). Sidecar backend and json encoding +are covered in <>. -[retention] -temporal-days = 90 # purged by `verisimiser gc` +=== Legacy manifest sections + +Pre-Phase-1 manifests used `[verisimiser]`, `[tier1]`, and `[tier2]`. +They still parse, so existing files keep working: + +[source,toml] +---- +[verisimiser] +name = "my-augmented-db" + +[database] +target-db = "postgresql" # legacy alias of `backend` +connection-string = "postgres://localhost/mydb" + +[tier1] +provenance = true +temporal-versioning = true +drift-detection = true -# Tier 2: overlay representations (additional storage alongside your DB) [tier2] graph = false vector = false @@ -256,16 +341,40 @@ tensor = false semantic = false document = false spatial = false - -[tier2.vector] -# model = "sentence-transformers/all-MiniLM-L6-v2" -# dimensions = 384 ---- +Read this carefully before copying it: + +* **`[tier1]` accepts exactly three keys** — `provenance`, + `temporal-versioning`, `drift-detection`. Lineage, Constraints, and + AccessControl toggles exist only in `[octad]`. Unknown keys inside a + section are ignored on parse, so a legacy manifest that set + `lineage = true` under `[tier1]` enabled nothing. +* **Nested tables under `[tier1]`/`[tier2]` are a parse error** — + their keys are booleans, so `[tier1.provenance]` or + `[tier2.vector]` fails with a type error. Overlay options such as + embedding model or dimensions are not expressible yet. +* **The legacy sections do not drive behaviour**: the runtime reads + `[octad]`/`[sidecar]`/`[retention]` only. Set those, even if a legacy + section is also present. +* **`backend` and `target-db` disagreeing is an error**, not a silent + tie-break (V-L2-E1). `connection-string` is likewise a legacy + alternative to `connection-string-env`; the env-var form is preferred + so secrets stay out of the file. +* **`[tier2]` is the enabled-overlay selection** over the six-member + Tier 2 overlay modality set, not a modality profile and not part of + the Octad (ADR-0014). The flags are currently inert; see + <>. + +Field names are stable: this section documents them, and does not +rename any of them. A rename would be a compatibility decision of its +own (ADR-0014 §14.6). + The `verisimiser octad` subcommand prints the active concerns from your manifest; `verisimiser doctor` checks that sidecars, thresholds, and retention bounds are configured consistently. +[[sidecar-storage]] === Sidecar storage backends (Phase 1 schema) The Phase 1 manifest uses a single `[sidecar]` section. All octad data @@ -342,7 +451,7 @@ are not yet implemented and refuse explicitly rather than silently no-op. └───────────────────────────────────┼──────────────────────┘ │ ┌───── optional, per-overlay ───────┘ - │ Tier 2 overlays (modalities) + │ Tier 2 overlay modalities (six-member set) │ │ ┌───────┐ ┌────────┐ ┌────────┐ ┌──────────┐ ┌────────┐ ┌────────┐ │ │ graph │ │ vector │ │ tensor │ │ semantic │ │ docs │ │ spatial│ @@ -368,12 +477,18 @@ VeriSimiser is NOT a replacement for VeriSimDB. It is a gateway drug. (Provenance, Lineage, Constraints, AccessControl, Temporal — plus Data and Metadata which are always-on) on your existing database. Zero commitment. -* **VeriSimiser Tier 2** gives you the modality overlays (graph, +* **VeriSimiser Tier 2** gives you the six overlay modalities (graph, vector, tensor, semantic, document, spatial) and the Simulation concern as sidecars. Incremental adoption. -* **Full VeriSimDB** gives you the complete octad with native - cross-modal querying, VCL, and built-in drift normalisation. Full - commitment. +* **Full VeriSimDB** gives you VeriSimDB's complete Octad — its + eight-modality API and model — with native cross-modal querying, VCL, + and built-in drift normalisation. Full commitment. + +Note the asymmetry: VeriSimiser Tier 2 ships six of VeriSimDB's eight +modalities, because Temporal and Provenance are Tier 1 concerns here. +"Octad" in this README always means the concern Octad unless it is +written "VeriSimDB's Octad"; see <>. The migration path is Tier 1 → Tier 2 → full VeriSimDB (if you want it). Most users will be happy at Tier 1 or Tier 2. diff --git a/ROADMAP.adoc b/ROADMAP.adoc index 317f5c5..9f4ad45 100644 --- a/ROADMAP.adoc +++ b/ROADMAP.adoc @@ -7,12 +7,13 @@ == Phase 0: Scaffold (COMPLETE) * [x] RSR template with full CI/CD * [x] CLI with subcommands (init, start, drift, provenance, history, status, octad, doctor, gc, validate, version) -* [x] Manifest parser (verisimiser.toml with `[tier1]`/`[tier2]`/`[retention]` config) +* [x] Manifest parser (verisimiser.toml: `[project]`/`[database]`/`[octad]`/`[sidecar]`/`[retention]`, plus legacy `[verisimiser]`/`[tier1]`/`[tier2]`) * [x] Concerns octad fixed canonical (ADR-0004): Data, Metadata, Provenance, Lineage, Constraints, AccessControl, Temporal, Simulation * [x] Tier 1 data types per concern (ProvenanceEntry, TemporalVersion, DriftReport, AccessPredicate) * [x] ABI module stubs (Idris2 + Zig FFI) and domain-tagged `compute_hash` * [x] Drift categories pinned (ADR-0003): input / distance / threshold per category * [x] README rewritten around concerns octad (V-L1-A2, #20) +* [x] Vocabulary fixed (ADR-0014, #213): unqualified *Octad* = the concern Octad; *VeriSimDB's Octad* = upstream eight-modality API/model; Tier 2 = six-member overlay modality set with per-manifest enabled overlays (no "modality profile") == Phase 1: PostgreSQL Tier 1 MVP — concerns layered onto your DB * [ ] PostgreSQL logical replication interception (Data / Metadata feed) diff --git a/TOPOLOGY.adoc b/TOPOLOGY.adoc index 9930a3a..2f2b521 100644 --- a/TOPOLOGY.adoc +++ b/TOPOLOGY.adoc @@ -2,8 +2,9 @@ === Purpose -verisimiser augments any existing database with the full VeriSimDB octad -of capabilities (the eight cross-modal dimensions). It reads the target +verisimiser augments any existing database with VeriSimiser's fixed +eight-concern Octad (ADR-0004/ADR-0014), drawing on capabilities from +VeriSimDB's eight-modality Octad upstream. It reads the target database schema and a `+verisimiser.toml+` manifest, then generates a sidecar overlay, query interceptors, drift detection, provenance chains, and temporal version history — without requiring schema migrations. @@ -21,8 +22,8 @@ verisimiser/ │ ├── manifest/mod.rs # verisimiser.toml parser │ ├── codegen/mod.rs # Sidecar overlay and query interceptor generation │ ├── intercept/ # Query interception layer -│ ├── tier1/ # Tier-1 octad dimension modules -│ ├── tier2/ # Tier-2 octad dimension modules +│ ├── tier1/ # Tier-1 concern modules (concern Octad) +│ ├── tier2/ # Tier-2 overlay modality stubs (six, not an octad) │ └── abi/ # Idris2 ABI bridge stubs ├── examples/ # Worked examples ├── verification/ # Proof harnesses @@ -36,7 +37,7 @@ verisimiser/ verisimiser.toml manifest │ ┌────▼────┐ - │ Manifest │ parse + validate database backend and octad dimension selections + │ Manifest │ parse + validate database backend, [octad] concerns, [tier2] overlay selection │ Parser │ └────┬────┘ │ validated augmentation config @@ -48,7 +49,7 @@ verisimiser.toml manifest │ Codegen │ emit generated/verisimiser/ (sidecar overlay, query interceptors, │ │ provenance chains, temporal history, drift detectors) └────┬────┘ - │ VeriSimDB octad augmentation artifacts + │ concern-Octad augmentation artifacts (sidecar schema + interceptors) ┌────▼────┐ │ Daemon │ start augmentation daemon alongside target database └─────────┘ diff --git a/docs/architecture/THREAT-MODEL.adoc b/docs/architecture/THREAT-MODEL.adoc index 860d793..a62fed6 100644 --- a/docs/architecture/THREAT-MODEL.adoc +++ b/docs/architecture/THREAT-MODEL.adoc @@ -6,9 +6,11 @@ == Overview -VeriSimiser augments existing databases with VeriSimDB octad capabilities. -It sits between applications and their databases, intercepting reads and writes -to maintain provenance chains, temporal versions, drift indices, and overlay +VeriSimiser augments existing databases with its fixed eight-concern Octad +(ADR-0004/ADR-0014), drawing capability from VeriSimDB's upstream +eight-modality Octad. It sits between applications and their databases, +intercepting reads and writes to maintain provenance chains, temporal +versions, and drift indices, and — once implemented — Tier 2 overlay modalities. == Trust Boundaries @@ -55,7 +57,8 @@ Type-safe queries cross both Tier 1 and Tier 2 boundaries. * **Threat**: False negatives in drift detection (inconsistencies not flagged). * **Mitigation**: 8-category drift classification ensures comprehensive coverage. - Idris2 ABI proofs verify that all modalities are checked. + Idris2 ABI proofs cover the detector's invariants; the taxonomy is + exhaustive over the eight categories. == Data at Rest diff --git a/docs/architecture/TOPOLOGY.adoc b/docs/architecture/TOPOLOGY.adoc index d78b8f6..c61e8f9 100644 --- a/docs/architecture/TOPOLOGY.adoc +++ b/docs/architecture/TOPOLOGY.adoc @@ -94,8 +94,11 @@ and Zig implementations. === Dependencies -* *VeriSimDB* (nextgen-databases): Source of the octad model. -VeriSimiser is a gateway to full VeriSimDB adoption. +* *VeriSimDB* (nextgen-databases): Source of the upstream +eight-modality Octad model. VeriSimiser's own Octad is the eight +*concerns* (ADR-0004), and its six Tier 2 overlay modalities are a +subset of upstream's modalities (ADR-0014). VeriSimiser is a gateway to +full VeriSimDB adoption. * *TypedQLiser*: Compile-time query type checking. Works alongside VeriSimiser for formally verified queries. * *SqueakWell*: Database recovery via cross-modal constraint diff --git a/docs/decisions/0004-octad-ontology.adoc b/docs/decisions/0004-octad-ontology.adoc index 185bbf3..bd3c456 100644 --- a/docs/decisions/0004-octad-ontology.adoc +++ b/docs/decisions/0004-octad-ontology.adoc @@ -121,6 +121,27 @@ argument loses to the implementation reality above. * ADR-0001 — adopts RSR template (predates this decision). * ADR-0003 — drift categories (built on the concerns octad). +* ADR-0014 — vocabulary around this decision (concern Octad vs + VeriSimDB's Octad vs the six-member Tier 2 overlay modality set). * V-L1-B1 — provenance threat model (cites concerns octad). * `src/abi/mod.rs::OctadDimension` — canonical enum. * `src/manifest/mod.rs::OctadConfig` — manifest mapping. + +## Amendment: vocabulary (2026-10-24) + +ADR-0014 (`0014-modality-vocabulary.adoc`) settles the vocabulary this +decision left implicit, without changing it: + +* Unqualified **Octad** in VeriSimiser means *this* (concern) octad. +* The upstream model is always written **VeriSimDB's Octad** — its + named eight-modality API/model, which VeriSimiser consumes but does + not own. +* The Tier 2 overlays named above are a **six-member overlay modality + set** (graph, vector, tensor, semantic, document, spatial); upstream's + Temporal and Provenance modalities are Tier 1 concerns here, not + overlays. +* A manifest's choice among those six is an **enabled-overlay + selection**, not a versioned "modality profile"; that term is + reserved for upstream verisimdb#299 and would need a schema change to + apply here. +* No schema, CLI, or manifest field is renamed by this amendment. diff --git a/docs/decisions/0014-modality-vocabulary.adoc b/docs/decisions/0014-modality-vocabulary.adoc new file mode 100644 index 0000000..419503d --- /dev/null +++ b/docs/decisions/0014-modality-vocabulary.adoc @@ -0,0 +1,210 @@ += Architecture Decision Record: 0014-modality-vocabulary + + + +# 14. Modality vocabulary: concern Octad, upstream Octad, enabled overlays + +Date: 2026-10-24 + +## Status + +Accepted — extends ADR-0004 (`0004-octad-ontology.adoc`); does not +supersede it. + +Addresses: https://github.com/hyperpolymath/verisimiser/issues/213 +(follow-on to V-L1-A2 / #20, the README rewrite). + +Related upstream terminology proposal: +https://github.com/hyperpolymath/verisimdb/issues/299. + +## Context + +ADR-0004 settled *which* eight-element model is canonical in +VeriSimiser. It did not settle the vocabulary used around that model, +and three distinct things are still called "octad" or "modalities" in +the tree: + +. **VeriSimiser's concern Octad** — Data · Metadata · Provenance · + Lineage · Constraints · AccessControl · Temporal · Simulation. + Canonical since ADR-0004. Materialised as + `src/abi/mod.rs::OctadDimension` (an enum with exactly eight + variants, enforced as a rule in + `.machine_readable/6a2/NEUROSYM.a2ml`), `src/manifest/mod.rs::OctadConfig`, + the `[octad]` manifest section, and `verisimiser octad`. + +. **VeriSimDB's (upstream) Octad** — Graph · Vector · Tensor · + Semantic · Document · Temporal · Provenance · Spatial. This is the + upstream project's *named eight-modality API and model*. VeriSimiser + consumes it as a source of capability; it does not own it, does not + re-export it, and has no `OctadDimension` variant for six of its + eight members. + +. **Tier 2 overlay modalities** — Graph · Vector · Tensor · Semantic · + Document · Spatial. Six members, not eight: upstream's Temporal and + Provenance members are Tier 1 *concerns* in VeriSimiser. Each is an + alternative storage shape an entity can additionally be projected + into (`src/manifest/mod.rs::Tier2Config`, currently a stub in + `src/tier2/mod.rs`). + +Issue #213 observed that this distinction is still easy to conflate, +and proposed **modality profile** as the number-agnostic term for a +selectable set of Tier 2 overlay modalities. The term must be adopted +only if it describes what the code actually does. + +## Decision + +### 14.1 "Octad" alone means the concern Octad + +In VeriSimiser documentation, unqualified **Octad** means the fixed +eight-**concern** model of ADR-0004: eight questions asked of an +entity, independent of storage. Its members are *concerns*, never +*modalities*. The arity is fixed at eight — `OctadDimension::all()` +returns `[OctadDimension; 8]`, and the enum may not grow a ninth +variant. + +### 14.2 Upstream is always qualified: "VeriSimDB's Octad" + +The upstream eight-**modality** API/model is written as **VeriSimDB's +Octad** (or "the upstream Octad"). It is a different ontology that +happens to also have eight members — the shared word is arity, not +meaning. Docs must not present it as VeriSimiser's type, and must not +imply that VeriSimiser implements all eight of its modalities natively. + +### 14.3 Tier 2 is a six-member overlay modality set, not an octad + +The Tier 2 **overlay modality set** is Graph, Vector, Tensor, Semantic, +Document, Spatial. Membership is fixed by `Tier2Config`'s six boolean +fields; adding a seventh is an ontology change (and would need its own +ADR, storage decision, and drift-category mapping), not a config edit. + +Upstream's Temporal and Provenance modalities appear in VeriSimiser as +Tier 1 concerns, not overlays. That asymmetry is deliberate: Tier 1 +records what happened to the real data; Tier 2 stores an additional +projection of it. + +### 14.4 Per-manifest selection is "enabled overlays" + +What a manifest chooses is an **enabled-overlay selection**: any subset +of the six-member set, cardinality 0–6, currently all defaulting to +`false`. The cardinality is *derived* (count of `true` flags); it is +never declared, stored, or validated anywhere. + +### 14.5 "Modality profile" is not adopted (yet) + +Upstream verisimdb#299 proposes **modality profile** for "the +versioned, implementation-specific selection of supported modalities", +with membership and cardinality explicit and not encoded in the generic +term. Measured against `Tier2Config` as it exists: + +[cols="2,2,1",options="header"] +|=== +| Criterion (from verisimdb#299) | VeriSimiser Tier 2 today | Match + +| Membership is explicit +| Six booleans in `Tier2Config`, fixed at compile time +| yes + +| Cardinality is explicit +| Derived from the flags; no declared count, no validation, no field +| no + +| Profile is versioned +| No version field; `Manifest` has no schema version either +| no + +| Profile describes what the *implementation supports* +| Supported set is a fixed six; the per-manifest flags express *user + enablement*, a different quantity +| no + +| Survives as a nameable artifact (schema/CLI surface) +| None; the flags exist, a "profile" does not +| no +|=== + +The term therefore describes neither of the two things it could be +attached to: not the fixed support set (which is not a profile because +it never varies or versions), and not the `[tier2]` flags (which are a +selection, not a declaration of support). Using it in prose while the +code has no such concept would recreate exactly the ambiguity ADR-0004 +removed. **VeriSimiser docs use "overlay modality set" for membership +and "enabled overlays" for the selection**, and reserve "modality +profile" for upstream VeriSimDB once #299 lands. + +If a versioned profile is ever wanted here — e.g. a +`[modality-profile]` table with `name`, `version`, and an explicit +member list — that is a manifest-schema change and needs its own +compatibility ADR (parser migration, `validate` coverage, `status` +output) before any doc adopts the word. + +### 14.6 No renames + +This ADR is documentation-only. The following surfaces are unchanged +and any rename is a separate compatibility decision: + +* Manifest keys: `[octad]`, `enable-provenance`, `enable-lineage`, + `enable-temporal`, `enable-access-control`, `enable-constraints`, + `enable-simulation`, `[sidecar]`, `[retention]`, and the legacy + `[verisimiser]`, `[tier1]`, `[tier2]` sections with their keys. +* Types: `OctadConfig`, `OctadStatus`, `OctadDimension`, `Tier2Config`. +* CLI: the `verisimiser octad` subcommand name and its options. +* Codegen output: `verisimdb_*` sidecar table names. + +## Consequences + +### Positive + +* A reader can tell which of the three eight-or-six-element models a + sentence means without reading further context. +* The docs stop implying that VeriSimiser implements VeriSimDB's full + modality Octad; Tier 2's six-member subset and its two Tier 1 + exemptions are stated once and cross-referenced. +* The `README`'s manifest example can be corrected against the parser + (see Follow-ups) without touching the schema. +* No code, schema, or CLI churn: comment and prose edits only. + +### Negative + +* "Overlay modality set" is longer than "modality profile" and reads + less well in prose; that is the cost of not naming a concept the code + does not have. +* Readers must consult ADR-0004 and this ADR together to get the full + picture. + +### Neutral + +* The legacy `[tier1]`/`[tier2]` sections stay. They are parsed for + backward compatibility but do not drive behaviour; `[octad]` is the + effective configuration. Docs now say so explicitly. +* VeriSimDB's Octad keeps changing upstream; classifying it as an + external model means VeriSimiser docs never have to track its edits. + +## Follow-ups + +* **Done in this change**: README gains a vocabulary table; the Tier 2 + section states the six-member set and the selected-subset semantics; + the manifest section shows the canonical `[project]`/`[database]`/ + `[octad]`/`[sidecar]`/`[retention]` schema with the legacy shape + documented separately; `docs/architecture/TOPOLOGY.adoc`, + `CONTRIBUTING-DEV.adoc`, `src/abi/mod.rs`, and `src/tier2/mod.rs` + use the vocabulary defined here. +* **Still open**: Tier 2 overlays have no implementation. `[tier2]` + flags are parsed and inert; README says so until overlay codegen and + query routing land (V-L1-F/G/H). +* **Still open**: revisit "modality profile" if verisimdb#299 fixes a + versioned profile shape and VeriSimiser adopts a matching schema + (separate ADR, per 14.5). + +## Cross-references + +* ADR-0004 (`0004-octad-ontology.adoc`) — concern Octad is canonical; + this ADR fixes the vocabulary around that decision. +* ADR-0003 (`0003-drift-categories.adoc`) — the eight drift categories + are Constraints symptoms observed across representations; they are + not the Octad's members. +* `src/abi/mod.rs::OctadDimension` — eight concern variants, no more. +* `src/manifest/mod.rs::OctadConfig` — concern toggles, fixed arity. +* `src/manifest/mod.rs::Tier2Config` — the six overlay modalities. +* `src/tier2/mod.rs` — Tier 2 module stubs. +* https://github.com/hyperpolymath/verisimdb/issues/299 — upstream + modality-profile terminology. diff --git a/docs/decisions/ADR-0001-octad-ontology.adoc b/docs/decisions/ADR-0001-octad-ontology.adoc index a35bd6d..ea67401 100644 --- a/docs/decisions/ADR-0001-octad-ontology.adoc +++ b/docs/decisions/ADR-0001-octad-ontology.adoc @@ -14,6 +14,12 @@ Closes as wontfix: https://github.com/hyperpolymath/verisimiser/issues/21[V-L1-A Unblocks: https://github.com/hyperpolymath/verisimiser/issues/20[V-L1-A2] (the README rewrite). +Vocabulary note (2026-10-24): `0014-modality-vocabulary.adoc` (ADR-0014) +fixes the terms around this decision — unqualified *Octad* means the +concern octad, the upstream model is written *VeriSimDB's Octad*, and the +Tier 2 overlays are a six-member *overlay modality set* with per-manifest +*enabled overlays* rather than a "modality profile". + == Context Two competing ontologies have lived in this repository under the same name diff --git a/src/abi/mod.rs b/src/abi/mod.rs index f9e8754..d2c6896 100644 --- a/src/abi/mod.rs +++ b/src/abi/mod.rs @@ -18,14 +18,19 @@ use serde::{Deserialize, Serialize}; use sha2::{Digest, Sha256}; // --------------------------------------------------------------------------- -// OctadDimension — the 8 modalities of VeriSimDB +// OctadDimension — the 8 concerns of VeriSimiser's Octad (ADR-0004/ADR-0014) // --------------------------------------------------------------------------- -/// The eight dimensions of the VeriSimDB octad model. +/// The eight concerns of VeriSimiser's Octad — fixed arity, never "modalities". /// -/// Every piece of data in a VeriSimDB-augmented database exists simultaneously -/// across up to 8 dimensions. The first two (Data, Metadata) are inherent in -/// the target database; the remaining six are added by the verisimiser sidecar. +/// Every entity in a VeriSimiser-augmented database is enriched along exactly +/// eight concerns. The first two (Data, Metadata) are inherent in the target +/// database; the remaining six are added by the verisimiser sidecar. +/// +/// This enum is *not* VeriSimDB's Octad (the upstream eight-modality model): +/// it deliberately has no Graph/Vector/Tensor/Semantic/Document/Spatial +/// variants. Those are Tier 2 overlay modalities, selected per manifest via +/// `Tier2Config` — see ADR-0014. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)] pub enum OctadDimension { /// The original data as stored in the target database. diff --git a/src/main.rs b/src/main.rs index 946eb73..5b9d2df 100644 --- a/src/main.rs +++ b/src/main.rs @@ -137,7 +137,7 @@ enum Commands { #[arg(long)] json: bool, }, - /// Show the octad modalities and which tiers they belong to. + /// Show the eight concerns of the Octad and which tiers they belong to. Octad, /// Print version, git-sha, and build-date. Version { @@ -692,9 +692,12 @@ fn short_hash(hash: &str) -> String { } } -/// Print the 8 octad dimensions with descriptions. +/// Print the eight concerns of VeriSimiser's Octad with descriptions. +/// +/// Deliberately not labelled "VeriSimDB Octad": that is the upstream +/// eight-modality model, a different vocabulary (ADR-0014). fn print_octad() { - println!("=== VeriSimDB Octad: Eight Dimensions ==="); + println!("=== VeriSimiser Octad: Eight Concerns ==="); println!(); for dim in abi::OctadDimension::all() { let inherent = if dim.is_inherent() { diff --git a/src/tier2/mod.rs b/src/tier2/mod.rs index 908c5f7..bca7100 100644 --- a/src/tier2/mod.rs +++ b/src/tier2/mod.rs @@ -3,7 +3,17 @@ // // Tier 2: Augmentation overlays. // These add additional storage alongside your database. -// Honest framing: this is "VeriSimDB modalities with your database as primary store." - -// Each modality overlay is a separate module, enabled independently. -// TODO: graph, vector, tensor, semantic, document, spatial +// Honest framing: these are (a subset of) VeriSimDB's modalities with your +// database as the primary store. +// +// The overlay modality set is fixed at six — graph, vector, tensor, semantic, +// document, spatial — and is NOT the Octad: VeriSimiser's Octad is the eight +// concerns in `crate::abi::OctadDimension`. Upstream's Temporal and Provenance +// modalities are Tier 1 concerns here, not overlays. +// +// `Tier2Config` flags select an enabled subset of those six (cardinality 0..=6). +// That selection is not a versioned "modality profile" — see ADR-0014. +// +// Each overlay is a separate module, enabled independently. +// TODO: graph, vector, tensor, semantic, document, spatial (stubs today; the +// `[tier2]` flags are parsed but no overlay codegen or query routing ships yet). From 1fee01826c51b90025d0478e68c1ef6bc1cd34c3 Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Sat, 24 Oct 2026 10:44:11 +0000 Subject: [PATCH 2/2] test(logging): assert the concern-Octad banner text The `octad` data-output assertion pinned "VeriSimDB Octad", which is the upstream modality model's name. The banner now reads "Verisimiser Octad: Eight Concerns" per ADR-0014; keep the stdout-data contract, update the substring. Refs #213. Co-authored-by: arena-agent <297053741+arena-agent@users.noreply.github.com> --- tests/logging_test.rs | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/tests/logging_test.rs b/tests/logging_test.rs index 963b1af..b8c1812 100644 --- a/tests/logging_test.rs +++ b/tests/logging_test.rs @@ -28,7 +28,8 @@ fn version_json_data_stays_pure_on_stdout() { } /// The `octad` table is data output and must land on stdout even with -/// JSON diagnostics enabled. +/// JSON diagnostics enabled. The banner names *VeriSimiser's* concern +/// Octad, not VeriSimDB's upstream modality Octad (ADR-0014). #[test] fn octad_table_is_data_on_stdout() { let out = bin() @@ -38,7 +39,7 @@ fn octad_table_is_data_on_stdout() { assert!(out.status.success()); let stdout = String::from_utf8(out.stdout).unwrap(); assert!( - stdout.contains("VeriSimDB Octad"), + stdout.contains("Verisimiser Octad"), "octad data on stdout, got: {stdout}" ); }