@open-mercato/cli 0.10.1-develop.7811.1.66050c1838 → 0.10.1-develop.7813.1.83931e7add

package/dist/agentic/guides/modules/staff/index.md

@@ -1,5 +1,5 @@
 # staff — module facts (generated, do not edit)
-<!-- generated from @open-mercato/core 0.10.1-develop.7811.1.66050c1838; core 0.10.1-develop.7811.1.66050c1838 — R1 staleness stamp -->
+<!-- generated from @open-mercato/core 0.10.1-develop.7813.1.83931e7add; core 0.10.1-develop.7813.1.83931e7add — R1 staleness stamp -->
 Source root: node_modules/@open-mercato/core/src/modules/staff
 
 ## Sections

package/dist/agentic/guides/modules/storage_s3/index.md

@@ -1,5 +1,5 @@
 # storage_s3 — module facts (generated, do not edit)
-<!-- generated from @open-mercato/storage-s3 0.10.1-develop.7811.1.66050c1838; core 0.10.1-develop.7811.1.66050c1838 — R1 staleness stamp -->
+<!-- generated from @open-mercato/storage-s3 0.10.1-develop.7813.1.83931e7add; core 0.10.1-develop.7813.1.83931e7add — R1 staleness stamp -->
 Source root: node_modules/@open-mercato/storage-s3/src/modules/storage_s3
 
 ## Sections

package/dist/agentic/guides/modules/sync_akeneo/index.md

@@ -1,5 +1,5 @@
 # sync_akeneo — module facts (generated, do not edit)
-<!-- generated from @open-mercato/sync-akeneo 0.10.1-develop.7811.1.66050c1838; core 0.10.1-develop.7811.1.66050c1838 — R1 staleness stamp -->
+<!-- generated from @open-mercato/sync-akeneo 0.10.1-develop.7813.1.83931e7add; core 0.10.1-develop.7813.1.83931e7add — R1 staleness stamp -->
 Source root: node_modules/@open-mercato/sync-akeneo/src/modules/sync_akeneo
 
 ## Sections

package/dist/agentic/guides/modules/sync_excel/index.md

@@ -1,5 +1,5 @@
 # sync_excel — module facts (generated, do not edit)
-<!-- generated from @open-mercato/core 0.10.1-develop.7811.1.66050c1838; core 0.10.1-develop.7811.1.66050c1838 — R1 staleness stamp -->
+<!-- generated from @open-mercato/core 0.10.1-develop.7813.1.83931e7add; core 0.10.1-develop.7813.1.83931e7add — R1 staleness stamp -->
 Source root: node_modules/@open-mercato/core/src/modules/sync_excel
 
 ## Sections

package/dist/agentic/guides/modules/system_status_overlays/index.md

@@ -1,5 +1,5 @@
 # system_status_overlays — module facts (generated, do not edit)
-<!-- generated from @open-mercato/enterprise 0.10.1-develop.7811.1.66050c1838; core 0.10.1-develop.7811.1.66050c1838 — R1 staleness stamp -->
+<!-- generated from @open-mercato/enterprise 0.10.1-develop.7813.1.83931e7add; core 0.10.1-develop.7813.1.83931e7add — R1 staleness stamp -->
 Source root: node_modules/@open-mercato/enterprise/src/modules/system_status_overlays
 
 ## Sections

package/dist/agentic/guides/modules/telemetry/index.md

@@ -1,5 +1,5 @@
 # telemetry — module facts (generated, do not edit)
-<!-- generated from @open-mercato/telemetry 0.10.1-develop.7811.1.66050c1838; core 0.10.1-develop.7811.1.66050c1838 — R1 staleness stamp -->
+<!-- generated from @open-mercato/telemetry 0.10.1-develop.7813.1.83931e7add; core 0.10.1-develop.7813.1.83931e7add — R1 staleness stamp -->
 Source root: node_modules/@open-mercato/telemetry/src/modules/telemetry
 
 ## Sections

package/dist/agentic/guides/modules/tillio/index.md

@@ -1,5 +1,5 @@
 # tillio — module facts (generated, do not edit)
-<!-- generated from @open-mercato/tillio 0.10.1-develop.7811.1.66050c1838; core 0.10.1-develop.7811.1.66050c1838 — R1 staleness stamp -->
+<!-- generated from @open-mercato/tillio 0.10.1-develop.7813.1.83931e7add; core 0.10.1-develop.7813.1.83931e7add — R1 staleness stamp -->
 Source root: node_modules/@open-mercato/tillio/src/modules/tillio
 
 ## Sections

package/dist/agentic/guides/modules/translations/index.md

@@ -1,5 +1,5 @@
 # translations — module facts (generated, do not edit)
-<!-- generated from @open-mercato/core 0.10.1-develop.7811.1.66050c1838; core 0.10.1-develop.7811.1.66050c1838 — R1 staleness stamp -->
+<!-- generated from @open-mercato/core 0.10.1-develop.7813.1.83931e7add; core 0.10.1-develop.7813.1.83931e7add — R1 staleness stamp -->
 Source root: node_modules/@open-mercato/core/src/modules/translations
 
 ## Sections

package/dist/agentic/guides/modules/warranty_claims/index.md

@@ -1,5 +1,5 @@
 # warranty_claims — module facts (generated, do not edit)
