Test-support bindings and observed readiness#

The repository-local entry tooling/onboarding/test-support.mts exports inspectTestSupport, verifyTestSupport and their TypeScript contracts. The support-* files are private implementation. This helper supplies the support seam for per-application onboarding recovery; it does not change execution-core APIs, TaskPacket, bridge requests or catalog frontmatter.

Review metadata#

Supply a SupportRequest containing selected application target, host/support revision, nonsecret environment, the current public Catalog, and approved scenarios. Each scenario names its testId, exact catalog revision and bounded bindings. Map all required authentication, fixtures, lifecycle, mid-scenario actions, environment/access, lookup and cleanup needs explicitly. Omit categories that the scenario does not need; an empty binding list is rejected. Limits are 100 scenarios, 50 bindings per scenario and 512 KiB of request metadata.

A binding names an opaque id, kind, and nonsecret mechanism pointer to the host-retained authorized API/CLI/tool instructions. Lifecycle bindings name an actual { phase, id } hook; function hooks must have their own callable export in SupportHost.functions. Authentication hook references must use beforeEach. Run/section hooks manage resources; they cannot authenticate a fresh browser attempt. Instruction hooks retain the selected runtime's existing instruction semantics.

SupportHost contains the selected public Runtime, already-approved module functions, the available mechanisms, and an authorized probe(packet, binding). inspectTestSupport(request, host, observations?) is synchronous and read-only: it invokes no callbacks and imports no modules. Host import/execution probes need explicit verification approval before loading arbitrary project modules. Lifecycle registration, capability declarations and catalog validity yield pending, never observed-ready. Missing mechanisms/exports yield missing; changed scenario revisions and unsupported isolation yield blocked.

The versioned SHA-256 review ID binds application/environment/revision, approved scenario selection/order and bindings, selected execution order, runtime capabilities, mechanisms and exported function names. Identity normalizes persisted JSON meaning: object-key order and omitted optional undefined fields are equivalent; array order stays meaningful. Non-finite numbers are rejected. Selected execution inputs include prerequisites, steps, expectations, executor, instructions, evidence settings, retries, destinations and the catalog-resolved ancestry/hook scope. Descriptive titles, file names, tags/components/levels and unrelated catalog entries do not discard selected observations. Changing ordering that changes the selected execution sequence still invalidates them.

Change the host revision whenever implementation, access, credential validity or runtime environment changes. Hosts whose custom hooks/probes depend on otherwise descriptive metadata must include those assumptions in the host revision or binding scope. This is an evidence scope fingerprint, not a lock or automatic detector of external changes. Trusted host observations can be reloaded for review; the helper cannot authenticate forged evidence or arbitrary caller-supplied identifiers. Earlier raw-JSON review identities require fresh approval and observation once when migrating to this identity version; they are not automatically upgraded.

Approved disposable verification#

verifyTestSupport(request, host, approval) requires the current reviewId, disposable: true, and a nonsecret evidence pointer. Each customIntegration needs matching earlier consent and concrete finalApproval pointers. These values record human decisions; hosts obtain the decisions before invoking the helper. This helper rejects an environment named production; the trusted host must also ensure the selected endpoints and credentials actually address the approved disposable environment. It cannot infer production from an alias.

Verification runs only eligible scenarios through the existing executeCatalog with one disposable attempt per scenario, overriding application retry limits inside the probe harness only. Normal application retry settings remain unchanged. It preserves lifecycle order, failure policy, null-context cleanup, browser-runtime selection and context freshness attestation. Application scenario steps are replaced by support probes, so this result establishes support readiness only. Normal execution still needs its own scenario acceptance evidence. The selected catalog's evidence requirements remain enforced; unavailable required proof conservatively blocks support verification rather than synthesizing it.

Implement the probe in the host adapter that can exercise the actual authorized worker API, CLI or tool. A coordinator's direct access or local HookContext.shared is insufficient to establish worker access. Use only existing TaskPacket fields for run/attempt/test identity and the exact session; there is no generic bridge invokeFunction request. For an authentication probe, check the account in that session after beforeEach; never check a globally selected page or section login. For fixture lookup, resolve seeded disposable data by the agreed run/attempt/test key from the worker mechanism. For an action, perform the agreed disposable operation at the required scenario point and check its effect. A boolean declaration or success from a different context is not a probe.

The helper supplies a cloned packet/binding to each probe. Return true only from observed checks; unexpected JavaScript return values fail closed and their content is excluded from records; keep response bodies and credentials inside the adapter. Cleanup and after-hook probes run after runner cleanup/context closure, with the original identifiers for lookup; the session is then an identity pointer, not a live browser handle. Verify disposal through the authorized API/CLI/tool. Setup, action, lookup, authentication, hook, context-close and cleanup failures block readiness. Run/section failures conservatively block the reviewed batch.

Output contains a review and minimal observations: review/test/binding IDs, run/attempt/context IDs, passed, and the approval evidence pointer. No response body, session handle, shared fixture data or error message is exported. Inputs and evidence pointers must already be nonsecret; these helpers do not sanitize arbitrary caller strings. Persist only reviewed metadata in the existing onboarding scratchpad and preserve private logs within authorized host storage.

Offer ready approved scenarios for normal execution, retaining blocked work and specific missing prerequisites. API/CLI scenarios can remain available when browser contexts are unsupported. Distinguish support/setup failures from application bugs; fixture tests and Chromium adapter observations do not certify unavailable native agent runtimes. This task neither provisions services nor authorizes production mutation, releases, deployment or merges.

Acceptance fixtures#

tooling/onboarding/test-support.test.mts uses the supported public entry with an explicitly loaded temporary host module, disposable loopback API and real isolated Chromium cookie contexts. It covers declared/pending support, worker action/lookup, exact-context login, unsupported isolation with API availability, missing exports, stale scope, partial failures/null-context cleanup, consent and secret-free errors. support-freshness.test.mts additionally covers canonical metadata identity, descriptive/unrelated changes, relevant scope invalidation, unexpected probe values and suppression of inherited application retries. The repository's full verification command includes these direct checks along with maintained automated browser journeys. Source-bound T3 smoke evidence complements these checks; screenshots alone cannot prove worker access or consent enforcement.