Extend Mobazha through public contracts

Choose the mechanism

Use the narrowest mechanism that matches one responsibility. A package may implement more than one role, but each public contract has one authority boundary. A callback is not automatically a Port, and a Module is not a service locator.

• Port: replace an implementation that Core requires.
• Module: assemble reviewed capabilities into a distribution.
• Function: customize a bounded deterministic business decision.
• Controller: reconcile an external system or perform external I/O.
• OrderExtension: attach versioned domain data and lifecycle to an order.

Preserve Core authority

Extensions submit declarations, decisions, observations, or attestations. Core validates identity, authorization, schema and contract versions, resource binding, expected state, idempotency, freshness, and policy before creating a Core-owned command or durable fact.

• Do not add a generic hook when a typed domain contract can express the need.
• Core retains release policy, order state, payment verification, settlement gates, audit, and key custody.
• Third-party code must not import internal packages, receive the Core object, or access raw signing material.
• Extensions never write Core tables or directly invoke an internal state transition.
• Payment, refund, dispute, and settlement changes re-enter a versioned, idempotent Core command and state machine.

extension input
  -> Core validation
  -> Core command or durable fact
  -> Core state machine
  -> audit and external execution through a scoped adapter

Design rules

• Ports provide replaceability for narrow Core-owned capabilities.
• Modules provide immutable startup composition and declare identity, versions, dependencies, capabilities, configuration, runtime type, and lifecycle.
• Functions are bounded and deterministic; they do not receive network, database, key, clock, or state-transition authority.
• Controllers reconcile external systems from durable Core facts and return observations or attestations.
• Governance is uniform across modules, while business contracts remain small, typed, and domain-specific.
• New extension points are deliberate and domain-scoped, with an owner, schema, authority boundary, failure semantics, idempotency, recovery, tests, and a removal plan.
• There is no global named hook bus, mutable runtime registry, or universal Core service locator.

Capability and trust gates

An extension capability remains unavailable until every activation gate passes. Source presence, a known identifier, or linked code is not evidence that the capability is enabled.

• Reviewed first-party modules are statically linked by default.
• Independently distributed or third-party infrastructure runs out of process by default.
• Merchant-authored decision rules use a restricted sandbox such as Wasm when that runtime is introduced.
• Moving to a less isolated runtime requires threat analysis and an architecture decision.

distribution allowlist
  ∩ contract compatible
  ∩ installed or statically composed
  ∩ authorized
  ∩ configured
  ∩ healthy

Current implementation boundary

The static order-extension v1 path currently validates exact contract names, immutable startup composition, dependencies and cycles, capability/interface agreement, and fail-closed invocation. It also provides append-only extension records, durable lifecycle delivery, typed reservation binding, and settlement attestations that re-enter the Core settlement command.

Distribution allowlists, per-tenant authorization and configuration, structured module health, drain, upgrade, rollback, a third-party process runtime, and a Wasm Function runtime remain governance targets. Do not describe those targets as generally available capabilities.

Collectibles as the first case

Collectibles proves the architecture without turning NFT concepts into universal Core abstractions. Product-specific hooks, settlement commands, queues, and FiatMetadata mirroring were removed during the direct development-time cutover.

• Signed NFT metadata becomes a versioned OrderExtension declaration produced by the Collectibles module.
• Token or inventory allocation is handled through a module-owned ReservationPort before funding.
• Minting and delivery are Controller work driven by durable extension events.
• Delivery evidence becomes a module-verified SettlementAttestation.
• Seller payout remains an existing Core conditional-settlement command.
• NFT, chain, mint, certificate, and provider vocabulary stays outside generic Core APIs.

Review a new extension point

If those answers are not stable, keep the mechanism private to its implementation instead of publishing another generic extension point.

• Identify the domain owner, business purpose, caller, declarer, and authorizer.
• Version the input, output, descriptor, and compatibility behavior independently.
• Define synchronous or durable delivery, ordering, idempotency, timeout, retry, dead-letter, and reconciliation behavior.
• Declare capability gates, permissions, sensitive data, and the Core state-machine re-entry point.
• Provide migration, rollback, removal, observability, negative tests, and conformance evidence.

Start with the normative documents