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

package/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright 2026 Merkle Bonsai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,145 @@
-# Temporary Holding Version
+# PEW — Plexus Expectation Workflow
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Package:** `@inhuman.tools/plexus-expectations`
+
+Durable work on Plexus documents. One noun for open work — **Expectation** (harness docs: **PEW/Expectation**) — demand with an
+outcome. The entity itself is the whole API: the claim-owner host writes PEW/Expectation bodies (Client queues the named action);
+observers read it; Actors honor it; the process holding the live PEW/Connection starts or declines it.
+
+This README is the contract.
+
+---
+
+## Three entry points, three roles
+
+| Import                               | Role                                                                            | Contents                                                                                                                   |
+| ------------------------------------ | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `@inhuman.tools/plexus-expectations` | **Vocabulary** — any process holding the doc (claim-owner host, observers, UIs) | `WorkExpectation`, `Job`, `WorkContainer`, `ConnectionSpec`, `DriverSpec`, outcome type |
+| `…/driver`                           | **Fulfillment** — PEW/Driver packages                                           | `PEWDriver`, `ExpectationActor`, bootstrap contexts                                                              |
+| `…/executor`                         | **Supervision** — the process that has the live connections                     | `Orchestrator` (PEW honor + Job executors; plus everything in `/driver`)                                                   |
+
+Observers and claim-owner hosts never import `/executor`; driver packages never need it either.
+
+---
+
+## The entity is the API
+
+Live `report` is the scan; settlement is the `outcome` / `outcomeReport` write on the entity; the next read is instant.
+
+Everything scoped to a unit of work lives on the `Expectation` model — there is no client
+object, no session parameter, and a cross-session mistake is unrepresentable (the entity locates
+its own document, plexus, and PEW/Awareness):
+
+| Face                                      | Surface                                                                                                                                                                                                                                                                                                               |
+| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Author** (claim-owner host, not Client) | `new Kind({ …fields })` — the subclass fields ARE the request                                                                                                                                                                               |
+| **Observer**                              | `await E` (settles with `"successful"` / `"failed"` when `isDone`; `failed` fulfills), `E.outcome` (`null` / `successful` / `failed`), `E.workerPresent`, `E.report` (outcome frame or live awareness), `E.endCause` / `E.endDetail`; catalog liveness is process-local on the spec entities' `.readyState` / `.live` |
+| **Actor**                                 | `this.expectation` (the request), `this.signal`, `admitTermination()`, `report()` / `complete()` / `fail()`; `ConnectionNotReady` / `DemandIncomplete` from `run()` settle fail, not crash                                                                                                                                                                        |
+| **Connection**                            | leftover attach PEW is honored; new work is kicked from origin (`complete` / Job BODY interned methods); catalog drivers load themselves; `PEWDriver.handle` remains the leftover door                                                                                                                                                                                                           |
+
+Role occupancy is one `role:expectations` map keyed by uuid. A role write requires a
+doc-homed entity — occupancy not propagated over awareness is no occupancy, so
+touching the role map on an unhomed entity throws loudly rather than publishing
+into the void.
+
+### Outcome
+
+```text
+null        = not done
+successful  = done as expected
+failed      = done otherwise (error, crash, cancel)
+```
+
+There is no expectation state machine and no durable `running`. "Someone is working
+to satisfy this" is actor presence (`workerPresent` / the role map), gone when the
+teller goes. Last progress this process saw stays on `progressAwareness` after the
+uuid retracts. The writers `succeed` / `fail` are first-writer-wins (`fail` with
+`endCause: cancel` is how cancel is recorded). `connection` on the expectation and
+`driver` on the connection are required — a missing field is a host bug, not an
+outcome. Every ending carries `endCause` (`settled` | `cancel` | `crash`) and
+`outcomeReport`.
+
+Cancel is host-owned: `admitTermination()` on a live actor, or `fail("cancel", …)` when
+nobody is working. No acks, no epochs, no kernel hop.
+
+### Endings are observed, never imposed
+
+There is no fold. Endings are `succeed` / `fail` writes — the actor on its own settlement,
+or host `admitTermination` (a settlement captured before admission outranks the cancel).
+The actor keeps one reaction on its entity's `isDone`: however the ending arrived — local
+settlement, admitted cancel, a peer's write — the process duties are identical: abort the
+signal, leave. Children of a done parent are skipped by honor (`isTreeOrphan`), not ended
+by a cascade from the parent's stack frame.
+
+---
+
+## Extending: kinds and drivers
+
+**Work vocabulary is global.** A product ships `Expectation` subclasses; the `@syncing` registry
+tag IS the kind — derived, never declared. The subclass is the single type carrier:
+
+```ts
+@syncing("myapp:tool_call")
+class ToolCallExpectation extends Expectation<ToolResult, ToolReport> {
+  @syncing accessor name = "";
+  @syncing accessor argsJson = "{}";
+
+  override applySettlement(result: ToolResult): void {
+    /* typed product-field writes */
+  }
+}
+```
+
+`ResultOf` / `ReportOf` extract the shapes.
+
+**PEW/Driver is claim, not invent — and the claim lives on the catalog, never on code.**
+`DriverSpec.can: string[]` is the durable claim surface ("this driver handles these
+kinds") — expectation model names, elevated through the process-global `@syncing` class registry.
+Dynamically loaded driver code does not get to declare its own authority.
+
+**The loaded class is `PEWDriver`. The instance is the connection.** `DriverSpec` and `ConnectionSpec` stay the inventory rows. A driver module's default export is
+a `PEWDriver` subclass: the static side is code identity (`pewBrand`, `offers`),
+each instance is one live connection (its own gated `bootstrap()`), and `resolve(expectation)`
+mints the actor — which may be a connection-specialized `ExpectationActor` subclass holding the
+live runtime directly:
+
+```ts
+export default class MyDriverConnection extends PEWDriver<ToolCallExpectation> {
+  static override configurationSchema = z.object({ token: z.string() });
+  static offers = [];
+
+  override async bootstrap() {
+    /* per-connection load */
+  }
+  protected override resolve(expectation: ToolCallExpectation) {
+    return new MyActor(expectation, this /* live runtime */);
+  }
+}
+```
+
+Process facts are `readyState` / `error` / `offers`. Driver extras live on `state`
+(`@observable.shallow override accessor state = { … }`); the orchestrator mirrors
+them onto `spec.live`. Clients render. A concrete class that should not share the
+base extras object declares its own `static state`. Reporting only (no machinery
+branches on it; instance bootstrap truth is the gate); `ensureBootstrapStarted` /
+`failReady` write the token and siblings.
+
+Settings enter through `configurationSchema` (Zod), secrets through
+`secretsSchema`. The constructor takes them as separate arguments;
+`parseConfiguration` / `parseSecrets` are the same doors without `new`.
+The live `secrets` view may be replaced after construct (reauth).
+
+Bootstrap contexts stay minimal (`{signal, secrets}`); a host hands drivers more by extending
+the context object structurally — there is no ports registry.
+
+**The seam.** `Orchestrator` is the boundary between the plexus plane and execution: it notices
+open work, maps the expectation's connection to a catalog row ensures the row's driver class and connection instance
+(memoized; a rejected memo IS the sticky failure), and hands the expectation to
+`connection.handle` — where
+everything about executing it lives. Mint is not a claim: `resolve()` throwing
+breaks the connection (the work stays unspawned). The actor machine still
+requires `START` before `run()`; that is process-local, not a durable claim.
+
+## License
+
+[MIT](./LICENSE.md).

package/dist/driver/ExpectationActor.d.ts

@@ -0,0 +1,56 @@
+import { ErrorWithInvariant } from "@inhuman.tools/error-with-invariant";
+import type { PEWDriver } from "./PEWDriver.js";
+import type { Settlement } from "../executor/types.js";
+import { type AnyWorkExpectation, type ReportOf, type ResultOf } from "../shared/models/WorkExpectation.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 declare abstract class ExpectationInvariant extends ErrorWithInvariant {
+    name: string;
+    constructor(message: string);
+}
+/** Honor started; the fulfiller is not live. */
+export declare class ConnectionNotReady extends ExpectationInvariant {
+    readonly connection: string;
+    constructor(connection: string);
+}
+/** Required field missing on the expectation body. */
+export declare class DemandIncomplete extends ExpectationInvariant {
+    readonly field: string;
+    constructor(field: string);
+}
+/**
+ * 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 declare abstract class ExpectationActor<E extends AnyWorkExpectation = AnyWorkExpectation> {
+    #private;
+    readonly expectation: E;
+    readonly driverConnection: PEWDriver<E>;
+    readonly signal: AbortSignal;
+    readonly settled: Promise<Settlement<ResultOf<E>>>;
+    constructor(expectation: E, driverConnection: PEWDriver<E>);
+    get started(): boolean;
+    get done(): boolean;
+    start(): void;
+    protected abstract run(): void | Promise<void>;
+    abort(reason?: unknown): void;
+    protected report(frame: ReportOf<E>): void;
+    protected complete(result: ResultOf<E>): void;
+    protected fail(reason: unknown): void;
+    /** Host cancel. A settlement captured while running outranks the cancel. */
+    admitTermination(): void;
+    leave(): void;
+}
+//# sourceMappingURL=ExpectationActor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ExpectationActor.d.ts","sourceRoot":"","sources":["../../src/driver/ExpectationActor.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AAMzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,QAAQ,EACb,KAAK,QAAQ,EAEd,MAAM,qCAAqC,CAAC;AAG7C;;;;;;GAMG;AACH,8BAAsB,oBAAqB,SAAQ,kBAAkB;IAC1D,IAAI,SAAyB;gBAE1B,OAAO,EAAE,MAAM;CAG5B;AAED,gDAAgD;AAChD,qBAAa,kBAAmB,SAAQ,oBAAoB;IAC9C,QAAQ,CAAC,UAAU,EAAE,MAAM;gBAAlB,UAAU,EAAE,MAAM;CAGxC;AAED,sDAAsD;AACtD,qBAAa,gBAAiB,SAAQ,oBAAoB;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM;gBAAb,KAAK,EAAE,MAAM;CAGnC;AAED;;;;;;;;;;GAUG;AACH,8BAAsB,gBAAgB,CAAC,CAAC,SAAS,kBAAkB,GAAG,kBAAkB;;aAcpE,WAAW,EAAE,CAAC;aACd,gBAAgB,EAAE,SAAS,CAAC,CAAC,CAAC;IAZhD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAA2B;IAKvD,SAAgB,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;gBAMxC,WAAW,EAAE,CAAC,EACd,gBAAgB,EAAE,SAAS,CAAC,CAAC,CAAC;IAgChD,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,IAAI,IAAI,IAAI,OAAO,CAElB;IAED,KAAK,IAAI,IAAI;IAsCb,SAAS,CAAC,QAAQ,CAAC,GAAG,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAE9C,KAAK,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI;IAI7B,SAAS,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI;IAa1C,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI;IAI7C,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;IAmDrC,4EAA4E;IAC5E,gBAAgB,IAAI,IAAI;IAQxB,KAAK,IAAI,IAAI;CASd"}

