memkin 0.4.2 → 0.4.4

package/dist/apply/candidate-selection.d.ts

@@ -0,0 +1,60 @@
+import type { DistilledSignal } from "../distiller/contract.js";
+import type { StoredPayload } from "../store/distilled-payload.js";
+import type { SqlConn } from "../store/sql-executor.js";
+import { type ApplyAction, type ApplyPlanData, type ApplyTarget, type Candidate } from "./types.js";
+export declare const DEFAULT_CANDIDATE_LIMIT = 5;
+/** The LLM's decision for one signal against its candidate set. */
+export interface CandidateDecision {
+    action: ApplyAction;
+    target_slug?: string | null;
+    reason?: string;
+}
+/** Pluggable decider — a thin LLM seam so tests can mock it deterministically. */
+export interface CandidateDecider {
+    decide(input: {
+        signal: DistilledSignal;
+        candidates: Candidate[];
+        target: ApplyTarget;
+    }): Promise<CandidateDecision>;
+}
+/** Source of candidate pages, scoped to one target schema. */
+export interface CandidateRepository {
+    findCandidates(signal: DistilledSignal, limit: number): Promise<Candidate[]>;
+}
+/**
+ * Read candidate pages from a target schema. Trigram-ranked against the signal's
+ * topic + what, restricted to the v2 candidate pool (spec §3.1 / §7).
+ */
+export declare class SchemaCandidateRepository implements CandidateRepository {
+    private readonly pg;
+    private readonly schema;
+    constructor(pg: SqlConn, target: ApplyTarget);
+    findCandidates(signal: DistilledSignal, limit: number): Promise<Candidate[]>;
+}
+/**
+ * Build the apply plan for one payload against one target. Pure orchestration —
+ * no writes; the returned data is what ApplyPlanStore.save persists.
+ */
+export declare function buildApplyPlan(params: {
+    payload: StoredPayload;
+    target: ApplyTarget;
+    repo: CandidateRepository;
+    decider: CandidateDecider;
+    candidateLimit?: number;
+}): Promise<ApplyPlanData>;
+export interface StoredApplyPlan {
+    id: number;
+    payloadId: number;
+    target: ApplyTarget;
+    data: ApplyPlanData;
+}
+/** Persists / retrieves frozen apply plans (one per payload+target). */
+export declare class ApplyPlanStore {
+    private readonly pg;
+    constructor(pg: SqlConn);
+    /** Upsert the plan for (payload_id, target); returns the plan id. */
+    save(data: ApplyPlanData): Promise<number>;
+    getById(id: number): Promise<StoredApplyPlan | null>;
+    getByPayloadTarget(payloadId: number, target: ApplyTarget): Promise<StoredApplyPlan | null>;
+}
+//# sourceMappingURL=candidate-selection.d.ts.map

package/dist/apply/candidate-selection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"candidate-selection.d.ts","sourceRoot":"","sources":["../../src/apply/candidate-selection.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAExD,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,SAAS,EAGf,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAGzC,mEAAmE;AACnE,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,WAAW,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,kFAAkF;AAClF,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,KAAK,EAAE;QACZ,MAAM,EAAE,eAAe,CAAC;QACxB,UAAU,EAAE,SAAS,EAAE,CAAC;QACxB,MAAM,EAAE,WAAW,CAAC;KACrB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAChC;AAED,8DAA8D;AAC9D,MAAM,WAAW,mBAAmB;IAClC,cAAc,CAAC,MAAM,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;CAC9E;AAQD;;;GAGG;AACH,qBAAa,yBAA0B,YAAW,mBAAmB;IAIjE,OAAO,CAAC,QAAQ,CAAC,EAAE;IAHrB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAGb,EAAE,EAAE,OAAO,EAC5B,MAAM,EAAE,WAAW;IAKf,cAAc,CAAC,MAAM,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;CAuCnF;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE;IAC3C,OAAO,EAAE,aAAa,CAAC;IACvB,MAAM,EAAE,WAAW,CAAC;IACpB,IAAI,EAAE,mBAAmB,CAAC;IAC1B,OAAO,EAAE,gBAAgB,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,GAAG,OAAO,CAAC,aAAa,CAAC,CAuEzB;AAUD,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,WAAW,CAAC;IACpB,IAAI,EAAE,aAAa,CAAC;CACrB;AAOD,wEAAwE;AACxE,qBAAa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,OAAO;IAExC,qEAAqE;IAC/D,IAAI,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC;IAW1C,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAKpD,kBAAkB,CACtB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;CAOnC"}

