Track WP4 local-build-only Docker decision; propose Planetary Utilities host a registry as future enabler

[mzargham]

Context

WP4 ("three-remote architecture made real" — see roadmap at /Users/z/.claude/plans/i-want-to-continue-atomic-lobster.md) ships with a locked decision (decision #1) that Docker images are built locally from the Dockerfile in git rather than pulled from a Docker registry. This issue records that decision, its rationale, and the explicit proposal to revisit it once Planetary Utilities (the Flexo MMS host) offers a Docker registry service as part of Starforge.

The decision (as shipped in WP4)

compute.materialize and compute.reproduce both work by:

1. Reading the rtm:gitRef triple off an rtm:DockerImage node (Flexo or local TriG record).
2. git checkout-ing the recorded SHA in a temp worktree.
3. docker build against compute/Dockerfile at that SHA.
4. Comparing the resulting runtime digest to the recorded rtm:contentHash.

The image bytes never leave the local Docker daemon. Flexo stores only the witness (digest + hashes + git ref + container ID). The three remotes in the architecture are: code & recipe in git → RDF witness in Flexo → runnable container locally.

Why local-only for now

• No third-party dependency. A registry (DockerHub, GHCR, ACR, ECR) introduces a fourth party whose availability the demo would depend on for reproducibility. The reproducibility loop today depends only on git + Docker daemon + Flexo, all of which the operator already needs for the other parts of the demo.
• No registry credentials to manage. Avoids the credential-sprawl trap (separate registry login on top of the FLEXO_TOKEN already needed).
• The recipe is the source of truth. If docker build from <git ref> + Dockerfile + build context produces a different digest than what Flexo recorded, that's the signal — the difference is the bug. Pulling a pre-built image from a registry would mask the failure mode the demo is built to detect.
• It's the right default for an integration demo. Local-only honors the "stop being a mock-up" framing (roadmap §"Context") without adding infrastructure the demo can't itself produce.

Why this should change later (the proposal)

For production deployments and multi-machine reproducibility scenarios, a hosted registry is the right architecture:

• Cross-machine reproducibility. Two collaborators on different hardware can't docker build to byte-identical digests reliably (build cache, base-image drift, BuildKit version, host kernel). A registry lets one party build canonically and others verify by pull-and-compare instead of rebuild-and-compare.
• Faster verification loop. docker pull + digest check is seconds; docker build + digest check is minutes-to-hours depending on the build context.
• Audit-grade trust transfer. A signed image in a registry (sigstore / Cosign / Notary) carries authenticity beyond what rtm:contentHash alone can. Pairs with future-work item Integration ontology + named-graph runtime + closure rules + audit + Flexo & Docker provenance #1 (cryptographic envelopes & W3C VC).
• Decoupling the witness from the recipe. Today's design conflates "the recipe (Dockerfile in git) is reproducible" with "the bytes are pinned and shareable." A registry separates those concerns cleanly.

Proposal: coordinate with Planetary Utilities on hosting a Docker registry as part of Starforge

Planetary Utilities currently hosts the Flexo MMS instance at try-layer1.starforge.app. The demo's three-remote architecture would benefit substantially from a fourth Starforge service: a Docker registry sitting alongside Flexo, sharing authentication (the same FLEXO_TOKEN or an OAuth-scoped variant), and modeled as just another remote the demo can talk to.

Concrete asks for the conversation with Planetary Utilities:

1. Is a hosted registry on the Starforge roadmap? If yes, what's the timeline?
2. Auth model. Can it share the existing Flexo token, or does it need a separate credential? Strong preference for the former.
3. Per-org image namespacing. Mirroring Flexo's <org>/<repo> model would let the demo write to try-layer1.starforge.app/registry/adcs-demo/lifecycle:<tag> analogously.
4. Public-by-default for demo content. The ADCS demo's images are intentionally public so reviewers can pull and verify. A pull-without-auth path would lower the friction for JAXA-style reviews.
5. Storage retention policy. How long do images live? Demos benefit from "as long as the recorded rtm:contentHash resolves."

Acceptance criteria for revisiting the decision

When a Planetary Utilities (or other vendor-neutral) registry becomes available, the demo should:

• Add a --registry=<url> flag to compute.materialize and compute.reproduce (default unset → preserve current local-build behavior).
• Extend rtm:DockerImage with an optional rtm:registryRef property (literal IRI: <registry-host>/<image>@sha256:<digest>).
• On push: docker push <registry>/<image>:<tag> after a successful local build; record the registry URI on the image node.
• On pull: docker pull <registry>/<image>@<digest>; verify the pulled digest matches the recorded rtm:contentHash (still the source of truth).
• Backwards compatibility: pipelines run today without registry remain unchanged; the registry path is purely additive.
• Document the option in ARCHITECTURE.md as a future-state diagram alongside the local-build canonical flow.

Out of scope

• Pinning to DockerHub or GHCR as a stopgap. Avoid introducing a third-party dependency the demo doesn't need today.
• Self-hosting a private registry alongside Flexo on the same host. That's an infra step, not a demo concern.
• Image signing / sigstore / Cosign. Pairs with future-work item Integration ontology + named-graph runtime + closure rules + audit + Flexo & Docker provenance #1 (cryptographic envelopes); separate issue.

References

• Roadmap section: WP4 — Three-remote architecture made real (the big one), locked decision Integration ontology + named-graph runtime + closure rules + audit + Flexo & Docker provenance #1.
• Future-work item Integration ontology + named-graph runtime + closure rules + audit + Flexo & Docker provenance #1 (CLAUDE.md) — cryptographic envelopes & signatures.
• Future-work item Rename ValidateShapes step IRI to VerifyShapes (with Flexo + audit migration) #6 (CLAUDE.md) — production Flexo deployment.
• Sibling issues to read as a set: #8 (externally-hosted RIME services + cockpit) and #9 (reusable oracles + on-demand model checking in Starforge).