Runtime Current State¶

Status: CURRENT

This document is the operational source of truth for the observed runtime posture of CMonChoix Platform. It records what is actually deployed, how it is executed, and which operational invariants must remain true.

It is not the architectural specification. For architecture, see ../runtime/overview.md.

Server context¶

Project root:

/mnt/data/cmonchoix-platform

WordPress runtime:

/mnt/data/cmonchoix-platform/wordpress

WP-CLI is executed from the worker service:

docker compose exec platform-worker wp --allow-root --path=/var/www/html ...

Do not assume a hard-coded container name when the Compose service is available.

Canonical plugin source¶

The repository contains one canonical plugin source:

plugins/ccx-feeds-industrial/

Docker Compose mounts this directory read-only at the runtime path in both WordPress and the platform worker:

/var/www/html/wp-content/plugins/ccx-feeds-industrial/

The legacy repository path must remain absent:

wordpress/wp-content/plugins/ccx-feeds-industrial/

Operational rules:

patch only the canonical source under plugins/;
never materialize or track an independent runtime mirror;
keep both Compose bind mounts read-only;
require identical tree hashes for the host, WordPress and worker;
use make doctor to enforce these invariants before and after deployment.

Canonical Platform classes remain under:

src/
vendor/

WordPress consumes them through the configured read-only mounts. Do not copy src/ into wordpress/ and do not create a second Platform namespace inside the plugin.

Bootstrap topology¶

The certified WordPress bootstrap graph is:

ccx-feeds.php
    -> bootstrap/platform.php
    -> bootstrap/plugin.php
        -> route-maintenance.php
        -> worker.php
        -> http.php
        -> admin.php
        -> cli.php
        -> frontend.php

Context runtimes:

admin    -> bootstrap/runtime-admin.php
HTTP     -> bootstrap/runtime-http.php after authorization
CLI      -> bootstrap/runtime-cli.php
worker   -> bootstrap/runtime.php

Targeted capability loaders:

bootstrap/mapping.php
bootstrap/quality.php
bootstrap/pipeline.php
bootstrap/strict.php
bootstrap/strict-schema.php
bootstrap/verticals.php
bootstrap/product-models-application.php

These loaders must remain lazy. The presence of the runtime bootstrap does not prove that the Pipeline, Mapping or Quality stack has been loaded.

Context loading matrix¶

Context	Frontend	Admin	CLI	HTTP	Worker	Pipeline
frontend request	1	0	0	0	0	0
admin read-only	0	1	0	0	0	0
admin action	0	1	0	0	0	targeted
CLI simple	0	0	1	0	0	0
CLI targeted action	0	0	1	0	0	targeted
HTTP forbidden / health	0	0	0	1	0	0
HTTP worker authorized	0	0	0	1	service	targeted
passive cron / empty queue	0	0	0	0	1	0
resumable worker run	0	0	0	0	1	targeted

Operational consequences:

frontend, admin, CLI, HTTP and worker adapters must not include one another;
a read-only request must not bootstrap the full Pipeline;
cron registration must remain lightweight when there is no resumable work;
the Pipeline is loaded only by actions that actually execute pipeline work.

Sync runtime¶

The Sync Runtime boundary is split by responsibility:

interfaces/admin/sync-runtime.php
application/admin-sync-runtime-read.php
application/admin-sync-runtime-actions.php
interfaces/admin/sync-runtime-view.php

CLI reads and actions are delegated through application facades:

application/cli-sync-runtime-read.php
application/cli-sync-runtime-actions.php
application/sync-runtime-actions.php

Rules:

adapters perform parsing, authorization, validation, delegation and output formatting only;
application facades remain transport-neutral;
no HTML, redirects, headers or direct request-global reads belong in application services;
no direct SQL belongs in the public adapter surfaces;
command names, nonces, redirects and observable payloads must remain stable unless explicitly versioned.

Projection writes¶

Projection writes are centralized behind dedicated services.

Offer projection:

CCX_OfferProjectionWriteService

Product Model projection family:

CCX_ProductModelProjectionWriteService
CCX_ProductVariantProjectionWriteService
CCX_ProductSpecificationProjectionWriteService
CCX_ProductGalleryProjectionWriteService

Multi-projection rebuild orchestration:

CCX_ProductModelRebuildOrchestrator

Canonical rebuild order:

Product Models
Variants
Specifications
Gallery

