@warlock.js/ai 4.4.0 → 4.6.0

package/esm/skills/sources/url-source.mjs

@@ -0,0 +1,117 @@
+import { fetchTextWithPolicy } from "../../security/outbound-policy.mjs";
+
+//#region ../@warlock.js/ai/src/skills/sources/url-source.ts
+/**
+* Read skills from a remote JSON manifest at `url`. The manifest is a flat
+* array of {@link SkillRecord}s (bodies inline).
+*
+* **Trust boundary (S3).** A remote skill source is a prompt supply chain —
+* its bodies flow straight into model context — so the manifest fetch runs
+* through the shared `OutboundPolicy` (scheme + host allowlist, post-DNS
+* private-IP deny, max bytes, timeout) and **every record is runtime-
+* validated** before it can be served. A malformed record fails loudly
+* rather than being cast blindly into a `SkillRecord`.
+*
+* The request is made lazily on the first `list()` / `load()`. The result
+* is cached for the source's lifetime, or for `cacheTtlMs` when set
+* (a stale cache refetches on next access).
+*/
+function urlSource(url, options = {}) {
+	const { headers, policy, cacheTtlMs } = options;
+	let cache;
+	let cachedAtMs;
+	const records = () => {
+		const expired = cacheTtlMs !== void 0 && cachedAtMs !== void 0 && Date.now() - cachedAtMs > cacheTtlMs;
+		if (!cache || expired) {
+			cachedAtMs = Date.now();
+			cache = fetchManifest(url, headers, policy);
+		}
+		return cache;
+	};
+	return {
+		async list(scope) {
+			const all = await records();
+			const wanted = scope?.tags;
+			return [...all.values()].filter((record) => record.type !== "candidate").filter((record) => intersects(record.tags, wanted)).map(toCatalogEntry);
+		},
+		async load(name, version) {
+			const record = (await records()).get(name);
+			if (!record || record.type === "candidate") return;
+			if (version !== void 0 && record.version !== version) return;
+			return record;
+		},
+		async saveCandidate() {
+			throw new Error("url source is read-only — saveCandidate requires a writable store (set `review.store`)");
+		},
+		async promote() {
+			throw new Error("url source is read-only — promote requires a writable store (set `review.store`)");
+		}
+	};
+}
+/** Fetch + validate + parse the manifest once into a name → record map. */
+async function fetchManifest(url, headers, policy) {
+	const result = await fetchTextWithPolicy(url, policy ?? {}, headers ? { headers } : void 0);
+	if (!result.ok) throw new Error(`url skill source failed: ${result.status} ${result.statusText} for ${url}`);
+	let parsed;
+	try {
+		parsed = JSON.parse(result.text);
+	} catch (cause) {
+		throw new Error(`url skill source returned invalid JSON from ${url}`, { cause });
+	}
+	if (!Array.isArray(parsed)) throw new Error(`url skill source at ${url} must return a JSON array of skill records`);
+	const records = /* @__PURE__ */ new Map();
+	parsed.forEach((raw, index) => {
+		const record = validateManifestRecord(raw, url, index);
+		records.set(record.name, record);
+	});
+	return records;
+}
+/**
+* Runtime-validate one manifest record before it is trusted as a
+* {@link SkillRecord}. Untyped remote JSON cast blindly into the context
+* is both an injection surface and a correctness bug; this rejects a
+* record missing the required `name` / `description` / `body` strings, and
+* fills `version` / `type` defaults for a thin record.
+*/
+function validateManifestRecord(raw, url, index) {
+	if (!raw || typeof raw !== "object") throw new Error(`url skill source at ${url}: record #${index} is not an object`);
+	const r = raw;
+	const requireString = (field) => {
+		const value = r[field];
+		if (typeof value !== "string" || value.length === 0) throw new Error(`url skill source at ${url}: record #${index} is missing a string "${field}"`);
+		return value;
+	};
+	const name = requireString("name");
+	const description = requireString("description");
+	const body = requireString("body");
+	const type = r.type === "authored" || r.type === "promoted" || r.type === "candidate" ? r.type : "authored";
+	return {
+		name,
+		description,
+		body,
+		version: typeof r.version === "number" ? r.version : 1,
+		type,
+		tags: Array.isArray(r.tags) ? r.tags.filter((t) => typeof t === "string") : void 0,
+		metadata: r.metadata && typeof r.metadata === "object" ? r.metadata : void 0
+	};
+}
+/** Project a full record down to its catalog entry (body omitted). */
+function toCatalogEntry(record) {
+	return {
+		name: record.name,
+		description: record.description,
+		version: record.version,
+		tags: record.tags,
+		type: record.type
+	};
+}
+/** True when no filter is requested or the record shares a requested tag. */
+function intersects(recordTags, wanted) {
+	if (!wanted || wanted.length === 0) return true;
+	if (!recordTags || recordTags.length === 0) return false;
+	return recordTags.some((tag) => wanted.includes(tag));
+}
+
+//#endregion
+export { urlSource };
+//# sourceMappingURL=url-source.mjs.map

