kiokuko-dsh 0.1.0

package/dist/gateway/checkpoint-service.d.ts

@@ -0,0 +1,40 @@
+import type { SqliteDatabase } from '../db/adapter.js';
+import type { Recommendation } from '../context/recommendations.js';
+import type { DeliveredNudge } from '../context/nudges.js';
+import { type CheckpointMutationResult } from './checkpoint-mutation-service.js';
+import { type ValidatedNudgeDeliveryRequest } from './nudge-delivery-service.js';
+export { CheckpointMutationService } from './checkpoint-mutation-service.js';
+export type { CheckpointMutationResult } from './checkpoint-mutation-service.js';
+export { NudgeDeliveryService } from './nudge-delivery-service.js';
+export type { ValidatedNudgeDeliveryRequest } from './nudge-delivery-service.js';
+export interface CheckpointResponse extends Omit<CheckpointMutationResult, 'preliminaryRecommendations'> {
+    readonly recommendations: readonly Recommendation[];
+    readonly nudge: DeliveredNudge | null;
+    readonly context: null;
+    readonly untrusted: true;
+}
+export interface LegacyCheckpointServicePort {
+    checkpoint(input: unknown): CheckpointResponse;
+    deliverNudge(input: ValidatedNudgeDeliveryRequest): DeliveredNudge | null;
+}
+export declare class CheckpointService {
+    private readonly mutation;
+    private readonly nudgeDelivery;
+    constructor(database: SqliteDatabase, now?: () => string);
+    /** @deprecated Use CheckpointMutationService and NudgeDeliveryService directly. */
+    checkpoint(input: unknown): CheckpointResponse;
+    /** @deprecated Use NudgeDeliveryService directly. */
+    deliverNudge(input: ValidatedNudgeDeliveryRequest): DeliveredNudge | null;
+}
+export interface FeedbackResponse {
+    category: 'context' | 'recommendation' | 'intake' | 'run';
+    record: unknown;
+    untrusted: true;
+}
+export declare class FeedbackService {
+    private readonly database;
+    private readonly now;
+    constructor(database: SqliteDatabase, now?: () => string);
+    feedback(input: unknown): FeedbackResponse;
+}
+//# sourceMappingURL=checkpoint-service.d.ts.map

package/dist/gateway/checkpoint-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-service.d.ts","sourceRoot":"","sources":["../../src/gateway/checkpoint-service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAQvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAO3D,OAAO,EAA6B,KAAK,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAC5G,OAAO,EAAwB,KAAK,6BAA6B,EAAE,MAAM,6BAA6B,CAAC;AAEvG,OAAO,EAAE,yBAAyB,EAAE,MAAM,kCAAkC,CAAC;AAC7E,YAAY,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AACjF,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,YAAY,EAAE,6BAA6B,EAAE,MAAM,6BAA6B,CAAC;AAEjF,MAAM,WAAW,kBAAmB,SAAQ,IAAI,CAAC,wBAAwB,EAAE,4BAA4B,CAAC;IACtG,QAAQ,CAAC,eAAe,EAAE,SAAS,cAAc,EAAE,CAAC;IACpD,QAAQ,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,2BAA2B;IAC1C,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,kBAAkB,CAAC;IAC/C,YAAY,CAAC,KAAK,EAAE,6BAA6B,GAAG,cAAc,GAAG,IAAI,CAAC;CAC3E;AAkBD,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;IACrD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAuB;gBAEzC,QAAQ,EAAE,cAAc,EAAE,GAAG,GAAE,MAAM,MAAuC;IAKxF,mFAAmF;IACnF,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,kBAAkB;IAY9C,qDAAqD;IACrD,YAAY,CAAC,KAAK,EAAE,6BAA6B,GAAG,cAAc,GAAG,IAAI;CAG1E;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,SAAS,GAAG,gBAAgB,GAAG,QAAQ,GAAG,KAAK,CAAC;IAC1D,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;CACjB;AAyED,qBAAa,eAAe;IACd,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAAkB,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAA9C,QAAQ,EAAE,cAAc,EAAmB,GAAG,GAAE,MAAM,MAAuC;IAE1H,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB;CAa3C"}

