Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 24 additions & 11 deletions README.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -61,11 +61,15 @@ Damaged data (fragments, corruption, inconsistencies)
Drift score: ~0.15
│
▼
PHASE 5 — CONVERGENCE (gate ceiling L6; VCL-total Levels 7-10 are future vcl-ut work)
Cardinality bounds, effect tracking, temporal consistency, linearity.
PHASE 5 — CONVERGENCE (gate ceiling L6; Levels 7-10 not yet reachable from VCL text)
Checks: recovery fixpoint reached, statements gate-admissible at the L6
ceiling, provenance chain verifies, server drift agrees with local
expectation. Cardinality safety is level 6. Effect tracking (7), temporal
safety (8), linearity (9) and epistemic safety (10) are defined in vcl-ut,
but VCL text cannot express them until its parser lands (vcl-ut #25).
The reintroduction statements for an entity are gate-admissible at level k
(ceiling 6 from VCL text; see docs/ROUTE-PLAN.adoc section 4.4).
Drift score: approaches 0.0
Drift: observed, not the completion criterion
│
▼
OUTPUT: reconstructed database with:
Expand Down Expand Up @@ -97,12 +101,16 @@ by the others:

**Progressive typing is the ratchet.** Each VCL-total level constrains the
solution space further. Level 1 accepts almost anything. Level 10 demands
formal proof. Data can only become more consistent through the levels,
never less. This is constraint propagation applied to database recovery.
formal proof. Each level narrows the admissible states, but consistency does
not rise monotonically: guarded fill can raise the conflict count (a
mechanised counter-model, rung R4 in link:PROOF-STATUS.adoc[PROOF-STATUS.adoc]),
which conflict resolution then has to clear. This is constraint propagation
applied to database recovery.

**Drift detection becomes the convergence metric.** Instead of alerting on
drift (normal VeriSimDB behaviour), drift score becomes the objective
function: recovery is complete when cross-modal drift approaches zero.
**Recovery completes at a conflict-free fixpoint.** Drift is observed, not
used as the completion criterion, and can rise during guarded fill. A
conflict-free state does not by itself establish zero drift: that bridge
lemma (R17 in link:PROOF-STATUS.adoc[PROOF-STATUS.adoc]) is still assumed.

== Architecture

Expand All @@ -117,7 +125,7 @@ function: recovery is complete when cross-modal drift approaches zero.
- Phase 2: Cross-modal inference (fill missing modalities)
- Phase 3: Conflict resolution (provenance + temporal + semantic arbitration)
- Phase 4: Type tightening (VCL-total levels 4-6; gating planned, the stub does not yet invoke `vclt-gate`)
- Phase 5: Convergence (no gate level beyond Phase 4's planned L6 ceiling; VCL-total levels 7-10 are future vcl-ut work)
- Phase 5: Convergence (no gate level beyond Phase 4's planned L6 ceiling; vcl-ut defines levels 7-10, but VCL text cannot reach them until vcl-ut #25)

* **Invariants** (`src/abi/mod.rs`) — the engine is designed so that the
following hold. No proof lives in this repository and the Rust engine itself
Expand All @@ -127,15 +135,20 @@ function: recovery is complete when cross-modal drift approaches zero.
fibre-intersection and hub-ceiling lemmas) is mechanised in its estate homes
and ledgered with prover receipts in link:PROOF-STATUS.adoc[PROOF-STATUS.adoc];
the prover homes per estate PROOF-POLICY are in `docs/ROUTE-PLAN.adoc`:
- Constraint propagation is monotonic (data only gets more consistent)
- Guarded fill is inflationary (it never overwrites a present value) but
not monotone, and can raise the conflict count; under the hypotheses
`conflict_refl` and `winner_some` (and the axioms listed in the ledger),
the recovery model reaches a conflict-free fixpoint within nine rounds by a
lexicographic measure (R10), not by monotone consistency
- Cross-modal inference preserves entity identity
- Conflict resolution is deterministic (same input → same output)
- Type ratchet is sound (passing level N implies passing levels 1..N-1)

* **VCL-UT integration** (planned) — The `vclt-gate` binary (hyperpolymath/vcl-ut)
is the certifier. Phase 1 is to gate at L1–3 and Phase 4 at L4–6, the L6
ceiling vcl-ut certifies from source today; Phase 5 adds no further gate level
(L7–10 are future vcl-ut work). The current engine stub prints the level names
(vcl-ut defines L7–10, but they are not expressible from VCL text until
vcl-ut #25). The current engine stub prints the level names
and does not yet invoke the gate, so no phase certifies anything today.

* **Output** — Reconstructed database in VeriSimDB format (all 8 modalities
Expand Down
35 changes: 31 additions & 4 deletions container/entrypoint.sh
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,25 @@ echo " Log: ${APP_LOG_FORMAT:-json}"
redact_url() {
_url="$1"
case "$_url" in
*://*) _scheme="${_url%%://*}://"; _rest="${_url#*://}" ;;
*) _scheme=""; _rest="$_url" ;;
*://*)
# Only an RFC 3986 scheme (ALPHA *( ALPHA / DIGIT / "+" / "-" / "." ))
# may be logged. Anything else before "://" (e.g. host?token=SECRET://x)
# could carry a secret, so log a placeholder instead.
_scheme="${_url%%://*}"
case "$_scheme" in
""|[!a-zA-Z]*|*[!a-zA-Z0-9+.-]*)
printf "%s\n" "<unparseable URL; not logged>"
return 0
;;
*) ;;
esac
_scheme="${_scheme}://"
_rest="${_url#*://}"
;;
*)
_scheme=""
_rest="$_url"
;;
esac
# Cut path, query and fragment first: an '@' inside them (e.g.
# ?token=a@secret) must not be mistaken for the userinfo separator.
Expand All @@ -35,12 +52,22 @@ redact_url() {
printf '%s%s\n' "$_scheme" "$_rest"
}

# True when the argument contains a non-whitespace character.
is_nonblank() {
case "$1" in
*[![:space:]]*) return 0 ;;
*) return 1 ;;
esac
}

