Mod package specification

The format of an OOMU .oomu Mod package, as Beta 2 parses it. For a walkthrough, see Building a Mod.

• Archive format: ZIP
• File extension: .oomu (required, lowercase)
• Required member: manifest.json at the archive root
• ABI schema version: 1

This is not the Beta 1 format. A Beta 1 package still installs, but the features Beta 2 does not implement are listed on the Mod card as Not supported in this Beta 2 build rather than honored. See §5.

---

1. Archive

A standard ZIP with the .oomu extension. OOMU parses the central directory and validates every entry before extracting anything.

1.1 Limits

Entry names are compared case-insensitively. Two entries whose names differ only in case are rejected as ambiguous. ZIP64 sentinel values in the central directory are rejected.

1.2 Installation

1. Confirm the file is a .oomu regular file within the size limit.
2. Parse the archive and validate every entry.
3. Read and parse manifest.json from the root.
4. Parse and validate the Beta 2 ABI, and confirm every declared asset exists.
5. Compute the canonical payload digest and evaluate trust.
6. Write to a staging directory, verify the staged contents, then promote atomically.
7. Record the Mod in installed_mods and installed_mod_packages.

A failed install leaves no partial state. Installing a package whose id matches an installed Mod upgrades it in place.

---

2. manifest.json

2.1 Example

{
  "id": "com.example.mods.house-style",
  "name": "House Style",
  "version": "2.0.0",
  "author": "Example Ltd",
  "description": "Reference material for our editorial standards.",
  "category": "writing",
  "entrypoint": "knowledge/style.md",
  "beta2Abi": {
    "schemaVersion": 1,
    "capabilities": [
      { "id": "mods.asset.read",    "assets": ["knowledge/style.md", "knowledge/terms.json"] },
      { "id": "mods.state.read",    "keys": ["last-reviewed"] },
      { "id": "mods.state.replace", "keys": ["last-reviewed"] }
    ]
  }
}

2.2 Fields

Unknown top-level fields are preserved and ignored, except where §5 recognizes them as legacy features to report.

entrypoint does not execute. Beta 2 has no Mod code runtime. The field is validated for existence and recorded; nothing runs. An entry point ending .js or .mjs is additionally reported as an unsupported legacy feature.

endpoints and permissions.allowed_hosts grant nothing. They are recorded for transparency and reported as an unsupported network-access declaration. A Mod cannot reach any host.

---

3. beta2Abi

The complete capability surface available to a Mod. There are three capabilities, and no others.

"beta2Abi": { "schemaVersion": 1, "capabilities": [ ... ] }

schemaVersion must be 1. capabilities must contain 1 to 3 entries with distinct id values. The object is parsed with unknown fields denied: an unrecognised key rejects the manifest.

3.1 mods.asset.read

{ "id": "mods.asset.read", "assets": ["knowledge/style.md"] }

Lets OOMU read the named files from inside the Mod. Each path must:

• be relative, with no ., .., or absolute components;
• have its first component be knowledge or content;
• end in .txt, .md, or .json;
• be at most 240 characters, trimmed, and unique in the list.

Every declared asset must exist in the archive, or the package is rejected.

3.2 mods.state.read and mods.state.replace

{ "id": "mods.state.read",    "keys": ["last-reviewed"] },
{ "id": "mods.state.replace", "keys": ["last-reviewed"] }

Read and write the Mod's own persisted values. Each key must be 1–64 characters of lowercase ASCII letters, digits, ., _, or -, starting and ending alphanumeric.

Read and write must declare identical key sets. If one is present the other must be too, with exactly the same keys. A Mod cannot declare write access to a key it did not also declare read access to.

3.3 Common limits

---

4. Trust

Trust is evaluated from the canonical digest of the archive payload together with the capability_bundle object, producing one of three states.

4.1 Signature material

"capability_bundle": {
  "payloadSha256": "<64 lowercase hex>",
  "publisher": { "publicKey": "<32-byte Ed25519 key>" },
  "signature": "<publisher signature>",
  "reviewSignature": {
    "algorithm": "ed25519",
    "keyId": "eldris-mod-review-v1",
    "payloadSha256": "<64 lowercase hex>",
    "signature": "<signature>",
    "signedAt": "<optional timestamp>"
  }
}

A review signature may instead be supplied as a detached signature.sig entry at the archive root, containing the same envelope. Supplying both an embedded and a detached review signature is an error.

4.2 Verification rules

• All signatures are Ed25519 over domain-separated messages: OOMU-MOD-PAYLOAD-V1, OOMU-MOD-REVIEW-V1, and OOMU-MOD-PUBLISHER-V1.
• The declared payloadSha256 must equal the computed payload digest, as 64 lowercase hex characters. A mismatch rejects the package.
• A review envelope must declare algorithm: "ed25519" and keyId: "eldris-mod-review-v1", and must verify against OOMU's embedded review public key.
• If trust material is present but nothing verifies, the package is rejected. It does not silently fall back to unsigned.

4.3 Integrity after install

Separately from trust, OOMU records the package digest and re-checks the installed files against it. Integrity state is verified, invalid (shown as Changed), or missing. A Mod whose integrity is not verified cannot be enabled.

---

5. Legacy features, and how they are reported

OOMU inspects the manifest for Beta 1 features it does not implement, and lists each on the Mod card.

A field counts as present only if it is non-empty. This is a transparency report, not a rejection: the Mod installs, and those features do nothing.

---

6. Rejection reference

---

Related

• Building a Mod: the hands-on guide.
• Installing a Mod: what a user sees.
• Local database schema: where installed Mods are recorded.