@wildo-ai/saas-models 1.1.5 → 1.1.6

package/dist/esm/resources/utils/collection-export.shared.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"collection-export.shared.utils.js","sourceRoot":"","sources":["../../../../../src/resources/utils/collection-export.shared.utils.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  getMergedObjectOrUnionShape,\n  getZodDefSchemaProperty,\n  getZodType,\n  unwrapSchema,\n} from '@wildo-ai/zod-decorators';\nimport { z } from 'zod';\n\nimport type { ResourceCollectionExportConfig } from '../resources-config.shared.schemas';\nimport { ResourceCollectionExportFormat, ResourceCollectionExportRowScope } from '../resources-config.shared.schemas';\n\n/** IANA media types, one per format. */\nexport const COLLECTION_EXPORT_CONTENT_TYPES: Readonly<Record<ResourceCollectionExportFormat, string>> = {\n  [ResourceCollectionExportFormat.CSV]: 'text/csv; charset=utf-8',\n  [ResourceCollectionExportFormat.JSON]: 'application/json; charset=utf-8',\n};\n\n/** File extensions, one per format. */\nexport const COLLECTION_EXPORT_FILE_EXTENSIONS: Readonly<Record<ResourceCollectionExportFormat, string>> = {\n  [ResourceCollectionExportFormat.CSV]: 'csv',\n  [ResourceCollectionExportFormat.JSON]: 'json',\n};\n\n/** Query-parameter names the export route reads its two selectors from. */\nexport const COLLECTION_EXPORT_FORMAT_QUERY_PARAM = 'format';\nexport const COLLECTION_EXPORT_ROW_SCOPE_QUERY_PARAM = 'rowScope';\n\n/** Response header carrying the number of rows actually written. */\nexport const COLLECTION_EXPORT_ROW_COUNT_HEADER = 'X-Wildo-Export-Row-Count';\n\n/**\n * The CSV column set for an exported listing, resolved from the operation's DECLARED response shape\n * rather than from the rows.\n *\n * ## Why the schema and not the rows\n *\n * A whole-result-set export streams: the header record is written before the last page has been\n * read. Resolving columns from rows would therefore have to guess from the first page, and a column\n * that first appears on page 40 (an optional field absent from every earlier row) would be dropped\n * from a file that looks complete. Silent column loss inside a file the user then treats as\n * authoritative is exactly the failure this codebase refuses elsewhere.\n *\n * The declared shape has none of that problem: it is complete, ordered by the schema's own field\n * order (which reads far better than alphabetical), and identical across every export of the same\n * operation — so a downstream consumer can rely on the header.\n *\n * Returns `undefined` when the shape cannot be resolved, and callers must then REFUSE to render CSV\n * rather than fall back to a row-derived guess. JSON is unaffected: it carries whatever each row\n * carries, so it needs no column set at all.\n */\nexport function resolveCollectionExportCsvColumns(responseDto: z.ZodTypeAny | undefined): string[] | undefined {\n  if (!responseDto) return undefined;\n\n  // ⚠️ `getZodObjectShape` answers `{}` — NOT `undefined` — for anything that is not an object, and\n  // `{}` is truthy. Every check here is therefore on the KEY COUNT. A truthiness check reads\n  // correctly and is always satisfied, which is how the first implementation returned \"no columns\"\n  // for a schema whose shape it had successfully read.\n  const envelopeShape = getMergedObjectOrUnionShape(deepUnwrapSchema(responseDto));\n  if (Object.keys(envelopeShape).length === 0) return undefined;\n\n  // A paginated LIST/SEARCH response is `{ data: Row[], pagination: {...} }`.\n  const dataSchema = envelopeShape.data ? deepUnwrapSchema(envelopeShape.data) : undefined;\n  if (!dataSchema || getZodType(dataSchema) !== 'array') return undefined;\n\n  const elementSchema = getZodDefSchemaProperty(dataSchema, 'element');\n  if (!elementSchema) return undefined;\n\n  // `getMergedObjectOrUnionShape` rather than `getZodObjectShape`: a resource declared through a\n  // schema family (`createSchemaFamily`) has a DISCRIMINATED UNION as its row type, not an object —\n  // Wonder Todos' `todos` is exactly that, discriminated on `recurringType`, with 24 fields on one\n  // variant and 27 on the other. Reading the object shape off such an element yields nothing, which\n  // would make CSV export impossible for every inheritance resource in the framework.\n  //\n  // The union is MERGED, not sampled: a recurring row carries fields a one-off row does not, and a\n  // column set taken from one branch would drop the other's fields from a file that looks complete.\n  const rowShape = getMergedObjectOrUnionShape(deepUnwrapSchema(elementSchema));\n  const columns = Object.keys(rowShape);\n  return columns.length > 0 ? columns : undefined;\n}\n\n/**\n * Peel every wrapper a response DTO may have acquired on its way here, until an inspectable schema\n * is reached.\n *\n * A LIST response DTO is not the plain object it was authored as: the DTO builder applies\n * network-boundary coercion (dates, money bigints), which produces `pipe`/effect wrappers around the\n * envelope AND around individual fields. A single `unwrapSchema` call stops at the first of those,\n * and the caller then reports \"no columns\" for a perfectly ordinary listing — a refusal that looks\n * like a configuration problem and is really a traversal that gave up one level early.\n *\n * `pipe` is walked OUTPUT-first: what a CSV column set describes is what the caller receives.\n */\nfunction deepUnwrapSchema(schema: z.ZodTypeAny, depth = 0): z.ZodTypeAny {\n  // A cheap cycle/rabbit-hole guard: `z.lazy` chains are legal and a malformed one must not hang\n  // resource configuration.\n  if (depth > 12) return schema;\n\n  const zodType = getZodType(schema);\n  if (zodType === 'pipe') {\n    const outSchema = getZodDefSchemaProperty(schema, 'out') ?? getZodDefSchemaProperty(schema, 'in');\n    return outSchema ? deepUnwrapSchema(outSchema, depth + 1) : schema;\n  }\n  if (zodType === 'lazy') {\n    const inner = getZodDefSchemaProperty(schema, 'getter');\n    return inner ? deepUnwrapSchema(inner, depth + 1) : schema;\n  }\n\n  const innerType = getZodDefSchemaProperty(schema, 'innerType');\n  if (innerType) return deepUnwrapSchema(innerType, depth + 1);\n\n  const unwrapped = unwrapSchema(schema);\n  return unwrapped !== schema ? deepUnwrapSchema(unwrapped, depth + 1) : schema;\n}\n\n/**\n * Resolve the caller's requested format against what the operation OFFERS.\n *\n * Absent ⇒ the operation's first declared format, which is the author's stated preference (the\n * declaration is an ordered list, not a set). Present but not offered ⇒ `undefined`, and the caller\n * refuses — never a silent fallback to something the author did not publish.\n */\nexport function resolveRequestedCollectionExportFormat(\n  requested: unknown,\n  offered: readonly ResourceCollectionExportFormat[],\n): ResourceCollectionExportFormat | undefined {\n  if (requested === undefined || requested === null || requested === '') {\n    return offered[0];\n  }\n  if (typeof requested !== 'string') return undefined;\n  return offered.find((format) => format === requested);\n}\n\n/** The row-scope twin of {@link resolveRequestedCollectionExportFormat}, with the same rules. */\nexport function resolveRequestedCollectionExportRowScope(\n  requested: unknown,\n  offered: readonly ResourceCollectionExportRowScope[],\n): ResourceCollectionExportRowScope | undefined {\n  if (requested === undefined || requested === null || requested === '') {\n    return offered[0];\n  }\n  if (typeof requested !== 'string') return undefined;\n  return offered.find((rowScope) => rowScope === requested);\n}\n\n/** One offered export: a format and a row scope the operation actually declared. */\nexport interface ResourceCollectionExportSelection {\n  format: ResourceCollectionExportFormat;\n  rowScope: ResourceCollectionExportRowScope;\n}\n\n/**\n * Every combination the operation offers, format-major, in the author's declared order.\n *\n * The declaration is two ORDERED lists, and the cross product is what a user should be able to\n * choose from — an action that silently picks one pair on their behalf is the surface answering a\n * question they were never asked. Format-major because format is the coarser choice: \"CSV or JSON\"\n * separates two audiences (a spreadsheet and a system), while the row scope refines within each.\n */\nexport function listCollectionExportSelections(\n  exportConfig: ResourceCollectionExportConfig,\n): ResourceCollectionExportSelection[] {\n  const selections: ResourceCollectionExportSelection[] = [];\n  for (const format of exportConfig.formats) {\n    for (const rowScope of exportConfig.rowScopes) {\n      selections.push({ format, rowScope });\n    }\n  }\n  return selections;\n}\n\n/**\n * `<resourceType>-<ISO date>.<ext>` — stable, sortable, and free of any row content.\n *\n * The date rather than a timestamp: two exports on one day should not produce filenames a human\n * cannot tell apart at a glance, and the exact moment is in the audit trail where it belongs.\n */\nexport function buildCollectionExportFilename(\n  resourceType: string,\n  format: ResourceCollectionExportFormat,\n  now: Date,\n): string {\n  const datePart = now.toISOString().slice(0, 10);\n  return `${resourceType}-${datePart}.${COLLECTION_EXPORT_FILE_EXTENSIONS[format]}`;\n}\n"]}
+{"version":3,"file":"collection-export.shared.utils.js","sourceRoot":"","sources":["../../../../../src/resources/utils/collection-export.shared.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,2BAA2B,EAC3B,uBAAuB,EACvB,UAAU,EACV,YAAY,GACb,MAAM,0BAA0B,CAAC;AAIlC,OAAO,EAAE,8BAA8B,EAAoC,MAAM,oCAAoC,CAAC;AAEtH,wCAAwC;AACxC,MAAM,CAAC,MAAM,+BAA+B,GAA6D;IACvG,CAAC,8BAA8B,CAAC,GAAG,CAAC,EAAE,yBAAyB;IAC/D,CAAC,8BAA8B,CAAC,IAAI,CAAC,EAAE,iCAAiC;IACxE,CAAC,8BAA8B,CAAC,GAAG,CAAC,EAAE,iBAAiB;CACxD,CAAC;AAEF,uCAAuC;AACvC,MAAM,CAAC,MAAM,iCAAiC,GAA6D;IACzG,CAAC,8BAA8B,CAAC,GAAG,CAAC,EAAE,KAAK;IAC3C,CAAC,8BAA8B,CAAC,IAAI,CAAC,EAAE,MAAM;IAC7C,CAAC,8BAA8B,CAAC,GAAG,CAAC,EAAE,KAAK;CAC5C,CAAC;AAEF,2EAA2E;AAC3E,MAAM,CAAC,MAAM,oCAAoC,GAAG,QAAQ,CAAC;AAC7D,MAAM,CAAC,MAAM,uCAAuC,GAAG,UAAU,CAAC;AAElE,oEAAoE;AACpE,MAAM,CAAC,MAAM,kCAAkC,GAAG,0BAA0B,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,iCAAiC,CAAC,WAAqC;IACrF,IAAI,CAAC,WAAW;QAAE,OAAO,SAAS,CAAC;IAEnC,kGAAkG;IAClG,2FAA2F;IAC3F,iGAAiG;IACjG,qDAAqD;IACrD,MAAM,aAAa,GAAG,2BAA2B,CAAC,gBAAgB,CAAC,WAAW,CAAC,CAAC,CAAC;IACjF,IAAI,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAE9D,4EAA4E;IAC5E,MAAM,UAAU,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,gBAAgB,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACzF,IAAI,CAAC,UAAU,IAAI,UAAU,CAAC,UAAU,CAAC,KAAK,OAAO;QAAE,OAAO,SAAS,CAAC;IAExE,MAAM,aAAa,GAAG,uBAAuB,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;IACrE,IAAI,CAAC,aAAa;QAAE,OAAO,SAAS,CAAC;IAErC,+FAA+F;IAC/F,kGAAkG;IAClG,iGAAiG;IACjG,kGAAkG;IAClG,oFAAoF;IACpF,EAAE;IACF,iGAAiG;IACjG,kGAAkG;IAClG,MAAM,QAAQ,GAAG,2BAA2B,CAAC,gBAAgB,CAAC,aAAa,CAAC,CAAC,CAAC;IAC9E,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACtC,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AAClD,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAS,gBAAgB,CAAC,MAAoB,EAAE,KAAK,GAAG,CAAC;IACvD,+FAA+F;IAC/F,0BAA0B;IAC1B,IAAI,KAAK,GAAG,EAAE;QAAE,OAAO,MAAM,CAAC;IAE9B,MAAM,OAAO,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;IACnC,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACvB,MAAM,SAAS,GAAG,uBAAuB,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,uBAAuB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAClG,OAAO,SAAS,CAAC,CAAC,CAAC,gBAAgB,CAAC,SAAS,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IACrE,CAAC;IACD,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACvB,MAAM,KAAK,GAAG,uBAAuB,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QACxD,OAAO,KAAK,CAAC,CAAC,CAAC,gBAAgB,CAAC,KAAK,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAC7D,CAAC;IAED,MAAM,SAAS,GAAG,uBAAuB,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC/D,IAAI,SAAS;QAAE,OAAO,gBAAgB,CAAC,SAAS,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;IAE7D,MAAM,SAAS,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IACvC,OAAO,SAAS,KAAK,MAAM,CAAC,CAAC,CAAC,gBAAgB,CAAC,SAAS,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;AAChF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sCAAsC,CACpD,SAAkB,EAClB,OAAkD;IAElD,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,KAAK,IAAI,IAAI,SAAS,KAAK,EAAE,EAAE,CAAC;QACtE,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;IACD,IAAI,OAAO,SAAS,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACpD,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC;AACxD,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,wCAAwC,CACtD,SAAkB,EAClB,OAAoD;IAEpD,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,KAAK,IAAI,IAAI,SAAS,KAAK,EAAE,EAAE,CAAC;QACtE,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;IACD,IAAI,OAAO,SAAS,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACpD,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC;AAC5D,CAAC;AAQD;;;;;;;GAOG;AACH,MAAM,UAAU,8BAA8B,CAC5C,YAA4C;IAE5C,MAAM,UAAU,GAAwC,EAAE,CAAC;IAC3D,KAAK,MAAM,MAAM,IAAI,YAAY,CAAC,OAAO,EAAE,CAAC;QAC1C,KAAK,MAAM,QAAQ,IAAI,YAAY,CAAC,SAAS,EAAE,CAAC;YAC9C,UAAU,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,6BAA6B,CAC3C,YAAoB,EACpB,MAAsC,EACtC,GAAS;IAET,MAAM,QAAQ,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAChD,OAAO,GAAG,YAAY,IAAI,QAAQ,IAAI,iCAAiC,CAAC,MAAM,CAAC,EAAE,CAAC;AACpF,CAAC","sourcesContent":["import {\n  getMergedObjectOrUnionShape,\n  getZodDefSchemaProperty,\n  getZodType,\n  unwrapSchema,\n} from '@wildo-ai/zod-decorators';\nimport { z } from 'zod';\n\nimport type { ResourceCollectionExportConfig } from '../resources-config.shared.schemas';\nimport { ResourceCollectionExportFormat, ResourceCollectionExportRowScope } from '../resources-config.shared.schemas';\n\n/** IANA media types, one per format. */\nexport const COLLECTION_EXPORT_CONTENT_TYPES: Readonly<Record<ResourceCollectionExportFormat, string>> = {\n  [ResourceCollectionExportFormat.CSV]: 'text/csv; charset=utf-8',\n  [ResourceCollectionExportFormat.JSON]: 'application/json; charset=utf-8',\n  [ResourceCollectionExportFormat.PDF]: 'application/pdf',\n};\n\n/** File extensions, one per format. */\nexport const COLLECTION_EXPORT_FILE_EXTENSIONS: Readonly<Record<ResourceCollectionExportFormat, string>> = {\n  [ResourceCollectionExportFormat.CSV]: 'csv',\n  [ResourceCollectionExportFormat.JSON]: 'json',\n  [ResourceCollectionExportFormat.PDF]: 'pdf',\n};\n\n/** Query-parameter names the export route reads its two selectors from. */\nexport const COLLECTION_EXPORT_FORMAT_QUERY_PARAM = 'format';\nexport const COLLECTION_EXPORT_ROW_SCOPE_QUERY_PARAM = 'rowScope';\n\n/** Response header carrying the number of rows actually written. */\nexport const COLLECTION_EXPORT_ROW_COUNT_HEADER = 'X-Wildo-Export-Row-Count';\n\n/**\n * The CSV column set for an exported listing, resolved from the operation's DECLARED response shape\n * rather than from the rows.\n *\n * ## Why the schema and not the rows\n *\n * A whole-result-set export streams: the header record is written before the last page has been\n * read. Resolving columns from rows would therefore have to guess from the first page, and a column\n * that first appears on page 40 (an optional field absent from every earlier row) would be dropped\n * from a file that looks complete. Silent column loss inside a file the user then treats as\n * authoritative is exactly the failure this codebase refuses elsewhere.\n *\n * The declared shape has none of that problem: it is complete, ordered by the schema's own field\n * order (which reads far better than alphabetical), and identical across every export of the same\n * operation — so a downstream consumer can rely on the header.\n *\n * Returns `undefined` when the shape cannot be resolved, and callers must then REFUSE to render CSV\n * rather than fall back to a row-derived guess. JSON is unaffected: it carries whatever each row\n * carries, so it needs no column set at all.\n */\nexport function resolveCollectionExportCsvColumns(responseDto: z.ZodTypeAny | undefined): string[] | undefined {\n  if (!responseDto) return undefined;\n\n  // ⚠️ `getZodObjectShape` answers `{}` — NOT `undefined` — for anything that is not an object, and\n  // `{}` is truthy. Every check here is therefore on the KEY COUNT. A truthiness check reads\n  // correctly and is always satisfied, which is how the first implementation returned \"no columns\"\n  // for a schema whose shape it had successfully read.\n  const envelopeShape = getMergedObjectOrUnionShape(deepUnwrapSchema(responseDto));\n  if (Object.keys(envelopeShape).length === 0) return undefined;\n\n  // A paginated LIST/SEARCH response is `{ data: Row[], pagination: {...} }`.\n  const dataSchema = envelopeShape.data ? deepUnwrapSchema(envelopeShape.data) : undefined;\n  if (!dataSchema || getZodType(dataSchema) !== 'array') return undefined;\n\n  const elementSchema = getZodDefSchemaProperty(dataSchema, 'element');\n  if (!elementSchema) return undefined;\n\n  // `getMergedObjectOrUnionShape` rather than `getZodObjectShape`: a resource declared through a\n  // schema family (`createSchemaFamily`) has a DISCRIMINATED UNION as its row type, not an object —\n  // Wonder Todos' `todos` is exactly that, discriminated on `recurringType`, with 24 fields on one\n  // variant and 27 on the other. Reading the object shape off such an element yields nothing, which\n  // would make CSV export impossible for every inheritance resource in the framework.\n  //\n  // The union is MERGED, not sampled: a recurring row carries fields a one-off row does not, and a\n  // column set taken from one branch would drop the other's fields from a file that looks complete.\n  const rowShape = getMergedObjectOrUnionShape(deepUnwrapSchema(elementSchema));\n  const columns = Object.keys(rowShape);\n  return columns.length > 0 ? columns : undefined;\n}\n\n/**\n * Peel every wrapper a response DTO may have acquired on its way here, until an inspectable schema\n * is reached.\n *\n * A LIST response DTO is not the plain object it was authored as: the DTO builder applies\n * network-boundary coercion (dates, money bigints), which produces `pipe`/effect wrappers around the\n * envelope AND around individual fields. A single `unwrapSchema` call stops at the first of those,\n * and the caller then reports \"no columns\" for a perfectly ordinary listing — a refusal that looks\n * like a configuration problem and is really a traversal that gave up one level early.\n *\n * `pipe` is walked OUTPUT-first: what a CSV column set describes is what the caller receives.\n */\nfunction deepUnwrapSchema(schema: z.ZodTypeAny, depth = 0): z.ZodTypeAny {\n  // A cheap cycle/rabbit-hole guard: `z.lazy` chains are legal and a malformed one must not hang\n  // resource configuration.\n  if (depth > 12) return schema;\n\n  const zodType = getZodType(schema);\n  if (zodType === 'pipe') {\n    const outSchema = getZodDefSchemaProperty(schema, 'out') ?? getZodDefSchemaProperty(schema, 'in');\n    return outSchema ? deepUnwrapSchema(outSchema, depth + 1) : schema;\n  }\n  if (zodType === 'lazy') {\n    const inner = getZodDefSchemaProperty(schema, 'getter');\n    return inner ? deepUnwrapSchema(inner, depth + 1) : schema;\n  }\n\n  const innerType = getZodDefSchemaProperty(schema, 'innerType');\n  if (innerType) return deepUnwrapSchema(innerType, depth + 1);\n\n  const unwrapped = unwrapSchema(schema);\n  return unwrapped !== schema ? deepUnwrapSchema(unwrapped, depth + 1) : schema;\n}\n\n/**\n * Resolve the caller's requested format against what the operation OFFERS.\n *\n * Absent ⇒ the operation's first declared format, which is the author's stated preference (the\n * declaration is an ordered list, not a set). Present but not offered ⇒ `undefined`, and the caller\n * refuses — never a silent fallback to something the author did not publish.\n */\nexport function resolveRequestedCollectionExportFormat(\n  requested: unknown,\n  offered: readonly ResourceCollectionExportFormat[],\n): ResourceCollectionExportFormat | undefined {\n  if (requested === undefined || requested === null || requested === '') {\n    return offered[0];\n  }\n  if (typeof requested !== 'string') return undefined;\n  return offered.find((format) => format === requested);\n}\n\n/** The row-scope twin of {@link resolveRequestedCollectionExportFormat}, with the same rules. */\nexport function resolveRequestedCollectionExportRowScope(\n  requested: unknown,\n  offered: readonly ResourceCollectionExportRowScope[],\n): ResourceCollectionExportRowScope | undefined {\n  if (requested === undefined || requested === null || requested === '') {\n    return offered[0];\n  }\n  if (typeof requested !== 'string') return undefined;\n  return offered.find((rowScope) => rowScope === requested);\n}\n\n/** One offered export: a format and a row scope the operation actually declared. */\nexport interface ResourceCollectionExportSelection {\n  format: ResourceCollectionExportFormat;\n  rowScope: ResourceCollectionExportRowScope;\n}\n\n/**\n * Every combination the operation offers, format-major, in the author's declared order.\n *\n * The declaration is two ORDERED lists, and the cross product is what a user should be able to\n * choose from — an action that silently picks one pair on their behalf is the surface answering a\n * question they were never asked. Format-major because format is the coarser choice: \"CSV, JSON or PDF\"\n * separates audiences (a spreadsheet, a system, a reader), while the row scope refines within each.\n */\nexport function listCollectionExportSelections(\n  exportConfig: ResourceCollectionExportConfig,\n): ResourceCollectionExportSelection[] {\n  const selections: ResourceCollectionExportSelection[] = [];\n  for (const format of exportConfig.formats) {\n    for (const rowScope of exportConfig.rowScopes) {\n      selections.push({ format, rowScope });\n    }\n  }\n  return selections;\n}\n\n/**\n * `<resourceType>-<ISO date>.<ext>` — stable, sortable, and free of any row content.\n *\n * The date rather than a timestamp: two exports on one day should not produce filenames a human\n * cannot tell apart at a glance, and the exact moment is in the audit trail where it belongs.\n */\nexport function buildCollectionExportFilename(\n  resourceType: string,\n  format: ResourceCollectionExportFormat,\n  now: Date,\n): string {\n  const datePart = now.toISOString().slice(0, 10);\n  return `${resourceType}-${datePart}.${COLLECTION_EXPORT_FILE_EXTENSIONS[format]}`;\n}\n"]}

package/dist/esm/resources/utils/http-api-write-declaration.shared.utils.d.ts

@@ -0,0 +1,103 @@
+/**
+ * The authoring contract of a WRITABLE read-through resource (#1679) — what a resource must declare
+ * before the engine will send a create, update or delete to a system of record it does not own.
+ *
+ * Checked in the resource FACTORY, at authoring, because every rule here is decidable from the one
+ * file an author is writing: the binding, the operation list and the schema. What is NOT decidable
+ * here — the instance's partition field, whether the dialect implements writes — needs the saas
+ * configuration and the engine's dialect registry, so it is checked at boot registration instead.
+ *
+ * Every refusal names the fix. A write door into somebody else's ERP is the declaration where a
+ * silently-accepted mistake costs the most, because the mistake is made against data the platform
+ * cannot restore.
+ */
+import type { z } from 'zod';
+import { HttpApiWriteVerb, type HttpApiResourceBinding } from '../../http-api-binding/http-api-binding.shared.schemas';
+import { ResourceOperationIdempotencyKeyRequirement } from '../../requests/idempotency-key.shared';
+import { CoreResourceOperation } from '../resources.shared.core.definitions';
+import { ResourceOperation_ServiceRuntimeMode } from '../resources.shared.schemas';
+/**
+ * The core operation each opened verb reaches, and the only three a read-through resource may write
+ * through. Total over {@link HttpApiWriteVerb}, so a fourth verb is a compile error here until
+ * somebody decides which operation it is.
+ */
+export declare const HTTP_API_WRITE_VERB_CORE_OPERATION: Readonly<Record<HttpApiWriteVerb, CoreResourceOperation>>;
+/**
+ * The write verb a core operation IS on a read-through resource, or `undefined` for a read.
+ *
+ * The one mapping both the authoring check and the repository's dispatch read, so the two cannot
+ * disagree about whether an operation is a write.
+ */
+export declare function resolveHttpApiWriteVerb(coreOperation: unknown): HttpApiWriteVerb | undefined;
+/** What the factory knows about ONE declared operation, reduced to what these rules read. */
+interface HttpApiWriteOperationFacts {
+    readonly operationKey: string;
+    /** The core semantics of each variant: the operation itself for a core one, `resourceOperationLike` for a custom one. */
+    readonly effectiveOperations: readonly unknown[];
+    readonly variants: ReadonlyArray<{
+        readonly idempotencyKey?: ResourceOperationIdempotencyKeyRequirement;
+        readonly haveBulkOperation?: boolean;
+    }>;
+    readonly serviceRuntimeMode?: ResourceOperation_ServiceRuntimeMode;
+}
+/**
+ * Reduce the authored operation declarations to {@link HttpApiWriteOperationFacts}.
+ *
+ * Enumerated by EFFECTIVE semantics, the way the pipeline's CLOSED-population rule enumerates
+ * creates: a core operation is its own semantics, a custom one borrows them per variant through
+ * `resourceOperationLike`, and both sources are unioned because neither sees the other's members.
+ * A custom operation that borrows UPDATE is exactly how an author would write a remote "confirm"
+ * without thinking of it as a write — so it is a write here too.
+ */
+export declare function collectHttpApiWriteOperationFacts(coreOperations: readonly unknown[], operationsConfiguration: Readonly<Record<string, unknown>> | undefined): HttpApiWriteOperationFacts[];
+/**
+ * The `Idempotency-Key` requirement a variant of a read-through WRITE carries — always REQUIRED.
+ *
+ * DERIVED rather than demanded from the author, because it has one legal value: a remote write cannot
+ * be rolled back, so a retry after a lost response must replay the first outcome instead of writing a
+ * second time, and only a required key makes every retry replayable. Asking an author to type the one
+ * answer the mechanism already knows is a question nobody should be asked (`derive-before-you-ask`).
+ * `ACCEPTED` is refused by {@link assertHttpApiWriteDeclarationCoherence}, never silently upgraded.
+ *
+ * The AUTHORED value comes first so the factory's forwarding line still reads
+ * `idempotencyKey: resolveHttpApiWriteIdempotencyKeyRequirement(variantParams.idempotencyKey, …)`, the shape
+ * `operation-variant-field-forwarding.guard.test.ts` recognises as forwarding.
+ */
+export declare function resolveHttpApiWriteIdempotencyKeyRequirement(authored: ResourceOperationIdempotencyKeyRequirement | undefined, isReadThroughWrite: boolean): ResourceOperationIdempotencyKeyRequirement | undefined;
+/**
+ * Refuse every write declaration on a read-through resource that the engine could not honour.
+ *
+ * Throws a plain `Error` naming the rule and the fix; the factory wraps it into its own configuration
+ * error with the resource identifier in front.
+ *
+ * The rules, and why each one exists:
+ *
+ *  1. **No bulk write operation**, opened or not — see {@link BULK_WRITE_OPERATIONS}. Nor a
+ *     `haveBulkOperation` twin of a write, which every tier would run as N single-row writes.
+ *  2. **Every write operation's verb is OPENED by the binding**, and **every opened verb has an
+ *     operation**. Both directions: the first is a route that would answer a refusal forever, the
+ *     second a declared door nobody can reach — and an inert declaration that looks like a control is
+ *     worse than none.
+ *  3. **Every write variant runs INLINE.** A queued or background execution cannot carry the
+ *     `Idempotency-Key`, so a retried request could not replay; the service tier refuses a key on a
+ *     non-INLINE operation already, and a key is required here.
+ *  4. **No write variant declares `Idempotency-Key: ACCEPTED`.** See
+ *     {@link resolveHttpApiWriteIdempotencyKeyRequirement}.
+ *  5. *(Moved, #2010.)* The erasure-stance rule this list carried — a binding that WRITES personal-data fields
+ *     may not declare `NO_SUBJECT_DATA` — is now `personalFieldsContradictingNoSubjectDataStance`, which the
+ *     factory applies to EVERY read-through binding and every pipeline copy. Reading those fields out of a
+ *     system that "holds no subject data" is the same contradiction as writing them into it.
+ *  6. **A `VERSION_CHECKED` binding's version field is one the UPDATE can carry and the CREATE cannot** (#1724). The
+ *     field must exist on the schema, be admitted to the update payload (the caller sends the version it read), and be
+ *     excluded from create (a new row has no version yet, and the vendor stamps it). It must be a STRING: the check
+ *     compares the caller's value byte for byte with the vendor's raw one, and a date schema would coerce it on the way
+ *     in and make every update stale. Whether it maps onto the vendor's `rowVersionField` needs the facet, and is
+ *     checked at boot.
+ */
+export declare function assertHttpApiWriteDeclarationCoherence(params: {
+    readonly binding: HttpApiResourceBinding;
+    readonly operations: readonly HttpApiWriteOperationFacts[];
+    readonly mainSchema: z.ZodTypeAny;
+}): void;
+export {};
+//# sourceMappingURL=http-api-write-declaration.shared.utils.d.ts.map

package/dist/esm/resources/utils/http-api-write-declaration.shared.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-api-write-declaration.shared.utils.d.ts","sourceRoot":"","sources":["../../../../../src/resources/utils/http-api-write-declaration.shared.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAG7B,OAAO,EAEL,gBAAgB,EAChB,KAAK,sBAAsB,EAC5B,MAAM,wDAAwD,CAAC;AAChE,OAAO,EAAE,0CAA0C,EAAE,MAAM,uCAAuC,CAAC;AACnG,OAAO,EAAE,qBAAqB,EAAE,MAAM,sCAAsC,CAAC;AAC7E,OAAO,EAAE,oCAAoC,EAAE,MAAM,6BAA6B,CAAC;AAEnF;;;;GAIG;AACH,eAAO,MAAM,kCAAkC,EAAE,QAAQ,CAAC,MAAM,CAAC,gBAAgB,EAAE,qBAAqB,CAAC,CAIvG,CAAC;AAEH;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,OAAO,GAAG,gBAAgB,GAAG,SAAS,CAK5F;AAeD,6FAA6F;AAC7F,UAAU,0BAA0B;IAClC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,yHAAyH;IACzH,QAAQ,CAAC,mBAAmB,EAAE,SAAS,OAAO,EAAE,CAAC;IACjD,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;QAC/B,QAAQ,CAAC,cAAc,CAAC,EAAE,0CAA0C,CAAC;QACrE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;KACtC,CAAC,CAAC;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,oCAAoC,CAAC;CACpE;AAED;;;;;;;;GAQG;AACH,wBAAgB,iCAAiC,CAC/C,cAAc,EAAE,SAAS,OAAO,EAAE,EAClC,uBAAuB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,GACrE,0BAA0B,EAAE,CAsB9B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,4CAA4C,CAC1D,QAAQ,EAAE,0CAA0C,GAAG,SAAS,EAChE,kBAAkB,EAAE,OAAO,GAC1B,0CAA0C,GAAG,SAAS,CAGxD;AAiFD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,sCAAsC,CAAC,MAAM,EAAE;IAC7D,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAC;IACzC,QAAQ,CAAC,UAAU,EAAE,SAAS,0BAA0B,EAAE,CAAC;IAC3D,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC,UAAU,CAAC;CACnC,GAAG,IAAI,CA8GP"}

package/dist/esm/resources/utils/http-api-write-declaration.shared.utils.js

@@ -0,0 +1,275 @@
+/**
+ * The authoring contract of a WRITABLE read-through resource (#1679) — what a resource must declare
+ * before the engine will send a create, update or delete to a system of record it does not own.
+ *
+ * Checked in the resource FACTORY, at authoring, because every rule here is decidable from the one
+ * file an author is writing: the binding, the operation list and the schema. What is NOT decidable
+ * here — the instance's partition field, whether the dialect implements writes — needs the saas
+ * configuration and the engine's dialect registry, so it is checked at boot registration instead.
+ *
+ * Every refusal names the fix. A write door into somebody else's ERP is the declaration where a
+ * silently-accepted mistake costs the most, because the mistake is made against data the platform
+ * cannot restore.
+ */
+import { getZodObjectShape, isExcludedFromCreate, isExcludedFromUpdate, isZodObject, unwrapSchema } from '@wildo-ai/zod-decorators';
+import { HttpApiWriteConcurrencyMode, HttpApiWriteVerb, } from '../../http-api-binding/http-api-binding.shared.schemas.js';
+import { ResourceOperationIdempotencyKeyRequirement } from '../../requests/idempotency-key.shared.js';
+import { CoreResourceOperation } from '../resources.shared.core.definitions.js';
+import { ResourceOperation_ServiceRuntimeMode } from '../resources.shared.schemas.js';
+/**
+ * The core operation each opened verb reaches, and the only three a read-through resource may write
+ * through. Total over {@link HttpApiWriteVerb}, so a fourth verb is a compile error here until
+ * somebody decides which operation it is.
+ */
+export const HTTP_API_WRITE_VERB_CORE_OPERATION = Object.freeze({
+    [HttpApiWriteVerb.CREATE]: CoreResourceOperation.CREATE,
+    [HttpApiWriteVerb.UPDATE]: CoreResourceOperation.UPDATE,
+    [HttpApiWriteVerb.DELETE]: CoreResourceOperation.DELETE,
+});
+/**
+ * The write verb a core operation IS on a read-through resource, or `undefined` for a read.
+ *
+ * The one mapping both the authoring check and the repository's dispatch read, so the two cannot
+ * disagree about whether an operation is a write.
+ */
+export function resolveHttpApiWriteVerb(coreOperation) {
+    for (const [verb, operation] of Object.entries(HTTP_API_WRITE_VERB_CORE_OPERATION)) {
+        if (operation === coreOperation)
+            return verb;
+    }
+    return undefined;
+}
+/**
+ * The BULK write operations, refused on a read-through resource whatever the binding opens.
+ *
+ * A bulk write against a system the platform does not own is N remote calls with no atomicity: any
+ * of them can fail after the earlier ones landed, and there is no transaction to roll back into. The
+ * engine opens single-row writes only, which is what an author can reason about one row at a time.
+ */
+const BULK_WRITE_OPERATIONS = new Set([
+    CoreResourceOperation.CREATE_MANY,
+    CoreResourceOperation.UPDATE_MANY,
+    CoreResourceOperation.DELETE_MANY,
+]);
+/**
+ * Reduce the authored operation declarations to {@link HttpApiWriteOperationFacts}.
+ *
+ * Enumerated by EFFECTIVE semantics, the way the pipeline's CLOSED-population rule enumerates
+ * creates: a core operation is its own semantics, a custom one borrows them per variant through
+ * `resourceOperationLike`, and both sources are unioned because neither sees the other's members.
+ * A custom operation that borrows UPDATE is exactly how an author would write a remote "confirm"
+ * without thinking of it as a write — so it is a write here too.
+ */
+export function collectHttpApiWriteOperationFacts(coreOperations, operationsConfiguration) {
+    const facts = new Map();
+    for (const operation of coreOperations) {
+        facts.set(String(operation), { operationKey: String(operation), effectiveOperations: [operation], variants: [] });
+    }
+    for (const [operationKey, operationConfig] of Object.entries(operationsConfiguration ?? {})) {
+        const config = (operationConfig ?? {});
+        const variants = config.variants ?? [];
+        const isCore = coreOperations.includes(operationKey);
+        facts.set(operationKey, {
+            operationKey,
+            effectiveOperations: variants.length > 0 && !isCore
+                ? variants.map((variant) => variant.resourceOperationLike ?? operationKey)
+                : [operationKey],
+            variants,
+            serviceRuntimeMode: config.serviceRuntimeMode,
+        });
+    }
+    return [...facts.values()];
+}
+/**
+ * The `Idempotency-Key` requirement a variant of a read-through WRITE carries — always REQUIRED.
+ *
+ * DERIVED rather than demanded from the author, because it has one legal value: a remote write cannot
+ * be rolled back, so a retry after a lost response must replay the first outcome instead of writing a
+ * second time, and only a required key makes every retry replayable. Asking an author to type the one
+ * answer the mechanism already knows is a question nobody should be asked (`derive-before-you-ask`).
+ * `ACCEPTED` is refused by {@link assertHttpApiWriteDeclarationCoherence}, never silently upgraded.
+ *
+ * The AUTHORED value comes first so the factory's forwarding line still reads
+ * `idempotencyKey: resolveHttpApiWriteIdempotencyKeyRequirement(variantParams.idempotencyKey, …)`, the shape
+ * `operation-variant-field-forwarding.guard.test.ts` recognises as forwarding.
+ */
+export function resolveHttpApiWriteIdempotencyKeyRequirement(authored, isReadThroughWrite) {
+    if (!isReadThroughWrite)
+        return authored;
+    return ResourceOperationIdempotencyKeyRequirement.REQUIRED;
+}
+/**
+ * The operations the binding's declared actions name as their HTTP doors, keyed by operation.
+ *
+ * One operation runs one action: two actions naming the same door would make the operation's meaning depend on which
+ * one its implementation happens to hand to the executor, so it is refused here rather than decided there.
+ */
+function collectSystemOfRecordActionDoors(binding) {
+    const doors = new Map();
+    for (const [actionName, action] of Object.entries(binding.actions ?? {})) {
+        if (action.operation === undefined)
+            continue;
+        const existing = doors.get(action.operation);
+        if (existing !== undefined) {
+            throw new Error(`operation '${action.operation}' is named as the door of two actions, '${existing.actionName}' and '${actionName}'. `
+                + 'One operation runs one action; declare a second operation for the second action.');
+        }
+        doors.set(action.operation, { actionName, writes: action.writes });
+    }
+    return doors;
+}
+/**
+ * Hold an action's HTTP door to the ACTION's rules instead of the row-write rules (#1678 review, F1).
+ *
+ * A door does not write a row of the bound entity: its implementation hands the request to the system-of-record action
+ * executor, which authorizes, confines, sends and audits the action. So `writableVerbs` does not open it, and it opens
+ * nothing. What it must still be is honest about the effect it has:
+ *
+ * - a WRITING action changes remote state that cannot be rolled back, so every variant borrows a SINGLE-ROW mutation verb
+ *   (never a read: a read-shaped route is a GET and claims its repeat is harmless, and the boot validator refuses a key on
+ *   one), requires the `Idempotency-Key` (the executor refuses a writing action without one, so anything less is a door
+ *   that always refuses), and runs INLINE (a queued execution cannot carry the key);
+ * - a NON-writing action (a vendor computation) is left to the ordinary rules for the verb it borrows.
+ *
+ * Never a bulk borrow: one request is one action on one target.
+ */
+function assertSystemOfRecordActionDoorCoherence(operation, door) {
+    const bulk = operation.effectiveOperations.find((effective) => BULK_WRITE_OPERATIONS.has(effective));
+    if (bulk !== undefined) {
+        throw new Error(`operation '${operation.operationKey}' is the door of action '${door.actionName}' and borrows a bulk verb ('${String(bulk)}'). `
+            + 'One request runs one action on one target; borrow a single-row verb.');
+    }
+    if (!door.writes)
+        return;
+    const readBorrow = operation.effectiveOperations.find((effective) => resolveHttpApiWriteVerb(effective) === undefined);
+    if (readBorrow !== undefined) {
+        throw new Error(`operation '${operation.operationKey}' is the door of action '${door.actionName}', which writes, and borrows '${String(readBorrow)}', `
+            + 'which is not a mutation. A state-changing route must not be read-shaped: it would be a GET, and a required Idempotency-Key '
+            + 'on a read is refused at boot. Borrow update (an action on one record) or create (an action that makes one) in resourceOperationLike.');
+    }
+    const unkeyed = operation.variants.find((variant) => variant.idempotencyKey !== ResourceOperationIdempotencyKeyRequirement.REQUIRED);
+    if (unkeyed !== undefined) {
+        throw new Error(`operation '${operation.operationKey}' is the door of action '${door.actionName}', which writes, and does not require an `
+            + 'Idempotency-Key on every variant. The executor refuses a writing action without one, so the route would refuse every request; '
+            + `declare idempotencyKey: '${ResourceOperationIdempotencyKeyRequirement.REQUIRED}'.`);
+    }
+    if (operation.serviceRuntimeMode !== undefined
+        && operation.serviceRuntimeMode !== ResourceOperation_ServiceRuntimeMode.INLINE) {
+        throw new Error(`operation '${operation.operationKey}' is the door of action '${door.actionName}' and runs '${operation.serviceRuntimeMode}'. `
+            + 'A writing action runs INLINE: a queued or background execution cannot carry its Idempotency-Key. Remove serviceRuntimeMode.');
+    }
+}
+/**
+ * Refuse every write declaration on a read-through resource that the engine could not honour.
+ *
+ * Throws a plain `Error` naming the rule and the fix; the factory wraps it into its own configuration
+ * error with the resource identifier in front.
+ *
+ * The rules, and why each one exists:
+ *
+ *  1. **No bulk write operation**, opened or not — see {@link BULK_WRITE_OPERATIONS}. Nor a
+ *     `haveBulkOperation` twin of a write, which every tier would run as N single-row writes.
+ *  2. **Every write operation's verb is OPENED by the binding**, and **every opened verb has an
+ *     operation**. Both directions: the first is a route that would answer a refusal forever, the
+ *     second a declared door nobody can reach — and an inert declaration that looks like a control is
+ *     worse than none.
+ *  3. **Every write variant runs INLINE.** A queued or background execution cannot carry the
+ *     `Idempotency-Key`, so a retried request could not replay; the service tier refuses a key on a
+ *     non-INLINE operation already, and a key is required here.
+ *  4. **No write variant declares `Idempotency-Key: ACCEPTED`.** See
+ *     {@link resolveHttpApiWriteIdempotencyKeyRequirement}.
+ *  5. *(Moved, #2010.)* The erasure-stance rule this list carried — a binding that WRITES personal-data fields
+ *     may not declare `NO_SUBJECT_DATA` — is now `personalFieldsContradictingNoSubjectDataStance`, which the
+ *     factory applies to EVERY read-through binding and every pipeline copy. Reading those fields out of a
+ *     system that "holds no subject data" is the same contradiction as writing them into it.
+ *  6. **A `VERSION_CHECKED` binding's version field is one the UPDATE can carry and the CREATE cannot** (#1724). The
+ *     field must exist on the schema, be admitted to the update payload (the caller sends the version it read), and be
+ *     excluded from create (a new row has no version yet, and the vendor stamps it). It must be a STRING: the check
+ *     compares the caller's value byte for byte with the vendor's raw one, and a date schema would coerce it on the way
+ *     in and make every update stale. Whether it maps onto the vendor's `rowVersionField` needs the facet, and is
+ *     checked at boot.
+ */
+export function assertHttpApiWriteDeclarationCoherence(params) {
+    const { binding, operations, mainSchema } = params;
+    const opened = new Set(binding.writableVerbs);
+    const reached = new Set();
+    const actionDoors = collectSystemOfRecordActionDoors(binding);
+    // Checked BEFORE the operations: a door named after a missing operation usually means the author mistyped it, and the
+    // operation they meant would otherwise be refused first as an unopened row write — a message about the wrong thing.
+    const declaredOperationKeys = new Set(operations.map((operation) => operation.operationKey));
+    for (const [operationKey, door] of actionDoors) {
+        if (!declaredOperationKeys.has(operationKey)) {
+            throw new Error(`actions.${door.actionName} names '${operationKey}' as its door, and this resource declares no such operation. `
+                + 'Declare the custom operation, or remove the `operation` from the action.');
+        }
+    }
+    for (const operation of operations) {
+        const door = actionDoors.get(operation.operationKey);
+        if (door !== undefined) {
+            assertSystemOfRecordActionDoorCoherence(operation, door);
+            continue;
+        }
+        const bulk = operation.effectiveOperations.find((effective) => BULK_WRITE_OPERATIONS.has(effective));
+        if (bulk !== undefined) {
+            throw new Error(`operation '${operation.operationKey}' is a bulk write ('${String(bulk)}'), which a read-through resource never runs: `
+                + 'N remote writes have no transaction to roll back into when one of them fails after the others landed. '
+                + 'Declare the single-row create/update/delete instead.');
+        }
+        const verbs = operation.effectiveOperations
+            .map((effective) => resolveHttpApiWriteVerb(effective))
+            .filter((verb) => verb !== undefined);
+        if (verbs.length === 0)
+            continue;
+        for (const verb of verbs) {
+            if (!opened.has(verb)) {
+                throw new Error(`operation '${operation.operationKey}' writes ('${verb}'), and httpApiBinding.writableVerbs does not open '${verb}'. `
+                    + `Add '${verb}' to writableVerbs to open the write toward '${binding.system}', or remove the operation.`);
+            }
+            reached.add(verb);
+        }
+        if (operation.variants.some((variant) => variant.haveBulkOperation === true)) {
+            throw new Error(`operation '${operation.operationKey}' declares a bulk twin (haveBulkOperation), which a read-through resource never runs — `
+                + 'one request would become N remote writes with no atomicity. Remove haveBulkOperation.');
+        }
+        if (operation.serviceRuntimeMode !== undefined
+            && operation.serviceRuntimeMode !== ResourceOperation_ServiceRuntimeMode.INLINE) {
+            throw new Error(`operation '${operation.operationKey}' writes to '${binding.system}' with serviceRuntimeMode '${operation.serviceRuntimeMode}'. `
+                + 'A remote write runs INLINE: its Idempotency-Key is required, and a queued or background execution cannot carry one, '
+                + 'so a retried request could not replay its first outcome. Remove serviceRuntimeMode.');
+        }
+        const accepted = operation.variants.find((variant) => variant.idempotencyKey === ResourceOperationIdempotencyKeyRequirement.ACCEPTED);
+        if (accepted !== undefined) {
+            throw new Error(`operation '${operation.operationKey}' declares idempotencyKey 'accepted'. A write to a system of record cannot be rolled back, `
+                + 'so every retry must replay the first outcome: the key is REQUIRED on every write variant, and the engine sets it for you. '
+                + 'Remove the idempotencyKey declaration.');
+        }
+    }
+    for (const verb of opened) {
+        if (!reached.has(verb)) {
+            throw new Error(`httpApiBinding.writableVerbs opens '${verb}', and no operation of this resource performs it. An opened write nobody can `
+                + `reach is a declaration that decides nothing; declare the ${HTTP_API_WRITE_VERB_CORE_OPERATION[verb]} operation, or remove the verb.`);
+        }
+    }
+    if (binding.writeConcurrency?.mode === HttpApiWriteConcurrencyMode.VERSION_CHECKED && isZodObject(mainSchema)) {
+        const versionField = binding.writeConcurrency.versionField;
+        const fieldSchema = getZodObjectShape(mainSchema)[versionField];
+        if (fieldSchema === undefined) {
+            throw new Error(`httpApiBinding.writeConcurrency.versionField names '${versionField}', which this resource's schema does not declare. `
+                + 'Declare the field (mapped to the vendor\'s row version, e.g. Odoo `write_date`) so a caller can read it and send it back.');
+        }
+        const unwrapped = unwrapSchema(fieldSchema);
+        if (unwrapped?._zod?.def?.type !== 'string') {
+            throw new Error(`httpApiBinding.writeConcurrency.versionField '${versionField}' must be a string schema: the version is compared byte for `
+                + 'byte with what the vendor served (Odoo `write_date`, "YYYY-MM-DD HH:MM:SS"), and a date or number schema would re-format it.');
+        }
+        if (isExcludedFromUpdate(fieldSchema)) {
+            throw new Error(`httpApiBinding.writeConcurrency.versionField '${versionField}' is excluded from UPDATE, so no caller could send the version `
+                + 'it read and every update would be refused. Remove .excludeFromUpdate() from it.');
+        }
+        if (opened.has(HttpApiWriteVerb.CREATE) && !isExcludedFromCreate(fieldSchema)) {
+            throw new Error(`httpApiBinding.writeConcurrency.versionField '${versionField}' may be sent on CREATE, and a new row has no version: the `
+                + 'vendor stamps it. Declare it .excludeFromCreate().');
+        }
+    }
+}
+//# sourceMappingURL=http-api-write-declaration.shared.utils.js.map

package/dist/esm/resources/utils/http-api-write-declaration.shared.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-api-write-declaration.shared.utils.js","sourceRoot":"","sources":["../../../../../src/resources/utils/http-api-write-declaration.shared.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The authoring contract of a WRITABLE read-through resource (#1679) — what a resource must declare\n * before the engine will send a create, update or delete to a system of record it does not own.\n *\n * Checked in the resource FACTORY, at authoring, because every rule here is decidable from the one\n * file an author is writing: the binding, the operation list and the schema. What is NOT decidable\n * here — the instance's partition field, whether the dialect implements writes — needs the saas\n * configuration and the engine's dialect registry, so it is checked at boot registration instead.\n *\n * Every refusal names the fix. A write door into somebody else's ERP is the declaration where a\n * silently-accepted mistake costs the most, because the mistake is made against data the platform\n * cannot restore.\n */\n\nimport type { z } from 'zod';\nimport { getZodObjectShape, isExcludedFromCreate, isExcludedFromUpdate, isZodObject, unwrapSchema } from '@wildo-ai/zod-decorators';\n\nimport {\n  HttpApiWriteConcurrencyMode,\n  HttpApiWriteVerb,\n  type HttpApiResourceBinding,\n} from '../../http-api-binding/http-api-binding.shared.schemas';\nimport { ResourceOperationIdempotencyKeyRequirement } from '../../requests/idempotency-key.shared';\nimport { CoreResourceOperation } from '../resources.shared.core.definitions';\nimport { ResourceOperation_ServiceRuntimeMode } from '../resources.shared.schemas';\n\n/**\n * The core operation each opened verb reaches, and the only three a read-through resource may write\n * through. Total over {@link HttpApiWriteVerb}, so a fourth verb is a compile error here until\n * somebody decides which operation it is.\n */\nexport const HTTP_API_WRITE_VERB_CORE_OPERATION: Readonly<Record<HttpApiWriteVerb, CoreResourceOperation>> = Object.freeze({\n  [HttpApiWriteVerb.CREATE]: CoreResourceOperation.CREATE,\n  [HttpApiWriteVerb.UPDATE]: CoreResourceOperation.UPDATE,\n  [HttpApiWriteVerb.DELETE]: CoreResourceOperation.DELETE,\n});\n\n/**\n * The write verb a core operation IS on a read-through resource, or `undefined` for a read.\n *\n * The one mapping both the authoring check and the repository's dispatch read, so the two cannot\n * disagree about whether an operation is a write.\n */\nexport function resolveHttpApiWriteVerb(coreOperation: unknown): HttpApiWriteVerb | undefined {\n  for (const [verb, operation] of Object.entries(HTTP_API_WRITE_VERB_CORE_OPERATION) as Array<[HttpApiWriteVerb, CoreResourceOperation]>) {\n    if (operation === coreOperation) return verb;\n  }\n  return undefined;\n}\n\n/**\n * The BULK write operations, refused on a read-through resource whatever the binding opens.\n *\n * A bulk write against a system the platform does not own is N remote calls with no atomicity: any\n * of them can fail after the earlier ones landed, and there is no transaction to roll back into. The\n * engine opens single-row writes only, which is what an author can reason about one row at a time.\n */\nconst BULK_WRITE_OPERATIONS: ReadonlySet<unknown> = new Set<unknown>([\n  CoreResourceOperation.CREATE_MANY,\n  CoreResourceOperation.UPDATE_MANY,\n  CoreResourceOperation.DELETE_MANY,\n]);\n\n/** What the factory knows about ONE declared operation, reduced to what these rules read. */\ninterface HttpApiWriteOperationFacts {\n  readonly operationKey: string;\n  /** The core semantics of each variant: the operation itself for a core one, `resourceOperationLike` for a custom one. */\n  readonly effectiveOperations: readonly unknown[];\n  readonly variants: ReadonlyArray<{\n    readonly idempotencyKey?: ResourceOperationIdempotencyKeyRequirement;\n    readonly haveBulkOperation?: boolean;\n  }>;\n  readonly serviceRuntimeMode?: ResourceOperation_ServiceRuntimeMode;\n}\n\n/**\n * Reduce the authored operation declarations to {@link HttpApiWriteOperationFacts}.\n *\n * Enumerated by EFFECTIVE semantics, the way the pipeline's CLOSED-population rule enumerates\n * creates: a core operation is its own semantics, a custom one borrows them per variant through\n * `resourceOperationLike`, and both sources are unioned because neither sees the other's members.\n * A custom operation that borrows UPDATE is exactly how an author would write a remote \"confirm\"\n * without thinking of it as a write — so it is a write here too.\n */\nexport function collectHttpApiWriteOperationFacts(\n  coreOperations: readonly unknown[],\n  operationsConfiguration: Readonly<Record<string, unknown>> | undefined,\n): HttpApiWriteOperationFacts[] {\n  const facts = new Map<string, HttpApiWriteOperationFacts>();\n  for (const operation of coreOperations) {\n    facts.set(String(operation), { operationKey: String(operation), effectiveOperations: [operation], variants: [] });\n  }\n  for (const [operationKey, operationConfig] of Object.entries(operationsConfiguration ?? {})) {\n    const config = (operationConfig ?? {}) as {\n      variants?: Array<{ resourceOperationLike?: unknown; idempotencyKey?: ResourceOperationIdempotencyKeyRequirement; haveBulkOperation?: boolean }>;\n      serviceRuntimeMode?: ResourceOperation_ServiceRuntimeMode;\n    };\n    const variants = config.variants ?? [];\n    const isCore = coreOperations.includes(operationKey);\n    facts.set(operationKey, {\n      operationKey,\n      effectiveOperations: variants.length > 0 && !isCore\n        ? variants.map((variant) => variant.resourceOperationLike ?? operationKey)\n        : [operationKey],\n      variants,\n      serviceRuntimeMode: config.serviceRuntimeMode,\n    });\n  }\n  return [...facts.values()];\n}\n\n/**\n * The `Idempotency-Key` requirement a variant of a read-through WRITE carries — always REQUIRED.\n *\n * DERIVED rather than demanded from the author, because it has one legal value: a remote write cannot\n * be rolled back, so a retry after a lost response must replay the first outcome instead of writing a\n * second time, and only a required key makes every retry replayable. Asking an author to type the one\n * answer the mechanism already knows is a question nobody should be asked (`derive-before-you-ask`).\n * `ACCEPTED` is refused by {@link assertHttpApiWriteDeclarationCoherence}, never silently upgraded.\n *\n * The AUTHORED value comes first so the factory's forwarding line still reads\n * `idempotencyKey: resolveHttpApiWriteIdempotencyKeyRequirement(variantParams.idempotencyKey, …)`, the shape\n * `operation-variant-field-forwarding.guard.test.ts` recognises as forwarding.\n */\nexport function resolveHttpApiWriteIdempotencyKeyRequirement(\n  authored: ResourceOperationIdempotencyKeyRequirement | undefined,\n  isReadThroughWrite: boolean,\n): ResourceOperationIdempotencyKeyRequirement | undefined {\n  if (!isReadThroughWrite) return authored;\n  return ResourceOperationIdempotencyKeyRequirement.REQUIRED;\n}\n\n/** A resource operation a declared system-of-record action names as its HTTP door (`actions.<name>.operation`). */\ninterface SystemOfRecordActionDoor {\n  readonly actionName: string;\n  readonly writes: boolean;\n}\n\n/**\n * The operations the binding's declared actions name as their HTTP doors, keyed by operation.\n *\n * One operation runs one action: two actions naming the same door would make the operation's meaning depend on which\n * one its implementation happens to hand to the executor, so it is refused here rather than decided there.\n */\nfunction collectSystemOfRecordActionDoors(binding: HttpApiResourceBinding): ReadonlyMap<string, SystemOfRecordActionDoor> {\n  const doors = new Map<string, SystemOfRecordActionDoor>();\n  for (const [actionName, action] of Object.entries(binding.actions ?? {})) {\n    if (action.operation === undefined) continue;\n    const existing = doors.get(action.operation);\n    if (existing !== undefined) {\n      throw new Error(\n        `operation '${action.operation}' is named as the door of two actions, '${existing.actionName}' and '${actionName}'. `\n        + 'One operation runs one action; declare a second operation for the second action.',\n      );\n    }\n    doors.set(action.operation, { actionName, writes: action.writes });\n  }\n  return doors;\n}\n\n/**\n * Hold an action's HTTP door to the ACTION's rules instead of the row-write rules (#1678 review, F1).\n *\n * A door does not write a row of the bound entity: its implementation hands the request to the system-of-record action\n * executor, which authorizes, confines, sends and audits the action. So `writableVerbs` does not open it, and it opens\n * nothing. What it must still be is honest about the effect it has:\n *\n * - a WRITING action changes remote state that cannot be rolled back, so every variant borrows a SINGLE-ROW mutation verb\n *   (never a read: a read-shaped route is a GET and claims its repeat is harmless, and the boot validator refuses a key on\n *   one), requires the `Idempotency-Key` (the executor refuses a writing action without one, so anything less is a door\n *   that always refuses), and runs INLINE (a queued execution cannot carry the key);\n * - a NON-writing action (a vendor computation) is left to the ordinary rules for the verb it borrows.\n *\n * Never a bulk borrow: one request is one action on one target.\n */\nfunction assertSystemOfRecordActionDoorCoherence(operation: HttpApiWriteOperationFacts, door: SystemOfRecordActionDoor): void {\n  const bulk = operation.effectiveOperations.find((effective) => BULK_WRITE_OPERATIONS.has(effective));\n  if (bulk !== undefined) {\n    throw new Error(\n      `operation '${operation.operationKey}' is the door of action '${door.actionName}' and borrows a bulk verb ('${String(bulk)}'). `\n      + 'One request runs one action on one target; borrow a single-row verb.',\n    );\n  }\n  if (!door.writes) return;\n  const readBorrow = operation.effectiveOperations.find((effective) => resolveHttpApiWriteVerb(effective) === undefined);\n  if (readBorrow !== undefined) {\n    throw new Error(\n      `operation '${operation.operationKey}' is the door of action '${door.actionName}', which writes, and borrows '${String(readBorrow)}', `\n      + 'which is not a mutation. A state-changing route must not be read-shaped: it would be a GET, and a required Idempotency-Key '\n      + 'on a read is refused at boot. Borrow update (an action on one record) or create (an action that makes one) in resourceOperationLike.',\n    );\n  }\n  const unkeyed = operation.variants.find((variant) => variant.idempotencyKey !== ResourceOperationIdempotencyKeyRequirement.REQUIRED);\n  if (unkeyed !== undefined) {\n    throw new Error(\n      `operation '${operation.operationKey}' is the door of action '${door.actionName}', which writes, and does not require an `\n      + 'Idempotency-Key on every variant. The executor refuses a writing action without one, so the route would refuse every request; '\n      + `declare idempotencyKey: '${ResourceOperationIdempotencyKeyRequirement.REQUIRED}'.`,\n    );\n  }\n  if (\n    operation.serviceRuntimeMode !== undefined\n    && operation.serviceRuntimeMode !== ResourceOperation_ServiceRuntimeMode.INLINE\n  ) {\n    throw new Error(\n      `operation '${operation.operationKey}' is the door of action '${door.actionName}' and runs '${operation.serviceRuntimeMode}'. `\n      + 'A writing action runs INLINE: a queued or background execution cannot carry its Idempotency-Key. Remove serviceRuntimeMode.',\n    );\n  }\n}\n\n/**\n * Refuse every write declaration on a read-through resource that the engine could not honour.\n *\n * Throws a plain `Error` naming the rule and the fix; the factory wraps it into its own configuration\n * error with the resource identifier in front.\n *\n * The rules, and why each one exists:\n *\n *  1. **No bulk write operation**, opened or not — see {@link BULK_WRITE_OPERATIONS}. Nor a\n *     `haveBulkOperation` twin of a write, which every tier would run as N single-row writes.\n *  2. **Every write operation's verb is OPENED by the binding**, and **every opened verb has an\n *     operation**. Both directions: the first is a route that would answer a refusal forever, the\n *     second a declared door nobody can reach — and an inert declaration that looks like a control is\n *     worse than none.\n *  3. **Every write variant runs INLINE.** A queued or background execution cannot carry the\n *     `Idempotency-Key`, so a retried request could not replay; the service tier refuses a key on a\n *     non-INLINE operation already, and a key is required here.\n *  4. **No write variant declares `Idempotency-Key: ACCEPTED`.** See\n *     {@link resolveHttpApiWriteIdempotencyKeyRequirement}.\n *  5. *(Moved, #2010.)* The erasure-stance rule this list carried — a binding that WRITES personal-data fields\n *     may not declare `NO_SUBJECT_DATA` — is now `personalFieldsContradictingNoSubjectDataStance`, which the\n *     factory applies to EVERY read-through binding and every pipeline copy. Reading those fields out of a\n *     system that \"holds no subject data\" is the same contradiction as writing them into it.\n *  6. **A `VERSION_CHECKED` binding's version field is one the UPDATE can carry and the CREATE cannot** (#1724). The\n *     field must exist on the schema, be admitted to the update payload (the caller sends the version it read), and be\n *     excluded from create (a new row has no version yet, and the vendor stamps it). It must be a STRING: the check\n *     compares the caller's value byte for byte with the vendor's raw one, and a date schema would coerce it on the way\n *     in and make every update stale. Whether it maps onto the vendor's `rowVersionField` needs the facet, and is\n *     checked at boot.\n */\nexport function assertHttpApiWriteDeclarationCoherence(params: {\n  readonly binding: HttpApiResourceBinding;\n  readonly operations: readonly HttpApiWriteOperationFacts[];\n  readonly mainSchema: z.ZodTypeAny;\n}): void {\n  const { binding, operations, mainSchema } = params;\n  const opened = new Set<HttpApiWriteVerb>(binding.writableVerbs);\n  const reached = new Set<HttpApiWriteVerb>();\n  const actionDoors = collectSystemOfRecordActionDoors(binding);\n  // Checked BEFORE the operations: a door named after a missing operation usually means the author mistyped it, and the\n  // operation they meant would otherwise be refused first as an unopened row write — a message about the wrong thing.\n  const declaredOperationKeys = new Set(operations.map((operation) => operation.operationKey));\n  for (const [operationKey, door] of actionDoors) {\n    if (!declaredOperationKeys.has(operationKey)) {\n      throw new Error(\n        `actions.${door.actionName} names '${operationKey}' as its door, and this resource declares no such operation. `\n        + 'Declare the custom operation, or remove the `operation` from the action.',\n      );\n    }\n  }\n\n  for (const operation of operations) {\n    const door = actionDoors.get(operation.operationKey);\n    if (door !== undefined) {\n      assertSystemOfRecordActionDoorCoherence(operation, door);\n      continue;\n    }\n    const bulk = operation.effectiveOperations.find((effective) => BULK_WRITE_OPERATIONS.has(effective));\n    if (bulk !== undefined) {\n      throw new Error(\n        `operation '${operation.operationKey}' is a bulk write ('${String(bulk)}'), which a read-through resource never runs: `\n        + 'N remote writes have no transaction to roll back into when one of them fails after the others landed. '\n        + 'Declare the single-row create/update/delete instead.',\n      );\n    }\n    const verbs = operation.effectiveOperations\n      .map((effective) => resolveHttpApiWriteVerb(effective))\n      .filter((verb): verb is HttpApiWriteVerb => verb !== undefined);\n    if (verbs.length === 0) continue;\n\n    for (const verb of verbs) {\n      if (!opened.has(verb)) {\n        throw new Error(\n          `operation '${operation.operationKey}' writes ('${verb}'), and httpApiBinding.writableVerbs does not open '${verb}'. `\n          + `Add '${verb}' to writableVerbs to open the write toward '${binding.system}', or remove the operation.`,\n        );\n      }\n      reached.add(verb);\n    }\n    if (operation.variants.some((variant) => variant.haveBulkOperation === true)) {\n      throw new Error(\n        `operation '${operation.operationKey}' declares a bulk twin (haveBulkOperation), which a read-through resource never runs — `\n        + 'one request would become N remote writes with no atomicity. Remove haveBulkOperation.',\n      );\n    }\n    if (\n      operation.serviceRuntimeMode !== undefined\n      && operation.serviceRuntimeMode !== ResourceOperation_ServiceRuntimeMode.INLINE\n    ) {\n      throw new Error(\n        `operation '${operation.operationKey}' writes to '${binding.system}' with serviceRuntimeMode '${operation.serviceRuntimeMode}'. `\n        + 'A remote write runs INLINE: its Idempotency-Key is required, and a queued or background execution cannot carry one, '\n        + 'so a retried request could not replay its first outcome. Remove serviceRuntimeMode.',\n      );\n    }\n    const accepted = operation.variants.find((variant) => variant.idempotencyKey === ResourceOperationIdempotencyKeyRequirement.ACCEPTED);\n    if (accepted !== undefined) {\n      throw new Error(\n        `operation '${operation.operationKey}' declares idempotencyKey 'accepted'. A write to a system of record cannot be rolled back, `\n        + 'so every retry must replay the first outcome: the key is REQUIRED on every write variant, and the engine sets it for you. '\n        + 'Remove the idempotencyKey declaration.',\n      );\n    }\n  }\n\n  for (const verb of opened) {\n    if (!reached.has(verb)) {\n      throw new Error(\n        `httpApiBinding.writableVerbs opens '${verb}', and no operation of this resource performs it. An opened write nobody can `\n        + `reach is a declaration that decides nothing; declare the ${HTTP_API_WRITE_VERB_CORE_OPERATION[verb]} operation, or remove the verb.`,\n      );\n    }\n  }\n\n  if (binding.writeConcurrency?.mode === HttpApiWriteConcurrencyMode.VERSION_CHECKED && isZodObject(mainSchema)) {\n    const versionField = binding.writeConcurrency.versionField;\n    const fieldSchema = getZodObjectShape(mainSchema)[versionField] as z.ZodTypeAny | undefined;\n    if (fieldSchema === undefined) {\n      throw new Error(\n        `httpApiBinding.writeConcurrency.versionField names '${versionField}', which this resource's schema does not declare. `\n        + 'Declare the field (mapped to the vendor\\'s row version, e.g. Odoo `write_date`) so a caller can read it and send it back.',\n      );\n    }\n    const unwrapped = unwrapSchema(fieldSchema as never) as { _zod?: { def?: { type?: unknown } } };\n    if (unwrapped?._zod?.def?.type !== 'string') {\n      throw new Error(\n        `httpApiBinding.writeConcurrency.versionField '${versionField}' must be a string schema: the version is compared byte for `\n        + 'byte with what the vendor served (Odoo `write_date`, \"YYYY-MM-DD HH:MM:SS\"), and a date or number schema would re-format it.',\n      );\n    }\n    if (isExcludedFromUpdate(fieldSchema)) {\n      throw new Error(\n        `httpApiBinding.writeConcurrency.versionField '${versionField}' is excluded from UPDATE, so no caller could send the version `\n        + 'it read and every update would be refused. Remove .excludeFromUpdate() from it.',\n      );\n    }\n    if (opened.has(HttpApiWriteVerb.CREATE) && !isExcludedFromCreate(fieldSchema)) {\n      throw new Error(\n        `httpApiBinding.writeConcurrency.versionField '${versionField}' may be sent on CREATE, and a new row has no version: the `\n        + 'vendor stamps it. Declare it .excludeFromCreate().',\n      );\n    }\n  }\n\n}\n"]}

package/dist/esm/resources/utils/no-subject-data-stance-coherence.shared.utils.d.ts

@@ -0,0 +1,51 @@
+/**
+ * `NO_SUBJECT_DATA` against the personal data a resource declares it gets from the system (#2010).
+ *
+ * `HttpApiErasureStance.NO_SUBJECT_DATA` says the remote rows hold no data about a person, which is why a
+ * subject erasure reports `DECLARED_NO_SUBJECT_DATA` for them and reaches nothing. A resource that declares
+ * personal-data categories (`.dataCategories()`) on the fields it takes FROM that system says the opposite about
+ * the same rows. Both cannot be true, and the stance is the half that erasure acts on, so the contradiction is
+ * refused where it is authored, in the resource factory.
+ *
+ * Which fields come from the system depends on the lane:
+ * - a READ-THROUGH binding keeps the rows in the system of record, so every field of the resource is the remote
+ *   row's, except the tenant anchors the engine stamps (`HTTP_API_ENGINE_INJECTED_FIELDS`). Whether the resource
+ *   also WRITES does not matter: the rows hold the data either way;
+ * - a PIPELINE copies only its mapped fields. A field no mapping writes is the application's own, and a `CONSTANT`
+ *   entry reads nothing from the source. These are the same fields the privacy notice's source statement counts
+ *   (`systemOfRecordFlowsOfResource`), so the refusal and the notice cannot disagree about what came from where.
+ *
+ * Replaces the narrower write-only rule that `assertHttpApiWriteDeclarationCoherence` carried (#1679 rule 5), which
+ * asked only whether a binding WRITES personal fields. Reading them is the same contradiction, and a pipeline copy
+ * of them was not checked at all. Wonder Todos' `externalCustomers` held both declarations for twelve days.
+ *
+ * Fixing a refusal is a question of fact, never of preference:
+ * - if the fields really are about a person, the rows hold subject data: declare the stance that says so
+ *   (`EXTERNAL_ERASURE_OPERATION`, or `CONTROLLER_ACKNOWLEDGED_NON_ERASURE`);
+ * - if they are not (a company's name and its contact details are data about a legal person, outside personal
+ *   data), remove the categories.
+ *
+ * spec-cite: GDPR Recital 14, https://gdpr-info.eu/recitals/no-14/ — "This Regulation does not cover the processing
+ * of personal data which concerns legal persons and in particular undertakings established as legal persons,
+ * including the name and the form of the legal person and the contact details of the legal person."
+ */
+import type { z } from 'zod';
+import { HttpApiErasureStance } from '../../http-api-binding/http-api-erasure-stance.shared';
+/**
+ * The fields that declare personal-data categories while the binding they come from declares `NO_SUBJECT_DATA`,
+ * sorted. Empty for any other stance, and for a schema that is not an object.
+ *
+ * `sourcedFields` is the set of fields that come from the system: omit it for a read-through binding (every field
+ * but the engine-stamped anchors), pass the pipeline's mapped non-constant local fields for a copy.
+ */
+export declare function personalFieldsContradictingNoSubjectDataStance(params: {
+    readonly stance: HttpApiErasureStance;
+    readonly mainSchema: z.ZodTypeAny;
+    readonly sourcedFields?: ReadonlySet<string>;
+}): readonly string[];
+/** The refusal's text, shared by both lanes so the remedy reads the same wherever it fires. */
+export declare function describeNoSubjectDataStanceContradiction(params: {
+    readonly system: string;
+    readonly personalFields: readonly string[];
+}): string;
+//# sourceMappingURL=no-subject-data-stance-coherence.shared.utils.d.ts.map

package/dist/esm/resources/utils/no-subject-data-stance-coherence.shared.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-subject-data-stance-coherence.shared.utils.d.ts","sourceRoot":"","sources":["../../../../../src/resources/utils/no-subject-data-stance-coherence.shared.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAG7B,OAAO,EAAE,oBAAoB,EAAE,MAAM,uDAAuD,CAAC;AAG7F;;;;;;GAMG;AACH,wBAAgB,8CAA8C,CAAC,MAAM,EAAE;IACrE,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC,UAAU,CAAC;IAClC,QAAQ,CAAC,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC9C,GAAG,SAAS,MAAM,EAAE,CAOpB;AAED,+FAA+F;AAC/F,wBAAgB,wCAAwC,CAAC,MAAM,EAAE;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAAG,MAAM,CAMhJ"}

package/dist/esm/resources/utils/no-subject-data-stance-coherence.shared.utils.js

@@ -0,0 +1,28 @@
+import { getDataCategories, getZodObjectShape, isZodObject } from '@wildo-ai/zod-decorators';
+import { HttpApiErasureStance } from '../../http-api-binding/http-api-erasure-stance.shared.js';
+import { HTTP_API_ENGINE_INJECTED_FIELDS } from '../../http-api-binding/read-through-engine-anchors.shared.js';
+/**
+ * The fields that declare personal-data categories while the binding they come from declares `NO_SUBJECT_DATA`,
+ * sorted. Empty for any other stance, and for a schema that is not an object.
+ *
+ * `sourcedFields` is the set of fields that come from the system: omit it for a read-through binding (every field
+ * but the engine-stamped anchors), pass the pipeline's mapped non-constant local fields for a copy.
+ */
+export function personalFieldsContradictingNoSubjectDataStance(params) {
+    if (params.stance !== HttpApiErasureStance.NO_SUBJECT_DATA || !isZodObject(params.mainSchema))
+        return [];
+    return Object.entries(getZodObjectShape(params.mainSchema))
+        .filter(([fieldName]) => (params.sourcedFields === undefined ? !HTTP_API_ENGINE_INJECTED_FIELDS.includes(fieldName) : params.sourcedFields.has(fieldName)))
+        .filter(([, fieldSchema]) => getDataCategories(fieldSchema) !== undefined)
+        .map(([fieldName]) => fieldName)
+        .sort();
+}
+/** The refusal's text, shared by both lanes so the remedy reads the same wherever it fires. */
+export function describeNoSubjectDataStanceContradiction(params) {
+    return `the fields [${params.personalFields.join(', ')}] come from '${params.system}' and declare personal-data categories, `
+        + `while the binding's erasure stance is '${HttpApiErasureStance.NO_SUBJECT_DATA}' — that those rows hold no data about a person. `
+        + 'Both cannot be true. If the fields are about a person, declare '
+        + `'${HttpApiErasureStance.EXTERNAL_ERASURE_OPERATION}' or '${HttpApiErasureStance.CONTROLLER_ACKNOWLEDGED_NON_ERASURE}'. `
+        + 'If they are not (a company\'s name and its contact details are data about a legal person), remove their .dataCategories().';
+}
+//# sourceMappingURL=no-subject-data-stance-coherence.shared.utils.js.map

package/dist/esm/resources/utils/no-subject-data-stance-coherence.shared.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-subject-data-stance-coherence.shared.utils.js","sourceRoot":"","sources":["../../../../../src/resources/utils/no-subject-data-stance-coherence.shared.utils.ts"],"names":[],"mappings":"AAgCA,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE7F,OAAO,EAAE,oBAAoB,EAAE,MAAM,uDAAuD,CAAC;AAC7F,OAAO,EAAE,+BAA+B,EAAE,MAAM,2DAA2D,CAAC;AAE5G;;;;;;GAMG;AACH,MAAM,UAAU,8CAA8C,CAAC,MAI9D;IACC,IAAI,MAAM,CAAC,MAAM,KAAK,oBAAoB,CAAC,eAAe,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,UAAU,CAAC;QAAE,OAAO,EAAE,CAAC;IACzG,OAAO,MAAM,CAAC,OAAO,CAAC,iBAAiB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;SACxD,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,+BAA+B,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC;SAC1J,MAAM,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,EAAE,EAAE,CAAC,iBAAiB,CAAC,WAA2B,CAAC,KAAK,SAAS,CAAC;SACzF,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC;SAC/B,IAAI,EAAE,CAAC;AACZ,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,wCAAwC,CAAC,MAA+E;IACtI,OAAO,eAAe,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,gBAAgB,MAAM,CAAC,MAAM,0CAA0C;UACzH,0CAA0C,oBAAoB,CAAC,eAAe,mDAAmD;UACjI,iEAAiE;UACjE,IAAI,oBAAoB,CAAC,0BAA0B,SAAS,oBAAoB,CAAC,mCAAmC,KAAK;UACzH,4HAA4H,CAAC;AACnI,CAAC","sourcesContent":["/**\n * `NO_SUBJECT_DATA` against the personal data a resource declares it gets from the system (#2010).\n *\n * `HttpApiErasureStance.NO_SUBJECT_DATA` says the remote rows hold no data about a person, which is why a\n * subject erasure reports `DECLARED_NO_SUBJECT_DATA` for them and reaches nothing. A resource that declares\n * personal-data categories (`.dataCategories()`) on the fields it takes FROM that system says the opposite about\n * the same rows. Both cannot be true, and the stance is the half that erasure acts on, so the contradiction is\n * refused where it is authored, in the resource factory.\n *\n * Which fields come from the system depends on the lane:\n * - a READ-THROUGH binding keeps the rows in the system of record, so every field of the resource is the remote\n *   row's, except the tenant anchors the engine stamps (`HTTP_API_ENGINE_INJECTED_FIELDS`). Whether the resource\n *   also WRITES does not matter: the rows hold the data either way;\n * - a PIPELINE copies only its mapped fields. A field no mapping writes is the application's own, and a `CONSTANT`\n *   entry reads nothing from the source. These are the same fields the privacy notice's source statement counts\n *   (`systemOfRecordFlowsOfResource`), so the refusal and the notice cannot disagree about what came from where.\n *\n * Replaces the narrower write-only rule that `assertHttpApiWriteDeclarationCoherence` carried (#1679 rule 5), which\n * asked only whether a binding WRITES personal fields. Reading them is the same contradiction, and a pipeline copy\n * of them was not checked at all. Wonder Todos' `externalCustomers` held both declarations for twelve days.\n *\n * Fixing a refusal is a question of fact, never of preference:\n * - if the fields really are about a person, the rows hold subject data: declare the stance that says so\n *   (`EXTERNAL_ERASURE_OPERATION`, or `CONTROLLER_ACKNOWLEDGED_NON_ERASURE`);\n * - if they are not (a company's name and its contact details are data about a legal person, outside personal\n *   data), remove the categories.\n *\n * spec-cite: GDPR Recital 14, https://gdpr-info.eu/recitals/no-14/ — \"This Regulation does not cover the processing\n * of personal data which concerns legal persons and in particular undertakings established as legal persons,\n * including the name and the form of the legal person and the contact details of the legal person.\"\n */\nimport type { z } from 'zod';\nimport { getDataCategories, getZodObjectShape, isZodObject } from '@wildo-ai/zod-decorators';\n\nimport { HttpApiErasureStance } from '../../http-api-binding/http-api-erasure-stance.shared';\nimport { HTTP_API_ENGINE_INJECTED_FIELDS } from '../../http-api-binding/read-through-engine-anchors.shared';\n\n/**\n * The fields that declare personal-data categories while the binding they come from declares `NO_SUBJECT_DATA`,\n * sorted. Empty for any other stance, and for a schema that is not an object.\n *\n * `sourcedFields` is the set of fields that come from the system: omit it for a read-through binding (every field\n * but the engine-stamped anchors), pass the pipeline's mapped non-constant local fields for a copy.\n */\nexport function personalFieldsContradictingNoSubjectDataStance(params: {\n  readonly stance: HttpApiErasureStance;\n  readonly mainSchema: z.ZodTypeAny;\n  readonly sourcedFields?: ReadonlySet<string>;\n}): readonly string[] {\n  if (params.stance !== HttpApiErasureStance.NO_SUBJECT_DATA || !isZodObject(params.mainSchema)) return [];\n  return Object.entries(getZodObjectShape(params.mainSchema))\n    .filter(([fieldName]) => (params.sourcedFields === undefined ? !HTTP_API_ENGINE_INJECTED_FIELDS.includes(fieldName) : params.sourcedFields.has(fieldName)))\n    .filter(([, fieldSchema]) => getDataCategories(fieldSchema as z.ZodTypeAny) !== undefined)\n    .map(([fieldName]) => fieldName)\n    .sort();\n}\n\n/** The refusal's text, shared by both lanes so the remedy reads the same wherever it fires. */\nexport function describeNoSubjectDataStanceContradiction(params: { readonly system: string; readonly personalFields: readonly string[] }): string {\n  return `the fields [${params.personalFields.join(', ')}] come from '${params.system}' and declare personal-data categories, `\n    + `while the binding's erasure stance is '${HttpApiErasureStance.NO_SUBJECT_DATA}' — that those rows hold no data about a person. `\n    + 'Both cannot be true. If the fields are about a person, declare '\n    + `'${HttpApiErasureStance.EXTERNAL_ERASURE_OPERATION}' or '${HttpApiErasureStance.CONTROLLER_ACKNOWLEDGED_NON_ERASURE}'. `\n    + 'If they are not (a company\\'s name and its contact details are data about a legal person), remove their .dataCategories().';\n}\n"]}