From e5dbbb91f785e82b4ce47aeb5e8f3bcf458d9a95 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 24 Aug 2026 08:52:04 +0100 Subject: [PATCH] refactor: migrate repository documentation from Markdown to AsciiDoc --- CHANGELOG.adoc | 159 ++++++++++++------ CHANGELOG.md | 80 --------- CONTRIBUTING.adoc | 71 ++++++++ CONTRIBUTING.md | 66 -------- SECURITY.adoc | 11 ++ SECURITY.md | 13 -- TEST-NEEDS.adoc | 36 ++++ TEST-NEEDS.md | 30 ---- TOPOLOGY.md => TOPOLOGY.adoc | 27 +-- .../{TOPOLOGY.md => TOPOLOGY.adoc} | 87 +++++----- llm-warmup-dev.adoc | 19 +++ llm-warmup-dev.md | 16 -- llm-warmup-user.adoc | 19 +++ llm-warmup-user.md | 16 -- 14 files changed, 328 insertions(+), 322 deletions(-) delete mode 100644 CHANGELOG.md create mode 100644 CONTRIBUTING.adoc delete mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.adoc delete mode 100644 SECURITY.md create mode 100644 TEST-NEEDS.adoc delete mode 100644 TEST-NEEDS.md rename TOPOLOGY.md => TOPOLOGY.adoc (73%) rename docs/architecture/{TOPOLOGY.md => TOPOLOGY.adoc} (55%) create mode 100644 llm-warmup-dev.adoc delete mode 100644 llm-warmup-dev.md create mode 100644 llm-warmup-user.adoc delete mode 100644 llm-warmup-user.md diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index 960e17f..4aef737 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -1,52 +1,107 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -= Changelog: verisimiser -:toc: - -All notable changes to verisimiser will be documented in this file. - -This format is based on https://keepachangelog.com/en/1.1.0/[Keep a Changelog], -and this project adheres to https://semver.org/spec/v2.0.0.html[Semantic Versioning]. - -== [0.2.0] - 2026-05-30 - -=== Added -* JSON-family sidecar storage backend (`[sidecar].storage = "json"`) with a - `[sidecar].format` key — `plain` | `ld` (JSON-LD) | `ndjson` — at full - runtime parity with the SQLite path: hash-chained provenance (incl. forks), - temporal versioning, drift, and gc (#146, V-L2-F3). -* `sidecar::StorageKind` — single source of truth resolving - `[sidecar].storage` (+ `format`) to a backend; `validate`/`generate`/ - `drift`/`gc` all defer to it. -* Cross-process write locking for the JSON sidecar (advisory `.lock` - with stale-steal) plus documented atomic-rename durability (#150, V-L2-F4). -* `provenance ` and `history [--at ]` CLI - subcommands now query the sidecar (sqlite + json) instead of stubbing - (#150, V-L2-F4). -* `examples/json-sidecar/` manifest demonstrating the NDJSON sidecar. - -=== Changed -* `verisimiser generate` emits a `sidecar_schema.{json,jsonld,ndjson}` - scaffold for the json family (SQL backends still emit DDL). - -== [0.1.0] - 2026-03-21 - -=== Phase 1 — RSR Compliance Sweep - -=== Added -* Phase 1 complete — scaffold, CLI, manifest parser, codegen stubs, ABI types -* RSR compliance sweep — STATE.a2ml, contractiles, Justfile updated -* Bespoke contractile constraints for Database augmentation with VeriSimDB octad model domain -* Project-specific Justfile recipes - -== [0.0.1] - 2026-03-20 - -=== Added -* Initial project scaffold from rsr-template-repo -* CLI with subcommands (init, validate, generate, build, run, info) -* Manifest parser (`verisimiser.toml`) -* Codegen engine (stubs — target-language-specific implementation pending) -* ABI module (Idris2 proof type definitions) -* Library API for programmatic use -* Full RSR template (17 CI workflows, governance docs, bot directives) -* README.adoc with architecture overview and value proposition +== Changelog + +All notable changes to `+verisimiser+` will be documented in this file. + +This file is generated from conventional commits by the +https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml[`+changelog-reusable.yml+`] +workflow (`+hyperpolymath/standards#206+`). Adopt the workflow in this +repo’s CI to keep this file in sync automatically — see +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+templates/cliff.toml+`] +for the canonical config. + +The format follows https://keepachangelog.com/en/1.1.0/[Keep a +Changelog]; this project aims to follow +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] + +==== Added + +* feat(sidecar): cross-process advisory write locking + atomic-rename +durability for the JSON sidecar, and wire the `+provenance+`/`+history+` +CLI subcommands against sqlite + json sidecars (V-L2-F4, ADR-0013, +closes #150) (#151) +* feat(sidecar): JSON-family sidecar storage backend — plain JSON / +JSON-LD / NDJSON with SQLite-parity octad runtime (provenance +incl. forks, temporal, drift, gc); new `+[sidecar].format+` key and a +single `+StorageKind::resolve+` backend resolver (V-L2-F3, ADR-0012, +closes #146) (#148) +* feat(codegen): split sidecar DDL by dialect; reject json sidecar (#45) +(#133) +* feat(codegen): split sidecar DDL by dialect; reject json sidecar (#45) +(#131) +* feat(logging): tracing diagnostics with –log-format/–log-level (#51) +(#124) +* feat(codegen): split sidecar DDL by dialect; reject json sidecar (#45) +(#129) +* feat(codegen): parse DDL with sqlparser, drop hand-rolled scanner +(#38) (#123) +* feat(provenance): fork-first-class chain model — ADR-0010 (#31; +supersedes #32) (#122) +* feat(provenance): fork-first-class chain model — ADR-0010 (#31; +supersedes #32) (#121) +* feat(provenance): fork-first-class chain model — ADR-0010 (#31; +supersedes #32) (#120) +* feat(codegen): split sidecar DDL by dialect; reject json sidecar (#45) +(#113) +* feat(provenance): fork-first-class chain model — ADR-0010 (#31; +supersedes #32) (#109) + +==== Fixed + +* fix(rhodibot): automated RSR compliance fixes (#135) +* fix: restore sqlparser dependency and security policy compliance +* fix(ci): bump a2ml/k9-validate-action pins to canonical (standards#85) +(#114) +* fix(ci): sync hypatia-scan.yml to canonical (kill cd-scanner build +drift) (#108) +* fix(ci): remove duplicate top-level concurrency block in rust-ci +* fix(ci): CodeQL language-aware detect (replace hardcoded rust) (#105) +* fix(#26): unify ProvenanceRecord/ProvenanceEntry (#103) +* fix(provenance): domain-separated, length-prefixed hash over all +fields (#88) +* fix(manifest): TOML parse errors now report filename:line:col (#84) +* fix(codegen): validate every identifier before interpolation into DDL +(#83) + +==== Changed + +* refactor(rename): VQL → VCL + verisimdb → verisim + +==== Documentation + +* docs(readme): rewrite around concerns octad (V-L1-A2) (#99) +* docs(adr): 0009-build-path — cargo + Containerfile canonical; rest +experimental (#97) +* docs(adr): 0008-contractile-ci — informational only until a real +consumer exists (#96) +* docs(adr): 0007-access-control-model — prefix-typed principals, +deny-wins, typed predicate (#95) +* docs(adr): 0006-simulation-semantics — isolated snapshots + manual +merge (#94) +* docs(adr): 0005-lineage-acyclicity — enforce DAG at write time (#93) +* docs(adr): 0004-octad-ontology — concerns octad is canonical (#92) +* docs(adr): 0003-drift-categories — input, distance, threshold per +category (#91) +* docs(theory): provenance threat model (foundational doc for Step 2) +(#90) +* docs: add CONTRIBUTING-DEV.adoc (#74) + +==== CI + +* ci(spark): adopt estate SPARK Theatre Gate (standards#135) (#117) +* ci: redistribute concurrency-cancel guard to read-only check workflows +(#116) +* ci(rust): rewrite rust-ci.yml so the workflow actually registers (#89) +* ci: bump actions/upload-artifact SHA to current v4 (#23) +* ci: bump actions/upload-artifact SHA to current v4 (#18) + +=== Pre-history + +Prior commits to this file’s introduction are recorded in git history +but not formally classified into Keep-a-Changelog sections. To backfill, +run `+git cliff -o CHANGELOG.md+` locally using the canonical +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+cliff.toml+`] +— this is one-shot mechanical work. + +''''' diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 58e4305..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,80 +0,0 @@ - - -# Changelog - -All notable changes to `verisimiser` will be documented in this file. - -This file is generated from conventional commits by the -[`changelog-reusable.yml`](https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml) -workflow (`hyperpolymath/standards#206`). Adopt the workflow in this repo's CI to keep this file in sync automatically — see -[`templates/cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) -for the canonical config. - -The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); -this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] - -### Added - -- feat(sidecar): cross-process advisory write locking + atomic-rename durability for the JSON sidecar, and wire the `provenance`/`history` CLI subcommands against sqlite + json sidecars (V-L2-F4, ADR-0013, closes #150) (#151) -- feat(sidecar): JSON-family sidecar storage backend — plain JSON / JSON-LD / NDJSON with SQLite-parity octad runtime (provenance incl. forks, temporal, drift, gc); new `[sidecar].format` key and a single `StorageKind::resolve` backend resolver (V-L2-F3, ADR-0012, closes #146) (#148) -- feat(codegen): split sidecar DDL by dialect; reject json sidecar (#45) (#133) -- feat(codegen): split sidecar DDL by dialect; reject json sidecar (#45) (#131) -- feat(logging): tracing diagnostics with --log-format/--log-level (#51) (#124) -- feat(codegen): split sidecar DDL by dialect; reject json sidecar (#45) (#129) -- feat(codegen): parse DDL with sqlparser, drop hand-rolled scanner (#38) (#123) -- feat(provenance): fork-first-class chain model — ADR-0010 (#31; supersedes #32) (#122) -- feat(provenance): fork-first-class chain model — ADR-0010 (#31; supersedes #32) (#121) -- feat(provenance): fork-first-class chain model — ADR-0010 (#31; supersedes #32) (#120) -- feat(codegen): split sidecar DDL by dialect; reject json sidecar (#45) (#113) -- feat(provenance): fork-first-class chain model — ADR-0010 (#31; supersedes #32) (#109) - -### Fixed - -- fix(rhodibot): automated RSR compliance fixes (#135) -- fix: restore sqlparser dependency and security policy compliance -- fix(ci): bump a2ml/k9-validate-action pins to canonical (standards#85) (#114) -- fix(ci): sync hypatia-scan.yml to canonical (kill cd-scanner build drift) (#108) -- fix(ci): remove duplicate top-level concurrency block in rust-ci -- fix(ci): CodeQL language-aware detect (replace hardcoded rust) (#105) -- fix(#26): unify ProvenanceRecord/ProvenanceEntry (#103) -- fix(provenance): domain-separated, length-prefixed hash over all fields (#88) -- fix(manifest): TOML parse errors now report filename:line:col (#84) -- fix(codegen): validate every identifier before interpolation into DDL (#83) - -### Changed - -- refactor(rename): VQL → VCL + verisimdb → verisim - -### Documentation - -- docs(readme): rewrite around concerns octad (V-L1-A2) (#99) -- docs(adr): 0009-build-path — cargo + Containerfile canonical; rest experimental (#97) -- docs(adr): 0008-contractile-ci — informational only until a real consumer exists (#96) -- docs(adr): 0007-access-control-model — prefix-typed principals, deny-wins, typed predicate (#95) -- docs(adr): 0006-simulation-semantics — isolated snapshots + manual merge (#94) -- docs(adr): 0005-lineage-acyclicity — enforce DAG at write time (#93) -- docs(adr): 0004-octad-ontology — concerns octad is canonical (#92) -- docs(adr): 0003-drift-categories — input, distance, threshold per category (#91) -- docs(theory): provenance threat model (foundational doc for Step 2) (#90) -- docs: add CONTRIBUTING-DEV.adoc (#74) - -### CI - -- ci(spark): adopt estate SPARK Theatre Gate (standards#135) (#117) -- ci: redistribute concurrency-cancel guard to read-only check workflows (#116) -- ci(rust): rewrite rust-ci.yml so the workflow actually registers (#89) -- ci: bump actions/upload-artifact SHA to current v4 (#23) -- ci: bump actions/upload-artifact SHA to current v4 (#18) - -## Pre-history - -Prior commits to this file's introduction are recorded in git history but not formally classified into Keep-a-Changelog sections. To backfill, run `git cliff -o CHANGELOG.md` locally using the canonical [`cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) — this is one-shot mechanical work. - ---- - - diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..858f44f --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,71 @@ +== Contributing + +Thank you for your interest in contributing! We follow a "`Dual-Track`" +architecture where human-readable documentation lives in the root and +machine-readable policies live in `+.machine_readable/+`. + +=== How to Contribute + +We welcome contributions in many forms: + +* *Code:* Improving the core stack or extensions +* *Documentation:* Enhancing docs or AI manifests +* *Testing:* Adding property-based tests or formal proofs +* *Bug reports:* Filing clear, reproducible issues + +=== Getting Started + +[arabic] +. *Read the AI Manifest:* Start with `+0-AI-MANIFEST.a2ml+` (if present) +to understand the repository structure. +. *Environment:* Use `+nix develop+` or `+direnv allow+` to set up your +tools. +. *Task Runner:* Use `+just+` to see available commands +(`+just --list+`). + +=== Development Workflow + +==== Branch Naming + +.... +docs/short-description # Documentation +test/what-added # Test additions +feat/short-description # New features +fix/issue-number-description # Bug fixes +refactor/what-changed # Code improvements +security/what-fixed # Security fixes +.... + +==== Commit Messages + +We follow https://www.conventionalcommits.org/[Conventional Commits]: + +.... +(): + +[optional body] + +[optional footer] +.... + +Types: `+feat+`, `+fix+`, `+docs+`, `+test+`, `+refactor+`, `+ci+`, +`+chore+`, `+security+` + +=== Reporting Bugs + +Before reporting: 1. Search existing issues 2. Check if it’s already +fixed in `+main+` + +When reporting, include: - Clear, descriptive title - Environment +details (OS, versions, toolchain) - Steps to reproduce - Expected vs +actual behaviour + +=== Code of Conduct + +All contributors are expected to adhere to our +link:CODE_OF_CONDUCT.md[Code of Conduct]. + +=== License + +By contributing, you agree that your contributions will be licensed +under the same license as the project (see LICENSE). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 80ecdac..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,66 +0,0 @@ - -# Contributing - -Thank you for your interest in contributing! We follow a "Dual-Track" architecture where human-readable documentation lives in the root and machine-readable policies live in `.machine_readable/`. - -## How to Contribute - -We welcome contributions in many forms: - -- **Code:** Improving the core stack or extensions -- **Documentation:** Enhancing docs or AI manifests -- **Testing:** Adding property-based tests or formal proofs -- **Bug reports:** Filing clear, reproducible issues - -## Getting Started - -1. **Read the AI Manifest:** Start with `0-AI-MANIFEST.a2ml` (if present) to understand the repository structure. -2. **Environment:** Use `nix develop` or `direnv allow` to set up your tools. -3. **Task Runner:** Use `just` to see available commands (`just --list`). - -## Development Workflow - -### Branch Naming - -``` -docs/short-description # Documentation -test/what-added # Test additions -feat/short-description # New features -fix/issue-number-description # Bug fixes -refactor/what-changed # Code improvements -security/what-fixed # Security fixes -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): - -``` -(): - -[optional body] - -[optional footer] -``` - -Types: `feat`, `fix`, `docs`, `test`, `refactor`, `ci`, `chore`, `security` - -## Reporting Bugs - -Before reporting: -1. Search existing issues -2. Check if it's already fixed in `main` - -When reporting, include: -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour - -## Code of Conduct - -All contributors are expected to adhere to our [Code of Conduct](CODE_OF_CONDUCT.md). - -## License - -By contributing, you agree that your contributions will be licensed under the same license as the project (see [LICENSE](LICENSE)). diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..7fa19c7 --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,11 @@ +== Security Policy + +=== Reporting a Vulnerability + +*Email:* j.d.a.jewell@open.ac.uk + +*Response timeline:* - Acknowledgement within 48 hours - Initial +assessment within 7 days - Fix or mitigation within 90 days + +*Safe harbour:* We will not pursue legal action against security +researchers who follow responsible disclosure. diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 5aecb31..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,13 +0,0 @@ - -# Security Policy - -## Reporting a Vulnerability - -**Email:** j.d.a.jewell@open.ac.uk - -**Response timeline:** -- Acknowledgement within 48 hours -- Initial assessment within 7 days -- Fix or mitigation within 90 days - -**Safe harbour:** We will not pursue legal action against security researchers who follow responsible disclosure. diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..6f48e63 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,36 @@ +== TEST-NEEDS.md — verisimiser + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Current Test State + +[width="100%",cols="42%,29%,29%",options="header",] +|=== +|Category |Count |Notes +|Integration tests (Rust) |2 |Dual compiled binaries (debug + release) + +|Verification tests |Unit-level |`+verification/tests/+` directory +present + +|FFI tests |Present |`+src/interface/ffi/test/+` +|=== + +=== What’s Covered + +* [x] Dual integration test builds +* [x] FFI verification layer +* [x] Cargo test harness + +=== Still Missing (for CRG B+) + +* [ ] Property-based verification testing +* [ ] Fuzzing for edge cases +* [ ] Benchmarking suite +* [ ] Multi-target platform tests + +=== Run Tests + +[source,bash] +---- +cd /var/mnt/eclipse/repos/verisimiser && cargo test +---- diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index 00a8976..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,30 +0,0 @@ -# TEST-NEEDS.md — verisimiser - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Current Test State - -| Category | Count | Notes | -|----------|-------|-------| -| Integration tests (Rust) | 2 | Dual compiled binaries (debug + release) | -| Verification tests | Unit-level | `verification/tests/` directory present | -| FFI tests | Present | `src/interface/ffi/test/` | - -## What's Covered - -- [x] Dual integration test builds -- [x] FFI verification layer -- [x] Cargo test harness - -## Still Missing (for CRG B+) - -- [ ] Property-based verification testing -- [ ] Fuzzing for edge cases -- [ ] Benchmarking suite -- [ ] Multi-target platform tests - -## Run Tests - -```bash -cd /var/mnt/eclipse/repos/verisimiser && cargo test -``` diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 73% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index fc89f77..9930a3a 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,14 +1,19 @@ - - -# TOPOLOGY.md — verisimiser +== TOPOLOGY.md — verisimiser -## Purpose +=== Purpose -verisimiser augments any existing database with the full VeriSimDB octad of capabilities (the eight cross-modal dimensions). 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. verisimiser is priority #3 in the -iser family and is the primary path for adding VeriSimDB capabilities to legacy PostgreSQL, SQLite, or MongoDB deployments. +verisimiser augments any existing database with the full VeriSimDB octad +of capabilities (the eight cross-modal dimensions). 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. +verisimiser is priority #3 in the -iser family and is the primary path +for adding VeriSimDB capabilities to legacy PostgreSQL, SQLite, or +MongoDB deployments. -## Module Map +=== Module Map -``` +.... verisimiser/ ├── src/ │ ├── main.rs # CLI entry point (clap): init, generate, start, drift, provenance, history, status, octad @@ -23,11 +28,11 @@ verisimiser/ ├── verification/ # Proof harnesses ├── container/ # Stapeln container ecosystem └── .machine_readable/ # A2ML metadata -``` +.... -## Data Flow +=== Data Flow -``` +.... verisimiser.toml manifest │ ┌────▼────┐ @@ -47,4 +52,4 @@ verisimiser.toml manifest ┌────▼────┐ │ Daemon │ start augmentation daemon alongside target database └─────────┘ -``` +.... diff --git a/docs/architecture/TOPOLOGY.md b/docs/architecture/TOPOLOGY.adoc similarity index 55% rename from docs/architecture/TOPOLOGY.md rename to docs/architecture/TOPOLOGY.adoc index 2b471fd..d78b8f6 100644 --- a/docs/architecture/TOPOLOGY.md +++ b/docs/architecture/TOPOLOGY.adoc @@ -1,11 +1,8 @@ - - +== VeriSimiser Topology -# VeriSimiser Topology +=== Component Map -## Component Map - -``` +.... verisimiser/ ├── CLI Layer (Rust) │ ├── src/main.rs — clap subcommands: init, start, drift, provenance, history, status, octad @@ -30,11 +27,11 @@ verisimiser/ │ └── Generated Headers └── src/interface/generated/abi/ — Auto-generated C headers from Idris2 ABI -``` +.... -## Data Flow +=== Data Flow -``` +.... Application → writes → Target Database (PostgreSQL / SQLite / MongoDB / Redis / MySQL) │ VeriSimiser intercepts (per-backend strategy) @@ -54,40 +51,54 @@ Application → writes → Target Database (PostgreSQL / SQLite / MongoDB / Redi │ │ │ Graph Vector Tensor Semantic Document Spatial (Tier 2 overlays — additional storage alongside target DB) -``` +.... -## Key Invariants +=== Key Invariants -1. **Tier 1 sidecar isolation**: Tier 1 operations NEVER write to the target database. -2. **Provenance append-only**: Hash chain records are immutable once written. -3. **Octad completeness**: All 8 dimensions accounted for (data, metadata, provenance, lineage, constraints, access-control, temporal, simulation). -4. **Drift completeness**: All 8 drift categories covered (structural, semantic, temporal, statistical, referential, provenance, spatial, embedding). -5. **C-ABI compatibility**: All FFI types match between Idris2 declarations and Zig implementations. +[arabic] +. *Tier 1 sidecar isolation*: Tier 1 operations NEVER write to the +target database. +. *Provenance append-only*: Hash chain records are immutable once +written. +. *Octad completeness*: All 8 dimensions accounted for (data, metadata, +provenance, lineage, constraints, access-control, temporal, simulation). +. *Drift completeness*: All 8 drift categories covered (structural, +semantic, temporal, statistical, referential, provenance, spatial, +embedding). +. *C-ABI compatibility*: All FFI types match between Idris2 declarations +and Zig implementations. -## Interception Strategies +=== Interception Strategies -| Backend | Method | Type | -|------------|------------------------------------------|-------------| -| PostgreSQL | Logical replication / pg_notify / triggers | CDC | -| SQLite | sqlite3_update_hook / WAL monitoring | Hook | -| MongoDB | Change streams | Stream | -| Redis | Keyspace notifications | PubSub | -| MySQL | Binlog CDC / triggers | CDC | -| App-level | Middleware / ORM hooks | Interceptor | +[width="100%",cols="19%,62%,19%",options="header",] +|=== +|Backend |Method |Type +|PostgreSQL |Logical replication / pg_notify / triggers |CDC +|SQLite |sqlite3_update_hook / WAL monitoring |Hook +|MongoDB |Change streams |Stream +|Redis |Keyspace notifications |PubSub +|MySQL |Binlog CDC / triggers |CDC +|App-level |Middleware / ORM hooks |Interceptor +|=== -## Memory Layouts (from Layout.idr) +=== Memory Layouts (from Layout.idr) -| Struct | Size (bytes) | Alignment | Purpose | -|---------------------|-------------|-----------|--------------------------------------| -| OctadRecord | 80 | 8 | Per-entity octad dimension pointers | -| ProvenanceEntry | 88 | 8 | SHA-256 hash chain link | -| DriftMeasurement | 88 | 8 | Per-entity drift scores (8 categories) | -| TemporalSnapshot | 48 | 8 | Versioned entity state | +[width="100%",cols="27%,15%,13%,45%",options="header",] +|=== +|Struct |Size (bytes) |Alignment |Purpose +|OctadRecord |80 |8 |Per-entity octad dimension pointers +|ProvenanceEntry |88 |8 |SHA-256 hash chain link +|DriftMeasurement |88 |8 |Per-entity drift scores (8 categories) +|TemporalSnapshot |48 |8 |Versioned entity state +|=== -## Dependencies +=== Dependencies -- **VeriSimDB** (nextgen-databases): Source of the octad model. 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 propagation. Uses VeriSimiser's drift detection. -- **proven**: Shared Idris2 verified library for formal proofs. -- **TypeLL**: Type theory engine used by TypedQLiser. +* *VeriSimDB* (nextgen-databases): Source of the octad model. +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 +propagation. Uses VeriSimiser’s drift detection. +* *proven*: Shared Idris2 verified library for formal proofs. +* *TypeLL*: Type theory engine used by TypedQLiser. diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..8c80722 --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — verisimiser (Developer) + +=== What is verisimiser? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-dev.md b/llm-warmup-dev.md deleted file mode 100644 index 13f2f33..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — verisimiser (Developer) - -## What is verisimiser? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.adoc b/llm-warmup-user.adoc new file mode 100644 index 0000000..55ead6c --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — verisimiser (User) + +=== What is verisimiser? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.md b/llm-warmup-user.md deleted file mode 100644 index e5f2f7f..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — verisimiser (User) - -## What is verisimiser? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture