@open-mercato/cli 0.6.7-develop.6862.1.c11a64ce0a → 0.6.7

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

@@ -1,316 +0,0 @@
-# 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.
-
-## Deprecation Protocol
-
-1. **Never remove or rename** a public contract surface in a single release.
-2. **Deprecate first**: add `@deprecated` JSDoc with migration guidance and the target removal version.
-3. **Provide a bridge**: re-export the old name/path, accept the old signature, or keep the old behavior alongside the new one for at least one minor version.
-4. **Document in UPGRADE_NOTES.md**: every deprecation and every removal must be listed with migration instructions.
-5. **Spec requirement**: any PR that modifies a contract surface MUST reference a spec (in `.ai/specs/`) that includes a "Migration & Backward Compatibility" section.
-
----
-
-## Contract Surface Categories
-
-### 1. Auto-Discovery File Conventions (FROZEN)
-
-The following file names, their expected export names, and their role in module auto-discovery MUST NOT change. New convention files may be added, but existing ones are immutable.
-
-| Convention File | Required Export | Contract |
-|-----------------|---------------|----------|
-| `index.ts` | `metadata: ModuleInfo` | MUST NOT rename export or change `ModuleInfo` shape in a breaking way |
-| `acl.ts` | `features: Array<{id,title,module}>` | MUST NOT change array item shape; may add optional fields |
-| `setup.ts` | `setup: ModuleSetupConfig` | MUST NOT remove hooks (`onTenantCreated`, `seedDefaults`, `seedExamples`, `defaultRoleFeatures`); may add optional hooks |
-| `ce.ts` | `entities: CustomEntitySpec[]` | MUST NOT change `CustomEntitySpec` required fields; may add optional fields |
-| `search.ts` | `searchConfig: SearchModuleConfig` | MUST NOT change `SearchEntityConfig` required fields; may add optional fields |
-| `events.ts` | `eventsConfig` via `createModuleEvents()` | MUST NOT change `EventDefinition` required fields (`id`, `label`); may add optional fields |
-| `extension-points.ts` | `extensionPoints: ModuleExtensionPoints` | New additive convention; declared exact/pattern host IDs, aliases, fallbacks, family/capability semantics, and bound call-site meaning MUST NOT change incompatibly |
-| `translations.ts` | `translatableFields` | MUST NOT change record shape |
-| `notifications.ts` | `notificationTypes: NotificationTypeDefinition[]` | MUST NOT change required fields; may add optional fields |
-| `notifications.client.ts` | — | MUST NOT change renderer props contract |
-| `ai-agents.ts` | `aiAgents: AiAgentDefinition[]` | MUST NOT change `AiAgentDefinition` required fields; optional sibling exports `aiAgentOverrides` and `aiAgentExtensions` are stable |
-| `ai-tools.ts` | `aiTools: AiToolDefinition[]` | MUST NOT change `AiToolDefinition` / inherited `McpToolDefinition` required fields; optional sibling export `aiToolOverrides` is stable |
-| `di.ts` | `register(container)` | MUST NOT change function signature |
-| `cli.ts` | default export | MUST NOT change expected signature |
-| `data/entities.ts` | Entity class exports | See Database Schema rules below |
-| `data/validators.ts` | Zod schema exports | MUST NOT remove or narrow existing schemas |
-| `data/extensions.ts` | `extensions: EntityExtension[]` | MUST NOT change `EntityExtension` shape |
-| `widgets/injection-table.ts` | `ModuleInjectionTable` | MUST NOT change table type or spot ID resolution |
-| `widgets/injection/*/widget.ts` | `InjectionWidgetModule` | MUST NOT change module shape or component props |
-| `widgets/dashboard/*/widget.ts` | `DashboardWidgetModule` | MUST NOT change module shape or component props |
-
-**Auto-discovery directory conventions** (FROZEN):
-
-| Directory Pattern | Route Mapping | Contract |
-|-------------------|--------------|----------|
-| `frontend/<path>.tsx` | `/<path>` | MUST NOT change routing algorithm |
-| `backend/<path>.tsx` | `/backend/<path>` | MUST NOT change routing algorithm |
-| `api/<method>/<path>.ts` | `/api/<path>` by HTTP method | MUST NOT change dispatch logic |
-| `subscribers/*.ts` | Event handler auto-registered | MUST NOT change metadata shape `{event, persistent?, id?}` |
-| `workers/*.ts` | Queue worker auto-registered | MUST NOT change metadata shape `{queue, id?, concurrency?}` |
-
-### 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.
-
-**Immutable required fields** (removing or renaming any is a breaking change):
-
-- `Module`: `id`, `info`, `backendRoutes`, `frontendRoutes`, `apis`, `subscribers`, `workers`, `setup`
-- `ModuleInfo`: `name` (all fields are optional today — keep them optional)
-- `PageMetadata`: all fields remain optional; MUST NOT remove any existing field
-- `ModuleSetupConfig`: `onTenantCreated`, `seedDefaults`, `seedExamples`, `defaultRoleFeatures` — MUST NOT remove
-- `EventDefinition`: `id`, `label` — MUST NOT remove; `category`, `module`, `entity`, `description` — MUST NOT remove
-- `EventPayload`: `id`, `tenantId`, `organizationId` — MUST NOT remove
-- `EntityExtension`: `base`, `extension`, `join` — MUST NOT remove
-- `ModuleExtensionPoints`: `moduleId`, `hosts` — MUST NOT remove; host declaration discriminants and exact/pattern address semantics are STABLE, and new optional metadata/capabilities may be added
-- `ModuleExtensionSurfaceFacts`: `hosts`, `contributions`, `unresolved` — MUST NOT remove; host IDs/patterns, contribution identities/targets, resolution classes, activation/phases/operations, scope contracts, round-trip IDs, override identities, and sanitized unresolved provenance MUST retain their meaning
-- `CustomFieldDefinition`: `key`, `kind` — MUST NOT remove; all other fields remain optional
-- `CustomEntitySpec`: `id` — MUST NOT remove
-- `InjectionWidgetMetadata`: `id`, `title` — MUST NOT remove
-- `InjectionWidgetComponentProps`: `context`, `data`, `onDataChange`, `disabled` — MUST NOT remove
-- `WidgetInjectionEventHandlers`: all existing handler names (`onLoad`, `onBeforeSave`, `onSave`, `onAfterSave`, `onBeforeDelete`, `onDelete`, `onAfterDelete`, `onDeleteError`) — MUST NOT remove or change signatures
-- `SearchModuleConfig`: `entities` — MUST NOT remove; `SearchEntityConfig.entityId` — MUST NOT remove
-- `NotificationTypeDefinition`: `type`, `module`, `titleKey`, `icon`, `severity`, `actions` — MUST NOT remove
-- `DashboardWidgetMetadata`: `id`, `title` — MUST NOT remove
-- `DashboardWidgetComponentProps`: `mode`, `layout`, `settings`, `context`, `onSettingsChange`, `refreshToken` — MUST NOT remove
-- `OpenApiRouteDoc`: `methods` — MUST NOT remove
-- `McpToolDefinition`: `name`, `description`, `inputSchema`, `handler` — MUST NOT remove
-- `AiToolDefinition`: inherited `McpToolDefinition` fields (`name`, `description`, `inputSchema`, `handler`) — MUST NOT remove; `requiredFeatures` remains optional for legacy/plain-object compatibility; `isMutation`, `isBulk`, `isDestructive`, `loadBeforeRecord`, `loadBeforeRecords`, `maxCallsPerTurn`, and `supportsAttachments` remain optional
-- `AiAgentDefinition`: `id`, `moduleId`, `label`, `description`, `systemPrompt`, `allowedTools` — MUST NOT remove; optional fields (`suggestions`, `executionMode`, `defaultModel`, `acceptedMediaTypes`, `requiredFeatures`, `uiParts`, `readOnly`, `mutationPolicy`, `maxSteps`, `output`, `resolvePageContext`, `keywords`, `domain`, `dataCapabilities`) MAY be extended but MUST NOT be narrowed
-- `AiAgentExtension`: `targetAgentId` — MUST NOT remove; patch fields (`replaceAllowedTools`, `deleteAllowedTools`, `appendAllowedTools`, `replaceSystemPrompt`, `appendSystemPrompt`, `replaceSuggestions`, `deleteSuggestions`, `appendSuggestions`) MUST keep their existing meaning; deprecated `suggestions` remains an append alias until removed through the deprecation protocol
-- `AiAgentOverridesMap` / `AiToolOverridesMap`: `Record<string, AiAgentDefinition | null>` and `Record<string, AiToolDefinition | null>` semantics are STABLE; `null` means disable
-- `ModuleOverrides`: `overrides.ai.agents`, `overrides.ai.tools`, and `overrides.ai.extensions` shapes are STABLE; other domain keys are reserved by the unified override contract and may be wired additively. `nav` was wired 2026-07-30 under that clause (see [spec](.ai/specs/2026-07-30-nav-group-order-override-domain.md)): `overrides.nav.groupOrder` **prepends** sidebar nav group ids ahead of the built-in `defaultGroupOrder`, and ids it does not name keep their existing position. It is a default applied *beneath* role and per-user sidebar preferences, so an operator's own arrangement still wins. With no override configured, group ordering is byte-identical to before — that guarantee MUST hold for any future change to this domain.
-- `WorkerMeta`: `queue` — MUST NOT remove
-- `RefreshCredentialsInput` (communication_channels hub): `channelId`, `credentials`, `scope` — MUST NOT remove. `oauthClient?` was added 2026-05-27 as an additive optional field (see [Spec A](.ai/specs/implemented/2026-05-27-email-integration-inbound-reliability-and-threading.md)). The legacy `credentials._client` read path in the Gmail adapter is **deprecated and slated for removal in the next minor release** — pass OAuth client config via `RefreshCredentialsInput.oauthClient` instead.
-- `OAuthClientConfig` (communication_channels hub): added 2026-05-27 with `clientId` required; optional `clientSecret`, `tenantId`, `scopes`. New optional fields may be added; required `clientId` MUST NOT be removed.
-- `BackendChromePayload`: `groups`, `settingsSections`, `settingsPathPrefixes`, `profileSections`, `profilePathPrefixes`, `grantedFeatures`, `roles` — MUST NOT remove. `currentOrganization?` (`BackendChromeCurrentOrganization | null`) was added 2026-07-30 as an additive optional field (see [spec](.ai/specs/2026-07-30-backend-chrome-current-organization.md)); it is `null` under an all-organizations selection, when no organization is in scope, and when the lookup fails, so consumers MUST treat `null` as "unknown" rather than "no organization". `brand?` is **unchanged** and remains the branding channel — it populates only when the organization has a `logoUrl`, and `currentOrganization` does not supersede it.
-
-**STABLE field shape, changed value semantics in 0.6.8:** each entry in `BackendChromePayload.settingsSections` keeps its `id`, `label`, `labelKey`, `order`, and `items` fields, but `id` is now the section's **untranslated group id** (the page's `pageGroupKey`, e.g. `settings.sections.moduleConfigs`) instead of a slug of the rendered group label. The old value was locale-dependent, so it could not be targeted reliably (see [#4843](https://github.com/open-mercato/open-mercato/issues/4843)). Consumers matching a settings section — notably injected `menuItems[].groupId` — MUST use the group id, which is the form the widget-injection documentation already prescribes. `buildSettingsSections`' `sectionOrder` parameter keeps a deprecated fallback lookup on the old label slug for at least one minor release.
-
-### 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.
-
-| Function | Package | Contract |
-|----------|---------|----------|
-| `createModuleEvents(options)` | `@open-mercato/shared/modules/events` | MUST NOT change `options` required shape or return type |
-| `makeCrudRoute(opts)` | `@open-mercato/shared/lib/crud/factory` | MUST NOT remove existing `opts` fields; MUST NOT change return shape |
-| `findWithDecryption(em, entityName, where, options?, scope?)` | `@open-mercato/shared/lib/encryption/find` | MUST NOT change parameter order or required params |
-| `findOneWithDecryption(...)` | `@open-mercato/shared/lib/encryption/find` | Same as above |
-| `findAndCountWithDecryption(...)` | `@open-mercato/shared/lib/encryption/find` | Same as above |
-| `entityId(moduleId, entity)` | `@open-mercato/shared/modules/dsl` | MUST NOT change |
-| `defineLink(base, extension, opts)` | `@open-mercato/shared/modules/dsl` | MUST NOT change |
-| `defineModuleExtensionPoints(declaration)` | `@open-mercato/shared/modules/widgets/extension-points` | MUST preserve immutable data-only declaration semantics and exact module/host values |
-| `injectionExtensionHost`, `dataTableExtensionHost`, `crudFormExtensionHost`, `componentExtensionHost` | `@open-mercato/shared/modules/widgets/extension-points` | MUST preserve family discrimination, exact/pattern validation, and returned IDs |
-| `defineFields(entity, fields, source?)` | `@open-mercato/shared/modules/dsl` | MUST NOT change |
-| `cf.text`, `cf.multiline`, `cf.integer`, `cf.float`, `cf.boolean`, `cf.select`, `cf.currency`, `cf.dictionary` | `@open-mercato/shared/modules/dsl` | MUST NOT remove any helper or change required params |
-| `lazyDashboardWidget(loader)` | `@open-mercato/shared/modules/dashboard/widgets` | MUST NOT change |
-| `registerMcpTool(tool, options?)` | `@open-mercato/ai-assistant` | MUST NOT change |
-| `defineAiAgent(definition)` | `@open-mercato/ai-assistant` | MUST NOT change parameter or return shape |
-| `defineAiAgentExtension(extension)` | `@open-mercato/ai-assistant` | MUST NOT change parameter or return shape |
-| `defineAiTool(definition)` | `@open-mercato/ai-assistant` | MUST NOT change parameter or return shape |
-| `applyAiAgentOverrides(overrides)` | `@open-mercato/ai-assistant` | MUST preserve map semantics and precedence |
-| `applyAiToolOverrides(overrides)` | `@open-mercato/ai-assistant` | MUST preserve map semantics and precedence |
-| `applyAiAgentExtensions(extensions)` | `@open-mercato/ai-assistant` | MUST preserve append/patch semantics |
-| `applyAiOverridesFromEnabledModules(modules)` | `@open-mercato/ai-assistant` | MUST keep accepting the `overrides.ai` module-entry shape |
-| `prepareMutation(input, context)` | `@open-mercato/ai-assistant` | MUST NOT bypass pending-action approval semantics or change required params |
-| `runAiAgentText(input)` / `runAiAgentObject(input)` | `@open-mercato/ai-assistant` | MUST NOT remove existing input fields or narrow output shape |
-| `applyModuleOverridesFromEnabledModules(modules)` | `@open-mercato/shared/modules/overrides` | MUST keep dispatching `entry.overrides.<domain>` by module-load order |
-| `registerModuleOverrideApplier(domain, applier)` | `@open-mercato/shared/modules/overrides` | MUST NOT change registration semantics |
-| `apiCall` / `apiCallOrThrow` / `readApiResultOrThrow` | `@open-mercato/ui/backend/utils/apiCall` | MUST NOT change |
-| `useT()` | `@open-mercato/shared/lib/i18n/context` | MUST NOT change return type |
-| `resolveTranslations()` | `@open-mercato/shared/lib/i18n/server` | MUST NOT change |
-| `createCrudOpenApiFactory(config)` | `@open-mercato/shared/lib/openapi/crud` | MUST NOT change |
-| `collectCustomFieldValues()` | `@open-mercato/ui/backend/utils/customFieldValues` | MUST NOT change |
-| `flash()` | `@open-mercato/ui` | MUST NOT change |
-| `CrudForm` component props | `@open-mercato/ui/backend/crud` | MUST NOT remove existing props |
-| `DataTable` component props | `@open-mercato/ui/backend` | MUST NOT remove existing props |
-| `parseBooleanToken` / `parseBooleanWithDefault` | `@open-mercato/shared/lib/boolean` | MUST NOT change |
-
-### 4. Import Paths (STABLE)
-
-All documented import paths in the "When You Need an Import" table and in package AGENTS.md files are public API. If a module is moved internally, the old import path MUST be re-exported for backward compatibility with a `@deprecated` annotation.
-
-### 5. Event IDs (FROZEN)
-
-Published event IDs (declared in any module's `events.ts`) are consumed by subscribers in other modules and by workflow triggers. Changing an event ID is a **breaking change**.
-
-- MUST NOT rename an existing event ID
-- MUST NOT remove an existing event ID
-- MUST NOT change an event's payload shape in a way that removes existing fields
-- MAY add new optional fields to event payloads
-- MAY add new event IDs freely
-- To retire an event: deprecate it, emit both old and new IDs during the bridge period, then remove after one minor version
-
-### 6. Widget Injection Spot IDs (FROZEN)
-
-Spot IDs are the addresses where external modules inject UI. Renaming or removing a spot ID silently breaks all modules targeting it.
-
-- MUST NOT rename an existing spot ID (e.g., `crud-form:catalog.product`, `sales.document.detail.order:tabs`, `backend:record:current`)
-- MUST NOT remove an existing spot ID from a page
-- MUST NOT change the context/data type passed to widgets at existing spots
-- MAY add new spot IDs to new or existing pages
-- MAY add new optional context fields to existing spots
-- Wildcard spots (`crud-form:*`, `data-table:*`) MUST continue to match as documented
-
-### 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
-- MAY add new optional fields to request/response schemas
-- MAY add new API routes freely
-- To retire a route: deprecate with `deprecated: true` in `openApi`, keep it functional for at least one minor version, then remove
-
-### 8. Database Schema (ADDITIVE-ONLY)
-
-Module developers create entities and run migrations. Core schema changes can break their data.
-
-- MUST NOT rename existing tables or columns
-- MUST NOT remove existing columns (use soft-deprecation: stop writing, keep column)
-- MUST NOT change column types in a narrowing way (e.g., `text` → `varchar(50)`)
-- MUST NOT remove or rename indexes that modules may depend on
-- MUST NOT change the standard column contract (`id`, `created_at`, `updated_at`, `deleted_at`, `is_active`, `organization_id`, `tenant_id`)
-- MAY add new columns with defaults (non-breaking)
-- MAY add new tables freely
-- MAY add new indexes freely
-- MAY widen column types (e.g., `varchar(100)` → `text`)
-- Foreign key column names on core entities (e.g., `organization_id`, `tenant_id`) are frozen
-
-### 9. DI Service Names (STABLE)
-
-Module code resolves services by name from the Awilix container. Renaming a DI registration breaks all resolvers.
-
-- MUST NOT rename existing DI service registration keys
-- MUST NOT change the interface of a resolved service in a breaking way
-- MAY add new DI registrations freely
-- MAY add optional methods to existing service interfaces
-
-### 10. ACL Feature IDs (FROZEN)
-
-Feature IDs are stored in database role configurations. Renaming a feature ID orphans existing role assignments.
-
-- MUST NOT rename an existing feature ID
-- MUST NOT remove an existing feature ID without a data migration that updates all stored role configs
-- MAY add new feature IDs freely
-- App-level `entry.overrides.acl.features[id] = null` is the supported reversible exception: stored grants are preserved but runtime-inert while the override is effective.
-
-**STABLE capability-field shape, changed value semantics in 0.6.6:** `BackendChromePayload.grantedFeatures` and customer portal `resolvedFeatures` remain `string[]`, but now contain concrete effective feature IDs. They no longer expose `*` or namespace wildcard strings. Consumers MUST check concrete IDs and MUST NOT infer staff/portal admin status from a wildcard; use the explicit admin boolean where exposed.
-
-### 11. Notification Type IDs (FROZEN)
-
-Notification types are referenced by subscribers, stored in database records, and rendered by client-side renderers.
-
-- MUST NOT rename a `type` string on `NotificationTypeDefinition`
-- MUST NOT remove an existing notification type
-- MAY add new notification types freely
-
-### 12. AI Agent, Tool, UI Part, and Override IDs (FROZEN / STABLE)
-
-AI framework registries are public extension points. Published IDs are referenced by module code, generated registries, app-level overrides, tenant prompt/policy overrides, launcher UI, and `allowedTools` arrays.
-
-**FROZEN IDs:**
-
-- MUST NOT rename an existing `AiAgentDefinition.id`
-- MUST NOT rename an existing `AiToolDefinition.name`
-- MUST NOT rename an existing AI UI part `componentId`
-- MUST NOT rename reserved AI UI part IDs (`mutation-preview-card`, `field-diff-card`, `confirmation-card`, `mutation-result-card`)
-- MUST NOT change the meaning of `null` in `AiAgentOverridesMap` / `AiToolOverridesMap`; it always means "disable this agent/tool"
-- MUST NOT change the meaning of `AiAgentDefinition.allowedTools`; entries are tool names and missing/disabled tools are omitted by the runtime with a warning
-
-**STABLE override surfaces:**
-
-- Per-module override exports MUST remain co-located in module-root `ai-agents.ts` / `ai-tools.ts`: `aiAgentOverrides`, `aiAgentExtensions`, `aiToolOverrides`
-- App-level overrides MUST remain under `ModuleEntry.overrides.ai.agents`, `ModuleEntry.overrides.ai.tools`, and `ModuleEntry.overrides.ai.extensions`
-- Programmatic overrides MUST keep highest precedence: `applyAiAgentOverrides`, `applyAiToolOverrides`, and `applyAiAgentExtensions`
-- Resolution order MUST remain: programmatic → `modules.ts` inline → file-based override exports → base registrations
-- `AiAgentExtension` patch order MUST remain: `replace*` first, `delete*` second, `append*` last
-- Override value validation MUST keep key/value matching semantics: a non-null agent override's `id` must equal the map key; a non-null tool override's `name` must equal the map key
-
-**Mutation approval contract:**
-
-- AI write tools MUST keep using `isMutation: true` and the `prepareMutation(...)` pending-action flow
-- `AiAgentMutationPolicy` values (`read-only`, `confirm-required`, `destructive-confirm-required`) MUST NOT be renamed or repurposed
-- Tenant prompt and mutation-policy override tables/API contracts are STABLE; fields may be added, but existing policy values and agent IDs must continue to resolve
-
-To retire an AI agent or tool: deprecate it, keep the old ID available or bridged for at least one minor version, update any shipped `allowedTools` references, and document migration instructions in the referenced spec and release notes.
-
-### 13. CLI Commands (STABLE)
-
-- MUST NOT rename or remove existing CLI commands or their required flags
-- MAY add new commands or optional flags freely
-
-### 14. Generated File Contracts (STABLE)
-
-Files in `apps/mercato/.mercato/generated/` are produced by the CLI generators. The generator output shape MUST remain compatible with the bootstrap consumer.
-
-- MUST NOT change the export names of generated files
-- MUST NOT change the `BootstrapData` type's required fields
-- MUST NOT remove AI generated registry exports: `aiAgentConfigEntries`, `allAiAgents`, `aiAgentOverrideEntries`, `aiAgentExtensionEntries`, `allAiAgentExtensions`, `aiToolConfigEntries`, `allAiTools`, `aiToolOverrideEntries`
-- MUST NOT change generated AI entry shapes: agent entries keep `{ moduleId, agents, overrides, extensions }`; tool entries keep `{ moduleId, tools, overrides }`
-- MAY add new generated files and new optional fields to `BootstrapData`
-- MAY add new generated AI registry exports additively
-- Generated `.ai/guides/module-facts.json` keeps its existing top-level module record and legacy sections; optional per-module `extensionSurfaces` is ADDITIVE. Its `hosts`, `contributions`, and `unresolved` arrays, correlation-resolution values, and exact public IDs are STABLE once published.
-- Generated `.ai/guides/framework-extension-points.md` is a sibling framework-owned catalog, not a synthetic module-facts key. Existing module Markdown headings, including `Host extension points`, MUST remain available; additive `UMES hosts`/`UMES contributions` sections may not redefine existing IDs.
-
----
-
-## Allowed vs Breaking Changes — Quick Reference
-
-| Surface | Add new | Add optional field | Remove field | Rename | Change type |
-|---------|---------|-------------------|-------------|--------|-------------|
-| Convention files | OK | OK | BREAKING | BREAKING | BREAKING |
-| Type interfaces | OK | OK | BREAKING | BREAKING | BREAKING (narrowing) |
-| Function params | OK (optional) | OK | BREAKING | BREAKING | BREAKING |
-| Event IDs | OK | OK (payload) | BREAKING | BREAKING | n/a |
-| Spot IDs | OK | OK (context) | BREAKING | BREAKING | BREAKING (context) |
-| API routes | OK | OK (req/res fields) | BREAKING (res fields) | BREAKING | BREAKING |
-| DB columns | OK (with default) | n/a | BREAKING | BREAKING | BREAKING (narrowing) |
-| DI names | OK | OK | BREAKING | BREAKING | BREAKING |
-| Feature IDs | OK | n/a | BREAKING* | BREAKING | n/a |
-| AI agent/tool IDs | OK | OK | BREAKING | BREAKING | BREAKING |
-| AI override surfaces | OK | OK | BREAKING | BREAKING | BREAKING |
-| Import paths | OK | n/a | BREAKING | BREAKING | n/a |
-| Generated registry exports | OK | OK | BREAKING | BREAKING | BREAKING |
-
-\* Feature ID removal requires a data migration.
-
----
-
-## Per-User Integration Credentials (2026-05-26)
-
-`.ai/specs/2026-05-21-email-integration-foundation.md` adds optional per-user scoping to integration credentials so two users on the same tenant can connect their own mailbox (Gmail / IMAP) without sharing one row. **All changes are additive** and pass the contract-surface checks above:
-
-| Surface | Change | Classification |
-|---------|--------|----------------|
-| 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 |
-
-**Migration path for existing tenants**: no action required. Existing integrations keep their single `user_id IS NULL` row and resolve exactly as before; only callers that pass `scope.userId` (the new per-user channels) read or write user-scoped rows.
-
----
-
-## Spec C — Provider Push Delivery (2026-05-27)
-
-`.ai/specs/implemented/2026-05-27-email-integration-inbound-reliability-and-threading.md` extends the communication-channels module with provider push delivery. **All changes are additive** and pass the contract-surface checks above:
-
-> **Update (2026-06-02):** the Microsoft Graph push surfaces (the two `/webhooks/microsoft/*` routes, the `…-microsoft-delta-sync` / `…-microsoft-renew-subscriptions` queues, and `OM_MICROSOFT_WEBHOOK_BASE_URL` / `OM_PUSH_RENEWAL_MICROSOFT_LEAD_HOURS`) were removed together with the `@open-mercato/channel-microsoft` provider — they never shipped in a release, so the removal is not a breaking change. The rows below reflect the Gmail-only surfaces that remain. The `client_state_encrypted` column — proposed solely for Microsoft Graph's anti-tampering nonce — was dropped from scope together with the provider before this branch's migrations were finalized; it appears in no committed migration or snapshot, so there is no schema change to reconcile.
-
-| Surface | Change | Classification |
-|---------|--------|----------------|
-| Adapter type interface (`ChannelAdapter`) | Three new **optional** methods: `registerPush?`, `unregisterPush?`, `applyPushNotification?` | ✓ ADDITIVE (Type interface, optional fields) |
-| Adapter input/output types | New exported types: `PushRegistration`, `RegisterPushInput`, `UnregisterPushInput`, `ApplyPushNotificationInput` | ✓ ADDITIVE (new types, no rename) |
-| Event IDs | Four new events: `communication_channels.push.{registered,failed,renewed,deactivated}` | ✓ ADDITIVE (new event IDs) |
-| ACL feature IDs | One new feature: `communication_channels.channel.push.manage` | ✓ ADDITIVE (new feature ID) |
-| API routes | Two new routes: `/webhooks/gmail`, `/channels/[id]/push/register` | ✓ ADDITIVE (new routes) |
-| Database schema | No change. The `client_state_encrypted` column proposed for Microsoft Graph was removed from scope before the migrations were finalized — it is absent from every committed migration and the snapshot. | ✓ No net schema change |
-| Queue names | Two new queues: `…-gmail-history-sync`, `…-gmail-renew-watch` | ✓ ADDITIVE |
-| Env vars | New optional: `OM_GMAIL_PUBSUB_TOPIC`, `OM_GMAIL_PUBSUB_AUDIENCE`, `OM_GMAIL_PUBSUB_SERVICE_ACCOUNT_EMAIL`, `OM_PUSH_RENEWAL_GMAIL_LEAD_HOURS` | ✓ ADDITIVE |
-| Polling cadence | `pollIntervalSeconds` flips 60 → 1800 only when `pushStatus='active'` is persisted. Non-push channels unchanged. | ✓ Behavior-preserving for existing channels |
-
-**Migration path for existing tenants**: no action required. Push is opt-in per channel — until an operator explicitly registers (via connect flow or `POST /push/register`), Gmail channels keep polling on the Spec B baseline. The new ACL feature `communication_channels.channel.push.manage` must be granted via `yarn mercato auth sync-role-acls` post-deploy for the "Re-register push" button to appear.

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

@@ -1,8 +0,0 @@
-{
-  "version": 1,
-  "generator": "@open-mercato/cli@0.6.7-develop.6862.1.c11a64ce0a",
-  "files": {
-    "AGENTS.md": "6403f2c9ee9e366b96ff34c43f8f901fb20841706b3c95bd8129935496b8ebdc",
-    "BACKWARD_COMPATIBILITY.md": "6e8e2640a92fd0b026c74e28af3c7afc4ce1fa7423b52ce25b1010d4f9de1d4e"
-  }
-}

package/dist/agentic/shared/ai/harness/README.md

@@ -1,50 +0,0 @@
-# Agent harness evaluations
-
-`cases.json` is the 203-case standalone-app contract. Run `yarn harness:validate --all` for the deterministic gate. Live routing uses a fresh read-only process per case:
-
-UMES routing is fact-first. The additive and unified-override audit evaluations, plus their targeted cases, resolve exact/pattern hosts, outgoing contributions, correlation provenance, round-trip groups, framework-owned targets, and override domain/key/mode from the generated module sheets and `.ai/guides/framework-extension-points.md` before bounded installed source. The repository UMES umbrella spec may appear as optional source-checkout provenance; it is never required in a standalone scaffold.
-
-```text
-yarn harness:validate --runner codex --all
-yarn harness:validate --runner claude --case OMH-009
-```
-
-For an explicitly requested Codex comparison outside the blocking release matrix, pin both dimensions so the sanitized result is reproducible, for example `--model gpt-5.4-mini --reasoning-effort high`. The effort override is Codex-only; supported values are `minimal`, `low`, `medium`, `high`, and `xhigh`, and omitting it preserves the existing runner default. Measured high-effort mini runs legitimately exceed ten minutes on broad context, so that exact model/effort pair uses a 15-minute per-attempt floor; measured Claude/Sonnet runs use a 10-minute floor. Passing `--timeout` remains authoritative, and other routing runs retain the five-minute default.
-
-A blocking release selects one primary runner for every live lane. The optional portability runner must be different and receives only the exact 46-case representative read-only set:
-
-```text
-yarn harness:release --runner codex --prepare-targets /absolute/empty-release-targets --acknowledge-writes
-yarn harness:release --runner codex --portability-runner claude --prepare-targets /absolute/empty-release-targets --acknowledge-writes
-```
-
-The primary runner owns all 203 routing cases, all 46 writable cases, and all generative-judge runs. No per-case fallback or mixed primary ownership is allowed. Omitting `--portability-runner` is valid and the sanitized report records `portabilityRunner: null`; explicitly requesting an unavailable or failing secondary runner fails that extended run.
-
-Writable evaluation is intentionally opt-in. The expanded catalog has a 46-case writable release target, but only cases registered in `release-matrix.json` and backed by controller-owned fixtures and oracles are executable. Copy or create a fresh standalone app for one registered case, then seed only that case and mark the target disposable:
-
-```text
-yarn harness:fixture --case OMH-009 --target /absolute/disposable/app --acknowledge-writes
-yarn harness:validate --runner codex --case OMH-009 --writable-root /absolute/disposable/app --acknowledge-writes
-```
-
-For a manually prepared writable target, run `yarn generate` in the target first and replace its `node_modules` directory with a link to the controller scaffold's dependency tree. The evaluator rejects copied or independently installed dependency trees because the controller must fingerprint and mount one protected dependency source. `--prepare-targets` performs both steps automatically for a full release run.
-
-The preparer refuses the controller app, non-standalone targets, reused targets, and existing fixture files. The evaluator rejects writes outside each case's `allowedWrites`. Every writable case is checked by the fixed controller-owned TypeScript AST oracle, so imports, comments, and token stuffing cannot satisfy an implementation contract. Integration/workflow and seeded regression cases also run isolated mocked behavior probes; the after phase runs the target's fixed `yarn typecheck` gate. A case-local `timeoutMs` may only raise the operator timeout floor for an unusually broad writable one-shot; it never lowers an explicit operator timeout and is capped at 10 minutes. The target can never supply or replace executable oracle code. Regression oracles must fail before the change and pass afterward. Fixture preparation is not run evidence. Generated results live under ignored `.ai/harness/results/`; they contain hashes and sanitized summaries, never raw transcripts or environment values.
-
-The four generated-test cases use direct controller-resolved Jest/Playwright CLIs, never target package scripts. The target and dependencies stay read-only; Jest has no network, Playwright has loopback only, and the browser lane exposes only the exact installed headless-shell runtime. JSON reporters must attest at least one passed test and zero skipped, todo, focused, flaky, or expected-failure tests before review evidence can be created.
-
-The generative judge is a separate post-oracle lane, never a nested second-model call. It applies the reusable `om-judge-agent-session` workflow, the pinned `om-code-review` skill, and UI design-system references when applicable. The individual command is opt-in while developing one case; the once-per-release suite requires it for every writable case:
-
-```text
-yarn harness:validate --runner codex --judge-writable-result /absolute/controller/.ai/harness/results/<writable-result>.json --writable-root /absolute/disposable/app
-```
-
-The source must be a passing one-shot implementation result from the current harness and its final whole-target fingerprint must still match. The controller copies changed regular text files as line-numbered inert snapshots, the local judge skill, its pinned installed `om-code-review` skill, and bounded trusted evidence into a temporary read-only bundle. Target package scripts, dependencies, Git data, tracker state, original source files, and the target's absolute path are not copied or supplied to the judge; trace-verified out-of-bundle, environment, or process inspection and any bundle or target mutation fail closed. A separate sanitized artifact records source-result, target, policy, and skill hashes plus fixed evidence, artifact findings, design-system assessment, the smallest harness-owner findings, strict verdicts, and both reports. The legacy `--review-writable-result` and `--review-validation-result` flags remain read-only compatibility aliases. This supplemental judge uses prior controller evidence and does not claim validation or CI that did not run.
-
-## Live-run security boundary
-
-The trusted runner receives an explicit allowlist of runtime/authentication variables rather than the evaluator's complete environment. The model receives no general shell, process, environment, discovery, browser, or network tool. Codex and Claude are both restricted to one evaluator-owned MCP server launched through `env -i`; it exposes only exact-path `read` and, for writable cases, allowlisted atomic `write`. The server rejects absolute/traversal paths, symlink escapes, credentials, dependencies, Git state, build output, and harness internals. Every response-derived string is also recursively redacted before validation or persistence.
-
-On macOS, Claude Code subscription credentials normally live in the login Keychain and cannot be copied into the isolated runner home. Run `claude setup-token`, export the resulting value as `CLAUDE_CODE_OAUTH_TOKEN`, and then start the Claude lane. Missing or exhausted provider authentication aborts the matrix as an environment failure instead of being counted as a case result.
-
-The controller places routing and generated-code review inside a host filesystem sandbox: macOS uses `/usr/bin/sandbox-exec`; Linux uses Bubblewrap with user namespaces; native Windows is unsupported for live/review lanes. Only the trusted runner binary receives provider transport and isolated authentication state. Prompt-directed tools cannot open sockets or read runner state: the sole MCP subprocess has an empty environment, is rooted at the app or inert review bundle, and implements no process or network operation. The mandatory outer sandbox remains the filesystem authority; the narrow MCP contract is the model-tool authority. Tool-event traces are still mandatory release evidence: missing traces, out-of-root reads, `.env*`, `.git/**`, `.ai/harness/**`, and case-forbidden or arbitrary app-root reads fail closed. `actualContext` contains only traced MCP reads; `declaredContext` separately measures the model-reported selection. Writable runs additionally fingerprint normally ignored/protected roots before and after execution so writes under `.git`, `node_modules`, build output, or harness results cannot evade the allowlist check.

package/dist/agentic/shared/ai/harness/RELEASE.md

@@ -1,57 +0,0 @@
-# Harness release gate
-
-Run the complete per-release gate from a generated standalone app with one command:
-
-```text
-yarn harness:release --runner codex --prepare-targets /absolute/empty-release-targets --acknowledge-writes
-```
-
-Choose exactly one blocking primary runner with `--runner codex` or `--runner claude`. That runner owns the complete 203-case routing gate and every writable/review lane. To add cross-model portability evidence, explicitly pass the other runner as `--portability-runner claude` or `--portability-runner codex`; it runs only the exact 46-case representative read-only set. The two runners must differ. Omitting the portability option is valid and is recorded as `portabilityRunner: null`; no secondary result is claimed. There is no per-case fallback or mixed primary ownership. Once requested, a portability failure or unavailable runner fails that extended release run.
-
-`--prepare-targets` accepts only an absolute, new or empty regular directory outside the controller app. The controller must be a sanitized fresh scaffold: automatic preparation fails before copying when it finds `.env`, `.env.*` (except `.env.example`, `.env.sample`, and `.env.template`), credential files, or private-key files. Never use a configured development or production app as the controller. It copies the fresh scaffold once per catalog case whose `evaluationKind` is `implementation` or `regression`, while excluding `.git`, `node_modules`, build/cache/coverage output, `.ai/harness/results`, `.ai/reports`, and `.ai/framework-context`. Each target receives a guarded link to the controller's installed dependency tree. The OS sandbox resolves that link as read-only during both the writable model run and the target command gate. The release gate also hashes every dependency entry and regular-file body once before execution and once after the complete suite, and fails if any nested content or metadata changed. A generated `release-targets.json` records the local mapping.
-
-## Containment prerequisites and policy
-
-The complete release gate fails closed unless it runs on Linux with a root-owned, non-group/world-writable `bwrap` (Bubblewrap) on `PATH` and user namespaces available. Preflight executes a nonce-bound containment probe that requires case-local loopback to work while an evaluator-owned host-loopback listener remains unreachable, and rejects payloads retaining any effective, permitted, inheritable, ambient, or bounding capability; no-op and pass-through shims fail. macOS `sandbox-exec` remains useful for network-free sandbox lanes, but it shares the host network namespace and cannot provide host-isolated loopback. The Playwright API/browser lanes therefore cannot run safely on native macOS. Native macOS and Windows users must run the complete command in a Linux VM/container with Bubblewrap rather than weakening containment. Release preflight rejects an unsupported host before target preparation, provider-backed runner invocation, or any writable lane starts.
-
-Only the explicitly selected trusted Codex or Claude runner binary—and the optional distinct portability runner when requested—receives provider transport and an isolated authentication copy. The model receives no general shell, process, environment, discovery, browser, or network tool. Its sole tool surface is an evaluator-owned MCP server launched through `env -i`: exact-path `read`, plus allowlisted atomic `write` only for primary-runner writable cases. That server is rooted at the app or inert review bundle, rejects absolute/traversal paths and symlink escapes, cannot address the isolated authentication directory, and implements no network operation. Controller dependencies are read-only. Trace validation independently rejects out-of-scope reads and selections.
-
-Linux containment unshares every namespace, including PID, user, IPC, UTS, cgroup, mount, and network; only the trusted provider-backed runner lane opts back into host networking, while its env-cleared MCP tool process has no network method. Network-free commands remain isolated, while generated HTTP/browser tests receive only loopback inside the isolated network namespace. macOS `sandbox-exec` still enforces filesystem and network-denied lanes, but it is not treated as an equivalent loopback boundary. Any unavailable, unrecognized, or untraced model tool fails closed.
-
-Model-authored `yarn generate`, `yarn typecheck`, `yarn lint`, and `yarn build` commands all run with network access denied—including the Next.js build—against an isolated copy of the disposable target; the original oracle-validated target stays unchanged for review. Their environment is rebuilt from a small allowlist: `PATH`, isolated `HOME`/temporary/XDG directories, an existing read-only `COREPACK_HOME` tool cache when present, the Windows launcher variables on supported hosts, and deterministic CI/telemetry/time-zone flags. Provider credentials, package-registry tokens, database URLs, and arbitrary parent environment values are never inherited. The copy permits only explicit command outputs (`.mercato/generated`, `.mercato/next`, `next-env.d.ts`, and `tsconfig.tsbuildinfo` where applicable), records the touched output roots in release evidence, rejects ordinary source/config or sibling writes, and keeps the resolved dependency tree read-only. A missing sandbox, denied namespace setup, missing offline package-manager runtime, unsafe target link, dependency fingerprint mismatch, or original-target drift fails the gate.
-
-Generated tests use a stricter lane. The controller resolves the Jest or Playwright CLI from the protected dependency tree and invokes it with fixed arguments; package scripts and `npx` are never executed. The report and review evidence bind the normalized direct Node argv, CLI package, and exact CLI file hash—not a package-script alias. The complete target is read-only, and only an isolated temporary output/cache directory is writable. Unit tests have no network. API and browser tests run only under Linux/Bubblewrap, receive loopback inside that isolated network namespace, must start self-contained `127.0.0.1` servers, and cannot reach external or host-loopback services. The browser lane exposes only the exact installed Chromium headless-shell revision through an isolated cache link—not the surrounding host browser cache. Missing CLIs, browsers, or isolation fail closed. No Docker socket, host credentials, or inherited provider configuration enters this lane.
-
-For externally prepared apps, `--writable-targets /absolute/release-targets.json` remains supported. The manifest must assign every writable case to its own fresh generated app:
-
-```json
-{
-  "schemaVersion": 1,
-  "targets": {
-    "OMH-009": "/absolute/fresh-app-for-OMH-009",
-    "OMH-011": "/absolute/fresh-app-for-OMH-011"
-  }
-}
-```
-
-The current catalog contains 203 cases, including 46 writable implementation/regression cases (22.7%). The command still derives all counts and case IDs from `cases.json`, `validators.json`, and `release-matrix.json`; those figures are documented release facts, not runner constants. The matrix keeps both supported runner model selectors, an exact all-case primary profile, an exact 46-case portability profile, and runner-neutral writable assignments. Run `yarn install-skills` first so the pinned external `om-code-review` skill and ownership evidence are present; the reusable local `om-judge-agent-session` skill ships with the scaffold. Before running a model or writing a fixture, the release command requires complete deterministic, primary live-routing, writable, trusted-oracle, target, generated-test, and generative-judge coverage. Every one of the 46 writable cases must have a judge assignment composing both skills. Missing business fixtures or release-matrix entries fail preflight and are listed by exact case ID in the report.
-
-## PR #4529 remediation evidence
-
-The PR's focused remediation evidence is not a release-certification substitute. Fresh emitted controllers pass deterministic 192/192, and the field-tested OMH-188–192 generative cohort passes on default Codex, Claude Sonnet, and high-effort gpt-5.4-mini. Fresh OMH-185 writable attempts fixed concrete organization-scope, command-object, module-activation, command-snapshot, schema, custom-field, UI, and Jest guidance defects at their routed owners without relaxing trusted oracles. The final attempt reached the case's fixed 600-second ceiling and is excluded from pass evidence. Issue #4670 now owns the complete selected-primary 203-case routing and 46-case writable/generated-test/review certification, prioritizing the generative cohort and recording unavailable Claude lanes without fallback or mixed-runner ownership.
-
-After preflight it runs, in order:
-
-1. deterministic validation for the complete catalog;
-2. the release matrix's fixed `yarn generate`, `yarn typecheck`, `yarn lint`, and `yarn build` foundation;
-3. the selected primary runner across all 203 live-routing cases, followed by the optional distinct portability runner across the exact 46-case read-only sample when requested;
-4. fixture preparation and the selected primary runner for every writable case, including the controller-owned AST/behavior oracles and target typecheck;
-5. `yarn generate`, `yarn typecheck`, `yarn lint`, and `yarn build` in every writable target, after its trusted oracles;
-6. real generated-code execution for OMH-163 and OMH-192 through fixed Jest, OMH-164 through API-only Playwright, and OMH-165 through real-browser Playwright; and
-7. explicit isolated `om-judge-agent-session` for every writable result, composing `om-code-review` and applicable design-system guidance, bound to its passing command attestation, any required generated-test result and artifact hash, and the final target fingerprint.
-
-Each writable target is single-use because fixture preparation marks it disposable. Externally supplied target realpaths must be pairwise disjoint and neither equal to, contain, nor be contained by the controller. A failed deterministic or foundation-validation step prevents model execution. Once fixture preparation succeeds, all four target commands run even when the writable gate itself fails, so every generated target has exact diagnostics. A writable case may declare `timeoutMs` only to raise the release `--case-timeout` floor (never lower it); OMH-185 and its business-language parity case OMH-193 use 600000 ms because the complete module slice exceeded the generic five-minute evaluator default while actively producing source. Generated tests run only after the trusted writable oracle and all four target commands pass; review then requires all applicable gates. A target command or generated-test failure is recorded with its sanitized diagnostic and review is skipped. Other matrix entries continue so the report remains useful.
-
-UI-routed implementation reviews receive only the bounded backend UI guide and `om-backend-ui-design` design-system references. Non-UI reviews do not receive that extra context.
-
-The command writes a mode-`0600` `*-release-suite.json` artifact under `.ai/harness/results/`. Its `runnerPolicy` names the blocking primary runner and records either the explicitly requested portability runner or `null`. It stores no raw runner transcripts, target paths, environment values, URL credentials, or provider credentials. Deterministic and `generate`/`typecheck`/`lint`/`build` foundation commands receive the same minimal isolated environment as target validation, not the controller process environment. Exact values of sensitive inherited environment variables and every scalar string copied from Codex `auth.json` or Claude `.credentials.json` stay inside the isolated trusted-runner state, are unreachable through the MCP root/tool contract, and are redacted from all structured results and errors as defense in depth. The report contains exact coverage gaps, sanitized per-target command/test outcomes and actionable failure reasons, first-pass and correction rates, aggregate context-token measures, review verdict counts, and categorized misuse/violation rates.