Kernlift

Validators and the release gate

Why every capability carries an executable check that asserts behaviour and wiring, and how the release gate decides which checks must pass.

Every capability in Kernlift carries a validator, an executable script that checks the feature works and is reachable. A release gate determines which of those checks must pass. The full list of scripts is in Validators.

One validator per capability

scripts/validate/*.ts holds one check per capability, each exposed as a validate:* script in package.json and chained into pnpm validate:all. A change is not finished until its validator exists and passes. Modules ship their own validators too, named in their manifest.

A validator reports each check it ran, most as a JSON report with the evidence for each, and exits non-zero when any check fails.

Behaviour and wiring, not file existence

A check that only asserts a file exists passes while the file sits unreferenced by any route. This repository has shipped that bug more than once, so validators assert behaviour and wiring. The usual shapes are:

ShapeWhat it proves
Run a repository or service with validate- prefixed fixtures against the real database, then remove themThe logic works on real tables, including failure paths
Render pages with the real marketing snapshot in both localesThe page shows real data in English and Chinese, with no hardcoded prices
Read routes, shells and dictionariesThe feature is reachable: routed, guarded, in the navigation and translated

Validators never fake a provider. Checks that need real credentials are part of external validation.

The release gate

Not every validator passes today. pnpm validate:all runs the whole chain and stops at the first failure, so it cannot serve as a gate while some checks are known to fail. CI runs pnpm validate:gate:

GroupHow the gate treats it
Validators not listed as known failuresMust pass; any failure is a regression
Validators in scripts/validate/known-failures.jsonRun too; one that starts passing must be removed from the list
validate:all, validate:gate, validate:storage-driversNot run by the gate. The storage driver check writes real objects to a bucket, so it runs only deliberately

Each known failure carries a written reason and what fixing it takes. The list may only shrink. A validator that starts failing must be fixed and must not be added to it. When you change something, record the pass and fail set before and after, and confirm you did not turn a passing check red.

External validation

Local validators check state machines and not-configured paths. Checks against real providers need sandbox or production credentials and run separately through pnpm validate:external. Without credentials those checks are reported as skipped, and EXTERNAL_VALIDATE_STRICT=true makes a skipped check fail. See Runtimes and database adapters.

Notable validators

ScriptProves
validate:auth-boundaryEvery API route is guarded or explicitly public with a reason
validate:migrationsBoth migration chains replay and match the schema
validate:billing-fulfilmentBilling notifies every enabled fulfilment plugin once, records failures and retries them from the scheduled round
validate:optional-agentThe web app is complete without the agent service, and its scheduled jobs run under one lock
validate:pluginsThe plugin registry rejects conflicts, disabling cascades, and every contributed entry reaches a route file
validate:store-boundaryNothing that sells Kernlift has come back into the template
validate:productsServer-side pricing, licence issue and revoke, bundle expansion
validate:registryFoundation plus modules reproduce the checkout; the foundation type-checks alone
validate:init-cliTokens never in argv, unlicensed refusal, upgrades keep local edits
validate:skillsSkills reference only real scripts, paths, routes and commands
validate:module-catalogModule pages render from the real snapshot with no price literals
validate:docsBilingual navigation and links resolve; module, Agent API, schema and environment references match source
validate:landing-blocksHome page counts are counted from the checkout

validate:products, validate:module-catalog, validate:docs and validate:landing-blocks belong to the store project; a project created from the template does not have them.

Files

scripts/validate
scripts/validate/gate.ts
scripts/validate/known-failures.json
scripts/validate/lint-budget.json
scripts/validate/change-path.ts
scripts/validate/render.ts
scripts/validate/fixtures.ts

change-path.ts resolves an OpenSpec change whether it is active or archived, so no validator hardcodes a change directory. render.ts server-renders a page so a check can assert on the rendered markup. fixtures.ts creates and removes the validate-prefixed rows a check needs, so it does not depend on seed data.

Next steps