@graphorin/memory 0.5.0 → 0.6.1

package/dist/tools/fact-tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"fact-tools.js","names":[],"sources":["../../src/tools/fact-tools.ts"],"sourcesContent":["import type { Tool } from '@graphorin/core';\nimport { tool } from '@graphorin/tools';\nimport { z } from 'zod';\nimport type { MemoryToolDeps } from './types.js';\n\nconst sensitivityEnum = z.enum(['public', 'internal', 'secret']);\nconst provenanceEnum = z.enum([\n  'user',\n  'tool',\n  'extraction',\n  'reflection',\n  'induction',\n  'imported',\n]);\n\nconst factRememberInputSchema = z.object({\n  text: z.string().min(1).max(8192),\n  tags: z.array(z.string().min(1).max(64)).max(32).optional(),\n  confidence: z.number().min(0).max(1).optional(),\n  sensitivity: sensitivityEnum.optional(),\n  validFrom: z.string().datetime().optional(),\n  validTo: z.string().datetime().optional(),\n});\nconst factRememberOutputSchema = z.object({\n  factId: z.string(),\n  /**\n   * MRET-3: `true` when the write landed in quarantine (hidden from\n   * default recall until validated). A synthesized consolidator write or\n   * a candidate that tripped the injection heuristics quarantines.\n   */\n  quarantined: z.boolean(),\n  /** Why it was quarantined, when it was. */\n  quarantineReason: z.enum(['injection', 'synthesized']).optional(),\n});\n\ntype FactRememberInput = z.infer<typeof factRememberInputSchema>;\ntype FactRememberOutput = z.infer<typeof factRememberOutputSchema>;\n\nconst factSearchInputSchema = z.object({\n  query: z.string().min(1).max(1024),\n  topK: z.number().int().positive().max(50).optional(),\n  tags: z.array(z.string().min(1)).max(16).optional(),\n  asOf: z.string().datetime().optional(),\n});\nconst factSearchOutputSchema = z.object({\n  hits: z.array(\n    z.object({\n      factId: z.string(),\n      text: z.string(),\n      score: z.number(),\n      sensitivity: sensitivityEnum,\n      provenance: provenanceEnum.optional(),\n    }),\n  ),\n});\n\ntype FactSearchInput = z.infer<typeof factSearchInputSchema>;\ntype FactSearchOutput = z.infer<typeof factSearchOutputSchema>;\n\nconst factSupersedeInputSchema = z.object({\n  oldId: z.string().min(1),\n  newText: z.string().min(1).max(8192),\n  reason: z.string().max(512).optional(),\n});\nconst factSupersedeOutputSchema = z.object({\n  oldId: z.string(),\n  newId: z.string(),\n});\n\ntype FactSupersedeInput = z.infer<typeof factSupersedeInputSchema>;\ntype FactSupersedeOutput = z.infer<typeof factSupersedeOutputSchema>;\n\nconst factForgetInputSchema = z.object({\n  factId: z.string().min(1),\n  reason: z.string().max(512).optional(),\n});\nconst factForgetOutputSchema = z.object({\n  factId: z.string(),\n  forgotten: z.boolean(),\n});\n\ntype FactForgetInput = z.infer<typeof factForgetInputSchema>;\ntype FactForgetOutput = z.infer<typeof factForgetOutputSchema>;\n\nconst factHistoryInputSchema = z.object({\n  factId: z.string().min(1),\n});\nconst factHistoryOutputSchema = z.object({\n  chain: z.array(\n    z.object({\n      factId: z.string(),\n      text: z.string(),\n      validFrom: z.string().optional(),\n      validTo: z.string().optional(),\n      supersedes: z.string().optional(),\n      supersededBy: z.string().optional(),\n      sensitivity: sensitivityEnum,\n    }),\n  ),\n});\n\ntype FactHistoryInput = z.infer<typeof factHistoryInputSchema>;\ntype FactHistoryOutput = z.infer<typeof factHistoryOutputSchema>;\n\nconst factValidateInputSchema = z.object({\n  factId: z.string().min(1),\n  reason: z.string().max(512).optional(),\n});\nconst factValidateOutputSchema = z.object({\n  factId: z.string(),\n  validated: z.boolean(),\n});\n\ntype FactValidateInput = z.infer<typeof factValidateInputSchema>;\ntype FactValidateOutput = z.infer<typeof factValidateOutputSchema>;\n\n/**\n * `fact_remember` — persist a single semantic fact. The minimum-viable\n * pipeline writes the fact straight through with MD5 deduplication;\n * Phase 10b extends the body with the multi-stage conflict resolution.\n *\n * @stable\n */\nexport function createFactRememberTool(\n  deps: MemoryToolDeps,\n): Tool<FactRememberInput, FactRememberOutput> {\n  return tool<FactRememberInput, FactRememberOutput>({\n    name: 'fact_remember',\n    description:\n      'Persist an atomic factual statement about the user, the world, or the current session. Prefer one fact per call; the system applies dedup + conflict resolution downstream. Pass `validFrom` / `validTo` for bi-temporal facts and `sensitivity` to control redaction.',\n    inputSchema: factRememberInputSchema,\n    outputSchema: factRememberOutputSchema,\n    sideEffectClass: 'side-effecting',\n    sandboxPolicy: 'none',\n    sensitivity: 'internal',\n    memoryGuardTier: 'memory-aware',\n    tags: ['memory', 'semantic'],\n    async execute(input, ctx) {\n      const scope = await deps.resolveScope(ctx);\n      const outcome = await deps.semantic.rememberWithDecision(scope, {\n        text: input.text,\n        ...(input.tags !== undefined ? { tags: input.tags } : {}),\n        ...(input.confidence !== undefined ? { confidence: input.confidence } : {}),\n        ...(input.sensitivity !== undefined ? { sensitivity: input.sensitivity } : {}),\n        ...(input.validFrom !== undefined ? { validFrom: input.validFrom } : {}),\n        ...(input.validTo !== undefined ? { validTo: input.validTo } : {}),\n      });\n      // MRET-3: tell the caller when the write was quarantined so a\n      // poisoned fact cannot masquerade as a normally-stored one.\n      return {\n        factId: outcome.fact.id,\n        quarantined: outcome.fact.status === 'quarantined',\n        ...(outcome.quarantineReason !== undefined\n          ? { quarantineReason: outcome.quarantineReason }\n          : {}),\n      };\n    },\n  });\n}\n\n/**\n * `fact_search` — hybrid (vector + FTS5) search over the user's\n * semantic memory. Results merged through the configured reranker.\n *\n * @stable\n */\nexport function createFactSearchTool(\n  deps: MemoryToolDeps,\n): Tool<FactSearchInput, FactSearchOutput> {\n  return tool<FactSearchInput, FactSearchOutput>({\n    name: 'fact_search',\n    description:\n      \"Search the user's long-term factual memory by natural-language query. Returns up to `topK` matched facts with their score and sensitivity. Use this BEFORE asking the user a question they may have answered earlier. Pass `asOf` (ISO-8601) to read memory as it was at a past instant — point-in-time / 'what was true on date X' — instead of the current state.\",\n    inputSchema: factSearchInputSchema,\n    outputSchema: factSearchOutputSchema,\n    sideEffectClass: 'read-only',\n    sandboxPolicy: 'none',\n    sensitivity: 'internal',\n    memoryGuardTier: 'pure',\n    tags: ['memory', 'semantic'],\n    async execute(input, ctx) {\n      const scope = await deps.resolveScope(ctx);\n      const hits = await deps.semantic.search(scope, input.query, {\n        ...(input.topK !== undefined ? { topK: input.topK } : {}),\n        // MRET-4: forward the tags filter — it was accepted by the\n        // schema and silently dropped here.\n        ...(input.tags !== undefined && input.tags.length > 0 ? { tags: input.tags } : {}),\n        ...(input.asOf !== undefined ? { asOf: input.asOf } : {}),\n        signal: ctx.signal,\n      });\n      return {\n        hits: hits.map((hit) => ({\n          factId: hit.record.id,\n          text: hit.record.text,\n          score: hit.score,\n          sensitivity: hit.record.sensitivity,\n          ...(hit.record.provenance !== undefined ? { provenance: hit.record.provenance } : {}),\n        })),\n      };\n    },\n  });\n}\n\n/**\n * `fact_supersede` — soft-supersede an old fact by storing a new one\n * that replaces it. The old fact is kept for replay but ranked below\n * the new one.\n *\n * @stable\n */\nexport function createFactSupersedeTool(\n  deps: MemoryToolDeps,\n): Tool<FactSupersedeInput, FactSupersedeOutput> {\n  return tool<FactSupersedeInput, FactSupersedeOutput>({\n    name: 'fact_supersede',\n    description:\n      \"Mark an old fact superseded by a new one. Use this when the user's situation changed (moved cities, updated a goal, switched a preference) — the old fact is preserved for replay but no longer surfaced as current.\",\n    inputSchema: factSupersedeInputSchema,\n    outputSchema: factSupersedeOutputSchema,\n    sideEffectClass: 'side-effecting',\n    sandboxPolicy: 'none',\n    sensitivity: 'internal',\n    memoryGuardTier: 'memory-aware',\n    tags: ['memory', 'semantic'],\n    async execute(input, ctx) {\n      const scope = await deps.resolveScope(ctx);\n      const result = await deps.semantic.supersede(\n        scope,\n        input.oldId,\n        { text: input.newText },\n        input.reason,\n      );\n      return { oldId: result.old, newId: result.new.id };\n    },\n  });\n}\n\n/**\n * `fact_forget` — soft-delete a fact (kept for replay; never hard-\n * deleted at this layer).\n *\n * @stable\n */\nexport function createFactForgetTool(\n  deps: MemoryToolDeps,\n): Tool<FactForgetInput, FactForgetOutput> {\n  return tool<FactForgetInput, FactForgetOutput>({\n    name: 'fact_forget',\n    description:\n      'Soft-delete a fact. The record is preserved for replay but no longer surfaced by fact_search. Use only for explicit user-driven removal (privacy / user request).',\n    inputSchema: factForgetInputSchema,\n    outputSchema: factForgetOutputSchema,\n    sideEffectClass: 'side-effecting',\n    sandboxPolicy: 'none',\n    sensitivity: 'internal',\n    memoryGuardTier: 'memory-aware',\n    tags: ['memory', 'semantic'],\n    async execute(input, ctx) {\n      const scope = await deps.resolveScope(ctx);\n      await deps.semantic.forget(scope, input.factId, input.reason);\n      return { factId: input.factId, forgotten: true };\n    },\n  });\n}\n\n/**\n * `fact_history` — trace how a fact changed over time. Returns the\n * full bi-temporal supersede chain the given fact belongs to, oldest →\n * newest, including superseded entries, so the agent can answer \"what\n * did the user say before\" / \"how did this change\". Read-only. P0-2.\n *\n * @stable\n */\nexport function createFactHistoryTool(\n  deps: MemoryToolDeps,\n): Tool<FactHistoryInput, FactHistoryOutput> {\n  return tool<FactHistoryInput, FactHistoryOutput>({\n    name: 'fact_history',\n    description:\n      \"Trace how a fact changed over time. Given a factId, returns its full bi-temporal supersede chain (oldest → newest), including superseded entries, with each entry's validFrom/validTo. Use this to answer 'how did this change' or 'what was the previous value'.\",\n    inputSchema: factHistoryInputSchema,\n    outputSchema: factHistoryOutputSchema,\n    sideEffectClass: 'read-only',\n    sandboxPolicy: 'none',\n    sensitivity: 'internal',\n    memoryGuardTier: 'pure',\n    tags: ['memory', 'semantic', 'temporal'],\n    async execute(input, ctx) {\n      const scope = await deps.resolveScope(ctx);\n      const chain = await deps.semantic.history(scope, input.factId);\n      return {\n        chain: chain.map((f) => ({\n          factId: f.id,\n          text: f.text,\n          ...(f.validFrom !== undefined ? { validFrom: f.validFrom } : {}),\n          ...(f.validTo !== undefined ? { validTo: f.validTo } : {}),\n          ...(f.supersedes !== undefined ? { supersedes: f.supersedes } : {}),\n          ...(f.supersededBy !== undefined ? { supersededBy: f.supersededBy } : {}),\n          sensitivity: f.sensitivity,\n        })),\n      };\n    },\n  });\n}\n\n/**\n * `fact_validate` — promote a quarantined fact to active (P1-4). The\n * validation path that admits a synthesized (consolidator / reflection)\n * memory into action-driving recall once it has been reviewed; the\n * promotion is audited in `memory_history`.\n *\n * MRET-3 / MST-1 — two gates close the one-turn memory-poisoning chain\n * (`fact_remember(poison)` → `fact_validate(id)` → active recall):\n *\n * 1. `needsApproval: true` — the run suspends for a human decision\n *    before this tool ever executes, so the agent cannot silently\n *    promote any quarantined fact.\n * 2. The underlying `SemanticMemory.validate(...)` re-checks the fact's\n *    text against the injection heuristics and **refuses** (no `force`\n *    is passed here) — an injection-flagged memory cannot be promoted by\n *    the agent at all. Only an operator, via the programmatic API with\n *    `{ force: true }`, can override after review.\n *\n * Synthesized-but-clean consolidator writes promote normally once\n * approved.\n *\n * @stable\n */\nexport function createFactValidateTool(\n  deps: MemoryToolDeps,\n): Tool<FactValidateInput, FactValidateOutput> {\n  return tool<FactValidateInput, FactValidateOutput>({\n    name: 'fact_validate',\n    description:\n      'Promote a quarantined fact to active so it becomes eligible for normal recall. Quarantined facts are memories the system synthesized or flagged as risky; validating one is a deliberate, human-approved admission and never a routine step. This action requires approval, and facts flagged as prompt-injection cannot be promoted here — they are an operator-only decision.',\n    inputSchema: factValidateInputSchema,\n    outputSchema: factValidateOutputSchema,\n    // MRET-3: the only real gate on a model-callable tool — suspend the\n    // run for a human decision before promoting anything out of quarantine.\n    needsApproval: true,\n    sideEffectClass: 'side-effecting',\n    sandboxPolicy: 'none',\n    sensitivity: 'internal',\n    memoryGuardTier: 'memory-aware',\n    tags: ['memory', 'semantic', 'safety'],\n    async execute(input, ctx) {\n      const scope = await deps.resolveScope(ctx);\n      // No `force`: the agent path can never promote an injection-flagged\n      // fact (validate throws QuarantinePromotionRefusedError for those).\n      await deps.semantic.validate(scope, input.factId, input.reason);\n      return { factId: input.factId, validated: true };\n    },\n  });\n}\n"],"mappings":"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"}
+{"version":3,"file":"fact-tools.js","names":[],"sources":["../../src/tools/fact-tools.ts"],"sourcesContent":["import type { Tool } from '@graphorin/core';\nimport { tool } from '@graphorin/tools';\nimport { z } from 'zod';\nimport { recallTaint } from './taint.js';\nimport type { MemoryToolDeps } from './types.js';\n\nconst sensitivityEnum = z.enum(['public', 'internal', 'secret']);\nconst provenanceEnum = z.enum([\n  'user',\n  'tool',\n  'extraction',\n  'reflection',\n  'induction',\n  'imported',\n]);\n\nconst factRememberInputSchema = z.object({\n  text: z.string().min(1).max(8192),\n  tags: z.array(z.string().min(1).max(64)).max(32).optional(),\n  confidence: z.number().min(0).max(1).optional(),\n  sensitivity: sensitivityEnum.optional(),\n  validFrom: z.string().datetime().optional(),\n  validTo: z.string().datetime().optional(),\n});\nconst factRememberOutputSchema = z.object({\n  factId: z.string(),\n  /**\n   * MRET-3: `true` when the write landed in quarantine (hidden from\n   * default recall until validated). A synthesized consolidator write or\n   * a candidate that tripped the injection heuristics quarantines.\n   */\n  quarantined: z.boolean(),\n  /** Why it was quarantined, when it was. */\n  quarantineReason: z.enum(['injection', 'synthesized']).optional(),\n});\n\ntype FactRememberInput = z.infer<typeof factRememberInputSchema>;\ntype FactRememberOutput = z.infer<typeof factRememberOutputSchema>;\n\nconst factSearchInputSchema = z.object({\n  query: z.string().min(1).max(1024),\n  topK: z.number().int().positive().max(50).optional(),\n  tags: z.array(z.string().min(1)).max(16).optional(),\n  asOf: z.string().datetime().optional(),\n});\nconst factSearchOutputSchema = z.object({\n  hits: z.array(\n    z.object({\n      factId: z.string(),\n      text: z.string(),\n      score: z.number(),\n      sensitivity: sensitivityEnum,\n      provenance: provenanceEnum.optional(),\n      /**\n       * Set when the fact's validity interval was closed (superseded /\n       * expired). Only present on `asOf` reads - default reads exclude\n       * such facts entirely (memory-retrieval-01).\n       */\n      validTo: z.string().optional(),\n      /** Id of the fact that superseded this one, when any. */\n      supersededBy: z.string().optional(),\n    }),\n  ),\n});\n\ntype FactSearchInput = z.infer<typeof factSearchInputSchema>;\ntype FactSearchOutput = z.infer<typeof factSearchOutputSchema>;\n\nconst factSupersedeInputSchema = z.object({\n  oldId: z.string().min(1),\n  newText: z.string().min(1).max(8192),\n  reason: z.string().max(512).optional(),\n});\nconst factSupersedeOutputSchema = z.object({\n  oldId: z.string(),\n  newId: z.string(),\n});\n\ntype FactSupersedeInput = z.infer<typeof factSupersedeInputSchema>;\ntype FactSupersedeOutput = z.infer<typeof factSupersedeOutputSchema>;\n\nconst factForgetInputSchema = z.object({\n  factId: z.string().min(1),\n  reason: z.string().max(512).optional(),\n});\nconst factForgetOutputSchema = z.object({\n  factId: z.string(),\n  forgotten: z.boolean(),\n});\n\ntype FactForgetInput = z.infer<typeof factForgetInputSchema>;\ntype FactForgetOutput = z.infer<typeof factForgetOutputSchema>;\n\nconst factHistoryInputSchema = z.object({\n  factId: z.string().min(1),\n});\nconst factHistoryOutputSchema = z.object({\n  chain: z.array(\n    z.object({\n      factId: z.string(),\n      text: z.string(),\n      validFrom: z.string().optional(),\n      validTo: z.string().optional(),\n      supersedes: z.string().optional(),\n      supersededBy: z.string().optional(),\n      sensitivity: sensitivityEnum,\n    }),\n  ),\n});\n\ntype FactHistoryInput = z.infer<typeof factHistoryInputSchema>;\ntype FactHistoryOutput = z.infer<typeof factHistoryOutputSchema>;\n\nconst factValidateInputSchema = z.object({\n  factId: z.string().min(1),\n  reason: z.string().max(512).optional(),\n});\nconst factValidateOutputSchema = z.object({\n  factId: z.string(),\n  validated: z.boolean(),\n});\n\ntype FactValidateInput = z.infer<typeof factValidateInputSchema>;\ntype FactValidateOutput = z.infer<typeof factValidateOutputSchema>;\n\n/**\n * `fact_remember` - persist a single semantic fact. The minimum-viable\n * pipeline writes the fact straight through with MD5 deduplication;\n * Phase 10b extends the body with the multi-stage conflict resolution.\n *\n * @stable\n */\nexport function createFactRememberTool(\n  deps: MemoryToolDeps,\n): Tool<FactRememberInput, FactRememberOutput> {\n  return tool<FactRememberInput, FactRememberOutput>({\n    name: 'fact_remember',\n    description:\n      'Persist an atomic factual statement about the user, the world, or the current session. Prefer one fact per call; the system applies dedup + conflict resolution downstream. Pass `validFrom` / `validTo` for bi-temporal facts and `sensitivity` to control redaction.',\n    inputSchema: factRememberInputSchema,\n    outputSchema: factRememberOutputSchema,\n    sideEffectClass: 'side-effecting',\n    sandboxPolicy: 'none',\n    sensitivity: 'internal',\n    memoryGuardTier: 'memory-aware',\n    tags: ['memory', 'semantic'],\n    async execute(input, ctx) {\n      const scope = await deps.resolveScope(ctx);\n      const outcome = await deps.semantic.rememberWithDecision(scope, {\n        text: input.text,\n        ...(input.tags !== undefined ? { tags: input.tags } : {}),\n        ...(input.confidence !== undefined ? { confidence: input.confidence } : {}),\n        ...(input.sensitivity !== undefined ? { sensitivity: input.sensitivity } : {}),\n        ...(input.validFrom !== undefined ? { validFrom: input.validFrom } : {}),\n        ...(input.validTo !== undefined ? { validTo: input.validTo } : {}),\n      });\n      // MRET-3: tell the caller when the write was quarantined so a\n      // poisoned fact cannot masquerade as a normally-stored one.\n      return {\n        factId: outcome.fact.id,\n        quarantined: outcome.fact.status === 'quarantined',\n        ...(outcome.quarantineReason !== undefined\n          ? { quarantineReason: outcome.quarantineReason }\n          : {}),\n      };\n    },\n  });\n}\n\n/**\n * `fact_search` - hybrid (vector + FTS5) search over the user's\n * semantic memory. Results merged through the configured reranker.\n *\n * @stable\n */\nexport function createFactSearchTool(\n  deps: MemoryToolDeps,\n): Tool<FactSearchInput, FactSearchOutput> {\n  return tool<FactSearchInput, FactSearchOutput>({\n    name: 'fact_search',\n    description:\n      \"Search the user's long-term factual memory by natural-language query. Returns up to `topK` matched facts with their score and sensitivity. Use this BEFORE asking the user a question they may have answered earlier. Pass `asOf` (ISO-8601) to read memory as it was at a past instant - point-in-time / 'what was true on date X' - instead of the current state.\",\n    inputSchema: factSearchInputSchema,\n    outputSchema: factSearchOutputSchema,\n    sideEffectClass: 'read-only',\n    sandboxPolicy: 'none',\n    sensitivity: 'internal',\n    memoryGuardTier: 'pure',\n    tags: ['memory', 'semantic'],\n    async execute(input, ctx) {\n      const scope = await deps.resolveScope(ctx);\n      const hits = await deps.semantic.search(scope, input.query, {\n        ...(input.topK !== undefined ? { topK: input.topK } : {}),\n        // MRET-4: forward the tags filter - it was accepted by the\n        // schema and silently dropped here.\n        ...(input.tags !== undefined && input.tags.length > 0 ? { tags: input.tags } : {}),\n        ...(input.asOf !== undefined ? { asOf: input.asOf } : {}),\n        signal: ctx.signal,\n      });\n      const output = {\n        hits: hits.map((hit) => ({\n          factId: hit.record.id,\n          text: hit.record.text,\n          score: hit.score,\n          sensitivity: hit.record.sensitivity,\n          ...(hit.record.provenance !== undefined ? { provenance: hit.record.provenance } : {}),\n          // memory-retrieval-01: surface validity metadata so the model\n          // can tell a historical (asOf) hit from a current one.\n          ...(hit.record.validTo !== undefined ? { validTo: hit.record.validTo } : {}),\n          ...(hit.record.supersededBy !== undefined\n            ? { supersededBy: hit.record.supersededBy }\n            : {}),\n        })),\n      };\n      // C6: recalled quarantined / foreign-provenance content re-arms the\n      // taint ledger - the cross-session poisoning leg.\n      const taint = recallTaint(hits.map((h) => h.record));\n      return taint === undefined ? output : { output, taint };\n    },\n  });\n}\n\n/**\n * `fact_supersede` - soft-supersede an old fact by storing a new one\n * that replaces it. The old fact is kept for replay but no longer\n * surfaced by default reads (they evaluate validity at NOW); it stays\n * reachable via `asOf` / inspector paths.\n *\n * @stable\n */\nexport function createFactSupersedeTool(\n  deps: MemoryToolDeps,\n): Tool<FactSupersedeInput, FactSupersedeOutput> {\n  return tool<FactSupersedeInput, FactSupersedeOutput>({\n    name: 'fact_supersede',\n    description:\n      \"Mark an old fact superseded by a new one. Use this when the user's situation changed (moved cities, updated a goal, switched a preference) - the old fact is preserved for replay but no longer surfaced as current.\",\n    inputSchema: factSupersedeInputSchema,\n    outputSchema: factSupersedeOutputSchema,\n    sideEffectClass: 'side-effecting',\n    sandboxPolicy: 'none',\n    sensitivity: 'internal',\n    memoryGuardTier: 'memory-aware',\n    tags: ['memory', 'semantic'],\n    async execute(input, ctx) {\n      const scope = await deps.resolveScope(ctx);\n      const result = await deps.semantic.supersede(\n        scope,\n        input.oldId,\n        { text: input.newText },\n        input.reason,\n      );\n      return { oldId: result.old, newId: result.new.id };\n    },\n  });\n}\n\n/**\n * `fact_forget` - soft-delete a fact (kept for replay; never hard-\n * deleted at this layer).\n *\n * @stable\n */\nexport function createFactForgetTool(\n  deps: MemoryToolDeps,\n): Tool<FactForgetInput, FactForgetOutput> {\n  return tool<FactForgetInput, FactForgetOutput>({\n    name: 'fact_forget',\n    description:\n      'Soft-delete a fact. The record is preserved for replay but no longer surfaced by fact_search. Use only for explicit user-driven removal (privacy / user request).',\n    inputSchema: factForgetInputSchema,\n    outputSchema: factForgetOutputSchema,\n    sideEffectClass: 'side-effecting',\n    sandboxPolicy: 'none',\n    sensitivity: 'internal',\n    memoryGuardTier: 'memory-aware',\n    tags: ['memory', 'semantic'],\n    async execute(input, ctx) {\n      const scope = await deps.resolveScope(ctx);\n      await deps.semantic.forget(scope, input.factId, input.reason);\n      return { factId: input.factId, forgotten: true };\n    },\n  });\n}\n\n/**\n * `fact_history` - trace how a fact changed over time. Returns the\n * full bi-temporal supersede chain the given fact belongs to, oldest →\n * newest, including superseded entries, so the agent can answer \"what\n * did the user say before\" / \"how did this change\". Read-only. P0-2.\n *\n * @stable\n */\nexport function createFactHistoryTool(\n  deps: MemoryToolDeps,\n): Tool<FactHistoryInput, FactHistoryOutput> {\n  return tool<FactHistoryInput, FactHistoryOutput>({\n    name: 'fact_history',\n    description:\n      \"Trace how a fact changed over time. Given a factId, returns its full bi-temporal supersede chain (oldest → newest), including superseded entries, with each entry's validFrom/validTo. Use this to answer 'how did this change' or 'what was the previous value'.\",\n    inputSchema: factHistoryInputSchema,\n    outputSchema: factHistoryOutputSchema,\n    sideEffectClass: 'read-only',\n    sandboxPolicy: 'none',\n    sensitivity: 'internal',\n    memoryGuardTier: 'pure',\n    tags: ['memory', 'semantic', 'temporal'],\n    async execute(input, ctx) {\n      const scope = await deps.resolveScope(ctx);\n      const chain = await deps.semantic.history(scope, input.factId);\n      return {\n        chain: chain.map((f) => ({\n          factId: f.id,\n          text: f.text,\n          ...(f.validFrom !== undefined ? { validFrom: f.validFrom } : {}),\n          ...(f.validTo !== undefined ? { validTo: f.validTo } : {}),\n          ...(f.supersedes !== undefined ? { supersedes: f.supersedes } : {}),\n          ...(f.supersededBy !== undefined ? { supersededBy: f.supersededBy } : {}),\n          sensitivity: f.sensitivity,\n        })),\n      };\n    },\n  });\n}\n\n/**\n * `fact_validate` - promote a quarantined fact to active (P1-4). The\n * validation path that admits a synthesized (consolidator / reflection)\n * memory into action-driving recall once it has been reviewed; the\n * promotion is audited in `memory_history`.\n *\n * MRET-3 / MST-1 - two gates close the one-turn memory-poisoning chain\n * (`fact_remember(poison)` → `fact_validate(id)` → active recall):\n *\n * 1. `needsApproval: true` - the run suspends for a human decision\n *    before this tool ever executes, so the agent cannot silently\n *    promote any quarantined fact.\n * 2. The underlying `SemanticMemory.validate(...)` re-checks the fact's\n *    text against the injection heuristics and **refuses** (no `force`\n *    is passed here) - an injection-flagged memory cannot be promoted by\n *    the agent at all. Only an operator, via the programmatic API with\n *    `{ force: true }`, can override after review.\n *\n * Synthesized-but-clean consolidator writes promote normally once\n * approved.\n *\n * @stable\n */\nexport function createFactValidateTool(\n  deps: MemoryToolDeps,\n): Tool<FactValidateInput, FactValidateOutput> {\n  return tool<FactValidateInput, FactValidateOutput>({\n    name: 'fact_validate',\n    description:\n      'Promote a quarantined fact to active so it becomes eligible for normal recall. Quarantined facts are memories the system synthesized or flagged as risky; validating one is a deliberate, human-approved admission and never a routine step. This action requires approval, and facts flagged as prompt-injection cannot be promoted here - they are an operator-only decision.',\n    inputSchema: factValidateInputSchema,\n    outputSchema: factValidateOutputSchema,\n    // MRET-3: the only real gate on a model-callable tool - suspend the\n    // run for a human decision before promoting anything out of quarantine.\n    needsApproval: true,\n    sideEffectClass: 'side-effecting',\n    sandboxPolicy: 'none',\n    sensitivity: 'internal',\n    memoryGuardTier: 'memory-aware',\n    tags: ['memory', 'semantic', 'safety'],\n    async execute(input, ctx) {\n      const scope = await deps.resolveScope(ctx);\n      // No `force`: the agent path can never promote an injection-flagged\n      // fact (validate throws QuarantinePromotionRefusedError for those).\n      await deps.semantic.validate(scope, input.factId, input.reason);\n      return { factId: input.factId, validated: true };\n    },\n  });\n}\n"],"mappings":"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"}

