@fgv/ts-agent-memory 5.1.0-37 → 5.1.0-39

package/dist/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.58.7"
+      "packageVersion": "7.58.9"
     }
   ]
 }

package/etc/ts-agent-memory.api.md

@@ -4,6 +4,7 @@
 
 ```ts
 
+import { AiAssist } from '@fgv/ts-extras';
 import { Brand } from '@fgv/ts-utils';
 import { Converter } from '@fgv/ts-utils';
 import { FileTree } from '@fgv/ts-json-base';
@@ -22,6 +23,16 @@ export type AdmissionDecision = {
     readonly evict: ReadonlyArray<MemoryId>;
 };
 
+// @public
+export class AsOfRetriever implements IMemoryRetriever {
+    get capabilities(): IMemoryRetrieverCapabilities;
+    static create(index: IMemoryIndex): Result<AsOfRetriever>;
+    retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
+}
+
+// @public
+export function assertNoCycles(existing: ReadonlyArray<ICycleGuardEdge>, proposed: ReadonlyArray<ICycleGuardEdge>): Result<true>;
+
 // @public
 export function assertPortableFilenameStem(stem: string): Result<string>;
 
@@ -35,6 +46,12 @@ export class BodyConverterRegistry implements IBodyConverterRegistry {
     registerSchema<T>(kind: Kind, schema: JsonSchema.ISchemaValidator<T>): void;
 }
 
+// @public
+export function buildCycleKey(edge: ICycleGuardEdge): Result<string>;
+
+// @public
+export const CONTRADICTS_LINK_TYPE: LinkType;
+
 // @public
 export const Convert: {
     readonly memoryId: Converter<MemoryId>;
@@ -45,12 +62,34 @@ export const Convert: {
     readonly linkType: Converter<LinkType>;
 };
 
+// @public
+export function createMemoryTools(params: ICreateMemoryToolsParams): ReadonlyArray<AiAssist.IAiClientTool>;
+
+// @public
+export class CurrentValidRetriever implements IMemoryRetriever {
+    get capabilities(): IMemoryRetrieverCapabilities;
+    static create(index: IMemoryIndex): Result<CurrentValidRetriever>;
+    retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
+}
+
+// @public
+export type CycleGuardMode = 'reject' | 'off';
+
 // @public
 export type DedupScope = 'content' | 'entity';
 
 // @public
 export const DEFAULT_DEDUP_SCOPE: DedupScope;
 
+// @public
+export const DEFAULT_MEMORY_TOOLS: ReadonlyArray<MemoryToolName>;
+
+// @public
+export const DEFAULT_SIMILARITY_THRESHOLD: number;
+
+// @public
+export const DEFAULT_SIMILARITY_TOP_K: number;
+
 // @public
 export function defaultMemoryScopeEncoding(scope: MemoryScopeKey): Result<string>;
 
@@ -79,6 +118,16 @@ export class FileTreeMemoryStore implements IMemoryStore {
 // @public
 export function guardRetrieverCapabilities(query: IMemoryQuery, capabilities: IMemoryRetrieverCapabilities): Result<true>;
 
+// @public
+export class HistoryRetriever implements IMemoryRetriever {
+    get capabilities(): IMemoryRetrieverCapabilities;
+    static create(index: IMemoryIndex): Result<HistoryRetriever>;
+    retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
+}
+
+// @public
+export const HOST_INGEST_PROVENANCE_SOURCE: string;
+
 // @public
 export class HybridRetriever implements IMemoryRetriever {
     get capabilities(): IMemoryRetrieverCapabilities;
@@ -95,6 +144,40 @@ export interface IBodyConverterRegistry {
     registerSchema<T>(kind: Kind, schema: JsonSchema.ISchemaValidator<T>): void;
 }
 
+// @public
+export interface ICandidateEdge {
+    readonly edge: IEdge;
+    readonly source: MemoryId;
+}
+
+// @public
+export interface ICandidateRecord {
+    readonly body: unknown;
+    readonly envelope: Omit<IMemoryEnvelope, StoreStampedEnvelopeField>;
+}
+
+// @public
+export interface ICreateMemoryToolsParams {
+    readonly codecs?: ReadonlyMap<Kind, IIdentityCodec>;
+    readonly defaultCodec?: IIdentityCodec;
+    readonly handleFor?: (record: IMemoryRecord<unknown>) => string;
+    readonly kinds?: ReadonlyArray<Kind>;
+    readonly registry: IBodyConverterRegistry;
+    readonly retriever: IMemoryRetriever;
+    readonly store: IMemoryStore;
+    readonly tools?: ReadonlyArray<MemoryToolName>;
+}
+
+// @public
+export interface ICycleGuardEdge {
+    // (undocumented)
+    readonly source: MemoryId;
+    // (undocumented)
+    readonly target: MemoryId;
+    // (undocumented)
+    readonly type: LinkType;
+}
+
 // @public
 export interface IEdge {
     readonly confidence?: number;
@@ -105,6 +188,23 @@ export interface IEdge {
     readonly valid_at?: number;
 }
 
+// @public
+export interface IEntityResolutionCandidate {
+    readonly id: MemoryId;
+    readonly record: IMemoryRecord<unknown>;
+    readonly score: number;
+}
+
+// @public
+export interface IEntityResolver {
+    resolve(candidate: ICandidateRecord, similar: ReadonlyArray<IEntityResolutionCandidate>): Promise<Result<ResolutionVerdict>>;
+}
+
+// @public
+export interface IFactExtractor {
+    extract(item: IIngestItem, classification: IMemoryClassification): Promise<Result<ReadonlyArray<ICandidateRecord>>>;
+}
+
 // @public
 export interface IFileTreeMemoryStoreCreateParams {
     readonly clock?: () => number;
@@ -140,12 +240,50 @@ export interface IIndexedMemoryRecord {
     readonly scope: MemoryScopeKey;
 }
 
+// @public
+export interface IIngestedRecordResult {
+    readonly candidate: ICandidateRecord;
+    readonly disposition: IngestDisposition;
+    readonly edges: ReadonlyArray<ICandidateEdge>;
+    readonly id: MemoryId;
+    readonly interlock?: 'temporal-versioned';
+    readonly record?: IMemoryRecord<unknown>;
+    readonly resolution: ResolutionVerdict;
+}
+
+// @public
+export interface IIngestItem {
+    readonly content: unknown;
+    readonly id: string;
+    readonly metadata?: Record<string, unknown>;
+    readonly sourceId?: MemoryId;
+}
+
+// @public
+export interface IIngestItemResult {
+    readonly item: IIngestItem;
+    readonly records: ReadonlyArray<IIngestedRecordResult>;
+}
+
 // @public
 export interface IMemoryCapCullPolicyParams {
     readonly maxRecords?: number;
     readonly mutableFields: ReadonlyArray<string>;
 }
 
+// @public
+export interface IMemoryClassification {
+    readonly [key: string]: unknown;
+    readonly confidence?: number;
+    readonly kind: Kind;
+    readonly tags?: ReadonlyArray<Tag>;
+}
+
+// @public
+export interface IMemoryClassifier {
+    classify(item: IIngestItem): Promise<Result<IMemoryClassification>>;
+}
+
 // @public
 export interface IMemoryEnvelope {
     readonly contentHash: string;
@@ -179,6 +317,30 @@ export interface IMemoryIndex {
     rebuild(entries: ReadonlyArray<IIndexedMemoryRecord>): Result<number>;
 }
 
+// @public
+export interface IMemoryIngestOrchestrator {
+    ingestBatch(items: ReadonlyArray<IIngestItem>): Promise<Result<ReadonlyArray<IIngestItemResult>>>;
+    ingestItem(item: IIngestItem): Promise<Result<IIngestItemResult>>;
+}
+
+// @public
+export interface IMemoryIngestOrchestratorCreateParams {
+    readonly classifier: IMemoryClassifier;
+    readonly codecs?: ReadonlyMap<Kind, IIdentityCodec>;
+    readonly cycleGuard?: CycleGuardMode;
+    readonly defaultCodec?: IIdentityCodec;
+    readonly embed?: MemoryEmbedder;
+    readonly entityResolver?: IEntityResolver;
+    readonly extractor: IFactExtractor;
+    readonly logger?: Logging.ILogger;
+    readonly registry: IBodyConverterRegistry;
+    readonly relationExtractor: IRelationExtractor;
+    readonly similarityThreshold?: number;
+    readonly similarityTopK?: number;
+    readonly store: IMemoryStore;
+    readonly vectorIndex?: IVectorIndex;
+}
+
 // @public
 export interface IMemoryObservationQuery {
     readonly kind?: Kind;
@@ -272,6 +434,23 @@ export interface IMemoryStoreListFilter {
     readonly tag?: Tag;
 }
 
+// @public
+export interface IMemoryToolResultItem {
+    readonly body: unknown;
+    readonly entityId: EntityId;
+    readonly handle: string;
+    readonly kind: Kind;
+    readonly tags: ReadonlyArray<string>;
+}
+
+// @public
+export interface IMemoryWriteResult {
+    readonly entityId: EntityId;
+    readonly id: MemoryId;
+    readonly kind: Kind;
+    readonly outcome: MemoryWriteOutcome;
+}
+
 // @public
 export interface IMergeStrategy {
     merge(resultSets: ReadonlyArray<ReadonlyArray<IMemoryRecord<unknown>>>): Result<ReadonlyArray<IMemoryRecord<unknown>>>;
@@ -280,6 +459,9 @@ export interface IMergeStrategy {
 // @public
 export function indexedRecordMatchesQuery(entry: IIndexedMemoryRecord, query: IMemoryQuery): boolean;
 
+// @public
+export type IngestDisposition = 'written' | 'deduped' | 'merged';
+
 // @public
 export class InMemoryCosineIndex implements IVectorIndex {
     add(id: MemoryId, vector: Float32Array): Promise<Result<string>>;
@@ -300,6 +482,23 @@ export interface IProvenance {
     readonly source: ProvenanceSource;
 }
 
+// @public
+export interface IRelationCandidate {
+    readonly candidate: ICandidateRecord;
+    readonly id: MemoryId;
+}
+
+// @public
+export interface IRelationContext {
+    readonly candidates: ReadonlyArray<IRelationCandidate>;
+    readonly item: IIngestItem;
+}
+
+// @public
+export interface IRelationExtractor {
+    relate(context: IRelationContext): Promise<Result<ReadonlyArray<ICandidateEdge>>>;
+}
+
 // @public
 export interface ISemanticBackend {
     readonly embedQuery: QueryEmbedder;
@@ -312,12 +511,36 @@ export interface ISemanticRetrieverCreateParams {
     readonly index: IMemoryIndex;
 }
 
+// @public
+export function isTemporalIdentityCodec(codec: IIdentityCodec): codec is ITemporalIdentityCodec;
+
+// @public
+export function isTemporalRecord(record: IMemoryRecord<unknown>): boolean;
+
+// @public
+export function isVersionCurrent(record: IMemoryRecord<unknown>): boolean;
+
+// @public
+export function isVersionValidAt(record: IMemoryRecord<unknown>, asOf: number): boolean;
+
 // @public
 export interface ITemporalBlock {
     readonly invalid_at?: number | null;
     readonly valid_at?: number;
 }
 
+// @public
+export interface ITemporalIdentityCodec extends IIdentityCodec {
+    decodeVersion(scope: MemoryScopeKey, stem: string): Result<ITemporalVersionAddress>;
+    encodeVersion(entityId: EntityId, seq: number): Result<string>;
+}
+
+// @public
+export interface ITemporalVersionAddress {
+    readonly entityId: EntityId;
+    readonly seq: number;
+}
+
 // @public
 export interface IVectorIndex {
     add(id: MemoryId, vector: Float32Array): Promise<Result<string>>;
@@ -419,6 +642,13 @@ export class MemoryIndex implements IMemoryIndex {
 // @public
 export type MemoryIndexPatchOp = 'put' | 'delete';
 
+// @public
+export class MemoryIngestOrchestrator implements IMemoryIngestOrchestrator {
+    static create(params: IMemoryIngestOrchestratorCreateParams): Result<MemoryIngestOrchestrator>;
+    ingestBatch(items: ReadonlyArray<IIngestItem>): Promise<Result<ReadonlyArray<IIngestItemResult>>>;
+    ingestItem(item: IIngestItem): Promise<Result<IIngestItemResult>>;
+}
+
 // @public
 export type MemoryObservationOutcome = 'success' | 'failure';
 
@@ -438,6 +668,12 @@ export class MemoryObservationStore implements IMemoryObserver {
 // @public
 export type MemoryScopeKey = Brand<string, 'MemoryScopeKey'>;
 
+// @public
+export type MemoryToolName = 'memory_write' | 'memory_read' | 'memory_search' | 'memory_context' | 'memory_delete';
+
+// @public
+export type MemoryWriteOutcome = 'written' | 'deduped';
+
 // @public
 export class MtmIdentityCodec implements IIdentityCodec {
     decode(scope: MemoryScopeKey, encodedStem: string): Result<EntityId>;
@@ -472,6 +708,20 @@ export class RecencyRetriever implements IMemoryRetriever {
     retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
 }
 
+// @public
+export type ResolutionVerdict = {
+    readonly verdict: 'new';
+} | {
+    readonly verdict: 'duplicate-of';
+    readonly target: MemoryId;
+} | {
+    readonly verdict: 'supersede';
+    readonly target: MemoryId;
+} | {
+    readonly verdict: 'merge-into';
+    readonly target: MemoryId;
+};
+
 // @public
 export class ScoreUnionMergeStrategy implements IMergeStrategy {
     static create(): Result<ScoreUnionMergeStrategy>;
@@ -481,6 +731,12 @@ export class ScoreUnionMergeStrategy implements IMergeStrategy {
 // @public
 export function selectByQuery(entries: ReadonlyArray<IIndexedMemoryRecord>, query: IMemoryQuery): IMemoryRecord<unknown>[];
 
+// @public
+export function selectCurrentVersion(versions: ReadonlyArray<IMemoryRecord<unknown>>): IMemoryRecord<unknown> | undefined;
+
+// @public
+export function selectVersionAsOf(versions: ReadonlyArray<IMemoryRecord<unknown>>, asOf: number): IMemoryRecord<unknown> | undefined;
+
 // @public
 export const SEMANTIC_UNWIRED_MESSAGE: string;
 
@@ -497,6 +753,9 @@ export function serializeMemoryFile(envelope: IMemoryEnvelope, body: string): Re
 // @public
 export function splitFrontmatter(raw: string): Result<IMemoryFileParts>;
 
+// @public
+export type StoreStampedEnvelopeField = 'id' | 'seq' | 'contentHash' | 'created' | 'updated';
+
 // @public
 export class StructuredFilterRetriever implements IMemoryRetriever {
     get capabilities(): IMemoryRetrieverCapabilities;
@@ -514,12 +773,37 @@ export class TagRetriever implements IMemoryRetriever {
     retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
 }
 
+// @public
+export const TEMPORAL_CAPABILITIES: IMemoryRetrieverCapabilities;
+
 // @public
 export const temporalConverter: Converter<ITemporalBlock>;
 
+// @public
+export class TemporalIdentityCodec implements ITemporalIdentityCodec {
+    readonly baseScope: string;
+    static create(baseScope: string): Result<TemporalIdentityCodec>;
+    decode(scope: MemoryScopeKey, encodedStem: string): Result<EntityId>;
+    decodeVersion(scope: MemoryScopeKey, stem: string): Result<ITemporalVersionAddress>;
+    encode(entityId: EntityId): Result<IIdentityCodecResult>;
+    encodeVersion(entityId: EntityId, seq: number): Result<string>;
+    static readonly entitiesSegment: string;
+    verifyRoundTrip(scope: MemoryScopeKey, stem: string): Result<true>;
+    static readonly versionInfix: string;
+}
+
 // @public
 export function temporalUnwiredMessage(kind?: Kind): string;
 
+// @public
+export class TemporalVersionedPolicy implements IWritePolicy {
+    admit(__incoming: IMemoryRecord<unknown>, __existing: ReadonlyArray<IMemoryRecord<unknown>>): Result<AdmissionDecision>;
+    applyUpdate(existing: IMemoryRecord<unknown>, patch: Record<string, unknown>): Result<IMemoryRecord<unknown>>;
+    static create(): Result<TemporalVersionedPolicy>;
+    readonly dedupScope: DedupScope;
+    readonly mutableFields: ReadonlyArray<string>;
+}
+
 // (No @packageDocumentation comment for this package)
 
 ```

