@remnic/core 9.69.55 → 9.69.57

package/dist/orchestration/semantic-merge-persist.d.ts

@@ -0,0 +1,318 @@
+/**
+ * Persist-side executor for judge-mediated merge-on-write (issue #2330, step 3).
+ *
+ * Lives beside `extraction-persist.ts` so that file stays within its
+ * file-size ratchet ceiling. Called once per surviving fact, right before
+ * the normal (non-chunked) sealed-envelope write. On every failure mode —
+ * disabled gate, empty band, judge refusal, invalid verdict, snapshot or
+ * update failure — the outcome is "created" and the caller falls through
+ * to the unchanged write path.
+ *
+ * Exact mutation order (checklist #14/#42): version snapshot FIRST, then
+ * the in-place content update, then the frontmatter patch, then hash-index
+ * remove/add, then reindex. The new fact's content is never indexed as
+ * its own entry — it was never persisted (checklist #32).
+ */
+import { type MergeJudgeCallOptions } from "../dedup/merge-judge.js";
+import { type MergeCreateReason, type MergeJudgeRawVerdict } from "../dedup/merge.js";
+import { type CitationContext } from "../source-attribution.js";
+import { type GraphConstructionCapabilitySet } from "../capabilities.js";
+import type { BehaviorSignalEvent, FaithfulnessFrontmatter, MemoryCategory, MemoryFile, MemoryFrontmatter, MemoryLink, MemorySubject, ProvenanceSource } from "../types.js";
+import type { StorageManager } from "../index.js";
+import type { ExtractionPersistDeps } from "./extraction-persist-deps.js";
+export type SemanticMergeCreateReason = MergeCreateReason | "target_inactive" | "target_changed" | "metadata_unpreservable" | "promoted_copy_present" | "snapshot_unavailable" | "snapshot_failed" | "update_failed" | "shadow_would_merge";
+export type SemanticMergePersistOutcome = {
+    action: "merged";
+    targetId: string;
+    /**
+     * The committed merged body (finding A): the caller's merged-target
+     * promotion must copy THIS body — not the incoming fact — so the
+     * shared/profile copy serves the same claims its `sourceMemoryId`
+     * points at. Present on the degraded branch too, where the merged
+     * text is committed even though the provenance patch failed.
+     */
+    mergedContent: string;
+    /**
+     * False only in the degraded case where the content update committed,
+     * the frontmatter patch failed, AND the automatic rollback could not
+     * run. The merged text IS in the target, so the caller must not write
+     * the fact again; the pre-merge snapshot is named in the error log.
+     */
+    provenancePatched: boolean;
+} | {
+    action: "created";
+    reason: SemanticMergeCreateReason;
+};
+export interface ApplySemanticMergeOptions {
+    storage: StorageManager;
+    /** RAW (pre-citation) fact content — the same form the dedup band scores. */
+    content: string;
+    category: string;
+    /** The incoming fact's claim-level provenance spans, appended to the target. */
+    sources?: ProvenanceSource[];
+    /**
+     * Provenance connector of the incoming fact. Forwarded to the decision so a
+     * cross-connector neighbor is never a merge target (same scope contract the
+     * novelty and semantic-dedup gates apply).
+     */
+    sourceConnector?: string;
+    /**
+     * Extraction metadata the normal write path persists but a merge cannot
+     * carry onto the target (item A). A merge forwards only content, category,
+     * sources, and connector; when any entry here is NEW information relative
+     * to the target, merging is bypassed so nothing is silently discarded.
+     */
+    incomingMetadata?: {
+        tags?: readonly string[];
+        entityRef?: string;
+        structuredAttributes?: Record<string, string>;
+        /** Effective `validAt` the write path would persist (bi-temporal or source). */
+        validAt?: string;
+        /** True when bi-temporal bounds (validFrom/validUntil/observedAt/eventTimeSource) apply. */
+        biTemporal?: boolean;
+        /** Importance score the write path would stamp. */
+        importanceScore?: number;
+        /**
+         * Confidence the write path would stamp (final round A). The merged
+         * record keeps the LOWER side — min(incoming, target), with the tier
+         * that score maps to — matching what the create path would have stored
+         * for the incoming fact alone; an incoming value at or above the
+         * target's needs no rewrite. An unreadable value (non-finite or outside
+         * [0, 1]) bypasses the merge rather than guessing a floor.
+         */
+        confidence?: number;
+        /**
+         * Provenance strength the write path would stamp.
+         */
+        provenanceStrength?: "verified" | "unverified" | "none";
+        /**
+         * True when the write path would stamp `toolScoped: true` (finding A):
+         * connector-scoped claims must never widen into an unscoped target, so
+         * such a fact is created through the write that stamps the flag. A
+         * target that already carries `toolScoped: true` keeps its stricter
+         * scope — the merge patch never touches that field.
+         */
+        toolScoped?: boolean;
+        /**
+         * Subject the write path would stamp when subject classification is
+         * enabled (finding A): the merge patch has no carrier for `subject`, so
+         * a fact whose effective subject differs from the target's must be
+         * created rather than merged into a target that keeps a different label.
+         */
+        subject?: MemorySubject;
+        /**
+         * Authority origin the write path would stamp (finding A). The merge
+         * patch has no carrier for `origin`, so the merged body would render
+         * under the TARGET's authority at recall; a cross-origin merge is
+         * refused outright (see {@link createPathMergeParity}).
+         */
+        origin?: string;
+        /**
+         * Faithfulness verdict the write path would stamp (finding C). In
+         * shadow mode a contradicted/unsupported fact receives this frontmatter
+         * without pending_review status, so the verdict — not just the enforce
+         * status — gates parity: the merge patch cannot compose an honest
+         * verdict for a combined body, so an incoming verdict that differs from
+         * the target's effective one bypasses the merge.
+         */
+        faithfulness?: FaithfulnessFrontmatter;
+        /**
+         * Episode/note classification the write path would stamp when
+         * `episodeNoteMode` is on (round N+2, finding B). The merge patch has
+         * no `memoryKind` carrier, so the merged record keeps the target's
+         * kind — the classification that drives episode-cache membership and
+         * the episode-only verification/promotion paths. A computed incoming
+         * kind that differs from the target's committed kind (including a
+         * kinded fact into an unkinded legacy target) bypasses the merge.
+         * Undefined means classification is off and no episode path consults
+         * the field, so those merges keep passing.
+         */
+        memoryKind?: MemoryFrontmatter["memoryKind"];
+    };
+    /**
+     * Navigation links the caller suggested for the incoming fact (finding B).
+     * The create path stamps these on the fact it writes; a merge that dropped
+     * them would permanently lose the relationships, so a successful merge
+     * attaches them to the TARGET record in the same conditional frontmatter
+     * patch that stamps provenance — deduped on (targetId, linkType), the key
+     * `StorageManager.addLinksToMemory` uses.
+     */
+    incomingLinks?: readonly MemoryLink[];
+    /**
+     * Round N+7 (C): the caller's single cited body for this write — the raw
+     * fact content with this write's citation marker attached (the same
+     * string the verbatim artifact stores). The committed merged body reuses
+     * that exact marker so the incoming claims stay attributed alongside the
+     * target's older citation, and memory and artifact share one timestamp.
+     * Absent (or citation-free) commits the judge's merged body unchanged.
+     */
+    incomingCitedContent?: string;
+    /**
+     * #2916: the citation context of THIS write (agent/session) — the same
+     * base a fresh attributed write stamps. When no incoming citation marker
+     * is liftable, the committed merged body still receives the configured
+     * inline-attribution transform exactly as a fresh attributed write would,
+     * stamped with this context and the merge's commit timestamp.
+     */
+    incomingCitationContext?: Omit<CitationContext, "ts">;
+    /**
+     * Finding C: async probe run after a merge verdict but before any
+     * mutation. True when the would-be target already has promoted
+     * shared/profile copies the merge cannot reconcile — the fact is created
+     * through the normal write (whose promotion step owns those copies)
+     * instead of merged.
+     */
+    targetHasPromotedCopies?: (targetId: string) => Promise<boolean>;
+    /** Caller-side bypass: contradiction detected or pending_review routing. */
+    skip?: boolean;
+    /** Injection seam for tests. */
+    now?: () => Date;
+    judgeCall?: (options: MergeJudgeCallOptions) => Promise<MergeJudgeRawVerdict | null>;
+}
+/**
+ * Create-path parity gate (final round, PR #2771). Nine review rounds all
+ * found the same defect class: the merge path did less, or something wider,
+ * than the create path. Instead of patching call sites, this ONE gate
+ * enumerates every trust/scope/verdict field the create path's write stamps
+ * (`writeSealedMemory` + extras in `extraction-persist.ts`) and decides,
+ * per field, whether the merge preserves it. A merge proceeds only when
+ * EVERY field is carried by the merge patch, preserved monotonically, or
+ * provably equal. Anything else — including anything unknown or unreadable —
+ * bypasses to a create, because a create is always safe and a merge is not.
+ *
+ * Field classification, from the create-path write:
+ *  - carried by the merge patch: content (judge-composed merged body),
+ *    sources (appended by buildMergeFrontmatterUpdate), contentHash
+ *    (restamped off the canonical merged form), status (a merge-eligible
+ *    fact is never pending_review — the caller skips — and the target is
+ *    re-verified active), provenance (only when downgraded to the
+ *    least-trusted side, see below).
+ *  - equality-required (bypass on mismatch): category (also enforced at
+ *    candidate resolution), entityRef, effective validity bounds — both
+ *    sides unbounded, or an incoming validAt identical to the target's
+ *    valid_at; a target carrying invalid_at never merges (round N+2 A) —
+ *    subject (effective), memoryKind when the incoming fact carries a
+ *    computed kind (round N+2 B), sourceConnector (against the COLD-AWARE
+ *    target snapshot, finding D), faithfulness verdict (effective, finding C).
+ *  - monotone-preservable (bypass when the incoming side exceeds what the
+ *    target retains): tags (target must be a superset), importance score
+ *    (incoming may not exceed), confidence score (incoming may not exceed;
+ *    a lower incoming DOWNGRADES the record to min(incoming, target) with
+ *    the tier that score maps to — final round A), provenance strength
+ *    (incoming may not be stronger — and a weaker incoming downgrades the
+ *    target so the merged body never carries trust its new claims did not
+ *    earn, finding B).
+ *  - bypass-on-presence (no carrier exists at all): structuredAttributes,
+ *    bi-temporal bounds.
+ *  - escalation-refused: origin (an untrusted incoming origin may never
+ *    merge into a trusted target; equal or fence-safe mismatches may).
+ *  - scope-widening-refused: toolScoped (an unscoped target may never gain
+ *    tool-scoped claims; a scoped target keeps its stricter flag).
+ */
+export type CreatePathMergeParity = {
+    ok: true;
+    provenanceFloor?: "verified" | "unverified" | "none";
+    /** Lower incoming confidence the patch must stamp (final round A). */
+    confidenceFloor?: number;
+} | {
+    ok: false;
+    field: string;
+};
+export declare function createPathMergeParity(input: {
+    /** Cold-aware committed snapshot of the merge target (never a lookup hit). */
+    target: MemoryFile;
+    incoming: ApplySemanticMergeOptions["incomingMetadata"];
+    /** The incoming fact's connector scope (finding D). */
+    sourceConnector?: string;
+    untrustedOrigins: readonly string[];
+}): CreatePathMergeParity;
+/**
+ * Finding B — union the incoming fact's suggested navigation links into the
+ * target's committed links, deduping on (targetId, linkType): the same key
+ * `StorageManager.addLinksToMemory` uses. A suggestion naming the surviving
+ * target itself is DISCARDED — memory linking and the merge judge both
+ * search on the incoming content, so the suggested neighbor is often the
+ * merge target itself, and attaching it would make the record its own
+ * neighbor (recall-navigate would return the current memory and burn
+ * traversal budget). Returns undefined when there is nothing to attach so
+ * the patch carries no `links` key at all (an empty array would ERASE
+ * committed links).
+ */
+export declare function mergeMemoryLinks(existing: readonly MemoryLink[] | undefined, incoming: readonly MemoryLink[] | undefined, survivingTargetId: string): MemoryLink[] | undefined;
+export declare function applySemanticMergeAtPersist(deps: ExtractionPersistDeps, options: ApplySemanticMergeOptions): Promise<SemanticMergePersistOutcome>;
+/**
+ * Finding B: for a qualifying write the create path stores the incoming
+ * extraction's text as a verbatim artifact anchored to the memory it just
+ * wrote. A merge that skipped that step would permanently drop the anchor
+ * the same extraction would have stored, so a successful merge persists the
+ * artifact against the MERGED target — same gates as the write path
+ * (verbatim artifacts enabled, category qualifies, confidence at or above
+ * the threshold). A merge target is always active and a pending_review fact
+ * never reaches the merge, so the write path's post-write guards cannot
+ * apply here. Round N+17 (B): this write is the merge path's LAST durable
+ * effect (create-path ordering), and a rejection is isolated inside to a
+ * logged warning — the committed target stays discoverable; failures never
+ * abort the merge batch.
+ */
+export declare function writeMergedVerbatimArtifact(deps: ExtractionPersistDeps, storage: StorageManager, targetId: string, input: {
+    category: string;
+    /** Incoming fact body, cited exactly once for this write by the caller. */
+    citedContent: string;
+    confidence: number;
+    tags: readonly string[];
+    intent?: {
+        goal?: string;
+        actionType?: string;
+        entityTypes?: string[];
+    };
+    sourceConnector?: string;
+    origin?: string;
+    toolScoped?: boolean;
+}): Promise<void>;
+/**
+ * Round N+5 (A+B) + N+6 (A/B/C): the create path's write is followed by
+ * post-write stages that OBSERVE the persisted record — graph-edge
+ * construction and the behavior-signal ledger. The merge path's `continue`
+ * skipped both, so a judge-accepted merge committed new claims that
+ * graph-mode recall and runtime-policy learning could never see. This helper
+ * runs them for the SURVIVING target, derived from the re-read committed
+ * record exactly like `buildMergedTargetPromotionPayload`: category,
+ * entityRef, graph content, AND the relative graph path come from the
+ * committed record, never the incoming extraction and never a hot-only
+ * path-map fallback — the graph context is built from a hot-only corpus
+ * scan, so a cold-tier target is absent from it and only `committed.path`
+ * carries the true location (N+6 A). The graph content is the canonical RAW
+ * pre-citation form — the same body the create path hands `buildGraphEdge`.
+ * The target's prior generated edges are removed first in EVERY enabled
+ * graph type — entity from-side, time/causal inbound — so a re-merge
+ * REPLACES them instead of re-appending duplicates into append-only JSONLs
+ * that spreadingActivation would then double-count (N+6 B, N+7 G); if the
+ * replacement build fails, the rows the failed build already appended are
+ * removed and the removed edges restored, so failure leaves EXACTLY the old
+ * set (N+7 E, N+10 C). The target joins the
+ * batch's thread episode list at its END — deduped first when already
+ * present — so the merge is the thread's latest event and later facts in
+ * the same extraction chain their time/causal adjacency through it (N+6 C,
+ * N+7 F). Graph failures are fail-open (the committed merge stands,
+ * matching the create path's try/catch); the caller owns the ledger flush,
+ * so the behavior events are RETURNED for its storage.
+ */
+export declare function runMergedTargetPostEffects(deps: ExtractionPersistDeps, storage: StorageManager, merge: {
+    targetId: string;
+    mergedContent: string;
+}, input: {
+    /** Written category (parity-guaranteed equal to the committed record's). */
+    category: MemoryCategory;
+    incomingContent: string;
+    incomingConfidence: number;
+    namespace: string;
+    graphCaps: GraphConstructionCapabilitySet;
+    graphContext: {
+        allMemsForGraph: MemoryFile[] | null;
+        memoryPathById: Map<string, string>;
+        previousPersistedRelPath?: string;
+    };
+    threadIdForEdge: string | undefined;
+    threadEpisodeIdsForGraph: string[] | undefined;
+}): Promise<BehaviorSignalEvent[]>;
+//# sourceMappingURL=semantic-merge-persist.d.ts.map

