@ixo/decision-oracle 0.0.0-stage → 0.2.1

package/dist/lib/review/attestation.js

@@ -0,0 +1,264 @@
+/**
+ * The reviewer's signed review attestation (design §B.3) — a small Verifiable Credential the
+ * REVIEWER issues with their own Ed25519 key (the same PIN-unlocked key their UCAN invocations are
+ * signed with), saying in their own name: "I, <did>, answered claim <claimId> at oracle
+ * <oracleDid> against evaluation <resultDigest> with these answers."
+ *
+ * A DELIBERATE MIRROR of the engine's `src/lib/receipt/attestation.ts`. There is no shared package
+ * between this kit and the engine — same posture as the rubric format — so the two copies are kept
+ * in lock-step by hand, and BOTH verify: the kit because it is the only party that sees the
+ * reviewer's UCAN invocation, the engine because it trusts nothing this kit asserts about the
+ * reviewer (§B.5). A change here needs the matching change there.
+ *
+ * Fail closed, at the first miss: every refusal carries its own code and nothing half-verified ever
+ * passes. The keys come from the SAME composite DID resolver `middleware/ucan-auth.ts` authenticates
+ * with, so an attestation can never verify against a key the UCAN layer would have rejected.
+ */
+import { base58btc } from "multiformats/bases/base58";
+import { z } from "zod";
+import { canonicalJson, cidForBytes } from "../hash.js";
+/**
+ * The attestation's JSON-LD context — a fixed CONSTANT on the namespace IXO operates, not a
+ * per-oracle URL: the same statement signed by two reviewers at two oracles must be the same
+ * vocabulary. Published as content in `ixofoundation/ns`; this kit never serves or resolves it.
+ */
+export const REVIEW_ATTESTATION_CONTEXT = "https://w3id.org/ixo/credentials/review-attestation/v1";
+/** The compact JWS protected header. `kid` is the `did:key` FORM of the signing key (§B.2) — not a
+ *  DID-document fragment — so the verifier's job is exactly one assertion: the chain publishes it. */
+export const ReviewAttestationHeaderSchema = z.strictObject({
+    alg: z.literal("EdDSA"),
+    typ: z.literal("vc+jwt"),
+    cty: z.literal("vc"),
+    kid: z.string().startsWith("did:key:"),
+});
+export const ReviewAttestationSchema = z.strictObject({
+    /** The second entry is canonically `REVIEW_ATTESTATION_CONTEXT`, but it is typed as a plain
+     *  string ON PURPOSE: a verifier must never refuse a reviewer's valid signature because a context
+     *  document has not been published yet, or was published under a different path. It is
+     *  provenance, not a check. */
+    "@context": z.tuple([z.literal("https://www.w3.org/ns/credentials/v2"), z.string().min(1)]),
+    id: z.string().min(1),
+    type: z.tuple([z.literal("VerifiableCredential"), z.literal("ClaimReviewAttestation")]),
+    issuer: z.string().min(1),
+    /** The reviewer's browser clock — provenance only, never compared, so skew cannot refuse a review. */
+    validFrom: z.iso.datetime(),
+    credentialSubject: z.strictObject({
+        id: z.string().min(1),
+        claimId: z.string().min(1),
+        oracleDid: z.string().min(1),
+        answeredAgainst: z.string().min(1),
+        answers: z.record(z.string(), z.union([z.boolean(), z.string()])),
+    }),
+});
+/** Field NAMES and reasons only — a failure list never carries an answer value. */
+const fail = (code, failures) => ({
+    ok: false,
+    code,
+    failures,
+});
+// Built once per isolate (module-level promise), the same posture as the UCAN validator: the
+// composite `ucan-auth.ts` builds MINUS its local resolver (this oracle's own did:web is never a
+// reviewer).
+let resolverPromise = null;
+function getResolver(config) {
+    resolverPromise ??= (async () => {
+        const u = await import("@ixo/ucan");
+        return u.createCompositeDIDResolver([
+            u.createIxoDIDResolver({ indexerUrl: config.BLOCKSYNC_GRAPHQL_URL }),
+            u.createWebDIDResolver({ fallbackToHttp: config.ENVIRONMENT !== "production" }),
+        ]);
+    })();
+    return resolverPromise;
+}
+/**
+ * Did the resolver ANSWER (no such document, no usable key, no resolver for this DID method), or
+ * did it fail to reach its source? The first is deterministic and must be a 400 — retrying cannot
+ * change it, and a 503 would have a portal looping forever on a reviewer DID that will never
+ * resolve. The second is transient and must stay a 503.
+ *
+ * `@ixo/ucan` returns ONE `{ name, did, message }` shape for both, so this reads the messages its
+ * resolvers build (`did/ixo-resolver.ts`, `did/web-resolver.ts`) — brittle by construction, which
+ * is exactly why the DEFAULT is the retryable side: an unrecognised failure must never be reported
+ * as "this reviewer has no such key", which is permanent and would refuse a valid signature
+ * forever. Byte-for-byte the rule the ENGINE applies to a resolver's error RESULT
+ * (`src/lib/receipt/attestation.ts`: same patterns, same 408/429 carve-out, same `from <url>`
+ * narrowing, same default) — the two services must answer the same code for the same reviewer, so
+ * this is a copy, not an independent reading. The real fix is a `kind` discriminator on
+ * `DIDKeyResolutionError` upstream.
+ *
+ * A resolver that THROWS instead of returning an error is transient on BOTH sides: the throw came
+ * from inside the resolve call, which reached nothing and can therefore say nothing about the
+ * reviewer, so each service catches it and answers `ATTESTATION_UNRESOLVABLE` (503). BUILDING the
+ * resolver is the other case and still a 500 on both — a misconfigured service is our fault, not a
+ * reviewer's, and no retry of theirs fixes it.
+ */
+function deterministicResolution(error) {
+    const message = error !== null && typeof error === "object" && typeof error.message === "string"
+        ? error.message
+        : String(error);
+    // The source was reached and said no: Blocksync indexed no such IID; the document carried no
+    // Ed25519 verification method; no resolver in the composite handles this DID method at all.
+    if (/DID document not found/i.test(message))
+        return true;
+    if (/No valid Ed25519 verification methods found/i.test(message))
+        return true;
+    if (/No resolver could handle/i.test(message))
+        return true;
+    if (/not a did:/i.test(message))
+        return true;
+    const status = /HTTP (\d{3})/.exec(message);
+    if (status) {
+        const code = Number(status[1]);
+        // Back-pressure and timeouts are 4xx by number only — both mean "ask again", never "no such DID".
+        if (code === 408 || code === 429)
+            return false;
+        // WHOSE 4xx is it? The did:web lane names the document URL it fetched (`… from <url>: HTTP 404`),
+        // so a 4xx there really is "no document at the DID's own address" — deterministic. The ixo lane's
+        // message carries no URL (`Failed to fetch DID document: HTTP 400`) because it is OUR GraphQL
+        // POST to Blocksync being rejected — a bad query, a moved endpoint, a gateway in front of it.
+        // That says nothing about the reviewer and must stay retryable, or one malformed request on our
+        // side would permanently refuse every review on the network.
+        return code < 500 && /\bfrom \S+: HTTP /.test(message);
+    }
+    return false;
+}
+const b64urlToBytes = (part) => {
+    const padded = part.replace(/-/g, "+").replace(/_/g, "/");
+    return new Uint8Array([...atob(padded)].map((c) => c.charCodeAt(0)));
+};
+export const b64urlToText = (part) => new TextDecoder().decode(b64urlToBytes(part));
+/** The raw 32-byte Ed25519 key inside a `did:key`, or null if it is not one (§B.4 step 2). */
+export function ed25519KeyOf(kid) {
+    try {
+        const bytes = base58btc.decode(kid.slice("did:key:".length));
+        // multicodec `ed25519-pub` = 0xed 0x01, then exactly 32 key bytes.
+        if (bytes.length !== 34 || bytes[0] !== 0xed || bytes[1] !== 0x01)
+            return null;
+        return bytes.subarray(2);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Does the compact JWS's signature verify under the raw Ed25519 key? A malformed JWS or key does
+ * not. Shared with the Decision API's reviewer-key proof (`routes/v1/api/members.ts`), whose
+ * payload is not an attestation but whose signature is checked the same way.
+ */
+export async function ed25519JwsVerifies(publicKeyRaw, jws) {
+    const [headerPart, payloadPart, signaturePart, ...rest] = jws.split(".");
+    if (!headerPart || !payloadPart || !signaturePart || rest.length > 0)
+        return false;
+    try {
+        const key = await crypto.subtle.importKey("raw", publicKeyRaw, { name: "Ed25519" }, false, ["verify"]);
+        return await crypto.subtle.verify("Ed25519", key, b64urlToBytes(signaturePart), new TextEncoder().encode(`${headerPart}.${payloadPart}`));
+    }
+    catch {
+        return false;
+    }
+}
+/** Key-set equality plus per-key strict equality — NEVER a `canonicalJson` compare: the body and
+ *  the credential are serialised independently, and a value's JSON form is not what is compared. */
+function sameAnswers(a, b) {
+    const keys = Object.keys(a);
+    if (keys.length !== Object.keys(b).length)
+        return false;
+    return keys.every((key) => Object.hasOwn(b, key) && a[key] === b[key]);
+}
+/**
+ * Verify one attestation against what this request binds it to. Order is the fail-closed order of
+ * §B.5 — shape, then the issuer we already know, then key, then signature, then the remaining
+ * bindings — so a refusal always names the FIRST thing that is wrong rather than the most
+ * convenient one, and a refusal we can make with no network costs no network.
+ */
+export async function verifyReviewAttestation(deps, jws, expected) {
+    const [headerPart, payloadPart, signaturePart, ...rest] = jws.split(".");
+    if (!headerPart || !payloadPart || !signaturePart || rest.length > 0) {
+        return fail("ATTESTATION_INVALID", ["not a compact JWS"]);
+    }
+    let header;
+    let attestation;
+    let payloadText;
+    try {
+        header = ReviewAttestationHeaderSchema.parse(JSON.parse(b64urlToText(headerPart)));
+        payloadText = b64urlToText(payloadPart);
+        attestation = ReviewAttestationSchema.parse(JSON.parse(payloadText));
+    }
+    catch {
+        return fail("ATTESTATION_INVALID", ["header or payload is not a ClaimReviewAttestation"]);
+    }
+    // The payload part must BE canonical JSON: the stored bytes are what the signature and the CID
+    // address, so one credential must have exactly one serialisation (§B.3).
+    if (payloadText !== canonicalJson(attestation)) {
+        return fail("ATTESTATION_INVALID", ["payload is not canonical JSON"]);
+    }
+    // Whose signature is this claimed to be? Checked BEFORE anything resolves (fix round 2): the
+    // answer is already in hand, and resolving first would let an attacker aim one outbound Blocksync
+    // lookup per request at any DID string they like, on a refusal we could have made for free.
+    if (attestation.issuer !== expected.issuer) {
+        return fail("ATTESTATION_ISSUER_MISMATCH", ["issuer is not the invoking principal"]);
+    }
+    // The key the CHAIN publishes for the issuer. Two very different negatives live behind one error
+    // shape: a resolver that REACHED its source and was told "no such document / no Ed25519 key" is
+    // deterministic — `ATTESTATION_KEY_UNKNOWN`, a 400, because retrying cannot change it — while a
+    // resolver that could not reach its source is `ATTESTATION_UNRESOLVABLE`, a 503. A THROW never
+    // reached anything, so it is always the transient side. Same rule as the engine's, deliberately.
+    //
+    // A `did:key` issuer — a Decision API reviewer key (Go Prod §10) — IS its document: its one key
+    // is the DID itself, so there is nothing to resolve (whether it is a REGISTERED key is the
+    // caller's check, lib/api-lane/review.ts). On the chain lane a did:key principal could pass the
+    // UCAN layer (`rootIssuers: ['*']`), but the collection read gate refuses it before this runs
+    // (it is no owner, enroller or grantee: routes/v1/shared.ts).
+    let resolved;
+    if (attestation.issuer.startsWith("did:key:")) {
+        resolved = { ok: [attestation.issuer] };
+    }
+    else {
+        const resolver = await getResolver(deps.config);
+        try {
+            resolved = await resolver(attestation.issuer);
+        }
+        catch (err) {
+            return fail("ATTESTATION_UNRESOLVABLE", [String(err)]);
+        }
+    }
+    if (!("ok" in resolved)) {
+        return deterministicResolution(resolved.error)
+            ? fail("ATTESTATION_KEY_UNKNOWN", [
+                `${attestation.issuer} publishes no usable Ed25519 verification method`,
+            ])
+            : fail("ATTESTATION_UNRESOLVABLE", [`could not resolve ${attestation.issuer}`]);
+    }
+    if (!resolved.ok.includes(header.kid)) {
+        return fail("ATTESTATION_KEY_UNKNOWN", [
+            `${attestation.issuer} does not publish ${header.kid}`,
+        ]);
+    }
+    const publicKeyRaw = ed25519KeyOf(header.kid);
+    if (!publicKeyRaw)
+        return fail("ATTESTATION_INVALID", ["kid is not an Ed25519 did:key"]);
+    if (!(await ed25519JwsVerifies(publicKeyRaw, jws)))
+        return fail("ATTESTATION_INVALID", ["signature does not verify"]);
+    // Signed, and by a key the chain publishes for its issuer — now: is it about THIS request?
+    const subject = attestation.credentialSubject;
+    const failures = [];
+    if (subject.oracleDid !== expected.oracleDid)
+        failures.push("oracleDid");
+    if (subject.claimId !== expected.claimId)
+        failures.push("claimId");
+    if (subject.answeredAgainst !== expected.answeredAgainst)
+        failures.push("answeredAgainst");
+    if (!sameAnswers(subject.answers, expected.answers))
+        failures.push("answers");
+    if (failures.length > 0)
+        return fail("ATTESTATION_MISMATCH", failures);
+    // The address of the exact bytes we were handed — the same `CIDv1(raw, sha256)` a claim and a
+    // receipt use, so the folded receipt can name the attestation without carrying it.
+    return {
+        ok: true,
+        attestation,
+        cid: await cidForBytes(new TextEncoder().encode(jws)),
+        kid: header.kid,
+    };
+}
+//# sourceMappingURL=attestation.js.map

package/dist/lib/review/attestation.js.map

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

package/dist/lib/review/reviewer-grant.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Who may answer a chain claim's review (company authority D2; ownership review F1, F2, F12): a
+ * person the COMPANY named, never "whoever holds an evaluate grant". The grant is one `@ixo/ucan`
+ * delegation, `claims/review` on `ixo:oracle/<our did:web>/collection/<id>`, from a current
+ * controller of the collection's entity to the reviewer's `did:ixo` (docs/ENGINE-CONTRACT.md
+ * "Reviewer authority: `reviewerGrant`"). The owner files it here (`POST /v1/collections/:id/
+ * reviewers`), the reviewer sends it back with every answer, and the fold forwards it verbatim: the
+ * engine checks the root again itself and records it in the receipt.
+ *
+ * The gate runs at the answer AND inside the fold (workflows/review-complete.ts): a revoke, a
+ * controller removed, or an evaluate grant given to the reviewer between the two refuses the fold
+ * with no engine call. The revocation half is OURS alone this round (the engine checks only the
+ * root and the cap) — which is exactly why it must run at fold time too.
+ *
+ * Checks, in order — the cheap and deterministic first, the chain reads last:
+ *   1. the CAR (`parseReviewerGrant`): one delegation, no proofs, no extra block; the signature
+ *      verifies against the issuer's on-chain key; the capability is exactly `claims/review` on
+ *      this collection's resource (no wildcard); issuer and audience are distinct `did:ixo`
+ *      accounts; `nbf` and `exp` both set, `exp − nbf` ≤ 30 days (ucanto has no `iat`), and
+ *      `nbf ≤ now + 60 s < …`, `now < exp`                                         → 400 INVALID
+ *   2. the audience is the reviewer (the attestation issuer, the UCAN principal)  → 400 INVALID
+ *   3. revocation: the canonical CID is a `collection_reviewers` row, unrevoked  → 403
+ *   4. no identity of THIS oracle anywhere in the chain — its OWNER included        → 403
+ *   5. live root: the issuer is a current controller of the collection's entity  → 403
+ *   6. no `did:ixo` in the chain holds an `EvaluateClaimAuthorization` on the collection — read
+ *      uncached: an evaluator must not review (F12)                               → 403
+ * Blocksync, the chain or a DID resolver unreachable is a 503 (`AppError.unavailable`), never a pass;
+ * so is a collection with no entity — there is no controller to root a grant at (fail closed).
+ *
+ * Every refusal carries `details.reason` in the engine's CA4 vocabulary (`GrantRefusal`), so the
+ * Portal and the Console read one set whichever side refused. `revoked` is ours alone: the engine
+ * keeps no revocations this round.
+ */
+import type { Config } from "../../config.js";
+import type { Database } from "../../db/client.js";
+import { type CollectionReviewer } from "../../db/schema.js";
+import { AppError } from "../errors.js";
+import type { TraceContext } from "../tracing.js";
+/** The one ability a reviewer grant carries. */
+export declare const REVIEW_CAN = "claims/review";
+/** The longest a reviewer grant may live (`exp − nbf`), as the engine enforces it. */
+export declare const REVIEWER_GRANT_MAX_SEC: number;
+/** Clock skew allowed on `nbf`, as the engine allows it (CA4): a grant minted on a clock a little
+ *  ahead of ours stands at once. `exp` is strict on both sides. */
+export declare const REVIEWER_GRANT_SKEW_SEC = 60;
+/** `details.reason` of a refusal — the engine's CA4 vocabulary, plus our `revoked`. */
+export type GrantRefusal = "absent" | "unparseable" | "extra-block" | "shape" | "audience" | "identity" | "capability" | "resource" | "lifetime" | "not-yet-valid" | "expired" | "too-long" | "signature" | "root-not-controller" | "oracle" | "oracle-owner" | "evaluator" | "revoked";
+export interface ReviewerGrantDeps {
+    config: Config;
+    trace: TraceContext;
+    db: Database;
+}
+/** A verified grant, as `collection_reviewers` keeps it. */
+export interface ReviewerGrant {
+    /** The canonical CID (grant-chain.ts `summarize`) — the row's identity and what a revoke names. */
+    cid: string;
+    rootDid: string;
+    memberDid: string;
+    /** Seconds. */
+    exp: number;
+    /**
+     * The CAR: as sent, from `parseReviewerGrant`; as FILED, from `checkReviewerGrant` — the bytes
+     * the controller uploaded, which are what an answer stores and the fold forwards, never the copy
+     * the reviewer happened to send (the same grant, but not necessarily the same bytes).
+     */
+    delegation: string;
+}
+export declare const invalid: (reason: GrantRefusal, why: string) => AppError;
+export declare const notAuthorized: (reason: GrantRefusal, why: string) => AppError;
+/** Check 1 — the CAR alone: shape, signature, capability, identities and window. */
+export declare function parseReviewerGrant(config: Config, car: string, collectionId: string, now?: number): Promise<ReviewerGrant>;
+/**
+ * An API-lane root's grant to itself (owner 2026-10-10; the engine's `rootKind:
+ * company-controller`): an organisation's controller answering a review of one of its sources
+ * carries ONE self-link — issuer = audience = `controllerDid`, `claims/review` on
+ * `ixo:oracle/<our did:web>/source/<sourceId>`, the same window rules — signed with `keyDid`, the
+ * key its attestation was signed with (already proved to be on its IID). Its controller-ness is
+ * the console's live root check, and the engine re-reads it; no oracle identity may be the
+ * controller. Throws `REVIEWER_GRANT_INVALID` / `REVIEWER_NOT_AUTHORIZED` with `details.reason`.
+ */
+export declare function parseSelfReviewGrant(config: Config, car: string, scope: {
+    sourceId: string;
+    controllerDid: string;
+    keyDid: string;
+}, now?: number): Promise<ReviewerGrant>;
+/**
+ * An API-lane MEMBER's reviewer grant (owner 2026-10-10, S1: the engine refuses a company
+ * decision's fold without one): ONE CAR of exactly two links, root first —
+ *   1. a current controller of the source's organisation → the member's did:ixo: the member's
+ *      STORED, unrevoked role grant, matched by canonical CID (`delegationCid`) — so `mayReview`'s
+ *      reading of that row (capabilities, `nb.protocols`, which the engine does not read) is the
+ *      protocol limit; any other first link is refused;
+ *   2. the member's did:ixo → `reviewerKey`, the did:key the member registered and the answers
+ *      are signed with: exactly `claims/review` on this source.
+ * Per link, as the engine: no wildcard in any `can` / `with`, a `claims/review` cap on
+ * `ixo:oracle/<our did:web>/source/<sourceId>`, the window (`inWindow`), and no oracle identity.
+ * Deterministic checks first; the two signatures (each against its issuer's IID) last.
+ */
+export declare function parseMemberReviewGrant(config: Config, car: string, scope: {
+    sourceId: string;
+    memberDid: string;
+    reviewerKey: string;
+    delegationCid: string;
+    roots: readonly string[];
+}, now?: number): Promise<ReviewerGrant>;
+/**
+ * Check 4: no identity of this oracle in `dids` — nor its OWNER, the account that signed
+ * `OWNER_DELEGATION_CAR`: the engine counts the owner among the oracle's identities and refuses its
+ * fold, so an answer that names it is refused here, before anything is stored (owner 2026-10-11).
+ */
+export declare function assertNotOracle(config: Config, dids: readonly string[]): Promise<void>;
+/**
+ * The oracle's owner: the issuer of `OWNER_DELEGATION_CAR` (the AuthHub session that registered the
+ * oracle with the engine — lib/engine/client.ts `register`). Null when none is configured. Read once
+ * per isolate per CAR; our own secret, so no signature check. One that does not parse is a broken
+ * config and throws, loud — the engine could not register this oracle with it either.
+ */
+export declare function oracleOwnerDid(config: Config): Promise<string | null>;
+/**
+ * Checks 4–6 — what the chain says about the people in a grant, now. Shared with the grant route,
+ * which runs it before filing a grant so an owner hears "that person evaluates this collection" at
+ * once rather than at their reviewer's first answer.
+ */
+export declare function assertReviewerAuthority(deps: Omit<ReviewerGrantDeps, "db">, grant: Pick<ReviewerGrant, "rootDid" | "memberDid">, collectionId: string): Promise<void>;
+/**
+ * The whole gate (header): the grant the reviewer sent with an answer, for `reviewerDid` on
+ * `collectionId`. Throws the refusal; returns the verified grant.
+ */
+export declare function checkReviewerGrant(deps: ReviewerGrantDeps, car: string, scope: {
+    collectionId: string;
+    reviewerDid: string;
+}): Promise<ReviewerGrant>;
+/**
+ * The collection's filed grants that stand NOW — the read gate's reviewer path (routes/v1/shared.ts)
+ * and the review room (lib/matrix/deliver.ts): unrevoked, inside their window (`nbf ≤ now + skew`, `now < exp`;
+ * the row keeps no `nbf`, so it is read off the filed CAR), and from a root that is STILL a current
+ * controller of the collection's entity. The standing half of the gate — no signature check, the
+ * row was verified when it was filed; an answer and a fold run the whole of `checkReviewerGrant`.
+ * Controllers are read uncached, and only once a row survives the table's own filter, so a caller
+ * who was never granted costs no chain read. Blocksync trouble throws (503), never an empty answer.
+ */
+export declare function liveReviewerGrants(deps: Omit<ReviewerGrantDeps, "db">, db: Database, collectionId: string, opts?: {
+    memberDid?: string;
+    now?: Date;
+}): Promise<Pick<CollectionReviewer, "memberDid" | "rootDid" | "delegationCid">[]>;
+//# sourceMappingURL=reviewer-grant.d.ts.map

package/dist/lib/review/reviewer-grant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reviewer-grant.d.ts","sourceRoot":"","sources":["../../../src/lib/review/reviewer-grant.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,KAAK,kBAAkB,EAAuB,MAAM,iBAAiB,CAAC;AAC/E,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAerC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,gDAAgD;AAChD,eAAO,MAAM,UAAU,kBAAkB,CAAC;AAC1C,sFAAsF;AACtF,eAAO,MAAM,sBAAsB,QAAc,CAAC;AAClD;mEACmE;AACnE,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C,uFAAuF;AACvF,MAAM,MAAM,YAAY,GACpB,QAAQ,GACR,aAAa,GACb,aAAa,GACb,OAAO,GACP,UAAU,GACV,UAAU,GACV,YAAY,GACZ,UAAU,GACV,UAAU,GACV,eAAe,GACf,SAAS,GACT,UAAU,GACV,WAAW,GACX,qBAAqB,GACrB,QAAQ,GACR,cAAc,GACd,WAAW,GACX,SAAS,CAAC;AAId,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,YAAY,CAAC;IACpB,EAAE,EAAE,QAAQ,CAAC;CACd;AAED,4DAA4D;AAC5D,MAAM,WAAW,aAAa;IAC5B,mGAAmG;IACnG,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe;IACf,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,OAAO,WAAY,YAAY,OAAO,MAAM,aAIrD,CAAC;AAEL,eAAO,MAAM,aAAa,WAAY,YAAY,OAAO,MAAM,aAI3D,CAAC;AAwFL,oFAAoF;AACpF,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,MAAM,EACpB,GAAG,SAAgC,GAClC,OAAO,CAAC,aAAa,CAAC,CAiBxB;AAED;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,KAAK,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAClE,GAAG,SAAgC,GAClC,OAAO,CAAC,aAAa,CAAC,CAsBxB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,KAAK,EAAE;IACL,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B,EACD,GAAG,SAAgC,GAClC,OAAO,CAAC,aAAa,CAAC,CA4DxB;AAcD;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAY5F;AAID;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiBrE;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,IAAI,CAAC,iBAAiB,EAAE,IAAI,CAAC,EACnC,KAAK,EAAE,IAAI,CAAC,aAAa,EAAE,SAAS,GAAG,WAAW,CAAC,EACnD,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC,CA6Bf;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,iBAAiB,EACvB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACnD,OAAO,CAAC,aAAa,CAAC,CA0BxB;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,IAAI,CAAC,iBAAiB,EAAE,IAAI,CAAC,EACnC,EAAE,EAAE,QAAQ,EACZ,YAAY,EAAE,MAAM,EACpB,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,IAAI,CAAA;CAAO,GAC5C,OAAO,CAAC,IAAI,CAAC,kBAAkB,EAAE,WAAW,GAAG,SAAS,GAAG,eAAe,CAAC,EAAE,CAAC,CA0BhF"}