@drawbridge/drawbridge-agents 0.1.58 → 0.1.59

package/claude/CLAUDE.md

@@ -8,6 +8,7 @@
 @../conventions/jsx-fragments.md
 @../conventions/transactions.md
 @../conventions/cascade-cleanup.md
+@../conventions/migrations.md
 @../conventions/dry.md
 @../conventions/property-shorthand.md
 @../conventions/drawbridge-packages.md

package/conventions/cross-repo-contracts.md

@@ -478,6 +478,28 @@ failure never does. Sync's step-runner errors the connection on that code during
 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).
 
+**A segment's `connections` rows have one writer, and the api ships first (utils ↔ sync ↔ api
+↔ app-web).** `segment.connections[]` — `{ connection, id, slug, type, url }`, one row per
+connection that publishes the segment — is written ONLY by drawbridge-sync's
+`step.segment.register` (cleared by `step.segment.remove`), through the shared descriptors in
+utils `lib/connections/segment-rows.js`. api and app-web read the rows raw; the `url` is built
+inside the hook, where the settings are decrypted, so nothing downstream may recompute it. Two
+deploy orders, both silent when violated: the api must have **booted** with `schema/segment.js`
+before any sync writes a row (strict validator, `additionalProperties : false` → Mongo 121, row
+lost), and the api's pin must land before sync provisions a workflow, because `enums.step.type`
+derives from the installed utils and the workflow route validates against it ("Document failed
+validation", naming no field). Detail: `drawbridge-docs/reference/connection-hooks.md`.
+
+**A system step's workflow is provisioned from the manifest's `trigger` (utils ↔ sync).**
+`ensureSystemWorkflows` in sync walks every system step a manifest declares and creates one
+workflow per step that names a `trigger` — no trigger means nothing fires it, which is how
+Shopify's audit-only token steps stay undispatched. No PUBLISHED manifest carries a trigger yet,
+so sync must not merge ahead of the utils pin bump: on the older package the walk finds no
+trigger, provisions nothing, and Klaviyo connections silently stop getting their daily health
+workflow. Provisioning is idempotent on `(connection, system, title)` with nothing
+unique-indexing it, so a system step's `key` must stay static — a key that varied by account
+would provision a second workflow every time it changed.
+
 **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

package/conventions/migrations.md

@@ -0,0 +1,50 @@
+# Migrations live in the api
+
+Every one-off migration and backfill goes in `drawbridge-api/scripts.js`.
+
+**The only exception is media processing** — work that needs ffmpeg or sharp to
+open an image or a video. Those dependencies exist in `drawbridge-sync` and
+nowhere else, so a migration that re-encodes a file or extracts a video frame
+has to run there. Nothing else qualifies.
+
+"It dispatches queue work" is **not** an exception. The api has BullMQ and Redis
+and already enqueues onto the workers' queues, so a migration that needs a worker
+enqueues the job from the api and lets the worker do it. That is the same split
+every live code path already uses: the api decides, the workers execute.
+
+## Why
+
+A migration is a thing somebody runs once, under supervision, reading the dry run
+before the real one. Keeping them in one file in one repo means there is one
+place to look on release day, one run-list to work down, and one review surface
+when someone asks what a release will do to production data. Splitting them
+across two repos means the release plan has two homes, and the second one gets
+forgotten — which is exactly what happened to the segment connection rows
+migration.
+
+It also means the file that runs migrations cannot break the worker. Sync
+crashed on boot for several days because its `index.js` required a migrations
+file the Dockerfile never copied, and App Platform rolled every deploy back so
+quietly that dev served stale code the whole time.
+
+## How
+
+- Add the function to `drawbridge-api/scripts.js`, alongside the others.
+- Add a commented invocation to the numbered run-list at the bottom. Nothing runs
+  until somebody uncomments a line and deploys.
+- Take `dryRun` and report what it would do. The first run of a migration is a
+  read.
+- Add it to the release document in `drawbridge-docs/releases/` for the launch it
+  belongs to, with the ordering constraint stated: what has to be deployed before
+  it can run, and what breaks if it runs early.
+- If the work needs a worker, enqueue the job the live path enqueues, with the
+  same job id shape, so a migration-queued run and a live run coalesce rather
+  than doubling.
+
+## Media migrations, the one exception
+
+A media migration still follows everything above, except it lives in
+`drawbridge-sync/scripts/` as a standalone script run by hand with `ENV_FILE`,
+rather than in a `scripts.js` the service requires at boot. **Sync's `index.js`
+must never require a migrations module** — that coupling is what took the worker
+down.

package/package.json

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