feat(api): establish the v19 Runtime and Lane surface - #769
Conversation
|
Warning Review limit reached
Next review available in: 4 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (10)
📝 WalkthroughWalkthroughThis PR replaces the v19 Warp/Timeline/Reading facade with a Runtime/Lane/Observer/Observation model. It adds domain contracts (Lane, Observer, Observation, ObservationReceipt, ObservedReading), a Runtime composition root backed by GitStorage/RuntimeActivity/RuntimeLaneAdapter, updates public exports, diagnostics, gate scripts, tests, fixtures, and documentation accordingly. ChangesRuntime/Lane/Observation v19 API
Estimated code review effort: 4 (Complex) | ~75 minutes Sequence Diagram(s)sequenceDiagram
participant Consumer
participant Runtime
participant Lane
participant Observer
participant Observation
Consumer->>Runtime: Runtime.open({ at, writer })
Runtime->>Runtime: GitStorage.open + openWarp
Consumer->>Runtime: runtime.lane(name)
Runtime->>Lane: createWorldlineLane
Consumer->>Lane: lane.write(intent)
Lane-->>Consumer: WriteReceipt
Consumer->>Lane: lane.observe(observer)
Lane->>Observation: construct dormant execution
Consumer->>Observation: iterate readings / one()
Observation-->>Consumer: Reading values + ObservationReceipt
Consumer->>Runtime: runtime.close()
Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3 | ❌ 2❌ Failed checks (2 warnings)
✅ Passed checks (3 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Release Preflight
If this PR is from a |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
test/integration/application/GitStorage.integration.test.ts (1)
1-47: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueFile name no longer matches its content.
The suite now targets
Runtimecomposition end-to-end ("Runtime public composition", Line 7) rather thanGitStoragein isolation, but the file is still namedGitStorage.integration.test.ts. Consider renaming toRuntime.integration.test.tsfor discoverability.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@test/integration/application/GitStorage.integration.test.ts` around lines 1 - 47, Rename the integration test file from GitStorage.integration.test.ts to Runtime.integration.test.ts so its filename matches the Runtime public composition suite defined by describe('Runtime public composition').
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/topics/querying.md`:
- Around line 114-115: Rewrite the querying guide’s examples and instructions to
use the v19 Runtime/Lane API: replace removed openWarp, reading.*,
timeline.read(), and explicit storage-lifecycle usage with Runtime.open(),
runtime.lane(), generated observers, Lane.observe(), Observation.receipt, and
runtime.close().
In `@src/application/Runtime.ts`:
- Around line 53-59: Update Runtime.lane to use a dedicated lane-identity
failure descriptor instead of OPEN_WARP_IDENTITY_FAILURE when calling
assertTimelineNameIdentity. Define or reuse the lane-specific descriptor so
runtime.lane('') reports the lane validation contract and error metadata without
changing the existing timeline execution flow.
In `@src/application/RuntimeLaneAdapter.ts`:
- Around line 71-90: Extract the shared accepted-receipt evidence validation
from readingFrom and completedObservationReceipt into a requireEvidence(receipt)
helper. Have both functions call this helper and reuse its existing
E_OBSERVATION_EVIDENCE_INVARIANT WarpError behavior, removing their duplicated
undefined checks.
In `@src/domain/api/LaneTick.ts`:
- Around line 1-7: Replace the exported Tick shape in LaneTick with a frozen
class that validates both id and lane in its constructor, exposes them as
readonly properties, and freezes each instance after validation. Update any
boundary checks using Tick to require instanceof Tick rather than structural or
shape-based validation, while preserving the existing default export contract.
In `@src/domain/api/ObservedReading.ts`:
- Around line 44-55: Update the constructor logic in ObservedReading to snapshot
options.value after isReadingValue validation, recursively copying mutable
arrays and plain objects and copying Uint8Array data into an immutable
representation. Assign the materialized snapshot to this.value so later caller
mutations cannot affect the Reading while preserving the validated value shape.
---
Outside diff comments:
In `@test/integration/application/GitStorage.integration.test.ts`:
- Around line 1-47: Rename the integration test file from
GitStorage.integration.test.ts to Runtime.integration.test.ts so its filename
matches the Runtime public composition suite defined by describe('Runtime public
composition').
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: f2428e56-1cf5-4eca-96ad-a1894df1430e
📒 Files selected for processing (51)
README.mdadvanced.tsdiagnostics.tsdocs/migrations/v19/README.mddocs/topics/api/README.mddocs/topics/querying.mddocs/topics/reference.mdindex.tsscripts/check-source-backed-reference.tsscripts/v19-root-declaration-gate.tssrc/application/GitStorage.tssrc/application/Runtime.tssrc/application/RuntimeActivity.tssrc/application/RuntimeLaneAdapter.tssrc/domain/api/Lane.tssrc/domain/api/LaneRuntime.tssrc/domain/api/LaneTick.tssrc/domain/api/Observation.tssrc/domain/api/ObservationReceipt.tssrc/domain/api/ObservedReading.tssrc/domain/api/Observer.tssrc/domain/api/ObserverRuntime.tssrc/domain/api/PublicReceipt.tssrc/domain/api/ReadingResult.tssrc/domain/api/ReadingValue.tssrc/domain/api/ReadingValueRuntime.tssrc/domain/api/WriteReceipt.tssrc/domain/api/WriteRuntime.tssrc/domain/api/captureCoordinate.tssrc/infrastructure/adapters/GitPlumbingRuntimeAdapter.tsstorage.tstest/conformance/v18FirstUseOpticsHonesty.test.tstest/integration/application/GitStorage.integration.test.tstest/type-check/generated-users.tstest/type-check/v19-consumer.tstest/type-check/v19-first-use.tstest/type-check/v19-subpaths.tstest/unit/application/GitStorage.test.tstest/unit/application/Runtime.test.tstest/unit/application/RuntimeActivity.test.tstest/unit/application/RuntimeLaneAdapter.test.tstest/unit/application/WarpStorageRegistry.test.tstest/unit/domain/Lane.test.tstest/unit/domain/Observation.test.tstest/unit/domain/ObservedReading.test.tstest/unit/domain/ReceiptDiagnostics.test.tstest/unit/domain/ReceiptOutcome.test.tstest/unit/domain/WarpFacade.test.tstest/unit/scripts/v19-public-api-boundary.test.tstest/unit/scripts/v19-root-declaration-gate.test.tsvitest.config.ts
📜 Review details
⏰ Context from checks skipped due to timeout. (3)
- GitHub Check: test-node (22)
- GitHub Check: coverage-threshold
- GitHub Check: preflight
🧰 Additional context used
📓 Path-based instructions (4)
src/**/*.{ts,tsx,js,jsx}
📄 CodeRabbit inference engine (AGENTS.md)
src/**/*.{ts,tsx,js,jsx}: Do not introduceany,as any,as unknown as,unknown(outside adapters),Record<string, unknown>(outside adapters),*Likeplaceholder types,JSON.parse/JSON.stringify(outside adapters),fetch(outside adapters),process.env(outside adapters),@ts-ignore, orz.any()in core code; use validated boundary models and ports instead.
Use constructor-injected ports for external capabilities; do not rely on ambient dependencies for I/O, clocks, persistence, or entropy.
Do not createutils.ts,helpers.ts,misc.ts, orcommon.ts; name files after the actual concept they model.
Prefer one file per class, type, or object; if a file accumulates peer concepts, split it.
Keep helper corridors, fake shape trust, transitional duplication, and compile-time theater out of the codebase; runtime-honest TypeScript must reflect actual behavior.
No enum usage; prefer runtime-backed domain forms and unions.
Do not use boolean trap parameters; prefer named option objects or separate methods.
Avoid magic strings or numbers when a named constant should exist.
Keep domain bytes asUint8Array;Bufferbelongs in infrastructure adapters.
Files:
src/domain/api/PublicReceipt.tssrc/domain/api/LaneTick.tssrc/domain/api/ReadingValue.tssrc/domain/api/captureCoordinate.tssrc/domain/api/WriteRuntime.tssrc/domain/api/LaneRuntime.tssrc/domain/api/Observer.tssrc/domain/api/ObservedReading.tssrc/domain/api/ObserverRuntime.tssrc/domain/api/WriteReceipt.tssrc/application/RuntimeActivity.tssrc/domain/api/ObservationReceipt.tssrc/application/RuntimeLaneAdapter.tssrc/application/Runtime.tssrc/domain/api/ReadingValueRuntime.tssrc/application/GitStorage.tssrc/domain/api/Lane.tssrc/infrastructure/adapters/GitPlumbingRuntimeAdapter.tssrc/domain/api/Observation.tssrc/domain/api/ReadingResult.ts
src/domain/**/*.{ts,tsx,js,jsx}
📄 CodeRabbit inference engine (AGENTS.md)
src/domain/**/*.{ts,tsx,js,jsx}: Insrc/domain/**, do not useDate.now(),new Date(),Date(),performance.now(),Math.random(),crypto.randomUUID(),crypto.getRandomValues(),setTimeout,setInterval, rawnew Error(...)/new TypeError(...), or direct imports from Node built-ins; time, entropy, and external capabilities must enter through ports or parameters, and domain errors should extendWarpError.
Construct domain objects only in core when doing so establishes validated runtime truth; do not build infrastructure adapters, host APIs, persistence implementations, wall clocks, or entropy sources inside core.
Prefer discriminated unions and explicit result types instead of boolean-flag bags, and model expected failures as return values rather than exceptions.
src/domain/must not import host APIs or Node-specific globals; hexagonal architecture boundaries are mandatory.
Domain code must not use the wall clock directly; time must enter through a port or parameter.
Files:
src/domain/api/PublicReceipt.tssrc/domain/api/LaneTick.tssrc/domain/api/ReadingValue.tssrc/domain/api/captureCoordinate.tssrc/domain/api/WriteRuntime.tssrc/domain/api/LaneRuntime.tssrc/domain/api/Observer.tssrc/domain/api/ObservedReading.tssrc/domain/api/ObserverRuntime.tssrc/domain/api/WriteReceipt.tssrc/domain/api/ObservationReceipt.tssrc/domain/api/ReadingValueRuntime.tssrc/domain/api/Lane.tssrc/domain/api/Observation.tssrc/domain/api/ReadingResult.ts
src/domain/**/!(*.test).{ts,tsx,js,jsx}
📄 CodeRabbit inference engine (AGENTS.md)
Use explicit domain concepts with validated constructors,
Object.freeze, andinstanceofdispatch; domain objects should be runtime-backed nouns, not ad hoc shape bags.
Files:
src/domain/api/PublicReceipt.tssrc/domain/api/LaneTick.tssrc/domain/api/ReadingValue.tssrc/domain/api/captureCoordinate.tssrc/domain/api/WriteRuntime.tssrc/domain/api/LaneRuntime.tssrc/domain/api/Observer.tssrc/domain/api/ObservedReading.tssrc/domain/api/ObserverRuntime.tssrc/domain/api/WriteReceipt.tssrc/domain/api/ObservationReceipt.tssrc/domain/api/ReadingValueRuntime.tssrc/domain/api/Lane.tssrc/domain/api/Observation.tssrc/domain/api/ReadingResult.ts
**/*.{ts,tsx,js,jsx}
📄 CodeRabbit inference engine (AGENTS.md)
**/*.{ts,tsx,js,jsx}: Do not use direct imports fromsrc/infrastructure/**insrc/domain/**orsrc/ports/**; depend on a port instead.
Do not use direct Node built-ins insrc/domain/**orsrc/ports/**; use a port instead.
Files:
src/domain/api/PublicReceipt.tssrc/domain/api/LaneTick.tstest/unit/application/WarpStorageRegistry.test.tstest/unit/application/RuntimeLaneAdapter.test.tsvitest.config.tstest/unit/application/RuntimeActivity.test.tstest/conformance/v18FirstUseOpticsHonesty.test.tsadvanced.tssrc/domain/api/ReadingValue.tstest/unit/scripts/v19-root-declaration-gate.test.tstest/type-check/generated-users.tstest/unit/domain/ReceiptOutcome.test.tssrc/domain/api/captureCoordinate.tsstorage.tstest/type-check/v19-first-use.tstest/unit/application/Runtime.test.tstest/unit/domain/ObservedReading.test.tssrc/domain/api/WriteRuntime.tsscripts/check-source-backed-reference.tstest/type-check/v19-subpaths.tssrc/domain/api/LaneRuntime.tssrc/domain/api/Observer.tssrc/domain/api/ObservedReading.tssrc/domain/api/ObserverRuntime.tstest/unit/domain/Lane.test.tstest/integration/application/GitStorage.integration.test.tstest/unit/domain/ReceiptDiagnostics.test.tsscripts/v19-root-declaration-gate.tstest/type-check/v19-consumer.tssrc/domain/api/WriteReceipt.tstest/unit/application/GitStorage.test.tsdiagnostics.tssrc/application/RuntimeActivity.tssrc/domain/api/ObservationReceipt.tssrc/application/RuntimeLaneAdapter.tssrc/application/Runtime.tstest/unit/scripts/v19-public-api-boundary.test.tssrc/domain/api/ReadingValueRuntime.tsindex.tssrc/application/GitStorage.tstest/unit/domain/Observation.test.tssrc/domain/api/Lane.tssrc/infrastructure/adapters/GitPlumbingRuntimeAdapter.tssrc/domain/api/Observation.tstest/unit/domain/WarpFacade.test.tssrc/domain/api/ReadingResult.ts
🔇 Additional comments (47)
index.ts (1)
6-40: LGTM!test/type-check/generated-users.ts (1)
1-29: LGTM!test/type-check/v19-consumer.ts (1)
1-39: LGTM!Also applies to: 56-86
test/type-check/v19-first-use.ts (1)
1-23: LGTM!README.md (1)
40-40: LGTM!Also applies to: 56-100, 109-121, 144-145, 292-296
docs/migrations/v19/README.md (1)
1-310: LGTM!docs/topics/api/README.md (1)
6-9: LGTM!Also applies to: 248-253, 333-335
docs/topics/reference.md (1)
25-83: LGTM!diagnostics.ts (1)
29-32: LGTM!Also applies to: 51-60
advanced.ts (1)
4-4: LGTM!test/type-check/v19-subpaths.ts (1)
9-9: LGTM!Also applies to: 21-42
scripts/check-source-backed-reference.ts (1)
182-187: LGTM!Also applies to: 265-267
scripts/v19-root-declaration-gate.ts (1)
22-28: LGTM!Also applies to: 57-60
test/unit/scripts/v19-public-api-boundary.test.ts (1)
7-34: LGTM!Also applies to: 175-175, 243-248
test/unit/scripts/v19-root-declaration-gate.test.ts (1)
73-94: LGTM!vitest.config.ts (1)
33-33: LGTM!src/domain/api/Lane.ts (1)
1-173: LGTM!src/domain/api/LaneRuntime.ts (1)
1-29: LGTM!src/domain/api/PublicReceipt.ts (1)
1-5: LGTM!src/domain/api/ReadingResult.ts (1)
3-6: LGTM!src/domain/api/ReadingValue.ts (1)
1-3: LGTM!src/domain/api/ReadingValueRuntime.ts (1)
1-87: LGTM!src/domain/api/WriteReceipt.ts (1)
11-11: LGTM!Also applies to: 28-35, 48-48
src/domain/api/WriteRuntime.ts (1)
126-126: LGTM!Also applies to: 171-171
src/domain/api/captureCoordinate.ts (1)
2-9: LGTM!src/domain/api/Observer.ts (1)
1-48: LGTM!src/domain/api/ObserverRuntime.ts (1)
1-41: LGTM!src/domain/api/Observation.ts (1)
1-211: LGTM!src/domain/api/ObservationReceipt.ts (1)
1-116: LGTM!test/unit/domain/Lane.test.ts (1)
1-219: LGTM!test/unit/domain/Observation.test.ts (1)
1-302: LGTM!test/unit/domain/ObservedReading.test.ts (1)
1-50: LGTM!test/unit/domain/ReceiptDiagnostics.test.ts (1)
58-58: LGTM!Also applies to: 161-161, 180-180
test/unit/domain/ReceiptOutcome.test.ts (1)
102-102: LGTM!Also applies to: 120-120, 152-152
test/unit/domain/WarpFacade.test.ts (1)
5-7: LGTM!Also applies to: 22-42, 308-308, 453-455
test/conformance/v18FirstUseOpticsHonesty.test.ts (1)
6-7: LGTM!src/application/Runtime.ts (1)
1-52: LGTM!Also applies to: 61-79
src/application/RuntimeActivity.ts (1)
1-48: LGTM!src/application/RuntimeLaneAdapter.ts (1)
1-70: LGTM!Also applies to: 92-114, 135-153
storage.ts (1)
1-5: LGTM!test/unit/application/GitStorage.test.ts (1)
1-177: LGTM!test/unit/application/Runtime.test.ts (1)
1-113: LGTM!test/unit/application/RuntimeActivity.test.ts (1)
1-29: LGTM!test/unit/application/RuntimeLaneAdapter.test.ts (1)
1-135: LGTM!test/unit/application/WarpStorageRegistry.test.ts (1)
3-3: LGTM!src/infrastructure/adapters/GitPlumbingRuntimeAdapter.ts (1)
3-3: 🗄️ Data Integrity & IntegrationNo change needed for
GitPlumbingimports.GitPlumbingTimeHistoryAdapter.tsre-exportsGitPlumbingfrom./gitErrorClassification.ts, soGitStorage.tsandGitPlumbingRuntimeAdapter.tsboth resolve to the same type source.src/application/GitStorage.ts (1)
24-48: 🩺 Stability & AvailabilityConfirm
plumbingdisposal semantics with the vendored package.
plumbingis created once and passed into both history and CAS; the local adapters only callhistory.close(), the CAS close returned byContentAddressableStore.createCbor(), and materialization closes. If@git-stunts/plumbing3.2.0 exposesclose()/Symbol.asyncDisposeor owns file/lock handles that must be released, add an explicit disposal point for it.
Release Preflight
If this PR is from a |
1 participant
Summary
Runtimethe production composition root and sole root runtime valueLane,Observer,Observation,Reading, and Receipt runtime nounsunknownbeyond the adapter boundaryValidation
npm run lintnpm run lint:ratchetnpm run lint:sludgenpm run lint:quarantine-graduatenpm run lint:semgrepnpm run lint:contaminationnpm run lint:mdnpm run lint:md:codenpm run lint:linksnpm run lint:docs-topologynpm run typechecknpm run typecheck:policynpm run typecheck:consumernpm run typecheck:surface— 0 errors, 0 warningsnpm run buildnpm run test:local— 7,150 passed, 2 skippednpm run test:coverage— 7,310 passed, 2 skipped; 92.93% linesnpx vitest run test/integration/application/GitStorage.integration.test.ts— 2 passednpm pack --dry-run --ignore-scripts --json— 2,067 filesManual SSJS scorecard
Advances #712