@crowdsource.you/core 1.2.0

package/dist/esm/outbox/enforcement/planner.js

@@ -0,0 +1,326 @@
+/**
+ * Deciding what an application will do about a decision — and nothing else.
+ *
+ * Pure: no database, no clock, no configuration. A decision in, a plan out. That
+ * is what makes the mapping testable as a table rather than as an integration
+ * scenario, and it is why `observe` mode is a real audit rather than a comment —
+ * the plan is computed identically in every mode and only its EXECUTION is
+ * gated.
+ *
+ * ## The application maps recommendations, not findings
+ *
+ * `decision.recommendedActions` is what this reads, falling back to severity
+ * only when a violation arrives with no recommendation at all.
+ *
+ * The reason is a division of labour: the jury classified the material and the
+ * consensus engine turned that into a recommendation under a versioned policy.
+ * An application that re-derived its action from raw severity would be quietly
+ * re-deciding the case with a second, unversioned policy of its own — and the
+ * two would diverge the first time CrowdSource's policy was updated. The
+ * fallback exists because a `violation` the application did nothing about would
+ * be worse than a mapped one.
+ *
+ * ## Why this ALGORITHM is shared and only the TABLES are per-application
+ *
+ * Every application has different actions, so the tables have to be its own. The
+ * algorithm must not be, because it carries a correctness property that is
+ * invisible by construction — see {@link withRestoreForNoViolation}. An
+ * application writing its own planner is a chance to ship that bug silently, and
+ * no test written against the application's own mapping would catch it.
+ */
+const SEVERITY_ORDER = ['low', 'medium', 'high', 'critical'];
+/**
+ * Recommendations that ask for NO effect.
+ *
+ * An unmapped recommendation goes to `reviewAction`, because a recommendation
+ * this application has no action for is a decision a human should see. These
+ * three are the exception, and the distinction is not cosmetic: they are
+ * CrowdSource saying "take no action", so routing them to review would put a
+ * human in front of every cleared case and bury the ones that need looking at.
+ *
+ * An application's own table still wins — it may genuinely want `allow` to mean
+ * something — but the default for an application that maps nothing has to be
+ * "do nothing" rather than "wake somebody".
+ */
+const NO_EFFECT_RECOMMENDATIONS = new Set([
+    'allow',
+    'no_action',
+    'no_global_effect',
+]);
+function actionForRecommendation(recommended, config) {
+    const mapped = config.recommendationToAction?.[recommended];
+    if (mapped !== undefined)
+        return mapped;
+    return NO_EFFECT_RECOMMENDATIONS.has(recommended)
+        ? config.noneAction
+        : config.reviewAction;
+}
+function highestSeverity(decision) {
+    let highest;
+    for (const finding of decision.findings) {
+        if (highest === undefined ||
+            SEVERITY_ORDER.indexOf(finding.severity) > SEVERITY_ORDER.indexOf(highest)) {
+            highest = finding.severity;
+        }
+    }
+    return highest;
+}
+/**
+ * `no_violation` always carries a restore, whatever it recommended.
+ *
+ * This exists because of a failure that is very easy to ship and very hard to
+ * see. A correction is a new revision whose outcome is `no_violation`, and its
+ * recommendation is frequently `no_action` — which is CrowdSource saying "take
+ * no NEW action", not "leave what you already did in place". Mapping that
+ * straight through plans nothing, and the object an earlier revision removed
+ * stays removed forever: the appeal succeeded, the case says the content was
+ * fine, and nothing in the application ever puts it back. No error, no log line,
+ * no failing test anywhere else.
+ *
+ * `allow`, `restore` and `no_action` are listed together as an application's
+ * options for `no_violation` precisely because choosing between them needs
+ * knowledge only the application has — whether it did something earlier. So the
+ * plan always includes the restore, and the executor records "there was nothing
+ * restricted" when that is the case, which is evidence rather than a silent
+ * no-op.
+ */
+function restoreActions(declared) {
+    if (declared === null)
+        return [];
+    return typeof declared === 'string' ? [declared] : declared;
+}
+function withRestoreForNoViolation(decision, planned, declared) {
+    /**
+     * `null` is a decision the application made, not an omission — the type
+     * requires it to be written down. An application with no sanction primitive
+     * has nothing an earlier revision could have removed, so there is nothing for
+     * a correction to put back.
+     */
+    if (decision.outcome !== 'no_violation')
+        return planned;
+    /**
+     * EVERY declared restore, not just the first. An application whose levers are
+     * "hide it" and "label it" has two things a correction must undo, and planning
+     * one leaves the other stuck forever — the object is un-hidden and stays
+     * labelled, with no error and nothing failing. That is the same failure this
+     * function exists to prevent, applied to the second reversible action instead
+     * of the first.
+     *
+     * A restore with nothing to undo is not waste: the executor records
+     * `changed: false` with its reason, which is evidence that it was checked.
+     */
+    const missing = restoreActions(declared).filter((action) => !planned.some((entry) => entry.action === action));
+    if (missing.length === 0)
+        return planned;
+    return [
+        ...planned,
+        ...missing.map((action) => ({
+            action,
+            reason: 'No violation: undo any earlier restriction',
+        })),
+    ];
+}
+/**
+ * Collapse a plan to the actions that can coexist.
+ *
+ * A decision may recommend both removal and a label; a removed object does not
+ * need one, and recording both would claim two effects where one happened. So an
+ * action absorbs whatever the application declared it absorbs, and the explicit
+ * "nothing" never survives alongside anything else.
+ *
+ * `reviewAction` always survives — it is a note for a human, and dropping it
+ * because something else was also done is how a `suspend_user` recommendation
+ * gets lost.
+ */
+function collapse(actions, config) {
+    const byAction = new Map();
+    for (const planned of actions) {
+        if (!byAction.has(planned.action))
+            byAction.set(planned.action, planned);
+    }
+    for (const [action, absorbed] of Object.entries(config.absorb ?? {})) {
+        if (!byAction.has(action))
+            continue;
+        for (const loser of absorbed ?? []) {
+            if (loser === config.reviewAction)
+                continue;
+            byAction.delete(loser);
+        }
+    }
+    if (byAction.size > 1)
+        byAction.delete(config.noneAction);
+    return Array.from(byAction.values());
+}
+/**
+ * What the application will do about this decision.
+ *
+ * Never empty: a decision that produces no action produces an explicit
+ * `noneAction`, because a row saying "we decided to do nothing, and why" is
+ * evidence and an absent row is a question.
+ */
+/**
+ * Raised when `restoreAction` names actions that are being UNDONE rather than
+ * actions that DO the undoing.
+ *
+ * A doc line is not enough for this one. An inverted `restoreAction` type-checks
+ * — both directions are `TAction[]` — and it does not fail at runtime either: it
+ * plans, it claims, and it applies a restriction and a label on an accepted
+ * appeal. It succeeds at the opposite thing, on the one path whose whole purpose
+ * is to give something back.
+ *
+ * The signal is unambiguous when it exists. `reverses` maps each undoing action
+ * to what it undoes, so its VALUES are targets and its KEYS are actors. An
+ * action that appears only as a target has been declared as a restore by
+ * someone reading the targets, which is exactly the mistake this catches.
+ *
+ * Deliberately narrow: an action absent from `reverses` entirely is fine (it may
+ * undo something needing no previous state), and one that is both a key and a
+ * value is fine (it undoes and is undone). Only "a target, and never an actor"
+ * is reported, so a correct configuration cannot trip it.
+ */
+export class ModerationRestoreDirectionError extends Error {
+    constructor(inverted) {
+        super(`restoreAction names [${inverted.join(', ')}], which 'reverses' lists as actions ` +
+            'being UNDONE rather than actions that do the undoing. restoreAction holds what ' +
+            "the planner emits on 'no_violation' — the restoring actions, e.g. " +
+            "['restore', 'unlabel_sensitive'] — not the restrictions being lifted. As written, " +
+            'an accepted appeal would apply the punishment it was correcting.');
+        this.name = 'ModerationRestoreDirectionError';
+    }
+}
+/**
+ * Refuse an inverted `restoreAction` at construction rather than at the first
+ * correction, which may be weeks later and reads as a moderation decision
+ * rather than a configuration error.
+ */
+export function assertRestoreDirection(config) {
+    const reverses = config.reverses ?? {};
+    const entries = Object.entries(reverses);
+    const actors = new Set(entries.map(([actor]) => actor));
+    const targets = new Set();
+    for (const [, undone] of entries) {
+        if (undone === undefined)
+            continue;
+        for (const action of typeof undone === 'string' ? [undone] : undone) {
+            targets.add(action);
+        }
+    }
+    const inverted = restoreActions(config.restoreAction).filter((action) => targets.has(action) && !actors.has(action));
+    if (inverted.length > 0)
+        throw new ModerationRestoreDirectionError(inverted);
+}
+export function planEnforcement(decision, config) {
+    const fromRecommendations = decision.recommendedActions.map((recommended) => ({
+        action: actionForRecommendation(recommended.action, config),
+        reason: `CrowdSource recommended ${recommended.action}`,
+        recommendedAction: recommended.action,
+    }));
+    if (fromRecommendations.length > 0) {
+        const collapsed = collapse(withRestoreForNoViolation(decision, fromRecommendations, config.restoreAction), config);
+        return collapsed.length > 0
+            ? collapsed
+            : [
+                {
+                    action: config.noneAction,
+                    reason: 'No recommended action maps to an effect this application has',
+                },
+            ];
+    }
+    switch (decision.outcome) {
+        case 'violation': {
+            const severity = highestSeverity(decision);
+            /**
+             * A `violation` with no findings cannot happen — the contract refuses it —
+             * so an absent severity here means a newer CrowdSource sent something this
+             * code has not seen. A human looks at it rather than a default removing an
+             * object.
+             */
+            if (severity === undefined) {
+                return [
+                    {
+                        action: config.reviewAction,
+                        reason: 'Violation carried no finding severity this version understands',
+                    },
+                ];
+            }
+            return [
+                {
+                    action: config.severityFallback?.[severity] ?? config.reviewAction,
+                    reason: `Violation with no recommended action, highest severity ${severity}`,
+                },
+            ];
+        }
+        case 'no_violation':
+            /**
+             * A restore, always planned — even when nothing was restricted. The
+             * executor records it as not applied with the reason, which is how "we
+             * checked and there was nothing to undo" is distinguishable from "we never
+             * looked".
+             */
+            {
+                const declared = restoreActions(config.restoreAction);
+                return declared.length === 0
+                    ? [
+                        {
+                            action: config.noneAction,
+                            reason: 'No violation, and this application has nothing to restore',
+                        },
+                    ]
+                    : declared.map((action) => ({
+                        action,
+                        reason: 'No violation: undo any earlier restriction',
+                    }));
+            }
+        case 'insufficient_context':
+        case 'inconclusive':
+        case 'escalated':
+            /**
+             * None of these is "remove", and none is "it was fine": absence of
+             * consensus is neither guilt nor innocence, so the application changes
+             * nothing on its own and asks a human.
+             */
+            return [
+                {
+                    action: config.reviewAction,
+                    reason: `Outcome ${decision.outcome}: no automatic action, internal review`,
+                },
+            ];
+        case 'content_unavailable':
+        case 'duplicate':
+            return [
+                {
+                    action: config.noneAction,
+                    reason: `Outcome ${decision.outcome}: nothing to enforce`,
+                },
+            ];
+        default:
+            /**
+             * An outcome the contract does not currently define. A newer server must
+             * not break an older client, and the safe reading of an unknown outcome is
+             * a human, never a default effect.
+             */
+            return [
+                {
+                    action: config.reviewAction,
+                    reason: 'Decision outcome not recognised by this version of the application',
+                },
+            ];
+    }
+}
+/**
+ * The one action worth recording on the report.
+ *
+ * One field, several planned actions, so it has to be the one that answers "what
+ * happened to this object". The application's `precedence` decides, strongest
+ * first — and `reviewAction` should sit near the end but ABOVE `noneAction`,
+ * because a reporter told "nothing happened" when a human is about to look is
+ * being told something untrue.
+ */
+export function primaryAction(actions, precedence) {
+    for (const candidate of precedence) {
+        if (actions.includes(candidate))
+            return candidate;
+    }
+    return actions[0];
+}
+//# sourceMappingURL=planner.js.map

