@nicia-ai/typegraph 0.37.1 → 0.38.0

package/dist/chunk-I6FX7AAG.js

@@ -0,0 +1,39 @@
+import { ValidationError } from './chunk-DPNA466P.js';
+
+// src/utils/date.ts
+var CANONICAL_ISO_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+function isCanonicalIsoDate(value) {
+  if (!CANONICAL_ISO_DATE_PATTERN.test(value)) return false;
+  const date = new Date(value);
+  return !Number.isNaN(date.getTime()) && date.toISOString() === value;
+}
+function validateCanonicalIsoDate(value, fieldName) {
+  if (!isCanonicalIsoDate(value)) {
+    throw new ValidationError(
+      `Invalid canonical ISO 8601 datetime for "${fieldName}": "${value}". Expected fixed-width UTC: YYYY-MM-DDTHH:mm:ss.sssZ`,
+      {
+        issues: [
+          {
+            path: fieldName,
+            message: `Expected canonical UTC ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ), got: "${value}"`
+          }
+        ]
+      },
+      {
+        suggestion: `Use a fixed-width UTC datetime like "2024-01-15T10:30:00.000Z" (e.g. new Date(value).toISOString()).`
+      }
+    );
+  }
+  return value;
+}
+function validateOptionalCanonicalIsoDate(value, fieldName) {
+  if (value === void 0) return void 0;
+  return validateCanonicalIsoDate(value, fieldName);
+}
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+
+export { isCanonicalIsoDate, nowIso, validateCanonicalIsoDate, validateOptionalCanonicalIsoDate };
+//# sourceMappingURL=chunk-I6FX7AAG.js.map
+//# sourceMappingURL=chunk-I6FX7AAG.js.map

