@graphorin/memory 0.5.0

package/dist/tiers/insight-memory.js

@@ -0,0 +1,133 @@
+import { withMemorySpan } from "../internal/spans.js";
+import { QuarantinePromotionRefusedError } from "../errors/index.js";
+import { detectMemoryInjection } from "../internal/injection-heuristics.js";
+
+//#region src/tiers/insight-memory.ts
+/**
+* `InsightMemory` — list / search reflection insights. A no-op (returns
+* empty) when the storage adapter does not expose the optional
+* `insights` surface.
+*
+* @stable
+*/
+var InsightMemory = class {
+	#store;
+	#tracer;
+	constructor(args) {
+		this.#store = args.store;
+		this.#tracer = args.tracer;
+	}
+	/** FTS keyword search over insight text. */
+	async search(scope, query, opts = {}) {
+		return withMemorySpan(this.#tracer, "memory.search.insight", scope, { "memory.search.query_length": query.length }, async (span) => {
+			const store = this.#store.insights;
+			if (store === void 0) {
+				span.setAttributes({ "memory.search.insight.count": 0 });
+				return [];
+			}
+			const hits = await store.search(scope, query, {
+				topK: opts.topK ?? 10,
+				...opts.includeQuarantined !== void 0 ? { includeQuarantined: opts.includeQuarantined } : {}
+			});
+			for (const hit of hits) try {
+				await store.bumpSalience(hit.record.id, 1, "retrieval");
+			} catch {}
+			span.setAttributes({ "memory.search.insight.count": hits.length });
+			return hits;
+		});
+	}
+	/** Most-recent insights for the scope (newest first). */
+	async list(scope, opts = {}) {
+		return withMemorySpan(this.#tracer, "memory.read.insight", scope, {}, async (span) => {
+			const store = this.#store.insights;
+			if (store === void 0) {
+				span.setAttributes({ "memory.read.insight.count": 0 });
+				return [];
+			}
+			const out = await store.list(scope, {
+				...opts.limit !== void 0 ? { limit: opts.limit } : {},
+				...opts.includeQuarantined !== void 0 ? { includeQuarantined: opts.includeQuarantined } : {}
+			});
+			span.setAttributes({ "memory.read.insight.count": out.length });
+			return out;
+		});
+	}
+	/** Lookup a single insight by id. */
+	async get(id) {
+		const store = this.#store.insights;
+		if (store === void 0 || typeof store.get !== "function") return null;
+		return store.get(id);
+	}
+	/**
+	* Promote a quarantined insight out of quarantine (MCON-2). Mirrors
+	* {@link SemanticMemory.validate}: re-derives the injection verdict from the
+	* stored text and **refuses** promotion of an injection-flagged insight
+	* unless an operator passes `{ force: true }` from a trusted context.
+	*/
+	async validate(scope, insightId, reason, options) {
+		await withMemorySpan(this.#tracer, "memory.write.insight", scope, {
+			"memory.insight.action": "validate",
+			"memory.insight.insight_id": insightId
+		}, async (span) => {
+			const store = this.#store.insights;
+			if (store === void 0 || typeof store.setStatus !== "function") throw new TypeError("[graphorin/memory] InsightMemory.validate(...) requires a storage adapter that implements `insights.setStatus(id, status)`. The default `@graphorin/store-sqlite` adapter implements it; custom adapters can opt in via InsightMemoryStoreExt.");
+			const force = options?.force === true;
+			const existing = typeof store.get === "function" ? await store.get(insightId) : null;
+			if (existing !== null && !force) {
+				const injection = detectMemoryInjection(existing.text);
+				if (injection.flagged) {
+					span.setAttributes({ "memory.insight.validate.refused": true });
+					throw new QuarantinePromotionRefusedError(insightId, injection.markers);
+				}
+			}
+			span.setAttributes({ "memory.insight.validate.forced": force });
+			await store.setStatus(insightId, "active", reason);
+		});
+	}
+};
+/** Tie-break margin keeping a capped insight strictly below its cited fact. */
+const RANK_CAP_EPSILON = 1e-6;
+/**
+* Enforce the P1-1 rank ceiling: an insight may never outrank a primary
+* fact **it cites**. For each insight hit, if any fact it cites is
+* present in `factHits`, its score is lowered to strictly below that
+* cited fact's score — so concatenating the two lists and sorting by
+* score descending can never place the insight above the evidence it
+* was synthesized from. Insights whose cited facts are absent from
+* `factHits` are returned unchanged; this is a relative, not a global,
+* cap (per the execution plan: "never outrank the primary facts they
+* cite").
+*
+* Pure + deterministic — does not mutate its inputs.
+*
+* @stable
+*/
+function capInsightsBelowFacts(factHits, insightHits) {
+	if (factHits.length === 0 || insightHits.length === 0) return insightHits;
+	const factScoreById = /* @__PURE__ */ new Map();
+	for (const hit of factHits) {
+		const prev = factScoreById.get(hit.record.id);
+		if (prev === void 0 || hit.score > prev) factScoreById.set(hit.record.id, hit.score);
+	}
+	return insightHits.map((hit) => {
+		let citedMax = Number.NEGATIVE_INFINITY;
+		for (const id of hit.record.cites) {
+			const score = factScoreById.get(id);
+			if (score !== void 0 && score > citedMax) citedMax = score;
+		}
+		if (citedMax === Number.NEGATIVE_INFINITY || hit.score < citedMax) return hit;
+		const capped = citedMax - RANK_CAP_EPSILON;
+		return {
+			...hit,
+			score: capped,
+			signals: Object.freeze({
+				...hit.signals ?? {},
+				"rank-cap": capped
+			})
+		};
+	});
+}
+
+//#endregion
+export { InsightMemory, capInsightsBelowFacts };
+//# sourceMappingURL=insight-memory.js.map

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

