@ambitresearch/genie 1.3.1

package/dist/sync/anchor.js

@@ -0,0 +1,210 @@
+/**
+ * M3-06 (DRO-262) — genie's own `.genie/sync.json` verification anchor.
+ *
+ * `.genie/sync.json` is the LAST file the atomic sync sequence writes: it
+ * records the source/render hashes and the
+ * `@genie`-validated component list for whatever the sync just wrote, so the
+ * *next* sync can diff against it and repair a half-completed prior run. A
+ * mid-plan failure must leave this file unwritten (or stale) — never
+ * partially written — which is why {@link writeAnchor} always does a
+ * temp-file + rename commit (AC7), the same durability pattern
+ * `store/local.ts`'s `stageAndCommit` and `plans/index.ts`'s plan snapshots
+ * use elsewhere in this codebase.
+ *
+ * This is genie's **native** anchor shape — NOT the Anthropic `_ds_sync.json`
+ * interop shape (CLAUDE.md hard rule 1 / AGENTS.md hard rule 1). An interop
+ * adapter may one day map this to `_ds_sync.json`; that mapping is out of
+ * scope here.
+ *
+ * ── Coordination with M3-05 (DRO-261) ───────────────────────────────────────
+ * The 5-step atomic orchestrator (M3-05) calls {@link writeAnchor} as its
+ * Step 5 (last write). That issue was still unbuilt on `main` as of this PR,
+ * so {@link PlanResult} is this module's own minimal seam — "the set of
+ * writes a sync touched, plus which components passed validation" — rather
+ * than importing a type from a module that doesn't exist yet. Whichever of
+ * M3-05 / M3-06 lands second adapts to the other's shape; the signature
+ * `writeAnchor(projectRoot, planResult)` itself (AC1) is the stable contract
+ * both issues were told to converge on.
+ */
+import { mkdir, mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { sriSha256 } from "../store/kit-files.js";
+// ─── Public shape (AC2) ──────────────────────────────────────────────────────
+/** Kit-root-relative path of genie's verification anchor (D-C). */
+export const ANCHOR_PATH = ".genie/sync.json";
+/** Env var overriding {@link Anchor.by} (AC6) — for forks of genie. */
+export const GENIE_BY_ENV = "GENIE_BY";
+/** Default {@link Anchor.by} value when `GENIE_BY` is unset (AC6). */
+export const DEFAULT_BY = "genie";
+/**
+ * Source-file extensions that count toward {@link Anchor.sourceHashes} (AC3).
+ * The issue's literal AC3 text says ".tsx/.jsx", written when React was the
+ * only shipped framework; Vue landed as a first-class framework in M2-08
+ * (merged to `main` the day before this PR) with `.vue` as its canonical
+ * single-file-component source (`framework/vue.ts`'s `renderSource` →
+ * `<Name>.vue`). Omitting `.vue` here would leave every Vue component's
+ * source invisible to the anchor's drift/tamper detection (RFC §10 T-05) —
+ * the exact failure mode this file exists to prevent — so the extension list
+ * covers both shipped component-source frameworks rather than only the one
+ * named in the issue's illustrative example.
+ *
+ * `.html` is deliberately **not** in this list even though vanilla HTML is now a
+ * first-class framework (`HtmlAdapter.renderSource` → `<Name>.html`, DRO-617).
+ * For a vanilla-HTML component the source file *is* the browser-ready
+ * `<Name>.html` preview — so it is already hash-covered by {@link Anchor.renderHashes}
+ * (which hashes every `.html` write, AC4), giving the anchor's drift/tamper
+ * detection full coverage of that source with no gap. Adding `.html` here instead
+ * would double-count it *and* mislabel every React/Vue `<Name>.html` — which is a
+ * *rendered* preview, not source — as `sourceHashes`, so the extension split stays
+ * "compiled-source suffixes → sourceHashes, `.html` → renderHashes" and HTML's
+ * source rides the render side by construction.
+ */
+const SOURCE_EXTENSIONS = [".tsx", ".jsx", ".vue"];
+/** Thrown by {@link readAnchor} when `.genie/sync.json` exists but is not valid genie anchor JSON. */
+export class AnchorParseError extends Error {
+    projectRoot;
+    reason;
+    constructor(projectRoot, reason) {
+        super(`Anchor at "${projectRoot}/${ANCHOR_PATH}" is malformed: ${reason}`);
+        this.projectRoot = projectRoot;
+        this.reason = reason;
+        this.name = "AnchorParseError";
+    }
+}
+// ─── Schema (validated on read; see AnchorParseError above) ─────────────────
+const anchorSchema = z.object({
+    version: z.literal(1),
+    writtenAt: z.string(),
+    by: z.string(),
+    sourceHashes: z.record(z.string(), z.string()),
+    renderHashes: z.record(z.string(), z.string()),
+    verified: z.array(z.string()),
+});
+// ─── writeAnchor (AC1, AC3–AC7) ──────────────────────────────────────────────
+/**
+ * Compute and atomically write `${projectRoot}/.genie/sync.json` (AC1).
+ *
+ * - `sourceHashes` covers every {@link SOURCE_EXTENSIONS} path in
+ *   `planResult.writes` (AC3 — `.tsx`/`.jsx`, plus `.vue` for the shipped Vue
+ *   framework); `renderHashes` covers every `.html` path (AC4). A path with
+ *   none of those extensions (e.g. `meta.json`) appears in neither map — this
+ *   anchor is scoped to source + render provenance, not a general write log.
+ * - `verified` is `planResult.verified` verbatim (AC5) — the caller (the
+ *   M3-05 orchestrator, or a direct test) is the one that ran the M3-04
+ *   validator and knows which `<group>/<Name>` ids passed.
+ * - `by` is {@link DEFAULT_BY} unless overridden by `env.GENIE_BY` (AC6).
+ * - The write is atomic (AC7): content lands in a temp file staged under
+ *   `<projectRoot>/.genie-tmp/` — a different directory from the `.genie/`
+ *   destination, but the same filesystem/mount, which is the one guarantee
+ *   POSIX `rename()` actually needs — then renamed over the destination. A
+ *   crash between the temp write and the rename leaves the PRIOR anchor (or
+ *   no anchor) intact — never a half-written one.
+ *
+ * @param env Injectable environment (defaults to `process.env`), so tests can
+ *   assert the `GENIE_BY` override without mutating global state — the same
+ *   pattern `write_files.ts`'s `resolveByteCap(env)` uses for
+ *   `GENIE_WRITE_BYTE_CAP`.
+ */
+export async function writeAnchor(projectRoot, planResult, env = process.env) {
+    const anchor = {
+        version: 1,
+        writtenAt: new Date().toISOString(),
+        by: env[GENIE_BY_ENV] ?? DEFAULT_BY,
+        sourceHashes: hashByExtension(planResult.writes, SOURCE_EXTENSIONS),
+        renderHashes: hashByExtension(planResult.writes, [".html"]),
+        verified: [...planResult.verified],
+    };
+    const destPath = join(projectRoot, ANCHOR_PATH);
+    await mkdir(join(projectRoot, ".genie"), { recursive: true });
+    // Stage under `<projectRoot>/.genie-tmp/` (NOT os.tmpdir()) so the final
+    // rename stays on the same filesystem — mirrors the load-bearing reasoning
+    // in store/local.ts's stageAndCommit (a kit dir and /tmp are commonly
+    // different mounts, and rename() is only atomic within one filesystem; it
+    // does NOT require source and destination to share a directory). Reusing
+    // `.genie-tmp` (rather than a new `.genie/`-nested
+    // staging dir) matters beyond consistency: `store/kit-files.ts`'s
+    // `DEFAULT_IGNORED_SEGMENTS` already excludes `.genie-tmp` from every kit
+    // listing, so a `list_files` call landing mid-write never surfaces this
+    // staging directory — the same guarantee `write_files`' own commit already
+    // gets from that shared exclusion.
+    const genieTmpRoot = join(projectRoot, ".genie-tmp");
+    await mkdir(genieTmpRoot, { recursive: true });
+    const stagingRoot = await mkdtemp(join(genieTmpRoot, "sync-"));
+    try {
+        const stagedPath = join(stagingRoot, "sync.json");
+        await writeFile(stagedPath, JSON.stringify(anchor, null, 2), "utf-8");
+        await rename(stagedPath, destPath);
+    }
+    finally {
+        await rm(stagingRoot, { recursive: true, force: true });
+    }
+}
+/**
+ * Build a `path -> sha256-<base64>` map over every `planResult.writes` entry
+ * whose path ends in one of `extensions` (AC3/AC4). Hashes the exact bytes
+ * handed in (`sriSha256` accepts either a `Buffer` or a `string`), never a
+ * fresh disk read — the anchor vouches for what THIS sync wrote, not
+ * whatever happens to be on disk afterward.
+ */
+function hashByExtension(writes, extensions) {
+    const result = {};
+    for (const { path, content } of writes) {
+        if (extensions.some((ext) => path.endsWith(ext))) {
+            result[path] = sriSha256(content);
+        }
+    }
+    return result;
+}
+// ─── readAnchor (AC1, AC8) ────────────────────────────────────────────────────
+/**
+ * Read + parse `${projectRoot}/.genie/sync.json` (AC1).
+ *
+ * - Returns `null` — never throws — when the file (or the whole `.genie`
+ *   dir, or `projectRoot` itself) does not exist (AC8): a fresh kit with no
+ *   prior sync is a normal, expected state, not an error.
+ * - Throws {@link AnchorParseError} when the file EXISTS but is not valid
+ *   JSON, or is valid JSON that doesn't match the {@link Anchor} shape
+ *   (including a `version` other than the literal `1`). This is
+ *   deliberately NOT folded into the `null` case: `null` means "no anchor
+ *   yet, that's fine"; a corrupt-but-present anchor is a real operability
+ *   problem for a file whose entire purpose is verification (RFC §10 T-05
+ *   flags anchor tampering) and must surface rather than silently
+ *   masquerade as "nothing to verify yet" — the same reasoning
+ *   `store/manifest.ts`'s `ManifestParseError` already applies to
+ *   `manifest.json`.
+ */
+export async function readAnchor(projectRoot) {
+    const destPath = join(projectRoot, ANCHOR_PATH);
+    let raw;
+    try {
+        raw = await readFile(destPath, "utf-8");
+    }
+    catch (error) {
+        if (isMissingPathError(error))
+            return null;
+        throw error;
+    }
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new AnchorParseError(projectRoot, describeError(error, "invalid JSON"));
+    }
+    const parsed = anchorSchema.safeParse(json);
+    if (!parsed.success) {
+        throw new AnchorParseError(projectRoot, parsed.error.issues[0]?.message ?? "schema mismatch");
+    }
+    return parsed.data;
+}
+/** ENOENT (missing file) and ENOTDIR (a parent component is a file) both mean "not there". */
+function isMissingPathError(error) {
+    return (error instanceof Error &&
+        "code" in error &&
+        (error.code === "ENOENT" || error.code === "ENOTDIR"));
+}
+function describeError(error, fallback) {
+    return error instanceof Error ? error.message : fallback;
+}
+//# sourceMappingURL=anchor.js.map