package/dist/gateway/checkpoint-service.js

@@ -0,0 +1,149 @@
+import { isProxy } from 'node:util/types';
+import { withImmediateTransaction } from '../db/transaction.js';
+import { KiokukoError } from '../errors.js';
+import { readRunIntakeLink } from '../akinator/store.js';
+import { LedgerStore } from '../ledger/store.js';
+import { validateTimestamp } from '../ledger/validate.js';
+import { executeIdempotentInTransaction } from '../server/idempotency.js';
+import { recordContextFeedbackInTransaction, recordIntakeFeedbackInTransaction, recordRunFeedbackInTransaction, validateFeedbackTimestamp, } from '../context/feedback.js';
+import { CheckpointMutationService } from './checkpoint-mutation-service.js';
+import { NudgeDeliveryService } from './nudge-delivery-service.js';
+export { CheckpointMutationService } from './checkpoint-mutation-service.js';
+export { NudgeDeliveryService } from './nudge-delivery-service.js';
+function validation() {
+    throw new KiokukoError('VALIDATION_ERROR', 'Invalid gateway request');
+}
+function assertPlainObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value) || isProxy(value))
+        validation();
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        validation();
+    return value;
+}
+function boundedString(value, max = 4_096) {
+    if (typeof value !== 'string' || value.length === 0 || value.length > max || /\p{Cc}/u.test(value))
+        validation();
+    return value;
+}
+export class CheckpointService {
+    mutation;
+    nudgeDelivery;
+    constructor(database, now = () => new Date().toISOString()) {
+        this.mutation = new CheckpointMutationService(database, now);
+        this.nudgeDelivery = new NudgeDeliveryService(database, now);
+    }
+    /** @deprecated Use CheckpointMutationService and NudgeDeliveryService directly. */
+    checkpoint(input) {
+        const result = this.mutation.checkpoint(input);
+        const { preliminaryRecommendations: _preliminaryRecommendations, ...mutation } = result;
+        return {
+            ...mutation,
+            recommendations: [...result.preliminaryRecommendations],
+            nudge: null,
+            context: null,
+            untrusted: true,
+        };
+    }
+    /** @deprecated Use NudgeDeliveryService directly. */
+    deliverNudge(input) {
+        return this.nudgeDelivery.deliver(input);
+    }
+}
+function feedbackRequest(raw) {
+    const input = assertPlainObject(raw);
+    const keys = Reflect.ownKeys(input);
+    const descriptors = Object.getOwnPropertyDescriptors(input);
+    const value = Object.create(null);
+    for (const key of keys) {
+        if (typeof key !== 'string')
+            validation();
+        const descriptor = descriptors[key];
+        if (!descriptor || !('value' in descriptor) || descriptor.enumerable !== true)
+            validation();
+        value[key] = descriptor.value;
+    }
+    if (value.apiVersion !== '1' || typeof value.category !== 'string' || !['context', 'recommendation', 'intake', 'run'].includes(value.category))
+        validation();
+    const categoryFields = value.category === 'context'
+        ? ['deliveryId', 'entryId', 'verdict']
+        : value.category === 'intake'
+            ? ['sessionId', 'questionId', 'profileField', 'verdict']
+            : ['outcome', 'recommendationCode', 'recommendationVerdict', 'rating'];
+    const allowed = new Set(['apiVersion', 'category', 'feedbackId', 'actor', 'createdAt', 'comment', ...categoryFields]);
+    if (keys.some((field) => typeof field !== 'string' || !allowed.has(field)))
+        validation();
+    if (Object.hasOwn(value, 'createdAt'))
+        validateFeedbackTimestamp(value.createdAt);
+    if (value.category === 'intake' && Object.hasOwn(value, 'sessionId'))
+        boundedString(value.sessionId, 256);
+    return value;
+}
+function feedbackField(value, field) {
+    return Object.hasOwn(value, field) ? value[field] : undefined;
+}
+function feedbackValue(database, runId, key, value, now) {
+    const run = new LedgerStore(database).readRun(runId);
+    if (!run)
+        throw new KiokukoError('NOT_FOUND', 'Ledger run not found');
+    const category = value.category;
+    const actor = Object.hasOwn(value, 'actor') ? boundedString(value.actor) : 'kiokuko-feedback';
+    const feedbackId = boundedString(value.feedbackId, 256);
+    const createdAt = Object.hasOwn(value, 'createdAt') ? validateFeedbackTimestamp(value.createdAt) : now;
+    const common = { workspace: run.workspace, feedbackId, actor, createdAt, idempotencyKey: key };
+    let record;
+    if (category === 'context') {
+        record = recordContextFeedbackInTransaction(database, {
+            ...common,
+            deliveryId: boundedString(feedbackField(value, 'deliveryId'), 256),
+            entryId: boundedString(feedbackField(value, 'entryId'), 256),
+            runId,
+            verdict: feedbackField(value, 'verdict'),
+            ...(feedbackField(value, 'comment') === undefined ? {} : { comment: feedbackField(value, 'comment') }),
+        });
+    }
+    else if (category === 'intake') {
+        const link = readRunIntakeLink(database, { workspace: run.workspace, runId });
+        record = recordIntakeFeedbackInTransaction(database, {
+            ...common,
+            runId,
+            sessionId: Object.hasOwn(value, 'sessionId') ? boundedString(value.sessionId, 256) : link.sessionId,
+            questionId: value.questionId ?? null,
+            profileField: value.profileField ?? null,
+            verdict: feedbackField(value, 'verdict'),
+            comment: value.comment ?? null,
+        });
+    }
+    else {
+        record = recordRunFeedbackInTransaction(database, {
+            ...common,
+            runId,
+            outcome: value.outcome ?? null,
+            recommendationCode: value.recommendationCode ?? null,
+            recommendationVerdict: value.recommendationVerdict ?? null,
+            rating: value.rating ?? null,
+            comment: value.comment ?? null,
+        });
+    }
+    return { category, record, untrusted: true };
+}
+export class FeedbackService {
+    database;
+    now;
+    constructor(database, now = () => new Date().toISOString()) {
+        this.database = database;
+        this.now = now;
+    }
+    feedback(input) {
+        const value = assertPlainObject(input);
+        if (typeof value.runId !== 'string' || value.runId.length === 0 || typeof value.idempotencyKey !== 'string' || value.idempotencyKey.length === 0)
+            validation();
+        const run = new LedgerStore(this.database).readRun(value.runId);
+        if (!run)
+            throw new KiokukoError('NOT_FOUND', 'Ledger run not found');
+        const now = validateTimestamp(this.now(), 'createdAt');
+        const request = feedbackRequest(value.request);
+        return withImmediateTransaction(this.database, () => executeIdempotentInTransaction(this.database, { scope: `agent.feedback.${value.runId}`, key: value.idempotencyKey, request, createdAt: now }, () => feedbackValue(this.database, value.runId, value.idempotencyKey, request, now)));
+    }
+}
+//# sourceMappingURL=checkpoint-service.js.map