package/dist/tools/index.d.ts

@@ -2,6 +2,7 @@ import { MemoryToolDeps, ScopeResolver } from "./types.js";
 import { createBlockAppendTool, createBlockReplaceTool, createBlockRethinkTool } from "./block-tools.js";
 import { createFactForgetTool, createFactHistoryTool, createFactRememberTool, createFactSearchTool, createFactSupersedeTool, createFactValidateTool } from "./fact-tools.js";
 import { createConversationSearchTool, createDeepRecallTool, createRecallEpisodesTool } from "./recall-tools.js";
+import { createRunbookSearchTool } from "./runbook-tools.js";
 import { Tool } from "@graphorin/core";
 
 //#region src/tools/index.d.ts
@@ -18,9 +19,15 @@ interface BuildMemoryToolsOptions {
    * default tool surface stays at the canonical eleven. Default `false`.
    */
   readonly includeDeepRecall?: boolean;
+  /**
+   * Append the gated `runbook_search` tool (D3). The facade sets this
+   * only when `createMemory({ runbookSearch: true })` opts in, so the
+   * default tool surface is unchanged. Default `false`.
+   */
+  readonly includeRunbookSearch?: boolean;
 }
 /**
- * Build the canonical eleven-memory-tool array. Order is stable —
+ * Build the canonical eleven-memory-tool array. Order is stable -
  * consumers can rely on the indices for snapshot tests. `fact_history`
  * (P0-2) and `fact_validate` (P1-4) are appended last so the original
  * nine indices are unchanged. With `{ includeDeepRecall: true }` the
@@ -31,5 +38,5 @@ interface BuildMemoryToolsOptions {
  */
 declare function buildMemoryTools(deps: MemoryToolDeps, options?: BuildMemoryToolsOptions): ReadonlyArray<Tool>;
 //#endregion