package/esm/skills/sources/url-source.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-source.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/skills/sources/url-source.ts"],"sourcesContent":["import { fetchTextWithPolicy } from \"../../security/outbound-policy\";\nimport type { OutboundPolicy } from \"../../security/outbound-policy.type\";\nimport type {\n  SkillCatalogEntry,\n  SkillRecord,\n} from \"../contracts/skill-record.type\";\nimport type { SkillsStoreContract } from \"../contracts/skills-store.contract\";\n\n/**\n * The JSON manifest shape a `url` source fetches — a flat array of skill\n * records. Bodies travel inline; the catalog projection drops them so the\n * always-injected metadata block stays cheap.\n */\ntype SkillManifest = SkillRecord[];\n\n/** Options for {@link urlSource} (S3). */\nexport type UrlSourceOptions = {\n  headers?: Record<string, string>;\n  /** Fetch hardening for the manifest request. */\n  policy?: OutboundPolicy;\n  /** Cache the manifest for this many ms; omit to cache for the source's lifetime. */\n  cacheTtlMs?: number;\n};\n\n/**\n * Read skills from a remote JSON manifest at `url`. The manifest is a flat\n * array of {@link SkillRecord}s (bodies inline).\n *\n * **Trust boundary (S3).** A remote skill source is a prompt supply chain —\n * its bodies flow straight into model context — so the manifest fetch runs\n * through the shared `OutboundPolicy` (scheme + host allowlist, post-DNS\n * private-IP deny, max bytes, timeout) and **every record is runtime-\n * validated** before it can be served. A malformed record fails loudly\n * rather than being cast blindly into a `SkillRecord`.\n *\n * The request is made lazily on the first `list()` / `load()`. The result\n * is cached for the source's lifetime, or for `cacheTtlMs` when set\n * (a stale cache refetches on next access).\n */\nexport function urlSource(\n  url: string,\n  options: UrlSourceOptions = {},\n): SkillsStoreContract {\n  const { headers, policy, cacheTtlMs } = options;\n\n  let cache: Promise<Map<string, SkillRecord>> | undefined;\n  let cachedAtMs: number | undefined;\n\n  const records = (): Promise<Map<string, SkillRecord>> => {\n    const expired =\n      cacheTtlMs !== undefined &&\n      cachedAtMs !== undefined &&\n      Date.now() - cachedAtMs > cacheTtlMs;\n\n    if (!cache || expired) {\n      cachedAtMs = Date.now();\n      cache = fetchManifest(url, headers, policy);\n    }\n\n    return cache;\n  };\n\n  return {\n    async list(scope?: { tags?: string[] }): Promise<SkillCatalogEntry[]> {\n      const all = await records();\n      const wanted = scope?.tags;\n\n      return [...all.values()]\n        .filter(record => record.type !== \"candidate\")\n        .filter(record => intersects(record.tags, wanted))\n        .map(toCatalogEntry);\n    },\n    async load(name: string, version?: number): Promise<SkillRecord | undefined> {\n      const all = await records();\n      const record = all.get(name);\n\n      if (!record || record.type === \"candidate\") {\n        return undefined;\n      }\n\n      if (version !== undefined && record.version !== version) {\n        return undefined;\n      }\n\n      return record;\n    },\n    async saveCandidate(): Promise<SkillRecord> {\n      throw new Error(\n        \"url source is read-only — saveCandidate requires a writable store (set `review.store`)\",\n      );\n    },\n    async promote(): Promise<SkillRecord> {\n      throw new Error(\n        \"url source is read-only — promote requires a writable store (set `review.store`)\",\n      );\n    },\n  };\n}\n\n/** Fetch + validate + parse the manifest once into a name → record map. */\nasync function fetchManifest(\n  url: string,\n  headers: Record<string, string> | undefined,\n  policy: OutboundPolicy | undefined,\n): Promise<Map<string, SkillRecord>> {\n  const result = await fetchTextWithPolicy(\n    url,\n    policy ?? {},\n    headers ? { headers } : undefined,\n  );\n\n  if (!result.ok) {\n    throw new Error(\n      `url skill source failed: ${result.status} ${result.statusText} for ${url}`,\n    );\n  }\n\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(result.text);\n  } catch (cause) {\n    throw new Error(`url skill source returned invalid JSON from ${url}`, {\n      cause,\n    });\n  }\n\n  if (!Array.isArray(parsed)) {\n    throw new Error(\n      `url skill source at ${url} must return a JSON array of skill records`,\n    );\n  }\n\n  const records = new Map<string, SkillRecord>();\n\n  (parsed as SkillManifest).forEach((raw, index) => {\n    const record = validateManifestRecord(raw, url, index);\n    records.set(record.name, record);\n  });\n\n  return records;\n}\n\n/**\n * Runtime-validate one manifest record before it is trusted as a\n * {@link SkillRecord}. Untyped remote JSON cast blindly into the context\n * is both an injection surface and a correctness bug; this rejects a\n * record missing the required `name` / `description` / `body` strings, and\n * fills `version` / `type` defaults for a thin record.\n */\nfunction validateManifestRecord(\n  raw: unknown,\n  url: string,\n  index: number,\n): SkillRecord {\n  if (!raw || typeof raw !== \"object\") {\n    throw new Error(`url skill source at ${url}: record #${index} is not an object`);\n  }\n\n  const r = raw as Record<string, unknown>;\n  const requireString = (field: string): string => {\n    const value = r[field];\n    if (typeof value !== \"string\" || value.length === 0) {\n      throw new Error(\n        `url skill source at ${url}: record #${index} is missing a string \"${field}\"`,\n      );\n    }\n    return value;\n  };\n\n  const name = requireString(\"name\");\n  const description = requireString(\"description\");\n  const body = requireString(\"body\");\n\n  const type =\n    r.type === \"authored\" || r.type === \"promoted\" || r.type === \"candidate\"\n      ? r.type\n      : \"authored\";\n  const version = typeof r.version === \"number\" ? r.version : 1;\n  const tags = Array.isArray(r.tags)\n    ? r.tags.filter((t): t is string => typeof t === \"string\")\n    : undefined;\n  const metadata =\n    r.metadata && typeof r.metadata === \"object\"\n      ? (r.metadata as Record<string, unknown>)\n      : undefined;\n\n  return { name, description, body, version, type, tags, metadata };\n}\n\n/** Project a full record down to its catalog entry (body omitted). */\nfunction toCatalogEntry(record: SkillRecord): SkillCatalogEntry {\n  return {\n    name: record.name,\n    description: record.description,\n    version: record.version,\n    tags: record.tags,\n    type: record.type,\n  };\n}\n\n/** True when no filter is requested or the record shares a requested tag. */\nfunction intersects(recordTags: string[] | undefined, wanted: string[] | undefined): boolean {\n  if (!wanted || wanted.length === 0) {\n    return true;\n  }\n\n  if (!recordTags || recordTags.length === 0) {\n    return false;\n  }\n\n  return recordTags.some(tag => wanted.includes(tag));\n}\n"],"mappings":"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"}

package/esm/skills/store/mock-skills-store.d.mts