package/dist/gateway/checkpoint-service.js.map

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

package/dist/gateway/nudge-delivery-service.d.ts

@@ -0,0 +1,21 @@
+import type { SqliteDatabase } from '../db/adapter.js';
+import type { LedgerProjection } from '../ledger/projection.js';
+import { type DeliveredNudge } from '../context/nudges.js';
+import type { Recommendation } from '../context/recommendations.js';
+export interface ValidatedNudgeDeliveryRequest {
+    readonly runId: string;
+    readonly idempotencyKey: string;
+    readonly throughSequence: number;
+    readonly projection: LedgerProjection;
+    readonly recommendations: readonly Recommendation[];
+}
+export interface NudgeDeliveryPort {
+    deliver(input: ValidatedNudgeDeliveryRequest): DeliveredNudge | null;
+}
+export declare class NudgeDeliveryService {
+    private readonly database;
+    private readonly now;
+    constructor(database: SqliteDatabase, now?: () => string);
+    deliver(input: ValidatedNudgeDeliveryRequest): DeliveredNudge | null;
+}
+//# sourceMappingURL=nudge-delivery-service.d.ts.map

package/dist/gateway/nudge-delivery-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nudge-delivery-service.d.ts","sourceRoot":"","sources":["../../src/gateway/nudge-delivery-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAKvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAiF,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE1I,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAEpE,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;IACtC,QAAQ,CAAC,eAAe,EAAE,SAAS,cAAc,EAAE,CAAC;CACrD;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,KAAK,EAAE,6BAA6B,GAAG,cAAc,GAAG,IAAI,CAAC;CACtE;AAED,qBAAa,oBAAoB;IACnB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAAkB,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAA9C,QAAQ,EAAE,cAAc,EAAmB,GAAG,GAAE,MAAM,MAAuC;IAE1H,OAAO,CAAC,KAAK,EAAE,6BAA6B,GAAG,cAAc,GAAG,IAAI;CAmDrE"}

