docs: bespoke verisimiser content — replace all template placeholders

Replace generic template placeholders with verisimiser-specific content:

- Idris2 ABI (Types.idr): OctadDimension (8 dims), DatabaseBackend (5 backends),
  DriftCategory (8 cats), AccessPolicy, Tier, SidecarIsolation proof
- Idris2 ABI (Layout.idr): OctadRecord (80B), ProvenanceEntry (88B),
  DriftMeasurement (88B), TemporalSnapshot (48B) with C-ABI proofs
- Idris2 ABI (Foreign.idr): lifecycle, database connect, octad overlay,
  provenance tracking, temporal versioning, drift detection, VQL-UT query FFI
- Zig FFI: full implementation stubs matching Idris2 ABI declarations
- ROADMAP.adoc: Phase 0-6 with PostgreSQL MVP, multi-backend, Tier 2 overlays,
  VQL-UT integration, production hardening, ecosystem milestones
- TOPOLOGY.md: component map, data flow diagram, invariants, memory layouts
- THREAT-MODEL.adoc: sidecar isolation, hash chain integrity, drift detection
- 0-AI-MANIFEST.a2ml: verisimiser-specific invariants and repo structure
- Machine-readable (AGENTIC, NEUROSYM, PLAYBOOK, STATE): bespoke content

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

.machine_readable/6a2/AGENTIC.a2ml

@@ -1,12 +1,13 @@
 # SPDX-License-Identifier: PMPL-1.0-or-later
 # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
 #
-# AGENTIC.a2ml — AI agent constraints and capabilities
+# AGENTIC.a2ml — AI agent constraints and capabilities for verisimiser
 # Defines what AI agents can and cannot do in this repository.
 
 [metadata]
 version = "0.1.0"
-last-updated = "{{CURRENT_DATE}}"
+last-updated = "2026-03-21"
+project = "verisimiser"
 
 [agent-permissions]
 can-edit-source = true
@@ -22,6 +23,18 @@ can-create-files = true
 # - Never use banned languages (TypeScript, Python, Go, etc.)
 # - Never place state files in repository root (must be in .machine_readable/)
 # - Never use AGPL license (use PMPL-1.0-or-later)
+# - Never generate code that writes to the target database from Tier 1
+# - Never break provenance hash chain ordering (append-only)
+# - Never bypass sidecar isolation guarantees
+
+[verisimiser-constraints]
+# Tier 1 sidecar isolation is a hard invariant:
+# - Drift detection: read-path observer ONLY
+# - Provenance: write to sidecar ONLY, never target DB
+# - Temporal: write to sidecar ONLY, never target DB
+tier1-never-writes-target-db = true
+provenance-chain-append-only = true
+hash-algorithm = "SHA-256"
 
 [maintenance-integrity]
 fail-closed = true

.machine_readable/6a2/NEUROSYM.a2ml

@@ -1,23 +1,34 @@
 # SPDX-License-Identifier: PMPL-1.0-or-later
 # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
 #
-# NEUROSYM.a2ml — Neurosymbolic integration metadata
+# NEUROSYM.a2ml — Neurosymbolic integration metadata for verisimiser
 # Configuration for Hypatia scanning and symbolic reasoning.
 
 [metadata]
 version = "0.1.0"
-last-updated = "{{CURRENT_DATE}}"
+last-updated = "2026-03-21"
+project = "verisimiser"
 
 [hypatia-config]
 scan-enabled = true
 scan-depth = "standard"  # quick | standard | deep
 report-format = "logtalk"
 
 [symbolic-rules]
-# Custom symbolic rules for this project
-# - { name = "no-unsafe-ffi", pattern = "believe_me|unsafeCoerce", severity = "critical" }
+# Custom symbolic rules for verisimiser:
+# - Provenance hash chains must be append-only
+# - Tier 1 operations must never write to the target database
+# - Drift detection must be read-path only (no mutation)
+# - OctadDimension enum must always have exactly 8 variants
+# - DriftCategory enum must always have exactly 8 variants
+rules = [
+  { name = "no-unsafe-ffi", pattern = "believe_me|unsafeCoerce|assert_total|Admitted|sorry", severity = "critical" },
+  { name = "tier1-sidecar-isolation", pattern = "target_db.*write|target_db.*insert|target_db.*update|target_db.*delete", severity = "critical" },
+  { name = "octad-completeness", pattern = "OctadDimension", check = "exactly-8-variants", severity = "high" },
+  { name = "drift-completeness", pattern = "DriftCategory", check = "exactly-8-variants", severity = "high" },
+]
 
 [neural-config]
 # Neural pattern detection settings