@@ -0,0 +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":";;;;;;;;;;;;AAgDA,IAAa,gBAAb,MAA2B;CACzB,CAASA;CACT,CAASC;CAET,YAAY,MAAqD;AAC/D,QAAKD,QAAS,KAAK;AACnB,QAAKC,SAAU,KAAK;;;CAItB,MAAM,OACJ,OACA,OACA,OAA6B,EAAE,EACa;AAC5C,SAAO,eACL,MAAKA,QACL,yBACA,OACA,EAAE,8BAA8B,MAAM,QAAQ,EAC9C,OAAO,SAAS;GACd,MAAM,QAAQ,MAAKD,MAAO;AAC1B,OAAI,UAAU,QAAW;AACvB,SAAK,cAAc,EAAE,+BAA+B,GAAG,CAAC;AACxD,WAAO,EAAE;;GAEX,MAAM,OAAO,MAAM,MAAM,OAAO,OAAO,OAAO;IAC5C,MAAM,KAAK,QAAQ;IACnB,GAAI,KAAK,uBAAuB,SAC5B,EAAE,oBAAoB,KAAK,oBAAoB,GAC/C,EAAE;IACP,CAAC;AAKF,QAAK,MAAM,OAAO,KAChB,KAAI;AACF,UAAM,MAAM,aAAa,IAAI,OAAO,IAAI,GAAG,YAAY;WACjD;AAIV,QAAK,cAAc,EAAE,+BAA+B,KAAK,QAAQ,CAAC;AAClE,UAAO;IAEV;;;CAIH,MAAM,KAAK,OAAqB,OAA2B,EAAE,EAAmC;AAC9F,SAAO,eAAe,MAAKC,QAAS,uBAAuB,OAAO,EAAE,EAAE,OAAO,SAAS;GACpF,MAAM,QAAQ,MAAKD,MAAO;AAC1B,OAAI,UAAU,QAAW;AACvB,SAAK,cAAc,EAAE,6BAA6B,GAAG,CAAC;AACtD,WAAO,EAAE;;GAEX,MAAM,MAAM,MAAM,MAAM,KAAK,OAAO;IAClC,GAAI,KAAK,UAAU,SAAY,EAAE,OAAO,KAAK,OAAO,GAAG,EAAE;IACzD,GAAI,KAAK,uBAAuB,SAC5B,EAAE,oBAAoB,KAAK,oBAAoB,GAC/C,EAAE;IACP,CAAC;AACF,QAAK,cAAc,EAAE,6BAA6B,IAAI,QAAQ,CAAC;AAC/D,UAAO;IACP;;;CAIJ,MAAM,IAAI,IAAqC;EAC7C,MAAM,QAAQ,MAAKA,MAAO;AAC1B,MAAI,UAAU,UAAa,OAAO,MAAM,QAAQ,WAAY,QAAO;AACnE,SAAO,MAAM,IAAI,GAAG;;;;;;;;CAStB,MAAM,SACJ,OACA,WACA,QACA,SACe;AACf,QAAM,eACJ,MAAKC,QACL,wBACA,OACA;GAAE,yBAAyB;GAAY,6BAA6B;GAAW,EAC/E,OAAO,SAAS;GACd,MAAM,QAAQ,MAAKD,MAAO;AAC1B,OAAI,UAAU,UAAa,OAAO,MAAM,cAAc,WACpD,OAAM,IAAI,UACR,iPAED;GAEH,MAAM,QAAQ,SAAS,UAAU;GACjC,MAAM,WAAW,OAAO,MAAM,QAAQ,aAAa,MAAM,MAAM,IAAI,UAAU,GAAG;AAChF,OAAI,aAAa,QAAQ,CAAC,OAAO;IAC/B,MAAM,YAAY,sBAAsB,SAAS,KAAK;AACtD,QAAI,UAAU,SAAS;AACrB,UAAK,cAAc,EAAE,mCAAmC,MAAM,CAAC;AAC/D,WAAM,IAAI,gCAAgC,WAAW,UAAU,QAAQ;;;AAG3E,QAAK,cAAc,EAAE,kCAAkC,OAAO,CAAC;AAC/D,SAAM,MAAM,UAAU,WAAW,UAAU,OAAO;IAErD;;;;AAKL,MAAM,mBAAmB;;;;;;;;;;;;;;;;AAiBzB,SAAgB,sBACd,UACA,aACmC;AACnC,KAAI,SAAS,WAAW,KAAK,YAAY,WAAW,EAAG,QAAO;CAC9D,MAAM,gCAAgB,IAAI,KAAqB;AAC/C,MAAK,MAAM,OAAO,UAAU;EAC1B,MAAM,OAAO,cAAc,IAAI,IAAI,OAAO,GAAG;AAC7C,MAAI,SAAS,UAAa,IAAI,QAAQ,KAAM,eAAc,IAAI,IAAI,OAAO,IAAI,IAAI,MAAM;;AAEzF,QAAO,YAAY,KAAK,QAAQ;EAC9B,IAAI,WAAW,OAAO;AACtB,OAAK,MAAM,MAAM,IAAI,OAAO,OAAO;GACjC,MAAM,QAAQ,cAAc,IAAI,GAAG;AACnC,OAAI,UAAU,UAAa,QAAQ,SAAU,YAAW;;AAG1D,MAAI,aAAa,OAAO,qBAAqB,IAAI,QAAQ,SAAU,QAAO;EAC1E,MAAM,SAAS,WAAW;AAC1B,SAAO;GACL,GAAG;GACH,OAAO;GACP,SAAS,OAAO,OAAO;IAAE,GAAI,IAAI,WAAW,EAAE;IAAG,YAAY;IAAQ,CAAC;GACvE;GACD"}

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

