Enforce the v19 public API contract#733
Conversation
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (1)
📜 Recent review details⏰ Context from checks skipped due to timeout. (3)
🧰 Additional context used📓 Path-based instructions (4)src/**/*.{ts,tsx,js,jsx}📄 CodeRabbit inference engine (AGENTS.md)
Files:
src/domain/**/*.{ts,tsx,js,jsx}📄 CodeRabbit inference engine (AGENTS.md)
Files:
src/domain/**/!(*.test).{ts,tsx,js,jsx}📄 CodeRabbit inference engine (AGENTS.md)
Files:
**/*.{ts,tsx,js,jsx}📄 CodeRabbit inference engine (AGENTS.md)
Files:
🔇 Additional comments (1)
📝 WalkthroughSummary by CodeRabbit
WalkthroughThis PR establishes the v19 application-oriented API boundary, removes graph-first package entrypoints, adds intent/reading/receipt and tick-based timeline flows, introduces bounded neighborhood pagination, and updates storage, diagnostics, documentation, tooling, and tests. Changesv19 public API boundary
Timeline and receipt runtime
Bounded neighborhood reads
Estimated code review effort: 5 (Critical) | ~120 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches📝 Generate docstrings
Comment |
# Conflicts: # CHANGELOG.md # docs/topics/reference.md # index.ts # test/unit/domain/WarpFacade.test.ts
# Conflicts: # docs/topics/reference.md # legacy.ts # vitest.config.ts
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: 12
🤖 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/getting-started.md`:
- Around line 139-140: Update the getting-started example around
audit.previewJoin and audit.join to call join only when preview.receipt.outcome
indicates acceptance, following the accepted-only branching pattern in the API
README; leave obstructed or conflicted previews without proceeding to join.
In `@docs/topics/querying.md`:
- Around line 88-91: In the unsupported-query list, remove the duplicated
“arbitrary traversal” entry while preserving the remaining entries and guidance
in the surrounding documentation.
In `@README.md`:
- Around line 266-272: Revise the causal-cone paragraph near the definition of
D(v) to remove the claim that well-foundedness alone makes D(v) finite. State
instead that finiteness follows from the runtime’s finite-support or optic-basis
guarantees, and connect that guarantee to why bounded reads can avoid
materializing H \setminus D(v).
In `@src/domain/api/TickRuntime.ts`:
- Around line 19-24: Update requireTickCoordinate to validate that the tick’s
coordinate belongs to the exact runtime instance that created it, not merely a
matching worldlineName. Use the coordinate metadata or runtime binding
established when tickCoordinates entries are created, and preserve the existing
E_TIMELINE_TICK_MISMATCH error for foreign-runtime ticks.
In `@src/domain/api/Timeline.ts`:
- Around line 112-117: Remove the public coordinate() method from the root
Timeline surface, including its WarpWorldlineCoordinate return path. Keep
captureCoordinate internal to Timeline and expose coordinate access only through
the advanced surface, preserving the documented separation between opaque tick
handles and coordinate evidence.
In `@src/domain/services/controllers/CheckpointController.ts`:
- Line 371: Update the checkpoint reference handling in
_hasCurrentCheckpointSchema so an existing ref with empty or non-checkpoint
content throws PersistenceError instead of returning false; reserve false for a
genuinely absent ref. Preserve the existing true result for valid current
checkpoint schemas and ensure _validateMigrationBoundary cannot succeed when a
malformed checkpoint ref is present.
In `@src/domain/services/optic/CheckpointTailWitnessLocator.ts`:
- Around line 199-224: Update the traversal flow around
_readWitnessedNeighborhoodPage and readNeighborhood so a single checkpoint basis
is loaded and reused for the entire traversal, rather than calling
_basisLoader.load() per frontier node. Also avoid repeating
_scanTailForNeighborhood() for each entry by reusing traversal-scoped tail data
or an equivalent cached result while preserving tail stability validation and
witnessed page construction.
In `@test/conformance/v18TraversalOpticReadBasis.test.ts`:
- Line 117: Move the inline regular expression used by the edgeCursor assertion
in the traversal conformance test to a module-level constant, then reuse that
static regex in the expect.stringMatching call. Preserve the existing pattern
and assertion behavior.
In `@test/conformance/v19BoundedNeighborhoodReading.test.ts`:
- Around line 177-183: Update readIdentityShardPaths to validate each shard’s
path before returning it: require the path to be a string and reject missing or
malformed values instead of coercing them with String(). Preserve the existing
checkpointIndexShards array validation and return only validated paths.
In `@test/unit/domain/services/optic/CheckpointShardFactReader.manifest.test.ts`:
- Around line 106-113: Strengthen the assertion in the manifest-page test around
the CheckpointShardFactReader result by replacing toMatchObject with strict
equality for the fields owned by this test, including the edge object. If
metadata is intentionally present, assert it separately without allowing
unrelated extra fields in the core contract.
In `@test/unit/scripts/v19-public-api-boundary.test.ts`:
- Around line 146-148: Update the sorted function to use spread syntax instead
of Array.from for converting values to an array, preserving the existing sorting
behavior.
- Around line 74-90: The export-scanning loop must record namespace re-exports
instead of skipping them. In the branch handling non-named export clauses,
detect ts.isNamespaceExport(statement.exportClause) and add the module specifier
text to starExports, while preserving the existing handling for other
unsupported export clauses.
🪄 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
Run ID: 1e5a23e0-f2f6-4b0b-b39d-c980e36f4729
📒 Files selected for processing (118)
CHANGELOG.mdREADME.mdadvanced.tsbin/cli/commands/optic.tsbrowser.tsdiagnostics.tsdocs/migrations/v19/README.mddocs/topics/api/README.mddocs/topics/getting-started.mddocs/topics/git-substrate.mddocs/topics/observers.mddocs/topics/optic-reads.mddocs/topics/querying.mddocs/topics/reference.mddocs/topics/strands.mddocs/topics/sync.mdeslint.config.tsexamples/README.mdexamples/bounded-reads.tsexamples/observers.tsexamples/optics.tsindex.tsjsr.jsonlegacy.tspackage.jsonrootCompatibility.tsscripts/check-source-backed-reference.tsscripts/direct-export-name.tsscripts/source-size-gate.tssrc/domain/api/DraftTimelineRuntime.tssrc/domain/api/Intent.tssrc/domain/api/IntentBuilders.tssrc/domain/api/IntentRuntime.tssrc/domain/api/JoinReceipt.tssrc/domain/api/ReadReceipt.tssrc/domain/api/Reading.tssrc/domain/api/ReadingBuilders.tssrc/domain/api/ReadingRuntime.tssrc/domain/api/Receipt.tssrc/domain/api/ReceiptOutcome.tssrc/domain/api/ReceiptSupport.tssrc/domain/api/Tick.tssrc/domain/api/TickRuntime.tssrc/domain/api/Timeline.tssrc/domain/api/TimelineRuntime.tssrc/domain/api/TimelineView.tssrc/domain/api/TimelineViewRuntime.tssrc/domain/api/WriteReceipt.tssrc/domain/api/WriteRuntime.tssrc/domain/api/openWarp.tssrc/domain/services/controllers/CheckpointController.tssrc/domain/services/optic/CheckpointNeighborhoodBitmapPager.tssrc/domain/services/optic/CheckpointNeighborhoodPageReader.tssrc/domain/services/optic/CheckpointShardFactReader.tssrc/domain/services/optic/CheckpointTailTraversalReader.tssrc/domain/services/optic/CheckpointTailWitnessLocator.tssrc/domain/services/optic/NeighborhoodPageCursor.tssrc/domain/utils/roaring.tssrc/infrastructure/adapters/GitGraphAdapter.tsstorage.tstest/conformance/btrProvenanceBoundary.test.tstest/conformance/btrSigningBytesOwnership.test.tstest/conformance/immutableSnapshotSurface.test.tstest/conformance/v18BoundedMemoryLargeGraphGate.test.tstest/conformance/v18CoordinateOpticPublicPath.test.tstest/conformance/v18FirstUseOpticsHonesty.test.tstest/conformance/v18NeighborhoodOpticReadBasis.test.tstest/conformance/v18TraversalOpticReadBasis.test.tstest/conformance/v19BoundedNeighborhoodReading.test.tstest/fixtures/mergeConflictCorpus.tstest/type-check/consumer.tstest/type-check/tsconfig.jsontest/type-check/v19-consumer.tstest/type-check/v19-first-use.tstest/type-check/v19-subpaths.tstest/unit/cli/optic.test.tstest/unit/domain/ReceiptDiagnostics.test.tstest/unit/domain/ReceiptOutcome.test.tstest/unit/domain/WarpApp.facade.test.tstest/unit/domain/WarpCore.apiSurface.test.tstest/unit/domain/WarpCore.effectPipeline.test.tstest/unit/domain/WarpCore.emit.test.tstest/unit/domain/WarpFacade.test.tstest/unit/domain/WarpGraph.public-sync.test.tstest/unit/domain/WarpGraph.strands.compare.test.tstest/unit/domain/WarpWorldline.test.tstest/unit/domain/continuum/GitWarpReceiptEnvelopeBoundary.test.tstest/unit/domain/diagnostics.exports.test.tstest/unit/domain/internalReadingSurface.behavior.test.tstest/unit/domain/legacy.exports.test.tstest/unit/domain/services/controllers/CheckpointController.test.tstest/unit/domain/services/merge/TtdMergeInspector.test.tstest/unit/domain/services/optic/CheckpointShardFactReader.manifest.test.tstest/unit/domain/services/optic/CheckpointTailTraversalReader.test.tstest/unit/domain/services/query/BoundedSupportRule.test.tstest/unit/domain/services/query/CausalIndexPlan.test.tstest/unit/domain/services/query/SupportFragmentPlan.test.tstest/unit/domain/strandAndRuntimeSeams.test.tstest/unit/domain/utils/roaring.test.tstest/unit/domain/worldlineExecutableExamples.test.tstest/unit/domain/worldlineReadExecutablePaths.test.tstest/unit/index.exports.test.tstest/unit/infrastructure/adapters/RoaringLoaderAdapter.test.tstest/unit/scripts/jsr-publish-root-graph-shape.test.tstest/unit/scripts/non-ts-tail-shape.test.tstest/unit/scripts/openwarpgraph-composition-root.test.tstest/unit/scripts/public-api-aperture-noun.test.tstest/unit/scripts/public-api-facade-split.test.tstest/unit/scripts/release-artifact-command.test.tstest/unit/scripts/root-export-line-budget.test.tstest/unit/scripts/source-size-inventory-command.test.tstest/unit/scripts/v18-package-surface-audit.test.tstest/unit/scripts/v19-public-api-boundary.test.tstest/unit/scripts/worldline-api-deprecation.test.tstest/unit/v7-guards.test.tstsconfig.publish.jsontsconfig.src.jsonvitest.config.ts
💤 Files with no reviewable changes (26)
- tsconfig.src.json
- tsconfig.publish.json
- test/unit/index.exports.test.ts
- examples/bounded-reads.ts
- test/unit/scripts/jsr-publish-root-graph-shape.test.ts
- examples/README.md
- examples/observers.ts
- test/unit/scripts/public-api-aperture-noun.test.ts
- test/unit/scripts/public-api-facade-split.test.ts
- docs/topics/optic-reads.md
- examples/optics.ts
- test/type-check/tsconfig.json
- test/unit/scripts/v18-package-surface-audit.test.ts
- browser.ts
- test/unit/scripts/worldline-api-deprecation.test.ts
- docs/topics/observers.md
- test/unit/domain/diagnostics.exports.test.ts
- test/unit/domain/legacy.exports.test.ts
- legacy.ts
- rootCompatibility.ts
- src/domain/api/IntentBuilders.ts
- test/type-check/consumer.ts
- test/unit/scripts/source-size-inventory-command.test.ts
- test/unit/scripts/root-export-line-budget.test.ts
- scripts/source-size-gate.ts
- eslint.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)
**/*.{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:
scripts/direct-export-name.tstest/unit/domain/WarpGraph.public-sync.test.tssrc/domain/api/Receipt.tssrc/domain/api/ReceiptSupport.tstest/unit/domain/WarpApp.facade.test.tstest/unit/domain/ReceiptOutcome.test.tsbin/cli/commands/optic.tstest/conformance/v18BoundedMemoryLargeGraphGate.test.tstest/unit/domain/WarpCore.apiSurface.test.tssrc/domain/api/WriteRuntime.tssrc/domain/api/TimelineViewRuntime.tssrc/domain/api/Tick.tssrc/domain/api/ReceiptOutcome.tssrc/infrastructure/adapters/GitGraphAdapter.tstest/fixtures/mergeConflictCorpus.tstest/unit/domain/services/optic/CheckpointShardFactReader.manifest.test.tsvitest.config.tstest/type-check/v19-first-use.tstest/unit/domain/ReceiptDiagnostics.test.tstest/unit/domain/utils/roaring.test.tssrc/domain/utils/roaring.tstest/unit/domain/services/merge/TtdMergeInspector.test.tstest/unit/domain/services/query/CausalIndexPlan.test.tstest/unit/domain/worldlineReadExecutablePaths.test.tssrc/domain/api/TickRuntime.tstest/unit/domain/continuum/GitWarpReceiptEnvelopeBoundary.test.tstest/type-check/v19-subpaths.tssrc/domain/api/TimelineView.tstest/unit/scripts/non-ts-tail-shape.test.tstest/unit/infrastructure/adapters/RoaringLoaderAdapter.test.tstest/conformance/v18NeighborhoodOpticReadBasis.test.tstest/unit/domain/services/query/BoundedSupportRule.test.tstest/unit/domain/WarpCore.effectPipeline.test.tstest/conformance/v18TraversalOpticReadBasis.test.tstest/unit/domain/services/query/SupportFragmentPlan.test.tstest/conformance/immutableSnapshotSurface.test.tstest/conformance/v19BoundedNeighborhoodReading.test.tsadvanced.tsdiagnostics.tssrc/domain/api/TimelineRuntime.tstest/unit/domain/services/optic/CheckpointTailTraversalReader.test.tssrc/domain/services/optic/NeighborhoodPageCursor.tssrc/domain/api/openWarp.tstest/unit/domain/services/controllers/CheckpointController.test.tstest/conformance/v18CoordinateOpticPublicPath.test.tssrc/domain/services/controllers/CheckpointController.tstest/conformance/btrProvenanceBoundary.test.tstest/unit/cli/optic.test.tssrc/domain/api/ReadingBuilders.tssrc/domain/services/optic/CheckpointNeighborhoodPageReader.tssrc/domain/api/Reading.tstest/conformance/v18FirstUseOpticsHonesty.test.tssrc/domain/api/IntentRuntime.tssrc/domain/api/ReadingRuntime.tstest/type-check/v19-consumer.tstest/unit/scripts/v19-public-api-boundary.test.tssrc/domain/api/JoinReceipt.tstest/unit/domain/internalReadingSurface.behavior.test.tstest/conformance/btrSigningBytesOwnership.test.tsscripts/check-source-backed-reference.tssrc/domain/services/optic/CheckpointTailTraversalReader.tsindex.tssrc/domain/api/WriteReceipt.tstest/unit/domain/WarpGraph.strands.compare.test.tssrc/domain/api/ReadReceipt.tstest/unit/scripts/release-artifact-command.test.tstest/unit/domain/strandAndRuntimeSeams.test.tssrc/domain/services/optic/CheckpointNeighborhoodBitmapPager.tsstorage.tstest/unit/v7-guards.test.tstest/unit/domain/worldlineExecutableExamples.test.tstest/unit/domain/WarpCore.emit.test.tssrc/domain/api/DraftTimelineRuntime.tstest/unit/domain/WarpWorldline.test.tssrc/domain/api/Timeline.tssrc/domain/services/optic/CheckpointTailWitnessLocator.tssrc/domain/api/Intent.tstest/unit/domain/WarpFacade.test.tstest/unit/scripts/openwarpgraph-composition-root.test.tssrc/domain/services/optic/CheckpointShardFactReader.ts
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/Receipt.tssrc/domain/api/ReceiptSupport.tssrc/domain/api/WriteRuntime.tssrc/domain/api/TimelineViewRuntime.tssrc/domain/api/Tick.tssrc/domain/api/ReceiptOutcome.tssrc/infrastructure/adapters/GitGraphAdapter.tssrc/domain/utils/roaring.tssrc/domain/api/TickRuntime.tssrc/domain/api/TimelineView.tssrc/domain/api/TimelineRuntime.tssrc/domain/services/optic/NeighborhoodPageCursor.tssrc/domain/api/openWarp.tssrc/domain/services/controllers/CheckpointController.tssrc/domain/api/ReadingBuilders.tssrc/domain/services/optic/CheckpointNeighborhoodPageReader.tssrc/domain/api/Reading.tssrc/domain/api/IntentRuntime.tssrc/domain/api/ReadingRuntime.tssrc/domain/api/JoinReceipt.tssrc/domain/services/optic/CheckpointTailTraversalReader.tssrc/domain/api/WriteReceipt.tssrc/domain/api/ReadReceipt.tssrc/domain/services/optic/CheckpointNeighborhoodBitmapPager.tssrc/domain/api/DraftTimelineRuntime.tssrc/domain/api/Timeline.tssrc/domain/services/optic/CheckpointTailWitnessLocator.tssrc/domain/api/Intent.tssrc/domain/services/optic/CheckpointShardFactReader.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/Receipt.tssrc/domain/api/ReceiptSupport.tssrc/domain/api/WriteRuntime.tssrc/domain/api/TimelineViewRuntime.tssrc/domain/api/Tick.tssrc/domain/api/ReceiptOutcome.tssrc/domain/utils/roaring.tssrc/domain/api/TickRuntime.tssrc/domain/api/TimelineView.tssrc/domain/api/TimelineRuntime.tssrc/domain/services/optic/NeighborhoodPageCursor.tssrc/domain/api/openWarp.tssrc/domain/services/controllers/CheckpointController.tssrc/domain/api/ReadingBuilders.tssrc/domain/services/optic/CheckpointNeighborhoodPageReader.tssrc/domain/api/Reading.tssrc/domain/api/IntentRuntime.tssrc/domain/api/ReadingRuntime.tssrc/domain/api/JoinReceipt.tssrc/domain/services/optic/CheckpointTailTraversalReader.tssrc/domain/api/WriteReceipt.tssrc/domain/api/ReadReceipt.tssrc/domain/services/optic/CheckpointNeighborhoodBitmapPager.tssrc/domain/api/DraftTimelineRuntime.tssrc/domain/api/Timeline.tssrc/domain/services/optic/CheckpointTailWitnessLocator.tssrc/domain/api/Intent.tssrc/domain/services/optic/CheckpointShardFactReader.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/Receipt.tssrc/domain/api/ReceiptSupport.tssrc/domain/api/WriteRuntime.tssrc/domain/api/TimelineViewRuntime.tssrc/domain/api/Tick.tssrc/domain/api/ReceiptOutcome.tssrc/domain/utils/roaring.tssrc/domain/api/TickRuntime.tssrc/domain/api/TimelineView.tssrc/domain/api/TimelineRuntime.tssrc/domain/services/optic/NeighborhoodPageCursor.tssrc/domain/api/openWarp.tssrc/domain/services/controllers/CheckpointController.tssrc/domain/api/ReadingBuilders.tssrc/domain/services/optic/CheckpointNeighborhoodPageReader.tssrc/domain/api/Reading.tssrc/domain/api/IntentRuntime.tssrc/domain/api/ReadingRuntime.tssrc/domain/api/JoinReceipt.tssrc/domain/services/optic/CheckpointTailTraversalReader.tssrc/domain/api/WriteReceipt.tssrc/domain/api/ReadReceipt.tssrc/domain/services/optic/CheckpointNeighborhoodBitmapPager.tssrc/domain/api/DraftTimelineRuntime.tssrc/domain/api/Timeline.tssrc/domain/services/optic/CheckpointTailWitnessLocator.tssrc/domain/api/Intent.tssrc/domain/services/optic/CheckpointShardFactReader.ts
🧠 Learnings (2)
📚 Learning: 2026-03-08T19:50:17.519Z
Learnt from: flyingrobots
Repo: git-stunts/git-warp PR: 65
File: CHANGELOG.md:88-88
Timestamp: 2026-03-08T19:50:17.519Z
Learning: Follow the Keep a Changelog convention for CHANGELOG.md. Allow duplicate subheadings across versions (e.g., '### Added', '### Fixed'). Configure markdownlint MD024 with {"siblings_only": true} to avoid cross-version false positives.
Applied to files:
CHANGELOG.md
📚 Learning: 2026-03-04T12:08:30.347Z
Learnt from: flyingrobots
Repo: git-stunts/git-warp PR: 63
File: package.json:126-126
Timestamp: 2026-03-04T12:08:30.347Z
Learning: Vitest 4 removes vite-node as a dependency and rewrites its pool system. Do not flag the absence of vite-node in package.json or lockfiles as an error for Vitest 4 projects. Use this as a general guideline: if a project uses Vitest 4, missing vite-node is expected and correct; only flag issues if there is evidence the project is not using Vitest 4 or if vite-node is explicitly required by the project.
Applied to files:
package.json
🪛 ast-grep (0.44.1)
test/unit/scripts/non-ts-tail-shape.test.ts
[warning] Importing child_process exposes a command-execution surface; ensure any command/argument built from input is validated, and prefer execFile/spawn with an argument array over exec.
Context: import { execFileSync } from 'node:child_process';
Note: [CWE-78] Improper Neutralization of Special Elements used in an OS Command ('OS Command Injection').
(detect-child-process-typescript)
test/unit/scripts/release-artifact-command.test.ts
[warning] 4: Importing child_process exposes a command-execution surface; ensure any command/argument built from input is validated, and prefer execFile/spawn with an argument array over exec.
Context: import {
spawnSync,
type SpawnSyncOptionsWithStringEncoding,
type SpawnSyncReturns,
} from 'node:child_process';
Note: [CWE-78] Improper Neutralization of Special Elements used in an OS Command ('OS Command Injection').
(detect-child-process-typescript)
[warning] 4: Importing child_process exposes a command-execution surface; ensure any command/argument built from input is validated, and prefer execFile/spawn with an argument array over exec.
Context: import {
spawnSync,
type SpawnSyncOptionsWithStringEncoding,
type SpawnSyncReturns,
} from 'node:child_process';
Note: [CWE-78] Improper Neutralization of Special Elements used in an OS Command ('OS Command Injection').
(detect-child-process-typescript)
[warning] 4: Importing child_process exposes a command-execution surface; ensure any command/argument built from input is validated, and prefer execFile/spawn with an argument array over exec.
Context: import {
spawnSync,
type SpawnSyncOptionsWithStringEncoding,
type SpawnSyncReturns,
} from 'node:child_process';
Note: [CWE-78] Improper Neutralization of Special Elements used in an OS Command ('OS Command Injection').
(detect-child-process-typescript)
[warning] 4: Importing child_process exposes a command-execution surface; ensure any command/argument built from input is validated, and prefer execFile/spawn with an argument array over exec.
Context: import {
spawnSync,
type SpawnSyncOptionsWithStringEncoding,
type SpawnSyncReturns,
} from 'node:child_process';
Note: [CWE-78] Improper Neutralization of Special Elements used in an OS Command ('OS Command Injection').
(detect-child-process-typescript)
🪛 ESLint
test/conformance/v18TraversalOpticReadBasis.test.ts
[error] 117-117: Move this regular expression to module scope to avoid re-compilation on every call.
(e18e/prefer-static-regex)
test/unit/scripts/v19-public-api-boundary.test.ts
[error] 147-147: Use spread syntax [...iterable] instead of Array.from(iterable) when no mapper function is provided
(e18e/prefer-spread-syntax)
🪛 OpenGrep (1.25.0)
scripts/direct-export-name.ts
[ERROR] 5-5: Dynamic command passed to child_process.exec/execSync. Use child_process.execFile or spawn with an argument array instead.
(coderabbit.command-injection.exec-js)
🔇 Additional comments (93)
test/conformance/btrProvenanceBoundary.test.ts (1)
3-8: LGTM!Also applies to: 51-61, 70-73, 82-88, 102-102
test/conformance/v18CoordinateOpticPublicPath.test.ts (1)
2-2: LGTM!Also applies to: 24-26, 35-37, 191-193
test/conformance/v18FirstUseOpticsHonesty.test.ts (1)
4-5: LGTM!Also applies to: 33-35, 100-100, 165-173, 183-187
test/conformance/v18NeighborhoodOpticReadBasis.test.ts (1)
54-54: LGTM!Also applies to: 66-66, 101-120, 174-180
test/conformance/v18TraversalOpticReadBasis.test.ts (1)
40-44: LGTM!Also applies to: 71-90, 118-129
test/conformance/v19BoundedNeighborhoodReading.test.ts (1)
1-176: LGTM!test/fixtures/mergeConflictCorpus.ts (1)
99-99: LGTM!test/type-check/v19-consumer.ts (1)
11-39: LGTM!Also applies to: 50-91, 107-120
test/conformance/btrSigningBytesOwnership.test.ts (1)
3-9: LGTM!Also applies to: 30-34, 44-48, 95-95, 109-109, 127-127, 145-163
test/conformance/immutableSnapshotSurface.test.ts (1)
2-7: LGTM!Also applies to: 38-38
test/unit/domain/services/query/SupportFragmentPlan.test.ts (1)
4-7: LGTM!Also applies to: 45-45, 55-55, 75-75, 93-105
test/unit/domain/strandAndRuntimeSeams.test.ts (1)
3-8: LGTM!Also applies to: 34-34, 59-59, 212-212, 234-234, 272-279
test/unit/domain/utils/roaring.test.ts (1)
49-57: LGTM!test/unit/domain/worldlineExecutableExamples.test.ts (1)
3-10: LGTM!Also applies to: 50-51, 180-183, 205-205, 214-223
test/unit/domain/worldlineReadExecutablePaths.test.ts (1)
3-3: LGTM!Also applies to: 7-7, 22-22
test/unit/infrastructure/adapters/RoaringLoaderAdapter.test.ts (1)
51-59: LGTM!test/conformance/v18BoundedMemoryLargeGraphGate.test.ts (1)
3-3: LGTM!test/type-check/v19-first-use.ts (1)
5-5: LGTM!test/type-check/v19-subpaths.ts (1)
4-33: LGTM!test/unit/cli/optic.test.ts (1)
12-17: LGTM!Also applies to: 48-52, 129-134, 172-177
test/unit/domain/ReceiptDiagnostics.test.ts (1)
1-39: LGTM!test/unit/domain/ReceiptOutcome.test.ts (1)
4-6: LGTM!Also applies to: 23-46
test/unit/domain/WarpApp.facade.test.ts (1)
3-5: LGTM!Also applies to: 25-25
test/unit/domain/WarpCore.apiSurface.test.ts (1)
2-2: LGTM!Also applies to: 32-39
test/unit/domain/WarpCore.effectPipeline.test.ts (1)
2-7: LGTM!Also applies to: 32-32, 57-57, 113-118, 130-130, 145-145
test/unit/domain/WarpCore.emit.test.ts (1)
2-14: LGTM!Also applies to: 24-24, 38-99, 126-126, 137-137, 163-182, 199-201
test/unit/domain/WarpFacade.test.ts (1)
5-16: LGTM!Also applies to: 67-67, 94-98, 109-147, 196-209, 220-239, 251-265, 276-285, 304-325, 327-498
test/unit/domain/WarpGraph.public-sync.test.ts (1)
2-2: LGTM!test/unit/domain/WarpGraph.strands.compare.test.ts (1)
76-81: LGTM!Also applies to: 92-92, 114-120, 146-157, 254-254, 337-337, 390-392, 418-430, 460-469, 526-527, 561-564, 611-614
test/unit/domain/WarpWorldline.test.ts (1)
3-3: LGTM!Also applies to: 19-19, 30-41, 57-65, 74-74, 83-83, 93-104, 146-151, 214-260, 335-337
test/unit/domain/continuum/GitWarpReceiptEnvelopeBoundary.test.ts (1)
3-3: LGTM!Also applies to: 12-29, 65-79
test/unit/domain/internalReadingSurface.behavior.test.ts (1)
3-12: LGTM!Also applies to: 24-24, 67-67, 79-80
test/unit/domain/services/merge/TtdMergeInspector.test.ts (1)
3-8: LGTM!test/unit/domain/services/optic/CheckpointTailTraversalReader.test.ts (1)
1-114: LGTM!test/unit/domain/services/query/BoundedSupportRule.test.ts (1)
4-5: LGTM!Also applies to: 43-43, 68-68, 89-104
test/unit/domain/services/query/CausalIndexPlan.test.ts (1)
4-5: LGTM!Also applies to: 53-58
test/unit/domain/services/controllers/CheckpointController.test.ts (1)
137-137: LGTM!Also applies to: 149-149, 441-442
test/unit/scripts/non-ts-tail-shape.test.ts (1)
44-46: LGTM!test/unit/scripts/openwarpgraph-composition-root.test.ts (1)
5-5: LGTM!Also applies to: 37-37, 68-72, 81-82, 100-101, 110-121, 172-174, 208-214
test/unit/scripts/release-artifact-command.test.ts (1)
1-13: LGTM!Also applies to: 25-31, 105-123, 133-138
test/unit/scripts/v19-public-api-boundary.test.ts (1)
7-53: LGTM!Also applies to: 99-136, 138-145, 154-212
test/unit/v7-guards.test.ts (1)
2-4: LGTM!Also applies to: 14-16, 48-50
vitest.config.ts (1)
33-33: LGTM!CHANGELOG.md (1)
29-33: LGTM!Also applies to: 46-50, 52-57
README.md (1)
58-59: LGTM!Also applies to: 61-105, 107-127, 129-149, 194-219, 237-237, 285-299, 326-326, 343-363, 369-373, 442-444
bin/cli/commands/optic.ts (1)
1-1: LGTM!docs/migrations/v19/README.md (1)
4-6: LGTM!Also applies to: 21-21, 30-47, 94-94, 108-108, 124-161, 185-185, 209-215, 231-254, 264-270, 306-308, 310-327
docs/topics/api/README.md (1)
3-3: LGTM!Also applies to: 66-66, 84-85, 105-116, 135-155, 219-224, 306-312, 340-340, 383-418
docs/topics/getting-started.md (1)
1-31: LGTM!Also applies to: 32-60, 62-110, 111-125, 126-138, 141-148, 149-159, 160-167
src/domain/api/Tick.ts (1)
1-23: LGTM!src/domain/api/Timeline.ts (1)
2-10: LGTM!Also applies to: 22-47, 59-90, 119-135, 160-175, 188-191, 211-272, 296-317
advanced.ts (1)
9-24: LGTM!diagnostics.ts (1)
7-28: LGTM!Also applies to: 30-44
src/domain/api/ReadReceipt.ts (1)
8-34: LGTM!Also applies to: 44-118
src/domain/api/Receipt.ts (1)
1-5: LGTM!src/domain/api/ReceiptSupport.ts (1)
3-16: LGTM!src/domain/services/optic/CheckpointNeighborhoodBitmapPager.ts (2)
98-112: LGTM!
175-197: 🎯 Functional CorrectnessNo change needed Roaring
rank(x)is inclusive (<= x), sobitmap.rank(after.globalId)andrankBefore(...)already advance past the current edge correctly.> Likely an incorrect or invalid review comment.src/domain/services/optic/CheckpointShardFactReader.ts (1)
40-52: LGTM!Also applies to: 106-115
src/domain/services/optic/CheckpointTailWitnessLocator.ts (1)
336-374: LGTM!docs/topics/git-substrate.md (1)
6-12: LGTM!docs/topics/querying.md (1)
1-20: LGTM!Also applies to: 21-55, 57-85, 86-87, 92-107, 108-113, 114-120
docs/topics/reference.md (1)
14-155: LGTM!Also applies to: 196-196
docs/topics/strands.md (1)
3-23: LGTM!Also applies to: 37-40
docs/topics/sync.md (1)
25-28: LGTM!index.ts (1)
7-7: LGTM!Also applies to: 18-63
src/domain/api/TimelineView.ts (1)
1-48: LGTM!src/domain/api/TimelineViewRuntime.ts (1)
1-15: LGTM!jsr.json (1)
9-18: LGTM!src/domain/api/DraftTimelineRuntime.ts (1)
9-10: LGTM!Also applies to: 22-26, 65-70, 177-192
src/domain/api/Intent.ts (1)
5-5: LGTM!Also applies to: 23-28, 60-64, 84-94, 97-121, 145-145
src/domain/api/IntentRuntime.ts (1)
8-14: LGTM!Also applies to: 50-53
src/domain/api/JoinReceipt.ts (1)
4-8: LGTM!Also applies to: 26-26, 49-87
src/domain/api/ReceiptOutcome.ts (1)
1-11: LGTM!src/domain/api/WriteReceipt.ts (1)
4-34: LGTM!Also applies to: 36-100
src/domain/api/WriteRuntime.ts (1)
1-79: LGTM!package.json (1)
32-32: LGTM!Also applies to: 47-47, 63-63
scripts/check-source-backed-reference.ts (1)
3-3: LGTM!Also applies to: 135-136, 240-248, 267-271, 284-284
scripts/direct-export-name.ts (1)
1-6: LGTM!src/domain/api/Reading.ts (1)
6-11: LGTM!Also applies to: 22-42, 60-63, 91-93, 117-182
src/domain/api/ReadingBuilders.ts (1)
2-5: LGTM!Also applies to: 7-13, 15-17
src/domain/api/ReadingRuntime.ts (1)
3-43: LGTM!Also applies to: 45-65, 67-73, 75-99, 100-134, 135-150, 152-183, 185-200
src/infrastructure/adapters/GitGraphAdapter.ts (1)
51-51: LGTM!storage.ts (1)
4-13: LGTM!Also applies to: 15-20, 21-21
src/domain/api/TickRuntime.ts (1)
1-17: LGTM!Also applies to: 27-32
src/domain/api/TimelineRuntime.ts (1)
9-31: LGTM!src/domain/api/openWarp.ts (1)
10-13: LGTM!src/domain/services/controllers/CheckpointController.ts (1)
11-11: LGTM!src/domain/services/optic/CheckpointNeighborhoodPageReader.ts (2)
1-122: LGTM!Also applies to: 124-139, 142-160, 164-348
123-123: 🗄️ Data Integrity & IntegrationValidate the shard payloads before decoding them.
decode<T>()only provides compile-time shapes; if these persisted shards are not runtime-validated, malformed data can still reachObject.entries, bitmap deserialization, or candidate construction.src/domain/services/optic/CheckpointTailTraversalReader.ts (1)
18-25: LGTM!Also applies to: 108-108, 122-122, 134-134, 152-160, 202-213
src/domain/services/optic/NeighborhoodPageCursor.ts (1)
1-170: LGTM!src/domain/utils/roaring.ts (1)
12-13: LGTM!
Self-review at
|
Code Lawyer review at
|
Release Preflight
If this PR is from a |
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (4)
docs/topics/getting-started.md (1)
62-88: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winShow the receipt-outcome check before logging
.value.Unlike the equivalent examples in
README.mdanddocs/topics/api/README.md(both gate.valueaccess onreceipt.outcome === 'accepted'), this example logsseverity.value/exists.valueunconditionally. Given the immediately following prose aboutobstructedreceipts, this teaches readers to skip the receipt-first pattern the rest of the doc set emphasizes.✏️ Suggested fix
-console.log(severity.value, severity.receipt); -console.log(exists.value, exists.receipt); +if (severity.receipt.outcome === 'accepted') { + console.log(severity.value); +} +console.log(exists.value, exists.receipt);🤖 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 `@docs/topics/getting-started.md` around lines 62 - 88, Update the “Read A Bounded Value” example to check each reading’s receipt outcome before accessing or logging its value, using the existing accepted-outcome pattern from the related documentation. Preserve receipt logging and ensure obstructed readings do not access or materialize `.value`.src/domain/services/optic/NeighborhoodPageCursor.ts (1)
42-50: 🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy liftMake pagination cursors opaque and tamper-resistant.
This directly exposes traversal coordinates and lets callers forge a valid
afterposition, so resumed reads can skip or reorder results instead of resuming exactly. Use an opaque cursor codec/state handle supplied through a port, rather than serializing scope and global IDs into the public token.As per PR objectives, traversal resumption must provide “exact opaque traversal resumption.”
🤖 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 `@src/domain/services/optic/NeighborhoodPageCursor.ts` around lines 42 - 50, Replace the direct field serialization in the cursor construction flow of NeighborhoodPageCursor with the opaque cursor codec/state-handle port. Encode the complete traversal state through that port and expose only its opaque token prefixed by CURSOR_PREFIX; do not include checkpointSha, nodeId, direction, labels, or globalId in the public cursor. Ensure decoding resumes the exact stored traversal state.src/domain/api/openWarp.ts (1)
2-21: 📐 Maintainability & Code Quality | 🟠 Major | 🏗️ Heavy liftKeep host-port installation outside the domain API.
openWarp()now initializes ambient codec/crypto host resolvers fromsrc/domain. Move this bootstrap into an application/infrastructure composition root and inject the required runtime ports; core must not depend on ambient host capabilities.🤖 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 `@src/domain/api/openWarp.ts` around lines 2 - 21, Remove installDefaultRuntimeHostNodePorts from openWarp and eliminate the domain API’s dependency on ambient host initialization. Move this bootstrap to the application/infrastructure composition root, then ensure openWarp receives the required runtime codec/crypto ports through its existing options or dependency-injection path while preserving assertOpenWarpOptions and the normal Warp creation flow.Source: Coding guidelines
src/domain/api/TimelineView.ts (1)
19-26: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winValidate the view’s runtime-backed fields.
The constructor accepts forged
tickvalues and invalidname/writeridentities. Validatetick instanceof Tickand the identity fields before storing them so aTimelineViewcannot carry invalid domain state.🤖 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 `@src/domain/api/TimelineView.ts` around lines 19 - 26, Update the TimelineView constructor to validate all runtime-backed options before assignment: require options.tick to be an instance of Tick and validate the name and writer identities using the domain’s existing identity requirements. Preserve the current readReading function validation and throw the established WarpError for invalid options, ensuring no invalid values are stored in the instance.Source: Coding guidelines
🤖 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 `@test/unit/domain/WarpFacade.test.ts`:
- Line 334: Remove the duplicate exposedValue declaration in the test scope,
retaining a single typed const declaration with the existing roles and evidence
shape so the test type-checks without changing its behavior.
---
Outside diff comments:
In `@docs/topics/getting-started.md`:
- Around line 62-88: Update the “Read A Bounded Value” example to check each
reading’s receipt outcome before accessing or logging its value, using the
existing accepted-outcome pattern from the related documentation. Preserve
receipt logging and ensure obstructed readings do not access or materialize
`.value`.
In `@src/domain/api/openWarp.ts`:
- Around line 2-21: Remove installDefaultRuntimeHostNodePorts from openWarp and
eliminate the domain API’s dependency on ambient host initialization. Move this
bootstrap to the application/infrastructure composition root, then ensure
openWarp receives the required runtime codec/crypto ports through its existing
options or dependency-injection path while preserving assertOpenWarpOptions and
the normal Warp creation flow.
In `@src/domain/api/TimelineView.ts`:
- Around line 19-26: Update the TimelineView constructor to validate all
runtime-backed options before assignment: require options.tick to be an instance
of Tick and validate the name and writer identities using the domain’s existing
identity requirements. Preserve the current readReading function validation and
throw the established WarpError for invalid options, ensuring no invalid values
are stored in the instance.
In `@src/domain/services/optic/NeighborhoodPageCursor.ts`:
- Around line 42-50: Replace the direct field serialization in the cursor
construction flow of NeighborhoodPageCursor with the opaque cursor
codec/state-handle port. Encode the complete traversal state through that port
and expose only its opaque token prefixed by CURSOR_PREFIX; do not include
checkpointSha, nodeId, direction, labels, or globalId in the public cursor.
Ensure decoding resumes the exact stored traversal state.
🪄 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
Run ID: 953890b1-c6ac-4766-938a-f569aa438245
📒 Files selected for processing (28)
CHANGELOG.mdREADME.mdbin/warp-graph.tsdocs/migrations/v19/README.mddocs/topics/api/README.mddocs/topics/getting-started.mddocs/topics/reference.mdindex.tssrc/domain/api/DraftTimelineRuntime.tssrc/domain/api/Intent.tssrc/domain/api/JoinReceipt.tssrc/domain/api/ReadReceipt.tssrc/domain/api/ReadingRuntime.tssrc/domain/api/ReceiptOutcome.tssrc/domain/api/Timeline.tssrc/domain/api/TimelineView.tssrc/domain/api/WriteReceipt.tssrc/domain/api/openWarp.tssrc/domain/graph/LegacyPropertyValue.tssrc/domain/services/optic/NeighborhoodPageCursor.tssrc/domain/types/PropValue.tstest/conformance/v18FirstUseOpticsHonesty.test.tstest/conformance/v18TraversalOpticReadBasis.test.tstest/type-check/v19-consumer.tstest/unit/domain/ReceiptOutcome.test.tstest/unit/domain/WarpFacade.test.tstest/unit/domain/services/optic/CheckpointTailTraversalReader.test.tstest/unit/scripts/v19-public-api-boundary.test.ts
💤 Files with no reviewable changes (1)
- index.ts
📜 Review details
⏰ Context from checks skipped due to timeout. (4)
- GitHub Check: test-node (22)
- GitHub Check: type-firewall-lint
- 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/ReceiptOutcome.tssrc/domain/services/optic/NeighborhoodPageCursor.tssrc/domain/api/TimelineView.tssrc/domain/graph/LegacyPropertyValue.tssrc/domain/api/JoinReceipt.tssrc/domain/api/Timeline.tssrc/domain/api/openWarp.tssrc/domain/api/WriteReceipt.tssrc/domain/api/DraftTimelineRuntime.tssrc/domain/api/ReadingRuntime.tssrc/domain/api/Intent.tssrc/domain/api/ReadReceipt.tssrc/domain/types/PropValue.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/ReceiptOutcome.tssrc/domain/services/optic/NeighborhoodPageCursor.tssrc/domain/api/TimelineView.tssrc/domain/graph/LegacyPropertyValue.tssrc/domain/api/JoinReceipt.tssrc/domain/api/Timeline.tssrc/domain/api/openWarp.tssrc/domain/api/WriteReceipt.tssrc/domain/api/DraftTimelineRuntime.tssrc/domain/api/ReadingRuntime.tssrc/domain/api/Intent.tssrc/domain/api/ReadReceipt.tssrc/domain/types/PropValue.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/ReceiptOutcome.tssrc/domain/services/optic/NeighborhoodPageCursor.tssrc/domain/api/TimelineView.tssrc/domain/graph/LegacyPropertyValue.tssrc/domain/api/JoinReceipt.tssrc/domain/api/Timeline.tssrc/domain/api/openWarp.tssrc/domain/api/WriteReceipt.tssrc/domain/api/DraftTimelineRuntime.tssrc/domain/api/ReadingRuntime.tssrc/domain/api/Intent.tssrc/domain/api/ReadReceipt.tssrc/domain/types/PropValue.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/ReceiptOutcome.tstest/unit/domain/services/optic/CheckpointTailTraversalReader.test.tsbin/warp-graph.tstest/unit/domain/ReceiptOutcome.test.tstest/conformance/v18FirstUseOpticsHonesty.test.tssrc/domain/services/optic/NeighborhoodPageCursor.tstest/type-check/v19-consumer.tstest/conformance/v18TraversalOpticReadBasis.test.tssrc/domain/api/TimelineView.tstest/unit/scripts/v19-public-api-boundary.test.tssrc/domain/graph/LegacyPropertyValue.tssrc/domain/api/JoinReceipt.tssrc/domain/api/Timeline.tssrc/domain/api/openWarp.tssrc/domain/api/WriteReceipt.tssrc/domain/api/DraftTimelineRuntime.tssrc/domain/api/ReadingRuntime.tssrc/domain/api/Intent.tssrc/domain/api/ReadReceipt.tssrc/domain/types/PropValue.tstest/unit/domain/WarpFacade.test.ts
🧠 Learnings (1)
📚 Learning: 2026-03-08T19:50:17.519Z
Learnt from: flyingrobots
Repo: git-stunts/git-warp PR: 65
File: CHANGELOG.md:88-88
Timestamp: 2026-03-08T19:50:17.519Z
Learning: Follow the Keep a Changelog convention for CHANGELOG.md. Allow duplicate subheadings across versions (e.g., '### Added', '### Fixed'). Configure markdownlint MD024 with {"siblings_only": true} to avoid cross-version false positives.
Applied to files:
CHANGELOG.md
🪛 ESLint
test/conformance/v18TraversalOpticReadBasis.test.ts
[error] 120-120: Move this regular expression to module scope to avoid re-compilation on every call.
(e18e/prefer-static-regex)
🔇 Additional comments (35)
README.md (2)
266-272: Causal-cone finiteness claim still unqualified.This aside still states well-foundedness alone makes
$D(v)$ finite even when$H$ is unbounded — the same false mathematical justification flagged previously. Only typography changed here, not the substance.
55-105: LGTM!docs/topics/getting-started.md (2)
139-140:join()still runs unconditionally afterpreviewJoin.Same issue as flagged previously:
audit.join(draft)is called regardless ofpreview.receipt.outcome, so obstructed/conflicted previews still proceed to join here.
1-61: LGTM!Also applies to: 89-137, 141-167
CHANGELOG.md (1)
28-29: LGTM!Also applies to: 41-42, 52-58
docs/topics/api/README.md (1)
87-163: LGTM!docs/topics/reference.md (3)
14-33: LGTM!
108-136: 📐 Maintainability & Code QualityConfirm
WarpWorldlineCoordinateFrontierEntrynaming is intentional underadvanced.This type retains the "WarpWorldline" prefix even though the migration guide documents
WarpWorldlineas renamed to rootTimeline. Sinceadvancedis allowed to keep expert-facing internals, this may be fine, but worth confirming it isn't a stray leftover from the pre-rename naming scheme that should follow the same rename.
87-107: LGTM!Also applies to: 138-196
docs/migrations/v19/README.md (2)
258-260: 🎯 Functional CorrectnessCheck the
openWarpGraph()replacement note. It repeats theWarpCoreguidance and may not describe the correct v19 migration path.
248-248: 🎯 Functional CorrectnessClarify the relationship between
EdgePropertyIntentFieldsandEdgeIntentFields. The migration table saysEdgePropertyIntentFieldswas removed, butdocs/topics/reference.mdalso listsEdgeIntentFieldsas a root export. If these are different shapes, note that distinction; if this is the renamed successor, the row should not say “removed”.bin/warp-graph.ts (1)
4-10: LGTM!src/domain/api/Intent.ts (1)
2-2: LGTM!Also applies to: 64-69, 84-94, 153-157
src/domain/api/WriteReceipt.ts (1)
4-4: LGTM!Also applies to: 38-49
src/domain/api/DraftTimelineRuntime.ts (1)
29-41: LGTM!Also applies to: 61-75, 182-197, 239-258
src/domain/graph/LegacyPropertyValue.ts (1)
2-15: LGTM!src/domain/types/PropValue.ts (1)
19-27: LGTM!Also applies to: 61-64, 85-127
src/domain/api/Timeline.ts (1)
112-117: Keep coordinate capture off the rootTimelinesurface.
coordinate()still exposes formal coordinate machinery from the first-use timeline API, contrary to the opaque-tick boundary.test/conformance/v18TraversalOpticReadBasis.test.ts (2)
120-120: Move the cursor regex to module scope.The inline regex still violates
e18e/prefer-static-regex.
21-21: LGTM!Also applies to: 39-44, 70-90, 180-196
test/conformance/v18FirstUseOpticsHonesty.test.ts (1)
33-35: LGTM!Also applies to: 99-100, 165-187
test/type-check/v19-consumer.ts (1)
8-39: LGTM!Also applies to: 50-95, 111-126
test/unit/scripts/v19-public-api-boundary.test.ts (3)
61-90: Namespace re-exports still bypass this boundary guard.
if (!ts.isNamedExports(statement.exportClause)) continue;still skipsexport * as ns from '...'(aNamespaceExportclause), so it is never recorded instarExports. This was flagged in a prior review round and remains unaddressed.
92-166: LGTM!
245-256: 🎯 Functional Correctness
defaultsModulemay be too specific for theindex.tscheck. IfimportedModules()compares raw specifiers,index.tscould import the same file through a different relative path and still make this assertion pass. Match by resolved path or basename instead.src/domain/api/ReadingRuntime.ts (5)
16-29: LGTM!
45-65: LGTM!
100-118: LGTM!
152-167: LGTM!
185-200: 🎯 Functional CorrectnessCheck whether
tail_budget_exceededneeds its own repair hints.missing_bounded_basisandtail_budget_exceededcurrently reuseREPAIR_BOUNDED_BASIS; split the guidance only if those failures call for different remediation.src/domain/api/ReceiptOutcome.ts (1)
8-18: LGTM!src/domain/api/JoinReceipt.ts (1)
4-27: LGTM!Also applies to: 32-35, 61-101
src/domain/api/ReadReceipt.ts (1)
5-30: LGTM!Also applies to: 47-71, 94-119
test/unit/domain/ReceiptOutcome.test.ts (1)
4-100: LGTM!test/unit/domain/services/optic/CheckpointTailTraversalReader.test.ts (1)
1-106: LGTM!
Self-review at
|
Code Lawyer review at
|
Release Preflight
If this PR is from a |
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/topics/querying.md (1)
23-30: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winDefine
plumbingbefore using it in the example.The standalone snippet passes
plumbingtoGitStorageAdapterbut never imports or initializes it. Add theGitPlumbingsetup, or explicitly reference the earlier setup example.🤖 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 `@docs/topics/querying.md` around lines 23 - 30, Update the standalone example around openWarp and GitStorageAdapter to define plumbing before it is passed to GitStorageAdapter, using the GitPlumbing import and initialization shown in the earlier setup example or explicitly referencing that setup instead.
🤖 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 `@src/domain/services/optic/CheckpointTailFactReducer.ts`:
- Around line 46-64: Update includesNeighborhood to check
neighborhoodNodeIdsForOperation results directly while iterating
entry.patch.ops, returning true immediately when options.nodeId matches and
false after all operations are checked. Do not call neighborhoodNodeIds or build
and sort the full node-ID set for this membership-only path; preserve
normalization and the existing neighborhood scope options.
---
Outside diff comments:
In `@docs/topics/querying.md`:
- Around line 23-30: Update the standalone example around openWarp and
GitStorageAdapter to define plumbing before it is passed to GitStorageAdapter,
using the GitPlumbing import and initialization shown in the earlier setup
example or explicitly referencing that setup instead.
🪄 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
Run ID: f1c85ceb-bff9-4331-ae3b-499768fb5561
📒 Files selected for processing (26)
CHANGELOG.mdREADME.mdadvanced.tsdocs/migrations/v19/README.mddocs/topics/api/README.mddocs/topics/getting-started.mddocs/topics/optic-reads.mddocs/topics/querying.mddocs/topics/reference.mdscripts/check-source-backed-reference.tssrc/domain/api/TickRuntime.tssrc/domain/api/Timeline.tssrc/domain/api/TimelineRuntime.tssrc/domain/api/captureCoordinate.tssrc/domain/services/controllers/CheckpointController.tssrc/domain/services/optic/CheckpointTailFactReducer.tssrc/domain/services/optic/CheckpointTailWitnessLocator.tstest/conformance/v18TraversalOpticReadBasis.test.tstest/conformance/v19BoundedNeighborhoodReading.test.tstest/type-check/v19-consumer.tstest/type-check/v19-subpaths.tstest/unit/domain/WarpFacade.test.tstest/unit/domain/WarpGraph.coverageGaps.test.tstest/unit/domain/services/controllers/CheckpointController.test.tstest/unit/domain/services/optic/CheckpointShardFactReader.manifest.test.tstest/unit/scripts/v19-public-api-boundary.test.ts
💤 Files with no reviewable changes (2)
- src/domain/api/TimelineRuntime.ts
- src/domain/api/Timeline.ts
📜 Review details
⏰ Context from checks skipped due to timeout. (3)
- GitHub Check: coverage-threshold
- GitHub Check: test-node (22)
- 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/captureCoordinate.tssrc/domain/api/TickRuntime.tssrc/domain/services/controllers/CheckpointController.tssrc/domain/services/optic/CheckpointTailFactReducer.tssrc/domain/services/optic/CheckpointTailWitnessLocator.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/captureCoordinate.tssrc/domain/api/TickRuntime.tssrc/domain/services/controllers/CheckpointController.tssrc/domain/services/optic/CheckpointTailFactReducer.tssrc/domain/services/optic/CheckpointTailWitnessLocator.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/captureCoordinate.tssrc/domain/api/TickRuntime.tssrc/domain/services/controllers/CheckpointController.tssrc/domain/services/optic/CheckpointTailFactReducer.tssrc/domain/services/optic/CheckpointTailWitnessLocator.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/captureCoordinate.tsscripts/check-source-backed-reference.tstest/unit/domain/services/optic/CheckpointShardFactReader.manifest.test.tstest/type-check/v19-subpaths.tstest/unit/domain/WarpGraph.coverageGaps.test.tssrc/domain/api/TickRuntime.tssrc/domain/services/controllers/CheckpointController.tstest/unit/domain/services/controllers/CheckpointController.test.tssrc/domain/services/optic/CheckpointTailFactReducer.tsadvanced.tstest/type-check/v19-consumer.tstest/conformance/v19BoundedNeighborhoodReading.test.tstest/unit/scripts/v19-public-api-boundary.test.tssrc/domain/services/optic/CheckpointTailWitnessLocator.tstest/conformance/v18TraversalOpticReadBasis.test.tstest/unit/domain/WarpFacade.test.ts
🧠 Learnings (1)
📚 Learning: 2026-03-08T19:50:17.519Z
Learnt from: flyingrobots
Repo: git-stunts/git-warp PR: 65
File: CHANGELOG.md:88-88
Timestamp: 2026-03-08T19:50:17.519Z
Learning: Follow the Keep a Changelog convention for CHANGELOG.md. Allow duplicate subheadings across versions (e.g., '### Added', '### Fixed'). Configure markdownlint MD024 with {"siblings_only": true} to avoid cross-version false positives.
Applied to files:
CHANGELOG.md
🔇 Additional comments (24)
src/domain/api/captureCoordinate.ts (1)
1-12: LGTM!docs/topics/getting-started.md (1)
1-167: LGTM!scripts/check-source-backed-reference.ts (1)
3-3: LGTM!Also applies to: 135-136, 240-248, 267-271, 284-284
test/unit/domain/services/optic/CheckpointShardFactReader.manifest.test.ts (1)
102-122: LGTM!test/type-check/v19-subpaths.ts (1)
4-33: LGTM!test/unit/domain/WarpGraph.coverageGaps.test.ts (1)
1053-1055: LGTM!docs/topics/querying.md (1)
1-20: LGTM!Also applies to: 44-121
test/conformance/v19BoundedNeighborhoodReading.test.ts (1)
177-190: LGTM!src/domain/api/TickRuntime.ts (1)
6-34: LGTM!CHANGELOG.md (1)
34-37: LGTM! Accurately reflects the tick-binding and coordinate-capture relocation changes.Based on learnings, the Keep a Changelog
siblings_onlyconvention for repeated subheadings is respected here.Source: Learnings
src/domain/services/controllers/CheckpointController.ts (1)
381-406: LGTM! Malformed checkpoint refs now correctly throwPersistenceErrorinstead of being treated as absent, addressing the prior finding.Also applies to: 603-610
test/unit/domain/services/controllers/CheckpointController.test.ts (1)
473-501: LGTM! Good coverage of both new rejection paths.test/type-check/v19-consumer.ts (1)
52-54: LGTM!src/domain/services/optic/CheckpointTailWitnessLocator.ts (1)
227-302: LGTM! This correctly resolves the prior finding — basis load and tail scan are now shared once per traversal viaTraversalReadContext/tailByNodeinstead of being repeated per frontier node.Also applies to: 339-387
docs/topics/api/README.md (1)
347-352: 🗄️ Data Integrity & IntegrationAlign the example with
captureCoordinate’s signature. The call shown here only passestimeline; show the required argument(s) or switch to the documented coordinate capture API.test/unit/scripts/v19-public-api-boundary.test.ts (1)
61-96: 📐 Maintainability & Code QualityBoth previously flagged issues are now resolved.
The namespace-export branch (
ts.isNamespaceExport) and the spread-syntax fix forsorted()are both present, and new tests cover the namespace-export classification and the advanced.ts value-export set.Also applies to: 186-188, 201-224
test/conformance/v18TraversalOpticReadBasis.test.ts (1)
13-13: 📐 Maintainability & Code QualityPreviously flagged regex-scope lint issue resolved.
The cursor pattern is now a module-scope constant (
NEIGHBORHOOD_CURSOR_PATTERN) reused across assertions.Also applies to: 96-154, 177-191
advanced.ts (1)
1-25: LGTM!docs/migrations/v19/README.md (1)
37-47: LGTM!Also applies to: 163-190, 229-268
docs/topics/optic-reads.md (1)
14-16: LGTM!Also applies to: 25-25, 81-81
README.md (1)
266-272: LGTM!docs/topics/reference.md (1)
110-136: LGTM!Also applies to: 193-197
test/unit/domain/WarpFacade.test.ts (2)
6-6: LGTM!Also applies to: 188-188, 438-438, 451-455
314-344: 🎯 Functional CorrectnessDuplicate
const exposedValuedeclaration
Keep only oneconst exposedValuein this test block; a second declaration here would fail type-checking.
Final self-review at
|
Final Code Lawyer addendum at
|
Release Preflight
If this PR is from a |
1 participant
Summary
openWarp,intent, andreading, with supported public nouns exported as typesReceiptOutcomeaxis@git-stunts/git-warp/advancedIssue
Closes #712
Public runtime values
Test plan
ADR checks
This PR does not change persisted operation formats, wire compatibility, or schema constants. The conditional ADR checks are therefore not applicable; checkpoint changes only make malformed existing refs fail closed.