@kduma-oss/pcf 0.0.1

package/README.md

@@ -0,0 +1,116 @@
+# pcf — Partitioned Container Format (TypeScript implementation)
+
+A TypeScript reader/writer for **PCF v1.0**, a language-agnostic binary
+container that stores multiple independent byte regions ("partitions") in one
+file.
+
+This package is a faithful port of the Rust reference implementation
+(`reference/PCF-v1.0/`) and mirrors the written specification
+(`specs/PCF-spec-v1.0.txt`) field-for-field. It favours auditability over
+performance and produces the **byte-exact** canonical test vector from spec
+section 15.
+
+## Layout
+
+```
+[ 20-byte header ] [ table block(s) ] [ partition data regions ]
+```
+
+- **Header** (20 B): magic `0x89 K P R T 0x0D 0x0A 0x1A`, major/minor version,
+  absolute offset of the first table block.
+- **Table block**: 74-byte header (`partitionCount`, `nextTableOffset`,
+  hash algo + 64-byte block hash) followed by `partitionCount` entries. Blocks
+  form a singly linked chain to hold more than 255 partitions.
+- **Entry** (141 B): `type`, 16-byte UID, 32-byte ASCII label, `startOffset`,
+  `maxLength`, `usedBytes`, 1-byte data-hash algorithm, 64-byte data hash.
+
+All integers are little-endian. `u64` fields are modelled as `bigint` to
+preserve full 64-bit fidelity; free space is `maxLength - usedBytes`.
+
+## Hash registry
+
+| id | algorithm        | id | algorithm |
+|----|------------------|----|-----------|
+| 0  | none             | 5  | SHA-1     |
+| 1  | CRC-32/ISO-HDLC  | 16 | SHA-256 (default) |
+| 2  | CRC-32C          | 17 | SHA-512   |
+| 3  | CRC-64/XZ        | 18 | BLAKE3    |
+| 4  | MD5              |    |           |
+
+Digests are provided by the audited [`@noble/hashes`](https://github.com/paulmillr/noble-hashes)
+package; the three CRC variants are implemented in pure TypeScript
+(`src/crc.ts`).
+
+## Usage
+
+```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();
+const data = c.readPartitionData(entries[0]);
+console.log(new TextDecoder().decode(data)); // "hello world"
+```
+
+A `Container` is backed by any `Storage`. Two implementations ship with the
+package:
+
+- `MemoryStorage` — an in-memory growable buffer (the default for
+  `Container.create()`).
+- `NodeFileStorage` — backed by a Node file descriptor:
+
+```ts
+import { Container, NodeFileStorage, HashAlgo } from "pcf";
+
+const store = NodeFileStorage.open("container.pcf", /* truncate */ true);
+const c = Container.create(store);
+// … add partitions …
+store.close();
+```
+
+## Project layout
+
+```
+implementations/ts/
+├── package.json
+├── tsconfig.json
+├── vitest.config.ts
+├── src/                       # library sources
+│   ├── consts.ts  errors.ts  crc.ts  hash.ts
+│   ├── header.ts  entry.ts   table.ts
+│   ├── storage.ts node-storage.ts container.ts
+│   └── index.ts               # public re-exports
+├── test/
+│   ├── roundtrip.test.ts      # end-to-end black-box tests
+│   ├── coverage.test.ts       # targeted error-path / edge-case tests
+│   └── spec-compliance.test.ts  # one test per normative MUST/SHALL
+└── examples/
+    └── gen-testvector.ts      # produces the canonical 395-byte spec vector
+```
+
+## Scripts
+
+Run from this directory:
+
+```
+npm install            # install dependencies
+npm run build          # type-check and emit dist/ (tsc, strict)
+npm test               # run the full vitest suite
+npm run coverage       # vitest + v8 coverage (95% line / 100% function floor)
+npm run gen-testvector # writes pcf_testvector.bin (the 395-byte spec vector)
+```
+
+CI (`.github/workflows/ts-ci.yml`) runs the type-check/build, the test suite on
+Linux/macOS/Windows, regenerates and size-checks the spec test vector, and
+enforces the coverage floor.

package/dist/consts.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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 declare const MAGIC: Uint8Array;
+/** Major format version implemented by this library. */
+export declare const VERSION_MAJOR = 1;
+/** Minor format version implemented by this library. */
+export declare const VERSION_MINOR = 0;
+/** Fixed size of the file header, in bytes. */
+export declare const HEADER_SIZE = 20;
+/** Fixed size of a table-block header, in bytes. */
+export declare const TABLE_HEADER_SIZE = 74;
+/** Fixed size of a single partition entry, in bytes. */
+export declare const ENTRY_SIZE = 141;
+/** Size of every hash field, in bytes (large enough for the widest digest). */
+export declare const HASH_FIELD_SIZE = 64;
+/** Size of the partition label field, in bytes. */
+export declare const LABEL_SIZE = 32;
+/** Size of the partition UID field, in bytes. */
+export declare const UID_SIZE = 16;
+/**
+ * Reserved partition type: invalid / uninitialised. MUST NOT label a live
+ * partition.
+ */
+export declare const TYPE_RESERVED = 0;
+/**
+ * Reserved partition type: raw / blob, interpreted entirely by the
+ * application.
+ */
+export declare const TYPE_RAW = 4294967295;
+/** The NIL UID (all zero). MUST NOT label a live partition. */
+export declare const NIL_UID: Uint8Array;
+/**
+ * Maximum number of entries a single table block can hold (`partition_count`
+ * is a `u8`).
+ */
+export declare const MAX_ENTRIES_PER_BLOCK = 255;
+//# sourceMappingURL=consts.d.ts.map

package/dist/consts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,sEAAsE;AACtE,eAAO,MAAM,KAAK,EAAE,UAElB,CAAC;AAEH,wDAAwD;AACxD,eAAO,MAAM,aAAa,IAAI,CAAC;AAC/B,wDAAwD;AACxD,eAAO,MAAM,aAAa,IAAI,CAAC;AAE/B,+CAA+C;AAC/C,eAAO,MAAM,WAAW,KAAK,CAAC;AAC9B,oDAAoD;AACpD,eAAO,MAAM,iBAAiB,KAAK,CAAC;AACpC,wDAAwD;AACxD,eAAO,MAAM,UAAU,MAAM,CAAC;AAE9B,+EAA+E;AAC/E,eAAO,MAAM,eAAe,KAAK,CAAC;AAClC,mDAAmD;AACnD,eAAO,MAAM,UAAU,KAAK,CAAC;AAC7B,iDAAiD;AACjD,eAAO,MAAM,QAAQ,KAAK,CAAC;AAE3B;;;GAGG;AACH,eAAO,MAAM,aAAa,IAAc,CAAC;AACzC;;;GAGG;AACH,eAAO,MAAM,QAAQ,aAAc,CAAC;AAEpC,+DAA+D;AAC/D,eAAO,MAAM,OAAO,EAAE,UAAqC,CAAC;AAE5D;;;GAGG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC"}

package/dist/consts.js

@@ -0,0 +1,44 @@
+/**
+ * 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 = 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 = 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;
+//# sourceMappingURL=consts.js.map

package/dist/consts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,sEAAsE;AACtE,MAAM,CAAC,MAAM,KAAK,GAAe,IAAI,UAAU,CAAC;IAC9C,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI;CAC/C,CAAC,CAAC;AAEH,wDAAwD;AACxD,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC;AAC/B,wDAAwD;AACxD,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC;AAE/B,+CAA+C;AAC/C,MAAM,CAAC,MAAM,WAAW,GAAG,EAAE,CAAC;AAC9B,oDAAoD;AACpD,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC;AACpC,wDAAwD;AACxD,MAAM,CAAC,MAAM,UAAU,GAAG,GAAG,CAAC;AAE9B,+EAA+E;AAC/E,MAAM,CAAC,MAAM,eAAe,GAAG,EAAE,CAAC;AAClC,mDAAmD;AACnD,MAAM,CAAC,MAAM,UAAU,GAAG,EAAE,CAAC;AAC7B,iDAAiD;AACjD,MAAM,CAAC,MAAM,QAAQ,GAAG,EAAE,CAAC;AAE3B;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,WAAW,CAAC;AACzC;;;GAGG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,WAAW,CAAC;AAEpC,+DAA+D;AAC/D,MAAM,CAAC,MAAM,OAAO,GAAe,IAAI,UAAU,CAAC,QAAQ,CAAC,CAAC;AAE5D;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAC"}

package/dist/container.d.ts

@@ -0,0 +1,124 @@
+/**
+ * The high-level {@link Container} type: reading and writing whole PCF files.
+ *
+ * `Container` is backed by any {@link Storage}, so it works equally with an
+ * in-memory {@link MemoryStorage} and a file-backed `NodeFileStorage`.
+ *
+ * # Reader vs. writer scope
+ *
+ * The *reader* side (`open`, `entries`, `readPartitionData`, `verify`) is fully
+ * general: it accepts any conforming file, including arbitrary region placement
+ * and overflow-block chains.
+ *
+ * The *writer* side implements one documented placement strategy (the format
+ * deliberately leaves layout to the writer, spec section 12 / A7, A9):
+ *
+ * - The first table block sits immediately after the header and is created with
+ *   reserved capacity for `firstBlockCapacity` entries, so entries can be
+ *   appended in place without moving data.
+ * - Partition data is appended at a growing end-of-data cursor; each partition
+ *   may reserve `extraReserve` spare bytes for later in-place growth.
+ * - When every known block is full, a new overflow block is appended and linked
+ *   into the chain.
+ * - Block capacity is *not* stored in the file (spec A9); it is tracked only in
+ *   memory for the lifetime of this handle. After {@link Container.open}, blocks
+ *   are treated as having no spare capacity, so subsequent additions go into
+ *   fresh overflow blocks. {@link Container.compactedImage} rebuilds a tightly
+ *   packed file.
+ */
+import { type PartitionEntry } from "./entry.js";
+import { HashAlgo } from "./hash.js";
+import { type FileHeader } from "./header.js";
+import { type Storage } from "./storage.js";
+import { type TableBlockHeader } from "./table.js";
+/**
+ * One table block read from disk: its absolute `offset`, its parsed
+ * {@link TableBlockHeader} (including `tableHash` and `nextTableOffset`), and
+ * its {@link PartitionEntry} list.
+ *
+ * Returned by {@link Container.readBlockAt}. It lets code layered on PCF group
+ * blocks, inspect each block's `tableHash`, and follow non-default
+ * `nextTableOffset` chains, instead of {@link Container.entries} which flattens
+ * the whole chain.
+ */
+export interface BlockView {
+    /** Absolute file offset of the table block. */
+    offset: number;
+    /** Parsed 74-byte block header. */
+    header: TableBlockHeader;
+    /** The block's entries, in stored order. */
+    entries: PartitionEntry[];
+}
+/** A PCF container backed by a {@link Storage}. */
+export declare class Container {
+    private storage;
+    private fileHeader;
+    private blocks;
+    private dataEof;
+    private defaultCapacity;
+    private tableHashAlgo;
+    private constructor();
+    /**
+     * Create an empty container with sensible defaults (first block capacity 16,
+     * table hashing with SHA-256). Defaults to an in-memory store.
+     */
+    static create(storage?: Storage): Container;
+    /**
+     * Create an empty container, choosing the first block's reserved capacity and
+     * the table-hash algorithm.
+     */
+    static createWith(storage: Storage, firstBlockCapacity: number, tableHashAlgo: HashAlgo): Container;
+    /** Open an existing container, validating the header (spec C1, C2). */
+    static open(storage: Storage): Container;
+    /** Consume the container and return the backing store. */
+    intoStorage(): Storage;
+    /** The parsed file header. */
+    header(): FileHeader;
+    private readBlock;
+    private writeBlock;
+    /** All live partition entries, in chain order. */
+    entries(): PartitionEntry[];
+    /**
+     * Read a single table block at an absolute `offset`, returning its parsed
+     * header (including `tableHash`) and entries. Unlike {@link entries}, which
+     * flattens the whole chain, this exposes one block at a time so a caller can
+     * follow an arbitrary `nextTableOffset` chain and inspect each block's
+     * `tableHash`. It is a read-only operation and does not alter the container.
+     */
+    readBlockAt(offset: number): BlockView;
+    /** Read a partition's used data. */
+    readPartitionData(entry: PartitionEntry): Uint8Array;
+    private locate;
+    private blockIndex;
+    /**
+     * Add a new partition. The data is appended at the end-of-data cursor and
+     * reserves `extraReserve` spare bytes for later in-place growth.
+     */
+    addPartition(partitionType: number, uid: Uint8Array, label: string, data: Uint8Array, extraReserve?: number | bigint, dataHashAlgo?: HashAlgo): void;
+    /**
+     * Replace a partition's data in place (spec section 8.5, hash cascade).
+     * Fails if `newData` exceeds the partition's reservation.
+     */
+    updatePartitionData(uid: Uint8Array, newData: Uint8Array): void;
+    /**
+     * Remove a partition. Entries after it in the same block shift down; the
+     * freed data region becomes dead space until {@link Container.compactedImage}
+     * reclaims it (spec section 11.4).
+     */
+    removePartition(uid: Uint8Array): void;
+    /**
+     * Verify every table block and every partition's data against its stored
+     * hash, and run the per-entry conformance checks (spec section 12).
+     */
+    verify(): void;
+    /**
+     * Build a freshly compacted image: all dead space removed, every `maxLength`
+     * trimmed to `usedBytes`, partitions placed contiguously after a tightly
+     * packed table (spec section 11.5). The current handle is left unchanged;
+     * write the bytes to a new store and re-open it.
+     */
+    compactedImage(): Uint8Array;
+    /** Write a compacted copy of the container to `out`. */
+    compactInto(out: Storage): void;
+}
+//# sourceMappingURL=container.d.ts.map

package/dist/container.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"container.d.ts","sourceRoot":"","sources":["../src/container.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAYH,OAAO,EAIL,KAAK,cAAc,EAEpB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAA+B,QAAQ,EAAY,MAAM,WAAW,CAAC;AAC5E,OAAO,EACL,KAAK,UAAU,EAGhB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAiB,KAAK,OAAO,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,YAAY,CAAC;AAWpB;;;;;;;;;GASG;AACH,MAAM,WAAW,SAAS;IACxB,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,mCAAmC;IACnC,MAAM,EAAE,gBAAgB,CAAC;IACzB,4CAA4C;IAC5C,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAcD,mDAAmD;AACnD,qBAAa,SAAS;IACpB,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,aAAa,CAAW;IAEhC,OAAO;IAkBP;;;OAGG;IACH,MAAM,CAAC,MAAM,CAAC,OAAO,GAAE,OAA6B,GAAG,SAAS;IAIhE;;;OAGG;IACH,MAAM,CAAC,UAAU,CACf,OAAO,EAAE,OAAO,EAChB,kBAAkB,EAAE,MAAM,EAC1B,aAAa,EAAE,QAAQ,GACtB,SAAS;IA4BZ,uEAAuE;IACvE,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS;IA2BxC,0DAA0D;IAC1D,WAAW,IAAI,OAAO;IAItB,8BAA8B;IAC9B,MAAM,IAAI,UAAU;IAMpB,OAAO,CAAC,SAAS;IAcjB,OAAO,CAAC,UAAU;IAyBlB,kDAAkD;IAClD,OAAO,IAAI,cAAc,EAAE;IAW3B;;;;;;OAMG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS;IAKtC,oCAAoC;IACpC,iBAAiB,CAAC,KAAK,EAAE,cAAc,GAAG,UAAU;IAQpD,OAAO,CAAC,MAAM;IAcd,OAAO,CAAC,UAAU;IAUlB;;;OAGG;IACH,YAAY,CACV,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,UAAU,EACf,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,UAAU,EAChB,YAAY,GAAE,MAAM,GAAG,MAAU,EACjC,YAAY,GAAE,QAA0B,GACvC,IAAI;IAuEP;;;OAGG;IACH,mBAAmB,CAAC,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,GAAG,IAAI;IAmB/D;;;;OAIG;IACH,eAAe,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI;IAatC;;;OAGG;IACH,MAAM,IAAI,IAAI;IA8Bd;;;;;OAKG;IACH,cAAc,IAAI,UAAU;IAqF5B,wDAAwD;IACxD,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI;CAGhC"}