base-image preflight: the Dockerfile parser's divergences from Docker all fail open

[swinney]

Context

_instruction_text / _final_stage_base in src/cli/managers/base_image_preflight.py decide
which base image a service template's final stage runs on. That decision gates archi create:
a template whose final stage is not a probeable a2rchi base must be refused before
remove_existing_deployment() (src/cli/cli_main.py:294) destroys the operator's deployment.

The parser is a line-oriented approximation of Dockerfile syntax. Automated review of PR #387
found six distinct inputs where it diverges from Docker, across two rounds:

Input	Divergence
RUN \ then <<TAG	heredoc opened on a continuation, delimiter not recorded
TAG as terminator	line.strip() closed <<TAG early
FROM ...	^FROM missed an indented instruction
RUN echo "example <<TAG here"	quoted marker over-read as an opener
RUN << TAG, RUN 3<<TAG, RUN <<- TAG	opener pattern only matched the tight form
# escape= + backtick continuation	continuation character hard-coded to \

Every one failed the same direction: open. The template read as covered on an earlier
a2rchi builder stage while its real final stage was third-party, so the deploy proceeded
without probing the image that actually ships. All six are fixed and guarded on #387
(1e73e727, 8d7eb9c0).

The problem this issue tracks

The individual fixes are not the concern — they are landed and tested. The concern is that
each round of review found more, and none was the last one. The remaining surface includes
at least: ARG-substituted references (FROM $BASE), COPY --from provenance, quoting cases
the widened opener pattern still misreads, and opener forms nobody has enumerated.

#387 added a partial mitigation: an unterminated heredoc now fails closed
(_instruction_text returns None → template reported uncoverable → refusal). That covers
over-reads — the parser seeing an opener that is not one. It does not cover under-reads,
where the parser misses a real opener entirely and scans the payload as instructions. Both of
round 2's findings were under-reads.

What to decide

Pick one; this needs a human call, which is why it is not on #387.

1. Differential-test the parser against BuildKit. Generate Dockerfiles, compare
   _final_stage_base against what docker build --print/BuildKit's parser reports as the
   final stage. Turns "we found six" into "we searched". Costs a Docker dependency in CI —
   note the gate is pytest tests/unit/ only, so this likely belongs in a separate job.
2. Property-test the invariant instead of the syntax. Hypothesis over generated templates
   asserting the one property that matters: if the real final stage is not an a2rchi base,
   _final_stage_base must not report one. No Docker dependency, but the generator encodes
   the same assumptions the parser does.
3. Delegate parsing. Use a real Dockerfile parser (e.g. dockerfile-parse) instead of
   regexes. Note CLAUDE.md says avoid third-party dependencies unless strictly necessary,
   and this one would sit on a deploy-critical path.
4. Accept and bound it. Decide the current fail-closed rule plus the six guards is enough,
   and record that decision in the module docstring so the next reviewer does not re-derive it.

Acceptance

• A recorded decision among the four, with the reasoning, in this issue.
• If 1–3: implemented, with the six known inputs above kept as explicit regression tests
  (they are already in tests/unit/test_base_image_preflight.py; do not delete them).
• If 4: the bound stated in _final_stage_base's docstring in the module's existing
  "state the bound rather than imply totality" idiom.

Pointers

• Parser: src/cli/managers/base_image_preflight.py — _instruction_text,
  _heredoc_delimiters, _escape_char, _final_stage_base, _FROM_STAGE_RE, _HEREDOC_RE.
• Existing guards: tests/unit/test_base_image_preflight.py, the tests named in the table above.
• Ordering contract this protects: archi create --force destroys the existing deployment before validating secrets #287; the module's governing invariant is in its
  opening docstring — establish, refuse, or say out loud that it could not tell.
• Round logs with the reproductions: fix(#382): require a service template's final-stage base to be one the preflight can probe #387 rounds 1 and 2.

[swinney]

Three more confirmed instances (2026-08-30, after PR #387's round bound)

A Codex pass on 8d7eb9c0 landed after the nightly reviewer's two-round bound closed. All
three were verified against that commit and are not fixed on #387. They raise the count
from six to nine, which is the argument for this issue rather than a tenth patch.

7. Alias resolution reads a whole-file map, so it resolves through a later alias.
src/cli/managers/base_image_preflight.py — _final_stage_base.

FROM external AS shipped
FROM ghcr.io/fasrc/a2rchi-python-base@sha256:aaaa... AS external
FROM shipped

_final_stage_base -> the a2rchi base. Docker -> the external image literally named
external, because at stage 1 no stage named external exists yet. alias_map is built from
all stages before resolution begins. Fix shape: bind each alias to the stages preceding it.

8. A second heredoc opened on a continuation of an instruction that already opened one.
src/cli/managers/base_image_preflight.py — _instruction_text.

FROM docker.io/library/debian:12
RUN <<ONE \
  <<TWO
ONE
FROM ghcr.io/fasrc/a2rchi-python-base@sha256:aaaa...
TWO

RUN <<ONE \ sets pending, so the if not pending guard leaves continued False and the
continuation line is swallowed as ONE's first payload line — TWO is never recorded. #387's
continuation-opener fix covers the case where the instruction opened no heredoc and misses
this one. Fix shape: join continuations before scanning, rather than scanning line by line.

9. The test-side pin guard reads a narrower set of lines than the parser it guards.
tests/unit/test_base_image_preflight.py — _FROM_GHCR (^FROM (ghcr\.io/fasrc/\S+)).

#387 made _FROM_STAGE_RE case-insensitive, flag-tolerant and indent-tolerant. _FROM_GHCR
did not move, so a template with an uppercase digest-pinned builder and a lowercase mutable
final from passes test_all_templates_share_one_pin_state while _final_stage_base reports
the mutable reference that actually ships.

This one is not the same class as the other eight — it is two regexes drifting apart, and
it is the smallest and most self-contained of the three. Worth fixing on its own regardless of
which option this issue lands on; having the guard read through the production parser (rather
than re-syncing a second regex) is what stops the drift recurring.

Threads with the full reproductions: #387, the three replies dated 2026-08-30.