Skip to content

Commit 19c2066

Browse files
flyingrobotsflyingrobots
authored
Merge pull request #679 from git-stunts/docs/source-backed-reference
docs: add source-backed reference gate
2 parents 615b974 + 28048b3 commit 19c2066

8 files changed

Lines changed: 628 additions & 2 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
55
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
66
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
77

8+
## [Unreleased]
9+
10+
### Added
11+
12+
- Added a generated source-backed reference topic for package entrypoints, root
13+
API exports, CLI commands, structured CLI error output, and public error
14+
classes, plus a docs-topology gate that fails when the reference drifts from
15+
source.
16+
817
## [18.1.1] - 2026-06-25
918

1019
### Release notes

‎README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -194,7 +194,8 @@ mindmap
194194

195195
The topic pages own the current explanations for these nouns. Exact API, CLI,
196196
schema, and error inventories should be generated or coverage-checked rather
197-
than maintained as long-form prose.
197+
than maintained as long-form prose; see the generated
198+
[source-backed reference](docs/topics/reference.md).
198199

199200
> `Optic` is now a reified runtime noun for the public read path. The fluent API lowers into a frozen `Optic` value before execution; see [Optic reads](docs/topics/optic-reads.md).
200201

‎docs/topics/README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,8 @@ lives in the root [CHANGELOG](../../CHANGELOG.md).
3838

3939
- [CLI](cli.md): inspect, validate, debug, and time-travel a live repository.
4040
- [Sync](sync.md): move WARP refs between clones and inspect sync status.
41+
- [Source-backed reference](reference.md): generated API, CLI, entrypoint, and
42+
error inventories with source citations.
4143
- [Troubleshooting](troubleshooting.md): start from symptoms and choose the next
4244
diagnostic check.
4345
- [Operations](../operations/): run checkpoint, GC, index, audit, trust, and

‎docs/topics/reference.md‎

