@entifix/next-shell 0.4.2 → 0.6.0

package/dist/lib/command-palette/use-use-cases-source.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/lib/command-palette/use-use-cases-source.ts"],"sourcesContent":["'use client';\n\nimport {\n  type CommandOption,\n  type CommandSource,\n  EntifixLogicError,\n  type Entity,\n  type EntityConstructor,\n  type EntityMetadataSource,\n  envelopeEntityName,\n  matchesCommand,\n  parseKeywords,\n} from '@entifix/core';\nimport {\n  useCasesForSurface,\n  useT,\n  useTranslateKey,\n} from '@entifix/react-controls';\nimport { useEntityUseCases } from '@entifix/react-integration';\nimport { useMemo } from 'react';\n\n/** How a declared verb is actually carried out, keyed by the verb. */\nexport type UseCaseHandlers = Readonly<Record<string, () => Promise<void>>>;\n\n/**\n * One entity whose served affordances contribute palette commands.\n *\n * The source comes one of two ways, and exactly one: built and handed over, or\n * read from the host's composition by a hook — typically\n * `() => useHostAdapters().userMetadata` — so the module declaring the entries\n * need not import the transport that fetches.\n */\nexport type UseCaseCommandEntity<TEntity extends Entity = Entity> = {\n  readonly entityConstructor: EntityConstructor<TEntity>;\n  readonly handlers: UseCaseHandlers;\n} & (\n  | {\n      /** Where `GET /api/<entity>/$metadata` is reached. */\n      readonly metadataSource: EntityMetadataSource;\n      readonly useMetadataSource?: never;\n    }\n  | {\n      /** Resolves the source from composition. Called as a hook, once per render. */\n      readonly useMetadataSource: () => EntityMetadataSource;\n      readonly metadataSource?: never;\n    }\n);\n\n/**\n * The `unbound` verbs this caller may invoke, as one group.\n *\n * This is the surface ADR 0035 mapped and nothing rendered: all three\n * `unbound:*` cells resolve to `'command-palette'`, and until now the palette\n * did not exist, so a verb declared there was granted, exported, passed every\n * `@r10c/slices` invariant and simply never appeared.\n *\n * The descriptors are **served, not imported**: `$metadata` filters them through\n * `PolicyDecisionTag` against the verified principal, which is a stronger check\n * than anything the browser could do — and it keeps every `@useCase()` class's\n * `Effect` body, repository tags and import closure out of the client bundle.\n *\n * ⚠️ A descriptor with **no handler throws**, at the first render of the\n * palette rather than on the click. A verb that appears and does nothing is\n * worse than one that is absent: it reads as a broken feature rather than a\n * missing wire, and it is the same posture `assertSearchable` and `surfaceFor`\n * already take.\n */\nfunction useUseCasesSource(\n  entity: UseCaseCommandEntity,\n  term: string,\n): CommandSource {\n  const t = useT('shell');\n  const translateKey = useTranslateKey();\n  // The entries are module-scope, so which branch an entity takes never changes\n  // between renders and the hook count stays fixed.\n  const useSource = entity.useMetadataSource ?? (() => entity.metadataSource);\n  const { metadata, isLoading } = useEntityUseCases(\n    entity.entityConstructor,\n    useSource(),\n  );\n\n  // Outside the memo: `useCasesForSurface` is a plain filter, but the name reads\n  // as a hook to `react-hooks/rules-of-hooks`, which then refuses it inside a\n  // callback. Hoisting is free — it is pure and cheap.\n  const descriptors = useCasesForSurface('command-palette', metadata?.useCases);\n\n  return useMemo(() => {\n    const name = envelopeEntityName(entity.entityConstructor);\n\n    const options: CommandOption[] = descriptors.map(descriptor => {\n      const run = entity.handlers[descriptor.key];\n      if (run === undefined) {\n        throw new EntifixLogicError(\n          `The use case \"${descriptor.key}\" on ${name} reaches the command palette but this host registered no handler for it. ` +\n            'Add one to the entity’s `handlers`, or stop declaring the verb `unbound`.',\n          undefined,\n          { entity: name, key: descriptor.key },\n        );\n      }\n\n      return {\n        id: `use-case:${name}:${descriptor.key}`,\n        label: translateKey(descriptor.labelKey),\n        keywords: parseKeywords(\n          descriptor.keywordsKey === undefined\n            ? undefined\n            : translateKey(descriptor.keywordsKey),\n        ),\n        run,\n        ...(descriptor.confirm === undefined\n          ? {}\n          : {\n              confirm: {\n                tone: descriptor.confirm.tone,\n                message: translateKey(descriptor.confirm.messageKey),\n              },\n            }),\n      } satisfies CommandOption;\n    });\n\n    return {\n      key: `use-cases:${name}`,\n      groups: [\n        {\n          key: `use-cases:${name}`,\n          label: t('commandPalette.groups.actions'),\n          options: options.filter(option => matchesCommand(term, option)),\n          isLoading,\n        },\n      ],\n    } satisfies CommandSource;\n  }, [entity, descriptors, isLoading, term, t, translateKey]);\n}\n\n/**\n * Every declared entity's palette verbs, as one source per entity.\n *\n * **Why the rule is disabled below.** `entities` is declared once at module\n * scope by the host and closed over, so it is the same array on every render and\n * the hook count is fixed — the invariant `react-hooks/rules-of-hooks` protects\n * and cannot see, because it reasons about the loop syntactically rather than\n * about the array's provenance. It is isolated here so the disable is written\n * once, with its reason, exactly as `useEntityLinkSources` does for pickers.\n */\nexport function useUseCaseSources(\n  entities: readonly UseCaseCommandEntity[],\n  term: string,\n): CommandSource[] {\n  const sources: CommandSource[] = [];\n  for (const entity of entities) {\n    // eslint-disable-next-line react-hooks/rules-of-hooks -- fixed-length loop over a module-scope array; see the note above.\n    sources.push(useUseCasesSource(entity, term));\n  }\n  return sources;\n}\n"],"names":["EntifixLogicError","envelopeEntityName","matchesCommand","parseKeywords","useCasesForSurface","useT","useTranslateKey","useEntityUseCases","useMemo","useUseCasesSource","entity","term","t","translateKey","useSource","useMetadataSource","metadataSource","metadata","isLoading","entityConstructor","descriptors","useCases","name","options","map","descriptor","run","handlers","key","undefined","id","label","labelKey","keywords","keywordsKey","confirm","tone","message","messageKey","groups","filter","option","useUseCaseSources","entities","sources","push"],"mappings":"AAAA;;AAEA,SAGEA,iBAAiB,EAIjBC,kBAAkB,EAClBC,cAAc,EACdC,aAAa,QACR,gBAAgB;AACvB,SACEC,kBAAkB,EAClBC,IAAI,EACJC,eAAe,QACV,0BAA0B;AACjC,SAASC,iBAAiB,QAAQ,6BAA6B;AAC/D,SAASC,OAAO,QAAQ,QAAQ;AA6BhC;;;;;;;;;;;;;;;;;;CAkBC,GACD,SAASC,kBACPC,MAA4B,EAC5BC,IAAY;QAMMD;IAJlB,MAAME,IAAIP,KAAK;IACf,MAAMQ,eAAeP;IACrB,8EAA8E;IAC9E,kDAAkD;IAClD,MAAMQ,aAAYJ,4BAAAA,OAAOK,iBAAiB,YAAxBL,4BAA6B,IAAMA,OAAOM,cAAc;IAC1E,MAAM,EAAEC,QAAQ,EAAEC,SAAS,EAAE,GAAGX,kBAC9BG,OAAOS,iBAAiB,EACxBL;IAGF,+EAA+E;IAC/E,4EAA4E;IAC5E,qDAAqD;IACrD,MAAMM,cAAchB,mBAAmB,mBAAmBa,4BAAAA,SAAUI,QAAQ;IAE5E,OAAOb,QAAQ;QACb,MAAMc,OAAOrB,mBAAmBS,OAAOS,iBAAiB;QAExD,MAAMI,UAA2BH,YAAYI,GAAG,CAACC,CAAAA;YAC/C,MAAMC,MAAMhB,OAAOiB,QAAQ,CAACF,WAAWG,GAAG,CAAC;YAC3C,IAAIF,QAAQG,WAAW;gBACrB,MAAM,IAAI7B,kBACR,CAAC,cAAc,EAAEyB,WAAWG,GAAG,CAAC,KAAK,EAAEN,KAAK,yEAAyE,CAAC,GACpH,6EACFO,WACA;oBAAEnB,QAAQY;oBAAMM,KAAKH,WAAWG,GAAG;gBAAC;YAExC;YAEA,OAAO;gBACLE,IAAI,CAAC,SAAS,EAAER,KAAK,CAAC,EAAEG,WAAWG,GAAG,EAAE;gBACxCG,OAAOlB,aAAaY,WAAWO,QAAQ;gBACvCC,UAAU9B,cACRsB,WAAWS,WAAW,KAAKL,YACvBA,YACAhB,aAAaY,WAAWS,WAAW;gBAEzCR;eACID,WAAWU,OAAO,KAAKN,YACvB,CAAC,IACD;gBACEM,SAAS;oBACPC,MAAMX,WAAWU,OAAO,CAACC,IAAI;oBAC7BC,SAASxB,aAAaY,WAAWU,OAAO,CAACG,UAAU;gBACrD;YACF;QAER;QAEA,OAAO;YACLV,KAAK,CAAC,UAAU,EAAEN,MAAM;YACxBiB,QAAQ;gBACN;oBACEX,KAAK,CAAC,UAAU,EAAEN,MAAM;oBACxBS,OAAOnB,EAAE;oBACTW,SAASA,QAAQiB,MAAM,CAACC,CAAAA,SAAUvC,eAAeS,MAAM8B;oBACvDvB;gBACF;aACD;QACH;IACF,GAAG;QAACR;QAAQU;QAAaF;QAAWP;QAAMC;QAAGC;KAAa;AAC5D;AAEA;;;;;;;;;CASC,GACD,OAAO,SAAS6B,kBACdC,QAAyC,EACzChC,IAAY;IAEZ,MAAMiC,UAA2B,EAAE;IACnC,KAAK,MAAMlC,UAAUiC,SAAU;QAC7B,0HAA0H;QAC1HC,QAAQC,IAAI,CAACpC,kBAAkBC,QAAQC;IACzC;IACA,OAAOiC;AACT"}
+{"version":3,"sources":["../../../src/lib/command-palette/use-use-cases-source.ts"],"sourcesContent":["'use client';\n\nimport {\n  type CommandOption,\n  type CommandSource,\n  EntifixLogicError,\n  type Entity,\n  type EntityConstructor,\n  type EntityMetadataSource,\n  envelopeEntityName,\n  matchesCommand,\n  parseKeywords,\n} from '@entifix/core';\nimport {\n  useCasesForSurface,\n  useT,\n  useTranslateKey,\n} from '@entifix/react-controls';\nimport { useEntityUseCases } from '@entifix/react-integration';\nimport { useMemo } from 'react';\n\n/** How a declared verb is actually carried out, keyed by the verb. */\nexport type UseCaseHandlers = Readonly<Record<string, () => Promise<void>>>;\n\n/**\n * One entity whose served affordances contribute palette commands.\n *\n * The source comes one of two ways, and exactly one: built and handed over, or\n * read from the host's composition by a hook — typically\n * `() => useHostAdapters().userMetadata` — so the module declaring the entries\n * need not import the transport that fetches.\n */\nexport type UseCaseCommandEntity<TEntity extends Entity = Entity> = {\n  readonly entityConstructor: EntityConstructor<TEntity>;\n  readonly handlers: UseCaseHandlers;\n} & (\n  | {\n      /** Where `GET /api/<entity>/$metadata` is reached. */\n      readonly metadataSource: EntityMetadataSource;\n      readonly useMetadataSource?: never;\n    }\n  | {\n      /** Resolves the source from composition. Called as a hook, once per render. */\n      readonly useMetadataSource: () => EntityMetadataSource;\n      readonly metadataSource?: never;\n    }\n);\n\n/**\n * The `unbound` verbs this caller may invoke, as one group.\n *\n * This is the surface the action placement map named and nothing rendered: all three\n * `unbound:*` cells resolve to `'command-palette'`, and until now the palette\n * did not exist, so a verb declared there was granted, exported, passed every\n * check the host's register ran and simply never appeared.\n *\n * The descriptors are **served, not imported**: `$metadata` filters them through\n * `PolicyDecisionTag` against the verified principal, which is a stronger check\n * than anything the browser could do — and it keeps every `@useCase()` class's\n * `Effect` body, repository tags and import closure out of the client bundle.\n *\n * ⚠️ A descriptor with **no handler throws**, at the first render of the\n * palette rather than on the click. A verb that appears and does nothing is\n * worse than one that is absent: it reads as a broken feature rather than a\n * missing wire, and it is the same posture `assertSearchable` and `surfaceFor`\n * already take.\n */\nfunction useUseCasesSource(\n  entity: UseCaseCommandEntity,\n  term: string,\n): CommandSource {\n  const t = useT('shell');\n  const translateKey = useTranslateKey();\n  // The entries are module-scope, so which branch an entity takes never changes\n  // between renders and the hook count stays fixed.\n  const useSource = entity.useMetadataSource ?? (() => entity.metadataSource);\n  const { metadata, isLoading } = useEntityUseCases(\n    entity.entityConstructor,\n    useSource(),\n  );\n\n  // Outside the memo: `useCasesForSurface` is a plain filter, but the name reads\n  // as a hook to `react-hooks/rules-of-hooks`, which then refuses it inside a\n  // callback. Hoisting is free — it is pure and cheap.\n  const descriptors = useCasesForSurface('command-palette', metadata?.useCases);\n\n  return useMemo(() => {\n    const name = envelopeEntityName(entity.entityConstructor);\n\n    const options: CommandOption[] = descriptors.map(descriptor => {\n      const run = entity.handlers[descriptor.key];\n      if (run === undefined) {\n        throw new EntifixLogicError(\n          `The use case \"${descriptor.key}\" on ${name} reaches the command palette but this host registered no handler for it. ` +\n            'Add one to the entity’s `handlers`, or stop declaring the verb `unbound`.',\n          undefined,\n          { entity: name, key: descriptor.key },\n        );\n      }\n\n      return {\n        id: `use-case:${name}:${descriptor.key}`,\n        label: translateKey(descriptor.labelKey),\n        keywords: parseKeywords(\n          descriptor.keywordsKey === undefined\n            ? undefined\n            : translateKey(descriptor.keywordsKey),\n        ),\n        run,\n        ...(descriptor.confirm === undefined\n          ? {}\n          : {\n              confirm: {\n                tone: descriptor.confirm.tone,\n                message: translateKey(descriptor.confirm.messageKey),\n              },\n            }),\n      } satisfies CommandOption;\n    });\n\n    return {\n      key: `use-cases:${name}`,\n      groups: [\n        {\n          key: `use-cases:${name}`,\n          label: t('commandPalette.groups.actions'),\n          options: options.filter(option => matchesCommand(term, option)),\n          isLoading,\n        },\n      ],\n    } satisfies CommandSource;\n  }, [entity, descriptors, isLoading, term, t, translateKey]);\n}\n\n/**\n * Every declared entity's palette verbs, as one source per entity.\n *\n * **Why the rule is disabled below.** `entities` is declared once at module\n * scope by the host and closed over, so it is the same array on every render and\n * the hook count is fixed — the invariant `react-hooks/rules-of-hooks` protects\n * and cannot see, because it reasons about the loop syntactically rather than\n * about the array's provenance. It is isolated here so the disable is written\n * once, with its reason, exactly as `useEntityLinkSources` does for pickers.\n */\nexport function useUseCaseSources(\n  entities: readonly UseCaseCommandEntity[],\n  term: string,\n): CommandSource[] {\n  const sources: CommandSource[] = [];\n  for (const entity of entities) {\n    // eslint-disable-next-line react-hooks/rules-of-hooks -- fixed-length loop over a module-scope array; see the note above.\n    sources.push(useUseCasesSource(entity, term));\n  }\n  return sources;\n}\n"],"names":["EntifixLogicError","envelopeEntityName","matchesCommand","parseKeywords","useCasesForSurface","useT","useTranslateKey","useEntityUseCases","useMemo","useUseCasesSource","entity","term","t","translateKey","useSource","useMetadataSource","metadataSource","metadata","isLoading","entityConstructor","descriptors","useCases","name","options","map","descriptor","run","handlers","key","undefined","id","label","labelKey","keywords","keywordsKey","confirm","tone","message","messageKey","groups","filter","option","useUseCaseSources","entities","sources","push"],"mappings":"AAAA;;AAEA,SAGEA,iBAAiB,EAIjBC,kBAAkB,EAClBC,cAAc,EACdC,aAAa,QACR,gBAAgB;AACvB,SACEC,kBAAkB,EAClBC,IAAI,EACJC,eAAe,QACV,0BAA0B;AACjC,SAASC,iBAAiB,QAAQ,6BAA6B;AAC/D,SAASC,OAAO,QAAQ,QAAQ;AA6BhC;;;;;;;;;;;;;;;;;;CAkBC,GACD,SAASC,kBACPC,MAA4B,EAC5BC,IAAY;QAMMD;IAJlB,MAAME,IAAIP,KAAK;IACf,MAAMQ,eAAeP;IACrB,8EAA8E;IAC9E,kDAAkD;IAClD,MAAMQ,aAAYJ,4BAAAA,OAAOK,iBAAiB,YAAxBL,4BAA6B,IAAMA,OAAOM,cAAc;IAC1E,MAAM,EAAEC,QAAQ,EAAEC,SAAS,EAAE,GAAGX,kBAC9BG,OAAOS,iBAAiB,EACxBL;IAGF,+EAA+E;IAC/E,4EAA4E;IAC5E,qDAAqD;IACrD,MAAMM,cAAchB,mBAAmB,mBAAmBa,4BAAAA,SAAUI,QAAQ;IAE5E,OAAOb,QAAQ;QACb,MAAMc,OAAOrB,mBAAmBS,OAAOS,iBAAiB;QAExD,MAAMI,UAA2BH,YAAYI,GAAG,CAACC,CAAAA;YAC/C,MAAMC,MAAMhB,OAAOiB,QAAQ,CAACF,WAAWG,GAAG,CAAC;YAC3C,IAAIF,QAAQG,WAAW;gBACrB,MAAM,IAAI7B,kBACR,CAAC,cAAc,EAAEyB,WAAWG,GAAG,CAAC,KAAK,EAAEN,KAAK,yEAAyE,CAAC,GACpH,6EACFO,WACA;oBAAEnB,QAAQY;oBAAMM,KAAKH,WAAWG,GAAG;gBAAC;YAExC;YAEA,OAAO;gBACLE,IAAI,CAAC,SAAS,EAAER,KAAK,CAAC,EAAEG,WAAWG,GAAG,EAAE;gBACxCG,OAAOlB,aAAaY,WAAWO,QAAQ;gBACvCC,UAAU9B,cACRsB,WAAWS,WAAW,KAAKL,YACvBA,YACAhB,aAAaY,WAAWS,WAAW;gBAEzCR;eACID,WAAWU,OAAO,KAAKN,YACvB,CAAC,IACD;gBACEM,SAAS;oBACPC,MAAMX,WAAWU,OAAO,CAACC,IAAI;oBAC7BC,SAASxB,aAAaY,WAAWU,OAAO,CAACG,UAAU;gBACrD;YACF;QAER;QAEA,OAAO;YACLV,KAAK,CAAC,UAAU,EAAEN,MAAM;YACxBiB,QAAQ;gBACN;oBACEX,KAAK,CAAC,UAAU,EAAEN,MAAM;oBACxBS,OAAOnB,EAAE;oBACTW,SAASA,QAAQiB,MAAM,CAACC,CAAAA,SAAUvC,eAAeS,MAAM8B;oBACvDvB;gBACF;aACD;QACH;IACF,GAAG;QAACR;QAAQU;QAAaF;QAAWP;QAAMC;QAAGC;KAAa;AAC5D;AAEA;;;;;;;;;CASC,GACD,OAAO,SAAS6B,kBACdC,QAAyC,EACzChC,IAAY;IAEZ,MAAMiC,UAA2B,EAAE;IACnC,KAAK,MAAMlC,UAAUiC,SAAU;QAC7B,0HAA0H;QAC1HC,QAAQC,IAAI,CAACpC,kBAAkBC,QAAQC;IACzC;IACA,OAAOiC;AACT"}

package/dist/lib/config/config-route.d.ts

@@ -1,3 +1,4 @@
+import type { ConfigurationSource } from './configuration-source.js';
 /** A group of parameters as `ConfigurationPlain` carries them. */
 type PlainConfiguration = Record<string, Array<{
     key: string;
@@ -21,31 +22,17 @@ type PlainConfiguration = Record<string, Array<{
  * domains it actually proxies.
  */
 export declare const rewriteServiceDomains: (plain: PlainConfiguration, map: Readonly<Record<string, string>>) => PlainConfiguration;
-/**
- * Where config-service answers, for the callers that reach it directly.
- *
- * One declaration rather than two: this route is no longer the only server-side
- * caller — the storefront's server components read their own configuration from
- * config-service without a route in between, because a Next app cannot fetch
- * its own `/api/config` while prerendering itself.
- */
-export declare const configApiUrl: () => string;
 export interface ConfigRouteOptions {
-    /** This app's key in the `configuration` table, e.g. `back-office-app`. */
-    readonly service: string;
+    /** Where this app's configuration is fetched from, and with what headers. */
+    readonly source: ConfigurationSource;
     /** Service domains to rewrite to same-origin proxy paths. */
     readonly proxies?: Readonly<Record<string, string>>;
-    /** Overrides `CONFIG_API_URL`; mainly for tests. */
-    readonly configApiUrl?: string;
 }
 /**
  * Builds the `GET /api/config` route handler every Next app exposes: fetch this
- * app's configuration from config-service, rewrite the proxied domains, and hand
- * the result to the browser.
- *
- * Shared because all three apps did the same thing, and because the shared-token
- * header is the kind of detail that goes stale in one copy out of three.
+ * app's configuration from its source, rewrite the proxied domains, and hand the
+ * result to the browser.
  */
-export declare const createConfigRoute: ({ service, proxies, configApiUrl: configApiUrlOverride, }: ConfigRouteOptions) => () => Promise<Response>;
+export declare const createConfigRoute: ({ source, proxies, }: ConfigRouteOptions) => () => Promise<Response>;
 export {};
 //# sourceMappingURL=config-route.d.ts.map

package/dist/lib/config/config-route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config-route.d.ts","sourceRoot":"","sources":["../../../src/lib/config/config-route.ts"],"names":[],"mappings":"AAIA,kEAAkE;AAClE,KAAK,kBAAkB,GAAG,MAAM,CAC9B,MAAM,EACN,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC,CACvC,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,qBAAqB,GAChC,OAAO,kBAAkB,EACzB,KAAK,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,KACpC,kBAOD,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,QAAO,MAC0B,CAAC;AAE3D,MAAM,WAAW,kBAAkB;IACjC,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,oDAAoD;IACpD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,GAAI,2DAI/B,kBAAkB,WACG,OAAO,CAAC,QAAQ,CAkBrC,CAAC"}
+{"version":3,"file":"config-route.d.ts","sourceRoot":"","sources":["../../../src/lib/config/config-route.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAErE,kEAAkE;AAClE,KAAK,kBAAkB,GAAG,MAAM,CAC9B,MAAM,EACN,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC,CACvC,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,qBAAqB,GAChC,OAAO,kBAAkB,EACzB,KAAK,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,KACpC,kBAOD,CAAC;AAEH,MAAM,WAAW,kBAAkB;IACjC,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IACrC,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,sBAG/B,kBAAkB,WACG,OAAO,CAAC,QAAQ,CAerC,CAAC"}

package/dist/lib/config/config-route.js

@@ -1,6 +1,5 @@
 import { _ as _extends } from "@swc/helpers/_/_extends";
 import { NextResponse } from 'next/server';
-import { SERVICE_TOKEN_HEADER, serviceToken } from './service-token.js';
 /**
  * Rewrites backend addresses to the app's own same-origin proxy paths.
  *
@@ -25,31 +24,15 @@ import { SERVICE_TOKEN_HEADER, serviceToken } from './service-token.js';
             }) : parameter)
     });
 };
-/**
- * Where config-service answers, for the callers that reach it directly.
- *
- * One declaration rather than two: this route is no longer the only server-side
- * caller — the storefront's server components read their own configuration from
- * config-service without a route in between, because a Next app cannot fetch
- * its own `/api/config` while prerendering itself.
- */ export const configApiUrl = ()=>{
-    var _process_env_CONFIG_API_URL;
-    return (_process_env_CONFIG_API_URL = process.env['CONFIG_API_URL']) != null ? _process_env_CONFIG_API_URL : 'http://localhost:3190';
-};
 /**
  * Builds the `GET /api/config` route handler every Next app exposes: fetch this
- * app's configuration from config-service, rewrite the proxied domains, and hand
- * the result to the browser.
- *
- * Shared because all three apps did the same thing, and because the shared-token
- * header is the kind of detail that goes stale in one copy out of three.
- */ export const createConfigRoute = ({ service, proxies = {}, configApiUrl: configApiUrlOverride })=>async function GET() {
-        const baseUrl = configApiUrlOverride != null ? configApiUrlOverride : configApiUrl();
-        const response = await fetch(`${baseUrl}/api/config/${service}`, {
+ * app's configuration from its source, rewrite the proxied domains, and hand the
+ * result to the browser.
+ */ export const createConfigRoute = ({ source, proxies = {} })=>async function GET() {
+        const { url, headers } = source();
+        const response = await fetch(url, {
             cache: 'no-store',
-            headers: {
-                [SERVICE_TOKEN_HEADER]: serviceToken()
-            }
+            headers
         });
         if (!response.ok) {
             return NextResponse.json({

package/dist/lib/config/config-route.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/lib/config/config-route.ts"],"sourcesContent":["import { NextResponse } from 'next/server';\n\nimport { SERVICE_TOKEN_HEADER, serviceToken } from './service-token.js';\n\n/** A group of parameters as `ConfigurationPlain` carries them. */\ntype PlainConfiguration = Record<\n  string,\n  Array<{ key: string; value: unknown }>\n>;\n\n/**\n * Rewrites backend addresses to the app's own same-origin proxy paths.\n *\n * config-service holds the real address, which is what the *server* needs. A\n * browser pointed at it would be making a cross-origin request that carries no\n * session cookie and gets a `401` — `entifix_at` is httpOnly and same-origin, and\n * host-scoping it does not help, since that governs which host stores the cookie\n * rather than which cross-origin requests send it.\n *\n * So each service domain is swapped for a path on this app's own origin before\n * the browser ever sees it, which leaves the entity adapters unaware that a proxy\n * exists at all. `map` is keyed by the configuration key, e.g.\n * `{ 'config-service-domain': '/api/system' }`.\n *\n * Keys absent from `map` are passed through untouched, so an app only names the\n * domains it actually proxies.\n */\nexport const rewriteServiceDomains = (\n  plain: PlainConfiguration,\n  map: Readonly<Record<string, string>>,\n): PlainConfiguration => ({\n  ...plain,\n  uri: (plain['uri'] ?? []).map(parameter =>\n    parameter.key in map\n      ? { ...parameter, value: map[parameter.key] }\n      : parameter,\n  ),\n});\n\n/**\n * Where config-service answers, for the callers that reach it directly.\n *\n * One declaration rather than two: this route is no longer the only server-side\n * caller — the storefront's server components read their own configuration from\n * config-service without a route in between, because a Next app cannot fetch\n * its own `/api/config` while prerendering itself.\n */\nexport const configApiUrl = (): string =>\n  process.env['CONFIG_API_URL'] ?? 'http://localhost:3190';\n\nexport interface ConfigRouteOptions {\n  /** This app's key in the `configuration` table, e.g. `back-office-app`. */\n  readonly service: string;\n  /** Service domains to rewrite to same-origin proxy paths. */\n  readonly proxies?: Readonly<Record<string, string>>;\n  /** Overrides `CONFIG_API_URL`; mainly for tests. */\n  readonly configApiUrl?: string;\n}\n\n/**\n * Builds the `GET /api/config` route handler every Next app exposes: fetch this\n * app's configuration from config-service, rewrite the proxied domains, and hand\n * the result to the browser.\n *\n * Shared because all three apps did the same thing, and because the shared-token\n * header is the kind of detail that goes stale in one copy out of three.\n */\nexport const createConfigRoute = ({\n  service,\n  proxies = {},\n  configApiUrl: configApiUrlOverride,\n}: ConfigRouteOptions) =>\n  async function GET(): Promise<Response> {\n    const baseUrl = configApiUrlOverride ?? configApiUrl();\n\n    const response = await fetch(`${baseUrl}/api/config/${service}`, {\n      cache: 'no-store',\n      headers: { [SERVICE_TOKEN_HEADER]: serviceToken() },\n    });\n\n    if (!response.ok) {\n      return NextResponse.json(\n        { error: 'Failed to load configuration' },\n        { status: 502 },\n      );\n    }\n\n    const plain = (await response.json()) as PlainConfiguration;\n\n    return NextResponse.json(rewriteServiceDomains(plain, proxies));\n  };\n"],"names":["NextResponse","SERVICE_TOKEN_HEADER","serviceToken","rewriteServiceDomains","plain","map","uri","parameter","key","value","configApiUrl","process","env","createConfigRoute","service","proxies","configApiUrlOverride","GET","baseUrl","response","fetch","cache","headers","ok","json","error","status"],"mappings":";AAAA,SAASA,YAAY,QAAQ,cAAc;AAE3C,SAASC,oBAAoB,EAAEC,YAAY,QAAQ,qBAAqB;AAQxE;;;;;;;;;;;;;;;;CAgBC,GACD,OAAO,MAAMC,wBAAwB,CACnCC,OACAC;QAGMD;WAFkB,aACrBA;QACHE,KAAK,EAACF,aAAAA,KAAK,CAAC,MAAM,YAAZA,aAAgB,EAAE,EAAEC,GAAG,CAACE,CAAAA,YAC5BA,UAAUC,GAAG,IAAIH,MACb,aAAKE;gBAAWE,OAAOJ,GAAG,CAACE,UAAUC,GAAG,CAAC;iBACzCD;;EAEL;AAEH;;;;;;;CAOC,GACD,OAAO,MAAMG,eAAe;QAC1BC;YAAAA,8BAAAA,QAAQC,GAAG,CAAC,iBAAiB,YAA7BD,8BAAiC;EAAwB;AAW3D;;;;;;;CAOC,GACD,OAAO,MAAME,oBAAoB,CAAC,EAChCC,OAAO,EACPC,UAAU,CAAC,CAAC,EACZL,cAAcM,oBAAoB,EACf,GACnB,eAAeC;QACb,MAAMC,UAAUF,+BAAAA,uBAAwBN;QAExC,MAAMS,WAAW,MAAMC,MAAM,GAAGF,QAAQ,YAAY,EAAEJ,SAAS,EAAE;YAC/DO,OAAO;YACPC,SAAS;gBAAE,CAACrB,qBAAqB,EAAEC;YAAe;QACpD;QAEA,IAAI,CAACiB,SAASI,EAAE,EAAE;YAChB,OAAOvB,aAAawB,IAAI,CACtB;gBAAEC,OAAO;YAA+B,GACxC;gBAAEC,QAAQ;YAAI;QAElB;QAEA,MAAMtB,QAAS,MAAMe,SAASK,IAAI;QAElC,OAAOxB,aAAawB,IAAI,CAACrB,sBAAsBC,OAAOW;IACxD,EAAE"}
+{"version":3,"sources":["../../../src/lib/config/config-route.ts"],"sourcesContent":["import { NextResponse } from 'next/server';\n\nimport type { ConfigurationSource } from './configuration-source.js';\n\n/** A group of parameters as `ConfigurationPlain` carries them. */\ntype PlainConfiguration = Record<\n  string,\n  Array<{ key: string; value: unknown }>\n>;\n\n/**\n * Rewrites backend addresses to the app's own same-origin proxy paths.\n *\n * config-service holds the real address, which is what the *server* needs. A\n * browser pointed at it would be making a cross-origin request that carries no\n * session cookie and gets a `401` — `entifix_at` is httpOnly and same-origin, and\n * host-scoping it does not help, since that governs which host stores the cookie\n * rather than which cross-origin requests send it.\n *\n * So each service domain is swapped for a path on this app's own origin before\n * the browser ever sees it, which leaves the entity adapters unaware that a proxy\n * exists at all. `map` is keyed by the configuration key, e.g.\n * `{ 'config-service-domain': '/api/system' }`.\n *\n * Keys absent from `map` are passed through untouched, so an app only names the\n * domains it actually proxies.\n */\nexport const rewriteServiceDomains = (\n  plain: PlainConfiguration,\n  map: Readonly<Record<string, string>>,\n): PlainConfiguration => ({\n  ...plain,\n  uri: (plain['uri'] ?? []).map(parameter =>\n    parameter.key in map\n      ? { ...parameter, value: map[parameter.key] }\n      : parameter,\n  ),\n});\n\nexport interface ConfigRouteOptions {\n  /** Where this app's configuration is fetched from, and with what headers. */\n  readonly source: ConfigurationSource;\n  /** Service domains to rewrite to same-origin proxy paths. */\n  readonly proxies?: Readonly<Record<string, string>>;\n}\n\n/**\n * Builds the `GET /api/config` route handler every Next app exposes: fetch this\n * app's configuration from its source, rewrite the proxied domains, and hand the\n * result to the browser.\n */\nexport const createConfigRoute = ({\n  source,\n  proxies = {},\n}: ConfigRouteOptions) =>\n  async function GET(): Promise<Response> {\n    const { url, headers } = source();\n\n    const response = await fetch(url, { cache: 'no-store', headers });\n\n    if (!response.ok) {\n      return NextResponse.json(\n        { error: 'Failed to load configuration' },\n        { status: 502 },\n      );\n    }\n\n    const plain = (await response.json()) as PlainConfiguration;\n\n    return NextResponse.json(rewriteServiceDomains(plain, proxies));\n  };\n"],"names":["NextResponse","rewriteServiceDomains","plain","map","uri","parameter","key","value","createConfigRoute","source","proxies","GET","url","headers","response","fetch","cache","ok","json","error","status"],"mappings":";AAAA,SAASA,YAAY,QAAQ,cAAc;AAU3C;;;;;;;;;;;;;;;;CAgBC,GACD,OAAO,MAAMC,wBAAwB,CACnCC,OACAC;QAGMD;WAFkB,aACrBA;QACHE,KAAK,EAACF,aAAAA,KAAK,CAAC,MAAM,YAAZA,aAAgB,EAAE,EAAEC,GAAG,CAACE,CAAAA,YAC5BA,UAAUC,GAAG,IAAIH,MACb,aAAKE;gBAAWE,OAAOJ,GAAG,CAACE,UAAUC,GAAG,CAAC;iBACzCD;;EAEL;AASH;;;;CAIC,GACD,OAAO,MAAMG,oBAAoB,CAAC,EAChCC,MAAM,EACNC,UAAU,CAAC,CAAC,EACO,GACnB,eAAeC;QACb,MAAM,EAAEC,GAAG,EAAEC,OAAO,EAAE,GAAGJ;QAEzB,MAAMK,WAAW,MAAMC,MAAMH,KAAK;YAAEI,OAAO;YAAYH;QAAQ;QAE/D,IAAI,CAACC,SAASG,EAAE,EAAE;YAChB,OAAOjB,aAAakB,IAAI,CACtB;gBAAEC,OAAO;YAA+B,GACxC;gBAAEC,QAAQ;YAAI;QAElB;QAEA,MAAMlB,QAAS,MAAMY,SAASI,IAAI;QAElC,OAAOlB,aAAakB,IAAI,CAACjB,sBAAsBC,OAAOQ;IACxD,EAAE"}

package/dist/lib/config/configuration-source.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Where an app's configuration is fetched from on the server, and what the
+ * request carries.
+ *
+ * Both halves are the host's: the URL a configuration service answers on and
+ * the credential it asks for are that deployment's protocol, so the routes here
+ * take them as a value rather than composing either. A function rather than an
+ * object so a rotated secret — or a test that sets one — is read on each
+ * request.
+ *
+ * Server-only: the headers usually carry a secret, and nothing here is
+ * exported from the client entry.
+ */
+export type ConfigurationSource = () => {
+    readonly url: string;
+    readonly headers?: Readonly<Record<string, string>>;
+};
+//# sourceMappingURL=configuration-source.d.ts.map

package/dist/lib/config/configuration-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"configuration-source.d.ts","sourceRoot":"","sources":["../../../src/lib/config/configuration-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM;IACtC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD,CAAC"}

package/dist/lib/config/configuration-source.js

@@ -0,0 +1,15 @@
+/**
+ * Where an app's configuration is fetched from on the server, and what the
+ * request carries.
+ *
+ * Both halves are the host's: the URL a configuration service answers on and
+ * the credential it asks for are that deployment's protocol, so the routes here
+ * take them as a value rather than composing either. A function rather than an
+ * object so a rotated secret — or a test that sets one — is read on each
+ * request.
+ *
+ * Server-only: the headers usually carry a secret, and nothing here is
+ * exported from the client entry.
+ */ export { };
+
+//# sourceMappingURL=configuration-source.js.map

package/dist/lib/config/configuration-source.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/lib/config/configuration-source.ts"],"sourcesContent":["/**\n * Where an app's configuration is fetched from on the server, and what the\n * request carries.\n *\n * Both halves are the host's: the URL a configuration service answers on and\n * the credential it asks for are that deployment's protocol, so the routes here\n * take them as a value rather than composing either. A function rather than an\n * object so a rotated secret — or a test that sets one — is read on each\n * request.\n *\n * Server-only: the headers usually carry a secret, and nothing here is\n * exported from the client entry.\n */\nexport type ConfigurationSource = () => {\n  readonly url: string;\n  readonly headers?: Readonly<Record<string, string>>;\n};\n"],"names":[],"mappings":"AAAA;;;;;;;;;;;;CAYC,GACD,WAGE"}

package/dist/lib/config/service-proxy-route.d.ts

@@ -18,11 +18,20 @@ export interface ServiceProxyRouteOptions {
      *
      * Caught on the live lab rather than by any check, and the symptom is exactly
      * the one this proxy exists to prevent — the SSE stream 404s, a pending write
-     * never settles, and every probe stays green
-     * ([ADR 0036](../../../../../../docs/adr/0036-the-reactive-stream-is-server-sent-and-same-origin.md)).
+     * never settles, and every probe stays green.
      */
     readonly pathPrefix?: string;
 }
+/**
+ * The code a proxy answers when the service behind it could not be reached.
+ *
+ * `502`, never the `500` an unhandled rejection becomes: the host did nothing
+ * wrong, and a `500` sends whoever reads it looking for a bug in the app rather
+ * than for a process that is not running. A **code, not a sentence**, so the
+ * browser can render it through the host's own `errors` catalog like every
+ * other refusal in the framework.
+ */
+export declare const UPSTREAM_UNAVAILABLE = "upstreamUnavailable";
 export declare const createServiceProxyRoute: ({ baseUrl, pathPrefix, }: ServiceProxyRouteOptions) => (request: Request, { params }: Params) => Promise<Response>;
 export {};
 //# sourceMappingURL=service-proxy-route.d.ts.map

package/dist/lib/config/service-proxy-route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service-proxy-route.d.ts","sourceRoot":"","sources":["../../../src/lib/config/service-proxy-route.ts"],"names":[],"mappings":"AAIA,KAAK,MAAM,GAAG;IAAE,MAAM,EAAE,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC;AAEtD,MAAM,WAAW,wBAAwB;IACvC,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAgED,eAAO,MAAM,uBAAuB,GAAI,0BAGrC,wBAAwB,eAEd,OAAO,cACJ,MAAM,KACjB,OAAO,CAAC,QAAQ,CA6DpB,CAAC"}
+{"version":3,"file":"service-proxy-route.d.ts","sourceRoot":"","sources":["../../../src/lib/config/service-proxy-route.ts"],"names":[],"mappings":"AAIA,KAAK,MAAM,GAAG;IAAE,MAAM,EAAE,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC;AAEtD,MAAM,WAAW,wBAAwB;IACvC,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAuDD;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,wBAAwB,CAAC;AAW1D,eAAO,MAAM,uBAAuB,GAAI,0BAGrC,wBAAwB,eAEd,OAAO,cACJ,MAAM,KACjB,OAAO,CAAC,QAAQ,CAqEpB,CAAC"}

package/dist/lib/config/service-proxy-route.js

@@ -29,7 +29,7 @@ import { bearerHeader, sessionToken } from '../session/bearer.js';
  * A factory, because a host mounts one of these per backend it talks to, and
  * back-office-app now talks to two: marketplace-admin-service for the catalog a
  * vendor authors, marketplace-service for the platform vocabulary it is
- * classified in (ADR 0022).
+ * classified in.
  */ /**
  * Response headers that must survive the rebuild.
  *
@@ -49,11 +49,20 @@ import { bearerHeader, sessionToken } from '../session/bearer.js';
  * forever and delivers nothing — no error, no timeout, and the browser's
  * `EventSource` sits in `CONNECTING` while the service is happily emitting.
  * It is the most likely way to build the reactive stream, see silence, and go
- * looking in the wrong service (ADR 0036).
+ * looking in the wrong service.
  */ const isStreamed = (upstream)=>{
     var _upstream_headers_get;
     return ((_upstream_headers_get = upstream.headers.get('content-type')) == null ? void 0 : _upstream_headers_get.startsWith('text/event-stream')) === true;
 };
+/**
+ * The code a proxy answers when the service behind it could not be reached.
+ *
+ * `502`, never the `500` an unhandled rejection becomes: the host did nothing
+ * wrong, and a `500` sends whoever reads it looking for a bug in the app rather
+ * than for a process that is not running. A **code, not a sentence**, so the
+ * browser can render it through the host's own `errors` catalog like every
+ * other refusal in the framework.
+ */ export const UPSTREAM_UNAVAILABLE = 'upstreamUnavailable';
 const passThrough = (upstream)=>{
     const headers = {};
     for (const name of CACHE_HEADERS){
@@ -76,15 +85,29 @@ export const createServiceProxyRoute = ({ baseUrl, pathPrefix })=>{
             headers['if-none-match'] = ifNoneMatch;
         }
         const hasBody = request.method !== 'GET' && request.method !== 'DELETE';
+        const body = hasBody ? await request.text() : undefined;
+        // Only the connection is caught. A service that answers — with anything,
+        // a `500` included — is passed through below exactly as it answered.
         const upstream = await fetch(`${baseUrl}/api/${[
             pathPrefix,
             ...path
         ].filter(Boolean).join('/')}${search}`, {
             method: request.method,
             headers,
-            body: hasBody ? await request.text() : undefined,
+            body,
             cache: 'no-store'
-        });
+        }).catch(()=>undefined);
+        if (upstream === undefined) {
+            return NextResponse.json({
+                error: 'the service behind this route could not be reached',
+                code: UPSTREAM_UNAVAILABLE
+            }, {
+                status: 502,
+                headers: {
+                    'cache-control': 'no-store'
+                }
+            });
+        }
         const passed = passThrough(upstream);
         // A `304` carries no body by definition, and neither does a `204`. Running
         // either through a body read is not merely wasteful — a `304` reconstructed

package/dist/lib/config/service-proxy-route.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/lib/config/service-proxy-route.ts"],"sourcesContent":["import { NextResponse } from 'next/server';\n\nimport { bearerHeader, sessionToken } from '../session/bearer.js';\n\ntype Params = { params: Promise<{ path: string[] }> };\n\nexport interface ServiceProxyRouteOptions {\n  /** Where the service listens, without the `/api` suffix. */\n  readonly baseUrl: string;\n  /**\n   * A segment to put back in front of the forwarded path.\n   *\n   * ⚠️ **Needed when the proxy's namespace *is* the upstream's route name.**\n   * `/api/stock/stock-item` forwards to `/api/stock-item` because `stock` names\n   * the service and `stock-item` names the entity — two different words. But\n   * `/api/transaction/events` forwards to `/api/events`, which exists nowhere:\n   * there the namespace and the route are the same word, and stripping it\n   * strips half the address.\n   *\n   * Caught on the live lab rather than by any check, and the symptom is exactly\n   * the one this proxy exists to prevent — the SSE stream 404s, a pending write\n   * never settles, and every probe stays green\n   * ([ADR 0036](../../../../../../docs/adr/0036-the-reactive-stream-is-server-sent-and-same-origin.md)).\n   */\n  readonly pathPrefix?: string;\n}\n\n/**\n * Builds a same-origin proxy for one backend service, mounted as a catch-all\n * route handler — e.g. `app/api/admin/[...path]/route.ts`.\n *\n * The browser can never call `:310N` directly: `entifix_at` is httpOnly and\n * same-origin, so a cross-origin request carries no cookie and a guarded route\n * answers `401`. Host-scoping the cookie does not help — that governs which host\n * *stores* it, not which cross-origin requests send it. Routing through the app's\n * own origin makes the cookie automatic and needs no CORS, which is the same\n * reason the credential routes are shaped this way.\n *\n * The cookie is forwarded upstream as a bearer token. **This proxy grants\n * nothing** — the service still verifies the token and applies its own\n * `requirePermission`. It only carries.\n *\n * It also carries the **caching contract** in both directions, which it did not\n * always: rebuilding every response as a fresh body dropped `ETag`,\n * `Cache-Control` and `Vary`, and forwarded no `If-None-Match`. The effect was\n * invisible and entirely wasteful — `GET /api/<entity>/$metadata` computes and\n * hashes a permission-filtered document per request, and a validator that never\n * reaches the service means it can never answer `304`. Worse, `Vary` is a\n * *correctness* header here: the document differs per caller, and one stripped\n * of `Vary: Cookie, Authorization` may be cached and served to a different\n * principal.\n *\n * A factory, because a host mounts one of these per backend it talks to, and\n * back-office-app now talks to two: marketplace-admin-service for the catalog a\n * vendor authors, marketplace-service for the platform vocabulary it is\n * classified in (ADR 0022).\n */\n/**\n * Response headers that must survive the rebuild.\n *\n * Deliberately a short allow-list rather than copying every header: the\n * upstream's `content-length` and `content-encoding` describe *its* body, and\n * carrying them onto a response this function reconstructs is how a proxy\n * serves a truncated payload.\n */\nconst CACHE_HEADERS = ['etag', 'cache-control', 'vary'] as const;\n\n/**\n * Whether the upstream answer must be piped rather than rebuilt.\n *\n * Reading a `text/event-stream` body to completion holds the request open\n * forever and delivers nothing — no error, no timeout, and the browser's\n * `EventSource` sits in `CONNECTING` while the service is happily emitting.\n * It is the most likely way to build the reactive stream, see silence, and go\n * looking in the wrong service (ADR 0036).\n */\nconst isStreamed = (upstream: Response): boolean =>\n  upstream.headers.get('content-type')?.startsWith('text/event-stream') ===\n  true;\n\nconst passThrough = (upstream: Response): Record<string, string> => {\n  const headers: Record<string, string> = {};\n  for (const name of CACHE_HEADERS) {\n    const value = upstream.headers.get(name);\n    if (value !== null) headers[name] = value;\n  }\n  return headers;\n};\n\nexport const createServiceProxyRoute = ({\n  baseUrl,\n  pathPrefix,\n}: ServiceProxyRouteOptions) => {\n  const forward = async (\n    request: Request,\n    { params }: Params,\n  ): Promise<Response> => {\n    const { path } = await params;\n    const search = new URL(request.url).search;\n\n    const headers: Record<string, string> = {\n      'content-type': 'application/json',\n      ...bearerHeader(await sessionToken()),\n    };\n\n    // Forwarded, or the validator never reaches the service and every\n    // `$metadata` read is a full document — see {@link CACHE_HEADERS}.\n    const ifNoneMatch = request.headers.get('if-none-match');\n    if (ifNoneMatch !== null) {\n      headers['if-none-match'] = ifNoneMatch;\n    }\n\n    const hasBody = request.method !== 'GET' && request.method !== 'DELETE';\n    const upstream = await fetch(\n      `${baseUrl}/api/${[pathPrefix, ...path].filter(Boolean).join('/')}${search}`,\n      {\n        method: request.method,\n        headers,\n        body: hasBody ? await request.text() : undefined,\n        cache: 'no-store',\n      },\n    );\n\n    const passed = passThrough(upstream);\n\n    // A `304` carries no body by definition, and neither does a `204`. Running\n    // either through a body read is not merely wasteful — a `304` reconstructed\n    // with a body is no longer a `304`.\n    if (upstream.status === 304) {\n      return new NextResponse(null, { status: 304, headers: passed });\n    }\n\n    // Piped, never buffered, and never re-typed as JSON: the body is an open\n    // stream of frames, and `no-store` is correctness rather than politeness —\n    // this response is scoped to one principal.\n    if (isStreamed(upstream)) {\n      return new NextResponse(upstream.body, {\n        status: upstream.status,\n        headers: {\n          ...passed,\n          'content-type': 'text/event-stream',\n          'cache-control': 'no-store',\n        },\n      });\n    }\n\n    // 204s and empty bodies must not be run through `json()`.\n    const text = await upstream.text();\n    return text === ''\n      ? new NextResponse(null, { status: upstream.status, headers: passed })\n      : new NextResponse(text, {\n          status: upstream.status,\n          headers: { ...passed, 'content-type': 'application/json' },\n        });\n  };\n\n  return forward;\n};\n"],"names":["NextResponse","bearerHeader","sessionToken","CACHE_HEADERS","isStreamed","upstream","headers","get","startsWith","passThrough","name","value","createServiceProxyRoute","baseUrl","pathPrefix","forward","request","params","path","search","URL","url","ifNoneMatch","hasBody","method","fetch","filter","Boolean","join","body","text","undefined","cache","passed","status"],"mappings":";AAAA,SAASA,YAAY,QAAQ,cAAc;AAE3C,SAASC,YAAY,EAAEC,YAAY,QAAQ,uBAAuB;AAyBlE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BC,GACD;;;;;;;CAOC,GACD,MAAMC,gBAAgB;IAAC;IAAQ;IAAiB;CAAO;AAEvD;;;;;;;;CAQC,GACD,MAAMC,aAAa,CAACC;QAClBA;WAAAA,EAAAA,wBAAAA,SAASC,OAAO,CAACC,GAAG,CAAC,oCAArBF,sBAAsCG,UAAU,CAAC,0BACjD;;AAEF,MAAMC,cAAc,CAACJ;IACnB,MAAMC,UAAkC,CAAC;IACzC,KAAK,MAAMI,QAAQP,cAAe;QAChC,MAAMQ,QAAQN,SAASC,OAAO,CAACC,GAAG,CAACG;QACnC,IAAIC,UAAU,MAAML,OAAO,CAACI,KAAK,GAAGC;IACtC;IACA,OAAOL;AACT;AAEA,OAAO,MAAMM,0BAA0B,CAAC,EACtCC,OAAO,EACPC,UAAU,EACe;IACzB,MAAMC,UAAU,OACdC,SACA,EAAEC,MAAM,EAAU;QAElB,MAAM,EAAEC,IAAI,EAAE,GAAG,MAAMD;QACvB,MAAME,SAAS,IAAIC,IAAIJ,QAAQK,GAAG,EAAEF,MAAM;QAE1C,MAAMb,UAAkC;YACtC,gBAAgB;WACbL,aAAa,MAAMC;QAGxB,kEAAkE;QAClE,mEAAmE;QACnE,MAAMoB,cAAcN,QAAQV,OAAO,CAACC,GAAG,CAAC;QACxC,IAAIe,gBAAgB,MAAM;YACxBhB,OAAO,CAAC,gBAAgB,GAAGgB;QAC7B;QAEA,MAAMC,UAAUP,QAAQQ,MAAM,KAAK,SAASR,QAAQQ,MAAM,KAAK;QAC/D,MAAMnB,WAAW,MAAMoB,MACrB,GAAGZ,QAAQ,KAAK,EAAE;YAACC;eAAeI;SAAK,CAACQ,MAAM,CAACC,SAASC,IAAI,CAAC,OAAOT,QAAQ,EAC5E;YACEK,QAAQR,QAAQQ,MAAM;YACtBlB;YACAuB,MAAMN,UAAU,MAAMP,QAAQc,IAAI,KAAKC;YACvCC,OAAO;QACT;QAGF,MAAMC,SAASxB,YAAYJ;QAE3B,2EAA2E;QAC3E,4EAA4E;QAC5E,oCAAoC;QACpC,IAAIA,SAAS6B,MAAM,KAAK,KAAK;YAC3B,OAAO,IAAIlC,aAAa,MAAM;gBAAEkC,QAAQ;gBAAK5B,SAAS2B;YAAO;QAC/D;QAEA,yEAAyE;QACzE,2EAA2E;QAC3E,4CAA4C;QAC5C,IAAI7B,WAAWC,WAAW;YACxB,OAAO,IAAIL,aAAaK,SAASwB,IAAI,EAAE;gBACrCK,QAAQ7B,SAAS6B,MAAM;gBACvB5B,SAAS,aACJ2B;oBACH,gBAAgB;oBAChB,iBAAiB;;YAErB;QACF;QAEA,0DAA0D;QAC1D,MAAMH,OAAO,MAAMzB,SAASyB,IAAI;QAChC,OAAOA,SAAS,KACZ,IAAI9B,aAAa,MAAM;YAAEkC,QAAQ7B,SAAS6B,MAAM;YAAE5B,SAAS2B;QAAO,KAClE,IAAIjC,aAAa8B,MAAM;YACrBI,QAAQ7B,SAAS6B,MAAM;YACvB5B,SAAS,aAAK2B;gBAAQ,gBAAgB;;QACxC;IACN;IAEA,OAAOlB;AACT,EAAE"}
+{"version":3,"sources":["../../../src/lib/config/service-proxy-route.ts"],"sourcesContent":["import { NextResponse } from 'next/server';\n\nimport { bearerHeader, sessionToken } from '../session/bearer.js';\n\ntype Params = { params: Promise<{ path: string[] }> };\n\nexport interface ServiceProxyRouteOptions {\n  /** Where the service listens, without the `/api` suffix. */\n  readonly baseUrl: string;\n  /**\n   * A segment to put back in front of the forwarded path.\n   *\n   * ⚠️ **Needed when the proxy's namespace *is* the upstream's route name.**\n   * `/api/stock/stock-item` forwards to `/api/stock-item` because `stock` names\n   * the service and `stock-item` names the entity — two different words. But\n   * `/api/transaction/events` forwards to `/api/events`, which exists nowhere:\n   * there the namespace and the route are the same word, and stripping it\n   * strips half the address.\n   *\n   * Caught on the live lab rather than by any check, and the symptom is exactly\n   * the one this proxy exists to prevent — the SSE stream 404s, a pending write\n   * never settles, and every probe stays green.\n   */\n  readonly pathPrefix?: string;\n}\n\n/**\n * Builds a same-origin proxy for one backend service, mounted as a catch-all\n * route handler — e.g. `app/api/admin/[...path]/route.ts`.\n *\n * The browser can never call `:310N` directly: `entifix_at` is httpOnly and\n * same-origin, so a cross-origin request carries no cookie and a guarded route\n * answers `401`. Host-scoping the cookie does not help — that governs which host\n * *stores* it, not which cross-origin requests send it. Routing through the app's\n * own origin makes the cookie automatic and needs no CORS, which is the same\n * reason the credential routes are shaped this way.\n *\n * The cookie is forwarded upstream as a bearer token. **This proxy grants\n * nothing** — the service still verifies the token and applies its own\n * `requirePermission`. It only carries.\n *\n * It also carries the **caching contract** in both directions, which it did not\n * always: rebuilding every response as a fresh body dropped `ETag`,\n * `Cache-Control` and `Vary`, and forwarded no `If-None-Match`. The effect was\n * invisible and entirely wasteful — `GET /api/<entity>/$metadata` computes and\n * hashes a permission-filtered document per request, and a validator that never\n * reaches the service means it can never answer `304`. Worse, `Vary` is a\n * *correctness* header here: the document differs per caller, and one stripped\n * of `Vary: Cookie, Authorization` may be cached and served to a different\n * principal.\n *\n * A factory, because a host mounts one of these per backend it talks to, and\n * back-office-app now talks to two: marketplace-admin-service for the catalog a\n * vendor authors, marketplace-service for the platform vocabulary it is\n * classified in.\n */\n/**\n * Response headers that must survive the rebuild.\n *\n * Deliberately a short allow-list rather than copying every header: the\n * upstream's `content-length` and `content-encoding` describe *its* body, and\n * carrying them onto a response this function reconstructs is how a proxy\n * serves a truncated payload.\n */\nconst CACHE_HEADERS = ['etag', 'cache-control', 'vary'] as const;\n\n/**\n * Whether the upstream answer must be piped rather than rebuilt.\n *\n * Reading a `text/event-stream` body to completion holds the request open\n * forever and delivers nothing — no error, no timeout, and the browser's\n * `EventSource` sits in `CONNECTING` while the service is happily emitting.\n * It is the most likely way to build the reactive stream, see silence, and go\n * looking in the wrong service.\n */\nconst isStreamed = (upstream: Response): boolean =>\n  upstream.headers.get('content-type')?.startsWith('text/event-stream') ===\n  true;\n\n/**\n * The code a proxy answers when the service behind it could not be reached.\n *\n * `502`, never the `500` an unhandled rejection becomes: the host did nothing\n * wrong, and a `500` sends whoever reads it looking for a bug in the app rather\n * than for a process that is not running. A **code, not a sentence**, so the\n * browser can render it through the host's own `errors` catalog like every\n * other refusal in the framework.\n */\nexport const UPSTREAM_UNAVAILABLE = 'upstreamUnavailable';\n\nconst passThrough = (upstream: Response): Record<string, string> => {\n  const headers: Record<string, string> = {};\n  for (const name of CACHE_HEADERS) {\n    const value = upstream.headers.get(name);\n    if (value !== null) headers[name] = value;\n  }\n  return headers;\n};\n\nexport const createServiceProxyRoute = ({\n  baseUrl,\n  pathPrefix,\n}: ServiceProxyRouteOptions) => {\n  const forward = async (\n    request: Request,\n    { params }: Params,\n  ): Promise<Response> => {\n    const { path } = await params;\n    const search = new URL(request.url).search;\n\n    const headers: Record<string, string> = {\n      'content-type': 'application/json',\n      ...bearerHeader(await sessionToken()),\n    };\n\n    // Forwarded, or the validator never reaches the service and every\n    // `$metadata` read is a full document — see {@link CACHE_HEADERS}.\n    const ifNoneMatch = request.headers.get('if-none-match');\n    if (ifNoneMatch !== null) {\n      headers['if-none-match'] = ifNoneMatch;\n    }\n\n    const hasBody = request.method !== 'GET' && request.method !== 'DELETE';\n    const body = hasBody ? await request.text() : undefined;\n    // Only the connection is caught. A service that answers — with anything,\n    // a `500` included — is passed through below exactly as it answered.\n    const upstream = await fetch(\n      `${baseUrl}/api/${[pathPrefix, ...path].filter(Boolean).join('/')}${search}`,\n      { method: request.method, headers, body, cache: 'no-store' },\n    ).catch(() => undefined);\n\n    if (upstream === undefined) {\n      return NextResponse.json(\n        {\n          error: 'the service behind this route could not be reached',\n          code: UPSTREAM_UNAVAILABLE,\n        },\n        { status: 502, headers: { 'cache-control': 'no-store' } },\n      );\n    }\n\n    const passed = passThrough(upstream);\n\n    // A `304` carries no body by definition, and neither does a `204`. Running\n    // either through a body read is not merely wasteful — a `304` reconstructed\n    // with a body is no longer a `304`.\n    if (upstream.status === 304) {\n      return new NextResponse(null, { status: 304, headers: passed });\n    }\n\n    // Piped, never buffered, and never re-typed as JSON: the body is an open\n    // stream of frames, and `no-store` is correctness rather than politeness —\n    // this response is scoped to one principal.\n    if (isStreamed(upstream)) {\n      return new NextResponse(upstream.body, {\n        status: upstream.status,\n        headers: {\n          ...passed,\n          'content-type': 'text/event-stream',\n          'cache-control': 'no-store',\n        },\n      });\n    }\n\n    // 204s and empty bodies must not be run through `json()`.\n    const text = await upstream.text();\n    return text === ''\n      ? new NextResponse(null, { status: upstream.status, headers: passed })\n      : new NextResponse(text, {\n          status: upstream.status,\n          headers: { ...passed, 'content-type': 'application/json' },\n        });\n  };\n\n  return forward;\n};\n"],"names":["NextResponse","bearerHeader","sessionToken","CACHE_HEADERS","isStreamed","upstream","headers","get","startsWith","UPSTREAM_UNAVAILABLE","passThrough","name","value","createServiceProxyRoute","baseUrl","pathPrefix","forward","request","params","path","search","URL","url","ifNoneMatch","hasBody","method","body","text","undefined","fetch","filter","Boolean","join","cache","catch","json","error","code","status","passed"],"mappings":";AAAA,SAASA,YAAY,QAAQ,cAAc;AAE3C,SAASC,YAAY,EAAEC,YAAY,QAAQ,uBAAuB;AAwBlE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BC,GACD;;;;;;;CAOC,GACD,MAAMC,gBAAgB;IAAC;IAAQ;IAAiB;CAAO;AAEvD;;;;;;;;CAQC,GACD,MAAMC,aAAa,CAACC;QAClBA;WAAAA,EAAAA,wBAAAA,SAASC,OAAO,CAACC,GAAG,CAAC,oCAArBF,sBAAsCG,UAAU,CAAC,0BACjD;;AAEF;;;;;;;;CAQC,GACD,OAAO,MAAMC,uBAAuB,sBAAsB;AAE1D,MAAMC,cAAc,CAACL;IACnB,MAAMC,UAAkC,CAAC;IACzC,KAAK,MAAMK,QAAQR,cAAe;QAChC,MAAMS,QAAQP,SAASC,OAAO,CAACC,GAAG,CAACI;QACnC,IAAIC,UAAU,MAAMN,OAAO,CAACK,KAAK,GAAGC;IACtC;IACA,OAAON;AACT;AAEA,OAAO,MAAMO,0BAA0B,CAAC,EACtCC,OAAO,EACPC,UAAU,EACe;IACzB,MAAMC,UAAU,OACdC,SACA,EAAEC,MAAM,EAAU;QAElB,MAAM,EAAEC,IAAI,EAAE,GAAG,MAAMD;QACvB,MAAME,SAAS,IAAIC,IAAIJ,QAAQK,GAAG,EAAEF,MAAM;QAE1C,MAAMd,UAAkC;YACtC,gBAAgB;WACbL,aAAa,MAAMC;QAGxB,kEAAkE;QAClE,mEAAmE;QACnE,MAAMqB,cAAcN,QAAQX,OAAO,CAACC,GAAG,CAAC;QACxC,IAAIgB,gBAAgB,MAAM;YACxBjB,OAAO,CAAC,gBAAgB,GAAGiB;QAC7B;QAEA,MAAMC,UAAUP,QAAQQ,MAAM,KAAK,SAASR,QAAQQ,MAAM,KAAK;QAC/D,MAAMC,OAAOF,UAAU,MAAMP,QAAQU,IAAI,KAAKC;QAC9C,yEAAyE;QACzE,qEAAqE;QACrE,MAAMvB,WAAW,MAAMwB,MACrB,GAAGf,QAAQ,KAAK,EAAE;YAACC;eAAeI;SAAK,CAACW,MAAM,CAACC,SAASC,IAAI,CAAC,OAAOZ,QAAQ,EAC5E;YAAEK,QAAQR,QAAQQ,MAAM;YAAEnB;YAASoB;YAAMO,OAAO;QAAW,GAC3DC,KAAK,CAAC,IAAMN;QAEd,IAAIvB,aAAauB,WAAW;YAC1B,OAAO5B,aAAamC,IAAI,CACtB;gBACEC,OAAO;gBACPC,MAAM5B;YACR,GACA;gBAAE6B,QAAQ;gBAAKhC,SAAS;oBAAE,iBAAiB;gBAAW;YAAE;QAE5D;QAEA,MAAMiC,SAAS7B,YAAYL;QAE3B,2EAA2E;QAC3E,4EAA4E;QAC5E,oCAAoC;QACpC,IAAIA,SAASiC,MAAM,KAAK,KAAK;YAC3B,OAAO,IAAItC,aAAa,MAAM;gBAAEsC,QAAQ;gBAAKhC,SAASiC;YAAO;QAC/D;QAEA,yEAAyE;QACzE,2EAA2E;QAC3E,4CAA4C;QAC5C,IAAInC,WAAWC,WAAW;YACxB,OAAO,IAAIL,aAAaK,SAASqB,IAAI,EAAE;gBACrCY,QAAQjC,SAASiC,MAAM;gBACvBhC,SAAS,aACJiC;oBACH,gBAAgB;oBAChB,iBAAiB;;YAErB;QACF;QAEA,0DAA0D;QAC1D,MAAMZ,OAAO,MAAMtB,SAASsB,IAAI;QAChC,OAAOA,SAAS,KACZ,IAAI3B,aAAa,MAAM;YAAEsC,QAAQjC,SAASiC,MAAM;YAAEhC,SAASiC;QAAO,KAClE,IAAIvC,aAAa2B,MAAM;YACrBW,QAAQjC,SAASiC,MAAM;YACvBhC,SAAS,aAAKiC;gBAAQ,gBAAgB;;QACxC;IACN;IAEA,OAAOvB;AACT,EAAE"}

package/dist/lib/crud/entity-crud-form.js

@@ -84,8 +84,8 @@ import { validationMessagesFor } from './validation-messages.js';
    * the stock surface: `stock-item` answers `["read"]` — no role holds
    * `stock-item:write` and there is no save route — so Save was correctly
    * absent while `onHand` and `reserved` still rendered as **enabled number
-   * inputs**. A vendor could type a new quantity into the very field ADR 0010
-   * forbids writing, and nothing would happen and nothing would say why.
+   * inputs**. A vendor could type a new quantity into a field that is only ever
+   * moved by a ledger, and nothing would happen and nothing would say why.
    *
    * A create is exempt: there is no record yet, so there is nothing to read and
    * a `read` mode would render an empty form with no way to fill it.
@@ -115,7 +115,7 @@ import { validationMessagesFor } from './validation-messages.js';
         backHref: backHref,
         renderLink: renderLink,
         // `entity` is undefined until the record lands, so testing it alone
-        // titled a loading edit form "New" and then relabelled it (#139).
+        // titled a loading edit form "New" and then relabelled it.
         title: et(entity || isLoading ? `${catalogKey}.form.editTitle` : `${catalogKey}.form.newTitle`),
         children: hiddenFields.map((field)=>/*#__PURE__*/ _jsx(EntityField, {
                 field: field,

package/dist/lib/crud/entity-crud-form.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/lib/crud/entity-crud-form.tsx"],"sourcesContent":["'use client';\n\nimport {\n  type EntifixError,\n  type Entity,\n  type EntityConstructor,\n  type EntityMetadataSource,\n  reconstructEntity,\n} from '@entifix/core';\nimport {\n  EntityField,\n  EntityForm,\n  type RenderLink,\n  useT,\n  useTranslateKey,\n} from '@entifix/react-controls';\nimport {\n  type EntityDraftStore,\n  useEntityForm,\n} from '@entifix/react-integration';\nimport { useEffect, useMemo } from 'react';\n\nimport type {\n  EntityCatalogKey,\n  EntityCrudLinkSource,\n} from './make-entity-crud.types.js';\nimport { useEntityAffordances } from './use-entity-affordances.js';\nimport { useEntityLinkSources } from './use-entity-link-sources.js';\nimport { validationMessagesFor } from './validation-messages.js';\n\nexport interface EntityCrudFormProps<TEntity extends Entity> {\n  readonly entityConstructor: EntityConstructor<TEntity>;\n  readonly catalogKey: EntityCatalogKey;\n  readonly hiddenFields: readonly string[];\n  readonly links: readonly EntityCrudLinkSource[];\n  /** The record being edited; `undefined` means this is a create. */\n  readonly entity?: TEntity;\n  readonly isLoading?: boolean;\n  readonly isSaving?: boolean;\n  readonly isDeleting?: boolean;\n  readonly error?: EntifixError;\n  readonly onSave: (entity: TEntity) => void;\n  /** Omitted for a create — there is nothing to delete yet. */\n  readonly onDelete?: () => void;\n  readonly backHref: string;\n  /** Renders the Back link; see `useCrudRenderLink`. */\n  readonly renderLink?: RenderLink;\n  /**\n   * Where to autosave this form's draft. Omitted by a route host, which is what\n   * keeps a plain route ephemeral; the workspace tab host supplies one.\n   */\n  readonly draft?: EntityDraftStore;\n  /**\n   * Where this caller's affordances come from. Absent keeps the pre-ADR-0026\n   * behaviour: Save and Delete render unconditionally and no declared verb\n   * appears — which is what every generated catalog did before it existed.\n   */\n  readonly metadataSource?: EntityMetadataSource;\n  /** Runs a declared `entity`-bound verb on this record, by its key. */\n  readonly onUseCase?: (key: string) => void;\n}\n\n/**\n * The generated create/update form. A thin wrapper over the agnostic\n * {@link EntityForm}: every field, label and validation rule comes from the\n * entity's own accessor metadata, and `reconstructEntity` derives the submit\n * rebuild from that same metadata — so nothing here is per-entity but the\n * constructor, the catalog key and the hidden-field list.\n *\n * A hidden member still round-trips. `code` is assigned by the create\n * transaction and never shown, but it is a plain writable member, so the rebuild\n * picks it out of the seeded draft; dropping it from the rendered fields is not\n * dropping it from the draft.\n *\n * `useEntityForm` owns the draft and seeds it once, so the page keys this\n * component by the record id to reseed when the record arrives.\n */\nexport function EntityCrudForm<TEntity extends Entity>({\n  entityConstructor,\n  catalogKey,\n  hiddenFields,\n  links,\n  entity,\n  isLoading = false,\n  isSaving = false,\n  isDeleting = false,\n  error,\n  onSave,\n  onDelete,\n  backHref,\n  renderLink,\n  draft,\n  metadataSource,\n  onUseCase,\n}: EntityCrudFormProps<TEntity>) {\n  const et = useT('entity');\n  const ct = useT('controls');\n\n  // `controls` copy, resolved here and handed down; see validationMessagesFor.\n  const validationMessages = useMemo(() => validationMessagesFor(ct), [ct]);\n\n  // A runtime-key translator, so a message names the field by its catalog word\n  // (`labelKey`) and a schema's keyed message resolves at all. Without it both\n  // fell back to untranslated text inside an otherwise Spanish sentence.\n  const translateKey = useTranslateKey();\n\n  const form = useEntityForm<TEntity>({\n    entityConstructor,\n    entity,\n    validationMessages,\n    translateKey,\n    draft,\n    onSubmit: values =>\n      onSave(\n        reconstructEntity(entityConstructor, values, { existing: entity }),\n      ),\n  });\n\n  const linkSources = useEntityLinkSources(links, {\n    values: form.values,\n    selection: form.links,\n  });\n\n  // Refill the relation sidecar from the ids the draft did keep.\n  //\n  // A draft is JSON, so it holds ids and nothing else; the instances behind them\n  // die with the page. Each picker already resolves its id — that is how a\n  // restored draft shows a brand's name instead of its key — so the instance is\n  // in hand and only has to be handed back. Without this, a member declared\n  // `linkSerialization: 'embedded'` reaches `applyEntityLinks` with an id and no\n  // target, which it refuses rather than writing the wrong wire shape.\n  //\n  // `hydrateLink`, not `setLink`: this is a lookup landing, not a pick, so it\n  // must leave the draft — and the form's dirty flag — alone.\n  const { links: selection, hydrateLink } = form;\n  useEffect(() => {\n    for (const [field, source] of Object.entries(linkSources)) {\n      const resolved = source.selected.entity;\n      if (resolved !== undefined && selection[field] === undefined) {\n        hydrateLink(field, resolved);\n      }\n    }\n  }, [linkSources, selection, hydrateLink]);\n\n  const affordances = useEntityAffordances(entityConstructor, metadataSource);\n\n  /**\n   * May this caller write the record in front of them?\n   *\n   * The **same authority that withholds Save**, applied one step earlier.\n   * Absent metadata keeps the pre-ADR-0026 behaviour, so an un-migrated call\n   * site is untouched; present metadata is authoritative, because it is what\n   * the service already decided.\n   *\n   * ⚠️ Without this the form rendered inputs nobody could submit. Measured on\n   * the stock surface: `stock-item` answers `[\"read\"]` — no role holds\n   * `stock-item:write` and there is no save route — so Save was correctly\n   * absent while `onHand` and `reserved` still rendered as **enabled number\n   * inputs**. A vendor could type a new quantity into the very field ADR 0010\n   * forbids writing, and nothing would happen and nothing would say why.\n   *\n   * A create is exempt: there is no record yet, so there is nothing to read and\n   * a `read` mode would render an empty form with no way to fill it.\n   */\n  const mayWrite =\n    entity === undefined ||\n    affordances.metadata === undefined ||\n    affordances.metadata.actions.includes('write');\n\n  return (\n    <EntityForm<TEntity>\n      entityConstructor={entityConstructor}\n      entity={entity}\n      // Driven by the served descriptor rather than fixed: `edit` for a caller\n      // who may write, `read` for one who may not. Passing it at all is what\n      // suppresses the built-in Ver/Editar toggle, which would otherwise offer\n      // a way back into inputs the service will refuse.\n      mode={mayWrite ? 'edit' : 'read'}\n      values={form.values}\n      onFieldChange={form.setField}\n      linkSources={linkSources}\n      onLinkChange={form.setLink}\n      errors={form.errors}\n      formError={form.formError}\n      onSubmit={form.submit}\n      onDelete={onDelete}\n      {...affordances}\n      onUseCase={onUseCase}\n      isLoading={isLoading}\n      isSaving={isSaving}\n      isDeleting={isDeleting}\n      error={error}\n      backHref={backHref}\n      renderLink={renderLink}\n      // `entity` is undefined until the record lands, so testing it alone\n      // titled a loading edit form \"New\" and then relabelled it (#139).\n      title={et(\n        entity || isLoading\n          ? `${catalogKey}.form.editTitle`\n          : `${catalogKey}.form.newTitle`,\n      )}\n    >\n      {hiddenFields.map(field => (\n        <EntityField<TEntity> key={field} field={field} hidden />\n      ))}\n    </EntityForm>\n  );\n}\n"],"names":["reconstructEntity","EntityField","EntityForm","useT","useTranslateKey","useEntityForm","useEffect","useMemo","useEntityAffordances","useEntityLinkSources","validationMessagesFor","EntityCrudForm","entityConstructor","catalogKey","hiddenFields","links","entity","isLoading","isSaving","isDeleting","error","onSave","onDelete","backHref","renderLink","draft","metadataSource","onUseCase","et","ct","validationMessages","translateKey","form","onSubmit","values","existing","linkSources","selection","hydrateLink","field","source","Object","entries","resolved","selected","undefined","affordances","mayWrite","metadata","actions","includes","mode","onFieldChange","setField","onLinkChange","setLink","errors","formError","submit","title","map","hidden"],"mappings":"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"}
+{"version":3,"sources":["../../../src/lib/crud/entity-crud-form.tsx"],"sourcesContent":["'use client';\n\nimport {\n  type EntifixError,\n  type Entity,\n  type EntityConstructor,\n  type EntityMetadataSource,\n  reconstructEntity,\n} from '@entifix/core';\nimport {\n  EntityField,\n  EntityForm,\n  type RenderLink,\n  useT,\n  useTranslateKey,\n} from '@entifix/react-controls';\nimport {\n  type EntityDraftStore,\n  useEntityForm,\n} from '@entifix/react-integration';\nimport { useEffect, useMemo } from 'react';\n\nimport type {\n  EntityCatalogKey,\n  EntityCrudLinkSource,\n} from './make-entity-crud.types.js';\nimport { useEntityAffordances } from './use-entity-affordances.js';\nimport { useEntityLinkSources } from './use-entity-link-sources.js';\nimport { validationMessagesFor } from './validation-messages.js';\n\nexport interface EntityCrudFormProps<TEntity extends Entity> {\n  readonly entityConstructor: EntityConstructor<TEntity>;\n  readonly catalogKey: EntityCatalogKey;\n  readonly hiddenFields: readonly string[];\n  readonly links: readonly EntityCrudLinkSource[];\n  /** The record being edited; `undefined` means this is a create. */\n  readonly entity?: TEntity;\n  readonly isLoading?: boolean;\n  readonly isSaving?: boolean;\n  readonly isDeleting?: boolean;\n  readonly error?: EntifixError;\n  readonly onSave: (entity: TEntity) => void;\n  /** Omitted for a create — there is nothing to delete yet. */\n  readonly onDelete?: () => void;\n  readonly backHref: string;\n  /** Renders the Back link; see `useCrudRenderLink`. */\n  readonly renderLink?: RenderLink;\n  /**\n   * Where to autosave this form's draft. Omitted by a route host, which is what\n   * keeps a plain route ephemeral; the workspace tab host supplies one.\n   */\n  readonly draft?: EntityDraftStore;\n  /**\n   * Where this caller's affordances come from. Absent keeps the pre-ADR-0026\n   * behaviour: Save and Delete render unconditionally and no declared verb\n   * appears — which is what every generated catalog did before it existed.\n   */\n  readonly metadataSource?: EntityMetadataSource;\n  /** Runs a declared `entity`-bound verb on this record, by its key. */\n  readonly onUseCase?: (key: string) => void;\n}\n\n/**\n * The generated create/update form. A thin wrapper over the agnostic\n * {@link EntityForm}: every field, label and validation rule comes from the\n * entity's own accessor metadata, and `reconstructEntity` derives the submit\n * rebuild from that same metadata — so nothing here is per-entity but the\n * constructor, the catalog key and the hidden-field list.\n *\n * A hidden member still round-trips. `code` is assigned by the create\n * transaction and never shown, but it is a plain writable member, so the rebuild\n * picks it out of the seeded draft; dropping it from the rendered fields is not\n * dropping it from the draft.\n *\n * `useEntityForm` owns the draft and seeds it once, so the page keys this\n * component by the record id to reseed when the record arrives.\n */\nexport function EntityCrudForm<TEntity extends Entity>({\n  entityConstructor,\n  catalogKey,\n  hiddenFields,\n  links,\n  entity,\n  isLoading = false,\n  isSaving = false,\n  isDeleting = false,\n  error,\n  onSave,\n  onDelete,\n  backHref,\n  renderLink,\n  draft,\n  metadataSource,\n  onUseCase,\n}: EntityCrudFormProps<TEntity>) {\n  const et = useT('entity');\n  const ct = useT('controls');\n\n  // `controls` copy, resolved here and handed down; see validationMessagesFor.\n  const validationMessages = useMemo(() => validationMessagesFor(ct), [ct]);\n\n  // A runtime-key translator, so a message names the field by its catalog word\n  // (`labelKey`) and a schema's keyed message resolves at all. Without it both\n  // fell back to untranslated text inside an otherwise Spanish sentence.\n  const translateKey = useTranslateKey();\n\n  const form = useEntityForm<TEntity>({\n    entityConstructor,\n    entity,\n    validationMessages,\n    translateKey,\n    draft,\n    onSubmit: values =>\n      onSave(\n        reconstructEntity(entityConstructor, values, { existing: entity }),\n      ),\n  });\n\n  const linkSources = useEntityLinkSources(links, {\n    values: form.values,\n    selection: form.links,\n  });\n\n  // Refill the relation sidecar from the ids the draft did keep.\n  //\n  // A draft is JSON, so it holds ids and nothing else; the instances behind them\n  // die with the page. Each picker already resolves its id — that is how a\n  // restored draft shows a brand's name instead of its key — so the instance is\n  // in hand and only has to be handed back. Without this, a member declared\n  // `linkSerialization: 'embedded'` reaches `applyEntityLinks` with an id and no\n  // target, which it refuses rather than writing the wrong wire shape.\n  //\n  // `hydrateLink`, not `setLink`: this is a lookup landing, not a pick, so it\n  // must leave the draft — and the form's dirty flag — alone.\n  const { links: selection, hydrateLink } = form;\n  useEffect(() => {\n    for (const [field, source] of Object.entries(linkSources)) {\n      const resolved = source.selected.entity;\n      if (resolved !== undefined && selection[field] === undefined) {\n        hydrateLink(field, resolved);\n      }\n    }\n  }, [linkSources, selection, hydrateLink]);\n\n  const affordances = useEntityAffordances(entityConstructor, metadataSource);\n\n  /**\n   * May this caller write the record in front of them?\n   *\n   * The **same authority that withholds Save**, applied one step earlier.\n   * Absent metadata keeps the pre-ADR-0026 behaviour, so an un-migrated call\n   * site is untouched; present metadata is authoritative, because it is what\n   * the service already decided.\n   *\n   * ⚠️ Without this the form rendered inputs nobody could submit. Measured on\n   * the stock surface: `stock-item` answers `[\"read\"]` — no role holds\n   * `stock-item:write` and there is no save route — so Save was correctly\n   * absent while `onHand` and `reserved` still rendered as **enabled number\n   * inputs**. A vendor could type a new quantity into a field that is only ever\n   * moved by a ledger, and nothing would happen and nothing would say why.\n   *\n   * A create is exempt: there is no record yet, so there is nothing to read and\n   * a `read` mode would render an empty form with no way to fill it.\n   */\n  const mayWrite =\n    entity === undefined ||\n    affordances.metadata === undefined ||\n    affordances.metadata.actions.includes('write');\n\n  return (\n    <EntityForm<TEntity>\n      entityConstructor={entityConstructor}\n      entity={entity}\n      // Driven by the served descriptor rather than fixed: `edit` for a caller\n      // who may write, `read` for one who may not. Passing it at all is what\n      // suppresses the built-in Ver/Editar toggle, which would otherwise offer\n      // a way back into inputs the service will refuse.\n      mode={mayWrite ? 'edit' : 'read'}\n      values={form.values}\n      onFieldChange={form.setField}\n      linkSources={linkSources}\n      onLinkChange={form.setLink}\n      errors={form.errors}\n      formError={form.formError}\n      onSubmit={form.submit}\n      onDelete={onDelete}\n      {...affordances}\n      onUseCase={onUseCase}\n      isLoading={isLoading}\n      isSaving={isSaving}\n      isDeleting={isDeleting}\n      error={error}\n      backHref={backHref}\n      renderLink={renderLink}\n      // `entity` is undefined until the record lands, so testing it alone\n      // titled a loading edit form \"New\" and then relabelled it.\n      title={et(\n        entity || isLoading\n          ? `${catalogKey}.form.editTitle`\n          : `${catalogKey}.form.newTitle`,\n      )}\n    >\n      {hiddenFields.map(field => (\n        <EntityField<TEntity> key={field} field={field} hidden />\n      ))}\n    </EntityForm>\n  );\n}\n"],"names":["reconstructEntity","EntityField","EntityForm","useT","useTranslateKey","useEntityForm","useEffect","useMemo","useEntityAffordances","useEntityLinkSources","validationMessagesFor","EntityCrudForm","entityConstructor","catalogKey","hiddenFields","links","entity","isLoading","isSaving","isDeleting","error","onSave","onDelete","backHref","renderLink","draft","metadataSource","onUseCase","et","ct","validationMessages","translateKey","form","onSubmit","values","existing","linkSources","selection","hydrateLink","field","source","Object","entries","resolved","selected","undefined","affordances","mayWrite","metadata","actions","includes","mode","onFieldChange","setField","onLinkChange","setLink","errors","formError","submit","title","map","hidden"],"mappings":"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"}

package/dist/lib/crud/hand-off-write.d.ts

@@ -15,7 +15,7 @@ export interface HandOffWriteOptions {
  *
  * A transactional create resolves at the `202`, **before** the write is
  * durable, so the save adapter has already announced it and the id is in the
- * pending set ([ADR 0043](../../../../../../docs/adr/0043-the-optimistic-mutation-contract.md)).
+ * pending set.
  * Handing the record over *is* the question: the returned entity is otherwise
  * indistinguishable from a plain REST create, and asking `entries.some(...)`
  * beforehand would read a set captured before the `await` that announced it.

package/dist/lib/crud/hand-off-write.js

@@ -3,7 +3,7 @@
  *
  * A transactional create resolves at the `202`, **before** the write is
  * durable, so the save adapter has already announced it and the id is in the
- * pending set ([ADR 0043](../../../../../../docs/adr/0043-the-optimistic-mutation-contract.md)).
+ * pending set.
  * Handing the record over *is* the question: the returned entity is otherwise
  * indistinguishable from a plain REST create, and asking `entries.some(...)`
  * beforehand would read a set captured before the `await` that announced it.

package/dist/lib/crud/hand-off-write.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/lib/crud/hand-off-write.ts"],"sourcesContent":["import type { PendingTransactionStore } from '@entifix/transactions';\n\nexport interface HandOffWriteOptions {\n  /** The saved record's id — the transaction id, for a tracked create. */\n  readonly id: string;\n  /** The record as the browser built it, shown until the service confirms. */\n  readonly record: unknown;\n  readonly pending: PendingTransactionStore;\n  /** The draft the write was composed in, if it had one. */\n  readonly draft?: { clear(): void };\n}\n\n/**\n * What happens to a draft once its write has been handed over.\n *\n * A transactional create resolves at the `202`, **before** the write is\n * durable, so the save adapter has already announced it and the id is in the\n * pending set ([ADR 0043](../../../../../../docs/adr/0043-the-optimistic-mutation-contract.md)).\n * Handing the record over *is* the question: the returned entity is otherwise\n * indistinguishable from a plain REST create, and asking `entries.some(...)`\n * beforehand would read a set captured before the `await` that announced it.\n *\n * ⚠️ A **still-pending write keeps its draft**. The write has not committed, and\n * a failure minutes from now would otherwise have destroyed the operator's only\n * copy of what they typed. Only a plain, committed write spends it.\n *\n * It lives here rather than inside `makeEntityCrud` because it is not the\n * generator's rule — it is the rule for every screen that writes. A wizard's\n * Finalizar performs the same three steps, and a second copy of them is where\n * one of the two would eventually stop keeping the draft.\n *\n * @returns whether the write is still in flight.\n */\nexport function handOffWrite({\n  id,\n  record,\n  pending,\n  draft,\n}: HandOffWriteOptions): boolean {\n  if (pending.attach(id, record)) return true;\n\n  draft?.clear();\n  return false;\n}\n"],"names":["handOffWrite","id","record","pending","draft","attach","clear"],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;CAoBC,GACD,OAAO,SAASA,aAAa,EAC3BC,EAAE,EACFC,MAAM,EACNC,OAAO,EACPC,KAAK,EACe;IACpB,IAAID,QAAQE,MAAM,CAACJ,IAAIC,SAAS,OAAO;IAEvCE,yBAAAA,MAAOE,KAAK;IACZ,OAAO;AACT"}
+{"version":3,"sources":["../../../src/lib/crud/hand-off-write.ts"],"sourcesContent":["import type { PendingTransactionStore } from '@entifix/transactions';\n\nexport interface HandOffWriteOptions {\n  /** The saved record's id — the transaction id, for a tracked create. */\n  readonly id: string;\n  /** The record as the browser built it, shown until the service confirms. */\n  readonly record: unknown;\n  readonly pending: PendingTransactionStore;\n  /** The draft the write was composed in, if it had one. */\n  readonly draft?: { clear(): void };\n}\n\n/**\n * What happens to a draft once its write has been handed over.\n *\n * A transactional create resolves at the `202`, **before** the write is\n * durable, so the save adapter has already announced it and the id is in the\n * pending set.\n * Handing the record over *is* the question: the returned entity is otherwise\n * indistinguishable from a plain REST create, and asking `entries.some(...)`\n * beforehand would read a set captured before the `await` that announced it.\n *\n * ⚠️ A **still-pending write keeps its draft**. The write has not committed, and\n * a failure minutes from now would otherwise have destroyed the operator's only\n * copy of what they typed. Only a plain, committed write spends it.\n *\n * It lives here rather than inside `makeEntityCrud` because it is not the\n * generator's rule — it is the rule for every screen that writes. A wizard's\n * Finalizar performs the same three steps, and a second copy of them is where\n * one of the two would eventually stop keeping the draft.\n *\n * @returns whether the write is still in flight.\n */\nexport function handOffWrite({\n  id,\n  record,\n  pending,\n  draft,\n}: HandOffWriteOptions): boolean {\n  if (pending.attach(id, record)) return true;\n\n  draft?.clear();\n  return false;\n}\n"],"names":["handOffWrite","id","record","pending","draft","attach","clear"],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;CAoBC,GACD,OAAO,SAASA,aAAa,EAC3BC,EAAE,EACFC,MAAM,EACNC,OAAO,EACPC,KAAK,EACe;IACpB,IAAID,QAAQE,MAAM,CAACJ,IAAIC,SAAS,OAAO;IAEvCE,yBAAAA,MAAOE,KAAK;IACZ,OAAO;AACT"}

package/dist/lib/crud/make-entity-crud.d.ts

@@ -1,4 +1,4 @@
-import { type ConfigurationRepositoryTag, type EntityRepositoryTag } from '@entifix/business';
+import { type EntityRepositoryTag } from '@entifix/business';
 import { type Entity, type EntityConstructor } from '@entifix/core';
 import type { TransactionSink } from '@entifix/transactions';
 import { TransactionSinkTag } from '@entifix/transactions';
@@ -12,17 +12,15 @@ import type { EntityCrud, EntityCrudOptions } from './make-entity-crud.types.js'
  * rebuilding the union at each such call site is how one of them ends up
  * missing `TransactionSinkTag` and quietly losing its optimistic treatment.
  */
-export type CrudContext = EntityRepositoryTag | ConfigurationRepositoryTag | TransactionSinkTag;
+export type CrudContext = EntityRepositoryTag | TransactionSinkTag;
 /**
- * Merges the configuration adapter with one repository adapter into the context
- * the use-cases run against.
+ * Adds the pending-write sink to one repository adapter, giving the context the
+ * use-cases run against.
  *
- * The casts are the price of naming adapters by key: `AdapterKey` narrows which
+ * The cast is the price of naming adapters by key: `AdapterKey` narrows which
  * names may be *offered*, but TypeScript will not carry that narrowing through
- * an index access on a generic record. The alternative is every call site
- * passing two `Context` values per entity — the duplication this factory exists
- * to remove.
+ * an index access on a generic record.
  */
-export declare function mergeCrudContext<TAdapters>(adapters: TAdapters, configuration: keyof TAdapters, repository: keyof TAdapters, sink: TransactionSink): Context.Context<CrudContext>;
+export declare function mergeCrudContext<TAdapters>(adapters: TAdapters, repository: keyof TAdapters, sink: TransactionSink): Context.Context<CrudContext>;
 export declare function makeEntityCrud<TEntity extends Entity, TAdapters>(entityConstructor: EntityConstructor<TEntity>, options: EntityCrudOptions<TAdapters, TEntity>): EntityCrud<TEntity>;
 //# sourceMappingURL=make-entity-crud.d.ts.map

package/dist/lib/crud/make-entity-crud.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"make-entity-crud.d.ts","sourceRoot":"","sources":["../../../src/lib/crud/make-entity-crud.tsx"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,0BAA0B,EAE/B,KAAK,mBAAmB,EAIzB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAKL,KAAK,MAAM,EACX,KAAK,iBAAiB,EAIvB,MAAM,eAAe,CAAC;AAQvB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE3D,OAAO,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAajC,OAAO,KAAK,EACV,UAAU,EAEV,iBAAiB,EAElB,MAAM,6BAA6B,CAAC;AAUrC;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GACrB,mBAAmB,GAAG,0BAA0B,GAAG,kBAAkB,CAAC;AAExE;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EACxC,QAAQ,EAAE,SAAS,EACnB,aAAa,EAAE,MAAM,SAAS,EAC9B,UAAU,EAAE,MAAM,SAAS,EAC3B,IAAI,EAAE,eAAe,GACpB,OAAO,CAAC,OAAO,CAAC,WAAW,CAAC,CAS9B;AAwCD,wBAAgB,cAAc,CAAC,OAAO,SAAS,MAAM,EAAE,SAAS,EAC9D,iBAAiB,EAAE,iBAAiB,CAAC,OAAO,CAAC,EAC7C,OAAO,EAAE,iBAAiB,CAAC,SAAS,EAAE,OAAO,CAAC,GAC7C,UAAU,CAAC,OAAO,CAAC,CAkXrB"}
+{"version":3,"file":"make-entity-crud.d.ts","sourceRoot":"","sources":["../../../src/lib/crud/make-entity-crud.tsx"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,mBAAmB,EAIzB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAKL,KAAK,MAAM,EACX,KAAK,iBAAiB,EAIvB,MAAM,eAAe,CAAC;AAQvB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE3D,OAAO,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAajC,OAAO,KAAK,EACV,UAAU,EAEV,iBAAiB,EAElB,MAAM,6BAA6B,CAAC;AAUrC;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,mBAAmB,GAAG,kBAAkB,CAAC;AAEnE;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EACxC,QAAQ,EAAE,SAAS,EACnB,UAAU,EAAE,MAAM,SAAS,EAC3B,IAAI,EAAE,eAAe,GACpB,OAAO,CAAC,OAAO,CAAC,WAAW,CAAC,CAM9B;AAuCD,wBAAgB,cAAc,CAAC,OAAO,SAAS,MAAM,EAAE,SAAS,EAC9D,iBAAiB,EAAE,iBAAiB,CAAC,OAAO,CAAC,EAC7C,OAAO,EAAE,iBAAiB,CAAC,SAAS,EAAE,OAAO,CAAC,GAC7C,UAAU,CAAC,OAAO,CAAC,CA4WrB"}

package/dist/lib/crud/make-entity-crud.js

@@ -22,16 +22,14 @@ import { useEntityAffordances } from './use-entity-affordances.js';
 import { useEntityBulk } from './use-entity-bulk.js';
 /** What a picker defaults to reading off its target. */ const TARGET_NAME_PROPERTY = 'name';
 /**
- * Merges the configuration adapter with one repository adapter into the context
- * the use-cases run against.
+ * Adds the pending-write sink to one repository adapter, giving the context the
+ * use-cases run against.
  *
- * The casts are the price of naming adapters by key: `AdapterKey` narrows which
+ * The cast is the price of naming adapters by key: `AdapterKey` narrows which
  * names may be *offered*, but TypeScript will not carry that narrowing through
- * an index access on a generic record. The alternative is every call site
- * passing two `Context` values per entity — the duplication this factory exists
- * to remove.
- */ export function mergeCrudContext(adapters, configuration, repository, sink) {
-    return Context.add(Context.merge(adapters[configuration], adapters[repository]), TransactionSinkTag, sink);
+ * an index access on a generic record.
+ */ export function mergeCrudContext(adapters, repository, sink) {
+    return Context.add(adapters[repository], TransactionSinkTag, sink);
 }
 /**
  * Builds the list page and the single-record page for one entity.
@@ -51,8 +49,7 @@ import { useEntityBulk } from './use-entity-bulk.js';
  *
  * **Serves compile-time `@entity()` classes only.** Operator reference data ships
  * with the code, so making this spec-driven would trade type safety for nothing;
- * a vendor-authored `EntitySpecification` renders through a separate path
- * (ADR 0014).
+ * a vendor-authored `EntitySpecification` renders through a separate path.
  */ /**
  * A rejected verb, as something the form's error slot can render.
  *
@@ -64,7 +61,7 @@ import { useEntityBulk } from './use-entity-bulk.js';
     return failure instanceof EntifixLogicError || failure instanceof EntifixBuildError ? failure : new EntifixLogicError(failure instanceof Error ? failure.message : String(failure));
 }
 export function makeEntityCrud(entityConstructor, options) {
-    const { useAdapters, basePath, catalogKey, repository, configuration, hiddenFields = [], columns, toolbar, links = [], metadataSource: givenMetadataSource, metadata, runBulkUseCase, runUseCase } = options;
+    const { useAdapters, basePath, catalogKey, repository, hiddenFields = [], columns, toolbar, links = [], metadataSource: givenMetadataSource, metadata, runBulkUseCase, runUseCase } = options;
     if (givenMetadataSource !== undefined && metadata !== undefined) {
         throw new EntifixBuildError(`${entityConstructor.name} was given both metadataSource and metadata; pass one`);
     }
@@ -127,7 +124,7 @@ export function makeEntityCrud(entityConstructor, options) {
         const optimistic = pendingRecordsFor(pending, entityName);
         const pager = useDataLoading({
             uc: loadUCFactory(),
-            ctx: mergeCrudContext(adapters, configuration, repository, pending),
+            ctx: mergeCrudContext(adapters, repository, pending),
             // Scoped rather than left to the per-instance fallback, which is correct
             // but unshared: with the entity's own scope one invalidation refreshes
             // every page and filter of it, which is what a bulk run needs — and it is
@@ -146,13 +143,13 @@ export function makeEntityCrud(entityConstructor, options) {
         // Decided from the served document rather than from the runner, because
         // the runner is a property of the *shell* (it knows the route) and the
         // grant is a property of the *caller*. The column therefore appears when
-        // the document lands, which is the asynchrony ADR 0026 already accepts for
-        // every action surface.
+        // the document lands, which is the asynchrony serving affordances accepts
+        // for every action surface.
         const canRunBulk = useCasesForSurface('bulk-bar', (_affordances_metadata = affordances.metadata) == null ? void 0 : _affordances_metadata.useCases).length > 0;
         const bulk = useEntityBulk({
             run: canRunBulk ? runBulkUseCase : undefined,
             // A bulk write changed the rows underneath the listing, so the page is
-            // re-read; the selection deliberately survives it (#121 — "the selection
+            // re-read; the selection deliberately survives it ("the selection
             // is still there afterwards"), because the operator's next act is usually
             // to retry the failures or run a second verb on the same rows.
             onCompleted: ()=>{
@@ -167,7 +164,7 @@ export function makeEntityCrud(entityConstructor, options) {
         // ⚠️ **A row verb and the form's are the same runner with different
         // arguments.** `EntityTable` hands back the whole record, because that is
         // what it has; `runUseCase` takes an id, because that is what a route needs
-        // (#216). The list has no error slot of its own, so a failure lands in the
+        // The list has no error slot of its own, so a failure lands in the
         // table's own error region — the same one a failed page read uses.
         const [useCaseError, setUseCaseError] = useState(undefined);
         // Called unconditionally and the *result* gated, the way the surfaces are
@@ -227,7 +224,7 @@ export function makeEntityCrud(entityConstructor, options) {
         // so it needs a slot of its own to reach the form's error area.
         const [useCaseError, setUseCaseError] = useState(undefined);
         const id = slugToEntityId(slug != null ? slug : params.slug);
-        const ctx = mergeCrudContext(adapters, configuration, repository, pending);
+        const ctx = mergeCrudContext(adapters, repository, pending);
         const { entity, isLoading, error: loadError, reload } = useEntityRecord({
             uc: getUCFactory(),
             ctx,
@@ -248,7 +245,7 @@ export function makeEntityCrud(entityConstructor, options) {
                     entityConstructor: plan.entityConstructor,
                     loadUc: loadUCFactory(),
                     getUc: getUCFactory(),
-                    ctx: mergeCrudContext(adapters, configuration, plan.repository, pending)
+                    ctx: mergeCrudContext(adapters, plan.repository, pending)
                 }
             }));
         // Inside a workspace tab, "back to the list" is the list's tab, not a URL