-# confidence-threshold = 0.85
+confidence-threshold = 0.85
 # model = "hypatia-v2"

.machine_readable/6a2/PLAYBOOK.a2ml

@@ -1,25 +1,29 @@
 # SPDX-License-Identifier: PMPL-1.0-or-later
 # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
 #
-# PLAYBOOK.a2ml — Operational playbook
+# PLAYBOOK.a2ml — Operational playbook for verisimiser
 # Runbooks, incident response, deployment procedures.
 
 [metadata]
 version = "0.1.0"
-last-updated = "{{CURRENT_DATE}}"
+last-updated = "2026-03-21"
+project = "verisimiser"
 
 [deployment]
-# method = "gitops"  # gitops | manual | ci-triggered
-# target = "container"  # container | binary | library | wasm
+method = "ci-triggered"
+target = "binary"  # Rust CLI binary + Zig shared library
+container = "optional"  # Chainguard-based Containerfile available
 
 [incident-response]
-# 1. Check .machine_readable/STATE.a2ml for current status
+# 1. Check .machine_readable/6a2/STATE.a2ml for current status
 # 2. Review recent commits and CI results
 # 3. Run `just validate` to check compliance
 # 4. Run `just security` to audit for vulnerabilities
+# 5. If provenance chain corruption suspected: run `verisimiser provenance --verify <entity>`
+# 6. If drift detection failing: check sidecar connectivity and drift index
 
 [release-process]
-# 1. Update version in STATE.a2ml, META.a2ml, Justfile
+# 1. Update version in STATE.a2ml, META.a2ml, Cargo.toml, Justfile
 # 2. Run `just release-preflight` (validate + quality + security + maint-hard-pass)
 # 3. Optional local permission hardening: `just perms-snapshot && just perms-lock`
 # 4. Tag and push
@@ -33,3 +37,7 @@ last-updated = "{{CURRENT_DATE}}"
 #   just maint-hard-pass
 # Permission audit:
 #   just perms-audit
+# Verify Zig FFI tests pass:
+#   cd src/interface/ffi && zig build test
+# Verify Rust tests pass:
+#   cargo test

.machine_readable/6a2/STATE.a2ml

@@ -5,7 +5,7 @@
 (state
   (metadata
     (version "0.1.0")
-    (last-updated "2026-03-20")
+    (last-updated "2026-03-21")
     (author "Jonathan D.A. Jewell"))
 
   (project-context
@@ -16,20 +16,34 @@
     (ecosystem "-iser family (https://github.com/hyperpolymath/iseriser)"))
 
   (current-position
-    (phase "initial-scaffold")
-    (completion-percentage 5)
-    (milestone "Architecture defined, CLI scaffolded, RSR template complete"))
+    (phase "scaffold-documented")
+    (completion-percentage 10)
+    (milestone "Architecture defined, CLI scaffolded, RSR template complete, ABI/FFI bespoke"))
 
   (route-to-mvp
-    (step 1 "Replace codegen stubs with target-language-specific generation")
-    (step 2 "Implement Idris2 ABI proofs for core invariants")
-    (step 3 "Build Zig FFI bridge")
-    (step 4 "Integration tests with real-world examples")
-    (step 5 "Documentation and examples"))
+    (step 1 "PostgreSQL Tier 1 MVP: logical replication interception")
+    (step 2 "Provenance sidecar (SQLite): SHA-256 hash-chain write-path observer")
+    (step 3 "Temporal versioning sidecar: point-in-time queries")
+    (step 4 "Cross-modal drift detection: read-path observer with 8-category index")
+    (step 5 "Idris2 ABI proofs: sidecar isolation, hash-chain integrity, version ordering")
+    (step 6 "Zig FFI bridge: compile and link against Idris2 ABI")
+    (step 7 "End-to-end integration test: PostgreSQL -> verisimiser -> VQL-UT query"))
+
+  (completed-actions
+    (action "Bespoke Idris2 ABI: Types.idr (OctadDimension, DatabaseBackend, DriftCategory, AccessPolicy, SidecarIsolation)")
+    (action "Bespoke Idris2 ABI: Layout.idr (OctadRecord 80B, ProvenanceEntry 88B, DriftMeasurement 88B, TemporalSnapshot 48B)")
+    (action "Bespoke Idris2 ABI: Foreign.idr (lifecycle, connect, overlay, provenance, temporal, drift, VQL-UT)")
+    (action "Bespoke Zig FFI: main.zig, build.zig, integration_test.zig")
+    (action "ROADMAP.adoc: Phase 0-6 with database-specific milestones")
+    (action "TOPOLOGY.md: component map, data flow, invariants, memory layouts")
+    (action "0-AI-MANIFEST.a2ml: verisimiser-specific invariants and structure")
+    (action "THREAT-MODEL.adoc: sidecar isolation, hash chain integrity, drift detection")
+    (action "Machine-readable files: AGENTIC, NEUROSYM, PLAYBOOK updated"))
 
   (blockers-and-issues
-    (none "Project is in scaffold phase — no blockers yet"))
+    (none "Project is in documented scaffold phase — no blockers yet"))
 
   (critical-next-actions
-    (action "Implement codegen for primary use case")
-    (action "Write first working example end-to-end")))
+    (action "Implement PostgreSQL logical replication interception")
+    (action "Build provenance sidecar with SQLite backend")
+    (action "First working end-to-end test with real PostgreSQL instance")))

