# Decision: productize agent access and live Package authoring

Status: proposed, 2026-09-24. Action: experiment.
This remains the broader architecture assessment and execution proposal, not a
production-release decision. The first local authoring slice is now implemented;
see [prepared Package authoring](PREPARED_PACKAGE_AUTHORING.md) for its contract,
executable tests and intentionally narrower acceptance scope.

## Context and evidence

The user wants Pajama Engine to support future agents and continuous content and
Package creation. [PRODUCT_GOAL.md](PRODUCT_GOAL.md) remains the sole North Star:
an author publishes a bounded exact Package through the authoritative admission,
CAS, composite-checkpoint and tick-activation contract. This proposal follows
[ENGINE_DECISIONS.md](ENGINE_DECISIONS.md); it does not replace the existing roadmap.

Inspected baseline: Git `e1dc2c0d5f38231054325dba67a9ea3344ea7ea5` plus the existing
dirty working tree. The following records the original assessment baseline;
the linked implementation decision records subsequent work and verification.

| Finding | Evidence and limit |
| --- | --- |
| Package staging, exact identities, admission, ABI2 state, checkpoint recovery and client delivery already exist. | `pajama-content`, `pajama-world::package`, server publication and client content owners; these should be extended, not duplicated. |
| The four-car rehearsal demonstrates a live V1-to-V2 update with retained old vehicles. | [Recording receipt](evidence/fleet-driving-20260924/demo-fleet-driving-receipt.json). This is a local four-client workload, not a production-scale MMO or arbitrary historical-version proof. |
| Shipping client policy still selects Catalog V1; V2 is an explicit experimental policy with non-default build features. | [app_bootstrap.rs](../crates/pajama-client/src/app_bootstrap.rs), [content.rs](../crates/pajama-client/src/content.rs). Do not equate a demo flag with normal-client completion. |
| An authoring runtime, MCP schemas and remote job bridge already exist. | [Authoring rehearsal](AGENT_AUTHORING_DEMO.md). The runtime's Edge bridge explicitly rejects non-loopback hosts. Remote job ingress is not remote production-world publication. |
| The author wrapper accepts one newly authored root per request. Interrupted preparation stops for inspection. | [runtime.mjs](../scripts/authoring/runtime.mjs), including its `preparing` journal state. The core's dependency-closure capabilities are broader than this author-facing wrapper. |
| Agent interaction already checks freshness, identity, bounded decisions and receipts. | [Driving director](../scripts/system-one/driving-director.mjs), [System One contract](SYSTEM_ONE_AGENT.md). Durable planner handoff and cross-process budgets remain proposed in [AGENT_INTEGRATION.md](AGENT_INTEGRATION.md). |
| Author schema and implementation have drifted. | `registry.rs` advertises at most 16 imported assets; `safeAssetFiles` accepts 32 while preserving a 64 MiB aggregate bound. Resolve the intended contract once, then generate and exercise both consumers. |
| Layout generation is a bounded finite-grid compiler. | [GENERATIVE_CONTENT.md](GENERATIVE_CONTENT.md): adjacency, separation, connected groups and exclusions; it does not establish arbitrary mesh clearance, walkability, structural stability or live terrain support. |
| Some historical documentation lags newer demonstrations. | For example, older content notes say general Package skills are absent, while the newer skill code and Jev receipts exercise them. Audit individual gates; do not relabel every historical unchecked item as missing code. |

The four-car update was orchestrated by the recording harness. Jev selected
driving and sabotage actions; the recording does not establish autonomous Jev
Package creation/publication. The proposed end-to-end gate below must establish
that additional capability separately.

## Alternatives and selection

