Skip to content

Align developer guides with published kernel startup #44

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
irl-dan merged 2 commits into from
Oct 6, 2026
Merged

Align developer guides with published kernel startup #44

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8d2ef7d
Clarify published startup and isolated tool configuration
Oct 6, 2026
2880e19
Match contributor CI version to existing Python workflow pin
Oct 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion cli/CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ adapter should remain thin.

Required development tools are Python 3.10, Rust 1.87.0 with Clippy
and rustfmt, Bun 1.3.5, Node.js 22.22.3 or newer, and npm 10 or newer. CI uses
Python 3.10.18 and Node.js 24.20.0. Use those exact versions when you need to
Python 3.10.20 and Node.js 24.20.0. Use those exact versions when you need to
reproduce CI or release behavior. The hash-locked test dependencies include
Python 3.10 native wheels; use a Python 3.10 virtual environment for the install
and test commands below. Newer Python versions may select wheels whose hashes
Expand Down
72 changes: 42 additions & 30 deletions cli/bun/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,44 +16,52 @@ Markdown remain owned by the separate language/image layer.
`--output-contract native` accepts the actual native harness terminal and
preserves final prose without requiring a model-authored JSON envelope.
Semantic status is `not-applicable`: validate program artifacts independently.
`image-envelope` remains the default and requires the image-declared terminal
envelope in addition to native completion. `--output human|json|jsonl` controls
Ordinary published-kernel builds default to `native`; explicit image and test
builds default to `image-envelope`, which additionally requires the image-declared
terminal envelope. `--output human|json|jsonl` controls
rendering separately. See [native output](../../docs/native-output.md) and
[private native capture](../../docs/native-capture.md).

A build without image overrides still embeds the nonsemantic `echo-v0` image.
That is a packaging default, not a limit on the runner: production-shaped
builds can instead embed a verified language-owned image or minimal entry
pointer using the documented [image bundle configuration](../shared/image/bundle/README.md).
The configured image supplies instructions; choosing native output does not
replace an echo image with a language interpreter. No CLI source changes are
needed to swap image data. Native completion alone is not a release or
language-conformance claim.
A build without image overrides resolves and verifies the published kernel
when preparing a run through an installed harness. It also embeds `echo-v0`
for local diagnostics; that fixture is not a startup fallback. Help, version
and harness inventory do not retrieve the kernel. See
[kernel startup](../../docs/kernel-startup.md) for the acquisition policy and
[image bundle configuration](../shared/image/bundle/README.md) for fixed inputs.
Native completion alone does not establish contract fulfillment or language
conformance.

## Local development

```sh
cd cli/bun
bun install --frozen-lockfile
bun run check
./dist/prose --help
./dist/prose cli harness list
./dist/prose --harness codex --output json run fixture.prose.md
./dist/prose --harness codex --dry-run --output json run fixture.prose.md
```

Start these commands at the repository root. The final command requires an
installed supported Codex and may retrieve the public kernel, but makes no
model call. Its readiness report is not proof of authentication or fulfillment.

`bun run check` performs strict TypeScript checking, unit/integration/shared-
schema tests, standalone compilation, and standalone smoke tests. The compile
schema tests and ordinary standalone compilation. Standalone smoke assertions
are exercised by the test suite. The compile
command disables Bun's runtime `.env`, `bunfig.toml`, `tsconfig.json`, and
`package.json` autoloading. A test places hostile `.env` and `bunfig.toml`
files in the invoked working directory and proves that the standalone ignores
them.

`bun run build` is the ordinary local build, matching Rust's default: it embeds
`echo-v0`, reports the `development` profile, and compiles with test seams off.
`bun run build` is the ordinary local build, matching Rust's default: it enables
published-kernel startup, reports the `development` profile, and compiles with test seams off.
It writes `dist/prose`. `bun run build:test` is the explicit test-only build;
it creates a private temporary `sentinel-v1` bundle, enables test seams, writes
`dist/prose-test` by default, and removes the temporary bundle. The test-only
command refuses to overwrite `dist/prose`. `bun run build:release` embeds the
release-eligible `echo-v0` image with test seams off.
command refuses to overwrite `dist/prose`. `bun run build:release` reports the
release profile with published startup and test seams off. Its structural check
of the embedded diagnostic image does not qualify the kernel or authorize a release.

### Developer endpoint build (OpenProse developers only)

Expand All @@ -71,11 +79,10 @@ the default `dist/prose` outfile. Public builds define the switch as false, so
Bun removes the override code (`src/core/service/dev-endpoint.ts`) and the
variable name from the binary; `test/dev-endpoint.test.ts` checks both builds.

