# WebAssembly integration modules

## Purpose

A module is a small translator between a game server API and DoGaMa's normalized game API.

```text
Game-specific API <-> WebAssembly adapter <-> normalized DoGaMa API
```

It may query status, list players, request an in-game save, announce, shut down gracefully, kick, ban or unban when the game supports those operations. It does not own container lifecycle, files, users, backups, scheduling or UI.

## Package

```text
palworld-rest-1.0.0.dogama-module/
  module.wasm
  manifest.yaml
  README.md
  LICENSE
```

The installed artifact is content-addressed. Manifest, binary checksum, source/trust status and installation time are recorded. A package cannot contain executable helpers or dynamic libraries.

## Runtime contract

The V1 ABI uses a versioned WebAssembly component/WIT contract or an equivalently typed ABI. JSON may be used at a debugging boundary but is not the authority for function signatures. `specs/normalized-module-api.md` defines semantics.

The runtime grants no ambient WASI filesystem, process, environment, raw sockets or arbitrary DNS. Time and randomness are provided only if a documented operation requires them. Host functions include:

- bounded HTTP request to logical handle `instance_api`;
- bounded TCP request only if declared by both template and manifest;
- secret lookup by declared configuration key without exposing unrelated secrets;
- structured diagnostic emission with runtime redaction;
- cancellation/deadline checks.

## Instance-scoped networking

Modules never receive an arbitrary destination URL. At activation, DoGaMa binds `instance_api` to a specific instance network identity and declared integration port. Every request is checked for protocol, port, method, timeout, redirect, request/response size and concurrency.

- No Internet or LAN destinations.
- No loopback, link-local, metadata or Unix-socket destinations.
- No redirects outside the bound origin.
- DNS rebinding cannot change the authorized resolved destination.
- The management port is preferably unexposed on the host.

## Capabilities

Capabilities are explicit strings defined by the normalized API. A module may implement a subset. DoGaMa shows actions only when all of these agree:

1. template enables the integration and feature;
2. manifest declares the capability;
3. module runtime reports the same capability;
4. current user has permission;
5. instance state permits the operation.

Unknown capabilities are rejected for the current schema version. A claimed capability without its required export blocks activation.

## Resource limits

Per call, enforce a deadline, instruction/fuel budget, memory ceiling, maximum host calls, maximum payload/response size and cancellation. Limit concurrent calls per module and instance. Repeated traps open a circuit breaker and degrade only the integration; generic container management remains available.

## Independent versioning

Templates and modules have independent semantic versions.

- A template pins an acceptable module ID and version range.
- A manifest states supported manager module-API versions and game IDs.
- Installation of a new module does not activate it automatically for existing instances.
- Activation runs schema, checksum, ABI, capability and connection tests.
- The previous version stays available for rollback until the new version is healthy.
- A module update never silently changes instance settings or template snapshots.

## Prohibited behavior

Modules cannot create/delete containers, read SQLite, access host/game files, create backups, execute commands, manage users, expose routes or UI, contact other instances, or make unrestricted network calls. If a proposed integration needs those powers, the generic DoGaMa contract must be extended safely instead of bypassed.