@graphrefly/ts 0.0.0

package/dist/semantic-memory-graph-CxyXLms3.d.ts

@@ -0,0 +1,356 @@
+import { d as Graph } from './graph-DfdF9zy4.js';
+import { N as Node } from './types-h12mNYbq.js';
+import { b as StrictJsonValue } from './codec-BB7p8fJc.js';
+
+/**
+ * Passive semantic-memory vocabulary and deterministic helpers.
+ *
+ * D158 splits semantic memory into horizontal patterns and vertical solutions.
+ * This module intentionally owns no graph nodes, storage restore, timers,
+ * subscriptions, vector indexes, knowledge graphs, or agentic runtime.
+ */
+
+/** Stable identity for a semantic-memory fact. */
+type FactId = string;
+/** Shard partition key used by passive sharding helpers. */
+type ShardKey = string | number;
+/**
+ * A single semantic-memory fact. Pattern convention only: this is not a
+ * protocol message, storage record owner, restore contract, or graph runtime.
+ */
+interface MemoryFragment<T = unknown> {
+    readonly id: FactId;
+    readonly payload: T;
+    /** Transaction time, typically monotonic nanoseconds. */
+    readonly tNs: bigint;
+    /** Valid-time start. Undefined means unbounded past. */
+    readonly validFrom?: bigint;
+    /** Valid-time end. Undefined means currently valid. */
+    readonly validTo?: bigint;
+    /** Confidence score in the closed interval [0, 1]. */
+    readonly confidence: number;
+    readonly tags: readonly string[];
+    /** Fact ids this fragment derives from or depends on. */
+    readonly sources: readonly FactId[];
+    readonly embedding?: readonly number[];
+    readonly parentFragmentId?: FactId;
+    readonly provenance?: string;
+}
+/** Columnar passive store vocabulary for callers that keep memory facts outside GraphReFly. */
+interface FactStore<T = unknown> {
+    readonly byId: ReadonlyMap<FactId, MemoryFragment<T>>;
+}
+/** Read-only projection passed to scoring policies; it exposes no mutation surface. */
+interface StoreReadHandle<T = unknown> {
+    get(id: FactId): MemoryFragment<T> | undefined;
+    has(id: FactId): boolean;
+    readonly size: number;
+    values(): IterableIterator<MemoryFragment<T>>;
+}
+type ScoringPolicy<T = unknown> = (fragment: MemoryFragment<T>, store: StoreReadHandle<T>) => number;
+type DecayPolicy = (confidence: number, ageNs: bigint) => number;
+type AdmissionFilter<T = unknown> = (fragment: MemoryFragment<T>) => boolean;
+/** Outcome signal for policy learning. This is an application fact, not a protocol event. */
+interface OutcomeSignal {
+    readonly factId: FactId;
+    readonly reward: number;
+}
+/** Passive structured query over semantic-memory facts. */
+interface MemoryQuery {
+    readonly tags?: readonly string[];
+    readonly asOf?: bigint;
+    readonly minConfidence?: number;
+    readonly limit?: number;
+}
+interface MemoryAnswer<T = unknown> {
+    readonly query: MemoryQuery;
+    readonly results: readonly MemoryFragment<T>[];
+}
+type KnowledgeAssertionStrictJsonValue = StrictJsonValue;
+/** Passive KG endpoint vocabulary. Entity ids are DATA keys, not graph node ids. */
+interface KnowledgeAssertionSubject {
+    readonly id: FactId;
+    readonly type?: string;
+}
+/** Passive KG object/value vocabulary. */
+type KnowledgeAssertionObject = {
+    readonly kind: "entity";
+    readonly id: FactId;
+    readonly type?: string;
+} | {
+    readonly kind: "value";
+    readonly value: KnowledgeAssertionStrictJsonValue;
+    readonly valueType?: string;
+};
+/** Passive KG assertion fact consumed by lower semantic-memory graph patterns. */
+interface KnowledgeAssertion {
+    readonly id: FactId;
+    readonly recordId?: FactId;
+    readonly fragmentId?: FactId;
+    readonly subject: KnowledgeAssertionSubject;
+    readonly predicate: string;
+    readonly object: KnowledgeAssertionObject;
+    readonly confidence?: number;
+    readonly sources?: readonly FactId[];
+    readonly provenance?: string;
+}
+/** Entry vocabulary for ranked collection-like memory views. */
+interface CollectionEntry<T = unknown> {
+    readonly id: string;
+    readonly value: T;
+    readonly createdAtNs: bigint;
+    readonly lastAccessNs: bigint;
+    readonly baseScore: number;
+}
+type RankedCollectionEntry<T = unknown> = CollectionEntry<T> & {
+    readonly score: number;
+};
+type CollectionScoreFn<T = unknown> = (value: T) => number;
+/** Query shape shared by passive retrieval/ranking helpers. */
+interface RetrievalQuery {
+    readonly text?: string;
+    readonly vector?: readonly number[];
+    readonly entityIds?: readonly string[];
+    readonly context?: readonly string[];
+}
+interface VectorSearchResult<TMeta = unknown> {
+    readonly id: string;
+    readonly score: number;
+    readonly meta?: TMeta;
+}
+interface RetrievalEntry<TMem = unknown> {
+    readonly key: string;
+    readonly value: TMem;
+    readonly score: number;
+    readonly sources: ReadonlyArray<"vector" | "graph" | "store">;
+    readonly context?: readonly string[];
+}
+interface RetrievalTrace<TMem = unknown> {
+    readonly vectorCandidates: ReadonlyArray<VectorSearchResult<TMem>>;
+    readonly graphExpanded: ReadonlyArray<string>;
+    readonly ranked: ReadonlyArray<RetrievalEntry<TMem>>;
+    readonly packed: ReadonlyArray<RetrievalEntry<TMem>>;
+}
+/** Generic per-dimension thresholds. Any configured dimension below threshold is rejected. */
+type AdmissionThresholds<Dims extends string> = Partial<Record<Dims, number>>;
+interface AdmissionScoredOptions<Dims extends string, TRaw = unknown> {
+    readonly scoreFn: (raw: TRaw) => Readonly<Record<Dims, number>>;
+    readonly thresholds?: AdmissionThresholds<Dims>;
+}
+interface AdmissionScores {
+    readonly persistence: number;
+    readonly structure: number;
+    readonly personalValue: number;
+}
+interface AdmissionScore3DOptions {
+    readonly scoreFn: (raw: unknown) => AdmissionScores;
+    readonly persistenceThreshold?: number;
+    readonly personalValueThreshold?: number;
+    readonly requireStructured?: boolean;
+}
+interface ShardByTenantOptions {
+    readonly tenants?: readonly string[];
+    readonly shardCount?: number;
+}
+interface ShardByTenantConfig<T = unknown> {
+    readonly shardBy: (fragment: MemoryFragment<T>) => ShardKey;
+    readonly shardCount: number;
+}
+interface MemoryFragmentValidation {
+    readonly ok: boolean;
+    readonly errors: readonly string[];
+}
+/** Cosine similarity over zero-padded vectors. Non-finite results normalize to 0. */
+declare function cosineSimilarity(a: readonly number[], b: readonly number[]): number;
+/**
+ * Returns true when a fragment is valid at `asOf`.
+ *
+ * Omitted `asOf` has no clock to compare against, so it admits only fragments
+ * that are live and not valid-time delayed.
+ */
+declare function memoryFragmentValidAt(fragment: MemoryFragment, asOf?: bigint): boolean;
+/** Pure structured-query predicate over a single fragment. */
+declare function memoryFragmentMatchesQuery(fragment: MemoryFragment, query?: MemoryQuery): boolean;
+/** Filter and rank fragments by confidence desc, then transaction time desc. */
+declare function filterMemoryFragments<T>(fragments: Iterable<MemoryFragment<T>>, query?: MemoryQuery): readonly MemoryFragment<T>[];
+/** Validate the passive MemoryFragment shape without throwing. */
+declare function validateMemoryFragment(value: unknown): MemoryFragmentValidation;
+declare function isMemoryFragment(value: unknown): value is MemoryFragment;
+/**
+ * Generic N-dimension admission filter. Missing or non-finite thresholded scores reject.
+ */
+declare function admissionScored<Dims extends string, TRaw = unknown>(opts: AdmissionScoredOptions<Dims, TRaw>): (raw: TRaw) => boolean;
+/** Three-axis admission sugar for persistence / structure / personal-value scoring. */
+declare function admissionFilter3D(opts: AdmissionScore3DOptions): (raw: unknown) => boolean;
+/** Build a passive `{ shardBy, shardCount }` pair for tenant-isolated sharding. */
+declare function shardByTenant<T>(tenantOf: (fragment: MemoryFragment<T>) => string, opts?: ShardByTenantOptions): ShardByTenantConfig<T>;
+
+/**
+ * Graph-visible semantic-memory retrieval patterns.
+ *
+ * D158 allows horizontal semantic-memory patterns when they are ordinary graph
+ * nodes with declared deps and graph-visible facts. This file intentionally
+ * owns no storage restore/hydration, scheduler, hidden subscription, vector DB,
+ * retention loop, consolidation loop, Graph subclass, or protocol behavior.
+ */
+
+/** Query shape for the first graph-visible retrieval bundle. */
+interface MemoryRetrievalQuery extends MemoryQuery {
+    /** Optional dense embedding used only for deterministic in-memory ranking. */
+    readonly vector?: readonly number[];
+}
+interface MemoryRetrievalCursor {
+    readonly evaluation: number;
+    readonly validFragments: number;
+    readonly invalidFragments: number;
+    readonly resultCount: number;
+}
+type MemoryRetrievalStatusState = "ready" | "empty" | "partial" | "error";
+interface MemoryRetrievalStatus {
+    readonly state: MemoryRetrievalStatusState;
+    readonly query: MemoryRetrievalQuery;
+    readonly cursor: MemoryRetrievalCursor;
+}
+interface MemoryRetrievalIndex<T = unknown> {
+    readonly ids: readonly FactId[];
+    readonly byId: Readonly<Record<FactId, MemoryFragment<T>>>;
+    readonly cursor: MemoryRetrievalCursor;
+}
+type MemoryRetrievalErrorCode = "duplicate-fragment-id" | "invalid-fragments-input" | "invalid-fragment" | "invalid-query" | "invalid-query-vector";
+interface MemoryRetrievalError {
+    readonly code: MemoryRetrievalErrorCode;
+    readonly message: string;
+    readonly index?: number;
+    readonly fragment?: unknown;
+    readonly validationErrors?: readonly string[];
+    readonly cursor: MemoryRetrievalCursor;
+}
+interface MemoryRetrievalSnapshot<T = unknown> {
+    readonly fragments: readonly MemoryFragment<T>[];
+    readonly indexed: MemoryRetrievalIndex<T>;
+    readonly ranked: MemoryAnswer<T>;
+    readonly status: MemoryRetrievalStatus;
+    readonly errors: readonly MemoryRetrievalError[];
+    readonly cursor: MemoryRetrievalCursor;
+}
+type MemoryRetrievalFact<T = unknown> = MemoryRetrievalSnapshot<T>;
+interface KnowledgeGraphEntity {
+    readonly id: FactId;
+    readonly type?: string;
+    readonly assertionIds: readonly FactId[];
+    readonly subjectAssertionIds: readonly FactId[];
+    readonly objectAssertionIds: readonly FactId[];
+}
+interface KnowledgeGraphRelation {
+    readonly assertionId: FactId;
+    readonly subject: KnowledgeAssertionSubject;
+    readonly predicate: string;
+    readonly object: KnowledgeAssertionObject;
+    readonly confidence?: number;
+    readonly sources: readonly FactId[];
+    readonly provenance?: string;
+}
+interface KnowledgeGraphTopic {
+    readonly predicate: string;
+    readonly assertionIds: readonly FactId[];
+    readonly entityIds: readonly FactId[];
+}
+interface KnowledgeGraphIndex {
+    readonly assertionIds: readonly FactId[];
+    readonly entityIds: readonly FactId[];
+    readonly relationIds: readonly FactId[];
+    readonly predicates: readonly string[];
+}
+interface KnowledgeGraphPolicy {
+    readonly allowedPredicates?: readonly string[];
+    readonly requireEntityTypes?: boolean;
+}
+interface KnowledgeGraphCursor {
+    readonly evaluation: number;
+    readonly validAssertions: number;
+    readonly invalidAssertions: number;
+    readonly entityCount: number;
+    readonly relationCount: number;
+    readonly predicateCount: number;
+}
+type KnowledgeGraphStatusState = "ready" | "empty" | "partial" | "error";
+interface KnowledgeGraphStatus {
+    readonly state: KnowledgeGraphStatusState;
+    readonly cursor: KnowledgeGraphCursor;
+}
+type KnowledgeGraphErrorCode = "invalid-assertions-input" | "invalid-assertion" | "duplicate-assertion-id" | "invalid-policy" | "policy-conflict";
+interface KnowledgeGraphError {
+    readonly code: KnowledgeGraphErrorCode;
+    readonly message: string;
+    readonly index?: number;
+    readonly assertionId?: FactId;
+    readonly assertion?: unknown;
+    readonly validationErrors?: readonly string[];
+    readonly cursor: KnowledgeGraphCursor;
+}
+interface KnowledgeGraphSnapshot {
+    readonly assertions: readonly KnowledgeAssertion[];
+    readonly entities: readonly KnowledgeGraphEntity[];
+    readonly relations: readonly KnowledgeGraphRelation[];
+    readonly topics: readonly KnowledgeGraphTopic[];
+    readonly index: KnowledgeGraphIndex;
+    readonly status: KnowledgeGraphStatus;
+    readonly errors: readonly KnowledgeGraphError[];
+    readonly cursor: KnowledgeGraphCursor;
+}
+interface KnowledgeGraphReducerBundle {
+    readonly input: {
+        readonly assertions: Node<readonly unknown[]>;
+        readonly policy?: Node<KnowledgeGraphPolicy>;
+    };
+    readonly snapshot: Node<KnowledgeGraphSnapshot>;
+    readonly assertions: Node<readonly KnowledgeAssertion[]>;
+    readonly entities: Node<readonly KnowledgeGraphEntity[]>;
+    readonly relations: Node<readonly KnowledgeGraphRelation[]>;
+    readonly topics: Node<readonly KnowledgeGraphTopic[]>;
+    readonly index: Node<KnowledgeGraphIndex>;
+    readonly status: Node<KnowledgeGraphStatus>;
+    readonly errors: Node<readonly KnowledgeGraphError[]>;
+    readonly cursor: Node<KnowledgeGraphCursor>;
+}
+interface KnowledgeGraphReducerBundleOptions {
+    readonly name?: string;
+    readonly assertions: Node<readonly unknown[]>;
+    readonly policy?: Node<KnowledgeGraphPolicy>;
+}
+interface MemoryRetrievalBundle<T = unknown> {
+    readonly input: {
+        readonly fragments: Node<readonly unknown[]>;
+        readonly query: Node<MemoryRetrievalQuery>;
+    };
+    readonly snapshot: Node<MemoryRetrievalSnapshot<T>>;
+    readonly fragments: Node<readonly MemoryFragment<T>[]>;
+    readonly indexed: Node<MemoryRetrievalIndex<T>>;
+    readonly ranked: Node<MemoryAnswer<T>>;
+    readonly status: Node<MemoryRetrievalStatus>;
+    readonly errors: Node<readonly MemoryRetrievalError[]>;
+    readonly cursor: Node<MemoryRetrievalCursor>;
+}
+interface MemoryRetrievalBundleOptions {
+    readonly name?: string;
+    readonly fragments: Node<readonly unknown[]>;
+    readonly query: Node<MemoryRetrievalQuery>;
+}
+/**
+ * Build a graph-visible memory retrieval bundle from explicit fragment/query deps.
+ *
+ * Invalid fragments and ranking status are emitted as ordinary DATA facts. The
+ * bundle never owns storage restore or hidden mutation; callers that need
+ * persistence compose D161 collection/storage sidecars outside this pattern.
+ */
+declare function memoryRetrievalBundle<T = unknown>(graph: Graph, opts: MemoryRetrievalBundleOptions): MemoryRetrievalBundle<T>;
+/**
+ * D170 lower semantic-memory KG materializer.
+ *
+ * Assertion, entity, relation, and topic ids remain DATA keys. The bundle has
+ * static describe-visible topology and owns no storage, LLM extraction,
+ * scheduler, agent runtime, or dynamic graph node lifecycle.
+ */
+declare function knowledgeGraphReducerBundle(graph: Graph, opts: KnowledgeGraphReducerBundleOptions): KnowledgeGraphReducerBundle;
+
+export { type VectorSearchResult as $, type AdmissionFilter as A, type MemoryRetrievalBundle as B, type CollectionEntry as C, type DecayPolicy as D, type MemoryRetrievalBundleOptions as E, type FactId as F, type MemoryRetrievalCursor as G, type MemoryRetrievalError as H, type MemoryRetrievalErrorCode as I, type MemoryRetrievalFact as J, type KnowledgeAssertion as K, type MemoryRetrievalIndex as L, type MemoryAnswer as M, type MemoryRetrievalQuery as N, type MemoryRetrievalSnapshot as O, type MemoryRetrievalStatus as P, type MemoryRetrievalStatusState as Q, type OutcomeSignal as R, type RankedCollectionEntry as S, type RetrievalEntry as T, type RetrievalQuery as U, type RetrievalTrace as V, type ScoringPolicy as W, type ShardByTenantConfig as X, type ShardByTenantOptions as Y, type ShardKey as Z, type StoreReadHandle as _, type KnowledgeAssertionObject as a, admissionFilter3D as a0, admissionScored as a1, cosineSimilarity as a2, filterMemoryFragments as a3, isMemoryFragment as a4, memoryFragmentMatchesQuery as a5, memoryFragmentValidAt as a6, memoryRetrievalBundle as a7, shardByTenant as a8, validateMemoryFragment as a9, type KnowledgeAssertionStrictJsonValue as b, type KnowledgeAssertionSubject as c, type KnowledgeGraphCursor as d, type KnowledgeGraphEntity as e, type KnowledgeGraphError as f, type KnowledgeGraphErrorCode as g, type KnowledgeGraphIndex as h, type KnowledgeGraphPolicy as i, type KnowledgeGraphReducerBundle as j, type KnowledgeGraphReducerBundleOptions as k, type KnowledgeGraphRelation as l, type KnowledgeGraphSnapshot as m, type KnowledgeGraphStatus as n, type KnowledgeGraphStatusState as o, type KnowledgeGraphTopic as p, knowledgeGraphReducerBundle as q, type AdmissionScore3DOptions as r, type AdmissionScoredOptions as s, type AdmissionScores as t, type AdmissionThresholds as u, type CollectionScoreFn as v, type FactStore as w, type MemoryFragment as x, type MemoryFragmentValidation as y, type MemoryQuery as z };