@graphorin/memory 0.5.0 → 0.6.1

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

@@ -24,7 +24,7 @@ interface BlockSpec {
    * runs preserve any value already in storage.
    */
   readonly defaultValue?: string;
-  /** Default `'truncate'` — `'reject'` opt-in for strict use cases. */
+  /** Default `'truncate'` - `'reject'` opt-in for strict use cases. */
   readonly overflowPolicy?: 'truncate' | 'reject';
   /** Optional free-form labels surfaced through `tags`. */
   readonly tags?: ReadonlyArray<string>;
@@ -56,7 +56,7 @@ interface BlockDefinition {
  */
 declare function defineBlock(spec: BlockSpec): BlockDefinition;
 /**
- * `WorkingMemory` — labeled, character-bounded blocks rendered into
+ * `WorkingMemory` - labeled, character-bounded blocks rendered into
  * every system prompt. Operations:
  *
  *  - `define(spec)`: idempotently registers a block definition; the
@@ -120,7 +120,7 @@ declare class WorkingMemory {
    *
    * The optional `agentId` argument is reserved for the per-agent
    * filtering Phase 10d wires through. In Phase 10a the argument is
-   * accepted but ignored — the rendering is scope-wide.
+   * accepted but ignored - the rendering is scope-wide.
    */
   compile(scope: SessionScope, agentId?: string): Promise<string>;
 }

package/dist/tiers/working-memory.js

@@ -26,7 +26,7 @@ function defineBlock(spec) {
 	});
 }
 /**
-* `WorkingMemory` — labeled, character-bounded blocks rendered into
+* `WorkingMemory` - labeled, character-bounded blocks rendered into
 * every system prompt. Operations:
 *
 *  - `define(spec)`: idempotently registers a block definition; the
@@ -152,7 +152,7 @@ var WorkingMemory = class {
 	*
 	* The optional `agentId` argument is reserved for the per-agent
 	* filtering Phase 10d wires through. In Phase 10a the argument is
-	* accepted but ignored — the rendering is scope-wide.
+	* accepted but ignored - the rendering is scope-wide.
 	*/
 	async compile(scope, agentId) {
 		const blocks = await this.list(scope);

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

@@ -1 +1 @@
-{"version":3,"file":"working-memory.js","names":["#store","#tracer","#defs","#mutate","#requireDefinition","block: Block"],"sources":["../../src/tiers/working-memory.ts"],"sourcesContent":["import type { Block, Sensitivity, SessionScope, Tracer, ZodLikeSchema } from '@graphorin/core';\nimport {\n  WorkingBlockOverflowError,\n  WorkingBlockReadOnlyError,\n  WorkingBlockReplaceMismatchError,\n} from '../errors/index.js';\nimport { newMemoryId } from '../internal/id.js';\nimport { withMemorySpan } from '../internal/spans.js';\nimport type { MemoryStoreAdapter } from '../internal/storage-adapter.js';\n\n/**\n * Author-time block specification accepted by\n * {@link defineBlock} and {@link WorkingMemory.define}.\n *\n * @stable\n */\nexport interface BlockSpec {\n  readonly label: string;\n  readonly description?: string;\n  readonly schema?: ZodLikeSchema<unknown>;\n  /** Maximum length of the rendered value in characters. */\n  readonly charLimit: number;\n  /** Default `'internal'`. */\n  readonly sensitivity?: Sensitivity;\n  /** Default `false`. */\n  readonly readOnly?: boolean;\n  /**\n   * Per-block default value. Applied on first definition only; later\n   * runs preserve any value already in storage.\n   */\n  readonly defaultValue?: string;\n  /** Default `'truncate'` — `'reject'` opt-in for strict use cases. */\n  readonly overflowPolicy?: 'truncate' | 'reject';\n  /** Optional free-form labels surfaced through `tags`. */\n  readonly tags?: ReadonlyArray<string>;\n}\n\n/**\n * Frozen block definition returned by {@link defineBlock}. Re-used by\n * the agent runtime / context engine to know which blocks should be\n * compiled into the system prompt every step.\n *\n * @stable\n */\nexport interface BlockDefinition {\n  readonly label: string;\n  readonly description?: string;\n  readonly schema?: ZodLikeSchema<unknown>;\n  readonly charLimit: number;\n  readonly sensitivity: Sensitivity;\n  readonly readOnly: boolean;\n  readonly defaultValue?: string;\n  readonly overflowPolicy: 'truncate' | 'reject';\n  readonly tags?: ReadonlyArray<string>;\n}\n\n/**\n * Build a frozen {@link BlockDefinition}. Surfaced as `blocks.define(...)`\n * for ergonomic call-sites; the underlying object is the same shape\n * the {@link WorkingMemory.define} method accepts.\n *\n * @stable\n */\nexport function defineBlock(spec: BlockSpec): BlockDefinition {\n  if (!spec.label || spec.label.length === 0) {\n    throw new TypeError('[graphorin/memory] BlockSpec.label must be a non-empty string.');\n  }\n  if (!Number.isInteger(spec.charLimit) || spec.charLimit <= 0) {\n    throw new TypeError(\n      `[graphorin/memory] BlockSpec.charLimit must be a positive integer, got ${String(spec.charLimit)}.`,\n    );\n  }\n  return Object.freeze({\n    label: spec.label,\n    ...(spec.description !== undefined ? { description: spec.description } : {}),\n    ...(spec.schema !== undefined ? { schema: spec.schema } : {}),\n    charLimit: spec.charLimit,\n    sensitivity: spec.sensitivity ?? 'internal',\n    readOnly: spec.readOnly ?? false,\n    ...(spec.defaultValue !== undefined ? { defaultValue: spec.defaultValue } : {}),\n    overflowPolicy: spec.overflowPolicy ?? 'truncate',\n    ...(spec.tags !== undefined ? { tags: Object.freeze([...spec.tags]) } : {}),\n  });\n}\n\n/**\n * `WorkingMemory` — labeled, character-bounded blocks rendered into\n * every system prompt. Operations:\n *\n *  - `define(spec)`: idempotently registers a block definition; the\n *    block's row is created in storage on the next `write` call so\n *    operators can change `description` between runs without\n *    triggering a write.\n *  - `read(scope, label)` / `list(scope)`: surface the current block\n *    contents.\n *  - `write(scope, label, value)`: full replace.\n *  - `append(scope, label, content)`: append-with-newline.\n *  - `replace(scope, label, oldUnique, newText)`: targeted replace\n *    with a uniqueness check.\n *  - `compile(scope)`: render the active blocks for the context\n *    engine (used by Phase 10d).\n *\n * @stable\n */\nexport class WorkingMemory {\n  readonly #store: MemoryStoreAdapter;\n  readonly #tracer: Tracer;\n  readonly #defs: Map<string, BlockDefinition>;\n\n  constructor(args: { store: MemoryStoreAdapter; tracer: Tracer }) {\n    this.#store = args.store;\n    this.#tracer = args.tracer;\n    this.#defs = new Map();\n  }\n\n  /** Register a block definition. Returns the same definition object. */\n  define(definition: BlockDefinition): BlockDefinition {\n    this.#defs.set(definition.label, definition);\n    return definition;\n  }\n\n  /** Snapshot of every registered definition. */\n  definitions(): ReadonlyArray<BlockDefinition> {\n    return Array.from(this.#defs.values());\n  }\n\n  /** Lookup a definition by label. */\n  definitionFor(label: string): BlockDefinition | undefined {\n    return this.#defs.get(label);\n  }\n\n  /** List active (non-deleted) blocks for the supplied scope. */\n  async list(scope: SessionScope): Promise<ReadonlyArray<Block>> {\n    return withMemorySpan(this.#tracer, 'memory.read.working', scope, {}, async (span) => {\n      const out = await this.#store.working.list(scope);\n      span.setAttributes({ 'memory.read.working.count': out.length });\n      return out;\n    });\n  }\n\n  /** Read a single block's value (or `null` when absent). */\n  async read(scope: SessionScope, label: string): Promise<string | null> {\n    return withMemorySpan(\n      this.#tracer,\n      'memory.read.working',\n      scope,\n      { 'memory.block.label': label },\n      async (span) => {\n        const block = await this.#store.working.get(scope, label);\n        span.setAttributes({ 'memory.read.working.found': block !== null });\n        if (block !== null) return block.value;\n        // MST-8: a defined-but-unwritten block answers with its declared\n        // defaultValue (previously advertised, copied into the\n        // definition, and then never read by anything).\n        const definition = this.#defs.get(label);\n        return definition?.defaultValue ?? null;\n      },\n    );\n  }\n\n  /** Replace a block's value entirely. Honours overflow policy. */\n  async write(scope: SessionScope, label: string, value: string): Promise<Block> {\n    return this.#mutate(scope, label, async () => value);\n  }\n\n  /** Append `content` to a block (with a newline separator). */\n  async append(scope: SessionScope, label: string, content: string): Promise<Block> {\n    return this.#mutate(scope, label, async (current) => {\n      if (current === '' || current === undefined) return content;\n      return `${current}\\n${content}`;\n    });\n  }\n\n  /**\n   * Replace the unique substring `oldUnique` inside the block's value\n   * with `newText`. Throws `WorkingBlockReplaceMismatchError` when\n   * the substring is missing or appears more than once.\n   */\n  async replace(\n    scope: SessionScope,\n    label: string,\n    oldUnique: string,\n    newText: string,\n  ): Promise<Block> {\n    return this.#mutate(scope, label, async (current) => {\n      const haystack = current ?? '';\n      const occurrences = countOccurrences(haystack, oldUnique);\n      if (occurrences !== 1) {\n        throw new WorkingBlockReplaceMismatchError(label, occurrences);\n      }\n      return haystack.replace(oldUnique, newText);\n    });\n  }\n\n  /** Run `mutator(current) => next` and persist the result. */\n  async rethink(\n    scope: SessionScope,\n    label: string,\n    mutator: (current: string) => string | Promise<string>,\n  ): Promise<Block> {\n    return this.#mutate(scope, label, async (current) => mutator(current ?? ''));\n  }\n\n  /** Soft-delete a block. */\n  async forget(scope: SessionScope, label: string, reason?: string): Promise<void> {\n    await withMemorySpan(\n      this.#tracer,\n      'memory.write.working',\n      scope,\n      { 'memory.block.label': label, 'memory.write.working.action': 'forget' },\n      async () => {\n        await this.#store.working.delete(scope, label, reason);\n      },\n    );\n  }\n\n  /**\n   * Attach a working block to an additional agent. Backed by the\n   * adapter's `shared.attach(...)` join table so multi-agent crews\n   * can share the same block without duplicating storage.\n   */\n  async attach(scope: SessionScope, blockId: string, agentId: string): Promise<void> {\n    await withMemorySpan(\n      this.#tracer,\n      'memory.write.working',\n      scope,\n      {\n        'memory.write.working.action': 'attach',\n        'memory.block.id': blockId,\n        'memory.write.working.target_agent_id': agentId,\n      },\n      async () => {\n        await this.#store.shared.attach(blockId, agentId);\n      },\n    );\n  }\n\n  /** Detach a working block from an agent. */\n  async detach(scope: SessionScope, blockId: string, agentId: string): Promise<void> {\n    await withMemorySpan(\n      this.#tracer,\n      'memory.write.working',\n      scope,\n      {\n        'memory.write.working.action': 'detach',\n        'memory.block.id': blockId,\n        'memory.write.working.target_agent_id': agentId,\n      },\n      async () => {\n        await this.#store.shared.detach(blockId, agentId);\n      },\n    );\n  }\n\n  /**\n   * Render a deterministic `<memory_blocks>` XML fragment for the\n   * supplied scope. The full layered system prompt (six layers) is\n   * produced by Phase 10d's ContextEngine; this method ships the\n   * minimum-viable rendering used by the smoke acceptance criteria.\n   *\n   * The optional `agentId` argument is reserved for the per-agent\n   * filtering Phase 10d wires through. In Phase 10a the argument is\n   * accepted but ignored — the rendering is scope-wide.\n   */\n  async compile(scope: SessionScope, agentId?: string): Promise<string> {\n    void agentId;\n    const blocks = await this.list(scope);\n    if (blocks.length === 0) return '';\n    const lines = ['<memory_blocks>'];\n    for (const block of blocks) {\n      const description =\n        block.description !== undefined ? ` description=\"${escapeXml(block.description)}\"` : '';\n      lines.push(`  <block label=\"${escapeXml(block.label)}\"${description}>`);\n      lines.push(`    ${escapeXml(block.value)}`);\n      lines.push('  </block>');\n    }\n    lines.push('</memory_blocks>');\n    return lines.join('\\n');\n  }\n\n  async #mutate(\n    scope: SessionScope,\n    label: string,\n    nextValueFn: (current: string | undefined) => Promise<string>,\n  ): Promise<Block> {\n    return withMemorySpan(\n      this.#tracer,\n      'memory.write.working',\n      scope,\n      { 'memory.block.label': label },\n      async (span) => {\n        const definition = this.#requireDefinition(label);\n        if (definition.readOnly === true) {\n          // MRET-14: a dedicated kind — the old\n          // WorkingBlockReplaceMismatchError(label, 0) read as \"substring\n          // matched 0 times\" and misled replace-retry callers.\n          throw new WorkingBlockReadOnlyError(label);\n        }\n        const existing = await this.#store.working.get(scope, label);\n        // MST-8: first materialization starts from the declared default,\n        // so an append/replace on an unwritten block composes with it.\n        const candidate = await nextValueFn(existing?.value ?? definition.defaultValue);\n        const enforcedValue = enforceCharLimit(candidate, definition);\n        const now = new Date().toISOString();\n        const id = existing?.id ?? newMemoryId('block');\n        const block: Block = {\n          id,\n          kind: 'working',\n          userId: scope.userId,\n          ...(scope.sessionId !== undefined ? { sessionId: scope.sessionId } : {}),\n          ...(scope.agentId !== undefined ? { agentId: scope.agentId } : {}),\n          sensitivity: definition.sensitivity,\n          label,\n          ...(definition.description !== undefined ? { description: definition.description } : {}),\n          value: enforcedValue,\n          charLimit: definition.charLimit,\n          readOnly: definition.readOnly,\n          ...(definition.tags !== undefined ? { tags: definition.tags } : {}),\n          createdAt: existing?.createdAt ?? now,\n          updatedAt: now,\n        };\n        await this.#store.working.upsert(scope, block);\n        span.setAttributes({\n          'memory.write.working.action': existing === null ? 'create' : 'update',\n          'memory.write.working.length': enforcedValue.length,\n        });\n        return block;\n      },\n    );\n  }\n\n  #requireDefinition(label: string): BlockDefinition {\n    const def = this.#defs.get(label);\n    if (def !== undefined) return def;\n    throw new TypeError(\n      `[graphorin/memory] working block '${label}' was not defined. ` +\n        'Call memory.working.define(blocks.define({...})) before writing to it.',\n    );\n  }\n}\n\nfunction enforceCharLimit(value: string, definition: BlockDefinition): string {\n  if (value.length <= definition.charLimit) return value;\n  if (definition.overflowPolicy === 'reject') {\n    throw new WorkingBlockOverflowError(definition.label, value.length, definition.charLimit);\n  }\n  return value.slice(0, definition.charLimit);\n}\n\nfunction countOccurrences(haystack: string, needle: string): number {\n  if (needle.length === 0) return 0;\n  let count = 0;\n  let idx = 0;\n  for (;;) {\n    const next = haystack.indexOf(needle, idx);\n    if (next === -1) return count;\n    count += 1;\n    idx = next + needle.length;\n  }\n}\n\nfunction escapeXml(value: string): string {\n  return value\n    .replace(/&/g, '&amp;')\n    .replace(/</g, '&lt;')\n    .replace(/>/g, '&gt;')\n    .replace(/\"/g, '&quot;');\n}\n"],"mappings":"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"}
+{"version":3,"file":"working-memory.js","names":["#store","#tracer","#defs","#mutate","#requireDefinition","block: Block"],"sources":["../../src/tiers/working-memory.ts"],"sourcesContent":["import type { Block, Sensitivity, SessionScope, Tracer, ZodLikeSchema } from '@graphorin/core';\nimport {\n  WorkingBlockOverflowError,\n  WorkingBlockReadOnlyError,\n  WorkingBlockReplaceMismatchError,\n} from '../errors/index.js';\nimport { newMemoryId } from '../internal/id.js';\nimport { withMemorySpan } from '../internal/spans.js';\nimport type { MemoryStoreAdapter } from '../internal/storage-adapter.js';\n\n/**\n * Author-time block specification accepted by\n * {@link defineBlock} and {@link WorkingMemory.define}.\n *\n * @stable\n */\nexport interface BlockSpec {\n  readonly label: string;\n  readonly description?: string;\n  readonly schema?: ZodLikeSchema<unknown>;\n  /** Maximum length of the rendered value in characters. */\n  readonly charLimit: number;\n  /** Default `'internal'`. */\n  readonly sensitivity?: Sensitivity;\n  /** Default `false`. */\n  readonly readOnly?: boolean;\n  /**\n   * Per-block default value. Applied on first definition only; later\n   * runs preserve any value already in storage.\n   */\n  readonly defaultValue?: string;\n  /** Default `'truncate'` - `'reject'` opt-in for strict use cases. */\n  readonly overflowPolicy?: 'truncate' | 'reject';\n  /** Optional free-form labels surfaced through `tags`. */\n  readonly tags?: ReadonlyArray<string>;\n}\n\n/**\n * Frozen block definition returned by {@link defineBlock}. Re-used by\n * the agent runtime / context engine to know which blocks should be\n * compiled into the system prompt every step.\n *\n * @stable\n */\nexport interface BlockDefinition {\n  readonly label: string;\n  readonly description?: string;\n  readonly schema?: ZodLikeSchema<unknown>;\n  readonly charLimit: number;\n  readonly sensitivity: Sensitivity;\n  readonly readOnly: boolean;\n  readonly defaultValue?: string;\n  readonly overflowPolicy: 'truncate' | 'reject';\n  readonly tags?: ReadonlyArray<string>;\n}\n\n/**\n * Build a frozen {@link BlockDefinition}. Surfaced as `blocks.define(...)`\n * for ergonomic call-sites; the underlying object is the same shape\n * the {@link WorkingMemory.define} method accepts.\n *\n * @stable\n */\nexport function defineBlock(spec: BlockSpec): BlockDefinition {\n  if (!spec.label || spec.label.length === 0) {\n    throw new TypeError('[graphorin/memory] BlockSpec.label must be a non-empty string.');\n  }\n  if (!Number.isInteger(spec.charLimit) || spec.charLimit <= 0) {\n    throw new TypeError(\n      `[graphorin/memory] BlockSpec.charLimit must be a positive integer, got ${String(spec.charLimit)}.`,\n    );\n  }\n  return Object.freeze({\n    label: spec.label,\n    ...(spec.description !== undefined ? { description: spec.description } : {}),\n    ...(spec.schema !== undefined ? { schema: spec.schema } : {}),\n    charLimit: spec.charLimit,\n    sensitivity: spec.sensitivity ?? 'internal',\n    readOnly: spec.readOnly ?? false,\n    ...(spec.defaultValue !== undefined ? { defaultValue: spec.defaultValue } : {}),\n    overflowPolicy: spec.overflowPolicy ?? 'truncate',\n    ...(spec.tags !== undefined ? { tags: Object.freeze([...spec.tags]) } : {}),\n  });\n}\n\n/**\n * `WorkingMemory` - labeled, character-bounded blocks rendered into\n * every system prompt. Operations:\n *\n *  - `define(spec)`: idempotently registers a block definition; the\n *    block's row is created in storage on the next `write` call so\n *    operators can change `description` between runs without\n *    triggering a write.\n *  - `read(scope, label)` / `list(scope)`: surface the current block\n *    contents.\n *  - `write(scope, label, value)`: full replace.\n *  - `append(scope, label, content)`: append-with-newline.\n *  - `replace(scope, label, oldUnique, newText)`: targeted replace\n *    with a uniqueness check.\n *  - `compile(scope)`: render the active blocks for the context\n *    engine (used by Phase 10d).\n *\n * @stable\n */\nexport class WorkingMemory {\n  readonly #store: MemoryStoreAdapter;\n  readonly #tracer: Tracer;\n  readonly #defs: Map<string, BlockDefinition>;\n\n  constructor(args: { store: MemoryStoreAdapter; tracer: Tracer }) {\n    this.#store = args.store;\n    this.#tracer = args.tracer;\n    this.#defs = new Map();\n  }\n\n  /** Register a block definition. Returns the same definition object. */\n  define(definition: BlockDefinition): BlockDefinition {\n    this.#defs.set(definition.label, definition);\n    return definition;\n  }\n\n  /** Snapshot of every registered definition. */\n  definitions(): ReadonlyArray<BlockDefinition> {\n    return Array.from(this.#defs.values());\n  }\n\n  /** Lookup a definition by label. */\n  definitionFor(label: string): BlockDefinition | undefined {\n    return this.#defs.get(label);\n  }\n\n  /** List active (non-deleted) blocks for the supplied scope. */\n  async list(scope: SessionScope): Promise<ReadonlyArray<Block>> {\n    return withMemorySpan(this.#tracer, 'memory.read.working', scope, {}, async (span) => {\n      const out = await this.#store.working.list(scope);\n      span.setAttributes({ 'memory.read.working.count': out.length });\n      return out;\n    });\n  }\n\n  /** Read a single block's value (or `null` when absent). */\n  async read(scope: SessionScope, label: string): Promise<string | null> {\n    return withMemorySpan(\n      this.#tracer,\n      'memory.read.working',\n      scope,\n      { 'memory.block.label': label },\n      async (span) => {\n        const block = await this.#store.working.get(scope, label);\n        span.setAttributes({ 'memory.read.working.found': block !== null });\n        if (block !== null) return block.value;\n        // MST-8: a defined-but-unwritten block answers with its declared\n        // defaultValue (previously advertised, copied into the\n        // definition, and then never read by anything).\n        const definition = this.#defs.get(label);\n        return definition?.defaultValue ?? null;\n      },\n    );\n  }\n\n  /** Replace a block's value entirely. Honours overflow policy. */\n  async write(scope: SessionScope, label: string, value: string): Promise<Block> {\n    return this.#mutate(scope, label, async () => value);\n  }\n\n  /** Append `content` to a block (with a newline separator). */\n  async append(scope: SessionScope, label: string, content: string): Promise<Block> {\n    return this.#mutate(scope, label, async (current) => {\n      if (current === '' || current === undefined) return content;\n      return `${current}\\n${content}`;\n    });\n  }\n\n  /**\n   * Replace the unique substring `oldUnique` inside the block's value\n   * with `newText`. Throws `WorkingBlockReplaceMismatchError` when\n   * the substring is missing or appears more than once.\n   */\n  async replace(\n    scope: SessionScope,\n    label: string,\n    oldUnique: string,\n    newText: string,\n  ): Promise<Block> {\n    return this.#mutate(scope, label, async (current) => {\n      const haystack = current ?? '';\n      const occurrences = countOccurrences(haystack, oldUnique);\n      if (occurrences !== 1) {\n        throw new WorkingBlockReplaceMismatchError(label, occurrences);\n      }\n      return haystack.replace(oldUnique, newText);\n    });\n  }\n\n  /** Run `mutator(current) => next` and persist the result. */\n  async rethink(\n    scope: SessionScope,\n    label: string,\n    mutator: (current: string) => string | Promise<string>,\n  ): Promise<Block> {\n    return this.#mutate(scope, label, async (current) => mutator(current ?? ''));\n  }\n\n  /** Soft-delete a block. */\n  async forget(scope: SessionScope, label: string, reason?: string): Promise<void> {\n    await withMemorySpan(\n      this.#tracer,\n      'memory.write.working',\n      scope,\n      { 'memory.block.label': label, 'memory.write.working.action': 'forget' },\n      async () => {\n        await this.#store.working.delete(scope, label, reason);\n      },\n    );\n  }\n\n  /**\n   * Attach a working block to an additional agent. Backed by the\n   * adapter's `shared.attach(...)` join table so multi-agent crews\n   * can share the same block without duplicating storage.\n   */\n  async attach(scope: SessionScope, blockId: string, agentId: string): Promise<void> {\n    await withMemorySpan(\n      this.#tracer,\n      'memory.write.working',\n      scope,\n      {\n        'memory.write.working.action': 'attach',\n        'memory.block.id': blockId,\n        'memory.write.working.target_agent_id': agentId,\n      },\n      async () => {\n        await this.#store.shared.attach(blockId, agentId);\n      },\n    );\n  }\n\n  /** Detach a working block from an agent. */\n  async detach(scope: SessionScope, blockId: string, agentId: string): Promise<void> {\n    await withMemorySpan(\n      this.#tracer,\n      'memory.write.working',\n      scope,\n      {\n        'memory.write.working.action': 'detach',\n        'memory.block.id': blockId,\n        'memory.write.working.target_agent_id': agentId,\n      },\n      async () => {\n        await this.#store.shared.detach(blockId, agentId);\n      },\n    );\n  }\n\n  /**\n   * Render a deterministic `<memory_blocks>` XML fragment for the\n   * supplied scope. The full layered system prompt (six layers) is\n   * produced by Phase 10d's ContextEngine; this method ships the\n   * minimum-viable rendering used by the smoke acceptance criteria.\n   *\n   * The optional `agentId` argument is reserved for the per-agent\n   * filtering Phase 10d wires through. In Phase 10a the argument is\n   * accepted but ignored - the rendering is scope-wide.\n   */\n  async compile(scope: SessionScope, agentId?: string): Promise<string> {\n    void agentId;\n    const blocks = await this.list(scope);\n    if (blocks.length === 0) return '';\n    const lines = ['<memory_blocks>'];\n    for (const block of blocks) {\n      const description =\n        block.description !== undefined ? ` description=\"${escapeXml(block.description)}\"` : '';\n      lines.push(`  <block label=\"${escapeXml(block.label)}\"${description}>`);\n      lines.push(`    ${escapeXml(block.value)}`);\n      lines.push('  </block>');\n    }\n    lines.push('</memory_blocks>');\n    return lines.join('\\n');\n  }\n\n  async #mutate(\n    scope: SessionScope,\n    label: string,\n    nextValueFn: (current: string | undefined) => Promise<string>,\n  ): Promise<Block> {\n    return withMemorySpan(\n      this.#tracer,\n      'memory.write.working',\n      scope,\n      { 'memory.block.label': label },\n      async (span) => {\n        const definition = this.#requireDefinition(label);\n        if (definition.readOnly === true) {\n          // MRET-14: a dedicated kind - the old\n          // WorkingBlockReplaceMismatchError(label, 0) read as \"substring\n          // matched 0 times\" and misled replace-retry callers.\n          throw new WorkingBlockReadOnlyError(label);\n        }\n        const existing = await this.#store.working.get(scope, label);\n        // MST-8: first materialization starts from the declared default,\n        // so an append/replace on an unwritten block composes with it.\n        const candidate = await nextValueFn(existing?.value ?? definition.defaultValue);\n        const enforcedValue = enforceCharLimit(candidate, definition);\n        const now = new Date().toISOString();\n        const id = existing?.id ?? newMemoryId('block');\n        const block: Block = {\n          id,\n          kind: 'working',\n          userId: scope.userId,\n          ...(scope.sessionId !== undefined ? { sessionId: scope.sessionId } : {}),\n          ...(scope.agentId !== undefined ? { agentId: scope.agentId } : {}),\n          sensitivity: definition.sensitivity,\n          label,\n          ...(definition.description !== undefined ? { description: definition.description } : {}),\n          value: enforcedValue,\n          charLimit: definition.charLimit,\n          readOnly: definition.readOnly,\n          ...(definition.tags !== undefined ? { tags: definition.tags } : {}),\n          createdAt: existing?.createdAt ?? now,\n          updatedAt: now,\n        };\n        await this.#store.working.upsert(scope, block);\n        span.setAttributes({\n          'memory.write.working.action': existing === null ? 'create' : 'update',\n          'memory.write.working.length': enforcedValue.length,\n        });\n        return block;\n      },\n    );\n  }\n\n  #requireDefinition(label: string): BlockDefinition {\n    const def = this.#defs.get(label);\n    if (def !== undefined) return def;\n    throw new TypeError(\n      `[graphorin/memory] working block '${label}' was not defined. ` +\n        'Call memory.working.define(blocks.define({...})) before writing to it.',\n    );\n  }\n}\n\nfunction enforceCharLimit(value: string, definition: BlockDefinition): string {\n  if (value.length <= definition.charLimit) return value;\n  if (definition.overflowPolicy === 'reject') {\n    throw new WorkingBlockOverflowError(definition.label, value.length, definition.charLimit);\n  }\n  return value.slice(0, definition.charLimit);\n}\n\nfunction countOccurrences(haystack: string, needle: string): number {\n  if (needle.length === 0) return 0;\n  let count = 0;\n  let idx = 0;\n  for (;;) {\n    const next = haystack.indexOf(needle, idx);\n    if (next === -1) return count;\n    count += 1;\n    idx = next + needle.length;\n  }\n}\n\nfunction escapeXml(value: string): string {\n  return value\n    .replace(/&/g, '&amp;')\n    .replace(/</g, '&lt;')\n    .replace(/>/g, '&gt;')\n    .replace(/\"/g, '&quot;');\n}\n"],"mappings":"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"}

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

@@ -73,14 +73,14 @@ declare const blockRethinkOutputSchema: z.ZodObject<{
 type BlockRethinkInput = z.infer<typeof blockRethinkInputSchema>;
 type BlockRethinkOutput = z.infer<typeof blockRethinkOutputSchema>;
 /**
- * `block_append` — append text (with a newline separator) to a working
+ * `block_append` - append text (with a newline separator) to a working
  * memory block.
  *
  * @stable
  */
 declare function createBlockAppendTool(deps: MemoryToolDeps): Tool<BlockAppendInput, BlockAppendOutput>;
 /**
- * `block_replace` — replace a unique substring inside a working
+ * `block_replace` - replace a unique substring inside a working
  * memory block. Throws when the substring is missing or appears more
  * than once.
  *
@@ -88,7 +88,7 @@ declare function createBlockAppendTool(deps: MemoryToolDeps): Tool<BlockAppendIn
  */
 declare function createBlockReplaceTool(deps: MemoryToolDeps): Tool<BlockReplaceInput, BlockReplaceOutput>;
 /**
- * `block_rethink` — rewrite a working memory block from scratch.
+ * `block_rethink` - rewrite a working memory block from scratch.
  *
  * @stable
  */

package/dist/tools/block-tools.js

@@ -28,7 +28,7 @@ const blockRethinkOutputSchema = z.object({
 	length: z.number()
 });
 /**
-* `block_append` — append text (with a newline separator) to a working
+* `block_append` - append text (with a newline separator) to a working
 * memory block.
 *
 * @stable
@@ -55,7 +55,7 @@ function createBlockAppendTool(deps) {
 	});
 }
 /**
-* `block_replace` — replace a unique substring inside a working
+* `block_replace` - replace a unique substring inside a working
 * memory block. Throws when the substring is missing or appears more
 * than once.
 *
@@ -83,7 +83,7 @@ function createBlockReplaceTool(deps) {
 	});
 }
 /**
-* `block_rethink` — rewrite a working memory block from scratch.
+* `block_rethink` - rewrite a working memory block from scratch.
 *
 * @stable
 */

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

@@ -1 +1 @@
-{"version":3,"file":"block-tools.js","names":[],"sources":["../../src/tools/block-tools.ts"],"sourcesContent":["import type { Tool } from '@graphorin/core';\nimport { tool } from '@graphorin/tools';\nimport { z } from 'zod';\nimport type { MemoryToolDeps } from './types.js';\n\nconst blockAppendInputSchema = z.object({\n  label: z.string().min(1).max(128),\n  content: z.string().min(1),\n});\nconst blockAppendOutputSchema = z.object({\n  label: z.string(),\n  length: z.number(),\n});\n\ntype BlockAppendInput = z.infer<typeof blockAppendInputSchema>;\ntype BlockAppendOutput = z.infer<typeof blockAppendOutputSchema>;\n\nconst blockReplaceInputSchema = z.object({\n  label: z.string().min(1).max(128),\n  oldUnique: z.string().min(1),\n  newText: z.string(),\n});\nconst blockReplaceOutputSchema = z.object({\n  label: z.string(),\n  length: z.number(),\n});\n\ntype BlockReplaceInput = z.infer<typeof blockReplaceInputSchema>;\ntype BlockReplaceOutput = z.infer<typeof blockReplaceOutputSchema>;\n\nconst blockRethinkInputSchema = z.object({\n  label: z.string().min(1).max(128),\n  newValue: z.string(),\n});\nconst blockRethinkOutputSchema = z.object({\n  label: z.string(),\n  length: z.number(),\n});\n\ntype BlockRethinkInput = z.infer<typeof blockRethinkInputSchema>;\ntype BlockRethinkOutput = z.infer<typeof blockRethinkOutputSchema>;\n\n/**\n * `block_append` — append text (with a newline separator) to a working\n * memory block.\n *\n * @stable\n */\nexport function createBlockAppendTool(\n  deps: MemoryToolDeps,\n): Tool<BlockAppendInput, BlockAppendOutput> {\n  return tool<BlockAppendInput, BlockAppendOutput>({\n    name: 'block_append',\n    description:\n      '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.',\n    inputSchema: blockAppendInputSchema,\n    outputSchema: blockAppendOutputSchema,\n    sideEffectClass: 'side-effecting',\n    sandboxPolicy: 'none',\n    sensitivity: 'internal',\n    memoryGuardTier: 'memory-aware',\n    tags: ['memory', 'working'],\n    async execute(input, ctx) {\n      const scope = await deps.resolveScope(ctx);\n      const block = await deps.working.append(scope, input.label, input.content);\n      return { label: block.label, length: block.value.length };\n    },\n  });\n}\n\n/**\n * `block_replace` — replace a unique substring inside a working\n * memory block. Throws when the substring is missing or appears more\n * than once.\n *\n * @stable\n */\nexport function createBlockReplaceTool(\n  deps: MemoryToolDeps,\n): Tool<BlockReplaceInput, BlockReplaceOutput> {\n  return tool<BlockReplaceInput, BlockReplaceOutput>({\n    name: 'block_replace',\n    description:\n      '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.',\n    inputSchema: blockReplaceInputSchema,\n    outputSchema: blockReplaceOutputSchema,\n    sideEffectClass: 'side-effecting',\n    sandboxPolicy: 'none',\n    sensitivity: 'internal',\n    memoryGuardTier: 'memory-aware',\n    tags: ['memory', 'working'],\n    async execute(input, ctx) {\n      const scope = await deps.resolveScope(ctx);\n      const block = await deps.working.replace(scope, input.label, input.oldUnique, input.newText);\n      return { label: block.label, length: block.value.length };\n    },\n  });\n}\n\n/**\n * `block_rethink` — rewrite a working memory block from scratch.\n *\n * @stable\n */\nexport function createBlockRethinkTool(\n  deps: MemoryToolDeps,\n): Tool<BlockRethinkInput, BlockRethinkOutput> {\n  return tool<BlockRethinkInput, BlockRethinkOutput>({\n    name: 'block_rethink',\n    description:\n      \"Replace a working memory block's value entirely. Use this when restructuring or summarising the block's contents. For surgical edits, prefer block_replace.\",\n    inputSchema: blockRethinkInputSchema,\n    outputSchema: blockRethinkOutputSchema,\n    sideEffectClass: 'side-effecting',\n    sandboxPolicy: 'none',\n    sensitivity: 'internal',\n    memoryGuardTier: 'memory-aware',\n    tags: ['memory', 'working'],\n    async execute(input, ctx) {\n      const scope = await deps.resolveScope(ctx);\n      const block = await deps.working.rethink(scope, input.label, () => input.newValue);\n      return { label: block.label, length: block.value.length };\n    },\n  });\n}\n"],"mappings":";;;;AAKA,MAAM,yBAAyB,EAAE,OAAO;CACtC,OAAO,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,IAAI;CACjC,SAAS,EAAE,QAAQ,CAAC,IAAI,EAAE;CAC3B,CAAC;AACF,MAAM,0BAA0B,EAAE,OAAO;CACvC,OAAO,EAAE,QAAQ;CACjB,QAAQ,EAAE,QAAQ;CACnB,CAAC;AAKF,MAAM,0BAA0B,EAAE,OAAO;CACvC,OAAO,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,IAAI;CACjC,WAAW,EAAE,QAAQ,CAAC,IAAI,EAAE;CAC5B,SAAS,EAAE,QAAQ;CACpB,CAAC;AACF,MAAM,2BAA2B,EAAE,OAAO;CACxC,OAAO,EAAE,QAAQ;CACjB,QAAQ,EAAE,QAAQ;CACnB,CAAC;AAKF,MAAM,0BAA0B,EAAE,OAAO;CACvC,OAAO,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,IAAI;CACjC,UAAU,EAAE,QAAQ;CACrB,CAAC;AACF,MAAM,2BAA2B,EAAE,OAAO;CACxC,OAAO,EAAE,QAAQ;CACjB,QAAQ,EAAE,QAAQ;CACnB,CAAC;;;;;;;AAWF,SAAgB,sBACd,MAC2C;AAC3C,QAAO,KAA0C;EAC/C,MAAM;EACN,aACE;EACF,aAAa;EACb,cAAc;EACd,iBAAiB;EACjB,eAAe;EACf,aAAa;EACb,iBAAiB;EACjB,MAAM,CAAC,UAAU,UAAU;EAC3B,MAAM,QAAQ,OAAO,KAAK;GACxB,MAAM,QAAQ,MAAM,KAAK,aAAa,IAAI;GAC1C,MAAM,QAAQ,MAAM,KAAK,QAAQ,OAAO,OAAO,MAAM,OAAO,MAAM,QAAQ;AAC1E,UAAO;IAAE,OAAO,MAAM;IAAO,QAAQ,MAAM,MAAM;IAAQ;;EAE5D,CAAC;;;;;;;;;AAUJ,SAAgB,uBACd,MAC6C;AAC7C,QAAO,KAA4C;EACjD,MAAM;EACN,aACE;EACF,aAAa;EACb,cAAc;EACd,iBAAiB;EACjB,eAAe;EACf,aAAa;EACb,iBAAiB;EACjB,MAAM,CAAC,UAAU,UAAU;EAC3B,MAAM,QAAQ,OAAO,KAAK;GACxB,MAAM,QAAQ,MAAM,KAAK,aAAa,IAAI;GAC1C,MAAM,QAAQ,MAAM,KAAK,QAAQ,QAAQ,OAAO,MAAM,OAAO,MAAM,WAAW,MAAM,QAAQ;AAC5F,UAAO;IAAE,OAAO,MAAM;IAAO,QAAQ,MAAM,MAAM;IAAQ;;EAE5D,CAAC;;;;;;;AAQJ,SAAgB,uBACd,MAC6C;AAC7C,QAAO,KAA4C;EACjD,MAAM;EACN,aACE;EACF,aAAa;EACb,cAAc;EACd,iBAAiB;EACjB,eAAe;EACf,aAAa;EACb,iBAAiB;EACjB,MAAM,CAAC,UAAU,UAAU;EAC3B,MAAM,QAAQ,OAAO,KAAK;GACxB,MAAM,QAAQ,MAAM,KAAK,aAAa,IAAI;GAC1C,MAAM,QAAQ,MAAM,KAAK,QAAQ,QAAQ,OAAO,MAAM,aAAa,MAAM,SAAS;AAClF,UAAO;IAAE,OAAO,MAAM;IAAO,QAAQ,MAAM,MAAM;IAAQ;;EAE5D,CAAC"}
+{"version":3,"file":"block-tools.js","names":[],"sources":["../../src/tools/block-tools.ts"],"sourcesContent":["import type { Tool } from '@graphorin/core';\nimport { tool } from '@graphorin/tools';\nimport { z } from 'zod';\nimport type { MemoryToolDeps } from './types.js';\n\nconst blockAppendInputSchema = z.object({\n  label: z.string().min(1).max(128),\n  content: z.string().min(1),\n});\nconst blockAppendOutputSchema = z.object({\n  label: z.string(),\n  length: z.number(),\n});\n\ntype BlockAppendInput = z.infer<typeof blockAppendInputSchema>;\ntype BlockAppendOutput = z.infer<typeof blockAppendOutputSchema>;\n\nconst blockReplaceInputSchema = z.object({\n  label: z.string().min(1).max(128),\n  oldUnique: z.string().min(1),\n  newText: z.string(),\n});\nconst blockReplaceOutputSchema = z.object({\n  label: z.string(),\n  length: z.number(),\n});\n\ntype BlockReplaceInput = z.infer<typeof blockReplaceInputSchema>;\ntype BlockReplaceOutput = z.infer<typeof blockReplaceOutputSchema>;\n\nconst blockRethinkInputSchema = z.object({\n  label: z.string().min(1).max(128),\n  newValue: z.string(),\n});\nconst blockRethinkOutputSchema = z.object({\n  label: z.string(),\n  length: z.number(),\n});\n\ntype BlockRethinkInput = z.infer<typeof blockRethinkInputSchema>;\ntype BlockRethinkOutput = z.infer<typeof blockRethinkOutputSchema>;\n\n/**\n * `block_append` - append text (with a newline separator) to a working\n * memory block.\n *\n * @stable\n */\nexport function createBlockAppendTool(\n  deps: MemoryToolDeps,\n): Tool<BlockAppendInput, BlockAppendOutput> {\n  return tool<BlockAppendInput, BlockAppendOutput>({\n    name: 'block_append',\n    description:\n      '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.',\n    inputSchema: blockAppendInputSchema,\n    outputSchema: blockAppendOutputSchema,\n    sideEffectClass: 'side-effecting',\n    sandboxPolicy: 'none',\n    sensitivity: 'internal',\n    memoryGuardTier: 'memory-aware',\n    tags: ['memory', 'working'],\n    async execute(input, ctx) {\n      const scope = await deps.resolveScope(ctx);\n      const block = await deps.working.append(scope, input.label, input.content);\n      return { label: block.label, length: block.value.length };\n    },\n  });\n}\n\n/**\n * `block_replace` - replace a unique substring inside a working\n * memory block. Throws when the substring is missing or appears more\n * than once.\n *\n * @stable\n */\nexport function createBlockReplaceTool(\n  deps: MemoryToolDeps,\n): Tool<BlockReplaceInput, BlockReplaceOutput> {\n  return tool<BlockReplaceInput, BlockReplaceOutput>({\n    name: 'block_replace',\n    description:\n      '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.',\n    inputSchema: blockReplaceInputSchema,\n    outputSchema: blockReplaceOutputSchema,\n    sideEffectClass: 'side-effecting',\n    sandboxPolicy: 'none',\n    sensitivity: 'internal',\n    memoryGuardTier: 'memory-aware',\n    tags: ['memory', 'working'],\n    async execute(input, ctx) {\n      const scope = await deps.resolveScope(ctx);\n      const block = await deps.working.replace(scope, input.label, input.oldUnique, input.newText);\n      return { label: block.label, length: block.value.length };\n    },\n  });\n}\n\n/**\n * `block_rethink` - rewrite a working memory block from scratch.\n *\n * @stable\n */\nexport function createBlockRethinkTool(\n  deps: MemoryToolDeps,\n): Tool<BlockRethinkInput, BlockRethinkOutput> {\n  return tool<BlockRethinkInput, BlockRethinkOutput>({\n    name: 'block_rethink',\n    description:\n      \"Replace a working memory block's value entirely. Use this when restructuring or summarising the block's contents. For surgical edits, prefer block_replace.\",\n    inputSchema: blockRethinkInputSchema,\n    outputSchema: blockRethinkOutputSchema,\n    sideEffectClass: 'side-effecting',\n    sandboxPolicy: 'none',\n    sensitivity: 'internal',\n    memoryGuardTier: 'memory-aware',\n    tags: ['memory', 'working'],\n    async execute(input, ctx) {\n      const scope = await deps.resolveScope(ctx);\n      const block = await deps.working.rethink(scope, input.label, () => input.newValue);\n      return { label: block.label, length: block.value.length };\n    },\n  });\n}\n"],"mappings":";;;;AAKA,MAAM,yBAAyB,EAAE,OAAO;CACtC,OAAO,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,IAAI;CACjC,SAAS,EAAE,QAAQ,CAAC,IAAI,EAAE;CAC3B,CAAC;AACF,MAAM,0BAA0B,EAAE,OAAO;CACvC,OAAO,EAAE,QAAQ;CACjB,QAAQ,EAAE,QAAQ;CACnB,CAAC;AAKF,MAAM,0BAA0B,EAAE,OAAO;CACvC,OAAO,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,IAAI;CACjC,WAAW,EAAE,QAAQ,CAAC,IAAI,EAAE;CAC5B,SAAS,EAAE,QAAQ;CACpB,CAAC;AACF,MAAM,2BAA2B,EAAE,OAAO;CACxC,OAAO,EAAE,QAAQ;CACjB,QAAQ,EAAE,QAAQ;CACnB,CAAC;AAKF,MAAM,0BAA0B,EAAE,OAAO;CACvC,OAAO,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,IAAI;CACjC,UAAU,EAAE,QAAQ;CACrB,CAAC;AACF,MAAM,2BAA2B,EAAE,OAAO;CACxC,OAAO,EAAE,QAAQ;CACjB,QAAQ,EAAE,QAAQ;CACnB,CAAC;;;;;;;AAWF,SAAgB,sBACd,MAC2C;AAC3C,QAAO,KAA0C;EAC/C,MAAM;EACN,aACE;EACF,aAAa;EACb,cAAc;EACd,iBAAiB;EACjB,eAAe;EACf,aAAa;EACb,iBAAiB;EACjB,MAAM,CAAC,UAAU,UAAU;EAC3B,MAAM,QAAQ,OAAO,KAAK;GACxB,MAAM,QAAQ,MAAM,KAAK,aAAa,IAAI;GAC1C,MAAM,QAAQ,MAAM,KAAK,QAAQ,OAAO,OAAO,MAAM,OAAO,MAAM,QAAQ;AAC1E,UAAO;IAAE,OAAO,MAAM;IAAO,QAAQ,MAAM,MAAM;IAAQ;;EAE5D,CAAC;;;;;;;;;AAUJ,SAAgB,uBACd,MAC6C;AAC7C,QAAO,KAA4C;EACjD,MAAM;EACN,aACE;EACF,aAAa;EACb,cAAc;EACd,iBAAiB;EACjB,eAAe;EACf,aAAa;EACb,iBAAiB;EACjB,MAAM,CAAC,UAAU,UAAU;EAC3B,MAAM,QAAQ,OAAO,KAAK;GACxB,MAAM,QAAQ,MAAM,KAAK,aAAa,IAAI;GAC1C,MAAM,QAAQ,MAAM,KAAK,QAAQ,QAAQ,OAAO,MAAM,OAAO,MAAM,WAAW,MAAM,QAAQ;AAC5F,UAAO;IAAE,OAAO,MAAM;IAAO,QAAQ,MAAM,MAAM;IAAQ;;EAE5D,CAAC;;;;;;;AAQJ,SAAgB,uBACd,MAC6C;AAC7C,QAAO,KAA4C;EACjD,MAAM;EACN,aACE;EACF,aAAa;EACb,cAAc;EACd,iBAAiB;EACjB,eAAe;EACf,aAAa;EACb,iBAAiB;EACjB,MAAM,CAAC,UAAU,UAAU;EAC3B,MAAM,QAAQ,OAAO,KAAK;GACxB,MAAM,QAAQ,MAAM,KAAK,aAAa,IAAI;GAC1C,MAAM,QAAQ,MAAM,KAAK,QAAQ,QAAQ,OAAO,MAAM,aAAa,MAAM,SAAS;AAClF,UAAO;IAAE,OAAO,MAAM;IAAO,QAAQ,MAAM,MAAM;IAAQ;;EAE5D,CAAC"}

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

@@ -12,16 +12,16 @@ declare const factRememberInputSchema: z.ZodObject<{
   validTo: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
   text: string;
-  sensitivity?: "public" | "internal" | "secret" | undefined;
   tags?: string[] | undefined;
   confidence?: number | undefined;
+  sensitivity?: "public" | "internal" | "secret" | undefined;
   validFrom?: string | undefined;
   validTo?: string | undefined;
 }, {
   text: string;
-  sensitivity?: "public" | "internal" | "secret" | undefined;
   tags?: string[] | undefined;
   confidence?: number | undefined;
+  sensitivity?: "public" | "internal" | "secret" | undefined;
   validFrom?: string | undefined;
   validTo?: string | undefined;
 }>;
@@ -54,13 +54,13 @@ declare const factSearchInputSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
   query: string;
   topK?: number | undefined;
-  asOf?: string | undefined;
   tags?: string[] | undefined;
+  asOf?: string | undefined;
 }, {
   query: string;
   topK?: number | undefined;
-  asOf?: string | undefined;
   tags?: string[] | undefined;
+  asOf?: string | undefined;
 }>;
 declare const factSearchOutputSchema: z.ZodObject<{
   hits: z.ZodArray<z.ZodObject<{
@@ -69,34 +69,50 @@ declare const factSearchOutputSchema: z.ZodObject<{
     score: z.ZodNumber;
     sensitivity: z.ZodEnum<["public", "internal", "secret"]>;
     provenance: z.ZodOptional<z.ZodEnum<["user", "tool", "extraction", "reflection", "induction", "imported"]>>;
+    /**
+     * 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.ZodOptional<z.ZodString>;
+    /** Id of the fact that superseded this one, when any. */
+    supersededBy: z.ZodOptional<z.ZodString>;
   }, "strip", z.ZodTypeAny, {
-    score: number;
-    factId: string;
     text: string;
+    score: number;
     sensitivity: "public" | "internal" | "secret";
+    factId: string;
+    validTo?: string | undefined;
     provenance?: "user" | "tool" | "extraction" | "reflection" | "induction" | "imported" | undefined;
+    supersededBy?: string | undefined;
   }, {
-    score: number;
-    factId: string;
     text: string;
+    score: number;
     sensitivity: "public" | "internal" | "secret";
+    factId: string;
+    validTo?: string | undefined;
     provenance?: "user" | "tool" | "extraction" | "reflection" | "induction" | "imported" | undefined;
+    supersededBy?: string | undefined;
   }>, "many">;
 }, "strip", z.ZodTypeAny, {
   hits: {
-    score: number;
-    factId: string;
     text: string;
+    score: number;
     sensitivity: "public" | "internal" | "secret";
+    factId: string;
+    validTo?: string | undefined;
     provenance?: "user" | "tool" | "extraction" | "reflection" | "induction" | "imported" | undefined;
+    supersededBy?: string | undefined;
   }[];
 }, {
   hits: {
-    score: number;
-    factId: string;
     text: string;
+    score: number;
     sensitivity: "public" | "internal" | "secret";
+    factId: string;
+    validTo?: string | undefined;
     provenance?: "user" | "tool" | "extraction" | "reflection" | "induction" | "imported" | undefined;
+    supersededBy?: string | undefined;
   }[];
 }>;
 type FactSearchInput = z.infer<typeof factSearchInputSchema>;
@@ -165,41 +181,41 @@ declare const factHistoryOutputSchema: z.ZodObject<{
     supersededBy: z.ZodOptional<z.ZodString>;
     sensitivity: z.ZodEnum<["public", "internal", "secret"]>;
   }, "strip", z.ZodTypeAny, {
-    factId: string;
     text: string;
     sensitivity: "public" | "internal" | "secret";
+    factId: string;
     validFrom?: string | undefined;
     validTo?: string | undefined;
-    supersedes?: string | undefined;
     supersededBy?: string | undefined;
+    supersedes?: string | undefined;
   }, {
-    factId: string;
     text: string;
     sensitivity: "public" | "internal" | "secret";
+    factId: string;
     validFrom?: string | undefined;
     validTo?: string | undefined;
-    supersedes?: string | undefined;
     supersededBy?: string | undefined;
+    supersedes?: string | undefined;
   }>, "many">;
 }, "strip", z.ZodTypeAny, {
   chain: {
-    factId: string;
     text: string;
     sensitivity: "public" | "internal" | "secret";
+    factId: string;
     validFrom?: string | undefined;
     validTo?: string | undefined;
-    supersedes?: string | undefined;
     supersededBy?: string | undefined;
+    supersedes?: string | undefined;
   }[];
 }, {
   chain: {
-    factId: string;
     text: string;
     sensitivity: "public" | "internal" | "secret";
+    factId: string;
     validFrom?: string | undefined;
     validTo?: string | undefined;
-    supersedes?: string | undefined;
     supersededBy?: string | undefined;
+    supersedes?: string | undefined;
   }[];
 }>;
 type FactHistoryInput = z.infer<typeof factHistoryInputSchema>;
@@ -227,7 +243,7 @@ declare const factValidateOutputSchema: z.ZodObject<{
 type FactValidateInput = z.infer<typeof factValidateInputSchema>;
 type FactValidateOutput = z.infer<typeof factValidateOutputSchema>;
 /**
- * `fact_remember` — persist a single semantic fact. The minimum-viable
+ * `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.
  *
@@ -235,29 +251,30 @@ type FactValidateOutput = z.infer<typeof factValidateOutputSchema>;
  */
 declare function createFactRememberTool(deps: MemoryToolDeps): Tool<FactRememberInput, FactRememberOutput>;
 /**
- * `fact_search` — hybrid (vector + FTS5) search over the user's
+ * `fact_search` - hybrid (vector + FTS5) search over the user's
  * semantic memory. Results merged through the configured reranker.
  *
  * @stable
  */
 declare function createFactSearchTool(deps: MemoryToolDeps): Tool<FactSearchInput, FactSearchOutput>;
 /**
- * `fact_supersede` — soft-supersede an old fact by storing a new one
- * that replaces it. The old fact is kept for replay but ranked below
- * the new one.
+ * `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
  */
 declare function createFactSupersedeTool(deps: MemoryToolDeps): Tool<FactSupersedeInput, FactSupersedeOutput>;
 /**
- * `fact_forget` — soft-delete a fact (kept for replay; never hard-
+ * `fact_forget` - soft-delete a fact (kept for replay; never hard-
  * deleted at this layer).
  *
  * @stable
  */
 declare function createFactForgetTool(deps: MemoryToolDeps): Tool<FactForgetInput, FactForgetOutput>;
 /**
- * `fact_history` — trace how a fact changed over time. Returns the
+ * `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.
@@ -266,20 +283,20 @@ declare function createFactForgetTool(deps: MemoryToolDeps): Tool<FactForgetInpu
  */
 declare function createFactHistoryTool(deps: MemoryToolDeps): Tool<FactHistoryInput, FactHistoryOutput>;
 /**
- * `fact_validate` — promote a quarantined fact to active (P1-4). The
+ * `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
+ * 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
+ * 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
+ *    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.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"fact-tools.d.ts","names":[],"sources":["../../src/tools/fact-tools.ts"],"sourcesContent":[],"mappings":";;;;;cAeM,yBAAuB,CAAA,CAAA;;EAAvB,IAAA,eAAA,WAOJ,YAAA,EAAA,MAAA,CAAA,CAAA;;;;;;;;;;;;;;EAP2B,WAAA,CAAA,EAAA,QAAA,GAAA,UAAA,GAAA,QAAA,GAAA,SAAA;EAAA,IAAA,CAAA,EAAA,MAAA,EAAA,GAAA,SAAA;EAQvB,UAAA,CAAA,EAAA,MAAA,GAAA,SAUJ;;;;cAVI,0BAAwB,CAAA,CAAA;;EAAA;;AAAA;AAYE;AACC;;;;;;;;;;EAEN,WAAA,EAAA,OAAA;EAAA,gBAAA,CAAA,EAAA,WAAA,GAAA,aAAA,GAAA,SAAA;AAAA,CAAA,CAAA;KAHtB,iBAAA,GAAoB,CAAA,CAAE,aAAa;KACnC,kBAAA,GAAqB,CAAA,CAAE,aAAa;cAEnC,uBAAqB,CAAA,CAAA;;;;;;;;EAMC,IAAA,CAAA,EAAA,MAAA,GAAA,SAAA;EAAA,IAAA,CAAA,EAAA,MAAA,EAAA,GAAA,SAAA;AAAA,CAAA,EAAA;EAavB,KAAA,EAAA,MAAA;EAEC,IAAA,CAAA,EAAA,MAAA,GAAA,SAAA;;;;cAfA,wBAAsB,CAAA,CAAA;;IAeE,MAAA,aAAA;IAAA,IAAA,aAAA;IAKxB,KAAA,aAAA;;;;IAAyB,KAAA,EAAA,MAAA;IAAA,MAAA,EAAA,MAAA;IAK1B,IAAA,EAAA,MAAA;IACA,WAAA,EAAA,QAAmB,GAAA,UAAkB,GAAA,QAAA;IAEpC,UAAA,CAAA,EAAA,MAAA,GAGJ,MAAA,GAAA,YAAA,GAAA,YAAA,GAAA,WAAA,GAAA,UAAA,GAAA,SAAA;;;;;IAHyB,WAAA,EAAA,QAAA,GAAA,UAAA,GAAA,QAAA;IAAA,UAAA,CAAA,EAAA,MAAA,GAAA,MAAA,GAAA,YAAA,GAAA,YAAA,GAAA,WAAA,GAAA,UAAA,GAAA,SAAA;EAIrB,CAAA,CAAA,EAAA,MAAA,CAAA;;;;IAAsB,MAAA,EAAA,MAAA;IAAA,IAAA,EAAA,MAAA;IAKvB,WAAA,EAAA,QAAe,GAAA,UAAkB,GAAA,QAAA;IACjC,UAAA,CAAA,EAAA,MAAgB,GAAA,MAAkB,GAAA,YAAA,GAAA,YAAb,GAAK,WAAA,GAAA,UAAA,GAAA,SAAA;EAEzB,CAAA,EAAA;;;IAAsB,KAAA,EAAA,MAAA;IAAA,MAAA,EAAA,MAAA;IAGtB,IAAA,EAAA,MAAA;;;;;KA/BD,eAAA,GAAkB,CAAA,CAAE,aAAa;KACjC,gBAAA,GAAmB,CAAA,CAAE,aAAa;cAEjC,0BAAwB,CAAA,CAAA;;;;;;;;;EA4BD,OAAA,EAAA,MAAA;EAAA,KAAA,EAAA,MAAA;EAcxB,MAAA,CAAA,EAAA,MAAA,GAAA,SAAgB;AAAU,CAAA,CAAA;AACC,cAtC1B,yBA2CJ,EA3C6B,CAAA,CAAA,SA2C7B,CAAA;;;;;EAH2B,KAAA,EAAA,MAAA;CAAA,EAAA;EAIvB,KAAA,EAAA,MAAA;;;KAvCD,kBAAA,GAAqB,CAAA,CAAE,aAAa;KACpC,mBAAA,GAAsB,CAAA,CAAE,KAsCC,CAAA,OAtCY,yBAsCZ,CAAA;cApCxB,qBAoCwB,EApCH,CAAA,CAAA,SAoCG,CAAA;EAKzB,MAAA,aAAA;EACA,MAAA,eAAkB,YAAA,CAAkB;AASzC,CAAA,EAAA,OAAgB,cAAA,EAAA;EACR,MAAA,EAAA,MAAA;EACA,MAAA,CAAA,EAAA,MAAA,GAAA,SAAA;CAAmB,EAAA;EAAxB,MAAA,EAAA,MAAA;EAAI,MAAA,CAAA,EAAA,MAAA,GAAA,SAAA;AAyCP,CAAA,CAAA;cA1FM,sBA2FE,EA3FoB,CAAA,CAAA,SA2FpB,CAAA;EACA,MAAA,aAAA;EAAiB,SAAA,cAAA;CAAtB,EAAA,OAAA,cAAA,EAAA;EAAI,MAAA,EAAA,MAAA;EA0CS,SAAA,EAAA,OAAA;CACR,EAAA;EACA,MAAA,EAAA,MAAA;EAAoB,SAAA,EAAA,OAAA;CAAzB,CAAA;KAnIE,eAAA,GAAkB,CAAA,CAAE,KAmIlB,CAAA,OAnI+B,qBAmI/B,CAAA;AA+BP,KAjKK,gBAAA,GAAmB,CAAA,CAAE,KAiKU,CAAA,OAjKG,sBAiKH,CAAA;cA/J9B,sBAgKE,EAhKoB,CAAA,CAAA,SAgKpB,CAAA;EACA,MAAA,aAAA;CAAiB,EAAA,OAAA,cAAA,EAAA;EAAtB,MAAA,EAAA,MAAA;CAAI,EAAA;EA4BS,MAAA,EAAA,MAAA;CACR,CAAA;cA3LF,uBA4LE,EA5LqB,CAAA,CAAA,SA4LrB,CAAA;EAAkB,KAAA,YAAA,YAAA,CAAA;IAAvB,MAAA,aAAA;IAAI,IAAA,aAAA;IAqDS,SAAA,eAAsB,YAAA,CAAA;IAC9B,OAAA,eAAA,YAAA,CAAA;IACA,UAAA,eAAA,YAAA,CAAA;IAAmB,YAAA,eAAA,YAAA,CAAA;IAAxB,WAAA,WAAA,CAAA,CAAA,QAAA,EAAA,UAAA,EAAA,QAAA,CAAA,CAAA;EAAI,CAAA,EAAA,OAAA,cAAA,EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KArOF,gBAAA,GAAmB,CAAA,CAAE,aAAa;KAClC,iBAAA,GAAoB,CAAA,CAAE,aAAa;cAElC,yBAAuB,CAAA,CAAA;;;;;;;;;;cAIvB,0BAAwB,CAAA,CAAA;;;;;;;;;;KAKzB,iBAAA,GAAoB,CAAA,CAAE,aAAa;KACnC,kBAAA,GAAqB,CAAA,CAAE,aAAa;;;;;;;;iBASzB,sBAAA,OACR,iBACL,KAAK,mBAAmB;;;;;;;iBAyCX,oBAAA,OACR,iBACL,KAAK,iBAAiB;;;;;;;;iBA0CT,uBAAA,OACR,iBACL,KAAK,oBAAoB;;;;;;;iBA+BZ,oBAAA,OACR,iBACL,KAAK,iBAAiB;;;;;;;;;iBA4BT,qBAAA,OACR,iBACL,KAAK,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;iBAqDV,sBAAA,OACR,iBACL,KAAK,mBAAmB"}
+{"version":3,"file":"fact-tools.d.ts","names":[],"sources":["../../src/tools/fact-tools.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/tools/fact-tools.js

@@ -1,3 +1,4 @@
+import { recallTaint } from "./taint.js";
 import { tool } from "@graphorin/tools";
 import { z } from "zod";
 
@@ -39,7 +40,9 @@ const factSearchOutputSchema = z.object({ hits: z.array(z.object({
 	text: z.string(),
 	score: z.number(),
 	sensitivity: sensitivityEnum,
-	provenance: provenanceEnum.optional()
+	provenance: provenanceEnum.optional(),
+	validTo: z.string().optional(),
+	supersededBy: z.string().optional()
 })) });
 const factSupersedeInputSchema = z.object({
 	oldId: z.string().min(1),
@@ -77,7 +80,7 @@ const factValidateOutputSchema = z.object({
 	validated: z.boolean()
 });
 /**
-* `fact_remember` — persist a single semantic fact. The minimum-viable
+* `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.
 *
@@ -113,7 +116,7 @@ function createFactRememberTool(deps) {
 	});
 }
 /**
-* `fact_search` — hybrid (vector + FTS5) search over the user's
+* `fact_search` - hybrid (vector + FTS5) search over the user's
 * semantic memory. Results merged through the configured reranker.
 *
 * @stable
@@ -121,7 +124,7 @@ function createFactRememberTool(deps) {
 function createFactSearchTool(deps) {
 	return tool({
 		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.",
+		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",
@@ -131,32 +134,41 @@ function createFactSearchTool(deps) {
 		tags: ["memory", "semantic"],
 		async execute(input, ctx) {
 			const scope = await deps.resolveScope(ctx);
-			return { hits: (await deps.semantic.search(scope, input.query, {
+			const hits = await deps.semantic.search(scope, input.query, {
 				...input.topK !== void 0 ? { topK: input.topK } : {},
 				...input.tags !== void 0 && input.tags.length > 0 ? { tags: input.tags } : {},
 				...input.asOf !== void 0 ? { asOf: input.asOf } : {},
 				signal: ctx.signal
-			})).map((hit) => ({
+			});
+			const output = { hits: hits.map((hit) => ({
 				factId: hit.record.id,
 				text: hit.record.text,
 				score: hit.score,
 				sensitivity: hit.record.sensitivity,
-				...hit.record.provenance !== void 0 ? { provenance: hit.record.provenance } : {}
+				...hit.record.provenance !== void 0 ? { provenance: hit.record.provenance } : {},
+				...hit.record.validTo !== void 0 ? { validTo: hit.record.validTo } : {},
+				...hit.record.supersededBy !== void 0 ? { supersededBy: hit.record.supersededBy } : {}
 			})) };
+			const taint = recallTaint(hits.map((h) => h.record));
+			return taint === void 0 ? output : {
+				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 ranked below
-* the new one.
+* `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
 */
 function createFactSupersedeTool(deps) {
 	return tool({
 		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.",
+		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",
@@ -175,7 +187,7 @@ function createFactSupersedeTool(deps) {
 	});
 }
 /**
-* `fact_forget` — soft-delete a fact (kept for replay; never hard-
+* `fact_forget` - soft-delete a fact (kept for replay; never hard-
 * deleted at this layer).
 *
 * @stable
@@ -202,7 +214,7 @@ function createFactForgetTool(deps) {
 	});
 }
 /**
-* `fact_history` — trace how a fact changed over time. Returns the
+* `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.
@@ -239,20 +251,20 @@ function createFactHistoryTool(deps) {
 	});
 }
 /**
-* `fact_validate` — promote a quarantined fact to active (P1-4). The
+* `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
+* 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
+* 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
+*    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.
 *
@@ -264,7 +276,7 @@ function createFactHistoryTool(deps) {
 function createFactValidateTool(deps) {
 	return tool({
 		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.",
+		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,
 		needsApproval: true,