@graphorin/memory 0.5.0

package/dist/internal/contextualize.d.ts

@@ -0,0 +1,14 @@
+import { Provider } from "@graphorin/core";
+
+//#region src/internal/contextualize.d.ts
+
+/**
+ * Contextual-retrieval mode. `'late-chunk'` is the offline default;
+ * `'llm'` is the opt-in, consolidator-only enrichment. P1-3.
+ *
+ * @stable
+ */
+type ContextualRetrievalMode = 'off' | 'late-chunk' | 'llm';
+//#endregion
+export { ContextualRetrievalMode };
+//# sourceMappingURL=contextualize.d.ts.map

package/dist/internal/contextualize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextualize.d.ts","names":[],"sources":["../../src/internal/contextualize.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;KA8BY,uBAAA"}

package/dist/internal/contextualize.js

@@ -0,0 +1,110 @@
+//#region src/internal/contextualize.ts
+const SITUATING_CONTEXT_SYSTEM_PROMPT = [
+	"You are a situating-context assistant for a long-running memory store.",
+	"Given one memory and any structured hints, write a single short sentence (≤ 25 words) that situates it — the entities, timeframe, and topic it concerns — so it can be retrieved later by a vaguely-worded question.",
+	"Do not restate the memory verbatim and do not add facts that are not implied. Return only the sentence, no preamble."
+].join(" ");
+/**
+* Build the deterministic situating-context prefix from a candidate's
+* structured signals. Returns `''` when nothing useful is available so
+* the caller can short-circuit to the canonical text.
+*
+* @internal
+*/
+function buildSituatingContext(input) {
+	const parts = [];
+	const subject = trimToUndefined(input.subject);
+	const predicate = trimToUndefined(input.predicate);
+	const object = trimToUndefined(input.object);
+	if (subject !== void 0 && predicate !== void 0 && object !== void 0) parts.push(`${subject} ${predicate} ${object}`);
+	else {
+		if (subject !== void 0) parts.push(subject);
+		if (object !== void 0) parts.push(object);
+	}
+	const validFrom = trimToUndefined(input.validFrom);
+	if (validFrom !== void 0) parts.push(`as of ${validFrom.length >= 10 ? validFrom.slice(0, 10) : validFrom}`);
+	const tags = (input.tags ?? []).map((t) => t.trim()).filter((t) => t.length > 0);
+	if (tags.length > 0) parts.push(`topics: ${tags.join(", ")}`);
+	if (parts.length === 0) return "";
+	return `[Context: ${parts.join("; ")}]`;
+}
+/**
+* Late-chunking contextualizer (offline default). Prepends the
+* deterministic situating context to the canonical text; a no-op when
+* the candidate carries no structured signals. Pure — never calls a
+* provider.
+*
+* @internal
+*/
+function contextualize(input) {
+	const ctx = buildSituatingContext(input);
+	return ctx === "" ? input.text : `${ctx}\n${input.text}`;
+}
+const ZERO_USAGE = Object.freeze({
+	promptTokens: 0,
+	completionTokens: 0,
+	totalTokens: 0
+});
+/**
+* LLM-context contextualizer (opt-in, consolidator-only). Spends one
+* cheap provider call to write a situating prefix, then prepends it to
+* the canonical text. Resilient by design: an empty completion or a
+* provider error degrades to {@link contextualize} (deterministic
+* late-chunk) so the enrichment can never wedge a write. Returns the
+* usage so the caller can record it against the budget.
+*
+* @internal
+*/
+async function contextualizeWithLlm(input, provider, opts = {}) {
+	const request = {
+		messages: [{
+			role: "user",
+			content: buildSituatingUserPrompt(input)
+		}],
+		systemMessage: SITUATING_CONTEXT_SYSTEM_PROMPT,
+		temperature: 0,
+		maxTokens: 256,
+		...opts.signal !== void 0 ? { signal: opts.signal } : {}
+	};
+	try {
+		const response = await provider.generate(request);
+		const prefix = (response.text ?? "").trim();
+		if (prefix.length === 0) return {
+			indexText: contextualize(input),
+			usage: response.usage
+		};
+		return {
+			indexText: `${prefix}\n${input.text}`,
+			usage: response.usage
+		};
+	} catch {
+		return {
+			indexText: contextualize(input),
+			usage: ZERO_USAGE
+		};
+	}
+}
+function buildSituatingUserPrompt(input) {
+	const hints = [];
+	const subject = trimToUndefined(input.subject);
+	const predicate = trimToUndefined(input.predicate);
+	const object = trimToUndefined(input.object);
+	if (subject !== void 0) hints.push(`subject=${subject}`);
+	if (predicate !== void 0) hints.push(`predicate=${predicate}`);
+	if (object !== void 0) hints.push(`object=${object}`);
+	const tags = (input.tags ?? []).map((t) => t.trim()).filter((t) => t.length > 0);
+	if (tags.length > 0) hints.push(`tags=${tags.join(", ")}`);
+	const validFrom = trimToUndefined(input.validFrom);
+	if (validFrom !== void 0) hints.push(`validFrom=${validFrom}`);
+	const hintLine = hints.length > 0 ? `\nStructured hints: ${hints.join("; ")}` : "";
+	return `Memory: ${input.text}${hintLine}`;
+}
+function trimToUndefined(value) {
+	if (value === void 0) return void 0;
+	const trimmed = value.trim();
+	return trimmed.length === 0 ? void 0 : trimmed;
+}
+
+//#endregion
+export { contextualize, contextualizeWithLlm };
+//# sourceMappingURL=contextualize.js.map