package/dist/driver/ExpectationActor.js

@@ -0,0 +1,210 @@
+import { ErrorWithInvariant } from "@inhuman.tools/error-with-invariant";
+import { reaction, runInAction } from "mobx";
+import invariant from "tiny-invariant";
+import { createActor } from "xstate";
+import { expectationActorMachine } from "./actor-machine.js";
+import { 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 class ExpectationInvariant extends ErrorWithInvariant {
+    name = this.constructor.name;
+    constructor(message) {
+        super(message);
+    }
+}
+/** Honor started; the fulfiller is not live. */
+export class ConnectionNotReady extends ExpectationInvariant {
+    connection;
+    constructor(connection) {
+        super(`${connection} connection not ready`);
+        this.connection = connection;
+    }
+}
+/** Required field missing on the expectation body. */
+export class DemandIncomplete extends ExpectationInvariant {
+    field;
+    constructor(field) {
+        super(`demand missing ${field}`);
+        this.field = 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 class ExpectationActor {
+    expectation;
+    driverConnection;
+    #hub;
+    #controller = new AbortController();
+    signal = this.#controller.signal;
+    #lastReportJson = null;
+    #settlement = null;
+    #resolveSettled;
+    #rejectSettled;
+    settled;
+    #phase = createActor(expectationActorMachine).start();
+    #laneDisposers = [];
+    #left = false;
+    constructor(expectation, driverConnection) {
+        this.expectation = expectation;
+        this.driverConnection = driverConnection;
+        this.settled = new Promise((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;
+        this.#laneDisposers.push(reaction(() => this.expectation.isDone, (done) => {
+            if (!done)
+                return;
+            this.abort("done");
+            this.#send("RELEASE");
+            this.leave();
+        }, { fireImmediately: true }));
+    }
+    get started() {
+        return !this.#phase.getSnapshot().can({ type: "START" });
+    }
+    get done() {
+        return this.#phase.getSnapshot().status === "done";
+    }
+    start() {
+        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.then === "function") {
+                result.catch((error) => this.#onRunError(error));
+            }
+        }
+        catch (error) {
+            this.#onRunError(error);
+        }
+    }
+    #onRunError(error) {
+        if (error instanceof ExpectationInvariant) {
+            this.fail(error);
+            return;
+        }
+        this.#crash(error);
+    }
+    #matches(phase) {
+        return this.#phase.getSnapshot().matches(phase);
+    }
+    #send(type) {
+        if (!this.#phase.getSnapshot().can({ type }))
+            return;
+        this.#phase.send({ type });
+    }
+    #occupyRoleLane() {
+        reportRole(this.#hub, this.expectation.uuid, ROLE_LANE_OCCUPIED);
+    }
+    abort(reason) {
+        this.#controller.abort(reason);
+    }
+    report(frame) {
+        if (!this.#matches("running"))
+            return;
+        let json;
+        try {
+            json = JSON.stringify(frame ?? null);
+        }
+        catch (error) {
+            this.#crash(error);
+            return;
+        }
+        this.#lastReportJson = json;
+        reportRole(this.#hub, this.expectation.uuid, JSON.parse(json));
+    }
+    complete(result) {
+        this.#settle({ outcome: "complete", result });
+    }
+    fail(reason) {
+        this.#settle({ outcome: "fail", reason });
+    }
+    #settle(settlement) {
+        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) {
+        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, wasRunning, crashDetail) {
+        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() {
+        this.#commitEnding("cancel", this.#matches("running"));
+    }
+    #frameJson() {
+        return this.#lastReportJson ?? "null";
+    }
+    leave() {
+        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);
+    }
+}
+//# sourceMappingURL=ExpectationActor.js.map

