@open-mercato/core 0.10.1-develop.7773.1.a41b0f6c03 → 0.10.1-develop.7775.1.2a1f553826

package/dist/modules/sales/components/documents/SalesDocumentExtensionSpot.js

@@ -0,0 +1,26 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { extensionPoints } from "@open-mercato/core/modules/sales/extension-points";
+import { resolveExtensionPointPattern } from "@open-mercato/shared/modules/widgets/extension-points";
+import { InjectionSpot } from "@open-mercato/ui/backend/injection/InjectionSpot";
+function SalesDocumentExtensionSpot({
+  surface,
+  context,
+  data,
+  onDataChange
+}) {
+  const pattern = surface === "stage-bar" ? extensionPoints.hosts.documentStageBar.pattern : extensionPoints.hosts.documentClosure.pattern;
+  return /* @__PURE__ */ jsx(
+    InjectionSpot,
+    {
+      spotId: resolveExtensionPointPattern(pattern, { kind: context.kind }),
+      context,
+      data,
+      onDataChange
+    }
+  );
+}
+export {
+  SalesDocumentExtensionSpot
+};
+//# sourceMappingURL=SalesDocumentExtensionSpot.js.map

package/dist/modules/sales/components/documents/SalesDocumentExtensionSpot.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/modules/sales/components/documents/SalesDocumentExtensionSpot.tsx"],
+  "sourcesContent": ["'use client'\n\nimport { extensionPoints } from '@open-mercato/core/modules/sales/extension-points'\nimport { resolveExtensionPointPattern } from '@open-mercato/shared/modules/widgets/extension-points'\nimport { InjectionSpot } from '@open-mercato/ui/backend/injection/InjectionSpot'\n\nexport type SalesDocumentExtensionContext<TRecord extends { id: string }> = {\n  kind: 'order' | 'quote'\n  documentId: string | null\n  record: TRecord | null\n  formId: string\n  resourceKind: 'sales.order' | 'sales.quote'\n  resourceId?: string\n  retryLastMutation: () => Promise<boolean>\n  organizationId: string | null\n  tenantId: string | null\n}\n\ntype SalesDocumentExtensionSpotProps<TRecord extends { id: string }> = {\n  surface: 'stage-bar' | 'closure'\n  context: SalesDocumentExtensionContext<TRecord>\n  data: TRecord\n  onDataChange: (data: TRecord) => void\n}\n\nexport function SalesDocumentExtensionSpot<TRecord extends { id: string }>({\n  surface,\n  context,\n  data,\n  onDataChange,\n}: SalesDocumentExtensionSpotProps<TRecord>) {\n  const pattern = surface === 'stage-bar'\n    ? extensionPoints.hosts.documentStageBar.pattern\n    : extensionPoints.hosts.documentClosure.pattern\n\n  return (\n    <InjectionSpot\n      spotId={resolveExtensionPointPattern(pattern, { kind: context.kind })}\n      context={context}\n      data={data}\n      onDataChange={onDataChange}\n    />\n  )\n}\n"],
+  "mappings": ";AAoCI;AAlCJ,SAAS,uBAAuB;AAChC,SAAS,oCAAoC;AAC7C,SAAS,qBAAqB;AAqBvB,SAAS,2BAA2D;AAAA,EACzE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,GAA6C;AAC3C,QAAM,UAAU,YAAY,cACxB,gBAAgB,MAAM,iBAAiB,UACvC,gBAAgB,MAAM,gBAAgB;AAE1C,SACE;AAAA,IAAC;AAAA;AAAA,MACC,QAAQ,6BAA6B,SAAS,EAAE,MAAM,QAAQ,KAAK,CAAC;AAAA,MACpE;AAAA,MACA;AAAA,MACA;AAAA;AAAA,EACF;AAEJ;",
+  "names": []
+}

package/dist/modules/sales/extension-points.js

@@ -17,6 +17,32 @@ const extensionPoints = defineModuleExtensionPoints({
       supported: ["render-widget"],
       source: "backend/sales/documents/[id]/page.tsx"
     }),