package/dist/chunk-I6FX7AAG.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/utils/date.ts"],"names":[],"mappings":";;;AAyEA,IAAM,0BAAA,GACJ,+CAAA;AAMK,SAAS,mBAAmB,KAAA,EAAwB;AACzD,EAAA,IAAI,CAAC,0BAAA,CAA2B,IAAA,CAAK,KAAK,GAAG,OAAO,KAAA;AACpD,EAAA,MAAM,IAAA,GAAO,IAAI,IAAA,CAAK,KAAK,CAAA;AAC3B,EAAA,OAAO,CAAC,OAAO,KAAA,CAAM,IAAA,CAAK,SAAS,CAAA,IAAK,IAAA,CAAK,WAAA,EAAY,KAAM,KAAA;AACjE;AAgBO,SAAS,wBAAA,CACd,OACA,SAAA,EACQ;AACR,EAAA,IAAI,CAAC,kBAAA,CAAmB,KAAK,CAAA,EAAG;AAC9B,IAAA,MAAM,IAAI,eAAA;AAAA,MACR,CAAA,yCAAA,EAA4C,SAAS,CAAA,IAAA,EAAO,KAAK,CAAA,qDAAA,CAAA;AAAA,MAEjE;AAAA,QACE,MAAA,EAAQ;AAAA,UACN;AAAA,YACE,IAAA,EAAM,SAAA;AAAA,YACN,OAAA,EAAS,qEAAqE,KAAK,CAAA,CAAA;AAAA;AACrF;AACF,OACF;AAAA,MACA;AAAA,QACE,UAAA,EAAY,CAAA,oGAAA;AAAA;AACd,KACF;AAAA,EACF;AACA,EAAA,OAAO,KAAA;AACT;AAUO,SAAS,gCAAA,CACd,OACA,SAAA,EACoB;AACpB,EAAA,IAAI,KAAA,KAAU,QAAW,OAAO,MAAA;AAChC,EAAA,OAAO,wBAAA,CAAyB,OAAO,SAAS,CAAA;AAClD;AAuBO,SAAS,MAAA,GAAiB;AAC/B,EAAA,OAAA,iBAAO,IAAI,IAAA,EAAK,EAAE,WAAA,EAAY;AAChC","file":"chunk-I6FX7AAG.js","sourcesContent":["/**\n * Date encoding utilities for consistent storage.\n *\n * Contract: All dates are stored as ISO 8601 strings in UTC.\n * - Always includes milliseconds\n * - Always UTC (Z suffix)\n * - Sorts correctly as strings\n */\n\nimport { ValidationError } from \"../errors\";\n\n/**\n * ISO 8601 datetime pattern.\n * Matches formats like:\n * - 2024-01-15T10:30:00.000Z\n * - 2024-01-15T10:30:00Z\n * - 2024-01-15T10:30:00.123Z\n */\nconst ISO_DATE_PATTERN = /^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$/;\n\n/**\n * Checks if a string is a valid ISO 8601 datetime.\n *\n * @param value - String to validate\n * @returns True if valid ISO 8601 datetime\n */\nexport function isValidIsoDate(value: string): boolean {\n  if (!ISO_DATE_PATTERN.test(value)) {\n    return false;\n  }\n  // Also check that Date parsing produces a valid date\n  const date = new Date(value);\n  return !Number.isNaN(date.getTime());\n}\n\n/**\n * Validates that a string is a valid ISO 8601 datetime.\n * Throws ValidationError if invalid.\n *\n * @param value - String to validate\n * @param fieldName - Name of field for error message\n * @returns The validated string\n * @throws ValidationError if not a valid ISO datetime\n */\nexport function validateIsoDate(value: string, fieldName: string): string {\n  if (!isValidIsoDate(value)) {\n    throw new ValidationError(\n      `Invalid ISO 8601 datetime for \"${fieldName}\": \"${value}\". ` +\n        `Expected format: YYYY-MM-DDTHH:mm:ss.sssZ`,\n      {\n        issues: [\n          {\n            path: fieldName,\n            message: `Invalid ISO 8601 datetime format. Expected: YYYY-MM-DDTHH:mm:ss.sssZ, got: \"${value}\"`,\n          },\n        ],\n      },\n      {\n        suggestion: `Use a valid ISO 8601 UTC datetime like \"2024-01-15T10:30:00.000Z\"`,\n      },\n    );\n  }\n  return value;\n}\n\n/**\n * Strict canonical ISO 8601 pattern: fixed-width UTC with exactly\n * millisecond precision (`YYYY-MM-DDTHH:mm:ss.sssZ`). Unlike\n * {@link ISO_DATE_PATTERN}, which tolerates a missing or variable-width\n * fractional part, this is the only shape whose lexicographic text order\n * matches chronological order — avoiding cases like `\"...:00.1Z\"` (= `.100`)\n * sorting *after* `\"...:00.101Z\"`.\n */\nconst CANONICAL_ISO_DATE_PATTERN =\n  /^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$/;\n\n/**\n * Checks if a string is a canonical UTC ISO 8601 datetime with fixed\n * millisecond width (`YYYY-MM-DDTHH:mm:ss.sssZ`).\n */\nexport function isCanonicalIsoDate(value: string): boolean {\n  if (!CANONICAL_ISO_DATE_PATTERN.test(value)) return false;\n  const date = new Date(value);\n  return !Number.isNaN(date.getTime()) && date.toISOString() === value;\n}\n\n/**\n * Validates that a string is a canonical UTC ISO 8601 datetime with fixed\n * millisecond width. Stricter than {@link validateIsoDate} (which also\n * accepts missing or 1–2 digit milliseconds): required wherever the value\n * is compared **as text** against stored timestamps and must sort\n * chronologically — e.g. a temporal `asOf` coordinate, where a\n * variable-width value would mis-order and silently include or exclude the\n * wrong rows. Produce one with `new Date(value).toISOString()`.\n *\n * @param value - String to validate\n * @param fieldName - Name of field for error message\n * @returns The validated string\n * @throws ValidationError if not a canonical UTC ISO datetime\n */\nexport function validateCanonicalIsoDate(\n  value: string,\n  fieldName: string,\n): string {\n  if (!isCanonicalIsoDate(value)) {\n    throw new ValidationError(\n      `Invalid canonical ISO 8601 datetime for \"${fieldName}\": \"${value}\". ` +\n        `Expected fixed-width UTC: YYYY-MM-DDTHH:mm:ss.sssZ`,\n      {\n        issues: [\n          {\n            path: fieldName,\n            message: `Expected canonical UTC ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ), got: \"${value}\"`,\n          },\n        ],\n      },\n      {\n        suggestion: `Use a fixed-width UTC datetime like \"2024-01-15T10:30:00.000Z\" (e.g. new Date(value).toISOString()).`,\n      },\n    );\n  }\n  return value;\n}\n\n/**\n * Validates an optional canonical ISO date string. Returns `undefined` for an\n * absent value; otherwise enforces canonical fixed-width UTC ISO 8601 via\n * {@link validateCanonicalIsoDate}. Used for stored validity-window inputs\n * (`validFrom` / `validTo`) so every timestamp the temporal filters compare as\n * text is canonical and sorts chronologically — the same contract the `asOf`\n * read coordinate already enforces.\n */\nexport function validateOptionalCanonicalIsoDate(\n  value: string | undefined,\n  fieldName: string,\n): string | undefined {\n  if (value === undefined) return undefined;\n  return validateCanonicalIsoDate(value, fieldName);\n}\n\n/**\n * Encodes a Date to an ISO 8601 string for storage.\n */\nexport function encodeDate(date: Date): string {\n  return date.toISOString();\n}\n\n/**\n * Decodes an ISO 8601 string to a Date.\n * Validates the string format first.\n *\n * @throws ValidationError if not a valid ISO datetime\n */\nexport function decodeDate(isoString: string): Date {\n  validateIsoDate(isoString, \"date\");\n  return new Date(isoString);\n}\n\n/**\n * Returns the current timestamp as an ISO string.\n */\nexport function nowIso(): string {\n  return new Date().toISOString();\n}\n"]}

