@graphorin/memory 0.6.1 → 0.7.0

package/dist/tiers/insight-memory.js.map

@@ -1 +1 @@
-{"version":3,"file":"insight-memory.js","names":["#store","#tracer"],"sources":["../../src/tiers/insight-memory.ts"],"sourcesContent":["/**\n * `InsightMemory` - the thin, read-only surface over the reflection\n * insights the consolidator synthesizes (P1-1). Insights are *derived*\n * (quarantined + `provenance: 'reflection'`), carry mandatory citations,\n * and are retrieval-ranked **below the primary facts they cite**. The\n * write + salience-management paths live in the consolidator's\n * reflection pass; this tier only lists / searches for the validation /\n * inspector path.\n *\n * Search is FTS-only - insights are a soft inspector surface, not\n * primary recall, so no embedder is wired here.\n *\n * @packageDocumentation\n */\n\nimport type { Fact, Insight, MemoryHit, SessionScope, Tracer } from '@graphorin/core';\nimport { QuarantinePromotionRefusedError } from '../errors/index.js';\nimport { detectMemoryInjection } from '../internal/injection-heuristics.js';\nimport { withMemorySpan } from '../internal/spans.js';\nimport type { MemoryStoreAdapter } from '../internal/storage-adapter.js';\n\n/** Per-call options accepted by {@link InsightMemory.search}. */\nexport interface InsightSearchOptions {\n  readonly topK?: number;\n  /**\n   * Include quarantined insights (P1-4). Defaults to `false`. Since\n   * reflection-synthesized insights *always* land quarantined, set this\n   * `true` to surface them for the validation / inspector path - never\n   * for auto-recall fed back into the model.\n   */\n  readonly includeQuarantined?: boolean;\n  readonly signal?: AbortSignal;\n}\n\n/** Per-call options accepted by {@link InsightMemory.list}. */\nexport interface InsightListOptions {\n  readonly limit?: number;\n  /** Include quarantined insights (validation / inspector path). */\n  readonly includeQuarantined?: boolean;\n}\n\n/**\n * `InsightMemory` - list / search reflection insights. A no-op (returns\n * empty) when the storage adapter does not expose the optional\n * `insights` surface.\n *\n * @stable\n */\nexport class InsightMemory {\n  readonly #store: MemoryStoreAdapter;\n  readonly #tracer: Tracer;\n\n  constructor(args: { store: MemoryStoreAdapter; tracer: Tracer }) {\n    this.#store = args.store;\n    this.#tracer = args.tracer;\n  }\n\n  /** FTS keyword search over insight text. */\n  async search(\n    scope: SessionScope,\n    query: string,\n    opts: InsightSearchOptions = {},\n  ): Promise<ReadonlyArray<MemoryHit<Insight>>> {\n    return withMemorySpan(\n      this.#tracer,\n      'memory.search.insight',\n      scope,\n      { 'memory.search.query_length': query.length },\n      async (span) => {\n        const store = this.#store.insights;\n        if (store === undefined) {\n          span.setAttributes({ 'memory.search.insight.count': 0 });\n          return [];\n        }\n        const hits = await store.search(scope, query, {\n          topK: opts.topK ?? 10,\n          ...(opts.includeQuarantined !== undefined\n            ? { includeQuarantined: opts.includeQuarantined }\n            : {}),\n        });\n        // MCON-16: retrieval reinforces (ExpeL) - a recalled insight gains\n        // +1 salience, offsetting the per-reflection-pass -1 decay, so\n        // used insights persist while unused ones slide to the prune\n        // floor. Best-effort bookkeeping: never break the read path.\n        for (const hit of hits) {\n          try {\n            await store.bumpSalience(hit.record.id, 1, 'retrieval');\n          } catch {\n            // Advisory only.\n          }\n        }\n        span.setAttributes({ 'memory.search.insight.count': hits.length });\n        return hits;\n      },\n    );\n  }\n\n  /** Most-recent insights for the scope (newest first). */\n  async list(scope: SessionScope, opts: InsightListOptions = {}): Promise<ReadonlyArray<Insight>> {\n    return withMemorySpan(this.#tracer, 'memory.read.insight', scope, {}, async (span) => {\n      const store = this.#store.insights;\n      if (store === undefined) {\n        span.setAttributes({ 'memory.read.insight.count': 0 });\n        return [];\n      }\n      const out = await store.list(scope, {\n        ...(opts.limit !== undefined ? { limit: opts.limit } : {}),\n        ...(opts.includeQuarantined !== undefined\n          ? { includeQuarantined: opts.includeQuarantined }\n          : {}),\n      });\n      span.setAttributes({ 'memory.read.insight.count': out.length });\n      return out;\n    });\n  }\n\n  /** Lookup a single insight by id. */\n  async get(id: string): Promise<Insight | null> {\n    const store = this.#store.insights;\n    if (store === undefined || typeof store.get !== 'function') return null;\n    return store.get(id);\n  }\n\n  /**\n   * Promote a quarantined insight out of quarantine (MCON-2). Mirrors\n   * {@link SemanticMemory.validate}: re-derives the injection verdict from the\n   * stored text and **refuses** promotion of an injection-flagged insight\n   * unless an operator passes `{ force: true }` from a trusted context.\n   */\n  async validate(\n    scope: SessionScope,\n    insightId: string,\n    reason?: string,\n    options?: { readonly force?: boolean },\n  ): Promise<void> {\n    await withMemorySpan(\n      this.#tracer,\n      'memory.write.insight',\n      scope,\n      { 'memory.insight.action': 'validate', 'memory.insight.insight_id': insightId },\n      async (span) => {\n        const store = this.#store.insights;\n        if (store === undefined || typeof store.setStatus !== 'function') {\n          throw new TypeError(\n            '[graphorin/memory] InsightMemory.validate(...) requires a storage adapter that implements `insights.setStatus(id, status)`. ' +\n              'The default `@graphorin/store-sqlite` adapter implements it; custom adapters can opt in via InsightMemoryStoreExt.',\n          );\n        }\n        const force = options?.force === true;\n        const existing = typeof store.get === 'function' ? await store.get(insightId) : null;\n        if (existing !== null && !force) {\n          const injection = detectMemoryInjection(existing.text);\n          if (injection.flagged) {\n            span.setAttributes({ 'memory.insight.validate.refused': true });\n            throw new QuarantinePromotionRefusedError(insightId, injection.markers);\n          }\n        }\n        span.setAttributes({ 'memory.insight.validate.forced': force });\n        await store.setStatus(insightId, 'active', reason);\n      },\n    );\n  }\n}\n\n/** Tie-break margin keeping a capped insight strictly below its cited fact. */\nconst RANK_CAP_EPSILON = 1e-6;\n\n/**\n * Enforce the P1-1 rank ceiling: an insight may never outrank a primary\n * fact **it cites**. For each insight hit, if any fact it cites is\n * present in `factHits`, its score is lowered to strictly below that\n * cited fact's score - so concatenating the two lists and sorting by\n * score descending can never place the insight above the evidence it\n * was synthesized from. Insights whose cited facts are absent from\n * `factHits` are returned unchanged; this is a relative, not a global,\n * cap (per the execution plan: \"never outrank the primary facts they\n * cite\").\n *\n * Pure + deterministic - does not mutate its inputs.\n *\n * @stable\n */\nexport function capInsightsBelowFacts(\n  factHits: ReadonlyArray<MemoryHit<Fact>>,\n  insightHits: ReadonlyArray<MemoryHit<Insight>>,\n): ReadonlyArray<MemoryHit<Insight>> {\n  if (factHits.length === 0 || insightHits.length === 0) return insightHits;\n  const factScoreById = new Map<string, number>();\n  for (const hit of factHits) {\n    const prev = factScoreById.get(hit.record.id);\n    if (prev === undefined || hit.score > prev) factScoreById.set(hit.record.id, hit.score);\n  }\n  return insightHits.map((hit) => {\n    let citedMax = Number.NEGATIVE_INFINITY;\n    for (const id of hit.record.cites) {\n      const score = factScoreById.get(id);\n      if (score !== undefined && score > citedMax) citedMax = score;\n    }\n    // No cited fact present in the fused set, or already below it ⇒ keep.\n    if (citedMax === Number.NEGATIVE_INFINITY || hit.score < citedMax) return hit;\n    const capped = citedMax - RANK_CAP_EPSILON;\n    return {\n      ...hit,\n      score: capped,\n      signals: Object.freeze({ ...(hit.signals ?? {}), 'rank-cap': capped }),\n    };\n  });\n}\n"],"mappings":"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"}
+{"version":3,"file":"insight-memory.js","names":["#store","#tracer"],"sources":["../../src/tiers/insight-memory.ts"],"sourcesContent":["/**\n * `InsightMemory` - the thin, read-only surface over the reflection\n * insights the consolidator synthesizes (P1-1). Insights are *derived*\n * (quarantined + `provenance: 'reflection'`), carry mandatory citations,\n * and are retrieval-ranked **below the primary facts they cite**. The\n * write + salience-management paths live in the consolidator's\n * reflection pass; this tier only lists / searches for the validation /\n * inspector path.\n *\n * Search is FTS-only - insights are a soft inspector surface, not\n * primary recall, so no embedder is wired here.\n *\n * @packageDocumentation\n */\n\nimport type { Fact, Insight, MemoryHit, SessionScope, Tracer } from '@graphorin/core';\nimport { QuarantinePromotionRefusedError } from '../errors/index.js';\nimport { detectMemoryInjection } from '../internal/injection-heuristics.js';\nimport { withMemorySpan } from '../internal/spans.js';\nimport type { MemoryStoreAdapter } from '../internal/storage-adapter.js';\n\n/** Per-call options accepted by {@link InsightMemory.search}. */\nexport interface InsightSearchOptions {\n  readonly topK?: number;\n  /**\n   * Include quarantined insights (P1-4). Defaults to `false`. Since\n   * reflection-synthesized insights *always* land quarantined, set this\n   * `true` to surface them for the validation / inspector path - never\n   * for auto-recall fed back into the model.\n   */\n  readonly includeQuarantined?: boolean;\n  readonly signal?: AbortSignal;\n}\n\n/** Per-call options accepted by {@link InsightMemory.list}. */\nexport interface InsightListOptions {\n  readonly limit?: number;\n  /** Include quarantined insights (validation / inspector path). */\n  readonly includeQuarantined?: boolean;\n}\n\n/**\n * `InsightMemory` - list / search reflection insights. A no-op (returns\n * empty) when the storage adapter does not expose the optional\n * `insights` surface.\n *\n * @stable\n */\nexport class InsightMemory {\n  readonly #store: MemoryStoreAdapter;\n  readonly #tracer: Tracer;\n\n  constructor(args: { store: MemoryStoreAdapter; tracer: Tracer }) {\n    this.#store = args.store;\n    this.#tracer = args.tracer;\n  }\n\n  /** FTS keyword search over insight text. */\n  async search(\n    scope: SessionScope,\n    query: string,\n    opts: InsightSearchOptions = {},\n  ): Promise<ReadonlyArray<MemoryHit<Insight>>> {\n    return withMemorySpan(\n      this.#tracer,\n      'memory.search.insight',\n      scope,\n      { 'memory.search.query_length': query.length },\n      async (span) => {\n        const store = this.#store.insights;\n        if (store === undefined) {\n          span.setAttributes({ 'memory.search.insight.count': 0 });\n          return [];\n        }\n        const hits = await store.search(scope, query, {\n          topK: opts.topK ?? 10,\n          ...(opts.includeQuarantined !== undefined\n            ? { includeQuarantined: opts.includeQuarantined }\n            : {}),\n        });\n        // MCON-16: retrieval reinforces (ExpeL) - a recalled insight gains\n        // +1 salience, offsetting the per-reflection-pass -1 decay, so\n        // used insights persist while unused ones slide to the prune\n        // floor. Best-effort bookkeeping: never break the read path.\n        for (const hit of hits) {\n          try {\n            await store.bumpSalience(hit.record.id, 1, 'retrieval');\n          } catch {\n            // Advisory only.\n          }\n        }\n        span.setAttributes({ 'memory.search.insight.count': hits.length });\n        return hits;\n      },\n    );\n  }\n\n  /** Most-recent insights for the scope (newest first). */\n  async list(scope: SessionScope, opts: InsightListOptions = {}): Promise<ReadonlyArray<Insight>> {\n    return withMemorySpan(this.#tracer, 'memory.read.insight', scope, {}, async (span) => {\n      const store = this.#store.insights;\n      if (store === undefined) {\n        span.setAttributes({ 'memory.read.insight.count': 0 });\n        return [];\n      }\n      const out = await store.list(scope, {\n        ...(opts.limit !== undefined ? { limit: opts.limit } : {}),\n        ...(opts.includeQuarantined !== undefined\n          ? { includeQuarantined: opts.includeQuarantined }\n          : {}),\n      });\n      span.setAttributes({ 'memory.read.insight.count': out.length });\n      return out;\n    });\n  }\n\n  /** Lookup a single insight by id. */\n  async get(id: string): Promise<Insight | null> {\n    const store = this.#store.insights;\n    if (store === undefined || typeof store.get !== 'function') return null;\n    return store.get(id);\n  }\n\n  /**\n   * Promote a quarantined insight out of quarantine (MCON-2). Mirrors\n   * {@link SemanticMemory.validate}: re-derives the injection verdict from the\n   * stored text and **refuses** promotion of an injection-flagged insight\n   * unless an operator passes `{ force: true }` from a trusted context.\n   */\n  async validate(\n    scope: SessionScope,\n    insightId: string,\n    reason?: string,\n    options?: { readonly force?: boolean },\n  ): Promise<void> {\n    await withMemorySpan(\n      this.#tracer,\n      'memory.write.insight',\n      scope,\n      { 'memory.insight.action': 'validate', 'memory.insight.insight_id': insightId },\n      async (span) => {\n        const store = this.#store.insights;\n        if (store === undefined || typeof store.setStatus !== 'function') {\n          throw new TypeError(\n            '[graphorin/memory] InsightMemory.validate(...) requires a storage adapter that implements `insights.setStatus(id, status)`. ' +\n              'The default `@graphorin/store-sqlite` adapter implements it; custom adapters can opt in via InsightMemoryStoreExt.',\n          );\n        }\n        const force = options?.force === true;\n        const existing = typeof store.get === 'function' ? await store.get(insightId) : null;\n        if (existing !== null && !force) {\n          const injection = detectMemoryInjection(existing.text);\n          if (injection.flagged) {\n            span.setAttributes({ 'memory.insight.validate.refused': true });\n            throw new QuarantinePromotionRefusedError(insightId, injection.markers);\n          }\n        }\n        span.setAttributes({ 'memory.insight.validate.forced': force });\n        await store.setStatus(insightId, 'active', reason, scope);\n      },\n    );\n  }\n}\n\n/** Tie-break margin keeping a capped insight strictly below its cited fact. */\nconst RANK_CAP_EPSILON = 1e-6;\n\n/**\n * Enforce the P1-1 rank ceiling: an insight may never outrank a primary\n * fact **it cites**. For each insight hit, if any fact it cites is\n * present in `factHits`, its score is lowered to strictly below that\n * cited fact's score - so concatenating the two lists and sorting by\n * score descending can never place the insight above the evidence it\n * was synthesized from. Insights whose cited facts are absent from\n * `factHits` are returned unchanged; this is a relative, not a global,\n * cap (per the execution plan: \"never outrank the primary facts they\n * cite\").\n *\n * Pure + deterministic - does not mutate its inputs.\n *\n * @stable\n */\nexport function capInsightsBelowFacts(\n  factHits: ReadonlyArray<MemoryHit<Fact>>,\n  insightHits: ReadonlyArray<MemoryHit<Insight>>,\n): ReadonlyArray<MemoryHit<Insight>> {\n  if (factHits.length === 0 || insightHits.length === 0) return insightHits;\n  const factScoreById = new Map<string, number>();\n  for (const hit of factHits) {\n    const prev = factScoreById.get(hit.record.id);\n    if (prev === undefined || hit.score > prev) factScoreById.set(hit.record.id, hit.score);\n  }\n  return insightHits.map((hit) => {\n    let citedMax = Number.NEGATIVE_INFINITY;\n    for (const id of hit.record.cites) {\n      const score = factScoreById.get(id);\n      if (score !== undefined && score > citedMax) citedMax = score;\n    }\n    // No cited fact present in the fused set, or already below it ⇒ keep.\n    if (citedMax === Number.NEGATIVE_INFINITY || hit.score < citedMax) return hit;\n    const capped = citedMax - RANK_CAP_EPSILON;\n    return {\n      ...hit,\n      score: capped,\n      signals: Object.freeze({ ...(hit.signals ?? {}), 'rank-cap': capped }),\n    };\n  });\n}\n"],"mappings":"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"}

