@graphorin/memory 0.6.0 → 0.7.0

package/src/tiers/session-memory.ts

@@ -0,0 +1,271 @@
+import type {
+  AgentRegistryEntry,
+  MemoryHit,
+  Message,
+  MessageRef,
+  SessionListOptions,
+  SessionMessageWithMetadata,
+  SessionScope,
+  Tracer,
+} from '@graphorin/core';
+import { newMemoryId } from '../internal/id.js';
+import { withMemorySpan } from '../internal/spans.js';
+import type { MemoryStoreAdapter } from '../internal/storage-adapter.js';
+
+/**
+ * Per-session compaction policy. The default `0.9` matches DEC-104:
+ * compaction kicks in once cached message tokens exceed
+ * `0.9 * contextWindow`.
+ *
+ * @stable
+ */
+export interface SessionCompactionPolicy {
+  /** Default `0.9`. */
+  readonly compactAtRatio?: number;
+  /** Default `8192`. */
+  readonly contextWindowTokens?: number;
+}
+
+/**
+ * Snapshot returned by {@link SessionMemory.compact}. The
+ * minimum-viable rendering simply reports counts; the full
+ * LLM-summarized cutoff (Phase 10c Consolidator) replaces this
+ * implementation later.
+ *
+ * @stable
+ */
+export interface SessionCompactionResult {
+  readonly removed: number;
+  readonly summarized: number;
+  readonly summary?: string;
+}
+
+/**
+ * `SessionMemory` - append-only message log per session. Owns the
+ * `session_messages` storage by single-source-of-truth (DEC-147); the
+ * `@graphorin/sessions` package wraps this surface in Phase 11.
+ *
+ * @stable
+ */
+export class SessionMemory {
+  readonly #store: MemoryStoreAdapter;
+  readonly #tracer: Tracer;
+  readonly #compactionPolicy: SessionCompactionPolicy;
+
+  constructor(args: {
+    store: MemoryStoreAdapter;
+    tracer: Tracer;
+    compactionPolicy?: SessionCompactionPolicy;
+  }) {
+    this.#store = args.store;
+    this.#tracer = args.tracer;
+    this.#compactionPolicy = args.compactionPolicy ?? {};
+  }
+
+  /** Persist a message. Returns the storage reference. */
+  async push(scope: SessionScope, message: Message): Promise<MessageRef> {
+    return withMemorySpan(
+      this.#tracer,
+      'memory.write.session',
+      scope,
+      {
+        'memory.session.message_role': message.role,
+        ...(message.role === 'assistant' && message.agentId !== undefined
+          ? { 'memory.session.agent_id': message.agentId }
+          : {}),
+      },
+      async (span) => {
+        const ref = await this.#store.session.push(scope, message);
+        span.setAttributes({
+          'memory.session.sequence': ref.sequence,
+          'memory.session.message_id': ref.messageId,
+        });
+        return ref;
+      },
+    );
+  }
+
+  /** List messages for the supplied scope. */
+  async list(scope: SessionScope, opts: SessionListOptions = {}): Promise<ReadonlyArray<Message>> {
+    return withMemorySpan(
+      this.#tracer,
+      'memory.read.session',
+      scope,
+      {
+        ...(opts.lastN !== undefined ? { 'memory.session.last_n': opts.lastN } : {}),
+        ...(opts.agentId !== undefined ? { 'memory.session.agent_id': opts.agentId } : {}),
+        ...(opts.role !== undefined ? { 'memory.session.role': opts.role } : {}),
+      },
+      async (span) => {
+        const out = await this.#store.session.list(scope, opts);
+        span.setAttributes({ 'memory.read.session.count': out.length });
+        return out;
+      },
+    );
+  }
+
+  /**
+   * RP-5: list messages with their persisted identity (stored id / sequence /
+   * `createdAt`) so an exporter preserves message identity + chronology.
+   * Delegates to the store when it supports the richer read.
+   */
+  async listWithMetadata(
+    scope: SessionScope,
+    opts: SessionListOptions = {},
+  ): Promise<ReadonlyArray<SessionMessageWithMetadata>> {
+    const store = this.#store.session;
+    if (store.listWithMetadata !== undefined) {
+      return store.listWithMetadata(scope, opts);
+    }
+    // A store without the richer read: fabricate a unique id + the current time
+    // (the pre-RP-5 behaviour, just centralised here).
+    const messages = await store.list(scope, opts);
+    return messages.map((message, i) => ({
+      message,
+      messageId: newMemoryId('msg'),
+      sequence: i + 1,
+      createdAt: new Date().toISOString(),
+    }));
+  }
+
+  /** Hybrid (FTS5) search over the session messages. */
+  async search(
+    scope: SessionScope,
+    query: string,
+    opts: { topK?: number; signal?: AbortSignal } = {},
+  ): Promise<ReadonlyArray<MemoryHit>> {
+    return withMemorySpan(
+      this.#tracer,
+      'memory.search.session',
+      scope,
+      { 'memory.search.query_length': query.length },
+      async (span) => {
+        const out = await this.#store.session.search(scope, query, {
+          query,
+          ...(opts.topK !== undefined ? { topK: opts.topK } : {}),
+          ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
+        });
+        span.setAttributes({ 'memory.search.session.count': out.length });
+        return out;
+      },
+    );
+  }
+
+  /**
+   * NOT IMPLEMENTED (MRET-12) - always resolves `{ flushed: 0 }` and
+   * performs no work. The consolidator pipeline (extraction → facts /
+   * episodes) superseded the planned "silent flush turn"; this method
+   * remains only for contract stability. Do not branch on its counter.
+   */
+  async flushImportant(
+    scope: SessionScope,
+    opts: { silent?: boolean } = {},
+  ): Promise<{ flushed: number }> {
+    void opts;
+    return withMemorySpan(
+      this.#tracer,
+      'memory.write.session',
+      scope,
+      { 'memory.session.action': 'flush-important', 'memory.session.implemented': false },
+      async () => ({ flushed: 0 }),
+    );
+  }
+
+  /**
+   * NOT IMPLEMENTED (MRET-12) - always resolves
+   * `{ removed: 0, summarized: 0 }` and deletes / summarizes nothing.
+   * Session-context compaction is owned by the context engine
+   * (`memory.contextEngine.compactNow`, driven by the agent runtime);
+   * this tier-level method previously FABRICATED counts (it reported
+   * `total - keepLastN` as "removed" while removing nothing - with the
+   * default `keepLastN: 0` it claimed to have compacted the whole
+   * session). It now reports the truth until a real message splice
+   * exists at this layer.
+   */
+  async compact(
+    scope: SessionScope,
+    opts: { keepLastN?: number } = {},
+  ): Promise<SessionCompactionResult> {
+    void opts;
+    return withMemorySpan(
+      this.#tracer,
+      'memory.write.session',
+      scope,
+      { 'memory.session.action': 'compact', 'memory.session.implemented': false },
+      async (span) => {
+        span.setAttributes({
+          'memory.session.compact.removed': 0,
+          'memory.session.compact.summarized': 0,
+        });
+        return { removed: 0, summarized: 0 };
+      },
+    );
+  }
+
+  /**
+   * Returns `true` when the cached message tokens exceed
+   * `compactAtRatio * contextWindow` (default `0.9` per DEC-104). The
+   * second argument can be either:
+   *
+   *  - a `number` - interpreted as the live `contextWindow` size in
+   *    tokens (matches the documented memory-system spec signature);
+   *  - an options bag - `{ usedTokens?, contextWindow? }`. When
+   *    `usedTokens` is supplied the call is purely arithmetic; when
+   *    omitted, the storage adapter's per-message `token_count`
+   *    cache (DEC-131) is consulted via `totalCachedTokens(scope)`,
+   *    falling back to a heuristic (~4 chars/token) for cache
+   *    misses.
+   *
+   * @stable
+   */
+  async shouldCompact(
+    scope: SessionScope,
+    contextWindowOrOptions: number | { usedTokens?: number; contextWindow?: number } = {},
+  ): Promise<boolean> {
+    const options =
+      typeof contextWindowOrOptions === 'number'
+        ? { contextWindow: contextWindowOrOptions }
+        : contextWindowOrOptions;
+    const ratio = this.#compactionPolicy.compactAtRatio ?? 0.9;
+    const window = options.contextWindow ?? this.#compactionPolicy.contextWindowTokens ?? 8192;
+    if (options.usedTokens !== undefined) {
+      return options.usedTokens / window > ratio;
+    }
+    if (typeof this.#store.session.totalCachedTokens === 'function') {
+      const cached = await this.#store.session.totalCachedTokens(scope);
+      if (cached !== null) {
+        return cached / window > ratio;
+      }
+    }
+    const messages = await this.#store.session.list(scope, {});
+    let used = 0;
+    for (const m of messages) used += approximateTokenLength(m);
+    return used / window > ratio;
+  }
+
+  /**
+   * NOT IMPLEMENTED (MRET-12) - always resolves `[]`. The agent
+   * registry lives in `@graphorin/sessions` and has never been
+   * threaded into this tier; the previous JSDoc claimed the default
+   * sqlite adapter "resolves" registry rows here, which was false. Use
+   * the sessions facade for participant attribution.
+   */
+  async attributedFor(scope: SessionScope): Promise<ReadonlyArray<AgentRegistryEntry>> {
+    void scope;
+    return [];
+  }
+}
+
+function approximateTokenLength(message: Message): number {
+  if (message.role === 'system') {
+    return Math.ceil(message.content.length / 4);
+  }
+  if (typeof message.content === 'string') return Math.ceil(message.content.length / 4);
+  let total = 0;
+  for (const part of message.content) {
+    if (part.type === 'text' || part.type === 'reasoning') {
+      total += Math.ceil(part.text.length / 4);
+    }
+  }
+  return total;
+}

