Kat3x Catalog Guard

By office4llm

0+ active installationsVersion 0.4.3

Compare WooCommerce catalogs with expected CSV lists and review differences with your assistant, within a declared scope.

Description

Complete user guides (EN, IT, DE, FR, ES) are in docs/ inside this ZIP; start with docs/en.md or your language. Technical reference: docs/reference.md.

Compare a WooCommerce catalog with an expected price list and show the differences
to your assistant, with the scope of the check always visible. Catalog Guard helps
agencies and catalog operators prepare an import handover with declared exclusions.
Load two CSV files, or compare one list with two read-only WooCommerce observations.
Confirm the proposed column mapping and decimal conventions before comparing.
Only SKU is required. Unmatched fields are listed; totals needing an unmatched
field are not calculable. Known unsupported importer columns are excluded explicitly.
The plugin reports differences, duplicate keys, ambiguous readings and a reconciliation
of stock and value totals. Prices use integer cents. It does not import or repair products.
The administration page is supplied in English, Italian, German, French and Spanish.

What the comparison can establish

Store reads use prepared SQL SELECTs (wpdb_select) and WooCommerce REST v3 GETs
inside WordPress (wc_rest_v3, wc_data_store, wp_object_cache). Both use the same
database: independence concerns the layers above it. Both enforce the same user
permission policy. No network requests are made by these readers.
A single available reading yields partial coverage with single_observation.
Two complete independent agreeing readings can yield the technical state verified.
Conflicting observations select no value. The catalog changing during a reading
can yield stale. Compatibility combinations remain empty: combo_unknown applies.
A signature does not establish store truth, freshness, revocation status, or importer compatibility.

Parent-managed stock is read from the parent. Effective prices use the sale dates
at the chosen instant. Variation names are not compared because WooCommerce derives
them from the parent and attributes; the local report states this limit. Other product
names are compared as original UTF-8 bytes. Only a hash and length are used internally
for agreement; neither the name nor its hash enters the signed export.
Product attributes are not observed by the store readers and remain a declared limit.
Without intl the original Unicode difference is retained and normalization is reported
unavailable. Windows-1252 conversion requires iconv; other unsupported encodings are rejected.

Five-minute demonstration

  1. Open WooCommerce > Kat3x Catalog Guard and select Use the demonstration sample.
  2. Review proposed columns and decimal conventions, then Compare.
  3. Inspect the 15 exceptions and the stock/value reconciliation.
  4. Download exceptions.csv and the unsigned local report.
  5. For store mode, load File A, select read-only store comparison, choose before/after
    import and optionally whole-catalog scope, then download the signed receipt.
    The sample is synthetic. A successful demonstration does not validate a real import.
    Contextual Help on this page explains the workflow, limits and common problems.
    The user guide in English, Italian, German, French and Spanish is included
    in the docs/ folder of the plugin.

Node and signing limits

The signing key is stored in the installation, in the plugin database option with
autoload disabled. The expected responses do not export it. Anyone with database
access or code execution on the site can read it; backups, caches and site copies
require protection and revocation management.
Two copies with the same address cannot be distinguished by the store: use a new
identity on every staging copy. Uninstalling removes local options but does not
revoke the key in the register: request revocation from Kat3x.
The comparison runs in the store. The receipt contains the declared reduced fields;
in the optional assistance path it passes to the customer’s model and Kat3x.
The signature permits checks of integrity and signing key. The receipt describes the readings and comparisons declared by the node; it does not guarantee that the catalog is correct. A compromised site can sign false data.
The plugin sends nothing on its own. Optional assistance uses customer-configured
connectors and requires a compatible model, Abilities API and MCP Adapter, revocable
credentials and product permissions; the complete assistance path still requires testing.
Guard and Sonda sign locally. Admission and verification of the node by the kernel
are under construction and require their own checks.
build_digest is the build declared by the node, without attesting the running code.
The node identifier and shop_ref are stable pseudonyms. Service purpose, retention
and deletion must be declared before the first real store uses the service.

