# HWLAB Artifact Catalog Contract The artifact catalog is the DEV-only MVP contract for interpreting generated deployment artifacts. It pins which HWLAB service image, commit, profile, namespace, and health path GitOps render must inject into runtime manifests. `deploy/deploy.json` stays the human-authored runtime config truth source. This file is not automatically a CI publish record. It proves only the state it declares: - `artifactState: "contract-skeleton"` means the source/artifact commit and image tags are aligned, but `ciPublished=false`, `registryVerified=false`, and every digest must stay `not_published`. - `artifactState: "published"` is allowed only after a DEV publish report proves every required enabled service was published for the same source commit with a real `sha256:<64 hex>` registry digest. Services explicitly disabled in the service inventory must stay `not_published` and carry a disabled reason. Do not infer registry existence, digest values, or deployment from commit tags. Real publish evidence must come from the publishing workflow and registry metadata, then be copied into the catalog by the refresh command below. ## Scope - Environment: DEV only. - Namespace: `hwlab-dev`. - Public DEV endpoint: `http://74.48.78.17:16667`. - 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 identity truth for generated image, digest, commit, and publish provenance fields. | | `deploy/deploy.json` | Human-authored DEV runtime config such as service topology, env, health, profile, replicas, and endpoints. | | `scripts/g14-gitops-render.mjs` | Declares the Tekton primitive CI tasks and minimal guardrails that generate the G14 CI/CD control plane. | | `scripts/deploy-desired-state-plan.mjs` | Read-only planner/checker for catalog artifact identity, generated identity leakage into deploy config, and deploy/runtime config contracts. | | `scripts/refresh-artifact-catalog.mjs` | Previews artifact catalog identity by default; only G14 Tekton promotion uses `--write` to update `deploy/artifact-catalog.dev.json` before committing generated state to `G14-gitops`. | | `scripts/validate-artifact-catalog.mjs` | Local static validator for the catalog and deploy manifest skeleton. | | `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 top-level catalog commit ID. Short or full lowercase Git SHA is allowed. | | `image` | Must match the DEV registry target `//:`. The matching field must not be copied into `deploy/deploy.json`. | | `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` in a blocked skeleton catalog, or `published` only when the catalog was refreshed from a successful publish report. | | `sourceState` | Must be `source-present` for MVP services with repository source, or `intentionally-disabled` for zero-replica services excluded from MVP publication. | | `artifactRequired` | Must match `serviceInventory.requiredServiceIds`; only required services need publish digests. | | `artifactScope` | `required` for services that must be published, or `disabled` with a `notPublishedReason`. | | `digest` | Must be `not_published` in the skeleton catalog; it may be a registry `sha256:<64 hex>` digest only after publish evidence exists. | The catalog `commitId` is the artifact source commit, not proof that a registry artifact exists. It must match every service `commitId` and the image tag. If a later target ref changes artifact build inputs after the publish source, the DEV gate preflight may reopen `artifact-source-commit` even when the base-image blocker is already closed. ## Desired-State Plan Use the read-only planner before refreshing or reviewing deploy desired-state: ```sh node scripts/deploy-desired-state-plan.mjs --plan --pretty node scripts/deploy-desired-state-plan.mjs --check node scripts/deploy-desired-state-plan.mjs --target-ref origin/G14 --pretty node scripts/deploy-desired-state-plan.mjs --target-tag --pretty node scripts/deploy-desired-state-plan.mjs --promotion-commit --check ``` The planner treats `deploy/deploy.json` as human-authored runtime config, `deploy/artifact-catalog.dev.json` as artifact identity truth, and `deploy/k8s/base/workloads.yaml` as a runtime template. It reports catalog service `commitId`/`image`/`imageTag`, blocks generated artifact identity that leaks into `deploy.json`, and leaves workload image/env mirror values to GitOps render because render overwrites them from the catalog. `--check` exits non-zero when the source files are missing or invalid, generated artifact identity leaks into `deploy.json`, an explicit target tag is invalid or mutable, or catalog artifact identity does not match the requested target. The source branch catalog is only a seed contract; published artifact identity is stored on `G14-gitops`. The optional report snapshot is contextual evidence only and is not an authoritative desired-state source. For PR review or CI/CD promotion handoff, use `--promotion-commit --check`. That mode is stricter than a `--target-ref` plan: the catalog top-level commit and each catalog service commit/image tag must align with the promotion commit/tag. A stale but internally consistent catalog is a blocker in promotion mode because applying it would roll DEV back. The planner does not prove registry existence, publish success, DEV apply, or M3 DEV-LIVE. Only real DEV observation of `res_boxsimu_1:DO1 -> hwlab-patch-panel -> res_boxsimu_2:DI1` with operation, trace, audit, and evidence records can be called M3 DEV-LIVE. ## Refresh Boundary Human source work must not refresh artifact identity into the source branch. To preview what a blocked catalog would look like, use read-only mode: ```sh node scripts/refresh-artifact-catalog.mjs --target-ref HEAD --blocked --no-write node scripts/deploy-desired-state-plan.mjs --check ``` This prints the planned catalog state and does not modify any repository file. Blocked skeleton refresh is intentionally preview-only. After a successful DEV artifact publish, only the G14 Tekton promotion path may record digests from the publish report: ```sh node scripts/refresh-artifact-catalog.mjs --target-ref --publish-report /workspace/source/dev-artifacts.json --write ``` The publish-report mode refuses to update the catalog unless the report says `artifactPublish.status="published"`, covers every frozen service in the v2 publish plan, matches the target source commit, and contains a valid `sha256` digest for each required service. Disabled services remain `skeleton-only` with `digest: "not_published"`. The written catalog is committed only to `G14-gitops`; `deploy/deploy.json` remains human-authored source truth. ## Relationship To `deploy/deploy.json` `deploy/deploy.json` remains the human-authored deploy manifest. The artifact catalog does not replace it and must not be consumed as proof that a release was built. GitOps render combines human config from `deploy.json` with generated artifact identity from the catalog; artifact identity must not be copied back into `deploy.json`. 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: ```sh 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:`. 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: ```sh node --check scripts/deploy-desired-state-plan.mjs node --check scripts/src/deploy-desired-state-plan.mjs node --test scripts/deploy-desired-state-plan.test.mjs node scripts/deploy-desired-state-plan.mjs --check node --check scripts/validate-artifact-catalog.mjs node --check scripts/refresh-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 and refresh command read local repository files and optional publish reports; refresh is read-only unless `--write` is explicitly supplied. The desired-state planner has the same read-only boundary. These commands do not contact a registry, read secrets, build images, push images, deploy to DEV, or deploy to PROD.