Lines changed: 315 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,315 @@
1+
# Source-backed reference
2+
3+
This page is generated from source code. Do not edit the inventories by hand;
4+
run `node scripts/check-source-backed-reference.ts --write` after changing a
5+
public API export, CLI command, package entrypoint, or public error class.
6+
7+
## Package entrypoints
8+
9+
| Surface | Name | Target | Source |
10+
| --- | --- | --- | --- |
11+
| npm bin | `warp-graph` | `./dist/bin/warp-graph.js` | `package.json#L23` |
12+
| npm bin | `git-warp` | `./bin/git-warp` | `package.json#L24` |
13+
| npm export | `.` | `types=./dist/index.d.ts; import=./dist/index.js; default=./dist/index.js` | `package.json#L27` |
14+
| npm export | `./browser` | `types=./dist/browser.d.ts; import=./dist/browser.js; default=./dist/browser.js` | `package.json#L32` |
15+
| npm export | `./sha1sync` | `types=./dist/src/infrastructure/adapters/sha1sync.d.ts; import=./dist/src/infrastructure/adapters/sha1sync.js; default=./dist/src/infrastructure/adapters/sha1sync.js` | `package.json#L37` |
16+
| npm export | `./package.json` | `./package.json` | `package.json#L42` |
17+
| JSR export | `.` | `./index.ts` | `jsr.json#L8` |
18+
| JSR export | `./browser` | `./browser.ts` | `jsr.json#L9` |
19+
| JSR export | `./sha1sync` | `./src/infrastructure/adapters/sha1sync.ts` | `jsr.json#L10` |
20+
21+
## Root API export modules
22+
23+
| Module | Kind | Source |
24+
| --- | --- | --- |
25+
| `./src/domain/graph/publicGraphSubstrate.ts` | export * | `index.ts#L231` |
26+
| `./src/domain/memory/index.ts` | export * | `index.ts#L232` |
27+
| `./src/continuumExports.ts` | export * | `index.ts#L233` |
28+
29+
## Root API value exports
30+
31+
Source: `index.ts`. Count: 161.
32+
33+
```text
34+
AlfredOperationPolicyAdapter @ index.ts#L238
35+
ApertureOpeningProof @ index.ts#L417
36+
AuditError @ index.ts#L242
37+
BisectService @ index.ts#L283
38+
BitmapIndexBuilder @ index.ts#L277
39+
BitmapIndexReader @ index.ts#L278
40+
BlobStoragePort @ index.ts#L297
41+
BoundedSupportRule @ index.ts#L340
42+
BTR @ index.ts#L406
43+
buildWarpStateIndex @ index.ts#L373
44+
BunHttpAdapter @ index.ts#L307
45+
canonicalEmissionJson @ index.ts#L426
46+
canonicalObservationJson @ index.ts#L428
47+
CasContentEncryptionPolicy @ index.ts#L236
48+
CausalIndexPlan @ index.ts#L341
49+
checkAborted @ index.ts#L314
50+
ChunkEffectSink @ index.ts#L437
51+
CommitDagTraversalService @ index.ts#L282
52+
compareVisibleState @ index.ts#L377
53+
composeWormholes @ index.ts#L413
54+
computeStateHash @ index.ts#L374
55+
computeTranslationCost @ index.ts#L354
56+
ConsoleEffectSink @ index.ts#L436
57+
ConsoleLogger @ index.ts#L290
58+
CONTENT_PROPERTY_KEY @ index.ts#L369
59+
ContentAttachmentProjection @ index.ts#L439
60+
ContinuumArtifactAuthorityError @ index.ts#L243
61+
CoordinateSelector @ index.ts#L338
62+
createBlobValue @ index.ts#L363
63+
createBTR @ index.ts#L407
64+
createDeliveryObservation @ index.ts#L427
65+
createEdgeAdd @ index.ts#L359
66+
createEdgeTombstone @ index.ts#L360
67+
createEffectEmission @ index.ts#L425
68+
createExternalizationPolicy @ index.ts#L429
69+
createInlineValue @ index.ts#L362
70+
createNodeAdd @ index.ts#L357
71+
createNodeTombstone @ index.ts#L358
72+
createPropSet @ index.ts#L361
73+
createStateReader @ index.ts#L376
74+
createTickReceipt @ index.ts#L397
75+
createTimeoutSignal @ index.ts#L315
76+
createV18BoundedMemoryCapabilityReport @ index.ts#L394
77+
createWormhole @ index.ts#L412
78+
CryptoPort @ index.ts#L299
79+
decodeEdgePropKey @ index.ts#L367
80+
DELIVERY_MODES @ index.ts#L430
81+
DELIVERY_OUTCOMES @ index.ts#L431
82+
DenoHttpAdapter @ index.ts#L308
83+
deserializeWormhole @ index.ts#L416
84+
EffectPipeline @ index.ts#L424
85+
EffectSinkPort @ index.ts#L422
86+
encodeEdgePropKey @ index.ts#L366
87+
EncryptionError @ index.ts#L244
88+
exportCoordinateComparisonFact @ index.ts#L392
89+
exportCoordinateTransferPlanFact @ index.ts#L393
90+
ForkError @ index.ts#L245
91+
GitGraphAdapter @ index.ts#L273
92+
GraphDiff @ index.ts#L378
93+
GraphNode @ index.ts#L275
94+
GraphOpAlgebraProjection @ index.ts#L276
95+
GraphPersistencePort @ index.ts#L284
96+
HealthCheckService @ index.ts#L280
97+
HealthStatus @ index.ts#L281
98+
HttpServerPort @ index.ts#L300
99+
ImmutableBytes @ index.ts#L386
100+
IndexError @ index.ts#L246
101+
IndexRebuildService @ index.ts#L279
102+
IndexStoragePort @ index.ts#L285
103+
InMemoryBlobStorageAdapter @ index.ts#L298
104+
InMemoryGraphAdapter @ index.ts#L274
105+
INSPECT_LENS @ index.ts#L434
106+
isEdgePropKey @ index.ts#L368
107+
LIVE_LENS @ index.ts#L432
108+
LiveSelector @ index.ts#L337
109+
LoggerPort @ index.ts#L288
110+
LogLevel @ index.ts#L291
111+
MemoryBudgetError @ index.ts#L247
112+
MultiplexSink @ index.ts#L423
113+
NodeCryptoAdapter @ index.ts#L303
114+
NoOpEffectSink @ index.ts#L435
115+
NoOpLogger @ index.ts#L289
116+
NoopOperationPolicyAdapter @ index.ts#L239
117+
normalizeVisibleStateScope @ index.ts#L390
118+
Observer @ index.ts#L344
119+
ObserverAccumulation @ index.ts#L345
120+
ObserverBasis @ index.ts#L346
121+
ObserverEmission @ index.ts#L347
122+
ObserverPlan @ index.ts#L348
123+
ObserverReadingEnvelope @ index.ts#L349
124+
openAperture @ index.ts#L419
125+
openWarpGraph @ index.ts#L319
126+
openWarpWorldline @ index.ts#L322
127+
OperationAbortedError @ index.ts#L248
128+
OperationPolicyExhaustedError @ index.ts#L240
129+
OperationPolicyPort @ index.ts#L234
130+
OperationPolicyTimeoutError @ index.ts#L240
131+
Optic @ index.ts#L326
132+
OpticAperturePosture @ index.ts#L327
133+
OpticBasisPosture @ index.ts#L328
134+
OpticCoordinatePosture @ index.ts#L329
135+
OpticSupportRule @ index.ts#L330
136+
PatchBuilder @ index.ts#L350
137+
PatchError @ index.ts#L249
138+
PatchSession @ index.ts#L351
139+
ProjectionHandle @ index.ts#L331
140+
projectState @ index.ts#L375
141+
ProvenanceIndex @ index.ts#L353
142+
ProvenancePayload @ index.ts#L403
143+
QueryBuilder @ index.ts#L343
144+
QueryError @ index.ts#L250
145+
RejectedApertureOpening @ index.ts#L417
146+
RejectedZKWormhole @ index.ts#L417
147+
REPLAY_LENS @ index.ts#L433
148+
replayBTR @ index.ts#L409
149+
replayWormhole @ index.ts#L414
150+
SchemaUnsupportedError @ index.ts#L251
151+
scopeMaterializedState @ index.ts#L391
152+
SeekCachePort @ index.ts#L294
153+
serializeWormhole @ index.ts#L415
154+
ShardCorruptionError @ index.ts#L252
155+
ShardLoadError @ index.ts#L253
156+
ShardValidationError @ index.ts#L254
157+
SnapshotORSet @ index.ts#L387
158+
SnapshotVersionVector @ index.ts#L388
159+
SnapshotWarpState @ index.ts#L389
160+
StorageError @ index.ts#L255
161+
StrandError @ index.ts#L256
162+
StrandSelector @ index.ts#L339
163+
SupportFragmentPlan @ index.ts#L342
164+
SyncError @ index.ts#L257
165+
SyncSecret @ index.ts#L438
166+
TICK_RECEIPT_OP_TYPES @ index.ts#L399
167+
TICK_RECEIPT_RESULT_TYPES @ index.ts#L400
168+
tickReceiptCanonicalJson @ index.ts#L398
169+
TraversalError @ index.ts#L258
170+
TtdMergeBranch @ index.ts#L379
171+
TtdMergeFootprint @ index.ts#L380
172+
TtdMergeInspection @ index.ts#L381
173+
TtdMergeInspector @ index.ts#L382
174+
TtdMergeLoweringWitness @ index.ts#L383
175+
TtdMergeObstructionWitness @ index.ts#L384
176+
TtdMergePolicyRequirement @ index.ts#L385
177+
VerifiedApertureOpening @ index.ts#L418
178+
VerifiedZKWormhole @ index.ts#L418
179+
verifyBTR @ index.ts#L408
180+
verifyZKWormhole @ index.ts#L419
181+
WarpApp @ index.ts#L334
182+
WarpCore @ index.ts#L335
183+
WarpOpenOptions @ index.ts#L318
184+
WarpStateIndexBuilder @ index.ts#L372
185+
WarpWorldline @ index.ts#L323
186+
WarpWorldlineCoordinate @ index.ts#L324
187+
WarpWorldlineOpticBasis @ index.ts#L325
188+
WebCryptoAdapter @ index.ts#L304
189+
WorldlineSelector @ index.ts#L336
190+
WormholeError @ index.ts#L259
191+
Writer @ index.ts#L352
192+
WriterError @ index.ts#L311
193+
ZKWormholeEdge @ index.ts#L418
194+
ZKWormholeProofVerifierPort @ index.ts#L419
195+
```
196+
197+
## Root API type exports
198+
199+
Source: `index.ts`. Count: 51.
200+
201+
```text
202+
Aperture @ index.ts#L443
203+
ApertureOpeningProofFields @ index.ts#L472
204+
ApertureOpeningVerificationResult @ index.ts#L472
205+
BoundedSupportDirection @ index.ts#L458
206+
BoundedSupportKind @ index.ts#L459
207+
BoundedSupportRuleFields @ index.ts#L460
208+
BoundedSupportSurface @ index.ts#L461
209+
CasContentEncryptionDiagnostics @ index.ts#L237
210+
CasContentEncryptionScheme @ index.ts#L237
211+
CasResolvedVaultKeyOptions @ index.ts#L237
212+
CasVaultResolutionWitness @ index.ts#L237
213+
CausalIndexFamily @ index.ts#L462
214+
CausalIndexPlanFields @ index.ts#L463
215+
CausalIndexPlanPosture @ index.ts#L464
216+
GraphDiffFields @ index.ts#L468
217+
GraphDiffOptions @ index.ts#L467
218+
ObserverConfig @ index.ts#L444
219+
ObserverPlanFields @ index.ts#L469
220+
ObserverReadingEnvelopeBudget @ index.ts#L470
221+
ObserverReadingEnvelopeFields @ index.ts#L471
222+
OperationPolicyExecuteOptions @ index.ts#L235
223+
OperationRetryDecision @ index.ts#L235
224+
OperationRetryObserver @ index.ts#L235
225+
OpticAperturePostureValue @ index.ts#L451
226+
OpticBasisPostureValue @ index.ts#L452
227+
OpticContextValue @ index.ts#L453
228+
OpticCoordinatePostureValue @ index.ts#L454
229+
OpticFields @ index.ts#L455
230+
OpticPostureFields @ index.ts#L456
231+
OpticSupportRuleValue @ index.ts#L457
232+
PropValue @ index.ts#L445
233+
SnapshotPropValue @ index.ts#L446
234+
SupportFragmentMaterializationPosture @ index.ts#L465
235+
SupportFragmentPlanFields @ index.ts#L466
236+
SyncRateLimitConfig @ index.ts#L447
237+
TtdMergeBranchFields @ index.ts#L475
238+
TtdMergeFootprintFields @ index.ts#L476
239+
TtdMergeInspectionDomain @ index.ts#L477
240+
TtdMergeInspectionFields @ index.ts#L478
241+
TtdMergeLoweringSurface @ index.ts#L479
242+
TtdMergeLoweringWitnessFields @ index.ts#L480
243+
TtdMergeObjectBranchInput @ index.ts#L481
244+
TtdMergeObjectInspectionInput @ index.ts#L482
245+
TtdMergeObstructionWitnessFields @ index.ts#L483
246+
TtdMergePolicyRequirementFields @ index.ts#L484
247+
WarpKernelPort @ index.ts#L448
248+
WarpWorldlineCoordinateFrontierEntry @ index.ts#L474
249+
WarpWorldlineOpenOptions @ index.ts#L449
250+
WarpWorldlinePatchBuild @ index.ts#L450
251+
ZKWormholeEdgeFields @ index.ts#L473
252+
ZKWormholeVerificationResult @ index.ts#L473
253+
```
254+
255+
## CLI command registry
256+
257+
| Command | Handler | Source |
258+
| --- | --- | --- |
259+
| `info` | `handleInfo` | `bin/cli/commands/registry.ts#L42` |
260+
| `check` | `handleCheck` | `bin/cli/commands/registry.ts#L43` |
261+
| `doctor` | `handleDoctor` | `bin/cli/commands/registry.ts#L44` |
262+
| `materialize` | `handleMaterialize` | `bin/cli/commands/registry.ts#L45` |
263+
| `seek` | `handleSeek` | `bin/cli/commands/registry.ts#L46` |
264+
| `query` | `handleQuery` | `bin/cli/commands/registry.ts#L47` |
265+
| `path` | `handlePath` | `bin/cli/commands/registry.ts#L48` |
266+
| `optic` | `handleOptic` | `bin/cli/commands/registry.ts#L49` |
267+
| `history` | `handleHistory` | `bin/cli/commands/registry.ts#L50` |
268+
| `debug` | `handleDebug` | `bin/cli/commands/registry.ts#L51` |
269+
| `strand` | `handleStrand` | `bin/cli/commands/registry.ts#L52` |
270+
| `verify-audit` | `handleVerifyAudit` | `bin/cli/commands/registry.ts#L53` |
271+
| `verify-index` | `handleVerifyIndex` | `bin/cli/commands/registry.ts#L54` |
272+
| `reindex` | `handleReindex` | `bin/cli/commands/registry.ts#L55` |
273+
| `trust` | `handleTrust` | `bin/cli/commands/registry.ts#L56` |
274+
| `patch` | `handlePatch` | `bin/cli/commands/registry.ts#L57` |
275+
| `tree` | `handleTree` | `bin/cli/commands/registry.ts#L58` |
276+
| `bisect` | `handleBisect` | `bin/cli/commands/registry.ts#L59` |
277+
| `install-hooks` | `handleInstallHooks` | `bin/cli/commands/registry.ts#L60` |
278+
| `mcp` | `handleMcp` | `bin/cli/commands/registry.ts#L61` |
279+
| `sync` | `handleSync` | `bin/cli/commands/registry.ts#L62` |
280+
| `serve` | `handleServe` | `bin/cli/commands/registry.ts#L63` |
281+
| `fork` | `handleFork` | `bin/cli/commands/registry.ts#L64` |
282+
| `checkpoint` | `handleCheckpoint` | `bin/cli/commands/registry.ts#L65` |
283+
| `gc` | `handleGc` | `bin/cli/commands/registry.ts#L66` |
284+
| `watch` | `handleWatch` | `bin/cli/commands/registry.ts#L67` |
285+
286+
Structured CLI errors for `--json` and `--ndjson` use the payload shape
287+
`{ error: { code, message, cause? } }` from the CLI entry point.
288+
289+
Source: `bin/warp-graph.ts#L129`.
290+
291+
## Public error classes
292+
293+
| Class | Module | Source |
294+
| --- | --- | --- |
295+
| `AuditError` | `./AuditError.ts` | `src/domain/errors/index.ts#L3` |
296+
| `ContinuumArtifactAuthorityError` | `./ContinuumArtifactAuthorityError.ts` | `src/domain/errors/index.ts#L4` |
297+
| `EncryptionError` | `./EncryptionError.ts` | `src/domain/errors/index.ts#L5` |
298+
| `ForkError` | `./ForkError.ts` | `src/domain/errors/index.ts#L6` |
299+
| `IndexError` | `./IndexError.ts` | `src/domain/errors/index.ts#L7` |
300+
| `MemoryBudgetError` | `./MemoryBudgetError.ts` | `src/domain/errors/index.ts#L8` |
301+
| `OperationAbortedError` | `./OperationAbortedError.ts` | `src/domain/errors/index.ts#L9` |
302+
| `OperationPolicyExhaustedError` | `./OperationPolicyExhaustedError.ts` | `src/domain/errors/index.ts#L10` |
303+
| `OperationPolicyTimeoutError` | `./OperationPolicyTimeoutError.ts` | `src/domain/errors/index.ts#L11` |
304+
| `PatchError` | `./PatchError.ts` | `src/domain/errors/index.ts#L12` |
305+
| `QueryError` | `./QueryError.ts` | `src/domain/errors/index.ts#L13` |
306+
| `SyncError` | `./SyncError.ts` | `src/domain/errors/index.ts#L14` |
307+
| `ShardCorruptionError` | `./ShardCorruptionError.ts` | `src/domain/errors/index.ts#L15` |
308+
| `ShardIdOverflowError` | `./ShardIdOverflowError.ts` | `src/domain/errors/index.ts#L16` |
309+
| `ShardLoadError` | `./ShardLoadError.ts` | `src/domain/errors/index.ts#L17` |
310+
| `ShardValidationError` | `./ShardValidationError.ts` | `src/domain/errors/index.ts#L18` |
311+
| `StorageError` | `./StorageError.ts` | `src/domain/errors/index.ts#L19` |
312+
| `SchemaUnsupportedError` | `./SchemaUnsupportedError.ts` | `src/domain/errors/index.ts#L20` |
313+
| `TraversalError` | `./TraversalError.ts` | `src/domain/errors/index.ts#L21` |
314+
| `StrandError` | `./StrandError.ts` | `src/domain/errors/index.ts#L22` |
315+
| `WormholeError` | `./WormholeError.ts` | `src/domain/errors/index.ts#L23` |

