@graphorin/memory 0.6.1 → 0.7.0

package/src/tools/block-tools.ts

@@ -0,0 +1,172 @@
+import type { Tool } from '@graphorin/core';
+import { tool } from '@graphorin/tools';
+import { z } from 'zod';
+import type { MemoryToolDeps } from './types.js';
+
+const blockAppendInputSchema = z.object({
+  label: z.string().min(1).max(128),
+  content: z.string().min(1),
+});
+const blockAppendOutputSchema = z.object({
+  label: z.string(),
+  length: z.number(),
+});
+
+/**
+ * W-013: explicit interfaces instead of `z.infer<typeof schema>` - the
+ * inferred aliases baked concrete v3 zod object generics into
+ * the published d.ts, which do not typecheck under a zod@4 consumer.
+ * Interface<->schema equality is pinned by type tests.
+ */
+export interface BlockAppendInput {
+  label: string;
+  content: string;
+}
+export interface BlockAppendOutput {
+  label: string;
+  length: number;
+}
+
+const blockReplaceInputSchema = z.object({
+  label: z.string().min(1).max(128),
+  oldUnique: z.string().min(1),
+  newText: z.string(),
+});
+const blockReplaceOutputSchema = z.object({
+  label: z.string(),
+  length: z.number(),
+});
+
+export interface BlockReplaceInput {
+  label: string;
+  oldUnique: string;
+  newText: string;
+}
+export interface BlockReplaceOutput {
+  label: string;
+  length: number;
+}
+
+const blockRethinkInputSchema = z.object({
+  label: z.string().min(1).max(128),
+  newValue: z.string(),
+});
+const blockRethinkOutputSchema = z.object({
+  label: z.string(),
+  length: z.number(),
+});
+
+export interface BlockRethinkInput {
+  label: string;
+  newValue: string;
+}
+export interface BlockRethinkOutput {
+  label: string;
+  length: number;
+}
+
+// W-013 parity gate (compile-time only, erased from the build and the
+// d.ts): each explicit interface must stay MUTUALLY assignable with its
+// schema's inference - a drifted transcription fails `tsc` right here.
+type W013Equals<A, B> = A extends B ? (B extends A ? true : false) : false;
+type W013Assert<T extends true> = T;
+type _W013Check1 = W013Assert<W013Equals<BlockAppendInput, z.infer<typeof blockAppendInputSchema>>>;
+type _W013Check2 = W013Assert<
+  W013Equals<BlockAppendOutput, z.infer<typeof blockAppendOutputSchema>>
+>;
+type _W013Check3 = W013Assert<
+  W013Equals<BlockReplaceInput, z.infer<typeof blockReplaceInputSchema>>
+>;
+type _W013Check4 = W013Assert<
+  W013Equals<BlockReplaceOutput, z.infer<typeof blockReplaceOutputSchema>>
+>;
+type _W013Check5 = W013Assert<
+  W013Equals<BlockRethinkInput, z.infer<typeof blockRethinkInputSchema>>
+>;
+type _W013Check6 = W013Assert<
+  W013Equals<BlockRethinkOutput, z.infer<typeof blockRethinkOutputSchema>>
+>;
+
+/**
+ * `block_append` - append text (with a newline separator) to a working
+ * memory block.
+ *
+ * @stable
+ */
+export function createBlockAppendTool(
+  deps: MemoryToolDeps,
+): Tool<BlockAppendInput, BlockAppendOutput> {
+  return tool<BlockAppendInput, BlockAppendOutput>({
+    name: 'block_append',
+    description:
+      'Append text to a working memory block. The block is identified by its label (registered via memory.working.define(...)). Use this when accumulating notes, observations, or reasoning steps that should persist across turns.',
+    inputSchema: blockAppendInputSchema,
+    outputSchema: blockAppendOutputSchema,
+    sideEffectClass: 'side-effecting',
+    sandboxPolicy: 'none',
+    sensitivity: 'internal',
+    memoryGuardTier: 'memory-aware',
+    tags: ['memory', 'working'],
+    async execute(input, ctx) {
+      const scope = await deps.resolveScope(ctx);
+      const block = await deps.working.append(scope, input.label, input.content);
+      return { label: block.label, length: block.value.length };
+    },
+  });
+}
+
+/**
+ * `block_replace` - replace a unique substring inside a working
+ * memory block. Throws when the substring is missing or appears more
+ * than once.
+ *
+ * @stable
+ */
+export function createBlockReplaceTool(
+  deps: MemoryToolDeps,
+): Tool<BlockReplaceInput, BlockReplaceOutput> {
+  return tool<BlockReplaceInput, BlockReplaceOutput>({
+    name: 'block_replace',
+    description:
+      'Replace a UNIQUE substring inside a working memory block. The substring must appear exactly once; the call fails fast if missing or non-unique. Use block_rethink for full rewrites.',
+    inputSchema: blockReplaceInputSchema,
+    outputSchema: blockReplaceOutputSchema,
+    sideEffectClass: 'side-effecting',
+    sandboxPolicy: 'none',
+    sensitivity: 'internal',
+    memoryGuardTier: 'memory-aware',
+    tags: ['memory', 'working'],
+    async execute(input, ctx) {
+      const scope = await deps.resolveScope(ctx);
+      const block = await deps.working.replace(scope, input.label, input.oldUnique, input.newText);
+      return { label: block.label, length: block.value.length };
+    },
+  });
+}
+
+/**
+ * `block_rethink` - rewrite a working memory block from scratch.
+ *
+ * @stable
+ */
+export function createBlockRethinkTool(
+  deps: MemoryToolDeps,
+): Tool<BlockRethinkInput, BlockRethinkOutput> {
+  return tool<BlockRethinkInput, BlockRethinkOutput>({
+    name: 'block_rethink',
+    description:
+      "Replace a working memory block's value entirely. Use this when restructuring or summarising the block's contents. For surgical edits, prefer block_replace.",
+    inputSchema: blockRethinkInputSchema,
+    outputSchema: blockRethinkOutputSchema,
+    sideEffectClass: 'side-effecting',
+    sandboxPolicy: 'none',
+    sensitivity: 'internal',
+    memoryGuardTier: 'memory-aware',
+    tags: ['memory', 'working'],
+    async execute(input, ctx) {
+      const scope = await deps.resolveScope(ctx);
+      const block = await deps.working.rethink(scope, input.label, () => input.newValue);
+      return { label: block.label, length: block.value.length };
+    },
+  });
+}

package/src/tools/fact-tools.ts

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