@shardworks/nexus-core 0.1.20 → 0.1.21

package/dist/session.d.ts

@@ -0,0 +1,214 @@
+/**
+ * Session infrastructure — the unified session funnel.
+ *
+ * ALL sessions (interactive, commissioned, briefed) flow through
+ * `launchSession()`. This provides unified logging, events, metrics,
+ * workspace lifecycle, and session record persistence.
+ *
+ * Session providers (e.g. claude-code, claude-api) implement the
+ * `SessionProvider` interface and are registered at startup.
+ */
+import type { ManifestResult } from './manifest.ts';
+/** What a session provider must implement. */
+export interface SessionProvider {
+    /** Provider identifier (e.g. "claude-code", "claude-api", "bedrock"). */
+    name: string;
+    /** Launch a session and return when it completes. */
+    launch(options: SessionProviderLaunchOptions): Promise<SessionProviderResult>;
+}
+/** Options passed to the provider's launch() — provider-specific subset. */
+export interface SessionProviderLaunchOptions {
+    /** Guild root path. */
+    home: string;
+    /** The manifest result — system prompt + resolved tools. */
+    manifest: ManifestResult;
+    /** The user-facing prompt (commission spec, consultation topic, brief). */
+    prompt: string | null;
+    /** Whether the session is interactive (human at keyboard) or autonomous. */
+    interactive: boolean;
+    /** Resolved working directory for the session. */
+    cwd: string;
+    /** Display name for tracking. */
+    name?: string;
+    /** Budget cap, if any. */
+    maxBudgetUsd?: number;
+}
+/** What comes back from the provider (before the funnel adds its own fields). */
+export interface SessionProviderResult {
+    exitCode: number;
+    /** Provider-reported token usage, if available. */
+    tokenUsage?: {
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens?: number;
+        cacheWriteTokens?: number;
+    };
+    /** Provider-reported cost in USD, if available. */
+    costUsd?: number;
+    /** Wall-clock duration in milliseconds. */
+    durationMs: number;
+    /** Session ID from the provider, if available (e.g. claude session ID). */
+    providerSessionId?: string;
+    /**
+     * Full conversation transcript — raw provider output, minimally typed.
+     * Stored as-is in the session record; typed normalization deferred.
+     */
+    transcript?: Record<string, unknown>[];
+}
+/** Everything needed to launch a session through the funnel. */
+export interface SessionLaunchOptions {
+    /** Guild root path. */
+    home: string;
+    /** The manifest result — system prompt + resolved tools. */
+    manifest: ManifestResult;
+    /** The user-facing prompt (commission spec, consultation topic, brief). */
+    prompt: string | null;
+    /** Whether the session is interactive (human at keyboard) or autonomous. */
+    interactive: boolean;
+    /** Workspace context. */
+    workspace: ResolvedWorkspace;
+    /** What triggered this session. */
+    trigger: 'consult' | 'summon' | 'brief';
+    /** Display name for tracking. */
+    name?: string;
+    /** Budget cap, if any. */
+    maxBudgetUsd?: number;
+}
+/** What the funnel returns to callers. */
+export interface SessionResult {
+    /** Ledger row ID — written by the funnel before provider launch. */
+    sessionId: number;
+    exitCode: number;
+    /** Provider-reported token usage, if available. */
+    tokenUsage?: {
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens?: number;
+        cacheWriteTokens?: number;
+    };
+    /** Provider-reported cost in USD, if available. */
+    costUsd?: number;
+    /** Wall-clock duration in milliseconds. */
+    durationMs: number;
+    /** Session ID from the provider, if available. */
+    providerSessionId?: string;
+    /** Raw transcript from the provider. */
+    transcript?: Record<string, unknown>[];
+}
+/**
+ * Standard optional fields on event payloads. Any event can carry these.
+ * The session launcher inspects the triggering event's payload and uses
+ * them to determine the working directory for the session.
+ */
+export interface WorkspaceContext {
+    /** Workshop name — session gets a fresh temporary worktree of main. */
+    workshop?: string;
+    /** Explicit worktree path — used as-is (caller owns the lifecycle). */
+    worktreePath?: string;
+}
+/** The resolved working directory for a session. */
+export type ResolvedWorkspace = {
+    kind: 'guildhall';
+} | {
+    kind: 'workshop-temp';
+    workshop: string;
+    worktreePath: string;
+} | {
+    kind: 'workshop-managed';
+    workshop: string;
+    worktreePath: string;
+};
+/** Full session record written to disk as JSON. */
+export interface SessionRecord {
+    /** Ledger session row ID (for cross-reference). */
+    sessionId: number;
+    /** The anima that ran this session, with full composition provenance. */
+    anima: {
+        id: number;
+        name: string;
+        roles: string[];
+        codex: string;
+        roleInstructions: string;
+        curriculum: {
+            name: string;
+            version: string;
+            content: string;
+        } | null;
+        temperament: {
+            name: string;
+            version: string;
+            content: string;
+        } | null;
+        toolInstructions: Array<{
+            toolName: string;
+            instructions: string;
+        }>;
+    };
+    /** The final assembled system prompt. */
+    systemPrompt: string;
+    /** Tools available to the anima. */
+    tools: Array<{
+        name: string;
+    }>;
+    /** Tools that were resolved but failed preconditions. */
+    unavailableTools: Array<{
+        name: string;
+        reasons: string[];
+    }>;
+    /** The user-facing prompt. */
+    userPrompt: string | null;
+    /** Raw conversation transcript from the provider. */
+    transcript: Record<string, unknown>[];
+}
+/**
+ * Register a session provider. Called once at startup.
+ */
+export declare function registerSessionProvider(provider: SessionProvider): void;
+/** Get the registered session provider. */
+export declare function getSessionProvider(): SessionProvider | null;
+/**
+ * Resolve workspace context from an event payload's standard fields.
+ */
+export declare function resolveWorkspace(payload: Record<string, unknown> | null): ResolvedWorkspace;
+/**
+ * Create a temporary worktree from a workshop's bare repo, checked out to main.
+ *
+ * Uses a crypto-safe random hash for the directory name. The worktree is
+ * a fresh snapshot — no branch management, no merge-back lifecycle.
+ *
+ * @returns Absolute path to the worktree directory.
+ */
+export declare function createTempWorktree(home: string, workshop: string): string;
+/**
+ * Remove a temporary worktree.
+ *
+ * Logs but does not throw on failure — stale worktrees are assumed to be
+ * reaped by a separate mechanism.
+ */
+export declare function removeTempWorktree(home: string, workshop: string, worktreePath: string): void;
+/**
+ * Launch a session through the registered provider.
+ *
+ * This is THE code path for all sessions. It:
+ * 1. If workspace is workshop-temp: create fresh worktree from main
+ * 2. Records session.started in the Ledger → gets sessionId
+ * 3. Signals session.started event
+ * 4. Delegates to the provider (passing resolved cwd)
+ * 5. Records session.ended in the Ledger (with metrics)
+ * 6. Writes the SessionRecord JSON to .nexus/sessions/{uuid}.json
+ * 7. Signals session.ended event (with full metrics + sessionId in payload)
+ * 8. If workspace is workshop-temp AND session is autonomous: tear down the worktree
+ *    (interactive sessions leave the worktree for manual cleanup)
+ * 9. Returns the result (including sessionId)
+ *
+ * Error handling guarantee: Steps 5–8 MUST execute even if the provider
+ * throws. The funnel wraps step 4 in try/finally. If the provider crashes,
+ * the session row still gets ended_at, exit_code, and the session.ended
+ * event still fires (with error details in the payload). If the funnel
+ * itself fails during recording (e.g. Ledger locked), it signals
+ * session.record-failed as a core event and continues with remaining
+ * cleanup steps. Worktree teardown failures are logged but do not throw —
+ * stale worktrees are assumed to be reaped by a separate mechanism.
+ */
+export declare function launchSession(options: SessionLaunchOptions): Promise<SessionResult>;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

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

