Files
prometeu-studio/docs/specs/compiler-languages/pbs/7. Cartridge Manifest and Runtime Capabilities Specification.md
T
bquarkz 1471b427f1
Test / Tests and coverage occurred while executing withChecks step.
Intrepid/Prometeu/Studio/pipeline/pr-master There was a failure building this commit
feat(studio): deliver asset authoring and automation workflows
Add shared human/task asset batches with reviewed atomic publication, explicit
reference rebinds, ownership inspection and qualified glyph/scene budgets.
Expose the same authoring and capacity results through Assets and MCP.

Deliver isolated guest test targets, retained visual evidence and immutable
runtime lifecycle/control observations. Preserve provider qualification and
installed authoring examples alongside the completed discussion lessons.

Close AGD-106 coordination and the delivered discussion workflows through
housekeeping, updating lesson references and preserving qualification limits.
Sound remains outside the asset delivery wave.

Validation: 579 module tests and 31 additional desktop, process and installed
checks passed; native glyph/scene 16/17 boundaries qualified. Discussion
validation passed after housekeeping.
2026-11-11 01:21:25 +00:00

9.3 KiB

Cartridge Manifest and Runtime Capabilities Specification

Status: Draft v1 (Temporary)
Applies to: manifest.json in Prometeu cartridges, runtime capability declaration, and loader capability input

1. Purpose

This document defines the current cartridge manifest contract relevant to runtime loading.

Its purpose is to stabilize:

  • the JSON surface consumed by the cartridge loader,
  • the declaration of cartridge-requested runtime capabilities,
  • the boundary between cartridge packaging and loader authority,
  • the conversion from manifest-facing capability names to runtime capability flags.

This document is intentionally temporary and limited. It does not define cartridge publishing, signing, or store policy.

2. Scope

This document defines:

  • the role of manifest.json in cartridge loading,
  • the current required manifest fields,
  • the new capabilities field,
  • the nominal capability enumeration used in JSON,
  • the mapping from nominal capabilities to runtime CapFlags,
  • the role of the loader when combining manifest capabilities with PBX SYSC.

This document does not define:

  • the full package format beyond the current directory cartridge contract,
  • policy UI or permission prompts,
  • cartridge signing or trust chains,
  • final platform grant policy when the host wants to reduce requested capabilities.

3. Current Cartridge Manifest Role

The cartridge manifest is an external load-time descriptor for a cartridge.

It is not compiled from PBS source directly. It is produced by cartridge packaging tooling and consumed by the runtime loader.

The manifest currently carries:

  • cartridge identity and metadata,
  • asset metadata,
  • preload metadata.

This document adds runtime capability declaration to that same manifest.

4. Manifest Shape

The current manifest shape relevant to this document is:

{
  "magic": "PMTU",
  "cartridge_version": 1,
  "app_id": 1001,
  "title": "Example",
  "app_version": "1.0.0",
  "app_mode": "game",
  "capabilities": ["gfx2d", "input"],
  "asset_table": [],
  "preload": []
}

Rules:

  • magic identifies a Prometeu cartridge manifest,
  • cartridge_version identifies the cartridge manifest format line,
  • capabilities declares the cartridge's requested runtime capabilities,
  • asset_table and preload remain separate concerns.
  • manifest.json MUST NOT declare nominal entrypoint authority for PBS v1 executable boot.
  • Runtime boot authority is the physical published entrypoint at function index 0.

5. capabilities

5.1 General rules

capabilities is a manifest-facing nominal list.

Rules:

  • capabilities is optional,
  • when omitted, it behaves as an empty list,
  • capability names are canonical lowercase identifiers,
  • duplicate entries are invalid,
  • unknown capability names are manifest errors.

5.2 Nominal capability set

The current nominal capability set is:

  • system
  • gfx2d
  • composer
  • input
  • audio
  • fs
  • log
  • asset
  • bank

These names are the normative manifest-facing representation.

For the low-level PBS asset host surface, the capability spelling MUST remain asset in the singular. PBS SDK owner names such as LowAssets do not change the manifest/runtime capability spelling.

6. Relationship to Runtime CapFlags

The runtime may continue to represent capabilities internally as a bitflag set.

That internal representation is an implementation detail.

The normative external model is:

  • a nominal capability enum in the manifest,
  • deterministic conversion by the loader into runtime flags.

Canonical mapping:

  • system -> SYSTEM
  • gfx2d -> GFX2D
  • composer -> COMPOSER
  • input -> INPUT
  • audio -> AUDIO
  • fs -> FS
  • log -> LOG
  • asset -> ASSET
  • bank -> BANK

