From 9be1c3028d20b2936e66ea623327cbdea05325dc Mon Sep 17 00:00:00 2001 From: tegwick Date: Tue, 23 Jun 2026 21:23:39 +0200 Subject: [PATCH] Clarify INTENT.md: ecosystem validation and one-way sand-boxer dependency Reframe wise-validator as cross-repo use-case stabilization, document one-way consumption of sand-boxer, and align maturity target with dormant-path rot detection across the Coulomb ecosystem. --- INTENT.md | 83 ++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 61 insertions(+), 22 deletions(-) diff --git a/INTENT.md b/INTENT.md index fb153ca..1a1c9c2 100644 --- a/INTENT.md +++ b/INTENT.md @@ -1,15 +1,16 @@ --- domain: infotech repo: wise-validator -updated: "2026-06-22" +updated: "2026-06-23" --- # INTENT -> wise-validator is the Coulomb **meta-framework for validation** — e2e test -> orchestration, health checks, and structured pass/fail reporting — while -> **consuming** sand-boxer for isolated execution environments. This file is -> preliminary; refine as the validation boundary is implemented. +> wise-validator is the Coulomb **meta-framework for validation** — cross-repo, +> use-case-driven end-to-end proof that declared behaviors still work — while +> **consuming** sand-boxer for isolated execution environments. sand-boxer is +> self-sustained and does **not** depend on wise-validator; the dependency runs +> one way only. --- @@ -36,6 +37,29 @@ requested from sand-boxer, not provisioned here. sand-boxer establishes the box. wise-validator **proves what runs inside it.** +### Ecosystem use-case stabilization + +Coulomb spans many repos and use cases — not all exercised continuously. Without +periodic proof, integrations **degenerate silently**: APIs drift, compose stacks +break, cross-repo assumptions fail, and nobody notices until a dormant path is +needed again. + +wise-validator exists so the **ecosystem as a whole** can keep use-case definitions +honest: + +- **Use-case contracts** per repo (e.g. `e2e/e2e.yml` or successor definitions) + declare what “still works” means +- **Cross-repo runs** exercise real stacks on isolated hosts via sand-boxer — + not laptop-only pytest in isolation +- **Scheduled or on-demand validation** (activity-core, CI, operators) catches + regression before production or agent work depends on a stale use case +- **Structured results** (pass/fail, health outcomes, duration) feed State Hub + and automation so degradation is visible, not anecdotal + +This is infrastructure for **Coulomb-wide confidence**, not a feature sand-boxer +needs to function. sand-boxer provisions venues; wise-validator audits whether +declared use cases still hold across that venue catalog. + --- ## The governing principle @@ -64,25 +88,29 @@ deployer on Railiance01. ## Coulomb sibling boundaries -### sand-boxer — sandbox establishment +### sand-boxer — sandbox establishment (upstream; not a dependency of sand-boxer) **sand-boxer owns:** Profiles, extensions, provision/teardown, placement, -lifecycle registration. +lifecycle registration, host telemetry. It is **self-sustained** — CLI, canary +self-deploy, and lifecycle events work without wise-validator. **wise-validator owns:** Requesting `profile.compose-e2e` (or successors), running validation **inside** the returned environment, releasing the sandbox when the validation workflow completes (via sand-boxer `destroy`). +**Dependency direction:** wise-validator → sand-boxer only. sand-boxer never +calls, waits for, or requires wise-validator. + ```text -wise-validator sand-boxer -────────────── ────────── -resolve e2e.yml + validation profile → POST /v1/sandboxes +wise-validator sand-boxer (independent service) +────────────── ────────────────────────────── +resolve use-case contract → create / destroy (optional client) health-wait + test_command in env ← sandbox_id + reachability -POST result to State Hub / CI → destroy (per cleanup policy) +POST validation result to State Hub (sand-boxer emits lifecycle only) ``` -sand-boxer smoke tests may prove an environment exists; wise-validator owns -whether that environment **passes validation**. +sand-boxer proves an environment **exists and is reachable** (`ready`). +wise-validator proves declared **use cases still pass** inside it. ### glas-harness — agent harness @@ -215,7 +243,9 @@ Structured run results (successor to `RunResult`): | Certs | `ops-warden` | Embedding `sandbox.provision()` in wise-validator recreates the monolith -sand-boxer is splitting apart. +sand-boxer is splitting apart. Likewise, sand-boxer must not embed validation +logic to “complete” e2e — that would couple establishment to a sibling that +should remain optional. --- @@ -259,7 +289,11 @@ glas-harness may trigger runs, wise-validator executes them deterministically as ## Design principles - **Validation meta-framework, not monolith** — one API; extensions for probes and reporters -- **sand-boxer for environments** — never embed provisioners or host SSH lifecycle +- **sand-boxer for environments** — never embed provisioners or host SSH lifecycle; + sand-boxer remains self-sustained without this repo +- **Use-case contracts, ecosystem scope** — validation targets declared cross-repo + behaviors, not ad-hoc per-session agent checks +- **Detect dormant-path rot** — runs matter even when a use case is not in daily use - **Contract in repo, orchestration in platform** — `e2e/e2e.yml` stays opt-in per repo - **Health before tests** — explicit polling; fail fast with actionable errors - **Cleanup is policy** — honor `cleanup: always | on_success | never`; default teardown via sand-boxer @@ -310,19 +344,24 @@ Track in `docs/integrations/sand-boxer.md` (wise-validator or sand-boxer repo). 7. **`the-custodian` shim** — `make e2e` delegates to wise-validator + sand-boxer 8. **Runbook** — operator docs successor to e2e-framework RUNBOOK -Planned sand-boxer follow-on: **SAND-WP-0003** (wise-validator extraction). +Implementation tracked in **SAND-WP-0003** (wise-validator extraction; workplan +in `sand-boxer` coordinates migration from `e2e-framework`). sand-boxer +SAND-WP-0002 and SAND-WP-0008 are complete independently of that work. --- ## Maturity target -A mature wise-validator is Coulomb's **default proof layer**: +A mature wise-validator is Coulomb's **default proof layer for declared use cases**: -- Any repo with `e2e/` can run cross-host validation without `the-custodian` checkout -- activity-core fires validation after deployments or agent work +- Any repo with a validation contract (`e2e/` or successor) can run cross-host + proof without `the-custodian` checkout +- activity-core schedules validation so **infrequently used use cases** do not rot + undetected - CI and glas-harness share the same validation API and result schema - Health probes reuse the same extension model as full e2e runs -- sand-boxer teardown is reliable because wise-validator always releases environments +- Environments are released via sand-boxer `destroy` when validation completes -sand-boxer establishes the box. glas-harness runs the agent. snuggle-inventor -writes the code. **wise-validator proves it works.** \ No newline at end of file +sand-boxer establishes the box — on its own, without wise-validator. glas-harness +runs the agent. snuggle-inventor writes the code. **wise-validator proves declared +use cases still work across the ecosystem.** \ No newline at end of file