@drawbridge/drawbridge-agents 0.1.43 → 0.1.47

package/conventions/cross-repo-contracts.md

@@ -31,6 +31,15 @@ skill) so it stops living only in tribal memory.
 
 - All socket emits from sync go through `drawbridge-sync/lib/emit.js` — never call
   `io.to().emit()` directly from a worker.
+- An `sms` identity row is **never created `verified`**: api's purchase route writes
+  `status:'pending'` + the `business` details, sync's `queue/identity.js` verify job is the
+  ONLY writer of `'verified'` (after Twilio Toll-Free Verification approval, via the utils
+  twilio transport — it also renders and uploads the opt-in evidence at submission), and
+  sync's `queue/notification.js` sends from `'verified'` rows only. An api route (or script)
+  minting `'verified'` ships a number Twilio blocks outright — it looks live and delivers
+  nothing. (Collection renamed `networking` → `identity` 2026-09-03, pre-data; the plan
+  feature key stays `organization:networking` because custom-plan documents can store
+  granted keys — that string is data, never rename it without a migration.)
 - Cascade cleanup of dependent rows belongs in a sync change-stream listener, not inline in the
   API route that triggered the delete (see `cascade-cleanup.md`).
 - A collection with no `queue/<collection>.js` handler is watched but its events are **silently
@@ -134,6 +143,17 @@ skill) so it stops living only in tribal memory.
   would have zeroed every invoice once the products were archived.
 - **The v2 pricing-plan layer (`bpp_*`, billing cadences) is never touched by script.** Canceling a
   billing cadence is terminal and unrecoverable. Dashboard, by hand, only.
+- **The Shopify meter handle is a config contract no code validates** (shopify ↔ Partner
+  Dashboard ↔ sync/utils). `SHOPIFY_USAGE_ORDERS_EVENT_HANDLE` in `@drawbridge/shopify`
+  (`drawbridge-orders`) must exactly match — case-sensitive, handle not display name — a usage
+  meter on the App Pricing plan version each merchant has APPROVED (meters are never
+  retroactive). A mismatch, a missing meter, or a merchant on a pre-meter plan still 202s every
+  event, logs it as a plain app event, and bills nothing; no error surfaces anywhere in code
+  (the 19/99 write-off). Any change to the handle constant, the Partner Dashboard pricing
+  config, or a plan version requires verifying a fresh order classifies as a billing event in
+  Dev Dashboard → Logs (type "App billing event"). The trace key both sides share is
+  `billed.transaction` = the event's `reference` = `drawbridge-orders.<orderId>`. Detail:
+  drawbridge-docs `reference/shopify-app.md` (Billing).
 - **A subscription must open with the plan item.** It used to open with the metered actions price
   and attach the plan afterwards with `always_invoice`. With no metered item, Stripe rejects an
   itemless subscription, so the plan goes in at creation — changing the first invoice's shape.
@@ -384,6 +404,21 @@ renaming one orphans what is already enqueued and starts a parallel stream nobod
 with no error. `bullmq-identity.test.js` in sync spells out the routing table so moving a
 step between queues requires editing it deliberately.
 
+**`grant_refused` is minted in utils, keyed on in sync (utils ↔ sync).** Only the two
+dead-grant paths in drawbridge-utils — a refused refresh (`connections/oauth.js`) and an
+unrenewable expiry (`connections/token.js`) — set `error.code = 'grant_refused'`; a network
+failure never does. Sync's step-runner errors the connection on that code during a
+`lifecycle.health` step (the shell mints the token, so the hook can't). Minting the code
+anywhere transient flips healthy connections to error on a blip; renaming it in either repo
+means dead grants retry into Sentry forever (the Shopify 08-16 incident, ecosystem-wide).
+
+**The SMS inbound URL is one string two repos must agree on (api ↔ sync ↔ webhooks).**
+`APP_CLIENT_WEBHOOKS_URI + '/connection/drawbridge/sms'` is written to each purchased
+number by api (`route/organization-networking.js`) and re-asserted by sync's daily identity
+sweep (`queue/identity.js`), which re-points any number whose Twilio config drifts. Change
+the path in one place and the sweep "repairs" every number to the wrong URL — inbound SMS
+(STOP included) goes dark with all rows reading healthy.
+
 ## Import surfaces
 
 - Import names against a package's **actual exports** — a missing export resolves to `undefined`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drawbridge/drawbridge-agents",
-  "version": "0.1.43",
+  "version": "0.1.47",
   "description": "Shared agent-instruction content (rules, code style, conventions) for the drawbridge-* monorepo.",
   "license": "UNLICENSED",
   "publishConfig": {