package/lib/index.d.ts

@@ -5,4 +5,6 @@ export * from './packlets/index';
 export * from './packlets/retrieve';
 export * from './packlets/observe';
 export * from './packlets/vector';
+export * from './packlets/tools';
+export * from './packlets/ingest';
 //# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC"}

package/lib/index.js

@@ -25,4 +25,6 @@ __exportStar(require("./packlets/index"), exports);
 __exportStar(require("./packlets/retrieve"), exports);
 __exportStar(require("./packlets/observe"), exports);
 __exportStar(require("./packlets/vector"), exports);
+__exportStar(require("./packlets/tools"), exports);
+__exportStar(require("./packlets/ingest"), exports);
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;;;;;;;;;;;;AAEH,mDAAiC;AACjC,wDAAsC;AACtC,mDAAiC;AACjC,mDAAiC;AACjC,sDAAoC;AACpC,qDAAmC;AACnC,oDAAkC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nexport * from './packlets/types';\nexport * from './packlets/converters';\nexport * from './packlets/store';\nexport * from './packlets/index';\nexport * from './packlets/retrieve';\nexport * from './packlets/observe';\nexport * from './packlets/vector';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;;;;;;;;;;;;AAEH,mDAAiC;AACjC,wDAAsC;AACtC,mDAAiC;AACjC,mDAAiC;AACjC,sDAAoC;AACpC,qDAAmC;AACnC,oDAAkC;AAClC,mDAAiC;AACjC,oDAAkC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nexport * from './packlets/types';\nexport * from './packlets/converters';\nexport * from './packlets/store';\nexport * from './packlets/index';\nexport * from './packlets/retrieve';\nexport * from './packlets/observe';\nexport * from './packlets/vector';\nexport * from './packlets/tools';\nexport * from './packlets/ingest';\n"]}

