Move graph exports behind v19 public API boundary - #726
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
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 comments (1)
📝 WalkthroughSummary by CodeRabbit
WalkthroughThis PR narrows the package root into a v19 application boundary, moves legacy graph-first compatibility into explicit subpaths, and updates docs, tests, and release checks to match the new public surface. Changesv19 API Boundary Restructuring
Estimated code review effort: 4 (Complex) | ~60 minutes Possibly related issues
Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
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: 4
🤖 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/migrations/v19/README.md`:
- Around line 115-125: The example in the receipt handling section treats every
non-accepted outcome as a generic error, which hides the distinct obstructed,
conflicted, and underdetermined flows used later. Update the snippet around
events.write and receipt.outcome to branch on those specific outcomes instead of
immediately throwing Error(receipt.reason), and preserve the
repair/resolve/support data so readers see how to handle each case correctly.
In `@examples/bounded-reads.ts`:
- Around line 2-10: Update the example header in the bounded-reads sample so it
no longer describes the APIs as the “advanced openWarpGraph() surface,” since
the import comes from the legacy subpath; keep the wording aligned with the
actual symbols GitGraphAdapter and openWarpGraph imported from
`@git-stunts/git-warp/legacy`, and make the text clearly distinguish this
migration example from the new /advanced path to avoid steering readers to the
wrong import.
In `@index.ts`:
- Around line 6-11: The package root exports in index.ts still include
graph-first and storage internals that should be kept behind the documented v19
boundary. Remove the root re-exports for IndexRebuildService,
BitmapIndexBuilder, BitmapIndexReader, BlobStoragePort, and
InMemoryBlobStorageAdapter, and leave those symbols available only through
legacy.ts or the appropriate subpath exports. If any of these must remain at the
root, update the index.ts boundary docstring and related boundary test to
explicitly document that exception.
In `@legacy.ts`:
- Line 216: Keep the top-level call to installDefaultRuntimeHostNodePorts() only
if it is guaranteed to be idempotent, since it runs on import as a module side
effect; otherwise move it behind an explicit initialization path in legacy.ts.
Also revisit the WarpApp default export in the same module and remove the
v15-era compatibility export if it is no longer needed, or otherwise leave a
clear migration-only compatibility path without adding additional deprecation
layers.
🪄 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: fb0dff67-28d0-4817-97e7-f05595813a1a
📒 Files selected for processing (69)
CHANGELOG.mdREADME.mdadvanced.tsbin/cli/commands/optic.tsbrowser.tsdiagnostics.tsdocs/migrations/v19/README.mddocs/topics/README.mddocs/topics/api/README.mddocs/topics/continuum-boundary.mddocs/topics/getting-started.mddocs/topics/git-substrate.mddocs/topics/querying.mddocs/topics/reference.mddocs/topics/strands.mddocs/topics/supported-outcome-settlement.mddocs/topics/sync.mdexamples/README.mdexamples/bounded-reads.tsexamples/observers.tsexamples/optics.tsindex.tsjsr.jsonlegacy.tspackage.jsonscripts/check-docs-topology.shscripts/release-guard.shsrc/domain/WarpApp.tssrc/domain/WarpCore.tssrc/domain/WarpGraph.tssrc/domain/WarpWorldline.tsstorage.tstest/conformance/btrProvenanceBoundary.test.tstest/conformance/btrSigningBytesOwnership.test.tstest/conformance/snapshotPublicApiSurface.test.tstest/conformance/v18BoundedMemoryLargeGraphGate.test.tstest/conformance/v18CoordinateOpticPublicPath.test.tstest/conformance/v18FirstUseOpticsHonesty.test.tstest/type-check/consumer.tstest/unit/cli/optic.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/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/index.exports.test.tstest/unit/domain/publicApiExecutableExamples.test.tstest/unit/domain/publicReadApiExecutablePaths.test.tstest/unit/domain/publicReadingSurface.behavior.test.tstest/unit/domain/publicStrandAndRuntimeSeams.test.tstest/unit/domain/services/merge/TtdMergeInspector.test.tstest/unit/domain/services/query/BoundedSupportRule.test.tstest/unit/domain/services/query/CausalIndexPlan.test.tstest/unit/domain/services/query/SupportFragmentPlan.test.tstest/unit/index.exports.test.tstest/unit/scripts/jsr-publish-root-graph-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/root-export-line-budget.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.json
📜 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)
**/*.{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:
test/conformance/v18BoundedMemoryLargeGraphGate.test.tstest/unit/domain/WarpApp.facade.test.tstest/unit/index.exports.test.tstest/unit/domain/publicStrandAndRuntimeSeams.test.tssrc/domain/WarpCore.tstest/unit/v7-guards.test.tstest/unit/domain/publicReadApiExecutablePaths.test.tstest/conformance/v18CoordinateOpticPublicPath.test.tstest/type-check/consumer.tstest/unit/scripts/root-export-line-budget.test.tstest/unit/scripts/v19-public-api-boundary.test.tssrc/domain/WarpApp.tstest/unit/domain/services/query/CausalIndexPlan.test.tstest/unit/scripts/openwarpgraph-composition-root.test.tstest/unit/domain/WarpCore.apiSurface.test.tssrc/domain/WarpGraph.tstest/unit/scripts/jsr-publish-root-graph-shape.test.tstest/unit/domain/services/query/SupportFragmentPlan.test.tstest/unit/domain/WarpGraph.strands.compare.test.tsstorage.tstest/unit/domain/continuum/GitWarpReceiptEnvelopeBoundary.test.tstest/unit/domain/WarpCore.effectPipeline.test.tstest/unit/domain/index.exports.test.tstest/unit/domain/WarpGraph.public-sync.test.tstest/unit/domain/WarpWorldline.test.tstest/unit/scripts/public-api-facade-split.test.tsbin/cli/commands/optic.tstest/unit/cli/optic.test.tsexamples/bounded-reads.tstest/conformance/btrProvenanceBoundary.test.tstest/conformance/v18FirstUseOpticsHonesty.test.tssrc/domain/WarpWorldline.tstest/unit/domain/services/query/BoundedSupportRule.test.tsexamples/optics.tstest/unit/domain/publicReadingSurface.behavior.test.tsdiagnostics.tstest/unit/domain/publicApiExecutableExamples.test.tstest/conformance/btrSigningBytesOwnership.test.tstest/conformance/snapshotPublicApiSurface.test.tstest/unit/scripts/worldline-api-deprecation.test.tsadvanced.tstest/unit/domain/WarpCore.emit.test.tslegacy.tstest/unit/scripts/public-api-aperture-noun.test.tstest/unit/scripts/v18-package-surface-audit.test.tsexamples/observers.tstest/unit/domain/services/merge/TtdMergeInspector.test.tsbrowser.tsindex.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/WarpCore.tssrc/domain/WarpApp.tssrc/domain/WarpGraph.tssrc/domain/WarpWorldline.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/WarpCore.tssrc/domain/WarpApp.tssrc/domain/WarpGraph.tssrc/domain/WarpWorldline.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/WarpCore.tssrc/domain/WarpApp.tssrc/domain/WarpGraph.tssrc/domain/WarpWorldline.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
🪛 LanguageTool
docs/topics/supported-outcome-settlement.md
[style] ~65-~65: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...port semantics into git-warp storage. - Do not require zk proof systems for base B...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~66-~66: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...oof systems for base BTR publication. - Do not call typed obstructions counterfact...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
docs/migrations/v19/README.md
[style] ~314-~314: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... reads with read(reading.*) calls. 5. Replace seek()/coordinate-first call sites wi...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
docs/topics/api/README.md
[style] ~14-~14: To elevate your writing, try using a synonym here.
Context: ...e boundary should be small, boring, and hard to misuse. ## Why Change The v18 publ...
(HARD_TO)
🔇 Additional comments (71)
CHANGELOG.md (1)
10-19: LGTM!README.md (1)
3-3: LGTM!Also applies to: 32-43, 54-103, 121-129, 260-279, 333-348
docs/topics/README.md (1)
19-20: LGTM!docs/topics/continuum-boundary.md (1)
43-43: LGTM!Also applies to: 67-67
docs/topics/getting-started.md (1)
1-6: LGTM!Also applies to: 26-33, 51-53
docs/topics/git-substrate.md (1)
6-18: LGTM!docs/topics/api/README.md (1)
127-129: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winFix the relative links on this page.
Lines 127-129 use paths as if this file lived at the repo root, but it is nested under
docs/topics/api/, so the links resolve incorrectly from here.Proposed fix
-See the [v19 API reflection](docs/topics/api/), the -[v19 migration guide](docs/migrations/v19/), and -[Optic reads](docs/topics/optic-reads.md) for the model. +See the [v19 API reflection](./), the +[v19 migration guide](../../migrations/v19/), and +[Optic reads](../optic-reads.md) for the model.> Likely an incorrect or invalid review comment.docs/topics/querying.md (1)
1-5: LGTM!Also applies to: 14-29, 42-45
docs/topics/reference.md (1)
15-28: LGTM!Also applies to: 29-34, 35-105, 107-117
docs/topics/strands.md (1)
3-4: LGTM!Also applies to: 26-27
docs/topics/supported-outcome-settlement.md (1)
1-66: LGTM!docs/topics/sync.md (1)
25-26: LGTM!Also applies to: 39-41
docs/migrations/v19/README.md (1)
1-112: LGTM!Also applies to: 128-358
scripts/check-docs-topology.sh (1)
18-20: LGTM!Also applies to: 62-70, 72-96
scripts/release-guard.sh (2)
77-80: LGTM!Also applies to: 90-99, 403-403
423-449: 📐 Maintainability & Code QualityNo action needed
docs/migrationsis README-only today, so this scan won’t block any non-doc assets in the current layout.index.ts (2)
20-55: LGTM!
60-63: LGTM!Also applies to: 66-102
test/unit/domain/WarpCore.effectPipeline.test.ts (1)
10-10: LGTM!test/unit/domain/WarpCore.emit.test.ts (1)
5-5: LGTM!test/unit/domain/WarpGraph.public-sync.test.ts (1)
2-2: LGTM!test/unit/domain/continuum/GitWarpReceiptEnvelopeBoundary.test.ts (1)
3-3: LGTM!test/unit/scripts/jsr-publish-root-graph-shape.test.ts (1)
7-7: LGTM!test/unit/scripts/root-export-line-budget.test.ts (1)
21-26: LGTM!legacy.ts (2)
1-12: LGTM!
21-21: 🎯 Functional CorrectnessNo issue: these ports are runtime abstract classes, so the plain imports/exports are fine.
> Likely an incorrect or invalid review comment.src/domain/WarpGraph.ts (1)
363-368: LGTM!test/conformance/btrProvenanceBoundary.test.ts (1)
10-10: LGTM!test/conformance/btrSigningBytesOwnership.test.ts (1)
8-8: LGTM!test/conformance/snapshotPublicApiSurface.test.ts (1)
9-9: LGTM!test/unit/domain/publicApiExecutableExamples.test.ts (1)
3-14: LGTM!test/unit/domain/publicReadingSurface.behavior.test.ts (1)
9-9: LGTM!examples/optics.ts (1)
2-12: LGTM!advanced.ts (1)
1-69: LGTM!browser.ts (1)
1-45: LGTM!package.json (1)
4-4: LGTM!Also applies to: 37-56, 169-174
bin/cli/commands/optic.ts (1)
1-1: 🎯 Functional CorrectnessCLI now depends on the deprecated
legacy.tsfacade.
openWarpWorldlineis sourced fromlegacy.ts, which per this PR's other changes is documented as a "migration-only compatibility facade" pointing to the v19 root API. Shipping CLI production code (not test code) against a module intended for migration-only use is a reasonable stopgap if the v19 root doesn't yet expose equivalent worldline functionality, but should be tracked for follow-up migration once the root API supports it.test/unit/cli/optic.test.ts (1)
12-21: LGTM!test/unit/domain/index.exports.test.ts (1)
1-6: 📐 Maintainability & Code Quality | 💤 Low valueStale header comment.
Header still says "Tests for the main index.ts exports" / "supporting ... the package entry point," but the file now imports from
legacy.ts(Lines 9, 143). Update the comment to reflect that this file exercises thelegacy.tscompatibility entrypoint, not the rootindex.ts.test/unit/domain/services/query/BoundedSupportRule.test.ts (1)
6-6: LGTM!test/unit/domain/services/query/CausalIndexPlan.test.ts (1)
1-61: LGTM!diagnostics.ts (1)
1-38: LGTM!test/conformance/v18FirstUseOpticsHonesty.test.ts (1)
4-4: LGTM!test/unit/domain/publicReadApiExecutablePaths.test.ts (1)
3-3: LGTM!test/unit/domain/publicStrandAndRuntimeSeams.test.ts (1)
7-7: LGTM!test/unit/domain/services/merge/TtdMergeInspector.test.ts (1)
7-10: LGTM!test/unit/domain/services/query/SupportFragmentPlan.test.ts (1)
8-8: LGTM!test/unit/index.exports.test.ts (1)
2-21: LGTM!test/unit/scripts/openwarpgraph-composition-root.test.ts (1)
5-5: LGTM!Also applies to: 167-170
storage.ts (1)
1-24: LGTM!jsr.json (1)
10-23: LGTM!tsconfig.publish.json (1)
14-17: LGTM!tsconfig.src.json (1)
6-9: LGTM!test/unit/scripts/v18-package-surface-audit.test.ts (1)
20-104: LGTM!examples/observers.ts (1)
2-12: LGTM!test/unit/scripts/v19-public-api-boundary.test.ts (1)
40-63: 🎯 Functional CorrectnessNo issue here
parseExportBlockalready strips inlinetypemodifiers, soexport { type Bar }is counted correctly.> Likely an incorrect or invalid review comment.src/domain/WarpApp.ts (1)
95-99: LGTM!src/domain/WarpCore.ts (1)
22-24: LGTM!src/domain/WarpWorldline.ts (1)
2-5: LGTM!Also applies to: 158-163
test/unit/domain/WarpCore.apiSurface.test.ts (1)
2-2: LGTM!test/unit/domain/WarpGraph.strands.compare.test.ts (1)
552-552: LGTM!test/unit/domain/WarpWorldline.test.ts (1)
3-3: LGTM!test/unit/scripts/worldline-api-deprecation.test.ts (1)
62-68: LGTM!Also applies to: 70-76, 77-84, 86-95, 96-103
examples/README.md (1)
1-5: LGTM!Also applies to: 14-18
test/conformance/v18BoundedMemoryLargeGraphGate.test.ts (1)
3-3: LGTM!test/conformance/v18CoordinateOpticPublicPath.test.ts (1)
2-2: LGTM!test/type-check/consumer.ts (1)
149-149: LGTM!test/unit/domain/WarpApp.facade.test.ts (1)
3-3: LGTM!test/unit/scripts/public-api-aperture-noun.test.ts (1)
2-9: LGTM!test/unit/scripts/public-api-facade-split.test.ts (1)
6-7: LGTM!test/unit/v7-guards.test.ts (1)
1-15: LGTM!
|
@codex review please Code Lawyer Activity Summary
Validation
Current Gate
|
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 (2)
examples/bounded-reads.ts (1)
5-10: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win"Diagnostic read path" wording now collides with the new
/diagnosticssubpath.The "advanced" → "legacy" wording fix from the prior review was applied, but the file still describes
materializeSlice()as a "diagnostic read path" (unchanged line 6). Since this PR adds a realdiagnostics.tssubpath, this phrasing risks the same migration confusion previously flagged for "advanced" — readers may assume this bounded-cone read belongs on/diagnostics.✏️ Suggested wording fix
- * openWarpGraph() surface; materializeSlice() is a diagnostic read path. + * openWarpGraph() surface; materializeSlice() is a bounded causal-cone read.🤖 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 `@examples/bounded-reads.ts` around lines 5 - 10, Update the comment in examples/bounded-reads.ts so materializeSlice() is no longer described as a “diagnostic read path,” since that wording now conflicts with the new diagnostics subpath. Keep the existing legacy/migration-testing guidance, but rewrite the doc text near the import of GitGraphAdapter and openWarpGraph to make it clear this bounded read path is part of the legacy surface and not related to /diagnostics.test/unit/scripts/v18-package-surface-audit.test.ts (1)
73-81: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueConsider asserting the new
/advancedand/diagnosticssubpaths in the index module doc too.The check only verifies
@git-stunts/git-warp/legacyand@git-stunts/git-warp/storageare mentioned; the PR also introducesadvanced.tsanddiagnostics.tsas part of the same boundary story.🤖 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/unit/scripts/v18-package-surface-audit.test.ts` around lines 73 - 81, The v19 boundary doc test in the package surface audit only checks the existing legacy and storage subpaths, so update the assertion block in the v18 package surface audit test to also verify the index module documentation includes the new /advanced and /diagnostics subpaths. Use the existing indexModuleDoc expectations in this test to add containment checks for the new subpath references alongside `@git-stunts/git-warp/legacy` and `@git-stunts/git-warp/storage`.
🤖 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/index.exports.test.ts`:
- Around line 2-11: This test name is misleading because it validates the legacy
compatibility exports from legacy.ts rather than index.ts. Rename the test file
and any related test description/fixture references to reflect the legacy
compatibility surface, using the existing publicApi import and legacy.ts scope
so it sits logically alongside test/unit/index.exports.test.ts.
---
Outside diff comments:
In `@examples/bounded-reads.ts`:
- Around line 5-10: Update the comment in examples/bounded-reads.ts so
materializeSlice() is no longer described as a “diagnostic read path,” since
that wording now conflicts with the new diagnostics subpath. Keep the existing
legacy/migration-testing guidance, but rewrite the doc text near the import of
GitGraphAdapter and openWarpGraph to make it clear this bounded read path is
part of the legacy surface and not related to /diagnostics.
In `@test/unit/scripts/v18-package-surface-audit.test.ts`:
- Around line 73-81: The v19 boundary doc test in the package surface audit only
checks the existing legacy and storage subpaths, so update the assertion block
in the v18 package surface audit test to also verify the index module
documentation includes the new /advanced and /diagnostics subpaths. Use the
existing indexModuleDoc expectations in this test to add containment checks for
the new subpath references alongside `@git-stunts/git-warp/legacy` and
`@git-stunts/git-warp/storage`.
🪄 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: d2a898b9-0f95-497a-8d6d-153f466a4c35
📒 Files selected for processing (14)
docs/migrations/v19/README.mddocs/topics/api/README.mddocs/topics/reference.mdexamples/bounded-reads.tsindex.tslegacy.tssrc/domain/WarpApp.tssrc/domain/WarpCore.tssrc/domain/WarpGraph.tssrc/domain/WarpWorldline.tstest/unit/domain/index.exports.test.tstest/unit/scripts/v18-package-surface-audit.test.tstest/unit/scripts/v19-public-api-boundary.test.tstest/unit/scripts/worldline-api-deprecation.test.ts
💤 Files with no reviewable changes (1)
- index.ts
📜 Review details
⏰ Context from checks skipped due to timeout. (3)
- GitHub Check: preflight
- GitHub Check: test-node (22)
- GitHub Check: coverage-threshold
🧰 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:
examples/bounded-reads.tssrc/domain/WarpApp.tssrc/domain/WarpGraph.tssrc/domain/WarpWorldline.tssrc/domain/WarpCore.tstest/unit/scripts/v19-public-api-boundary.test.tstest/unit/scripts/v18-package-surface-audit.test.tstest/unit/domain/index.exports.test.tstest/unit/scripts/worldline-api-deprecation.test.tslegacy.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/WarpApp.tssrc/domain/WarpGraph.tssrc/domain/WarpWorldline.tssrc/domain/WarpCore.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/WarpApp.tssrc/domain/WarpGraph.tssrc/domain/WarpWorldline.tssrc/domain/WarpCore.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/WarpApp.tssrc/domain/WarpGraph.tssrc/domain/WarpWorldline.tssrc/domain/WarpCore.ts
🔇 Additional comments (16)
legacy.ts (3)
216-218: Idempotency and default-export concerns from prior review addressed.The added comment clarifies the
installDefaultRuntimeHostNodePorts()side effect is idempotent (and ES module top-level code only runs once per module instance regardless of import count, so this is a non-issue), and the default-export comment now reflects "old migration callers" as suggested.Also applies to: 476-477
14-215: LGTM!Also applies to: 220-260, 261-429
138-138: 🎯 Functional CorrectnessNo change needed:
WarpOpenOptionsis a runtime class, so the value import/export is correct.> Likely an incorrect or invalid review comment.examples/bounded-reads.ts (1)
13-38: LGTM!src/domain/WarpGraph.ts (1)
366-368: LGTM!src/domain/WarpWorldline.ts (1)
2-5: LGTM!Also applies to: 158-163
test/unit/scripts/v18-package-surface-audit.test.ts (2)
62-71: LGTM!Also applies to: 83-106
23-23: 📐 Maintainability & Code QualityThe guard is intentional. The unit-test jobs build first, so this check only skips runs where
dist/index.d.tswas never generated.> Likely an incorrect or invalid review comment.test/unit/domain/index.exports.test.ts (1)
12-143: LGTM!Also applies to: 146-648
docs/migrations/v19/README.md (1)
123-136: LGTM!docs/topics/api/README.md (1)
121-163: LGTM!Also applies to: 254-299
docs/topics/reference.md (1)
37-112: LGTM!src/domain/WarpApp.ts (1)
95-98: LGTM!src/domain/WarpCore.ts (1)
22-24: LGTM!test/unit/scripts/v19-public-api-boundary.test.ts (1)
18-39: LGTM!Also applies to: 111-118
test/unit/scripts/worldline-api-deprecation.test.ts (1)
65-67: LGTM!Also applies to: 70-80, 86-103
Release Preflight
If this PR is from a |
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 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/migrations/v19/README.md`:
- Around line 324-325: The migration steps incorrectly present `write(intent.*)`
and `read(reading.*)` as standalone APIs; update the wording in the README to
use the timeline receiver explicitly. In the migration guide section that
mentions `commit((patch) => ...)`, revise the examples and surrounding text to
reference `timeline.write(...)` and `timeline.read(...)` so the docs match the
public receiver-based API and avoid implying a non-existent entry point.
🪄 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: 69098446-7eb3-4ed6-883b-95613f60347d
📒 Files selected for processing (3)
docs/migrations/v19/README.mddocs/topics/api/README.mddocs/topics/supported-outcome-settlement.md
📜 Review details
🔇 Additional comments (2)
docs/topics/supported-outcome-settlement.md (1)
1-67: LGTM!docs/topics/api/README.md (1)
14-14: LGTM!
Release Preflight
If this PR is from a |
Code Lawyer Addendum
Validation for addendum fixes:
Current gate: review threads are resolved; latest CI and CodeRabbit are still running after |
Release Preflight
If this PR is from a |
1 participant
Summary
Self-review
Test plan
npm run lint:sludgenpm run lint:mdnpm run lint:md:codenpm run lint:docs-topologynpm run lint -- --quietnpm run typecheck:srcnpm run typecheck:testnpm run typecheck:consumernpm run typecheck:policynpm run typecheck:surfacenpx vitest run test/unit/scripts/v18-package-surface-audit.test.ts test/unit/scripts/v19-public-api-boundary.test.ts test/unit/scripts/worldline-api-deprecation.test.ts test/unit/domain/index.exports.test.tsnpm run test:coverage:ciADR checks
docs/topics/api/README.md.docs/migrations/v19/README.md.Validation
Refs #712