@@ -0,0 +1,147 @@
+import { MemoryStoreAdapter } from "../internal/storage-adapter.js";
+import { Trajectory, WorkflowInducer } from "../consolidator/phases/induce.js";
+import { Rule, RunState, Sensitivity, SessionScope, Tracer } from "@graphorin/core";
+
+//#region src/tiers/procedural-memory.d.ts
+
+/**
+ * Author-time rule payload accepted by {@link ProceduralMemory.define}.
+ *
+ * @stable
+ */
+interface RuleInput {
+  readonly text: string;
+  /**
+   * Free-form predicate evaluated by {@link ProceduralMemory.activate}.
+   * The predicate language is intentionally narrow in v0.1: either
+   * the literal string `'always'`, or a `'topic=...'` / `'tag=...'`
+   * shorthand. Custom predicates should be expressed as a callable
+   * matched in `activate(...)`'s `customMatchers` argument.
+   */
+  readonly condition?: string;
+  /** Default `'public'` per DEC-126 — rules are NOT user data. */
+  readonly sensitivity?: Sensitivity;
+  readonly priority?: number;
+  readonly tags?: ReadonlyArray<string>;
+  /**
+   * Optional structured workflow payload (P2-2). Usually set by
+   * {@link ProceduralMemory.induce}, but accepted here so an author can
+   * round-trip a hand-written procedure. See {@link Rule.steps}.
+   */
+  readonly steps?: ReadonlyArray<string>;
+  /** Variable names abstracted into {@link RuleInput.steps} (P2-2). */
+  readonly variables?: ReadonlyArray<string>;
+  /** Verifiable success criteria stored with the procedure (P2-2). */
+  readonly successCriteria?: ReadonlyArray<string>;
+}
+/**
+ * Options for {@link ProceduralMemory.induce}.
+ *
+ * @stable
+ */
+interface InduceOptions {
+  /** Sensitivity of the stored procedure. Default `'internal'`. */
+  readonly sensitivity?: Sensitivity;
+  /** Priority of the stored procedure. Default {@link INDUCED_PRIORITY} (40). */
+  readonly priority?: number;
+}
+/**
+ * Predicate context passed to {@link ProceduralMemory.activate}.
+ *
+ * @stable
+ */
+interface RuleActivationContext {
+  readonly topic?: string;
+  readonly tags?: ReadonlyArray<string>;
+}
+/**
+ * `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.
+ *
+ * P2-2 adds {@link ProceduralMemory.induce}: distil a reusable workflow
+ * from a successful agent trajectory and store it **quarantined** (it must
+ * not drive actions until validated). Quarantined procedures are excluded
+ * from {@link ProceduralMemory.activate} but remain visible to
+ * {@link ProceduralMemory.list}.
+ *
+ * @stable
+ */
+declare class ProceduralMemory {
+  #private;
+  constructor(args: {
+    store: MemoryStoreAdapter;
+    tracer: Tracer;
+    inducer?: WorkflowInducer | null;
+    promoteAfterSuccesses?: number | null;
+  });
+  /**
+   * Record the outcome of one demonstrated reuse of a procedure
+   * (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
+   * 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
+   * `checkSuccessCriteria(...)` over the procedure's stored
+   * `successCriteria`, or an operator's judgement.
+   *
+   * @stable
+   */
+  recordOutcome(scope: SessionScope, ruleId: string, succeeded: boolean): Promise<{
+    readonly successCount: number;
+    readonly promoted: boolean;
+    readonly refused: boolean;
+  }>;
+  /** Persist a rule. Returns the stored record. */
+  define(scope: SessionScope, input: RuleInput): Promise<Rule>;
+  /**
+   * Induce a reusable procedure (P2-2) from a successful agent trajectory
+   * and store it **quarantined** + `provenance: 'induction'` (P1-4). Returns
+   * the stored {@link Rule}, or `null` when the trajectory was unsuccessful /
+   * empty or the inducer produced nothing inducible.
+   *
+   * Throws {@link ProcedureInductionNotConfiguredError} when no inducer was
+   * configured (`createMemory({ procedureInduction: { provider } })`).
+   */
+  induce(scope: SessionScope, trajectory: Trajectory, opts?: InduceOptions): Promise<Rule | null>;
+  /**
+   * Convenience over {@link induce}: distil the {@link Trajectory} from a
+   * completed {@link RunState} (the agent's already-emitted run state) and
+   * induce a procedure. The success signal is `status === 'completed'`.
+   */
+  induceFromRun(scope: SessionScope, run: RunState, opts?: InduceOptions): Promise<Rule | null>;
+  /** Soft-delete a rule. */
+  remove(scope: SessionScope, ruleId: string, reason?: string): Promise<void>;
+  /** List every active (non-deleted) rule for the supplied scope. */
+  list(scope: SessionScope): Promise<ReadonlyArray<Rule>>;
+  /**
+   * Return the rules active under `context`. Rules without a
+   * `condition` are always active; the bundled predicate vocabulary
+   * supports the literals `'always'`, `'topic=<topic>'`, and
+   * `'tag=<tag>'`. Anything outside that grammar is treated as
+   * 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.
+   */
+  activate(scope: SessionScope, context?: RuleActivationContext): Promise<ReadonlyArray<Rule>>;
+  /**
+   * 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
+   * procedure unless an operator passes `{ force: true }`. Induced procedures
+   * drive *actions*, so this gate matters most for them.
+   */
+  validate(scope: SessionScope, ruleId: string, reason?: string, options?: {
+    readonly force?: boolean;
+  }): Promise<void>;
+}
+//#endregion
+export { InduceOptions, ProceduralMemory, RuleActivationContext, RuleInput };
+//# sourceMappingURL=procedural-memory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"procedural-memory.d.ts","names":[],"sources":["../../src/tiers/procedural-memory.ts"],"sourcesContent":[],"mappings":";;;;;;;;AAkCA;;;AAmBmB,UAnBF,SAAA,CAmBE;EAEI,SAAA,IAAA,EAAA,MAAA;EAEM;;AAQ7B;AAYA;AAmBA;;;EAcc,SAAA,SAAA,CAAA,EAAA,MAAA;EA4BH;EAGN,SAAA,WAAA,CAAA,EAhGoB,WAgGpB;EA8CiB,SAAA,QAAA,CAAA,EAAA,MAAA;EAAqB,SAAA,IAAA,CAAA,EA5IzB,aA4IyB,CAAA,MAAA,CAAA;EAAoB;;;;;EA8ClD,SAAA,KAAA,CAAA,EApLM,aAoLN,CAAA,MAAA,CAAA;EAAR;EAqDM,SAAA,SAAA,CAAA,EAvOY,aAuOZ,CAAA,MAAA,CAAA;EACF;EACC,SAAA,eAAA,CAAA,EAvOmB,aAuOnB,CAAA,MAAA,CAAA;;;;;;;AAmBiC,UAlP1B,aAAA,CAkP0B;EAAR;EAoBxB,SAAA,WAAA,CAAA,EApQc,WAoQd;EACE;EACc,SAAA,QAAA,CAAA,EAAA,MAAA;;;;;;;UA5PV,qBAAA;;kBAEC;;;;;;;;;;;;;;;;cAiBL,gBAAA;;;WAYF;YACC;cACE;;;;;;;;;;;;;;;;;;;uBA4BH,mDAGN;;;;;;gBA8CiB,qBAAqB,YAAY,QAAQ;;;;;;;;;;gBA2CpD,0BACK,mBACN,gBACL,QAAQ;;;;;;uBAqDF,mBACF,iBACC,gBACL,QAAQ;;gBAKS,gDAAgD;;cAalD,eAAe,QAAQ,cAAc;;;;;;;;;;;;kBAoB9C,wBACE,wBACR,QAAQ,cAAc;;;;;;;;kBAehB;;MAIN"}