package/dist/esm/outbox/enforcement/planner.js.map

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

package/dist/esm/outbox/evidence.js

@@ -0,0 +1,173 @@
+import { createHash } from 'crypto';
+/**
+ * Turning a stored report into the thing the SDK delivers.
+ *
+ * This is NOT a case-envelope builder, and the difference matters enough to
+ * name: `@crowdsource.you/core` builds the Case Envelope, and it deliberately does
+ * not export the function that does it. What this module produces is the SDK's
+ * `ReportInput` — a description of the material — and the SDK derives the
+ * envelope from it: resource ids, relations, digests, pseudonymous principal
+ * refs, the identity binding proof, the pinned policy version, the privacy terms
+ * and the idempotency key.
+ *
+ * That is not a technicality. Those derived values are exactly what the case
+ * dedup key is computed over, so an application that composed its own envelope
+ * would be the reason two reporters about one object opened two cases — and "one
+ * penalty per incident" would fail in production with nothing failing in a test.
+ * Building the description and letting the SDK build the document is what keeps
+ * that property true for every application at once.
+ *
+ * So this module does three things and no more: ask the registry for a snapshot
+ * of the reported object, translate the reporter's categories into allegations,
+ * and assemble both with the report's own identity.
+ */
+/**
+ * The material could not be described, because nothing can describe it.
+ *
+ * This is a DEFECT, not a state, and it should be unreachable. A report whose
+ * type has no subject provider never gets a delivery event in the first place —
+ * intake decides that from the same registry this module reads — so an event
+ * that arrives here has been created by something that bypassed intake, or by a
+ * deployment where a provider was removed while its reports were still in
+ * flight.
+ *
+ * `retryable: false` therefore dead-letters the outbox event, so the
+ * reconciliation sweep counts it and a human looks. The alternative — writing a
+ * local state — would file a genuine defect in the one place that looks
+ * identical to the deliberate local-only reports, and nothing would ever alert
+ * on it.
+ *
+ * Separate from "the object is gone": a deleted object is a fact about the world
+ * and closes the report normally.
+ */
+export class ModerationSubjectUnsupportedError extends Error {
+    constructor(reportedType) {
+        super(`No moderation subject provider is registered for '${reportedType}'.`);
+        this.retryable = false;
+        this.name = 'ModerationSubjectUnsupportedError';
+    }
+}
+/**
+ * The application's taxonomy produced no allegation for a report.
+ *
+ * Not retryable and never silently defaulted. A report with no allegation is not
+ * a report, and substituting `other.unclassifiable` here would put a claim in
+ * front of a jury that no reporter made and that no version of the mapping
+ * records — the taxonomy is the application's to fix, and dead-lettering is what
+ * makes somebody fix it.
+ */
+export class ModerationTaxonomyError extends Error {
+    constructor(categories) {
+        super(`The report taxonomy produced no allegation for categories [${categories.join(', ')}]. ` +
+            'Map every category to a code; use `other.unclassifiable` for one the universal taxonomy cannot name.');
+        this.retryable = false;
+        this.name = 'ModerationTaxonomyError';
+    }
+}
+/**
+ * SHA-256 of the snapshot, stored on the report.
+ *
+ * Taken over the described MATERIAL, not over the whole `ReportInput`: the
+ * report id, the reporter and the allegations are properties of the report, and
+ * including them would mean two people reporting identical content produced
+ * different hashes — which is the opposite of what this hash is for. Key order
+ * is fixed by the literal below rather than by `Object.keys`, so the digest is
+ * stable across Node versions and across a refactor that reorders a field.
+ */
+export function snapshotHash(snapshot) {
+    const canonical = JSON.stringify({
+        subject: {
+            externalId: snapshot.subject.externalId,
+            type: snapshot.subject.type,
+            author: snapshot.subject.author?.oxyUserId ?? null,
+        },
+        content: snapshot.content,
+        attachments: snapshot.attachments ?? [],
+        context: snapshot.context ?? [],
+    });
+    return `sha256:${createHash('sha256').update(canonical, 'utf8').digest('hex')}`;
+}
+export function createSubjectRegistry(providers) {
+    const byType = new Map();
+    for (const provider of providers) {
+        const existing = byType.get(provider.reportedType);
+        if (existing) {
+            /**
+             * Two providers for one noun is not a merge to resolve quietly: whichever
+             * one lost would describe nothing, and the subject type a jury reasons
+             * about would depend on array order.
+             */
+            throw new Error(`Two moderation subject providers are registered for '${provider.reportedType}' ` +
+                `('${existing.subjectType}' and '${provider.subjectType}'). A reported type has one provider.`);
+        }
+        byType.set(provider.reportedType, provider);
+    }
+    return {
+        providerFor: (reportedType) => byType.get(reportedType),
+        deliverableTypes: () => Array.from(byType.keys()),
+    };
+}
+/**
+ * Describe a stored report for delivery, or report why it cannot be described.
+ *
+ * Returns `null` when the reported object no longer exists. That is not an error
+ * either: content deleted between the report and its delivery is ordinary, and
+ * evidence stays available through retention on CrowdSource's side — but an
+ * object the application never got to snapshot has no evidence to keep.
+ */
+export async function buildModerationReportInput(input) {
+    const { report, registry, taxonomy } = input;
+    const provider = registry.providerFor(report.reportedType);
+    if (!provider)
+        throw new ModerationSubjectUnsupportedError(report.reportedType);
+    const snapshot = await provider.snapshot(report.reportedId);
+    if (!snapshot)
+        return null;
+    const allegationCodes = taxonomy.allegationsFor(report.categories);
+    if (allegationCodes.length === 0)
+        throw new ModerationTaxonomyError(report.categories);
+    const details = report.details?.trim();
+    return {
+        reportInput: {
+            externalReportId: report.id,
+            subject: snapshot.subject,
+            content: snapshot.content,
+            ...(snapshot.attachments === undefined ? {} : { attachments: snapshot.attachments }),
+            ...(snapshot.context === undefined ? {} : { context: snapshot.context }),
+            /**
+             * The reporter's own words ride on the FIRST allegation only.
+             *
+             * Repeating one free-text field across every code would say the reporter
+             * wrote it about each of them separately, and details are the reporter's
+             * claim and never evidence for it.
+             */
+            allegations: allegationCodes.map((code, index) => index === 0 && details ? { code, details } : { code }),
+            /**
+             * The Oxy subject IS the binding proof. Reporters are stored as Oxy user
+             * ids, so there is no separate binding step to implement here.
+             */
+            reportedBy: { oxyUserId: report.reporter },
+            /**
+             * The moment the USER reported it — the local report's own timestamp, not
+             * the moment of delivery. Any value invented per attempt would make every
+             * retry from the outbox a permanent 409.
+             */
+            submittedAt: report.createdAt,
+            metadata: {
+                /**
+                 * The application's own entries FIRST, so the two below cannot be
+                 * shadowed. An adopter that names `taxonomyVersion` or `categories` gets
+                 * them overwritten rather than winning — a case has to be readable back
+                 * against the mapping that produced it, and that is not negotiable per
+                 * application.
+                 */
+                ...taxonomy.metadata,
+                /** So a case can be read back against the mapping that produced it. */
+                taxonomyVersion: taxonomy.version,
+                categories: [...report.categories].sort().join(','),
+            },
+        },
+        snapshotHash: snapshotHash(snapshot),
+    };
+}
+//# sourceMappingURL=evidence.js.map

