feat(studio): integrate memcard persistence and headless controls
Test / Tests and coverage
Intrepid/Prometeu/Studio/pipeline/pr-master This commit looks good

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:
2026-10-30 11:01:02 +00:00
parent 3a3417eb44
commit 1d8b8c2101
110 changed files with 6502 additions and 85 deletions
@@ -699,7 +699,7 @@
{
"name": "studio_headless_boot",
"authority": "task",
"description": "Boot the project's known build artifact in one managed headless session. Never accepts an arbitrary cartridge path.",
"description": "Boot the project's known build artifact in one managed headless session. Never accepts an arbitrary cartridge path. Memcard requires an explicit choice and protocol 1.1 capability. Optional memcard prepares media before boot; create never replaces existing media.",
"inputSchema": {
"type": "object",
"properties": {
@@ -716,6 +716,40 @@
"buildId": {
"type": "string",
"minLength": 1
},
"memcard": {
"type": "object",
"properties": {
"path": {
"type": "string",
"minLength": 1,
"description": "Explicit image path; omitted selects .studio/memcard.pmc in this project."
},
"action": {
"enum": [
"open",
"create"
]
},
"access": {
"enum": [
"read_write",
"read_only"
]
}
},
"required": [
"action",
"access"
],
"additionalProperties": false
},
"memcardChoice": {
"enum": [
"persistent",
"memory_fresh",
"memory_existing"
]
}
},
"required": [
@@ -797,7 +831,7 @@
{
"name": "studio_headless_reset",
"authority": "task",
"description": "reset the task-owned headless session; preserve runtime semantics and task authority.",
"description": "reset the task-owned headless session; preserve runtime semantics and task authority. A native memcard refusal preserves the session and structured state for a later explicit decision.",
"inputSchema": {
"type": "object",
"properties": {
@@ -810,6 +844,16 @@
"type": "string",
"minLength": 1,
"description": "Current task identity obtained after human grant."
},
"discardUnsaved": {
"type": "boolean",
"description": "Explicit consent to discard remaining dirty game RAM. Default false."
},
"pendingWrites": {
"enum": [
"wait",
"cancel"
]
}
},
"required": [
@@ -1261,7 +1305,7 @@
{
"name": "studio_headless_shutdown",
"authority": "task",
"description": "shutdown the task-owned headless session; preserve runtime semantics and task authority.",
"description": "shutdown the task-owned headless session; preserve runtime semantics and task authority. A native memcard refusal preserves the session and structured state for a later explicit decision.",
"inputSchema": {
"type": "object",
"properties": {
@@ -1274,6 +1318,16 @@
"type": "string",
"minLength": 1,
"description": "Current task identity obtained after human grant."
},
"discardUnsaved": {
"type": "boolean",
"description": "Explicit consent to discard remaining dirty game RAM. Default false."
},
"pendingWrites": {
"enum": [
"wait",
"cancel"
]
}
},
"required": [
@@ -1848,6 +1902,482 @@
"operationId": "operation-advance",
"cancellationRequested": true
}
},
{
"name": "studio_headless_memcard_state",
"authority": "task",
"description": "Observe native media, session, dirty RAM, request, IO and recovery state without executing the guest. Requires negotiated protocol 1.1 memcard capability.",
"inputSchema": {
"type": "object",
"properties": {
"projectRoot": {
"type": "string",
"minLength": 1,
"description": "Absolute root of an open project. Never inferred from UI focus."
},
"taskId": {
"type": "string",
"minLength": 1,
"description": "Current task identity obtained after human grant."
}
},
"required": [
"projectRoot",
"taskId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"oneOf": [
{
"type": "object",
"properties": {
"status": {
"const": "ok"
},
"value": {
"type": "object"
}
},
"required": [
"status",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"const": "error"
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"minLength": 1
},
"message": {
"type": "string"
},
"runtimeError": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"code",
"message"
],
"additionalProperties": false
}
},
"required": [
"status",
"error"
],
"additionalProperties": false
}
]
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false
},
"exampleArguments": {
"projectRoot": "/projects/game",
"taskId": "task-example"
},
"exampleValue": {
"sessionId": "runtime-example"
}
},
{
"name": "studio_headless_memcard_mount",
"authority": "task",
"description": "Explicitly open or create media after reset and before boot; create never replaces existing media. Requires negotiated protocol 1.1 memcard capability.",
"inputSchema": {
"type": "object",
"properties": {
"projectRoot": {
"type": "string",
"minLength": 1,
"description": "Absolute root of an open project. Never inferred from UI focus."
},
"taskId": {
"type": "string",
"minLength": 1,
"description": "Current task identity obtained after human grant."
},
"path": {
"type": "string",
"minLength": 1,
"description": "Explicit image path; omitted selects .studio/memcard.pmc in this project."
},
"action": {
"enum": [
"open",
"create"
]
},
"access": {
"enum": [
"read_write",
"read_only"
]
}
},
"required": [
"projectRoot",
"taskId",
"action",
"access"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"oneOf": [
{
"type": "object",
"properties": {
"status": {
"const": "ok"
},
"value": {
"type": "object"
}
},
"required": [
"status",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"const": "error"
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"minLength": 1
},
"message": {
"type": "string"
},
"runtimeError": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"code",
"message"
],
"additionalProperties": false
}
},
"required": [
"status",
"error"
],
"additionalProperties": false
}
]
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false
},
"exampleArguments": {
"projectRoot": "/projects/game",
"taskId": "task-example",
"action": "open",
"access": "read_write"
},
"exampleValue": {
"sessionId": "runtime-example"
}
},
{
"name": "studio_headless_memcard_unmount",
"authority": "task",
"description": "Unmount idle media outside a resident game session. Requires negotiated protocol 1.1 memcard capability.",
"inputSchema": {
"type": "object",
"properties": {
"projectRoot": {
"type": "string",
"minLength": 1,
"description": "Absolute root of an open project. Never inferred from UI focus."
},
"taskId": {
"type": "string",
"minLength": 1,
"description": "Current task identity obtained after human grant."
}
},
"required": [
"projectRoot",
"taskId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"oneOf": [
{
"type": "object",
"properties": {
"status": {
"const": "ok"
},
"value": {
"type": "object"
}
},
"required": [
"status",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"const": "error"
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"minLength": 1
},
"message": {
"type": "string"
},
"runtimeError": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"code",
"message"
],
"additionalProperties": false
}
},
"required": [
"status",
"error"
],
"additionalProperties": false
}
]
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false
},
"exampleArguments": {
"projectRoot": "/projects/game",
"taskId": "task-example"
},
"exampleValue": {
"sessionId": "runtime-example"
}
},
{
"name": "studio_headless_memcard_reconcile",
"authority": "task",
"description": "Ask the runtime to revalidate the selected same card while suspended; preserves RAM and continuation. Requires negotiated protocol 1.1 memcard capability.",
"inputSchema": {
"type": "object",
"properties": {
"projectRoot": {
"type": "string",
"minLength": 1,
"description": "Absolute root of an open project. Never inferred from UI focus."
},
"taskId": {
"type": "string",
"minLength": 1,
"description": "Current task identity obtained after human grant."
}
},
"required": [
"projectRoot",
"taskId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"oneOf": [
{
"type": "object",
"properties": {
"status": {
"const": "ok"
},
"value": {
"type": "object"
}
},
"required": [
"status",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"const": "error"
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"minLength": 1
},
"message": {
"type": "string"
},
"runtimeError": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"code",
"message"
],
"additionalProperties": false
}
},
"required": [
"status",
"error"
],
"additionalProperties": false
}
]
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false
},
"exampleArguments": {
"projectRoot": "/projects/game",
"taskId": "task-example"
},
"exampleValue": {
"sessionId": "runtime-example"
}
},
{
"name": "studio_headless_memcard_continue_in_memory",
"authority": "task",
"description": "Explicitly continue a suspended session in RAM through the runtime; no durability claim. Requires negotiated protocol 1.1 memcard capability.",
"inputSchema": {
"type": "object",
"properties": {
"projectRoot": {
"type": "string",
"minLength": 1,
"description": "Absolute root of an open project. Never inferred from UI focus."
},
"taskId": {
"type": "string",
"minLength": 1,
"description": "Current task identity obtained after human grant."
}
},
"required": [
"projectRoot",
"taskId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"oneOf": [
{
"type": "object",
"properties": {
"status": {
"const": "ok"
},
"value": {
"type": "object"
}
},
"required": [
"status",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"const": "error"
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"minLength": 1
},
"message": {
"type": "string"
},
"runtimeError": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"code",
"message"
],
"additionalProperties": false
}
},
"required": [
"status",
"error"
],
"additionalProperties": false
}
]
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false
},
"exampleArguments": {
"projectRoot": "/projects/game",
"taskId": "task-example"
},
"exampleValue": {
"sessionId": "runtime-example"
}
}
]
}