-<!-- generated from @open-mercato/core 0.10.1-develop.7811.1.66050c1838; core 0.10.1-develop.7811.1.66050c1838 — R1 staleness stamp -->
+<!-- generated from @open-mercato/core 0.10.1-develop.7813.1.83931e7add; core 0.10.1-develop.7813.1.83931e7add — R1 staleness stamp -->
 Source root: node_modules/@open-mercato/core/src/modules/warranty_claims
 
 ## Sections

package/dist/agentic/guides/modules/webhooks/index.md

@@ -1,5 +1,5 @@
 # webhooks — module facts (generated, do not edit)
-<!-- generated from @open-mercato/webhooks 0.10.1-develop.7811.1.66050c1838; core 0.10.1-develop.7811.1.66050c1838 — R1 staleness stamp -->
+<!-- generated from @open-mercato/webhooks 0.10.1-develop.7813.1.83931e7add; core 0.10.1-develop.7813.1.83931e7add — R1 staleness stamp -->
 Source root: node_modules/@open-mercato/webhooks/src/modules/webhooks
 
 ## Sections

package/dist/agentic/guides/modules/wms/index.md

@@ -1,5 +1,5 @@
 # wms — module facts (generated, do not edit)
-<!-- generated from @open-mercato/core 0.10.1-develop.7811.1.66050c1838; core 0.10.1-develop.7811.1.66050c1838 — R1 staleness stamp -->
+<!-- generated from @open-mercato/core 0.10.1-develop.7813.1.83931e7add; core 0.10.1-develop.7813.1.83931e7add — R1 staleness stamp -->
 Source root: node_modules/@open-mercato/core/src/modules/wms
 
 ## Sections

package/dist/agentic/guides/modules/workflows/index.md

@@ -1,5 +1,5 @@
 # workflows — module facts (generated, do not edit)
-<!-- generated from @open-mercato/core 0.10.1-develop.7811.1.66050c1838; core 0.10.1-develop.7811.1.66050c1838 — R1 staleness stamp -->
+<!-- generated from @open-mercato/core 0.10.1-develop.7813.1.83931e7add; core 0.10.1-develop.7813.1.83931e7add — R1 staleness stamp -->
 Source root: node_modules/@open-mercato/core/src/modules/workflows
 
 ## Sections

package/dist/agentic/guides/reference-module-facts.json

