@drawbridge/drawbridge-agents 0.1.37 → 0.1.39

package/conventions/cross-repo-contracts.md

@@ -9,6 +9,11 @@ skill) so it stops living only in tribal memory.
 
 - `OAUTH_TOKEN_HMAC_KEY` must be identical in **drawbridge-api** and **drawbridge-sync** — both
   `assertEnv` it at boot. A mismatch silently breaks realtime token verification.
+- `HMAC_UNSUBSCRIBE_TOKEN_KEY` must be identical in **drawbridge-api** and **drawbridge-sync** —
+  both `assertEnv` it at boot. Sync signs the unsubscribe tokens it builds into notification
+  emails (`lib/suppression.js buildToken`); api verifies them on the public `/unsubscribe/:token`
+  routes (`lib/unsubscribe.js`). A mismatch makes every unsubscribe link 404 as "invalid or
+  expired" — one-click unsubscribes silently stop landing, which mail providers punish.
 - reCAPTCHA on auth is a key pair: `GOOGLE_RECAPTCHA_SECRET` (**drawbridge-api**) + `NEXT_PUBLIC_GOOGLE_RECAPTCHA_KEY`
   (**drawbridge-app-web**), both `assertEnv`'d at boot. The api verifies the v3 token app-web's
   `/auth` forms attach and enforces it **unconditionally** on `/oauth/{signup,signin}/request`
@@ -48,6 +53,19 @@ skill) so it stops living only in tribal memory.
   `ads-republishing.<connectionId>`). Never unique-index `coalesce` (superseding requires the
   second insert to land), and writes that set `key` need the writer-side E11000 handler or a
   replayed event logs a false error.
