@orcareplay/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from './blobs.js';
+export * from './graph.js';
+export * from './paths.js';
+export * from './reader.js';
+export * from './redaction.js';
+export * from './writer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from './blobs.js';
+export * from './graph.js';
+export * from './paths.js';
+export * from './reader.js';
+export * from './redaction.js';
+export * from './writer.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC"}

package/dist/paths.d.ts

@@ -0,0 +1,45 @@
+export interface RunRef {
+    runId: string;
+    /** RFC3339, from the manifest when it is readable, else the directory's mtime. */
+    createdAt: string;
+    dir: string;
+    /** Set when this run was forked from another (spec §1). Absent on a plain recording. */
+    parentRun?: string;
+    forkPoint?: number;
+}
+export declare function orcaDir(cwd: string): string;
+export declare function runsDir(cwd: string): string;
+/**
+ * Create `.orca/runs`, and make the store ignore itself.
+ *
+ * A recording is the conversation the model saw — which is your source — plus shell output, a
+ * snapshot of the whole workspace, and an environment allowlist. SECURITY.md says to treat one as
+ * roughly as sensitive as a shell history plus a heap dump. It was also landing in `git status` as
+ * an untracked directory, one `git add -A` away from being committed and pushed, in the working
+ * tree of the project it just recorded.
+ *
+ * `.orca/.gitignore` containing `*` is git's own idiom for a directory that excludes itself: no
+ * edit to the user's `.gitignore`, nothing to remember, and it works in a repo orca has never seen
+ * before. Written once at creation and never rewritten, so anyone who deliberately wants their
+ * traces tracked can delete it and orca will not put it back.
+ */
+export declare function ensureRunsDir(cwd: string): Promise<string>;
+/** Run ids reach us from argv, so the pattern check is also the path-traversal guard. */
+export declare function runDirFor(cwd: string, runId: string): string;
+/** Every recorded run in the workspace, newest first. */
+export declare function listRuns(cwd: string): Promise<RunRef[]>;
+/**
+ * Resolves the CLI's run argument: `last` for the newest run, anything else as a run id.
+ *
+ * `last` skips replay traces. Since exact replay started writing one, the newest run in a
+ * directory is usually a report about the run before it, and every command defaults to `last` — so
+ * that quietly redirected all of them. The sharpest case is the line in the README:
+ * `orca scrub last --match my-hostname` scrubbed the empty trace, found nothing, and said "nothing
+ * matched — the trace is unchanged", while the secret sat in the recording beside it. A security
+ * tool reporting clean because it searched the wrong thing is worse than one that fails.
+ *
+ * Naming a replay trace explicitly still resolves it, and when a directory holds nothing else it
+ * is still returned — a selector that refuses to resolve is not an improvement.
+ */
+export declare function resolveRunSelector(cwd: string, selector: string): Promise<RunRef>;
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,MAAM;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,wFAAwF;IACxF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAYhE;AAED,yFAAyF;AACzF,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAG5D;AA6BD,yDAAyD;AACzD,wBAAsB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAc7D;AAaD;;;;;;;;;;;;GAYG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAevF"}

package/dist/paths.js

