@porulle/core 0.57.1 → 0.59.0

package/dist/modules/inventory/service.js

@@ -291,6 +291,103 @@ export class InventoryService {
             ...(input.variantId !== undefined ? { variantId: input.variantId } : {}),
         }, actor, ctx);
     }
+    /**
+     * `setAbsolute` for a whole page of levels, set-based — the inventory sync's write.
+     *
+     * setAbsolute per level is a permission check, a row lock, a clamped write, a movement row and an
+     * `inventory.afterAdjust` each: a 27k-variant store synced at ~20 levels per Workflow step and
+     * every changed variant re-marked its product. This keeps the same invariants in a CONSTANT
+     * number of statements per call:
+     *  - `inventory:adjust` is asserted once for the page (refused → nothing is written);
+     *  - the default warehouse (`pickWarehouse`) and the actor's org, once;
+     *  - an unchanged level writes nothing and is not announced; a missing level is created;
+     *  - quantities clamp at 0 (as `GREATEST(0, …)` does) and `version` is bumped;
+     *  - one `adjustment` movement per changed level, carrying its delta.
+     * It announces the page ONCE through `inventory.afterAdjustMany`, grouped by product — NOT
+     * `inventory.afterAdjust` per level. Core's audit and webhook subscribers handle the bulk hook,
+     * so every change is still audited and delivered; a plugin that subscribes to `afterAdjust` must
+     * also subscribe to `afterAdjustMany` (the kernel refuses to boot otherwise).
+     */
+    async setAbsoluteMany(rows, actor, ctx, options = {}) {
+        try {
+            assertPermission(actor ?? null, "inventory:adjust");
+        }
+        catch (error) {
+            return Err(toCommerceError(error));
+        }
+        const orgId = resolveOrgIdForCommerce(actor ?? ctx?.actor ?? null, this.deps.config);
+        if (rows.length === 0)
+            return Ok({ organizationId: orgId, entities: [] });
+        const warehouseId = await this.pickWarehouse(actor, ctx);
+        const reason = options.reason ?? "External store absolute inventory sync";
+        const performedBy = actor?.userId ?? "system";
+        const keyOf = (entityId, variantId) => `${entityId}\u0000${variantId ?? ""}`;
+        const write = async (txCtx) => {
+            const entityIds = [...new Set(rows.map((row) => row.entityId))];
+            const existing = new Map((await this.repo.findLevelsForUpdate(orgId, warehouseId, entityIds, txCtx))
+                .map((level) => [keyOf(level.entityId, level.variantId), level]));
+            const updates = [];
+            const inserts = [];
+            const seen = new Set();
+            for (const row of rows) {
+                const key = keyOf(row.entityId, row.variantId ?? null);
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                const quantity = Math.max(0, row.quantity);
+                const level = existing.get(key);
+                if (level === undefined) {
+                    inserts.push({
+                        organizationId: orgId, entityId: row.entityId, warehouseId, quantityOnHand: quantity,
+                        quantityReserved: 0, quantityIncoming: 0, ...(row.variantId !== undefined ? { variantId: row.variantId } : {}),
+                    });
+                }
+                else if (level.quantityOnHand !== quantity) {
+                    updates.push({ id: level.id, quantity, before: level.quantityOnHand });
+                }
+            }
+            if (updates.length === 0 && inserts.length === 0)
+                return { organizationId: orgId, entities: [] };
+            const beforeById = new Map(updates.map((update) => [update.id, update.before]));
+            const updated = await this.repo.setLevelQuantities(orgId, updates, txCtx);
+            const created = await this.repo.createLevels(inserts, txCtx);
+            const changed = [...updated, ...created];
+            await this.repo.createMovements(changed.map((level) => ({
+                organizationId: orgId,
+                entityId: level.entityId,
+                warehouseId,
+                type: "adjustment",
+                quantity: level.quantityOnHand - (beforeById.get(level.id) ?? 0),
+                reason,
+                performedBy,
+                ...(level.variantId !== null ? { variantId: level.variantId } : {}),
+            })), txCtx);
+            const byEntity = new Map();
+            for (const level of changed)
+                byEntity.set(level.entityId, [...(byEntity.get(level.entityId) ?? []), level]);
+            const result = {
+                organizationId: orgId,
+                entities: [...byEntity].map(([entityId, levels]) => ({ entityId, levels })),
+            };
+            const hookCtx = createHookContext({
+                actor: actor ?? null,
+                tx: txCtx.tx,
+                logger: createLogger("inventory.adjustMany"),
+                services: this.deps.services,
+                context: { moduleName: "inventory" },
+                database: { db: this.deps.database.db },
+                commerceConfig: this.deps.config,
+            });
+            await runAfterHooks(this.deps.hooks.resolve("inventory.afterAdjustMany"), null, result, "update", hookCtx, (hook) => this.deps.hooks.runsInTransaction(hook));
+            return result;
+        };
+        try {
+            return Ok(await this.withTransaction(ctx, async (tx) => write(ctx?.tx ? ctx : createTxContext(tx, { actor: actor ?? null }))));
+        }
+        catch (error) {
+            return Err(toCommerceError(error));
+        }
+    }
     /**
      * Deduct inventory on fulfillment (system-level, no permission check).
      *

package/dist/modules/webhooks/hook.d.ts

@@ -1,4 +1,5 @@
 import type { AfterHook } from "../../kernel/hooks/types.js";
+import type { InventoryAdjustManyResult } from "../inventory/service.js";
 /**
  * Webhook delivery hook — enqueues delivery jobs instead of blocking.
  *
@@ -10,4 +11,10 @@ import type { AfterHook } from "../../kernel/hooks/types.js";
  * asynchronously with retries. The HTTP response returns immediately.
  */
 export declare const deliverWebhooks: AfterHook<unknown>;
