Contract Registry

@vibelands/mod-sdk/shared exports MOD_CONTRACT_OPERATIONS, the canonical command/query/event catalog for the installed ABI. Each operation declares its runtime side, required capability, ownership scope, authority, input/output type names, side effects, and stable error codes.

The three operation kinds are deliberately distinct:

• query reads a host projection and must not mutate state;
• command requests a validated state change and is host-authorized;
• event reports a fact that already happened; a mod cannot manufacture a host-authoritative fact by emitting a similarly named private message.

Use getModContractView to expose only the least-privilege catalog relevant to a mod or agent:

import { getModContractView } from '@vibelands/mod-sdk/shared';

const tools = getModContractView({
  runtimeSide: 'server',
  permissions: ['world.entities'],
  kinds: ['command', 'query'],
});

The returned metadata is for discovery, documentation, and adapter generation; it does not grant authority. The host still checks the real capability and ownership boundary on every SDK call. vibelands context . --json includes both the full registry and server/client views projected from the manifest.

Manifest v3 draft

The SDK also exposes a tooling-only v3 manifest/schema generator. Production runtimes still require apiVersion: 2. To inspect the proposed capability split and generate JSON Schema command/event envelopes without modifying the production manifest:

vibelands migrate . --to 3 --dry-run --json
vibelands migrate . --to 3 --json

The second command writes vibelands-mod.v3-draft.json, its draft schema, and derived contracts/*.schema.json files. These artifacts are review inputs, not publishable runtime manifests. In particular, generated command schemas preserve delivery: "at-most-once" by requiring an operation ID.