Solidify the design basis

[omry]

Resolves the decided findings from round one of a deep design review over
docs/PORTABLE_TOOL_DEFINITION_DESIGN.md.

The review produced 17 findings: 1 High, 11 Medium, 5 Low. This PR lands 11 of
them. The other 6 describe acquisition budgets, mirror-mismatch durability,
probe failure behavior, the pre-acquisition recheck, and validation-evidence
custody — all surface that PTD-13 onward will build, and all better answered
next to the code that implements them.

Same shape as #93: a design amendment as its own slice rather than an amend of
#81, which would rewrite 13 approved commits and discard their review evidence.

Decisions

Binding inference precedence. The design named inference three times and
defined it nowhere, while introducing a contract-level default that
REPOSITORY_DESIGN.md does not have. The two documents disagreed for any
contract advertising more than one binding. Inference now resolves in a stated
order — explicit request, contract default, the baseline's active-provider
match, sole advertised binding — with the default deliberately outranking the
provider match, because the resolved binding is part of lock and cache identity
and should not depend on ambient build state.

Probes are not a semantic key. As written the key could not function: rule 9
fails a conflict only when two contributions share a key with different values,
and probe identity was the complete canonical value, so a conflict was
unreachable. The alternative reading — identity by executable path — would fail
an ordinary definition that probes one executable two ways.

The limits claim is scoped to size. It asserted no upper limit on a
definition "as a whole" while the integration contract rejects a definition
whose required Cartesian coverage exceeds a core cap. Both hold of different
things, and the size decision is now indexed in the Decision Summary with the
trigger that would make an aggregate ceiling answerable.

Corrections

• version-selection preconditions delegated to REPOSITORY_DESIGN.md explicitly
  rather than left absent;
• rules assigned to publication name the actor that performs them today;
• Decision 10 no longer attributes mirror declaration to artifact records;
• target parameter narrowing rules added to the static validation list;
• atomic installation names its procedure;
• vestigial size authority clause dropped;
• the aggregate definition digest described in the past tense;
• the migration list defers delivery status to the implementation plan;
• frontmatter updated stamped, which Define no aggregate ceiling on portable tool definitions #93 left at the prior date.

Scope

Design document only. No code changes, and every decision matches what the
approved slices already implement — including probe deduplication in
records_compose.go and the four target narrowing rules in
validateTargetAgainstContractV1, both of which enforce the amended text today.

Two findings already cost implementation time before this review: the revision
pin precondition and prerelease exclusion were both found during PTD-09 review
by reading the baseline rather than this design, which is what the delegation
note is there to prevent.

Full review output is not committed; it lives under the ignored temp/ tree.

---

Also: blueprint environment model verified against the implementation

A separate review loop verified
docs/BLUEPRINT_ENVIRONMENT_MODEL.md
against the code (swe:deep-design-review-loop, 3 rounds, exited clean).
Thirteen enumerable contracts match, several near-verbatim. One high finding:
Runtime Mount Integrity checks 2 and 3 are specified but were never built —
only the reserved-destination check exists, at blueprint validation rather than
the documented pre-container enforcement point.

Landed here per the accepted disposition:

• the section now states the true enforcement status at all three sites that
  stated the rule, keeping the full specification as design intent;
• new review sidecar
  docs/.review/BLUEPRINT_ENVIRONMENT_MODEL.md
  carries the standing decision and a clean attestation over the reviewed
  bytes;
• new P1 backlog entry "Implement runtime mount integrity checks 2 and 3"
  refers back to the sidecar.

Docs only; no code changes.

[omry]

@codex, review docs/BLUEPRINT_ENVIRONMENT_MODEL.md as a whole at 57bdcdd — the complete document, not only this PR's diff.

This is the normative blueprint environment, workload, application, provider contribution, lifecycle, and Docker rendering model, and it is the design basis the portable-tool work refines. It is largely implemented; a local design-versus-implementation review found the enumerable contracts implemented nearly verbatim, with one gap now stated in the document itself (Runtime Mount Integrity checks 2 and 3 are specified but not yet built — see docs/.review/BLUEPRINT_ENVIRONMENT_MODEL.md and the BACKLOG entry).

Please focus on the design as a design: internal contradictions, claims the mechanisms cannot support, rules an implementer would have to invent, unstated failure directions at trust boundaries, and present-tense claims that do not hold at this revision. Prose style is out of scope. The Proposed Embedded Built-In Tools section marks itself as proposed and becomes normative only when that implementation lands.

[chatgpt-codex-connector]

💡 Codex Review

reploy/docs/BLUEPRINT_ENVIRONMENT_MODEL.md

Lines 1665 to 1667 in 57bdcdd

	During `reploy build`, final-image validation applies the portable-access rule
	to every runtime-exposed output and validates every compiled mount destination
	against the exact resulting image. A changed runtime plan makes the build stale.

Remove the false final-image mount-validation claim