package/dist/tiers/procedural-memory.d.ts

@@ -44,7 +44,7 @@ interface RuleInput {
 interface InduceOptions {
   /** Sensitivity of the stored procedure. Default `'internal'`. */
   readonly sensitivity?: Sensitivity;
-  /** Priority of the stored procedure. Default {@link INDUCED_PRIORITY} (40). */
+  /** Priority of the stored procedure. Default `INDUCED_PRIORITY` (40). */
   readonly priority?: number;
 }
 /**

package/dist/tiers/procedural-memory.js

@@ -1,8 +1,8 @@
 import { withMemorySpan } from "../internal/spans.js";
 import { ProcedureInductionNotConfiguredError, QuarantinePromotionRefusedError } from "../errors/index.js";
+import { detectMemoryInjection } from "../internal/injection-heuristics.js";
 import { runWorkflowInduction, trajectoryFromRunState } from "../consolidator/phases/induce.js";
 import { newMemoryId } from "../internal/id.js";
-import { detectMemoryInjection } from "../internal/injection-heuristics.js";
 
 //#region src/tiers/procedural-memory.ts
 /** Default priority for an *induced* procedure - below the author default
@@ -297,7 +297,7 @@ var ProceduralMemory = class {
 				}
 			}
 			span.setAttributes({ "memory.procedural.validate.forced": force });
-			await store.setStatus(ruleId, "active", reason);
+			await store.setStatus(ruleId, "active", reason, scope);
 		});
 	}
 };

package/dist/tiers/procedural-memory.js.map

@@ -1 +1 @@
-{"version":3,"file":"procedural-memory.js","names":["#store","#tracer","#inducer","#promoteAfterSuccesses","rule: Rule"],"sources":["../../src/tiers/procedural-memory.ts"],"sourcesContent":["import type {\n  MemoryHit,\n  MemoryOwner,\n  MemoryProvenance,\n  MemoryStatus,\n  Rule,\n  RunState,\n  Sensitivity,\n  SessionScope,\n  Tracer,\n} from '@graphorin/core';\nimport {\n  type InducedProcedure,\n  runWorkflowInduction,\n  type Trajectory,\n  trajectoryFromRunState,\n  type WorkflowInducer,\n} from '../consolidator/phases/induce.js';\nimport {\n  ProcedureInductionNotConfiguredError,\n  QuarantinePromotionRefusedError,\n} from '../errors/index.js';\nimport { newMemoryId } from '../internal/id.js';\nimport { detectMemoryInjection } from '../internal/injection-heuristics.js';\nimport { withMemorySpan } from '../internal/spans.js';\nimport type { MemoryStoreAdapter } from '../internal/storage-adapter.js';\n\n/** Default priority for an *induced* procedure - below the author default\n * (50) because an induced, still-quarantined procedure is provisional. */\nconst INDUCED_PRIORITY = 40;\n\n/**\n * Author-time rule payload accepted by {@link ProceduralMemory.define}.\n *\n * @stable\n */\nexport interface RuleInput {\n  readonly text: string;\n  /**\n   * Free-form predicate evaluated by {@link ProceduralMemory.activate}.\n   * The predicate language is intentionally narrow in v0.1: either\n   * the literal string `'always'`, or a `'topic=...'` / `'tag=...'`\n   * shorthand. Custom predicates should be expressed as a callable\n   * matched in `activate(...)`'s `customMatchers` argument.\n   */\n  readonly condition?: string;\n  /** Default `'public'` per DEC-126 - rules are NOT user data. */\n  readonly sensitivity?: Sensitivity;\n  readonly priority?: number;\n  readonly tags?: ReadonlyArray<string>;\n  /**\n   * Optional structured workflow payload (P2-2). Usually set by\n   * {@link ProceduralMemory.induce}, but accepted here so an author can\n   * round-trip a hand-written procedure. See {@link Rule.steps}.\n   */\n  readonly steps?: ReadonlyArray<string>;\n  /** Variable names abstracted into {@link RuleInput.steps} (P2-2). */\n  readonly variables?: ReadonlyArray<string>;\n  /** Verifiable success criteria stored with the procedure (P2-2). */\n  readonly successCriteria?: ReadonlyArray<string>;\n  /** Principal dimension (D3). Absent ⇒ NULL (treated `'user'`). */\n  readonly owner?: MemoryOwner;\n}\n\n/**\n * Options for {@link ProceduralMemory.induce}.\n *\n * @stable\n */\nexport interface InduceOptions {\n  /** Sensitivity of the stored procedure. Default `'internal'`. */\n  readonly sensitivity?: Sensitivity;\n  /** Priority of the stored procedure. Default {@link INDUCED_PRIORITY} (40). */\n  readonly priority?: number;\n}\n\n/**\n * Predicate context passed to {@link ProceduralMemory.activate}.\n *\n * @stable\n */\nexport interface RuleActivationContext {\n  readonly topic?: string;\n  readonly tags?: ReadonlyArray<string>;\n}\n\n/**\n * `ProceduralMemory` - standing orders activated when the agent's\n * current context matches the rule's predicate. The activation rules\n * are deterministic so the agent runtime + ContextEngine can render\n * the active set into the system prompt every step.\n *\n * P2-2 adds {@link ProceduralMemory.induce}: distil a reusable workflow\n * from a successful agent trajectory and store it **quarantined** (it must\n * not drive actions until validated). Quarantined procedures are excluded\n * from {@link ProceduralMemory.activate} but remain visible to\n * {@link ProceduralMemory.list}.\n *\n * @stable\n */\nexport class ProceduralMemory {\n  readonly #store: MemoryStoreAdapter;\n  readonly #tracer: Tracer;\n  /** Opt-in workflow inducer (P2-2). `null` ⇒ {@link induce} throws. */\n  readonly #inducer: WorkflowInducer | null;\n  /**\n   * Promotion-by-demonstrated-success threshold (MCON-2 part 4).\n   * `null` ⇒ outcomes are counted but never auto-promote.\n   */\n  readonly #promoteAfterSuccesses: number | null;\n\n  constructor(args: {\n    store: MemoryStoreAdapter;\n    tracer: Tracer;\n    inducer?: WorkflowInducer | null;\n    promoteAfterSuccesses?: number | null;\n  }) {\n    this.#store = args.store;\n    this.#tracer = args.tracer;\n    this.#inducer = args.inducer ?? null;\n    const k = args.promoteAfterSuccesses;\n    this.#promoteAfterSuccesses =\n      typeof k === 'number' && Number.isFinite(k) && k >= 1 ? Math.floor(k) : null;\n  }\n\n  /**\n   * Record the outcome of one demonstrated reuse of a procedure\n   * (MCON-2 part 4). A success increments the rule's persistent\n   * `successCount`; when `procedurePromotion.afterSuccesses` is\n   * configured and a QUARANTINED procedure reaches the threshold it is\n   * promoted through {@link validate} - the injection gate still\n   * applies, so a flagged text refuses promotion (surfaced as\n   * `refused: true`) no matter how many successes accumulate.\n   * Failures are observed but not persisted (no negative counter yet).\n   *\n   * Callers decide what \"success\" means - typically\n   * `checkSuccessCriteria(...)` over the procedure's stored\n   * `successCriteria`, or an operator's judgement.\n   *\n   * @stable\n   */\n  async recordOutcome(\n    scope: SessionScope,\n    ruleId: string,\n    succeeded: boolean,\n  ): Promise<{\n    readonly successCount: number;\n    readonly promoted: boolean;\n    readonly refused: boolean;\n  }> {\n    return withMemorySpan(\n      this.#tracer,\n      'memory.write.procedural',\n      scope,\n      { 'memory.procedural.action': 'record-outcome', 'memory.procedural.rule_id': ruleId },\n      async (span) => {\n        const store = this.#store.procedural;\n        if (!succeeded || typeof store.recordSuccess !== 'function') {\n          span.setAttributes({ 'memory.procedural.outcome.counted': false });\n          return { successCount: 0, promoted: false, refused: false };\n        }\n        const successCount = await store.recordSuccess(ruleId);\n        span.setAttributes({ 'memory.procedural.outcome.success_count': successCount });\n        const threshold = this.#promoteAfterSuccesses;\n        if (threshold === null || successCount < threshold) {\n          return { successCount, promoted: false, refused: false };\n        }\n        const existing = (await store.list(scope)).find((rule) => rule.id === ruleId) ?? null;\n        if (existing === null || existing.status !== 'quarantined') {\n          return { successCount, promoted: false, refused: false };\n        }\n        try {\n          await this.validate(\n            scope,\n            ruleId,\n            `demonstrated-success: ${successCount} >= ${threshold}`,\n          );\n          span.setAttributes({ 'memory.procedural.outcome.promoted': true });\n          return { successCount, promoted: true, refused: false };\n        } catch (err) {\n          if (err instanceof QuarantinePromotionRefusedError) {\n            span.setAttributes({ 'memory.procedural.outcome.refused': true });\n            return { successCount, promoted: false, refused: true };\n          }\n          throw err;\n        }\n      },\n    );\n  }\n\n  /** Persist a rule. Returns the stored record. */\n  async define(scope: SessionScope, input: RuleInput): Promise<Rule> {\n    return withMemorySpan(this.#tracer, 'memory.write.procedural', scope, {}, async (span) => {\n      const now = new Date().toISOString();\n      const rule: Rule = {\n        id: newMemoryId('rule'),\n        kind: 'procedural',\n        userId: scope.userId,\n        ...(scope.sessionId !== undefined ? { sessionId: scope.sessionId } : {}),\n        ...(scope.agentId !== undefined ? { agentId: scope.agentId } : {}),\n        sensitivity: input.sensitivity ?? 'public',\n        text: input.text,\n        ...(input.condition !== undefined ? { condition: input.condition } : {}),\n        priority: input.priority ?? 50,\n        ...(input.tags !== undefined ? { tags: Object.freeze([...input.tags]) } : {}),\n        ...(input.steps !== undefined ? { steps: Object.freeze([...input.steps]) } : {}),\n        ...(input.variables !== undefined\n          ? { variables: Object.freeze([...input.variables]) }\n          : {}),\n        ...(input.successCriteria !== undefined\n          ? { successCriteria: Object.freeze([...input.successCriteria]) }\n          : {}),\n        ...(input.owner !== undefined ? { owner: input.owner } : {}),\n        createdAt: now,\n        updatedAt: now,\n      };\n      await this.#store.procedural.add(rule);\n      span.setAttributes({\n        'memory.procedural.priority': rule.priority,\n        'memory.procedural.text_length': input.text.length,\n      });\n      return rule;\n    });\n  }\n\n  /**\n   * Induce a reusable procedure (P2-2) from a successful agent trajectory\n   * and store it **quarantined** + `provenance: 'induction'` (P1-4). Returns\n   * the stored {@link Rule}, or `null` when the trajectory was unsuccessful /\n   * empty or the inducer produced nothing inducible.\n   *\n   * Throws {@link ProcedureInductionNotConfiguredError} when no inducer was\n   * configured (`createMemory({ procedureInduction: { provider } })`).\n   */\n  async induce(\n    scope: SessionScope,\n    trajectory: Trajectory,\n    opts: InduceOptions = {},\n  ): Promise<Rule | null> {\n    const inducer = this.#inducer;\n    if (inducer === null) throw new ProcedureInductionNotConfiguredError();\n    return withMemorySpan(\n      this.#tracer,\n      'memory.write.procedural',\n      scope,\n      { 'memory.procedural.action': 'induce' },\n      async (span) => {\n        const induced = await runWorkflowInduction(trajectory, inducer, {});\n        if (induced === null) {\n          span.setAttributes({ 'memory.procedural.induced': 0 });\n          return null;\n        }\n        const now = new Date().toISOString();\n        const rule: Rule = {\n          id: newMemoryId('rule'),\n          kind: 'procedural',\n          userId: scope.userId,\n          ...(scope.sessionId !== undefined ? { sessionId: scope.sessionId } : {}),\n          ...(scope.agentId !== undefined ? { agentId: scope.agentId } : {}),\n          // Induced from a run ⇒ user-derived, so 'internal' (not the public\n          // default for author-defined rules).\n          sensitivity: opts.sensitivity ?? 'internal',\n          text: renderProcedureText(induced),\n          priority: opts.priority ?? INDUCED_PRIORITY,\n          steps: Object.freeze([...induced.steps]),\n          variables: Object.freeze([...induced.variables]),\n          successCriteria: Object.freeze([...induced.successCriteria]),\n          // Highest-poisoning-risk write in the system - procedures drive\n          // actions, so it lands quarantined + provenance-tagged (P1-4).\n          provenance: 'induction' satisfies MemoryProvenance,\n          status: 'quarantined' satisfies MemoryStatus,\n          // D3: an induced procedure is the agent's own inference.\n          owner: 'agent',\n          createdAt: now,\n          updatedAt: now,\n        };\n        await this.#store.procedural.add(rule);\n        span.setAttributes({\n          'memory.procedural.induced': 1,\n          'memory.procedural.steps': induced.steps.length,\n          'memory.procedural.variables': induced.variables.length,\n        });\n        return rule;\n      },\n    );\n  }\n\n  /**\n   * Convenience over {@link induce}: distil the {@link Trajectory} from a\n   * completed {@link RunState} (the agent's already-emitted run state) and\n   * induce a procedure. The success signal is `status === 'completed'`.\n   */\n  async induceFromRun(\n    scope: SessionScope,\n    run: RunState,\n    opts: InduceOptions = {},\n  ): Promise<Rule | null> {\n    return this.induce(scope, trajectoryFromRunState(run), opts);\n  }\n\n  /** Soft-delete a rule. */\n  async remove(scope: SessionScope, ruleId: string, reason?: string): Promise<void> {\n    await withMemorySpan(\n      this.#tracer,\n      'memory.write.procedural',\n      scope,\n      { 'memory.procedural.action': 'remove', 'memory.procedural.rule_id': ruleId },\n      async () => {\n        await this.#store.procedural.remove(ruleId, reason);\n      },\n    );\n  }\n\n  /** List every active (non-deleted) rule for the supplied scope. */\n  async list(scope: SessionScope): Promise<ReadonlyArray<Rule>> {\n    return withMemorySpan(this.#tracer, 'memory.read.procedural', scope, {}, async (span) => {\n      const out = await this.#store.procedural.list(scope);\n      span.setAttributes({ 'memory.read.procedural.count': out.length });\n      return out;\n    });\n  }\n\n  /**\n   * Return the rules active under `context`. Rules without a\n   * `condition` are always active; the bundled predicate vocabulary\n   * supports the literals `'always'`, `'topic=<topic>'`, and\n   * `'tag=<tag>'`. Anything outside that grammar is treated as\n   * always-active so callers do not silently lose rules.\n   *\n   * **Quarantined procedures are excluded** (P1-4 / P2-2): an induced\n   * procedure must not drive actions until validated, so activation - which\n   * feeds the system prompt - never surfaces it.\n   */\n  async activate(\n    scope: SessionScope,\n    context: RuleActivationContext = {},\n  ): Promise<ReadonlyArray<Rule>> {\n    const rules = await this.list(scope);\n    return rules\n      .filter((rule) => rule.status !== 'quarantined' && predicateMatches(rule, context))\n      .sort((a, b) => b.priority - a.priority);\n  }\n\n  /**\n   * Runbook content search (D3): \"find the procedure for this task\" -\n   * lexical recall over rule text, as opposed to predicate\n   * {@link activate}. Returns **whole validated procedures** (the full\n   * {@link Rule} incl. steps / variables / success criteria) so a match\n   * can be followed file-style rather than re-synthesized from\n   * fragments. Quarantined (unvalidated induced) procedures are\n   * excluded - they must not drive actions - unless the inspector opts\n   * in via `includeQuarantined`.\n   *\n   * Uses the storage adapter's FTS surface when available\n   * (`procedural.search`, the default `@graphorin/store-sqlite` adapter\n   * implements it via migration 028); otherwise degrades to an offline\n   * in-memory token-overlap scan over {@link list}, so custom adapters\n   * keep working without the index.\n   */\n  async search(\n    scope: SessionScope,\n    query: string,\n    opts: { readonly topK?: number; readonly includeQuarantined?: boolean } = {},\n  ): Promise<ReadonlyArray<MemoryHit<Rule>>> {\n    return withMemorySpan(\n      this.#tracer,\n      'memory.read.procedural',\n      scope,\n      { 'memory.procedural.action': 'search' },\n      async (span) => {\n        const topK = opts.topK ?? 5;\n        const store = this.#store.procedural;\n        if (typeof store.search === 'function') {\n          const hits = await store.search(scope, query, {\n            topK,\n            ...(opts.includeQuarantined === true ? { includeQuarantined: true } : {}),\n          });\n          span.setAttributes({\n            'memory.read.procedural.count': hits.length,\n            'memory.read.procedural.search_backend': 'store',\n          });\n          return hits;\n        }\n        // Fallback: offline token-overlap scoring over list(). Coarse by\n        // design - it exists so the runbook surface degrades instead of\n        // disappearing on adapters without an FTS index.\n        const tokens = tokenizeForRunbook(query);\n        const rules = await this.list(scope);\n        const scored = rules\n          .filter((rule) => opts.includeQuarantined === true || rule.status !== 'quarantined')\n          .map((rule) => {\n            const haystack = tokenizeForRunbook(\n              [rule.text, ...(rule.steps ?? []), ...(rule.tags ?? [])].join(' '),\n            );\n            const overlap = tokens.filter((t) => haystack.includes(t)).length;\n            return { rule, overlap };\n          })\n          .filter((entry) => entry.overlap > 0)\n          .sort((a, b) => b.overlap - a.overlap || (a.rule.id < b.rule.id ? -1 : 1))\n          .slice(0, topK);\n        span.setAttributes({\n          'memory.read.procedural.count': scored.length,\n          'memory.read.procedural.search_backend': 'fallback',\n        });\n        return scored.map((entry) => ({\n          record: entry.rule,\n          score: tokens.length === 0 ? 0 : entry.overlap / tokens.length,\n          signals: { lexical: entry.overlap },\n        }));\n      },\n    );\n  }\n\n  /**\n   * Promote a quarantined (induced) procedure into `activate()` (MCON-2).\n   * Mirrors {@link SemanticMemory.validate}: re-derives the injection verdict\n   * from the stored rule text and **refuses** promotion of an injection-flagged\n   * procedure unless an operator passes `{ force: true }`. Induced procedures\n   * drive *actions*, so this gate matters most for them.\n   */\n  async validate(\n    scope: SessionScope,\n    ruleId: string,\n    reason?: string,\n    options?: { readonly force?: boolean },\n  ): Promise<void> {\n    await withMemorySpan(\n      this.#tracer,\n      'memory.write.procedural',\n      scope,\n      { 'memory.procedural.action': 'validate', 'memory.procedural.rule_id': ruleId },\n      async (span) => {\n        const store = this.#store.procedural;\n        if (typeof store.setStatus !== 'function') {\n          throw new TypeError(\n            '[graphorin/memory] ProceduralMemory.validate(...) requires a storage adapter that implements `procedural.setStatus(id, status)`. ' +\n              'The default `@graphorin/store-sqlite` adapter implements it; custom adapters can opt in via ProceduralMemoryStoreExt.',\n          );\n        }\n        const force = options?.force === true;\n        // No store get-by-id for rules - list() already surfaces quarantined.\n        const existing = (await store.list(scope)).find((rule) => rule.id === ruleId) ?? null;\n        if (existing !== null && !force) {\n          const injection = detectMemoryInjection(existing.text);\n          if (injection.flagged) {\n            span.setAttributes({ 'memory.procedural.validate.refused': true });\n            throw new QuarantinePromotionRefusedError(ruleId, injection.markers);\n          }\n        }\n        span.setAttributes({ 'memory.procedural.validate.forced': force });\n        await store.setStatus(ruleId, 'active', reason);\n      },\n    );\n  }\n}\n\n/** Render an induced procedure into the human-readable `Rule.text`. */\nfunction renderProcedureText(procedure: InducedProcedure): string {\n  const lines = [procedure.title, ...procedure.steps.map((step, i) => `${i + 1}. ${step}`)];\n  return lines.join('\\n');\n}\n\n/** Lowercased word tokens for the offline runbook-search fallback (D3). */\nfunction tokenizeForRunbook(text: string): ReadonlyArray<string> {\n  return text\n    .toLowerCase()\n    .split(/[^\\p{L}\\p{N}]+/u)\n    .filter((token) => token.length > 1);\n}\n\nfunction predicateMatches(rule: Rule, context: RuleActivationContext): boolean {\n  if (rule.condition === undefined || rule.condition === 'always') return true;\n  if (rule.condition.startsWith('topic=')) {\n    const wanted = rule.condition.slice('topic='.length).trim();\n    return context.topic === wanted;\n  }\n  if (rule.condition.startsWith('tag=')) {\n    const wanted = rule.condition.slice('tag='.length).trim();\n    return (context.tags ?? []).includes(wanted);\n  }\n  return true;\n}\n"],"mappings":"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"}
+{"version":3,"file":"procedural-memory.js","names":["#store","#tracer","#inducer","#promoteAfterSuccesses","rule: Rule"],"sources":["../../src/tiers/procedural-memory.ts"],"sourcesContent":["import type {\n  MemoryHit,\n  MemoryOwner,\n  MemoryProvenance,\n  MemoryStatus,\n  Rule,\n  RunState,\n  Sensitivity,\n  SessionScope,\n  Tracer,\n} from '@graphorin/core';\nimport {\n  type InducedProcedure,\n  runWorkflowInduction,\n  type Trajectory,\n  trajectoryFromRunState,\n  type WorkflowInducer,\n} from '../consolidator/phases/induce.js';\nimport {\n  ProcedureInductionNotConfiguredError,\n  QuarantinePromotionRefusedError,\n} from '../errors/index.js';\nimport { newMemoryId } from '../internal/id.js';\nimport { detectMemoryInjection } from '../internal/injection-heuristics.js';\nimport { withMemorySpan } from '../internal/spans.js';\nimport type { MemoryStoreAdapter } from '../internal/storage-adapter.js';\n\n/** Default priority for an *induced* procedure - below the author default\n * (50) because an induced, still-quarantined procedure is provisional. */\nconst INDUCED_PRIORITY = 40;\n\n/**\n * Author-time rule payload accepted by {@link ProceduralMemory.define}.\n *\n * @stable\n */\nexport interface RuleInput {\n  readonly text: string;\n  /**\n   * Free-form predicate evaluated by {@link ProceduralMemory.activate}.\n   * The predicate language is intentionally narrow in v0.1: either\n   * the literal string `'always'`, or a `'topic=...'` / `'tag=...'`\n   * shorthand. Custom predicates should be expressed as a callable\n   * matched in `activate(...)`'s `customMatchers` argument.\n   */\n  readonly condition?: string;\n  /** Default `'public'` per DEC-126 - rules are NOT user data. */\n  readonly sensitivity?: Sensitivity;\n  readonly priority?: number;\n  readonly tags?: ReadonlyArray<string>;\n  /**\n   * Optional structured workflow payload (P2-2). Usually set by\n   * {@link ProceduralMemory.induce}, but accepted here so an author can\n   * round-trip a hand-written procedure. See {@link Rule.steps}.\n   */\n  readonly steps?: ReadonlyArray<string>;\n  /** Variable names abstracted into {@link RuleInput.steps} (P2-2). */\n  readonly variables?: ReadonlyArray<string>;\n  /** Verifiable success criteria stored with the procedure (P2-2). */\n  readonly successCriteria?: ReadonlyArray<string>;\n  /** Principal dimension (D3). Absent ⇒ NULL (treated `'user'`). */\n  readonly owner?: MemoryOwner;\n}\n\n/**\n * Options for {@link ProceduralMemory.induce}.\n *\n * @stable\n */\nexport interface InduceOptions {\n  /** Sensitivity of the stored procedure. Default `'internal'`. */\n  readonly sensitivity?: Sensitivity;\n  /** Priority of the stored procedure. Default `INDUCED_PRIORITY` (40). */\n  readonly priority?: number;\n}\n\n/**\n * Predicate context passed to {@link ProceduralMemory.activate}.\n *\n * @stable\n */\nexport interface RuleActivationContext {\n  readonly topic?: string;\n  readonly tags?: ReadonlyArray<string>;\n}\n\n/**\n * `ProceduralMemory` - standing orders activated when the agent's\n * current context matches the rule's predicate. The activation rules\n * are deterministic so the agent runtime + ContextEngine can render\n * the active set into the system prompt every step.\n *\n * P2-2 adds {@link ProceduralMemory.induce}: distil a reusable workflow\n * from a successful agent trajectory and store it **quarantined** (it must\n * not drive actions until validated). Quarantined procedures are excluded\n * from {@link ProceduralMemory.activate} but remain visible to\n * {@link ProceduralMemory.list}.\n *\n * @stable\n */\nexport class ProceduralMemory {\n  readonly #store: MemoryStoreAdapter;\n  readonly #tracer: Tracer;\n  /** Opt-in workflow inducer (P2-2). `null` ⇒ {@link induce} throws. */\n  readonly #inducer: WorkflowInducer | null;\n  /**\n   * Promotion-by-demonstrated-success threshold (MCON-2 part 4).\n   * `null` ⇒ outcomes are counted but never auto-promote.\n   */\n  readonly #promoteAfterSuccesses: number | null;\n\n  constructor(args: {\n    store: MemoryStoreAdapter;\n    tracer: Tracer;\n    inducer?: WorkflowInducer | null;\n    promoteAfterSuccesses?: number | null;\n  }) {\n    this.#store = args.store;\n    this.#tracer = args.tracer;\n    this.#inducer = args.inducer ?? null;\n    const k = args.promoteAfterSuccesses;\n    this.#promoteAfterSuccesses =\n      typeof k === 'number' && Number.isFinite(k) && k >= 1 ? Math.floor(k) : null;\n  }\n\n  /**\n   * Record the outcome of one demonstrated reuse of a procedure\n   * (MCON-2 part 4). A success increments the rule's persistent\n   * `successCount`; when `procedurePromotion.afterSuccesses` is\n   * configured and a QUARANTINED procedure reaches the threshold it is\n   * promoted through {@link validate} - the injection gate still\n   * applies, so a flagged text refuses promotion (surfaced as\n   * `refused: true`) no matter how many successes accumulate.\n   * Failures are observed but not persisted (no negative counter yet).\n   *\n   * Callers decide what \"success\" means - typically\n   * `checkSuccessCriteria(...)` over the procedure's stored\n   * `successCriteria`, or an operator's judgement.\n   *\n   * @stable\n   */\n  async recordOutcome(\n    scope: SessionScope,\n    ruleId: string,\n    succeeded: boolean,\n  ): Promise<{\n    readonly successCount: number;\n    readonly promoted: boolean;\n    readonly refused: boolean;\n  }> {\n    return withMemorySpan(\n      this.#tracer,\n      'memory.write.procedural',\n      scope,\n      { 'memory.procedural.action': 'record-outcome', 'memory.procedural.rule_id': ruleId },\n      async (span) => {\n        const store = this.#store.procedural;\n        if (!succeeded || typeof store.recordSuccess !== 'function') {\n          span.setAttributes({ 'memory.procedural.outcome.counted': false });\n          return { successCount: 0, promoted: false, refused: false };\n        }\n        const successCount = await store.recordSuccess(ruleId);\n        span.setAttributes({ 'memory.procedural.outcome.success_count': successCount });\n        const threshold = this.#promoteAfterSuccesses;\n        if (threshold === null || successCount < threshold) {\n          return { successCount, promoted: false, refused: false };\n        }\n        const existing = (await store.list(scope)).find((rule) => rule.id === ruleId) ?? null;\n        if (existing === null || existing.status !== 'quarantined') {\n          return { successCount, promoted: false, refused: false };\n        }\n        try {\n          await this.validate(\n            scope,\n            ruleId,\n            `demonstrated-success: ${successCount} >= ${threshold}`,\n          );\n          span.setAttributes({ 'memory.procedural.outcome.promoted': true });\n          return { successCount, promoted: true, refused: false };\n        } catch (err) {\n          if (err instanceof QuarantinePromotionRefusedError) {\n            span.setAttributes({ 'memory.procedural.outcome.refused': true });\n            return { successCount, promoted: false, refused: true };\n          }\n          throw err;\n        }\n      },\n    );\n  }\n\n  /** Persist a rule. Returns the stored record. */\n  async define(scope: SessionScope, input: RuleInput): Promise<Rule> {\n    return withMemorySpan(this.#tracer, 'memory.write.procedural', scope, {}, async (span) => {\n      const now = new Date().toISOString();\n      const rule: Rule = {\n        id: newMemoryId('rule'),\n        kind: 'procedural',\n        userId: scope.userId,\n        ...(scope.sessionId !== undefined ? { sessionId: scope.sessionId } : {}),\n        ...(scope.agentId !== undefined ? { agentId: scope.agentId } : {}),\n        sensitivity: input.sensitivity ?? 'public',\n        text: input.text,\n        ...(input.condition !== undefined ? { condition: input.condition } : {}),\n        priority: input.priority ?? 50,\n        ...(input.tags !== undefined ? { tags: Object.freeze([...input.tags]) } : {}),\n        ...(input.steps !== undefined ? { steps: Object.freeze([...input.steps]) } : {}),\n        ...(input.variables !== undefined\n          ? { variables: Object.freeze([...input.variables]) }\n          : {}),\n        ...(input.successCriteria !== undefined\n          ? { successCriteria: Object.freeze([...input.successCriteria]) }\n          : {}),\n        ...(input.owner !== undefined ? { owner: input.owner } : {}),\n        createdAt: now,\n        updatedAt: now,\n      };\n      await this.#store.procedural.add(rule);\n      span.setAttributes({\n        'memory.procedural.priority': rule.priority,\n        'memory.procedural.text_length': input.text.length,\n      });\n      return rule;\n    });\n  }\n\n  /**\n   * Induce a reusable procedure (P2-2) from a successful agent trajectory\n   * and store it **quarantined** + `provenance: 'induction'` (P1-4). Returns\n   * the stored {@link Rule}, or `null` when the trajectory was unsuccessful /\n   * empty or the inducer produced nothing inducible.\n   *\n   * Throws {@link ProcedureInductionNotConfiguredError} when no inducer was\n   * configured (`createMemory({ procedureInduction: { provider } })`).\n   */\n  async induce(\n    scope: SessionScope,\n    trajectory: Trajectory,\n    opts: InduceOptions = {},\n  ): Promise<Rule | null> {\n    const inducer = this.#inducer;\n    if (inducer === null) throw new ProcedureInductionNotConfiguredError();\n    return withMemorySpan(\n      this.#tracer,\n      'memory.write.procedural',\n      scope,\n      { 'memory.procedural.action': 'induce' },\n      async (span) => {\n        const induced = await runWorkflowInduction(trajectory, inducer, {});\n        if (induced === null) {\n          span.setAttributes({ 'memory.procedural.induced': 0 });\n          return null;\n        }\n        const now = new Date().toISOString();\n        const rule: Rule = {\n          id: newMemoryId('rule'),\n          kind: 'procedural',\n          userId: scope.userId,\n          ...(scope.sessionId !== undefined ? { sessionId: scope.sessionId } : {}),\n          ...(scope.agentId !== undefined ? { agentId: scope.agentId } : {}),\n          // Induced from a run ⇒ user-derived, so 'internal' (not the public\n          // default for author-defined rules).\n          sensitivity: opts.sensitivity ?? 'internal',\n          text: renderProcedureText(induced),\n          priority: opts.priority ?? INDUCED_PRIORITY,\n          steps: Object.freeze([...induced.steps]),\n          variables: Object.freeze([...induced.variables]),\n          successCriteria: Object.freeze([...induced.successCriteria]),\n          // Highest-poisoning-risk write in the system - procedures drive\n          // actions, so it lands quarantined + provenance-tagged (P1-4).\n          provenance: 'induction' satisfies MemoryProvenance,\n          status: 'quarantined' satisfies MemoryStatus,\n          // D3: an induced procedure is the agent's own inference.\n          owner: 'agent',\n          createdAt: now,\n          updatedAt: now,\n        };\n        await this.#store.procedural.add(rule);\n        span.setAttributes({\n          'memory.procedural.induced': 1,\n          'memory.procedural.steps': induced.steps.length,\n          'memory.procedural.variables': induced.variables.length,\n        });\n        return rule;\n      },\n    );\n  }\n\n  /**\n   * Convenience over {@link induce}: distil the {@link Trajectory} from a\n   * completed {@link RunState} (the agent's already-emitted run state) and\n   * induce a procedure. The success signal is `status === 'completed'`.\n   */\n  async induceFromRun(\n    scope: SessionScope,\n    run: RunState,\n    opts: InduceOptions = {},\n  ): Promise<Rule | null> {\n    return this.induce(scope, trajectoryFromRunState(run), opts);\n  }\n\n  /** Soft-delete a rule. */\n  async remove(scope: SessionScope, ruleId: string, reason?: string): Promise<void> {\n    await withMemorySpan(\n      this.#tracer,\n      'memory.write.procedural',\n      scope,\n      { 'memory.procedural.action': 'remove', 'memory.procedural.rule_id': ruleId },\n      async () => {\n        await this.#store.procedural.remove(ruleId, reason);\n      },\n    );\n  }\n\n  /** List every active (non-deleted) rule for the supplied scope. */\n  async list(scope: SessionScope): Promise<ReadonlyArray<Rule>> {\n    return withMemorySpan(this.#tracer, 'memory.read.procedural', scope, {}, async (span) => {\n      const out = await this.#store.procedural.list(scope);\n      span.setAttributes({ 'memory.read.procedural.count': out.length });\n      return out;\n    });\n  }\n\n  /**\n   * Return the rules active under `context`. Rules without a\n   * `condition` are always active; the bundled predicate vocabulary\n   * supports the literals `'always'`, `'topic=<topic>'`, and\n   * `'tag=<tag>'`. Anything outside that grammar is treated as\n   * always-active so callers do not silently lose rules.\n   *\n   * **Quarantined procedures are excluded** (P1-4 / P2-2): an induced\n   * procedure must not drive actions until validated, so activation - which\n   * feeds the system prompt - never surfaces it.\n   */\n  async activate(\n    scope: SessionScope,\n    context: RuleActivationContext = {},\n  ): Promise<ReadonlyArray<Rule>> {\n    const rules = await this.list(scope);\n    return rules\n      .filter((rule) => rule.status !== 'quarantined' && predicateMatches(rule, context))\n      .sort((a, b) => b.priority - a.priority);\n  }\n\n  /**\n   * Runbook content search (D3): \"find the procedure for this task\" -\n   * lexical recall over rule text, as opposed to predicate\n   * {@link activate}. Returns **whole validated procedures** (the full\n   * {@link Rule} incl. steps / variables / success criteria) so a match\n   * can be followed file-style rather than re-synthesized from\n   * fragments. Quarantined (unvalidated induced) procedures are\n   * excluded - they must not drive actions - unless the inspector opts\n   * in via `includeQuarantined`.\n   *\n   * Uses the storage adapter's FTS surface when available\n   * (`procedural.search`, the default `@graphorin/store-sqlite` adapter\n   * implements it via migration 028); otherwise degrades to an offline\n   * in-memory token-overlap scan over {@link list}, so custom adapters\n   * keep working without the index.\n   */\n  async search(\n    scope: SessionScope,\n    query: string,\n    opts: { readonly topK?: number; readonly includeQuarantined?: boolean } = {},\n  ): Promise<ReadonlyArray<MemoryHit<Rule>>> {\n    return withMemorySpan(\n      this.#tracer,\n      'memory.read.procedural',\n      scope,\n      { 'memory.procedural.action': 'search' },\n      async (span) => {\n        const topK = opts.topK ?? 5;\n        const store = this.#store.procedural;\n        if (typeof store.search === 'function') {\n          const hits = await store.search(scope, query, {\n            topK,\n            ...(opts.includeQuarantined === true ? { includeQuarantined: true } : {}),\n          });\n          span.setAttributes({\n            'memory.read.procedural.count': hits.length,\n            'memory.read.procedural.search_backend': 'store',\n          });\n          return hits;\n        }\n        // Fallback: offline token-overlap scoring over list(). Coarse by\n        // design - it exists so the runbook surface degrades instead of\n        // disappearing on adapters without an FTS index.\n        const tokens = tokenizeForRunbook(query);\n        const rules = await this.list(scope);\n        const scored = rules\n          .filter((rule) => opts.includeQuarantined === true || rule.status !== 'quarantined')\n          .map((rule) => {\n            const haystack = tokenizeForRunbook(\n              [rule.text, ...(rule.steps ?? []), ...(rule.tags ?? [])].join(' '),\n            );\n            const overlap = tokens.filter((t) => haystack.includes(t)).length;\n            return { rule, overlap };\n          })\n          .filter((entry) => entry.overlap > 0)\n          .sort((a, b) => b.overlap - a.overlap || (a.rule.id < b.rule.id ? -1 : 1))\n          .slice(0, topK);\n        span.setAttributes({\n          'memory.read.procedural.count': scored.length,\n          'memory.read.procedural.search_backend': 'fallback',\n        });\n        return scored.map((entry) => ({\n          record: entry.rule,\n          score: tokens.length === 0 ? 0 : entry.overlap / tokens.length,\n          signals: { lexical: entry.overlap },\n        }));\n      },\n    );\n  }\n\n  /**\n   * Promote a quarantined (induced) procedure into `activate()` (MCON-2).\n   * Mirrors {@link SemanticMemory.validate}: re-derives the injection verdict\n   * from the stored rule text and **refuses** promotion of an injection-flagged\n   * procedure unless an operator passes `{ force: true }`. Induced procedures\n   * drive *actions*, so this gate matters most for them.\n   */\n  async validate(\n    scope: SessionScope,\n    ruleId: string,\n    reason?: string,\n    options?: { readonly force?: boolean },\n  ): Promise<void> {\n    await withMemorySpan(\n      this.#tracer,\n      'memory.write.procedural',\n      scope,\n      { 'memory.procedural.action': 'validate', 'memory.procedural.rule_id': ruleId },\n      async (span) => {\n        const store = this.#store.procedural;\n        if (typeof store.setStatus !== 'function') {\n          throw new TypeError(\n            '[graphorin/memory] ProceduralMemory.validate(...) requires a storage adapter that implements `procedural.setStatus(id, status)`. ' +\n              'The default `@graphorin/store-sqlite` adapter implements it; custom adapters can opt in via ProceduralMemoryStoreExt.',\n          );\n        }\n        const force = options?.force === true;\n        // No store get-by-id for rules - list() already surfaces quarantined.\n        const existing = (await store.list(scope)).find((rule) => rule.id === ruleId) ?? null;\n        if (existing !== null && !force) {\n          const injection = detectMemoryInjection(existing.text);\n          if (injection.flagged) {\n            span.setAttributes({ 'memory.procedural.validate.refused': true });\n            throw new QuarantinePromotionRefusedError(ruleId, injection.markers);\n          }\n        }\n        span.setAttributes({ 'memory.procedural.validate.forced': force });\n        await store.setStatus(ruleId, 'active', reason, scope);\n      },\n    );\n  }\n}\n\n/** Render an induced procedure into the human-readable `Rule.text`. */\nfunction renderProcedureText(procedure: InducedProcedure): string {\n  const lines = [procedure.title, ...procedure.steps.map((step, i) => `${i + 1}. ${step}`)];\n  return lines.join('\\n');\n}\n\n/** Lowercased word tokens for the offline runbook-search fallback (D3). */\nfunction tokenizeForRunbook(text: string): ReadonlyArray<string> {\n  return text\n    .toLowerCase()\n    .split(/[^\\p{L}\\p{N}]+/u)\n    .filter((token) => token.length > 1);\n}\n\nfunction predicateMatches(rule: Rule, context: RuleActivationContext): boolean {\n  if (rule.condition === undefined || rule.condition === 'always') return true;\n  if (rule.condition.startsWith('topic=')) {\n    const wanted = rule.condition.slice('topic='.length).trim();\n    return context.topic === wanted;\n  }\n  if (rule.condition.startsWith('tag=')) {\n    const wanted = rule.condition.slice('tag='.length).trim();\n    return (context.tags ?? []).includes(wanted);\n  }\n  return true;\n}\n"],"mappings":"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"}

package/dist/tiers/semantic-memory.d.ts

@@ -105,6 +105,20 @@ type FusionStrategy = {
  *
  * @stable
  */
+/**
+ * Search options an operator may default at construction time via
+ * `createMemory({ searchDefaults })` (W-086) - the advanced-retrieval
+ * switches (fan-out, HyDE, graph expansion, fusion, decay) that the
+ * model-facing surfaces (`fact_search`, auto-recall, `deep_recall`)
+ * cannot reach per-call. Deliberately a `Pick` that EXCLUDES the
+ * trust-sensitive predicates (`includeQuarantined`, `includeSuperseded`,
+ * `trustWeighting`, `owner`): configuration must not be able to silently
+ * weaken trust gates for every caller. Per-call options always win
+ * key-by-key.
+ *
+ * @stable
+ */
+type SemanticSearchDefaults = Pick<FactSearchOptions, 'multiQuery' | 'hyde' | 'expandHops' | 'entityMatch' | 'graphScoring' | 'fusion' | 'decay' | 'candidateTopK'>;
 interface FactSearchOptions {
   readonly topK?: number;
   readonly signal?: AbortSignal;
@@ -287,6 +301,14 @@ interface IterativeSearchOptions extends FactSearchOptions {
    * requests and tests.
    */
   readonly forceHard?: boolean;
+  /**
+   * Difficulty-gate threshold in `[0, 1]` for THIS call (W-088). The
+   * gate's signal lexicon is **English-only** - for non-English
+   * deployments lower the threshold or use {@link forceHard}. Omitted ⇒
+   * the facade default (`iterativeRetrieval.difficultyThreshold`) or the
+   * built-in `0.5`.
+   */
+  readonly difficultyThreshold?: number;
 }
 /**
  * Outcome of {@link SemanticMemory.searchIterative}. Beyond the ranked
@@ -407,12 +429,27 @@ declare class SemanticMemory {
     grader?: RetrievalGrader;
     /** Default total-pass cap for `searchIterative`. Default 3. */
     iterativeMaxIterations?: number;
+    /**
+     * Default difficulty-gate threshold for `searchIterative` (W-088).
+     * Omitted ⇒ the gate's built-in `0.5`. Per-call
+     * `difficultyThreshold` overrides it.
+     */
+    iterativeDifficultyThreshold?: number;
     /**
      * Weights for the rank-time trust discount (C5). Reuses the
      * eviction-path `SalienceWeights` semantics; defaults to
      * `DEFAULT_SALIENCE_WEIGHTS`.
      */
     trustWeights?: SalienceWeights;
+    /**
+     * Construction-time retrieval defaults (W-086) merged under every
+     * `search(...)` call - see {@link SemanticSearchDefaults}. Because
+     * the merge happens inside `search()`, the model-facing surfaces
+     * (`fact_search`, auto-recall, `deep_recall`) inherit them without
+     * any per-surface wiring; per-call options override key-by-key (so
+     * e.g. `deep_recall`'s widen-pass `expandHops` still wins).
+     */
+    searchDefaults?: SemanticSearchDefaults;
   });
   /** Replace the active reranker. Returns the previous instance. */
   setReranker(reranker: ReRanker): ReRanker;
@@ -435,7 +472,7 @@ declare class SemanticMemory {
    */
   rememberWithDecision(scope: SessionScope, input: FactInput, options?: FactRememberOptions): Promise<RememberOutcome>;
   /** Hybrid (vector + FTS5) search merged through the configured reranker. */
-  search(scope: SessionScope, query: string, opts?: FactSearchOptions): Promise<ReadonlyArray<MemoryHit<Fact>>>;
+  search(scope: SessionScope, query: string, callOpts?: FactSearchOptions): Promise<ReadonlyArray<MemoryHit<Fact>>>;
   /**
    * Gated, iterative ("deep") recall for hard queries (P2-4). A cheap
    * local heuristic ({@link assessQueryDifficulty}) decides whether the
@@ -507,8 +544,25 @@ declare class SemanticMemory {
   validate(scope: SessionScope, factId: string, reason?: string, options?: {
     readonly force?: boolean;
   }): Promise<void>;
-  /** Mark `oldId` superseded by a new fact. Returns the new record. */
-  supersede(scope: SessionScope, oldId: string, newInput: FactInput, reason?: string): Promise<{
+  /**
+   * Mark `oldId` superseded by a new fact. Returns the new record.
+   *
+   * W-019 (security-first, knowledge-preserving): when the successor
+   * lands QUARANTINED (the default for `extraction`/synthesized
+   * provenance), the old ACTIVE fact's validity interval is NOT closed
+   * - default recall keeps returning the old knowledge until the
+   * successor passes {@link validate}, which completes the closure.
+   * The link is recorded on the successor's `supersedes` field. With
+   * `autoPromoteSynthesized` (threaded from the consolidator's
+   * `autoPromoteExtraction` escape hatch) an injection-clean successor
+   * is active immediately and the interval closes right away - the
+   * pre-W-019 behaviour. Inverting the default (auto-activating the
+   * successor) would hand a MINJA attacker instant active memory via
+   * any text the reconciler classifies as an 'update'.
+   */
+  supersede(scope: SessionScope, oldId: string, newInput: FactInput, reason?: string, options?: {
+    readonly autoPromoteSynthesized?: boolean;
+  }): Promise<{
     readonly old: string;
     readonly new: Fact;
   }>;
@@ -538,5 +592,5 @@ declare class SemanticMemory {
   static fuseWeighted<TRecord extends Fact>(lists: ReadonlyArray<ReadonlyArray<MemoryHit<TRecord>>>, weights: ReadonlyArray<number> | undefined, k?: number): ReadonlyArray<MemoryHit<TRecord>>;
 }
 //#endregion
-export { FactInput, FactRememberOptions, FactSearchOptions, FusionStrategy, FusionWeights, IterativeRecallResult, IterativeSearchOptions, RememberOutcome, SemanticMemory };
+export { FactInput, FactRememberOptions, FactSearchOptions, FusionStrategy, FusionWeights, IterativeRecallResult, IterativeSearchOptions, RememberOutcome, SemanticMemory, SemanticSearchDefaults };
 //# sourceMappingURL=semantic-memory.d.ts.map

package/dist/tiers/semantic-memory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"semantic-memory.d.ts","names":[],"sources":["../../src/tiers/semantic-memory.ts"],"sourcesContent":[],"mappings":"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"}
+{"version":3,"file":"semantic-memory.d.ts","names":[],"sources":["../../src/tiers/semantic-memory.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/tiers/semantic-memory.js

@@ -1,12 +1,12 @@
 import { withMemorySpan } from "../internal/spans.js";
 import { DEFAULT_SALIENCE_WEIGHTS } from "../consolidator/decay.js";
 import { QuarantinePromotionRefusedError } from "../errors/index.js";
+import { detectMemoryInjection } from "../internal/injection-heuristics.js";
 import { contextualize } from "../internal/contextualize.js";
 import { newMemoryId } from "../internal/id.js";
 import { normalizeEntityName } from "../graph/entity-resolver.js";
 import { DEFAULT_MAX_ITERATIONS, runIterativeRetrieval } from "../search/iterative.js";
 import { WeightedRRFReranker, fuseRrf, fuseWeighted } from "../search/rrf.js";
-import { detectMemoryInjection } from "../internal/injection-heuristics.js";
 import { explainRecall } from "../search/explain.js";
 import { pprActivation } from "../search/graph-ppr.js";
 import { trustDiscount } from "../search/trust.js";
@@ -37,8 +37,10 @@ var SemanticMemory = class {
 	#entityResolver;
 	#grader;
 	#iterativeMaxIterations;
+	#iterativeDifficultyThreshold;
 	#reranker;
 	#trustWeights;
+	#searchDefaults;
 	constructor(args) {
 		this.#store = args.store;
 		this.#tracer = args.tracer;
@@ -51,7 +53,9 @@ var SemanticMemory = class {
 		this.#entityResolver = args.entityResolver ?? null;
 		this.#grader = args.grader ?? null;
 		this.#iterativeMaxIterations = args.iterativeMaxIterations ?? DEFAULT_MAX_ITERATIONS;
+		this.#iterativeDifficultyThreshold = args.iterativeDifficultyThreshold;
 		this.#trustWeights = args.trustWeights ?? DEFAULT_SALIENCE_WEIGHTS;
+		this.#searchDefaults = args.searchDefaults ?? {};
 	}
 	/** Replace the active reranker. Returns the previous instance. */
 	setReranker(reranker) {
@@ -230,7 +234,11 @@ var SemanticMemory = class {
 		} catch {}
 	}
 	/** Hybrid (vector + FTS5) search merged through the configured reranker. */
-	async search(scope, query, opts = {}) {
+	async search(scope, query, callOpts = {}) {
+		const opts = {
+			...this.#searchDefaults,
+			...callOpts
+		};
 		return withMemorySpan(this.#tracer, "memory.search.semantic", scope, { "memory.search.query_length": query.length }, async (span) => {
 			const candidateTopK = opts.candidateTopK ?? 60;
 			const finalTopK = opts.topK ?? 10;
@@ -240,6 +248,8 @@ var SemanticMemory = class {
 			const wGraph = weighted?.weights.graph ?? 1;
 			const wEntity = weighted?.weights.entity ?? 1;
 			const queries = await this.#expandQueries(query, opts);
+			const variantVectors = await this.#tryBatchEmbedQueries(queries);
+			const hydeHitsPromise = this.#tryHyde(scope, query, opts, candidateTopK);
 			const lists = [];
 			const listWeights = [];
 			const listLabels = [];
@@ -260,7 +270,8 @@ var SemanticMemory = class {
 				lists.push(ftsHits);
 				listWeights.push(wFts);
 				listLabels.push(`fts_${queries.indexOf(q)}`);
-				const vectorHits = await this.#tryVectorSearch(scope, q, candidateTopK, opts.asOf, opts.includeQuarantined, opts.includeSuperseded, opts.owner);
+				const preVector = variantVectors?.get(q);
+				const vectorHits = preVector !== void 0 ? await this.#vectorSearchWithVector(scope, preVector, candidateTopK, opts.asOf, opts.includeQuarantined, opts.includeSuperseded, opts.owner) : await this.#tryVectorSearch(scope, q, candidateTopK, opts.asOf, opts.includeQuarantined, opts.includeSuperseded, opts.owner);
 				if (vectorHits.length > 0) {
 					lists.push(vectorHits);
 					listWeights.push(wVector);
@@ -272,7 +283,7 @@ var SemanticMemory = class {
 					isPrimary = false;
 				}
 			}
-			const hydeHits = await this.#tryHyde(scope, query, opts, candidateTopK);
+			const hydeHits = await hydeHitsPromise;
 			if (hydeHits.length > 0) {
 				lists.push(hydeHits);
 				listWeights.push(wVector);
@@ -294,7 +305,7 @@ var SemanticMemory = class {
 				weights: listWeights,
 				...weighted.k !== void 0 ? { k: weighted.k } : {}
 			}) : this.#reranker;
-			const fusedTopK = opts.decay !== void 0 || (opts.tags?.length ?? 0) > 0 || opts.owner !== void 0 || (opts.expandHops ?? 0) > 0 || opts.entityMatch === true ? Math.max(finalTopK, lists.reduce((n, l) => n + l.length, 0)) : finalTopK;
+			const fusedTopK = opts.decay !== void 0 || (opts.tags?.length ?? 0) > 0 || opts.owner !== void 0 || (opts.expandHops ?? 0) > 0 || opts.entityMatch === true || opts.trustWeighting !== "off" || opts.includeQuarantined === true ? Math.max(finalTopK, lists.reduce((n, l) => n + l.length, 0)) : finalTopK;
 			const fused = await reranker.rerank(query, lists, {
 				topK: fusedTopK,
 				labels: listLabels,
@@ -310,7 +321,7 @@ var SemanticMemory = class {
 			const ownerFiltered = wantedOwners !== null ? filtered.filter((h) => wantedOwners.includes(h.record.owner ?? "user")) : filtered;
 			const ranked = (opts.trustWeighting === "off" ? ownerFiltered : this.#applyTrustDiscount(ownerFiltered)).slice(0, finalTopK);
 			if (ranked.length > 0 && typeof this.#store.semantic.markAccessed === "function") try {
-				await this.#store.semantic.markAccessed(ranked.map((h) => h.record.id));
+				await this.#store.semantic.markAccessed(ranked.map((h) => h.record.id), void 0, scope);
 			} catch {}
 			const explanation = explainRecall(ranked, {
 				query,
@@ -364,12 +375,16 @@ var SemanticMemory = class {
 				idOf: (hit) => hit.record.id,
 				grader: this.#grader,
 				fuse: (lists) => fuseRrf(lists, 60)
-			}, {
-				maxIterations: opts.maxIterations ?? this.#iterativeMaxIterations,
-				maxResults: opts.topK ?? 10,
-				...opts.forceHard !== void 0 ? { forceHard: opts.forceHard } : {},
-				...opts.signal !== void 0 ? { signal: opts.signal } : {}
-			});
+			}, (() => {
+				const difficultyThreshold = opts.difficultyThreshold ?? this.#iterativeDifficultyThreshold;
+				return {
+					maxIterations: opts.maxIterations ?? this.#iterativeMaxIterations,
+					maxResults: opts.topK ?? 10,
+					...opts.forceHard !== void 0 ? { forceHard: opts.forceHard } : {},
+					...opts.signal !== void 0 ? { signal: opts.signal } : {},
+					...difficultyThreshold !== void 0 ? { difficulty: { threshold: difficultyThreshold } } : {}
+				};
+			})());
 			span.setAttributes({
 				"memory.search.semantic.iterative.gate_hard": result.gateHard,
 				"memory.search.semantic.iterative.iterations": result.iterations,
@@ -465,16 +480,51 @@ var SemanticMemory = class {
 				}
 			}
 			span.setAttributes({ "memory.semantic.validate.forced": force });
-			await this.#store.semantic.setStatus(factId, "active", reason);
+			await this.#store.semantic.setStatus(factId, "active", reason, scope);
+			if (existing !== null && existing.supersedes !== void 0) {
+				const oldFact = await this.#fetchExisting(existing.supersedes);
+				if (oldFact !== null && oldFact.supersededBy === void 0 && oldFact.validTo === void 0) {
+					span.setAttributes({ "memory.semantic.validate.completed_supersede": true });
+					await this.#store.semantic.supersede(existing.supersedes, {
+						...existing,
+						status: "active"
+					}, reason ?? "validated-supersede");
+				}
+			}
 		});
 	}
-	/** Mark `oldId` superseded by a new fact. Returns the new record. */
-	async supersede(scope, oldId, newInput, reason) {
-		return withMemorySpan(this.#tracer, "memory.write.semantic", scope, { "memory.semantic.action": "supersede" }, async () => {
+	/**
+	* Mark `oldId` superseded by a new fact. Returns the new record.
+	*
+	* W-019 (security-first, knowledge-preserving): when the successor
+	* lands QUARANTINED (the default for `extraction`/synthesized
+	* provenance), the old ACTIVE fact's validity interval is NOT closed
+	* - default recall keeps returning the old knowledge until the
+	* successor passes {@link validate}, which completes the closure.
+	* The link is recorded on the successor's `supersedes` field. With
+	* `autoPromoteSynthesized` (threaded from the consolidator's
+	* `autoPromoteExtraction` escape hatch) an injection-clean successor
+	* is active immediately and the interval closes right away - the
+	* pre-W-019 behaviour. Inverting the default (auto-activating the
+	* successor) would hand a MINJA attacker instant active memory via
+	* any text the reconciler classifies as an 'update'.
+	*/
+	async supersede(scope, oldId, newInput, reason, options) {
+		return withMemorySpan(this.#tracer, "memory.write.semantic", scope, { "memory.semantic.action": "supersede" }, async (span) => {
 			const newFact = await this.remember(scope, {
 				...newInput,
 				supersedes: oldId
-			}, { pipeline: "off" });
+			}, {
+				pipeline: "off",
+				...options?.autoPromoteSynthesized === true ? { autoPromoteSynthesized: true } : {}
+			});
+			if (newFact.status === "quarantined") {
+				span.setAttributes({ "memory.semantic.supersede.pending": true });
+				return {
+					old: oldId,
+					new: newFact
+				};
+			}
 			await this.#store.semantic.supersede(oldId, newFact, reason);
 			return {
 				old: oldId,
@@ -488,7 +538,7 @@ var SemanticMemory = class {
 			"memory.semantic.action": "forget",
 			"memory.semantic.fact_id": factId
 		}, async () => {
-			await this.#store.semantic.forget(factId, reason);
+			await this.#store.semantic.forget(factId, reason, scope);
 		});
 	}
 	/**
@@ -504,7 +554,7 @@ var SemanticMemory = class {
 			"memory.semantic.fact_id": factId
 		}, async () => {
 			if (typeof this.#store.semantic.purge !== "function") throw new TypeError("[graphorin/memory] SemanticMemory.purge(...) requires a storage adapter that implements `semantic.purge(id)`. For storage adapters without GDPR-grade hard-delete, prefer `SemanticMemory.forget(...)`.");
-			await this.#store.semantic.purge(factId, reason);
+			await this.#store.semantic.purge(factId, reason, scope);
 		});
 	}
 	/** Fuse multiple ranked lists outside of a `search()` call. */
@@ -565,7 +615,7 @@ var SemanticMemory = class {
 		try {
 			const pseudo = await this.#queryTransformer.hypothetical(query, { ...opts.signal !== void 0 ? { signal: opts.signal } : {} });
 			if (pseudo === null || pseudo.trim().length === 0) return [];
-			return this.#tryVectorSearch(scope, pseudo, topK, opts.asOf, opts.includeQuarantined);
+			return this.#tryVectorSearch(scope, pseudo, topK, opts.asOf, opts.includeQuarantined, opts.includeSuperseded, opts.owner);
 		} catch {
 			return [];
 		}
@@ -661,9 +711,42 @@ var SemanticMemory = class {
 		if (this.#embedder === null || embedderId === null || typeof this.#store.semantic.searchVector !== "function") return [];
 		const [vector] = await this.#embedder.embed([query], { taskType: "query" });
 		if (vector === void 0) return [];
+		return this.#vectorSearchWithVector(scope, vector, topK, asOf, includeQuarantined, includeSuperseded, owner);
+	}
+	/**
+	* W-087: the store half of {@link SemanticMemory.#tryVectorSearch} -
+	* runs the KNN read against an ALREADY-COMPUTED query vector so the
+	* multi-query fan-out can batch its N variant embeddings into one
+	* `embed([q1..qN])` call instead of N provider round-trips.
+	*/
+	async #vectorSearchWithVector(scope, vector, topK, asOf, includeQuarantined, includeSuperseded, owner) {
+		const embedderId = this.#embedderIdProvider();
+		if (embedderId === null || typeof this.#store.semantic.searchVector !== "function") return [];
 		return this.#store.semantic.searchVector(scope, vector, embedderId, topK, asOf, includeQuarantined, includeSuperseded, owner);
 	}
 	/**
+	* W-087: embed every fan-out variant in ONE embedder call. Returns
+	* `null` - and the caller degrades to the per-variant path - when
+	* there is no fan-out, no vector surface, or the batch call fails; a
+	* batching failure must never fail the search.
+	*/
+	async #tryBatchEmbedQueries(queries) {
+		if (queries.length <= 1) return null;
+		if (this.#embedder === null || this.#embedderIdProvider() === null || typeof this.#store.semantic.searchVector !== "function") return null;
+		try {
+			const vectors = await this.#embedder.embed([...queries], { taskType: "query" });
+			if (vectors.length !== queries.length) return null;
+			const byQuery = /* @__PURE__ */ new Map();
+			queries.forEach((q, i) => {
+				const v = vectors[i];
+				if (v !== void 0) byQuery.set(q, v);
+			});
+			return byQuery;
+		} catch {
+			return null;
+		}
+	}
+	/**
 	* C5: multiply each hit's fused score by its trust factor and re-sort.
 	* No-ops (returns the same array) when every factor is 1.
 	*/