@nodii/saga 0.0.2 → 0.2.0

package/dist/saga.d.ts

@@ -0,0 +1,48 @@
+import { type CreateSagaOpts, type SagaHandle, type StepOpts } from "./types";
+/**
+ * § 5.2 + § 5.8 — createSaga.
+ *
+ * Resume detection: if a `ResumeContext` is primed on the ALS (set by
+ * `withSaga`), the function reloads the saga from the state store and
+ * passes the persisted `step_outputs` map so completed steps short-circuit
+ * to their cached output via the idempotency layer.
+ */
+export declare function createSaga<O>(opts: CreateSagaOpts, fn: () => Promise<O>): Promise<O>;
+/**
+ * § 5.8 — withSaga primes a ResumeContext + an inner createSaga reloads.
+ *
+ * v0.1.0 surface: `withSaga(handle, fn)` runs `fn` in the saga's ALS scope
+ * with `resume.isResume = true`. The expected usage is for the inner
+ * function to call `createSaga` with the same type — that's how the registry
+ * gets re-entered.
+ */
+export declare function withSaga<O>(sagaId: string, fn: () => Promise<O>): Promise<O>;
+/**
+ * § 5.2 — step.
+ *
+ * Pipeline:
+ *   1. update saga_state.current_step = name
+ *   2. run handler via idempotency.wrapForSagaStep
+ *   3. on success: persist output, push undo record onto saga's undo stack
+ *   4. on failure: throw SagaStepFailed; createSaga catches + runs compensation
+ *
+ * `mode: 'best-effort'` per-step (or via the undo object form) makes
+ * compensation lenient — a thrown undo records `compensated_with_errors`
+ * instead of `compensation_failed`.
+ */
+export declare function step<O>(name: string, opts: StepOpts<O>): Promise<O>;
+/**
+ * § 5.2 — stepParallel. Fans out concurrently; collects results into an array.
+ *
+ * Compensation semantics match `step` — undos are pushed onto the stack in
+ * the order they completed, so reverse-order traversal is preserved.
+ */
+export declare function stepParallel<O>(steps: {
+    name: string;
+    opts: StepOpts<O>;
+}[]): Promise<O[]>;
+/** Public cancel entry-point (also reachable via handle.cancel). */
+export declare function cancel(sagaId: string, reason: string): Promise<void>;
+/** Read-only accessor for the active saga handle in scope. */
+export declare function currentSaga(): SagaHandle | null;
+//# sourceMappingURL=saga.d.ts.map

package/dist/saga.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"saga.d.ts","sourceRoot":"","sources":["../src/saga.ts"],"names":[],"mappings":"AAoBA,OAAO,EAEL,KAAK,cAAc,EAEnB,KAAK,UAAU,EAEf,KAAK,QAAQ,EAGd,MAAM,SAAS,CAAC;AAmFjB;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAChC,IAAI,EAAE,cAAc,EACpB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CA8EZ;AAED;;;;;;;GAOG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAC9B,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAGZ;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAgGzE;AAeD;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAA;CAAE,EAAE,GAC3C,OAAO,CAAC,CAAC,EAAE,CAAC,CAEd;AAuFD,oEAAoE;AACpE,wBAAsB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE1E;AAED,8DAA8D;AAC9D,wBAAgB,WAAW,IAAI,UAAU,GAAG,IAAI,CAE/C"}

package/dist/saga.js

@@ -0,0 +1,384 @@
+// createSaga / withSaga / step / stepParallel / saga.cancel.
+//
+// Spec §§ 5.2, 5.3, 5.8. v0.1.0 ships the deterministic core: state-store
+// CRUD, ALS-primed handle, idempotency-wrapped step execution, reverse-order
+// undo on failure (strict-mode halt vs best-effort `compensated_with_errors`),
+// `cancel()` → status='cancelled' + D33 audit event.
+//
+// Resume detection (§ 5.8) is wired but the reaper / grace-period orchestrator
+// is deferred (`// TODO saga-v0.1.x:`); same for cross-saga compensation as
+// library-spawned child saga (we record entries on `compensation_log` instead).
+import { getResumeContext, getSagaContext, requireSagaContext, runInSagaContext, runWithResumeContext, } from "./context";
+import { requireSaga } from "./init";
+import { uuidv7 } from "./uuid";
+import { SagaCompensationFailed, SagaStepFailed, } from "./types";
+import { beginAsyncStep, SagaPausedSentinel } from "./async-step";
+const nowIso = () => new Date().toISOString();
+const TERMINAL_STATUSES = new Set([
+    "completed",
+    "compensated",
+    "compensation_failed",
+    "compensated_with_errors",
+    "compensated_manual",
+    "technical_failure",
+    "cancelled",
+]);
+// We track per-saga undo stacks on the context so resume + cancel paths
+// don't lose them. Keyed by saga.id to support nested withSaga calls.
+const undoStacks = new Map();
+function pushUndo(sagaId, record) {
+    const stack = undoStacks.get(sagaId) ?? [];
+    stack.push(record);
+    undoStacks.set(sagaId, stack);
+}
+function takeUndoStack(sagaId) {
+    const stack = undoStacks.get(sagaId) ?? [];
+    undoStacks.delete(sagaId);
+    return stack;
+}
+function newSagaRow(opts) {
+    const id = opts.sagaId ?? uuidv7();
+    return {
+        id,
+        tenant_id: opts.tenantId ?? null,
+        type: opts.type,
+        status: "active",
+        current_step: null,
+        step_outputs: {},
+        episode: 1,
+        trigger_trace_id: opts.triggerTraceId ?? id,
+        trigger_span_id: opts.triggerSpanId ?? id,
+        trigger_request_id: opts.triggerRequestId ?? id,
+        parent_saga_id: opts.parent?.sagaId ?? null,
+        parent_relationship: opts.parentRelationship ?? "child",
+        children: [],
+        started_at: nowIso(),
+        completed_at: null,
+        next_resume_at: null,
+        failure_reason: null,
+        failure_step: null,
+        compensation_log: [],
+        last_admin_action: null,
+        last_admin_actor_id: null,
+        last_admin_at: null,
+        input: opts.input,
+        cancel_reason: null,
+    };
+}
+async function emitAuditEvent(action, sagaId, payload) {
+    const cfg = requireSaga();
+    if (!cfg.telemetryAudit)
+        return;
+    await cfg.telemetryAudit.emit({
+        action,
+        target_kind: "saga",
+        target_id: sagaId,
+        payload,
+    });
+}
+/**
+ * § 5.2 + § 5.8 — createSaga.
+ *
+ * Resume detection: if a `ResumeContext` is primed on the ALS (set by
+ * `withSaga`), the function reloads the saga from the state store and
+ * passes the persisted `step_outputs` map so completed steps short-circuit
+ * to their cached output via the idempotency layer.
+ */
+export async function createSaga(opts, fn) {
+    const cfg = requireSaga();
+    const resume = getResumeContext();
+    let row;
+    if (resume?.isResume) {
+        const existing = await cfg.stateStore.getSaga(resume.sagaId);
+        if (!existing) {
+            // Treat as a fresh saga — defensive: resume context referenced a row
+            // the store no longer has.
+            row = newSagaRow({ ...opts, sagaId: resume.sagaId });
+            await cfg.stateStore.createSaga(row);
+            await emitAuditEvent("saga_started", row.id, { type: row.type });
+        }
+        else {
+            row = existing;
+            await cfg.stateStore.updateSagaStatus(row.id, { status: "active" });
+            row.status = "active";
+            await emitAuditEvent("saga_resumed", row.id, { episode: row.episode });
+        }
+    }
+    else {
+        row = newSagaRow(opts);
+        await cfg.stateStore.createSaga(row);
+        await emitAuditEvent("saga_started", row.id, { type: row.type });
+    }
+    const handle = {
+        id: row.id,
+        type: row.type,
+        tenantId: row.tenant_id,
+        async cancel(reason) {
+            await cancelSaga(row.id, reason);
+        },
+    };
+    try {
+        const result = await runInSagaContext({ handle, row, resume, completedSteps: [] }, fn);
+        // If the saga was cancelled (or otherwise terminalized) mid-flight,
+        // do NOT overwrite to "completed". Re-read once to settle.
+        const latest = await cfg.stateStore.getSaga(row.id);
+        if (latest &&
+            !TERMINAL_STATUSES.has(latest.status) &&
+            latest.status !== "paused") {
+            await cfg.stateStore.updateSagaStatus(row.id, {
+                status: "completed",
+                completed_at: nowIso(),
+            });
+            await emitAuditEvent("saga_completed", row.id);
+        }
+        undoStacks.delete(row.id);
+        return result;
+    }
+    catch (err) {
+        // Pattern 2 sentinel — saga paused at an async step boundary. NOT a
+        // failure; the saga remains 'paused' and a downstream completion-event
+        // resumes it via withSaga(). Return the saga handle's id as the
+        // result placeholder (sentinel.sagaId).
+        if (err instanceof SagaPausedSentinel) {
+            // Don't touch status — beginAsyncStep already set it.
+            // Don't clear the undo stack — a future resume might need it.
+            return undefined;
+        }
+        // step() throws SagaStepFailed when its do-fn fails; we run compensation
+        // here so the user-facing API stays "createSaga rejects if any step
+        // fails after compensation runs". v0.1.0 compensation walks the per-saga
+        // undoStack in reverse.
+        if (err instanceof SagaStepFailed) {
+            await runCompensation(row.id, err.stepName);
+            throw err;
+        }
+        // Non-step errors (programming errors, etc.) propagate without changing
+        // status — the caller decides what to do.
+        throw err;
+    }
+}
+/**
+ * § 5.8 — withSaga primes a ResumeContext + an inner createSaga reloads.
+ *
+ * v0.1.0 surface: `withSaga(handle, fn)` runs `fn` in the saga's ALS scope
+ * with `resume.isResume = true`. The expected usage is for the inner
+ * function to call `createSaga` with the same type — that's how the registry
+ * gets re-entered.
+ */
+export async function withSaga(sagaId, fn) {
+    const ctx = { isResume: true, sagaId };
+    return runWithResumeContext(ctx, fn);
+}
+/**
+ * § 5.2 — step.
+ *
+ * Pipeline:
+ *   1. update saga_state.current_step = name
+ *   2. run handler via idempotency.wrapForSagaStep
+ *   3. on success: persist output, push undo record onto saga's undo stack
+ *   4. on failure: throw SagaStepFailed; createSaga catches + runs compensation
+ *
+ * `mode: 'best-effort'` per-step (or via the undo object form) makes
+ * compensation lenient — a thrown undo records `compensated_with_errors`
+ * instead of `compensation_failed`.
+ */
+export async function step(name, opts) {
+    if (opts.async === true) {
+        // Pattern 2: beginAsyncStep persists `paused` + writes the outbox row
+        // and throws SagaPausedSentinel — control unwinds back through
+        // createSaga which catches the sentinel and returns the saga handle.
+        return beginAsyncStep(name, opts);
+    }
+    const cfg = requireSaga();
+    const sagaCtx = requireSagaContext("step");
+    const row = sagaCtx.row;
+    await cfg.stateStore.updateSagaStatus(row.id, { current_step: name });
+    row.current_step = name;
+    // Idempotency-key payload — narrow + alphabetically-keyed JSON to be
+    // byte-equal with the Go (stepKeyPayload struct) and Python
+    // (json.dumps(..., sort_keys=True)) ports. Spec § 5.4: the cache key
+    // is sha256(saga_id + step_name + serialized_input) and parity-fence
+    // requires the three languages produce the same hash.
+    let serializedInput;
+    try {
+        const payload = {
+            name,
+            persist_fields: [...(opts.persistFields ?? [])].sort(),
+        };
+        if (opts.input !== undefined)
+            payload.input = opts.input;
+        // Stable key order: input < name < persist_fields (alphabetical).
+        serializedInput = JSON.stringify(payload, [
+            "input",
+            "name",
+            "persist_fields",
+        ]);
+    }
+    catch {
+        serializedInput = `${name}::nonserializable::${row.id}`;
+    }
+    const handler = opts.do;
+    let result;
+    try {
+        result = await cfg.idempotency.wrapForSagaStep({
+            sagaId: row.id,
+            stepName: name,
+            serializedInput: opts.idempotencyKey ?? serializedInput,
+            handler,
+        });
+    }
+    catch (err) {
+        // Surface the store-write failure alongside the step failure —
+        // matches Go's errors.Join + Python's logger.warn-then-raise.
+        // Silently swallowing it would lose visibility into transient
+        // production-store errors.
+        try {
+            await cfg.stateStore.updateSagaStatus(row.id, {
+                failure_reason: err instanceof Error ? err.message : String(err),
+                failure_step: name,
+            });
+        }
+        catch (updErr) {
+            cfg.logger?.warn?.("updateSagaStatus failed while recording step failure", {
+                saga_id: row.id,
+                step: name,
+                error: updErr instanceof Error ? updErr.message : String(updErr),
+            });
+        }
+        throw new SagaStepFailed(name, err);
+    }
+    // Persist the output + push the undo record (when undo provided).
+    await cfg.stateStore.appendStepOutput(row.id, name, result);
+    row.step_outputs[name] = result;
+    sagaCtx.completedSteps.push({ name, output: result });
+    if (opts.undo) {
+        const { fn: undoFn, mode } = normalizeUndo(opts.undo, opts.mode);
+        pushUndo(row.id, {
+            stepName: name,
+            output: result,
+            fn: undoFn,
+            mode,
+        });
+    }
+    else {
+        // Even when there's no undo, record an entry so compensation walks can
+        // log "skipped_no_undo" — keeps the compensation_log shape consistent.
+        pushUndo(row.id, {
+            stepName: name,
+            output: result,
+            fn: async () => {
+                /* no-op; logged as skipped_no_undo */
+            },
+            mode: opts.mode === "best-effort" ? "best-effort" : "strict",
+        });
+    }
+    return result;
+}
+function normalizeUndo(undo, stepMode) {
+    if (typeof undo === "function") {
+        return {
+            fn: undo,
+            mode: stepMode === "best-effort" ? "best-effort" : "strict",
+        };
+    }
+    return { fn: undo.fn, mode: undo.mode };
+}
+/**
+ * § 5.2 — stepParallel. Fans out concurrently; collects results into an array.
+ *
+ * Compensation semantics match `step` — undos are pushed onto the stack in
+ * the order they completed, so reverse-order traversal is preserved.
+ */
+export async function stepParallel(steps) {
+    return Promise.all(steps.map((s) => step(s.name, s.opts)));
+}
+async function runCompensation(sagaId, failedStep) {
+    const cfg = requireSaga();
+    await cfg.stateStore.updateSagaStatus(sagaId, {
+        status: "compensating",
+        failure_step: failedStep,
+    });
+    await emitAuditEvent("saga_compensation_started", sagaId, {
+        failed_step: failedStep,
+    });
+    const stack = takeUndoStack(sagaId).reverse();
+    let hadLenientError = false;
+    for (const entry of stack) {
+        if (entry.stepName === failedStep) {
+            // The failing step never produced a checkpoint we trust, so we skip
+            // its undo. compensation_log records skipped_no_undo for visibility.
+            const skipEntry = {
+                step_name: entry.stepName,
+                outcome: "skipped_no_undo",
+                ts: nowIso(),
+            };
+            await cfg.stateStore.appendCompensationLog(sagaId, skipEntry);
+            continue;
+        }
+        try {
+            await entry.fn(entry.output);
+            const okEntry = {
+                step_name: entry.stepName,
+                outcome: "undone",
+                ts: nowIso(),
+            };
+            await cfg.stateStore.appendCompensationLog(sagaId, okEntry);
+        }
+        catch (undoErr) {
+            const failEntry = {
+                step_name: entry.stepName,
+                outcome: "undo_failed",
+                error: undoErr instanceof Error ? undoErr.message : String(undoErr),
+                ts: nowIso(),
+            };
+            await cfg.stateStore.appendCompensationLog(sagaId, failEntry);
+            if (entry.mode === "strict") {
+                await cfg.stateStore.updateSagaStatus(sagaId, {
+                    status: "compensation_failed",
+                });
+                await emitAuditEvent("saga_compensation_failed", sagaId, {
+                    step: entry.stepName,
+                    error: failEntry.error,
+                });
+                throw new SagaCompensationFailed(entry.stepName, undoErr);
+            }
+            hadLenientError = true;
+        }
+    }
+    const terminal = hadLenientError ? "compensated_with_errors" : "compensated";
+    await cfg.stateStore.updateSagaStatus(sagaId, { status: terminal });
+    if (hadLenientError) {
+        await emitAuditEvent("saga_compensation_completed", sagaId, {
+            outcome: "compensated_with_errors",
+        });
+    }
+    else {
+        await emitAuditEvent("saga_compensation_completed", sagaId);
+    }
+}
+async function cancelSaga(sagaId, reason) {
+    const cfg = requireSaga();
+    await cfg.stateStore.updateSagaStatus(sagaId, {
+        status: "cancelled",
+        cancel_reason: reason,
+        completed_at: nowIso(),
+    });
+    if (cfg.telemetryAudit) {
+        await cfg.telemetryAudit.emit({
+            action: "saga_admin_cancel",
+            target_kind: "saga",
+            target_id: sagaId,
+            payload: { reason },
+        });
+    }
+    undoStacks.delete(sagaId);
+}
+/** Public cancel entry-point (also reachable via handle.cancel). */
+export async function cancel(sagaId, reason) {
+    await cancelSaga(sagaId, reason);
+}
+/** Read-only accessor for the active saga handle in scope. */
+export function currentSaga() {
+    return getSagaContext()?.handle ?? null;
+}
+//# sourceMappingURL=saga.js.map

