@drawbridge/drawbridge-agents 0.1.25 → 0.1.26

package/conventions/cross-repo-contracts.md

@@ -63,17 +63,23 @@ skill) so it stops living only in tribal memory.
 
 ## Billing / metering
 
-- Meter events are **single-writer**: true-ups are `billing.trueup` ledger rows, never meter
-  events. A true-up written as a meter event in-window corrupts the reflection poll and strands
-  units unbillable.
-- **Upgrade mechanics and the billing path are one contract**: drawbridge-stripe's upgrade
-  (`subscription.change`) swaps the metered actions price in place, and classic-mode Stripe then
-  ignores meter events on that closing cycle invoice entirely — so drawbridge-sync's
-  `settleCycleUsage` bills upgrade-truncated invoices (actions line starts >60s after
-  `period_start`) as plain invoice items priced from plans.js instead of the meter. Changing the
-  upgrade mechanic (schedules, cycle-anchor reset, `billing_mode=flexible`) or the metering path
-  without re-checking the other side silently re-zeroes upgrade-cycle invoices. Detail:
-  drawbridge-docs `reference/billing.md` § Stripe meter emission.
+- **Actions never touch Stripe's meter.** Every cycle invoice bills the period's ledger count as
+  invoice items priced from `plans.js` (drawbridge-sync `settleCycleUsage`). The meter was removed
+  after it produced five distinct defects, ending in a 60-second line-window overlap that billed
+  one correctly-delivered event twice. Do not reintroduce meter events, and do not "fix" a billing
+  discrepancy by reporting usage to Stripe — corrections are `billing.trueup` ledger rows.
+- **The actions PRODUCT is load-bearing; the meter and metered price are not.** drawbridge-stripe
+  (≥0.1.42) provisions only a product for actions, and drawbridge-sync prices its invoice lines
+  with `price_data.product` read from `items.actions.product`. Deactivating or dropping that
+  product breaks every future invoice — which is why api's `scripts.js removeActionsMeters` strips
+  the item, price and meter but never the product, and does not reuse
+  `stripeSubscription.deactivatableItems` (that includes it).
+- **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.
+- **Invoice line descriptions must keep the word "actions":** `isActionsLine` matches `/actions/i`
+  to count billed quantity for the billed-vs-ledger reconcile. A copy edit that drops it silently
+  breaks the audit. Detail: drawbridge-docs `reference/billing.md`.
 - Every `$inc` on a `totals.*` counter needs a matching entry in `drawbridge-sync/lib/totals.js`
   `SOURCES` — that map is the only drift backstop.
 - The `invoice` collection's **unique partial index on `stripeInvoiceId`** (drawbridge-api

package/package.json

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