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
- Manifest.
manifest.jsondeclares 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. - 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. - 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. - 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.
- 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.
- 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).