0-AI-MANIFEST.a2ml

@@ -1,19 +1,27 @@
-# ⚠️ STOP - CRITICAL READING REQUIRED
-
-**THIS FILE MUST BE READ FIRST BY ALL AI AGENTS**
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# STOP - CRITICAL READING REQUIRED
+#
+# THIS FILE MUST BE READ FIRST BY ALL AI AGENTS
 
 ## WHAT IS THIS?
 
-This is the AI manifest for **[YOUR-REPO-NAME]**. It declares:
+This is the AI manifest for **verisimiser**. It declares:
 - Canonical file locations (where things MUST be, and nowhere else)
 - 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.
+
 ## CANONICAL LOCATIONS (UNIVERSAL RULE)
 
 ### Machine-Readable Metadata: `.machine_readable/` ONLY
 
-These 6 a2ml files MUST exist in `.machine_readable/` directory ONLY:
+These 6 a2ml files MUST exist in `.machine_readable/6a2/` directory ONLY:
 1. **STATE.a2ml** - Project state, progress, blockers
 2. **META.a2ml** - Architecture decisions, governance
 3. **ECOSYSTEM.a2ml** - Position in ecosystem, relationships
@@ -55,7 +63,7 @@ Policy enforcement contracts (k9, dust, lust, must, trust).
 ### AI Configuration & Guides: `.machine_readable/ai/` ONLY
 
 - `AI.a2ml` - Language-specific or LLM-specific patterns
-- `PLACEHOLDERS.md` - Bootstrap guide
+- `PLACEHOLDERS.adoc` - Bootstrap guide
 
 ### Community & Forge Metadata: `.github/` ONLY
 
@@ -80,42 +88,73 @@ Policy enforcement contracts (k9, dust, lust, must, trust).
 6. **Container images** - MUST use Chainguard base (`cgr.dev/chainguard/wolfi-base:latest` or `cgr.dev/chainguard/static:latest`)
 7. **Container runtime** - Podman, never Docker. Files are `Containerfile`, never `Dockerfile`
 8. **Container orchestration** - `selur-compose`, never `docker-compose`
