agentfootprint 9.5.0 → 9.6.0

package/dist/types/memory/define.types.d.ts

@@ -314,6 +314,23 @@ export interface MemoryDefinition<T = unknown> {
     readonly read: ReadonlyMemoryFlowChart<T>;
     /** Compiled write subflow. Optional — `EPHEMERAL`-style configs omit. */
     readonly write?: ReadonlyMemoryFlowChart<T>;
+    /**
+     * The store this memory reads and writes (9.6.0).
+     *
+     * The compiled subflows already closed over it — this carries it in the
+     * open for the one question a subflow cannot answer from inside itself:
+     * **which turn of this conversation is about to happen?** A turn number
+     * is the key in `msg-{turn}-{index}` / `snap-{turn}` / `beat-{turn}-{i}`,
+     * and the only thing that remembers how far a conversation has got —
+     * across processes, across a fresh `Agent` per turn — is the store. The
+     * Agent reads this to resolve the turn once per run (`resolveTurnNumber`)
+     * before any memory subflow runs.
+     *
+     * Optional because a `MemoryDefinition` may be hand-built; a definition
+     * without it simply keeps whatever turn number its host supplies, which
+     * is what every release before 9.6.0 did.
+     */
+    readonly store?: MemoryStore;
     /** When `read` runs. Default `TURN_START`. */
     readonly timing: MemoryTiming;
     /** Reserved for a future release — patterns to redact before write. */

package/dist/types/memory/define.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define.types.d.ts","sourceRoot":"","sources":["../../../src/memory/define.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAI9D;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY;;;;;CAKf,CAAC;AACX,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAE1E;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;CAQpB,CAAC;AACX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,OAAO,iBAAiB,CAAC,CAAC;AAE5F;;;;;;GAMG;AACH,eAAO,MAAM,aAAa;;;CAGhB,CAAC;AACX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,OAAO,aAAa,CAAC,CAAC;AAE9E;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB;;;;;CAKvB,CAAC;AACX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,OAAO,oBAAoB,CAAC,CAAC;AAIlG;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,OAAO,iBAAiB,CAAC,MAAM,CAAC;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,OAAO,iBAAiB,CAAC,MAAM,CAAC;IAC/C,2EAA2E;IAC3E,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,0DAA0D;IAC1D,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,OAAO,iBAAiB,CAAC,SAAS,CAAC;IAClD,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,uEAAuE;IACvE,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;CAC3B;AAED;;;;GAIG;AACH;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,GAAG,qBAAqB,GAAG,qBAAqB,CAAC;AAEzE,uEAAuE;AACvE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,OAAO,iBAAiB,CAAC,KAAK,CAAC;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;;;OASG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC;CAC5B;AAED,mFAAmF;AACnF,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,OAAO,iBAAiB,CAAC,KAAK,CAAC;IAC9C,yFAAyF;IACzF,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IACtC,oDAAoD;IACpD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,OAAO,iBAAiB,CAAC,OAAO,CAAC;IAChD,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,KAAK,CAAC;IACtC,wCAAwC;IACxC,QAAQ,CAAC,GAAG,CAAC,EAAE,WAAW,CAAC;IAC3B,8DAA8D;IAC9D,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,iDAAiD;IACjD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,OAAO,iBAAiB,CAAC,KAAK,CAAC;IAC9C;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,OAAO,iBAAiB,CAAC,MAAM,CAAC;IAC/C,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC,OAAO,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC;CACvE;AAED,yDAAyD;AACzD,MAAM,MAAM,QAAQ,GAChB,oBAAoB,GACpB,cAAc,GACd,iBAAiB,GACjB,YAAY,GACZ,eAAe,GACf,aAAa,GACb,cAAc,CAAC;AAInB;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,kDAAkD;IAClD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAID;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,OAAO;IAC3C,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,0CAA0C;IAC1C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAE9B,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAE1B,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC,CAAC,CAAC,CAAC;IAE1C,yEAAyE;IACzE,QAAQ,CAAC,KAAK,CAAC,EAAE,uBAAuB,CAAC,CAAC,CAAC,CAAC;IAE5C,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAQ9B,uEAAuE;IACvE,QAAQ,CAAC,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAExC,oEAAoE;IACpE,QAAQ,CAAC,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAEzC;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC;IAEjC;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;CAChC;AAED,uDAAuD;AACvD,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,KAAK,CAAC;AAE5C;;;;;;GAMG;AAEH,MAAM,MAAM,uBAAuB,CAAC,EAAE,IAAI;IACxC,QAAQ,CAAC,OAAO,EAAE,yBAAyB,CAAC;CAC7C,CAAC;AAIF;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;IAK/B,QAAQ,CAAC,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAExC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC;IAEjC;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAE5B,iFAAiF;IACjF,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;CAChC;AAED,MAAM,WAAW,qBAAsB,SAAQ,uBAAuB;IACpE,QAAQ,CAAC,IAAI,EAAE,OAAO,YAAY,CAAC,QAAQ,CAAC;CAC7C;AAED,MAAM,WAAW,qBAAsB,SAAQ,uBAAuB;IACpE,QAAQ,CAAC,IAAI,EAAE,OAAO,YAAY,CAAC,QAAQ,CAAC;CAC7C;AAED,MAAM,WAAW,sBAAuB,SAAQ,uBAAuB;IACrE,QAAQ,CAAC,IAAI,EAAE,OAAO,YAAY,CAAC,SAAS,CAAC;CAC9C;AAED,MAAM,WAAW,mBAAoB,SAAQ,uBAAuB;IAClE,QAAQ,CAAC,IAAI,EAAE,OAAO,YAAY,CAAC,MAAM,CAAC;IAC1C,4DAA4D;IAC5D,QAAQ,CAAC,UAAU,CAAC,EAAE,kBAAkB,CAAC;CAC1C;AAED,2EAA2E;AAC3E,MAAM,MAAM,mBAAmB,GAC3B,qBAAqB,GACrB,qBAAqB,GACrB,sBAAsB,GACtB,mBAAmB,CAAC;AAIxB,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,UAAU,CAE/D;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,kBAAkB,CAE/E;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,YAAY,CAEnE;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,kBAAkB,CAE/E;AAID;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,oBAA8B,CAAC;AAEvE,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,6BAA6B,sBAAgC,CAAC;AAE3E,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE3D"}
+{"version":3,"file":"define.types.d.ts","sourceRoot":"","sources":["../../../src/memory/define.types.ts"],"names":[],"mappings":"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"}

package/dist/types/memory/index.d.ts

@@ -14,6 +14,7 @@ export * from './identity/index.js';
 export * from './pipeline/index.js';
 export * from './stages/index.js';
 export * from './store/index.js';
+export * from './turn/index.js';
 export * from './wire/index.js';
 export * from './retrieval/index.js';
 export { MEMORY_TYPES, MEMORY_STRATEGIES, MEMORY_TIMING, SNAPSHOT_PROJECTIONS, MEMORY_INJECTION_KEY_PREFIX, RETRIEVAL_EVIDENCE_KEY_PREFIX, isMemoryType, isMemoryStrategyKind, isMemoryTiming, isSnapshotProjection, memoryInjectionKey, isMemoryInjectionKey, retrievalEvidenceKey, isRetrievalEvidenceKey, type MemoryType, type MemoryStrategyKind, type MemoryTiming, type SnapshotProjection, type Strategy, type MemoryWindowStrategy, type BudgetStrategy, type SummarizeStrategy, type TopKStrategy, type TopKShorthandStrategy, type TopKRetrievalStrategy, type MemoryFlavor, type ExtractStrategy, type DecayStrategy, type HybridStrategy, type MemoryDefinition, type DefineMemoryOptions, type DefineEpisodicOptions, type DefineSemanticOptions, type DefineNarrativeOptions, type DefineCausalOptions, type MemoryRedactionPolicy, } from './define.types.js';

package/dist/types/memory/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/memory/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AAGrC,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,oBAAoB,EACpB,2BAA2B,EAC3B,6BAA6B,EAC7B,YAAY,EACZ,oBAAoB,EACpB,cAAc,EACd,oBAAoB,EACpB,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,sBAAsB,EACtB,KAAK,UAAU,EACf,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,QAAQ,EACb,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,GAC3B,MAAM,mBAAmB,CAAC;AAQ3B,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAI3C,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,GAC/B,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/memory/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AAGrC,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,oBAAoB,EACpB,2BAA2B,EAC3B,6BAA6B,EAC7B,YAAY,EACZ,oBAAoB,EACpB,cAAc,EACd,oBAAoB,EACpB,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,sBAAsB,EACtB,KAAK,UAAU,EACf,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,QAAQ,EACb,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,GAC3B,MAAM,mBAAmB,CAAC;AAQ3B,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAI3C,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,GAC/B,MAAM,iBAAiB,CAAC"}

package/dist/types/memory/stages/types.d.ts

@@ -24,9 +24,19 @@ export interface MemoryState {
      */
     readonly identity: MemoryIdentity;
     /**
-     * Run-local turn counter — 1 for the first `agent.run`, 2 for the second,
-     * and so on within the same conversationId. Written into `MemoryEntry.source`
-     * by write-side stages for provenance.
+     * WHICH TURN of this conversation this pipeline is running for — 1 for the
+     * first exchange, 2 for the second, and so on within one `conversationId`.
+     * Set by the wire layer before the pipeline runs.
+     *
+     * Not a label: write-side stages KEY their entries on it (`msg-{turn}-{i}`,
+     * `snap-{turn}`, `beat-{turn}-{i}`) and stamp it into `MemoryEntry.source`
+     * so recall can say "remembered from turn 5". Two turns that share this
+     * number are one turn overwriting the other.
+     *
+     * Under an Agent it is resolved once per run against the memory stores
+     * themselves (`resolveTurnNumber`), so it survives a fresh Agent — or a
+     * fresh process — per turn. A host that mounts these subflows itself owns
+     * the number: pass a real one, or call `resolveTurnNumber` to derive it.
      */
     readonly turnNumber: number;
     /**

package/dist/types/memory/stages/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/memory/stages/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,IAAI,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAErE,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAElC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;;;;;;OAOG;IACH,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;IAExC;;;;OAIG;IACH,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC;IAE/B;;;;;OAKG;IACH,QAAQ,EAAE,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC;IAEjC;;;;OAIG;IACH,SAAS,EAAE,OAAO,EAAE,CAAC;IAErB;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,EAAE,OAAO,uBAAuB,EAAE,iBAAiB,CAAC;IAE9D;;;;OAIG;IACH,WAAW,EAAE,OAAO,EAAE,CAAC;IAEvB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,+BAA+B,EAAE,WAAW,CAAC;IAElE,+EAA+E;IAC/E,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/memory/stages/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,IAAI,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAErE,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAElC;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;;;;;;OAOG;IACH,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;IAExC;;;;OAIG;IACH,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC;IAE/B;;;;;OAKG;IACH,QAAQ,EAAE,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC;IAEjC;;;;OAIG;IACH,SAAS,EAAE,OAAO,EAAE,CAAC;IAErB;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,EAAE,OAAO,uBAAuB,EAAE,iBAAiB,CAAC;IAE9D;;;;OAIG;IACH,WAAW,EAAE,OAAO,EAAE,CAAC;IAEvB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,+BAA+B,EAAE,WAAW,CAAC;IAElE,+EAA+E;IAC/E,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB"}

package/dist/types/memory/strategies.d.ts

@@ -24,7 +24,10 @@
  * `requirements` is what a host must SUPPLY (an embedder, an LLM, a store
  * that can search). Empty means the strategy runs anywhere, at $0.
  *
- * Pattern: declared capability descriptors + a guard that enforces them.
+ * Pattern: declared capability descriptors + the two guards that enforce
+ *          them — SHAPE first (`assertStrategyShape`: is this even a
+ *          strategy?), REQUIREMENTS after (`assertStrategyRequirements`: can
+ *          this deployment run it?).
  * Role:    memory/ layer-1, beside the const it describes.
  * Emits:   N/A — build-time only.
  *
@@ -85,6 +88,29 @@ export declare function listMemoryStrategies(): readonly MemoryStrategyInfo[];
  * not a strategy at all.
  */
 export declare function memoryStrategyInfo(kind: string): MemoryStrategyInfo | undefined;
+/**
+ * Refuse a strategy whose SHAPE is wrong, before anything reads into it.
+ *
+ * WHY it runs FIRST, ahead of both the pipeline dispatch and the
+ * requirements walk: those two read FIELDS off the strategy
+ * (`strategies[0]`, `s.embedder`, `for (const sub of strategy.strategies)`),
+ * and a field read off a shape that never had it is a `TypeError` with the
+ * library's internals in the text — `Cannot read properties of undefined
+ * (reading '0')` for `{ kind: 'hybrid', size: 5 }`, which names neither the
+ * option the caller got wrong nor the one they meant. A caller cannot act on
+ * that. This guard turns every such read into a refusal that names the
+ * field, shows the line that would have worked, and points at the catalogue.
+ *
+ * It checks SHAPE only — is this an object, does it carry a `kind`, does a
+ * `hybrid` carry the array that makes it a hybrid. It deliberately does NOT
+ * judge whether the kind is real or legal for the type: the dispatch refuses
+ * those and names the alternative for that type, which is the better message.
+ *
+ * @param strategy the strategy exactly as the caller wrote it — `unknown`,
+ *                 because the whole point is that it may not be a `Strategy`.
+ * @param site     the call to name in the message, e.g. `defineMemory[chat]`.
+ */
+export declare function assertStrategyShape(strategy: unknown, site: string): void;
 /**
  * Refuse a config whose strategy declares a requirement the caller did not
  * supply — by name, at BUILD, with the fix in the message.

package/dist/types/memory/strategies.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"strategies.d.ts","sourceRoot":"","sources":["../../../src/memory/strategies.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAGL,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,UAAU,EAEhB,MAAM,mBAAmB,CAAC;AAI3B;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,yBAAyB,GACjC,UAAU,GACV,cAAc,GACd,KAAK,GACL,CAAC,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;AAEpC;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,6EAA6E;IAC7E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2EAA2E;IAC3E,QAAQ,CAAC,YAAY,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAC5D,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;CACvC;AAsFD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,IAAI,SAAS,kBAAkB,EAAE,CAEpE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAE/E;AAID;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,mBAAmB,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAE3F"}
+{"version":3,"file":"strategies.d.ts","sourceRoot":"","sources":["../../../src/memory/strategies.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAGL,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,UAAU,EAEhB,MAAM,mBAAmB,CAAC;AAI3B;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,yBAAyB,GACjC,UAAU,GACV,cAAc,GACd,KAAK,GACL,CAAC,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;AAEpC;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,6EAA6E;IAC7E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2EAA2E;IAC3E,QAAQ,CAAC,YAAY,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAC5D,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;CACvC;AAsFD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,IAAI,SAAS,kBAAkB,EAAE,CAEpE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAE/E;AAuBD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAEzE;AA6ED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,mBAAmB,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAE3F"}

package/dist/types/memory/turn/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Turn identity — which turn of a conversation is about to happen.
+ *
+ * One rule, shared by every memory kind, so two turns of one conversation
+ * can never write the same turn-stamped ids. See `./resolveTurnNumber.ts`.
+ */
+export { maxStoredTurn, resolveTurnNumber, type MaxStoredTurnOptions, type ResolveTurnNumberOptions, } from './resolveTurnNumber.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/memory/turn/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/memory/turn/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,GAC9B,MAAM,wBAAwB,CAAC"}

package/dist/types/memory/turn/resolveTurnNumber.d.ts

@@ -0,0 +1,95 @@
+/**
+ * resolveTurnNumber — which turn of this conversation is about to happen?
+ *
+ * A memory entry's id is turn-stamped (`msg-{turn}-{index}`, `snap-{turn}`,
+ * `beat-{turn}-{index}`), so the turn number is not a label: it is the KEY
+ * two consecutive turns must not share. Get it wrong and every turn
+ * overwrites the previous one — a conversation memory that silently holds
+ * exactly one exchange no matter how large the window says it is. That is
+ * the bug this function exists to make impossible (9.6.0).
+ *
+ * **Why the host's own counter is not enough.** A host that runs one Agent
+ * instance for a whole conversation can count turns in memory. The shape
+ * seen in a production field deployment cannot: it builds a FRESH agent per
+ * turn (new process, new instance, same `conversationId`, same store), so
+ * anything counted in a variable is back to 1 on every request. The only
+ * thing that remembers how far the conversation has got is the STORE.
+ *
+ * **The rule** — `max(hostTurn, maxStoredTurn + 1)`:
+ *   - Hosts that track the turn honestly keep their numbering (`hostTurn: 5`
+ *     → turn 5; gaps preserved — an ordinal, not a count).
+ *   - A host whose counter is stale still gets a fresh, ordered turn: the
+ *     second turn of a conversation whose store already holds turn 1 is
+ *     turn 2, never turn 1 again.
+ *   - The two sources compose: whichever knows more wins, and neither can
+ *     drag the conversation backwards.
+ *
+ * The rule is the one `writeSnapshot` has applied to causal snapshots since
+ * 9.1 — this is that carve-out generalised so every memory kind shares one
+ * definition of "which turn is this", resolved ONCE per run (in the Agent's
+ * seed stage) rather than re-derived per write stage. Re-deriving per stage
+ * is not equivalent and is why this is a shared helper: `writeMessages`
+ * stamps turn N, and a scan taken after it would read N and answer N+1 — so
+ * beats written later in the same turn would carry a turn number no message
+ * of theirs has, and their `msg-{turn}-{index}` references would point at
+ * entries that do not exist.
+ *
+ * Cost: one paged `list()` per store per run, on the store the memory was
+ * already going to talk to. Bounded by {@link MAX_SCAN_PAGES}.
+ *
+ * @see ../stages/writeMessages.ts   the id format this protects
+ * @see ../causal/writeSnapshot.ts   the same rule, kept as self-defense for
+ *                                   hand-composed (non-Agent) pipelines
+ */
+import type { MemoryEntry } from '../entry/index.js';
+import type { MemoryIdentity } from '../identity/index.js';
+import type { MemoryStore } from '../store/index.js';
+export interface MaxStoredTurnOptions {
+    /**
+     * Which entries count. Default: every entry that carries
+     * `source.turn`. `writeSnapshot` narrows this to its own `snap-{n}` ids
+     * so that its self-defense stays stable no matter what else shares the
+     * namespace.
+     */
+    readonly turnFor?: (entry: MemoryEntry<unknown>) => number;
+}
+/**
+ * The highest turn already stored in this identity's namespace — 0 when the
+ * conversation has never been written to.
+ *
+ * Only LIVE entries are seen: `store.list` drops TTL-expired ones, the same
+ * as every read path, so an expired turn 4 does not hold the numbering open.
+ */
+export declare function maxStoredTurn(store: MemoryStore, identity: MemoryIdentity, options?: MaxStoredTurnOptions): Promise<number>;
+export interface ResolveTurnNumberOptions {
+    /**
+     * The durable stores this conversation is written to. Every one is
+     * consulted and the highest turn wins, so two memories sharing a
+     * conversation agree on which turn it is even when they keep their
+     * entries in different backends.
+     *
+     * Duplicates (the usual case — one store, several memories) are scanned
+     * once.
+     */
+    readonly stores: readonly MemoryStore[];
+    /** The conversation namespace to scan. */
+    readonly identity: MemoryIdentity;
+    /**
+     * What the host believes the turn is — a FLOOR, never the last word. The
+     * Agent derives it from the conversation it was handed (how many user
+     * turns are already in the history), which is right for a followed-up
+     * conversation and stale for a fresh agent per turn. Default 1.
+     */
+    readonly hostTurn?: number;
+}
+/**
+ * Resolve the turn number this run should stamp on everything it writes.
+ *
+ * Returns at least 1, always. A store that throws is NOT swallowed: a memory
+ * whose store is unreachable is going to fail on the next read anyway, and a
+ * turn number quietly guessed here is how entries overwrite each other.
+ */
+export declare function resolveTurnNumber(options: ResolveTurnNumberOptions): Promise<number>;
+/** A host turn below 1 (or not a number at all) means "I do not know" → 1. */
+export declare function normalizeHostTurn(hostTurn: number | undefined): number;
+//# sourceMappingURL=resolveTurnNumber.d.ts.map

package/dist/types/memory/turn/resolveTurnNumber.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveTurnNumber.d.ts","sourceRoot":"","sources":["../../../../src/memory/turn/resolveTurnNumber.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAsBrD,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,CAAC,OAAO,CAAC,KAAK,MAAM,CAAC;CAC5D;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,cAAc,EACxB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,MAAM,CAAC,CAqBjB;AAED,MAAM,WAAW,wBAAwB;IACvC;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;IAExC,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAElC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,MAAM,CAAC,CAS1F;AAED,8EAA8E;AAC9E,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAGtE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentfootprint",
-  "version": "9.5.0",
+  "version": "9.6.0",
   "description": "The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.",
   "license": "MIT",
   "type": "commonjs",