if [ -z "${VERISIMDB_URL+set}" ]; then
echo " VeriSimDB: <unset> WARNING: the client falls back to http://localhost:8080 and"
echo " persistence errors are not fatal, so session and phase events"
echo " may not be recorded anywhere. Set VERISIMDB_URL for a real batch."
elif [ -z "${VERISIMDB_URL}" ]; then
echo " VeriSimDB: <set but empty> WARNING: VERISIMDB_URL is set to the empty string"
elif ! is_nonblank "${VERISIMDB_URL}"; then
# Blank means empty or whitespace only: VeriSimDbClient::from_env_value
# trims the value and falls back to localhost in both cases.
echo " VeriSimDB: <set but blank> WARNING: VERISIMDB_URL is empty or whitespace only"
echo " (usually a compose file passing through an unset variable)."
echo " The client treats it as unset and falls back to http://localhost:8080;"
echo " session and phase events may not be recorded anywhere."
Expand Down
40 changes: 26 additions & 14 deletions docs/ROUTE-PLAN.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -196,12 +196,13 @@ in each.
postulates. At recon time (2026-11-05) there was no partial-section or
multi-witness layer and `EchoTruncation.agda` was unwired from `All.agda`
(dead code under the repo's own discipline). *Update 2026-11-09:* all three
gaps are closed in echo-types PR #370 (open, not yet on `main`):
gaps are closed by echo-types PR #370 (merged 2026-11-10):
`EchoPartialSection.agda` (R3/R9 theory), `EchoFibreIntersection.agda` (R8)
and `EchoTruncation` wired into `All.agda`/`Smoke.agda`; see
`PROOF-STATUS.adoc`. Still missing there: the drift bridge R17. Not
echo-types work: R11 is a Creusot proof of the Rust resolve kernel that
lives in squeakwell, and the f64 confidence statement needs the
`PROOF-STATUS.adoc`. Not echo-types work: the drift bridge R17 is a Rocq
lemma for verisimdb `Drift.v` (ASSUMED, not yet stated); R11 is a planned
Creusot proof of the Rust resolve kernel, to live in squeakwell (OPEN: no
Creusot source yet), and the f64 confidence statement needs the
quantisation layer noted under R6/R7 (R18 is the separate Kripke-world
conjecture, gated on vcl-ut `Epistemic.idr`).
Retracted and gated: the graded comonad,
Expand Down Expand Up @@ -535,8 +536,8 @@ until the server can return modality content (`GET /octads/{id}/full`).
| S–M

| `formal/Recovery.v` (rung 1) and functorising `Normalizer.v` so it and
`Octad.v` can coexist in one `Require` chain; fix the CROSS-REPO-MAP rows that
cite the unwired `EchoTruncation`
`Octad.v` can coexist in one `Require` chain; the CROSS-REPO-MAP rows that cited the
unwired `EchoTruncation` are moot since echo-types #370 wired it
| No `drift(octad)`, no fill/resolve composition, no measure exists in
`formal/`.
| 150–250 lines Rocq
Expand All @@ -558,6 +559,15 @@ until the server can return modality content (`GET /octads/{id}/full`).

=== 5.3 echo-types

*Update 2026-11-17:* `EchoPartialSection.agda`, `EchoFibreIntersection.agda`
and the `EchoTruncation` wiring landed in echo-types #370 (shapes as recorded
in `PROOF-STATUS.adoc`; the merge is a resolver-parametric algebra, not a join
for the information order). Still open from this list: the Kleene fixpoint on
`Fin 8` (the merged `EchoPartialSection.agda` has guarded fill and its
inflationarity, but no fixpoint lemma; the nine-round fixpoint is mechanised
in Rocq as R10), the generic `fibre-blind` lemma and the `EchoRecovery`
audience record.