package/dist/gateway/nudge-delivery-service.js

@@ -0,0 +1,67 @@
+import { withImmediateTransaction } from '../db/transaction.js';
+import { KiokukoError } from '../errors.js';
+import { canonicalContentHash } from '../serialization/validate.js';
+import { LedgerStore } from '../ledger/store.js';
+import { buildDeliveredNudge, deriveNudgeCandidates, NUDGE_POLICY_VERSION, selectNudge } from '../context/nudges.js';
+import { parseNewNudgeDelivery, readNudgeDeliveryForCheckpoint, readNudgeHistory, insertNudgeDelivery, serializeNudgeDelivery } from '../context/nudge-store.js';
+export class NudgeDeliveryService {
+    database;
+    now;
+    constructor(database, now = () => new Date().toISOString()) {
+        this.database = database;
+        this.now = now;
+    }
+    deliver(input) {
+        if (input.runId.length === 0 || input.idempotencyKey.length === 0
+            || !Number.isSafeInteger(input.throughSequence) || input.throughSequence < 0) {
+            throw new KiokukoError('VALIDATION_ERROR', 'Invalid nudge delivery request');
+        }
+        const checkpointId = canonicalContentHash({
+            kind: 'agent-checkpoint-nudge-v1',
+            runId: input.runId,
+            idempotencyKey: input.idempotencyKey,
+        });
+        const candidates = deriveNudgeCandidates(input.projection, input.recommendations);
+        return withImmediateTransaction(this.database, () => {
+            const run = new LedgerStore(this.database).readRun(input.runId);
+            if (!run)
+                throw new KiokukoError('NOT_FOUND', 'Ledger run not found');
+            if (run.lastSequence !== input.throughSequence) {
+                throw new KiokukoError('CONFLICT', 'Nudge delivery conflicts with current run state');
+            }
+            const existing = readNudgeDeliveryForCheckpoint(this.database, {
+                runId: input.runId,
+                policyVersion: NUDGE_POLICY_VERSION,
+                checkpointId,
+            });
+            if (existing !== null) {
+                const matchingCandidate = candidates.find((candidateValue) => candidateValue.occurrenceId === existing.occurrenceId);
+                if (matchingCandidate === undefined)
+                    return null;
+                if (matchingCandidate.code !== existing.code) {
+                    throw new KiokukoError('INTEGRITY_ERROR', 'Stored nudge occurrence binding is invalid');
+                }
+                return existing;
+            }
+            const history = readNudgeHistory(this.database, input.runId, NUDGE_POLICY_VERSION);
+            const selected = selectNudge(candidates, history, input.throughSequence);
+            if (selected === null)
+                return null;
+            const delivery = parseNewNudgeDelivery({
+                runId: input.runId,
+                policyVersion: NUDGE_POLICY_VERSION,
+                code: selected.code,
+                occurrenceId: selected.occurrenceId,
+                checkpointId,
+                throughSequence: input.throughSequence,
+                priority: selected.priority,
+                evidenceEventIds: selected.evidenceEventIds,
+                referenceIds: selected.referenceIds,
+                deliveredAt: this.now(),
+            });
+            insertNudgeDelivery(this.database, serializeNudgeDelivery(delivery));
+            return buildDeliveredNudge(selected);
+        });
+    }
+}
+//# sourceMappingURL=nudge-delivery-service.js.map