package/dist/driver/ExpectationActor.js.map

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

package/dist/driver/PEWDriver.d.ts

@@ -0,0 +1,144 @@
+import type { PlexusAwareness } from "@here.build/plexus";
+import type { ExpectationActor } from "./ExpectationActor.js";
+import type { AnyWorkExpectation, WorkExpectation } from "../shared/models/WorkExpectation.js";
+import { 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;
+};
+/** Module-graph duplication breaks instanceof; the elevation gate checks this brand too. */
+export declare 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 declare function extraLiveFromState(state: object): Record<string, unknown>;
+/**
+ * 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 declare abstract class PEWDriver<E extends AnyWorkExpectation = AnyWorkExpectation, C = Readonly<Record<string, unknown>>> implements AsyncDisposable {
+    readonly connectionId: string;
+    static readonly pewBrand: string;
+    /**
+     * 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;
+    static readonly configurationLabel: string;
+    static configurationError(message: string): string;
+    /** YAML settings door. Does not construct an instance. */
+    static parseConfiguration(settings?: unknown): unknown;
+    static readonly secretsSchema: ConfigurationSchema;
+    static secretsError(message: string): string;
+    /** YAML secrets door. Does not construct an instance. */
+    static parseSecrets(secrets?: unknown): unknown;
+    /** 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: string;
+    /**
+     * A getter, not `@computed` — MobX: the decorator's initializer pins to the
+     * declaring class, so subclasses would share one computed.
+     */
+    static get revalidationDemand(): RevalidationDemand;
+    accessor readyState: ReadyState;
+    accessor error: string;
+    /**
+     * MobX: shallow — extras (models, tools, account) are replaced wholesale.
+     * Override the accessor with a wider literal to add driver facts.
+     */
+    accessor state: Record<string, unknown>;
+    accessor awareness: PlexusAwareness | undefined;
+    get revalidationDemand(): RevalidationDemand;
+    constructor(connectionId: string, settings?: unknown, secrets?: ConnectionSecretsView | Readonly<Record<string, unknown>>);
+    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: boolean;
+    bootstrapPending: Promise<void> | null;
+    /** `resolve()` threw — the connection is broken, not the work. */
+    broken: boolean;
+    /** Concurrent callers share one promise. Async settlement is its own MobX action. */
+    ensureBootstrapStarted(): Promise<void>;
+    failReady(error: unknown): void;
+    protected abstract resolve(expectation: E): ExpectationActor<E>;
+    /** Nothing in PEW calls this; hosts or tests may. */
+    [Symbol.asyncDispose](): Promise<void>;
+    private readonly actors;
+    private readonly liveActors;
+    has(expectation: WorkExpectation): boolean;
+    resolveExpectation<T extends AnyWorkExpectation>(expectation: T): ExpectationActor<T>;
+    release(expectation: WorkExpectation): void;
+    /**
+     * Logout/drop aborts interned work. Not park. Subclasses abort `#inflight`.
+     */
+    abortOnDrop(reason: unknown): void;
+    /**
+     * Honor one demand.
+     * `resolve()` throwing is a broken connection, not a failed expectation.
+     */
+    handle(expectation: WorkExpectation): void;
+}
+/**
+ * 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 declare function isDriverConnectionClass(value: unknown): value is DriverConnectionClass;
+//# sourceMappingURL=PEWDriver.d.ts.map

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

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