@milaboratories/pl-middle-layer 1.74.19 → 1.76.0

package/src/middle_layer/block_action_context.ts

@@ -0,0 +1,162 @@
+import type {
+  KeyValueString,
+  OptionalSignedResourceId,
+  SignedResourceId,
+} from "@milaboratories/pl-client";
+import { isNullSignedResourceId, parseSignedResourceId } from "@milaboratories/pl-client";
+import { projectFieldName } from "../model/project_model";
+
+/** Which render of a block the action context tree belongs to. */
+export type BlockActionContextMode = "prod" | "staging";
+
+/** An action transition: transition/<namespace>/<resource>/<ns> in an action context. */
+export type BlockActionTransition = {
+  namespace: string;
+  /** The resource that reported, e.g. the render or a command it created. */
+  resource: string;
+  /** Server clock in nanoseconds when the transition was recorded, as a decimal string. */
+  timestampNs: string;
+  state: string;
+  detail: string;
+  reason: string;
+};
+
+/**
+ * A reading: reading/<namespace>/<resource>/<key> in an action context. The backend sets it asynchronously:
+ * of two readings of one key, the one from the transaction opened later stays.
+ */
+export type BlockActionReading = {
+  namespace: string;
+  resource: string;
+  key: string;
+  /** Opaque bytes as UTF-8 text; the reporter owns the format. */
+  value: string;
+};
+
+/** One action context: the action context of one render and the renders it created. */
+export type BlockActionContextNode = {
+  /**
+   * Global resource ID of this ActionContext resource itself, as a decimal string. Not the ID of the
+   * render it describes: that is {@link BlockActionContextNode.resource}. Pass it back to the MCP
+   * tool to fetch this node's subtree.
+   */
+  contextId: string;
+  /**
+   * The render the context belongs to: the resource of its first transition under namespace "render",
+   * which the workflow controller records when it evaluates the render.
+   * Undefined until that transition is applied, or on a backend without block action context reports.
+   */
+  resource?: string;
+  /** Context baggage: name, block-pack, block-id, run-id and so on. */
+  baggage: Record<string, string>;
+  /** In time order. */
+  transitions: BlockActionTransition[];
+  readings: BlockActionReading[];
+  children: BlockActionContextNode[];
+};
+
+const childFieldPrefix = "child/";
+
+/**
+ * Reads the action context tree of a block render: the root action context the project holds in
+ * <blockId>-prodActionContext or <blockId>-stagingActionContext, and every child context under it.
+ * Reads the current state in one transaction; it does not watch for changes.
+ *
+ * @returns undefined when the block has no action context: it was not rendered yet, or the backend
+ *          does not support block action context.
+ */
+/**
+ * The part of a read transaction the reader uses: a {@link PlTransaction} satisfies it, and a test
+ * can serve it without a backend.
+ */
+export interface ActionContextReadTx {
+  getResourceData(
+    rId: SignedResourceId,
+    loadFields: true,
+  ): Promise<{
+    readonly data?: Uint8Array;
+    readonly fields: readonly { readonly name: string; readonly value: OptionalSignedResourceId }[];
+  }>;
+  listKeyValuesString(rId: SignedResourceId): Promise<KeyValueString[]>;
+}
+
+/** The part of a client the reader uses: a {@link PlClient} satisfies it. */
+export interface ActionContextReader {
+  withReadTx<T>(name: string, body: (tx: ActionContextReadTx) => Promise<T>): Promise<T>;
+}
+
+export async function readBlockActionContextTree(
+  pl: ActionContextReader,
+  projectRid: SignedResourceId,
+  blockId: string,
+  mode: BlockActionContextMode,
+): Promise<BlockActionContextNode | undefined> {
+  return await pl.withReadTx("readBlockActionContextTree", async (tx) => {
+    const project = await tx.getResourceData(projectRid, true);
+    const fieldName = projectFieldName(
+      blockId,
+      mode === "prod" ? "prodActionContext" : "stagingActionContext",
+    );
+    const actionContextField = project.fields.find((f) => f.name === fieldName);
+    if (actionContextField === undefined || isNullSignedResourceId(actionContextField.value))
+      return undefined;
+
+    return await readActionContextNode(tx, actionContextField.value);
+  });
+}
+
+async function readActionContextNode(
+  tx: ActionContextReadTx,
+  contextRef: SignedResourceId,
+): Promise<BlockActionContextNode> {
+  const [context, kvs] = await Promise.all([
+    tx.getResourceData(contextRef, true),
+    tx.listKeyValuesString(contextRef),
+  ]);
+
+  const baggage =
+    context.data === undefined || context.data.length === 0
+      ? {}
+      : (JSON.parse(Buffer.from(context.data).toString()) as Record<string, string>);
+
+  const transitions: BlockActionTransition[] = [];
+  const readings: BlockActionReading[] = [];
+  for (const { key, value } of kvs) {
+    const parts = key.split("/");
+    if (parts[0] === "transition" && parts.length === 4) {
+      const parsed = JSON.parse(value) as { state?: string; detail?: string; reason?: string };
+      transitions.push({
+        namespace: parts[1],
+        resource: parts[2],
+        timestampNs: parts[3],
+        state: parsed.state ?? "",
+        detail: parsed.detail ?? "",
+        reason: parsed.reason ?? "",
+      });
+    } else if (parts[0] === "reading" && parts.length === 4) {
+      readings.push({ namespace: parts[1], resource: parts[2], key: parts[3], value });
+    }
+  }
+  transitions.sort((a, b) => compareDecimal(a.timestampNs, b.timestampNs));
+
+  const childRefs: SignedResourceId[] = [];
+  for (const f of context.fields) {
+    if (f.name.startsWith(childFieldPrefix) && !isNullSignedResourceId(f.value))
+      childRefs.push(f.value);
+  }
+  const children = await Promise.all(childRefs.map((ref) => readActionContextNode(tx, ref)));
+
+  return {
+    contextId: String(parseSignedResourceId(contextRef).globalId),
+    resource: transitions.find((t) => t.namespace === "render")?.resource,
+    baggage,
+    transitions,
+    readings,
+    children,
+  };
+}
+
+/** Compares non-negative decimal integers given as strings. */
+function compareDecimal(a: string, b: string): number {
+  return a.length !== b.length ? a.length - b.length : a < b ? -1 : a > b ? 1 : 0;
+}

