@open-mercato/shared 0.6.8-develop.6930.1.1e5976efc3 → 0.6.8-develop.6940.1.177ea30c6e

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

@@ -1,3 +1,48 @@
+const EXTENSION_HOST_FAMILIES = [
+  "generic",
+  "menu",
+  "data-table",
+  "crud-form",
+  "detail",
+  "portal-page",
+  "component-handle",
+  "entity",
+  "api-route",
+  "command",
+  "event",
+  "query-lifecycle",
+  "dashboard",
+  "notification",
+  "integration",
+  "specialized-registry",
+  "module-override"
+];
+const EXTENSION_HOST_CAPABILITIES = [
+  "render-widget",
+  "headless-widget",
+  "menu-item",
+  "column-widget",
+  "row-action",
+  "bulk-action",
+  "filter-widget",
+  "toolbar-widget",
+  "field-widget",
+  "lifecycle-handler",
+  "component-replacement",
+  "response-enricher",
+  "query-enricher",
+  "api-interceptor",
+  "command-interceptor",
+  "mutation-guard",
+  "entity-extension",
+  "async-subscriber",
+  "sync-subscriber",
+  "browser-client",
+  "browser-portal",
+  "registry-contribution",
+  "module-override"
+];
+const EXTENSION_HOST_ACTIVATIONS = ["always", "host-opt-in", "caller-opt-in", "feature-gated"];
 function defineModuleExtensionPoints(declaration) {
   return Object.freeze({
     ...declaration,
@@ -36,6 +81,7 @@ const DATA_TABLE_EXTENSION_SURFACES = [
   { key: "replacement", suffix: null, capabilities: ["component-replacement"], bound: true },
   { key: "emptyState", suffix: "empty-state", capabilities: ["render-widget"], bound: false }
 ];
+const DATA_TABLE_EXTENSION_SURFACE_KEYS = DATA_TABLE_EXTENSION_SURFACES.map((surface) => surface.key);
 const CRUD_FORM_EXTENSION_SURFACES = [
   { key: "base", suffix: null, capabilities: ["render-widget", "lifecycle-handler"], bound: true },
   { key: "header", suffix: "header", capabilities: ["render-widget"], bound: true },
@@ -49,6 +95,7 @@ const CRUD_FORM_EXTENSION_SURFACES = [
   { key: "fieldBefore", suffix: "field:{fieldId}:before", capabilities: ["render-widget"], bound: false },
   { key: "fieldAfter", suffix: "field:{fieldId}:after", capabilities: ["render-widget"], bound: false }
 ];
+const CRUD_FORM_EXTENSION_SURFACE_KEYS = CRUD_FORM_EXTENSION_SURFACES.map((surface) => surface.key);
 const CRUD_FORM_LIFECYCLE_PHASES = [
   "transformValidation",
   "transformDisplayData",
@@ -78,11 +125,95 @@ function extensionSpotChildId(spotId, suffix) {
 function resolveExtensionPointPattern(pattern, parameters) {
   return pattern.replace(/\{([^}]+)\}/g, (token, parameterName) => parameters[parameterName] ?? token);
 }
+const MODULE_EXTENSION_CONTRIBUTION_KINDS = [
+  "widget",
+  "data-table",
+  "crud-form",
+  "component-override",
+  "response-enricher",
+  "api-interceptor",
+  "command-interceptor",
+  "mutation-guard",
+  "entity-extension",
+  "subscriber",
+  "browser-reaction",
+  "specialized-registry",
+  "module-override"
+];
+const MODULE_EXTENSION_ACTIVATION_KINDS = [
+  "crud-response-enricher",
+  "query-enricher",
+  "mutation-guard",
+  "api-interceptor-bridge",
+  "command-interceptor-bridge",
+  "widget-injection-consumer",
+  "component-extension-consumer",
+  "dashboard-host-consumer"
+];
+const MODULE_EXTENSION_TARGET_KINDS = [
+  "module",
+  "entity",
+  "api-route",
+  "command",
+  "widget-spot",
+  "component",
+  "event",
+  "notification",
+  "wildcard"
+];
+const MODULE_EXTENSION_RESOLUTIONS = [
+  "bound",
+  "capability-only",
+  "optional-target-missing",
+  "wildcard",
+  "unresolved"
+];
+const MODULE_EXTENSION_HOST_RESOLUTIONS = ["exact", "pattern", "framework", "fact-ref"];
+const MODULE_EXTENSION_TARGET_RESOLUTIONS = [
+  "exact",
+  "pattern",
+  "framework",
+  "fact-ref",
+  "optional-external",
+  "unresolved"
+];
+const MODULE_SPECIALIZED_REGISTRIES = [
+  "notification",
+  "integration",
+  "search",
+  "vector",
+  "ai",
+  "payment",
+  "shipping",
+  "currency",
+  "workflow"
+];
+const COMPONENT_OVERRIDE_MODES = ["replace", "wrapper", "props"];
+const MODULE_EXTENSION_UNRESOLVED_REASONS = [
+  "unclassified-binding",
+  "unbound-declaration",
+  "dynamic-without-pattern",
+  "unresolved-first-party-target"
+];
 export {
+  COMPONENT_OVERRIDE_MODES,
   CRUD_FORM_EXTENSION_SURFACES,
+  CRUD_FORM_EXTENSION_SURFACE_KEYS,
   CRUD_FORM_LIFECYCLE_PHASES,
   CRUD_FORM_OPERATIONS,
   DATA_TABLE_EXTENSION_SURFACES,
+  DATA_TABLE_EXTENSION_SURFACE_KEYS,
+  EXTENSION_HOST_ACTIVATIONS,
+  EXTENSION_HOST_CAPABILITIES,
+  EXTENSION_HOST_FAMILIES,
+  MODULE_EXTENSION_ACTIVATION_KINDS,
+  MODULE_EXTENSION_CONTRIBUTION_KINDS,
+  MODULE_EXTENSION_HOST_RESOLUTIONS,
+  MODULE_EXTENSION_RESOLUTIONS,
+  MODULE_EXTENSION_TARGET_KINDS,
+  MODULE_EXTENSION_TARGET_RESOLUTIONS,
+  MODULE_EXTENSION_UNRESOLVED_REASONS,
+  MODULE_SPECIALIZED_REGISTRIES,
   componentExtensionHost,
   crudFormExtensionHost,
   crudFormExtensionSpotId,

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

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/modules/widgets/extension-points.ts"],
-  "sourcesContent": ["export type ExtensionHostFamily =\n  | 'generic'\n  | 'menu'\n  | 'data-table'\n  | 'crud-form'\n  | 'detail'\n  | 'portal-page'\n  | 'component-handle'\n  | 'entity'\n  | 'api-route'\n  | 'command'\n  | 'event'\n  | 'query-lifecycle'\n  | 'dashboard'\n  | 'notification'\n  | 'integration'\n  | 'specialized-registry'\n  | 'module-override'\n\nexport type ExtensionHostCapability =\n  | 'render-widget'\n  | 'headless-widget'\n  | 'menu-item'\n  | 'column-widget'\n  | 'row-action'\n  | 'bulk-action'\n  | 'filter-widget'\n  | 'toolbar-widget'\n  | 'field-widget'\n  | 'lifecycle-handler'\n  | 'component-replacement'\n  | 'response-enricher'\n  | 'query-enricher'\n  | 'api-interceptor'\n  | 'command-interceptor'\n  | 'mutation-guard'\n  | 'entity-extension'\n  | 'async-subscriber'\n  | 'sync-subscriber'\n  | 'browser-client'\n  | 'browser-portal'\n  | 'registry-contribution'\n  | 'module-override'\n\nexport type ExtensionHostActivation = 'always' | 'host-opt-in' | 'caller-opt-in' | 'feature-gated'\n\nexport type ExtensionPointPatternParameter = {\n  source: string\n  pattern?: string\n}\n\ntype ExtensionHostDeclarationBase = {\n  source: string\n  contextContract?: string\n  dataContract?: string\n  scopeContract?: string\n  runtimeContract?: string\n  activation?: ExtensionHostActivation\n  aliases?: readonly string[]\n  fallbacks?: readonly string[]\n}\n\ntype InjectionExtensionHostDeclarationBase = ExtensionHostDeclarationBase & {\n  family: Exclude<ExtensionHostFamily, 'data-table' | 'crud-form' | 'component-handle'>\n  supported: readonly ExtensionHostCapability[]\n}\n\nexport type InjectionExtensionHostDeclaration = InjectionExtensionHostDeclarationBase & (\n  | {\n      spotId: string\n      pattern?: never\n      parameters?: never\n    }\n  | {\n      spotId?: never\n      pattern: string\n      parameters: Readonly<Record<string, ExtensionPointPatternParameter>>\n    }\n)\n\nexport type DataTableExtensionHostDeclaration = ExtensionHostDeclarationBase & {\n  family: 'data-table'\n  tableId: string\n  baseSpotId?: string\n}\n\nexport type CrudFormExtensionHostDeclaration = ExtensionHostDeclarationBase & {\n  family: 'crud-form'\n  entityId: string\n  spotId?: string\n}\n\nexport type ComponentExtensionHostDeclaration = ExtensionHostDeclarationBase & {\n  family: 'component-handle'\n  componentId: string\n  propsContract?: string\n}\n\nexport type ModuleExtensionHostDeclaration =\n  | InjectionExtensionHostDeclaration\n  | DataTableExtensionHostDeclaration\n  | CrudFormExtensionHostDeclaration\n  | ComponentExtensionHostDeclaration\n\nexport type ModuleExtensionPoints<\n  TModuleId extends string = string,\n  THosts extends Readonly<Record<string, ModuleExtensionHostDeclaration>> = Readonly<Record<string, ModuleExtensionHostDeclaration>>,\n> = {\n  moduleId: TModuleId\n  hosts: THosts\n}\n\nexport function defineModuleExtensionPoints<\n  const TModuleId extends string,\n  const THosts extends Readonly<Record<string, ModuleExtensionHostDeclaration>>,\n>(declaration: ModuleExtensionPoints<TModuleId, THosts>): ModuleExtensionPoints<TModuleId, THosts> {\n  return Object.freeze({\n    ...declaration,\n    hosts: Object.freeze({ ...declaration.hosts }),\n  })\n}\n\nexport function injectionExtensionHost<const TDeclaration extends InjectionExtensionHostDeclaration>(\n  declaration: TDeclaration,\n): Readonly<TDeclaration> {\n  const hasExactId = typeof declaration.spotId === 'string' && declaration.spotId.length > 0\n  const hasPattern = typeof declaration.pattern === 'string' && declaration.pattern.length > 0\n  if (hasExactId === hasPattern) {\n    throw new Error('[internal] injection extension hosts require exactly one of spotId or pattern')\n  }\n  if (hasPattern && (!declaration.parameters || Object.keys(declaration.parameters).length === 0)) {\n    throw new Error('[internal] patterned injection extension hosts require named parameters')\n  }\n  return Object.freeze({ ...declaration })\n}\n\nexport function dataTableExtensionHost<\n  const TDeclaration extends Omit<DataTableExtensionHostDeclaration, 'family'>,\n>(\n  declaration: TDeclaration,\n): Readonly<TDeclaration & { family: 'data-table' }> {\n  return Object.freeze({ family: 'data-table', ...declaration })\n}\n\nexport function crudFormExtensionHost<\n  const TDeclaration extends Omit<CrudFormExtensionHostDeclaration, 'family'>,\n>(\n  declaration: TDeclaration,\n): Readonly<TDeclaration & { family: 'crud-form' }> {\n  return Object.freeze({ family: 'crud-form', ...declaration })\n}\n\nexport function componentExtensionHost<\n  const TDeclaration extends Omit<ComponentExtensionHostDeclaration, 'family'>,\n>(\n  declaration: TDeclaration,\n): Readonly<TDeclaration & { family: 'component-handle' }> {\n  return Object.freeze({ family: 'component-handle', ...declaration })\n}\n\nexport type BoundExtensionSurface = {\n  key: string\n  suffix: string | null\n  capabilities: readonly ExtensionHostCapability[]\n  bound: boolean\n  phases?: readonly string[]\n  operations?: readonly string[]\n}\n\nexport const DATA_TABLE_EXTENSION_SURFACES = [\n  { key: 'header', suffix: 'header', capabilities: ['render-widget'], bound: true },\n  { key: 'footer', suffix: 'footer', capabilities: ['render-widget'], bound: true },\n  { key: 'toolbar', suffix: 'toolbar', capabilities: ['toolbar-widget'], bound: true },\n  { key: 'searchTrailing', suffix: 'search-trailing', capabilities: ['render-widget'], bound: true },\n  { key: 'columns', suffix: 'columns', capabilities: ['column-widget'], bound: true },\n  { key: 'rowActions', suffix: 'row-actions', capabilities: ['row-action'], bound: true },\n  { key: 'bulkActions', suffix: 'bulk-actions', capabilities: ['bulk-action'], bound: true },\n  { key: 'filters', suffix: 'filters', capabilities: ['filter-widget'], bound: true },\n  { key: 'replacement', suffix: null, capabilities: ['component-replacement'], bound: true },\n  { key: 'emptyState', suffix: 'empty-state', capabilities: ['render-widget'], bound: false },\n] as const satisfies readonly BoundExtensionSurface[]\n\nexport const CRUD_FORM_EXTENSION_SURFACES = [\n  { key: 'base', suffix: null, capabilities: ['render-widget', 'lifecycle-handler'], bound: true },\n  { key: 'header', suffix: 'header', capabilities: ['render-widget'], bound: true },\n  { key: 'fields', suffix: 'fields', capabilities: ['field-widget'], bound: true },\n  { key: 'replacement', suffix: null, capabilities: ['component-replacement'], bound: true },\n  { key: 'beforeFields', suffix: 'before-fields', capabilities: ['render-widget'], bound: false },\n  { key: 'afterFields', suffix: 'after-fields', capabilities: ['render-widget'], bound: false },\n  { key: 'footer', suffix: 'footer', capabilities: ['render-widget'], bound: false },\n  { key: 'sidebar', suffix: 'sidebar', capabilities: ['render-widget'], bound: false },\n  { key: 'group', suffix: 'group:{groupId}', capabilities: ['render-widget'], bound: false },\n  { key: 'fieldBefore', suffix: 'field:{fieldId}:before', capabilities: ['render-widget'], bound: false },\n  { key: 'fieldAfter', suffix: 'field:{fieldId}:after', capabilities: ['render-widget'], bound: false },\n] as const satisfies readonly BoundExtensionSurface[]\n\nexport const CRUD_FORM_LIFECYCLE_PHASES = [\n  'transformValidation',\n  'transformDisplayData',\n  'onBeforeNavigate',\n  'onAppEvent',\n  'onVisibilityChange',\n  'onBeforeDelete',\n  'onDelete',\n  'onAfterDelete',\n  'onDeleteError',\n  'onFieldChange',\n  'transformFormData',\n  'onBeforeSave',\n  'onSave',\n  'onAfterSave',\n] as const\n\nexport const CRUD_FORM_OPERATIONS = ['create', 'update', 'delete'] as const\n\nexport function dataTableExtensionSpotId(tableId: string, suffix?: string): string {\n  return suffix ? `data-table:${tableId}:${suffix}` : `data-table:${tableId}`\n}\n\nexport function crudFormExtensionSpotId(entityId: string, suffix?: string): string {\n  return suffix ? `crud-form:${entityId}:${suffix}` : `crud-form:${entityId}`\n}\n\nexport function extensionSpotChildId(spotId: string, suffix: string): string {\n  return `${spotId}:${suffix}`\n}\n\nexport function resolveExtensionPointPattern(\n  pattern: string,\n  parameters: Readonly<Record<string, string>>,\n): string {\n  return pattern.replace(/\\{([^}]+)\\}/g, (token, parameterName: string) => parameters[parameterName] ?? token)\n}\n\n/**\n * Portable, structural copy of the CLI provenance source reference\n * (`ModuleFactSourceRef` in `packages/cli/.../module-facts.ts`). Redefined here\n * \u2014 rather than imported \u2014 so `@open-mercato/shared` keeps zero dependency on\n * `@open-mercato/cli`. Field names are kept byte-identical so the two are\n * assignable across the package boundary.\n */\nexport type ModuleFactSourceRef = {\n  sourcePath: string\n  exportName?: string\n  line?: number\n}\n\n/** Portable, structural copy of the CLI provenance fact reference. */\nexport type ModuleFactRef = {\n  factSection: string\n  factKey: string\n}\n\nexport type ModuleExtensionContributionKind = ModuleExtensionContributionFact['kind']\n\nexport type ModuleExtensionActivationKind =\n  | 'crud-response-enricher'\n  | 'query-enricher'\n  | 'mutation-guard'\n  | 'api-interceptor-bridge'\n  | 'command-interceptor-bridge'\n  | 'widget-injection-consumer'\n  | 'component-extension-consumer'\n  | 'dashboard-host-consumer'\n\nexport type ModuleExtensionTargetRef = {\n  kind:\n    | 'module'\n    | 'entity'\n    | 'api-route'\n    | 'command'\n    | 'widget-spot'\n    | 'component'\n    | 'event'\n    | 'notification'\n    | 'wildcard'\n  id: string\n  moduleId?: string\n  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'\n}\n\nexport type ModuleExtensionActivation = {\n  id: string\n  kind: ModuleExtensionActivationKind\n  host: ModuleExtensionTargetRef\n  contributionKinds: ModuleExtensionContributionKind[]\n  phases?: string[]\n  /**\n   * Mutation operations the call site guards, when statically declared. A\n   * contribution declaring only other operations is not bound by this activation.\n   */\n  operations?: string[]\n  source: ModuleFactSourceRef\n  bridge?: ModuleFactRef\n}\n\nexport type ModuleExtensionResolution =\n  | 'bound'\n  | 'capability-only'\n  | 'optional-target-missing'\n  | 'wildcard'\n  | 'unresolved'\n\nexport type ModuleIncomingExtensionRef = {\n  contributionId: string\n  contributionKind: ModuleExtensionContributionKind\n  contributorModuleId: string\n  target: ModuleExtensionTargetRef\n  activationId?: string\n  resolution: ModuleExtensionResolution\n  source: ModuleFactSourceRef\n}\n\nexport type ModuleContributionResolution = {\n  contributionId: string\n  target: ModuleExtensionTargetRef\n  resolution: ModuleExtensionResolution\n  activationIds: string[]\n}\n\n/**\n * Additive, optional bidirectional-topology fields layered on top of the\n * existing extension-surface facts. Every field is optional so legacy consumers\n * and pre-existing generated output remain byte-compatible.\n */\nexport type ModuleExtensionSurfaceFactsAdditions = {\n  activations?: ModuleExtensionActivation[]\n  incoming?: ModuleIncomingExtensionRef[]\n  contributionResolutions?: ModuleContributionResolution[]\n}\n\nexport type ModuleExtensionSurfaceFacts = {\n  hosts: ModuleExtensionHostFact[]\n  contributions: ModuleExtensionContributionFact[]\n  unresolved: ModuleExtensionUnresolvedFact[]\n} & ModuleExtensionSurfaceFactsAdditions\n\nexport type ModuleExtensionHostFact = {\n  key: string\n  id: string\n  resolution: 'exact' | 'pattern' | 'framework' | 'fact-ref'\n  family: ExtensionHostFamily\n  ownerModule: string\n  capabilities: ExtensionHostCapability[]\n  phases?: string[]\n  operations?: string[]\n  contextContract?: string\n  dataContract?: string\n  scopeContract?: string\n  runtimeContract?: string\n  activation?: ExtensionHostActivation\n  bound: boolean\n  stability: 'frozen' | 'stable'\n  source:\n    | { kind: 'declaration'; path: string; symbol: string }\n    | { kind: 'fact-ref'; factSection: string; factKey: string }\n    | { kind: 'framework'; path: string; symbol: string }\n  aliases?: string[]\n  patternParameters?: Record<string, ExtensionPointPatternParameter>\n  fallbacks?: string[]\n}\n\nexport type ModuleExtensionTargetFact = {\n  id: string\n  resolution: 'exact' | 'pattern' | 'framework' | 'fact-ref' | 'optional-external' | 'unresolved'\n  factRef?: { factSection: string; factKey: string }\n  optionalOwnerPackage?: string\n}\n\nexport type ModuleExtensionContributionBase = {\n  id: string\n  targets: ModuleExtensionTargetFact[]\n  phases?: string[]\n  operations?: string[]\n  features?: string[]\n  scopeContract: string\n  activation?: ExtensionHostActivation\n  placement?: { relativeTo?: string; position?: 'first' | 'last' | 'before' | 'after'; priority?: number }\n  roundTripId?: string\n  override?: { domain: string; key: string; mode: 'disable-replace' | 'replace' | 'additive' }\n  source: { path: string; symbol?: string }\n}\n\nexport type ModuleExtensionContributionFact = ModuleExtensionContributionBase & (\n  | {\n      kind: 'widget'\n      details: {\n        payload: 'render' | 'headless' | 'menu' | 'dashboard' | 'notification' | 'integration'\n        registryKey: string\n        itemIds?: string[]\n        labelKeys?: string[]\n        contextContract?: string\n        dataContract?: string\n        executionGuard: 'host' | 'contribution' | 'both'\n      }\n    }\n  | {\n      kind: 'data-table'\n      details: {\n        payload: 'column' | 'row-action' | 'bulk-action' | 'filter' | 'toolbar' | 'render'\n        tableId: string\n        executionGuard: 'host' | 'contribution' | 'both'\n      }\n    }\n  | {\n      kind: 'crud-form'\n      details: {\n        payload: 'render' | 'field' | 'lifecycle-handler'\n        entityId: string\n        fieldIds?: string[]\n        groupIds?: string[]\n        requestHeaderCapability: boolean\n      }\n    }\n  | {\n      kind: 'component-override'\n      details: { handle: string; mode: 'replace' | 'wrapper' | 'props'; propsContract: string }\n    }\n  | {\n      kind: 'response-enricher'\n      details: {\n        targetEntity: string\n        surfaces: Array<'list' | 'detail'>\n        timeoutMs: number\n        fallback: 'none' | 'configured'\n        critical: boolean\n        cachePosture: 'record-pure' | 'rerun-on-list-cache-hit'\n        queryEngine?: {\n          engines: string[]\n          applyOn: Array<'list' | 'detail'>\n          activation: 'caller-opt-in'\n        }\n      }\n    }\n  | {\n      kind: 'api-interceptor'\n      details: {\n        route: string\n        methods: string[]\n        phases: Array<'before' | 'after'>\n        activation: 'crud-pipeline' | 'custom-route-bridge'\n        timeoutMs: number\n        failurePosture: 'fail-closed' | 'fallback'\n      }\n    }\n  | {\n      kind: 'command-interceptor'\n      details: {\n        targetCommand: string\n        phases: Array<'before-execute' | 'after-execute' | 'before-undo' | 'after-undo'>\n      }\n    }\n  | {\n      kind: 'mutation-guard'\n      details: {\n        entityId: string\n        operations: Array<'create' | 'update' | 'delete'>\n        capabilities: Array<'block' | 'rewrite' | 'after-success'>\n        optimisticLock: 'preserved'\n      }\n    }\n  | {\n      kind: 'entity-extension'\n      details: {\n        hostEntityId: string\n        extensionEntityId: string\n        linkId: string\n        scopeContract: string\n        orphanContract: string\n      }\n    }\n  | {\n      kind: 'subscriber'\n      details: {\n        event: string\n        subscriberId: string\n        persistent: boolean\n        sync: boolean\n        priority?: number\n      }\n    }\n  | {\n      kind: 'browser-reaction'\n      details: {\n        transports: Array<'client' | 'portal' | 'notification-effect'>\n        hooks: string[]\n        audienceScopeContract: string\n        maxPayloadBytes?: number\n        dedupWindowMs?: number\n        /**\n         * Statically declared handler id. Runtime keys `notifications.handlers`\n         * overrides by it, so it is absent when the module declares no id (such a\n         * handler cannot be overridden).\n         */\n        overrideKey?: string\n      }\n    }\n  | {\n      kind: 'specialized-registry'\n      details: {\n        registry: 'notification' | 'integration' | 'search' | 'vector' | 'ai' | 'payment' | 'shipping' | 'currency' | 'workflow'\n        registryId: string\n        specialistRoute: string\n      }\n    }\n  | {\n      kind: 'module-override'\n      details: {\n        domain: string\n        key: string\n        mode: 'disable-replace' | 'replace' | 'additive'\n      }\n    }\n)\n\nexport type ModuleExtensionUnresolvedFact = {\n  key: string\n  source: { path: string; symbol?: string }\n  reason:\n    | 'unclassified-binding'\n    | 'unbound-declaration'\n    | 'dynamic-without-pattern'\n    | 'unresolved-first-party-target'\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["export const EXTENSION_HOST_FAMILIES = [\n  'generic',\n  'menu',\n  'data-table',\n  'crud-form',\n  'detail',\n  'portal-page',\n  'component-handle',\n  'entity',\n  'api-route',\n  'command',\n  'event',\n  'query-lifecycle',\n  'dashboard',\n  'notification',\n  'integration',\n  'specialized-registry',\n  'module-override',\n] as const\n\nexport type ExtensionHostFamily = (typeof EXTENSION_HOST_FAMILIES)[number]\n\nexport const EXTENSION_HOST_CAPABILITIES = [\n  'render-widget',\n  'headless-widget',\n  'menu-item',\n  'column-widget',\n  'row-action',\n  'bulk-action',\n  'filter-widget',\n  'toolbar-widget',\n  'field-widget',\n  'lifecycle-handler',\n  'component-replacement',\n  'response-enricher',\n  'query-enricher',\n  'api-interceptor',\n  'command-interceptor',\n  'mutation-guard',\n  'entity-extension',\n  'async-subscriber',\n  'sync-subscriber',\n  'browser-client',\n  'browser-portal',\n  'registry-contribution',\n  'module-override',\n] as const\n\nexport type ExtensionHostCapability = (typeof EXTENSION_HOST_CAPABILITIES)[number]\n\nexport const EXTENSION_HOST_ACTIVATIONS = ['always', 'host-opt-in', 'caller-opt-in', 'feature-gated'] as const\n\nexport type ExtensionHostActivation = (typeof EXTENSION_HOST_ACTIVATIONS)[number]\n\nexport type ExtensionPointPatternParameter = {\n  source: string\n  pattern?: string\n}\n\ntype ExtensionHostDeclarationBase = {\n  source: string\n  contextContract?: string\n  dataContract?: string\n  scopeContract?: string\n  runtimeContract?: string\n  activation?: ExtensionHostActivation\n  aliases?: readonly string[]\n  fallbacks?: readonly string[]\n}\n\ntype InjectionExtensionHostDeclarationBase = ExtensionHostDeclarationBase & {\n  family: Exclude<ExtensionHostFamily, 'data-table' | 'crud-form' | 'component-handle'>\n  supported: readonly ExtensionHostCapability[]\n}\n\nexport type InjectionExtensionHostDeclaration = InjectionExtensionHostDeclarationBase & (\n  | {\n      spotId: string\n      pattern?: never\n      parameters?: never\n    }\n  | {\n      spotId?: never\n      pattern: string\n      parameters: Readonly<Record<string, ExtensionPointPatternParameter>>\n    }\n)\n\nexport type DataTableExtensionHostDeclaration = ExtensionHostDeclarationBase & {\n  family: 'data-table'\n  tableId: string\n  baseSpotId?: string\n}\n\nexport type CrudFormExtensionHostDeclaration = ExtensionHostDeclarationBase & {\n  family: 'crud-form'\n  entityId: string\n  spotId?: string\n}\n\nexport type ComponentExtensionHostDeclaration = ExtensionHostDeclarationBase & {\n  family: 'component-handle'\n  componentId: string\n  propsContract?: string\n}\n\nexport type ModuleExtensionHostDeclaration =\n  | InjectionExtensionHostDeclaration\n  | DataTableExtensionHostDeclaration\n  | CrudFormExtensionHostDeclaration\n  | ComponentExtensionHostDeclaration\n\nexport type ModuleExtensionPoints<\n  TModuleId extends string = string,\n  THosts extends Readonly<Record<string, ModuleExtensionHostDeclaration>> = Readonly<Record<string, ModuleExtensionHostDeclaration>>,\n> = {\n  moduleId: TModuleId\n  hosts: THosts\n}\n\nexport function defineModuleExtensionPoints<\n  const TModuleId extends string,\n  const THosts extends Readonly<Record<string, ModuleExtensionHostDeclaration>>,\n>(declaration: ModuleExtensionPoints<TModuleId, THosts>): ModuleExtensionPoints<TModuleId, THosts> {\n  return Object.freeze({\n    ...declaration,\n    hosts: Object.freeze({ ...declaration.hosts }),\n  })\n}\n\nexport function injectionExtensionHost<const TDeclaration extends InjectionExtensionHostDeclaration>(\n  declaration: TDeclaration,\n): Readonly<TDeclaration> {\n  const hasExactId = typeof declaration.spotId === 'string' && declaration.spotId.length > 0\n  const hasPattern = typeof declaration.pattern === 'string' && declaration.pattern.length > 0\n  if (hasExactId === hasPattern) {\n    throw new Error('[internal] injection extension hosts require exactly one of spotId or pattern')\n  }\n  if (hasPattern && (!declaration.parameters || Object.keys(declaration.parameters).length === 0)) {\n    throw new Error('[internal] patterned injection extension hosts require named parameters')\n  }\n  return Object.freeze({ ...declaration })\n}\n\nexport function dataTableExtensionHost<\n  const TDeclaration extends Omit<DataTableExtensionHostDeclaration, 'family'>,\n>(\n  declaration: TDeclaration,\n): Readonly<TDeclaration & { family: 'data-table' }> {\n  return Object.freeze({ family: 'data-table', ...declaration })\n}\n\nexport function crudFormExtensionHost<\n  const TDeclaration extends Omit<CrudFormExtensionHostDeclaration, 'family'>,\n>(\n  declaration: TDeclaration,\n): Readonly<TDeclaration & { family: 'crud-form' }> {\n  return Object.freeze({ family: 'crud-form', ...declaration })\n}\n\nexport function componentExtensionHost<\n  const TDeclaration extends Omit<ComponentExtensionHostDeclaration, 'family'>,\n>(\n  declaration: TDeclaration,\n): Readonly<TDeclaration & { family: 'component-handle' }> {\n  return Object.freeze({ family: 'component-handle', ...declaration })\n}\n\nexport type BoundExtensionSurface = {\n  key: string\n  suffix: string | null\n  capabilities: readonly ExtensionHostCapability[]\n  bound: boolean\n  phases?: readonly string[]\n  operations?: readonly string[]\n}\n\nexport const DATA_TABLE_EXTENSION_SURFACES = [\n  { key: 'header', suffix: 'header', capabilities: ['render-widget'], bound: true },\n  { key: 'footer', suffix: 'footer', capabilities: ['render-widget'], bound: true },\n  { key: 'toolbar', suffix: 'toolbar', capabilities: ['toolbar-widget'], bound: true },\n  { key: 'searchTrailing', suffix: 'search-trailing', capabilities: ['render-widget'], bound: true },\n  { key: 'columns', suffix: 'columns', capabilities: ['column-widget'], bound: true },\n  { key: 'rowActions', suffix: 'row-actions', capabilities: ['row-action'], bound: true },\n  { key: 'bulkActions', suffix: 'bulk-actions', capabilities: ['bulk-action'], bound: true },\n  { key: 'filters', suffix: 'filters', capabilities: ['filter-widget'], bound: true },\n  { key: 'replacement', suffix: null, capabilities: ['component-replacement'], bound: true },\n  { key: 'emptyState', suffix: 'empty-state', capabilities: ['render-widget'], bound: false },\n] as const satisfies readonly BoundExtensionSurface[]\n\nexport const DATA_TABLE_EXTENSION_SURFACE_KEYS = DATA_TABLE_EXTENSION_SURFACES.map((surface) => surface.key)\n\nexport const CRUD_FORM_EXTENSION_SURFACES = [\n  { key: 'base', suffix: null, capabilities: ['render-widget', 'lifecycle-handler'], bound: true },\n  { key: 'header', suffix: 'header', capabilities: ['render-widget'], bound: true },\n  { key: 'fields', suffix: 'fields', capabilities: ['field-widget'], bound: true },\n  { key: 'replacement', suffix: null, capabilities: ['component-replacement'], bound: true },\n  { key: 'beforeFields', suffix: 'before-fields', capabilities: ['render-widget'], bound: false },\n  { key: 'afterFields', suffix: 'after-fields', capabilities: ['render-widget'], bound: false },\n  { key: 'footer', suffix: 'footer', capabilities: ['render-widget'], bound: false },\n  { key: 'sidebar', suffix: 'sidebar', capabilities: ['render-widget'], bound: false },\n  { key: 'group', suffix: 'group:{groupId}', capabilities: ['render-widget'], bound: false },\n  { key: 'fieldBefore', suffix: 'field:{fieldId}:before', capabilities: ['render-widget'], bound: false },\n  { key: 'fieldAfter', suffix: 'field:{fieldId}:after', capabilities: ['render-widget'], bound: false },\n] as const satisfies readonly BoundExtensionSurface[]\n\nexport const CRUD_FORM_EXTENSION_SURFACE_KEYS = CRUD_FORM_EXTENSION_SURFACES.map((surface) => surface.key)\n\nexport const CRUD_FORM_LIFECYCLE_PHASES = [\n  'transformValidation',\n  'transformDisplayData',\n  'onBeforeNavigate',\n  'onAppEvent',\n  'onVisibilityChange',\n  'onBeforeDelete',\n  'onDelete',\n  'onAfterDelete',\n  'onDeleteError',\n  'onFieldChange',\n  'transformFormData',\n  'onBeforeSave',\n  'onSave',\n  'onAfterSave',\n] as const\n\nexport const CRUD_FORM_OPERATIONS = ['create', 'update', 'delete'] as const\n\nexport function dataTableExtensionSpotId(tableId: string, suffix?: string): string {\n  return suffix ? `data-table:${tableId}:${suffix}` : `data-table:${tableId}`\n}\n\nexport function crudFormExtensionSpotId(entityId: string, suffix?: string): string {\n  return suffix ? `crud-form:${entityId}:${suffix}` : `crud-form:${entityId}`\n}\n\nexport function extensionSpotChildId(spotId: string, suffix: string): string {\n  return `${spotId}:${suffix}`\n}\n\nexport function resolveExtensionPointPattern(\n  pattern: string,\n  parameters: Readonly<Record<string, string>>,\n): string {\n  return pattern.replace(/\\{([^}]+)\\}/g, (token, parameterName: string) => parameters[parameterName] ?? token)\n}\n\n/**\n * Portable, structural copy of the CLI provenance source reference\n * (`ModuleFactSourceRef` in `packages/cli/.../module-facts.ts`). Redefined here\n * \u2014 rather than imported \u2014 so `@open-mercato/shared` keeps zero dependency on\n * `@open-mercato/cli`. Field names are kept byte-identical so the two are\n * assignable across the package boundary.\n */\nexport type ModuleFactSourceRef = {\n  sourcePath: string\n  exportName?: string\n  line?: number\n}\n\n/** Portable, structural copy of the CLI provenance fact reference. */\nexport type ModuleFactRef = {\n  factSection: string\n  factKey: string\n}\n\nexport const MODULE_EXTENSION_CONTRIBUTION_KINDS = [\n  'widget',\n  'data-table',\n  'crud-form',\n  'component-override',\n  'response-enricher',\n  'api-interceptor',\n  'command-interceptor',\n  'mutation-guard',\n  'entity-extension',\n  'subscriber',\n  'browser-reaction',\n  'specialized-registry',\n  'module-override',\n] as const\n\nexport type ModuleExtensionContributionKind = (typeof MODULE_EXTENSION_CONTRIBUTION_KINDS)[number]\n\nexport const MODULE_EXTENSION_ACTIVATION_KINDS = [\n  'crud-response-enricher',\n  'query-enricher',\n  'mutation-guard',\n  'api-interceptor-bridge',\n  'command-interceptor-bridge',\n  'widget-injection-consumer',\n  'component-extension-consumer',\n  'dashboard-host-consumer',\n] as const\n\nexport type ModuleExtensionActivationKind = (typeof MODULE_EXTENSION_ACTIVATION_KINDS)[number]\n\nexport const MODULE_EXTENSION_TARGET_KINDS = [\n  'module',\n  'entity',\n  'api-route',\n  'command',\n  'widget-spot',\n  'component',\n  'event',\n  'notification',\n  'wildcard',\n] as const\n\nexport type ModuleExtensionTargetKind = (typeof MODULE_EXTENSION_TARGET_KINDS)[number]\n\nexport type ModuleExtensionTargetRef = {\n  kind: ModuleExtensionTargetKind\n  id: string\n  moduleId?: string\n  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'\n}\n\nexport type ModuleExtensionActivation = {\n  id: string\n  kind: ModuleExtensionActivationKind\n  host: ModuleExtensionTargetRef\n  contributionKinds: ModuleExtensionContributionKind[]\n  phases?: string[]\n  /**\n   * Mutation operations the call site guards, when statically declared. A\n   * contribution declaring only other operations is not bound by this activation.\n   */\n  operations?: string[]\n  source: ModuleFactSourceRef\n  bridge?: ModuleFactRef\n}\n\nexport const MODULE_EXTENSION_RESOLUTIONS = [\n  'bound',\n  'capability-only',\n  'optional-target-missing',\n  'wildcard',\n  'unresolved',\n] as const\n\nexport type ModuleExtensionResolution = (typeof MODULE_EXTENSION_RESOLUTIONS)[number]\n\nexport type ModuleIncomingExtensionRef = {\n  contributionId: string\n  contributionKind: ModuleExtensionContributionKind\n  contributorModuleId: string\n  target: ModuleExtensionTargetRef\n  activationId?: string\n  resolution: ModuleExtensionResolution\n  source: ModuleFactSourceRef\n}\n\nexport type ModuleContributionResolution = {\n  contributionId: string\n  target: ModuleExtensionTargetRef\n  resolution: ModuleExtensionResolution\n  activationIds: string[]\n}\n\n/**\n * Additive, optional bidirectional-topology fields layered on top of the\n * existing extension-surface facts. Every field is optional so legacy consumers\n * and pre-existing generated output remain byte-compatible.\n */\nexport type ModuleExtensionSurfaceFactsAdditions = {\n  activations?: ModuleExtensionActivation[]\n  incoming?: ModuleIncomingExtensionRef[]\n  contributionResolutions?: ModuleContributionResolution[]\n}\n\nexport type ModuleExtensionSurfaceFacts = {\n  hosts: ModuleExtensionHostFact[]\n  contributions: ModuleExtensionContributionFact[]\n  unresolved: ModuleExtensionUnresolvedFact[]\n} & ModuleExtensionSurfaceFactsAdditions\n\nexport const MODULE_EXTENSION_HOST_RESOLUTIONS = ['exact', 'pattern', 'framework', 'fact-ref'] as const\n\nexport type ModuleExtensionHostResolution = (typeof MODULE_EXTENSION_HOST_RESOLUTIONS)[number]\n\nexport type ModuleExtensionHostFact = {\n  key: string\n  id: string\n  resolution: ModuleExtensionHostResolution\n  family: ExtensionHostFamily\n  ownerModule: string\n  capabilities: ExtensionHostCapability[]\n  phases?: string[]\n  operations?: string[]\n  contextContract?: string\n  dataContract?: string\n  scopeContract?: string\n  runtimeContract?: string\n  activation?: ExtensionHostActivation\n  bound: boolean\n  stability: 'frozen' | 'stable'\n  source:\n    | { kind: 'declaration'; path: string; symbol: string }\n    | { kind: 'fact-ref'; factSection: string; factKey: string }\n    | { kind: 'framework'; path: string; symbol: string }\n  aliases?: string[]\n  patternParameters?: Record<string, ExtensionPointPatternParameter>\n  fallbacks?: string[]\n}\n\nexport const MODULE_EXTENSION_TARGET_RESOLUTIONS = [\n  'exact',\n  'pattern',\n  'framework',\n  'fact-ref',\n  'optional-external',\n  'unresolved',\n] as const\n\nexport type ModuleExtensionTargetResolution = (typeof MODULE_EXTENSION_TARGET_RESOLUTIONS)[number]\n\nexport type ModuleExtensionTargetFact = {\n  id: string\n  resolution: ModuleExtensionTargetResolution\n  factRef?: { factSection: string; factKey: string }\n  optionalOwnerPackage?: string\n}\n\nexport type ModuleExtensionContributionBase = {\n  id: string\n  targets: ModuleExtensionTargetFact[]\n  phases?: string[]\n  operations?: string[]\n  features?: string[]\n  scopeContract: string\n  activation?: ExtensionHostActivation\n  placement?: { relativeTo?: string; position?: 'first' | 'last' | 'before' | 'after'; priority?: number }\n  roundTripId?: string\n  override?: { domain: string; key: string; mode: 'disable-replace' | 'replace' | 'additive' }\n  source: { path: string; symbol?: string }\n}\n\nexport const MODULE_SPECIALIZED_REGISTRIES = [\n  'notification',\n  'integration',\n  'search',\n  'vector',\n  'ai',\n  'payment',\n  'shipping',\n  'currency',\n  'workflow',\n] as const\n\nexport type ModuleSpecializedRegistry = (typeof MODULE_SPECIALIZED_REGISTRIES)[number]\n\nexport const COMPONENT_OVERRIDE_MODES = ['replace', 'wrapper', 'props'] as const\n\nexport type ModuleComponentOverrideMode = (typeof COMPONENT_OVERRIDE_MODES)[number]\n\nexport type ModuleExtensionContributionFact = ModuleExtensionContributionBase & (\n  | {\n      kind: 'widget'\n      details: {\n        payload: 'render' | 'headless' | 'menu' | 'dashboard' | 'notification' | 'integration'\n        registryKey: string\n        itemIds?: string[]\n        labelKeys?: string[]\n        contextContract?: string\n        dataContract?: string\n        executionGuard: 'host' | 'contribution' | 'both'\n      }\n    }\n  | {\n      kind: 'data-table'\n      details: {\n        payload: 'column' | 'row-action' | 'bulk-action' | 'filter' | 'toolbar' | 'render'\n        tableId: string\n        executionGuard: 'host' | 'contribution' | 'both'\n      }\n    }\n  | {\n      kind: 'crud-form'\n      details: {\n        payload: 'render' | 'field' | 'lifecycle-handler'\n        entityId: string\n        fieldIds?: string[]\n        groupIds?: string[]\n        requestHeaderCapability: boolean\n      }\n    }\n  | {\n      kind: 'component-override'\n      details: { handle: string; mode: ModuleComponentOverrideMode; propsContract: string }\n    }\n  | {\n      kind: 'response-enricher'\n      details: {\n        targetEntity: string\n        surfaces: Array<'list' | 'detail'>\n        timeoutMs: number\n        fallback: 'none' | 'configured'\n        critical: boolean\n        cachePosture: 'record-pure' | 'rerun-on-list-cache-hit'\n        queryEngine?: {\n          engines: string[]\n          applyOn: Array<'list' | 'detail'>\n          activation: 'caller-opt-in'\n        }\n      }\n    }\n  | {\n      kind: 'api-interceptor'\n      details: {\n        route: string\n        methods: string[]\n        phases: Array<'before' | 'after'>\n        activation: 'crud-pipeline' | 'custom-route-bridge'\n        timeoutMs: number\n        failurePosture: 'fail-closed' | 'fallback'\n      }\n    }\n  | {\n      kind: 'command-interceptor'\n      details: {\n        targetCommand: string\n        phases: Array<'before-execute' | 'after-execute' | 'before-undo' | 'after-undo'>\n      }\n    }\n  | {\n      kind: 'mutation-guard'\n      details: {\n        entityId: string\n        operations: Array<'create' | 'update' | 'delete'>\n        capabilities: Array<'block' | 'rewrite' | 'after-success'>\n        optimisticLock: 'preserved'\n      }\n    }\n  | {\n      kind: 'entity-extension'\n      details: {\n        hostEntityId: string\n        extensionEntityId: string\n        linkId: string\n        scopeContract: string\n        orphanContract: string\n      }\n    }\n  | {\n      kind: 'subscriber'\n      details: {\n        event: string\n        subscriberId: string\n        persistent: boolean\n        sync: boolean\n        priority?: number\n      }\n    }\n  | {\n      kind: 'browser-reaction'\n      details: {\n        transports: Array<'client' | 'portal' | 'notification-effect'>\n        hooks: string[]\n        audienceScopeContract: string\n        maxPayloadBytes?: number\n        dedupWindowMs?: number\n        /**\n         * Statically declared handler id. Runtime keys `notifications.handlers`\n         * overrides by it, so it is absent when the module declares no id (such a\n         * handler cannot be overridden).\n         */\n        overrideKey?: string\n      }\n    }\n  | {\n      kind: 'specialized-registry'\n      details: {\n        registry: ModuleSpecializedRegistry\n        registryId: string\n        specialistRoute: string\n      }\n    }\n  | {\n      kind: 'module-override'\n      details: {\n        domain: string\n        key: string\n        mode: 'disable-replace' | 'replace' | 'additive'\n      }\n    }\n)\n\nexport const MODULE_EXTENSION_UNRESOLVED_REASONS = [\n  'unclassified-binding',\n  'unbound-declaration',\n  'dynamic-without-pattern',\n  'unresolved-first-party-target',\n] as const\n\nexport type ModuleExtensionUnresolvedReason = (typeof MODULE_EXTENSION_UNRESOLVED_REASONS)[number]\n\nexport type ModuleExtensionUnresolvedFact = {\n  key: string\n  source: { path: string; symbol?: string }\n  reason: ModuleExtensionUnresolvedReason\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/shared",
-  "version": "0.6.8-develop.6930.1.1e5976efc3",
+  "version": "0.6.8-develop.6940.1.177ea30c6e",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -105,7 +105,7 @@
     "@mikro-orm/core": "^7.1.8",
     "@mikro-orm/decorators": "^7.1.8",
     "@mikro-orm/postgresql": "^7.1.8",
-    "@open-mercato/cache": "0.6.8-develop.6930.1.1e5976efc3",
+    "@open-mercato/cache": "0.6.8-develop.6940.1.177ea30c6e",
     "@types/sanitize-html": "^2.16.1",
     "dotenv": "^17.4.2",
     "pino": "^10.3.1",

package/src/lib/auth/__tests__/server.test.ts

@@ -185,3 +185,64 @@ describe('auth server integrity checks', () => {
     await expect(resolveAuthFromRequestDetailed(request)).resolves.toEqual({ auth: null, status: 'missing' })
   })
 })
+
+describe('super-admin tenant cookie override', () => {
+  const ACTOR_TENANT = '22222222-2222-4222-8222-222222222222'
+  const OTHER_TENANT = '44444444-4444-4444-8444-444444444444'
+
+  const superAdminAuth = {
+    sub: '11111111-1111-4111-8111-111111111111',
+    tenantId: ACTOR_TENANT,
+    orgId: '33333333-3333-4333-8333-333333333333',
+    roles: ['superadmin'],
+    isSuperAdmin: true,
+  }
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+    cookieStore.get.mockReset()
+    createRequestContainer.mockResolvedValue({
+      resolve: (name: string) => (name === 'em' ? em : null),
+    })
+    verifyJwt.mockReturnValue(superAdminAuth)
+    resolveCanonicalStaffAuthContext.mockResolvedValue(superAdminAuth)
+  })
+
+  async function authFor(cookie: string) {
+    const { getAuthFromRequest } = await import('@open-mercato/shared/lib/auth/server')
+    return getAuthFromRequest(new Request('https://example.test/api/test', { headers: { cookie } }))
+  }
+
+  it.each([
+    ['blank', 'om_selected_tenant='],
+    ['whitespace-only', 'om_selected_tenant=%20%20'],
+  ])('treats a %s tenant cookie as no selection and keeps the tenant from the token', async (_label, tenantCookie) => {
+    const auth = await authFor(`auth_token=jwt-token; ${tenantCookie}`)
+
+    expect(auth?.tenantId).toBe(ACTOR_TENANT)
+    expect(auth).not.toHaveProperty('actorTenantId')
+  })
+
+  it('still applies a concrete tenant selection and preserves the actor tenant', async () => {
+    const auth = await authFor(`auth_token=jwt-token; om_selected_tenant=${OTHER_TENANT}`)
+
+    expect(auth?.tenantId).toBe(OTHER_TENANT)
+    expect((auth as { actorTenantId?: string | null }).actorTenantId).toBe(ACTOR_TENANT)
+  })
+
+  it('leaves the organization override working when the tenant cookie is blank', async () => {
+    const auth = await authFor('auth_token=jwt-token; om_selected_tenant=; om_selected_org=__all__')
+
+    expect(auth?.tenantId).toBe(ACTOR_TENANT)
+    expect(auth?.orgId).toBeNull()
+    expect((auth as { actorOrgId?: string | null }).actorOrgId).toBe(superAdminAuth.orgId)
+  })
+
+  it('leaves a non-super-admin session untouched by a blank tenant cookie', async () => {
+    const staffAuth = { ...superAdminAuth, roles: ['employee'], isSuperAdmin: false }
+    verifyJwt.mockReturnValue(staffAuth)
+    resolveCanonicalStaffAuthContext.mockResolvedValue(staffAuth)
+
+    await expect(authFor('auth_token=jwt-token; om_selected_tenant=')).resolves.toEqual(staffAuth)
+  })
+})

package/src/lib/auth/server.ts

@@ -98,12 +98,22 @@ function readCookieFromHeader(header: string | null | undefined, name: string):
   return undefined
 }
 
+/**
+ * A blank `om_selected_tenant` is "no selection", not a deliberate "no tenant".
+ *
+ * Unlike the organization cookie there is no all-tenants sentinel to express, and the tenant
+ * selector renders with `includeEmptyOption={false}`, so no UI produces a blank value. Treating it
+ * as an applied override nulled `tenantId` for the whole super-admin session, which is what turned
+ * a cosmetic client bug into `tenantId ?? ''` reaching a NOT NULL uuid column. Reporting the
+ * override as not applied instead keeps the tenant carried in the token and remediates an
+ * already-poisoned browser on its next request, whatever wrote the cookie.
+ */
 function resolveTenantOverride(raw: string | undefined): CookieOverride {
   if (raw === undefined) return { applied: false, value: null }
   const decoded = decodeCookieValue(raw)
-  if (!decoded) return { applied: true, value: null }
+  if (!decoded) return { applied: false, value: null }
   const trimmed = decoded.trim()
-  if (!trimmed) return { applied: true, value: null }
+  if (!trimmed) return { applied: false, value: null }
   return { applied: true, value: trimmed }
 }
 

package/src/lib/bootstrap/dynamicLoader.ts

@@ -358,20 +358,54 @@ type CompileAndImportOptions = {
 }
 
 /**
- * Compile a TypeScript file to JavaScript using esbuild bundler.
- * This bundles the file and all its dependencies, handling JSON imports properly.
- * The compiled file is written next to the source file with a .mjs extension unless
- * `outFile` says otherwise.
+ * Options for `compileAppSourceFile`.
+ *
+ * `appRoot` anchors the tsconfig, the `@/` alias resolution and the dependency
+ * cache; `outFile` is the absolute path of the artifact to write. `format`
+ * selects the module system of that artifact — `'cjs'` exists for the Jest
+ * runtime, which cannot `import()` an ESM sibling.
  */
-async function compileAndImport(
+export type CompileAppSourceOptions = {
+  appRoot: string
+  outFile: string
+  format?: 'esm' | 'cjs'
+}
+
+/**
+ * Compile one app-owned TypeScript source and its relative import graph into a
+ * single JavaScript artifact, leaving every package import external.
+ *
+ * This is the only supported way to load app source (`apps/<app>/src/**`,
+ * `.mercato/generated/**`) from a plain Node process. Those files are never
+ * compiled to `dist`, and Node's own type stripping cannot load them: it
+ * requires explicit file extensions on relative specifiers and rejects the
+ * decorator and enum syntax the entities and DI files use.
+ *
+ * The artifact is cached against the content of the entry, its whole bundled
+ * dependency graph, and the tsconfig chain, so an edit anywhere in the graph
+ * invalidates it.
+ *
+ * The build runs inside the shared esbuild lifecycle. Callers outside a
+ * bootstrap load — the generated-registry loader compiling an `@app` module —
+ * would otherwise hold a build on a service another scope is entitled to
+ * `stop()`, and would leave the helper process running afterwards. Nesting is
+ * safe: the scope only releases the service when the last participant exits.
+ */
+export async function compileAppSourceFile(
   tsPath: string,
-  options: CompileAndImportOptions = {},
-): Promise<Record<string, unknown>> {
-  const allowRecovery = options.allowRecovery ?? true
-  const jsPath = options.outFile ?? tsPath.replace(/\.ts$/, '.mjs')
-  const appRoot = options.appRoot ?? path.dirname(path.dirname(path.dirname(tsPath)))
+  options: CompileAppSourceOptions,
+): Promise<string> {
+  return withEsbuildLifecycle(() => compileAppSourceFileWithActiveEsbuild(tsPath, options))
+}
+
+async function compileAppSourceFileWithActiveEsbuild(
+  tsPath: string,
+  options: CompileAppSourceOptions,
+): Promise<string> {
+  const { appRoot, outFile } = options
+  const format = options.format ?? 'esm'
   const appTsconfig = path.join(appRoot, 'tsconfig.json')
-  const metadataPath = cacheMetadataPath(jsPath)
+  const metadataPath = cacheMetadataPath(outFile)
 
   const tsExists = fs.existsSync(tsPath)
   const tsconfigExists = fs.existsSync(appTsconfig)
@@ -385,39 +419,59 @@ async function compileAndImport(
 
   const tsconfigPaths = collectTsconfigPaths(appTsconfig)
   const expectedInputHash = cacheInputHash(tsPath, appRoot, tsconfigPaths)
-  const needsCompile = !cacheIsValid(appRoot, jsPath, metadataPath, expectedInputHash)
-
-  if (needsCompile) {
-    fs.mkdirSync(path.dirname(jsPath), { recursive: true })
-    // Dynamically import esbuild only when needed
-    const esbuild = await getEsbuildRuntime()
-
-    // Use esbuild.build with bundling to handle JSON imports
-    const result = await esbuild.build({
-      entryPoints: [tsPath],
-      outfile: jsPath,
-      absWorkingDir: appRoot,
-      bundle: true,
-      metafile: true,
-      format: 'esm',
-      platform: 'node',
-      target: 'node18',
-      tsconfig: appTsconfig,
-      plugins: createCliBundlePlugins(appRoot),
-      // Allow JSON imports
-      loader: { '.json': 'json' },
-    })
-    const metadata: DynamicLoaderCacheMetadata = {
-      version: DYNAMIC_LOADER_CACHE_VERSION,
-      inputHash: expectedInputHash,
-      outputHash: contentHash(fs.readFileSync(jsPath)),
-      dependencies: {
-        ...collectDependencyHashes(appRoot, result.metafile.inputs),
-        ...hashFilesRelativeTo(appRoot, tsconfigPaths),
-      },
-    }
-    fs.writeFileSync(metadataPath, JSON.stringify(metadata))
+
+  if (cacheIsValid(appRoot, outFile, metadataPath, expectedInputHash)) {
+    return outFile
+  }
+
+  fs.mkdirSync(path.dirname(outFile), { recursive: true })
+  // Dynamically import esbuild only when needed
+  const esbuild = await getEsbuildRuntime()
+
+  // Use esbuild.build with bundling to handle JSON imports
+  const result = await esbuild.build({
+    entryPoints: [tsPath],
+    outfile: outFile,
+    absWorkingDir: appRoot,
+    bundle: true,
+    metafile: true,
+    format,
+    platform: 'node',
+    target: 'node18',
+    tsconfig: appTsconfig,
+    plugins: createCliBundlePlugins(appRoot),
+    // Allow JSON imports
+    loader: { '.json': 'json' },
+  })
+  const metadata: DynamicLoaderCacheMetadata = {
+    version: DYNAMIC_LOADER_CACHE_VERSION,
+    inputHash: expectedInputHash,
+    outputHash: contentHash(fs.readFileSync(outFile)),
+    dependencies: {
+      ...collectDependencyHashes(appRoot, result.metafile.inputs),
+      ...hashFilesRelativeTo(appRoot, tsconfigPaths),
+    },
   }
+  fs.writeFileSync(metadataPath, JSON.stringify(metadata))
+
+  return outFile
+}
+
+/**
+ * Compile a TypeScript file to JavaScript using esbuild bundler.
+ * This bundles the file and all its dependencies, handling JSON imports properly.
+ * The compiled file is written next to the source file with a .mjs extension unless
+ * `outFile` says otherwise.
+ */
+async function compileAndImport(
+  tsPath: string,
+  options: CompileAndImportOptions = {},
+): Promise<Record<string, unknown>> {
+  const allowRecovery = options.allowRecovery ?? true
+  const jsPath = options.outFile ?? tsPath.replace(/\.ts$/, '.mjs')
+  const appRoot = options.appRoot ?? path.dirname(path.dirname(path.dirname(tsPath)))
+
+  await compileAppSourceFile(tsPath, { appRoot, outFile: jsPath })
 
   // Import the compiled JavaScript
   try {

package/src/lib/crud/__tests__/crud-factory.test.ts

@@ -585,6 +585,45 @@ describe('CRUD Factory', () => {
     expect(ids).toContain(otherTenant.id)
   })
 
+  it('GET resolves function-form CSV headers and rows per request', async () => {
+    // Regression coverage for the additive `(query, ctx)` form of `ListConfig.csv`.
+    // A route whose export columns depend on per-request discovery (custom-field keys,
+    // for example) must resolve them from the request context, never from module-level
+    // state that the previous request left behind.
+    const perRequestColumns = new WeakMap<object, string>()
+    const dynamicCsvRoute = makeCrudRoute({
+      metadata: { GET: { requireAuth: true } },
+      orm: { entity: Todo, idField: 'id', orgField: 'organizationId', tenantField: 'tenantId', softDeleteField: 'deletedAt' },
+      indexer: { entityType: 'example.todo' },
+      list: {
+        schema: querySchema,
+        entityId: 'example.todo',
+        fields: ['id', 'title', 'is_done'],
+        sortFieldMap: { id: 'id' },
+        buildFilters: () => ({} as any),
+        transformItem: (item: any) => ({ id: item.id, title: item.title }),
+        allowCsv: true,
+        csv: {
+          headers: (_query, ctx) => ['id', perRequestColumns.get(ctx) ?? 'fallback'],
+          row: (item: any, ctx) => [item.id, `${perRequestColumns.get(ctx) ?? 'fallback'}:${item.title}`],
+          filename: 'dynamic.csv',
+        },
+      },
+      hooks: {
+        beforeList: (_query, ctx) => {
+          const column = new URL(ctx.request!.url).searchParams.get('column')
+          perRequestColumns.set(ctx, column ?? 'fallback')
+        },
+      },
+    })
+
+    const first = await dynamicCsvRoute.GET(new Request('http://x/api/example/todos?format=csv&column=alpha'))
+    const second = await dynamicCsvRoute.GET(new Request('http://x/api/example/todos?format=csv&column=beta'))
+
+    expect((await first.text()).split('\n')[0]).toBe('id,alpha')
+    expect((await second.text()).split('\n')[0]).toBe('id,beta')
+  })
+
   it('GET returns CSV when format=csv', async () => {
     const res = await route.GET(new Request('http://x/api/example/todos?page=1&pageSize=10&sortField=id&sortDir=asc&format=csv'))
     expect(res.headers.get('content-type')).toContain('text/csv')