‎package.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,11 +60,12 @@
6060
"lint:ratchet": "sh scripts/lint-ratchet.sh",
6161
"lint:md": "markdownlint \"**/*.md\" --ignore node_modules --ignore \"**/node_modules/**\"",
6262
"lint:md:code": "node scripts/lint-markdown-code-samples.ts",
63-
"lint:docs-topology": "bash scripts/check-docs-topology.sh",
63+
"lint:docs-topology": "bash scripts/check-docs-topology.sh && npm run lint:source-backed-reference",
6464
"lint:links": "lychee --config .lychee.toml '**/*.md'",
6565
"lint:semgrep": "node scripts/lint-semgrep-with-quarantines.ts",
6666
"lint:sludge": "bash scripts/check-anti-sludge.sh",
6767
"lint:source-size": "node scripts/source-size-gate.ts",
68+
"lint:source-backed-reference": "node scripts/check-source-backed-reference.ts",
6869
"lint:source-version-names": "node scripts/source-version-name-policy.ts",
6970
"lint:contamination": "node scripts/contamination-map.ts",
7071
"lint:quarantine-graduate": "node scripts/quarantine-graduate-check.ts",

‎scripts/check-docs-topology.sh‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ REQUIRED_DOCS=(
1919
"docs/topics/continuum-boundary.md"
2020
"docs/topics/sync.md"
2121
"docs/topics/cli.md"
22+
"docs/topics/reference.md"
2223
"docs/topics/troubleshooting.md"
2324
)
2425

0 commit comments

Comments
 (0)