@wildo-ai/saas-models 1.0.1 → 1.1.0

package/dist/esm/http-api-binding/http-api-binding-id.shared.utils.js

@@ -0,0 +1,232 @@
+/**
+ * HTTP-API resource-id synthesis — THE single authority for encoding/decoding the engine-facing
+ * `_id` of an `HTTP_API`-backed resource from its remote key components.
+ *
+ * Contract (design paper `.claude/plans/etl-composite-key-synthesis.md`):
+ * - **Deterministic + injective**: the same remote row yields the same `_id` on every machine,
+ *   forever; two rows never collide (JSON array encoding preserves order and type).
+ * - **Charset law**: every synthesized id matches `^[A-Za-z0-9._~-]+$` (URL-unreserved). This is
+ *   what survives the two measured hazards: the frontend's unencoded `String.replace` URL
+ *   substitution (forbids `/ ? # % $`) and colon-parsed websocket-room / Redis keys (forbids `:`).
+ * - **Two static forms**, selected by the BINDING, never sniffed per row:
+ *   verbatim (single key whose codec's whole value space is charset-safe — GUID, INTEGER) or
+ *   encoded (base64url of the canonical JSON array of normalized components, no padding).
+ * - **Decodable offline**: `_id` → key components needs no remote call.
+ *
+ * Errors are thrown as the typed {@link HttpApiResourceIdError} — this module is shared-tier (no
+ * `ErrorBuilder` here; same precedent as `selectByPersistenceAdapter`). Backend callers classify
+ * it by INSTANCE into a LOUD `VALIDATION` refusal — never a silent not-found (the Mongo
+ * CastError-to-404 behavior is explicitly NOT mimicked).
+ *
+ * No `Buffer` here on purpose: this file must run in the browser bundle as well as Node, so
+ * base64url is implemented over `TextEncoder`/`TextDecoder`.
+ */
+/*
+ * entrypoint-closure-waiver: this root-reachable module imports the external-data AUTHORING
+ * contract, which only `@wildo-ai/saas-models/external-data` publishes (see
+ * `external-data.exports.ts` for why that subpath exists).
+ *
+ * MEASURED SAFE 2026-08-29 by the probe `package-public-entrypoints.md` prescribes — a consumer
+ * importing ONLY the package root, re-exporting these surfaces and deriving their parameter types
+ * so declaration emit must WRITE them rather than alias them, compiled with `declaration: true`:
+ * zero TS2742 / TS2883 / TS7056, and the emitted `.d.ts` names `@wildo-ai/saas-models` with no
+ * `node_modules/...` path anywhere in it.
+ *
+ * The mechanism, so the next reader need not re-derive it: every crossing here is an EXPLICIT
+ * ANNOTATION inside this package, so TypeScript emits a RELATIVE intra-package import in our own
+ * `.d.ts` — which resolves by PATH for any consumer, whatever the exports map says. TS2742 bites
+ * only when TypeScript must INVENT a specifier for an INFERRED type. Re-run the probe if a
+ * root-exported contract here ever starts inferring one.
+ */
+import { HttpApiKeyComponentCodec, httpApiBindingUsesVerbatimKey, } from './http-api-binding.shared.schemas.js';
+/**
+ * The typed refusal every codec failure throws — undecodable ids, non-canonical aliases, missing
+ * or malformed key components. Typed (rather than message-matched) so the backend adapter can
+ * classify it into a VALIDATION projection without regexing prose that a reword would silently
+ * break.
+ */
+export class HttpApiResourceIdError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'HttpApiResourceIdError';
+    }
+}
+/**
+ * The charset law for every synthesized HTTP-API resource id: URL-unreserved characters only.
+ * See the module JSDoc for the two measured hazards this survives.
+ */
+export const HTTP_API_RESOURCE_ID_CHARSET = /^[A-Za-z0-9._~-]+$/;
+const GUID_PATTERN = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+// --------------------------------
+// base64url (portable, unpadded)
+// --------------------------------
+const B64URL_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+const B64URL_REVERSE = new Map([...B64URL_ALPHABET].map((char, index) => [char, index]));
+function bytesToBase64Url(bytes) {
+    let out = '';
+    for (let i = 0; i < bytes.length; i += 3) {
+        const b0 = bytes[i];
+        const b1 = i + 1 < bytes.length ? bytes[i + 1] : undefined;
+        const b2 = i + 2 < bytes.length ? bytes[i + 2] : undefined;
+        out += B64URL_ALPHABET[b0 >> 2];
+        out += B64URL_ALPHABET[((b0 & 0x03) << 4) | ((b1 ?? 0) >> 4)];
+        if (b1 !== undefined) {
+            out += B64URL_ALPHABET[((b1 & 0x0f) << 2) | ((b2 ?? 0) >> 6)];
+        }
+        if (b2 !== undefined) {
+            out += B64URL_ALPHABET[b2 & 0x3f];
+        }
+    }
+    return out;
+}
+function base64UrlToBytes(encoded) {
+    if (encoded.length % 4 === 1) {
+        throw new HttpApiResourceIdError(`Invalid base64url payload length in HTTP-API resource id (length ${encoded.length}).`);
+    }
+    const byteLength = Math.floor((encoded.length * 3) / 4);
+    const bytes = new Uint8Array(byteLength);
+    let byteIndex = 0;
+    let buffer = 0;
+    let bitsInBuffer = 0;
+    for (const char of encoded) {
+        const value = B64URL_REVERSE.get(char);
+        if (value === undefined) {
+            throw new HttpApiResourceIdError(`Invalid base64url character '${char}' in HTTP-API resource id.`);
+        }
+        buffer = (buffer << 6) | value;
+        bitsInBuffer += 6;
+        if (bitsInBuffer >= 8) {
+            bitsInBuffer -= 8;
+            bytes[byteIndex] = (buffer >> bitsInBuffer) & 0xff;
+            byteIndex += 1;
+        }
+    }
+    return bytes;
+}
+// --------------------------------
+// Component normalization per codec
+// --------------------------------
+/**
+ * Normalize one raw remote key value per its declared codec. Normalization is what makes the
+ * synthesis STABLE: the same remote row must produce byte-identical components regardless of the
+ * remote system's incidental formatting (GUID casing, datetime precision).
+ */
+export function normalizeHttpApiKeyComponent(keyField, rawValue) {
+    switch (keyField.codec) {
+        case HttpApiKeyComponentCodec.STRING: {
+            if (typeof rawValue !== 'string' || rawValue.length === 0) {
+                throw new HttpApiResourceIdError(`HTTP-API key component '${keyField.remoteField}' (codec STRING) must be a non-empty string, got ${describeValue(rawValue)}.`);
+            }
+            return rawValue;
+        }
+        case HttpApiKeyComponentCodec.INTEGER: {
+            const numeric = typeof rawValue === 'string' && /^-?\d+$/.test(rawValue) ? Number(rawValue) : rawValue;
+            if (typeof numeric !== 'number' || !Number.isSafeInteger(numeric)) {
+                throw new HttpApiResourceIdError(`HTTP-API key component '${keyField.remoteField}' (codec INTEGER) must be a safe integer, got ${describeValue(rawValue)}.`);
+            }
+            return numeric;
+        }
+        case HttpApiKeyComponentCodec.GUID: {
+            if (typeof rawValue !== 'string' || !GUID_PATTERN.test(rawValue)) {
+                throw new HttpApiResourceIdError(`HTTP-API key component '${keyField.remoteField}' (codec GUID) must be a GUID string, got ${describeValue(rawValue)}.`);
+            }
+            // Lowercase so the same remote row synthesizes the same id regardless of the target's casing.
+            return rawValue.toLowerCase();
+        }
+        case HttpApiKeyComponentCodec.DATETIME_ISO: {
+            // Strict ISO 8601 shape gate BEFORE Date.parse: bare Date.parse accepts
+            // implementation-defined non-ISO formats, which would make the synthesized id differ
+            // across JS engines — the determinism the module contract promises would silently hold
+            // only for genuinely ISO inputs.
+            const isStrictIso = typeof rawValue === 'string'
+                && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/.test(rawValue);
+            const timestamp = isStrictIso ? Date.parse(rawValue) : Number.NaN;
+            if (Number.isNaN(timestamp)) {
+                throw new HttpApiResourceIdError(`HTTP-API key component '${keyField.remoteField}' (codec DATETIME_ISO) must be an ISO 8601 datetime string with an explicit offset, got ${describeValue(rawValue)}.`);
+            }
+            return new Date(timestamp).toISOString();
+        }
+    }
+}
+function describeValue(value) {
+    if (typeof value === 'string') {
+        return `'${value.length > 64 ? `${value.slice(0, 64)}…` : value}'`;
+    }
+    return `${typeof value} ${String(value)}`;
+}
+// --------------------------------
+// Encode / decode (the two id forms)
+// --------------------------------
+/**
+ * Synthesize the engine-facing `_id` for one remote row, from its raw remote key values in
+ * `keyFields` order. The form (verbatim vs encoded) is a static property of the binding
+ * (`httpApiBindingUsesVerbatimKey`).
+ */
+export function synthesizeHttpApiResourceId(binding, rawComponents) {
+    if (rawComponents.length !== binding.keyFields.length) {
+        throw new HttpApiResourceIdError(`HTTP-API id synthesis received ${rawComponents.length} key component(s) for a binding declaring ${binding.keyFields.length}.`);
+    }
+    const normalized = binding.keyFields.map((keyField, index) => normalizeHttpApiKeyComponent(keyField, rawComponents[index]));
+    if (httpApiBindingUsesVerbatimKey(binding)) {
+        const verbatim = String(normalized[0]);
+        // Defensive: the codec gate should make this unreachable, but the charset law is the invariant
+        // every downstream consumer relies on, so it is asserted where the id is minted.
+        assertCharsetSafe(verbatim);
+        return verbatim;
+    }
+    const encoded = bytesToBase64Url(new TextEncoder().encode(JSON.stringify(normalized)));
+    assertCharsetSafe(encoded);
+    return encoded;
+}
+/**
+ * Resolve an engine-facing `_id` back to its normalized key components, in `keyFields` order.
+ * Purely local — no remote call. Throws on any id this binding could not have synthesized —
+ * INCLUDING every non-canonical ALIAS of a valid id (base64url trailing-bit variants,
+ * JSON-whitespace variants, non-normalized verbatim forms such as an uppercase GUID): one remote
+ * row answers to exactly ONE engine id, because row identity, URL canonicality, dedup keys and
+ * id-based exclusion filters are all built on that equality. Enforced by re-synthesizing from the
+ * resolved components and requiring byte-equality with the incoming id.
+ */
+export function resolveHttpApiKeyComponents(binding, resourceId) {
+    if (resourceId.length === 0) {
+        throw new HttpApiResourceIdError('HTTP-API resource id must be a non-empty string.');
+    }
+    let components;
+    if (httpApiBindingUsesVerbatimKey(binding)) {
+        components = [normalizeHttpApiKeyComponent(binding.keyFields[0], resourceId)];
+    }
+    else {
+        assertCharsetSafe(resourceId);
+        let parsed;
+        try {
+            parsed = JSON.parse(new TextDecoder().decode(base64UrlToBytes(resourceId)));
+        }
+        catch (error) {
+            throw new HttpApiResourceIdError(`HTTP-API resource id '${resourceId}' is not a valid encoded composite key: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (!Array.isArray(parsed) || parsed.length !== binding.keyFields.length) {
+            throw new HttpApiResourceIdError(`HTTP-API resource id '${resourceId}' decodes to ${Array.isArray(parsed) ? `${parsed.length} component(s)` : 'a non-array'} for a binding declaring ${binding.keyFields.length}.`);
+        }
+        components = binding.keyFields.map((keyField, index) => normalizeHttpApiKeyComponent(keyField, parsed[index]));
+    }
+    // Canonicality gate: re-synthesize and require byte-equality. Normalization is idempotent per
+    // codec, so a canonical id always round-trips to itself; any alias (dropped-bit base64url
+    // variant, whitespace-bearing JSON, '042' for an INTEGER key, 'ABC…' for a GUID key) differs
+    // here and is refused rather than silently adopted as a second name for the same row.
+    const canonical = synthesizeHttpApiResourceId(binding, components);
+    if (canonical !== resourceId) {
+        throw new HttpApiResourceIdError(`HTTP-API resource id ${describeValue(resourceId)} is a non-canonical alias of ${describeValue(canonical)} and is refused: every remote row has exactly one engine id.`);
+    }
+    return components;
+}
+/** Runtime guard for the charset law. */
+export function isCharsetSafeHttpApiResourceId(candidate) {
+    return HTTP_API_RESOURCE_ID_CHARSET.test(candidate);
+}
+function assertCharsetSafe(candidate) {
+    if (!isCharsetSafeHttpApiResourceId(candidate)) {
+        throw new HttpApiResourceIdError(`HTTP-API resource id violates the charset law ${HTTP_API_RESOURCE_ID_CHARSET}: ${describeValue(candidate)}. `
+            + 'Ids must stay URL-unreserved — the frontend substitutes them into URLs without encoding, and websocket room names parse on \':\'.');
+    }
+}
+//# sourceMappingURL=http-api-binding-id.shared.utils.js.map

package/dist/esm/http-api-binding/http-api-binding-id.shared.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-api-binding-id.shared.utils.js","sourceRoot":"","sources":["../../../../src/http-api-binding/http-api-binding-id.shared.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * HTTP-API resource-id synthesis — THE single authority for encoding/decoding the engine-facing\n * `_id` of an `HTTP_API`-backed resource from its remote key components.\n *\n * Contract (design paper `.claude/plans/etl-composite-key-synthesis.md`):\n * - **Deterministic + injective**: the same remote row yields the same `_id` on every machine,\n *   forever; two rows never collide (JSON array encoding preserves order and type).\n * - **Charset law**: every synthesized id matches `^[A-Za-z0-9._~-]+$` (URL-unreserved). This is\n *   what survives the two measured hazards: the frontend's unencoded `String.replace` URL\n *   substitution (forbids `/ ? # % $`) and colon-parsed websocket-room / Redis keys (forbids `:`).\n * - **Two static forms**, selected by the BINDING, never sniffed per row:\n *   verbatim (single key whose codec's whole value space is charset-safe — GUID, INTEGER) or\n *   encoded (base64url of the canonical JSON array of normalized components, no padding).\n * - **Decodable offline**: `_id` → key components needs no remote call.\n *\n * Errors are thrown as the typed {@link HttpApiResourceIdError} — this module is shared-tier (no\n * `ErrorBuilder` here; same precedent as `selectByPersistenceAdapter`). Backend callers classify\n * it by INSTANCE into a LOUD `VALIDATION` refusal — never a silent not-found (the Mongo\n * CastError-to-404 behavior is explicitly NOT mimicked).\n *\n * No `Buffer` here on purpose: this file must run in the browser bundle as well as Node, so\n * base64url is implemented over `TextEncoder`/`TextDecoder`.\n */\n\n/*\n * entrypoint-closure-waiver: this root-reachable module imports the external-data AUTHORING\n * contract, which only `@wildo-ai/saas-models/external-data` publishes (see\n * `external-data.exports.ts` for why that subpath exists).\n *\n * MEASURED SAFE 2026-08-29 by the probe `package-public-entrypoints.md` prescribes — a consumer\n * importing ONLY the package root, re-exporting these surfaces and deriving their parameter types\n * so declaration emit must WRITE them rather than alias them, compiled with `declaration: true`:\n * zero TS2742 / TS2883 / TS7056, and the emitted `.d.ts` names `@wildo-ai/saas-models` with no\n * `node_modules/...` path anywhere in it.\n *\n * The mechanism, so the next reader need not re-derive it: every crossing here is an EXPLICIT\n * ANNOTATION inside this package, so TypeScript emits a RELATIVE intra-package import in our own\n * `.d.ts` — which resolves by PATH for any consumer, whatever the exports map says. TS2742 bites\n * only when TypeScript must INVENT a specifier for an INFERRED type. Re-run the probe if a\n * root-exported contract here ever starts inferring one.\n */\nimport {\n  HttpApiKeyComponentCodec,\n  httpApiBindingUsesVerbatimKey,\n  type HttpApiKeyField,\n} from './http-api-binding.shared.schemas';\n\n/**\n * The typed refusal every codec failure throws — undecodable ids, non-canonical aliases, missing\n * or malformed key components. Typed (rather than message-matched) so the backend adapter can\n * classify it into a VALIDATION projection without regexing prose that a reword would silently\n * break.\n */\nexport class HttpApiResourceIdError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'HttpApiResourceIdError';\n  }\n}\n\n/** One normalized key component value as it participates in id synthesis. */\nexport type HttpApiKeyComponentValue = string | number;\n\n/**\n * The charset law for every synthesized HTTP-API resource id: URL-unreserved characters only.\n * See the module JSDoc for the two measured hazards this survives.\n */\nexport const HTTP_API_RESOURCE_ID_CHARSET: RegExp = /^[A-Za-z0-9._~-]+$/;\n\nconst GUID_PATTERN = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;\n\n// --------------------------------\n// base64url (portable, unpadded)\n// --------------------------------\n\nconst B64URL_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';\n\nconst B64URL_REVERSE: ReadonlyMap<string, number> = new Map(\n  [...B64URL_ALPHABET].map((char, index) => [char, index]),\n);\n\nfunction bytesToBase64Url(bytes: Uint8Array): string {\n  let out = '';\n  for (let i = 0; i < bytes.length; i += 3) {\n    const b0 = bytes[i];\n    const b1 = i + 1 < bytes.length ? bytes[i + 1] : undefined;\n    const b2 = i + 2 < bytes.length ? bytes[i + 2] : undefined;\n    out += B64URL_ALPHABET[b0 >> 2];\n    out += B64URL_ALPHABET[((b0 & 0x03) << 4) | ((b1 ?? 0) >> 4)];\n    if (b1 !== undefined) {\n      out += B64URL_ALPHABET[((b1 & 0x0f) << 2) | ((b2 ?? 0) >> 6)];\n    }\n    if (b2 !== undefined) {\n      out += B64URL_ALPHABET[b2 & 0x3f];\n    }\n  }\n  return out;\n}\n\nfunction base64UrlToBytes(encoded: string): Uint8Array {\n  if (encoded.length % 4 === 1) {\n    throw new HttpApiResourceIdError(`Invalid base64url payload length in HTTP-API resource id (length ${encoded.length}).`);\n  }\n  const byteLength = Math.floor((encoded.length * 3) / 4);\n  const bytes = new Uint8Array(byteLength);\n  let byteIndex = 0;\n  let buffer = 0;\n  let bitsInBuffer = 0;\n  for (const char of encoded) {\n    const value = B64URL_REVERSE.get(char);\n    if (value === undefined) {\n      throw new HttpApiResourceIdError(`Invalid base64url character '${char}' in HTTP-API resource id.`);\n    }\n    buffer = (buffer << 6) | value;\n    bitsInBuffer += 6;\n    if (bitsInBuffer >= 8) {\n      bitsInBuffer -= 8;\n      bytes[byteIndex] = (buffer >> bitsInBuffer) & 0xff;\n      byteIndex += 1;\n    }\n  }\n  return bytes;\n}\n\n// --------------------------------\n// Component normalization per codec\n// --------------------------------\n\n/**\n * Normalize one raw remote key value per its declared codec. Normalization is what makes the\n * synthesis STABLE: the same remote row must produce byte-identical components regardless of the\n * remote system's incidental formatting (GUID casing, datetime precision).\n */\nexport function normalizeHttpApiKeyComponent(\n  keyField: HttpApiKeyField,\n  rawValue: unknown,\n): HttpApiKeyComponentValue {\n  switch (keyField.codec) {\n    case HttpApiKeyComponentCodec.STRING: {\n      if (typeof rawValue !== 'string' || rawValue.length === 0) {\n        throw new HttpApiResourceIdError(\n          `HTTP-API key component '${keyField.remoteField}' (codec STRING) must be a non-empty string, got ${describeValue(rawValue)}.`,\n        );\n      }\n      return rawValue;\n    }\n    case HttpApiKeyComponentCodec.INTEGER: {\n      const numeric = typeof rawValue === 'string' && /^-?\\d+$/.test(rawValue) ? Number(rawValue) : rawValue;\n      if (typeof numeric !== 'number' || !Number.isSafeInteger(numeric)) {\n        throw new HttpApiResourceIdError(\n          `HTTP-API key component '${keyField.remoteField}' (codec INTEGER) must be a safe integer, got ${describeValue(rawValue)}.`,\n        );\n      }\n      return numeric;\n    }\n    case HttpApiKeyComponentCodec.GUID: {\n      if (typeof rawValue !== 'string' || !GUID_PATTERN.test(rawValue)) {\n        throw new HttpApiResourceIdError(\n          `HTTP-API key component '${keyField.remoteField}' (codec GUID) must be a GUID string, got ${describeValue(rawValue)}.`,\n        );\n      }\n      // Lowercase so the same remote row synthesizes the same id regardless of the target's casing.\n      return rawValue.toLowerCase();\n    }\n    case HttpApiKeyComponentCodec.DATETIME_ISO: {\n      // Strict ISO 8601 shape gate BEFORE Date.parse: bare Date.parse accepts\n      // implementation-defined non-ISO formats, which would make the synthesized id differ\n      // across JS engines — the determinism the module contract promises would silently hold\n      // only for genuinely ISO inputs.\n      const isStrictIso = typeof rawValue === 'string'\n        && /^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,9})?(?:Z|[+-]\\d{2}:\\d{2})$/.test(rawValue);\n      const timestamp = isStrictIso ? Date.parse(rawValue as string) : Number.NaN;\n      if (Number.isNaN(timestamp)) {\n        throw new HttpApiResourceIdError(\n          `HTTP-API key component '${keyField.remoteField}' (codec DATETIME_ISO) must be an ISO 8601 datetime string with an explicit offset, got ${describeValue(rawValue)}.`,\n        );\n      }\n      return new Date(timestamp).toISOString();\n    }\n  }\n}\n\nfunction describeValue(value: unknown): string {\n  if (typeof value === 'string') {\n    return `'${value.length > 64 ? `${value.slice(0, 64)}…` : value}'`;\n  }\n  return `${typeof value} ${String(value)}`;\n}\n\n// --------------------------------\n// Encode / decode (the two id forms)\n// --------------------------------\n\n/**\n * Synthesize the engine-facing `_id` for one remote row, from its raw remote key values in\n * `keyFields` order. The form (verbatim vs encoded) is a static property of the binding\n * (`httpApiBindingUsesVerbatimKey`).\n */\nexport function synthesizeHttpApiResourceId(\n  binding: { keyFields: readonly HttpApiKeyField[] },\n  rawComponents: readonly unknown[],\n): string {\n  if (rawComponents.length !== binding.keyFields.length) {\n    throw new HttpApiResourceIdError(\n      `HTTP-API id synthesis received ${rawComponents.length} key component(s) for a binding declaring ${binding.keyFields.length}.`,\n    );\n  }\n  const normalized = binding.keyFields.map((keyField, index) =>\n    normalizeHttpApiKeyComponent(keyField, rawComponents[index]),\n  );\n\n  if (httpApiBindingUsesVerbatimKey(binding)) {\n    const verbatim = String(normalized[0]);\n    // Defensive: the codec gate should make this unreachable, but the charset law is the invariant\n    // every downstream consumer relies on, so it is asserted where the id is minted.\n    assertCharsetSafe(verbatim);\n    return verbatim;\n  }\n\n  const encoded = bytesToBase64Url(new TextEncoder().encode(JSON.stringify(normalized)));\n  assertCharsetSafe(encoded);\n  return encoded;\n}\n\n/**\n * Resolve an engine-facing `_id` back to its normalized key components, in `keyFields` order.\n * Purely local — no remote call. Throws on any id this binding could not have synthesized —\n * INCLUDING every non-canonical ALIAS of a valid id (base64url trailing-bit variants,\n * JSON-whitespace variants, non-normalized verbatim forms such as an uppercase GUID): one remote\n * row answers to exactly ONE engine id, because row identity, URL canonicality, dedup keys and\n * id-based exclusion filters are all built on that equality. Enforced by re-synthesizing from the\n * resolved components and requiring byte-equality with the incoming id.\n */\nexport function resolveHttpApiKeyComponents(\n  binding: { keyFields: readonly HttpApiKeyField[] },\n  resourceId: string,\n): HttpApiKeyComponentValue[] {\n  if (resourceId.length === 0) {\n    throw new HttpApiResourceIdError('HTTP-API resource id must be a non-empty string.');\n  }\n\n  let components: HttpApiKeyComponentValue[];\n  if (httpApiBindingUsesVerbatimKey(binding)) {\n    components = [normalizeHttpApiKeyComponent(binding.keyFields[0], resourceId)];\n  } else {\n    assertCharsetSafe(resourceId);\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(new TextDecoder().decode(base64UrlToBytes(resourceId)));\n    } catch (error) {\n      throw new HttpApiResourceIdError(\n        `HTTP-API resource id '${resourceId}' is not a valid encoded composite key: ${error instanceof Error ? error.message : String(error)}`,\n      );\n    }\n    if (!Array.isArray(parsed) || parsed.length !== binding.keyFields.length) {\n      throw new HttpApiResourceIdError(\n        `HTTP-API resource id '${resourceId}' decodes to ${Array.isArray(parsed) ? `${parsed.length} component(s)` : 'a non-array'} for a binding declaring ${binding.keyFields.length}.`,\n      );\n    }\n    components = binding.keyFields.map((keyField, index) => normalizeHttpApiKeyComponent(keyField, parsed[index]));\n  }\n\n  // Canonicality gate: re-synthesize and require byte-equality. Normalization is idempotent per\n  // codec, so a canonical id always round-trips to itself; any alias (dropped-bit base64url\n  // variant, whitespace-bearing JSON, '042' for an INTEGER key, 'ABC…' for a GUID key) differs\n  // here and is refused rather than silently adopted as a second name for the same row.\n  const canonical = synthesizeHttpApiResourceId(binding, components);\n  if (canonical !== resourceId) {\n    throw new HttpApiResourceIdError(\n      `HTTP-API resource id ${describeValue(resourceId)} is a non-canonical alias of ${describeValue(canonical)} and is refused: every remote row has exactly one engine id.`,\n    );\n  }\n  return components;\n}\n\n/** Runtime guard for the charset law. */\nexport function isCharsetSafeHttpApiResourceId(candidate: string): boolean {\n  return HTTP_API_RESOURCE_ID_CHARSET.test(candidate);\n}\n\nfunction assertCharsetSafe(candidate: string): void {\n  if (!isCharsetSafeHttpApiResourceId(candidate)) {\n    throw new HttpApiResourceIdError(\n      `HTTP-API resource id violates the charset law ${HTTP_API_RESOURCE_ID_CHARSET}: ${describeValue(candidate)}. `\n      + 'Ids must stay URL-unreserved — the frontend substitutes them into URLs without encoding, and websocket room names parse on \\':\\'.',\n    );\n  }\n}\n"]}