Skip to content

feat(echo): wire trusted runtime lifecycle into jedit - #27

Merged
flyingrobots merged 58 commits into
mainfrom
stack/trusted-echo-runtime-lifecycle-port
May 24, 2026
Merged

flyingrobots merged 58 commits into
mainfrom
stack/trusted-echo-runtime-lifecycle-port

Conversation

@flyingrobots

Copy link
Copy Markdown
Owner

Summary

This PR wires jedit's Echo lifecycle authority into the product-side integration path without letting application code tick Echo.

It adds five focused slices:

  1. Trusted Echo runtime lifecycle port over the trusted host control transport.
  2. Echo-powered TextBufferOptic session composition that requests lifecycle after mutations only.
  3. Agent-facing session witness command for create/edit/read JSON evidence.
  4. Trusted lifecycle Stop support through the same host-only port.
  5. Trusted host shutdown witness that records stop evidence after the session run.

Authority boundaries

  • App code still holds TextBufferOptic, not Echo control exports.
  • Mutations request host lifecycle after app-safe intent submission.
  • Reads do not request lifecycle.
  • requestRunUntilIdle and requestStop remain trusted-host-only.
  • No tick, step, advance, raw control dispatch, or app cancellation API is exposed.
  • The fast agent command uses the fake Echo-shaped transport; the opt-in real Echo WASM witness remains the substrate proof.

Verification

  • npm run check
  • npm run witness:echo:session

npm run check passed locally with 279 passing tests, 1 opt-in real Echo WASM witness skipped, and quality clean.

@coderabbitai

coderabbitai Bot commented May 23, 2026 •

Copy link
Copy Markdown

Review Change Stack

Warning

Review limit reached

@flyingrobots, we couldn't start this review because you've used your available PR reviews for now.

Your plan currently allows 1 review/hour. Refill in 55 minutes and 31 seconds.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more review capacity refills, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than trial, open-source, and free plans. In all cases, review capacity refills continuously over time.

Please see our FAQ for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 5094eb56-5f02-41af-a549-dbaa3f01d0db

📥 Commits

Reviewing files that changed from the base of the PR and between d300891 and 0b54e67.

📒 Files selected for processing (57)
  • docs/BEARING.md
  • docs/data-model.md
  • docs/design/0020-trusted-echo-runtime-lifecycle-port/trusted-echo-runtime-lifecycle-port.md
  • docs/design/0021-echo-powered-text-buffer-optic-session/echo-powered-text-buffer-optic-session.md
  • docs/design/0022-agent-echo-powered-session-witness/agent-echo-powered-session-witness.md
  • docs/design/0024-jedit-powered-by-echo-release-gate.md
  • docs/design/0026-echo-hosting-hardening-first-twenty.md
  • docs/design/structural-history-graphql-authority.md
  • docs/jedit-echo-end-to-end.md
  • docs/releases/v0.1.0/final-witness-report.json
  • docs/releases/v0.1.0/quickstart.md
  • docs/stack-map.md
  • scripts/jedit-echo-powered-session.mjs
  • spec/echo-hosting-counter-template.spec.mjs
  • spec/echo-powered-session-witness-cli.spec.mjs
  • spec/installed-jedit-contract-echo-transport.spec.mjs
  • spec/interactive-echo-text-session.spec.mjs
  • spec/jedit-contract-mutation-handlers.spec.mjs
  • spec/jedit-echo-retention-lookup.spec.mjs
  • spec/jedit-echo-witness-mcp-adapter.spec.mjs
  • spec/jedit-optic-client.spec.mjs
  • spec/jedit-receipt-correlation.spec.mjs
  • spec/jedit-retained-evidence.spec.mjs
  • spec/jedit-runtime-handler-invocation.spec.mjs
  • spec/jedit-runtime-work-envelope.spec.mjs
  • spec/main-runtime-order.spec.mjs
  • spec/trusted-echo-runtime-loop.spec.mjs
  • spec/workspace-runtime.spec.mjs
  • src/adapters/echo-backed-text-buffer-session.ts
  • src/adapters/installed-jedit-contract-echo-transport.ts
  • src/adapters/interactive-echo-text-session.ts
  • src/adapters/jedit-echo-contract-package-installer.ts
  • src/adapters/jedit-echo-witness-mcp-adapter.ts
  • src/adapters/workspace-app.ts
  • src/app/echo-hosting-counter-template.ts
  • src/app/echo-powered-text-buffer-witness.ts
  • src/app/jedit-contract-mutation-handlers.ts
  • src/app/jedit-contract-package-preflight.ts
  • src/app/jedit-contract-package.ts
  • src/app/jedit-echo-retention-lookup.ts
  • src/app/jedit-local-replay-proof.ts
  • src/app/jedit-observer-runtime.ts
  • src/app/jedit-restart-posture.ts
  • src/app/jedit-restart-witness.ts
  • src/app/jedit-retained-evidence.ts
  • src/app/jedit-runtime-handler-invocation.ts
  • src/app/jedit-ticketed-work-boundary.ts
  • src/app/text-buffer-session.ts
  • src/app/trusted-echo-runtime-loop.ts
  • src/ports/echo-runtime-lifecycle.ts
  • src/ports/jedit-echo-agent-witness.ts
  • src/ports/jedit-optic-client.ts
  • src/ports/jedit-restart-posture.ts
  • src/ports/jedit-restart-witness.ts
  • src/ports/jedit-retained-evidence.ts
  • src/ports/jedit-ticketed-work-boundary.ts
  • src/ports/text-buffer-session.ts

