WordPress Connector — Full Specification

00 · Front matter

How to use this spec

• Identity: repository aivis-wordpress-connector (org per shared Q-8 of the edge spec), plugin slug aivis-os, license GPL-2.0-or-later (WordPress ecosystem requirement — the deliberate divergence from the edge connector's Apache-2.0), plugin 1.0.0 target, API contract: AIVIS Public API v1.0.0.
• What it is: a delivery connector, not a rules engine. It authenticates, syncs, stores safely, matches by canonical URL, injects once, invalidates caches, and fails open. All Schema.org business logic stays in AIVIS OS. It never generates, edits, merges, repairs, ranks, or interprets structured data — and it never republishes WordPress content (no wp_update_post(), no revisions, no post_modified changes).
• Live test target: dev instance https://aivis-new.dev.onepoint.ro/api/public/v1 (docs at /docs, spec at /openapi.json) — development and staging only; the release ships the confirmed production hostname (Q-01).
• Anything marked verify at build must be confirmed against current WordPress/AIVIS behaviour before relying on it.

Doctrine mapping — edge connector → WordPress

Two intentional architecture differences: (1) WordPress syncs asynchronously instead of fetching on cold public requests — PHP origin latency must never depend on the remote API; (2) analytics is excluded (§22). Shared prerequisite with the edge connector: business-scoped API tokens (edge spec V-02) — a user-scoped token inside a customer's WordPress database (backups, exports, migrations) is a wider exposure than a Worker secret, so V-02 lands before any customer-managed install.

0R · Review verdict

Changes vs developer draft 0.9.0

Verdict: the draft is sound and is accepted as the base. Its architecture (async local sync, local-only render path, no republishing, zero-trust pipeline, honest cache states, GPL) is exactly right for WordPress. This revision makes six changes:

1. Retraction semantics added (R-01…R-03). The draft retired artifacts only after absence in two consecutive complete syncs — meaning a deliberately unpublished ("bad") JSON-LD would keep serving for ≥ 2 sync cycles plus cache TTL. Now a confirmed fetch-404 deactivates immediately, mirroring edge C-10. WP-I8 amended to match.
2. Analytics fenced permanently, with an architecture answer (§22). The draft excluded it from v1 as "not forgotten." This revision closes the question: WordPress-side crawler analytics is structurally biased, not just incomplete — so measurement moves to the edge connector, which gains an analytics-only mode for composition.
3. Per-URL "Refresh now" admin action plus honest retraction-latency display (R-03).
4. Business-scoped tokens elevated from release question (draft Q-02) to shared prerequisite for customer-managed installs (§00).
5. Marked assumptions: the /jsonld?url= multi-chain "winner" rule (non-stale first, then newest) and the loopback self-fetch used by live verification are flagged verify at build with fallbacks.
6. Format: restructured into the AIVIS-EDGE spec-sheet format with cross-connector doctrine map, AC-17, and retraction tests. All other normative content from 0.9.0 is preserved.

01 · Scope

In, out, and the customer's own responsibility

Interpretation note carried from the draft: "inject all available AIVIS plugins" means "inject all available JSON-LD artifacts exposed by Public API v1." The v1 API exposes JSON-LD and browsing/status endpoints only; any future AIVIS output types need their own versioned schemas and delivery specs — nothing generic is implemented speculatively.

02 · Guarantees

Ten invariants — each maps to automated tests

03 · Architecture

Sync path and render path never meet

Component boundaries

04 · API contract

AIVIS Public API v1 — endpoints, pagination, errors

Base /api/public/v1; every request carries Authorization: Bearer aivis_… and Accept: application/json.

• Pagination: cursor-based on all lists; request limit=200; follow nextCursor; a sync is authoritative only when every page of every chain completed. A partial traversal never deactivates stored artifacts.
• API base: release ships the confirmed production hostname (Q-01); not freely editable in the normal settings UI (an arbitrary endpoint would receive the bearer token). Development override via a documented AIVIS_API_BASE_URL constant or test-only filter.
• Transport: wp_safe_remote_get() (unsafe URLs rejected), TLS verified, zero redirects (no token forwarding), 10 s background timeout, 1 MiB response cap, connector version in the user agent, never on the public render path.

05 · Administrator experience

Settings → AIVIS OS

WordPress Settings API, standard components, accessible labels, nonces, manage_options by default (filterable, §16).

06 · Synchronization & retraction

Resumable background jobs; retraction beats retention

Initial synchronization

1. 1Verify./me, then the selected business is still accessible.
2. 2Traverse.All pages of chains, then all pages of URLs per chain; build the unique set of absolute URLs with at least one jsonLd.ready = true.
3. 3Fetch./jsonld?url=… per unique URL (AIVIS applies its winner rule); validate through ZT-01…06; upsert only valid artifacts.
4. 4Commit.Sync is complete only when the full traversal and all artifact batches finish; per-URL failures make it "completed with errors" with URL + reason shown; existing valid rows stay live.
5. 5Publish.Enable injection only after first complete sync + admin master switch; purge changed URLs; verify a bounded public sample.

Incremental synchronization

Each scheduled run traverses inventory metadata and refetches a URL only when: no local artifact exists; any candidate's generatedAt changed; readiness flipped to true; a forced refresh was requested; a prior failure's retry is due; or the local row failed its integrity check. If the fetched content hash is unchanged: update metadata, do not purge.

Batching, locking, scheduling

• Max 20 artifact requests per job; stop before the PHP execution-time budget; persist cursors/state so the next event resumes.
• Single per-site sync lock with expiry; never two concurrent inventory/artifact-write jobs; recover abandoned locks after 15 min and record the recovery.
• WP-Cron or compatible queue adapter; no blocking sleeps. Document that WP-Cron is traffic-driven — recommend system cron hitting wp-cron.php or WP-CLI where the freshness interval matters operationally.

R-01–R-03 Retraction (added — mirrors edge C-10)

• R-02 Inventory retirement (unchanged from draft): a URL merely absent from inventory retires only after two consecutive complete, authoritative syncs — protection against flaky traversals. Retirement flips the row inactive before deletion; inactive rows are retained 30 days for rollback and are never injected. Other legitimate retirement paths: admin disconnect + explicit clear; business change; per-URL admin disable.
• R-03 Latency honesty: worst-case retraction latency = sync interval + cache purge. The status screen displays it; the 5-minute interval is recommended for retraction-sensitive sites; "Refresh this URL now" gives an immediate path. Future scope (shared with edge V-03): an HMAC-signed inbound refresh ping from AIVIS, so retraction/publish latency stops depending on polling.

On-demand miss behaviour

Public request with no local row: output nothing, never call the API synchronously, schedule one deduplicated background refresh (if connected + enabled), and negative-cache that scheduling decision for 15 minutes to prevent bot-driven job floods.

07 · URL identity

Canonical URLs, not raw Host headers

AIVIS matches exactly plus a trailing-slash variant — so the plugin derives a stable canonical URL per request:

1. Singular post/page/attachment/public CPT → WordPress canonical permalink.
2. Front page / posts page → configured canonical WordPress URL.
3. Taxonomy/author/date archives → corresponding WP link API.
4. Plugin-defined routes (e.g. commerce) → the canonical URL WordPress + the owning plugin expose.
5. Fallback only: configured home origin + routed request path — never an untrusted Host header.
6. aivis_connector_current_url filter for compatibility integrations.

Normalization contract (local keys): http/https only; lowercase scheme+host; strip default ports and fragments; drop tracking-only params (utm_*, gclid, fbclid, msclkid, _ga); keep semantically meaningful params, sorted deterministically; preserve path + percent-encoding semantics; treat both trailing-slash variants as aliases; key = SHA-256 of the normalized result. The AIVIS response url is stored for audit. Normalization must never make two semantically distinct WP URLs share one artifact.

Host + business binding before storing: response businessId equals the selected business; response host ∈ allowed site hosts (defaults from home_url()/site_url(), aliases configurable for domain-mapped/multilingual setups); requested vs returned URL exact or approved alias; urlId/chainId non-empty; chain belongs to the selected business when inventory context exists.

08 · Storage

A URL-keyed table — transients are not a store

Custom table {$wpdb->prefix}aivis_jsonld (posts, pages, CPTs, archives, taxonomy URLs, commerce routes, and multilingual URLs don't all map to post meta). Created/upgraded with dbDelta() + a schema-version option.

Indexes: PK; unique url_key; (business_id, active); url_id; last_seen_sync_id; retired_at. Options (all non-autoloaded, separate): token source/status + DB fallback; selected business + allowed hosts; delivery settings; sync state/cursors; capped diagnostics; schema version; uninstall-retention preference. Transients may vanish before expiry — never the only artifact store.

09 · Zero-trust pipeline

Every artifact, every gate — the WP mirror of edge S-01…S-06

10 · Front-end injection

One hook, one element, zero network

• Hook: wp_head at priority 100. No output buffering or whole-document rewriting in core v1 (compatibility and memory risk; the standard hook already solves it). Themes must call wp_head() — absence is a Site Health warning, not an output-buffer fallback.
• Gates: site-wide switch on · normal public front-end HTML GET · not admin/REST/AJAX/feed/robots/sitemap/trackback/preview/404 · URL resolves safely · active matching local artifact · stored integrity hash passes. Injects on singular and archive routes if and only if AIVIS has an exact matching artifact — never synthesizes schema.
• Output, exactly one element: <script type="application/ld+json" data-aivis="1">…</script> — no token, IDs, debug, comments, pixels, or executable JS; no variation by UA, cookie, consent, login, referrer, or IP (WP-I3); per-request guard against duplicate emission if the hook fires twice; never searches for or touches other JSON-LD; on any runtime check failure emit nothing and continue (WP-I1).
• Performance budget (uncached origin render, warm DB): zero outbound network calls; ≤ 1 indexed query; p95 connector overhead < 5 ms excluding JSON write-out; no front-end writes except the deduplicated miss-schedule.

11 · Cache & publication

Stored is not live — publication is a tracked state

An artifact is "stored" after local commit; it is "publicly live" only after a compatible adapter confirms invalidation for the URL or live verification finds data-aivis="1" with the expected hash in public HTML (WP-I10). Cache invalidation is infrastructure, never a content edit (WP-I5).

1. Collect + deduplicate changed public URLs after commit.
2. Resolve a post ID when possible → clean_post_cache() (object caches only — not assumed to purge page caches/CDNs).
3. Pass the URL batch to the cache-adapter interface; fire do_action( 'aivis_connector_purge_urls', $urls, $context ).
4. Record per-provider result: confirmed · requested-not-confirmed · unsupported · failed.
5. Run bounded live verification after a confirmed/requested purge. The self-fetch may be blocked by loopback restrictions on some hosts verify at build — fall back to an admin-browser check or WP-CLI verify.

Adapter interface: is_available(): bool; purge_urls(array $urls): PurgeResult; optional purge_all() (first activation/deactivation only); provider-safe batching; sanitized errors; no AIVIS credentials. Targeted purges preferred; full-site purge only when the provider can't purge URLs and the admin initiated enable/disable/deactivate/full-resync. Never flush the global WP object cache just to publish JSON-LD. No supported adapter: finish the sync, mark "manual purge required" with affected-URL count + instructions, never claim live, allow verification after the manual purge. Bundled adapter matrix is a release decision (Q-03); the neutral interface + manual fallback are mandatory.

12 · Failure behaviour

Every failure, what happens instead

Stable error codes only — e.g. AIVIS_AUTH_401, AIVIS_HTTP_TIMEOUT, AIVIS_SCHEMA_INVALID, AIVIS_SCOPE_MISMATCH, AIVIS_RETRACTED, AIVIS_DB_WRITE, AIVIS_PURGE_UNSUPPORTED. Raw bodies and authorization headers are never logged.

13 · Security & privacy

WordPress hygiene, secret honesty, zero telemetry

• Admin: manage_options (filterable) for all config/sync actions; nonces on every state change; sanitize on input, escape at output; prepared queries via WP DB APIs; no direct PHP file execution; no public unauthenticated connector REST endpoints (internal progress polling requires REST nonce + capability).
• Secrets: token never returned to the browser, never in URLs, only in the Authorization header to the fixed host; redirects disabled; bearer-shaped strings redacted from exceptions; excluded from export/support tools; rotation + revocation documented. Preferred custody: AIVIS_API_TOKEN constant (wp-config or environment). DB fallback follows the WordPress security model and is described honestly — no fake "encryption" with a key stored beside the ciphertext.
• Privacy (WP-I9): no crawler analytics, no visitor telemetry, no raw UA/IP storage, no WP-user or customer data to AIVIS. Sync necessarily sends requested URLs/IDs + the bearer token to AIVIS. Ship PRIVACY.md and a clear external-service disclosure in readme.txt.
• Supply chain: no remotely downloaded executable code; dependencies committed/built into release ZIPs under compatible licenses with public lockfiles; GitHub Actions pinned to SHAs; CI builds official releases (never personal machines); SHA-256 checksums + provenance; SECURITY.md with private disclosure + supported versions; dependency/static-analysis/secret/license scans in CI.

14 · Plugin lifecycle

Activate, deactivate, uninstall, upgrade — all reversible

15 · Compatibility

Baseline, routes, Multisite, i18n

• Baseline (Q-05): WordPress 6.5+, PHP 8.1+, WP-supported MySQL/MariaDB, standard single-site, themes calling wp_head().
• Routes: the URL-keyed design covers posts, pages, public CPTs, taxonomy/author/date archives, translated URLs, and plugin routes with stable canonical URLs. No dependency on Gutenberg, Classic Editor, page builders, or any SEO plugin.
• Multisite (Q-06): network activation may load the plugin, but config/storage/sync/delivery stay per site (own business + token context; correct table prefix on blog switch). No network-wide admin or sync. If not fully tested before release, v1 blocks network activation instead of half-supporting it.
• i18n/a11y: all strings translatable under one text domain; English source, German as first translation; admin UI meets WP accessibility conventions (keyboard, labels, focus order, status announcements, non-color-only states).

16 · Extension contract

Stable hooks, no business-logic leaks

apply_filters( 'aivis_connector_current_url', $url, $query_context );
apply_filters( 'aivis_connector_allowed_hosts', $hosts );
apply_filters( 'aivis_connector_manage_capability', 'manage_options' );
apply_filters( 'aivis_connector_sync_interval', $seconds );

do_action( 'aivis_connector_artifact_changed', $url, $old_hash, $new_hash );
do_action( 'aivis_connector_purge_urls', $urls, $context );
do_action( 'aivis_connector_sync_completed', $summary );
do_action( 'aivis_connector_sync_failed', $error_code );

• No filter that lets third parties rewrite raw JSON-LD in core v1 — that would move output responsibility into the connector.
• Hook payloads never include the token or authorization headers; public hooks are documented and covered by BC tests.
• Optional WP-CLI wrapping the same services (never a second sync implementation): wp aivis connection test · wp aivis sync --all · wp aivis status · wp aivis verify [--url=…].

17 · Observability

Local diagnostics + Site Health — nothing leaves the site

• Capped run history: run ID; timestamps/duration; trigger (setup/manual/scheduled/CLI/retry); counts for chains, URLs, fetched, unchanged, updated, stale, retired, failed; stable error codes; purge + verification summaries; connector/API versions. Never stored: tokens, auth headers, visitor requests, IPs, user agents, raw response bodies, unbounded logs.
• Site Health tests (capability-protected): token configured + connection state; initial sync completed; overdue scheduled sync; wp_head()/live-marker verification; stale artifacts; unsupported/failed cache invalidation; DB schema health.

18 · Open source & releases

GPL, reproducible ZIPs, CI-built releases

aivis-wordpress-connector/
├── aivis-os.php                  bootstrap + plugin headers (incl. Update URI)
├── src/ {Admin, Api, Cache, Delivery, Domain, Security, Storage, Sync}
├── assets/  ├── languages/
├── docs/ {SPECIFICATION, ARCHITECTURE, CACHE-INTEGRATIONS, PRIVACY, RUNBOOK, THREAT-MODEL}.md
├── tests/ {Unit, Integration, EndToEnd}
├── .github/ {ISSUE_TEMPLATE, workflows, dependabot.yml}
├── composer.json · composer.lock · phpcs.xml.dist · phpunit.xml.dist
├── readme.txt · uninstall.php
└── CONTRIBUTING.md · SECURITY.md · CHANGELOG.md · LICENSE

• License GPL-2.0-or-later; all bundled libraries/assets GPL-compatible. The AIVIS platform stays proprietary; the connector's complete corresponding source is public. Namespaces + DI for testability, no heavy framework.
• Release model: SemVer; protected default branch + mandatory PR review; CI on every PR; tagged releases built by CI; ZIP contains runtime files/licenses/translations only; SHA-256 checksum + generated changelog; Update URI header points at the canonical repo (prevents update-collision hijacks); v1 documents manual GitHub-release upgrades — WordPress.org distribution is a separate decision (Q-07).
• CI gates: PHP syntax matrix; WPCS via PHPCS; static analysis; PHPUnit unit + integration; WP/PHP compatibility matrix; JS/CSS checks if admin assets appear; dependency vulnerability + license scan; secret scan; build-reproducibility check; release-ZIP install smoke test.

19 · Testing

Proving the invariants, not just the features

20 · Acceptance criteria

Demonstrated on staging against the designated AIVIS environment

21 · Milestones

M0 → M6

1. M0Contract lock.Production API base; repo org/name; WP/PHP baseline; token scope + rotation (V-02 dependency); cache-adapter launch matrix. Resolves Q-01…Q-08.
2. M1Skeleton, storage, API client.Public GPL repo from first commit; bootstrap + DI boundaries; settings/secret storage; custom table + migrations; hardened API client with mock contract tests.
3. M2Inventory & synchronization.Business selection + host binding; cursor traversal; resumable initial/incremental jobs; LKG writes, retries, retirement and retraction R-01…R-03.
4. M3Delivery.Canonical URL resolver; safe wp_head injector; performance + fail-open tests; UA parity + zero-trust tests.
5. M4Cache publication & operations.Adapter interface + launch adapters; manual fallback; live verification; status dashboard, Site Health, disable/deactivate runbooks.
6. M5Hardening & OSS readiness.Full compatibility matrix; threat model, privacy + external-service disclosure, contribution/security policies; CI gates; release packaging + provenance.
7. M6Pilot & 1.0.0.Staging smoke against live API; pilot on an AIVIS-controlled WP site with real page cache/CDN; failure drills (API outage, invalid token, malformed artifact, delayed cron, failed purge, retraction, rollback); tagged 1.0.0 + customer runbook.

22 · Analytics decision

Permanently out of WordPress — measured at the edge instead

The architecture answer — measure where every request is visible:

• WP site behind Cloudflare (typical SMB): compose the two connectors. The WordPress plugin delivers JSON-LD at the origin (the block rides inside cached HTML — zero added edge latency), and the edge worker runs in analytics-only mode (edge spec: INJECT=off; its idempotency check detects the origin-shipped data-aivis block and records injected:"origin"). Delivery at origin, measurement at the edge — each layer does the one thing it can do truthfully.
• WP site not behind any CDN: no traffic analytics — and that's fine. The Monitoring SKU's core evidence is platform-side anyway: AIVIS's forensic/citation runs measure the outcome (is the brand reconstructed correctly in ChatGPT/Perplexity), which needs no site instrumentation at all. Crawler traffic is a leading indicator, nice to have where it's accurate; it is not the product.
• Consequences here: WP-I9 (zero telemetry) is permanent — which also keeps the plugin clean for any future WordPress.org review; the AIVIS events-ingest endpoint (edge V-01) remains an edge-connector dependency only; no analytics settings, warnings, or partial modules ever appear in the WP admin UI.

Appendix · Release decisions

To confirm in M0