Signed receipt ability (0.4.0)

The optional WordPress MCP Adapter can expose kat3x-catalog-guard/receipt to a user
with manage_woocommerce. The caller supplies CSV text (at most 1048576 bytes), column
mapping, decimal convention, whole-catalog flag and import phase. No file path or
saved page result is accepted as a reference.
Every call reads the catalog again through the same database and in-process REST
readers used by the local comparison. A stale REST object cache can produce a declared
conflict; timestamps and watermark alone do not prove new data.
A supplied kernel request is copied unchanged after structural and UTC calendar checks.
Without one, the receipt declares issued_by plugin-locale; freshness is not guaranteed
by the kernel. The plugin does not decide whether the kernel issued a request or
whether it was already consumed.
The signed ability response contains the receipt only. Technical text identifiers are
replaced by opaque references local to that receipt, product names are omitted, and
supported numeric differences remain visible. These references cannot be matched
across receipts. The local page download retains its separate, existing export policy.
Orders, customers and user data are outside this catalog response.
The three node abilities do not change catalog rows or node options after activation,
except that a failed signature with a broken key records chiave_non_valida. Saving a
shop reference preserves chiave_da_ammettere and chiave_non_valida.
PHP, WordPress, MCP Adapter and Plugin Check are evaluated separately at the server
bench. The release is not admitted by its author and compatibility is not assumed.
The skeleton uses the product namespace; Abilities API is optional for panel use.

Privacy

The plugin reads product lists and catalog data, not orders or customers. No external
services are called. The local report contains full product names; the signed receipt
omits them. The signed ability uses opaque text references local to each receipt;
supported numeric differences remain visible. The local page has a separate export policy.
Uploads are private temporary files, retained for one hour and removed on cleanup.
WP-Cron is request-driven, so deletion may occur later. Signing keys and node options
are stored locally. Protect database access, code execution, backups and site copies.
The node identifier and shop_ref are stable pseudonyms, not anonymous values.
If optional assistance is chosen, the reduced receipt passes through the configured
model and Kat3x. Define service purpose, retention and deletion before the first real
store. Do not include customer or supplier data in a support example.

Installation

  1. Use WordPress 6.9 or later and PHP 8.1 or later with WooCommerce active.
  2. In Plugins > Add New > Upload Plugin, select the release ZIP and activate it.
  3. Open WooCommerce > Kat3x Catalog Guard with an account granted manage_woocommerce.
  4. Start with the synthetic demonstration, then confirm mapping and decimal settings
    for your own files before interpreting the result.
    Network activation is refused. Configure a distinct node identity on each site copy.
    Signed receipts need the PHP sodium extension. Without it the plugin still works:
    file and store comparison and the local report are available, and signed receipts are off.
    Translations come as language packs: put kat3x-catalog-guard-.mo in
    wp-content/languages/plugins/ and WordPress loads it for that site language.

FAQ

For complete procedures, result checks and troubleshooting, read docs/en.md, docs/it.md, docs/de.md, docs/fr.md or docs/es.md inside the plugin ZIP. Technical details: docs/reference.md.

Does Catalog Guard import or change products?

No. It compares files or reads catalog data. Review reported differences before
choosing a correction in your importer or store workflow.

How should an agency use the result after an import?

Compare the intended list with the store, check coverage and exceptions, and include
the declared scope and limits when handing the report to the client. Do not present
an unsigned report or a technical verified state as a certification of the whole store.

What if a column is not recognized?

Confirm its mapping manually or leave it unmatched. Only SKU is required. A field
without a mapping is not compared; totals depending on that field are not calculable.

What are the CSV limits?

The page accepts at most 5 MB per file and 10000 data rows across the files. The optional
signed receipt ability accepts CSV text up to 1048576 bytes, not a file path.

Does a valid signature prove the catalog is correct?

The signature permits checks of integrity and signing key. The receipt describes the readings and comparisons declared by the node; it does not guarantee that the catalog is correct. A compromised site can sign false data.
A signature does not establish store truth, freshness, revocation status, or importer compatibility.

