@prisma/streams-server 0.1.1 → 0.1.3

package/src/search/column_encoding.ts

@@ -0,0 +1,43 @@
+const INT64_SIGN = 0x8000_0000_0000_0000n;
+const UINT64_MASK = 0xffff_ffff_ffff_ffffn;
+
+export function encodeSortableInt64(value: bigint): Uint8Array {
+  const signed = BigInt.asIntN(64, value);
+  const sortable = BigInt.asUintN(64, signed ^ INT64_SIGN);
+  const out = new Uint8Array(8);
+  const dv = new DataView(out.buffer, out.byteOffset, out.byteLength);
+  dv.setBigUint64(0, sortable, false);
+  return out;
+}
+
+export function decodeSortableInt64(bytes: Uint8Array, offset = 0): bigint {
+  const dv = new DataView(bytes.buffer, bytes.byteOffset + offset, 8);
+  const sortable = dv.getBigUint64(0, false);
+  return BigInt.asIntN(64, sortable ^ INT64_SIGN);
+}
+
+export function encodeSortableFloat64(value: number): Uint8Array {
+  const out = new Uint8Array(8);
+  const dv = new DataView(out.buffer, out.byteOffset, out.byteLength);
+  dv.setFloat64(0, value, false);
+  const raw = dv.getBigUint64(0, false);
+  const sortable = (raw & INT64_SIGN) !== 0n ? (~raw) & UINT64_MASK : raw ^ INT64_SIGN;
+  dv.setBigUint64(0, sortable, false);
+  return out;
+}
+
+export function decodeSortableFloat64(bytes: Uint8Array, offset = 0): number {
+  const dv = new DataView(bytes.buffer, bytes.byteOffset + offset, 8);
+  const sortable = dv.getBigUint64(0, false);
+  const raw = (sortable & INT64_SIGN) !== 0n ? sortable ^ INT64_SIGN : (~sortable) & UINT64_MASK;
+  dv.setBigUint64(0, raw, false);
+  return dv.getFloat64(0, false);
+}
+
+export function encodeSortableBool(value: boolean): Uint8Array {
+  return new Uint8Array([value ? 1 : 0]);
+}
+
+export function decodeSortableBool(bytes: Uint8Array, offset = 0): boolean {
+  return bytes[offset] === 1;
+}

package/src/search/companion_file_cache.ts

