@honua/app-platform 0.0.20-alpha.0

package/operator/controllers/map-workspace.js

@@ -0,0 +1,296 @@
+/**
+ * `MapWorkspaceController` — orchestrates the `HonuaMapRuntime` and the
+ * `ExplorationContext` for a single result `MapPackage`. The controller
+ * owns no MapLibre source/style code of its own — every map mutation
+ * delegates to the runtime from `src/runtime/`.
+ *
+ * @module
+ */
+import { createExplorationContext, } from "../../exploration/index.js";
+import { loadMapPackage, } from "../../runtime/index.js";
+import { HonuaOperatorMapError } from "../errors.js";
+import { ListenerBag, withTelemetrySpan } from "./base.js";
+const MAP_VIEW_BINDING_ID = "map-primary";
+export class MapWorkspaceController {
+    #client;
+    #mapFactory;
+    #preset;
+    #telemetry;
+    #loadOptions;
+    #bag = new ListenerBag();
+    #runtime;
+    #context;
+    #viewHandle;
+    #disposeMap;
+    #activeIntentId;
+    // Bumped on every loadPackage() / refine() / dispose() entry. The
+    // operation captures it before awaiting and only commits state when
+    // the captured value still matches at resolution time. Parallel
+    // loads or refinements thereby cannot let an older `MapPackage`
+    // overwrite a newer one.
+    #opGeneration = 0;
+    constructor(options) {
+        this.#client = options.client;
+        this.#mapFactory = options.mapFactory;
+        this.#preset = options.explorationPreset ?? "mapDriven";
+        this.#telemetry = options.telemetry;
+        this.#loadOptions = options.loadOptions;
+    }
+    get runtime() {
+        return this.#runtime;
+    }
+    get exploration() {
+        return this.#context;
+    }
+    on(listener) {
+        return this.#bag.on(listener);
+    }
+    /**
+     * Bind the controller to an intent so that subsequent `refine()` calls
+     * have an intent id to attach to the server request. Idempotent.
+     */
+    bindIntent(intentId) {
+        this.#activeIntentId = intentId;
+    }
+    /**
+     * Load a `MapPackage` into a fresh runtime + exploration context.
+     * Tears down any previously loaded package; safe to call repeatedly.
+     *
+     * Concurrent loads supersede each other via `#opGeneration`: an
+     * older load whose factory or `loadMapPackage` is still pending when
+     * a newer load arrives discards its locally-built runtime/context
+     * instead of overwriting the newer state.
+     */
+    async loadPackage(pkg) {
+        if (!this.#loadOptions) {
+            throw new HonuaOperatorMapError("loadPackage requires loadOptions on the controller", {
+                detail: { mapPackageId: pkg.mapPackageId },
+            });
+        }
+        this.#tearDown();
+        const gen = ++this.#opGeneration;
+        return withTelemetrySpan(this.#telemetry, "map-load", this.#activeIntentId, async () => {
+            let factoryResult;
+            let runtime;
+            try {
+                // The host-supplied factory can reject before any runtime
+                // setup happens (e.g. WebGL unavailable). Keep its failure
+                // inside the wrapper so embedders see a typed
+                // HonuaOperatorMapError on the workspace event stream
+                // instead of a raw factory rejection.
+                factoryResult = await this.#mapFactory();
+                if (gen !== this.#opGeneration) {
+                    disposeFactoryResult(factoryResult);
+                    throw new HonuaOperatorMapError("map load superseded by newer load", {
+                        detail: { mapPackageId: pkg.mapPackageId },
+                    });
+                }
+                runtime = await loadMapPackage(pkg, factoryResult.map, {
+                    ...this.#loadOptions,
+                });
+                if (gen !== this.#opGeneration) {
+                    disposeRuntime(runtime);
+                    disposeFactoryResult(factoryResult);
+                    throw new HonuaOperatorMapError("map load superseded by newer load", {
+                        detail: { mapPackageId: pkg.mapPackageId },
+                    });
+                }
+                this.#disposeMap = factoryResult.dispose;
+                this.#runtime = runtime;
+                this.#context = createExplorationContext({
+                    datasetId: pkg.mapPackageId,
+                    sourceIds: pkg.sourceBindings.map((binding) => binding.sourceId),
+                    preset: this.#preset,
+                });
+                this.#viewHandle = this.#context.bind({ id: MAP_VIEW_BINDING_ID, role: "map" });
+                this.#bag.emit({ kind: "package-loaded", pkg });
+                return runtime;
+            }
+            catch (error) {
+                if (gen !== this.#opGeneration) {
+                    // Superseded; the newer load owns teardown. Don't re-tear or emit.
+                    throw error;
+                }
+                // `#disposeMap` is only assigned after `loadMapPackage`
+                // succeeds, so a factory that returned a host map followed
+                // by a `loadMapPackage` failure leaves the map orphaned.
+                // Dispose the locally-captured factoryResult / runtime here
+                // before #tearDown runs (it will be a no-op for those).
+                if (runtime !== undefined)
+                    disposeRuntime(runtime);
+                if (factoryResult !== undefined && this.#disposeMap === undefined) {
+                    disposeFactoryResult(factoryResult);
+                }
+                this.#tearDown();
+                const wrapped = error instanceof HonuaOperatorMapError
+                    ? error
+                    : new HonuaOperatorMapError("map package load failed", {
+                        cause: error,
+                        detail: { mapPackageId: pkg.mapPackageId },
+                    });
+                this.#bag.emit({ kind: "error", error: wrapped });
+                throw wrapped;
+            }
+        }, { mapPackageId: pkg.mapPackageId });
+    }
+    /**
+     * Natural-language refinement. The server returns an updated
+     * `MapPackage`; the runtime's diff path applies it incrementally.
+     * Source-binding failures inside the runtime are forwarded via
+     * `runtime.reportSourceError(...)` rather than thrown.
+     */
+    async refine(prompt, signal) {
+        if (!this.#runtime) {
+            throw new HonuaOperatorMapError("refine called before loadPackage");
+        }
+        if (!this.#activeIntentId) {
+            throw new HonuaOperatorMapError("refine requires bindIntent before invocation");
+        }
+        const intentId = this.#activeIntentId;
+        const ownRuntime = this.#runtime;
+        const gen = ++this.#opGeneration;
+        return withTelemetrySpan(this.#telemetry, "map-refine", intentId, async () => {
+            try {
+                const next = await this.#client.operator.refineMap(intentId, prompt, signal);
+                if (gen !== this.#opGeneration || this.#runtime !== ownRuntime) {
+                    // Superseded by a newer load/refine, or the runtime was
+                    // torn down while we awaited. Skip the apply so we never
+                    // mutate a stale or replaced runtime.
+                    return next;
+                }
+                await ownRuntime.updatePackage(next);
+                if (gen !== this.#opGeneration || this.#runtime !== ownRuntime) {
+                    return next;
+                }
+                this.#syncExplorationContext(next);
+                this.#bag.emit({ kind: "package-refined", pkg: next });
+                return next;
+            }
+            catch (error) {
+                if (gen !== this.#opGeneration || this.#runtime !== ownRuntime) {
+                    // Superseded; let the newer op own error reporting.
+                    throw error;
+                }
+                const wrapped = new HonuaOperatorMapError("map refine failed", {
+                    intentId,
+                    cause: error,
+                    detail: { prompt },
+                });
+                this.#bag.emit({ kind: "error", error: wrapped });
+                // Forward any per-source recoveries to the runtime so
+                // listeners on the runtime see the failure on the same
+                // channel as native source events.
+                ownRuntime.reportSourceError("__refine__", error);
+                throw wrapped;
+            }
+        }, { prompt });
+    }
+    // ── Thin re-exports of HonuaMapRuntime ops ───────────────────
+    setLayerVisibility(layerId, visible) {
+        this.#assertRuntime().setLayerVisibility(layerId, visible);
+    }
+    bindPopup(layerId, binding) {
+        return this.#assertRuntime().bindPopup(layerId, binding);
+    }
+    setViewState(view) {
+        this.#assertRuntime().setViewState(view);
+    }
+    getLegend() {
+        return this.#assertRuntime().getLegend();
+    }
+    dispose() {
+        this.#opGeneration += 1;
+        this.#tearDown();
+        this.#bag.clear();
+    }
+    #assertRuntime() {
+        if (!this.#runtime) {
+            throw new HonuaOperatorMapError("operation requires a loaded MapPackage");
+        }
+        return this.#runtime;
+    }
+    /**
+     * `ExplorationContext` exposes immutable `datasetId` / `sourceIds`,
+     * so a refined package that changes either leaves linked views bound
+     * to stale metadata. Rebuild the context (and the primary view
+     * binding) on those transitions; otherwise leave it intact so
+     * subscribers retain their current state.
+     */
+    #syncExplorationContext(pkg) {
+        const nextSourceIds = pkg.sourceBindings.map((binding) => binding.sourceId);
+        if (this.#context &&
+            this.#context.datasetId === pkg.mapPackageId &&
+            sameSourceIds(this.#context.sourceIds, nextSourceIds)) {
+            return;
+        }
+        if (this.#viewHandle) {
+            this.#viewHandle.unbind();
+            this.#viewHandle = undefined;
+        }
+        if (this.#context) {
+            this.#context.dispose();
+            this.#context = undefined;
+        }
+        this.#context = createExplorationContext({
+            datasetId: pkg.mapPackageId,
+            sourceIds: nextSourceIds,
+            preset: this.#preset,
+        });
+        this.#viewHandle = this.#context.bind({ id: MAP_VIEW_BINDING_ID, role: "map" });
+    }
+    #tearDown() {
+        if (this.#viewHandle) {
+            this.#viewHandle.unbind();
+            this.#viewHandle = undefined;
+        }
+        if (this.#context) {
+            this.#context.dispose();
+            this.#context = undefined;
+        }
+        if (this.#runtime) {
+            try {
+                this.#runtime.dispose();
+            }
+            catch {
+                // dispose is best-effort during teardown; map errors do not
+                // re-surface here because the controller already returned.
+            }
+            this.#runtime = undefined;
+            this.#bag.emit({ kind: "package-disposed" });
+        }
+        if (this.#disposeMap) {
+            try {
+                this.#disposeMap();
+            }
+            catch {
+                // ignore — host-owned teardown.
+            }
+            this.#disposeMap = undefined;
+        }
+    }
+}
+function sameSourceIds(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i += 1) {
+        if (a[i] !== b[i])
+            return false;
+    }
+    return true;
+}
+function disposeFactoryResult(factoryResult) {
+    try {
+        factoryResult.dispose?.();
+    }
+    catch {
+        // ignore — host-owned teardown.
+    }
+}
+function disposeRuntime(runtime) {
+    try {
+        runtime.dispose();
+    }
+    catch {
+        // dispose is best-effort during supersession cleanup.
+    }
+}

