@odla-ai/kg 0.2.3 → 0.3.0

package/dist/chunk-V3N2GRYU.js

@@ -0,0 +1,73 @@
+// src/temporal/time.ts
+var DAY = 864e5;
+var DATE_ONLY = /^(\d{4})-(\d{2})-(\d{2})$/;
+function parseDateMs(v) {
+  if (typeof v === "number") return Number.isFinite(v) ? v : null;
+  if (typeof v !== "string") return null;
+  const m = DATE_ONLY.exec(v.trim());
+  if (m) {
+    const t2 = Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]));
+    return new Date(t2).toISOString().slice(0, 10) === m[0].trim() ? t2 : null;
+  }
+  const t = Date.parse(v);
+  return Number.isNaN(t) ? null : t;
+}
+function isoWeek(t) {
+  const d = new Date(t);
+  const midnight = Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate());
+  const dow = new Date(midnight).getUTCDay() || 7;
+  const thursday = midnight + (4 - dow) * DAY;
+  const year = new Date(thursday).getUTCFullYear();
+  const week = Math.floor((thursday - Date.UTC(year, 0, 1)) / DAY / 7) + 1;
+  return { year, week };
+}
+function isoWeekStart(year, week) {
+  const jan4 = Date.UTC(year, 0, 4);
+  const dow = new Date(jan4).getUTCDay() || 7;
+  return jan4 - (dow - 1) * DAY + (week - 1) * 7 * DAY;
+}
+var pad2 = (n) => String(n).padStart(2, "0");
+function bucketKey(t, grain) {
+  const d = new Date(t);
+  if (grain === "month") return `${d.getUTCFullYear()}-${pad2(d.getUTCMonth() + 1)}`;
+  if (grain === "quarter") return `${d.getUTCFullYear()}-Q${Math.floor(d.getUTCMonth() / 3) + 1}`;
+  const { year, week } = isoWeek(t);
+  return `${year}-W${pad2(week)}`;
+}
+function bucketFor(key) {
+  let m = /^(\d{4})-(\d{2})$/.exec(key);
+  if (m) {
+    const [y, mo] = [Number(m[1]), Number(m[2])];
+    return { key, start: Date.UTC(y, mo - 1, 1), end: Date.UTC(y, mo, 1) };
+  }
+  m = /^(\d{4})-Q([1-4])$/.exec(key);
+  if (m) {
+    const [y, q] = [Number(m[1]), Number(m[2])];
+    return { key, start: Date.UTC(y, (q - 1) * 3, 1), end: Date.UTC(y, q * 3, 1) };
+  }
+  m = /^(\d{4})-W(\d{2})$/.exec(key);
+  if (m) {
+    const start = isoWeekStart(Number(m[1]), Number(m[2]));
+    return { key, start, end: start + 7 * DAY };
+  }
+  throw new Error(`not a bucket key: ${key}`);
+}
+function bucketRange(from, to, grain) {
+  const out = [];
+  if (from > to) return out;
+  let cur = bucketFor(bucketKey(from, grain));
+  const last = bucketKey(to, grain);
+  for (; ; ) {
+    out.push(cur);
+    if (cur.key === last) return out;
+    cur = bucketFor(bucketKey(cur.end, grain));
+  }
+}
+
+export {
+  parseDateMs,
+  bucketKey,
+  bucketFor,
+  bucketRange
+};
+//# sourceMappingURL=chunk-V3N2GRYU.js.map

