@bevel-software/platform-core-backend 0.31.0 → 0.33.0

package/dist/modules/workspace/file-readers/doc-extract.service.js

@@ -1,5 +1,13 @@
 import { extractionMarker, fileExtension } from './doc-extract.types.js';
 import { DocExtractionCache, gitBlobSha } from './extraction-cache.js';
+/**
+ * How long an extraction stopped over its budget, or whose worker died under
+ * it, is remembered: an overrun is a property of the moment (a busy server, a
+ * large file), not of the bytes, so it is tried again after this. A parser's
+ * refusal is a property of the bytes and is remembered like a success
+ * (decided 2026-10-15/19).
+ */
+export const TIMEOUT_MEMORY_MS = 60 * 60 * 1000;
 /**
  * The content-hash CACHE wrap around document text extraction. The per-format
  * `DocumentReader`s in the file-reader registry stay pure (each pairs one
@@ -15,7 +23,15 @@ import { DocExtractionCache, gitBlobSha } from './extraction-cache.js';
  * extract DIFFERENTLY per format: a `.odt` renamed `.ods` must run the ods
  * extractor, not return the odt extraction. Extraction is deterministic
  * (stable slide/sheet/page ordering), which is what makes a content-keyed
- * cache correct. Failures are NOT cached (rare, and fail fast). The key also carries
+ * cache correct.
+ *
+ * Extraction itself runs in a worker, under a budget (`IDocumentExtractor`),
+ * and its FAILURES are remembered under the same key: a parser's refusal for
+ * good, so damaged bytes cost the server once for as long as the entry is
+ * kept (the cache evicts by size, as it does successes), and a timeout or a
+ * crash for {@link TIMEOUT_MEMORY_MS}. A re-saved file is new content and is
+ * extracted again. Only "no worker was free" is not remembered: it says
+ * nothing about the file. The key also carries
  * `EXTRACTION_SCHEMA`, so an upgrade that changes what an extractor emits does
  * not keep serving the previous release's text for unchanged bytes.
  */