+/**
+ * `inventory.afterAdjustMany` — a page of changed levels. Subscribers get exactly what
+ * `inventory.afterAdjust` gave them: one `inventory.update` event per changed level, per endpoint.
+ * Only the endpoint lookup is shared across the page.
+ */
+export declare const deliverWebhooksForAdjustMany: AfterHook<InventoryAdjustManyResult>;
 //# sourceMappingURL=hook.d.ts.map

package/dist/modules/webhooks/hook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hook.d.ts","sourceRoot":"","sources":["../../../src/modules/webhooks/hook.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAE7D;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,CAAC,OAAO,CA2B9C,CAAC"}
+{"version":3,"file":"hook.d.ts","sourceRoot":"","sources":["../../../src/modules/webhooks/hook.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AAEzE;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,CAAC,OAAO,CA2B9C,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,EAAE,SAAS,CAAC,yBAAyB,CAyB7E,CAAC"}

package/dist/modules/webhooks/hook.js

@@ -33,3 +33,34 @@ export const deliverWebhooks = async ({ result, operation, context }) => {
         });
     }
 };
+/**
+ * `inventory.afterAdjustMany` — a page of changed levels. Subscribers get exactly what
+ * `inventory.afterAdjust` gave them: one `inventory.update` event per changed level, per endpoint.
+ * Only the endpoint lookup is shared across the page.
+ */
+export const deliverWebhooksForAdjustMany = async ({ result, operation, context }) => {
+    const eventName = `${String(context.context.moduleName ?? "unknown")}.${operation}`;
+    const webhooksService = context.services.webhooks;
+    const orgId = resolveOrgIdForCommerce(context.actor, context.commerceConfig);
+    const levels = result.entities.flatMap((entity) => entity.levels);
+    if (levels.length === 0)
+        return;
+    const endpoints = await webhooksService.getEndpointsForEvent(eventName, orgId);
+    if (!endpoints.ok)
+        return;
+    for (const endpoint of endpoints.value) {
+        for (const level of levels) {
+            await context.jobs.enqueue("webhooks/deliver", {
+                endpointId: endpoint.id,
+                endpointUrl: endpoint.url,
+                endpointSecret: endpoint.secret,
+                eventName,
+                payload: level,
+            }, {
+                organizationId: orgId,
+                maxAttempts: 5,
+                queue: "webhooks",
+            });
+        }
+    }
+};

