Skip to content

feat(runtime): add lifecycle execution kernel - #31

Merged
Punisheroot merged 1 commit into
mainfrom
feat/js/lifecycle-execution-kernel
Aug 4, 2026
Merged

feat(runtime): add lifecycle execution kernel#31
Punisheroot merged 1 commit into
mainfrom
feat/js/lifecycle-execution-kernel

Conversation

@Punisheroot

Copy link
Copy Markdown
Contributor

Summary

Closes #21.

Adds the runtime-owned lifecycle execution kernel that replays the current lifecycle, invokes exactly one injected adapter for the active phase, and commits typed transitions through the existing parent-owned digest-CAS boundary.

Successful execution stops at apply/awaiting_approval without approving or mutating the active worktree.

Implementation

  • Adds bounded, versioned adapter request and outcome contracts for explore, implement, test, review, and verify.
  • Binds every invocation to the lifecycle identity, expected state digest, frozen phase profile, remaining aggregate budget, immutable change context, and a deterministic invocation ID.
  • Validates phase, profile, worker depth, logical spawn count, usage, cleanup, failure details, and serialized payload bounds before committing.
  • Keeps lifecycle transitions parent-owned through RuntimeStore::parent_transition_lifecycle.
  • Uses the existing transactional change/lifecycle operation to consume the single repair reservation.
  • Checks cancellation before adapter execution, after execution, and before consuming a reserved repair.
  • Returns fail-closed outcomes for invalid output, exhausted budgets, cancellation, adapter failure, cleanup failure, corruption, and stale CAS.
  • Adds immutable change-context loading with request-digest verification.
  • Requires concrete adapters to deduplicate external side effects by deterministic invocation ID so an uncommitted attempt can be retried safely.
  • Adds deterministic provider-free fake-adapter tests covering success, rejection, repair, phase/profile mismatch, cancellation, budget exhaustion, failures, stale CAS, corruption, and restart behavior.

No lifecycle semantics, role-profile semantics, test-plan semantics, storage schema, apply behavior, or provider integration were changed.

Validation

cargo test --locked -p needle-core lifecycle
10 passed; 59 filtered out

cargo test --locked -p needle-runtime
131 passed across 2 suites

cargo test --locked -p needle-runtime lifecycle_executor
12 passed; 119 filtered out

cargo clippy --locked -p needle-runtime --all-targets -- -D warnings
No issues found

git diff --check
Clean

Provider processes, live smoke tests, and benchmarks were not run because this kernel is provider-free and makes no end-to-end performance claim.

Risks/limitations

  • Concrete RuntimeEngine, Codex patcher, test, reviewer, verifier, and apply adapters remain outside this change.
  • HTTP/UI integration, credentials, provider execution, and active-worktree mutation remain unwired.
  • The kernel supplies deterministic invocation identities, but each future concrete adapter must honor the documented idempotency contract for its own external side effects.
  • Adapter execution is intentionally bounded to one synchronous phase invocation per step; process supervision belongs to the dependent integration work.
  • Validation is deterministic and offline, so no provider-backed behavior is claimed.

Documentation/evidence

Updated:

  • PROJECT_STATUS.md
  • docs/ARCHITECTURE.md
  • docs/ROADMAP.md
  • docs/VERIFIED_CHANGES.md

Evidence consists of the lifecycle-domain tests, the complete needle-runtime suite, the SQLite immutable-context test, and provider-free adversarial fake-adapter coverage.

AI assistance and human verification

AI assistance: investigation, code, tests, and documentation — mapped the existing lifecycle and store boundaries, implemented the injected-adapter kernel, built deterministic adversarial coverage, and aligned the architecture/status documentation with the resulting behavior.
Human verification: The complete diff was manually reviewed end to end. Each execution disposition, digest-CAS path, repair transition, cancellation boundary, budget check, adapter contract, and restart behavior was traced against issue #21. The staged file set was checked for unrelated edits, credentials, generated files, and live artifacts, and all reported validation results were verified.

Ownership checklist

  • I read and understand the complete diff and can explain every material change.
  • I personally verified the reported tests and technical or performance claims.
  • I finalized and personally published the commits and this pull request.
  • I checked for unrelated edits, credentials, generated files, and live artifacts.
  • Public documentation and PROJECT_STATUS.md are updated when applicable.

@Punisheroot
Punisheroot requested a review from JJordan0C August 4, 2026 18:06
@Punisheroot
Punisheroot merged commit 5838229 into main Aug 4, 2026
15 checks passed
@Punisheroot
Punisheroot deleted the feat/js/lifecycle-execution-kernel branch August 4, 2026 19:53
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.

Add the parent-owned lifecycle execution kernel with injected phase adapters

2 participants