Builds without image overrides embed the deliberately nonsemantic `echo-v0` image. They can
discover and run exactly admitted user-installed Prime, OMP, Codex, Claude, and Agents SDK
Ordinary builds can discover and run supported user-installed Prime, OMP, Codex, Claude, and Agents SDK
harnesses through direct argument-array subprocesses. The adapters preserve
the complete image/task boundary, use adapter-specific credential allowlists,
and, in the default output-contract mode, recover the image-owned terminal
and, when `image-envelope` is explicitly selected, recover the image-owned terminal
envelope without a shell, outer PTY, or
harness fallback. Codex and Claude can use their installed login state. Prime
and OMP additionally require a fully qualified `provider/model` plus an
Expand Down Expand Up @@ -104,9 +111,13 @@ native output, SDK support, image selection, and environment profiles.
Functional-alpha admission is an exact audited allowlist: Prime `0.7.0` or
`0.8.1`, OMP `18.0.9`, Codex `0.149.0-alpha.4.1`, Claude `2.1.243`,
and the optional `prose-agents-sdk` harness `0.1.0` (currently macOS ARM64).
Nearby patches and prereleases are detected but refused, with the detected
identity, exact admitted set, and a copyable repair command in machine and
human doctor/run errors. The CLI build remains on its pinned Bun 1.3.5
These are exact audited identities, not a claim of qualification for every
accepted version. Claude additionally permits stable versions at or above the
recipe minimum within its major version. Codex permits an explicit
`--codex-compatibility probe` attempt after required capabilities are observed;
the default `qualified` mode retains its exact qualified set. Other unknown
identities remain rejected with actionable diagnostics. See
[Codex compatibility](../../docs/codex-compatibility.md). The CLI build remains on its pinned Bun 1.3.5
toolchain; the separate upstream OMP package/source audit used Bun 1.3.14.

Prime runs use one private per-run daemon socket. If its owned service cannot
Expand All @@ -130,16 +141,16 @@ binary uses Bun's `baseline` runtime variant rather than the AVX2-oriented
standard target; ARM64 binaries use their exact native target. Unsupported
build hosts fail before producing a mislabeled artifact.

The exact same user journey is available in release-profile functional-alpha
builds. A completed `echo-v0` invocation proves transport completion only: it
Published startup also applies to ordinary release-profile builds. A completed
explicit `echo-v0` invocation proves transport completion only: it
does not parse OpenProse, claim semantic success, or earn a strict-wrapper
claim. The default `openprose` identity still fails closed with
`HOSTED_UNAVAILABLE` until OpenProse-billed execution exists.

The deterministic `mock` and `fake-process` transports remain test-only. They
are admitted only by the explicit `bun run build:test` command, which carries
the release-ineligible sentinel image and enables test seams. Without image overrides, ordinary
`bun run build` and release-profile builds carry `echo-v0` with test seams off
`bun run build` and release-profile builds use published startup with test seams off
and refuse these transports before execution. Internal provider-free controls
cannot be enabled in a release build and never become a harness, language, or
billing fallback.
Expand All @@ -162,8 +173,9 @@ successfully on native Windows and that evidence is retained.

## Packaging boundary

The default build produces `dist/prose`, a local Bun standalone carrying
`echo-v0`; explicit image arguments select a different verified bundle. Functional-alpha packaging creates platform-specific npm packages
The default build produces `dist/prose`, a local Bun standalone using published
startup with an embedded diagnostic fixture. Explicit image arguments disable
published acquisition and select the verified bundle. Packaging creates platform-specific npm packages
and a small Node-compatible launcher in `@openprose/prose-cli`. Both products
embed the same exact prerelease SemVer and source revision through
`OPENPROSE_BUILD_VERSION` and `OPENPROSE_BUILD_COMMIT`. The launcher selects an
Expand All @@ -172,9 +184,9 @@ and SHA-256, performs no download or postinstall work, forwards signals, and
preserves the binary exit status. Isolated install, integrity, and foreground
signal tests exercise the packed tarballs without a registry.

The functional alpha is explicitly transport-only. Its package evidence keeps
publication and full-release admission false; a semantic release remains
blocked on the canonical language-owned image and its external authorities.
Build and package checks establish mechanical transport and integrity facts.
Current publication gates and release evidence are maintained in the
[release guide](../release/README.md); none establish contract fulfillment.