package/dist/chunk-IMQKXL4E.cjs

@@ -0,0 +1,12 @@
+'use strict';
+
+var chunkN2V3HJFV_cjs = require('./chunk-N2V3HJFV.cjs');
+
+// src/graph-extension/define-graph-extension.ts
+function defineGraphExtension(input) {
+  return chunkN2V3HJFV_cjs.unwrap(chunkN2V3HJFV_cjs.validateGraphExtension(input, { strict: true }));
+}
+
+exports.defineGraphExtension = defineGraphExtension;
+//# sourceMappingURL=chunk-IMQKXL4E.cjs.map
+//# sourceMappingURL=chunk-IMQKXL4E.cjs.map

package/dist/{chunk-QSXTWU4U.cjs.map → chunk-IMQKXL4E.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/graph-extension/define-graph-extension.ts"],"names":["unwrap","validateGraphExtension"],"mappings":";;;;;AAyDO,SAAS,qBAAqB,KAAA,EAAuC;AAC1E,EAAA,OAAOA,yBAAOC,wCAAA,CAAuB,KAAA,EAAO,EAAE,MAAA,EAAQ,IAAA,EAAM,CAAC,CAAA;AAC/D","file":"chunk-QSXTWU4U.cjs","sourcesContent":["/**\n * Public entry for declaring a graph extension.\n *\n * Pure value: validates the input, deeply freezes the result, and returns\n * a `GraphExtension`. Invalid documents throw\n * `GraphExtensionValidationError` carrying every issue with a\n * JSON-pointer `path` to the offending field.\n */\nimport { unwrap } from \"../utils/result\";\nimport { type GraphExtension } from \"./extension-types\";\nimport { validateGraphExtension } from \"./validation\";\n\n/**\n * Validates and freezes a graph-extension document.\n *\n * Authoring entry point — runs validation in **strict** mode: unknown\n * top-level keys (e.g. `node` instead of `nodes`) and unsupported\n * string formats (e.g. `\"date-time\"` with a hyphen instead of\n * `\"datetime\"`) fail loudly with `UNKNOWN_DOCUMENT_KEY` /\n * `UNSUPPORTED_STRING_FORMAT`. The persistence-load path leaves both\n * checks off so a document committed by a future v1.x writer with\n * additive fields still parses on an older v1 reader. Callers\n * accepting raw JSON from an untyped source (e.g. an LLM proposal)\n * should validate first via `validateGraphExtension` and surface\n * the structured issues, then pass the validated document here.\n *\n * @param input - Document describing additional node kinds, edge\n *   kinds, and ontology relations. Must satisfy the v1 property-type\n *   subset documented in `ExtensionPropertyType`.\n *\n * @returns The same document, deeply frozen and shape-checked.\n *\n * @throws {GraphExtensionValidationError} when the document violates\n *   the v1 property-type subset, references undeclared kinds, contains\n *   ontology cycles, etc. The thrown error's `details.issues` array\n *   carries every failure with a JSON-pointer path.\n * @throws {GraphExtensionVersionUnsupportedError} when the document\n *   declares a future major version this library cannot safely decode.\n *\n * @example\n * ```typescript\n * const extension = defineGraphExtension({\n *   nodes: {\n *     Paper: {\n *       properties: {\n *         doi:   { type: \"string\" },\n *         title: { type: \"string\", searchable: { language: \"english\" } },\n *       },\n *       unique: [{ name: \"paper_doi\", fields: [\"doi\"] }],\n *     },\n *   },\n * });\n *\n * const evolved = await store.evolve(extension);\n * const papers = evolved.getNodeCollectionOrThrow(\"Paper\");\n * ```\n */\nexport function defineGraphExtension(input: GraphExtension): GraphExtension {\n  return unwrap(validateGraphExtension(input, { strict: true }));\n}\n"]}
+{"version":3,"sources":["../src/graph-extension/define-graph-extension.ts"],"names":["unwrap","validateGraphExtension"],"mappings":";;;;;AAyDO,SAAS,qBAAqB,KAAA,EAAuC;AAC1E,EAAA,OAAOA,yBAAOC,wCAAA,CAAuB,KAAA,EAAO,EAAE,MAAA,EAAQ,IAAA,EAAM,CAAC,CAAA;AAC/D","file":"chunk-IMQKXL4E.cjs","sourcesContent":["/**\n * Public entry for declaring a graph extension.\n *\n * Pure value: validates the input, deeply freezes the result, and returns\n * a `GraphExtension`. Invalid documents throw\n * `GraphExtensionValidationError` carrying every issue with a\n * JSON-pointer `path` to the offending field.\n */\nimport { unwrap } from \"../utils/result\";\nimport { type GraphExtension } from \"./extension-types\";\nimport { validateGraphExtension } from \"./validation\";\n\n/**\n * Validates and freezes a graph-extension document.\n *\n * Authoring entry point — runs validation in **strict** mode: unknown\n * top-level keys (e.g. `node` instead of `nodes`) and unsupported\n * string formats (e.g. `\"date-time\"` with a hyphen instead of\n * `\"datetime\"`) fail loudly with `UNKNOWN_DOCUMENT_KEY` /\n * `UNSUPPORTED_STRING_FORMAT`. The persistence-load path leaves both\n * checks off so a document committed by a future v1.x writer with\n * additive fields still parses on an older v1 reader. Callers\n * accepting raw JSON from an untyped source (e.g. an LLM proposal)\n * should validate first via `validateGraphExtension` and surface\n * the structured issues, then pass the validated document here.\n *\n * @param input - Document describing additional node kinds, edge\n *   kinds, and ontology relations. Must satisfy the v1 property-type\n *   subset documented in `ExtensionPropertyType`.\n *\n * @returns The same document, deeply frozen and shape-checked.\n *\n * @throws {GraphExtensionValidationError} when the document violates\n *   the v1 property-type subset, references undeclared kinds, contains\n *   ontology cycles, etc. The thrown error's `details.issues` array\n *   carries every failure with a JSON-pointer path.\n * @throws {GraphExtensionVersionUnsupportedError} when the document\n *   declares a future major version this library cannot safely decode.\n *\n * @example\n * ```typescript\n * const extension = defineGraphExtension({\n *   nodes: {\n *     Paper: {\n *       properties: {\n *         doi:   { type: \"string\" },\n *         title: { type: \"string\", searchable: { language: \"english\" } },\n *       },\n *       unique: [{ name: \"paper_doi\", fields: [\"doi\"] }],\n *     },\n *   },\n * });\n *\n * const evolved = await store.evolve(extension);\n * const papers = evolved.getNodeCollectionOrThrow(\"Paper\");\n * ```\n */\nexport function defineGraphExtension(input: GraphExtension): GraphExtension {\n  return unwrap(validateGraphExtension(input, { strict: true }));\n}\n"]}

