PathMX Actor And Action Implementation State

This is the concise authority for the Actor/Action slice implemented during OpenAI Build Week through July 19, 2026. Use the linked decisions for durable why and the code for exact exported types. Older Actor, Action Reducer, Instantiation, Model/Point, and Action Source designs are historical inputs, not competing contracts.

What is implemented

Actor Host

The portable @pathmx/actor package owns the application-facing Actor Host. Its public verbs are:

  • play(context, input) to create or resume a source-backed Play Session;
  • act(context, submission) to validate, authorize, admit, plan, apply, and finalize one Action request.

Player, CLI, Server, and other transports call the Actor Host. They do not call the internal Action Runner directly. The Host receives a trusted Actor request context containing the Actor, optional Persona, and Selected Root.

Action Definitions and mappings

Installed code contributes versioned Action Definitions through defineAction(...) from the normal pathmx/plugin authoring surface. A definition owns its target type, input/result contracts, capability limits, availability check, and semantic plan. Its Action Context is ready to use: the canonical target is a parsed Source or SourceBlock, sources.graph exposes the standard PathMXGraphQueries, and sources.require(sourceId) loads another parsed Source.

The plan builder exposes bounded PathMX operations such as Block data updates, Block replacement/insertion, Source replacement, and Source creation. It derives Source version expectations and low-level operations from every read and planned change. Ordinary plugin Actions therefore do not parse Markdown again, calculate byte ranges, or construct Runner protocol records. The low-level pathmx/actor definition remains available for Host/Runner adapters and specialized Core Actions.

Build supplies the already parsed Repository Source. If versioned storage is briefly one Source revision ahead of that projection, availability reports source-projection-stale and planning conflicts without invoking plugin code. The caller may retry after settlement; the Action never receives a reduced or second parsed representation.

Authored Sources and Blocks map a readable local name such as save or submit to an installed Action Definition. A submitted mapping selector is either Source-scoped or Block-scoped. Build resolves the trusted Action ID and canonical target; the browser does not choose either one.

The same local name may appear independently on multiple Blocks because scope includes the owning Source or Block. Mixed or repeated transport identity is rejected before admission.

Runs, authority, and workspaces

Every admitted mutation is an Action Run with:

  • Initiating Actor and optional Persona;
  • Effective Authority and Sealing Host;
  • Play Session and Selected Root context when present;
  • invocation ID, installed Action identity, normalized input, and target;
  • plan evidence and a durable finalized, no-op, conflict, unavailable, failed, or cancelled outcome.

The append-only Journal owns idempotent admission and final outcomes. Invalid or unauthorized requests rejected before admission do not fabricate Runs.

The Runner opens one revision-bound Authorized Source Workspace only after planning and authority checks. It applies the whole plan atomically or discards partial work. It does not keep a workspace or authority open across deferred network or AI work.

Build and Server adapters

@pathmx/build/actor adapts ordinary Markdown Sources to Actor contracts. It reads Play Sessions, resolves Source/Block Action Mappings, reads current Source versions, exposes the canonical cached PathMXGraph for the selected Root, and applies guarded Source changes through the existing mutation kernel. Deferred build changes are projected before graph reads without reparsing already indexed Sources. The selected graph bounds mutation authority; unrelated local Markdown may exist in the workspace without becoming writable.

The Bun Server has one canonical Source POST path. It derives trusted request context, selector identity, and Actor state, then calls the Actor Host. Finalized Source Changes flow through the existing build/live pipeline. Update envelopes may carry causal Action Run IDs so the Player can reconcile pending state with the canonical visible update.

The request carries the actual Host-selected Root; neither Graph Index content nor Projection Revision fabricates Root Membership. The Build adapter caches Graph Index routing by representation identity, reuses byte-bounded parsed Sources and the canonical Source Graph, and advances Source Revision from the exact admitted paths. The short Source mutation lease ends once those paths and causal Run IDs are synchronously admitted to Host reconciliation.

Host computes recovery and frontier continuation outside the interactive adoption lane, coalesces synchronous Source-change bursts, and returns a discriminated Root outcome. Server responds with a small projection receipt. Runtime applies the canonical update or resync before Player settles a matching Run; unchanged output may settle directly from the receipt, while a projection failure remains an explicit saved-but-not-visible state.

First-party interactions

The implemented first-party Actions include:

  • session.open for source-backed Play Session creation;
  • task submission through readable task-list Markdown;
  • Block-scoped single-choice, text, and field question submission;
  • responses.save for deterministic object-valued Block response data;
  • annotation comment, reply, and resolve Actions.

Task, Question, Response, and Annotation mutations use the same parsed Action Context and plan builder as installed plugin Actions. Annotation Actions retain their focused anchor/footnote edit planner because text selections and Beats are annotation-domain inputs; the shared Action layer still owns Source reads, version expectations, conflict handling, and the final write.

Generated forms remain ordinary canonical submitters. Player Action Affordances call those forms with requestSubmit, preserving native validation and pending/rejected state. ctx.play.actions remains the separate surface for ephemeral Literate Component commands.

Accepted boundaries

  • Direct trusted author edits are Source Changes, not Action Runs.
  • Root Projection coordination, Root Selection, Root Subscription, and live delivery remain outside @pathmx/actor.
  • Credentials and provider proofs stay outside authored Sources.
  • Reachability is not mutation authority.
  • A finalized Source Change is durable even if later projection convergence fails; the Host reports that failure rather than rolling back history.
  • Undo or redo is a new authorized Run, not Journal rewriting.
  • Plugin Action Definitions do not own Play Sessions, authority, Journals, or the Actor Host lifecycle.
  • The Action Context is a read-only planning view plus a plan builder. It is not an Authorized Source Workspace and cannot apply mutations directly.
  • Spaceholders remain a separate authored/plugin capability. The old Model/Point/Input Projection and live-Spaceholder architectures are not the current Actor input model.

Accepted but not yet implemented

  • The installable Codex learning plugin and its proposed protected adapter surface remain behind their separate contract review.
  • General inspect or subscribe Actor Host verbs are not part of the public first slice.
  • Production identity providers, Permission Source schemas, access policy adapters, and multi-root Actor-scale authorization remain future work.
  • Deferred AI/provider work needs causally linked Runs and visible recovery artifacts; the first slice does not hold one Run open across that work.
  • General template/rule/instantiation grammar, automatic Spaceholder input projection, and the old Model/Point formula system are not accepted runtime contracts.

Verification baseline

The Build Week issue records the exact evolving counts. The accepted baseline includes focused Actor/Build/Server/form tests, the full Build and Player suites, package typechecks, Player/runtime asset checks, a scratch paths/ build, packed-package task/question/response Action smokes, readable Markdown reload, exact Journal Run correlation, and strict maintainability review.

The Action convergence browser baseline additionally runs 20 real Source writes through Bun, WebSocket, Runtime, and Player on both a one-Source and a 1,000-Source Root. Submit-to-applied p95 is measured inside the page at the actual DOM transition; the slower p95s from two consecutive July 19 runs are 40.7 ms and 61.6 ms.

When behavior changes, update the code and focused issue evidence first. Update this guide only when the implemented boundary or its durable status changes.