From 3a13477d9a5d81075dd6fe06758d34f617b88a91 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Wed, 7 Oct 2026 11:30:44 +0100 Subject: [PATCH] docs: affirm state at d9b4c8799d1e721489c9cc35e9c0f7ec3f8150ea Profile A affirmation per standards docs/AFFIRMATION-STANDARD.adoc; every claim produced by live runs at the anchor commit on 2026-10-07. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01GpUzjdhWFi26k6s7AWxYcf Signed-off-by: Jonathan D.A. Jewell <6759885+hyperpolymath@users.noreply.github.com> --- docs/AFFIRMATION.adoc | 233 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 233 insertions(+) create mode 100644 docs/AFFIRMATION.adoc diff --git a/docs/AFFIRMATION.adoc b/docs/AFFIRMATION.adoc new file mode 100644 index 0000000..aa0e4b4 --- /dev/null +++ b/docs/AFFIRMATION.adoc @@ -0,0 +1,233 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell += AFFIRMATION: llm-grace, as of 2026-10-07 +Jonathan D.A. Jewell +:toc: macro +:toclevels: 2 +:icons: font +:std-docs: https://github.com/hyperpolymath/standards/blob/main/docs + +_This file states what was true and checkable at one commit, and how it was checked._ + +[NOTE] +==== +An affirmation is a dated declaration of what we believe is true. This one is +profile A (evidential) of the +link:{std-docs}/AFFIRMATION-STANDARD.adoc[AFFIRMATION standard]. It belongs +with `README.adoc` and `EXPLAINME.adoc`: + +[cols="1,3,2",options="header"] +|=== +| File | Answers | Tense +| `README.adoc` | Where is this going, and why? | future +| `EXPLAINME.adoc` | How is it built, and what is the evidence? | descriptive +| `docs/AFFIRMATION.adoc` (this file) | What was true and checkable at one commit? | a frozen instant +|=== + +This file is optional. Delete it rather than keep it unverified, because a +stale affirmation is worse than none. +==== + +toc::[] + +== What this is, and how it works + +*What it is.* A dated, signed record of what can be claimed about +*llm-grace* at one exact commit. It makes no promises about the future; the +README covers that. + +*What the project is.* Graceful degradation for concurrent LLM and agent +terminals. When system resources run short, sessions back off voluntarily and +in priority order, before the OS out-of-memory killer takes the whole VM down. + +*How it stays trustworthy.* Every claim below comes from running the +repository's own `just` recipes in the session that wrote this file. The anchor +names the exact commit. A signed git commit lands the file. + +== The epistemic contract + +This file records our best belief at the timestamp below. It does not guarantee +correctness. It does guarantee no intentional overclaim: a test that could not +run here is listed as not run, not as passed. + +You may conclude that: + +* every claim below was produced by running the tool at the anchor commit, not + copied from memory or from a status document. + +You may *not* conclude that: + +* anything is true at a later commit; +* anything this file does not list passes. Silence is not a claim. + +Anyone may challenge any claim here with a counter-example or a failing run. + +[#verifiable-anchor] +== Verifiable anchor + +[cols="1,2", options="header"] +|=== +| Field | Contents + +| Repo +| `hyperpolymath/llm-grace` + +| Branch +| `main` + +| Commit (HEAD) +| `d9b4c8799d1e721489c9cc35e9c0f7ec3f8150ea` + +| Permalink +| https://github.com/hyperpolymath/llm-grace/tree/d9b4c8799d1e721489c9cc35e9c0f7ec3f8150ea + +| Verified (UTC) +| `2026-10-07T10:25:44Z` + +| Working-tree delta at verification +| `clean`. A detached worktree at `origin/main`; `git status --short` was empty. + +| Toolchain +| Zig 0.15.2, just 1.56.0, GNU bash 5.2.37, on Debian 13 (WSL2, Linux + 6.18.33.2). LMDB development library *not installed* (see <>). +|=== + +[WARNING] +==== +If you are reading this at a later commit, these claims may no longer hold. +Re-run the steps in <> and write a new affirmation. Do not rely on a +stale one. +==== + +== Companion documents and repo metadata + +[cols="1,3", options="header"] +|=== +| Item | State at the anchor + +| `README.adoc` +| Present. Its opening paragraph matches the GitHub description. + +| `EXPLAINME.adoc` +| Present. + +| GitHub description +| "Graceful degradation for concurrent LLM/agent terminals…", checked against + the README on 2026-10-07. + +| GitHub topics +| 13 topics, present. +|=== + +== The honest state + +=== What is solid, and how we checked + +[cols="2,1,3", options="header"] +|=== +| Claim | Result | Command + +| Signal-layer unit tests pass (sampler, classifier) +| 10/10 +| `just test-smoke` + +| Core tests up to the ledger pass: sampler/classifier 10, monitor 10, ladder + 2, safety 2 +| 24/24 run, 24 passed +| `just test` (stops at the LMDB link step, see <>) + +| Structural checks: fail-closed entrypoints, read-only session start, root + allowlist (45 entries, 54 permitted), STATE required fields +| rc=0 +| `just check` + +| Workflow validation, STATE fields, compliance regression tests +| rc=0 +| `just lint` + +| Zig formatting of `src/signal`, `src/control`, `src/ledger`, + `src/monitor` +| rc=0 +| `just fmt-check` + +| Cross-cutting aspect tests +| PASS=2, FAIL=0, WARN=2 +| `just aspect` +|=== + +=== The nuance you must not lose + +* `just check` says "This is not a release or security certification", and so + does this file. It covers the structural checks only. +* `just e2e` exits 1 *by design*: the live monitor and hook acceptance suite + is not implemented (issue #4). The recipe refuses to report a fake success. +* There is no app or daemon binary to install yet (`just run` says so). + +=== Known gaps, stated in the repo + +* The end-to-end suite (issue #4) and benchmarks are not implemented. + +[#outstanding] +=== Outstanding, weak or refuted + +* *Ledger tests not run here.* `just test` stops with "unable to find dynamic + system library 'lmdb'" after the 24 tests above. The ledger tests need the + LMDB headers and library (`LMDB_PREFIX`), which this machine did not have. + Their result is *unknown*, not passed. +* *Aspect warnings.* `src/interface/ffi/src/main.zig` lacks an SPDX header. + The aspect suite flags this as an owner-only licensing review. +* *Red CI at the anchor.* Of 37 check runs on this commit, 25 succeeded, 3 were + skipped and 9 failed: + `governance / Actions lockfile verify`, + `governance / Check Workflow Staleness`, + `governance / Workflow security linter`, `Hypatia neurosymbolic scan`, + `openssf-compliance`, `skeleton-drift`, `SonarCloud Code Analysis`, + `Validate DEED manifests`, `Validate K9 contracts`. None is a required + check. Issue #96 tracks the pre-existing failures. + +[#reproduce] +== Reproduce it yourself + +[source,bash] +---- +git clone https://github.com/hyperpolymath/llm-grace +cd llm-grace +git checkout d9b4c8799d1e721489c9cc35e9c0f7ec3f8150ea +just test-smoke # expect: All 10 tests passed. +just check # expect: Implemented local checks passed. +just lint +just fmt-check +just aspect # expect: PASS=2 FAIL=0 WARN=2 +just test # needs LMDB; without it, stops after 24 passing tests +---- + +== One-line characterisation + +At `d9b4c87`, llm-grace's signal, monitor, ladder and safety layers pass 24 +Zig tests and every implemented structural check. The ledger tests were not run +here for lack of LMDB, the end-to-end suite does not exist yet, and nine +non-required CI checks are red. + +== Joint attestation + +We assert that, to the best of our joint belief at the timestamp above, every +claim in this file is true and was checked as described. The open gaps are +stated, not hidden. + +* *Engineering party (AI):* Claude Opus 5.5 (`claude-opus-5-5`) ran the checks + recorded here at `2026-10-07T10:25:44Z`. It stands behind the wording above as + a faithful report of those runs. +* *Owner / maintainer:* Jonathan D.A. Jewell signs + by committing this file with `-S`. The git commit signature over this + content, at the commit SHA recorded above, is the cryptographic form of this + affirmation. + +[source,bash] +---- +git commit -S -s docs/AFFIRMATION.adoc -m "docs: affirm state at d9b4c8799d1e721489c9cc35e9c0f7ec3f8150ea" +git log --show-signature -1 +---- + +The file is landed by a signed git commit. Check with `git log --show-signature` +that the anchor SHA above matches the parent of the commit that introduced this +affirmation. If they do not match, read this file as a draft.