The Open Mercato GuideEditorial guide · not official documentation
Menu
GitHubPL

Concept family 03 · cross-module change

Open Mercato Extensibility, Events, and Workflow Contracts

Cross-module behavior should travel through a declared contract rather than a peer-module import. UMES covers UI, API, response, command, guard, and entity-link surfaces; typed events and persistent subscribers carry reactions; workflows coordinate longer processes and compensation. Each mechanism has a different timing and failure model.

An extension surface creates a contract; it does not remove versioning, absence, timeout, or compensation work.

Source snapshot:

ae856df1ecfc · ARCHITECTURE.md sections: 11, 12, 13, 24

Direct answer

Position in the system

This family crosses module boundaries and then hands durable reactions to events, queues, or workflows. It does not own provider operations or project workflow suitability.

Compose, inject, react, or orchestrate

Own-page changes compose directly; another module uses a stable UMES surface; reactions use events; multi-step process state belongs in workflows.

Compose, inject, react, or orchestrateOwn-page changes compose directly; another module uses a stable UMES surface; reactions use events; multi-step process state belongs in workflows.
01

UMES exposes widget injection, component overrides, interceptors, enrichers, guards, command hooks, and entity links for cross-module extension.

oss-core

02

Modules declare typed events and register event configurations before the event bus dispatches subscribers.

infrastructure-package

03

The events package supports in-memory delivery, wildcard handlers, persistent subscribers, and browser bridges configured by event metadata.

infrastructure-package

04

Code-defined workflows compose typed steps and may coordinate approvals, signals, asynchronous activities, and compensation.

oss-core

Event to persistent side effect

Delivery choice determines whether failure is immediate, best-effort, retryable, or compensating.

  1. The module declares a typed event contract.

    product-factoss-core

  2. The event bus dispatches matching in-memory handlers.

    product-factoss-core

  3. Persistent subscribers cross the queue boundary for retryable work.

    product-factoss-core

  4. The worker must be idempotent and observed through failure and retry.

    documented-conventionoss-core

Extension contracts and failure ownership

Extension contracts and failure ownership
MechanismEditorial implicationLimitationDecision owner
UMES exposes widget injection, component overrides, interceptors, enrichers, guards, command hooks, and entity links for cross-module extension.Treat it as an “oss-core” contract and confirm project-specific fit separately.The surface is optional or separately configured and must not be read as universally enabled.Module and workflow owner
Modules declare typed events and register event configurations before the event bus dispatches subscribers.Treat it as an “infrastructure-package” contract and confirm project-specific fit separately.The mechanism does not prove performance, security, availability, compliance, or production readiness for a particular deployment.Module and workflow owner
The events package supports in-memory delivery, wildcard handlers, persistent subscribers, and browser bridges configured by event metadata.Treat it as an “infrastructure-package” contract and confirm project-specific fit separately.The surface is optional or separately configured and must not be read as universally enabled.Module and workflow owner
Code-defined workflows compose typed steps and may coordinate approvals, signals, asynchronous activities, and compensation.Treat it as an “oss-core” contract and confirm project-specific fit separately.The surface is optional or separately configured and must not be read as universally enabled.Module and workflow owner

Footguns and failure modes

The events package supports in-memory delivery, wildcard handlers, persistent subscribers, and browser bridges configured by event metadata.

The surface is optional or separately configured and must not be read as universally enabled.

Inspect pinned source

Code-defined workflows compose typed steps and may coordinate approvals, signals, asynchronous activities, and compensation.

The surface is optional or separately configured and must not be read as universally enabled.

Inspect pinned source
Sources and method · 8 evidence records

Every fact, node, connector, and flow step has a stable ID, claim class, source locator, scope, limitation, and pinned revision. A local verifier checks every file and locator and ensures sections 1–33 are covered exactly once.

  • UMES exposes widget injection, component overrides, interceptors, enrichers, guards, command hooks, and entity links for cross-module extension.

    ID
    section-11-umes
    Class
    product-fact
    Scope
    oss-core

  • Modules declare typed events and register event configurations before the event bus dispatches subscribers.

    ID
    section-12-events
    Class
    product-fact
    Scope
    infrastructure-package
    Source
    packages/shared/src/modules/events/factory.ts · export function createModuleEvents

  • The events package supports in-memory delivery, wildcard handlers, persistent subscribers, and browser bridges configured by event metadata.

    ID
    section-13-realtime
    Class
    product-fact
    Scope
    infrastructure-package
    Source
    packages/events/src/bus.ts · export function createEventBus

  • Code-defined workflows compose typed steps and may coordinate approvals, signals, asynchronous activities, and compensation.

    ID
    section-24-workflows
    Class
    product-fact
    Scope
    oss-core
    Source
    packages/shared/src/modules/workflows/builder.ts · export function defineWorkflow

  • The module declares a typed event contract.

    ID
    flow-event-declare
    Class
    product-fact
    Scope
    oss-core
    Source
    packages/shared/src/modules/events/factory.ts · export function createModuleEvents

  • The event bus dispatches matching in-memory handlers.

    ID
    flow-event-emit
    Class
    product-fact
    Scope
    oss-core
    Source
    packages/events/src/bus.ts · export function createEventBus

  • Persistent subscribers cross the queue boundary for retryable work.

    ID
    flow-event-persist
    Class
    product-fact
    Scope
    oss-core
    Source
    packages/events/src/bus.ts · persistentSubscribers

  • The worker must be idempotent and observed through failure and retry.

    ID
    flow-event-operate
    Class
    documented-convention
    Scope
    oss-core
    Source
    ARCHITECTURE.md · ## 19. Queue and Background Jobs