package/dist/chunk-J6IJARLG.js

@@ -0,0 +1,94 @@
+import { validateCanonicalIsoDate } from './chunk-I6FX7AAG.js';
+import { ValidationError } from './chunk-DPNA466P.js';
+
+// src/core/temporal.ts
+var RECORDED_MAX = "9999-12-31T23:59:59.999Z";
+function assertValidRecordedInstant(value, path) {
+  validateCanonicalIsoDate(value, path);
+  if (value >= RECORDED_MAX) {
+    throw new ValidationError(
+      `${path} must be before the recorded-time open sentinel ${RECORDED_MAX}.`,
+      {
+        issues: [
+          {
+            path,
+            message: `Expected a timestamp before ${RECORDED_MAX}, got "${value}"`
+          }
+        ]
+      },
+      {
+        suggestion: "Use a real recorded-time commit instant, not the open-interval sentinel."
+      }
+    );
+  }
+}
+function asRecordedInstant(value) {
+  assertValidRecordedInstant(value, "asRecordedInstant");
+  return value;
+}
+function resolveReadCoordinate(mode, asOf, suggestion) {
+  if (mode !== "asOf" && asOf !== void 0) {
+    throw new ValidationError(
+      `Temporal mode "${mode}" does not take an asOf timestamp.`,
+      {
+        issues: [
+          {
+            path: "asOf",
+            message: `asOf is only valid with mode "asOf", not "${mode}"`
+          }
+        ]
+      },
+      {
+        suggestion: 'Pin an instant with store.asOf(timestamp) or store.view({ mode: "asOf", asOf }); drop asOf for other modes.'
+      }
+    );
+  }
+  assertValidAsOf(
+    mode,
+    asOf,
+    suggestion === void 0 ? void 0 : { suggestion }
+  );
+  return { valid: asOf === void 0 ? { mode } : { mode, asOf } };
+}
+function withRecordedCoordinate(coordinate, recordedAsOf) {
+  assertValidRecordedInstant(recordedAsOf, "asOfRecorded");
+  return {
+    ...coordinate,
+    recorded: { asOf: recordedAsOf }
+  };
+}
+function assertValidAsOf(mode, asOf, options) {
+  if (mode === "asOf" && asOf === void 0) {
+    throw new ValidationError(
+      'Temporal mode "asOf" requires a timestamp',
+      {
+        issues: [
+          { path: "asOf", message: "Timestamp is required for asOf mode" }
+        ]
+      },
+      {
+        suggestion: options?.suggestion ?? 'Provide an ISO-8601 timestamp for asOf mode, e.g. "2026-01-01T00:00:00.000Z".'
+      }
+    );
+  }
+  if (asOf !== void 0) {
+    validateCanonicalIsoDate(asOf, "asOf");
+  }
+}
+function describeCoordinate(coordinate) {
+  const { mode, asOf } = coordinate.valid;
+  const valid = asOf === void 0 ? `mode "${mode}"` : `mode "${mode}" asOf ${asOf}`;
+  return coordinate.recorded === void 0 ? valid : `${valid}, recorded asOf ${coordinate.recorded.asOf}`;
+}
+function coordinateContext(coordinate) {
+  const { mode, asOf } = coordinate.valid;
+  return {
+    temporalMode: mode,
+    ...asOf !== void 0 && { asOf },
+    ...coordinate.recorded === void 0 ? {} : { recordedAsOf: coordinate.recorded.asOf }
+  };
+}
+
+export { RECORDED_MAX, asRecordedInstant, assertValidRecordedInstant, coordinateContext, describeCoordinate, resolveReadCoordinate, withRecordedCoordinate };
+//# sourceMappingURL=chunk-J6IJARLG.js.map
+//# sourceMappingURL=chunk-J6IJARLG.js.map

