@graphorin/memory 0.5.0 → 0.6.1

package/dist/tiers/procedural-memory.js

@@ -5,11 +5,11 @@ 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
+/** Default priority for an *induced* procedure - below the author default
 * (50) because an induced, still-quarantined procedure is provisional. */
 const INDUCED_PRIORITY = 40;
 /**
-* `ProceduralMemory` — standing orders activated when the agent's
+* `ProceduralMemory` - standing orders activated when the agent's
 * current context matches the rule's predicate. The activation rules
 * are deterministic so the agent runtime + ContextEngine can render
 * the active set into the system prompt every step.
@@ -44,12 +44,12 @@ var ProceduralMemory = class {
 	* (MCON-2 part 4). A success increments the rule's persistent
 	* `successCount`; when `procedurePromotion.afterSuccesses` is
 	* configured and a QUARANTINED procedure reaches the threshold it is
-	* promoted through {@link validate} — the injection gate still
+	* promoted through {@link validate} - the injection gate still
 	* applies, so a flagged text refuses promotion (surfaced as
 	* `refused: true`) no matter how many successes accumulate.
 	* Failures are observed but not persisted (no negative counter yet).
 	*
-	* Callers decide what "success" means — typically
+	* Callers decide what "success" means - typically
 	* `checkSuccessCriteria(...)` over the procedure's stored
 	* `successCriteria`, or an operator's judgement.
 	*
@@ -122,6 +122,7 @@ var ProceduralMemory = class {
 				...input.steps !== void 0 ? { steps: Object.freeze([...input.steps]) } : {},
 				...input.variables !== void 0 ? { variables: Object.freeze([...input.variables]) } : {},
 				...input.successCriteria !== void 0 ? { successCriteria: Object.freeze([...input.successCriteria]) } : {},
+				...input.owner !== void 0 ? { owner: input.owner } : {},
 				createdAt: now,
 				updatedAt: now
 			};
@@ -166,6 +167,7 @@ var ProceduralMemory = class {
 				successCriteria: Object.freeze([...induced.successCriteria]),
 				provenance: "induction",
 				status: "quarantined",
+				owner: "agent",
 				createdAt: now,
 				updatedAt: now
 			};
@@ -211,13 +213,67 @@ var ProceduralMemory = class {
 	* always-active so callers do not silently lose rules.
 	*
 	* **Quarantined procedures are excluded** (P1-4 / P2-2): an induced
-	* procedure must not drive actions until validated, so activation — which
-	* feeds the system prompt — never surfaces it.
+	* procedure must not drive actions until validated, so activation - which
+	* feeds the system prompt - never surfaces it.
 	*/
 	async activate(scope, context = {}) {
 		return (await this.list(scope)).filter((rule) => rule.status !== "quarantined" && predicateMatches(rule, context)).sort((a, b) => b.priority - a.priority);
 	}
 	/**
+	* Runbook content search (D3): "find the procedure for this task" -
+	* lexical recall over rule text, as opposed to predicate
+	* {@link activate}. Returns **whole validated procedures** (the full
+	* {@link Rule} incl. steps / variables / success criteria) so a match
+	* can be followed file-style rather than re-synthesized from
+	* fragments. Quarantined (unvalidated induced) procedures are
+	* excluded - they must not drive actions - unless the inspector opts
+	* in via `includeQuarantined`.
+	*
+	* Uses the storage adapter's FTS surface when available
+	* (`procedural.search`, the default `@graphorin/store-sqlite` adapter
+	* implements it via migration 028); otherwise degrades to an offline
+	* in-memory token-overlap scan over {@link list}, so custom adapters
+	* keep working without the index.
+	*/
+	async search(scope, query, opts = {}) {
+		return withMemorySpan(this.#tracer, "memory.read.procedural", scope, { "memory.procedural.action": "search" }, async (span) => {
+			const topK = opts.topK ?? 5;
+			const store = this.#store.procedural;
+			if (typeof store.search === "function") {
+				const hits = await store.search(scope, query, {
+					topK,
+					...opts.includeQuarantined === true ? { includeQuarantined: true } : {}
+				});
+				span.setAttributes({
+					"memory.read.procedural.count": hits.length,
+					"memory.read.procedural.search_backend": "store"
+				});
+				return hits;
+			}
+			const tokens = tokenizeForRunbook(query);
+			const scored = (await this.list(scope)).filter((rule) => opts.includeQuarantined === true || rule.status !== "quarantined").map((rule) => {
+				const haystack = tokenizeForRunbook([
+					rule.text,
+					...rule.steps ?? [],
+					...rule.tags ?? []
+				].join(" "));
+				return {
+					rule,
+					overlap: tokens.filter((t) => haystack.includes(t)).length
+				};
+			}).filter((entry) => entry.overlap > 0).sort((a, b) => b.overlap - a.overlap || (a.rule.id < b.rule.id ? -1 : 1)).slice(0, topK);
+			span.setAttributes({
+				"memory.read.procedural.count": scored.length,
+				"memory.read.procedural.search_backend": "fallback"
+			});
+			return scored.map((entry) => ({
+				record: entry.rule,
+				score: tokens.length === 0 ? 0 : entry.overlap / tokens.length,
+				signals: { lexical: entry.overlap }
+			}));
+		});
+	}
+	/**
 	* Promote a quarantined (induced) procedure into `activate()` (MCON-2).
 	* Mirrors {@link SemanticMemory.validate}: re-derives the injection verdict
 	* from the stored rule text and **refuses** promotion of an injection-flagged
@@ -249,6 +305,10 @@ var ProceduralMemory = class {
 function renderProcedureText(procedure) {
 	return [procedure.title, ...procedure.steps.map((step, i) => `${i + 1}. ${step}`)].join("\n");
 }
+/** Lowercased word tokens for the offline runbook-search fallback (D3). */
+function tokenizeForRunbook(text) {
+	return text.toLowerCase().split(/[^\p{L}\p{N}]+/u).filter((token) => token.length > 1);
+}
 function predicateMatches(rule, context) {
 	if (rule.condition === void 0 || rule.condition === "always") return true;
 	if (rule.condition.startsWith("topic=")) {

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  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}\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        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          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   * 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\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":";;;;;;;;;AA2BA,MAAM,mBAAmB;;;;;;;;;;;;;;;AAqEzB,IAAa,mBAAb,MAA8B;CAC5B,CAASA;CACT,CAASC;;CAET,CAASC;;;;;CAKT,CAASC;CAET,YAAY,MAKT;AACD,QAAKH,QAAS,KAAK;AACnB,QAAKC,SAAU,KAAK;AACpB,QAAKC,UAAW,KAAK,WAAW;EAChC,MAAM,IAAI,KAAK;AACf,QAAKC,wBACH,OAAO,MAAM,YAAY,OAAO,SAAS,EAAE,IAAI,KAAK,IAAI,KAAK,MAAM,EAAE,GAAG;;;;;;;;;;;;;;;;;;CAmB5E,MAAM,cACJ,OACA,QACA,WAKC;AACD,SAAO,eACL,MAAKF,QACL,2BACA,OACA;GAAE,4BAA4B;GAAkB,6BAA6B;GAAQ,EACrF,OAAO,SAAS;GACd,MAAM,QAAQ,MAAKD,MAAO;AAC1B,OAAI,CAAC,aAAa,OAAO,MAAM,kBAAkB,YAAY;AAC3D,SAAK,cAAc,EAAE,qCAAqC,OAAO,CAAC;AAClE,WAAO;KAAE,cAAc;KAAG,UAAU;KAAO,SAAS;KAAO;;GAE7D,MAAM,eAAe,MAAM,MAAM,cAAc,OAAO;AACtD,QAAK,cAAc,EAAE,2CAA2C,cAAc,CAAC;GAC/E,MAAM,YAAY,MAAKG;AACvB,OAAI,cAAc,QAAQ,eAAe,UACvC,QAAO;IAAE;IAAc,UAAU;IAAO,SAAS;IAAO;GAE1D,MAAM,YAAY,MAAM,MAAM,KAAK,MAAM,EAAE,MAAM,SAAS,KAAK,OAAO,OAAO,IAAI;AACjF,OAAI,aAAa,QAAQ,SAAS,WAAW,cAC3C,QAAO;IAAE;IAAc,UAAU;IAAO,SAAS;IAAO;AAE1D,OAAI;AACF,UAAM,KAAK,SACT,OACA,QACA,yBAAyB,aAAa,MAAM,YAC7C;AACD,SAAK,cAAc,EAAE,sCAAsC,MAAM,CAAC;AAClE,WAAO;KAAE;KAAc,UAAU;KAAM,SAAS;KAAO;YAChD,KAAK;AACZ,QAAI,eAAe,iCAAiC;AAClD,UAAK,cAAc,EAAE,qCAAqC,MAAM,CAAC;AACjE,YAAO;MAAE;MAAc,UAAU;MAAO,SAAS;MAAM;;AAEzD,UAAM;;IAGX;;;CAIH,MAAM,OAAO,OAAqB,OAAiC;AACjE,SAAO,eAAe,MAAKF,QAAS,2BAA2B,OAAO,EAAE,EAAE,OAAO,SAAS;GACxF,MAAM,uBAAM,IAAI,MAAM,EAAC,aAAa;GACpC,MAAMG,OAAa;IACjB,IAAI,YAAY,OAAO;IACvB,MAAM;IACN,QAAQ,MAAM;IACd,GAAI,MAAM,cAAc,SAAY,EAAE,WAAW,MAAM,WAAW,GAAG,EAAE;IACvE,GAAI,MAAM,YAAY,SAAY,EAAE,SAAS,MAAM,SAAS,GAAG,EAAE;IACjE,aAAa,MAAM,eAAe;IAClC,MAAM,MAAM;IACZ,GAAI,MAAM,cAAc,SAAY,EAAE,WAAW,MAAM,WAAW,GAAG,EAAE;IACvE,UAAU,MAAM,YAAY;IAC5B,GAAI,MAAM,SAAS,SAAY,EAAE,MAAM,OAAO,OAAO,CAAC,GAAG,MAAM,KAAK,CAAC,EAAE,GAAG,EAAE;IAC5E,GAAI,MAAM,UAAU,SAAY,EAAE,OAAO,OAAO,OAAO,CAAC,GAAG,MAAM,MAAM,CAAC,EAAE,GAAG,EAAE;IAC/E,GAAI,MAAM,cAAc,SACpB,EAAE,WAAW,OAAO,OAAO,CAAC,GAAG,MAAM,UAAU,CAAC,EAAE,GAClD,EAAE;IACN,GAAI,MAAM,oBAAoB,SAC1B,EAAE,iBAAiB,OAAO,OAAO,CAAC,GAAG,MAAM,gBAAgB,CAAC,EAAE,GAC9D,EAAE;IACN,WAAW;IACX,WAAW;IACZ;AACD,SAAM,MAAKJ,MAAO,WAAW,IAAI,KAAK;AACtC,QAAK,cAAc;IACjB,8BAA8B,KAAK;IACnC,iCAAiC,MAAM,KAAK;IAC7C,CAAC;AACF,UAAO;IACP;;;;;;;;;;;CAYJ,MAAM,OACJ,OACA,YACA,OAAsB,EAAE,EACF;EACtB,MAAM,UAAU,MAAKE;AACrB,MAAI,YAAY,KAAM,OAAM,IAAI,sCAAsC;AACtE,SAAO,eACL,MAAKD,QACL,2BACA,OACA,EAAE,4BAA4B,UAAU,EACxC,OAAO,SAAS;GACd,MAAM,UAAU,MAAM,qBAAqB,YAAY,SAAS,EAAE,CAAC;AACnE,OAAI,YAAY,MAAM;AACpB,SAAK,cAAc,EAAE,6BAA6B,GAAG,CAAC;AACtD,WAAO;;GAET,MAAM,uBAAM,IAAI,MAAM,EAAC,aAAa;GACpC,MAAMG,OAAa;IACjB,IAAI,YAAY,OAAO;IACvB,MAAM;IACN,QAAQ,MAAM;IACd,GAAI,MAAM,cAAc,SAAY,EAAE,WAAW,MAAM,WAAW,GAAG,EAAE;IACvE,GAAI,MAAM,YAAY,SAAY,EAAE,SAAS,MAAM,SAAS,GAAG,EAAE;IAGjE,aAAa,KAAK,eAAe;IACjC,MAAM,oBAAoB,QAAQ;IAClC,UAAU,KAAK,YAAY;IAC3B,OAAO,OAAO,OAAO,CAAC,GAAG,QAAQ,MAAM,CAAC;IACxC,WAAW,OAAO,OAAO,CAAC,GAAG,QAAQ,UAAU,CAAC;IAChD,iBAAiB,OAAO,OAAO,CAAC,GAAG,QAAQ,gBAAgB,CAAC;IAG5D,YAAY;IACZ,QAAQ;IACR,WAAW;IACX,WAAW;IACZ;AACD,SAAM,MAAKJ,MAAO,WAAW,IAAI,KAAK;AACtC,QAAK,cAAc;IACjB,6BAA6B;IAC7B,2BAA2B,QAAQ,MAAM;IACzC,+BAA+B,QAAQ,UAAU;IAClD,CAAC;AACF,UAAO;IAEV;;;;;;;CAQH,MAAM,cACJ,OACA,KACA,OAAsB,EAAE,EACF;AACtB,SAAO,KAAK,OAAO,OAAO,uBAAuB,IAAI,EAAE,KAAK;;;CAI9D,MAAM,OAAO,OAAqB,QAAgB,QAAgC;AAChF,QAAM,eACJ,MAAKC,QACL,2BACA,OACA;GAAE,4BAA4B;GAAU,6BAA6B;GAAQ,EAC7E,YAAY;AACV,SAAM,MAAKD,MAAO,WAAW,OAAO,QAAQ,OAAO;IAEtD;;;CAIH,MAAM,KAAK,OAAmD;AAC5D,SAAO,eAAe,MAAKC,QAAS,0BAA0B,OAAO,EAAE,EAAE,OAAO,SAAS;GACvF,MAAM,MAAM,MAAM,MAAKD,MAAO,WAAW,KAAK,MAAM;AACpD,QAAK,cAAc,EAAE,gCAAgC,IAAI,QAAQ,CAAC;AAClE,UAAO;IACP;;;;;;;;;;;;;CAcJ,MAAM,SACJ,OACA,UAAiC,EAAE,EACL;AAE9B,UADc,MAAM,KAAK,KAAK,MAAM,EAEjC,QAAQ,SAAS,KAAK,WAAW,iBAAiB,iBAAiB,MAAM,QAAQ,CAAC,CAClF,MAAM,GAAG,MAAM,EAAE,WAAW,EAAE,SAAS;;;;;;;;;CAU5C,MAAM,SACJ,OACA,QACA,QACA,SACe;AACf,QAAM,eACJ,MAAKC,QACL,2BACA,OACA;GAAE,4BAA4B;GAAY,6BAA6B;GAAQ,EAC/E,OAAO,SAAS;GACd,MAAM,QAAQ,MAAKD,MAAO;AAC1B,OAAI,OAAO,MAAM,cAAc,WAC7B,OAAM,IAAI,UACR,yPAED;GAEH,MAAM,QAAQ,SAAS,UAAU;GAEjC,MAAM,YAAY,MAAM,MAAM,KAAK,MAAM,EAAE,MAAM,SAAS,KAAK,OAAO,OAAO,IAAI;AACjF,OAAI,aAAa,QAAQ,CAAC,OAAO;IAC/B,MAAM,YAAY,sBAAsB,SAAS,KAAK;AACtD,QAAI,UAAU,SAAS;AACrB,UAAK,cAAc,EAAE,sCAAsC,MAAM,CAAC;AAClE,WAAM,IAAI,gCAAgC,QAAQ,UAAU,QAAQ;;;AAGxE,QAAK,cAAc,EAAE,qCAAqC,OAAO,CAAC;AAClE,SAAM,MAAM,UAAU,QAAQ,UAAU,OAAO;IAElD;;;;AAKL,SAAS,oBAAoB,WAAqC;AAEhE,QADc,CAAC,UAAU,OAAO,GAAG,UAAU,MAAM,KAAK,MAAM,MAAM,GAAG,IAAI,EAAE,IAAI,OAAO,CAAC,CAC5E,KAAK,KAAK;;AAGzB,SAAS,iBAAiB,MAAY,SAAyC;AAC7E,KAAI,KAAK,cAAc,UAAa,KAAK,cAAc,SAAU,QAAO;AACxE,KAAI,KAAK,UAAU,WAAW,SAAS,EAAE;EACvC,MAAM,SAAS,KAAK,UAAU,MAAM,EAAgB,CAAC,MAAM;AAC3D,SAAO,QAAQ,UAAU;;AAE3B,KAAI,KAAK,UAAU,WAAW,OAAO,EAAE;EACrC,MAAM,SAAS,KAAK,UAAU,MAAM,EAAc,CAAC,MAAM;AACzD,UAAQ,QAAQ,QAAQ,EAAE,EAAE,SAAS,OAAO;;AAE9C,QAAO"}
+{"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":";;;;;;;;;AA6BA,MAAM,mBAAmB;;;;;;;;;;;;;;;AAuEzB,IAAa,mBAAb,MAA8B;CAC5B,CAASA;CACT,CAASC;;CAET,CAASC;;;;;CAKT,CAASC;CAET,YAAY,MAKT;AACD,QAAKH,QAAS,KAAK;AACnB,QAAKC,SAAU,KAAK;AACpB,QAAKC,UAAW,KAAK,WAAW;EAChC,MAAM,IAAI,KAAK;AACf,QAAKC,wBACH,OAAO,MAAM,YAAY,OAAO,SAAS,EAAE,IAAI,KAAK,IAAI,KAAK,MAAM,EAAE,GAAG;;;;;;;;;;;;;;;;;;CAmB5E,MAAM,cACJ,OACA,QACA,WAKC;AACD,SAAO,eACL,MAAKF,QACL,2BACA,OACA;GAAE,4BAA4B;GAAkB,6BAA6B;GAAQ,EACrF,OAAO,SAAS;GACd,MAAM,QAAQ,MAAKD,MAAO;AAC1B,OAAI,CAAC,aAAa,OAAO,MAAM,kBAAkB,YAAY;AAC3D,SAAK,cAAc,EAAE,qCAAqC,OAAO,CAAC;AAClE,WAAO;KAAE,cAAc;KAAG,UAAU;KAAO,SAAS;KAAO;;GAE7D,MAAM,eAAe,MAAM,MAAM,cAAc,OAAO;AACtD,QAAK,cAAc,EAAE,2CAA2C,cAAc,CAAC;GAC/E,MAAM,YAAY,MAAKG;AACvB,OAAI,cAAc,QAAQ,eAAe,UACvC,QAAO;IAAE;IAAc,UAAU;IAAO,SAAS;IAAO;GAE1D,MAAM,YAAY,MAAM,MAAM,KAAK,MAAM,EAAE,MAAM,SAAS,KAAK,OAAO,OAAO,IAAI;AACjF,OAAI,aAAa,QAAQ,SAAS,WAAW,cAC3C,QAAO;IAAE;IAAc,UAAU;IAAO,SAAS;IAAO;AAE1D,OAAI;AACF,UAAM,KAAK,SACT,OACA,QACA,yBAAyB,aAAa,MAAM,YAC7C;AACD,SAAK,cAAc,EAAE,sCAAsC,MAAM,CAAC;AAClE,WAAO;KAAE;KAAc,UAAU;KAAM,SAAS;KAAO;YAChD,KAAK;AACZ,QAAI,eAAe,iCAAiC;AAClD,UAAK,cAAc,EAAE,qCAAqC,MAAM,CAAC;AACjE,YAAO;MAAE;MAAc,UAAU;MAAO,SAAS;MAAM;;AAEzD,UAAM;;IAGX;;;CAIH,MAAM,OAAO,OAAqB,OAAiC;AACjE,SAAO,eAAe,MAAKF,QAAS,2BAA2B,OAAO,EAAE,EAAE,OAAO,SAAS;GACxF,MAAM,uBAAM,IAAI,MAAM,EAAC,aAAa;GACpC,MAAMG,OAAa;IACjB,IAAI,YAAY,OAAO;IACvB,MAAM;IACN,QAAQ,MAAM;IACd,GAAI,MAAM,cAAc,SAAY,EAAE,WAAW,MAAM,WAAW,GAAG,EAAE;IACvE,GAAI,MAAM,YAAY,SAAY,EAAE,SAAS,MAAM,SAAS,GAAG,EAAE;IACjE,aAAa,MAAM,eAAe;IAClC,MAAM,MAAM;IACZ,GAAI,MAAM,cAAc,SAAY,EAAE,WAAW,MAAM,WAAW,GAAG,EAAE;IACvE,UAAU,MAAM,YAAY;IAC5B,GAAI,MAAM,SAAS,SAAY,EAAE,MAAM,OAAO,OAAO,CAAC,GAAG,MAAM,KAAK,CAAC,EAAE,GAAG,EAAE;IAC5E,GAAI,MAAM,UAAU,SAAY,EAAE,OAAO,OAAO,OAAO,CAAC,GAAG,MAAM,MAAM,CAAC,EAAE,GAAG,EAAE;IAC/E,GAAI,MAAM,cAAc,SACpB,EAAE,WAAW,OAAO,OAAO,CAAC,GAAG,MAAM,UAAU,CAAC,EAAE,GAClD,EAAE;IACN,GAAI,MAAM,oBAAoB,SAC1B,EAAE,iBAAiB,OAAO,OAAO,CAAC,GAAG,MAAM,gBAAgB,CAAC,EAAE,GAC9D,EAAE;IACN,GAAI,MAAM,UAAU,SAAY,EAAE,OAAO,MAAM,OAAO,GAAG,EAAE;IAC3D,WAAW;IACX,WAAW;IACZ;AACD,SAAM,MAAKJ,MAAO,WAAW,IAAI,KAAK;AACtC,QAAK,cAAc;IACjB,8BAA8B,KAAK;IACnC,iCAAiC,MAAM,KAAK;IAC7C,CAAC;AACF,UAAO;IACP;;;;;;;;;;;CAYJ,MAAM,OACJ,OACA,YACA,OAAsB,EAAE,EACF;EACtB,MAAM,UAAU,MAAKE;AACrB,MAAI,YAAY,KAAM,OAAM,IAAI,sCAAsC;AACtE,SAAO,eACL,MAAKD,QACL,2BACA,OACA,EAAE,4BAA4B,UAAU,EACxC,OAAO,SAAS;GACd,MAAM,UAAU,MAAM,qBAAqB,YAAY,SAAS,EAAE,CAAC;AACnE,OAAI,YAAY,MAAM;AACpB,SAAK,cAAc,EAAE,6BAA6B,GAAG,CAAC;AACtD,WAAO;;GAET,MAAM,uBAAM,IAAI,MAAM,EAAC,aAAa;GACpC,MAAMG,OAAa;IACjB,IAAI,YAAY,OAAO;IACvB,MAAM;IACN,QAAQ,MAAM;IACd,GAAI,MAAM,cAAc,SAAY,EAAE,WAAW,MAAM,WAAW,GAAG,EAAE;IACvE,GAAI,MAAM,YAAY,SAAY,EAAE,SAAS,MAAM,SAAS,GAAG,EAAE;IAGjE,aAAa,KAAK,eAAe;IACjC,MAAM,oBAAoB,QAAQ;IAClC,UAAU,KAAK,YAAY;IAC3B,OAAO,OAAO,OAAO,CAAC,GAAG,QAAQ,MAAM,CAAC;IACxC,WAAW,OAAO,OAAO,CAAC,GAAG,QAAQ,UAAU,CAAC;IAChD,iBAAiB,OAAO,OAAO,CAAC,GAAG,QAAQ,gBAAgB,CAAC;IAG5D,YAAY;IACZ,QAAQ;IAER,OAAO;IACP,WAAW;IACX,WAAW;IACZ;AACD,SAAM,MAAKJ,MAAO,WAAW,IAAI,KAAK;AACtC,QAAK,cAAc;IACjB,6BAA6B;IAC7B,2BAA2B,QAAQ,MAAM;IACzC,+BAA+B,QAAQ,UAAU;IAClD,CAAC;AACF,UAAO;IAEV;;;;;;;CAQH,MAAM,cACJ,OACA,KACA,OAAsB,EAAE,EACF;AACtB,SAAO,KAAK,OAAO,OAAO,uBAAuB,IAAI,EAAE,KAAK;;;CAI9D,MAAM,OAAO,OAAqB,QAAgB,QAAgC;AAChF,QAAM,eACJ,MAAKC,QACL,2BACA,OACA;GAAE,4BAA4B;GAAU,6BAA6B;GAAQ,EAC7E,YAAY;AACV,SAAM,MAAKD,MAAO,WAAW,OAAO,QAAQ,OAAO;IAEtD;;;CAIH,MAAM,KAAK,OAAmD;AAC5D,SAAO,eAAe,MAAKC,QAAS,0BAA0B,OAAO,EAAE,EAAE,OAAO,SAAS;GACvF,MAAM,MAAM,MAAM,MAAKD,MAAO,WAAW,KAAK,MAAM;AACpD,QAAK,cAAc,EAAE,gCAAgC,IAAI,QAAQ,CAAC;AAClE,UAAO;IACP;;;;;;;;;;;;;CAcJ,MAAM,SACJ,OACA,UAAiC,EAAE,EACL;AAE9B,UADc,MAAM,KAAK,KAAK,MAAM,EAEjC,QAAQ,SAAS,KAAK,WAAW,iBAAiB,iBAAiB,MAAM,QAAQ,CAAC,CAClF,MAAM,GAAG,MAAM,EAAE,WAAW,EAAE,SAAS;;;;;;;;;;;;;;;;;;CAmB5C,MAAM,OACJ,OACA,OACA,OAA0E,EAAE,EACnC;AACzC,SAAO,eACL,MAAKC,QACL,0BACA,OACA,EAAE,4BAA4B,UAAU,EACxC,OAAO,SAAS;GACd,MAAM,OAAO,KAAK,QAAQ;GAC1B,MAAM,QAAQ,MAAKD,MAAO;AAC1B,OAAI,OAAO,MAAM,WAAW,YAAY;IACtC,MAAM,OAAO,MAAM,MAAM,OAAO,OAAO,OAAO;KAC5C;KACA,GAAI,KAAK,uBAAuB,OAAO,EAAE,oBAAoB,MAAM,GAAG,EAAE;KACzE,CAAC;AACF,SAAK,cAAc;KACjB,gCAAgC,KAAK;KACrC,yCAAyC;KAC1C,CAAC;AACF,WAAO;;GAKT,MAAM,SAAS,mBAAmB,MAAM;GAExC,MAAM,UADQ,MAAM,KAAK,KAAK,MAAM,EAEjC,QAAQ,SAAS,KAAK,uBAAuB,QAAQ,KAAK,WAAW,cAAc,CACnF,KAAK,SAAS;IACb,MAAM,WAAW,mBACf;KAAC,KAAK;KAAM,GAAI,KAAK,SAAS,EAAE;KAAG,GAAI,KAAK,QAAQ,EAAE;KAAE,CAAC,KAAK,IAAI,CACnE;AAED,WAAO;KAAE;KAAM,SADC,OAAO,QAAQ,MAAM,SAAS,SAAS,EAAE,CAAC,CAAC;KACnC;KACxB,CACD,QAAQ,UAAU,MAAM,UAAU,EAAE,CACpC,MAAM,GAAG,MAAM,EAAE,UAAU,EAAE,YAAY,EAAE,KAAK,KAAK,EAAE,KAAK,KAAK,KAAK,GAAG,CACzE,MAAM,GAAG,KAAK;AACjB,QAAK,cAAc;IACjB,gCAAgC,OAAO;IACvC,yCAAyC;IAC1C,CAAC;AACF,UAAO,OAAO,KAAK,WAAW;IAC5B,QAAQ,MAAM;IACd,OAAO,OAAO,WAAW,IAAI,IAAI,MAAM,UAAU,OAAO;IACxD,SAAS,EAAE,SAAS,MAAM,SAAS;IACpC,EAAE;IAEN;;;;;;;;;CAUH,MAAM,SACJ,OACA,QACA,QACA,SACe;AACf,QAAM,eACJ,MAAKC,QACL,2BACA,OACA;GAAE,4BAA4B;GAAY,6BAA6B;GAAQ,EAC/E,OAAO,SAAS;GACd,MAAM,QAAQ,MAAKD,MAAO;AAC1B,OAAI,OAAO,MAAM,cAAc,WAC7B,OAAM,IAAI,UACR,yPAED;GAEH,MAAM,QAAQ,SAAS,UAAU;GAEjC,MAAM,YAAY,MAAM,MAAM,KAAK,MAAM,EAAE,MAAM,SAAS,KAAK,OAAO,OAAO,IAAI;AACjF,OAAI,aAAa,QAAQ,CAAC,OAAO;IAC/B,MAAM,YAAY,sBAAsB,SAAS,KAAK;AACtD,QAAI,UAAU,SAAS;AACrB,UAAK,cAAc,EAAE,sCAAsC,MAAM,CAAC;AAClE,WAAM,IAAI,gCAAgC,QAAQ,UAAU,QAAQ;;;AAGxE,QAAK,cAAc,EAAE,qCAAqC,OAAO,CAAC;AAClE,SAAM,MAAM,UAAU,QAAQ,UAAU,OAAO;IAElD;;;;AAKL,SAAS,oBAAoB,WAAqC;AAEhE,QADc,CAAC,UAAU,OAAO,GAAG,UAAU,MAAM,KAAK,MAAM,MAAM,GAAG,IAAI,EAAE,IAAI,OAAO,CAAC,CAC5E,KAAK,KAAK;;;AAIzB,SAAS,mBAAmB,MAAqC;AAC/D,QAAO,KACJ,aAAa,CACb,MAAM,kBAAkB,CACxB,QAAQ,UAAU,MAAM,SAAS,EAAE;;AAGxC,SAAS,iBAAiB,MAAY,SAAyC;AAC7E,KAAI,KAAK,cAAc,UAAa,KAAK,cAAc,SAAU,QAAO;AACxE,KAAI,KAAK,UAAU,WAAW,SAAS,EAAE;EACvC,MAAM,SAAS,KAAK,UAAU,MAAM,EAAgB,CAAC,MAAM;AAC3D,SAAO,QAAQ,UAAU;;AAE3B,KAAI,KAAK,UAAU,WAAW,OAAO,EAAE;EACrC,MAAM,SAAS,KAAK,UAAU,MAAM,EAAc,CAAC,MAAM;AACzD,UAAQ,QAAQ,QAAQ,EAAE,EAAE,SAAS,OAAO;;AAE9C,QAAO"}

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

@@ -1,11 +1,12 @@
 import { MemoryStoreAdapter } from "../internal/storage-adapter.js";
 import { ConflictDecision, ConflictPipeline } from "../conflict/types.js";
 import "../conflict/index.js";
+import { SalienceWeights } from "../consolidator/decay.js";
 import { EntityResolver } from "../graph/entity-resolver.js";
 import { IterativeRetrievalResult, RetrievalGrader } from "../search/iterative.js";
 import { QueryTransformer } from "../search/query-transform.js";
 import { ReRanker } from "../search/types.js";
-import { EmbedderProvider, Fact, MemoryHit, MemoryProvenance, Sensitivity, SessionScope, Tracer } from "@graphorin/core";
+import { EmbedderProvider, Fact, MemoryHit, MemoryOwner, MemoryProvenance, Sensitivity, SessionScope, Tracer } from "@graphorin/core";
 
 //#region src/tiers/semantic-memory.d.ts
 
@@ -31,21 +32,28 @@ interface FactInput {
   /**
    * Trust-provenance tag (P1-4). Writers that synthesize memory pass
    * `'extraction'` / `'reflection'` so the fact lands quarantined;
-   * first-party writers pass `'user'` / `'tool'` (or omit it — absent ⇒
+   * first-party writers pass `'user'` / `'tool'` (or omit it - absent ⇒
    * treated as first-party `active`). The `status` is *derived* from
    * this tag plus the injection heuristics; it is never author-set.
    */
   readonly provenance?: MemoryProvenance;
   /**
    * Importance hint in `[0, 1]` (X-1 / MCON-12). Feeds the multi-signal
-   * salience score that orders decay archiving and capacity eviction —
+   * salience score that orders decay archiving and capacity eviction -
    * higher importance ⇒ evicted later. Values are clamped to `[0, 1]`;
    * non-finite values are dropped. The consolidator's extraction pass
-   * fills this from the model's per-fact 1–10 rating
+   * fills this from the model's per-fact 1-10 rating
    * (`normalizeImportance`); absent ⇒ the neutral midpoint at scoring
    * time.
    */
   readonly importance?: number;
+  /**
+   * Principal dimension (D3). The consolidator stamps `'agent'` on
+   * synthesized writes; user-authored writes may pass `'user'`. Absent
+   * (the default) leaves the column NULL - treated as `'user'` at
+   * filter time. Never gates default recall.
+   */
+  readonly owner?: MemoryOwner;
 }
 /**
  * Per-list weights for {@link FusionStrategy} `'weighted'` fusion (X-2),
@@ -61,12 +69,21 @@ interface FusionWeights {
   readonly fts?: number;
   /** Weight applied to every vector (incl. HyDE) candidate list. Default `1`. */
   readonly vector?: number;
+  /**
+   * Weight applied to the graph-expansion candidate list (D5). Default
+   * `1` (the previous neutral behaviour). Tune it once the graph leg's
+   * reliability is calibrated against labels - the roadmap's "graph as a
+   * first-class tunable fusion weight" (was hardcoded neutral).
+   */
+  readonly graph?: number;
+  /** Weight applied to the exact entity-match candidate list (D5). Default `1`. */
+  readonly entity?: number;
 }
 /**
  * Score-fusion strategy for {@link SemanticMemory.search} (X-2).
  *
  * - `'rrf'` (the default when `fusion` is omitted) fuses the candidate
- *   lists through the configured reranker — the zero-tuning
+ *   lists through the configured reranker - the zero-tuning
  *   {@link RRFReranker} unless one was overridden.
  * - `'weighted'` fuses through {@link WeightedRRFReranker}, scaling each
  *   list's reciprocal-rank contribution by its {@link FusionWeights}, for
@@ -113,7 +130,7 @@ interface FactSearchOptions {
   readonly asOf?: string;
   /**
    * Include quarantined facts in the result (P1-4). Defaults to
-   * `false` — action-driving recall (`fact_search`, auto-recall) never
+   * `false` - action-driving recall (`fact_search`, auto-recall) never
    * returns quarantined rows. Set `true` only for the validation /
    * inspector path that surfaces quarantined facts to a human for
    * promotion via {@link SemanticMemory.validate}.
@@ -121,6 +138,29 @@ interface FactSearchOptions {
    * @stable
    */
   readonly includeQuarantined?: boolean;
