Add opt-in Mongo admission commit on Engine submit

.github/workflows/ci.yml

@@ -1115,11 +1115,43 @@ jobs:
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           files: ${{ steps.cov.outputs.files }}
-          name: ts-stack
+          # Make the current attempt distinguishable from a previous rerun of
+          # the same commit when waiting for Codecov to finish processing it.
+          name: ts-stack-${{ github.run_id }}-${{ github.run_attempt }}
           slug: bsv-blockchain/ts-stack
+          # CI checks out GitHub's synthetic PR merge commit but Codecov
+          # reports against the branch head.  Give Codecov the actual base
+          # parent so it does not fall back to its last covered main commit.
+          commit_parent: ${{ github.event.pull_request.base.sha || github.event.before }}
           # Coverage upload is non-blocking: Codecov CLI GPG-verify/outages must not gate CI.
           fail_ci_if_error: false
 
+      - name: Wait for Codecov to merge the uploaded report
+        if: steps.cov.outputs.has-coverage == 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository)
+        env:
+          CODECOV_COMMIT: ${{ github.event.pull_request.head.sha || github.sha }}
+          CODECOV_BUILD_URL: https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}
+          CODECOV_UPLOAD_NAME: ts-stack-${{ github.run_id }}-${{ github.run_attempt }}
+        run: |
+          deadline=$((SECONDS + 300))
+          commit_url="https://api.codecov.io/api/v2/github/bsv-blockchain/repos/ts-stack/commits/${CODECOV_COMMIT}/"
+          uploads_url="${commit_url}uploads/"
+          while true; do
+            if commit=$(curl --fail --silent --show-error --location --proto '=https' --proto-redir '=https' --connect-timeout 5 --max-time 15 "$commit_url") &&
+              [ "$(jq --raw-output '.state // empty' <<<"$commit")" = 'complete' ] &&
+              uploads=$(curl --fail --silent --show-error --location --proto '=https' --proto-redir '=https' --connect-timeout 5 --max-time 15 "$uploads_url") &&
+              [ "$(jq --arg build_url "$CODECOV_BUILD_URL" --arg name "$CODECOV_UPLOAD_NAME" '[.results[]? | select(.build_url == $build_url and .name == $name and .state_name == "MERGED")] | length' <<<"$uploads")" -gt 0 ]; then
+              echo "Codecov merged ${CODECOV_UPLOAD_NAME} for ${CODECOV_COMMIT}."
+              break
+            fi
+
+            if [ "$SECONDS" -ge "$deadline" ]; then
+              echo "::error::Codecov did not merge coverage for ${CODECOV_COMMIT} within five minutes."
+              exit 1
+            fi
+            sleep 5
+          done
+
       - name: Publish finalized Codecov notifications
         if: steps.cov.outputs.has-coverage == 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository)
         uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0

docs/packages/overlays/overlay-discovery-services.md

@@ -4,9 +4,9 @@ title: '@bsv/overlay-discovery-services'
 kind: package
 domain: overlays
 npm: '@bsv/overlay-discovery-services'
-version: '2.2.1'
-last_updated: '2026-08-27'
-last_verified: '2026-08-27'
+version: '2.2.2'
+last_updated: '2026-09-08'
+last_verified: '2026-09-08'
 review_cadence_days: 30
 repo: 'https://github.com/bsv-blockchain/ts-stack/tree/main/packages/overlays/overlay-discovery-services'
 status: stable

docs/packages/overlays/overlay-express.md

@@ -4,9 +4,9 @@ title: '@bsv/overlay-express'
 kind: package
 domain: overlays
 npm: '@bsv/overlay-express'
-version: '2.6.1'
-last_updated: '2026-08-27'
-last_verified: '2026-08-27'
+version: '2.6.2'
+last_updated: '2026-09-08'
+last_verified: '2026-09-08'
 review_cadence_days: 30
 repo: 'https://github.com/bsv-blockchain/ts-stack/tree/main/packages/overlays/overlay-express'
 status: stable

docs/packages/overlays/overlay-topics.md

@@ -4,9 +4,9 @@ title: '@bsv/overlay-topics'
 kind: package
 domain: overlays
 npm: '@bsv/overlay-topics'
-version: '1.7.1'
-last_updated: '2026-08-27'
-last_verified: '2026-08-27'
+version: '1.7.2'
+last_updated: '2026-09-08'
+last_verified: '2026-09-08'
 review_cadence_days: 30
 repo: 'https://github.com/bsv-blockchain/ts-stack/tree/main/packages/overlays/topics'
 status: stable

docs/packages/overlays/overlay.md

@@ -4,9 +4,9 @@ title: '@bsv/overlay'
 kind: package
 domain: overlays
 npm: '@bsv/overlay'
-version: '2.3.1'
-last_updated: '2026-08-27'
-last_verified: '2026-08-27'
+version: '2.4.0'
+last_updated: '2026-09-09'
+last_verified: '2026-09-09'
 review_cadence_days: 30
 repo: 'https://github.com/bsv-blockchain/ts-stack/tree/main/packages/overlays/overlay'
 status: stable
@@ -76,6 +76,37 @@ const result = await engine.lookup({
 - **BASM support** — BRC-136 topic anchors, TAC computation, reorg reconciliation,
   proof refresh, and unproven transaction maintenance
 
+## Optional persistence contracts
+
+The package exports an additive `AdmissionStorage` capability, semantic identity
+helpers and recovery fence/cursor predicates. `storageHasAdmission` reports
+whether the optional `Storage.admission` field is present; `getAdmissionStorage`
+additionally requires the v1 protocol and both commit and reconciliation
+methods. These define the local durable receipt and pending index/propagation
+boundary for future adapters. Current `Engine.submit`, its early STEAK callback
+and Knex storage do not use the capability. See the [persistence v1
+specification](https://github.com/bsv-blockchain/ts-stack/blob/main/specs/overlay/persistence-v1.md)
+for the shared fixtures and explicit limits. No consumer migration is required.
+
+## Optional Mongo foundation
+
+The package also contains an opt-in MongoDB foundation for schema bootstrap,
+content-addressed payload publication, reference guards, and payload collection.
+It is not an Engine integration, an `AdmissionStorage` implementation, or a
+default storage selection; importing `@bsv/overlay` does not load MongoDB.
+
+Applications using a Mongo deep entry point install the optional peer first:
+
+```sh
+npm install @bsv/overlay mongodb@^7.5.0
+```
+
+The initial entry points are `@bsv/overlay/storage/mongo/MongoSchema` and
+`@bsv/overlay/storage/mongo/MongoPayloadStore`. They require an explicitly
+operated unsharded replica set; the supported deployment profile is three
+members. See the [Mongo v1
+foundation](https://github.com/bsv-blockchain/ts-stack/blob/main/specs/overlay/mongo-v1.md).
+
 ## Common patterns
 
 ### Implementing a TopicManager