package/dist/session.js

@@ -0,0 +1,349 @@
+/**
+ * Session infrastructure — the unified session funnel.
+ *
+ * ALL sessions (interactive, commissioned, briefed) flow through
+ * `launchSession()`. This provides unified logging, events, metrics,
+ * workspace lifecycle, and session record persistence.
+ *
+ * Session providers (e.g. claude-code, claude-api) implement the
+ * `SessionProvider` interface and are registered at startup.
+ */
+import crypto from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import Database from 'better-sqlite3';
+import { ledgerPath, nexusDir, workshopBarePath } from "./nexus-home.js";
+import { signalEvent } from "./events.js";
+// ── Provider Registration ──────────────────────────────────────────────
+let _provider = null;
+/**
+ * Register a session provider. Called once at startup.
+ */
+export function registerSessionProvider(provider) {
+    _provider = provider;
+}
+/** Get the registered session provider. */
+export function getSessionProvider() {
+    return _provider;
+}
+// ── Workspace Helpers ──────────────────────────────────────────────────
+/**
+ * Resolve workspace context from an event payload's standard fields.
+ */
+export function resolveWorkspace(payload) {
+    if (!payload)
+        return { kind: 'guildhall' };
+    const worktreePath = payload.worktreePath;
+    const workshop = payload.workshop;
+    if (worktreePath && workshop) {
+        return { kind: 'workshop-managed', workshop, worktreePath };
+    }
+    if (workshop) {
+        // workshop-temp: worktreePath gets set by createTempWorktree before launch
+        // We return a placeholder — the funnel fills in the actual path
+        return { kind: 'workshop-temp', workshop, worktreePath: '' };
+    }
+    return { kind: 'guildhall' };
+}
+/**
+ * Create a temporary worktree from a workshop's bare repo, checked out to main.
+ *
+ * Uses a crypto-safe random hash for the directory name. The worktree is
+ * a fresh snapshot — no branch management, no merge-back lifecycle.
+ *
+ * @returns Absolute path to the worktree directory.
+ */
+export function createTempWorktree(home, workshop) {
+    const hash = crypto.randomBytes(8).toString('hex');
+    const worktreeDir = path.join(nexusDir(home), 'worktrees', workshop, hash);
+    const barePath = workshopBarePath(home, workshop);
+    if (!fs.existsSync(barePath)) {
+        throw new Error(`Workshop "${workshop}" bare repo not found at ${barePath}. ` +
+            `Has the workshop been added with 'nsg workshop add'?`);
+    }
+    fs.mkdirSync(path.dirname(worktreeDir), { recursive: true });
+    execFileSync('git', ['worktree', 'add', '--detach', worktreeDir, 'main'], {
+        cwd: barePath,
+        stdio: 'pipe',
+    });
+    return worktreeDir;
+}
+/**
+ * Remove a temporary worktree.
+ *
+ * Logs but does not throw on failure — stale worktrees are assumed to be
+ * reaped by a separate mechanism.
+ */
+export function removeTempWorktree(home, workshop, worktreePath) {
+    const barePath = workshopBarePath(home, workshop);
+    try {
+        execFileSync('git', ['worktree', 'remove', '--force', worktreePath], {
+            cwd: barePath,
+            stdio: 'pipe',
+        });
+    }
+    catch (err) {
+        console.error(`[session] Warning: failed to remove temp worktree ${worktreePath}: ` +
+            `${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+// ── Session Record Helpers ─────────────────────────────────────────────
+/** Path to the sessions directory. */
+function sessionsDir(home) {
+    return path.join(nexusDir(home), 'sessions');
+}
+/**
+ * Build a SessionRecord from the manifest and provider result.
+ */
+function buildSessionRecord(sessionId, manifest, prompt, providerResult) {
+    return {
+        sessionId,
+        anima: {
+            id: manifest.anima.id,
+            name: manifest.anima.name,
+            roles: manifest.anima.roles,
+            codex: manifest.composition.codex,
+            roleInstructions: manifest.composition.roleInstructions,
+            curriculum: manifest.composition.curriculum,
+            temperament: manifest.composition.temperament,
+            toolInstructions: manifest.composition.toolInstructions,
+        },
+        systemPrompt: manifest.systemPrompt,
+        tools: manifest.tools.map(t => ({ name: t.name })),
+        unavailableTools: manifest.unavailable,
+        userPrompt: prompt,
+        transcript: providerResult?.transcript ?? [],
+    };
+}
+/**
+ * Write a session record to disk.
+ * @returns The relative record_path (relative to guild root).
+ */
+function writeSessionRecord(home, record) {
+    const dir = sessionsDir(home);
+    fs.mkdirSync(dir, { recursive: true });
+    const uuid = crypto.randomUUID();
+    const filename = `${uuid}.json`;
+    const fullPath = path.join(dir, filename);
+    const relativePath = path.relative(home, fullPath);
+    fs.writeFileSync(fullPath, JSON.stringify(record, null, 2));
+    return relativePath;
+}
+// ── Ledger Helpers ─────────────────────────────────────────────────────
+/**
+ * Insert a session.started row in the Ledger.
+ * @returns The session row ID.
+ */
+function insertSessionRow(home, opts) {
+    const db = new Database(ledgerPath(home));
+    db.pragma('foreign_keys = ON');
+    try {
+        const result = db.prepare(`INSERT INTO sessions (anima_id, provider, trigger, workshop, workspace_kind,
+        curriculum_name, curriculum_version, temperament_name, temperament_version,
+        roles, started_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(opts.animaId, opts.provider, opts.trigger, opts.workshop, opts.workspaceKind, opts.curriculumName, opts.curriculumVersion, opts.temperamentName, opts.temperamentVersion, JSON.stringify(opts.roles), opts.startedAt);
+        return Number(result.lastInsertRowid);
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Update a session row with end-of-session data.
+ */
+function updateSessionRow(home, sessionId, opts) {
+    const db = new Database(ledgerPath(home));
+    db.pragma('foreign_keys = ON');
+    try {
+        db.prepare(`UPDATE sessions SET
+        ended_at = ?, exit_code = ?,
+        input_tokens = ?, output_tokens = ?,
+        cache_read_tokens = ?, cache_write_tokens = ?,
+        cost_usd = ?, duration_ms = ?,
+        provider_session_id = ?, record_path = ?
+       WHERE id = ?`).run(opts.endedAt, opts.exitCode, opts.inputTokens ?? null, opts.outputTokens ?? null, opts.cacheReadTokens ?? null, opts.cacheWriteTokens ?? null, opts.costUsd ?? null, opts.durationMs ?? null, opts.providerSessionId ?? null, opts.recordPath ?? null, sessionId);
+    }
+    finally {
+        db.close();
+    }
+}
+// ── The Session Funnel ─────────────────────────────────────────────────
+/**
+ * Launch a session through the registered provider.
+ *
+ * This is THE code path for all sessions. It:
+ * 1. If workspace is workshop-temp: create fresh worktree from main
+ * 2. Records session.started in the Ledger → gets sessionId
+ * 3. Signals session.started event
+ * 4. Delegates to the provider (passing resolved cwd)
+ * 5. Records session.ended in the Ledger (with metrics)
+ * 6. Writes the SessionRecord JSON to .nexus/sessions/{uuid}.json
+ * 7. Signals session.ended event (with full metrics + sessionId in payload)
+ * 8. If workspace is workshop-temp AND session is autonomous: tear down the worktree
+ *    (interactive sessions leave the worktree for manual cleanup)
+ * 9. Returns the result (including sessionId)
+ *
+ * Error handling guarantee: Steps 5–8 MUST execute even if the provider
+ * throws. The funnel wraps step 4 in try/finally. If the provider crashes,
+ * the session row still gets ended_at, exit_code, and the session.ended
+ * event still fires (with error details in the payload). If the funnel
+ * itself fails during recording (e.g. Ledger locked), it signals
+ * session.record-failed as a core event and continues with remaining
+ * cleanup steps. Worktree teardown failures are logged but do not throw —
+ * stale worktrees are assumed to be reaped by a separate mechanism.
+ */
+export async function launchSession(options) {
+    if (!_provider) {
+        throw new Error('No session provider registered. Call registerSessionProvider() at startup.');
+    }
+    const { home, manifest, prompt, interactive, trigger, name, maxBudgetUsd } = options;
+    let { workspace } = options;
+    // Step 1: If workshop-temp, create fresh worktree
+    if (workspace.kind === 'workshop-temp') {
+        const worktreePath = createTempWorktree(home, workspace.workshop);
+        workspace = { ...workspace, worktreePath };
+    }
+    // Resolve cwd from workspace
+    const cwd = workspace.kind === 'guildhall'
+        ? home
+        : workspace.worktreePath;
+    const startedAt = new Date().toISOString();
+    // Derive workshop name from workspace
+    const workshopName = workspace.kind === 'guildhall' ? null : workspace.workshop;
+    // Step 2: Record session.started in the Ledger
+    let sessionId;
+    try {
+        sessionId = insertSessionRow(home, {
+            animaId: manifest.anima.id,
+            provider: _provider.name,
+            trigger,
+            workshop: workshopName,
+            workspaceKind: workspace.kind,
+            curriculumName: manifest.composition.curriculum?.name ?? null,
+            curriculumVersion: manifest.composition.curriculum?.version ?? null,
+            temperamentName: manifest.composition.temperament?.name ?? null,
+            temperamentVersion: manifest.composition.temperament?.version ?? null,
+            roles: manifest.anima.roles,
+            startedAt,
+        });
+    }
+    catch (err) {
+        // If we can't even write the session row, signal failure and abort
+        try {
+            signalEvent(home, 'session.record-failed', {
+                error: err instanceof Error ? err.message : String(err),
+                phase: 'insert',
+                anima: manifest.anima.name,
+            }, 'framework');
+        }
+        catch { /* swallow — best effort */ }
+        throw err;
+    }
+    // Step 3: Signal session.started event
+    try {
+        signalEvent(home, 'session.started', {
+            sessionId,
+            anima: manifest.anima.name,
+            trigger,
+            workshop: workshopName,
+            workspaceKind: workspace.kind,
+        }, 'framework');
+    }
+    catch { /* swallow — event signalling is best-effort */ }
+    // Step 4: Delegate to the provider (wrapped in try/finally for guarantees)
+    let providerResult = null;
+    let providerError = null;
+    try {
+        providerResult = await _provider.launch({
+            home,
+            manifest,
+            prompt,
+            interactive,
+            cwd,
+            name,
+            maxBudgetUsd,
+        });
+    }
+    catch (err) {
+        providerError = err instanceof Error ? err : new Error(String(err));
+    }
+    // Steps 5–8: Always execute, even if the provider threw
+    const endedAt = new Date().toISOString();
+    const exitCode = providerResult?.exitCode ?? 1;
+    const durationMs = providerResult?.durationMs ?? (Date.now() - new Date(startedAt).getTime());
+    // Step 5: Update session row in Ledger
+    let recordPath;
+    try {
+        // Step 6: Write SessionRecord JSON
+        const record = buildSessionRecord(sessionId, manifest, prompt, providerResult);
+        recordPath = writeSessionRecord(home, record);
+    }
+    catch (err) {
+        try {
+            signalEvent(home, 'session.record-failed', {
+                sessionId,
+                error: err instanceof Error ? err.message : String(err),
+                phase: 'write-record',
+            }, 'framework');
+        }
+        catch { /* swallow */ }
+    }
+    try {
+        updateSessionRow(home, sessionId, {
+            endedAt,
+            exitCode,
+            inputTokens: providerResult?.tokenUsage?.inputTokens,
+            outputTokens: providerResult?.tokenUsage?.outputTokens,
+            cacheReadTokens: providerResult?.tokenUsage?.cacheReadTokens,
+            cacheWriteTokens: providerResult?.tokenUsage?.cacheWriteTokens,
+            costUsd: providerResult?.costUsd,
+            durationMs,
+            providerSessionId: providerResult?.providerSessionId,
+            recordPath,
+        });
+    }
+    catch (err) {
+        try {
+            signalEvent(home, 'session.record-failed', {
+                sessionId,
+                error: err instanceof Error ? err.message : String(err),
+                phase: 'update-row',
+            }, 'framework');
+        }
+        catch { /* swallow */ }
+    }
+    // Step 7: Signal session.ended event
+    try {
+        signalEvent(home, 'session.ended', {
+            sessionId,
+            anima: manifest.anima.name,
+            trigger,
+            workshop: workshopName,
+            exitCode,
+            durationMs,
+            costUsd: providerResult?.costUsd ?? null,
+            error: providerError?.message ?? null,
+        }, 'framework');
+    }
+    catch { /* swallow */ }
+    // Step 8: Teardown temp worktree (autonomous only)
+    if (workspace.kind === 'workshop-temp' && !interactive) {
+        removeTempWorktree(home, workspace.workshop, workspace.worktreePath);
+    }
+    // Step 9: Return result
+    if (providerError && !providerResult) {
+        // Provider threw without returning — re-throw so caller knows
+        throw providerError;
+    }
+    return {
+        sessionId,
+        exitCode,
+        tokenUsage: providerResult?.tokenUsage,
+        costUsd: providerResult?.costUsd,
+        durationMs,
+        providerSessionId: providerResult?.providerSessionId,
+        transcript: providerResult?.transcript,
+    };
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

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

package/dist/worktree.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Commission worktree management — creates isolated git worktrees for
+ * commission sessions.
+ *
+ * When an anima is dispatched to work on a commission, this module:
+ * 1. Creates a new git branch for the commission
+ * 2. Sets up a git worktree pointing at that branch
+ * 3. Returns the worktree path so the session can launch in the correct cwd
+ *
+ * Worktrees provide isolation — each commission gets its own working copy
+ * of the repo, so multiple animas can work concurrently without conflicts
+ * in the working directory.
+ *
+ * Absorbed from the former `engine-worktree-setup` package.
+ *
+ * ## Directory layout
+ *
+ * Commission worktrees are created from workshop bare clones:
+ *
+ *   GUILD_ROOT/
+ *     .nexus/
+ *       workshops/
+ *         workshop-a.git/          ← bare clone (source for worktrees)
+ *       worktrees/
+ *         workshop-a/
+ *           commission-42/         ← worktree for commission #42
+ *         workshop-b/
+ *           commission-17/         ← worktree for commission #17
+ */
+export interface WorktreeConfig {
+    /** Absolute path to the guild root. */
+    home: string;
+    /** Workshop name — the bare clone source for the worktree. */
+    workshop: string;
+    /** Commission ID — used to derive branch name and worktree directory. */
+    commissionId: number;
+    /** Base branch to create the worktree from (default: 'main'). */
+    baseBranch?: string;
+}
+export interface WorktreeResult {
+    /** Absolute path to the created worktree. */
+    path: string;
+    /** Branch name created for the worktree. */
+    branch: string;
+    /** Commission ID this worktree serves. */
+    commissionId: number;
+}
+/**
+ * Create a git worktree for a commission session.
+ *
+ * Creates a new branch from the base branch and sets up a worktree in
+ * .nexus/worktrees/{workshop}/commission-{id}/.
+ *
+ * @throws If the worktree or branch already exists.
+ */
+export declare function setupWorktree(config: WorktreeConfig): WorktreeResult;
+/**
+ * Remove a worktree after a commission session completes.
+ *
+ * Removes the worktree directory and prunes it from git's tracking.
+ * Does NOT delete the branch — the branch should be kept for history
+ * until explicitly merged or pruned.
+ */
+export declare function teardownWorktree(home: string, workshop: string, commissionId: number): void;
+/**
+ * List active commission worktrees.
+ */
+export declare function listWorktrees(home: string, workshop?: string): WorktreeResult[];
+//# sourceMappingURL=worktree.d.ts.map

package/dist/worktree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree.d.ts","sourceRoot":"","sources":["../src/worktree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAOH,MAAM,WAAW,cAAc;IAC7B,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,YAAY,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,YAAY,EAAE,MAAM,CAAC;CACtB;AAMD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CAqBpE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAmB3F;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,cAAc,EAAE,CAiC/E"}