At this revision, this present-tense claim contradicts the Runtime Mount Integrity section at lines 2167–2174, which correctly states that image-side destination inspection and protected-runtime-set comparison are not implemented. An implementer reading this paragraph would conclude that reploy build already enforces those checks and records a validated mount plan, potentially relying on protection that does not exist. Qualify this as intended validation, or explicitly limit the current claim to the checks that are actually enforced.

---

reploy/docs/BLUEPRINT_ENVIRONMENT_MODEL.md

Lines 267 to 270 in 57bdcdd

	Every command invocation is one-shot by default and is expected to exit with a
	status. In Docker, Reploy runs it in a transient container created from the same
	materialized environment image, as the effective runtime user, with the same
	managed paths and application configuration as the workload container. The

Define whether private environment values reach one-shot commands

When a deployment has a .env file and a native or lifecycle command reads one of its variables, this promise of the same application configuration conflicts with the later mechanism: lines 2029–2039 define private FIFO injection only for the persistent workload, while lines 2044–2045 merely mask .env in app-command and lifecycle containers. The current app-command path validates the file but does not inject its assignments, so this present-tense equivalence does not hold. Specify that .env is workload-only, or define an equivalent private injection contract for transient commands.

---

reploy/docs/BLUEPRINT_ENVIRONMENT_MODEL.md

Lines 2329 to 2333 in 57bdcdd

	Published addresses should normally use loopback, with `127.0.0.1` as the
	recommended default. Existing wildcard publication remains supported for
	services intentionally exposed beyond the host. For readiness, Reploy converts
	`0.0.0.0` to `127.0.0.1` and `::` to `::1`; this changes only the client probe
	target, not Docker publication. IPv6 addresses are bracketed when constructing

Specify endpoint address grammar and omission defaults

When an endpoint omits bind.address or publish.address, or supplies a hostname, wildcard, bracketed IPv6 value, or scoped address, the normative model does not say which forms are valid or what omission resolves to. These values control Docker exposure, readiness URL construction, network-policy inputs, and interpolated application arguments, so an implementer currently has to invent security-relevant behavior; the existing renderer independently chooses 0.0.0.0 for an empty bind and 127.0.0.1 for an empty publication. Define canonical accepted address forms and normative defaults rather than only recommending loopback.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[omry]

@gitar-bot take a look

[gitar-bot]

@gitar-bot take a look

Taking a look now — review results will show up on the dashboard shortly.

[omry]

@gitar-bot ,review the entire docs/BLUEPRINT_ENVIRONMENT_MODEL.md file from scratch

[gitar-bot]

@gitar-bot ,review the entire docs/BLUEPRINT_ENVIRONMENT_MODEL.md file from scratch

On it — I'll do a full review of docs/.review/BLUEPRINT_ENVIRONMENT_MODEL.md from scratch and the results will show up on the dashboard shortly.

[omry]

All three findings verified against the code and fixed in 8a24e82.

Final-image mount-validation claim — confirmed false at this revision: portable-access validation of runtime-exposed outputs exists, but no build- or deploy-time step inspects mount destinations inside the image. That is exactly the unimplemented checks-2/3 surface this PR already documents under Runtime Mount Integrity, so this was a fourth site of the same rule our sweep missed — the paragraph now points there instead of claiming the validation.

Private env for one-shot commands — confirmed: startAndInjectPrivateWorkloadEnvironmentV1 is called only from the service-container and install-host-execute paths; current_app_command_run.go and the lifecycle executor call only the prepare/validate step and never inject. The one-shot command paragraph now states the workload-only boundary, and whether transient commands should gain an equivalent injection contract is a recorded backlog decision (docs/BACKLOG.md, standing decision E-2 in the review sidecar).

Endpoint address grammar — confirmed: the renderer resolves an omitted bind to 0.0.0.0 and an omitted publication to 127.0.0.1 (execution_plan.go), with no spec backing. The implemented omission defaults are now stated in the endpoints section, and the canonical accepted-address grammar is a recorded backlog decision (E-3).

The review sidecar docs/.review/BLUEPRINT_ENVIRONMENT_MODEL.md carries all standing decisions and a fresh attestation over the updated bytes.

[omry]

@codex, review docs/BLUEPRINT_ENVIRONMENT_MODEL.md as a whole at 8a24e82 — the complete document, not only this PR's diff.

Follow-up to your previous round: all three findings were verified against the code and fixed (final-image mount-validation claim now points at the unimplemented checks, the private-env workload-only boundary is stated, and the implemented endpoint omission defaults are documented with the grammar deferred to the backlog). Same scope as before: design contradictions, claims the mechanisms cannot support, rules an implementer would invent, unstated failure directions, and present-tense claims untrue at this revision. Prose style out of scope; the Proposed Embedded Built-In Tools section marks itself proposed.

[omry]

@gitar-bot take a look

[gitar-bot]

@gitar-bot take a look

Taking a look now — review results will show up on the dashboard shortly.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8a24e822a7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Correct the runtime-policy implementation status

