@drawbridge/drawbridge-utils 0.0.176 → 0.0.178

package/dist/{index-B8JhYfvU.d.ts → index-DOYCXtd7.d.ts}

@@ -1,11 +1,18 @@
 import { isDuplicateKey } from './usage.js';
+import { decrypt, encrypt } from './encrypt.js';
 import { authToken } from './connections/oauth.js';
 import { toE164, detectCountry } from './phone.js';
 import crypto, { randomUUID, createHmac, timingSafeEqual, createVerify, createHash } from 'node:crypto';
 import { request } from './http.js';
 import { customAlphabet } from 'nanoid';
+import { i as shopifyAdmin } from './admin-C3HtEM6h.js';
+import { a as shopifyBilling } from './billing-mNsKflmQ.js';
+import { s as shopifyOauth } from './oauth-DveZMLHx.js';
+import { s as shopifyPartner } from './partner-BOZltuh2.js';
+import { s as shopifyStorefront } from './storefront-DJFGLqPl.js';
 import { toCanonicalEmail } from './email.js';
-import { decrypt } from './encrypt.js';
+import { tokenTypes, hashToken } from './oauth/index.js';
+import { sanitizeDomain } from './sanitize.js';
 import { slugify } from './slugify.js';
 import { safeRequest } from './safe-http.js';
 
