@drawbridge/drawbridge-utils 0.0.117 → 0.0.121

package/dist/connections/index.d.cts

@@ -2,19 +2,22 @@ import { authToken } from './oauth.cjs';
 export { consentUrl, pkcePair } from './oauth.cjs';
 import { request } from '../http.cjs';
 import { channels } from '../pricing.cjs';
-import crypto, { createHmac, timingSafeEqual } from 'node:crypto';
+import crypto, { createHmac, timingSafeEqual, randomUUID } from 'node:crypto';
+import { customAlphabet } from 'nanoid';
+import { toCanonicalEmail } from '../email.cjs';
+import { toE164 } from '../phone.cjs';
+import { conversionRate } from '../plans.cjs';
 import { safeRequest } from '../safe-http.cjs';
-import '../plans.cjs';
+import '../billing.cjs';
+import '../transactions.cjs';
+import '@drawbridge/drawbridge-telemetry';
+import '../usage.cjs';
+import 'libphonenumber-js';
 import '../features.cjs';
 import '../index.cjs';
 import 'currency-codes';
-import 'nanoid';
 import '../color.cjs';
 import 'tinycolor2';
-import '../usage.cjs';
-import '../billing.cjs';
-import '../transactions.cjs';
-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 (historically
+//              env var names, kept as the stable vocabulary)
 //   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
@@ -562,8 +807,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 +830,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'
@@ -696,7 +945,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 = fetch } = {} ) => {
 
 				const query = new URLSearchParams({
 					limit : String( Math.min( limit, 1000 ) ),
@@ -809,15 +1058,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 +1268,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 +1285,7 @@ const contacts = {
 					fetcher,
 					method : 'DELETE',
 					path : '/crm/v3/objects/contacts/' + contact,
-					token : key
+					token
 				});
 
 			},
@@ -1037,19 +1296,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 +1319,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;
 
 			}
@@ -1110,6 +1368,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 +1461,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,13 +1490,221 @@ 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 : {}
+
+			// 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,
@@ -1167,8 +1714,264 @@ var drawbridge = {
 			products : false,
 			promotions : false
 		},
-		segment : { sync : {} },
-		sms : { send : {} },
+		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,
@@ -1212,11 +2015,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' }
@@ -1395,7 +2198,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,7 +2348,7 @@ 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 });
 
@@ -1563,7 +2367,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 +2399,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 +2438,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;
 
@@ -1768,7 +2571,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
@@ -2023,7 +2826,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 : {
@@ -2086,7 +2889,7 @@ 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 }) => {
+			audiences : async ( { cursor, limit = 100, search, settings, token }, { fetcher = fetch } = {} ) => {
 
 				// Bearer, not Basic. Mailchimp's fundamentals doc states "API keys and
 				// OAuth 2 tokens can be used to make authenticated requests the same
@@ -2204,14 +3007,30 @@ var icon = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xmln
 //
 // 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,7 +3040,7 @@ const verifySignature = ({ body, descriptor, headers }) => {
 
 	}
 
-	const digest = createHmac( descriptor.signature.algorithm, process.env[ descriptor.signature.secret ] )
+	const digest = createHmac( descriptor.signature.algorithm, secret )
 		.update( body )
 		.digest( descriptor.signature.encoding );
 
@@ -2249,6 +3068,75 @@ const verifySignature = ({ body, descriptor, headers }) => {
 // 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 );
+
+		acc.attributedGross += line.price * line.quantity;
+		acc.attributedLines.push( line );
+
+		return acc;
+
+	},
+	{ 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 );
+
+// 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';
+
+// 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
 // rather than as string literals in a route — which is where they were, and is
@@ -2391,20 +3279,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 +3961,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 +3998,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 +4185,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 +4208,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,
@@ -2574,9 +4292,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 +4500,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 +4509,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 +4577,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.',
@@ -3361,10 +5074,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 +5176,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 +5186,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 +5220,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 ) {
 
@@ -3681,4 +5418,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 };