+  /**
+   * Rank-time trust discount (C5). `'on'` (default) multiplies each
+   * hit's fused score by its trust factor - quarantined-but-included
+   * rows by `1 - quarantine` (default 0.3x), foreign-provenance rows by
+   * `1 - foreignProvenance` (default 0.8x); first-party active facts are
+   * untouched. `'off'` restores pure similarity ranking (inspector /
+   * calibration paths). Factors surface as the `trust` signal on hits
+   * and in `explainRecall`.
+   *
+   * @stable
+   */
+  readonly trustWeighting?: 'on' | 'off';
+  /**
+   * Include superseded / validity-expired facts (memory-retrieval-01).
+   * Defaults to `false`: a default read behaves as `asOf = now`, so a
+   * fact whose validity interval was closed (e.g. by `supersede`)
+   * never surfaces as current - what the `fact_supersede` tool
+   * promises. Set `true` only for inspector / audit paths. Ignored
+   * when an explicit {@link asOf} is supplied.
+   *
+   * @stable
+   */
+  readonly includeSuperseded?: boolean;
   /**
    * Optional decay-aware ranking. When set, the reranker output is
    * post-multiplied by the per-fact retention curve
@@ -143,7 +183,7 @@ interface FactSearchOptions {
    * transformer is configured (`createMemory({ queryTransform })`), the
    * query is fanned into up to `N - 1` reworded variants via one cheap
    * LLM call; each variant is retrieved (FTS + vector) and **all** lists
-   * are fused through the existing RRF reranker — recovering memories
+   * are fused through the existing RRF reranker - recovering memories
    * whose stored wording differs from the user's phrasing. `N` bounds
    * the *total* query strings, including the original. Offline (no
    * transformer, or `N <= 1`) this is a **silent no-op**: search stays
@@ -154,11 +194,11 @@ interface FactSearchOptions {
    */
   readonly multiQuery?: number;
   /**
-   * HyDE — Hypothetical Document Embeddings (arXiv:2212.10496), P2-3.
+   * HyDE - Hypothetical Document Embeddings (arXiv:2212.10496), P2-3.
    * When `true` *and* both a query transformer and an embedder are
    * configured, generate a short hypothetical answer, embed it, and fuse
    * its vector neighbours into the result. Helps short / ambiguous
-   * queries but adds a generate + embed round-trip and can drift — hence
+   * queries but adds a generate + embed round-trip and can drift - hence
    * opt-in. With no transformer (or no embedder) this is a silent no-op
    * and no provider call is made.
    *
@@ -167,7 +207,7 @@ interface FactSearchOptions {
   readonly hyde?: boolean;
   /**
    * Score-fusion strategy (X-2). Omitted (the default) ⇒ RRF via the
-   * configured reranker — behaviour is unchanged. `{ strategy:
+   * configured reranker - behaviour is unchanged. `{ strategy:
    * 'weighted', weights }` fuses through {@link WeightedRRFReranker},
    * up-/down-weighting the FTS vs vector candidate lists per
    * {@link FusionWeights}; reserve it for callers who have calibrated the
@@ -182,17 +222,52 @@ interface FactSearchOptions {
    * storage adapter (`store.graph`), the facts retrieved by the lexical /
    * vector candidate pass are treated as seeds: facts sharing a canonical
    * entity (subject / object) are fetched via a recursive CTE and fused
-   * in as an extra candidate list before rerank — surfacing connected
+   * in as an extra candidate list before rerank - surfacing connected
    * facts the query never matched directly ("what did the person I met in
    * Tbilisi recommend?"). `0` (the default) or a graph-less adapter ⇒ a
-   * silent no-op; recall is unchanged. Opt-in + retrieval-heavy.
+   * silent no-op; recall is unchanged. Opt-in + retrieval-heavy. `2`
+   * (D5) widens to two-hop expansion - pair with `graphScoring: 'ppr'`
+   * so distant neighbours decay instead of tying with direct ones.
+   *
+   * @stable
+   */
+  readonly expandHops?: 0 | 1 | 2;
+  /**
+   * Graph-expansion scoring (D5). `'flat'` (the default) scores every
+   * graph neighbour `1` (the pre-D5 behaviour). `'ppr'` uses PPR-lite
+   * damped spreading activation (`damping^hopDepth`) via the store's
+   * `expandActivation`, so a two-hop neighbour ranks below a direct one;
+   * a no-op without `expandHops >= 1` or a graph-capable adapter.
+   *
+   * @stable
+   */
+  readonly graphScoring?: 'flat' | 'ppr';
+  /**
+   * Exact entity-match retriever (D5). When set, the query terms are
+   * normalized to entity names and facts linked to a matching canonical
+   * entity are fused in as a precise candidate leg (`entity` fusion
+   * weight), distinct from the fuzzy FTS / vector legs. A no-op without
+   * a graph-capable adapter. Opt-in.
    *
    * @stable
    */
