dorfl 0.0.0 → 0.1.0

package/dist/apply-merge-action.js

@@ -0,0 +1,307 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { allAnswered, isEntryAnswered, parseSidecar, sidecarPathFor, } from './sidecar.js';
+import { run as runProc } from './git.js';
+import { createJob } from './workspace.js';
+import { performIntegration, } from './integration-core.js';
+/**
+ * Parse the human's plain free-text answer into the deterministic
+ * {@link MergeActionVerb}. The merge-question surfacer renders
+ * `merge | hold | drop` in the entry's `default` as a human-readable hint, so
+ * the human typically types one of those words verbatim. We accept any text
+ * whose first whole word (case-insensitive) is one of `merge` / `hold` / `drop`
+ * — this is the same machine-parseable choice shape the surfacer's applied
+ * answer q1 documents ("a DETERMINISTIC CHOICE shape … the human picks and the
+ * system parses unambiguously").
+ *
+ * Returns `undefined` on ANYTHING else (an empty answer, a typo, a long
+ * narrative without one of the three words at the start) so the caller can
+ * route the ambiguity HONESTLY — never default-to-merge on a malformed answer,
+ * which would invent a land the human did not authorise.
+ */
+export function parseMergeAnswer(text) {
+    const trimmed = text.trim().toLowerCase();
+    if (trimmed === '')
+        return undefined;
+    // The first whole alphabetic word; trailing punctuation (a comma, em-dash,
+    // period) and any following commentary are tolerated. We deliberately do
+    // NOT consume hyphens / apostrophes — the three verbs are plain ASCII
+    // words, and over-tolerating typo-shapes would silently invent a verb the
+    // human did not pick.
+    const match = /^([a-z]+)/.exec(trimmed);
+    if (match === null)
+        return undefined;
+    const word = match[1];
+    if (word === 'merge' || word === 'hold' || word === 'drop') {
+        return word;
+    }
+    return undefined;
+}
+/**
+ * Detect the FIRST answered `kind: merge` entry's deterministic action verb in
+ * a fully-answered sidecar (the apply rung's pre-decider kind-check). Returns
+ * `undefined` when the sidecar carries no answered `kind: merge` entry (the
+ * apply rung then proceeds to the existing path — agentic for observations,
+ * normal apply for task/prd content questions).
+ *
+ * The sidecar is read OFF DISK keyed off the namespaced item identity; the
+ * model is parsed via the SAME `parseSidecar` the rest of the engine uses.
+ * Returns `undefined` on a missing/unparseable sidecar (the caller's normal
+ * apply path will then raise the right error).
+ */
+export function detectAnsweredMergeAction(cwd, item) {
+    const abs = join(cwd, sidecarPathFor(item));
+    if (!existsSync(abs))
+        return undefined;
+    let model;
+    try {
+        model = parseSidecar(readFileSync(abs, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+    if (!allAnswered(model))
+        return undefined;
+    for (const entry of model.entries) {
+        if (entry.kind !== 'merge')
+            continue;
+        if (!isEntryAnswered(entry))
+            continue;
+        const verb = parseMergeAnswer(entry.answer);
+        if (verb !== undefined) {
+            return { verb, entry };
+        }
+    }
+    return undefined;
+}
+/**
+ * Resolve the arbiter URL the land worktree mirrors from. Prefers the
+ * caller-supplied `arbiterUrl` (the registry-set advance driver knows it
+ * directly); falls back to `git remote get-url <arbiter>` in the apply rung's
+ * `cwd` (the in-place / one-shot caller). Returns `undefined` when the URL
+ * cannot be resolved — the caller maps that to a clean refusal.
+ */
+function resolveArbiterUrl(input) {
+    if (input.arbiterUrl !== undefined && input.arbiterUrl !== '') {
+        return input.arbiterUrl;
+    }
+    const res = runProc('git', ['remote', 'get-url', input.arbiter], input.cwd, {
+        env: input.env,
+    });
+    if (res.status !== 0)
+        return undefined;
+    const url = res.stdout.trim();
+    return url === '' ? undefined : url;
+}
+/**
+ * The `strictMergeApproval` re-stale check (PRD OQ6 opt-in): did `<arbiter>/
+ * main` move past the merge-base of the work branch since the surfacer
+ * authored the question? The git-alone analogue of GitHub's "dismiss stale
+ * approvals when the base changes" — host-agnostic by reachability.
+ *
+ * We fetch the latest `<arbiter>/main` from the JOB worktree's hub mirror (the
+ * worktree's `origin`), compute `merge-base(<branch>, <origin/main>)`, and
+ * compare against `<origin/main>` itself: if the merge-base IS `<origin/main>`,
+ * the branch is a strict descendant — the merge-base did NOT move — and the
+ * cheap default applies (HONOUR + land on green re-verify). If the merge-base
+ * is NOT `<origin/main>`, `main` advanced past the branch's divergence point
+ * since the branch was last rebased — the merge-base MOVED — and the strict
+ * mode re-surfaces.
+ *
+ * Returns `true` when the merge-base moved (⇒ re-surface), `false` otherwise.
+ * On any plumbing failure returns `false` (do NOT spuriously re-surface — the
+ * red re-verify is still the load-bearing safety; a transient git failure must
+ * not block a clean answer-then-land).
+ */
+function mergeBaseMoved(job, env) {
+    const fetch = runProc('git', [
+        'fetch',
+        '--quiet',
+        job.arbiterRemote,
+        `+refs/heads/main:refs/remotes/${job.arbiterRemote}/main`,
+    ], job.dir, { env });
+    if (fetch.status !== 0)
+        return false;
+    const mainRef = `${job.arbiterRemote}/main`;
+    const mainSha = runProc('git', ['rev-parse', '--verify', '--quiet', mainRef], job.dir, { env });
+    if (mainSha.status !== 0)
+        return false;
+    const base = runProc('git', ['merge-base', 'HEAD', mainRef], job.dir, { env });
+    if (base.status !== 0)
+        return false;
+    return base.stdout.trim() !== mainSha.stdout.trim();
+}
+/**
+ * The PRODUCTION dispatcher: an answered `kind: merge` entry's verb drives one
+ * of the four terminals (`landed` / `refused` / `restale` / `hold|drop`). For
+ * `answer=merge` it checks out the unmerged `work/<slug>` via the EXISTING
+ * `workspace.ts` per-job worktree seam ({@link createJob}, the same seam the
+ * build / recovery callers use) and invokes the LAND primitive
+ * ({@link performIntegration}) with `committedRecovery: true` +
+ * `freshWorktreeGate: true` — so the rebased tip is re-verified BEFORE it
+ * lands, the answered-merge land path NEVER integrates a clean-rebase-but-
+ * broken tree, and a refusal routes to needs-attention through the SAME
+ * shared seam (`applyNeedsAttentionTransition`) the build path uses. The job
+ * worktree is always disposed (success or failure) so the hub mirror does not
+ * accumulate stale per-job state.
+ *
+ * For `answer=hold` and `answer=drop` the dispatcher does not land — it just
+ * tells the apply rung to fall through to the normal answer-recording path.
+ * (Cancellation of the work branch on `drop` is OUT OF SCOPE; the answer is
+ * recorded and a future surfacer / human handles the artifact.)
+ */
+export async function performMergeAction(input) {
+    const note = input.note ?? (() => { });
+    const { verb } = input.action;
+    if (verb === 'hold') {
+        return {
+            outcome: 'hold',
+            message: `merge-question for ${input.item} answered HOLD — leaving \`work/${input.slug}\` ` +
+                `unmerged (the answer is recorded in the item body).`,
+        };
+    }
+    if (verb === 'drop') {
+        return {
+            outcome: 'drop',
+            message: `merge-question for ${input.item} answered DROP — leaving \`work/${input.slug}\` ` +
+                `unmerged (the answer is recorded; cancellation of the work branch is ` +
+                `out of this dispatcher's scope).`,
+        };
+    }
+    // verb === 'merge'
+    const url = resolveArbiterUrl(input);
+    if (url === undefined) {
+        return {
+            outcome: 'refused',
+            message: `merge-question for ${input.item} answered MERGE — but the arbiter URL ` +
+                `could not be resolved (no arbiterUrl threaded, and \`git remote get-url ` +
+                `${input.arbiter}\` failed in ${input.cwd}). NOT landing; the answer ` +
+                `stays surfaced.`,
+        };
+    }
+    // Check out the unmerged `work/<type>-<slug>` via the EXISTING per-job
+    // worktree seam — the SAME seam build/recovery callers use, NOT a bespoke
+    // worktree or clone. The job dir is the worktree `performIntegration` works
+    // from; its `arbiterRemote` is the worktree's `origin` (a bare-hub remote
+    // that mirrors the real arbiter), which the integration core push-targets.
+    let job;
+    try {
+        job = createJob({
+            url,
+            slug: input.slug,
+            type: 'task',
+            workspacesDir: input.workspacesDir,
+            env: input.env,
+        });
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        return {
+            outcome: 'refused',
+            message: `merge-question for ${input.item} answered MERGE — but checking out ` +
+                `\`work/${input.slug}\` via the per-job worktree seam failed (${detail}). ` +
+                `NOT landing; the answer stays surfaced.`,
+        };
+    }
+    try {
+        // CONTINUE-rebase-conflict: createJob's CONTINUE-rebase aborted on a
+        // genuine code conflict. The kept work stays on the branch (recoverable);
+        // we refuse the land and route via the standard refusal shape.
+        if (job.continueRebaseConflict) {
+            return {
+                outcome: 'refused',
+                message: `merge-question for ${input.item} answered MERGE — but rebasing ` +
+                    `\`work/${input.slug}\` onto current main conflicted (the kept work is ` +
+                    `intact on the branch; resolve and re-answer). NOT landing.`,
+            };
+        }
+        if (job.continuePushFailure !== undefined) {
+            return {
+                outcome: 'refused',
+                message: `merge-question for ${input.item} answered MERGE — but the ` +
+                    `continue-rebase push to the arbiter failed (${job.continuePushFailure}). ` +
+                    `NOT landing; the kept work is intact on the branch.`,
+            };
+        }
+        // STRICT re-stale check (OQ6 opt-in): when ON and the merge-base moved
+        // between the surfacer's question and this apply, RE-SURFACE the
+        // merge-question (the apply rung folds this into a re-pause) instead of
+        // landing. Default OFF ⇒ this block is skipped; the cheap "green
+        // re-verify is enough" path runs.
+        if (input.strictMergeApproval === true && mergeBaseMoved(job, input.env)) {
+            return {
+                outcome: 'restale',
+                message: `merge-question for ${input.item} answered MERGE — but ` +
+                    `strictMergeApproval is ON and the merge-base of \`work/${input.slug}\` ` +
+                    `moved between answer and apply: RE-SURFACING the merge-question ` +
+                    `(no land; the human re-confirms against the new base).`,
+            };
+        }
+        // LAND through the EXISTING `performIntegration`. The branch's tip
+        // already carries its done-move commit (surfacer enumerates `work/*`
+        // unreachable from main, so it is a previously-built strand), so we
+        // drive the committed-recovery tail — but with `freshWorktreeGate: true`
+        // so the REBASED TIP is re-verified BEFORE the integrate (the
+        // `committed-recovery-honours-fresh-worktree-gate` task's contract).
+        const integration = await performIntegration({
+            cwd: job.dir,
+            arbiter: job.arbiterRemote,
+            slug: input.slug,
+            source: 'tasks-ready',
+            recovering: false,
+            committedRecovery: true,
+            freshWorktreeGate: true,
+            prepare: input.prepare,
+            verify: input.verify,
+            mode: 'merge',
+            // surfaceArbiter is set so a RED rebased-tip gate (or a rebase
+            // conflict surfaced during the retry loop) routes to needs-attention
+            // observably on the arbiter (not local-only). The build path uses
+            // this shape; we mirror it here for the answered-merge land.
+            surfaceArbiter: job.arbiterRemote,
+            recoveryRebaseRetries: input.recoveryRebaseRetries,
+            recoveryRebaseJitterMs: input.recoveryRebaseJitterMs,
+            mergeRetries: input.mergeRetries,
+            env: input.env,
+            note,
+        });
+        if (integration.outcome === 'completed') {
+            return {
+                outcome: 'landed',
+                message: `merge-question for ${input.item} answered MERGE — landed ` +
+                    `\`work/${input.slug}\` on \`${job.arbiterRemote}/main\` via the ` +
+                    `land primitive (rebase → re-verify on the rebased tip → advance).`,
+                integration,
+            };
+        }
+        if (integration.outcome === 'already-integrated') {
+            return {
+                outcome: 'already-integrated',
+                message: `merge-question for ${input.item} answered MERGE — \`work/${input.slug}\` ` +
+                    `was already on \`${job.arbiterRemote}/main\` (idempotent re-run).`,
+                integration,
+            };
+        }
+        // gate-failed / prepare-failed / review-blocked / review-unparseable /
+        // rebase-conflict / invariant-violation: the land was REFUSED;
+        // performIntegration routed the bounce per its own shared seam (gated by
+        // `surfaceArbiter`), so `main` never received a failing tree.
+        return {
+            outcome: 'refused',
+            message: integration.reason ??
+                `merge-question for ${input.item} answered MERGE — the land was REFUSED ` +
+                    `(${integration.outcome}); NOT landing; the answer stays surfaced.`,
+            integration,
+        };
+    }
+    finally {
+        try {
+            job.dispose();
+        }
+        catch {
+            // Best-effort: a failed dispose leaves a reapable per-job worktree
+            // behind, which `gc` cleans up. Never crash the dispatch on teardown.
+        }
+    }
+}
+//# sourceMappingURL=apply-merge-action.js.map

package/dist/apply-merge-action.js.map

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

package/dist/apply-persist.d.ts

@@ -0,0 +1,174 @@
+import { type NewQuestion } from './sidecar.js';
+import { APPLY_LIFECYCLE_FOLDERS, resolveItemPathByIdentity } from './item-path.js';
+/**
+ * The engine-owned APPLY PERSIST (prd `advance-loop`, task `advance-rung-apply`;
+ * AGENTIC apply, task `agentic-apply-retire-disposition-vocabulary`) — the half of
+ * the APPLY rung the ENGINE owns. On `classify=apply` (ALL sidecar entries
+ * answered), it applies the HUMAN's answers to the item ATOMICALLY (item body +
+ * sidecar in ONE commit, via the sidecar contract's {@link applyAtomic}), then
+ * EITHER:
+ *
+ *   - **append / re-pause** — when the apply has NEW questions to ask: append
+ *     `qN+1…`, stay `needsAnswers:true`, re-pause (the "all answered?" flips back
+ *     to false); OR
+ *   - **discharge by deletion** — when the caller decided the SOURCE should leave
+ *     by deletion (`discharge` set): `git rm` the source + sidecar in a STANDALONE
+ *     revertible commit, the reason in the commit message (git history is the
+ *     archive); OR
+ *   - **resolve fully** (the default) — clear `needsAnswers` + DELETE the sidecar
+ *     in the SAME atomic commit (the invariant `needsAnswers:false ⟺ no active
+ *     sidecar`); the item advances toward build by its normal lifecycle.
+ *
+ * **The disposition vocabulary is GONE** (task
+ * `agentic-apply-retire-disposition-vocabulary`): the apply rung no longer reads a
+ * per-entry `disposition=` token, no longer runs a most-decisive picker, and has
+ * no `keep`/`triaged:keep` resting state. A sidecar entry is BINARY (no-answer |
+ * answered); what to DO with a fully-answered OBSERVATION is decided by the
+ * AGENTIC apply decision in the advance tick (`advance.ts` `applyRung` over the
+ * shared `decide` engine), which then routes here (re-pause / discharge / via
+ * `promoteObservation` for a mint). A signal is still-open, acted-on, or deleted
+ * — there is no \"retain as resolved\" state.
+ *
+ * The work-item (task/prd) terminal MOVES (`tasks/cancelled`, `prds/dropped`) and
+ * the `needs-attention/` LIFECYCLE state are a SEPARATE lifecycle concern (a
+ * task/prd is dropped by its own lifecycle, not by a question answer) — they are
+ * NOT routed from here any more (they were the removed disposition vocabulary).
+ *
+ * It is the SIBLING of {@link import('./surface-persist.js').persistSurfacedQuestions}:
+ * that is the SURFACE rung's one-commit primitive (append-or-create + set
+ * `needsAnswers`); this is the APPLY rung's (apply answers + resolve / re-pause /
+ * discharge). Kept file-orthogonal so the rung bodies land in different tasks.
+ *
+ * **NEVER invents an answer (US #4).** The apply rung applies ONLY what the human
+ * authored — the recorded `answer:` text. It does NOT fill, guess, or author an
+ * answer; a SUBSET-answered sidecar is not even classified `apply` (the classifier
+ * NO-OPs), so this is only ever called with a fully-answered sidecar. **ALWAYS
+ * allowed (no gate)** — applying a human's answer is never gated, even with every
+ * autonomy flag off (the engine, not this module, enforces the no-gate
+ * sequencing).
+ *
+ * Like the surface persist, this is the LOCAL one-commit primitive over a working
+ * tree (the throwaway-git-repo test pattern). The `advancing` CAS lock that makes
+ * it WINNER-ONLY is held by `performAdvance` BEFORE this is called; this module
+ * does NOT race the arbiter — that is the lock's job.
+ */
+export { APPLY_LIFECYCLE_FOLDERS, resolveItemPathByIdentity };
+/** Marker that opens the applied-answers record in an item body. */
+declare const APPLIED_HEADING = "## Applied answers";
+/**
+ * The STRUCTURAL fence the templates wrap the transient open-questions block in
+ * — an HTML-comment marker pair, mirroring the existing `<!-- dorfl-…
+ * -->` style in `sidecar.ts`. Apply's reconcile (full-resolution route only)
+ * strips everything between the OPEN and CLOSE markers (inclusive) when it folds
+ * answers in and clears `needsAnswers`, so the resolved item body reads as
+ * resolved (no leftover "these are still open" prose above `## Applied answers`).
+ *
+ * The strip is STRUCTURAL (marker-pair based), NOT a heading-text regex — the
+ * prd's D1 decision: a `## Open questions` heading match would be fragile to
+ * author wording (`## Open questions (clear needsAnswers when resolved)` vs.
+ * `## Open questions`). Items authored WITHOUT the markers are left untouched
+ * (backward compat — no marker ⇒ nothing to strip ⇒ identical bytes).
+ *
+ * The sibling task `templates-mark-transient-open-questions-block` introduces
+ * the markers in the prd/task templates; this task exports the constants so
+ * the two tasks agree on the literal byte sequence.
+ */
+export declare const OPEN_QUESTIONS_MARKER_OPEN = "<!-- open-questions -->";
+export declare const OPEN_QUESTIONS_MARKER_CLOSE = "<!-- /open-questions -->";
+export interface ApplyAnsweredQuestionsOptions {
+    /** Working clone/worktree the apply commits in. */
+    cwd: string;
+    /** The namespaced item identity (`task:foo` / `prd:bar` / `observation:baz`). */
+    item: string;
+    /**
+     * The item file path RELATIVE to `cwd` (e.g. `work/backlog/foo.md`). The
+     * sidecar path is derived from the identity, NOT from this path (identity-keyed,
+     * folder-agnostic). The apply rewrites THIS file + the sidecar and commits them
+     * together.
+     */
+    itemPath: string;
+    /**
+     * NEW follow-up questions the apply has (the agentic `ask-follow-up` verdict, or
+     * a caller-supplied batch). When non-empty, the apply APPENDS them (`qN+1…`,
+     * never mutating an answered entry) and RE-PAUSES (`needsAnswers:true` stays) —
+     * the "all answered?" flips back to false. Empty/omitted ⇒ resolve the item (or
+     * discharge it, when `discharge` is set).
+     */
+    appendQuestions?: NewQuestion[];
+    /**
+     * DISCHARGE the SOURCE by DELETION (the agentic `delete-source` verdict, or a
+     * direct discharge): instead of resolving in place, `git rm` the source + its
+     * answered sidecar in a STANDALONE revertible commit, the `reason` recorded in
+     * the commit message (git history is the archive). Fires DIRECT (no
+     * preview/confirm — decision 12). Mutually exclusive with `appendQuestions`
+     * (re-pause and discharge cannot both happen on one apply); when both are given
+     * the re-pause wins (you cannot discharge a source you are still asking about).
+     */
+    discharge?: {
+        reason: string;
+    };
+    /** Advisory committer id for the commit subject. Defaults to git user.name. */
+    by?: string;
+    /** Environment for child git processes. */
+    env?: NodeJS.ProcessEnv;
+    /** Sink for human-readable progress notes. */
+    note?: (message: string) => void;
+}
+/** The terminal an apply reached. */
+export type ApplyTerminal = 
+/** Resolved fully: needsAnswers cleared + sidecar deleted (the default). */
+'resolved'
+/** New questions appended; stayed needsAnswers:true and re-paused. */
+ | 'repaused'
+/**
+ * The SOURCE was DISCHARGED BY DELETION (the agentic `delete-source` verdict, or
+ * a direct discharge): the source (+ its answered sidecar) were `git rm`-ed in a
+ * STANDALONE revertible commit, the reason recorded in the commit message (git
+ * history = archive). A discharged item leaves by being GONE — there is no
+ * resting marker. This is the apply rung applying the human's RATIFIED answer
+ * (human-authored, not a unilateral agent destruction of a live signal).
+ */
+ | 'deleted'
+/**
+ * The item file was GONE by the time apply tried to write (a concurrent
+ * promote/terminal-move/delete between capture and write). Apply exited
+ * CLEAN: no commit, no ghost file at the stale path. The matching benign
+ * skip the surface/triage rungs already use (`advance.ts` `vanishedSkip`),
+ * extended into the apply rung by the F3a folder-agnostic resolver.
+ */
+ | 'vanished';
+export interface ApplyAnsweredQuestionsResult {
+    /** The terminal the apply reached. */
+    outcome: ApplyTerminal;
+    /** The commit sha the apply produced. */
+    commit?: string;
+    /** The sidecar path (relative to `cwd`) the apply touched. */
+    sidecarPath: string;
+    /** The item path (relative to `cwd`) after the apply. */
+    itemPath: string;
+    /** A human-readable summary. */
+    message: string;
+}
+/** Raised for usage errors (a missing repo, an unreadable item, a subset apply). */
+export declare class ApplyPersistError extends Error {
+    constructor(message: string);
+}
+/**
+ * Apply a FULLY-ANSWERED sidecar's answers to its item ATOMICALLY, then route it.
+ * The keystone APPLY rung the advance engine dispatches into once the classifier
+ * said `apply` (all entries answered) AND the `advancing` lock was won.
+ *
+ * The decision (the human's recorded intent + the caller's routing — NEVER an
+ * invention):
+ *
+ *   1. **append / re-pause** — `appendQuestions` is non-empty: append `qN+1…`,
+ *      keep `needsAnswers:true`, re-pause (one commit, body + sidecar).
+ *   2. **discharge by deletion** — `discharge` is set (the `delete-source`
+ *      verdict): `git rm` the source + sidecar in a standalone revertible commit,
+ *      the reason in the commit message.
+ *   3. **resolve fully** (the default) — clear `needsAnswers` + delete the sidecar
+ *      in ONE commit; the item advances toward build by its normal lifecycle.
+ */
+export declare function applyAnsweredQuestions(options: ApplyAnsweredQuestionsOptions): ApplyAnsweredQuestionsResult;
+export { APPLIED_HEADING };
+//# sourceMappingURL=apply-persist.d.ts.map

package/dist/apply-persist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-persist.d.ts","sourceRoot":"","sources":["../src/apply-persist.ts"],"names":[],"mappings":"AAIA,OAAO,EAKN,KAAK,WAAW,EAGhB,MAAM,cAAc,CAAC;AACtB,OAAO,EACN,uBAAuB,EACvB,yBAAyB,EACzB,MAAM,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAMH,OAAO,EAAC,uBAAuB,EAAE,yBAAyB,EAAC,CAAC;AAE5D,oEAAoE;AACpE,QAAA,MAAM,eAAe,uBAAuB,CAAC;AAE7C;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,0BAA0B,4BAA4B,CAAC;AACpE,eAAO,MAAM,2BAA2B,6BAA6B,CAAC;AAEtE,MAAM,WAAW,6BAA6B;IAC7C,mDAAmD;IACnD,GAAG,EAAE,MAAM,CAAC;IACZ,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,WAAW,EAAE,CAAC;IAChC;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE;QAAC,MAAM,EAAE,MAAM,CAAA;KAAC,CAAC;IAC7B,+EAA+E;IAC/E,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,2CAA2C;IAC3C,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,8CAA8C;IAC9C,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAED,qCAAqC;AACrC,MAAM,MAAM,aAAa;AACxB,4EAA4E;AAC1E,UAAU;AACZ,sEAAsE;GACpE,UAAU;AACZ;;;;;;;GAOG;GACD,SAAS;AACX;;;;;;GAMG;GACD,UAAU,CAAC;AAEd,MAAM,WAAW,4BAA4B;IAC5C,sCAAsC;IACtC,OAAO,EAAE,aAAa,CAAC;IACvB,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,WAAW,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,oFAAoF;AACpF,qBAAa,iBAAkB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI3B;AAsID;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CACrC,OAAO,EAAE,6BAA6B,GACpC,4BAA4B,CAyH9B;AA8DD,OAAO,EAAC,eAAe,EAAC,CAAC"}