The Open Mercato GuideEditorial guide · not official documentation
Menu
GitHubPL

Concept family 05 · change discipline

Open Mercato Engineering Conventions and Compatibility Contracts

Open Mercato treats naming, files, routes, events, feature IDs, DI keys, schemas, generated registries, and AI approval as contracts with different compatibility classes. Engineering changes therefore carry an explicit command and verification path. The conventions reduce accidental breakage, but only review and tests show whether a specific change preserves them.

A documented convention guides review; it is not runtime enforcement of every custom application.

Source snapshot:

ae856df1ecfc · ARCHITECTURE.md sections: 22, 23, 27, 30, 31, 32, 33

Direct answer

Position in the system

This family surrounds every layer as a change contract: UI and language, AI writes, public compatibility surfaces, generation, development commands, review evidence, architectural decisions, and shared terminology.

Change-to-verification lifecycle

Identify the contract class, change the source of truth, regenerate derived files, run the affected checks, document migration, and retain a bridge when required.

Change-to-verification lifecycleIdentify the contract class, change the source of truth, regenerate derived files, run the affected checks, document migration, and retain a bridge when required.
01

The shared design system and i18n rules define stable primitives, semantic tokens, and localized user-facing copy conventions.

ui-shared

02

AI mutation tools prepare a scoped pending action and preview; the write runs only through a separate confirmation path.

infrastructure-package

03

Public surfaces are classified as frozen, stable, additive-only, or generated contracts and require a staged deprecation bridge before removal.

documented-convention

04

Generation, package build, migration generation, tests, and role synchronization are explicit steps tied to the type of source change.

documented-convention

05

The architecture checklist groups module, data, API, command, UI, extension, security, runtime, compatibility, and verification obligations.

documented-convention

06

Load-bearing architectural decisions are recorded in dated specifications and referenced from the authoritative architecture guide.

documented-convention

07

The glossary fixes the intended meaning of module, DataEngine, QueryEngine, command, UMES, subscriber, worker, scope, edition, and related terms.

documented-convention

AI mutation approval as a concrete contract

The approval path demonstrates how policy, scope, preview, idempotency, and a separate confirmation route combine.

  1. AI mutation tools prepare a scoped pending action and preview; the write runs only through a separate confirmation path.

    product-factinfrastructure-package

  2. Public surfaces are classified as frozen, stable, additive-only, or generated contracts and require a staged deprecation bridge before removal.

    documented-conventiondocumented-convention

  3. Generation, package build, migration generation, tests, and role synchronization are explicit steps tied to the type of source change.

    documented-conventiondocumented-convention

  4. The architecture checklist groups module, data, API, command, UI, extension, security, runtime, compatibility, and verification obligations.

    documented-conventiondocumented-convention

Contract class and maintenance duty

Contract class and maintenance duty
MechanismEditorial implicationLimitationDecision owner
The shared design system and i18n rules define stable primitives, semantic tokens, and localized user-facing copy conventions.Treat it as an “ui-shared” contract and confirm project-specific fit separately.This is a committed engineering convention. A custom application can still violate it and must be reviewed separately.Engineering lead and reviewer
AI mutation tools prepare a scoped pending action and preview; the write runs only through a separate confirmation path.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.Engineering lead and reviewer
Public surfaces are classified as frozen, stable, additive-only, or generated contracts and require a staged deprecation bridge before removal.Treat it as an “documented-convention” contract and confirm project-specific fit separately.This is a committed engineering convention. A custom application can still violate it and must be reviewed separately.Engineering lead and reviewer
Generation, package build, migration generation, tests, and role synchronization are explicit steps tied to the type of source change.Treat it as an “documented-convention” contract and confirm project-specific fit separately.This is a committed engineering convention. A custom application can still violate it and must be reviewed separately.Engineering lead and reviewer
The architecture checklist groups module, data, API, command, UI, extension, security, runtime, compatibility, and verification obligations.Treat it as an “documented-convention” contract and confirm project-specific fit separately.This is a committed engineering convention. A custom application can still violate it and must be reviewed separately.Engineering lead and reviewer
Load-bearing architectural decisions are recorded in dated specifications and referenced from the authoritative architecture guide.Treat it as an “documented-convention” contract and confirm project-specific fit separately.This is a committed engineering convention. A custom application can still violate it and must be reviewed separately.Engineering lead and reviewer
The glossary fixes the intended meaning of module, DataEngine, QueryEngine, command, UMES, subscriber, worker, scope, edition, and related terms.Treat it as an “documented-convention” contract and confirm project-specific fit separately.This is a committed engineering convention. A custom application can still violate it and must be reviewed separately.Engineering lead and reviewer

Footguns and failure modes

Public surfaces are classified as frozen, stable, additive-only, or generated contracts and require a staged deprecation bridge before removal.

This is a committed engineering convention. A custom application can still violate it and must be reviewed separately.

Inspect pinned source

AI mutation tools prepare a scoped pending action and preview; the write runs only through a separate confirmation path.

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

Inspect pinned source
Sources and method · 7 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.

  • The shared design system and i18n rules define stable primitives, semantic tokens, and localized user-facing copy conventions.

    ID
    section-22-design-i18n
    Class
    documented-convention
    Scope
    ui-shared
    Source
    ARCHITECTURE.md · ## 22. Design System and i18n Conventions

  • AI mutation tools prepare a scoped pending action and preview; the write runs only through a separate confirmation path.

    ID
    section-23-ai-approval
    Class
    product-fact
    Scope
    infrastructure-package
    Source
    packages/ai-assistant/src/modules/ai_assistant/lib/prepare-mutation.ts · export async function prepareMutation

  • Public surfaces are classified as frozen, stable, additive-only, or generated contracts and require a staged deprecation bridge before removal.

    ID
    section-27-compatibility
    Class
    documented-convention
    Scope
    documented-convention
    Source
    BACKWARD_COMPATIBILITY.md · ## Deprecation Protocol

  • Generation, package build, migration generation, tests, and role synchronization are explicit steps tied to the type of source change.

    ID
    section-30-development-commands
    Class
    documented-convention
    Scope
    documented-convention
    Source
    ARCHITECTURE.md · ## 30. Development Workflow and Commands

  • The architecture checklist groups module, data, API, command, UI, extension, security, runtime, compatibility, and verification obligations.

    ID
    section-31-review-checklist
    Class
    documented-convention
    Scope
    documented-convention
    Source
    ARCHITECTURE.md · ## 31. Conventions and Code-Review Checklist

  • Load-bearing architectural decisions are recorded in dated specifications and referenced from the authoritative architecture guide.

    ID
    section-32-decisions
    Class
    documented-convention
    Scope
    documented-convention
    Source
    ARCHITECTURE.md · ## 32. Key Architectural Decisions and Specs

  • The glossary fixes the intended meaning of module, DataEngine, QueryEngine, command, UMES, subscriber, worker, scope, edition, and related terms.

    ID
    section-33-glossary
    Class
    documented-convention
    Scope
    documented-convention
    Source
    ARCHITECTURE.md · ## 33. Glossary