For asset host bindings, PBS declarations MUST use [Capability(name = "asset")] so that host admission, PBX host binding metadata, and cartridge capability checks all converge on the same runtime flag.

This means the recommended runtime design is:

  1. deserialize capabilities into a nominal enum or equivalent validated representation,
  2. convert that validated set into internal CapFlags,
  3. use those flags during host-binding resolution.

7. Loader Semantics

The loader consumes both:

  • the cartridge manifest,
  • and the PBX SYSC table.

Required behavior:

  1. parse manifest.json,
  2. parse capabilities,
  3. convert the nominal capability list to internal capability flags,
  4. parse program.pbx,
  5. resolve each SYSC entry against the host registry,
  6. obtain required capabilities from resolved syscall metadata,
  7. fail if required capabilities are not granted by the manifest/policy environment.

The manifest alone does not make a program valid. The manifest must be consistent with the actual syscalls required by the PBX.

8. Requested vs Granted Authority

The manifest declares requested cartridge capabilities.

The loader/runtime environment is the authority that decides what is granted.

Current direction:

  • in the initial runtime model, the manifest may act as the immediate source of granted capabilities,
  • a future platform policy layer may reduce or deny requested capabilities before final load.

Normative rule:

  • the compiler does not grant capabilities,
  • the PBX does not grant capabilities,
  • cartridge/runtime loading is the authority boundary.

9. Relationship to Compiler and Packer

Responsibilities are split as follows:

Compiler:

  • compiles source to PBX,
  • emits SYSC,
  • emits HOSTCALL <sysc_index>,
  • computes deterministic requiredCapabilities from admitted host bindings for packer tooling,
  • does not grant authority.

Packer:

  • produces the cartridge manifest,
  • declares requested runtime capabilities,
  • packages manifest.json, program.pbx, and assets.

Loader:

  • reads the manifest,
  • derives or receives granted capability flags,
  • validates those capabilities against PBX host requirements.

10. Validation Rules

The cartridge manifest must fail validation if:

  1. capabilities contains an unknown name,
  2. capabilities contains duplicates,
  3. capabilities is not an array of strings or nominal enum values under the chosen serialization form.

Cartridge load must fail if:

  1. the manifest omits a capability required by a resolved SYSC entry,
  2. a future platform policy denies a capability required by a resolved SYSC entry.

11. Serialization Guidance

The recommended manifest-facing model is a nominal enum list, not numeric masks.

Recommended JSON:

{
  "capabilities": ["gfx2d", "input", "audio"]
}

Rejected as normative surface:

  • raw integer bitmasks,
  • hex masks,
  • unnamed positional arrays.

Rationale:

  • nominal capability names are readable,
  • manifest diffs remain understandable,
  • packer and tooling validation is straightforward,
  • runtime may still use bitflags internally after conversion.

12. Current Decision Summary

The current temporary contract is:

  1. manifest.json is the cartridge-facing load descriptor.
  2. capabilities is declared in manifest.json, not in prometeu.json.
  3. capabilities uses nominal canonical names such as gfx2d, composer, and audio.
  4. The runtime may keep using internal CapFlags.
  5. The loader converts nominal manifest capabilities into internal flags.
  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 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.

Test selection and negotiated log observation

Project testTargets version 1 MUST select an alternate source/lifecycle context without changing the production cartridge identity, appId, machine profile or asset/dependency rules. Test builds MUST retain target/source/configuration/assets provenance in their Studio result and use exclusive target/build output paths. Production Play MUST NOT consume a test build by recency.

Structured test execution MUST require negotiated headless protocol 1.2 capability log_read before guest execution. A provider without that capability MUST refuse structured tests explicitly while preserving compatible production flows. get_logs MUST be read-only and non-destructive, using nullable exclusive afterSequence and limit 1..1024. Lossless uint64 sequences include zero with a null initial cursor. The result MUST retain session/epoch, typed native records, retention bounds, next cursor and gap/overflow evidence. Wall-clock timestamps MUST NOT form deterministic assertion oracles. This is a tooling extension over existing sdk/log, not a new guest syscall/ABI or an increased execution budget.

Test media MUST be explicit memory_fresh or a disposable image under .studio/test-runs/<runId>/. Production/default/personal card paths MUST NOT be selected implicitly. Persisted-save proof requires closing the process and reopening the same disposable card in a new one; RAM state and commit acknowledgement are not durability proof. Pending-data refusals MUST remain native and require explicit recovery, without silent discard. Provider writes/builds await the separate runtime authorization gate in PLN-0172.