package/dist/runtime/kernel-register-hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kernel-register-hooks.d.ts","sourceRoot":"","sources":["../../src/runtime/kernel-register-hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,YAAY,EAAoB,MAAM,6BAA6B,CAAC;AAK7E,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,cAAc,EACtB,KAAK,EAAE,YAAY,GAClB,IAAI,CAmDN"}
+{"version":3,"file":"kernel-register-hooks.d.ts","sourceRoot":"","sources":["../../src/runtime/kernel-register-hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,YAAY,EAAoB,MAAM,6BAA6B,CAAC;AAM7E,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,cAAc,EACtB,KAAK,EAAE,YAAY,GAClB,IAAI,CAwDN"}

package/dist/runtime/kernel-register-hooks.js

@@ -1,6 +1,7 @@
-import { deliverWebhooks } from "../modules/webhooks/hook.js";
+import { deliverWebhooks, deliverWebhooksForAdjustMany } from "../modules/webhooks/hook.js";
 import { syncToSearchIndex } from "../modules/search/hooks.js";
 import { auditHooks } from "../modules/audit/hooks.js";
+import { assertBulkHookPairs } from "../kernel/hooks/bulk-pairs.js";
 export function registerConfiguredKernelHooks(config, hooks) {
     for (const [entityType, entityConfig] of Object.entries(config.entities ?? {})) {
         const entityHooks = entityConfig.hooks ?? {};
@@ -17,6 +18,7 @@ export function registerConfiguredKernelHooks(config, hooks) {
         const hooksObject = moduleConfig?.hooks;
         if (!hooksObject)
             continue;
+        assertBulkHookPairs(Object.entries(hooksObject).filter(([, handlers]) => Array.isArray(handlers) && handlers.length > 0).map(([hookName]) => `${moduleName}.${hookName}`), `config.${moduleName}.hooks`);
         for (const [hookName, handlers] of Object.entries(hooksObject)) {
             const normalizedHandlers = (Array.isArray(handlers) ? handlers : []);
             hooks.registerConfigHooks(`${moduleName}.${hookName}`, normalizedHandlers);
@@ -28,6 +30,7 @@ export function registerConfiguredKernelHooks(config, hooks) {
     hooks.append("catalog.afterUpdate", deliverWebhooks);
     hooks.append("catalog.afterDelete", deliverWebhooks);
     hooks.append("inventory.afterAdjust", deliverWebhooks);
+    hooks.append("inventory.afterAdjustMany", deliverWebhooksForAdjustMany);
     hooks.append("customers.afterCreate", deliverWebhooks);
     hooks.append("customers.afterUpdate", deliverWebhooks);
     hooks.append("pricing.afterCreate", deliverWebhooks);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porulle/core",
-  "version": "0.57.1",
+  "version": "0.59.0",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -62,8 +62,8 @@
     "eslint": "^9.39.1",
     "typescript": "5.9.2",
     "vitest": "^3.2.4",
-    "@porulle/typescript-config": "0.1.0",
-    "@porulle/eslint-config": "0.1.0"
+    "@porulle/eslint-config": "0.1.0",
+    "@porulle/typescript-config": "0.1.0"
   },
   "publishConfig": {
     "access": "public"

package/src/auth/auth-failure.ts

@@ -11,8 +11,13 @@
  * better-call's `APIError` carries `name === "APIError"` and a numeric
  * `statusCode`; its `status` is a string such as `"UNAUTHORIZED"`.
  */
-export function isCredentialRejection(err: unknown): boolean {
+export function isCredentialRejection(err: unknown): err is { name: "APIError"; statusCode: number } {
   if (typeof err !== "object" || err === null) return false;
   const { name, statusCode } = err as { name?: unknown; statusCode?: unknown };
   return name === "APIError" && typeof statusCode === "number";
 }
+
+/** The HTTP status better-auth attached to a credential rejection, or null for anything else. */
+export function credentialRejectionStatus(err: unknown): number | null {
+  return isCredentialRejection(err) ? err.statusCode : null;
+}

package/src/auth/middleware.ts

@@ -4,7 +4,7 @@ import type { Actor } from "./types.js";
 import type { AuthInstance } from "./setup.js";
 import { getCustomerPermissions, resolveActor } from "./actor.js";
 import { DEFAULT_ORG_ID } from "./org.js";
-import { isCredentialRejection } from "./auth-failure.js";
+import { credentialRejectionStatus, isCredentialRejection } from "./auth-failure.js";
 import { isStrictOrgResolution } from "./strict-org-resolution.js";
 import { isIdentityFreeRoute } from "./identity-free-routes.js";
 
@@ -208,15 +208,30 @@ export function authMiddleware(
           return;
         }
       } catch (err) {
-        // An invalid, expired, or rate-limited key is a rejection: fall through
-        // to anonymous. Anything else means the key was never checked.
+        // A rejection better-auth raised was an evaluated credential; anything else means the key
+        // was never checked, and is a fault. A rate-limited key is not a bad one: say so.
         if (!isCredentialRejection(err)) {
           reportAuthCheckFault(err, "api_key");
           throw err;
         }
+        if (credentialRejectionStatus(err) === 429) {
+          return c.json({ error: { code: "RATE_LIMITED", message: "Too many requests for this credential." } }, 429);
+        }
       }
     }
 
+    // A credential the caller PRESENTED and that did not verify is refused, not served as a guest.
+    // Falling through to anonymous gave a shopper whose token had expired a fresh guest cart in
+    // place of theirs, and told a broken client nothing. Absent credentials stay anonymous (guest
+    // checkout depends on it), and a stale session COOKIE is not "presented": browsers carry one on
+    // every public page, and refusing it would 401 logged-out browsing.
+    const presented = (c.req.header("x-api-key") ?? "").trim() !== "" || (c.req.header("authorization") ?? "").trim() !== "";
+    if (presented) {
+      const refused = c.json({ error: { code: "UNAUTHORIZED", message: "The presented credential could not be verified." } }, 401);
+      applyAuthenticateChallenge(refused);
+      return refused;
+    }
+
     if (!c.get("actor")) {
       // For anonymous requests in multi-store deployments, resolve the
       // store so catalog/search queries return the right store's data.

package/src/config/types.ts

@@ -380,6 +380,8 @@ export interface OrdersConfig {
 export interface InventoryConfig {
   hooks?: {
     afterAdjust?: AfterHook<unknown>[];
+    /** One page of changed levels grouped by product (`inventory.setAbsoluteMany`). Required alongside `afterAdjust`. */
+    afterAdjustMany?: AfterHook<unknown>[];
   };
 }
 

package/src/index.ts

@@ -228,6 +228,9 @@ export type {
   ImportRowFailureCode,
 } from "./modules/catalog/import-service.js";
 export { writeEntityLinks, removeEntityLinks, linkFieldPaths } from "./modules/catalog/entity-links.js";
+/** The `inventory.afterAdjustMany` payload: a page's changed levels, grouped by product. */
+export type { InventoryAdjustManyResult } from "./modules/inventory/service.js";
+export type { InventoryLevel } from "./modules/inventory/repository/index.js";
 export type { EntityLinkRemovals, EntityLinkRows, EntityMediaRole, WrittenEntityLinks } from "./modules/catalog/entity-links.js";
 export type {
   TxContext,

package/src/kernel/hooks/bulk-pairs.ts

@@ -0,0 +1,23 @@
+/**
+ * Hooks with a bulk sibling. An operation that writes a whole page at once announces ONLY the bulk
+ * hook — `inventory.setAbsoluteMany` fires `inventory.afterAdjustMany` once per page, not
+ * `inventory.afterAdjust` per level — so a subscriber to the single hook alone would go silently
+ * blind to every bulk write. Registering the single without the bulk is refused at boot, loudly,
+ * naming who did it: a boot failure is found by the first test or dev run, a missing event never is.
+ */
+export const BULK_HOOK_PAIRS: Readonly<Record<string, string>> = {
+  "inventory.afterAdjust": "inventory.afterAdjustMany",
+};
+
+export function assertBulkHookPairs(keys: Iterable<string>, registeredBy: string): void {
+  const registered = new Set(keys);
+  for (const [single, bulk] of Object.entries(BULK_HOOK_PAIRS)) {
+    if (registered.has(single) && !registered.has(bulk)) {
+      throw new Error(
+        `${registeredBy} subscribes to "${single}" but not to "${bulk}". Bulk writes (e.g. a store's `
+        + `inventory sync through setAbsoluteMany) announce only "${bulk}", once per page grouped by `
+        + `product — subscribe to it too, or this subscriber never sees them.`,
+      );
+    }
+  }
+}

package/src/kernel/plugin/manifest.ts

@@ -1,3 +1,4 @@
+import { assertBulkHookPairs } from "../hooks/bulk-pairs.js";
 import type { Hono } from "hono";
 import { markHookInTransaction } from "../hooks/registry.js";
 import type { OpenAPIHono, RouteConfig } from "@hono/zod-openapi";
@@ -300,6 +301,7 @@ export function defineCommercePlugin(
     // 2. Hooks — merge into flat hooks map (kernel registers at boot)
     if (manifest.hooks) {
       const registrations = manifest.hooks();
+      assertBulkHookPairs(registrations.map((reg) => reg.key), `Plugin "${manifest.id}"`);
       const hookMap: Record<string, Array<(...args: unknown[]) => unknown>> = {
         ...(result.hooks ?? {}),
       };

package/src/modules/audit/hooks.ts

@@ -2,6 +2,7 @@ import type { AfterHook } from "../../kernel/hooks/types.js";
 import type { HookHandler } from "../../kernel/hooks/registry.js";
 import type { AuditService } from "./service.js";
 import type { ImportProductsReport } from "../catalog/import-service.js";
+import type { InventoryAdjustManyResult } from "../inventory/service.js";
 
 /**
  * Creates an after-hook that records an audit entry for the operation.
@@ -69,6 +70,21 @@ const catalogImportAuditHook: AfterHook<ImportProductsReport> = async ({ result,
   });
 };
 
+/**
+ * `inventory.afterAdjustMany` — one page of absolute levels. Each changed level is still its own
+ * audit entry (as `inventory.afterAdjust` records one per adjust), written in ONE insert.
+ */
+const inventoryAdjustManyAuditHook: AfterHook<InventoryAdjustManyResult> = async ({ result, context }) => {
+  const audit = context.services.audit as AuditService | undefined;
+  if (!audit?.recordMany) return;
+  await audit.recordMany(result.entities.flatMap((entity) => entity.levels.map((level) => ({
+    entityType: "inventory",
+    entityId: level.id,
+    event: "adjusted",
+    payload: safePayload(level),
+  }))), context);
+};
+
 export const auditHooks: Record<string, HookHandler> = {
   // Catalog
   "catalog.afterCreate": createAuditAfterHook("catalog_entity", "created") as HookHandler,
@@ -81,6 +97,7 @@ export const auditHooks: Record<string, HookHandler> = {
 
   // Inventory
   "inventory.afterAdjust": createAuditAfterHook("inventory", "adjusted") as HookHandler,
+  "inventory.afterAdjustMany": inventoryAdjustManyAuditHook as HookHandler,
 
   // Customers
   "customers.afterCreate": createAuditAfterHook("customer", "created") as HookHandler,

package/src/modules/audit/service.ts

@@ -37,6 +37,8 @@ export interface ListArgs {
 
 export interface AuditService {
   record(args: RecordArgs): Promise<void>;
+  /** Many entries sharing one context, in ONE insert — for bulk operations (`inventory.afterAdjustMany`). */
+  recordMany(entries: ReadonlyArray<Omit<RecordArgs, "ctx">>, ctx: RecordArgs["ctx"]): Promise<void>;
   listForEntity(args: ListForEntityArgs): Promise<AuditEntry[]>;
   list(args: ListArgs): Promise<AuditEntry[]>;
 }
@@ -58,6 +60,9 @@ export function createNullAuditService(): AuditService {
         createdAt: new Date(),
       });
     },
+    async recordMany(many, ctx) {
+      for (const entry of many) await this.record({ ...entry, ctx });
+    },
     async listForEntity(args) {
       return entries
         .filter(
@@ -105,6 +110,22 @@ export function createAuditService(db: DrizzleDatabase): AuditService {
       });
     },
 
+    async recordMany(many, ctx) {
+      if (many.length === 0) return;
+      const dbOrTx = ctx.tx != null ? (ctx.tx as typeof db) : db;
+      const organizationId = resolveOrgIdForCommerce(ctx.actor, ctx.commerceConfig);
+      await dbOrTx.insert(auditLog).values(many.map((entry) => ({
+        organizationId,
+        entityType: entry.entityType,
+        entityId: entry.entityId,
+        event: entry.event,
+        payload: entry.payload ?? {},
+        actorId: ctx.actor?.userId ?? null,
+        actorType: ctx.actor != null ? "user" : null,
+        requestId: ctx.requestId,
+      })));
+    },
+
     async listForEntity(args) {
       const { organizationId, entityType, entityId, limit = 50, ctx } = args;
       const dbOrTx =

package/src/modules/channels/adapter.ts

@@ -215,6 +215,13 @@ export interface ChannelConnector {
   ): Promise<Result<{ credentials: Record<string, unknown>; storeDomain: string }, ChannelConnectorError>>;
   importCatalog(store: ChannelStore, cursor?: string): Promise<Result<ChannelCatalogPage>>;
   fetchInventory(store: ChannelStore, ids?: string[]): Promise<Result<ChannelInventoryLevel[]>>;
+  /**
+   * One page of the store's inventory, starting at `cursor` (null for the first page), with the
+   * cursor of the next page or null on the last. The store's inventory sync takes one page per
+   * step through this; a connector without it is synced by re-reading `fetchInventory` whole on
+   * every step, which is O(levels²) per sync.
+   */
+  fetchInventoryPage?(store: ChannelStore, cursor: string | null): Promise<Result<{ levels: ChannelInventoryLevel[]; nextCursor: string | null }>>;
   pushOrder(store: ChannelStore, slice: ChannelOrderSlice): Promise<Result<ChannelPushOrderResult, ChannelConnectorError>>;
   pushCatalog?(
     store: ChannelStore,

package/src/modules/inventory/repository/index.ts

@@ -622,6 +622,63 @@ export class InventoryRepository {
     return { ok: true, level: updated[0]! };
   }
 
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Set-based writes for one page of absolute levels (`setAbsoluteMany`)
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /** Every level of these entities in one warehouse, row-locked — one statement for a page. */
+  async findLevelsForUpdate(
+    organizationId: string,
+    warehouseId: string,
+    entityIds: readonly string[],
+    ctx: TxContext,
+  ): Promise<InventoryLevel[]> {
+    if (entityIds.length === 0) return [];
+    return this.getDb(ctx)
+      .select()
+      .from(inventoryLevels)
+      .where(and(
+        eq(inventoryLevels.organizationId, organizationId),
+        eq(inventoryLevels.warehouseId, warehouseId),
+        inArray(inventoryLevels.entityId, [...entityIds]),
+      ))
+      .for("update");
+  }
+
+  /** Set each level to its absolute quantity (clamped at 0), one UPDATE for the page; bumps `version`. */
+  async setLevelQuantities(
+    organizationId: string,
+    rows: ReadonlyArray<{ id: string; quantity: number }>,
+    ctx: TxContext,
+  ): Promise<InventoryLevel[]> {
+    if (rows.length === 0) return [];
+    const byId = sql.join(rows.map((row) => sql`WHEN ${row.id}::uuid THEN ${Math.max(0, row.quantity)}::integer`), sql` `);
+    return this.getDb(ctx)
+      .update(inventoryLevels)
+      .set({
+        quantityOnHand: sql`CASE ${inventoryLevels.id} ${byId} END`,
+        updatedAt: new Date(),
+        version: sql`${inventoryLevels.version} + 1`,
+      })
+      .where(and(
+        eq(inventoryLevels.organizationId, organizationId),
+        inArray(inventoryLevels.id, rows.map((row) => row.id)),
+      ))
+      .returning();
+  }
+
+  /** New levels, one INSERT for the page; a row another writer created meanwhile is skipped. */
+  async createLevels(rows: readonly InventoryLevelInsert[], ctx: TxContext): Promise<InventoryLevel[]> {
+    if (rows.length === 0) return [];
+    return this.getDb(ctx).insert(inventoryLevels).values([...rows]).onConflictDoNothing().returning();
+  }
+
+  /** Movements, one INSERT for the page. */
+  async createMovements(rows: readonly InventoryMovementInsert[], ctx: TxContext): Promise<void> {
+    if (rows.length === 0) return;
+    await this.getDb(ctx).insert(inventoryMovements).values([...rows]);
+  }
+
   // ─────────────────────────────────────────────────────────────────────────────
   // Aggregate Queries
   // ─────────────────────────────────────────────────────────────────────────────

package/src/modules/inventory/service.ts

@@ -22,8 +22,17 @@ import {
   InventoryRepository,
   type Warehouse,
   type InventoryLevel,
+  type InventoryLevelInsert,
 } from "./repository/index.js";
 
+type InventoryLevelInsertRow = InventoryLevelInsert;
+
+/** What `inventory.afterAdjustMany` announces: the page's CHANGED levels, grouped by product. */
+export interface InventoryAdjustManyResult {
+  organizationId: string;
+  entities: Array<{ entityId: string; levels: InventoryLevel[] }>;
+}
+
 export type { InventoryAdjustInput, InventoryReserveInput, InventoryReleaseInput } from "./schemas.js";
 import type { InventoryAdjustInput, InventoryReserveInput, InventoryReleaseInput } from "./schemas.js";
 
@@ -533,6 +542,113 @@ export class InventoryService {
     );
   }
 
+  /**
+   * `setAbsolute` for a whole page of levels, set-based — the inventory sync's write.
+   *
+   * setAbsolute per level is a permission check, a row lock, a clamped write, a movement row and an
+   * `inventory.afterAdjust` each: a 27k-variant store synced at ~20 levels per Workflow step and
+   * every changed variant re-marked its product. This keeps the same invariants in a CONSTANT
+   * number of statements per call:
+   *  - `inventory:adjust` is asserted once for the page (refused → nothing is written);
+   *  - the default warehouse (`pickWarehouse`) and the actor's org, once;
+   *  - an unchanged level writes nothing and is not announced; a missing level is created;
+   *  - quantities clamp at 0 (as `GREATEST(0, …)` does) and `version` is bumped;
+   *  - one `adjustment` movement per changed level, carrying its delta.
+   * It announces the page ONCE through `inventory.afterAdjustMany`, grouped by product — NOT
+   * `inventory.afterAdjust` per level. Core's audit and webhook subscribers handle the bulk hook,
+   * so every change is still audited and delivered; a plugin that subscribes to `afterAdjust` must
+   * also subscribe to `afterAdjustMany` (the kernel refuses to boot otherwise).
+   */
+  async setAbsoluteMany(
+    rows: ReadonlyArray<{ entityId: string; variantId?: string | undefined; quantity: number }>,
+    actor?: Actor | null,
+    ctx?: TxContext,
+    options: { reason?: string } = {},
+  ): Promise<Result<InventoryAdjustManyResult>> {
+    try {
+      assertPermission(actor ?? null, "inventory:adjust");
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+    const orgId = resolveOrgIdForCommerce(actor ?? ctx?.actor ?? null, this.deps.config);
+    if (rows.length === 0) return Ok({ organizationId: orgId, entities: [] });
+    const warehouseId = await this.pickWarehouse(actor, ctx);
+    const reason = options.reason ?? "External store absolute inventory sync";
+    const performedBy = actor?.userId ?? "system";
+    const keyOf = (entityId: string, variantId: string | null) => `${entityId}\u0000${variantId ?? ""}`;
+
+    const write = async (txCtx: TxContext): Promise<InventoryAdjustManyResult> => {
+      const entityIds = [...new Set(rows.map((row) => row.entityId))];
+      const existing = new Map((await this.repo.findLevelsForUpdate(orgId, warehouseId, entityIds, txCtx))
+        .map((level) => [keyOf(level.entityId, level.variantId), level]));
+      const updates: Array<{ id: string; quantity: number; before: number }> = [];
+      const inserts: InventoryLevelInsertRow[] = [];
+      const seen = new Set<string>();
+      for (const row of rows) {
+        const key = keyOf(row.entityId, row.variantId ?? null);
+        if (seen.has(key)) continue;
+        seen.add(key);
+        const quantity = Math.max(0, row.quantity);
+        const level = existing.get(key);
+        if (level === undefined) {
+          inserts.push({
+            organizationId: orgId, entityId: row.entityId, warehouseId, quantityOnHand: quantity,
+            quantityReserved: 0, quantityIncoming: 0, ...(row.variantId !== undefined ? { variantId: row.variantId } : {}),
+          });
+        } else if (level.quantityOnHand !== quantity) {
+          updates.push({ id: level.id, quantity, before: level.quantityOnHand });
+        }
+      }
+      if (updates.length === 0 && inserts.length === 0) return { organizationId: orgId, entities: [] };
+
+      const beforeById = new Map(updates.map((update) => [update.id, update.before]));
+      const updated = await this.repo.setLevelQuantities(orgId, updates, txCtx);
+      const created = await this.repo.createLevels(inserts, txCtx);
+      const changed = [...updated, ...created];
+      await this.repo.createMovements(changed.map((level) => ({
+        organizationId: orgId,
+        entityId: level.entityId,
+        warehouseId,
+        type: "adjustment" as const,
+        quantity: level.quantityOnHand - (beforeById.get(level.id) ?? 0),
+        reason,
+        performedBy,
+        ...(level.variantId !== null ? { variantId: level.variantId } : {}),
+      })), txCtx);
+
+      const byEntity = new Map<string, InventoryLevel[]>();
+      for (const level of changed) byEntity.set(level.entityId, [...(byEntity.get(level.entityId) ?? []), level]);
+      const result: InventoryAdjustManyResult = {
+        organizationId: orgId,
+        entities: [...byEntity].map(([entityId, levels]) => ({ entityId, levels })),
+      };
+      const hookCtx: HookContext = createHookContext({
+        actor: actor ?? null,
+        tx: txCtx.tx,
+        logger: createLogger("inventory.adjustMany"),
+        services: this.deps.services,
+        context: { moduleName: "inventory" },
+        database: { db: this.deps.database.db as PluginDb },
+        commerceConfig: this.deps.config,
+      });
+      await runAfterHooks(
+        this.deps.hooks.resolve("inventory.afterAdjustMany") as Parameters<typeof runAfterHooks>[0],
+        null,
+        result,
+        "update",
+        hookCtx,
+        (hook) => this.deps.hooks.runsInTransaction(hook),
+      );
+      return result;
+    };
+
+    try {
+      return Ok(await this.withTransaction(ctx, async (tx) => write(ctx?.tx ? ctx : createTxContext(tx, { actor: actor ?? null }))));
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+  }
+
   /**
    * Deduct inventory on fulfillment (system-level, no permission check).
    *