package/dist/apply/candidate-selection.js

@@ -0,0 +1,159 @@
+// src/apply/candidate-selection.ts
+//
+// Restricted upsert candidate selection (spec §7). For each signal in a
+// distilled payload this picks one of five actions —
+// NEW | UPDATE | SUPERSEDE | LINK_EXISTING | NOOP — against a top-5 candidate
+// pool drawn from the CURRENT TARGET's schema (staging candidates ≠ production
+// candidates). The result is frozen into an apply_plan(payload_id, target); the
+// apply engine later replays that plan WITHOUT calling the LLM again (spec §6.2).
+//
+// Guardrails:
+//   - Authority admissibility (spec §5): session-log-only signals become NOOP
+//     and never reach the LLM (no candidate page is created for them).
+//   - Candidate pool is restricted (pre-legacy-cleanup) to v2-pipeline pages +
+//     identity entity pages (spec §3.1).
+//   - Restricted actions (UPDATE/SUPERSEDE/LINK_EXISTING) must reference a slug
+//     that is actually in the offered candidate set; an out-of-pool pick is
+//     coerced to NEW so the LLM can never point at an arbitrary page.
+import { admissibility } from "../distiller/authority-matrix.js";
+import { contributionId, normalizeTopic, signalFamilyKey } from "./ids.js";
+import { ENTITY_PAGE_TYPES, } from "./types.js";
+export const DEFAULT_CANDIDATE_LIMIT = 5;
+const BODY_TRUNCATE = 1000;
+function truncate(s) {
+    return s.length > BODY_TRUNCATE ? `${s.slice(0, BODY_TRUNCATE)}…` : s;
+}
+const RESTRICTED_ACTIONS = new Set(["UPDATE", "SUPERSEDE", "LINK_EXISTING"]);
+/**
+ * Read candidate pages from a target schema. Trigram-ranked against the signal's
+ * topic + what, restricted to the v2 candidate pool (spec §3.1 / §7).
+ */
+export class SchemaCandidateRepository {
+    pg;
+    schema;
+    constructor(pg, target) {
+        this.pg = pg;
+        this.schema = target === "staging" ? "staging" : "public";
+    }
+    async findCandidates(signal, limit) {
+        const probe = `${signal.topic} ${signal.what}`.trim();
+        const rows = await this.pg.query(`SELECT p.slug, p.title,
+              LEFT(p.compiled_truth, ${BODY_TRUNCATE}) AS body,
+              p.updated_at::text AS updated_at,
+              p.content_hash,
+              p.frontmatter->>'project' AS project,
+              (
+                SELECT COALESCE(string_agg(mc.signal->>'what', '; '), '')
+                FROM ${this.schema}.memory_contributions mc
+                WHERE mc.canonical_page_id = p.id AND mc.active
+              ) AS contributions_summary
+         FROM ${this.schema}.pages p
+        WHERE (p.frontmatter->>'pipeline' = 'v2' OR p.type = ANY($2::text[]))
+          AND GREATEST(similarity(p.title, $1), similarity(p.compiled_truth, $1)) > 0
+        ORDER BY GREATEST(similarity(p.title, $1), similarity(p.compiled_truth, $1)) DESC,
+                 p.updated_at DESC
+        LIMIT $3`, [probe, ENTITY_PAGE_TYPES, limit]);
+        return rows.rows.map((r) => ({
+            slug: r.slug,
+            title: r.title,
+            body: truncate(r.body ?? ""),
+            updated_at: r.updated_at,
+            content_hash: r.content_hash,
+            project: r.project,
+            contributions_summary: r.contributions_summary ?? "",
+        }));
+    }
+}
+/**
+ * Build the apply plan for one payload against one target. Pure orchestration —
+ * no writes; the returned data is what ApplyPlanStore.save persists.
+ */
+export async function buildApplyPlan(params) {
+    const { payload, target, repo, decider } = params;
+    const limit = params.candidateLimit ?? DEFAULT_CANDIDATE_LIMIT;
+    const actions = [];
+    const signals = payload.payload.signals;
+    for (let i = 0; i < signals.length; i++) {
+        const signal = signals[i];
+        const normalizedTopic = normalizeTopic(signal.topic);
+        const cid = contributionId(payload.revisionId, signal.type, normalizedTopic);
+        const fam = signalFamilyKey(payload.sourceInstance, payload.sessionId, signal.type, normalizedTopic);
+        const base = {
+            signal_index: i,
+            signal,
+            contribution_id: cid,
+            signal_family_key: fam,
+            normalized_topic: normalizedTopic,
+        };
+        // Authority gate (spec §5): session-log-only signals never create a page.
+        if (admissibility(signal.type, signal.authority) === "session_log_only") {
+            actions.push({
+                ...base,
+                action: "NOOP",
+                target_slug: null,
+                target_content_hash: null,
+                candidates: [],
+                reason: "session_log_only (authority admissibility)",
+            });
+            continue;
+        }
+        const candidates = await repo.findCandidates(signal, limit);
+        const decision = await decider.decide({ signal, candidates, target });
+        let action = decision.action;
+        let targetSlug = decision.target_slug ?? null;
+        let reason = decision.reason ?? "";
+        let contentHash = null;
+        if (RESTRICTED_ACTIONS.has(action)) {
+            const match = candidates.find((c) => c.slug === targetSlug);
+            if (!match) {
+                // Out-of-pool pick — coerce to NEW rather than trust an arbitrary slug.
+                action = "NEW";
+                targetSlug = null;
+                reason = `${reason} [coerced to NEW: target not in candidate pool]`.trim();
+            }
+            else {
+                contentHash = match.content_hash;
+            }
+        }
+        else if (action === "NOOP") {
+            targetSlug = null;
+        }
+        actions.push({
+            ...base,
+            action,
+            target_slug: targetSlug,
+            target_content_hash: contentHash,
+            candidates,
+            reason,
+        });
+    }
+    return { payload_id: payload.id, target, actions };
+}
+function parsePlan(row) {
+    const data = typeof row.plan === "string" ? JSON.parse(row.plan) : row.plan;
+    return { id: row.id, payloadId: row.payload_id, target: row.target, data };
+}
+/** Persists / retrieves frozen apply plans (one per payload+target). */
+export class ApplyPlanStore {
+    pg;
+    constructor(pg) {
+        this.pg = pg;
+    }
+    /** Upsert the plan for (payload_id, target); returns the plan id. */
+    async save(data) {
+        const r = await this.pg.query(`INSERT INTO apply_plan (payload_id, target, plan)
+       VALUES ($1, $2, $3::jsonb)
+       ON CONFLICT (payload_id, target) DO UPDATE SET plan = EXCLUDED.plan
+       RETURNING id`, [data.payload_id, data.target, JSON.stringify(data)]);
+        return r.rows[0].id;
+    }
+    async getById(id) {
+        const r = await this.pg.query("SELECT * FROM apply_plan WHERE id = $1", [id]);
+        return r.rows[0] ? parsePlan(r.rows[0]) : null;
+    }
+    async getByPayloadTarget(payloadId, target) {
+        const r = await this.pg.query("SELECT * FROM apply_plan WHERE payload_id = $1 AND target = $2", [payloadId, target]);
+        return r.rows[0] ? parsePlan(r.rows[0]) : null;
+    }
+}
+//# sourceMappingURL=candidate-selection.js.map