-export { BuildMemoryToolsOptions, type MemoryToolDeps, type ScopeResolver, buildMemoryTools, createBlockAppendTool, createBlockReplaceTool, createBlockRethinkTool, createConversationSearchTool, createDeepRecallTool, createFactForgetTool, createFactHistoryTool, createFactRememberTool, createFactSearchTool, createFactSupersedeTool, createFactValidateTool, createRecallEpisodesTool };
+export { BuildMemoryToolsOptions, type MemoryToolDeps, type ScopeResolver, buildMemoryTools, createBlockAppendTool, createBlockReplaceTool, createBlockRethinkTool, createConversationSearchTool, createDeepRecallTool, createFactForgetTool, createFactHistoryTool, createFactRememberTool, createFactSearchTool, createFactSupersedeTool, createFactValidateTool, createRecallEpisodesTool, createRunbookSearchTool };
 //# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/tools/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;UAyDiB,uBAAA;;;;;;;;;;;;;;;;;;iBAmBD,gBAAA,OACR,0BACG,0BACR,cAAc"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/tools/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;UA2DiB,uBAAA;;;;;;;;;;;;;;;;;;;;;;;;iBAyBD,gBAAA,OACR,0BACG,0BACR,cAAc"}

package/dist/tools/index.js

@@ -1,10 +1,11 @@
 import { createBlockAppendTool, createBlockReplaceTool, createBlockRethinkTool } from "./block-tools.js";
 import { createFactForgetTool, createFactHistoryTool, createFactRememberTool, createFactSearchTool, createFactSupersedeTool, createFactValidateTool } from "./fact-tools.js";
 import { createConversationSearchTool, createDeepRecallTool, createRecallEpisodesTool } from "./recall-tools.js";