package/dist/orchestration/semantic-merge-persist.d.ts.map

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

package/dist/orchestration/semantic-merge-promotion-payload.d.ts

@@ -0,0 +1,132 @@
+import type { StorageManager } from "../index.js";
+import type { ImportanceScore, MemoryFrontmatter, MemorySubject, ProvenanceSource } from "../types.js";
+/**
+ * The merged-target promotion payload (final round): EVERY field the
+ * shared/profile copy is stamped from, taken wholesale off the re-read
+ * committed record — no field on the promotion path reads the incoming
+ * extraction. `origin` is normalized through `parseOriginClass` so an
+ * unstamped legacy target promotes as `unknown`, the fence's
+ * least-privilege default, and never falls back to the extraction's own
+ * origin. Absent optional fields stay absent: a target without temporal
+ * bounds or attributes promotes a copy without them. The record's
+ * confidence is the downgraded min(incoming, target) value the merge
+ * patch stamped (final round A), so the copy stamps that same value. The
+ * tool-scope marker and owning connector ride along (finding A) so the
+ * promotion's withhold gate evaluates the record's committed scope, not a
+ * fresh content-heuristic guess over the merged body.
+ */
+export interface MergedTargetPromotionPayload {
+    category: string;
+    content: string;
+    confidence: number;
+    tags: string[];
+    entityRef?: string;
+    structuredAttributes?: Record<string, string>;
+    sourceMemoryId: string;
+    importance?: ImportanceScore;
+    intentGoal?: string;
+    intentActionType?: string;
+    intentEntityTypes?: string[];
+    memoryKind?: MemoryFrontmatter["memoryKind"];
+    validAt?: string;
+    invalidAt?: string;
+    observedAt?: string;
+    eventTimeSource?: "extracted" | "assumed";
+    /** Normalized committed origin; never undefined, so the envelope's extraction fallback cannot fire. */
+    origin: string;
+    sources?: ProvenanceSource[];
+    provenance?: "verified" | "unverified" | "none";
+    subject?: MemorySubject;
+    /** The committed target's own write provenance label. */
+    source: string;
+    /** Committed tool-scope marker + owning connector (finding A): the copy must
+     * stay withheld from the shared namespace exactly like the record it copies.
+     * Re-running the content heuristics over the merged body is not equivalent —
+     * the judge-composed text can drop the tool references that earned the
+     * target its marker at write time, and without the connector the heuristic
+     * returns false outright. */
+    toolScoped?: true;
+    sourceConnector?: string;
+    /**
+     * The committed record's CAS revision token at payload-build time (round
+     * N+15 A, #2807) — the dedicated sidecar identity, never public
+     * `frontmatter.updated`. The payload is a CACHE: before promoting it, the
+     * caller re-reads the record and confirms the token AND body still match —
+     * a writer that merged the same target again in between makes this
+     * payload stale, and a stale body must never be promoted or become the
+     * reconciliation canon.
+     */
+    committedRevision?: string;
+    /** #2813 (P1 B): sha256 hex digest of the durable memory file when committed. */
+    committedDigest?: string;
+    /** #2870: canonical SEMANTIC fingerprint of the durable file at
+     * payload-build time — access telemetry (`accessCount`/`lastAccessed`)
+     * excluded, the same exclusion set `invalidationCommitFingerprint`
+     * applies. The final guard re-reads the file and compares THIS, not the
+     * byte digest: an access-tracking flush between build and promotion
+     * leaves it equal (the flush mints no receipt and touches no semantic
+     * line), while any body/confidence/provenance/scope/tags/status change
+     * makes it differ. */
+    committedSemanticFingerprint?: string;
+}
+/**
+ * #2807 (finding 1): the builder's null has two meanings the caller must
+ * not conflate. A REFUSED payload (degraded merge, target replaced
+ * mid-flight, retired record) means "no promotion is warranted" — the
+ * caller's destructive reconciliation may proceed on that conclusion. A
+ * payload that is UNKNOWN because the post-commit reread itself failed
+ * means no such conclusion was reached, so `readFailed` preserves the
+ * failure reason across the call boundary.
+ */
+export interface MergedTargetPromotionResult {
+    payload: MergedTargetPromotionPayload | null;
+    /** True when `payload` is null because the reread threw OR the CAS receipt
+     * sidecar was unreadable (#2813 P1 A) — the payload is unknown, not refused. */
+    readFailed: boolean;
+}
+/**
+ * Re-read the committed merge target (cold-aware id lookup — the same
+ * resolver the merge itself used) and derive the promotion payload solely
+ * from that record. Returns a null payload when the record can no longer
+ * ground the promotion (deleted, its body was replaced after the merge
+ * committed, or a concurrent lifecycle operation archived/superseded it
+ * between the merge commit and this reread — promoting from a retired
+ * record would resurrect content that operation retired, final round B),
+ * and null for a degraded merge whose provenance patch never landed (round
+ * N+7 A) — the gate every trust-elevating consumer routes through; callers
+ * then skip the promotion fail-open — the merge itself stands. Round N+18
+ * (B): the reread itself is isolated fail-open — a locked secure store or
+ * a corpus read I/O error resolves to a null payload with `readFailed:
+ * true` and a logged warn rather than a rejection, because the merge has
+ * already committed and the hash-index repair makes any retry dedupe
+ * against the committed body; an uncaught throw here would strand every
+ * remaining durable effect (thread episode, temporal/tag refresh, harmonic
+ * construction, graph rebuild, behavior signals, artifact write). #2807:
+ * the failure reason rides out on the result so reconciliation can tell an
+ * unknown payload from a refused one.
+ */
+export declare function buildMergedTargetPromotionPayload(storage: StorageManager, merge: {
+    targetId: string;
+    mergedContent: string;
+    provenancePatched: boolean;
+}): Promise<MergedTargetPromotionResult>;
+/** #2870: canonical SEMANTIC fingerprint of a durable file's CURRENT
+ * bytes — the file text with access telemetry stripped
+ * ({@link canonicalSemanticFileText}), hashed exactly the way the CAS
+ * receipt records it at commit time. Null when the file cannot be read
+ * (fail-open, like readDurableFileDigest). */
+export declare function readDurableSemanticFingerprint(filePath: string): Promise<string | null>;
+/** #2813 (P1 A): read the standing receipt as a three-way truth for the
+ * promotion path. Present and absent are usable identities (absent = the
+ * target predates the sidecar); unavailable is not. A storage whose status
+ * probe itself throws reads as unavailable — never as absence. */
+export declare function readPromotionReceiptStatus(storage: Pick<StorageManager, "readCasRevisionStatus">, filePath: string): Promise<{
+    available: true;
+    revision: string | undefined;
+    committedDigest?: string;
+    committedSemanticFingerprint?: string;
+} | {
+    available: false;
+    reason: string;
+}>;
+//# sourceMappingURL=semantic-merge-promotion-payload.d.ts.map

