@substrat-run/kernel 0.138.0 → 0.140.0

package/dist/derived-objects.js.map

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

package/dist/email-intent.d.ts

@@ -0,0 +1,56 @@
+import { type PlatformOutcomeEvent, type PlatformRequestFailure, type PlatformRequestId, type PlatformRequestStatus, type ScopeId, type SendEmailRequest, type TenantId } from '@substrat-run/contracts';
+import type { OperationContext } from './scope-host.js';
+import type { SwitchSql } from './system-switch.js';
+/**
+ * Ask the platform to send one email, inside the operation (#2102).
+ *
+ * The send is a platform intent: a row written in this operation's transaction, so an
+ * operation that throws afterwards sends nothing, and one that commits is delivered by the
+ * platform's drain — retried while the provider defers it, and reported back as an
+ * `email.sent`, `email.refused` or `email.dead-lettered` event on `mail.about` (or on the
+ * intent, when the mail names no entity). The returned id is the `request` those events carry.
+ *
+ * Name the recipient's `subjectId` when they are a person in your data: the row holds their
+ * address and the message, and that id is how a subject erasure finds and cancels it.
+ *
+ * Parsed here rather than at drain time, so a malformed address fails the operation that wrote
+ * it, in front of the person who typed it, instead of a refusal event minutes later. Needs the
+ * vertical's `emailSender` grant, as the relay always has; without it the send is refused.
+ */
+export declare function requestEmail(ctx: Pick<OperationContext, 'requestPlatform'>, mail: Omit<SendEmailRequest, 'piiClass'>): PlatformRequestId;
+/** What the scope stamps on an outcome event it writes: the drain names the rest. */
+export interface OutcomeEventStamp {
+    tenantId: TenantId;
+    scopeId: ScopeId;
+    /** ISO 8601 — the settle's instant. */
+    now: string;
+    mintEventId(ms: number): string;
+    /** The deploy writing it, for the outbox's `version` column. */
+    version: string | null;
+}
+export interface PlatformRequestSettle {
+    status: PlatformRequestStatus;
+    result?: unknown;
+    lastError?: string | null;
+    failure?: PlatformRequestFailure | null;
+    /** #2102: the event this settle writes into the scope, when it moves the row out of `pending`. */
+    event?: PlatformOutcomeEvent | null;
+}
+/**
+ * Journal a platform-request outcome, and write its outcome event (#2102) — one step, so both
+ * adapters say the same thing and the event commits with the settle or not at all. Run it in a
+ * transaction.
+ *
+ * **Compare-and-set on `pending` (#1600 review).** The drain reads pending rows, runs a handler,
+ * then settles — and between the read and the settle a subject erasure can redact the row.
+ * Settling by `id` alone let that stale pass overwrite the redaction and write a provider's
+ * reply, which can quote the person, back into `last_error`. A settle that finds the row
+ * already terminal does nothing, deliberately silently — throwing would make the drain's
+ * blanket catch retry a row that is correctly over. The event follows the same rule: written
+ * only by the settle that actually moved the row, so a repeated settle never writes it twice.
+ *
+ * The event is refused (before anything is written) on a `pending` settle — an outcome event
+ * says the request is over — and when its `request` is not the row being settled.
+ */
+export declare function settlePlatformRequestIn(db: SwitchSql, id: PlatformRequestId, outcome: PlatformRequestSettle, stamp: OutcomeEventStamp): void;
+//# sourceMappingURL=email-intent.d.ts.map

package/dist/email-intent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-intent.d.ts","sourceRoot":"","sources":["../src/email-intent.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,OAAO,EACZ,KAAK,gBAAgB,EACrB,KAAK,QAAQ,EACd,MAAM,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,IAAI,CAAC,gBAAgB,EAAE,iBAAiB,CAAC,EAC9C,IAAI,EAAE,IAAI,CAAC,gBAAgB,EAAE,UAAU,CAAC,GACvC,iBAAiB,CAKnB;AAED,qFAAqF;AACrF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,uCAAuC;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,gEAAgE;IAChE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,qBAAqB,CAAC;IAC9B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,OAAO,CAAC,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACxC,kGAAkG;IAClG,KAAK,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAAC;CACrC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,SAAS,EACb,EAAE,EAAE,iBAAiB,EACrB,OAAO,EAAE,qBAAqB,EAC9B,KAAK,EAAE,iBAAiB,GACvB,IAAI,CAsCN"}

