feat(studio): integrate memcard persistence and headless controls
Persist cartridge identity and slot configuration, add MemcardBoot and the MemcardBuffer SDK, and consume the runtime's negotiated memcard host controls with protected teardown. Qualify save/reopen and version upgrades through distinct configured runtime processes. Include specs, examples, regression evidence and the consolidated discussion lesson.
This commit is contained in:
@@ -206,9 +206,16 @@ See [Concrete generic structs and free functions](17.%20Generic%20Structs%20and%
|
||||
## Guest hook marker identity
|
||||
|
||||
LifecycleMarker explicitly distinguishes NONE, INIT, FRAME, BEFORE_PAUSE and
|
||||
BEFORE_RESUME. Preserve marker attributes and source spans alongside the marker;
|
||||
BEFORE_RESUME and MEMCARD_BOOT. Preserve marker attributes and source spans alongside the marker;
|
||||
never reconstruct the role from a function name or an import alias. Invalid
|
||||
attribute targets/combinations MUST be diagnosed rather than silently treated
|
||||
as ordinary functions. Generic substitution/import processing MUST preserve
|
||||
canonical source identity and marker metadata. No MemcardBoot marker is defined
|
||||
by this surface.
|
||||
canonical source identity and marker metadata. The additional MEMCARD_BOOT marker follows the dedicated memcard contract.
|
||||
|
||||
|
||||
## Memcard integration
|
||||
|
||||
The [Memcard Bootstrap and SDK contract](<26. Memcard Bootstrap and SDK Specification.md>)
|
||||
defines the additional [MemcardBoot] marker, exact signature, neutral once-only
|
||||
bootstrap, project identity/slot validation and complete installed mem ABI.
|
||||
Its requirements apply in addition to this chapter; pause/resume remain independent.
|
||||
|
||||
@@ -283,3 +283,11 @@ MUST preserve bodies and metadata. Common code consumes neutral typed roles,
|
||||
never PBS ASTs/names. The ordinary assembled entry remains physical FunctionId
|
||||
zero; hook targets are nonzero after deterministic linking. Common Registry/PBX
|
||||
validation and production runtime admission remain mandatory defenses.
|
||||
|
||||
|
||||
## Memcard integration
|
||||
|
||||
The [Memcard Bootstrap and SDK contract](<26. Memcard Bootstrap and SDK Specification.md>)
|
||||
defines the additional [MemcardBoot] marker, exact signature, neutral once-only
|
||||
bootstrap, project identity/slot validation and complete installed mem ABI.
|
||||
Its requirements apply in addition to this chapter; pause/resume remain independent.
|
||||
|
||||
@@ -0,0 +1,153 @@
|
||||
# Memcard Bootstrap and SDK Specification
|
||||
|
||||
Owner: compiler/pbs; propagation to compiler/general and studio.
|
||||
|
||||
## Source configuration and identity
|
||||
|
||||
`prometeu.json` accepts numeric integral `app_id` (uint32, 0..4294967295) and
|
||||
optional integral `memcard_slots` (1..64). Strings, booleans, Null, fractions and
|
||||
out-of-range values MUST fail validation. Memcard opt-in MUST have exactly one
|
||||
role 3 target, capability memcard and a bootstrap boundary. Memcard imports without
|
||||
that complete declaration MUST fail before launch; ordinary projects remain unchanged.
|
||||
|
||||
Studio persists an explicit initial app_id for new projects and adopts the
|
||||
legacy generated value once for an older project before shipping. Adoption MUST
|
||||
preserve unrelated manifest fields and existing explicit IDs. Rename, version,
|
||||
language and stdlib changes MUST NOT derive a new ID. A copied manifest is the
|
||||
same game; a distinct game needs an explicitly different identity. The source
|
||||
identity is propagated losslessly to build/manifest.json, with slots only when
|
||||
memcard is enabled. Media path and session policy are local host configuration.
|
||||
|
||||
## Marker and lifecycle boundary
|
||||
|
||||
```pbs
|
||||
[MemcardBoot]
|
||||
fn restore(context: long) -> int {
|
||||
// Inspect admitted RAM and provide presentation through @sdk:mem.
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
The marker MUST select a nongeneric top-level user function of exact signature
|
||||
(long)->int with no captures. It accepts no arguments and MUST NOT combine with
|
||||
another lifecycle marker. Doc metadata, global access and internal closures remain
|
||||
allowed. Uniqueness is per compiled image and canonical source identity, including
|
||||
imports and reexports. Names and normal direct calls do not grant lifecycle authority.
|
||||
The target and its dependencies MUST survive optimization without source callers.
|
||||
Registry role is 3 and physical FunctionId MUST NOT be zero.
|
||||
|
||||
PBS contributes an explicit neutral host-bootstrap request through serializable
|
||||
common lifecycle declarations. Common assembly emits mem.bootstrap@1 HOSTCALL
|
||||
with 0 arguments/1 Int32 result after all file/module/project initialization,
|
||||
inside the once-per-boot guard and before the first Frame. It discards the gate
|
||||
result after runtime admission. It MUST NOT directly invoke the role, inspect
|
||||
PBS names or teach the runtime Init/Frame concepts. Ordinary images emit no gate.
|
||||
|
||||
READY=0 and INCONSISTENT=1, diagnostic text (at most 1024 UTF-8 bytes), continuation,
|
||||
budget/trap behavior and provisional registration follow the runtime contract.
|
||||
A commit submitted in the hook stays pending until READY/coherent registration;
|
||||
the hook MUST return rather than await it. Resume/remount does not rerun Init or
|
||||
bootstrap. BeforePause may submit/return and BeforeResume may query across frames.
|
||||
|
||||
## MemcardBuffer
|
||||
|
||||
`@sdk:mem` exports the nongeneric opaque source type MemcardBuffer. Construct
|
||||
`new MemcardBuffer(capacity)` with int capacity in 0..4096. Storage is fixed length
|
||||
and zero initialized; `capacity() -> int`, `read(index: int) -> int` and
|
||||
`write(index: int, value: int) -> void` provide checked access. Reads always return
|
||||
an int, with no vacancy/optional representation. Values MUST be in 0..255;
|
||||
invalid capacity/index/value traps before mutation. Copies alias the same buffer.
|
||||
|
||||
The compiler MUST identify the origin-verified SDK declaration, not its spelling,
|
||||
and lower it directly to concrete Array<Int32> in common Registry/PBX. There is
|
||||
no Struct wrapper, Dynamic boxing, automatic conversion from ordinary arrays,
|
||||
copying adapter, new runtime BuiltinId or syscall. Allocation and work obey the
|
||||
existing VM limits and element charge (four bytes per element). Ordinary PBS
|
||||
arrays retain their existing vacancy and optional-read semantics.
|
||||
|
||||
The same carrier serves slot_read, slot_write and presentation. Successful reads
|
||||
mutate the same buffer only over the returned range. The buffer owns guest RAM,
|
||||
not a persistent logical slot or the runtime's asynchronous snapshot.
|
||||
|
||||
## Installed SDK
|
||||
|
||||
`import {Mem} from @sdk:mem;` selects the forwarding facade. LowMem contains the
|
||||
exact module mem/version 1/capability memcard host bindings. Bootstrap is compiler
|
||||
owned; a game MUST NOT manually substitute a direct hook call or bootstrap call.
|
||||
|
||||
All numeric domain results/context/request use long, except the Int32 bootstrap
|
||||
result. Flags are bool; text is str; ranges/local slots are int; presentation
|
||||
format version is long to represent uint32. Byte transport is MemcardBuffer, each
|
||||
value 0..255, at most 4096 per transfer; slot capacity is 65536 private bytes.
|
||||
|
||||
| Native ID | Binding | Arguments | Results (native order) |
|
||||
| --- | --- | ---: | --- |
|
||||
| 0x4200 | bootstrap | 0 | int readiness |
|
||||
| 0x4201 | slot_count | 1 | status, count |
|
||||
| 0x4202 | slot_stat | 2 | status, has_payload, used_bytes, generation, update_at, crc32c, dirty |
|
||||
| 0x4203 | slot_read | 6 | status, bytes_read |
|
||||
| 0x4204 | slot_write | 6 | status, bytes_written |
|
||||
| 0x4205 | slot_commit | 2 | status, request |
|
||||
| 0x4206 | slot_clear | 2 | status |
|
||||
| 0x4207 | query | 2 | status, state, reason |
|
||||
| 0x4208 | release | 2 | status |
|
||||
| 0x4209 | info | 1 | status, mode, is_new, recovered, degraded, write_blocked |
|
||||
| 0x420A | metadata | 1 | status, title, data_format_version, created_at |
|
||||
| 0x420B | presentation | 8 | status |
|
||||
| 0x420C | diagnostic | 2 | status |
|
||||
| 0x420D | publish_presentation | 1 | status, request |
|
||||
|
||||
slot_stat.has_payload is numeric 0/1; dirty/info health flags are bool.
|
||||
The PBS source tuple groups generation/update_at/crc32c under `stat.durable`;
|
||||
recursive flattening preserves all seven native results and their exact types/order,
|
||||
without increasing the language's six-field tuple bound. CRC/generation/timestamp
|
||||
are durable descriptor data; used_bytes/dirty describe RAM. Unsigned 64-bit values
|
||||
retain their bit pattern in long. This SDK introduces no general save codec.
|
||||
|
||||
The installed facade uses origin-checked exact host forwarding. Its callsites
|
||||
emit the native operation directly, preserving error Null payloads until the
|
||||
caller checks status; an intermediate typed-return wrapper MUST NOT turn an
|
||||
ordinary domain error into a VM type trap. Argument order and evaluation are
|
||||
preserved. The private HostForward binding accepts only a single exact host
|
||||
return of unchanged positional parameters and matching result ABI.
|
||||
|
||||
Every operation checks status before using payload. Error payload positions are
|
||||
Null and MUST remain unobserved on a failed status. Status 0 is OK; 3 no space,
|
||||
4 access denied, 5 corrupt, 6 indeterminate, 7 unavailable, 8 invalid state/canceled,
|
||||
9 busy, 10 read-only/counter exhausted, 11 invalid range, 12 unsupported,
|
||||
13 IO error, 16 out of memory. Type/heap/carrier violations are VM traps.
|
||||
|
||||
Submitting a commit does not establish persistence. Query state 0 pending,
|
||||
1 success, 2 failure, 3 indeterminate, 4 memory-only is independent of reason.
|
||||
Reason 15 is deadline/restart; Success/15 is valid. Only one request/result is
|
||||
retained until release. Release MUST NOT free in-flight resources. A source slot
|
||||
is readable but rejects writes/clear with BUSY while committing; other slots
|
||||
continue. Clear changes RAM and requires explicit commit. No implicit retries,
|
||||
autosave or disk waits are hidden by the facade.
|
||||
|
||||
## Provider boundary and qualification
|
||||
|
||||
Runtime owns hosts/headless/storage, explicit persistent/fresh-RAM/load-existing-RAM
|
||||
choices, concurrent image access, discard confirmation and reconciliation. Studio
|
||||
uses supported public configuration/operations/diagnostics of its configured
|
||||
installation. Missing/failed media MUST NOT silently choose memory-only. Image
|
||||
creation is explicit and never overwrites a file. The development image location
|
||||
is .studio/memcard.pmc, outside build output; shared images require explicit choice.
|
||||
|
||||
Transport loss/timeout/forced termination cannot prove rollback or durable failure.
|
||||
A missing provider surface is an explicit external dependency, never invented flags,
|
||||
a second host or a duplicated SO/Hub UI. RAM survives pause/resume.
|
||||
|
||||
The installed opt-in `memcard/` subproject demonstrates presentation, status-first
|
||||
read/write, query and release separately from the ordinary example. Qualification
|
||||
MUST distinguish source/PBX, native production-host and configured-process evidence.
|
||||
Complete persistence proof requires SUCCESS, process termination, a new process on
|
||||
the same image, exact bytes, and the same result after a project-version change.
|
||||
Record provider revision, OS/architecture, runtime dev/release and PBS optimizer
|
||||
variants. Native injection is useful contract evidence but never substitutes for
|
||||
that process proof.
|
||||
|
||||
## References
|
||||
|
||||
- [Runtime memcard contract](../../../../../runtime/docs/specs/runtime/08-save-memory-and-memcard.md).
|
||||
- [Common Registry](<../../compiler/25. Typed Registry and PBX v0 Specification.md>).
|
||||
@@ -80,7 +80,7 @@ Rules:
|
||||
- Attributes are not first-class values and are not reflectable in v1 core.
|
||||
- Attributes do not automatically survive into runtime or bytecode artifacts.
|
||||
- An attribute affects runtime artifacts only when another specification defines an explicit lowering for its semantic effect.
|
||||
- In v1 core, the normative reserved attributes are `Host`, `Capability`, `AssetLowering`, `BuiltinType`, `BuiltinConst`, `IntrinsicCall`, `Init`, `Frame`, `BeforePause`, `BeforeResume`, `InitAllowed`, and `Doc`.
|
||||
- In v1 core, the normative reserved attributes are `Host`, `Capability`, `AssetLowering`, `BuiltinType`, `BuiltinConst`, `IntrinsicCall`, `Init`, `Frame`, `BeforePause`, `BeforeResume`, `MemcardBoot`, `InitAllowed`, and `Doc`.
|
||||
- `Host` is valid only on a host method signature declared directly inside a reserved stdlib/interface-module `declare host` body.
|
||||
- `Capability` is valid only on a host method signature declared directly inside a reserved stdlib/interface-module `declare host` body.
|
||||
- `AssetLowering` is valid only on a host method signature declared directly inside a reserved stdlib/interface-module `declare host` body.
|
||||
@@ -858,3 +858,11 @@ Direct calls remain normal calls and do not request an OS transition or create
|
||||
a controlled invocation. Runtime FunctionId zero is reserved for the ordinary
|
||||
entry; physical hook IDs are validated after linking. Init/Frame requirements
|
||||
and their frontend/common assembly remain unchanged.
|
||||
|
||||
|
||||
## Memcard integration
|
||||
|
||||
The [Memcard Bootstrap and SDK contract](<26. Memcard Bootstrap and SDK Specification.md>)
|
||||
defines the additional [MemcardBoot] marker, exact signature, neutral once-only
|
||||
bootstrap, project identity/slot validation and complete installed mem ABI.
|
||||
Its requirements apply in addition to this chapter; pause/resume remain independent.
|
||||
|
||||
+8
@@ -570,3 +570,11 @@ See [PBS generic contracts](16.%20Generic%20Contracts%20Specification.md).
|
||||
Generic struct/function barrels export declarations and ordered parameters, including complete function signatures, rather than enumerated specializations. Imports and aliases preserve nominal origins and definition-scoped bodies/private helpers. Specializations are shared across equivalent uses and do not export private dependencies. SDK and program sources use the same language machinery.
|
||||
|
||||
See [Concrete generic structs and free functions](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md).
|
||||
|
||||
|
||||
## Memcard integration
|
||||
|
||||
The [Memcard Bootstrap and SDK contract](<26. Memcard Bootstrap and SDK Specification.md>)
|
||||
defines the additional [MemcardBoot] marker, exact signature, neutral once-only
|
||||
bootstrap, project identity/slot validation and complete installed mem ABI.
|
||||
Its requirements apply in addition to this chapter; pause/resume remain independent.
|
||||
|
||||
+8
@@ -252,3 +252,11 @@ The current temporary contract is:
|
||||
6. PBX `SYSC` declares required host bindings, not authority.
|
||||
7. Loader validation fails if PBX host requirements exceed granted cartridge capabilities.
|
||||
8. `manifest.json` is not entrypoint authority for PBS v1 boot.
|
||||
|
||||
|
||||
## Memcard integration
|
||||
|
||||
The [Memcard Bootstrap and SDK contract](<26. Memcard Bootstrap and SDK Specification.md>)
|
||||
defines the additional [MemcardBoot] marker, exact signature, neutral once-only
|
||||
bootstrap, project identity/slot validation and complete installed mem ABI.
|
||||
Its requirements apply in addition to this chapter; pause/resume remain independent.
|
||||
|
||||
@@ -411,4 +411,12 @@ effects. Fatal traps/host failures and unfinished fuel exhaustion fail the
|
||||
session, block gameplay and retain the existing crash envelope, without retry,
|
||||
rollback or compensation. HALT is OS termination, not successful hook return.
|
||||
Existing capability/service rules apply, without auto-save, flush, disk wait,
|
||||
transition veto or reason argument. MemcardBoot and persistence are separate.
|
||||
transition veto or reason argument. MemcardBoot and persistence follow the dedicated memcard chapter.
|
||||
|
||||
|
||||
## Memcard integration
|
||||
|
||||
The [Memcard Bootstrap and SDK contract](<26. Memcard Bootstrap and SDK Specification.md>)
|
||||
defines the additional [MemcardBoot] marker, exact signature, neutral once-only
|
||||
bootstrap, project identity/slot validation and complete installed mem ABI.
|
||||
Its requirements apply in addition to this chapter; pause/resume remain independent.
|
||||
|
||||
@@ -202,3 +202,5 @@ IDs returned by project context. The alias catalog is generated by the frontend
|
||||
build from this single source directory. It does not read a second spec tree.
|
||||
The internal resource path is `pbs-knowledge/specs/<numbered filename>.md`;
|
||||
reference clients resolve IDs through the catalog instead of constructing paths.
|
||||
|
||||
- [Memcard Bootstrap and SDK](<26. Memcard Bootstrap and SDK Specification.md>): opt-in persistence producer and runtime-consumer boundaries.
|
||||
|
||||
@@ -113,8 +113,8 @@ requires relocating every PUSH_CONST index; changing only the table is invalid.
|
||||
|
||||
Roles are None 0, BeforePause 1, BeforeResume 2 and MemcardBoot 3. Nonzero roles
|
||||
are unique, cannot target entry zero and cannot capture. Pause/resume have empty
|
||||
signatures; MemcardBoot has `(Int64) -> Int32`. This metadata does not implement
|
||||
frontend hook selection, mem.bootstrap gating or persistence.
|
||||
signatures; MemcardBoot has `(Int64) -> Int32`. Frontend-owned role selection and neutral common bootstrap assembly implement
|
||||
the producer boundary; runtime owns persistence and admission.
|
||||
|
||||
Implementations are unique per Struct/Trait pair, complete and ordered. Each
|
||||
method target has an exact signature with a concrete Struct receiver first,
|
||||
@@ -286,4 +286,24 @@ Common emission validates unique nonzero roles, empty pause/resume signatures
|
||||
and capture lists, and final hook FunctionIds other than zero. The ordinary
|
||||
entry and synthetic Init/Frame assembly keep role None. Calling a hook as an
|
||||
ordinary function does not request an OS transition. PBS marker syntax belongs
|
||||
to its frontend; MemcardBoot selection/bootstrap is a separate producer scope.
|
||||
to its frontend. MemcardBoot uses a typed role and an explicit neutral bootstrap
|
||||
request, specified below.
|
||||
|
||||
|
||||
## Neutral host bootstrap requests
|
||||
|
||||
IRLifecycleFileDeclaration and IRLifecycleDeclaration carry ordered serializable
|
||||
bootstrapCalls, each ordinary HostCallMetadata (module/name/version/argSlots/retSlots).
|
||||
Empty requests preserve the existing lifecycle. Aggregation preserves requests
|
||||
and deduplicates identical boundaries from repeated file contributions. Frontends
|
||||
MUST request a zero-argument boundary explicitly; the assembler MUST NOT inspect
|
||||
language syntax/names. It emits CALL_HOST and discards each result after ordered
|
||||
module/project initialization, before setting the boot guard and invoking Frame.
|
||||
Requests that require operands from initializer stacks MUST fail validation.
|
||||
|
||||
The memcard producer requests mem.bootstrap@1, 0→1. Its role 3 target and callees
|
||||
are external-entry retention roots. Production project validation requires coherent
|
||||
slots 1..64, capability memcard, unique role 3 and the boundary before launch.
|
||||
This is distinct from a direct CALL to the hook. Host storage and headless transport
|
||||
remain runtime-owned and absent from the common IR. See the PBS
|
||||
[producer contract](<../compiler-languages/pbs/26. Memcard Bootstrap and SDK Specification.md>).
|
||||
|
||||
@@ -234,6 +234,16 @@ Reset leaves the runtime unbooted and clears its capture. It does not implicitly
|
||||
boot the cartridge again. A subsequent explicit boot may reuse the session's
|
||||
known build cartridge; an invalidated process requires an explicit new session.
|
||||
|
||||
Memcard use negotiates the provider's protocol 1.1 extension explicitly. The
|
||||
adapter projects mount/choice/state/reconcile/RAM-continuation and protected
|
||||
teardown as specified in [Project-local memcard integration](<8. Project-Local Studio State Specification.md#published-memcard-host-integration>).
|
||||
Native `memcard_error` refusal preserves structured state and the live channel;
|
||||
it does not trigger process termination or detach. `action_required` preserves
|
||||
known progress and becomes `ACTION_REQUIRED`, with the resident session retained.
|
||||
Human reclaim never supplies discard consent. Following a protected cleanup
|
||||
refusal, DEV offers a separate confirmed discard/retry action; canceling it
|
||||
preserves the process and control guard.
|
||||
|
||||
| Configurable, handshake-advertised limit | Default |
|
||||
| --- | --- |
|
||||
| Frames per advance | 600 |
|
||||
|
||||
@@ -183,15 +183,20 @@ Input objects reject undeclared fields. IDs are nonempty opaque strings.
|
||||
| `studio_control_release` | task | none | state=MANUAL, only after ordered cleanup |
|
||||
| `studio_language_query` | task | operation, parameters | Supported LSP query/proposal result |
|
||||
| `studio_build_start` | task | clientRequestId | operationId, clientRequestId, state |
|
||||
| `studio_headless_boot` | task | buildId | sessionId, buildId; boot uses the task's known build |
|
||||
| `studio_headless_reset` | task | none | Current session/reset state |
|
||||
| `studio_headless_boot` | task | buildId, optional memcard/memcardChoice | sessionId, buildId; boot uses the task's known build |
|
||||
| `studio_headless_reset` | task | optional discardUnsaved/pendingWrites | Current session/reset state and negotiated memcard state |
|
||||
| `studio_headless_set_input` | task | input | Current session acknowledgement |
|
||||
| `studio_headless_clear_input` | task | none | Current session acknowledgement |
|
||||
| `studio_headless_advance` | task | clientRequestId, frames | operationId, clientRequestId, state |
|
||||
| `studio_headless_capture` | task | none | Canonical image and metadata in section 6 |
|
||||
| `studio_headless_state` | task | none | Current session and runtime state |
|
||||
| `studio_headless_fault` | task | none | fault object or null, preserving structural fault details |
|
||||
| `studio_headless_shutdown` | task | none | Session shutdown acknowledgement after managed cleanup |
|
||||
| `studio_headless_shutdown` | task | optional discardUnsaved/pendingWrites | Session shutdown acknowledgement/final memcard state after managed cleanup; native refusal preserves session |
|
||||
| `studio_headless_memcard_state` | task | none | Native media/session/dirty/request/IO/recovery state |
|
||||
| `studio_headless_memcard_mount` | task | action, access, optional path | Explicit idle open/create through the provider |
|
||||
| `studio_headless_memcard_unmount` | task | none | Explicit idle media release |
|
||||
| `studio_headless_memcard_reconcile` | task | none | Runtime-owned same-card revalidation while suspended |
|
||||
| `studio_headless_memcard_continue_in_memory` | task | none | Explicit runtime-owned RAM continuation while suspended |
|
||||
| `studio_operation_get` | task | exactly one of operationId/clientRequestId | State, known progress, typed result/failure |
|
||||
| `studio_operation_cancel` | task | operationId | operationId, cancellationRequested |
|
||||
|
||||
@@ -401,6 +406,17 @@ that process, invalidates previous buildIds and requires a fresh explicit boot.
|
||||
Synchronous headless failures finish their worker before returning the error,
|
||||
so a corrective call cannot race the failed worker's admission lock.
|
||||
|
||||
Memcard boot options are local host configuration, never an arbitrary cartridge
|
||||
path. `memcard` contains explicit action/access and optional image path;
|
||||
`memcardChoice` is an explicit provider choice. Protocol 1.1 plus capability
|
||||
`memcard` is required before mutation. `MEMCARD_ERROR` preserves native
|
||||
operation/reason/state in `runtimeError`. Refused reset/shutdown keep the attached
|
||||
session and task available for inspection and a later explicit choice.
|
||||
`discardUnsaved` and `pendingWrites` are forwarded only when supplied. Neither
|
||||
ordinary Stop/task release nor connection loss supplies discard consent.
|
||||
See [published memcard host integration](<8. Project-Local Studio State Specification.md#published-memcard-host-integration>)
|
||||
for local paths, protected human reclaim and `ACTION_REQUIRED` outcomes.
|
||||
|
||||
Task-local operation/build records are discarded after worker termination on
|
||||
return, revocation or project closure. Cleanup failures never restore authority;
|
||||
the records are still discarded after managed work stops. Neither connection
|
||||
@@ -536,7 +552,8 @@ authentication, Origin, endpoint/method/version handling, tool dispatch, malform
|
||||
or oversized input, closure, restart and old-token rejection. Provider doubles
|
||||
exist only in tests. Composition starts/closes transport with Studio.
|
||||
|
||||
The production registry composes all 17 tools as of step 23, including headless
|
||||
The production registry composes 22 tools, including five negotiated memcard
|
||||
controls and the original headless
|
||||
handlers bound to the actual `HeadlessProcessGateway`. Missing project runtime
|
||||
configuration fails at boot with `RUNTIME_UNAVAILABLE`; tool discovery does not
|
||||
grant authority or launch a process. No fake runtime is shipped.
|
||||
|
||||
@@ -138,3 +138,73 @@ commit. Failure aborts credentials/files and reports a failed grant. Revoke/clos
|
||||
invalidate credentials before asynchronous work cleanup, then remove owned
|
||||
publication and release ownership. File cleanup failure MUST NOT prevent runtime
|
||||
cancellation. An already-admitted release response MUST remain deliverable.
|
||||
|
||||
|
||||
## Cartridge identity and local memcard configuration
|
||||
|
||||
Versioned prometeu.json owns explicit numeric uint32 app_id and optional integral
|
||||
memcard_slots in 1..64. Studio project references preserve both. New projects persist
|
||||
their initial identity. Before shipping a legacy project, the current legacy
|
||||
name/version/language/stdlib hash is adopted once via atomic manifest replacement,
|
||||
with unknown fields preserved. Existing explicit IDs are authoritative and are
|
||||
never regenerated on upgrades/rename/clone. A copied manifest represents the same
|
||||
game; a distinct game requires an explicitly different identity. Invalid values
|
||||
MUST fail rather than fall back to hashing. build/manifest.json propagates ID and
|
||||
coherent slots/capability. Compiler validation additionally requires MemcardBoot
|
||||
and the bootstrap boundary for memcard images.
|
||||
|
||||
Media path and session choice are local runtime-host configuration. The development
|
||||
image location is `.studio/memcard.pmc`, outside rebuildable output; shared external
|
||||
images require explicit selection. Studio creates no media implicitly and never
|
||||
replaces existing saves. Runtime owns creation/mounting/concurrency, headless,
|
||||
player-choice/dirty-discard workflow and reconciliation. Studio consumes only a
|
||||
published interface of its configured runtime installation. It MUST NOT invent
|
||||
flags/JSONL fields, implement an alternative host or duplicate SO/Hub.
|
||||
|
||||
Missing provider controls/dirty-pending diagnostics remain explicit integration
|
||||
dependencies. They do not alter the guest ABI or permit silent memory-only fallback.
|
||||
A process failure does not establish whether publication occurred; supervision
|
||||
errors MUST NOT be presented as durable save failure/rollback. Native host evidence
|
||||
and configured-process reopen evidence MUST be reported separately.
|
||||
|
||||
### Published memcard host integration
|
||||
|
||||
Memcard projects MUST negotiate protocol 1.1 and capability `memcard` with their
|
||||
configured installation before mounting media or booting. Ordinary projects keep
|
||||
the 1.0 flow. Runtime version strings are not capability detection.
|
||||
|
||||
`studio_headless_boot` accepts optional `memcard` mount configuration (`path`,
|
||||
explicit `action:open/create`, explicit `access:read_write/read_only`) and the
|
||||
explicit `memcardChoice:persistent/memory_fresh/memory_existing`. Studio sends
|
||||
the published `memcard_mount` before `boot`, preserving native domain failures.
|
||||
Omitted mount path selects the project-local development path; it does not imply
|
||||
mounting, creation or a memory choice. An explicit create at that default path
|
||||
may create its `.studio` parent; the runtime alone formats and creates the media.
|
||||
Explicit external paths resolve against the project root. No open failure may
|
||||
be retried as create, repaired or converted into a RAM choice automatically.
|
||||
|
||||
Local `.studio/setup.json` MAY set `memcardPath` to explicitly select another
|
||||
image; relative selections resolve against the project root. Desktop Debug passes
|
||||
the published `--memcard` option for opt-in projects, and headless mount defaults
|
||||
to that same selection. An explicit per-session mount path overrides it for that
|
||||
session. No desktop `--create-memcard` is inferred from file absence or launch.
|
||||
Ordinary projects receive no media startup options. The default development
|
||||
selection remains `.studio/memcard.pmc` when `memcardPath` is absent.
|
||||
|
||||
The consumer exposes native state, idle mount/unmount, same-card reconciliation
|
||||
and explicit continuation in memory. These operations preserve the runtime's
|
||||
state and choices; they do not expose private payloads. Reset/shutdown accept
|
||||
explicit `discardUnsaved` and `pendingWrites:wait/cancel`; omission preserves
|
||||
provider defaults. A native refusal MUST retain the process, channel and session
|
||||
association. A subsequent explicit decision can retry. The structured
|
||||
`memcard_error` is carried as `MEMCARD_ERROR` with unchanged native details.
|
||||
An `action_required` advance is an `ACTION_REQUIRED` outcome with native
|
||||
diagnostics, preserving known completed frames and the resident session.
|
||||
|
||||
Human reclaim first attempts protected shutdown without discard consent. On
|
||||
refusal it keeps manual mutation locked and exposes the diagnostics. DEV offers
|
||||
a separately confirmed discard of unsaved game RAM and cancellation of admitted
|
||||
writes before retrying cleanup. Canceling that confirmation sends no consent.
|
||||
Neither task release, Stop, reclaim nor a timeout implicitly permits discard.
|
||||
Forced termination remains infrastructure failure with unknown publication
|
||||
outcome; it MUST NOT manufacture a durable save result.
|
||||
|
||||
Reference in New Issue
Block a user