+import { createRunbookSearchTool } from "./runbook-tools.js";
 
 //#region src/tools/index.ts
 /**
-* Build the canonical eleven-memory-tool array. Order is stable —
+* Build the canonical eleven-memory-tool array. Order is stable -
 * consumers can rely on the indices for snapshot tests. `fact_history`
 * (P0-2) and `fact_validate` (P1-4) are appended last so the original
 * nine indices are unchanged. With `{ includeDeepRecall: true }` the
@@ -28,9 +29,10 @@ function buildMemoryTools(deps, options = {}) {
 		createFactValidateTool(deps)
 	];
 	if (options.includeDeepRecall === true) tools.push(createDeepRecallTool(deps));
+	if (options.includeRunbookSearch === true) tools.push(createRunbookSearchTool(deps));
 	return Object.freeze(tools);
 }
 
 //#endregion
-export { buildMemoryTools, createBlockAppendTool, createBlockReplaceTool, createBlockRethinkTool, createConversationSearchTool, createDeepRecallTool, createFactForgetTool, createFactHistoryTool, createFactRememberTool, createFactSearchTool, createFactSupersedeTool, createFactValidateTool, createRecallEpisodesTool };
+export { buildMemoryTools, createBlockAppendTool, createBlockReplaceTool, createBlockRethinkTool, createConversationSearchTool, createDeepRecallTool, createFactForgetTool, createFactHistoryTool, createFactRememberTool, createFactSearchTool, createFactSupersedeTool, createFactValidateTool, createRecallEpisodesTool, createRunbookSearchTool };
 //# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["tools: Tool[]"],"sources":["../../src/tools/index.ts"],"sourcesContent":["/**\n * Eleven memory tools registered with `@graphorin/tools` by the\n * `createMemory()` facade — plus an opt-in twelfth, `deep_recall` (P2-4),\n * appended only when iterative retrieval is configured. Each factory\n * takes a {@link MemoryToolDeps} bundle so consumers can scope the tool\n * surface (per-tier ACL, scope resolver, etc.) without rebuilding the\n * underlying memory facade.\n *\n * @packageDocumentation\n */\n\nimport type { Tool } from '@graphorin/core';\nimport {\n  createBlockAppendTool,\n  createBlockReplaceTool,\n  createBlockRethinkTool,\n} from './block-tools.js';\nimport {\n  createFactForgetTool,\n  createFactHistoryTool,\n  createFactRememberTool,\n  createFactSearchTool,\n  createFactSupersedeTool,\n  createFactValidateTool,\n} from './fact-tools.js';\nimport {\n  createConversationSearchTool,\n  createDeepRecallTool,\n  createRecallEpisodesTool,\n} from './recall-tools.js';\nimport type { MemoryToolDeps } from './types.js';\n\nexport {\n  createBlockAppendTool,\n  createBlockReplaceTool,\n  createBlockRethinkTool,\n} from './block-tools.js';\nexport {\n  createFactForgetTool,\n  createFactHistoryTool,\n  createFactRememberTool,\n  createFactSearchTool,\n  createFactSupersedeTool,\n  createFactValidateTool,\n} from './fact-tools.js';\nexport {\n  createConversationSearchTool,\n  createDeepRecallTool,\n  createRecallEpisodesTool,\n} from './recall-tools.js';\nexport type { MemoryToolDeps, ScopeResolver } from './types.js';\n\n/**\n * Options for {@link buildMemoryTools}.\n *\n * @stable\n */\nexport interface BuildMemoryToolsOptions {\n  /**\n   * Append the gated `deep_recall` tool (P2-4) as a twelfth tool. The\n   * facade sets this only when `iterativeRetrieval` is configured, so the\n   * default tool surface stays at the canonical eleven. Default `false`.\n   */\n  readonly includeDeepRecall?: boolean;\n}\n\n/**\n * Build the canonical eleven-memory-tool array. Order is stable —\n * consumers can rely on the indices for snapshot tests. `fact_history`\n * (P0-2) and `fact_validate` (P1-4) are appended last so the original\n * nine indices are unchanged. With `{ includeDeepRecall: true }` the\n * gated `deep_recall` tool (P2-4) is appended as a twelfth, after the\n * stable eleven.\n *\n * @stable\n */\nexport function buildMemoryTools(\n  deps: MemoryToolDeps,\n  options: BuildMemoryToolsOptions = {},\n): ReadonlyArray<Tool> {\n  const tools: Tool[] = [\n    createBlockAppendTool(deps) as Tool,\n    createBlockReplaceTool(deps) as Tool,\n    createBlockRethinkTool(deps) as Tool,\n    createFactRememberTool(deps) as Tool,\n    createFactSearchTool(deps) as Tool,\n    createFactSupersedeTool(deps) as Tool,\n    createFactForgetTool(deps) as Tool,\n    createRecallEpisodesTool(deps) as Tool,\n    createConversationSearchTool(deps) as Tool,\n    createFactHistoryTool(deps) as Tool,\n    createFactValidateTool(deps) as Tool,\n  ];\n  if (options.includeDeepRecall === true) {\n    tools.push(createDeepRecallTool(deps) as Tool);\n  }\n  return Object.freeze(tools);\n}\n"],"mappings":";;;;;;;;;;;;;;;AA4EA,SAAgB,iBACd,MACA,UAAmC,EAAE,EAChB;CACrB,MAAMA,QAAgB;EACpB,sBAAsB,KAAK;EAC3B,uBAAuB,KAAK;EAC5B,uBAAuB,KAAK;EAC5B,uBAAuB,KAAK;EAC5B,qBAAqB,KAAK;EAC1B,wBAAwB,KAAK;EAC7B,qBAAqB,KAAK;EAC1B,yBAAyB,KAAK;EAC9B,6BAA6B,KAAK;EAClC,sBAAsB,KAAK;EAC3B,uBAAuB,KAAK;EAC7B;AACD,KAAI,QAAQ,sBAAsB,KAChC,OAAM,KAAK,qBAAqB,KAAK,CAAS;AAEhD,QAAO,OAAO,OAAO,MAAM"}