package/dist/chunk-J6IJARLG.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/temporal.ts"],"names":[],"mappings":"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","file":"chunk-J6IJARLG.js","sourcesContent":["/**\n * Shared temporal coordinate + validation.\n */\nimport { ValidationError } from \"../errors\";\nimport { validateCanonicalIsoDate } from \"../utils/date\";\nimport { type TemporalMode } from \"./types\";\n\n/**\n * Open-ended recorded-time sentinel. Chosen so SQLite text ordering and\n * PostgreSQL `timestamptz` ordering both put every real commit instant before\n * the open interval end.\n */\nexport const RECORDED_MAX = \"9999-12-31T23:59:59.999Z\";\n\ndeclare const RECORDED_INSTANT_BRAND: unique symbol;\n\n/**\n * A canonical UTC ISO-8601 recorded-time instant (`YYYY-MM-DDTHH:mm:ss.sssZ`),\n * nominally branded so it can only originate from a recorded-time source —\n * {@link Store.recordedNow} or an explicit {@link asRecordedInstant} — never an\n * ad-hoc wall-clock string.\n *\n * The recorded commit clock is a logical, monotonic per-graph instant that can\n * run briefly ahead of wall time under bursty same-millisecond writes, so a raw\n * `new Date().toISOString()` may sort *before* the most recent commits and\n * silently omit them. The brand turns that footgun into a compile error:\n * `store.asOfRecorded` accepts only a `RecordedInstant`, so a bare wall-clock\n * string no longer type-checks — callers reach for `await store.recordedNow()`\n * (the monotonic high-water mark) or {@link asRecordedInstant} instead.\n */\nexport type RecordedInstant = string & {\n  readonly [RECORDED_INSTANT_BRAND]: \"RecordedInstant\";\n};\n\nexport function assertValidRecordedInstant(value: string, path: string): void {\n  validateCanonicalIsoDate(value, path);\n  if (value >= RECORDED_MAX) {\n    throw new ValidationError(\n      `${path} must be before the recorded-time open sentinel ${RECORDED_MAX}.`,\n      {\n        issues: [\n          {\n            path,\n            message: `Expected a timestamp before ${RECORDED_MAX}, got \"${value}\"`,\n          },\n        ],\n      },\n      {\n        suggestion:\n          \"Use a real recorded-time commit instant, not the open-interval sentinel.\",\n      },\n    );\n  }\n}\n\n/**\n * Brands a canonical UTC ISO-8601 string as a {@link RecordedInstant}.\n *\n * The escape hatch for an instant that round-trips through untyped storage:\n * captured from {@link Store.recordedNow}, persisted as a plain string, read\n * back, and replayed into `asOfRecorded`. Validates the canonical form eagerly —\n * the same check `asOfRecorded` applies — so a malformed value fails here, at the\n * brand site, rather than deeper in a read. Does *not* assert the instant is a\n * real captured commit; it only guarantees the value is well-formed enough to\n * compare correctly against the recorded relations.\n *\n * @throws {ValidationError} when `value` is not a canonical UTC ISO-8601 string.\n */\nexport function asRecordedInstant(value: string): RecordedInstant {\n  assertValidRecordedInstant(value, \"asRecordedInstant\");\n  return value as RecordedInstant;\n}\n\n/**\n * The single opaque temporal coordinate every pinned read is resolved\n * against. It carries the valid-time axis plus an optional recorded/system-time\n * axis, so every surface can inject one coordinate object instead of threading\n * each temporal dimension separately.\n */\nexport type ReadCoordinate = Readonly<{\n  /**\n   * The valid-time axis: a resolved temporal mode and (only for `\"asOf\"`) the\n   * instant it is pinned to.\n   */\n  valid: Readonly<{\n    mode: TemporalMode;\n    /** Defined only when `mode` is `\"asOf\"`. */\n    asOf?: string;\n  }>;\n  /** The recorded/system-time axis. Defined only for recorded-pinned views. */\n  recorded?: Readonly<{ asOf: RecordedInstant }>;\n}>;\n\n/**\n * Resolves and validates a `(mode, asOf)` pair into a {@link ReadCoordinate}.\n * Rejects an `asOf` paired with any non-`\"asOf\"` mode rather than silently\n * dropping it — pinning an instant is only meaningful in `\"asOf\"` mode, so a\n * `view({ mode: \"current\", asOf })` is a caller mistake, not a coordinate to\n * quietly discard. Then validates via {@link assertValidAsOf}.\n *\n * @param mode - The temporal mode to pin.\n * @param asOf - The supplied timestamp. Required for `\"asOf\"`; rejected for\n *   every other mode.\n * @param suggestion - Caller-specific remediation hint for the\n *   missing/invalid-timestamp case.\n */\nexport function resolveReadCoordinate(\n  mode: TemporalMode,\n  asOf: string | undefined,\n  suggestion?: string,\n): ReadCoordinate {\n  if (mode !== \"asOf\" && asOf !== undefined) {\n    throw new ValidationError(\n      `Temporal mode \"${mode}\" does not take an asOf timestamp.`,\n      {\n        issues: [\n          {\n            path: \"asOf\",\n            message: `asOf is only valid with mode \"asOf\", not \"${mode}\"`,\n          },\n        ],\n      },\n      {\n        suggestion:\n          'Pin an instant with store.asOf(timestamp) or store.view({ mode: \"asOf\", asOf }); drop asOf for other modes.',\n      },\n    );\n  }\n  assertValidAsOf(\n    mode,\n    asOf,\n    suggestion === undefined ? undefined : { suggestion },\n  );\n  return { valid: asOf === undefined ? { mode } : { mode, asOf } };\n}\n\n/**\n * Adds a recorded/system-time pin to an existing valid-time coordinate.\n * Direct `store.asOfRecorded(T)` passes the diagonal valid-time coordinate\n * (`mode: \"asOf\", asOf: T`); `store.asOf(vt).asOfRecorded(rt)` passes the\n * already-resolved valid coordinate and adds the recorded sibling.\n */\nexport function withRecordedCoordinate(\n  coordinate: ReadCoordinate,\n  recordedAsOf: RecordedInstant,\n): ReadCoordinate {\n  assertValidRecordedInstant(recordedAsOf, \"asOfRecorded\");\n  return {\n    ...coordinate,\n    recorded: { asOf: recordedAsOf },\n  };\n}\n\n/**\n * Validates the `asOf` coordinate of a temporal read: `\"asOf\"` mode\n * requires a timestamp, and any supplied timestamp must be a canonical\n * fixed-width UTC ISO-8601 string (`YYYY-MM-DDTHH:mm:ss.sssZ`). The latter\n * is load-bearing — temporal filters compare `asOf` against `valid_from` /\n * `valid_to` as text on SQLite, so a non-canonical value (date-only, an\n * offset, natural language, or variable-width / missing milliseconds like\n * `.1Z`) would sort and compare wrong rather than error. Reached only through\n * {@link resolveReadCoordinate}, which every temporal read entry point routes\n * through (direct reads, queries, subgraphs, algorithms, and StoreView), so\n * they all fail identically.\n *\n * @param mode - The resolved temporal mode.\n * @param asOf - The supplied timestamp (may be `undefined`).\n * @param options.suggestion - A caller-specific remediation hint for the\n *   missing-timestamp case.\n *\n * @throws {ValidationError} when `mode` is `\"asOf\"` and `asOf` is missing, or\n *   when any supplied `asOf` is not a canonical UTC ISO-8601 timestamp. The\n *   canonical check runs for *every* mode that consumes `asOf`, so a\n *   non-canonical value can never reach a text comparison.\n */\nfunction assertValidAsOf(\n  mode: TemporalMode,\n  asOf: string | undefined,\n  options?: Readonly<{ suggestion?: string }>,\n): void {\n  if (mode === \"asOf\" && asOf === undefined) {\n    throw new ValidationError(\n      'Temporal mode \"asOf\" requires a timestamp',\n      {\n        issues: [\n          { path: \"asOf\", message: \"Timestamp is required for asOf mode\" },\n        ],\n      },\n      {\n        suggestion:\n          options?.suggestion ??\n          'Provide an ISO-8601 timestamp for asOf mode, e.g. \"2026-01-01T00:00:00.000Z\".',\n      },\n    );\n  }\n  if (asOf !== undefined) {\n    validateCanonicalIsoDate(asOf, \"asOf\");\n  }\n}\n\n/**\n * A human-readable description of a coordinate for error messages, e.g.\n * `mode \"current\"` or `mode \"asOf\" asOf 2026-01-01T00:00:00.000Z`. Shared by\n * every refusal path (the `StoreView` read-only / current-only / search facades\n * and the sealed-query builder) so they describe a coordinate identically — and\n * a future axis (recorded time) is reflected everywhere from one place.\n */\nexport function describeCoordinate(coordinate: ReadCoordinate): string {\n  const { mode, asOf } = coordinate.valid;\n  const valid =\n    asOf === undefined ? `mode \"${mode}\"` : `mode \"${mode}\" asOf ${asOf}`;\n  return coordinate.recorded === undefined ?\n      valid\n    : `${valid}, recorded asOf ${coordinate.recorded.asOf}`;\n}\n\n/**\n * The structured error-context fields describing a coordinate, shared by the\n * same refusal paths as {@link describeCoordinate}.\n */\nexport function coordinateContext(\n  coordinate: ReadCoordinate,\n): Record<string, unknown> {\n  const { mode, asOf } = coordinate.valid;\n  return {\n    temporalMode: mode,\n    ...(asOf !== undefined && { asOf }),\n    ...(coordinate.recorded === undefined ?\n      {}\n    : { recordedAsOf: coordinate.recorded.asOf }),\n  };\n}\n"]}

