@remnic/core 9.3.712 → 9.3.714

package/dist/{orchestrator-B1iVjEyc.d.ts → orchestrator-iVZWi8aW.d.ts}

@@ -12,7 +12,7 @@ import { LiveConnectorsRunSummary } from './live-connectors-runner.js';
 import { ModelRegistry } from './model-registry.js';
 import { RelevanceStore } from './relevance.js';
 import { NegativeExampleStore } from './negative.js';
-import { LastRecallStore, TierMigrationStatusStore, GraphRecallExpandedEntry, TierMigrationStatusSnapshot, TierMigrationCycleSummary, LastRecallSnapshot } from './recall-state.js';
+import { LastRecallStore, RecallHandleHistoryStore, TierMigrationStatusStore, GraphRecallExpandedEntry, TierMigrationStatusSnapshot, TierMigrationCycleSummary, LastRecallSnapshot } from './recall-state.js';
 import { RecallXraySnapshot } from './recall-xray.js';
 import { SessionObserverState } from './session-observer-state.js';
 import { EmbeddingFallback } from './embedding-fallback.js';
@@ -21,11 +21,11 @@ import { CapabilitySet } from './capabilities.js';
 import { ReplayTurn } from './replay/types.js';
 import { I as ImportTurn } from './types-gb_SNtjR.js';
 import { JudgeCandidate, JudgeBatchResult } from './extraction-judge.js';
-import { u as BufferTurn, a0 as ExtractionResult, M as MemoryCategory, a9 as ImportanceScore, f as MemoryStatus, aw as WearableConversation, ax as WearableSourceSettings, ay as WearableNativeMemory, az as WearableMemoryMode, aA as WearableSourceConnector, aB as WearablesConfig, aC as WearableSyncSummary, aD as WearableSourceStatus, aE as WearableDayTranscript, aF as WearableCorrectionRule, P as PluginConfig, aG as CodingContext, Q as QmdSearchResult, e as BehaviorLoopPolicyState, aH as BootstrapOptions, aI as BootstrapResult, aJ as ConsolidationObservation, g as MemoryFile, a2 as DaySummaryResult, W as MemoryActionEvent, h as RecallPlanMode, aa as MemoryIntent, aK as EntityTimelineEntry, k as MemoryFrontmatter, I as IdentityInjectionMode } from './types-Dr0Cw3L9.js';
+import { u as BufferTurn, a0 as ExtractionResult, M as MemoryCategory, a9 as ImportanceScore, f as MemoryStatus, aw as WearableConversation, ax as WearableSourceSettings, ay as WearableNativeMemory, az as WearableMemoryMode, aA as WearableSourceConnector, aB as WearablesConfig, aC as WearableSyncSummary, aD as WearableSourceStatus, aE as WearableDayTranscript, aF as WearableCorrectionRule, P as PluginConfig, aG as CodingContext, Q as QmdSearchResult, e as BehaviorLoopPolicyState, aH as BootstrapOptions, aI as BootstrapResult, aJ as ConsolidationObservation, g as MemoryFile, a2 as DaySummaryResult, W as MemoryActionEvent, h as RecallPlanMode, aa as MemoryIntent, aK as EntityTimelineEntry, k as MemoryFrontmatter, I as IdentityInjectionMode } from './types-D9dwzU_x.js';
 import { LcmEngine } from './lcm/engine.js';
-import { S as SemanticConsolidationResult } from './semantic-consolidation-CY8uVRNJ.js';
+import { S as SemanticConsolidationResult } from './semantic-consolidation-DSjMDZ1u.js';
 import { ConversationIndexBackendInspection } from './conversation-index/backend.js';
-import { a as NamespaceKind, N as NamespaceCatalog } from './catalog-CadPvH29.js';
+import { a as NamespaceKind, N as NamespaceCatalog } from './catalog-CbR0CsUw.js';
 import { NamespaceSearchHealth } from './namespaces/search.js';
 import { SharedContextManager } from './shared-context/manager.js';
 import { CompoundingEngine } from './compounding/engine.js';