The Node interpreter used by installed-package conformance is deliberately not
copied away from its dynamic libraries. Its resolved installed executable is
Expand Down
12 changes: 12 additions & 0 deletions cli/protocol/OWNERSHIP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -777,3 +777,15 @@ IMP-086 lease extension: `cli/ci/test_rehearse_release.py` for exact current 64-
IMP-086 lease extension: `cli/conformance/fixtures/adapter-host-expectations.json` and the existing leased host runner/tests for independently frozen inventory expectations across admitted POSIX hosts; keep all Codex blocked-state and full-inventory assertions.

IMP-086 lease extension: `cli/ci/test_run_local.py` solely to make the interrupt-tree fixture reap its controlled descendant and publish readiness after signal-safe setup; supervisor behavior, 130/143 exits and PID-absence assertions remain unchanged.
## IMP-055 build documentation lane — October 5, 2026

Root authorized `/root/build_docs` on `codex/imp-055-build-docs` to edit exactly
`cli/bun/README.md`, `cli/rust/README.md`, `docs/kernel-startup.md`, and
`cli/shared/image/bundle/README.md`. Scope: published startup, fixed images,
diagnostic/test builds and explicit tool configuration; provider-free copied
example verification. No source, release documentation, model calls or new
Python. Root retains integration and publication ownership.

IMP-055 final documentation audit: root extends this branch's lease to
`cli/CONTRIBUTING.md` solely to align its stated CI Python patch version with
the existing workflow pin. No toolchain, workflow or Python source change.
58 changes: 37 additions & 21 deletions cli/rust/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,19 +9,20 @@ dependency on the repository's language or kernel packages.
`--output-contract native` accepts the actual native harness terminal and
preserves final prose without requiring a model-authored JSON envelope.
Semantic status is `not-applicable`: validate program artifacts independently.
`image-envelope` remains the default and requires the image-declared terminal
envelope in addition to native completion. `--output human|json|jsonl` controls
Ordinary published-kernel builds default to `native`; explicit image and test
builds default to `image-envelope`, which additionally requires the image-declared
terminal envelope. `--output human|json|jsonl` controls
rendering separately. See [native output](../../docs/native-output.md) and
[private native capture](../../docs/native-capture.md).

A build without image overrides still embeds the nonsemantic `echo-v0` image.
That is a packaging default, not a limit on the runner: production-shaped
builds can instead embed a verified language-owned image or minimal entry
pointer using the documented [image bundle configuration](../shared/image/bundle/README.md).
The configured image supplies instructions; choosing native output does not
replace an echo image with a language interpreter. No CLI source changes are
needed to swap image data. Native completion alone is not a release or
language-conformance claim.
A build without image overrides resolves and verifies the published kernel
when preparing a run through an installed harness. It also embeds `echo-v0`
for local diagnostics; that fixture is not a startup fallback. Help, version
and harness inventory do not retrieve the kernel. See
[kernel startup](../../docs/kernel-startup.md) for the acquisition policy and
[image bundle configuration](../shared/image/bundle/README.md) for fixed inputs.
Native completion alone does not establish contract fulfillment or language
conformance.

## Local verification