| Option | Benefit | Cost and limitation | Decision |
| --- | --- | --- | --- |
| Continue adding scenario-specific recording scripts | Fast demonstrations using proven engine primitives | Duplicates identity, retries, observations and evidence; does not qualify a stable third-party contract | Retain scripts as consumers and regression fixtures |
| Extract stable agent/author contracts around existing owners | Reuses durability and isolation while making authoring resumable and testable | Requires explicit versions, permission policy, failure tests and lifecycle qualification | Preferred direction |
| Introduce a second agent-owned world mutation service or put planning/solving inside the tick | Superficially simpler direct access | Splits authority or couples inference/search latency to gameplay; violates current invariants | Reject |
| Begin with a distributed engine rewrite, new solver stack or native-code Package plugins | Potential future breadth | No measured blocker justifies the compatibility and operational surface | Defer |

First run a small lifecycle/contract experiment against the current baseline.
Then implement the narrowest missing owner contract. New crates or services are
justified by a real ownership/deployment need, not by the labels below.

## Target responsibilities

Keep two loops with distinct grants and a shared authoritative result model:

```text
acting agent
  -> permitted observation + discoverable active capabilities
  -> bounded intent -> existing server command validation
  -> authoritative outcome -> replicated observation

authoring agent / person / generator
  -> isolated draft -> typed specification -> bounded build job
  -> validate + preview + impact report -> immutable candidate
  -> EXISTING admission / CAS / checkpoint / tick transaction
  -> exact active Package receipt -> per-client readiness + behavior evidence
```

Model inference, asset generation, search, compilation and preview stay outside
the simulation tick. Luau stays a bounded policy returning typed commands.
Driving's fast controller stays native; a remote model selects expiring intents.
Neither MCP nor an LLM becomes the frame-rate physics-control transport.

`pajama-world` owns serializable versioned contracts; `pajama-content` owns cold
validation/compiler work; `pajama-server` owns grants, authoritative commits and
recovery; the client owns exact-revision delivery and presentation. External
author/job runners orchestrate these owners. They never receive world handles.

## Work packages and acceptance

| Priority | Work | Concrete acceptance |
| --- | --- | --- |
| P0 | Qualify the normal Package lifecycle and reconcile the evidence ledger | Exact candidate, ordinary client policy and recorded failure matrix cover update, late join, independent client restart, corrupt/offline content, server restart and rollback. Do not flip the default V2 flag to substitute for evidence. |
| P0 | Make live-instance revision lifetime explicit | A1 instances remain while B2 and C3 are proposed. Every referenced recipe, behavior and presentation artifact is either retained under a bounded durable policy, migrated explicitly, or causes publication to reject before mutation. Test reconnect and restart with the original instances. |
| P1 | Publish one coherent Agent API/SDK contract | Two independently implemented clients discover the same schema and capabilities and perform the same permitted task. Cover stale observations, changed relevant Package pins, revoked grants, duplicate requests, timeout/unknown outcome and process restart. |
| P1 | Turn the existing author runner into a resumable candidate workflow | Draft, validate, preview, submit and status have distinct semantics. Restart at each stage resumes/reconciles the exact input; no duplicate paid generation, release or world effect. Expose verified dependency closures through the existing backend capability. |
| P1 | Prove a creator-to-player agent handoff | An authoring agent creates a new allowed capability, publication becomes authoritative, a player agent discovers and uses it, and independent world/client observations confirm the result. No scenario-specific direct mutation. |
| P1 | Qualify remote identity, grants and concurrency | Separate player/actor control from author/release grants. Cover world/realm binding, expiry, revocation, idempotency, stale epochs and all enabled downstream writes before qualifying the remote publication route. Preserve existing guards until then. |
| P2 | Extend generative specifications with domain validators | Start with a concrete road/outpost task: terrain support, vehicle clearance and connectivity. An independently checked placement certificate and preview detect invalid results; incomplete search is not reported as unsatisfiable. |
| P2 | Measure sustained authoring and multi-agent load | Increase agents, observations and update rate on one authority; record tick/frame tails, queues, bytes, residency and accepted-task cost. Partition only after a measured limit and an ownership/failover design justify it. |

P0 correctness work and a small local P1 SDK/candidate slice can advance together.
Unattended remote creation is gated by lifecycle and authorization evidence, not
by a completed interface document.