@@ -0,0 +1,57 @@
+import { SkillCatalogEntry, SkillRecord } from "../contracts/skill-record.type.mjs";
+import { SkillsStoreContract } from "../contracts/skills-store.contract.mjs";
+
+//#region ../@warlock.js/ai/src/skills/store/mock-skills-store.d.ts
+/**
+ * In-memory {@link SkillsStoreContract} that ships with the package.
+ *
+ * Backs tests and small/ephemeral skill libraries with zero external
+ * dependencies. Holds the **latest** record per skill name; `saveCandidate`
+ * writes an INERT `type: "candidate"` (never injectable until promoted),
+ * and `promote` flips it to `type: "promoted"` with a monotonic
+ * `version + 1`.
+ *
+ * Construct via `new MockSkillsStore([...records])` — it is a concrete
+ * test/utility store, not a factory-fronted runtime primitive, so `new`
+ * is the public surface here.
+ *
+ * @example
+ * const store = new MockSkillsStore([
+ *   { name: "scaffold", description: "Scaffold a form", version: 1, body: "...", type: "authored" },
+ * ]);
+ * const lib = skills({ name: "build", sources: [{ type: "store", store }] });
+ */
+declare class MockSkillsStore implements SkillsStoreContract {
+  /** Latest record per skill name. */
+  private readonly records;
+  constructor(seed?: SkillRecord[]);
+  /**
+   * List the cheap catalog metadata for every NON-candidate skill,
+   * optionally filtered to those whose `tags` intersect `scope.tags`.
+   * Candidates are filtered out — they can never be catalogued or injected.
+   */
+  list(scope?: {
+    tags?: string[];
+  }): Promise<SkillCatalogEntry[]>;
+  /**
+   * Load the full record for `name`. When `version` is given, returns the
+   * record only if its version matches (pin); otherwise the latest. A
+   * `candidate` is never returned here — it is inert until promoted.
+   */
+  load(name: string, version?: number): Promise<SkillRecord | undefined>;
+  /**
+   * Write an INERT candidate (`type: "candidate"`, `version: 0`). A
+   * candidate is filtered out of `list()` / `load()` — it can never be
+   * injected until a `review` gate promotes it.
+   */
+  saveCandidate(record: Omit<SkillRecord, "version" | "type">): Promise<SkillRecord>;
+  /**
+   * Promote the stored candidate for `name` to a new monotonic version
+   * (`type: "promoted"`, `version + 1`). Throws when there is no candidate
+   * to promote — promotion of a non-existent skill is a programming error.
+   */
+  promote(name: string): Promise<SkillRecord>;
+}
+//#endregion
+export { MockSkillsStore };
+//# sourceMappingURL=mock-skills-store.d.mts.map

package/esm/skills/store/mock-skills-store.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-skills-store.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/skills/store/mock-skills-store.ts"],"mappings":";;;;;;AAyBA;;;;;;;;;;;;;;;;;cAAa,eAAA,YAA2B,mBAAA;EAErB;EAAA,iBAAA,OAAA;cAEE,IAAA,GAAM,WAAA;EAAN;;;;;EAWN,IAAA,CAAK,KAAA;IAAU,IAAA;EAAA,IAAoB,OAAA,CAAQ,iBAAA;EAcxB;;;;;EAAnB,IAAA,CAAK,IAAA,UAAc,OAAA,YAAmB,OAAA,CAAQ,WAAA;EAoBzD;;;;;EADW,aAAA,CACX,MAAA,EAAQ,IAAA,CAAK,WAAA,wBACZ,OAAA,CAAQ,WAAA;EAiBiC;;AAAW;;;EAA1C,OAAA,CAAQ,IAAA,WAAe,OAAA,CAAQ,WAAA;AAAA"}

package/esm/skills/store/mock-skills-store.mjs

@@ -0,0 +1,100 @@
+//#region ../@warlock.js/ai/src/skills/store/mock-skills-store.ts
+/**
+* In-memory {@link SkillsStoreContract} that ships with the package.
+*
+* Backs tests and small/ephemeral skill libraries with zero external
+* dependencies. Holds the **latest** record per skill name; `saveCandidate`
+* writes an INERT `type: "candidate"` (never injectable until promoted),
+* and `promote` flips it to `type: "promoted"` with a monotonic
+* `version + 1`.
+*
+* Construct via `new MockSkillsStore([...records])` — it is a concrete
+* test/utility store, not a factory-fronted runtime primitive, so `new`
+* is the public surface here.
+*
+* @example
+* const store = new MockSkillsStore([
+*   { name: "scaffold", description: "Scaffold a form", version: 1, body: "...", type: "authored" },
+* ]);
+* const lib = skills({ name: "build", sources: [{ type: "store", store }] });
+*/
+var MockSkillsStore = class {
+	constructor(seed = []) {
+		this.records = /* @__PURE__ */ new Map();
+		for (const record of seed) this.records.set(record.name, { ...record });
+	}
+	/**
+	* List the cheap catalog metadata for every NON-candidate skill,
+	* optionally filtered to those whose `tags` intersect `scope.tags`.
+	* Candidates are filtered out — they can never be catalogued or injected.
+	*/
+	async list(scope) {
+		const wanted = scope?.tags;
+		return [...this.records.values()].filter((record) => record.type !== "candidate").filter((record) => intersects(record.tags, wanted)).map(toCatalogEntry);
+	}
+	/**
+	* Load the full record for `name`. When `version` is given, returns the
+	* record only if its version matches (pin); otherwise the latest. A
+	* `candidate` is never returned here — it is inert until promoted.
+	*/
+	async load(name, version) {
+		const record = this.records.get(name);
+		if (!record || record.type === "candidate") return;
+		if (version !== void 0 && record.version !== version) return;
+		return { ...record };
+	}
+	/**
+	* Write an INERT candidate (`type: "candidate"`, `version: 0`). A
+	* candidate is filtered out of `list()` / `load()` — it can never be
+	* injected until a `review` gate promotes it.
+	*/
+	async saveCandidate(record) {
+		const candidate = {
+			...record,
+			version: 0,
+			type: "candidate"
+		};
+		this.records.set(candidate.name, candidate);
+		return { ...candidate };
+	}
+	/**
+	* Promote the stored candidate for `name` to a new monotonic version
+	* (`type: "promoted"`, `version + 1`). Throws when there is no candidate
+	* to promote — promotion of a non-existent skill is a programming error.
+	*/
+	async promote(name) {
+		const existing = this.records.get(name);
+		if (!existing) throw new Error(`MockSkillsStore.promote: no skill named "${name}" to promote`);
+		const promoted = {
+			...existing,
+			version: existing.version + 1,
+			type: "promoted"
+		};
+		this.records.set(name, promoted);
+		return { ...promoted };
+	}
+};
+/** Project a full record down to its catalog entry (body omitted). */
+function toCatalogEntry(record) {
+	return {
+		name: record.name,
+		description: record.description,
+		version: record.version,
+		tags: record.tags,
+		type: record.type
+	};
+}
+/**
+* True when no filter tags are requested, or when the record carries at
+* least one of the requested tags. A tagless record matches only the
+* unfiltered case.
+*/
+function intersects(recordTags, wanted) {
+	if (!wanted || wanted.length === 0) return true;
+	if (!recordTags || recordTags.length === 0) return false;
+	return recordTags.some((tag) => wanted.includes(tag));
+}
+
+//#endregion
+export { MockSkillsStore };
+//# sourceMappingURL=mock-skills-store.mjs.map