* `proofs/agda/EchoPartialSection.agda` (250–400 lines): `PartialSection P :=
(b : B) → Maybe (P b)` over `EchoDisplayed.Displayed`; `Defined`/`dom`;
pointwise information order with refl/trans (antisymmetry only under the
Expand All @@ -568,8 +578,8 @@ until the server can return modality content (`GET /octads/{id}/full`).
postulates, wired into `All.agda` and pinned in `Smoke.agda`.
* `EchoFibreIntersection.agda` (60–120 lines): binary narrowing as a
funext-free one-liner, the `Fin n` form by induction; `narrow-shrinks`.
* Wire `EchoTruncation.agda` into `All.agda`; add the generic one-line
`fibre-blind` lemma (today only the `collapse : Bool → ⊤` instance exists).
* Done in #370: wire `EchoTruncation.agda` into `All.agda`. Open: add the
generic one-line `fibre-blind` lemma (today only the `collapse : Bool → ⊤` instance exists).
* An `EchoRecovery` audience record in the `EchoProvenance` pattern, over
fragment positions and the accepted set `T`.

Expand Down Expand Up @@ -676,7 +686,7 @@ refutation. Every row is OPEN in the ledger until the named prover runs.
| R13 | Review-queue completeness over the enumerated candidate fibre:
`hits_y ≡ 0 ⇔ ¬Echo`, `hits_y ≥ 2 ⇒ queued`, `exported ⇒ hits_y ≡ 1`;
needs decidable equality on a concrete `mval` | `EchoFiberCount.agda`,
`EchoTruncation.agda` (wire it) | Agda + Creusot queue predicate | one session
`EchoTruncation.agda` (wired in echo-types #370) | Agda + Creusot queue predicate | one session

| R14 | Fibre-blind functionals are constant on the fibre (generic one-line
`refl`); witness-reading confidences are not covered, so confidence ranks
Expand Down Expand Up @@ -856,14 +866,16 @@ runs the experiments and refuses to pass anything it did not run.
(propose/apply, create-with-id, `/full`, drift library, Document→Graph,
resolve kernel, fixed threshold, Recovery.v), vcl-ut (weaken, the RECOVER verb
with evidence slot and Residue payload, Epistemic 149, batching, schema builder), echo-types
(EchoPartialSection, EchoFibreIntersection, wire EchoTruncation),
(EchoPartialSection, EchoFibreIntersection, wire EchoTruncation: all done in #370),
tropical-types (HubCeiling, reachGrade, Isabelle status) | T17, T18 |
elsewhere | yes
| T20 | `verisimdb/formal/Recovery.v` draft with Justfile recipe and
Print-Assumptions whitelist; marked unbuilt if `coqc` absent | T06 |
verisimdb | yes
| T21 | `echo-types` drafts `EchoPartialSection.agda`, `EchoFibreIntersection.agda`;
`All.agda`/`Smoke.agda` wiring; marked "awaiting agda check" | T06 |
| T21 | Done in echo-types #370: `EchoPartialSection.agda` and
`EchoFibreIntersection.agda`, wired into `All.agda`/`Smoke.agda` and
Agda-checked (receipts in `PROOF-STATUS.adoc`). Remaining: the `Fin 8` Kleene
fixpoint, `fibre-blind` and `EchoRecovery` (section 5.3) | T06 |
echo-types | yes
| T22 | `src/interface/abi/Program.idr`: IR wire format, journal round-trip,
gate request/response; ledger row says whether idris2 ran | T14 | squeakwell
Expand Down Expand Up @@ -942,8 +954,8 @@ Issues to file once the MVP numbers exist (T19), one per line:
carrying the `Residue` payload); `Epistemic.idr` line 149
and Believes/Knows; batching; exported schema-JSON builder; register
squeakwell as a gate consumer.
* echo-types: `EchoPartialSection`; `EchoFibreIntersection`; wire
`EchoTruncation`; generic fibre-blind lemma; `EchoRecovery` record; check the
* echo-types: done in #370: `EchoPartialSection`, `EchoFibreIntersection`,
`EchoTruncation` wiring. Open: generic fibre-blind lemma; `EchoRecovery` record; check the
AGPL text in `LICENSES/` before any vendoring.
* tropical-types: `HubCeiling.lean`; `reachGrade` and `lsum_filter_mono`;
generic `weightedResidueMeasure`; reconcile the Isabelle status and add a CI
Expand Down
78 changes: 78 additions & 0 deletions tests/entrypoint_redaction_test.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
// SPDX-License-Identifier: MPL-2.0
//! The container entrypoint logs its run parameters before it execs the
//! binary. These tests run the real script under `sh` (the final `exec`
//! fails here because `/app/squeakwell` does not exist, which is fine: the
//! log lines are already written) and pin that no secret part of
//! `VERISIMDB_URL` reaches the log, and that a blank value is reported the
//! way `VeriSimDbClient::from_env_value` treats it.

use std::path::Path;
use std::process::Command;

fn entrypoint_log(url: Option<&str>) -> String {
let script = Path::new(env!("CARGO_MANIFEST_DIR")).join("container/entrypoint.sh");
let data = std::env::temp_dir();
let mut cmd = Command::new("sh");
cmd.arg(&script)
.env_clear()
.env("PATH", "/usr/bin:/bin")
.env("APP_DATA_DIR", &data);
if let Some(u) = url {
cmd.env("VERISIMDB_URL", u);
}
let out = cmd.output().expect("run sh");
String::from_utf8_lossy(&out.stdout).into_owned()
}

fn verisim_line(log: &str) -> String {
log.lines()
.find(|l| l.contains("VeriSimDB:"))
.expect("VeriSimDB line")
.to_owned()
}

#[test]
fn secrets_in_userinfo_path_query_and_fragment_are_not_logged() {
for url in [
"https://user:SECRET@db.example:8443/v1?token=SECRET#SECRET",
"https://db.example:8443/v1?token=a@SECRET",
"https://db.example:8443#a@SECRET",
] {
let line = verisim_line(&entrypoint_log(Some(url)));
assert!(!line.contains("SECRET"), "{url} leaked: {line}");
assert!(
line.contains("https://db.example:8443"),
"{url} lost the host: {line}"
);
}
}

#[test]
fn an_invalid_scheme_prefix_is_not_logged() {
for url in [
"host?token=SECRET://example",
"SECRET/x://y",
"://SECRET",
"9x://SECRET",
] {
let line = verisim_line(&entrypoint_log(Some(url)));
assert!(!line.contains("SECRET"), "{url} leaked: {line}");
assert!(line.contains("not logged"), "{url}: {line}");
}
}

#[test]
fn a_url_without_scheme_keeps_only_the_host() {
let line = verisim_line(&entrypoint_log(Some("user:SECRET@db.example/x?t=SECRET")));
assert!(!line.contains("SECRET"), "leaked: {line}");
assert!(line.contains("db.example"), "lost the host: {line}");
}

#[test]
fn unset_empty_and_whitespace_values_warn_about_the_fallback() {
assert!(verisim_line(&entrypoint_log(None)).contains("<unset>"));
for blank in ["", " ", "\t"] {
let line = verisim_line(&entrypoint_log(Some(blank)));
assert!(line.contains("<set but blank>"), "{blank:?}: {line}");
}
}
Loading