package/dist/email-intent.js

@@ -0,0 +1,71 @@
+import { SEND_EMAIL_KIND, domainEvent, eventId, platformOutcomeEvent, sendEmailRequest, } from '@substrat-run/contracts';
+import { KERNEL_ACTOR, kernelOutboxInsertSql } from './kernel-outbox.js';
+/**
+ * Ask the platform to send one email, inside the operation (#2102).
+ *
+ * The send is a platform intent: a row written in this operation's transaction, so an
+ * operation that throws afterwards sends nothing, and one that commits is delivered by the
+ * platform's drain — retried while the provider defers it, and reported back as an
+ * `email.sent`, `email.refused` or `email.dead-lettered` event on `mail.about` (or on the
+ * intent, when the mail names no entity). The returned id is the `request` those events carry.
+ *
+ * Name the recipient's `subjectId` when they are a person in your data: the row holds their
+ * address and the message, and that id is how a subject erasure finds and cancels it.
+ *
+ * Parsed here rather than at drain time, so a malformed address fails the operation that wrote
+ * it, in front of the person who typed it, instead of a refusal event minutes later. Needs the
+ * vertical's `emailSender` grant, as the relay always has; without it the send is refused.
+ */
+export function requestEmail(ctx, mail) {
+    const parsed = sendEmailRequest.parse(mail);
+    // Classified like an event naming the same person, so a subject erasure reaches the row.
+    const payload = parsed.subjectId ? { ...parsed, piiClass: 'direct' } : parsed;
+    return ctx.requestPlatform({ kind: SEND_EMAIL_KIND, payload });
+}
+/**
+ * Journal a platform-request outcome, and write its outcome event (#2102) — one step, so both
+ * adapters say the same thing and the event commits with the settle or not at all. Run it in a
+ * transaction.
+ *
+ * **Compare-and-set on `pending` (#1600 review).** The drain reads pending rows, runs a handler,
+ * then settles — and between the read and the settle a subject erasure can redact the row.
+ * Settling by `id` alone let that stale pass overwrite the redaction and write a provider's
+ * reply, which can quote the person, back into `last_error`. A settle that finds the row
+ * already terminal does nothing, deliberately silently — throwing would make the drain's
+ * blanket catch retry a row that is correctly over. The event follows the same rule: written
+ * only by the settle that actually moved the row, so a repeated settle never writes it twice.
+ *
+ * The event is refused (before anything is written) on a `pending` settle — an outcome event
+ * says the request is over — and when its `request` is not the row being settled.
+ */
+export function settlePlatformRequestIn(db, id, outcome, stamp) {
+    const event = outcome.event == null ? null : platformOutcomeEvent.parse(outcome.event);
+    if (event && outcome.status === 'pending') {
+        throw new Error(`settle of platform request ${id}: an outcome event needs a terminal status, not 'pending'`);
+    }
+    if (event && event.payload.request !== id) {
+        throw new Error(`settle of platform request ${id}: the outcome event names request ${event.payload.request}`);
+    }
+    const was = db.all('SELECT status FROM _substrat_platform_requests WHERE id = ?', id)[0]?.status;
+    db.run(`UPDATE _substrat_platform_requests
+       SET status = ?, result = COALESCE(?, result), last_error = ?, last_failure = ?,
+           attempts = attempts + 1, settled_at = ?
+     WHERE id = ? AND status = 'pending'`, outcome.status, outcome.result === undefined ? null : JSON.stringify(outcome.result), outcome.lastError ?? null, outcome.failure == null ? null : JSON.stringify(outcome.failure), outcome.status === 'pending' ? null : stamp.now, id);
+    if (!event || was !== 'pending')
+        return;
+    const full = domainEvent.parse({
+        id: eventId.parse(stamp.mintEventId(Date.parse(stamp.now))),
+        type: event.type,
+        schemaVersion: 1,
+        occurredAt: stamp.now,
+        tenantId: stamp.tenantId,
+        scopeId: stamp.scopeId,
+        actor: KERNEL_ACTOR,
+        entity: event.entity,
+        piiClass: 'none',
+        payload: event.payload,
+    });
+    const st = kernelOutboxInsertSql(full, stamp.version);
+    db.run(st.sql, ...st.params);
+}
+//# sourceMappingURL=email-intent.js.map