Entrypoints and orchestrators must not call legacy projection writers directly. Only the dedicated projection services and explicitly documented compatibility writers may touch projection SQL.

Media Quality operational posture¶

Media Quality runs after offer projection through the normalized offers path:

projection writer
    -> ccx_feeds_upsert_items_to_offers_norm()
    -> pipeline/90-offers-norm.php
    -> includes/media-quality/engine.php
    -> includes/media-quality/rules/*

Current policy is audit-first:

mutation is disabled by default;
image_norm must not be cleared because evidence is uncertain or contradictory;
observations, reason codes and metrics are produced before any write is considered;
replacement is allowed only when a sufficiently strong candidate is available;
a historical run whose images were already cleared must be regenerated before new metrics are trusted.

Historical destructive behavior under includes/pipeline/norm/25-image-quality.php is compatibility debt, not the policy reference.

Operational checks must distinguish at least:

scanned rows;
rows with image and color evidence;
checked rows;
matched rows;
mismatched rows;
unknown actual color;
ambiguous evidence;
replacement candidates found or absent;
mutations attempted and applied.

A run is not considered healthy merely because it completed. Its evidence distribution and mutation counters must also be reviewed.

WP-CLI verification¶

Do not verify command presence with plain grep against wp cli cmd-dump --format=json. The command emits a nested JSON tree.

Use one of these approaches:

docker compose exec platform-worker wp --allow-root --path=/var/www/html help ccx

or parse the JSON structurally:

docker compose exec platform-worker wp --allow-root --path=/var/www/html cli cmd-dump --format=json | jq ...

Operational scripts must fail explicitly when a command is absent instead of interpreting an empty grep result as authoritative.

Health and HTTP¶

The health route remains a thin HTTP adapter around application services. Authorization, throttling and response translation belong at the boundary; health computation belongs in the application layer.

The generic runtime bootstrap must not register HTTP hooks directly. Unauthorized and health-only requests must not load the full Pipeline.

Technical state¶

WordPress options, transients and named locks are accessed through the technical state boundary rather than scattered direct calls.

Technical state includes, among other concerns:

governance snapshots;
cache state;
health throttles;
Product Models cache entries;
ccx_offers_version;
named-lock consumers.

Merchant activation is not WordPress technical state. CCX_ACTIVE_FEEDS is the single deployment-owned authority. The legacy ccx_runtime_enabled_feeds option must remain absent, and runtime activation write helpers fail closed.

Loading a capability must not install or mutate schema implicitly. Schema work belongs to explicit installation, migration or maintenance commands.

Run safety¶

Every operational run must expose enough information to diagnose and resume safely:

run identifier;
feed or scope;
start and end timestamps;
current status;
processed and failed counts;
batch or offset information;
last error and reason codes;
whether persistence or mutation occurred.

Expected safety properties:

idempotent replay where supported;
explicit resume semantics;
no duplicate projection caused by retry;
no silent partial success;
bounded batches;
controlled locks and timeouts;
observable cancellation.

Deployment and synchronization procedure¶

Before runtime work:

confirm the active Git branch;
confirm the plugin copy loaded by WordPress;
inspect the relevant bootstrap and application service;
capture baseline command and database metrics.

After a change:

run syntax and targeted tests;
verify bootstrap isolation for affected contexts;
run the relevant WP-CLI command in the worker service;
compare runtime metrics with the baseline;
verify that unintended schema or projection writes did not occur;
record the commit SHA and operational result.

When historical data has been destructively altered, rebuild the affected projection before evaluating a new algorithm.

Operational invariants¶

The runtime is considered conformant only while all of the following remain true:

Adapters are thin and context-specific.
Shared application services are transport-neutral.
Read-only contexts do not load the full Pipeline.
Frontend requests do not perform persistent route-maintenance writes.
Passive cron does not bootstrap pipeline work without a resumable job.
Projection writes pass through dedicated write services.
Schema mutation is explicit and never an incidental side effect of loading code.
Media Quality is non-destructive by default.
The canonical plugin source is mounted read-only and no runtime mirror exists.
Merchant activation has one deployment-owned authority and no WordPress option shadow.
Every material run is traceable, diagnosable and safely resumable.

../runtime/overview.md
../architecture/media-quality-engine.md
../pipeline/normalisation.md
../business-domains/catalog/projection-engine.md
../contracts/quality-scorer.md
../../plugins/ccx-feeds-industrial/README.md