diff --git a/docs/consumers/supporting/omegaflow-rp-c6-implementation-plan/approved-hld-workflow-preimage.txt b/docs/consumers/supporting/omegaflow-rp-c6-implementation-plan/approved-hld-workflow-preimage.txt new file mode 100644 index 00000000..795799d6 --- /dev/null +++ b/docs/consumers/supporting/omegaflow-rp-c6-implementation-plan/approved-hld-workflow-preimage.txt @@ -0,0 +1,548 @@ +--- +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. + +## High-level design + +Architecture proposal for review and maintainer acceptance. 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. HLD 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 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-implementation-plan/bounded-proof-evidence.json b/docs/consumers/supporting/omegaflow-rp-c6-implementation-plan/bounded-proof-evidence.json new file mode 100644 index 00000000..7b2eabfe --- /dev/null +++ b/docs/consumers/supporting/omegaflow-rp-c6-implementation-plan/bounded-proof-evidence.json @@ -0,0 +1,20 @@ +{ + "OmegaFlow-lld-stream-proof-result.json": { + "path": "/home/omry/.local/state/awd/reploy-E-resume-20261028/OmegaFlow-lld-stream-proof-result.json", + "sha256": "77296342e921500e313d3dddf9d4410edf7a39c8dc5697842119f4e272050310" + }, + "OmegaFlow-lld-stream-proof-attempt01-result.json": { + "path": "/home/omry/.local/state/awd/reploy-E-resume-20261028/OmegaFlow-lld-stream-proof-attempt01-result.json", + "sha256": "0d80e32b8ec4bcb5dc94479851a944a9d1d43abd1b0f307768164486f94b22e8" + }, + "OmegaFlow-lld-image-namespace-proof-result.json": { + "path": "/home/omry/.local/state/awd/reploy-E-resume-20261028/OmegaFlow-lld-image-namespace-proof-result.json", + "sha256": "29258adecb304005864b7a03cf41c33df43b105d64bac0180105181e2fda8be0" + }, + "watchdog_focused_test": { + "command": "go test ./internal/dockerdeploy -run '^(TestControlledSessionWatchdogParentLossRemovesOnlyManifestResources|TestControlledSessionWatchdogRetriesParentLossCleanupWhileDockerIsUnavailable|TestControlledSessionWatchdogRejectsPriorBootBeforeReady)$' -count=1", + "exit_code": 0, + "output": "ok github.com/omry/reploy/internal/dockerdeploy 0.008s", + "limits": "Existing shared algorithm tests, not native child-process proof." + } +} diff --git a/docs/consumers/supporting/omegaflow-rp-c6-implementation-plan/candidate-boundaries-and-sizing.md b/docs/consumers/supporting/omegaflow-rp-c6-implementation-plan/candidate-boundaries-and-sizing.md new file mode 100644 index 00000000..35f0aa8a --- /dev/null +++ b/docs/consumers/supporting/omegaflow-rp-c6-implementation-plan/candidate-boundaries-and-sizing.md @@ -0,0 +1,102 @@ +# Engineering sizing assessment before the LLD + +This is a source-based candidate responsibility map, not a canonical slice +inventory, reviewed estimate or implementation authorization. Actual IDs and +coherent cuts belong to the LLD authoring stage. Open readiness proofs can change +these ranges; a material mechanism or guarantee change returns to architecture +review. No production code has been written for these responsibilities. + +The historical 1300–2050 production / 2700–4350 test estimate is withdrawn as a +current forecast. It omitted real portable-channel/watchdog prerequisites and +did not settle image namespace protection. It remains historical evidence in the +approved preimage; the current consumer record must replace its table when the +full LLD is authored and reviewed. This assessment is not that final replacement. + +## Cost and compatibility audit disposition + +The [source/contract audit](scope-and-multi-identity-compatibility.md) found +substantial existing broker/protocol, protected-path, build/store and cleanup +behavior to reuse. The rows below are responsibility envelopes, not evidence +that each subsystem must be implemented again. In particular, the transport row +needs a container-private peer relay and host integration, not another public +controller broker. Existing namespace checks need complete evidence/alias +extensions, not an independent OmegaFlow policy compiler. + +The ranges and arithmetic below remain the pre-audit candidate assessment. They +are retained for traceability and are **not an accepted delivery forecast**. +No lower replacement total is justified until missing interfaces/proofs yield +concrete implementation deltas. Shared E/F foundations will have one owner in +the canonical LLD; backend adapters and qualification remain separate. + +## Counting convention + +Changed physical text lines means additions plus removals against the accepted +parent, including comments and blank lines. Production includes shipped runtime, +build and packaging configuration. Test code includes test helpers, test-only +configuration and textual fixtures. A line is counted once. Generated/vendor/ +lockfile changes, binaries, Markdown, review bookkeeping, release execution and +OmegaFlow-side changes are excluded. Native test access and evidence collection +are material non-LOC prerequisites, not free proof inferred from these figures. +No working-hour estimate is provided. + +## Candidate responsibility ranges + +Shared foundations have one owner here. Dependent rows reuse those foundations. +Ranges reflect the inspected current modules and the unproven work below, not +measurements or a fixed PR count. The 450–650 broker row exceeds the 500 target +at its upper bound but stays below the 750 hard maximum; refine its coherent +cut after the transport proof, rather than claim a 500-line cap was met. + +| Responsibility | Production/configuration LOC | Test-code LOC | Concrete change basis | +| --- | ---: | ---: | --- | +| Namespace path resolution | 300–500 | 650–1000 | Component-aware path/absence and ELF metadata observations in internal/probe; retain current inspection protocol compatibility. | +| Namespace mount protection | 300–500 | 700–1100 | Derived image execution/configuration roots; alias/ancestor/automatic-volume checks in dockerdeploy, not just lexical Bash overlap. | +| Container-private broker | 450–650 | 800–1300 | Packaged Linux helper peer credentials, one claim and bounded frame relay; reuse protocol validation. | +| Host portable channel integration | 300–500 | 700–1100 | Pinned local-engine attached stream and lifecycle integration; replace host Unix channel after parity proof, not a second default route. | +| macOS watchdog adapter | 80–160 | 250–450 | Reuse Unix inherited descriptor model and existing shared exact-manifest cleanup; native survival and receipt tests. | +| Windows watchdog adapter | 300–500 | 700–1100 | Explicit inherited private handles, detached child survival, readiness/disarm/EOF and incident target; reuse shared cleanup and boot identity. | +| Native safe supplied-file opening | 200–350 | 550–850 | Reuse providerstore expected-byte publication; descriptor-safe regular-file opening, alias refusal and source independence across native filesystems. | +| Selected image and environment provenance | 300–450 | 450–700 | Public selection retained into current ordinary provider build; separate inherited/application/final environment; no tag fallback. | +| Protected input contract and capture | 350–500 | 650–1000 | Bounded complete inventory and independent manifest expectation; validation, cancellation and generation-owned capture publication. | +| Normal image payload delivery | 350–500 | 650–1000 | Deterministic archive through current normal build, fixed modes, trusted collision check and exact final inventory verification. | +| Bounded public observations | 300–500 | 700–1100 | No-healthcheck trusted create profile, bounded requested facts, types and absence; reuse namespace resolver rather than duplicate. | +| Retained comparison record | 250–400 | 500–800 | Versioned opaque public identifier, private projection under existing generation ownership, record bounds and replay/deletion behavior. | +| Locked admission binding | 350–500 | 700–1100 | Expected identity on existing session entry; compare again after queue waits, pin through use, no caller-report trust or alias fallback. | +| Reachability and recovery | 250–400 | 500–850 | Capture/record/image generation reachability, cancellation and exact-owned cleanup/incident continuation. | +| Public interface composition | 250–400 | 450–750 | Existing native blueprint and structured CLI/JSON integration; user docs and Changie fragment excluded from LOC. | +| Integrated acceptance and adoption evidence | 150–300 | 1000–1600 | Full public path and refusal/cleanup matrix on inherited supported hosts plus WSL2 Desktop; three Linux/amd64 consumer profiles. | +| **Candidate total** | **4480–7110** | **9950–15800** | Sum of the above lower/upper bounds. | + +The first seven shared prerequisites subtotal **1930–3160 production/configuration LOC** and **4350–6900 test-code LOC**. Namespace enforcement, transport and native watchdogs are +substantive production work. They cannot be hidden in a test-only final slice. + +## Inspected reuse and uncertainty + +At current source, `controlledsession/channel.go` has 294 lines and its Linux +transport 179. The existing engine attach adapter has 219. Reuse bounded frame +validation and local-engine endpoint dialers; an engine non-TTY exec stream still +needs its own multiplexing, claim and cancellation handling, not a copied PTY +assumption. The broker and host rows include removal/adjustment of the old route. +The shared watchdog has 561 lines, its Linux launch adapter 231; retain the +algorithm instead of implementing cleanup separately per host. Darwin can reuse +Unix descriptor semantics; native proof is still required. Windows Go exposes +explicit inherited handles, but inherited process-job behavior and parent-loss +receipt ownership remain unproven. + +Current probe inspection has 230 lines but only resolves final symlinks. It is +not a complete safe ancestor resolver or namespace derivation module. The normal +payload image helper has 964 lines and staging 593; reuse the build/store graph, +not its image-shell destination checks. Providerstore has 676 lines and already +compares expected digests before publication. It does not supply native alias +checks, a complete supplied-input contract or generation reachability alone. + +The namespace rows remain the largest feasibility uncertainty: runtime lookup +paths, loader/configuration state, required absence, mount aliases and engine +mounts must be protected without a new generic dependency-analysis service. +The three cached image inspections establish loader/library presence only, not +that the proposed namespace derivation is sufficient or the Bash builds qualify. +If these requirements cannot fit a bounded trusted-helper extension, return to +architecture review before accepting the inventory or implementing it. + +Endpoint publication remains separate. The existing E campaign remains paused +before E2.3. No part of this estimate allocates E work to OmegaFlow. diff --git a/docs/consumers/supporting/omegaflow-rp-c6-implementation-plan/consumer-adoption-reconciliation.md b/docs/consumers/supporting/omegaflow-rp-c6-implementation-plan/consumer-adoption-reconciliation.md new file mode 100644 index 00000000..e57952ca --- /dev/null +++ b/docs/consumers/supporting/omegaflow-rp-c6-implementation-plan/consumer-adoption-reconciliation.md @@ -0,0 +1,44 @@ +# OmegaFlow RP-C6 consumer adoption reconciliation + +This is a Reploy-side contract mapping and handoff. It does not claim that the +OmegaFlow checkout has been edited, reviewed, qualified or adopted. The relayed +corrected request accepts protected copies and supplies the bounded hash +inventory. The approved Reploy architecture chooses ordinary immutable-image +delivery. Older consumer assumptions must be reconciled before adoption. + +## Required consumer changes + +| Older consumer assumption | Agreed contract | Adoption check | +| --- | --- | --- | +| Final executable runtime must be a read-only source bind at `/omegaflow-runtime`. | Retained bytes are verified against the supplied complete inventory and independent manifest digest, then delivered in the normal immutable final image at those paths with fixed modes. Physical source-bind type is not the acceptance fact. | C6.3 accepts protected image delivery and verifies protected inventory/path/mode facts. Remove the old required physical bind from reserved composition; do not patch composed YAML later. | +| A staged-tree hash establishes the runtime that will launch. | Hash the actual retained bytes against supplied expected hashes and verify the exact final-image inventory. The public prepared identity binds those facts through admission/use. | Pre-capture corruption refuses. Original source mutation/removal after independent capture remains valid. Workload writes and shadowing cannot replace protected contents. | +| Obtain raw Bash/system-rc bytes. | R4 requires bounded resolved path/type/digest/absence facts; no raw file export. | Compare Bash digest to OmegaFlow's qualified build table; require the exact selected system-rc path absent, with errors and dangling links distinguished from absence. | +| Any mutable tag/source change invalidates prior inspection. | Changes to actual admitted state invalidate; irrelevant external references do not. | Moving a tag with the same retained image and changing original files after capture succeeds; actual final image/generation/command/env/identity/mount/endpoints change refuses before bootstrap. | +| Reploy needs a consumer image-dependency inventory. | Reploy protects image code/configuration and lookup namespaces; OmegaFlow inventories only its 18 payload files plus manifest. | Bash, sh, loader and image libraries remain Reploy-owned. Do not add a discovery/snapshot task to OmegaFlow. | +| All runtime paths are protected/immutable. | App data is live; `/run/omegaflow` remains writable tmpfs for sockets/FIFOs. | App data changes remain ordinary runtime behavior; none may shadow protected contents or required absence. | + +## Governing sources and acceptance order + +The older source is [OmegaFlow part-C C6.3](../../../../../omegaflow/docs/design/part-c-implementation-design.md), +with the historical reserved-workload locator +`src/omegaflow/conf/reploy/envoy/reserved/default.yaml` in that checkout. That +file is absent at checkpoint verification; this is a historical source reference, +not a verified current composition. Resolve the consumer's actual composition +before adoption; no replacement source is inferred here. +Those checkout links are context, not new design authorities or claims of changed +consumer files. The corrected normative request is retained in +[the requirements source](../omegaflow-rp-c6-requirements/consumer-request-and-evaluation.txt) +and [R4/R9 clarification](../omegaflow-rp-c6-requirements/consumer-clarifications.md). +The approved requirements and HLD govern this mapping. + +1. Complete reviewed Reploy LLD and readiness proofs; implement only after its + required approval and separate delivery authorization. +2. Qualify the complete public inspection → admission → launch path and refusal/ + cleanup behavior on the supported hosts, including WSL2/Desktop. +3. Select an explicit compatible Reploy release/source and let OmegaFlow update + and review its bind-specific C6.3/composition checks through its own workflow. +4. OmegaFlow qualifies its three Bash compatibility profiles and supplied runtime + against that selected release before claiming RP-C6 unblocked. + +Endpoint publication is a separate dependency. This mapping does not resolve it +or restart OmegaFlow's paused campaign or Reploy milestone E. diff --git a/docs/consumers/supporting/omegaflow-rp-c6-implementation-plan/engineering-readiness.md b/docs/consumers/supporting/omegaflow-rp-c6-implementation-plan/engineering-readiness.md new file mode 100644 index 00000000..51ecfa81 --- /dev/null +++ b/docs/consumers/supporting/omegaflow-rp-c6-implementation-plan/engineering-readiness.md @@ -0,0 +1,117 @@ +# RP-C6 LLD engineering and proof readiness + +HLD approval permits LLD engineering and slice planning. It does not accept an +unproven namespace boundary, qualify a native host or authorize implementation. +Accepted requirements/HLD decisions remain unchanged. Original approved bytes +remain in the retained preimages and approval records; the documentation +checkpoint reconciles only stale approval/status wording. This material remains +an unfinished planning checkpoint, not an approved LLD. The full public support +contract remains Linux, native Windows, native macOS and WSL2, with the same +integrity/refusal/cleanup guarantees. + +## Bounded evidence retained + +[Proof identities and original locators](bounded-proof-evidence.json) bind the +real records. These are mechanism observations, not final public qualification. + +- A static disposable Go helper in a scratch image relayed binary bytes through + a non-TTY engine exec stream and a container-private Unix socket. The socket + refused UID 2000; the UID/GID 1000:1000 client exchanged exact bytes including + NUL and 0xff. Closing/unlinking after claim refused a second connection. + Exact owned image/container cleanup returned exit 0. The helper used read-only + root, no network, dropped capabilities and no-new-privileges. It did not mount + the host engine socket or publish a listener. This ran only on WSL2/Desktop. +- The first fixture attempt failed before READY. Its original source remains in + its ignored scratch workspace and its failure receipt is retained. Replacing + the fixture's bare blocking select with a timed hold permitted the second + attempt above. This is a fixture correction, not a Reploy runtime fix. +- Three focused current watchdog tests passed: exact-manifest parent-loss + cleanup, retry while Docker is unavailable, and rejection of a previous boot + before ready. These exercise the existing shared algorithm with test backends; + they do not prove a native detached child survives parent/process-job death. +- Cached Debian 12, Debian 13 and Ubuntu 26.04 candidates were created using + immutable image IDs, no-healthcheck, a never-started entrypoint, no network and + read-only root. Bounded docker-copy archives supplied Bash and loader config + metadata to trusted host readelf. All three Bash files name + `/lib64/ld-linux-x86-64.so.2`, `libtinfo.so.6` and `libc.so.6`; their loader + configuration includes multiarch and `/usr/local/lib` roots. Each container + remained `created` and was removed successfully. This is not a proof of all + lookup roots, protection enforcement or qualified Bash version/digest. + +## Chosen direction and finite unresolved engineering + +Use one engine-attached host channel if the complete proof preserves claim and +framing semantics. The scratch test favors it over maintaining a host Unix +transport plus native adapters: it avoids dependence on host socket ownership +and sharing while keeping peer credentials inside Linux. The current engine +attach module already has Unix/named-pipe endpoint adapters. Production still +needs non-TTY Docker multiplexing, cancellation and exact-container exec binding; +raw CLI fixture success does not prove those. No final transport replacement is +implementation-ready yet. Keep all protocol bounds and host validation. + +Keep the shared watchdog algorithm. Darwin can use inherited Unix descriptors; +Windows needs explicitly inherited private handles and child lifecycle flags. +The installed Go Windows syscall implementation exposes +`AdditionalInheritedHandles`, `NoInheritHandles` and `CreationFlags`. Their +existence does not establish process-job survival or leak-free native cleanup. +No replacement receipt authority, boot identifier or engine endpoint is needed. + +Namespace protection must include ancestor aliases, invocation/loader paths, +applicable library/configuration lookup roots, supplied payload and required +absence. Lexical comparison against `/bin/bash` alone is insufficient. The +current probe resolves final symlinks only; the account archive reader is narrow +and must not become a general image reconstruction service. Bounded trusted +path resolution and a demonstrably sufficient namespace derivation remain open. +An image-parser/dependency system or weaker guarantee would require renewed +architecture review. No such expansion is adopted here. + +## Design-readiness proof work, sized separately + +These are disposable design proofs, not production foundations or approved +implementation slices. Test-code ranges are authored fixture/harness physical +lines, additional to the shipping candidate estimate. Reuse results where +sufficient; actual temporary code is not silently counted as shipped product. + +| Proof | Production/configuration LOC | Disposable test-code LOC | Required result | +| --- | ---: | ---: | --- | +| Image namespace boundary on all three required profiles | 0 | 100–180 | Full path/alias/loader/config/absence and automatic-volume/mount-shadow refusal, alongside allowed live data; no image code during inspection. | +| Portable private stream parity | 0 | 80–140 | Single exact peer claim, frame limits/multiplexing, disconnect/cancel/ambiguous exec cleanup on Unix and Windows local endpoints. | +| Native macOS watchdog | 0 | 80–140 | Detached child survives abrupt parent exit, private descriptor inheritance, exact receipt and owned cleanup. | +| Native Windows watchdog | 0 | 100–180 | Explicit private handle list, parent/job-loss survival, no inherited liveness writer leak, exact receipt and owned cleanup. | +| **Total remaining design-proof envelope** | **0** | **360–640** | Separate from production implementation and full public-path acceptance. | + +The envelope is provisional; real fixture size and results replace it. It does +not promise that production foundations can be implemented as a design proof. +The existing WSL stream and old shared-algorithm tests remain reusable evidence, +not substitutes for the listed unresolved controls. + +## Execution prerequisites and next supported point + +The current execution environment is WSL2. The maintainer confirms native +Windows and macOS machines are easily available; Linux is possible. This answers +the machine-availability question. Execution targets/access details are not yet +bound and no native proof is inferred. Availability no longer blocks engineering. The T3 linked-environment listing tool is not callable in this +session (`TypeError: tools.mcp__t3_code__t3_environment_links is not a function`). +Earlier Windows interop returned UtilAcceptVsock failures; a bounded recheck did +not produce a retained result and establishes no new version/access fact. +Native host target/access information is needed before claiming those mechanism +proofs. Existing Windows CI explicitly skips Docker and cannot stand in for +full native acceptance. Do not drop platforms or use WSL as native evidence. + +The current responsible action is +`f01-f05-s02-inspect-current-source-and-real-prerequi` in +`run_3k0spmw1cd3w8pmjsq65ggeese`. Source investigation and the narrow results +above are retained. Important engineering rules and native proof remain open. +The canonical LLD and implementation inventory have not been authored, reviewed +or accepted; do not advance to a ready implementation plan from this material. + +See [candidate ranges and source basis](candidate-boundaries-and-sizing.md) and +[consumer adoption reconciliation](consumer-adoption-reconciliation.md). + +## Subsequent bounded scope/compatibility check + +The [source/contract audit](scope-and-multi-identity-compatibility.md) is complete. +It identifies shared E/F ownership, reuse and required regression boundaries. +It does not complete the broader LLD/proof stage. Three focused existing Go +test groups passed on the unchanged source; the native and namespace proof +gates remain open. Do not revive the answered availability-only question. diff --git a/docs/consumers/supporting/omegaflow-rp-c6-implementation-plan/input-resolution.json b/docs/consumers/supporting/omegaflow-rp-c6-implementation-plan/input-resolution.json new file mode 100644 index 00000000..7bd69657 --- /dev/null +++ b/docs/consumers/supporting/omegaflow-rp-c6-implementation-plan/input-resolution.json @@ -0,0 +1,12 @@ +{ + "run_id": "run_3k0spmw1cd3w8pmjsq65ggeese", + "source_sections": { + "requirements": "existing requirements in docs/consumers/omegaflow.md, identical decisions to approved clean requirements", + "hld": "High-level design section in docs/consumers/omegaflow.md" + }, + "input_preimage": "docs/consumers/supporting/omegaflow-rp-c6-implementation-plan/approved-hld-workflow-preimage.txt", + "sha256": "348371b18433691d73b3589ff6502b817bef1cc40dfedf197a8c39ded646337e", + "output_sections": "new Low-level design and implementation plan section; replace historical estimate with current plan link under explicit approval; preserve accepted requirements and HLD", + "clean_output": "docs/consumers/omegaflow-rp-c6-implementation-plan.md", + "implementation_authorized": false +} diff --git a/docs/consumers/supporting/omegaflow-rp-c6-implementation-plan/pre-audit-candidate-assessment.txt b/docs/consumers/supporting/omegaflow-rp-c6-implementation-plan/pre-audit-candidate-assessment.txt new file mode 100644 index 00000000..d57cefe2 --- /dev/null +++ b/docs/consumers/supporting/omegaflow-rp-c6-implementation-plan/pre-audit-candidate-assessment.txt @@ -0,0 +1,86 @@ +# Engineering sizing assessment before the LLD + +This is a source-based candidate responsibility map, not a canonical slice +inventory, reviewed estimate or implementation authorization. Actual IDs and +coherent cuts belong to the LLD authoring stage. Open readiness proofs can change +these ranges; a material mechanism or guarantee change returns to architecture +review. No production code has been written for these responsibilities. + +The historical 1300–2050 production / 2700–4350 test estimate is withdrawn as a +current forecast. It omitted real portable-channel/watchdog prerequisites and +did not settle image namespace protection. It remains historical evidence in the +approved preimage; the current consumer record must replace its table when the +full LLD is authored and reviewed. This assessment is not that final replacement. + +## Counting convention + +Changed physical text lines means additions plus removals against the accepted +parent, including comments and blank lines. Production includes shipped runtime, +build and packaging configuration. Test code includes test helpers, test-only +configuration and textual fixtures. A line is counted once. Generated/vendor/ +lockfile changes, binaries, Markdown, review bookkeeping, release execution and +OmegaFlow-side changes are excluded. Native test access and evidence collection +are material non-LOC prerequisites, not free proof inferred from these figures. +No working-hour estimate is provided. + +## Candidate responsibility ranges + +Shared foundations have one owner here. Dependent rows reuse those foundations. +Ranges reflect the inspected current modules and the unproven work below, not +measurements or a fixed PR count. The 450–650 broker row exceeds the 500 target +at its upper bound but stays below the 750 hard maximum; refine its coherent +cut after the transport proof, rather than claim a 500-line cap was met. + +| Responsibility | Production/configuration LOC | Test-code LOC | Concrete change basis | +| --- | ---: | ---: | --- | +| Namespace path resolution | 300–500 | 650–1000 | Component-aware path/absence and ELF metadata observations in internal/probe; retain current inspection protocol compatibility. | +| Namespace mount protection | 300–500 | 700–1100 | Derived image execution/configuration roots; alias/ancestor/automatic-volume checks in dockerdeploy, not just lexical Bash overlap. | +| Container-private broker | 450–650 | 800–1300 | Packaged Linux helper peer credentials, one claim and bounded frame relay; reuse protocol validation. | +| Host portable channel integration | 300–500 | 700–1100 | Pinned local-engine attached stream and lifecycle integration; replace host Unix channel after parity proof, not a second default route. | +| macOS watchdog adapter | 80–160 | 250–450 | Reuse Unix inherited descriptor model and existing shared exact-manifest cleanup; native survival and receipt tests. | +| Windows watchdog adapter | 300–500 | 700–1100 | Explicit inherited private handles, detached child survival, readiness/disarm/EOF and incident target; reuse shared cleanup and boot identity. | +| Native safe supplied-file opening | 200–350 | 550–850 | Reuse providerstore expected-byte publication; descriptor-safe regular-file opening, alias refusal and source independence across native filesystems. | +| Selected image and environment provenance | 300–450 | 450–700 | Public selection retained into current ordinary provider build; separate inherited/application/final environment; no tag fallback. | +| Protected input contract and capture | 350–500 | 650–1000 | Bounded complete inventory and independent manifest expectation; validation, cancellation and generation-owned capture publication. | +| Normal image payload delivery | 350–500 | 650–1000 | Deterministic archive through current normal build, fixed modes, trusted collision check and exact final inventory verification. | +| Bounded public observations | 300–500 | 700–1100 | No-healthcheck trusted create profile, bounded requested facts, types and absence; reuse namespace resolver rather than duplicate. | +| Retained comparison record | 250–400 | 500–800 | Versioned opaque public identifier, private projection under existing generation ownership, record bounds and replay/deletion behavior. | +| Locked admission binding | 350–500 | 700–1100 | Expected identity on existing session entry; compare again after queue waits, pin through use, no caller-report trust or alias fallback. | +| Reachability and recovery | 250–400 | 500–850 | Capture/record/image generation reachability, cancellation and exact-owned cleanup/incident continuation. | +| Public interface composition | 250–400 | 450–750 | Existing native blueprint and structured CLI/JSON integration; user docs and Changie fragment excluded from LOC. | +| Integrated acceptance and adoption evidence | 150–300 | 1000–1600 | Full public path and refusal/cleanup matrix on inherited supported hosts plus WSL2 Desktop; three Linux/amd64 consumer profiles. | +| **Candidate total** | **4480–7110** | **9950–15800** | Sum of the above lower/upper bounds. | + +The first seven shared prerequisites subtotal **1930–3160 production/configuration LOC** and **4350–6900 test-code LOC**. Namespace enforcement, transport and native watchdogs are +substantive production work. They cannot be hidden in a test-only final slice. + +## Inspected reuse and uncertainty + +At current source, `controlledsession/channel.go` has 294 lines and its Linux +transport 179. The existing engine attach adapter has 219. Reuse bounded frame +validation and local-engine endpoint dialers; an engine non-TTY exec stream still +needs its own multiplexing, claim and cancellation handling, not a copied PTY +assumption. The broker and host rows include removal/adjustment of the old route. +The shared watchdog has 561 lines, its Linux launch adapter 231; retain the +algorithm instead of implementing cleanup separately per host. Darwin can reuse +Unix descriptor semantics; native proof is still required. Windows Go exposes +explicit inherited handles, but inherited process-job behavior and parent-loss +receipt ownership remain unproven. + +Current probe inspection has 230 lines but only resolves final symlinks. It is +not a complete safe ancestor resolver or namespace derivation module. The normal +payload image helper has 964 lines and staging 593; reuse the build/store graph, +not its image-shell destination checks. Providerstore has 676 lines and already +compares expected digests before publication. It does not supply native alias +checks, a complete supplied-input contract or generation reachability alone. + +The namespace rows remain the largest feasibility uncertainty: runtime lookup +paths, loader/configuration state, required absence, mount aliases and engine +mounts must be protected without a new generic dependency-analysis service. +The three cached image inspections establish loader/library presence only, not +that the proposed namespace derivation is sufficient or the Bash builds qualify. +If these requirements cannot fit a bounded trusted-helper extension, return to +architecture review before accepting the inventory or implementing it. + +Endpoint publication remains separate. The existing E campaign remains paused +before E2.3. No part of this estimate allocates E work to OmegaFlow. diff --git a/docs/consumers/supporting/omegaflow-rp-c6-implementation-plan/scope-and-multi-identity-compatibility.md b/docs/consumers/supporting/omegaflow-rp-c6-implementation-plan/scope-and-multi-identity-compatibility.md new file mode 100644 index 00000000..0645c2ff --- /dev/null +++ b/docs/consumers/supporting/omegaflow-rp-c6-implementation-plan/scope-and-multi-identity-compatibility.md @@ -0,0 +1,127 @@ +# OmegaFlow scope, reuse and multi-identity compatibility assessment + +Current-agent source/contract audit at `9ce81ef698e0882e6b9559e49ee1bfd8443b1fde`. +This assesses the proposed implementation direction, not an implemented feature. +The focused existing tests below passed. No independent review, native platform +qualification, complete LLD acceptance or implementation readiness is claimed. + +## Decision and limits + +Preserve the approved requirements and HLD. Use the existing controlled-session +entry, broker/protocol, image/build/store, protected-path policy and cleanup +algorithm. Limit new work to missing observations/capture/admission behavior and +the transport/process adapters needed by the existing public host commitment. + +No inherent contract conflict was found with multi-identity E/F under the +constraints below. The largest overlap is the shared image-code/mount protection +foundation. Its production derivation is not implemented by E2.2, so it cannot +be counted as already available. Work brought forward by OmegaFlow must be +reusable by F without treating a Docker observation as mapped Podman proof. + +The previous candidate total is not a reviewed or accepted delivery forecast. +Source inspection supports significant reuse but does not establish a cheaper +replacement total. Do not lower estimates to satisfy an expectation, count +future F integration as already delivered, or assume every platform needs a +separate implementation of the feature. + +## Concrete waste controls from source + +| Area | Existing implementation | Minimum extension and waste to avoid | +| --- | --- | --- | +| Controller behavior | `controlledsession/controller_broker.go`, `controller_stream.go`, `client.go` already implement the public broker, bounded messages and session state. | Keep these. Add only the missing engine-stream/private-peer transport integration. The existing broker dials the host socket; it is not itself the new container-side transport endpoint. Neither a second controller broker nor claiming that portability is already solved is justified. | +| Host claim and authorization | `controlledsession/channel.go` already owns one claim, exact UID/GID comparison, opened-first ordering and bounded frames. | Preserve this contract through an appropriate transport adapter. Do not duplicate protocol validation or add another permission system. The container-side trusted peer result must remain bound to the exact host-created exec/container. | +| Engine connection | `docker_pty_attach.go` plus Windows/Unix dialers already provide pinned local connections and hijack/cancellation patterns. | Reuse endpoint selection/dialing. Non-TTY exec framing, multiplexing and ambiguous-start cleanup still need explicit engineering; a PTY adapter cannot simply be relabeled. Avoid host TCP listeners, controller engine access or a new engine SDK. | +| Watchdog | Shared `controlled_session_watchdog.go` owns exact-manifest cleanup, retries and receipts; Linux has the launch adapter. | Keep the shared algorithm. Prove/reuse a Unix adapter for macOS and a private-handle adapter for Windows. Do not implement separate cleanup engines, boot IDs or per-OS observation policies. | +| Source capture | Providerstore has `PublishExpected` and `OpenVerifiedArtifact`; existing source snapshots use held roots and verified copies. | Extend these primitives for the bounded complete expected-hash inventory and native alias checks. Do not build a snapshot service or copy/hash live application data. Store verification does not replace safe source opening or full inventory ownership. | +| Image payload | `portable_runtime_payload_image.go` already owns ordinary payload-layer build and final inventory comparison. | Reuse build/archive/ownership paths. Replace image-shell collision checks for the new trusted-only inspection path; do not duplicate the build pipeline or generalize unrelated provider behavior by default. | +| Protected paths | `runtime_policy_compile.go` already compiles executable/link/provider roots and checks mount overlap. E2.2 checks complete resolved code and mount proof. | Extend canonical evidence and these checks, with one namespace foundation. Do not add an independent OmegaFlow-only policy/compiler. Full loader/configuration lookup derivation is still unresolved and is not proven by current lexical overlap checks. | +| Admission | Current session entry already owns generation selection, sorted operation locks, leases and queue waits. | Add an opaque expected-state comparison to the same path, recheck after waits and retain resources through use. No parallel launcher, receipt authority or lock hierarchy. | +| Testing | Existing protocol, broker, protected-path, proof-refusal and lifecycle tests cover shared behavior. | Reuse them. Add changed-boundary tests and complete required public acceptance per host. Do not write a new exhaustive per-OS protocol suite or repeat a passing check without changed risk. Cross-compilation is not native lifecycle proof. | + +Using a different ordinary application launch command would not satisfy approved +R8, which explicitly requires the existing controlled-session entry. It is not +a legitimate shortcut without an approved requirements change. The current +architecture does not require another launcher. + +## E/F compatibility crosswalk + +| Shared concern | Existing multi-identity authority/owner | Compatibility requirement for OmegaFlow | +| --- | --- | --- | +| Identity declarations and grants | D records users/groups/roles/capability intent; E authorizes actual native startup. | Supplied-file declarations and an inspection identity grant no UID/GID, capability, mapping or launch authority. Keep ordinary empty-capability behavior and exact private-descriptor closure. | +| Immutable image/code closure | E2.2 `mapped_sandbox_proof.go`; E design assigns production closure/mount observations to F. | Add image/payload evidence through shared generation and protected-path machinery. Keep a complete trusted code-closure derivation reusable by F; don't treat the new public report as F's production proof. | +| Proof freshness | E2.2 binds proof to mapped request, generation/image, container/PID, runtime/network policy, complete code and resolved mount observations. | A public opaque inspection identity is only a comparison input. It lacks that live-instance evidence and cannot satisfy or bypass this gate. Reuse common facts through a future trusted adapter, not by decoding caller reports into mapped proof. | +| Managed storage | F1/F2 require descriptor-safe owned objects, exclusive prepare/attach, restart inhibition and exact recovery. | Capturing an external source during preparation must produce independent generation-owned contents. It does not authorize arbitrary external runtime binds in mapped workloads. Reuse descriptor/inventory helpers where sufficient; F keeps attachment/ownership proofs. | +| Lifetime and replacement | E3.1 owns native-master lifetime, leases and host-admitted replacement; engine-autonomous restart cannot bypass admission. | Retain host-owned cleanup, exact resource IDs and journal/receipt handling. A portable host watchdog does not introduce a privileged resident workload supervisor or grant the controller resource-creation authority. | +| Every execution entry | E4.1/E4.2 require authority checks across commands, tests, shell, hooks, controlled sessions, replacement and exec. | Keep the current public unmapped guard. Expected-state success must not unlock identity_policy/identity_mapping. Future mapped session entry still needs the same E/F/G gate and final startup boundary. | +| Backend/host qualification | Mapped cohort is non-root staging/user-scope local rootless Linux Podman; public activation stays closed. | OmegaFlow Docker/Desktop host evidence is separate. It neither activates mapped execution nor qualifies Podman/network/storage behavior. No expansion of mapped host/backend scope is adopted. | +| Lock and schema continuity | E uses the existing writer and F observation provider must not reacquire OperationLock. Retained generations/legacy admission state remain meaningful. | Add records beneath existing ownership, retain current lock ordering and revalidate after queue waits. Do not alter mapping journal/binding semantics, rewrite legacy states or add unreviewed required fields to old records. | +| Same-identity authority | A same-UID role name does not create isolation; privileged native masters retain their accepted authority. | The relay must run at its declared existing controller authority with protected helper code. Peer UID and helper packaging do not promise isolation from other processes with the same accepted identity. | + +## Ownership and delivery ordering + +1. During OmegaFlow LLD, define one immutable namespace evidence foundation using + the current protected-path representation, with explicit resolved aliases, + lookup roots, required absence and mount inventory. Prove a bounded solution + for the three required profiles. No general dependency-analysis service. +2. Own that foundation once in the eventual OmegaFlow slice inventory. Mark its + E2.2/F consumers and integration tests; F's mapped live evidence adapter and + storage/attachment/network qualification remain separate unfinished work. +3. Own portable host transport/process adapters once under existing session + machinery. E3.1 consumes the unchanged lifecycle contract rather than growing + another watcher. Preserve protocol/release compatibility when modifying the + packaged helper. +4. Implement selection, capture, safe inspection and expected-state admission as + coherent extensions through the current build/generation/session path. +5. Qualify the full public path on the promised hosts, with exact versions and + storage locations. Endpoint publication and consumer release adoption stay + separate. No part of this audit resumes E2.3 or changes E/F approval. + +This ordering identifies reuse; it does not reserve new slices, change approved +multi-identity documents or subtract unmeasured LOC from future F estimates. + +## Review and delivery checks required by this assessment + +- Current source calls `unmappedRuntimeDocumentV1` for both loaded session + deployments. Retain no-effect refusal for identity policy, declared mapping and + retained mapping authority. Add direct controller/workload expected-identity + regression coverage when implementing that admission input. The general guard + tests run below cover other real payload entries; they are not direct tests + of the not-yet-implemented expected-identity path. +- Preserve E2.2 tests for wrong request/network, writable root, missing/substituted + closure, required-code omission and direct/resolved mount shadow. Keep missing + production F observation fail-closed. Root `/` is explicitly rejected as a + code-closure shortcut. +- One shared fact library must not erase the distinction between immutable-image + facts, current host-owned plan and fresh live-container observation. +- Retain ordinary unmapped lifecycle and frozen controller protocol behavior + while adding transport adapters. Refusal, disconnect, parent death and exact + cleanup must remain valid; no engine-autonomous restart bypass. +- Public opaque comparison identifiers confer no authorization. Private internal + plan/generation digests remain outside public stream and diagnostics. +- Reuse Linux/WSL container evidence where it establishes identical shared code, + but obtain actual Windows/macOS adapter and full public-path evidence. Do not + weaken or silently drop a required acceptance case to reduce testing cost. + +## Evidence and stopping point + +Three focused Go test groups passed on the unchanged checkout: existing +controller claim/protocol/broker behavior; mapped sandbox and protected-path +contracts plus ordinary session orchestration; and mapped public-entry guard +behavior. Commands, exact source hashes and outputs are retained in +`/home/omry/.local/state/awd/reploy-E-resume-20261028/OmegaFlow-waste-compatibility-audit-evidence.json`. +These are current Linux/WSL checks, not native platform or unimplemented feature +qualification. No runtime fix is claimed. + +Planning corrections: the earlier candidate labels did not clearly distinguish +existing broker/policy behavior from missing transport/namespace extensions. +This is a representation fix in the planning material. The underlying native +portability and complete namespace proof gaps remain. The production estimate +needs concrete delta sizing after those interfaces are settled; no lower total +is asserted by this audit. + +See [the candidate assessment](candidate-boundaries-and-sizing.md), +[engineering readiness](engineering-readiness.md) and +[consumer reconciliation](consumer-adoption-reconciliation.md). +The approved requirements/HLD remain unchanged. The same parent LLD engineering +stage remains incomplete; this bounded audit is complete. Stop here for this +requested assessment without implementation, publication or E resumption.