-  readonly expandHops?: 0 | 1;
+  readonly entityMatch?: boolean;
+  /**
+   * Retrieval-time principal filter (D3). When set, only facts whose
+   * `owner` is in the requested set are returned - `'user'` for
+   * user-stated facts, `'agent'` for the agent's own inferences,
+   * `'shared'` for multi-agent shared records. Rows written before the
+   * feature (owner NULL) are treated as `'user'`. Applied in-store on
+   * the FTS + vector legs and as a record-level filter on the fused
+   * result so the HyDE / graph legs obey it too. Absent (the default)
+   * ⇒ **no owner filter** - recall is byte-identical.
+   *
+   * @stable
+   */
+  readonly owner?: MemoryOwner | ReadonlyArray<MemoryOwner>;
 }
 /**
- * Per-call options for {@link SemanticMemory.searchIterative} (P2-4) —
+ * Per-call options for {@link SemanticMemory.searchIterative} (P2-4) -
  * the gated grade-then-reformulate loop. Extends {@link FactSearchOptions}
  * (every base option applies to each retrieval pass); `topK` doubles as
  * the cap on the accumulated result count.
@@ -216,7 +291,7 @@ interface IterativeSearchOptions extends FactSearchOptions {
 /**
  * Outcome of {@link SemanticMemory.searchIterative}. Beyond the ranked
  * `hits`, `sufficient` / `abstained` tell the caller whether the memory
- * actually answered the query — `abstained: true` means it should say so
+ * actually answered the query - `abstained: true` means it should say so
  * rather than confabulate.
  *
  * @stable
@@ -238,7 +313,7 @@ interface FactRememberOptions {
   /**
    * Precomputed contextual-retrieval index text (P1-3, advanced). When
    * supplied it overrides the instance's `'late-chunk'` computation: the
-   * embedding is computed from — and the FTS row indexed against — this
+   * embedding is computed from - and the FTS row indexed against - this
    * text, while the canonical `text` is stored unchanged. The background
    * consolidator passes this in its `'llm'` mode (the one place an LLM is
    * allowed to write the situating context); first-party callers normally
@@ -249,7 +324,7 @@ interface FactRememberOptions {
    * Auto-promotion policy (MCON-2). When `true`, a *synthesized* write
    * (consolidator extraction) that is **clean** by the injection heuristics is
    * stored `active` instead of quarantined. Injection-flagged writes always
-   * stay quarantined — the security gate is preserved. Off by default; the
+   * stay quarantined - the security gate is preserved. Off by default; the
    * consolidator passes it only when the operator opts in via
    * `autoPromoteExtraction`. No effect on non-synthesized writes.
    */