package/src/middle_layer/column_links.test.ts

@@ -0,0 +1,350 @@
+import {
+  Annotation,
+  createColumnValueId,
+  createGlobalPObjectId,
+  type PColumnSpec,
+  type ColumnLink,
+} from "@milaboratories/pl-model-common";
+import type { PlTreeState } from "@milaboratories/pl-tree";
+import { mapValues } from "es-toolkit";
+import { getQuickJS } from "quickjs-emscripten";
+import { beforeAll, describe, expect, test } from "vitest";
+import { ProjectHelper } from "../model/project_helper";
+import { FakeProject } from "../test/fake_project";
+import {
+  blockDependencies,
+  blockDependents,
+  labelBlockColumnLinks,
+  type ColumnLinksEnv,
+} from "./column_links";
+
+let env: ColumnLinksEnv;
+
+beforeAll(async () => {
+  const projectHelper = new ProjectHelper(await getQuickJS());
+  env = { projectHelper, logger: projectHelper.logger };
+});
+
+const condition = createGlobalPObjectId("samples", "condition");
+const pick = (value: string, column = condition) => createColumnValueId({ column, value });
+
+describe("blockDependencies and blockDependents", () => {
+  test("check each reference against the last run of its producer, on both sides", async () => {
+    const prj = new FakeProject();
+    prj.block("samples", {
+      currentArgs: prj.args({}),
+      prodArgs: prj.args({}),
+      prodCtx: prj.value("BContext", {}),
+      prodUiCtx: prj.frame({ condition: { spec: SPEC, cells: ["treated", "mock"] } }),
+    });
+    prj.block("x", { currentArgs: prj.args({ levels: [pick("treated"), pick("control")] }) });
+    const tree = prj.tree();
+
+    const link: ColumnLink = {
+      producer: { blockId: "samples", name: "condition" },
+      holderBlockId: "x",
+      ref: condition,
+      values: ["treated", "control"],
+      columnLabel: "Condition",
+      check: { type: "missingValues", values: ["control"] },
+    };
+    expect(await dependenciesOf(tree, "x")).toEqual([link]);
+    expect(await dependentsOf(tree, "samples")).toEqual([link]);
+  });
+
+  test("a producer with no last run is not run, labelled from what it prepares", async () => {
+    const prj = new FakeProject();
+    prj.block("samples", {
+      currentArgs: prj.args({}),
+      stagingCtx: prj.value("BContext", {}),
+      stagingUiCtx: prj.frame({ condition: { spec: SPEC, cells: ["treated"] } }),
+    });
+    prj.block("x", { currentArgs: prj.args({ target: pick("treated") }) });
+    const tree = prj.tree();
+
+    expect(await dependenciesOf(tree, "x")).toMatchObject([
+      { columnLabel: "Condition", check: { type: "notRun" } },
+    ]);
+    expect(await dependentsOf(tree, "samples")).toMatchObject([
+      { holderBlockId: "x", check: { type: "notRun" } },
+    ]);
+  });
+
+  test("a producer with a last run whose results failed to render is unavailable", async () => {
+    const prj = new FakeProject();
+    prj.block("samples", {
+      prodArgs: prj.args({}),
+      prodCtx: prj.value("BContext", {}),
+      prodUiCtx: { error: prj.error("render failed") },
+    });
+    prj.block("x", { currentArgs: prj.args({ target: pick("treated") }) });
+    const tree = prj.tree();
+
+    expect(await dependenciesOf(tree, "x")).toMatchObject([{ check: { type: "unavailable" } }]);
+    expect(await dependentsOf(tree, "samples")).toMatchObject([{ check: { type: "unavailable" } }]);
+  });
+
+  test("a producer with a last run whose results are not there yet is pending", async () => {
+    const prj = new FakeProject();
+    prj.block("samples", {
+      prodArgs: prj.args({}),
+      prodCtx: prj.value("BContext", {}),
+      prodUiCtx: "unresolved",
+    });
+    prj.block("x", { currentArgs: prj.args({ target: pick("treated") }) });
+
+    expect(await dependenciesOf(prj.tree(), "x")).toMatchObject([{ check: { type: "pending" } }]);
+  });
+
+  test("a failed result list that never locks settles the links", async () => {
+    const prj = new FakeProject();
+    prj.block("samples", {
+      prodArgs: prj.args({}),
+      prodCtx: prj.value("BContext", {}),
+      prodUiCtx: prj.frame({}, { state: "failed" }),
+    });
+    prj.block("x", { currentArgs: prj.args({ target: pick("treated") }) });
+    const tree = prj.tree();
+    const dependencies = blockDependencies(tree.entry(), "x", env);
+    const dependents = blockDependents(tree.entry(), "samples", env);
+
+    expect(await dependencies.getFullValue()).toMatchObject({
+      stable: true,
+      value: [{ check: { type: "unavailable" } }],
+    });
+    expect(await dependents.getFullValue()).toMatchObject({
+      stable: true,
+      value: [{ check: { type: "unavailable" } }],
+    });
+  });
+
+  test("an output of a result list still open is pending until the list locks", async () => {
+    const prj = new FakeProject();
+    const frame = prj.frame({}, { state: "open" });
+    prj.block("samples", { prodArgs: prj.args({}), prodUiCtx: frame });
+    prj.block("x", { currentArgs: prj.args({ target: pick("treated") }) });
+    const tree = prj.tree();
+    const dependencies = blockDependencies(tree.entry(), "x", env);
+
+    expect(await dependencies.getFullValue()).toMatchObject({
+      stable: false,
+      value: [{ check: { type: "pending" } }],
+    });
+
+    prj.extend(frame, { condition: { spec: SPEC, cells: ["treated"] } }, { state: "locked" });
+    tree.updateFromResourceData(prj.changes());
+
+    expect(await dependencies.getFullValue()).toMatchObject({
+      stable: true,
+      value: [{ check: { type: "ok" } }],
+    });
+  });
+
+  test("a block without current args is read from the args of its last run", async () => {
+    const prj = new FakeProject();
+    prj.block("samples", {
+      prodArgs: prj.args({}),
+      prodUiCtx: prj.frame({ condition: { spec: SPEC, cells: ["treated"] } }),
+    });
+    prj.block("x", { prodArgs: prj.args({ target: pick("treated") }) });
+
+    expect(await dependenciesOf(prj.tree(), "x")).toMatchObject([{ check: { type: "ok" } }]);
+  });
+
+  test("a block whose argsIssues found errors keeps its links, read from its current args", async () => {
+    const prj = new FakeProject();
+    const args = { target: pick("treated"), threshold: undefined };
+    prj.block("samples", {
+      currentArgs: prj.args({}),
+      prodArgs: prj.args({}),
+      prodUiCtx: prj.frame({ condition: { spec: SPEC, cells: ["treated"] } }),
+    });
+    prj.block("x", {
+      currentArgs: prj.args(args),
+      inputsValid: prj.argsErrors([{ severity: "error", message: "Set a threshold" }], args),
+    });
+    const tree = prj.tree();
+
+    expect(await dependenciesOf(tree, "x")).toMatchObject([
+      { producer: { blockId: "samples" }, ref: condition, check: { type: "ok" } },
+    ]);
+    expect(await dependentsOf(tree, "samples")).toMatchObject([
+      { holderBlockId: "x", ref: condition, check: { type: "ok" } },
+    ]);
+  });
+
+  test("recalculate when the args of a block change", async () => {
+    const prj = new FakeProject();
+    prj.block("samples", {
+      currentArgs: prj.args({}),
+      prodArgs: prj.args({}),
+      prodUiCtx: prj.frame({ condition: { spec: SPEC, cells: ["treated"] } }),
+    });
+    prj.block("x", { currentArgs: prj.args({ target: pick("control") }) });
+    const tree = prj.tree();
+    const dependencies = blockDependencies(tree.entry(), "x", env);
+
+    expect(await dependencies.getValue()).toMatchObject([
+      { check: { type: "missingValues", values: ["control"] } },
+    ]);
+
+    prj.block("x", { currentArgs: prj.args({ target: pick("treated") }) });
+    tree.updateFromResourceData(prj.changes());
+
+    expect(await dependencies.getValue()).toMatchObject([{ check: { type: "ok" } }]);
+  });
+});
+
+describe("what the column links of a block watch", () => {
+  const donor = createGlobalPObjectId("donors", "donor");
+
+  /** Two producers, each referenced by one block below them, the second block also by a third. */
+  function twoChains() {
+    const prj = new FakeProject();
+    const samplesFrame = prj.frame(
+      { condition: { spec: SPEC, cells: ["treated"] } },
+      { state: "open" },
+    );
+    prj.block("samples", {
+      currentArgs: prj.args({}),
+      prodArgs: prj.args({}),
+      prodUiCtx: samplesFrame,
+    });
+    const donorsArgs = prj.args({});
+    prj.block("donors", {
+      currentArgs: donorsArgs,
+      prodArgs: prj.args({}),
+      prodUiCtx: prj.frame({ donor: { spec: SPEC, cells: ["d1"] } }),
+    });
+    prj.block("x", { currentArgs: prj.args({ target: pick("treated") }) });
+    prj.block("y", { currentArgs: prj.args({ target: pick("d1", donor) }) });
+    const tree = prj.tree();
+    const watched = {
+      xDependencies: blockDependencies(tree.entry(), "x", env),
+      yDependencies: blockDependencies(tree.entry(), "y", env),
+      samplesDependents: blockDependents(tree.entry(), "samples", env),
+      donorsDependents: blockDependents(tree.entry(), "donors", env),
+    };
+    return { prj, tree, samplesFrame, donorsArgs, watched };
+  }
+
+  const changed = (watched: Record<string, { isChanged(): boolean }>) =>
+    mapValues(watched, (computable) => computable.isChanged());
+
+  test("a new run of one producer leaves the links of blocks not referencing it alone", async () => {
+    const { prj, tree, donorsArgs, watched } = twoChains();
+    await Promise.all(Object.values(watched).map((c) => c.getValue()));
+
+    prj.block("donors", {
+      currentArgs: donorsArgs,
+      prodArgs: prj.args({ rerun: true }),
+      prodUiCtx: prj.frame({ donor: { spec: SPEC, cells: ["d2"] } }),
+    });
+    tree.updateFromResourceData(prj.changes());
+
+    expect(changed(watched)).toEqual({
+      xDependencies: false,
+      yDependencies: true,
+      samplesDependents: false,
+      donorsDependents: true,
+    });
+  });
+
+  test("a column added to a run leaves the links to its other columns alone", async () => {
+    const { prj, tree, samplesFrame, watched } = twoChains();
+    await Promise.all(Object.values(watched).map((c) => c.getValue()));
+
+    prj.extend(samplesFrame, { batch: { spec: SPEC, cells: ["b1"] } }, { state: "open" });
+    tree.updateFromResourceData(prj.changes());
+
+    expect(changed(watched)).toEqual({
+      xDependencies: false,
+      yDependencies: false,
+      samplesDependents: false,
+      donorsDependents: false,
+    });
+  });
+
+  test("an args edit of a block reaches its dependencies and the dependents of the blocks above", async () => {
+    const { prj, tree, watched } = twoChains();
+    await Promise.all(Object.values(watched).map((c) => c.getValue()));
+
+    prj.block("x", { currentArgs: prj.args({ target: pick("mock") }) });
+    tree.updateFromResourceData(prj.changes());
+
+    expect(changed(watched)).toEqual({
+      xDependencies: true,
+      yDependencies: false,
+      samplesDependents: true,
+      donorsDependents: true,
+    });
+  });
+});
+
+describe("labelBlockColumnLinks", () => {
+  const dependencies: ColumnLink[] = [
+    {
+      producer: { blockId: "samples", name: "condition" },
+      holderBlockId: "x",
+      ref: condition,
+      values: null,
+      columnLabel: null,
+      check: { type: "ok" },
+    },
+  ];
+  const dependents: ColumnLink[] = [
+    {
+      producer: { blockId: "x", name: "condition" },
+      holderBlockId: "untitled",
+      ref: condition,
+      values: null,
+      columnLabel: null,
+      check: { type: "ok" },
+    },
+  ];
+
+  test("labels the blocks the links name by their titles in the overview", () => {
+    const blocks = [
+      { id: "samples", title: "Samples & data" },
+      { id: "untitled", title: undefined },
+    ];
+
+    expect(labelBlockColumnLinks({ blockId: "x", dependencies, dependents }, blocks)).toEqual({
+      blockId: "x",
+      dependencies,
+      dependents,
+      labels: { samples: "Samples & data" },
+    });
+  });
+
+  test("gives no links while a side is not computed", () => {
+    expect(
+      labelBlockColumnLinks({ blockId: "x", dependencies, dependents: undefined }, []),
+    ).toBeUndefined();
+    expect(
+      labelBlockColumnLinks({ blockId: "x", dependencies: undefined, dependents }, []),
+    ).toBeUndefined();
+  });
+});
+
+// Internals
+
+const SPEC: PColumnSpec = {
+  kind: "PColumn",
+  name: "condition",
+  valueType: "String",
+  axesSpec: [{ name: "sample", type: "String" }],
+  annotations: { [Annotation.Label]: "Condition" },
+};
+
+async function dependenciesOf(tree: PlTreeState, blockId: string) {
+  const value = await blockDependencies(tree.entry(), blockId, env).getValue();
+  if (value === undefined) throw new Error(`No dependencies of ${blockId}`);
+  return value;
+}
+
+async function dependentsOf(tree: PlTreeState, blockId: string) {
+  const value = await blockDependents(tree.entry(), blockId, env).getValue();
+  if (value === undefined) throw new Error(`No dependents of ${blockId}`);
+  return value;
+}