package/lib/packlets/ingest/cycleGuard.d.ts

@@ -0,0 +1,41 @@
+import { Result } from '@fgv/ts-utils';
+import { LinkType, MemoryId } from '../types';
+/**
+ * A directed edge in the link graph the cycle guard reasons over: `source` links
+ * to `target` under relation `type`.
+ * @public
+ */
+export interface ICycleGuardEdge {
+    readonly source: MemoryId;
+    readonly target: MemoryId;
+    readonly type: LinkType;
+}
+/**
+ * Build the design's `buildCycleKey` — a deterministic, canonical (RFC-8785,
+ * via `Crc32Normalizer` from `@fgv/ts-utils`) identity for a directed edge. Used
+ * to de-duplicate proposed edges so a repeated `(source, target, type)` proposal
+ * contributes a single graph edge (and never spuriously "re-closes" a cycle).
+ * @public
+ */
+export declare function buildCycleKey(edge: ICycleGuardEdge): Result<string>;
+/**
+ * Write-time cycle guard. Given the graph's EXISTING directed edges plus a set of
+ * PROPOSED edges, verify that adding the proposed edges keeps the union graph a
+ * DAG. Fails loudly, naming the first proposed edge that would close a directed
+ * cycle.
+ *
+ * @remarks
+ * Distinct from the read-time BFS in `LinkTraversalRetriever` (which tolerates
+ * cycles via a visited-set): this is a WRITE-time admission check. Cycle
+ * detection is DFS reachability — a proposed `source -> target` edge closes a
+ * cycle iff `target` already reaches `source` in the graph built so far. Proposed
+ * edges are folded in one at a time (in order), so an intra-batch cycle
+ * (`A->B`, `B->A` both proposed) is caught as well as a batch-vs-existing cycle.
+ *
+ * See the design note §4: this enforces GLOBAL directed-acyclicity over all link
+ * types (conservative — a mutual associative pair is rejected). Callers that need
+ * mutual links disable the guard.
+ * @public
+ */
+export declare function assertNoCycles(existing: ReadonlyArray<ICycleGuardEdge>, proposed: ReadonlyArray<ICycleGuardEdge>): Result<true>;
+//# sourceMappingURL=cycleGuard.d.ts.map