package/dist/gateway/nudge-delivery-service.js.map

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

package/dist/ledger/archive.d.ts

@@ -0,0 +1,48 @@
+import type { SqliteDatabase } from '../db/adapter.js';
+export declare const LEDGER_ARCHIVE_FORMAT: "kiokuko-ledger-jsonl";
+export declare const LEDGER_ARCHIVE_API_VERSION: "1";
+export declare const LEDGER_ARCHIVE_VERSION: 3;
+export declare const MAX_ARCHIVE_LINE_COUNT = 10000;
+export declare const MAX_ARCHIVE_LINE_BYTES: number;
+export declare const MAX_ARCHIVE_TOTAL_BYTES: number;
+export interface LedgerArchiveCounts {
+    runs: number;
+    sessions: number;
+    answers: number;
+    runIntakes: number;
+    intakeFeedback: number;
+    events: number;
+    evidence: number;
+    deliveries: number;
+    deliveryEntries: number;
+    nudgeDeliveries: number;
+    contextFeedback: number;
+    runFeedback: number;
+    memoryLinks: number;
+    purgeAudit: number;
+}
+export interface ExportLedgerArchiveOptions {
+    workspace: string;
+}
+export interface LedgerArchiveExport {
+    workspace: string;
+    counts: LedgerArchiveCounts;
+    checksum: string;
+    content: string;
+}
+export interface ImportLedgerArchiveOptions {
+    content: string;
+    workspace?: string;
+    dryRun?: boolean;
+}
+export interface LedgerArchiveImportResult {
+    workspace: string;
+    dryRun: boolean;
+    counts: LedgerArchiveCounts;
+    imported: LedgerArchiveCounts;
+    duplicates: LedgerArchiveCounts;
+    conflicts: number;
+}
+export declare function exportLedgerArchive(database: SqliteDatabase, options: ExportLedgerArchiveOptions): LedgerArchiveExport;
+export declare function importLedgerArchive(database: SqliteDatabase | undefined, options: ImportLedgerArchiveOptions): LedgerArchiveImportResult;
+//# sourceMappingURL=archive.d.ts.map

package/dist/ledger/archive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../../src/ledger/archive.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAe,MAAM,kBAAkB,CAAC;AAoBpE,eAAO,MAAM,qBAAqB,EAAG,sBAA+B,CAAC;AACrE,eAAO,MAAM,0BAA0B,EAAG,GAAY,CAAC;AACvD,eAAO,MAAM,sBAAsB,EAAG,CAAU,CAAC;AAIjD,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAC7C,eAAO,MAAM,sBAAsB,QAAa,CAAC;AACjD,eAAO,MAAM,uBAAuB,QAAmB,CAAC;AAkBxD,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,0BAA0B;IACzC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,mBAAmB,CAAC;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,yBAAyB;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,mBAAmB,CAAC;IAC5B,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,UAAU,EAAE,mBAAmB,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;CACnB;AAomBD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,cAAc,EAAE,OAAO,EAAE,0BAA0B,GAAG,mBAAmB,CAOtH;AAqbD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,cAAc,GAAG,SAAS,EAAE,OAAO,EAAE,0BAA0B,GAAG,yBAAyB,CA4CxI"}