@kduma-oss/pcf 0.0.1

package/dist/index.js

@@ -0,0 +1,42 @@
+/**
+ * # `pcf` — Partitioned Container Format (TypeScript implementation)
+ *
+ * A language-agnostic binary container that stores multiple independent regions
+ * of bytes ("partitions") in a single file. This package mirrors the written
+ * specification (`PCF-spec-v1.0.txt`) and the Rust reference implementation
+ * field-for-field and favours auditability over performance.
+ *
+ * ## Layout at a glance
+ *
+ * ```text
+ * [ 20-byte header ] [ table block(s) ] [ partition data regions ]
+ * ```
+ *
+ * All integers are little-endian. Free space is derived as
+ * `maxLength - usedBytes`.
+ *
+ * ## Example
+ *
+ * ```ts
+ * import { Container, HashAlgo } from "pcf";
+ *
+ * const c = Container.create();
+ * const uid = new Uint8Array(16).fill(1);
+ * c.addPartition(0x10, uid, "notes", new TextEncoder().encode("hello world"), 64, HashAlgo.Sha256);
+ *
+ * c.verify();
+ * const entries = c.entries();
+ * console.log(new TextDecoder().decode(c.readPartitionData(entries[0]))); // "hello world"
+ * ```
+ */
+export * from "./consts.js";
+export { PcfError, PcfErrorKind } from "./errors.js";
+export { HashAlgo, hashAlgoFromId, hashAlgoId, digestLen, verifies, computeHashField, verifyHashField, } from "./hash.js";
+export { crc32, crc32c, crc64 } from "./crc.js";
+export { headerToBytes, headerFromBytes, } from "./header.js";
+export { entryToBytes, entryFromBytes, validateEntry, freeBytes, entryLabelString, encodeLabel, decodeLabel, } from "./entry.js";
+export { tableHeaderToBytes, tableHeaderFromBytes, computeTableHash, } from "./table.js";
+export { MemoryStorage } from "./storage.js";
+export { NodeFileStorage } from "./node-storage.js";
+export { Container } from "./container.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EACL,QAAQ,EACR,cAAc,EACd,UAAU,EACV,SAAS,EACT,QAAQ,EACR,gBAAgB,EAChB,eAAe,GAChB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EAEL,aAAa,EACb,eAAe,GAChB,MAAM,aAAa,CAAC;AACrB,OAAO,EAEL,YAAY,EACZ,cAAc,EACd,aAAa,EACb,SAAS,EACT,gBAAgB,EAChB,WAAW,EACX,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,OAAO,EAEL,kBAAkB,EAClB,oBAAoB,EACpB,gBAAgB,GACjB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAgB,aAAa,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAkB,MAAM,gBAAgB,CAAC"}

package/dist/node-storage.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A {@link Storage} implementation backed by a Node file descriptor, the
+ * analogue of using `std::fs::File` with the reference implementation.
+ *
+ * This module imports `node:fs` and is therefore Node-only; the rest of the
+ * library is runtime-agnostic.
+ */
+import type { Storage } from "./storage.js";
+/** File-descriptor backed random-access storage. */
+export declare class NodeFileStorage implements Storage {
+    private fd;
+    private constructor();
+    /**
+     * Open `path` for reading and writing, creating it if necessary (mode
+     * `"r+"`-like with creation). Use `truncate` to start from an empty file.
+     */
+    static open(path: string, truncate?: boolean): NodeFileStorage;
+    readAt(offset: number, length: number): Uint8Array;
+    writeAt(offset: number, data: Uint8Array): void;
+    size(): number;
+    /** Close the underlying file descriptor. */
+    close(): void;
+}
+//# sourceMappingURL=node-storage.d.ts.map

package/dist/node-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-storage.d.ts","sourceRoot":"","sources":["../src/node-storage.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAUH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,oDAAoD;AACpD,qBAAa,eAAgB,YAAW,OAAO;IAC7C,OAAO,CAAC,EAAE,CAAS;IAEnB,OAAO;IAIP;;;OAGG;IACH,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,UAAQ,GAAG,eAAe;IAO5D,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU;IAelD,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,IAAI;IAc/C,IAAI,IAAI,MAAM;IAId,4CAA4C;IAC5C,KAAK,IAAI,IAAI;CAGd"}