@@ -0,0 +1,115 @@
+import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { RUN_ID_PATTERN } from '@orcareplay/schema';
+export function orcaDir(cwd) {
+    return join(cwd, '.orca');
+}
+export function runsDir(cwd) {
+    return join(orcaDir(cwd), 'runs');
+}
+/**
+ * Create `.orca/runs`, and make the store ignore itself.
+ *
+ * A recording is the conversation the model saw — which is your source — plus shell output, a
+ * snapshot of the whole workspace, and an environment allowlist. SECURITY.md says to treat one as
+ * roughly as sensitive as a shell history plus a heap dump. It was also landing in `git status` as
+ * an untracked directory, one `git add -A` away from being committed and pushed, in the working
+ * tree of the project it just recorded.
+ *
+ * `.orca/.gitignore` containing `*` is git's own idiom for a directory that excludes itself: no
+ * edit to the user's `.gitignore`, nothing to remember, and it works in a repo orca has never seen
+ * before. Written once at creation and never rewritten, so anyone who deliberately wants their
+ * traces tracked can delete it and orca will not put it back.
+ */
+export async function ensureRunsDir(cwd) {
+    const dir = runsDir(cwd);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const ignore = join(orcaDir(cwd), '.gitignore');
+    if (!(await stat(ignore).catch(() => null))) {
+        await writeFile(ignore, '# Recordings hold source, shell output and workspace snapshots. Not for committing.\n*\n', { mode: 0o600, flag: 'wx' }).catch(() => undefined);
+    }
+    return dir;
+}
+/** Run ids reach us from argv, so the pattern check is also the path-traversal guard. */
+export function runDirFor(cwd, runId) {
+    if (!RUN_ID_PATTERN.test(runId))
+        throw new Error(`not a valid run id: ${JSON.stringify(runId)}`);
+    return join(runsDir(cwd), runId);
+}
+/**
+ * The manifest facts a listing needs, read in one pass.
+ *
+ * Everything here degrades rather than throws: a run whose manifest is missing or truncated is
+ * still worth listing — that is exactly the crashed run someone is looking for.
+ */
+async function factsOf(dir) {
+    try {
+        const raw = JSON.parse(await readFile(join(dir, 'manifest.json'), 'utf8'));
+        const at = raw.created_at;
+        if (typeof at === 'string' && !Number.isNaN(Date.parse(at))) {
+            return {
+                createdAt: at,
+                ...(typeof raw.parent_run === 'string' ? { parentRun: raw.parent_run } : {}),
+                ...(typeof raw.fork_point === 'number' ? { forkPoint: raw.fork_point } : {}),
+            };
+        }
+    }
+    catch {
+        // Fall through to the directory's mtime.
+    }
+    return { createdAt: new Date((await stat(dir)).mtimeMs).toISOString() };
+}
+/** Every recorded run in the workspace, newest first. */
+export async function listRuns(cwd) {
+    const root = runsDir(cwd);
+    const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+    const runs = [];
+    for (const e of entries) {
+        if (!e.isDirectory() || !RUN_ID_PATTERN.test(e.name))
+            continue;
+        const dir = join(root, e.name);
+        runs.push({ runId: e.name, dir, ...(await factsOf(dir)) });
+    }
+    return runs.sort((a, b) => a.createdAt === b.createdAt
+        ? b.runId.localeCompare(a.runId)
+        : b.createdAt.localeCompare(a.createdAt));
+}
+/**
+ * A run that describes another run rather than being one: an exact replay's own trace.
+ *
+ * It holds divergences and nothing else — no exchanges, no blobs, no filesystem store. A fork is
+ * not one of these: it has a `fork_point`, real exchanges and a worktree, and is a thing you act
+ * on.
+ */
+function isReplayTrace(run) {
+    return run.parentRun !== undefined && run.forkPoint === undefined;
+}
+/**
+ * Resolves the CLI's run argument: `last` for the newest run, anything else as a run id.
+ *
+ * `last` skips replay traces. Since exact replay started writing one, the newest run in a
+ * directory is usually a report about the run before it, and every command defaults to `last` — so
+ * that quietly redirected all of them. The sharpest case is the line in the README:
+ * `orca scrub last --match my-hostname` scrubbed the empty trace, found nothing, and said "nothing
+ * matched — the trace is unchanged", while the secret sat in the recording beside it. A security
+ * tool reporting clean because it searched the wrong thing is worse than one that fails.
+ *
+ * Naming a replay trace explicitly still resolves it, and when a directory holds nothing else it
+ * is still returned — a selector that refuses to resolve is not an improvement.
+ */
+export async function resolveRunSelector(cwd, selector) {
+    if (selector === 'last') {
+        const runs = await listRuns(cwd);
+        const newest = runs.find((r) => !isReplayTrace(r)) ?? runs[0];
+        if (!newest) {
+            throw new Error(`no runs recorded in ${runsDir(cwd)} — record one first: orca record -- <your agent>`);
+        }
+        return newest;
+    }
+    const dir = runDirFor(cwd, selector);
+    const found = (await listRuns(cwd)).find((r) => r.dir === dir);
+    if (!found)
+        throw new Error(`no run ${selector} in ${runsDir(cwd)} — list runs with: orca list`);
+    return found;
+}
+//# sourceMappingURL=paths.js.map