package/esm/skills/store/mock-skills-store.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-skills-store.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/skills/store/mock-skills-store.ts"],"sourcesContent":["import type {\n  SkillCatalogEntry,\n  SkillRecord,\n} from \"../contracts/skill-record.type\";\nimport type { SkillsStoreContract } from \"../contracts/skills-store.contract\";\n\n/**\n * In-memory {@link SkillsStoreContract} that ships with the package.\n *\n * Backs tests and small/ephemeral skill libraries with zero external\n * dependencies. Holds the **latest** record per skill name; `saveCandidate`\n * writes an INERT `type: \"candidate\"` (never injectable until promoted),\n * and `promote` flips it to `type: \"promoted\"` with a monotonic\n * `version + 1`.\n *\n * Construct via `new MockSkillsStore([...records])` — it is a concrete\n * test/utility store, not a factory-fronted runtime primitive, so `new`\n * is the public surface here.\n *\n * @example\n * const store = new MockSkillsStore([\n *   { name: \"scaffold\", description: \"Scaffold a form\", version: 1, body: \"...\", type: \"authored\" },\n * ]);\n * const lib = skills({ name: \"build\", sources: [{ type: \"store\", store }] });\n */\nexport class MockSkillsStore implements SkillsStoreContract {\n  /** Latest record per skill name. */\n  private readonly records = new Map<string, SkillRecord>();\n\n  public constructor(seed: SkillRecord[] = []) {\n    for (const record of seed) {\n      this.records.set(record.name, { ...record });\n    }\n  }\n\n  /**\n   * List the cheap catalog metadata for every NON-candidate skill,\n   * optionally filtered to those whose `tags` intersect `scope.tags`.\n   * Candidates are filtered out — they can never be catalogued or injected.\n   */\n  public async list(scope?: { tags?: string[] }): Promise<SkillCatalogEntry[]> {\n    const wanted = scope?.tags;\n\n    return [...this.records.values()]\n      .filter((record) => record.type !== \"candidate\")\n      .filter((record) => intersects(record.tags, wanted))\n      .map(toCatalogEntry);\n  }\n\n  /**\n   * Load the full record for `name`. When `version` is given, returns the\n   * record only if its version matches (pin); otherwise the latest. A\n   * `candidate` is never returned here — it is inert until promoted.\n   */\n  public async load(name: string, version?: number): Promise<SkillRecord | undefined> {\n    const record = this.records.get(name);\n\n    if (!record || record.type === \"candidate\") {\n      return undefined;\n    }\n\n    if (version !== undefined && record.version !== version) {\n      return undefined;\n    }\n\n    return { ...record };\n  }\n\n  /**\n   * Write an INERT candidate (`type: \"candidate\"`, `version: 0`). A\n   * candidate is filtered out of `list()` / `load()` — it can never be\n   * injected until a `review` gate promotes it.\n   */\n  public async saveCandidate(\n    record: Omit<SkillRecord, \"version\" | \"type\">,\n  ): Promise<SkillRecord> {\n    const candidate: SkillRecord = {\n      ...record,\n      version: 0,\n      type: \"candidate\",\n    };\n\n    this.records.set(candidate.name, candidate);\n\n    return { ...candidate };\n  }\n\n  /**\n   * Promote the stored candidate for `name` to a new monotonic version\n   * (`type: \"promoted\"`, `version + 1`). Throws when there is no candidate\n   * to promote — promotion of a non-existent skill is a programming error.\n   */\n  public async promote(name: string): Promise<SkillRecord> {\n    const existing = this.records.get(name);\n\n    if (!existing) {\n      throw new Error(`MockSkillsStore.promote: no skill named \"${name}\" to promote`);\n    }\n\n    const promoted: SkillRecord = {\n      ...existing,\n      version: existing.version + 1,\n      type: \"promoted\",\n    };\n\n    this.records.set(name, promoted);\n\n    return { ...promoted };\n  }\n}\n\n/** Project a full record down to its catalog entry (body omitted). */\nfunction toCatalogEntry(record: SkillRecord): SkillCatalogEntry {\n  return {\n    name: record.name,\n    description: record.description,\n    version: record.version,\n    tags: record.tags,\n    type: record.type,\n  };\n}\n\n/**\n * True when no filter tags are requested, or when the record carries at\n * least one of the requested tags. A tagless record matches only the\n * unfiltered case.\n */\nfunction intersects(recordTags: string[] | undefined, wanted: string[] | undefined): boolean {\n  if (!wanted || wanted.length === 0) {\n    return true;\n  }\n\n  if (!recordTags || recordTags.length === 0) {\n    return false;\n  }\n\n  return recordTags.some((tag) => wanted.includes(tag));\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAyBA,IAAa,kBAAb,MAA4D;CAI1D,AAAO,YAAY,OAAsB,CAAC,GAAG;iCAFlB,IAAI,IAAyB;EAGtD,KAAK,MAAM,UAAU,MACnB,KAAK,QAAQ,IAAI,OAAO,MAAM,EAAE,GAAG,OAAO,CAAC;CAE/C;;;;;;CAOA,MAAa,KAAK,OAA2D;EAC3E,MAAM,SAAS,OAAO;EAEtB,OAAO,CAAC,GAAG,KAAK,QAAQ,OAAO,CAAC,CAAC,CAC9B,QAAQ,WAAW,OAAO,SAAS,WAAW,CAAC,CAC/C,QAAQ,WAAW,WAAW,OAAO,MAAM,MAAM,CAAC,CAAC,CACnD,IAAI,cAAc;CACvB;;;;;;CAOA,MAAa,KAAK,MAAc,SAAoD;EAClF,MAAM,SAAS,KAAK,QAAQ,IAAI,IAAI;EAEpC,IAAI,CAAC,UAAU,OAAO,SAAS,aAC7B;EAGF,IAAI,YAAY,UAAa,OAAO,YAAY,SAC9C;EAGF,OAAO,EAAE,GAAG,OAAO;CACrB;;;;;;CAOA,MAAa,cACX,QACsB;EACtB,MAAM,YAAyB;GAC7B,GAAG;GACH,SAAS;GACT,MAAM;EACR;EAEA,KAAK,QAAQ,IAAI,UAAU,MAAM,SAAS;EAE1C,OAAO,EAAE,GAAG,UAAU;CACxB;;;;;;CAOA,MAAa,QAAQ,MAAoC;EACvD,MAAM,WAAW,KAAK,QAAQ,IAAI,IAAI;EAEtC,IAAI,CAAC,UACH,MAAM,IAAI,MAAM,4CAA4C,KAAK,aAAa;EAGhF,MAAM,WAAwB;GAC5B,GAAG;GACH,SAAS,SAAS,UAAU;GAC5B,MAAM;EACR;EAEA,KAAK,QAAQ,IAAI,MAAM,QAAQ;EAE/B,OAAO,EAAE,GAAG,SAAS;CACvB;AACF;;AAGA,SAAS,eAAe,QAAwC;CAC9D,OAAO;EACL,MAAM,OAAO;EACb,aAAa,OAAO;EACpB,SAAS,OAAO;EAChB,MAAM,OAAO;EACb,MAAM,OAAO;CACf;AACF;;;;;;AAOA,SAAS,WAAW,YAAkC,QAAuC;CAC3F,IAAI,CAAC,UAAU,OAAO,WAAW,GAC/B,OAAO;CAGT,IAAI,CAAC,cAAc,WAAW,WAAW,GACvC,OAAO;CAGT,OAAO,WAAW,MAAM,QAAQ,OAAO,SAAS,GAAG,CAAC;AACtD"}