@@ -1185,7 +1185,7 @@
     "facts": {
       "title": "Example Module",
       "description": "Demonstrates pages, APIs, entities and DI.",
-      "coreVersion": "0.10.1-develop.7811.1.66050c1838",
+      "coreVersion": "0.10.1-develop.7813.1.83931e7add",
       "sourcePackage": null,
       "sourceVersion": null,
       "sourceRoot": "src/modules/example",

package/dist/agentic/guides/upstream/BACKWARD_COMPATIBILITY.md

@@ -1,6 +1,6 @@
 # Backward Compatibility Contract
 
-Open Mercato modules are developed by third-party developers who depend on stable platform APIs. Every surface listed below is a **public contract**. Changes to these surfaces MUST follow the deprecation protocol or they are **breaking changes** that block merge.
+Every listed surface is a **public contract**. Changes MUST follow the deprecation protocol or block merge as **breaking changes**.
 
 ## Deprecation Protocol
 
@@ -68,7 +68,7 @@ The following file names, their expected export names, and their role in module
 
 ### 2. Type Definitions & Interfaces (STABLE)
 
-These exported types are consumed by module developers. Required fields MUST NOT be removed or have their types narrowed. Optional fields may be added freely.
+Required fields MUST NOT be removed or narrowed. Optional fields may be added freely.
 
 **Immutable required fields** (removing or renaming any is a breaking change):
 
@@ -112,7 +112,7 @@ These exported types are consumed by module developers. Required fields MUST NOT
 
 ### 3. Function Signatures (STABLE)
 
-These functions are called directly by module code. Their signatures MUST NOT change in a breaking way. New optional parameters may be added.
+Signatures MUST NOT change incompatibly. New optional parameters may be added.
 
 |Function|Package|Contract|
 |---|---|---|
@@ -180,8 +180,6 @@ Spot IDs are the addresses where external modules inject UI. Renaming or removin
 
 ### 7. API Route URLs (STABLE)
 
-External tools, frontends, and integrations depend on API URL patterns.
-
 - MUST NOT rename or remove an existing API route URL
 - MUST NOT change the HTTP method for an existing operation
 - MUST NOT remove fields from existing response schemas
@@ -312,7 +310,7 @@ Files in `apps/mercato/.mercato/generated/` are produced by the CLI generators.
 
 |Surface|Change|Classification|
 |---|---|---|
-|Type interface (`IntegrationScope`)|New **optional** field `userId?: string \| null`|✓ ADDITIVE (Type interface, optional field)|
+|Type interface (`IntegrationScope`)|New **optional** field `userId?: string \|null`|✓ ADDITIVE (Type interface, optional field)|
 |Database schema|New nullable column `integration_credentials.user_id uuid` via additive migration `Migration20260526154136`, plus partial unique index `integration_credentials_user_lookup_idx` on `(integration_id, organization_id, tenant_id, user_id)` `WHERE user_id IS NOT NULL AND deleted_at IS NULL`|✓ ADDITIVE (NULL default; the partial index leaves existing tenant-wide rows untouched)|
 |`createCredentialsService` API|`getRaw` / `resolve` / `save` / `saveField` signatures unchanged; when `scope.userId` is falsy the lookup filter pins `user_id = NULL`, reproducing the prior tenant-wide behaviour exactly|✓ Behaviour-preserving for existing callers|
 
@@ -423,7 +421,7 @@ Deleting a user who had customised their sidebar failed on the `user_sidebar_pre
 |Surface|Change|Classification|
 |---|---|---|
 |Function signatures|New export `onModulesRegistered(listener)` on `@open-mercato/shared/lib/modules/registry`|✓ ADDITIVE (new function)|
-|Type definitions|New export `ModulesRegisteredListener = (modules: Module[]) => void \| PromiseLike<void>`|✓ ADDITIVE (new type, no rename)|
+|Type definitions|New export `ModulesRegisteredListener = (modules: Module[]) => void \|PromiseLike<void>`|✓ ADDITIVE (new type, no rename)|
 |`registerModules(modules)`|Signature, return type, and synchronous behavior unchanged; it now also notifies listeners after the reconciliation it already performed|✓ Behaviour-preserving for existing callers|
 |Import paths|None — both exports ship from the existing registry path|✓ No change|
 |Event IDs, API routes, DB schema, DI names, ACL features, notification IDs, CLI commands, generated files|No change|✓ n/a|
@@ -470,7 +468,7 @@ Issue #3852 removed the non-cryptographic passkey verification shape from `Passk
 
 |Surface|Change|Classification|
 |---|---|---|
-|Type definitions (§2)|New optional method `DataSyncAdapter.supportsStartControl?(control, entityType)`; new exported type `DataSyncStartControl = 'fullSync' \| 'batchSize'`|✓ ADDITIVE (optional member, new type — same shape as the `persistsSharedCursor` and `runParameters` additions before it)|
+|Type definitions (§2)|New optional method `DataSyncAdapter.supportsStartControl?(control, entityType)`; new exported type `DataSyncStartControl = 'fullSync' \|'batchSize'`|✓ ADDITIVE (optional member, new type — same shape as the `persistsSharedCursor` and `runParameters` additions before it)|
 |Import paths (§4)|New module `data_sync/lib/start-controls.ts` exporting `resolveStartControlMap`, `applicableStartControls`, `StartControlMap`, `StartControlApplicability`, `DATA_SYNC_START_CONTROLS`|✓ ADDITIVE (new path; nothing moved or re-exported)|
 |API route URLs (§7)|`GET /api/data_sync/options` items gain a `startControls` object; `POST /api/data_sync/run` is unchanged and keeps honouring `fullSync` and `batchSize` whatever an adapter declares|✓ ADDITIVE (new optional response field, no request-shape change)|
 |Auto-discovery, function signatures, event IDs, widget spot IDs, DB schema, DI names, ACL features, notification IDs, CLI commands, generated files|No change|✓ n/a|
@@ -546,11 +544,11 @@ Clients use WebAuthn; operators audit key provenance, re-enroll with recovery. [
 |Type definitions (`CommandHandler`, `CommandRuntimeContext`, `CommandExecuteResult`)|New optional `atomicReplay?: boolean` and `stabilizeReplay(...)` handler capabilities, optional `replayTransactionGuard` request guard, optional caller-owned `transactionLifetime`, and optional `replaySourceFinalized?: boolean` result signal. `TransactionLifetime` plus its observation/completion-registration helpers are new exports; lifetime creation/completion remains owned by `withAtomicFlush`|✓ ADDITIVE (optional fields and exports; omitted handlers and contexts keep the prior flow)|
 |`ActionLogService` method signatures|`log`, `claimForUndo`, `releaseUndoClaim`, and `markUndone` accept an optional trailing transactional `EntityManager`; new `claimForRedo` method|✓ ADDITIVE (optional parameters appended and a new method; existing calls retain behavior)|
 |`RbacService`|New `loadAclWithEntityManager`, `userHasAllFeaturesWithEntityManager`, and `getGrantedFeaturesWithEntityManager` methods bypass caches and bind every query to the supplied transaction|✓ ADDITIVE (new methods; existing cache-backed methods are unchanged)|
-| Auth command replay behavior | Auth user/role handlers opt in so source-log state, domain changes, undo trace or new redo log, and redo source finalization commit or roll back together. Before the request guard or feature interceptors run, `stabilizeReplay` discovers and seals one actor/target/destination footprint and locks API keys, users, roles, tenant/organization hierarchy, and authorization children in a total order using the same transaction | ⚠️ Intentional security hardening. A race that previously could deadlock or replay with stale authority is rejected with the existing domain `409`; successful, authorized replay keeps the same response shape |
-| Action-log actor persistence and self replay | `actor_user_id` remains a UUID; new entries also store the canonical user or `api_key:<uuid>` subject in `context.actorSubject`. API-key list ownership, undo/redo ownership, exact-EM RBAC, locks, and latest replay queries use the canonical subject. Canonical history is selected before the legacy bare-UUID fallback, which additionally requires a coherent live `isApiKey`/`keyId`/`sub` tuple | ✓ Database-compatible additive context metadata; same-UUID user, malformed, or ambiguous ownership cannot shadow canonical key history and fails closed |
-| Auth authorization-state writers | First-party `UserRole`, `UserAcl`, and `RoleAcl` writers in commands, setup, CLI, execution principals, SSO, and agent orchestration now share the canonical parent-lock protocol; SSO membership and grant rows commit together | ⚠️ Intentional concurrency hardening; no request, response, schema, import-path, event, feature, or CLI contract changes |
-| Non-auth command replay | Handlers that omit `atomicReplay` retain the existing undo claim/release compensation and route-level redo finalization | ✓ Behavior-preserving |
-| API routes, response schemas, database schema, event IDs, ACL feature IDs, DI names, CLI commands, generated files | No shape or identifier change | ✓ n/a |
+|Auth command replay behavior|Auth user/role handlers opt in so source-log state, domain changes, undo trace or new redo log, and redo source finalization commit or roll back together. Before the request guard or feature interceptors run, `stabilizeReplay` discovers and seals one actor/target/destination footprint and locks API keys, users, roles, tenant/organization hierarchy, and authorization children in a total order using the same transaction|⚠️ Intentional security hardening. A race that previously could deadlock or replay with stale authority is rejected with the existing domain `409`; successful, authorized replay keeps the same response shape|
+|Action-log actor persistence and self replay|`actor_user_id` remains a UUID; new entries also store the canonical user or `api_key:<uuid>` subject in `context.actorSubject`. API-key list ownership, undo/redo ownership, exact-EM RBAC, locks, and latest replay queries use the canonical subject. Canonical history is selected before the legacy bare-UUID fallback, which additionally requires a coherent live `isApiKey`/`keyId`/`sub` tuple|✓ Database-compatible additive context metadata; same-UUID user, malformed, or ambiguous ownership cannot shadow canonical key history and fails closed|
+|Auth authorization-state writers|First-party `UserRole`, `UserAcl`, and `RoleAcl` writers in commands, setup, CLI, execution principals, SSO, and agent orchestration now share the canonical parent-lock protocol; SSO membership and grant rows commit together|⚠️ Intentional concurrency hardening; no request, response, schema, import-path, event, feature, or CLI contract changes|
+|Non-auth command replay|Handlers that omit `atomicReplay` retain the existing undo claim/release compensation and route-level redo finalization|✓ Behavior-preserving|
+|API routes, response schemas, database schema, event IDs, ACL feature IDs, DI names, CLI commands, generated files|No shape or identifier change|✓ n/a|
 
 **Migration path for existing modules**: none. Third-party commands remain on the established replay lifecycle unless they explicitly set `atomicReplay: true`. An opting-in handler must perform all replay database work through `ctx.transactionalEm`; when authorization depends on mutable domain rows it may add `stabilizeReplay` to acquire its complete footprint before guards and interceptors. The command bus supplies and owns the transaction by default. A caller deliberately composing replay inside an already-active `ctx.transactionalEm` must open that outer transaction with `withAtomicFlush(..., { transaction: true })`, obtain its exact `TransactionLifetime` inside the phase, and pass it as `ctx.transactionLifetime`; otherwise replay fails before mutation. Commit-only hooks and redo-finalization reporting follow the true outer completion. The capability does not claim that legacy non-opted-in action-log and domain writes are transactionally atomic.
 
@@ -560,11 +558,11 @@ Clients use WebAuthn; operators audit key provenance, re-enroll with recovery. [
 
 `directory.organizations.update` treated an omitted `parentId` as `null` and an omitted `childIds` as `[]`, so a partial update — notably `PUT /api/directory/organization-branding`, which sends only logo fields — detached the organization from its parent and orphaned its children. Omitted hierarchy fields are now preserved:
 
-| Surface | Change | Classification |
+|Surface|Change|Classification|
 |---|---|---|
-| Command behaviour (`directory.organizations.update`) | `parentId` is written and validated only when present in the input; children are reconciled only when `childIds` is present. Explicit `parentId: null` and `childIds: []` still clear. With `childIds` present and `parentId` omitted, listing the current parent answers `400 Child cannot equal parent` (it answered `400 Cannot assign ancestor as child`) | ⚠️ Behaviour change on a previously-corrupting path. A caller that omitted the fields to clear the hierarchy must send the explicit values. Regression-tested in `updateOrganization.partial-hierarchy.test.ts` and `TC-DIR-018` |
-| API routes (`PUT /api/directory/organizations`, `PUT /api/directory/organization-branding`) | Same URLs, request schema (`organizationUpdateSchema` already declares both fields optional) and response shapes | ✓ No shape change |
-| Database schema, event IDs, ACL features, DI names, CLI commands | No change | ✓ n/a |
+|Command behaviour (`directory.organizations.update`)|`parentId` is written and validated only when present in the input; children are reconciled only when `childIds` is present. Explicit `parentId: null` and `childIds: []` still clear. With `childIds` present and `parentId` omitted, listing the current parent answers `400 Child cannot equal parent` (it answered `400 Cannot assign ancestor as child`)|⚠️ Behaviour change on a previously-corrupting path. A caller that omitted the fields to clear the hierarchy must send the explicit values. Regression-tested in `updateOrganization.partial-hierarchy.test.ts` and `TC-DIR-018`|
+|API routes (`PUT /api/directory/organizations`, `PUT /api/directory/organization-branding`)|Same URLs, request schema (`organizationUpdateSchema` already declares both fields optional) and response shapes|✓ No shape change|
+|Database schema, event IDs, ACL features, DI names, CLI commands|No change|✓ n/a|
 
 **Migration path for existing modules**: send `parentId: null` / `childIds: []` where clearing is intended. Trees flattened before the upgrade are not repaired (see UPGRADE_NOTES.md).
 
@@ -574,12 +572,12 @@ Clients use WebAuthn; operators audit key provenance, re-enroll with recovery. [
 
 `POST /api/auth/logout` answered `401` before its handler ran once the access token expired, so the remember-me session was never revoked ([#7225](https://github.com/open-mercato/open-mercato/issues/7225)). It now declares `requireAuth: false`, like the portal logout:
 
-| Surface | Change | Classification |
+|Surface|Change|Classification|
 |---|---|---|
-| API route gating | `requireAuth` `true` → `false`; the handler revokes only the sessions its own cookies identify | ⚠️ Narrow relaxation: missing/unverifiable token or no cookie got `401`, now `307` (UPGRADE_NOTES.md) |
-| URL, method, response shape | Unchanged | ✓ n/a |
-| `auth.logout` event | Emitted only for a verified staff `auth_token` (now incl. MFA-pending); `session_token`-only revocation emits none | ✓ No ID or payload change |
-| Database schema, ACL features, DI names, CLI commands | No change | ✓ n/a |
+|API route gating|`requireAuth` `true` → `false`; the handler revokes only the sessions its own cookies identify|⚠️ Narrow relaxation: missing/unverifiable token or no cookie got `401`, now `307` (UPGRADE_NOTES.md)|
+|URL, method, response shape|Unchanged|✓ n/a|
+|`auth.logout` event|Emitted only for a verified staff `auth_token` (now incl. MFA-pending); `session_token`-only revocation emits none|✓ No ID or payload change|
+|Database schema, ACL features, DI names, CLI commands|No change|✓ n/a|
 
 **Migration path for existing modules**: none. A client that read a logout `401` as "already signed out" gets the redirect instead.
 
@@ -593,23 +591,23 @@ Clients use WebAuthn; operators audit key provenance, re-enroll with recovery. [
 
 [`.ai/specs/2026-10-01-oauth2-grant-lifecycle-core.md`](.ai/specs/2026-10-01-oauth2-grant-lifecycle-core.md) (parent: [`.ai/specs/2026-09-27-app-spec-oauth2-grant-lifecycle.md`](.ai/specs/2026-09-27-app-spec-oauth2-grant-lifecycle.md) §10.1) adds a tenant-level OAuth2 grant core to `integrations` that no existing integration uses yet. **All changes are additive** except the reserved `__oauth_grant` suffix, an intentional security narrowing that no first-party integration or bundle id hits. Developer guide: `apps/docs/docs/framework/modules/integrations-oauth-grants.mdx`.
 
-| Surface | Change | Classification |
+|Surface|Change|Classification|
 |---|---|---|
-| Import paths (§4) | New `@open-mercato/shared/lib/db/advisoryLock` (explicit `exports` entry); `@open-mercato/core/modules/integrations/lib/oauth/{token-endpoint,pkce,authorization,redirect,resource-challenge,descriptor,grant-service,health}` and `…/lib/oauth/testing/fakeAuthorizationServer` — exactly these files, no directory index. Every path, plus `…/lib/credentials-service`, `…/lib/log-service` and the hub's `…/communication_channels/lib/oauth-state`, is verified against the built `dist` by `scripts/check-oauth-publish-shape.mjs` in CI | ✓ ADDITIVE (new import paths) |
-| Type definitions (§2) | New `OAuthProviderDescriptor`, `OAuthGrantOwner`, `OAuthTokenEndpointResponse`, `OAuthClientAuthMethod`, the grant-service result and inspection types (the inspection carries no token), `AdvisoryLockOptions` (`waitDeadlineMs`, `maxConcurrentHolders`); the `FakeAuthorizationServer` handle with its options, `FakeInjection` and `FakeRotationMode`; error classes `OAuthGrantError`, `OAuthDescriptorError`, `AdvisoryLockUnavailableError` (`reason: AdvisoryLockUnavailableReason` = `'deadline' \| 'transient_db' \| 'commit_unknown'`); closed unions (`OAuthTokenFailure`, `OAuthConnectFailure`, `OAuthConnectionState`, `OAuthUnavailableReason`, …) that are additive-only, so consumers keep a default branch. `IntegrationOAuthGrantService` is a type to call, not to implement: adding a method is additive. Optional `IntegrationDetailPageConfig.connectTabId`. `CredentialsService`, `IntegrationLogService` and `IntegrationCredentialFieldOauth` are unchanged apart from `@internal` options | ✓ ADDITIVE (new types; optional fields) |
-| Function signatures (§3) | New `withAdvisoryXactLock`, `createPkcePair`, `buildAuthorizationUrl`, `exchangeAuthorizationCode`, `resolveOAuthRedirectUri`, `classifyResourceChallenge`, `mapInspectionToHealth` with `OAUTH_HEALTH_CODES`, `startFakeAuthorizationServer` with the methods of the handle it returns (`issueAuthorizationCode`, `inject`, `revokeAuthorization`, `reset`, `counters`, `requests`, `issuedTokens`, `close`) and the `IntegrationOAuthGrantService` methods | ✓ ADDITIVE (new functions) |
-| DI service names (§9) | New scoped `integrationOAuthGrantService`. Contract note: inside the grant lock the service builds its credentials and log services from the core factories, so DI overrides of `integrationCredentialsService` don't apply to grant rows | ✓ ADDITIVE |
-| API routes (§7) | `GET /api/integrations/:id` gains the nullable `oauthGrant: { status: 'active' \| 'invalidated' \| 'unavailable' } \| null` (always present; `null` without a live grant) and returns `integration.detailPage.connectTabId` | ✓ ADDITIVE (response fields) |
-| Widget injection context (§6) | Spot IDs unchanged; the `integrations.detail.v1` context gains the optional `detail.oauthGrant` and `integration.detailPage.connectTabId` | ✓ ADDITIVE (context fields) |
-| Log and health codes | Log codes `integrations.oauth_*` and the `OAUTH_HEALTH_CODES` values with `OAuthHealthCode` | ✓ ADDITIVE; STABLE once released, additive-only |
-| Persisted formats | The grant row id `<integrationId>__oauth_grant`; the blob `version`; the lock key `oauth_grant:<integrationId>:<tenantId>:<organizationId>:<userId or ->` and its mapping `pg_try_advisory_xact_lock(hashtextextended(key, 0))`; `resourceKind` `integrations.oauth_grant`; the `Symbol.for` brands `@open-mercato/shared:AdvisoryLockUnavailableError`, `@open-mercato/core:OAuthGrantError` and `@open-mercato/core:OAuthDescriptorError` that keep `instanceof` reliable across module copies. The codes `integrations.oauth_disconnected` and `integrations.oauth_revocation_{pending,confirmed,failed,unsupported,skipped_reconnected,skipped_invalidated}` with their `disconnectId` payload key are read back to derive `lastDisconnect`; the per-process holder-slot registry `globalThis.__openMercatoAdvisoryLockSlots__` is shared by every `@open-mercato/shared` instance | The lock key, its mapping and the brand keys FROZEN for every existing Grant Owner (processes of two versions must exclude each other during a rolling deploy); everything else ADDITIVE-ONLY |
-| External dependency | Provider routes import the hub-owned `@open-mercato/core/modules/communication_channels/lib/oauth-state`: `createOAuthState`, `verifyOAuthState`, `consumeOAuthStateOnce`, `OAuthStatePayload`, `OAuthStateConsumeStore` and `OAuthStateError` (its `code` values additive-only, `replay` included) are documented as STABLE; the path's other exports are not covered | ✓ No change to the path (now a documented STABLE import) |
-| Testing contract | With `OM_ENABLE_TEST_OAUTH_GRANTS` on (or outside production), a descriptor may use `http:` endpoints on a loopback host (`localhost`, `127.0.0.1`, `[::1]`), so a provider's test seam can point its descriptor at an in-process fake; otherwise endpoints are `https:` | STABLE; the flag itself enables nothing else for providers |
-| API routes (§7): `GET` / `PUT /api/integrations/:id/credentials` | Answer 404 for any id ending in `__oauth_grant`, also when an integration with that id is registered (I4: grant secrets never reach the admin credentials API) | ⚠️ Intentional security narrowing only (no first-party integration id ends in the suffix) |
-| Function behaviour (§3, §9): `resolve()` and `resolveUpdatedAt()` of `createCredentialsService` / DI `integrationCredentialsService` | Don't fall through to a `bundleId` ending in `__oauth_grant`, for every caller (integration list and detail GETs, the credentials route, the health service, data_sync); the grant service's Client Configuration read skips it too | ⚠️ Intentional security narrowing only (I4, I7; no first-party bundle id ends in the suffix) |
-| Explicitly not covered (`@internal`) | `createIntegrationOAuthGrantService`, `IntegrationOAuthGrantServiceDeps`, `requestTokenEndpoint`, `revokeToken`, `OAuthTokenEndpointError` with `OAuthTokenEndpointErrorKind` and its brand, `OAUTH_RESPONSE_MAX_BYTES`, `OAuthClientCredentials`, `OAuthInvalidatedReason`, `oauthProviderDescriptorSchema`, `resolveOAuthProviderDescriptor`, `AdvisoryLockOptions.onWait` with `AdvisoryLockWaitResult`, `isTransientLockDbError` (`@open-mercato/shared/lib/db/pg-errors`), the third parameter `{ kms }` of `createCredentialsService`, `CredentialsWriteOptions.ensureEncryptionMap`, `eraseIntegrationCredentials`, `readCredentialRowLayered`, `LayeredCredentialRead`, `isReservedOAuthGrantId`, `bundleFallthroughId`, `findLatestIntegrationLogsByCodes`, and every export of `lib/oauth/{grant-blob,pin-tenant-dek,error-brand}` | Not a contract surface; may change without the deprecation protocol |
-| Not contracts | The test-only route `POST /api/integrations/test-oauth-grants`, its helper `@open-mercato/core/helpers/integration/oauthGrantTestRoute`, the flag `OM_ENABLE_TEST_OAUTH_GRANTS` (apart from the testing contract above) and the `test_oauth_grant` integration (like `test-seed`) | n/a |
-| Event IDs, database schema, ACL features, notification types, AI agent and tool IDs, CLI commands | No change | ✓ n/a |
+|Import paths (§4)|New `@open-mercato/shared/lib/db/advisoryLock` (explicit `exports` entry); `@open-mercato/core/modules/integrations/lib/oauth/{token-endpoint,pkce,authorization,redirect,resource-challenge,descriptor,grant-service,health}` and `…/lib/oauth/testing/fakeAuthorizationServer` — exactly these files, no directory index. Every path, plus `…/lib/credentials-service`, `…/lib/log-service` and the hub's `…/communication_channels/lib/oauth-state`, is verified against the built `dist` by `scripts/check-oauth-publish-shape.mjs` in CI|✓ ADDITIVE (new import paths)|
+|Type definitions (§2)|New `OAuthProviderDescriptor`, `OAuthGrantOwner`, `OAuthTokenEndpointResponse`, `OAuthClientAuthMethod`, the grant-service result and inspection types (the inspection carries no token), `AdvisoryLockOptions` (`waitDeadlineMs`, `maxConcurrentHolders`); the `FakeAuthorizationServer` handle with its options, `FakeInjection` and `FakeRotationMode`; error classes `OAuthGrantError`, `OAuthDescriptorError`, `AdvisoryLockUnavailableError` (`reason: AdvisoryLockUnavailableReason` = `'deadline' \|'transient_db' \|'commit_unknown'`); closed unions (`OAuthTokenFailure`, `OAuthConnectFailure`, `OAuthConnectionState`, `OAuthUnavailableReason`, …) that are additive-only, so consumers keep a default branch. `IntegrationOAuthGrantService` is a type to call, not to implement: adding a method is additive. Optional `IntegrationDetailPageConfig.connectTabId`. `CredentialsService`, `IntegrationLogService` and `IntegrationCredentialFieldOauth` are unchanged apart from `@internal` options|✓ ADDITIVE (new types; optional fields)|
+|Function signatures (§3)|New `withAdvisoryXactLock`, `createPkcePair`, `buildAuthorizationUrl`, `exchangeAuthorizationCode`, `resolveOAuthRedirectUri`, `classifyResourceChallenge`, `mapInspectionToHealth` with `OAUTH_HEALTH_CODES`, `startFakeAuthorizationServer` with the methods of the handle it returns (`issueAuthorizationCode`, `inject`, `revokeAuthorization`, `reset`, `counters`, `requests`, `issuedTokens`, `close`) and the `IntegrationOAuthGrantService` methods|✓ ADDITIVE (new functions)|
+|DI service names (§9)|New scoped `integrationOAuthGrantService`. Contract note: inside the grant lock the service builds its credentials and log services from the core factories, so DI overrides of `integrationCredentialsService` don't apply to grant rows|✓ ADDITIVE|
+|API routes (§7)|`GET /api/integrations/:id` gains the nullable `oauthGrant: { status: 'active' \|'invalidated' \|'unavailable' } \|null` (always present; `null` without a live grant) and returns `integration.detailPage.connectTabId`|✓ ADDITIVE (response fields)|
+|Widget injection context (§6)|Spot IDs unchanged; the `integrations.detail.v1` context gains the optional `detail.oauthGrant` and `integration.detailPage.connectTabId`|✓ ADDITIVE (context fields)|
+|Log and health codes|Log codes `integrations.oauth_*` and the `OAUTH_HEALTH_CODES` values with `OAuthHealthCode`|✓ ADDITIVE; STABLE once released, additive-only|
+|Persisted formats|The grant row id `<integrationId>__oauth_grant`; the blob `version`; the lock key `oauth_grant:<integrationId>:<tenantId>:<organizationId>:<userId or ->` and its mapping `pg_try_advisory_xact_lock(hashtextextended(key, 0))`; `resourceKind` `integrations.oauth_grant`; the `Symbol.for` brands `@open-mercato/shared:AdvisoryLockUnavailableError`, `@open-mercato/core:OAuthGrantError` and `@open-mercato/core:OAuthDescriptorError` that keep `instanceof` reliable across module copies. The codes `integrations.oauth_disconnected` and `integrations.oauth_revocation_{pending,confirmed,failed,unsupported,skipped_reconnected,skipped_invalidated}` with their `disconnectId` payload key are read back to derive `lastDisconnect`; the per-process holder-slot registry `globalThis.__openMercatoAdvisoryLockSlots__` is shared by every `@open-mercato/shared` instance|The lock key, its mapping and the brand keys FROZEN for every existing Grant Owner (processes of two versions must exclude each other during a rolling deploy); everything else ADDITIVE-ONLY|
+|External dependency|Provider routes import the hub-owned `@open-mercato/core/modules/communication_channels/lib/oauth-state`: `createOAuthState`, `verifyOAuthState`, `consumeOAuthStateOnce`, `OAuthStatePayload`, `OAuthStateConsumeStore` and `OAuthStateError` (its `code` values additive-only, `replay` included) are documented as STABLE; the path's other exports are not covered|✓ No change to the path (now a documented STABLE import)|
+|Testing contract|With `OM_ENABLE_TEST_OAUTH_GRANTS` on (or outside production), a descriptor may use `http:` endpoints on a loopback host (`localhost`, `127.0.0.1`, `[::1]`), so a provider's test seam can point its descriptor at an in-process fake; otherwise endpoints are `https:`|STABLE; the flag itself enables nothing else for providers|
+|API routes (§7): `GET` / `PUT /api/integrations/:id/credentials`|Answer 404 for any id ending in `__oauth_grant`, also when an integration with that id is registered (I4: grant secrets never reach the admin credentials API)|⚠️ Intentional security narrowing only (no first-party integration id ends in the suffix)|
+|Function behaviour (§3, §9): `resolve()` and `resolveUpdatedAt()` of `createCredentialsService` / DI `integrationCredentialsService`|Don't fall through to a `bundleId` ending in `__oauth_grant`, for every caller (integration list and detail GETs, the credentials route, the health service, data_sync); the grant service's Client Configuration read skips it too|⚠️ Intentional security narrowing only (I4, I7; no first-party bundle id ends in the suffix)|
+|Explicitly not covered (`@internal`)|`createIntegrationOAuthGrantService`, `IntegrationOAuthGrantServiceDeps`, `requestTokenEndpoint`, `revokeToken`, `OAuthTokenEndpointError` with `OAuthTokenEndpointErrorKind` and its brand, `OAUTH_RESPONSE_MAX_BYTES`, `OAuthClientCredentials`, `OAuthInvalidatedReason`, `oauthProviderDescriptorSchema`, `resolveOAuthProviderDescriptor`, `AdvisoryLockOptions.onWait` with `AdvisoryLockWaitResult`, `isTransientLockDbError` (`@open-mercato/shared/lib/db/pg-errors`), the third parameter `{ kms }` of `createCredentialsService`, `CredentialsWriteOptions.ensureEncryptionMap`, `eraseIntegrationCredentials`, `readCredentialRowLayered`, `LayeredCredentialRead`, `isReservedOAuthGrantId`, `bundleFallthroughId`, `findLatestIntegrationLogsByCodes`, and every export of `lib/oauth/{grant-blob,pin-tenant-dek,error-brand}`|Not a contract surface; may change without the deprecation protocol|
+|Not contracts|The test-only route `POST /api/integrations/test-oauth-grants`, its helper `@open-mercato/core/helpers/integration/oauthGrantTestRoute`, the flag `OM_ENABLE_TEST_OAUTH_GRANTS` (apart from the testing contract above) and the `test_oauth_grant` integration (like `test-seed`)|n/a|
+|Event IDs, database schema, ACL features, notification types, AI agent and tool IDs, CLI commands|No change|✓ n/a|
 
 **Migration path for existing modules**: none for first-party code. Third-party modules must not register an integration or bundle id that ends in `__oauth_grant` (see `UPGRADE_NOTES.md`).
 
@@ -632,3 +630,7 @@ STABLE API §7: `GET /api/checkout/pay/:slug` omits admin fields; retaining them
 ## #3805 2026-10-31
 
 STABLE tools/execute writes bypass approval; no bridge. [Migrate](UPGRADE_NOTES.md#issue-3805)
+
+## SCIM rate limiting (2026-10-27)
+
+SCIM adds 429/503 before credentials; honor Retry-After. Optional `beforeAuth: ApiRouteBeforeAuth` is additive. See [contract and migration](.ai/specs/enterprise/implemented/SPEC-ENT-004-2026-02-19-sso-directory-sync.md#migration--backward-compatibility).

package/dist/agentic/guides/upstream/manifest.json

@@ -1,8 +1,8 @@
 {
   "version": 1,
-  "generator": "@open-mercato/cli@0.10.1-develop.7811.1.66050c1838",
+  "generator": "@open-mercato/cli@0.10.1-develop.7813.1.83931e7add",
   "files": {
     "AGENTS.md": "b27342ee5f61e805ba52703fdb7ec822b030490f734b4d80f48dfd1e05fa4cf5",
-    "BACKWARD_COMPATIBILITY.md": "e4b53767506d7ff4628c6cc7e38956792b32eb606749f8f4ba3f67dd2c9e86da"
+    "BACKWARD_COMPATIBILITY.md": "ffcf62846c1d7ab3238979c4915203fd13ee183c6b5064b10bd397142d1b2683"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/cli",
-  "version": "0.10.1-develop.7811.1.66050c1838",
+  "version": "0.10.1-develop.7813.1.83931e7add",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -60,10 +60,10 @@
     "@mikro-orm/decorators": "^7.1.14",
     "@mikro-orm/migrations": "^7.1.14",
     "@mikro-orm/postgresql": "^7.1.14",
-    "@open-mercato/events": "0.10.1-develop.7811.1.66050c1838",
-    "@open-mercato/queue": "0.10.1-develop.7811.1.66050c1838",
-    "@open-mercato/shared": "0.10.1-develop.7811.1.66050c1838",
-    "@open-mercato/telemetry": "0.10.1-develop.7811.1.66050c1838",
+    "@open-mercato/events": "0.10.1-develop.7813.1.83931e7add",
+    "@open-mercato/queue": "0.10.1-develop.7813.1.83931e7add",
+    "@open-mercato/shared": "0.10.1-develop.7813.1.83931e7add",
+    "@open-mercato/telemetry": "0.10.1-develop.7813.1.83931e7add",
     "cross-spawn": "^7.0.6",
     "minisearch": "7.2.0",
     "pg": "8.23.0",
@@ -75,10 +75,10 @@
     "typescript-js": "npm:typescript@6.0.3"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.10.1-develop.7811.1.66050c1838"
+    "@open-mercato/shared": "0.10.1-develop.7813.1.83931e7add"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.10.1-develop.7811.1.66050c1838",
+    "@open-mercato/shared": "0.10.1-develop.7813.1.83931e7add",
     "@types/jest": "^30.0.0",
     "jest": "^30.4.2",
     "ts-jest": "^29.4.12"