package/operator/controllers/plan-review.d.ts

@@ -0,0 +1,66 @@
+/**
+ * `PlanReviewController` — exposes a server-produced plan, lets the
+ * embedder accept or revise it, and emits lifecycle events the workspace
+ * relays to embedders.
+ *
+ * Plan revisions are pass-through to the server; the controller never
+ * mutates plan steps locally.
+ *
+ * @module
+ */
+import type { OperatorClient } from "../client.js";
+import { HonuaOperatorPlanError } from "../errors.js";
+import type { OperatorTelemetry } from "../telemetry.js";
+import type { OperatorPlan, PlanStep } from "../workspace/types.js";
+import { type Unsubscribe } from "./base.js";
+export type PlanRevisionRequest = {
+    readonly intentId: string;
+    readonly notes?: string;
+};
+export type PlanReviewEvent = {
+    kind: "plan-loaded";
+    plan: OperatorPlan;
+} | {
+    kind: "plan-accepted";
+    plan: OperatorPlan;
+} | {
+    kind: "plan-revising";
+    plan: OperatorPlan;
+} | {
+    kind: "plan-revised";
+    plan: OperatorPlan;
+} | {
+    kind: "error";
+    error: HonuaOperatorPlanError;
+};
+export type DecorateStep = (step: PlanStep) => PlanStep;
+export interface PlanReviewControllerOptions {
+    client: OperatorClient;
+    telemetry?: OperatorTelemetry;
+    /** Pure transformation applied to plan steps before they are emitted. */
+    decorateStep?: DecorateStep;
+}
+export declare class PlanReviewController {
+    #private;
+    constructor(options: PlanReviewControllerOptions);
+    get plan(): OperatorPlan | undefined;
+    on(listener: (event: PlanReviewEvent) => void): Unsubscribe;
+    /**
+     * Load the plan attached to an intent. Wraps transport errors in
+     * `HonuaOperatorPlanError` and emits an `error` event.
+     */
+    load(intentId: string, signal?: AbortSignal): Promise<OperatorPlan>;
+    /**
+     * Accept the loaded plan. The controller does not start execution —
+     * the workspace handles the hand-off to `ExecutionController`.
+     */
+    accept(): OperatorPlan;
+    /**
+     * Ask the server for a revised plan. The controller forwards the
+     * embedder's revision notes through `OperatorClient.revisePlan` so
+     * the server can act on them, instead of just observing them in
+     * telemetry. The controller never mutates step shape locally.
+     */
+    revise(request: PlanRevisionRequest, signal?: AbortSignal): Promise<OperatorPlan>;
+}
+//# sourceMappingURL=plan-review.d.ts.map

package/operator/controllers/plan-review.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-review.d.ts","sourceRoot":"","sources":["../../../../src/operator/controllers/plan-review.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,KAAK,EAIV,YAAY,EACZ,QAAQ,EAET,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAe,KAAK,WAAW,EAAqB,MAAM,WAAW,CAAC;AAE7E,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,YAAY,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,IAAI,EAAE,YAAY,CAAA;CAAE,GAC7C;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,IAAI,EAAE,YAAY,CAAA;CAAE,GAC7C;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,IAAI,EAAE,YAAY,CAAA;CAAE,GAC5C;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,sBAAsB,CAAA;CAAE,CAAC;AAErD,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,QAAQ,KAAK,QAAQ,CAAC;AAExD,MAAM,WAAW,2BAA2B;IAC1C,MAAM,EAAE,cAAc,CAAC;IACvB,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B,yEAAyE;IACzE,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAED,qBAAa,oBAAoB;;gBAaZ,OAAO,EAAE,2BAA2B;IAMvD,IAAW,IAAI,IAAI,YAAY,GAAG,SAAS,CAE1C;IAEM,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,GAAG,WAAW;IAIlE;;;OAGG;IACU,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;IA0BhF;;;OAGG;IACI,MAAM,IAAI,YAAY;IAS7B;;;;;OAKG;IACU,MAAM,CAAC,OAAO,EAAE,mBAAmB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;CAiD/F"}

package/operator/controllers/plan-review.js

@@ -0,0 +1,124 @@
+/**
+ * `PlanReviewController` — exposes a server-produced plan, lets the
+ * embedder accept or revise it, and emits lifecycle events the workspace
+ * relays to embedders.
+ *
+ * Plan revisions are pass-through to the server; the controller never
+ * mutates plan steps locally.
+ *
+ * @module
+ */
+import { HonuaOperatorPlanError } from "../errors.js";
+import { ListenerBag, withTelemetrySpan } from "./base.js";
+export class PlanReviewController {
+    #client;
+    #telemetry;
+    #decorateStep;
+    #bag = new ListenerBag();
+    #plan;
+    // Bumped on every load() / revise() entry. When `getPlan` /
+    // `revisePlan` resolves out of order (older intent's plan arrives
+    // after a newer intent has already triggered a load), the older
+    // resolution finds gen !== captured and is dropped without
+    // committing or emitting — accept() never executes a stale plan.
+    #generation = 0;
+    constructor(options) {
+        this.#client = options.client;
+        this.#telemetry = options.telemetry;
+        this.#decorateStep = options.decorateStep;
+    }
+    get plan() {
+        return this.#plan ? this.#decoratedPlan(this.#plan) : undefined;
+    }
+    on(listener) {
+        return this.#bag.on(listener);
+    }
+    /**
+     * Load the plan attached to an intent. Wraps transport errors in
+     * `HonuaOperatorPlanError` and emits an `error` event.
+     */
+    async load(intentId, signal) {
+        const gen = ++this.#generation;
+        try {
+            const plan = await withTelemetrySpan(this.#telemetry, "plan-load", intentId, () => this.#client.operator.getPlan(intentId, signal));
+            const decorated = this.#decoratedPlan(plan);
+            if (gen !== this.#generation) {
+                // Superseded by a newer load()/revise(); don't commit or emit.
+                return decorated;
+            }
+            this.#plan = plan;
+            this.#bag.emit({ kind: "plan-loaded", plan: decorated });
+            return decorated;
+        }
+        catch (error) {
+            const wrapped = error instanceof HonuaOperatorPlanError
+                ? error
+                : new HonuaOperatorPlanError("plan load failed", { intentId, cause: error });
+            if (gen === this.#generation) {
+                this.#bag.emit({ kind: "error", error: wrapped });
+            }
+            throw wrapped;
+        }
+    }
+    /**
+     * Accept the loaded plan. The controller does not start execution —
+     * the workspace handles the hand-off to `ExecutionController`.
+     */
+    accept() {
+        if (!this.#plan) {
+            throw new HonuaOperatorPlanError("acceptPlan called before plan load");
+        }
+        const decorated = this.#decoratedPlan(this.#plan);
+        this.#bag.emit({ kind: "plan-accepted", plan: decorated });
+        return decorated;
+    }
+    /**
+     * Ask the server for a revised plan. The controller forwards the
+     * embedder's revision notes through `OperatorClient.revisePlan` so
+     * the server can act on them, instead of just observing them in
+     * telemetry. The controller never mutates step shape locally.
+     */
+    async revise(request, signal) {
+        if (this.#plan) {
+            this.#bag.emit({ kind: "plan-revising", plan: this.#decoratedPlan(this.#plan) });
+        }
+        const gen = ++this.#generation;
+        try {
+            const next = await withTelemetrySpan(this.#telemetry, "plan-load", request.intentId, () => this.#client.operator.revisePlan(request.intentId, request.notes, signal), { revision: true, notes: request.notes });
+            const decorated = this.#decoratedPlan(next);
+            if (gen !== this.#generation) {
+                return decorated;
+            }
+            this.#plan = next;
+            this.#bag.emit({ kind: "plan-revised", plan: decorated });
+            return decorated;
+        }
+        catch (error) {
+            const wrapped = error instanceof HonuaOperatorPlanError
+                ? error
+                : new HonuaOperatorPlanError("plan revision failed", {
+                    intentId: request.intentId,
+                    cause: error,
+                });
+            if (gen === this.#generation) {
+                this.#bag.emit({ kind: "error", error: wrapped });
+            }
+            throw wrapped;
+        }
+    }
+    #decoratedPlan(plan) {
+        if (!this.#decorateStep)
+            return plan;
+        const steps = plan.steps.map((step) => this.#decorateStep(step));
+        switch (plan.kind) {
+            case "analysis":
+                return { ...plan, steps };
+            case "publishing":
+                return { ...plan, steps };
+            case "builder":
+                return { ...plan, steps };
+            case "deployment":
+                return { ...plan, steps };
+        }
+    }
+}

package/operator/errors.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Operator-stage errors. Mirrors the discriminated-union pattern from
+ * `src/core/errors.ts`: each concrete class extends `Error` directly,
+ * the `HonuaOperatorError` type is the union of those classes, and
+ * `isHonuaOperatorError()` is the narrowing type guard.
+ *
+ * The set is independent of `HonuaError` in `src/core/errors.ts`; the
+ * two coexist so that adapter-level failures and operator-level failures
+ * can be discriminated separately.
+ *
+ * @module
+ */
+export type HonuaOperatorErrorStage = "intent" | "plan" | "execution" | "approval" | "map" | "app";
+/**
+ * Failure-kind taxonomy aligned with `AI_OPERATOR_CONTRACT`. Server
+ * responses with a structured failure kind populate the controller's
+ * error verbatim; unknown values are preserved as strings.
+ */
+export type HonuaOperatorExecutionFailureKind = "ValidationFailed" | "AuthorizationDenied" | "UnknownDataset" | "UnknownProcess" | "ExecutionFailed" | "Timeout" | "Cancelled" | "OutputBindingFailed" | (string & {
+    readonly __brand?: never;
+});
+interface OperatorErrorContext {
+    intentId?: string;
+    planId?: string;
+    executionId?: string;
+    detail?: Record<string, unknown>;
+    cause?: unknown;
+}
+declare abstract class HonuaOperatorErrorBase extends Error {
+    readonly stage: HonuaOperatorErrorStage;
+    readonly intentId: string | undefined;
+    readonly planId: string | undefined;
+    readonly executionId: string | undefined;
+    readonly detail: Record<string, unknown> | undefined;
+    readonly cause: unknown;
+    protected constructor(stage: HonuaOperatorErrorStage, message: string, context?: OperatorErrorContext);
+}
+export declare class HonuaOperatorIntentError extends HonuaOperatorErrorBase {
+    constructor(message: string, context?: OperatorErrorContext);
+}
+export declare class HonuaOperatorPlanError extends HonuaOperatorErrorBase {
+    constructor(message: string, context?: OperatorErrorContext);
+}
+export declare class HonuaOperatorExecutionError extends HonuaOperatorErrorBase {
+    readonly failureKind: HonuaOperatorExecutionFailureKind | undefined;
+    constructor(message: string, context?: OperatorErrorContext & {
+        failureKind?: HonuaOperatorExecutionFailureKind;
+    });
+}
+export declare class HonuaOperatorApprovalError extends HonuaOperatorErrorBase {
+    constructor(message: string, context?: OperatorErrorContext);
+}
+export declare class HonuaOperatorMapError extends HonuaOperatorErrorBase {
+    constructor(message: string, context?: OperatorErrorContext);
+}
+export declare class HonuaOperatorAppError extends HonuaOperatorErrorBase {
+    constructor(message: string, context?: OperatorErrorContext);
+}
+export type HonuaOperatorError = HonuaOperatorIntentError | HonuaOperatorPlanError | HonuaOperatorExecutionError | HonuaOperatorApprovalError | HonuaOperatorMapError | HonuaOperatorAppError;
+export declare function isHonuaOperatorError(error: unknown): error is HonuaOperatorError;
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/operator/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/operator/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,MAAM,uBAAuB,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,UAAU,GAAG,KAAK,GAAG,KAAK,CAAC;AAEnG;;;;GAIG;AACH,MAAM,MAAM,iCAAiC,GACzC,kBAAkB,GAClB,qBAAqB,GACrB,gBAAgB,GAChB,gBAAgB,GAChB,iBAAiB,GACjB,SAAS,GACT,WAAW,GACX,qBAAqB,GACrB,CAAC,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC,CAAC;AAE5C,UAAU,oBAAoB;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,uBAAe,sBAAuB,SAAQ,KAAK;IACjD,SAAgB,KAAK,EAAE,uBAAuB,CAAC;IAC/C,SAAgB,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7C,SAAgB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,SAAgB,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChD,SAAgB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAC5D,SAAyB,KAAK,EAAE,OAAO,CAAC;IAExC,SAAS,aAAa,KAAK,EAAE,uBAAuB,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAyB;CAS1G;AAED,qBAAa,wBAAyB,SAAQ,sBAAsB;gBAC/C,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAyB;CAIvE;AAED,qBAAa,sBAAuB,SAAQ,sBAAsB;gBAC7C,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAyB;CAIvE;AAED,qBAAa,2BAA4B,SAAQ,sBAAsB;IACrE,SAAgB,WAAW,EAAE,iCAAiC,GAAG,SAAS,CAAC;gBAGzE,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAoB,GAAG;QAAE,WAAW,CAAC,EAAE,iCAAiC,CAAA;KAAO;CAM3F;AAED,qBAAa,0BAA2B,SAAQ,sBAAsB;gBACjD,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAyB;CAIvE;AAED,qBAAa,qBAAsB,SAAQ,sBAAsB;gBAC5C,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAyB;CAIvE;AAED,qBAAa,qBAAsB,SAAQ,sBAAsB;gBAC5C,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAyB;CAIvE;AAED,MAAM,MAAM,kBAAkB,GAC1B,wBAAwB,GACxB,sBAAsB,GACtB,2BAA2B,GAC3B,0BAA0B,GAC1B,qBAAqB,GACrB,qBAAqB,CAAC;AAE1B,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,kBAAkB,CAShF"}

package/operator/errors.js

@@ -0,0 +1,75 @@
+/**
+ * Operator-stage errors. Mirrors the discriminated-union pattern from
+ * `src/core/errors.ts`: each concrete class extends `Error` directly,
+ * the `HonuaOperatorError` type is the union of those classes, and
+ * `isHonuaOperatorError()` is the narrowing type guard.
+ *
+ * The set is independent of `HonuaError` in `src/core/errors.ts`; the
+ * two coexist so that adapter-level failures and operator-level failures
+ * can be discriminated separately.
+ *
+ * @module
+ */
+class HonuaOperatorErrorBase extends Error {
+    stage;
+    intentId;
+    planId;
+    executionId;
+    detail;
+    cause;
+    constructor(stage, message, context = {}) {
+        super(message);
+        this.stage = stage;
+        this.intentId = context.intentId;
+        this.planId = context.planId;
+        this.executionId = context.executionId;
+        this.detail = context.detail;
+        this.cause = context.cause;
+    }
+}
+export class HonuaOperatorIntentError extends HonuaOperatorErrorBase {
+    constructor(message, context = {}) {
+        super("intent", message, context);
+        this.name = "HonuaOperatorIntentError";
+    }
+}
+export class HonuaOperatorPlanError extends HonuaOperatorErrorBase {
+    constructor(message, context = {}) {
+        super("plan", message, context);
+        this.name = "HonuaOperatorPlanError";
+    }
+}
+export class HonuaOperatorExecutionError extends HonuaOperatorErrorBase {
+    failureKind;
+    constructor(message, context = {}) {
+        super("execution", message, context);
+        this.name = "HonuaOperatorExecutionError";
+        this.failureKind = context.failureKind;
+    }
+}
+export class HonuaOperatorApprovalError extends HonuaOperatorErrorBase {
+    constructor(message, context = {}) {
+        super("approval", message, context);
+        this.name = "HonuaOperatorApprovalError";
+    }
+}
+export class HonuaOperatorMapError extends HonuaOperatorErrorBase {
+    constructor(message, context = {}) {
+        super("map", message, context);
+        this.name = "HonuaOperatorMapError";
+    }
+}
+export class HonuaOperatorAppError extends HonuaOperatorErrorBase {
+    constructor(message, context = {}) {
+        super("app", message, context);
+        this.name = "HonuaOperatorAppError";
+    }
+}
+export function isHonuaOperatorError(error) {
+    return (error instanceof HonuaOperatorIntentError ||
+        error instanceof HonuaOperatorPlanError ||
+        error instanceof HonuaOperatorExecutionError ||
+        error instanceof HonuaOperatorApprovalError ||
+        error instanceof HonuaOperatorMapError ||
+        error instanceof HonuaOperatorAppError);
+}

package/operator/i18n/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `@honua/sdk-js/operator/i18n` — operator message catalog and resolution helpers.
+ *
+ * @experimental This entrypoint is not yet covered by the SDK's semver contract
+ *   — the surface may change in any minor release prior to `1.0.0`.
+ * @module
+ */
+export { DEFAULT_MESSAGES, resolveMessage } from "./messages.js";
+export type { MessageCatalog, MessageId } from "./messages.js";
+//# sourceMappingURL=index.d.ts.map

package/operator/i18n/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/operator/i18n/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACjE,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC"}

package/operator/i18n/index.js

@@ -0,0 +1,8 @@
+/**
+ * `@honua/sdk-js/operator/i18n` — operator message catalog and resolution helpers.
+ *
+ * @experimental This entrypoint is not yet covered by the SDK's semver contract
+ *   — the surface may change in any minor release prior to `1.0.0`.
+ * @module
+ */
+export { DEFAULT_MESSAGES, resolveMessage } from "./messages.js";

package/operator/i18n/messages.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `MessageCatalog` — flat `id → string` map with ICU-lite placeholder
+ * substitution (`{name}`). The catalog is the only place reference
+ * components read user-facing strings from; embedders ship alternates
+ * by passing a different catalog.
+ *
+ * @module
+ */
+export type MessageId = "chat.placeholder" | "chat.send" | "chat.empty" | "clarification.title" | "clarification.submit" | "clarification.required" | "plan.title" | "plan.empty" | "plan.accept" | "plan.revise" | "plan.requiresApproval" | "plan.estimatedCost" | "execution.idle" | "execution.accepted" | "execution.running" | "execution.successful" | "execution.failed" | "execution.dismissed" | "map.empty" | "map.refine" | "builder.empty" | "builder.refine" | "approval.notRequired" | "approval.pending" | "approval.granted" | "approval.deferred" | "approval.denied" | "approval.confirm" | "approval.audit";
+export type MessageCatalog = Partial<Record<MessageId, string>>;
+export declare const DEFAULT_MESSAGES: Readonly<Record<MessageId, string>>;
+/**
+ * Resolve a message id to a string with ICU-lite `{placeholder}`
+ * substitution. Falls back to `DEFAULT_MESSAGES` when an id is not
+ * present in the supplied catalog. Unknown placeholders survive
+ * unrendered so missing data is visible rather than silently empty.
+ */
+export declare function resolveMessage(catalog: MessageCatalog | undefined, id: MessageId, values?: Readonly<Record<string, string | number>>): string;
+//# sourceMappingURL=messages.d.ts.map