+- **The opt-out floor: `suppression` is the single consent gate** (api ↔ sync ↔ webhooks).
+  Writers: api's `/unsubscribe` routes and draw preflight, sync's twilio buffer drain
+  (`lib/buffer.js 'twilio.message.inbound'`). The ONLY reader on any send path is sync
+  `lib/suppression.js canSend()` — a new lead-facing send path must call it, or opted-out
+  recipients get contacted (TCPA/CAN-SPAM exposure). Lead-facing = the notification carries
+  `lead`/`workflow`/`connection`; those sends also REQUIRE an org connection (no system-sender
+  fallback), while org-less system mail (OTC codes, member invites, security notices) keeps the
+  system sender and is never suppressed. Inbound STOP flows webhooks
+  (`POST /connection/:id/twilio`, signature-verified against the URL built from
+  `APP_CLIENT_WEBHOOKS_URI`) → `buffer` doc → sync drain → platform-global suppression row;
+  api registers the number's SmsUrl at twilio connect (`lib/twilio.js`) and `scripts.js
+  registerTwilioWebhooks` backfills — a deployed webhooks route with unregistered numbers hears
+  nothing, silently.
 - **Adding an email/SMS vendor is a two-repo change** (api ↔ sync). A connection is deliverable
   only if sync implements a sender for its slug — `lib/email.js` (`{ mailchimp, sendgrid }`) and
   `lib/sms.js` (`{ twilio }`), which `queue/notification.js` reads **directly** as its guard and
@@ -217,6 +235,33 @@ skill) so it stops living only in tribal memory.
   drawbridge-utils (15 min). The prize-draw branch is a genuinely different 5 min
   (api `route/otc.js` CODE_TTL_MINUTES) — the two are not interchangeable.
 
+## Submission answers are immutable (api ↔ sync ↔ app-web ↔ share)
+
+- **Nothing rewrites `submission.fields[]` after the write.** Renaming a field or one of its
+  options, and deleting a field, all used to reach back into every stored submission (`$set` on
+  `fields.$[element].label` / `.value`, `$pull` by `reference`). An answer is the record of what a
+  person was asked and said; a definition change must not touch it. The link forward is
+  `fields[].reference` (the field id) and, for choice answers, `fields[].option` (the option id
+  captured at submission time) — text is display, ids are identity.
+- **Deleting a field is a tombstone**, `deleted : true`, never a `delete`. Every live read must
+  filter `deleted : { $ne : true }` — api's builder field list, create position count, delete
+  position decrement, and the share `campaign-fields` cache aggregate; sync's leads exporter and
+  the nightly `totals.fields` recount. The **lead-detail endpoint deliberately does not filter**:
+  app-web pivots `fieldsById[reference]`, so returning tombstoned definitions is the only thing
+  keeping a removed field's historical answers displayable (it labels them `(removed)`).
+- Because the doc survives, **`stream/field.js`'s `delete` handler never fires for a removal** —
+  its `update` handler watches `updateDescription.updatedFields.deleted === true` for the
+  `campaign.totals.fields` decrement and cache-chain invalidation. A new consumer of field
+  deletion must hook the transition, not the delete.
+- **Field validators live in `@drawbridge/drawbridge-utils/fields-validate`**, consumed by BOTH
+  drawbridge-share's form and drawbridge-api's submission POST — `yup` is injected so each keeps
+  its own copy. A rule added on one side only is client-side theater: the submission endpoint is
+  publicly reachable. `select` is checked in-list against the field's own options; `required()`
+  honours `attributes.required === false`.
+- **`scripts/backfill-submission-option-ids.js` must run before any further option rename lands.**
+  It matches legacy answers to options by text one last time; once a definition and its stored
+  text diverge, nothing can match them again.
+
 ## Growth attribution tags (growth ↔ api)
 
 - drawbridge-growth `lib/tags.js` MIRRORS drawbridge-api `lib/utm.js` — allow-listed keys, trim,
@@ -298,6 +343,34 @@ skill) so it stops living only in tribal memory.
 - `sizes.original` must be set when a multipart upload completes, not at create — the resize
   worker reads it as its source, and a file without it is shaped unlike every other file.
 
+## Connection manifests are the single declaration (utils ↔ api ↔ sync ↔ webhooks)
+
+A connection is **one file** in `drawbridge-utils/lib/connections/`. Everything else
+derives from it: the builder catalog and `enums.step.type` in api, the queue routing table
+and hook registry in sync, the inbound receiver in webhooks, the connections page in
+app-web. Adding a vendor is that file plus its import in `index.js` — a test reads the
+directory and fails if the two disagree, because a manifest nothing imports is a vendor
+that exists on disk and in nobody's catalog.
+
+**`STEPS` and `RETIRED` in `contract.js` must stay in step with `enums.step.type` in the
+api.** That enum is the `$jsonSchema` validator on the workflow collection: a type absent
+from it is rejected by the DATABASE with "Document failed validation" naming no field. The
+enum DERIVES from `STEPS` and UNIONS its own legacy map — union rather than replace, or
+stored documents carrying a retired type become unwritable, including by the migration that
+would retire them.
+
+**A hook lives in drawbridge-sync only if it needs Drawbridge's own database, sockets or
+queues.** Everything else belongs on the manifest. `lib/hooks/` in sync mirrors
+`lib/connections/` in utils, one file per connection. A hook declared `{}` means "supported,
+implemented in the repo holding the dependencies"; if that registration is missing the
+runner resolves nothing and the step is SKIPPED with a `succeeded` record — silent, so
+`step-handler-coverage.test.js` asserts both directions.
+
+**Job identity is production state.** Step types, queue names and jobIds are live in Redis;
+renaming one orphans what is already enqueued and starts a parallel stream nobody consumes,
+with no error. `bullmq-identity.test.js` in sync spells out the routing table so moving a
+step between queues requires editing it deliberately.
+
 ## Import surfaces
 
 - Import names against a package's **actual exports** — a missing export resolves to `undefined`

package/conventions/rules.md

@@ -6,3 +6,9 @@
 3. Don't touch unrelated code. If a file or function is not directly part of the current task, do not modify it, even if you think it could be improved.
 
 4. Flag uncertainty explicitly. If you are not confident about an approach or technical detail, say so before proceeding. Confidence without certainty causes more damage than admitting a gap.
+
+5. Read the code before you have an opinion about it. Never describe what a component, handler or helper does — what props it takes, what it cannot do, whether two things are the same — on the strength of a grep or a partial read. Open the whole file first. A grep tells you a string is present; it cannot tell you what surrounds it, what the other variant does, or which prop already solves the problem you are about to declare unsolvable.
+
+   This is not a style preference, it is the difference between advice and noise. Asserting a limitation that isn't real sends the reader to check your work, and asserting two implementations are identical when one carries a field the other drops ships a regression. Both have happened.
+
+   In practice: before claiming a component can't do something, read the component. Before calling two implementations equivalent, read both ends to end. Before proposing a new endpoint or field to work around a gap, confirm the gap exists in the code rather than in your sample of it.

package/conventions/workflow-step-naming.md

@@ -0,0 +1,70 @@
+# Workflow step naming
+
+Step `type` strings follow **`step.<domain>[.<resource>].<verb>`** — dots, never dashes.
+
+The resource segment appears when the domain acts on more than one thing, and is omitted
+when it acts on one. Both forms are correct:
+
+    step.shopify.order.record       four — shopify manages orders, customers,
+    step.shopify.customer.insert           discounts, products, tokens
+    step.shopify.token.refresh
+
+    step.email.send                 three — email sends one thing
+    step.email.notify
+    step.sms.send
+    step.segment.sync
+
+State it as a flat four segments and the three-segment ones read as drift, and someone
+tries to "correct" them. They are not drift.
+
+**The last segment is a verb.** `step.webhook.outgoing` breaks that — `outgoing` is a
+direction — and should have been `step.webhook.send`. **Do not rename it**: webhooks are
+shipped and step slugs are stored in workflow documents. Known exception, not a pattern.
+
+## Renaming
+
+**Stored step slugs cannot be renamed once merchants hold them.** A rename is only free
+while a slug has no workflows anywhere, which in practice means before it reaches `main`.
+Check both environments before assuming — dev counts prove nothing about production.
+
+## Adding a step
+
+**This used to be a six-place ritual.** The type string had to appear identically in the
+api's `enums.step.type`, its workflow catalog, its `stepSettingsShapes`, sync's
+`stepTypeToQueueName`, sync's handler registry, and app-web's builder — and a mismatch in
+any one failed silently, saving the step and then dropping the work at run time.
+
+It is now **two places**, and both are declarations rather than copies:
+
+1. `drawbridge-utils/lib/connections/contract.js` — the type and its label in `STEPS`
+2. `drawbridge-utils/lib/connections/<vendor>.js` — the step, and the hook it points at
+
+Everything else DERIVES: the builder catalog, `enums.step.type`, `stepSettingsShapes`,
+sync's routing table. `build()` refuses the manifest at import if the declaration and the
+hook disagree, and `step-handler-coverage.test.js` in drawbridge-sync fails if the body is
+missing.
+
+**A step that does real work must declare a `hook`.** The runner resolves hooks by
+declaration, so a step declaring none is *skipped* — the step doc reads `succeeded` with a
+null message and the work silently stops. That shipped once, for `segment.sync`.
+
+## Labels
+
+**One label, in `STEPS`.** The enum label and the builder's `key` used to be two strings
+for one step and they drifted — `step.sms.send` was "Send SMS" in the enum and "Send Twilio
+SMS" in the builder. The enum now derives from `STEPS`, so there is nothing to keep in
+step.
+
+The label lives on the vocabulary rather than on a vendor because a step type belongs to
+the CAPABILITY: Klaviyo and Mailchimp both do `contacts.sync`, and a label taken from
+either would show a merchant two identically-named entries. A manifest's own `key` is the
+INSTANCE label — "Sync contact to Acme Co" — which is a different sentence for a different
+place.
+
+## Retiring a type
+
+`RETIRED` in `contract.js` maps each retired type to what it became. Stored documents carry
+the old names until a backfill runs, and the runner resolves a manifest **by type** — so
+without that map a legacy step finds no manifest and is silently skipped. `enums.step.type`
+keeps every retired key so those documents stay writable, including by the migration that
+retires them. A type leaves the map a release AFTER its backfill, never with it.

package/package.json

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