unidesk-code-queue-runner
152 lines
6.6 KiB
Markdown
152 lines
6.6 KiB
Markdown
# HWLAB DEV Gate Report Contract
|
|
|
|
This document defines the canonical DEV gate report format for
|
|
`pikasTech/HWLAB#31` and the DEV deploy apply report extension for
|
|
`pikasTech/HWLAB#33`. It is the handoff surface for the parallel workstreams
|
|
behind `#7/#9/#12/#17/#20/#21/#22/#23/#24/#25/#26`, so source-contract
|
|
evidence, local smoke, dry-run notes, real DEV prerequisites, and remaining
|
|
blockers stay in one place.
|
|
|
|
This contract is report-only. It does not authorize a real DEV or PROD
|
|
deployment.
|
|
|
|
## Report Lifecycle
|
|
|
|
Each committed DEV gate report must carry `reportLifecycle`:
|
|
|
|
- `state: "active"` means the report belongs to the current DEV gate surface.
|
|
Its `activeEndpoint` must be `http://74.48.78.17:16667`, its
|
|
`activeBrowserEndpoint` must be `http://74.48.78.17:16666`, and
|
|
`deprecatedEndpoint` must be `null`.
|
|
- `state: "historical"` means the report is retained only for evidence
|
|
provenance. It may name a deprecated endpoint such as
|
|
`http://74.48.78.17:6667`, but it must stay blocked/non-green and cannot be
|
|
consumed as active acceptance evidence.
|
|
- Active reports may preserve a legacy public endpoint only inside an explicit
|
|
`runtimeSmoke.legacyPublicEndpoint` object with `status: "deprecated"` and
|
|
`activeGreenEligible: false`.
|
|
- Active reports must not present `:6666` or `:6667` as a current public DEV
|
|
endpoint in endpoint, route, health, ingress, API, frontend, or browser
|
|
evidence. Internal k3s service/listen ports may still be `6667` when the
|
|
surrounding field names them as cluster-local service ports rather than
|
|
public endpoints.
|
|
- M3 DEV-LIVE remains narrower than report freshness: it requires
|
|
`res_boxsimu_1:DO1 -> hwlab-patch-panel -> res_boxsimu_2:DI1` in real DEV
|
|
plus operation, audit, and evidence identifiers. SOURCE, LOCAL, DRY-RUN,
|
|
fixture, and historical report evidence are support/diagnostics only.
|
|
- M5 DEV-LIVE cannot be inferred from public entrypoint reachability. Reports
|
|
must keep EDGE/ROUTE live, DB live/degraded, M3 hardware trusted loop,
|
|
M4 agent loop, and artifact/desired-state source status as separate layers.
|
|
If the only read-only evidence is `16666/16667` reachability, M5 must remain
|
|
blocked/non-green.
|
|
- Gate/report aggregators must cross-check DB, M3, M4, and M5 acceptance
|
|
against the corresponding source reports before showing `DEV-LIVE` or green
|
|
status. Frontend/browser revision facts, public route reachability, source
|
|
manifests, local smoke, dry-run output, and fixtures are non-promoting
|
|
support evidence for those layers.
|
|
|
|
## Files
|
|
|
|
- `reports/dev-gate/dev-gate-report.example.json`: machine-readable example.
|
|
- `reports/dev-gate/dev-deploy-report.json`: DEV deploy apply/preflight result.
|
|
- `scripts/validate-dev-gate-report.mjs`: local validator for the report shape.
|
|
- `scripts/report-lifecycle.mjs`: lightweight lifecycle helper for validating
|
|
one report or marking a replaced report historical/deprecated after endpoint
|
|
changes.
|
|
|
|
## Required Fields
|
|
|
|
Every report must include:
|
|
|
|
- `$schema`
|
|
- `$id`
|
|
- `reportVersion`
|
|
- `issue`
|
|
- `taskId`
|
|
- `commitId`
|
|
- `acceptanceLevel`
|
|
- `devOnly`
|
|
- `prodDisabled`
|
|
- `reportLifecycle`
|
|
- `sourceContract`
|
|
- `validationCommands`
|
|
- `localSmoke`
|
|
- `dryRun`
|
|
- `devPreconditions`
|
|
- `blockers`
|
|
|
|
## Field Rules
|
|
|
|
- `issue` is fixed to `pikasTech/HWLAB#31`.
|
|
- `devOnly` must be `true`.
|
|
- `prodDisabled` must be `true`.
|
|
- `commitId` must be a git SHA string.
|
|
- `taskId` and `acceptanceLevel` must be stable slugs, not free-form prose.
|
|
- `validationCommands` must record the exact commands used to validate the
|
|
report contract.
|
|
- `sourceContract.documents` should point at the frozen docs that define the
|
|
gate contract.
|
|
- `localSmoke`, `dryRun`, and `devPreconditions` should each summarize their
|
|
own state with a status, command list, evidence list, and short summary.
|
|
- `blockers` should list the remaining open blockers as machine-readable
|
|
objects.
|
|
- DB gate extensions may add redacted `db`, `cloudApiDb`, or check evidence
|
|
objects. These must include only env names, presence/missing status, Secret
|
|
reference names, and redacted readiness layers such as `configReady`,
|
|
`envInjected`, `connectionAttempted`, `connectionResult`, and
|
|
`liveConnected`. They must not include connection strings, passwords, tokens,
|
|
DB hostnames from the secret URL, or fixture output presented as live DB
|
|
evidence.
|
|
- DEV deploy apply reports must include
|
|
`devDeployApply.templateJobReplacementPolicy` and
|
|
`devDeployApply.templateJobReplacements`. These fields document the
|
|
DEV-only suspended template Job replacement allowlist, plus each planned or
|
|
executed replacement with namespace, Job name, old image, new image, and
|
|
result. The allowlist is limited to `hwlab-agent-worker-template` and
|
|
`hwlab-cli-template` in `hwlab-dev`; it must not generalize to ordinary Jobs
|
|
or non-Job resources.
|
|
|
|
## Validation
|
|
|
|
Run:
|
|
|
|
```sh
|
|
node --check scripts/validate-dev-gate-report.mjs
|
|
node scripts/validate-dev-gate-report.mjs
|
|
```
|
|
|
|
The validator scans `reports/dev-gate/*.json` by default. It only checks the
|
|
contract shape and the frozen report metadata; it does not run any DEV or PROD
|
|
deployment.
|
|
|
|
For M5 aggregator reports, the validator also verifies non-promotion
|
|
boundaries by reading the declared source report paths. DB acceptance must come
|
|
from redacted live DB readiness (`ready=true`, `connected=true`, and
|
|
`liveDbEvidence=true`); M3 must come from a real live operation with operation,
|
|
trace, audit, and evidence identifiers; M4 must come from the live preflight;
|
|
and M5 must remain blocked until DB, M3, M4, and the M5 live source report
|
|
each pass their own source checks. Frontend route, source, dry-run, and
|
|
fixture evidence may remain in the report, but it cannot promote those layers
|
|
to DEV-LIVE acceptance.
|
|
|
|
## Invalidate/Rebuild Workflow
|
|
|
|
When the public DEV endpoint mapping changes, do not rewrite historical
|
|
evidence strings. Preserve the old facts and mark any report that can no longer
|
|
represent the active gate as historical:
|
|
|
|
```sh
|
|
node --check scripts/report-lifecycle.mjs
|
|
node scripts/report-lifecycle.mjs invalidate reports/dev-gate/<old-report>.json \
|
|
--deprecated-endpoint http://74.48.78.17:6667 \
|
|
--reason "Public DEV endpoint moved to frontend :16666 and API/edge :16667" \
|
|
--out reports/dev-gate/historical/<old-report>-legacy-6667.json
|
|
node scripts/validate-dev-gate-report.mjs reports/dev-gate/historical/<old-report>-legacy-6667.json
|
|
```
|
|
|
|
Then regenerate the active report through its owning script so the active file
|
|
uses `http://74.48.78.17:16666` for browser/frontend evidence and
|
|
`http://74.48.78.17:16667` for API/edge/live evidence. Keep PR notes explicit:
|
|
which legacy reports were moved or marked historical, which active reports were
|
|
regenerated, and which current reports still need real DEV reruns.
|