At this revision, check 3 is already implemented: CompileRuntimePolicyV1 derives protected paths from provider-exclusive roots and referenced executable link chains, and validateRuntimePolicyOverlays rejects every compiled plan mount that overlaps them; CurrentBuildMatchesRuntimeV1 also recomputes this policy from the lock during the pre-container readiness check. ValidateRuntimePolicyV1 likewise applies check 1 to every compiled runtime-plan mount, not only during blueprint validation. Describing both checks as deferred could lead an implementer to duplicate or replace an existing safety path and incorrectly states which unsafe plans can currently run; only the image-side emptiness inspection in check 2 appears unimplemented.

Useful? React with 👍 / 👎.

[omry]

Correct, and thank you — this round caught an error in our own review, not just in the document.

Verified: CompileRuntimePolicyV1 / CompileRuntimePolicyFromLockV1 derive the protected set from Reploy roots, provider-exclusive roots, and referenced executables' invocation paths, link chains, and terminals; validateRuntimePolicyOverlays rejects any compiled mount overlapping that set or another mount; ValidateRuntimePolicyV1 applies the reserved-destination rules to every compiled plan mount; and CurrentBuildMatchesRuntimeV1 recompiles the policy from the build lock before workload, shell, app-command, and controlled-session containers, with a failing compile reading as stale. Check 3 and the enforcement point were implemented all along — the local review's case-sensitive searches missed runtime_policy_compile.go, and the previous fix then landed that overclaim into the document.

Fixed in 2a62027: the section now states checks 1 and 3 as enforced with their mechanisms, check 2 (image-side destination emptiness/ancestry inspection) as the one remaining gap; the original "an unsafe plan cannot run them" clause is restored, since it was true; the reploy build paragraph credits the lock-derived validation while noting image-side inspection is not part of it; the backlog entry is narrowed to check 2; and the review sidecar records the correction beside a fresh attestation.

[omry]

@codex, review docs/BLUEPRINT_ENVIRONMENT_MODEL.md as a whole at 2a62027 — the complete document, not only this PR's diff.

Follow-up to your last round: your correction was verified and landed. The Runtime Mount Integrity status text now states checks 1 and 3 as enforced with their mechanisms (reserved-path rules on every compiled plan mount; protected-set overlap validation at policy compile, recomputed from the build lock before runtime containers), check 2 (image-side destination emptiness/ancestry inspection) as the one remaining gap, the original "an unsafe plan cannot run them" clause restored, and the reploy build paragraph crediting the lock-derived validation. Same scope as before: design contradictions, claims the mechanisms cannot support, rules an implementer would invent, unstated failure directions, and present-tense claims untrue at this revision. Prose style out of scope; the Proposed Embedded Built-In Tools section marks itself proposed.

[chatgpt-codex-connector]

💡 Codex Review

reploy/docs/BLUEPRINT_ENVIRONMENT_MODEL.md

Line 2247 in 2a62027

Staging and deployed execution use the same materialized image, container-side

Qualify image parity across install scopes

When installation selects a different UID/GID from staging, the runtime identity contract at lines 1646-1650 explicitly requires rebuilding the final account/verifier layer and recording an identity-specific installed image while retaining the staging image. The blanket assertion that staging and deployed execution use the same materialized image contradicts that rule and could lead an implementer to reuse an image whose account database and verifier identity do not match the installed authority.

---

reploy/docs/BLUEPRINT_ENVIRONMENT_MODEL.md

Line 2248 in 2a62027

endpoint scheme and port, runtime user, mounts, application configuration, and

Exclude private values from configuration parity

When an installed .env has been edited or a later install preserves it while staging contains different values, the application-configuration contract at lines 2065-2074 intentionally leaves staging and deployed workloads with different private assignments. Claiming identical application configuration here conflicts with that preservation rule and could make an implementer overwrite installed private state to enforce parity; this statement should explicitly exclude deployment-local private environment values.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[omry]

Both verified and fixed in 5c548f1.

Image parity — confirmed: install_runtime_identity.go performs the account-specific runtime rebuild against the locked upstream exactly as the identity contract describes, so the installed image legitimately differs from staging when the installed authority differs. The parity summary also claimed "runtime user" parity, which the same rule breaks — swept in the same fix.

Configuration parity — confirmed: the install planner's PathPreservePrivateEnv default reads the installed copy when present, so deployment-local private values legitimately diverge from staging until an explicit --replace.

In both cases the code and the document's detailed rules agree; the summary sentence was the defect. It now states the shared surface and carves out exactly those two cases, each pointing at the rule that creates it. The review sidecar attestation is re-stamped over the new bytes.

[gitar-bot]

Code Review ✅ Approved

Resolves round-one design review findings in the portable tool definition design document and verifies the blueprint environment model against implementation. No issues found.

Options

Auto-apply is off → Gitar will not commit updates to this branch.
Display: compact → Showing less information.

Comment with these commands to change the behavior for this request:

Auto-apply	Compact
gitar auto-apply:on	gitar display:verbose

_{Was this helpful? React with 👍 / 👎 | Powered by Gitar — free for open source}

[omry]

Superseded by the finalized design-basis fold into #81. The descendant portable-tool stack was intentionally not restacked and must be reviewed bottom-up against the rewritten foundation.