package/dist/paths.js.map

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

package/dist/reader.d.ts

@@ -0,0 +1,45 @@
+import type { BlobRef, Manifest, TraceEvent } from '@orcareplay/schema';
+/** A line the reader could not use. Reported, never repaired (spec §6). */
+export interface ReadProblem {
+    /** 1-based line number in events.jsonl; 0 for a problem with the file itself. */
+    line: number;
+    reason: string;
+}
+export interface IntegrityResult {
+    /** True only for a sealed run whose events file still hashes to the digest it was sealed with. */
+    ok: boolean;
+    /**
+     * Why `ok` is what it is. `unsealed` is not `mismatch`, and collapsing the two is how a run whose
+     * recorder was killed gets reported as tampered: nothing changed under it, there was simply never
+     * a digest to check it against. Callers that only care whether the bytes are trustworthy read
+     * `ok`; callers that tell a person what happened have to tell those two apart.
+     */
+    state: 'verified' | 'unsealed' | 'mismatch';
+    /** Absent when the run was never sealed, so there is nothing to check against. */
+    expected?: string;
+    actual?: string;
+}
+/**
+ * Reader for one recorded run.
+ *
+ * Two tolerances are mandated by spec §2 and both are deliberate: a run that crashed mid-write
+ * leaves a partial final line, and a trace written by a newer Orca may carry event types this
+ * build has never heard of. Neither may take down the whole trace — but neither is hidden either,
+ * so anything skipped shows up in {@link problems}.
+ */
+export declare class TraceReader {
+    #private;
+    private constructor();
+    static open(runDir: string): Promise<TraceReader>;
+    get runDir(): string;
+    manifest(): Manifest;
+    /** Lines skipped by the most recent read pass. */
+    problems(): ReadProblem[];
+    events(): Promise<TraceEvent[]>;
+    stream(): AsyncIterableIterator<TraceEvent>;
+    blob(ref: BlobRef | string): Promise<Uint8Array>;
+    /** The event's payload, reading it back from its blob when it was spilled (spec §2.2). */
+    resolvePayload(event: TraceEvent): Promise<unknown>;
+    verifyIntegrity(): Promise<IntegrityResult>;
+}
+//# sourceMappingURL=reader.d.ts.map

package/dist/reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader.d.ts","sourceRoot":"","sources":["../src/reader.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAIxE,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,kGAAkG;IAClG,EAAE,EAAE,OAAO,CAAC;IACZ;;;;;OAKG;IACH,KAAK,EAAE,UAAU,GAAG,UAAU,GAAG,UAAU,CAAC;IAC5C,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAID;;;;;;;GAOG;AACH,qBAAa,WAAW;;IAOtB,OAAO;WAOM,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAkBvD,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,QAAQ,IAAI,QAAQ;IAIpB,kDAAkD;IAClD,QAAQ,IAAI,WAAW,EAAE;IAInB,MAAM,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAM9B,MAAM,IAAI,qBAAqB,CAAC,UAAU,CAAC;IAiC5C,IAAI,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAItD,0FAA0F;IACpF,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC;IAYnD,eAAe,IAAI,OAAO,CAAC,eAAe,CAAC;CAiClD"}

package/dist/reader.js