package/dist/apply/candidate-selection.js.map

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

package/dist/apply/cutover.d.ts

@@ -0,0 +1,45 @@
+import type { AgentPipelineMode } from "../core/config.js";
+import type { SqlExecutor } from "../store/sql-executor.js";
+import { type CandidateDecider, type CandidateRepository } from "./candidate-selection.js";
+import { type ApplyOutcome } from "./engine.js";
+import { type RollbackOutcome } from "./rollback.js";
+export interface CutoverDeps {
+    executor: SqlExecutor;
+    /** Decides the restricted upsert action per signal (LLM seam; mockable). */
+    decider: CandidateDecider;
+    /** Override the production candidate repository (defaults to the public schema). */
+    repo?: CandidateRepository;
+    candidateLimit?: number;
+}
+export interface CutoverOutcome {
+    payloadId: number;
+    /** The persisted production apply_plan id (freshly regenerated, not the staging one). */
+    planId: number;
+    /** The apply engine result (target is always "production"). */
+    apply: ApplyOutcome;
+    /** True when the apply failed / dead-lettered → flip the source flag to legacy. */
+    recommendLegacyFallback: boolean;
+    /** The mode to flip back to when recommendLegacyFallback is set. */
+    fallbackMode: AgentPipelineMode;
+}
+export interface CutoverRollbackOutcome {
+    rollback: RollbackOutcome;
+    /** After a rollback, the source flag should return to legacy to stop the bleeding. */
+    fallbackMode: AgentPipelineMode;
+}
+export declare class Cutover {
+    private readonly deps;
+    private readonly payloads;
+    private readonly plans;
+    private readonly engine;
+    private readonly rollbacker;
+    constructor(deps: CutoverDeps);
+    /** Regenerate the production plan for one existing payload and apply it. */
+    run(payloadId: number): Promise<CutoverOutcome>;
+    /**
+     * Roll back a cutover apply via the PR-4 contributions-based rollback and
+     * signal that the source flag should return to legacy (spec §3.1).
+     */
+    rollback(attemptId: number): Promise<CutoverRollbackOutcome>;
+}
+//# sourceMappingURL=cutover.d.ts.map