package/dist/orchestration/semantic-merge-promotion-payload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-merge-promotion-payload.d.ts","sourceRoot":"","sources":["../../src/orchestration/semantic-merge-promotion-payload.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EACV,eAAe,EAEf,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EACjB,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9C,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,UAAU,CAAC,EAAE,iBAAiB,CAAC,YAAY,CAAC,CAAC;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAC1C,uGAAuG;IACvG,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC7B,UAAU,CAAC,EAAE,UAAU,GAAG,YAAY,GAAG,MAAM,CAAC;IAChD,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;IACf;;;;;iCAK6B;IAC7B,UAAU,CAAC,EAAE,IAAI,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;;OAQG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iFAAiF;IACjF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;0BAOsB;IACtB,4BAA4B,CAAC,EAAE,MAAM,CAAC;CACvC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE,4BAA4B,GAAG,IAAI,CAAC;IAC7C;oFACgF;IAChF,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,iCAAiC,CACrD,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,iBAAiB,EAAE,OAAO,CAAA;CAAE,GAC7E,OAAO,CAAC,2BAA2B,CAAC,CA4HtC;AAED;;;;8CAI8C;AAC9C,wBAAsB,8BAA8B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAQ7F;AACD;;;kEAGkE;AAClE,wBAAsB,0BAA0B,CAC9C,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,uBAAuB,CAAC,EACtD,QAAQ,EAAE,MAAM,GACf,OAAO,CACN;IAAE,SAAS,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAAC,4BAA4B,CAAC,EAAE,MAAM,CAAA;CAAE,GAClH;IAAE,SAAS,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CACvC,CAcA"}