@helipod/id-codec 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,281 @@
+import { SerializedKeyRange } from '@helipod/index-key-codec';
+
+/**
+ * Crockford Base32 — case-insensitive, omits the ambiguous letters I, L, O, U.
+ * Used to render binary document ids as compact, human-safe, copy-pasteable strings.
+ */
+declare const CROCKFORD_ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz";
+declare class Base32Error extends Error {
+    name: string;
+}
+declare function base32Encode(bytes: Uint8Array): string;
+declare function base32Decode(text: string): Uint8Array;
+declare function isValidBase32(text: string): boolean;
+
+/**
+ * Fletcher-16 checksum. Appended to each document id so a corrupted or fabricated id is
+ * rejected client-side without a database round-trip.
+ */
+declare function fletcher16(bytes: Uint8Array): number;
+declare function verifyFletcher16(bytes: Uint8Array, checksum: number): boolean;
+
+/**
+ * LEB128 unsigned varint over uint32 (1–5 bytes). Encodes the table number that
+ * prefixes a document id, so small system table numbers stay compact.
+ */
+declare class VarintError extends Error {
+    name: string;
+}
+declare function varintEncode(value: number): Uint8Array;
+interface VarintDecodeResult {
+    value: number;
+    bytesRead: number;
+}
+declare function varintDecode(bytes: Uint8Array, offset?: number): VarintDecodeResult;
+declare function varintEncodedLength(value: number): number;
+
+type InternalId = Uint8Array;
+declare const INTERNAL_ID_BYTES = 16;
+interface InternalDocumentId {
+    tableNumber: number;
+    internalId: InternalId;
+}
+declare const docIdBrand: unique symbol;
+type DocumentId = string & {
+    readonly [docIdBrand]: "DocumentId";
+};
+declare class DocumentIdError extends Error {
+    name: string;
+}
+declare function internalIdToHex(internalId: InternalId): string;
+declare function generateInternalId(): InternalId;
+declare function newDocumentId(tableNumber: number): InternalDocumentId;
+declare function encodeDocumentId(tableNumber: number, internalId: InternalId): DocumentId;
+declare function encodeInternalDocumentId(id: InternalDocumentId): DocumentId;
+/** Mint a full encoded document id CLIENT-SIDE (same shape and entropy as the engine's own
+ *  minting — 16 random bytes). The engine validates at insert; see client-supplied ids spec. */
+declare function mintEncodedDocumentId(tableNumber: number): DocumentId;
+declare function decodeDocumentId(encoded: string): InternalDocumentId;
+declare function tryDecodeDocumentId(encoded: string): InternalDocumentId | null;
+declare function isValidDocumentId(encoded: string, expectedTableNumber?: number): boolean;
+/** The encoded length in characters for ids of a given table number (31–37). */
+declare function getEncodedLength(tableNumber: number): number;
+declare function documentIdKey(id: InternalDocumentId): string;
+declare function parseDocumentIdKey(key: string): InternalDocumentId;
+declare function documentIdsEqual(a: InternalDocumentId, b: InternalDocumentId): boolean;
+
+/**
+ * Stable string identifiers the storage layer uses to name a table's document space and
+ * its indexes. Derived from the table *number* (not name) so renames never touch storage.
+ */
+declare function encodeStorageTableId(tableNumber: number): string;
+declare function decodeStorageTableId(tableId: string): number;
+declare function encodeStorageIndexId(tableNumber: number, indexName: string): string;
+declare function decodeStorageIndexId(indexId: string): {
+    tableNumber: number;
+    indexName: string;
+};
+
+/**
+ * Shared point-range conversion helpers — the canonical home for `keyToPointRange`/
+ * `docKeyToPointRange`, byte-for-byte identical to the versions that originally shipped in
+ * `ee/packages/fleet/src/ranges.ts` (Tier 3 Slice 1/2). Extracted here (Tier 3 Slice 8, Task 8.1) so
+ * `ee/packages/objectstore-substrate`'s replica reactive-tailer wiring can reuse them without taking
+ * a dependency on `@helipod/fleet` (an EE package objectstore-substrate must not import — the
+ * object-store substrate and the Postgres fleet are siblings, not a hierarchy).
+ *
+ * Homed in `@helipod/id-codec`, NOT `@helipod/index-key-codec`, despite `SerializedKeyRange`
+ * itself living in the latter: these functions bridge a STORAGE id (`decodeStorageIndexId`,
+ * `encodeStorageTableId` — this package's own `storage-id.ts`) to the engine's KEYSPACE id
+ * (`indexKeyspaceId`/`tableKeyspaceId` — `@helipod/index-key-codec`'s `keyspace.ts`), so they
+ * inherently need both id spaces. `@helipod/id-codec` already depends on
+ * `@helipod/index-key-codec` (see `jump-hash.ts`'s `encodeIndexKey` import), so this direction adds
+ * no new edge; the reverse — moving these into `index-key-codec` and having IT depend on
+ * `id-codec`'s storage-id helpers — would create an import cycle (`id-codec -> index-key-codec ->
+ * id-codec`). `id-codec` is therefore the only cycle-free canonical home for this bridge.
+ *
+ * `ee/packages/fleet/src/ranges.ts` re-exports both functions from here verbatim — fleet's public
+ * API and existing tests are unaffected by the move.
+ */
+
+/**
+ * Convert a single written `(indexId, key)` pair into the sync handler's point range
+ * `[key, keySuccessor(key))` — the exact same half-open encoding `RangeSet.addKey` uses for a
+ * point read/write, so a follower's derived write range overlaps a subscription's recorded read
+ * range under `rangesOverlap`.
+ *
+ * `indexId` here is the storage `index_id` — the STORAGE index id produced by
+ * `encodeStorageIndexId`, format `"<tableNumber>/<indexName>"` (e.g. `"10001/by_creation"`). That
+ * is NOT the same string as the engine's keyspace id (`indexKeyspaceId`'s `"index:<table>:<name>"`
+ * / `tableKeyspaceId`'s `"table:<table>"`), which is what `SerializedKeyRange.keyspace` — and
+ * `rangesOverlap` — actually compare on. So the storage id must be decoded back into its parts and
+ * the keyspace REBUILT with the engine's own helper; feeding the raw storage id straight through
+ * silently produces ranges that can never overlap anything.
+ */
+declare function keyToPointRange(indexId: string, key: Uint8Array): SerializedKeyRange;
+/**
+ * Convert a single written `(table_id, internal_id)` pair — e.g. from a `DerivedInvalidation`'s (or
+ * `AppliedInvalidation`'s) `writtenDocs` — into the DOCUMENT-keyspace point range a bare
+ * `ctx.db.get(id)` read records: `[internalId, keySuccessor(internalId))` under
+ * `tableKeyspaceId(table)`. Unlike `keyToPointRange` above, no decode/recompose round trip is
+ * needed here — `table_id` is already `encodeStorageTableId(tableNumber)`, exactly the string
+ * `tableKeyspaceId` expects; it is NOT a storage *index* id, so there is no separate "storage id"
+ * vs "engine keyspace id" split to bridge for the table half. This must match
+ * `single-writer-transactor.ts`'s `docKeyspace()` (`tableKeyspaceId(encodeStorageTableId(...))`)
+ * plus its `RangeSet.addKey(docKeyspace(id), id.internalId)` byte-for-byte, or a follower never
+ * invalidates a subscription whose only read was a point `get`.
+ */
+declare function docKeyToPointRange(tableId: string, internalId: Uint8Array): SerializedKeyRange;
+
+/**
+ * Sharding primitives — scale-seam #1. A conversation (or any partition) maps to a shard
+ * key derived from a document field; a shard router maps that key to the single-writer
+ * shard that owns it. At **Tier 0 there is exactly one shard (`"default"`)** and the
+ * router always returns it, but the seam exists in the interfaces from day one so Tier 2
+ * per-conversation sharding is a config swap, not an engine rewrite.
+ */
+type ShardId = string;
+type ShardKey = string;
+declare const DEFAULT_SHARD: ShardId;
+interface ShardKeyResolverInput {
+    table: string;
+    document: Record<string, unknown>;
+}
+/** Extracts the shard key from a document, or null if the table isn't sharded. */
+interface ShardKeyResolver {
+    resolve(input: ShardKeyResolverInput): ShardKey | null;
+}
+/** Tier 0: nothing is sharded — every document lives in the default shard. */
+declare class DefaultShardKeyResolver implements ShardKeyResolver {
+    resolve(): ShardKey | null;
+}
+/** Resolves the shard key from a configured field per table (e.g. `messages.conversationId`). */
+declare class FieldShardKeyResolver implements ShardKeyResolver {
+    private readonly fieldByTable;
+    constructor(fieldByTable: ReadonlyMap<string, string>);
+    resolve({ table, document }: ShardKeyResolverInput): ShardKey | null;
+}
+/**
+ * Routes shard keys and clients to shards/nodes. Tier 2 implements consistent hashing
+ * (document→committer) and rendezvous hashing (client→sync node); `TStub` is the
+ * per-shard handle (e.g. a Durable Object stub).
+ */
+interface ShardRouter<TStub = unknown> {
+    getShardForKey(shardKey: ShardKey | null): ShardId;
+    getShardForDocument(table: string, shardKey: ShardKey | null): ShardId;
+    getSyncNodeId(clientId: string): string;
+    resolveStub?(shardId: ShardId): TStub;
+}
+/** Tier 0 router: one shard, one local sync node. */
+declare class SimpleShardRouter implements ShardRouter {
+    getShardForKey(_shardKey: ShardKey | null): ShardId;
+    getShardForDocument(_table: string, _shardKey: ShardKey | null): ShardId;
+    getSyncNodeId(_clientId: string): string;
+}
+
+/**
+ * Map a 64-bit `key` to a bucket in `[0, buckets)`. The reference ~10-line algorithm: walk a
+ * pseudo-random sequence of "jump" points, keeping the last one that lands below `buckets`.
+ * Deterministic and allocation-free; `buckets` must be ≥ 1.
+ */
+declare function jumpConsistentHash(key: bigint, buckets: number): number;
+/**
+ * Resolve a shard-key VALUE (a scalar: string/number/bigint/boolean/null/bytes) to its shard id
+ * under `numShards`. Canonicalizes via the engine's own index-key encoding so routing is stable
+ * across the arg → route and document → route paths. Slot 0 → `"default"`, slot k → `"s"+k`.
+ */
+declare function shardIdForKeyValue(value: unknown, numShards: number): ShardId;
+/**
+ * The canonical ordered shard-id list for `numShards` shards: `["default", "s1", …, "s{N-1}"]`.
+ * The array INDEX is the slot number — slot 0 is `"default"`, slot k is `"s"+k` — matching
+ * `shardIdForKeyValue`'s slot→id mapping exactly. This is the ONE source of truth for the
+ * slot↔shardId contract the fleet's per-shard commit pool (`NodePgClient`'s `commitPool.shards`),
+ * per-slot advisory locks (`tryAcquireShardLock(slot)`), and lease acquire-all loop all share, so
+ * nobody hand-rolls (and risks disagreeing on) the numbering. `numShards` must be ≥ 1.
+ */
+declare function shardIdList(numShards: number): ShardId[];
+/**
+ * The B2a `ShardRouter`: jump-consistent-hash routing over `numShards` shards. Single-node, so
+ * every client resolves to one local sync node. `getShardForKey`/`getShardForDocument` take the
+ * already-extracted shard-key value (a string, per the seam); `shardIdForKeyValue` is the
+ * value-typed entry point the executor and kernel call directly with the raw arg/field value.
+ */
+declare class JumpShardRouter implements ShardRouter {
+    private readonly numShards;
+    constructor(numShards: number);
+    getShardForKey(shardKey: ShardKey | null): ShardId;
+    getShardForDocument(_table: string, shardKey: ShardKey | null): ShardId;
+    getSyncNodeId(_clientId: string): string;
+}
+
+/**
+ * The table registry assigns each table a stable numeric id (embedded in document ids).
+ * System tables (`_`-prefixed) get numbers 1–9999; user tables start at 10001, leaving a
+ * reserved gap. The DocStore-backed durable registry arrives in M2; this in-memory one is
+ * the canonical interface + the Tier 0 / test implementation.
+ */
+type TableVisibility = "user" | "system";
+type TableState = "active" | "creating" | "deleting";
+interface TableInfo {
+    name: string;
+    tableNumber: number;
+    visibility: TableVisibility;
+    state: TableState;
+    /** The document field used as the shard key (seam #1), or null. */
+    shardKey: string | null;
+}
+interface AllocateOptions {
+    visibility?: TableVisibility;
+    shardKey?: string | null;
+}
+interface TableRegistry {
+    getByName(name: string): TableInfo | undefined;
+    getByNumber(tableNumber: number): TableInfo | undefined;
+    allocate(name: string, options?: AllocateOptions): TableInfo;
+    list(): TableInfo[];
+}
+interface PreassignOptions {
+    visibility?: TableVisibility;
+    shardKey?: string | null;
+    state?: TableState;
+}
+declare const SYSTEM_TABLE_NUMBER_MIN = 1;
+declare const SYSTEM_TABLE_NUMBER_MAX = 9999;
+declare const USER_TABLE_NUMBER_START = 10001;
+/**
+ * Reserved table numbers for built-in app-namespace system tables. These MUST stay stable
+ * forever: a persisted `Id<"_storage">` encodes this number, so it must always decode back to
+ * the same table. Registry seeding pins them with `preassign(name, number)` before any other
+ * system table is auto-allocated, keeping their numbers deterministic across runs regardless of
+ * registration order. `_storage` (the file-storage feature's document table) is 20.
+ */
+declare const STORAGE_TABLE_NUMBER = 20;
+declare function isSystemTableName(name: string): boolean;
+declare function getFullTableName(name: string, componentPath: string): string;
+declare function parseFullTableName(fullName: string): {
+    componentPath: string;
+    name: string;
+};
+declare class MemoryTableRegistry implements TableRegistry {
+    private readonly byName;
+    private readonly byNumber;
+    private nextUser;
+    private nextSystem;
+    getByName(name: string): TableInfo | undefined;
+    getByNumber(tableNumber: number): TableInfo | undefined;
+    /** Idempotent: allocating an existing name returns the existing entry. */
+    allocate(name: string, options?: AllocateOptions): TableInfo;
+    list(): TableInfo[];
+    /**
+     * Pre-register a table at a KNOWN (already-live) number, so a later `allocate(name)` for the
+     * same name returns this number instead of minting a fresh one — used to seed a fresh registry
+     * with a running deploy's table numbers before composing a new schema, so existing tables
+     * (app AND component) never renumber; only genuinely-new tables get numbers above the seeded
+     * max. Idempotent/no-op if `name` is already known (first registration wins, matching
+     * `allocate`'s idempotency). Bumps the relevant `next*` counter so future `allocate` calls
+     * never collide with a preassigned number.
+     */
+    preassign(name: string, tableNumber: number, options?: PreassignOptions): TableInfo;
+}
+
+export { type AllocateOptions, Base32Error, CROCKFORD_ALPHABET, DEFAULT_SHARD, DefaultShardKeyResolver, type DocumentId, DocumentIdError, FieldShardKeyResolver, INTERNAL_ID_BYTES, type InternalDocumentId, type InternalId, JumpShardRouter, MemoryTableRegistry, STORAGE_TABLE_NUMBER, SYSTEM_TABLE_NUMBER_MAX, SYSTEM_TABLE_NUMBER_MIN, type ShardId, type ShardKey, type ShardKeyResolver, type ShardKeyResolverInput, type ShardRouter, SimpleShardRouter, type TableInfo, type TableRegistry, type TableState, type TableVisibility, USER_TABLE_NUMBER_START, type VarintDecodeResult, VarintError, base32Decode, base32Encode, decodeDocumentId, decodeStorageIndexId, decodeStorageTableId, docKeyToPointRange, documentIdKey, documentIdsEqual, encodeDocumentId, encodeInternalDocumentId, encodeStorageIndexId, encodeStorageTableId, fletcher16, generateInternalId, getEncodedLength, getFullTableName, internalIdToHex, isSystemTableName, isValidBase32, isValidDocumentId, jumpConsistentHash, keyToPointRange, mintEncodedDocumentId, newDocumentId, parseDocumentIdKey, parseFullTableName, shardIdForKeyValue, shardIdList, tryDecodeDocumentId, varintDecode, varintEncode, varintEncodedLength, verifyFletcher16 };

