From 39de5c3cc5207ea3b3a3c3c02999e80e2800ea09 Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Sun, 25 Oct 2026 20:42:01 +0000 Subject: [PATCH 1/4] docs(quickstart): make install/test instructions match the repo The three quickstarts and docs/QUICKSTART.adoc were unfilled RSR templates: literal {{LANG_STACK}}/{{BUILD_CMD}} placeholders, `just setup`, `just e2e`, `just check-error-codes`, `just panic-scan`, `just llm-context`, `just stapeln-*` and `just uninstall` recipes that this repo does not define, and Nix/Guix/container paths described as if they worked. Rewritten against the repository as it is: * rustup --profile minimal + `rustup component add clippy rustfmt`; MSRV 1.85, edition 2024, bundled SQLite needs a C compiler * real install paths: `cargo install --path .` (-> ~/.cargo/bin), `cargo build --release` (-> target/release), `cargo install --root` for a prefix (`just install` takes no arguments) * test story: `just test`, CI parity mirror `cargo test --all-targets --no-fail-fast`, and the actual suite layout (5 integration files / 23 tests / 146 unit #[test]s) * explicit "not ready" list: Containerfile is a template stub, no flake.nix, guix.scm is a dev shell pinned below Cargo.toml, .devcontainer has unreplaced tokens, Tier 2 is stubs, postgres runtime reads refuse, and no release/tag exists yet despite the workflow Guard so this cannot silently drift again: * scripts/check-doc-recipes.sh + `just doc-recipes` fail when an .adoc code block references a recipe the Justfile (or an imported *.just) does not define; template artifacts are reported and skipped * CONTRIBUTING-DEV gains "Commands in docs must exist" with the non-recipe -> real-alternative table (fix docs, don't invent recipes) Also: README build section corrected (Containerfile/release claims), TEST-NEEDS de-hardcoded from /var/mnt/eclipse/... and refreshed, llm-warmup-{dev,user} and the setup.sh header no longer point at `just setup`. Verified: all touched .adoc render with Asciidoctor with zero warnings; check-doc-recipes passes and fails correctly on a probe file. Refs #213. Co-authored-by: arena-agent <297053741+arena-agent@users.noreply.github.com> --- CHANGELOG.adoc | 17 +++ CONTRIBUTING-DEV.adoc | 36 +++++ Justfile | 5 + QUICKSTART-DEV.adoc | 254 +++++++++++++++++++++++++++++------ QUICKSTART-MAINTAINER.adoc | 190 +++++++++++++++++--------- QUICKSTART-USER.adoc | 163 +++++++++++++--------- README.adoc | 38 ++++-- TEST-NEEDS.adoc | 53 +++++--- docs/QUICKSTART.adoc | 67 +++++++-- llm-warmup-dev.adoc | 35 +++-- llm-warmup-user.adoc | 37 +++-- scripts/check-doc-recipes.sh | 108 +++++++++++++++ setup.sh | 3 +- 13 files changed, 774 insertions(+), 232 deletions(-) create mode 100755 scripts/check-doc-recipes.sh diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index b7f167f..669199b 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -70,6 +70,23 @@ fields (#88) ==== Documentation +* docs(quickstart): rewrite QUICKSTART-DEV/USER/MAINTAINER and +docs/QUICKSTART against the repository as it actually is — real rustup + +cargo/`just` workflow (MSRV 1.85, bundled SQLite needs a C compiler), real +recipes, real artifact paths (`cargo install --path .`, +`target/release/verisimiser`), and an honest "not ready" list for the +Containerfile, devcontainer, Nix and Tier 2. Drops every RSR-template +placeholder and the recipes that never existed (`just setup`, +`just e2e`, `just check-error-codes`, `just panic-scan`, `just llm-context`, +`just build-release`, `just stapeln-*`, `just uninstall`) +* feat(just): `just doc-recipes` + `scripts/check-doc-recipes.sh` fail when a +documented `just` recipe is undefined, so quickstarts cannot drift from the +Justfile again +* docs: stop claiming unreleased/absent artifacts — no published release +(no tags yet), Containerfile is a template stub rather than a working OCI +build, and there is no `flake.nix`; TEST-NEEDS de-hardcoded from +`/var/mnt/eclipse/...` and refreshed to the current 146 unit / 23 integration +tests * 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 diff --git a/CONTRIBUTING-DEV.adoc b/CONTRIBUTING-DEV.adoc index b5a9010..97f17cd 100644 --- a/CONTRIBUTING-DEV.adoc +++ b/CONTRIBUTING-DEV.adoc @@ -109,6 +109,42 @@ backends. a *new* overlay changes the set's membership and so needs an ADR, not just a README edit (ADR-0014 §14.3). +== Commands in docs must exist + +Documentation is treated as an interface: if a guide tells someone to run a +command, that command has to work. The RSR templates this repo started from +referenced recipes from other projects, so several guides shipped instructions +that failed with `Justfile does not contain recipe`. + +* **Only reference recipes that the Justfile (or an imported `*.just`) defines.** + `just --list` is authoritative. +* **`just doc-recipes`** runs `scripts/check-doc-recipes.sh`, which fails if any + `.adoc` code block mentions an undefined recipe. Run it after editing docs. +* **Do not add a recipe just to satisfy a doc.** ADR-0002 removed aspirational + recipes that wrapped things which did not exist; the fix direction is to + correct the docs, not to invent the recipe. + +Known non-recipes, with the real alternative: + +[cols="2,2",options="header"] +|=== +| Mentioned in old docs | Actually + +| `just setup`, `just setup-dev` | `cargo fetch` / `just deps` (`./setup.sh` falls back to `just doctor`) +| `just check-error-codes` | No error-code catalogue exists in this repo +| `just e2e` | `just test` (`tests/` holds the integration + e2e suite) +| `just panic-scan` | `just assail` +| `just llm-context` | read `0-AI-MANIFEST.a2ml` and `.claude/CLAUDE.md` +| `just build-release` | `just build` +| `just install --prefix=…` | `cargo install --path . --root ` +| `just stapeln-*`, `just uninstall`, `just init` | Not present +|=== + +Template artifacts that are sync-managed from `hyperpolymath/standards` +(`docs/RSR_OUTLINE.adoc`, `container/*`, `.machine_readable/**`) still describe +the template's own recipes; `just doc-recipes` reports and skips the one it +scans rather than rewriting synced content. + == Style notes * **Vocabulary** (ADR-0014): unqualified `Octad` means VeriSimiser's diff --git a/Justfile b/Justfile index 4b0591f..4e5a00c 100644 --- a/Justfile +++ b/Justfile @@ -58,6 +58,11 @@ assail: # `start`, `drift`, `provenance`, `history`, `status`, `octad`). # Re-add wrappers here when their underlying subcommands ship. +# Verify that every `just ` in the docs is actually defined here. +# Guards against template leftovers (just setup / e2e / check-error-codes). +doc-recipes: + ./scripts/check-doc-recipes.sh + # Run contractile checks (informational only — not required by CI per ADR-0008) contractile-check: @echo "Running contractile validation..." diff --git a/QUICKSTART-DEV.adoc b/QUICKSTART-DEV.adoc index bbf366e..e429efc 100644 --- a/QUICKSTART-DEV.adoc +++ b/QUICKSTART-DEV.adoc @@ -1,111 +1,279 @@ // SPDX-License-Identifier: CC-BY-SA-4.0 -// Template: QUICKSTART-DEV.adoc — clone → build → test → PR -// Replace verisimiser, {{BUILD_CMD}}, {{TEST_CMD}}, {{LANG_STACK}} with actuals +// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) = verisimiser — Quick Start for Developers :toc: :toclevels: 2 +Clone → build → test → PR, using only commands that exist in this repo. + +TIP: Every command in this file is checked against the Justfile by +`just doc-recipes` (see <>). + == Tech Stack -{{LANG_STACK}} +* **Rust**, edition 2024, MSRV **1.85** (`rust-version` in `Cargo.toml`). +* **SQLite via `rusqlite` with the `bundled` feature** — SQLite is compiled + from source at build time, so a C compiler is required. +* **No system library dependencies** for the CLI itself (no OpenSSL, no + libsqlite3). +* **Optional:** Zig 0.14.0 for the FFI seam (`scripts/install-zig.sh`), + Idris2 for the ABI proof job in CI. Neither is needed to build or test + the CLI. == Set Up Development Environment -=== Option A: Guix (preferred) +=== 1. Rust toolchain + +[source,bash] +---- +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal +. "$HOME/.cargo/env" +---- + +`--profile minimal` installs `rustc` and `cargo` only. The quality recipes +need clippy and rustfmt, so add them: [source,bash] ---- -guix shell +rustup component add clippy rustfmt ---- -=== Option B: Nix (fallback) +To reproduce the MSRV leg of CI (`.github/workflows/rust-ci.yml` tests both +`1.85` and `stable`): [source,bash] ---- -nix develop +rustup toolchain install 1.85 ---- -=== Option C: Manual +=== 2. `just` (optional, but the recipes are the documented interface) + +[source,bash] +---- +cargo install just --locked +---- + +`.tool-versions` pins `just` at 1.36.0. Everything below also works as plain +`cargo` commands if you skip this step. + +=== 3. System packages + +* A C compiler (`cc`, `gcc`, or `clang`) — required by `rusqlite`'s bundled + SQLite. On Debian/Ubuntu: `sudo apt install build-essential`. +* `git` — used by `build.rs` to stamp the binary with the current SHA. + +=== 4. Clone and warm the cache [source,bash] ---- git clone https://github.com/hyperpolymath/verisimiser.git cd verisimiser -just setup-dev +cargo fetch # or: just deps (also attempts the Zig toolchain) ---- +`just deps` additionally runs `scripts/install-zig.sh`, which fetches Zig +from `ziglang.org` and is fail-soft: if Zig cannot be downloaded (proxies, +restricted egress), the recipe still succeeds and you can ignore it unless +you are working on `src/interface/ffi/`. + == Build [source,bash] ---- -{{BUILD_CMD}} +just build # cargo build --release +cargo build # faster debug loop ---- +Release binary: `target/release/verisimiser`. + +Per `docs/decisions/0009-build-path.adoc`, `cargo` is the canonical +development path. The Containerfile is the intended ops path but is **not +implemented yet** — it is still an RSR template stub with `TODO` build +steps, so `podman build` does not produce a working image. See +<>. + == Test [source,bash] ---- -{{TEST_CMD}} +just test # cargo test ---- +For CI parity (CI runs the wider set): + +[source,bash] +---- +cargo test --all-targets --no-fail-fast +---- + +Suite layout (counts as of this commit): + +[cols="2,1,3",options="header"] +|=== +| File | Tests | Covers + +| `tests/integration_test.rs` | 9 | Schema parse → overlay DDL, interceptors, manifest shapes, `OctadDimension` +| `tests/sidecar_cli_test.rs` | 2 | `provenance` / `history` CLI over the JSON sidecar +| `tests/provenance_fork_test.rs` | 4 | First-class provenance forks (ADR-0010) +| `tests/logging_test.rs` | 6 | stdout data contract vs stderr diagnostics +| `tests/sqlite_intercept_e2e.rs` | 2 | End-to-end SQLite Tier 1 interception +| `src/**` unit tests | 146 | Per-module invariants +|=== + +Several tests execute the built binary through `CARGO_BIN_EXE_verisimiser`, +which `cargo test` builds automatically — there is no separate "e2e" recipe +or command to run. + +== Full quality gate + +[source,bash] +---- +just quality # fmt-check + lint + test +---- + +CI is stricter than `just lint`: it runs +`cargo clippy --all-targets -- -D warnings`, while the recipe runs +`cargo clippy -- -D warnings`. Run the CI form before pushing: + +[source,bash] +---- +cargo fmt --all -- --check +cargo clippy --all-targets -- -D warnings +cargo test --all-targets --no-fail-fast +---- + +[[only-real-recipes]] +== Only real recipes + +The Justfile is the contract for commands, and ADR-0002 removed recipes that +wrapped things that did not exist. Some older docs and RSR template files +still mention recipe names that are **not defined here** — running them +fails with `Justfile does not contain recipe`: + +[cols="2,2",options="header"] +|=== +| Not a recipe | Use instead + +| `just setup`, `just setup-dev` | `cargo fetch`, or `just deps`; `./setup.sh` falls back to `just doctor` +| `just check-error-codes` | There is no error-code catalogue in this repo +| `just e2e` | `just test` (integration tests in `tests/`) +| `just panic-scan` | `just assail` (wraps `panic-attack assail`) +| `just llm-context` | Read `0-AI-MANIFEST.a2ml` and `.claude/CLAUDE.md` +| `just build-release` | `just build` +| `just stapeln-*`, `just uninstall` | Not present +|=== + +`just doc-recipes` fails if any `.adoc` code block references a recipe that +the Justfile does not define. + == Project Structure [source] ---- verisimiser/ -├── src/ # Source code -├── src/abi/ # Idris2 ABI definitions (if applicable) -├── ffi/zig/ # Zig FFI bridge (if applicable) -├── tests/ # Test suite -├── docs/ # Documentation -├── .machine_readable/ # Checkpoint files (STATE, META, ECOSYSTEM) -├── Justfile # Task runner recipes -├── guix.scm # Guix environment -├── flake.nix # Nix environment (fallback) -└── 0-AI-MANIFEST.a2ml # AI agent entry point +├── src/ +│ ├── main.rs # clap CLI: init, generate, start, drift, provenance, +│ │ # history, status, octad, validate, doctor, gc, version +│ ├── lib.rs # library root +│ ├── abi/ # Rust-side ABI types (OctadDimension, ProvenanceEntry, …) +│ ├── manifest/ # verisimiser.toml parsing + validation + status +│ ├── codegen/ # schema parser, sidecar DDL, query interceptors +│ ├── tier1/ # provenance, temporal, drift (concern Octad) +│ ├── tier2/ # overlay modality stubs (not implemented) +│ ├── sidecar/ # sqlite / postgres / json-family stores + locking +│ ├── intercept/ # per-backend interception (sqlite today) +│ └── interface/ # verified interface seam +│ ├── abi/Verisimiser/ABI/*.idr # Idris2 models + proofs +│ ├── ffi/ # Zig FFI bridge (build.zig, src/main.zig) +│ └── generated/ # generated C headers +├── tests/ # integration + CLI tests +├── examples/ # blog-db, json-sidecar, golden (frozen codegen sample) +├── docs/ # decisions/ (ADRs), architecture/, theory/, … +├── Justfile # task runner (imports contractile.just) +├── Cargo.toml # MSRV 1.85, edition 2024 +├── Containerfile # TEMPLATE STUB — no build steps yet +├── guix.scm # experimental dev shell +└── 0-AI-MANIFEST.a2ml # AI agent entry point ---- +[[status-and-gotchas]] +== Status and gotchas + +* **`src/tier2/` is stubs.** The `[tier2]` manifest flags parse but do + nothing yet; no overlay DDL or query routing ships. +* **`Containerfile` is a template.** It has commented-out `TODO` steps and + unfilled template metadata, so `podman build` produces an empty image. +* **`flake.nix` does not exist.** `guix.scm` is a development shell + (`guix shell -D -f guix.scm`), not a package definition, and pins version + 0.1.0 while `Cargo.toml` says 0.2.0. +* **`.devcontainer/` is not usable.** `devcontainer.json` and + `.devcontainer/Containerfile` still contain the unreplaced `PROJECT_NAME` + template token. +* **PostgreSQL runtime reads are not implemented.** `provenance`, `history`, + `drift`, and `gc` refuse explicitly on the `postgres` sidecar backend + rather than silently no-op. + == Key Recipes [source,bash] ---- -just build # Build the project -just test # Run tests -just doctor # Self-diagnostic -just lint # Lint and format -just panic-scan # Security scan via panic-attacker -just tour # Guided tour of the codebase +just build # cargo build --release +just test # cargo test +just quality # fmt-check + lint + test +just lint # cargo clippy -- -D warnings +just fmt # cargo fmt +just fmt-check # cargo fmt -- --check +just doc # rustdoc, opens in a browser +just run -- --help # cargo run -- --help (note the extra --) +just doctor # checks tools, paths, permissions +just deps # Zig toolchain (fail-soft) + cargo fetch +just assail # panic-attack scan, if installed +just must-check # contractile MUST invariants (from contractile.just) +just doc-recipes # verify documented recipes exist +just --list # the authoritative list ---- == Before Submitting a PR [source,bash] ---- -just lint # Format and lint -just test # All tests pass -just panic-scan # No new security issues +cargo fmt --all -- --check +cargo clippy --all-targets -- -D warnings +cargo test --all-targets --no-fail-fast ---- -== Contractile Invariants - -Read `.machine_readable/MUST.contractile` before making changes. -Key invariants that must never be violated: - -{{MUST_INVARIANTS}} +* Commits are SSH-signed (`.github/CONTRIBUTING.md`); PRs target `main`. +* `docs/CONTRIBUTING-DEV.adoc` has the per-area checklists (new drift + category, new Tier 2 overlay, vocabulary rules). -== LLM/AI Agent Development +== Contractile Invariants -If using an AI assistant, load the warmup context first: +Must/Trust/Dust/Intend contractiles live in +`.machine_readable/contractiles/`. The MUST invariants are enforced by +recipes imported from `contractile.just`: [source,bash] ---- -just llm-context # Outputs role-appropriate context +just must-check # LICENSE, README, SPDX headers, no Dockerfile/Makefile +just trust-verify # licence content, no committed secrets, pinned images +just contractile-check # presence check only (informational, ADR-0008) ---- -Or read `0-AI-MANIFEST.a2ml` and `.claude/CLAUDE.md` directly. +Never write to the target database from Tier 1 code paths, and keep +provenance chains append-only — see `docs/architecture/THREAT-MODEL.adoc`. + +== LLM/AI Agent Development + +There is no `just llm-context` recipe. Read these directly: + +* `0-AI-MANIFEST.a2ml` — canonical locations, invariants, startup checklist. +* `.claude/CLAUDE.md` — repository conventions. +* `.machine_readable/6a2/STATE.a2ml` — current project state. == Get Help -* **Architecture**: link:EXPLAINME.adoc[EXPLAINME.adoc] -* **Wiki**: https://github.com/hyperpolymath/verisimiser/wiki -* **Report issue**: `just help-me` +* **Architecture and claims**: link:EXPLAINME.adoc[EXPLAINME.adoc], + link:README.adoc[README.adoc], `docs/decisions/` +* **Diagnostics**: `just doctor` output in any issue report +* **Report issue**: `just help-me` prints the diagnostic bundle to paste + into https://github.com/hyperpolymath/verisimiser/issues/new diff --git a/QUICKSTART-MAINTAINER.adoc b/QUICKSTART-MAINTAINER.adoc index ecd77cc..40ca5a1 100644 --- a/QUICKSTART-MAINTAINER.adoc +++ b/QUICKSTART-MAINTAINER.adoc @@ -1,18 +1,24 @@ // SPDX-License-Identifier: CC-BY-SA-4.0 -// Template: QUICKSTART-MAINTAINER.adoc — packaging, deploying, and maintaining -// Replace verisimiser, {{PACKAGE_NAME}}, {{DEPS}} with actuals +// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) = verisimiser — Quick Start for Platform Maintainers :toc: :toclevels: 2 -== Overview - -This guide covers packaging, deploying, and maintaining verisimiser for -distribution on your platform. +Packaging, installing, and operating verisimiser. Every command below was +checked against the repository at the time of writing; see +<> before promising +a distro package or container image. == Runtime Dependencies -{{DEPS}} +* **None** beyond libc. `verisimiser` is a single dynamically-linked-of-libc + binary; SQLite is compiled in via `rusqlite`'s `bundled` feature, so there + is no `libsqlite3` runtime dependency. +* **Build-time only:** a C compiler (for the bundled SQLite) and `git` (the + build script stamps the SHA from `HEAD`; if git is absent it records + `unknown` rather than failing). +* Target databases (PostgreSQL, SQLite, MongoDB) are *not* linked in; they + are reached over their own protocols and connection strings. == Build from Source @@ -20,110 +26,162 @@ distribution on your platform. ---- git clone https://github.com/hyperpolymath/verisimiser.git cd verisimiser -just build-release +cargo build --release # or: just build ---- -Output: `{{BUILD_OUTPUT_PATH}}` - -== Packaging +Output binary: `target/release/verisimiser`. -=== Guix +Verify the build is what you packaged: [source,bash] ---- -guix build -f guix.scm +./target/release/verisimiser --version +./target/release/verisimiser version --json ---- -=== Nix +`version --json` emits `version`, `git_sha`, `git_describe`, and +`build_date`, baked in at compile time by `build.rs`. -[source,bash] ----- -nix build ----- +== Packaging -=== Container (Stapeln) +=== Cargo (upstream-native) [source,bash] ---- -just stapeln-export # Generates Containerfile -podman build -t verisimiser . +cargo install --path . +cargo install --path . --root /opt/verisimiser # -> /opt/verisimiser/bin/verisimiser +cargo install --path . --locked # honour Cargo.lock ---- -=== Manual Package +`cargo install` writes exactly one file: `/bin/verisimiser` (default +root `$HOME/.cargo`). There is **no `--prefix` flag** and no data, man page, +or `.desktop` file to install — the old `just install --prefix=…` examples in +this repo's templates never worked. Use `--root`. + +=== Guix (experimental) + +`guix.scm` describes a **development shell**, not a package: [source,bash] ---- -just install --prefix=/usr/local +guix shell -D -f guix.scm ---- -Files installed: +It pins `version = "0.1.0"` while `Cargo.toml` is at 0.2.0, so do not use it +as the basis of a distro package without updating it first. A real Guix +package would need `cargo-build-system` and a vendored/`cargo-crates` +source, which does not exist here yet. -[cols="1,2"] -|=== -| Path | Contents +=== Nix + +There is **no `flake.nix`** in this repository. ADR-0009 keeps Nix/Guix in +the tree as experimental; only `cargo` (dev) and the Containerfile (ops, +aspirational) are named canonical. + +=== Container (not ready) -| `$PREFIX/bin/` -| Executables +The `Containerfile` is an unfilled RSR template: build steps, artifact copy, +and `ENTRYPOINT` are commented-out `TODO`s, and the header still contains +unreplaced template metadata (project name, author, year). `podman build` therefore +produces an empty image. Sealing and publishing should wait until it is +implemented (chainguard `wolfi-base` builder → `static` runtime, +`COPY --from=build /build/target/release/verisimiser /usr/local/bin/`). -| `$PREFIX/share/{{PACKAGE_NAME}}/` -| Data files, assets +=== Manual package -| `$PREFIX/share/doc/{{PACKAGE_NAME}}/` -| Documentation +The complete file list to install is: -| `$PREFIX/share/applications/` -| .desktop file (Linux, if GUI) +[cols="1,2",options="header"] +|=== +| Path | Contents -| `$PREFIX/share/man/man1/` -| Man pages +| `$PREFIX/bin/verisimiser` | The CLI binary |=== -== Configuration +No configuration file is installed: verisimiser has **no global config and +no XDG lookup**. Every invocation reads a `verisimiser.toml` from the path +given by `--manifest`/`-m`, defaulting to `./verisimiser.toml` in the working +directory. That makes per-user and multi-tenant installs trivial — see +<>. + +== Release Artifacts -Default config location: `$XDG_CONFIG_HOME/{{PACKAGE_NAME}}/config.toml` +`.github/workflows/release.yml` triggers on any `v*` tag and builds archives +for `x86_64-unknown-linux-gnu`, `aarch64-unknown-linux-gnu`, +`aarch64-apple-darwin`, and `x86_64-pc-windows-msvc`, each with a `.sha256` +companion, then publishes them with SLSA provenance attestations. -Fallback: `$HOME/.config/{{PACKAGE_NAME}}/config.toml` +**No release or tag exists yet**, so there is nothing to download: the source +build is currently the only supported install path. The first tagged release +will make the archives available. -== Health Checks +== Operating + +=== Verify a deployment [source,bash] ---- -just doctor # Full diagnostic -just run --version # Version check -just run --selftest # Built-in self-test +verisimiser version --json # binary identity +verisimiser -m /etc/myapp/verisimiser.toml validate +verisimiser -m /etc/myapp/verisimiser.toml status --json +verisimiser doctor -m /etc/myapp/verisimiser.toml ---- -== Updating +`status --json` is a documented, stable schema (`name`, `backend`, +`sidecar_path`, `sidecar_storage`, `octad`) — safe to scrape from your +monitoring. + +=== Retention / garbage collection [source,bash] ---- -git pull -just build-release -just install --prefix=/usr/local +verisimiser -m verisimiser.toml gc --dry-run --json # what would be deleted +verisimiser -m verisimiser.toml gc # apply ---- -Or via OPSM: `opsm update {{PACKAGE_NAME}}` +Bounds come from `[retention]` in the manifest (`provenance-days`, +`temporal-days`, `lineage-days`; `0` = keep forever). Schedule `gc` +alongside your existing backup rotation. -== Security Notes +=== Sidecar backends -* License: MPL-2.0 (code) / CC-BY-SA-4.0 (docs) -* All dependencies SHA-pinned -* `panic-attacker` scan results: link:INSTALL-SECURITY-REPORT.adoc[] -* OpenSSF Scorecard: see badge in README +`sqlite` (default reference store), `postgres` (DDL dialect only — runtime +reads are **not** implemented and refuse explicitly), and the `json` family +(`plain`, `ld`, `ndjson`) with crash-safe writes and cross-process locking. +Pick per manifest under `[sidecar]`. -== Multi-Instance Deployment +[[multiple-instances]] +=== Multiple instances -For deploying multiple instances (e.g., different users or tenants): +Because configuration is a path, not a global file, run several augmented +databases on one host: [source,bash] ---- -just install --prefix=/opt/{{PACKAGE_NAME}}-instance1 --config=/etc/{{PACKAGE_NAME}}/instance1.toml -just install --prefix=/opt/{{PACKAGE_NAME}}-instance2 --config=/etc/{{PACKAGE_NAME}}/instance2.toml ----- - -Each instance has isolated config, data, and logs. - -== Reporting Issues - -* Upstream: https://github.com/hyperpolymath/verisimiser/issues -* With diagnostic: `just help-me` (pre-fills context) +mkdir -p /etc/verisimiser/{orders,analytics} +cp verisimiser.toml /etc/verisimiser/orders/ +cp verisimiser.toml /etc/verisimiser/analytics/ +verisimiser -m /etc/verisimiser/orders/verisimiser.toml status +verisimiser -m /etc/verisimiser/analytics/verisimiser.toml status +---- + +Give each manifest its own `[sidecar].path` so the stores do not collide. +Connection strings are read from the environment variable named by +`[database].connection-string-env`, so secrets stay in your existing secret +manager rather than in the manifest. + +[[what-is-not-packaging-ready]] +== What is not packaging-ready + +State this plainly in any package description: + +* **Tier 2 is stubs.** `[tier2]` overlay flags parse but nothing is + generated or routed; do not advertise graph/vector/tensor/spatial + overlays. +* **PostgreSQL is codegen-only at runtime.** `provenance`, `history`, + `drift`, and `gc` refuse on the `postgres` sidecar backend. +* **Container and devcontainer are templates**, not usable artifacts. +* **No published releases yet**, so packagers must build from source and + record the commit SHA they built. +* **Pre-alpha.** `Cargo.toml` says 0.2.0, APIs may move, and only the + `status --json` field set plus the manifest keys are documented as stable. diff --git a/QUICKSTART-USER.adoc b/QUICKSTART-USER.adoc index 0dab13d..6fc3ee0 100644 --- a/QUICKSTART-USER.adoc +++ b/QUICKSTART-USER.adoc @@ -1,124 +1,167 @@ // SPDX-License-Identifier: CC-BY-SA-4.0 -// Template: QUICKSTART-USER.adoc — 5-minute path to working software -// Replace verisimiser, Verisimiser — See README.adoc for details., just run, Verisimiser started successfully. with actuals +// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) = verisimiser — Quick Start for Users :toc: :toclevels: 2 == What is verisimiser? -Verisimiser — See README.adoc for details. +A CLI that augments an existing PostgreSQL, SQLite, or MongoDB database with +VeriSimiser's eight-concern Octad — provenance, lineage, temporal versioning, +access control, constraints — without migrating your schema or changing how +your application talks to its database. The sidecar lives beside your +database; Tier 1 code never writes to it. See link:README.adoc[README.adoc] +for the full picture and its honest limits. == Prerequisites -Before you begin, ensure you have: +* **Rust 1.85 or newer** — verisimiser is distributed as source only, so you + build it yourself. +* **A C compiler** (`cc`, `gcc`, or `clang`) — SQLite is compiled in from + source by `rusqlite`'s `bundled` feature. +* **git** — to clone the repository. +* **No database server is needed to install or run `--help`/`octad`/`version`.** + You only need your target database when you actually point a manifest at it. -* **just** — task runner (https://github.com/casey/just[install guide]) -* Platform-specific requirements listed below - -[cols="1,3"] -|=== -| Platform | Additional Requirements - -| Linux -| See README.adoc - -| macOS -| See README.adoc - -| Windows -| See README.adoc -|=== +TIP: Check for a published release first — +https://github.com/hyperpolymath/verisimiser/releases. The release workflow +exists (tag `v*` → four platform archives) but **no release has been published +yet**, so today the source build is the only route. == Install -=== Option 1: Standard Install (recommended) +=== Option 1: `cargo install` (recommended) [source,bash] ---- -# Clone and set up +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal +. "$HOME/.cargo/env" + git clone https://github.com/hyperpolymath/verisimiser.git cd verisimiser -just setup +cargo install --path . ---- -The setup script will: +This installs to `$HOME/.cargo/bin/verisimiser`. If `verisimiser --version` +is "command not found", add the directory to your `PATH`: -* Detect your platform and shell -* Install missing dependencies (with your permission) -* Configure the application -* Offer install location choices -* Run a self-diagnostic to verify everything works +[source,bash] +---- +export PATH="$HOME/.cargo/bin:$PATH" +---- -=== Option 2: Container (via Stapeln) +=== Option 2: build without installing [source,bash] ---- -just stapeln-run +cargo build --release +./target/release/verisimiser --version ---- -=== Option 3: Portable (no system changes) +Copy `target/release/verisimiser` wherever you like; it is a single binary +with no runtime library dependencies beyond libc. + +=== Option 3: `just` + +If you have https://github.com/casey/just[`just`] installed: [source,bash] ---- -just install --portable --prefix=./verisimiser-portable +just build # cargo build --release +just install # cargo install --path . ---- +`just install` takes no arguments. For a custom prefix use +`cargo install --path . --root /opt/verisimiser` (binary lands in +`/opt/verisimiser/bin/`). + +=== Not available yet + +* **No container image.** The `Containerfile` in the repo is still an + unfilled template, so `podman build` does not produce a working image. +* **No `just setup`, `just stapeln-run`, or `just uninstall`.** Those appear + in some template docs but are not recipes in this repo; `just --list` is + authoritative. + == First Run +Create a manifest in the directory you want to augment, then inspect it: + [source,bash] ---- -just run +cd ~/projects/my-app +verisimiser init --database sqlite --name my-augmented-db ---- -Expected output: +That writes `verisimiser.toml` in the current directory (it refuses to +overwrite an existing one unless you pass `--force`). `--database` accepts +`postgresql`, `sqlite`, or `mongodb` and defaults to `postgresql`. + +Check what you got: -[source] +[source,bash] ---- -Verisimiser started successfully. +verisimiser validate # manifest checks; non-zero exit if any fail +verisimiser status # backend, sidecar path, which concerns are on +verisimiser octad # the eight concerns and their tier ---- -== Self-Diagnostic - -If something isn't working: +Generate sidecar DDL and query interceptors (needs a schema file): [source,bash] ---- -just doctor +# add: schema-source = "schema.sql" under [database] in verisimiser.toml +verisimiser generate # writes into .verisim/ ---- -This checks all dependencies, permissions, paths, and connectivity. -If it finds issues, it will suggest fixes. +Without `schema-source`, `generate` warns and emits an empty overlay. + +== Configuration -To attempt automatic repair: +Everything lives in the `verisimiser.toml` you just created: + +* `[database]` — `backend` and `connection-string-env` (the name of the + environment variable holding the connection string; secrets stay out of + the file). +* `[octad]` — which concerns are enabled. +* `[sidecar]` — where the sidecar store lives (`sqlite`, `postgres`, or the + `json` family) and its path. +* `[retention]` — how long `provenance`, `temporal`, and `lineage` data is + kept; enforced by `verisimiser gc`. + +See the manifest section of link:README.adoc[README.adoc] for a full example +and the legacy sections. + +== Self-Diagnostic [source,bash] ---- -just heal +verisimiser doctor # environment + toolchain checks +verisimiser doctor -m verisimiser.toml # also run manifest validation +verisimiser --help # all subcommands +verisimiser --help # per-subcommand options ---- -== Get Help - -* **In-app**: `just run --help` -* **Guided tour**: `just tour` -* **Report a problem**: `just help-me` (pre-fills diagnostic context) -* **Wiki**: https://github.com/hyperpolymath/verisimiser/wiki +If you installed `just`, `just doctor` and `just help-me` add repo-level +checks and a paste-ready diagnostic bundle. == Uninstall [source,bash] ---- -just uninstall +cargo uninstall verisimiser ---- -You will be asked: - -1. Which uninstall tier (Bennett reversible, parameter-based, standard, or secure) -2. Whether to include or exclude your data -3. Whether to clear caches and LLM models +Or simply delete the binary (`~/.cargo/bin/verisimiser`, or the path you +copied it to). Your data is untouched: the manifest is the +`verisimiser.toml` you created, and sidecar data lives at the +`[sidecar].path` recorded in it — remove that file only if you want the +provenance/temporal history gone too. == Next Steps -* Read the link:README.adoc[README] for full feature overview -* Read the link:EXPLAINME.adoc[EXPLAINME] for architecture and design decisions -* Try `just tour` for a guided walkthrough +* link:README.adoc[README] — tiers, the eight concerns, and what is not + implemented yet. +* link:EXPLAINME.adoc[EXPLAINME] — technology choices and the reasoning. +* link:QUICKSTART-DEV.adoc[QUICKSTART-DEV] — building from a checkout, + running tests, contributing. diff --git a/README.adoc b/README.adoc index b073d9a..c207a85 100644 --- a/README.adoc +++ b/README.adoc @@ -496,20 +496,36 @@ it). Most users will be happy at Tier 1 or Tier 2. == Building and Running Per `docs/decisions/0009-build-path.adoc`, two build paths are -canonical: +*named* canonical. Only the first is implemented today: -* **`cargo build`** for development. MSRV pinned at Rust 1.85 - (`rust-version` in `Cargo.toml`). The Justfile wraps the common - recipes. -* **`Containerfile`** for ops. Produces a single OCI image suitable - for deployment, CI, and reproducible release builds. +* **`cargo build`** — implemented, and the only supported path. MSRV is + Rust 1.85 (`rust-version` in `Cargo.toml`, edition 2024). + `rusqlite` compiles bundled SQLite, so you need a C compiler. The + Justfile wraps the common recipes. -`flake.nix`, `guix.scm`, `.guix-channel`, and `.devcontainer/` remain -in the tree as **experimental** paths — kept, not maintained. +[source,bash] +---- +cargo build --release # -> target/release/verisimiser +cargo install --path . # -> $HOME/.cargo/bin/verisimiser +cargo test --all-targets --no-fail-fast # what CI runs +---- -Pre-built release binaries for `linux-x86_64`, `linux-aarch64`, -`macos-arm64`, and `windows-x86_64` are published by the release -workflow (V-L3-L1, #58) with `.sha256` companions. +* **`Containerfile`** — the intended ops path, **not yet implemented**. + It is still an RSR template stub: build steps, artifact copy, and + `ENTRYPOINT` are commented-out `TODO`s and the header retains unfilled + template metadata, so `podman build` produces an empty image. + +Everything else in the tree is **experimental**: `guix.scm` (a development +shell, `guix shell -D -f guix.scm`, pinned to an older version than +`Cargo.toml`), `.guix-channel`, and `.devcontainer/` (whose +`devcontainer.json` and `Containerfile` still contain the unreplaced +`PROJECT_NAME` template token). There is **no `flake.nix`** in this repository. + +No release has been published: the release workflow builds +`linux-x86_64`, `linux-aarch64`, `macos-arm64`, and `windows-x86_64` +archives with `.sha256` companions on any `v*` tag (V-L3-L1, #58), but no +tag exists yet, so building from source is the only install route. See +`QUICKSTART-USER.adoc` and `QUICKSTART-MAINTAINER.adoc`. == Integration with TypedQLiser diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc index 6f48e63..c1d3571 100644 --- a/TEST-NEEDS.adoc +++ b/TEST-NEEDS.adoc @@ -1,36 +1,55 @@ -== TEST-NEEDS.md — verisimiser +// SPDX-License-Identifier: CC-BY-SA-4.0 +// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) += TEST-NEEDS.md — verisimiser -=== CRG Grade: C — ACHIEVED 2026-04-04 +== CRG Grade: C — ACHIEVED 2026-04-04 -=== Current Test State +== Current Test State -[width="100%",cols="42%,29%,29%",options="header",] +[width="auto",cols="34%,10%,56%",options="header",] |=== |Category |Count |Notes -|Integration tests (Rust) |2 |Dual compiled binaries (debug + release) +|Integration tests (Rust) |23 |5 files under `tests/` +|Unit tests (Rust) |146 |`#[test]` in `src/**` +|FFI tests |Present |`src/interface/ffi/test/` (Zig, run by `abi-ffi-gate.yml`) +|ABI proofs |Present |`src/interface/abi/Verisimiser/ABI/*.idr` (Idris2, run by `provable.yml`) +|=== + +Integration test files: -|Verification tests |Unit-level |`+verification/tests/+` directory -present +[cols="1,3",options="header"] +|=== +|File |Covers -|FFI tests |Present |`+src/interface/ffi/test/+` +|`tests/integration_test.rs` |Schema parse → overlay DDL, interceptors, manifest shapes, `OctadDimension` +|`tests/logging_test.rs` |stdout data contract vs stderr diagnostics +|`tests/provenance_fork_test.rs` |First-class provenance forks (ADR-0010) +|`tests/sidecar_cli_test.rs` |`provenance` / `history` over the JSON sidecar +|`tests/sqlite_intercept_e2e.rs` |End-to-end SQLite Tier 1 interception |=== -=== What’s Covered +== What’s Covered -* [x] Dual integration test builds +* [x] Dual integration test builds (stable + MSRV 1.85) * [x] FFI verification layer -* [x] Cargo test harness +* [x] Cargo test harness, including CLI-driven tests via `CARGO_BIN_EXE_verisimiser` +* [x] Idris2 ABI models machine-checked in CI -=== Still Missing (for CRG B+) +== Still Missing (for CRG B+) -* [ ] Property-based verification testing -* [ ] Fuzzing for edge cases +* [ ] Property-based verification testing — `proptest` is a declared + dev-dependency but no test uses it yet +* [ ] Fuzzing — `tests/fuzz/` contains only a placeholder * [ ] Benchmarking suite -* [ ] Multi-target platform tests +* [ ] Multi-target platform tests (the release workflow cross-builds, but + the test matrix is Linux-only) -=== Run Tests +== Run Tests [source,bash] ---- -cd /var/mnt/eclipse/repos/verisimiser && cargo test +cd verisimiser +cargo test --all-targets --no-fail-fast # what CI runs +just test # cargo test +just quality # fmt-check + lint + test ---- diff --git a/docs/QUICKSTART.adoc b/docs/QUICKSTART.adoc index b20b3d0..837a78b 100644 --- a/docs/QUICKSTART.adoc +++ b/docs/QUICKSTART.adoc @@ -1,24 +1,71 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 +// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) = Quickstart :toc: preamble -Get up and running in 60 seconds. +Get from a clone to a validated manifest. + +This page is the index; the three role-specific guides carry the detail: + +[cols="1,3",options="header"] +|=== +| Guide | Audience + +| link:../QUICKSTART-USER.adoc[QUICKSTART-USER] +| Installing and running the CLI for the first time +| link:../QUICKSTART-DEV.adoc[QUICKSTART-DEV] +| Building from a checkout, running the test suite, contributing +| link:../QUICKSTART-MAINTAINER.adoc[QUICKSTART-MAINTAINER] +| Packaging, verifying, and operating a deployment +|=== == Prerequisites -* Git 2.40+ -* just (command runner) -* Your language toolchain (see Justfile for details) +* **Rust 1.85+** (`rust-version` in `Cargo.toml`, edition 2024) +* **A C compiler** — `rusqlite` builds bundled SQLite from source +* **git** — `build.rs` stamps the binary with the current commit +* **Optional:** `just` for the task recipes (`cargo install just --locked`) + +There are no system library dependencies: SQLite is compiled in, and nothing +links OpenSSL. + +== Sixty seconds + +[source,bash] +---- +git clone https://github.com/hyperpolymath/verisimiser.git +cd verisimiser +cargo install --path . # -> $HOME/.cargo/bin/verisimiser +cd ~/projects/my-app +verisimiser init --database sqlite --name my-augmented-db +verisimiser validate +verisimiser status +---- -== From Template (New Project) +`init` writes `verisimiser.toml` in the current directory; `validate` exits +non-zero if any manifest check fails. + +== Running the test suite [source,bash] ---- -git clone https://github.com/hyperpolymath/rsr-template-repo my-project -cd my-project -rm -rf .git && git init -b main -just init # interactive placeholder replacement +cd verisimiser +cargo test --all-targets --no-fail-fast # what CI runs +just quality # fmt-check + lint + test ---- +== What this repository does *not* give you yet + +* **No published release.** The `v*`-tagged release workflow exists, but no + tag or release has been created, so build from source. +* **No usable container.** `Containerfile` and `.devcontainer/` are RSR + template stubs with `TODO` build steps and unfilled template metadata. +* **No `flake.nix`.** `guix.scm` is an experimental dev shell only. +* **No `just setup` / `just check-error-codes` / `just e2e` recipes.** Run + `just --list` for the authoritative set; `just doc-recipes` checks that + documentation does not reference recipes which do not exist. + == Project Structure -See README.adoc in the root for the Dual-Track architecture summary. +See link:../QUICKSTART-DEV.adoc[QUICKSTART-DEV] for the annotated tree, and link:../README.adoc[README.adoc] for the Dual-Track +(Tier 1 / Tier 2) architecture summary. diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc index 8c80722..5c8acf9 100644 --- a/llm-warmup-dev.adoc +++ b/llm-warmup-dev.adoc @@ -1,19 +1,30 @@ -== LLM Warmup — verisimiser (Developer) +// SPDX-License-Identifier: CC-BY-SA-4.0 +// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) += LLM Warmup — verisimiser (Developer) -=== What is verisimiser? +== What is verisimiser? -See README.adoc for overview. +Augments an existing database with VeriSimiser's eight-concern Octad +(ADR-0004): provenance, lineage, constraints, access control, temporal, +simulation. VeriSimDB's upstream Octad is a different, eight-modality model +(ADR-0014). See link:README.adoc[README.adoc]. -=== Key Commands +== 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 +* `just build` — `cargo build --release` +* `just test` — `cargo test` (CI also runs `--all-targets --no-fail-fast`) +* `just quality` — fmt-check + clippy + test +* `just deps` — Zig toolchain (fail-soft) + `cargo fetch` +* `just doctor` — toolchain/path diagnostics +* `just heal` — best-effort repair of permissions and caches +* `just doc-recipes` — verify docs reference only real recipes -=== Quick Context +There is no `just setup` or `just setup-dev`; use `cargo fetch` (or +`./setup.sh`, which falls back to `just doctor`). + +== Quick Context * License: MPL-2.0 -* Part of hyperpolymath ecosystem -* See EXPLAINME.adoc for architecture +* MSRV 1.85, edition 2024; SQLite is bundled via `rusqlite` +* Tier 2 (`src/tier2/`) is stubs; Containerfile is a template stub +* See link:EXPLAINME.adoc[EXPLAINME.adoc] and `docs/decisions/` diff --git a/llm-warmup-user.adoc b/llm-warmup-user.adoc index 55ead6c..3ee7585 100644 --- a/llm-warmup-user.adoc +++ b/llm-warmup-user.adoc @@ -1,19 +1,32 @@ -== LLM Warmup — verisimiser (User) +// SPDX-License-Identifier: CC-BY-SA-4.0 +// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) += LLM Warmup — verisimiser (User) -=== What is verisimiser? +== What is verisimiser? -See README.adoc for overview. +A CLI that adds provenance, lineage, temporal versioning, access control, and +constraint/drift reporting to an existing PostgreSQL, SQLite, or MongoDB +database using sidecar storage. See link:README.adoc[README.adoc]. -=== Key Commands +== 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 +[source,bash] +---- +cargo install --path . # install (needs Rust 1.85+ and a C compiler) +verisimiser init --database sqlite --name my-db +verisimiser validate +verisimiser status +verisimiser octad +verisimiser --help +---- -=== Quick Context +With `just`: `just build`, `just install`, `just doctor`, `just help-me`. +There is no `just setup` or `just uninstall` recipe; uninstall with +`cargo uninstall verisimiser`. + +== Quick Context * License: MPL-2.0 -* Part of hyperpolymath ecosystem -* See EXPLAINME.adoc for architecture +* No published releases yet — build from source +* Pre-alpha: Tier 2 overlays and PostgreSQL runtime reads are not implemented +* See link:QUICKSTART-USER.adoc[QUICKSTART-USER.adoc] diff --git a/scripts/check-doc-recipes.sh b/scripts/check-doc-recipes.sh new file mode 100755 index 0000000..f313b50 --- /dev/null +++ b/scripts/check-doc-recipes.sh @@ -0,0 +1,108 @@ +#!/bin/sh +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# check-doc-recipes.sh — fail if documentation tells readers to run a +# `just` recipe that the Justfile does not define. +# +# Why: the quickstarts inherited from the RSR template referenced recipes +# that never existed here (`just setup`, `just e2e`, `just check-error-codes`, +# `just panic-scan`), so readers hit "Justfile does not contain recipe". +# ADR-0002 removed aspirational recipes; this check keeps the docs honest in +# the other direction. +# +# Scope: only `just ` occurrences inside AsciiDoc code blocks +# (`----` and `....` fences) are checked. Prose such as "just the eight +# concerns" is ignored because it is not inside a fence. +# +# Skipped on purpose (reported, not failed): template artifacts that describe +# the upstream RSR template repository rather than this project, and which are +# sync-managed from hyperpolymath/standards. Their recipes belong to the +# template, not to this Justfile. +# +# Usage: scripts/check-doc-recipes.sh [repo-root] (default: this repo) + +set -eu + +ROOT="${1:-$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)}" +cd "$ROOT" + +[ -f Justfile ] || [ -f justfile ] || { + echo "check-doc-recipes: no Justfile in $ROOT" >&2 + exit 2 +} + +# Documents maintained upstream as template content, not as verisimiser docs. +SKIP="docs/RSR_OUTLINE.adoc" + +# Recipe names: `name:`, `name arg:`, `name *args:`, `name +args:`, `name=default:`, +# while ignoring attributes, comments, variable assignments and the +# `alias`/`import`/`export`/`set`/`mod` keywords. +recipe_names() { + awk ' + /^[ \t]/ { next } # indented body lines + /^#/ { next } # comments + /^@/ { next } # attributes/quiet lines + /^(alias|import|export|set|mod)[ \t!?]/ { next } + /^[a-zA-Z][a-zA-Z0-9_-]*([ \t][^:]*)?:/ { + line = $0 + sub(/[ \t].*/, "", line) # keep the leading token + sub(/:.*/, "", line) + if (line != "") print line + } + ' "$@" +} + +recipes="$( { + [ -f Justfile ] && recipe_names Justfile + [ -f justfile ] && recipe_names justfile + for f in *.just; do + [ -f "$f" ] && recipe_names "$f" + done +} | sort -u )" + +[ -n "$recipes" ] || { echo "check-doc-recipes: no recipes found" >&2; exit 2; } + +docs="$(ls ./*.adoc 2>/dev/null; find docs -name '*.adoc' 2>/dev/null)" + +tmp="$(mktemp)" +trap 'rm -f "$tmp"' EXIT + +for doc in $docs; do + case " $(echo "$doc" | sed 's|^\./||') " in + *" $SKIP "*) + printf 'check-doc-recipes: skipping template artifact %s\n' "$doc" + continue + ;; + esac + awk -v DOC="$doc" ' + /^----[[:space:]]*$/ || /^\.\.\.\.[[:space:]]*$/ { infence = !infence; next } + infence { + rest = $0 + while (match(rest, /just[ \t]+[a-zA-Z][a-zA-Z0-9_-]*/)) { + tok = substr(rest, RSTART, RLENGTH) + sub(/^just[ \t]+/, "", tok) + print DOC "\t" tok + rest = substr(rest, RSTART + RLENGTH) + } + } + ' "$doc" >> "$tmp" +done + +bad=0 +while IFS=' ' read -r doc name; do + [ -n "$name" ] || continue + if ! printf '%s\n' "$recipes" | grep -qx "$name"; then + printf 'undefined recipe: just %s (%s)\n' "$name" "$doc" + bad=1 + fi +done < "$tmp" + +if [ "$bad" -ne 0 ]; then + echo "" + echo "check-doc-recipes: FAIL - documentation references recipes that do not exist." >&2 + echo "Either add the recipe, or fix the docs. Run 'just --list' for the real set." >&2 + exit 1 +fi + +echo "check-doc-recipes: OK - every documented 'just' recipe is defined." diff --git a/setup.sh b/setup.sh index 688a26f..4ae2829 100755 --- a/setup.sh +++ b/setup.sh @@ -3,7 +3,8 @@ # setup.sh — Universal setup script for verisimiser # # Detects your shell, platform, and installs prerequisites. -# Then hands off to `just setup` for project-specific configuration. +# Then runs `just setup`/`just setup-dev` if defined, else falls back to +# `just doctor` (verisimiser defines neither). # # Usage: # curl -fsSL https://raw.githubusercontent.com/hyperpolymath/verisimiser/main/setup.sh | sh From 8a1eeadedd1c16042b3bdafb48e35087c4029a0f Mon Sep 17 00:00:00 2001 From: "coderabbitai[bot]" <136622811+coderabbitai[bot]@users.noreply.github.com> Date: Sun, 25 Oct 2026 21:58:30 +0000 Subject: [PATCH 2/4] docs(scripts): clarify recipe_names inputs, parsing limits, and exit status --- scripts/check-doc-recipes.sh | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/scripts/check-doc-recipes.sh b/scripts/check-doc-recipes.sh index f313b50..e259c83 100755 --- a/scripts/check-doc-recipes.sh +++ b/scripts/check-doc-recipes.sh @@ -35,9 +35,12 @@ cd "$ROOT" # Documents maintained upstream as template content, not as verisimiser docs. SKIP="docs/RSR_OUTLINE.adoc" -# Recipe names: `name:`, `name arg:`, `name *args:`, `name +args:`, `name=default:`, -# while ignoring attributes, comments, variable assignments and the -# `alias`/`import`/`export`/`set`/`mod` keywords. +# Print recipe-name candidates from the supplied file paths, one per line. +# With no paths, read standard input. Recognises `name:`, `name arg:`, +# `name *args:` and `name +args:`; this is not a full Justfile parser. +# Skips indented lines, comments, leading `@` lines and declarations using +# the `alias`/`import`/`export`/`set`/`mod` keywords. +# Returns awk's exit status, including failure to read an input file. recipe_names() { awk ' /^[ \t]/ { next } # indented body lines From 6119907860dec3afd36bca13f1059b6207c1b6dc Mon Sep 17 00:00:00 2001 From: "coderabbitai[bot]" <136622811+coderabbitai[bot]@users.noreply.github.com> Date: Sun, 25 Oct 2026 21:59:39 +0000 Subject: [PATCH 3/4] fix(docs): correct quickstart guidance and validate recipes against Just's active inventory --- QUICKSTART-DEV.adoc | 31 +++++++---- QUICKSTART-MAINTAINER.adoc | 38 +++++++++---- QUICKSTART-USER.adoc | 10 ++-- README.adoc | 4 +- docs/QUICKSTART.adoc | 5 +- llm-warmup-dev.adoc | 6 +- scripts/check-doc-recipes.sh | 33 +++-------- scripts/test-check-doc-recipes.sh | 93 +++++++++++++++++++++++++++++++ 8 files changed, 164 insertions(+), 56 deletions(-) create mode 100644 scripts/test-check-doc-recipes.sh diff --git a/QUICKSTART-DEV.adoc b/QUICKSTART-DEV.adoc index e429efc..bf3b0d6 100644 --- a/QUICKSTART-DEV.adoc +++ b/QUICKSTART-DEV.adoc @@ -6,8 +6,9 @@ Clone → build → test → PR, using only commands that exist in this repo. -TIP: Every command in this file is checked against the Justfile by -`just doc-recipes` (see <>). +TIP: `just doc-recipes` checks `just ` references in `----` and +`....` blocks against the active Justfile and skips the template document +`docs/RSR_OUTLINE.adoc` (see <>). == Tech Stack @@ -68,13 +69,23 @@ cargo install just --locked ---- git clone https://github.com/hyperpolymath/verisimiser.git cd verisimiser -cargo fetch # or: just deps (also attempts the Zig toolchain) +cargo fetch ---- -`just deps` additionally runs `scripts/install-zig.sh`, which fetches Zig -from `ziglang.org` and is fail-soft: if Zig cannot be downloaded (proxies, -restricted egress), the recipe still succeeds and you can ignore it unless -you are working on `src/interface/ffi/`. +Contributors working on `src/interface/ffi/` can use `just deps` to install +Zig as well as fetch Cargo dependencies. First configure a writable +`ZIG_PREFIX` (the default is `/usr/local`): + +[source,bash] +---- +export ZIG_PREFIX="$HOME/.local" +export PATH="$ZIG_PREFIX/bin:$PATH" +just deps +---- + +The installer fetches Zig from `ziglang.org`. Download failures (proxies, +restricted egress) are fail-soft; filesystem permission errors can still +fail the recipe. == Build @@ -154,7 +165,7 @@ fails with `Justfile does not contain recipe`: |=== | Not a recipe | Use instead -| `just setup`, `just setup-dev` | `cargo fetch`, or `just deps`; `./setup.sh` falls back to `just doctor` +| `just setup`, `just setup-dev` | `cargo fetch`; for Zig too, configure a writable `ZIG_PREFIX` before `just deps`; `./setup.sh` falls back to `just doctor` | `just check-error-codes` | There is no error-code catalogue in this repo | `just e2e` | `just test` (integration tests in `tests/`) | `just panic-scan` | `just assail` (wraps `panic-attack assail`) @@ -243,8 +254,8 @@ cargo test --all-targets --no-fail-fast ---- * Commits are SSH-signed (`.github/CONTRIBUTING.md`); PRs target `main`. -* `docs/CONTRIBUTING-DEV.adoc` has the per-area checklists (new drift - category, new Tier 2 overlay, vocabulary rules). +* link:CONTRIBUTING-DEV.adoc[CONTRIBUTING-DEV.adoc] has the per-area + checklists (new drift category, new Tier 2 overlay, vocabulary rules). == Contractile Invariants diff --git a/QUICKSTART-MAINTAINER.adoc b/QUICKSTART-MAINTAINER.adoc index 40ca5a1..ae00076 100644 --- a/QUICKSTART-MAINTAINER.adoc +++ b/QUICKSTART-MAINTAINER.adoc @@ -17,8 +17,15 @@ a distro package or container image. * **Build-time only:** a C compiler (for the bundled SQLite) and `git` (the build script stamps the SHA from `HEAD`; if git is absent it records `unknown` rather than failing). -* Target databases (PostgreSQL, SQLite, MongoDB) are *not* linked in; they - are reached over their own protocols and connection strings. +* PostgreSQL and MongoDB are separate servers addressed by their own + protocols and connection strings. +* SQLite is an embedded, file-based database; its library is bundled as + described above. In `[database]`, use `backend = "sqlite"` and set the + environment variable named by `connection-string-env` (default + `DATABASE_URL`) to a file path such as `/srv/myapp/app.db`. The legacy + `connection-string` field can hold the path directly. These target + connection settings are parsed but the CLI does not yet open the target + database from them. == Build from Source @@ -29,9 +36,10 @@ cd verisimiser cargo build --release # or: just build ---- -Output binary: `target/release/verisimiser`. +Output binary: `target/release/verisimiser` on Unix, or +`target/release/verisimiser.exe` on Windows MSVC. -Verify the build is what you packaged: +Verify the build is what you packaged. On Unix: [source,bash] ---- @@ -39,6 +47,14 @@ Verify the build is what you packaged: ./target/release/verisimiser version --json ---- +On Windows MSVC (PowerShell): + +[source,powershell] +---- +.\target\release\verisimiser.exe --version +.\target\release\verisimiser.exe version --json +---- + `version --json` emits `version`, `git_sha`, `git_describe`, and `build_date`, baked in at compile time by `build.rs`. @@ -49,14 +65,16 @@ Verify the build is what you packaged: [source,bash] ---- cargo install --path . -cargo install --path . --root /opt/verisimiser # -> /opt/verisimiser/bin/verisimiser +cargo install --path . --root /opt/verisimiser # Unix example: /opt/verisimiser/bin/verisimiser cargo install --path . --locked # honour Cargo.lock ---- -`cargo install` writes exactly one file: `/bin/verisimiser` (default -root `$HOME/.cargo`). There is **no `--prefix` flag** and no data, man page, -or `.desktop` file to install — the old `just install --prefix=…` examples in -this repo's templates never worked. Use `--root`. +`cargo install` places the binary at `/bin/verisimiser` on Unix or +`/bin/verisimiser.exe` on Windows MSVC (default root `$HOME/.cargo` +on Unix, `%USERPROFILE%\.cargo` on Windows). There is **no `--prefix` flag** +and no data, man page, or `.desktop` file to install — the old +`just install --prefix=…` examples in this repo's templates never worked. +Use `--root`. === Guix (experimental) @@ -95,7 +113,7 @@ The complete file list to install is: |=== | Path | Contents -| `$PREFIX/bin/verisimiser` | The CLI binary +| `$PREFIX/bin/verisimiser` (Unix) or `$PREFIX/bin/verisimiser.exe` (Windows MSVC) | The CLI binary |=== No configuration file is installed: verisimiser has **no global config and diff --git a/QUICKSTART-USER.adoc b/QUICKSTART-USER.adoc index 6fc3ee0..33cbd01 100644 --- a/QUICKSTART-USER.adoc +++ b/QUICKSTART-USER.adoc @@ -7,9 +7,9 @@ == What is verisimiser? A CLI that augments an existing PostgreSQL, SQLite, or MongoDB database with -VeriSimiser's eight-concern Octad — provenance, lineage, temporal versioning, -access control, constraints — without migrating your schema or changing how -your application talks to its database. The sidecar lives beside your +VeriSimiser's eight-concern Octad — data, metadata, provenance, lineage, +constraints, access control, temporal, simulation — without migrating your +schema or changing how your application talks to its database. The sidecar lives beside your database; Tier 1 code never writes to it. See link:README.adoc[README.adoc] for the full picture and its honest limits. @@ -139,9 +139,11 @@ and the legacy sections. verisimiser doctor # environment + toolchain checks verisimiser doctor -m verisimiser.toml # also run manifest validation verisimiser --help # all subcommands -verisimiser --help # per-subcommand options +verisimiser status --help # per-subcommand options ---- +Replace `status` with another subcommand to see its options. + If you installed `just`, `just doctor` and `just help-me` add repo-level checks and a paste-ready diagnostic bundle. diff --git a/README.adoc b/README.adoc index c207a85..bb91aac 100644 --- a/README.adoc +++ b/README.adoc @@ -505,8 +505,8 @@ Per `docs/decisions/0009-build-path.adoc`, two build paths are [source,bash] ---- -cargo build --release # -> target/release/verisimiser -cargo install --path . # -> $HOME/.cargo/bin/verisimiser +cargo build --release # Unix: target/release/verisimiser; Windows MSVC: target/release/verisimiser.exe +cargo install --path . # Unix: $HOME/.cargo/bin/verisimiser; Windows MSVC: %USERPROFILE%\.cargo\bin\verisimiser.exe cargo test --all-targets --no-fail-fast # what CI runs ---- diff --git a/docs/QUICKSTART.adoc b/docs/QUICKSTART.adoc index 837a78b..64dddd7 100644 --- a/docs/QUICKSTART.adoc +++ b/docs/QUICKSTART.adoc @@ -26,8 +26,8 @@ This page is the index; the three role-specific guides carry the detail: * **git** — `build.rs` stamps the binary with the current commit * **Optional:** `just` for the task recipes (`cargo install just --locked`) -There are no system library dependencies: SQLite is compiled in, and nothing -links OpenSSL. +No additional system libraries are required beyond libc: SQLite is compiled +in, and nothing links OpenSSL. == Sixty seconds @@ -36,6 +36,7 @@ links OpenSSL. git clone https://github.com/hyperpolymath/verisimiser.git cd verisimiser cargo install --path . # -> $HOME/.cargo/bin/verisimiser +mkdir -p ~/projects/my-app cd ~/projects/my-app verisimiser init --database sqlite --name my-augmented-db verisimiser validate diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc index 5c8acf9..9259bb8 100644 --- a/llm-warmup-dev.adoc +++ b/llm-warmup-dev.adoc @@ -5,9 +5,9 @@ == What is verisimiser? Augments an existing database with VeriSimiser's eight-concern Octad -(ADR-0004): provenance, lineage, constraints, access control, temporal, -simulation. VeriSimDB's upstream Octad is a different, eight-modality model -(ADR-0014). See link:README.adoc[README.adoc]. +(ADR-0004): data, metadata, provenance, lineage, constraints, access control, +temporal, simulation. VeriSimDB's upstream Octad is a different, +eight-modality model (ADR-0014). See link:README.adoc[README.adoc]. == Key Commands diff --git a/scripts/check-doc-recipes.sh b/scripts/check-doc-recipes.sh index f313b50..62c79b2 100755 --- a/scripts/check-doc-recipes.sh +++ b/scripts/check-doc-recipes.sh @@ -35,31 +35,14 @@ cd "$ROOT" # Documents maintained upstream as template content, not as verisimiser docs. SKIP="docs/RSR_OUTLINE.adoc" -# Recipe names: `name:`, `name arg:`, `name *args:`, `name +args:`, `name=default:`, -# while ignoring attributes, comments, variable assignments and the -# `alias`/`import`/`export`/`set`/`mod` keywords. -recipe_names() { - awk ' - /^[ \t]/ { next } # indented body lines - /^#/ { next } # comments - /^@/ { next } # attributes/quiet lines - /^(alias|import|export|set|mod)[ \t!?]/ { next } - /^[a-zA-Z][a-zA-Z0-9_-]*([ \t][^:]*)?:/ { - line = $0 - sub(/[ \t].*/, "", line) # keep the leading token - sub(/:.*/, "", line) - if (line != "") print line - } - ' "$@" -} - -recipes="$( { - [ -f Justfile ] && recipe_names Justfile - [ -f justfile ] && recipe_names justfile - for f in *.just; do - [ -f "$f" ] && recipe_names "$f" - done -} | sort -u )" +# Let Just resolve declarations and imports for the active Justfile, including +# quiet (`@name:`) recipes. Unimported .just files must not supply recipe names. +# Use --list to include callable aliases, which --summary omits. Keep listing +# separate from normalization so a Just error is not masked by sort. +recipes="$(just --list --list-heading '' --list-prefix '')" +recipes="$(printf '%s\n' "$recipes" | awk ' + /^[a-zA-Z][a-zA-Z0-9_-]*([[:space:]]|$)/ { print $1 } +' | sort -u)" [ -n "$recipes" ] || { echo "check-doc-recipes: no recipes found" >&2; exit 2; } diff --git a/scripts/test-check-doc-recipes.sh b/scripts/test-check-doc-recipes.sh new file mode 100644 index 0000000..4b3a847 --- /dev/null +++ b/scripts/test-check-doc-recipes.sh @@ -0,0 +1,93 @@ +#!/bin/sh +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# Regression checks for the documented-recipe inventory. Requires just. +set -eu + +CHECKER="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)/check-doc-recipes.sh" +tmp="$(mktemp -d)" +trap 'rm -rf "$tmp"' EXIT +mkdir -p "$tmp/docs" "$tmp/recipes" + +cat > "$tmp/Justfile" <<'EOF' +import "recipes/imported.just" + +@quiet: + exit 99 + +with-arg arg: + exit 99 + +alias shortcut := quiet +EOF +cat > "$tmp/recipes/imported.just" <<'EOF' +imported: + exit 99 +EOF +cat > "$tmp/unimported.just" <<'EOF' +unimported: + exit 99 +EOF +cat > "$tmp/docs/RSR_OUTLINE.adoc" <<'EOF' +---- +just template-only +---- +EOF +cat > "$tmp/README.adoc" <<'EOF' +Prose references such as just prose-only are ignored. +---- +just quiet +just with-arg value +just shortcut +just imported +---- +.... +just quiet +.... +EOF + +sh "$CHECKER" "$tmp" + +expect_failure() { + expected_status="$1" + expected_message="$2" + status=0 + sh "$CHECKER" "$tmp" > "$tmp/result" 2>&1 || status=$? + if [ "$status" -ne "$expected_status" ] || + ! grep -Fq "$expected_message" "$tmp/result"; then + cat "$tmp/result" >&2 + echo "expected exit $expected_status containing: $expected_message" >&2 + exit 1 + fi +} + +# An unimported file cannot make a documented recipe valid. +cat >> "$tmp/README.adoc" <<'EOF' +---- +just unimported +---- +EOF +expect_failure 1 'undefined recipe: just unimported' + +# Undefined references in literal blocks are also checked. +cat > "$tmp/README.adoc" <<'EOF' +.... +just missing +.... +EOF +expect_failure 1 'undefined recipe: just missing' + +# Lowercase justfiles are supported by Just too. +mv "$tmp/Justfile" "$tmp/justfile" +cat > "$tmp/README.adoc" <<'EOF' +---- +just quiet +---- +EOF +sh "$CHECKER" "$tmp" + +# Listing errors must propagate rather than validating against a partial list. +printf '\ninvalid syntax\n' >> "$tmp/justfile" +expect_failure 1 'error:' + +echo 'test-check-doc-recipes: OK' From 976f832896796b08295f5e647ef7c7d88e9d2dd6 Mon Sep 17 00:00:00 2001 From: "coderabbitai[bot]" <136622811+coderabbitai[bot]@users.noreply.github.com> Date: Sun, 25 Oct 2026 22:00:16 +0000 Subject: [PATCH 4/4] fix(ci): expect unavailable sidecars in FFI tests and name maintenance checklist metadata --- docs/governance/MAINTENANCE-CHECKLIST.a2ml | 1 + src/interface/ffi/test/integration_test.zig | 15 +++++++++------ 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/governance/MAINTENANCE-CHECKLIST.a2ml b/docs/governance/MAINTENANCE-CHECKLIST.a2ml index eaee720..eb80aad 100644 --- a/docs/governance/MAINTENANCE-CHECKLIST.a2ml +++ b/docs/governance/MAINTENANCE-CHECKLIST.a2ml @@ -2,6 +2,7 @@ # Cross-repo maintenance baseline (machine-readable canonical) [metadata] +name = "Cross-repo maintenance checklist" version = "1.1.0" last-updated = "2026-02-24" scope = "cross-repo" diff --git a/src/interface/ffi/test/integration_test.zig b/src/interface/ffi/test/integration_test.zig index b0debf2..351bd65 100644 --- a/src/interface/ffi/test/integration_test.zig +++ b/src/interface/ffi/test/integration_test.zig @@ -97,13 +97,14 @@ test "invalid backend is not supported" { // Octad Dimension Tests //============================================================================== -test "enable valid octad dimension" { +test "enable valid octad dimension without overlay returns sidecar_unavailable" { const handle = verisimiser_init() orelse return error.InitFailed; defer verisimiser_free(handle); // Enable provenance dimension (2) for entity 42 const result = verisimiser_enable_dimension(handle, 42, 2); - try testing.expectEqual(@as(c_int, 0), result); // 0 = ok + // The overlay index is not wired into the FFI yet; no dimension was enabled. + try testing.expectEqual(@as(c_int, 7), result); // 7 = sidecar_unavailable } test "enable invalid octad dimension returns error" { @@ -124,13 +125,14 @@ test "enable dimension with null handle returns null_pointer" { // Provenance Tests //============================================================================== -test "record provenance with valid handle" { +test "record provenance with valid handle returns sidecar_unavailable" { const handle = verisimiser_init() orelse return error.InitFailed; defer verisimiser_free(handle); // Record a create operation (0) for entity 42 const result = verisimiser_record_provenance(handle, 42, 0, 0); - try testing.expectEqual(@as(c_int, 0), result); // 0 = ok + // The provenance sidecar is not wired into the FFI yet; no event was stored. + try testing.expectEqual(@as(c_int, 7), result); // 7 = sidecar_unavailable } test "record provenance with null handle" { @@ -161,12 +163,13 @@ test "provenance length with null handle" { // Temporal Versioning Tests //============================================================================== -test "record version with valid handle" { +test "record version with valid handle returns sidecar_unavailable" { const handle = verisimiser_init() orelse return error.InitFailed; defer verisimiser_free(handle); const result = verisimiser_record_version(handle, 42, 0, 0); - try testing.expectEqual(@as(c_int, 0), result); // 0 = ok + // The temporal sidecar is not wired into the FFI yet; no snapshot was stored. + try testing.expectEqual(@as(c_int, 7), result); // 7 = sidecar_unavailable } test "record version with null handle" {