diff --git a/docs/BACKLOG.md b/docs/BACKLOG.md index cd927702..c89664be 100644 --- a/docs/BACKLOG.md +++ b/docs/BACKLOG.md @@ -34,6 +34,14 @@ This file is the day-to-day queue for design and implementation gaps. ## Pre-release +- [ ] `P2` Evaluate the minimum public preparation inspection and launch + admission delivery that can unblock OmegaFlow RP-C6. + Follow [the consumer requirements and progress record](consumers/omegaflow.md). + Requirements and HLD are approved; complete the remaining LLD engineering + and review with bottom-up estimates, delivery cuts and explicit deferrals + when prioritized. Keep the separate endpoint dependency and milestone E + unchanged; no implementation is authorized by this backlog entry. + - [ ] `P2` Move the exhaustive portable-tool build matrix to the release gate. PR CI currently requires the complete Java matrix added in #222; its roughly 1m42s cost is acceptable for now but will grow with tools and diff --git a/docs/consumers/.review/omegaflow-rp-c6-high-level-design.md b/docs/consumers/.review/omegaflow-rp-c6-high-level-design.md new file mode 100644 index 00000000..0c502072 --- /dev/null +++ b/docs/consumers/.review/omegaflow-rp-c6-high-level-design.md @@ -0,0 +1,28 @@ +--- +artifact: swe-design-review-attestation +schema_version: 4 +scope_key: e14255a6399fd5c606eb6cf643031882028d631d5931da211a08d3520781e424 +scope: {"kind": "path", "primary_target": "docs/consumers/omegaflow-rp-c6-high-level-design.md", "repository": ".", "selector": "docs/consumers/omegaflow-rp-c6-high-level-design.md"} +review_content_identity_sha256: 6b8f37bb2a5c19bc453ece23b79c6e2e763981e0df75dc5f9bbb5172e1b6c7c9 +target_content_identity_sha256: aaead3da9ba82756c30bad717e3e3b6d55363b5e3bcdebf4b2c2f2c185b04641 +baseline_content_identity_sha256: 2e2450d919a913c204a30d5a04c4e69976338ffe7c042e0e2420b9d971835c80 +target_documents: [{"executable": false, "path": "docs/consumers/omegaflow-rp-c6-high-level-design.md", "repository": ".", "sha256": "a11766d9c835b48e8168fe8f1f291d5a9d475f57f1e9ec7498bcf0d695f77b88"}] +baseline_documents: [{"executable": false, "path": "docs/consumers/omegaflow-rp-c6-requirements.md", "repository": ".", "sha256": "496045631808a2f3aaecc88cf0d2450015b386069a43ffc572acedfb961557d5"}] +design_dependency_documents: [{"executable": false, "path": "docs/consumers/omegaflow-rp-c6-requirements.md", "repository": ".", "sha256": "496045631808a2f3aaecc88cf0d2450015b386069a43ffc572acedfb961557d5"}] +document_repository: "." +document_path: "docs/consumers/omegaflow-rp-c6-high-level-design.md" +document_revision_provenance: "39e6abca4d2daad47fdeca8c3faa1a174b11cb9e" +document_sha256: a11766d9c835b48e8168fe8f1f291d5a9d475f57f1e9ec7498bcf0d695f77b88 +verdict: clean +attested_at: 2026-10-30T08:55:42Z +--- + + +# SWE design-review attestation + +Review freshness binds target and baseline document bytes and executable state +listed in the version-4 header. Revisions are provenance only. + +## Durable review state + +No standing rejected or deferred decisions. diff --git a/docs/consumers/.review/omegaflow-rp-c6-requirements.md b/docs/consumers/.review/omegaflow-rp-c6-requirements.md new file mode 100644 index 00000000..432e7035 --- /dev/null +++ b/docs/consumers/.review/omegaflow-rp-c6-requirements.md @@ -0,0 +1,28 @@ +--- +artifact: swe-design-review-attestation +schema_version: 4 +scope_key: 45bb5a85de8dc494deea13aad2ebc8a33e9ed7ccdda77c3ee3ffbc40b9d0772a +scope: {"kind": "path", "primary_target": "docs/consumers/omegaflow-rp-c6-requirements.md", "repository": ".", "selector": "docs/consumers/omegaflow-rp-c6-requirements.md"} +review_content_identity_sha256: a334668539dff1aca318d254082984cae2415b663dac5c1980ea03998db26360 +target_content_identity_sha256: 2e2450d919a913c204a30d5a04c4e69976338ffe7c042e0e2420b9d971835c80 +baseline_content_identity_sha256: null +target_documents: [{"executable": false, "path": "docs/consumers/omegaflow-rp-c6-requirements.md", "repository": ".", "sha256": "496045631808a2f3aaecc88cf0d2450015b386069a43ffc572acedfb961557d5"}] +baseline_documents: [] +design_dependency_documents: [] +document_repository: "." +document_path: "docs/consumers/omegaflow-rp-c6-requirements.md" +document_revision_provenance: "39e6abca4d2daad47fdeca8c3faa1a174b11cb9e" +document_sha256: 496045631808a2f3aaecc88cf0d2450015b386069a43ffc572acedfb961557d5 +verdict: clean +attested_at: 2026-10-30T08:55:39Z +--- + + +# SWE design-review attestation + +Review freshness binds target and baseline document bytes and executable state +listed in the version-4 header. Revisions are provenance only. + +## Durable review state + +No standing rejected or deferred decisions. diff --git a/docs/consumers/.review/omegaflow.md b/docs/consumers/.review/omegaflow.md new file mode 100644 index 00000000..af4407b3 --- /dev/null +++ b/docs/consumers/.review/omegaflow.md @@ -0,0 +1,28 @@ +--- +artifact: swe-design-review-attestation +schema_version: 4 +scope_key: e1cc8e67b76839ab0287482083549bb5f19f5b5cbd1a23576f6d7ee396f1158c +scope: {"kind": "path", "primary_target": "docs/consumers/omegaflow.md", "repository": ".", "selector": "docs/consumers/omegaflow.md"} +review_content_identity_sha256: 1f7e833bae37af2cc82f16a163466756eda569faf379a7bf78216e84a6dc6570 +target_content_identity_sha256: 6f86b0136d4b62c92934a471871ed4f4ad9eaf10fd08d60c5b892157e1d0e772 +baseline_content_identity_sha256: null +target_documents: [{"executable": false, "path": "docs/consumers/omegaflow.md", "repository": ".", "sha256": "ec5c8d45a8e223edd6c4303b4609dfc0d3a7121b2e764ee21c18a5b9c8d9bc3d"}] +baseline_documents: [] +design_dependency_documents: [] +document_repository: "." +document_path: "docs/consumers/omegaflow.md" +document_revision_provenance: "39e6abca4d2daad47fdeca8c3faa1a174b11cb9e" +document_sha256: ec5c8d45a8e223edd6c4303b4609dfc0d3a7121b2e764ee21c18a5b9c8d9bc3d +verdict: clean +attested_at: 2026-10-30T08:56:23Z +--- + + +# SWE design-review attestation + +Review freshness binds target and baseline document bytes and executable state +listed in the version-4 header. Revisions are provenance only. + +## Durable review state + +No standing rejected or deferred decisions. diff --git a/docs/consumers/README.md b/docs/consumers/README.md index 315fc1e1..b970c047 100644 --- a/docs/consumers/README.md +++ b/docs/consumers/README.md @@ -5,6 +5,7 @@ it into a subdirectory only when that improves navigation. | Consumer | Current need | Status | Next step | | --- | --- | --- | --- | +| [OmegaFlow](omegaflow.md) | Public preparation inspection and admission of the inspected workload; separate private-endpoint dependency | Requirements/HLD approved; LLD unfinished and paused for E | Resume detailed engineering when prioritized | | [Dingo](dingo.md) | Development workspace and robot deployment capabilities | Historical needs recorded; current gaps need revalidation | Evaluate and prioritize against current Reploy behavior | ## What belongs here diff --git a/docs/consumers/omegaflow-rp-c6-high-level-design.md b/docs/consumers/omegaflow-rp-c6-high-level-design.md new file mode 100644 index 00000000..74307430 --- /dev/null +++ b/docs/consumers/omegaflow-rp-c6-high-level-design.md @@ -0,0 +1,303 @@ +# OmegaFlow RP-C6 high-level design + +Approved architecture for LLD engineering and slice planning. Requirements are in +[the approved baseline](omegaflow-rp-c6-requirements.md). This document does not +claim implementation readiness, platform qualification or consumer acceptance. + +## Outcome and existing constraints + +A consumer selects an immutable image, evaluates its inherited and application +environment, composes its blueprint, prepares and inspects the final workload, +and launches only that inspected state. Reploy refuses relevant changes before +bootstrap. OmegaFlow owns its policy and expected payload inventory. Reploy owns +image delivery, safe observations, retained contents and admission enforcement. + +Keep Reploy's Go implementation, native blueprint/YAML and structured JSON +interfaces. Extend the existing build, generation, provider store and controlled +session machinery. Add no inspection daemon, general filesystem snapshot service, +independent receipt authority or parallel build pipeline. + +Public host coverage inherits Reploy's existing Linux, native Windows and native +macOS commitment and includes WSL2 with Docker Desktop's Linux-container engine. +WSL does not substitute for native Windows. The initial OmegaFlow workload +profiles remain Linux/amd64 with the three qualified Bash builds in the +requirements. Host and workload architecture are separate qualification facts. +Existing staging/install-scope differences remain. This work adds neither +Windows-container workloads nor Podman, rootless or remote-engine support. + +The same integrity, refusal and cleanup contract applies on every supported +host. Record actual versions and filesystem locations in qualification evidence. +See [the platform contract](supporting/omegaflow-rp-c6-high-level-design/platform-qualification.md). + +## Actors and authority + +| Actor | Responsibility and authority | +| --- | --- | +| Consumer | Authors blueprint, expected file inventory and policy; decides whether reported facts are acceptable; supplies expected prepared identity to launch. | +| Host Reploy | Owns local engine access, selection/preparation, private retained metadata, observation validation, locked admission, session ownership and cleanup. | +| Trusted Reploy container helper | Performs bounded filesystem observations or transports existing session frames. It executes no workload command during inspection and grants no engine access to the controller. | +| Workload/controller application | Uses only its existing session authority and declared resources. It cannot authorize a caller-written observation or alter protected retained contents. | +| Container engine | Supplies immutable images, read-only root/mount enforcement and exact resource identities through the existing trusted local-engine boundary. | + +Do not strengthen hostile-host-root or same-identity isolation claims. A public +prepared identity is a comparison input, not a new permission to launch. Existing +host authorization and controller/workload session ownership remain necessary. + +## Architecture + +### 1. Retain the selected image through ordinary preparation + +Expose a host-side structured selection view using the current image resolver +and descriptor. It contains the selected immutable image/platform and inherited +environment before reserved consumer composition. Retain the selected descriptor +under existing preparation ownership; the authored image reference remains +provenance, not a later instruction to resolve a different image. + +The consumer carries the expected selection into ordinary final preparation. +The build uses that exact selected upstream image and normal provider graph; +it does not silently substitute a newly resolved tag or edit the consumer YAML. +The final generated image can contain the graph's ordinary declared changes and +protected payload layer. Report its distinct final identity after preparation. +A different selected upstream image requires a fresh view and consumer check. + +Return inherited, application and final effective environment as distinct fact +layers. Preserve the inherited facts even when composition overrides values. +Configured private values stay outside reports, comparison identities and errors. +The existing controlled-session refusal of private environment injection remains. + +### 2. Capture supplied bytes and deliver them in the normal immutable image + +Add a generic protected supplied-file input to existing preparation. It carries +a bounded complete inventory, expected digests, destination paths and executable +versus data modes. Bind the manifest's expected digest independently. The public +syntax and exact bounds are LLD work; they must support the current 18 payload +files plus manifest and approximately 7.9 MiB without copying arbitrary app data. + +Open sources safely and stream into private store artifacts using expected-byte +verification. An observed digest cannot become its own expectation. Publish only +a complete verified inventory; failed or cancelled captures publish no usable +prepared record. Source aliases, unsupported file types and escaping paths refuse. +The retained objects must be independent of the original files. + +Materialize a deterministic, verified payload archive into the **existing normal +generated-image build**, with no workload RUN command for this step. Encode +`0555` directories/executables and `0444` data; do not preserve source numeric +ownership. Check destination/ancestor collisions and verify the resulting image's +exact selected inventory against expectations before publishing its generation. +Keep the declared container paths, including `/omegaflow-runtime`. Collision and +inventory checks use the trusted probe, not image `/bin/sh` or image utilities; +existing helpers that execute those tools cannot be reused unchanged. + +This is a protected-copy implementation. Placing retained bytes in the normal +immutable generation avoids making the integrity boundary depend on Windows, +macOS or shared-filesystem chmod semantics or a surviving source bind. Use the +existing image ownership and store reachability for retention and cleanup. +Later original-source mutation or removal cannot change the published image. + +The consumer inspects protected-file delivery facts and contents at declared +paths, not an assertion that the final physical implementation is a source bind. +Its older bind-specific checks must reconcile with its corrected acceptance of +protected copies. Reploy must not encode OmegaFlow names, Bash policy or its +qualified-build table. + +### 3. Observe final facts with trusted, non-workload code + +Build the view from the verified current generation and actual effective runtime +plan. Report image/platform, environment layers, numeric identity, effective +mount declarations including read/write/tmpfs, endpoint bindings, selected command +and protected inventory. Run only the packaged, release-matched static Reploy +probe in a read-only networkless inspection container; never start the workload +entrypoint, bootstrap shell, package manager or an image-provided inspector. + +Use an inspection-specific fixed create policy. Explicitly disable inherited +image healthchecks (`--no-healthcheck`) and every image-controlled automatic +execution path. Drop unnecessary capabilities, use no-new-privileges, fix the +trusted helper entrypoint and sanitize its execution environment. Validate image +volume declarations and the actual mount map before starting inspection. Reuse +the probe/workspace protocol, not the current container-create policy unchanged. + +Qualification must include an image whose enabled healthcheck emits an execution +marker: normal enabled execution is the positive control; public inspection must +leave that marker absent while returning its expected observations. Exercise the +same no-image-execution constraint on refusal and cancellation paths. This is a +design obligation; the current source profile has not been fixed by this document. + +Extend the existing probe for bounded path resolution, terminal type/digest and +required-absence observations. Resolve ancestor and final symbolic links with +explicit limits; do not equate a broken link, permission failure, non-regular +file or size-limit failure with absence. A required digest is computed from the +opened inspected regular file. No raw Bash or system-rc byte export is required. + +The immutable image preserves Bash, `/bin/sh`, loaders and image libraries; +OmegaFlow supplies no dependency inventory for those files. Read-only root is +necessary but not sufficient: Reploy must also reject effective mounts that hide +protected payload or image execution/configuration namespaces, including aliases +and automatic image-volume/engine mounts. It must protect required absence from +being filled by a mutable mount. + +Reploy owns deriving and validating that image namespace boundary. It includes +resolved invocation/loader paths and applicable execution/configuration lookup +roots, not only `/bin/bash` as a string. LLD must prove this for all three required +Bash profiles without a new general dependency-analysis service. If the boundary +cannot be enforced simply, revisit this architecture before calling a slice ready. + +Application data and `/run/omegaflow` sockets/FIFOs remain live. Hash neither +arbitrary video inputs nor transient socket contents. They cannot shadow the +protected namespace. Their ordinary runtime failures do not invalidate retained +protected contents. + +### 4. Bind observations to existing generation admission + +Store the validated observation projection and its private comparison bindings +under existing deployment/generation metadata. Return a versioned opaque public +identifier for that record. Do not expose private generation/build/plan digests +or sign arbitrary caller-provided facts. No new global signing service or +credential authority is needed. + +Bind selected/final image identities, generation, protected capture, command and +all policy-relevant environment, identity, mount and endpoint facts. Bind the +inspection request and its observations. Exclude per-run ephemeral coordinates +such as newly allocated run IDs from the stable projection; their allowed +creation remains constrained by the same existing session plan. + +Expected identity is an optional comparison input on the existing public session +entry. The protected-consumer flow must supply it. Host Reploy loads the retained +record and derives the current projection itself under normal operation locks. +Unknown, malformed, oversized, unsupported-version, unavailable or mismatched +records refuse. A caller-written JSON report grants no admission. + +Queue admission can release and reacquire locks. Revalidate the selected state +and protected resource retention after those waits and before bootstrap; do not +rely on a check made only at initial load. Keep the final image and retained +resources pinned through actual use under existing session ownership. A missing +retained image/capture refuses instead of pulling a mutable alias as fallback. + +A public identity may be reused while its same bound generation/state remains +available and existing launch authorization allows it. It is not a single-use +credential. A generation or relevant state change requires fresh inspection. +Tag movement with the same retained image, original-source changes after capture +and live app-data changes do not alone invalidate it. Exact retention bounds, +record deletion and replay errors must be resolved in LLD. + +### 5. Preserve the session contract across existing hosts + +The host retains admission and supervision authority on all platforms. The current +Linux-only host socket and watchdog launch are prerequisites to resolve, not +reasons to narrow the public host contract. + +Proposed portable control transport: use the existing pinned engine connection +and a trusted packaged controller helper over a private engine-attached stream. +Keep the controller-side Unix socket/broker inside the Linux controller container; +relay existing bounded session frames to Host Reploy without exposing an engine +socket, host listener or new network capability to application code. Host Reploy +still validates every operation against the same frozen authorization and owns +the workload PTY. The relay makes no policy decisions. + +Use one host-independent channel boundary if the proof supports it, preserving +the existing protocol and lifecycle semantics. Compare the change with keeping +the Linux route plus host-specific adapters before choosing the final LLD. Do +not silently add multiple transports or relax claim, peer, cancellation or +disconnect guarantees. Container-internal Linux helpers remain Linux binaries; +that is compatible with native Windows/macOS host Reploy. + +Keep the existing watchdog cleanup algorithm, immutable exact resource manifest, +incident receipts and endpoint pinning. Add the necessary native child-launch +and parent-liveness adapters; reuse existing Windows/macOS boot identities and +local Unix/named-pipe engine endpoints. Parent death must leave an independently +owned cleanup path with no broader resource authority. Platform process/handle +inheritance, engine loss/restart and recovery are proof gates, not inferred from +cross-compilation. A watchdog that disappears with its parent is not acceptable. + +## End-to-end journeys and failure behavior + +1. Select image and inspect inherited/application facts before reserved composition. +2. Compose native blueprint and prepare against that selected upstream identity. +3. Verify supplied expected bytes, incorporate them through normal build and + publish only a complete verified final generation. +4. Inspect final workload facts with trusted non-workload code; obtain the public + immutable comparison identity and apply consumer policy. +5. Invoke existing controlled-session entry with expected identity. Revalidate + current state after admission waits, then start only the frozen owned plan. +6. Complete or cancel through the existing lifecycle. Release resources and keep + only generation-reachable artifacts and required recovery receipts. + +Capture/probe failure produces no admitted record. Stale/malformed admission +refuses before bootstrap and cleans its reservations/inert resources. Concurrent +rebuild cannot retarget a pending or live run. Parent loss invokes exact owned +cleanup; daemon unavailability retains recoverable ownership and incidents rather +than claiming containers were removed. No refusal test passes unless it also +checks that bootstrap did not begin where required. + +## Alternatives and proportionality + +| Alternative | Assessment | +| --- | --- | +| Verified private copy plus read-only source bind | Small on native Linux and the narrow WSL proof passed. Cross-platform delivery still needs mode, path-sharing, alias, lifetime and cleanup proofs. Prefer normal immutable-image delivery for one portable retained-byte boundary. | +| Protected files in existing generated image | Proposed: reuse build/verification/generation ownership, preserve exact paths/modes, remove later source mutation from the launch dependency. Requires a generic input/graph cut and final inventory verification. | +| Offline general image filesystem reconstruction | Avoid as the primary path: existing account-file archive reader is intentionally narrow; general layer/link/whiteout semantics would add substantial parser work. Reuse trusted probe instead. | +| Host-specific sockets and a separate portability implementation | Compare with engine-attached transport during LLD; retain multiple paths only if the proof and cost of replacing the existing route justify them. | +| New snapshot service, broker authority or permanent daemon | No requirement justifies them; not proposed. | + +The initial responsibilities estimate is historical. Payload delivery and portable +session prerequisites must be sized from actual engineering cuts. Do not label +them test-only qualification work or hide them in an integration-only final slice. + +## Requirement coverage + +| Requirement | Owning architectural responsibility and observable acceptance | +| --- | --- | +| R1 | Retained selected upstream descriptor through ordinary preparation; tag movement cannot substitute image B for selected A. | +| R2 | Separate inherited/application/final environment; forbidden inherited values remain visible and private configured values remain absent. | +| R3 | Verified final plan projection and trusted-only probe; workload/bootstrap execution marker remains absent during inspection. | +| R4 | Bounded path/type/hash/absence probe; explicit link, type, unreadable and over-limit failures. | +| R5 | Expected-hash capture plus separately bound manifest, normal-build final inventory check; substitution and capture races refuse. | +| R6 | Immutable generation payload with read-only runtime and namespace/mount protection; post-capture source changes cannot replace it. | +| R7 | Explicit live data and session-resource paths; mutation is ordinary runtime behavior and cannot shadow protected state. | +| R8 | Public opaque comparison record at existing locked admission; caller-written facts cannot authorize launch. | +| R9 | Stable actual-state projection, post-wait revalidation and retained resources; paired success/refusal tests distinguish external reference movement from actual bound changes. | +| R10 | Existing generation reachability, leases, native supervision and exact cleanup/recovery; no leaked active workload or reservation after required cancellation/refusal paths. | +| R11 | Complete public path on supported native hosts and WSL2/Desktop, with exact versions/paths and actual release adoption by OmegaFlow. | + +## Engineering gates before LLD readiness + +- Prove selected-image retention and environment provenance through normal builds. + Resolve duplicate inherited environment entries and private-value redaction. +- Define generic protected-file declaration, inventory/manifest trust, safe native + source opening, deterministic modes/archive and exact final-image verification. + Specify numeric limits and preserve source-change independence. +- Prove component-aware observation and image execution/lookup namespace protection, + including hidden mounts, automatic volumes, absence and aliases. The three + required Bash profiles cannot silently become unsupported. +- Prove the proposed engine-mediated private stream preserves the existing claim, + framing, controller identity, disconnect and lifecycle boundaries. Compare the + simpler retained-route alternative before committing to a transport replacement. +- Prove native watchdog child survival, private handles, parent-loss detection, + receipt ownership and exact cleanup on Windows and macOS; retain Linux parity. +- Specify opaque identity encoding, bounded record storage, lifetime/replay, + generation reachability, post-queue comparison and race-free use. +- Define and obtain full native-host plus WSL2/Desktop acceptance evidence for + success/refusal/cancellation/parent-loss/engine-loss/cleanup and real filesystem + classes. Build/smoke passes and the protected-copy fixture cannot substitute. +- Produce the complete slice inventory with production/configuration and test-code + estimates, totals and the agreed changed-physical-line counting convention. + Shared portability foundations have one owning prerequisite. No working-hour + estimates; no deferred consumer obligation without owner agreement. + +Failure of a gate can invalidate its proposed mechanism or estimates. Reassess +before delivery rather than accumulate exceptions or claim readiness. Reviewed +HLD acceptance permits detailed engineering; it does not by itself approve an unresolved +LLD, implementation, commits, publication or release. + +Optional host endpoint publication remains a separate dependency. This design +does not activate mapped execution, resume E2.3 or recover the OmegaFlow campaign. +Consumer acceptance also requires qualification against an explicitly selected +compatible Reploy release. + +## Supporting material + +- [Source investigation and narrow mechanism proof](supporting/omegaflow-rp-c6-high-level-design/source-investigation.md) +- [Existing public-host contract and qualification evidence](supporting/omegaflow-rp-c6-high-level-design/platform-qualification.md) +- [Observed local versions and filesystem paths](supporting/omegaflow-rp-c6-high-level-design/local-proof-environment.json) +- [Maintainer platform clarification](supporting/omegaflow-rp-c6-high-level-design/platform-contract-clarification.json) +- [Preserved requirements-phase workflow document](supporting/omegaflow-rp-c6-high-level-design/requirements-workflow-preimage.txt) +- [Document and estimate contract](supporting/omegaflow-rp-c6-requirements/design-contract.md) diff --git a/docs/consumers/omegaflow-rp-c6-requirements.md b/docs/consumers/omegaflow-rp-c6-requirements.md new file mode 100644 index 00000000..5e608d9b --- /dev/null +++ b/docs/consumers/omegaflow-rp-c6-requirements.md @@ -0,0 +1,204 @@ +# OmegaFlow RP-C6 requirements + +Approved requirements baseline. This document states the consumer outcome and +constraints; it does not select a public API or claim implementation readiness. + +## Outcome + +OmegaFlow can inspect the exact workload Reploy will launch, evaluate its own +policy, and require that same prepared state at controlled-session admission. +Reploy rejects relevant mismatches before workload or bootstrap execution. +The delivery must satisfy the full requirements below; reducing an implementation +estimate does not authorize dropping an obligation. + +## Ownership and scope + +Reploy owns generic preparation facts, workload-image delivery, protected supplied +inputs, launch admission and resource cleanup. Extend its existing implementation, +preparation, immutable-image selection, build verification, inspection and session +machinery. Do not introduce a parallel image selector, inspection daemon, receipt +authority or build pipeline. + +OmegaFlow defines its blueprint and owns reserved-environment policy, qualified +Bash compatibility checks, supplied runtime contents, mount acceptance policy and +recording behavior. It does not enumerate or snapshot files supplied by the image, +including Bash, `/bin/sh`, loaders and libraries. Reploy delivers and enforces +those image contents. + +The initial consumer workload is Linux/amd64 with the consumer's qualified Bash +profiles: Debian 12/5.2.15, Debian 13/5.2.37 and Ubuntu 26.04/5.3.9. Qualification +must identify the exact image/build tuple. An ARM64 artifact or controller build +does not establish ARM64 workload qualification. The design must state the exact +supported engine/host cohort and reject unsupported cases rather than silently +weaken a guarantee. + +## Required behavior + +### R1. Select and retain the image used for preparation + +Expose the selected image's immutable identity, platform and inherited environment +through public preparation machinery before OmegaFlow adds reserved composition +values. Permit OmegaFlow to evaluate that image plus application environment. +Final preparation must use that same selected image. If it selects a different +image, reject and require a fresh preparation view; do not silently rewrite the +consumer's retained YAML or reuse checks for another image. + +### R2. Keep environment sources observable and private values private + +Distinguish image-inherited, application and final effective environment facts. +Overriding a value during composition must not erase inherited facts needed for +policy evaluation. Report uninspectable required facts as failure rather than +silently omitting them. Do not disclose configured private environment values in +reports, identities or diagnostics. This requirement does not add private +environment injection to controlled sessions. + +### R3. Inspect the actual prepared workload without starting it + +Expose the prepared generation's final image/platform, effective environment, +numeric execution identity, effective mounts and declared endpoint bindings. +Mount facts include targets and read/write/tmpfs semantics. Inspection must not +start workload/bootstrap code, execute untrusted workload code or grant the +controller container-engine access. + +### R4. Provide bounded executable and required-absence evidence + +Expose the resolved `/bin/bash` path, file type and SHA-256 digest needed by the +consumer's qualified-build check. Compute that digest from the actual inspected +file and bind the evidence to the prepared state that will be admitted. Report +the selected system-rc path's absence, or its presence/type if present. OmegaFlow's +current profiles require `/etc/bash.bashrc` to be absent. Raw Bash and system-rc +file-byte export is not required for this delivery. + +Specify safe path resolution, symbolic-link handling, regular/non-regular file +behavior, required-absence semantics and errors. Bound requests, responses and +file hashing. An unreadable, uninspectable or over-limit file must produce an +explicit failure, not an absence claim. Do not mistake hash equality for proof +of path, type, mode, absence or mount integrity. + +### R5. Capture supplied runtime files against expected hashes + +Accept a complete bounded inventory of consumer-supplied runtime files with +expected SHA-256 values. The supplied manifest's expected digest is bound +separately; an attacker-controlled replacement manifest cannot supply its own +expectations. Verify the bytes actually retained against those expectations. +Computing fresh observed hashes and treating them as expected values is +insufficient. + +The current consumer inventory contains 18 payload files plus `manifest.json`, +approximately 7.9 MiB total: + +- `bin/envoy` and `bin/awsh`; helper commands use the same Awsh executable; +- `etc/awsh-bashrc`, `etc/inputrc` and `etc/bash-builds.json`; +- one terminal database entry and 12 locale files; and +- `manifest.json`, with its expected digest supplied separately. + +These inventory and size facts are consumer inputs, not independently measured +qualification evidence. Preserve the declared paths under `/omegaflow-runtime`. +The supplied files have no symbolic-link or hardlink aliases. Deliver directories +and executables as `0555` and data files as `0444`. The workload needs read/execute +access; retaining the source owner's numeric UID/GID is unnecessary. The adapter +rcfile sources no additional startup files. + +### R6. Protect the retained payload through admission and use + +Prevent source mutation after verification, workload writes and mount shadowing +from replacing protected supplied contents. File permissions alone do not +establish that boundary. A verified independent protected copy is acceptable; +the design need not introduce a general filesystem snapshot service. + +After such a capture exists, later changes to the original source need not +invalidate it. Set explicit capture size limits that support the required +inventory, and reject unsupported sizes instead of weakening protection. + +### R7. Keep application data and session resources live + +Videos and other unprotected application data may remain live. Mutation, +disappearance and processing errors are ordinary runtime failures. Do not require +copying or hashing arbitrary large application inputs merely to prevent those +errors. `/run/omegaflow` remains writable for live sockets and FIFOs; these are not +protected startup payload. + +### R8. Bind inspected facts to public launch admission + +Return one public immutable identity that binds the relevant prepared facts and +protected capture. Accept the expected identity at the existing controlled-session +entry. Validate it against Reploy's actual selected state under existing admission +ownership before bootstrap starts. A caller-written report is not launch authority. +Pinning only the image is insufficient. + +Keep private internal generation/build/plan digests out of the public session +stream as required by the existing session contract. The design must define the +public binding's representation, lifetime, replay and invalidation rules without +creating a second launch-authorization system. + +### R9. Reject stale or malformed state before effects + +Invalidate the expected identity when the state actually selected for admission +differs from the state bound by inspection. This includes changes to the selected +immutable image, inspected executable/image contents, protected payload, bound +blueprint/environment/mount facts or selected generation. Prevent a relevant +replacement race between successful validation and use. + +Changes to external references that no longer affect that retained state do not +by themselves invalidate it. If an original mutable image tag moves while Reploy +retains and launches the same inspected immutable image, the binding remains +valid. Likewise, changes to the original supplied-file source after an independent +verified protected capture, or to unprotected application data, need not +invalidate that capture or binding. + +Admission must use the retained bound image and capture, not re-resolve a mutable +reference and silently select a replacement. If the required retained state is +unavailable or cannot be verified, refuse rather than fall back to different +contents. A rebuild or generation replacement that selects a different bound +state still requires a new inspection identity. + +Reject malformed, oversized, unknown-version and forged identities. Define public +schema versions, limits and error behavior. Each stale-state refusal must prove +workload/bootstrap execution did not begin. + +### R10. Preserve cancellation, ownership and cleanup + +Reuse existing session ownership and resource cleanup. Interrupted inspection or +admission must not leave an active workload or leaked reservation. Define retained +capture reachability, cancellation and concurrent replacement behavior. Preserve +the distinction between preparation evidence, admission ownership and runtime +session resources. + +### R11. Qualify the integrated public path + +Retain public-interface tests for nominal inspection and launch, forbidden +inherited environment, qualified Bash and system-rc evidence, mount/identity facts, +protected payload/manifest substitution, capture races, size limits, malformed and +stale identities, concurrent rebuild/replacement and interrupted cleanup. Include +positive launch controls showing that original-tag movement with the same retained +immutable image, and original-source changes after protected capture, do not +invalidate unchanged admitted state. Pair them with negative controls for actual +bound-state changes. Every relevant refusal must verify that bootstrap did not +start. Exercise the public +inspection and launch interfaces together; isolated internal helper tests do not +establish consumer acceptance. + +Retain the exact release/source identity, public contract and native evidence. +OmegaFlow must qualify against an explicitly selected compatible release before +the consumer is reported unblocked. A reviewed design or approved implementation +PR alone is insufficient. + +## Boundaries and dependencies + +Optional host publication for private endpoints is a separate dependency. Link +its existing backlog item when identified; do not duplicate it. RP-C6 does not +alone establish all OmegaFlow acceptance, and this work does not recover the +OmegaFlow campaign or adopt a release for it. + +The delivery does not activate mapped execution, implement remaining multi-identity +E slices, introduce hostile-host-root containment or strengthen the existing +same-identity isolation guarantee. New platform/engine qualification requires its +own explicit evidence. Unsupported cases must fail closed. + +## Supporting material + +- [Consumer source and earlier evaluation](supporting/omegaflow-rp-c6-requirements/consumer-request-and-evaluation.txt) +- [Consumer clarification of inspection and invalidation](supporting/omegaflow-rp-c6-requirements/consumer-clarifications.md) +- [Document and estimation contract](supporting/omegaflow-rp-c6-requirements/design-contract.md) +- [Engineering follow-up from the interview](supporting/omegaflow-rp-c6-requirements/interview-synthesis.md) +- [Workflow feedback](supporting/omegaflow-rp-c6-requirements/design-workflow-feedback.md) diff --git a/docs/consumers/omegaflow.md b/docs/consumers/omegaflow.md new file mode 100644 index 00000000..ed72de4b --- /dev/null +++ b/docs/consumers/omegaflow.md @@ -0,0 +1,551 @@ +--- +status: Requirements and HLD approved; LLD paused for milestone E +updated: 2026-10-29 +summary: Approved OmegaFlow RP-C6 requirements and architecture; detailed engineering and delivery slices remain unfinished. +--- + +# OmegaFlow + +## Design outputs + +The active `global:swe:design` run retains this consumer record and its required +tracking. Its additional outputs follow the +[design document contract](supporting/omegaflow-rp-c6-requirements/design-contract.md): +`omegaflow-rp-c6-requirements.md`, `omegaflow-rp-c6-high-level-design.md`, and +`omegaflow-rp-c6-implementation-plan.md`, alongside this file. Each is authored +at its responsible phase. Requirements and HLD are approved; the LLD and slice +plan remain unfinished and unapproved. +Durable supporting material belongs under `supporting//`. +Feedback for later AWD improvements is collected in +[design workflow feedback](supporting/omegaflow-rp-c6-requirements/design-workflow-feedback.md). + +The approved [requirements baseline](omegaflow-rp-c6-requirements.md) carries the full +corrected RP-C6 scope. Its +[interview synthesis](supporting/omegaflow-rp-c6-requirements/interview-synthesis.md) +separates existing project constraints from engineering investigations. Requirements and HLD completed review and maintainer acceptance. +The approval records remain under the requirements and HLD supporting directories. +The HLD readiness gates still apply; no implementation-plan approval, platform +qualification or delivery readiness is implied. + +## Use case and source + +OmegaFlow needs to inspect the workload it will launch, evaluate its own policy, +and launch exactly that inspected preparation. Reploy must reject relevant +changes before workload or bootstrap execution begins. + +Source: the 2026-10-29 planning draft in the OmegaFlow checkout, +`temp/part-c-delivery/implementation-through-C6.1/RP-C6-HANDOFF-PLANNING.md` +(read from `/home/omry/dev/omegaflow`), corrected by the maintainer-relayed +OmegaFlow scope clarification on 2026-10-29. The clarification below takes +precedence over the earlier handoff where they differ. These are consumer +requirements, not an approved Reploy API or an installed-release conformance +claim. + +The subsequent [OmegaFlow clarification](supporting/omegaflow-rp-c6-requirements/consumer-clarifications.md) +removes raw Bash/system-rc byte export from the requirements scope and makes +invalidation depend on changes to the bound prepared state. It takes precedence +over older byte-export or unconditional tag-change language in source evidence +and preliminary estimates. + +## Corrected ownership and supplied-input scope + +OmegaFlow defines the blueprint; Reploy delivers and enforces it. Bash, `/bin/sh`, +loaders and libraries supplied by the workload image remain Reploy's +responsibility. OmegaFlow does not need to enumerate or snapshot that image +dependency closure. OmegaFlow owns compatibility checks against its qualified +Bash build table. Reploy must expose the resolved Bash and selected system-rc +facts for the generation actually launched. The selected system-rc path must be +absent; the consumer reports `/etc/bash.bashrc` for all three current profiles. + +For consumer-supplied inputs, OmegaFlow reports a complete expected-SHA-256 +inventory of 18 payload files plus `manifest.json`, approximately 7.9 MiB total: + +- `bin/envoy` and `bin/awsh`; helper commands use the same Awsh executable; +- `etc/awsh-bashrc`, `etc/inputrc` and `etc/bash-builds.json`; +- one terminal database entry and 12 locale files; and +- `manifest.json`, with its expected digest supplied separately. + +Retain established paths under `/omegaflow-runtime`. These are regular files +without symbolic-link or hardlink aliases. The reported staged modes are `0555` +for directories/executables and `0444` for data. The workload needs read/execute +access; source numeric UID/GID preservation is not required. The adapter rcfile +sources no additional startup files. These inventory facts are consumer-reported, +not independently verified measurements in this record. + +Protected copies are acceptable. Verify the bytes actually retained against the +supplied expected hashes, then deliver those exact contents at the declared +paths. Computing fresh hashes without checking the supplied expectations could +accept inputs mutated before capture. Once an independent protected capture +exists, changes to its original source need not invalidate it. Enforce explicit +size bounds and reject unsupported sizes. Copying is an implementation candidate, +not a requirement to introduce a general filesystem snapshot service. + +Distinguish protected supplied inputs from unprotected application data. Videos +and other application data can remain live; mutation, disappearance and processing +errors are acceptable ordinary runtime failures. `/run/omegaflow` remains writable +for live sockets and FIFOs. Those resources are not protected startup payload. + +Protect retained runtime contents against source mutation after verification, +workload writes and mount shadowing through Reploy delivery machinery. File +permissions alone do not establish the boundary. Hostile-host-root containment +and stronger same-identity isolation are outside the clarified requirement. + +## Requirements and acceptance + +1. Select the workload image through existing public preparation machinery. + Observe its immutable identity and inherited environment, and evaluate image + plus application environment before OmegaFlow adds reserved composition + values. Forbidden inherited values must not disappear from observation. +2. Compose final native blueprints through OmegaFlow's existing Hydra entry and + prepare with the same selected image. Reject image replacement rather than + silently changing composed YAML or reusing checks for another image. +3. Inspect the prepared generation's final image/platform, effective environment, + execution identity, mounts, endpoints, resolved executable path/type/hash and required + selected system-rc absence. Keep configured private environment values private. + Define bounded metadata/hash/absence evidence, safe path resolution, and explicit + absent, symbolic-link, non-regular-file and error behavior. Inspection must + not start bootstrap or execute untrusted workload code. +4. Bind the observations to one public immutable identity. Accept that expected + identity at controlled-session admission, using Reploy's existing ownership + and cleanup. Bind the protected supplied-input capture and relevant image + facts through admission and use; pinning only the image is insufficient. +5. Prove public inspection and public launch work together. Relevant rebuilds, + changes to the selected immutable image, bound blueprint/environment/mount facts, + protected content or selected generation must invalidate stale facts. Moving an + original tag while the inspected immutable image is retained and launched does + not by itself invalidate the binding. Source changes after an independent + verified capture and changes to unprotected application data need not invalidate + that capture. Each stale case must prove + bootstrap did not start. Malformed, + oversized, unknown-version and forged identities must fail closed; + interruptions must leave no active workload or leaked reservation. +6. Retain the exact release/source identity, public contract and native test + evidence. Qualify OmegaFlow against an explicitly selected compatible release + before claiming the consumer is unblocked. + +## Current support and gaps + +The Reploy source inspection on 2026-10-29 identified reusable internal generation +and build identities in [controlled-session planning](../../internal/dockerdeploy/controlled_session_plan.go), +and executable hash, ownership, permission and symbolic-link observations in the +[probe protocol](../../internal/probe/protocol.go). These do not establish the +complete public inspection/admission contract above. The inspected +[public launch options](../../internal/cli/controlled_session.go) do not accept +the consumer's expected preparation identity. Existing executable metadata/hash +observations do not establish the complete public absence and admission contract. +The current scope does not require raw Bash or system-rc byte export; see the +[consumer clarifications](supporting/omegaflow-rp-c6-requirements/consumer-clarifications.md). + +The [controlled-session design](../CONTROLLED_SESSION_DESIGN.md) keeps internal +generation/build/plan digests out of the public session stream. A separate +preparation interface with an opaque public binding is a candidate, not a +selected design. Reuse existing preparation, immutable-image selection, build +verification, inspection and session admission. Do not add a parallel image +selector, inspection daemon, receipt authority or build pipeline. + +Reploy owns generic facts, image delivery, protected supplied-input delivery and +admission. OmegaFlow owns its reserved environment policy, Bash compatibility +checks, supplied runtime contents, mount acceptance policy and recording behavior. + +## Separate endpoint dependency + +The handoff reports that optional host publication for private endpoints is +already known Reploy backlog work. Its exact backlog item is not yet confirmed; +do not create a duplicate. Related endpoint-address and network-policy items are +not an exact match. Existing private controlled-session networking must remain +distinct from the native-blueprint validation gap reported for OmegaFlow's +selected installed release. + +The handoff reports this dependency blocks C6.1 acceptance. RP-C6 separately +blocks C6.2/C6.3 and dependent launch acceptance. Resolving one does not prove the +other is resolved. + +## Delivery decision and next step + +**Minimum delivery: undecided.** Evaluate which acceptance checks are essential +to unblock RP-C6 and recommend the smallest coherent contract from the actual +code. Produce bottom-up production/test estimates, proposed delivery cuts, +acceptance evidence and release/adoption prerequisites. Any deferred consumer +requirements need explicit consumer agreement; do not silently weaken the +launch guarantee to make the delivery smaller. + +Resolve image selection through final preparation, protected-input capture, +private-value handling, identity lifetime, cancellation, concurrent replacement, +platform support, bounds and errors during design. Review the resulting design +through the required local deep design review and remote PR cycle before +implementation. Return to design if costs or mechanisms expand. + +## Progress and evidence + +### Revised preliminary size estimate, 2026-10-29 + +This is a source-based planning estimate, not a reviewed LLD, measured result or +approved set of slices. Counts are added plus removed lines; tests include +fixtures. Documentation, review bookkeeping, generated output, release execution +and OmegaFlow-side integration are excluded. + +| Responsibility | Production LOC | Test/fixture LOC | +| --- | ---: | ---: | +| Bind selected image through preparation; inherited/application/final environment observations | 250–400 | 400–650 | +| Bounded resolved-Bash inspection/export and selected system-rc absence evidence | 300–450 | 600–900 | +| Generic protected supplied-input declaration/capture, expected-hash verification, exact path/mode delivery and mount protection | 350–550 | 700–1150 | +| Expected preparation identity at existing admission; stale-state refusal and capture lifetime/cleanup | 250–400 | 500–850 | +| Public CLI/schema integration and end-to-end inspection/launch qualification | 150–250 | 500–800 | +| **Total** | **1300–2050** | **2700–4350** | + +Expect approximately four to six implementation PRs after design, subject to +coherent cuts and the repository's production-size limits. These rows are +responsibilities, not approved task IDs. The superseded estimate was 1550–2500 +production and 3200–5200 test LOC. The narrower inventory and protection boundary +reduce estimated work and uncertainty; they do not establish implementation +readiness or a measured saving. + +The estimate assumes reuse of the existing controlled-session platform and +ownership model, the consumer's explicit bounded payload inventory and supplied +expected hashes, and reuse of existing artifact storage/materialization where +it meets the required delivery boundary. The public API and delivery mechanism +remain undecided. It does not estimate a general mutable-tree +snapshot service, a new image-selection pipeline, remote-engine support, +multi-identity activation or private-environment injection. Unsupported inputs +must refuse; a read-only bind or permission change alone is not a substitute for +protected delivery. If necessary protection cannot fit this scope, resolve +the design and re-estimate before committing to delivery. + +Basis: [current session admission](../../internal/dockerdeploy/current_controlled_session_run.go) +already loads verified current builds under both deployment locks and owns queue +leases; [runtime input handling](../../internal/dockerdeploy/current_runtime_files.go) +validates generated inputs under the operation lock. Those locks do not by +themselves prevent external bind-source mutation. The +[image inspector](../../internal/dockerdeploy/docker_image_inspect.go) already +extracts inherited environment, while the [probe](../../internal/probe/protocol.go) +returns executable metadata/hashes but still needs the complete bounded public +inspection/absence and admission semantics. The historical estimate above included +byte export, which the consumer subsequently removed from the required scope. +The [artifact store](../../internal/providerstore/store.go) already offers +`PublishExpected`, which compares retained bytes against an expected descriptor +before atomic publication. That is a reuse candidate, not proof of complete +runtime delivery, reachability/cleanup integration or mount-shadow resistance. +No new runtime proof or tests ran for this estimate. + +Optional host endpoint publication remains a separately identified dependency +with an unconfirmed exact backlog item; its cost is excluded. Delivery of RP-C6 +alone therefore does not claim to unblock all OmegaFlow acceptance. + +### Delivery status + +- Current priority: milestone E delivery. E2.2 and its prerequisite stack were + merged; remaining E work has been re-planned. OmegaFlow design remains paused + at detailed engineering, preserving its existing run and approvals. +- Requirements and HLD are reviewed and approved as the basis for LLD. The HLD + retains namespace-protection and portable transport/watchdog proof gates. +- Evaluation remains linked from [the backlog](../BACKLOG.md). Detailed delivery + cuts, implementation, release selection and consumer qualification remain + unapproved. This checkpoint records existing design work only. +- This is separate from milestone E and does not expand its delivery scope. +- The source handoff reports C6.1 preserved and unaccepted, with two unresolved + ownership findings. Those campaign conditions have not been independently + revalidated here. It authorizes no campaign recovery or dependency upgrade. +- After prerequisite delivery and release selection, OmegaFlow must use its + reviewed dependency-adoption and guarded campaign-recovery path. + +## High-level design + +Approved architecture for LLD engineering and slice planning. Clean phase output: [OmegaFlow RP-C6 HLD](omegaflow-rp-c6-high-level-design.md). Requirements above remain unchanged; the public-host clarification inherits existing Reploy support. Namespace protection and portable transport/watchdog proofs remain readiness gates. The LLD and implementation are not approved. + +### Outcome and existing constraints + +A consumer selects an immutable image, evaluates its inherited and application +environment, composes its blueprint, prepares and inspects the final workload, +and launches only that inspected state. Reploy refuses relevant changes before +bootstrap. OmegaFlow owns its policy and expected payload inventory. Reploy owns +image delivery, safe observations, retained contents and admission enforcement. + +Keep Reploy's Go implementation, native blueprint/YAML and structured JSON +interfaces. Extend the existing build, generation, provider store and controlled +session machinery. Add no inspection daemon, general filesystem snapshot service, +independent receipt authority or parallel build pipeline. + +Public host coverage inherits Reploy's existing Linux, native Windows and native +macOS commitment and includes WSL2 with Docker Desktop's Linux-container engine. +WSL does not substitute for native Windows. The initial OmegaFlow workload +profiles remain Linux/amd64 with the three qualified Bash builds in the +requirements. Host and workload architecture are separate qualification facts. +Existing staging/install-scope differences remain. This work adds neither +Windows-container workloads nor Podman, rootless or remote-engine support. + +The same integrity, refusal and cleanup contract applies on every supported +host. Record actual versions and filesystem locations in qualification evidence. +See [the platform contract](supporting/omegaflow-rp-c6-high-level-design/platform-qualification.md). + +### Actors and authority + +| Actor | Responsibility and authority | +| --- | --- | +| Consumer | Authors blueprint, expected file inventory and policy; decides whether reported facts are acceptable; supplies expected prepared identity to launch. | +| Host Reploy | Owns local engine access, selection/preparation, private retained metadata, observation validation, locked admission, session ownership and cleanup. | +| Trusted Reploy container helper | Performs bounded filesystem observations or transports existing session frames. It executes no workload command during inspection and grants no engine access to the controller. | +| Workload/controller application | Uses only its existing session authority and declared resources. It cannot authorize a caller-written observation or alter protected retained contents. | +| Container engine | Supplies immutable images, read-only root/mount enforcement and exact resource identities through the existing trusted local-engine boundary. | + +Do not strengthen hostile-host-root or same-identity isolation claims. A public +prepared identity is a comparison input, not a new permission to launch. Existing +host authorization and controller/workload session ownership remain necessary. + +### Architecture + +#### 1. Retain the selected image through ordinary preparation + +Expose a host-side structured selection view using the current image resolver +and descriptor. It contains the selected immutable image/platform and inherited +environment before reserved consumer composition. Retain the selected descriptor +under existing preparation ownership; the authored image reference remains +provenance, not a later instruction to resolve a different image. + +The consumer carries the expected selection into ordinary final preparation. +The build uses that exact selected upstream image and normal provider graph; +it does not silently substitute a newly resolved tag or edit the consumer YAML. +The final generated image can contain the graph's ordinary declared changes and +protected payload layer. Report its distinct final identity after preparation. +A different selected upstream image requires a fresh view and consumer check. + +Return inherited, application and final effective environment as distinct fact +layers. Preserve the inherited facts even when composition overrides values. +Configured private values stay outside reports, comparison identities and errors. +The existing controlled-session refusal of private environment injection remains. + +#### 2. Capture supplied bytes and deliver them in the normal immutable image + +Add a generic protected supplied-file input to existing preparation. It carries +a bounded complete inventory, expected digests, destination paths and executable +versus data modes. Bind the manifest's expected digest independently. The public +syntax and exact bounds are LLD work; they must support the current 18 payload +files plus manifest and approximately 7.9 MiB without copying arbitrary app data. + +Open sources safely and stream into private store artifacts using expected-byte +verification. An observed digest cannot become its own expectation. Publish only +a complete verified inventory; failed or cancelled captures publish no usable +prepared record. Source aliases, unsupported file types and escaping paths refuse. +The retained objects must be independent of the original files. + +Materialize a deterministic, verified payload archive into the **existing normal +generated-image build**, with no workload RUN command for this step. Encode +`0555` directories/executables and `0444` data; do not preserve source numeric +ownership. Check destination/ancestor collisions and verify the resulting image's +exact selected inventory against expectations before publishing its generation. +Keep the declared container paths, including `/omegaflow-runtime`. Collision and +inventory checks use the trusted probe, not image `/bin/sh` or image utilities; +existing helpers that execute those tools cannot be reused unchanged. + +This is a protected-copy implementation. Placing retained bytes in the normal +immutable generation avoids making the integrity boundary depend on Windows, +macOS or shared-filesystem chmod semantics or a surviving source bind. Use the +existing image ownership and store reachability for retention and cleanup. +Later original-source mutation or removal cannot change the published image. + +The consumer inspects protected-file delivery facts and contents at declared +paths, not an assertion that the final physical implementation is a source bind. +Its older bind-specific checks must reconcile with its corrected acceptance of +protected copies. Reploy must not encode OmegaFlow names, Bash policy or its +qualified-build table. + +#### 3. Observe final facts with trusted, non-workload code + +Build the view from the verified current generation and actual effective runtime +plan. Report image/platform, environment layers, numeric identity, effective +mount declarations including read/write/tmpfs, endpoint bindings, selected command +and protected inventory. Run only the packaged, release-matched static Reploy +probe in a read-only networkless inspection container; never start the workload +entrypoint, bootstrap shell, package manager or an image-provided inspector. + +Use an inspection-specific fixed create policy. Explicitly disable inherited +image healthchecks (`--no-healthcheck`) and every image-controlled automatic +execution path. Drop unnecessary capabilities, use no-new-privileges, fix the +trusted helper entrypoint and sanitize its execution environment. Validate image +volume declarations and the actual mount map before starting inspection. Reuse +the probe/workspace protocol, not the current container-create policy unchanged. + +Qualification must include an image whose enabled healthcheck emits an execution +marker: normal enabled execution is the positive control; public inspection must +leave that marker absent while returning its expected observations. Exercise the +same no-image-execution constraint on refusal and cancellation paths. This is a +design obligation; the current source profile has not been fixed by this document. + +Extend the existing probe for bounded path resolution, terminal type/digest and +required-absence observations. Resolve ancestor and final symbolic links with +explicit limits; do not equate a broken link, permission failure, non-regular +file or size-limit failure with absence. A required digest is computed from the +opened inspected regular file. No raw Bash or system-rc byte export is required. + +The immutable image preserves Bash, `/bin/sh`, loaders and image libraries; +OmegaFlow supplies no dependency inventory for those files. Read-only root is +necessary but not sufficient: Reploy must also reject effective mounts that hide +protected payload or image execution/configuration namespaces, including aliases +and automatic image-volume/engine mounts. It must protect required absence from +being filled by a mutable mount. + +Reploy owns deriving and validating that image namespace boundary. It includes +resolved invocation/loader paths and applicable execution/configuration lookup +roots, not only `/bin/bash` as a string. LLD must prove this for all three required +Bash profiles without a new general dependency-analysis service. If the boundary +cannot be enforced simply, revisit this architecture before calling a slice ready. + +Application data and `/run/omegaflow` sockets/FIFOs remain live. Hash neither +arbitrary video inputs nor transient socket contents. They cannot shadow the +protected namespace. Their ordinary runtime failures do not invalidate retained +protected contents. + +#### 4. Bind observations to existing generation admission + +Store the validated observation projection and its private comparison bindings +under existing deployment/generation metadata. Return a versioned opaque public +identifier for that record. Do not expose private generation/build/plan digests +or sign arbitrary caller-provided facts. No new global signing service or +credential authority is needed. + +Bind selected/final image identities, generation, protected capture, command and +all policy-relevant environment, identity, mount and endpoint facts. Bind the +inspection request and its observations. Exclude per-run ephemeral coordinates +such as newly allocated run IDs from the stable projection; their allowed +creation remains constrained by the same existing session plan. + +Expected identity is an optional comparison input on the existing public session +entry. The protected-consumer flow must supply it. Host Reploy loads the retained +record and derives the current projection itself under normal operation locks. +Unknown, malformed, oversized, unsupported-version, unavailable or mismatched +records refuse. A caller-written JSON report grants no admission. + +Queue admission can release and reacquire locks. Revalidate the selected state +and protected resource retention after those waits and before bootstrap; do not +rely on a check made only at initial load. Keep the final image and retained +resources pinned through actual use under existing session ownership. A missing +retained image/capture refuses instead of pulling a mutable alias as fallback. + +A public identity may be reused while its same bound generation/state remains +available and existing launch authorization allows it. It is not a single-use +credential. A generation or relevant state change requires fresh inspection. +Tag movement with the same retained image, original-source changes after capture +and live app-data changes do not alone invalidate it. Exact retention bounds, +record deletion and replay errors must be resolved in LLD. + +#### 5. Preserve the session contract across existing hosts + +The host retains admission and supervision authority on all platforms. The current +Linux-only host socket and watchdog launch are prerequisites to resolve, not +reasons to narrow the public host contract. + +Proposed portable control transport: use the existing pinned engine connection +and a trusted packaged controller helper over a private engine-attached stream. +Keep the controller-side Unix socket/broker inside the Linux controller container; +relay existing bounded session frames to Host Reploy without exposing an engine +socket, host listener or new network capability to application code. Host Reploy +still validates every operation against the same frozen authorization and owns +the workload PTY. The relay makes no policy decisions. + +Use one host-independent channel boundary if the proof supports it, preserving +the existing protocol and lifecycle semantics. Compare the change with keeping +the Linux route plus host-specific adapters before choosing the final LLD. Do +not silently add multiple transports or relax claim, peer, cancellation or +disconnect guarantees. Container-internal Linux helpers remain Linux binaries; +that is compatible with native Windows/macOS host Reploy. + +Keep the existing watchdog cleanup algorithm, immutable exact resource manifest, +incident receipts and endpoint pinning. Add the necessary native child-launch +and parent-liveness adapters; reuse existing Windows/macOS boot identities and +local Unix/named-pipe engine endpoints. Parent death must leave an independently +owned cleanup path with no broader resource authority. Platform process/handle +inheritance, engine loss/restart and recovery are proof gates, not inferred from +cross-compilation. A watchdog that disappears with its parent is not acceptable. + +### End-to-end journeys and failure behavior + +1. Select image and inspect inherited/application facts before reserved composition. +2. Compose native blueprint and prepare against that selected upstream identity. +3. Verify supplied expected bytes, incorporate them through normal build and + publish only a complete verified final generation. +4. Inspect final workload facts with trusted non-workload code; obtain the public + immutable comparison identity and apply consumer policy. +5. Invoke existing controlled-session entry with expected identity. Revalidate + current state after admission waits, then start only the frozen owned plan. +6. Complete or cancel through the existing lifecycle. Release resources and keep + only generation-reachable artifacts and required recovery receipts. + +Capture/probe failure produces no admitted record. Stale/malformed admission +refuses before bootstrap and cleans its reservations/inert resources. Concurrent +rebuild cannot retarget a pending or live run. Parent loss invokes exact owned +cleanup; daemon unavailability retains recoverable ownership and incidents rather +than claiming containers were removed. No refusal test passes unless it also +checks that bootstrap did not begin where required. + +### Alternatives and proportionality + +| Alternative | Assessment | +| --- | --- | +| Verified private copy plus read-only source bind | Small on native Linux and the narrow WSL proof passed. Cross-platform delivery still needs mode, path-sharing, alias, lifetime and cleanup proofs. Prefer normal immutable-image delivery for one portable retained-byte boundary. | +| Protected files in existing generated image | Proposed: reuse build/verification/generation ownership, preserve exact paths/modes, remove later source mutation from the launch dependency. Requires a generic input/graph cut and final inventory verification. | +| Offline general image filesystem reconstruction | Avoid as the primary path: existing account-file archive reader is intentionally narrow; general layer/link/whiteout semantics would add substantial parser work. Reuse trusted probe instead. | +| Host-specific sockets and a separate portability implementation | Compare with engine-attached transport during LLD; retain multiple paths only if the proof and cost of replacing the existing route justify them. | +| New snapshot service, broker authority or permanent daemon | No requirement justifies them; not proposed. | + +The initial responsibilities estimate is historical. Payload delivery and portable +session prerequisites must be sized from actual engineering cuts. Do not label +them test-only qualification work or hide them in an integration-only final slice. + +### Requirement coverage + +| Requirement | Owning architectural responsibility and observable acceptance | +| --- | --- | +| R1 | Retained selected upstream descriptor through ordinary preparation; tag movement cannot substitute image B for selected A. | +| R2 | Separate inherited/application/final environment; forbidden inherited values remain visible and private configured values remain absent. | +| R3 | Verified final plan projection and trusted-only probe; workload/bootstrap execution marker remains absent during inspection. | +| R4 | Bounded path/type/hash/absence probe; explicit link, type, unreadable and over-limit failures. | +| R5 | Expected-hash capture plus separately bound manifest, normal-build final inventory check; substitution and capture races refuse. | +| R6 | Immutable generation payload with read-only runtime and namespace/mount protection; post-capture source changes cannot replace it. | +| R7 | Explicit live data and session-resource paths; mutation is ordinary runtime behavior and cannot shadow protected state. | +| R8 | Public opaque comparison record at existing locked admission; caller-written facts cannot authorize launch. | +| R9 | Stable actual-state projection, post-wait revalidation and retained resources; paired success/refusal tests distinguish external reference movement from actual bound changes. | +| R10 | Existing generation reachability, leases, native supervision and exact cleanup/recovery; no leaked active workload or reservation after required cancellation/refusal paths. | +| R11 | Complete public path on supported native hosts and WSL2/Desktop, with exact versions/paths and actual release adoption by OmegaFlow. | + +### Engineering gates before LLD readiness + +- Prove selected-image retention and environment provenance through normal builds. + Resolve duplicate inherited environment entries and private-value redaction. +- Define generic protected-file declaration, inventory/manifest trust, safe native + source opening, deterministic modes/archive and exact final-image verification. + Specify numeric limits and preserve source-change independence. +- Prove component-aware observation and image execution/lookup namespace protection, + including hidden mounts, automatic volumes, absence and aliases. The three + required Bash profiles cannot silently become unsupported. +- Prove the proposed engine-mediated private stream preserves the existing claim, + framing, controller identity, disconnect and lifecycle boundaries. Compare the + simpler retained-route alternative before committing to a transport replacement. +- Prove native watchdog child survival, private handles, parent-loss detection, + receipt ownership and exact cleanup on Windows and macOS; retain Linux parity. +- Specify opaque identity encoding, bounded record storage, lifetime/replay, + generation reachability, post-queue comparison and race-free use. +- Define and obtain full native-host plus WSL2/Desktop acceptance evidence for + success/refusal/cancellation/parent-loss/engine-loss/cleanup and real filesystem + classes. Build/smoke passes and the protected-copy fixture cannot substitute. +- Produce the complete slice inventory with production/configuration and test-code + estimates, totals and the agreed changed-physical-line counting convention. + Shared portability foundations have one owning prerequisite. No working-hour + estimates; no deferred consumer obligation without owner agreement. + +Failure of a gate can invalidate its proposed mechanism or estimates. Reassess +before delivery rather than accumulate exceptions or claim readiness. Reviewed +HLD acceptance permits detailed engineering; it does not by itself approve an unresolved +LLD, implementation, commits, publication or release. + +Optional host endpoint publication remains a separate dependency. This design +does not activate mapped execution, resume E2.3 or recover the OmegaFlow campaign. +Consumer acceptance also requires qualification against an explicitly selected +compatible Reploy release. + +### Supporting material + +- [Source investigation and narrow mechanism proof](supporting/omegaflow-rp-c6-high-level-design/source-investigation.md) +- [Existing public-host contract and qualification evidence](supporting/omegaflow-rp-c6-high-level-design/platform-qualification.md) +- [Observed local versions and filesystem paths](supporting/omegaflow-rp-c6-high-level-design/local-proof-environment.json) +- [Maintainer platform clarification](supporting/omegaflow-rp-c6-high-level-design/platform-contract-clarification.json) +- [Preserved requirements-phase workflow document](supporting/omegaflow-rp-c6-high-level-design/requirements-workflow-preimage.txt) +- [Document and estimate contract](supporting/omegaflow-rp-c6-requirements/design-contract.md) diff --git a/docs/consumers/supporting/omegaflow-rp-c6-high-level-design/hld-approval.json b/docs/consumers/supporting/omegaflow-rp-c6-high-level-design/hld-approval.json new file mode 100644 index 00000000..ac2e224d --- /dev/null +++ b/docs/consumers/supporting/omegaflow-rp-c6-high-level-design/hld-approval.json @@ -0,0 +1,36 @@ +{ + "schema_version": 1, + "kind": "relayed-reviewed-HLD-approval", + "recorded_at": "2026-10-29T20:50:44.098211+00:00", + "source": "User message in this conversation relaying architecture approval; original speaker label retained without claiming independent authentication.", + "message_label_as_received": "OmegaConf", + "topic_resolved_from_context": "OmegaFlow RP-C6, unchanged", + "message": "Approve this architecture as the basis for LLD engineering and slice planning. Keep the namespace-protection and portable transport/watchdog proofs as explicit readiness gates. Size those prerequisites separately and replace the historical estimate. If proof requires materially broader mechanisms or weaker guarantees, return for architecture review before implementation. Reconcile OmegaFlow\u2019s older bind-specific assumptions before consumer adoption.", + "run_id": "run_3k0spmw1cd3w8pmjsq65ggeese", + "responsible_prompt_stage": "f01-s21-block-the-responsible-hld-approval-gate-", + "human_gate": "f01-s22-user-gate-before-retain-explicit-human-h", + "request": "/home/omry/.local/state/awd/reploy-E-resume-20261028/OmegaFlow-hld-approval-request.json", + "request_sha256": "27783994d45bb30dff1177e46f4d9d485e0c1ad89649fe79230fe879219962fd", + "approved_artifacts": { + "docs/consumers/omegaflow.md": "348371b18433691d73b3589ff6502b817bef1cc40dfedf197a8c39ded646337e", + "docs/consumers/omegaflow-rp-c6-high-level-design.md": "6f3a958997df277d79f4423af8206c5396441da006346b83308d7cb9b598472b", + "docs/consumers/omegaflow-rp-c6-requirements.md": "c1c823193042e0ce513d175fffafe2add489bc49bf56cfad61401302029ef9c6" + }, + "approved_scope": "Current reviewed architecture as the basis for LLD engineering and slice planning", + "conditions": [ + "Namespace protection remains an explicit readiness gate.", + "Portable transport and native watchdog proof remains an explicit readiness gate.", + "Size prerequisites separately; replace historical estimate with current bottom-up production/configuration and test-code ranges plus totals.", + "Materially broader mechanisms or weaker guarantees require architecture review before implementation.", + "Reconcile older bind-specific consumer assumptions before adoption." + ], + "not_approved": [ + "LLD", + "implementation-ready slices", + "implementation", + "commit", + "publication", + "release" + ], + "review_stamp": false +} diff --git a/docs/consumers/supporting/omegaflow-rp-c6-high-level-design/local-proof-environment.json b/docs/consumers/supporting/omegaflow-rp-c6-high-level-design/local-proof-environment.json new file mode 100644 index 00000000..c4d3ebf5 --- /dev/null +++ b/docs/consumers/supporting/omegaflow-rp-c6-high-level-design/local-proof-environment.json @@ -0,0 +1,91 @@ +{ + "scope": "Observed local mechanism-proof environment, not full public acceptance", + "kernel": "6.18.54.1-microsoft-standard-WSL2", + "process_platform": "Linux-6.18.54.1-microsoft-standard-WSL2-x86_64-with-glibc2.39", + "checkout": "/home/omry/dev/reploy", + "proof_workspace": "/home/omry/dev/reploy/temp/omegaflow-hld-copy-0bzst26e", + "original_source": "/home/omry/dev/reploy/temp/omegaflow-hld-copy-0bzst26e/original", + "retained_capture": "/home/omry/dev/reploy/temp/omegaflow-hld-copy-0bzst26e/capture", + "retained_file": "/home/omry/dev/reploy/temp/omegaflow-hld-copy-0bzst26e/capture/payload", + "container_path": "/runtime/payload", + "read_only_mount_target": "/runtime", + "proof_result": "/home/omry/.local/state/awd/reploy-E-resume-20261028/OmegaFlow-hld-protected-copy-proof-result.json", + "commands": [ + { + "argv": [ + "docker", + "version", + "--format", + "{{json .}}" + ], + "exit_code": 0, + "stdout": "{\"Client\":{\"Version\":\"29.8.1\",\"ApiVersion\":\"1.56\",\"DefaultAPIVersion\":\"1.56\",\"GitCommit\":\"4a63305\",\"GoVersion\":\"go1.26.8\",\"Os\":\"linux\",\"Arch\":\"amd64\",\"BuildTime\":\"Tue Sep 15 16:24:42 2026\",\"Context\":\"default\"},\"Server\":{\"Platform\":{\"Name\":\"Docker Desktop 4.93.0 (240920)\"},\"Version\":\"29.8.1\",\"ApiVersion\":\"1.56\",\"MinAPIVersion\":\"1.40\",\"Os\":\"linux\",\"Arch\":\"amd64\",\"Components\":[{\"Name\":\"Engine\",\"Version\":\"29.8.1\",\"Details\":{\"ApiVersion\":\"1.56\",\"Arch\":\"amd64\",\"BuildTime\":\"Tue Sep 15 16:25:38 2026\",\"Experimental\":\"false\",\"GitCommit\":\"464cd50\",\"GoVersion\":\"go1.26.8\",\"KernelVersion\":\"6.18.54.1-microsoft-standard-WSL2\",\"MinAPIVersion\":\"1.40\",\"Module\":\"github.com/moby/moby/v2\",\"ModuleVersion\":\"v2.0.0+unknown\",\"Os\":\"linux\"}},{\"Name\":\"containerd\",\"Version\":\"v2.3.5\",\"Details\":{\"GitCommit\":\"1294c24a7da8e5a793ed378161673abe94118892\"}},{\"Name\":\"runc\",\"Version\":\"1.5.1\",\"Details\":{\"GitCommit\":\"v1.5.1-0-g8f2685a4\"}},{\"Name\":\"docker-init\",\"Version\":\"0.19.0\",\"Details\":{\"GitCommit\":\"de40ad0\"}}],\"GitCommit\":\"464cd50\",\"GoVersion\":\"go1.26.8\",\"KernelVersion\":\"6.18.54.1-microsoft-standard-WSL2\",\"BuildTime\":\"2026-09-15T16:25:38.000000000+00:00\"}}\n", + "stderr": "" + }, + { + "argv": [ + "docker", + "info", + "--format", + "{\"os_type\":{{json .OSType}},\"architecture\":{{json .Architecture}},\"operating_system\":{{json .OperatingSystem}},\"docker_root_dir\":{{json .DockerRootDir}}}" + ], + "exit_code": 0, + "stdout": "{\"os_type\":\"linux\",\"architecture\":\"x86_64\",\"operating_system\":\"Docker Desktop (containerized)\",\"docker_root_dir\":\"/var/lib/docker\"}\n", + "stderr": "" + }, + { + "argv": [ + "docker", + "context", + "inspect", + "--format", + "{{json .Endpoints.docker.Host}}" + ], + "exit_code": 0, + "stdout": "\"unix:///var/run/docker.sock\"\n", + "stderr": "" + }, + { + "argv": [ + "findmnt", + "-J", + "-T", + "/home/omry/dev/reploy/temp/omegaflow-hld-copy-0bzst26e", + "-o", + "TARGET,FSTYPE,SOURCE" + ], + "exit_code": 0, + "stdout": "{\n \"filesystems\": [\n {\n \"target\": \"/\",\n \"fstype\": \"ext4\",\n \"source\": \"/dev/sdd\"\n }\n ]\n}\n", + "stderr": "" + }, + { + "argv": [ + "go", + "version" + ], + "exit_code": 0, + "stdout": "go version go1.26.8 linux/amd64\n", + "stderr": "" + }, + { + "argv": [ + "wsl.exe", + "--version" + ], + "exit_code": 1, + "stdout": "", + "stderr": "<3>WSL (3447587 - ) ERROR: UtilAcceptVsock:281: accept4 failed 110\n" + }, + { + "argv": [ + "cmd.exe", + "/c", + "ver" + ], + "exit_code": 1, + "stdout": "", + "stderr": "<3>WSL (3448526 - ) ERROR: UtilAcceptVsock:281: accept4 failed 110\n" + } + ], + "distro_os_release": "PRETTY_NAME=\"Ubuntu 24.04.4 LTS\"\nNAME=\"Ubuntu\"\nVERSION_ID=\"24.04\"\nVERSION=\"24.04.4 LTS (Noble Numbat)\"\nVERSION_CODENAME=noble\nID=ubuntu\nID_LIKE=debian\nHOME_URL=\"https://www.ubuntu.com/\"\nSUPPORT_URL=\"https://help.ubuntu.com/\"\nBUG_REPORT_URL=\"https://bugs.launchpad.net/ubuntu/\"\nPRIVACY_POLICY_URL=\"https://www.ubuntu.com/legal/terms-and-policies/privacy-policy\"\nUBUNTU_CODENAME=noble\nLOGO=ubuntu-logo\n" +} diff --git a/docs/consumers/supporting/omegaflow-rp-c6-high-level-design/platform-contract-clarification.json b/docs/consumers/supporting/omegaflow-rp-c6-high-level-design/platform-contract-clarification.json new file mode 100644 index 00000000..beb268c1 --- /dev/null +++ b/docs/consumers/supporting/omegaflow-rp-c6-high-level-design/platform-contract-clarification.json @@ -0,0 +1,29 @@ +{ + "kind": "existing-product-platform-contract-clarification", + "recorded_at": "2026-10-29T19:54:37.593375+00:00", + "source": "Maintainer messages in this conversation", + "messages": [ + "Include my current setup in the first delivery: Reploy running inside WSL2, using Docker Desktop\u2019s Linux-container engine. Record the tested versions and filesystem locations.", + "This is meant for public use. WSL and general Windows, Linux and Mac support.", + "nothing new here I think. Reploy is already for all those environments." + ], + "resolved_stage": "f01-f03-s03-distinguish-settled-owner-decisions-from", + "disposition": "Inherit existing public Reploy host support. The agent incorrectly treated platform support as a new owner choice. WSL2/Desktop is one required qualification case, not the entire delivery cohort.", + "hosts": [ + "native Windows", + "WSL2", + "Linux", + "native macOS" + ], + "workloads": "Linux containers; first OmegaFlow qualified workload remains linux/amd64", + "acceptance": "Complete public inspection -> admission -> launch with success, relevant refusal/no-bootstrap, cancellation and cleanup cases on supported host/engine combinations. Retain exact versions, architecture and filesystem/storage locations. Keep identical integrity guarantees.", + "not_included": [ + "Windows-container workloads", + "Podman", + "rootless engines", + "remote engines" + ], + "requirements_approval": "Reuse unchanged requirements R1-R11 and prior actual approval; this instruction clarifies existing host coverage and required qualification without approving an HLD, LLD or implementation.", + "hld_approved": false, + "implementation_authorized": false +} diff --git a/docs/consumers/supporting/omegaflow-rp-c6-high-level-design/platform-qualification.md b/docs/consumers/supporting/omegaflow-rp-c6-high-level-design/platform-qualification.md new file mode 100644 index 00000000..4b42e778 --- /dev/null +++ b/docs/consumers/supporting/omegaflow-rp-c6-high-level-design/platform-qualification.md @@ -0,0 +1,70 @@ +# Public-host qualification contract + +Reploy already supports Linux, macOS and Windows as product hosts; WSL2 with +Docker Desktop is also an explicitly required first-delivery case. This design +inherits that commitment. It does not present those hosts as a new product-scope +expansion. See [the maintainer clarification](platform-contract-clarification.json). + +The first OmegaFlow workload profiles remain Linux/amd64. Host architecture, +container architecture and emulation are separate facts. A Linux guest or WSL +invocation does not establish native Windows or native macOS client support. +Linux-container engines remain the runtime model. Podman, rootless, remote +engines and Windows-container workloads are not added by this request. + +## Required public acceptance + +Every supported host/engine case must qualify the public inspection -> expected +state admission -> launch path, including nominal completion, malformed/stale +refusals before bootstrap, capture substitution and mount-shadow refusal, +concurrent replacement, cancellation, parent loss, interrupted cleanup and exact +owned-resource recovery. Do not lower integrity guarantees to obtain a pass. +The protected-copy fixture proves one mechanism only and is not acceptance. + +Record exact Reploy source/release, host OS/build/kernel, client and server engine +versions, Desktop version where applicable, host/container architecture and +emulation, selected immutable images, and the observed filesystem locations and +types for source inputs, private retained storage, staging/deployments and +container paths. State whether locations are WSL ext4, Windows-backed/DrvFS, +Windows native storage, macOS storage or engine-managed Linux storage. Do not +claim one filesystem result for another. A location class needs its real path +semantics/alias/permission/cleanup evidence; supported paths cannot silently fall +back to weaker verification. Preserve existing install-scope differences. + +Current CI has native Linux/macOS target smoke and Windows host smoke, but +Windows smoke explicitly skips Docker. Existing CI success therefore does not +establish this new complete public path on Desktop. Plan explicit native-host +engine qualification; unavailable execution access remains an evidence gap, +not permission to drop the host. + +## Observed local proof environment + +See [the exact observed record](local-proof-environment.json). The dummy proof +ran from WSL2 Ubuntu 24.04.4, kernel 6.18.54.1-microsoft-standard-WSL2, with Docker +client/engine 29.8.1 and Docker Desktop 4.93.0 (240920), Linux/amd64 containers. +Its source and retained copy were on WSL ext4 under +`/home/omry/dev/reploy/temp/omegaflow-hld-copy-0bzst26e/`, at `original` and +`capture/payload`; container path was `/runtime/payload`. The local endpoint was +`unix:///var/run/docker.sock`; Docker reported `/var/lib/docker` inside its engine +storage. This does not test Windows-backed paths, native Windows or macOS. + +`wsl.exe --version` and `cmd.exe /c ver` failed through the current interop with +`UtilAcceptVsock ... accept4 failed 110`. WSL package and Windows host build +versions were not obtained; do not invent them. Record them in final public +qualification through a working native path. + +## Existing path-specific engineering gaps + +- `internal/controlledsession/channel_unsupported.go` and + `internal/dockerdeploy/controlled_session_controller_channel_unsupported.go` + currently reject non-Linux host private channels. The Linux path relies on a + host Unix socket, POSIX ownership and peer credentials crossing a bind mount. +- `internal/dockerdeploy/controlled_session_watchdog_unsupported.go` rejects + non-Linux watchdog launch. The existing Linux child uses inherited files and + a detached process session. Preserve parent-loss cleanup on native hosts. +- Local endpoint selection already understands Unix sockets and Windows named + pipes; boot-session identities already exist for Linux, macOS and Windows. + Reuse them rather than creating replacements. + +These are concrete prerequisites in this feature path, not evidence that Reploy +has no general Windows/macOS support. Container-internal Linux helpers are not +host portability gaps merely because their source files have Linux build tags. diff --git a/docs/consumers/supporting/omegaflow-rp-c6-high-level-design/requirements-workflow-preimage.txt b/docs/consumers/supporting/omegaflow-rp-c6-high-level-design/requirements-workflow-preimage.txt new file mode 100644 index 00000000..f626e67e --- /dev/null +++ b/docs/consumers/supporting/omegaflow-rp-c6-high-level-design/requirements-workflow-preimage.txt @@ -0,0 +1,246 @@ +--- +status: Evaluation pending +updated: 2026-10-29 +summary: OmegaFlow preparation inspection and launch admission needs; minimum Reploy delivery remains undecided. +--- + +# OmegaFlow + +## Design outputs + +The active `global:swe:design` run retains this consumer record and its required +tracking. Its additional outputs follow the +[design document contract](supporting/omegaflow-rp-c6-requirements/design-contract.md): +`omegaflow-rp-c6-requirements.md`, `omegaflow-rp-c6-high-level-design.md`, and +`omegaflow-rp-c6-implementation-plan.md`, alongside this file. Each is authored +at its responsible phase; the architecture and slice plan are not yet approved. +Durable supporting material belongs under `supporting//`. +Feedback for later AWD improvements is collected in +[design workflow feedback](supporting/omegaflow-rp-c6-requirements/design-workflow-feedback.md). + +The current [requirements draft](omegaflow-rp-c6-requirements.md) carries the full +corrected RP-C6 scope. Its +[interview synthesis](supporting/omegaflow-rp-c6-requirements/interview-synthesis.md) +separates existing project constraints from engineering investigations. Formal +requirements review and approval remain pending; no HLD, implementation plan or +delivery readiness is implied. + +## Use case and source + +OmegaFlow needs to inspect the workload it will launch, evaluate its own policy, +and launch exactly that inspected preparation. Reploy must reject relevant +changes before workload or bootstrap execution begins. + +Source: the 2026-10-29 planning draft in the OmegaFlow checkout, +`temp/part-c-delivery/implementation-through-C6.1/RP-C6-HANDOFF-PLANNING.md` +(read from `/home/omry/dev/omegaflow`), corrected by the maintainer-relayed +OmegaFlow scope clarification on 2026-10-29. The clarification below takes +precedence over the earlier handoff where they differ. These are consumer +requirements, not an approved Reploy API or an installed-release conformance +claim. + +The subsequent [OmegaFlow clarification](supporting/omegaflow-rp-c6-requirements/consumer-clarifications.md) +removes raw Bash/system-rc byte export from the pending scope and makes +invalidation depend on changes to the bound prepared state. It takes precedence +over older byte-export or unconditional tag-change language in source evidence +and preliminary estimates. + +## Corrected ownership and supplied-input scope + +OmegaFlow defines the blueprint; Reploy delivers and enforces it. Bash, `/bin/sh`, +loaders and libraries supplied by the workload image remain Reploy's +responsibility. OmegaFlow does not need to enumerate or snapshot that image +dependency closure. OmegaFlow owns compatibility checks against its qualified +Bash build table. Reploy must expose the resolved Bash and selected system-rc +facts for the generation actually launched. The selected system-rc path must be +absent; the consumer reports `/etc/bash.bashrc` for all three current profiles. + +For consumer-supplied inputs, OmegaFlow reports a complete expected-SHA-256 +inventory of 18 payload files plus `manifest.json`, approximately 7.9 MiB total: + +- `bin/envoy` and `bin/awsh`; helper commands use the same Awsh executable; +- `etc/awsh-bashrc`, `etc/inputrc` and `etc/bash-builds.json`; +- one terminal database entry and 12 locale files; and +- `manifest.json`, with its expected digest supplied separately. + +Retain established paths under `/omegaflow-runtime`. These are regular files +without symbolic-link or hardlink aliases. The reported staged modes are `0555` +for directories/executables and `0444` for data. The workload needs read/execute +access; source numeric UID/GID preservation is not required. The adapter rcfile +sources no additional startup files. These inventory facts are consumer-reported, +not independently verified measurements in this record. + +Protected copies are acceptable. Verify the bytes actually retained against the +supplied expected hashes, then deliver those exact contents at the declared +paths. Computing fresh hashes without checking the supplied expectations could +accept inputs mutated before capture. Once an independent protected capture +exists, changes to its original source need not invalidate it. Enforce explicit +size bounds and reject unsupported sizes. Copying is an implementation candidate, +not a requirement to introduce a general filesystem snapshot service. + +Distinguish protected supplied inputs from unprotected application data. Videos +and other application data can remain live; mutation, disappearance and processing +errors are acceptable ordinary runtime failures. `/run/omegaflow` remains writable +for live sockets and FIFOs. Those resources are not protected startup payload. + +Protect retained runtime contents against source mutation after verification, +workload writes and mount shadowing through Reploy delivery machinery. File +permissions alone do not establish the boundary. Hostile-host-root containment +and stronger same-identity isolation are outside the clarified requirement. + +## Requirements and acceptance + +1. Select the workload image through existing public preparation machinery. + Observe its immutable identity and inherited environment, and evaluate image + plus application environment before OmegaFlow adds reserved composition + values. Forbidden inherited values must not disappear from observation. +2. Compose final native blueprints through OmegaFlow's existing Hydra entry and + prepare with the same selected image. Reject image replacement rather than + silently changing composed YAML or reusing checks for another image. +3. Inspect the prepared generation's final image/platform, effective environment, + execution identity, mounts, endpoints, resolved executable path/type/hash and required + selected system-rc absence. Keep configured private environment values private. + Define bounded metadata/hash/absence evidence, safe path resolution, and explicit + absent, symbolic-link, non-regular-file and error behavior. Inspection must + not start bootstrap or execute untrusted workload code. +4. Bind the observations to one public immutable identity. Accept that expected + identity at controlled-session admission, using Reploy's existing ownership + and cleanup. Bind the protected supplied-input capture and relevant image + facts through admission and use; pinning only the image is insufficient. +5. Prove public inspection and public launch work together. Relevant rebuilds, + changes to the selected immutable image, bound blueprint/environment/mount facts, + protected content or selected generation must invalidate stale facts. Moving an + original tag while the inspected immutable image is retained and launched does + not by itself invalidate the binding. Source changes after an independent + verified capture and changes to unprotected application data need not invalidate + that capture. Each stale case must prove + bootstrap did not start. Malformed, + oversized, unknown-version and forged identities must fail closed; + interruptions must leave no active workload or leaked reservation. +6. Retain the exact release/source identity, public contract and native test + evidence. Qualify OmegaFlow against an explicitly selected compatible release + before claiming the consumer is unblocked. + +## Current support and gaps + +The Reploy source inspection on 2026-10-29 identified reusable internal generation +and build identities in [controlled-session planning](../../internal/dockerdeploy/controlled_session_plan.go), +and executable hash, ownership, permission and symbolic-link observations in the +[probe protocol](../../internal/probe/protocol.go). These do not establish the +complete public inspection/admission contract above. The inspected +[public launch options](../../internal/cli/controlled_session.go) do not accept +the consumer's expected preparation identity. Existing executable metadata/hash +observations do not establish the complete public absence and admission contract. +The current scope does not require raw Bash or system-rc byte export; see the +[consumer clarifications](supporting/omegaflow-rp-c6-requirements/consumer-clarifications.md). + +The [controlled-session design](../CONTROLLED_SESSION_DESIGN.md) keeps internal +generation/build/plan digests out of the public session stream. A separate +preparation interface with an opaque public binding is a candidate, not a +selected design. Reuse existing preparation, immutable-image selection, build +verification, inspection and session admission. Do not add a parallel image +selector, inspection daemon, receipt authority or build pipeline. + +Reploy owns generic facts, image delivery, protected supplied-input delivery and +admission. OmegaFlow owns its reserved environment policy, Bash compatibility +checks, supplied runtime contents, mount acceptance policy and recording behavior. + +## Separate endpoint dependency + +The handoff reports that optional host publication for private endpoints is +already known Reploy backlog work. Its exact backlog item is not yet confirmed; +do not create a duplicate. Related endpoint-address and network-policy items are +not an exact match. Existing private controlled-session networking must remain +distinct from the native-blueprint validation gap reported for OmegaFlow's +selected installed release. + +The handoff reports this dependency blocks C6.1 acceptance. RP-C6 separately +blocks C6.2/C6.3 and dependent launch acceptance. Resolving one does not prove the +other is resolved. + +## Delivery decision and next step + +**Minimum delivery: undecided.** Evaluate which acceptance checks are essential +to unblock RP-C6 and recommend the smallest coherent contract from the actual +code. Produce bottom-up production/test estimates, proposed delivery cuts, +acceptance evidence and release/adoption prerequisites. Any deferred consumer +requirements need explicit consumer agreement; do not silently weaken the +launch guarantee to make the delivery smaller. + +Resolve image selection through final preparation, protected-input capture, +private-value handling, identity lifetime, cancellation, concurrent replacement, +platform support, bounds and errors during design. Review the resulting design +through the required local deep design review and remote PR cycle before +implementation. Return to design if costs or mechanisms expand. + +## Progress and evidence + +### Revised preliminary size estimate, 2026-10-29 + +This is a source-based planning estimate, not a reviewed LLD, measured result or +approved set of slices. Counts are added plus removed lines; tests include +fixtures. Documentation, review bookkeeping, generated output, release execution +and OmegaFlow-side integration are excluded. + +| Responsibility | Production LOC | Test/fixture LOC | +| --- | ---: | ---: | +| Bind selected image through preparation; inherited/application/final environment observations | 250–400 | 400–650 | +| Bounded resolved-Bash inspection/export and selected system-rc absence evidence | 300–450 | 600–900 | +| Generic protected supplied-input declaration/capture, expected-hash verification, exact path/mode delivery and mount protection | 350–550 | 700–1150 | +| Expected preparation identity at existing admission; stale-state refusal and capture lifetime/cleanup | 250–400 | 500–850 | +| Public CLI/schema integration and end-to-end inspection/launch qualification | 150–250 | 500–800 | +| **Total** | **1300–2050** | **2700–4350** | + +Expect approximately four to six implementation PRs after design, subject to +coherent cuts and the repository's production-size limits. These rows are +responsibilities, not approved task IDs. The superseded estimate was 1550–2500 +production and 3200–5200 test LOC. The narrower inventory and protection boundary +reduce estimated work and uncertainty; they do not establish implementation +readiness or a measured saving. + +The estimate assumes reuse of the existing controlled-session platform and +ownership model, the consumer's explicit bounded payload inventory and supplied +expected hashes, and reuse of existing artifact storage/materialization where +it meets the required delivery boundary. The public API and delivery mechanism +remain undecided. It does not estimate a general mutable-tree +snapshot service, a new image-selection pipeline, remote-engine support, +multi-identity activation or private-environment injection. Unsupported inputs +must refuse; a read-only bind or permission change alone is not a substitute for +protected delivery. If necessary protection cannot fit this scope, resolve +the design and re-estimate before committing to delivery. + +Basis: [current session admission](../../internal/dockerdeploy/current_controlled_session_run.go) +already loads verified current builds under both deployment locks and owns queue +leases; [runtime input handling](../../internal/dockerdeploy/current_runtime_files.go) +validates generated inputs under the operation lock. Those locks do not by +themselves prevent external bind-source mutation. The +[image inspector](../../internal/dockerdeploy/docker_image_inspect.go) already +extracts inherited environment, while the [probe](../../internal/probe/protocol.go) +returns executable metadata/hashes but still needs the complete bounded public +inspection/absence and admission semantics. The historical estimate above included +byte export, which the consumer subsequently removed from the required scope. +The [artifact store](../../internal/providerstore/store.go) already offers +`PublishExpected`, which compares retained bytes against an expected descriptor +before atomic publication. That is a reuse candidate, not proof of complete +runtime delivery, reachability/cleanup integration or mount-shadow resistance. +No new runtime proof or tests ran for this estimate. + +Optional host endpoint publication remains a separately identified dependency +with an unconfirmed exact backlog item; its cost is excluded. Delivery of RP-C6 +alone therefore does not claim to unblock all OmegaFlow acceptance. + +### Delivery status + +- Maintainer priority on 2026-10-29: once the global helper blocker is fixed, + finalize E2.2 through PR approval, then pause E before E2.3 and run + `global:swe:design` for this consumer record. Follow its requirements, HLD and + LLD review/approval gates; stop before implementation. The remaining E slices + stay unfinished and preserved. +- Evaluation is queued in [the backlog](../BACKLOG.md); no delivery cuts, + implementation, release selection or consumer qualification are approved. +- This is separate from milestone E and does not expand its delivery scope. +- The source handoff reports C6.1 preserved and unaccepted, with two unresolved + ownership findings. Those campaign conditions have not been independently + revalidated here. It authorizes no campaign recovery or dependency upgrade. +- After prerequisite delivery and release selection, OmegaFlow must use its + reviewed dependency-adoption and guarded campaign-recovery path. diff --git a/docs/consumers/supporting/omegaflow-rp-c6-high-level-design/source-investigation.md b/docs/consumers/supporting/omegaflow-rp-c6-high-level-design/source-investigation.md new file mode 100644 index 00000000..2269a2b7 --- /dev/null +++ b/docs/consumers/supporting/omegaflow-rp-c6-high-level-design/source-investigation.md @@ -0,0 +1,109 @@ +# RP-C6 HLD source investigation + +This is supporting design evidence, not the HLD or implementation approval. +Requirements were reviewed clean and remain unchanged. No product source changed. + +## Existing primitives and gaps + +| Responsibility | Existing source | Reuse and missing work | +| --- | --- | --- | +| Selected immutable image | `internal/deploy/image.go`, `internal/dockerdeploy/docker_image_inspect.go`, `provider_base_prepare.go` | Existing descriptor binds config/rootfs/platform. Add public selection facts and carry the exact selection through normal build; current cached author-reference resolution is not the new retained-selection contract. | +| Environment provenance | `internal/dockerdeploy/docker_image_inspect.go` | Raw image Env is normalized into sorted unique BaseConfig entries. Retain inherited/application/final layers for consumer evaluation and keep private values outside reports. | +| Non-workload inspection | `internal/dockerdeploy/probe_run.go`, `probe_workspace.go`, `internal/probe/inspect_linux.go` | Existing read-only, networkless validation container starts the packaged fixed Go helper, not the image entrypoint. Extend bounded path/type/hash/absence observations; current resolver does not by itself establish complete ancestor-link or required-absence semantics. | +| Supplied-byte capture | `internal/providerstore/store.go` | PublishExpected compares streamed retained bytes before publication. OpenVerifiedArtifact preserves the opened file across pathname replacement. A protected tree still needs inventory, independent file materialization and publication/reachability ownership. | +| Runtime delivery | `internal/dockerdeploy/controlled_session_plan.go`, `current_runtime_files.go` | Current session already requires read-only root, drops capabilities and renders explicit mounts, private metadata masks and fixed startup verifier. Reuse protected read-only bind projection with independent capture, no writable alias and no shadowing; mode changes alone are insufficient. | +| Admission | `internal/dockerdeploy/current_controlled_session_run.go` | Loads verified current runtimes under sorted deployment locks. Queue await can release/reacquire ownership. Expected prepared state must be checked again after waiting and before effects, not only at initial load. | +| Lifetime and cleanup | Existing generation references, provider store reachability and session leases | Bind captures and inspection records to existing generation/session ownership; add their exact reachability rather than a second authority service. | + +## Smallest alternatives under investigation + +1. A verified private copy, mounted read-only through the existing runtime plan, + is the smallest candidate for supplied runtime files. Reuse the authored mount + target and replace only the physical delivery source with retained bytes. + Keep expected inventory/manifest binding generic; no OmegaFlow names in Reploy. +2. Baking payload into the normal generated image is an existing packaging + candidate, but adds image/build-lock integration and destination checks. It is + not needed merely to obtain independent copied bytes; prefer the direct copy + if the complete alias, mount, lifetime and qualification proofs hold. +3. A general filesystem snapshot service, inspection daemon or new receipt + authority has no demonstrated need and is excluded by the requirements. + +Image files remain Reploy-owned. Read-only root is useful but does not by itself +prevent a mutable mount from hiding image code or creating relevant startup +files. HLD/LLD must define a generic image-code/lookup namespace boundary and +mount-overlap checks, including source aliases and automatic engine mounts. Do +not ask OmegaFlow for a loader/library inventory. Do not claim the existing +executable probe or the narrow proof below solves this boundary. + +## Bounded evidence actually run + +Two existing production-primitive tests passed with count=1: + +- TestOpenVerifiedArtifactKeepsTheVerifiedFileAfterPathReplacement +- TestStorePublishExpectedRejectsChangedBytesBeforeBlobPublication + +Command: `go test ./internal/providerstore -run '^(TestOpenVerifiedArtifactKeepsTheVerifiedFileAfterPathReplacement|TestStorePublishExpectedRejectsChangedBytesBeforeBlobPublication)$' -count=1` + +A disposable scratch image contained only a trusted static Go fixture. Host +preparation copied a dummy file to a distinct inode, verified its expected digest +and then changed the original. A read-only bind into a read-only-root container +preserved the retained digest. Root inside that container, with all capabilities +dropped and no-new-privileges, received EROFS for overwrite, chmod, rename and +creation, and EPERM for remount. Exact owned container and image cleanup passed. + +Proof environment: Docker 29.8.1, Linux/x86_64 daemon, **Docker Desktop +(containerized)**, local Unix socket. This is not native Linux or rootless, +Podman, remote-engine or full Reploy public-path qualification. The fixture does +not prove shadowing/alias rejection, image lookup protection, crash cleanup or +capture-race behavior. It does not change Reploy platform support. + +Private original result: `/home/omry/.local/state/awd/reploy-E-resume-20261028/OmegaFlow-hld-protected-copy-proof-result.json` +Private proof source: `/home/omry/.local/state/awd/reploy-E-resume-20261028/OmegaFlow-hld-protected-copy-proof.py` + +## Finite work for the HLD and later LLD + +- Select the actual initial engine/host cohort with the maintainer. The existing + controlled-session design explicitly requires evidence before Desktop, + rootless and Podman support; the current local proof environment is Desktop. +- Design selection retention through final preparation and prove no tag + re-resolution/fallback changes the selected image. +- Define the generic protected image-code namespace and safe inspection path + resolution. Compare a simpler mechanism if protecting loaders/libraries would + require a new generic dependency-analysis service. +- Resolve protected capture source opening, exact bytes/modes, inventory bounds, + atomic publication, mount aliases/shadowing and cleanup reachability. +- Define the public opaque checked-state binding as an extension of existing + generation/admission ownership, excluding run-specific ephemeral coordinates. + Bind command and relevant environment/mount/identity/endpoint facts, verify + after queue waits and retain resources through use. +- Qualify the public inspection/launch pair on the agreed cohort with both + unchanged-retained-state success and actual-bound-change refusal controls. + +No HLD, public syntax, platform expansion, final slices or estimates have been +approved. No implementation readiness is claimed. + +Original result SHA256: `5f7e1c729ac94fa12fce1868dba1157c7274c4e55405b4f8712dddd494014c67`. + +## HLD review result and current decision + +The original workflow document's HLD loop completed two local current-agent +attempts (trail rounds 2 and 3). One high design finding required explicit +suppression of inherited image healthchecks during inspection. The next pass +verified the design-contract correction; no runtime change is claimed. The clean +HLD received its own exact current-agent review against the approved requirements +with zero findings. Both helper-generated document stamps and their dependency +closure were verified. No independent agent or remote review ran. + +Original private results: +- `/home/omry/.local/state/awd/reploy-E-resume-20261028/OmegaFlow-hld-workflow-review-result.json` +- `/home/omry/.local/state/awd/reploy-E-resume-20261028/OmegaFlow-clean-hld-review-result.json` + +Public host coverage inherits Reploy's existing commitment; the earlier cohort +question was an agent framing error. See [the correction](platform-contract-clarification.json) +and [full-path qualification contract](platform-qualification.md). The proposed +architecture uses normal immutable-image delivery for protected supplied inputs; +the earlier copy-bind fixture remains evidence for that narrow alternative only. +Private channel/watchdog portability and protected image namespace enforcement +remain substantive engineering proof gates. The historical estimate is not a +current delivery estimate. HLD human acceptance, LLD/slice engineering and product +implementation remain separate. diff --git a/docs/consumers/supporting/omegaflow-rp-c6-requirements/consumer-clarifications.md b/docs/consumers/supporting/omegaflow-rp-c6-requirements/consumer-clarifications.md new file mode 100644 index 00000000..0ba8af98 --- /dev/null +++ b/docs/consumers/supporting/omegaflow-rp-c6-requirements/consumer-clarifications.md @@ -0,0 +1,54 @@ +# OmegaFlow consumer clarifications + +The maintainer relayed these OmegaFlow questions after the first clean +requirements draft. They refine the pending baseline; they are not requirements, +HLD, LLD, implementation or release approval. The earlier handoff and preserved +source remain historical evidence. Reploy records the clarification here; +OmegaFlow owns reconciliation of its own design documents. + +## R4: facts suffice for the qualified Bash check + +OmegaFlow checks Bash's qualified digest, resolved path/type and required +system-rc absence. It identified no additional need to export raw Bash or +system-rc bytes and stated that the earlier byte-export request could be removed. + +The pending Reploy draft therefore requires bounded metadata/hash/absence evidence +instead. Reploy must compute the digest from the actual inspected file and bind +that evidence through admission/use. Missing, present, non-regular, link, error +and unsupported-size cases need explicit semantics; an inspection failure is not +absence. No raw file-export interface is required by this minimum delivery. + +This removes a consumer interface requirement. It does not remove reading/hashing +files internally, expected-hash verification of supplied runtime payload, or the +requirement that the inspected executable is the one delivered for launch. + +## R9: invalidate changes to the bound prepared state + +OmegaFlow asked to distinguish actual admitted-state changes from movement of +external references that no longer affect the retained state. The same principle +already permits source changes after an independent protected capture. + +The pending draft now makes these cases explicit: + +- Original tag changes; the inspected immutable image and all other bound state + remain retained and are used: the binding remains valid. +- Original supplied-file source changes; the independent verified protected copy + and all other bound state remain retained and are used: the binding remains valid. +- Unprotected application data changes: ordinary runtime behavior/failure, not + automatic invalidation of the protected capture. +- Reploy selects a different bound image, protected contents, relevant runtime + facts or generation: reject the stale expected identity before bootstrap. +- A retained image/capture is missing or cannot be verified: refuse; do not + re-resolve a mutable reference and silently substitute different state. + +Integrated acceptance must exercise both continued validity and stale-state +refusal. Rejecting every external change would not satisfy this contract. + +## Impact and remaining work + +The R4 interface is smaller. R9 states the intended identity boundary more +precisely. Neither change implements or proves runtime protection/admission. +The preliminary estimate that included byte export is historical; re-estimate +from the actual HLD/LLD rather than claim a measured saving. The baseline still +needs explicit maintainer approval at its existing gate, followed by the saved +workflow's review/approval sequence. diff --git a/docs/consumers/supporting/omegaflow-rp-c6-requirements/consumer-request-and-evaluation.txt b/docs/consumers/supporting/omegaflow-rp-c6-requirements/consumer-request-and-evaluation.txt new file mode 100644 index 00000000..5303a82f --- /dev/null +++ b/docs/consumers/supporting/omegaflow-rp-c6-requirements/consumer-request-and-evaluation.txt @@ -0,0 +1,215 @@ +--- +status: Evaluation pending +updated: 2026-10-29 +summary: OmegaFlow preparation inspection and launch admission needs; minimum Reploy delivery remains undecided. +--- + +# OmegaFlow + +## Use case and source + +OmegaFlow needs to inspect the workload it will launch, evaluate its own policy, +and launch exactly that inspected preparation. Reploy must reject relevant +changes before workload or bootstrap execution begins. + +Source: the 2026-10-29 planning draft in the OmegaFlow checkout, +`temp/part-c-delivery/implementation-through-C6.1/RP-C6-HANDOFF-PLANNING.md` +(read from `/home/omry/dev/omegaflow`), corrected by the maintainer-relayed +OmegaFlow scope clarification on 2026-10-29. The clarification below takes +precedence over the earlier handoff where they differ. These are consumer +requirements, not an approved Reploy API or an installed-release conformance +claim. + +## Corrected ownership and supplied-input scope + +OmegaFlow defines the blueprint; Reploy delivers and enforces it. Bash, `/bin/sh`, +loaders and libraries supplied by the workload image remain Reploy's +responsibility. OmegaFlow does not need to enumerate or snapshot that image +dependency closure. OmegaFlow owns compatibility checks against its qualified +Bash build table. Reploy must expose the resolved Bash and selected system-rc +facts for the generation actually launched. The selected system-rc path must be +absent; the consumer reports `/etc/bash.bashrc` for all three current profiles. + +For consumer-supplied inputs, OmegaFlow reports a complete expected-SHA-256 +inventory of 18 payload files plus `manifest.json`, approximately 7.9 MiB total: + +- `bin/envoy` and `bin/awsh`; helper commands use the same Awsh executable; +- `etc/awsh-bashrc`, `etc/inputrc` and `etc/bash-builds.json`; +- one terminal database entry and 12 locale files; and +- `manifest.json`, with its expected digest supplied separately. + +Retain established paths under `/omegaflow-runtime`. These are regular files +without symbolic-link or hardlink aliases. The reported staged modes are `0555` +for directories/executables and `0444` for data. The workload needs read/execute +access; source numeric UID/GID preservation is not required. The adapter rcfile +sources no additional startup files. These inventory facts are consumer-reported, +not independently verified measurements in this record. + +Protected copies are acceptable. Verify the bytes actually retained against the +supplied expected hashes, then deliver those exact contents at the declared +paths. Computing fresh hashes without checking the supplied expectations could +accept inputs mutated before capture. Once an independent protected capture +exists, changes to its original source need not invalidate it. Enforce explicit +size bounds and reject unsupported sizes. Copying is an implementation candidate, +not a requirement to introduce a general filesystem snapshot service. + +Distinguish protected supplied inputs from unprotected application data. Videos +and other application data can remain live; mutation, disappearance and processing +errors are acceptable ordinary runtime failures. `/run/omegaflow` remains writable +for live sockets and FIFOs. Those resources are not protected startup payload. + +Protect retained runtime contents against source mutation after verification, +workload writes and mount shadowing through Reploy delivery machinery. File +permissions alone do not establish the boundary. Hostile-host-root containment +and stronger same-identity isolation are outside the clarified requirement. + +## Requirements and acceptance + +1. Select the workload image through existing public preparation machinery. + Observe its immutable identity and inherited environment, and evaluate image + plus application environment before OmegaFlow adds reserved composition + values. Forbidden inherited values must not disappear from observation. +2. Compose final native blueprints through OmegaFlow's existing Hydra entry and + prepare with the same selected image. Reject image replacement rather than + silently changing composed YAML or reusing checks for another image. +3. Inspect the prepared generation's final image/platform, effective environment, + execution identity, mounts, endpoints, resolved executable bytes and required + selected system-rc absence. Keep configured private environment values private. + Define bounded requests and byte exports, safe path resolution, and explicit + absent, symbolic-link, non-regular-file and error behavior. Inspection must + not start bootstrap or execute untrusted workload code. +4. Bind the observations to one public immutable identity. Accept that expected + identity at controlled-session admission, using Reploy's existing ownership + and cleanup. Bind the protected supplied-input capture and relevant image + facts through admission and use; pinning only the image is insufficient. +5. Prove public inspection and public launch work together. Relevant rebuilds, + image/tag replacement, blueprint/environment/mount changes, protected-content + substitution and generation replacement must invalidate stale facts. Source + changes after an independent verified capture and changes to unprotected + application data need not invalidate that capture. Each stale case must prove + bootstrap did not start. Malformed, + oversized, unknown-version and forged identities must fail closed; + interruptions must leave no active workload or leaked reservation. +6. Retain the exact release/source identity, public contract and native test + evidence. Qualify OmegaFlow against an explicitly selected compatible release + before claiming the consumer is unblocked. + +## Current support and gaps + +The Reploy source inspection on 2026-10-29 identified reusable internal generation +and build identities in [controlled-session planning](../../internal/dockerdeploy/controlled_session_plan.go), +and executable hash, ownership, permission and symbolic-link observations in the +[probe protocol](../../internal/probe/protocol.go). These do not establish the +complete public inspection/admission contract above. The inspected +[public launch options](../../internal/cli/controlled_session.go) do not accept +the consumer's expected preparation identity, and the probe response does not +provide file bytes. + +The [controlled-session design](../CONTROLLED_SESSION_DESIGN.md) keeps internal +generation/build/plan digests out of the public session stream. A separate +preparation interface with an opaque public binding is a candidate, not a +selected design. Reuse existing preparation, immutable-image selection, build +verification, inspection and session admission. Do not add a parallel image +selector, inspection daemon, receipt authority or build pipeline. + +Reploy owns generic facts, image delivery, protected supplied-input delivery and +admission. OmegaFlow owns its reserved environment policy, Bash compatibility +checks, supplied runtime contents, mount acceptance policy and recording behavior. + +## Separate endpoint dependency + +The handoff reports that optional host publication for private endpoints is +already known Reploy backlog work. Its exact backlog item is not yet confirmed; +do not create a duplicate. Related endpoint-address and network-policy items are +not an exact match. Existing private controlled-session networking must remain +distinct from the native-blueprint validation gap reported for OmegaFlow's +selected installed release. + +The handoff reports this dependency blocks C6.1 acceptance. RP-C6 separately +blocks C6.2/C6.3 and dependent launch acceptance. Resolving one does not prove the +other is resolved. + +## Delivery decision and next step + +**Minimum delivery: undecided.** Evaluate which acceptance checks are essential +to unblock RP-C6 and recommend the smallest coherent contract from the actual +code. Produce bottom-up production/test estimates, proposed delivery cuts, +acceptance evidence and release/adoption prerequisites. Any deferred consumer +requirements need explicit consumer agreement; do not silently weaken the +launch guarantee to make the delivery smaller. + +Resolve image selection through final preparation, protected-input capture, +private-value handling, identity lifetime, cancellation, concurrent replacement, +platform support, bounds and errors during design. Review the resulting design +through the required local deep design review and remote PR cycle before +implementation. Return to design if costs or mechanisms expand. + +## Progress and evidence + +### Revised preliminary size estimate, 2026-10-29 + +This is a source-based planning estimate, not a reviewed LLD, measured result or +approved set of slices. Counts are added plus removed lines; tests include +fixtures. Documentation, review bookkeeping, generated output, release execution +and OmegaFlow-side integration are excluded. + +| Responsibility | Production LOC | Test/fixture LOC | +| --- | ---: | ---: | +| Bind selected image through preparation; inherited/application/final environment observations | 250–400 | 400–650 | +| Bounded resolved-Bash inspection/export and selected system-rc absence evidence | 300–450 | 600–900 | +| Generic protected supplied-input declaration/capture, expected-hash verification, exact path/mode delivery and mount protection | 350–550 | 700–1150 | +| Expected preparation identity at existing admission; stale-state refusal and capture lifetime/cleanup | 250–400 | 500–850 | +| Public CLI/schema integration and end-to-end inspection/launch qualification | 150–250 | 500–800 | +| **Total** | **1300–2050** | **2700–4350** | + +Expect approximately four to six implementation PRs after design, subject to +coherent cuts and the repository's production-size limits. These rows are +responsibilities, not approved task IDs. The superseded estimate was 1550–2500 +production and 3200–5200 test LOC. The narrower inventory and protection boundary +reduce estimated work and uncertainty; they do not establish implementation +readiness or a measured saving. + +The estimate assumes reuse of the existing controlled-session platform and +ownership model, the consumer's explicit bounded payload inventory and supplied +expected hashes, and reuse of existing artifact storage/materialization where +it meets the required delivery boundary. The public API and delivery mechanism +remain undecided. It does not estimate a general mutable-tree +snapshot service, a new image-selection pipeline, remote-engine support, +multi-identity activation or private-environment injection. Unsupported inputs +must refuse; a read-only bind or permission change alone is not a substitute for +protected delivery. If necessary protection cannot fit this scope, resolve +the design and re-estimate before committing to delivery. + +Basis: [current session admission](../../internal/dockerdeploy/current_controlled_session_run.go) +already loads verified current builds under both deployment locks and owns queue +leases; [runtime input handling](../../internal/dockerdeploy/current_runtime_files.go) +validates generated inputs under the operation lock. Those locks do not by +themselves prevent external bind-source mutation. The +[image inspector](../../internal/dockerdeploy/docker_image_inspect.go) already +extracts inherited environment, while the [probe](../../internal/probe/protocol.go) +returns executable metadata/hashes but needs bounded byte and absence semantics. +The [artifact store](../../internal/providerstore/store.go) already offers +`PublishExpected`, which compares retained bytes against an expected descriptor +before atomic publication. That is a reuse candidate, not proof of complete +runtime delivery, reachability/cleanup integration or mount-shadow resistance. +No new runtime proof or tests ran for this estimate. + +Optional host endpoint publication remains a separately identified dependency +with an unconfirmed exact backlog item; its cost is excluded. Delivery of RP-C6 +alone therefore does not claim to unblock all OmegaFlow acceptance. + +### Delivery status + +- Maintainer priority on 2026-10-29: once the global helper blocker is fixed, + finalize E2.2 through PR approval, then pause E before E2.3 and run + `global:swe:design` for this consumer record. Follow its requirements, HLD and + LLD review/approval gates; stop before implementation. The remaining E slices + stay unfinished and preserved. +- Evaluation is queued in [the backlog](../BACKLOG.md); no delivery cuts, + implementation, release selection or consumer qualification are approved. +- This is separate from milestone E and does not expand its delivery scope. +- The source handoff reports C6.1 preserved and unaccepted, with two unresolved + ownership findings. Those campaign conditions have not been independently + revalidated here. It authorizes no campaign recovery or dependency upgrade. +- After prerequisite delivery and release selection, OmegaFlow must use its + reviewed dependency-adoption and guarded campaign-recovery path. diff --git a/docs/consumers/supporting/omegaflow-rp-c6-requirements/design-contract.md b/docs/consumers/supporting/omegaflow-rp-c6-requirements/design-contract.md new file mode 100644 index 00000000..a8411ff1 --- /dev/null +++ b/docs/consumers/supporting/omegaflow-rp-c6-requirements/design-contract.md @@ -0,0 +1,104 @@ +# OmegaFlow RP-C6 design output contract + +This maintainer instruction supplements the active `global:swe:design` run. +It governs document preparation and review. It does not approve requirements, +architecture, implementation slices, implementation, publication or release. + +## Clean outputs + +The feature prefix is `omegaflow-rp-c6`. All three outputs reside in +`docs/consumers/`: + +- `omegaflow-rp-c6-requirements.md` +- `omegaflow-rp-c6-high-level-design.md` +- `omegaflow-rp-c6-implementation-plan.md` + +Create each document at its responsible workflow phase. Do not publish empty +architecture or slice plans as finished outputs. Each main document describes +only the current agreed requirements or design, observable behavior, constraints +and applicable readiness. Identify unapproved proposals explicitly. Keep history, +investigations, review records and superseded choices in supporting material. + +## Supporting material + +Use these owning-document directories: + +- `supporting/omegaflow-rp-c6-requirements/` +- `supporting/omegaflow-rp-c6-high-level-design/` +- `supporting/omegaflow-rp-c6-implementation-plan/` + +Each document links its durable supporting material. Prefixes identify the +consumer and feature so other designs can coexist in the same top-level directory. +Store shared source requirements and this contract under the requirements stem; +other documents may link that same material rather than duplicate it. Keep +investigation evidence with its owning design and sizing evidence with its plan. +Keep secrets and raw sensitive execution data out of tracked supporting material. +Existing private AWD review authorities and runtime records remain in their +original stores; supporting documents may identify their evidence locators and +limitations without copying a stamp or manufacturing approval. + +## Workflow continuity + +Continue run `run_3k0spmw1cd3w8pmjsq65ggeese` with its existing pinned +`swe:design` definition, original `docs/consumers/omegaflow.md` document argument, +default security selection, and requirements, reviewed-HLD and reviewed-LLD +human gates. Preserve the consumer record, original source preimage, decisions, +reviews, tracking and separate E priority pause. The three clean documents are +additional phase outputs alongside the workflow-required artifact. Use the same +review mechanisms and bind review and approval to the exact current clean output +as well as the required workflow output; a copied clean document is not approved +merely because another artifact was reviewed. Reconcile corresponding content +before claiming a phase ready. Do not hand-edit stamps, runtime graphs or global +AWD configuration. + +## Questions and stack agreement + +The maintainer's correction supersedes the proposed four-question limit and any +saved-function requirement to close design decisions at a fixed count. There is +no agreed numerical question cap. Keep the existing decision agenda and a running +question/answer record. Reuse sufficient prior answers, ask one concrete question +at a time when needed, and retain unresolved decisions explicitly. Do not reset +consumption history, mark unresolved work settled, or restart the design run to +obtain more allowance. If a runtime batching boundary is reached, preserve the +remaining decisions and continue through supported tracking; it is not a reason +to force a decision or claim completion. + +Discuss and agree the stack when a real stack choice exists. An extension to an +existing project inherits its established stack unless evidence justifies a +material change. Do not manufacture an approval question to reconfirm existing +languages, interfaces or primitives. For this Reploy extension, retain the +existing implementation stack as a project constraint. Surface a necessary +material addition or change before adopting it. Ordinary engineering decisions +do not require individual approval. + +## Implementation estimates + +Each slice and the plan total must provide separate ranges for: + +- **Production/configuration LOC:** authored shipped implementation and runtime, + build or packaging configuration needed for the slice. +- **Test-code LOC:** authored tests, test-only helpers and textual fixtures. + +The unit is a changed physical text line: additions plus removals against the +slice's accepted parent, including changed blank and comment lines, not net growth. +A line belongs to one category. Test-only configuration and fixture programs count +as tests. Generated output, vendored dependencies, lockfile churn, binary payloads, +Markdown design documents and review bookkeeping are excluded from these LOC +columns; disclose material excluded work separately. Payload bytes are a separate +size constraint, not code lines. Reuse the delivery helper's supported per-path +role classifications and report any accounting mismatch explicitly. + +Count shared foundations once in their owning prerequisite. Show per-slice lower +and upper bounds and totals that sum those bounds. Preserve the repository's +existing production-size limits and coherent slice boundaries. State uncertainty +and source/proof basis. No working-hour estimates. Preliminary consumer estimates +remain historical evidence until replaced by the reviewed bottom-up slice plan. + +## Maintainer source + +The maintainer instructed this session to use the existing AWD `swe:design` workflow +with three clean documents, supporting material under `supporting//`, +separate production/configuration and test-code line estimates with totals and a +counting convention, no working-hour estimates, explicit stack discussion and +agreement, and further questions when needed without a fixed question count +forcing premature decisions. Preserve required workflow outputs and tracking. diff --git a/docs/consumers/supporting/omegaflow-rp-c6-requirements/design-workflow-feedback.md b/docs/consumers/supporting/omegaflow-rp-c6-requirements/design-workflow-feedback.md new file mode 100644 index 00000000..eb705f2a --- /dev/null +++ b/docs/consumers/supporting/omegaflow-rp-c6-requirements/design-workflow-feedback.md @@ -0,0 +1,282 @@ +# Feedback for the modified SWE design workflow + +Collected during the OmegaFlow RP-C6 design run. This is input for a later AWD +Config improvement, not a request to change global helpers now. Append concrete +observations as the design continues. Separate observed behavior, agent mistakes, +new maintainer requirements and proposed improvements. + +## Context and evidence + +- The active design run is `run_3k0spmw1cd3w8pmjsq65ggeese`. +- Its pinned `swe:design` fingerprint is + `sha256:9cdd5fda8ffc9a91f74ea6a5599fa1e4dfb4c3be8d2628befa38ccf20d368ba8`. +- Its pinned interview fingerprint is + `sha256:9fbd130f1e35c44d278181928885045e8dde774ed8319fbbd18c1060d8cc96e9`. +- The maintainer's additional output requirements are retained in the + [local design contract](design-contract.md). +- The unnecessary stack question and its withdrawal are recorded in + [interview corrections](interview-corrections.md). +- The [original consumer request and evaluation](consumer-request-and-evaluation.txt) + remains a source snapshot, not an approved requirements/HLD/LLD result. +- At collection, no requirements, HLD or LLD phase approval has been recorded. + The stack question is withdrawn, with no answer or approval fabricated. + +## 1. Ask about an actual decision, not a checklist heading + +**Classification: agent error; corrected locally.** + +The agent treated “discuss and agree on the stack” as a mandatory question about +using Go, the existing Reploy CLI, YAML and JSON. This extends an existing +application. No credible alternative or necessary technology change had been +identified. The maintainer asked whether this was even a relevant question. + +The existing interview already requires materiality, evidence and reuse of prior +decisions. The agent passed that check for the wrong reason: the general +instruction mentioned stack agreement. The workflow did not require this +particular bad question. + +**Suggested improvement:** make stack discussion conditional on a real choice. +For an existing project, record its established stack as a constraint. Ask when +a new project needs a selection, or evidence justifies a material addition or +change. Require a concrete consequence that differs between plausible answers. +An instruction heading alone does not establish decision value. + +**Acceptance example:** an extension to an existing Go CLI with no proposed new +runtime reaches engineering investigation without asking permission to retain +Go. A proposed new service or runtime produces a concrete decision brief before +adoption. Withdrawing a pointless question does not record stack approval. + +## 2. Question counts must not become readiness criteria + +**Classification: saved-workflow limitation; explicit maintainer override active.** + +The pinned interview requires an agreed finite allowance of at most eight design +questions and a setup gate for that allowance. The agent proposed four questions +before establishing that four owner decisions existed. The maintainer instructed +the agent to ask further questions when needed and not let a fixed count force +premature decisions. + +**Suggested improvement:** track the decision agenda, actual questions, answers, +withdrawals and unresolved work. Close questioning because the needed owner +decisions are settled or because useful further questions need engineering +evidence. Do not close it merely because a count is reached. Preserve bounded +execution/recovery and cumulative history without presenting a transport batch +limit as the owner's decision allowance or requiring a ritual budget approval. + +**Acceptance example:** supplied requirements can be reused without inventing +questions to fill a quota. If more than eight genuine decisions emerge, retain +and address them without silently resetting history or claiming readiness. +Further questions must still pass relevance and materiality checks. + +## 3. Make the three phase documents native outputs + +**Classification: additional maintainer requirement; interim contract recorded.** + +The saved composition uses one document for requirements, HLD and LLD. The +maintainer now requires `-requirements.md`, `-high-level-design.md` +and `-implementation-plan.md`, each describing the current agreed design. +The interim instruction preserves the workflow artifact alongside these files. +That adds a risk of duplicated statements and drift; no drift failure is claimed +to have occurred yet. + +**Suggested improvement:** resolve and retain one canonical output per phase, +with explicit phase-to-phase references and exact review/approval identities. +Keep orchestration state separate from design prose. The supported transition +from the interim arrangement must preserve existing decisions, review evidence +and continuation points instead of restarting a run. + +**Acceptance example:** a requirements change identifies the affected downstream +design and plan. Each phase approval covers its actual current output. Copying +a reviewed file or an approval stamp cannot approve another document. An +unwritten HLD or unestimated plan is not reported as complete. + +## 4. Keep supporting material durable and namespaced + +**Classification: additional maintainer requirement; layout adopted locally.** + +The interview uses ignored `temp/design-interviews` working state, while the +consumer record already mixes requirements, investigation notes, preliminary +estimates and progress. The maintainer wants durable supporting material under +`supporting//` and clean main documents. + +**Suggested improvement:** retain compact executor state where the runtime owns +it, but place durable human-facing sources, investigations, review records, +superseded choices and progress under the owning document's supporting directory. +Link them from that document. Preserve original trusted review authorities in +their existing stores; a tracked copy must not become approval authority. + +Use a feature-specific name, such as `omegaflow-rp-c6`, rather than a shared +`requirements.md` or `supporting/reviews/` directory. + +**Acceptance example:** two designs coexist in one top-level directory without +overwriting sources or evidence. Their main documents contain the current +requirements/design rather than a discussion transcript. Supporting links remain +valid; source snapshots preserve their identity and original path context. + +## 5. Define estimate categories and units in the plan + +**Classification: additional maintainer requirement; not a measured sizing result.** + +The maintainer requires production/configuration and test-code estimates for +each implementation slice and totals, with a counting convention and no +working-hour estimates. The local contract defines the convention; the actual +bottom-up implementation slices have not been designed or approved yet. + +**Suggested improvement:** make the plan template require separate lower/upper +columns for production/configuration and tests, summed totals, and explicit +rules for additions/removals, fixtures, generated files and excluded work. +Count shared foundations once. Align the stated convention with supported +delivery measurement classifications; report a mismatch instead of quietly +changing units between planning and delivery. + +**Acceptance example:** totals equal the sums of the slice bounds. Test-only +configuration is not also counted as production. Payload bytes are not LOC. +Historical preliminary ranges cannot stand in for reviewed slice estimates. +The plan contains no working-hour estimates. + +## 6. Distinguish unresolved engineering from owner decisions + +**Classification: execution guidance to reinforce.** + +The current open work is how to protect retained payload bytes through use, bind +inspection to the admitted state, and expose the smallest sufficient public +interface. Those are engineering investigations under the agreed requirements. +They do not justify asking the maintainer to design the mechanism before the +agent has inspected existing primitives and gathered evidence. + +**Suggested improvement:** investigate first. Ask only when evidence exposes a +material choice about behavior, authority, compatibility, scope or significant +cost. Present the consumer scenario, the consequences, viable choices and a +recommendation. Keep questions one at a time; do not present dense labels that +the owner must reconstruct into a decision. + +**Acceptance example:** the agent investigates protected capture and admission +using existing store/session mechanisms. If none can satisfy the agreed boundary +without a material change, it presents that concrete tradeoff. Ordinary internal +choices continue autonomously. An unresolved engineering prerequisite remains +visible and prevents a false implementation-ready claim. + +## 7. Name the purpose of each requirements approval + +**Classification: observed workflow sequencing; clarity to preserve in the update.** + +The interview closeout requests confirmation of the requirements baseline before +the composition's formal requirements review. The later composition also checks +for exact current requirements approval. The formal review has not run yet, so +no duplicate approval interaction is claimed here. + +**Suggested improvement:** state clearly whether the owner is confirming the +intended requirements, accepting reviewed requirements, choosing architecture or +authorizing implementation. Reuse an exact existing approval when its scope and +artifact remain current; request renewed approval for material changes. Do not +make the owner guess which gate a generic “approve?” refers to. + +**Acceptance example:** the baseline-confirmation brief names the observable +consumer outcome, constraints and remaining engineering work. After review, +unchanged exact requirements retain their approval; changed major requirements +are presented with their concrete consequences. Neither approval authorizes +implementation. + +## 8. Separate required facts from transport and invalidation mechanisms + +**Classification: consumer scope clarification; not an implementation finding.** + +OmegaFlow clarified that its Bash compatibility check needs a qualified digest, +resolved path/type and system-rc absence, rather than raw file-byte export. It +also clarified that moving an original tag must not invalidate a retained +immutable image that Reploy still launches. Both corrections came from the +consumer; the earlier byte-export request was an actual source requirement, +not an agent-invented capability. + +**Suggested improvement:** verify the observable consumer need before carrying +a transport mechanism into the minimum delivery. Define which prepared facts an +identity binds and distinguish changes to them from changes to irrelevant source +references. Trace both valid continuation and required refusal in acceptance. +Keep earlier estimates and decisions as history instead of silently rewriting +their basis or claiming measured savings. + +**Acceptance example:** no raw file-export API is designed without a concrete +need. Original-tag movement remains valid when all retained admitted state is +unchanged; selection of a different image or protected payload refuses before +bootstrap. A source clarification updates the existing pending baseline and +preserves the original approval request rather than inventing approval or +restarting the interview. + +## Preserve these controls + +- Keep requirements, reviewed HLD and reviewed detailed-plan approvals distinct. +- Reuse sufficient existing decisions; do not infer approval from silence, a + general workflow correction or rejection of an irrelevant question. +- Keep the saved run, approval evidence and actual consumption history through + corrections. Do not fake a pass or restart to avoid a limit. +- Preserve the separation between design, implementation and publication. +- Keep required review and tracking. Reduce clerical burden without weakening + the exact artifact and evidence boundaries. + +## Later follow-up + +The suggestions above are collected, not implemented in AWD Config. Continue +appending observed cases here. Assess the document/review integration again when +the first clean requirements document reaches review; that path has not run yet. + +## 9. Integrate phase outputs with exact review selectors + +Observed in this run: the pinned design function reviews the whole original +consumer document exactly. The added clean requirements output therefore needed +a separate runtime-backed design review and its own helper stamp. Both reviews +completed one clean round; neither target could borrow the other stamp. This is +an interim-contract integration cost, not evidence that either review may be +skipped. Proposed improvement: native named phase outputs and exact multi-artifact +review/approval bindings, while retaining the original whole-document lineage +and preventing copied files from inheriting approval. The current run and pins +were preserved; no global workflow changes were made. + +## 10. Inherit product host support before posing cohort choices + +Agent error: the agent treated the current WSL2/Desktop proof environment and +Linux-only controlled-session implementation as grounds to ask whether public +host coverage could be narrowed. README already states Linux/macOS/Windows +product support. The maintainer corrected the frame: inherit that commitment, +include WSL2/Desktop and qualify the complete public path with unchanged +integrity. Specific channel/watchdog gaps are delivery dependencies, not a new +product-platform decision. Improvement: distinguish existing product commitment, +feature-path implementation gaps and actual qualification evidence before asking +an owner. This does not remove real scope gates or authorize false compatibility +claims. No global workflow change was made. + +## 11. Separate proof access, mechanism evidence and final acceptance + +Observed during LLD investigation: a WSL2/Desktop scratch relay can prove one +engine-stdio/peer-credential mechanism while native Windows/macOS watchdog +survival remains unproved. Current source tests exercise the shared cleanup +algorithm, not actual native child/handle behavior. Existing smoke CI skips +Windows Docker. A source-based estimate that assumes a portable channel already +exists materially undercounts shared production prerequisites. + +Suggested improvement: record existing product support, current implementation +gaps, proof execution targets and downstream full-path acceptance separately at +HLD/LLD handoff. Own and size shared prerequisites explicitly. Distinguish a +missing execution target from a new product-cohort decision, and request only +the target/access information needed. Retain negative attempts and narrow proof +limits. Do not turn a provisional responsibility estimate into approved slices +or use a fixture to claim the final public inspection/admission/launch path. +No global workflow changes were made. + +## 12. Audit existing behavior and adjacent campaign ownership before sizing + +Agent planning weakness: the candidate estimate named a new container-private +broker without clearly separating it from the existing controller application +broker/protocol and the genuinely missing engine/peer transport. Likewise, new +namespace rows did not identify the existing protected-path compiler and E2.2's +F-owned live-proof contract prominently enough. The code has useful reuse, but +its existing socket client is not already portable and E supplies no production +F observation provider. Neither a complete rewrite nor claiming prerequisites +already exist is justified. + +Suggested improvement: require a concrete existing/missing delta and an adjacent +plan ownership crosswalk before presenting a delivery forecast. Count shared +foundations once, preserve backend-specific proof/authority and qualification, +and label unresolved estimates explicitly. The user asked for this reassessment +before implementation. The audit retained earlier estimates and corrected their +interpretation without claiming a lower measured cost or fixing runtime gaps. +No global workflow changes were made. diff --git a/docs/consumers/supporting/omegaflow-rp-c6-requirements/interview-corrections.md b/docs/consumers/supporting/omegaflow-rp-c6-requirements/interview-corrections.md new file mode 100644 index 00000000..1943d746 --- /dev/null +++ b/docs/consumers/supporting/omegaflow-rp-c6-requirements/interview-corrections.md @@ -0,0 +1,15 @@ +# Interview corrections + +## Stack question withdrawn + +The agent asked for agreement to use Reploy's existing Go implementation, CLI, +YAML blueprints and JSON interfaces. The maintainer challenged the relevance of +that question. No concrete alternative or material stack change had been +identified. The question was unnecessary and is withdrawn. + +This records a correction to the agent's question, not maintainer approval or +rejection of the stack, requirements, architecture or implementation plan. +Continue with existing project constraints. Investigate actual delivery gaps and +ask for an owner decision only when the evidence establishes a material choice. +The instruction to discuss the stack does not require manufacturing a decision +when the existing project already determines it. diff --git a/docs/consumers/supporting/omegaflow-rp-c6-requirements/interview-synthesis.md b/docs/consumers/supporting/omegaflow-rp-c6-requirements/interview-synthesis.md new file mode 100644 index 00000000..330700a0 --- /dev/null +++ b/docs/consumers/supporting/omegaflow-rp-c6-requirements/interview-synthesis.md @@ -0,0 +1,70 @@ +# Interview synthesis and engineering follow-up + +The requirements draft carries the corrected consumer scope. Existing project +constraints determine the implementation stack. No owner decision about a new +stack, public syntax, protection mechanism or slice plan has been approved. +The unnecessary stack question was withdrawn; see +[the correction record](interview-corrections.md). + +## Coherent responsibility and trust boundaries + +OmegaFlow authors the blueprint, expected runtime inventory and compatibility +policy. Reploy selects and delivers the image, verifies supplied retained bytes, +reports generic prepared facts and admits only the inspected state. The workload +can access declared live data and session resources but cannot replace protected +payload through its writes or a shadowing mount. Hostile host root and stronger +same-identity containment remain outside this request. + +The normal journey is image selection and inherited-fact inspection, consumer +composition, final preparation, final metadata/hash/absence inspection, consumer policy check, +then expected-state admission through existing session ownership. A relevant +mismatch refuses before bootstrap. Cancellation and interrupted preparation must +preserve existing cleanup ownership. An independent verified payload capture +does not depend on later survival of the original source. Moving an original image +tag is also irrelevant when the same inspected immutable image is retained and +launched. See the [consumer clarification](consumer-clarifications.md). + +These are responsibility boundaries and required journeys, not a selected HLD +mechanism or proof that existing internal checks already satisfy them. + +## Bounded source observations + +- `internal/cli/controlled_session.go` and + `internal/dockerdeploy/current_controlled_session_run.go` have no public + expected-preparation input. Existing admission loads verified controller and + workload runtime under sorted operation locks. +- `internal/providerstore/store.go` has `PublishExpected`, which streams retained + bytes, compares the descriptor and only then publishes the digest-addressed + object. This is useful capture machinery, not proof of final runtime delivery + or mount protection. +- `internal/probe/protocol.go` returns resolved executable metadata and hashes. + The corrected consumer scope needs bounded metadata/hash/absence evidence, not + raw file-byte export. Public integration and general absence/error semantics + still need design; this observation does not establish their implementation. +- `internal/dockerdeploy/docker_image_inspect.go` retains image metadata and + normalizes environment entries into a map. The public consumer handoff must + separately establish inherited/application/final facts rather than assume a + final normalized environment satisfies the whole requirement. +- The consumer's Part C design states the first workload is Linux/amd64 with + three qualified Bash profiles. No broader workload support follows from an + ARM64 controller or artifact build. + +These are source observations at the retained E2.2 checkout. No new runtime +proof, installed-release test or complete feasibility assessment ran for this +interview synthesis. + +## Engineering investigations for HLD and LLD + +| Work | Depends on | Required result | +| --- | --- | --- | +| Image selection and environment provenance | Existing image inspection, preparation and consumer composition | Same selected immutable image through final preparation; inherited facts cannot be hidden by final composition; private values remain private. | +| Non-executing file inspection | Existing probe/image/runtime paths | Smallest safe bounded metadata/hash/absence mechanism, with path/type/link/error semantics and no untrusted workload execution; no raw file export. | +| Protected payload delivery | Expected-hash artifact publication and existing runtime mount planning | Retained bytes match supplied expectations and remain protected from source changes, workload writes and mount shadowing through use; explicit size bounds and cleanup. | +| Expected-state admission | Final observation identity and existing locked session admission | Binding lifetime, replay/invalidation and concurrent replacement behavior; invalidate actual bound-state changes, retain validity for external-reference changes that do not affect retained state; stale refusals before bootstrap; no separate authority system. | +| Integrated qualification and slice plan | The selected architecture and load-bearing mechanism evidence | Full requirement-to-slice/test coverage, supported cohort, bottom-up production/configuration and test LOC estimates with totals, and release/adoption gates. | + +Investigate ordinary engineering choices autonomously. If evidence establishes a +material behavior, trust, compatibility, scope or cost tradeoff, return a concrete +decision brief to the maintainer at the responsible stage. Do not invent that +choice before the investigation, silently drop a requirement or claim LLD +readiness while a prerequisite is unproved. diff --git a/docs/consumers/supporting/omegaflow-rp-c6-requirements/requirements-baseline-approval.json b/docs/consumers/supporting/omegaflow-rp-c6-requirements/requirements-baseline-approval.json new file mode 100644 index 00000000..72ed65bf --- /dev/null +++ b/docs/consumers/supporting/omegaflow-rp-c6-requirements/requirements-baseline-approval.json @@ -0,0 +1,25 @@ +{ + "schema_version": 1, + "kind": "maintainer-requirements-baseline-approval", + "recorded_at": "2026-10-29T17:52:54.693444+00:00", + "source": "Maintainer message in this conversation", + "message": "approved then.", + "run_id": "run_3k0spmw1cd3w8pmjsq65ggeese", + "gate": "f01-f01-s19-user-gate-before-record-explicit-human-a", + "request": "/home/omry/.local/state/awd/reploy-E-resume-20261028/OmegaFlow-requirements-baseline-approval-request-02.json", + "request_sha256": "150e7a008bb1169b5a13e54360ac4c4382c29c1e62641648a72a5cd0877f8865", + "approved_artifacts": { + "docs/consumers/omegaflow.md": "0f7f51ac1a2df979014cd44fe15519401bacb6f06d64ae06ea22de038e98d3cb", + "docs/consumers/omegaflow-rp-c6-requirements.md": "c1c823193042e0ce513d175fffafe2add489bc49bf56cfad61401302029ef9c6" + }, + "scope": "Full revised OmegaFlow RP-C6 requirements including R4 metadata/hash/absence without raw byte export and R9 actual-bound-state invalidation.", + "not_approved": [ + "HLD", + "LLD or slices", + "implementation", + "commit", + "publication", + "release" + ], + "review_stamp": false +}