@@ -0,0 +1,152 @@
+import { createReadStream } from 'node:fs';
+import { readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+import { EVENT_TYPES, assertManifest, isBlobRef, validateEvent } from '@orcareplay/schema';
+import { BlobStore, sha256File } from './blobs.js';
+const KNOWN_TYPES = new Set(EVENT_TYPES);
+/**
+ * Reader for one recorded run.
+ *
+ * Two tolerances are mandated by spec §2 and both are deliberate: a run that crashed mid-write
+ * leaves a partial final line, and a trace written by a newer Orca may carry event types this
+ * build has never heard of. Neither may take down the whole trace — but neither is hidden either,
+ * so anything skipped shows up in {@link problems}.
+ */
+export class TraceReader {
+    #runDir;
+    #eventsPath;
+    #manifest;
+    #blobs;
+    #problems = [];
+    constructor(runDir, manifest) {
+        this.#runDir = runDir;
+        this.#eventsPath = join(runDir, 'events.jsonl');
+        this.#manifest = manifest;
+        this.#blobs = new BlobStore(join(runDir, 'blobs'));
+    }
+    static async open(runDir) {
+        const path = join(runDir, 'manifest.json');
+        let raw;
+        try {
+            raw = await readFile(path, 'utf8');
+        }
+        catch {
+            throw new Error(`not an orca run: cannot read ${path}`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            throw new Error(`invalid manifest: ${path} is not JSON`);
+        }
+        assertManifest(parsed);
+        return new TraceReader(runDir, parsed);
+    }
+    get runDir() {
+        return this.#runDir;
+    }
+    manifest() {
+        return this.#manifest;
+    }
+    /** Lines skipped by the most recent read pass. */
+    problems() {
+        return [...this.#problems];
+    }
+    async events() {
+        const out = [];
+        for await (const e of this.stream())
+            out.push(e);
+        return out;
+    }
+    async *stream() {
+        this.#problems = [];
+        if (!(await stat(this.#eventsPath).catch(() => null))) {
+            this.#problems.push({ line: 0, reason: `${this.#eventsPath} is missing` });
+            return;
+        }
+        const rl = createInterface({
+            input: createReadStream(this.#eventsPath),
+            crlfDelay: Number.POSITIVE_INFINITY,
+        });
+        // One line is held back so the last one can be told apart from the rest: only the last may
+        // legitimately be half-written.
+        let held;
+        let n = 0;
+        try {
+            for await (const raw of rl) {
+                n += 1;
+                if (raw.trim().length === 0)
+                    continue;
+                if (held) {
+                    const e = this.#parse(held, false);
+                    if (e)
+                        yield e;
+                }
+                held = { line: n, text: raw };
+            }
+            if (held) {
+                const e = this.#parse(held, true);
+                if (e)
+                    yield e;
+            }
+        }
+        finally {
+            rl.close();
+        }
+    }
+    async blob(ref) {
+        return this.#blobs.get(ref);
+    }
+    /** The event's payload, reading it back from its blob when it was spilled (spec §2.2). */
+    async resolvePayload(event) {
+        const payload = event.payload;
+        if (!isBlobRef(payload))
+            return payload;
+        const text = new TextDecoder().decode(await this.blob(payload));
+        if (payload.media_type !== undefined && !payload.media_type.includes('json'))
+            return text;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new Error(`blob ${payload.$blob} is not JSON; read it with blob() instead`);
+        }
+    }
+    async verifyIntegrity() {
+        const expected = this.#manifest.integrity?.events_sha256;
+        const actual = await sha256File(this.#eventsPath);
+        if (expected === undefined)
+            return { ok: false, state: 'unsealed', actual };
+        return expected === actual
+            ? { ok: true, state: 'verified', expected, actual }
+            : { ok: false, state: 'mismatch', expected, actual };
+    }
+    #parse(held, isLast) {
+        let value;
+        try {
+            value = JSON.parse(held.text);
+        }
+        catch {
+            const reason = isLast ? 'truncated final line' : 'malformed JSON';
+            this.#problems.push({ line: held.line, reason });
+            return undefined;
+        }
+        const type = value.type;
+        if (typeof type !== 'string' || !KNOWN_TYPES.has(type)) {
+            this.#problems.push({
+                line: held.line,
+                reason: `unknown event type ${JSON.stringify(type)}`,
+            });
+            return undefined;
+        }
+        const result = validateEvent(value);
+        if (!result.valid) {
+            this.#problems.push({ line: held.line, reason: result.errors.join('; ') });
+            return undefined;
+        }
+        return value;
+    }
+}
+//# sourceMappingURL=reader.js.map

package/dist/reader.js.map

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

package/dist/redaction.d.ts

@@ -0,0 +1,48 @@
+import type { RedactionRecord } from '@orcareplay/schema';
+/** Bump when a rule is added or changed, so old traces stay interpretable. */
+export declare const REDACTION_POLICY_VERSION = 3;
+/** Environment capture is allowlist-only (spec §5). Everything else is denied. */
+export declare const DEFAULT_ENV_ALLOWLIST: string[];
+/**
+ * Request headers whose value is never written, whatever it looks like (spec §5).
+ *
+ * The single list. There were three — here, in the recording proxy, and in the TLS interceptor —
+ * and they had drifted: `api-key` and `x-goog-api-key` were known to exactly one of them, so the
+ * same Azure or Google credential was stripped on the intercepted path and written on the recorded
+ * one. Nothing about a header set that has to stay identical in three places will keep it that
+ * way, so it is defined once and imported.
+ */
+export declare const AUTH_REQUEST_HEADERS: string[];
+/** A response can hand out credentials too. `set-cookie` is a session, not metadata. */
+export declare const AUTH_RESPONSE_HEADERS: string[];
+/** Every header name whose value is never written, in either direction. */
+export declare const AUTH_HEADERS: string[];
+export interface RedactionOptions {
+    /** Per-run salt. Defaults to fresh randomness, and is deliberately never persisted. */
+    salt?: string;
+    /** Replaces {@link DEFAULT_ENV_ALLOWLIST} outright — this is a deny-by-default control. */
+    envAllowlist?: string[];
+}
+export interface RedactionResult<T> {
+    value: T;
+    hits: RedactionRecord[];
+}
+/**
+ * Write-path redactor (spec §5).
+ *
+ * The placeholder is `<secret:kind:hash8>` where hash8 is sha256(salt + secret) truncated, so the
+ * same secret always yields the same placeholder — replay still matches structurally — while the
+ * secret itself is unrecoverable. The salt is per run and never written down, which is what stops
+ * a short secret from being brute-forced out of a published trace.
+ */
+export declare class Redactor {
+    #private;
+    constructor(opts?: RedactionOptions);
+    redactString(s: string, context?: string): RedactionResult<string>;
+    redactHeaders(headers: Record<string, string>): RedactionResult<Record<string, string>>;
+    redactEnv(env: Record<string, string | undefined>): Record<string, string>;
+    /** Every removal so far, aggregated by rule and identifier. Never contains a value. */
+    records(): RedactionRecord[];
+    rulesFired(): Record<string, number>;
+}
+//# sourceMappingURL=redaction.d.ts.map

package/dist/redaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redaction.d.ts","sourceRoot":"","sources":["../src/redaction.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D,8EAA8E;AAK9E,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C,kFAAkF;AAClF,eAAO,MAAM,qBAAqB,UAUjC,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,UAQhC,CAAC;AAEF,wFAAwF;AACxF,eAAO,MAAM,qBAAqB,UAAiB,CAAC;AAEpD,2EAA2E;AAC3E,eAAO,MAAM,YAAY,UAAsD,CAAC;AA0GhF,MAAM,WAAW,gBAAgB;IAC/B,uFAAuF;IACvF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2FAA2F;IAC3F,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,KAAK,EAAE,CAAC,CAAC;IACT,IAAI,EAAE,eAAe,EAAE,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,qBAAa,QAAQ;;gBAKP,IAAI,GAAE,gBAAqB;IAKvC,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,eAAe,CAAC,MAAM,CAAC;IAOlE,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,eAAe,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAcvF,SAAS,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAY1E,uFAAuF;IACvF,OAAO,IAAI,eAAe,EAAE;IAI5B,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;CA6DrC"}