@@ -0,0 +1,319 @@
+import {
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readSync,
+  readdirSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { Result } from "better-result";
+import { type CompanionToc } from "./companion_format";
+import { LruCache } from "../util/lru";
+
+export type CompanionFileCacheError = { kind: "invalid_companion_cache"; message: string };
+
+export type MappedCompanionBundle = {
+  objectKey: string;
+  path: string;
+  bytes: Uint8Array;
+  toc: CompanionToc;
+  sizeBytes: number;
+};
+
+type FileEntry = {
+  path: string;
+  size: number;
+  mtimeMs: number;
+};
+
+export type CompanionFileCacheStats = {
+  usedBytes: number;
+  entryCount: number;
+  mappedBytes: number;
+  mappedEntryCount: number;
+  pinnedEntryCount: number;
+};
+
+function invalidCompanionCache<T = never>(message: string): Result<T, CompanionFileCacheError> {
+  return Result.err({ kind: "invalid_companion_cache", message });
+}
+
+export class CompanionFileCache {
+  private readonly entries = new Map<string, FileEntry>();
+  private readonly pinnedKeys = new Set<string>();
+  private readonly mappedBundles: LruCache<string, MappedCompanionBundle>;
+  private totalBytes = 0;
+
+  constructor(
+    private readonly rootDir: string,
+    private readonly maxBytes: number,
+    private readonly maxAgeMs: number,
+    mappedEntries: number
+  ) {
+    mkdirSync(this.rootDir, { recursive: true });
+    this.mappedBundles = new LruCache(Math.max(1, mappedEntries));
+    this.loadIndex();
+    this.pruneForBudget(Date.now(), 0, true);
+  }
+
+  clearMapped(): void {
+    this.mappedBundles.clear();
+  }
+
+  bytesForObjectKeyPrefix(prefix: string): number {
+    let total = 0;
+    for (const [objectKey, entry] of this.entries.entries()) {
+      if (objectKey.startsWith(prefix)) total += entry.size;
+    }
+    return total;
+  }
+
+  remove(objectKey: string): void {
+    this.removeEntry(objectKey, true);
+  }
+
+  storeBytesResult(objectKey: string, bytes: Uint8Array): Result<string, CompanionFileCacheError> {
+    if (this.maxBytes <= 0) return invalidCompanionCache("search companion file cache must have a positive size budget");
+    if (bytes.byteLength > this.maxBytes) {
+      return invalidCompanionCache(`companion cache object exceeds budget: ${objectKey}`);
+    }
+    this.pruneForBudget(Date.now(), bytes.byteLength, false);
+    const path = this.pathFor(objectKey);
+    mkdirSync(dirname(path), { recursive: true });
+    const tmpPath = `${path}.tmp-${process.pid}-${Date.now()}`;
+    try {
+      writeFileSync(tmpPath, bytes);
+      renameSync(tmpPath, path);
+    } catch (e: unknown) {
+      try {
+        unlinkSync(tmpPath);
+      } catch {
+        // ignore temp cleanup failures
+      }
+      return invalidCompanionCache(String((e as any)?.message ?? e));
+    }
+    const existing = this.entries.get(objectKey);
+    if (existing) this.totalBytes = Math.max(0, this.totalBytes - existing.size);
+    const nextEntry = { path, size: bytes.byteLength, mtimeMs: Date.now() };
+    this.entries.delete(objectKey);
+    this.entries.set(objectKey, nextEntry);
+    this.totalBytes += bytes.byteLength;
+    this.touch(objectKey);
+    return Result.ok(path);
+  }
+
+  async loadMappedBundleResult(args: {
+    objectKey: string;
+    expectedSize: number;
+    loadBytes: () => Promise<Uint8Array>;
+    decodeToc: (bytes: Uint8Array) => Result<CompanionToc, { message: string }>;
+  }): Promise<Result<MappedCompanionBundle, CompanionFileCacheError>> {
+    const cached = this.mappedBundles.get(args.objectKey);
+    if (cached) {
+      this.pinnedKeys.add(args.objectKey);
+      this.touch(args.objectKey);
+      return Result.ok(cached);
+    }
+
+    const localPathRes = await this.ensureLocalFileResult(args.objectKey, args.expectedSize, args.loadBytes);
+    if (Result.isError(localPathRes)) return localPathRes;
+
+    let mappedRes = this.mapBundleResult(args.objectKey, localPathRes.value, args.expectedSize, args.decodeToc);
+    if (Result.isError(mappedRes)) {
+      this.removeEntry(args.objectKey, true);
+      const refetchedPathRes = await this.ensureLocalFileResult(args.objectKey, args.expectedSize, args.loadBytes);
+      if (Result.isError(refetchedPathRes)) return refetchedPathRes;
+      mappedRes = this.mapBundleResult(args.objectKey, refetchedPathRes.value, args.expectedSize, args.decodeToc);
+    }
+    if (Result.isError(mappedRes)) return mappedRes;
+
+    this.pinnedKeys.add(args.objectKey);
+    this.mappedBundles.set(args.objectKey, mappedRes.value);
+    this.touch(args.objectKey);
+    return mappedRes;
+  }
+
+  stats(): CompanionFileCacheStats {
+    let mappedBytes = 0;
+    let mappedEntryCount = 0;
+    for (const bundle of this.mappedBundles.values()) {
+      mappedBytes += bundle.sizeBytes;
+      mappedEntryCount += 1;
+    }
+    return {
+      usedBytes: this.totalBytes,
+      entryCount: this.entries.size,
+      mappedBytes,
+      mappedEntryCount,
+      pinnedEntryCount: this.pinnedKeys.size,
+    };
+  }
+
+  private async ensureLocalFileResult(
+    objectKey: string,
+    expectedSize: number,
+    loadBytes: () => Promise<Uint8Array>
+  ): Promise<Result<string, CompanionFileCacheError>> {
+    const existing = this.entries.get(objectKey);
+    if (existing) {
+      const stat = this.safeStat(existing.path);
+      if (stat && stat.size === expectedSize) {
+        this.touch(objectKey);
+        return Result.ok(existing.path);
+      }
+      this.removeEntry(objectKey, true);
+    }
+
+    let bytes: Uint8Array;
+    try {
+      bytes = await loadBytes();
+    } catch (e: unknown) {
+      return invalidCompanionCache(String((e as any)?.message ?? e));
+    }
+    if (bytes.byteLength !== expectedSize) {
+      return invalidCompanionCache(`unexpected companion object size for ${objectKey}`);
+    }
+    return this.storeBytesResult(objectKey, bytes);
+  }
+
+  private mapBundleResult(
+    objectKey: string,
+    path: string,
+    expectedSize: number,
+    decodeToc: (bytes: Uint8Array) => Result<CompanionToc, { message: string }>
+  ): Result<MappedCompanionBundle, CompanionFileCacheError> {
+    const stat = this.safeStat(path);
+    if (!stat) return invalidCompanionCache(`missing cached companion file ${path}`);
+    if (stat.size !== expectedSize) return invalidCompanionCache(`unexpected cached companion size for ${objectKey}`);
+    const tocProbeLength = Math.min(expectedSize, 512);
+    const tocProbe = this.readPrefix(path, tocProbeLength);
+    if (Result.isError(tocProbe)) return tocProbe;
+    const tocRes = decodeToc(tocProbe.value);
+    if (Result.isError(tocRes)) return invalidCompanionCache(tocRes.error.message);
+    let bytes: Uint8Array;
+    try {
+      bytes = (Bun as any).mmap(path, { shared: true }) as Uint8Array;
+    } catch (e: unknown) {
+      return invalidCompanionCache(String((e as any)?.message ?? e));
+    }
+    if (bytes.byteLength !== expectedSize) {
+      return invalidCompanionCache(`unexpected mapped companion size for ${objectKey}`);
+    }
+    return Result.ok({
+      objectKey,
+      path,
+      bytes,
+      toc: tocRes.value,
+      sizeBytes: expectedSize,
+    });
+  }
+
+  private pathFor(objectKey: string): string {
+    return join(this.rootDir, objectKey);
+  }
+
+  private loadIndex(): void {
+    const files: Array<{ key: string; path: string; size: number; mtimeMs: number }> = [];
+    const walk = (dir: string) => {
+      for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+          walk(full);
+          continue;
+        }
+        if (!entry.isFile()) continue;
+        const stat = statSync(full);
+        files.push({
+          key: relative(this.rootDir, full),
+          path: full,
+          size: stat.size,
+          mtimeMs: stat.mtimeMs,
+        });
+      }
+    };
+    if (!existsSync(this.rootDir)) return;
+    walk(this.rootDir);
+    files.sort((left, right) => left.mtimeMs - right.mtimeMs);
+    for (const file of files) {
+      this.entries.set(file.key, { path: file.path, size: file.size, mtimeMs: file.mtimeMs });
+      this.totalBytes += file.size;
+    }
+  }
+
+  private pruneForBudget(nowMs: number, incomingBytes: number, allowMappedDeletes: boolean): void {
+    if (this.maxAgeMs > 0) {
+      for (const [objectKey, entry] of Array.from(this.entries.entries())) {
+        if (this.pinnedKeys.has(objectKey)) continue;
+        if (nowMs - entry.mtimeMs <= this.maxAgeMs) continue;
+        this.removeEntry(objectKey, allowMappedDeletes);
+      }
+    }
+    if (this.maxBytes <= 0) return;
+    while (this.totalBytes + incomingBytes > this.maxBytes) {
+      const next = this.entries.keys().next();
+      if (next.done) break;
+      const objectKey = next.value as string;
+      if (this.pinnedKeys.has(objectKey)) {
+        let removed = false;
+        for (const candidateKey of this.entries.keys()) {
+          if (this.pinnedKeys.has(candidateKey)) continue;
+          this.removeEntry(candidateKey, false);
+          removed = true;
+          break;
+        }
+        if (!removed) break;
+        continue;
+      }
+      this.removeEntry(objectKey, allowMappedDeletes);
+    }
+  }
+
+  private touch(objectKey: string): void {
+    const entry = this.entries.get(objectKey);
+    if (!entry) return;
+    this.entries.delete(objectKey);
+    this.entries.set(objectKey, { ...entry });
+  }
+
+  private removeEntry(objectKey: string, allowMappedDelete: boolean): void {
+    if (this.pinnedKeys.has(objectKey)) return;
+    const entry = this.entries.get(objectKey);
+    if (!entry) return;
+    try {
+      unlinkSync(entry.path);
+    } catch {
+      // ignore remove failures
+    }
+    this.totalBytes = Math.max(0, this.totalBytes - entry.size);
+    this.entries.delete(objectKey);
+    this.mappedBundles.delete(objectKey);
+  }
+
+  private safeStat(path: string): { size: number } | null {
+    try {
+      return existsSync(path) ? { size: statSync(path).size } : null;
+    } catch {
+      return null;
+    }
+  }
+
+  private readPrefix(path: string, byteLength: number): Result<Uint8Array, CompanionFileCacheError> {
+    try {
+      const fd = openSync(path, "r");
+      try {
+        const out = new Uint8Array(byteLength);
+        const bytesRead = readSync(fd, out, 0, byteLength, 0);
+        return Result.ok(out.subarray(0, bytesRead));
+      } finally {
+        closeSync(fd);
+      }
+    } catch (e: unknown) {
+      return invalidCompanionCache(String((e as any)?.message ?? e));
+    }
+  }
+}

