@kduma-oss/pcf 0.0.1

package/src/storage.ts

@@ -0,0 +1,85 @@
+/**
+ * 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";
+
+/** 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 class MemoryStorage implements Storage {
+  private buf: Uint8Array;
+  private len: number;
+
+  constructor(initial?: Uint8Array) {
+    if (initial && initial.length > 0) {
+      this.buf = initial.slice();
+      this.len = initial.length;
+    } else {
+      this.buf = new Uint8Array(64);
+      this.len = 0;
+    }
+  }
+
+  private ensureCapacity(needed: number): void {
+    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: number, length: number): Uint8Array {
+    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: number, data: Uint8Array): void {
+    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(): number {
+    return this.len;
+  }
+
+  /** Return a copy of the logical contents (the analogue of `into_inner`). */
+  toUint8Array(): Uint8Array {
+    return this.buf.slice(0, this.len);
+  }
+}

package/src/table.ts

@@ -0,0 +1,67 @@
+/**
+ * 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, type PartitionEntry } from "./entry.js";
+import { computeHashField, HashAlgo, hashAlgoFromId, hashAlgoId } 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 function tableHeaderToBytes(h: TableBlockHeader): Uint8Array {
+  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: Uint8Array): TableBlockHeader {
+  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: HashAlgo,
+  nextTableOffset: bigint,
+  entries: readonly PartitionEntry[],
+): Uint8Array {
+  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);
+}