### Agent contract

Build on the existing game client, directors and schema registry. Stabilize
capability discovery, bounded AOI/event observations, command submission,
request-status reconciliation and control release. Include world/realm/session,
server instance/epoch, observation sequence/freshness, relevant exact Package
references, idempotency key, grant and resource budget where each operation needs
them. These are proposed semantic fields, not a decision to rewrite every wire DTO.

An unrelated Package addition should not unnecessarily cancel a valid pinned
vehicle intent. A changed relevant capability, expired observation or revoked
grant must trigger re-observation/rejection. Observation access follows the same
visibility/permission policy as gameplay; agents do not read private whole-world
state through an admin shortcut.

Distinguish accepted, authoritative committed/failed, unknown and observed
postcondition. A missing reply is unknown, not proof of rejection. Cancellation
before commit can stop work; cancellation after commit does not undo the world.
Use one language SDK first around the existing Node consumers, with schemas
generated from the engine contract. Add other SDK languages for actual consumers.

### Authoring and concurrent work

The existing runtime becomes a reviewable candidate workflow with an isolated
source workspace, base generation, input hash, compiler identity, dependency
closure, impact summary, permission requirements and bounded cost estimates.
Validation/preview do not publish. Failed preparation retains diagnostics and
can resume only when completed artifacts and journal state reconcile exactly.

Source/build jobs and inference budgets must survive coordinator restart.
Extend the existing job bridge where appropriate; do not build another publisher.
An existing delegated grant can permit automatic activation within its scope.
Requests outside that grant require the configured authorization path; this
proposal does not mandate a manual approval click for every package.

Concurrent authors build separate immutable candidates. Conflicting generations
return structured conflicts; an explicit rebase is revalidated and previewed.
They do not overwrite each other's world edits or silently publish last-writer
wins. Keep the current single authority and CAS ordering initially.

### Revisions, retention and migration

Definition updates, instance migration and compensating world edits are separate
operations. A vehicle Package update must state whether existing instances stay
pinned or enter an explicit, recoverable migration. A changed mesh cannot imply
an unreviewed mass/collider/behavior change on a moving vehicle.

Retained versions need a bounded closure rooted in live instances, executable
state, declared rollback/recovery cuts and supported in-flight work. Resource
reclamation must respect that closure. Indefinitely pinning every historical
version is not a design. When capacity is exhausted, reject or require an explicit
migration/retirement policy before accepting the update.

Immediate-predecessor retention is the demonstrated starting point. Broader
history needs an adjacent durable/protocol version if its semantics require one;
do not reinterpret existing DTOs or promote currently unsupported recovery data.

Server activation and client resource readiness are different events. Keep exact
identity and bounded pending/failure behavior per client. A slow client must not
become an unbounded global activation barrier. Preserve authorized old-instance
presentation while new assets load, including the conditions behind the earlier
pink-model regression.

### Constraint generation and extensibility

Separate declarative input, compiled intermediate representation, bounded solver,
independent result validation, ordinary Package output and explicit placement.
Keep compiler/schema/seed and sampled world dependencies with the result.
Recheck affected world preconditions at authoritative application; a correct
layout against an old terrain snapshot may be invalid when applied.

Add hard constraints and soft objectives by domain: support, clearance, access,
road grade and reachability first. Return offending constraints and useful
counterexamples where available; do not promise a minimal unsatisfiable core
without implementing and checking that solver property. Begin with local
incremental rebuilds and bounded jobs, not a universal unbounded DSL.

Packages can compose installed native capabilities, data and sandboxed behavior.
A fundamentally new physics/rendering/native component capability still requires
an engine adapter/version and compatibility evidence. Dynamic Packages must not
be marketed or implemented as unrestricted native-code loading.

### Runtime budgets and evidence

