@drawbridge/drawbridge-agents 0.1.25 → 0.1.27

package/conventions/cross-repo-contracts.md

@@ -63,17 +63,31 @@ 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.
+- **`items.actions` is the record of what the customer was SOLD** — `{ limit,
+  overageCentsPerAction }`, written by drawbridge-stripe (≥0.1.44) at create/upgrade/downgrade and
+  read by drawbridge-sync at cycle close. plans.js is the default for NEW sales only; editing it
+  does not reprice existing customers (that is `repriceActionsSnapshot`, explicit and dry-runnable).
+  Anything adding custom/enterprise pricing must gate the plan-change paths and the reprice script
+  or negotiated values get silently overwritten. The rate is a NUMBER in cents — the string
+  `'2.5'` shape exists only at the Stripe `unit_amount_decimal` boundary.
+- **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
+  in sync's billing: the old one skipped billing entirely for a productless subscription, which
+  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.
+- **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.27",
   "description": "Shared agent-instruction content (rules, code style, conventions) for the drawbridge-* monorepo.",
   "license": "UNLICENSED",
   "publishConfig": {