package/dist/chunk-V3N2GRYU.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/temporal/time.ts"],"sourcesContent":["// UTC-only time bucketing. Date-only strings are read as UTC midnight and all\n// bucket math uses Date.UTC accessors — results never depend on the host zone.\n\n/** Supported bucketing granularities. */\nexport type TimeGrain = \"week\" | \"month\" | \"quarter\";\n\n/** One half-open time bucket: `start` inclusive, `end` exclusive (epoch ms). */\nexport interface TimeBucket {\n  key: string;\n  start: number;\n  end: number;\n}\n\nconst DAY = 86_400_000;\nconst DATE_ONLY = /^(\\d{4})-(\\d{2})-(\\d{2})$/;\n\n/**\n * Parse a date-ish value to epoch ms, or null if unparseable. Accepts\n * `\"YYYY-MM-DD\"` (UTC midnight, with real calendar validation — `2026-02-31`\n * is null), full ISO strings, and finite numbers (already epoch ms).\n */\nexport function parseDateMs(v: unknown): number | null {\n  if (typeof v === \"number\") return Number.isFinite(v) ? v : null;\n  if (typeof v !== \"string\") return null;\n  const m = DATE_ONLY.exec(v.trim());\n  if (m) {\n    const t = Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]));\n    // JS rolls invalid components (\"2026-02-31\" → Mar 3); a real date\n    // round-trips to the same YYYY-MM-DD.\n    return new Date(t).toISOString().slice(0, 10) === m[0].trim() ? t : null;\n  }\n  const t = Date.parse(v);\n  return Number.isNaN(t) ? null : t;\n}\n\n// ISO-8601 week: week 1 contains the year's first Thursday; weeks run Mon–Sun.\nfunction isoWeek(t: number): { year: number; week: number } {\n  const d = new Date(t);\n  const midnight = Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate());\n  const dow = new Date(midnight).getUTCDay() || 7; // Mon=1 … Sun=7\n  const thursday = midnight + (4 - dow) * DAY;\n  const year = new Date(thursday).getUTCFullYear();\n  const week = Math.floor((thursday - Date.UTC(year, 0, 1)) / DAY / 7) + 1;\n  return { year, week };\n}\n\n// Monday (UTC midnight) of ISO week `week` of ISO year `year`: Jan 4 is\n// always inside week 1.\nfunction isoWeekStart(year: number, week: number): number {\n  const jan4 = Date.UTC(year, 0, 4);\n  const dow = new Date(jan4).getUTCDay() || 7;\n  return jan4 - (dow - 1) * DAY + (week - 1) * 7 * DAY;\n}\n\nconst pad2 = (n: number) => String(n).padStart(2, \"0\");\n\n/** The bucket key containing epoch-ms `t`: `\"2026-07\"`, `\"2026-Q3\"`, or `\"2026-W29\"`. */\nexport function bucketKey(t: number, grain: TimeGrain): string {\n  const d = new Date(t);\n  if (grain === \"month\") return `${d.getUTCFullYear()}-${pad2(d.getUTCMonth() + 1)}`;\n  if (grain === \"quarter\") return `${d.getUTCFullYear()}-Q${Math.floor(d.getUTCMonth() / 3) + 1}`;\n  const { year, week } = isoWeek(t);\n  return `${year}-W${pad2(week)}`;\n}\n\n/**\n * Expand a bucket key back to its half-open [start, end) range. Throws on a\n * key that matches no known grain format.\n */\nexport function bucketFor(key: string): TimeBucket {\n  let m = /^(\\d{4})-(\\d{2})$/.exec(key);\n  if (m) {\n    const [y, mo] = [Number(m[1]), Number(m[2])];\n    return { key, start: Date.UTC(y, mo - 1, 1), end: Date.UTC(y, mo, 1) };\n  }\n  m = /^(\\d{4})-Q([1-4])$/.exec(key);\n  if (m) {\n    const [y, q] = [Number(m[1]), Number(m[2])];\n    return { key, start: Date.UTC(y, (q - 1) * 3, 1), end: Date.UTC(y, q * 3, 1) };\n  }\n  m = /^(\\d{4})-W(\\d{2})$/.exec(key);\n  if (m) {\n    const start = isoWeekStart(Number(m[1]), Number(m[2]));\n    return { key, start, end: start + 7 * DAY };\n  }\n  throw new Error(`not a bucket key: ${key}`);\n}\n\n/**\n * Every bucket from the one containing `from` through the one containing `to`,\n * in order. Returns [] when from > to.\n */\nexport function bucketRange(from: number, to: number, grain: TimeGrain): TimeBucket[] {\n  const out: TimeBucket[] = [];\n  if (from > to) return out;\n  let cur = bucketFor(bucketKey(from, grain));\n  const last = bucketKey(to, grain);\n  for (;;) {\n    out.push(cur);\n    if (cur.key === last) return out;\n    cur = bucketFor(bucketKey(cur.end, grain));\n  }\n}\n"],"mappings":"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","names":["t"]}