+9. **Tier isolation** - Tier 1 capabilities NEVER write to the target database
+10. **Sidecar integrity** - Provenance hash chains are append-only and tamper-evident
+
+## VERISIMISER-SPECIFIC INVARIANTS
+
+- **Octad dimensions**: data, metadata, provenance, lineage, constraints, access-control, temporal, simulation
+- **Tier 1 (piggybacks)**: drift detection, provenance tracking, temporal versioning -- sidecar-only
+- **Tier 2 (overlays)**: graph, vector, tensor, semantic, document, spatial -- additional storage
+- **Supported backends**: PostgreSQL, SQLite, MongoDB, Redis (extensible)
+- **VQL-UT**: Type-safe query interface for octad queries
 
 ## REPOSITORY STRUCTURE
 
 This repo follows the **Dual-Track** architecture:
 
 ```
-[YOUR-REPO-NAME]/
+verisimiser/
 ├── 0-AI-MANIFEST.a2ml         # THIS FILE (start here)
 ├── README.adoc                 # High-level orientation (Rich Human)
 ├── ROADMAP.adoc                # Future direction
 ├── CONTRIBUTING.adoc           # Human contribution guide
-├── GOVERNANCE.adoc             # Decision-making model
 ├── Justfile                    # Task runner
 ├── Containerfile               # OCI build
-├── LICENSE                     # Primary license
+├── Cargo.toml                  # Rust build config
+├── LICENSE                     # Primary license (PMPL-1.0-or-later)
 ├── src/                        # Source code
+│   ├── main.rs                 # CLI entry point (clap subcommands)
+│   ├── lib.rs                  # Library root
+│   ├── manifest/               # TOML manifest parsing
+│   ├── tier1/                  # Tier 1 piggyback capabilities
+│   │   ├── drift.rs            # Cross-modal drift detection
+│   │   ├── provenance.rs       # SHA-256 hash-chain provenance
+│   │   └── temporal.rs         # Temporal versioning sidecar
+│   ├── tier2/                  # Tier 2 augmentation overlays
+│   ├── abi/                    # ABI module (Rust side)
+│   ├── intercept/              # Per-database interception strategies
 │   └── interface/              # Verified Interface Seams
 │       ├── abi/                # Idris2 ABI (The Spec)
+│       │   ├── Types.idr       # OctadDimension, DatabaseBackend, etc.
+│       │   ├── Layout.idr      # Octad record memory layout
+│       │   └── Foreign.idr     # Database connection, overlay, VQL-UT FFI
 │       ├── ffi/                # Zig FFI (The Bridge)
+│       │   ├── build.zig
+│       │   ├── src/main.zig
+│       │   └── test/integration_test.zig
 │       └── generated/          # C Headers (The Result)
 ├── container/                  # Stapeln container ecosystem
 ├── docs/                       # Technical depths
 │   ├── attribution/            # Citations, owners, maintainers (adoc)
-│   ├── architecture/           # Topology, diagrams
+│   ├── architecture/           # Topology, diagrams, threat model
 │   ├── theory/                 # Domain theory
-│   └── practice/               # Manuals
-├── docs/legal/                  # Legal exhibits and full texts
+│   └── legal/                  # Legal exhibits and full texts
 └── .machine_readable/          # ALL machine-readable metadata
+    └── 6a2/                    # STATE, META, ECOSYSTEM, AGENTIC, NEUROSYM, PLAYBOOK
 ```
 
 ## SESSION STARTUP CHECKLIST
 
-✅ Read THIS file (0-AI-MANIFEST.a2ml) first
-✅ Understand canonical location: `.machine_readable/`
-✅ State understanding of canonical locations
+1. Read THIS file (0-AI-MANIFEST.a2ml) first
+2. Understand canonical location: `.machine_readable/`
+3. State understanding of canonical locations
+4. Read `.machine_readable/6a2/STATE.a2ml` for current project state
 
 ## ATTESTATION PROOF
 
-**"I have read the AI manifest. All machine-readable content (state files, anchors, policies, bot directives, contractiles, AI guides) is located in `.machine_readable/` ONLY, and community metadata is in `.github/`. I will not create duplicate files in the root directory."**
+**"I have read the AI manifest for verisimiser. All machine-readable content
+(state files, anchors, policies, bot directives, contractiles, AI guides) is
+located in `.machine_readable/` ONLY, and community metadata is in `.github/`.
+I will not create duplicate files in the root directory. Tier 1 capabilities
+never write to the target database."**

ROADMAP.adoc

@@ -1,32 +1,66 @@
 // SPDX-License-Identifier: PMPL-1.0-or-later