+{"version":3,"file":"index.js","names":["tools: Tool[]"],"sources":["../../src/tools/index.ts"],"sourcesContent":["/**\n * Eleven memory tools registered with `@graphorin/tools` by the\n * `createMemory()` facade - plus an opt-in twelfth, `deep_recall` (P2-4),\n * appended only when iterative retrieval is configured. Each factory\n * takes a {@link MemoryToolDeps} bundle so consumers can scope the tool\n * surface (per-tier ACL, scope resolver, etc.) without rebuilding the\n * underlying memory facade.\n *\n * @packageDocumentation\n */\n\nimport type { Tool } from '@graphorin/core';\nimport {\n  createBlockAppendTool,\n  createBlockReplaceTool,\n  createBlockRethinkTool,\n} from './block-tools.js';\nimport {\n  createFactForgetTool,\n  createFactHistoryTool,\n  createFactRememberTool,\n  createFactSearchTool,\n  createFactSupersedeTool,\n  createFactValidateTool,\n} from './fact-tools.js';\nimport {\n  createConversationSearchTool,\n  createDeepRecallTool,\n  createRecallEpisodesTool,\n} from './recall-tools.js';\nimport { createRunbookSearchTool } from './runbook-tools.js';\nimport type { MemoryToolDeps } from './types.js';\n\nexport {\n  createBlockAppendTool,\n  createBlockReplaceTool,\n  createBlockRethinkTool,\n} from './block-tools.js';\nexport {\n  createFactForgetTool,\n  createFactHistoryTool,\n  createFactRememberTool,\n  createFactSearchTool,\n  createFactSupersedeTool,\n  createFactValidateTool,\n} from './fact-tools.js';\nexport {\n  createConversationSearchTool,\n  createDeepRecallTool,\n  createRecallEpisodesTool,\n} from './recall-tools.js';\nexport { createRunbookSearchTool } from './runbook-tools.js';\nexport type { MemoryToolDeps, ScopeResolver } from './types.js';\n\n/**\n * Options for {@link buildMemoryTools}.\n *\n * @stable\n */\nexport interface BuildMemoryToolsOptions {\n  /**\n   * Append the gated `deep_recall` tool (P2-4) as a twelfth tool. The\n   * facade sets this only when `iterativeRetrieval` is configured, so the\n   * default tool surface stays at the canonical eleven. Default `false`.\n   */\n  readonly includeDeepRecall?: boolean;\n  /**\n   * Append the gated `runbook_search` tool (D3). The facade sets this\n   * only when `createMemory({ runbookSearch: true })` opts in, so the\n   * default tool surface is unchanged. Default `false`.\n   */\n  readonly includeRunbookSearch?: boolean;\n}\n\n/**\n * Build the canonical eleven-memory-tool array. Order is stable -\n * consumers can rely on the indices for snapshot tests. `fact_history`\n * (P0-2) and `fact_validate` (P1-4) are appended last so the original\n * nine indices are unchanged. With `{ includeDeepRecall: true }` the\n * gated `deep_recall` tool (P2-4) is appended as a twelfth, after the\n * stable eleven.\n *\n * @stable\n */\nexport function buildMemoryTools(\n  deps: MemoryToolDeps,\n  options: BuildMemoryToolsOptions = {},\n): ReadonlyArray<Tool> {\n  const tools: Tool[] = [\n    createBlockAppendTool(deps) as Tool,\n    createBlockReplaceTool(deps) as Tool,\n    createBlockRethinkTool(deps) as Tool,\n    createFactRememberTool(deps) as Tool,\n    createFactSearchTool(deps) as Tool,\n    createFactSupersedeTool(deps) as Tool,\n    createFactForgetTool(deps) as Tool,\n    createRecallEpisodesTool(deps) as Tool,\n    createConversationSearchTool(deps) as Tool,\n    createFactHistoryTool(deps) as Tool,\n    createFactValidateTool(deps) as Tool,\n  ];\n  if (options.includeDeepRecall === true) {\n    tools.push(createDeepRecallTool(deps) as Tool);\n  }\n  if (options.includeRunbookSearch === true) {\n    tools.push(createRunbookSearchTool(deps) as Tool);\n  }\n  return Object.freeze(tools);\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAoFA,SAAgB,iBACd,MACA,UAAmC,EAAE,EAChB;CACrB,MAAMA,QAAgB;EACpB,sBAAsB,KAAK;EAC3B,uBAAuB,KAAK;EAC5B,uBAAuB,KAAK;EAC5B,uBAAuB,KAAK;EAC5B,qBAAqB,KAAK;EAC1B,wBAAwB,KAAK;EAC7B,qBAAqB,KAAK;EAC1B,yBAAyB,KAAK;EAC9B,6BAA6B,KAAK;EAClC,sBAAsB,KAAK;EAC3B,uBAAuB,KAAK;EAC7B;AACD,KAAI,QAAQ,sBAAsB,KAChC,OAAM,KAAK,qBAAqB,KAAK,CAAS;AAEhD,KAAI,QAAQ,yBAAyB,KACnC,OAAM,KAAK,wBAAwB,KAAK,CAAS;AAEnD,QAAO,OAAO,OAAO,MAAM"}

package/dist/tools/recall-tools.d.ts

@@ -38,37 +38,37 @@ declare const recallEpisodesOutputSchema: z.ZodObject<{
     score: z.ZodNumber;
     startedAt: z.ZodString;
     endedAt: z.ZodString;
-    /** Trust-provenance tag (MST-10) — synthesized episodes say so. */
+    /** Trust-provenance tag (MST-10) - synthesized episodes say so. */
     provenance: z.ZodOptional<z.ZodString>;
   }, "strip", z.ZodTypeAny, {
+    score: number;
     episodeId: string;
     summary: string;
-    score: number;
     startedAt: string;
     endedAt: string;
     provenance?: string | undefined;
   }, {
+    score: number;
     episodeId: string;
     summary: string;
-    score: number;
     startedAt: string;
     endedAt: string;
     provenance?: string | undefined;
   }>, "many">;
 }, "strip", z.ZodTypeAny, {
   episodes: {
+    score: number;
     episodeId: string;
     summary: string;
-    score: number;
     startedAt: string;
     endedAt: string;
     provenance?: string | undefined;
   }[];
 }, {
   episodes: {
+    score: number;
     episodeId: string;
     summary: string;
-    score: number;
     startedAt: string;
     endedAt: string;
     provenance?: string | undefined;
@@ -118,13 +118,13 @@ declare const deepRecallInputSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
   query: string;
   topK?: number | undefined;
-  maxIterations?: number | undefined;
   asOf?: string | undefined;
+  maxIterations?: number | undefined;
 }, {
   query: string;
   topK?: number | undefined;
-  maxIterations?: number | undefined;
   asOf?: string | undefined;
+  maxIterations?: number | undefined;
 }>;
 declare const deepRecallOutputSchema: z.ZodObject<{
   hits: z.ZodArray<z.ZodObject<{
@@ -132,71 +132,91 @@ declare const deepRecallOutputSchema: z.ZodObject<{
     text: z.ZodString;
     score: z.ZodNumber;
     sensitivity: z.ZodEnum<["public", "internal", "secret"]>;
-    /** Trust-provenance tag (MST-10) — synthesized facts say so. */
+    /** Trust-provenance tag (MST-10) - synthesized facts say so. */
     provenance: z.ZodOptional<z.ZodString>;
+    /** Closed validity end (only surfaces on `asOf` reads). */
+    validTo: z.ZodOptional<z.ZodString>;
+    /** Id of the fact that superseded this one, when any. */
+    supersededBy: z.ZodOptional<z.ZodString>;
   }, "strip", z.ZodTypeAny, {
-    score: number;
-    factId: string;
     text: string;
+    score: number;
     sensitivity: "public" | "internal" | "secret";
+    factId: string;
+    validTo?: string | undefined;
     provenance?: string | undefined;
+    supersededBy?: string | undefined;
   }, {
-    score: number;
-    factId: string;
     text: string;
+    score: number;
     sensitivity: "public" | "internal" | "secret";
+    factId: string;
+    validTo?: string | undefined;
     provenance?: string | undefined;
+    supersededBy?: string | undefined;
   }>, "many">;
   sufficient: z.ZodBoolean;
   abstained: z.ZodBoolean;
+  /**
+   * Whether the grader actually judged sufficiency
+   * (memory-retrieval-02). When `false`, `sufficient: true` is a
+   * default, not a verdict.
+   */
+  graded: z.ZodBoolean;
   iterations: z.ZodNumber;
 }, "strip", z.ZodTypeAny, {
   hits: {
-    score: number;
-    factId: string;
     text: string;
+    score: number;
     sensitivity: "public" | "internal" | "secret";
+    factId: string;
+    validTo?: string | undefined;
     provenance?: string | undefined;
+    supersededBy?: string | undefined;
   }[];
   sufficient: boolean;
   abstained: boolean;
+  graded: boolean;
   iterations: number;
 }, {
   hits: {
-    score: number;
-    factId: string;
     text: string;
+    score: number;
     sensitivity: "public" | "internal" | "secret";
+    factId: string;
+    validTo?: string | undefined;
     provenance?: string | undefined;
+    supersededBy?: string | undefined;
   }[];
   sufficient: boolean;
   abstained: boolean;
+  graded: boolean;
   iterations: number;
 }>;
 type DeepRecallInput = z.infer<typeof deepRecallInputSchema>;
 type DeepRecallOutput = z.infer<typeof deepRecallOutputSchema>;
 /**
- * `recall_episodes` — triple-signal episode retrieval (recency ×
+ * `recall_episodes` - triple-signal episode retrieval (recency ×
  * relevance × importance).
  *
  * @stable
  */
 declare function createRecallEpisodesTool(deps: MemoryToolDeps): Tool<RecallEpisodesInput, RecallEpisodesOutput>;
 /**
- * `conversation_search` — FTS5 search over the active session
+ * `conversation_search` - FTS5 search over the active session
  * messages.
  *
  * @stable
  */
 declare function createConversationSearchTool(deps: MemoryToolDeps): Tool<ConversationSearchInput, ConversationSearchOutput>;
 /**
- * `deep_recall` — gated, multi-pass ("deep") recall over the user's
+ * `deep_recall` - gated, multi-pass ("deep") recall over the user's
  * factual memory for HARD questions (P2-4). A local difficulty gate keeps
  * simple lookups single-shot; only queries judged hard trigger a
  * grade-and-reformulate loop (bounded by `maxIterations`, hard-capped at
  * 5), widening to one-hop graph expansion on reformulation passes. The
  * output reports `abstained: true` when memory was insufficient even
- * after reformulating — the agent should then say it lacks the
+ * after reformulating - the agent should then say it lacks the
  * information rather than guess. Registered only when the facade is
  * created with `iterativeRetrieval`; otherwise it degrades to a single
  * pass, so prefer the cheaper `fact_search` for ordinary lookups.

package/dist/tools/recall-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"recall-tools.d.ts","names":[],"sources":["../../src/tools/recall-tools.ts"],"sourcesContent":[],"mappings":";;;;;cAKM,2BAAyB,CAAA,CAAA;;EAAzB,IAAA,eAAA,YASJ,CAAA;;;;;;;;;;;;EAT6B,KAAA,EAAA,MAAA;EAAA,IAAA,CAAA,EAAA,MAAA,GAAA,SAAA;EAUzB,SAAA,CAAA,EAAA;;;;;;;;;;;;cAAA,0BAA0B,EAAA,CAAA,CAAA,SAAA,CAAA;EAAA,QAAA,YAAA,YAAA,CAAA;IAc3B,SAAA,aAAmB;IACnB,OAAA,aAAoB;IAEnB,KAAA,aAAA;;;;;EAA6B,CAAA,EAAA,OAAA,cAAA,EAAA;IAAA,SAAA,EAAA,MAAA;IAI7B,OAAA,EAAA,MAAA;;;;;;;IAA8B,OAAA,EAAA,MAAA;IAAA,KAAA,EAAA,MAAA;IAS/B,SAAA,EAAA,MAAA;IACA,OAAA,EAAA,MAAA;IAGC,UAAA,CAAA,EAAA,MAAA,GAKJ,SAAA;;;;;;;;;IALyB,UAAA,CAAA,EAAA,MAAA,GAAA,SAAA;EAAA,CAAA,EAAA;AAAA,CAAA,EAAA;;;;;;;;;;KApBtB,mBAAA,GAAsB,CAAA,CAAE,aAAa;KACrC,oBAAA,GAAuB,CAAA,CAAE,aAAa;cAErC,+BAA6B,CAAA,CAAA;;EAuBP,IAAA,eAAA,YAAA,CAAA;CAAA,EAAA,OAAA,cAAA,EAAA;EAgBvB,KAAA,EAAA,MAAA;EACA,IAAA,CAAA,EAAA,MAAA,GAAA,SAAgB;AAQrB,CAAA,EAAA;EACQ,KAAA,EAAA,MAAA;EACA,IAAA,CAAA,EAAA,MAAA,GAAA,SAAA;CAAqB,CAAA;cA9CvB,8BA8CH,EA9CiC,CAAA,CAAA,SA8CjC,CAAA;EAAI,OAAA,YAAA,YAAA,CAAA;IAiDS,SAAA,aAAA;IACR,KAAA,aAAA;EACA,CAAA,EAAA,OAAA,cAAA,EAAA;IAAyB,KAAA,EAAA,MAAA;IAA9B,SAAA,EAAA,MAAA;EAAI,CAAA,EAAA;IA0CS,KAAA,EAAA,MAAA;IACR,SAAA,EAAA,MAAA;EACA,CAAA,CAAA,EAAA,MAAA,CAAA;CAAiB,EAAA,OAAA,cAAA,EAAA;EAAtB,OAAA,EAAA;IAAI,KAAA,EAAA,MAAA;;;;;;;;;KApIF,uBAAA,GAA0B,CAAA,CAAE,aAAa;KACzC,wBAAA,GAA2B,CAAA,CAAE,aAAa;cAGzC,uBAAqB,CAAA,CAAA;;;;;;;;;;;;;;;;cAMrB,wBAAsB,CAAA,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAgBvB,eAAA,GAAkB,CAAA,CAAE,aAAa;KACjC,gBAAA,GAAmB,CAAA,CAAE,aAAa;;;;;;;iBAQvB,wBAAA,OACR,iBACL,KAAK,qBAAqB;;;;;;;iBAiDb,4BAAA,OACR,iBACL,KAAK,yBAAyB;;;;;;;;;;;;;;;iBA0CjB,oBAAA,OACR,iBACL,KAAK,iBAAiB"}
+{"version":3,"file":"recall-tools.d.ts","names":[],"sources":["../../src/tools/recall-tools.ts"],"sourcesContent":[],"mappings":";;;;;cAMM,2BAAyB,CAAA,CAAA;;EAAzB,IAAA,eAAA,YASJ,CAAA;;;;;;;;;;;;EAT6B,KAAA,EAAA,MAAA;EAAA,IAAA,CAAA,EAAA,MAAA,GAAA,SAAA;EAUzB,SAAA,CAAA,EAAA;;;;;;;;;;;;cAAA,0BAA0B,EAAA,CAAA,CAAA,SAAA,CAAA;EAAA,QAAA,YAAA,YAAA,CAAA;IAc3B,SAAA,aAAmB;IACnB,OAAA,aAAoB;IAEnB,KAAA,aAAA;;;;;EAA6B,CAAA,EAAA,OAAA,cAAA,EAAA;IAAA,KAAA,EAAA,MAAA;IAI7B,SAAA,EAAA,MAAA;;;;;;;IAA8B,SAAA,EAAA,MAAA;IAAA,OAAA,EAAA,MAAA;IAS/B,SAAA,EAAA,MAAA;IACA,OAAA,EAAA,MAAA;IAGC,UAAA,CAAA,EAAA,MAAA,GAKJ,SAAA;;;;;;;;;IALyB,UAAA,CAAA,EAAA,MAAA,GAAA,SAAA;EAAA,CAAA,EAAA;AAAA,CAAA,EAAA;;;;;;;;;;KApBtB,mBAAA,GAAsB,CAAA,CAAE,aAAa;KACrC,oBAAA,GAAuB,CAAA,CAAE,aAAa;cAErC,+BAA6B,CAAA,CAAA;;;;;;;EAuBP,KAAA,EAAA,MAAA;EAAA,IAAA,CAAA,EAAA,MAAA,GAAA,SAAA;AAAA,CAAA,CAAA;AA0BE,cA7CxB,8BA8CiC,EA9CH,CAAA,CAAA,SA8CG,CAAA;EAQvB,OAAA,YAAA,YAAwB,CAAA;IAChC,SAAA,aAAA;IACA,KAAA,aAAA;EAAqB,CAAA,EAAA,OAAA,cAAA,EAAA;IAA1B,KAAA,EAAA,MAAA;IAAI,SAAA,EAAA,MAAA;EAqDS,CAAA,EAAA;IACR,KAAA,EAAA,MAAA;IACA,SAAA,EAAA,MAAA;EAAyB,CAAA,CAAA,EAAA,MAAA,CAAA;CAA9B,EAAA,OAAA,cAAA,EAAA;EAAI,OAAA,EAAA;IA0CS,KAAA,EAAA,MAAA;IACR,SAAA,EAAA,MAAA;EACA,CAAA,EAAA;CAAiB,EAAA;EAAtB,OAAA,EAAA;IAAI,KAAA,EAAA,MAAA;;;;KAlJF,uBAAA,GAA0B,CAAA,CAAE,aAAa;KACzC,wBAAA,GAA2B,CAAA,CAAE,aAAa;cAGzC,uBAAqB,CAAA,CAAA;;;;;;;;;;;;;;;;cAMrB,wBAAsB,CAAA,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA0BvB,eAAA,GAAkB,CAAA,CAAE,aAAa;KACjC,gBAAA,GAAmB,CAAA,CAAE,aAAa;;;;;;;iBAQvB,wBAAA,OACR,iBACL,KAAK,qBAAqB;;;;;;;iBAqDb,4BAAA,OACR,iBACL,KAAK,yBAAyB;;;;;;;;;;;;;;;iBA0CjB,oBAAA,OACR,iBACL,KAAK,iBAAiB"}

package/dist/tools/recall-tools.js

@@ -1,3 +1,4 @@
+import { recallTaint } from "./taint.js";
 import { tool } from "@graphorin/tools";
 import { z } from "zod";
 
@@ -43,14 +44,17 @@ const deepRecallOutputSchema = z.object({
 		text: z.string(),
 		score: z.number(),
 		sensitivity: deepRecallSensitivityEnum,
-		provenance: z.string().optional()
+		provenance: z.string().optional(),
+		validTo: z.string().optional(),
+		supersededBy: z.string().optional()
 	})),
 	sufficient: z.boolean(),
 	abstained: z.boolean(),
+	graded: z.boolean(),
 	iterations: z.number().int()
 });
 /**
-* `recall_episodes` — triple-signal episode retrieval (recency ×
+* `recall_episodes` - triple-signal episode retrieval (recency ×
 * relevance × importance).
 *
 * @stable
@@ -72,11 +76,12 @@ function createRecallEpisodesTool(deps) {
 				...input.dateRange.from !== void 0 ? { from: input.dateRange.from } : {},
 				...input.dateRange.to !== void 0 ? { to: input.dateRange.to } : {}
 			} : void 0;
-			return { episodes: (await deps.episodic.search(scope, input.query, {
+			const hits = await deps.episodic.search(scope, input.query, {
 				...input.topK !== void 0 ? { topK: input.topK } : {},
 				...dateRange !== void 0 ? { dateRange } : {},
 				signal: ctx.signal
-			})).map((hit) => ({
+			});
+			const output = { episodes: hits.map((hit) => ({
 				episodeId: hit.record.id,
 				summary: hit.record.summary,
 				score: hit.score,
@@ -84,11 +89,16 @@ function createRecallEpisodesTool(deps) {
 				endedAt: hit.record.endedAt,
 				...hit.record.provenance !== void 0 ? { provenance: hit.record.provenance } : {}
 			})) };
+			const taint = recallTaint(hits.map((h) => h.record));
+			return taint === void 0 ? output : {
+				output,
+				taint
+			};
 		}
 	});
 }
 /**
-* `conversation_search` — FTS5 search over the active session
+* `conversation_search` - FTS5 search over the active session
 * messages.
 *
 * @stable
@@ -117,13 +127,13 @@ function createConversationSearchTool(deps) {
 	});
 }
 /**
-* `deep_recall` — gated, multi-pass ("deep") recall over the user's
+* `deep_recall` - gated, multi-pass ("deep") recall over the user's
 * factual memory for HARD questions (P2-4). A local difficulty gate keeps
 * simple lookups single-shot; only queries judged hard trigger a
 * grade-and-reformulate loop (bounded by `maxIterations`, hard-capped at
 * 5), widening to one-hop graph expansion on reformulation passes. The
 * output reports `abstained: true` when memory was insufficient even
-* after reformulating — the agent should then say it lacks the
+* after reformulating - the agent should then say it lacks the
 * information rather than guess. Registered only when the facade is
 * created with `iterativeRetrieval`; otherwise it degrades to a single
 * pass, so prefer the cheaper `fact_search` for ordinary lookups.
@@ -133,7 +143,7 @@ function createConversationSearchTool(deps) {
 function createDeepRecallTool(deps) {
 	return tool({
 		name: "deep_recall",
-		description: "Multi-pass ('deep') recall over the user's long-term factual memory for HARD multi-hop or temporal questions one search can't answer (e.g. 'who recommended the book the person I met in Tbilisi mentioned?'). A difficulty gate keeps simple lookups single-shot; hard questions trigger a bounded grade-and-reformulate loop. If `abstained` is true the memory was insufficient even after reformulating — tell the user you don't have enough stored to answer and DO NOT guess. Prefer the cheaper fact_search for ordinary lookups.",
+		description: "Multi-pass ('deep') recall over the user's long-term factual memory for HARD multi-hop or temporal questions one search can't answer (e.g. 'who recommended the book the person I met in Tbilisi mentioned?'). A difficulty gate keeps simple lookups single-shot; hard questions trigger a bounded grade-and-reformulate loop. If `abstained` is true the memory was insufficient even after reformulating - tell the user you don't have enough stored to answer and DO NOT guess. Prefer the cheaper fact_search for ordinary lookups.",
 		inputSchema: deepRecallInputSchema,
 		outputSchema: deepRecallOutputSchema,
 		sideEffectClass: "read-only",
@@ -147,20 +157,29 @@ function createDeepRecallTool(deps) {
 				...input.topK !== void 0 ? { topK: input.topK } : {},
 				...input.maxIterations !== void 0 ? { maxIterations: input.maxIterations } : {},
 				...input.asOf !== void 0 ? { asOf: input.asOf } : {},
+				forceHard: true,
 				signal: ctx.signal
 			});
-			return {
+			const output = {
 				hits: result.hits.map((hit) => ({
 					factId: hit.record.id,
 					text: hit.record.text,
 					score: hit.score,
 					sensitivity: hit.record.sensitivity,
-					...hit.record.provenance !== void 0 ? { provenance: hit.record.provenance } : {}
+					...hit.record.provenance !== void 0 ? { provenance: hit.record.provenance } : {},
+					...hit.record.validTo !== void 0 ? { validTo: hit.record.validTo } : {},
+					...hit.record.supersededBy !== void 0 ? { supersededBy: hit.record.supersededBy } : {}
 				})),
 				sufficient: result.sufficient,
 				abstained: result.abstained,
+				graded: result.graded,
 				iterations: result.iterations
 			};
+			const taint = recallTaint(result.hits.map((h) => h.record));
+			return taint === void 0 ? output : {
+				output,
+				taint
+			};
 		}
 	});
 }

package/dist/tools/recall-tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"recall-tools.js","names":[],"sources":["../../src/tools/recall-tools.ts"],"sourcesContent":["import type { Tool } from '@graphorin/core';\nimport { tool } from '@graphorin/tools';\nimport { z } from 'zod';\nimport type { MemoryToolDeps } from './types.js';\n\nconst recallEpisodesInputSchema = z.object({\n  query: z.string().min(1).max(1024),\n  topK: z.number().int().positive().max(20).optional(),\n  dateRange: z\n    .object({\n      from: z.string().datetime().optional(),\n      to: z.string().datetime().optional(),\n    })\n    .optional(),\n});\nconst recallEpisodesOutputSchema = z.object({\n  episodes: z.array(\n    z.object({\n      episodeId: z.string(),\n      summary: z.string(),\n      score: z.number(),\n      startedAt: z.string(),\n      endedAt: z.string(),\n      /** Trust-provenance tag (MST-10) — synthesized episodes say so. */\n      provenance: z.string().optional(),\n    }),\n  ),\n});\n\ntype RecallEpisodesInput = z.infer<typeof recallEpisodesInputSchema>;\ntype RecallEpisodesOutput = z.infer<typeof recallEpisodesOutputSchema>;\n\nconst conversationSearchInputSchema = z.object({\n  query: z.string().min(1).max(1024),\n  topK: z.number().int().positive().max(20).optional(),\n});\nconst conversationSearchOutputSchema = z.object({\n  matches: z.array(\n    z.object({\n      messageId: z.string(),\n      score: z.number(),\n    }),\n  ),\n});\n\ntype ConversationSearchInput = z.infer<typeof conversationSearchInputSchema>;\ntype ConversationSearchOutput = z.infer<typeof conversationSearchOutputSchema>;\n\nconst deepRecallSensitivityEnum = z.enum(['public', 'internal', 'secret']);\nconst deepRecallInputSchema = z.object({\n  query: z.string().min(1).max(1024),\n  topK: z.number().int().positive().max(50).optional(),\n  maxIterations: z.number().int().min(1).max(5).optional(),\n  asOf: z.string().datetime().optional(),\n});\nconst deepRecallOutputSchema = z.object({\n  hits: z.array(\n    z.object({\n      factId: z.string(),\n      text: z.string(),\n      score: z.number(),\n      sensitivity: deepRecallSensitivityEnum,\n      /** Trust-provenance tag (MST-10) — synthesized facts say so. */\n      provenance: z.string().optional(),\n    }),\n  ),\n  sufficient: z.boolean(),\n  abstained: z.boolean(),\n  iterations: z.number().int(),\n});\n\ntype DeepRecallInput = z.infer<typeof deepRecallInputSchema>;\ntype DeepRecallOutput = z.infer<typeof deepRecallOutputSchema>;\n\n/**\n * `recall_episodes` — triple-signal episode retrieval (recency ×\n * relevance × importance).\n *\n * @stable\n */\nexport function createRecallEpisodesTool(\n  deps: MemoryToolDeps,\n): Tool<RecallEpisodesInput, RecallEpisodesOutput> {\n  return tool<RecallEpisodesInput, RecallEpisodesOutput>({\n    name: 'recall_episodes',\n    description:\n      \"Recall summarized episodes (multi-message stretches of past activity) matching a natural-language query. Combines vector relevance, time-decay recency, and the per-episode importance score. Use for long-horizon recall ('the last time we discussed X').\",\n    inputSchema: recallEpisodesInputSchema,\n    outputSchema: recallEpisodesOutputSchema,\n    sideEffectClass: 'read-only',\n    sandboxPolicy: 'none',\n    sensitivity: 'internal',\n    memoryGuardTier: 'pure',\n    tags: ['memory', 'episodic'],\n    async execute(input, ctx) {\n      const scope = await deps.resolveScope(ctx);\n      const dateRange =\n        input.dateRange !== undefined\n          ? {\n              ...(input.dateRange.from !== undefined ? { from: input.dateRange.from } : {}),\n              ...(input.dateRange.to !== undefined ? { to: input.dateRange.to } : {}),\n            }\n          : undefined;\n      const hits = await deps.episodic.search(scope, input.query, {\n        ...(input.topK !== undefined ? { topK: input.topK } : {}),\n        ...(dateRange !== undefined ? { dateRange } : {}),\n        signal: ctx.signal,\n      });\n      return {\n        episodes: hits.map((hit) => ({\n          episodeId: hit.record.id,\n          summary: hit.record.summary,\n          score: hit.score,\n          startedAt: hit.record.startedAt,\n          endedAt: hit.record.endedAt,\n          // MST-10: surface origin so a consumer can tell a synthesized\n          // (consolidator-extracted) episode from a first-party record —\n          // recalled text re-enters the model as trusted tool output.\n          ...(hit.record.provenance !== undefined ? { provenance: hit.record.provenance } : {}),\n        })),\n      };\n    },\n  });\n}\n\n/**\n * `conversation_search` — FTS5 search over the active session\n * messages.\n *\n * @stable\n */\nexport function createConversationSearchTool(\n  deps: MemoryToolDeps,\n): Tool<ConversationSearchInput, ConversationSearchOutput> {\n  return tool<ConversationSearchInput, ConversationSearchOutput>({\n    name: 'conversation_search',\n    description:\n      'Search the active session message log by natural-language query. Returns up to `topK` matched messages with their stable id and BM25 score.',\n    inputSchema: conversationSearchInputSchema,\n    outputSchema: conversationSearchOutputSchema,\n    sideEffectClass: 'read-only',\n    sandboxPolicy: 'none',\n    sensitivity: 'internal',\n    memoryGuardTier: 'pure',\n    tags: ['memory', 'session'],\n    async execute(input, ctx) {\n      const scope = await deps.resolveScope(ctx);\n      const hits = await deps.session.search(scope, input.query, {\n        ...(input.topK !== undefined ? { topK: input.topK } : {}),\n        signal: ctx.signal,\n      });\n      return {\n        matches: hits.map((hit) => ({\n          messageId: hit.record.id,\n          score: hit.score,\n        })),\n      };\n    },\n  });\n}\n\n/**\n * `deep_recall` — gated, multi-pass (\"deep\") recall over the user's\n * factual memory for HARD questions (P2-4). A local difficulty gate keeps\n * simple lookups single-shot; only queries judged hard trigger a\n * grade-and-reformulate loop (bounded by `maxIterations`, hard-capped at\n * 5), widening to one-hop graph expansion on reformulation passes. The\n * output reports `abstained: true` when memory was insufficient even\n * after reformulating — the agent should then say it lacks the\n * information rather than guess. Registered only when the facade is\n * created with `iterativeRetrieval`; otherwise it degrades to a single\n * pass, so prefer the cheaper `fact_search` for ordinary lookups.\n *\n * @stable\n */\nexport function createDeepRecallTool(\n  deps: MemoryToolDeps,\n): Tool<DeepRecallInput, DeepRecallOutput> {\n  return tool<DeepRecallInput, DeepRecallOutput>({\n    name: 'deep_recall',\n    description:\n      \"Multi-pass ('deep') recall over the user's long-term factual memory for HARD multi-hop or temporal questions one search can't answer (e.g. 'who recommended the book the person I met in Tbilisi mentioned?'). A difficulty gate keeps simple lookups single-shot; hard questions trigger a bounded grade-and-reformulate loop. If `abstained` is true the memory was insufficient even after reformulating — tell the user you don't have enough stored to answer and DO NOT guess. Prefer the cheaper fact_search for ordinary lookups.\",\n    inputSchema: deepRecallInputSchema,\n    outputSchema: deepRecallOutputSchema,\n    sideEffectClass: 'read-only',\n    sandboxPolicy: 'none',\n    sensitivity: 'internal',\n    memoryGuardTier: 'pure',\n    tags: ['memory', 'semantic'],\n    async execute(input, ctx) {\n      const scope = await deps.resolveScope(ctx);\n      const result = await deps.semantic.searchIterative(scope, input.query, {\n        ...(input.topK !== undefined ? { topK: input.topK } : {}),\n        ...(input.maxIterations !== undefined ? { maxIterations: input.maxIterations } : {}),\n        ...(input.asOf !== undefined ? { asOf: input.asOf } : {}),\n        signal: ctx.signal,\n      });\n      return {\n        hits: result.hits.map((hit) => ({\n          factId: hit.record.id,\n          text: hit.record.text,\n          score: hit.score,\n          sensitivity: hit.record.sensitivity,\n          // MST-10: origin annotation, mirroring fact_search.\n          ...(hit.record.provenance !== undefined ? { provenance: hit.record.provenance } : {}),\n        })),\n        sufficient: result.sufficient,\n        abstained: result.abstained,\n        iterations: result.iterations,\n      };\n    },\n  });\n}\n"],"mappings":"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"}
+{"version":3,"file":"recall-tools.js","names":[],"sources":["../../src/tools/recall-tools.ts"],"sourcesContent":["import type { Tool } from '@graphorin/core';\nimport { tool } from '@graphorin/tools';\nimport { z } from 'zod';\nimport { recallTaint } from './taint.js';\nimport type { MemoryToolDeps } from './types.js';\n\nconst recallEpisodesInputSchema = z.object({\n  query: z.string().min(1).max(1024),\n  topK: z.number().int().positive().max(20).optional(),\n  dateRange: z\n    .object({\n      from: z.string().datetime().optional(),\n      to: z.string().datetime().optional(),\n    })\n    .optional(),\n});\nconst recallEpisodesOutputSchema = z.object({\n  episodes: z.array(\n    z.object({\n      episodeId: z.string(),\n      summary: z.string(),\n      score: z.number(),\n      startedAt: z.string(),\n      endedAt: z.string(),\n      /** Trust-provenance tag (MST-10) - synthesized episodes say so. */\n      provenance: z.string().optional(),\n    }),\n  ),\n});\n\ntype RecallEpisodesInput = z.infer<typeof recallEpisodesInputSchema>;\ntype RecallEpisodesOutput = z.infer<typeof recallEpisodesOutputSchema>;\n\nconst conversationSearchInputSchema = z.object({\n  query: z.string().min(1).max(1024),\n  topK: z.number().int().positive().max(20).optional(),\n});\nconst conversationSearchOutputSchema = z.object({\n  matches: z.array(\n    z.object({\n      messageId: z.string(),\n      score: z.number(),\n    }),\n  ),\n});\n\ntype ConversationSearchInput = z.infer<typeof conversationSearchInputSchema>;\ntype ConversationSearchOutput = z.infer<typeof conversationSearchOutputSchema>;\n\nconst deepRecallSensitivityEnum = z.enum(['public', 'internal', 'secret']);\nconst deepRecallInputSchema = z.object({\n  query: z.string().min(1).max(1024),\n  topK: z.number().int().positive().max(50).optional(),\n  maxIterations: z.number().int().min(1).max(5).optional(),\n  asOf: z.string().datetime().optional(),\n});\nconst deepRecallOutputSchema = z.object({\n  hits: z.array(\n    z.object({\n      factId: z.string(),\n      text: z.string(),\n      score: z.number(),\n      sensitivity: deepRecallSensitivityEnum,\n      /** Trust-provenance tag (MST-10) - synthesized facts say so. */\n      provenance: z.string().optional(),\n      /** Closed validity end (only surfaces on `asOf` reads). */\n      validTo: z.string().optional(),\n      /** Id of the fact that superseded this one, when any. */\n      supersededBy: z.string().optional(),\n    }),\n  ),\n  sufficient: z.boolean(),\n  abstained: z.boolean(),\n  /**\n   * Whether the grader actually judged sufficiency\n   * (memory-retrieval-02). When `false`, `sufficient: true` is a\n   * default, not a verdict.\n   */\n  graded: z.boolean(),\n  iterations: z.number().int(),\n});\n\ntype DeepRecallInput = z.infer<typeof deepRecallInputSchema>;\ntype DeepRecallOutput = z.infer<typeof deepRecallOutputSchema>;\n\n/**\n * `recall_episodes` - triple-signal episode retrieval (recency ×\n * relevance × importance).\n *\n * @stable\n */\nexport function createRecallEpisodesTool(\n  deps: MemoryToolDeps,\n): Tool<RecallEpisodesInput, RecallEpisodesOutput> {\n  return tool<RecallEpisodesInput, RecallEpisodesOutput>({\n    name: 'recall_episodes',\n    description:\n      \"Recall summarized episodes (multi-message stretches of past activity) matching a natural-language query. Combines vector relevance, time-decay recency, and the per-episode importance score. Use for long-horizon recall ('the last time we discussed X').\",\n    inputSchema: recallEpisodesInputSchema,\n    outputSchema: recallEpisodesOutputSchema,\n    sideEffectClass: 'read-only',\n    sandboxPolicy: 'none',\n    sensitivity: 'internal',\n    memoryGuardTier: 'pure',\n    tags: ['memory', 'episodic'],\n    async execute(input, ctx) {\n      const scope = await deps.resolveScope(ctx);\n      const dateRange =\n        input.dateRange !== undefined\n          ? {\n              ...(input.dateRange.from !== undefined ? { from: input.dateRange.from } : {}),\n              ...(input.dateRange.to !== undefined ? { to: input.dateRange.to } : {}),\n            }\n          : undefined;\n      const hits = await deps.episodic.search(scope, input.query, {\n        ...(input.topK !== undefined ? { topK: input.topK } : {}),\n        ...(dateRange !== undefined ? { dateRange } : {}),\n        signal: ctx.signal,\n      });\n      const output = {\n        episodes: hits.map((hit) => ({\n          episodeId: hit.record.id,\n          summary: hit.record.summary,\n          score: hit.score,\n          startedAt: hit.record.startedAt,\n          endedAt: hit.record.endedAt,\n          // MST-10: surface origin so a consumer can tell a synthesized\n          // (consolidator-extracted) episode from a first-party record -\n          // recalled text re-enters the model as trusted tool output.\n          ...(hit.record.provenance !== undefined ? { provenance: hit.record.provenance } : {}),\n        })),\n      };\n      // C6: recalled foreign-provenance / quarantined episodes re-arm the\n      // taint ledger (the cross-session poisoning leg).\n      const taint = recallTaint(hits.map((h) => h.record));\n      return taint === undefined ? output : { output, taint };\n    },\n  });\n}\n\n/**\n * `conversation_search` - FTS5 search over the active session\n * messages.\n *\n * @stable\n */\nexport function createConversationSearchTool(\n  deps: MemoryToolDeps,\n): Tool<ConversationSearchInput, ConversationSearchOutput> {\n  return tool<ConversationSearchInput, ConversationSearchOutput>({\n    name: 'conversation_search',\n    description:\n      'Search the active session message log by natural-language query. Returns up to `topK` matched messages with their stable id and BM25 score.',\n    inputSchema: conversationSearchInputSchema,\n    outputSchema: conversationSearchOutputSchema,\n    sideEffectClass: 'read-only',\n    sandboxPolicy: 'none',\n    sensitivity: 'internal',\n    memoryGuardTier: 'pure',\n    tags: ['memory', 'session'],\n    async execute(input, ctx) {\n      const scope = await deps.resolveScope(ctx);\n      const hits = await deps.session.search(scope, input.query, {\n        ...(input.topK !== undefined ? { topK: input.topK } : {}),\n        signal: ctx.signal,\n      });\n      return {\n        matches: hits.map((hit) => ({\n          messageId: hit.record.id,\n          score: hit.score,\n        })),\n      };\n    },\n  });\n}\n\n/**\n * `deep_recall` - gated, multi-pass (\"deep\") recall over the user's\n * factual memory for HARD questions (P2-4). A local difficulty gate keeps\n * simple lookups single-shot; only queries judged hard trigger a\n * grade-and-reformulate loop (bounded by `maxIterations`, hard-capped at\n * 5), widening to one-hop graph expansion on reformulation passes. The\n * output reports `abstained: true` when memory was insufficient even\n * after reformulating - the agent should then say it lacks the\n * information rather than guess. Registered only when the facade is\n * created with `iterativeRetrieval`; otherwise it degrades to a single\n * pass, so prefer the cheaper `fact_search` for ordinary lookups.\n *\n * @stable\n */\nexport function createDeepRecallTool(\n  deps: MemoryToolDeps,\n): Tool<DeepRecallInput, DeepRecallOutput> {\n  return tool<DeepRecallInput, DeepRecallOutput>({\n    name: 'deep_recall',\n    description:\n      \"Multi-pass ('deep') recall over the user's long-term factual memory for HARD multi-hop or temporal questions one search can't answer (e.g. 'who recommended the book the person I met in Tbilisi mentioned?'). A difficulty gate keeps simple lookups single-shot; hard questions trigger a bounded grade-and-reformulate loop. If `abstained` is true the memory was insufficient even after reformulating - tell the user you don't have enough stored to answer and DO NOT guess. Prefer the cheaper fact_search for ordinary lookups.\",\n    inputSchema: deepRecallInputSchema,\n    outputSchema: deepRecallOutputSchema,\n    sideEffectClass: 'read-only',\n    sandboxPolicy: 'none',\n    sensitivity: 'internal',\n    memoryGuardTier: 'pure',\n    tags: ['memory', 'semantic'],\n    async execute(input, ctx) {\n      const scope = await deps.resolveScope(ctx);\n      const result = await deps.semantic.searchIterative(scope, input.query, {\n        ...(input.topK !== undefined ? { topK: input.topK } : {}),\n        ...(input.maxIterations !== undefined ? { maxIterations: input.maxIterations } : {}),\n        ...(input.asOf !== undefined ? { asOf: input.asOf } : {}),\n        // memory-retrieval-02: the model choosing deep_recall over\n        // fact_search IS the hardness signal - the local heuristic gate\n        // rejected the tool's own documented multi-hop examples\n        // (W_MULTI_HOP 0.4 < threshold 0.5) and is English-only. The\n        // cap + grader stop conditions still bound cost.\n        forceHard: true,\n        signal: ctx.signal,\n      });\n      const output = {\n        hits: result.hits.map((hit) => ({\n          factId: hit.record.id,\n          text: hit.record.text,\n          score: hit.score,\n          sensitivity: hit.record.sensitivity,\n          // MST-10: origin annotation, mirroring fact_search.\n          ...(hit.record.provenance !== undefined ? { provenance: hit.record.provenance } : {}),\n          ...(hit.record.validTo !== undefined ? { validTo: hit.record.validTo } : {}),\n          ...(hit.record.supersededBy !== undefined\n            ? { supersededBy: hit.record.supersededBy }\n            : {}),\n        })),\n        sufficient: result.sufficient,\n        abstained: result.abstained,\n        graded: result.graded,\n        iterations: result.iterations,\n      };\n      // C6: mirror fact_search - recalled poisoned content re-arms the ledger.\n      const taint = recallTaint(result.hits.map((h) => h.record));\n      return taint === undefined ? output : { output, taint };\n    },\n  });\n}\n"],"mappings":"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"}

package/dist/tools/runbook-tools.d.ts

@@ -0,0 +1,76 @@
+import { MemoryToolDeps } from "./types.js";
+import { Tool } from "@graphorin/core";
+import { z } from "zod";
+
+//#region src/tools/runbook-tools.d.ts
+
+declare const runbookSearchInputSchema: z.ZodObject<{
+  query: z.ZodString;
+  topK: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+  query: string;
+  topK?: number | undefined;
+}, {
+  query: string;
+  topK?: number | undefined;
+}>;
+declare const runbookSearchOutputSchema: z.ZodObject<{
+  procedures: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    text: z.ZodString;
+    steps: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    variables: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    successCriteria: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    priority: z.ZodNumber;
+    score: z.ZodNumber;
+  }, "strip", z.ZodTypeAny, {
+    id: string;
+    text: string;
+    priority: number;
+    score: number;
+    steps?: string[] | undefined;
+    variables?: string[] | undefined;
+    successCriteria?: string[] | undefined;
+  }, {
+    id: string;
+    text: string;
+    priority: number;
+    score: number;
+    steps?: string[] | undefined;
+    variables?: string[] | undefined;
+    successCriteria?: string[] | undefined;
+  }>, "many">;
+}, "strip", z.ZodTypeAny, {
+  procedures: {
+    id: string;
+    text: string;
+    priority: number;
+    score: number;
+    steps?: string[] | undefined;
+    variables?: string[] | undefined;
+    successCriteria?: string[] | undefined;
+  }[];
+}, {
+  procedures: {
+    id: string;
+    text: string;
+    priority: number;
+    score: number;
+    steps?: string[] | undefined;
+    variables?: string[] | undefined;
+    successCriteria?: string[] | undefined;
+  }[];
+}>;
+type RunbookSearchInput = z.infer<typeof runbookSearchInputSchema>;
+type RunbookSearchOutput = z.infer<typeof runbookSearchOutputSchema>;
+/**
+ * `runbook_search` - find validated procedures matching a task
+ * description. Quarantined (unvalidated induced) procedures never
+ * surface here: they must not drive actions until validated.
+ *
+ * @stable
+ */
+declare function createRunbookSearchTool(deps: MemoryToolDeps): Tool<RunbookSearchInput, RunbookSearchOutput>;
+//#endregion
+export { createRunbookSearchTool };
+//# sourceMappingURL=runbook-tools.d.ts.map

package/dist/tools/runbook-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runbook-tools.d.ts","names":[],"sources":["../../src/tools/runbook-tools.ts"],"sourcesContent":[],"mappings":";;;;;;cAiBM,0BAAwB,CAAA,CAAA;;;;;;;;;;cAIxB,2BAAyB,CAAA,CAAA;;;;;;IAAA,eAAA,eAAA,WAAA,YAAA,EAAA,MAAA,CAAA,CAAA;IAAA,QAAA,aAAA;IAc1B,KAAA,aAAkB;EAClB,CAAA,EAAA,OAAA,cAAmB,EAAA;IASR,EAAA,EAAA,MAAA;IACR,IAAA,EAAA,MAAA;IACA,QAAA,EAAA,MAAA;IAAoB,KAAA,EAAA,MAAA;IAAzB,KAAA,CAAA,EAAA,MAAA,EAAA,GAAA,SAAA;IAAI,SAAA,CAAA,EAAA,MAAA,EAAA,GAAA,SAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAZF,kBAAA,GAAqB,CAAA,CAAE,aAAa;KACpC,mBAAA,GAAsB,CAAA,CAAE,aAAa;;;;;;;;iBAS1B,uBAAA,OACR,iBACL,KAAK,oBAAoB"}