pikasTech-HWLAB/docs/artifact-catalog.md

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 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 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/refresh-artifact-catalog.mjs	Refreshes source/artifact commit tags and records either blocked not_published state or proven publish digests.
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 the DEV registry target <registry>/<namespace>/<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 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 deploy/deploy.json, every service commitId, and the image tag. If it does not match the selected source ref, the DEV gate preflight reports artifact-source-commit as a blocker.

Refresh Workflow

When the source commit changes and no publish report proves digests, refresh the catalog and deploy manifests in blocked mode:

node scripts/refresh-artifact-catalog.mjs --target-ref origin/main --blocked

This updates deploy/deploy.json, deploy/artifact-catalog.dev.json, and deploy/k8s/base/workloads.yaml to the selected commit tag. It keeps artifactState: "contract-skeleton", ciPublished=false, registryVerified=false, and every service digest as not_published.

After a successful DEV artifact publish, record digests only from the publish report:

node scripts/refresh-artifact-catalog.mjs --target-ref origin/main --publish-report reports/dev-gate/dev-artifacts.json

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".

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/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 only local repository files and optional publish reports. They do not contact a registry, read secrets, build images, push images, deploy to DEV, or deploy to PROD.