@@ -158,6 +165,10 @@ const HOOKS = Object.freeze({
 		'code',
 		// Create the buyer at the vendor, so an order can be attributed to them.
 		'customer',
+		// HOW MANY OF THIS PRODUCT ARE LEFT, at the vendor. Read at the moment a
+		// campaign's product list is rendered rather than stored, because stock is
+		// the one product fact that is stale the instant it is written down.
+		'inventory',
 		// An order arrived at the vendor: attribute it, record it, update totals.
 		'order',
 		// Pull product data across on a vendor update.
@@ -233,7 +244,19 @@ const HOOKS = Object.freeze({
 
 		// What the merchant pays the VENDOR. Pairs with auth.install.billing, which
 		// declares the plan they are being charged on.
-		plan : Object.freeze([ 'cancel', 'reselect' ]),
+		//
+		// `verify` is the odd one of the three: not something a merchant does, but
+		// the question "is this store's billing actually metered right now". It is
+		// here because it is the same subject — and because the answer was being
+		// derived in TWO places, the vendor's health check and drawbridge-sync's
+		// approval webhook, whose copy said in its own comment that it matched the
+		// other and did not.
+		// `charge` and `verify` are the two that are not merchant actions: one
+		// sends a usage charge to the vendor's meter, the other asks whether that
+		// meter is actually working. Both are here because both are the same
+		// subject — what the merchant pays the vendor — and both were being done
+		// from drawbridge-sync with a direct import of the vendor's client.
+		plan : Object.freeze([ 'cancel', 'charge', 'reselect', 'verify' ]),
 
 		// The embedded app's own session, stored by us on the vendor's behalf.
 		session : Object.freeze([ 'clear', 'read', 'save' ]),
@@ -535,12 +558,22 @@ const WRITE_OPERATIONS = Object.freeze([ 'create', 'delete', 'update' ]);
 //                       -> features)
 //   chunkSize           the worker fleet's fan-out width — deployment tuning,
 //                       passed, never published
+//   currencies          the settlement currencies Drawbridge can bill, so a
+//                       store outside them is refused with the reason rather
+//                       than failing a validator inside a transaction
 //   dispatch()          the caller's own coordinator table, for hooks that are
 //                       dispatches
+//   mark()              the one write a description cannot carry because of its
+//                       ORDER — install.plan.reselect must persist the marker
+//                       BEFORE it releases the approval, and a described write
+//                       lands after the hook returns
 //   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
+//   planTitle()         the name of the Drawbridge plan an organization is on,
+//                       given its subscription. Injected for the same reason as
+//                       conversionRate, and from the same catalogue
 //   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
@@ -553,10 +586,15 @@ const WRITE_OPERATIONS = Object.freeze([ 'create', 'delete', 'update' ]);
 //                       decides billing
 //   resolveSettings()   fresh from wherever the vendor keeps credentials, per
 //                       call, never a snapshot
+//   shopify             the vendor's client namespaces. DEFAULTED to the real
+//                       client, which the manifest imports directly — production
+//                       injects nothing. Overridable because it is the SDK
+//                       boundary, and that is where a hook test belongs: the
+//                       health tests stub getActiveAppSubscriptions and assert
+//                       the arguments it was called with
 //   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
+
 //
 // WHICH OF THESE A GIVEN SLOT ACTUALLY CARRIES is the table below, not this
 // glossary. A name here means one thing everywhere it appears; the table says
@@ -564,7 +602,13 @@ const WRITE_OPERATIONS = Object.freeze([ 'create', 'delete', 'update' ]);
 // Three signatures shared by a whole family, declared once so the family cannot
 // drift apart the way resources.* was starting to. Named rather than repeated:
 // a copy-pasted array is a copy that can be edited alone.
-const INSTALL_SIGNATURE = Object.freeze({ options : [ 'read', 'request' ], props : [ 'context' ] });
+// THE INSTALL BASELINE: the request's own body, and the ability to read. Seven
+// of the thirteen slots need nothing else — they answer from the shared install
+// record and describe their writes. `request` came off it when the slots were
+// implemented and none of them made an outbound call of its own; four reach the
+// VENDOR, and they do it through `shopify`, which is the seam every other
+// vendor-calling slot already uses.
+const INSTALL_SIGNATURE = Object.freeze({ options : [ 'read' ], props : [ 'context' ] });
 
 const LIFECYCLE_SIGNATURE = Object.freeze({ options : [ 'dispatch' ], props : [ 'context' ] });
 
@@ -617,15 +661,30 @@ const HOOK_SLOT_PROPS = Object.freeze({
 	// stubbed-fetcher-reaches-production failure the split exists to prevent.
 	'auth.token' : false,
 
-	// COMMERCE. `cart` is declared and unimplemented — the Checkout Kit path in
-	// api/route/subdomain.js writes nothing, which is why it never became a hook
-	// — so its signature mirrors `code`, its nearest sibling, and moving the
-	// route here is a deliberate widening of this line rather than a silent one.
-	'commerce.cart' : Object.freeze({ options : [ 'adminToken', 'shopify' ], props : [ 'connection', 'context', 'step' ] }),
+	// COMMERCE. `cart` is the odd one: it runs for a SHOPPER on a public page,
+	// not for an organization inside a workflow, so it takes no `connection` and
+	// no `step`. It reads the storefront with the store's own storefront token
+	// and mints a checkout token from DRAWBRIDGE'S app credentials, which is why
+	// `clientId`/`clientSecret` are here — as props, the way auth.disconnect
+	// already carries them, because a credential is a fact of the run rather
+	// than a service.
+	'commerce.cart' : Object.freeze({
+		options : [ 'fetcher', 'shopify' ],
+		props : [ 'clientId', 'clientSecret', 'context', 'settings' ]
+	}),
 	'commerce.code' : Object.freeze({ options : [ 'adminToken', 'shopify' ], props : [ 'connection', 'context', 'step' ] }),
 	'commerce.customer' : Object.freeze({ options : [ 'adminToken', 'read', 'shopify' ], props : [ 'connection', 'context' ] }),
+	'commerce.inventory' : Object.freeze({ options : [ 'adminToken', 'shopify' ], props : [ 'connection', 'context' ] }),
 	'commerce.order' : Object.freeze({ options : [ 'conversionRate', 'logger', 'mintId', 'read' ], props : [ 'connection', 'context' ] }),
-	'commerce.product' : Object.freeze({ options : [ 'mintId', 'read' ], props : [ 'connection', 'context', 'workflow' ] }),
+	// THREE OPERATIONS, one slot — record, sync, variants. `settings` and
+	// `adminToken` arrived with the pull half: the storefront read needs the
+	// store's storefront token and the product-feedback send needs its admin one,
+	// and both are resolved by the caller because minting either needs a
+	// controller.
+	'commerce.product' : Object.freeze({
+		options : [ 'adminToken', 'mintId', 'read', 'shopify' ],
+		props : [ 'connection', 'context', 'settings', 'workflow' ]
+	}),
 
 	// THE ADDRESS IS `contact` IN BOTH, and the shell already says why: it is the
 	// person, not the lead document. `remove` called it `email` and `sync` called
@@ -641,19 +700,58 @@ const HOOK_SLOT_PROPS = Object.freeze({
 	'inbound.receive' : Object.freeze({ options : [], props : [ 'channel', 'event', 'headers', 'payload' ] }),
 	'inbound.verify' : Object.freeze({ options : [], props : [ 'body', 'channel', 'headers', 'secret', 'url' ] }),
 
-	// INSTALL — thirteen slots, none implemented yet. They are what the thirteen
-	// routes in api/route/shopify-embedded.js become, and the signature is
-	// deliberately narrow: `context` is the request's own body, `read` and
-	// `request` are the only services an install surface has been shown to need.
-	// A route that cannot be expressed inside this line is a finding to bring
-	// back here, not a name to add at the call site.
+	// INSTALL — thirteen slots, and they are the thirteen routes that used to be
+	// api/route/shopify-embedded.js. `context` is the request's own body in all
+	// of them; the options are where they differ, and every difference below was
+	// forced by a line in those routes rather than chosen.
+	//
+	// SEVEN NEED NOTHING BUT `read`. The two session slots that write, the two
+	// token slots that write, the two clears, and both account slots answer from
+	// the shared install record alone.
+	//
+	// SIX TAKE MORE, and the widenings are worth naming because each is a fact
+	// Drawbridge owns that the manifest must not:
+	//
+	//   conversionRate, planTitle   what Drawbridge charges this organization.
+	//                               The org list renders both, and importing the
+	//                               plan catalogue here is the cycle
+	//                               features -> connections -> shopify -> plans
+	//                               -> features that was just broken.
+	//   currencies                  which settlement currencies Drawbridge can
+	//                               bill. A store outside them fails the
+	//                               connection validator INSIDE the transaction,
+	//                               which surfaces as an opaque 500, so `add`
+	//                               checks first and says so.
+	//   mintId                      the connection's id, known before the write
+	//                               that creates it, because the organization's
+	//                               own refs have to name it in the same
+	//                               transaction.
+	//   shopify                     the vendor. Four slots call the store: two
+	//                               read the live plan, two release it.
+	//   mark                        THE ONE WRITE A DESCRIPTION CANNOT CARRY, and
+	//                               `reselect` is the only slot with one. See its
+	//                               implementation for why the order is the point.
 	'install.account.link' : INSTALL_SIGNATURE,
 	'install.account.unlink' : INSTALL_SIGNATURE,
-	'install.organizations.add' : INSTALL_SIGNATURE,
-	'install.organizations.list' : INSTALL_SIGNATURE,
+	'install.organizations.add' : Object.freeze({
+		options : [ 'currencies', 'mintId', 'read', 'shopify' ],
+		props : [ 'context' ]
+	}),
+	'install.organizations.list' : Object.freeze({
+		options : [ 'conversionRate', 'planTitle', 'read', 'shopify' ],
+		props : [ 'context' ]
+	}),
 	'install.organizations.remove' : INSTALL_SIGNATURE,
-	'install.plan.cancel' : INSTALL_SIGNATURE,
-	'install.plan.reselect' : INSTALL_SIGNATURE,
+	'install.plan.cancel' : Object.freeze({ options : [ 'read', 'shopify' ], props : [ 'context' ] }),
+	// `manifest` because the handle this charge bills under is the vendor's own
+	// declaration (auth.install.billing.handle), and checking the job against the
+	// declaration is what the enqueuer-checks-itself version could not do.
+	'install.plan.charge' : Object.freeze({
+		options : [ 'shopify' ],
+		props : [ 'clientId', 'clientSecret', 'context', 'manifest' ]
+	}),
+	'install.plan.reselect' : Object.freeze({ options : [ 'mark', 'read', 'shopify' ], props : [ 'context' ] }),
+	'install.plan.verify' : Object.freeze({ options : [ 'adminToken', 'read', 'shopify' ], props : [ 'context' ] }),
 	'install.session.clear' : INSTALL_SIGNATURE,
 	'install.session.read' : INSTALL_SIGNATURE,
 	'install.session.save' : INSTALL_SIGNATURE,
@@ -837,6 +935,16 @@ const TRIGGERS = Object.freeze({
 	'range.ended' : Object.freeze({ event : 'range.ended', type : 'range' }),
 	'range.started' : Object.freeze({ event : 'range.started', type : 'range' }),
 	'schedule.day' : Object.freeze({ event : 'day', type : 'schedule' }),
+	// THE THREE SHOPIFY TRIGGERS, which were never in this vocabulary because the
+	// four workflows they fire were hand-written in drawbridge-sync's register job
+	// rather than provisioned from the manifest. `webhook` is a fourth trigger
+	// TYPE, and it is the honest name: these fire when the vendor calls us, which
+	// is neither an event Drawbridge raised nor a schedule it keeps.
+	'shopify.order.create' : Object.freeze({ event : 'shopify.order.create', type : 'webhook' }),
+	'shopify.product.update' : Object.freeze({ event : 'shopify.product.update', type : 'webhook' }),
+	// The token audit, dispatched programmatically by the register job when a
+	// store's grant is exchanged or rotated.
+	'shopify.token' : Object.freeze({ event : 'shopify.token', type : 'event' }),
 	'schedule.month' : Object.freeze({ event : 'month', type : 'schedule' }),
 	'schedule.week' : Object.freeze({ event : 'week', type : 'schedule' }),
 	'segment.contact.add' : Object.freeze({ event : 'segment.contact.add', type : 'event' }),
@@ -952,7 +1060,7 @@ const HOOK_NAMES = Object.freeze( names( HOOKS ) );
 // matched on it. A fifth outcome that no producer produces and no consumer reads
 // is a branch somebody writes one day for a case that cannot happen.
 //
-// Not to be confused with STATUSES.disconnected below, which is a CONNECTION's
+// Not to be confused with a CONNECTION's own status, which is
 // state and stays until a count says it can go.
 const OUTCOMES = Object.freeze({
 	answered : 'answered',
@@ -978,7 +1086,13 @@ const OUTCOMES = Object.freeze({
 // NO `incomplete`. That is an ORGANIZATION status meaning outstanding invoices,
 // and reusing the word for a connection would leave nobody able to say which
 // object a status referred to.
-const STATUSES = Object.freeze([ 'active', 'disconnected', 'error', 'pending' ]);
+//
+// NO `disconnected` EITHER, as of 2026-09-13. Nothing wrote it — drawbridge-api
+// DELETES a connection on disconnect — and its removal was gated on a count
+// rather than on the reading, because a value a live document still holds cannot
+// leave a strict validator without rejecting that document on its next write.
+// Counted read-only on both clusters the day it went: 0 on dev, 0 on prod.
+const STATUSES = Object.freeze([ 'active', 'error', 'pending' ]);
 
 // HOW A VENDOR IS CONNECTED — SAID BY THE SHAPE, not by an enum beside it.
 //
@@ -1198,18 +1312,16 @@ const bearing = ( entry ) => ERROR_SOURCES[ entry?.source ] !== false;
 // checked status alone, so saving a workflow flipped it active against a
 // connection sync immediately re-errored.
 //
-// TERMINAL STATES ARE NOT REASSESSED. `disconnected` is a merchant's decision,
-// and a passing health check proves a credential works — never that somebody
-// wants the connection. (Nothing writes it today: the api DELETES a connection on
-// disconnect. It stays in the vocabulary, and stays honoured here, until a count
-// on both clusters says it can leave.)
-const assess = ({ errors = [], status = null } = {}) => {
-
-	if( status === 'disconnected' ) return status;
-
-	return ( errors || [] ).some( bearing ) ? 'error' : 'active';
-
-};
+// NO TERMINAL STATE TO HONOUR ANY MORE. This used to return `disconnected`
+// untouched, on the reasoning that a passing health check proves a credential
+// works and never that somebody wants the connection. True — but nothing ever
+// wrote that status, because drawbridge-api deletes a connection on disconnect,
+// and it left the vocabulary once a count on both clusters read zero.
+//
+// So every status this can see is derived, and it derives all of them.
+const assess = ({ errors = [] } = {}) => (
+	( errors || [] ).some( bearing ) ? 'error' : 'active'
+);
 
 // WHAT SURVIVES A PASS THAT PROVED SOMETHING. A health run proves the credential,
 // so it may clear `oauth` and whatever else it judged — and must leave every
@@ -1223,6 +1335,301 @@ const surviving = ({ errors = [], proved = [] } = {}) => (
 // as a Mongo "Document failed validation" naming no field.
 const isStatus = ( status ) => STATUSES.includes( status );
 
+// CARRYING OUT WHAT A HOOK DESCRIBED, and the only place that does it.
+//
+// It lived in drawbridge-sync until drawbridge-api needed it too: the install
+// hooks describe writes, and an api route that performed them itself would be a
+// second implementation of this file. Two performers is exactly the drift this
+// package exists to remove — and the subtle half is not the writing, it is the
+// ORDERING and the transaction, which a second copy would eventually get wrong.
+//
+// ENQUEUE AND EMIT ARE INJECTED rather than imported. They are the two effects a
+// performer cannot own: sync enqueues onto its own BullMQ queues through the
+// telemetry wrapper and emits through its socket server, and the api has
+// neither. Everything else — the writes, the duplicate rule, the transaction —
+// is the same wherever the answer came from.
+
+const perform = async ({ answer, controller, emit, enqueue }) => {
+
+	const { enqueues, events, transaction, writes } = answerOf( answer ) || {};
+
+	const write = async ( { collection, data, ignoreDuplicate, multiple, operation, options, query }, session ) => {
+
+		// NOTHING IS REBUILT HERE. This used to reconstruct `_id` from a created
+		// document's `id`, because the injected `mintId` handed the manifests a bare
+		// string — a published package has no mongodb dependency and cannot make an
+		// ObjectId. So the pair was minted in one direction here and derived in the
+		// other by drawbridge-mongodb's own `ids()`, which already accepts a supplied
+		// `_id` and derives `id` from it. Two places minting one pair, opposite ways.
+		//
+		// `mintId` now returns BOTH halves and the hook places each, so a described
+		// write arrives already shaped and this is a plain pass-through.
+
+		try {
+
+			await controller[ operation ]({
+				collection,
+				data,
+				// The controller takes `multiple` beside options — an update that
+				// means every matching document must say so explicitly.
+				...( multiple && { multiple : true }),
+				...( ( options || session ) && { options : { ...options, ...( session && { session }) } }),
+				...( query && { query })
+			});
+
+		} catch ( error ){
+
+			// A DUPLICATE IS THE MECHANISM WORKING where the hook said so — the
+			// team-notify damper is a partial unique index, and a collision means this
+			// recipient has already been told inside the bucket. Everywhere else a
+			// duplicate key is a real failure and must still throw.
+			if( ! ( ignoreDuplicate && isDuplicateKey( error ) ) ) throw error;
+
+		}
+
+	};
+
+	// ALL OR NONE when the hook asked for it — the order/redemption pair, where a
+	// half-written attribution is revenue counted twice or not at all. Enqueues
+	// and events stay OUTSIDE and after: a job must not observe rows that later
+	// roll back, and an emit is not transactional anywhere.
+	if( transaction ){
+
+		await controller.transaction( async ( session ) => {
+
+			for( const descriptor of writes ) await write( descriptor, session );
+
+		});
+
+	} else {
+
+		for( const descriptor of writes ) await write( descriptor );
+
+	}
+
+	for( const { data, name, options, queue : target } of enqueues ){
+
+		// ENQUEUE AND EMIT ARE INJECTED, because they are the two things a
+		// performer cannot own. drawbridge-sync enqueues through the telemetry
+		// wrapper onto its own BullMQ queues and emits through its socket server;
+		// drawbridge-api has neither. A hook that describes one where the caller
+		// supplied no way to do it is a programming error, and it says so rather
+		// than dropping the effect on the floor.
+		if( ! enqueue ) throw new Error( 'A hook described an enqueue and this caller supplied no enqueuer' );
+
+		await enqueue({ data, name, options, queue : target });
+
+	}
+
+	for( const descriptor of events ){
+
+		if( ! emit ) throw new Error( 'A hook described a socket event and this caller supplied no emitter' );
+
+		emit( descriptor );
+
+	}
+
+};
+
+// WORK DONE ON A STORED CONNECTION ROW, FROM OUTSIDE A HOOK.
+//
+// Two things live here, and they are here for the same reason: each needs a
+// CONTROLLER, which a hook may never hold. A hook describes its effects and
+// perform() carries them out; these two are the cases where that split does not
+// fit, so they are the shell's work — but they were the shell's work in
+// drawbridge-sync, in a `lib/connection.js` that also imported the Shopify
+// client. That made them a second connections library beside this one.
+//
+// They take a controller as an ARGUMENT rather than importing anything, exactly
+// as perform() does. That is the established shape for a utils file that has to
+// touch the database.
+
+// FETCH A CONNECTION AND DECRYPT ITS SETTINGS IN ONE CALL. Callers pass the
+// whole query — by id, by organization and slug, with $in arrays — and typically
+// include `status : 'active'`.
+//
+// Answers `{ connection, settings }`, both null when nothing matched, so the
+// call site keeps its terse guard:
+//
+//     const { connection, settings } = await connectionSettings({ controller, query });
+//     if( ! connection ) return;
+const connectionSettings = async ({ controller, query }) => {
+
+	const connection = await controller.get({ collection : 'connection', query });
+
+	if( ! connection ) return { connection : null, settings : null };
+
+	return { connection, settings : decrypt( connection.settings ) };
+
+};
+
+const SCOPES_ERROR_SOURCE = 'scopes';
+
+// Merchant-facing text. It must match the entry drawbridge-api presents, so the
+// two writers converging on one row never change the message; the missing-scope
+// detail stays in the log.
+const SCOPES_ERROR_MESSAGE = 'Shopify permissions are out of date. Open the Drawbridge app in your Shopify admin to approve the updated permissions.';
+
+// SCOPE-DRIFT ENFORCEMENT, SHOP-SCOPED — because every organization's connection
+// to the same store shares ONE grant.
+//
+// WHY THIS IS NOT A HOOK, which is the question it invites. A hook answers for
+// one connection and describes writes for that connection. This one reads a
+// grant held on a shared install record and then writes across EVERY
+// organization's connection to that store, plus their products and
+// advertisements. And `lifecycle.health` needs its RESULT to compose the message
+// it returns, which is why the health hook takes it as an injected
+// `reconcileScopes` rather than calling it.
+//
+// THE VENDOR STILL JUDGES ITS OWN GRANT. What is missing from a grant is
+// `auth.scopes`, asked here through runHook. What to DO about it is this
+// function. The judging half used to be a direct import of the Shopify client.
+//
+// Missing scopes: every connection for the shop goes `status : 'error'` with a
+// scopes-sourced entry, the store's products deactivate, and their
+// advertisements draft. Complete scopes: the entry is removed, status returns to
+// active when nothing else survives, and each product RE-SYNCS through its own
+// worker — the single reconciliation point — rather than a blanket reactivate,
+// which would wrongly revive products that are inactive because the merchant
+// unpublished them from the channel. Ads stay drafted for a deliberate
+// re-enable, matching the disconnect and unpublish cascades.
+//
+// `granted` is the grant to evaluate, a string or an array. Omitted, it is read
+// from the install record's stored session, which the embedded app rewrites on
+// every open. NO GRANT DATA AT ALL MEANS SKIP, never enforce: absence of evidence
+// must not error a healthy connection, and a legacy one-to-one install carries no
+// install record.
+const reconcileConnectionScopes = async ({
+	controller,
+	enqueue,
+	granted = null,
+	logger,
+	shop,
+	slug = 'shopify'
+}) => {
+
+	if( granted === null ){
+
+		const record = await controller.get({ collection : 'shop', query : { shop } });
+
+		const session = record?.settings ? decrypt( record.settings ) : null;
+
+		granted = session?.scope || null;
+
+	}
+
+	if( ! granted ) return null;
+
+	// NULL IS NOT AN EMPTY LIST. The hook answers null when the grant could not be
+	// read at all, and reading that as "nothing missing" is how a connection
+	// reports healthy while it has quietly stopped doing half its job.
+	const answered = await runHook( slug, 'auth.scopes', { scope : granted } );
+
+	const missing = answered.outcome === 'answered' ? answered.answer.result?.missing : null;
+
+	if( ! Array.isArray( missing ) ){
+
+		logger?.warn?.( 'connection.scopes.unreadable', { shop, slug });
+
+		return null;
+
+	}
+
+	const connections = await controller.aggregate({
+		collection : 'connection',
+		pipeline : [ { $match : { shop, slug } } ]
+	});
+
+	let hadScopesError = false;
+
+	for( const connection of connections ){
+
+		const others = ( connection.errors || [] ).filter( ( entry ) => entry.source !== SCOPES_ERROR_SOURCE );
+
+		const hasScopesError = others.length !== ( connection.errors || [] ).length;
+
+		hadScopesError = hadScopesError || hasScopesError;
+
+		if( missing.length ){
+
+			await controller.update({
+				collection : 'connection',
+				data : {
+					$set : {
+						errors : [ ...others, { message : SCOPES_ERROR_MESSAGE, source : SCOPES_ERROR_SOURCE } ],
+						status : 'error'
+					}
+				},
+				query : { id : connection.id }
+			});
+
+		} else if( hasScopesError ){
+
+			await controller.update({
+				collection : 'connection',
+				data : {
+					$set : {
+						errors : others,
+						...( connection.status === 'error' && ! others.length && { status : 'active' })
+					}
+				},
+				query : { id : connection.id }
+			});
+
+		}
+
+	}
+
+	const products = connections.length
+		? await controller.aggregate({
+			collection : 'product',
+			pipeline : [ { $match : { 'provider.slug' : slug, 'source.domain' : shop } } ]
+		})
+		: [];
+
+	if( missing.length && products.length ){
+
+		const productIds = products.map( ( product ) => product.id );
+
+		await controller.update({
+			collection : 'product',
+			data : { $set : { status : 'inactive' } },
+			multiple : true,
+			query : { id : { $in : productIds } }
+		});
+
+		await controller.update({
+			collection : 'advertisement',
+			data : { $set : { status : 'drafted' } },
+			multiple : true,
+			query : { product : { $in : productIds } }
+		});
+
+	} else if( ! missing.length && hadScopesError && enqueue ){
+
+		// ENQUEUE IS INJECTED, for the same reason perform()'s is: this package
+		// holds no BullMQ queues, and a caller that supplied no enqueuer gets the
+		// writes without the re-sync rather than a crash. The health path supplies
+		// one; a caller that only wants the status corrected need not.
+		for( const product of products ){
+
+			await enqueue({
+				data : { product : product.id },
+				name : 'sync',
+				options : { jobId : 'product.' + slug + '.' + product.id + '.' + Date.now() },
+				queue : 'product.' + slug
+			});
+
+		}
+
+	}
+
+	logger?.info?.( 'connection.scopes.reconciled', { connections : connections.length, missing, shop });
+
+	return missing;
+
+};
+
 // THE WORKFLOWS A CONNECTION OWNS, provisioned from its manifest.
 //
 // It lived in drawbridge-sync until it was needed twice: sync provisions lazily
@@ -1250,6 +1657,54 @@ const systemSteps = ( node, path = [] ) => Object.entries( node || {} ).flatMap(
 	}
 );
 
+// THE WORKFLOWS A MANIFEST DECLARES, as data and without writing any of them.
+//
+// SHARED WITH THE MIGRATION THAT REPORTS WHAT IS MISSING. drawbridge-api's
+// provisionSystemWorkflows had its own copy of this walk so a dry run could say
+// what it WOULD create without creating it — and the copy fell behind the moment
+// a workflow could carry several steps: it keyed titles off each step's own
+// `key`, so a grouped pair looked like two workflows named after steps rather
+// than one named after the grouping. Two walks over the same manifests is
+// exactly the drift this package exists to remove, so there is one.
+//
+// ONE ROW PER TITLE, and several steps may share one. A step that declares
+// `workflow` takes its title, its trigger and its position from there; every
+// other step is a workflow of one, titled by its own key.
+//
+// NO TRIGGER IS A DECISION, and it is honoured here: a system step with neither
+// its own trigger nor a workflow carrying one is declared so a stray dispatch
+// lands on a real queue, and provisioning a row for it would put something in
+// the merchant's list that never runs.
+//
+// SORTED BY DECLARED ORDER, because a workflow of several runs them in sequence
+// and the tree walk is alphabetical, which is not meaningful.
+const systemWorkflows = ( manifest ) => {
+
+	const grouped = new Map();
+
+	for( const [ type, declared ] of systemSteps( manifest?.steps ) ){
+
+		const trigger = declared.workflow?.trigger || declared.trigger;
+
+		if( ! trigger?.event || ! trigger?.type ) continue;
+
+		const title = declared.workflow?.key || declared.key;
+
+		if( ! title ) continue;
+
+		if( ! grouped.has( title ) ) grouped.set( title, { steps : [], title, trigger });
+
+		grouped.get( title ).steps.push({ order : declared.workflow?.order ?? 0, type });
+
+	}
+
+	return [ ...grouped.values() ].map( ( workflow ) => ({
+		...workflow,
+		steps : workflow.steps.slice().sort( ( a, b ) => a.order - b.order )
+	}) );
+
+};
+
 // THE WORKFLOWS A CONNECTION OWNS, provisioned from the manifest rather than
 // from a branch per step type. A vendor that declares a new system step with a
 // trigger gets its workflow with no edit here, which is the whole point of the
@@ -1268,8 +1723,13 @@ const systemSteps = ( node, path = [] ) => Object.entries( node || {} ).flatMap(
 // { connection, system, title } where system is true refuses every create but
 // the first, and the catch below is what lets a loser carry on.
 //
-// Shopify is excluded: its register job creates the same workflow with three
-// siblings, and racing it here would write a duplicate.
+// SHOPIFY IS NO LONGER EXCLUDED. It was, because its register job hand-wrote the
+// same four workflows and racing it here would write duplicates — and the reason
+// that spec could not simply be deleted is that one of its four, "Shopify Token
+// Activity", carries TWO steps, which a declaration had no way to express. It
+// does now: a step may declare `workflow`, naming the title, the trigger and its
+// order, and the grouping below provisions one row for all the steps that share
+// a key. The hand-written spec is gone with it.
 //
 // `connections` is a parameter whose default is the real registry. The seam is
 // there so this module's behaviour can be tested against a manifest shape — a
@@ -1278,7 +1738,7 @@ const systemSteps = ( node, path = [] ) => Object.entries( node || {} ).flatMap(
 // to be installed. Production callers pass nothing and get the real thing.
 const ensureSystemWorkflows = async ({ connections : registry = connections, controller, doc }) => {
 
-	if( ! doc?.id || doc.slug === 'shopify' ) return [];
+	if( ! doc?.id ) return [];
 
 	const manifest = registry[ doc.slug ];
 
@@ -1286,17 +1746,7 @@ const ensureSystemWorkflows = async ({ connections : registry = connections, con
 
 	const provisioned = [];
 
-	for( const [ type, declared ] of systemSteps( manifest.steps ) ){
-
-		// NO TRIGGER IS A DECISION. Shopify's token-audit steps are declared so a
-		// stray dispatch lands on a real queue, and are never fired — provisioning
-		// a workflow for them would put a row in the merchant's list for something
-		// that never runs.
-		if( ! declared.trigger?.event || ! declared.trigger?.type ) continue;
-
-		const title = declared.key;
-
-		if( ! title ) continue;
+	for( const { steps : members, title, trigger } of systemWorkflows( manifest ) ){
 
 		const existing = await controller.count({
 			collection : 'workflow',
@@ -1316,13 +1766,10 @@ const ensureSystemWorkflows = async ({ connections : registry = connections, con
 			connection : doc.id,
 			organization : doc.organization,
 			status : 'active',
-			steps : [ {
-				settings : {},
-				type
-			} ],
+			steps : members.map( ( { type } ) => ({ settings : {}, type }) ),
 			system : true,
 			title,
-			trigger : declared.trigger
+			trigger
 		};
 
 		let created;
@@ -1361,6 +1808,213 @@ const ensureSystemWorkflows = async ({ connections : registry = connections, con
 
 };
 
+// THE FACTS OF THE REGISTRY, AS MARKDOWN.
+//
+// `drawbridge-docs/reference/connection-hooks.md` carried a support matrix under
+// the footnote "Generated from the manifests in drawbridge-utils — if this table
+// and the package disagree, the package is right."
+//
+// IT WAS NOT GENERATED, AND THEY DISAGREED. Measured 2026-09-12, before this
+// existed: four columns against six manifests, seventeen rows against
+// thirty-one hook slots, and THREE OF THE THIRTEEN checkable rows were factually
+// wrong — auth.connect documented `yes` for two vendors that decline it,
+// auth.disconnect `yes` for three that decline it, auth.scopes `no` for Klaviyo,
+// which implements it. Plus twenty-seven references to a `catalog.*` domain that
+// had been called `resources.*` for two renames.
+//
+// So the facts are emitted from the registry and the doc includes them. THE
+// PROSE AROUND THEM STAYS HAND-WRITTEN: the reasoning about why
+// `resources.prices` is declined everywhere is worth a person's words. Only the
+// facts rot, so only the facts are generated.
+//
+// A test asserts that regenerating produces no diff — which is the check that
+// footnote always claimed and nobody ever ran.
+
+const MARKER = {
+	end : '<!-- /generated -->',
+	start : '<!-- generated: drawbridge-utils lib/connections/reference.js — do not edit by hand -->'
+};
+
+const slugs = () => Object.keys( connections ).sort();
+
+// Every hook slot, in the vocabulary's own order, as dotted names. HOOKS nests
+// arbitrarily deep — `notification.email.send`, `install.organizations.add` —
+// and the depth is part of the name.
+const slots = ( node = HOOKS, path = [] ) => Object.entries( node ).flatMap(
+	( [ key, value ] ) => (
+		Array.isArray( value )
+			? value.map( ( verb ) => [ ...path, key, verb ].join( '.' ) )
+			: slots( value, [ ...path, key ] )
+	)
+);
+
+const implemented$1 = ( hooks, name ) => {
+
+	const found = name.split( '.' ).reduce(
+		( node, key ) => ( node && typeof node === 'object' && Object.hasOwn( node, key ) ) ? node[ key ] : undefined,
+		hooks
+	);
+
+	if( typeof found === 'function' ) return 'yes';
+
+	// `{}` IS A THIRD ANSWER, not a yes: declared here, implemented in the repo
+	// holding the dependencies. Collapsing it into `yes` is how a doc tells a
+	// reader the package can do something it cannot.
+	if( found && typeof found === 'object' ) return 'elsewhere';
+
+	return 'no';
+
+};
+
+const table = ( header, rows ) => [
+	'| ' + header.join( ' | ' ) + ' |',
+	'|' + header.map( () => '---' ).join( '|' ) + '|',
+	...rows.map( ( row ) => '| ' + row.join( ' | ' ) + ' |' )
+].join( '\n' );
+
+const matrix = () => {
+
+	const columns = slugs();
+
+	return table(
+		[ 'Hook', ...columns ],
+		slots().map( ( name ) => [
+			'`' + name + '`',
+			...columns.map( ( slug ) => implemented$1( connections[ slug ].hooks, name ) )
+		] )
+	);
+
+};
+
+const vocabularies = () => {
+
+	const list = ( values ) => values.map( ( value ) => '`' + value + '`' ).join( ', ' );
+
+	return table(
+		[ 'Vocabulary', 'Values' ],
+		[
+			[ '`AUTH_KINDS`', list( AUTH_KINDS ) ],
+			[ '`GROUPS`', list( GROUPS ) ],
+			[ '`INPUTS`', list( INPUTS ) ],
+			[ '`STATUSES`', list( STATUSES ) ],
+			[ '`TRIGGERS`', list( Object.keys( TRIGGERS ).sort() ) ],
+			[ '`TRIGGER_TYPES`', list( TRIGGER_TYPES ) ]
+		]
+	);
+
+};
+
+// Every step in the registry, with the hook it calls and what fires it. A step
+// with NO hook is real and stays visible: Shopify's token-audit pair is declared
+// for routing and never dispatched.
+const steps = () => {
+
+	const rows = [];
+
+	const walk = ( node, path, slug ) => {
+
+		if( ! node || typeof node !== 'object' ) return;
+
+		for( const [ key, value ] of Object.entries( node ) ){
+
+			if( typeof value === 'function' ){
+
+				let declared;
+
+				try { declared = value({}); } catch { continue; }
+
+				if( ! declared?.type ) continue;
+
+				const fires = declared.workflow?.trigger || declared.trigger;
+
+				rows.push([
+					'`' + declared.type + '`',
+					slug,
+					declared.hook ? '`' + declared.hook + '`' : '—',
+					declared.queue,
+					declared.system ? 'system' : declared.withdrawn ? 'withdrawn' : 'builder',
+					fires ? '`' + fires.event + '` / `' + fires.type + '`' : ( declared.triggers || [] ).map( ( t ) => '`' + t + '`' ).join( ', ' ) || '—'
+				]);
+
+				continue;
+
+			}
+
+			walk( value, [ ...path, key ], slug );
+
+		}
+
+	};
+
+	for( const slug of slugs() ) walk( connections[ slug ].steps, [], slug );
+
+	return table( [ 'Step', 'Connection', 'Hook', 'Queue', 'Shape', 'Fired by' ], rows.sort( ( a, b ) => a[ 0 ].localeCompare( b[ 0 ] ) || a[ 1 ].localeCompare( b[ 1 ] ) ) );
+
+};
+
+// The workflows a connection is provisioned with, which is the other half of
+// "what runs on its own": a step is only reachable if something fires it.
+const workflows = () => table(
+	[ 'Workflow', 'Connection', 'Steps', 'Trigger' ],
+	slugs().flatMap( ( slug ) => systemWorkflows( connections[ slug ] ).map( ( workflow ) => [
+		workflow.title,
+		slug,
+		workflow.steps.map( ( step ) => '`' + step.type + '`' ).join( ' → ' ),
+		'`' + workflow.trigger.event + '` / `' + workflow.trigger.type + '`'
+	] ) )
+);
+
+const reference = () => [
+	MARKER.start,
+	'',
+	'### The support matrix',
+	'',
+	'`yes` is a body in this package. `elsewhere` is declared here and implemented in the repo holding the dependencies — a different fact from `no`, and collapsing the two is how a table tells a reader the package can do something it cannot.',
+	'',
+	matrix(),
+	'',
+	'### The closed vocabularies',
+	'',
+	vocabularies(),
+	'',
+	'### Every step',
+	'',
+	'A step with no hook is real: Shopify\'s token-audit pair is declared so a stray dispatch lands on a real queue, and is never fired.',
+	'',
+	steps(),
+	'',
+	'### The system workflows a connection is provisioned with',
+	'',
+	'Idempotent on (connection, system, title), so the TITLE is load-bearing — one that varied by account would provision a second workflow every time it changed.',
+	'',
+	workflows(),
+	'',
+	'### Counts',
+	'',
+	'- **' + slugs().length + '** connections',
+	'- **' + slots().length + '** hook slots',
+	'- **' + Object.keys( STEPS ).length + '** step types',
+	'- **' + Object.keys( TRIGGERS ).length + '** triggers',
+	'',
+	MARKER.end
+].join( '\n' );
+
+// Splice the generated block into a document, replacing whatever is between the
+// markers. Returns the document unchanged when it carries no markers, so a
+// caller can tell a doc that opted in from one that did not.
+const spliced = ( document ) => {
+
+	const from = document.indexOf( MARKER.start );
+	const to = document.indexOf( MARKER.end );
+
+	if( from < 0 || to < 0 ) return document;
+
+	return document.slice( 0, from ) + reference() + document.slice( to + MARKER.end.length );
+
+};
+
+const MARKERS = MARKER;
+
 // A LIVE ACCESS TOKEN, for any vendor that issues an expiring one.
 //
 // Written once here rather than per vendor, because every OAuth connection ends
@@ -1895,9 +2549,18 @@ var scaffold = {
 		commerce : {
 			// NEW in phase 1 — the Checkout Kit cart path, which writes nothing and is
 			// the last api surface Shopify owns outside a hook.
-			cart : async ( { connection, context }, { read } = {} ) => ANSWER,
+			// NO `connection` AND NO `step`: this one runs for a SHOPPER on a public
+			// page, not for an organization inside a workflow. It reads the storefront
+			// with the store's storefront token and mints a checkout token from
+			// DRAWBRIDGE'S app credentials, which is why the credential pair rides in
+			// as props — the way auth.disconnect already carries it.
+			cart : async ( { clientId, clientSecret, context, settings }, { fetcher, shopify } = {} ) => ANSWER,
 			code : async ( { connection, context, step }, { adminToken, shopify } = {} ) => ANSWER,
 			customer : async ( { connection, context }, { adminToken, read, shopify } = {} ) => ANSWER,
+			// STOCK, READ AT RENDER TIME rather than stored. It is the one product
+			// fact that is stale the instant it is written down, so the campaign
+			// product list asks the vendor and caches the answer for a minute.
+			inventory : async ( { connection, context }, { adminToken, shopify } = {} ) => ANSWER,
 			order : async ( { connection, context }, { logger, mintId, read } = {} ) => ANSWER,
 			// THIS IS WHERE `product.insert` LANDS.
 			//
@@ -1919,7 +2582,7 @@ var scaffold = {
 			// nothing and shows up only as `workflow.dispatch.candidates matched : 0` in
 			// a log. Phase 1 closes it and build() checks every trigger against it.
 			product : {
-				hook : async ( { connection, context, workflow }, { mintId, read } = {} ) => ANSWER,
+				hook : async ( { connection, context, settings, workflow }, { adminToken, mintId, read, shopify } = {} ) => ANSWER,
 				step : () => ({
 					description : 'Syncs product data from the vendor when a product changes.',
 					key : 'Vendor Product Sync',
@@ -2067,8 +2730,19 @@ var scaffold = {
 			// Vendor billing, the only group that is not generic. Pairs with
 			// auth.install.billing, which declares what the merchant is being charged.
 			plan : {
-				cancel : async ( { context }, { dispatch, read } = {} ) => ANSWER,
-				reselect : async ( { context }, { dispatch, read } = {} ) => ANSWER
+				cancel : async ( { context }, { read, shopify } = {} ) => ANSWER,
+				// NOT A MERCHANT ACTION EITHER — one attributed order's usage charge,
+				// sent to the vendor's meter. The credential pair rides in as props
+				// because the charge authenticates as the APP, not as the store.
+				charge : async ( { clientId, clientSecret, context, manifest }, { shopify } = {} ) => ANSWER,
+				// `mark` is the one write a description cannot carry: the marker must
+				// be persisted BEFORE the approval is released, and a described write
+				// lands after the hook returns.
+				reselect : async ( { context }, { mark, read, shopify } = {} ) => ANSWER,
+				// NOT A MERCHANT ACTION — the question "is this store's billing
+				// actually metered right now", asked by the daily health check and by
+				// the vendor's own approval webhook, which used to hand-copy it.
+				verify : async ( { context }, { adminToken, read, shopify } = {} ) => ANSWER
 			},
 			// The embedded app's own session, stored by us on the vendor's behalf.
 			session : {
@@ -2344,7 +3018,7 @@ var scaffold = {
 // A .js wrapper around otherwise untouched SVG so `node --test` can run against
 // lib/ directly. A bare .svg import would need a bundler loader and force the
 // tests through dist.
-var icon$7 = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xmlns="http://www.w3.org/2000/svg">
+var icon$8 = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xmlns="http://www.w3.org/2000/svg">
 <rect width="500" height="500" fill="#FFD967"/>
 <path d="M239.369 127.404C260.863 122.013 284.964 132.569 295.576 152.039C321.796 201.286 347.928 250.567 374.131 299.825C380.149 311.989 381.244 326.564 376.733 339.41C371.446 355.097 358.039 367.69 342.107 372.089C326.274 376.67 308.351 372.871 295.741 362.255C288.865 356.892 284.161 349.359 280.354 341.629C261.869 306.95 243.478 272.217 225.071 237.501C214.409 218.614 187.221 212.656 169.622 225.315C168.104 227.309 164.159 226.857 164.72 223.796C176.911 202.569 189.361 181.497 201.662 160.331C205.183 154.428 208.214 148.129 212.967 143.091C219.844 135.272 229.263 129.782 239.374 127.404" fill="#1E1C1C"/>
 <path d="M166.04 261.805C180.228 259.107 195.528 261.893 207.581 269.971C218.512 277.079 226.908 288.136 230.604 300.657C234.835 314.103 233.614 329.124 227.485 341.788C220.097 356.875 205.782 368.543 189.317 372.089C173.957 375.652 157.089 372.386 144.304 363.103C132.971 355.295 124.912 342.989 121.891 329.581C118.943 316.636 120.725 302.656 127.002 290.938C134.699 275.951 149.503 264.933 166.046 261.811" fill="#1E1C1C"/>
@@ -2711,16 +3385,19 @@ var attentive = {
 			'Anyone who has opted out in Drawbridge is sent to Attentive as an unsubscribe rather than omitted, so a person who asked not to be contacted stays suppressed in both systems instead of quietly reappearing.',
 			'Attentive accepts these updates and applies them in the background, so a contact appears in your segment shortly after the sync rather than the instant it runs.'
 		],
-		// NO VENDOR-SPECIFIC CONNECT COPY, and that is a decision rather than a gap.
-		// The dashboard already carries generic reasons for every way an
-		// authorization can fail — declined, expired state, a vendor we are not set
-		// up for — and a sentence here is an ADDITION to those, for a vendor whose
-		// failures need saying differently. This one's do not.
+		// WHAT THE MERCHANT READS WHEN A CONNECT FAILS. Two states, because the
+		// consent screen has two ways to end: they said no, or something between
+		// here and the vendor went wrong.
 		//
-		// Answered rather than omitted, because `errors` existed on two of six
-		// manifests and there was no way to tell "nothing to add" from "nobody
-		// wrote it".
-		errors : false,
+		// THE VENDOR IS NAMED IN BOTH. The dashboard's generic copy says "the
+		// authorization"; a merchant connecting two accounts in one sitting needs
+		// to know which one this was.
+		errors : {
+			connect : {
+				denied : 'The Attentive authorization was declined, so nothing was connected.',
+				invalid : 'We couldn\'t complete the Attentive connection. Try connecting again.'
+			}
+		},
 		excerpt : 'Sync your Drawbridge contacts into an Attentive segment.',
 		// NAMES THE SEGMENT STEP, because `status` below gates on it: a grant with
 		// no segment chosen sits at Pending, and a guide that stops at the consent
@@ -3174,7 +3851,7 @@ var attentive = {
 		webhook : false
 
 	},
-	icon: icon$7,
+	icon: icon$8,
 	// DERIVED from the vendors this connection spends — every `credential` their
 	// files declare. It used to be typed out here as well, which made the same env
 	// names a three-copy fact (here, auth.oauth.client, and the vendor field).
@@ -3793,7 +4470,7 @@ const contacts = {
 // A .js wrapper around otherwise untouched SVG so `node --test` can run against
 // lib/ directly. A bare .svg import would need a bundler loader and force the
 // tests onto dist/, which is a worse trade than one line of wrapper.
-var icon$6 = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xmlns="http://www.w3.org/2000/svg">
+var icon$7 = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xmlns="http://www.w3.org/2000/svg">
 <rect width="500" height="500" fill="#0D1314"/>
 <g clip-path="url(#clip0_2115_2832)">
 <path d="M153.198 142.241L183.69 196.065V303.852L153 357.676L184.82 375.028L220.116 313.163V186.865L185.046 125L153.198 142.241Z" fill="#BAEC5F"/>
@@ -3814,7 +4491,7 @@ var icon$6 = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xm
 // A .js wrapper around otherwise untouched SVG so `node --test` can run against
 // lib/ directly. A bare .svg import would need a bundler loader and force the
 // tests onto dist/, which is a worse trade than one line of wrapper.
-var icon$5 = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xmlns="http://www.w3.org/2000/svg">
+var icon$6 = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xmlns="http://www.w3.org/2000/svg">
 <rect width="500" height="500" fill="#FF7A59"/>
 <circle cx="290" cy="290" r="78" stroke="white" stroke-width="30"/>
 <circle cx="290" cy="290" r="18" fill="white"/>
@@ -3832,7 +4509,7 @@ var icon$5 = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xm
 // A .js wrapper around otherwise untouched SVG so `node --test` can run against
 // lib/ directly. A bare .svg import would need a bundler loader and force the
 // tests onto dist/, which is a worse trade than one line of wrapper.
-var icon$4 = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xmlns="http://www.w3.org/2000/svg">
+var icon$5 = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xmlns="http://www.w3.org/2000/svg">
 <rect width="500" height="500" fill="#F1FAFF"/>
 <g clip-path="url(#clip0_1011_2743)">
 <path d="M366.676 134.534V289.172H289.203V366.487H134.258L134.258 289.171L134.256 289.172V211.851H211.729V134.534H366.676Z" fill="#9DD6E3"/>
@@ -3855,7 +4532,7 @@ var icon$4 = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xm
 // A .js wrapper around otherwise untouched SVG so `node --test` can run against
 // lib/ directly. A bare .svg import would need a bundler loader and force the
 // tests onto dist/, which is a worse trade than one line of wrapper.
-var icon$3 = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xmlns="http://www.w3.org/2000/svg">
+var icon$4 = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xmlns="http://www.w3.org/2000/svg">
 <rect width="500" height="500" fill="#F22F46"/>
 <path d="M250 134.954C186.341 134.954 134.954 186.341 134.954 250C134.954 313.659 186.341 365.047 250 365.047C313.659 365.047 365.047 313.659 365.047 250C365.047 186.341 313.659 134.954 250 134.954ZM250 334.368C203.215 334.368 165.633 296.786 165.633 250C165.633 203.215 203.215 165.633 250 165.633C296.786 165.633 334.368 203.215 334.368 250C334.368 296.786 296.786 334.368 250 334.368ZM302.155 221.622C302.155 234.661 291.417 245.399 278.378 245.399C265.34 245.399 254.602 234.661 254.602 221.622C254.602 208.584 265.34 197.846 278.378 197.846C291.417 197.846 302.155 208.584 302.155 221.622ZM302.155 278.378C302.155 291.417 291.417 302.155 278.378 302.155C265.34 302.155 254.602 291.417 254.602 278.378C254.602 265.34 265.34 254.602 278.378 254.602C291.417 254.602 302.155 265.34 302.155 278.378ZM245.399 278.378C245.399 291.417 234.661 302.155 221.622 302.155C208.584 302.155 197.846 291.417 197.846 278.378C197.846 265.34 208.584 254.602 221.622 254.602C234.661 254.602 245.399 265.34 245.399 278.378ZM245.399 221.622C245.399 234.661 234.661 245.399 221.622 245.399C208.584 245.399 197.846 234.661 197.846 221.622C197.846 208.584 208.584 197.846 221.622 197.846C234.661 197.846 245.399 208.584 245.399 221.622Z" fill="white"/>
 </svg>`;
@@ -4255,15 +4932,12 @@ var drawbridge = {
 		description : [
 			'Drawbridge sends your notification emails and your entrants\' emails, and recalculates segment membership on a schedule. It is always on and needs nothing connected.'
 		],
-		// NO VENDOR-SPECIFIC CONNECT COPY, and that is a decision rather than a gap.
-		// The dashboard already carries generic reasons for every way an
-		// authorization can fail — declined, expired state, a vendor we are not set
-		// up for — and a sentence here is an ADDITION to those, for a vendor whose
-		// failures need saying differently. This one's do not.
+		// NOTHING IS EVER CONNECTED, so no connect can fail. This is the platform's
+		// own manifest — always on, private, never in the catalogue — and it exists
+		// to give Drawbridge's own steps a hook to point at. `denied` and `invalid`
+		// describe a consent screen this connection does not have.
 		//
-		// Answered rather than omitted, because `errors` existed on two of six
-		// manifests and there was no way to tell "nothing to add" from "nobody
-		// wrote it".
+		// `false` is the recorded decision, not silence.
 		errors : false,
 		excerpt : 'The steps Drawbridge runs itself.',
 		guide : [
@@ -5003,7 +5677,7 @@ var drawbridge = {
 		},
 		webhook : false
 	},
-	icon: icon$6,
+	icon: icon$7,
 
 	// WHERE TWILIO PUTS THINGS on an inbound request, and WHICH credential
 	// verifies each channel. The route resolves the NAME to the stored value and
@@ -5260,7 +5934,7 @@ var drawbridge = {
 // A .js wrapper around otherwise untouched SVG so `node --test` can run against
 // lib/ directly. A bare .svg import would need a bundler loader and force the
 // tests onto dist/, which is a worse trade than one line of wrapper.
-var icon$2 = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xmlns="http://www.w3.org/2000/svg">
+var icon$3 = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xmlns="http://www.w3.org/2000/svg">
 <rect width="500" height="500" fill="#FF4B32"/>
 <path d="M365.047 327.038H134.954V172.964H365.047L316.856 250.001L365.047 327.038Z" fill="#232121"/>
 </svg>`;
@@ -6242,7 +6916,7 @@ var klaviyo = {
 		webhook : false
 
 	},
-	icon: icon$2,
+	icon: icon$3,
 	// DERIVED from the vendors this connection spends — every `credential` their
 	// files declare. It used to be typed out here as well, which made the same env
 	// names a three-copy fact (here, auth.oauth.client, and the vendor field).
@@ -6401,7 +7075,7 @@ var klaviyo = {
 // A .js wrapper around otherwise untouched SVG so `node --test` can run against
 // lib/ directly. A bare .svg import would need a bundler loader and force the
 // tests onto dist/, which is a worse trade than one line of wrapper.
-var icon$1 = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xmlns="http://www.w3.org/2000/svg">
+var icon$2 = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xmlns="http://www.w3.org/2000/svg">
 <rect width="500" height="500" fill="#FFE01B"/>
 <path d="M310.633 243.561C312.49 243.336 314.249 243.308 315.882 243.561C316.81 241.394 316.979 237.665 316.149 233.598C314.882 227.561 313.18 223.917 309.662 224.508C306.13 225.071 305.989 229.433 307.269 235.47C307.973 238.847 309.24 241.746 310.633 243.561ZM280.392 248.332C282.925 249.429 284.473 250.147 285.05 249.542C285.458 249.148 285.345 248.36 284.74 247.375C283.112 245.042 280.844 243.229 278.211 242.154C275.397 240.982 272.328 240.556 269.301 240.916C266.274 241.275 263.391 242.41 260.93 244.209C259.256 245.447 257.666 247.15 257.863 248.191C257.961 248.515 258.186 248.782 258.777 248.895C260.17 249.049 265.025 246.587 270.64 246.249C274.608 245.968 277.859 247.206 280.392 248.332ZM275.312 251.216C272.047 251.737 270.232 252.807 269.078 253.848C268.079 254.72 267.488 255.649 267.488 256.339L267.741 256.93L268.262 257.127C269.008 257.127 270.668 256.479 270.668 256.479C275.228 254.861 278.253 255.044 281.25 255.382C282.897 255.579 283.671 255.663 284.037 255.1C284.135 254.931 284.29 254.608 283.938 254.059C283.15 252.778 279.843 250.682 275.312 251.216ZM300.416 261.855C302.654 262.953 305.102 262.502 305.904 260.884C306.735 259.266 305.567 257.056 303.329 255.973C301.106 254.861 298.643 255.283 297.841 256.902C297.039 258.52 298.207 260.757 300.416 261.855ZM314.742 249.317C312.94 249.289 311.449 251.259 311.393 253.764C311.35 256.254 312.8 258.281 314.615 258.295C316.43 258.323 317.922 256.339 317.964 253.862C318.006 251.385 316.571 249.359 314.742 249.317ZM193.103 294.108C192.653 293.545 191.907 293.7 191.189 293.897C190.683 293.995 190.12 294.136 189.515 294.122C188.909 294.134 188.308 293.998 187.767 293.726C187.225 293.454 186.757 293.054 186.405 292.56C185.575 291.294 185.617 289.394 186.546 287.241L186.968 286.27C188.431 283.019 190.838 277.559 188.122 272.367C187.234 270.534 185.908 268.948 184.261 267.75C182.614 266.553 180.697 265.78 178.679 265.5C176.772 265.256 174.835 265.469 173.026 266.123C171.218 266.776 169.591 267.85 168.28 269.257C164.284 273.661 163.679 279.684 164.439 281.823C164.734 282.611 165.184 282.822 165.494 282.864C166.169 282.963 167.169 282.456 167.802 280.754L167.999 280.219C168.28 279.318 168.801 277.63 169.659 276.307C170.717 274.689 172.375 273.558 174.267 273.162C176.159 272.766 178.131 273.138 179.749 274.196C182.563 276.039 183.619 279.473 182.423 282.752C181.803 284.455 180.804 287.691 181.015 290.351C181.466 295.74 184.815 297.907 187.77 298.175C190.669 298.273 192.695 296.655 193.216 295.459C193.511 294.713 193.258 294.277 193.103 294.108Z" fill="#231E15"/>
 <path d="M360.476 284.243C360.35 283.835 359.618 281.204 358.647 278.052L356.621 272.648C360.575 266.696 360.645 261.405 360.124 258.393C359.531 254.519 357.693 250.944 354.89 248.205C351.766 244.94 345.363 241.563 336.385 239.044L331.671 237.736C331.643 237.524 331.418 226.619 331.235 221.933C331.08 218.555 330.798 213.264 329.152 208.058C327.182 200.993 323.791 194.858 319.527 190.876C331.277 178.717 338.594 165.307 338.58 153.81C338.538 131.703 311.379 124.976 277.902 138.851L270.824 141.863C270.795 141.835 258.004 129.283 257.821 129.128C219.63 95.8334 100.327 228.476 138.49 260.687L146.835 267.737C144.581 273.775 143.781 280.259 144.499 286.664C145.414 295.543 149.973 304.029 157.375 310.6C164.411 316.82 173.684 320.788 182.648 320.774C197.494 354.998 231.408 375.965 271.175 377.161C313.842 378.427 349.641 358.403 364.67 322.435C365.641 319.916 369.806 308.546 369.806 298.513C369.792 288.409 364.093 284.229 360.476 284.243ZM185.913 311.149C184.613 311.381 183.293 311.48 181.973 311.445C169.083 311.079 155.166 299.483 153.787 285.735C152.253 270.537 160.02 258.829 173.783 256.071C175.415 255.72 177.414 255.537 179.552 255.635C187.264 256.085 198.606 261.996 201.209 278.784C203.517 293.63 199.858 308.785 185.913 311.149ZM171.545 246.953C163.179 248.499 155.744 253.244 150.817 260.18C148.045 257.873 142.909 253.426 142.008 251.681C134.635 237.693 150.043 210.478 160.823 195.111C187.405 157.145 229.086 128.424 248.393 133.603C251.517 134.503 261.902 146.563 261.902 146.563C261.902 146.563 242.623 157.244 224.724 172.16C200.646 190.735 182.423 217.697 171.545 246.953ZM306.792 305.464C306.937 305.403 307.057 305.295 307.134 305.157C307.211 305.019 307.239 304.86 307.214 304.704C307.205 304.61 307.178 304.519 307.133 304.436C307.088 304.353 307.027 304.28 306.954 304.221C306.88 304.162 306.796 304.118 306.705 304.092C306.614 304.066 306.519 304.059 306.426 304.071C306.426 304.071 286.246 307.054 267.179 300.089C269.247 293.348 274.792 295.754 283.137 296.444C296.108 297.209 309.116 295.802 321.623 292.279C330.25 289.788 341.592 284.905 350.401 277.953C353.384 284.497 354.425 291.674 354.425 291.674C354.425 291.674 356.719 291.265 358.647 292.447C360.476 293.573 361.799 295.895 360.898 301.89C359.027 313.119 354.271 322.224 346.235 330.611C341.236 336.036 335.277 340.492 328.659 343.754C324.983 345.691 321.151 347.32 317.205 348.623C286.964 358.487 256.006 347.638 246.029 324.321C245.224 322.535 244.556 320.691 244.03 318.804C239.781 303.438 243.383 285.032 254.655 273.408C255.372 272.676 256.09 271.804 256.09 270.706C256.09 269.806 255.499 268.835 255.007 268.131C251.066 262.418 237.374 252.666 240.132 233.795C242.088 220.23 253.951 210.689 265.012 211.252L267.826 211.421C272.611 211.702 276.79 212.307 280.73 212.49C287.344 212.758 293.268 211.801 300.304 205.947C302.683 203.949 304.582 202.246 307.791 201.711C308.128 201.627 308.973 201.359 310.647 201.416C312.365 201.485 314.032 202.015 315.474 202.949C321.103 206.693 321.905 215.783 322.214 222.439C322.383 226.225 322.848 235.414 322.988 238.031C323.354 244.054 324.944 244.912 328.125 245.954C329.94 246.573 331.615 246.995 334.077 247.713C341.521 249.781 345.968 251.934 348.754 254.65C350.198 256.049 351.13 257.893 351.4 259.885C352.315 266.316 346.432 274.252 330.925 281.457C313.954 289.324 293.367 291.322 279.154 289.732L274.173 289.169C262.774 287.649 256.315 302.34 263.14 312.402C267.545 318.889 279.52 323.11 291.523 323.11C319.006 323.139 340.142 311.402 348.023 301.242L348.642 300.356C349.008 299.765 348.712 299.469 348.22 299.779C341.817 304.169 313.279 321.619 282.771 316.384C282.771 316.384 279.056 315.765 275.678 314.442C273.005 313.429 267.362 310.811 266.686 305.042C291.27 312.683 306.792 305.478 306.792 305.464ZM220.671 194.971C230.127 184.051 241.765 174.538 252.206 169.219C252.558 169.022 252.938 169.43 252.741 169.754C251.46 172 250.476 174.403 249.814 176.902C249.73 177.282 250.138 177.592 250.461 177.353C256.963 172.934 268.248 168.192 278.155 167.601C278.251 167.584 278.351 167.601 278.436 167.65C278.521 167.698 278.586 167.775 278.621 167.866C278.656 167.957 278.658 168.058 278.627 168.151C278.596 168.244 278.533 168.323 278.451 168.375C276.809 169.634 275.342 171.105 274.088 172.751C273.891 173.032 274.074 173.44 274.426 173.44C281.378 173.483 291.186 175.903 297.56 179.491C297.982 179.745 297.673 180.575 297.209 180.462C287.527 178.253 271.724 176.564 255.288 180.575C240.597 184.149 229.396 189.666 221.248 195.618C220.826 195.899 220.333 195.351 220.671 194.971Z" fill="#231E15"/>
@@ -6607,16 +7281,19 @@ var mailchimp = {
 			'Anyone who has opted out in Drawbridge is synced as unsubscribed rather than omitted, so a person who asked not to be contacted stays suppressed in both systems instead of quietly reappearing.',
 			'Someone who unsubscribed inside Mailchimp keeps that choice: a resync only sets the status of a subscriber Mailchimp has never seen before.'
 		],
-		// NO VENDOR-SPECIFIC CONNECT COPY, and that is a decision rather than a gap.
-		// The dashboard already carries generic reasons for every way an
-		// authorization can fail — declined, expired state, a vendor we are not set
-		// up for — and a sentence here is an ADDITION to those, for a vendor whose
-		// failures need saying differently. This one's do not.
+		// WHAT THE MERCHANT READS WHEN A CONNECT FAILS. Two states, because the
+		// consent screen has two ways to end: they said no, or something between
+		// here and the vendor went wrong.
 		//
-		// Answered rather than omitted, because `errors` existed on two of six
-		// manifests and there was no way to tell "nothing to add" from "nobody
-		// wrote it".
-		errors : false,
+		// THE VENDOR IS NAMED IN BOTH. The dashboard's generic copy says "the
+		// authorization"; a merchant connecting two accounts in one sitting needs
+		// to know which one this was.
+		errors : {
+			connect : {
+				denied : 'The Mailchimp authorization was declined, so nothing was connected.',
+				invalid : 'We couldn\'t complete the Mailchimp connection. Try connecting again.'
+			}
+		},
 		excerpt : 'Sync your Drawbridge contacts into a Mailchimp audience.',
 		// NAMES THE AUDIENCE STEP, because `status` below gates on it: a grant with
 		// no audience chosen sits at Pending, and a guide that stops at the consent
@@ -7268,7 +7945,7 @@ var mailchimp = {
 		// Drawbridge posts to a merchant's own endpoint, never through a vendor.
 		webhook : false
 	},
-	icon: icon$1,
+	icon: icon$2,
 	// The OAuth client this deployment registered. Without both, the vendor drops
 	// out of availableConnections rather than offering a Connect button that
 	// cannot complete.
@@ -7428,12 +8105,34 @@ var mailchimp = {
 // A .js wrapper around otherwise untouched SVG so `node --test` can run against
 // lib/ directly. A bare .svg import would need a bundler loader and force the
 // tests onto dist/, which is a worse trade than one line of wrapper.
-var icon = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xmlns="http://www.w3.org/2000/svg">
+var icon$1 = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xmlns="http://www.w3.org/2000/svg">
 <rect width="500" height="500" fill="#95C049"/>
 <path d="M292.997 147.633C292.997 147.633 289.98 148.495 285.023 150.004C284.161 147.202 282.868 143.969 281.144 140.521C275.54 129.744 267.134 123.925 257.22 123.925C256.574 123.925 255.927 123.925 255.065 124.141C254.849 123.71 254.418 123.494 254.203 123.063C249.892 118.322 244.289 116.166 237.607 116.382C224.676 116.813 211.744 126.081 201.399 142.676C194.071 154.314 188.468 168.97 186.959 180.393C172.088 184.919 161.743 188.152 161.527 188.367C153.984 190.738 153.768 190.954 152.906 198.066C151.613 203.454 132 355.4 132 355.4L294.937 383.633V147.202C294.075 147.418 293.429 147.418 292.997 147.633ZM255.281 159.271C246.66 161.858 237.176 164.875 227.909 167.677C230.495 157.547 235.668 147.418 241.702 140.736C244.073 138.365 247.306 135.564 250.97 133.839C254.634 141.598 255.496 152.159 255.281 159.271ZM237.823 125.003C240.84 125.003 243.427 125.649 245.582 126.943C242.133 128.667 238.685 131.469 235.452 134.702C227.262 143.538 221.012 157.332 218.426 170.479C210.667 172.85 202.908 175.22 195.796 177.376C200.322 156.901 217.779 125.649 237.823 125.003ZM212.607 243.542C213.469 257.335 249.892 260.353 252.048 292.897C253.556 318.545 238.47 336.002 216.701 337.295C190.407 339.02 175.967 323.502 175.967 323.502L181.571 299.794C181.571 299.794 196.011 310.786 207.649 309.924C215.193 309.493 217.995 303.242 217.779 298.932C216.701 280.828 186.959 281.905 185.019 252.163C183.295 227.377 199.675 202.161 235.883 199.79C249.892 198.928 257.005 202.377 257.005 202.377L248.815 233.412C248.815 233.412 239.547 229.102 228.555 229.964C212.607 231.041 212.391 241.171 212.607 243.542ZM263.902 156.685C263.902 150.219 263.039 140.952 260.022 133.193C269.936 135.133 274.678 146.124 276.833 152.806C272.954 153.883 268.643 155.176 263.902 156.685Z" fill="white"/>
 <path d="M300.325 382.771L368 365.96C368 365.96 338.904 169.185 338.689 167.892C338.473 166.599 337.396 165.737 336.318 165.737C335.24 165.737 316.274 165.306 316.274 165.306C316.274 165.306 304.636 154.099 300.325 149.788V382.771Z" fill="white"/>
 </svg>`;
 
+// THE CLIENT, IMPORTED AND DEFAULTED — the same shape as `fetcher = fetch`
+// everywhere else in this package.
+//
+// It used to be injected because @drawbridge/shopify depended on this package,
+// so this file could not import it. That cycle is gone: the client lives in
+// lib/shopify/ now. But the injection had a SECOND job nobody wrote down — it is
+// the test seam, and it is at the right level. The hook tests stub
+// getActiveAppSubscriptions and getUsageChargeEvents and assert the arguments
+// they were called with; stubbing raw HTTP instead would mean hand-building
+// Shopify GraphQL envelopes and would lose those assertions entirely.
+//
+// So the default is the real client and callers inject nothing. Production
+// passes no `shopify` option at all — drawbridge-api and drawbridge-sync have
+// stopped wiring one — and a test overrides exactly the namespace it needs.
+const client = Object.freeze({
+	admin : shopifyAdmin,
+	billing : shopifyBilling,
+	oauth : shopifyOauth,
+	partner : shopifyPartner,
+	storefront : shopifyStorefront
+});
+
 // ── ORDER ATTRIBUTION, the vendor's own arithmetic ───────────────────────────
 //
 // Orders are attributed via `_drwbrdg_*` line-item properties injected at
@@ -7553,7 +8252,7 @@ const discountWarning = ( discount ) => {
 // equal, case-sensitively, the meter HANDLE configured on the app's plan in
 // the Dev Dashboard (the plan editor's Handle field — display names prove
 // nothing) and the SHOPIFY_USAGE_ORDERS_EVENT_HANDLE default in
-// @drawbridge/shopify, which this package cannot import. This is the single
+// the Shopify client, which lives in this package now. This is the single
 // mint point on the utils side: the transaction id is prefixed with it, the
 // billing enqueue carries it, and the manifest publishes it under
 // auth.install.billing.handle — so drawbridge-sync can refuse to send an event whose
@@ -7624,8 +8323,548 @@ const COMPLIANCE_TOPICS = new Set([
 	'shop/redact'
 ]);
 
-// Shopify — installed from the App Store, never connected with keys.
-var shopify = {
+// ── THE EMBEDDED-APP SURFACE ─────────────────────────────────────────────────
+//
+// Everything from here to the end of this block serves `hooks.install`, which
+// is what api/route/shopify-embedded.js became: 1,386 lines and thirteen routes
+// whose paths all began `/shopify/embedded/` — a vendor's name in a url, on a
+// surface no other connection could ever reach.
+
+// A REFUSAL WITH A STATUS. runHook already carries `error.status` out to the
+// caller for exactly this — inbound.verify answers 401 on a forged signature the
+// same way — so the install slots say 402, 403, 409, 422 or 502 in the same
+// breath as the reason, and the route answers what they said rather than folding
+// every rejection into a 500.
+const refusal = ( message, status ) => Object.assign( new Error( message ), { status });
+
+// THIRTY MINUTES for the one-shot link token. Long enough for a merchant to
+// finish a consent screen, short enough that a stranded token is not a standing
+// key to a store.
+const LINK_TOKEN_TTL_MS = 30 * 60 * 1000;
+
+// The statuses the connection-write gate accepts, mirroring the dashboard's
+// own list on every organization-connection route. Read by BOTH `add` and
+// `list`, so the list cannot tell a merchant an org is connectable and then
+// have `add` refuse it.
+const CONNECTABLE_STATUSES = [ 'active', 'unsubscribed' ];
+
+// THE MERCHANT'S OWN ORGANIZATIONS — owned, or joined with the `connections`
+// capability at `manage`. Shared by the list and the two org slots that gate on
+// access, and each org carries its Shopify connection ({ id, shop, status }) so
+// the one-store-per-organization rule is answered in the same round trip.
+const merchantOrganizations = ({ read, user }) => read.aggregate({
+	collection : 'organization',
+	pipeline : [
+		// A member qualifies only at `manage`; an owner always qualifies.
+		{
+			$lookup : {
+				as : 'membership',
+				from : 'member',
+				let : { organization : '$id' },
+				pipeline : [
+					{
+						$match : {
+							$expr : { $eq : [ '$organization', '$$organization' ] },
+							'capabilities.connections' : 'manage',
+							status : 'accepted',
+							user
+						}
+					},
+					{ $limit : 1 },
+					{ $project : { _id : 0, organization : 1 } }
+				]
+			}
+		},
+		{
+			$match : {
+				status : { $ne : 'canceled' },
+				$or : [ { owner : user }, { 'membership.0' : { $exists : true } } ]
+			}
+		},
+		// `organization.subscription` is a subscription RECORD ID — resolved here so
+		// the list can read the real plan and conversion rate. Without it every org
+		// rendered as free tier.
+		{ $lookup : { as : 'subscription', foreignField : 'id', from : 'subscription', localField : 'subscription' } },
+		{ $unwind : { path : '$subscription', preserveNullAndEmptyArrays : true } },
+		{
+			$lookup : {
+				as : 'connection',
+				foreignField : 'organization',
+				from : 'connection',
+				localField : 'id',
+				pipeline : [
+					{ $match : { slug : 'shopify' } },
+					{ $limit : 1 },
+					{ $project : { _id : 0, id : 1, shop : 1, status : 1 } }
+				]
+			}
+		},
+		{ $unwind : { path : '$connection', preserveNullAndEmptyArrays : true } },
+		{ $project : { _id : 0, billingStatus : '$status', connection : 1, id : 1, name : '$title', subscription : 1 } },
+		{ $sort : { name : 1 } }
+	]
+});
+
+// THE STORE'S LIVE APP PRICING STATUS. getActiveAppSubscriptions returns only
+// ACTIVE subscriptions, so a non-empty list means the merchant approved a plan.
+//
+// BEST-EFFORT, AND THE FAILURE IS NAMED. "No plan" and "couldn't check" are
+// different answers — `add` returns a retryable 502 for the latter rather than
+// telling a paying merchant to approve a plan.
+const storePlan = async ({ record, shopify }) => {
+
+	const settings = record?.settings ? decrypt( record.settings ) : null;
+
+	if( ! settings?.accessToken ) return { active : false, name : null };
+
+	try {
+
+		const { subscriptions } = await shopify.admin.getActiveAppSubscriptions({
+			adminAccessToken : settings.accessToken,
+			domain : record.shop
+		});
+
+		const active = ( subscriptions || [] ).length > 0;
+
+		// A USAGE LINE ON THE APPROVAL IS POSITIVE EVIDENCE (metered true); its
+		// ABSENCE IS NO VERDICT (null). Measured 2026-09-04 on both 2026-04 and
+		// unstable: managed-pricing App-Events meters never materialize as
+		// subscription line items, so absence must not drive the App Home banner.
+		// `false` is reserved for a signal that can actually observe the meter —
+		// Partner-ledger accrual, which sync stamps onto the connection.
+		const metered = active && subscriptions.some( ( subscription ) => subscription.metered === true ) ? true : null;
+
+		return { active, metered, name : active ? subscriptions[ 0 ]?.name || null : null };
+
+	} catch ( _ ) {
+
+		return { active : false, name : null, unavailable : true };
+
+	}
+
+};
+
+// RELEASE EVERY ACTIVE APPROVAL for this app on this store. Shared by `cancel`
+// and `reselect`, which differ only in what happens before and what it means —
+// the mechanics are identical, and two copies of a billing mutation is how they
+// come to disagree.
+const releaseApprovals = async ({ context, read, shopify }) => {
+
+	const shop = sanitizeDomain( context?.shop );
+
+	if( ! shop ) throw refusal( 'shop is required', 400 );
+
+	const record = await read.get({ collection : 'shop', query : { shop } });
+
+	const settings = record?.settings ? decrypt( record.settings ) : null;
+
+	if( ! settings?.accessToken ) throw refusal( 'Store is not installed', 409 );
+
+	const { subscriptions } = await shopify.admin.getActiveAppSubscriptions({
+		adminAccessToken : settings.accessToken,
+		domain : shop
+	});
+
+	for( const subscription of ( subscriptions || [] ) ){
+
+		const data = await shopify.admin.adminFetch({
+			adminAccessToken : settings.accessToken,
+			domain : shop,
+			query : 'mutation appSubscriptionCancel( $id : ID! ) { appSubscriptionCancel( id : $id ) { appSubscription { id status } userErrors { field message } } }',
+			variables : { id : subscription.id }
+		});
+
+		const [ userError ] = data?.appSubscriptionCancel?.userErrors || [];
+
+		// SHOPIFY'S OWN WORDS, not ours. A cancel Shopify refused is a merchant-
+		// actionable fact and 422 is the honest code for it.
+		if( userError ) throw refusal( userError.message, 422 );
+
+	}
+
+	return {
+		message : 'Released ' + ( subscriptions || [] ).length + ' approval(s).',
+		request : { shop },
+		result : { ok : true }
+	};
+
+};
+
+// ── THE METER VERDICT, ASKED ONCE ────────────────────────────────────────────
+//
+// IS THIS STORE'S ORDER BILLING ACTUALLY WORKING? Two signals, and the rule for
+// reading them is the subtle part — subtle enough that drawbridge-sync's
+// approval webhook hand-copied it, said so in its own comment twice, and copied
+// it slightly wrong. One copy now, here, beside the vendor it is about.
+//
+//   A USAGE LINE on the approval is POSITIVE evidence and gets stamped. Its
+//   ABSENCE PROVES NOTHING: measured 2026-09-04, on both 2026-04 and unstable
+//   and against a plan whose meter exists, managed-pricing App-Events meters
+//   never materialize as subscription line items — AppUsagePricing is the
+//   legacy usage-charge model. Reading absence as "unmetered" flagged healthy
+//   stores, so absence is NO VERDICT: the stamp, the Issue, the card and the
+//   meter-missing pager all stay silent.
+//
+//   PARTNER-LEDGER ACCRUAL is the real signal. A CHARGE_USAGE event for this
+//   shop is proof billing works, and its charge id becomes the stamp — it
+//   overrides the line-item probe, which managed pricing keeps blind. A usage
+//   ROW exists per subscription even before anything accrues (measured: a
+//   pre-meter approval shows qty 0), so the row is not the proof; a POSITIVE
+//   usageQuantity is, and the LATEST positive row is the stamp.
+//
+// `undefined` means no verdict this run — never `null`, which is the health
+// check's word for "probed, and nothing is accruing".
+//
+// The boundaries come back with it because each charge row is also a billing
+// BOUNDARY the health check reconciles the books against, and re-reading the
+// ledger to get them would be a second call for data this one already holds.
+const LEDGER_WINDOW_MS = 30 * 24 * 60 * 60 * 1000;
+
+const meterVerdict = async ({ adminAccessToken, ledgerFloor, partner, shop, shopId, shopify }) => {
+
+	const { subscriptions } = await shopify.admin.getActiveAppSubscriptions({ adminAccessToken, domain : shop });
+
+	let metered = subscriptions.find( ( subscription ) => subscription.usageLineItemId )?.usageLineItemId;
+
+	// Off entirely until the provider row carries the Partner credentials.
+	// `ledger` says whether it was consulted at all, because "read it and found
+	// nothing accruing" and "could not read it" are different answers and only
+	// the first is evidence about the store.
+	if( ! ( partner?.partnerToken && partner?.partnerOrgId && partner?.partnerAppId && shopId ) ){
+
+		return { boundaries : [], ledger : false, metered };
+
+	}
+
+	const accruals = await shopify.partner.getUsageChargeEvents({
+		appId : 'gid://shopify/App/' + partner.partnerAppId,
+		first : 10,
+		occurredAtMin : ledgerFloor.toISOString(),
+		organizationId : partner.partnerOrgId,
+		partnerToken : partner.partnerToken,
+		shopId : 'gid://shopify/Shop/' + shopId
+	});
+
+	// Oldest first: each charge row closes the window since the row before it.
+	const boundaries = ( accruals || [] )
+		.filter( ( event ) => event.occurredAt )
+		.sort( ( a, b ) => new Date( a.occurredAt ) - new Date( b.occurredAt ) );
+
+	const accrued = [ ...boundaries ].reverse().find( ( event ) => Number( event.usageQuantity ) > 0 );
+
+	if( accrued ) metered = String( accrued.chargeId || accrued.id );
+
+	return { boundaries, ledger : true, metered };
+
+};
+
+// ── PRODUCT SYNC, the pull half ──────────────────────────────────────────────
+//
+// Everything below served drawbridge-sync's queue/product.js — 443 lines and two
+// BullMQ workers that imported three of this vendor's client modules directly.
+// It was a shadow implementation of the `commerce.product` step this manifest
+// already declared, and the step had no trigger, so the declaration and the
+// thing doing the work had never met.
+
+// A Storefront variant edge as the product row stores it.
+const toVariant = ( edge ) => ({
+	availableForSale : edge.node.availableForSale || false,
+	currency : edge.node.price?.currencyCode || null,
+	id : edge.node.id,
+	image : edge.node.image?.url || null,
+	price : parseFloat( edge.node.price?.amount ) || null,
+	requiresShipping : edge.node.requiresShipping || false,
+	sale : parseFloat( edge.node.compareAtPrice?.amount ) || null,
+	title : edge.node.title !== 'Default Title' ? edge.node.title : null
+});
+
+// REAL PURCHASABILITY, OVERLAID ON THE STOREFRONT'S CLAIM. availableForSale can
+// report true for stock checkout cannot actually fulfil — inventory at a
+// fulfillment-service location that cannot fulfil an online order — so a
+// throwaway cart is probed for Shopify's MERCHANDISE_OUT_OF_STOCK warnings.
+//
+// NEVER THROWS. A failed probe leaves the vendor's own answer standing, which is
+// the honest fallback: the overlay only ever removes availability it can prove
+// is wrong.
+const applyOutOfStock = async ({ domain, shopify, storefrontAccessToken, variants }) => {
+
+	try {
+
+		const outOfStock = new Set( await shopify.storefront.probeVariantsOutOfStock({
+			domain,
+			storefrontAccessToken,
+			variantIds : variants.map( ( variant ) => variant.id )
+		}) );
+
+		return variants.map( ( variant ) => ({
+			...variant,
+			availableForSale : variant.availableForSale && ! outOfStock.has( variant.id )
+		}) );
+
+	} catch ( _ ){
+
+		return variants;
+
+	}
+
+};
+
+// BEST-EFFORT PRODUCT ResourceFeedback — the required-action message on the
+// product page in the Shopify admin, which the sales-channel requirements say is
+// where a channel communicates a product's problems.
+//
+// Feedback must never fail the sync, and a failure must be LOUD. It is reported
+// through the caller's error channel rather than a warning: a warn only reaches
+// Sentry Logs, which is how a feedback path failing on every send since the
+// channel shipped stayed invisible through two rounds of QA.
+// sendProductResourceFeedback answers null rather than throwing for the expected
+// "nothing to attach it to" case, so anything that lands here is a real fault.
+const sendFeedback = async ({ adminToken, connection, messages, productId, shopify, state }) => {
+
+	try {
+
+		await shopify.admin.sendProductResourceFeedback({
+			adminAccessToken : await adminToken(),
+			domain : connection.shop,
+			messages,
+			productId,
+			state
+		});
+
+		return null;
+
+	} catch ( error ){
+
+		return error;
+
+	}
+
+};
+
+// BY PROVIDER IDENTITY WHEN THE DOC ID MISSES. The webhook branch upserts the row
+// and queues this pull in one described answer, so under a concurrent redelivery
+// the id it minted may be the one that LOST the upsert race — the row exists,
+// under the winner's id. The provider id and the shop are stable either way.
+const resolveProduct = async ({ connection, context, read }) => {
+
+	const byId = context?.product ? await read.get({ collection : 'product', query : { id : context.product } }) : null;
+
+	const row = byId || ( context?.providerId && ( context?.shop || connection?.shop )
+		? await read.get({
+			collection : 'product',
+			query : {
+				'provider.id' : context.providerId,
+				'provider.slug' : 'shopify',
+				'source.domain' : context.shop || connection.shop
+			}
+		})
+		: null );
+
+	return row;
+
+};
+
+// THE MESSAGE, and its format is enforced by Shopify rather than chosen: one
+// message, at most 100 characters, leading capital, trailing period, not all
+// caps — a breach fails the whole send.
+//
+// Shopify only carries this for a product STILL published to our channel, so
+// "publish this product" is advice the reader has already followed by the time
+// they can read it. The one state where it renders is a product the channel
+// holds but the Storefront will not return: excluded from the channel's US
+// market. Drafting does not qualify — drafting removes the product from the
+// channel, Shopify refuses the send, and the embedded app's publishing section
+// is that product's surface instead. Both causes stay named, because the
+// merchant reading it cannot tell which applies.
+const UNAVAILABLE_FEEDBACK = 'Drawbridge can\'t display this product. Check it is active and available in the United States.';
+
+// The Storefront's contract for a product it cannot see — not published to the
+// Drawbridge channel, or deleted. True deletions arrive on products/delete.
+const NOT_FOUND = 'Shopify product not found';
+
+const syncProduct = async ({ adminToken, connection, context, read, settings, shopify }) => {
+
+	const row = await resolveProduct({ connection, context, read });
+
+	if( ! row ) return { message : 'No product row to sync.', request : { product : context?.product || null }, skipped : true };
+
+	const domain = connection.shop;
+	const providerId = row.provider?.id;
+	const request = { product : row.id, providerId : providerId || null, shop : domain };
+
+	let product;
+
+	try {
+
+		product = await shopify.storefront.getProduct({
+			domain,
+			productId : providerId,
+			storefrontAccessToken : settings?.storefrontAccessToken
+		});
+
+	} catch ( error ){
+
+		// SOFT STATE, NOT TEARDOWN. The row goes inactive but keeps its campaign
+		// references, its ads are drafted — they cannot sell an invisible product —
+		// and the merchant gets product-page feedback. A later successful sync
+		// reverses all of it except the drafting, which stays for a deliberate
+		// re-enable, matching the disconnect and unpublish cascades.
+		if( error.message !== NOT_FOUND ) throw error;
+
+		const failed = await sendFeedback({
+			adminToken,
+			connection,
+			messages : [ UNAVAILABLE_FEEDBACK ],
+			productId : providerId,
+			shopify,
+			state : 'REQUIRES_ACTION'
+		});
+
+		return {
+			failed : failed ? [ failed.message ] : undefined,
+			message : 'Storefront cannot see this product — deactivated.',
+			request,
+			result : { status : 'inactive' },
+			writes : [
+				{
+					collection : 'product',
+					data : { $set : { status : 'inactive' } },
+					operation : 'update',
+					query : { id : row.id }
+				},
+				{
+					collection : 'advertisement',
+					data : { $set : { status : 'drafted' } },
+					multiple : true,
+					operation : 'update',
+					query : { product : row.id }
+				}
+			]
+		};
+
+	}
+
+	const variants = await applyOutOfStock({
+		domain,
+		shopify,
+		storefrontAccessToken : settings?.storefrontAccessToken,
+		variants : ( product?.variants?.edges || [] ).map( toVariant )
+	});
+
+	// The product is visible to the channel again, so any prior required-action
+	// feedback clears — ResourceFeedback replaces per send.
+	const failed = await sendFeedback({
+		adminToken,
+		connection,
+		messages : [],
+		productId : providerId,
+		shopify,
+		state : 'ACCEPTED'
+	});
+
+	return {
+		// EVERYTHING PAST THE FIRST PAGE, filled in silently. The first page is
+		// written above; a product with thousands of variants becomes N short
+		// sequential jobs rather than one long loop that risks a BullMQ stall.
+		enqueues : [ {
+			data : { operation : 'variants', product : row.id },
+			name : 'sync',
+			options : { jobId : 'product.shopify.variants.' + row.id + '.' + Date.now() },
+			queue : 'product.shopify.variants'
+		} ],
+		failed : failed ? [ failed.message ] : undefined,
+		message : 'Synced ' + ( product.title || 'product' ) + '.',
+		request,
+		result : { status : 'active', variants : variants.length },
+		writes : [ {
+			collection : 'product',
+			data : {
+				$set : {
+					description : product.description || null,
+					image : product.featuredImage?.url || null,
+					// A successful sync PROVES channel visibility, which reverses the
+					// deactivation above. Ads stay drafted.
+					status : 'active',
+					title : product.title || null,
+					type : product.productType || null,
+					url : ( domain && product.handle ) ? 'https://' + domain + '/products/' + product.handle : null,
+					variants
+				}
+			},
+			operation : 'update',
+			query : { id : row.id }
+		} ]
+	};
+
+};
+
+// ONE SHOPIFY PAGE PER RUN, self-chaining on the cursor.
+//
+// The first page (no cursor) $sets the array, clearing anything stale from a
+// prior sync; later pages $push, and Shopify's cursor pagination guarantees no
+// overlap within a session, so no dedup is needed. A restart begins again at
+// page one with $set, so a partial-state window is always recoverable.
+const syncVariants = async ({ connection, context, read, settings, shopify }) => {
+
+	const row = await resolveProduct({ connection, context, read });
+
+	if( ! row ) return { message : 'No product row to paginate.', request : { product : context?.product || null }, skipped : true };
+
+	const cursor = context?.cursor || null;
+	const request = { cursor, product : row.id };
+
+	let page;
+
+	try {
+
+		page = await shopify.storefront.getProductVariantsPage({
+			cursor,
+			domain : connection.shop,
+			productId : row.provider?.id,
+			storefrontAccessToken : settings?.storefrontAccessToken
+		});
+
+	} catch ( error ){
+
+		// Unpublished or deleted mid-pagination, the same contract getProduct
+		// carries. The sync branch's next run owns the feedback; just stop.
+		if( error.message !== NOT_FOUND ) throw error;
+
+		return { message : 'Storefront lost this product mid-pagination — stopping.', request, skipped : true };
+
+	}
+
+	const variants = await applyOutOfStock({
+		domain : connection.shop,
+		shopify,
+		storefrontAccessToken : settings?.storefrontAccessToken,
+		variants : ( page.edges || [] ).map( toVariant )
+	});
+
+	return {
+		...( page.pageInfo?.hasNextPage && { enqueues : [ {
+			data : { cursor : page.pageInfo.endCursor, operation : 'variants', product : row.id },
+			name : 'page',
+			options : { jobId : 'product.shopify.variants.' + row.id + '.' + Date.now() },
+			queue : 'product.shopify.variants'
+		} ] }),
+		message : variants.length + ' variant(s) on this page.',
+		request,
+		result : { hasNextPage : Boolean( page.pageInfo?.hasNextPage ), variants : variants.length },
+		writes : [ {
+			collection : 'product',
+			data : cursor
+				? { $push : { variants : { $each : variants } } }
+				: { $set : { variants } },
+			operation : 'update',
+			query : { id : row.id }
+		} ]
+	};
+
+};
+
+// Shopify — installed from the App Store, never connected with keys.
+var shopify = {
 
 	// THE WORDS ON THE BUTTONS. `listing` was `content.redirect.title`, which put
 	// a BUTTON LABEL inside the copy object next to a url — the title and the
@@ -7825,8 +9064,8 @@ var shopify = {
 			// string; this answers what is missing from it.
 			//
 			// `shopify` is injected for the same reason it is everywhere else — this
-			// package cannot import @drawbridge/shopify, which depends on it.
-			scopes : ( { scope }, { shopify } = {} ) => ({ result : { missing : scope ? shopify.oauth.missingScopes( scope ) : null } }),
+			// client is imported here and defaulted, never wired in by a caller.
+			scopes : ( { scope }, { shopify = client } = {} ) => ({ result : { missing : 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
@@ -7841,18 +9080,74 @@ var shopify = {
 		// for the hooks that are dispatches).
 		commerce : {
 
-			// NOT YET. The Checkout Kit cart path is `api/route/subdomain.js`, six direct
-			// calls into `@drawbridge/shopify/storefront` that write nothing — which is
-			// exactly why it never became a hook: a hook is reached to have its effects
-			// performed, and this one has none to perform. It moves here when the vendor
-			// client moves into the manifest and `subdomain.js` stops importing the
-			// package directly.
-			cart : false,
+			// THE CHECKOUT KIT CART. Six operations that were six direct calls into
+			// the storefront client from api/route/subdomain.js.
+			//
+			// IT WRITES NOTHING, which is exactly why it was the last surface to
+			// become a hook — a hook is usually reached to have its effects performed
+			// and this one has none. That reasoning was wrong: a hook is also the one
+			// place a vendor's client is allowed to be called from, and leaving the
+			// cart out meant a public route importing a vendor SDK directly.
+			//
+			// ONE HOOK, OPERATION IN THE CONTEXT, the same shape `inbound.process`
+			// uses for its topic table. Six slots would be six names in the closed
+			// vocabulary for one question — what does this shopper's cart look like
+			// now — asked six ways.
+			//
+			// A USER ERROR IS A 400 AND THE SHOPPER'S OWN WORDS. Shopify's cart
+			// mutations answer "that variant is sold out" as a userError rather than a
+			// transport failure, and the route it replaced already told the two apart.
+			// runHook carries `status` off a thrown error, so it survives to the
+			// caller; the rest of a thrown error's shape does not.
+			cart : async ( { clientId, clientSecret, context, settings }, { fetcher, shopify = client } = {} ) => {
+
+				const { cartId, lineIds, lines, operation } = context || {};
+				const { domain, storefrontAccessToken } = settings || {};
+
+				// MINTED FROM DRAWBRIDGE'S OWN APP CREDENTIALS rather than the store's
+				// token — the Checkout Kit authenticates as the app. The only operation
+				// here that does not touch the merchant's storefront.
+				if( operation === 'checkout' ){
+
+					const token = await shopify.storefront.createCheckoutToken({ clientId, clientSecret, fetcher });
+
+					return { message : 'Checkout token minted.', result : { token } };
+
+				}
+
+				const storefront = { domain, fetcher, storefrontAccessToken };
+
+				try {
+
+					const cart = await ({
+						create : () => shopify.storefront.cartCreate({ ...storefront, lines }),
+						get : () => shopify.storefront.cartGet({ ...storefront, cartId }),
+						linesAdd : () => shopify.storefront.cartLinesAdd({ ...storefront, cartId, lines }),
+						linesRemove : () => shopify.storefront.cartLinesRemove({ ...storefront, cartId, lineIds }),
+						linesUpdate : () => shopify.storefront.cartLinesUpdate({ ...storefront, cartId, lines })
+					}[ operation ] || ( () => {
+
+						throw Object.assign( new Error( 'Unknown cart operation: ' + operation ), { status : 400 });
+
+					}) )();
+
+					return { message : 'Cart ' + operation + '.', request : { cartId : cartId || null, operation }, result : cart };
+
+				} catch ( error ){
+
+					// The shopper can act on this one; everything else is ours.
+					if( error?.userError ) throw Object.assign( error, { status : 400 });
+
+					throw error;
+
+				}
+
+			},
 
 			// 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 } = {} ) => {
+			code : async ( { connection, context, step }, { adminToken, shopify = client } = {} ) => {
 
 				const discount = step.settings?.discount;
 
@@ -7927,7 +9222,7 @@ var shopify = {
 			// 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 } = {} ) => {
+			customer : async ( { connection, context }, { adminToken, read, shopify = client } = {} ) => {
 
 				const request = { email : context?.email || null, lead : context?.lead || null, shop : connection.shop };
 
@@ -7999,6 +9294,38 @@ var shopify = {
 
 			},
 
+			// HOW MANY ARE LEFT. Read at the moment a campaign's product list is
+			// rendered rather than stored on the product, because stock is the one
+			// product fact that is stale the instant it is written down.
+			//
+			// SUMMED HERE, not by the caller. Shopify answers per variant and every
+			// caller wanted the total; the one that existed summed it inline, and
+			// summing `Object.values()` over the raw map is how a cache wrapper's own
+			// bookkeeping key got counted as a quantity.
+			inventory : async ( { connection, context }, { adminToken, shopify = client } = {} ) => {
+
+				const productId = context?.product;
+
+				const request = { product : productId || null, shop : connection.shop };
+
+				if( ! productId ) return { message : 'No product id — nothing to count.', request, result : { total : null }, skipped : true };
+
+				const adminAccessToken = await adminToken();
+
+				const byVariant = await shopify.admin.getProductInventory({
+					adminAccessToken,
+					domain : connection.shop,
+					productId
+				});
+
+				return {
+					message : 'Inventory read.',
+					request,
+					result : { total : Object.values( byVariant || {} ).reduce( ( sum, quantity ) => sum + quantity, 0 ) }
+				};
+
+			},
+
 			// 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.
@@ -8468,188 +9795,1043 @@ var shopify = {
 				// roll back.
 				const billable = org?.billingProvider === 'shopify' && fee > 0 && ! backfill;
 
-				// THE EFFECTIVE METER HANDLE. The provider row's orderEventHandle
-				// (admin-editable, for the day the plan config's meter changes)
-				// overrides the built-in default; slugified again on read as belt
-				// and braces with the save-side formatter, since a drifted stored
-				// value would mint transactions no meter classifies. Read directly
-				// (not via providerSettings — that module imports this one) and
-				// only for a billable order, which keeps the cost off every
-				// ordinary redemption.
-				const providerRow = billable
-					? await read.get({ collection : 'provider', query : { slug : 'shopify' } })
-					: null;
+				// THE EFFECTIVE METER HANDLE. The provider row's orderEventHandle
+				// (admin-editable, for the day the plan config's meter changes)
+				// overrides the built-in default; slugified again on read as belt
+				// and braces with the save-side formatter, since a drifted stored
+				// value would mint transactions no meter classifies. Read directly
+				// (not via providerSettings — that module imports this one) and
+				// only for a billable order, which keeps the cost off every
+				// ordinary redemption.
+				const providerRow = billable
+					? await read.get({ collection : 'provider', query : { slug : 'shopify' } })
+					: null;
+
+				const { orderEventHandle } = providerRow?.settings ? decrypt( providerRow.settings ) : {};
+
+				const handle = ( typeof orderEventHandle === 'string' && slugify( orderEventHandle ) ) || ORDER_EVENT_HANDLE;
+
+				// A billable order with no shop id is revenue lost SILENTLY — the
+				// gate below just yields no job, the order records normally, and the
+				// connection looks healthy. An Error (not a warn) because this is
+				// money: the order id goes in the MESSAGE, since Sentry matches
+				// titles, and the health check's source self-heal is what makes the
+				// state rare enough to page on.
+				if( billable && ! connection?.source?.id ){
+
+					logger?.error?.( new Error(
+						'shopify.usage.billing.skipped on order ' + orderId + ': '
+						+ Math.round( fee * 100 ) + ' cents not billed — connection '
+						+ connection?.id + ' has no source.id'
+					), {
+						extra : {
+							connectionId : connection?.id,
+							fee,
+							orderDocId,
+							orderId : String( orderId )
+						}
+					});
+
+				}
+
+				const enqueues = ( billable && connection?.source?.id )
+					? [ {
+						data : {
+							// The meter handle travels WITH the job so the sender can
+							// verify it against the transaction prefix and refuse a
+							// drifted pair — idempotency keys are permanent, so a
+							// mistraceable event can never be resent under its own key.
+							handle,
+							idempotencyKey : String( orderId ),
+							orderDocId,
+							orderId : String( orderId ),
+							rate,
+							shopId : connection.source.id,
+							// WHICH VENDOR IS BEING CHARGED, so the sender does not have
+							// to assume. queue/usage.js named the slug itself and
+							// defaults to it for anything already queued when this
+							// shipped — an app-store vendor billing through its own meter
+							// enqueues the same job with its own slug.
+							slug : connection.slug,
+							// 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 : handle + '.' + 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.
+			// A PRODUCT, IN THREE MOVES. Nested by operation rather than by three
+			// slots in the closed vocabulary, the same shape inbound.process uses
+			// for its topic table — they are one subject, and a vendor that syncs
+			// products has to answer all three or none.
+			//
+			//   record     a webhook said a product changed: upsert the row and
+			//              queue the pull
+			//   sync       pull the product from the storefront and write what it
+			//              says, including what it says by NOT answering
+			//   variants   one page of variants, self-chaining
+			//
+			// `sync` and `variants` were 443 lines of drawbridge-sync's
+			// queue/product.js — a shadow implementation of the step this manifest
+			// already declared, importing three of the vendor's client modules from
+			// a worker file.
+			product : async ( { connection, context, settings, workflow }, { adminToken, mintId, read, shopify = client } = {} ) => {
+
+				const operation = context?.operation || 'record';
+
+				if( operation === 'sync' ) return syncProduct({ adminToken, connection, context, read, settings, shopify });
+
+				if( operation === 'variants' ) return syncVariants({ connection, context, read, settings, shopify });
+
+
+				const request = {
+					numericId : context?.id || null,
+					organizationId : workflow?.organization || null,
+					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;
+
+				// THE ROW'S OWN ID WHEN IT ALREADY EXISTS, a fresh one only when it
+				// does not.
+				//
+				// The write below is an upsert whose `id` sits in $setOnInsert, so a
+				// product we have seen before keeps the id it was first given and a
+				// newly minted one is silently discarded. Minting unconditionally
+				// therefore published an id belonging to no row: the enqueue named a
+				// product the worker then had to fall back off, and the step's
+				// response showed QA a value that matched nothing they could look up
+				// — which is exactly how it was reported.
+				//
+				// Reading first costs one indexed lookup on the same key the upsert
+				// matches. A concurrent redelivery can still have both runs miss and
+				// mint, which is why the job carries the PROVIDER identity too and the
+				// worker falls back to provider + shop — stable either way.
+				const query = {
+					'provider.id' : providerId,
+					'provider.slug' : 'shopify',
+					'source.domain' : connection.shop
+				};
+
+				const existing = read?.get ? await read.get({ collection : 'product', query }) : null;
+
+				const mintedProduct = existing?.id ? null : mintId();
+
+				const productId = existing?.id || mintedProduct.id;
+
+				return {
+					enqueues : [ {
+						data : { product : productId, providerId, shop : connection.shop },
+						name : 'workflow',
+						// The numeric id, not the gid: BullMQ refuses a custom id with a
+					// colon in it, and every gid carries two.
+					options : { jobId : 'product.workflow.shopify.' + context.id + '.' + 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 : {
+								...( mintedProduct && { _id : mintedProduct._id }),
+								id : productId,
+								provider : { id : providerId, slug : 'shopify' },
+								'source.id' : connection.id,
+								status : 'active'
+							}
+						},
+						operation : 'update',
+						options : { upsert : true },
+						query
+					} ]
+				};
+
+			}
+
+		},
+		contacts : { remove : false, sync : false },
+
+		// THE EMBEDDED-APP SURFACE. Only a vendor whose merchants arrive from its
+		// own app store has one, and these thirteen slots are the thirteen routes
+		// that used to live in api/route/shopify-embedded.js.
+		//
+		// A HOOK DESCRIBES ITS WRITES and the shell performs them, so none of these
+		// holds a controller — `read` is the controller's read methods and nothing
+		// else. Where one REFUSES it throws with a status, and the route answers
+		// what it said. The helpers they share are above the manifest.
+		install : {
+
+			account : {
+
+				// ESTABLISH THE DURABLE MERCHANT-TO-STORE LINK. The breakout
+				// authenticates the merchant once, top-level, and stashes their user
+				// token in `install.token.save`; App Bridge has already proven shop
+				// control by the time this runs.
+				//
+				// THE STASHED TOKEN IS THE TRUST ANCHOR, not merely any valid user
+				// token: the presented one must BE this shop's one-shot handoff token,
+				// unexpired, and an access or pat record — a refresh or oauth-state
+				// token that happens to resolve to a user must not qualify, which is
+				// the rule a session is held to in drawbridge-api's middleware.
+				link : async ( { context }, { read } = {} ) => {
+
+					const shop = sanitizeDomain( context?.shop );
+					const token = context?.token;
+
+					if( ! shop || ! token ) throw refusal( 'shop and token are required', 400 );
+
+					const now = new Date();
+
+					const record = await read.get({ collection : 'shop', query : { shop } });
+
+					const stashed = record?.linkToken ? decrypt( record.linkToken )?.token : null;
+					const expired = ! record?.linkTokenExpiresAt || new Date( record.linkTokenExpiresAt ) <= now;
+
+					if( ! stashed || expired || stashed !== token ) throw refusal( 'Invalid or expired link token', 401 );
+
+					const granted = await read.get({
+						collection : 'token',
+						query : {
+							revoked : false,
+							tokenHash : hashToken( token ),
+							type : { $in : [ tokenTypes.access, tokenTypes.pat ] }
+						}
+					});
+
+					if( ! granted?.user || ( granted.expiresAt && new Date( granted.expiresAt ) <= now ) ){
+
+						throw refusal( 'Invalid or expired link token', 401 );
+
+					}
+
+					// RE-LINKING TO A DIFFERENT ACCOUNT TEARS THE OLD LINK DOWN. The
+					// store's existing org connections belong to the outgoing user, who
+					// can no longer see or manage them from the embedded app. Left in
+					// place they keep serving that user's campaigns off this store while
+					// the merchant is told they are connected as somebody else. Dependent
+					// cleanup fires from drawbridge-sync's connection change stream, the
+					// single home for that cascade.
+					const switching = Boolean( record?.user ) && record.user !== granted.user;
+
+					const connections = switching
+						? await read.aggregate({
+							collection : 'connection',
+							pipeline : [
+								{ $match : { shop, slug : 'shopify' } },
+								{ $project : { _id : 0, id : 1 } }
+							]
+						})
+						: [];
+
+					return {
+						message : switching ? 'Linked to a different Drawbridge account.' : 'Linked.',
+						request : { shop },
+						result : { connected : true, switched : switching },
+						// ALL OR NONE. A half-done switch is a store linked to the new
+						// account while the old account's connections still serve from it.
+						transaction : true,
+						writes : [
+							...( connections || [] ).map( ( connection ) => ({
+								collection : 'connection',
+								operation : 'delete',
+								query : { id : connection.id }
+							}) ),
+							{
+								collection : 'shop',
+								data : { $set : { linkToken : null, linkTokenExpiresAt : null, user : granted.user } },
+								operation : 'update',
+								query : { shop }
+							}
+						]
+					};
+
+				},
+
+				// DISCONNECT THE ACCOUNT FROM THE STORE. Every org connection goes and
+				// the durable link clears; the offline token and the shop record stay,
+				// because the app is still installed and the merchant may link a
+				// different account next.
+				unlink : async ( { context }, { read } = {} ) => {
+
+					const shop = sanitizeDomain( context?.shop );
+
+					if( ! shop ) throw refusal( 'shop is required', 400 );
+
+					const connections = await read.aggregate({
+						collection : 'connection',
+						pipeline : [
+							{ $match : { shop, slug : 'shopify' } },
+							{ $project : { _id : 0, id : 1 } }
+						]
+					});
+
+					return {
+						message : 'Unlinked ' + ( connections || [] ).length + ' connection(s).',
+						request : { shop },
+						result : { ok : true },
+						transaction : true,
+						writes : [
+							...( connections || [] ).map( ( connection ) => ({
+								collection : 'connection',
+								operation : 'delete',
+								query : { id : connection.id }
+							}) ),
+							{
+								collection : 'shop',
+								data : { $set : { linkToken : null, linkTokenExpiresAt : null, user : null } },
+								operation : 'update',
+								query : { shop }
+							}
+						]
+					};
+
+				}
+
+			},
+
+			organizations : {
+
+				// BIND ONE ORGANIZATION TO THIS STORE. The longest slot here, and every
+				// gate in it came from a line in the route it replaces.
+				add : async ( { context }, { currencies, mintId, read, shopify = client } = {} ) => {
+
+					const organization = context?.organization;
+					const shop = sanitizeDomain( context?.shop );
+
+					if( ! shop ) throw refusal( 'shop is required', 400 );
+					if( ! organization ) throw refusal( 'organization is required', 400 );
+
+					const record = await read.get({ collection : 'shop', query : { shop } });
+
+					if( ! record?.user ) throw refusal( 'Account is not connected for this store', 409 );
+
+					// The linked merchant may only add orgs they own or hold the
+					// connections capability on.
+					const owned = await merchantOrganizations({ read, user : record.user });
+					const org = ( owned || [] ).find( ( entry ) => entry.id === organization );
+
+					if( ! org ) throw refusal( 'No access to this organization', 403 );
+
+					// The dashboard's connection-write gate, applied to the embedded path
+					// too: a locked, suspended, past-due, unpaid or paused org cannot take
+					// a new revenue connection either way in.
+					if( ! CONNECTABLE_STATUSES.includes( org.billingStatus ) ){
+
+						throw refusal( 'This organization can\'t accept connections right now — check its billing status in the dashboard', 403 );
+
+					}
+
+					// ONE STORE PER ORGANIZATION. The write below keys on
+					// { organization, slug }, so without this a second store would
+					// silently re-point the org's existing connection at itself.
+					// Re-adding from the SAME store stays allowed. A connection carrying
+					// no `shop` is a legacy dashboard link and counts as another store.
+					if( org.connection && org.connection.shop !== shop ){
+
+						throw refusal( 'This organization is already connected to another Shopify store', 409 );
+
+					}
+
+					const settings = record?.settings ? decrypt( record.settings ) : null;
+
+					if( ! settings?.accessToken ){
+
+						throw refusal( 'Store is not installed — open the app in the Shopify admin first', 409 );
+
+					}
+
+					const plan = await storePlan({ record, shopify });
+
+					if( plan.unavailable ) throw refusal( 'Couldn\'t verify the store\'s plan — try again shortly', 502 );
+
+					if( ! plan.active ) throw refusal( 'Approve a plan before connecting organizations', 402 );
+
+					// THE STOREFRONT TOKEN IS MINTED ONCE PER STORE. Product sync and
+					// storefront reads need it and token exchange only yields the admin
+					// token. It lives in its own field because a session refresh
+					// overwrites `settings` wholesale. BEST-EFFORT: a miss must not block
+					// the link, and the next add re-mints it.
+					let storefront = null;
+
+					if( ! record.storefront ){
+
+						try {
+
+							const minted = await shopify.oauth.createStorefrontToken({
+								adminAccessToken : settings.accessToken,
+								shop
+							});
+
+							if( minted ) storefront = encrypt({ token : minted });
+
+						} catch ( _ ) {
+
+							// re-minted on a later add
+
+						}
+
+					}
+
+					// LIVE SHOP METADATA. `source.id` is required for App Pricing
+					// commission billing. Best-effort again — a fetch miss links with
+					// whatever the shop record already held.
+					let currency = record?.currency || null;
+					let source = record?.source || null;
+
+					try {
+
+						const shopData = await shopify.oauth.getShop({ adminAccessToken : settings.accessToken, shop });
+
+						if( shopData ){
+
+							currency = String( shopData.currency || '' ).toLowerCase() || null;
+							source = { domain : shopData.myshopifyDomain, id : String( shopData.id ), label : shopData.name };
+
+						}
+
+					} catch ( _ ) {
+
+						// keep what the shop record had
+
+					}
+
+					// A STORE SETTLING OUTSIDE THE BILLING-FX SET would fail the
+					// connection validator INSIDE the transaction below, which surfaces
+					// as an opaque 500. Said plainly here instead. `currencies` is
+					// injected rather than imported: which currencies Drawbridge can bill
+					// is not a fact about Shopify.
+					if( currency && currencies && ! currencies.includes( currency ) ){
+
+						throw refusal( 'This store settles in a currency we can\'t bill yet. Connect a store with a supported settlement currency.', 422 );
+
+					}
+
+					// THE CONNECTION'S ID, KNOWN BEFORE THE WRITE THAT CREATES IT,
+					// because the organization's own refs have to name it inside the same
+					// transaction. An existing connection already has one.
+					const minted = org.connection?.id ? null : mintId();
+					const connectionId = org.connection?.id || minted.id;
+
+					return {
+						message : 'Connected ' + org.name + ' to ' + shop + '.',
+						request : { organization, shop },
+						result : { ok : true },
+						transaction : true,
+						writes : [
+							...( storefront ? [ {
+								collection : 'shop',
+								data : { $set : { storefront } },
+								operation : 'update',
+								query : { shop }
+							} ] : [] ),
+							{
+								collection : 'connection',
+								data : {
+									$set : {
+										currency,
+										errors : [],
+										// The token of record lives on the shared `shop` row; this
+										// is the pointer that satisfies the required `settings`
+										// string, and `auth.install.shared` declares how to read it.
+										settings : encrypt({ ref : 'shop', shop }),
+										shop,
+										status : 'pending',
+										...( source && { source })
+									},
+									$setOnInsert : {
+										...( minted && { _id : minted._id, id : minted.id }),
+										feature : 'organization:connection:shopify',
+										organization,
+										slug : 'shopify'
+									}
+								},
+								operation : 'update',
+								options : { upsert : true },
+								query : { organization, slug : 'shopify' }
+							},
+							{
+								collection : 'organization',
+								data : {
+									// $addToSet UNCONDITIONALLY. The route this replaces only
+									// registered the refs when the upsert INSERTED, which meant an
+									// org whose refs had drifted stayed drifted through every
+									// re-link. Adding a member that is already there is a no-op,
+									// so doing it every time costs nothing and repairs the drift.
+									$addToSet : {
+										'connections.groups' : 'ecommerce',
+										'connections.ids' : connectionId,
+										'connections.keys' : 'shopify'
+									},
+									$set : { billingProvider : 'shopify' }
+								},
+								operation : 'update',
+								query : { id : organization }
+							}
+						]
+					};
+
+				},
+
+				// WHAT THIS STORE CAN SEE: the linked merchant's organizations, the
+				// store's live plan, and the products the merchant has to act on.
+				//
+				// AN ORG CONNECTED TO A DIFFERENT STORE IS OMITTED ENTIRELY, because
+				// `add` would refuse it — a list that offers what the next call rejects
+				// is worse than a shorter one.
+				list : async ( { context }, { conversionRate, planTitle, read, shopify = client } = {} ) => {
+
+					const shop = sanitizeDomain( context?.shop );
+
+					if( ! shop ) throw refusal( 'shop is required', 400 );
+
+					const record = await read.get({ collection : 'shop', query : { shop } });
+
+					if( ! record?.user ){
+
+						return {
+							message : 'No account linked to this store.',
+							request : { shop },
+							result : {
+								account : null,
+								connected : false,
+								organizations : [],
+								plan : { active : false, name : null },
+								unavailableProducts : [],
+								unavailableProductsTotal : 0
+							}
+						};
+
+					}
+
+					const owned = await merchantOrganizations({ read, user : record.user });
+
+					const organizations = ( owned || [] )
+						.filter( ( org ) => ! org.connection || org.connection.shop === shop )
+						.map( ( org ) => ({
+							// The org's OWN billing status decides whether `add` accepts it.
+							// Sent up so the app can disable Connect and name the reason
+							// rather than letting the merchant click into a 403 —
+							// listed-but-blocked beats hidden, because an org vanishing from
+							// the list is indistinguishable from a bug.
+							billingStatus : org.billingStatus || null,
+							connectable : CONNECTABLE_STATUSES.includes( org.billingStatus ),
+							connected : Boolean( org.connection ),
+							conversion : conversionRate( org.subscription ),
+							id : org.id,
+							name : org.name,
+							plan : planTitle( org.subscription ),
+							status : org.connection?.status || null
+						}) );
+
+					// PRODUCTS THE MERCHANT MUST ACT ON, for the app's publishing section
+					// — App Store 5.7.8 and 5.7.11: a sales channel reports its own
+					// publishing problems rather than pushing them to the product page.
+					// `status : 'inactive'` is exactly the set drawbridge-sync deactivated
+					// because the Storefront API could not see them. Scoped to THIS store,
+					// so one shop never sees another org's titles.
+					const connections = ( owned || [] )
+						.filter( ( org ) => org.connection?.shop === shop && org.connection.id )
+						.map( ( org ) => org.connection.id );
+
+					const [ account, plan, unavailable ] = await Promise.all([
+						read.get({ collection : 'user', query : { id : record.user } }),
+						storePlan({ record, shopify }),
+						connections.length
+							? read.aggregate({
+								collection : 'product',
+								pipeline : [
+									{ $match : { connections : { $in : connections }, 'source.domain' : shop, status : 'inactive' } },
+									// $facet so the app can name the first 25 AND report a
+									// truthful total: listing 25 of 40 under "25 products need
+									// attention" would understate the problem.
+									{
+										$facet : {
+											items : [ { $sort : { title : 1 } }, { $limit : 25 }, { $project : { _id : 0, id : 1, title : 1 } } ],
+											total : [ { $count : 'count' } ]
+										}
+									}
+								]
+							})
+							: []
+					]);
+
+					const facet = ( unavailable || [] )[ 0 ] || {};
+
+					// THE STAMP OVERLAYS THE BLIND PROBE. storePlan can only see line
+					// items, which managed pricing never populates — the truth-based
+					// verdict lives on the connections, written from Partner-ledger
+					// accrual by sync. A charge id is proof; an explicit null is billed
+					// orders with nothing accrued, which is what makes the banner render.
+					if( plan.active && plan.metered !== true ){
+
+						const stamped = await read.aggregate({
+							collection : 'connection',
+							pipeline : [
+								{ $match : { shop, slug : 'shopify' } },
+								{ $project : { _id : 0, 'source.metered' : 1 } }
+							]
+						});
+
+						const verdicts = ( stamped || [] ).map( ( row ) => row?.source?.metered );
+
+						if( verdicts.some( ( verdict ) => typeof verdict === 'string' ) ) plan.metered = true;
+						else if( verdicts.some( ( verdict ) => verdict === null ) ) plan.metered = false;
+
+					}
+
+					return {
+						message : organizations.length + ' organization(s) for this store.',
+						request : { shop },
+						result : {
+							account : { email : account?.email || null },
+							connected : true,
+							organizations,
+							plan,
+							unavailableProducts : ( facet.items || [] ).map( ( product ) => ({
+								id : product.id,
+								title : product.title || 'Untitled product'
+							}) ),
+							// The total can exceed the 25 listed above, and has to.
+							unavailableProductsTotal : ( facet.total || [] )[ 0 ]?.count || 0
+						}
+					};
+
+				},
+
+				// DISCONNECT ONE ORGANIZATION. The connection is deleted and nothing
+				// else: every dependent — products, ads, steps, workflows, and the org's
+				// own connection refs — is torn down by drawbridge-sync's connection
+				// change stream. The shared token and the other orgs are untouched.
+				remove : async ( { context }, { read } = {} ) => {
+
+					const organization = context?.organization;
+					const shop = sanitizeDomain( context?.shop );
+
+					if( ! shop ) throw refusal( 'shop is required', 400 );
+					if( ! organization ) throw refusal( 'organization is required', 400 );
+
+					const record = await read.get({ collection : 'shop', query : { shop } });
+
+					if( ! record?.user ) throw refusal( 'Account is not connected for this store', 409 );
+
+					// The same gate as `add`: whoever drives the Shopify admin acts as
+					// the linked account, and removes only orgs that account can manage.
+					const owned = await merchantOrganizations({ read, user : record.user });
+
+					if( ! ( owned || [] ).some( ( entry ) => entry.id === organization ) ){
+
+						throw refusal( 'No access to this organization', 403 );
+
+					}
+
+					const connection = await read.get({
+						collection : 'connection',
+						query : { organization, shop, slug : 'shopify' }
+					});
+
+					if( ! connection ) throw refusal( 'No connection to remove', 404 );
+
+					return {
+						message : 'Disconnected.',
+						request : { organization, shop },
+						result : { ok : true },
+						writes : [ { collection : 'connection', operation : 'delete', query : { id : connection.id } } ]
+					};
+
+				}
+
+			},
+
+			plan : {
+
+				// RELEASE EVERY ACTIVE APPROVAL. The App Home then re-checks the plan
+				// and falls back to "Choose a plan".
+				cancel : ( { context }, { read, shopify = client } = {} ) => releaseApprovals({ context, read, shopify }),
+
+				// ONE ATTRIBUTED ORDER'S USAGE CHARGE. Enqueued per conversion by the
+				// order step and run on a retrying queue, so this may be called
+				// several times for one order — which is safe because the idempotency
+				// key is PERMANENT for billing events and Shopify settles the repeat.
+				//
+				// THE HANDLE IS CHECKED AGAINST THE MANIFEST'S OWN DECLARATION, which
+				// is a real strengthening of what it replaced: drawbridge-sync compared
+				// the job's `handle` against the job's `transaction` — two fields from
+				// the same enqueuer, so a drifted enqueuer agreed with itself. The
+				// handle is the one string that decides whether the event bills at all,
+				// and this is the file that publishes it.
+				//
+				// REFUSE BEFORE SENDING, because sending burns the order's PERMANENT
+				// idempotency key on an event that misclassifies or mistraces. The
+				// throw rides the queue's normal retry path and the abandoned-job alert
+				// pages on exhaustion.
+				//
+				// DELIBERATELY NO TIMESTAMP. sendAppEvent defaults to the SEND time,
+				// which is always inside the merchant's current billing cycle at the
+				// moment of sending and so can never hit PERIOD_CLOSED. Pinning the
+				// purchase time reads more correct and is strictly worse: a retry
+				// backoff crossing a cycle boundary would carry a closed-cycle
+				// timestamp, Shopify would 202-accept, silently drop it, and the
+				// commission would be lost. Send-time's worst case is benign — the
+				// charge lands in the next cycle, but it lands.
+				charge : async ( { clientId, clientSecret, context, manifest }, { shopify = client } = {} ) => {
+
+					const { idempotencyKey, order, orderId, rate, revision, shopId, timestamp, transaction, value } = context || {};
+
+					// THE MANIFEST'S HANDLE, unless an operator overrode it on the
+					// provider row — which is the same precedence the automatic path
+					// mints against, and the recovery migration is the only caller that
+					// can supply one. The GUARD holds either way: whichever handle is
+					// in force, the transaction has to carry it, which is what keeps
+					// the event's classifier and its trace id telling one story.
+					const handle = context?.handle || manifest.auth.install.billing.handle;
+
+					if( ! transaction || ! String( transaction ).startsWith( handle + '.' ) ){
+
+						throw new Error( 'shopify.usage.billing.handle.mismatch on order ' + orderId + ': transaction '
+							+ ( transaction || 'null' ) + ' does not carry handle ' + handle + ' — refusing to send' );
+
+					}
+
+					await shopify.billing.sendAppEvent({
+						clientId,
+						clientSecret,
+						eventHandle : handle,
+						idempotencyKey,
+						// The Shopify-side event record names the order that produced it.
+						reference : transaction,
+						// OPERATOR-ONLY, BOTH OF THEM, and absent on every automatic
+						// send. `revision` suffixes the idempotency key, which is what
+						// makes a second attempt possible once a key has been consumed;
+						// the encoding is owned by sendAppEvent so no caller builds keys
+						// itself. `timestamp` pins the PURCHASE time, which the automatic
+						// path must never do — see the note above — and the recovery
+						// migration must, because it is resending orders from a closed
+						// window and bounds its own run to the merchant's current cycle.
+						...( revision && { revision }),
+						...( timestamp && { timestamp }),
+						shopId,
+						value
+					});
+
+					return {
+						message : 'Usage charge sent for order ' + orderId + '.',
+						request : { order : order || null, orderId : orderId || null, shopId : shopId || null, value },
+						result : { transaction : String( transaction ) },
+						// TRACEABILITY. The App Events API returns no event id, so the
+						// trace key into Shopify's event logs is the transaction id the
+						// commerce.order hook minted and this sent as `reference`.
+						// `amount` is the per-order usage value in cents, mirroring the
+						// Stripe path's marker.
+						...( order && { writes : [ {
+							collection : 'order',
+							data : {
+								$set : {
+									billed : {
+										amount : value,
+										date : new Date(),
+										rate : rate || 0,
+										transaction : String( transaction )
+									}
+								}
+							},
+							operation : 'update',
+							query : { id : order }
+						} ] })
+					};
+
+				},
+
+				// RESELECT, NOT CANCEL. The same mechanics — the current approval has to
+				// be released before the pricing page will offer the plan again — but
+				// the intent is a thirty-second round trip rather than a departure.
+				//
+				// `mark` IS A DECLARED CAPABILITY, and this is the only slot here that
+				// needs one. The marker has to be persisted BEFORE the approval is
+				// released: it is what tells sync's CANCELLED handler to hold the pause
+				// — no connection error, no owner email — and start a timed recheck that
+				// pauses honestly if the merchant abandons. A described write lands
+				// after the hook returns, which is after the cancel, and a marker
+				// written then can race the very webhook it exists to soften. Same
+				// precedent as `resolveContact`: the one write a description cannot
+				// carry.
+				reselect : async ( { context }, { mark, read, shopify = client } = {} ) => {
+
+					const shop = sanitizeDomain( context?.shop );
+
+					if( ! shop ) throw refusal( 'shop is required', 400 );
+
+					await mark({ shop });
+
+					return releaseApprovals({ context, read, shopify });
+
+				},
+
+				// IS THIS STORE'S ORDER BILLING ACTUALLY METERED? Not a merchant
+				// action — the other two slots here are — but the same subject, and
+				// the reason it is a declared hook rather than a helper is that the
+				// answer was being derived in two places: `lifecycle.health` below,
+				// and drawbridge-sync's app_subscriptions/update handler, whose copy
+				// stated in its own comment that it matched this one and did not.
+				//
+				// THREE ANSWERS, and the caller must keep them apart:
+				//
+				//   a string     PROVEN. The charge id or usage line id, stamped on
+				//                the connection as the evidence.
+				//   null         PROBED, and nothing is accruing.
+				//   undefined    NO VERDICT — the probe could not run. `probed` says
+				//                which, because undefined does not survive JSON.
+				verify : async ( { context }, { adminToken, read, shopify = client } = {} ) => {
+
+					const shop = sanitizeDomain( context?.shop );
+
+					if( ! shop ) throw refusal( 'shop is required', 400 );
+
+					const adminAccessToken = await adminToken();
+
+					if( ! adminAccessToken ){
+
+						return { message : 'No admin token for this store — no verdict.', request : { shop }, result : { metered : null, probed : false }, skipped : true };
+
+					}
+
+					const partnerRow = read?.get ? await read.get({ collection : 'provider', query : { slug : 'shopify' } }) : null;
+					const partner = partnerRow?.settings ? decrypt( partnerRow.settings ) : {};
+
+					const { ledger, metered } = await meterVerdict({
+						adminAccessToken,
+						ledgerFloor : new Date( Date.now() - LEDGER_WINDOW_MS ),
+						partner,
+						shop,
+						shopId : context?.shopId || null,
+						shopify
+					});
+
+					return {
+						message : typeof metered === 'string' ? 'Billing is metered.' : 'No meter evidence for this store.',
+						request : { shop },
+						// `probed` is the LEDGER, not the call: a store whose Partner
+						// credentials are absent was not asked, and reporting that as
+						// "probed, nothing accruing" would stamp an unmetered verdict on
+						// a store nobody looked at.
+						result : { metered : metered ?? null, probed : ledger || typeof metered === 'string' }
+					};
+
+				}
+
+			},
+
+			// THE EMBEDDED APP'S SESSION STORE. The @shopify/shopify-app library
+			// persists the offline session on token exchange and refresh; it lives
+			// encrypted on the shared `shop` record, which is the same row every
+			// organization's connection to this store points at.
+			session : {
+
+				// SOFT-CLEAR, NEVER A DELETE. The library calls this on session
+				// invalidation and not only on uninstall, so hard-deleting the record
+				// would orphan every org connection pointing at it — token resolution
+				// silently nulls — and destroy the durable account link and the
+				// storefront token with it. The next embedded load re-runs token
+				// exchange. The full record delete belongs to the uninstall webhook.
+				clear : async ({ context }) => {
+
+					const shop = sanitizeDomain( context?.shop );
+
+					if( ! shop ) throw refusal( 'shop is required', 400 );
+
+					return {
+						message : 'Session cleared.',
+						request : { shop },
+						result : { ok : true },
+						writes : [ {
+							collection : 'shop',
+							data : { $set : { settings : null } },
+							operation : 'update',
+							query : { shop }
+						} ]
+					};
+
+				},
+
+				read : async ( { context }, { read } = {} ) => {
+
+					const shop = sanitizeDomain( context?.shop );
+
+					if( ! shop ) throw refusal( 'shop is required', 400 );
+
+					const record = await read.get({ collection : 'shop', query : { shop } });
+
+					if( ! record?.settings ) throw refusal( 'No session for this store', 404 );
+
+					return {
+						message : 'Session read.',
+						request : { shop },
+						result : { session : decrypt( record.settings ) }
+					};
+
+				},
+
+				save : async ({ context }) => {
+
+					const session = context?.session;
+					const shop = sanitizeDomain( session?.shop );
+
+					if( ! shop || ! session?.accessToken ) throw refusal( 'session.shop and session.accessToken are required', 400 );
+
+					return {
+						message : 'Session saved.',
+						request : { shop },
+						result : { ok : true },
+						writes : [ {
+							collection : 'shop',
+							data : {
+								$set : { settings : encrypt( session ), shop },
+								$setOnInsert : { status : 'pending' }
+							},
+							operation : 'update',
+							options : { upsert : true },
+							query : { shop }
+						} ]
+					};
+
+				}
+
+			},
+
+			// THE LINK-TOKEN HANDOFF. The breakout callback runs top-level and can set
+			// a first-party cookie; the embedded App Home cannot read that cookie from
+			// inside the Shopify admin iframe. So the callback stashes the merchant's
+			// user token here keyed by shop, and App Home reads it once and clears it.
+			//
+			// DURABLE RATHER THAN IN REDIS: a restart must not strand a merchant
+			// mid-handoff. Short-lived and encrypted.
+			token : {
+
+				clear : async ({ context }) => {
+
+					const shop = sanitizeDomain( context?.shop );
 
-				const { orderEventHandle } = providerRow?.settings ? decrypt( providerRow.settings ) : {};
+					if( ! shop ) throw refusal( 'shop is required', 400 );
 
-				const handle = ( typeof orderEventHandle === 'string' && slugify( orderEventHandle ) ) || ORDER_EVENT_HANDLE;
+					return {
+						message : 'Link token cleared.',
+						request : { shop },
+						result : { ok : true },
+						writes : [ {
+							collection : 'shop',
+							data : { $set : { linkToken : null, linkTokenExpiresAt : null } },
+							operation : 'update',
+							query : { shop }
+						} ]
+					};
 
-				// A billable order with no shop id is revenue lost SILENTLY — the
-				// gate below just yields no job, the order records normally, and the
-				// connection looks healthy. An Error (not a warn) because this is
-				// money: the order id goes in the MESSAGE, since Sentry matches
-				// titles, and the health check's source self-heal is what makes the
-				// state rare enough to page on.
-				if( billable && ! connection?.source?.id ){
+				},
 
-					logger?.error?.( new Error(
-						'shopify.usage.billing.skipped on order ' + orderId + ': '
-						+ Math.round( fee * 100 ) + ' cents not billed — connection '
-						+ connection?.id + ' has no source.id'
-					), {
-						extra : {
-							connectionId : connection?.id,
-							fee,
-							orderDocId,
-							orderId : String( orderId )
-						}
-					});
+				read : async ( { context }, { read } = {} ) => {
 
-				}
+					const shop = sanitizeDomain( context?.shop );
 
-				const enqueues = ( billable && connection?.source?.id )
-					? [ {
-						data : {
-							// The meter handle travels WITH the job so the sender can
-							// verify it against the transaction prefix and refuse a
-							// drifted pair — idempotency keys are permanent, so a
-							// mistraceable event can never be resent under its own key.
-							handle,
-							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 : handle + '.' + orderId,
-							value : Math.round( fee * 100 )
-						},
-						name : 'billing',
-						options : { jobId : 'shopify.usage.' + orderId },
-						queue : 'usage'
-					} ]
-					: [];
+					if( ! shop ) throw refusal( 'shop is required', 400 );
 
-				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
-				};
+					const record = await read.get({ collection : 'shop', query : { shop } });
 
-			},
+					const expiresAt = record?.linkTokenExpiresAt ? new Date( record.linkTokenExpiresAt ) : null;
 
-			// 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, read } = {} ) => {
+					// EXPIRY IS CHECKED ON READ, not by a sweep. The token is one-shot
+					// and short-lived, so the read is the only moment anyone cares.
+					if( ! record?.linkToken || ! expiresAt || expiresAt <= new Date() ){
 
-				const request = {
-					numericId : context?.id || null,
-					organizationId : workflow.organization,
-					title : context?.title || null
-				};
+						throw refusal( 'No link token for this store', 404 );
 
-				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 };
+					return {
+						message : 'Link token read.',
+						request : { shop },
+						result : { token : decrypt( record.linkToken )?.token ?? null }
+					};
 
-				const providerId = 'gid://shopify/Product/' + context.id;
+				},
 
-				// THE ROW'S OWN ID WHEN IT ALREADY EXISTS, a fresh one only when it
-				// does not.
-				//
-				// The write below is an upsert whose `id` sits in $setOnInsert, so a
-				// product we have seen before keeps the id it was first given and a
-				// newly minted one is silently discarded. Minting unconditionally
-				// therefore published an id belonging to no row: the enqueue named a
-				// product the worker then had to fall back off, and the step's
-				// response showed QA a value that matched nothing they could look up
-				// — which is exactly how it was reported.
-				//
-				// Reading first costs one indexed lookup on the same key the upsert
-				// matches. A concurrent redelivery can still have both runs miss and
-				// mint, which is why the job carries the PROVIDER identity too and the
-				// worker falls back to provider + shop — stable either way.
-				const query = {
-					'provider.id' : providerId,
-					'provider.slug' : 'shopify',
-					'source.domain' : connection.shop
-				};
+				save : async ({ context }) => {
 
-				const existing = read?.get ? await read.get({ collection : 'product', query }) : null;
+					const shop = sanitizeDomain( context?.shop );
+					const token = context?.token;
 
-				const mintedProduct = existing?.id ? null : mintId();
+					if( ! shop || ! token ) throw refusal( 'shop and token are required', 400 );
 
-				const productId = existing?.id || mintedProduct.id;
+					return {
+						message : 'Link token saved.',
+						request : { shop },
+						result : { ok : true },
+						writes : [ {
+							collection : 'shop',
+							data : {
+								$set : {
+									linkToken : encrypt({ token }),
+									linkTokenExpiresAt : new Date( Date.now() + LINK_TOKEN_TTL_MS )
+								}
+							},
+							operation : 'update',
+							query : { shop }
+						} ]
+					};
 
-				return {
-					enqueues : [ {
-						data : { product : productId, providerId, shop : connection.shop },
-						name : 'workflow',
-						// The numeric id, not the gid: BullMQ refuses a custom id with a
-					// colon in it, and every gid carries two.
-					options : { jobId : 'product.workflow.shopify.' + context.id + '.' + 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 : {
-								...( mintedProduct && { _id : mintedProduct._id }),
-								id : productId,
-								provider : { id : providerId, slug : 'shopify' },
-								'source.id' : connection.id,
-								status : 'active'
-							}
-						},
-						operation : 'update',
-						options : { upsert : true },
-						query
-					} ]
-				};
+				}
 
 			}
 
 		},
-		contacts : { remove : false, sync : false },
-
-		// The embedded-app surface. Only a vendor whose merchants arrive from its
-		// own app store has one.
-		install : false,
 
 		// Drawbridge sends its own notification email and SMS — see the private
 		// `drawbridge` manifest. A vendor answering these would be a second sender,
@@ -8731,7 +10913,7 @@ var shopify = {
 			// 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, logger, read, reconcileScopes, resolveSettings, rotateToken, shopify } = {} ) => {
+			health : async ( { connection, workflow }, { adminToken, logger, read, reconcileScopes, resolveSettings, rotateToken, shopify = client } = {} ) => {
 
 				const request = {
 					connectionId : workflow.connection,
@@ -8833,62 +11015,27 @@ var shopify = {
 
 						}
 
-						const { subscriptions } = await shopify.admin.getActiveAppSubscriptions({
-							adminAccessToken,
-							domain : connection.shop
-						});
-
-						// A usage line on the approval is POSITIVE evidence and gets
-						// stamped. Its ABSENCE proves nothing: measured 2026-09-04
-						// (both 2026-04 and unstable, against a plan whose meter
-						// exists), managed-pricing App-Events meters never
-						// materialize as subscription line items — AppUsagePricing is
-						// the legacy usage-charge model. Reading absence as
-						// "unmetered" flagged healthy stores, so absence is NO
-						// VERDICT: the stamp, the Issue, the card and the
-						// meter-missing pager all stay silent until a signal that can
-						// actually observe the meter exists (Partner API
-						// USAGE_CHARGE_APPLIED accrual events are that signal).
-						const usageLine = subscriptions.find( ( subscription ) => subscription.usageLineItemId )?.usageLineItemId;
-
-						if( usageLine ) metered = usageLine;
-
-						// THE REAL METER SIGNAL — Partner API accrual. A CHARGE_USAGE
-						// event for this shop is proof billing works: its charge id
-						// becomes the stamp (overriding the line-item probe, which
-						// managed pricing keeps blind), and each charge row is a
-						// billing BOUNDARY the reconciler below balances the books
-						// against. Off entirely until the provider row carries the
-						// credentials.
+						// ONE READING OF THE TWO SIGNALS, shared with the approval
+						// webhook in drawbridge-sync, which used to hand-copy it.
 						const partnerRow = read?.get ? await read.get({ collection : 'provider', query : { slug : 'shopify' } }) : null;
 						const partner = partnerRow?.settings ? decrypt( partnerRow.settings ) : {};
 
-						if( partner.partnerToken && partner.partnerOrgId && partner.partnerAppId && source?.id && shopify.partner?.getUsageChargeEvents ){
-
-							const ledgerFloor = new Date( Date.now() - 30 * 24 * 60 * 60 * 1000 );
+						const ledgerFloor = new Date( Date.now() - LEDGER_WINDOW_MS );
 
-							const accruals = await shopify.partner.getUsageChargeEvents({
-								appId : 'gid://shopify/App/' + partner.partnerAppId,
-								first : 10,
-								occurredAtMin : ledgerFloor.toISOString(),
-								organizationId : partner.partnerOrgId,
-								partnerToken : partner.partnerToken,
-								shopId : 'gid://shopify/Shop/' + source.id
-							});
+						const verdict = await meterVerdict({
+							adminAccessToken,
+							ledgerFloor,
+							partner,
+							shop : connection.shop,
+							shopId : source?.id,
+							shopify
+						});
 
-							// Oldest first: each charge row is a boundary that closes
-							// the window since the row before it.
-							const boundaries = accruals
-								.filter( ( event ) => event.occurredAt )
-								.sort( ( a, b ) => new Date( a.occurredAt ) - new Date( b.occurredAt ) );
+						if( verdict.metered !== undefined ) metered = verdict.metered;
 
-							// A usage ROW exists per subscription even before anything
-							// accrues (measured: a pre-meter approval shows qty 0), so
-							// the row is not the proof — a POSITIVE usageQuantity is.
-							// The LATEST positive row is the stamp.
-							const accrued = [ ...boundaries ].reverse().find( ( event ) => Number( event.usageQuantity ) > 0 );
+						const { boundaries } = verdict;
 
-							if( accrued ) metered = String( accrued.chargeId || accrued.id );
+						if( boundaries.length ){
 
 							// THE BOUNDARY RECONCILER. Money truth lives at boundaries:
 							// each charge row states what Shopify actually charged for
@@ -9227,13 +11374,13 @@ var shopify = {
 			// They are the same two questions every other vendor answers through
 			// resources.*, so they answer them the same way now.
 			//
-			// `shopify` is INJECTED: this package cannot import @drawbridge/shopify,
+			// `shopify` DEFAULTS to the client this file imports; nothing injects it,
 			// which depends on it. What arrives is the SDK's pure HTTP namespaces
 			// and nothing else — no controller, no collection access. Resolving the
 			// 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, sort }, { shopify } = {} ) => {
+			products : async ( { cursor, limit = 100, search, settings, sort }, { shopify = client } = {} ) => {
 
 				const products = await shopify.storefront.getProducts({
 					cursor,
@@ -9258,7 +11405,7 @@ var shopify = {
 
 			},
 
-			promotions : async ( { cursor, limit = 100, search, settings }, { shopify } = {} ) => {
+			promotions : async ( { cursor, limit = 100, search, settings }, { shopify = client } = {} ) => {
 
 				const discounts = await shopify.admin.getDiscounts({
 					adminAccessToken : settings?.adminAccessToken,
@@ -9305,7 +11452,7 @@ var shopify = {
 		// Drawbridge posts to a merchant's own endpoint, never through a vendor.
 		webhook : false
 	},
-	icon,
+	icon: icon$1,
 	// A pre-launch integration: it only surfaces once the App Store listing
 	// exists and the app is fully configured. Requiring all four means it can
 	// never render half-configured — and absence of any one excludes the
@@ -9420,6 +11567,13 @@ var shopify = {
 					key : 'Shopify Order Tracking',
 					queue : 'connection',
 					system : true,
+					// THE TRIGGER THE REGISTER JOB HAND-WROTE. It is byte-identical to
+					// the one on every stored workflow, because these documents exist on
+					// prod with thousands of runs behind them and provisioning is
+					// idempotent on (connection, system, title) — a different trigger
+					// here would not be picked up by the existing rows anyway, and a
+					// different TITLE would provision a second workflow for every store.
+					trigger : { event : 'shopify.order.create', type : 'webhook' },
 					type : 'step.commerce.order.record'
 				})
 			},
@@ -9431,6 +11585,15 @@ var shopify = {
 					key : 'Shopify Product Sync',
 					queue : 'connection',
 					system : true,
+					// `shopify.product.update`, NOT `product.insert`. The plan named the
+					// latter, and it is the right long-term answer — a Drawbridge product
+					// row appearing should pull the vendor's copy, rather than
+					// stream/product.js branching on the slug and enqueueing a
+					// vendor-named queue. But a workflow carries ONE trigger, this one is
+					// stored on prod against the webhook, and changing a live workflow's
+					// trigger is a data migration. So the declaration matches what exists
+					// and `product.insert` stays a separate, migration-gated change.
+					trigger : { event : 'shopify.product.update', type : 'webhook' },
 					type : 'step.commerce.product.sync'
 				})
 			}
@@ -9456,26 +11619,37 @@ var shopify = {
 				})
 			},
 
-			// Audit-only. The "Shopify Token Activity" system workflow lists these
-			// for descriptive grouping, but its audit step docs are written manually
-			// at OAuth time — the workflow is never dispatched. Routing is declared
-			// defensively so that if it ever IS dispatched, the job lands on a real
-			// queue and the handler lookup misses cleanly instead of throwing
-			// "Unknown step type".
+			// THE ONE WORKFLOW THAT CARRIES TWO STEPS, and the shape the plan called
+			// the single genuinely new thing in it.
+			//
+			// Every other system step is its own workflow, titled by its own `key`.
+			// These two are "Shopify Token Activity", one row in the merchant's list
+			// with both steps in it — so they declare `workflow`, which names the
+			// title, the trigger and the ORDER, and the provisioner groups on it.
+			// Without that key the pair could only be provisioned by the hand-written
+			// spec in drawbridge-sync's register job, which is exactly why that spec
+			// outlived every other one.
+			//
+			// AUDIT-ONLY. The step documents are written manually at OAuth time and
+			// the workflow is never dispatched; `queue` is declared defensively so
+			// that if it ever IS, the job lands on a real queue and the handler lookup
+			// misses cleanly rather than throwing "Unknown step type".
 			token : {
 				exchange : () => ({
 					description : 'Records the token exchange that completed an install. Audit only — never dispatched.',
 					key : 'Shopify Token Exchange',
 					queue : 'connection',
 					system : true,
-					type : 'step.connection.token.exchange'
+					type : 'step.connection.token.exchange',
+					workflow : { key : 'Shopify Token Activity', order : 0, trigger : { event : 'shopify.token', type : 'event' } }
 				}),
 				refresh : () => ({
 					description : 'Records a token rotation. Audit only — never dispatched.',
 					key : 'Shopify Token Refresh',
 					queue : 'connection',
 					system : true,
-					type : 'step.connection.token.refresh'
+					type : 'step.connection.token.refresh',
+					workflow : { key : 'Shopify Token Activity', order : 1, trigger : { event : 'shopify.token', type : 'event' } }
 				})
 			}
 
@@ -9683,14 +11857,15 @@ var webhook = {
 			'Drawbridge can POST event payloads to your endpoint as activity happens in your account, so your own systems can react to it.',
 			'Generate a signing secret and Drawbridge signs every request with it. Your endpoint recomputes the signature to confirm each payload genuinely came from Drawbridge before acting on it.'
 		],
-		// NO VENDOR-SPECIFIC CONNECT COPY, and that is a decision rather than a gap.
-		// The dashboard already carries generic reasons for every way an
-		// authorization can fail — declined, expired state, a vendor we are not set
-		// up for — and a sentence here is an ADDITION to those, for a vendor whose
-		// failures need saying differently. This one's do not.
+		// THERE IS NO CONSENT SCREEN TO FAIL. Connecting mints a signing secret;
+		// nothing is authorized against a third party, so neither `denied` nor
+		// `invalid` has a state it could describe. The failures this connection
+		// really has are at DELIVERY — a merchant's endpoint refusing a POST — and
+		// those reach them through the connection's own errors rather than through
+		// connect copy.
 		//
-		// Answered rather than omitted, because `errors` existed on two of six
-		// manifests and there was no way to tell "nothing to add" from "nobody
+		// `false` is the recorded decision, not silence: `errors` existed on two of
+		// six manifests and there was no way to tell "nothing to add" from "nobody
 		// wrote it".
 		errors : false,
 		excerpt : 'Sign outgoing webhook payloads with an HMAC secret to verify authenticity.',
@@ -9812,7 +11987,7 @@ var webhook = {
 	// Borrowed: this is the Drawbridge mark, because Webhooks has none of its own.
 	// It is the one card that reads wrong — our logo among vendor logos — and it
 	// wants a mark of its own when there is one.
-	icon: icon$6,
+	icon: icon$7,
 	// EXPLICIT, not derived, because the name is not a vendor's. There is no third
 	// party behind a webhook — connecting MINTS a secret — so this is one of
 	// Drawbridge's own keys, listed in PLATFORM_CREDENTIALS. Without it the signing
@@ -9861,7 +12036,7 @@ var webhook = {
 	// The connect prompt only where connecting is not already the card's whole
 	// story: a disconnected or errored document renders a Connect action itself,
 	// and a task repeating it talks over the button.
-	tasks : ( { settings, status } = {} ) => ( [ 'disconnected', 'error' ].includes( status )
+	tasks : ( { settings, status } = {} ) => ( status === 'error'
 		? []
 		: settings?.secret
 		? [
@@ -9950,7 +12125,7 @@ var attentiveVendor = {
 
 	// The same mark the connection carries. One vendor, one icon — mergeVendors
 	// used to throw when two manifests disagreed about this.
-	icon: icon$7,
+	icon: icon$8,
 
 	name : 'Attentive',
 
@@ -9969,6 +12144,112 @@ var attentiveVendor = {
 
 };
 
+// Bright Data's mark, drawn by hand rather than exported from a brand kit —
+// there was no export to hand. The eight-spoke burst on their blue is the
+// recognisable part; replace with the kit's own mark when one is available.
+//
+// A .js wrapper around otherwise untouched SVG so `node --test` can run against
+// lib/ directly. A bare .svg import would need a bundler loader and force the
+// tests onto dist/, which is a worse trade than one line of wrapper.
+var icon = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xmlns="http://www.w3.org/2000/svg">
+<rect width="500" height="500" fill="#0F58FF"/>
+<circle cx="250" cy="250" r="52" fill="white"/>
+<rect x="234" y="70" width="32" height="96" rx="16" fill="white"/>
+<rect x="234" y="334" width="32" height="96" rx="16" fill="white"/>
+<rect x="70" y="234" width="96" height="32" rx="16" fill="white"/>
+<rect x="334" y="234" width="96" height="32" rx="16" fill="white"/>
+<rect x="117" y="140" width="32" height="96" rx="16" transform="rotate(-45 117 140)" fill="white"/>
+<rect x="304" y="327" width="32" height="96" rx="16" transform="rotate(-45 304 327)" fill="white"/>
+<rect x="360" y="117" width="32" height="96" rx="16" transform="rotate(45 360 117)" fill="white"/>
+<rect x="173" y="304" width="32" height="96" rx="16" transform="rotate(45 173 304)" fill="white"/>
+</svg>`;
+
+// DRAWBRIDGE'S OWN CREDENTIALS FOR BRIGHT DATA — the scrape path's rendering and
+// unblocking, spent on our account and never on a merchant's.
+//
+// A VENDOR WITH NO CONNECTION, and the second one after Stripe. Nobody links a
+// Bright Data account to Drawbridge; scraping is infrastructure that happens to
+// cost money, so there is no manifest, no hooks and nothing merchant-facing. It
+// is here because a vendor is the row in the `provider` collection holding our
+// keys for it — and until vendors became their own files, a vendor with no
+// connection could not hold credentials at all, because the admin screen's
+// vocabulary was derived from the connection registry.
+//
+// WHY IT MOVED OFF ENV, 2026-09-16. The unlocker key had an expiry nobody knew
+// about and Bright Data mailed a three-day warning to one person's inbox. Their
+// API offers no programmatic rotation — the docs are explicit that refreshing is
+// a human in the control panel and that "any request you will send with the old
+// key will fail to authenticate" the moment you do — so renewal is always going
+// to be a paste. The question was only where it gets pasted: three env vars
+// across two DigitalOcean app specs, each needing a redeploy, or one admin
+// screen with a 60-second memo. Darren, 2026-09-16, choosing the latter and an
+// unlimited-expiry key.
+//
+// `credential` NAMES THE ENV VAR EACH FIELD FALLS BACK TO, which is what makes
+// the move safe to ship before the row exists: old deployments keep reading env,
+// and the row takes over the moment it is filled.
+var brightdataVendor = {
+
+	fields : [
+		{
+			credential : 'BRIGHTDATA_BROWSER_URI',
+			input : 'password',
+			key : 'browserUri',
+			// A wss:// endpoint with the account's user and password in its
+			// authority, which is why it is a password field rather than a url one:
+			// the whole string is the credential.
+			label : 'Scraping Browser endpoint',
+			message : 'The wss:// Scraping Browser endpoint, carrying its own credentials. Used to render pages that need a real browser.',
+			redact : true,
+			required : true
+		},
+		{
+			credential : 'BRIGHTDATA_UNLOCKER_API_KEY',
+			input : 'password',
+			key : 'unlockerApiKey',
+			label : 'Web Unlocker API key',
+			// NO EXPIRY FIELD, and that is a decision rather than an omission. Bright
+			// Data offers an `Unlimited` expiry and recommends against it; Drawbridge
+			// takes the unlimited key deliberately, because there is no way to rotate
+			// this programmatically and a date nothing can act on is a date that only
+			// surfaces after it has already broken scraping. If a fixed expiry is ever
+			// taken instead, the field to add is a stored date and a warning ahead of
+			// it — not a rotation, which the vendor cannot support.
+			message : 'Bright Data account settings → API keys. Taken with an unlimited expiry: their API offers no way to rotate a key, so a dated one can only ever break scraping silently.',
+			redact : true,
+			required : true
+		},
+		{
+			credential : 'BRIGHTDATA_UNLOCKER_ZONE',
+			input : 'text',
+			key : 'unlockerZone',
+			label : 'Web Unlocker zone',
+			// Not secret — a zone is a label on the account, and it is shown rather
+			// than redacted so an operator can confirm which one is in use without
+			// clearing the field to read it.
+			message : 'The zone name the Unlocker requests run against.',
+			required : true
+		}
+	],
+
+	icon,
+
+	name : 'Bright Data',
+
+	slug : 'brightdata',
+
+	// WHERE THE FACTS CAME FROM, read 2026-09-16.
+	urls : {
+		api : 'https://docs.brightdata.com/api-reference/authentication',
+		dashboard : 'https://brightdata.com/cp/setting/users',
+		// Bright Data has no scope model — a key carries the account's own access —
+		// so there is nothing to link. `false` is the recorded answer rather than a
+		// missing key.
+		scopes : false
+	}
+
+};
+
 // DRAWBRIDGE'S OWN CREDENTIALS FOR HUBSPOT, and where the facts about it came
 // from. One file per vendor, because a vendor is NOT a connection: it is the row
 // in the `provider` collection holding our keys for it, and a connection names
@@ -9999,7 +12280,7 @@ var hubspotVendor = {
 
 	// The vendor's own mark rather than the connection's: drawbridge fronts three
 	// vendors and none of them is Drawbridge.
-	icon: icon$5,
+	icon: icon$6,
 
 	name : 'HubSpot',
 
@@ -10056,7 +12337,7 @@ var klaviyoVendor = {
 
 	// The same mark the connection carries. One vendor, one icon — mergeVendors
 	// used to throw when two manifests disagreed about this.
-	icon: icon$2,
+	icon: icon$3,
 
 	name : 'Klaviyo',
 
@@ -10113,7 +12394,7 @@ var mailchimpVendor = {
 
 	// The same mark the connection carries. One vendor, one icon — mergeVendors
 	// used to throw when two manifests disagreed about this.
-	icon: icon$1,
+	icon: icon$2,
 
 	name : 'Mailchimp',
 
@@ -10184,7 +12465,7 @@ var sendgridVendor = {
 
 	// The vendor's own mark rather than the connection's: drawbridge fronts three
 	// vendors and none of them is Drawbridge.
-	icon: icon$4,
+	icon: icon$5,
 
 	name : 'SendGrid',
 
@@ -10291,7 +12572,7 @@ var shopifyVendor = {
 
 	// The same mark the connection carries. One vendor, one icon — mergeVendors
 	// used to throw when two manifests disagreed about this.
-	icon,
+	icon: icon$1,
 
 	name : 'Shopify',
 
@@ -10357,7 +12638,7 @@ var twilioVendor = {
 
 	// The vendor's own mark rather than the connection's: drawbridge fronts three
 	// vendors and none of them is Drawbridge.
-	icon: icon$3,
+	icon: icon$4,
 
 	name : 'Twilio',
 
@@ -10537,7 +12818,7 @@ const checkIcon = ( owner, icon ) => {
 // its icon, declaring one of its fields two ways, or claiming the same credential.
 // None of those can happen when a vendor is declared once, so all of it is gone.
 const vendors = Object.freeze( Object.fromEntries(
-	[ attentiveVendor, hubspotVendor, klaviyoVendor, mailchimpVendor, sendgridVendor, shopifyVendor, twilioVendor ]
+	[ attentiveVendor, brightdataVendor, hubspotVendor, klaviyoVendor, mailchimpVendor, sendgridVendor, shopifyVendor, twilioVendor ]
 		.map( ( vendor ) => [ vendor.slug, vendor ] )
 ) );
 
@@ -11420,17 +13701,42 @@ const build = ( manifest ) => {
 
 		}
 
-		if( declared.trigger ){
+		// A WORKFLOW GROUPING several steps into one row. Its trigger is checked
+		// against the same table as a step's own, because a typo here is the same
+		// silent failure: the workflow saves, reads active, and matches nothing.
+		if( declared.workflow ){
+
+			if( ! declared.workflow.key ){
+
+				throw new Error( manifest.slug + ' step ' + type + ' declares a workflow with no key — the title several steps share' );
+
+			}
+
+			if( typeof declared.workflow.order !== 'number' ){
+
+				throw new Error( manifest.slug + ' step ' + type + ' declares a workflow with no order — two steps in one row need a sequence' );
+
+			}
+
+			if( declared.trigger ){
+
+				throw new Error( manifest.slug + ' step ' + type + ' declares BOTH a trigger and a workflow — the workflow carries the trigger for every step in it' );
+
+			}
+
+		}
+
+		for( const candidate of [ declared.trigger, declared.workflow?.trigger ].filter( Boolean ) ){
 
 			const known = TRIGGERS[
-				Object.keys( TRIGGERS ).find( ( key ) => TRIGGERS[ key ].event === declared.trigger.event && TRIGGERS[ key ].type === declared.trigger.type )
+				Object.keys( TRIGGERS ).find( ( key ) => TRIGGERS[ key ].event === candidate.event && TRIGGERS[ key ].type === candidate.type )
 			];
 
 			if( ! known ){
 
 				throw new Error(
-					manifest.slug + ' step ' + type + ' declares trigger { event : ' + declared.trigger.event
-					+ ', type : ' + declared.trigger.type + ' }, which nothing dispatches'
+					manifest.slug + ' step ' + type + ' declares trigger { event : ' + candidate.event
+					+ ', type : ' + candidate.type + ' }, which nothing dispatches'
 				);
 
 			}
@@ -11582,6 +13888,16 @@ const connectionSteps = ( env = {} ) => Object.entries( availableConnections( en
 
 // Which vendors implement a given hook. The uniform surface makes this total —
 // every vendor appears in exactly one of the two lists, never neither.
+// DOES THIS VENDOR IMPLEMENT THIS HOOK? The same walk `hookSupport` and
+// `build()` use, exported because callers outside this package were asking it by
+// naming a slug — drawbridge-sync dispatched the post-connect register job on
+// `slug === 'shopify'`, with a comment explaining that no other vendor has one,
+// which is this function's answer written out by hand.
+//
+// TAKES THE HOOKS, not the manifest, so a caller holding a built manifest and a
+// caller holding a fixture ask the same way.
+const implementsHook = ( hooks, name ) => implemented( hooks, name );
+
 const hookSupport = ( name ) => ({
 	no : Object.keys( connections ).filter( ( slug ) => ! implemented( connections[ slug ].hooks, name ) ),
 	yes : Object.keys( connections ).filter( ( slug ) => implemented( connections[ slug ].hooks, name ) )
@@ -11925,4 +14241,4 @@ const resolveConnection = ( item, data, env = {} ) => {
 
 };
 
-export { tokenSettings as $, ANSWER_KEYS as A, hookSupport as B, isStale as C, isStatus as D, ERROR_SOURCES as E, mergeSettings as F, GROUPS as G, HOOKS as H, INPUTS as I, projectConnection as J, publicConnectionKeys as K, publicSettingsBySlug as L, redactSettings as M, resolveConnection as N, OAUTH_ENDPOINTS as O, PLATFORM_CREDENTIALS as P, runHook as Q, RETIRED as R, STATUSES as S, TRIGGERS as T, scopesMessage as U, stepLabels as V, WRITE_OPERATIONS as W, stepQueues as X, stepRoutes as Y, surviving as Z, systemSteps as _, AUTH_KINDS as a, vendors as a0, AUTH_TYPES as b, HOOK_CONFIG as c, HOOK_EFFECTS as d, HOOK_NAMES as e, HOOK_OPTIONS as f, HOOK_PROPS as g, HOOK_SLOT_PROPS as h, OAUTH_FIELDS as i, OUTCOMES as j, STEPS as k, STEP_TYPES as l, TRIGGER_TYPES as m, accessToken as n, answerOf as o, assess as p, availableConnections as q, build as r, buildVendor as s, catalogConnections as t, channels as u, connectFields as v, connectionSteps as w, connections as x, effectsOf as y, ensureSystemWorkflows as z };
+export { scopesMessage as $, ANSWER_KEYS as A, ensureSystemWorkflows as B, hookSupport as C, implementsHook as D, ERROR_SOURCES as E, isStale as F, GROUPS as G, HOOKS as H, INPUTS as I, isStatus as J, mergeSettings as K, perform as L, MARKERS as M, projectConnection as N, OAUTH_ENDPOINTS as O, PLATFORM_CREDENTIALS as P, publicConnectionKeys as Q, RETIRED as R, STATUSES as S, TRIGGERS as T, publicSettingsBySlug as U, reconcileConnectionScopes as V, WRITE_OPERATIONS as W, redactSettings as X, reference as Y, resolveConnection as Z, runHook as _, AUTH_KINDS as a, spliced as a0, stepLabels as a1, stepQueues as a2, stepRoutes as a3, surviving as a4, systemSteps as a5, systemWorkflows as a6, tokenSettings as a7, vendors as a8, AUTH_TYPES as b, HOOK_CONFIG as c, HOOK_EFFECTS as d, HOOK_NAMES as e, HOOK_OPTIONS as f, HOOK_PROPS as g, HOOK_SLOT_PROPS as h, OAUTH_FIELDS as i, OUTCOMES as j, STEPS as k, STEP_TYPES as l, TRIGGER_TYPES as m, accessToken as n, answerOf as o, assess as p, availableConnections as q, build as r, buildVendor as s, catalogConnections as t, channels as u, connectFields as v, connectionSettings as w, connectionSteps as x, connections as y, effectsOf as z };