Are the two store observations independent databases?

No. Both use the same database; independence concerns the layers above it. A single
reader yields partial coverage. Conflicts select no value. Stale cache contents can
cause a conflict; timestamps alone do not prove freshness.

Where is the signing key stored and what happens on a site copy?

It is in a database option with autoload disabled. Database access or site code can
read it. Protect backups and copies, and create a new identity on each staging copy.
Two copies with the same address cannot be distinguished by the store. Uninstalling
does not revoke a key in the register; revocation is a separate operation.

Does the plugin contact external services?

No external services are called by the plugin. Optional assistance uses connectors
you configure; the reduced receipt then passes to your model and Kat3x. Review the
service purpose, retention and deletion policy before sharing a real store receipt.

Why are variation names or attributes not compared?

Variation names are generated by WooCommerce and are excluded. Other names are
compared as original bytes. Product attributes are not observed by these store readers.

Why can cleanup happen later than one hour?

Uploads are private temporary files retained for one hour and removed on cleanup.
WP-Cron runs when WordPress receives requests, so cleanup may run later. Deactivation
clears scheduled cleanup and removes the temporary files for this plugin.

Which permissions and optional integrations are needed?

The page and receipt ability require manage_woocommerce. Node configuration requires
manage_options. Panel use does not require an AI model. Optional assistance requires
a compatible model, WordPress Abilities API and MCP Adapter with revocable credentials;
the complete admission and assistance path requires separate testing.

Changelog

0.4.3

Translations arrive as language packs; the ZIP carries only the POT template.
No change of function.

0.4.2

Changes for the WordPress.org plugin review only. The exceptions filter script is now
enqueued with wp_add_inline_script on the plugin page only. Every PHP file stops when
loaded directly, outside WordPress. Activation without the PHP sodium extension no
longer fails: no key or node option is written, and signed receipts are turned off.
The receipt format is unchanged.

0.4.1

Complete five-language user guides and English technical reference included in docs/.
Updated the directory description and release metadata; no comparison logic changed.
Prepared English and Italian Demo A instructions and an observation sheet, supplied
alongside the release. Screenshot, banner and icon assets remain pending.
Carries forward the 0.4.0 maintenance fixes: a release-versioned POT, user guides
inside the ZIP, and the Plugin Check warning fixes tested for that earlier build.
The 0.4.1 build needs its own runtime and Plugin Check results; earlier results
do not establish acceptance of this release.

0.4.0

Added the optional signed receipt ability with a fresh store read for each call,
bounded CSV text input and receipt-local opaque references. Added contextual help
and a separate user guide. Reorganized this readme for the directory format.
Runtime acceptance and node admission remain separate checks.

0.3.0

Added local node identity, public key/status abilities and the 0.4 receipt contract.
Release metadata is read from the product card. Signing keys remain local, with
explicit limits for database access, staging copies and external revocation.

0.2.4

Temporary page keys use the full product prefix; a session open during the update must reload its file.

0.2.3

Corrected two pure tests and one test mutant; no behavior changes.

0.2.2

Variation names are excluded from agreement and file/store name comparison:
WooCommerce generates them from the parent and attributes. The local report
states this limit. Other product names are still compared as original bytes.
M0 0.5 scales the interrupted import to 1000 file rows, 600 imported and 400 missing.
The supplied server script limits pure runs and mutants to 600 seconds each.
WordPress keeps the bench time limit and reports seconds for each M0 case.
No compatibility combination is claimed before the runtime bench.

0.2.1

Test imports use .csv temporary files; unavailable REST routes and empty stock
are constructed explicitly in the test bench. Automatic drafts are excluded
from all direct database queries. Failing M0 cases print field diagnostics.
Parent stock agreement still requires the WordPress bench; the previous P03
conflict has no proven cause yet. No compatibility combination is claimed.

0.2.0

Optional columns and two distinct store transports. Runtime PHP and WordPress checks are performed separately
at the release test bench; no compatibility combination is claimed without its result.