HWLAB Code Queue
4.5 KiB
HWLAB Artifact Catalog Contract
The artifact catalog is the DEV-only MVP contract for interpreting deployment artifacts. It pins which HWLAB service image, commit, profile, namespace, and health path a static deploy manifest is claiming for acceptance review.
This file is not a CI publish record. It does not prove that an image exists in a registry, that a digest was produced, or that a deployment happened. Real CI publish evidence must come from the future publishing workflow and registry metadata. Until that exists, the catalog can only validate that the local skeleton files agree with each other and do not drift into PROD.
Scope
- Environment: DEV only.
- Namespace:
hwlab-dev. - Public DEV endpoint:
http://74.48.78.17:6667. - Profile:
dev. - Health path:
/health/live. - Artifact state: contract skeleton only.
- PROD deployment, PROD smoke, secret reads, force push, real image publish, and UniDesk runtime substitution are forbidden.
Files
| File | Role |
|---|---|
deploy/artifact-catalog.dev.json |
Machine-readable DEV artifact catalog sample and static source of truth for the skeleton. |
deploy/deploy.json |
DEV deploy manifest skeleton that the catalog explains. |
CI.json |
Lightweight command and forbidden-action skeleton. |
scripts/validate-artifact-catalog.mjs |
Local static validator for the catalog, deploy manifest, and CI forbidden list. |
scripts/preflight-dev-base-image.mjs |
Local DEV builder base-image preflight for future artifact publish. |
docs/dev-base-image-preflight.md |
Operator contract for interpreting preflight readiness and blockers. |
Pin Rules
Every service entry in deploy/artifact-catalog.dev.json must satisfy these
rules:
| Field | Rule |
|---|---|
serviceId |
Must be one of the frozen HWLAB service IDs and must appear exactly once. |
commitId |
Must match the catalog and deploy/deploy.json commit ID. Short or full lowercase Git SHA is allowed. |
image |
Must match ghcr.io/pikastech/<serviceId>:<imageTag> and the matching deploy/deploy.json service image. |
imageTag |
Must be the first seven characters of commitId. Mutable tags such as latest, dev, or main are forbidden. |
profile |
Must be dev. |
namespace |
Must be hwlab-dev. |
healthPath |
Must be /health/live and match the DEV health contract. |
publishState |
Must be skeleton-only until real CI publish evidence exists. |
digest |
Must be not_published in the skeleton catalog; CI must replace this with a registry digest only after publishing. |
The current skeleton commit and tag values intentionally mirror
deploy/deploy.json. They are traceability placeholders for static acceptance
work, not a statement that GHCR already contains those images.
Relationship To deploy/deploy.json
deploy/deploy.json remains the deploy manifest skeleton. The artifact catalog
does not replace it and must not be consumed as proof that a release was built.
The catalog explains the artifact identity that deploy/deploy.json currently
claims, then adds stricter DEV-only rules around commit pinning, image tags,
health paths, forbidden profiles, and publish state.
If a future CI workflow publishes real images, it should update or generate a publish result that includes registry digests and provenance. That publish result may be compared with this contract, but it must not be inferred from this contract.
DEV Builder Preflight
Before a future DEV artifact publish attempts to build or publish service images, run:
npm run --silent dev-base-image:preflight
The preflight is local-only and checks for an approved builder base image through
HWLAB_DEV_BASE_IMAGE, a local node:20-* Docker image, or an explicit local
HWLAB dev base tag such as hwlab-dev-base:<tag>. It prints the image source,
local tag, image ID, publish usability, blockers, next steps, and
machine-readable preload/provision commands. The recommended source is
node:20-bookworm-slim; the recommended HWLAB-local tag is
127.0.0.1:5000/hwlab/hwlab-dev-base:node20-bookworm-slim. A blocked result
means artifact publish must stop and must not be reported as a successful
publish.
Validation
Run the local static validator:
node --check scripts/validate-artifact-catalog.mjs
node --check scripts/preflight-dev-base-image.mjs
node --check scripts/src/dev-base-image-preflight.mjs
node scripts/validate-artifact-catalog.mjs
The validator reads only local repository files. It does not contact a registry, read secrets, build images, push images, deploy to DEV, or deploy to PROD.