package/dist/sync/anchor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchor.js","sourceRoot":"","sources":["../../src/sync/anchor.ts"],"names":[],"mappings":"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"}

package/dist/sync/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Public re-export barrel for genie's sync layer:
+ *   - M3-06 (`anchor.ts`) — the `.genie/sync.json` verification anchor.
+ *   - M3-05 (`orchestrator.ts`) — the 5-step atomic write-sequence orchestrator
+ *     that writes that anchor last.
+ *
+ * Mirrors the existing `store/index.ts` / `validate/index.ts` barrel pattern:
+ * downstream consumers (the sync-flow caller wiring generation → commit, and any
+ * future consumer outside this directory) import from `../sync/index.js` rather
+ * than reaching into `./anchor.js` / `./orchestrator.js` directly, so the
+ * module's internal file layout can change without breaking callers.
+ */
+export { ANCHOR_PATH, GENIE_BY_ENV, DEFAULT_BY, writeAnchor, readAnchor, AnchorParseError, type Anchor, type PlanResult, } from "./anchor.js";
+export { RECOMPILE_SENTINEL_PATH, RECOMPILE_SENTINEL_BODY, runAtomicSync, detectResumeStep, type StepNumber, type StepEvent, type SyncResult, type WriteInput, type SyncArgs, type SyncDeps, } from "./orchestrator.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/sync/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sync/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EACL,WAAW,EACX,YAAY,EACZ,UAAU,EACV,WAAW,EACX,UAAU,EACV,gBAAgB,EAChB,KAAK,MAAM,EACX,KAAK,UAAU,GAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,aAAa,EACb,gBAAgB,EAChB,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,QAAQ,GACd,MAAM,mBAAmB,CAAC"}

