@drawbridge/drawbridge-agents 0.1.38 → 0.1.39

package/conventions/cross-repo-contracts.md

@@ -9,7 +9,7 @@ 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.
-- `UNSUBSCRIBE_TOKEN_HMAC_KEY` must be identical in **drawbridge-api** and **drawbridge-sync** —
+- `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
@@ -343,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.38",
+  "version": "0.1.39",
   "description": "Shared agent-instruction content (rules, code style, conventions) for the drawbridge-* monorepo.",
   "license": "UNLICENSED",
   "publishConfig": {