package/esm/skills/store/procedural-skill-store.d.mts

@@ -0,0 +1,30 @@
+import { ProceduralMemoryConfig } from "../../contracts/memory/memory-config.type.mjs";
+import { SkillsStoreContract } from "../contracts/skills-store.contract.mjs";
+
+//#region ../@warlock.js/ai/src/skills/store/procedural-skill-store.d.ts
+/**
+ * {@link SkillsStoreContract} backed by the procedural memory tier
+ * (`ai.memory({ procedural })`). **The unification** the design calls for:
+ * "promote a proven procedural memory to a named skill" and "save a
+ * self-authored skill" are the SAME machinery — one store, two entry
+ * points. No fifth `MemoryTier` is added; the existing `"procedural"` tier
+ * is reused verbatim.
+ *
+ * - `saveCandidate` ⇒ `memory.remember({ tier: "procedural", metadata: { type: "candidate" } })`.
+ * - `promote` ⇒ re-remembers the same id with `type: "promoted"` and
+ *   `version + 1`, which the procedural tier reinforces (increments `uses`).
+ * - `list` / `load` map `memory.recall(..., { tier: "procedural" })` ⇒
+ *   `RecalledMemory[]` ⇒ `SkillCatalogEntry[]` / `SkillRecord`, filtering
+ *   out inert candidates so they can never be catalogued or injected.
+ *
+ * @example
+ * const store = proceduralSkillStore({ embedder, store: cacheDriver });
+ * const lib = skills({ name: "learned", sources: [{ type: "store", store }], review: gate });
+ */
+declare function proceduralSkillStore(config: ProceduralMemoryConfig & {
+  name?: string;
+  recallQuery?: string;
+}): SkillsStoreContract;
+//#endregion
+export { proceduralSkillStore };
+//# sourceMappingURL=procedural-skill-store.d.mts.map

package/esm/skills/store/procedural-skill-store.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"procedural-skill-store.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/skills/store/procedural-skill-store.ts"],"mappings":";;;;;;AAsDA;;;;;;;;;;AAEsB;;;;;;;iBAFN,oBAAA,CACd,MAAA,EAAQ,sBAAA;EAA2B,IAAA;EAAe,WAAA;AAAA,IACjD,mBAAmB"}

package/esm/skills/store/procedural-skill-store.mjs