package/dist/sync/index.js

@@ -0,0 +1,15 @@
+/**
+ * Public re-export barrel for genie's sync layer:
+ *   - M3-06 (`anchor.ts`) — the `.genie/sync.json` verification anchor.
+ *   - M3-05 (`orchestrator.ts`) — the 5-step atomic write-sequence orchestrator
+ *     that writes that anchor last.
+ *
+ * Mirrors the existing `store/index.ts` / `validate/index.ts` barrel pattern:
+ * downstream consumers (the sync-flow caller wiring generation → commit, and any
+ * future consumer outside this directory) import from `../sync/index.js` rather
+ * than reaching into `./anchor.js` / `./orchestrator.js` directly, so the
+ * module's internal file layout can change without breaking callers.
+ */
+export { ANCHOR_PATH, GENIE_BY_ENV, DEFAULT_BY, writeAnchor, readAnchor, AnchorParseError, } from "./anchor.js";
+export { RECOMPILE_SENTINEL_PATH, RECOMPILE_SENTINEL_BODY, runAtomicSync, detectResumeStep, } from "./orchestrator.js";
+//# sourceMappingURL=index.js.map

package/dist/sync/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sync/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EACL,WAAW,EACX,YAAY,EACZ,UAAU,EACV,WAAW,EACX,UAAU,EACV,gBAAgB,GAGjB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,aAAa,EACb,gBAAgB,GAOjB,MAAM,mBAAmB,CAAC"}