package/src/search/companion_format.ts

@@ -0,0 +1,313 @@
+import { Result } from "better-result";
+import { decodeAggSegmentCompanionResult, encodeAggSegmentCompanion, type AggSectionInput, type AggSectionView } from "./agg_format";
+import { decodeColSegmentCompanionResult, encodeColSegmentCompanion, type ColSectionInput, type ColSectionView } from "./col_format";
+import { decodeFtsSegmentCompanionResult, encodeFtsSegmentCompanion, type FtsSectionInput, type FtsSectionView } from "./fts_format";
+import {
+  decodeMetricsBlockSegmentCompanionResult,
+  encodeMetricsBlockSegmentCompanion,
+  type MetricsBlockSectionInput,
+  type MetricsBlockSectionView,
+} from "../profiles/metrics/block_format";
+import type { SearchCompanionPlan } from "./companion_plan";
+import { BinaryCursor, BinaryWriter, concatBytes, readU16, readU32, readU64 } from "./binary/codec";
+import { streamHash16Hex } from "../util/stream_paths";
+
+const MAGIC = new TextEncoder().encode("PSCIX2");
+const MAJOR_VERSION = 2;
+const HEADER_BYTES = 58;
+const SECTION_ENTRY_BYTES = 28;
+export const PSCIX2_MAX_SECTION_COUNT = 4;
+export const PSCIX2_MAX_TOC_BYTES = HEADER_BYTES + SECTION_ENTRY_BYTES * PSCIX2_MAX_SECTION_COUNT;
+
+const SECTION_KIND_CODE = {
+  col: 1,
+  fts: 2,
+  agg: 3,
+  mblk: 4,
+} as const;
+
+const CODE_SECTION_KIND = {
+  1: "col",
+  2: "fts",
+  3: "agg",
+  4: "mblk",
+} as const;
+
+export type CompanionSectionKind = "col" | "fts" | "agg" | "mblk";
+
+export type CompanionSectionInputMap = {
+  col?: ColSectionInput;
+  fts?: FtsSectionInput;
+  agg?: AggSectionInput;
+  mblk?: MetricsBlockSectionInput;
+};
+
+export type CompanionSectionMap = {
+  col?: ColSectionView;
+  fts?: FtsSectionView;
+  agg?: AggSectionView;
+  mblk?: MetricsBlockSectionView;
+};
+
+export type CompanionTocSection = {
+  kind: CompanionSectionKind;
+  version: number;
+  compression: number;
+  flags: number;
+  offset: number;
+  length: number;
+  dir_length: number;
+  logical_length: number;
+};
+
+export type CompanionToc = {
+  version: 2;
+  plan_generation: number;
+  segment_index: number;
+  stream_hash16: string;
+  sections: CompanionTocSection[];
+};
+
+export type BundledSegmentCompanion = {
+  toc: CompanionToc;
+  sections: CompanionSectionMap;
+};
+
+export type EncodedCompanionSectionPayload = {
+  kind: CompanionSectionKind;
+  version: number;
+  compression: number;
+  flags: number;
+  dirLength: number;
+  logicalLength: number;
+  payload: Uint8Array;
+};
+
+type CompanionFormatError = { kind: "invalid_companion"; message: string };
+
+function invalidCompanion<T = never>(message: string): Result<T, CompanionFormatError> {
+  return Result.err({ kind: "invalid_companion", message });
+}
+
+function sectionKindCode(kind: CompanionSectionKind): number {
+  return SECTION_KIND_CODE[kind];
+}
+
+function encodeSectionPayload(
+  kind: CompanionSectionKind,
+  section: CompanionSectionInputMap[CompanionSectionKind],
+  plan: SearchCompanionPlan
+): EncodedCompanionSectionPayload {
+  if (kind === "col") {
+    const payload = encodeColSegmentCompanion(section as ColSectionInput, plan);
+    return { kind, version: 2, compression: 0, flags: 0, dirLength: 8, logicalLength: payload.byteLength, payload };
+  }
+  if (kind === "fts") {
+    const payload = encodeFtsSegmentCompanion(section as FtsSectionInput, plan);
+    return { kind, version: 2, compression: 0, flags: 0, dirLength: 8, logicalLength: payload.byteLength, payload };
+  }
+  if (kind === "agg") {
+    const payload = encodeAggSegmentCompanion(section as AggSectionInput, plan);
+    return { kind, version: 2, compression: 0, flags: 0, dirLength: 4, logicalLength: payload.byteLength, payload };
+  }
+  const payload = encodeMetricsBlockSegmentCompanion(section as MetricsBlockSectionInput);
+  return { kind, version: 2, compression: 0, flags: 0, dirLength: 20, logicalLength: payload.byteLength, payload };
+}
+
+export function encodeCompanionSectionPayload(
+  kind: CompanionSectionKind,
+  section: CompanionSectionInputMap[CompanionSectionKind],
+  plan: SearchCompanionPlan
+): EncodedCompanionSectionPayload {
+  return encodeSectionPayload(kind, section, plan);
+}
+
+function decodeSectionResult(
+  kind: CompanionSectionKind,
+  bytes: Uint8Array,
+  plan: SearchCompanionPlan
+): Result<CompanionSectionMap[CompanionSectionKind], CompanionFormatError> {
+  if (kind === "col") {
+    const decoded = decodeColSegmentCompanionResult(bytes, plan);
+    if (Result.isError(decoded)) return invalidCompanion(decoded.error.message);
+    return Result.ok(decoded.value as CompanionSectionMap[CompanionSectionKind]);
+  }
+  if (kind === "fts") {
+    const decoded = decodeFtsSegmentCompanionResult(bytes, plan);
+    if (Result.isError(decoded)) return invalidCompanion(decoded.error.message);
+    return Result.ok(decoded.value as CompanionSectionMap[CompanionSectionKind]);
+  }
+  if (kind === "agg") {
+    const decoded = decodeAggSegmentCompanionResult(bytes, plan);
+    if (Result.isError(decoded)) return invalidCompanion(decoded.error.message);
+    return Result.ok(decoded.value as CompanionSectionMap[CompanionSectionKind]);
+  }
+  const decoded = decodeMetricsBlockSegmentCompanionResult(bytes);
+  if (Result.isError(decoded)) return invalidCompanion(decoded.error.message);
+  return Result.ok(decoded.value as CompanionSectionMap[CompanionSectionKind]);
+}
+
+export function encodeBundledSegmentCompanion(companion: {
+  stream: string;
+  segment_index: number;
+  plan_generation: number;
+  plan: SearchCompanionPlan;
+  sections: CompanionSectionInputMap;
+}): Uint8Array {
+  const sectionPayloads: EncodedCompanionSectionPayload[] = [];
+  for (const kind of ["col", "fts", "agg", "mblk"] as CompanionSectionKind[]) {
+    const section = companion.sections[kind];
+    if (!section) continue;
+    sectionPayloads.push(encodeSectionPayload(kind, section, companion.plan));
+  }
+  return encodeBundledSegmentCompanionFromPayloads({
+    stream: companion.stream,
+    segment_index: companion.segment_index,
+    plan_generation: companion.plan_generation,
+    sections: sectionPayloads,
+  });
+}
+
+export function encodeBundledSegmentCompanionFromPayloads(companion: {
+  stream: string;
+  segment_index: number;
+  plan_generation: number;
+  sections: EncodedCompanionSectionPayload[];
+}): Uint8Array {
+  const writer = new BinaryWriter();
+  writer.writeBytes(MAGIC);
+  writer.writeU16(MAJOR_VERSION);
+  writer.writeU16(0);
+  writer.writeU16(companion.sections.length);
+  writer.writeU16(0);
+  writer.writeU32(companion.plan_generation);
+  writer.writeU64(BigInt(companion.segment_index));
+  writer.writeBytes(hexToBytes(streamHash16Hex(companion.stream)));
+  writer.writeBytes(new Uint8Array(16));
+
+  let payloadOffset = HEADER_BYTES + SECTION_ENTRY_BYTES * companion.sections.length;
+  const sectionTable = new BinaryWriter();
+  for (const section of companion.sections) {
+    sectionTable.writeU8(sectionKindCode(section.kind));
+    sectionTable.writeU8(section.version);
+    sectionTable.writeU8(section.compression);
+    sectionTable.writeU8(section.flags);
+    sectionTable.writeU64(BigInt(payloadOffset));
+    sectionTable.writeU64(BigInt(section.payload.byteLength));
+    sectionTable.writeU32(section.dirLength);
+    sectionTable.writeU32(section.logicalLength);
+    payloadOffset += section.payload.byteLength;
+  }
+  return concatBytes([writer.finish(), sectionTable.finish(), ...companion.sections.map((section) => section.payload)]);
+}
+
+export function decodeBundledSegmentCompanionTocResult(bytes: Uint8Array): Result<CompanionToc, CompanionFormatError> {
+  if (bytes.byteLength < HEADER_BYTES) return invalidCompanion("invalid PSCIX2 header");
+  for (let index = 0; index < MAGIC.byteLength; index++) {
+    if (bytes[index] !== MAGIC[index]) return invalidCompanion("invalid PSCIX2 magic");
+  }
+  const majorVersion = readU16(bytes, MAGIC.byteLength);
+  if (majorVersion !== MAJOR_VERSION) return invalidCompanion("unsupported PSCIX2 version");
+  const sectionCount = readU16(bytes, MAGIC.byteLength + 4);
+  if (sectionCount < 0 || sectionCount > PSCIX2_MAX_SECTION_COUNT) {
+    return invalidCompanion("invalid PSCIX2 section count");
+  }
+  if (bytes.byteLength < HEADER_BYTES + SECTION_ENTRY_BYTES * sectionCount) {
+    return invalidCompanion("truncated PSCIX2 section table");
+  }
+  const planGeneration = readU32(bytes, MAGIC.byteLength + 8);
+  const segmentIndex = Number(readU64(bytes, MAGIC.byteLength + 12));
+  const streamHash16 = bytesToHex(bytes.subarray(MAGIC.byteLength + 20, MAGIC.byteLength + 36));
+  const sections: CompanionTocSection[] = [];
+  let offset = HEADER_BYTES;
+  for (let index = 0; index < sectionCount; index++) {
+    const kindCode = bytes[offset]!;
+    const kind = CODE_SECTION_KIND[kindCode as keyof typeof CODE_SECTION_KIND];
+    if (!kind) return invalidCompanion("invalid PSCIX2 section kind");
+    sections.push({
+      kind,
+      version: bytes[offset + 1]!,
+      compression: bytes[offset + 2]!,
+      flags: bytes[offset + 3]!,
+      offset: Number(readU64(bytes, offset + 4)),
+      length: Number(readU64(bytes, offset + 12)),
+      dir_length: readU32(bytes, offset + 20),
+      logical_length: readU32(bytes, offset + 24),
+    });
+    offset += SECTION_ENTRY_BYTES;
+  }
+  return Result.ok({
+    version: 2,
+    plan_generation: planGeneration,
+    segment_index: segmentIndex,
+    stream_hash16: streamHash16,
+    sections,
+  });
+}
+
+export function decodeBundledSegmentCompanionSectionResult<K extends CompanionSectionKind>(
+  bytes: Uint8Array,
+  kind: K,
+  plan: SearchCompanionPlan
+): Result<CompanionSectionMap[K] | null, CompanionFormatError> {
+  const tocRes = decodeBundledSegmentCompanionTocResult(bytes);
+  if (Result.isError(tocRes)) return tocRes;
+  return decodeBundledSegmentCompanionSectionFromTocResult(bytes, tocRes.value, kind, plan);
+}
+
+export function decodeBundledSegmentCompanionSectionFromTocResult<K extends CompanionSectionKind>(
+  bytes: Uint8Array,
+  toc: CompanionToc,
+  kind: K,
+  plan: SearchCompanionPlan
+): Result<CompanionSectionMap[K] | null, CompanionFormatError> {
+  const section = toc.sections.find((entry) => entry.kind === kind);
+  if (!section) return Result.ok(null);
+  const sectionEnd = section.offset + section.length;
+  if (section.offset < 0 || section.length < 0 || sectionEnd > bytes.byteLength) {
+    return invalidCompanion("invalid PSCIX2 section bounds");
+  }
+  const decodedRes = decodeSectionResult(kind, bytes.subarray(section.offset, sectionEnd), plan);
+  if (Result.isError(decodedRes)) return decodedRes;
+  return Result.ok(decodedRes.value as CompanionSectionMap[K]);
+}
+
+export function decodeCompanionSectionPayloadResult<K extends CompanionSectionKind>(
+  kind: K,
+  bytes: Uint8Array,
+  plan: SearchCompanionPlan
+): Result<NonNullable<CompanionSectionMap[K]>, CompanionFormatError> {
+  const decodedRes = decodeSectionResult(kind, bytes, plan);
+  if (Result.isError(decodedRes)) return decodedRes as Result<NonNullable<CompanionSectionMap[K]>, CompanionFormatError>;
+  if (!decodedRes.value) return invalidCompanion(`missing PSCIX2 ${kind} payload`);
+  return Result.ok(decodedRes.value as NonNullable<CompanionSectionMap[K]>);
+}
+
+export function decodeBundledSegmentCompanionResult(
+  bytes: Uint8Array,
+  plan: SearchCompanionPlan
+): Result<BundledSegmentCompanion, CompanionFormatError> {
+  const tocRes = decodeBundledSegmentCompanionTocResult(bytes);
+  if (Result.isError(tocRes)) return tocRes;
+  const sections: CompanionSectionMap = {};
+  for (const entry of tocRes.value.sections) {
+    const decodedRes = decodeBundledSegmentCompanionSectionFromTocResult(bytes, tocRes.value, entry.kind, plan);
+    if (Result.isError(decodedRes)) return decodedRes;
+    if (decodedRes.value) (sections as Record<string, unknown>)[entry.kind] = decodedRes.value;
+  }
+  return Result.ok({ toc: tocRes.value, sections });
+}
+
+function hexToBytes(value: string): Uint8Array {
+  const out = new Uint8Array(value.length / 2);
+  for (let index = 0; index < value.length; index += 2) {
+    out[index / 2] = Number.parseInt(value.slice(index, index + 2), 16);
+  }
+  return out;
+}
+
+function bytesToHex(value: Uint8Array): string {
+  return Array.from(value)
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("");
+}