@@ -0,0 +1,125 @@
+import { memory } from "../../memory/memory.mjs";
+
+//#region ../@warlock.js/ai/src/skills/store/procedural-skill-store.ts
+const RECALL_K = 1e3;
+/**
+* {@link SkillsStoreContract} backed by the procedural memory tier
+* (`ai.memory({ procedural })`). **The unification** the design calls for:
+* "promote a proven procedural memory to a named skill" and "save a
+* self-authored skill" are the SAME machinery — one store, two entry
+* points. No fifth `MemoryTier` is added; the existing `"procedural"` tier
+* is reused verbatim.
+*
+* - `saveCandidate` ⇒ `memory.remember({ tier: "procedural", metadata: { type: "candidate" } })`.
+* - `promote` ⇒ re-remembers the same id with `type: "promoted"` and
+*   `version + 1`, which the procedural tier reinforces (increments `uses`).
+* - `list` / `load` map `memory.recall(..., { tier: "procedural" })` ⇒
+*   `RecalledMemory[]` ⇒ `SkillCatalogEntry[]` / `SkillRecord`, filtering
+*   out inert candidates so they can never be catalogued or injected.
+*
+* @example
+* const store = proceduralSkillStore({ embedder, store: cacheDriver });
+* const lib = skills({ name: "learned", sources: [{ type: "store", store }], review: gate });
+*/
+function proceduralSkillStore(config) {
+	const store = memory({
+		name: config.name ?? "skills.procedural",
+		working: false,
+		defaultTier: "procedural",
+		procedural: {
+			embedder: config.embedder,
+			store: config.store,
+			namespace: config.namespace,
+			reinforcementWeight: config.reinforcementWeight
+		}
+	});
+	const recallQuery = config.recallQuery ?? "skill procedure how-to";
+	const recallAll = async () => {
+		return (await store.recall(recallQuery, {
+			tier: "procedural",
+			k: RECALL_K,
+			threshold: 0
+		})).map((hit) => ({
+			body: hit.text,
+			meta: hit.metadata
+		})).filter((entry) => Boolean(entry.meta?.skill));
+	};
+	return {
+		async list(scope) {
+			const all = await recallAll();
+			const wanted = scope?.tags;
+			return all.filter((entry) => entry.meta.type !== "candidate").filter((entry) => intersects(entry.meta.tags, wanted)).map((entry) => toCatalogEntry(entry.meta));
+		},
+		async load(name, version) {
+			const match = (await recallAll()).find((entry) => entry.meta.name === name);
+			if (!match || match.meta.type === "candidate") return;
+			if (version !== void 0 && match.meta.version !== version) return;
+			return toRecord(match.body, match.meta);
+		},
+		async saveCandidate(record) {
+			const meta = {
+				skill: true,
+				name: record.name,
+				type: "candidate",
+				description: record.description,
+				version: 0,
+				tags: record.tags
+			};
+			await store.remember({
+				id: record.name,
+				text: record.body,
+				tier: "procedural",
+				metadata: meta
+			});
+			return {
+				...record,
+				version: 0,
+				type: "candidate"
+			};
+		},
+		async promote(name) {
+			const match = (await recallAll()).find((entry) => entry.meta.name === name);
+			if (!match) throw new Error(`proceduralSkillStore.promote: no skill named "${name}" to promote`);
+			const meta = {
+				...match.meta,
+				type: "promoted",
+				version: match.meta.version + 1
+			};
+			await store.remember({
+				id: name,
+				text: match.body,
+				tier: "procedural",
+				metadata: meta
+			});
+			return toRecord(match.body, meta);
+		}
+	};
+}
+function toCatalogEntry(meta) {
+	return {
+		name: meta.name,
+		description: meta.description,
+		version: meta.version,
+		tags: meta.tags,
+		type: meta.type
+	};
+}
+function toRecord(body, meta) {
+	return {
+		name: meta.name,
+		description: meta.description,
+		version: meta.version,
+		body,
+		tags: meta.tags,
+		type: meta.type
+	};
+}
+function intersects(recordTags, wanted) {
+	if (!wanted || wanted.length === 0) return true;
+	if (!recordTags || recordTags.length === 0) return false;
+	return recordTags.some((tag) => wanted.includes(tag));
+}
+
+//#endregion
+export { proceduralSkillStore };
+//# sourceMappingURL=procedural-skill-store.mjs.map