package/src/tiers/shared-memory.ts

@@ -0,0 +1,62 @@
+import type { MemoryRecord, Tracer } from '@graphorin/core';
+import { withMemorySpan } from '../internal/spans.js';
+import type { MemoryStoreAdapter } from '../internal/storage-adapter.js';
+
+/**
+ * `SharedMemory` - many-to-many attach mode for blocks / facts /
+ * rules across multiple agents. Storage adapters represent
+ * attachments as a join table (`shared_attachments` in
+ * `@graphorin/store-sqlite`).
+ *
+ * @stable
+ */
+export class SharedMemory {
+  readonly #store: MemoryStoreAdapter;
+  readonly #tracer: Tracer;
+
+  constructor(args: { store: MemoryStoreAdapter; tracer: Tracer }) {
+    this.#store = args.store;
+    this.#tracer = args.tracer;
+  }
+
+  /** Attach `recordId` to `agentId`. Idempotent. */
+  async attach(recordId: string, agentId: string, userId: string): Promise<void> {
+    await withMemorySpan(
+      this.#tracer,
+      'memory.write.shared',
+      { userId, agentId },
+      { 'memory.shared.action': 'attach', 'memory.shared.record_id': recordId },
+      async () => {
+        await this.#store.shared.attach(recordId, agentId);
+      },
+    );
+  }
+
+  /** Detach `recordId` from `agentId`. Idempotent. */
+  async detach(recordId: string, agentId: string, userId: string): Promise<void> {
+    await withMemorySpan(
+      this.#tracer,
+      'memory.write.shared',
+      { userId, agentId },
+      { 'memory.shared.action': 'detach', 'memory.shared.record_id': recordId },
+      async () => {
+        await this.#store.shared.detach(recordId, agentId);
+      },
+    );
+  }
+
+  /** List every attachment for `agentId`. */
+  async listFor(agentId: string, userId: string): Promise<ReadonlyArray<MemoryRecord>> {
+    return withMemorySpan(
+      this.#tracer,
+      'memory.read.shared',
+      { userId, agentId },
+      {},
+      async (span) => {
+        const out = await this.#store.shared.listFor(agentId);
+        span.setAttributes({ 'memory.read.shared.count': out.length });
+        return out;
+      },
+    );
+  }
+}

package/src/tiers/working-memory.ts

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