package/dist/{chunk-W63OVYY4.js → chunk-K34OPSJK.js}

@@ -1,4 +1,4 @@
-import { FNV1A_OFFSET_BASIS, FNV1A_PRIME } from './chunk-OHMP6N2J.js';
+import { FNV1A_OFFSET_BASIS, FNV1A_PRIME } from './chunk-2EBMPJBO.js';
 
 // src/utils/hash.ts
 function fnv1aBase36(input) {
@@ -25,5 +25,5 @@ async function sha256Hex(input, byteLength = 8) {
 }
 
 export { fnv1aBase36, sha256Hex };
-//# sourceMappingURL=chunk-W63OVYY4.js.map
-//# sourceMappingURL=chunk-W63OVYY4.js.map
+//# sourceMappingURL=chunk-K34OPSJK.js.map
+//# sourceMappingURL=chunk-K34OPSJK.js.map

package/dist/{chunk-W63OVYY4.js.map → chunk-K34OPSJK.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/utils/hash.ts"],"names":[],"mappings":";;;AAWO,SAAS,YAAY,KAAA,EAAuB;AACjD,EAAA,IAAI,IAAA,GAAO,kBAAA;AACX,EAAA,KAAA,MAAW,aAAa,KAAA,EAAO;AAC7B,IAAA,MAAM,SAAA,GAAY,SAAA,CAAU,WAAA,CAAY,CAAC,CAAA;AACzC,IAAA,IAAI,cAAc,MAAA,EAAW;AAC7B,IAAA,IAAA,IAAQ,SAAA;AACR,IAAA,IAAA,GAAO,IAAA,CAAK,IAAA,CAAK,IAAA,EAAM,WAAW,CAAA;AAAA,EACpC;AACA,EAAA,OAAA,CAAQ,IAAA,KAAS,CAAA,EAAG,QAAA,CAAS,EAAE,CAAA;AACjC;AAWA,eAAsB,SAAA,CACpB,KAAA,EACA,UAAA,GAAa,CAAA,EACI;AACjB,EAAA,MAAM,OAAA,GAAU,IAAI,WAAA,EAAY,CAAE,OAAO,KAAK,CAAA;AAC9C,EAAA,MAAM,SAAS,MAAM,UAAA,CAAW,OAAO,MAAA,CAAO,MAAA,CAAO,WAAW,OAAO,CAAA;AACvE,EAAA,MAAM,KAAA,GAAQ,IAAI,UAAA,CAAW,MAAM,CAAA;AACnC,EAAA,IAAI,GAAA,GAAM,EAAA;AACV,EAAA,KAAA,IAAS,KAAA,GAAQ,CAAA,EAAG,KAAA,GAAQ,UAAA,EAAY,KAAA,EAAA,EAAS;AAC/C,IAAA,MAAM,IAAA,GAAO,MAAM,KAAK,CAAA;AACxB,IAAA,IAAI,SAAS,MAAA,EAAW;AACxB,IAAA,GAAA,IAAO,KAAK,QAAA,CAAS,EAAE,CAAA,CAAE,QAAA,CAAS,GAAG,GAAG,CAAA;AAAA,EAC1C;AACA,EAAA,OAAO,GAAA;AACT","file":"chunk-W63OVYY4.js","sourcesContent":["/**\n * Hash utilities — FNV-1a for fast non-cryptographic identifier\n * generation, SHA-256 (truncated) for collision-resistant signatures.\n */\nimport { FNV1A_OFFSET_BASIS, FNV1A_PRIME } from \"../constants\";\n\n/**\n * FNV-1a hash of `input`, returned as a base-36 encoded string. Used for\n * generating short, deterministic identifiers (column aliases, index\n * name suffixes, etc.).\n */\nexport function fnv1aBase36(input: string): string {\n  let hash = FNV1A_OFFSET_BASIS;\n  for (const character of input) {\n    const codePoint = character.codePointAt(0);\n    if (codePoint === undefined) continue;\n    hash ^= codePoint;\n    hash = Math.imul(hash, FNV1A_PRIME);\n  }\n  return (hash >>> 0).toString(36);\n}\n\n/**\n * Hex-truncated SHA-256 of `input` via the Web Crypto API. Works in\n * Node.js 16+, Cloudflare Workers, Deno, and browsers.\n *\n * `byteLength` controls how many bytes of the digest are emitted —\n * default 8 (16 hex chars, ~64 bits, sufficient for schema-version and\n * per-graph index signatures). Pass 16 (32 hex chars) when hashes are\n * compared against externally-stored signatures.\n */\nexport async function sha256Hex(\n  input: string,\n  byteLength = 8,\n): Promise<string> {\n  const encoded = new TextEncoder().encode(input);\n  const digest = await globalThis.crypto.subtle.digest(\"SHA-256\", encoded);\n  const bytes = new Uint8Array(digest);\n  let hex = \"\";\n  for (let index = 0; index < byteLength; index++) {\n    const byte = bytes[index];\n    if (byte === undefined) break;\n    hex += byte.toString(16).padStart(2, \"0\");\n  }\n  return hex;\n}\n"]}
+{"version":3,"sources":["../src/utils/hash.ts"],"names":[],"mappings":";;;AAWO,SAAS,YAAY,KAAA,EAAuB;AACjD,EAAA,IAAI,IAAA,GAAO,kBAAA;AACX,EAAA,KAAA,MAAW,aAAa,KAAA,EAAO;AAC7B,IAAA,MAAM,SAAA,GAAY,SAAA,CAAU,WAAA,CAAY,CAAC,CAAA;AACzC,IAAA,IAAI,cAAc,MAAA,EAAW;AAC7B,IAAA,IAAA,IAAQ,SAAA;AACR,IAAA,IAAA,GAAO,IAAA,CAAK,IAAA,CAAK,IAAA,EAAM,WAAW,CAAA;AAAA,EACpC;AACA,EAAA,OAAA,CAAQ,IAAA,KAAS,CAAA,EAAG,QAAA,CAAS,EAAE,CAAA;AACjC;AAWA,eAAsB,SAAA,CACpB,KAAA,EACA,UAAA,GAAa,CAAA,EACI;AACjB,EAAA,MAAM,OAAA,GAAU,IAAI,WAAA,EAAY,CAAE,OAAO,KAAK,CAAA;AAC9C,EAAA,MAAM,SAAS,MAAM,UAAA,CAAW,OAAO,MAAA,CAAO,MAAA,CAAO,WAAW,OAAO,CAAA;AACvE,EAAA,MAAM,KAAA,GAAQ,IAAI,UAAA,CAAW,MAAM,CAAA;AACnC,EAAA,IAAI,GAAA,GAAM,EAAA;AACV,EAAA,KAAA,IAAS,KAAA,GAAQ,CAAA,EAAG,KAAA,GAAQ,UAAA,EAAY,KAAA,EAAA,EAAS;AAC/C,IAAA,MAAM,IAAA,GAAO,MAAM,KAAK,CAAA;AACxB,IAAA,IAAI,SAAS,MAAA,EAAW;AACxB,IAAA,GAAA,IAAO,KAAK,QAAA,CAAS,EAAE,CAAA,CAAE,QAAA,CAAS,GAAG,GAAG,CAAA;AAAA,EAC1C;AACA,EAAA,OAAO,GAAA;AACT","file":"chunk-K34OPSJK.js","sourcesContent":["/**\n * Hash utilities — FNV-1a for fast non-cryptographic identifier\n * generation, SHA-256 (truncated) for collision-resistant signatures.\n */\nimport { FNV1A_OFFSET_BASIS, FNV1A_PRIME } from \"../constants\";\n\n/**\n * FNV-1a hash of `input`, returned as a base-36 encoded string. Used for\n * generating short, deterministic identifiers (column aliases, index\n * name suffixes, etc.).\n */\nexport function fnv1aBase36(input: string): string {\n  let hash = FNV1A_OFFSET_BASIS;\n  for (const character of input) {\n    const codePoint = character.codePointAt(0);\n    if (codePoint === undefined) continue;\n    hash ^= codePoint;\n    hash = Math.imul(hash, FNV1A_PRIME);\n  }\n  return (hash >>> 0).toString(36);\n}\n\n/**\n * Hex-truncated SHA-256 of `input` via the Web Crypto API. Works in\n * Node.js 16+, Cloudflare Workers, Deno, and browsers.\n *\n * `byteLength` controls how many bytes of the digest are emitted —\n * default 8 (16 hex chars, ~64 bits, sufficient for schema-version and\n * per-graph index signatures). Pass 16 (32 hex chars) when hashes are\n * compared against externally-stored signatures.\n */\nexport async function sha256Hex(\n  input: string,\n  byteLength = 8,\n): Promise<string> {\n  const encoded = new TextEncoder().encode(input);\n  const digest = await globalThis.crypto.subtle.digest(\"SHA-256\", encoded);\n  const bytes = new Uint8Array(digest);\n  let hex = \"\";\n  for (let index = 0; index < byteLength; index++) {\n    const byte = bytes[index];\n    if (byte === undefined) break;\n    hex += byte.toString(16).padStart(2, \"0\");\n  }\n  return hex;\n}\n"]}