@wildo-ai/saas-backend-lib 1.1.1 → 1.1.3

package/dist/esm/files/utils/file-uploader.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"file-uploader.utils.js","sourceRoot":"","sources":["../../../../../src/files/utils/file-uploader.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,8BAA8B,EAC9B,sBAAsB,GACvB,MAAM,uBAAuB,CAAC;AAqC/B;;;;;;GAMG;AACH,MAAM,UAAU,4BAA4B,CAC1C,gBAAuC;IAEvC,MAAM,YAAY,GAAG,gBAAgB,CAAC,YAAY,CAAC;IAEnD,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,QAAQ,gBAAgB,CAAC,aAAa,EAAE,CAAC;QACvC,KAAK,8BAA8B,CAAC,YAAY;YAC9C,OAAO,YAAY,CAAC,MAAM;gBACxB,CAAC,CAAC;oBACE,UAAU,EAAE,YAAY,CAAC,MAAM;oBAC/B,oBAAoB,EAAE,sBAAsB,CAAC,IAAI;iBAClD;gBACH,CAAC,CAAC,SAAS,CAAC;QAEhB,KAAK,8BAA8B,CAAC,iBAAiB;YACnD,OAAO,YAAY,CAAC,eAAe;gBACjC,CAAC,CAAC;oBACE,UAAU,EAAE,YAAY,CAAC,eAAe;oBACxC,oBAAoB,EAAE,sBAAsB,CAAC,cAAc;iBAC5D;gBACH,CAAC,CAAC,SAAS,CAAC;QAEhB,sFAAsF;QACtF,+FAA+F;QAC/F,+FAA+F;QAC/F,8FAA8F;QAC9F,gGAAgG;QAChG,+EAA+E;QAC/E,KAAK,8BAA8B,CAAC,oBAAoB;YACtD,OAAO,YAAY,CAAC,iBAAiB;gBACnC,CAAC,CAAC;oBACE,UAAU,EAAE,YAAY,CAAC,iBAAiB,CAAC,YAAY;oBACvD,oBAAoB,EAAE,sBAAsB,CAAC,oBAAoB;iBAClE;gBACH,CAAC,CAAC,SAAS,CAAC;QAEhB,KAAK,8BAA8B,CAAC,mBAAmB;YACrD,OAAO,YAAY,CAAC,iBAAiB;gBACnC,CAAC,CAAC;oBACE,UAAU,EAAE,YAAY,CAAC,iBAAiB,CAAC,YAAY;oBACvD,oBAAoB,EAAE,sBAAsB,CAAC,mBAAmB;iBACjE;gBACH,CAAC,CAAC,SAAS,CAAC;QAEhB;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC","sourcesContent":["import {\n  ExecutionContext_ExecutionType,\n  FileUploaderEntityType,\n} from '@wildo-ai/saas-models';\n\nimport type { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';\n\n/**\n * SINGLE SOURCE OF TRUTH — the machine file-uploader entity types are DERIVED-BY-CONTRACT from the\n * machine EXECUTION types, which are the authority.\n *\n * `FileUploaderEntityType.{ORGANIZATION,APPLICATION}_MACHINE` and\n * `ExecutionContext_ExecutionType.{ORGANIZATION,APPLICATION}_MACHINE` name the SAME machine\n * principal, so their string values MUST stay identical — the switch below projects the execution\n * type straight onto the entity type. They cannot physically share the literal: `FileUploaderEntityType`\n * lives in the upstream `zod-decorators` package (it cannot import the execution type), and TS\n * string-enum members must be literals (not computed from another enum). So instead these compile-time\n * assertions PIN the two equal. A future rename of a machine execution-type VALUE — exactly the\n * `org_api_key`→`organization_machine` recentering that silently left this uploader stranded on\n * `*_api_key` — then FAILS TO COMPILE here until the file-uploader enum is updated in lockstep.\n *\n * Only the MACHINE values are pinned. The human values legitimately DIFFER (`USER`=`user` vs\n * `USER_REQUEST`=`user_request`; `ANONYMOUS_USER`=`anonymous_user` vs `ANONYMOUS_SESSION`=\n * `anonymous_session`) — an entity/principal KIND is not the same concept as an execution KIND — so\n * pinning them would be wrong.\n */\ntype _StringEqual<A extends string, B extends string> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;\ntype _Expect<T extends true> = T;\ntype _AssertOrgMachineUploaderTracksExecutionType = _Expect<\n  _StringEqual<`${FileUploaderEntityType.ORGANIZATION_MACHINE}`, `${ExecutionContext_ExecutionType.ORGANIZATION_MACHINE}`>\n>;\ntype _AssertAppMachineUploaderTracksExecutionType = _Expect<\n  _StringEqual<`${FileUploaderEntityType.APPLICATION_MACHINE}`, `${ExecutionContext_ExecutionType.APPLICATION_MACHINE}`>\n>;\n\nexport interface FileUploaderPrincipal {\n  uploadedBy: string;\n  uploadedByEntityType: FileUploaderEntityType;\n}\n\n/**\n * Derive the concrete uploader principal from the execution context.\n *\n * File ownership is intentionally stored as a lightweight raw id + entity type\n * pair. We do not resolve related entities here; callers can hydrate richer\n * display data separately when needed.\n */\nexport function resolveFileUploaderPrincipal(\n  executionContext: ExecutionContext<any>,\n): FileUploaderPrincipal | undefined {\n  const initiatorIds = executionContext.initiatorIds;\n\n  if (!initiatorIds) {\n    return undefined;\n  }\n\n  switch (executionContext.executionType) {\n    case ExecutionContext_ExecutionType.USER_REQUEST:\n      return initiatorIds.userId\n        ? {\n            uploadedBy: initiatorIds.userId,\n            uploadedByEntityType: FileUploaderEntityType.USER,\n          }\n        : undefined;\n\n    case ExecutionContext_ExecutionType.ANONYMOUS_SESSION:\n      return initiatorIds.anonymousUserId\n        ? {\n            uploadedBy: initiatorIds.anonymousUserId,\n            uploadedByEntityType: FileUploaderEntityType.ANONYMOUS_USER,\n          }\n        : undefined;\n\n    // Machine principals (API key OR OAuth client): the uploader id is the authenticating\n    // credential (`machineCredential.credentialId`), and the entity type is the credential-NEUTRAL\n    // machine principal (`ORGANIZATION_MACHINE` / `APPLICATION_MACHINE`) — an api-key and an OAuth\n    // client both resolve to the same machine principal, so labelling the upload `*_MACHINE` (not\n    // `*_API_KEY`) is honest for both. The specific credential KIND (api-key vs OAuth client) is on\n    // `machineCredential.authMethod` if a consumer ever needs to distinguish them.\n    case ExecutionContext_ExecutionType.ORGANIZATION_MACHINE:\n      return initiatorIds.machineCredential\n        ? {\n            uploadedBy: initiatorIds.machineCredential.credentialId,\n            uploadedByEntityType: FileUploaderEntityType.ORGANIZATION_MACHINE,\n          }\n        : undefined;\n\n    case ExecutionContext_ExecutionType.APPLICATION_MACHINE:\n      return initiatorIds.machineCredential\n        ? {\n            uploadedBy: initiatorIds.machineCredential.credentialId,\n            uploadedByEntityType: FileUploaderEntityType.APPLICATION_MACHINE,\n          }\n        : undefined;\n\n    default:\n      return undefined;\n  }\n}\n"]}
+{"version":3,"file":"file-uploader.utils.js","sourceRoot":"","sources":["../../../../../src/files/utils/file-uploader.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,8BAA8B,EAC9B,sBAAsB,GACvB,MAAM,uBAAuB,CAAC;AAqC/B;;;;;;GAMG;AACH,MAAM,UAAU,4BAA4B,CAC1C,gBAAuC;IAEvC,MAAM,YAAY,GAAG,gBAAgB,CAAC,YAAY,CAAC;IAEnD,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,QAAQ,gBAAgB,CAAC,aAAa,EAAE,CAAC;QACvC,KAAK,8BAA8B,CAAC,YAAY;YAC9C,OAAO,YAAY,CAAC,MAAM;gBACxB,CAAC,CAAC;oBACE,UAAU,EAAE,YAAY,CAAC,MAAM;oBAC/B,oBAAoB,EAAE,sBAAsB,CAAC,IAAI;iBAClD;gBACH,CAAC,CAAC,SAAS,CAAC;QAEhB,KAAK,8BAA8B,CAAC,iBAAiB;YACnD,OAAO,YAAY,CAAC,eAAe;gBACjC,CAAC,CAAC;oBACE,UAAU,EAAE,YAAY,CAAC,eAAe;oBACxC,oBAAoB,EAAE,sBAAsB,CAAC,cAAc;iBAC5D;gBACH,CAAC,CAAC,SAAS,CAAC;QAEhB,sFAAsF;QACtF,+FAA+F;QAC/F,+FAA+F;QAC/F,8FAA8F;QAC9F,gGAAgG;QAChG,+EAA+E;QAC/E,KAAK,8BAA8B,CAAC,oBAAoB;YACtD,OAAO,YAAY,CAAC,iBAAiB;gBACnC,CAAC,CAAC;oBACE,UAAU,EAAE,YAAY,CAAC,iBAAiB,CAAC,YAAY;oBACvD,oBAAoB,EAAE,sBAAsB,CAAC,oBAAoB;iBAClE;gBACH,CAAC,CAAC,SAAS,CAAC;QAEhB,KAAK,8BAA8B,CAAC,mBAAmB;YACrD,OAAO,YAAY,CAAC,iBAAiB;gBACnC,CAAC,CAAC;oBACE,UAAU,EAAE,YAAY,CAAC,iBAAiB,CAAC,YAAY;oBACvD,oBAAoB,EAAE,sBAAsB,CAAC,mBAAmB;iBACjE;gBACH,CAAC,CAAC,SAAS,CAAC;QAEhB,kGAAkG;QAClG,sGAAsG;QACtG,iGAAiG;QACjG,iGAAiG;QACjG,wDAAwD;QACxD,KAAK,8BAA8B,CAAC,gBAAgB;YAClD,OAAO,YAAY,CAAC,MAAM;gBACxB,CAAC,CAAC;oBACE,UAAU,EAAE,YAAY,CAAC,MAAM;oBAC/B,oBAAoB,EAAE,sBAAsB,CAAC,IAAI;iBAClD;gBACH,CAAC,CAAC,SAAS,CAAC;QAEhB;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC","sourcesContent":["import {\n  ExecutionContext_ExecutionType,\n  FileUploaderEntityType,\n} from '@wildo-ai/saas-models';\n\nimport type { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';\n\n/**\n * SINGLE SOURCE OF TRUTH — the machine file-uploader entity types are DERIVED-BY-CONTRACT from the\n * machine EXECUTION types, which are the authority.\n *\n * `FileUploaderEntityType.{ORGANIZATION,APPLICATION}_MACHINE` and\n * `ExecutionContext_ExecutionType.{ORGANIZATION,APPLICATION}_MACHINE` name the SAME machine\n * principal, so their string values MUST stay identical — the switch below projects the execution\n * type straight onto the entity type. They cannot physically share the literal: `FileUploaderEntityType`\n * lives in the upstream `zod-decorators` package (it cannot import the execution type), and TS\n * string-enum members must be literals (not computed from another enum). So instead these compile-time\n * assertions PIN the two equal. A future rename of a machine execution-type VALUE — exactly the\n * `org_api_key`→`organization_machine` recentering that silently left this uploader stranded on\n * `*_api_key` — then FAILS TO COMPILE here until the file-uploader enum is updated in lockstep.\n *\n * Only the MACHINE values are pinned. The human values legitimately DIFFER (`USER`=`user` vs\n * `USER_REQUEST`=`user_request`; `ANONYMOUS_USER`=`anonymous_user` vs `ANONYMOUS_SESSION`=\n * `anonymous_session`) — an entity/principal KIND is not the same concept as an execution KIND — so\n * pinning them would be wrong.\n */\ntype _StringEqual<A extends string, B extends string> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;\ntype _Expect<T extends true> = T;\ntype _AssertOrgMachineUploaderTracksExecutionType = _Expect<\n  _StringEqual<`${FileUploaderEntityType.ORGANIZATION_MACHINE}`, `${ExecutionContext_ExecutionType.ORGANIZATION_MACHINE}`>\n>;\ntype _AssertAppMachineUploaderTracksExecutionType = _Expect<\n  _StringEqual<`${FileUploaderEntityType.APPLICATION_MACHINE}`, `${ExecutionContext_ExecutionType.APPLICATION_MACHINE}`>\n>;\n\nexport interface FileUploaderPrincipal {\n  uploadedBy: string;\n  uploadedByEntityType: FileUploaderEntityType;\n}\n\n/**\n * Derive the concrete uploader principal from the execution context.\n *\n * File ownership is intentionally stored as a lightweight raw id + entity type\n * pair. We do not resolve related entities here; callers can hydrate richer\n * display data separately when needed.\n */\nexport function resolveFileUploaderPrincipal(\n  executionContext: ExecutionContext<any>,\n): FileUploaderPrincipal | undefined {\n  const initiatorIds = executionContext.initiatorIds;\n\n  if (!initiatorIds) {\n    return undefined;\n  }\n\n  switch (executionContext.executionType) {\n    case ExecutionContext_ExecutionType.USER_REQUEST:\n      return initiatorIds.userId\n        ? {\n            uploadedBy: initiatorIds.userId,\n            uploadedByEntityType: FileUploaderEntityType.USER,\n          }\n        : undefined;\n\n    case ExecutionContext_ExecutionType.ANONYMOUS_SESSION:\n      return initiatorIds.anonymousUserId\n        ? {\n            uploadedBy: initiatorIds.anonymousUserId,\n            uploadedByEntityType: FileUploaderEntityType.ANONYMOUS_USER,\n          }\n        : undefined;\n\n    // Machine principals (API key OR OAuth client): the uploader id is the authenticating\n    // credential (`machineCredential.credentialId`), and the entity type is the credential-NEUTRAL\n    // machine principal (`ORGANIZATION_MACHINE` / `APPLICATION_MACHINE`) — an api-key and an OAuth\n    // client both resolve to the same machine principal, so labelling the upload `*_MACHINE` (not\n    // `*_API_KEY`) is honest for both. The specific credential KIND (api-key vs OAuth client) is on\n    // `machineCredential.authMethod` if a consumer ever needs to distinguish them.\n    case ExecutionContext_ExecutionType.ORGANIZATION_MACHINE:\n      return initiatorIds.machineCredential\n        ? {\n            uploadedBy: initiatorIds.machineCredential.credentialId,\n            uploadedByEntityType: FileUploaderEntityType.ORGANIZATION_MACHINE,\n          }\n        : undefined;\n\n    case ExecutionContext_ExecutionType.APPLICATION_MACHINE:\n      return initiatorIds.machineCredential\n        ? {\n            uploadedBy: initiatorIds.machineCredential.credentialId,\n            uploadedByEntityType: FileUploaderEntityType.APPLICATION_MACHINE,\n          }\n        : undefined;\n\n    // A consumable-token context carries the userId the token was MINTED for (set by the token bridge\n    // in `createExecutionContextFromRequest`). For a user-minted file upload grant that IS the uploader —\n    // the person who delegated the upload, not the bearer who performed it. A token with no `userId`\n    // (a machine-minted grant) resolves to nothing here; the upload handler then attributes the file\n    // from the grant's own `minter` record. Issue #312, D7.\n    case ExecutionContext_ExecutionType.CONSUMABLE_TOKEN:\n      return initiatorIds.userId\n        ? {\n            uploadedBy: initiatorIds.userId,\n            uploadedByEntityType: FileUploaderEntityType.USER,\n          }\n        : undefined;\n\n    default:\n      return undefined;\n  }\n}\n"]}

package/dist/esm/files/utils/office-document-text-extraction.backend.utils.d.ts

@@ -0,0 +1,86 @@
+/**
+ * LOCAL text extraction for the two ZIP+XML document families — OOXML (`.docx` / `.xlsx` /
+ * `.pptx`) and OpenDocument (`.odt` / `.ods` / `.odp`).
+ *
+ * ## Why these six, and not the other three (#434, decided 2026-09-09)
+ *
+ * The nine document types the `Documents` media group admits are THREE technical problems, and
+ * treating them as one is what produced the original "there is no local library for Office" claim:
+ *
+ * | family                | types                     | container            |
+ * |-----------------------|---------------------------|----------------------|
+ * | OOXML                 | `.docx` `.xlsx` `.pptx`   | ZIP + XML            |
+ * | OpenDocument          | `.odt` `.ods` `.odp`      | ZIP + XML — the SAME |
+ * | legacy binary Office  | `.doc` `.xls` `.ppt`      | OLE2 compound file   |
+ *
+ * The first two are one technique, which is why one module serves both. The third is a
+ * pre-2007 binary format whose reader is a project rather than a dependency, and it stays
+ * PROVIDER-ONLY — along with the genuinely provider-shaped case a local parser can never serve: a
+ * scanned document whose text exists only inside images and needs real OCR.
+ *
+ * ## Why a local library at all, when a provider can already do it
+ *
+ * Because without one, a deployment with no `AI_DOCUMENT_EXTRACTION` provider accepted a `.docx`
+ * upload, stored it, and produced NO corpus from it — logged at DEBUG and never an error. The media
+ * group advertised nine types the deployment could not read, and said nothing.
+ *
+ * A local parser also keeps the document IN the deployment. Routing every `.docx` to a vendor for
+ * text that is already sitting in plain XML inside the file is egress an operator has to declare
+ * and a per-page cost, for a document that needs neither.
+ *
+ * The provider is NOT displaced: `FileTextExtractionBackendService` keeps its existing ladder, and
+ * this module is the same rung `pdfjs-dist` occupies for PDF — the local library a provider falls
+ * back to, and the only path when no provider is configured.
+ *
+ * ## What is extracted, and what is deliberately dropped
+ *
+ * Text, in document order, with a line break at each block boundary. Nothing else: no styling, no
+ * cell coordinates, no slide numbers, no revision metadata. The consumer is a RAG corpus, which
+ * embeds prose — a spreadsheet's cell addresses would be embedded noise, and a document's fonts
+ * carry no meaning to retrieve.
+ */
+import { Buffer } from 'node:buffer';
+/** OOXML — the Office 2007+ ZIP container. */
+export declare const OOXML_DOCUMENT_MIMES: ReadonlySet<string>;
+/** OpenDocument — the same ZIP+XML technique, one `content.xml` per document. */
+export declare const OPEN_DOCUMENT_MIMES: ReadonlySet<string>;
+/** Every type this module can read without any provider. */
+export declare const LOCALLY_EXTRACTABLE_DOCUMENT_MIMES: ReadonlySet<string>;
+/**
+ * Pre-2007 binary Office. NOT served here, and the omission is a decision rather than a gap:
+ * these are OLE2 compound files, a different container from a different era, and a reader for them
+ * is a project. They remain extractable only through a configured provider.
+ */
+export declare const LEGACY_BINARY_OFFICE_MIMES: ReadonlySet<string>;
+/** Why a local extraction could not be produced. The service maps these onto its own failure classes. */
+export declare enum OfficeDocumentExtractionFailure {
+    /** The bytes are not a readable ZIP container — a truncated upload, or a file whose extension lies. */
+    UNREADABLE_CONTAINER = "UNREADABLE_CONTAINER",
+    /** A readable archive that declares more uncompressed bytes than {@link MAX_TOTAL_UNCOMPRESSED_BYTES}. */
+    ARCHIVE_TOO_LARGE = "ARCHIVE_TOO_LARGE",
+    /**
+     * A readable archive with none of the XML parts this format keeps its text in. Almost always a
+     * mislabelled file — a `.zip` renamed, or a `.docx` MIME on something else entirely.
+     */
+    NO_TEXT_PARTS = "NO_TEXT_PARTS"
+}
+export declare class OfficeDocumentExtractionError extends Error {
+    readonly failure: OfficeDocumentExtractionFailure;
+    readonly cause?: unknown;
+    constructor(failure: OfficeDocumentExtractionFailure, message: string, cause?: unknown);
+}
+export interface OfficeDocumentExtraction {
+    readonly text: string;
+    /** How many XML parts contributed — slides, sheets, or the single `content.xml`. Reported as `pageCount`. */
+    readonly partCount: number;
+}
+/**
+ * Extract the text of one OOXML or OpenDocument file.
+ *
+ * Throws {@link OfficeDocumentExtractionError} rather than returning an empty string for a document
+ * it could not read: an empty corpus and an unreadable file are different facts, and the caller
+ * classifies them differently — one is "this document has no text", the other is "these bytes are
+ * not what they claim to be".
+ */
+export declare function extractOfficeDocumentText(document: Buffer, mimeType: string): Promise<OfficeDocumentExtraction>;
+//# sourceMappingURL=office-document-text-extraction.backend.utils.d.ts.map

package/dist/esm/files/utils/office-document-text-extraction.backend.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"office-document-text-extraction.backend.utils.d.ts","sourceRoot":"","sources":["../../../../../src/files/utils/office-document-text-extraction.backend.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,8CAA8C;AAC9C,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,MAAM,CAInD,CAAC;AAEH,iFAAiF;AACjF,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAIlD,CAAC;AAEH,4DAA4D;AAC5D,eAAO,MAAM,kCAAkC,EAAE,WAAW,CAAC,MAAM,CAGjE,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,EAAE,WAAW,CAAC,MAAM,CAIzD,CAAC;AAuCH,yGAAyG;AACzG,oBAAY,+BAA+B;IACzC,uGAAuG;IACvG,oBAAoB,yBAAyB;IAC7C,0GAA0G;IAC1G,iBAAiB,sBAAsB;IACvC;;;OAGG;IACH,aAAa,kBAAkB;CAChC;AAED,qBAAa,6BAA8B,SAAQ,KAAK;IAC1C,QAAQ,CAAC,OAAO,EAAE,+BAA+B;IAAmB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO;gBAAnF,OAAO,EAAE,+BAA+B,EAAE,OAAO,EAAE,MAAM,EAAW,KAAK,CAAC,EAAE,OAAO;CAIzG;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6GAA6G;IAC7G,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAuGD;;;;;;;GAOG;AACH,wBAAsB,yBAAyB,CAC7C,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,wBAAwB,CAAC,CA8FnC"}

package/dist/esm/files/utils/office-document-text-extraction.backend.utils.js

@@ -0,0 +1,288 @@
+/**
+ * LOCAL text extraction for the two ZIP+XML document families — OOXML (`.docx` / `.xlsx` /
+ * `.pptx`) and OpenDocument (`.odt` / `.ods` / `.odp`).
+ *
+ * ## Why these six, and not the other three (#434, decided 2026-09-09)
+ *
+ * The nine document types the `Documents` media group admits are THREE technical problems, and
+ * treating them as one is what produced the original "there is no local library for Office" claim:
+ *
+ * | family                | types                     | container            |
+ * |-----------------------|---------------------------|----------------------|
+ * | OOXML                 | `.docx` `.xlsx` `.pptx`   | ZIP + XML            |
+ * | OpenDocument          | `.odt` `.ods` `.odp`      | ZIP + XML — the SAME |
+ * | legacy binary Office  | `.doc` `.xls` `.ppt`      | OLE2 compound file   |
+ *
+ * The first two are one technique, which is why one module serves both. The third is a
+ * pre-2007 binary format whose reader is a project rather than a dependency, and it stays
+ * PROVIDER-ONLY — along with the genuinely provider-shaped case a local parser can never serve: a
+ * scanned document whose text exists only inside images and needs real OCR.
+ *
+ * ## Why a local library at all, when a provider can already do it
+ *
+ * Because without one, a deployment with no `AI_DOCUMENT_EXTRACTION` provider accepted a `.docx`
+ * upload, stored it, and produced NO corpus from it — logged at DEBUG and never an error. The media
+ * group advertised nine types the deployment could not read, and said nothing.
+ *
+ * A local parser also keeps the document IN the deployment. Routing every `.docx` to a vendor for
+ * text that is already sitting in plain XML inside the file is egress an operator has to declare
+ * and a per-page cost, for a document that needs neither.
+ *
+ * The provider is NOT displaced: `FileTextExtractionBackendService` keeps its existing ladder, and
+ * this module is the same rung `pdfjs-dist` occupies for PDF — the local library a provider falls
+ * back to, and the only path when no provider is configured.
+ *
+ * ## What is extracted, and what is deliberately dropped
+ *
+ * Text, in document order, with a line break at each block boundary. Nothing else: no styling, no
+ * cell coordinates, no slide numbers, no revision metadata. The consumer is a RAG corpus, which
+ * embeds prose — a spreadsheet's cell addresses would be embedded noise, and a document's fonts
+ * carry no meaning to retrieve.
+ */
+/** OOXML — the Office 2007+ ZIP container. */
+export const OOXML_DOCUMENT_MIMES = new Set([
+    'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+]);
+/** OpenDocument — the same ZIP+XML technique, one `content.xml` per document. */
+export const OPEN_DOCUMENT_MIMES = new Set([
+    'application/vnd.oasis.opendocument.text',
+    'application/vnd.oasis.opendocument.spreadsheet',
+    'application/vnd.oasis.opendocument.presentation',
+]);
+/** Every type this module can read without any provider. */
+export const LOCALLY_EXTRACTABLE_DOCUMENT_MIMES = new Set([
+    ...OOXML_DOCUMENT_MIMES,
+    ...OPEN_DOCUMENT_MIMES,
+]);
+/**
+ * Pre-2007 binary Office. NOT served here, and the omission is a decision rather than a gap:
+ * these are OLE2 compound files, a different container from a different era, and a reader for them
+ * is a project. They remain extractable only through a configured provider.
+ */
+export const LEGACY_BINARY_OFFICE_MIMES = new Set([
+    'application/msword',
+    'application/vnd.ms-excel',
+    'application/vnd.ms-powerpoint',
+]);
+/**
+ * Largest total of UNCOMPRESSED bytes this module will decompress out of one archive.
+ *
+ * A ZIP bomb is a real upload, not a hypothetical: a few hundred kilobytes can declare gigabytes,
+ * and `unzipSync` would allocate every one of them before anything else could refuse. The cap is
+ * applied from the central directory's declared sizes — BEFORE decompression — which is the only
+ * point at which refusing is still cheap.
+ *
+ * 64 MiB because it is far above any genuine document's XML (a 500-page manuscript's
+ * `document.xml` is single-digit megabytes) and far below a size that could exhaust a backend
+ * serving many uploads at once.
+ */
+const MAX_TOTAL_UNCOMPRESSED_BYTES = 64 * 1024 * 1024;
+/** Bound on entries INSPECTED, so a pathological central directory cannot make the filter itself the attack. */
+const MAX_ARCHIVE_ENTRIES = 4096;
+/**
+ * Element names after which the walker emits a line break.
+ *
+ * ONE union across both families rather than a per-format table, because the walker never needs to
+ * know which format it is reading — it needs to know which elements END A BLOCK, and the six
+ * formats disagree only about spelling:
+ *
+ * - `w:p` / `w:tr`   — WordprocessingML paragraph and table row
+ * - `a:p`            — DrawingML paragraph (every `.pptx` text frame)
+ * - `text:p` / `text:h` / `text:table-row` — OpenDocument paragraph, heading, table row
+ * - `si` / `c`       — SpreadsheetML shared-string item and cell: one line per value, which is what
+ *                      makes a sheet read as a list of values rather than one unbroken string
+ */
+const BLOCK_ELEMENT_NAMES = new Set([
+    'w:p', 'w:tr',
+    'a:p',
+    'text:p', 'text:h', 'text:table-row',
+    'si', 'c',
+]);
+/** Why a local extraction could not be produced. The service maps these onto its own failure classes. */
+export var OfficeDocumentExtractionFailure;
+(function (OfficeDocumentExtractionFailure) {
+    /** The bytes are not a readable ZIP container — a truncated upload, or a file whose extension lies. */
+    OfficeDocumentExtractionFailure["UNREADABLE_CONTAINER"] = "UNREADABLE_CONTAINER";
+    /** A readable archive that declares more uncompressed bytes than {@link MAX_TOTAL_UNCOMPRESSED_BYTES}. */
+    OfficeDocumentExtractionFailure["ARCHIVE_TOO_LARGE"] = "ARCHIVE_TOO_LARGE";
+    /**
+     * A readable archive with none of the XML parts this format keeps its text in. Almost always a
+     * mislabelled file — a `.zip` renamed, or a `.docx` MIME on something else entirely.
+     */
+    OfficeDocumentExtractionFailure["NO_TEXT_PARTS"] = "NO_TEXT_PARTS";
+})(OfficeDocumentExtractionFailure || (OfficeDocumentExtractionFailure = {}));
+export class OfficeDocumentExtractionError extends Error {
+    failure;
+    cause;
+    constructor(failure, message, cause) {
+        super(message);
+        this.failure = failure;
+        this.cause = cause;
+        this.name = 'OfficeDocumentExtractionError';
+    }
+}
+function selectorFor(mimeType) {
+    switch (mimeType) {
+        case 'application/vnd.openxmlformats-officedocument.wordprocessingml.document':
+            /*
+             * Body first, then notes. Headers and footers are deliberately EXCLUDED: they repeat on every
+             * page, so including them multiplies one boilerplate line by the page count and hands the
+             * corpus a phrase that retrieves against everything.
+             */
+            return {
+                matches: (name) => name === 'word/document.xml' || name === 'word/footnotes.xml' || name === 'word/endnotes.xml',
+                rank: (name) => (name === 'word/document.xml' ? 0 : 1),
+            };
+        case 'application/vnd.openxmlformats-officedocument.presentationml.presentation':
+            /*
+             * Slides, then speaker notes. Notes are included because they routinely carry the substance a
+             * slide only gestures at — the sentence a presenter says out loud is often the one worth
+             * retrieving.
+             */
+            return {
+                matches: (name) => /^ppt\/(slides\/slide|notesSlides\/notesSlide)\d+\.xml$/u.test(name),
+                rank: (name) => (name.startsWith('ppt/slides/') ? 0 : 1),
+            };
+        case 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet':
+            /*
+             * Shared strings FIRST, then the sheets. In SpreadsheetML most cell text is de-duplicated into
+             * `sharedStrings.xml` and referenced by index from the sheet, so the shared table IS the
+             * document's prose; the sheets add inline strings and the numbers' surrounding structure.
+             *
+             * The index indirection is deliberately NOT resolved. Reading both parts yields every string
+             * once, which is what a corpus needs; rebuilding each cell's value in place would reproduce
+             * the spreadsheet, not its text, and would repeat every shared string once per use.
+             */
+            return {
+                matches: (name) => name === 'xl/sharedStrings.xml' || /^xl\/worksheets\/sheet\d+\.xml$/u.test(name),
+                rank: (name) => (name === 'xl/sharedStrings.xml' ? 0 : 1),
+            };
+        default:
+            // Every OpenDocument format keeps its whole body in one `content.xml` — which is why the
+            // three of them need no branch between them.
+            return { matches: (name) => name === 'content.xml', rank: () => 0 };
+    }
+}
+/** Numeric-aware comparison, so `slide2.xml` precedes `slide10.xml` rather than following it. */
+function compareNumericallyWithinRank(left, right) {
+    return left.localeCompare(right, 'en', { numeric: true });
+}
+/**
+ * Walk a `preserveOrder` parse tree, appending every text node and breaking lines at block
+ * boundaries.
+ *
+ * `preserveOrder` is what makes this correct rather than approximate: the parser emits an ARRAY of
+ * single-key objects in document order, so text that is interleaved between child elements — which
+ * is every run in a Word paragraph — arrives in the order a reader would meet it. The default
+ * (unordered) shape collapses repeated siblings into arrays keyed by tag name and loses the
+ * interleaving entirely, which silently reorders every sentence containing formatting.
+ */
+function collectText(node, out) {
+    if (Array.isArray(node)) {
+        for (const child of node) {
+            collectText(child, out);
+        }
+        return;
+    }
+    if (typeof node !== 'object' || node === null) {
+        return;
+    }
+    for (const [name, value] of Object.entries(node)) {
+        if (name === '#text') {
+            // `trimValues: false` keeps the intra-run spacing that separates words across formatting
+            // boundaries — trimming here is what turns "the <b>quick</b> fox" into "thequickfox".
+            if (typeof value === 'string' && value.length > 0) {
+                out.push(value);
+            }
+            continue;
+        }
+        collectText(value, out);
+        if (BLOCK_ELEMENT_NAMES.has(name)) {
+            out.push('\n');
+        }
+    }
+}
+/**
+ * Extract the text of one OOXML or OpenDocument file.
+ *
+ * Throws {@link OfficeDocumentExtractionError} rather than returning an empty string for a document
+ * it could not read: an empty corpus and an unreadable file are different facts, and the caller
+ * classifies them differently — one is "this document has no text", the other is "these bytes are
+ * not what they claim to be".
+ */
+export async function extractOfficeDocumentText(document, mimeType) {
+    // Dynamic, matching how `pdfjs-dist` is loaded for PDF: both are installed dependencies that only
+    // a file-extraction call needs, and neither belongs on the boot path of every backend process.
+    const [{ unzipSync }, { XMLParser }] = await Promise.all([
+        import('fflate'),
+        import('fast-xml-parser'),
+    ]);
+    const selector = selectorFor(mimeType);
+    let declaredBytes = 0;
+    let inspectedEntries = 0;
+    let entries;
+    try {
+        entries = unzipSync(new Uint8Array(document), {
+            filter: (file) => {
+                inspectedEntries += 1;
+                if (inspectedEntries > MAX_ARCHIVE_ENTRIES) {
+                    throw new OfficeDocumentExtractionError(OfficeDocumentExtractionFailure.ARCHIVE_TOO_LARGE, `Archive declares more than ${MAX_ARCHIVE_ENTRIES} entries`);
+                }
+                if (!selector.matches(file.name)) {
+                    return false;
+                }
+                /*
+                 * `originalSize` comes from the central directory, so this refuses BEFORE the bytes are
+                 * allocated. Checking after decompression would be checking after the damage.
+                 */
+                declaredBytes += file.originalSize;
+                if (declaredBytes > MAX_TOTAL_UNCOMPRESSED_BYTES) {
+                    throw new OfficeDocumentExtractionError(OfficeDocumentExtractionFailure.ARCHIVE_TOO_LARGE, `Archive declares ${declaredBytes} uncompressed bytes across its text parts, above the ${MAX_TOTAL_UNCOMPRESSED_BYTES} limit`);
+                }
+                return true;
+            },
+        });
+    }
+    catch (cause) {
+        if (cause instanceof OfficeDocumentExtractionError) {
+            throw cause;
+        }
+        throw new OfficeDocumentExtractionError(OfficeDocumentExtractionFailure.UNREADABLE_CONTAINER, 'The document is not a readable ZIP container', cause);
+    }
+    const partNames = Object.keys(entries).sort((left, right) => selector.rank(left) - selector.rank(right) || compareNumericallyWithinRank(left, right));
+    if (partNames.length === 0) {
+        throw new OfficeDocumentExtractionError(OfficeDocumentExtractionFailure.NO_TEXT_PARTS, `The archive holds none of the XML parts a ${mimeType} keeps its text in`);
+    }
+    const parser = new XMLParser({
+        preserveOrder: true,
+        // Attributes carry no prose. Ignoring them also keeps the walker from having to skip the
+        // parser's `:@` attribute nodes, which would otherwise be indistinguishable from elements.
+        ignoreAttributes: true,
+        trimValues: false,
+        // XML's five predefined entities and numeric references are what a `&amp;` in a document body
+        // arrives as; without this the corpus carries the escape rather than the character.
+        processEntities: true,
+    });
+    const decoder = new TextDecoder('utf-8');
+    const pieces = [];
+    for (const partName of partNames) {
+        collectText(parser.parse(decoder.decode(entries[partName])), pieces);
+        // A part boundary is a block boundary: the last paragraph of one slide must not run into the
+        // first of the next.
+        pieces.push('\n');
+    }
+    /*
+     * Collapse the runs of blank lines the block breaks produce — a Word paragraph inside a table row
+     * closes both, and an empty paragraph closes one around nothing. Left alone, a document with any
+     * table structure arrives as more newlines than text, and the chunker then splits on them.
+     */
+    const text = pieces
+        .join('')
+        .replace(/[ \t]+\n/gu, '\n')
+        .replace(/\n{3,}/gu, '\n\n')
+        .trim();
+    return { text, partCount: partNames.length };
+}
+//# sourceMappingURL=office-document-text-extraction.backend.utils.js.map

package/dist/esm/files/utils/office-document-text-extraction.backend.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"office-document-text-extraction.backend.utils.js","sourceRoot":"","sources":["../../../../../src/files/utils/office-document-text-extraction.backend.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * LOCAL text extraction for the two ZIP+XML document families — OOXML (`.docx` / `.xlsx` /\n * `.pptx`) and OpenDocument (`.odt` / `.ods` / `.odp`).\n *\n * ## Why these six, and not the other three (#434, decided 2026-09-09)\n *\n * The nine document types the `Documents` media group admits are THREE technical problems, and\n * treating them as one is what produced the original \"there is no local library for Office\" claim:\n *\n * | family                | types                     | container            |\n * |-----------------------|---------------------------|----------------------|\n * | OOXML                 | `.docx` `.xlsx` `.pptx`   | ZIP + XML            |\n * | OpenDocument          | `.odt` `.ods` `.odp`      | ZIP + XML — the SAME |\n * | legacy binary Office  | `.doc` `.xls` `.ppt`      | OLE2 compound file   |\n *\n * The first two are one technique, which is why one module serves both. The third is a\n * pre-2007 binary format whose reader is a project rather than a dependency, and it stays\n * PROVIDER-ONLY — along with the genuinely provider-shaped case a local parser can never serve: a\n * scanned document whose text exists only inside images and needs real OCR.\n *\n * ## Why a local library at all, when a provider can already do it\n *\n * Because without one, a deployment with no `AI_DOCUMENT_EXTRACTION` provider accepted a `.docx`\n * upload, stored it, and produced NO corpus from it — logged at DEBUG and never an error. The media\n * group advertised nine types the deployment could not read, and said nothing.\n *\n * A local parser also keeps the document IN the deployment. Routing every `.docx` to a vendor for\n * text that is already sitting in plain XML inside the file is egress an operator has to declare\n * and a per-page cost, for a document that needs neither.\n *\n * The provider is NOT displaced: `FileTextExtractionBackendService` keeps its existing ladder, and\n * this module is the same rung `pdfjs-dist` occupies for PDF — the local library a provider falls\n * back to, and the only path when no provider is configured.\n *\n * ## What is extracted, and what is deliberately dropped\n *\n * Text, in document order, with a line break at each block boundary. Nothing else: no styling, no\n * cell coordinates, no slide numbers, no revision metadata. The consumer is a RAG corpus, which\n * embeds prose — a spreadsheet's cell addresses would be embedded noise, and a document's fonts\n * carry no meaning to retrieve.\n */\n\nimport { Buffer } from 'node:buffer';\n\n/** OOXML — the Office 2007+ ZIP container. */\nexport const OOXML_DOCUMENT_MIMES: ReadonlySet<string> = new Set([\n  'application/vnd.openxmlformats-officedocument.wordprocessingml.document',\n  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',\n  'application/vnd.openxmlformats-officedocument.presentationml.presentation',\n]);\n\n/** OpenDocument — the same ZIP+XML technique, one `content.xml` per document. */\nexport const OPEN_DOCUMENT_MIMES: ReadonlySet<string> = new Set([\n  'application/vnd.oasis.opendocument.text',\n  'application/vnd.oasis.opendocument.spreadsheet',\n  'application/vnd.oasis.opendocument.presentation',\n]);\n\n/** Every type this module can read without any provider. */\nexport const LOCALLY_EXTRACTABLE_DOCUMENT_MIMES: ReadonlySet<string> = new Set([\n  ...OOXML_DOCUMENT_MIMES,\n  ...OPEN_DOCUMENT_MIMES,\n]);\n\n/**\n * Pre-2007 binary Office. NOT served here, and the omission is a decision rather than a gap:\n * these are OLE2 compound files, a different container from a different era, and a reader for them\n * is a project. They remain extractable only through a configured provider.\n */\nexport const LEGACY_BINARY_OFFICE_MIMES: ReadonlySet<string> = new Set([\n  'application/msword',\n  'application/vnd.ms-excel',\n  'application/vnd.ms-powerpoint',\n]);\n\n/**\n * Largest total of UNCOMPRESSED bytes this module will decompress out of one archive.\n *\n * A ZIP bomb is a real upload, not a hypothetical: a few hundred kilobytes can declare gigabytes,\n * and `unzipSync` would allocate every one of them before anything else could refuse. The cap is\n * applied from the central directory's declared sizes — BEFORE decompression — which is the only\n * point at which refusing is still cheap.\n *\n * 64 MiB because it is far above any genuine document's XML (a 500-page manuscript's\n * `document.xml` is single-digit megabytes) and far below a size that could exhaust a backend\n * serving many uploads at once.\n */\nconst MAX_TOTAL_UNCOMPRESSED_BYTES = 64 * 1024 * 1024;\n\n/** Bound on entries INSPECTED, so a pathological central directory cannot make the filter itself the attack. */\nconst MAX_ARCHIVE_ENTRIES = 4096;\n\n/**\n * Element names after which the walker emits a line break.\n *\n * ONE union across both families rather than a per-format table, because the walker never needs to\n * know which format it is reading — it needs to know which elements END A BLOCK, and the six\n * formats disagree only about spelling:\n *\n * - `w:p` / `w:tr`   — WordprocessingML paragraph and table row\n * - `a:p`            — DrawingML paragraph (every `.pptx` text frame)\n * - `text:p` / `text:h` / `text:table-row` — OpenDocument paragraph, heading, table row\n * - `si` / `c`       — SpreadsheetML shared-string item and cell: one line per value, which is what\n *                      makes a sheet read as a list of values rather than one unbroken string\n */\nconst BLOCK_ELEMENT_NAMES: ReadonlySet<string> = new Set([\n  'w:p', 'w:tr',\n  'a:p',\n  'text:p', 'text:h', 'text:table-row',\n  'si', 'c',\n]);\n\n/** Why a local extraction could not be produced. The service maps these onto its own failure classes. */\nexport enum OfficeDocumentExtractionFailure {\n  /** The bytes are not a readable ZIP container — a truncated upload, or a file whose extension lies. */\n  UNREADABLE_CONTAINER = 'UNREADABLE_CONTAINER',\n  /** A readable archive that declares more uncompressed bytes than {@link MAX_TOTAL_UNCOMPRESSED_BYTES}. */\n  ARCHIVE_TOO_LARGE = 'ARCHIVE_TOO_LARGE',\n  /**\n   * A readable archive with none of the XML parts this format keeps its text in. Almost always a\n   * mislabelled file — a `.zip` renamed, or a `.docx` MIME on something else entirely.\n   */\n  NO_TEXT_PARTS = 'NO_TEXT_PARTS',\n}\n\nexport class OfficeDocumentExtractionError extends Error {\n  constructor(readonly failure: OfficeDocumentExtractionFailure, message: string, readonly cause?: unknown) {\n    super(message);\n    this.name = 'OfficeDocumentExtractionError';\n  }\n}\n\nexport interface OfficeDocumentExtraction {\n  readonly text: string;\n  /** How many XML parts contributed — slides, sheets, or the single `content.xml`. Reported as `pageCount`. */\n  readonly partCount: number;\n}\n\n/**\n * Which XML parts inside the archive hold this format's text, and in what order.\n *\n * Returned as a MATCHER plus a sort key rather than a fixed list, because two of the six formats\n * hold their text in an unbounded numbered series (`slide1.xml` … `slideN.xml`) whose members are\n * only known once the archive is open.\n */\ninterface TextPartSelector {\n  readonly matches: (entryName: string) => boolean;\n  /** Ordering rank. Lower sorts first; ties fall back to a NUMERIC name comparison. */\n  readonly rank: (entryName: string) => number;\n}\n\nfunction selectorFor(mimeType: string): TextPartSelector {\n  switch (mimeType) {\n    case 'application/vnd.openxmlformats-officedocument.wordprocessingml.document':\n      /*\n       * Body first, then notes. Headers and footers are deliberately EXCLUDED: they repeat on every\n       * page, so including them multiplies one boilerplate line by the page count and hands the\n       * corpus a phrase that retrieves against everything.\n       */\n      return {\n        matches: (name) => name === 'word/document.xml' || name === 'word/footnotes.xml' || name === 'word/endnotes.xml',\n        rank: (name) => (name === 'word/document.xml' ? 0 : 1),\n      };\n\n    case 'application/vnd.openxmlformats-officedocument.presentationml.presentation':\n      /*\n       * Slides, then speaker notes. Notes are included because they routinely carry the substance a\n       * slide only gestures at — the sentence a presenter says out loud is often the one worth\n       * retrieving.\n       */\n      return {\n        matches: (name) => /^ppt\\/(slides\\/slide|notesSlides\\/notesSlide)\\d+\\.xml$/u.test(name),\n        rank: (name) => (name.startsWith('ppt/slides/') ? 0 : 1),\n      };\n\n    case 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet':\n      /*\n       * Shared strings FIRST, then the sheets. In SpreadsheetML most cell text is de-duplicated into\n       * `sharedStrings.xml` and referenced by index from the sheet, so the shared table IS the\n       * document's prose; the sheets add inline strings and the numbers' surrounding structure.\n       *\n       * The index indirection is deliberately NOT resolved. Reading both parts yields every string\n       * once, which is what a corpus needs; rebuilding each cell's value in place would reproduce\n       * the spreadsheet, not its text, and would repeat every shared string once per use.\n       */\n      return {\n        matches: (name) => name === 'xl/sharedStrings.xml' || /^xl\\/worksheets\\/sheet\\d+\\.xml$/u.test(name),\n        rank: (name) => (name === 'xl/sharedStrings.xml' ? 0 : 1),\n      };\n\n    default:\n      // Every OpenDocument format keeps its whole body in one `content.xml` — which is why the\n      // three of them need no branch between them.\n      return { matches: (name) => name === 'content.xml', rank: () => 0 };\n  }\n}\n\n/** Numeric-aware comparison, so `slide2.xml` precedes `slide10.xml` rather than following it. */\nfunction compareNumericallyWithinRank(left: string, right: string): number {\n  return left.localeCompare(right, 'en', { numeric: true });\n}\n\n/**\n * Walk a `preserveOrder` parse tree, appending every text node and breaking lines at block\n * boundaries.\n *\n * `preserveOrder` is what makes this correct rather than approximate: the parser emits an ARRAY of\n * single-key objects in document order, so text that is interleaved between child elements — which\n * is every run in a Word paragraph — arrives in the order a reader would meet it. The default\n * (unordered) shape collapses repeated siblings into arrays keyed by tag name and loses the\n * interleaving entirely, which silently reorders every sentence containing formatting.\n */\nfunction collectText(node: unknown, out: string[]): void {\n  if (Array.isArray(node)) {\n    for (const child of node) {\n      collectText(child, out);\n    }\n    return;\n  }\n  if (typeof node !== 'object' || node === null) {\n    return;\n  }\n\n  for (const [name, value] of Object.entries(node as Record<string, unknown>)) {\n    if (name === '#text') {\n      // `trimValues: false` keeps the intra-run spacing that separates words across formatting\n      // boundaries — trimming here is what turns \"the <b>quick</b> fox\" into \"thequickfox\".\n      if (typeof value === 'string' && value.length > 0) {\n        out.push(value);\n      }\n      continue;\n    }\n    collectText(value, out);\n    if (BLOCK_ELEMENT_NAMES.has(name)) {\n      out.push('\\n');\n    }\n  }\n}\n\n/**\n * Extract the text of one OOXML or OpenDocument file.\n *\n * Throws {@link OfficeDocumentExtractionError} rather than returning an empty string for a document\n * it could not read: an empty corpus and an unreadable file are different facts, and the caller\n * classifies them differently — one is \"this document has no text\", the other is \"these bytes are\n * not what they claim to be\".\n */\nexport async function extractOfficeDocumentText(\n  document: Buffer,\n  mimeType: string,\n): Promise<OfficeDocumentExtraction> {\n  // Dynamic, matching how `pdfjs-dist` is loaded for PDF: both are installed dependencies that only\n  // a file-extraction call needs, and neither belongs on the boot path of every backend process.\n  const [{ unzipSync }, { XMLParser }] = await Promise.all([\n    import('fflate'),\n    import('fast-xml-parser'),\n  ]);\n\n  const selector = selectorFor(mimeType);\n\n  let declaredBytes = 0;\n  let inspectedEntries = 0;\n  let entries: Record<string, Uint8Array>;\n  try {\n    entries = unzipSync(new Uint8Array(document), {\n      filter: (file) => {\n        inspectedEntries += 1;\n        if (inspectedEntries > MAX_ARCHIVE_ENTRIES) {\n          throw new OfficeDocumentExtractionError(\n            OfficeDocumentExtractionFailure.ARCHIVE_TOO_LARGE,\n            `Archive declares more than ${MAX_ARCHIVE_ENTRIES} entries`,\n          );\n        }\n        if (!selector.matches(file.name)) {\n          return false;\n        }\n        /*\n         * `originalSize` comes from the central directory, so this refuses BEFORE the bytes are\n         * allocated. Checking after decompression would be checking after the damage.\n         */\n        declaredBytes += file.originalSize;\n        if (declaredBytes > MAX_TOTAL_UNCOMPRESSED_BYTES) {\n          throw new OfficeDocumentExtractionError(\n            OfficeDocumentExtractionFailure.ARCHIVE_TOO_LARGE,\n            `Archive declares ${declaredBytes} uncompressed bytes across its text parts, above the ${MAX_TOTAL_UNCOMPRESSED_BYTES} limit`,\n          );\n        }\n        return true;\n      },\n    });\n  } catch (cause) {\n    if (cause instanceof OfficeDocumentExtractionError) {\n      throw cause;\n    }\n    throw new OfficeDocumentExtractionError(\n      OfficeDocumentExtractionFailure.UNREADABLE_CONTAINER,\n      'The document is not a readable ZIP container',\n      cause,\n    );\n  }\n\n  const partNames = Object.keys(entries).sort(\n    (left, right) => selector.rank(left) - selector.rank(right) || compareNumericallyWithinRank(left, right),\n  );\n\n  if (partNames.length === 0) {\n    throw new OfficeDocumentExtractionError(\n      OfficeDocumentExtractionFailure.NO_TEXT_PARTS,\n      `The archive holds none of the XML parts a ${mimeType} keeps its text in`,\n    );\n  }\n\n  const parser = new XMLParser({\n    preserveOrder: true,\n    // Attributes carry no prose. Ignoring them also keeps the walker from having to skip the\n    // parser's `:@` attribute nodes, which would otherwise be indistinguishable from elements.\n    ignoreAttributes: true,\n    trimValues: false,\n    // XML's five predefined entities and numeric references are what a `&amp;` in a document body\n    // arrives as; without this the corpus carries the escape rather than the character.\n    processEntities: true,\n  });\n\n  const decoder = new TextDecoder('utf-8');\n  const pieces: string[] = [];\n  for (const partName of partNames) {\n    collectText(parser.parse(decoder.decode(entries[partName]!)), pieces);\n    // A part boundary is a block boundary: the last paragraph of one slide must not run into the\n    // first of the next.\n    pieces.push('\\n');\n  }\n\n  /*\n   * Collapse the runs of blank lines the block breaks produce — a Word paragraph inside a table row\n   * closes both, and an empty paragraph closes one around nothing. Left alone, a document with any\n   * table structure arrives as more newlines than text, and the chunker then splits on them.\n   */\n  const text = pieces\n    .join('')\n    .replace(/[ \\t]+\\n/gu, '\\n')\n    .replace(/\\n{3,}/gu, '\\n\\n')\n    .trim();\n\n  return { text, partCount: partNames.length };\n}\n"]}

package/dist/esm/flows-actors/a2a/batches/a2a-abandoned-task-sweep.batch.backend.service.d.ts

@@ -20,6 +20,21 @@
  * the lease is refreshed on a heartbeat, the row is not. So `updatedAt` is used purely
  * to avoid a Redis lookup per non-terminal row; the LEASE decides. Treating an old
  * timestamp as proof of abandonment would kill healthy long-running work.
+ *
+ * ## Why a missing lease is not, on its own, the verdict either
+ *
+ * The lease decides only when its ABSENCE can be explained. A pod whose own Redis writes are
+ * failing produces a turn that is running perfectly and has no lease, and from this pod that is
+ * indistinguishable from a pod that died — while `isLeaseMechanismWritable` above, which is
+ * evaluated HERE, sees nothing wrong. Recording FAILED on such a row makes a false reading
+ * permanent, and until the reclaim path in `advanceTask` there was no way back at all.
+ *
+ * So each candidate's missing lease has to explain itself before this batch acts on it
+ * (`corroborateAbandonment` → {@link A2A_AbandonmentEvidence}): a lease that demonstrably existed
+ * and lapsed is a verdict on the first pass, an unexplained absence has to still be there a full
+ * sweep period later, and an enquiry that failed outright is never counted as either. The cost is
+ * an hour's delay for the rare row whose establishment marker has expired; the benefit is that no
+ * single unexplainable reading can end a live turn.
  */
 import { createCustomBatchExecutionService } from '../../../base-classes/services/batches/batches-cronjobs-custom-execution.service';
 export declare function createA2AAbandonedTaskSweepBatch(): ReturnType<typeof createCustomBatchExecutionService>;

package/dist/esm/flows-actors/a2a/batches/a2a-abandoned-task-sweep.batch.backend.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"a2a-abandoned-task-sweep.batch.backend.service.d.ts","sourceRoot":"","sources":["../../../../../../src/flows-actors/a2a/batches/a2a-abandoned-task-sweep.batch.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAUH,OAAO,EAAE,iCAAiC,EAAE,MAAM,4FAA4F,CAAC;AA+C/I,wBAAgB,gCAAgC,IAAI,UAAU,CAAC,OAAO,iCAAiC,CAAC,CAqKvG"}
+{"version":3,"file":"a2a-abandoned-task-sweep.batch.backend.service.d.ts","sourceRoot":"","sources":["../../../../../../src/flows-actors/a2a/batches/a2a-abandoned-task-sweep.batch.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAUH,OAAO,EAAE,iCAAiC,EAAE,MAAM,4FAA4F,CAAC;AA6D/I,wBAAgB,gCAAgC,IAAI,UAAU,CAAC,OAAO,iCAAiC,CAAC,CAgNvG"}

package/dist/esm/flows-actors/a2a/batches/a2a-abandoned-task-sweep.batch.backend.service.js

@@ -20,6 +20,21 @@
  * the lease is refreshed on a heartbeat, the row is not. So `updatedAt` is used purely
  * to avoid a Redis lookup per non-terminal row; the LEASE decides. Treating an old
  * timestamp as proof of abandonment would kill healthy long-running work.
+ *
+ * ## Why a missing lease is not, on its own, the verdict either
+ *
+ * The lease decides only when its ABSENCE can be explained. A pod whose own Redis writes are
+ * failing produces a turn that is running perfectly and has no lease, and from this pod that is
+ * indistinguishable from a pod that died — while `isLeaseMechanismWritable` above, which is
+ * evaluated HERE, sees nothing wrong. Recording FAILED on such a row makes a false reading
+ * permanent, and until the reclaim path in `advanceTask` there was no way back at all.
+ *
+ * So each candidate's missing lease has to explain itself before this batch acts on it
+ * (`corroborateAbandonment` → {@link A2A_AbandonmentEvidence}): a lease that demonstrably existed
+ * and lapsed is a verdict on the first pass, an unexplained absence has to still be there a full
+ * sweep period later, and an enquiry that failed outright is never counted as either. The cost is
+ * an hour's delay for the rare row whose establishment marker has expired; the benefit is that no
+ * single unexplainable reading can end a live turn.
  */
 import { z } from 'zod';
 import { CoreResourceType, FlowsActors_Status, } from '@wildo-ai/saas-models';
@@ -28,7 +43,7 @@ import { ENGINE_A2A_ABANDONED_TASK_SWEEP_BATCH_MANIFEST } from '../../../base-cl
 import { SAAS_SERVICE_TYPES } from '../../../inject/models/service-types.js';
 import { projectCaughtErrorLogFields } from '../../../errors/utils/error-log-level-classification.backend.utils.js';
 import { A2A_TASK_LEASE_TTL_SECONDS } from '../../../flows-actors/a2a/services/a2a-task-cancellation.backend.service.js';
-import { isLivenessGovernedA2ATaskStatus, LIVENESS_GOVERNED_TASK_STATUSES, } from '../../../flows-actors/a2a/models/a2a.backend.schemas.js';
+import { A2A_AbandonmentEvidence, abandonmentEvidenceIsAVerdict, isLivenessGovernedA2ATaskStatus, LIVENESS_GOVERNED_TASK_STATUSES, } from '../../../flows-actors/a2a/models/a2a.backend.schemas.js';
 /**
  * Only rows untouched for several lease periods are even considered. Generous on
  * purpose: the cost of waiting one more cycle to repair a dead row is nil, while the
@@ -59,6 +74,18 @@ const A2AAbandonedTaskSweepOutputSchema = z.object({
     stillAlive: z.number(),
     /** Rows that reached a terminal state between the listing and the repair — NOT repairs. */
     raced: z.number(),
+    /**
+     * Rows whose missing lease could not yet be explained, and whose absence this run RECORDED so a
+     * later one can corroborate it. Counted apart from `markedFailed` for the same reason `raced`
+     * is: reporting an enquiry as a repair is claiming work that did not happen.
+     */
+    awaitingCorroboration: z.number(),
+    /**
+     * Rows about which this run learned NOTHING — the enquiry itself failed. Distinct from
+     * `awaitingCorroboration`, which made progress toward a verdict; a run that is mostly this is a
+     * degraded run, not a quiet one.
+     */
+    undetermined: z.number(),
 });
 export function createA2AAbandonedTaskSweepBatch() {
     return createCustomBatchExecutionService({
@@ -83,6 +110,12 @@ export function createA2AAbandonedTaskSweepBatch() {
             // because they are NOT repairs — counting them in `markedFailed` is how a sweep claims work
             // it did not do, which is the same dishonesty the no-match log exists to prevent.
             let raced = 0;
+            // Rows this run declined to judge, split by WHY. Two counters, not one, because the two
+            // want opposite reactions: a run full of `awaitingCorroboration` is working as designed and
+            // will decide next hour, while a run full of `undetermined` is one whose liveness enquiry is
+            // itself broken and will never decide anything.
+            let awaitingCorroboration = 0;
+            let undetermined = 0;
             // ── ABSTAIN when the liveness signal cannot be trusted (review finding A3-4) ───────────
             //
             // This batch is the ONLY consumer that converts a liveness answer into a durable terminal
@@ -98,7 +131,7 @@ export function createA2AAbandonedTaskSweepBatch() {
                 logger.warn('[A2ATaskSweep] Skipping the run: the task-lease mechanism is not writable, so liveness cannot be trusted', {
                     consequence: 'abandoned tasks stay unrepaired until a later run; derive-on-read still reports them as failed',
                 });
-                return { scanned: 0, markedFailed: 0, stillAlive: 0, raced: 0 };
+                return { scanned: 0, markedFailed: 0, stillAlive: 0, raced: 0, awaitingCorroboration: 0, undetermined: 0 };
             }
             const cutoff = new Date(Date.now() - ABANDONMENT_GRACE_MS);
             for (const resourceType of TASK_VARIANTS) {
@@ -139,6 +172,40 @@ export function createA2AAbandonedTaskSweepBatch() {
                         stillAlive += 1;
                         continue;
                     }
+                    // ── "No lease" is not yet a VERDICT (review finding S-1a) ──────────────────────────
+                    //
+                    // The fleet-wide `isLeaseMechanismWritable` gate above is evaluated on THIS pod. A
+                    // per-pod failure — the EXECUTING pod's Redis connection is broken while the sweep's is
+                    // fine — passes it untouched: `isTurnAlive` then truthfully reports no lease for a turn
+                    // that is running perfectly well, and everything below would record that durably. The
+                    // owning pod does log the fact, but it logs it on the pod nobody here is reading.
+                    //
+                    // So the absence has to explain itself before it is acted on. `LEASE_LAPSED` means the
+                    // lease demonstrably existed and stopped — a pod held this work and died, which is this
+                    // batch's whole purpose and is repaired on the first pass, exactly as before.
+                    // `CORROBORATED_ABSENCE` means a previous run saw the same unexplained absence and it is
+                    // still there a full sweep period later, which no merely-failed write survives. Anything
+                    // else is an enquiry, not an answer, and an enquiry must never become a terminal status.
+                    const evidence = await cancellation.corroborateAbandonment(task.taskId);
+                    if (!abandonmentEvidenceIsAVerdict(evidence)) {
+                        // Note what is NOT done here: no broadcast. Cancelling on an unexplained absence would
+                        // destroy the very turn this abstention exists to protect, and the broadcast below is
+                        // deliberately paired with the durable write rather than with the observation.
+                        if (evidence === A2A_AbandonmentEvidence.FIRST_ABSENCE) {
+                            awaitingCorroboration += 1;
+                            logger.info('[A2ATaskSweep] A task has no lease and no record of ever having had one; left alone pending corroboration', {
+                                taskId: task.taskId,
+                                consequence: 'if the absence is still there next run it is repaired; if the owning pod was merely unable to write, its next heartbeat clears this',
+                            });
+                        }
+                        else {
+                            undetermined += 1;
+                            logger.warn('[A2ATaskSweep] Could not establish why a task has no lease; nothing was learned and nothing was recorded', {
+                                taskId: task.taskId, evidence,
+                            });
+                        }
+                        continue;
+                    }
                     // Site 2 of 2 for "a cancellation is broadcast whenever cancellation is requested"
                     // (review finding G7-2). The sweep is about to DECLARE this turn dead. If it is not
                     // actually dead — the lease could be missing because a write failed, or because the
@@ -175,6 +242,11 @@ export function createA2AAbandonedTaskSweepBatch() {
                         const repaired = await systemAccess.updateAsSystem(resourceType, { taskId: task.taskId, status: { $in: SWEEPABLE_STATUSES } }, { status: FlowsActors_Status.FAILED, finishedAt: new Date() });
                         if (repaired) {
                             markedFailed += 1;
+                            // The EVIDENCE is carried into the record of the repair, not just the fact of it. A
+                            // run whose repairs are all `corroborated-absence` is telling an operator that turns
+                            // are being killed on the weaker of the two verdicts — which is the signal that a
+                            // pod somewhere cannot write its leases, and the only place that shows.
+                            logger.info('[A2ATaskSweep] Repaired an abandoned task', { taskId: task.taskId, evidence });
                         }
                         else {
                             // A no-match is now AMBIGUOUS and the two causes want opposite reactions, so it is
@@ -203,9 +275,8 @@ export function createA2AAbandonedTaskSweepBatch() {
             }
             // Logged unconditionally, including the zero case: a sweep that silently finds
             // nothing is indistinguishable from a sweep that silently stopped running.
-            logger.info('[A2ATaskSweep] Abandoned-task sweep complete', { scanned, markedFailed, stillAlive });
-            logger.info('[A2ATaskSweep] Sweep complete', { scanned, markedFailed, stillAlive, raced });
-            return { scanned, markedFailed, stillAlive, raced };
+            logger.info('[A2ATaskSweep] Sweep complete', { scanned, markedFailed, stillAlive, raced, awaitingCorroboration, undetermined });
+            return { scanned, markedFailed, stillAlive, raced, awaitingCorroboration, undetermined };
         },
     });
 }