@drawbridge/drawbridge-utils 0.0.118 → 0.0.124

package/dist/connections/index.d.ts

@@ -1,20 +1,23 @@
 import { authToken } from './oauth.js';
 export { consentUrl, pkcePair } from './oauth.js';
+import { toE164, detectCountry } from '../phone.js';
 import { request } from '../http.js';
 import { channels } from '../pricing.js';
-import crypto, { createHmac, timingSafeEqual } from 'node:crypto';
+import crypto, { createHash, createHmac, timingSafeEqual, randomUUID } from 'node:crypto';
+import { customAlphabet } from 'nanoid';
+import { toCanonicalEmail } from '../email.js';
+import { conversionRate } from '../plans.js';
 import { safeRequest } from '../safe-http.js';
-import '../plans.js';
+import 'libphonenumber-js';
+import '../billing.js';
+import '../transactions.js';
+import '@drawbridge/drawbridge-telemetry';
+import '../usage.js';
 import '../features.js';
 import '../index.js';
 import 'currency-codes';
-import 'nanoid';
 import '../color.js';
 import 'tinycolor2';
-import '../usage.js';
-import '../billing.js';
-import '../transactions.js';
-import '@drawbridge/drawbridge-telemetry';
 import 'dns';
 import 'node:http';
 import 'node:https';
@@ -228,6 +231,246 @@ const HOOKS = Object.freeze({
 
 });
 
+// WHAT A HOOK RETURNS — and, just as much, what it must NOT do.
+//
+// A HOOK DOES THE WORK AND SAYS WHAT HAPPENED. It never records the run, never
+// bills, never enqueues the next step and never decides its own price: that is
+// the shell's, identically for every step. Five keys say what happened, and
+// every one of them is unchanged from the day the shell was written:
+//
+//   context    merged forward into the next step's payload
+//   message    the sentence a merchant reads in the run log
+//   request    what was sent, for support to read back
+//   response   what came back
+//   skipped    true when it deliberately did no work, so it does not bill
+//
+// THE PROBLEM THOSE FIVE COULD NOT SOLVE. A hook that had to write a document,
+// enqueue a job or tell an open dashboard something had no way to say so — so it
+// did it, with a controller, a queue and a socket server handed to it. That is
+// why the bodies lived in drawbridge-sync rather than beside the declarations
+// that name them: a published package cannot carry a database, so any hook
+// needing one had to be somewhere else, and "a vendor's logic lives in a repo
+// the vendor file cannot see" is the split these manifests exist to close.
+//
+// So a hook DESCRIBES the side effects instead, and the shell performs them:
+//
+//   writes     [ { collection, data, ignoreDuplicate, operation, options, query } ]
+//   enqueues   [ { data, name, options, queue } ]
+//   events     [ { event, payload, room } ]
+//
+// Each is a plain array of plain objects, in the order the shell must run them,
+// and each descriptor is named for the call it becomes — `operation` is the
+// controller method, `queue` is the queue's own name, `room` is the socket room.
+// No descriptor carries a function: a hook that could hand back a callback would
+// be doing the work again with an extra step.
+//
+// A REJECTION MAY CARRY EFFECTS TOO. Throwing is how a hook rejects, and some
+// rejections have to leave the world tidy — segment.sync locks each segment at
+// `syncing` and every exit, including the failing one, has to put it back or the
+// merchant watches a spinner forever. So the three keys may ride out on the
+// thrown error, and the shell performs them before it records the failure. It is
+// the same precedent as `error.status` and `error.response`, which the shell
+// already reads off a rejection.
+//
+// WHAT IS STILL PASSED IN. Reads are not side effects and are not described:
+// gathering the facts IS the work. A hook receives `read` — the controller's
+// read-only methods and nothing else — so it cannot write through it even by
+// mistake. Anything else a hook genuinely needs is injected the same way the
+// `shopify` SDK is: as an argument, named for what it does.
+const HOOK_EFFECTS = Object.freeze([ 'enqueues', 'events', 'writes' ]);
+
+// The controller methods a described write may become. Only the two that a hook
+// has ever needed — a deletion is a cascade, and cascades are owned by
+// drawbridge-sync's streams rather than by a step.
+const WRITE_OPERATIONS = Object.freeze([ 'create', 'update' ]);
+
+// READ A HOOK'S EFFECTS, or refuse them.
+//
+// The shell performs whatever comes back here, so a malformed descriptor is a
+// write against the wrong collection or an emit to every open dashboard. Caught
+// at the boundary instead, in the hook's own words, because the alternative is a
+// TypeError inside the controller naming nothing that would help.
+//
+// Absent keys are an EMPTY ARRAY rather than undefined: the caller performs
+// `writes` unconditionally, and a shell that has to null-check three keys is
+// three places one of them gets forgotten.
+// WHAT A HOOK IS HANDED: TWO OBJECTS, so a signature says on sight what is a
+// property of the run and what is a service being passed in.
+//
+//   hook( props, options )
+//
+// PROPS are facts — data about this run, this merchant, this payload. OPTIONS
+// are services — capabilities the caller injects, every one either read-only or
+// owned by the shell. A hook that wants a service reaches into its second
+// argument, which is what keeps a fact from quietly becoming a handle.
+//
+// One vocabulary for every manifest. A name below means the same thing in every
+// hook that receives it; a synonym splits the vocabulary and fails the test
+// that walks these.
+//
+//   PROPS — facts of the run
+//   channel      which inbound surface the request arrived on
+//   clientId,    OUR app's credential VALUES, resolved by the caller from the
+//   clientSecret provider collection — auth.disconnect and auth.probe, where
+//                the vendor wants them re-presented
+//   connection   the merchant's connection document
+//   contact      the person's email — the address, not the lead document
+//   context      the step's accumulated trigger data
+//   cursor,      resources.* pagination, always these names
+//   limit,
+//   search, sort
+//   declaration  the step declaration the shell resolved for this run
+//   doc          the document a stream-driven hook acts on
+//   email, id    the identifiers a contacts hook acts on when there is no doc
+//   event        the inbound event name the manifest extracted
+//   headers      the inbound request's headers
+//   lead         the lead document, resolved by the shell when the run names one
+//   manifest     the hook's own manifest, for the vendor facts it declares
+//   payload      the verified inbound body
+//   scope        the granted scope string being judged
+//   secret       the credential VALUE the caller resolved for verification
+//   settings     the connection's decrypted settings
+//   step         the step document
+//   suppressed   the opt-out floor's answer for this lead, computed by the shell
+//   token        a LIVE access token, refreshed by the shell before the call —
+//                oauth vendors only; null everywhere else
+//   tokens       the FRESH GRANT auth.connect receives from the oauth runner —
+//                the whole exchange response, not one live token
+//   workflow     the workflow document
+//
+//   OPTIONS — services passed in
+//   adminToken()        mint or refresh the store token — Shopify's install
+//                       model, where rotation persists mid-call; a resolver
+//                       rather than a value, unlike `token`
+//   canSend()           the opt-out floor, bound to this run's organization
+//   chunkSize           the worker fleet's fan-out width — deployment tuning,
+//                       passed, never published
+//   dispatch()          the caller's own coordinator table, for hooks that are
+//                       dispatches
+//   fetcher             fetch-shaped transport: ( url, options )
+//   logger              the caller's logger
+//   mintId()            an id minted before the write it belongs to, so one
+//                       described write can reference another
+//   read                the controller's READ methods — get, aggregate, count —
+//                       and never anything that writes; not `controller`, not
+//                       `db`, because a name that implies writing invites it
+//   reconcileScopes()   the caller's scope writer-of-record; injected because
+//                       the hook needs its result
+//   request             safeRequest-shaped transport: ({ body, headers, method,
+//                       url }) — a different SHAPE than fetcher, so a different
+//                       name
+//   resolveContact()    the one write a description cannot carry — its result
+//                       decides billing
+//   resolveSettings()   fresh from wherever the vendor keeps credentials, per
+//                       call, never a snapshot
+//   rotateToken()       deliberate rotation, for the health check that rotates
+//                       before the window closes
+//   shopify             the SDK namespaces, injected — this package cannot
+//                       import what depends on it
+// THE ONE EXEMPTION: hooks.auth.token takes a SINGLE bag. It is the OAuth token
+// request itself — called directly by the oauth runner and the refresh path,
+// never through runHook — and its argument is the request's fields (clientId,
+// code, refreshToken, fetcher) as one unit. Splitting it would change a
+// wire-shaped call for symmetry's sake. Callers must never invoke it via
+// runHook with a second bag: the options would be silently discarded, which is
+// exactly the stubbed-fetcher-goes-live failure the split exists to prevent.
+const HOOK_PROPS = Object.freeze([
+	'channel', 'clientId', 'clientSecret', 'connection', 'contact', 'context',
+	'cursor', 'declaration', 'doc', 'email', 'event', 'headers', 'id', 'lead', 'limit',
+	'manifest', 'payload',
+	'scope', 'search', 'secret', 'settings', 'sort', 'step', 'suppressed',
+	'token', 'tokens', 'workflow'
+]);
+
+const HOOK_OPTIONS = Object.freeze([
+	'adminToken', 'canSend', 'chunkSize', 'dispatch', 'fetcher', 'logger',
+	'mintId', 'read', 'reconcileScopes', 'request', 'resolveContact',
+	'resolveSettings', 'rotateToken', 'shopify'
+]);
+
+const effectsOf = ( answer ) => {
+
+	for( const key of HOOK_EFFECTS ){
+
+		if( answer?.[ key ] !== undefined && ! Array.isArray( answer[ key ] ) ){
+
+			throw new Error( 'A hook returned ' + key + ' that is not an array' );
+
+		}
+
+	}
+
+	const enqueues = answer?.enqueues || [];
+	const events = answer?.events || [];
+	const writes = answer?.writes || [];
+
+	for( const write of writes ){
+
+		if( ! write?.collection ) throw new Error( 'A described write names no collection' );
+
+		if( ! WRITE_OPERATIONS.includes( write?.operation ) ){
+
+			throw new Error( 'A described write on ' + write.collection + ' needs an operation — one of ' + WRITE_OPERATIONS.join( ', ' ) );
+
+		}
+
+		if( ! write?.data ) throw new Error( 'A described write on ' + write.collection + ' carries no data' );
+
+		// AN UPDATE WITH NO QUERY IS EVERY DOCUMENT IN THE COLLECTION. Refused here
+		// rather than survived, because the controller would happily run it.
+		if( write.operation === 'update' && ! write.query ){
+
+			throw new Error( 'A described update on ' + write.collection + ' has no query — that is every document in it' );
+
+		}
+
+		// The controller's create takes no query, so one here is a filter the
+		// author believed in and the database never saw.
+		if( write.operation === 'create' && write.query ){
+
+			throw new Error( 'A described create on ' + write.collection + ' carries a query — create does not filter' );
+
+		}
+
+	}
+
+	for( const enqueue of enqueues ){
+
+		if( ! enqueue?.queue ) throw new Error( 'A described enqueue names no queue' );
+
+		// BullMQ's own first argument. Without it the job lands unnamed and no
+		// worker handler matches it — a job accepted and never run.
+		if( ! enqueue?.name ) throw new Error( 'A described enqueue on the ' + enqueue.queue + ' queue names no job' );
+
+	}
+
+	for( const event of events ){
+
+		if( ! event?.event ) throw new Error( 'A described event has no name' );
+
+		// A ROOM IS NOT OPTIONAL. An emit without one reaches every connected
+		// dashboard, which is one organization's data arriving in another's tab.
+		if( ! event?.room ) throw new Error( 'A described ' + event.event + ' event has no room' );
+
+	}
+
+	// ALL OR NONE. `transaction : true` asks the shell to land every described
+	// write in one transaction — for the order/redemption pair, where a
+	// half-written attribution is revenue counted twice or not at all. It covers
+	// the WRITES only: enqueues and events still run after the writes commit,
+	// which is the ordering a job that reads a row it expects to exist depends on.
+	const transaction = Boolean( answer?.transaction );
+
+	if( transaction && ! writes.length ){
+
+		throw new Error( 'A hook asked for a transaction and described no writes' );
+
+	}
+
+	return { enqueues, events, transaction, writes };
+
+};
+
 // WHAT A WORKFLOW STEP CAN BE. Closed, and the LABEL LIVES HERE rather than on a
 // vendor, because a step type belongs to the capability and not to whoever
 // implements it: Klaviyo and Mailchimp both do contacts.sync, and a label taken
