Hosted system packages

A hosted system package is an immutable .aethersystem.zip artifact. It defines the game vocabulary for one world without loading creator code into Aether's server process. A world pins the system id, version, SHA-256 artifact identity, and complete dependency graph.

Repository-owned systems may still use the source-composed defineSystem path. Marketplace systems use the hosted artifact path described here. The two paths do not give Marketplace code the same trust as Aether code.

#What a system owns

aether.system.json contains a system object and an inventory of project files. The system object can declare:

• portable document schemas and creation defaults;
• document capabilities and owner-only or GM-only field projection;
• compiled native sheets, rolls, derived expressions, effects, and initiative;
• starter documents that are inserted only during the selected installation flow;
• QuickJS automation entries and iframe companion applications;
• versioned seeded generators with typed inputs and one declared output type;
• required and optional packages plus typed service requirements;
• ordered forward migrations and explicit reverse migrations;
• Aether and SDK version ranges, listing copy, changelog, license, and a creator rights declaration.

Every inventoried file has a relative path, role, content type, byte count, and SHA-256 digest. Build output is canonical, and the archive timestamp is fixed, so the same project bytes produce the same artifact identity.

#Native sheets

Native sheets are declarative view trees rendered by Aether. The available nodes cover responsive stacks, grids, tabs, sections, scores, meters, fields, lists, cards, badges, details, filters, buttons, and conditional or role-aware content. References bind a node to projected document data; actions ask the host to edit, roll, or emit a declared topic.

A native sheet receives no DOM, network, file, database, or React access. Aether owns keyboard behavior, focus, accessible names, bounded theme tokens, permission checks, and hidden-field projection. Use native sheets for ordinary character and NPC play, including narrow docks.

#Companion applications

A companion application is an inventoried HTML entry for a builder, browser, import assistant, or other workflow that does not fit a native sheet. It runs in an opaque-origin iframe with a Content Security Policy and talks to the host through the typed bridge. Its capabilities are reviewed separately.

Companion applications cannot reach host cookies, the host DOM, the React tree, another sandbox, the renderer, the database, the object store, the filesystem, or arbitrary network destinations. An ordinary character sheet must not require a companion application merely to render.

#Package and service dependencies

Package edges name an id, semantic-version range, and whether the edge is optional. Service edges name a namespaced service, version range, execution scope, and whether the service is optional. A provider declares schema-validated actions, queries, and events.

Before installation, one resolver walks direct and transitive edges, checks Aether, SDK, and system compatibility, rejects package and service cycles, reports conflicting version ranges, and pins one exact version and hash per package. It never floats an installed world to another version.

Service payloads are serialized and validated in both directions. Authoritative calls pass through the server, retain the caller and provider identities, and apply endpoint payload, rate, timeout, and permission limits. A system does not inherit a provider mod's grants. A required missing or incompatible service blocks activation; an optional one is recorded as unavailable.

A package pinned by the active system graph cannot be disabled, removed, or replaced on its own. Change it through a system upgrade so every consumer is preflighted together.

#Automation and migrations

Automation and scripted migrations run in bounded QuickJS sandboxes. They have no imports, DOM, network, filesystem, ambient clock, or ambient randomness. The host supplies the permitted input and validates the output.

An upgrade requires one ordered path from the installed version to the target. A reverse path is a separate declaration and is the only way a lower version becomes an available manual downgrade. Every transformed document must validate against the destination schema before the staged result is committed.

#Seeded generators

A generator declares its input schema, output document type, algorithm version, source-pool types, and tighter runtime, memory, and output limits. Preview runs the checksum-locked QuickJS file on the world server with the visible seed, validated options, and exact revisions of any selected world records. It can read only those selected records and return one JSON value; mutation, dice, state, clock, filesystem, network, and imports are unavailable.

Commit reruns the same bytes and refuses a preview whose inputs, source records, or canonical output changed. The created document records the package, artifact, generator, algorithm, seed, options, source revisions, and preview identity. Reusing a commit mutation id returns the same document.

#Artifact limits

Format 1 enforces these ceilings before activation:

Paths must be relative, use forward slashes, and contain no empty, . or .. segments. Duplicate paths, undeclared files, hash mismatches, unexpected manifest fields, native binaries, credentials, temporary URLs, and arbitrary server modules are rejected.

#Startup and recovery

Startup reopens the pinned artifacts, verifies every digest, validates the package graph and services, registers the schemas and native views, and only then marks the system ready. Missing, tampered, or incompatible bytes produce a failed recovery state while world data remains intact. Aether does not substitute Demo System, an empty registry, or another plausible version.

Restore the exact artifact or dependency named by the failure, then use Retry exact package in world settings. See Publish a system for artifact commands and Install and upgrade a system for the GM flow.