@substrat-run/kernel 0.133.0 → 0.134.0

package/dist/attachment-extractor.d.ts

@@ -0,0 +1,180 @@
+/**
+ * The attachment extractor seam (#1575, K-43): where file formats stop and text begins.
+ *
+ * **The kernel indexes attachment text; it does not parse file formats** (K-43). Every
+ * parser — text and HTML decoding, the zip reader and its inflate budget, DOCX/XLSX/PPTX,
+ * and later PDF and OCR — lives behind this seam in a host-side package
+ * (`@substrat-run/attachment-extractors`), which neither the kernel nor an adapter imports.
+ * Whoever constructs the host passes the extractors in; a host given none records every
+ * type `unsupported`, with that reason, which is a valid configuration rather than a broken
+ * one. `lint:deps` refuses an import of that package from the kernel or an adapter.
+ *
+ * The parsers are the riskiest code in the feature — a zip reader exists to be handed hostile
+ * input — so this file holds them to the guarantees that protect the SCOPE, whatever an
+ * extractor does:
+ *
+ * - **Declarations are checked when the host is built** (`assertAttachmentExtractors`): a
+ *   name, `accepts` and `extract`, and a `maxInputBytes` that is a positive integer if it is
+ *   given at all. A host refuses a list it could not honour rather than misreading it later.
+ * - **The input bound is judged before a byte is fetched**, on the RECORDED size: the kernel's
+ *   ceiling FIRST and on its own, then the extractor's declared bound if it is a valid one.
+ *   Neither can widen the other — a declaration that slipped past the check (a `NaN`) is
+ *   ignored, never allowed to disable the ceiling.
+ * - **A throw is an outcome, not a retry.** An extractor that throws records `failed`, so a
+ *   file that crashes its parser cannot fail its job forever. The thrown message is NOT
+ *   recorded: it is the parser's text, and it may quote the file.
+ * - **The result is validated.** Anything but exactly one of `{ text }` or `{ failed }` is
+ *   `failed`.
+ * - **The output cap is enforced here, after the extractor returns** — normalized, then cut to
+ *   `maxTextBytes` of UTF-8 on a code point boundary and recorded `truncated`. An extractor
+ *   is told the cap as a hint (so it can stop reading early) and cannot exceed it.
+ *
+ * ## The time budget is cooperative, and what that means
+ *
+ * An extractor that has not answered within `timeoutMs` is recorded `failed`, its `signal` is
+ * aborted, and anything it answers afterwards is DISCARDED — including an answer that arrives
+ * "late" because the extractor never yielded: after it returns, the kernel gives the timer the
+ * turn it was owed, and a result the deadline passed is never indexed.
+ *
+ * What the kernel cannot do from inside one isolate is STOP code that does not yield. A
+ * synchronous loop holds the thread until it returns, timer or not; the abort is a request,
+ * honoured by an extractor that checks its `signal` and yields between units of work (the
+ * bundled parsers do, every 64 KiB). So the guarantee is: a cooperative extractor stops
+ * promptly, an uncooperative one cannot get its late answer indexed, and only the runtime's
+ * own CPU limit ends it sooner. A hard deadline on uncooperative code needs process or
+ * isolate isolation — a host can provide it by running its extractors in a separate worker
+ * and handing the kernel a thin extractor that calls it. Under K-43 an extractor is
+ * HOST-supplied code, trusted as the host is; the budget protects the scope from a slow or
+ * broken parser, not from a hostile one, and the bundled parsers bound their own CPU by
+ * construction (linear scans under fixed input caps — their package says how far).
+ */
+/**
+ * The cancellation an extractor is handed — the runtime's own `AbortSignal`, typed here by the
+ * one member the kernel promises: once `aborted` is true, nothing the extractor answers will be
+ * used, and it should stop.
+ */
+export interface ExtractionSignal {
+    readonly aborted: boolean;
+}
+/** What an extractor is handed. `maxTextBytes` is the kernel's output cap, as a hint. */
+export interface AttachmentExtractorInput {
+    readonly body: Uint8Array;
+    readonly contentType: string;
+    readonly filename: string;
+    /** The kernel cuts the text to this many UTF-8 bytes anyway; an extractor may stop early. */
+    readonly maxTextBytes: number;
+    /** Aborted when the time budget runs out. A cooperative extractor checks it and yields. */
+    readonly signal: ExtractionSignal;
+}
+/**
+ * What an extractor answers: the file's text, or a reason it has none. `failed` is for a
+ * file that is not what it says or that broke a bound; its reason is recorded verbatim, so it
+ * must never quote the file. `truncated` says the extractor itself stopped early.
+ */
+export type AttachmentExtractorResult = {
+    text: string;
+    truncated?: boolean;
+} | {
+    failed: string;
+};
+/**
+ * One format's parser (K-43). The host is handed a list; the first that `accepts` a file
+ * extracts it.
+ */
+export interface AttachmentExtractor {
+    /** Recorded as the row's `extractor` — `text`, `html`, `docx`. Unique within a host. */
+    readonly name: string;
+    /**
+     * The largest file this extractor will be handed, judged on the recorded size BEFORE the
+     * bytes are fetched — a positive integer. The kernel's own ceiling applies first, whatever
+     * this says.
+     */
+    readonly maxInputBytes?: number;
+    /** Whether this extractor reads a file of this declared type (and name). */
+    accepts(contentType: string, filename: string): boolean;
+    extract(input: AttachmentExtractorInput): Promise<AttachmentExtractorResult>;
+}
+/** What one extraction recorded. `indexed` is the only outcome that carries text. */
+export type ExtractionOutcome = {
+    status: 'indexed';
+    extractor: string;
+    text: string;
+    truncated: boolean;
+} | {
+    status: 'empty';
+    extractor: string;
+} | {
+    status: 'unsupported';
+    detail: string;
+} | {
+    status: 'failed';
+    extractor: string | null;
+    detail: string;
+};
+/** The bounds the kernel holds every extractor to — each a positive integer. */
+export interface AttachmentTextBounds {
+    /** The ceiling on a file's recorded size, applied before any extractor's own. */
+    readonly maxInputBytes: number;
+    /** UTF-8 bytes of text one attachment may contribute to the index. */
+    readonly maxTextBytes: number;
+    /** How long one extraction may take before it is recorded `failed`. */
+    readonly timeoutMs: number;
+}
+/**
+ * The defaults. `maxTextBytes` is 512 KiB of UTF-8 — a few hundred pages of prose, and a
+ * quarter of the ~2 MB a Durable Object row holds. 32 MiB of input is what a Worker can hold
+ * as bytes beside what it decodes from them.
+ */
+export declare const DEFAULT_ATTACHMENT_TEXT_BOUNDS: AttachmentTextBounds;
+/** A bound that means something: a positive integer. `NaN`, `Infinity`, `0`, `-1` and `'8'` do not. */
+export declare function isPositiveIntegerBound(value: unknown): value is number;
+/** `Text/Plain; charset=UTF-8` → `text/plain`. */
+export declare function mediaTypeOf(contentType: string): string;
+/** Refuse bounds the kernel could not honour: each must be a positive integer. */
+export declare function assertAttachmentTextBounds(bounds: AttachmentTextBounds): void;
+/**
+ * Refuse, when the host is built, an extractor list it could not honour: a missing or
+ * repeated name, an `accepts` or `extract` that is not a function, or a `maxInputBytes` that
+ * is not a positive integer. Failing here, once, is the alternative to misreading the
+ * declaration on every job.
+ */
+export declare function assertAttachmentExtractors(extractors: readonly AttachmentExtractor[]): void;
+/**
+ * Why a file of `size` bytes may not be handed to `extractor`, or null when it may.
+ *
+ * The kernel's ceiling is judged FIRST and on its own, then the extractor's declaration —
+ * and only a valid declaration, so one that slipped past `assertAttachmentExtractors` can
+ * narrow nothing and widen nothing. Never a `Math.min` over the two: a `NaN` there makes every
+ * comparison false, which is the ceiling switched off.
+ */
+export declare function inputBoundRefusal(size: number, extractor: Pick<AttachmentExtractor, 'maxInputBytes'>, bounds: Pick<AttachmentTextBounds, 'maxInputBytes'>): string | null;
+/** The first extractor that reads this file, or none. An `accepts` that throws reads as a no. */
+export declare function chooseAttachmentExtractor(extractors: readonly AttachmentExtractor[], contentType: string, filename: string): AttachmentExtractor | undefined;
+/**
+ * Cut `text` to at most `maxBytes` of UTF-8, on a code point boundary.
+ *
+ * Encodes once and backs off over continuation bytes (`10xxxxxx`), so a cut never splits
+ * a multi-byte character into a replacement character at the end of the index.
+ */
+export declare function truncateUtf8(text: string, maxBytes: number): {
+    text: string;
+    truncated: boolean;
+};
+/**
+ * Whitespace collapsed, control characters dropped, line structure kept.
+ *
+ * For the index whitespace is noise, and for the cap it is worse: a spreadsheet's padding
+ * or an HTML file's indentation would spend the per-attachment budget on nothing.
+ */
+export declare function normalizeExtractedText(text: string): string;
+/**
+ * Run one extractor and turn whatever it does into an outcome the kernel can record: the
+ * time budget, the throw, the shape and the output cap, all judged here, after it returns.
+ * See this file's header for what the budget can and cannot stop.
+ */
+export declare function runAttachmentExtractor(extractor: AttachmentExtractor, input: {
+    body: Uint8Array;
+    contentType: string;
+    filename: string;
+}, bounds?: AttachmentTextBounds): Promise<ExtractionOutcome>;
+//# sourceMappingURL=attachment-extractor.d.ts.map