package/dist/node-storage.js

@@ -0,0 +1,52 @@
+/**
+ * A {@link Storage} implementation backed by a Node file descriptor, the
+ * analogue of using `std::fs::File` with the reference implementation.
+ *
+ * This module imports `node:fs` and is therefore Node-only; the rest of the
+ * library is runtime-agnostic.
+ */
+import { closeSync, fstatSync, openSync, readSync, writeSync, } from "node:fs";
+/** File-descriptor backed random-access storage. */
+export class NodeFileStorage {
+    fd;
+    constructor(fd) {
+        this.fd = fd;
+    }
+    /**
+     * Open `path` for reading and writing, creating it if necessary (mode
+     * `"r+"`-like with creation). Use `truncate` to start from an empty file.
+     */
+    static open(path, truncate = false) {
+        // "w+" truncates+creates for read/write; "a+"/"r+" otherwise.
+        const flags = truncate ? "w+" : "a+";
+        const fd = openSync(path, flags);
+        return new NodeFileStorage(fd);
+    }
+    readAt(offset, length) {
+        const buf = new Uint8Array(length);
+        let read = 0;
+        while (read < length) {
+            const n = readSync(this.fd, buf, read, length - read, offset + read);
+            if (n === 0) {
+                throw new Error(`unexpected EOF: wanted ${length} bytes at offset ${offset}`);
+            }
+            read += n;
+        }
+        return buf;
+    }
+    writeAt(offset, data) {
+        let written = 0;
+        while (written < data.length) {
+            const n = writeSync(this.fd, data, written, data.length - written, offset + written);
+            written += n;
+        }
+    }
+    size() {
+        return fstatSync(this.fd).size;
+    }
+    /** Close the underlying file descriptor. */
+    close() {
+        closeSync(this.fd);
+    }
+}
+//# sourceMappingURL=node-storage.js.map

package/dist/node-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-storage.js","sourceRoot":"","sources":["../src/node-storage.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,SAAS,EACT,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,SAAS,GACV,MAAM,SAAS,CAAC;AAIjB,oDAAoD;AACpD,MAAM,OAAO,eAAe;IAClB,EAAE,CAAS;IAEnB,YAAoB,EAAU;QAC5B,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;IACf,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,IAAI,CAAC,IAAY,EAAE,QAAQ,GAAG,KAAK;QACxC,8DAA8D;QAC9D,MAAM,KAAK,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;QACrC,MAAM,EAAE,GAAG,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACjC,OAAO,IAAI,eAAe,CAAC,EAAE,CAAC,CAAC;IACjC,CAAC;IAED,MAAM,CAAC,MAAc,EAAE,MAAc;QACnC,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;QACnC,IAAI,IAAI,GAAG,CAAC,CAAC;QACb,OAAO,IAAI,GAAG,MAAM,EAAE,CAAC;YACrB,MAAM,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;YACrE,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;gBACZ,MAAM,IAAI,KAAK,CACb,0BAA0B,MAAM,oBAAoB,MAAM,EAAE,CAC7D,CAAC;YACJ,CAAC;YACD,IAAI,IAAI,CAAC,CAAC;QACZ,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,OAAO,CAAC,MAAc,EAAE,IAAgB;QACtC,IAAI,OAAO,GAAG,CAAC,CAAC;QAChB,OAAO,OAAO,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YAC7B,MAAM,CAAC,GAAG,SAAS,CACjB,IAAI,CAAC,EAAE,EACP,IAAI,EACJ,OAAO,EACP,IAAI,CAAC,MAAM,GAAG,OAAO,EACrB,MAAM,GAAG,OAAO,CACjB,CAAC;YACF,OAAO,IAAI,CAAC,CAAC;QACf,CAAC;IACH,CAAC;IAED,IAAI;QACF,OAAO,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC;IACjC,CAAC;IAED,4CAA4C;IAC5C,KAAK;QACH,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACrB,CAAC;CACF"}

