generated from coulomb/repo-seed
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.
This commit is contained in:
83
INTENT.md
83
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.**
|
||||
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.**
|
||||
Reference in New Issue
Block a user