package/dist/tiers/procedural-memory.js

@@ -0,0 +1,267 @@
+import { withMemorySpan } from "../internal/spans.js";
+import { ProcedureInductionNotConfiguredError, QuarantinePromotionRefusedError } from "../errors/index.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
+* (50) because an induced, still-quarantined procedure is provisional. */
+const INDUCED_PRIORITY = 40;
+/**
+* `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.
+*
+* P2-2 adds {@link ProceduralMemory.induce}: distil a reusable workflow
+* from a successful agent trajectory and store it **quarantined** (it must
+* not drive actions until validated). Quarantined procedures are excluded
+* from {@link ProceduralMemory.activate} but remain visible to
+* {@link ProceduralMemory.list}.
+*
+* @stable
+*/
+var ProceduralMemory = class {
+	#store;
+	#tracer;
+	/** Opt-in workflow inducer (P2-2). `null` ⇒ {@link induce} throws. */
+	#inducer;
+	/**
+	* Promotion-by-demonstrated-success threshold (MCON-2 part 4).
+	* `null` ⇒ outcomes are counted but never auto-promote.
+	*/
+	#promoteAfterSuccesses;
+	constructor(args) {
+		this.#store = args.store;
+		this.#tracer = args.tracer;
+		this.#inducer = args.inducer ?? null;
+		const k = args.promoteAfterSuccesses;
+		this.#promoteAfterSuccesses = typeof k === "number" && Number.isFinite(k) && k >= 1 ? Math.floor(k) : null;
+	}
+	/**
+	* Record the outcome of one demonstrated reuse of a procedure
+	* (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
+	* 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
+	* `checkSuccessCriteria(...)` over the procedure's stored
+	* `successCriteria`, or an operator's judgement.
+	*
+	* @stable
+	*/
+	async recordOutcome(scope, ruleId, succeeded) {
+		return withMemorySpan(this.#tracer, "memory.write.procedural", scope, {
+			"memory.procedural.action": "record-outcome",
+			"memory.procedural.rule_id": ruleId
+		}, async (span) => {
+			const store = this.#store.procedural;
+			if (!succeeded || typeof store.recordSuccess !== "function") {
+				span.setAttributes({ "memory.procedural.outcome.counted": false });
+				return {
+					successCount: 0,
+					promoted: false,
+					refused: false
+				};
+			}
+			const successCount = await store.recordSuccess(ruleId);
+			span.setAttributes({ "memory.procedural.outcome.success_count": successCount });
+			const threshold = this.#promoteAfterSuccesses;
+			if (threshold === null || successCount < threshold) return {
+				successCount,
+				promoted: false,
+				refused: false
+			};
+			const existing = (await store.list(scope)).find((rule) => rule.id === ruleId) ?? null;
+			if (existing === null || existing.status !== "quarantined") return {
+				successCount,
+				promoted: false,
+				refused: false
+			};
+			try {
+				await this.validate(scope, ruleId, `demonstrated-success: ${successCount} >= ${threshold}`);
+				span.setAttributes({ "memory.procedural.outcome.promoted": true });
+				return {
+					successCount,
+					promoted: true,
+					refused: false
+				};
+			} catch (err) {
+				if (err instanceof QuarantinePromotionRefusedError) {
+					span.setAttributes({ "memory.procedural.outcome.refused": true });
+					return {
+						successCount,
+						promoted: false,
+						refused: true
+					};
+				}
+				throw err;
+			}
+		});
+	}
+	/** Persist a rule. Returns the stored record. */
+	async define(scope, input) {
+		return withMemorySpan(this.#tracer, "memory.write.procedural", scope, {}, async (span) => {
+			const now = (/* @__PURE__ */ new Date()).toISOString();
+			const rule = {
+				id: newMemoryId("rule"),
+				kind: "procedural",
+				userId: scope.userId,
+				...scope.sessionId !== void 0 ? { sessionId: scope.sessionId } : {},
+				...scope.agentId !== void 0 ? { agentId: scope.agentId } : {},
+				sensitivity: input.sensitivity ?? "public",
+				text: input.text,
+				...input.condition !== void 0 ? { condition: input.condition } : {},
+				priority: input.priority ?? 50,
+				...input.tags !== void 0 ? { tags: Object.freeze([...input.tags]) } : {},
+				...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]) } : {},
+				createdAt: now,
+				updatedAt: now
+			};
+			await this.#store.procedural.add(rule);
+			span.setAttributes({
+				"memory.procedural.priority": rule.priority,
+				"memory.procedural.text_length": input.text.length
+			});
+			return rule;
+		});
+	}
+	/**
+	* Induce a reusable procedure (P2-2) from a successful agent trajectory
+	* and store it **quarantined** + `provenance: 'induction'` (P1-4). Returns
+	* the stored {@link Rule}, or `null` when the trajectory was unsuccessful /
+	* empty or the inducer produced nothing inducible.
+	*
+	* Throws {@link ProcedureInductionNotConfiguredError} when no inducer was
+	* configured (`createMemory({ procedureInduction: { provider } })`).
+	*/
+	async induce(scope, trajectory, opts = {}) {
+		const inducer = this.#inducer;
+		if (inducer === null) throw new ProcedureInductionNotConfiguredError();
+		return withMemorySpan(this.#tracer, "memory.write.procedural", scope, { "memory.procedural.action": "induce" }, async (span) => {
+			const induced = await runWorkflowInduction(trajectory, inducer, {});
+			if (induced === null) {
+				span.setAttributes({ "memory.procedural.induced": 0 });
+				return null;
+			}
+			const now = (/* @__PURE__ */ new Date()).toISOString();
+			const rule = {
+				id: newMemoryId("rule"),
+				kind: "procedural",
+				userId: scope.userId,
+				...scope.sessionId !== void 0 ? { sessionId: scope.sessionId } : {},
+				...scope.agentId !== void 0 ? { agentId: scope.agentId } : {},
+				sensitivity: opts.sensitivity ?? "internal",
+				text: renderProcedureText(induced),
+				priority: opts.priority ?? INDUCED_PRIORITY,
+				steps: Object.freeze([...induced.steps]),
+				variables: Object.freeze([...induced.variables]),
+				successCriteria: Object.freeze([...induced.successCriteria]),
+				provenance: "induction",
+				status: "quarantined",
+				createdAt: now,
+				updatedAt: now
+			};
+			await this.#store.procedural.add(rule);
+			span.setAttributes({
+				"memory.procedural.induced": 1,
+				"memory.procedural.steps": induced.steps.length,
+				"memory.procedural.variables": induced.variables.length
+			});
+			return rule;
+		});
+	}
+	/**
+	* Convenience over {@link induce}: distil the {@link Trajectory} from a
+	* completed {@link RunState} (the agent's already-emitted run state) and
+	* induce a procedure. The success signal is `status === 'completed'`.
+	*/
+	async induceFromRun(scope, run, opts = {}) {
+		return this.induce(scope, trajectoryFromRunState(run), opts);
+	}
+	/** Soft-delete a rule. */
+	async remove(scope, ruleId, reason) {
+		await withMemorySpan(this.#tracer, "memory.write.procedural", scope, {
+			"memory.procedural.action": "remove",
+			"memory.procedural.rule_id": ruleId
+		}, async () => {
+			await this.#store.procedural.remove(ruleId, reason);
+		});
+	}
+	/** List every active (non-deleted) rule for the supplied scope. */
+	async list(scope) {
+		return withMemorySpan(this.#tracer, "memory.read.procedural", scope, {}, async (span) => {
+			const out = await this.#store.procedural.list(scope);
+			span.setAttributes({ "memory.read.procedural.count": out.length });
+			return out;
+		});
+	}
+	/**
+	* Return the rules active under `context`. Rules without a
+	* `condition` are always active; the bundled predicate vocabulary
+	* supports the literals `'always'`, `'topic=<topic>'`, and
+	* `'tag=<tag>'`. Anything outside that grammar is treated as
+	* 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.
+	*/
+	async activate(scope, context = {}) {
+		return (await this.list(scope)).filter((rule) => rule.status !== "quarantined" && predicateMatches(rule, context)).sort((a, b) => b.priority - a.priority);
+	}
+	/**
+	* 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
+	* procedure unless an operator passes `{ force: true }`. Induced procedures
+	* drive *actions*, so this gate matters most for them.
+	*/
+	async validate(scope, ruleId, reason, options) {
+		await withMemorySpan(this.#tracer, "memory.write.procedural", scope, {
+			"memory.procedural.action": "validate",
+			"memory.procedural.rule_id": ruleId
+		}, async (span) => {
+			const store = this.#store.procedural;
+			if (typeof store.setStatus !== "function") throw new TypeError("[graphorin/memory] ProceduralMemory.validate(...) requires a storage adapter that implements `procedural.setStatus(id, status)`. The default `@graphorin/store-sqlite` adapter implements it; custom adapters can opt in via ProceduralMemoryStoreExt.");
+			const force = options?.force === true;
+			const existing = (await store.list(scope)).find((rule) => rule.id === ruleId) ?? null;
+			if (existing !== null && !force) {
+				const injection = detectMemoryInjection(existing.text);
+				if (injection.flagged) {
+					span.setAttributes({ "memory.procedural.validate.refused": true });
+					throw new QuarantinePromotionRefusedError(ruleId, injection.markers);
+				}
+			}
+			span.setAttributes({ "memory.procedural.validate.forced": force });
+			await store.setStatus(ruleId, "active", reason);
+		});
+	}
+};
+/** Render an induced procedure into the human-readable `Rule.text`. */
+function renderProcedureText(procedure) {
+	return [procedure.title, ...procedure.steps.map((step, i) => `${i + 1}. ${step}`)].join("\n");
+}
+function predicateMatches(rule, context) {
+	if (rule.condition === void 0 || rule.condition === "always") return true;
+	if (rule.condition.startsWith("topic=")) {
+		const wanted = rule.condition.slice(6).trim();
+		return context.topic === wanted;
+	}
+	if (rule.condition.startsWith("tag=")) {
+		const wanted = rule.condition.slice(4).trim();
+		return (context.tags ?? []).includes(wanted);
+	}
+	return true;
+}
+
+//#endregion
+export { ProceduralMemory };
+//# sourceMappingURL=procedural-memory.js.map

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

@@ -0,0 +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":"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"}