@drawbridge/drawbridge-agents 0.1.43 → 0.1.49

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
@@ -127,6 +136,16 @@ skill) so it stops living only in tribal memory.
   admin-negotiated actions values, so read the dry run). The legacy keys are copy-only until the
   overrides cleanup release, and sync (reader) deploys before stripe (writer) on any shape change.
   Detail: drawbridge-docs `reference/billing.md`.
+- **Stripe response shapes follow drawbridge-stripe's `apiVersion` pin, not the Stripe docs
+  default** (stripe ↔ api ↔ sync ↔ webhooks). The shared client pins a preview version
+  (`drawbridge-stripe/index.js`, currently `2026-01-28.preview`), and pinned versions change
+  embedded-object shapes — e.g. a promotion code carries its coupon as a bare id under
+  `promotion.coupon`; there is no embedded `coupon` object. Reading the docs-default shape fails
+  SILENTLY (optional chaining just skips the branch): the promo entry validation shipped with its
+  currency and product-restriction refusals dead this way (Asana 1211453698575738). Before reading
+  a Stripe field a consumer hasn't read before, verify it against a real response at the pin
+  (`curl` with the `Stripe-Version` header); treat any pin bump as a shape-change release across
+  every consumer.
 - **No Stripe product backs actions (≥0.1.45).** Invoice items carry
   currency/quantity/unit_amount_decimal/tax_behavior/description directly; the account keeps exactly
   one product — the plan product behind `STRIPE_PRICE_*`. Never reintroduce a product-presence guard
@@ -134,6 +153,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.
@@ -294,6 +324,15 @@ skill) so it stops living only in tribal memory.
   in the tree. Keep the pins aligned.
 - Shared packages that wrap a stateful SDK (Sentry, redis, mongodb) must direct-dep it at an
   exact pin, never a loose peer range (see `sentry-sdk.md`).
+- **A publish must rebuild `dist/` in the same command** — every published package needs a
+  `prepublishOnly` script (tsup + tests), because a bare `npm publish` ships whatever stale
+  `dist/` sits on disk with the current `package.json` version stamped on it: the version says
+  one thing, the code says another, and nothing errors anywhere. utils `0.0.100/0.0.101`
+  silently dropped the multipart upload exports this way, and utils `0.0.139` shipped the old
+  2GB `maximumUploadBytes` under a version everyone believed carried 50MB (2026-09-04; `0.0.139`
+  is poisoned — never pin it). utils ≥0.0.140 has the guard; add it to any `@drawbridge/*`
+  package before its next publish (`shopify` flagged 2026-09-04). After ANY publish, verify the
+  tarball, not the git tree: `npm pack`/curl the tarball and grep `dist/` for the change.
 - `@drawbridge/components` `Video` (≥0.0.62) owns the whole pre-playback story; consumers must NOT
   re-add their own poster layer or mount gate. `poster` renders as an SSR placeholder (opt into
   `priority` for fetchpriority=high when it's the LCP element), `defer` gates only the player —
@@ -384,6 +423,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.49",
   "description": "Shared agent-instruction content (rules, code style, conventions) for the drawbridge-* monorepo.",
   "license": "UNLICENSED",
   "publishConfig": {