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

package/src/driver/ExpectationActor.ts

@@ -0,0 +1,244 @@
+import { type PlexusAwareness } from "@here.build/plexus";
+import { ErrorWithInvariant } from "@inhuman.tools/error-with-invariant";
+import { reaction, runInAction } from "mobx";
+import invariant from "tiny-invariant";
+import { createActor } from "xstate";
+
+import { type ActorPhase, type ActorPhaseEvent, expectationActorMachine } from "./actor-machine.js";
+import type { PEWDriver } from "./PEWDriver.js";
+import type { Settlement } from "../executor/types.js";
+import type { SessionAwareness } from "../shared/index.js";
+import {
+  type AnyWorkExpectation,
+  type ReportOf,
+  type ResultOf,
+  ROLE_LANE_OCCUPIED,
+} from "../shared/models/WorkExpectation.js";
+import { reportRole, retractRole } from "../shared/role.js";
+
+/**
+ * Thrown from `run()` — `start()` settles the work as fail, not crash.
+ *
+ * Two kinds: {@link ConnectionNotReady} (fulfiller not live), {@link DemandIncomplete}
+ * (required field missing on the expectation). Not this family: cancel, applySettlement,
+ * report JSON crash, HTTP/tool `fail(reason)`.
+ */
+export abstract class ExpectationInvariant extends ErrorWithInvariant {
+  override name = this.constructor.name;
+
+  constructor(message: string) {
+    super(message);
+  }
+}
+
+/** Honor started; the fulfiller is not live. */
+export class ConnectionNotReady extends ExpectationInvariant {
+  constructor(readonly connection: string) {
+    super(`${connection} connection not ready`);
+  }
+}
+
+/** Required field missing on the expectation body. */
+export class DemandIncomplete extends ExpectationInvariant {
+  constructor(readonly field: string) {
+    super(`demand missing ${field}`);
+  }
+}
+
+/**
+ * One execution of one expectation, bound to the process that has the live connection.
+ *
+ * ENDINGS ARE OBSERVED, NOT IMPOSED. The actor writes durable endings only at
+ * two authority points — its own settlement (`#settle` / `#crash`) and host
+ * admission (`admitTermination`). Everything that must happen BECAUSE the
+ * work ended (abort the signal, leave) runs in the done reaction — so an
+ * ending that arrives from anywhere (a peer's write synced in, host policy)
+ * stops this actor exactly like its own. Child endings are supervision's
+ * job (the tree-orphan rule), never a cascade from here.
+ */
+export abstract class ExpectationActor<E extends AnyWorkExpectation = AnyWorkExpectation> {
+  readonly #hub: PlexusAwareness<SessionAwareness>;
+  readonly #controller = new AbortController();
+  readonly signal: AbortSignal = this.#controller.signal;
+  #lastReportJson: string | null = null;
+  #settlement: Settlement<ResultOf<E>> | null = null;
+  #resolveSettled!: (settlement: Settlement<ResultOf<E>>) => void;
+  #rejectSettled!: (reason: unknown) => void;
+  public readonly settled: Promise<Settlement<ResultOf<E>>>;
+  readonly #phase = createActor(expectationActorMachine).start();
+  #laneDisposers: Array<() => void> = [];
+  #left = false;
+
+  constructor(
+    public readonly expectation: E,
+    public readonly driverConnection: PEWDriver<E>,
+  ) {
+    this.settled = new Promise<Settlement<ResultOf<E>>>((resolve, reject) => {
+      this.#resolveSettled = resolve;
+      this.#rejectSettled = reject;
+    });
+    void this.settled.catch(() => {});
+
+    this.signal.addEventListener(
+      "abort",
+      () => {
+        this.#send("ABORT");
+      },
+      { once: true },
+    );
+
+    invariant(expectation.plexus != null, "ExpectationActor requires the expectation to be on a session plexus");
+    this.#hub = expectation.plexus.awareness as PlexusAwareness<SessionAwareness>;
+    this.#laneDisposers.push(
+      reaction(
+        () => this.expectation.isDone,
+        (done) => {
+          if (!done) return;
+          this.abort("done");
+          this.#send("RELEASE");
+          this.leave();
+        },
+        { fireImmediately: true },
+      ),
+    );
+  }
+
+  get started(): boolean {
+    return !this.#phase.getSnapshot().can({ type: "START" });
+  }
+
+  get done(): boolean {
+    return this.#phase.getSnapshot().status === "done";
+  }
+
+  start(): void {
+    invariant(this.#phase.getSnapshot().can({ type: "START" }), "double-start attempt");
+    this.#send("START");
+    runInAction(() => {
+      this.expectation.markStarted();
+    });
+    this.#occupyRoleLane();
+    try {
+      const result = this.run();
+      if (result != null && typeof (result as Promise<void>).then === "function") {
+        (result as Promise<void>).catch((error) => this.#onRunError(error));
+      }
+    } catch (error) {
+      this.#onRunError(error);
+    }
+  }
+
+  #onRunError(error: unknown): void {
+    if (error instanceof ExpectationInvariant) {
+      this.fail(error);
+      return;
+    }
+    this.#crash(error);
+  }
+
+  #matches(phase: ActorPhase): boolean {
+    return this.#phase.getSnapshot().matches(phase);
+  }
+
+  #send(type: ActorPhaseEvent["type"]): void {
+    if (!this.#phase.getSnapshot().can({ type })) return;
+    this.#phase.send({ type });
+  }
+
+  #occupyRoleLane(): void {
+    reportRole(this.#hub, this.expectation.uuid, ROLE_LANE_OCCUPIED);
+  }
+
+  protected abstract run(): void | Promise<void>;
+
+  abort(reason?: unknown): void {
+    this.#controller.abort(reason);
+  }
+
+  protected report(frame: ReportOf<E>): void {
+    if (!this.#matches("running")) return;
+    let json: string;
+    try {
+      json = JSON.stringify(frame ?? null);
+    } catch (error) {
+      this.#crash(error);
+      return;
+    }
+    this.#lastReportJson = json;
+    reportRole(this.#hub, this.expectation.uuid, JSON.parse(json));
+  }
+
+  protected complete(result: ResultOf<E>): void {
+    this.#settle({ outcome: "complete", result });
+  }
+
+  protected fail(reason: unknown): void {
+    this.#settle({ outcome: "fail", reason });
+  }
+
+  #settle(settlement: Settlement<ResultOf<E>>): void {
+    if (this.done || !this.#phase.getSnapshot().can({ type: "SETTLE" })) return;
+    const wasRunning = this.#matches("running");
+    this.#settlement = settlement;
+    this.#resolveSettled(settlement);
+    this.#send("SETTLE");
+    this.#commitEnding("settle", wasRunning);
+  }
+
+  #crash(reason: unknown): void {
+    if (this.done || !this.#phase.getSnapshot().can({ type: "CRASH" })) return;
+    const wasRunning = this.#matches("running");
+    this.#rejectSettled(reason);
+    this.#send("CRASH");
+    this.#commitEnding("crash", wasRunning, String(reason));
+  }
+
+  /**
+   * ENDING PRECEDES ABORT. A settlement captured while running (or consulted
+   * when admitting cancel) wins. A complete/fail flushed from an abort listener
+   * is stored on `#settlement` but not written here.
+   */
+  #commitEnding(kind: "settle" | "crash" | "cancel", wasRunning: boolean, crashDetail?: string): void {
+    if (this.expectation.isDone) return;
+    if (this.#settlement !== null && (wasRunning || kind === "cancel")) {
+      const settlement = this.#settlement;
+      if (settlement.outcome === "complete") {
+        this.expectation.succeed("settled", "", this.#frameJson(), { result: settlement.result });
+      } else {
+        this.expectation.fail(
+          "settled",
+          settlement.reason instanceof Error ? settlement.reason.message : String(settlement.reason),
+          this.#frameJson(),
+        );
+      }
+      return;
+    }
+    if (kind === "cancel") {
+      this.expectation.fail("cancel", "terminate", this.#frameJson());
+      return;
+    }
+    if (!wasRunning) return;
+    if (kind === "crash") {
+      this.expectation.fail("crash", crashDetail ?? "", this.#frameJson());
+    }
+  }
+
+  /** Host cancel. A settlement captured while running outranks the cancel. */
+  admitTermination(): void {
+    this.#commitEnding("cancel", this.#matches("running"));
+  }
+
+  #frameJson(): string {
+    return this.#lastReportJson ?? "null";
+  }
+
+  leave(): void {
+    if (!this.#left) {
+      this.#left = true;
+      for (const dispose of this.#laneDisposers) dispose();
+      this.#laneDisposers = [];
+      retractRole(this.#hub, this.expectation.uuid);
+    }
+    this.driverConnection.release(this.expectation);
+  }
+}

package/src/driver/PEWDriver.ts

@@ -0,0 +1,302 @@
+import { DefaultedWeakMap } from "@here.build/collections";
+import type { PlexusAwareness } from "@here.build/plexus";
+import { action, computed, observable, toJS } from "mobx";
+
+import type { ExpectationActor } from "./ExpectationActor.js";
+import { pewConfigurationSchema, pewSecretsSchema } from "../schemas/connection.js";
+import type { AnyWorkExpectation, WorkExpectation } from "../shared/models/WorkExpectation.js";
+import { revalidationDemandOf, type RevalidationDemand } from "../shared/revalidation-demand.js";
+import type { ReadyState } from "../shared/types.js";
+
+/** Duck-typed — drivers may ship a different Zod major than this package. */
+export type ConfigurationSchema = {
+  safeParse(
+    data: unknown,
+  ):
+    | { readonly success: true; readonly data: unknown }
+    | { readonly success: false; readonly error: { readonly issues: ReadonlyArray<{ readonly message?: string }> } };
+};
+
+/** Process-local. Secrets are never a Plexus field. */
+export type ConnectionSecretsView = {
+  readonly revision?: number;
+  get(field: string): unknown | undefined;
+  /** MCP env_* enumerates deposited fields. */
+  all?(): Readonly<Record<string, unknown>> | undefined;
+  /** Hosts that persist a refreshed session (reauth) implement this. */
+  replace?(secrets: Readonly<Record<string, string>>): void;
+};
+
+const EMPTY_SECRETS: ConnectionSecretsView = { 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";
+
+/** A connection construction the driver already knows will work. */
+export type DriverOffer = {
+  readonly name: string;
+  readonly description: string;
+  readonly live: boolean;
+  readonly adoptable: boolean;
+  readonly settings: Readonly<Record<string, unknown>>;
+};
+
+/**
+ * Driver extras the orchestrator mirrors onto `spec.live`.
+ * Core process facts live on `readyState` / `error` / `offers`.
+ */
+export function extraLiveFromState(state: object): Record<string, unknown> {
+  const extra: Record<string, unknown> = {};
+  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).
+ */
+export abstract class PEWDriver<
+  E extends AnyWorkExpectation = AnyWorkExpectation,
+  C = Readonly<Record<string, unknown>>,
+> implements AsyncDisposable {
+  // ── driver side (the CLASS is the driver) ─────────────────────────────
+  static readonly pewBrand: string = 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 readonly configurationSchema: ConfigurationSchema = pewConfigurationSchema;
+
+  static readonly configurationLabel: string = "";
+
+  static configurationError(message: string): string {
+    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: unknown = {}): unknown {
+    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 readonly secretsSchema: ConfigurationSchema = pewSecretsSchema;
+
+  static secretsError(message: string): string {
+    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: unknown = {}): unknown {
+    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 readonly state: Record<string, unknown> = {};
+  /**
+   * 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 readonly offers: readonly DriverOffer[] = [];
+
+  /** Kernel-plane occupancy hub. Orchestrator assignment is own-per-class. */
+  static awareness: PlexusAwareness | undefined;
+  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(): RevalidationDemand {
+    const hub = this.awareness;
+    const name = this.driverName;
+    if (hub === undefined || name === "") return "none";
+    return revalidationDemandOf(hub, { kind: "driver", name });
+  }
+
+  // ── connection side (the INSTANCE is the connection) ──────────────────
+  @observable accessor readyState: ReadyState = null;
+  @observable accessor error: string = "";
+  /**
+   * MobX: shallow — extras (models, tools, account) are replaced wholesale.
+   * Override the accessor with a wider literal to add driver facts.
+   */
+  @observable.shallow accessor state: Record<string, unknown> = {};
+
+  @observable.ref accessor awareness: PlexusAwareness | undefined = undefined;
+
+  @computed
+  get revalidationDemand(): RevalidationDemand {
+    const hub = this.awareness;
+    if (hub === undefined) return "none";
+    return revalidationDemandOf(hub, { kind: "connection", id: this.connectionId });
+  }
+
+  constructor(
+    public readonly connectionId: string,
+    settings: unknown = {},
+    secrets: ConnectionSecretsView | Readonly<Record<string, unknown>> = EMPTY_SECRETS,
+  ) {
+    const cls = new.target as typeof PEWDriver;
+    this.settings = cls.parseConfiguration(settings) as C;
+    const view: ConnectionSecretsView =
+      typeof (secrets as ConnectionSecretsView).get === "function"
+        ? (secrets as ConnectionSecretsView)
+        : {
+            get: (field) => (secrets as Readonly<Record<string, unknown>>)[field],
+            all: () => secrets as Readonly<Record<string, unknown>>,
+          };
+    cls.parseSecrets(view.all?.() ?? {});
+    this.secrets = view;
+  }
+  readonly settings: C;
+  /** Live view. The host may replace it (reauth). */
+  secrets: ConnectionSecretsView;
+
+  /**
+   * 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: (patch: Readonly<Record<string, unknown>>) => void): void {}
+
+  abstract bootstrap(): Promise<void>;
+
+  bootstrapDone = false;
+  bootstrapPending: Promise<void> | null = null;
+  /** `resolve()` threw — the connection is broken, not the work. */
+  broken = false;
+  /** Concurrent callers share one promise. Async settlement is its own MobX action. */
+  @action
+  ensureBootstrapStarted(): Promise<void> {
+    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: unknown) => {
+        this.readyState = "failed";
+        this.error = error instanceof Error ? error.message : String(error);
+        throw error;
+      }),
+    );
+    return this.bootstrapPending;
+  }
+
+  @action
+  failReady(error: unknown): void {
+    this.broken = true;
+    this.readyState = "failed";
+    this.error = error instanceof Error ? error.message : String(error);
+  }
+
+  protected abstract resolve(expectation: E): ExpectationActor<E>;
+  /** Nothing in PEW calls this; hosts or tests may. */
+  async [Symbol.asyncDispose](): Promise<void> {}
+
+  private readonly actors = new DefaultedWeakMap<WorkExpectation, ExpectationActor<any>>((expectation: WorkExpectation): ExpectationActor<any> => {
+  const actor = this.resolve(expectation as E);
+  this.liveActors.add(actor);
+  return actor;
+});
+  private readonly liveActors = new Set<ExpectationActor<any>>();
+
+  has(expectation: WorkExpectation): boolean {
+    return this.actors.has(expectation);
+  }
+  resolveExpectation<T extends AnyWorkExpectation>(expectation: T): ExpectationActor<T> {
+    return this.actors.get(expectation);
+  }
+  release(expectation: WorkExpectation): void {
+    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: unknown): void {
+    for (const actor of this.liveActors) actor.abort(reason);
+  }
+
+  /**
+   * Honor one demand.
+   * `resolve()` throwing is a broken connection, not a failed expectation.
+   */
+  handle(expectation: WorkExpectation): void {
+    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: ExpectationActor<any>;
+    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();
+    }
+  }
+}
+
+/**
+ * A concrete `PEWDriver` subclass — constructable, not abstract.
+ * `loadDriverModule` returns `unknown`; {@link isDriverConnectionClass} is the gate.
+ */
+export type DriverConnectionClass = {
+  [K in keyof typeof PEWDriver]: (typeof PEWDriver)[K];
+} & (new (...args: ConstructorParameters<typeof PEWDriver>) => PEWDriver);
+
+export function isDriverConnectionClass(value: unknown): value is DriverConnectionClass {
+  if (typeof value !== "function") return false;
+  if ((value as { pewBrand?: unknown }).pewBrand === PEW_DRIVER_BRAND) return true;
+  return (
+    typeof (value as { prototype?: unknown }).prototype === "object" &&
+    (value as { prototype: object }).prototype instanceof PEWDriver
+  );
+}

package/src/driver/actor-machine.ts

@@ -0,0 +1,54 @@
+import { setup, 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 const expectationActorMachine = setup({
+  types: {
+    events: {} as { type: "START" | "SETTLE" | "CRASH" | "ABORT" | "RELEASE" },
+  },
+}).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" },
+  },
+});
+
+export type ActorPhase = StateValueFrom<typeof expectationActorMachine>;
+
+export type ActorPhaseEvent = EventFromLogic<typeof expectationActorMachine>;

package/src/driver/connection-miss.ts

@@ -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 {
+  readonly code: "noconnect" | "not-ready" | "needs-auth" | "connection-dropped";
+
+  constructor(code: ConnectionMiss["code"], message?: string) {
+    super(message ?? code);
+    this.name = "ConnectionMiss";
+    this.code = code;
+  }
+}

package/src/driver/index.ts

@@ -0,0 +1,5 @@
+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";

package/src/executor/index.ts

@@ -0,0 +1,3 @@
+export * from "./orchestrator.js";
+export * from "./kernel-intern.js";
+export * from "./types.js";