-= verisimiser Roadmap
+// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+= VeriSimiser Roadmap
 :toc:
 :icons: font
 
 == Phase 0: Scaffold (COMPLETE)
-* [x] RSR template with full CI/CD
-* [x] CLI with subcommands
-* [x] Manifest parser
-* [x] Codegen stubs
-* [x] ABI module stubs
-* [x] README with architecture
+* [x] RSR template with full CI/CD (17 workflows)
+* [x] CLI with subcommands (init, start, drift, provenance, history, status, octad)
+* [x] Manifest parser (verisimiser.toml with tier1/tier2 config)
+* [x] Tier 1 data types (DriftReport, ProvenanceRecord, TemporalVersion)
+* [x] ABI module stubs (Idris2 + Zig FFI)
+* [x] README with two-tier architecture and honest framing
 
-== Phase 1: Core Implementation
-* [ ] Implement target-language-specific code generation
-* [ ] Write Idris2 ABI proofs for core invariants
-* [ ] Build Zig FFI bridge
-* [ ] First working end-to-end example
-* [ ] Integration tests
+== Phase 1: PostgreSQL Tier 1 MVP
+* [ ] PostgreSQL logical replication interception
+* [ ] Provenance sidecar (SQLite) — write-path observer
+* [ ] SHA-256 hash-chain integrity for provenance records
+* [ ] Temporal versioning sidecar — point-in-time queries
+* [ ] Cross-modal drift detection — read-path observer
+* [ ] Drift index with 8-category classification
+* [ ] Idris2 ABI proofs: sidecar isolation, hash-chain integrity, version ordering
+* [ ] Zig FFI bridge: database connection, overlay operations, VQL-UT queries
+* [ ] End-to-end test: PostgreSQL -> verisimiser overlay -> VQL-UT query
 
-== Phase 2: Polish
-* [ ] Error messages and diagnostics
+== Phase 2: Multi-Backend Support
+* [ ] SQLite interception via sqlite3_update_hook / WAL monitoring
+* [ ] MongoDB interception via change streams
+* [ ] Redis interception via keyspace notifications
+* [ ] MySQL interception via binlog CDC
+* [ ] Application-level middleware / ORM hooks
+* [ ] Backend-agnostic interception trait abstraction
+* [ ] Per-backend integration tests
+
+== Phase 3: Tier 2 Overlays
+* [ ] Graph overlay (RDF triples / property graph edges)
+* [ ] Vector overlay (HNSW embedding similarity search)
+* [ ] Tensor overlay (ndarray multi-dimensional numeric data)
+* [ ] Semantic overlay (CBOR type annotations + proof blobs)
+* [ ] Document overlay (Tantivy full-text search)
+* [ ] Spatial overlay (R-tree geospatial coordinates)
+* [ ] Independent enable/disable per overlay via manifest
+
+== Phase 4: VQL-UT Integration
+* [ ] VQL-UT type-safe query parsing
+* [ ] Cross-tier queries (Tier 1 + Tier 2 in single query)
+* [ ] TypedQLiser integration for compile-time query validation
+* [ ] Query planner for multi-sidecar operations
+* [ ] Performance benchmarks: overhead of augmentation layer
+
+== Phase 5: Production Hardening
+* [ ] Retention policies (auto-prune temporal history)
+* [ ] Sidecar compaction and garbage collection
+* [ ] Concurrent access safety (multi-writer provenance chains)
+* [ ] Backup and restore for sidecars
+* [ ] Monitoring and alerting integration
+* [ ] Error recovery and graceful degradation
 * [ ] Shell completions (bash, zsh, fish)
-* [ ] CI/CD for the generated artifacts
-* [ ] Performance benchmarks
-* [ ] Additional examples
 
-== Phase 3: Ecosystem
-* [ ] PanLL panel integration
-* [ ] BoJ-server cartridge
-* [ ] VeriSimDB backing store for results
+== Phase 6: Ecosystem
+* [ ] PanLL panel for drift monitoring dashboard
+* [ ] BoJ-server cartridge (MCP integration)
+* [ ] SqueakWell integration (database recovery via cross-modal constraint propagation)
+* [ ] Migration tooling: Tier 1 -> Tier 2 -> full VeriSimDB
 * [ ] Publish to crates.io
+* [ ] Chainguard container image