RFCs: structured execution contexts and manifest composition - #600
RFCs: structured execution contexts and manifest composition#600leynos wants to merge 10 commits into
Conversation
Specify identity-based stream validation and deterministic pipeline relay cleanup. Keep generated Ninja manifests usable through leased, persistent action-plan sidecars.
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
Warning Your free Security trial is over. An organization admin can activate billing to continue. Comment |
Reviewer's GuideThis documentation-only PR establishes a staged manifest-composition design: RFC 0002 provides deterministic local includes, RFC 0003 layers typed and versioned local bundles with exports, digests, and locks, and RFC 0004 later extends the model to exact, digest-pinned Git acquisition; an RFC 0001 amendment independently standardizes capability-scoped structured-command working directories. Sequence diagram for local bundle resolution and lockingsequenceDiagram
participant Manifest
participant Resolver
participant Catalogue
participant Bundle
participant Lock
Manifest->>Resolver: resolve bundle source and version
Resolver->>Catalogue: enumerate candidates in sorted order
Catalogue-->>Resolver: bundle descriptors
Resolver->>Resolver: select highest compatible SemVer
Resolver->>Bundle: validate parameters and exports
Bundle-->>Resolver: canonical content digest
Resolver->>Lock: verify selected version and digests
Lock-->>Resolver: lock status
Resolver-->>Manifest: namespaced exported declarations
Sequence diagram for digest-pinned external Git bundle verificationsequenceDiagram
participant Manifest
participant GitResolver
participant GitRemote
participant Cache
participant Verifier
participant Lock
Manifest->>GitResolver: resolve exact tag or commit
GitResolver->>GitRemote: fetch normalized refs/tags/... or full commit
GitRemote-->>GitResolver: Git objects and tag provenance
GitResolver->>Verifier: verify subdir, metadata, SemVer, and canonical digest
Verifier->>Cache: read or publish content-addressed bundle
Cache-->>Verifier: verified content
Verifier->>Lock: compare tag, peeled commit, and digest
Lock-->>Verifier: lock verification result
Verifier-->>Manifest: verified bundle instance
Sequence diagram for structured command cwd executionsequenceDiagram
participant Compiler
participant ActionRunner
participant WorkspaceCapability
participant ChildProcess
Compiler->>ActionRunner: provide ProcessSpec with cwd
ActionRunner->>WorkspaceCapability: resolve and validate cwd
WorkspaceCapability-->>ActionRunner: capability-relative directory
ActionRunner->>ChildProcess: spawn with current_dir(cwd)
ChildProcess-->>ActionRunner: process result
Flow diagram for deterministic local manifest compositionflowchart TD
ROOT[Root manifest]
PARSE[Parse literal includes]
RESOLVE[Resolve relative to including file]
CHECK[Check workspace boundary and canonical identity]
RECURSE[Compose nested includes depth-first]
MERGE[Append declarations in post-order]
VALIDATE[Reject cycles and duplicates]
PROVENANCE[Retain source spans and include chains]
GRAPH[Build deterministic manifest graph]
ROOT --> PARSE
PARSE --> RESOLVE
RESOLVE --> CHECK
CHECK --> RECURSE
RECURSE --> MERGE
MERGE --> VALIDATE
VALIDATE --> PROVENANCE
PROVENANCE --> GRAPH
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![codescene-access[bot]](https://avatars.githubusercontent.com/in/3755875?s=60&v=4){kind=small}
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9304b658e5
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| @@ -0,0 +1,501 @@ | |||
| # RFC 0001 amendment: Structured-command working directories | |||
There was a problem hiding this comment.
This creates a second document identified as RFC 0001 alongside the existing 0001-structured-command-blocks.md, despite the documentation style guide requiring sequentially allocated RFC numbers, the # RFC NNNN: ... title form, and an RFC-number preamble entry. References to “RFC 0001” are consequently ambiguous, so either fold this proposal into the original as described later in the document or allocate it its own number before publishing it.
AGENTS.md reference: AGENTS.md:L57-L58
Useful? React with 👍 / 👎.
| - source: | ||
| catalogue: build/bundle-catalogue/rust-quality | ||
| version: "^1.4" | ||
| as: rust |
There was a problem hiding this comment.
When a catalogue contains descriptors for more than one declared bundle name, this import supplies only a version range and namespace, while the resolution algorithm groups candidates by bundle name and then says to select the highest matching version. There is no rule for choosing among those groups, so implementations can select different bundle identities from the same catalogue. Add an expected bundle name to the import or require and validate that every candidate has one identity.
Useful? React with 👍 / 👎.
| - files not reachable from the bundle composition unless the descriptor lists | ||
| them as runtime resources; and |
There was a problem hiding this comment.
A bundle recipe can invoke a bundled script or consume a data file that is not reachable through the manifest include graph, but this exclusion leaves that file outside the content digest. The descriptor schema defines no runtime-resource field—the mechanism is still an open question—so changing such a script would continue to satisfy local lock verification and RFC 0004's mandatory external digest even though executed behaviour changed. Define and require a resource declaration now, or hash the complete selected bundle tree.
Useful? React with 👍 / 👎.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
leynos
changed the title
1 participant
Summary
Adds the staged manifest-composition RFC sequence requested for the v0.2.0 design gate:
It also adds two normative amendments to RFC 0001:
cwdfor direct, shell, sequence, and pipeline execution;pipe: stderrto connect one stage's standard error to the next stage's standard input;cwd: { env: NAME }with text-versus-directory-capability enforcement; andSequencing
This PR is intentionally stacked on #573 so its RFC numbering and documentation index build on RFC 0001. The implementation order remains:
Tagged Git references are supported in the external RFC as exact
refs/tags/...resolution. Tags are discovery handles, not trust anchors: the lock record stores tag-object and peeled-commit identities, while the reviewed canonical bundle digest binds the bytes.The structured-command amendments should be folded into RFC 0001 before that RFC moves from Proposed to Accepted.
Structured runtime contract
The new runtime-binding amendment deliberately avoids parent-process environment mutation. Captures and secure-directory bindings live only in one action-runner sequence and enter later child environments through an owned overlay.
Captured stdout is bounded before strict UTF-8 decoding, redacted by default, and committed only after successful execution. A text binding cannot grant authority to an absolute external directory merely by containing its path. Runner-created secure tempdirs carry a separate typed directory capability, receive owner-only permissions before child access, and are removed after success, failure, cancellation, or spawn error.
pipe: stderrselects standard error as the raw byte stream for the next stage's stdin. It does not merge stdout and stderr, and it never connects a process's own writable stderr handle to its own readable stdin.Scope
Documentation and design only. This PR does not implement composition, bundle resolution, networking, caching, locking, structured-command working directories, runtime captures, stream selection, or secure tempdirs.
Review focus
cwdresolution, capability, and stream-path semantics;pipe: stderrvalidation and pipeline cleanup;Related work