package/dist/esm/outbox/evidence.js.map

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

package/dist/esm/outbox/inbound.js

@@ -0,0 +1,87 @@
+import { decisionApplyEventId } from './outbox/service.js';
+import { MODERATION_EVENT_RETENTION_SECONDS } from './retention.js';
+/**
+ * What happens between "a signed decision arrived" and "2xx".
+ *
+ * The receiver's contract is to answer quickly and queue the processing. So
+ * exactly two writes happen here, in ONE transaction — the event's audit row is
+ * completed and a durable `decision.apply` event is created — and the dispatcher
+ * does the rest.
+ *
+ * The transaction is what makes the dedupe safe. The middleware has already
+ * claimed the event id by inserting the row (see {@link createProcessedEventStore});
+ * if completing that row and queueing the work were two operations, a crash
+ * between them would leave an event that is permanently deduplicated with no
+ * work queued — a decision silently lost, with a row that says it arrived.
+ * Committing both together means the only two possible outcomes are "recorded
+ * and queued" or "neither", and "neither" releases the claim and gets
+ * redelivered.
+ */
+/**
+ * The webhook dedupe store, backed by the moderation event log.
+ *
+ * `@crowdsource.you/core/express` defaults to an in-process store and says exactly
+ * when that is not enough: two instances behind a load balancer each keep their
+ * own, so a redelivery landing on the other instance is not deduplicated. Every
+ * Oxy backend runs several tasks behind one load balancer, so this is that case.
+ *
+ * The claim/release contract is the SDK's, and it is the right one. A row
+ * inserted BEFORE the handler runs means a concurrent redelivery cannot also run
+ * it; deleting that row when the handler THROWS means the sender's retry
+ * schedule can still deliver the event later. Recording the id only after
+ * success would let two copies run at once; recording it before and never
+ * releasing would make a transient failure permanent and lose a decision
+ * silently.
+ *
+ * The retention window is computed HERE rather than in a store, so both backends
+ * keep an audit row for the same length of time.
+ */
+export function createProcessedEventStore(events) {
+    return {
+        async claim(eventId) {
+            const now = new Date();
+            return await events.claim({
+                eventId,
+                receivedAt: now,
+                expiresAt: new Date(now.getTime() + MODERATION_EVENT_RETENTION_SECONDS * 1000),
+            });
+        },
+        async release(eventId) {
+            await events.release(eventId);
+        },
+    };
+}
+export function createInboundService(input) {
+    return {
+        async recordDecisionEvent(event) {
+            await input.transaction.run(async (tx) => {
+                const now = new Date();
+                await input.events.markQueued({
+                    eventId: event.eventId,
+                    type: event.type,
+                    caseId: event.caseId,
+                    payload: { caseId: event.caseId, decision: event.decision },
+                    now,
+                }, tx);
+                await input.outbox.enqueue({
+                    eventId: decisionApplyEventId(event.eventId),
+                    kind: 'decision.apply',
+                    payload: {
+                        eventId: event.eventId,
+                        caseId: event.caseId,
+                        decision: event.decision,
+                    },
+                }, tx);
+            });
+        },
+        async recordIgnoredEvent(event) {
+            await input.events.markIgnored({
+                eventId: event.eventId,
+                type: event.type,
+                ...(event.caseId === undefined ? {} : { caseId: event.caseId }),
+                now: new Date(),
+            });
+        },
+    };
+}
+//# sourceMappingURL=inbound.js.map