package/dist/storage.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Synchronous random-access storage backing a {@link "./container".Container}.
+ *
+ * This mirrors the reference implementation's `Read + Write + Seek` bound: the
+ * container only needs to read and write byte ranges at absolute offsets and to
+ * learn the current size. Two implementations are provided: an in-memory
+ * growable buffer (the analogue of the reference's `Cursor<Vec<u8>>`) and a
+ * Node file-descriptor backed store.
+ *
+ * Offsets are plain `number` byte positions. The on-disk format preserves full
+ * `u64` fidelity (offsets are encoded as little-endian `u64` via `DataView`);
+ * any real file fits comfortably below `Number.MAX_SAFE_INTEGER`.
+ */
+/** Random-access byte store. */
+export interface Storage {
+    /** Read exactly `length` bytes starting at `offset`. */
+    readAt(offset: number, length: number): Uint8Array;
+    /** Write `data` starting at `offset`, growing the store as needed. */
+    writeAt(offset: number, data: Uint8Array): void;
+    /** Current logical size, in bytes. */
+    size(): number;
+}
+/** In-memory growable storage (the `Cursor<Vec<u8>>` analogue). */
+export declare class MemoryStorage implements Storage {
+    private buf;
+    private len;
+    constructor(initial?: Uint8Array);
+    private ensureCapacity;
+    readAt(offset: number, length: number): Uint8Array;
+    writeAt(offset: number, data: Uint8Array): void;
+    size(): number;
+    /** Return a copy of the logical contents (the analogue of `into_inner`). */
+    toUint8Array(): Uint8Array;
+}
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,gCAAgC;AAChC,MAAM,WAAW,OAAO;IACtB,wDAAwD;IACxD,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAAC;IACnD,sEAAsE;IACtE,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;IAChD,sCAAsC;IACtC,IAAI,IAAI,MAAM,CAAC;CAChB;AAED,mEAAmE;AACnE,qBAAa,aAAc,YAAW,OAAO;IAC3C,OAAO,CAAC,GAAG,CAAa;IACxB,OAAO,CAAC,GAAG,CAAS;gBAER,OAAO,CAAC,EAAE,UAAU;IAUhC,OAAO,CAAC,cAAc;IAatB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU;IAUlD,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,IAAI;IAY/C,IAAI,IAAI,MAAM;IAId,4EAA4E;IAC5E,YAAY,IAAI,UAAU;CAG3B"}

package/dist/storage.js

@@ -0,0 +1,66 @@
+/**
+ * Synchronous random-access storage backing a {@link "./container".Container}.
+ *
+ * This mirrors the reference implementation's `Read + Write + Seek` bound: the
+ * container only needs to read and write byte ranges at absolute offsets and to
+ * learn the current size. Two implementations are provided: an in-memory
+ * growable buffer (the analogue of the reference's `Cursor<Vec<u8>>`) and a
+ * Node file-descriptor backed store.
+ *
+ * Offsets are plain `number` byte positions. The on-disk format preserves full
+ * `u64` fidelity (offsets are encoded as little-endian `u64` via `DataView`);
+ * any real file fits comfortably below `Number.MAX_SAFE_INTEGER`.
+ */
+import { PcfError, PcfErrorKind } from "./errors.js";
+/** In-memory growable storage (the `Cursor<Vec<u8>>` analogue). */
+export class MemoryStorage {
+    buf;
+    len;
+    constructor(initial) {
+        if (initial && initial.length > 0) {
+            this.buf = initial.slice();
+            this.len = initial.length;
+        }
+        else {
+            this.buf = new Uint8Array(64);
+            this.len = 0;
+        }
+    }
+    ensureCapacity(needed) {
+        if (needed <= this.buf.length) {
+            return;
+        }
+        let cap = this.buf.length === 0 ? 64 : this.buf.length;
+        while (cap < needed) {
+            cap *= 2;
+        }
+        const next = new Uint8Array(cap);
+        next.set(this.buf.subarray(0, this.len), 0);
+        this.buf = next;
+    }
+    readAt(offset, length) {
+        if (offset < 0 || offset + length > this.len) {
+            throw new PcfError(PcfErrorKind.Io, `read out of bounds: offset ${offset}, length ${length}, size ${this.len}`);
+        }
+        return this.buf.slice(offset, offset + length);
+    }
+    writeAt(offset, data) {
+        if (offset < 0) {
+            throw new PcfError(PcfErrorKind.Io, `negative write offset ${offset}`);
+        }
+        const end = offset + data.length;
+        this.ensureCapacity(end);
+        this.buf.set(data, offset);
+        if (end > this.len) {
+            this.len = end;
+        }
+    }
+    size() {
+        return this.len;
+    }
+    /** Return a copy of the logical contents (the analogue of `into_inner`). */
+    toUint8Array() {
+        return this.buf.slice(0, this.len);
+    }
+}
+//# sourceMappingURL=storage.js.map

package/dist/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAYrD,mEAAmE;AACnE,MAAM,OAAO,aAAa;IAChB,GAAG,CAAa;IAChB,GAAG,CAAS;IAEpB,YAAY,OAAoB;QAC9B,IAAI,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAClC,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;YAC3B,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC;QAC5B,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,GAAG,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC;YAC9B,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC;QACf,CAAC;IACH,CAAC;IAEO,cAAc,CAAC,MAAc;QACnC,IAAI,MAAM,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC;YAC9B,OAAO;QACT,CAAC;QACD,IAAI,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC;QACvD,OAAO,GAAG,GAAG,MAAM,EAAE,CAAC;YACpB,GAAG,IAAI,CAAC,CAAC;QACX,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;QAC5C,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC;IAClB,CAAC;IAED,MAAM,CAAC,MAAc,EAAE,MAAc;QACnC,IAAI,MAAM,GAAG,CAAC,IAAI,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YAC7C,MAAM,IAAI,QAAQ,CAChB,YAAY,CAAC,EAAE,EACf,8BAA8B,MAAM,YAAY,MAAM,UAAU,IAAI,CAAC,GAAG,EAAE,CAC3E,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;IACjD,CAAC;IAED,OAAO,CAAC,MAAc,EAAE,IAAgB;QACtC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;YACf,MAAM,IAAI,QAAQ,CAAC,YAAY,CAAC,EAAE,EAAE,yBAAyB,MAAM,EAAE,CAAC,CAAC;QACzE,CAAC;QACD,MAAM,GAAG,GAAG,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QACjC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;QACzB,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC3B,IAAI,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACnB,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACjB,CAAC;IACH,CAAC;IAED,IAAI;QACF,OAAO,IAAI,CAAC,GAAG,CAAC;IAClB,CAAC;IAED,4EAA4E;IAC5E,YAAY;QACV,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;IACrC,CAAC;CACF"}

package/dist/table.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The 74-byte table-block header and table-block hashing
+ * (spec sections 5.1, 8.4).
+ */
+import { type PartitionEntry } from "./entry.js";
+import { HashAlgo } from "./hash.js";
+/** Parsed table-block header (the entries follow it on disk). */
+export interface TableBlockHeader {
+    /** Number of entries stored in this block (0..=255). */
+    partitionCount: number;
+    /** Absolute offset of the next block, or 0 for end-of-chain. */
+    nextTableOffset: bigint;
+    /** Algorithm used for `tableHash`. */
+    tableHashAlgo: HashAlgo;
+    /** 64-byte table hash field. */
+    tableHash: Uint8Array;
+}
+/** Serialise a table-block header to its on-disk 74-byte layout. */
+export declare function tableHeaderToBytes(h: TableBlockHeader): Uint8Array;
+/** Parse a table-block header from its on-disk 74-byte layout. */
+export declare function tableHeaderFromBytes(b: Uint8Array): TableBlockHeader;
+/**
+ * Compute the table hash over `[header-with-zeroed-hash || entries]`
+ * (spec section 8.4). The `table_hash_algo` byte is included; the 64-byte
+ * hash field is treated as zero; trailing reserved space is excluded.
+ */
+export declare function computeTableHash(algo: HashAlgo, nextTableOffset: bigint, entries: readonly PartitionEntry[]): Uint8Array;
+//# sourceMappingURL=table.d.ts.map

package/dist/table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../src/table.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,EAAoB,QAAQ,EAA8B,MAAM,WAAW,CAAC;AAEnF,iEAAiE;AACjE,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,cAAc,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,eAAe,EAAE,MAAM,CAAC;IACxB,sCAAsC;IACtC,aAAa,EAAE,QAAQ,CAAC;IACxB,gCAAgC;IAChC,SAAS,EAAE,UAAU,CAAC;CACvB;AAED,oEAAoE;AACpE,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,gBAAgB,GAAG,UAAU,CAQlE;AAED,kEAAkE;AAClE,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,UAAU,GAAG,gBAAgB,CAOpE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,QAAQ,EACd,eAAe,EAAE,MAAM,EACvB,OAAO,EAAE,SAAS,cAAc,EAAE,GACjC,UAAU,CAeZ"}

package/dist/table.js

@@ -0,0 +1,48 @@
+/**
+ * The 74-byte table-block header and table-block hashing
+ * (spec sections 5.1, 8.4).
+ */
+import { HASH_FIELD_SIZE, TABLE_HEADER_SIZE } from "./consts.js";
+import { entryToBytes } from "./entry.js";
+import { computeHashField, HashAlgo, hashAlgoFromId, hashAlgoId } from "./hash.js";
+/** Serialise a table-block header to its on-disk 74-byte layout. */
+export function tableHeaderToBytes(h) {
+    const b = new Uint8Array(TABLE_HEADER_SIZE);
+    const view = new DataView(b.buffer);
+    b[0] = h.partitionCount & 0xff;
+    view.setBigUint64(1, h.nextTableOffset, true);
+    b[9] = hashAlgoId(h.tableHashAlgo);
+    b.set(h.tableHash, 10);
+    return b;
+}
+/** Parse a table-block header from its on-disk 74-byte layout. */
+export function tableHeaderFromBytes(b) {
+    const view = new DataView(b.buffer, b.byteOffset, b.byteLength);
+    const partitionCount = b[0];
+    const nextTableOffset = view.getBigUint64(1, true);
+    const tableHashAlgo = hashAlgoFromId(b[9]);
+    const tableHash = b.slice(10, 10 + HASH_FIELD_SIZE);
+    return { partitionCount, nextTableOffset, tableHashAlgo, tableHash };
+}
+/**
+ * Compute the table hash over `[header-with-zeroed-hash || entries]`
+ * (spec section 8.4). The `table_hash_algo` byte is included; the 64-byte
+ * hash field is treated as zero; trailing reserved space is excluded.
+ */
+export function computeTableHash(algo, nextTableOffset, entries) {
+    const header = tableHeaderToBytes({
+        partitionCount: entries.length,
+        nextTableOffset,
+        tableHashAlgo: algo,
+        tableHash: new Uint8Array(HASH_FIELD_SIZE), // zeroed for the computation
+    });
+    const image = new Uint8Array(TABLE_HEADER_SIZE + entries.length * 141);
+    image.set(header, 0);
+    let off = TABLE_HEADER_SIZE;
+    for (const e of entries) {
+        image.set(entryToBytes(e), off);
+        off += 141;
+    }
+    return computeHashField(algo, image);
+}
+//# sourceMappingURL=table.js.map

package/dist/table.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"table.js","sourceRoot":"","sources":["../src/table.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EAAE,YAAY,EAAuB,MAAM,YAAY,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAcnF,oEAAoE;AACpE,MAAM,UAAU,kBAAkB,CAAC,CAAmB;IACpD,MAAM,CAAC,GAAG,IAAI,UAAU,CAAC,iBAAiB,CAAC,CAAC;IAC5C,MAAM,IAAI,GAAG,IAAI,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,cAAc,GAAG,IAAI,CAAC;IAC/B,IAAI,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,eAAe,EAAE,IAAI,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC;IACnC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;IACvB,OAAO,CAAC,CAAC;AACX,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,oBAAoB,CAAC,CAAa;IAChD,MAAM,IAAI,GAAG,IAAI,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC;IAChE,MAAM,cAAc,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;IAC7B,MAAM,eAAe,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IACnD,MAAM,aAAa,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC,CAAC;IAC5C,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,GAAG,eAAe,CAAC,CAAC;IACpD,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAE,SAAS,EAAE,CAAC;AACvE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAAc,EACd,eAAuB,EACvB,OAAkC;IAElC,MAAM,MAAM,GAAG,kBAAkB,CAAC;QAChC,cAAc,EAAE,OAAO,CAAC,MAAM;QAC9B,eAAe;QACf,aAAa,EAAE,IAAI;QACnB,SAAS,EAAE,IAAI,UAAU,CAAC,eAAe,CAAC,EAAE,6BAA6B;KAC1E,CAAC,CAAC;IACH,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,iBAAiB,GAAG,OAAO,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC;IACvE,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACrB,IAAI,GAAG,GAAG,iBAAiB,CAAC;IAC5B,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QAChC,GAAG,IAAI,GAAG,CAAC;IACb,CAAC;IACD,OAAO,gBAAgB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AACvC,CAAC"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@kduma-oss/pcf",
+  "version": "0.0.1",
+  "description": "TypeScript implementation of the Partitioned Container Format (PCF) v1.0",
+  "license": "MIT OR Apache-2.0",
+  "author": "Krystian Duma",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kduma-OSS/Partitioned-Container-Format.git",
+    "directory": "implementations/ts"
+  },
+  "bugs": {
+    "url": "https://github.com/kduma-OSS/Partitioned-Container-Format/issues"
+  },
+  "homepage": "https://github.com/kduma-OSS/Partitioned-Container-Format#readme",
+  "keywords": [
+    "pcf",
+    "partitioned-container-format",
+    "binary",
+    "container",
+    "file-format"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage",
+    "gen-testvector": "tsx examples/gen-testvector.ts"
+  },
+  "dependencies": {
+    "@noble/hashes": "^1.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.19",
+    "@vitest/coverage-v8": "^4.1.8",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.8"
+  }
+}