package/dist/index.js

@@ -0,0 +1,475 @@
+// src/base32.ts
+var CROCKFORD_ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz";
+var DECODE = (() => {
+  const map = {};
+  for (let i = 0; i < CROCKFORD_ALPHABET.length; i++) {
+    const ch = CROCKFORD_ALPHABET[i];
+    map[ch] = i;
+    map[ch.toUpperCase()] = i;
+  }
+  map["i"] = map["I"] = 1;
+  map["l"] = map["L"] = 1;
+  map["o"] = map["O"] = 0;
+  return map;
+})();
+var Base32Error = class extends Error {
+  name = "Base32Error";
+};
+function base32Encode(bytes) {
+  let bits = 0;
+  let value = 0;
+  let out = "";
+  for (let i = 0; i < bytes.length; i++) {
+    value = value << 8 | bytes[i];
+    bits += 8;
+    while (bits >= 5) {
+      out += CROCKFORD_ALPHABET[value >>> bits - 5 & 31];
+      bits -= 5;
+    }
+  }
+  if (bits > 0) out += CROCKFORD_ALPHABET[value << 5 - bits & 31];
+  return out;
+}
+function base32Decode(text) {
+  let bits = 0;
+  let value = 0;
+  const out = [];
+  for (const ch of text) {
+    const v = DECODE[ch];
+    if (v === void 0) throw new Base32Error(`invalid base32 character: ${JSON.stringify(ch)}`);
+    value = value << 5 | v;
+    bits += 5;
+    if (bits >= 8) {
+      out.push(value >>> bits - 8 & 255);
+      bits -= 8;
+    }
+  }
+  if (bits > 0 && (value & (1 << bits) - 1) !== 0) {
+    throw new Base32Error("non-canonical base32 padding bits");
+  }
+  return Uint8Array.from(out);
+}
+function isValidBase32(text) {
+  for (const ch of text) if (DECODE[ch] === void 0) return false;
+  return true;
+}
+
+// src/checksum.ts
+function fletcher16(bytes) {
+  let sum1 = 0;
+  let sum2 = 0;
+  for (let i = 0; i < bytes.length; i++) {
+    sum1 = (sum1 + bytes[i]) % 255;
+    sum2 = (sum2 + sum1) % 255;
+  }
+  return sum2 << 8 | sum1;
+}
+function verifyFletcher16(bytes, checksum) {
+  return fletcher16(bytes) === checksum;
+}
+
+// src/varint.ts
+var VarintError = class extends Error {
+  name = "VarintError";
+};
+var UINT32_MAX = 4294967295;
+function varintEncode(value) {
+  if (!Number.isInteger(value) || value < 0 || value > UINT32_MAX) {
+    throw new VarintError(`varint value out of uint32 range: ${value}`);
+  }
+  const out = [];
+  let v = value;
+  do {
+    let byte = v & 127;
+    v = Math.floor(v / 128);
+    if (v > 0) byte |= 128;
+    out.push(byte);
+  } while (v > 0);
+  return Uint8Array.from(out);
+}
+function varintDecode(bytes, offset = 0) {
+  let result = 0;
+  let shift = 0;
+  let pos = offset;
+  while (true) {
+    if (pos >= bytes.length) throw new VarintError("varint truncated");
+    const byte = bytes[pos];
+    result += (byte & 127) * 2 ** shift;
+    pos += 1;
+    if ((byte & 128) === 0) break;
+    shift += 7;
+    if (shift > 28) throw new VarintError("varint exceeds uint32");
+  }
+  if (result > UINT32_MAX) throw new VarintError("varint exceeds uint32");
+  return { value: result, bytesRead: pos - offset };
+}
+function varintEncodedLength(value) {
+  return varintEncode(value).length;
+}
+
+// src/document-id.ts
+var INTERNAL_ID_BYTES = 16;
+var CHECKSUM_BYTES = 2;
+var DocumentIdError = class extends Error {
+  name = "DocumentIdError";
+};
+function concatBytes(...parts) {
+  const total = parts.reduce((n, p) => n + p.length, 0);
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const p of parts) {
+    out.set(p, offset);
+    offset += p.length;
+  }
+  return out;
+}
+function internalIdToHex(internalId) {
+  let hex = "";
+  for (let i = 0; i < internalId.length; i++) hex += internalId[i].toString(16).padStart(2, "0");
+  return hex;
+}
+function hexToInternalId(hex) {
+  if (hex.length % 2 !== 0) throw new DocumentIdError("odd-length hex");
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    const byte = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    if (Number.isNaN(byte)) throw new DocumentIdError("invalid hex");
+    out[i] = byte;
+  }
+  return out;
+}
+function generateInternalId() {
+  const bytes = new Uint8Array(INTERNAL_ID_BYTES);
+  crypto.getRandomValues(bytes);
+  return bytes;
+}
+function newDocumentId(tableNumber) {
+  return { tableNumber, internalId: generateInternalId() };
+}
+function encodeDocumentId(tableNumber, internalId) {
+  if (internalId.length !== INTERNAL_ID_BYTES) {
+    throw new DocumentIdError(`internalId must be ${INTERNAL_ID_BYTES} bytes, got ${internalId.length}`);
+  }
+  const prefix = concatBytes(varintEncode(tableNumber), internalId);
+  const checksum = fletcher16(prefix);
+  const checksumBytes = new Uint8Array([checksum >>> 8 & 255, checksum & 255]);
+  return base32Encode(concatBytes(prefix, checksumBytes));
+}
+function encodeInternalDocumentId(id) {
+  return encodeDocumentId(id.tableNumber, id.internalId);
+}
+function mintEncodedDocumentId(tableNumber) {
+  return encodeInternalDocumentId(newDocumentId(tableNumber));
+}
+function decodeDocumentId(encoded) {
+  let bytes;
+  try {
+    bytes = base32Decode(encoded);
+  } catch (e) {
+    throw new DocumentIdError(e instanceof Base32Error ? e.message : "invalid base32");
+  }
+  let tableNumber;
+  let bytesRead;
+  try {
+    ({ value: tableNumber, bytesRead } = varintDecode(bytes, 0));
+  } catch {
+    throw new DocumentIdError("invalid table number");
+  }
+  const internalIdEnd = bytesRead + INTERNAL_ID_BYTES;
+  if (bytes.length !== internalIdEnd + CHECKSUM_BYTES) {
+    throw new DocumentIdError("incorrect id length");
+  }
+  const internalId = bytes.slice(bytesRead, internalIdEnd);
+  const checksum = bytes[internalIdEnd] << 8 | bytes[internalIdEnd + 1];
+  const prefix = bytes.slice(0, internalIdEnd);
+  if (!verifyFletcher16(prefix, checksum)) throw new DocumentIdError("checksum mismatch");
+  return { tableNumber, internalId };
+}
+function tryDecodeDocumentId(encoded) {
+  try {
+    return decodeDocumentId(encoded);
+  } catch {
+    return null;
+  }
+}
+function isValidDocumentId(encoded, expectedTableNumber) {
+  const decoded = tryDecodeDocumentId(encoded);
+  if (decoded === null) return false;
+  return expectedTableNumber === void 0 || decoded.tableNumber === expectedTableNumber;
+}
+function getEncodedLength(tableNumber) {
+  const byteLen = varintEncodedLength(tableNumber) + INTERNAL_ID_BYTES + CHECKSUM_BYTES;
+  return Math.ceil(byteLen * 8 / 5);
+}
+function documentIdKey(id) {
+  return `${id.tableNumber}:${internalIdToHex(id.internalId)}`;
+}
+function parseDocumentIdKey(key) {
+  const sep = key.indexOf(":");
+  if (sep < 0) throw new DocumentIdError("invalid document id key");
+  const tableNumber = Number.parseInt(key.slice(0, sep), 10);
+  if (!Number.isInteger(tableNumber)) throw new DocumentIdError("invalid table number in key");
+  return { tableNumber, internalId: hexToInternalId(key.slice(sep + 1)) };
+}
+function documentIdsEqual(a, b) {
+  if (a.tableNumber !== b.tableNumber || a.internalId.length !== b.internalId.length) return false;
+  for (let i = 0; i < a.internalId.length; i++) if (a.internalId[i] !== b.internalId[i]) return false;
+  return true;
+}
+
+// src/storage-id.ts
+function encodeStorageTableId(tableNumber) {
+  return String(tableNumber);
+}
+function decodeStorageTableId(tableId) {
+  const n = Number.parseInt(tableId, 10);
+  if (!Number.isInteger(n) || String(n) !== tableId) throw new Error(`invalid storage table id: ${tableId}`);
+  return n;
+}
+function encodeStorageIndexId(tableNumber, indexName) {
+  return `${tableNumber}/${indexName}`;
+}
+function decodeStorageIndexId(indexId) {
+  const sep = indexId.indexOf("/");
+  if (sep < 0) throw new Error(`invalid storage index id: ${indexId}`);
+  return {
+    tableNumber: decodeStorageTableId(indexId.slice(0, sep)),
+    indexName: indexId.slice(sep + 1)
+  };
+}
+
+// src/point-range.ts
+import {
+  keySuccessor,
+  serializeKeyRange,
+  indexKeyspaceId,
+  tableKeyspaceId
+} from "@helipod/index-key-codec";
+function keyToPointRange(indexId, key) {
+  const { tableNumber, indexName } = decodeStorageIndexId(indexId);
+  const keyspace = indexKeyspaceId(encodeStorageTableId(tableNumber), indexName);
+  return serializeKeyRange({ keyspace, start: key, end: keySuccessor(key) });
+}
+function docKeyToPointRange(tableId, internalId) {
+  const keyspace = tableKeyspaceId(tableId);
+  return serializeKeyRange({ keyspace, start: internalId, end: keySuccessor(internalId) });
+}
+
+// src/shard.ts
+var DEFAULT_SHARD = "default";
+var DefaultShardKeyResolver = class {
+  resolve() {
+    return null;
+  }
+};
+var FieldShardKeyResolver = class {
+  constructor(fieldByTable) {
+    this.fieldByTable = fieldByTable;
+  }
+  fieldByTable;
+  resolve({ table, document }) {
+    const field = this.fieldByTable.get(table);
+    if (field === void 0) return null;
+    const value = document[field];
+    return value === void 0 || value === null ? null : String(value);
+  }
+};
+var SimpleShardRouter = class {
+  getShardForKey(_shardKey) {
+    return DEFAULT_SHARD;
+  }
+  getShardForDocument(_table, _shardKey) {
+    return DEFAULT_SHARD;
+  }
+  getSyncNodeId(_clientId) {
+    return "local";
+  }
+};
+
+// src/jump-hash.ts
+import { encodeIndexKey } from "@helipod/index-key-codec";
+var U64_MASK = 0xffffffffffffffffn;
+var LCG_MULT = 2862933555777941757n;
+function jumpConsistentHash(key, buckets) {
+  if (buckets < 1) throw new RangeError(`buckets must be >= 1, got ${buckets}`);
+  let k = BigInt.asUintN(64, key);
+  let b = -1n;
+  let j = 0n;
+  const n = BigInt(buckets);
+  while (j < n) {
+    b = j;
+    k = k * LCG_MULT + 1n & U64_MASK;
+    const denom = Number(k >> 33n) + 1;
+    j = BigInt(Math.floor((Number(b) + 1) * (2147483648 / denom)));
+  }
+  return Number(b);
+}
+function fnv1a64(bytes) {
+  let h = 0xcbf29ce484222325n;
+  for (let i = 0; i < bytes.length; i++) {
+    h ^= BigInt(bytes[i]);
+    h = h * 0x100000001b3n & U64_MASK;
+  }
+  return h;
+}
+function shardIdForKeyValue(value, numShards) {
+  const bytes = encodeIndexKey([value]);
+  const slot = jumpConsistentHash(fnv1a64(bytes), Math.max(1, numShards));
+  return slot === 0 ? DEFAULT_SHARD : `s${slot}`;
+}
+function shardIdList(numShards) {
+  if (numShards < 1) throw new RangeError(`numShards must be >= 1, got ${numShards}`);
+  const ids = [DEFAULT_SHARD];
+  for (let slot = 1; slot < numShards; slot++) ids.push(`s${slot}`);
+  return ids;
+}
+var JumpShardRouter = class {
+  constructor(numShards) {
+    this.numShards = numShards;
+    if (numShards < 1) throw new RangeError(`numShards must be >= 1, got ${numShards}`);
+  }
+  numShards;
+  getShardForKey(shardKey) {
+    return shardKey === null ? DEFAULT_SHARD : shardIdForKeyValue(shardKey, this.numShards);
+  }
+  getShardForDocument(_table, shardKey) {
+    return this.getShardForKey(shardKey);
+  }
+  getSyncNodeId(_clientId) {
+    return "local";
+  }
+};
+
+// src/table-registry.ts
+var SYSTEM_TABLE_NUMBER_MIN = 1;
+var SYSTEM_TABLE_NUMBER_MAX = 9999;
+var USER_TABLE_NUMBER_START = 10001;
+var STORAGE_TABLE_NUMBER = 20;
+function isSystemTableName(name) {
+  return name.startsWith("_");
+}
+function getFullTableName(name, componentPath) {
+  return componentPath ? `${componentPath}/${name}` : name;
+}
+function parseFullTableName(fullName) {
+  const i = fullName.lastIndexOf("/");
+  return i < 0 ? { componentPath: "", name: fullName } : { componentPath: fullName.slice(0, i), name: fullName.slice(i + 1) };
+}
+var MemoryTableRegistry = class {
+  byName = /* @__PURE__ */ new Map();
+  byNumber = /* @__PURE__ */ new Map();
+  nextUser = USER_TABLE_NUMBER_START;
+  nextSystem = SYSTEM_TABLE_NUMBER_MIN;
+  getByName(name) {
+    return this.byName.get(name);
+  }
+  getByNumber(tableNumber) {
+    return this.byNumber.get(tableNumber);
+  }
+  /** Idempotent: allocating an existing name returns the existing entry. */
+  allocate(name, options = {}) {
+    const existing = this.byName.get(name);
+    if (existing) return existing;
+    const visibility = options.visibility ?? (isSystemTableName(name) ? "system" : "user");
+    let tableNumber;
+    if (visibility === "system") {
+      if (this.nextSystem > SYSTEM_TABLE_NUMBER_MAX) throw new Error("exhausted system table numbers");
+      tableNumber = this.nextSystem++;
+    } else {
+      tableNumber = this.nextUser++;
+    }
+    const info = {
+      name,
+      tableNumber,
+      visibility,
+      state: "active",
+      shardKey: options.shardKey ?? null
+    };
+    this.byName.set(name, info);
+    this.byNumber.set(tableNumber, info);
+    return info;
+  }
+  list() {
+    return [...this.byName.values()];
+  }
+  /**
+   * Pre-register a table at a KNOWN (already-live) number, so a later `allocate(name)` for the
+   * same name returns this number instead of minting a fresh one — used to seed a fresh registry
+   * with a running deploy's table numbers before composing a new schema, so existing tables
+   * (app AND component) never renumber; only genuinely-new tables get numbers above the seeded
+   * max. Idempotent/no-op if `name` is already known (first registration wins, matching
+   * `allocate`'s idempotency). Bumps the relevant `next*` counter so future `allocate` calls
+   * never collide with a preassigned number.
+   */
+  preassign(name, tableNumber, options = {}) {
+    const existing = this.byName.get(name);
+    if (existing) return existing;
+    const visibility = options.visibility ?? (isSystemTableName(name) ? "system" : "user");
+    const info = {
+      name,
+      tableNumber,
+      visibility,
+      state: options.state ?? "active",
+      shardKey: options.shardKey ?? null
+    };
+    this.byName.set(name, info);
+    this.byNumber.set(tableNumber, info);
+    if (visibility === "system") {
+      this.nextSystem = Math.max(this.nextSystem, tableNumber + 1);
+    } else {
+      this.nextUser = Math.max(this.nextUser, tableNumber + 1);
+    }
+    return info;
+  }
+};
+export {
+  Base32Error,
+  CROCKFORD_ALPHABET,
+  DEFAULT_SHARD,
+  DefaultShardKeyResolver,
+  DocumentIdError,
+  FieldShardKeyResolver,
+  INTERNAL_ID_BYTES,
+  JumpShardRouter,
+  MemoryTableRegistry,
+  STORAGE_TABLE_NUMBER,
+  SYSTEM_TABLE_NUMBER_MAX,
+  SYSTEM_TABLE_NUMBER_MIN,
+  SimpleShardRouter,
+  USER_TABLE_NUMBER_START,
+  VarintError,
+  base32Decode,
+  base32Encode,
+  decodeDocumentId,
+  decodeStorageIndexId,
+  decodeStorageTableId,
+  docKeyToPointRange,
+  documentIdKey,
+  documentIdsEqual,
+  encodeDocumentId,
+  encodeInternalDocumentId,
+  encodeStorageIndexId,
+  encodeStorageTableId,
+  fletcher16,
+  generateInternalId,
+  getEncodedLength,
+  getFullTableName,
+  internalIdToHex,
+  isSystemTableName,
+  isValidBase32,
+  isValidDocumentId,
+  jumpConsistentHash,
+  keyToPointRange,
+  mintEncodedDocumentId,
+  newDocumentId,
+  parseDocumentIdKey,
+  parseFullTableName,
+  shardIdForKeyValue,
+  shardIdList,
+  tryDecodeDocumentId,
+  varintDecode,
+  varintEncode,
+  varintEncodedLength,
+  verifyFletcher16
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/base32.ts","../src/checksum.ts","../src/varint.ts","../src/document-id.ts","../src/storage-id.ts","../src/point-range.ts","../src/shard.ts","../src/jump-hash.ts","../src/table-registry.ts"],"sourcesContent":["/**\n * Crockford Base32 — case-insensitive, omits the ambiguous letters I, L, O, U.\n * Used to render binary document ids as compact, human-safe, copy-pasteable strings.\n */\nexport const CROCKFORD_ALPHABET = \"0123456789abcdefghjkmnpqrstvwxyz\"; // omits i l o u\n\nconst DECODE: Record<string, number> = (() => {\n  const map: Record<string, number> = {};\n  for (let i = 0; i < CROCKFORD_ALPHABET.length; i++) {\n    const ch = CROCKFORD_ALPHABET[i]!;\n    map[ch] = i;\n    map[ch.toUpperCase()] = i;\n  }\n  // Crockford normalization of look-alikes.\n  map[\"i\"] = map[\"I\"] = 1;\n  map[\"l\"] = map[\"L\"] = 1;\n  map[\"o\"] = map[\"O\"] = 0;\n  return map;\n})();\n\nexport class Base32Error extends Error {\n  override name = \"Base32Error\";\n}\n\nexport function base32Encode(bytes: Uint8Array): string {\n  let bits = 0;\n  let value = 0;\n  let out = \"\";\n  for (let i = 0; i < bytes.length; i++) {\n    value = (value << 8) | bytes[i]!;\n    bits += 8;\n    while (bits >= 5) {\n      out += CROCKFORD_ALPHABET[(value >>> (bits - 5)) & 0x1f];\n      bits -= 5;\n    }\n  }\n  if (bits > 0) out += CROCKFORD_ALPHABET[(value << (5 - bits)) & 0x1f];\n  return out;\n}\n\nexport function base32Decode(text: string): Uint8Array {\n  let bits = 0;\n  let value = 0;\n  const out: number[] = [];\n  for (const ch of text) {\n    const v = DECODE[ch];\n    if (v === undefined) throw new Base32Error(`invalid base32 character: ${JSON.stringify(ch)}`);\n    value = (value << 5) | v;\n    bits += 5;\n    if (bits >= 8) {\n      out.push((value >>> (bits - 8)) & 0xff);\n      bits -= 8;\n    }\n  }\n  // Leftover bits must be zero padding (canonical form), else the string is malformed.\n  if (bits > 0 && (value & ((1 << bits) - 1)) !== 0) {\n    throw new Base32Error(\"non-canonical base32 padding bits\");\n  }\n  return Uint8Array.from(out);\n}\n\nexport function isValidBase32(text: string): boolean {\n  for (const ch of text) if (DECODE[ch] === undefined) return false;\n  return true;\n}\n","/**\n * Fletcher-16 checksum. Appended to each document id so a corrupted or fabricated id is\n * rejected client-side without a database round-trip.\n */\nexport function fletcher16(bytes: Uint8Array): number {\n  let sum1 = 0;\n  let sum2 = 0;\n  for (let i = 0; i < bytes.length; i++) {\n    sum1 = (sum1 + bytes[i]!) % 255;\n    sum2 = (sum2 + sum1) % 255;\n  }\n  return (sum2 << 8) | sum1;\n}\n\nexport function verifyFletcher16(bytes: Uint8Array, checksum: number): boolean {\n  return fletcher16(bytes) === checksum;\n}\n","/**\n * LEB128 unsigned varint over uint32 (1–5 bytes). Encodes the table number that\n * prefixes a document id, so small system table numbers stay compact.\n */\nexport class VarintError extends Error {\n  override name = \"VarintError\";\n}\n\nconst UINT32_MAX = 0xffffffff;\n\nexport function varintEncode(value: number): Uint8Array {\n  if (!Number.isInteger(value) || value < 0 || value > UINT32_MAX) {\n    throw new VarintError(`varint value out of uint32 range: ${value}`);\n  }\n  const out: number[] = [];\n  let v = value;\n  do {\n    let byte = v & 0x7f;\n    v = Math.floor(v / 128);\n    if (v > 0) byte |= 0x80;\n    out.push(byte);\n  } while (v > 0);\n  return Uint8Array.from(out);\n}\n\nexport interface VarintDecodeResult {\n  value: number;\n  bytesRead: number;\n}\n\nexport function varintDecode(bytes: Uint8Array, offset = 0): VarintDecodeResult {\n  let result = 0;\n  let shift = 0;\n  let pos = offset;\n  while (true) {\n    if (pos >= bytes.length) throw new VarintError(\"varint truncated\");\n    const byte = bytes[pos]!;\n    result += (byte & 0x7f) * 2 ** shift;\n    pos += 1;\n    if ((byte & 0x80) === 0) break;\n    shift += 7;\n    if (shift > 28) throw new VarintError(\"varint exceeds uint32\");\n  }\n  if (result > UINT32_MAX) throw new VarintError(\"varint exceeds uint32\");\n  return { value: result, bytesRead: pos - offset };\n}\n\nexport function varintEncodedLength(value: number): number {\n  return varintEncode(value).length;\n}\n","/**\n * Document identity. Internally a document is `(tableNumber, internalId)` where\n * `internalId` is 16 random bytes. The developer-facing `DocumentId` string is:\n *\n *     base32( varint(tableNumber) ++ internalId(16) ++ fletcher16(prefix)[2] )\n *\n * giving a compact (31–37 char), self-validating, order-irrelevant id. The table number\n * (not the name) is embedded, so renaming a table never rewrites its ids.\n */\nimport { base32Encode, base32Decode, Base32Error } from \"./base32\";\nimport { fletcher16, verifyFletcher16 } from \"./checksum\";\nimport { varintEncode, varintDecode, varintEncodedLength } from \"./varint\";\n\nexport type InternalId = Uint8Array;\n\nexport const INTERNAL_ID_BYTES = 16;\nconst CHECKSUM_BYTES = 2;\n\nexport interface InternalDocumentId {\n  tableNumber: number;\n  internalId: InternalId;\n}\n\ndeclare const docIdBrand: unique symbol;\nexport type DocumentId = string & { readonly [docIdBrand]: \"DocumentId\" };\n\nexport class DocumentIdError extends Error {\n  override name = \"DocumentIdError\";\n}\n\nfunction concatBytes(...parts: Uint8Array[]): Uint8Array {\n  const total = parts.reduce((n, p) => n + p.length, 0);\n  const out = new Uint8Array(total);\n  let offset = 0;\n  for (const p of parts) {\n    out.set(p, offset);\n    offset += p.length;\n  }\n  return out;\n}\n\nexport function internalIdToHex(internalId: InternalId): string {\n  let hex = \"\";\n  for (let i = 0; i < internalId.length; i++) hex += internalId[i]!.toString(16).padStart(2, \"0\");\n  return hex;\n}\n\nfunction hexToInternalId(hex: string): InternalId {\n  if (hex.length % 2 !== 0) throw new DocumentIdError(\"odd-length hex\");\n  const out = new Uint8Array(hex.length / 2);\n  for (let i = 0; i < out.length; i++) {\n    const byte = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);\n    if (Number.isNaN(byte)) throw new DocumentIdError(\"invalid hex\");\n    out[i] = byte;\n  }\n  return out;\n}\n\nexport function generateInternalId(): InternalId {\n  const bytes = new Uint8Array(INTERNAL_ID_BYTES);\n  crypto.getRandomValues(bytes);\n  return bytes;\n}\n\nexport function newDocumentId(tableNumber: number): InternalDocumentId {\n  return { tableNumber, internalId: generateInternalId() };\n}\n\nexport function encodeDocumentId(tableNumber: number, internalId: InternalId): DocumentId {\n  if (internalId.length !== INTERNAL_ID_BYTES) {\n    throw new DocumentIdError(`internalId must be ${INTERNAL_ID_BYTES} bytes, got ${internalId.length}`);\n  }\n  const prefix = concatBytes(varintEncode(tableNumber), internalId);\n  const checksum = fletcher16(prefix);\n  const checksumBytes = new Uint8Array([(checksum >>> 8) & 0xff, checksum & 0xff]);\n  return base32Encode(concatBytes(prefix, checksumBytes)) as DocumentId;\n}\n\nexport function encodeInternalDocumentId(id: InternalDocumentId): DocumentId {\n  return encodeDocumentId(id.tableNumber, id.internalId);\n}\n\n/** Mint a full encoded document id CLIENT-SIDE (same shape and entropy as the engine's own\n *  minting — 16 random bytes). The engine validates at insert; see client-supplied ids spec. */\nexport function mintEncodedDocumentId(tableNumber: number): DocumentId {\n  return encodeInternalDocumentId(newDocumentId(tableNumber));\n}\n\nexport function decodeDocumentId(encoded: string): InternalDocumentId {\n  let bytes: Uint8Array;\n  try {\n    bytes = base32Decode(encoded);\n  } catch (e) {\n    throw new DocumentIdError(e instanceof Base32Error ? e.message : \"invalid base32\");\n  }\n  let tableNumber: number;\n  let bytesRead: number;\n  try {\n    ({ value: tableNumber, bytesRead } = varintDecode(bytes, 0));\n  } catch {\n    throw new DocumentIdError(\"invalid table number\");\n  }\n  const internalIdEnd = bytesRead + INTERNAL_ID_BYTES;\n  if (bytes.length !== internalIdEnd + CHECKSUM_BYTES) {\n    throw new DocumentIdError(\"incorrect id length\");\n  }\n  const internalId = bytes.slice(bytesRead, internalIdEnd);\n  const checksum = (bytes[internalIdEnd]! << 8) | bytes[internalIdEnd + 1]!;\n  const prefix = bytes.slice(0, internalIdEnd);\n  if (!verifyFletcher16(prefix, checksum)) throw new DocumentIdError(\"checksum mismatch\");\n  return { tableNumber, internalId };\n}\n\nexport function tryDecodeDocumentId(encoded: string): InternalDocumentId | null {\n  try {\n    return decodeDocumentId(encoded);\n  } catch {\n    return null;\n  }\n}\n\nexport function isValidDocumentId(encoded: string, expectedTableNumber?: number): boolean {\n  const decoded = tryDecodeDocumentId(encoded);\n  if (decoded === null) return false;\n  return expectedTableNumber === undefined || decoded.tableNumber === expectedTableNumber;\n}\n\n/** The encoded length in characters for ids of a given table number (31–37). */\nexport function getEncodedLength(tableNumber: number): number {\n  const byteLen = varintEncodedLength(tableNumber) + INTERNAL_ID_BYTES + CHECKSUM_BYTES;\n  return Math.ceil((byteLen * 8) / 5);\n}\n\n/* --- stable Map/Set keys for InternalDocumentId --- */\n\nexport function documentIdKey(id: InternalDocumentId): string {\n  return `${id.tableNumber}:${internalIdToHex(id.internalId)}`;\n}\n\nexport function parseDocumentIdKey(key: string): InternalDocumentId {\n  const sep = key.indexOf(\":\");\n  if (sep < 0) throw new DocumentIdError(\"invalid document id key\");\n  const tableNumber = Number.parseInt(key.slice(0, sep), 10);\n  if (!Number.isInteger(tableNumber)) throw new DocumentIdError(\"invalid table number in key\");\n  return { tableNumber, internalId: hexToInternalId(key.slice(sep + 1)) };\n}\n\nexport function documentIdsEqual(a: InternalDocumentId, b: InternalDocumentId): boolean {\n  if (a.tableNumber !== b.tableNumber || a.internalId.length !== b.internalId.length) return false;\n  for (let i = 0; i < a.internalId.length; i++) if (a.internalId[i] !== b.internalId[i]) return false;\n  return true;\n}\n","/**\n * Stable string identifiers the storage layer uses to name a table's document space and\n * its indexes. Derived from the table *number* (not name) so renames never touch storage.\n */\nexport function encodeStorageTableId(tableNumber: number): string {\n  return String(tableNumber);\n}\n\nexport function decodeStorageTableId(tableId: string): number {\n  const n = Number.parseInt(tableId, 10);\n  if (!Number.isInteger(n) || String(n) !== tableId) throw new Error(`invalid storage table id: ${tableId}`);\n  return n;\n}\n\nexport function encodeStorageIndexId(tableNumber: number, indexName: string): string {\n  return `${tableNumber}/${indexName}`;\n}\n\nexport function decodeStorageIndexId(indexId: string): { tableNumber: number; indexName: string } {\n  const sep = indexId.indexOf(\"/\");\n  if (sep < 0) throw new Error(`invalid storage index id: ${indexId}`);\n  return {\n    tableNumber: decodeStorageTableId(indexId.slice(0, sep)),\n    indexName: indexId.slice(sep + 1),\n  };\n}\n","/**\n * Shared point-range conversion helpers — the canonical home for `keyToPointRange`/\n * `docKeyToPointRange`, byte-for-byte identical to the versions that originally shipped in\n * `ee/packages/fleet/src/ranges.ts` (Tier 3 Slice 1/2). Extracted here (Tier 3 Slice 8, Task 8.1) so\n * `ee/packages/objectstore-substrate`'s replica reactive-tailer wiring can reuse them without taking\n * a dependency on `@helipod/fleet` (an EE package objectstore-substrate must not import — the\n * object-store substrate and the Postgres fleet are siblings, not a hierarchy).\n *\n * Homed in `@helipod/id-codec`, NOT `@helipod/index-key-codec`, despite `SerializedKeyRange`\n * itself living in the latter: these functions bridge a STORAGE id (`decodeStorageIndexId`,\n * `encodeStorageTableId` — this package's own `storage-id.ts`) to the engine's KEYSPACE id\n * (`indexKeyspaceId`/`tableKeyspaceId` — `@helipod/index-key-codec`'s `keyspace.ts`), so they\n * inherently need both id spaces. `@helipod/id-codec` already depends on\n * `@helipod/index-key-codec` (see `jump-hash.ts`'s `encodeIndexKey` import), so this direction adds\n * no new edge; the reverse — moving these into `index-key-codec` and having IT depend on\n * `id-codec`'s storage-id helpers — would create an import cycle (`id-codec -> index-key-codec ->\n * id-codec`). `id-codec` is therefore the only cycle-free canonical home for this bridge.\n *\n * `ee/packages/fleet/src/ranges.ts` re-exports both functions from here verbatim — fleet's public\n * API and existing tests are unaffected by the move.\n */\nimport {\n  keySuccessor,\n  serializeKeyRange,\n  indexKeyspaceId,\n  tableKeyspaceId,\n  type SerializedKeyRange,\n} from \"@helipod/index-key-codec\";\nimport { decodeStorageIndexId, encodeStorageTableId } from \"./storage-id\";\n\n/**\n * Convert a single written `(indexId, key)` pair into the sync handler's point range\n * `[key, keySuccessor(key))` — the exact same half-open encoding `RangeSet.addKey` uses for a\n * point read/write, so a follower's derived write range overlaps a subscription's recorded read\n * range under `rangesOverlap`.\n *\n * `indexId` here is the storage `index_id` — the STORAGE index id produced by\n * `encodeStorageIndexId`, format `\"<tableNumber>/<indexName>\"` (e.g. `\"10001/by_creation\"`). That\n * is NOT the same string as the engine's keyspace id (`indexKeyspaceId`'s `\"index:<table>:<name>\"`\n * / `tableKeyspaceId`'s `\"table:<table>\"`), which is what `SerializedKeyRange.keyspace` — and\n * `rangesOverlap` — actually compare on. So the storage id must be decoded back into its parts and\n * the keyspace REBUILT with the engine's own helper; feeding the raw storage id straight through\n * silently produces ranges that can never overlap anything.\n */\nexport function keyToPointRange(indexId: string, key: Uint8Array): SerializedKeyRange {\n  const { tableNumber, indexName } = decodeStorageIndexId(indexId);\n  const keyspace = indexKeyspaceId(encodeStorageTableId(tableNumber), indexName);\n  return serializeKeyRange({ keyspace, start: key, end: keySuccessor(key) });\n}\n\n/**\n * Convert a single written `(table_id, internal_id)` pair — e.g. from a `DerivedInvalidation`'s (or\n * `AppliedInvalidation`'s) `writtenDocs` — into the DOCUMENT-keyspace point range a bare\n * `ctx.db.get(id)` read records: `[internalId, keySuccessor(internalId))` under\n * `tableKeyspaceId(table)`. Unlike `keyToPointRange` above, no decode/recompose round trip is\n * needed here — `table_id` is already `encodeStorageTableId(tableNumber)`, exactly the string\n * `tableKeyspaceId` expects; it is NOT a storage *index* id, so there is no separate \"storage id\"\n * vs \"engine keyspace id\" split to bridge for the table half. This must match\n * `single-writer-transactor.ts`'s `docKeyspace()` (`tableKeyspaceId(encodeStorageTableId(...))`)\n * plus its `RangeSet.addKey(docKeyspace(id), id.internalId)` byte-for-byte, or a follower never\n * invalidates a subscription whose only read was a point `get`.\n */\nexport function docKeyToPointRange(tableId: string, internalId: Uint8Array): SerializedKeyRange {\n  const keyspace = tableKeyspaceId(tableId);\n  return serializeKeyRange({ keyspace, start: internalId, end: keySuccessor(internalId) });\n}\n","/**\n * Sharding primitives — scale-seam #1. A conversation (or any partition) maps to a shard\n * key derived from a document field; a shard router maps that key to the single-writer\n * shard that owns it. At **Tier 0 there is exactly one shard (`\"default\"`)** and the\n * router always returns it, but the seam exists in the interfaces from day one so Tier 2\n * per-conversation sharding is a config swap, not an engine rewrite.\n */\nexport type ShardId = string;\nexport type ShardKey = string;\n\nexport const DEFAULT_SHARD: ShardId = \"default\";\n\nexport interface ShardKeyResolverInput {\n  table: string;\n  document: Record<string, unknown>;\n}\n\n/** Extracts the shard key from a document, or null if the table isn't sharded. */\nexport interface ShardKeyResolver {\n  resolve(input: ShardKeyResolverInput): ShardKey | null;\n}\n\n/** Tier 0: nothing is sharded — every document lives in the default shard. */\nexport class DefaultShardKeyResolver implements ShardKeyResolver {\n  resolve(): ShardKey | null {\n    return null;\n  }\n}\n\n/** Resolves the shard key from a configured field per table (e.g. `messages.conversationId`). */\nexport class FieldShardKeyResolver implements ShardKeyResolver {\n  constructor(private readonly fieldByTable: ReadonlyMap<string, string>) {}\n\n  resolve({ table, document }: ShardKeyResolverInput): ShardKey | null {\n    const field = this.fieldByTable.get(table);\n    if (field === undefined) return null;\n    const value = document[field];\n    return value === undefined || value === null ? null : String(value);\n  }\n}\n\n/**\n * Routes shard keys and clients to shards/nodes. Tier 2 implements consistent hashing\n * (document→committer) and rendezvous hashing (client→sync node); `TStub` is the\n * per-shard handle (e.g. a Durable Object stub).\n */\nexport interface ShardRouter<TStub = unknown> {\n  getShardForKey(shardKey: ShardKey | null): ShardId;\n  getShardForDocument(table: string, shardKey: ShardKey | null): ShardId;\n  getSyncNodeId(clientId: string): string;\n  resolveStub?(shardId: ShardId): TStub;\n}\n\n/** Tier 0 router: one shard, one local sync node. */\nexport class SimpleShardRouter implements ShardRouter {\n  getShardForKey(_shardKey: ShardKey | null): ShardId {\n    return DEFAULT_SHARD;\n  }\n  getShardForDocument(_table: string, _shardKey: ShardKey | null): ShardId {\n    return DEFAULT_SHARD;\n  }\n  getSyncNodeId(_clientId: string): string {\n    return \"local\";\n  }\n}\n","/**\n * Jump consistent hash (Lamping & Veach, 2014) + the concrete `ShardRouter` built on it.\n *\n * The routing seam (`./shard.ts`) declares WHAT a router does; this file is HOW B2a does it:\n * a shard-key value is canonicalized to bytes the way the engine already canonicalizes index\n * keys (`encodeIndexKey` from `@helipod/index-key-codec` — never a hand-rolled encoding, so\n * a `1` routes the same whether it arrives as an arg or is read back off a document), hashed to\n * a 64-bit key, and mapped to a bucket in `[0, numShards)` by jump consistent hash. Slot 0 is\n * the reserved `\"default\"` shard (unsharded tables + no-`shardBy` mutations); slot k>0 is `\"s\"+k`.\n *\n * Jump consistent hash is chosen for its movement-minimality: growing the bucket count from n to\n * n' only ever moves a key to one of the NEW buckets `[n, n')`, never reshuffles a key among the\n * old buckets — the property B5's offline resharding tool leans on.\n */\nimport { encodeIndexKey, type IndexableValue } from \"@helipod/index-key-codec\";\nimport { DEFAULT_SHARD, type ShardId, type ShardKey } from \"./shard\";\nimport type { ShardRouter } from \"./shard\";\n\nconst U64_MASK = 0xffffffffffffffffn;\n/** 64-bit LCG multiplier from the reference jump-hash implementation. */\nconst LCG_MULT = 2862933555777941757n;\n\n/**\n * Map a 64-bit `key` to a bucket in `[0, buckets)`. The reference ~10-line algorithm: walk a\n * pseudo-random sequence of \"jump\" points, keeping the last one that lands below `buckets`.\n * Deterministic and allocation-free; `buckets` must be ≥ 1.\n */\nexport function jumpConsistentHash(key: bigint, buckets: number): number {\n  if (buckets < 1) throw new RangeError(`buckets must be >= 1, got ${buckets}`);\n  let k = BigInt.asUintN(64, key);\n  let b = -1n;\n  let j = 0n;\n  const n = BigInt(buckets);\n  while (j < n) {\n    b = j;\n    k = (k * LCG_MULT + 1n) & U64_MASK;\n    // j = floor((b + 1) * (2^31 / ((k >> 33) + 1)))\n    const denom = Number(k >> 33n) + 1;\n    j = BigInt(Math.floor((Number(b) + 1) * (0x80000000 / denom)));\n  }\n  return Number(b);\n}\n\n/** FNV-1a 64-bit hash of a byte string → a well-mixed 64-bit key for `jumpConsistentHash`. */\nfunction fnv1a64(bytes: Uint8Array): bigint {\n  let h = 0xcbf29ce484222325n;\n  for (let i = 0; i < bytes.length; i++) {\n    h ^= BigInt(bytes[i]!);\n    h = (h * 0x100000001b3n) & U64_MASK;\n  }\n  return h;\n}\n\n/**\n * Resolve a shard-key VALUE (a scalar: string/number/bigint/boolean/null/bytes) to its shard id\n * under `numShards`. Canonicalizes via the engine's own index-key encoding so routing is stable\n * across the arg → route and document → route paths. Slot 0 → `\"default\"`, slot k → `\"s\"+k`.\n */\nexport function shardIdForKeyValue(value: unknown, numShards: number): ShardId {\n  const bytes = encodeIndexKey([value as IndexableValue]);\n  const slot = jumpConsistentHash(fnv1a64(bytes), Math.max(1, numShards));\n  return slot === 0 ? DEFAULT_SHARD : `s${slot}`;\n}\n\n/**\n * The canonical ordered shard-id list for `numShards` shards: `[\"default\", \"s1\", …, \"s{N-1}\"]`.\n * The array INDEX is the slot number — slot 0 is `\"default\"`, slot k is `\"s\"+k` — matching\n * `shardIdForKeyValue`'s slot→id mapping exactly. This is the ONE source of truth for the\n * slot↔shardId contract the fleet's per-shard commit pool (`NodePgClient`'s `commitPool.shards`),\n * per-slot advisory locks (`tryAcquireShardLock(slot)`), and lease acquire-all loop all share, so\n * nobody hand-rolls (and risks disagreeing on) the numbering. `numShards` must be ≥ 1.\n */\nexport function shardIdList(numShards: number): ShardId[] {\n  if (numShards < 1) throw new RangeError(`numShards must be >= 1, got ${numShards}`);\n  const ids: ShardId[] = [DEFAULT_SHARD];\n  for (let slot = 1; slot < numShards; slot++) ids.push(`s${slot}`);\n  return ids;\n}\n\n/**\n * The B2a `ShardRouter`: jump-consistent-hash routing over `numShards` shards. Single-node, so\n * every client resolves to one local sync node. `getShardForKey`/`getShardForDocument` take the\n * already-extracted shard-key value (a string, per the seam); `shardIdForKeyValue` is the\n * value-typed entry point the executor and kernel call directly with the raw arg/field value.\n */\nexport class JumpShardRouter implements ShardRouter {\n  constructor(private readonly numShards: number) {\n    if (numShards < 1) throw new RangeError(`numShards must be >= 1, got ${numShards}`);\n  }\n\n  getShardForKey(shardKey: ShardKey | null): ShardId {\n    return shardKey === null ? DEFAULT_SHARD : shardIdForKeyValue(shardKey, this.numShards);\n  }\n\n  getShardForDocument(_table: string, shardKey: ShardKey | null): ShardId {\n    return this.getShardForKey(shardKey);\n  }\n\n  getSyncNodeId(_clientId: string): string {\n    return \"local\";\n  }\n}\n","/**\n * The table registry assigns each table a stable numeric id (embedded in document ids).\n * System tables (`_`-prefixed) get numbers 1–9999; user tables start at 10001, leaving a\n * reserved gap. The DocStore-backed durable registry arrives in M2; this in-memory one is\n * the canonical interface + the Tier 0 / test implementation.\n */\nexport type TableVisibility = \"user\" | \"system\";\nexport type TableState = \"active\" | \"creating\" | \"deleting\";\n\nexport interface TableInfo {\n  name: string;\n  tableNumber: number;\n  visibility: TableVisibility;\n  state: TableState;\n  /** The document field used as the shard key (seam #1), or null. */\n  shardKey: string | null;\n}\n\nexport interface AllocateOptions {\n  visibility?: TableVisibility;\n  shardKey?: string | null;\n}\n\nexport interface TableRegistry {\n  getByName(name: string): TableInfo | undefined;\n  getByNumber(tableNumber: number): TableInfo | undefined;\n  allocate(name: string, options?: AllocateOptions): TableInfo;\n  list(): TableInfo[];\n}\n\nexport interface PreassignOptions {\n  visibility?: TableVisibility;\n  shardKey?: string | null;\n  state?: TableState;\n}\n\nexport const SYSTEM_TABLE_NUMBER_MIN = 1;\nexport const SYSTEM_TABLE_NUMBER_MAX = 9999;\nexport const USER_TABLE_NUMBER_START = 10001;\n\n/**\n * Reserved table numbers for built-in app-namespace system tables. These MUST stay stable\n * forever: a persisted `Id<\"_storage\">` encodes this number, so it must always decode back to\n * the same table. Registry seeding pins them with `preassign(name, number)` before any other\n * system table is auto-allocated, keeping their numbers deterministic across runs regardless of\n * registration order. `_storage` (the file-storage feature's document table) is 20.\n */\nexport const STORAGE_TABLE_NUMBER = 20;\n\nexport function isSystemTableName(name: string): boolean {\n  return name.startsWith(\"_\");\n}\n\nexport function getFullTableName(name: string, componentPath: string): string {\n  return componentPath ? `${componentPath}/${name}` : name;\n}\n\nexport function parseFullTableName(fullName: string): { componentPath: string; name: string } {\n  const i = fullName.lastIndexOf(\"/\");\n  return i < 0 ? { componentPath: \"\", name: fullName } : { componentPath: fullName.slice(0, i), name: fullName.slice(i + 1) };\n}\n\nexport class MemoryTableRegistry implements TableRegistry {\n  private readonly byName = new Map<string, TableInfo>();\n  private readonly byNumber = new Map<number, TableInfo>();\n  private nextUser = USER_TABLE_NUMBER_START;\n  private nextSystem = SYSTEM_TABLE_NUMBER_MIN;\n\n  getByName(name: string): TableInfo | undefined {\n    return this.byName.get(name);\n  }\n\n  getByNumber(tableNumber: number): TableInfo | undefined {\n    return this.byNumber.get(tableNumber);\n  }\n\n  /** Idempotent: allocating an existing name returns the existing entry. */\n  allocate(name: string, options: AllocateOptions = {}): TableInfo {\n    const existing = this.byName.get(name);\n    if (existing) return existing;\n\n    const visibility = options.visibility ?? (isSystemTableName(name) ? \"system\" : \"user\");\n    let tableNumber: number;\n    if (visibility === \"system\") {\n      if (this.nextSystem > SYSTEM_TABLE_NUMBER_MAX) throw new Error(\"exhausted system table numbers\");\n      tableNumber = this.nextSystem++;\n    } else {\n      tableNumber = this.nextUser++;\n    }\n\n    const info: TableInfo = {\n      name,\n      tableNumber,\n      visibility,\n      state: \"active\",\n      shardKey: options.shardKey ?? null,\n    };\n    this.byName.set(name, info);\n    this.byNumber.set(tableNumber, info);\n    return info;\n  }\n\n  list(): TableInfo[] {\n    return [...this.byName.values()];\n  }\n\n  /**\n   * Pre-register a table at a KNOWN (already-live) number, so a later `allocate(name)` for the\n   * same name returns this number instead of minting a fresh one — used to seed a fresh registry\n   * with a running deploy's table numbers before composing a new schema, so existing tables\n   * (app AND component) never renumber; only genuinely-new tables get numbers above the seeded\n   * max. Idempotent/no-op if `name` is already known (first registration wins, matching\n   * `allocate`'s idempotency). Bumps the relevant `next*` counter so future `allocate` calls\n   * never collide with a preassigned number.\n   */\n  preassign(name: string, tableNumber: number, options: PreassignOptions = {}): TableInfo {\n    const existing = this.byName.get(name);\n    if (existing) return existing;\n\n    const visibility = options.visibility ?? (isSystemTableName(name) ? \"system\" : \"user\");\n    const info: TableInfo = {\n      name,\n      tableNumber,\n      visibility,\n      state: options.state ?? \"active\",\n      shardKey: options.shardKey ?? null,\n    };\n    this.byName.set(name, info);\n    this.byNumber.set(tableNumber, info);\n    if (visibility === \"system\") {\n      this.nextSystem = Math.max(this.nextSystem, tableNumber + 1);\n    } else {\n      this.nextUser = Math.max(this.nextUser, tableNumber + 1);\n    }\n    return info;\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@helipod/id-codec",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "FSL-1.1-Apache-2.0",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@helipod/index-key-codec": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/helipod-sh/helipod.git",
+    "directory": "packages/id-codec"
+  },
+  "homepage": "https://github.com/helipod-sh/helipod"
+}