@@ -268,15 +343,15 @@ interface RememberOutcome {
   readonly decision: ConflictDecision;
   /**
    * Why this write landed quarantined, if it did (P1-4 / MRET-3).
-   * `'injection'` — the offline injection heuristics flagged the text
-   * (a memory-poisoning candidate). `'synthesized'` — a consolidator /
+   * `'injection'` - the offline injection heuristics flagged the text
+   * (a memory-poisoning candidate). `'synthesized'` - a consolidator /
    * reflection / induction write awaiting validation. Absent when the
    * fact is `active` or when a dedup returned a pre-existing row.
    */
   readonly quarantineReason?: 'injection' | 'synthesized';
 }
 /**
- * `SemanticMemory` — long-term factual store. Hybrid (vector + FTS5)
+ * `SemanticMemory` - long-term factual store. Hybrid (vector + FTS5)
  * search merges the two ranked lists through the configured
  * {@link ReRanker} (default {@link RRFReranker} with `k = 60`).
  *
@@ -310,7 +385,7 @@ declare class SemanticMemory {
      * (default) prepends a deterministic situating context to the text
      * that is embedded + FTS-indexed, leaving the canonical `text`
      * untouched; `'off'` indexes the bare text. The hot write path never
-     * makes an LLM call — the `'llm'` enrichment is confined to the
+     * makes an LLM call - the `'llm'` enrichment is confined to the
      * background consolidator, which supplies a precomputed `indexText`.
      */
     contextualRetrieval?: 'off' | 'late-chunk';
