Separate deployed, published, and development states first
Reviewed 14 July 2026. The development repository was at revision 01911d00e28f44cf484d0b1d04860dcfef5370bf. The latest public Git tag and GitHub release were v0.6.5, and the npm latest channel for @open-mercato/core resolved to 0.6.5. The develop source already contained 0.6.6 material and prerelease channels; those are not automatically an application target.
The decision must record current lockfile and manifests, exact target tag and commit, and evidence that Core, Enterprise, official, and provider packages align. A latest label, the develop branch, and a running application are three different facts.
Five evidence layers answer different questions
Manifests and lockfile show what is deployed. A tag, commit, and packages identify the target. Changelog or release notes describe shipped changes. UPGRADE_NOTES records known actions for every crossed window. BACKWARD_COMPATIBILITY governs changes to public contracts. Only application tests, runbooks, and acceptance evidence prove the deployed outcome.
The compatibility contract does not mean zero work
Auto-discovery conventions and identifiers are frozen, public types, functions, import paths, and routes are stable, and database evolution is additive-only. A breaking change requires deprecation, a compatibility bridge for at least one minor version, migration guidance, and a specification. These are platform contribution rules, not a guarantee for dependencies, custom code, configuration, data, integrations, or operations.
Examples show why the exact window matters
The 0.5.0 → 0.6.0 window carried MikroORM v6 → v7 work: decorator moves, persist/flush changes, Knex-to-Kysely migration, migrator and bootstrap changes, tighter types, and test configuration where used. By contrast, the 0.6.0 → 0.6.1 and 0.6.1 → 0.6.2 notes record no actionable dependency upgrade for downstream code. That does not waive application regression or forecast another window.
Automation edits patterns; it does not approve behavior
The 0.4.10 → 0.5.0 helper detects and edits selected patterns, typechecks, and reports human-review items. A separate workflow covers MikroORM v6 → v7. Their scope is version-specific and mechanical. Neither proves data migration, integration behavior, authorization, performance, recovery, or business acceptance.
Owned code and rollback widen responsibility
Overrides and documented extension surfaces reduce the need to modify Core but still require contract tests. App-local and provider modules have their own compatibility lifecycle. Ejection copies a module into the app and changes its origin to @app: it becomes organization-owned code requiring diffing, merging, testing, and security review; upstream fixes do not flow into it automatically.
Rollback must separately cover packages and application code, schema and migrations, data-transformation reversibility, configuration and secrets, cache and generated artifacts, external side effects, and supplier changes. A down migration or one component snapshot does not restore the whole service.
Maintenance starts after deployment
After the change, verify migrations and health, observe errors, queues, and integrations, reconcile critical records, retain evidence, close temporary exceptions, update the application baseline, and schedule the next review. Infrastructure and production-depth decisions remain with their dedicated guides.
Upgrade evidence hierarchy
| Layer | What it can prove | What it cannot prove | Exact source |
|---|---|---|---|
| Deployed manifests and lockfile | What package versions and dependency graph are actually deployed. | Runtime behavior, data health, or target compatibility. | Project evidence |
| Public target tag, commit, and package artifacts | The immutable target identity and whether aligned packages exist. | That the application has been tested against it. | Project evidence |
| Changelog and release notes | User-facing changes attributed to a shipped release. | Every downstream code action or application regression. | Inspect source |
| UPGRADE_NOTES for every crossed window | Known actionable incompatibilities for downstream apps, modules, and extensions. | Unknown custom behavior or a successful migration. | Inspect source |
| Backward-compatibility contract | How platform contributors must preserve or deprecate public contract surfaces. | A warranty for dependencies, custom code, data, configuration, integrations, or operations. | Inspect source |
| Application tests, runbooks, and acceptance | What happened in the exact staging and production-like application. | Future releases or untested workflows. | Project evidence |
Compatibility categories and limits
| Category | Repository rule | Application limit |
|---|---|---|
| Frozen | Auto-discovery conventions, event and extension IDs, ACL IDs, and other published addresses cannot be renamed or removed directly. | A platform-change rule, not a zero-work application guarantee. |
| Stable | Public types, functions, routes, import paths, CLI, DI, and generated contracts must preserve existing consumers. | A platform-change rule, not a zero-work application guarantee. |
| Additive-only | Database evolution may add safe columns, tables, and indexes but may not narrow, rename, or remove existing schema contracts. | A platform-change rule, not a zero-work application guarantee. |
| Deprecation and bridge | Breaking evolution requires a deprecation, migration guidance, a compatibility bridge for at least one minor version, and a migration-aware spec. | A platform-change rule, not a zero-work application guarantee. |
Customization exposure matrix
| Exposure | Review owner | Likely evidence | Why exposure differs |
|---|---|---|---|
| Documented app-level override | Application owner | Inventory stable IDs, stale-key warnings, contract tests, and regression of replacement behavior. | Uses a supported seam but can still depend on changed semantics or context. |
| Documented UMES / extension surface | Extension owner | Inventory event, widget, enricher, guard, command, entity, or AI contracts and test the absence case. | Stable addresses reduce direct-core coupling; payload and business assumptions still need review. |
| App-local custom module | Application team | Package imports, entities, migrations, ACLs, generated artifacts, unit and integration tests. | The organization owns compatibility for its code and data. |
| Provider or official module package | Contracted module owner and application owner | Exact package alignment, release notes, source or contract evidence, staging tests, and support boundary. | A separate package may have its own release and compatibility cadence. |
| Ejected module copied to @app | Application owner | Diff against upstream, merge plan, security review, migrations, full module regression. | It is independent app-owned source; upstream fixes do not arrive automatically. |
| Direct Core patch or maintained fork | Fork maintainer | Patch inventory, upstream diff, merge conflicts, contract review, security and full regression evidence. | It creates the broadest merge and maintenance burden. |
| External integration or data contract | Integration and business-system owners | Provider version, schemas, auth, retry, idempotency, reconciliation, failure and rollback tests. | A stable Open Mercato API does not freeze the external system or side effects. |
| Environment, secrets, workers, search, and cache configuration | Operations owner | Versioned configuration, migration ordering, background-drain plan, health and restoration evidence. | Code compatibility alone does not prove operational compatibility. |
Bounded version-window examples
| Window | Documented downstream statement | Boundary |
|---|---|---|
| 0.5.0 → 0.6.0 | MikroORM v6 → v7 required downstream review and changes where decorators, persistence calls, Knex/raw SQL, migrator APIs, custom bootstrap, strict types, or Jest setup were used. | Significant documented work for this exact window; actual exposure depends on application usage. |
| 0.6.0 → 0.6.1 | No actionable dependency upgrades were documented for downstream user code. | Still requires baseline regression, target pinning, application review, and acceptance. |
| 0.6.1 → 0.6.2 | No actionable dependency upgrades were documented for downstream user code. | The statement does not apply to later windows or prove business behavior. |
Ten decision gates from baseline to closeout
| Gate | Review owner | Required output or evidence | Stop condition |
|---|---|---|---|
| 1. Baseline and freeze | Application owner | Deployed inventory and change freeze | Unreproducible or changing baseline |
| 2. Target selection and pinning | Technical owner | Exact public tag, commit, packages and channel decision | Unpublished, mutable, or unaligned target |
| 3. Evidence collection | Upgrade lead | Every crossed window read and source ledger | Unread or ambiguous version window |
| 4. Impact classification | Code, data, integration and operations owners | Complete exposure and impact register | Affected artifact without owner or action |
| 5. Backup and rollback preparation | Data and operations owners | Restoration exercise and rollback decision tree | Missing or untested recovery path |
| 6. Staging migration and build | Engineering and data owners | Reproducible build, migrations and generated artifacts | Build, migration or data reconciliation failure |
| 7. Technical and business regression | QA, security and process owners | Critical-flow, integration, security, performance and acceptance evidence | Failed critical test or unresolved acceptance |
| 8. Production change approval | Authorized change owner | Dated go, pause or reject record and maintenance window | Any blocker or incomplete risk acceptance |
| 9. Deployment and observation | Release and operations owners | Ordered change, health, monitoring and rollback watch | Stop threshold reached or unknown service state |
| 10. Post-change closeout | Service owner | Reconciliation, evidence pack, new baseline, exceptions and next review | Critical discrepancy or temporary exception without expiry |
Rollback is a set of state-specific decisions
| State layer | Required rollback question |
|---|---|
| Packages and application code | Pin the prior known artifact and prove deploy ordering; code rollback cannot undo later data effects. |
| Database schema and migrations | Classify forward-only and reversible steps; a down migration must be tested with real dependencies. |
| Transformed data | Retain pre-change evidence and define reversal or compensating action; backups do not make every transformation logically reversible. |
| Configuration, environment, and secrets | Version values and rotation state without exporting secrets; coordinate code/config compatibility. |
| Generated artifacts, search, and cache | Define regeneration, invalidation, queue handling, and degraded behavior. |
| External integrations and side effects | Account for webhooks, payments, messages, exports, and remote writes that local rollback cannot erase. |
| Supplier and platform changes | Record provider changes, contracts, feature flags, and exit dependencies outside the code repository. |
Local planning tool
Upgrade impact register
All 21 coverage areas start unresolved. “No documented action” is only a classification; it never verifies a row or removes baseline regression.
Privacy: Entries remain in this browser and local exports. Do not enter secrets, personal data, production records, or credentials.
Decision state
NOT READYOpen approval gates: 262
Version inventory — leave unknown application facts blank
Record exact deployed and target evidence. No fictitious current or target version is prefilled.
| Area | Affected artifact | Current state | Target change | Source / version window | Classification | Accountable owner | Required action | Validation evidence | Rollback action | Stop condition | Status | Review date | Authorized risk role | Risk reason | Acceptance date | Expiry / review trigger |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Core, Enterprise, official and provider package alignment | ||||||||||||||||
| Direct dependency and runtime changes | ||||||||||||||||
| Public contract surfaces and deprecated bridges | ||||||||||||||||
| App-local custom modules and overrides | ||||||||||||||||
| Ejected modules, patches, and forks | ||||||||||||||||
| Database migrations and schema ordering | ||||||||||||||||
| Data transformations and reconciliation | ||||||||||||||||
| Generated registries, clients, assets, and snapshots | ||||||||||||||||
| Environment, configuration, feature flags, and secrets | ||||||||||||||||
| Background workers, queues, schedulers, and events | ||||||||||||||||
| Search indexes, vectors, and cache state | ||||||||||||||||
| Integrations, webhooks, files, and remote side effects | ||||||||||||||||
| Authentication, authorization, ACLs, encryption, and privacy | ||||||||||||||||
| Critical user journeys and accessibility | ||||||||||||||||
| Performance, capacity, and timeouts | ||||||||||||||||
| Backup, restoration, and transformed-data recovery | ||||||||||||||||
| Logs, metrics, alerts, and error budgets | ||||||||||||||||
| Deployment ordering and maintenance window | ||||||||||||||||
| Rollback feasibility across every state layer | ||||||||||||||||
| Business acceptance and critical-record reconciliation | ||||||||||||||||
| Runbooks, support handover, baseline, and next review |
Method, assumptions and limitations
Reviewed 14 July 2026. Product facts were checked against both the public code at the cited repository revision and official documentation. Where documentation and code differ, this guide describes behavior supported by code. Interpretations and recommendations concern implementation work, not product guarantees.
This material is not a quote, audit, certification, or legal, tax, or accounting advice. Edition, enabled modules, configuration, custom code, infrastructure, data, third-party providers, and operating practices affect the outcome.
Primary source collections: code repository, documentation, public releases.