package/src/consts.ts

@@ -0,0 +1,50 @@
+/**
+ * On-disk constants defined by PCF v1.0.
+ *
+ * Every value here is normative and corresponds directly to a figure in the
+ * specification (see Appendix A, "Field Layout Summary").
+ */
+
+/** File signature, 8 bytes: `0x89 'K' 'P' 'R' 'T' 0x0D 0x0A 0x1A`. */
+export const MAGIC: Uint8Array = new Uint8Array([
+  0x89, 0x4b, 0x50, 0x52, 0x54, 0x0d, 0x0a, 0x1a,
+]);
+
+/** Major format version implemented by this library. */
+export const VERSION_MAJOR = 1;
+/** Minor format version implemented by this library. */
+export const VERSION_MINOR = 0;
+
+/** Fixed size of the file header, in bytes. */
+export const HEADER_SIZE = 20;
+/** Fixed size of a table-block header, in bytes. */
+export const TABLE_HEADER_SIZE = 74;
+/** Fixed size of a single partition entry, in bytes. */
+export const ENTRY_SIZE = 141;
+
+/** Size of every hash field, in bytes (large enough for the widest digest). */
+export const HASH_FIELD_SIZE = 64;
+/** Size of the partition label field, in bytes. */
+export const LABEL_SIZE = 32;
+/** Size of the partition UID field, in bytes. */
+export const UID_SIZE = 16;
+
+/**
+ * Reserved partition type: invalid / uninitialised. MUST NOT label a live
+ * partition.
+ */
+export const TYPE_RESERVED = 0x0000_0000;
+/**
+ * Reserved partition type: raw / blob, interpreted entirely by the
+ * application.
+ */
+export const TYPE_RAW = 0xffff_ffff;
+
+/** The NIL UID (all zero). MUST NOT label a live partition. */
+export const NIL_UID: Uint8Array = new Uint8Array(UID_SIZE);
+
+/**
+ * Maximum number of entries a single table block can hold (`partition_count`
+ * is a `u8`).
+ */
+export const MAX_ENTRIES_PER_BLOCK = 255;