Walkthrough

Adds a full release-gate: trusted Echo lifecycle port and adapter, installed-contract transport and package installer/preflight, jedit mutation handlers and query observers, in-memory hosting boundaries (ledger/state/ticketing/retention), echo-powered TextBufferOptic session and witness orchestration, CLI witness and release-gate scripts, extensive tests, and documentation and release artifacts.

Changes

Release Gate: Lifecycle, Contracts, Transport, Witnesses

Layer / File(s) Summary
Trusted lifecycle port and adapter
src/ports/echo-runtime-lifecycle.ts, src/adapters/echo-runtime-lifecycle.ts, src/app/trusted-echo-runtime-loop.ts, src/app/trusted-echo-runtime-host.ts, spec/echo-runtime-lifecycle.spec.mjs, spec/trusted-echo-runtime-loop.spec.mjs
Adds lifecycle request/response contracts and codec, adapter that dispatches trusted control bytes to the host, a loop abstraction (start/drain/stop/status), a host stop helper that enforces appCanTick: false, and tests ensuring no app-facing tick authority.
Contract package descriptor & preflight
src/app/jedit-contract-package.ts, src/app/jedit-contract-package-preflight.ts, spec/jedit-contract-package.spec.mjs, spec/jedit-contract-package-preflight.spec.mjs
Typed jedit hot-text package descriptor, observer plan id derivation, and preflight validator that reports READY/BLOCKED and classifies operation support.
Package installer & host port types
src/ports/echo-contract-package-host.ts, src/adapters/jedit-echo-contract-package-installer.ts, spec/jedit-contract-package-install.spec.mjs
Echo contract package host request/result types and installer adapter that gates installs via preflight and records/validates host interactions.
Installed-contract echo transport
src/adapters/installed-jedit-contract-echo-transport.ts, spec/installed-jedit-contract-echo-transport.spec.mjs
Transport implementing kernel submit/observe by routing to installed jedit registries, staging runtime work envelopes, ticketed-work gating, and mapping obstructed responses to typed failures.
Mutation handlers registry
src/app/jedit-contract-mutation-handlers.ts, spec/jedit-contract-mutation-handlers.spec.mjs
Typed registry for create/replace/checkpoint mutation handlers, optional state publication, and execution gated to scheduler authority.
Query observer registry
src/app/jedit-contract-query-observers.ts, spec/jedit-contract-query-observers.spec.mjs
Typed observers for worldline snapshot and textWindow that optionally require contract-state basis; dispatcher enforces read-only authority.
Intent outcome ledger
src/ports/jedit-intent-outcomes.ts, src/app/jedit-intent-outcomes.ts, spec/jedit-intent-outcomes.spec.mjs
In-memory intent outcome ledger (accept/apply/reject/obstruct/observe) with handle factories and tests.
Retained evidence model & lookup
src/ports/jedit-retained-evidence.ts, src/app/jedit-retained-evidence.ts, src/ports/jedit-echo-retention-lookup.ts, src/app/jedit-echo-retention-lookup.ts, spec/jedit-retained-evidence.spec.mjs, spec/jedit-echo-retention-lookup.spec.mjs
Data model for retained refs/inventories and an in-memory Echo retention lookup doing semantic-coordinate + byte-hash matching with typed missing-material obstruction.
Submission ledger & ticketed ingress/work
src/ports/jedit-submission-ledger.ts, src/app/jedit-submission-ledger.ts, src/ports/jedit-ticketed-runtime-ingress.ts, src/app/jedit-ticketed-runtime-ingress.ts, src/ports/jedit-ticketed-work-boundary.ts, src/app/jedit-ticketed-work-boundary.ts, spec/jedit-submission-ledger.spec.mjs, spec/jedit-ticketed-runtime-ingress.spec.mjs, spec/jedit-ticketed-work-boundary.spec.mjs
In-memory submission ledger with deterministic submissionId, ticket issuance, ticketed ingress helpers, and tests for accepted/duplicate/missing behaviors.
Entity-fact model & state port
src/ports/jedit-contract-entity-facts.ts, src/app/jedit-contract-entity-facts.ts, src/ports/jedit-contract-state-port.ts, src/app/jedit-contract-state-port.ts, spec/jedit-contract-entity-facts.spec.mjs, spec/jedit-contract-state-port.spec.mjs
Contract entity-fact types and converter from session to fact set; in-memory contract state port with publish/read/require helpers and tests for read/write/missing.
Echo-powered TextBuffer session & witness
src/app/echo-powered-text-buffer-optic-session.ts, src/app/echo-powered-text-buffer-witness.ts, src/ports/echo-powered-text-buffer-witness.ts, spec/jedit-optic-client.spec.mjs, spec/echo-powered-session-witness-cli.spec.mjs
Composes an app-safe OpticSession with lifecycle adapter, witness orchestration to apply replace-range, record outcomes, observe window, produce structured JSON; CLI supports dry-run, replay-local, unsupported-mutation.
Trusted runtime loop & host stop helper
src/app/trusted-echo-runtime-loop.ts, src/app/trusted-echo-runtime-host.ts, spec/trusted-echo-runtime-loop.spec.mjs
Loop abstraction delegating to lifecycle port and stopTrustedEchoRuntime helper enforcing appCanTick: false; tests for lifecycle transitions and recorded requests.
Echo witness MCP adapter & agent witness port
src/ports/jedit-echo-agent-witness.ts, src/adapters/jedit-echo-witness-mcp-adapter.ts, spec/jedit-echo-witness-mcp-adapter.spec.mjs
Typed agent witness port (dryRun/run) and MCP adapter forwarding to witness port without leaking lifecycle authority.
CLI scripts & release-gate
scripts/jedit-echo-powered-session.mjs, scripts/jedit-echo-release-gate.mjs, package.json, spec/release-gate-script.spec.mjs, spec/release-quickstart.spec.mjs
New CLI to run echo-powered session witness (JSON output, replay-local), release-gate script validating metadata and running focused tests/quality, and package.json script.
Interactive session wiring & runtime mode
src/adapters/interactive-echo-text-session.ts, src/app/interactive-text-runtime-mode.ts, src/adapters/workspace-app.ts, src/app/workspace/init.ts, src/app/workspace/model.ts, spec/interactive-echo-text-session.spec.mjs
Adapter selecting echo-backed vs local sessions by runtime mode, runtime-mode parser, workspace wiring to propagate mode, and integration tests.
Design, docs, release artifacts
AGENTS.md, README.md, docs/BEARING.md, docs/design/*, docs/echo-application-hosting-guide.md, docs/releases/v0.1.0/*, CHANGELOG.md
Extensive documentation and release artifacts describing authority boundaries, BEARING plan, hosting pattern, quickstart, witness reports (JSON), and changelog entry.
Numerous tests added/updated
spec/*, tests/*
Broad test coverage added/updated across lifecycle, transport, registries, ledgers, replay proof, retention lookup, restart witness, and many end-to-end scenarios.

Sequence Diagram(s)

sequenceDiagram
  participant Client as EchoPoweredTextBufferOpticSession
  participant Lifecycle as TrustedEchoRuntimeLifecyclePort
  participant Host as EchoWasmKernelHostTransport
  Client->>Host: submitIntentBytes(intent)
  Client->>Lifecycle: requestRunUntilIdle(cycleLimit)
  Lifecycle->>Host: dispatchControlIntentBytes(run-until-idle)
  Host-->>Lifecycle: EchoRunUntilIdleResult
  Host-->>Client: observeBytes(readingEnvelope)
  Client-->>Lifecycle: requestStop()
  Lifecycle->>Host: dispatchControlIntentBytes(stop)
  Host-->>Lifecycle: EchoStopResult
Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

A gate, a host, a witness in the night,
Lifecycle whispers, contracts hold tight.
Tests march in rows, evidence in hand,
Slices checked off, release-songs grand.
Merge the gate — let Echo greet the land.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch stack/trusted-echo-runtime-lifecycle-port

@flyingrobots

Copy link
Copy Markdown
Owner Author

@codex spot check please: this PR wires jedit trusted Echo lifecycle control into the product-session path. Please focus on whether the authority split stays intact: app-facing TextBufferOptic should not expose tick/control authority, lifecycle requests should remain trusted-host-only, reads should not trigger lifecycle, and the agent witness should be honest about using the fake Echo-shaped transport while the opt-in real Echo WASM witness remains the substrate proof.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3f88070720

ℹ️ 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".

Comment thread src/app/echo-powered-text-buffer-optic-session.ts Outdated
Comment thread src/app/echo-powered-text-buffer-optic-session.ts Outdated
@flyingrobots

Copy link
Copy Markdown
Owner Author

@codex Boundary update pushed in f93ad1c.

Area Outcome Witness
jedit ownership TextBufferOptic, text windows, rope semantics, and text-domain docs remain jedit-owned, behind ports/adapters/contracts. spec/text-buffer-optic-contract-readiness.spec.mjs; docs/jedit-echo-end-to-end.md
Echo generic boundary The real Echo WASM witness now expects UNSUPPORTED_QUERY until a jedit-owned observer is installed; no hardcoded text materialization is assumed. spec/jedit-echo-wasm-stack-witness.spec.mjs
Stale doctrine cleanup Docs no longer claim Echo implements the rope/string manipulation or returns QueryBytes("hello") from a kernel fixture. docs/data-model.md; docs/stack-map.md; design notes

Companion Echo PR: flyingrobots/echo#377 removes the actual hardcoded Stack Witness text fixture from warp-wasm and cleans app-shaped fixture names out of warp-core tests.

Validation: npm run build && npm run quality; targeted Node test slice for Echo witness, CLI witness, contract readiness, and rope-worldline cycle.

@chatgpt-codex-connector

Copy link
Copy Markdown

To use Codex here, create an environment for this repo.

@flyingrobots

Copy link
Copy Markdown
Owner Author

@codex PR #27 review backlog pass completed.

Issue group Severity Outcome Commit(s) Regression / verification
Lifecycle start/stop validation and completion typing Major Invalid starts fail before lifecycle control; rejected stop preserves running state; completion values are constrained. 7f96b63 spec/trusted-echo-runtime-loop.spec.mjs; npm run release-gate:echo
CLI non-report summaries and build-order dependency Major Human output now handles dry-run, unsupported, replay-local, and fallback summaries; CLI spec builds deterministically. 7f96b63 spec/echo-powered-session-witness-cli.spec.mjs; npm run release-gate:echo
MCP dry-run boundary and interactive adapter injection Major MCP control flags stay adapter-local; interactive session factories are injectable; unknown modes fail fast; seeded runtime modes are preserved. 7f96b63 spec/jedit-echo-witness-mcp-adapter.spec.mjs, spec/interactive-echo-text-session.spec.mjs, spec/workspace-runtime.spec.mjs; npm run release-gate:echo
Runtime authority, ticketed work, replay, restart, retention, and package identity string drift Critical/Major Handler authority uses runtime authority objects; package identity uses structural equality; ticket ids and submission ids use structured deterministic material; retained lookup uses structured semantic-coordinate indexes; restart witness uses typed recovery routing. b3cab25, 0b54e67 spec/jedit-runtime-handler-invocation.spec.mjs, spec/installed-jedit-contract-echo-transport.spec.mjs, spec/jedit-local-replay-proof.spec.mjs, spec/jedit-restart-witness.spec.mjs, spec/jedit-ticketed-work-boundary.spec.mjs, spec/jedit-echo-retention-lookup.spec.mjs; npm run release-gate:echo
Retained evidence shape Major/Nit Protocol strings are centralized; retained refs are discriminated by posture so present-inline refs require byte identity and missing refs do not carry it. da51c14 spec/jedit-retained-evidence.spec.mjs, spec/jedit-echo-retention-lookup.spec.mjs; npm run release-gate:echo
Counter template state leak Major In-memory counter state port now copies state on read/write boundaries. b3cab25 spec/echo-hosting-counter-template.spec.mjs; npm run release-gate:echo
Observer plan literals and hash rationale Major/Nit Text-window observer plan literals are consolidated into a single runtime spec object with documented digest truncation rationale. 71e936a spec/jedit-contract-query-observers.spec.mjs, spec/installed-jedit-contract-echo-transport.spec.mjs; npm run release-gate:echo
Docs, quickstart, markdown numbering, release witness, and test precision Minor/Nit BEARING numbering is markdownlint-friendly; end-to-end wording and final item numbering are corrected; release witness JSON refreshed; brittle retained-evidence and runtime-order tests are tightened. da51c14 spec/release-quickstart.spec.mjs, spec/main-runtime-order.spec.mjs, git diff --check; npm run release-gate:echo

False-positive / stale reviewer note handled: the quickstart comment claiming the shipped witness uses report.retainedEvidenceRoles is stale. Current shipped and tested shape is report.retainedEvidence.refs, verified by docs/releases/v0.1.0/final-witness-report.json and spec/echo-powered-session-witness-cli.spec.mjs.

Final local gate on pushed head 0b54e67:

npm run release-gate:echo
92 tests passed; quality gate passed; no regressions.

@chatgpt-codex-connector

Copy link
Copy Markdown

To use Codex here, create an environment for this repo.

@flyingrobots
flyingrobots merged commit b7fa3cb into main May 24, 2026
2 checks passed
@flyingrobots
flyingrobots deleted the stack/trusted-echo-runtime-lifecycle-port branch May 24, 2026 16:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant