@inhuman.tools/plexus-expectations 0.0.0-stage → 0.2.0

package/dist/driver/PEWDriver.js

@@ -0,0 +1,303 @@
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+import { DefaultedWeakMap } from "@here.build/collections";
+import { action, computed, observable, toJS } from "mobx";
+import { pewConfigurationSchema, pewSecretsSchema } from "../schemas/connection.js";
+import { revalidationDemandOf } from "../shared/revalidation-demand.js";
+const EMPTY_SECRETS = { get: () => undefined };
+/** Module-graph duplication breaks instanceof; the elevation gate checks this brand too. */
+// eslint-disable-next-line no-secrets/no-secrets -- package identity tag, not a secret
+export const PEW_DRIVER_BRAND = "@inhuman.tools/plexus-expectations:PEWDriver@1";
+/**
+ * Driver extras the orchestrator mirrors onto `spec.live`.
+ * Core process facts live on `readyState` / `error` / `offers`.
+ */
+export function extraLiveFromState(state) {
+    const extra = {};
+    for (const [key, value] of Object.entries(state)) {
+        if (value === undefined)
+            continue;
+        extra[key] = toJS(value);
+    }
+    return extra;
+}
+/**
+ * The CLASS is the driver (one loaded module per driver name).
+ * The INSTANCE is a live connection (one per connection id).
+ *
+ * CLAIM DOES NOT LIVE HERE. Which WorkExpectation classes this driver handles
+ * lives on the advertised driver record (`can`): dynamically loaded code does
+ * not get to declare its own authority.
+ *
+ * Live state is report only — no machinery branches on it. Instance bootstrap
+ * truth is `bootstrapDone` / `bootstrapPending`. Drivers read {@link attention}
+ * as the reduced token, never clientIds.
+ *
+ * YAML doors ({@link configurationSchema} / {@link secretsSchema}) parse
+ * without `new`. Secrets stay a live view — the host may replace it (reauth).
+ */
+let PEWDriver = (() => {
+    var _a, _b;
+    let _instanceExtraInitializers = [];
+    let _readyState_decorators;
+    let _readyState_initializers = [];
+    let _readyState_extraInitializers = [];
+    let _error_decorators;
+    let _error_initializers = [];
+    let _error_extraInitializers = [];
+    let _state_decorators;
+    let _state_initializers = [];
+    let _state_extraInitializers = [];
+    let _awareness_decorators;
+    let _awareness_initializers = [];
+    let _awareness_extraInitializers = [];
+    let _get_revalidationDemand_decorators;
+    let _ensureBootstrapStarted_decorators;
+    let _failReady_decorators;
+    return class PEWDriver {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
+            __esDecorate(this, null, _readyState_decorators, { kind: "accessor", name: "readyState", static: false, private: false, access: { has: obj => "readyState" in obj, get: obj => obj.readyState, set: (obj, value) => { obj.readyState = value; } }, metadata: _metadata }, _readyState_initializers, _readyState_extraInitializers);
+            __esDecorate(this, null, _error_decorators, { kind: "accessor", name: "error", static: false, private: false, access: { has: obj => "error" in obj, get: obj => obj.error, set: (obj, value) => { obj.error = value; } }, metadata: _metadata }, _error_initializers, _error_extraInitializers);
+            __esDecorate(this, null, _state_decorators, { kind: "accessor", name: "state", static: false, private: false, access: { has: obj => "state" in obj, get: obj => obj.state, set: (obj, value) => { obj.state = value; } }, metadata: _metadata }, _state_initializers, _state_extraInitializers);
+            __esDecorate(this, null, _awareness_decorators, { kind: "accessor", name: "awareness", static: false, private: false, access: { has: obj => "awareness" in obj, get: obj => obj.awareness, set: (obj, value) => { obj.awareness = value; } }, metadata: _metadata }, _awareness_initializers, _awareness_extraInitializers);
+            __esDecorate(this, null, _get_revalidationDemand_decorators, { kind: "getter", name: "revalidationDemand", static: false, private: false, access: { has: obj => "revalidationDemand" in obj, get: obj => obj.revalidationDemand }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _ensureBootstrapStarted_decorators, { kind: "method", name: "ensureBootstrapStarted", static: false, private: false, access: { has: obj => "ensureBootstrapStarted" in obj, get: obj => obj.ensureBootstrapStarted }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _failReady_decorators, { kind: "method", name: "failReady", static: false, private: false, access: { has: obj => "failReady" in obj, get: obj => obj.failReady }, metadata: _metadata }, null, _instanceExtraInitializers);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        connectionId = __runInitializers(this, _instanceExtraInitializers);
+        // ── driver side (the CLASS is the driver) ─────────────────────────────
+        static pewBrand = PEW_DRIVER_BRAND;
+        /**
+         * YAML settings shape. Default is a passthrough record — subclasses replace
+         * this with a real object schema (transforms included). First issue message
+         * is what construct / parse throw.
+         */
+        static configurationSchema = pewConfigurationSchema;
+        static configurationLabel = "";
+        static configurationError(message) {
+            const label = this.configurationLabel.trim();
+            return label === "" ? `connection config invalid: ${message}` : `${label} connection config invalid: ${message}`;
+        }
+        /** YAML settings door. Does not construct an instance. */
+        static parseConfiguration(settings = {}) {
+            const result = this.configurationSchema.safeParse(settings ?? {});
+            if (result.success)
+                return result.data;
+            const message = result.error.issues[0]?.message ?? "invalid";
+            throw new Error(this.configurationError(message));
+        }
+        static secretsSchema = pewSecretsSchema;
+        static secretsError(message) {
+            const label = this.configurationLabel.trim();
+            return label === "" ? `connection secrets invalid: ${message}` : `${label} connection secrets invalid: ${message}`;
+        }
+        /** YAML secrets door. Does not construct an instance. */
+        static parseSecrets(secrets = {}) {
+            const result = this.secretsSchema.safeParse(secrets ?? {});
+            if (result.success)
+                return result.data;
+            const message = result.error.issues[0]?.message ?? "invalid";
+            throw new Error(this.secretsError(message));
+        }
+        /** Shared on the prototype chain — own extras per subclass. */
+        static state = {};
+        /**
+         * A plain list, or a getter over observable state when the driver keeps its
+         * offers fresh (local detection). The orchestrator mirrors it onto
+         * `DriverSpec.offers` with a reaction, which is also what observes it.
+         */
+        static offers = [];
+        /** Kernel-plane occupancy hub. Orchestrator assignment is own-per-class. */
+        static awareness;
+        static driverName = "";
+        /**
+         * A getter, not `@computed` — MobX: the decorator's initializer pins to the
+         * declaring class, so subclasses would share one computed.
+         */
+        static get revalidationDemand() {
+            const hub = this.awareness;
+            const name = this.driverName;
+            if (hub === undefined || name === "")
+                return "none";
+            return revalidationDemandOf(hub, { kind: "driver", name });
+        }
+        #readyState_accessor_storage = __runInitializers(this, _readyState_initializers, null);
+        // ── connection side (the INSTANCE is the connection) ──────────────────
+        get readyState() { return this.#readyState_accessor_storage; }
+        set readyState(value) { this.#readyState_accessor_storage = value; }
+        #error_accessor_storage = (__runInitializers(this, _readyState_extraInitializers), __runInitializers(this, _error_initializers, ""));
+        get error() { return this.#error_accessor_storage; }
+        set error(value) { this.#error_accessor_storage = value; }
+        #state_accessor_storage = (__runInitializers(this, _error_extraInitializers), __runInitializers(this, _state_initializers, {}));
+        /**
+         * MobX: shallow — extras (models, tools, account) are replaced wholesale.
+         * Override the accessor with a wider literal to add driver facts.
+         */
+        get state() { return this.#state_accessor_storage; }
+        set state(value) { this.#state_accessor_storage = value; }
+        #awareness_accessor_storage = (__runInitializers(this, _state_extraInitializers), __runInitializers(this, _awareness_initializers, undefined));
+        get awareness() { return this.#awareness_accessor_storage; }
+        set awareness(value) { this.#awareness_accessor_storage = value; }
+        get revalidationDemand() {
+            const hub = this.awareness;
+            if (hub === undefined)
+                return "none";
+            return revalidationDemandOf(hub, { kind: "connection", id: this.connectionId });
+        }
+        constructor(connectionId, settings = {}, secrets = EMPTY_SECRETS) {
+            this.connectionId = connectionId;
+            const cls = new.target;
+            this.settings = cls.parseConfiguration(settings);
+            const view = typeof secrets.get === "function"
+                ? secrets
+                : {
+                    get: (field) => secrets[field],
+                    all: () => secrets,
+                };
+            cls.parseSecrets(view.all?.() ?? {});
+            this.secrets = view;
+        }
+        settings = __runInitializers(this, _awareness_extraInitializers);
+        /** Live view. The host may replace it (reauth). */
+        secrets;
+        /**
+         * Host binds the disk writer for this connection's settings bag.
+         * Parsed settings stay readonly; a driver that learns a value overrides this.
+         */
+        bindSettingsWriter(_write) { }
+        bootstrapDone = false;
+        bootstrapPending = null;
+        /** `resolve()` threw — the connection is broken, not the work. */
+        broken = false;
+        /** Concurrent callers share one promise. Async settlement is its own MobX action. */
+        ensureBootstrapStarted() {
+            if (this.bootstrapDone)
+                return Promise.resolve();
+            if (this.bootstrapPending)
+                return this.bootstrapPending;
+            this.readyState = "bootstrapping";
+            this.error = "";
+            this.bootstrapPending = this.bootstrap().then(action(() => {
+                this.bootstrapDone = true;
+                this.readyState = "ready";
+                this.error = "";
+            }), action((error) => {
+                this.readyState = "failed";
+                this.error = error instanceof Error ? error.message : String(error);
+                throw error;
+            }));
+            return this.bootstrapPending;
+        }
+        failReady(error) {
+            this.broken = true;
+            this.readyState = "failed";
+            this.error = error instanceof Error ? error.message : String(error);
+        }
+        /** Nothing in PEW calls this; hosts or tests may. */
+        async [(_readyState_decorators = [observable], _error_decorators = [observable], _state_decorators = [(_a = observable).shallow.bind(_a)], _awareness_decorators = [(_b = observable).ref.bind(_b)], _get_revalidationDemand_decorators = [computed], _ensureBootstrapStarted_decorators = [action], _failReady_decorators = [action], Symbol.asyncDispose)]() { }
+        actors = new DefaultedWeakMap((expectation) => {
+            const actor = this.resolve(expectation);
+            this.liveActors.add(actor);
+            return actor;
+        });
+        liveActors = new Set();
+        has(expectation) {
+            return this.actors.has(expectation);
+        }
+        resolveExpectation(expectation) {
+            return this.actors.get(expectation);
+        }
+        release(expectation) {
+            if (!this.actors.has(expectation))
+                return;
+            const actor = this.actors.get(expectation);
+            this.actors.delete(expectation);
+            this.liveActors.delete(actor);
+            actor.leave();
+        }
+        /**
+         * Logout/drop aborts interned work. Not park. Subclasses abort `#inflight`.
+         */
+        abortOnDrop(reason) {
+            for (const actor of this.liveActors)
+                actor.abort(reason);
+        }
+        /**
+         * Honor one demand.
+         * `resolve()` throwing is a broken connection, not a failed expectation.
+         */
+        handle(expectation) {
+            if (this.broken)
+                return;
+            if (expectation.isDone)
+                return;
+            if (this.has(expectation)) {
+                const existing = this.resolveExpectation(expectation);
+                if (!existing.started)
+                    existing.start();
+                return;
+            }
+            let actor;
+            try {
+                actor = this.resolveExpectation(expectation);
+            }
+            catch (error) {
+                this.failReady(error);
+                return;
+            }
+            // Awareness / host policy may have sealed the work while resolve() ran.
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- resolve() can seal via spawn hooks
+            if (expectation.isDone) {
+                actor.leave();
+                return;
+            }
+            if (!actor.started) {
+                actor.start();
+            }
+        }
+    };
+})();
+export { PEWDriver };
+export function isDriverConnectionClass(value) {
+    if (typeof value !== "function")
+        return false;
+    if (value.pewBrand === PEW_DRIVER_BRAND)
+        return true;
+    return (typeof value.prototype === "object" &&
+        value.prototype instanceof PEWDriver);
+}
+//# sourceMappingURL=PEWDriver.js.map

package/dist/driver/PEWDriver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PEWDriver.js","sourceRoot":"","sources":["../../src/driver/PEWDriver.ts"],"names":[],"mappings":"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","sourcesContent":["import { DefaultedWeakMap } from \"@here.build/collections\";\nimport type { PlexusAwareness } from \"@here.build/plexus\";\nimport { action, computed, observable, toJS } from \"mobx\";\n\nimport type { ExpectationActor } from \"./ExpectationActor.js\";\nimport { pewConfigurationSchema, pewSecretsSchema } from \"../schemas/connection.js\";\nimport type { AnyWorkExpectation, WorkExpectation } from \"../shared/models/WorkExpectation.js\";\nimport { revalidationDemandOf, type RevalidationDemand } from \"../shared/revalidation-demand.js\";\nimport type { ReadyState } from \"../shared/types.js\";\n\n/** Duck-typed — drivers may ship a different Zod major than this package. */\nexport type ConfigurationSchema = {\n  safeParse(\n    data: unknown,\n  ):\n    | { readonly success: true; readonly data: unknown }\n    | { readonly success: false; readonly error: { readonly issues: ReadonlyArray<{ readonly message?: string }> } };\n};\n\n/** Process-local. Secrets are never a Plexus field. */\nexport type ConnectionSecretsView = {\n  readonly revision?: number;\n  get(field: string): unknown | undefined;\n  /** MCP env_* enumerates deposited fields. */\n  all?(): Readonly<Record<string, unknown>> | undefined;\n  /** Hosts that persist a refreshed session (reauth) implement this. */\n  replace?(secrets: Readonly<Record<string, string>>): void;\n};\n\nconst EMPTY_SECRETS: ConnectionSecretsView = { get: () => undefined };\n\n/** Module-graph duplication breaks instanceof; the elevation gate checks this brand too. */\n// eslint-disable-next-line no-secrets/no-secrets -- package identity tag, not a secret\nexport const PEW_DRIVER_BRAND = \"@inhuman.tools/plexus-expectations:PEWDriver@1\";\n\n/** A connection construction the driver already knows will work. */\nexport type DriverOffer = {\n  readonly name: string;\n  readonly description: string;\n  readonly live: boolean;\n  readonly adoptable: boolean;\n  readonly settings: Readonly<Record<string, unknown>>;\n};\n\n/**\n * Driver extras the orchestrator mirrors onto `spec.live`.\n * Core process facts live on `readyState` / `error` / `offers`.\n */\nexport function extraLiveFromState(state: object): Record<string, unknown> {\n  const extra: Record<string, unknown> = {};\n  for (const [key, value] of Object.entries(state)) {\n    if (value === undefined) continue;\n    extra[key] = toJS(value);\n  }\n  return extra;\n}\n\n/**\n * The CLASS is the driver (one loaded module per driver name).\n * The INSTANCE is a live connection (one per connection id).\n *\n * CLAIM DOES NOT LIVE HERE. Which WorkExpectation classes this driver handles\n * lives on the advertised driver record (`can`): dynamically loaded code does\n * not get to declare its own authority.\n *\n * Live state is report only — no machinery branches on it. Instance bootstrap\n * truth is `bootstrapDone` / `bootstrapPending`. Drivers read {@link attention}\n * as the reduced token, never clientIds.\n *\n * YAML doors ({@link configurationSchema} / {@link secretsSchema}) parse\n * without `new`. Secrets stay a live view — the host may replace it (reauth).\n */\nexport abstract class PEWDriver<\n  E extends AnyWorkExpectation = AnyWorkExpectation,\n  C = Readonly<Record<string, unknown>>,\n> implements AsyncDisposable {\n  // ── driver side (the CLASS is the driver) ─────────────────────────────\n  static readonly pewBrand: string = PEW_DRIVER_BRAND;\n\n  /**\n   * YAML settings shape. Default is a passthrough record — subclasses replace\n   * this with a real object schema (transforms included). First issue message\n   * is what construct / parse throw.\n   */\n  static readonly configurationSchema: ConfigurationSchema = pewConfigurationSchema;\n\n  static readonly configurationLabel: string = \"\";\n\n  static configurationError(message: string): string {\n    const label = this.configurationLabel.trim();\n    return label === \"\" ? `connection config invalid: ${message}` : `${label} connection config invalid: ${message}`;\n  }\n\n  /** YAML settings door. Does not construct an instance. */\n  static parseConfiguration(settings: unknown = {}): unknown {\n    const result = this.configurationSchema.safeParse(settings ?? {});\n    if (result.success) return result.data;\n    const message = result.error.issues[0]?.message ?? \"invalid\";\n    throw new Error(this.configurationError(message));\n  }\n\n  static readonly secretsSchema: ConfigurationSchema = pewSecretsSchema;\n\n  static secretsError(message: string): string {\n    const label = this.configurationLabel.trim();\n    return label === \"\" ? `connection secrets invalid: ${message}` : `${label} connection secrets invalid: ${message}`;\n  }\n\n  /** YAML secrets door. Does not construct an instance. */\n  static parseSecrets(secrets: unknown = {}): unknown {\n    const result = this.secretsSchema.safeParse(secrets ?? {});\n    if (result.success) return result.data;\n    const message = result.error.issues[0]?.message ?? \"invalid\";\n    throw new Error(this.secretsError(message));\n  }\n\n  /** Shared on the prototype chain — own extras per subclass. */\n  static readonly state: Record<string, unknown> = {};\n  /**\n   * A plain list, or a getter over observable state when the driver keeps its\n   * offers fresh (local detection). The orchestrator mirrors it onto\n   * `DriverSpec.offers` with a reaction, which is also what observes it.\n   */\n  static readonly offers: readonly DriverOffer[] = [];\n\n  /** Kernel-plane occupancy hub. Orchestrator assignment is own-per-class. */\n  static awareness: PlexusAwareness | undefined;\n  static driverName = \"\";\n\n  /**\n   * A getter, not `@computed` — MobX: the decorator's initializer pins to the\n   * declaring class, so subclasses would share one computed.\n   */\n  static get revalidationDemand(): RevalidationDemand {\n    const hub = this.awareness;\n    const name = this.driverName;\n    if (hub === undefined || name === \"\") return \"none\";\n    return revalidationDemandOf(hub, { kind: \"driver\", name });\n  }\n\n  // ── connection side (the INSTANCE is the connection) ──────────────────\n  @observable accessor readyState: ReadyState = null;\n  @observable accessor error: string = \"\";\n  /**\n   * MobX: shallow — extras (models, tools, account) are replaced wholesale.\n   * Override the accessor with a wider literal to add driver facts.\n   */\n  @observable.shallow accessor state: Record<string, unknown> = {};\n\n  @observable.ref accessor awareness: PlexusAwareness | undefined = undefined;\n\n  @computed\n  get revalidationDemand(): RevalidationDemand {\n    const hub = this.awareness;\n    if (hub === undefined) return \"none\";\n    return revalidationDemandOf(hub, { kind: \"connection\", id: this.connectionId });\n  }\n\n  constructor(\n    public readonly connectionId: string,\n    settings: unknown = {},\n    secrets: ConnectionSecretsView | Readonly<Record<string, unknown>> = EMPTY_SECRETS,\n  ) {\n    const cls = new.target as typeof PEWDriver;\n    this.settings = cls.parseConfiguration(settings) as C;\n    const view: ConnectionSecretsView =\n      typeof (secrets as ConnectionSecretsView).get === \"function\"\n        ? (secrets as ConnectionSecretsView)\n        : {\n            get: (field) => (secrets as Readonly<Record<string, unknown>>)[field],\n            all: () => secrets as Readonly<Record<string, unknown>>,\n          };\n    cls.parseSecrets(view.all?.() ?? {});\n    this.secrets = view;\n  }\n  readonly settings: C;\n  /** Live view. The host may replace it (reauth). */\n  secrets: ConnectionSecretsView;\n\n  /**\n   * Host binds the disk writer for this connection's settings bag.\n   * Parsed settings stay readonly; a driver that learns a value overrides this.\n   */\n  bindSettingsWriter(_write: (patch: Readonly<Record<string, unknown>>) => void): void {}\n\n  abstract bootstrap(): Promise<void>;\n\n  bootstrapDone = false;\n  bootstrapPending: Promise<void> | null = null;\n  /** `resolve()` threw — the connection is broken, not the work. */\n  broken = false;\n  /** Concurrent callers share one promise. Async settlement is its own MobX action. */\n  @action\n  ensureBootstrapStarted(): Promise<void> {\n    if (this.bootstrapDone) return Promise.resolve();\n    if (this.bootstrapPending) return this.bootstrapPending;\n    this.readyState = \"bootstrapping\";\n    this.error = \"\";\n    this.bootstrapPending = this.bootstrap().then(\n      action(() => {\n        this.bootstrapDone = true;\n        this.readyState = \"ready\";\n        this.error = \"\";\n      }),\n      action((error: unknown) => {\n        this.readyState = \"failed\";\n        this.error = error instanceof Error ? error.message : String(error);\n        throw error;\n      }),\n    );\n    return this.bootstrapPending;\n  }\n\n  @action\n  failReady(error: unknown): void {\n    this.broken = true;\n    this.readyState = \"failed\";\n    this.error = error instanceof Error ? error.message : String(error);\n  }\n\n  protected abstract resolve(expectation: E): ExpectationActor<E>;\n  /** Nothing in PEW calls this; hosts or tests may. */\n  async [Symbol.asyncDispose](): Promise<void> {}\n\n  private readonly actors = new DefaultedWeakMap<WorkExpectation, ExpectationActor<any>>((expectation: WorkExpectation): ExpectationActor<any> => {\n  const actor = this.resolve(expectation as E);\n  this.liveActors.add(actor);\n  return actor;\n});\n  private readonly liveActors = new Set<ExpectationActor<any>>();\n\n  has(expectation: WorkExpectation): boolean {\n    return this.actors.has(expectation);\n  }\n  resolveExpectation<T extends AnyWorkExpectation>(expectation: T): ExpectationActor<T> {\n    return this.actors.get(expectation);\n  }\n  release(expectation: WorkExpectation): void {\n    if (!this.actors.has(expectation)) return;\n    const actor = this.actors.get(expectation);\n    this.actors.delete(expectation);\n    this.liveActors.delete(actor);\n    actor.leave();\n  }\n\n  /**\n   * Logout/drop aborts interned work. Not park. Subclasses abort `#inflight`.\n   */\n  abortOnDrop(reason: unknown): void {\n    for (const actor of this.liveActors) actor.abort(reason);\n  }\n\n  /**\n   * Honor one demand.\n   * `resolve()` throwing is a broken connection, not a failed expectation.\n   */\n  handle(expectation: WorkExpectation): void {\n    if (this.broken) return;\n    if (expectation.isDone) return;\n    if (this.has(expectation)) {\n      const existing = this.resolveExpectation(expectation);\n      if (!existing.started) existing.start();\n      return;\n    }\n\n    let actor: ExpectationActor<any>;\n    try {\n      actor = this.resolveExpectation(expectation);\n    } catch (error) {\n      this.failReady(error);\n      return;\n    }\n\n    // Awareness / host policy may have sealed the work while resolve() ran.\n    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- resolve() can seal via spawn hooks\n    if (expectation.isDone) {\n      actor.leave();\n      return;\n    }\n\n    if (!actor.started) {\n      actor.start();\n    }\n  }\n}\n\n/**\n * A concrete `PEWDriver` subclass — constructable, not abstract.\n * `loadDriverModule` returns `unknown`; {@link isDriverConnectionClass} is the gate.\n */\nexport type DriverConnectionClass = {\n  [K in keyof typeof PEWDriver]: (typeof PEWDriver)[K];\n} & (new (...args: ConstructorParameters<typeof PEWDriver>) => PEWDriver);\n\nexport function isDriverConnectionClass(value: unknown): value is DriverConnectionClass {\n  if (typeof value !== \"function\") return false;\n  if ((value as { pewBrand?: unknown }).pewBrand === PEW_DRIVER_BRAND) return true;\n  return (\n    typeof (value as { prototype?: unknown }).prototype === \"object\" &&\n    (value as { prototype: object }).prototype instanceof PEWDriver\n  );\n}\n"]}

package/dist/driver/actor-machine.d.ts

@@ -0,0 +1,28 @@
+import { type EventFromLogic, type StateValueFrom } from "xstate";
+/**
+ * Process-local actor phase. Distinct from the durable WorkExpectation lifecycle.
+ *
+ * minted ──START──► running ──SETTLE|CRASH──► resolved (final)
+ *    │                 │
+ *    ├──ABORT──► aborted ──SETTLE|CRASH──────────┘
+ *    └──RELEASE────────┴──RELEASE──────────► released (final)
+ *
+ * ENDINGS ARE OBSERVED. RELEASE fires from the actor's done reaction on the
+ * durable entity — never from a control-flow wrapper. `resolved` is
+ * settlement/crash; `released` is abort without a settlement.
+ */
+export declare const expectationActorMachine: import("xstate").StateMachine<import("xstate").MachineContext, {
+    type: "START" | "SETTLE" | "CRASH" | "ABORT" | "RELEASE";
+}, {}, never, never, never, never, "minted" | "running" | "aborted" | "released" | "resolved", string, import("xstate").NonReducibleUnknown, import("xstate").NonReducibleUnknown, import("xstate").EventObject, import("xstate").MetaObject, {
+    id: "pew-expectation-actor";
+    states: {
+        readonly minted: {};
+        readonly running: {};
+        readonly resolved: {};
+        readonly aborted: {};
+        readonly released: {};
+    };
+}>;
+export type ActorPhase = StateValueFrom<typeof expectationActorMachine>;
+export type ActorPhaseEvent = EventFromLogic<typeof expectationActorMachine>;
+//# sourceMappingURL=actor-machine.d.ts.map

package/dist/driver/actor-machine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actor-machine.d.ts","sourceRoot":"","sources":["../../src/driver/actor-machine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,QAAQ,CAAC;AAEzE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,uBAAuB;UAEV,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS;;;;;;;;;;EAiC1E,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,cAAc,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,MAAM,MAAM,eAAe,GAAG,cAAc,CAAC,OAAO,uBAAuB,CAAC,CAAC"}

package/dist/driver/actor-machine.js

@@ -0,0 +1,50 @@
+import { setup } from "xstate";
+/**
+ * Process-local actor phase. Distinct from the durable WorkExpectation lifecycle.
+ *
+ * minted ──START──► running ──SETTLE|CRASH──► resolved (final)
+ *    │                 │
+ *    ├──ABORT──► aborted ──SETTLE|CRASH──────────┘
+ *    └──RELEASE────────┴──RELEASE──────────► released (final)
+ *
+ * ENDINGS ARE OBSERVED. RELEASE fires from the actor's done reaction on the
+ * durable entity — never from a control-flow wrapper. `resolved` is
+ * settlement/crash; `released` is abort without a settlement.
+ */
+export const expectationActorMachine = setup({
+    types: {
+        events: {},
+    },
+}).createMachine({
+    id: "pew-expectation-actor",
+    initial: "minted",
+    states: {
+        minted: {
+            tags: ["live"],
+            on: {
+                START: "running",
+                ABORT: "aborted",
+                RELEASE: "released",
+            },
+        },
+        running: {
+            tags: ["live"],
+            on: {
+                SETTLE: "resolved",
+                CRASH: "resolved",
+                ABORT: "aborted",
+                RELEASE: "released",
+            },
+        },
+        resolved: { type: "final" },
+        aborted: {
+            on: {
+                SETTLE: "resolved",
+                CRASH: "resolved",
+                RELEASE: "released",
+            },
+        },
+        released: { type: "final" },
+    },
+});
+//# sourceMappingURL=actor-machine.js.map

package/dist/driver/actor-machine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actor-machine.js","sourceRoot":"","sources":["../../src/driver/actor-machine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAA4C,MAAM,QAAQ,CAAC;AAEzE;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,KAAK,CAAC;IAC3C,KAAK,EAAE;QACL,MAAM,EAAE,EAAkE;KAC3E;CACF,CAAC,CAAC,aAAa,CAAC;IACf,EAAE,EAAE,uBAAuB;IAC3B,OAAO,EAAE,QAAQ;IACjB,MAAM,EAAE;QACN,MAAM,EAAE;YACN,IAAI,EAAE,CAAC,MAAM,CAAC;YACd,EAAE,EAAE;gBACF,KAAK,EAAE,SAAS;gBAChB,KAAK,EAAE,SAAS;gBAChB,OAAO,EAAE,UAAU;aACpB;SACF;QACD,OAAO,EAAE;YACP,IAAI,EAAE,CAAC,MAAM,CAAC;YACd,EAAE,EAAE;gBACF,MAAM,EAAE,UAAU;gBAClB,KAAK,EAAE,UAAU;gBACjB,KAAK,EAAE,SAAS;gBAChB,OAAO,EAAE,UAAU;aACpB;SACF;QACD,QAAQ,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE;QAC3B,OAAO,EAAE;YACP,EAAE,EAAE;gBACF,MAAM,EAAE,UAAU;gBAClB,KAAK,EAAE,UAAU;gBACjB,OAAO,EAAE,UAAU;aACpB;SACF;QACD,QAAQ,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE;KAC5B;CACF,CAAC,CAAC","sourcesContent":["import { setup, type EventFromLogic, type StateValueFrom } from \"xstate\";\n\n/**\n * Process-local actor phase. Distinct from the durable WorkExpectation lifecycle.\n *\n * minted ──START──► running ──SETTLE|CRASH──► resolved (final)\n *    │                 │\n *    ├──ABORT──► aborted ──SETTLE|CRASH──────────┘\n *    └──RELEASE────────┴──RELEASE──────────► released (final)\n *\n * ENDINGS ARE OBSERVED. RELEASE fires from the actor's done reaction on the\n * durable entity — never from a control-flow wrapper. `resolved` is\n * settlement/crash; `released` is abort without a settlement.\n */\nexport const expectationActorMachine = setup({\n  types: {\n    events: {} as { type: \"START\" | \"SETTLE\" | \"CRASH\" | \"ABORT\" | \"RELEASE\" },\n  },\n}).createMachine({\n  id: \"pew-expectation-actor\",\n  initial: \"minted\",\n  states: {\n    minted: {\n      tags: [\"live\"],\n      on: {\n        START: \"running\",\n        ABORT: \"aborted\",\n        RELEASE: \"released\",\n      },\n    },\n    running: {\n      tags: [\"live\"],\n      on: {\n        SETTLE: \"resolved\",\n        CRASH: \"resolved\",\n        ABORT: \"aborted\",\n        RELEASE: \"released\",\n      },\n    },\n    resolved: { type: \"final\" },\n    aborted: {\n      on: {\n        SETTLE: \"resolved\",\n        CRASH: \"resolved\",\n        RELEASE: \"released\",\n      },\n    },\n    released: { type: \"final\" },\n  },\n});\n\nexport type ActorPhase = StateValueFrom<typeof expectationActorMachine>;\n\nexport type ActorPhaseEvent = EventFromLogic<typeof expectationActorMachine>;\n"]}

package/dist/driver/connection-miss.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Intern / send-ready miss. Remainder maps `noconnect` → writeFail("no model connection").
+ * Honor fallback (one release) catches only this class.
+ */
+export declare class ConnectionMiss extends Error {
+    readonly code: "noconnect" | "not-ready" | "needs-auth" | "connection-dropped";
+    constructor(code: ConnectionMiss["code"], message?: string);
+}
+//# sourceMappingURL=connection-miss.d.ts.map

package/dist/driver/connection-miss.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-miss.d.ts","sourceRoot":"","sources":["../../src/driver/connection-miss.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,WAAW,GAAG,YAAY,GAAG,oBAAoB,CAAC;gBAEnE,IAAI,EAAE,cAAc,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM;CAK3D"}

package/dist/driver/connection-miss.js

@@ -0,0 +1,13 @@
+/**
+ * Intern / send-ready miss. Remainder maps `noconnect` → writeFail("no model connection").
+ * Honor fallback (one release) catches only this class.
+ */
+export class ConnectionMiss extends Error {
+    code;
+    constructor(code, message) {
+        super(message ?? code);
+        this.name = "ConnectionMiss";
+        this.code = code;
+    }
+}
+//# sourceMappingURL=connection-miss.js.map

package/dist/driver/connection-miss.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-miss.js","sourceRoot":"","sources":["../../src/driver/connection-miss.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC9B,IAAI,CAAkE;IAE/E,YAAY,IAA4B,EAAE,OAAgB;QACxD,KAAK,CAAC,OAAO,IAAI,IAAI,CAAC,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF","sourcesContent":["/**\n * Intern / send-ready miss. Remainder maps `noconnect` → writeFail(\"no model connection\").\n * Honor fallback (one release) catches only this class.\n */\nexport class ConnectionMiss extends Error {\n  readonly code: \"noconnect\" | \"not-ready\" | \"needs-auth\" | \"connection-dropped\";\n\n  constructor(code: ConnectionMiss[\"code\"], message?: string) {\n    super(message ?? code);\n    this.name = \"ConnectionMiss\";\n    this.code = code;\n  }\n}\n"]}

package/dist/driver/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./PEWDriver.js";
+export { type RevalidationDemand as RevalidationDemand } from "../shared/index.js";
+export * from "./ExpectationActor.js";
+export * from "./actor-machine.js";
+export * from "./connection-miss.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/driver/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/driver/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,KAAK,kBAAkB,IAAI,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACnF,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC"}

package/dist/driver/index.js

@@ -0,0 +1,5 @@
+export * from "./PEWDriver.js";
+export * from "./ExpectationActor.js";
+export * from "./actor-machine.js";
+export * from "./connection-miss.js";
+//# sourceMappingURL=index.js.map

package/dist/driver/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/driver/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAE/B,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC","sourcesContent":["export * from \"./PEWDriver.js\";\nexport { type RevalidationDemand as RevalidationDemand } from \"../shared/index.js\";\nexport * from \"./ExpectationActor.js\";\nexport * from \"./actor-machine.js\";\nexport * from \"./connection-miss.js\";\n"]}

package/dist/executor/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./orchestrator.js";
+export * from "./kernel-intern.js";
+export * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/executor/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/executor/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,YAAY,CAAC"}

package/dist/executor/index.js

@@ -0,0 +1,4 @@
+export * from "./orchestrator.js";
+export * from "./kernel-intern.js";
+export * from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/executor/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/executor/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,YAAY,CAAC","sourcesContent":["export * from \"./orchestrator.js\";\nexport * from \"./kernel-intern.js\";\nexport * from \"./types.js\";\n"]}

package/dist/executor/kernel-intern.d.ts

@@ -0,0 +1,16 @@
+import { type PEWDriver } from "../driver/PEWDriver.js";
+import type { ConnectionSpec } from "../shared/models/ConnectionSpec.js";
+type KernelRoot = {
+    readonly connections: Record<string, ConnectionSpec | undefined>;
+};
+export declare function acquireConnection(kernel: KernelRoot, owner: object, connectionId: string, construct: () => PEWDriver | Promise<PEWDriver>): Promise<PEWDriver>;
+export declare function releaseConnection(kernel: object, owner: object, connectionId: string): void;
+/**
+ * Remint door. Logout/drop — not park, not last-ref.
+ * Pending lease still `asyncDispose`s when it fulfills. Next `ensure` remints.
+ */
+export declare function dropConnection(kernel: KernelRoot, connectionId: string): Promise<void>;
+/** Kernel teardown only. Session park is a document wrap, not a connection lifetime. */
+export declare function disposeKernelConnections(kernel: object): void;
+export {};
+//# sourceMappingURL=kernel-intern.d.ts.map

package/dist/executor/kernel-intern.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kernel-intern.d.ts","sourceRoot":"","sources":["../../src/executor/kernel-intern.ts"],"names":[],"mappings":"AAWA,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAC5E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AASzE,KAAK,UAAU,GAAG;IAAE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,GAAG,SAAS,CAAC,CAAA;CAAE,CAAC;AAUvF,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,GAC9C,OAAO,CAAC,SAAS,CAAC,CAsCpB;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAG3F;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAmB5F;AAED,wFAAwF;AACxF,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAa7D"}

package/dist/executor/kernel-intern.js

@@ -0,0 +1,98 @@
+/**
+ * Process-local connection intern table keyed by the kernel root object.
+ *
+ * Session wrap is Yjs load. Park drops an owner ref and must not dispose the
+ * instance — {@link disposeKernelConnections} is kernel teardown only.
+ * Rejected: last-ref dispose. Switching seats reminted every driver.
+ */
+import { DefaultedWeakMap } from "@here.build/collections";
+import { comparer, reaction } from "mobx";
+import { ConnectionMiss } from "../driver/connection-miss.js";
+import { extraLiveFromState } from "../driver/PEWDriver.js";
+import { asReadyState } from "../shared/types.js";
+function internOwnerOf(owner) {
+    return typeof owner.forgetConnection === "function" ? owner : undefined;
+}
+const internByKernel = new DefaultedWeakMap(() => ({ connections: new Map() }));
+export function acquireConnection(kernel, owner, connectionId, construct) {
+    const bag = internByKernel.get(kernel);
+    const existing = bag.connections.get(connectionId);
+    if (existing !== undefined) {
+        existing.refs.add(owner);
+        return existing.pending;
+    }
+    const lease = {
+        refs: new Set([owner]),
+        pending: Promise.resolve().then(construct).then((instance) => {
+            lease.mirror = reaction(() => {
+                const spec = kernel.connections[connectionId];
+                if (spec === undefined)
+                    return null;
+                const ready = asReadyState(instance.readyState);
+                // Bootstrapping remint must not wipe a ready catalog.
+                if (ready !== "ready" && ready !== "failed" && spec.readyState === "ready")
+                    return null;
+                return { ready, error: instance.error, live: extraLiveFromState(instance.state) };
+            }, (snap) => {
+                if (snap == null)
+                    return;
+                kernel.connections[connectionId]?.stampProcess({
+                    readyState: snap.ready,
+                    error: snap.error,
+                    live: snap.live,
+                });
+            }, { fireImmediately: true, equals: comparer.structural });
+            return instance;
+        }),
+        mirror: undefined,
+    };
+    bag.connections.set(connectionId, lease);
+    void lease.pending.then(undefined, () => {
+        if (lease.refs.size === 0)
+            bag.connections.delete(connectionId);
+    });
+    return lease.pending;
+}
+export function releaseConnection(kernel, owner, connectionId) {
+    if (!internByKernel.has(kernel))
+        return;
+    internByKernel.get(kernel).connections.get(connectionId)?.refs.delete(owner);
+}
+/**
+ * Remint door. Logout/drop — not park, not last-ref.
+ * Pending lease still `asyncDispose`s when it fulfills. Next `ensure` remints.
+ */
+export async function dropConnection(kernel, connectionId) {
+    if (!internByKernel.has(kernel))
+        return;
+    const bag = internByKernel.get(kernel);
+    const lease = bag.connections.get(connectionId);
+    if (lease === undefined)
+        return;
+    bag.connections.delete(connectionId);
+    lease.mirror?.();
+    const owners = [...lease.refs];
+    lease.refs.clear();
+    const miss = new ConnectionMiss("connection-dropped", `connection ${connectionId} dropped`);
+    const disposing = lease.pending.then((instance) => {
+        instance.abortOnDrop(miss);
+        return instance[Symbol.asyncDispose]();
+    }, () => { });
+    for (const owner of owners)
+        internOwnerOf(owner)?.forgetConnection(connectionId);
+    await disposing;
+}
+/** Kernel teardown only. Session park is a document wrap, not a connection lifetime. */
+export function disposeKernelConnections(kernel) {
+    if (!internByKernel.has(kernel))
+        return;
+    const bag = internByKernel.get(kernel);
+    internByKernel.delete(kernel);
+    for (const lease of bag.connections.values()) {
+        lease.refs.clear();
+        lease.mirror?.();
+        void lease.pending.then((instance) => instance[Symbol.asyncDispose](), () => { });
+    }
+    bag.connections.clear();
+}
+//# sourceMappingURL=kernel-intern.js.map