package/dist/internal/contextualize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextualize.js","names":["parts: string[]","ZERO_USAGE: Usage","request: ProviderRequest","hints: string[]"],"sources":["../../src/internal/contextualize.ts"],"sourcesContent":["/**\n * Contextual retrieval (P1-3). Before a memory is embedded / FTS-indexed\n * the framework can prepend a short *situating context* (entities,\n * timeframe, topics) so a terse fact like \"moved there in March\" stays\n * findable by \"Where did Anna relocate?\". This mirrors Anthropic's\n * Contextual Retrieval, applied to both the vector embedding *and* the\n * lexical index, while the canonical `text` shown to the user / audit\n * trail is left untouched.\n *\n * Three modes:\n * - `'off'` — index the bare canonical text (pre-P1-3 behaviour).\n * - `'late-chunk'` — the **offline default**: prepend a context derived\n *   deterministically from the memory's own structured metadata. No LLM\n *   call, so the local-first write path is unchanged in cost.\n * - `'llm'` — an opt-in, **consolidator-only** enrichment: one cheap\n *   provider call writes a 1–2 sentence situating prefix. Confined to the\n *   background consolidator (never the hot write path); a failure or empty\n *   completion degrades to {@link contextualize} so a write never wedges.\n *\n * @packageDocumentation\n */\n\nimport type { Provider, ProviderRequest, Usage } from '@graphorin/core';\n\n/**\n * Contextual-retrieval mode. `'late-chunk'` is the offline default;\n * `'llm'` is the opt-in, consolidator-only enrichment. P1-3.\n *\n * @stable\n */\nexport type ContextualRetrievalMode = 'off' | 'late-chunk' | 'llm';\n\n/**\n * Structural subset of a fact / candidate consumed by the\n * contextualizers. Only **author / extraction-supplied** signals are\n * used — never framework-defaulted fields (e.g. a `validFrom` defaulted\n * to write-time) and never opaque scope ids (random uuids would only\n * add noise to the embedding). A candidate with no structured signals\n * yields an empty context, so plain `remember({ text })` writes are\n * left byte-identical.\n *\n * @internal\n */\nexport interface ContextualizeInput {\n  readonly text: string;\n  readonly subject?: string;\n  readonly predicate?: string;\n  readonly object?: string;\n  readonly tags?: ReadonlyArray<string>;\n  /** Author-set validity start (ISO-8601). Framework-defaulted values are *not* passed. */\n  readonly validFrom?: string;\n}\n\nconst SITUATING_CONTEXT_SYSTEM_PROMPT = [\n  'You are a situating-context assistant for a long-running memory store.',\n  'Given one memory and any structured hints, write a single short sentence (≤ 25 words) that situates it — the entities, timeframe, and topic it concerns — so it can be retrieved later by a vaguely-worded question.',\n  'Do not restate the memory verbatim and do not add facts that are not implied. Return only the sentence, no preamble.',\n].join(' ');\n\n/**\n * Build the deterministic situating-context prefix from a candidate's\n * structured signals. Returns `''` when nothing useful is available so\n * the caller can short-circuit to the canonical text.\n *\n * @internal\n */\nexport function buildSituatingContext(input: ContextualizeInput): string {\n  const parts: string[] = [];\n  const subject = trimToUndefined(input.subject);\n  const predicate = trimToUndefined(input.predicate);\n  const object = trimToUndefined(input.object);\n  if (subject !== undefined && predicate !== undefined && object !== undefined) {\n    parts.push(`${subject} ${predicate} ${object}`);\n  } else {\n    if (subject !== undefined) parts.push(subject);\n    if (object !== undefined) parts.push(object);\n  }\n  const validFrom = trimToUndefined(input.validFrom);\n  if (validFrom !== undefined) {\n    parts.push(`as of ${validFrom.length >= 10 ? validFrom.slice(0, 10) : validFrom}`);\n  }\n  const tags = (input.tags ?? []).map((t) => t.trim()).filter((t) => t.length > 0);\n  if (tags.length > 0) {\n    parts.push(`topics: ${tags.join(', ')}`);\n  }\n  if (parts.length === 0) return '';\n  return `[Context: ${parts.join('; ')}]`;\n}\n\n/**\n * Late-chunking contextualizer (offline default). Prepends the\n * deterministic situating context to the canonical text; a no-op when\n * the candidate carries no structured signals. Pure — never calls a\n * provider.\n *\n * @internal\n */\nexport function contextualize(input: ContextualizeInput): string {\n  const ctx = buildSituatingContext(input);\n  return ctx === '' ? input.text : `${ctx}\\n${input.text}`;\n}\n\nconst ZERO_USAGE: Usage = Object.freeze({\n  promptTokens: 0,\n  completionTokens: 0,\n  totalTokens: 0,\n});\n\n/** Result of the LLM-context enrichment — the index text plus call usage for budgeting. */\nexport interface ContextualizeLlmResult {\n  readonly indexText: string;\n  readonly usage: Usage;\n}\n\n/**\n * LLM-context contextualizer (opt-in, consolidator-only). Spends one\n * cheap provider call to write a situating prefix, then prepends it to\n * the canonical text. Resilient by design: an empty completion or a\n * provider error degrades to {@link contextualize} (deterministic\n * late-chunk) so the enrichment can never wedge a write. Returns the\n * usage so the caller can record it against the budget.\n *\n * @internal\n */\nexport async function contextualizeWithLlm(\n  input: ContextualizeInput,\n  provider: Provider,\n  opts: { readonly signal?: AbortSignal } = {},\n): Promise<ContextualizeLlmResult> {\n  const request: ProviderRequest = {\n    messages: [{ role: 'user', content: buildSituatingUserPrompt(input) }],\n    systemMessage: SITUATING_CONTEXT_SYSTEM_PROMPT,\n    temperature: 0,\n    // MCON-14: per-call output cap — a one-sentence situating prefix.\n    maxTokens: 256,\n    ...(opts.signal !== undefined ? { signal: opts.signal } : {}),\n  };\n  try {\n    const response = await provider.generate(request);\n    const prefix = (response.text ?? '').trim();\n    if (prefix.length === 0) {\n      return { indexText: contextualize(input), usage: response.usage };\n    }\n    return { indexText: `${prefix}\\n${input.text}`, usage: response.usage };\n  } catch {\n    // Contextualization is an enhancement, not a correctness requirement —\n    // a provider failure must never wedge the underlying write. Fall back\n    // to the deterministic late-chunk prefix at zero cost.\n    return { indexText: contextualize(input), usage: ZERO_USAGE };\n  }\n}\n\nfunction buildSituatingUserPrompt(input: ContextualizeInput): string {\n  const hints: string[] = [];\n  const subject = trimToUndefined(input.subject);\n  const predicate = trimToUndefined(input.predicate);\n  const object = trimToUndefined(input.object);\n  if (subject !== undefined) hints.push(`subject=${subject}`);\n  if (predicate !== undefined) hints.push(`predicate=${predicate}`);\n  if (object !== undefined) hints.push(`object=${object}`);\n  const tags = (input.tags ?? []).map((t) => t.trim()).filter((t) => t.length > 0);\n  if (tags.length > 0) hints.push(`tags=${tags.join(', ')}`);\n  const validFrom = trimToUndefined(input.validFrom);\n  if (validFrom !== undefined) hints.push(`validFrom=${validFrom}`);\n  const hintLine = hints.length > 0 ? `\\nStructured hints: ${hints.join('; ')}` : '';\n  return `Memory: ${input.text}${hintLine}`;\n}\n\nfunction trimToUndefined(value: string | undefined): string | undefined {\n  if (value === undefined) return undefined;\n  const trimmed = value.trim();\n  return trimmed.length === 0 ? undefined : trimmed;\n}\n"],"mappings":"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"}

package/dist/internal/embedder-binding.js

@@ -0,0 +1,50 @@
+//#region src/internal/embedder-binding.ts
+/**
+* Infer the canonical adapter family from the embedder id. The
+* canonical id format is `'<adapter>:<model>@<dim>'`; we slice the
+* adapter name off the front so the registry can index by family
+* without needing the embedder to expose an extra property.
+*
+* @internal
+*/
+function inferAdapterKind(id) {
+	const colonIndex = id.indexOf(":");
+	if (colonIndex < 0) return "custom";
+	return id.slice(0, colonIndex);
+}
+/**
+* Infer the model id portion of a canonical embedder id.
+*
+* @internal
+*/
+function inferModelName(id) {
+	const colonIndex = id.indexOf(":");
+	const atIndex = id.lastIndexOf("@");
+	if (colonIndex < 0) return id;
+	if (atIndex < 0 || atIndex < colonIndex) return id.slice(colonIndex + 1);
+	return id.slice(colonIndex + 1, atIndex);
+}
+/**
+* Register the supplied embedder with the storage layer's
+* `embedding_meta` registry. Returns the canonical id surfaced to the
+* memory writers. Idempotent — a registry that already knows the id
+* with a matching `configHash` returns the existing row.
+*
+* @internal
+*/
+function bindEmbedder(embedder, registry) {
+	const id = embedder.id();
+	registry.registerOrReturn({
+		id,
+		embedderKind: inferAdapterKind(id),
+		model: inferModelName(id),
+		dim: embedder.dim(),
+		configHash: embedder.configHash(),
+		distanceMetric: "cosine"
+	});
+	return id;
+}
+
+//#endregion
+export { bindEmbedder };
+//# sourceMappingURL=embedder-binding.js.map

package/dist/internal/embedder-binding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedder-binding.js","names":[],"sources":["../../src/internal/embedder-binding.ts"],"sourcesContent":["import type { EmbedderProvider } from '@graphorin/core';\nimport type { EmbeddingMetaRegistryLike } from './storage-adapter.js';\n\n/**\n * Infer the canonical adapter family from the embedder id. The\n * canonical id format is `'<adapter>:<model>@<dim>'`; we slice the\n * adapter name off the front so the registry can index by family\n * without needing the embedder to expose an extra property.\n *\n * @internal\n */\nexport function inferAdapterKind(id: string): string {\n  const colonIndex = id.indexOf(':');\n  if (colonIndex < 0) return 'custom';\n  return id.slice(0, colonIndex);\n}\n\n/**\n * Infer the model id portion of a canonical embedder id.\n *\n * @internal\n */\nexport function inferModelName(id: string): string {\n  const colonIndex = id.indexOf(':');\n  const atIndex = id.lastIndexOf('@');\n  if (colonIndex < 0) return id;\n  if (atIndex < 0 || atIndex < colonIndex) return id.slice(colonIndex + 1);\n  return id.slice(colonIndex + 1, atIndex);\n}\n\n/**\n * Register the supplied embedder with the storage layer's\n * `embedding_meta` registry. Returns the canonical id surfaced to the\n * memory writers. Idempotent — a registry that already knows the id\n * with a matching `configHash` returns the existing row.\n *\n * @internal\n */\nexport function bindEmbedder(\n  embedder: EmbedderProvider,\n  registry: EmbeddingMetaRegistryLike,\n): string {\n  const id = embedder.id();\n  registry.registerOrReturn({\n    id,\n    embedderKind: inferAdapterKind(id),\n    model: inferModelName(id),\n    dim: embedder.dim(),\n    configHash: embedder.configHash(),\n    distanceMetric: 'cosine',\n  });\n  return id;\n}\n"],"mappings":";;;;;;;;;AAWA,SAAgB,iBAAiB,IAAoB;CACnD,MAAM,aAAa,GAAG,QAAQ,IAAI;AAClC,KAAI,aAAa,EAAG,QAAO;AAC3B,QAAO,GAAG,MAAM,GAAG,WAAW;;;;;;;AAQhC,SAAgB,eAAe,IAAoB;CACjD,MAAM,aAAa,GAAG,QAAQ,IAAI;CAClC,MAAM,UAAU,GAAG,YAAY,IAAI;AACnC,KAAI,aAAa,EAAG,QAAO;AAC3B,KAAI,UAAU,KAAK,UAAU,WAAY,QAAO,GAAG,MAAM,aAAa,EAAE;AACxE,QAAO,GAAG,MAAM,aAAa,GAAG,QAAQ;;;;;;;;;;AAW1C,SAAgB,aACd,UACA,UACQ;CACR,MAAM,KAAK,SAAS,IAAI;AACxB,UAAS,iBAAiB;EACxB;EACA,cAAc,iBAAiB,GAAG;EAClC,OAAO,eAAe,GAAG;EACzB,KAAK,SAAS,KAAK;EACnB,YAAY,SAAS,YAAY;EACjC,gBAAgB;EACjB,CAAC;AACF,QAAO"}

package/dist/internal/id.js

@@ -0,0 +1,24 @@
+import { randomBytes } from "node:crypto";
+
+//#region src/internal/id.ts
+/**
+* Stable id generator. Combines `Date.now()` (millisecond resolution),
+* a per-process monotonic counter (resists collision inside the same
+* millisecond), and a 36-bit crypto-quality random suffix (ties the id
+* to the host so different runs do not collide either).
+*
+* The format is intentionally NOT a UUID — UUIDs are 16 bytes once
+* decoded; these ids are 18 chars on average which is what the
+* `audit.db` hash chain (Phase 03b) was sized for.
+*
+* @stable
+*/
+let counter = 0;
+function newMemoryId(prefix) {
+	counter = counter + 1 & 65535;
+	return `${prefix}_${Date.now().toString(36)}${counter.toString(36).padStart(3, "0")}${randomBytes(4).toString("hex")}`;
+}
+
+//#endregion
+export { newMemoryId };
+//# sourceMappingURL=id.js.map

package/dist/internal/id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"id.js","names":[],"sources":["../../src/internal/id.ts"],"sourcesContent":["/**\n * Stable id generator. Combines `Date.now()` (millisecond resolution),\n * a per-process monotonic counter (resists collision inside the same\n * millisecond), and a 36-bit crypto-quality random suffix (ties the id\n * to the host so different runs do not collide either).\n *\n * The format is intentionally NOT a UUID — UUIDs are 16 bytes once\n * decoded; these ids are 18 chars on average which is what the\n * `audit.db` hash chain (Phase 03b) was sized for.\n *\n * @stable\n */\nimport { randomBytes } from 'node:crypto';\n\nlet counter = 0;\n\nexport function newMemoryId(prefix: string): string {\n  counter = (counter + 1) & 0xffff;\n  const time = Date.now().toString(36);\n  const c = counter.toString(36).padStart(3, '0');\n  const rand = randomBytes(4).toString('hex');\n  return `${prefix}_${time}${c}${rand}`;\n}\n"],"mappings":";;;;;;;;;;;;;;;AAcA,IAAI,UAAU;AAEd,SAAgB,YAAY,QAAwB;AAClD,WAAW,UAAU,IAAK;AAI1B,QAAO,GAAG,OAAO,GAHJ,KAAK,KAAK,CAAC,SAAS,GAAG,GAC1B,QAAQ,SAAS,GAAG,CAAC,SAAS,GAAG,IAAI,GAClC,YAAY,EAAE,CAAC,SAAS,MAAM"}

package/dist/internal/injection-heuristics.js

@@ -0,0 +1,64 @@
+//#region src/internal/injection-heuristics.ts
+/**
+* Default English injection-marker rules. High-precision: each requires
+* injection-characteristic structure so benign facts do not trip them.
+*
+* @stable
+*/
+const DEFAULT_INJECTION_RULES = Object.freeze([
+	{
+		label: "ignore-previous-instructions",
+		pattern: /\bignore\s+(?:all\s+|any\s+)?(?:previous|prior|earlier|the\s+above|preceding)\s+(?:instructions?|prompts?|messages?|commands?|directions?|context|rules?)\b/i
+	},
+	{
+		label: "disregard-instructions",
+		pattern: /\bdisregard\s+(?:all\s+|any\s+|the\s+)?(?:previous|prior|earlier|above|preceding|prior\s+)?(?:instructions?|prompts?|rules?|guidelines?|guardrails?)\b/i
+	},
+	{
+		label: "override-directive",
+		pattern: /\boverride\s+(?:the\s+)?(?:system|safety|security|previous|prior|default)\b/i
+	},
+	{
+		label: "system-prompt-exfil",
+		pattern: /\b(?:reveal|show|print|repeat|leak|expose|dump)\b[^.?!\n]{0,40}\b(?:system\s+prompt|system\s+message|initial\s+instructions|hidden\s+(?:instructions|prompt))\b/i
+	},
+	{
+		label: "role-markup-injection",
+		pattern: /<\/?(?:system|im_start|im_end|tool_call|function_call)\b|\[\/?(?:INST|SYS)\]/i
+	},
+	{
+		label: "secrecy-directive",
+		pattern: /\b(?:do\s+not|don['’]?t|never)\s+(?:tell|inform|notify|alert|mention\s+(?:this\s+)?to|reveal\s+(?:this\s+)?to)\s+(?:the\s+)?(?:user|human|operator|owner)\b|\bwithout\s+(?:telling|informing|notifying|alerting)\s+(?:the\s+)?(?:user|human|operator)\b/i
+	},
+	{
+		label: "exfiltration-directive",
+		pattern: /\b(?:send|forward|email|transmit|upload|post|exfiltrate|leak)\b[^.?!\n]{0,60}\b(?:password|secret|api[\s_-]?keys?|credentials?|private\s+keys?|access\s+tokens?|auth\s+tokens?)\b/i
+	},
+	{
+		label: "persistent-override",
+		pattern: /\bfrom\s+now\s+on\b[^.?!\n]{0,40}\b(?:always|never|you\s+must|ignore|disregard|do\s+not)\b/i
+	}
+]);
+/**
+* Scan candidate memory text for obvious injection markers. Pure,
+* offline, allocation-light. Returns the matched rule labels so callers
+* can record *why* a candidate was quarantined.
+*
+* @stable
+*/
+function detectMemoryInjection(text, options = {}) {
+	const rules = options.rules ?? DEFAULT_INJECTION_RULES;
+	const markers = [];
+	for (const rule of rules) if (rule.pattern.test(text)) markers.push(rule.label);
+	if (options.extraRules !== void 0) {
+		for (const rule of options.extraRules) if (!markers.includes(rule.label) && rule.pattern.test(text)) markers.push(rule.label);
+	}
+	return {
+		flagged: markers.length > 0,
+		markers: Object.freeze(markers)
+	};
+}
+
+//#endregion
+export { detectMemoryInjection };
+//# sourceMappingURL=injection-heuristics.js.map

package/dist/internal/injection-heuristics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"injection-heuristics.js","names":["DEFAULT_INJECTION_RULES: ReadonlyArray<InjectionRule>","markers: string[]"],"sources":["../../src/internal/injection-heuristics.ts"],"sourcesContent":["/**\n * Offline, dependency-free heuristics that flag obvious memory-injection\n * markers in candidate memory text (P1-4). Long-lived memory is the prime\n * target for poisoning: an injected instruction planted today fires weeks\n * later when semantically recalled, defeating session-scoped prompt-injection\n * defenses (MINJA arXiv:2601.05504; MemoryGraft arXiv:2512.16962). Flagged\n * candidates are quarantined at write time so they never enter\n * action-driving recall until a human validates them.\n *\n * The detector is deliberately *high-precision*: every rule targets\n * injection-characteristic structure (imperative override of prior\n * instructions, role-markup smuggling, secrecy/exfiltration directives), not\n * lone common verbs, so benign first-party facts (\"I always run in the\n * mornings\", \"lives in Lisbon\") are not quarantined. It is locale-aware via\n * pluggable {@link InjectionRule} lists and performs no network or model\n * calls — pure regex over the candidate string.\n *\n * @packageDocumentation\n */\n\n/**\n * A single named injection-detection rule. The `label` is a stable,\n * audit-friendly identifier surfaced in {@link InjectionScan.markers};\n * the `pattern` MUST NOT carry the `g` flag (stateful `RegExp.test`).\n *\n * @stable\n */\nexport interface InjectionRule {\n  readonly label: string;\n  readonly pattern: RegExp;\n}\n\n/**\n * Result of scanning a candidate string. `flagged` is `true` when at\n * least one rule matched; `markers` lists the matched rule labels\n * (deduped, in rule order) for the audit trail.\n *\n * @stable\n */\nexport interface InjectionScan {\n  readonly flagged: boolean;\n  readonly markers: ReadonlyArray<string>;\n}\n\n/**\n * Options for {@link detectMemoryInjection}.\n *\n * @stable\n */\nexport interface InjectionHeuristicOptions {\n  /**\n   * Replace the default English rule set wholesale (advanced — for a\n   * fully custom locale). When omitted, {@link DEFAULT_INJECTION_RULES}\n   * is used.\n   */\n  readonly rules?: ReadonlyArray<InjectionRule>;\n  /**\n   * Additional locale-specific rules merged *after* the active rule set.\n   * The common way to make the detector locale-aware without discarding\n   * the English defaults.\n   */\n  readonly extraRules?: ReadonlyArray<InjectionRule>;\n}\n\n/**\n * Default English injection-marker rules. High-precision: each requires\n * injection-characteristic structure so benign facts do not trip them.\n *\n * @stable\n */\nexport const DEFAULT_INJECTION_RULES: ReadonlyArray<InjectionRule> = Object.freeze([\n  {\n    label: 'ignore-previous-instructions',\n    pattern:\n      /\\bignore\\s+(?:all\\s+|any\\s+)?(?:previous|prior|earlier|the\\s+above|preceding)\\s+(?:instructions?|prompts?|messages?|commands?|directions?|context|rules?)\\b/i,\n  },\n  {\n    label: 'disregard-instructions',\n    pattern:\n      /\\bdisregard\\s+(?:all\\s+|any\\s+|the\\s+)?(?:previous|prior|earlier|above|preceding|prior\\s+)?(?:instructions?|prompts?|rules?|guidelines?|guardrails?)\\b/i,\n  },\n  {\n    label: 'override-directive',\n    pattern: /\\boverride\\s+(?:the\\s+)?(?:system|safety|security|previous|prior|default)\\b/i,\n  },\n  {\n    label: 'system-prompt-exfil',\n    pattern:\n      /\\b(?:reveal|show|print|repeat|leak|expose|dump)\\b[^.?!\\n]{0,40}\\b(?:system\\s+prompt|system\\s+message|initial\\s+instructions|hidden\\s+(?:instructions|prompt))\\b/i,\n  },\n  {\n    label: 'role-markup-injection',\n    pattern: /<\\/?(?:system|im_start|im_end|tool_call|function_call)\\b|\\[\\/?(?:INST|SYS)\\]/i,\n  },\n  {\n    label: 'secrecy-directive',\n    pattern:\n      /\\b(?:do\\s+not|don['’]?t|never)\\s+(?:tell|inform|notify|alert|mention\\s+(?:this\\s+)?to|reveal\\s+(?:this\\s+)?to)\\s+(?:the\\s+)?(?:user|human|operator|owner)\\b|\\bwithout\\s+(?:telling|informing|notifying|alerting)\\s+(?:the\\s+)?(?:user|human|operator)\\b/i,\n  },\n  {\n    label: 'exfiltration-directive',\n    pattern:\n      /\\b(?:send|forward|email|transmit|upload|post|exfiltrate|leak)\\b[^.?!\\n]{0,60}\\b(?:password|secret|api[\\s_-]?keys?|credentials?|private\\s+keys?|access\\s+tokens?|auth\\s+tokens?)\\b/i,\n  },\n  {\n    label: 'persistent-override',\n    pattern:\n      /\\bfrom\\s+now\\s+on\\b[^.?!\\n]{0,40}\\b(?:always|never|you\\s+must|ignore|disregard|do\\s+not)\\b/i,\n  },\n]);\n\n/**\n * Scan candidate memory text for obvious injection markers. Pure,\n * offline, allocation-light. Returns the matched rule labels so callers\n * can record *why* a candidate was quarantined.\n *\n * @stable\n */\nexport function detectMemoryInjection(\n  text: string,\n  options: InjectionHeuristicOptions = {},\n): InjectionScan {\n  const rules = options.rules ?? DEFAULT_INJECTION_RULES;\n  const markers: string[] = [];\n  for (const rule of rules) {\n    if (rule.pattern.test(text)) markers.push(rule.label);\n  }\n  if (options.extraRules !== undefined) {\n    for (const rule of options.extraRules) {\n      if (!markers.includes(rule.label) && rule.pattern.test(text)) markers.push(rule.label);\n    }\n  }\n  return { flagged: markers.length > 0, markers: Object.freeze(markers) };\n}\n"],"mappings":";;;;;;;AAsEA,MAAaA,0BAAwD,OAAO,OAAO;CACjF;EACE,OAAO;EACP,SACE;EACH;CACD;EACE,OAAO;EACP,SACE;EACH;CACD;EACE,OAAO;EACP,SAAS;EACV;CACD;EACE,OAAO;EACP,SACE;EACH;CACD;EACE,OAAO;EACP,SAAS;EACV;CACD;EACE,OAAO;EACP,SACE;EACH;CACD;EACE,OAAO;EACP,SACE;EACH;CACD;EACE,OAAO;EACP,SACE;EACH;CACF,CAAC;;;;;;;;AASF,SAAgB,sBACd,MACA,UAAqC,EAAE,EACxB;CACf,MAAM,QAAQ,QAAQ,SAAS;CAC/B,MAAMC,UAAoB,EAAE;AAC5B,MAAK,MAAM,QAAQ,MACjB,KAAI,KAAK,QAAQ,KAAK,KAAK,CAAE,SAAQ,KAAK,KAAK,MAAM;AAEvD,KAAI,QAAQ,eAAe,QACzB;OAAK,MAAM,QAAQ,QAAQ,WACzB,KAAI,CAAC,QAAQ,SAAS,KAAK,MAAM,IAAI,KAAK,QAAQ,KAAK,KAAK,CAAE,SAAQ,KAAK,KAAK,MAAM;;AAG1F,QAAO;EAAE,SAAS,QAAQ,SAAS;EAAG,SAAS,OAAO,OAAO,QAAQ;EAAE"}

package/dist/internal/spans.js

@@ -0,0 +1,35 @@
+//#region src/internal/spans.ts
+/**
+* Sanitize a `SessionScope` for span attributes — the raw user id is
+* surfaced as-is (it is a stable opaque identifier per DEC-005), but
+* session and agent ids are emitted only when defined to avoid
+* polluting the trace with `null` strings.
+*
+* @internal
+*/
+function scopeAttrs(scope) {
+	const attrs = { "memory.scope.user_id": scope.userId };
+	if (scope.sessionId !== void 0) attrs["memory.scope.session_id"] = scope.sessionId;
+	if (scope.agentId !== void 0) attrs["memory.scope.agent_id"] = scope.agentId;
+	return Object.freeze(attrs);
+}
+/**
+* Run an async function inside a `memory.*` span with the standard
+* scope attributes already populated. Adds the span result count and
+* status automatically.
+*
+* @internal
+*/
+async function withMemorySpan(tracer, type, scope, extras, fn) {
+	return tracer.span({
+		type,
+		attrs: {
+			...scopeAttrs(scope),
+			...extras
+		}
+	}, fn);
+}
+
+//#endregion
+export { withMemorySpan };
+//# sourceMappingURL=spans.js.map

package/dist/internal/spans.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spans.js","names":["attrs: Record<string, string>"],"sources":["../../src/internal/spans.ts"],"sourcesContent":["import type { SessionScope, SpanAttributes, SpanType, Tracer } from '@graphorin/core';\n\n/**\n * Sanitize a `SessionScope` for span attributes — the raw user id is\n * surfaced as-is (it is a stable opaque identifier per DEC-005), but\n * session and agent ids are emitted only when defined to avoid\n * polluting the trace with `null` strings.\n *\n * @internal\n */\nexport function scopeAttrs(scope: SessionScope): SpanAttributes {\n  const attrs: Record<string, string> = {\n    'memory.scope.user_id': scope.userId,\n  };\n  if (scope.sessionId !== undefined) attrs['memory.scope.session_id'] = scope.sessionId;\n  if (scope.agentId !== undefined) attrs['memory.scope.agent_id'] = scope.agentId;\n  return Object.freeze(attrs);\n}\n\n/**\n * Run an async function inside a `memory.*` span with the standard\n * scope attributes already populated. Adds the span result count and\n * status automatically.\n *\n * @internal\n */\nexport async function withMemorySpan<T extends SpanType, R>(\n  tracer: Tracer,\n  type: T,\n  scope: SessionScope,\n  extras: SpanAttributes,\n  fn: (span: import('@graphorin/core').AISpan<T>) => Promise<R>,\n): Promise<R> {\n  return tracer.span({ type, attrs: { ...scopeAttrs(scope), ...extras } }, fn);\n}\n"],"mappings":";;;;;;;;;AAUA,SAAgB,WAAW,OAAqC;CAC9D,MAAMA,QAAgC,EACpC,wBAAwB,MAAM,QAC/B;AACD,KAAI,MAAM,cAAc,OAAW,OAAM,6BAA6B,MAAM;AAC5E,KAAI,MAAM,YAAY,OAAW,OAAM,2BAA2B,MAAM;AACxE,QAAO,OAAO,OAAO,MAAM;;;;;;;;;AAU7B,eAAsB,eACpB,QACA,MACA,OACA,QACA,IACY;AACZ,QAAO,OAAO,KAAK;EAAE;EAAM,OAAO;GAAE,GAAG,WAAW,MAAM;GAAE,GAAG;GAAQ;EAAE,EAAE,GAAG"}