@@ -38,7 +54,10 @@ import { DocExtractionCache, gitBlobSha } from './extraction-cache.js';
  */
 export const EXTRACTION_SCHEMA = 'v3';
 export class DocExtractService {
+    extractor;
     cache;
+    now;
+    onUnreadable;
     /**
      * Cold extractions currently running, by cache key. Two reads of the same
      * document arriving together would otherwise BOTH parse it — the expensive
@@ -46,48 +65,81 @@ export class DocExtractService {
      * written the cache entry yet when the other looked.
      */
     inFlight = new Map();
-    constructor(cacheRoot) {
+    constructor(cacheRoot, extractor, opts = {}) {
+        this.extractor = extractor;
         this.cache = new DocExtractionCache(cacheRoot);
+        this.now = opts.now ?? Date.now;
+        this.onUnreadable = opts.onUnreadable;
     }
     /**
-     * The CACHED extraction for these bytes, or undefined on a cache miss —
-     * never extracts. `grep` uses this (via `DocumentReader.greppableText`) to
-     * search already-extracted documents for free and apply its per-walk budget
-     * only to cold ones.
+     * What the cache REMEMBERS for these bytes — the extraction, or the notice
+     * of a failed one — or undefined on a miss; never extracts. `grep` uses this
+     * (via `DocumentReader.cachedRead`) to search already-extracted documents
+     * for free, skip remembered failures for free, and apply its per-walk budget
+     * only to cold ones; `file_stat` uses it to report a remembered failure.
      */
     async getCached(path, bytes) {
-        const hit = await this.cache.get(this.cacheKey(path, bytes));
-        return hit && { marker: extractionMarker(path, hit.summary), text: hit.text };
+        const hit = await this.cache.get(this.cacheKey(path, bytes), this.now());
+        if (!hit)
+            return undefined;
+        return hit.failed
+            ? { ok: false, message: hit.message }
+            : { ok: true, marker: extractionMarker(path, hit.summary), text: hit.text };
     }
-    /** Extract via `extractFn` (cache hit or parse + store). `path` supplies the marker AND the key's format part. */
-    async extract(path, bytes, extractFn) {
+    /**
+     * The extraction of `bytes` (remembered, or run in the extractor's worker
+     * and remembered). `path` supplies the marker AND the key's format part;
+     * `origin`, when given, is where a fresh failure is reported.
+     */
+    async extract(path, bytes, origin) {
         const key = this.cacheKey(path, bytes);
-        const hit = await this.cache.get(key);
-        if (hit)
-            return { ok: true, marker: extractionMarker(path, hit.summary), text: hit.text };
+        const remembered = await this.getCached(path, bytes);
+        if (remembered)
+            return remembered;
         const running = this.inFlight.get(key);
         const result = await (running ??
             (() => {
                 // The cache write stays INSIDE the shared promise: were the entry
                 // dropped as soon as parsing settled, a read arriving during the
                 // write would miss both the cache and the in-flight map — and parse
-                // the same document again.
+                // the same document again. The bytes are hashed (above) BEFORE the
+                // extractor takes its copy of them.
                 const started = (async () => {
-                    const res = await extractFn(bytes);
-                    if (res.ok)
+                    const res = await this.extractor.extract(fileExtension(path), bytes);
+                    if (res.ok) {
                         await this.cache.put(key, { summary: res.summary, text: res.text });
+                    }
+                    else if (res.failure !== 'busy') {
+                        const until = res.failure === 'parser' ? undefined : this.now() + TIMEOUT_MEMORY_MS;
+                        await this.cache.put(key, { failed: true, message: res.message, ...(until === undefined ? {} : { until }) });
+                        if (origin)
+                            this.notifyUnreadable({ workspaceId: origin.workspaceId, path, reason: reasonOf(res.message) });
+                    }
                     return res;
                 })().finally(() => this.inFlight.delete(key));
                 this.inFlight.set(key, started);
                 return started;
             })());
         if (!result.ok)
-            return result;
+            return { ok: false, message: result.message };
         return { ok: true, marker: extractionMarker(path, result.summary), text: result.text };
     }
+    /** Best-effort, like every event: a listener that throws never fails the read. */
+    notifyUnreadable(doc) {
+        try {
+            this.onUnreadable?.(doc);
+        }
+        catch {
+            // the read still answers its notice
+        }
+    }
     /** Content hash + lowercased extension — e.g. `…sha….odt` (see the class doc). */
     cacheKey(path, bytes) {
         return `${gitBlobSha(bytes)}${fileExtension(path)}.${EXTRACTION_SCHEMA}`;
     }
 }
+/** A failure's notice, worded to follow "Could not be read:" (the explorer's copy) without saying it twice. */
+function reasonOf(message) {
+    return message.replace(/^could not be read: /, '');
+}
 //# sourceMappingURL=doc-extract.service.js.map

package/dist/modules/workspace/file-readers/doc-extract.service.js.map

@@ -1 +1 @@
-{"version":3,"file":"doc-extract.service.js","sourceRoot":"","sources":["../../../../src/modules/workspace/file-readers/doc-extract.service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"doc-extract.service.js","sourceRoot":"","sources":["../../../../src/modules/workspace/file-readers/doc-extract.service.ts"],"names":[],"mappings":"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"}

package/dist/modules/workspace/file-readers/doc-extract.types.d.ts

@@ -33,12 +33,19 @@ export type ExtractResult = ({
 } & ExtractedDoc) | {
     ok: false;
     message: string;
+    /**
+     * Set when the failure is the reader's, not the file's — the parser
+     * itself did not load — so it is not remembered as the file's answer
+     * the way a refusal of its bytes is.
+     */
+    transient?: true;
 };
 /**
  * A format's PURE extract function — bytes in, `ExtractResult` out (async for
  * pdf.js). One per supported format (extract-docx.ts and friends); each is
- * paired with its extension by a `DocumentReader` entry in the file-reader
- * registry, and cache-wrapped by `DocExtractService`.
+ * paired with its extension in the extraction worker's table
+ * (`document-extractors.ts`), run there under a budget, and cache-wrapped by
+ * `DocExtractService`.
  */
 export type ExtractFn = (bytes: Buffer) => ExtractResult | Promise<ExtractResult>;
 /**

package/dist/modules/workspace/file-readers/doc-extract.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doc-extract.types.d.ts","sourceRoot":"","sources":["../../../../src/modules/workspace/file-readers/doc-extract.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,uHAAuH;IACvH,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,GACrB,CAAC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG,YAAY,CAAC,GAC7B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnC;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;AAElF;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIlD"}
+{"version":3,"file":"doc-extract.types.d.ts","sourceRoot":"","sources":["../../../../src/modules/workspace/file-readers/doc-extract.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,uHAAuH;IACvH,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,GACrB,CAAC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG,YAAY,CAAC,GAC7B;IACE,EAAE,EAAE,KAAK,CAAC;IACV,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,SAAS,CAAC,EAAE,IAAI,CAAC;CAClB,CAAC;AAEN;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;AAElF;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIlD"}

package/dist/modules/workspace/file-readers/doc-extract.types.js.map

@@ -1 +1 @@
-{"version":3,"file":"doc-extract.types.js","sourceRoot":"","sources":["../../../../src/modules/workspace/file-readers/doc-extract.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AA8B7D;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,OAAe;IAC5D,OAAO,sBAAsB,aAAa,CAAC,IAAI,CAAC,MAAM,OAAO,GAAG,CAAC;AACnE,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IACnD,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAClC,OAAO,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AACtD,CAAC"}
+{"version":3,"file":"doc-extract.types.js","sourceRoot":"","sources":["../../../../src/modules/workspace/file-readers/doc-extract.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAwC7D;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,OAAe;IAC5D,OAAO,sBAAsB,aAAa,CAAC,IAAI,CAAC,MAAM,OAAO,GAAG,CAAC;AACnE,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IACnD,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAClC,OAAO,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AACtD,CAAC"}

package/dist/modules/workspace/file-readers/document-extractor.contract.d.ts

@@ -0,0 +1,41 @@
+import type { ExtractedDoc } from './doc-extract.types.js';
+/**
+ * The contract for running a document's extractor: what `DocExtractService`
+ * depends on, so it never holds a concrete engine. The one implementation is
+ * `WorkerDocumentExtractor` (`extract-in-worker.ts`), owned by the
+ * composition root and closed with the graph.
+ *
+ * A parser can hang on crafted input and can reject promises it never hands
+ * back, so an implementation must never run one on the request thread, must
+ * stop an extraction that outlives its budget, and must answer every failure
+ * — a parser error, a dangling rejection, a crash — as an outcome, never as a
+ * rejection of `extract` and never as an event on the server's process.
+ */
+export interface IDocumentExtractor {
+    /** Extract `bytes` as a file of `extension` (lowercased, with its dot). The caller's buffer is left as it was. */
+    extract(extension: string, bytes: Buffer): Promise<IsolatedExtraction>;
+    /** Ends the workers; an extraction after this is answered `busy`. */
+    close(): Promise<void>;
+}
+/**
+ * Why an extraction failed, which is what decides how long the failure is
+ * remembered (see `DocExtractService`):
+ *  - `parser`: the parser refused the bytes, threw, or left a rejection behind
+ *    it — a property of the content;
+ *  - `timeout`: the extraction outlived its budget and was stopped;
+ *  - `crashed`: the worker failed or died under the job without answering
+ *    (out of memory, a script that would not load), or the parser itself did
+ *    not load — a fault of the moment;
+ *  - `busy`: no worker could take the job — nothing was learned about the file.
+ */
+export type ExtractionFailure = 'parser' | 'timeout' | 'crashed' | 'busy';
+export type IsolatedExtraction = ({
+    ok: true;
+} & ExtractedDoc) | {
+    ok: false;
+    message: string;
+    failure: ExtractionFailure;
+};
+/** The notice an extraction stopped over its budget answers with. */
+export declare function extractionTimeoutNotice(budgetMs: number): string;
+//# sourceMappingURL=document-extractor.contract.d.ts.map

package/dist/modules/workspace/file-readers/document-extractor.contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-extractor.contract.d.ts","sourceRoot":"","sources":["../../../../src/modules/workspace/file-readers/document-extractor.contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,kBAAkB;IACjC,kHAAkH;IAClH,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACvE,qEAAqE;IACrE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;AAE1E,MAAM,MAAM,kBAAkB,GAC1B,CAAC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG,YAAY,CAAC,GAC7B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,iBAAiB,CAAA;CAAE,CAAC;AAE/D,qEAAqE;AACrE,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEhE"}

package/dist/modules/workspace/file-readers/document-extractor.contract.js

@@ -0,0 +1,5 @@
+/** The notice an extraction stopped over its budget answers with. */
+export function extractionTimeoutNotice(budgetMs) {
+    return `could not be read: extracting its text took longer than ${budgetMs / 1000} seconds`;
+}
+//# sourceMappingURL=document-extractor.contract.js.map

package/dist/modules/workspace/file-readers/document-extractor.contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-extractor.contract.js","sourceRoot":"","sources":["../../../../src/modules/workspace/file-readers/document-extractor.contract.ts"],"names":[],"mappings":"AAsCA,qEAAqE;AACrE,MAAM,UAAU,uBAAuB,CAAC,QAAgB;IACtD,OAAO,2DAA2D,QAAQ,GAAG,IAAI,UAAU,CAAC;AAC9F,CAAC"}

package/dist/modules/workspace/file-readers/document-extractors.d.ts

@@ -0,0 +1,9 @@
+import type { DocumentExtension } from './document-formats.js';
+import type { ExtractFn } from './doc-extract.types.js';
+/**
+ * Which pure extract function owns which document format. Loaded by the
+ * extraction worker only (`extract.worker.ts`): no parser runs on the
+ * server's request thread.
+ */
+export declare const DOCUMENT_EXTRACTORS: Readonly<Record<DocumentExtension, ExtractFn>>;
+//# sourceMappingURL=document-extractors.d.ts.map

package/dist/modules/workspace/file-readers/document-extractors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-extractors.d.ts","sourceRoot":"","sources":["../../../../src/modules/workspace/file-readers/document-extractors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAWxD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,iBAAiB,EAAE,SAAS,CAAC,CAU9E,CAAC"}

package/dist/modules/workspace/file-readers/document-extractors.js

@@ -0,0 +1,26 @@
+import { extractDocx } from './extract-docx.js';
+import { extractEml } from './extract-eml.js';
+import { extractMsg } from './extract-msg.js';
+import { extractOdp } from './extract-odp.js';
+import { extractOds } from './extract-ods.js';
+import { extractOdt } from './extract-odt.js';
+import { extractPdf } from './extract-pdf.js';
+import { extractPptx } from './extract-pptx.js';
+import { extractXlsx } from './extract-xlsx.js';
+/**
+ * Which pure extract function owns which document format. Loaded by the
+ * extraction worker only (`extract.worker.ts`): no parser runs on the
+ * server's request thread.
+ */
+export const DOCUMENT_EXTRACTORS = {
+    '.docx': extractDocx,
+    '.pptx': extractPptx,
+    '.xlsx': extractXlsx,
+    '.pdf': extractPdf,
+    '.odt': extractOdt,
+    '.odp': extractOdp,
+    '.ods': extractOds,
+    '.eml': extractEml,
+    '.msg': extractMsg,
+};
+//# sourceMappingURL=document-extractors.js.map

package/dist/modules/workspace/file-readers/document-extractors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-extractors.js","sourceRoot":"","sources":["../../../../src/modules/workspace/file-readers/document-extractors.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAmD;IACjF,OAAO,EAAE,WAAW;IACpB,OAAO,EAAE,WAAW;IACpB,OAAO,EAAE,WAAW;IACpB,MAAM,EAAE,UAAU;IAClB,MAAM,EAAE,UAAU;IAClB,MAAM,EAAE,UAAU;IAClB,MAAM,EAAE,UAAU;IAClB,MAAM,EAAE,UAAU;IAClB,MAAM,EAAE,UAAU;CACnB,CAAC"}

package/dist/modules/workspace/file-readers/document-formats.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The document formats whose text is EXTRACTED rather than read: the one list
+ * both sides of the extraction worker agree on. The file-reader registry
+ * builds a reader for each, on the request thread, without loading a single
+ * parser; the worker's table (`document-extractors.ts`) is typed by these
+ * lists, so a format added here and not there fails to compile.
+ */
+export declare const OFFICE_DOCUMENT_EXTENSIONS: readonly [".docx", ".pptx", ".xlsx", ".pdf", ".odt", ".odp", ".ods"];
+/** Email files: extracted the same way, refused for writing with an email-honest message (see `EmailReader`). */
+export declare const EMAIL_EXTENSIONS: readonly [".eml", ".msg"];
+export type DocumentExtension = (typeof OFFICE_DOCUMENT_EXTENSIONS)[number] | (typeof EMAIL_EXTENSIONS)[number];
+//# sourceMappingURL=document-formats.d.ts.map

package/dist/modules/workspace/file-readers/document-formats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-formats.d.ts","sourceRoot":"","sources":["../../../../src/modules/workspace/file-readers/document-formats.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,sEAAuE,CAAC;AAE/G,iHAAiH;AACjH,eAAO,MAAM,gBAAgB,2BAA4B,CAAC;AAE1D,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,0BAA0B,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/modules/workspace/file-readers/document-formats.js

@@ -0,0 +1,11 @@
+/**
+ * The document formats whose text is EXTRACTED rather than read: the one list
+ * both sides of the extraction worker agree on. The file-reader registry
+ * builds a reader for each, on the request thread, without loading a single
+ * parser; the worker's table (`document-extractors.ts`) is typed by these
+ * lists, so a format added here and not there fails to compile.
+ */
+export const OFFICE_DOCUMENT_EXTENSIONS = ['.docx', '.pptx', '.xlsx', '.pdf', '.odt', '.odp', '.ods'];
+/** Email files: extracted the same way, refused for writing with an email-honest message (see `EmailReader`). */
+export const EMAIL_EXTENSIONS = ['.eml', '.msg'];
+//# sourceMappingURL=document-formats.js.map

package/dist/modules/workspace/file-readers/document-formats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-formats.js","sourceRoot":"","sources":["../../../../src/modules/workspace/file-readers/document-formats.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAU,CAAC;AAE/G,iHAAiH;AACjH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAU,CAAC"}

package/dist/modules/workspace/file-readers/document-reader.d.ts

@@ -1,21 +1,20 @@
 import type { DocExtractService } from './doc-extract.service.js';
-import type { ExtractFn } from './doc-extract.types.js';
-import { type FileReader, type ReadResult } from './file-reader.js';
+import { type FileReader, type ReadOrigin, type ReadResult } from './file-reader.js';
 /**
- * FileReader over one document format: a thin wrapper pairing the format's
- * PURE extract function (extract-docx.ts and friends) with the shared
- * content-hash extraction cache (`DocExtractService`). Reads return the
- * extraction under its honest `[extracted text of …]` marker; a parse failure
- * becomes a refusal message, never a 500.
+ * FileReader over one document format: a thin wrapper around the shared
+ * content-hash extraction service (`DocExtractService`), which runs the
+ * format's extractor in a worker and remembers what it answered. Reads return
+ * the extraction under its honest `[extracted text of …]` marker; a failed
+ * extraction becomes a refusal message, never a 500.
  *
- * `grep` semantics: `greppableText` serves only the CACHED extraction (a hit
- * costs one small JSON read), returning null for a cold document — whether to
- * spend grep's per-walk extraction budget on a cold one is the walk's call,
- * which then extracts through `read` (see grepWalk in workspace.tools.ts).
- * grep also branches on `instanceof DocumentReader` for exactly that decision.
+ * `grep` semantics: `cachedRead` answers only what the cache REMEMBERS (a hit
+ * costs one small JSON read) — the extraction, or a failure's notice — and
+ * undefined for a cold document; whether to spend grep's per-walk extraction
+ * budget on a cold one is the walk's call, which then extracts through `read`
+ * (see grepWalk in workspace.tools.ts). grep also branches on
+ * `instanceof DocumentReader` for exactly that decision.
  */
 export declare class DocumentReader implements FileReader {
-    private readonly extract;
     private readonly service;
     readonly extensions: readonly string[];
     /**
@@ -25,10 +24,15 @@ export declare class DocumentReader implements FileReader {
      */
     readonly textEditable = false;
     readonly fileKind: "document";
-    constructor(extension: string, extract: ExtractFn, service: DocExtractService);
-    read(bytes: Buffer, path: string): Promise<ReadResult>;
+    constructor(extension: string, service: DocExtractService);
+    /** `origin` names the workspace the file was read in, so a fresh failure can be reported there. */
+    read(bytes: Buffer, path: string, origin?: ReadOrigin): Promise<ReadResult>;
+    /**
+     * What `read` would answer, from the cache alone — the extraction (marker
+     * line included, so grep's line numbers match read_file's) or a remembered
+     * failure's refusal — or undefined when the document is cold. Never extracts.
+     */
+    cachedRead(bytes: Buffer, path: string): Promise<ReadResult | undefined>;
     mimeFor(path: string): string | undefined;
-    /** The cached extraction (marker line included, so grep's line numbers match read_file's), or null when cold. */
-    greppableText(bytes: Buffer, path: string): Promise<string | null>;
 }
 //# sourceMappingURL=document-reader.d.ts.map

package/dist/modules/workspace/file-readers/document-reader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"document-reader.d.ts","sourceRoot":"","sources":["../../../../src/modules/workspace/file-readers/document-reader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAwB,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG1F;;;;;;;;;;;;GAYG;AACH,qBAAa,cAAe,YAAW,UAAU;IAY7C,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAZ1B,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,YAAY,SAAS;IAC9B,QAAQ,CAAC,QAAQ,EAAG,UAAU,CAAU;gBAGtC,SAAS,EAAE,MAAM,EACA,OAAO,EAAE,SAAS,EAClB,OAAO,EAAE,iBAAiB;IAKvC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAwB5D,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIzC,iHAAiH;IAC3G,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;CAIzE"}
+{"version":3,"file":"document-reader.d.ts","sourceRoot":"","sources":["../../../../src/modules/workspace/file-readers/document-reader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAqB,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACrF,OAAO,EAAwB,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG3G;;;;;;;;;;;;;GAaG;AACH,qBAAa,cAAe,YAAW,UAAU;IAY7C,OAAO,CAAC,QAAQ,CAAC,OAAO;IAX1B,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,YAAY,SAAS;IAC9B,QAAQ,CAAC,QAAQ,EAAG,UAAU,CAAU;gBAGtC,SAAS,EAAE,MAAM,EACA,OAAO,EAAE,iBAAiB;IAK7C,mGAAmG;IAC7F,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IAcjF;;;;OAIG;IACG,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAK9E,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;CAG1C"}

package/dist/modules/workspace/file-readers/document-reader.js

@@ -1,20 +1,20 @@
 import { displayPath, oneLine } from './file-reader.js';
 import { extensionMime } from './text-reader.js';
 /**
- * FileReader over one document format: a thin wrapper pairing the format's
- * PURE extract function (extract-docx.ts and friends) with the shared
- * content-hash extraction cache (`DocExtractService`). Reads return the
- * extraction under its honest `[extracted text of …]` marker; a parse failure
- * becomes a refusal message, never a 500.
+ * FileReader over one document format: a thin wrapper around the shared
+ * content-hash extraction service (`DocExtractService`), which runs the
+ * format's extractor in a worker and remembers what it answered. Reads return
+ * the extraction under its honest `[extracted text of …]` marker; a failed
+ * extraction becomes a refusal message, never a 500.
  *
- * `grep` semantics: `greppableText` serves only the CACHED extraction (a hit
- * costs one small JSON read), returning null for a cold document — whether to
- * spend grep's per-walk extraction budget on a cold one is the walk's call,
- * which then extracts through `read` (see grepWalk in workspace.tools.ts).
- * grep also branches on `instanceof DocumentReader` for exactly that decision.
+ * `grep` semantics: `cachedRead` answers only what the cache REMEMBERS (a hit
+ * costs one small JSON read) — the extraction, or a failure's notice — and
+ * undefined for a cold document; whether to spend grep's per-walk extraction
+ * budget on a cold one is the walk's call, which then extracts through `read`
+ * (see grepWalk in workspace.tools.ts). grep also branches on
+ * `instanceof DocumentReader` for exactly that decision.
  */
 export class DocumentReader {
-    extract;
     service;
     extensions;
     /**
@@ -24,41 +24,45 @@ export class DocumentReader {
      */
     textEditable = false;
     fileKind = 'document';
-    constructor(extension, extract, service) {
-        this.extract = extract;
+    constructor(extension, service) {
         this.service = service;
         this.extensions = [extension];
     }
-    async read(bytes, path) {
-        // An extractor is contracted to ANSWER for bad content rather than throw,
-        // but it wraps third-party parsers, and one of those throwing past its own
-        // guard is a corrupt file — not a server fault. read_file says so instead
-        // of failing the whole tool call with a 500.
+    /** `origin` names the workspace the file was read in, so a fresh failure can be reported there. */
+    async read(bytes, path, origin) {
+        // The service answers every parser failure as an outcome; a throw here is
+        // the service's own fault (the cache's disk, say) — still answered as the
+        // file's honest refusal rather than failing the whole tool call with a 500.
         let res;
         try {
-            res = await this.service.extract(path, bytes, this.extract);
+            res = await this.service.extract(path, bytes, origin);
         }
         catch (err) {
             const reason = err instanceof Error ? err.message : String(err);
-            return {
-                kind: 'refusal',
-                message: `[${displayPath(path)} could not be extracted (${oneLine(reason)}) — the file may be corrupt or mislabeled. To fix it, replace the document by uploading a new version.]`,
-            };
+            res = { ok: false, message: `could not be extracted (${reason})` };
         }
-        return res.ok
-            ? { kind: 'text', text: `${res.marker}\n${res.text}` }
-            : {
-                kind: 'refusal',
-                message: `[${displayPath(path)} ${oneLine(res.message)} — the file may be corrupt or mislabeled. To fix it, replace the document by uploading a new version.]`,
-            };
+        return toReadResult(path, res);
+    }
+    /**
+     * What `read` would answer, from the cache alone — the extraction (marker
+     * line included, so grep's line numbers match read_file's) or a remembered
+     * failure's refusal — or undefined when the document is cold. Never extracts.
+     */
+    async cachedRead(bytes, path) {
+        const hit = await this.service.getCached(path, bytes);
+        return hit && toReadResult(path, hit);
     }
     mimeFor(path) {
         return extensionMime(path);
     }
-    /** The cached extraction (marker line included, so grep's line numbers match read_file's), or null when cold. */
-    async greppableText(bytes, path) {
-        const hit = await this.service.getCached(path, bytes);
-        return hit ? `${hit.marker}\n${hit.text}` : null;
-    }
+}
+/** One outcome, one wording: the same refusal whether the failure is fresh or remembered. */
+function toReadResult(path, res) {
+    return res.ok
+        ? { kind: 'text', text: `${res.marker}\n${res.text}` }
+        : {
+            kind: 'refusal',
+            message: `[${displayPath(path)} ${oneLine(res.message)} — the file may be corrupt or mislabeled. To fix it, replace the document by uploading a new version.]`,
+        };
 }
 //# sourceMappingURL=document-reader.js.map

package/dist/modules/workspace/file-readers/document-reader.js.map

@@ -1 +1 @@
-{"version":3,"file":"document-reader.js","sourceRoot":"","sources":["../../../../src/modules/workspace/file-readers/document-reader.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,OAAO,EAAoC,MAAM,kBAAkB,CAAC;AAC1F,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,cAAc;IAYN;IACA;IAZV,UAAU,CAAoB;IACvC;;;;OAIG;IACM,YAAY,GAAG,KAAK,CAAC;IACrB,QAAQ,GAAG,UAAmB,CAAC;IAExC,YACE,SAAiB,EACA,OAAkB,EAClB,OAA0B;QAD1B,YAAO,GAAP,OAAO,CAAW;QAClB,YAAO,GAAP,OAAO,CAAmB;QAE3C,IAAI,CAAC,UAAU,GAAG,CAAC,SAAS,CAAC,CAAC;IAChC,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,KAAa,EAAE,IAAY;QACpC,0EAA0E;QAC1E,2EAA2E;QAC3E,0EAA0E;QAC1E,6CAA6C;QAC7C,IAAI,GAAqD,CAAC;QAC1D,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAC9D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAChE,OAAO;gBACL,IAAI,EAAE,SAAS;gBACf,OAAO,EAAE,IAAI,WAAW,CAAC,IAAI,CAAC,4BAA4B,OAAO,CAAC,MAAM,CAAC,yGAAyG;aACnL,CAAC;QACJ,CAAC;QAED,OAAO,GAAG,CAAC,EAAE;YACX,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,GAAG,CAAC,MAAM,KAAK,GAAG,CAAC,IAAI,EAAE,EAAE;YACtD,CAAC,CAAC;gBACE,IAAI,EAAE,SAAS;gBACf,OAAO,EAAE,IAAI,WAAW,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,wGAAwG;aAC/J,CAAC;IACR,CAAC;IAED,OAAO,CAAC,IAAY;QAClB,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IAED,iHAAiH;IACjH,KAAK,CAAC,aAAa,CAAC,KAAa,EAAE,IAAY;QAC7C,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACtD,OAAO,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,MAAM,KAAK,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACnD,CAAC;CACF"}
+{"version":3,"file":"document-reader.js","sourceRoot":"","sources":["../../../../src/modules/workspace/file-readers/document-reader.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,OAAO,EAAqD,MAAM,kBAAkB,CAAC;AAC3G,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,cAAc;IAYN;IAXV,UAAU,CAAoB;IACvC;;;;OAIG;IACM,YAAY,GAAG,KAAK,CAAC;IACrB,QAAQ,GAAG,UAAmB,CAAC;IAExC,YACE,SAAiB,EACA,OAA0B;QAA1B,YAAO,GAAP,OAAO,CAAmB;QAE3C,IAAI,CAAC,UAAU,GAAG,CAAC,SAAS,CAAC,CAAC;IAChC,CAAC;IAED,mGAAmG;IACnG,KAAK,CAAC,IAAI,CAAC,KAAa,EAAE,IAAY,EAAE,MAAmB;QACzD,0EAA0E;QAC1E,0EAA0E;QAC1E,4EAA4E;QAC5E,IAAI,GAAsB,CAAC;QAC3B,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;QACxD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAChE,GAAG,GAAG,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,2BAA2B,MAAM,GAAG,EAAE,CAAC;QACrE,CAAC;QACD,OAAO,YAAY,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACjC,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,UAAU,CAAC,KAAa,EAAE,IAAY;QAC1C,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACtD,OAAO,GAAG,IAAI,YAAY,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACxC,CAAC;IAED,OAAO,CAAC,IAAY;QAClB,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;CACF;AAED,6FAA6F;AAC7F,SAAS,YAAY,CAAC,IAAY,EAAE,GAAsB;IACxD,OAAO,GAAG,CAAC,EAAE;QACX,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,GAAG,CAAC,MAAM,KAAK,GAAG,CAAC,IAAI,EAAE,EAAE;QACtD,CAAC,CAAC;YACE,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,IAAI,WAAW,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,wGAAwG;SAC/J,CAAC;AACR,CAAC"}

package/dist/modules/workspace/file-readers/extract-in-worker.d.ts

@@ -0,0 +1,60 @@
+import { type IDocumentExtractor, type IsolatedExtraction } from './document-extractor.contract.js';
+/**
+ * Extraction time one document may spend in its worker: the platform's rule,
+ * not a deployment's (decided 2026-10-19). A longer wait is too unresponsive
+ * for a read or a search; the hour a timeout is remembered for is what keeps a
+ * hanging file cheap (see `DocExtractService`).
+ */
+export declare const EXTRACTION_BUDGET_MS = 10000;
+/** What a document answers when its worker failed outside the parser: never the worker's own error. */
+export declare const EXTRACTION_WORKER_FAILED = "could not be read: its extraction failed on the server; try again later";
+/** The worker script: a module that calls `serveExtractions` (see `extraction-worker.ts`). */
+export interface ExtractionWorkerEntry {
+    url: URL;
+    /** Node options for the worker thread — a TypeScript entry needs its loader. */
+    execArgv: string[];
+}
+export interface WorkerDocumentExtractorOptions {
+    /** Worker time one extraction may spend. Default {@link EXTRACTION_BUDGET_MS}. */
+    budgetMs?: number;
+    /** Workers kept for extractions at once; one past this waits for a worker. Default 4. */
+    poolMax?: number;
+    /**
+     * Extractions that may wait for a worker at once. A waiting extraction holds
+     * the file's bytes, so the queue is capped: past it an extraction is answered
+     * `busy`, and nothing about the file is remembered. Default 32.
+     */
+    maxWaiting?: number;
+    /**
+     * The worker script. Default: the document extractors (`extract.worker`).
+     * A composition serving other extractors — a test's misbehaving parser —
+     * names its own module calling `serveExtractions`.
+     */
+    entry?: ExtractionWorkerEntry;
+}
+/**
+ * The one place a document's extractor runs (see {@link IDocumentExtractor}):
+ * a pooled worker thread — the extraction worker kind of the shared
+ * {@link WorkerPool}, which `grep`'s regex matcher is the other kind of —
+ * under a budget per file.
+ *
+ * The bytes are COPIED once on the request thread and the copy transferred,
+ * so the caller's buffer (already hashed for the cache key, and possibly a
+ * slice of Node's shared pool) is never detached. Past the budget the worker is
+ * terminated, which stops a parser mid-loop, and the file answers the timeout
+ * notice. A worker that answers with a dangling rejection, raises, or dies is
+ * never reused; the pool replaces it. A rejection the worker cannot pin on
+ * this job — it had served another before (see `serveExtractions`) — runs the
+ * job again in a fresh worker, so one file's failure is never another's.
+ */
+export declare class WorkerDocumentExtractor implements IDocumentExtractor {
+    private readonly budgetMs;
+    private readonly pool;
+    private nextJob;
+    private closing;
+    constructor(opts?: WorkerDocumentExtractorOptions);
+    extract(extension: string, bytes: Buffer): Promise<IsolatedExtraction>;
+    private attempt;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=extract-in-worker.d.ts.map

package/dist/modules/workspace/file-readers/extract-in-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-in-worker.d.ts","sourceRoot":"","sources":["../../../../src/modules/workspace/file-readers/extract-in-worker.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACxB,MAAM,kCAAkC,CAAC;AAM1C;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAE3C,uGAAuG;AACvG,eAAO,MAAM,wBAAwB,4EAA4E,CAAC;AAElH,8FAA8F;AAC9F,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,GAAG,CAAC;IACT,gFAAgF;IAChF,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,8BAA8B;IAC7C,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yFAAyF;IACzF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,KAAK,CAAC,EAAE,qBAAqB,CAAC;CAC/B;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,uBAAwB,YAAW,kBAAkB;IAChE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;IAClC,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,OAAO,CAAS;gBAEZ,IAAI,GAAE,8BAAmC;IAc/C,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;YAe9D,OAAO;IAkDrB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAIvB"}