Expand All @@ -32,6 +33,10 @@ cargo clippy --workspace --all-targets --features prose-cli/test-seams --locked
cargo fmt --all -- --check
```

Start at the repository root. The remaining commands in this guide assume
`cli/rust` as the current directory. Use the pinned toolchain and install the
dependencies described in [contributing](../CONTRIBUTING.md) first.

Build and inspect an installed harness without starting a model run:

```sh
Expand All @@ -40,6 +45,10 @@ cargo build --locked -p prose-cli
./target/debug/prose --harness codex --dry-run --output json run example.prose.md
```

The dry run requires an installed supported Codex and may retrieve the public
kernel, but makes no model call. Readiness is not proof of authentication,
model availability or contract fulfillment.

The functional alpha can run installed `prime-agent`, `omp`, `codex`, and
`claude` executables directly, plus the optional `prose-agents-sdk` harness,
without a shell or outer PTY. Prime and OMP
Expand Down Expand Up @@ -67,10 +76,13 @@ native output, SDK support, image selection, and environment profiles.
Functional-alpha admission is an exact audited allowlist: Prime `0.7.0` or
`0.8.1`, OMP `18.0.9`, Codex `0.149.0-alpha.4.1`, Claude `2.1.243`,
and the optional `prose-agents-sdk` harness `0.1.0` (currently macOS ARM64).
Nearby patches and prereleases are detected but refused rather than admitted by
range extrapolation. Machine errors include the detected identity, exact
allowlist, and repair command; human doctor/run output prints the same copyable
repair command.
These are exact audited identities, not a claim of qualification for every
accepted version. Claude additionally permits stable versions at or above the
recipe minimum within its major version. Codex permits an explicit
`--codex-compatibility probe` attempt after required capabilities are observed;
the default `qualified` mode retains its exact qualified set. Other unknown
identities remain rejected with actionable diagnostics. See
[Codex compatibility](../../docs/codex-compatibility.md).

Prime runs use one private per-run daemon socket. If its owned service cannot
be settled, OpenProse recursively removes prompt, image, task, credential, and
Expand All @@ -93,12 +105,11 @@ OpenProse-billed adapter exists, a language run fails with
`HOSTED_UNAVAILABLE` and exit code 10. It never falls back to a third-party
harness.

Builds without image overrides embed the release-eligible `echo-v0` Skill Runtime Image. It is
a functional-alpha placeholder: it asks the selected harness to echo the task
and produce a structurally verified terminal envelope, so successful runs have
semantic status `not-applicable`. It does not implement the OpenProse language.
Strict wrapper admission and a full semantic release still require the future
canonical, language-owned runtime image plus versioned real-harness evidence.
An explicit build selecting the committed `echo-v0` image exercises transport
only: the image asks the harness to echo the task and produce a terminal
envelope. It does not implement OpenProse. Ordinary builds instead acquire the
published kernel on run. Both routes leave artifact fulfillment to independent
assessment; see the [release guide](../release/README.md) for current release gates.

An ordinary `cargo build` reports the development profile with test seams
disabled. An ordinary `cargo build --release` reports the release profile with
Expand All @@ -110,7 +121,7 @@ cargo build --locked -p prose-cli --features prose-cli/test-seams
```

The build rejects `--release` combined with `prose-cli/test-seams`. Release
workflows can set an exact validated prerelease version without editing Cargo
workflows can set an exact prerelease version without editing Cargo
metadata:

```sh
Expand All @@ -119,6 +130,11 @@ OPENPROSE_REQUIRE_RELEASE_IMAGE=1 \
cargo build --release --locked -p prose-cli
```

This still selects published startup unless explicit image paths are supplied.
`OPENPROSE_REQUIRE_RELEASE_IMAGE=1` checks the embedded diagnostic image's
structural eligibility; it does not pin or qualify the remotely selected kernel
or authorize publication.

## Developer endpoint build (OpenProse developers only)

Public builds talk only to the production OpenProse service; the service
Expand Down
30 changes: 28 additions & 2 deletions cli/shared/image/bundle/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,30 @@ bun ../../../bun/scripts/image-bundle.ts build \

Neither path requires an adapter or runner source edit. The build first checks
the source directory, exact staged bytes, and checksum; any drift fails closed.
Supply all three paths. This explicit selection disables published-kernel
acquisition and defaults to the image's terminal-envelope mode; select
`--output-contract native` explicitly when appropriate for the chosen image.
It pins the embedded instruction bytes, not the harness, model, toolchain,
dependencies or every other campaign input.

To inspect the existing committed diagnostic bundle and build an offline,
fixed-image Bun executable from the repository root:

```sh
bun cli/bun/scripts/image-bundle.ts check \
--image-dir cli/shared/image/echo-v0 \
--bundle cli/shared/image/embedded/current.bundle.bin \
--checksum cli/shared/image/embedded/current.bundle.sha256
bun cli/bun/scripts/image-bundle.ts build \
--image-dir cli/shared/image/echo-v0 \
--bundle cli/shared/image/embedded/current.bundle.bin \
--checksum cli/shared/image/embedded/current.bundle.sha256 \
--outfile cli/bun/dist/prose-echo
```

This selects the nonsemantic echo fixture, not OpenProse language execution.
The existing image staging/validation implementation still uses Python
internally; these commands do not introduce another implementation or dependency.

The Rust runner's explicit provider-free test build is separate from the
data-only replacement path:
Expand All @@ -49,6 +73,8 @@ cargo build --manifest-path ../../../rust/Cargo.toml -p prose-cli \
```

That development-only feature embeds `sentinel-v1` and enables the mock and
conformance seams. Ordinary development and release builds keep the committed
`echo-v0` image and report test seams as disabled. Combining `--release` with
conformance seams. Ordinary development and release builds without image
overrides acquire the verified published kernel for installed-harness runs;
they retain `echo-v0` only as a diagnostic fixture and keep test seams disabled.
See [published startup](../../../../docs/kernel-startup.md). Combining `--release` with
the test-seams feature fails closed.
Loading
Loading