@poe-platform/safe-bash 0.1.817 → 0.1.818

package/dist/spreadsheet-format-xls/biff-properties-merge.js

@@ -1,3 +1,5 @@
+import { BiffPropertyNames } from './biff-property-names.js';
+import { BiffOriginalProperties } from './biff-property-observations.js';
 import { BiffMutablePropertyValues } from './biff-property-values.js';
 import { createBiffPropertyNameEncoder } from "./biff-property-name.js";
 import { readBiffPropertyText } from "./biff-property-text.js";
@@ -8,10 +10,9 @@ import { Binary, invalidBiff } from "./biff-binary.js";
 import { biffPropertyFields, biffPropertyFormats, readBiffProperties } from "./biff-properties.js";
 import { propertyRange, readPropertySectionRanges, withPropertyValueRanges } from "./biff-property-range.js";
 /** Rebuild offsets around original opaque spans. Never transcode their codepage. */
-export async function mergeBiffProperties(book, streams, handled, context, charge, allocate, staged) {
+export async function mergeBiffProperties(book, streams, handled, context, charge, allocate, staged, preserved) {
     const canonical = (name) => ["\u0005SummaryInformation", "\u0005DocumentSummaryInformation"].find(target => target.toUpperCase() === name.toUpperCase());
     const snapshots = new Map(), duplicates = new Set();
-    const preserved = new Set();
     let nodes = 0, textBytes = 0;
     const admit = (amount) => {
         charge(amount);
@@ -85,7 +86,7 @@ export async function mergeBiffProperties(book, streams, handled, context, charg
         for (const name of duplicates)
             snapshots.delete(name);
         if (!snapshots.size)
-            return preserved;
+            return;
         const parse = async (input) => {
             const file = propertyRange(input, context), sections = [];
             for await (const section of readPropertySectionRanges(file, admit, charge, context)) {
@@ -117,12 +118,22 @@ export async function mergeBiffProperties(book, streams, handled, context, charg
             }
             return new Binary(bytes);
         };
-        const original = new Map(), pending = new Map();
-        const identity = (property) => `${property.stream}:${property.section}:${property.id}`;
+        const same = (a, b) => {
+            if (!Array.isArray(a) || !Array.isArray(b))
+                return Object.is(a, b);
+            charge(a.length + b.length);
+            return a.length === b.length && a.every((value, i) => Object.is(value, b[i]));
+        };
+        const original = new BiffOriginalProperties(context, charge), pending = new Map();
+        temporarySources.push(original);
         const readContext = { ...context, limits: { ...context.limits, inputBytes: context.limits.outputBytes } };
         // Reuse scalar decoding, but do not create another retained hexadecimal copy.
-        await readBiffProperties(new Map([...snapshots].map(([name, value]) => [name, value.bytes])), readContext, accountText, charge, undefined, property => { admit(1); original.set(identity(property), property); }, false);
-        await readBiffProperties(streams, readContext, accountText, charge, undefined, property => { admit(1); pending.set(property.key, property); }, false);
+        await readBiffProperties(new Map([...snapshots].map(([name, value]) => [name, value.bytes])), readContext, accountText, charge, undefined, async (property) => {
+            admit(1);
+            const { stream, section, id, key } = property;
+            await original.add({ stream, section, id, key, unchanged: same(property.value, book.properties?.[key]) });
+        }, false);
+        await readBiffProperties(streams, readContext, accountText, charge, undefined, property => { admit(1); const { stream, section, id, key } = property; pending.set(key, { stream, section, id, key }); }, false);
         const chunks = async function* (source) {
             for (let at = 0; at < source.size;) {
                 const bytes = await source.read(at, source.size - at);
@@ -232,48 +243,43 @@ export async function mergeBiffProperties(book, streams, handled, context, charg
                 view.setUint16(8 + i * 2, value.charCodeAt(i), true);
             return propertyRange(bytes, context);
         };
-        const same = (a, b) => {
-            if (!Array.isArray(a) || !Array.isArray(b))
-                return Object.is(a, b);
-            charge(a.length + b.length);
-            return a.length === b.length && a.every((value, i) => Object.is(value, b[i]));
-        };
         for (const [name, snapshot] of snapshots) {
-            const seen = new Set();
-            function* modeled() {
+            const seen = new BiffPropertyNames(context, charge);
+            temporarySources.push(seen);
+            async function* modeled() {
                 if (snapshot.modeled) {
                     yield* snapshot.modeled;
                     return;
                 }
                 // SummaryInformation is read first. A legacy document-only snapshot lacks
                 // that earlier stream's ownership decisions: infer only unchanged values.
-                for (const property of original.values()) {
+                for await (const property of original.values()) {
                     charge(1);
                     if (property.stream !== name)
                         continue;
                     if (name === "\u0005SummaryInformation" || snapshots.has("\u0005SummaryInformation") ||
-                        Object.hasOwn(book.properties ?? {}, property.key) && same(property.value, book.properties?.[property.key])) {
+                        Object.hasOwn(book.properties ?? {}, property.key) && property.unchanged) {
                         admit(1);
                         yield [property.section, property.id, property.key];
                     }
                 }
             }
-            for (const entry of modeled()) {
+            for await (const entry of modeled()) {
                 admit(1);
                 if (!Array.isArray(entry) || entry.length !== 3 || typeof entry[0] !== "number" || typeof entry[1] !== "number" || typeof entry[2] !== "string")
                     invalidBiff("invalid retained property identity");
                 const [offset, id, key] = entry;
-                const property = original.get(identity({ stream: name, section: offset, id }));
-                if (!property || property.key !== key || seen.has(key))
+                const property = await original.get(name, offset, id);
+                if (!property || property.key !== key || await seen.has(key))
                     invalidBiff("invalid retained property identity");
-                seen.add(key);
+                await seen.add(key);
                 charge(old.get(name).length);
                 const section = old.get(name).find(section => section.offset === offset);
-                const value = book.properties?.[key], replacement = pending.get(key);
+                const replacement = pending.get(key);
                 if (!Object.hasOwn(book.properties ?? {}, key))
                     await remove(section, id);
-                else if (same(property.value, value)) {
-                    preserved.add(key);
+                else if (property.unchanged) {
+                    await preserved?.add(key);
                     if (replacement)
                         await take(replacement);
                 }
@@ -451,13 +457,14 @@ export async function mergeBiffProperties(book, streams, handled, context, charg
             if (snapshot)
                 handled.add(snapshot.record);
         }
-        const exposed = new Set();
-        await readBiffProperties(staged?.sources ?? streams, readContext, accountText, charge, undefined, property => {
+        const exposed = new BiffPropertyNames(context, charge);
+        temporarySources.push(exposed);
+        await readBiffProperties(staged?.sources ?? streams, readContext, accountText, charge, undefined, async (property) => {
             admit(1);
             if (!Object.hasOwn(book.properties ?? {}, property.key))
-                exposed.add(property.key);
+                await exposed.add(property.key);
         }, false);
-        for (const key of exposed)
+        for await (const key of exposed.values())
             await warn(key, "opaque property exposes a field absent from the model");
     }
     catch (error) {
@@ -470,5 +477,4 @@ export async function mergeBiffProperties(book, streams, handled, context, charg
         throw error;
     }
     await closeTemporary();
-    return preserved;
 }

package/dist/spreadsheet-format-xls/biff-properties-write.js

@@ -1,3 +1,4 @@
+import { BiffPropertyNames } from "./biff-property-names.js";
 import { propertyChunks, stagePropertyBytes } from "./biff-property-bytes.js";
 import { SsconvertError } from "../spreadsheet-engine/contracts.js";
 import { biffPropertyFields, biffPropertyFormats, isBiffKeywordSpace } from "./biff-properties.js";
@@ -6,7 +7,7 @@ const fieldByName = new Map([...biffPropertyFields].flatMap(([guid, fields]) =>
 const maximumFileTime = 0xffffffffffffffffn;
 /** Only discard a generic loss report when every XML field has been handled.
  * Keep the original record on the caller's workbook, including unknown content. */
-function handledPropertyRecord(record, keys, charge) {
+function handledPropertyRecord(record, properties, charge) {
     if (record.disposition !== "retained" || record.source !== "Gnumeric_XmlIO:sax" || record.kind !== "document-meta")
         return false;
     const office = "urn:oasis:names:tc:opendocument:xmlns:office:1.0", meta = "urn:oasis:names:tc:opendocument:xmlns:meta:1.0";
@@ -85,7 +86,7 @@ function handledPropertyRecord(record, keys, charge) {
                 return false;
         }
         const keyword = field.namespace === meta && field.name === "keyword";
-        if (key === undefined || !keys.has(key) || seen.has(key) && !(keyword && seen.get(key)))
+        if (key === undefined || !Object.prototype.propertyIsEnumerable.call(properties ?? {}, key) || seen.has(key) && !(keyword && seen.get(key)))
             return false;
         seen.set(key, keyword);
     }
@@ -141,7 +142,6 @@ function durationTicks(text) {
 }
 export async function writeBiffProperties(book, context, staged = false) {
     const planned = new Map(), sections = new Map();
-    const handledKeys = new Set();
     const unsupportedKeys = [];
     let work = 0, textBytes = 0, nodes = 0, payloadBytes = 0;
     const charge = (amount) => {
@@ -275,7 +275,6 @@ export async function writeBiffProperties(book, context, staged = false) {
             if (++nodes > (context.limits.workbookNodes ?? context.limits.outputBytes))
                 throw new SsconvertError("resource-limit", "ssconvert BIFF property node limit exceeded");
             const field = fieldByName.get(key);
-            handledKeys.add(key);
             let source = book.properties[key];
             if (key === "dc:keywords" && Array.isArray(source)) {
                 charge(source.length);
@@ -318,7 +317,7 @@ export async function writeBiffProperties(book, context, staged = false) {
     const handledMetadata = new Set();
     for (const record of book.unsupportedRecords ?? []) {
         charge(1);
-        if (handledPropertyRecord(record, handledKeys, charge))
+        if (handledPropertyRecord(record, book.properties, charge))
             handledMetadata.add(record);
     }
     if (names.length) {
@@ -399,6 +398,7 @@ export async function writeBiffProperties(book, context, staged = false) {
     const snapshots = (book.unsupportedRecords ?? []).some(record => record.source === "biff" && record.kind === "ole-properties" && record.disposition === "retained");
     const streams = new Map(), inputs = [];
     const sources = new Map();
+    let preserved;
     const close = async () => {
         const errors = [];
         for (const source of [...sources.values(), ...inputs])
@@ -408,6 +408,12 @@ export async function writeBiffProperties(book, context, staged = false) {
             catch (error) {
                 errors.push(error);
             }
+        try {
+            await preserved?.close();
+        }
+        catch (error) {
+            errors.push(error);
+        }
         if (errors.length === 1)
             throw errors[0];
         if (errors.length)
@@ -431,10 +437,13 @@ export async function writeBiffProperties(book, context, staged = false) {
                     streams.set(name, bytes);
                 }
             }
-        const preserved = await mergeBiffProperties(book, streams, handledMetadata, context, charge, allocate, staged ? { sources, reserve } : undefined);
+        if (snapshots && unsupportedKeys.length)
+            preserved = new BiffPropertyNames(context, charge);
+        await mergeBiffProperties(book, streams, handledMetadata, context, charge, allocate, staged ? { sources, reserve } : undefined, preserved);
         for (const key of unsupportedKeys)
-            if (!preserved.has(key))
+            if (!await preserved?.has(key))
                 await context.diagnostic?.({ code: "biff-loss-warning", severity: "warning", message: `Unsupported Excel BIFF document property: ${key}` });
+        await preserved?.close();
         if (!staged)
             return { streams, handledMetadata, async close() { } };
         for (const [name, value] of snapshots ? streams : planned)

package/dist/spreadsheet-format-xls/biff-property-names.d.ts

@@ -8,6 +8,8 @@ export declare class BiffPropertyNames {
     private readonly index;
     private readonly fallback;
     private initialized;
+    private first;
+    private last;
     private pending;
     private closed;
     private closing;
@@ -20,5 +22,6 @@ export declare class BiffPropertyNames {
     private contains;
     has(name: string): Promise<boolean>;
     add(name: string): Promise<void>;
+    values(): AsyncIterable<string>;
     close(): Promise<void>;
 }

package/dist/spreadsheet-format-xls/biff-property-names.js

@@ -10,6 +10,8 @@ export class BiffPropertyNames {
     index;
     fallback;
     initialized = false;
+    first = 0;
+    last = 0;
     pending = Promise.resolve();
     closed = false;
     closing;
@@ -145,7 +147,7 @@ export class BiffPropertyNames {
         finally {
             buffer.fill(0);
         }
-        const record = new Uint8Array(24), descriptor = new DataView(record.buffer);
+        const record = new Uint8Array(32), descriptor = new DataView(record.buffer);
         descriptor.setFloat64(0, Number(head ?? 0n), true);
         descriptor.setFloat64(8, name.length, true);
         descriptor.setFloat64(16, start, true);
@@ -158,6 +160,47 @@ export class BiffPropertyNames {
         }
         await this.index.set(key, BigInt(position));
         this.check();
+        if (this.last) {
+            const link = new Uint8Array(8);
+            new DataView(link.buffer).setFloat64(0, position, true);
+            try {
+                await this.io(() => this.storage.write(this.last + 24, link));
+            }
+            finally {
+                link.fill(0);
+            }
+        }
+        else
+            this.first = position;
+        this.last = position;
+    }
+    async *values() {
+        this.check();
+        if (this.fallback) {
+            for (const name of this.fallback) {
+                this.check();
+                yield name;
+            }
+            return;
+        }
+        let position = this.first;
+        while (position) {
+            const record = new DataView((await this.read(position, 32)).buffer);
+            const length = record.getFloat64(8, true), start = record.getFloat64(16, true);
+            position = record.getFloat64(24, true);
+            this.charge(length + 1);
+            let name = '';
+            for (let at = 0; at < length;) {
+                const count = Math.min(8192, length - at), bytes = await this.read(start + at * 2, count * 2);
+                const view = new DataView(bytes.buffer), units = new Uint16Array(count);
+                for (let i = 0; i < count; i++)
+                    units[i] = view.getUint16(i * 2, true);
+                name += String.fromCharCode(...units);
+                at += count;
+            }
+            yield name;
+        }
+        this.check();
     }
     close() {
         this.closed = true;

package/dist/spreadsheet-format-xls/biff-property-observations.d.ts

@@ -0,0 +1,33 @@
+import { type CapabilityContext } from "../spreadsheet-engine/contracts.js";
+export interface BiffOriginalProperty {
+    stream: string;
+    section: number;
+    id: number;
+    key: string;
+    unchanged: boolean;
+}
+/** Original identities are immutable and arrive once, in import order. Keep only
+ * the comparison result, never decoded property values, in caller-backed records. */
+export declare class BiffOriginalProperties {
+    private readonly context;
+    private readonly charge;
+    private readonly storage;
+    private readonly indexes;
+    private readonly fallback;
+    private first;
+    private last;
+    private pending;
+    private closed;
+    private closing;
+    constructor(context: CapabilityContext, charge: (amount: number) => void);
+    private check;
+    private allocate;
+    private io;
+    private read;
+    private write;
+    add(property: BiffOriginalProperty): Promise<void>;
+    private decode;
+    get(stream: string, section: number, id: number): Promise<BiffOriginalProperty | undefined>;
+    values(): AsyncIterable<BiffOriginalProperty>;
+    close(): Promise<void>;
+}

package/dist/spreadsheet-format-xls/biff-property-observations.js

@@ -0,0 +1,160 @@
+import { IntegerTable } from "@poe-platform/safe-fs/storage";
+import { SsconvertError } from "../spreadsheet-engine/contracts.js";
+const streams = ['\u0005SummaryInformation', '\u0005DocumentSummaryInformation'];
+/** Original identities are immutable and arrive once, in import order. Keep only
+ * the comparison result, never decoded property values, in caller-backed records. */
+export class BiffOriginalProperties {
+    context;
+    charge;
+    storage;
+    indexes;
+    fallback;
+    first = 0;
+    last = 0;
+    pending = Promise.resolve();
+    closed = false;
+    closing;
+    constructor(context, charge) {
+        this.context = context;
+        this.charge = charge;
+        this.storage = context.createWorkingStorage?.();
+        if (this.storage) {
+            const backing = { allocate: (length) => this.allocate(length),
+                read: (at, length) => this.read(at, length), write: (at, bytes) => this.write(at, bytes) };
+            this.indexes = streams.map(() => new IntegerTable(backing, 64));
+        }
+        else
+            this.fallback = new Map();
+        context.own(() => this.close());
+    }
+    check() {
+        this.context.signal.throwIfAborted();
+        if (this.closed)
+            throw new SsconvertError('invalid-request', 'BIFF original properties are closed');
+    }
+    allocate(length) { this.check(); const position = this.storage.allocate(length); this.check(); return position; }
+    io(action) {
+        const result = this.pending.then(async () => { this.check(); const value = await action(); this.check(); return value; });
+        this.pending = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    read(at, length) {
+        return this.io(async () => {
+            const bytes = await this.storage.read(at, length);
+            if (bytes.length !== length)
+                throw new SsconvertError('io', 'Truncated BIFF original property index');
+            return new Uint8Array(bytes);
+        });
+    }
+    async write(at, bytes) {
+        const owned = new Uint8Array(bytes);
+        try {
+            await this.io(() => this.storage.write(at, owned));
+        }
+        finally {
+            owned.fill(0);
+        }
+    }
+    async add(property) {
+        this.check();
+        this.charge(1 + property.key.length);
+        const stream = streams.indexOf(property.stream);
+        if (stream < 0 || !Number.isInteger(property.section) || property.section < 0 || property.section > 0xffffffff ||
+            !Number.isInteger(property.id) || property.id < 0 || property.id > 0xffffffff)
+            throw new SsconvertError('invalid-request', 'Invalid BIFF original property identity');
+        if (this.fallback) {
+            const key = `${property.stream}:${property.section}:${property.id}`;
+            if (this.fallback.has(key))
+                throw new SsconvertError('invalid-request', 'Duplicate BIFF original property identity');
+            this.fallback.set(key, { ...property });
+            return;
+        }
+        if (!this.first)
+            this.allocate(8);
+        const key = BigInt(property.section) << 32n | BigInt(property.id), index = this.indexes[stream];
+        if (await index.get(key) !== undefined)
+            throw new SsconvertError('invalid-request', 'Duplicate BIFF original property identity');
+        this.check();
+        const start = this.allocate(property.key.length * 2), buffer = new Uint8Array(Math.min(16384, property.key.length * 2)), view = new DataView(buffer.buffer);
+        try {
+            for (let at = 0; at < property.key.length;) {
+                const count = Math.min(buffer.length / 2, property.key.length - at);
+                for (let i = 0; i < count; i++)
+                    view.setUint16(i * 2, property.key.charCodeAt(at + i), true);
+                await this.write(start + at * 2, buffer.subarray(0, count * 2));
+                at += count;
+            }
+        }
+        finally {
+            buffer.fill(0);
+        }
+        const bytes = new Uint8Array(32), record = new DataView(bytes.buffer);
+        record.setUint32(8, property.section, true);
+        record.setUint32(12, property.id, true);
+        record.setFloat64(16, start, true);
+        record.setUint32(24, property.key.length, true);
+        record.setUint8(28, stream);
+        record.setUint8(29, property.unchanged ? 1 : 0);
+        const position = this.allocate(bytes.length);
+        await this.write(position, bytes);
+        if (this.last) {
+            record.setFloat64(0, position, true);
+            await this.write(this.last, bytes.subarray(0, 8));
+        }
+        else
+            this.first = position;
+        this.last = position;
+        await index.set(key, BigInt(position));
+        this.check();
+    }
+    async decode(record) {
+        const length = record.getUint32(24, true), start = record.getFloat64(16, true);
+        this.charge(length + 1);
+        let key = '';
+        for (let at = 0; at < length;) {
+            const count = Math.min(8192, length - at), bytes = await this.read(start + at * 2, count * 2), view = new DataView(bytes.buffer);
+            const units = new Uint16Array(count);
+            for (let i = 0; i < count; i++)
+                units[i] = view.getUint16(i * 2, true);
+            key += String.fromCharCode(...units);
+            at += count;
+        }
+        return { stream: streams[record.getUint8(28)], section: record.getUint32(8, true), id: record.getUint32(12, true), key, unchanged: record.getUint8(29) !== 0 };
+    }
+    async get(stream, section, id) {
+        this.check();
+        this.charge(1);
+        if (!Number.isInteger(section) || section < 0 || section > 0xffffffff || !Number.isInteger(id) || id < 0 || id > 0xffffffff)
+            return undefined;
+        if (this.fallback)
+            return this.fallback.get(`${stream}:${section}:${id}`);
+        const index = this.indexes[streams.indexOf(stream)];
+        if (!index)
+            return undefined;
+        const position = await index.get(BigInt(section) << 32n | BigInt(id));
+        this.check();
+        return position === undefined ? undefined : this.decode(new DataView((await this.read(Number(position), 32)).buffer));
+    }
+    async *values() {
+        this.check();
+        if (this.fallback) {
+            for (const property of this.fallback.values()) {
+                this.check();
+                yield property;
+            }
+            return;
+        }
+        let position = this.first;
+        while (position) {
+            const record = new DataView((await this.read(position, 32)).buffer);
+            position = record.getFloat64(0, true);
+            yield await this.decode(record);
+        }
+        this.check();
+    }
+    close() {
+        this.closed = true;
+        this.fallback?.clear();
+        return this.closing ??= this.pending.then(async () => { await this.storage?.close(); });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poe-platform/safe-bash",
-  "version": "0.1.817",
+  "version": "0.1.818",
   "description": "Extensible virtual shell with pluggable filesystems and streaming commands",
   "type": "module",
   "license": "MIT",
@@ -1407,14 +1407,14 @@
     "access": "public"
   },
   "dependencies": {
-    "@poe-platform/safe-fs": "0.1.817",
+    "@poe-platform/safe-fs": "0.1.818",
     "pdf-lib": "1.17.1",
     "@types/node": "^25.2.2",
     "@formatjs/intl-numberformat": "9.4.0",
     "@petamoriken/float16": "^3.9.3",
     "@noble/hashes": "2.4.0",
-    "@noble/ciphers": "2.4.0",
     "pako": "3.0.1",
+    "@noble/ciphers": "2.4.0",
     "@kayahr/text-encoding": "^2.2.0",
     "@sqlite.org/sqlite-wasm": "3.50.4-build1",
     "parse5": "7.3.0",
@@ -1556,6 +1556,7 @@
     "./dist/office-package/zip-source.js",
     "./dist/office-package/zip-write-storage.js",
     "./dist/office-package/zip.js",
+    "./dist/pdf-ast/image.js",
     "./dist/pdf-ast/index.js",
     "./dist/pdf-ast/vendor/pdfjs-fonts.mjs",
     "./dist/safe-bash-base-encoding-engine/base.js",
@@ -2600,6 +2601,7 @@
     "./dist/spreadsheet-engine/engine.js",
     "./dist/spreadsheet-engine/formatting.js",
     "./dist/spreadsheet-engine/formatting/cell-text.js",
+    "./dist/spreadsheet-engine/formatting/general-number.js",
     "./dist/spreadsheet-engine/formatting/locale.js",
     "./dist/spreadsheet-engine/formatting/number-format.js",
     "./dist/spreadsheet-engine/formatting/numeric.js",
@@ -2742,7 +2744,6 @@
     "./dist/spreadsheet-engine/rendering/print/font-normalization.js",
     "./dist/spreadsheet-engine/rendering/print/font-shaping.js",
     "./dist/spreadsheet-engine/rendering/print/formula-text.js",
-    "./dist/spreadsheet-engine/rendering/print/general-number.js",
     "./dist/spreadsheet-engine/rendering/print/harfbuzz/data.js",
     "./dist/spreadsheet-engine/rendering/print/header-footer.js",
     "./dist/spreadsheet-engine/rendering/print/hyphen-scripts.js",
@@ -2844,6 +2845,7 @@
     "./dist/spreadsheet-format-xls/biff-property-index.js",
     "./dist/spreadsheet-format-xls/biff-property-name.js",
     "./dist/spreadsheet-format-xls/biff-property-names.js",
+    "./dist/spreadsheet-format-xls/biff-property-observations.js",
     "./dist/spreadsheet-format-xls/biff-property-range.js",
     "./dist/spreadsheet-format-xls/biff-property-text.js",
     "./dist/spreadsheet-format-xls/biff-property-transcode.js",

package/third-party/pdf-ast/THIRD_PARTY_NOTICES.md

@@ -601,3 +601,18 @@ uses the converted structure directly. Type1 parsing admits lexer token growth,
 decryption buffers, CID glyph/offset tables, fallback glyph copies, and every
 recursive charstring conversion before allocation. Skipped comments do not
 reserve token-sized buffers.
+
+# Python / V8 stable sorting
+
+`src/extract/text-sort.ts` adapts the TimSort implementation in V8
+14.6.202.34 (`third_party/v8/builtins/array-sort.tq`), derived from Python.
+Copyright (c) 2001–2018 Python Software Foundation; all rights reserved.
+V8 contributions are copyright the V8 project authors. See
+`licenses/PYTHON-PSF.txt` and `licenses/V8-BSD.txt` for the respective terms.
+
+The adaptation replaces resident work and temporary arrays with resumable
+record-read, record-write and comparison requests. Scalar run state and the
+comparison decisions are retained; allocation, I/O and cancellation belong to
+the driver.
+
+Source: https://github.com/v8/v8/blob/14.6.202.34/third_party/v8/builtins/array-sort.tq