@@ -985,6 +985,7 @@ declare class Orchestrator {
     readonly relevance: RelevanceStore;
     readonly negatives: NegativeExampleStore;
     readonly lastRecall: LastRecallStore;
+    readonly handleHistory: RecallHandleHistoryStore;
     readonly tierMigrationStatus: TierMigrationStatusStore;
     /**
      * In-memory X-ray snapshot from the most recent `recall()` call that
@@ -1929,6 +1930,22 @@ declare class Orchestrator {
     recordMemoryFeedback(memoryId: string, vote: "up" | "down", note?: string): Promise<void>;
     recordNotUsefulMemories(memoryIds: string[], note?: string): Promise<void>;
     getLastRecall(sessionKey: string): LastRecallSnapshot | null;
+    /**
+     * Issue #1582 — resolve a memory handle (`[m:4f2a]` / bare hex) to its memory
+     * id against THIS session's recent recall history. Returns the id on a unique
+     * hit, `null` on a miss, and throws on ambiguity (callers must disambiguate —
+     * rule 34/51). Resolution is per-session and snapshot-scoped; there is no
+     * global handle→id map (rule 42).
+     */
+    resolveMemoryHandle(handle: string, sessionKey: string): string | null;
+    /**
+     * Issue #1582 — resolve a caller reference that may be EITHER a memory id or
+     * a handle to a concrete memory id. Handles resolve against the session's
+     * recall history; raw ids pass through unchanged. The single shared helper
+     * every surface (memory_get / feedback / outcome / correction targetIds)
+     * calls so handle resolution has one path (rule 22).
+     */
+    resolveMemoryIdOrHandle(ref: string, sessionKey?: string): string;
     /**
      * Check if a new memory contradicts an existing one.
      * Uses QMD to find similar memories, then LLM to verify contradiction.

package/dist/orchestrator.d.ts

@@ -9,7 +9,7 @@ import './local-llm.js';
 import './fallback-llm.js';
 import './orchestration/maintenance.js';
 import './live-connectors-runner.js';
-export { L as BulkImportBatchIngestResult, M as BulkImportBatchPartialFailureError, N as GraphRecallRankedResult, Q as GraphRecallShadowComparison, G as GraphRecallSnapshot, I as IntentDebugSnapshot, O as Orchestrator, T as QmdRecallSnapshot, U as RecallInvocationOptions, V as RecallModeDecision, X as appendMemoryToGraphContext, Y as blendGraphExpandedRecallScore, Z as buildCompressionGuidelinesMarkdown, _ as buildMemoryPathById, $ as computeArtifactCandidateFetchLimit, a0 as computeArtifactRecallLimit, a1 as computeQmdHybridFetchLimit, a2 as dedupeEntitySynthesisEvidenceEntries, q as defaultWorkspaceDir, a3 as deriveTopicsFromExtraction, a4 as filterRecallCandidates, a5 as formatCompressionGuidelinesForRecall, a6 as graphPathRelativeToStorage, a7 as hasIdentityRecoveryIntent, a8 as isArtifactMemoryPath, a9 as lifecycleRecallScoreAdjustment, aa as mergeArtifactRecallCandidates, ab as mergeGraphExpandedResults, ac as resolveEffectiveIdentityInjectionMode, ad as resolveEffectiveRecallMode, ae as resolvePersistedMemoryRelativePath, af as resolveRecallModeDecision, ag as resolveRecallModeDecisionAsync, ah as resolveRecentThreadMemoryPaths, A as sanitizeSessionKeyForFilename, ai as shouldFilterLifecycleRecallCandidate, aj as summarizeGraphShadowComparison } from './orchestrator-B1iVjEyc.js';
+export { L as BulkImportBatchIngestResult, M as BulkImportBatchPartialFailureError, N as GraphRecallRankedResult, Q as GraphRecallShadowComparison, G as GraphRecallSnapshot, I as IntentDebugSnapshot, O as Orchestrator, T as QmdRecallSnapshot, U as RecallInvocationOptions, V as RecallModeDecision, X as appendMemoryToGraphContext, Y as blendGraphExpandedRecallScore, Z as buildCompressionGuidelinesMarkdown, _ as buildMemoryPathById, $ as computeArtifactCandidateFetchLimit, a0 as computeArtifactRecallLimit, a1 as computeQmdHybridFetchLimit, a2 as dedupeEntitySynthesisEvidenceEntries, q as defaultWorkspaceDir, a3 as deriveTopicsFromExtraction, a4 as filterRecallCandidates, a5 as formatCompressionGuidelinesForRecall, a6 as graphPathRelativeToStorage, a7 as hasIdentityRecoveryIntent, a8 as isArtifactMemoryPath, a9 as lifecycleRecallScoreAdjustment, aa as mergeArtifactRecallCandidates, ab as mergeGraphExpandedResults, ac as resolveEffectiveIdentityInjectionMode, ad as resolveEffectiveRecallMode, ae as resolvePersistedMemoryRelativePath, af as resolveRecallModeDecision, ag as resolveRecallModeDecisionAsync, ah as resolveRecentThreadMemoryPaths, A as sanitizeSessionKeyForFilename, ai as shouldFilterLifecycleRecallCandidate, aj as summarizeGraphShadowComparison } from './orchestrator-iVZWi8aW.js';
 import './model-registry.js';
 import './relevance.js';
 import './negative.js';
@@ -21,11 +21,11 @@ import './semantic-SLAa_prH.js';
 import './capabilities.js';
 import './replay/types.js';
 import './types-gb_SNtjR.js';
-import './types-Dr0Cw3L9.js';
+import './types-D9dwzU_x.js';
 import './lcm/engine.js';
-import './semantic-consolidation-CY8uVRNJ.js';
+import './semantic-consolidation-DSjMDZ1u.js';
 import './conversation-index/backend.js';
-import './catalog-CadPvH29.js';
+import './catalog-CbR0CsUw.js';
 import './namespaces/search.js';
 import './shared-context/manager.js';
 import './compounding/engine.js';

package/dist/orchestrator.js

@@ -28,44 +28,44 @@ import {
   sanitizeSessionKeyForFilename,
   shouldFilterLifecycleRecallCandidate,
   summarizeGraphShadowComparison
-} from "./chunk-GKPIY7EQ.js";
+} from "./chunk-FXZKXW7C.js";
 import "./chunk-DGTDRIUO.js";
-import "./chunk-3TCRU4JA.js";
+import "./chunk-O62P2LFL.js";
 import "./chunk-7HYPN2GC.js";
 import "./chunk-666A3MOW.js";
 import "./chunk-HHLLAQGZ.js";
+import "./chunk-UWK5OXUJ.js";
 import "./chunk-773DPI6T.js";
 import "./chunk-7N4KAIGN.js";
 import "./chunk-TPDBFYEG.js";
 import "./chunk-KCYE2MZM.js";
 import "./chunk-KYYL4U6X.js";
 import "./chunk-XPOOY35N.js";
-import "./chunk-UWK5OXUJ.js";
+import "./chunk-HW5EF6LV.js";
 import "./chunk-TECVW3JP.js";
 import "./chunk-O7GOFAM3.js";
-import "./chunk-HW5EF6LV.js";
-import "./chunk-54TI5GLV.js";
+import "./chunk-WI4QX7GH.js";
 import "./chunk-UFS7OXGL.js";
-import "./chunk-UHGBNIOS.js";
 import "./chunk-LXOM6IQU.js";
+import "./chunk-ECZU5BJH.js";
+import "./chunk-UHGBNIOS.js";
 import "./chunk-4EX5WZ4M.js";
 import "./chunk-VOUOLGIP.js";
 import "./chunk-S75M5ZRK.js";
-import "./chunk-ECZU5BJH.js";
 import "./chunk-IO5NQEGZ.js";
 import "./chunk-3FAMU5TX.js";
 import "./chunk-4SBW47WK.js";
 import "./chunk-DKTSR7EK.js";
+import "./chunk-5IZL4DCV.js";
+import "./chunk-GG6AJN7A.js";
 import "./chunk-E3VODCC3.js";
 import "./chunk-L6W77GWW.js";
 import "./chunk-L24JROPR.js";
 import "./chunk-MGN7VHWQ.js";
-import "./chunk-5IZL4DCV.js";
+import "./chunk-UC4YOAC2.js";
 import "./chunk-X7XN6YU4.js";
-import "./chunk-GG6AJN7A.js";
 import "./chunk-YDBIWGNI.js";
 import "./chunk-VQ34TERH.js";
-import "./chunk-VILEUJXC.js";
 import "./chunk-ZZTOURJI.js";
 import "./chunk-EXM3CQTZ.js";
 import "./chunk-3GPTTA4J.js";
@@ -75,7 +75,7 @@ import "./chunk-H63EDPFJ.js";
 import "./chunk-PD6O7AXF.js";
 import "./chunk-YAZNBMNF.js";
 import "./chunk-TH7WMHVK.js";
-import "./chunk-VYZNWH4J.js";
+import "./chunk-2SXMCQEQ.js";
 import "./chunk-4RA3C3EV.js";
 import "./chunk-5GSUBCZM.js";
 import "./chunk-54V4BZWP.js";
@@ -93,21 +93,21 @@ import "./chunk-VEWZZM3H.js";
 import "./chunk-OQH5XUH3.js";
 import "./chunk-6HEM6HTQ.js";
 import "./chunk-ZA2S2VLL.js";
-import "./chunk-HSDJCT3V.js";
+import "./chunk-DXGS5YOQ.js";
 import "./chunk-EO5QWINU.js";
 import "./chunk-2PRQG7PV.js";
 import "./chunk-WIWPSQYU.js";
-import "./chunk-S6FQLQGH.js";
+import "./chunk-V7GDTQ6I.js";
 import "./chunk-2F6NP3NT.js";
 import "./chunk-TERNBNJB.js";
 import "./chunk-QRDOSYOR.js";
-import "./chunk-SKQCFAYU.js";
+import "./chunk-JVEMUX6L.js";
 import "./chunk-ZRWB5D4H.js";
 import "./chunk-GY3SKOS4.js";
 import "./chunk-SFQ6QNL7.js";
-import "./chunk-7NDYFAJS.js";
-import "./chunk-GMRNKPWO.js";
-import "./chunk-BQCFXAMN.js";
+import "./chunk-GM3BMWKR.js";
+import "./chunk-6QUPUTT7.js";
+import "./chunk-MPHDVHIB.js";
 import "./chunk-KFY3SGN7.js";
 import "./chunk-33JBK2XP.js";
 import "./chunk-TQNRI55H.js";
@@ -122,8 +122,8 @@ import "./chunk-FZZ2QTJI.js";
 import "./chunk-LMDRGRJ2.js";
 import "./chunk-OD4FM2U7.js";
 import "./chunk-PBH4JUAB.js";
-import "./chunk-NXL5CVE7.js";
-import "./chunk-CNVIWMQI.js";
+import "./chunk-2Y6LMOQQ.js";
+import "./chunk-UY4JMEAK.js";
 import "./chunk-UUH4YQOF.js";
 import "./chunk-JLNBQWZ2.js";
 import "./chunk-3UXOZBHV.js";
@@ -144,15 +144,15 @@ import "./chunk-RS25QOKZ.js";
 import "./chunk-JGSKJHF7.js";
 import "./chunk-S4DDLTPX.js";
 import "./chunk-FF4KLI5W.js";
-import "./chunk-OWOKOFXK.js";
-import "./chunk-K22IJO4R.js";
-import "./chunk-OMSTU233.js";
+import "./chunk-AJOIM6UR.js";
+import "./chunk-CTOQEZSN.js";
+import "./chunk-2KAYTPPT.js";
+import "./chunk-WRFKZEO6.js";
 import "./chunk-CYEPCZN5.js";
 import "./chunk-LQ6JI4VH.js";
 import "./chunk-SANZHXY2.js";
 import "./chunk-EHISUJFN.js";
 import "./chunk-5CEJH5ZN.js";
-import "./chunk-WRFKZEO6.js";
 import "./chunk-AER6MT24.js";
 import "./chunk-CINZGPSJ.js";
 import "./chunk-ZFXCQPNO.js";
@@ -168,7 +168,7 @@ import "./chunk-EI6V5UXY.js";
 import "./chunk-PNLCEFE4.js";
 import "./chunk-O75CRYGF.js";
 import "./chunk-QDW3E4RD.js";
-import "./chunk-HV57RHMD.js";
+import "./chunk-EH5ED3C6.js";
 import "./chunk-3ONXXHQO.js";
 import "./chunk-YI7RZO7Y.js";
 import "./chunk-YGKUAX2B.js";
@@ -176,18 +176,18 @@ import "./chunk-DEUNUKTD.js";
 import "./chunk-2LSZVONP.js";
 import "./chunk-TBBDFYXW.js";
 import "./chunk-ZBJMUXZH.js";
-import "./chunk-35YJ6KCV.js";
-import "./chunk-JSDZMOT7.js";
-import "./chunk-M7XQSUBB.js";
+import "./chunk-JEIROMLX.js";
+import "./chunk-OC56UWV5.js";
 import "./chunk-3JJWNZTT.js";
+import "./chunk-M7XQSUBB.js";
 import "./chunk-5UZXUTVO.js";
 import "./chunk-5GPPACXK.js";
 import "./chunk-TKZ3AL5V.js";
 import "./chunk-6CIAGZ6X.js";
+import "./chunk-J6A3CX5N.js";
 import "./chunk-SVOZFLIQ.js";
 import "./chunk-LTJAMRGI.js";
-import "./chunk-J6A3CX5N.js";
-import "./chunk-BOGENF7P.js";
+import "./chunk-MSVSP5VO.js";
 import "./chunk-RULE4VG5.js";
 import "./chunk-SCU65EZI.js";
 import "./chunk-MB5RSUW6.js";
@@ -216,13 +216,14 @@ import "./chunk-I4WBNM3M.js";
 import "./chunk-SOAU2OE2.js";
 import "./chunk-UZYLX7M6.js";
 import "./chunk-U3PN77QT.js";
-import "./chunk-SK2CR6MW.js";
-import "./chunk-FVQJYWH7.js";
+import "./chunk-RVLB4E6N.js";
+import "./chunk-5GKPFL3S.js";
 import "./chunk-4DJQYKMN.js";
 import "./chunk-EYIEWJNI.js";
 import "./chunk-JUC24CTX.js";
 import "./chunk-NU3CSQ4H.js";
 import "./chunk-6MKAMLQL.js";
+import "./chunk-JAKIDQB2.js";
 import "./chunk-PVGDJXVK.js";
 import "./chunk-A2IYSXDQ.js";
 import "./chunk-LPSF4OQH.js";

package/dist/patterns-cli.d.ts

@@ -1,4 +1,4 @@
-import { M as MemoryCategory, g as MemoryFile } from './types-Dr0Cw3L9.js';
+import { M as MemoryCategory, g as MemoryFile } from './types-D9dwzU_x.js';
 import './types-gb_SNtjR.js';
 import './message-parts/index.js';
 

package/dist/policy-runtime.d.ts

@@ -1,4 +1,4 @@
-import { P as PluginConfig, e as BehaviorLoopPolicyState } from './types-Dr0Cw3L9.js';
+import { P as PluginConfig, e as BehaviorLoopPolicyState } from './types-D9dwzU_x.js';
 import './types-gb_SNtjR.js';
 import './message-parts/index.js';
 

package/dist/provenance.d.ts

@@ -1,4 +1,4 @@
-import { ai as ProvenanceSource, aj as ProvenanceConfig, k as MemoryFrontmatter } from './types-Dr0Cw3L9.js';
+import { ai as ProvenanceSource, aj as ProvenanceConfig, k as MemoryFrontmatter } from './types-D9dwzU_x.js';
 import './types-gb_SNtjR.js';
 import './message-parts/index.js';
 

package/dist/provenance.js

@@ -5,10 +5,11 @@ import {
   parseProvenanceTag,
   reconcileProvenanceRead,
   serializeProvenanceFields
-} from "./chunk-SK2CR6MW.js";
-import "./chunk-FVQJYWH7.js";
+} from "./chunk-RVLB4E6N.js";
+import "./chunk-5GKPFL3S.js";
 import "./chunk-JUC24CTX.js";
 import "./chunk-6MKAMLQL.js";
+import "./chunk-JAKIDQB2.js";
 import "./chunk-PZ5AY32C.js";
 export {
   buildFactProvenance,

package/dist/qmd-recall-cache.d.ts

@@ -1,4 +1,4 @@
-import { h as RecallPlanMode } from './types-Dr0Cw3L9.js';
+import { h as RecallPlanMode } from './types-D9dwzU_x.js';
 import { SearchQueryOptions } from './search/port.js';
 import './types-gb_SNtjR.js';
 import './message-parts/index.js';

package/dist/qmd.d.ts

@@ -1,4 +1,4 @@
-import { Q as QmdSearchResult, ab as QmdSearchExplain } from './types-Dr0Cw3L9.js';
+import { Q as QmdSearchResult, ab as QmdSearchExplain } from './types-D9dwzU_x.js';
 import { SearchBackend, SearchExecutionOptions, SearchQueryOptions } from './search/port.js';
 import './types-gb_SNtjR.js';
 import './message-parts/index.js';

package/dist/recall-disclosure-escalation.d.ts

@@ -1,4 +1,4 @@
-import { i as RecallDisclosure } from './types-Dr0Cw3L9.js';
+import { i as RecallDisclosure } from './types-D9dwzU_x.js';
 import './types-gb_SNtjR.js';
 import './message-parts/index.js';
 

package/dist/recall-explain-renderer.d.ts

@@ -1,5 +1,5 @@
 import { LastRecallSnapshot } from './recall-state.js';
-import { R as RecallTierExplain } from './types-Dr0Cw3L9.js';
+import { R as RecallTierExplain } from './types-D9dwzU_x.js';
 import { RecallXraySnapshot } from './recall-xray.js';
 import './search/port.js';
 import './types-gb_SNtjR.js';

package/dist/recall-explain-renderer.js

@@ -5,10 +5,10 @@ import {
   toRecallExplainJson,
   toRecallExplainText,
   toRecallXraySnapshotFromLegacy
-} from "./chunk-5QUS24F7.js";
+} from "./chunk-I56LKMF7.js";
 import "./chunk-SOBJ6NEY.js";
-import "./chunk-OWOKOFXK.js";
-import "./chunk-BOGENF7P.js";
+import "./chunk-AJOIM6UR.js";
+import "./chunk-MSVSP5VO.js";
 import "./chunk-I4WBNM3M.js";
 import "./chunk-SOAU2OE2.js";
 import "./chunk-PZ5AY32C.js";

package/dist/recall-handles.d.ts

@@ -0,0 +1,228 @@
+/**
+ * recall-handles.ts — injection-time memory handles (issue #1582).
+ *
+ * Every injected memory gets a stable short handle — `[m:4f2a]` — so a user
+ * (or the agent) can react to ONE specific memory in-band ("[m:4f2a] is
+ * stale", thumbs-down, "correct that") without a context switch to a CLI or
+ * console. The handle is derived from the memory **id** (never the content),
+ * so it is stable across edits/versioning.
+ *
+ * This module is PURE — no I/O, no side effects, no state. It owns:
+ *   - {@link handleFor} — deterministic 4-hex handle from a memory id.
+ *   - {@link renderHandle} / {@link renderHandlesForInjection} — render the
+ *     `[m:xxxx]` token for one memory (or a whole injection set, extending to
+ *     6 chars on intra-injection collision).
+ *   - {@link parseHandles} — extract handle tokens from prose.
+ *   - {@link normalizeHandle} / {@link isHandleToken} — classify a string.
+ *   - {@link resolveHandle} — map a handle back to a memory id against the
+ *     session's recent recall snapshots (hit / not-found / ambiguous).
+ *
+ * Design rules honored (issue #1582 design + pitfalls):
+ *   - Handles are derived from the id only — never hashed with content, never
+ *     persisted into memory files or rawContent (rule 23). Rendering happens
+ *     at injection time only.
+ *   - Resolution is per-session and snapshot-scoped — there is NEVER a global
+ *     handle→id map (collision space too small globally, leaks across
+ *     principals — rule 42). Misses are tagged, never guessed (rule 34/51).
+ *   - The formatter is allocation-light: a string append at render time, no
+ *     per-memory object churn, because it runs on every recall.
+ */
+/**
+ * Default handle width in hex characters (4 → 65 536-handle space).
+ * Per-injection sets are ~10–40 memories, so in-context collisions are
+ * vanishingly rare; {@link renderHandlesForInjection} widens the colliding
+ * member to {@link HANDLE_EXTENDED_WIDTH} when two ids in ONE injection would
+ * collide.
+ */
+declare const HANDLE_DEFAULT_WIDTH = 4;
+/**
+ * Width used to disambiguate two ids that collide at the default width within
+ * a single injection. 6 hex chars → ~16 M-handle space, which is comfortably
+ * beyond per-injection set sizes.
+ */
+declare const HANDLE_EXTENDED_WIDTH = 6;
+/** Minimum/maximum accepted hex widths for a rendered/parsed handle. */
+declare const HANDLE_MIN_WIDTH = 4;
+declare const HANDLE_MAX_WIDTH = 8;
+/**
+ * Regex matching a rendered handle token anywhere in prose: `[m:` followed by
+ * 4–8 lowercase hex chars and a closing `]`. Malformed tokens (`[m:xyz!]`,
+ * `[m:abc]` with uppercase, missing bracket) are intentionally NOT matched.
+ * Used by {@link parseHandles} and the sanitizer.
+ */
+declare const HANDLE_REGEX: RegExp;
+/**
+ * Memory ids are `<category>-<timestamp>-<suffix>` (e.g. `fact-1770469224307-eelr`,
+ * `artifact-...`, `reasoning_trace-...`, plus parent-`-chunk-N` variants). The
+ * category segment allows underscores because `MemoryCategory` includes
+ * `reasoning_trace` (codex review); bare names (`Widget`) still fail. Entity
+ * reconstructions and other non-memory `.md` rows use bare names (`Widget`)
+ * that must NOT receive a handle — citing one would resolve to a basename no
+ * storage can load. This pattern gates handle rendering/recording to plausible
+ * memory ids only (issue #1582, codex review).
+ */
+declare const MEMORY_ID_PATTERN: RegExp;
+/**
+ * Derive the deterministic handle hex for a memory id at a given width.
+ *
+ * `handleFor(id) === handleFor(id)` always, and `handleFor(id, w)` is a prefix
+ * of `handleFor(id, w+1)` (both slice the same sha256 hex digest), so widening
+ * for collision-disambiguation never changes the shorter prefix.
+ *
+ * @param memoryId  Stable memory id (e.g. `fact-1770469224307-eelr`).
+ * @param width     Hex width. Defaults to {@link HANDLE_DEFAULT_WIDTH}.
+ *                   Clamped to [4, 8]; the digest has 64 hex chars available.
+ */
+declare function handleFor(memoryId: string, width?: number): string;
+/**
+ * Render the `[m:xxxx]` token for one memory id. Width override is for the
+ * collision-extension path in {@link renderHandlesForInjection}; callers that
+ * render a single handle in isolation should omit it.
+ */
+declare function renderHandle(memoryId: string, widthOverride?: number): string;
+/**
+ * Append a handle to a memory line, allocation-light. When `widthOverride` is
+ * omitted the default-width handle is used; pass the widened width from
+ * {@link renderHandlesForInjection} for a colliding member.
+ *
+ *   appendHandle("API rate limit is 1000 rpm.", "fact-1-abc")
+ *   // → "API rate limit is 1000 rpm. [m:4f2a]"
+ */
+declare function appendHandle(line: string, memoryId: string, widthOverride?: number): string;
+/**
+ * Result of {@link renderHandlesForInjection}: for each memory id, the width
+ * used (default 4, or 6 when widened to break an intra-injection collision)
+ * and the rendered token. Ordered for stable iteration.
+ */
+interface InjectionHandleEntry {
+    memoryId: string;
+    width: number;
+    handle: string;
+}
+/**
+ * Build handles for a whole injection set, widening to 6 chars when two ids
+ * collide at the default width within THIS set (so each rendered token is
+ * unique in context). Idempotent for the same input.
+ *
+ * The collision case is vanishingly rare (~10–40 memories per injection), but
+ * widening guarantees a user can always point at exactly one memory in-band.
+ */
+declare function renderHandlesForInjection(memoryIds: readonly string[]): InjectionHandleEntry[];
+/**
+ * Build a `resultIndex → handle` map for a QMD result set. Returns an empty
+ * map when handles are disabled or no result carries a handle-eligible memory
+ * id. Extracted from the orchestrator's `formatQmdResults` so the rendering
+ * logic lives in the pure handles module, not the god file (issue #1582,
+ * rule 4).
+ *
+ * Only real memory ids (matching {@link MEMORY_ID_PATTERN}) are handle-eligible;
+ * entity reconstructions and other non-memory `.md` rows get no handle.
+ *
+ * @param results  QMD search results (each has a `path` like `…/fact-x.md`).
+ * @param enabled  Whether handle rendering is on. The caller gates on both the
+ *                  config flag and session-key availability — handles rendered
+ *                  without a session key can never be resolved, so they must
+ *                  not be shown (cursor review of #1582).
+ */
+declare function buildHandleIndexForResults(results: readonly {
+    path: string;
+}[], enabled: boolean): Map<number, string>;
+/**
+ * Extract every handle token from prose, in order of appearance. Returns the
+ * full rendered tokens (e.g. `[m:4f2a]`) so callers can locate them in text.
+ * Malformed tokens are ignored. Duplicates are preserved (a user may cite the
+ * same memory twice).
+ *
+ *   parseHandles("see [m:4f2a] (also [m:1b9e]) — not [m:xyz!]")
+ *   // → ["[m:4f2a]", "[m:1b9e]"]
+ */
+declare function parseHandles(text: string): string[];
+/**
+ * Strip every handle token from text, collapsing the spacing it introduced.
+ * Used by the sanitizer so handles observed back into the pipeline never
+ * become memory content (issue #1582 hygiene §2).
+ *
+ *   stripHandles("API limit 1000 rpm. [m:4f2a]") → "API limit 1000 rpm."
+ */
+declare function stripHandles(text: string): string;
+/**
+ * Normalize a handle token (or bare hex) to its lowercase hex core, or `null`
+ * when the input is not a handle. Accepts both the rendered `[m:4f2a]` form
+ * and the bare `m:4f2a` / `4f2a` form a user might type.
+ *
+ *   normalizeHandle("[m:4f2a]") → "4f2a"
+ *   normalizeHandle("m:4f2a")   → "4f2a"
+ *   normalizeHandle("4f2a")     → "4f2a"
+ *   normalizeHandle("fact-1")   → null
+ */
+declare function normalizeHandle(token: string): string | null;
+/**
+ * Whether a string looks like a handle token (rendered or bare). Cheaper
+ * boolean form of {@link normalizeHandle} for callers that only need to branch.
+ */
+declare function isHandleToken(token: string): boolean;
+/**
+ * A flattened id-or-handle reference: either a raw memory id or the hex core
+ * of a handle. {@link resolveMemoryIdOrHandle} produces this so the snapshot
+ * lookup only runs for actual handles.
+ */
+interface ParsedIdOrHandle {
+    /** The original reference as supplied by the caller. */
+    raw: string;
+    /** `true` when `raw` is a handle that still needs snapshot resolution. */
+    isHandle: boolean;
+    /** For a handle, its hex core; for a raw id, the id itself. */
+    value: string;
+}
+/**
+ * Classify a single caller reference as id-or-handle.
+ */
+declare function parseIdOrHandle(ref: string): ParsedIdOrHandle;
+/**
+ * A flattened view of the memory-id sets a session has recently recalled.
+ * Each entry is one past recall's admitted memory ids (newest first).
+ * Resolution never sees raw {@link LastRecallSnapshot}s — callers flatten to
+ * this so the pure resolver has no dependency on the snapshot type.
+ */
+interface RecallSnapshotIds {
+    memoryIds: readonly string[];
+}
+/**
+ * Result of resolving a handle against recent recall snapshots.
+ * - `{ ok: true, memoryId }` — exactly one match within the lookback window.
+ * - `{ ok: false, reason: "not_found" }` — no memory id produced this handle
+ *   within the window (misses are acceptable and tagged, never guessed).
+ * - `{ ok: false, reason: "ambiguous", candidates }` — two DIFFERENT memory
+ *   ids in the window collide on the same handle; the caller must disambiguate
+ *   (rule 34/51: never guess).
+ */
+type ResolveHandleResult = {
+    ok: true;
+    memoryId: string;
+} | {
+    ok: false;
+    reason: "not_found";
+} | {
+    ok: false;
+    reason: "ambiguous";
+    candidates: string[];
+};
+/**
+ * Resolve a handle hex (or a rendered token / bare form) to its memory id
+ * against the session's recent recall snapshots.
+ *
+ * @param handle     A handle token, bare hex, or `m:hex` form.
+ * @param snapshots  Recent recall snapshots for the session, newest first.
+ *                   Only the first `depth` entries are searched.
+ * @param depth      How many snapshots (newest-first) to search. Defaults to
+ *                   {@link DEFAULT_HANDLE_SNAPSHOT_DEPTH}.
+ */
+declare function resolveHandle(handle: string, snapshots: readonly RecallSnapshotIds[], depth?: number): ResolveHandleResult;
+/**
+ * Default snapshot lookback depth for handle resolution (issue #1582 config
+ * `recall.handleSnapshotDepth`). Older-than-N snapshots are not searched and a
+ * miss is tagged rather than widening the window.
+ */
+declare const DEFAULT_HANDLE_SNAPSHOT_DEPTH = 5;
+
+export { DEFAULT_HANDLE_SNAPSHOT_DEPTH, HANDLE_DEFAULT_WIDTH, HANDLE_EXTENDED_WIDTH, HANDLE_MAX_WIDTH, HANDLE_MIN_WIDTH, HANDLE_REGEX, type InjectionHandleEntry, MEMORY_ID_PATTERN, type ParsedIdOrHandle, type RecallSnapshotIds, type ResolveHandleResult, appendHandle, buildHandleIndexForResults, handleFor, isHandleToken, normalizeHandle, parseHandles, parseIdOrHandle, renderHandle, renderHandlesForInjection, resolveHandle, stripHandles };

package/dist/recall-handles.js

@@ -0,0 +1,42 @@
+import {
+  DEFAULT_HANDLE_SNAPSHOT_DEPTH,
+  HANDLE_DEFAULT_WIDTH,
+  HANDLE_EXTENDED_WIDTH,
+  HANDLE_MAX_WIDTH,
+  HANDLE_MIN_WIDTH,
+  HANDLE_REGEX,
+  MEMORY_ID_PATTERN,
+  appendHandle,
+  buildHandleIndexForResults,
+  handleFor,
+  isHandleToken,
+  normalizeHandle,
+  parseHandles,
+  parseIdOrHandle,
+  renderHandle,
+  renderHandlesForInjection,
+  resolveHandle,
+  stripHandles
+} from "./chunk-JAKIDQB2.js";
+import "./chunk-PZ5AY32C.js";
+export {
+  DEFAULT_HANDLE_SNAPSHOT_DEPTH,
+  HANDLE_DEFAULT_WIDTH,
+  HANDLE_EXTENDED_WIDTH,
+  HANDLE_MAX_WIDTH,
+  HANDLE_MIN_WIDTH,
+  HANDLE_REGEX,
+  MEMORY_ID_PATTERN,
+  appendHandle,
+  buildHandleIndexForResults,
+  handleFor,
+  isHandleToken,
+  normalizeHandle,
+  parseHandles,
+  parseIdOrHandle,
+  renderHandle,
+  renderHandlesForInjection,
+  resolveHandle,
+  stripHandles
+};
+//# sourceMappingURL=recall-handles.js.map

package/dist/recall-handles.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/recall-planner-llm.d.ts

@@ -1,4 +1,4 @@
-import { h as RecallPlanMode, P as PluginConfig } from './types-Dr0Cw3L9.js';
+import { h as RecallPlanMode, P as PluginConfig } from './types-D9dwzU_x.js';
 import { CapabilitySet } from './capabilities.js';
 import { FallbackLlmClient, FallbackLlmOptions } from './fallback-llm.js';
 import './types-gb_SNtjR.js';