@kindgi/api 0.0.0-bootstrap.0 → 0.1.1

package/dist/openapi/generate.js

@@ -0,0 +1,241 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * OpenAPI 3.1 document generator. Assembles `info` + `servers` +
+ * `components` + `paths` + `tags` from the operation registry
+ * (`operations.ts`) and the schema registry (`schemas.ts`).
+ *
+ * The output is a plain JSON-serializable object — the caller decides
+ * how to expose it (route handler, static file, both).
+ */
+import { OPERATIONS, honoToOpenapiPath, } from './operations.js';
+import { COMPONENT_SCHEMAS } from './schemas.js';
+const DEFAULT_INFO = {
+    title: 'Kindgi Platform API',
+    version: '0.1.0',
+    description: 'REST + SSE API for Kindgi: runs, agents, flows, human-in-the-loop approvals and the admin control plane. Generated from the route and schema registrations in `@kindgi/api` and drift-checked against the mounted routes.',
+};
+const DEFAULT_SERVERS = [
+    { url: '/', description: 'Same-origin — path relative to the deployment root.' },
+];
+const TAG_DESCRIPTIONS = {
+    system: 'Health + spec discovery.',
+    runs: 'Run lifecycle (start, list, get, cancel, resume, journal, stream).',
+    'signing-keys': 'The deployment trust list: the public keys whose signatures `POST /v1/deployments` accepts. Revoked keys stay readable for audit.',
+    tokens: 'API token administration (mint + revoke), and public run tokens: short-lived, read-only tokens a browser uses to follow specific runs.',
+    approvals: 'Human-in-the-loop review queue (role-scoped).',
+    observations: 'Supervisor readback of run outcomes.',
+    agents: 'Agent catalog (list, get, publish, unregister — caller-plugged registry).',
+    flows: 'Flow catalog (list, get, publish, unregister — caller-plugged registry). Enables non-agent workflows via HTTP — publish once, execute many via `POST /v1/runs`.',
+    tools: 'Tool catalog (list, get, register, unregister — caller-plugged registry, metadata-only).',
+    guardrails: 'Guardrail catalog (list, get, register, unregister — caller-plugged registry, metadata-only).',
+    conversations: 'Durable multi-turn threads (open, list, get, close, read messages).',
+    memory: 'Fact catalog + retrieval (list, get, write, supersede, retrieve — caller-plugged binding wraps the memory subsystem).',
+    proposals: 'Supervisor fix-proposal lifecycle (draft, dry-run, submit-review, apply, rollback, withdraw — caller-plugged binding wraps the supervisor).',
+    provenance: 'Causal DAG readback + signed exports (list, get, export — signing is caller-plugged via `SigningKeyBinding`).',
+    artifacts: 'Blob storage (list metadata, multipart upload, streaming download, HEAD, delete). Caller-plugged via `BlobStorageBinding` (from `@kindgi/blob-binding`).',
+    capabilities: 'Capability catalog (list + get) — part of the admin control plane. Read-only over HTTP. Capabilities are framework-declared (`FEATURES` enum + `@kindgi/specs/capability.schema.json`) and deployment-extended at boot time via `CapabilityRegistryBinding`; tenants do NOT author capabilities via the API.',
+    providers: 'Model-provider catalog (list, get, register, unregister, capabilities sub-resource) — part of the admin control plane. Full CRUD. `ProviderMetadata` is the wire shape; secrets never cross the wire (they live inside `ProviderRegistryBinding`). The capability router picks a best-fit provider from this set per capability requirement at run time.',
+    cost: 'Cost readback (list records, get record, aggregate across a required time window) — part of the admin control plane. Read-only over HTTP; records are written by the runtime usage instrumentation (agents, tools, sandboxes). Caller-plugged via `CostBinding`. Budgets are not enforced through this surface.',
+    adapters: 'Unified adapter catalog (list, get, test) — part of the admin control plane. Covers every adapter kind the deployment wired: model providers, embedding providers, blob storage, sandbox providers, eval judges. Read-only + smoke-test-only over HTTP; adapter lifecycle (register / unregister / reconfigure) is a deployment concern — the runtime learns about adapters at `CreateAppInput` time. Caller-plugged via `AdapterRegistryBinding`. Config is REDACTED on the wire — no secrets crossing.',
+    policies: 'Tenant policy catalog (list, get, versions, publish, unregister) — part of the admin control plane. Full versioned CRUD, mirrors `flows` 1:1. Registry-only: enforcement is out of scope. `policyKind` selects the shape of `spec` — closed enum, extended additively (`access-control`, `model-routing`, `adapter-allowlist`, `rate-limit`, `retention`, `compliance`). Runtime consumers (e.g. model routing for `model-routing`, retention sweeps for `retention`) read policies from this store and apply them at their own boundary. Caller-plugged via `PolicyRegistryBinding`.',
+    'eval-suites': 'Evaluation suite catalog (list, get, versions, publish, unregister) — part of the admin control plane. Full versioned CRUD, mirrors `policies` 1:1. Registry-only: eval-run execution + per-kind grader dispatch live on the `eval-runs` tag. `evalKind` selects the shape of `spec` — closed enum, extended additively (`accuracy`, `pairwise`, `regression`, `human-review`, `benchmark`, `custom`). Runs against these suites are started through the `eval-runs` tag. Caller-plugged via `EvalSuiteRegistryBinding`.',
+    'eval-runs': 'Eval-run data plane (start, list, get, cancel, events SSE). Dispatches an eval run against a registered suite. Dispatch is per-`EvalKind`; kinds without a registered dispatcher return `422 dispatcher-not-registered`. `result` is kind-specific opaque JSON on the wire — for `accuracy` it is `{ passCount, totalCount, meanScore, perCase[] }`. SSE events mirror run streaming: per-case progress followed by a terminal frame carrying the aggregate. Caller-plugged via `EvalRunBinding`.',
+    auth: 'OAuth 2.0 / OIDC identity providers + session lifecycle. Layers browser-based auth on top of the static bearer-token surface: bearer tokens continue to work byte-shape-identical; session tokens use the `kgi_sk_*` prefix so the same middleware routes both flavors. Providers are caller-plugged via `IdentityProviderBinding` (no baked-in list). Sessions persist via `SessionStoreBinding`. Code exchange is caller-supplied via `exchangeCode`. PKCE (S256) is mandatory. `clientSecretRef` is a REFERENCE — the plaintext secret never crosses the wire.',
+    identity: 'Tenant-scoped identity directory (list, get, list-active-sessions, revoke-sessions, whoami) — part of the admin control plane. Caller-plugged via `IdentityDirectoryBinding` — deployments plug in their own user store (LDAP, SCIM, or bespoke). Registry-only over HTTP: the framework does NOT own user persistence. The directory is flat; groups, roles, invitations, directory sync and impersonation are not part of this surface. `primaryEmail` may be redacted per tenant policy — the routes treat it as opaque. Provider access-token / refresh-token NEVER cross the wire, even to admins.',
+    mcp: "MCP-endpoint catalog (list, get, register, unregister). Tenants declare the remote MCP servers (`stdio` / `http-sse` / `streamable-http`) they want the runtime to consume. The runtime discovers each endpoint's tools and registers them into `ToolRegistryBinding` under the same tenant — remote MCP tools become native Kindgi tools without a recompile. Secrets never cross the wire: `secretRef` names a secret in the deployment's store, resolved at the endpoint's tenant scope. A deployment refuses `stdio` endpoints unless `KINDGI_TENANT_HOST_ACCESS=local`. Caller-plugged via `MCPEndpointRegistryBinding`.",
+    deployments: 'Signed pack deployments (register, list, get). The single wire surface that lands a signed OCI image + index.json into the platform. Register runs a six-step atomic transaction: Ed25519 signature verify over the canonical `{imageDigest, artifactVersion, indexHash, tenantId, publishedAt}` envelope, tenant-scoped trust-list check via `SigningKeyRegistryBinding`, image pullability + `/app/index.json` sha256 match via `ImageRegistryBinding`, per-primitive manifest validation, registry upserts (tools + guardrails + agents + flows), append-only deployment ledger row via `DeploymentBinding`. All-or-nothing rollback on any failure; digest-based idempotency (redeploying the same image returns the existing record). Records are immutable — rollback = re-register the previous digest.',
+    compliance: 'Compliance-evidence readback + signed exports (list, get, export). Reads are a classification lens over `AuditEventBinding`; only classifier-marked `exportable` kinds appear on the wire. Signed export is caller-plugged via `SigningKeyBinding` — deployments without a signing key get `404 signing-not-configured`. Bundle envelope matches `provenance.export` + audit-bundle byte-for-byte so verifiers reuse one `verifyEd25519` wrapper across all three surfaces. Redaction happens when evidence is generated, not at the export boundary — records are stored already redacted.',
+    audit: 'PDP decision audit stream (list). Every route-level authz `check()` emits one `AuditEvent` (kind `authz-decision`) via the `AuditEventBinding`; this route pages through them, tenant-scoped, with `?actorSubject=` / `?onBehalfOf=` / `?action=` / `?resource=` / `?outcome=` / `?runId=` / `?from=` / `?to=` filters. Admin@tenant only. This view is a filtered projection of the tenant audit events.',
+    orgs: 'Multi-tenant hierarchy — Org CRUD (list, create, get, patch, delete). Optional structural subdivision within a tenant; small tenants ignore Orgs entirely. Caller-plugged via `OrgBinding` from `@kindgi/platform`.',
+    teams: 'Multi-tenant hierarchy — Team CRUD (list, create, get, patch, delete) + `TeamMembership` sub-resource (list, add, updateRole, remove). People-groups that work together on projects; users belong to many teams. Team memberships are framework-owned (no external directory sync). Membership add is idempotent on `(teamId, userId)` — role mutation goes through PATCH.',
+    projects: 'Multi-tenant hierarchy — Project CRUD (list, create, get, patch, delete) + `/projects/default` shortcut + `ProjectMembership` sub-resource (list, add, updateRole, remove). Primary content scope: every content resource belongs to exactly one project. The Default project (`isDefault: true`) is auto-created per tenant at inception — exactly one per tenant, enforced at the storage layer.',
+    tenant: 'Sovereignty boundary readback + tenant-scoped config (get tenant; list + upsert entries routed to the env / secrets bindings). There is no `/v1/tenants` collection — the caller\'s tenant is implicit from the bearer token. `PATCH /config` routes writes to `SecretBinding` when `sensitive: true` OR `kind: "secret"`; else to `EnvBinding`. `GET /config` merges both bindings at tenant scope; secret values are ALWAYS redacted here. The `/config` sub-routes mount when at least one of `envBinding` / `secretsBinding` is wired. Prefer `/v1/env/*` + `/v1/secrets/*` for new callers.',
+    env: 'Non-sensitive per-env values (`/v1/env/*`). Every route requires `envName` + `scopeKind` (+ `scopeId` for org / project); `value` is present on every read path (env is non-sensitive by definition). Writes require the `env:write` capability. Caller-plugged via `EnvBinding` (`@kindgi/env-inmemory` is an in-memory implementation for development and tests).',
+    'webhook-endpoints': 'Outbound webhooks: endpoints the platform sends signed events to (`run.finished` when a top-level run completes, fails or is cancelled), their delivery log, redelivery and a test event. Signed in the Standard Webhooks format with a secret the endpoint references by name (`secretRef`); delivered at least once, so receivers deduplicate on `webhook-id`. Event bodies are under `webhooks`. Not to be confused with `/v1/webhooks`, which are inbound triggers. Caller-plugged via `WebhookEndpointBinding`.',
+    secrets: 'Sensitive per-env values (`/v1/secrets/*`). The ONLY endpoint that accepts plaintext is `POST /v1/secrets`; every other route is metadata-only (`value` NEVER returns on list / get / listVersions / getVersion — structural redaction). Rotation is discriminated: sync providers return 201 inline, async providers return 202 with a status URL + SSE events URL. Hard-revoke performs cryptographic erasure. Every mutating route is capability-gated (`secrets:write`, `secrets:rotate`, `secrets:revoke`, `secrets:revoke:hard`).',
+};
+export function generateOpenApiDocument(opts = {}) {
+    const info = { ...DEFAULT_INFO, ...opts.info };
+    const servers = opts.servers ?? DEFAULT_SERVERS;
+    const paths = buildPaths(OPERATIONS);
+    const components = {
+        schemas: Object.fromEntries(COMPONENT_SCHEMAS),
+        securitySchemes: {
+            bearerAuth: {
+                type: 'http',
+                scheme: 'bearer',
+                description: "Bearer token minted via `POST /v1/tokens` (or the deployment's equivalent). See `docs/API-ROUTE-CONVENTIONS.md` §2.",
+            },
+            publicRunToken: {
+                type: 'http',
+                scheme: 'bearer',
+                bearerFormat: 'kgi_pt',
+                description: 'Public run token (`kgi_pt_…`): short-lived and read-only, for a browser following specific runs. Returned by `POST /v1/runs` and minted by `POST /v1/tokens/public`. Accepted only by `GET /v1/runs/{runId}/progress` and its stream.',
+            },
+        },
+    };
+    const tags = uniqueTags(OPERATIONS).map((name) => ({
+        name,
+        ...(TAG_DESCRIPTIONS[name] !== undefined && { description: TAG_DESCRIPTIONS[name] }),
+    }));
+    return {
+        openapi: '3.1.0',
+        info,
+        servers,
+        tags,
+        components,
+        paths,
+        webhooks: buildOutboundWebhooks(),
+    };
+}
+/**
+ * The requests the platform sends to registered webhook endpoints
+ * (OpenAPI 3.1 `webhooks`): one entry per event type, all signed the same
+ * way.
+ */
+function buildOutboundWebhooks() {
+    const signatureHeaders = [
+        {
+            name: 'webhook-id',
+            in: 'header',
+            required: true,
+            description: 'The event id; the same on every retry. Deduplicate on it.',
+            schema: { type: 'string' },
+        },
+        {
+            name: 'webhook-timestamp',
+            in: 'header',
+            required: true,
+            description: 'Unix seconds when the request was signed. Reject requests far from your clock.',
+            schema: { type: 'string', pattern: '^[0-9]+$' },
+        },
+        {
+            name: 'webhook-signature',
+            in: 'header',
+            required: true,
+            description: '`v1,<base64 HMAC-SHA256 of "{webhook-id}.{webhook-timestamp}.{body}">` under the endpoint\'s secret; space-separated when two secrets sign during a rotation.',
+            schema: { type: 'string' },
+        },
+    ];
+    const event = (type, summary, schema) => ({
+        post: {
+            operationId: `webhook.${type}`,
+            summary,
+            tags: ['webhook-endpoints'],
+            // The receiver authenticates the request by its signature
+            // (`webhook-signature`), not by an API credential.
+            security: [],
+            parameters: signatureHeaders,
+            requestBody: {
+                required: true,
+                content: { 'application/json': { schema: { $ref: `#/components/schemas/${schema}` } } },
+            },
+            responses: {
+                '2XX': {
+                    description: 'Received. Any other answer, or none within 10 seconds, is retried.',
+                },
+            },
+        },
+    });
+    return {
+        'run.finished': event('run.finished', 'A top-level run completed, failed or was cancelled', 'RunFinishedEvent'),
+        'webhook.test': event('webhook.test', 'A test event sent on request (`POST /v1/webhook-endpoints/{endpointId}/test`)', 'WebhookTestEvent'),
+    };
+}
+// ---------------- internals ----------------
+function buildPaths(ops) {
+    const paths = {};
+    for (const op of ops) {
+        const key = op.openapiPath ?? honoToOpenapiPath(op.honoPath);
+        let bucket = paths[key];
+        if (bucket === undefined) {
+            bucket = {};
+            paths[key] = bucket;
+        }
+        if (bucket[op.method] !== undefined) {
+            throw new Error(`Duplicate operation for ${op.method.toUpperCase()} ${key}`);
+        }
+        bucket[op.method] = buildOperation(op);
+    }
+    return paths;
+}
+function buildOperation(op) {
+    const doc = {
+        operationId: op.operationId,
+        summary: op.summary,
+        tags: [...op.tags],
+        responses: buildResponses(op.responses),
+    };
+    if (op.description !== undefined)
+        doc.description = op.description;
+    if (op.parameters !== undefined && op.parameters.length > 0) {
+        doc.parameters = op.parameters.map(buildParameter);
+    }
+    if (op.requestBody !== undefined) {
+        const contentType = op.requestBody.contentType ?? 'application/json';
+        const contentSlot = { schema: op.requestBody.schema };
+        if (op.requestBody.encoding !== undefined) {
+            contentSlot.encoding = op.requestBody.encoding;
+        }
+        doc.requestBody = {
+            required: op.requestBody.required ?? true,
+            ...(op.requestBody.description !== undefined && {
+                description: op.requestBody.description,
+            }),
+            content: {
+                [contentType]: contentSlot,
+            },
+        };
+    }
+    if (op.security === 'bearer') {
+        doc.security = [{ bearerAuth: [] }];
+    }
+    else if (op.security === 'bearer-or-public-run') {
+        doc.security = [{ bearerAuth: [] }, { publicRunToken: [] }];
+    }
+    else {
+        doc.security = [];
+    }
+    return doc;
+}
+function buildParameter(p) {
+    const doc = {
+        name: p.name,
+        in: p.in,
+        schema: p.schema,
+    };
+    if (p.required !== undefined)
+        doc.required = p.required;
+    else if (p.in === 'path')
+        doc.required = true;
+    if (p.description !== undefined)
+        doc.description = p.description;
+    return doc;
+}
+function buildResponses(responses) {
+    const doc = {};
+    for (const [status, spec] of Object.entries(responses)) {
+        const entry = { description: spec.description };
+        if (spec.schema !== undefined) {
+            const contentType = spec.contentType ?? 'application/json';
+            entry.content = { [contentType]: { schema: spec.schema } };
+        }
+        doc[status] = entry;
+    }
+    return doc;
+}
+function uniqueTags(ops) {
+    const seen = new Set();
+    const out = [];
+    for (const op of ops) {
+        for (const t of op.tags) {
+            if (seen.has(t))
+                continue;
+            seen.add(t);
+            out.push(t);
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=generate.js.map

package/dist/openapi/generate.js.map

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

package/dist/openapi/operations.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Operation registry — the single source of truth for the OpenAPI
+ * document. Every route mounted on the Hono app has exactly one entry
+ * here; the drift test in `tests/openapi.test.ts` fails if that
+ * guardrail breaks.
+ *
+ * Fields:
+ * - `honoPath`  — the path segment as registered via `r.get(path, ...)` in
+ *                 the corresponding router. `:id` style.
+ * - `openapiPath` — OpenAPI 3.1 templated path (`{id}` style). Derived
+ *                 automatically by the drift test if you leave it out —
+ *                 but authored explicitly here so the emitted JSON is
+ *                 easy to scan.
+ * - `security`  — `'bearer'` (default) or `'public'`. Public routes are
+ *                 mounted outside the `/v1/*` auth chain.
+ *
+ * All request/response schemas are `$ref`s into
+ * `components.schemas` (populated from `schemas.ts`).
+ */
+import { type JsonSchema } from './schemas.js';
+export type HttpMethod = 'get' | 'post' | 'put' | 'patch' | 'delete' | 'head';
+export interface ParameterSpec {
+    readonly name: string;
+    readonly in: 'query' | 'header' | 'path';
+    readonly required?: boolean;
+    readonly description?: string;
+    readonly schema: JsonSchema;
+}
+export interface ResponseSpec {
+    readonly description: string;
+    /** JSON body schema for `application/json` responses. Omit for streaming responses. */
+    readonly schema?: JsonSchema;
+    /** Content-type of the response body. Defaults to `application/json`. */
+    readonly contentType?: string;
+}
+export interface OperationSpec {
+    readonly method: HttpMethod;
+    readonly honoPath: string;
+    readonly openapiPath: string;
+    readonly operationId: string;
+    readonly summary: string;
+    readonly description?: string;
+    readonly tags: readonly string[];
+    /**
+     * `bearer`: an API token. `bearer-or-public-run`: an API token, or a
+     * public run token (`kgi_pt_…`) naming the run, which gets the public
+     * view. `public`: no authentication.
+     */
+    readonly security: 'bearer' | 'bearer-or-public-run' | 'public';
+    readonly parameters?: readonly ParameterSpec[];
+    readonly requestBody?: {
+        readonly required?: boolean;
+        readonly description?: string;
+        readonly schema: JsonSchema;
+        /**
+         * Wire content type. Defaults to `application/json`. Set to
+         * `multipart/form-data` (or a comma-separated list) for uploads
+         * — the schema then describes the form parts, and OpenAPI will
+         * emit the appropriate `content.<type>` slot.
+         */
+        readonly contentType?: string;
+        /** Optional `encoding` map for multipart form parts. */
+        readonly encoding?: Readonly<Record<string, Record<string, unknown>>>;
+    };
+    readonly responses: Readonly<Record<string, ResponseSpec>>;
+}
+export declare const OPERATIONS: readonly OperationSpec[];
+/** Utility used by both the generator and the drift test. */
+export declare function honoToOpenapiPath(honoPath: string): string;
+//# sourceMappingURL=operations.d.ts.map

package/dist/openapi/operations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.d.ts","sourceRoot":"","sources":["../../src/openapi/operations.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,KAAK,UAAU,EAAO,MAAM,cAAc,CAAC;AAEpD,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE9E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;IACzC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;CAC7B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,uFAAuF;IACvF,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,sBAAsB,GAAG,QAAQ,CAAC;IAChE,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAC/C,QAAQ,CAAC,WAAW,CAAC,EAAE;QACrB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;QAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAC9B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;QAC5B;;;;;WAKG;QACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAC9B,wDAAwD;QACxD,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;KACvE,CAAC;IACF,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;CAC5D;AAyyBD,eAAO,MAAM,UAAU,EAAE,SAAS,aAAa,EA48IrC,CAAC;AAEX,6DAA6D;AAC7D,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE1D"}