package/dist/apply/cutover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cutover.d.ts","sourceRoot":"","sources":["../../src/apply/cutover.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EAGzB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAe,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAiB,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAKpE,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,WAAW,CAAC;IACtB,4EAA4E;IAC5E,OAAO,EAAE,gBAAgB,CAAC;IAC1B,oFAAoF;IACpF,IAAI,CAAC,EAAE,mBAAmB,CAAC;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,yFAAyF;IACzF,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,KAAK,EAAE,YAAY,CAAC;IACpB,mFAAmF;IACnF,uBAAuB,EAAE,OAAO,CAAC;IACjC,oEAAoE;IACpE,YAAY,EAAE,iBAAiB,CAAC;CACjC;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,eAAe,CAAC;IAC1B,sFAAsF;IACtF,YAAY,EAAE,iBAAiB,CAAC;CACjC;AAED,qBAAa,OAAO;IAMN,OAAO,CAAC,QAAQ,CAAC,IAAI;IALjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAwB;IACjD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAgB;gBAEd,IAAI,EAAE,WAAW;IAO9C,4EAA4E;IACtE,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAkCrD;;;OAGG;IACG,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC;CAInE"}

package/dist/apply/cutover.js

@@ -0,0 +1,85 @@
+// src/apply/cutover.ts
+//
+// Cutover (extraction-quality-redesign PR-6, spec §3.1, §11).
+//
+// Promotes an EXISTING distilled payload to production with the SINGLE PR-4 apply
+// engine (target=production). The load-bearing rule (spec §3.1, review R3-3):
+//
+//   The staging plan is NEVER reused for production. Candidate page sets,
+//   content_hashes, and slug collisions differ between the staging and public
+//   schemas, so cutover ALWAYS rebuilds the production candidate selection from
+//   scratch (this step is allowed to call the LLM). The distilled payload itself
+//   is NOT re-distilled — only the candidate selection is redone.
+//
+// Flow per payload:
+//   1. buildApplyPlan(target=production) — candidate pool from the PUBLIC schema;
+//   2. persist the production apply_plan under (payload_id, target=production);
+//   3. apply via the target-agnostic ApplyEngine (one transaction, CAS + retry).
+//
+// Stop-the-bleeding: cutover is flag-gated (agent_pipeline=new). If an apply
+// fails or dead-letters, `recommendLegacyFallback` is set and `fallbackMode` is
+// "legacy" so the operator can flip the source flag back to legacy. The same
+// applies to a triggered rollback (spec §3.1): `rollback()` undoes the apply via
+// the PR-4 contributions-based ApplyRollback and returns fallbackMode "legacy".
+import { DistilledPayloadStore } from "../store/distilled-payload.js";
+import { ApplyPlanStore, buildApplyPlan, SchemaCandidateRepository, } from "./candidate-selection.js";
+import { ApplyEngine } from "./engine.js";
+import { ApplyRollback } from "./rollback.js";
+/** The mode an operator flips back to when a cutover apply/rollback fires. */
+const LEGACY_FALLBACK_MODE = "legacy";
+export class Cutover {
+    deps;
+    payloads;
+    plans;
+    engine;
+    rollbacker;
+    constructor(deps) {
+        this.deps = deps;
+        this.payloads = new DistilledPayloadStore(deps.executor);
+        this.plans = new ApplyPlanStore(deps.executor);
+        this.engine = new ApplyEngine(deps.executor);
+        this.rollbacker = new ApplyRollback(deps.executor);
+    }
+    /** Regenerate the production plan for one existing payload and apply it. */
+    async run(payloadId) {
+        const payload = await this.payloads.getById(payloadId);
+        if (!payload)
+            throw new Error(`cutover: payload ${payloadId} not found`);
+        // Rebuild the production candidate selection from scratch — never reuse the
+        // staging plan (candidate pools differ per target, spec §3.1). This does NOT
+        // re-distill: it only re-decides candidates against the production schema.
+        const repo = this.deps.repo ?? new SchemaCandidateRepository(this.deps.executor, "production");
+        const planData = await buildApplyPlan({
+            payload,
+            target: "production",
+            repo,
+            decider: this.deps.decider,
+            candidateLimit: this.deps.candidateLimit,
+        });
+        const planId = await this.plans.save(planData);
+        const plan = {
+            id: planId,
+            payloadId,
+            target: "production",
+            data: planData,
+        };
+        const apply = await this.engine.apply(plan);
+        const recommendLegacyFallback = apply.status !== "applied";
+        return {
+            payloadId,
+            planId,
+            apply,
+            recommendLegacyFallback,
+            fallbackMode: LEGACY_FALLBACK_MODE,
+        };
+    }
+    /**
+     * Roll back a cutover apply via the PR-4 contributions-based rollback and
+     * signal that the source flag should return to legacy (spec §3.1).
+     */
+    async rollback(attemptId) {
+        const rollback = await this.rollbacker.rollback(attemptId);
+        return { rollback, fallbackMode: LEGACY_FALLBACK_MODE };
+    }
+}
+//# sourceMappingURL=cutover.js.map