package/dist/email-intent.js.map

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

package/dist/entity-edges.d.ts

@@ -1,4 +1,4 @@
-import { type DomainEventInput, type Instant } from '@substrat-run/contracts';
+import { type DomainEventInput, type EntityRef, type Instant } from '@substrat-run/contracts';
 import type { OperationContext, ScopedSql } from './scope-host.js';
 /**
  * `ctx.link` and `ctx.relink` (K-16, #1864), written once — both adapters hand the same
@@ -29,6 +29,11 @@ export interface EntityEdgeDeps {
     emit: (event: DomainEventInput) => void;
     /** K-42's read-only refusal, for the effecting verbs. */
     assertWrites: (verb: string) => void;
+    /**
+     * Is this entity out of reach as a parent (#119) — its type declares trash, and it is binned or
+     * missing (`isUnreachableParent`)? Refused by `link` and as `relink`'s `to`, one answer for both.
+     */
+    isUnreachableParent: (entity: EntityRef) => boolean;
 }
 export type EntityEdgeVerbs = Pick<OperationContext, 'link' | 'relink'>;
 export declare function createEntityEdgeVerbs(deps: EntityEdgeDeps): EntityEdgeVerbs;

package/dist/entity-edges.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entity-edges.d.ts","sourceRoot":"","sources":["../src/entity-edges.ts"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,gBAAgB,EAErB,KAAK,OAAO,EACb,MAAM,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEnE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,cAAc;IAC7B,2FAA2F;IAC3F,GAAG,EAAE,SAAS,CAAC;IACf,mFAAmF;IACnF,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;IACpD,kEAAkE;IAClE,GAAG,EAAE,OAAO,CAAC;IACb,2EAA2E;IAC3E,IAAI,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACxC,yDAAyD;IACzD,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC;AAED,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,gBAAgB,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAC;AAExE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,cAAc,GAAG,eAAe,CA8I3E"}
+{"version":3,"file":"entity-edges.d.ts","sourceRoot":"","sources":["../src/entity-edges.ts"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,OAAO,EACb,MAAM,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEnE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,cAAc;IAC7B,2FAA2F;IAC3F,GAAG,EAAE,SAAS,CAAC;IACf,mFAAmF;IACnF,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;IACpD,kEAAkE;IAClE,GAAG,EAAE,OAAO,CAAC;IACb,2EAA2E;IAC3E,IAAI,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACxC,yDAAyD;IACzD,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC;;;OAGG;IACH,mBAAmB,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC;CACrD;AAED,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,gBAAgB,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAC;AAExE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,cAAc,GAAG,eAAe,CA4J3E"}

package/dist/entity-edges.js

@@ -7,6 +7,17 @@ export function createEntityEdgeVerbs(deps) {
                 `(declare it in a module manifest's entityRelations)`);
         }
     };