Budget generation, uploads, decode, GPU staging, mesh/collider preparation,
replication and residency separately. Build/compile/solve work stays off the live
lock. Keep queue bounds, cancellation and stale-result fencing across workers.
Large world construction can use independently valid bounded transactions when
its gameplay contract allows them; a Package closure must never become half active.

Use an isolated experiment world with its own identity/storage/lease and an exact
checkpoint/content seed. Record model outputs for repeatable transport tests,
then sample the real provider separately. Do not claim bitwise cross-platform
physics/GPU determinism; use exact identity checks and declared physical tolerances.

Record intent -> candidate -> release -> authoritative event -> client observation
with correlated IDs and timestamps. For craters, a committed command or a particle
burst is not enough to establish visible gameplay: assert changed terrain, updated
collision, wheel/ground interaction when claimed, and useful before/after views.
Track hot-update-conditioned frame tails rather than only whole-run averages.

## First executable slice

1. Resolve author-schema/runtime drift and validate ordinary SDK requests through
   both the advertised schema and runtime, including limits and rejection cases.
2. Extend the existing lifecycle rehearsal with A1 -> B2 -> C3 while A1 vehicles
   remain. Establish whether the current contract retains or rejects safely;
   preserve the outcome instead of assuming arbitrary-history support.
3. Build the minimal separate validate/preview/status surface around the existing
   author runner. Preview uses an isolated world; it never creates a live release.
4. Run one author-agent-created road/outpost or vehicle capability, publish through
   existing admission, then let a separately authorized player agent discover and
   exercise it. Include lost acknowledgement, one conflicting publication and
   coordinator restart before calling the orchestration complete.

Existing entry points include `node --test scripts/authoring/authoring.test.mjs`,
the System One/driving Node suites, owning Rust crate tests, and the real-shard
rollback fixture (`npm run test:e2e:rollback` in `services/pajama-edge`). Those suites
are regression foundations; they do not already contain every new assertion above.
Use the repository's task-specific Cargo target and cleanup rules for code work.

Freeze workload, source/binary identities, relevant baseline failures, assertion
set and resource ceilings before each implementation experiment. Stop or replan
on authority ambiguity, incompatible version semantics or failed retained-capability
checks. New source or hardware invalidates comparisons that depended on the old one.

## Outcome and reuse

The assessment itself executed no runtime mutation. Subsequent authorized work
implemented resumable cold candidates, exact-digest submission, hash-checked
read-only status, unknown-outcome reconciliation and the 32-asset schema/runtime
alignment. See [the implementation decision](PREPARED_PACKAGE_AUTHORING.md).
Its real rehearsal covers three primitive-prefab revisions and two protocol
clients; it does not close the A1/B2/C3 vehicle-presentation, isolated-preview,
author-to-player agent handoff or remote authorization gates above.

Inspected source identities (SHA-256):

| File | Digest |
| --- | --- |
| `docs/PRODUCT_GOAL.md` | `876a87b25b5cb4737e090d8725109d216170278781edff45752b86b343f776de` |
| `docs/ROADMAP.md` | `a4eb5cd37b633ca61fa0ec23ac394d87076d7e5d78edc6c52b40e97ace11d7cb` |
| `crates/pajama-client/src/app_bootstrap.rs` | `38a51bcda1b766824d7417db0d4a26cee13ee0cc7591a21fbf25f6d7b4813e69` |
| `crates/pajama-world/src/registry.rs` | `d549e4b2d8973366fc4b25e142b464ca84460017b3aa790c4d93506f48a25200` |
| `scripts/authoring/runtime.mjs` | `cd2a7b5d33d8083549cfb2b6e3daf4fdfc97fad018083e2b887af2d21d273cf1` |
| `scripts/system-one/driving-director.mjs` | `a6f567a74478579a021f1a1c90ab97cca600510ede648b28da8e1155f524f7a3` |
| `crates/pajama-content/src/layout.rs` | `bf1d7a47986d8365fcb3ab92f56afb841d6d626a40e96e46f9af3e61fdac9eb3` |