Skip to content

docs(Dockerfile): record the frozen-graph gap where the gap is - #16

Merged
y1o1 merged 1 commit into
mainfrom
docs/record-frozen-graph-gap
Jul 27, 2026
Merged

docs(Dockerfile): record the frozen-graph gap where the gap is#16
y1o1 merged 1 commit into
mainfrom
docs/record-frozen-graph-gap

Conversation

@y1o1

@y1o1 y1o1 commented Jul 27, 2026

Copy link
Copy Markdown
Contributor

Summary

The builder stage's pnpm install resolves the generated instance's transitive
graph fresh, at image-build time. release.lock.frozen-graph forbids
exactly that: the published artifact's dependency graph was then never the graph
anything tested, and it can differ between two builds of one source.

--dplaax-module-ref now pins the git deps to a commit (enforced since #14),
but their own npm dependencies are still resolved in this stage.

This was tracked in a temporary publication runbook that is about to be
deleted
. A backlog entry outliving its file is how a known gap becomes an
unknown one — so it moves to the line it describes.

What the note says beyond "TODO"

  • Why it is not closable here. pnpm --lockfile-only in the gen stage just
    moves the fresh resolution a few lines earlier, still inside the release
    build. The fix generates the lockfile before the image build, proves it with
    --frozen-lockfile + the consumer smoke, then hands that exact instance and
    lockfile to docker build — a change to the publish workflow, not this stage.
  • Why it waits for the next version cut. That is when publish-images
    actually runs, so a mistake in the restructure surfaces immediately instead of
    sitting in a path nothing exercises. Landing it earlier would repeat
    provin.oss's quickstart §2f: documented, unexecuted, and wrong.

Test plan

Comment only — no build instruction changed. CI on this PR is the check.

The builder stage's `pnpm install` resolves the generated instance's transitive
graph fresh at image-build time — release.lock.frozen-graph forbids precisely
that, because the published artifact's dependency graph was then never the
graph anything tested and can differ between two builds of one source.

This was tracked in a temporary publication runbook that is about to be
deleted. A backlog entry outliving its file is how a known gap becomes an
unknown one, so it moves to the line it describes: a reader of this stage now
learns it from the stage.

The note also says why it is not closable here — moving the resolution a few
lines earlier into the gen stage keeps it inside the release build — and why
it waits for the next version cut: that is when publish-images actually runs,
so a mistake in the restructure surfaces immediately rather than sitting in a
path nothing exercises. Landing it earlier would repeat provin.oss's quickstart
§2f: documented, unexecuted, and wrong.
@y1o1
y1o1 merged commit e7b7417 into main Jul 27, 2026
3 checks passed
@y1o1
y1o1 deleted the docs/record-frozen-graph-gap branch July 27, 2026 07:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant