@haibun/core 4.0.0-alpha.2 → 4.0.0-alpha.3

package/build/lib/execution.d.ts

@@ -0,0 +1,304 @@
+/**
+ * Execution — how the haibun runtime drives features, scenarios, and steps.
+ *
+ * Answers "what is the world at runtime, how are features structured, and what is a stepper's lifecycle?"
+ * Pure type declarations — browser-safe. All runtime behavior lives in the phases/* and lib/core/*
+ * implementations; this file only holds the shapes those implementations use.
+ *
+ * Contents:
+ *   - World/runtime: TWorld, TRuntime, options
+ *   - Features: TFeature, TFeatureStep, TResolvedFeature, source locations
+ *   - Steppers: CStepper, IStepperCycles, IStepperWhen, IStepperConcerns, TStepperStep
+ *   - Lifecycle args: TStartFeature, TEndFeature, TBeforeStep, TAfterStep, …
+ *   - CycleWhen: ordering hints for cycle execution
+ *   - IObservationSource, IRouteRegistry: runtime-plug interfaces
+ *
+ * Resource vocabulary (topology, rels, access, etc.) lives in resources.ts — import from there.
+ */
+import type { z } from "zod";
+import type { AStepper } from "./astepper.js";
+import type { TAnyFixme } from "./fixme.js";
+import type { TTag } from "./ttag.js";
+import type { FeatureVariables } from "./feature-variables.js";
+import type { Prompter } from "./prompter.js";
+import type { IEventLogger } from "./EventLogger.js";
+import type { ExecutionIntent, TSeqPath, TStepResult, TFeatureResult, TExecutorResult, TStepArgs, TStepValue, Timer, THaibunEvent, TActionResult } from "../schema/protocol.js";
+import { CONTINUE_AFTER_ERROR } from "../schema/protocol.js";
+import type { TDomainDefinition, TRegisteredDomain } from "./resources.js";
+export type TWorld = {
+    tag: TTag;
+    shared: FeatureVariables;
+    runtime: TRuntime;
+    prompter: Prompter;
+    options: TBaseOptions;
+    moduleOptions: TModuleOptions;
+    timer: Timer;
+    bases: TBase;
+    domains: Record<string, TRegisteredDomain>;
+    eventLogger: IEventLogger;
+};
+export type TRuntime = {
+    backgrounds?: TFeature[];
+    scenario?: string;
+    feature?: string;
+    /** Current feature file path (for dynamic statement execution) */
+    currentFeaturePath?: string;
+    stepResults: TStepResult[];
+    /** Active steppers for this execution. Set by Executor, used by populateActionArgs / domain coercion. */
+    steppers?: AStepper[];
+    /** Shared step registry. Set by Executor, used for dynamic step registration. */
+    stepRegistry?: import("./step-dispatch.js").StepRegistry;
+    /** Generic storage for observation data, cleared between features */
+    observations: Map<string, TAnyFixme>;
+    /** If non-empty, execution was aborted due to exhaustion (description explains why). */
+    exhaustionError?: string;
+    /**
+     * Monotonic counter for synthetic seqPaths produced by external-protocol
+     * entry points (MCP) that have no caller seqPath to thread. See
+     * `syntheticSeqPath(hostId, adHocSeq)` in host-id.ts — synthetic paths
+     * are [hostId, SYNTHETIC_FEATURE_NUM, adHocSeq] so they sort distinctly
+     * from any feature path. Internal dispatches (RPC, subprocess) now
+     * require the caller's seqPath instead of producing a synthetic.
+     */
+    adHocSeq?: number;
+    [name: string]: TAnyFixme;
+};
+export type TBaseOptions = {
+    DEST: string;
+    KEY?: string;
+    DESCRIPTION?: string;
+    LOG_LEVEL?: string;
+    LOG_FOLLOW?: string;
+    STAY?: string;
+    SETTING?: string;
+    STEP_DELAY?: number;
+    [CONTINUE_AFTER_ERROR]?: boolean;
+    envVariables?: TEnvVariables;
+};
+export type TEnvVariables = {
+    [name: string]: string;
+};
+export type TModuleOptions = {
+    [name: string]: string;
+};
+export type TProtoOptions = {
+    options: TBaseOptions;
+    moduleOptions: TModuleOptions;
+};
+export type TBase = string[];
+export declare const RemoteStepperSchema: z.ZodObject<{
+    remote: z.ZodString;
+    token: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type TRemoteStepper = z.infer<typeof RemoteStepperSchema>;
+export declare const StepperEntrySchema: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    remote: z.ZodString;
+    token: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>]>;
+export type TStepperEntry = z.infer<typeof StepperEntrySchema>;
+export declare const SpeclSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    steppers: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        remote: z.ZodString;
+        token: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>]>>;
+    runPolicy: z.ZodOptional<z.ZodString>;
+    appParameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$loose>;
+export type TSpecl = z.infer<typeof SpeclSchema>;
+export type TFeatureMeta = {
+    base: string;
+    name: string;
+    path: string;
+};
+export type TFeature = TFeatureMeta & {
+    content: string;
+    /** For kireji files: maps BDD line number (1-indexed) to TypeScript step index (0-indexed) */
+    kirejiLineMap?: Map<number, number>;
+};
+export type TFeatures = TFeature[];
+export type TExpandedFeature = TFeatureMeta & {
+    expanded: TExpandedLine[];
+};
+export type TExpandedLine = {
+    line: string;
+    rawLine?: string;
+    lineNumber?: number;
+    feature: TFeature;
+};
+export interface TSourceLocation {
+    source: {
+        /** Absolute path to the source file */
+        path: string;
+        /** 1-indexed line number in the source file */
+        lineNumber?: number;
+    };
+}
+/** A statement with its source location */
+export type TStepInput = TSourceLocation & {
+    in: string;
+};
+export type TResolvedFeature = {
+    path: string;
+    base: string;
+    name: string;
+    featureSteps: TFeatureStep[];
+};
+export type TFeatureStep = TSourceLocation & {
+    in: string;
+    seqPath: TSeqPath;
+    action: TStepAction;
+    isSubStep?: boolean;
+    /** True if this step was triggered by an afterEvery hook (prevents recursive afterEvery) */
+    isAfterEveryStep?: boolean;
+    intent?: ExecutionIntent;
+    /** Runtime args for variable binding in nested quantifier calls */
+    runtimeArgs?: Record<string, string>;
+    /**
+     * Routing hint: when set, dispatch resolves the tool via the
+     * hostId-prefixed registry key (`${targetHostId}:${method}`) — the
+     * step runs against that remote host. Set by composition verbs like
+     * `on host {hostId} {statement}` in haibun.ts.
+     */
+    targetHostId?: number;
+};
+export type TStepAction = {
+    actionName: string;
+    stepperName: string;
+    step: TStepperStep;
+    stepValuesMap?: TStepValuesMap;
+};
+export type TStepValuesMap = Record<string, TStepValue>;
+type TStepperStepBase = {
+    handlesUndefined?: true | string[];
+    description?: string;
+    precludes?: string[];
+    unique?: boolean;
+    fallback?: boolean;
+    exposeMCP?: boolean;
+    /** Optional capability label required for external dispatch. */
+    capability?: string;
+    virtual?: boolean;
+    /** For dynamically generated steps (like waypoints): source location metadata */
+    source?: {
+        path: string;
+        lineNumber?: number;
+    };
+    match?: RegExp;
+    gwta?: string;
+    exact?: string;
+    resolveFeatureLine?(line: string, path: string, stepper: AStepper, backgrounds: TFeatures, allLines?: string[], lineIndex?: number, actualSourcePath?: string): boolean | void;
+};
+/** Step that declares an output schema — action MUST return products on success. */
+type TStepperStepWithProducts = TStepperStepBase & {
+    outputSchema: z.ZodType;
+    action(args: TStepArgs, featureStep?: TFeatureStep): Promise<TActionResult> | TActionResult;
+};
+/** Step without output schema — no products on success. */
+type TStepperStepPlain = TStepperStepBase & {
+    outputSchema?: undefined;
+    action(args: TStepArgs, featureStep?: TFeatureStep): Promise<TActionResult> | TActionResult;
+};
+export type TStepperStep = TStepperStepWithProducts | TStepperStepPlain;
+export interface CStepper {
+    new (): AStepper;
+}
+export interface IStepperWhen {
+    startExecution?: number;
+    startFeature?: number;
+    endFeature?: number;
+}
+export declare const CycleWhen: {
+    FIRST: number;
+    LAST: number;
+};
+/**
+ * Observation source for the 'observed in' quantifier pattern.
+ * Provides ephemeral iteration over runtime metrics.
+ */
+export interface IObservationSource {
+    name: string;
+    observe(world: TWorld): {
+        items: string[];
+        metrics: Record<string, Record<string, unknown>>;
+    };
+}
+export interface IStepperConcerns {
+    domains?: TDomainDefinition[];
+    sources?: IObservationSource[];
+    quadStore?: {
+        store: import("./quad-types.js").IQuadStore;
+        namedGraphs: string[];
+    };
+}
+export interface IStepperCycles {
+    getConcerns?(): IStepperConcerns;
+    /** Return registered outcome definitions for artifact emission. Used by ActivitiesStepper. */
+    getRegisteredOutcomes?(): Record<string, unknown>;
+    startExecution?(features: TStartExecution): Promise<void> | void;
+    startFeature?(startFeature: TStartFeature): Promise<void> | void;
+    startScenario?(startScenario: TStartScenario): Promise<void>;
+    beforeStep?(beforeStep: TBeforeStep): Promise<void>;
+    afterStep?(afterStep: TAfterStep): Promise<TAfterStepResult>;
+    endScenario?(): Promise<void>;
+    endFeature?(endedWith?: TEndFeature): Promise<void>;
+    onFailure?(result: TFailureArgs): Promise<void>;
+    endExecution?(results: TExecutorResult): Promise<void>;
+    onEvent?(event: THaibunEvent): Promise<void> | void;
+}
+export type TStartExecution = TResolvedFeature[];
+export type TEndFeature = {
+    featurePath: string;
+    shouldClose: boolean;
+    isLast: boolean;
+    okSoFar: boolean;
+    continueAfterError: boolean;
+    stayOnFailure: boolean;
+    thisFeatureOK: boolean;
+};
+export type TStartFeature = {
+    resolvedFeature: TResolvedFeature;
+    index: number;
+};
+export type TStartScenario = {
+    scopedVars: FeatureVariables;
+};
+export type TBeforeStep = {
+    featureStep: TFeatureStep;
+};
+export type TAfterStep = {
+    featureStep: TFeatureStep;
+    actionResult: TActionResult;
+};
+export type TFailureArgs = {
+    featureResult: TFeatureResult;
+    failedStep: TStepResult;
+};
+export type TAfterStepResult = {
+    rerunStep?: boolean;
+    nextStep?: boolean;
+    failed: boolean;
+};
+export type StepperMethodArgs = {
+    [K in keyof IStepperCycles]: Parameters<NonNullable<IStepperCycles[K]>>[0];
+};
+/** A vertex returned from graph operations, with routing metadata. */
+export type TVertexResult = Record<string, unknown> & {
+    _id: string;
+    _label?: string;
+    _inReplyTo?: string;
+    _edges?: Array<{
+        type: string;
+        targetId: string;
+    }>;
+};
+/** Minimal route registry interface — implemented by IWebServer, consumed by http-observations. */
+export interface IRouteRegistry {
+    readonly mounted: Record<string, Record<string, string>>;
+}
+/** Extract all registered route paths from a route registry. */
+export declare function registeredPaths(registry: IRouteRegistry): Set<string>;
+export type TOptionValue = TAnyFixme;
+export {};
+//# sourceMappingURL=execution.d.ts.map

package/build/lib/execution.d.ts.map

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

package/build/lib/execution.js

@@ -0,0 +1,23 @@
+import { z as zr } from "zod";
+import { CONTINUE_AFTER_ERROR } from "../schema/protocol.js";
+// ============================================================================
+// Specl (runtime config file)
+// ============================================================================
+export const RemoteStepperSchema = zr.object({ remote: zr.string(), token: zr.string().optional() });
+export const StepperEntrySchema = zr.union([zr.string(), RemoteStepperSchema]);
+export const SpeclSchema = zr.looseObject({
+    $schema: zr.string().optional(),
+    steppers: zr.array(StepperEntrySchema),
+    runPolicy: zr.string().optional(),
+    appParameters: zr.record(zr.string(), zr.record(zr.string(), zr.unknown())).optional(),
+    options: zr.record(zr.string(), zr.unknown()).optional(),
+});
+export const CycleWhen = {
+    FIRST: -999,
+    LAST: 999,
+};
+/** Extract all registered route paths from a route registry. */
+export function registeredPaths(registry) {
+    return new Set(Object.values(registry.mounted).flatMap((m) => Object.keys(m)));
+}
+//# sourceMappingURL=execution.js.map

package/build/lib/execution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution.js","sourceRoot":"","sources":["../../src/lib/execution.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,MAAM,KAAK,CAAC;AAS9B,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AA0E7D,+EAA+E;AAC/E,8BAA8B;AAC9B,+EAA+E;AAE/E,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;AAGrG,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,mBAAmB,CAAC,CAAC,CAAC;AAG/E,MAAM,CAAC,MAAM,WAAW,GAAG,EAAE,CAAC,WAAW,CAAC;IACzC,OAAO,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,QAAQ,EAAE,EAAE,CAAC,KAAK,CAAC,kBAAkB,CAAC;IACtC,SAAS,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACjC,aAAa,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE;IACtF,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;CACxD,CAAC,CAAC;AA+IH,MAAM,CAAC,MAAM,SAAS,GAAG;IACxB,KAAK,EAAE,CAAC,GAAG;IACX,IAAI,EAAE,GAAG;CACT,CAAC;AAkFF,gEAAgE;AAChE,MAAM,UAAU,eAAe,CAAC,QAAwB;IACvD,OAAO,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAChF,CAAC"}

package/build/lib/feature-variables.d.ts

@@ -1,77 +1,48 @@
 import { AStepper } from "./astepper.js";
-import { TFeatureStep, TWorld } from './defs.js';
-import { TOrigin, TProvenanceIdentifier, TStepValue } from '../schema/protocol.js';
+import { TFeatureStep, TWorld } from "./execution.js";
+import { TOrigin, TProvenanceIdentifier, TStepValue } from "../schema/protocol.js";
 import { IQuadStore, TQuad } from "./quad-types.js";
 export declare const SHARED_GRAPH = "variables";
-export declare const META_GRAPH = "meta";
 export declare const OBSERVATION_GRAPH = "observation";
 export declare const OBSCURED_VALUE = "[o\u0334b\u0335s\u0335c\u0337u\u0336r\u0338e\u0335d\u0335]";
 export declare class FeatureVariables {
     private world;
     private store;
-    private values;
     constructor(world: TWorld, initial?: {
         [name: string]: TStepValue;
     });
     getStore(): IQuadStore;
-    clear(): void;
-    all(): {
+    all(): Promise<{
         [name: string]: TStepValue;
-    };
+    }>;
     toString(): string;
-    setJSON(label: string, value: object, origin: TOrigin, source: TFeatureStep): void;
-    setForStepper(stepper: string, sv: TStepValue, provenance: TProvenanceIdentifier, namedGraph?: string): void;
-    unset(name: string): void;
-    set(sv: TStepValue, provenance: TProvenanceIdentifier, namedGraph?: string): void;
-    _set(sv: TStepValue, provenance: TProvenanceIdentifier, namedGraph?: string): void;
-    /**
-     * Resolves a variable and its domain based on its actual origin.
-     * Requires explicit options.secure to return the real value of a secret.
-     */
+    setJSON(label: string, value: object, origin: TOrigin, source: TFeatureStep): Promise<void>;
+    setForStepper(stepper: string, sv: TStepValue, provenance: TProvenanceIdentifier, namedGraph?: string): Promise<void>;
+    unset(name: string): Promise<void>;
+    set(sv: TStepValue, provenance: TProvenanceIdentifier, namedGraph?: string): Promise<void>;
+    _set(sv: TStepValue, provenance: TProvenanceIdentifier, namedGraph?: string): Promise<void>;
+    /** Look up a variable from store or dot-path. Shared by Origin.var, Origin.defined, Origin.quoted. */
+    private lookupVariable;
     resolveVariable(input: {
         term: string;
         origin: TOrigin;
         domain?: string;
     }, featureStep?: TFeatureStep, steppers?: AStepper[], options?: {
         secure: boolean;
-    }): TStepValue;
-    /** Try dot-path navigation into a stored structured value. */
+    }): Promise<TStepValue>;
+    /** Reconstruct a stored variable entry from the quad's properties. */
+    private getStoredEntry;
     private resolveDotPath;
-    getDomainValues(domainName: string): {
+    getDomainValues(domainName: string): Promise<{
         values: unknown[];
         error?: string;
-    };
-    get(term: string, secure?: boolean): unknown;
-    queryQuads(pattern: {
-        subject?: string;
-        predicate?: string;
-        object?: unknown;
-        namedGraph?: string;
-    }): TQuad[];
-    existsQuad(pattern: {
-        subject?: string;
-        predicate?: string;
-        object?: unknown;
-        namedGraph?: string;
-    }): boolean;
-    countQuads(pattern: {
-        subject?: string;
-        predicate?: string;
-        object?: unknown;
-        namedGraph?: string;
-    }): number;
-    addQuad(quad: Omit<TQuad, 'timestamp'>): void;
-    removeQuad(pattern: {
-        subject?: string;
-        predicate?: string;
-        object?: unknown;
-        namedGraph?: string;
-    }): void;
-    allQuads(): TQuad[];
+    }>;
+    get(term: string, secure?: boolean): Promise<unknown>;
+    allQuads(): Promise<TQuad[]>;
     isSecret(name: string): boolean;
-    getSecrets(): {
+    getSecrets(): Promise<{
         [name: string]: string;
-    };
-    private storeAsQuad;
+    }>;
+    private writeQuads;
 }
 //# sourceMappingURL=feature-variables.d.ts.map

package/build/lib/feature-variables.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"feature-variables.d.ts","sourceRoot":"","sources":["../../src/lib/feature-variables.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"feature-variables.d.ts","sourceRoot":"","sources":["../../src/lib/feature-variables.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGzC,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAU,OAAO,EAAE,qBAAqB,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAG3F,OAAO,EAAE,UAAU,EAAE,KAAK,EAAuB,MAAM,iBAAiB,CAAC;AAEzE,eAAO,MAAM,YAAY,cAAc,CAAC;AACxC,eAAO,MAAM,iBAAiB,gBAAgB,CAAC;AAC/C,eAAO,MAAM,cAAc,+DAAuB,CAAC;AAEnD,qBAAa,gBAAgB;IAI3B,OAAO,CAAC,KAAK;IAHd,OAAO,CAAC,KAAK,CAAa;gBAGjB,KAAK,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE;QAAE,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAA;KAAE;IAczC,QAAQ,IAAI,UAAU;IAIhB,GAAG,IAAI,OAAO,CAAC;QAAE,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAA;KAAE,CAAC;IAepD,QAAQ;IAIF,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY;IAO3E,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,UAAU,EAAE,UAAU,EAAE,qBAAqB,EAAE,UAAU,CAAC,EAAE,MAAM;IAIrG,KAAK,CAAC,IAAI,EAAE,MAAM;IAIlB,GAAG,CAAC,EAAE,EAAE,UAAU,EAAE,UAAU,EAAE,qBAAqB,EAAE,UAAU,CAAC,EAAE,MAAM;IAQ1E,IAAI,CAAC,EAAE,EAAE,UAAU,EAAE,UAAU,EAAE,qBAAqB,EAAE,UAAU,GAAE,MAAqB;IAY/F,sGAAsG;YACxF,cAAc;IAUtB,eAAe,CACpB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,EACzD,WAAW,CAAC,EAAE,YAAY,EAC1B,QAAQ,CAAC,EAAE,QAAQ,EAAE,EACrB,OAAO,GAAE;QAAE,MAAM,EAAE,OAAO,CAAA;KAAsB,GAC9C,OAAO,CAAC,UAAU,CAAC;IAyEtB,sEAAsE;YACxD,cAAc;YAed,cAAc;IAiBtB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,OAAO,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAYnF,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,OAAe;IAIzC,QAAQ,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;IAIlC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIzB,UAAU,IAAI,OAAO,CAAC;QAAE,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;YAazC,UAAU;CAkBxB"}