package/esm/skills/store/procedural-skill-store.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"procedural-skill-store.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/skills/store/procedural-skill-store.ts"],"sourcesContent":["import type { MemoryContract } from \"../../contracts/memory/memory.contract\";\nimport type { ProceduralMemoryConfig } from \"../../contracts/memory/memory-config.type\";\nimport { memory } from \"../../memory\";\nimport type {\n  SkillCatalogEntry,\n  SkillRecord,\n} from \"../contracts/skill-record.type\";\nimport type { SkillsStoreContract } from \"../contracts/skills-store.contract\";\n\n/**\n * Metadata a procedural memory carries to round-trip a skill. `recall()`\n * surfaces `metadata` verbatim, so the skill's identity (name, version,\n * provenance, description, tags) rides here while the procedure body lives\n * in the memory's `text`.\n */\ntype ProceduralSkillMeta = {\n  /** Marks the record as a skill (vs. a plain procedure) so `list` can scope. */\n  skill: true;\n  /** Skill name — the catalog key (also the memory `id`). */\n  name: string;\n  /** Provenance flag round-tripped onto the SkillRecord. */\n  type: \"candidate\" | \"promoted\";\n  /** Catalog line. */\n  description: string;\n  /** Monotonic version — bumped on promote. */\n  version: number;\n  /** Optional scope tags. */\n  tags?: string[];\n};\n\n/** A recalled skill entry — the procedure body plus its skill metadata. */\ntype ProceduralSkillEntry = { body: string; meta: ProceduralSkillMeta };\n\nconst RECALL_K = 1000;\n\n/**\n * {@link SkillsStoreContract} backed by the procedural memory tier\n * (`ai.memory({ procedural })`). **The unification** the design calls for:\n * \"promote a proven procedural memory to a named skill\" and \"save a\n * self-authored skill\" are the SAME machinery — one store, two entry\n * points. No fifth `MemoryTier` is added; the existing `\"procedural\"` tier\n * is reused verbatim.\n *\n * - `saveCandidate` ⇒ `memory.remember({ tier: \"procedural\", metadata: { type: \"candidate\" } })`.\n * - `promote` ⇒ re-remembers the same id with `type: \"promoted\"` and\n *   `version + 1`, which the procedural tier reinforces (increments `uses`).\n * - `list` / `load` map `memory.recall(..., { tier: \"procedural\" })` ⇒\n *   `RecalledMemory[]` ⇒ `SkillCatalogEntry[]` / `SkillRecord`, filtering\n *   out inert candidates so they can never be catalogued or injected.\n *\n * @example\n * const store = proceduralSkillStore({ embedder, store: cacheDriver });\n * const lib = skills({ name: \"learned\", sources: [{ type: \"store\", store }], review: gate });\n */\nexport function proceduralSkillStore(\n  config: ProceduralMemoryConfig & { name?: string; recallQuery?: string },\n): SkillsStoreContract {\n  const store: MemoryContract = memory({\n    name: config.name ?? \"skills.procedural\",\n    working: false,\n    defaultTier: \"procedural\",\n    procedural: {\n      embedder: config.embedder,\n      store: config.store,\n      namespace: config.namespace,\n      reinforcementWeight: config.reinforcementWeight,\n    },\n  });\n\n  // The procedural tier recalls by similarity to a query; for a full\n  // catalog listing we recall against a broad seed with a large `k` and a\n  // zero floor so every stored skill comes back.\n  const recallQuery = config.recallQuery ?? \"skill procedure how-to\";\n\n  const recallAll = async (): Promise<ProceduralSkillEntry[]> => {\n    const hits = await store.recall(recallQuery, {\n      tier: \"procedural\",\n      k: RECALL_K,\n      threshold: 0,\n    });\n\n    return hits\n      .map((hit) => ({ body: hit.text, meta: hit.metadata as ProceduralSkillMeta | undefined }))\n      .filter((entry): entry is ProceduralSkillEntry => Boolean(entry.meta?.skill));\n  };\n\n  return {\n    async list(scope?: { tags?: string[] }): Promise<SkillCatalogEntry[]> {\n      const all = await recallAll();\n      const wanted = scope?.tags;\n\n      return all\n        .filter((entry) => entry.meta.type !== \"candidate\")\n        .filter((entry) => intersects(entry.meta.tags, wanted))\n        .map((entry) => toCatalogEntry(entry.meta));\n    },\n    async load(name: string, version?: number): Promise<SkillRecord | undefined> {\n      const all = await recallAll();\n      const match = all.find((entry) => entry.meta.name === name);\n\n      if (!match || match.meta.type === \"candidate\") {\n        return undefined;\n      }\n\n      if (version !== undefined && match.meta.version !== version) {\n        return undefined;\n      }\n\n      return toRecord(match.body, match.meta);\n    },\n    async saveCandidate(record: Omit<SkillRecord, \"version\" | \"type\">): Promise<SkillRecord> {\n      const meta: ProceduralSkillMeta = {\n        skill: true,\n        name: record.name,\n        type: \"candidate\",\n        description: record.description,\n        version: 0,\n        tags: record.tags,\n      };\n\n      await store.remember({\n        id: record.name,\n        text: record.body,\n        tier: \"procedural\",\n        metadata: meta,\n      });\n\n      return { ...record, version: 0, type: \"candidate\" };\n    },\n    async promote(name: string): Promise<SkillRecord> {\n      const all = await recallAll();\n      const match = all.find((entry) => entry.meta.name === name);\n\n      if (!match) {\n        throw new Error(`proceduralSkillStore.promote: no skill named \"${name}\" to promote`);\n      }\n\n      const meta: ProceduralSkillMeta = {\n        ...match.meta,\n        type: \"promoted\",\n        version: match.meta.version + 1,\n      };\n\n      // Re-remembering the same id reinforces (uses++) AND flips the\n      // metadata — the procedural tier's reinforcement IS the promotion.\n      await store.remember({\n        id: name,\n        text: match.body,\n        tier: \"procedural\",\n        metadata: meta,\n      });\n\n      return toRecord(match.body, meta);\n    },\n  };\n}\n\nfunction toCatalogEntry(meta: ProceduralSkillMeta): SkillCatalogEntry {\n  return {\n    name: meta.name,\n    description: meta.description,\n    version: meta.version,\n    tags: meta.tags,\n    type: meta.type,\n  };\n}\n\nfunction toRecord(body: string, meta: ProceduralSkillMeta): SkillRecord {\n  return {\n    name: meta.name,\n    description: meta.description,\n    version: meta.version,\n    body,\n    tags: meta.tags,\n    type: meta.type,\n  };\n}\n\nfunction intersects(recordTags: string[] | undefined, wanted: string[] | undefined): boolean {\n  if (!wanted || wanted.length === 0) {\n    return true;\n  }\n\n  if (!recordTags || recordTags.length === 0) {\n    return false;\n  }\n\n  return recordTags.some((tag) => wanted.includes(tag));\n}\n"],"mappings":";;;AAiCA,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;AAqBjB,SAAgB,qBACd,QACqB;CACrB,MAAM,QAAwB,OAAO;EACnC,MAAM,OAAO,QAAQ;EACrB,SAAS;EACT,aAAa;EACb,YAAY;GACV,UAAU,OAAO;GACjB,OAAO,OAAO;GACd,WAAW,OAAO;GAClB,qBAAqB,OAAO;EAC9B;CACF,CAAC;CAKD,MAAM,cAAc,OAAO,eAAe;CAE1C,MAAM,YAAY,YAA6C;EAO7D,QAAO,MANY,MAAM,OAAO,aAAa;GAC3C,MAAM;GACN,GAAG;GACH,WAAW;EACb,CAAC,EAEU,CACR,KAAK,SAAS;GAAE,MAAM,IAAI;GAAM,MAAM,IAAI;EAA4C,EAAE,CAAC,CACzF,QAAQ,UAAyC,QAAQ,MAAM,MAAM,KAAK,CAAC;CAChF;CAEA,OAAO;EACL,MAAM,KAAK,OAA2D;GACpE,MAAM,MAAM,MAAM,UAAU;GAC5B,MAAM,SAAS,OAAO;GAEtB,OAAO,IACJ,QAAQ,UAAU,MAAM,KAAK,SAAS,WAAW,CAAC,CAClD,QAAQ,UAAU,WAAW,MAAM,KAAK,MAAM,MAAM,CAAC,CAAC,CACtD,KAAK,UAAU,eAAe,MAAM,IAAI,CAAC;EAC9C;EACA,MAAM,KAAK,MAAc,SAAoD;GAE3E,MAAM,SAAQ,MADI,UAAU,EACX,CAAC,MAAM,UAAU,MAAM,KAAK,SAAS,IAAI;GAE1D,IAAI,CAAC,SAAS,MAAM,KAAK,SAAS,aAChC;GAGF,IAAI,YAAY,UAAa,MAAM,KAAK,YAAY,SAClD;GAGF,OAAO,SAAS,MAAM,MAAM,MAAM,IAAI;EACxC;EACA,MAAM,cAAc,QAAqE;GACvF,MAAM,OAA4B;IAChC,OAAO;IACP,MAAM,OAAO;IACb,MAAM;IACN,aAAa,OAAO;IACpB,SAAS;IACT,MAAM,OAAO;GACf;GAEA,MAAM,MAAM,SAAS;IACnB,IAAI,OAAO;IACX,MAAM,OAAO;IACb,MAAM;IACN,UAAU;GACZ,CAAC;GAED,OAAO;IAAE,GAAG;IAAQ,SAAS;IAAG,MAAM;GAAY;EACpD;EACA,MAAM,QAAQ,MAAoC;GAEhD,MAAM,SAAQ,MADI,UAAU,EACX,CAAC,MAAM,UAAU,MAAM,KAAK,SAAS,IAAI;GAE1D,IAAI,CAAC,OACH,MAAM,IAAI,MAAM,iDAAiD,KAAK,aAAa;GAGrF,MAAM,OAA4B;IAChC,GAAG,MAAM;IACT,MAAM;IACN,SAAS,MAAM,KAAK,UAAU;GAChC;GAIA,MAAM,MAAM,SAAS;IACnB,IAAI;IACJ,MAAM,MAAM;IACZ,MAAM;IACN,UAAU;GACZ,CAAC;GAED,OAAO,SAAS,MAAM,MAAM,IAAI;EAClC;CACF;AACF;AAEA,SAAS,eAAe,MAA8C;CACpE,OAAO;EACL,MAAM,KAAK;EACX,aAAa,KAAK;EAClB,SAAS,KAAK;EACd,MAAM,KAAK;EACX,MAAM,KAAK;CACb;AACF;AAEA,SAAS,SAAS,MAAc,MAAwC;CACtE,OAAO;EACL,MAAM,KAAK;EACX,aAAa,KAAK;EAClB,SAAS,KAAK;EACd;EACA,MAAM,KAAK;EACX,MAAM,KAAK;CACb;AACF;AAEA,SAAS,WAAW,YAAkC,QAAuC;CAC3F,IAAI,CAAC,UAAU,OAAO,WAAW,GAC/B,OAAO;CAGT,IAAI,CAAC,cAAc,WAAW,WAAW,GACvC,OAAO;CAGT,OAAO,WAAW,MAAM,QAAQ,OAAO,SAAS,GAAG,CAAC;AACtD"}