@@ -366,7 +609,9 @@ const GROUPS = Object.freeze([ 'commerce', 'contacts', 'developer', 'messaging'
 //
 //   authorize  the consent url
 //   token      the exchange/refresh url
-//   client     the ENV VAR NAMES holding our own id and secret, never the values
+//   client     the NAMES of our own id and secret, never the values — keys into
+//              the credential map the provider collection answers, matching a
+//              provider field's `credential`
 //   redirect   our callback path — DECLARED, never derived from the slug. It is
 //              registered in the vendor's console and they refuse anything that
 //              does not byte-match, so it is a fact about someone else's records
@@ -531,6 +776,38 @@ var icon$4 = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xm
 <path d="M166.04 261.805C180.228 259.107 195.528 261.893 207.581 269.971C218.512 277.079 226.908 288.136 230.604 300.657C234.835 314.103 233.614 329.124 227.485 341.788C220.097 356.875 205.782 368.543 189.317 372.089C173.957 375.652 157.089 372.386 144.304 363.103C132.971 355.295 124.912 342.989 121.891 329.581C118.943 316.636 120.725 302.656 127.002 290.938C134.699 275.951 149.503 264.933 166.046 261.811" fill="#1E1C1C"/>
 </svg>`;
 
+// ONE REQUEST SHAPE for every Attentive call, the way Klaviyo's file has one.
+// The path carries its own version — the segments picker is v2 and the
+// subscription writes are v1 — because Attentive versions per resource rather
+// than per API.
+const api$2 = async ( path, { fetcher = fetch, method = 'GET', payload, token } ) => {
+
+	const response = await fetcher( 'https://api.attentivemobile.com' + path, {
+		...( payload && { body : JSON.stringify( payload ) }),
+		headers : {
+			authorization : 'Bearer ' + token,
+			...( payload && { 'content-type' : 'application/json' })
+		},
+		method,
+		signal : AbortSignal.timeout( 15000 )
+	});
+
+	if( ! response.ok ){
+
+		throw Object.assign(
+			new Error( 'Attentive refused the request (' + response.status + ')' ),
+			{ status : response.status }
+		);
+
+	}
+
+	// 202 ACCEPTED may carry a body (the bulk-segment job id) or nothing at all,
+	// and asking json() for an empty body throws — which would report a write
+	// Attentive accepted as a failed step. A body that will not parse answers null.
+	return response.json().catch( () => null );
+
+};
+
 // Attentive — SMS-first marketing, installed as a distributed Attentive app.
 //
 // EVERY VENDOR FACT BELOW IS CITED from docs.attentive.com (fetched 2026-09-01):
@@ -562,8 +839,9 @@ var icon$4 = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xm
 //
 // DORMANT UNTIL REGISTERED. `requires` names the client credentials that only
 // exist once the Attentive app is created (their console: enable distribution,
-// set the redirect URL, Generate Credentials). Until those env vars land, no
-// deployment offers this connection — the manifest ships complete and inert.
+// set the redirect URL, Generate Credentials). Until an admin enters them on
+// the provider screen, no deployment offers this connection — the manifest
+// ships complete and inert.
 //
 // THREE THINGS TO VERIFY AT REGISTRATION, because the docs conflict or are
 // silent, and only a live install answers them:
@@ -584,9 +862,12 @@ var icon$4 = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xm
 var attentive = {
 	auth : {
 		oauth : {
-			// NAMES of the env vars holding OUR app's client — set at registration,
-			// never before. No `headers` on the client: Attentive takes credentials
-			// as form fields, which is the runner's default.
+			// NAMES of the credentials holding OUR app's client — keys into the map
+			// the provider collection answers, entered on the admin screen at
+			// registration, never before. (The names are the env vars they once
+			// were; the vocabulary stayed when the storage moved.) No `headers` on
+			// the client: Attentive takes credentials as form fields, which is the
+			// runner's default.
 			client : {
 				id : 'ATTENTIVE_OAUTH_CLIENT_ID',
 				secret : 'ATTENTIVE_OAUTH_CLIENT_SECRET'
@@ -611,9 +892,10 @@ var attentive = {
 		// has to say so rather than let them believe otherwise.
 		confirm : 'Disconnecting removes Drawbridge\'s stored Attentive token. Attentive does not offer a way for us to revoke it, so remove the Drawbridge integration in Attentive as well if you want its access fully withdrawn. Your subscribers stay in both Attentive and Drawbridge — neither list is deleted.',
 		description : [
-			'Attentive is where your SMS marketing lives, and this connection is becoming the way your Drawbridge contacts sync into an Attentive segment.',
+			'Attentive is where your SMS marketing lives, and this connection syncs the contacts your campaigns collect into an Attentive segment — subscribed for marketing and added to the segment you choose.',
 			'You authorize Drawbridge from inside Attentive and can revoke that access there at any time. Drawbridge never sees or stores your Attentive password.',
-			'Subscriber syncing is not live yet, so connecting today does nothing except choose the segment it will use when it ships.'
+			'Anyone who has opted out in Drawbridge is sent to Attentive as an unsubscribe rather than omitted, so a person who asked not to be contacted stays suppressed in both systems instead of quietly reappearing.',
+			'Attentive accepts these updates and applies them in the background, so a contact appears in your segment shortly after the sync rather than the instant it runs.'
 		],
 		excerpt : 'Sync your Drawbridge contacts into an Attentive segment.',
 		guide : [
@@ -633,7 +915,11 @@ var attentive = {
 			label : 'Attentive segment',
 			message : 'Contacts your campaigns collect are synced into this segment.',
 			hook : 'resources.audiences',
-			required : true
+			required : true,
+			// CONSUMED BY THE MEMBERSHIP CALL, not by the subscribe. Attentive's
+			// /v1/subscriptions takes no segment id — subscription and segment
+			// membership are two operations here — so contacts.sync makes both calls
+			// and this value is the externalId the second one carries.
 			// No `search : false` here, and that is a first: /v2/segments takes a
 			// `name` filter (partial match, cited above), so this picker searches
 			// the ACCOUNT — Klaviyo and Mailchimp can only match the fetched page.
@@ -647,17 +933,25 @@ var attentive = {
 	hooks : {
 
 		auth : {
-			// The exchange already yields the tokens, and Attentive documents no
-			// account-identity endpoint to enrich them with — Klaviyo's connect
-			// reads the account name back; this has nothing cited to read. The
-			// callback stores the tokens and skips enrichment on `unimplemented`.
 			// FALSE, NOT {}. `{}` means "supported, implemented in the repo with the
-			// dependencies", and nothing anywhere implements either of these —
-			// there is nothing for them to do. The exchange already yields the
-			// tokens and Attentive documents no account-identity endpoint to
-			// enrich them with, so connect has nothing to add; and they document
-			// no revocation endpoint at all, so disconnect has nothing to call.
-			// Recorded as a decision rather than left as an unkept promise.
+			// dependencies", and nothing anywhere implements either of these — there
+			// is nothing for them to do. They document no revocation endpoint at all,
+			// so disconnect has nothing to call. Recorded as a decision rather than
+			// left as an unkept promise.
+			//
+			// STILL FALSE AFTER LOOKING AGAIN, and this is the reason written down so
+			// nobody re-derives it. Klaviyo's connect reads the account name back so
+			// the card is not blank; Attentive's card stays blank. There IS an
+			// endpoint — GET https://api.attentivemobile.com/v1/me, Bearer, described
+			// on docs.attentive.com/pages/authentication/ as returning "information
+			// specific to your company" — but its RESPONSE SCHEMA is published
+			// nowhere we can read: the docs show the curl and no body. Reading
+			// `body.name` would be a guess, and a guess here fails at the worst
+			// moment, in the callback, after the merchant has already consented.
+			//
+			// A live token settles it in one call, alongside the three registration
+			// checks in the header. Until then the honest state is a blank field, not
+			// a hopeful one.
 			connect : false,
 			disconnect : false,
 			probe : false,
@@ -682,7 +976,154 @@ var attentive = {
 			}
 		},
 		commerce : false,
-		contacts : { remove : false, sync : false },
+
+		// The verb the contacts.sync step points at.
+		contacts : {
+
+			// Not yet. Suppression syncs an opt-out as unsubscribed, which is a
+			// different thing from erasing the subscriber — Attentive's deletion sits
+			// behind their privacy-request API, which is a different grant.
+			remove : false,
+
+			// TWO CALLS, BECAUSE ATTENTIVE HAS TWO IDEAS.
+			//
+			// Subscribing and being in a segment are NOT the same operation here —
+			// unlike Klaviyo, where a subscription is created against the list itself.
+			// /v1/subscriptions takes no segment id at all, so the segment a merchant
+			// picked on this connection can only be honoured by the bulk segment
+			// membership API:
+			//
+			//   subscribe   POST /v1/subscriptions
+			//               { user : { email, phone }, locale, subscriptionType } — the
+			//               docs require EITHER signUpSourceId OR (locale +
+			//               subscriptionType), and we hold no sign-up source. 202.
+			//
+			//   membership  POST /v2/bulk/segments/members
+			//               { externalId, members : [ { email, phone } ] }, 1-10,000
+			//               members, 202 with a batchJobId
+			//               (docs.attentive.com/reference/postbulksegmentmembers).
+			//
+			//   unsubscribe POST /v1/subscriptions/unsubscribe
+			//               { user, subscriptions : [ { type, channel } ] }. 202.
+			//
+			// EVERY ONE OF THEM ANSWERS 202 ACCEPTED, which means Attentive took the
+			// job, not that it ran — the same distinction the Shopify usage charge
+			// makes between a 202 and a charge. The message below says accepted, and
+			// must keep saying accepted.
+			sync : async ( { lead, settings, suppressed, token }, { fetcher } = {} ) => {
+
+				const segment = settings?.segment;
+
+				// status() already stops a connection reaching Active without a
+				// segment; this is the belt to that braces. A workflow saved before the
+				// segment was chosen must not silently write into nothing.
+				if( ! segment ) return { message : 'No Attentive segment is chosen for this connection.', skipped : true };
+
+				const email = lead?.canonical?.email?.value || lead?.email;
+
+				// E.164 OR NOTHING. Attentive requires it, and a national-format number
+				// is refused with the whole request — so an unparseable one is dropped
+				// and the email carries the sync instead.
+				const phone = toE164( lead?.canonical?.phone?.value || lead?.phone );
+
+				// Their `user` requires phone OR email. With neither there is nobody to
+				// subscribe, so this is a skip rather than a failure.
+				if( ! email && ! phone ) return { message : 'That lead has no email address or phone number to sync.', skipped : true };
+
+				const user = {
+					...( email && { email }),
+					...( phone && { phone })
+				};
+
+				// SUPPRESSED PEOPLE ARE SYNCED AS UNSUBSCRIBED, NEVER OMITTED.
+				//
+				// Omitting them means Attentive never learns they said no, so the
+				// merchant can import them from somewhere else and start texting them
+				// again. Pushing them as unsubscribed makes the suppression travel with
+				// the person, which is the reason this connection is allowed to send
+				// anything at all.
+				//
+				// `suppressed` arrives as an argument because canSend() is sync's — a
+				// manifest cannot reach it, and this rule is too important to infer.
+				//
+				// AND THE SEGMENT IS SKIPPED for them: adding someone who opted out to
+				// a marketing segment is the same mistake as omitting the opt-out,
+				// wearing the other hat.
+				if( suppressed ){
+
+					await api$2( '/v1/subscriptions/unsubscribe', {
+						fetcher,
+						method : 'POST',
+						payload : {
+							// One entry per channel we can actually name them by. MARKETING
+							// is the only type Drawbridge ever subscribed them to.
+							subscriptions : [
+								...( phone ? [ { channel : 'TEXT', type : 'MARKETING' } ] : [] ),
+								...( email ? [ { channel : 'EMAIL', type : 'MARKETING' } ] : [] )
+							],
+							user
+						},
+						token
+					});
+
+					return {
+						message : 'Attentive accepted an unsubscribe for this contact — they have opted out.',
+						response : { accepted : true, unsubscribed : true }
+					};
+
+				}
+
+				await api$2( '/v1/subscriptions', {
+					fetcher,
+					method : 'POST',
+					payload : {
+						// LOCALE, because we hold no signUpSourceId and the docs require
+						// one or the other. The country is READ OFF the number when there
+						// is one — libphonenumber knows it from the calling code — rather
+						// than assumed; only the fallback pair below is a default, and it
+						// is the one value here that no vendor document dictates.
+						//
+						// ponytail: en/US default. A `signUpSourceId` field on the
+						// connection is the upgrade — Attentive's sign-up sources carry
+						// the consent language, which is a better answer than any locale
+						// we can infer — and it replaces this branch entirely.
+						locale : {
+							country : ( phone && detectCountry( phone ) ) || 'US',
+							language : 'en'
+						},
+						subscriptionType : 'MARKETING',
+						user
+					},
+					token
+				});
+
+				// THE SEGMENT THE MERCHANT PICKED, which the subscribe above cannot
+				// carry. One member per call rather than a batch: this hook is one
+				// contact, and their endpoint takes 1-10,000.
+				const membership = await api$2( '/v2/bulk/segments/members', {
+					fetcher,
+					method : 'POST',
+					payload : {
+						externalId : segment,
+						members : [ user ]
+					},
+					token
+				});
+
+				return {
+					// ACCEPTED, NOT LIVE. Both writes answered 202, which means Attentive
+					// queued them — a merchant who reads "synced" and looks for the person
+					// in Attentive a second later has been told the wrong thing.
+					message : 'Attentive accepted this contact for the segment. Attentive processes these asynchronously, so it appears there shortly.',
+					response : {
+						accepted : true,
+						...( membership?.batchJobId && { batchJobId : membership.batchJobId })
+					}
+				};
+
+			}
+
+		},
 		email : false,
 		inbound : false,
 		lifecycle : false,
@@ -696,7 +1137,7 @@ var attentive = {
 			// show a picker quietly missing most of a real account. The response's
 			// only identifier is `externalId`, so an entry without one cannot be
 			// stored and is dropped.
-			audiences : async ({ cursor, fetcher = fetch, limit = 100, search, token }) => {
+			audiences : async ( { cursor, limit = 100, search, token }, { fetcher } = {} ) => {
 
 				const query = new URLSearchParams({
 					limit : String( Math.min( limit, 1000 ) ),
@@ -704,24 +1145,7 @@ var attentive = {
 					...( search?.value && { name : String( search.value ).trim() } )
 				});
 
-				const response = await fetcher(
-					'https://api.attentivemobile.com/v2/segments?' + query,
-					{
-						headers : { authorization : 'Bearer ' + token },
-						signal : AbortSignal.timeout( 15000 )
-					}
-				);
-
-				if( ! response.ok ){
-
-					throw Object.assign(
-						new Error( 'Attentive refused the request (' + response.status + ')' ),
-						{ status : response.status }
-					);
-
-				}
-
-				const body = await response.json();
+				const body = await api$2( '/v2/segments?' + query, { fetcher, token });
 
 				return {
 					items : ( body?.segments || [] )
@@ -745,33 +1169,79 @@ var attentive = {
 
 	},
 	icon: icon$4,
+	// DRAWBRIDGE'S OWN CREDENTIALS for this vendor, as opposed to a merchant's —
+	// what an admin types on the provider screen, and the only declaration of it.
+	// It lives beside `requires`, which names the same variables: the manifest
+	// says what it needs and this says how someone supplies it, so a credential
+	// cannot be required by a vendor that offers nowhere to enter it.
+	//
+	// `redact` marks a secret — never returned by the api, and blank on save means
+	// keep the stored value. `required` drives the live check.
+	provider : {
+		fields : [
+			{ input : 'text', key : 'clientId', credential : 'ATTENTIVE_OAUTH_CLIENT_ID', label : 'Client ID', required : true },
+			{ input : 'password', key : 'clientSecret', credential : 'ATTENTIVE_OAUTH_CLIENT_SECRET', label : 'Client secret', redact : true, required : true }
+		]
+	},
 	requires : [
 		'ATTENTIVE_OAUTH_CLIENT_ID',
 		'ATTENTIVE_OAUTH_CLIENT_SECRET'
 	],
 	slug : 'attentive',
-	// A consent with no segment chosen is authenticated and inert — the sync,
-	// when it ships, needs somewhere to put people.
+	// A consent with no segment chosen is authenticated and inert — the sync needs
+	// somewhere to put people — so the card says Pending rather than Active over
+	// nothing.
 	status : ( data ) => ( data?.settings?.segment ? data.status : 'pending' ),
-	// No steps: subscriber sync has not shipped, so this vendor contributes
-	// nothing to a workflow yet. An empty steps object is the honest declaration.
-	steps : {},
-	tasks : ( data ) => [
-		...( data?.settings?.segment
-			? []
-			: [
-				{
-					message : 'Choose which Attentive segment your contacts should sync into. Until you do, nothing is being synced.',
-					title : 'Choose a segment'
-				}
-			]
-		),
-		{
-			message : 'Contact syncing to Attentive segments has not shipped yet. Nothing is being sent to Attentive right now.',
-			title : 'Subscriber sync not available yet',
-			type : 'warning'
+
+	steps : {
+
+		contacts : {
+
+			// A DECLARATION, not the work. The nesting IS the name: this is
+			// `step.contacts.sync`, the string a workflow document stores. Klaviyo and
+			// Mailchimp declare the same type — a step belongs to the capability, not
+			// to whoever implements it — and the connection on the step document is
+			// what says which vendor runs.
+			sync : ({ data }) => ({
+
+				hook : 'contacts.sync',
+
+				// NO ACCOUNT NAME TO INTERPOLATE, unlike Klaviyo: auth.connect is false
+				// because Attentive publishes no account-identity response we can read
+				// (see its comment), and settings.segment is an opaque externalId no
+				// merchant would recognise in a builder label.
+				key : 'Sync contact to Attentive',
+
+				queue : 'connection',
+
+				// Nothing for a merchant to configure on the step itself — the segment
+				// is chosen once on the connection. Declared empty rather than omitted,
+				// so "this step takes no settings" and "nobody thought about settings"
+				// stay different statements.
+				settings : {},
+
+				// BOTH triggers, for the same reason as Klaviyo: lead.insert alone only
+				// ever fires for someone with no history yet, and crossing into a
+				// segment is the other moment a contact is worth pushing.
+				triggers : [ 'lead.insert', 'segment.contact.add' ],
+
+				usage : { actions : 1 }
+
+			})
+
 		}
-	],
+
+	},
+	// WHY, in the merchant's words, and what to do about it.
+	tasks : ( data ) => ( data?.settings?.segment
+		? []
+		: [
+			{
+				message : 'Choose which Attentive segment your contacts should sync into. Until you do, nothing is being synced.',
+				title : 'Choose a segment'
+			}
+		]
+	),
 	title : 'Attentive'
 };
 
@@ -809,15 +1279,22 @@ var attentive = {
 
 const HUBSPOT_BASE = 'https://api.hubapi.com';
 
-// Best-effort: with no Private App token configured the whole integration
-// no-ops so a missing secret never crashes sync. Callers wrap these in
-// try/catch and treat a missing id gracefully.
+// THE TOKEN IS THE CALLER'S TO PASS. It used to fall back to process.env; it
+// lives encrypted in the `provider` collection now (lib/providers.js).
+//
+// THROWS RATHER THAN DEGRADES, once a request is actually being made. Whether
+// the portal is configured at all is decided by the callers below — the token is
+// declared optional on purpose — but a path that got as far as here without one
+// would send `Bearer undefined` and read the 401 as HubSpot being down. The
+// absence has to be named where it happens.
 const hubspotRequest = ({ body, fetcher, method, path, query, token }) => {
 
+	if( ! token ) throw new Error( 'HubSpot access token missing — pass token (the drawbridge provider\'s hubspotToken)' );
+
 	return ( fetcher || request )({
 		body,
 		headers : {
-			'Authorization' : 'Bearer ' + ( token || process.env.HUBSPOT_ACCESS_TOKEN )
+			'Authorization' : 'Bearer ' + token
 		},
 		method,
 		query,
@@ -1012,13 +1489,16 @@ const contacts = {
 			// FORGET A CONTACT, by id or by email. Account deletion — the caller had
 			// to search then remove, which is one round trip it should not have to
 			// know about.
-			remove : async ({ email, fetcher, id, token }) => {
-
-				const key = token || process.env.HUBSPOT_ACCESS_TOKEN;
+			remove : async ( { email, id, token }, { fetcher } = {} ) => {
 
-				if( ! key ) return;
+				// NO TOKEN IS A NO-OP HERE, unlike sendgrid and twilio, and the
+				// difference is what the credential is declared to be: hubspotToken
+				// is the one provider field that is not `required`, because this is
+				// internal CRM tooling no merchant sees. A deployment with no portal
+				// is a supported state, not a missing credential.
+				if( ! token ) return;
 
-				const contact = id || await lookup({ email, fetcher, token : key });
+				const contact = id || await lookup({ email, fetcher, token });
 
 				if( ! contact ) return;
 
@@ -1026,7 +1506,7 @@ const contacts = {
 					fetcher,
 					method : 'DELETE',
 					path : '/crm/v3/objects/contacts/' + contact,
-					token : key
+					token
 				});
 
 			},
@@ -1037,19 +1517,18 @@ const contacts = {
 			// no delete-old-then-create-new.
 			//
 			// Prefer the cached hubspotId; fall back to a search; create last.
-			sync : async ({ doc, fetcher, token }) => {
-
-				const key = token || process.env.HUBSPOT_ACCESS_TOKEN;
+			sync : async ( { doc, token }, { fetcher } = {} ) => {
 
-				// NO TOKEN IS A NO-OP, not an error. A deployment without a portal
-				// configured must not crash the user stream.
-				if( ! key ) return;
+				// NO TOKEN IS A NO-OP, not an error — see remove() above. A
+				// deployment without a portal configured must not crash the user
+				// stream over internal tooling.
+				if( ! token ) return;
 
 				if( doc?.hubspotId ){
 
 					try {
 
-						return ( await send({ doc, fetcher, method : 'PATCH', path : '/crm/v3/objects/contacts/' + doc.hubspotId, token : key }) )?.id;
+						return ( await send({ doc, fetcher, method : 'PATCH', path : '/crm/v3/objects/contacts/' + doc.hubspotId, token }) )?.id;
 
 					} catch ( error ){
 
@@ -1061,14 +1540,14 @@ const contacts = {
 
 				}
 
-				const existing = await lookup({ email : doc?.email, fetcher, token : key });
+				const existing = await lookup({ email : doc?.email, fetcher, token });
 
 				return ( await send({
 					doc,
 					fetcher,
 					method : existing ? 'PATCH' : 'POST',
 					path : existing ? '/crm/v3/objects/contacts/' + existing : '/crm/v3/objects/contacts',
-					token : key
+					token
 				}) )?.id;
 
 			}
@@ -1085,7 +1564,7 @@ var icon$3 = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xm
 <rect width="500" height="500" fill="#BAEC5F"/>
 <g clip-path="url(#clip0_2115_2832)">
 <path d="M140.224 127.586L174.803 188.73V311.176L140 372.32L176.084 392.031L216.111 321.753V178.278L176.341 108L140.224 127.586Z" fill="#0D1314"/>
-<path d="M360.001 127.523L323.693 108.282L284.948 178.498V321.596L322.923 391.749L359.393 372.79L326.224 311.52V188.73L360.001 127.523Z" fill="#0D1314"/>
+<path d="M360.002 127.523L323.694 108.282L284.949 178.498V321.596L322.924 391.749L359.394 372.79L326.225 311.52V188.73L360.002 127.523Z" fill="#0D1314"/>
 </g>
 <defs>
 <clipPath id="clip0_2115_2832">
@@ -1110,6 +1589,82 @@ var icon$3 = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xm
 // answers "can this merchant connect it" through `requires` and a plan feature.
 // A private one is always present, in every deployment, for every organization —
 // so it declares neither, and build() knows not to ask.
+
+// Replace {{key}} placeholders with values from the run's accumulated context.
+// An unresolved key is left as it was written rather than blanked: a merchant
+// reading "Hello {{name}}" knows their template is wrong, where "Hello " reads
+// like a person with no name.
+//
+// Moved here from drawbridge-sync's lib/step.js with the bodies that were its
+// only callers. It is a string function — nothing about it needed a service.
+const interpolate = ( template, data ) => {
+
+	if( ! template ) return template;
+
+	return template.replace( /\{\{(\w+)\}\}/g, ( _, key ) => ( data?.[ key ] != null ? String( data[ key ] ) : '{{' + key + '}}' ) );
+
+};
+
+// WHO ON THE TEAM GETS TOLD. Shared by email.notify and email.digest, which
+// resolved it identically — the same forty lines twice, and the dedupe rule is
+// subtle enough that two copies would eventually differ.
+//
+// The OWNER IS ALWAYS A RECIPIENT. `settings.members` is an optional list of
+// ADDITIONAL people: the members endpoint is owner-gated and the owner is not a
+// `member` document, so a solo merchant has nothing selectable and could
+// otherwise not use these steps at all.
+const teamRecipients = async ({ memberIds = [], organization, read }) => {
+
+	const org = await read.get({ collection : 'organization', query : { id : organization } });
+
+	const owner = org?.owner
+		? await read.get({ collection : 'user', query : { id : org.owner } })
+		: null;
+
+	// Re-scoped to the org and to ACCEPTED members: the id list is stored on the
+	// step and outlives the membership it names — someone who declined, was
+	// removed, or never accepted.
+	const members = memberIds.length
+		? await read.aggregate({
+			collection : 'member',
+			pipeline : [
+				{
+					$match : {
+						id : { $in : memberIds },
+						organization,
+						status : 'accepted'
+					}
+				}
+			]
+		})
+		: [];
+
+	// Deduped by address, lower-cased and NO FURTHER. The owner is commonly also
+	// named in settings.members and nobody should get two copies. Canonicalizing
+	// (toCanonicalEmail) would be wrong: it strips +tags, so two genuinely
+	// different teammates collapse into one and the second is never told.
+	const seen = new Set();
+
+	return [ owner, ...members ].filter( ( member ) => {
+
+		if( ! member?.id || ! member?.email ) return false;
+
+		const address = member.email.toLowerCase();
+
+		if( seen.has( address ) ) return false;
+
+		seen.add( address );
+
+		return true;
+
+	});
+
+};
+
+// ONE NOTIFICATION, DESCRIBED. queue/notification.js owns delivery, the
+// unsubscribe token and the CAN-SPAM footer — these steps only say who and what.
+const queueNotification = ( data ) => ({ collection : 'notification', data, operation : 'create' });
+
 var drawbridge = {
 	auth : {
 		type : 'none'
@@ -1127,10 +1682,15 @@ var drawbridge = {
 	exclusive : false,
 	fields : [],
 	group : 'developer',
-	// EVERY BODY LIVES IN drawbridge-sync. Sending needs the provider clients, the
-	// suppression collection and the queues; segment sync needs the streams. A
-	// published package carrying those makes every consumer carry them, which is
-	// the reason `{}` exists as an answer.
+	// THE BODIES LIVE HERE, beside the declarations that name them. They used to
+	// live in drawbridge-sync because they touch the database, the queues and the
+	// sockets — and a published package cannot carry a controller.
+	//
+	// It does not have to. A hook is a function, so everything it needs is PASSED
+	// IN: `read` for the reads, `canSend` for the opt-out floor, `resolveContact`
+	// for the one write whose RESULT the hook has to count. Everything else a hook
+	// wants done it DESCRIBES — `writes`, `enqueues`, `events` — and the shell
+	// performs it. See lib/connections/contract.js for that shape.
 	hooks : {
 		auth : {
 			// Nothing to connect, revoke, probe or re-scope.
@@ -1151,46 +1711,538 @@ var drawbridge = {
 		// accounts DRAWBRIDGE holds rather than ones a merchant connects.
 		contacts,
 		email : {
-			digest : {},
-			// To organization members. NEVER suppressed and never billed: an
-			// entrant's opt-out must not silence an alert to staff, and staff mail is
-			// not a metered send.
-			notify : {},
-			// To a lead. Suppression applies and the send is billed.
-			send : {}
-		},
-		inbound : false,
-		lifecycle : false,
-		resources : {
-			audiences : false,
-			prices : false,
-			products : false,
-			promotions : false
-		},
-		segment : { sync : {} },
-		sms : { send : {} },
-		webhook : false
-	},
-	icon: icon$3,
-	// PRIVATE: never in the catalog, always available to the builder.
-	private : true,
-	// NOTHING, and HUBSPOT_ACCESS_TOKEN in particular must not be here.
-	//
-	// `requires` gates AVAILABILITY: a name in it that is unset removes the whole
-	// connection. This one is private and contributes every base workflow step —
-	// email.send, sms.send, segment.sync — so gating it on a CRM token would take
-	// all of them away from any deployment without a HubSpot portal, to protect a
-	// sync that is best-effort and already no-ops without a token.
-	//
-	// The test 'a vendor is only available when its environment is configured'
-	// caught exactly that: availableConnections({}) went from [ 'drawbridge' ] to
-	// empty the moment this was added.
-	requires : [],
-	slug : 'drawbridge',
-	// Always on. There is no credential that could go bad and no configuration a
-	// merchant could leave half-finished.
-	status : () => 'active',
-	// DERIVED FROM drawbridge-api/lib/workflows.js, not invented. Every value
+
+			// A PERIODIC SUMMARY to the team, on a schedule trigger rather than per
+			// lead.
+			//
+			// The count is the point: `email.notify` tells the owner one lead arrived
+			// and dampens a spike to one message per bucket, which is deliberately not
+			// a count. This is where "you got 43 entries this week" comes from.
+			digest : async ( { context, step, workflow }, { read } = {} ) => {
+
+				// The window comes from the TRIGGER that fired it, so Daily/Weekly/
+				// Monthly each summarise their own period without a second setting to
+				// keep in step.
+				const days = { day : 1, month : 30, week : 7 }[ workflow?.trigger?.event ] || 7;
+
+				const since = new Date( Date.now() - ( days * 24 * 60 * 60 * 1000 ) );
+				const campaign = workflow?.trigger?.filters?.campaign || null;
+
+				const [ counted ] = await read.aggregate({
+					collection : 'lead',
+					pipeline : [
+						{
+							$match : {
+								createdAt : { $gte : since },
+								organization : workflow.organization,
+								...( campaign && { campaigns : { $in : [ campaign ] } })
+							}
+						},
+						{ $count : 'count' }
+					]
+				});
+
+				const count = Number( counted?.count || 0 );
+
+				const request = { campaign, count, days };
+
+				// Nothing happened, so nobody is told. A digest reading "0 new leads" is
+				// mail the merchant did not ask for and would learn to ignore.
+				if( ! count ) return { message : 'No new leads in the period — digest skipped.', request, response : { skipped : true }, skipped : true };
+
+				const recipients = await teamRecipients({
+					memberIds : step.settings?.members || [],
+					organization : workflow.organization,
+					read
+				});
+
+				// `count` joins the interpolation values so a merchant can write
+				// "{{count}} new entries this week" in the step's own copy.
+				const values = { ...context, count };
+
+				return {
+					message : 'Digest of ' + count + ' new lead(s) queued for ' + recipients.length + ' recipient(s).',
+					request,
+					response : { count, notified : recipients.length },
+					writes : recipients.map( ( member ) => queueNotification({
+						audience : 'member',
+						message : interpolate( step.settings?.message, values ),
+						organization : workflow.organization,
+						send : { type : 'email', email : member.email },
+						title : interpolate( step.settings?.subject, values ),
+						workflow : workflow.id
+					}) )
+				};
+
+			},
+
+			// To the organization's OWN PEOPLE. Never suppressed, never
+			// subscription-gated, no unsubscribe footer — telling an org's staff about
+			// their own leads is not commercial mail to a stranger.
+			//
+			// FREE, permanently. The lead that triggered this run already consumed the
+			// billable action, and `members` is a list — billing here would turn one
+			// lead into five more charges and the org would be paying to read its own
+			// mail. The declaration prices it at zero; the shell bills nothing for
+			// zero.
+			notify : async ( { context, step, workflow }, { read } = {} ) => {
+
+				const memberIds = step.settings?.members || [];
+
+				const request = { members : memberIds.length };
+
+				const recipients = await teamRecipients({ memberIds, organization : workflow.organization, read });
+
+				if( ! recipients.length ){
+
+					return {
+						message : 'No owner or accepted member with an email address — team notification skipped.',
+						request,
+						response : { skipped : true },
+						skipped : true
+					};
+
+				}
+
+				// SPIKE DAMPER, as a fixed window rather than a sliding one.
+				//
+				// This used `coalesce`, which is supersede-and-delay: every new entry
+				// pre-empted the pending job and re-enqueued it 30 seconds out. Under a
+				// genuine spike — entries arriving faster than one per 30s, which is
+				// what viral means — delivery deferred indefinitely and the owner heard
+				// NOTHING until traffic dropped, precisely when they would most want to
+				// know.
+				//
+				// `key` is first-write-wins against a partial unique index: the first
+				// entry in each bucket creates the notification and it goes out
+				// immediately, the rest collide and are refused. A spike yields at most
+				// one heads-up per recipient per bucket, promptly, instead of one
+				// eventually or never.
+				//
+				// Deliberately NOT a change to `coalesce` itself — stream/transaction.js
+				// uses it for balance and credit notices, and its semantics are not ours
+				// to redefine from here.
+				const bucket = Math.floor( Date.now() / ( 15 * 60 * 1000 ) );
+
+				return {
+					message : 'Team notification queued for ' + recipients.length + ' recipient(s).',
+					request,
+					response : { notified : recipients.length },
+					writes : recipients.map( ( member ) => ({
+						...queueNotification({
+							audience : 'member',
+							// Per workflow, recipient AND bucket, so one recipient's damper
+							// can never swallow another's mail and a later bucket is never
+							// mistaken for a duplicate of an earlier one.
+							key : 'team.notify.' + workflow.id + '.' + member.id + '.' + bucket,
+							message : interpolate( step.settings?.message, context ),
+							organization : workflow.organization,
+							send : { type : 'email', email : member.email },
+							title : interpolate( step.settings?.subject, context ),
+							workflow : workflow.id
+						}),
+						// E11000 IS THE DAMPER WORKING: this recipient has already been
+						// told within the bucket. Declared per write rather than assumed by
+						// the shell, because on every other write here a duplicate key is a
+						// real failure.
+						ignoreDuplicate : true
+					}) )
+				};
+
+			},
+
+			// Drawbridge sends lead-facing email itself — no merchant provider gates
+			// it.
+			//
+			// This QUEUES rather than sends: queue/notification.js owns delivery, the
+			// unsubscribe token and the CAN-SPAM footer. The step's job is to say who
+			// and what, correctly, and to refuse early when it must not send at all.
+			send : async ( { context, step, workflow }, { canSend, read } = {} ) => {
+
+				const to = context?.email;
+
+				if( ! to ) throw new Error( 'No email address on context (context.email is required)' );
+
+				const request = { to };
+
+				// PRE-CHECKED HERE so an opted-out recipient skips WITHOUT billing. The
+				// send() gate in queue/notification.js would cancel the doc anyway, but
+				// only after the action had already counted.
+				//
+				// `canSend` is INJECTED rather than read through `read`: suppression is
+				// the only consent source and canSend is its only reader, so a hook
+				// querying the collection itself would be a second reader of the
+				// opt-out floor — and the second one is the one that gets the query
+				// wrong.
+				const { ok : sendable } = await canSend({ channel : 'email', to });
+
+				if( ! sendable ) return { message : 'Recipient has opted out — skipped.', request, response : { skipped : true }, skipped : true };
+
+				// A LIVE SUBSCRIPTION, in two reads. Free organizations get system mail
+				// only; a lead-facing send is a paid feature.
+				const organization = await read.get({ collection : 'organization', query : { id : workflow.organization } });
+
+				const subscription = organization?.subscription
+					? await read.get({ collection : 'subscription', query : { id : organization.subscription } })
+					: null;
+
+				if( subscription?.status !== 'active' ){
+
+					return {
+						message : 'Organization has no active subscription — workflow-step email skipped.',
+						request,
+						response : { skipped : true },
+						skipped : true
+					};
+
+				}
+
+				return {
+					message : 'Email queued for delivery to ' + to + '.',
+					request,
+					response : { queued : true },
+					// NO `connection` FIELD, deliberately: the platform sends this.
+					// `audience : 'lead'` states what the queue would otherwise infer from
+					// shape.
+					//
+					// `campaign` is not decoration. queue/notification.js mints the
+					// unsubscribe token with it, so it decides whether opting out is
+					// scoped to this campaign or the whole organization, and it names the
+					// campaign in the footer. Sending without it silently broadens every
+					// opt-out to the entire organization.
+					writes : [
+						queueNotification({
+							audience : 'lead',
+							campaign : context?.campaign || null,
+							lead : context?.lead || null,
+							message : interpolate( step.settings?.message, context ),
+							organization : workflow.organization,
+							send : { type : 'email', email : to },
+							title : interpolate( step.settings?.subject, context ),
+							workflow : workflow.id
+						})
+					]
+				};
+
+			}
+
+		},
+		inbound : false,
+		lifecycle : false,
+		resources : {
+			audiences : false,
+			prices : false,
+			products : false,
+			promotions : false
+		},
+		segment : {
+
+			// RECALCULATE SEGMENT MEMBERSHIP. The one FAN-OUT hook: it evaluates every
+			// contact in an organization against every segment, which is too much for
+			// one job, so it returns chunks and the shell defers completion.
+			//
+			// Returning `chunks` is the only thing that makes it different. The
+			// declaration, the guards, the step document and the price are the shell's,
+			// exactly as they are for a step that finishes in one go.
+			sync : async ( { context, step }, { chunkSize, logger, read, resolveContact } = {} ) => {
+
+				// The fan-out width is the WORKER FLEET'S number, not the vendor's — how
+				// much work one job may carry is a fact about the machines running it.
+				// Required rather than defaulted, because a default here would silently
+				// disagree with the deployment's own tuning and nothing would say so.
+				if( ! chunkSize ) throw new Error( 'segment.sync needs chunkSize from the shell' );
+
+				const organization = context?.organization;
+
+				const configured = step?.settings?.segment;
+
+				const request = { organization : organization || null, segmentId : configured || null };
+
+				// A segment sitting at `syncing` with nothing running is a spinner that
+				// never stops, so every exit below puts it back — DESCRIBED, and
+				// performed by the shell. Including the throwing exit: the effects ride
+				// out on the error, which is the only way a rejection can still release
+				// what it locked.
+				const release = ( ids, status = 'active' ) => {
+
+					const released = ( ids || [] ).filter( Boolean );
+
+					return {
+						events : organization
+							? released.map( ( id ) => ({
+								event : 'organization.segments',
+								payload : { id, status },
+								room : 'organization.' + organization
+							}) )
+							: [],
+						writes : released.map( ( id ) => ({
+							collection : 'segment',
+							data : { $set : { status } },
+							operation : 'update',
+							query : { id }
+						}) )
+					};
+
+				};
+
+				if( ! organization ){
+
+					return {
+						...release([ configured ]),
+						message : 'Trigger data missing organization id — cannot sync segments.',
+						request,
+						response : { skipped : true },
+						skipped : true
+					};
+
+				}
+
+				const segments = await read.aggregate({
+					collection : 'segment',
+					pipeline : [ { $match : configured ? { id : configured, organization } : { organization } } ]
+				});
+
+				if( ! segments.length ){
+
+					return {
+						...release([ configured ]),
+						message : 'No segments matched the request — nothing to sync.',
+						request,
+						response : { skipped : true },
+						skipped : true
+					};
+
+				}
+
+				const segmentIds = segments.map( ( entry ) => entry.id );
+
+				try {
+
+					let backfilled = 0;
+
+					// A SYSTEM SEGMENT evaluates contacts, so any lead without one has to
+					// get one first or it can never be a member of anything.
+					if( segments.some( ( entry ) => entry.system ) ){
+
+						const contacted = await read.aggregate({
+							collection : 'contact',
+							pipeline : [
+								{ $match : { organization } },
+								{ $project : { _id : 0, leads : 1 } },
+								{ $unwind : '$leads' },
+								{ $group : { _id : null, ids : { $addToSet : '$leads' } } }
+							]
+						});
+
+						const uncontacted = await read.aggregate({
+							collection : 'lead',
+							pipeline : [
+								{ $match : { id : { $nin : contacted[ 0 ]?.ids || [] }, organization } },
+								{ $project : { _id : 0, id : 1 } }
+							]
+						});
+
+						// THE ONE WRITE THIS HOOK CANNOT DESCRIBE, and the reason it is
+						// injected instead. Its RESULT is an input to what the hook returns:
+						// how many contacts this run had to create decides whether the
+						// chunks bill, and a description cannot be counted before it runs.
+						//
+						// So the caller supplies the collaborator — the same shape as the
+						// `shopify` SDK injection elsewhere in this directory — and the
+						// hook still reaches for no controller of its own.
+						for( const lead of uncontacted ){
+
+							try {
+
+								await resolveContact({ leadId : lead.id });
+
+								backfilled += 1;
+
+							} catch ( error ){
+
+								// A duplicate means a concurrent resolve created it first, which
+								// is the outcome we wanted.
+								if( error.code !== 11000 ) throw error;
+
+							}
+
+						}
+
+						logger?.info?.( 'segment.sync.backfill', { backfilled, organization, uncontacted : uncontacted.length });
+
+					}
+
+					const contacts = await read.aggregate({
+						collection : 'contact',
+						pipeline : [
+							{ $match : { organization } },
+							{ $project : { _id : 0, id : 1 } },
+							{ $sort : { id : 1 } }
+						]
+					});
+
+					if( ! contacts.length ){
+
+						return {
+							...release( segmentIds ),
+							message : 'Organization has no contacts to evaluate against segments.',
+							request,
+							response : { skipped : true },
+							skipped : true
+						};
+
+					}
+
+					const contactIds = contacts.map( ( contact ) => contact.id );
+
+					const org = await read.get({ collection : 'organization', query : { id : organization } });
+
+					// THE FAN-OUT. `chunks` tells the shell to open the step rather than
+					// close it, and the SHELL builds one slot per chunk — the slot is the
+					// step document's own shape, so counting them here was a manifest
+					// carrying a schema that is not its.
+					const chunks = [];
+
+					for( let index = 0 ; index < contactIds.length ; index += chunkSize ){
+
+						chunks.push({
+							contactIds : contactIds.slice( index, index + chunkSize ),
+							organization,
+							segments : segmentIds,
+							// A BACKFILL IS NOT BILLABLE. It creates the contacts this run
+							// then evaluates, so charging for it would bill an organization
+							// for work its own history made necessary.
+							usage : ( context?.billable === true && backfilled === 0 ) ? org?.usage || null : null
+						});
+
+					}
+
+					return {
+						chunks,
+						...( configured && { extra : { segment : configured } }),
+						message : 'Queued ' + contactIds.length + ' contacts across ' + chunks.length + ' chunks for segment evaluation.',
+						queue : 'segment',
+						request : { ...request, segments : segmentIds },
+						response : { chunks : chunks.length, contacts : contactIds.length, segments : segments.length }
+					};
+
+				} catch ( error ){
+
+					// A segment left mid-sync shows as errored rather than syncing forever.
+					// The release rides OUT ON THE ERROR because a throw is how a hook
+					// rejects, and the shell performs a rejection's effects before it
+					// records the failure.
+					throw Object.assign( error, release( segmentIds, 'error' ) );
+
+				}
+
+			}
+
+		},
+		sms : {
+
+			// SMS TO A LEAD, through the merchant's own Twilio connection.
+			//
+			// WITHDRAWN from the builder — twilio went, and a connection-gated step
+			// with no connection to gate on could only ever render permanently
+			// disabled. Stored workflows still carry it, so it still runs.
+			//
+			// It looks its own connection up rather than relying on the shell, because
+			// the step is declared by the PRIVATE drawbridge connection (which has
+			// none) while the credential belongs to twilio (which has no manifest).
+			// Platform SMS will remove that split the way it did for email.
+			send : async ( { context, step, workflow }, { canSend, read } = {} ) => {
+
+				const to = context?.phone?.number;
+
+				if( ! to ) throw new Error( 'No phone number on context (context.phone.number is required)' );
+
+				const request = { to };
+
+				const connection = await read.get({
+					collection : 'connection',
+					query : { organization : workflow.organization, slug : 'twilio', status : 'active' }
+				});
+
+				if( ! connection ) return { message : 'No active Twilio SMS connection — workflow-step SMS skipped.', request, response : { skipped : true }, skipped : true };
+
+				// PRE-CHECKED so an opted-out recipient skips WITHOUT billing. The
+				// carrier opt-out is a legal obligation, not a preference.
+				const { ok : sendable } = await canSend({ channel : 'sms', to : context.phone });
+
+				if( ! sendable ) return { message : 'Recipient has opted out — skipped.', request, response : { skipped : true }, skipped : true };
+
+				return {
+					message : 'SMS queued for delivery to ' + to + ' via twilio.',
+					request,
+					response : { provider : 'twilio', queued : true },
+					// QUEUES rather than sends: queue/notification.js owns delivery, the
+					// carrier opt-out line and the segment count this is billed on.
+					writes : [
+						queueNotification({
+							connection : connection.id,
+							message : interpolate( step.settings?.message, context ),
+							organization : workflow.organization,
+							send : { phone : { number : to }, type : 'phone' },
+							title : interpolate( step.settings?.subject, context ),
+							workflow : workflow.id
+						})
+					]
+				};
+
+			}
+
+		},
+		webhook : false
+	},
+	icon: icon$3,
+	// PRIVATE: never in the catalog, always available to the builder.
+	private : true,
+	// THE PLATFORM'S OWN SENDING CREDENTIALS — SendGrid, Twilio, and the internal
+	// HubSpot portal. No merchant ever sees these; they are what an admin types on
+	// the provider screen so that Drawbridge itself can send.
+	//
+	// They belong on THIS manifest because this is the connection that sends: the
+	// email, sms and segment hooks below are the only things that spend them, and
+	// a private connection is still where a vendor fact lives.
+	//
+	// UNLIKE every public vendor, none of these appear in `requires` — see the
+	// comment there. Availability and configuration are different questions, and a
+	// missing CRM token must not take every base workflow step away.
+	provider : {
+		fields : [
+			{ input : 'email', key : 'accountSender', credential : 'SENDGRID_FROM_ADDRESS', label : 'Account sender', message : 'Verification codes and security alerts send from here.', required : true },
+			{ input : 'password', key : 'apiKey', credential : 'SENDGRID_API_KEY', label : 'SendGrid API key', redact : true, required : true },
+			// NOT required. The CRM sync is best-effort internal tooling and no-ops
+			// without a token — requiring it would make the whole drawbridge provider
+			// read not-live over something no merchant ever sees.
+			{ input : 'password', key : 'hubspotToken', credential : 'HUBSPOT_ACCESS_TOKEN', label : 'HubSpot access token', message : 'Drawbridge\'s own CRM portal. Internal — no merchant sees this.', redact : true },
+			// Optional: SENDGRID_SEND_FROM_ADDRESS is not boot-required in sync
+			// either. Unset, it degrades to the account sender rather than
+			// refusing to start.
+			{ input : 'email', key : 'leadSender', credential : 'SENDGRID_SEND_FROM_ADDRESS', label : 'Lead sender', message : 'The default for lead-facing mail when a merchant has not verified their own domain.' },
+			{ input : 'text', key : 'smsFrom', credential : 'TWILIO_ACCOUNT_FROM', label : 'SMS number', required : true },
+			{ input : 'password', key : 'smsSid', credential : 'TWILIO_ACCOUNT_SID', label : 'Twilio account SID', redact : true, required : true },
+			{ input : 'password', key : 'smsToken', credential : 'TWILIO_AUTH_TOKEN', label : 'Twilio auth token', redact : true, required : true }
+		]
+	},
+	// NOTHING, and HUBSPOT_ACCESS_TOKEN in particular must not be here.
+	//
+	// `requires` gates AVAILABILITY: a name in it that is unset removes the whole
+	// connection. This one is private and contributes every base workflow step —
+	// email.send, sms.send, segment.sync — so gating it on a CRM token would take
+	// all of them away from any deployment without a HubSpot portal, to protect a
+	// sync that is best-effort and already no-ops without a token.
+	//
+	// The test 'a vendor is only available when its environment is configured'
+	// caught exactly that: availableConnections({}) went from [ 'drawbridge' ] to
+	// empty the moment this was added.
+	requires : [],
+	slug : 'drawbridge',
+	// Always on. There is no credential that could go bad and no configuration a
+	// merchant could leave half-finished.
+	status : () => 'active',
+	// DERIVED FROM drawbridge-api/lib/workflows.js, not invented. Every value
 	// below — trigger, billable, settings — is what that catalog and the workflow
 	// route already enforce today, because this replaces them rather than
 	// competing with them.
@@ -1212,11 +2264,11 @@ var drawbridge = {
 				key : 'Email — Digest',
 				queue : 'notification',
 				settings : {
-					// The organization OWNER is always a recipient, resolved in sync,
-					// so this is additional recipients rather than the list. It cannot
-					// be required: the members endpoint is owner-gated and the owner is
-					// not a member document, so a solo merchant has nothing to pick and
-					// could never save the step.
+					// The organization OWNER is always a recipient, resolved by the
+					// hook, so this is additional recipients rather than the list. It
+					// cannot be required: the members endpoint is owner-gated and the
+					// owner is not a member document, so a solo merchant has nothing to
+					// pick and could never save the step.
 					members : { of : 'string', type : 'array' },
 					message : { required : true, type : 'string' },
 					subject : { required : true, type : 'string' }
@@ -1327,11 +2379,11 @@ var drawbridge = {
 // lib/ directly. A bare .svg import would need a bundler loader and force the
 // tests onto dist/, which is a worse trade than one line of wrapper.
 var icon$2 = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xmlns="http://www.w3.org/2000/svg">
-<rect width="500" height="500" fill="white"/>
+<rect width="500" height="500" fill="#FF4B32"/>
 <path d="M365.047 327.038H134.954V172.964H365.047L316.856 250.001L365.047 327.038Z" fill="#232121"/>
 </svg>`;
 
-const api = async ( path, { fetcher = fetch, method = 'GET', payload, token } ) => {
+const api$1 = async ( path, { fetcher = fetch, method = 'GET', payload, token } ) => {
 
 	const response = await fetcher( 'https://a.klaviyo.com/api' + path, {
 		...( payload && { body : JSON.stringify( payload ) }),
@@ -1395,7 +2447,8 @@ var klaviyo = {
 	// differently, and it says so in hooks.auth.token rather than as a flag here.
 	auth : {
 		oauth : {
-			// NAMES the env vars holding OUR application's client. One identity,
+			// NAMES the credentials holding OUR application's client — keys into
+			// the stored provider credentials, not env vars. One identity,
 			// every merchant — the token is the merchant's and arrives from their
 			// own consent, which is what stops one organization reading another's
 			// data.
@@ -1544,9 +2597,9 @@ var klaviyo = {
 			// renders an empty "Klaviyo account" field, because the merchant is
 			// never asked which account they connected — the consent already
 			// decided it, and asking again would be a question we can answer.
-			connect : async ({ fetcher, tokens }) => {
+			connect : async ( { tokens }, { fetcher } = {} ) => {
 
-				const body = await api( '/accounts', { fetcher, token : tokens.accessToken });
+				const body = await api$1( '/accounts', { fetcher, token : tokens.accessToken });
 
 				const account = body?.data?.[ 0 ];
 
@@ -1563,7 +2616,7 @@ var klaviyo = {
 			//
 			// Basic auth with our client, exactly like the token exchange — the
 			// token being revoked is the subject, not the credential.
-			disconnect : async ({ clientId, clientSecret, fetcher = fetch, manifest, settings }) => {
+			disconnect : async ( { clientId, clientSecret, manifest, settings }, { fetcher = fetch } = {} ) => {
 
 				const token = settings?.refreshToken || settings?.accessToken;
 
@@ -1595,7 +2648,7 @@ var klaviyo = {
 			// the refresh token is the only thing that asks Klaviyo.
 			//
 			// It also keeps the grant warm against the 90-day idle window above.
-			probe : async ({ clientId, clientSecret, fetcher, manifest, settings }) => {
+			probe : async ( { clientId, clientSecret, manifest, settings }, { fetcher } = {} ) => {
 
 				const token = await accessToken({
 					clientId,
@@ -1634,14 +2687,13 @@ var klaviyo = {
 		commerce : false,
 
 		// The verb the contacts.sync step points at. It does the work — including
-		// writing the profile id back onto the lead — and returns what happened.
 		contacts : {
 
 			// Not yet. Suppression syncs an opt-out as unsubscribed, which is a
 			// different thing from deleting the profile.
 			remove : false,
 
-			sync : async ({ contact, fetcher, lead, settings, suppressed, token }) => {
+			sync : async ( { contact, lead, settings, suppressed, token }, { fetcher } = {} ) => {
 
 				const list = settings?.list;
 
@@ -1661,7 +2713,7 @@ var klaviyo = {
 				// exist on a single-address record.
 				const totals = contact?.totals || {};
 
-				const profile = await api( '/profiles/', {
+				const profile = await api$1( '/profiles/', {
 					fetcher,
 					method : 'POST',
 					payload : {
@@ -1702,7 +2754,7 @@ var klaviyo = {
 				//
 				// `suppressed` arrives as an argument because canSend() is sync's —
 				// a manifest cannot reach it, and this rule is too important to infer.
-				await api( '/profile-subscription-bulk-create-jobs/', {
+				await api$1( '/profile-subscription-bulk-create-jobs/', {
 					fetcher,
 					method : 'POST',
 					payload : {
@@ -1768,7 +2820,7 @@ var klaviyo = {
 			// it, so one call quietly returns the first ten lists and an account
 			// with more shows a picker missing the one they wanted, with nothing to
 			// indicate anything was cut.
-			audiences : async ({ cursor, fetcher, limit = 100, search, token }) => {
+			audiences : async ( { cursor, limit = 100, search, token }, { fetcher } = {} ) => {
 
 				// `limit` is what the CALLER wants back rather than what one request
 				// can carry — the loop keeps pulling until it has that many or the
@@ -1783,7 +2835,7 @@ var klaviyo = {
 
 				while( next && audiences.length < limit && pages < 20 ){
 
-					const body = await api( next, { fetcher, token });
+					const body = await api$1( next, { fetcher, token });
 
 					for( const list of ( body?.data || [] ) ){
 
@@ -1830,6 +2882,16 @@ var klaviyo = {
 
 	},
 	icon: icon$2,
+	// DRAWBRIDGE'S OWN CREDENTIALS for this vendor, as opposed to a merchant's —
+	// what an admin types on the provider screen. Declared here rather than in a
+	// table in lib/providers.js, so a vendor's credentials sit beside the
+	// `requires` that names the same variables.
+	provider : {
+		fields : [
+			{ input : 'text', key : 'clientId', credential : 'KLAVIYO_OAUTH_CLIENT_ID', label : 'Client ID', required : true },
+			{ input : 'password', key : 'clientSecret', credential : 'KLAVIYO_OAUTH_CLIENT_SECRET', label : 'Client secret', redact : true, required : true }
+		]
+	},
 	requires : [
 		'KLAVIYO_OAUTH_CLIENT_ID',
 		'KLAVIYO_OAUTH_CLIENT_SECRET'
@@ -1937,6 +2999,54 @@ const base = ( dc ) => {
 
 };
 
+// ONE REQUEST SHAPE for the Marketing API, the way Klaviyo's file has one.
+//
+// Bearer, not Basic. Mailchimp's fundamentals doc states "API keys and OAuth 2
+// tokens can be used to make authenticated requests the same way", so one header
+// serves both — the Basic form this used under keys was never OAuth-compatible.
+//
+// The host comes from base( dc ) on every call rather than being captured once:
+// there is no fixed host, and a request assembled without the stored data centre
+// is a 404 nobody can read.
+const api = async ( path, { dc, fetcher = fetch, method = 'GET', payload, token } ) => {
+
+	const response = await fetcher( base( dc ) + path, {
+		...( payload && { body : JSON.stringify( payload ) }),
+		headers : {
+			authorization : 'Bearer ' + token,
+			...( payload && { 'content-type' : 'application/json' })
+		},
+		method,
+		signal : AbortSignal.timeout( 15000 )
+	});
+
+	if( ! response.ok ){
+
+		throw Object.assign(
+			new Error( 'Mailchimp refused the request (' + response.status + ')' ),
+			{ status : response.status }
+		);
+
+	}
+
+	return response.json();
+
+};
+
+// THE MEMBER ID IS COMPUTED, not handed back: Mailchimp addresses a member by
+// "the MD5 hash of the lowercase version of the list member's email address".
+//
+// That is what makes PUT an UPSERT — the same person hashes to the same id, so a
+// resync updates rather than creating a second member — and it is why the
+// address is lowercased before hashing rather than after: Ada@Example.com and
+// ada@example.com are one subscriber to Mailchimp and would otherwise be two.
+//
+// MD5 is the vendor's choice and nothing here is authenticated by it; it is an
+// address, not a secret.
+const subscriberHash = ( email ) => createHash( 'md5' )
+	.update( String( email ).trim().toLowerCase() )
+	.digest( 'hex' );
+
 // Mailchimp — contact sync, not a sender.
 var mailchimp = {
 	// OAUTH 2, authorization code. Every url below is quoted from
@@ -1980,7 +3090,9 @@ var mailchimp = {
 		confirm : 'Disconnecting removes Drawbridge\'s stored Mailchimp access. You can also remove Drawbridge from the Authorized Apps page in your Mailchimp account. Your contacts stay in both Drawbridge and Mailchimp — neither list is deleted.',
 		description : [
 			'Drawbridge no longer sends email through Mailchimp. Notification email now sends from Drawbridge itself, and verifying a domain under Networking in your organization settings puts your own brand in the from line.',
-			'This connection is becoming the way your Drawbridge contacts sync into a Mailchimp audience. Audience syncing is not live yet, so connecting today does nothing except choose the audience it will use when it ships.'
+			'Connecting Mailchimp lets Drawbridge sync the contacts your campaigns collect into a Mailchimp audience, so the people who enter a giveaway can be marketed to alongside the rest of your list.',
+			'Anyone who has opted out in Drawbridge is synced as unsubscribed rather than omitted, so a person who asked not to be contacted stays suppressed in both systems instead of quietly reappearing.',
+			'Someone who unsubscribed inside Mailchimp keeps that choice: a resync only sets the status of a subscriber Mailchimp has never seen before.'
 		],
 		excerpt : 'Sync your Drawbridge contacts into a Mailchimp audience.',
 		guide : [
@@ -2023,7 +3135,7 @@ var mailchimp = {
 			// The header here is `OAuth <token>`, not Bearer — that is specific to
 			// the metadata endpoint. Marketing API calls take Bearer; see the
 			// audiences hook.
-			connect : async ({ fetcher = fetch, tokens }) => {
+			connect : async ( { tokens }, { fetcher = fetch } = {} ) => {
 
 				const response = await fetcher( 'https://login.mailchimp.com/oauth2/metadata', {
 					headers : {
@@ -2066,7 +3178,89 @@ var mailchimp = {
 			token : authToken
 		},
 		commerce : false,
-		contacts : { remove : false, sync : false },
+
+		// The verb the contacts.sync step points at.
+		contacts : {
+
+			// Not yet. Suppression syncs an opt-out as unsubscribed, which is a
+			// different thing from deleting the member — and Mailchimp's own delete is
+			// permanent, so the address can never be re-added.
+			remove : false,
+
+			// PUT /lists/{list_id}/members/{subscriber_hash} — an UPSERT, which is
+			// why there is no create-or-update branch here. Quoted from Mailchimp's
+			// Marketing API reference for the list-members resource.
+			sync : async ( { lead, settings, suppressed, token }, { fetcher } = {} ) => {
+
+				const audience = settings?.audience;
+
+				// status() already stops a connection reaching Active without an
+				// audience; this is the belt to that braces. A workflow saved before
+				// the audience was chosen must not silently write into nothing.
+				if( ! audience ) return { message : 'No Mailchimp audience is chosen for this connection.', skipped : true };
+
+				const email = lead?.canonical?.email?.value || lead?.email;
+
+				// A Mailchimp member IS an email address — there is no other identity
+				// to write, so a lead without one is skipped rather than failed.
+				if( ! email ) return { message : 'That lead has no email address to sync.', skipped : true };
+
+				const hash = subscriberHash( email );
+
+				// SUPPRESSED PEOPLE ARE SYNCED AS UNSUBSCRIBED, NEVER OMITTED.
+				//
+				// Omitting them means Mailchimp never learns they said no, so the
+				// merchant can import them from somewhere else and start mailing them
+				// again. Pushing them as unsubscribed makes the suppression travel with
+				// the person, which is the reason this connection is allowed to send
+				// anything at all.
+				//
+				// `suppressed` arrives as an argument because canSend() is sync's — a
+				// manifest cannot reach it, and this rule is too important to infer.
+				//
+				// STATUS_IF_NEW EVERYWHERE, `status` ONLY TO SUPPRESS, and the
+				// asymmetry is the whole point. status_if_new applies to a member being
+				// CREATED and is ignored for one that already exists, so a resync
+				// cannot overwrite what a subscriber themselves chose — someone who
+				// unsubscribed inside Mailchimp stays unsubscribed. An opt-out is the
+				// one thing allowed to overwrite, because it travels in the direction
+				// that protects the person; so suppression sets `status` outright, and
+				// sets status_if_new alongside it because the upsert leg still needs a
+				// status for a member Mailchimp has never seen.
+				const member = await api( '/lists/' + audience + '/members/' + hash, {
+					dc : settings?.dc,
+					fetcher,
+					method : 'PUT',
+					payload : {
+						email_address : email,
+						// FNAME ONLY. Unlike Klaviyo, Mailchimp's custom fields are not
+						// schemaless — a merge tag that does not exist on the audience is
+						// refused, taking the whole request with it — and FNAME is one of
+						// the two tags every audience is created with. The Drawbridge
+						// totals Klaviyo receives cannot travel until something registers
+						// merge fields on the chosen audience, which is lifecycle.register's
+						// job and is not built.
+						...( lead?.name && { merge_fields : { FNAME : String( lead.name ).trim().split( /\s+/ )[ 0 ] } }),
+						...( suppressed && { status : 'unsubscribed' }),
+						status_if_new : suppressed ? 'unsubscribed' : 'subscribed'
+					},
+					token
+				});
+
+				return {
+					// Merged into `context` for later steps in this run.
+					context : { mailchimpMemberId : member?.id || hash },
+					message : suppressed
+						? 'Synced to Mailchimp as unsubscribed — this contact has opted out.'
+						: 'Synced to the Mailchimp audience.',
+					// Recorded on the run for support to read back, not a write
+					// instruction — the hook has already written what it needed to.
+					response : { mailchimpMemberId : member?.id || hash }
+				};
+
+			}
+
+		},
 		// Drawbridge sends its own notification email and SMS, and owns its own
 		// segments — see the private `drawbridge` manifest. A vendor answering
 		// these would be a second sender, which is the arrangement the platform
@@ -2086,36 +3280,16 @@ var mailchimp = {
 			// successful — the same silent truncation Klaviyo has, at a different
 			// number. Paged against total_items so an account past a thousand still
 			// resolves.
-			audiences : async ({ cursor, fetcher = fetch, limit = 100, search, settings, token }) => {
-
-				// Bearer, not Basic. Mailchimp's fundamentals doc states "API keys and
-				// OAuth 2 tokens can be used to make authenticated requests the same
-				// way", so one header serves both — the Basic form this used under
-				// keys was never OAuth-compatible.
-				const dc = settings?.dc;
+			audiences : async ( { cursor, limit = 100, search, settings, token }, { fetcher } = {} ) => {
 
 				const count = Math.min( limit, 1000 );
 				const offset = Number( cursor || 0 );
 
-				const response = await fetcher(
-					base( dc ) + '/lists?count=' + count + '&offset=' + offset + '&fields=lists.id,lists.name,total_items',
-					{
-						headers : { authorization : 'Bearer ' + token },
-						signal : AbortSignal.timeout( 15000 )
-					}
+				const body = await api(
+					'/lists?count=' + count + '&offset=' + offset + '&fields=lists.id,lists.name,total_items',
+					{ dc : settings?.dc, fetcher, token }
 				);
 
-				if( ! response.ok ){
-
-					throw Object.assign(
-						new Error( 'Mailchimp refused the request (' + response.status + ')' ),
-						{ status : response.status }
-					);
-
-				}
-
-				const body = await response.json();
-
 				const audiences = ( body?.lists || [] ).map( ( list ) => ({ id : list.id, title : list?.name || list.id }) );
 
 				// Mailchimp's /lists takes no name filter, so a term is matched against
@@ -2150,6 +3324,15 @@ var mailchimp = {
 		webhook : false
 	},
 	icon: icon$1,
+	// DRAWBRIDGE'S OWN CREDENTIALS for this vendor, as opposed to a merchant's —
+	// what an admin types on the provider screen, beside the `requires` naming the
+	// same variables.
+	provider : {
+		fields : [
+			{ input : 'text', key : 'clientId', credential : 'MAILCHIMP_OAUTH_CLIENT_ID', label : 'Client ID', required : true },
+			{ input : 'password', key : 'clientSecret', credential : 'MAILCHIMP_OAUTH_CLIENT_SECRET', label : 'Client secret', redact : true, required : true }
+		]
+	},
 	// The OAuth client this deployment registered. Without both, the vendor drops
 	// out of availableConnections rather than offering a Connect button that
 	// cannot complete.
@@ -2158,32 +3341,66 @@ var mailchimp = {
 		'MAILCHIMP_OAUTH_CLIENT_SECRET'
 	],
 	slug : 'mailchimp',
-	// A key with no audience chosen is authenticated and inert. Mailchimp also
-	// needs its merge fields created on that audience before any Drawbridge total
-	// can be written to a member — unlike Klaviyo, its custom fields are not
-	// schemaless — so the audience must be picked before lifecycle.register has
-	// anything to register against.
+	// A grant with no audience chosen is authenticated and useless — the sync has
+	// nowhere to put anyone — so the card must say Pending rather than Active over
+	// nothing. Mailchimp also needs its merge fields created on that audience
+	// before any Drawbridge total can be written to a member — unlike Klaviyo, its
+	// custom fields are not schemaless — so the audience must be picked before
+	// lifecycle.register has anything to register against.
 	status : ( data ) => ( data?.settings?.audience ? data.status : 'pending' ),
-	// No steps: audience sync has not shipped, so this vendor contributes nothing
-	// to a workflow yet. An empty steps object is the honest declaration — the
-	// catalog renders the connection, and no builder offers a step it cannot run.
-	steps : {},
-	tasks : ( data ) => [
-		...( data?.settings?.audience
-			? []
-			: [
-				{
-					message : 'Choose which Mailchimp audience your contacts should sync into. Until you do, nothing is being synced.',
-					title : 'Choose an audience'
-				}
-			]
-		),
-		{
-			message : 'Contact syncing to Mailchimp audiences has not shipped yet, and this connection no longer sends your email. Nothing is being sent to Mailchimp right now.',
-			title : 'Audience sync not available yet',
-			type : 'warning'
+
+	steps : {
+
+		contacts : {
+
+			// A DECLARATION, not the work. It names the hook that does the work, and
+			// the nesting IS the name: this is `step.contacts.sync`, the string a
+			// workflow document stores. Klaviyo and Attentive declare the same type —
+			// a step belongs to the capability, not to whoever implements it — and the
+			// connection on the step document is what says which vendor runs.
+			sync : ({ data }) => ({
+
+				hook : 'contacts.sync',
+
+				// NO ACCOUNT NAME TO INTERPOLATE, unlike Klaviyo. Mailchimp's
+				// auth.connect deliberately stores only the data centre (a test pins
+				// that), and settings.audience is an opaque list id no merchant would
+				// recognise in a builder label — so the label names the vendor rather
+				// than showing a string like a1b2c3d4e5.
+				key : 'Sync contact to Mailchimp',
+
+				queue : 'connection',
+
+				// Nothing for a merchant to configure on the step itself — the audience
+				// is chosen once on the connection. Declared empty rather than omitted,
+				// so "this step takes no settings" and "nobody thought about settings"
+				// stay different statements.
+				settings : {},
+
+				// BOTH triggers, for the same reason as Klaviyo: lead.insert alone only
+				// ever fires for someone with no history yet, and crossing into a
+				// segment is the other moment a contact is worth pushing.
+				triggers : [ 'lead.insert', 'segment.contact.add' ],
+
+				// One source for cost: what the builder discloses before a merchant
+				// adds this step, and what is charged when it runs.
+				usage : { actions : 1 }
+
+			})
+
 		}
-	],
+
+	},
+	// WHY, in the merchant's words, and what to do about it.
+	tasks : ( data ) => ( data?.settings?.audience
+		? []
+		: [
+			{
+				message : 'Choose which Mailchimp audience your contacts should sync into. Until you do, nothing is being synced.',
+				title : 'Choose an audience'
+			}
+		]
+	),
 	title : 'Mailchimp'
 };
 
@@ -2194,24 +3411,39 @@ var mailchimp = {
 // lib/ directly. A bare .svg import would need a bundler loader and force the
 // tests onto dist/, which is a worse trade than one line of wrapper.
 var icon = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xmlns="http://www.w3.org/2000/svg">
-<rect width="500" height="500" fill="white"/>
-<path fill-rule="evenodd" clip-rule="evenodd" d="M309.524 407.192L308.799 128.423C306.921 126.545 303.258 127.112 301.827 127.531L292.29 130.487C291.113 126.613 289.585 122.854 287.726 119.258C280.959 106.337 271.069 99.5052 259.096 99.4866H259.059C258.259 99.4866 257.469 99.5609 256.67 99.626L256.577 99.6353C256.231 99.2089 255.871 98.7935 255.499 98.3897C250.293 92.8125 243.601 90.0889 235.588 90.3213C220.139 90.7675 204.755 101.941 192.271 121.786C183.487 135.757 176.823 153.298 174.917 166.878L144.493 176.313C135.542 179.129 135.263 179.408 134.082 187.858C133.199 194.253 109.766 375.69 109.766 375.69L306.159 409.692L309.524 407.192ZM245.181 103.065C242.569 101.346 239.511 100.546 235.885 100.621C212.033 101.308 191.23 138.611 185.923 163.467L208.771 156.384L212.851 155.119C215.845 139.336 223.355 122.957 233.181 112.416C236.616 108.639 240.671 105.477 245.172 103.065H245.181ZM224.145 151.615L256.94 141.446C257.042 132.894 256.112 120.252 251.836 111.329C247.282 113.207 243.452 116.497 240.7 119.444C233.329 127.373 227.315 139.466 224.155 151.615H224.145ZM267.211 138.267L282.455 133.536C280.02 125.616 274.238 112.342 262.517 110.111C266.161 119.527 267.099 130.431 267.211 138.267Z" fill="#95BF47"/>
-<path d="M353.528 149.156C352.356 149.063 329.657 148.709 329.657 148.709C329.657 148.709 310.666 130.249 308.789 128.362C308.062 127.691 307.141 127.268 306.158 127.153V409.64L391.257 388.456C391.257 388.456 356.53 153.366 356.307 151.758C356.199 151.075 355.866 150.448 355.361 149.976C354.856 149.505 354.216 149.216 353.528 149.156Z" fill="#5E8E3E"/>
-<path d="M258.993 193.019L249.103 230.052C249.103 230.052 238.079 225.023 225 225.85C205.833 227.059 205.628 239.171 205.824 242.21C206.865 258.756 250.376 262.381 252.821 301.171C254.745 331.688 236.656 352.574 210.592 354.21C179.313 356.19 162.089 337.711 162.089 337.711L168.716 309.472C168.716 309.472 186.052 322.569 199.921 321.686C208.993 321.119 212.228 313.738 211.903 308.514C210.536 286.921 175.102 288.185 172.862 252.695C170.985 222.811 190.57 192.554 233.803 189.821C250.46 188.762 258.993 193.028 258.993 193.028" fill="white"/>
+<rect width="500" height="500" fill="#95C049"/>
+<path d="M292.997 147.633C292.997 147.633 289.98 148.495 285.023 150.004C284.161 147.202 282.868 143.969 281.144 140.521C275.54 129.744 267.134 123.925 257.22 123.925C256.574 123.925 255.927 123.925 255.065 124.141C254.849 123.71 254.418 123.494 254.203 123.063C249.892 118.322 244.289 116.166 237.607 116.382C224.676 116.813 211.744 126.081 201.399 142.676C194.071 154.314 188.468 168.97 186.959 180.393C172.088 184.919 161.743 188.152 161.527 188.367C153.984 190.738 153.768 190.954 152.906 198.066C151.613 203.454 132 355.4 132 355.4L294.937 383.633V147.202C294.075 147.418 293.429 147.418 292.997 147.633ZM255.281 159.271C246.66 161.858 237.176 164.875 227.909 167.677C230.495 157.547 235.668 147.418 241.702 140.736C244.073 138.365 247.306 135.564 250.97 133.839C254.634 141.598 255.496 152.159 255.281 159.271ZM237.823 125.003C240.84 125.003 243.427 125.649 245.582 126.943C242.133 128.667 238.685 131.469 235.452 134.702C227.262 143.538 221.012 157.332 218.426 170.479C210.667 172.85 202.908 175.22 195.796 177.376C200.322 156.901 217.779 125.649 237.823 125.003ZM212.607 243.542C213.469 257.335 249.892 260.353 252.048 292.897C253.556 318.545 238.47 336.002 216.701 337.295C190.407 339.02 175.967 323.502 175.967 323.502L181.571 299.794C181.571 299.794 196.011 310.786 207.649 309.924C215.193 309.493 217.995 303.242 217.779 298.932C216.701 280.828 186.959 281.905 185.019 252.163C183.295 227.377 199.675 202.161 235.883 199.79C249.892 198.928 257.005 202.377 257.005 202.377L248.815 233.412C248.815 233.412 239.547 229.102 228.555 229.964C212.607 231.041 212.391 241.171 212.607 243.542ZM263.902 156.685C263.902 150.219 263.039 140.952 260.022 133.193C269.936 135.133 274.678 146.124 276.833 152.806C272.954 153.883 268.643 155.176 263.902 156.685Z" fill="white"/>
+<path d="M300.325 382.771L368 365.96C368 365.96 338.904 169.185 338.689 167.892C338.473 166.599 337.396 165.737 336.318 165.737C335.24 165.737 316.274 165.306 316.274 165.306C316.274 165.306 304.636 154.099 300.325 149.788V382.771Z" fill="white"/>
 </svg>`;
 
 // THE SHARED HALF OF inbound.verify.
 //
 // A vendor whose scheme is "hash the raw body with a shared secret and compare,
 // constant-time, against a header" declares that shape as `inbound.signature`
-// data on its manifest (algorithm, encoding, the env var naming the secret) and
+// data on its manifest (algorithm, encoding, the NAME of the credential) and
 // wires this straight in as its hook — Shopify does exactly that.
 //
 // A vendor whose scheme is not that shape — Twilio signs the REGISTERED URL
 // rather than the body, a JWT-bodied vendor verifies against a JWKS — writes its
 // own inbound.verify instead. That is why verify is a hook and not config: this
 // file covers the common case, not the contract.
-const verifySignature = ({ body, descriptor, headers }) => {
+const verifySignature = ({ body, descriptor, headers, secret }) => {
+
+	// THE MANIFEST STILL DECLARES THE NAME, the caller supplies the value.
+	// descriptor.signature.secret is 'SHOPIFY_API_SECRET' and stays that way —
+	// naming which credential a vendor needs is the manifest's job. Reading it is
+	// not: the value lives encrypted in the `provider` collection, and a package
+	// that reached into process.env for it would force every service to copy the
+	// collection back into its environment at boot before this could work.
+	//
+	// A 500 rather than the 401 below, because a secret we never loaded is our
+	// misconfiguration and must not be indistinguishable in the logs from the
+	// forged request that gets the same door slammed on it.
+	if( ! secret ){
+
+		throw Object.assign( new Error( 'Missing webhook secret: ' + descriptor.signature.secret ), { status : 500 });
+
+	}
 
 	const provided = headers[ descriptor.headers.signature ];
 
@@ -2221,33 +3453,102 @@ const verifySignature = ({ body, descriptor, headers }) => {
 
 	}
 
-	const digest = createHmac( descriptor.signature.algorithm, process.env[ descriptor.signature.secret ] )
-		.update( body )
-		.digest( descriptor.signature.encoding );
+	const digest = createHmac( descriptor.signature.algorithm, secret )
+		.update( body )
+		.digest( descriptor.signature.encoding );
+
+	// Buffers of different lengths crash timingSafeEqual rather than compare
+	// false — decided here, before the length itself becomes a timing signal.
+	const digestBuffer = Buffer.from( digest, descriptor.signature.encoding );
+	const providedBuffer = Buffer.from( provided, descriptor.signature.encoding );
+
+	if(
+		digestBuffer.length !== providedBuffer.length ||
+		! timingSafeEqual( digestBuffer, providedBuffer )
+	){
+
+		throw Object.assign( new Error( 'Invalid webhook signature' ), { status : 401 });
+
+	}
+
+	// The proof and the parse happen together on purpose. Nothing downstream of
+	// inbound.verify ever sees the raw bytes, which is what makes acting on
+	// unverified data impossible rather than merely discouraged.
+	return JSON.parse( body.toString() );
+
+};
+
+// THE SHARED HALF OF inbound.event, for a vendor that puts it in a header.
+const readEventHeader = ({ descriptor, headers }) => headers[ descriptor.headers.event ];
+
+// ── ORDER ATTRIBUTION, the vendor's own arithmetic ───────────────────────────
+//
+// Orders are attributed via `_drwbrdg_*` line-item properties injected at
+// add-to-cart (NOT url params); only items tagged with `_drwbrdg_ca` count
+// toward a conversion's attributed gross. This is Shopify's payload shape, so
+// it lives with the vendor — it was drawbridge-sync's lib/attribution.js.
+
+const toLine = ({
+	price,
+	product_id : productId,
+	quantity,
+	title,
+	variant_id : variantId,
+	variant_title : variantTitle
+}) => ({
+	price : parseFloat( price ) || 0,
+	productId : productId ? 'gid://shopify/Product/' + productId : null,
+	quantity : quantity || 1,
+	title : title || null,
+	variantId : variantId ? 'gid://shopify/ProductVariant/' + variantId : null,
+	variantTitle : variantTitle || null
+});
+
+// Reduce an order's line items to the campaign attribution: the first tagged
+// item's property map wins for ids (attrMap), gross/lines accumulate across
+// every tagged item. Untagged items contribute nothing.
+const attributeLineItems = ( lineItems = [] ) => lineItems.reduce(
+	( acc, item ) => {
+
+		const attrs = ( item.properties || [] ).reduce(
+			( map, { name, value } ) => {
+
+				map[ name ] = value;
+
+				return map;
+
+			},
+			{}
+		);
+
+		if( ! attrs[ '_drwbrdg_ca' ] ) return acc;
+
+		if( ! Object.keys( acc.attrMap ).length ) acc.attrMap = attrs;
+
+		const line = toLine( item );
 
-	// Buffers of different lengths crash timingSafeEqual rather than compare
-	// false — decided here, before the length itself becomes a timing signal.
-	const digestBuffer = Buffer.from( digest, descriptor.signature.encoding );
-	const providedBuffer = Buffer.from( provided, descriptor.signature.encoding );
+		acc.attributedGross += line.price * line.quantity;
+		acc.attributedLines.push( line );
 
-	if(
-		digestBuffer.length !== providedBuffer.length ||
-		! timingSafeEqual( digestBuffer, providedBuffer )
-	){
+		return acc;
 
-		throw Object.assign( new Error( 'Invalid webhook signature' ), { status : 401 });
+	},
+	{ attrMap : {}, attributedGross : 0, attributedLines : [] }
+);
 
-	}
+// Unambiguous alphabet and length, because a merchant reads these aloud and
+// types them into a checkout.
+const generateDiscountCode = customAlphabet( '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ', 8 );
 
-	// The proof and the parse happen together on purpose. Nothing downstream of
-	// inbound.verify ever sees the raw bytes, which is what makes acting on
-	// unverified data impossible rather than merely discouraged.
-	return JSON.parse( body.toString() );
+// Rotate before the window closes rather than at it: Shopify's refresh token has
+// an expiry, and a rotation attempted after it has passed cannot succeed.
+const REFRESH_TOKEN_FRESHNESS_BUFFER_MS = 5 * 24 * 60 * 60 * 1000;
 
-};
+const OAUTH_ERROR_SOURCE = 'oauth';
 
-// THE SHARED HALF OF inbound.event, for a vendor that puts it in a header.
-const readEventHeader = ({ descriptor, headers }) => headers[ descriptor.headers.event ];
+// What Shopify says when the merchant has uninstalled or revoked. Neither is
+// retryable and both mean the same thing to a merchant: reconnect.
+const OAUTH_GRANT_REVOKED_CODES = [ 'application_cannot_be_found', 'invalid_grant' ];
 
 // WHERE THIS VENDOR PUTS THINGS ON AN INBOUND REQUEST. Header names are facts
 // about someone else's product, so they belong beside the rest of the vendor
@@ -2334,7 +3635,7 @@ var shopify = {
 		// the App Store listing, and the dashboard must never imply a store can be
 		// linked from inside it.
 		redirect : {
-			env : 'SHOPIFY_APP_LISTING_URL',
+			credential : 'SHOPIFY_APP_LISTING_URL',
 			title : 'View on the Shopify App Store'
 		}
 	},
@@ -2391,20 +3692,670 @@ var shopify = {
 			//
 			// `shopify` is injected for the same reason it is everywhere else — this
 			// package cannot import @drawbridge/shopify, which depends on it.
-			scopes : ({ scope, shopify }) => ( scope ? shopify.oauth.missingScopes( scope ) : null ),
+			scopes : ( { scope }, { shopify } = {} ) => ( scope ? shopify.oauth.missingScopes( scope ) : null ),
 			// Shopify's install grant is exchanged inside its own app flow, not
 			// through the shared OAuth runner.
 			token : false
 		},
-		// Implemented in drawbridge-sync, which owns the attribution and the
-		// controllers it needs. Declared here so the steps below can point at them:
-		// a step naming a hook the vendor does not implement is a workflow that
-		// accepts the step and then silently does nothing.
+		// THE VENDOR'S OWN WORK, here in full. Every body describes its writes,
+		// enqueues and events for the shell to perform — see contract.js — and
+		// everything it needs arrives as an argument: `read` (the controller's
+		// read methods, nothing that writes), `shopify` (the SDK, injected because
+		// this package cannot import what depends on it), `adminToken` (minted by
+		// the shell, which persists rotations), `mintId` (so one described write
+		// can reference another), `dispatch` (the caller's own coordinator table,
+		// for the hooks that are dispatches).
 		commerce : {
-			code : {},
-			customer : {},
-			order : {},
-			product : {}
+
+			// MINT A DISCOUNT CODE against the merchant's chosen discount, mapped to
+			// one lead — which is what lets an order that redeems it be attributed
+			// back.
+			code : async ( { connection, context, step }, { adminToken, shopify } = {} ) => {
+
+				const discount = step.settings?.discount;
+
+				const request = { email : context?.email || null, lead : context?.lead || null, shop : connection.shop };
+
+				if( ! context?.email ) return { message : 'Lead email is missing.', request, response : { skipped : true }, skipped : true };
+				if( ! context?.lead ) return { message : 'Lead id is missing.', request, response : { skipped : true }, skipped : true };
+				if( ! discount?.id ) return { message : 'Discount is not configured on this step.', request, response : { skipped : true }, skipped : true };
+
+				const adminAccessToken = await adminToken();
+
+				// The customer must exist before a code is mapped to them. An earlier
+				// commerce.customer step usually did this and left the id on the
+				// context; when this step runs alone, it does it here.
+				if( ! context.shopifyCustomerId ){
+
+					const customer = await shopify.admin.getOrCreateCustomer({ adminAccessToken, domain : connection.shop, email : context.email });
+
+					if( ! customer?.id ) return { message : 'Shopify did not return a customer id — create/lookup failed.', request, response : { skipped : true }, skipped : true };
+
+				}
+
+				const discountCode = await shopify.admin.createDiscountCode({
+					adminAccessToken,
+					code : 'DB-' + generateDiscountCode(),
+					discountId : discount.id,
+					domain : connection.shop
+				});
+
+				if( ! discountCode ) return { message : 'Shopify did not return a discount code — create failed.', request, response : { skipped : true }, skipped : true };
+
+				return {
+					context : {
+						shopifyDiscountCode : discountCode.code,
+						shopifyDiscountId : String( discountCode.id )
+					},
+					message : 'Discount code created and linked to lead.',
+					request,
+					response : { code : discountCode.code, id : String( discountCode.id ) },
+					// bypassDocumentValidation because these are vendor ids on a
+					// Drawbridge document the schema does not declare — the
+					// canonical-identity work resolves it properly.
+					writes : [ {
+						collection : 'lead',
+						data : {
+							$set : {
+								shopifyDiscountCode : discountCode.code,
+								shopifyDiscountId : String( discountCode.id )
+							}
+						},
+						operation : 'update',
+						options : { bypassDocumentValidation : true },
+						query : { id : context.lead }
+					} ]
+				};
+
+			},
+
+			// CREATE THE BUYER AT THE STORE, so an order can be attributed to them.
+			//
+			// IDEMPOTENT THREE WAYS, because this runs on every entry and a duplicate
+			// customer at the store is a support ticket: the context may already
+			// carry the id from an earlier step, the lead may already be linked from
+			// an earlier run, and Shopify's own get-or-create settles the rest.
+			customer : async ( { connection, context }, { adminToken, read, shopify } = {} ) => {
+
+				const request = { email : context?.email || null, lead : context?.lead || null, shop : connection.shop };
+
+				if( ! context?.email ) return { message : 'Lead email is missing — cannot create Shopify customer.', request, response : { skipped : true }, skipped : true };
+				if( ! context?.lead ) return { message : 'Lead id is missing — cannot create Shopify customer.', request, response : { skipped : true }, skipped : true };
+
+				// Already known from an earlier step in this run.
+				if( context.shopifyCustomerId ){
+
+					return {
+						context : { shopifyCustomerId : context.shopifyCustomerId },
+						message : 'Trigger data already includes a Shopify customer id — reusing.',
+						request,
+						response : { shopifyCustomerId : context.shopifyCustomerId },
+						// Reusing an id is not a creation, so it does not bill.
+						skipped : true
+					};
+
+				}
+
+				const lead = await read.get({ collection : 'lead', query : { id : context.lead } });
+
+				// Already linked by an earlier run.
+				if( lead?.shopifyCustomerId ){
+
+					return {
+						context : { shopifyCustomerId : lead.shopifyCustomerId },
+						message : 'Lead already has a Shopify customer id — reusing.',
+						request,
+						response : { shopifyCustomerId : lead.shopifyCustomerId },
+						skipped : true
+					};
+
+				}
+
+				const adminAccessToken = await adminToken();
+
+				// Shopify keeps first and last separately; Drawbridge keeps one name.
+				// Split on the first space and give everything after it to the
+				// surname, which is wrong for some names and is what the vendor's
+				// shape allows.
+				const parts = ( lead?.name || '' ).trim().split( /\s+/ ).filter( Boolean );
+
+				const customer = await shopify.admin.getOrCreateCustomer({
+					adminAccessToken,
+					domain : connection.shop,
+					email : context.email,
+					firstName : parts.length ? parts[ 0 ] : null,
+					lastName : parts.length > 1 ? parts.slice( 1 ).join( ' ' ) : null,
+					source : 'drawbridge'
+				});
+
+				if( ! customer?.id ) return { message : 'Shopify did not return a customer id — create/lookup failed.', request, response : { skipped : true }, skipped : true };
+
+				return {
+					context : { shopifyCustomerId : customer.id },
+					message : 'Shopify customer created/linked to lead.',
+					request,
+					response : { shopifyCustomerId : customer.id },
+					// The hook's own result, described beside the call that produced it.
+					writes : [ {
+						collection : 'lead',
+						data : { $set : { shopifyCustomerId : customer.id } },
+						operation : 'update',
+						options : { bypassDocumentValidation : true },
+						query : { id : context.lead }
+					} ]
+				};
+
+			},
+
+			// AN ORDER ARRIVED AT THE STORE. The largest hook in the family, because
+			// attribution genuinely is: an order can reach Drawbridge two ways and
+			// they bill differently.
+			//
+			//   CONVERSION — a `_drwbrdg_ca` line-item property, injected at
+			//                add-to-cart. Causal: the campaign produced the sale, so
+			//                it carries a fee.
+			//   REDEMPTION — a DB- discount code matched to a lead. Associative: we
+			//                cannot claim we caused the purchase, so it is fee-free.
+			//
+			// Both can be true, and an order already recorded as a conversion can
+			// later have a redemption backfilled onto it — `backfill` below.
+			//
+			// IDEMPOTENT THROUGH THE RETRY, one layer up: two deliveries of the same
+			// order race, the loser's transaction hits a duplicate key, the step
+			// fails and BullMQ redelivers — and the re-run's read at the top finds
+			// what the winner wrote and skips instead of double-billing a merchant
+			// for one purchase. The hook used to loop for this itself; describing
+			// the writes moved the retry to the queue, with the same guarantee.
+			order : async ( { connection, context }, { logger, mintId, read } = {} ) => {
+
+				const {
+					advertisement,
+					created_at : createdAt,
+					currency,
+					customer : orderCustomer,
+					email,
+					id : orderId,
+					line_items : lineItems = [],
+					organization,
+					phone
+				} = context || {};
+
+				const request = { orderId : orderId ? String( orderId ) : null, organization };
+
+				const [ existingOrder, existingRedemption ] = await Promise.all([
+					read.get({ collection : 'order', query : { 'provider.id' : String( orderId ), 'provider.slug' : 'shopify' } }),
+					read.get({ collection : 'redemption', query : { 'provider.id' : String( orderId ), 'provider.slug' : 'shopify' } })
+				]);
+
+				// Already fully recorded. This is the branch the redelivery exists to
+				// reach.
+				if( existingRedemption ){
+
+					return {
+						message : 'Order/redemption already recorded — skipping duplicate.',
+						request,
+						response : {
+							existingOrderId : existingOrder?.id || null,
+							existingRedemptionId : existingRedemption.id,
+							skipped : true
+						},
+						skipped : true
+					};
+
+				}
+
+				const backfill = ! ! existingOrder;
+
+				// ONLY `_drwbrdg_ca`-TAGGED LINES COUNT toward attributed gross.
+				const { attrMap, attributedGross, attributedLines } = attributeLineItems( lineItems );
+
+				const campaign = attrMap[ '_drwbrdg_ca' ] || null;
+
+				const discountCodes = Array.isArray( context?.discount_codes ) ? context.discount_codes : [];
+				const codes = [ ...new Set( discountCodes.map( ( dc ) => dc?.code ).filter( Boolean ) ) ];
+
+				const matchedLeads = codes.length
+					? await read.aggregate({
+						collection : 'lead',
+						pipeline : [ { $match : { organization, shopifyDiscountCode : { $in : codes } } } ]
+					})
+					: [];
+
+				const codeToLead = {};
+
+				for( const found of matchedLeads ){
+
+					if( found.shopifyDiscountCode ) codeToLead[ found.shopifyDiscountCode ] = found;
+
+				}
+
+				const matchedDiscounts = discountCodes
+					.filter( ( dc ) => dc?.code && codeToLead[ dc.code ] )
+					.map( ( dc ) => ({
+						amount : parseFloat( dc.amount ) || 0,
+						code : dc.code,
+						id : codeToLead[ dc.code ].shopifyDiscountId || null
+					}) );
+
+				const matchedLead = matchedDiscounts.length ? codeToLead[ matchedDiscounts[ 0 ].code ] : null;
+
+				const discount = matchedDiscounts.length
+					? {
+						amount : matchedDiscounts.reduce( ( sum, entry ) => sum + entry.amount, 0 ),
+						codes : matchedDiscounts
+					}
+					: null;
+
+				const matchedCodes = new Set( matchedDiscounts.map( ( entry ) => entry.code ) );
+
+				// A DB- code we minted that matched no lead. Logged rather than
+				// ignored: it means a code went out and its lead link was lost, which
+				// is revenue we cannot attribute and nobody would otherwise notice.
+				const unmatched = codes.filter( ( code ) => code.startsWith( 'DB-' ) && ! matchedCodes.has( code ) );
+
+				if( unmatched.length ){
+
+					logger?.warn?.( 'shopify.order.discount.unmatched', {
+						campaign : campaign || null,
+						codes : JSON.stringify( unmatched ),
+						isConversion : ! ! campaign,
+						orderId : String( orderId ),
+						organization
+					});
+
+				}
+
+				if( ( ! campaign && ! discount ) || ( backfill && ! discount ) ){
+
+					return {
+						message : backfill
+							? 'Order already recorded and no Drawbridge discount code matched — nothing to backfill.'
+							: 'Order has no Drawbridge attribution — not recording.',
+						request,
+						response : { skipped : true },
+						skipped : true
+					};
+
+				}
+
+				let advertisementId = null;
+				let affiliateId = null;
+				let campaignOrganization = organization;
+				let gross = 0;
+				let leadId = null;
+				let lines = [];
+				let orderCampaign = null;
+				let pageId = null;
+
+				const isConversion = ! ! campaign;
+
+				const customerPhone = toE164( orderCustomer?.phone || phone ) || null;
+
+				const matchPhones = [ ...new Set([
+					customerPhone,
+					toE164( context?.billing_address?.phone ),
+					toE164( context?.shipping_address?.phone )
+				].filter( Boolean ) ) ];
+
+				if( isConversion ){
+
+					const campaignDoc = await read.get({ collection : 'campaign', query : { id : campaign } });
+
+					// THE CAMPAIGN MUST BELONG TO THE DELIVERING SHOP'S OWN ORG.
+					//
+					// `_drwbrdg_ca` is a line-item property, and on most Shopify themes
+					// a buyer can attach arbitrary line-item properties via cart
+					// permalinks or the AJAX cart API — and campaign ids are
+					// discoverable from public campaign links. Without this check, a $1
+					// order on ANY connected store carrying another org's campaign id
+					// records a conversion under that org: its revenue totals climb,
+					// its usage document is incremented, and its matching leads gain
+					// order counts — a cross-tenant write driven entirely by the buyer.
+					//
+					// A stale or garbage id lands here too, so this is also the null
+					// check: either way the order simply has no Drawbridge attribution.
+					if( ! campaignDoc || campaignDoc.organization !== organization ){
+
+						return {
+							message : 'Order carried a campaign attribution that does not belong to this store — not recording.',
+							request,
+							response : { skipped : true },
+							skipped : true
+						};
+
+					}
+
+					advertisementId = attrMap[ '_drwbrdg_ad' ] || advertisement || null;
+					affiliateId = attrMap[ '_drwbrdg_af' ] || null;
+					campaignOrganization = campaignDoc.organization;
+					gross = attributedGross;
+					lines = attributedLines;
+					orderCampaign = campaign;
+					pageId = attrMap[ '_drwbrdg_pg' ] || null;
+
+					// MATCHED ON EVERY IDENTITY WE HOLD, canonical forms included,
+					// because the address on an order is often not the one they entered
+					// with.
+					const identifiers = [];
+
+					const canonicalEmail = toCanonicalEmail( email );
+
+					if( email ) identifiers.push({ email : email.toLowerCase() });
+					if( canonicalEmail ) identifiers.push({ 'canonical.email.value' : canonicalEmail });
+					if( matchPhones.length ) identifiers.push({ 'phone.number' : { $in : matchPhones } });
+					if( matchPhones.length ) identifiers.push({ 'canonical.phone.value' : { $in : matchPhones } });
+
+					if( identifiers.length ){
+
+						// Narrowed to the campaign first; an org-wide match is the
+						// fallback, because a buyer who entered a different campaign is
+						// still the same person and still worth linking.
+						const lead = await read.get({
+							collection : 'lead',
+							query : {
+								campaigns : { $in : [ campaign ] },
+								organization : campaignOrganization,
+								$or : identifiers
+							}
+						});
+
+						leadId = lead?.id || null;
+
+						if( ! leadId ){
+
+							const orgLead = await read.get({
+								collection : 'lead',
+								query : { organization : campaignOrganization, $or : identifiers }
+							});
+
+							leadId = orgLead?.id || null;
+
+						}
+
+					}
+
+				} else {
+
+					// REDEMPTION. The lead is known from the code, and the whole order
+					// counts as gross — there are no tagged lines to narrow it to.
+					leadId = matchedLead.id;
+					orderCampaign = ( matchedLead.campaigns || [] ).length === 1 ? matchedLead.campaigns[ 0 ] : null;
+					gross = lineItems.reduce( ( sum, item ) => {
+
+						const line = toLine( item );
+
+						return sum + ( line.price * line.quantity );
+
+					}, 0 );
+					lines = lineItems.map( toLine );
+
+				}
+
+				const org = await read.get({ collection : 'organization', query : { id : campaignOrganization } });
+
+				let rate = 0;
+
+				// THE FEE IS THE CONVERSION FEE, and only a conversion carries one. A
+				// redemption is associative — we cannot claim we caused the purchase —
+				// so it is recorded fee-free.
+				if( isConversion ){
+
+					const subscription = await read.get({ collection : 'subscription', query : { id : org?.subscription } });
+
+					rate = conversionRate( subscription );
+
+				}
+
+				const fee = isConversion ? Math.round( gross * rate ) / 100 : 0;
+				const net = Math.round( ( gross - fee ) * 100 ) / 100;
+
+				const currencyCode = ( currency || 'usd' ).toLowerCase();
+				const purchasedAt = new Date( createdAt || Date.now() );
+
+				const customer = ( orderCustomer || email || phone )
+					? {
+						acceptsMarketing : orderCustomer?.email_marketing_consent?.state
+							? orderCustomer.email_marketing_consent.state === 'subscribed'
+							: ( typeof orderCustomer?.accepts_marketing === 'boolean' ? orderCustomer.accepts_marketing : null ),
+						email : orderCustomer?.email || email || null,
+						firstName : orderCustomer?.first_name || null,
+						id : orderCustomer?.id ? String( orderCustomer.id ) : null,
+						lastName : orderCustomer?.last_name || null,
+						phone : customerPhone
+					}
+					: null;
+
+				const source = connection?.source
+					? { domain : connection.source.domain, id : connection.source.id }
+					: undefined;
+
+				// MINTED HERE, because the redemption names its order and the usage
+				// job names both — a description cannot read a write's result, so the
+				// id exists before either does.
+				const orderDocId = existingOrder?.id || ( isConversion && ! backfill ? mintId() : null );
+
+				const writes = [];
+
+				if( isConversion && ! backfill ){
+
+					writes.push({
+						collection : 'order',
+						data : {
+							advertisement : advertisementId,
+							affiliate : affiliateId,
+							campaign : orderCampaign,
+							currency : currencyCode,
+							customer,
+							discount,
+							fee,
+							gross,
+							id : orderDocId,
+							lead : leadId,
+							lines,
+							net,
+							organization : campaignOrganization,
+							page : pageId,
+							provider : { id : String( orderId ), slug : 'shopify' },
+							purchasedAt,
+							rate,
+							source,
+							status : 'completed'
+						},
+						operation : 'create'
+					});
+
+					if( org?.usage ){
+
+						writes.push({
+							collection : 'usage',
+							data : { $inc : { 'totals.revenue' : gross } },
+							operation : 'update',
+							query : { id : org.usage }
+						});
+
+					}
+
+					if( leadId ){
+
+						writes.push({
+							collection : 'lead',
+							data : { $inc : { 'totals.orders' : 1 } },
+							operation : 'update',
+							options : { bypassDocumentValidation : true },
+							query : { id : leadId }
+						});
+
+					}
+
+				}
+
+				if( discount ){
+
+					writes.push({
+						collection : 'redemption',
+						data : {
+							advertisement : advertisementId,
+							affiliate : affiliateId,
+							campaign : orderCampaign,
+							code : matchedDiscounts[ 0 ]?.code || null,
+							currency : currencyCode,
+							customer,
+							discount,
+							gross,
+							lead : leadId,
+							order : orderDocId,
+							organization : campaignOrganization,
+							page : pageId,
+							provider : { id : String( orderId ), slug : 'shopify' },
+							purchasedAt,
+							source,
+							status : 'completed'
+						},
+						operation : 'create'
+					});
+
+					if( org?.usage ){
+
+						writes.push({
+							collection : 'usage',
+							data : { $inc : { 'totals.redemptions' : 1 } },
+							operation : 'update',
+							query : { id : org.usage }
+						});
+
+					}
+
+					if( leadId ){
+
+						writes.push({
+							collection : 'lead',
+							data : { $inc : { 'totals.redemptions' : 1 } },
+							operation : 'update',
+							options : { bypassDocumentValidation : true },
+							query : { id : leadId }
+						});
+
+					}
+
+				}
+
+				// SHOPIFY-BILLED ORGS ARE CHARGED THROUGH SHOPIFY, keyed on the order
+				// id so a redelivery cannot charge twice. Never on a backfill: the fee
+				// was charged when the order was first recorded. Enqueues run after
+				// the transaction commits, so the job can never observe rows that
+				// roll back.
+				const enqueues = ( org?.billingProvider === 'shopify' && fee > 0 && connection?.source?.id && ! backfill )
+					? [ {
+						data : {
+							idempotencyKey : String( orderId ),
+							orderDocId,
+							orderId : String( orderId ),
+							rate,
+							shopId : connection.source.id,
+							// The App Events API returns no event id, so one is generated
+							// here — the event handle plus the order id — and sent as the
+							// event's `reference`. queue/usage.js stamps the same id onto
+							// the order as billed.transaction.
+							transaction : 'drawbridge-orders.' + orderId,
+							value : Math.round( fee * 100 )
+						},
+						name : 'billing',
+						options : { jobId : 'shopify.usage.' + orderId },
+						queue : 'usage'
+					} ]
+					: [];
+
+				return {
+					enqueues,
+					message : backfill
+						? 'Redemption backfilled for an already-recorded order.'
+						: isConversion ? 'Order recorded.' : 'Discount redemption recorded (fee-free).',
+					request,
+					response : {
+						campaign : orderCampaign,
+						currency : currencyCode,
+						discount,
+						fee,
+						gross,
+						lead : leadId,
+						lines : lines.length,
+						net,
+						orderId : String( orderId )
+					},
+					// ONE TRANSACTION. The order, the redemption and both totals
+					// counters land together or not at all — a half-written attribution
+					// is revenue counted twice or not at all, and neither is
+					// recoverable by hand.
+					transaction : writes.length > 0,
+					writes
+				};
+
+			},
+
+			// A PRODUCT CHANGED AT THE STORE. Upserts the product row and hands it to
+			// the product pipeline; the actual field sync happens there.
+			//
+			// The shell has already refused a missing or inactive Shopify connection,
+			// so what is left is the two things only this hook can know are wrong.
+			product : async ( { connection, context, workflow }, { mintId } = {} ) => {
+
+				const request = {
+					numericId : context?.id || null,
+					organizationId : workflow.organization,
+					title : context?.title || null
+				};
+
+				if( ! context?.id ) return { message : 'Skipped — product webhook payload had no id.', request, response : { skipped : true }, skipped : true };
+
+				// The shop domain is half the identity below. Without it the upsert
+				// would match on provider id alone and could collide across stores.
+				if( ! connection.shop ) return { message : 'Skipped — Shopify connection is missing shop domain.', request, response : { skipped : true }, skipped : true };
+
+				const providerId = 'gid://shopify/Product/' + context.id;
+
+				// Minted so the enqueue can name the row this upsert makes — and the
+				// job carries the PROVIDER identity too, because under a concurrent
+				// redelivery this id may be the one that lost the upsert race. The
+				// worker falls back to provider + shop, which are stable either way.
+				const productId = mintId();
+
+				return {
+					enqueues : [ {
+						data : { product : productId, providerId, shop : connection.shop },
+						name : 'workflow',
+						options : { jobId : 'product.workflow.shopify.' + providerId + '.' + Date.now() },
+						queue : 'product.shopify'
+					} ],
+					message : 'Product sync queued from Shopify webhook.',
+					request,
+					response : { productId, providerId, title : context?.title || null },
+					// KEYED ON PROVIDER + SHOP, so the same product in two stores stays
+					// two rows. `connections` accumulates rather than replaces: one
+					// store can be linked to several organizations, and each keeps its
+					// own claim on the row.
+					writes : [ {
+						collection : 'product',
+						data : {
+							$addToSet : { connections : connection.id },
+							$setOnInsert : {
+								id : productId,
+								provider : { id : providerId, slug : 'shopify' },
+								'source.id' : connection.id,
+								status : 'active'
+							}
+						},
+						operation : 'update',
+						options : { upsert : true },
+						query : {
+							'provider.id' : providerId,
+							'provider.slug' : 'shopify',
+							'source.domain' : connection.shop
+						}
+					} ]
+				};
+
+			}
+
 		},
 		contacts : { remove : false, sync : false },
 
@@ -2423,8 +4374,22 @@ var shopify = {
 		sms : false,
 		inbound : {
 			event : ( args ) => readEventHeader({ ...args, descriptor : inbound }),
-			process : {},
-			receive : ({ channel, event, headers, payload }) => {
+			// One hook over the whole topic table, because that is what this
+			// manifest declares: Shopify processes its own buffered events. The
+			// topic rides in on the context rather than being a second hook name per
+			// topic; the caller's handler table arrives as a prop.
+			process : async ( { context }, { dispatch } = {} ) => {
+
+				const key = 'shopify.' + context?.topic;
+
+				const handled = await dispatch({ data : context?.data, handler : key });
+
+				if( ! handled ) return { message : 'No handler for ' + key, skipped : true };
+
+				return { message : 'Processed ' + key, request : { topic : context?.topic } };
+
+			},
+			receive : ( { channel, event, headers, payload } ) => {
 
 			if( channel === 'compliance' && ! COMPLIANCE_TOPICS.has( event ) ){
 
@@ -2446,7 +4411,173 @@ var shopify = {
 			},
 			verify : ( args ) => verifySignature({ ...args, descriptor : inbound })
 		},
-		lifecycle : { cleanup : {}, health : {}, register : {}, rehydrate : {} },
+		lifecycle : {
+
+			// DISPATCHES INTO THE CALLER'S OWN COORDINATORS. These three are
+			// declarations made true: the work is queue orchestration over
+			// Drawbridge's own collections, which is coordinator work and stays in
+			// the repo that owns the queues. The hook receives the dispatch table as
+			// a prop and picks the entry, so the manifest owns the SEAM — asking
+			// Shopify whether it handles its own lifecycle now gets a real function
+			// instead of `unimplemented` while the work happened anyway.
+			cleanup : async ( { context }, { dispatch } = {} ) => {
+
+				await dispatch({ data : context, handler : 'cleanup' });
+
+				return { message : 'Ran shopify lifecycle.cleanup', request : context || null };
+
+			},
+
+			// KEEP STORE ACCESS WORKING. Not a webhook monitor, despite the name the
+			// step once carried — webhooks are declarative, declared in the app's
+			// toml and applied by Shopify to every install, so nothing here registers
+			// or checks them.
+			//
+			// It rotates the refresh token before its window closes, proves the
+			// access token still works, reconciles the scopes the store granted
+			// against the ones the app now needs, and queues a webhook
+			// reconciliation.
+			health : async ( { connection, workflow }, { adminToken, read, reconcileScopes, resolveSettings, rotateToken, shopify } = {} ) => {
+
+				const request = {
+					connectionId : workflow.connection,
+					organizationId : workflow.organization,
+					shop : connection.shop
+				};
+
+				// Captured BEFORE anything runs. If the calls below fail with
+				// invalid_grant, this is what distinguishes "the merchant revoked us"
+				// from "a concurrent rotation spent the token we were holding" — and
+				// only the first should error the connection.
+				const refreshTokenAtStart = ( await resolveSettings() ).refreshToken || null;
+
+				try {
+
+					const adminAccessToken = await adminToken();
+
+					const settings = await resolveSettings();
+
+					const refreshTokenExpiresAt = settings.refreshTokenExpiresAt;
+
+					const needsRotation = refreshTokenExpiresAt
+						&& new Date( refreshTokenExpiresAt ) < new Date( Date.now() + REFRESH_TOKEN_FRESHNESS_BUFFER_MS );
+
+					let refreshTokenRotated = false;
+
+					if( needsRotation ){
+
+						await rotateToken();
+
+						refreshTokenRotated = true;
+
+					}
+
+					await shopify.oauth.ping({ adminAccessToken, domain : connection.shop });
+
+					// SCOPE DRIFT IS ITS OWN FAILURE. A token can be perfectly valid
+					// while the grant is too narrow, which no ping would ever reveal.
+					// Injected rather than described: reconciliation is the caller's
+					// writer-of-record routine, shared with the webhook drain, and this
+					// hook needs its RESULT to compose the message below.
+					const scopesMissing = await reconcileScopes({ shop : connection.shop });
+
+					return {
+						enqueues : [ {
+							data : {
+								data : {
+									connectionId : workflow.connection,
+									organizationId : workflow.organization
+								},
+								event : 'shopify.register.webhooks'
+							},
+							name : 'register',
+							options : { jobId : 'connection.update.register.' + workflow.connection + '.' + randomUUID() },
+							queue : 'connection'
+						} ],
+						message : scopesMissing?.length
+							? 'Health check: ping ok, webhooks reconciled — connection errored, granted scopes are missing: ' + scopesMissing.join( ', ' ) + '.'
+							: refreshTokenRotated
+								? 'Health check passed — refresh token rotated, ping ok, webhooks reconciled.'
+								: 'Health check passed — ping ok, webhooks reconciled.',
+						request,
+						response : {
+							pingedAt : new Date(),
+							refreshTokenExpiresAt : refreshTokenExpiresAt || null,
+							refreshTokenRotated,
+							scopesMissing,
+							webhookReconciliationQueued : true
+						}
+					};
+
+				} catch ( error ){
+
+					// A REVOKED GRANT IS THE MERCHANT'S TO FIX, so the connection says
+					// so rather than failing silently on a schedule nobody watches. The
+					// write rides OUT ON THE REJECTION — the contract performs a thrown
+					// error's effects — because the step must still fail.
+					if( OAUTH_GRANT_REVOKED_CODES.includes( error.code ) ){
+
+						const current = await read.get({ collection : 'connection', query : { id : connection.id } });
+
+						// Against the FRESH doc, not the one this run started with — a legacy
+						// connection keeps its tokens in its own settings blob, and a
+						// concurrent rotation rewrote that blob after our snapshot.
+						const refreshTokenStored = current ? ( await resolveSettings( current ) ).refreshToken || null : null;
+
+						// A CONCURRENT ROTATION, not a revocation: another job spent the
+						// refresh token between our read and our use of it. Erroring the
+						// connection here would disconnect a store that is working fine.
+						const rotated = error.code === 'invalid_grant' && refreshTokenStored !== refreshTokenAtStart;
+
+						if( current && ! rotated ){
+
+							const others = ( current.errors || [] ).filter( ( entry ) => entry.source !== OAUTH_ERROR_SOURCE );
+
+							error.writes = [ {
+								collection : 'connection',
+								data : {
+									$set : {
+										errors : [
+											...others,
+											{
+												message : 'Shopify disconnected this store. Open the Drawbridge app in your Shopify admin to reconnect.',
+												source : OAUTH_ERROR_SOURCE
+											}
+										],
+										status : 'error'
+									}
+								},
+								operation : 'update',
+								query : { id : connection.id }
+							} ];
+
+						}
+
+					}
+
+					throw error;
+
+				}
+
+			},
+
+			register : async ( { context }, { dispatch } = {} ) => {
+
+				await dispatch({ data : context, handler : 'register' });
+
+				return { message : 'Ran shopify lifecycle.register', request : context || null };
+
+			},
+
+			rehydrate : async ( { context }, { dispatch } = {} ) => {
+
+				await dispatch({ data : context, handler : 'rehydrate' });
+
+				return { message : 'Ran shopify lifecycle.rehydrate', request : context || null };
+
+			}
+
+		},
 		resources : {
 			audiences : false,
 			// Shopify has no separate price resource — a price belongs to a product
@@ -2467,7 +4598,7 @@ var shopify = {
 			// credential is the caller's job because it is Drawbridge's job: the
 			// admin token refreshes and writes itself back, which is service work,
 			// not vendor work.
-			products : async ({ cursor, limit = 100, search, settings, shopify, sort }) => {
+			products : async ( { cursor, limit = 100, search, settings, sort }, { shopify } = {} ) => {
 
 				const products = await shopify.storefront.getProducts({
 					cursor,
@@ -2490,7 +4621,7 @@ var shopify = {
 
 			},
 
-			promotions : async ({ cursor, limit = 100, search, settings, shopify }) => {
+			promotions : async ( { cursor, limit = 100, search, settings }, { shopify } = {} ) => {
 
 				const discounts = await shopify.admin.getDiscounts({
 					adminAccessToken : settings?.adminAccessToken,
@@ -2541,6 +4672,19 @@ var shopify = {
 			: undefined;
 
 	},
+	// DRAWBRIDGE'S OWN CREDENTIALS for this vendor, as opposed to a merchant's —
+	// what an admin types on the provider screen. The four names below are exactly
+	// what `requires` gates on, which is the point of declaring them together: a
+	// name required by the manifest and enterable nowhere is a vendor that can
+	// never go live from the admin screen.
+	provider : {
+		fields : [
+			{ input : 'text', key : 'apiKey', credential : 'SHOPIFY_API_KEY', label : 'API key', required : true },
+			{ input : 'password', key : 'apiSecret', credential : 'SHOPIFY_API_SECRET', label : 'API secret', redact : true, required : true },
+			{ input : 'text', key : 'appHandle', credential : 'SHOPIFY_APP_HANDLE', label : 'App handle', required : true },
+			{ input : 'text', key : 'listingUrl', credential : 'SHOPIFY_APP_LISTING_URL', label : 'App listing URL', required : true }
+		]
+	},
 	// A pre-launch integration: it only surfaces once the App Store listing
 	// exists and the app is fully configured. Requiring all four means it can
 	// never render half-configured — and absence of any one excludes the
@@ -2574,9 +4718,6 @@ var shopify = {
 	// workflow document, and those strings cannot be renamed without a backfill.
 	//
 	// EVERY LEAF IS A FUNCTION so a step can read the merchant's own connection.
-	// The bodies these point at still live in drawbridge-sync; moving them is the
-	// next unit, and commerce.order.record is the one that decides whether the
-	// shape holds — 569 lines and 15 controller calls.
 	steps : {
 
 		commerce : {
@@ -2785,7 +4926,7 @@ var webhook = {
 		// needs Drawbridge's own database, sockets or queues. This one does not.
 		webhook : {
 
-			send : async ({ context, controller, request : send = safeRequest, settings, step }) => {
+			send : async ( { context, lead, settings, step }, { request : send = safeRequest } = {} ) => {
 
 			const { headers = {}, method = 'POST', url } = step.settings || {};
 
@@ -2794,11 +4935,9 @@ var webhook = {
 			if( ! url ) return { message : 'Outgoing webhook URL is not configured for this step.', request, response : { skipped : true }, skipped : true };
 
 			// The LEAD, when there is one, rather than the accumulated context. A
-			// receiver wants the entrant's record, not our internal step state.
-			const lead = context?.lead
-			? await controller.get({ collection : 'lead', query : { id : context.lead } })
-			: null;
-
+			// receiver wants the entrant's record, not our internal step state —
+			// and the shell already resolved it, because every hook that names a
+			// lead gets the document and its consent together.
 			const body = lead || context;
 
 			request.body = body;
@@ -2864,7 +5003,7 @@ var webhook = {
 	// pressing Connect will do; afterwards it states the verification the
 	// merchant's own endpoint has to perform, because a signed payload nobody
 	// checks is an unsigned payload.
-	tasks : ({ settings }) => ( settings?.secret
+	tasks : ( { settings } ) => ( settings?.secret
 		? [
 			{
 				message : 'Compute HMAC-SHA256( secret, body ) and compare against the X-Drawbridge-Signature header to confirm each payload.',
@@ -3030,6 +5169,39 @@ const build = ( manifest ) => {
 
 	}
 
+	// DRAWBRIDGE'S OWN CREDENTIALS for this vendor, if it has any. A connection
+	// with no third party behind it — webhook — declares no block at all, which is
+	// what keeps it off the provider screen.
+	//
+	// Every field is checked harder than a merchant field: it must be editable
+	// (an admin cannot type into a read-only descriptor, and a credential nobody
+	// can enter is a vendor that can never go live), and a `password` MUST be
+	// redacted. That last one is a SECURITY BOUNDARY rather than tidiness —
+	// providerFields is what the api's redaction derives from, so a password field
+	// that forgot `redact : true` is a platform secret handed back over the wire
+	// to every admin screen that asks.
+	for( const field of manifest.provider?.fields || [] ){
+
+		if( ! field?.key || ! field?.label ){
+
+			throw new Error( manifest.slug + ' declares a provider field with no key or label' );
+
+		}
+
+		if( ! INPUTS.includes( field.input ) ){
+
+			throw new Error( manifest.slug + '.provider.' + field.key + ' needs an input the admin form can render — one of ' + INPUTS.join( ', ' ) );
+
+		}
+
+		if( field.input === 'password' && ! field.redact ){
+
+			throw new Error( manifest.slug + '.provider.' + field.key + ' is a password and must declare redact : true — the api would hand the value back' );
+
+		}
+
+	}
+
 	// THE ICON RIDES WITH THE MANIFEST, so a vendor cannot name an asset nobody
 	// added — which is what the old arrangement allowed, with the markup in one
 	// repo and the file in another.
@@ -3324,36 +5496,41 @@ const connections = Object.freeze({
 	webhook : build( webhook )
 });
 
-// A step type belongs to exactly one vendor.
+// A STEP TYPE MAY BE SHARED, BUT NOT ITS QUEUE.
 //
-// This is checked because the current naming HIDES the problem rather than
-// solving it: every commerce step is namespaced by vendor
-// (step.shopify.customer.insert), so a collision is impossible only for as long
-// as that holds. The moment a capability is named for what it does rather than
-// who does it — step.commerce.customer.insert, which is where this should go —
-// two vendors declaring it would silently collapse into one entry in stepQueues
-// and one of them would route nowhere.
+// A step type belongs to the CAPABILITY rather than to whoever implements it —
+// that is why step.shopify.* became step.commerce.*, and why Klaviyo, Mailchimp
+// and Attentive all declare step.contacts.sync. Sharing the name is the intent,
+// and the vendor is carried on the step DOCUMENT (its connection), not in the
+// type string.
 //
-// Fail at import instead. When the neutral names land, this is the guard that
-// makes the ambiguity visible on the first line of the first test run.
+// What must not be shared is the ROUTE. stepQueues is { type : queue }, so two
+// vendors declaring one type with different queues collapse into a single entry
+// and whichever loses is enqueued nowhere — a workflow that accepts the step and
+// silently never runs it. That is the real failure this guard was written for;
+// the ownership rule was a proxy for it that also refused the case it was
+// designed to anticipate.
 ( () => {
 
-	const owners = {};
+	const routes = {};
 
 	for( const [ slug, manifest ] of Object.entries( connections ) ){
 
-		for( const [ name ] of leaves( manifest.steps ) ){
+		for( const [ name, step ] of leaves( manifest.steps ) ){
 
 			const type = 'step.' + name;
+			const queue = step({})?.queue;
 
+			if( routes[ type ] && routes[ type ].queue !== queue ){
 
-			if( owners[ type ] ){
-
-				throw new Error( 'Step ' + type + ' is declared by both ' + owners[ type ] + ' and ' + slug );
+				throw new Error(
+					'Step ' + type + ' routes to ' + routes[ type ].queue + ' for ' + routes[ type ].slug
+					+ ' and ' + queue + ' for ' + slug + ' — one of them would be enqueued nowhere'
+				);
 
 			}
 
-			owners[ type ] = slug;
+			routes[ type ] = { queue, slug };
 
 		}
 
@@ -3361,10 +5538,13 @@ const connections = Object.freeze({
 
 })();
 
-// The vendors whose environment is actually configured. Every consumer asks this
-// the same way, so "is Shopify available" has one answer rather than one per
-// repo — the api gated it on four env vars and sync inferred it from a different
-// signal, which is how the two drifted.
+// The vendors whose credentials are actually present in the map handed in —
+// which the callers build from the provider collection, with the deployment's
+// environment answering only for names no provider field owns
+// (ENCRYPT_CONNECTION_SECRET). Every consumer asks this the same way, so "is
+// Shopify available" has one answer rather than one per repo — the api once
+// gated it on four env vars and sync inferred it from a different signal, which
+// is how the two drifted.
 const availableConnections = ( env = {} ) => Object.fromEntries(
 	Object.entries( connections ).filter(
 		( [ , manifest ] ) => manifest.requires.every( ( name ) => Boolean( env[ name ] ) )
@@ -3460,7 +5640,9 @@ const connectFields = ( slug ) => ( connections[ slug ]?.fields || [] )
 // The four outcomes are the point. "unsupported", "unimplemented", "failed" and
 // a result are different answers to why there is no data, and collapsing them is
 // how "this vendor cannot do that" becomes indistinguishable from "it broke".
-const runHook = async ( slug, name, args = {} ) => {
+// TWO OBJECTS: props are facts of the run, options are services being passed
+// in. A caller with no services to inject omits the second bag.
+const runHook = async ( slug, name, props = {}, options = {} ) => {
 
 	const manifest = connections[ slug ];
 
@@ -3468,7 +5650,17 @@ const runHook = async ( slug, name, args = {} ) => {
 
 	// The hook's own value is the answer — there is no `supports` map to consult,
 	// and therefore none to disagree with what is actually here.
-	const hook = name.split( '.' ).reduce( ( node, key ) => node?.[ key ], manifest.hooks );
+	//
+	// OWN PROPERTIES ONLY. A bare property walk resolves 'resources.constructor'
+	// to Object.prototype.constructor — a truthy FUNCTION, so every guard on
+	// "does the vendor implement this" passes and runHook calls Object() with
+	// the props, answering the caller's own payload back as a result. With the
+	// api's hook route caching answers in shared Redis, that payload holds a
+	// live admin token. Same fix providerFields already carries.
+	const hook = name.split( '.' ).reduce(
+		( node, key ) => ( node && typeof node === 'object' && Object.hasOwn( node, key ) ) ? node[ key ] : undefined,
+		manifest.hooks
+	);
 
 	if( hook === false || hook == null ){
 
@@ -3492,7 +5684,16 @@ const runHook = async ( slug, name, args = {} ) => {
 		// disconnect until auth.oauth.urls gathered every vendor address in one
 		// place, and a hook that cannot see its own manifest would have forced it
 		// back. Callers never have to know to pass it.
-		return { outcome : OUTCOMES.answered, result : await hook({ ...args, manifest }) };
+		const result = await hook({ ...props, manifest }, options );
+
+		// THE ANSWER IS CHECKED WHERE IT IS PRODUCED. A hook may describe writes,
+		// enqueues and events for its caller to perform, and a malformed descriptor
+		// is a write against the wrong collection — so it is refused here, at the one
+		// call surface, rather than surviving as far as whoever performs it. A hook
+		// that describes nothing (every resources.* read) validates to nothing.
+		effectsOf( result );
+
+		return { outcome : OUTCOMES.answered, result };
 
 	} catch ( error ) {
 
@@ -3672,7 +5873,11 @@ const resolveConnection = ( item, data, env = {} ) => {
 
 	return Object.fromEntries(
 		Object.entries( item )
-			.filter( ( [ key ] ) => ! [ 'auth', 'enabled', 'fields', 'hooks', 'inbound', 'requires', 'steps', 'supports' ].includes( key ) )
+			// `provider` is in the list for a different reason than the rest: it is
+			// PLATFORM configuration — which credentials an admin types in for this
+			// vendor — and no merchant-facing resolution has any business carrying
+			// it, even as bare descriptors.
+			.filter( ( [ key ] ) => ! [ 'auth', 'enabled', 'fields', 'hooks', 'inbound', 'provider', 'requires', 'steps', 'supports' ].includes( key ) )
 			.map( ( [ key, value ] ) => [
 				key,
 				( typeof value === 'function' ? value( data, env ) : value )
@@ -3681,4 +5886,4 @@ const resolveConnection = ( item, data, env = {} ) => {
 
 };
 
-export { AUTH_TYPES, GROUPS, HOOKS, HOOK_NAMES, INPUTS, OAUTH_FIELDS, OUTCOMES, RETIRED, STATUSES, STEPS, STEP_TYPES, accessToken, authToken, availableConnections, build, catalogConnections, connectFields, connectionSteps, connections, hookSupport, isStale, mergeSettings, projectConnection, publicConnectionKeys, publicSettingsBySlug, redactSettings, resolveConnection, runHook, scopesMessage, stepLabels, stepQueues, stepRoutes, tokenSettings };
+export { AUTH_TYPES, GROUPS, HOOKS, HOOK_EFFECTS, HOOK_NAMES, HOOK_OPTIONS, HOOK_PROPS, INPUTS, OAUTH_FIELDS, OUTCOMES, RETIRED, STATUSES, STEPS, STEP_TYPES, WRITE_OPERATIONS, accessToken, authToken, availableConnections, build, catalogConnections, connectFields, connectionSteps, connections, effectsOf, hookSupport, isStale, mergeSettings, projectConnection, publicConnectionKeys, publicSettingsBySlug, redactSettings, resolveConnection, runHook, scopesMessage, stepLabels, stepQueues, stepRoutes, tokenSettings };