docs(checks): close resolved TBDs in data-storage, events, README#481
Open
docs(checks): close resolved TBDs in data-storage, events, README#481
Conversation
Items previously marked TBD that are now implemented in code: - data-storage.md assertions #3, #5, #6, #7 (pieceConfirmed, IPNI discoverability, retrievability, all-checks-gated) -> Yes. - data-storage.md poll intervals: replace TBD_VARIABLE refs with the concrete sources (hardcoded POLLING_INTERVAL_MS = 2.5s for SP piece status, IPNI_VERIFICATION_POLLING_MS env var with 2s default for IPNI verification; doc previously claimed 5s). - data-storage.md section 7 header drops TBD; intro disclaimer removed. - data-storage.md "TBD Summary" rewritten as "Implementation History" with code references for inline retrieval, CID integrity, per-deal timeout (AbortController -> DealStatus.FAILED), gated status, status model, onPieceConfirmed, IPFS gateway retrieval, filecoin-pin CAR. - events-and-metrics.md: pieceConfirmed -> Yes (pieceConfirmedOnChainMs histogram); ipfsRetrievalIntegrityChecked -> implemented inline via per-block sha256 verification in ipfs-block.strategy.ts (no discrete event); ipfsRetrievalFirstByte/LastByteReceived marked Partial since duration histograms exist but no discrete event; histogram-buckets TBD replaced with link to metrics-prometheus.module.ts. - README.md: name the dataset-creation job (data-set-creation) and reference its config envs. Still TBD (not changed in this commit): uploadToSpStart, ipniVerificationStart, ipfsRetrievalStart events; jobs.md PR #263 lookahead-skip; PDP_SUBGRAPH_ENDPOINT production value.
Contributor
There was a problem hiding this comment.
Pull request overview
Updates docs/checks/ to close out previously-marked TBDs by reflecting what is already implemented in the backend (events, metrics, polling intervals, and dataset-creation job naming/config).
Changes:
- Mark several Data Storage assertions as implemented; replace placeholder poll-interval TBDs with concrete config/constants.
- Update Events & Metrics documentation to reflect implemented on-chain confirmation + retrieval integrity behavior and point histogram buckets to the Prometheus metrics module.
- Update checks README to name the dataset creation job and list its relevant configuration env vars.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
| docs/checks/events-and-metrics.md | Updates event/metric implementation status and references (piece confirmation, retrieval integrity, histogram bucket source). |
| docs/checks/data-storage.md | Marks previously-TBD assertions as implemented; documents actual polling intervals and adds “Implementation History”. |
| docs/checks/README.md | Documents the dataset-creation job and its configuration knobs. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- data-storage.md: rename Synapse callbacks to plural form (onPiecesAdded, onPiecesConfirmed) to match deal.service.ts. - events-and-metrics.md: same rename in the event list. Clarify that dealCreated maps to DealStatus.DEAL_CREATED only after all gates pass (upload alone sets UPLOADED, not DEAL_CREATED). - events-and-metrics.md: ipfsRetrievalIntegrityChecked downgraded from Yes to Partial since no discrete event is emitted (inline check only). - events-and-metrics.md: Mermaid timeline now matches the table - ipfsRetrievalFirstByteReceived/LastByteReceived labelled as "Partial: histogram only", ipfsRetrievalIntegrityChecked labelled "Partial: inline check, no event". - README.md: refer to the canonical pg-boss job type data_set_creation (underscore) so operators can map the doc to jobType values.
The 'Data Storage Only' rect used rgb(50, 50, 50), which renders as a near-black block that hides the message labels and arrows inside it (both on GitHub light/dark themes). Switch to a translucent rgba(120, 120, 200, 0.15) so the highlight is visible without obscuring content.
The 'events' in this doc are named anchors used to define metric Timer Starts/Ends; dealbot does not necessarily emit each as a discrete Prometheus event or log line. Add an explicit note up top so readers don't expect every entry to map to an emitted event, and update rows that were marked TBD/Partial purely because no discrete event is emitted. - uploadToSpStart -> Yes (anchor: deal.uploadStartTime in deal.service.ts:255). - ipniVerificationStart -> Yes (anchor: ipniVerificationStartTime in ipni-verification.service.ts:63 - drives ipniVerifyMs). - ipfsRetrievalStart -> Yes (anchor: retrieval startTime in retrieval-addons.service.ts:227; logs 'retrieval_started'). - ipfsRetrievalFirstByteReceived -> Yes (drives ipfsRetrievalFirstByteMs). - ipfsRetrievalLastByteReceived -> Yes (drives ipfsRetrievalLastByteMs). - ipfsRetrievalIntegrityChecked -> Yes (per-block sha256 in ipfs-block.strategy.ts; inline, no discrete event). - Mermaid timeline: drop the (TBD) / (Partial: ...) annotations on these markers so the diagram and the table agree.
All rows are now Yes (each marker is anchored in code), so the column adds no signal. Anchor details folded into the Source-of-truth column. Intro note tightened.
silent-cipher
approved these changes
Apr 28, 2026
| | Per-deal max time limit | Done — `DEAL_JOB_TIMEOUT_SECONDS` triggers an `AbortController` in `jobs.service.ts`; on abort the deal is set to `DealStatus.FAILED` with failure-status metrics emitted. | | ||
| | Deal gated on all checks | Done — deal only reaches `DealStatus.DEAL_CREATED` after upload, onchain, IPNI, and retrieval all succeed. | | ||
| | Status model update | Done — `DealStatus` includes `PIECE_CONFIRMED`, `DEAL_CREATED`, `FAILED`; `IpniStatus` includes `SP_INDEXED`, `SP_ADVERTISED`, `VERIFIED`, `FAILED`; `RetrievalStatus` enum exists. | | ||
| | `onPieceConfirmed` callback tracking | Done — `piecesConfirmedTime` recorded, `pieceConfirmedOnChainMs` histogram emitted, `DealStatus.PIECE_CONFIRMED` state exists. | |
Collaborator
There was a problem hiding this comment.
Suggested change
| | `onPieceConfirmed` callback tracking | Done — `piecesConfirmedTime` recorded, `pieceConfirmedOnChainMs` histogram emitted, `DealStatus.PIECE_CONFIRMED` state exists. | | |
| | `onPiecesConfirmed` progress event tracking | Done — `piecesConfirmedTime` recorded, `pieceConfirmedOnChainMs` histogram emitted, `DealStatus.PIECE_CONFIRMED` state exists. | |
| ## Datasets for Checks | ||
|
|
||
| Dealbot manages a set of datasets to use for its checks. Creating these datasets is a precondition before the "data storage" check can run. This is handled by **TBD** job ([tracking issue](https://github.com/FilOzone/dealbot/issues/284)) when it discovers a new SP to measure from the registry. | ||
| Dealbot manages a set of datasets to use for its checks. Creating these datasets is a precondition before the "data storage" check can run. This is handled by the canonical `data_set_creation` job type (see [`jobs.md`](../jobs.md), [tracking issue](https://github.com/FilOzone/dealbot/issues/284)) when it discovers a new SP to measure from the registry. Configured by `DATASET_CREATIONS_PER_SP_PER_HOUR` and `DATA_SET_CREATION_JOB_TIMEOUT_SECONDS`. |
Collaborator
There was a problem hiding this comment.
Suggested change
| Dealbot manages a set of datasets to use for its checks. Creating these datasets is a precondition before the "data storage" check can run. This is handled by the canonical `data_set_creation` job type (see [`jobs.md`](../jobs.md), [tracking issue](https://github.com/FilOzone/dealbot/issues/284)) when it discovers a new SP to measure from the registry. Configured by `DATASET_CREATIONS_PER_SP_PER_HOUR` and `DATA_SET_CREATION_JOB_TIMEOUT_SECONDS`. | |
| Dealbot manages a set of datasets to use for its checks. Creating these datasets is a precondition before the "data storage" check can run. This is handled by the canonical `data_set_creation` job type (see [`jobs.md`](../jobs.md) when it discovers a new SP to measure from the registry. Configured by `DATASET_CREATIONS_PER_SP_PER_HOUR` and `DATA_SET_CREATION_JOB_TIMEOUT_SECONDS`. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes out TBD items in
docs/checks/that have already been implemented in code. Each closure was verified against the current source.Verified done (this PR)
Yes. Code refs:pieceConfirmedOnChainMshistogram,DealStatus.PIECE_CONFIRMED(deal.service.ts:386).ipniVerifyMs+IpniStatus.VERIFIED(ipni.strategy.ts,ipni-verification.service.ts).deal.service.ts:454(testAllRetrievalMethods); deal throws on failure.DEAL_CREATEDafter all sub-checks pass;dataStorageCheckMsemitted.onPiecesAdded,onPiecesConfirmed) to matchdeal.service.ts:345,370.TBD_VARIABLEpoll-interval refs replaced:POLLING_INTERVAL_MS = 2500inipni.strategy.ts:46.IPNI_VERIFICATION_POLLING_MS(default2000, was incorrectly documented as 5s).— **TBD**; intro disclaimer removed.## TBD Summaryrewritten as## Implementation Historywith code references for: inline retrieval verification, CID-based content verification (per-block sha256 viacreateBlockinipfs-block.strategy.ts:230), per-deal max time limit (AbortController injobs.service.ts:443→DealStatus.FAILEDatdeal.service.ts:515), gated status, status model,onPieceConfirmed, IPFS gateway retrieval,filecoin-pinCAR conversion.uploadToSpStart→ Yes (anchor:deal.uploadStartTimeatdeal.service.ts:255).ipniVerificationStart→ Yes (anchor:ipniVerificationStartTimeatipni-verification.service.ts:63, drivesipniVerifyMs).ipfsRetrievalStart→ Yes (anchor: retrievalstartTimeatretrieval-addons.service.ts:227; logsretrieval_started).ipfsRetrievalFirstByteReceived/LastByteReceived→ Yes (drive the matching histograms).ipfsRetrievalIntegrityChecked→ Yes (per-block sha256 inipfs-block.strategy.ts; inline, no discrete event).pieceConfirmed→ Yes (onPiecesConfirmed→pieceConfirmedOnChainMs).dealCreatedclarified —DEAL_CREATEDonly after all gates; upload alone setsUPLOADED.metrics-prometheus.module.ts.rgb(50, 50, 50)rect fill swapped for translucentrgba(120, 120, 200, 0.15).data_set_creation) with config envs.Still TBD (not addressed here)
jobs.md:64: PR feat: cap deal/retrievals with abort signals #263 lookahead-skip for upcoming maintenance windows is not implemented.getMaintenanceWindowStatusonly checks if a window is currently active. Either implement or rewrite the doc.production-configuration-and-approval-methodology.md:43:PDP_SUBGRAPH_ENDPOINTproduction value — needs deployment-config access (not in this repo).Tracking: #280
Test plan
IPNI_VERIFICATION_POLLING_MSdefault reads as2000inapp.config.ts:137POLLING_INTERVAL_MSconstant inipni.strategy.ts