@graphrefly/ts 0.0.0

package/dist/patterns/index.cjs

@@ -0,0 +1,1045 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/patterns/index.ts
+var patterns_exports = {};
+__export(patterns_exports, {
+  admissionFilter3D: () => admissionFilter3D,
+  admissionScored: () => admissionScored,
+  cosineSimilarity: () => cosineSimilarity,
+  filterMemoryFragments: () => filterMemoryFragments,
+  isMemoryFragment: () => isMemoryFragment,
+  knowledgeGraphReducerBundle: () => knowledgeGraphReducerBundle,
+  memoryFragmentMatchesQuery: () => memoryFragmentMatchesQuery,
+  memoryFragmentValidAt: () => memoryFragmentValidAt,
+  memoryRetrievalBundle: () => memoryRetrievalBundle,
+  profileSummary: () => profileSummary,
+  shardByTenant: () => shardByTenant,
+  validateMemoryFragment: () => validateMemoryFragment
+});
+module.exports = __toCommonJS(patterns_exports);
+
+// src/patterns/inspection.ts
+function profileSummary(graph, opts = {}) {
+  const profile = graph.profile();
+  const described = graph.describe();
+  const nodeIds = new Set(described.nodes.map((node) => node.id));
+  for (const id of Object.keys(profile.nodes)) nodeIds.add(id);
+  const byStatus = {};
+  const hotNodes = [];
+  for (const path of [...nodeIds].sort()) {
+    const nodeProfile = profile.nodes[path];
+    if (nodeProfile === void 0) continue;
+    byStatus[nodeProfile.status] = (byStatus[nodeProfile.status] ?? 0) + 1;
+    hotNodes.push({
+      path,
+      invokes: nodeProfile.invokes,
+      totalDurationNs: nodeProfile.totalDurationNs,
+      lastDurationNs: nodeProfile.lastDurationNs,
+      status: nodeProfile.status
+    });
+  }
+  hotNodes.sort((a, b) => b.invokes - a.invokes || a.path.localeCompare(b.path));
+  return {
+    nodeCount: nodeIds.size,
+    totalInvokes: profile.totalInvokes,
+    byStatus,
+    hotNodes: hotNodes.slice(0, opts.limit ?? hotNodes.length)
+  };
+}
+
+// src/patterns/semantic-memory.ts
+function cosineSimilarity(a, b) {
+  const n = Math.max(a.length, b.length);
+  let dot = 0;
+  let na = 0;
+  let nb = 0;
+  for (let i = 0; i < n; i += 1) {
+    const av = a[i] ?? 0;
+    const bv = b[i] ?? 0;
+    dot += av * bv;
+    na += av * av;
+    nb += bv * bv;
+  }
+  if (na === 0 || nb === 0) return 0;
+  const score = dot / Math.sqrt(na * nb);
+  return Number.isFinite(score) ? score : 0;
+}
+function memoryFragmentValidAt(fragment, asOf) {
+  if (asOf === void 0) return fragment.validTo === void 0 && fragment.validFrom === void 0;
+  if (fragment.validFrom !== void 0 && fragment.validFrom > asOf) return false;
+  if (fragment.validTo !== void 0 && fragment.validTo <= asOf) return false;
+  return true;
+}
+function memoryFragmentMatchesQuery(fragment, query = {}) {
+  if (!memoryFragmentValidAt(fragment, query.asOf)) return false;
+  if (query.minConfidence !== void 0 && fragment.confidence < query.minConfidence) return false;
+  if (query.tags && query.tags.length > 0 && !query.tags.some((tag) => fragment.tags.includes(tag))) {
+    return false;
+  }
+  return true;
+}
+function filterMemoryFragments(fragments, query = {}) {
+  const results = [...fragments].filter((fragment) => memoryFragmentMatchesQuery(fragment, query));
+  results.sort((a, b) => b.confidence - a.confidence || compareBigIntDesc(a.tNs, b.tNs));
+  return query.limit === void 0 ? results : results.slice(0, Math.max(0, query.limit));
+}
+function validateMemoryFragment(value) {
+  const errors = [];
+  if (typeof value !== "object" || value === null) {
+    return { ok: false, errors: ["fragment must be an object"] };
+  }
+  const fragment = value;
+  if (typeof fragment.id !== "string" || fragment.id.length === 0) {
+    errors.push("id must be a non-empty string");
+  }
+  if (!Object.hasOwn(fragment, "payload")) {
+    errors.push("payload must be present");
+  }
+  if (typeof fragment.tNs !== "bigint") {
+    errors.push("tNs must be a bigint");
+  }
+  const confidence = fragment.confidence;
+  if (!Number.isFinite(confidence) || confidence === void 0 || confidence < 0 || confidence > 1) {
+    errors.push("confidence must be a finite number in [0, 1]");
+  }
+  if (!isDenseArrayOf(fragment.tags, (tag) => typeof tag === "string")) {
+    errors.push("tags must be a readonly string array");
+  }
+  if (!isDenseArrayOf(fragment.sources, (source) => typeof source === "string")) {
+    errors.push("sources must be a readonly string array");
+  }
+  if (fragment.validFrom !== void 0 && typeof fragment.validFrom !== "bigint") {
+    errors.push("validFrom must be a bigint when present");
+  }
+  if (fragment.validTo !== void 0 && typeof fragment.validTo !== "bigint") {
+    errors.push("validTo must be a bigint when present");
+  }
+  if (typeof fragment.validFrom === "bigint" && typeof fragment.validTo === "bigint" && fragment.validFrom >= fragment.validTo) {
+    errors.push("validFrom must be earlier than validTo");
+  }
+  if (fragment.embedding !== void 0 && !isDenseArrayOf(
+    fragment.embedding,
+    (component) => Number.isFinite(component)
+  )) {
+    errors.push("embedding must be a finite number array when present");
+  }
+  if (fragment.parentFragmentId !== void 0 && typeof fragment.parentFragmentId !== "string") {
+    errors.push("parentFragmentId must be a string when present");
+  }
+  if (fragment.provenance !== void 0 && typeof fragment.provenance !== "string") {
+    errors.push("provenance must be a string when present");
+  }
+  return { ok: errors.length === 0, errors };
+}
+function isMemoryFragment(value) {
+  return validateMemoryFragment(value).ok;
+}
+function admissionScored(opts) {
+  const thresholds = opts.thresholds ?? {};
+  return (raw) => {
+    const scores = opts.scoreFn(raw);
+    for (const dim of Object.keys(thresholds)) {
+      const min = thresholds[dim];
+      if (min === void 0) continue;
+      const score = scores[dim];
+      const safe = Number.isFinite(score) ? score : Number.NEGATIVE_INFINITY;
+      if (safe < min) return false;
+    }
+    return true;
+  };
+}
+function admissionFilter3D(opts) {
+  return (raw) => {
+    const scores = opts.scoreFn(raw);
+    if (!scoreAtLeast(scores.persistence, opts.persistenceThreshold ?? 0.3)) return false;
+    if (!scoreAtLeast(scores.personalValue, opts.personalValueThreshold ?? 0.3)) return false;
+    if (!opts.requireStructured) return true;
+    return scoreAtLeast(scores.structure, Number.MIN_VALUE);
+  };
+}
+function shardByTenant(tenantOf, opts = {}) {
+  if (opts.tenants && opts.tenants.length > 0) {
+    const tenants = [...new Set(opts.tenants)];
+    const index = new Map(tenants.map((tenant, i) => [tenant, i]));
+    const overflow = tenants.length;
+    return {
+      shardBy: (fragment) => index.get(tenantOf(fragment)) ?? overflow,
+      shardCount: tenants.length + 1
+    };
+  }
+  const configuredShardCount = opts.shardCount ?? 4;
+  const shardCount = Number.isSafeInteger(configuredShardCount) ? Math.max(1, configuredShardCount) : 4;
+  return { shardBy: (fragment) => tenantOf(fragment), shardCount };
+}
+function compareBigIntDesc(a, b) {
+  if (a === b) return 0;
+  return a > b ? -1 : 1;
+}
+function isDenseArrayOf(value, predicate) {
+  if (!Array.isArray(value)) return false;
+  for (let i = 0; i < value.length; i += 1) {
+    if (!Object.hasOwn(value, i) || !predicate(value[i])) return false;
+  }
+  return true;
+}
+function scoreAtLeast(score, min) {
+  return Number.isFinite(score) && score >= min;
+}
+
+// src/protocol/messages.ts
+var SENTINEL = void 0;
+
+// src/ctx/types.ts
+var CTX_DEP_CACHE = /* @__PURE__ */ Symbol("graphrefly.ctx.depCache");
+function depWaves(ctx, depIndex) {
+  return ctx.waveData[depIndex] ?? [];
+}
+function depBatch(ctx, depIndex) {
+  const waves = depWaves(ctx, depIndex);
+  if (waves.length === 0) return null;
+  const flattened = waves.flat().filter((v) => v !== SENTINEL);
+  return flattened.length === 0 ? [] : flattened;
+}
+function depLatest(ctx, depIndex) {
+  return ctx[CTX_DEP_CACHE]?.latest[depIndex];
+}
+
+// src/patterns/semantic-memory-graph.ts
+function memoryRetrievalBundle(graph, opts) {
+  const name = opts.name ?? "memoryRetrieval";
+  const { fragments, query } = opts;
+  const snapshot = graph.node(
+    [fragments, query],
+    (ctx) => {
+      const state = ctx.state.get() ?? { evaluation: 0 };
+      state.evaluation += 1;
+      const rawFragments = depLatest(ctx, 0);
+      const rawQuery = depLatest(ctx, 1);
+      const queryValidation = validateMemoryRetrievalQuery(rawQuery);
+      const currentQuery = queryValidation.query;
+      const valid = [];
+      const seenIds = /* @__PURE__ */ new Set();
+      const errors = [...queryValidation.errors];
+      if (!Array.isArray(rawFragments)) {
+        errors.push({
+          code: "invalid-fragments-input",
+          message: "memoryRetrievalBundle: fragments input must be an array",
+          fragment: rawFragments
+        });
+      } else {
+        const length = safeArrayLength(rawFragments);
+        if (length === void 0) {
+          errors.push({
+            code: "invalid-fragments-input",
+            message: "memoryRetrievalBundle: fragments input length could not be read",
+            fragment: rawFragments
+          });
+        }
+        for (let i = 0; i < (length ?? 0); i += 1) {
+          const result = validateAndSnapshotFragment(rawFragments, i);
+          if (result.error !== void 0) {
+            errors.push(result.error);
+            continue;
+          }
+          const fragment = result.fragment;
+          if (seenIds.has(fragment.id)) {
+            errors.push({
+              code: "duplicate-fragment-id",
+              message: "memoryRetrievalBundle: duplicate fragment id",
+              index: i,
+              fragment,
+              validationErrors: [`duplicate fragment id '${fragment.id}'`]
+            });
+            continue;
+          }
+          seenIds.add(fragment.id);
+          valid.push(fragment);
+        }
+      }
+      const ranked = errors.some((error) => !isRecoverableFragmentError(error)) ? [] : rankFragments(valid, currentQuery);
+      const cursor = Object.freeze({
+        evaluation: state.evaluation,
+        validFragments: valid.length,
+        invalidFragments: errors.filter(
+          (error) => error.code === "invalid-fragment" || error.code === "duplicate-fragment-id"
+        ).length,
+        resultCount: ranked.length
+      });
+      ctx.state.set(state);
+      const answer = Object.freeze({
+        query: currentQuery,
+        results: Object.freeze(ranked)
+      });
+      const status = Object.freeze({
+        state: statusState(errors, ranked.length),
+        query: currentQuery,
+        cursor
+      });
+      const indexed = Object.freeze({
+        ids: Object.freeze(valid.map((fragment) => fragment.id)),
+        byId: indexById(valid),
+        cursor
+      });
+      const errorFacts = Object.freeze(
+        errors.map(
+          (error) => Object.freeze({
+            ...error,
+            ...error.validationErrors === void 0 ? {} : { validationErrors: Object.freeze([...error.validationErrors]) },
+            cursor
+          })
+        )
+      );
+      ctx.down([
+        [
+          "DATA",
+          Object.freeze({
+            fragments: Object.freeze([...valid]),
+            indexed,
+            ranked: answer,
+            status,
+            errors: errorFacts,
+            cursor
+          })
+        ]
+      ]);
+    },
+    {
+      name: `${name}/snapshot`,
+      factory: "memoryRetrievalSnapshot",
+      completeWhenDepsComplete: false,
+      errorWhenDepsError: false
+    }
+  );
+  return {
+    input: { fragments, query },
+    snapshot,
+    fragments: retrievalProjection(
+      graph,
+      snapshot,
+      `${name}/fragments`,
+      "memoryRetrievalFragments",
+      (fact) => fact.fragments
+    ),
+    indexed: retrievalProjection(
+      graph,
+      snapshot,
+      `${name}/indexed`,
+      "memoryRetrievalIndexed",
+      (fact) => fact.indexed
+    ),
+    ranked: retrievalProjection(
+      graph,
+      snapshot,
+      `${name}/ranked`,
+      "memoryRetrievalRanked",
+      (fact) => fact.ranked
+    ),
+    status: retrievalProjection(
+      graph,
+      snapshot,
+      `${name}/status`,
+      "memoryRetrievalStatus",
+      (fact) => fact.status
+    ),
+    errors: retrievalProjection(
+      graph,
+      snapshot,
+      `${name}/errors`,
+      "memoryRetrievalErrors",
+      (fact) => fact.errors
+    ),
+    cursor: retrievalProjection(
+      graph,
+      snapshot,
+      `${name}/cursor`,
+      "memoryRetrievalCursor",
+      (fact) => fact.cursor
+    )
+  };
+}
+function knowledgeGraphReducerBundle(graph, opts) {
+  const name = opts.name ?? "knowledgeGraph";
+  const deps = opts.policy === void 0 ? [opts.assertions] : [opts.assertions, opts.policy];
+  const snapshot = graph.node(
+    deps,
+    (ctx) => {
+      const state = ctx.state.get() ?? { evaluation: 0 };
+      state.evaluation += 1;
+      const policy = validateKnowledgeGraphPolicy(
+        opts.policy === void 0 ? void 0 : depLatest(ctx, 1)
+      );
+      const reduced = reduceKnowledgeAssertions(depLatest(ctx, 0), policy.policy);
+      const pendingErrors = [...policy.errors, ...reduced.errors];
+      const cursor = Object.freeze({
+        evaluation: state.evaluation,
+        validAssertions: reduced.assertions.length,
+        invalidAssertions: reduced.invalidAssertions,
+        entityCount: reduced.entities.length,
+        relationCount: reduced.relations.length,
+        predicateCount: reduced.topics.length
+      });
+      const errors = Object.freeze(
+        pendingErrors.map(
+          (error) => Object.freeze({
+            ...error,
+            ...error.validationErrors === void 0 ? {} : { validationErrors: Object.freeze([...error.validationErrors]) },
+            cursor
+          })
+        )
+      );
+      const status = Object.freeze({
+        state: reduced.assertions.length === 0 && errors.length === 0 ? "empty" : errors.length === 0 ? "ready" : reduced.assertions.length > 0 ? "partial" : "error",
+        cursor
+      });
+      ctx.state.set(state);
+      ctx.down([
+        [
+          "DATA",
+          Object.freeze({
+            assertions: Object.freeze(reduced.assertions),
+            entities: Object.freeze(reduced.entities),
+            relations: Object.freeze(reduced.relations),
+            topics: Object.freeze(reduced.topics),
+            index: reduced.index,
+            status,
+            errors,
+            cursor
+          })
+        ]
+      ]);
+    },
+    {
+      name: `${name}/snapshot`,
+      factory: "knowledgeGraphReducerSnapshot",
+      completeWhenDepsComplete: false,
+      errorWhenDepsError: false
+    }
+  );
+  return {
+    input: {
+      assertions: opts.assertions,
+      ...opts.policy === void 0 ? {} : { policy: opts.policy }
+    },
+    snapshot,
+    assertions: kgProjection(
+      graph,
+      snapshot,
+      `${name}/assertions`,
+      "knowledgeGraphAssertions",
+      (fact) => fact.assertions
+    ),
+    entities: kgProjection(
+      graph,
+      snapshot,
+      `${name}/entities`,
+      "knowledgeGraphEntities",
+      (fact) => fact.entities
+    ),
+    relations: kgProjection(
+      graph,
+      snapshot,
+      `${name}/relations`,
+      "knowledgeGraphRelations",
+      (fact) => fact.relations
+    ),
+    topics: kgProjection(
+      graph,
+      snapshot,
+      `${name}/topics`,
+      "knowledgeGraphTopics",
+      (fact) => fact.topics
+    ),
+    index: kgProjection(
+      graph,
+      snapshot,
+      `${name}/index`,
+      "knowledgeGraphIndex",
+      (fact) => fact.index
+    ),
+    status: kgProjection(
+      graph,
+      snapshot,
+      `${name}/status`,
+      "knowledgeGraphStatus",
+      (fact) => fact.status
+    ),
+    errors: kgProjection(
+      graph,
+      snapshot,
+      `${name}/errors`,
+      "knowledgeGraphErrors",
+      (fact) => fact.errors
+    ),
+    cursor: kgProjection(
+      graph,
+      snapshot,
+      `${name}/cursor`,
+      "knowledgeGraphCursor",
+      (fact) => fact.cursor
+    )
+  };
+}
+function retrievalProjection(graph, snapshot, name, factory, select) {
+  return graph.node(
+    [snapshot],
+    (ctx) => {
+      for (const raw of depBatch(ctx, 0) ?? []) {
+        const fact = raw;
+        const selected = select(fact);
+        if (selected !== void 0) ctx.down([["DATA", selected]]);
+      }
+    },
+    {
+      name,
+      factory,
+      completeWhenDepsComplete: false,
+      errorWhenDepsError: false
+    }
+  );
+}
+function kgProjection(graph, snapshot, name, factory, select) {
+  return graph.node(
+    [snapshot],
+    (ctx) => {
+      for (const raw of depBatch(ctx, 0) ?? []) {
+        ctx.down([["DATA", select(raw)]]);
+      }
+    },
+    {
+      name,
+      factory,
+      completeWhenDepsComplete: false,
+      errorWhenDepsError: false
+    }
+  );
+}
+function validateKnowledgeGraphPolicy(value) {
+  if (value === void 0) return { policy: void 0, errors: [] };
+  if (!isPlainObject(value)) {
+    return {
+      errors: [
+        {
+          code: "invalid-policy",
+          message: "knowledgeGraphReducerBundle: policy must be an object",
+          assertion: value
+        }
+      ]
+    };
+  }
+  const errors = [];
+  const policy = value;
+  if (policy.allowedPredicates !== void 0 && !isDenseArrayOf2(policy.allowedPredicates, (item) => typeof item === "string")) {
+    errors.push("allowedPredicates must be a readonly string array");
+  }
+  if (policy.requireEntityTypes !== void 0 && typeof policy.requireEntityTypes !== "boolean") {
+    errors.push("requireEntityTypes must be a boolean when present");
+  }
+  if (errors.length > 0) {
+    return {
+      errors: [
+        {
+          code: "invalid-policy",
+          message: "knowledgeGraphReducerBundle: policy is invalid",
+          assertion: value,
+          validationErrors: Object.freeze(errors)
+        }
+      ]
+    };
+  }
+  return {
+    policy: Object.freeze({
+      ...policy.allowedPredicates === void 0 ? {} : { allowedPredicates: Object.freeze([...policy.allowedPredicates]) },
+      ...policy.requireEntityTypes === void 0 ? {} : { requireEntityTypes: policy.requireEntityTypes }
+    }),
+    errors: []
+  };
+}
+function reduceKnowledgeAssertions(value, policy) {
+  const assertions = [];
+  const errors = [];
+  const seenAssertions = /* @__PURE__ */ new Set();
+  if (!Array.isArray(value)) {
+    return {
+      assertions,
+      entities: [],
+      relations: [],
+      topics: [],
+      index: emptyKnowledgeGraphIndex(),
+      errors: [
+        {
+          code: "invalid-assertions-input",
+          message: "knowledgeGraphReducerBundle: assertions input must be an array",
+          assertion: value
+        }
+      ],
+      invalidAssertions: 0
+    };
+  }
+  const length = safeArrayLength(value);
+  if (length === void 0) {
+    return {
+      assertions,
+      entities: [],
+      relations: [],
+      topics: [],
+      index: emptyKnowledgeGraphIndex(),
+      errors: [
+        {
+          code: "invalid-assertions-input",
+          message: "knowledgeGraphReducerBundle: assertions input length could not be read",
+          assertion: value
+        }
+      ],
+      invalidAssertions: 0
+    };
+  }
+  for (let i = 0; i < length; i += 1) {
+    const result = validateKnowledgeAssertion(value[i], i, policy);
+    if (result.error !== void 0) {
+      errors.push(result.error);
+      continue;
+    }
+    const assertion = result.assertion;
+    if (seenAssertions.has(assertion.id)) {
+      errors.push({
+        code: "duplicate-assertion-id",
+        message: "knowledgeGraphReducerBundle: duplicate assertion id",
+        index: i,
+        assertionId: assertion.id,
+        assertion,
+        validationErrors: Object.freeze([`duplicate assertion id '${assertion.id}'`])
+      });
+      continue;
+    }
+    seenAssertions.add(assertion.id);
+    assertions.push(assertion);
+  }
+  const materialized = materializeKnowledgeGraph(assertions);
+  return {
+    assertions: Object.freeze(assertions),
+    ...materialized,
+    errors,
+    invalidAssertions: errors.filter((error) => error.code !== "invalid-policy").length
+  };
+}
+function validateKnowledgeAssertion(value, index, policy) {
+  if (!isPlainObject(value)) {
+    return invalidKnowledgeAssertion(index, value, ["assertion must be an object"]);
+  }
+  const raw = value;
+  const errors = [];
+  if (!isNonEmptyString(raw.id)) errors.push("id must be a non-empty string");
+  if (!isKnowledgeSubject(raw.subject)) errors.push("subject.id must be a non-empty string");
+  if (!isNonEmptyString(raw.predicate)) errors.push("predicate must be a non-empty string");
+  if (!isKnowledgeObject(raw.object)) errors.push("object shape is invalid");
+  if (raw.confidence !== void 0 && (!Number.isFinite(raw.confidence) || raw.confidence < 0 || raw.confidence > 1)) {
+    errors.push("confidence must be a finite number in [0, 1] when present");
+  }
+  if (raw.sources !== void 0 && !isDenseArrayOf2(raw.sources, isNonEmptyString)) {
+    errors.push("sources must be a readonly non-empty string array when present");
+  }
+  if (policy?.allowedPredicates !== void 0 && !policy.allowedPredicates.includes(raw.predicate ?? "")) {
+    errors.push(`predicate '${String(raw.predicate)}' is not allowed by policy`);
+  }
+  if (policy?.requireEntityTypes === true) {
+    if (isKnowledgeSubject(raw.subject) && raw.subject.type === void 0) {
+      errors.push("subject.type is required by policy");
+    }
+    if (isKnowledgeObject(raw.object) && raw.object.kind === "entity" && raw.object.type === void 0) {
+      errors.push("object.type is required by policy for entity objects");
+    }
+  }
+  if (errors.length > 0) {
+    return invalidKnowledgeAssertion(index, value, errors, raw.id);
+  }
+  return {
+    assertion: Object.freeze({
+      id: raw.id,
+      ...raw.recordId === void 0 ? {} : { recordId: raw.recordId },
+      ...raw.fragmentId === void 0 ? {} : { fragmentId: raw.fragmentId },
+      subject: snapshotSubject(raw.subject),
+      predicate: raw.predicate,
+      object: snapshotObject(raw.object),
+      ...raw.confidence === void 0 ? {} : { confidence: raw.confidence },
+      sources: Object.freeze([...raw.sources ?? []]),
+      ...raw.provenance === void 0 ? {} : { provenance: raw.provenance }
+    })
+  };
+}
+function invalidKnowledgeAssertion(index, assertion, validationErrors, assertionId) {
+  return {
+    error: {
+      code: "invalid-assertion",
+      message: "knowledgeGraphReducerBundle: assertion is invalid",
+      index,
+      assertionId: typeof assertionId === "string" ? assertionId : void 0,
+      assertion,
+      validationErrors: Object.freeze([...validationErrors])
+    }
+  };
+}
+function materializeKnowledgeGraph(assertions) {
+  const entityAssertions = /* @__PURE__ */ new Map();
+  const topics = /* @__PURE__ */ new Map();
+  const relations = [];
+  for (const assertion of assertions) {
+    const subject = touchEntity(entityAssertions, assertion.subject.id, assertion.subject.type);
+    subject.assertionIds.add(assertion.id);
+    subject.subjectAssertionIds.add(assertion.id);
+    let topic = topics.get(assertion.predicate);
+    if (topic === void 0) {
+      topic = { assertionIds: /* @__PURE__ */ new Set(), entityIds: /* @__PURE__ */ new Set() };
+      topics.set(assertion.predicate, topic);
+    }
+    topic.assertionIds.add(assertion.id);
+    topic.entityIds.add(assertion.subject.id);
+    if (assertion.object.kind === "entity") {
+      const object = touchEntity(entityAssertions, assertion.object.id, assertion.object.type);
+      object.assertionIds.add(assertion.id);
+      object.objectAssertionIds.add(assertion.id);
+      topic.entityIds.add(assertion.object.id);
+    }
+    relations.push(
+      Object.freeze({
+        assertionId: assertion.id,
+        subject: assertion.subject,
+        predicate: assertion.predicate,
+        object: assertion.object,
+        ...assertion.confidence === void 0 ? {} : { confidence: assertion.confidence },
+        sources: Object.freeze([...assertion.sources ?? []]),
+        ...assertion.provenance === void 0 ? {} : { provenance: assertion.provenance }
+      })
+    );
+  }
+  const entities = [...entityAssertions.entries()].map(
+    ([id, entity]) => Object.freeze({
+      id,
+      ...entity.type === void 0 ? {} : { type: entity.type },
+      assertionIds: freezeSortedSet(entity.assertionIds),
+      subjectAssertionIds: freezeSortedSet(entity.subjectAssertionIds),
+      objectAssertionIds: freezeSortedSet(entity.objectAssertionIds)
+    })
+  );
+  entities.sort((a, b) => compareString(a.id, b.id));
+  relations.sort((a, b) => compareString(a.assertionId, b.assertionId));
+  const topicFacts = [...topics.entries()].map(
+    ([predicate, topic]) => Object.freeze({
+      predicate,
+      assertionIds: freezeSortedSet(topic.assertionIds),
+      entityIds: freezeSortedSet(topic.entityIds)
+    })
+  );
+  topicFacts.sort((a, b) => compareString(a.predicate, b.predicate));
+  const index = Object.freeze({
+    assertionIds: Object.freeze(assertions.map((assertion) => assertion.id).sort(compareString)),
+    entityIds: Object.freeze(entities.map((entity) => entity.id)),
+    relationIds: Object.freeze(relations.map((relation) => relation.assertionId)),
+    predicates: Object.freeze(topicFacts.map((topic) => topic.predicate))
+  });
+  return {
+    entities: Object.freeze(entities),
+    relations: Object.freeze(relations),
+    topics: Object.freeze(topicFacts),
+    index
+  };
+}
+function touchEntity(entities, id, type) {
+  let entity = entities.get(id);
+  if (entity === void 0) {
+    entity = {
+      ...type === void 0 ? {} : { type },
+      assertionIds: /* @__PURE__ */ new Set(),
+      subjectAssertionIds: /* @__PURE__ */ new Set(),
+      objectAssertionIds: /* @__PURE__ */ new Set()
+    };
+    entities.set(id, entity);
+  } else if (entity.type === void 0 && type !== void 0) {
+    entity.type = type;
+  }
+  return entity;
+}
+function emptyKnowledgeGraphIndex() {
+  return Object.freeze({
+    assertionIds: Object.freeze([]),
+    entityIds: Object.freeze([]),
+    relationIds: Object.freeze([]),
+    predicates: Object.freeze([])
+  });
+}
+function snapshotSubject(subject) {
+  return Object.freeze({
+    id: subject.id,
+    ...subject.type === void 0 ? {} : { type: subject.type }
+  });
+}
+function snapshotObject(object) {
+  return object.kind === "entity" ? Object.freeze({
+    kind: "entity",
+    id: object.id,
+    ...object.type === void 0 ? {} : { type: object.type }
+  }) : Object.freeze({
+    kind: "value",
+    value: object.value,
+    ...object.valueType === void 0 ? {} : { valueType: object.valueType }
+  });
+}
+function isKnowledgeSubject(value) {
+  return isPlainObject(value) && isNonEmptyString(value.id) && (value.type === void 0 || isNonEmptyString(value.type));
+}
+function isKnowledgeObject(value) {
+  if (!isPlainObject(value)) return false;
+  if (value.kind === "entity") {
+    return isNonEmptyString(value.id) && (value.type === void 0 || isNonEmptyString(value.type));
+  }
+  if (value.kind !== "value") return false;
+  return isStrictJsonValue(value.value) && (value.valueType === void 0 || isNonEmptyString(value.valueType));
+}
+function isStrictJsonValue(value) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+  if (typeof value === "number") return Number.isFinite(value);
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i += 1) {
+      if (!Object.hasOwn(value, i) || !isStrictJsonValue(value[i])) return false;
+    }
+    return true;
+  }
+  if (!isPlainObject(value)) return false;
+  for (const key of Object.keys(value)) {
+    if (!isStrictJsonValue(value[key])) return false;
+  }
+  return Object.getOwnPropertySymbols(value).length === 0;
+}
+function freezeSortedSet(value) {
+  return Object.freeze([...value].sort(compareString));
+}
+function rankFragments(fragments, query) {
+  if (query.vector === void 0) return filterMemoryFragments(fragments, query);
+  const ranked = fragments.filter((fragment) => memoryFragmentMatchesQuery(fragment, query));
+  ranked.sort((a, b) => {
+    const vectorDelta = vectorScore(b, query) - vectorScore(a, query);
+    if (vectorDelta !== 0) return vectorDelta;
+    const confidenceDelta = b.confidence - a.confidence;
+    if (confidenceDelta !== 0) return confidenceDelta;
+    return compareBigIntDesc2(a.tNs, b.tNs);
+  });
+  return query.limit === void 0 ? ranked : ranked.slice(0, Math.max(0, query.limit));
+}
+function vectorScore(fragment, query) {
+  if (query.vector === void 0 || fragment.embedding === void 0) return 0;
+  return cosineSimilarity(query.vector, fragment.embedding);
+}
+function statusState(errors, resultCount) {
+  if (errors.some((error) => !isRecoverableFragmentError(error))) return "error";
+  if (errors.length > 0) return "partial";
+  return resultCount > 0 ? "ready" : "empty";
+}
+function isRecoverableFragmentError(error) {
+  return error.code === "invalid-fragment" || error.code === "duplicate-fragment-id";
+}
+function indexById(fragments) {
+  const byId = /* @__PURE__ */ Object.create(null);
+  for (const fragment of fragments) byId[fragment.id] = fragment;
+  return Object.freeze(byId);
+}
+function isFiniteVector(value) {
+  if (!Array.isArray(value)) return false;
+  for (let i = 0; i < value.length; i += 1) {
+    if (!Object.hasOwn(value, i) || !Number.isFinite(value[i])) return false;
+  }
+  return true;
+}
+function validateMemoryRetrievalQuery(value) {
+  try {
+    return validateMemoryRetrievalQueryInner(value);
+  } catch (error) {
+    return {
+      ok: false,
+      query: {},
+      errors: [
+        {
+          code: "invalid-query",
+          message: `memoryRetrievalBundle: query access failed: ${errorMessage(error)}`,
+          fragment: value
+        }
+      ]
+    };
+  }
+}
+function validateMemoryRetrievalQueryInner(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return invalidQuery(value, "memoryRetrievalBundle: query must be an object");
+  }
+  const query = value;
+  const errors = [];
+  if (query.tags !== void 0 && !isDenseArrayOf2(query.tags, (tag) => typeof tag === "string")) {
+    errors.push({
+      code: "invalid-query",
+      message: "memoryRetrievalBundle: query.tags must be a readonly string array",
+      fragment: value,
+      validationErrors: ["tags must be a readonly string array"]
+    });
+  }
+  if (query.asOf !== void 0 && typeof query.asOf !== "bigint") {
+    errors.push({
+      code: "invalid-query",
+      message: "memoryRetrievalBundle: query.asOf must be a bigint",
+      fragment: value,
+      validationErrors: ["asOf must be a bigint when present"]
+    });
+  }
+  if (query.minConfidence !== void 0 && (!Number.isFinite(query.minConfidence) || query.minConfidence < 0 || query.minConfidence > 1)) {
+    errors.push({
+      code: "invalid-query",
+      message: "memoryRetrievalBundle: query.minConfidence must be a finite number in [0, 1]",
+      fragment: value,
+      validationErrors: ["minConfidence must be a finite number in [0, 1]"]
+    });
+  }
+  if (query.limit !== void 0 && (!Number.isSafeInteger(query.limit) || query.limit < 0)) {
+    errors.push({
+      code: "invalid-query",
+      message: "memoryRetrievalBundle: query.limit must be a non-negative safe integer",
+      fragment: value,
+      validationErrors: ["limit must be a non-negative safe integer"]
+    });
+  }
+  if (query.vector !== void 0 && !isFiniteVector(query.vector)) {
+    errors.push({
+      code: "invalid-query-vector",
+      message: "memoryRetrievalBundle: query.vector must be a finite number array",
+      fragment: value,
+      validationErrors: ["vector must be a finite number array"]
+    });
+  }
+  if (errors.length > 0) return { ok: false, query: {}, errors };
+  return { ok: true, query: snapshotQuery(query), errors };
+}
+function invalidQuery(value, message) {
+  return {
+    ok: false,
+    query: {},
+    errors: [
+      {
+        code: "invalid-query",
+        message,
+        fragment: value
+      }
+    ]
+  };
+}
+function snapshotQuery(query) {
+  return Object.freeze({
+    ...query.tags === void 0 ? {} : { tags: Object.freeze([...query.tags]) },
+    ...query.asOf === void 0 ? {} : { asOf: query.asOf },
+    ...query.minConfidence === void 0 ? {} : { minConfidence: query.minConfidence },
+    ...query.limit === void 0 ? {} : { limit: query.limit },
+    ...query.vector === void 0 ? {} : { vector: Object.freeze([...query.vector]) }
+  });
+}
+function safeArrayLength(value) {
+  try {
+    return value.length;
+  } catch {
+    return void 0;
+  }
+}
+function validateAndSnapshotFragment(rawFragments, index) {
+  let raw;
+  try {
+    raw = rawFragments[index];
+    const validation = validateMemoryFragment(raw);
+    if (!validation.ok) {
+      return {
+        error: {
+          code: "invalid-fragment",
+          message: "memoryRetrievalBundle: invalid memory fragment",
+          index,
+          fragment: raw,
+          validationErrors: Object.freeze([...validation.errors])
+        }
+      };
+    }
+    return { fragment: snapshotFragment(raw) };
+  } catch (error) {
+    return {
+      error: {
+        code: "invalid-fragment",
+        message: `memoryRetrievalBundle: fragment access failed: ${errorMessage(error)}`,
+        index,
+        fragment: raw,
+        validationErrors: Object.freeze(["fragment access failed"])
+      }
+    };
+  }
+}
+function snapshotFragment(fragment) {
+  return Object.freeze({
+    id: fragment.id,
+    payload: fragment.payload,
+    tNs: fragment.tNs,
+    ...fragment.validFrom === void 0 ? {} : { validFrom: fragment.validFrom },
+    ...fragment.validTo === void 0 ? {} : { validTo: fragment.validTo },
+    confidence: fragment.confidence,
+    tags: Object.freeze([...fragment.tags]),
+    sources: Object.freeze([...fragment.sources]),
+    ...fragment.embedding === void 0 ? {} : { embedding: Object.freeze([...fragment.embedding]) },
+    ...fragment.parentFragmentId === void 0 ? {} : { parentFragmentId: fragment.parentFragmentId },
+    ...fragment.provenance === void 0 ? {} : { provenance: fragment.provenance }
+  });
+}
+function isDenseArrayOf2(value, predicate) {
+  if (!Array.isArray(value)) return false;
+  for (let i = 0; i < value.length; i += 1) {
+    if (!Object.hasOwn(value, i) || !predicate(value[i])) return false;
+  }
+  return true;
+}
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.length > 0;
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function compareString(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+function compareBigIntDesc2(a, b) {
+  if (a === b) return 0;
+  return a > b ? -1 : 1;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  admissionFilter3D,
+  admissionScored,
+  cosineSimilarity,
+  filterMemoryFragments,
+  isMemoryFragment,
+  knowledgeGraphReducerBundle,
+  memoryFragmentMatchesQuery,
+  memoryFragmentValidAt,
+  memoryRetrievalBundle,
+  profileSummary,
+  shardByTenant,
+  validateMemoryFragment
+});
+//# sourceMappingURL=index.cjs.map