package/dist/apply/cutover.js.map

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

package/dist/apply/engine.d.ts

@@ -0,0 +1,34 @@
+import type { SqlExecutor } from "../store/sql-executor.js";
+import type { StoredApplyPlan } from "./candidate-selection.js";
+import type { ApplyAction, ApplyTarget } from "./types.js";
+export interface ApplyOutcome {
+    attemptId: number;
+    status: "applied" | "failed" | "dead_letter";
+    target: ApplyTarget;
+    applied: {
+        slug: string;
+        action: ApplyAction;
+    }[];
+    retried: boolean;
+    replay: boolean;
+    error?: string;
+}
+export declare class ApplyEngine {
+    private readonly ex;
+    constructor(ex: SqlExecutor);
+    /**
+     * Apply a frozen plan. Idempotent per plan; target-parameterized; single
+     * transaction; CAS with one retry then dead_letter.
+     */
+    apply(plan: StoredApplyPlan): Promise<ApplyOutcome>;
+    private loadPayloadMeta;
+    private runTransaction;
+    private applyAction;
+    /** Lock the target row and enforce the plan-snapshot CAS (spec §7). */
+    private lockForCas;
+    /** Insert (or reactivate) the page row; journal a brand-new page for rollback. */
+    private ensurePage;
+    private markSuperseded;
+    private attachContribution;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/apply/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/apply/engine.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAW,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEhE,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAiB,MAAM,YAAY,CAAC;AA8B1E,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,aAAa,CAAC;IAC7C,MAAM,EAAE,WAAW,CAAC;IACpB,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,WAAW,CAAA;KAAE,EAAE,CAAC;IACjD,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,WAAW;IACV,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,WAAW;IAE5C;;;OAGG;IACG,KAAK,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,YAAY,CAAC;YA2E3C,eAAe;YAoBf,cAAc;YAmBd,WAAW;IAoDzB,uEAAuE;YACzD,UAAU;IAiBxB,kFAAkF;YACpE,UAAU;YAsBV,cAAc;YAsBd,kBAAkB;CAwCjC"}