@@ -332,6 +407,12 @@ declare class SemanticMemory {
     grader?: RetrievalGrader;
     /** Default total-pass cap for `searchIterative`. Default 3. */
     iterativeMaxIterations?: number;
+    /**
+     * Weights for the rank-time trust discount (C5). Reuses the
+     * eviction-path `SalienceWeights` semantics; defaults to
+     * `DEFAULT_SALIENCE_WEIGHTS`.
+     */
+    trustWeights?: SalienceWeights;
   });
   /** Replace the active reranker. Returns the previous instance. */
   setReranker(reranker: ReRanker): ReRanker;
@@ -363,8 +444,8 @@ declare class SemanticMemory {
    * hard *and* with a grader configured
    * (`createMemory({ iterativeRetrieval })`), the retrieved set is graded
    * for sufficiency and, when weak, the query is reformulated and
-   * retrieved again — **widening to one-hop graph expansion**
-   * (`expandHops: 1`) on each reformulation pass — up to `maxIterations`
+   * retrieved again - **widening to one-hop graph expansion**
+   * (`expandHops: 1`) on each reformulation pass - up to `maxIterations`
    * (hard-capped at 5). When still insufficient it returns
    * `abstained: true` so the caller can decline to answer instead of
    * confabulating.
@@ -382,7 +463,7 @@ declare class SemanticMemory {
    * zone thresholds are calibrated against them), and it **includes
    * quarantined facts** so prior synthesized memories are visible to
    * reconciliation. Returns `[]` when no embedder / vector adapter is
-   * configured — the consolidator then treats every candidate as a
+   * configured - the consolidator then treats every candidate as a
    * fresh `add`, degrading gracefully to the pre-reconcile behaviour.
    *
    * @stable
@@ -397,7 +478,7 @@ declare class SemanticMemory {
    * to, oldest → newest, including superseded / soft-deleted rows so
    * callers can answer "how did this fact change over time". Requires
    * a storage adapter that implements
-   * `SemanticMemoryStoreExt.historyOf(...)` — the default
+   * `SemanticMemoryStoreExt.historyOf(...)` - the default
    * `@graphorin/store-sqlite` adapter wires this through. P0-2.
    *
    * @stable
@@ -408,12 +489,12 @@ declare class SemanticMemory {
    * that admits a synthesized memory into action-driving recall once a
    * human (or trusted non-agent caller) has reviewed it. Writes a
    * `memory_history` audit row. Requires a storage adapter that
-   * implements `SemanticMemoryStoreExt.setStatus(...)` — the default
+   * implements `SemanticMemoryStoreExt.setStatus(...)` - the default
    * `@graphorin/store-sqlite` adapter wires this through.
    *
    * MRET-3 / MST-1: promotion of a fact whose text still trips the
    * offline injection heuristics is **refused** with
-   * {@link QuarantinePromotionRefusedError} — the model-facing
+   * {@link QuarantinePromotionRefusedError} - the model-facing
    * `fact_validate` tool calls this with no `force`, so a poisoned
    * memory can never be promoted by the agent itself (the one-turn
    * `fact_remember(poison)` → `fact_validate(id)` chain is closed). An
@@ -437,7 +518,7 @@ declare class SemanticMemory {
    * Hard-delete a fact (GDPR path). Distinct from {@link forget}: the
    * record is removed from storage entirely instead of soft-archived.
    * Requires a storage adapter that implements
-   * `SemanticMemoryStoreExt.purge(...)` — the default
+   * `SemanticMemoryStoreExt.purge(...)` - the default
    * `@graphorin/store-sqlite` adapter wires this through.
    */
   purge(scope: SessionScope, factId: string, reason?: string): Promise<void>;
@@ -446,10 +527,10 @@ declare class SemanticMemory {
     topK?: number;
     signal?: AbortSignal;
   }): Promise<ReadonlyArray<MemoryHit<Fact>>>;
-  /** Pure-fusion helper — exposed for callers that already collected results. */
+  /** Pure-fusion helper - exposed for callers that already collected results. */
   static fuseRrf<TRecord extends Fact>(lists: ReadonlyArray<ReadonlyArray<MemoryHit<TRecord>>>, k?: number): ReadonlyArray<MemoryHit<TRecord>>;
   /**
-   * Pure weighted-fusion helper (X-2) — like {@link SemanticMemory.fuseRrf}
+   * Pure weighted-fusion helper (X-2) - like {@link SemanticMemory.fuseRrf}
    * but scales each list `i`'s reciprocal-rank contribution by
    * `weights[i]`. A missing / invalid entry defaults to `1`, so equal or
    * absent weights reproduce RRF.

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":";;;;;;;;;;;;;;AAsCA;;;;;AAwCiB,UAxCA,SAAA,CAwCa;EAoBlB,SAAA,IAAA,EAAA,MAAc;EAcT,SAAA,OAAA,CAAA,EAAA,MAAiB;EAEd,SAAA,SAAA,CAAA,EAAA,MAAA;EAUF,SAAA,MAAA,CAAA,EAAA,MAAA;EA4EE,SAAA,IAAA,CAAA,EA7JF,aA6JE,CAAA,MAAA,CAAA;EAAc,SAAA,UAAA,CAAA,EAAA,MAAA;EAwBjB,SAAA,WAAA,CAAA,EAnLQ,WAmLe;EAuB5B,SAAA,SAAA,CAAA,EAAA,MAAqB;EAAsC,SAAA,OAAA,CAAA,EAAA,MAAA;EAAV,SAAA,UAAA,CAAA,EAAA,MAAA;EAAzB;;AAWpC;AAiCA;AA0BA;;;EAgBc,SAAA,UAAA,CAAA,EArRU,gBAqRV;EAEA;;;;;;;;;EAwEH,SAAA,UAAA,CAAA,EAAA,MAAA;;;;;;;;;;;AAqO0B,UA9iBpB,aAAA,CA8iBoB;EAAV;EAAd,SAAA,GAAA,CAAA,EAAA,MAAA;EAAR;EAqLM,SAAA,MAAA,CAAA,EAAA,MAAA;;;;;;;;;;;;;;;AA0G2C,KAzzB1C,cAAA,GAyzB0C;EAyC3C,SAAA,QAAA,EAAA,KAAA;CAIN,GAAA;EAoCM,SAAA,QAAA,EAAA,UAAA;EAEG,SAAA,OAAA,EAx4BU,aAw4BV;EAEqC;EAA9C,SAAA,CAAA,CAAA,EAAA,MAAA;CAwBiB;;;;;;AAwCG,UAh8BR,iBAAA,CAg8BQ;EAAd,SAAA,IAAA,CAAA,EAAA,MAAA;EAC4B,SAAA,MAAA,CAAA,EA/7BnB,WA+7BmB;EACF;EAAV,SAAA,aAAA,CAAA,EAAA,MAAA;EAAd;;;;;;;EAQgB,SAAA,IAAA,CAAA,EA97BX,aA87BW,CAAA,MAAA,CAAA;EAAV;;;;;;;;;EAcA,SAAA,IAAA,CAAA,EAAA,MAAA;EAAd;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBAh4Be;;;;;;;;;;;;;;;;;;;;;;;UAwBH,sBAAA,SAA+B;;;;;;;;;;;;;;;;;;;;;;KAuBpC,qBAAA,GAAwB,yBAAyB,UAAU;;;;;;;;;;UAWtD,mBAAA;;;oBAGG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UA8BH,eAAA;iBACA;qBACI;;;;;;;;;;;;;;;;;;;;;;;cAwBR,cAAA;;;WAcF;YACC;cACE;;cAEA;uBACS;;;;;;;;uBAQA;;;;;;;;;;;;;;;;;qBAiBF;;;;;;;;aAQR;;;;;wBAkBW,WAAW;;cAOrB;;;;;;;;kBAYH,qBACA,qBACE,sBACR,QAAQ;;;;;;;;8BAaF,qBACA,qBACE,sBACR,QAAQ;;gBAgNF,oCAED,oBACL,QAAQ,cAAc,UAAU;;;;;;;;;;;;;;;;;;;;yBAqL1B,oCAED,yBACL,QAAQ;;;;;;;;;;;;;mBAiEF;;MAGN,QAAQ,cAAc,UAAU;;aAKlB,+BAA+B,QAAQ;;;;;;;;;;;iBA8BnC,+BAA+B,QAAQ,cAAc;;;;;;;;;;;;;;;;;;;;;kBAyCjE;;MAIN;;mBAoCM,uCAEG,6BAET;;kBAA8C;;;gBAwB7B,gDAAgD;;;;;;;;eAmBjD,gDAAgD;;6BAqB1D,cAAc,cAAc,UAAU;;aACV;MAClC,QAAQ,cAAc,UAAU;;iCAKJ,aACtB,cAAc,cAAc,UAAU,yBAE5C,cAAc,UAAU;;;;;;;sCAUS,aAC3B,cAAc,cAAc,UAAU,qBACpC,gDAER,cAAc,UAAU"}
+{"version":3,"file":"semantic-memory.d.ts","names":[],"sources":["../../src/tiers/semantic-memory.ts"],"sourcesContent":[],"mappings":"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"}