package/lib/packlets/ingest/cycleGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cycleGuard.d.ts","sourceRoot":"","sources":["../../../src/packlets/ingest/cycleGuard.ts"],"names":[],"mappings":"AAKA,OAAO,EAAQ,MAAM,EAA6B,MAAM,eAAe,CAAC;AACxE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAE9C;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,CAAC,CAMnE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,aAAa,CAAC,eAAe,CAAC,EACxC,QAAQ,EAAE,aAAa,CAAC,eAAe,CAAC,GACvC,MAAM,CAAC,IAAI,CAAC,CAiCd"}

package/lib/packlets/ingest/cycleGuard.js

@@ -0,0 +1,115 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCycleKey = buildCycleKey;
+exports.assertNoCycles = assertNoCycles;
+const ts_utils_1 = require("@fgv/ts-utils");
+/**
+ * Build the design's `buildCycleKey` — a deterministic, canonical (RFC-8785,
+ * via `Crc32Normalizer` from `@fgv/ts-utils`) identity for a directed edge. Used
+ * to de-duplicate proposed edges so a repeated `(source, target, type)` proposal
+ * contributes a single graph edge (and never spuriously "re-closes" a cycle).
+ * @public
+ */
+function buildCycleKey(edge) {
+    return new ts_utils_1.Hash.Crc32Normalizer().computeHash({
+        source: edge.source,
+        target: edge.target,
+        type: edge.type
+    });
+}
+/**
+ * Write-time cycle guard. Given the graph's EXISTING directed edges plus a set of
+ * PROPOSED edges, verify that adding the proposed edges keeps the union graph a
+ * DAG. Fails loudly, naming the first proposed edge that would close a directed
+ * cycle.
+ *
+ * @remarks
+ * Distinct from the read-time BFS in `LinkTraversalRetriever` (which tolerates
+ * cycles via a visited-set): this is a WRITE-time admission check. Cycle
+ * detection is DFS reachability — a proposed `source -> target` edge closes a
+ * cycle iff `target` already reaches `source` in the graph built so far. Proposed
+ * edges are folded in one at a time (in order), so an intra-batch cycle
+ * (`A->B`, `B->A` both proposed) is caught as well as a batch-vs-existing cycle.
+ *
+ * See the design note §4: this enforces GLOBAL directed-acyclicity over all link
+ * types (conservative — a mutual associative pair is rejected). Callers that need
+ * mutual links disable the guard.
+ * @public
+ */
+function assertNoCycles(existing, proposed) {
+    // Canonically key every edge up front (the only fallible step); the graph
+    // building + cycle detection below is then pure.
+    return keyEdges(existing).onSuccess((existingKeyed) => keyEdges(proposed).onSuccess((proposedKeyed) => {
+        // Adjacency map, de-duplicated by canonical edge key so a repeated edge is
+        // one arc. Seed with the existing edges, then fold in each proposed edge,
+        // checking reachability BEFORE inserting it.
+        const adjacency = new Map();
+        const seenKeys = new Set();
+        for (const keyed of existingKeyed) {
+            addEdge(adjacency, seenKeys, keyed);
+        }
+        for (const keyed of proposedKeyed) {
+            const edge = keyed.edge;
+            // A self-loop is the degenerate one-node cycle.
+            if (edge.source === edge.target) {
+                return (0, ts_utils_1.fail)(`ingest cycle guard: edge '${edge.source}' -${edge.type}-> '${edge.target}' is a self-loop`);
+            }
+            // Reachability: does `target` already reach `source`? If so, adding
+            // `source -> target` closes a directed cycle.
+            if (reaches(adjacency, edge.target, edge.source)) {
+                return (0, ts_utils_1.fail)(`ingest cycle guard: edge '${edge.source}' -${edge.type}-> '${edge.target}' would create a cycle`);
+            }
+            addEdge(adjacency, seenKeys, keyed);
+        }
+        return (0, ts_utils_1.succeed)(true);
+    }));
+}
+/** Canonically key a set of edges (the guard's only fallible step). */
+function keyEdges(edges) {
+    return (0, ts_utils_1.mapResults)(edges.map((edge) => buildCycleKey(edge).onSuccess((key) => (0, ts_utils_1.succeed)({ edge, key }))));
+}
+/** Add an edge to the adjacency map, de-duplicated by its canonical key. */
+function addEdge(adjacency, seenKeys, keyed) {
+    if (seenKeys.has(keyed.key)) {
+        return;
+    }
+    seenKeys.add(keyed.key);
+    const source = keyed.edge.source;
+    const target = keyed.edge.target;
+    const targets = adjacency.get(source);
+    if (targets === undefined) {
+        adjacency.set(source, new Set([target]));
+    }
+    else {
+        targets.add(target);
+    }
+}
+/** DFS reachability: is `to` reachable from `from` over `adjacency`? */
+function reaches(adjacency, from, to) {
+    const visited = new Set();
+    const stack = [from];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (node === to) {
+            return true;
+        }
+        if (visited.has(node)) {
+            continue;
+        }
+        visited.add(node);
+        const neighbors = adjacency.get(node);
+        if (neighbors !== undefined) {
+            for (const neighbor of neighbors) {
+                if (!visited.has(neighbor)) {
+                    stack.push(neighbor);
+                }
+            }
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=cycleGuard.js.map

package/lib/packlets/ingest/cycleGuard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cycleGuard.js","sourceRoot":"","sources":["../../../src/packlets/ingest/cycleGuard.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Hash, Result, fail, mapResults, succeed } from '@fgv/ts-utils';\nimport { LinkType, MemoryId } from '../types';\n\n/**\n * A directed edge in the link graph the cycle guard reasons over: `source` links\n * to `target` under relation `type`.\n * @public\n */\nexport interface ICycleGuardEdge {\n  readonly source: MemoryId;\n  readonly target: MemoryId;\n  readonly type: LinkType;\n}\n\n/**\n * Build the design's `buildCycleKey` — a deterministic, canonical (RFC-8785,\n * via `Crc32Normalizer` from `@fgv/ts-utils`) identity for a directed edge. Used\n * to de-duplicate proposed edges so a repeated `(source, target, type)` proposal\n * contributes a single graph edge (and never spuriously \"re-closes\" a cycle).\n * @public\n */\nexport function buildCycleKey(edge: ICycleGuardEdge): Result<string> {\n  return new Hash.Crc32Normalizer().computeHash({\n    source: edge.source,\n    target: edge.target,\n    type: edge.type\n  });\n}\n\n/**\n * Write-time cycle guard. Given the graph's EXISTING directed edges plus a set of\n * PROPOSED edges, verify that adding the proposed edges keeps the union graph a\n * DAG. Fails loudly, naming the first proposed edge that would close a directed\n * cycle.\n *\n * @remarks\n * Distinct from the read-time BFS in `LinkTraversalRetriever` (which tolerates\n * cycles via a visited-set): this is a WRITE-time admission check. Cycle\n * detection is DFS reachability — a proposed `source -> target` edge closes a\n * cycle iff `target` already reaches `source` in the graph built so far. Proposed\n * edges are folded in one at a time (in order), so an intra-batch cycle\n * (`A->B`, `B->A` both proposed) is caught as well as a batch-vs-existing cycle.\n *\n * See the design note §4: this enforces GLOBAL directed-acyclicity over all link\n * types (conservative — a mutual associative pair is rejected). Callers that need\n * mutual links disable the guard.\n * @public\n */\nexport function assertNoCycles(\n  existing: ReadonlyArray<ICycleGuardEdge>,\n  proposed: ReadonlyArray<ICycleGuardEdge>\n): Result<true> {\n  // Canonically key every edge up front (the only fallible step); the graph\n  // building + cycle detection below is then pure.\n  return keyEdges(existing).onSuccess((existingKeyed) =>\n    keyEdges(proposed).onSuccess((proposedKeyed) => {\n      // Adjacency map, de-duplicated by canonical edge key so a repeated edge is\n      // one arc. Seed with the existing edges, then fold in each proposed edge,\n      // checking reachability BEFORE inserting it.\n      const adjacency: Map<string, Set<string>> = new Map<string, Set<string>>();\n      const seenKeys: Set<string> = new Set<string>();\n      for (const keyed of existingKeyed) {\n        addEdge(adjacency, seenKeys, keyed);\n      }\n      for (const keyed of proposedKeyed) {\n        const edge: ICycleGuardEdge = keyed.edge;\n        // A self-loop is the degenerate one-node cycle.\n        if (edge.source === edge.target) {\n          return fail(\n            `ingest cycle guard: edge '${edge.source}' -${edge.type}-> '${edge.target}' is a self-loop`\n          );\n        }\n        // Reachability: does `target` already reach `source`? If so, adding\n        // `source -> target` closes a directed cycle.\n        if (reaches(adjacency, edge.target, edge.source)) {\n          return fail(\n            `ingest cycle guard: edge '${edge.source}' -${edge.type}-> '${edge.target}' would create a cycle`\n          );\n        }\n        addEdge(adjacency, seenKeys, keyed);\n      }\n      return succeed(true);\n    })\n  );\n}\n\n/** An edge paired with its canonical cycle key. */\ninterface IKeyedEdge {\n  readonly edge: ICycleGuardEdge;\n  readonly key: string;\n}\n\n/** Canonically key a set of edges (the guard's only fallible step). */\nfunction keyEdges(edges: ReadonlyArray<ICycleGuardEdge>): Result<ReadonlyArray<IKeyedEdge>> {\n  return mapResults(edges.map((edge) => buildCycleKey(edge).onSuccess((key) => succeed({ edge, key }))));\n}\n\n/** Add an edge to the adjacency map, de-duplicated by its canonical key. */\nfunction addEdge(adjacency: Map<string, Set<string>>, seenKeys: Set<string>, keyed: IKeyedEdge): void {\n  if (seenKeys.has(keyed.key)) {\n    return;\n  }\n  seenKeys.add(keyed.key);\n  const source: string = keyed.edge.source;\n  const target: string = keyed.edge.target;\n  const targets: Set<string> | undefined = adjacency.get(source);\n  if (targets === undefined) {\n    adjacency.set(source, new Set<string>([target]));\n  } else {\n    targets.add(target);\n  }\n}\n\n/** DFS reachability: is `to` reachable from `from` over `adjacency`? */\nfunction reaches(adjacency: ReadonlyMap<string, Set<string>>, from: string, to: string): boolean {\n  const visited: Set<string> = new Set<string>();\n  const stack: string[] = [from];\n  while (stack.length > 0) {\n    const node: string = stack.pop() as string;\n    if (node === to) {\n      return true;\n    }\n    if (visited.has(node)) {\n      continue;\n    }\n    visited.add(node);\n    const neighbors: Set<string> | undefined = adjacency.get(node);\n    if (neighbors !== undefined) {\n      for (const neighbor of neighbors) {\n        if (!visited.has(neighbor)) {\n          stack.push(neighbor);\n        }\n      }\n    }\n  }\n  return false;\n}\n"]}