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

package/src/shared/models/ConnectionSpec.ts

@@ -0,0 +1,84 @@
+/**
+ * YAML connection inventory. Settings ride a private synced bag; the public
+ * face is {@link configuration} (deep-readonly get, whole-bag set).
+ * Secrets never live here. PEW process facts are `readyState` / `error`
+ * plus {@link live}. YAML file fill does not touch process facts.
+ */
+import { PlexusModel, syncing } from "@here.build/plexus";
+import { computed } from "mobx";
+
+import type { ReadyState, SpecCatalog } from "../types.js";
+import { DriverSpec } from "./DriverSpec.js";
+import { readJsonRecord, writeJsonRecord, type LiveFacts } from "./jsonRecord.js";
+
+export type ConfigurationAtom = string | number | boolean | null;
+export type ConfigurationValue =
+  | ConfigurationAtom
+  | readonly ConfigurationValue[]
+  | { readonly [key: string]: ConfigurationValue };
+export type ConnectionConfiguration = { readonly [key: string]: ConfigurationValue };
+
+@syncing("@inhuman.tools/plexus-expectations:ConnectionSpec")
+export class ConnectionSpec extends PlexusModel<SpecCatalog | null> {
+  get id(): string {
+    return (this.parentFieldKey as string | null) ?? "";
+  }
+
+  /** Only `failed` is a problem. */
+  get issue(): "failed" | false {
+    return this.readyState === "failed" ? "failed" : false;
+  }
+
+  /** YAML `driver:` resolves to this entity. */
+  @syncing accessor driver!: DriverSpec;
+  @syncing accessor name: string = "";
+  @syncing accessor annotation: string = "";
+  @syncing.record private accessor configurationMap: Record<string, string> = {};
+
+  /** PEW instance self-report. `null` = never ensured. YAML fill does not touch this. */
+  @syncing accessor readyState: ReadyState = null;
+  @syncing accessor error: string = "";
+  @syncing.record private accessor liveMap: Record<string, string> = {};
+
+  /** Frozen through; assign the whole bag to write. */
+  @computed
+  get configuration(): ConnectionConfiguration {
+    return readJsonRecord(this.configurationMap) as ConnectionConfiguration;
+  }
+
+  set configuration(settings: Readonly<Record<string, unknown>> | undefined) {
+    this.#writeConfiguration(settings);
+  }
+
+  @syncing.action
+  #writeConfiguration(settings: Readonly<Record<string, unknown>> | undefined): void {
+    writeJsonRecord(this.configurationMap, settings);
+  }
+
+  @computed
+  get live(): LiveFacts {
+    return readJsonRecord(this.liveMap) as LiveFacts;
+  }
+
+  set live(next: Readonly<Record<string, unknown>> | undefined) {
+    this.#writeLive(next);
+  }
+
+  @syncing.action
+  #writeLive(next: Readonly<Record<string, unknown>> | undefined): void {
+    writeJsonRecord(this.liveMap, next);
+  }
+
+  /** Process self-report. YAML fill does not call this. */
+  @syncing.action
+  stampProcess(next: {
+    readonly readyState: ReadyState;
+    readonly error: string;
+    readonly live: Readonly<Record<string, unknown>> | undefined;
+  }): void {
+    this.readyState = next.readyState;
+    this.error = next.error;
+    this.live = next.live;
+  }
+}
+

package/src/shared/models/DriverSpec.ts