package/dist/attachment-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment-extractor.d.ts","sourceRoot":"","sources":["../src/attachment-extractor.ts"],"names":[],"mappings":"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"}

package/dist/attachment-extractor.js

@@ -0,0 +1,230 @@
+/**
+ * The attachment extractor seam (#1575, K-43): where file formats stop and text begins.
+ *
+ * **The kernel indexes attachment text; it does not parse file formats** (K-43). Every
+ * parser — text and HTML decoding, the zip reader and its inflate budget, DOCX/XLSX/PPTX,
+ * and later PDF and OCR — lives behind this seam in a host-side package
+ * (`@substrat-run/attachment-extractors`), which neither the kernel nor an adapter imports.
+ * Whoever constructs the host passes the extractors in; a host given none records every
+ * type `unsupported`, with that reason, which is a valid configuration rather than a broken
+ * one. `lint:deps` refuses an import of that package from the kernel or an adapter.
+ *
+ * The parsers are the riskiest code in the feature — a zip reader exists to be handed hostile
+ * input — so this file holds them to the guarantees that protect the SCOPE, whatever an
+ * extractor does:
+ *
+ * - **Declarations are checked when the host is built** (`assertAttachmentExtractors`): a
+ *   name, `accepts` and `extract`, and a `maxInputBytes` that is a positive integer if it is
+ *   given at all. A host refuses a list it could not honour rather than misreading it later.
+ * - **The input bound is judged before a byte is fetched**, on the RECORDED size: the kernel's
+ *   ceiling FIRST and on its own, then the extractor's declared bound if it is a valid one.
+ *   Neither can widen the other — a declaration that slipped past the check (a `NaN`) is
+ *   ignored, never allowed to disable the ceiling.
+ * - **A throw is an outcome, not a retry.** An extractor that throws records `failed`, so a
+ *   file that crashes its parser cannot fail its job forever. The thrown message is NOT
+ *   recorded: it is the parser's text, and it may quote the file.
+ * - **The result is validated.** Anything but exactly one of `{ text }` or `{ failed }` is
+ *   `failed`.
+ * - **The output cap is enforced here, after the extractor returns** — normalized, then cut to
+ *   `maxTextBytes` of UTF-8 on a code point boundary and recorded `truncated`. An extractor
+ *   is told the cap as a hint (so it can stop reading early) and cannot exceed it.
+ *
+ * ## The time budget is cooperative, and what that means
+ *
+ * An extractor that has not answered within `timeoutMs` is recorded `failed`, its `signal` is
+ * aborted, and anything it answers afterwards is DISCARDED — including an answer that arrives
+ * "late" because the extractor never yielded: after it returns, the kernel gives the timer the
+ * turn it was owed, and a result the deadline passed is never indexed.
+ *
+ * What the kernel cannot do from inside one isolate is STOP code that does not yield. A
+ * synchronous loop holds the thread until it returns, timer or not; the abort is a request,
+ * honoured by an extractor that checks its `signal` and yields between units of work (the
+ * bundled parsers do, every 64 KiB). So the guarantee is: a cooperative extractor stops
+ * promptly, an uncooperative one cannot get its late answer indexed, and only the runtime's
+ * own CPU limit ends it sooner. A hard deadline on uncooperative code needs process or
+ * isolate isolation — a host can provide it by running its extractors in a separate worker
+ * and handing the kernel a thin extractor that calls it. Under K-43 an extractor is
+ * HOST-supplied code, trusted as the host is; the budget protects the scope from a slow or
+ * broken parser, not from a hostile one, and the bundled parsers bound their own CPU by
+ * construction (linear scans under fixed input caps — their package says how far).
+ */
+/**
+ * The defaults. `maxTextBytes` is 512 KiB of UTF-8 — a few hundred pages of prose, and a
+ * quarter of the ~2 MB a Durable Object row holds. 32 MiB of input is what a Worker can hold
+ * as bytes beside what it decodes from them.
+ */
+export const DEFAULT_ATTACHMENT_TEXT_BOUNDS = {
+    maxInputBytes: 32 * 1024 * 1024,
+    maxTextBytes: 512 * 1024,
+    timeoutMs: 30_000,
+};
+/** A bound that means something: a positive integer. `NaN`, `Infinity`, `0`, `-1` and `'8'` do not. */
+export function isPositiveIntegerBound(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value > 0;
+}
+/** `Text/Plain; charset=UTF-8` → `text/plain`. */
+export function mediaTypeOf(contentType) {
+    return (contentType.split(';')[0] ?? '').trim().toLowerCase();
+}
+/** Refuse bounds the kernel could not honour: each must be a positive integer. */
+export function assertAttachmentTextBounds(bounds) {
+    for (const key of ['maxInputBytes', 'maxTextBytes', 'timeoutMs']) {
+        if (!isPositiveIntegerBound(bounds[key])) {
+            throw new Error(`attachment text bound ${key} must be a positive integer, not ${String(bounds[key])}`);
+        }
+    }
+}
+/**
+ * Refuse, when the host is built, an extractor list it could not honour: a missing or
+ * repeated name, an `accepts` or `extract` that is not a function, or a `maxInputBytes` that
+ * is not a positive integer. Failing here, once, is the alternative to misreading the
+ * declaration on every job.
+ */
+export function assertAttachmentExtractors(extractors) {
+    const seen = new Set();
+    for (const e of extractors) {
+        if (typeof e?.name !== 'string' || !/^[a-z0-9][a-z0-9._-]{0,63}$/.test(e.name)) {
+            throw new Error(`attachment extractor name '${String(e?.name)}' is not a short lowercase identifier`);
+        }
+        if (typeof e.accepts !== 'function' || typeof e.extract !== 'function') {
+            throw new Error(`attachment extractor '${e.name}' must have accepts() and extract()`);
+        }
+        if (e.maxInputBytes !== undefined && !isPositiveIntegerBound(e.maxInputBytes)) {
+            throw new Error(`attachment extractor '${e.name}' declares maxInputBytes ${String(e.maxInputBytes)}, ` +
+                'which is not a positive integer');
+        }
+        if (seen.has(e.name))
+            throw new Error(`attachment extractor '${e.name}' is registered twice`);
+        seen.add(e.name);
+    }
+}
+/**
+ * Why a file of `size` bytes may not be handed to `extractor`, or null when it may.
+ *
+ * The kernel's ceiling is judged FIRST and on its own, then the extractor's declaration —
+ * and only a valid declaration, so one that slipped past `assertAttachmentExtractors` can
+ * narrow nothing and widen nothing. Never a `Math.min` over the two: a `NaN` there makes every
+ * comparison false, which is the ceiling switched off.
+ */
+export function inputBoundRefusal(size, extractor, bounds) {
+    if (!(size <= bounds.maxInputBytes)) {
+        return `the file is ${size} bytes, over the ${bounds.maxInputBytes}-byte input bound`;
+    }
+    const declared = extractor.maxInputBytes;
+    if (isPositiveIntegerBound(declared) && size > declared) {
+        return `the file is ${size} bytes, over the extractor's ${declared}-byte input bound`;
+    }
+    return null;
+}
+/** The first extractor that reads this file, or none. An `accepts` that throws reads as a no. */
+export function chooseAttachmentExtractor(extractors, contentType, filename) {
+    return extractors.find((e) => {
+        try {
+            return e.accepts(contentType, filename) === true;
+        }
+        catch {
+            return false;
+        }
+    });
+}
+const utf8 = new TextEncoder();
+/**
+ * Cut `text` to at most `maxBytes` of UTF-8, on a code point boundary.
+ *
+ * Encodes once and backs off over continuation bytes (`10xxxxxx`), so a cut never splits
+ * a multi-byte character into a replacement character at the end of the index.
+ */
+export function truncateUtf8(text, maxBytes) {
+    const bytes = utf8.encode(text);
+    if (bytes.length <= maxBytes)
+        return { text, truncated: false };
+    let cut = maxBytes;
+    while (cut > 0 && (bytes[cut] & 0xc0) === 0x80)
+        cut -= 1;
+    return { text: new TextDecoder('utf-8').decode(bytes.subarray(0, cut)), truncated: true };
+}
+/**
+ * Whitespace collapsed, control characters dropped, line structure kept.
+ *
+ * For the index whitespace is noise, and for the cap it is worse: a spreadsheet's padding
+ * or an HTML file's indentation would spend the per-attachment budget on nothing.
+ */
+export function normalizeExtractedText(text) {
+    return text
+        .replace(/\r\n?/g, '\n')
+        // C0 controls other than tab and newline, DEL, and the C1 range.
+        .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/g, '')
+        .replace(/[ \t ]+/g, ' ')
+        .replace(/ *\n */g, '\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+/** One turn of the event loop — a macrotask, so a due timer runs before what follows. */
+const nextTurn = () => new Promise((resolve) => setTimeout(resolve, 0));
+const TIMED_OUT = Symbol('timed out');
+/** A recorded reason is short: an extractor's `failed` is cut, never trusted to be. */
+const DETAIL_MAX = 500;
+/**
+ * Run one extractor and turn whatever it does into an outcome the kernel can record: the
+ * time budget, the throw, the shape and the output cap, all judged here, after it returns.
+ * See this file's header for what the budget can and cannot stop.
+ */
+export async function runAttachmentExtractor(extractor, input, bounds = DEFAULT_ATTACHMENT_TEXT_BOUNDS) {
+    const failed = (detail) => ({
+        status: 'failed',
+        extractor: extractor.name,
+        detail: detail.slice(0, DETAIL_MAX),
+    });
+    const timeout = failed(`extractor '${extractor.name}' did not answer within ${bounds.timeoutMs} ms`);
+    const controller = new AbortController();
+    let timedOut = false;
+    let onTimeout = () => { };
+    const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+        onTimeout(TIMED_OUT);
+    }, bounds.timeoutMs);
+    // Called inside a promise chain, so a synchronous throw lands in the catch below too. Its
+    // eventual rejection is handled here, so an extractor abandoned at the deadline that fails
+    // later cannot surface as an unhandled rejection.
+    const work = Promise.resolve().then(() => extractor.extract({ ...input, maxTextBytes: bounds.maxTextBytes, signal: controller.signal }));
+    work.catch(() => { });
+    let result;
+    let threw = undefined;
+    let didThrow = false;
+    try {
+        result = await Promise.race([work, new Promise((resolve) => (onTimeout = resolve))]);
+    }
+    catch (err) {
+        didThrow = true;
+        threw = err;
+    }
+    // A SYNCHRONOUS extractor returns before its timer can run, however long it took. Give the
+    // timer the turn it was owed: if the deadline passed meanwhile, the answer is discarded.
+    if (!timedOut)
+        await nextTurn();
+    clearTimeout(timer);
+    if (timedOut || result === TIMED_OUT)
+        return timeout;
+    if (didThrow) {
+        // The message is the parser's text and may quote the file; only its kind is recorded.
+        const kind = threw instanceof Error && /^[A-Za-z][\w$]{0,63}$/.test(threw.name) ? threw.name : 'a value';
+        return failed(`extractor '${extractor.name}' threw (${kind})`);
+    }
+    const r = result;
+    if (r !== null && typeof r === 'object' && typeof r.failed === 'string' && !('text' in r))
+        return failed(r.failed);
+    if (r === null ||
+        typeof r !== 'object' ||
+        typeof r.text !== 'string' ||
+        // Both answers at once is no answer: neither half can be trusted over the other.
+        'failed' in r ||
+        (r.truncated !== undefined && typeof r.truncated !== 'boolean')) {
+        return failed(`extractor '${extractor.name}' returned an unreadable result`);
+    }
+    const cut = truncateUtf8(normalizeExtractedText(r.text), bounds.maxTextBytes);
+    if (cut.text.length === 0)
+        return { status: 'empty', extractor: extractor.name };
+    return { status: 'indexed', extractor: extractor.name, text: cut.text, truncated: cut.truncated || r.truncated === true };
+}
+//# sourceMappingURL=attachment-extractor.js.map

package/dist/attachment-extractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment-extractor.js","sourceRoot":"","sources":["../src/attachment-extractor.ts"],"names":[],"mappings":"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"}