package/dist/esm/outbox/inbound.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbound.js","sourceRoot":"","sources":["../../../src/outbox/inbound.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAsB,MAAM,qBAAqB,CAAC;AAC/E,OAAO,EAAE,kCAAkC,EAAE,MAAM,gBAAgB,CAAC;AAGpE;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,yBAAyB,CACvC,MAAiC;IAEjC,OAAO;QACL,KAAK,CAAC,KAAK,CAAC,OAAe;YACzB,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,OAAO,MAAM,MAAM,CAAC,KAAK,CAAC;gBACxB,OAAO;gBACP,UAAU,EAAE,GAAG;gBACf,SAAS,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,kCAAkC,GAAG,IAAK,CAAC;aAChF,CAAC,CAAC;QACL,CAAC;QAED,KAAK,CAAC,OAAO,CAAC,OAAe;YAC3B,MAAM,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAChC,CAAC;KACF,CAAC;AACJ,CAAC;AAoCD,MAAM,UAAU,oBAAoB,CAAM,KAIzC;IACC,OAAO;QACL,KAAK,CAAC,mBAAmB,CAAC,KAAK;YAC7B,MAAM,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE;gBACvC,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;gBACvB,MAAM,KAAK,CAAC,MAAM,CAAC,UAAU,CAC3B;oBACE,OAAO,EAAE,KAAK,CAAC,OAAO;oBACtB,IAAI,EAAE,KAAK,CAAC,IAAI;oBAChB,MAAM,EAAE,KAAK,CAAC,MAAM;oBACpB,OAAO,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE;oBAC3D,GAAG;iBACJ,EACD,EAAE,CACH,CAAC;gBAEF,MAAM,KAAK,CAAC,MAAM,CAAC,OAAO,CACxB;oBACE,OAAO,EAAE,oBAAoB,CAAC,KAAK,CAAC,OAAO,CAAC;oBAC5C,IAAI,EAAE,gBAAgB;oBACtB,OAAO,EAAE;wBACP,OAAO,EAAE,KAAK,CAAC,OAAO;wBACtB,MAAM,EAAE,KAAK,CAAC,MAAM;wBACpB,QAAQ,EAAE,KAAK,CAAC,QAAQ;qBACzB;iBACF,EACD,EAAE,CACH,CAAC;YACJ,CAAC,CAAC,CAAC;QACL,CAAC;QAED,KAAK,CAAC,kBAAkB,CAAC,KAAK;YAC5B,MAAM,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC;gBAC7B,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;gBAC/D,GAAG,EAAE,IAAI,IAAI,EAAE;aAChB,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}