package/src/middle_layer/column_links.ts

@@ -0,0 +1,152 @@
+import { Computable } from "@milaboratories/computable";
+import type { PlTreeEntry, PlTreeNodeAccessor } from "@milaboratories/pl-tree";
+import { notEmpty } from "@milaboratories/ts-helpers";
+import {
+  computeDependencies,
+  computeDependents,
+  type BlockColumnLinks,
+  type ArgsKind,
+  type ColumnLinksSource,
+  type ProducerRun,
+  type ColumnLink,
+} from "@milaboratories/pl-model-common";
+import type { BlockStateOverview } from "@milaboratories/pl-model-middle-layer";
+import type { ProjectStructure } from "../model/project_model";
+import { ProjectStructureKey, projectFieldName } from "../model/project_model";
+import { allBlocks } from "../model/project_model_util";
+import type { MiddleLayerEnvironment } from "./middle_layer";
+
+/** What the column links computables read besides the project tree. */
+export type ColumnLinksEnv = Pick<MiddleLayerEnvironment, "projectHelper" | "logger">;
+
+/**
+ * Outputs of other blocks that the args of the block reference, checked against what the last
+ * runs of their producers export; `undefined` when they could not be computed. Reads the order
+ * of the blocks, the args of the block, and of each producer above it that the args reference:
+ * whether it has a last run, the results of that run as far as the referenced columns go, and,
+ * only to label a column the run does not export, the results the producer prepares before it
+ * is run.
+ */
+export function blockDependencies(
+  prjEntry: PlTreeEntry,
+  blockId: string,
+  env: ColumnLinksEnv,
+): Computable<ColumnLink[] | undefined> {
+  return Computable.make(
+    (ctx) => computeDependencies(columnLinksSource(ctx.accessor(prjEntry).node(), env), blockId),
+    { recover: forgetFailed(env, "dependencies") },
+  );
+}
+
+/**
+ * Blocks whose args reference outputs of the block, each reference checked against what the
+ * last run of the block exports; `undefined` when they could not be computed. Reads the order of
+ * the blocks, the args of the block and of every block below it, and of the block's own runs:
+ * whether it has a last run, the results of that run as far as the referenced columns go, and,
+ * only to label a column the run does not export, the results it prepares before it is run.
+ */
+export function blockDependents(
+  prjEntry: PlTreeEntry,
+  blockId: string,
+  env: ColumnLinksEnv,
+): Computable<ColumnLink[] | undefined> {
+  return Computable.make(
+    (ctx) => computeDependents(columnLinksSource(ctx.accessor(prjEntry).node(), env), blockId),
+    { recover: forgetFailed(env, "dependents") },
+  );
+}
+
+/**
+ * Column links of a block with the blocks they name labelled by their titles in the project
+ * overview, the names the project shows; a block the overview has no title for stays unlabelled.
+ * `undefined` while either side is not computed.
+ */
+export function labelBlockColumnLinks(
+  links: {
+    blockId: string;
+    dependencies: undefined | ColumnLink[];
+    dependents: undefined | ColumnLink[];
+  },
+  blocks: readonly Pick<BlockStateOverview, "id" | "title">[],
+): BlockColumnLinks | undefined {
+  const { blockId, dependencies, dependents } = links;
+  if (dependencies === undefined || dependents === undefined) return undefined;
+  const named = new Set([
+    ...dependencies.map((link) => link.producer.blockId),
+    ...dependents.map((link) => link.holderBlockId),
+  ]);
+  const labels: Record<string, string> = {};
+  for (const { id, title } of blocks) {
+    if (named.has(id) && title !== undefined) labels[id] = title;
+  }
+  return { blockId, dependencies, dependents, labels };
+}
+
+// Internals
+
+/** Logs why a side of the column links failed; the side is then not computed. */
+function forgetFailed(env: ColumnLinksEnv, side: "dependencies" | "dependents") {
+  return (cause: unknown[]): undefined => {
+    env.logger.error(new Error(`Error in column links: ${side}`, { cause }));
+    return undefined;
+  };
+}
+
+function columnLinksSource(
+  prj: PlTreeNodeAccessor,
+  env: ColumnLinksEnv,
+): ColumnLinksSource<PlTreeNodeAccessor> {
+  const structure = notEmpty(prj.getKeyValueAsJson<ProjectStructure>(ProjectStructureKey));
+  return {
+    blockIds: [...allBlocks(structure)].map(({ id }) => id),
+    referencesOf: (blockId, kind) => {
+      const args = readArgs(prj, blockId, kind);
+      if (args === undefined) return undefined;
+      return env.projectHelper.getColumnReferences(args.id, () => args.getDataAsJson());
+    },
+    lastRunOf: (blockId) => readLastRun(prj, blockId),
+    stagingOf: (blockId) => readStaging(prj, blockId),
+  };
+}
+
+/** The project field holding a block's args of each kind. */
+const ARGS_FIELD = { current: "currentArgs", lastRun: "prodArgs" } as const satisfies Record<
+  ArgsKind,
+  string
+>;
+
+function readArgs(
+  prj: PlTreeNodeAccessor,
+  blockId: string,
+  kind: ArgsKind,
+): undefined | PlTreeNodeAccessor {
+  return prj.traverse({
+    field: projectFieldName(blockId, ARGS_FIELD[kind]),
+    assertFieldType: "Dynamic",
+    stableIfNotFound: true,
+  });
+}
+
+/**
+ * A block has a last run while it holds the args of that run. The results of the run fail to
+ * render when their field, or the result list itself, has an error.
+ */
+function readLastRun(prj: PlTreeNodeAccessor, blockId: string): ProducerRun<PlTreeNodeAccessor> {
+  if (readArgs(prj, blockId, "lastRun") === undefined) return { type: "notRun" };
+  const ctx = prj.traverseOrError({
+    field: projectFieldName(blockId, "prodUiCtx"),
+    stableIfNotFound: true,
+  });
+  if (ctx === undefined) return { type: "rendering" };
+  if (!ctx.ok || ctx.value.getError() !== undefined) return { type: "failed" };
+  return { type: "rendered", ctx: ctx.value };
+}
+
+/** The results a block prepares before it is run; `undefined` while there are none, or they failed. */
+function readStaging(prj: PlTreeNodeAccessor, blockId: string): undefined | PlTreeNodeAccessor {
+  const ctx = prj.traverseOrError({
+    field: projectFieldName(blockId, "stagingUiCtx"),
+    stableIfNotFound: true,
+  });
+  return ctx !== undefined && ctx.ok ? ctx.value : undefined;
+}

package/src/middle_layer/index.ts

@@ -15,3 +15,9 @@ export type {
   TemplateId,
   TemplateListEntry,
 } from "./template_list";
+export type {
+  BlockActionReading,
+  BlockActionContextMode,
+  BlockActionContextNode,
+  BlockActionTransition,
+} from "./block_action_context";

package/src/middle_layer/middle_layer.ts

@@ -1976,6 +1976,8 @@ export class MiddleLayer {
     runtimeCapabilities.addSupportedRequirement("requiresModelAPIVersion", 2);
     runtimeCapabilities.addSupportedRequirement("requiresCreatePTable", 2);
     runtimeCapabilities.addSupportedRequirement("requiresPFramesVersion", REQUIRES_PFRAMES_VERSION);
+    // The project overview and production rendering refuse to run args argsIssues found errors in
+    runtimeCapabilities.addSupportedRequirement("requiresArgsIssues");
     registerServiceCapabilities((flag, value) =>
       runtimeCapabilities.addSupportedRequirement(flag, value),
     );