package/dist/sync/orchestrator.d.ts

@@ -0,0 +1,160 @@
+/**
+ * M3-05 (DRO-261) — genie's 5-step atomic write-sequence orchestrator.
+ *
+ * `runAtomicSync` sequences one sync commit as five ordered, stop-on-first-
+ * failure steps. The atomic write sequence is load-bearing and unchanged in
+ * shape:
+ *
+ *   1. Write the `.genie/recompile` sentinel FIRST, to fence the manifest/copy
+ *      machinery — a consumer that sees the sentinel knows a sync is mid-flight
+ *      and the tree may be inconsistent until the anchor lands.
+ *   2. Apply every content write, chunked into batches of ≤ 256 per
+ *      `write_files` call (the M1-08 `MAX_FILES_PER_CALL` ceiling — a 257-file
+ *      call would be rejected as `TooManyFilesError`).
+ *   3. Apply every delete via one `delete_files` call. A path that is
+ *      authorized-but-absent is NOT a failure (M1-09 AC5 returns it in
+ *      `notFoundPaths`) — only a real error (out-of-plan path, unlink failure)
+ *      trips stop-on-first-failure.
+ *   4. RE-ARM the sentinel (write it again), so it still fences the tree after
+ *      the writes/deletes landed and right up until the anchor is committed.
+ *   5. Write `.genie/sync.json` LAST, via M3-06's {@link writeAnchor}. It is the
+ *      completion proof: its presence means every prior step succeeded.
+ *
+ * ── Why the anchor is last (AC7) ─────────────────────────────────────────────
+ * A mid-plan failure (steps 1–4) returns before step 5, so `.genie/sync.json`
+ * is never written for an incomplete sync. The NEXT sync sees "sentinel present,
+ * anchor absent" ({@link detectResumeStep} → 2) and knows the tree is a
+ * half-write to repair from step 2 — rather than trusting a stale anchor that
+ * would mask the incomplete state. This is the whole reason the write order is
+ * load-bearing.
+ *
+ * ── Native surface (CLAUDE.md hard rule 1) ───────────────────────────────────
+ * `.genie/recompile` and `.genie/sync.json` are genie-NATIVE artifacts. They are
+ * written fs-native to `projectRoot` (NOT through the plan-gated `write_files`
+ * verb — they would never match a user plan's `writes` globs, and they are
+ * genie's own bookkeeping, not user content). They must NOT be renamed to the
+ * Anthropic `_ds_recompile` / `_ds_sync.json` interop shapes; an interop bridge
+ * that maps them is a separate, opt-in concern.
+ *
+ * ── Composition (Kiln's plan, DRO-696) ───────────────────────────────────────
+ * Steps 2–3 call the in-process `writeFiles` / `deleteFiles` CORE functions
+ * directly (not over the MCP transport) — the same way `conjure_screen.ts`
+ * composes tool-layer logic — so the orchestrator reuses their full plan-gating,
+ * atomicity, and rollback contracts without re-implementing any of it.
+ */
+import type { KitStore } from "../store/interface.js";
+/** Kit-root-relative path of genie's recompile fence sentinel (native surface). */
+export declare const RECOMPILE_SENTINEL_PATH = ".genie/recompile";
+/**
+ * The exact sentinel body (AC2). genie's native `{"by":"genie"}` marker — NOT
+ * the Anthropic `_ds_recompile` interop shape (CLAUDE.md hard rule 1). Kept as
+ * a compact single-line literal so a byte-for-byte assertion is trivial and the
+ * re-arm in step 4 reproduces it exactly.
+ */
+export declare const RECOMPILE_SENTINEL_BODY = "{\"by\":\"genie\"}";
+/** The five ordered steps of one atomic sync. */
+export type StepNumber = 1 | 2 | 3 | 4 | 5;
+/**
+ * One observability event per attempted step (AC9): which `step`, whether it
+ * succeeded (`ok`), and how long it took (`ms`, wall-clock via
+ * `performance.now()`). Emitted for EVERY attempted step — including the one
+ * that failed — and never for a step the sequence stopped short of.
+ */
+export interface StepEvent {
+    step: StepNumber;
+    ok: boolean;
+    ms: number;
+}
+/**
+ * Result of one `runAtomicSync` call (AC1, AC7).
+ *   - Success — every step landed; `.genie/sync.json` was written last.
+ *   - Failure — a step BEFORE the anchor failed; `.genie/sync.json` was NOT
+ *     written. `failedStep` is the 1-based step that threw, `error` is the
+ *     underlying cause, and `events` records every step attempted up to and
+ *     including the failure.
+ */
+export type SyncResult = {
+    ok: true;
+    events: StepEvent[];
+} | {
+    ok: false;
+    failedStep: StepNumber;
+    error: Error;
+    events: StepEvent[];
+};
+/**
+ * One content write for the sync. Structurally the same as `write_files`'
+ * per-file input, so the batch passes straight through to the plan-gated
+ * `writeFiles` core fn: exactly one of `data` (inline bytes — the common
+ * case for genie-generated component source/render) or `localPath` (a source
+ * path resolved against the plan's `localDir`) must be set.
+ */
+export interface WriteInput {
+    path: string;
+    data?: string;
+    encoding?: "utf-8" | "base64";
+    localPath?: string;
+    mimeType?: string;
+}
+/**
+ * Arguments to {@link runAtomicSync} (AC1). The issue's literal signature is
+ * `{ planId, writes, deletes }`; `verified` is threaded through additively so
+ * step 5's anchor can carry the `<group>/<Name>` ids that passed the M3-04
+ * validator within THIS sync (M3-06's `PlanResult.verified`). It is optional and
+ * defaults to `[]`, so the literal AC1 shape still type-checks and runs — the
+ * two issues were told to converge on each other's shape (see `anchor.ts`'s
+ * module-doc coordination note), and this is that convergence.
+ */
+export interface SyncArgs {
+    planId: string;
+    writes: WriteInput[];
+    deletes: string[];
+    /** `<group>/<Name>` ids that passed validation this sync (M3-06 anchor). */
+    verified?: string[];
+}
+/**
+ * Injected collaborators (mirrors `conjure_screen.ts`'s `ConjureScreenDeps`).
+ *
+ * - `store` — the kit backend steps 2–3 write/delete through (LocalFs or
+ *   GitHost), behind the same `KitStore` seam every M1 verb uses.
+ * - `projectRoot` — the on-disk kit root the native sentinel + anchor are
+ *   written to. CONTRACT: this MUST be the same directory the injected `store`
+ *   resolves the plan's `kitId` to (for `LocalFsKitStore`,
+ *   `<baseDir>/<kitId>`), so the fs-native sentinel/anchor and the
+ *   store-written content land in ONE tree. The sync-flow caller computes it;
+ *   the orchestrator takes it explicitly, matching `writeAnchor`'s own
+ *   `projectRoot`-first signature (M3-06).
+ */
+export interface SyncDeps {
+    store: KitStore;
+    projectRoot: string;
+}
+/**
+ * Run the 5-step atomic sync sequence. Stops on the first failing step (AC7),
+ * leaving `.genie/sync.json` unwritten so the next sync's diff repairs the
+ * half-write; a not-found delete inside step 3 is NOT a failure (AC4). Every
+ * attempted step emits a {@link StepEvent} (AC9).
+ */
+export declare function runAtomicSync(deps: SyncDeps, args: SyncArgs): Promise<SyncResult>;
+/**
+ * Inspect a kit root and report where the NEXT sync should resume from (AC8):
+ *
+ *   - `2`    — sentinel present, anchor ABSENT: a prior sync fenced the tree
+ *              (step 1) then crashed before the anchor landed (steps 2–4). The
+ *              tree is a half-write; resume from step 2 to re-apply
+ *              writes/deletes and re-arm before writing the anchor.
+ *   - `1`    — sentinel AND anchor both absent: a fresh, never-synced kit.
+ *              Start a normal sync from step 1.
+ *   - `null` — the anchor is present (a prior sync completed cleanly): there is
+ *              no partial-write to resume; the next sync is a NEW plan from step
+ *              1 with fresh inputs, not a resume.
+ *
+ * Never mutates the tree. Propagates {@link readAnchor}'s `AnchorParseError`
+ * for a corrupt-but-present anchor — a corrupt anchor is a real operability
+ * problem, not a "nothing to resume" signal (same reasoning `readAnchor` itself
+ * applies). Likewise propagates any non-"missing" error from the sentinel
+ * `stat` (e.g. `EACCES` on `.genie/`) rather than treating it as "sentinel
+ * absent" — see {@link pathExists}.
+ */
+export declare function detectResumeStep(projectRoot: string): Promise<StepNumber | null>;
+//# sourceMappingURL=orchestrator.d.ts.map

package/dist/sync/orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../src/sync/orchestrator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAMH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAOtD,mFAAmF;AACnF,eAAO,MAAM,uBAAuB,qBAAqB,CAAC;AAE1D;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,uBAAmB,CAAC;AAIxD,iDAAiD;AACjD,MAAM,MAAM,UAAU,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,UAAU,CAAC;IACjB,EAAE,EAAE,OAAO,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAClB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,SAAS,EAAE,CAAA;CAAE,GACjC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,UAAU,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,SAAS,EAAE,CAAA;CAAE,CAAC;AAE7E;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,QAAQ,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACrB;AAID;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,CA8BvF;AAID;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAMtF"}