package/dist/saga.js.map

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

package/dist/signal-bus/index.d.ts

@@ -0,0 +1,2 @@
+export { RedisSignalBus, type RedisSignalBusOpts } from "./redis-stream";
+//# sourceMappingURL=index.d.ts.map

package/dist/signal-bus/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/signal-bus/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,cAAc,EAAE,KAAK,kBAAkB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/signal-bus/index.js

@@ -0,0 +1,6 @@
+// Production-bound signal-bus exports.
+//
+// `RedisSignalBus` is the only signal bus production code should use.
+// For tests, see `@nodii/saga/test-doubles`.
+export { RedisSignalBus } from "./redis-stream";
+//# sourceMappingURL=index.js.map

package/dist/signal-bus/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/signal-bus/index.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,EAAE;AACF,sEAAsE;AACtE,6CAA6C;AAE7C,OAAO,EAAE,cAAc,EAA2B,MAAM,gBAAgB,CAAC"}

package/dist/signal-bus/redis-stream.d.ts

@@ -0,0 +1,43 @@
+import type { Redis } from "ioredis";
+import type { SagaSignalBus } from "../types";
+export interface RedisSignalBusOpts {
+    redis: Redis;
+    serviceId: string;
+    /** Override the stream name; defaults to nodii:<serviceId>:saga:signals. */
+    streamName?: string;
+    /** XREADGROUP block window in ms (default 50). */
+    blockMs?: number;
+}
+export declare class RedisSignalBus implements SagaSignalBus {
+    private readonly redis;
+    private readonly stream;
+    private readonly blockMs;
+    private readonly groupsEnsured;
+    constructor(opts: RedisSignalBusOpts);
+    emit(args: {
+        sagaId: string;
+        eventType: string;
+        payload: unknown;
+        scope?: "siblings" | "global";
+        to?: string;
+    }): Promise<void>;
+    consume(args: {
+        sagaId: string;
+        eventType: string;
+        from?: string;
+        predicate?: (payload: unknown) => boolean;
+    }): Promise<unknown | null>;
+    list(args: {
+        sagaId: string;
+        eventType?: string;
+    }): Promise<{
+        sagaId: string;
+        eventType: string;
+        payload: unknown;
+    }[]>;
+    /** Test helper — drop the stream + reset ensure cache. */
+    resetForTests(): Promise<void>;
+    close(): Promise<void>;
+    private ensureGroup;
+}
+//# sourceMappingURL=redis-stream.d.ts.map

package/dist/signal-bus/redis-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-stream.d.ts","sourceRoot":"","sources":["../../src/signal-bus/redis-stream.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9C,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,KAAK,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAWD,qBAAa,cAAe,YAAW,aAAa;IAClD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAIjC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqB;gBAEvC,IAAI,EAAE,kBAAkB;IAM9B,IAAI,CAAC,IAAI,EAAE;QACf,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,OAAO,CAAC;QACjB,KAAK,CAAC,EAAE,UAAU,GAAG,QAAQ,CAAC;QAC9B,EAAE,CAAC,EAAE,MAAM,CAAC;KACb,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBX,OAAO,CAAC,IAAI,EAAE;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC;KAC3C,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAwDrB,IAAI,CAAC,IAAI,EAAE;QACf,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;IAyBtE,0DAA0D;IACpD,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAS9B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAId,WAAW;CAa1B"}