package/dist/index.cjs

@@ -33,6 +33,7 @@ __export(index_exports, {
   createProvider: () => createProvider,
   emptyUsage: () => emptyUsage,
   enabledSources: () => enabledSources,
+  exportFragment: () => exportFragment,
   extractJson: () => extractJson,
   extractJsonArray: () => extractJsonArray,
   fetchText: () => fetchText,
@@ -207,6 +208,124 @@ async function writeFragment(db, fragment, ontology, mutationId) {
   return { txId, ops: ops.length };
 }
 
+// src/temporal/time.ts
+var DATE_ONLY = /^(\d{4})-(\d{2})-(\d{2})$/;
+function parseDateMs(v) {
+  if (typeof v === "number") return Number.isFinite(v) ? v : null;
+  if (typeof v !== "string") return null;
+  const m = DATE_ONLY.exec(v.trim());
+  if (m) {
+    const t2 = Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]));
+    return new Date(t2).toISOString().slice(0, 10) === m[0].trim() ? t2 : null;
+  }
+  const t = Date.parse(v);
+  return Number.isNaN(t) ? null : t;
+}
+
+// src/graph/export.ts
+function planLinks(ontology, type, labels) {
+  return labels.map((label) => {
+    for (const edge of Object.values(ontology.edges)) {
+      if (edge.forwardLabel === label && edge.from === type) {
+        return { label, counterpart: edge.to, direction: "forward", forwardLabel: edge.forwardLabel };
+      }
+      if (edge.reverseLabel === label && edge.to === type) {
+        return { label, counterpart: edge.from, direction: "reverse", forwardLabel: edge.forwardLabel };
+      }
+    }
+    throw new Error(`exportFragment: no ontology edge matches link "${label}" on "${type}"`);
+  });
+}
+var isScalar = (v) => v === null || typeof v !== "object" && typeof v !== "function";
+function pickAttrs(row, spec, links) {
+  const out = {};
+  for (const [k, v] of Object.entries(row)) {
+    if (spec.attrs ? !spec.attrs.includes(k) : k === "id" || links.includes(k) || !isScalar(v)) continue;
+    if (isScalar(v) && v !== null) out[k] = v;
+  }
+  return out;
+}
+var RETRYABLE_WITHOUT_WHERE = /query_scan_limit|query_too_complex/;
+async function exportFragment(db, ontology, spec) {
+  const keys = naturalKeysOf(ontology);
+  const pageSize = Math.min(1e3, Math.max(1, spec.pageSize ?? 200));
+  const nodes = /* @__PURE__ */ new Map();
+  const edges = /* @__PURE__ */ new Map();
+  const putNode = (node) => {
+    const id = `${node.type}:${node.key}`;
+    const existing = nodes.get(id);
+    if (!existing || Object.keys(node.attrs).length > Object.keys(existing.attrs).length) nodes.set(id, node);
+  };
+  for (const [type, entity] of Object.entries(spec.entities)) {
+    const naturalKey = keys[type];
+    if (!naturalKey) throw new Error(`exportFragment: no ontology entity "${type}"`);
+    const links = planLinks(ontology, type, entity.links ?? []);
+    const limit = entity.limit ?? 1e3;
+    const fromMs = entity.window ? parseDateMs(entity.window.from) : null;
+    let useWhere = entity.window?.indexed === true;
+    let offset = 0;
+    let taken = 0;
+    while (taken < limit) {
+      const opts = {
+        limit: Math.min(pageSize, limit - taken),
+        offset,
+        order: { [naturalKey]: "asc" }
+      };
+      if (useWhere && entity.window) opts.where = { [entity.window.dateAttr]: { $gte: entity.window.from } };
+      const query = {
+        [type]: { $: opts, ...Object.fromEntries(links.map((l) => [l.label, {}])) }
+      };
+      let rows;
+      try {
+        rows = (await db.query(query))[type] ?? [];
+      } catch (err) {
+        if (useWhere && RETRYABLE_WITHOUT_WHERE.test(String(err.message ?? err))) {
+          useWhere = false;
+          offset = 0;
+          taken = 0;
+          continue;
+        }
+        throw err;
+      }
+      for (const row of rows) {
+        const key = row[naturalKey];
+        if (key === void 0 || key === null) continue;
+        if (entity.window && fromMs !== null) {
+          const t = parseDateMs(row[entity.window.dateAttr]);
+          if (t !== null && t < fromMs) continue;
+        }
+        const rootRef = { type, key: String(key) };
+        putNode({ ...rootRef, attrs: pickAttrs(row, entity, entity.links ?? []) });
+        for (const plan of links) {
+          const nestedKeyAttr = keys[plan.counterpart];
+          if (!nestedKeyAttr) throw new Error(`exportFragment: no ontology entity "${plan.counterpart}"`);
+          const raw = row[plan.label];
+          const nestedRows = Array.isArray(raw) ? raw : raw ? [raw] : [];
+          for (const nested of nestedRows) {
+            const nestedKey = nested[nestedKeyAttr];
+            if (nestedKey === void 0 || nestedKey === null) continue;
+            const nestedRef = { type: plan.counterpart, key: String(nestedKey) };
+            putNode({ ...nestedRef, attrs: pickAttrs(nested, {}, []) });
+            const edge = plan.direction === "forward" ? { from: rootRef, to: nestedRef, label: plan.forwardLabel } : { from: nestedRef, to: rootRef, label: plan.forwardLabel };
+            edges.set(`${edge.from.type}:${edge.from.key}|${edge.label}|${edge.to.type}:${edge.to.key}`, edge);
+          }
+        }
+        taken++;
+        if (taken >= limit) break;
+      }
+      if (rows.length < pageSize) break;
+      offset += rows.length;
+    }
+  }
+  const byRef = (a, b) => a.type < b.type ? -1 : a.type > b.type ? 1 : a.key < b.key ? -1 : a.key > b.key ? 1 : 0;
+  return {
+    nodes: [...nodes.values()].sort(byRef),
+    edges: [...edges.values()].sort(
+      (a, b) => byRef(a.from, b.from) || (a.label < b.label ? -1 : a.label > b.label ? 1 : 0) || byRef(a.to, b.to)
+    )
+  };
+}
+
 // src/graph/resolve.ts
 async function searchEntities(db, type, q, limit = 5) {
   if (!q.trim()) return [];
@@ -826,6 +945,7 @@ function allJobs(sources) {
 // src/state/kv.ts
 var SEEN_TTL_S = 120 * 24 * 60 * 60;
 var ENRICHED_TTL_S = 30 * 24 * 60 * 60;
+var TEMPORAL_TTL_S = 120 * 24 * 60 * 60;
 var Store = class {
   constructor(kv) {
     this.kv = kv;
@@ -872,6 +992,22 @@ var Store = class {
   async setConfigSources(list) {
     await this.kv.put("config:sources", JSON.stringify(list));
   }
+  /** Cache the latest temporal report (`temporal:latest`) plus a dated history copy. */
+  async setTemporalReport(report, date = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10)) {
+    const raw = JSON.stringify(report);
+    await this.kv.put("temporal:latest", raw);
+    await this.kv.put(`temporal:${date}`, raw, { expirationTtl: TEMPORAL_TTL_S });
+  }
+  /** The cached latest temporal report, or null when absent/unparseable. */
+  async getTemporalReport() {
+    const raw = await this.kv.get("temporal:latest");
+    if (!raw) return null;
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  }
 };
 
 // src/workflow/helpers.ts