package/esm/speech/index.mjs

@@ -0,0 +1,3 @@
+import { speech } from "./speech.mjs";
+
+export {  };

package/esm/speech/speech.d.mts

@@ -0,0 +1,65 @@
+import { BaseReport } from "../contracts/result/base-report.type.mjs";
+import { ExecuteResult } from "../contracts/result/execute-result.type.mjs";
+import { FlowObserveOption } from "../observe/resolve-observers.mjs";
+import { GeneratedAudio, SpeechModelContract } from "../contracts/speech-model.contract.mjs";
+
+//#region ../@warlock.js/ai/src/speech/speech.d.ts
+/** Parameters for {@link speech}. `model` comes from `sdk.speech({ name })`. */
+type SpeechParams = {
+  /** The TTS model to synthesize with. */model: SpeechModelContract; /** The text to speak. */
+  text: string; /** Voice id/name; overrides the model's default voice. */
+  voice?: string; /** Output container (`"mp3"` / `"opus"` / `"aac"` / `"flac"` / `"wav"` / `"pcm"`). */
+  format?: string; /** Playback speed multiplier. */
+  speed?: number; /** Extra tone/delivery steering (model-dependent). */
+  instructions?: string; /** Cancellation handle. */
+  signal?: AbortSignal; /** Observability routing — same `observe` seam as agents. */
+  observe?: FlowObserveOption; /** Groups this call into a session for flat cost/trace queries. */
+  sessionId?: string; /** Report node name (defaults to `"speech"`). */
+  name?: string; /** Provider-specific options forwarded verbatim to the adapter. */
+  options?: Record<string, unknown>;
+};
+/** Success payload of a {@link speech} run. */
+type SpeechData = {
+  /** The synthesized audio, normalized to the discriminated shape. */audio: GeneratedAudio;
+};
+/** The report node a {@link speech} run produces (`type: "speech"`). */
+type SpeechReport = BaseReport & {
+  type: "speech"; /** Identity of the TTS model this run used. */
+  model: {
+    name: string;
+    provider: string;
+  }; /** Number of input characters synthesized (0 on failure). */
+  characters: number;
+};
+/** Result envelope of {@link speech} — the uniform `{ data, error, usage, report }`. */
+type SpeechResult = ExecuteResult<SpeechData> & {
+  type: "speech";
+  report: SpeechReport;
+};
+/**
+ * Synthesize speech from text — the text-to-speech verb of the
+ * output-modality track (Theme I), sibling to `ai.image()`. Wraps a
+ * {@link SpeechModelContract} (from `openai.speech(...)`) in the
+ * framework's uniform result contract:
+ *
+ * - **Never throws.** Provider failures surface as a typed `AIError` on
+ *   `result.error`; `result.data` is then `undefined`.
+ * - **Cost-truth.** `result.usage.cost` is filled per-character
+ *   (`tts-1`) or per-token (`gpt-4o-mini-tts`), folding into the same
+ *   `Usage.cost` rollup as text.
+ * - **Observable.** The completed {@link SpeechReport} routes to any
+ *   registered `Observer` (panoptic, OTel, …) via the `observe` seam.
+ *
+ * @example
+ * const openai = new OpenAISDK({ apiKey });
+ * const { data, error } = await ai.speech({
+ *   model: openai.speech({ name: "tts-1", voice: "alloy" }),
+ *   text: "Your order has shipped.",
+ *   format: "mp3",
+ * });
+ * if (!error) await fs.writeFile("ship.mp3", Buffer.from(data.audio.base64, "base64"));
+ */
+declare function speech(params: SpeechParams): Promise<SpeechResult>;
+//#endregion
+export { SpeechData, SpeechParams, SpeechReport, SpeechResult, speech };
+//# sourceMappingURL=speech.d.mts.map

package/esm/speech/speech.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"speech.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/speech/speech.ts"],"mappings":";;;;;;;KAmBY,YAAA;EAAA,wCAEV,KAAA,EAAO,mBAAA;EAEP,IAAA,UAUS;EART,KAAA,WAgBU;EAdV,MAAA,WAcgB;EAZhB,KAAA,WARO;EAUP,YAAA,WANA;EAQA,MAAA,GAAS,WAAA,EAJT;EAMA,OAAA,GAAU,iBAAA,EAFV;EAIA,SAAA,WAFA;EAIA,IAAA,WAFA;EAIA,OAAA,GAAU,MAAA;AAAA;;KAIA,UAAA;EAJM,oEAMhB,KAAA,EAAO,cAAc;AAAA;;KAIX,YAAA,GAAe,UAAU;EACnC,IAAA,YADU;EAGV,KAAA;IAAS,IAAA;IAAc,QAAA;EAAA,GAFvB;EAIA,UAAA;AAAA;;KAIU,YAAA,GAAe,aAAA,CAAc,UAAA;EACvC,IAAA;EACA,MAAA,EAAQ,YAAA;AAAA;;;;;;;;;;;;;;AAAY;AA0BtB;;;;;;;;;iBAAsB,MAAA,CAAO,MAAA,EAAQ,YAAA,GAAe,OAAA,CAAQ,YAAA"}