@graphorin/memory 0.5.0

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

@@ -0,0 +1,129 @@
+import { MemoryStoreAdapter } from "../internal/storage-adapter.js";
+import { Block, Sensitivity, SessionScope, Tracer, ZodLikeSchema } from "@graphorin/core";
+
+//#region src/tiers/working-memory.d.ts
+
+/**
+ * Author-time block specification accepted by
+ * {@link defineBlock} and {@link WorkingMemory.define}.
+ *
+ * @stable
+ */
+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
+ */
+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
+ */
+declare function defineBlock(spec: BlockSpec): BlockDefinition;
+/**
+ * `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
+ */
+declare class WorkingMemory {
+  #private;
+  constructor(args: {
+    store: MemoryStoreAdapter;
+    tracer: Tracer;
+  });
+  /** Register a block definition. Returns the same definition object. */
+  define(definition: BlockDefinition): BlockDefinition;
+  /** Snapshot of every registered definition. */
+  definitions(): ReadonlyArray<BlockDefinition>;
+  /** Lookup a definition by label. */
+  definitionFor(label: string): BlockDefinition | undefined;
+  /** List active (non-deleted) blocks for the supplied scope. */
+  list(scope: SessionScope): Promise<ReadonlyArray<Block>>;
+  /** Read a single block's value (or `null` when absent). */
+  read(scope: SessionScope, label: string): Promise<string | null>;
+  /** Replace a block's value entirely. Honours overflow policy. */
+  write(scope: SessionScope, label: string, value: string): Promise<Block>;
+  /** Append `content` to a block (with a newline separator). */
+  append(scope: SessionScope, label: string, content: string): Promise<Block>;
+  /**
+   * Replace the unique substring `oldUnique` inside the block's value
+   * with `newText`. Throws `WorkingBlockReplaceMismatchError` when
+   * the substring is missing or appears more than once.
+   */
+  replace(scope: SessionScope, label: string, oldUnique: string, newText: string): Promise<Block>;
+  /** Run `mutator(current) => next` and persist the result. */
+  rethink(scope: SessionScope, label: string, mutator: (current: string) => string | Promise<string>): Promise<Block>;
+  /** Soft-delete a block. */
+  forget(scope: SessionScope, label: string, reason?: string): Promise<void>;
+  /**
+   * 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.
+   */
+  attach(scope: SessionScope, blockId: string, agentId: string): Promise<void>;
+  /** Detach a working block from an agent. */
+  detach(scope: SessionScope, blockId: string, agentId: string): Promise<void>;
+  /**
+   * 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.
+   */
+  compile(scope: SessionScope, agentId?: string): Promise<string>;
+}
+//#endregion
+export { BlockDefinition, BlockSpec, WorkingMemory, defineBlock };
+//# sourceMappingURL=working-memory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"working-memory.d.ts","names":[],"sources":["../../src/tiers/working-memory.ts"],"sourcesContent":[],"mappings":";;;;;;;AAgBA;;;;AAkB+B,UAlBd,SAAA,CAkBc;EAUd,SAAA,KAAA,EAAA,MAAe;EAGZ,SAAA,WAAA,CAAA,EAAA,MAAA;EAEI,SAAA,MAAA,CAAA,EA9BJ,aA8BI,CAAA,OAAA,CAAA;EAIN;EAAa,SAAA,SAAA,EAAA,MAAA;EAUf;EAyCH,SAAA,WAAa,CAAA,EAjFD,WAiFC;EAKG;EAA4B,SAAA,QAAA,CAAA,EAAA,OAAA;EAOpC;;;;EAWW,SAAA,YAAA,CAAA,EAAA,MAAA;EAKZ;EAAqC,SAAA,cAAA,CAAA,EAAA,UAAA,GAAA,QAAA;EAAd;EAAR,SAAA,IAAA,CAAA,EAlGjB,aAkGiB,CAAA,MAAA,CAAA;;;;;;;;;AA+CxB,UAvIM,eAAA,CAuIN;EAIE,SAAA,KAAA,EAAA,MAAA;EAAR,SAAA,WAAA,CAAA,EAAA,MAAA;EAaM,SAAA,MAAA,CAAA,EArJS,aAqJT,CAAA,OAAA,CAAA;EAEgC,SAAA,SAAA,EAAA,MAAA;EAC9B,SAAA,WAAA,EAtJW,WAsJX;EAAR,SAAA,QAAA,EAAA,OAAA;EAKiB,SAAA,YAAA,CAAA,EAAA,MAAA;EAA+C,SAAA,cAAA,EAAA,UAAA,GAAA,QAAA;EAiB/C,SAAA,IAAA,CAAA,EAxKJ,aAwKI,CAAA,MAAA,CAAA;;;;;;;;;iBA9JN,WAAA,OAAkB,YAAY;;;;;;;;;;;;;;;;;;;;cAyCjC,aAAA;;;WAKgB;YAA4B;;;qBAOpC,kBAAkB;;iBAMtB,cAAc;;gCAKC;;cAKZ,eAAe,QAAQ,cAAc;;cASrC,8BAA8B;;eAoB7B,6CAA6C,QAAQ;;gBAKpD,+CAA+C,QAAQ;;;;;;iBAalE,kEAIN,QAAQ;;iBAaF,oEAEgC,kBACtC,QAAQ;;gBAKS,+CAA+C;;;;;;gBAiB/C,iDAAiD;;gBAiBjD,iDAAiD;;;;;;;;;;;iBA0BhD,iCAAiC"}

