Home / Guides / Build guide

How to build an AmetiOS module

Draft Module interface documented; the module registry is Roadmap. Related: quickstart.

An AmetiOS module is a package of actions, policies, and handlers that runs inside the execution chain. This guide defines the module structure, the contracts a module must satisfy, and the testing expectations for anything that runs under governance.

Module structure Draft

Illustrative referenceCanonical module layout.
my-module/
  manifest.json          # module identity, actions, policy bundle reference
  actions/               # one JSON schema per action, e.g. invoice.issue.schema.json
  policies/
    default.json         # policy bundle (see the policy model)
  handlers/
    index.js             # action handlers; one export per action
  tests/
    fixtures/            # deterministic fixtures: proposals, policies, expected decisions
    policy.test.js       # policy decision-matrix tests
    handlers.test.js     # handler tests against fixtures
  README.md              # what the module does, its actions, its policy defaults

Contracts a module must satisfy Draft

  1. Manifest. manifest.json declares the module name, version, every action it registers (with schema version pins), and the default policy bundle. Names are namespaced: <module>.<action>, e.g. billing.invoice.issue.
  2. Action schemas. Every action has a versioned JSON schema in actions/. Schemas are immutable once published; changes require a new version and a migration note.
  3. Policy bundle. Every module ships a default policy bundle in policies/. Defaults must be deny-by-default; a module may not ship an allow-all rule.
  4. Evidence emission. Every action a module executes must produce an evidence receipt: inputs hash, policy trace, outputs hash, expected vs actual value/cost/risk. Handlers do not construct receipts by hand — they return results through the governed-action interface, which issues the receipt.
  5. Deterministic handlers. Handlers are pure with respect to governance: given the same proposal, they must produce the same outputs. Non-determinism (random ids, clock reads) is injected through explicit, recorded inputs, never read silently.
  6. Tenant awareness. Handlers receive the resolved tenant context and must never reach outside it. Cross-tenant access is a contract violation, not just a bug.

Testing expectations Draft

  • Deterministic fixtures. Tests run against checked-in fixtures: proposals, policy bundles, and expected decisions/receipts. No test may depend on the current time, randomness, or execution order.
  • No external network in unit tests. Handler and policy tests must not make real network calls. External dependencies are replaced with deterministic local fixtures.
  • Policy decision matrix. Every rule in the module's policy bundle has at least one allow-case, one deny-case, and (where applicable) one require-approval-case test. The full evaluation trace is asserted, not just the decision.
  • Receipt verification. At least one end-to-end test executes an action through all six chain stages and verifies the resulting receipt with the verification protocol (hash recomputation + chain link).
  • Contract conformance. A manifest lint checks: every registered action has a schema file, every schema version is pinned, and every handler export matches a registered action.

Example manifest

Illustrative referencemanifest.json for a billing module. Field names follow this guide.
{
  "module": "billing",
  "version": "0.3.0",
  "description": "Invoice issuance and refund requests under governed policy.",
  "actions": [
    {
      "name": "billing.invoice.issue",
      "schema": "actions/invoice.issue.schema.json",
      "schema_version": "1.2.0",
      "handler": "handlers/index.js#issueInvoice"
    },
    {
      "name": "billing.refund.request",
      "schema": "actions/refund.request.schema.json",
      "schema_version": "1.0.0",
      "handler": "handlers/index.js#requestRefund"
    }
  ],
  "default_policy_bundle": "policies/default.json",
  "required_capabilities": ["ledger.write"],
  "evidence": {
    "receipt_format": "ametios.receipt/v1"
  }
}

Related: reference implementations (see the contracts in code), policy model (bundle format), evidence model (receipt format).