@@ -0,0 +1,102 @@
+/**
+ * Advertised driver inventory. `can` is a plexus list — file tokens, no load required.
+ * PEW process facts are `readyState` / `error` / `offersJson` plus {@link live}.
+ * YAML file fill does not touch process facts.
+ */
+import { PlexusModel, syncing } from "@here.build/plexus";
+import { computed } from "mobx";
+import invariant from "tiny-invariant";
+
+import type { ReadyState, SpecCatalog } from "../types.js";
+import { readJsonRecord, writeJsonRecord, type LiveFacts } from "./jsonRecord.js";
+
+/** How a new connection of this driver is offered, before the class loads. */
+export type DriverMultiplicity = "add-by-default" | "add-as-secondary";
+
+@syncing("@inhuman.tools/plexus-expectations:DriverSpec")
+export class DriverSpec extends PlexusModel<SpecCatalog | null> {
+  @syncing accessor name: string = "";
+  @syncing accessor description: string = "";
+  @syncing accessor importPath: string = "";
+  /** Expectation kind names this driver handles. Not tool names. */
+  @syncing.list accessor abilityClaim: string[] = [];
+  @syncing accessor multiplicity: DriverMultiplicity = "add-as-secondary";
+
+  /** Module-load self-report. `null` = never loaded. YAML fill does not touch this. */
+  @syncing accessor readyState: ReadyState = null;
+  @syncing accessor error: string = "";
+  /** Offer list JSON. Null = no offers. */
+  @syncing private accessor offersJson: string | null = null;
+  @syncing.record private accessor liveMap: Record<string, string> = {};
+
+  @computed
+  get live(): LiveFacts {
+    return readJsonRecord(this.liveMap) as LiveFacts;
+  }
+
+  set live(next: Readonly<Record<string, unknown>> | undefined) {
+    this.#writeLive(next);
+  }
+
+  @syncing.action
+  #writeLive(next: Readonly<Record<string, unknown>> | undefined): void {
+    writeJsonRecord(this.liveMap, next);
+  }
+
+  /**
+   * Module-load self-report. Omitted `offersJson` / `live` stay
+   * (failure must not wipe a previous load).
+   */
+  @syncing.action
+  stampLoad(next: {
+    readonly readyState: ReadyState;
+    readonly error: string;
+    readonly offersJson?: string | null;
+    readonly live?: Readonly<Record<string, unknown>>;
+  }): void {
+    this.readyState = next.readyState;
+    this.error = next.error;
+    if (next.offersJson !== undefined) this.offersJson = next.offersJson;
+    if (next.live !== undefined) this.live = next.live;
+  }
+
+  /**
+   * Class-bootstrap offers. Null, blank, and the string `"null"` are no offers.
+   * A non-string cell or malformed JSON throws: a silent [] hides a driver defect.
+   */
+  @computed
+  get offers(): readonly object[] {
+    return readDriverOffers(this.offersJson);
+  }
+
+  set offers(next: readonly object[] | null) {
+    this.#writeOffers(next);
+  }
+
+  @syncing.action
+  #writeOffers(next: readonly object[] | null): void {
+    this.offersJson = next == null ? null : JSON.stringify(next);
+  }
+}
+
+export function readDriverOffers(raw: unknown): object[] {
+  if (raw == null) return [];
+  invariant(typeof raw === "string", "harness/kernel/offers: offersJson must be a JSON string");
+  const text = raw.trim();
+  if (text === "" || text === "null") return [];
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    throw new Error(
+      `harness/kernel/offers: offersJson is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  invariant(Array.isArray(parsed), "harness/kernel/offers: offersJson must be a JSON array of offer objects");
+  for (const item of parsed) {
+    invariant(typeof item === "object", "harness/kernel/offers: offersJson entries must be objects");
+    invariant(item !== null, "harness/kernel/offers: offersJson entries cannot be null");
+    invariant(!Array.isArray(item), "harness/kernel/offers: offersJson entries cannot be arrays");
+  }
+  return parsed as object[];
+}

package/src/shared/models/Job.ts

@@ -0,0 +1,192 @@
+/**
+ * COLLECTORS ARE NOT `.work`. Collectors expand until `walkBoundary`.
+ * Job is a WorkContainer, not a WorkExpectation.
+ *
+ * `orchestrationResult` is the guard's boolean. `orchestrated` is computed
+ * (`!== null`). `cancelled` is the cancel fact. Do not assign `orchestrated`.
+ *
+ * Await settles on `result`, not on this object. `result` stays null until
+ * `endedAtMs` is set, then this class fulfills `undefined`. `cancelled` alone
+ * does not settle. A subclass names its value and rejection by overriding `result`.
+ */
+import { syncing } from "@here.build/plexus";
+import { computed, when } from "mobx";
+import invariant from "tiny-invariant";
+
+import { WorkContainer } from "./WorkContainer.js";
+
+export type JobResolution<TValue, TReason> =
+  { readonly status: "fulfilled"; readonly value: TValue } | { readonly status: "rejected"; readonly reason: TReason };
+
+export type JobKind = "command" | "agent" | "bot" | "workflow";
+
+/** Runtime that owns a job's effect. */
+export type JobEffectOwner = "session-runtime" | "tool-runtime" | "scheme-runtime" | "agent-calls" | "honor";
+
+/** What a restart does with a job whose outcome it cannot see. */
+export type UnknownOutcomeRecovery = "resume-queued" | "resume-inner" | "unknown-no-replay";
+
+@syncing("@inhuman.tools/plexus-expectations:Job")
+export abstract class Job<TValue = unknown, TReason = unknown> extends WorkContainer implements Promise<TValue> {
+  #pending: Promise<TValue> | null = null;
+
+  /** Not this instantiation — a parent holds jobs with other fulfill and reject types. */
+  @syncing.child.list accessor children: Job<unknown, unknown>[] = [];
+  @syncing accessor background: boolean = false;
+  @syncing accessor walkBoundary: boolean = false;
+  /** Guard return. `null` = phase 1 not done. */
+  @syncing accessor orchestrationResult: true | false | null = null;
+  /** Cancel fact. `false → true`. Not a deny and not a human approval. */
+  @syncing accessor cancelled: boolean = false;
+  /** This job's own work has finalized (ok or not). */
+  @syncing accessor completed: boolean = false;
+  /**
+   * Crash ending: the license guard or the executor body threw. Empty means
+   * no crash. The message is the fact; the host stamps a receipt from it and
+   * the job completes, so whoever joins the job is released with an outcome.
+   */
+  @syncing accessor crash: string = "";
+  /**
+   * Ordering as data: jobs that must be released before this one is claimed
+   * (license and body). Refs to earlier siblings, never a cycle. The
+   * orchestrator honours it on every pass, so it holds across a restart.
+   */
+  @syncing.list accessor after: Job<unknown, unknown>[] = [];
+
+  /**
+   * Seal + end clock, in one update: `result` keys on `endedAtMs`, so a
+   * crash between the two writes would leave a completed job unawaitable.
+   * Deny-without-BODY leaves `startedAtMs` null.
+   */
+  @syncing.action
+  markComplete(now = Date.now()): void {
+    if (!this.completed) this.completed = true;
+    this.markEnded(now);
+  }
+
+  /** Replace {@link after}. Call before the job becomes reachable. */
+  @syncing.action
+  stampAfter(jobs: readonly Job<unknown, unknown>[]): void {
+    this.after.splice(0, this.after.length, ...jobs);
+  }
+
+  /**
+   * Released for a successor: done, cancelled, or a background job that has
+   * started. A denied or failed predecessor is done too; order is not success.
+   */
+  get released(): boolean {
+    return this.completed || this.cancelled || (this.orchestrated && this.background);
+  }
+
+  /** Every {@link after} predecessor is released. */
+  @computed
+  get afterReleased(): boolean {
+    return this.after.every((job) => job.released);
+  }
+
+  /** Parent `child` when it is not already in `children`. Does not enqueue or wait. */
+  registerJob<T extends Job<unknown, unknown>>(child: T): T {
+    if (!this.children.includes(child)) this.children.push(child);
+    return child;
+  }
+
+  @computed
+  get orchestrated(): boolean {
+    return this.orchestrationResult !== null;
+  }
+
+  /** Not one call. Agent, bot, shell, and program override. */
+  get kind(): JobKind {
+    return "workflow";
+  }
+
+  /** Not the background flag. Call, program, and shell override. */
+  get isTrackedBackground(): boolean {
+    return false;
+  }
+
+  /** Not the wire name. Call, program, and shell override. */
+  get object(): string {
+    return "";
+  }
+
+  /**
+   * Effect contract for this class. Not synced. An abstract intermediate
+   * declares none, so every concrete kind has to state its own.
+   */
+  abstract readonly owner: JobEffectOwner;
+  abstract readonly intent: string;
+  abstract readonly checkpoint: string;
+  abstract readonly dispatch: string;
+  abstract readonly settlement: string;
+  abstract readonly cancel: string;
+  abstract readonly unknownRecovery: UnknownOutcomeRecovery;
+  abstract readonly unknownNote: string;
+  abstract readonly intentRequired: boolean;
+
+  @computed
+  get jobs(): Job<unknown, unknown>[] {
+    const out: Job<unknown, unknown>[] = [];
+    for (const child of this.children) {
+      if (!(child instanceof Job)) continue;
+      out.push(child);
+      if (!child.walkBoundary) out.push(...child.jobs);
+    }
+    return out;
+  }
+
+  @computed
+  get foregroundJobs(): Job<unknown, unknown>[] {
+    return this.jobs.filter((node) => !node.background);
+  }
+
+  @computed
+  get backgroundJobs(): Job<unknown, unknown>[] {
+    return this.jobs.filter((node) => node.background);
+  }
+
+  @computed
+  get result(): JobResolution<TValue, TReason> | null {
+    if (this.endedAtMs == null) return null;
+    return { status: "fulfilled", value: undefined as TValue };
+  }
+
+  @computed
+  get work(): readonly WorkContainer[] {
+    return this.children;
+  }
+
+  then<TFulfilled = TValue, TRejected = never>(
+    onfulfilled?: ((value: TValue) => TFulfilled | PromiseLike<TFulfilled>) | null,
+    onrejected?: ((reason: TReason) => TRejected | PromiseLike<TRejected>) | null,
+  ): Promise<TFulfilled | TRejected> {
+    return this.#settled().then(onfulfilled, onrejected);
+  }
+
+  catch<TRejected = never>(
+    onrejected?: ((reason: TReason) => TRejected | PromiseLike<TRejected>) | null,
+  ): Promise<TValue | TRejected> {
+    return this.#settled().catch(onrejected);
+  }
+
+  finally(onfinally?: (() => void) | null): Promise<TValue> {
+    return this.#settled().finally(onfinally);
+  }
+
+  get [Symbol.toStringTag](): string {
+    return "Job";
+  }
+
+  #settled(): Promise<TValue> {
+    if (this.#pending != null) return this.#pending;
+    const deliver = (): TValue => {
+      const resolution = this.result;
+      invariant(resolution != null, "Job settled without result");
+      if (resolution.status === "rejected") throw resolution.reason;
+      return resolution.value;
+    };
+    this.#pending =
+      this.result != null ? Promise.resolve().then(deliver) : when(() => this.result != null).then(deliver);
+    return this.#pending;
+  }
+}

package/src/shared/models/WorkContainer.ts

@@ -0,0 +1,90 @@
+/**
+ * Work graph node. `work` may be a synced list or a computed getter.
+ * Walking `.work` from the document root is the whole out-reachable set.
+ *
+ * Brand is on this class — do not duck-type `.work`.
+ *
+ * Thenable. The fulfillment is not `this` — a thenable that resolves to itself
+ * never settles. This class settles when `endedAtMs` is set, fulfills
+ * `undefined`, and does not reject. {@link WorkExpectation} fulfills its
+ * outcome. {@link Job} fulfills or rejects from `result`. The promise value
+ * here is `unknown` so both stay containers.
+ */
+import { PlexusModel, syncing } from "@here.build/plexus";
+import { when } from "mobx";
+
+export const workContainer: unique symbol = Symbol.for("work:container") as never;
+
+/** Base promise value. An expectation narrows it to the outcome; a job narrows it per class. */
+export type WorkFulfillment = unknown;
+
+@syncing("@inhuman.tools/plexus-expectations:WorkContainer")
+export abstract class WorkContainer extends PlexusModel implements Promise<WorkFulfillment> {
+  readonly [workContainer] = true as const;
+  #settledPromise: Promise<WorkFulfillment> | null = null;
+
+  /** Epoch ms. Write-once. BODY / actor start — not mint, not the guard. */
+  @syncing accessor startedAtMs: number | null = null;
+  /** Epoch ms. Write-once. Job complete / PEW succeed|fail. This class's thenable settles on this. */
+  @syncing accessor endedAtMs: number | null = null;
+
+  abstract readonly work: readonly WorkContainer[];
+
+  markStarted(now = Date.now()): void {
+    if (this.startedAtMs != null) return;
+    this.startedAtMs = now;
+  }
+
+  markEnded(now = Date.now()): void {
+    if (this.endedAtMs != null) return;
+    this.endedAtMs = now;
+  }
+
+  /** Live: `now - startedAtMs`. Sealed: `endedAtMs - startedAtMs`. Null if start was never stamped. */
+  durationMs(now = Date.now()): number | null {
+    if (this.startedAtMs == null || !Number.isFinite(this.startedAtMs)) return null;
+    const end =
+      this.endedAtMs != null && Number.isFinite(this.endedAtMs) ? this.endedAtMs : now;
+    return Math.max(0, end - this.startedAtMs);
+  }
+
+  then<TFulfilled = WorkFulfillment, TRejected = never>(
+    onfulfilled?: ((value: WorkFulfillment) => TFulfilled | PromiseLike<TFulfilled>) | null,
+    onrejected?: ((reason: unknown) => TRejected | PromiseLike<TRejected>) | null,
+  ): Promise<TFulfilled | TRejected> {
+    return this.#settled().then(onfulfilled, onrejected);
+  }
+
+  catch<TRejected = never>(
+    onrejected?: ((reason: unknown) => TRejected | PromiseLike<TRejected>) | null,
+  ): Promise<WorkFulfillment | TRejected> {
+    return this.#settled().catch(onrejected);
+  }
+
+  finally(onfinally?: (() => void) | null): Promise<WorkFulfillment> {
+    return this.#settled().finally(onfinally);
+  }
+
+  get [Symbol.toStringTag](): string {
+    return "WorkContainer";
+  }
+
+  #settled(): Promise<WorkFulfillment> {
+    if (this.#settledPromise != null) return this.#settledPromise;
+    const fulfill = (): WorkFulfillment => undefined;
+    this.#settledPromise =
+      this.endedAtMs != null ? Promise.resolve(fulfill()) : when(() => this.endedAtMs != null).then(fulfill);
+    return this.#settledPromise;
+  }
+}
+
+/** Preorder walk of `.work`, cycle-safe. `item === container` stops a leaf `[this]` from recursing. */
+export function* walkWork(container: WorkContainer, seen: Set<WorkContainer> = new Set()): Generator<WorkContainer> {
+  for (const item of container.work) {
+    if (seen.has(item)) continue;
+    seen.add(item);
+    yield item;
+    if (item === container) continue;
+    yield* walkWork(item, seen);
+  }
+}

package/src/shared/models/WorkExpectation.ts

@@ -0,0 +1,229 @@
+import { type PlexusAwareness, syncing } from "@here.build/plexus";
+import { docPlexus } from "@here.build/plexus/internals";
+import { comparer, computed, observable, reaction, when } from "mobx";
+import invariant from "tiny-invariant";
+
+import { type EndCause, type ExpectationOutcome } from "../control.js";
+import { roleOf } from "../role.js";
+import type { SessionAwareness, SessionPlexus } from "../types.js";
+import { Job } from "./Job.js";
+import { WorkContainer } from "./WorkContainer.js";
+
+/**
+ * Awareness: empty string occupies the role map without a report frame.
+ * Retract drops the uuid. Not a durable outcome.
+ */
+export const ROLE_LANE_OCCUPIED = "";
+
+@syncing("@inhuman.tools/plexus-expectations:WorkExpectation")
+export abstract class WorkExpectation<TResult = unknown, TReport = unknown>
+  extends WorkContainer
+  implements Promise<ExpectationOutcome>
+{
+  /**
+   * Kernel catalog key this work rides. Required at construction.
+   * Plexus materialization passes a symbol through unchanged.
+   */
+  @syncing
+  accessor connectionId!: string;
+
+  constructor(init: { readonly connectionId: string } | symbol) {
+    if (typeof init !== "symbol") {
+      invariant(
+        typeof init.connectionId === "string" && init.connectionId !== "",
+        "WorkExpectation.connectionId is required",
+      );
+    }
+    super(init);
+  }
+
+  @syncing
+  accessor outcome: ExpectationOutcome | null = null;
+
+  @syncing
+  accessor endCause: EndCause | null = null;
+
+  @syncing
+  accessor endDetail: string | null = null;
+
+  /** Durable last frame as JSON. `"null"` when the work ended without a report. */
+  @syncing
+  accessor outcomeReport: string | null = null;
+
+  /** Last live role-map frame this process saw. Retract does not clear it. */
+  @observable.ref private accessor lastProgress: TReport | null = null;
+  #progressCacheStarted = false;
+  #settledPromise: Promise<ExpectationOutcome> | null = null;
+
+  get plexus(): SessionPlexus | null {
+    const doc = this.__doc__;
+    if (!doc) return null;
+    const plexus = docPlexus.get(doc);
+    if (!plexus) return null;
+    return plexus as SessionPlexus;
+  }
+
+  get awareness(): PlexusAwareness<SessionAwareness> | null {
+    const hub = this.plexus?.awareness ?? null;
+    if (hub != null) this.#ensureProgressCache();
+    return hub;
+  }
+
+  // MobX: arm on the first `awareness` read so a later untracked read still
+  // sees the last frame. Dispose on done — a sealed lane is frozen; do not
+  // keep a reaction per expectation for the life of the document.
+  #ensureProgressCache(): void {
+    if (this.#progressCacheStarted) return;
+    this.#progressCacheStarted = true;
+    reaction(
+      () => ({ done: this.isDone, frame: this.#liveProgressFrame() }),
+      ({ done, frame }, _previous, self) => {
+        if (frame !== null) this.lastProgress = frame;
+        if (done) self.dispose();
+      },
+      { fireImmediately: true, equals: comparer.structural },
+    );
+  }
+
+  #liveProgressFrame(): TReport | null {
+    const hub = this.awareness;
+    if (hub == null) return null;
+    const frame = roleOf(hub, this.uuid);
+    if (frame == null || frame === ROLE_LANE_OCCUPIED) return null;
+    return frame as TReport;
+  }
+
+  /** Live progress as the fulfiller tells it. Awareness retract does not drop the last frame. */
+  @computed
+  get progressAwareness(): TReport | null {
+    return this.#liveProgressFrame() ?? this.lastProgress;
+  }
+
+  /** Occupancy on the role map. Not a durable outcome. */
+  @computed
+  get workerPresent(): boolean {
+    const hub = this.awareness;
+    if (hub == null) return false;
+    const value = roleOf(hub, this.uuid);
+    return value !== undefined && value !== null;
+  }
+
+  get isDone(): boolean {
+    return this.outcome != null;
+  }
+
+  /** Leaf. PEW does not parent PEW. */
+  get work(): readonly WorkExpectation[] {
+    return [this];
+  }
+
+  /**
+   * Settles when {@link isDone}. Fulfills with {@link outcome} for both
+   * `successful` and `failed` — failure is an outcome, not a rejection.
+   * The fulfillment cannot be `this`: a thenable that resolves to itself
+   * never settles (Promise unwraps `then` forever).
+   */
+  then<TFulfilled = ExpectationOutcome, TRejected = never>(
+    onfulfilled?: ((value: ExpectationOutcome) => TFulfilled | PromiseLike<TFulfilled>) | null,
+    onrejected?: ((reason: unknown) => TRejected | PromiseLike<TRejected>) | null,
+  ): Promise<TFulfilled | TRejected> {
+    return this.#settled().then(onfulfilled, onrejected);
+  }
+
+  catch<TRejected = never>(
+    onrejected?: ((reason: unknown) => TRejected | PromiseLike<TRejected>) | null,
+  ): Promise<ExpectationOutcome | TRejected> {
+    return this.#settled().catch(onrejected);
+  }
+
+  finally(onfinally?: (() => void) | null): Promise<ExpectationOutcome> {
+    return this.#settled().finally(onfinally);
+  }
+
+  get [Symbol.toStringTag](): string {
+    return "WorkExpectation";
+  }
+
+  #settled(): Promise<ExpectationOutcome> {
+    if (this.#settledPromise != null) return this.#settledPromise;
+    this.#settledPromise = this.isDone
+      ? Promise.resolve(this.#sealedOutcome())
+      : when(() => this.isDone).then(() => this.#sealedOutcome());
+    return this.#settledPromise;
+  }
+
+  #sealedOutcome(): ExpectationOutcome {
+    invariant(this.outcome != null, "WorkExpectation settled without outcome");
+    return this.outcome;
+  }
+
+  applySettlement(_result: TResult): void {}
+
+  #parseOutcomeReport(): TReport | null {
+    if (this.outcomeReport == null) return null;
+    try {
+      return JSON.parse(this.outcomeReport) as TReport | null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Durable outcome frame if written, else last progress seen.
+   * {@link ROLE_LANE_OCCUPIED} is not a frame. Retract keeps the last frame.
+   */
+  @computed
+  get report(): TReport | null {
+    if (this.outcomeReport != null) return this.#parseOutcomeReport();
+    return this.progressAwareness;
+  }
+
+  @syncing.action
+  succeed(cause: EndCause, detail: string, outcomeReport: string, settlement?: { readonly result: TResult }): boolean {
+    if (this.isDone) return false;
+    if (settlement !== undefined) {
+      try {
+        this.applySettlement(settlement.result);
+      } catch (error) {
+        this.outcome = "failed";
+        this.endCause = cause;
+        this.endDetail = `apply_error: ${String(error)}`;
+        this.outcomeReport = outcomeReport;
+        this.markEnded();
+        return true;
+      }
+    }
+    this.outcome = "successful";
+    this.endCause = cause;
+    this.endDetail = detail;
+    this.outcomeReport = outcomeReport;
+    this.markEnded();
+    return true;
+  }
+
+  @syncing.action
+  fail(cause: EndCause, detail: string, outcomeReport: string): boolean {
+    if (this.isDone) return false;
+    this.outcome = "failed";
+    this.endCause = cause;
+    this.endDetail = detail;
+    this.outcomeReport = outcomeReport;
+    this.markEnded();
+    return true;
+  }
+}
+
+/** Open work whose parent sealed — honor does not start these. */
+export function isTreeOrphan(node: WorkExpectation): boolean {
+  if (node.isDone) return false;
+  const parent = node.parent;
+  if (parent === null) return false;
+  if (parent instanceof WorkExpectation) return parent.isDone;
+  if (parent instanceof Job) return parent.completed;
+  return false;
+}
+
+/** Admits every WorkExpectation instantiation. */
+export type AnyWorkExpectation = WorkExpectation<any, any>;
+export type ResultOf<E extends AnyWorkExpectation> = Parameters<E["applySettlement"]>[0];
+export type ReportOf<E extends AnyWorkExpectation> = Exclude<E["report"], null>;