+    documentStageBar: injectionExtensionHost({
+      family: "detail",
+      pattern: "detail:sales.{kind}:stage-bar",
+      parameters: {
+        kind: { source: "SalesDocumentExtensionContext.kind", pattern: "^(order|quote)$" }
+      },
+      supported: ["render-widget"],
+      source: ["components/documents/SalesDocumentExtensionSpot.tsx", "backend/sales/documents/[id]/page.tsx"],
+      contextContract: "SalesDocumentExtensionContext: kind, documentId, record, formId, resourceKind, resourceId, retryLastMutation, organizationId, tenantId",
+      dataContract: "Current sales order or quote record; onDataChange updates the in-page record only",
+      scopeContract: "organizationId and tenantId from the loaded, server-scoped document; widget writes must enforce their own authorization",
+      runtimeContract: "Rendered below the document header; no native stage transition or mutation lifecycle is added"
+    }),
+    documentClosure: injectionExtensionHost({
+      family: "detail",
+      pattern: "detail:sales.{kind}:closure",
+      parameters: {
+        kind: { source: "SalesDocumentExtensionContext.kind", pattern: "^(order|quote)$" }
+      },
+      supported: ["render-widget"],
+      source: ["components/documents/SalesDocumentExtensionSpot.tsx", "backend/sales/documents/[id]/page.tsx"],
+      contextContract: "SalesDocumentExtensionContext: kind, documentId, record, formId, resourceKind, resourceId, retryLastMutation, organizationId, tenantId",
+      dataContract: "Current sales order or quote record; onDataChange updates the in-page record only",
+      scopeContract: "organizationId and tenantId from the loaded, server-scoped document; widget writes must enforce their own authorization",
+      runtimeContract: "Rendered below document details for closure extensions; no native closure dialog or mutation lifecycle is added"
+    }),
     documentDetail: injectionExtensionHost({
       family: "detail",
       pattern: "sales.document.detail.{kind}:{surface}",

package/dist/modules/sales/extension-points.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/modules/sales/extension-points.ts"],
-  "sourcesContent": ["import { dataTableExtensionHost, defineModuleExtensionPoints, injectionExtensionHost } from '@open-mercato/shared/modules/widgets/extension-points'\n\nexport const extensionPoints = defineModuleExtensionPoints({\n  moduleId: 'sales',\n  hosts: {\n    ordersTable: dataTableExtensionHost({ tableId: 'sales.orders', source: 'components/documents/SalesDocumentsTable.tsx' }),\n    quotesTable: dataTableExtensionHost({ tableId: 'sales.quotes', source: 'components/documents/SalesDocumentsTable.tsx' }),\n    paymentsTable: dataTableExtensionHost({ tableId: 'sales.payments', source: 'components/documents/PaymentsSection.tsx' }),\n    orderItemColumns: injectionExtensionHost({\n      family: 'detail',\n      spotId: 'data-table:sales.order.items:columns',\n      supported: ['column-widget'],\n      source: 'components/documents/ItemsSection.tsx',\n    }),\n    orderShipping: injectionExtensionHost({\n      family: 'detail',\n      spotId: 'detail:sales.order:shipping',\n      supported: ['render-widget'],\n      source: 'backend/sales/documents/[id]/page.tsx',\n    }),\n    documentDetail: injectionExtensionHost({\n      family: 'detail',\n      pattern: 'sales.document.detail.{kind}:{surface}',\n      parameters: {\n        kind: { source: 'SalesDocumentKind', pattern: '^(order|quote)$' },\n        surface: { source: 'host declaration', pattern: '^(tabs|details)$' },\n      },\n      supported: ['render-widget'],\n      source: 'backend/sales/documents/[id]/page.tsx',\n    }),\n  },\n})\n\nexport default extensionPoints\n"],
-  "mappings": "AAAA,SAAS,wBAAwB,6BAA6B,8BAA8B;AAErF,MAAM,kBAAkB,4BAA4B;AAAA,EACzD,UAAU;AAAA,EACV,OAAO;AAAA,IACL,aAAa,uBAAuB,EAAE,SAAS,gBAAgB,QAAQ,+CAA+C,CAAC;AAAA,IACvH,aAAa,uBAAuB,EAAE,SAAS,gBAAgB,QAAQ,+CAA+C,CAAC;AAAA,IACvH,eAAe,uBAAuB,EAAE,SAAS,kBAAkB,QAAQ,2CAA2C,CAAC;AAAA,IACvH,kBAAkB,uBAAuB;AAAA,MACvC,QAAQ;AAAA,MACR,QAAQ;AAAA,MACR,WAAW,CAAC,eAAe;AAAA,MAC3B,QAAQ;AAAA,IACV,CAAC;AAAA,IACD,eAAe,uBAAuB;AAAA,MACpC,QAAQ;AAAA,MACR,QAAQ;AAAA,MACR,WAAW,CAAC,eAAe;AAAA,MAC3B,QAAQ;AAAA,IACV,CAAC;AAAA,IACD,gBAAgB,uBAAuB;AAAA,MACrC,QAAQ;AAAA,MACR,SAAS;AAAA,MACT,YAAY;AAAA,QACV,MAAM,EAAE,QAAQ,qBAAqB,SAAS,kBAAkB;AAAA,QAChE,SAAS,EAAE,QAAQ,oBAAoB,SAAS,mBAAmB;AAAA,MACrE;AAAA,MACA,WAAW,CAAC,eAAe;AAAA,MAC3B,QAAQ;AAAA,IACV,CAAC;AAAA,EACH;AACF,CAAC;AAED,IAAO,2BAAQ;",
+  "sourcesContent": ["import { dataTableExtensionHost, defineModuleExtensionPoints, injectionExtensionHost } from '@open-mercato/shared/modules/widgets/extension-points'\n\nexport const extensionPoints = defineModuleExtensionPoints({\n  moduleId: 'sales',\n  hosts: {\n    ordersTable: dataTableExtensionHost({ tableId: 'sales.orders', source: 'components/documents/SalesDocumentsTable.tsx' }),\n    quotesTable: dataTableExtensionHost({ tableId: 'sales.quotes', source: 'components/documents/SalesDocumentsTable.tsx' }),\n    paymentsTable: dataTableExtensionHost({ tableId: 'sales.payments', source: 'components/documents/PaymentsSection.tsx' }),\n    orderItemColumns: injectionExtensionHost({\n      family: 'detail',\n      spotId: 'data-table:sales.order.items:columns',\n      supported: ['column-widget'],\n      source: 'components/documents/ItemsSection.tsx',\n    }),\n    orderShipping: injectionExtensionHost({\n      family: 'detail',\n      spotId: 'detail:sales.order:shipping',\n      supported: ['render-widget'],\n      source: 'backend/sales/documents/[id]/page.tsx',\n    }),\n    documentStageBar: injectionExtensionHost({\n      family: 'detail',\n      pattern: 'detail:sales.{kind}:stage-bar',\n      parameters: {\n        kind: { source: 'SalesDocumentExtensionContext.kind', pattern: '^(order|quote)$' },\n      },\n      supported: ['render-widget'],\n      source: ['components/documents/SalesDocumentExtensionSpot.tsx', 'backend/sales/documents/[id]/page.tsx'],\n      contextContract: 'SalesDocumentExtensionContext: kind, documentId, record, formId, resourceKind, resourceId, retryLastMutation, organizationId, tenantId',\n      dataContract: 'Current sales order or quote record; onDataChange updates the in-page record only',\n      scopeContract: 'organizationId and tenantId from the loaded, server-scoped document; widget writes must enforce their own authorization',\n      runtimeContract: 'Rendered below the document header; no native stage transition or mutation lifecycle is added',\n    }),\n    documentClosure: injectionExtensionHost({\n      family: 'detail',\n      pattern: 'detail:sales.{kind}:closure',\n      parameters: {\n        kind: { source: 'SalesDocumentExtensionContext.kind', pattern: '^(order|quote)$' },\n      },\n      supported: ['render-widget'],\n      source: ['components/documents/SalesDocumentExtensionSpot.tsx', 'backend/sales/documents/[id]/page.tsx'],\n      contextContract: 'SalesDocumentExtensionContext: kind, documentId, record, formId, resourceKind, resourceId, retryLastMutation, organizationId, tenantId',\n      dataContract: 'Current sales order or quote record; onDataChange updates the in-page record only',\n      scopeContract: 'organizationId and tenantId from the loaded, server-scoped document; widget writes must enforce their own authorization',\n      runtimeContract: 'Rendered below document details for closure extensions; no native closure dialog or mutation lifecycle is added',\n    }),\n    documentDetail: injectionExtensionHost({\n      family: 'detail',\n      pattern: 'sales.document.detail.{kind}:{surface}',\n      parameters: {\n        kind: { source: 'SalesDocumentKind', pattern: '^(order|quote)$' },\n        surface: { source: 'host declaration', pattern: '^(tabs|details)$' },\n      },\n      supported: ['render-widget'],\n      source: 'backend/sales/documents/[id]/page.tsx',\n    }),\n  },\n})\n\nexport default extensionPoints\n"],
+  "mappings": "AAAA,SAAS,wBAAwB,6BAA6B,8BAA8B;AAErF,MAAM,kBAAkB,4BAA4B;AAAA,EACzD,UAAU;AAAA,EACV,OAAO;AAAA,IACL,aAAa,uBAAuB,EAAE,SAAS,gBAAgB,QAAQ,+CAA+C,CAAC;AAAA,IACvH,aAAa,uBAAuB,EAAE,SAAS,gBAAgB,QAAQ,+CAA+C,CAAC;AAAA,IACvH,eAAe,uBAAuB,EAAE,SAAS,kBAAkB,QAAQ,2CAA2C,CAAC;AAAA,IACvH,kBAAkB,uBAAuB;AAAA,MACvC,QAAQ;AAAA,MACR,QAAQ;AAAA,MACR,WAAW,CAAC,eAAe;AAAA,MAC3B,QAAQ;AAAA,IACV,CAAC;AAAA,IACD,eAAe,uBAAuB;AAAA,MACpC,QAAQ;AAAA,MACR,QAAQ;AAAA,MACR,WAAW,CAAC,eAAe;AAAA,MAC3B,QAAQ;AAAA,IACV,CAAC;AAAA,IACD,kBAAkB,uBAAuB;AAAA,MACvC,QAAQ;AAAA,MACR,SAAS;AAAA,MACT,YAAY;AAAA,QACV,MAAM,EAAE,QAAQ,sCAAsC,SAAS,kBAAkB;AAAA,MACnF;AAAA,MACA,WAAW,CAAC,eAAe;AAAA,MAC3B,QAAQ,CAAC,uDAAuD,uCAAuC;AAAA,MACvG,iBAAiB;AAAA,MACjB,cAAc;AAAA,MACd,eAAe;AAAA,MACf,iBAAiB;AAAA,IACnB,CAAC;AAAA,IACD,iBAAiB,uBAAuB;AAAA,MACtC,QAAQ;AAAA,MACR,SAAS;AAAA,MACT,YAAY;AAAA,QACV,MAAM,EAAE,QAAQ,sCAAsC,SAAS,kBAAkB;AAAA,MACnF;AAAA,MACA,WAAW,CAAC,eAAe;AAAA,MAC3B,QAAQ,CAAC,uDAAuD,uCAAuC;AAAA,MACvG,iBAAiB;AAAA,MACjB,cAAc;AAAA,MACd,eAAe;AAAA,MACf,iBAAiB;AAAA,IACnB,CAAC;AAAA,IACD,gBAAgB,uBAAuB;AAAA,MACrC,QAAQ;AAAA,MACR,SAAS;AAAA,MACT,YAAY;AAAA,QACV,MAAM,EAAE,QAAQ,qBAAqB,SAAS,kBAAkB;AAAA,QAChE,SAAS,EAAE,QAAQ,oBAAoB,SAAS,mBAAmB;AAAA,MACrE;AAAA,MACA,WAAW,CAAC,eAAe;AAAA,MAC3B,QAAQ;AAAA,IACV,CAAC;AAAA,EACH;AACF,CAAC;AAED,IAAO,2BAAQ;",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/core",
-  "version": "0.10.1-develop.7773.1.a41b0f6c03",
+  "version": "0.10.1-develop.7775.1.2a1f553826",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -266,16 +266,16 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@open-mercato/ai-assistant": "0.10.1-develop.7773.1.a41b0f6c03",
-    "@open-mercato/shared": "0.10.1-develop.7773.1.a41b0f6c03",
-    "@open-mercato/ui": "0.10.1-develop.7773.1.a41b0f6c03",
+    "@open-mercato/ai-assistant": "0.10.1-develop.7775.1.2a1f553826",
+    "@open-mercato/shared": "0.10.1-develop.7775.1.2a1f553826",
+    "@open-mercato/ui": "0.10.1-develop.7775.1.2a1f553826",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@open-mercato/ai-assistant": "0.10.1-develop.7773.1.a41b0f6c03",
-    "@open-mercato/shared": "0.10.1-develop.7773.1.a41b0f6c03",
-    "@open-mercato/ui": "0.10.1-develop.7773.1.a41b0f6c03",
+    "@open-mercato/ai-assistant": "0.10.1-develop.7775.1.2a1f553826",
+    "@open-mercato/shared": "0.10.1-develop.7775.1.2a1f553826",
+    "@open-mercato/ui": "0.10.1-develop.7775.1.2a1f553826",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^7.0.1",
     "@testing-library/react": "^16.3.3",

package/src/modules/cart/lib/promotionContext.ts

@@ -1,3 +1,4 @@
+import { TransactionContext } from '@mikro-orm/core'
 import type { EntityManager } from '@mikro-orm/postgresql'
 import { findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
 import { CatalogProduct, CatalogProductVariant } from '@open-mercato/core/modules/catalog/data/entities'
@@ -163,7 +164,7 @@ export type BuildPromotionsEffectsPhaseParams = {
 export function buildPromotionsEffectsPhase(params: BuildPromotionsEffectsPhaseParams): () => Promise<void> {
   const { em, container, cart, lines, assortmentScope, tenantScope, now, adjustments, warnings, createdGiftLines, removedGiftLines } = params
 
-  return async () => {
+  return () => TransactionContext.create(em, async () => {
     const promotionsService = container.resolve<PromotionsService>('promotionsService')
     const salesCalculationService = container.resolve<SalesCalculationService>('salesCalculationService')
 
@@ -181,11 +182,6 @@ export function buildPromotionsEffectsPhase(params: BuildPromotionsEffectsPhaseP
     const codeIdsInUse = Array.from(
       new Set(existingApplications.map((application) => application.codeId).filter((id): id is string => !!id)),
     )
-    // A code-id's reservation lives on `promotions`' own tables, not this cart's `em` — so
-    // extending it and then re-checking it still exists is two round trips against a
-    // DIFFERENT EntityManager (`extendReservation`'s own `resolvePromotionsEm` fork) plus a
-    // plain cross-module read on THIS `em`, never a read-after-mutate hazard on this phase's
-    // own pending changes (there are none yet at this point in the phase).
     const lapsedCodeIds = new Set<string>()
     for (const codeId of codeIdsInUse) {
       await promotionsService.extendReservation(codeId, cart.id)
@@ -566,5 +562,5 @@ export function buildPromotionsEffectsPhase(params: BuildPromotionsEffectsPhaseP
     // has the full `appliedPromotions` shape to read from, same "found and closed before
     // anyone needed it" style this run's earlier steps use for a half-wired field.
     cart.promotionEffects = result.appliedPromotions
-  }
+  })
 }

package/src/modules/catalog/AGENTS.md

@@ -112,6 +112,6 @@ Two typed AI agents ship from `ai-agents.ts`. See `/framework/ai-assistant/agent
 | Agent ID | Mode | Policy | Purpose |
 |----------|------|--------|---------|
 | `catalog.catalog_assistant` | chat | `read-only` | General operator explorer for products, categories, variants, prices, offers, product media, tags, option schemas, and unit conversions via the base catalog tool pack + general-purpose packs. |
-| `catalog.merchandising_assistant` | chat | `read-only` (mutation-capable via per-tenant override unlocking `catalog.update_product`, `catalog.bulk_update_products`, `catalog.apply_attribute_extraction`, `catalog.update_product_media_descriptions`) | D18 demo agent: proposes descriptions, attribute extractions, title variants, and price adjustments for the current selection on the products list page. |
+| `catalog.merchandising_assistant` | chat | `confirm-required`; tenant overrides may restrict to `read-only`, never escalate | D18 agent: proposes descriptions, attribute extractions, title variants, and price adjustments; whitelisted product, batch, attribute, and media writes require approval. See `ai-agents.ts`. |
 
-The merchandising assistant is the Phase 2 D18 demo. `<AiChat agent="catalog.merchandising_assistant" />` is injected via `MerchandisingAssistantSheet.tsx` on `/backend/catalog/catalog/products` (see `packages/core/src/modules/catalog/backend/catalog/products/page.tsx`). Mutation-capable authoring tools route through `prepareMutation` + the approval-card contract; confirmed batches refresh the DataTable via `catalog.product.updated` events on the DOM event bridge.
+The merchandising assistant is the D18 demo. `<AiChat agent="catalog.merchandising_assistant" />` is injected via `MerchandisingAssistantSheet.tsx` on `/backend/catalog/products` (see `packages/core/src/modules/catalog/backend/catalog/products/page.tsx`). Mutation tools route through `prepareMutation` + the approval-card contract; confirmed batches refresh the DataTable via `catalog.product.updated` events on the DOM event bridge.

package/src/modules/customers/AGENTS.md

@@ -125,8 +125,8 @@ This module is the reference implementation for the AI framework. Copy `ai-agent
 
 | Agent ID | Mode | Policy | Purpose |
 |----------|------|--------|---------|
-| `customers.account_assistant` | chat | read-only (mutation-capable via per-tenant override that unlocks `customers.update_deal_stage`; see `packages/core/src/modules/customers/ai-agents.ts` for the whitelist and prompt) | Operator-facing assistant that explores people, companies, deals, activities, tasks, addresses, tags, and settings through the customers tool pack. |
-| `customers.update_deal_stage` | tool (mutation) | `destructive-confirm-required` — goes through `prepareMutation` + the approval card | Moves a deal between stages / flips status between open, won, lost. Declared via `defineAiTool` in `ai-tools.ts` and exposed only when the tenant mutation-policy override promotes the agent above read-only. |
+| `customers.account_assistant` | chat | `confirm-required`; tenant overrides may restrict to `read-only`, never escalate | Explores people, companies, deals, activities, tasks, addresses, tags, and settings; whitelisted stage, comment, and activity writes require approval. See `ai-agents.ts`. |
+| `customers.update_deal_stage` | tool (mutation) | Agent mutation policy applies through `prepareMutation` + the approval card | Moves deals between stages or open/won/lost statuses. Declared in `ai-tools/deals-pack.ts`; blocked when the agent is read-only. |
 | `customers.deal_analyzer` | chat, `executionEngine: 'stream-text'` | `confirm-required` | Multi-step agentic demo that exercises loop primitives from PRs #1856..#1869. Calls `customers.analyze_deals`, ranks deals by health score, then calls `customers.update_deal_stage` for the highest-value stalled deal — loop stops immediately after (loop.stopWhen). `loop.prepareStep` scopes the active tool set by step without overriding the model. It intentionally leaves `defaultProvider` and `defaultModel` unset so runtime resolution uses `OM_AI_PROVIDER` / `OM_AI_MODEL` or tenant/runtime overrides. |
 | `customers.deal_analyzer_tool_loop` | chat, `executionEngine: 'tool-loop-agent'` | `confirm-required` | Sibling agent identical to `customers.deal_analyzer` but dispatched via `ToolLoopAgent`. Proves the mutation-approval gate holds for both execution engines (TC-AI-AGENT-LOOP-006). |
 

package/src/modules/customers/ai-tools.ts

@@ -1,18 +1,15 @@
 /**
- * Module-root AI tool contribution for the customers module
- * (Phase 1 WS-C, Step 3.9 — read-only Phase 1 surface).
+ * Module-root AI tool contribution for the customers module.
  *
  * The generator walks every module for a top-level `ai-tools.ts` and takes
  * the default/`aiTools` export as the contribution. This file aggregates the
- * six customers packs (people, companies, deals, activities+tasks,
- * addresses+tags, settings) so they all flow through the existing
+ * customers packs (people, companies, deals, activities+tasks,
+ * addresses+tags, settings, deal analysis) so they all flow through the existing
  * `ai-tools.generated.ts` pipeline without any generator changes.
  *
- * Mutation tools are deferred to Step 5.13+ under the pending-action contract;
- * every tool here is read-only and enforces tenant + organization scoping via
- * the existing encryption helpers. See
- * `.ai/runs/2026-04-18-ai-framework-unification/step-3.9-checks.md` for the
- * matrix of required features and decisions.
+ * Read and mutation tools enforce tenant + organization scoping. Mutations
+ * use the pending-action approval contract and command-backed writes;
+ * read-only agents cannot expose them. See the framework AI agents guide.
  */
 import peopleAiTools from './ai-tools/people-pack'
 import companiesAiTools from './ai-tools/companies-pack'

package/src/modules/promotions/lib/promotions-service.ts

@@ -1,3 +1,4 @@
+import { TransactionContext } from '@mikro-orm/core'
 import type { EntityManager } from '@mikro-orm/postgresql'
 import { computeProductScopeKeys, PRODUCT_SCOPE_CATEGORY_PREFIX } from '@open-mercato/core/modules/catalog/lib/productScopeKeys'
 import { Currency } from '@open-mercato/core/modules/currencies/data/entities'
@@ -91,9 +92,10 @@ function resolvePromotionsServiceScope(container: PromotionsServiceContainer): P
 }
 
 function resolvePromotionsEm(container: PromotionsServiceContainer): EntityManager {
-  // Same fork-on-resolve precedent as `services/promotion-cache.ts`'s
-  // `resolvePromotionEm` / `commands/promotions.ts`'s command handlers.
-  return container.resolve<EntityManager>('em').fork()
+  const registeredEm = container.resolve<EntityManager>('em')
+  const contextualEm = TransactionContext.getEntityManager(registeredEm.name) as EntityManager | undefined
+  const em = contextualEm && contextualEm.getDriver() === registeredEm.getDriver() ? contextualEm : registeredEm
+  return em.fork({ keepTransactionContext: true, disableContextResolution: Boolean(contextualEm && contextualEm !== em) })
 }
 
 // Step 6.2's five code-service methods need the full `auth` (not just tenant/org scope)

package/src/modules/promotions/services/promotion-cache.ts

@@ -1,3 +1,4 @@
+import { TransactionContext } from '@mikro-orm/core'
 import type { EntityManager } from '@mikro-orm/postgresql'
 import { runWithCacheTenant, type CacheStrategy } from '@open-mercato/cache'
 import { createLogger } from '@open-mercato/shared/lib/logger'
@@ -284,6 +285,7 @@ export type PromotionCacheContainer = {
 }
 
 function resolvePromotionCacheStrategy(container: PromotionCacheContainer): CacheStrategy | null {
+  if (resolvePromotionEm(container).isInTransaction()) return null
   try {
     return container.resolve<CacheStrategy>('cache') ?? null
   } catch {
@@ -292,15 +294,21 @@ function resolvePromotionCacheStrategy(container: PromotionCacheContainer): Cach
 }
 
 function resolvePromotionEm(container: PromotionCacheContainer): EntityManager {
-  // Exact precedent: `commands/promotions.ts` resolves/forks the same way —
-  // `(ctx.container.resolve('em') as EntityManager).fork()` — before any read/write.
-  return (container.resolve<EntityManager>('em')).fork()
+  const registeredEm = container.resolve<EntityManager>('em')
+  const contextualEm = TransactionContext.getEntityManager(registeredEm.name) as EntityManager | undefined
+  const em = contextualEm && contextualEm.getDriver() === registeredEm.getDriver() ? contextualEm : registeredEm
+  return em.fork({ keepTransactionContext: true, disableContextResolution: Boolean(contextualEm && contextualEm !== em) })
 }
 
 export class PromotionCacheService {
   constructor(private readonly container: PromotionCacheContainer) {}
 
   async getActivePromotions(tenantId: string, organizationId: string): Promise<NormalizedPromotion[]> {
+    const em = resolvePromotionEm(this.container)
+    if (em.isInTransaction()) {
+      const promotions = await this.buildActivePromotionTrees(tenantId, organizationId)
+      return this.buildTransactionalUsageSnapshot(em, promotions, tenantId, organizationId)
+    }
     const cache = resolvePromotionCacheStrategy(this.container)
     const treeKey = buildPromotionTreeCacheKey(tenantId, organizationId)
 
@@ -317,6 +325,35 @@ export class PromotionCacheService {
     )
   }
 
+  private async buildTransactionalUsageSnapshot(
+    em: EntityManager,
+    promotions: NormalizedPromotion[],
+    tenantId: string,
+    organizationId: string,
+  ): Promise<NormalizedPromotion[]> {
+    const budgeted = promotions.filter((promotion) => promotion.maxBudget !== null)
+    const currencies = [...new Set(budgeted.map((promotion) => promotion.budgetCurrency).filter((currency): currency is string => !!currency))]
+    const totals = new Map<string, string>()
+    if (budgeted.length > 0 && currencies.length > 0) {
+      const promotionIds = budgeted.map((promotion) => promotion.id)
+      const promotionSlots = promotionIds.map(() => '?').join(', ')
+      const currencySlots = currencies.map(() => '?').join(', ')
+      const rows = await em.execute<Array<{ promotion_id: string; currency: string; total: string }>>(
+        `SELECT promotion_id, currency, COALESCE(SUM(total_discount_amount), 0)::text AS total
+         FROM promotion_usages
+         WHERE promotion_id IN (${promotionSlots}) AND currency IN (${currencySlots})
+           AND organization_id = ? AND tenant_id = ? AND reverted_at IS NULL
+         GROUP BY promotion_id, currency`,
+        [...promotionIds, ...currencies, organizationId, tenantId],
+      )
+      for (const row of rows) totals.set(`${row.promotion_id}:${row.currency}`, row.total)
+    }
+    return promotions.map((promotion) => promotion.maxBudget === null ? promotion : freezeOutsideProduction({
+      ...promotion,
+      totalDiscountGranted: totals.get(`${promotion.id}:${promotion.budgetCurrency}`) ?? '0',
+    }))
+  }
+
   // §Cache Build Contract item 4: "read only for budget-capped promotions" — an
   // uncapped promotion's `totalDiscountGranted` is never read back from
   // `promotion_usages`, it stays the inert '0' baked into the tree cache.
@@ -369,7 +406,7 @@ export class PromotionCacheService {
   ): Promise<string> {
     if (!budgetCurrency) return '0'
     const em = resolvePromotionEm(this.container)
-    const rows = (await em.getConnection().execute(
+    const rows = (await em.execute(
       `SELECT COALESCE(SUM(total_discount_amount), 0)::text AS total
        FROM promotion_usages
        WHERE promotion_id = ? AND organization_id = ? AND tenant_id = ? AND currency = ? AND reverted_at IS NULL`,

package/src/modules/sales/api/documents/factory.ts

@@ -473,7 +473,7 @@ export function buildDocumentCrudOptions(binding: DocumentBinding) {
     indexer: {
       entityType: binding.entityId,
     },
-    enrichers: binding.kind === 'order' ? { entityId: binding.entityId } : undefined,
+    enrichers: { entityId: binding.entityId },
     list: {
       schema: listSchema,
       entityId: binding.entityId,

package/src/modules/sales/api/orders/route.ts

@@ -3,8 +3,8 @@ import { SalesOrder } from '../../data/entities'
 import { E } from '#generated/entities.ids.generated'
 import { buildDocumentCrudOptions, buildDocumentOpenApi } from '../documents/factory'
 
-const crud = makeCrudRoute(
-  buildDocumentCrudOptions({
+const crud = makeCrudRoute({
+  ...buildDocumentCrudOptions({
     kind: 'order',
     entity: SalesOrder,
     entityId: E.sales.sales_order,
@@ -15,7 +15,8 @@ const crud = makeCrudRoute(
     manageFeature: 'sales.orders.manage',
     viewFeature: 'sales.orders.view',
   }),
-)
+  enrichers: { entityId: E.sales.sales_order },
+})
 
 export const metadata = crud.metadata
 export const GET = crud.GET

package/src/modules/sales/api/quotes/route.ts

@@ -3,8 +3,8 @@ import { SalesQuote } from '../../data/entities'
 import { E } from '#generated/entities.ids.generated'
 import { buildDocumentCrudOptions, buildDocumentOpenApi } from '../documents/factory'
 
-const crud = makeCrudRoute(
-  buildDocumentCrudOptions({
+const crud = makeCrudRoute({
+  ...buildDocumentCrudOptions({
     kind: 'quote',
     entity: SalesQuote,
     entityId: E.sales.sales_quote,
@@ -15,7 +15,8 @@ const crud = makeCrudRoute(
     manageFeature: 'sales.quotes.manage',
     viewFeature: 'sales.quotes.view',
   }),
-)
+  enrichers: { entityId: E.sales.sales_quote },
+})
 
 export const metadata = crud.metadata
 export const GET = crud.GET

package/src/modules/sales/backend/sales/documents/[id]/page.tsx

@@ -52,6 +52,7 @@ import type { AdjustmentRowData } from '@open-mercato/core/modules/sales/compone
 import { SalesShipmentsSection } from '@open-mercato/core/modules/sales/components/documents/ShipmentsSection'
 import { SalesReturnsSection } from '@open-mercato/core/modules/sales/components/documents/ReturnsSection'
 import { DocumentTotals } from '@open-mercato/core/modules/sales/components/documents/DocumentTotals'
+import { SalesDocumentExtensionSpot, type SalesDocumentExtensionContext } from '@open-mercato/core/modules/sales/components/documents/SalesDocumentExtensionSpot'
 import { E } from '#generated/entities.ids.generated'
 import type { DictionarySelectLabels } from '@open-mercato/core/modules/dictionaries/components/DictionaryEntrySelect'
 import { useCurrencyDictionary } from '@open-mercato/core/modules/customers/components/detail/hooks/useCurrencyDictionary'
@@ -862,6 +863,8 @@ type StatusOption = {
 
 type DocumentRecord = {
   id: string
+  organizationId?: string | null
+  tenantId?: string | null
   orderNumber?: string | null
   quoteNumber?: string | null
   status?: string | null
@@ -1992,14 +1995,17 @@ export default function SalesDocumentDetailPage({
     contextId: mutationContextId,
     blockedMessage: t('ui.forms.flash.saveBlocked', 'Save blocked by validation'),
   })
-  const detailInjectionContext = React.useMemo(
+  const detailInjectionContext = React.useMemo<SalesDocumentExtensionContext<DocumentRecord>>(
     () => ({
       kind,
+      documentId: record?.id ?? null,
       record,
       formId: mutationContextId,
       resourceKind: `sales.${kind}`,
       resourceId: record?.id ?? undefined,
       retryLastMutation,
+      organizationId: record?.organizationId ?? null,
+      tenantId: record?.tenantId ?? null,
     }),
     [kind, mutationContextId, record, retryLastMutation],
   )
@@ -4779,6 +4785,12 @@ export default function SalesDocumentDetailPage({
           isDeleting={deleting}
           deleteLabel={t('sales.documents.detail.delete', 'Delete')}
         />
+        <SalesDocumentExtensionSpot
+          surface="stage-bar"
+          context={detailInjectionContext}
+          data={record}
+          onDataChange={setRecord}
+        />
         <div className="grid gap-4 md:grid-cols-4">
           <div className="md:col-span-3">
             <CustomerInlineEditor
@@ -5023,6 +5035,12 @@ export default function SalesDocumentDetailPage({
           />
         </div>
 
+        <SalesDocumentExtensionSpot
+          surface="closure"
+          context={detailInjectionContext}
+          data={record}
+          onDataChange={setRecord}
+        />
         <div className="space-y-4">
           <CustomDataSection
             title={t('sales.documents.detail.customData', 'Custom data')}

package/src/modules/sales/components/documents/SalesDocumentExtensionSpot.tsx

@@ -0,0 +1,44 @@
+'use client'
+
+import { extensionPoints } from '@open-mercato/core/modules/sales/extension-points'
+import { resolveExtensionPointPattern } from '@open-mercato/shared/modules/widgets/extension-points'
+import { InjectionSpot } from '@open-mercato/ui/backend/injection/InjectionSpot'
+
+export type SalesDocumentExtensionContext<TRecord extends { id: string }> = {
+  kind: 'order' | 'quote'
+  documentId: string | null
+  record: TRecord | null
+  formId: string
+  resourceKind: 'sales.order' | 'sales.quote'
+  resourceId?: string
+  retryLastMutation: () => Promise<boolean>
+  organizationId: string | null
+  tenantId: string | null
+}
+
+type SalesDocumentExtensionSpotProps<TRecord extends { id: string }> = {
+  surface: 'stage-bar' | 'closure'
+  context: SalesDocumentExtensionContext<TRecord>
+  data: TRecord
+  onDataChange: (data: TRecord) => void
+}
+
+export function SalesDocumentExtensionSpot<TRecord extends { id: string }>({
+  surface,
+  context,
+  data,
+  onDataChange,
+}: SalesDocumentExtensionSpotProps<TRecord>) {
+  const pattern = surface === 'stage-bar'
+    ? extensionPoints.hosts.documentStageBar.pattern
+    : extensionPoints.hosts.documentClosure.pattern
+
+  return (
+    <InjectionSpot
+      spotId={resolveExtensionPointPattern(pattern, { kind: context.kind })}
+      context={context}
+      data={data}
+      onDataChange={onDataChange}
+    />
+  )
+}

package/src/modules/sales/extension-points.ts

@@ -18,6 +18,32 @@ export const extensionPoints = defineModuleExtensionPoints({
       supported: ['render-widget'],
       source: 'backend/sales/documents/[id]/page.tsx',
     }),
+    documentStageBar: injectionExtensionHost({
+      family: 'detail',
+      pattern: 'detail:sales.{kind}:stage-bar',
+      parameters: {
+        kind: { source: 'SalesDocumentExtensionContext.kind', pattern: '^(order|quote)$' },
+      },
+      supported: ['render-widget'],
+      source: ['components/documents/SalesDocumentExtensionSpot.tsx', 'backend/sales/documents/[id]/page.tsx'],
+      contextContract: 'SalesDocumentExtensionContext: kind, documentId, record, formId, resourceKind, resourceId, retryLastMutation, organizationId, tenantId',
+      dataContract: 'Current sales order or quote record; onDataChange updates the in-page record only',
+      scopeContract: 'organizationId and tenantId from the loaded, server-scoped document; widget writes must enforce their own authorization',
+      runtimeContract: 'Rendered below the document header; no native stage transition or mutation lifecycle is added',
+    }),
+    documentClosure: injectionExtensionHost({
+      family: 'detail',
+      pattern: 'detail:sales.{kind}:closure',
+      parameters: {
+        kind: { source: 'SalesDocumentExtensionContext.kind', pattern: '^(order|quote)$' },
+      },
+      supported: ['render-widget'],
+      source: ['components/documents/SalesDocumentExtensionSpot.tsx', 'backend/sales/documents/[id]/page.tsx'],
+      contextContract: 'SalesDocumentExtensionContext: kind, documentId, record, formId, resourceKind, resourceId, retryLastMutation, organizationId, tenantId',
+      dataContract: 'Current sales order or quote record; onDataChange updates the in-page record only',
+      scopeContract: 'organizationId and tenantId from the loaded, server-scoped document; widget writes must enforce their own authorization',
+      runtimeContract: 'Rendered below document details for closure extensions; no native closure dialog or mutation lifecycle is added',
+    }),
     documentDetail: injectionExtensionHost({
       family: 'detail',
       pattern: 'sales.document.detail.{kind}:{surface}',