docs(protocol): catalogue the -32016 PUSH_PENDING_LIMITED push-bound error

docs/support/error-codes.md

@@ -27,7 +27,7 @@ This catalog is also published as [`error-codes.json`](https://docs.dig.net/erro
 
 ## dig RPC (JSON-RPC)
 
-The [dig RPC](../protocol/dig-rpc.md) uses the standard [JSON-RPC 2.0](https://www.jsonrpc.org/specification) error codes plus the protocol-specific `-32004`, `-32005`, the node-profile `-32006` / `-32007` / `-32008` / `-32009`, the shell/staging codes `-32010` (upstream) and `-32011`–`-32014` (`dig.stage`), the metadata-response bound `-32015` (`dig.getMetadata`), the [private-retrieval](../protocol/onion-routing.md) codes `-32020` / `-32021` / `-32022`, the local control-plane codes `-32030` / `-32031` / `-32032`, and the wallet-balance read codes `-32040`–`-32043`. A content **miss is never an error** — the capsule returns its own indistinguishable, non-verifying response (there is no `decoy` field on the wire), and the client discovers the miss by inclusion-proof and/or decryption failure (see [the blind host model](../protocol/blind-host-model.md)). For any well-formed body the HTTP status is `200`; the error is carried in the JSON envelope.
+The [dig RPC](../protocol/dig-rpc.md) uses the standard [JSON-RPC 2.0](https://www.jsonrpc.org/specification) error codes plus the protocol-specific `-32004`, `-32005`, the node-profile `-32006` / `-32007` / `-32008` / `-32009`, the shell/staging codes `-32010` (upstream) and `-32011`–`-32014` (`dig.stage`), the metadata-response bound `-32015` (`dig.getMetadata`), the push-reassembly bound `-32016` (`cache.pushCapsule`), the [private-retrieval](../protocol/onion-routing.md) codes `-32020` / `-32021` / `-32022`, the local control-plane codes `-32030` / `-32031` / `-32032`, and the wallet-balance read codes `-32040`–`-32043`. A content **miss is never an error** — the capsule returns its own indistinguishable, non-verifying response (there is no `decoy` field on the wire), and the client discovers the miss by inclusion-proof and/or decryption failure (see [the blind host model](../protocol/blind-host-model.md)). For any well-formed body the HTTP status is `200`; the error is carried in the JSON envelope.
 
 | Code | Meaning | What to do |
 |---|---|---|
@@ -48,6 +48,7 @@ The [dig RPC](../protocol/dig-rpc.md) uses the standard [JSON-RPC 2.0](https://w
 | `-32013` | **Stage: content exceeds the capsule size cap** — the staged content is over the size limit. | Reduce the content to within the capsule size cap. |
 | `-32014` | **Stage: compile/IO failure** — building the module hit a compile or IO error. | Check the source + disk; re-run with `--verbose` for detail. |
 | `-32015` | **Metadata too large** — a [`dig.getMetadata`](../rpc/methods.md#diggetmetadata) capsule's publisher metadata section is larger than the 3 MiB response ceiling. This section is returned whole (it cannot be paged like content), and its `custom`/`links` fields are publisher-controlled, so an oversized section is refused with this bounded error rather than returned as one very large response. A normal store's metadata is well within the ceiling. | Read the store's public file surface with [`dig.getManifest`](../rpc/methods.md#diggetmanifest) / individual files with [`dig.getContent`](../protocol/dig-rpc.md) instead of the whole metadata blob; if you publish, keep the metadata `custom`/`links` fields small. |
+| `-32016` | **Push pending-reassembly limit reached** — [`cache.pushCapsule`](../run-a-node/manage.md#cache-pushcapsule) refused this window: the node's in-flight pending-reassembly bound is exceeded (a per-requestor or global concurrent-push cap, the global pending-bytes budget, or an abandoned-partial TTL). | Wait for your in-flight pushes to complete, then retry the window. |
 | `-32020` | **Onion circuit unavailable** — a [`mode:"privacy"`](../protocol/onion-routing.md) content read could not be served privately (no circuit could be built, or one died mid-fetch). The node **fails closed** rather than downgrading to a direct fetch — a silent downgrade would deanonymize the very reader who asked for privacy. | Retry (a fresh circuit may build); or explicitly choose a fast `mode:"speed"` fetch if you accept revealing the read. |
 | `-32021` | **Privacy requires a local node** — [`mode:"privacy"`](../protocol/onion-routing.md#toggle-placement) was requested but the caller is not the node's own trusted local originator. A node will not fetch privately for a remote/anonymous caller (that would hand it the caller's identity and query). | Run a local DIG node (in-process browser node or the OS-service node on loopback) and issue the private read to it. |
 | `-32022` | **Onion hop count out of range** — the requested [`privacy.hops`](../protocol/onion-routing.md#modes) (circuit length) is outside the allowed range `[2, 5]` (default 3). | Request a hop count within `[2, 5]`. |

package.json

@@ -1,6 +1,6 @@
 {
   "name": "docs-dig-net",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "private": true,
   "scripts": {
     "docusaurus": "docusaurus",

scripts/dig-spec.mjs

@@ -1010,6 +1010,12 @@ export const rpcErrors = {
     meaning:
       "dig.getMetadata refused: the capsule's publisher metadata section renders larger than the 3 MiB response ceiling. The section is returned WHOLE (it cannot be paged like content) and its custom/links fields are publisher-controlled, so an oversized section is refused with this bounded error rather than returned as one very large response. A normal store's metadata is well within the ceiling.",
   },
+  PUSH_PENDING_LIMITED: {
+    code: -32016,
+    message: "Push pending-reassembly limit reached",
+    meaning:
+      "cache.pushCapsule refused this window: the node's in-flight pending-reassembly bound is exceeded (a per-requestor concurrent-push cap, a global concurrent-push cap, the global pending-bytes budget, or an abandoned-partial TTL). Returned by the node-profile cache.pushCapsule. Retriable once in-flight pushes complete.",
+  },
   ONION_CIRCUIT_UNAVAILABLE: {
     code: -32020,
     message: "Onion circuit unavailable",

static/error-codes.json

@@ -129,6 +129,13 @@
       "http_or_exit": 200,
       "description": "Metadata too large — dig.getMetadata refused: the capsule's publisher metadata section renders larger than the 3 MiB response ceiling. The section is returned WHOLE (it cannot be paged like content) and its custom/links fields are publisher-controlled, so an oversized section is refused with this bounded error rather than returned as one very large response. A normal store's metadata is well within the ceiling."
     },
+    {
+      "surface": "dig-rpc",
+      "code": -32016,
+      "name": "PUSH_PENDING_LIMITED",
+      "http_or_exit": 200,
+      "description": "Push pending-reassembly limit reached — cache.pushCapsule refused this window: the node's in-flight pending-reassembly bound is exceeded (a per-requestor concurrent-push cap, a global concurrent-push cap, the global pending-bytes budget, or an abandoned-partial TTL). Returned by the node-profile cache.pushCapsule. Retriable once in-flight pushes complete."
+    },
     {
       "surface": "dig-rpc",
       "code": -32020,
@@ -584,6 +591,13 @@
         "http_or_exit": 200,
         "description": "Metadata too large — dig.getMetadata refused: the capsule's publisher metadata section renders larger than the 3 MiB response ceiling. The section is returned WHOLE (it cannot be paged like content) and its custom/links fields are publisher-controlled, so an oversized section is refused with this bounded error rather than returned as one very large response. A normal store's metadata is well within the ceiling."
       },
+      {
+        "surface": "dig-rpc",
+        "code": -32016,
+        "name": "PUSH_PENDING_LIMITED",
+        "http_or_exit": 200,
+        "description": "Push pending-reassembly limit reached — cache.pushCapsule refused this window: the node's in-flight pending-reassembly bound is exceeded (a per-requestor concurrent-push cap, a global concurrent-push cap, the global pending-bytes budget, or an abandoned-partial TTL). Returned by the node-profile cache.pushCapsule. Retriable once in-flight pushes complete."
+      },
       {
         "surface": "dig-rpc",
         "code": -32020,

static/openrpc-node.json

@@ -2,7 +2,7 @@
   "openrpc": "1.2.6",
   "info": {
     "title": "dig RPC — node profile (local dig-node / in-process DIG Browser)",
-    "version": "0.13.0",
+    "version": "0.14.1",
     "description": "The NODE PROFILE: a distinct, smaller surface than the network profile. Of the byte methods it implements ONLY dig.getContent (local-first, else proxy); everything else proxies upstream or returns -32601. It ADDS node-only methods the security model depends on — chiefly dig.getAnchoredRoot (the CHIP-0035 on-chain head, the trusted root for mandatory root-pinning), dig.stage, and cache.*. Gate on dig.methods rather than assuming one uniform surface. See https://docs.dig.net/docs/protocol/dig-rpc#node-profile.",
     "license": {
       "name": "GPL-2.0",
@@ -1120,6 +1120,13 @@
           "type": "object"
         }
       },
+      "PUSH_PENDING_LIMITED": {
+        "code": -32016,
+        "message": "Push pending-reassembly limit reached",
+        "data": {
+          "type": "object"
+        }
+      },
       "ONION_CIRCUIT_UNAVAILABLE": {
         "code": -32020,
         "message": "Onion circuit unavailable",

static/openrpc.json

@@ -2,7 +2,7 @@
   "openrpc": "1.2.6",
   "info": {
     "title": "dig RPC — DIG Network Content Interface (network profile)",
-    "version": "0.13.0",
+    "version": "0.14.1",
     "description": "The network-wide read interface for DIG content over JSON-RPC 2.0 — the NETWORK PROFILE served by the canonical node at rpc.dig.net. Blind by construction (the node holds no URN and no key), verifiable without trust (merkle inclusion proofs against the chain-anchored root), and streamable at any size. There is no `decoy` field on the wire and no CDN. See https://docs.dig.net/docs/protocol/dig-rpc.",
     "license": {
       "name": "GPL-2.0",
@@ -1054,6 +1054,13 @@
           "type": "object"
         }
       },
+      "PUSH_PENDING_LIMITED": {
+        "code": -32016,
+        "message": "Push pending-reassembly limit reached",
+        "data": {
+          "type": "object"
+        }
+      },
       "ONION_CIRCUIT_UNAVAILABLE": {
         "code": -32020,
         "message": "Onion circuit unavailable",