package/dist/tiers/working-memory.js

@@ -0,0 +1,229 @@
+import { withMemorySpan } from "../internal/spans.js";
+import { WorkingBlockOverflowError, WorkingBlockReadOnlyError, WorkingBlockReplaceMismatchError } from "../errors/index.js";
+import { newMemoryId } from "../internal/id.js";
+
+//#region src/tiers/working-memory.ts
+/**
+* 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
+*/
+function defineBlock(spec) {
+	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 !== void 0 ? { description: spec.description } : {},
+		...spec.schema !== void 0 ? { schema: spec.schema } : {},
+		charLimit: spec.charLimit,
+		sensitivity: spec.sensitivity ?? "internal",
+		readOnly: spec.readOnly ?? false,
+		...spec.defaultValue !== void 0 ? { defaultValue: spec.defaultValue } : {},
+		overflowPolicy: spec.overflowPolicy ?? "truncate",
+		...spec.tags !== void 0 ? { 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
+*/
+var WorkingMemory = class {
+	#store;
+	#tracer;
+	#defs;
+	constructor(args) {
+		this.#store = args.store;
+		this.#tracer = args.tracer;
+		this.#defs = /* @__PURE__ */ new Map();
+	}
+	/** Register a block definition. Returns the same definition object. */
+	define(definition) {
+		this.#defs.set(definition.label, definition);
+		return definition;
+	}
+	/** Snapshot of every registered definition. */
+	definitions() {
+		return Array.from(this.#defs.values());
+	}
+	/** Lookup a definition by label. */
+	definitionFor(label) {
+		return this.#defs.get(label);
+	}
+	/** List active (non-deleted) blocks for the supplied scope. */
+	async list(scope) {
+		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, label) {
+		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;
+			return this.#defs.get(label)?.defaultValue ?? null;
+		});
+	}
+	/** Replace a block's value entirely. Honours overflow policy. */
+	async write(scope, label, value) {
+		return this.#mutate(scope, label, async () => value);
+	}
+	/** Append `content` to a block (with a newline separator). */
+	async append(scope, label, content) {
+		return this.#mutate(scope, label, async (current) => {
+			if (current === "" || current === void 0) 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, label, oldUnique, newText) {
+		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, label, mutator) {
+		return this.#mutate(scope, label, async (current) => mutator(current ?? ""));
+	}
+	/** Soft-delete a block. */
+	async forget(scope, label, reason) {
+		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, blockId, agentId) {
+		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, blockId, agentId) {
+		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, 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 !== void 0 ? ` 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, label, nextValueFn) {
+		return withMemorySpan(this.#tracer, "memory.write.working", scope, { "memory.block.label": label }, async (span) => {
+			const definition = this.#requireDefinition(label);
+			if (definition.readOnly === true) throw new WorkingBlockReadOnlyError(label);
+			const existing = await this.#store.working.get(scope, label);
+			const enforcedValue = enforceCharLimit(await nextValueFn(existing?.value ?? definition.defaultValue), definition);
+			const now = (/* @__PURE__ */ new Date()).toISOString();
+			const block = {
+				id: existing?.id ?? newMemoryId("block"),
+				kind: "working",
+				userId: scope.userId,
+				...scope.sessionId !== void 0 ? { sessionId: scope.sessionId } : {},
+				...scope.agentId !== void 0 ? { agentId: scope.agentId } : {},
+				sensitivity: definition.sensitivity,
+				label,
+				...definition.description !== void 0 ? { description: definition.description } : {},
+				value: enforcedValue,
+				charLimit: definition.charLimit,
+				readOnly: definition.readOnly,
+				...definition.tags !== void 0 ? { 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) {
+		const def = this.#defs.get(label);
+		if (def !== void 0) 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, definition) {
+	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, needle) {
+	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) {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+
+//#endregion
+export { WorkingMemory, defineBlock };
+//# sourceMappingURL=working-memory.js.map

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

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

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

@@ -0,0 +1,98 @@
+import { MemoryToolDeps } from "./types.js";
+import { Tool } from "@graphorin/core";
+import { z } from "zod";
+
+//#region src/tools/block-tools.d.ts
+declare const blockAppendInputSchema: z.ZodObject<{
+  label: z.ZodString;
+  content: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+  label: string;
+  content: string;
+}, {
+  label: string;
+  content: string;
+}>;
+declare const blockAppendOutputSchema: z.ZodObject<{
+  label: z.ZodString;
+  length: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+  length: number;
+  label: string;
+}, {
+  length: number;
+  label: string;
+}>;
+type BlockAppendInput = z.infer<typeof blockAppendInputSchema>;
+type BlockAppendOutput = z.infer<typeof blockAppendOutputSchema>;
+declare const blockReplaceInputSchema: z.ZodObject<{
+  label: z.ZodString;
+  oldUnique: z.ZodString;
+  newText: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+  label: string;
+  oldUnique: string;
+  newText: string;
+}, {
+  label: string;
+  oldUnique: string;
+  newText: string;
+}>;
+declare const blockReplaceOutputSchema: z.ZodObject<{
+  label: z.ZodString;
+  length: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+  length: number;
+  label: string;
+}, {
+  length: number;
+  label: string;
+}>;
+type BlockReplaceInput = z.infer<typeof blockReplaceInputSchema>;
+type BlockReplaceOutput = z.infer<typeof blockReplaceOutputSchema>;
+declare const blockRethinkInputSchema: z.ZodObject<{
+  label: z.ZodString;
+  newValue: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+  label: string;
+  newValue: string;
+}, {
+  label: string;
+  newValue: string;
+}>;
+declare const blockRethinkOutputSchema: z.ZodObject<{
+  label: z.ZodString;
+  length: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+  length: number;
+  label: string;
+}, {
+  length: number;
+  label: string;
+}>;
+type BlockRethinkInput = z.infer<typeof blockRethinkInputSchema>;
+type BlockRethinkOutput = z.infer<typeof blockRethinkOutputSchema>;
+/**
+ * `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
+ * memory block. Throws when the substring is missing or appears more
+ * than once.
+ *
+ * @stable
+ */
+declare function createBlockReplaceTool(deps: MemoryToolDeps): Tool<BlockReplaceInput, BlockReplaceOutput>;
+/**
+ * `block_rethink` — rewrite a working memory block from scratch.
+ *
+ * @stable
+ */
+declare function createBlockRethinkTool(deps: MemoryToolDeps): Tool<BlockRethinkInput, BlockRethinkOutput>;
+//#endregion
+export { createBlockAppendTool, createBlockReplaceTool, createBlockRethinkTool };
+//# sourceMappingURL=block-tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"block-tools.d.ts","names":[],"sources":["../../src/tools/block-tools.ts"],"sourcesContent":[],"mappings":";;;;;cAKM,wBAAsB,CAAA,CAAA;;EAAtB,OAAA,aAAA;;;;CAAsB,EAAA;EAAA,KAAA,EAAA,MAAA;EAItB,OAAA,EAAA,MAAA;;cAAA,yBAAuB,CAAA,CAAA;;EAAA,MAAA,aAAA;CAAA,EAAA,OAAA,cAAA,EAAA;EAKxB,MAAA,EAAA,MAAA;EACA,KAAA,EAAA,MAAA;AAA2B,CAAA,EAAA;;;;KAD3B,gBAAA,GAAmB,CAAA,CAAE,aAAa;KAClC,iBAAA,GAAoB,CAAA,CAAE,KAEE,CAAA,OAFW,uBAEX,CAAA;cAAvB,uBAAuB,EAAA,CAAA,CAAA,SAAA,CAAA;EAKvB,KAAA,aAAA;;;;EAAwB,KAAA,EAAA,MAAA;EAAA,SAAA,EAAA,MAAA;EAKzB,OAAA,EAAA,MAAA;AAA2B,CAAA,EAAA;EAG1B,KAAA,EAAA,MAAA;;;;cARA,wBAQuB,EARC,CAAA,CAAA,SAQD,CAAA;EAAA,KAAA,aAAA;EAIvB,MAAA,aAAA;;;;CAAwB,EAAA;EAAA,MAAA,EAAA,MAAA;EAKzB,KAAA,EAAA,MAAA;AAA2B,CAAA,CAAA;AAShC,KArBK,iBAAA,GAAoB,CAAA,CAAE,KAqBU,CAAA,OArBG,uBAqBH,CAAA;KApBhC,kBAAA,GAAqB,CAAA,CAAE,KAqBpB,CAAA,OArBiC,wBAqBjC,CAAA;cAnBF,uBAoBE,EApBqB,CAAA,CAAA,SAoBrB,CAAA;EAAkB,KAAA,aAAA;EAAvB,QAAA,aAAA;CAAI,EAAA,OAAA,cAAA,EAAA;EA2BS,KAAA,EAAA,MAAA;EACR,QAAA,EAAA,MAAA;CACA,EAAA;EAAmB,KAAA,EAAA,MAAA;EAAxB,QAAA,EAAA,MAAA;CAAI,CAAA;AAyBP,cAtEM,wBAsEgC,EAtER,CAAA,CAAA,SAsEQ,CAAA;EAC9B,KAAA,aAAA;EACA,MAAA,aAAA;CAAmB,EAAA,OAAA,cAAA,EAAA;EAAxB,MAAA,EAAA,MAAA;EAAI,KAAA,EAAA,MAAA;;;;;KAnEF,iBAAA,GAAoB,CAAA,CAAE,aAAa;KACnC,kBAAA,GAAqB,CAAA,CAAE,aAAa;;;;;;;iBAQzB,qBAAA,OACR,iBACL,KAAK,kBAAkB;;;;;;;;iBA2BV,sBAAA,OACR,iBACL,KAAK,mBAAmB;;;;;;iBAyBX,sBAAA,OACR,iBACL,KAAK,mBAAmB"}

package/dist/tools/block-tools.js

@@ -0,0 +1,114 @@
+import { tool } from "@graphorin/tools";
+import { z } from "zod";
+
+//#region src/tools/block-tools.ts
+const blockAppendInputSchema = z.object({
+	label: z.string().min(1).max(128),
+	content: z.string().min(1)
+});
+const blockAppendOutputSchema = z.object({
+	label: z.string(),
+	length: z.number()
+});
+const blockReplaceInputSchema = z.object({
+	label: z.string().min(1).max(128),
+	oldUnique: z.string().min(1),
+	newText: z.string()
+});
+const blockReplaceOutputSchema = z.object({
+	label: z.string(),
+	length: z.number()
+});
+const blockRethinkInputSchema = z.object({
+	label: z.string().min(1).max(128),
+	newValue: z.string()
+});
+const blockRethinkOutputSchema = z.object({
+	label: z.string(),
+	length: z.number()
+});
+/**
+* `block_append` — append text (with a newline separator) to a working
+* memory block.
+*
+* @stable
+*/
+function createBlockAppendTool(deps) {
+	return tool({
+		name: "block_append",
+		description: "Append text to a working memory block. The block is identified by its label (registered via memory.working.define(...)). Use this when accumulating notes, observations, or reasoning steps that should persist across turns.",
+		inputSchema: blockAppendInputSchema,
+		outputSchema: blockAppendOutputSchema,
+		sideEffectClass: "side-effecting",
+		sandboxPolicy: "none",
+		sensitivity: "internal",
+		memoryGuardTier: "memory-aware",
+		tags: ["memory", "working"],
+		async execute(input, ctx) {
+			const scope = await deps.resolveScope(ctx);
+			const block = await deps.working.append(scope, input.label, input.content);
+			return {
+				label: block.label,
+				length: block.value.length
+			};
+		}
+	});
+}
+/**
+* `block_replace` — replace a unique substring inside a working
+* memory block. Throws when the substring is missing or appears more
+* than once.
+*
+* @stable
+*/
+function createBlockReplaceTool(deps) {
+	return tool({
+		name: "block_replace",
+		description: "Replace a UNIQUE substring inside a working memory block. The substring must appear exactly once; the call fails fast if missing or non-unique. Use block_rethink for full rewrites.",
+		inputSchema: blockReplaceInputSchema,
+		outputSchema: blockReplaceOutputSchema,
+		sideEffectClass: "side-effecting",
+		sandboxPolicy: "none",
+		sensitivity: "internal",
+		memoryGuardTier: "memory-aware",
+		tags: ["memory", "working"],
+		async execute(input, ctx) {
+			const scope = await deps.resolveScope(ctx);
+			const block = await deps.working.replace(scope, input.label, input.oldUnique, input.newText);
+			return {
+				label: block.label,
+				length: block.value.length
+			};
+		}
+	});
+}
+/**
+* `block_rethink` — rewrite a working memory block from scratch.
+*
+* @stable
+*/
+function createBlockRethinkTool(deps) {
+	return tool({
+		name: "block_rethink",
+		description: "Replace a working memory block's value entirely. Use this when restructuring or summarising the block's contents. For surgical edits, prefer block_replace.",
+		inputSchema: blockRethinkInputSchema,
+		outputSchema: blockRethinkOutputSchema,
+		sideEffectClass: "side-effecting",
+		sandboxPolicy: "none",
+		sensitivity: "internal",
+		memoryGuardTier: "memory-aware",
+		tags: ["memory", "working"],
+		async execute(input, ctx) {
+			const scope = await deps.resolveScope(ctx);
+			const block = await deps.working.rethink(scope, input.label, () => input.newValue);
+			return {
+				label: block.label,
+				length: block.value.length
+			};
+		}
+	});
+}
+
+//#endregion
+export { createBlockAppendTool, createBlockReplaceTool, createBlockRethinkTool };
+//# sourceMappingURL=block-tools.js.map

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

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