+    /**
+     * A binned entity is gone from everyone's view until it is restored (#119), so nothing new
+     * hangs off it. The refusal is the one a MISSING parent of the same type gets, word for word:
+     * `link` checks no permission, so a refusal that named the trash would tell a caller who may not
+     * see the parent that it exists. An ARCHIVED parent passes: archived is filed away and readable.
+     */
+    const assertParentReachable = (verb, parent) => {
+        if (deps.isUnreachableParent(parent)) {
+            throw substratError('not_found', `${verb}: ${parent.entityType}:${parent.entityId} not found`);
+        }
+    };
     /**
      * Refuse when `ancestorCandidate` is `child` itself, or already lies beneath `child` in the
      * live parent graph — shared by `link` (candidate = the new `parent`) and `relink` (candidate
@@ -54,6 +65,7 @@ export function createEntityEdgeVerbs(deps) {
             const c = entityObjectRef(child, 'ctx.link'); // #1856: an edge the walk can read back
             const p = entityObjectRef(parent, 'ctx.link');
             assertDeclared('ctx.link', child, parent);
+            assertParentReachable('ctx.link', parent);
             // Refuse a parent that is the child itself or already beneath it (#1875) — same question
             // `relink` asks of `to`, same walk.
             assertNoCycle('ctx.link', 'link', c, p);
@@ -80,6 +92,7 @@ export function createEntityEdgeVerbs(deps) {
             // whether or not its relation is still declared, so an edge that grants must stay
             // movable. What `from` must be is an edge that exists.
             assertDeclared('ctx.relink', child, to);
+            assertParentReachable('ctx.relink', to);
             // The walk's own `live` predicate, so "is a parent" means what a check means by it.
             const live = deps.sql.query(`SELECT 1 AS live FROM _substrat_tuples
          WHERE subject = ? AND relation = 'parent' AND object = ? AND ${liveTupleSql()}`, [c, f, deps.now]);

package/dist/entity-edges.js.map

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

package/dist/entity-grant-shape.d.ts

@@ -0,0 +1,94 @@
+import { type EntityGrantShape, type EntityRef, type PrincipalId } from '@substrat-run/contracts';
+import type { SwitchSql } from './system-switch.js';
+/**
+ * A declared entity-grant SHAPE, reconciled (#2071).
+ *
+ * A vertical declares the keys a person is given on their own record (`ENTITY_GRANTS`:
+ * meridian's `EMPLOYEE_SELF` on `employee`, todo's owner grant on `owner`). They used to be
+ * minted key by key, once, when the person arrived, so a key added to the shape by a later
+ * release reached only the people who arrived after it, while `PERMISSIONS.md` said everyone
+ * held it.
+ *
+ * Three pieces, each one statement shared by both adapters:
+ *
+ * - {@link grantEntityShapeIn}: the grant. The shape's keys plus a MARKER tuple
+ *   (`ENTITY_SHAPE_MARKER_RELATION`) on the same entity. The marker is what makes a person a
+ *   holder of the shape, which no set of keys can: someone `ctx.grant`ed one of those keys
+ *   holds part of the shape and must never be topped up to all of it.
+ * - {@link topUpEntityGrantShapes}: one bounded pass of the reconcile, writing each top-up's
+ *   `entity.grants-topped-up` event beside it. Each live marker whose
+ *   entity lacks a key of the CURRENT shape gets that key. A key with any row at all is
+ *   skipped, and that includes a tombstone (K-21): a key someone took back from that person
+ *   stays taken back. A key merely dropped from the shape is left where it is, because silently
+ *   revoking authority on a deploy is the riskier mistake.
+ * - The retirement (#2082), in the same pass and budget, between the backfill and the top-up: a
+ *   key the shape declares `retired` is tombstoned for every live marker that still holds it
+ *   live, with one `entity.grants-retired` event per (person, entity). The tombstones are the
+ *   progress; a record tuple (`shape:<type>`, `shape-retired:<key>`, `scope:<id>`) ends it once
+ *   a batch comes back short, so a key granted to a holder again afterwards is left alone. A key
+ *   back in the shape's `permissions` tombstones that record, so a later release may retire it
+ *   again. One tuple is one authority: a direct grant of the key on the same entity to the same
+ *   person is that row, and goes with it.
+ * - The backfill, inside the same budget, until it is done once per (scope, entity type): how
+ *   people granted before markers existed become holders. For own-record holders it reads
+ *   provenance, never key sets alone.
+ *   The shape's declared `holder` says whose record each entity is (`'self'`: the entity id is
+ *   the principal; a table column naming the principal), and a person is marked only on their
+ *   own record, and only when they hold a row there (live or tombstoned) for some key of the
+ *   shape — evidence they were given it. Someone `ctx.grant`ed even the whole shape on another
+ *   person's record is never marked. A shape with no `holder` gets no backfill. Each batch marks
+ *   at most what the pass's budget allows; the markers are the progress, since a marked pair is
+ *   no longer a candidate, and a record tuple (`shape:<type>`, `shape-backfilled`, `scope:<id>`)
+ *   ends it once a batch comes back short.
+ * - `holder: 'grantee'` (#2083), for a record that names no principal (a portal customer, a
+ *   contact): whoever holds a live current or retired key of the shape on such an entity was given it.
+ *   Each pass records current and retired keys (`shape-grantee-key`), and the explicit tuple
+ *   writer makes non-shape grants refuse them on that entity type. A tuple from before the
+ *   first such pass cannot be told apart. A marker already written by a shape grant persists
+ *   through retirement, so its holder receives the new keys even if their old key was K alone.
+ *
+ * Only a shape declared `bootstrap: true` is reconciled: one a person is GIVEN on their own
+ * record. A sharing shape, which people reach through `ctx.grant` (todo's `list`), is skipped
+ * whole, backfill included, so a sharee is never marked a holder.
+ */
+/** Holders topped up per pass — one transaction each, so a large scope never holds one long. */
+export declare const SHAPE_TOP_UP_BATCH = 500;
+/** The largest batch a caller may ask for: past this a pass is the long transaction it exists to avoid. */
+export declare const SHAPE_TOP_UP_BATCH_MAX = 5000;
+/** `batch`, or `validation_failed`: a pass size is a positive integer no larger than the max. */
+export declare function shapeTopUpBatch(batch?: number): number;
+/**
+ * The shape's grant to one person on one entity: the marker and every key, each an explicit
+ * write, so a re-grant brings back what a revoke tombstoned — as `ctx.grant` does.
+ * `entityObjectRef` refuses a ref the walk could not read back (#1856). Run it in ONE
+ * transaction, so the marker and its keys land together or not at all.
+ */
+export declare function grantEntityShapeIn(db: SwitchSql, principal: PrincipalId, entity: EntityRef, permissions: readonly string[]): void;
+/** Where a pass runs and how its events are stamped — the facts only the adapter holds. */
+export interface ShapePass {
+    tenantId: string;
+    scopeId: string;
+    shapes: readonly EntityGrantShape[];
+    /** The pass's one instant: marker liveness and every event's `occurredAt`. */
+    now: string;
+    /** Rows of work at most: a backfill mark or a holder topped up each count one. */
+    limit: number;
+    /** The adapter's monotonic event-id mint, given the instant in ms. */
+    mintEventId: (ms: number) => string;
+    /** The deploy writing the events, for the outbox `version` column. */
+    version: string | null;
+}
+/**
+ * One pass of the reconcile over one scope, at most `limit` rows of work: backfill marks for any
+ * shape whose backfill is not done here, then holders whose retired keys are taken back, each
+ * with its `entity.grants-retired` event, then holders topped up, each with its
+ * `entity.grants-topped-up` event. `done` is false when the budget ran out, and the caller runs
+ * another pass. Run it inside ONE transaction, so the keys and their events commit together.
+ * Re-running a finished scope writes nothing.
+ */
+export declare function topUpEntityGrantShapes(db: SwitchSql, pass: ShapePass): {
+    toppedUp: number;
+    retired: number;
+    done: boolean;
+};
+//# sourceMappingURL=entity-grant-shape.d.ts.map

package/dist/entity-grant-shape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-grant-shape.d.ts","sourceRoot":"","sources":["../src/entity-grant-shape.ts"],"names":[],"mappings":"AAAA,OAAO,EAUL,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,WAAW,EACjB,MAAM,yBAAyB,CAAC;AAMjC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,gGAAgG;AAChG,eAAO,MAAM,kBAAkB,MAAM,CAAC;AACtC,2GAA2G;AAC3G,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAE3C,iGAAiG;AACjG,wBAAgB,eAAe,CAAC,KAAK,GAAE,MAA2B,GAAG,MAAM,CAS1E;AAiBD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CASjI;AAED,2FAA2F;AAC3F,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACpC,8EAA8E;IAC9E,GAAG,EAAE,MAAM,CAAC;IACZ,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,WAAW,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;IACpC,sEAAsE;IACtE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,SAAS,EACb,IAAI,EAAE,SAAS,GACd;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CA+EtD"}