Changeset 3784837

clautron/tags/1.5.0/clautron.php

-              r3691450
+              r3784837
  * Plugin URI:        https://wordpress.org/plugins/clautron/
  * Description:       Get the feature. Not the plugin. Add exactly the WordPress capability you need: inspectable, secure, reversible.
  * Version:           1.2.0
+ * Version:           1.5.0
  * Author:            Clautron
  * Author URI:        https://profiles.wordpress.org/dudaster/
 …
 // ─── Constants ───────────────────────────────────────────────────────────────
 define( 'CLAUTRON_VERSION',     '1.2.0' );
+define( 'CLAUTRON_VERSION',     '1.5.0' );
 define( 'CLAUTRON_FILE',        __FILE__ );
 define( 'CLAUTRON_DIR',         plugin_dir_path( __FILE__ ) );
 define( 'CLAUTRON_URL',         plugin_dir_url( __FILE__ ) );
 define( 'CLAUTRON_DB_VERSION',  '4' );
+define( 'CLAUTRON_DB_VERSION',  '5' );
 // ─── Autoloader ──────────────────────────────────────────────────────────────
 …
         'primitive-cookie'     => 'includes/primitives/class-primitive-cookie.php',
+        // Consent (cookie-consent banner + category-gated script output)
+        'primitive-consent'    => 'includes/primitives/class-primitive-consent.php',
         // Language (multilingual query filtering)
         'primitive-language'   => 'includes/primitives/class-primitive-language.php',
 …
         'catalog'              => 'includes/class-catalog.php',
+        // Capability Manifest (machine-readable contract: version, requirements, scopes, effects)
+        'manifest-registry'    => 'includes/registry/class-manifest-registry.php',
+        'capability-store'     => 'includes/class-capability-store.php',
         // Smoke Tester (verify compiled blueprints are wired correctly)
         'smoke-tester'         => 'includes/class-smoke-tester.php',
+        // Abilities (every operation above as a self-describing WordPress Ability)
+        'abilities'            => 'includes/class-abilities.php',
         // Admin

clautron/tags/1.5.0/demo/blueprint-cookie-consent.json

-              r3691441
+              r3784837
   "id": "f2a3b4c5-d6e7-4890-b123-c45678901bcd",
   "object_type": "feature",
   "name": "Cookie Consent Banner",
   "description": "Shows a GDPR-style cookie consent banner in the footer with an Accept link. Clicking it stores consent in a first-party cookie for 365 days, which also suppresses the banner on return visits. Replaces a basic cookie-notice plugin.",
+  "name": "GDPR Consent Banner",
+  "description": "Cookie-consent banner with per-category consent (necessary/analytics/marketing), a full audit trail of who consented to what and when, automatic opt-out when the visitor's browser sends Global Privacy Control (Sec-GPC), and Google Consent Mode v2 signals for GA4/Ads. Replaces a dedicated cookie-consent plugin for the common case.",
   "capability_id": "cookie-consent-banner",
   "provides": {},
   "status": "draft",
   "source": "manual",
   "nl_input": "Show a cookie consent banner on the site with an accept button that remembers the choice for a year.",
+  "nl_input": "Show a GDPR cookie consent banner with analytics/marketing categories, honor Global Privacy Control automatically, and signal Google Consent Mode.",
   "structures": [
+    {
       "id": "s-banner",
       "type": "inject_wp_footer",
+      "type": "consent_banner",
       "config": {
+        "template": "<div id=\"clautron-cookie-banner\" style=\"position:fixed;bottom:0;left:0;right:0;background:#222;color:#fff;padding:14px 20px;font-size:14px;z-index:9999;\">This site uses cookies to improve your experience. <a href=\"?clautron_action=accept_cookies\" style=\"color:#8ecdf7;\">Accept</a></div>",
+        "suppress_if_cookie": "cookie_consent"
+        "categories": [
+          { "key": "necessary", "label": "Necessary", "description": "Required for the site to function.", "required": true },
+          { "key": "analytics", "label": "Analytics", "description": "Helps us understand site usage." },
+          { "key": "marketing", "label": "Marketing", "description": "Used for ad personalization." }
+        ],
+        "policy_version": "1",
+        "banner_text": "This site uses cookies. Choose which categories you're OK with.",
+        "position": "bottom",
+        "days": 180,
+        "endpoint_path": "consent",
+        "honor_gpc": true,
+        "consent_mode_map": {
+          "analytics": ["analytics_storage"],
+          "marketing": ["ad_storage", "ad_user_data", "ad_personalization"]
+        }
+      }
+    },
+    {
+      "id": "s-analytics-script",
+      "type": "gate_script_by_consent",
+      "config": {
+        "category": "analytics",
+        "html": "<!-- Load your analytics script here — it only outputs once \"analytics\" consent is granted -->",
+        "placement": "head"
+      }
+    }
-  ],
-  "trigger": { "type": "hook", "config": { "hook": "template_redirect" } },
-  "conditions": [
-    { "id": "c1", "type": "read_request_param", "config": { "source": "get", "param": "clautron_action", "output_variable": "action", "default": "" } },
-    { "id": "c2", "type": "if_else", "config": { "field": "{{action}}", "operator": "eq", "value": "accept_cookies", "pass_branch": ["a1"], "fail_branch": [] } }
-  ],
-  "actions": [
-    { "id": "a1", "type": "write_cookie", "config": { "name": "cookie_consent", "value": "accepted", "days": 365 } }
+  ]
+}

clautron/tags/1.5.0/includes/class-catalog.php

-              r3582869
+              r3784837
  *  - Active capabilities (compiled + running on this site).
  *  - Available templates (demo blueprints not yet installed).
+ *  - inspect(): install/version/compatibility state for one capability_id.
+ *
+ * When a capability_id has a manifest (demo/capabilities/*.manifest.json,
+ * loaded via CLAUTRON_Manifest_Registry), catalog entries carry it under
+ * 'manifest' plus a 'has_manifest' flag — additive, so capabilities without
+ * a manifest keep working exactly as before.
+ *
  * External systems (e.g. AICOM) call these methods directly — no HTTP needed.
 …
                 continue;
+            }
+            $manifest = class_exists( 'CLAUTRON_Manifest_Registry' ) ? CLAUTRON_Manifest_Registry::get( $data['capability_id'] ) : null;
             $active[] = [
                 'capability_id' => $data['capability_id'],
 …
                 'provides'      => $data['provides'] ?? [],
                 'llm_guide'     => $data['llm_guide'] ?? '',
+                'manifest'      => $manifest,
+                'has_manifest'  => $manifest !== null,
             ];
+        }
 …
                 continue;
+            }
+            $manifest = class_exists( 'CLAUTRON_Manifest_Registry' ) ? CLAUTRON_Manifest_Registry::get( $data['capability_id'] ) : null;
             $templates[] = [
                 'capability_id' => $data['capability_id'],
 …
                 'provides'      => $data['provides'] ?? [],
                 'llm_guide'     => $data['llm_guide'] ?? '',
+                'manifest'      => $manifest,
+                'has_manifest'  => $manifest !== null,
             ];
+        }
 …
+        }
+        // Find template file.
+        $demo_dir = CLAUTRON_DIR . 'demo/';
+        $template = null;
+        foreach ( glob( $demo_dir . '*.json' ) ?: [] as $path ) {
+            $data = json_decode( file_get_contents( $path ), true );
+            if ( is_array( $data ) && ( $data['capability_id'] ?? '' ) === $capability_id ) {
+                $template = $data;
+                break;
+            }
+        }
+        // Known but not active (e.g. deactivated) — reactivate the SAME
+        // blueprint instead of creating a new one, so version history and
+        // the blueprint's own identity survive a deactivate → install cycle.
+        $known = class_exists( 'CLAUTRON_Capability_Store' )
+            ? CLAUTRON_Capability_Store::find_by_capability_id( $capability_id )
+            : null;
+        if ( $known ) {
+            $existing_blueprint_id = (int) $known->blueprint_id;
+            $existing_row          = CLAUTRON_Blueprint_Store::get( $existing_blueprint_id );
+            if ( $existing_row ) {
+                $result = CLAUTRON_Plugin::make_compiler()->compile( $existing_blueprint_id );
+                if ( ! empty( $result->get_errors() ) ) {
+                    return [
+                        'success'       => false,
+                        'blueprint_id'  => $existing_blueprint_id,
+                        'compiled'      => false,
+                        'capability_id' => $capability_id,
+                        'error'         => implode( '; ', $result->get_errors() ),
+                    ];
+                }
+                self::record_installed_instance( $capability_id, $existing_blueprint_id );
+                return [
+                    'success'       => true,
+                    'blueprint_id'  => $existing_blueprint_id,
+                    'compiled'      => true,
+                    'capability_id' => $capability_id,
+                    'note'          => 'Reactivated existing blueprint.',
+                    'warnings'      => $result->get_warnings(),
+                ];
+            }
+            // Fall through to a fresh template install if the known
+            // blueprint row itself is gone (shouldn't normally happen).
+        }
+        $template = self::find_template_data( $capability_id );
         if ( ! $template ) {
 …
+        }
+        self::record_installed_instance( $capability_id, $blueprint_id );
         return [
             'success'       => true,
 …
+    }
+    /**
+     * Update an already-installed capability to its manifest's current
+     * declared version, in place — same blueprint row, new blueprint_json,
+     * recompiled. Distinct from install(): requires the capability to
+     * already be installed, and requires a manifest (the target version
+     * always comes from the manifest's own 'version' field — there's no
+     * store of multiple historical template versions to pick from).
+     *
+     * @return array {
+     *   @type bool        $success
+     *   @type string      $status         'already_current' | 'updated' (only on success)
+     *   @type int|null    $blueprint_id
+     *   @type string|null $from_version
+     *   @type string|null $to_version
+     *   @type string      $error          (only on failure)
+     * }
+     */
+    public static function update( string $capability_id ): array {
+        $installed = class_exists( 'CLAUTRON_Capability_Store' )
+            ? CLAUTRON_Capability_Store::find_by_capability_id( $capability_id )
+            : null;
+        if ( ! $installed ) {
+            return [
+                'success' => false,
+                'error'   => "Capability '{$capability_id}' is not installed. Use clautron.catalog.install first.",
+                'code'    => 'not_installed',
+            ];
+        }
+        $manifest = class_exists( 'CLAUTRON_Manifest_Registry' ) ? CLAUTRON_Manifest_Registry::get( $capability_id ) : null;
+        if ( ! $manifest ) {
+            return [
+                'success' => false,
+                'error'   => "Capability '{$capability_id}' has no manifest, so it has no declared target version to update to.",
+                'code'    => 'no_manifest',
+            ];
+        }
+        $from_version = $installed->installed_version;
+        $to_version   = $manifest['version'];
+        if ( $from_version === $to_version ) {
+            return [
+                'success'      => true,
+                'status'       => 'already_current',
+                'blueprint_id' => (int) $installed->blueprint_id,
+                'from_version' => $from_version,
+                'to_version'   => $to_version,
+            ];
+        }
+        $template = self::find_template_data( $capability_id );
+        if ( ! $template ) {
+            return [
+                'success' => false,
+                'error'   => "No template found for capability_id '{$capability_id}'.",
+                'code'    => 'template_missing',
+            ];
+        }
+        $blueprint_id = (int) $installed->blueprint_id;
+        $blueprint_row = CLAUTRON_Blueprint_Store::get( $blueprint_id );
+        if ( ! $blueprint_row ) {
+            return [
+                'success' => false,
+                'error'   => "Installed blueprint (id {$blueprint_id}) no longer exists.",
+                'code'    => 'blueprint_missing',
+            ];
+        }
+        // In-place edit: keep the existing blueprint's own UUID — this
+        // updates the same blueprint row, it doesn't create a new one.
+        $template['id'] = $blueprint_row->uuid;
+        $validation_blueprint = new CLAUTRON_Blueprint( $template );
+        $validation           = CLAUTRON_Blueprint_Validator::validate( $validation_blueprint );
+        if ( ! $validation->is_valid() ) {
+            return [
+                'success' => false,
+                'error'   => 'Updated template failed validation: ' . implode( '; ', $validation->get_errors() ),
+                'code'    => 'validation_failed',
+            ];
+        }
+        $encoded = wp_json_encode( $template );
+        $saved   = CLAUTRON_Blueprint_Store::update_json( $blueprint_id, $encoded, "Updated to v{$to_version} via Capability Contract" );
+        if ( ! $saved ) {
+            return [
+                'success' => false,
+                'error'   => 'Failed to save updated blueprint to database.',
+                'code'    => 'save_failed',
+            ];
+        }
+        $result = CLAUTRON_Plugin::make_compiler()->compile( $blueprint_id );
+        if ( ! empty( $result->get_errors() ) ) {
+            return [
+                'success'      => false,
+                'blueprint_id' => $blueprint_id,
+                'from_version' => $from_version,
+                'to_version'   => $to_version,
+                'error'        => implode( '; ', $result->get_errors() ),
+                'code'         => 'compile_failed',
+            ];
+        }
+        self::record_installed_instance( $capability_id, $blueprint_id );
+        return [
+            'success'      => true,
+            'status'       => 'updated',
+            'blueprint_id' => $blueprint_id,
+            'from_version' => $from_version,
+            'to_version'   => $to_version,
+            'warnings'     => $result->get_warnings(),
+        ];
+    }
+    /**
+     * Deactivate an installed capability — stops its compile-phase
+     * primitives from being re-applied on the next request
+     * (CLAUTRON_Runtime_Engine::boot() only replays workflows with
+     * status='active'; CLAUTRON_Compiler::decompile() removes the
+     * workflow row and pauses the blueprint). Never touches data: no
+     * postmeta, terms, or custom table rows written while the capability
+     * was active are read or modified. Always allowed, regardless of
+     * reversibility.strategy — that field describes what a future
+     * `rollback` action would (not) be able to undo, it does not gate
+     * deactivate.
+     *
+     * @return array {
+     *   @type bool     $success
+     *   @type string   $status           'deactivated' (only on success)
+     *   @type int|null $blueprint_id
+     *   @type bool     $data_preserved   Always true on success.
+     *   @type string[] $residual_effects Human-readable notes derived from the manifest's 'effects', if any.
+     *   @type string   $error            (only on failure)
+     * }
+     */
+    public static function deactivate( string $capability_id ): array {
+        $installed = class_exists( 'CLAUTRON_Capability_Store' )
+            ? CLAUTRON_Capability_Store::find_by_capability_id( $capability_id )
+            : null;
+        if ( ! $installed || $installed->status !== 'active' ) {
+            return [
+                'success' => false,
+                'error'   => "Capability '{$capability_id}' is not currently active.",
+                'code'    => 'not_active',
+            ];
+        }
+        $blueprint_id = (int) $installed->blueprint_id;
+        CLAUTRON_Plugin::make_compiler()->decompile( $blueprint_id );
+        // Covers decompile()'s one confirmed gap: it doesn't flush rewrite
+        // rules, so a register_cpt/register_taxonomy with a custom slug
+        // can leave stale permalinks until the next flush. Cheap enough
+        // for a rare, explicit operation.
+        flush_rewrite_rules( false );
+        CLAUTRON_Capability_Store::update_status( $capability_id, 'paused' );
+        $manifest          = class_exists( 'CLAUTRON_Manifest_Registry' ) ? CLAUTRON_Manifest_Registry::get( $capability_id ) : null;
+        $residual_effects  = self::describe_residual_effects( $manifest['effects'] ?? [] );
+        return [
+            'success'          => true,
+            'status'           => 'deactivated',
+            'blueprint_id'     => $blueprint_id,
+            'data_preserved'   => true,
+            'residual_effects' => $residual_effects,
+        ];
+    }
+    /**
+     * Translate a manifest's declared 'effects' into human-readable notes
+     * about what deactivate does NOT undo — derived from data already
+     * declared on the manifest, no new metadata needed.
+     */
+    private static function describe_residual_effects( array $effects ): array {
+        $notes = [];
+        if ( ! empty( $effects['writes_database'] ) ) {
+            $notes[] = 'Data written while active (e.g. post meta) is preserved and not reverted.';
+        }
+        if ( ! empty( $effects['changes_schema'] ) ) {
+            $notes[] = 'Any schema changes made while active (e.g. new fields/columns) are preserved.';
+        }
+        if ( ! empty( $effects['writes_files'] ) ) {
+            $notes[] = 'Files written while active are preserved on disk.';
+        }
+        return $notes;
+    }
+    /**
+     * Locate a demo template's decoded JSON by capability_id, or null.
+     */
+    private static function find_template_data( string $capability_id ): ?array {
+        $demo_dir = CLAUTRON_DIR . 'demo/';
+        foreach ( glob( $demo_dir . '*.json' ) ?: [] as $path ) {
+            $data = json_decode( file_get_contents( $path ), true );
+            if ( is_array( $data ) && ( $data['capability_id'] ?? '' ) === $capability_id ) {
+                return $data;
+            }
+        }
+        return null;
+    }
+    /**
+     * Upsert the installed-instance row (wp_clautron_capabilities) after a
+     * successful install/compile — separate from the generic blueprint row,
+     * see CLAUTRON_Capability_Store.
+     */
+    private static function record_installed_instance( string $capability_id, int $blueprint_id ): void {
+        if ( ! class_exists( 'CLAUTRON_Capability_Store' ) ) {
+            return;
+        }
+        $manifest = class_exists( 'CLAUTRON_Manifest_Registry' ) ? CLAUTRON_Manifest_Registry::get( $capability_id ) : null;
+        CLAUTRON_Capability_Store::upsert( [
+            'capability_id'     => $capability_id,
+            'blueprint_id'      => $blueprint_id,
+            'installed_version' => $manifest['version'] ?? 'unknown',
+            'status'            => 'active',
+            'reversibility'     => $manifest['reversibility']['strategy'] ?? 'none',
+        ] );
+    }
     // ── Idempotent provisioning ───────────────────────────────────────────────
     /**
+     * Ensure a capability exists and is active. Idempotent — safe to call repeatedly.
+     * What ensure() would do for a capability_id, without doing it. ensure()
+     * itself follows this, so a dry run can never disagree with the real call.
+     *
      * Resolution order:
+     *  1. Already active with this capability_id → return it unchanged.
+     *  2. Available as a demo template → install it.
+     *  3. blueprint_json provided → create + compile (capability_id is forced into the JSON).
+     *  1. already_active   — active with this capability_id: nothing to do.
+     *  2. reactivate       — known but deactivated, blueprint still there:
+     *                        install() recompiles the SAME blueprint. Without
+     *                        this a custom (non-template) capability would get
+     *                        a second blueprint every time it was ensured
+     *                        after a deactivate.
+     *  3. install_template — a demo template: install it.
+     *  4. create           — create + compile the caller's blueprint_json.
+     *
+     * @return array{action: string, blueprint_id: ?int}
+     */
+    public static function ensure_plan( string $capability_id ): array {
+        $cap = self::find_active( $capability_id );
+        if ( $cap ) {
+            return [ 'action' => 'already_active', 'blueprint_id' => (int) $cap['blueprint_id'] ];
+        }
+        $known = CLAUTRON_Capability_Store::find_by_capability_id( $capability_id );
+        if ( $known && CLAUTRON_Blueprint_Store::get( (int) $known->blueprint_id ) ) {
+            return [ 'action' => 'reactivate', 'blueprint_id' => (int) $known->blueprint_id ];
+        }
+        if ( in_array( $capability_id, array_column( self::get_templates(), 'capability_id' ), true ) ) {
+            return [ 'action' => 'install_template', 'blueprint_id' => null ];
+        }
+        return [ 'action' => 'create', 'blueprint_id' => null ];
+    }
+    /**
+     * Ensure a capability exists and is active. Idempotent — safe to call
+     * repeatedly. Resolution order: see ensure_plan().
+     *
      * @param string $capability_id  Unique slug identifying this capability.
 …
      * @return array {
      *   @type bool   $success
      *   @type string $status        'already_active' | 'installed_from_template' | 'created_and_compiled'
+     *   @type string $status        'already_active' | 'reactivated' | 'installed_from_template' | 'created_and_compiled'
      *   @type string $capability_id
      *   @type int    $blueprint_id
 …
      */
     public static function ensure( string $capability_id, string $blueprint_json = '' ): array {
         // ── 1. Already active ─────────────────────────────────────────────────
+        $cap = self::find_active( $capability_id );
         if ( $cap ) {
+        $plan = self::ensure_plan( $capability_id );
+        if ( 'already_active' === $plan['action'] ) {
             return [
                 'success'       => true,
                 'status'        => 'already_active',
                 'capability_id' => $capability_id,
+                'blueprint_id'  => $cap['blueprint_id'],
+            ];
+        }
+        // ── 2. Available as template ──────────────────────────────────────────
+        $templates = self::get_templates();
+        foreach ( $templates as $tpl ) {
+            if ( $tpl['capability_id'] === $capability_id ) {
+                $result           = self::install( $capability_id );
+                $result['status'] = $result['success'] ? 'installed_from_template' : ( $result['status'] ?? 'error' );
+                return $result;
+            }
+        }
+        // ── 3. Create from provided blueprint_json ────────────────────────────
+                'blueprint_id'  => $plan['blueprint_id'],
+            ];
+        }
+        if ( 'reactivate' === $plan['action'] || 'install_template' === $plan['action'] ) {
+            $result           = self::install( $capability_id );
+            $result['status'] = $result['success']
+                ? ( 'reactivate' === $plan['action'] ? 'reactivated' : 'installed_from_template' )
+                : ( $result['status'] ?? 'error' );
+            return $result;
+        }
+        // ── create: from the provided blueprint_json ──────────────────────────
         if ( ! $blueprint_json ) {
             return [
 …
+        }
+        self::record_installed_instance( $capability_id, $blueprint_id );
         return [
             'success'       => true,
 …
+    }
+    // ── Inspect ───────────────────────────────────────────────────────────────
+    /**
+     * Contract-level actions that always work for any capability_id,
+     * manifest or not — they're generic lookups, never gated by what a
+     * specific manifest opts into declaring.
+     */
+    private const ALWAYS_AVAILABLE_ACTIONS = [ 'discover', 'inspect' ];
+    /**
+     * Per-capability lifecycle actions the Capability Contract currently
+     * has a real, working executor for. A manifest may *declare* more
+     * (e.g. "update", "verify", "remove") than the contract can actually
+     * run yet — available_actions only ever advertises the intersection,
+     * so a caller never gets pointed at an action that would just fail.
+     */
+    private const IMPLEMENTED_LIFECYCLE_ACTIONS = [ 'install', 'update', 'deactivate' ];
+    /**
+     * Resolve current install/version/compatibility state for a capability_id.
+     *
+     * @return array {
+     *   @type bool        $installed
+     *   @type string|null $installed_version
+     *   @type string|null $available_version   From the manifest, if one exists.
+     *   @type bool        $compatible           True if no unmet requirements (or no manifest to check).
+     *   @type string      $status               not_installed|active|paused|removed
+     *   @type string[]    $available_actions    ALWAYS_AVAILABLE_ACTIONS + (manifest actions ∩ IMPLEMENTED_LIFECYCLE_ACTIONS).
+     *   @type string[]    $unmet_requirements
+     * }
+     */
+    public static function inspect( string $capability_id ): array {
+        $manifest = class_exists( 'CLAUTRON_Manifest_Registry' ) ? CLAUTRON_Manifest_Registry::get( $capability_id ) : null;
+        $installed_row = class_exists( 'CLAUTRON_Capability_Store' )
+            ? CLAUTRON_Capability_Store::find_by_capability_id( $capability_id )
+            : null;
+        $unmet = ( $manifest && class_exists( 'CLAUTRON_Manifest_Registry' ) )
+            ? CLAUTRON_Manifest_Registry::check_requirements( $manifest )
+            : [];
+        $declared_actions  = $manifest['actions'] ?? [];
+        $available_actions = array_values( array_unique( array_merge(
+            self::ALWAYS_AVAILABLE_ACTIONS,
+            array_intersect( $declared_actions, self::IMPLEMENTED_LIFECYCLE_ACTIONS )
+        ) ) );
+        return [
+            'installed'          => $installed_row !== null,
+            'installed_version'  => $installed_row->installed_version ?? null,
+            'available_version'  => $manifest['version'] ?? null,
+            'compatible'         => empty( $unmet ),
+            'status'             => $installed_row->status ?? 'not_installed',
+            'available_actions'  => $available_actions,
+            'unmet_requirements' => $unmet,
+        ];
+    }
     // ── Helpers ───────────────────────────────────────────────────────────────

clautron/tags/1.5.0/includes/class-db.php

-              r3582869
+              r3784837
  *   3 — add last_error column to jobs table
  *   4 — add clautron_events time-series table
+ *   5 — add clautron_capabilities table (installed-instance state, separate
+ *       from the source/template manifest — see docs/schemas/capability_manifest.json)
  */
 class CLAUTRON_DB {
 …
         ) $charset;" );
+        // ── capabilities ──────────────────────────────────────────────────────
+        // Installed-instance state for a capability, separate from the
+        // source/template manifest (demo/capabilities/*.manifest.json) and
+        // from the generic blueprints table, which serves every blueprint
+        // whether or not it's a governed capability. One row per capability_id
+        // currently installed on this site.
+        dbDelta( "CREATE TABLE {$pfx}capabilities (
+            id                 BIGINT UNSIGNED  NOT NULL AUTO_INCREMENT,
+            capability_id      VARCHAR(191)     NOT NULL,
+            blueprint_id       BIGINT UNSIGNED  NOT NULL,
+            installed_version  VARCHAR(20)      NOT NULL DEFAULT 'unknown',
+            status             VARCHAR(20)      NOT NULL DEFAULT 'active',
+            reversibility      VARCHAR(10)      NOT NULL DEFAULT 'none',
+            installed_at       DATETIME         NOT NULL,
+            updated_at         DATETIME         NOT NULL,
+            PRIMARY KEY  (id),
+            UNIQUE KEY   capability_id (capability_id),
+            KEY          blueprint_id (blueprint_id)
+        ) $charset;" );
         // ── In-place migrations for existing installs ─────────────────────────
         // dbDelta reliably creates tables but does NOT add missing columns.
 …
+        }
+        // v5: backfill capabilities table for blueprints that were installed
+        // (compiled + active, with a capability_id) before this table existed.
+        // Preserves continuity — nothing about an already-installed capability
+        // changes on upgrade, it just becomes visible to the new inspect()/
+        // versioning machinery.
+        self::backfill_capabilities();
         update_option( 'clautron_db_version', CLAUTRON_DB_VERSION );
+    }
+    /**
+     * One-time backfill: for every active blueprint that already declares a
+     * capability_id but has no row yet in the capabilities table, insert one.
+     * Safe to call repeatedly — skips capability_ids that already have a row.
+     */
+    private static function backfill_capabilities(): void {
+        global $wpdb;
+        $existing_ids = $wpdb->get_col( $wpdb->prepare( 'SELECT capability_id FROM %i', self::capabilities() ) );
+        $rows = $wpdb->get_results( $wpdb->prepare(
+            'SELECT id, blueprint_json FROM %i WHERE status = %s',
+            self::blueprints(),
+            'active'
+        ) );
+        $now = current_time( 'mysql', true );
+        foreach ( $rows as $row ) {
+            $data = json_decode( $row->blueprint_json, true );
+            if ( ! is_array( $data ) || empty( $data['capability_id'] ) ) {
+                continue;
+            }
+            if ( in_array( $data['capability_id'], $existing_ids, true ) ) {
+                continue;
+            }
+            $manifest          = class_exists( 'CLAUTRON_Manifest_Registry' ) ? CLAUTRON_Manifest_Registry::get( $data['capability_id'] ) : null;
+            $installed_version = $manifest['version'] ?? 'unknown';
+            $reversibility     = $manifest['reversibility']['strategy'] ?? 'none';
+            $wpdb->insert(
+                self::capabilities(),
+                [
+                    'capability_id'     => $data['capability_id'],
+                    'blueprint_id'      => (int) $row->id,
+                    'installed_version' => $installed_version,
+                    'status'            => 'active',
+                    'reversibility'     => $reversibility,
+                    'installed_at'      => $now,
+                    'updated_at'        => $now,
+                ],
+                [ '%s', '%d', '%s', '%s', '%s', '%s', '%s' ]
+            );
+        }
+    }
 …
         global $wpdb;
         $pfx    = $wpdb->prefix . 'clautron_';
         $tables = [ 'events', 'jobs', 'ai_requests', 'conversations', 'execution_logs', 'workflows', 'versions', 'blueprints' ];
+        $tables = [ 'capabilities', 'events', 'jobs', 'ai_requests', 'conversations', 'execution_logs', 'workflows', 'versions', 'blueprints' ];
         foreach ( $tables as $t ) {
             $wpdb->query( $wpdb->prepare( 'DROP TABLE IF EXISTS %i', $pfx . $t ) );
 …
     public static function jobs(): string          { global $wpdb; return $wpdb->prefix . 'clautron_jobs'; }
     public static function events(): string        { global $wpdb; return $wpdb->prefix . 'clautron_events'; }
+    public static function capabilities(): string  { global $wpdb; return $wpdb->prefix . 'clautron_capabilities'; }
+}

clautron/tags/1.5.0/includes/class-plugin.php

-              r3691441
+              r3784837
         CLAUTRON_Primitive_Redirect::register_all();
         CLAUTRON_Primitive_Cookie::register_all();
+        CLAUTRON_Primitive_Consent::register_all();
         CLAUTRON_Primitive_Language::register_all();
         CLAUTRON_Primitive_Request::register_all();
 …
         // ── 3. Boot job runner ───────────────────────────────────────────────
         CLAUTRON_Job_Runner::boot();
+        // ── 3b. Expose operations as WordPress Abilities ─────────────────────
+        CLAUTRON_Abilities::boot();
         // ── 4b. Boot runtime engine ──────────────────────────────────────────

clautron/tags/1.5.0/includes/class-smoke-tester.php

-              r3582869
+              r3784837
  * Smoke Tester — verifies that a compiled blueprint is correctly wired into WordPress.
+ *
+ * Checks are lightweight WordPress-introspection only (no HTTP requests).
+ * Each check inspects the WordPress state that the compile-phase primitives
+ * should have set up: post types, taxonomies, meta boxes, columns, hooks, etc.
+ * Generic executor: each compile-phase structure node is checked by its own
+ * primitive's declared `verify` callable (CLAUTRON_Primitive_Registry). A
+ * primitive type with no `verify` declared lands in `unavailable`, not
+ * silently dropped — see the primitive's own file for its check, and
+ * CLAUTRON_Primitive_Registry::register()'s docblock for the `verify`
+ * contract. Part of the AICOM-Clautron Capability Contract v1.
  */
 class CLAUTRON_Smoke_Tester {
 …
      *   @type string[] $failed
      *   @type string[] $warnings
+     *   @type string[] $unavailable  Structures whose primitive type has no declared verify check.
      *   @type string   $summary
      * }
 …
         $row = CLAUTRON_Blueprint_Store::get( $blueprint_id );
         if ( ! $row ) {
             return self::result( [], [], [ "Blueprint {$blueprint_id} not found." ], 0, 0 );
+            return self::result( [], [], [ "Blueprint {$blueprint_id} not found." ], [] );
+        }
         $data = json_decode( $row->blueprint_json, true );
         if ( ! is_array( $data ) ) {
             return self::result( [], [], [ 'blueprint_json is not valid JSON.' ], 0, 0 );
+            return self::result( [], [], [ 'blueprint_json is not valid JSON.' ], [] );
+        }
         if ( $row->status !== 'active' ) {
             return self::result( [], [], [ "Blueprint is '{$row->status}', not active — compile it first." ], 0, 0 );
+            return self::result( [], [], [ "Blueprint is '{$row->status}', not active — compile it first." ], [] );
+        }
+        $passed   = [];
+        $failed   = [];
+        $warnings = [];
+        $passed      = [];
+        $failed      = [];
+        $warnings    = [];
+        $unavailable = [];
         // ── Check trigger ──────────────────────────────────────────────────────
+        // Not a primitive — the blueprint's own trigger field, checked directly.
         $trigger = $data['trigger'] ?? null;
         if ( $trigger ) {
 …
             $id     = $node['id'] ?? $type;
             switch ( $type ) {
+            $def = class_exists( 'CLAUTRON_Primitive_Registry' ) ? CLAUTRON_Primitive_Registry::get( $type ) : null;
+                case 'register_cpt': {
+                    $pt = $config['post_type'] ?? '';
+                    if ( $pt && get_post_type_object( $pt ) ) {
+                        $passed[] = "register_cpt:{$pt}";
+                    } elseif ( $pt ) {
+                        $failed[] = "register_cpt:{$pt} — post type not registered.";
+                    }
+                    break;
+                }
+            if ( ! $def ) {
+                $unavailable[] = "{$type}:{$id} — primitive type not registered.";
+                continue;
+            }
+                case 'register_taxonomy': {
+                    $tax = $config['taxonomy'] ?? '';
+                    if ( $tax && taxonomy_exists( $tax ) ) {
+                        $passed[] = "register_taxonomy:{$tax}";
+                    } elseif ( $tax ) {
+                        $failed[] = "register_taxonomy:{$tax} — taxonomy not registered.";
+                    }
+                    break;
+                }
+            if ( empty( $def['verify'] ) || ! is_callable( $def['verify'] ) ) {
+                $unavailable[] = "{$type}:{$id} — no verification declared for this primitive type.";
+                continue;
+            }
+                case 'register_meta': {
+                    $key = $config['meta_key'] ?? '';
+                    $pts = (array) ( $config['post_types'] ?? [ 'post' ] );
+                    if ( $key ) {
+                        $registered = registered_meta_key_exists( 'post', $key, $pts[0] ?? '' );
+                        if ( $registered ) {
+                            $passed[] = "register_meta:{$key}";
+                        } else {
+                            $warnings[] = "register_meta:{$key} — not found in registered meta (may still work via update_post_meta).";
+                        }
+                    }
+                    break;
+                }
+            $items = call_user_func( $def['verify'], $config );
+            foreach ( (array) $items as $item ) {
+                $label  = $item['label']  ?? "{$type}:{$id}";
+                $reason = $item['reason'] ?? null;
+                $line   = $reason ? "{$label} — {$reason}" : $label;
+                case 'add_metabox': {
+                    $mbid = $config['id'] ?? '';
+                    $pts  = (array) ( $config['post_types'] ?? [ 'post' ] );
+                    $pt   = $pts[0] ?? 'post';
+                    // Meta boxes are only registered in admin context.
+                    if ( ! is_admin() ) {
+                        $warnings[] = "add_metabox:{$mbid} — skipped (requires admin context; will work correctly on post edit screens).";
+                switch ( $item['status'] ?? 'warning' ) {
+                    case 'passed':
+                        $passed[] = $line;
                         break;
+                    }
+                    $hook_name = 'add_meta_boxes_' . $pt;
+                    do_action( $hook_name, null );
+                    do_action( 'add_meta_boxes', $pt, null );
+                    global $wp_meta_boxes;
+                    $found = false;
+                    foreach ( $wp_meta_boxes[ $pt ] ?? [] as $context ) {
+                        foreach ( $context as $priority ) {
+                            if ( isset( $priority[ $mbid ] ) ) {
+                                $found = true;
+                                break 2;
+                            }
+                        }
+                    }
+                    if ( $found ) {
+                        $passed[] = "add_metabox:{$mbid}";
+                    } else {
+                        $failed[] = "add_metabox:{$mbid} — not found in wp_meta_boxes for post type '{$pt}'.";
+                    }
+                    break;
+                }
+                case 'add_admin_column': {
+                    $pts = (array) ( $config['post_types'] ?? [] );
+                    foreach ( $pts as $pt ) {
+                        $filter = "manage_{$pt}_posts_columns";
+                        if ( has_filter( $filter ) ) {
+                            $passed[] = "add_admin_column:{$pt}";
+                        } else {
+                            $failed[] = "add_admin_column:{$pt} — filter '{$filter}' not hooked.";
+                        }
+                    }
+                    break;
+                }
+                case 'inject_wp_head': {
+                    $priority = (int) ( $config['priority'] ?? 5 );
+                    if ( has_action( 'wp_head' ) ) {
+                        $passed[] = "inject_wp_head (priority:{$priority})";
+                    } else {
+                        $failed[] = 'inject_wp_head — no actions registered on wp_head.';
+                    }
+                    break;
+                }
+                case 'inject_wp_footer': {
+                    if ( has_action( 'wp_footer' ) ) {
+                        $passed[] = 'inject_wp_footer';
+                    } else {
+                        $failed[] = 'inject_wp_footer — no actions registered on wp_footer.';
+                    }
+                    break;
+                }
+                case 'register_rest_route': {
+                    $route = $config['route'] ?? '';
+                    if ( $route ) {
+                        $routes    = rest_get_server()->get_routes();
+                        $full_path = '/clautron/v1/' . ltrim( $route, '/' );
+                        if ( isset( $routes[ $full_path ] ) ) {
+                            $passed[] = "register_rest_route:{$route}";
+                        } else {
+                            $warnings[] = "register_rest_route:{$route} — not found in registered routes (REST server may not be initialized yet).";
+                        }
+                    }
+                    break;
+                }
+                case 'add_row_action': {
+                    $pts = (array) ( $config['post_types'] ?? [] );
+                    foreach ( $pts as $pt ) {
+                        $filter = "post_row_actions";
+                        if ( has_filter( $filter ) || has_filter( "{$pt}_row_actions" ) ) {
+                            $passed[] = "add_row_action:{$pt}";
+                        } else {
+                            $warnings[] = "add_row_action:{$pt} — row action filter not detected (may still work).";
+                        }
+                    }
+                    break;
+                }
+                case 'gate_publish': {
+                    if ( has_action( 'admin_notices' ) ) {
+                        $passed[] = 'gate_publish';
+                    } else {
+                        $warnings[] = 'gate_publish — admin_notices hook not detected in current context.';
+                    }
+                    break;
+                    case 'failed':
+                        $failed[] = $line;
+                        break;
+                    default:
+                        $warnings[] = $line;
+                        break;
+                }
+            }
+        }
+        $total = count( $passed ) + count( $failed );
+        return self::result( $passed, $failed, $warnings, count( $passed ), $total );
+        return self::result( $passed, $failed, $warnings, $unavailable );
+    }
 …
         array $failed,
         array $warnings,
+        int   $pass_count,
+        int   $total
+        array $unavailable
     ): array {
+        $pass_count = count( $passed );
+        $total      = $pass_count + count( $failed );
         if ( $total === 0 ) {
             $summary = 'No checkable structures found.';
+            $summary = empty( $unavailable ) ? 'No checkable structures found.' : 'No checks could run.';
         } elseif ( empty( $failed ) ) {
             $summary = "All checks passed ({$pass_count}/{$total}).";
 …
+        }
+        if ( ! empty( $unavailable ) ) {
+            $summary .= ' ' . count( $unavailable ) . ' structure(s) have no verification declared.';
+        }
         return [
+            'passed'   => $passed,
+            'failed'   => $failed,
+            'warnings' => $warnings,
+            'summary'  => $summary,
+            'passed'      => $passed,
+            'failed'      => $failed,
+            'warnings'    => $warnings,
+            'unavailable' => $unavailable,
+            'summary'     => $summary,
         ];
+    }

clautron/tags/1.5.0/includes/primitives/class-primitive-ai.php

r3691441	r3784837
27	27	'category' => 'ai',
28	28	'phase' => 'runtime',
	29	'effects' => [ 'external_requests' ],
29	30	'label' => 'AI Generate',
30	31	'description' => 'Generate text with the WordPress AI Client (site-configured provider) and store the result in a context variable. Use for excerpts, meta descriptions, alt text, translations, summaries. Prompt supports {{variable}} placeholders. Output is plain text only.',

clautron/tags/1.5.0/includes/primitives/class-primitive-comments.php

-              r3691441
+              r3784837
             'category'    => 'comments',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Query Comments',
             'description' => 'Query WordPress comments with filters. Returns array of comments (id, post_id, author, author_email, content, status, date, parent_id) stored in a context variable.',
 …
             'category'    => 'comments',
             'phase'       => 'runtime',
+            // approve: core emails the post author (wp_set_comment_status → wp_new_comment_notify_postauthor).
+            'effects'     => static fn( array $c ): array => [ 'trash' => [ 'writes_database', 'deletes_data' ], 'approve' => [ 'writes_database', 'external_requests' ] ][ $c['status'] ?? '' ] ?? [ 'writes_database' ],
+            'effects_max' => [ 'writes_database', 'deletes_data', 'external_requests' ],
             'label'       => 'Moderate Comment',
             'description' => 'Change a comment\'s moderation status. Allowed statuses: approve, hold, spam, trash. Hard deletion is intentionally not supported.',
 …
             'category'    => 'comments',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database' ],
             'label'       => 'Create Comment',
             'description' => 'Insert a comment (or a threaded reply via parent_id) on a post. Content supports {{variable}} placeholders.',

clautron/tags/1.5.0/includes/primitives/class-primitive-cookie.php

-              r3691441
+              r3784837
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
+            'reversible'  => false,
             'safe'        => false,
             'label'       => 'Write Cookie',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Read Cookie',
             'description' => 'Read a clautron_-prefixed cookie into a workflow variable. Resolves to null if the cookie is not set.',

clautron/tags/1.5.0/includes/primitives/class-primitive-data.php

-              r3582869
+              r3784837
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Read Post Field',
             'description' => 'Read a field from the current post (ID, title, content, status, author, etc.) and store it in a variable.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database' ],
             'label'       => 'Write Meta',
             'description' => 'Write a meta value to a post, user, or term.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Read Meta',
             'description' => 'Read a meta value from a post, user, or term and store it in a variable.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database' ],
             'safe'        => false,
             'label'       => 'Write Option',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Read Option',
             'description' => 'Read a WordPress option and store it in a variable.',
 …
             'category'    => 'wordpress',
             'phase'       => 'compile',
+            'effects'     => [ 'writes_database' ],
             'label'       => 'Gate Publish',
             'description' => 'Block or warn when publishing a post that fails completeness checks.',
 …
                     echo '</p></div>';
                 } );
+            },
+            'verify' => static function ( array $config ): array {
+                if ( has_action( 'admin_notices' ) ) {
+                    return [ [ 'status' => 'passed', 'label' => 'gate_publish' ] ];
+                }
+                return [ [ 'status' => 'warning', 'label' => 'gate_publish', 'reason' => 'admin_notices hook not detected in current context.' ] ];
             },
         ] );
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database' ],
             'label'       => 'Check Fields Completeness',
             'description' => 'Evaluate a list of post fields and calculate a completeness score (0-100). Saves the score to a meta key and an output variable.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Run Report',
             'description' => 'Execute a saved report blueprint and store its result rows in a context variable. Use with foreach_query_result to process each row.',

clautron/tags/1.5.0/includes/primitives/class-primitive-elementor.php

-              r3592659
+              r3784837
             'category'    => 'elementor',
             'phase'       => 'compile',
+            'effects'     => [ 'executes_code' ],
             'label'       => 'Elementor Widget',
             'description' => 'Create a custom Elementor widget with content controls, style tab sections, and a server-rendered HTML template. Appears under the "Clautron" category in the Elementor panel.',
 …
             'category'    => 'wordpress',
             'phase'       => 'compile',
+            'effects'     => [ 'executes_code' ],
             'label'       => 'WordPress Widget',
             'description' => 'Register a native WordPress sidebar widget (WP_Widget) usable in Appearance > Widgets and any theme sidebar. Supports text, textarea, number, url, color, checkbox, and select controls. Use {{key}} (escaped), {{{key}}} (HTML), {{key.url}} (URL), and {{#if key}}...{{/if}} in the template.',

clautron/tags/1.5.0/includes/primitives/class-primitive-email.php

-              r3691441
+              r3784837
             'category'    => 'communication',
             'phase'       => 'runtime',
+            'effects'     => [ 'external_requests' ],
             'label'       => 'Send Email',
             'description' => 'Send an email via wp_mail(). All fields support {{variable}} template syntax.',
 …
             'category'    => 'communication',
             'phase'       => 'runtime',
+            'effects'     => [ 'external_requests' ],
             'label'       => 'Notify User',
             'description' => 'Send a notification email to a WordPress user by their user ID. Subject and body support {{variable}} template syntax.',
 …
             'category'    => 'communication',
             'phase'       => 'compile',
+            'effects'     => [ 'external_requests' ],
             'safe'        => false,
             'label'       => 'Configure SMTP',

clautron/tags/1.5.0/includes/primitives/class-primitive-events.php

-              r3691441
+              r3784837
             'category'    => 'events',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database' ],
             'label'       => 'Track Event',
             'description' => 'Write one event to the clautron_events time-series store. Use this inside any blueprint trigger to record that something happened (a pageview, a login failure, an order, a cron run, etc.).',
 …
             'category'    => 'events',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Query Events',
             'description' => 'Read raw event rows from the clautron_events store. Results are stored in output_variable for use in subsequent primitives (foreach_query_result, send_email, etc.).',
 …
             'category'    => 'events',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Aggregate Events',
             'description' => 'Group and aggregate event data: total counts, sums, averages, grouped by time period or object. Returns an array of {period, value} rows in output_variable.',
 …
             'category'    => 'events',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database', 'deletes_data' ],
             'label'       => 'Purge Events',
             'description' => 'Delete old events for retention management. Use inside a recurring job (e.g. weekly). Returns the count of deleted rows in output_variable.',
 …
             'category'    => 'events',
             'phase'       => 'compile',
+            'effects'     => [ 'writes_database' ],
             'safe'        => false,
             'label'       => 'Log All Outgoing Email',
 …
             'category'    => 'events',
             'phase'       => 'compile',
+            'effects'     => [ 'writes_database' ],
             'safe'        => false,
             'label'       => 'Log Site Activity',

clautron/tags/1.5.0/includes/primitives/class-primitive-filter.php

r3691441	r3784837
33	33	'category' => 'frontend',
34	34	'phase' => 'compile',
	35	'effects' => [],
35	36	'label' => 'Filter Query by Request Parameters',
36	37	'description' => 'Restrict frontend main queries (archives, search, home) using one or more filter rules read from GET parameters: taxonomy facets, exact meta match, or numeric meta range. Built for shop/archive filter sidebars (category, in-stock, price range). Never touches wp-admin or REST requests.',

clautron/tags/1.5.0/includes/primitives/class-primitive-frontend.php

-              r3691441
+              r3784837
             'category'    => 'frontend',
             'phase'       => 'compile',
+            'effects'     => [ 'executes_code' ],
             'label'       => 'Inject into <head>',
             'description' => 'Output HTML into wp_head on singular post/page views. Supports {{post.field}}, {{site.field}}, and {{_meta_key}} placeholders. Optionally outputs a Schema.org JSON-LD block via json_ld config.',
 …
                 }, $priority );
             },
+            'verify' => static function ( array $config ): array {
+                $priority = (int) ( $config['priority'] ?? 5 );
+                if ( has_action( 'wp_head' ) ) {
+                    return [ [ 'status' => 'passed', 'label' => "inject_wp_head (priority:{$priority})" ] ];
+                }
+                return [ [ 'status' => 'failed', 'label' => 'inject_wp_head', 'reason' => 'no actions registered on wp_head.' ] ];
+            },
         ] );
+    }
 …
             'category'    => 'frontend',
             'phase'       => 'compile',
+            'effects'     => [ 'executes_code' ],
             'label'       => 'Inject before </body>',
             'description' => 'Output HTML into wp_footer. Same {{variable}} resolution as inject_wp_head (post.*, site.*, meta keys). Leave post_types empty to render on every frontend page (banners, popups, share widgets) — set it to restrict to singular views of those post types, where {{post.*}}/meta-key tokens resolve against the viewed post. Set suppress_if_cookie to hide the whole block once a clautron_-prefixed cookie (e.g. one set by write_cookie) has any non-empty value — the standard pattern for "don\'t show this again after accept/dismiss".',
 …
                 }, $priority );
             },
+            'verify' => static function ( array $config ): array {
+                if ( has_action( 'wp_footer' ) ) {
+                    return [ [ 'status' => 'passed', 'label' => 'inject_wp_footer' ] ];
+                }
+                return [ [ 'status' => 'failed', 'label' => 'inject_wp_footer', 'reason' => 'no actions registered on wp_footer.' ] ];
+            },
         ] );
+    }
 …
             'category'    => 'frontend',
             'phase'       => 'compile',
+            'effects'     => [ 'executes_code' ],
             'label'       => 'Register Shortcode',
             'description' => 'Register a WordPress [shortcode] rendered from an HTML template. Attributes become template tokens: {{attr}} escaped text, {{{attr}}} sanitized HTML, {{attr.url}} URL, {{#if attr}}...{{/if}} conditionals. Enclosed content is available as {{{content}}}.',
 …
             'category'    => 'frontend',
             'phase'       => 'compile',
+            'effects'     => [],
             'label'       => 'Enqueue Registered Asset',
             'description' => 'Load CSS/JS assets that are ALREADY registered on the site (by core, the theme, or plugins) onto frontend pages, by handle. Never loads external URLs or new code — only activates assets the site already ships (e.g. dashicons, wp-block-library, swiper, theme handles). Use widget/shortcode templates with the classes those assets provide.',

clautron/tags/1.5.0/includes/primitives/class-primitive-http.php

-              r3582869
+              r3784837
             'category'    => 'http',
             'phase'       => 'runtime',
+            'effects'     => [ 'external_requests' ],
+            'safe'        => false,
             'label'       => 'HTTP Request',
             'description' => 'Send an HTTP request (GET, POST, PUT, DELETE, PATCH) and store the response body and status code in context variables.',
 …
             'category'    => 'http',
             'phase'       => 'runtime',
+            'effects'     => [ 'external_requests', 'writes_database' ], // SimplePie caches the feed in transients
+            'safe'        => false,
             'label'       => 'Fetch RSS/Atom Feed',
             'description' => 'Fetch an RSS or Atom feed and store items as an array of {title, link, description, pubdate} objects.',
-            'safe'        => true,
             'schema'      => [
                 'url'             => [ 'type' => 'string',  'required' => true, 'description' => 'Feed URL. Supports {{variable}}.' ],
 …
             'category'    => 'http',
             'phase'       => 'runtime',
+            'effects'     => [ 'external_requests' ],
             'label'       => 'Send Webhook',
             'description' => 'POST a JSON payload to a webhook URL. Supports {{variable}} in URL and payload values.',

clautron/tags/1.5.0/includes/primitives/class-primitive-language.php

r3691441	r3784837
29	29	'category' => 'frontend',
30	30	'phase' => 'compile',
	31	'effects' => [],
31	32	'label' => 'Filter Query by Language',
32	33	'description' => 'Restrict frontend main queries (archives, search, home, singular) to posts tagged with one term of a language taxonomy. Language is resolved from a URL query var, falling back to a cookie, falling back to a configured default. Never touches wp-admin or REST requests.',

clautron/tags/1.5.0/includes/primitives/class-primitive-logic.php

-              r3582869
+              r3784837
             'category'    => 'logic',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'If / Else',
             'description' => 'Evaluate a condition. Execute pass_branch nodes if true, fail_branch nodes if false.',
 …
             'category'    => 'logic',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Stop Execution',
             'description' => 'Halt workflow execution immediately. No further nodes will run.',
 …
             'category'    => 'logic',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Set Variable',
             'description' => 'Assign a literal or resolved value to a context variable for use in later nodes.',
 …
             'category'    => 'logic',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'For Each Row',
             'description' => 'Iterate over rows from a query result stored in a context variable. Each row\'s columns become available as {{row.column_name}} for the body nodes.',
 …
             'category'    => 'logic',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Switch / Case',
             'description' => 'Evaluate a value against multiple cases and execute the matching branch. Falls through to default_branch if no case matches.',

clautron/tags/1.5.0/includes/primitives/class-primitive-media.php

-              r3691441
+              r3784837
             'category'    => 'media',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database', 'writes_files', 'external_requests' ],
             'label'       => 'Create Media from URL',
             'description' => 'Download an image from a URL and add it to the WordPress media library. Returns the new attachment ID.',
 …
             'category'    => 'media',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database' ],
             'label'       => 'Set Featured Image',
             'description' => 'Set the featured image (thumbnail) of a post to a given attachment ID.',
 …
             'category'    => 'media',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Get Image URL',
             'description' => 'Get the URL of an attachment image at a given size.',
 …
             'category'    => 'media',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database', 'writes_files' ],
             'safe'        => false,
             'label'       => 'Handle File Upload',
 …
             'handler' => static function ( array $config, CLAUTRON_Workflow_Context $ctx ): int|false {
                 $out_var = $config['output_variable'] ?? 'uploaded_attachment_id';
                 $fail    = static function () use ( $ctx, $out_var ): false {
+                $fail    = static function () use ( $ctx, $out_var ): bool {
                     if ( $out_var ) {
                         $ctx->write_variable( $out_var, false );

clautron/tags/1.5.0/includes/primitives/class-primitive-query.php

-              r3691441
+              r3784837
             'category'    => 'query',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Query Posts',
             'description' => 'Query WordPress posts with flexible filters. Returns array of post objects (id, title, content, excerpt, status, type, author, date, permalink) stored in a context variable.',
 …
             'category'    => 'query',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Get Post',
             'description' => 'Fetch a single post by ID and store its fields in a context variable.',
 …
             'category'    => 'query',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Count Posts',
             'description' => 'Count posts matching given criteria. Writes integer to output_variable.',
 …
             'category'    => 'query',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Query Users',
             'description' => 'Query WordPress users with flexible filters. Returns array of user objects.',
 …
             'category'    => 'query',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Get User',
             'description' => 'Fetch a single user by ID and store their data in a context variable.',
 …
             'category'    => 'query',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Query Terms',
             'description' => 'Query taxonomy terms. Returns array of term objects.',

clautron/tags/1.5.0/includes/primitives/class-primitive-redirect.php

-              r3691441
+              r3784837
             'category'    => 'frontend',
             'phase'       => 'compile',
+            'effects'     => [],
+            // Browsers cache permanent redirects indefinitely; removing the rule doesn't reach them.
+            'reversible'  => static fn( array $c ): bool => ! in_array( (int) ( $c['status'] ?? 301 ), [ 301, 308 ], true ),
             'label'       => 'Redirect URL',
             'description' => 'Redirect requests from one path to another. Refuses redirects that would break wp-admin/login/REST access or create a loop.',

clautron/tags/1.5.0/includes/primitives/class-primitive-request.php

r3691441	r3784837
25	25	'category' => 'data',
26	26	'phase' => 'runtime',
	27	'effects' => [],
27	28	'safe' => false,
28	29	'label' => 'Read Request Parameter',

clautron/tags/1.5.0/includes/primitives/class-primitive-security.php

-              r3691441
+              r3784837
 /**
  * Security Primitives — abuse throttling.
+ * Security Primitives — abuse throttling and information-disclosure hardening.
+ *
  * Registered primitives:
+ *   - rate_limit_check   Fixed-window counter (transient-backed) keyed by an
+ *                         identifier (defaults to client IP). Use as a
+ *                         condition to gate login/comment/form actions.
+ *   - rate_limit_check          Fixed-window counter (transient-backed) keyed by an
+ *                                identifier (defaults to client IP). Use as a
+ *                                condition to gate login/comment/form actions.
+ *   - harden_user_enumeration   Stop anonymous visitors from discovering usernames
+ *                                (REST users endpoint, author archives, oEmbed
+ *                                author, login error messages).
+ *   - security_headers          Send Referrer-Policy, X-Content-Type-Options,
+ *                                X-Frame-Options and Permissions-Policy on
+ *                                frontend responses, and HSTS on HTTPS (opt-in).
+ *   - hide_wp_version           Remove generator tags, mask the WordPress
+ *                                version in core asset URLs and, opt-in,
+ *                                delete readme.html.
+ *
+ * The hardening primitives hook named static methods rather than closures
+ * wherever the callback needs no config: add_filter() with the same callable
+ * and priority is idempotent, so two blueprints declaring the same primitive
+ * do not stack duplicate callbacks, and verify can check the exact callable
+ * with has_filter() instead of "something is hooked here".
  */
 class CLAUTRON_Primitive_Security extends CLAUTRON_Abstract_Primitive {
+    /** Login error codes that reveal whether a username/email exists. */
+    private const LOGIN_ENUMERATION_CODES = [ 'invalid_username', 'invalid_email', 'incorrect_password' ];
+    private const REFERRER_POLICIES = [
+        'no-referrer', 'no-referrer-when-downgrade', 'origin', 'origin-when-cross-origin',
+        'same-origin', 'strict-origin', 'strict-origin-when-cross-origin', 'unsafe-url',
+    ];
+    private const FRAME_OPTIONS = [ 'SAMEORIGIN', 'DENY' ];
+    private const PERMISSIONS_POLICY = 'camera=(), microphone=()';
+    /** WordPress version readme.html was last removed for (see remove_core_readme()). */
+    private const README_OPTION = 'clautron_readme_removed_for';
+    /** Headers merged from every active security_headers structure; the first one to set a header wins. */
+    private static array $security_headers = [];
     public static function register_all(): void {
         self::register_rate_limit_check();
+        self::register_harden_user_enumeration();
+        self::register_security_headers();
+        self::register_hide_wp_version();
+    }
 …
             'category'    => 'security',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database' ],
             'safe'        => false,
             'label'       => 'Rate Limit Check',
 …
         return false;
+    }
+    // ── harden_user_enumeration ──────────────────────────────────────────────
+    private static function register_harden_user_enumeration(): void {
+        CLAUTRON_Primitive_Registry::register( 'harden_user_enumeration', [
+            'category'    => 'security',
+            'phase'       => 'compile',
+            'effects'     => [],
+            'safe'        => false,
+            'label'       => 'Harden User Enumeration',
+            'description' => 'Stop anonymous visitors from discovering usernames. Blocks the /wp/v2/users REST endpoints for logged-out requests (logged-in users, including the block editor author picker, keep working); returns 404 for every author archive (?author=N, ?author_name=, /author/slug/ and their feeds), drops the users sitemap and points author links at the homepage; replaces the post author in oEmbed responses with the site name; and gives the same login error for an unknown username and a wrong password. Each part can be switched off individually.',
+            'schema'      => [
+                'block_rest_users'        => [ 'type' => 'boolean', 'default' => true, 'description' => '401 on every /wp/v2/users route for logged-out requests.' ],
+                'disable_author_archives' => [ 'type' => 'boolean', 'default' => true, 'description' => '404 on all author archives for everyone, remove the users sitemap, point author links to the homepage.' ],
+                'strip_oembed_author'     => [ 'type' => 'boolean', 'default' => true, 'description' => 'oEmbed responses show the site name and homepage instead of the post author.' ],
+                'generic_login_errors'    => [ 'type' => 'boolean', 'default' => true, 'description' => 'Same login error whether the username/email is unknown or the password is wrong.' ],
+            ],
+            'examples'    => [
+                [],
+                [ 'disable_author_archives' => false ],
+            ],
+            'handler' => static function ( array $config ): void {
+                if ( $config['block_rest_users'] ?? true ) {
+                    add_filter( 'rest_request_before_callbacks', [ self::class, 'gate_rest_users' ], 10, 3 );
+                }
+                if ( $config['disable_author_archives'] ?? true ) {
+                    add_filter( 'request', [ self::class, 'block_author_request' ] );
+                    add_filter( 'wp_sitemaps_add_provider', [ self::class, 'drop_users_sitemap' ], 10, 2 );
+                    add_filter( 'author_link', [ self::class, 'neutral_author_link' ] );
+                }
+                if ( $config['strip_oembed_author'] ?? true ) {
+                    add_filter( 'oembed_response_data', [ self::class, 'neutral_oembed_author' ] );
+                }
+                if ( $config['generic_login_errors'] ?? true ) {
+                    // After every core authenticator (20) and the spam check (99).
+                    add_filter( 'authenticate', [ self::class, 'generic_login_error' ], 100 );
+                }
+            },
+            'verify' => static function ( array $config ): array {
+                $items  = [];
+                $checks = [
+                    'block_rest_users'        => [ 'rest_request_before_callbacks', 'gate_rest_users' ],
+                    'disable_author_archives' => [ 'request', 'block_author_request' ],
+                    'strip_oembed_author'     => [ 'oembed_response_data', 'neutral_oembed_author' ],
+                    'generic_login_errors'    => [ 'authenticate', 'generic_login_error' ],
+                ];
+                foreach ( $checks as $option => [ $hook, $method ] ) {
+                    if ( ! ( $config[ $option ] ?? true ) ) {
+                        continue;
+                    }
+                    $items[] = false !== has_filter( $hook, [ self::class, $method ] )
+                        ? [ 'status' => 'passed', 'label' => "harden_user_enumeration:{$option}" ]
+                        : [ 'status' => 'failed', 'label' => "harden_user_enumeration:{$option}", 'reason' => "not hooked on {$hook}." ];
+                }
+                if ( $config['block_rest_users'] ?? true ) {
+                    $status  = self::anonymous_rest_status( '/wp/v2/users' );
+                    $items[] = in_array( $status, [ 401, 403 ], true )
+                        ? [ 'status' => 'passed', 'label' => "anonymous GET /wp/v2/users → {$status}" ]
+                        : [ 'status' => 'failed', 'label' => 'anonymous GET /wp/v2/users', 'reason' => "expected 401, got {$status}." ];
+                }
+                if ( $config['disable_author_archives'] ?? true ) {
+                    $vars    = self::author_query_vars( [ 'author' => '1' ], false );
+                    $items[] = ( $vars['error'] ?? '' ) === '404'
+                        ? [ 'status' => 'passed', 'label' => '?author=1 resolves to 404' ]
+                        : [ 'status' => 'failed', 'label' => '?author=1', 'reason' => 'author query was not turned into a 404.' ];
+                }
+                return $items;
+            },
+        ] );
+    }
+    /**
+     * rest_request_before_callbacks: refuse every route served by the core
+     * users controller to logged-out requests.
+     *
+     * Keyed on the controller that matched, not on the URL: WordPress matches
+     * routes case-insensitively (/wp/v2/USERS works) and also accepts
+     * ?rest_route=, so a path check would have to replicate the router to be
+     * airtight. Whatever spelling reached the users controller is caught here.
+     */
+    public static function gate_rest_users( mixed $response, array $handler, WP_REST_Request $request ): mixed {
+        $callback = $handler['callback'] ?? null;
+        if ( ! is_array( $callback ) || ! ( $callback[0] ?? null ) instanceof WP_REST_Users_Controller ) {
+            return $response;
+        }
+        if ( is_user_logged_in() ) {
+            return $response;
+        }
+        return new WP_Error(
+            'rest_forbidden',
+            __( 'Sorry, you are not allowed to do that.', 'clautron' ),
+            [ 'status' => rest_authorization_required_code() ]
+        );
+    }
+    /** request filter: wiring for author_query_vars(). */
+    public static function block_author_request( array $query_vars ): array {
+        return self::author_query_vars( $query_vars, is_admin() );
+    }
+    /**
+     * Replace any author-archive query with a plain 404. Public for unit
+     * testing (see CLAUTRON_Primitive_WordPress::build_cpt_args()).
+     *
+     * Runs on `request`, before WP_Query exists, so every way of asking for an
+     * author archive is covered by one check: ?author=N, ?author_name=slug,
+     * /author/slug/ (rewrite sets author_name) and their /feed/ variants.
+     * Blocking only the canonical redirect is not enough: an author without
+     * published posts gets no redirect, but the archive still prints the slug
+     * in <title> and body_class.
+     *
+     * Left alone:
+     *   - wp-admin, because edit.php?author=N calls wp() and goes through this
+     *     same filter to filter the posts list;
+     *   - REST requests, because /wp-json/wp/v2/posts?author=N is a legitimate
+     *     filter and `author` is a public query var.
+     */
+    public static function author_query_vars( array $query_vars, bool $in_admin ): array {
+        if ( $in_admin || isset( $query_vars['rest_route'] ) ) {
+            return $query_vars;
+        }
+        if ( empty( $query_vars['author'] ) && empty( $query_vars['author_name'] ) ) {
+            return $query_vars;
+        }
+        // Same shape WP::parse_request() produces for an unmatched URL, so
+        // WP::send_headers() sends the 404 status and nocache headers itself.
+        return [ 'error' => '404' ];
+    }
+    /** wp_sitemaps_add_provider: the users sitemap only lists author archive URLs. */
+    public static function drop_users_sitemap( mixed $provider, string $name ): mixed {
+        return 'users' === $name ? false : $provider;
+    }
+    /** author_link: author archives are gone, and the link itself carries the slug. */
+    public static function neutral_author_link(): string {
+        return home_url( '/' );
+    }
+    /**
+     * oembed_response_data: use the values core itself falls back to when a
+     * post has no author, instead of display_name + author archive URL.
+     */
+    public static function neutral_oembed_author( array $data ): array {
+        if ( isset( $data['author_name'] ) || isset( $data['author_url'] ) ) {
+            $data['author_name'] = get_bloginfo( 'name' );
+            $data['author_url']  = get_home_url();
+        }
+        return $data;
+    }
+    /**
+     * authenticate: collapse "unknown username", "unknown email" and "wrong
+     * password" into one error.
+     *
+     * Reuses core's own 'invalidcombo' code: it is already in wp-login.php's
+     * shake list, and it keeps wp-login.php from pre-filling the username
+     * field only on a wrong password, which would otherwise leak the same
+     * information through the form instead of the message.
+     */
+    public static function generic_login_error( mixed $user ): mixed {
+        if ( ! is_wp_error( $user ) || ! array_intersect( $user->get_error_codes(), self::LOGIN_ENUMERATION_CODES ) ) {
+            return $user;
+        }
+        return new WP_Error(
+            'invalidcombo',
+            __( '<strong>Error:</strong> The username, email address or password is incorrect.', 'clautron' )
+        );
+    }
+    /** Dispatch a GET as a logged-out visitor and return the HTTP status. */
+    private static function anonymous_rest_status( string $route ): int {
+        $previous_user = get_current_user_id();
+        wp_set_current_user( 0 );
+        try {
+            return rest_do_request( new WP_REST_Request( 'GET', $route ) )->get_status();
+        } finally {
+            wp_set_current_user( $previous_user );
+        }
+    }
+    // ── security_headers ─────────────────────────────────────────────────────
+    private static function register_security_headers(): void {
+        CLAUTRON_Primitive_Registry::register( 'security_headers', [
+            'category'    => 'security',
+            'phase'       => 'compile',
+            'effects'     => [],
+            // Browsers keep honouring HSTS for max-age after the header stops.
+            'reversible'  => static fn( array $c ): bool => (int) ( $c['hsts_max_age'] ?? 0 ) <= 0,
+            'safe'        => false,
+            'label'       => 'Security Headers',
+            'description' => 'Send Referrer-Policy, X-Content-Type-Options, X-Frame-Options and Permissions-Policy on frontend responses, plus Strict-Transport-Security (HSTS) on HTTPS when opted in. A header already set by another plugin through wp_headers is left as is. Headers are sent from PHP, so pages served straight from a page cache or CDN without running WordPress will not carry them; verify loads the homepage to detect that.',
+            'schema'      => [
+                'referrer_policy'         => [ 'type' => 'string',  'default' => 'strict-origin-when-cross-origin', 'description' => 'Any standard Referrer-Policy value. Empty = do not send. strict-origin-when-cross-origin matches what WordPress core sends in wp-admin; no-referrer breaks YouTube embeds and referral analytics.' ],
+                'content_type_options'    => [ 'type' => 'boolean', 'default' => true, 'description' => 'Send X-Content-Type-Options: nosniff.' ],
+                'frame_options'           => [ 'type' => 'string',  'default' => 'SAMEORIGIN', 'description' => 'SAMEORIGIN, DENY, or empty to not send. SAMEORIGIN keeps the Customizer and page-builder previews working.' ],
+                'permissions_policy'      => [ 'type' => 'string',  'default' => self::PERMISSIONS_POLICY, 'description' => 'Permissions-Policy value, e.g. "camera=(), microphone=(), geolocation=(self)". Empty = do not send; an invalid value is not sent. The default turns off camera and microphone only: blocking geolocation would break store/branch locators, and payment would break Apple Pay / Google Pay buttons.' ],
+                'hsts_max_age'            => [ 'type' => 'integer', 'default' => 0, 'description' => 'Opt-in Strict-Transport-Security max-age in seconds (31536000 = one year). 0 = do not send. Only sent over HTTPS. Browsers then refuse plain HTTP for that long and deactivating does not undo it, so turn it on only when the whole site works over HTTPS.' ],
+                'hsts_include_subdomains' => [ 'type' => 'boolean', 'default' => false, 'description' => 'Add includeSubDomains to HSTS. Only when every subdomain serves HTTPS.' ],
+            ],
+            'examples'    => [
+                [],
+                [ 'permissions_policy' => 'camera=(), microphone=(), geolocation=(self)', 'hsts_max_age' => 31536000 ],
+            ],
+            'handler' => static function ( array $config ): void {
+                $headers = self::build_security_headers( $config );
+                if ( ! $headers ) {
+                    return;
+                }
+                self::$security_headers = self::merge_headers( self::$security_headers, $headers );
+                add_filter( 'wp_headers', [ self::class, 'send_security_headers' ] );
+            },
+            'verify' => static function ( array $config ): array {
+                $expected = self::build_security_headers( $config );
+                if ( ! $expected ) {
+                    return [];
+                }
+                if ( false === has_filter( 'wp_headers', [ self::class, 'send_security_headers' ] ) ) {
+                    return [ [ 'status' => 'failed', 'label' => 'security_headers', 'reason' => 'not hooked on wp_headers.' ] ];
+                }
+                $items = [];
+                foreach ( $expected as $name => $value ) {
+                    if ( ( self::$security_headers[ $name ] ?? null ) !== $value ) {
+                        $items[] = [ 'status' => 'warning', 'label' => "security_headers:{$name}", 'reason' => 'another security_headers capability already sets it to "' . ( self::$security_headers[ $name ] ?? '' ) . '"; the first one wins.' ];
+                    }
+                }
+                $https = 'https' === wp_parse_url( home_url(), PHP_URL_SCHEME );
+                if ( isset( $expected['Strict-Transport-Security'] ) && ! $https ) {
+                    $items[] = [ 'status' => 'warning', 'label' => 'security_headers:Strict-Transport-Security', 'reason' => 'HSTS is only sent over HTTPS and this site\'s address is http://.' ];
+                    unset( $expected['Strict-Transport-Security'] );
+                }
+                $response = wp_remote_get( home_url( '/' ), [ 'timeout' => 5, 'redirection' => 3 ] );
+                if ( is_wp_error( $response ) ) {
+                    $items[] = [ 'status' => 'warning', 'label' => 'security_headers:live', 'reason' => 'could not load the homepage to confirm the headers reach visitors: ' . $response->get_error_message() ];
+                    return $items;
+                }
+                foreach ( $expected as $name => $value ) {
+                    $items[] = '' !== wp_remote_retrieve_header( $response, $name )
+                        ? [ 'status' => 'passed', 'label' => "{$name} on homepage" ]
+                        : [ 'status' => 'warning', 'label' => "{$name} on homepage", 'reason' => 'set by WordPress but missing from the live response; a page cache, CDN or proxy is serving the page without PHP or stripping the header. Set it at that layer too.' ];
+                }
+                return $items;
+            },
+        ] );
+    }
+    /**
+     * wp_headers: everything active security_headers structures asked for.
+     * One named callback (not a closure per structure) so verify can check
+     * that this primitive, not just any plugin, is hooked.
+     */
+    public static function send_security_headers( array $headers ): array {
+        $ours = self::$security_headers;
+        if ( ! is_ssl() ) {
+            unset( $ours['Strict-Transport-Security'] );
+        }
+        return self::merge_headers( $headers, $ours );
+    }
+    /**
+     * Header name → value from a security_headers config. Invalid values are
+     * dropped rather than sent, since a malformed Referrer-Policy or
+     * X-Frame-Options is ignored by browsers anyway. Public for unit testing.
+     */
+    public static function build_security_headers( array $config ): array {
+        $headers = [];
+        $referrer = strtolower( trim( (string) ( $config['referrer_policy'] ?? 'strict-origin-when-cross-origin' ) ) );
+        if ( in_array( $referrer, self::REFERRER_POLICIES, true ) ) {
+            $headers['Referrer-Policy'] = $referrer;
+        }
+        if ( $config['content_type_options'] ?? true ) {
+            $headers['X-Content-Type-Options'] = 'nosniff';
+        }
+        $frame = strtoupper( trim( (string) ( $config['frame_options'] ?? 'SAMEORIGIN' ) ) );
+        if ( in_array( $frame, self::FRAME_OPTIONS, true ) ) {
+            $headers['X-Frame-Options'] = $frame;
+        }
+        $permissions = trim( (string) ( $config['permissions_policy'] ?? self::PERMISSIONS_POLICY ) );
+        $directive   = '[a-z0-9-]+=(?:\*|\((?:[ \t]*(?:self|src|\*|"https?:\/\/[^"\s]+"))*[ \t]*\))';
+        if ( preg_match( '/^' . $directive . '(?:[ \t]*,[ \t]*' . $directive . ')*$/D', $permissions ) ) {
+            $headers['Permissions-Policy'] = $permissions;
+        }
+        $max_age = min( 63072000, (int) ( $config['hsts_max_age'] ?? 0 ) );
+        if ( $max_age > 0 ) {
+            $headers['Strict-Transport-Security'] = "max-age={$max_age}" . ( empty( $config['hsts_include_subdomains'] ) ? '' : '; includeSubDomains' );
+        }
+        return $headers;
+    }
+    /**
+     * Add $ours to $existing without overriding a header someone else already
+     * set (case-insensitive, like HTTP header names). Overriding could weaken
+     * a stricter choice, e.g. a security plugin's X-Frame-Options: DENY.
+     */
+    public static function merge_headers( array $existing, array $ours ): array {
+        $taken = array_change_key_case( $existing, CASE_LOWER );
+        foreach ( $ours as $name => $value ) {
+            if ( ! isset( $taken[ strtolower( $name ) ] ) ) {
+                $existing[ $name ] = $value;
+            }
+        }
+        return $existing;
+    }
+    // ── hide_wp_version ──────────────────────────────────────────────────────
+    private static function register_hide_wp_version(): void {
+        CLAUTRON_Primitive_Registry::register( 'hide_wp_version', [
+            'category'    => 'security',
+            'phase'       => 'compile',
+            'effects'     => static fn( array $c ): array => empty( $c['remove_readme'] ) ? [] : [ 'writes_files', 'writes_database' ],
+            'effects_max' => [ 'writes_files', 'writes_database' ],
+            'safe'        => false,
+            'label'       => 'Hide WordPress Version',
+            'description' => 'Stop advertising the WordPress version. Removes the generator meta tag and the feed <generator> element (which also drops WooCommerce\'s generator line), turns off Elementor\'s generator tag without changing its saved setting, and replaces ?ver=<WordPress version> on asset URLs with a site-specific hash that still changes on every update, so browser caches are still refreshed. readme.html in the site root also states the version, but the web server serves it without WordPress, so nothing above hides it: set remove_readme to delete it (opt-in, a file deletion that deactivating does not undo).',
+            'schema'      => [
+                'remove_generator'    => [ 'type' => 'boolean', 'default' => true, 'description' => 'Remove generator tags (WordPress, WooCommerce, Elementor) from pages and feeds.' ],
+                'mask_asset_versions' => [ 'type' => 'boolean', 'default' => true, 'description' => 'Replace ?ver=<WordPress version> on script/style URLs with a hash of it.' ],
+                'remove_readme'       => [ 'type' => 'boolean', 'default' => false, 'description' => 'Delete readme.html from the site root, and again after every WordPress update (which restores it). Works on any web server. Deactivating does not bring the file back; the next WordPress update does.' ],
+            ],
+            'examples'    => [
+                [],
+                [ 'remove_readme' => true ],
+            ],
+            'handler' => static function ( array $config ): void {
+                if ( ! empty( $config['remove_readme'] ) ) {
+                    add_action( 'init', [ self::class, 'maybe_remove_core_readme' ] );
+                }
+                if ( $config['remove_generator'] ?? true ) {
+                    add_filter( 'the_generator', '__return_empty_string' );
+                    // Elementor prints its own tag on wp_head unless this option is '1'.
+                    // pre_option_ overrides it for as long as the feature is active and
+                    // leaves the stored value untouched when it is deactivated.
+                    add_filter( 'pre_option_elementor_meta_generator_tag', [ self::class, 'elementor_generator_off' ] );
+                }
+                if ( $config['mask_asset_versions'] ?? true ) {
+                    add_filter( 'script_loader_src', [ self::class, 'mask_core_version' ] );
+                    add_filter( 'style_loader_src', [ self::class, 'mask_core_version' ] );
+                }
+            },
+            'verify' => static function ( array $config ): array {
+                $items = [];
+                if ( $config['remove_generator'] ?? true ) {
+                    $items[] = false !== has_filter( 'the_generator', '__return_empty_string' )
+                        ? [ 'status' => 'passed', 'label' => 'hide_wp_version:remove_generator' ]
+                        : [ 'status' => 'failed', 'label' => 'hide_wp_version:remove_generator', 'reason' => 'not hooked on the_generator.' ];
+                }
+                if ( $config['mask_asset_versions'] ?? true ) {
+                    $version = get_bloginfo( 'version' );
+                    $masked  = self::mask_core_version( includes_url( 'js/jquery/jquery.min.js?ver=' . $version ) );
+                    $items[] = false !== has_filter( 'script_loader_src', [ self::class, 'mask_core_version' ] ) && ! str_contains( $masked, $version )
+                        ? [ 'status' => 'passed', 'label' => 'hide_wp_version:mask_asset_versions' ]
+                        : [ 'status' => 'failed', 'label' => 'hide_wp_version:mask_asset_versions', 'reason' => 'asset URLs still carry the WordPress version.' ];
+                }
+                if ( ! empty( $config['remove_readme'] ) ) {
+                    $items[] = ! file_exists( ABSPATH . 'readme.html' )
+                        ? [ 'status' => 'passed', 'label' => 'hide_wp_version:remove_readme' ]
+                        : [ 'status' => 'failed', 'label' => 'hide_wp_version:remove_readme', 'reason' => 'readme.html is still in the site root; WordPress could not delete it (file permissions). Delete it by hand or deny it at the web server.' ];
+                }
+                return $items;
+            },
+        ] );
+    }
+    /** init: wiring for remove_core_readme(). */
+    public static function maybe_remove_core_readme(): void {
+        self::remove_core_readme( ABSPATH . 'readme.html', (string) get_bloginfo( 'version' ) );
+    }
+    /**
+     * Delete $path once per WordPress version. Every core update (one-click,
+     * WP-CLI or files copied by hand) puts readme.html back and changes the
+     * version, so keying on the version catches all of them for the price of
+     * one autoloaded option read per request, not a file stat. A failed
+     * delete is not recorded, so it is retried. Public for unit testing.
+     */
+    public static function remove_core_readme( string $path, string $version ): bool {
+        if ( get_option( self::README_OPTION ) === $version ) {
+            return false;
+        }
+        if ( file_exists( $path ) ) {
+            wp_delete_file( $path );
+        }
+        if ( file_exists( $path ) ) {
+            return false;
+        }
+        update_option( self::README_OPTION, $version, true );
+        return true;
+    }
+    /** pre_option_elementor_meta_generator_tag: '1' is Elementor's "disabled". */
+    public static function elementor_generator_off(): string {
+        return '1';
+    }
+    /**
+     * script_loader_src / style_loader_src: swap ver=<WordPress version> for a
+     * salted hash of it. Assets enqueued without an explicit version get the
+     * WordPress version by default, so they are masked too. Other versions
+     * (a plugin's own) are left alone. Public for unit testing.
+     */
+    public static function mask_core_version( mixed $src ): mixed {
+        if ( ! is_string( $src ) || '' === $src ) {
+            return $src;
+        }
+        $version = get_bloginfo( 'version' );
+        parse_str( (string) wp_parse_url( $src, PHP_URL_QUERY ), $query );
+        if ( ( $query['ver'] ?? null ) !== $version ) {
+            return $src;
+        }
+        return add_query_arg( 'ver', substr( wp_hash( $version ), 0, 8 ), $src );
+    }
+}

clautron/tags/1.5.0/includes/primitives/class-primitive-sitemap.php

r3691441	r3784837
30	30	'category' => 'frontend',
31	31	'phase' => 'compile',
	32	'effects' => [],
32	33	'safe' => false,
33	34	'label' => 'Register XML Sitemap',

clautron/tags/1.5.0/includes/primitives/class-primitive-taxonomy.php

-              r3582869
+              r3784837
             'category'    => 'taxonomy',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database' ],
             'label'       => 'Set Post Terms',
             'description' => 'Assign taxonomy terms to a post. Accepts term IDs, slugs, or names.',
 …
             'category'    => 'taxonomy',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Get Post Terms',
             'description' => 'Get all terms assigned to a post for a given taxonomy.',
 …
             'category'    => 'taxonomy',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database' ],
             'label'       => 'Create Term',
             'description' => 'Create a new taxonomy term if it does not already exist. Returns the term ID.',
 …
             'category'    => 'taxonomy',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Term Exists',
             'description' => 'Check if a term exists in a taxonomy. Writes term ID (int) or 0 if not found.',

clautron/tags/1.5.0/includes/primitives/class-primitive-transform.php

-              r3582869
+              r3784837
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Parse JSON',
             'description' => 'Decode a JSON string into an associative array and store it in a context variable.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'To JSON',
             'description' => 'Encode a context variable as a JSON string and store it in another variable.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Map Fields',
             'description' => 'Remap an array of objects to a new shape. Each output key\'s value is a source field name or a {{expr}} template evaluated per item.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Filter Array',
             'description' => 'Filter an array of objects by a field condition. Supported operators: eq, neq, gt, gte, lt, lte, contains, not_contains, empty, not_empty.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Array Pluck',
             'description' => 'Extract a single field from each item in an array, producing a flat array of values.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Array Merge',
             'description' => 'Merge multiple array variables into one combined array.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Array Unique',
             'description' => 'Remove duplicate values from a flat array and reindex.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Array Sort',
             'description' => 'Sort an array. If field is set, sort an array of objects by that field. Otherwise sort a flat array.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Array Slice',
             'description' => 'Return a portion of an array starting at offset for a given length.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Count Array',
             'description' => 'Count the number of items in an array variable and store the integer.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'String Format',
             'description' => 'Render a template string with {{variable}} placeholders and store the result.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'String Truncate',
             'description' => 'Truncate a string to a maximum character length, appending a suffix when truncated.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'String Replace',
             'description' => 'Find and replace a substring within a string.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'String Split',
             'description' => 'Split a string by a delimiter into an array. Empty elements are removed.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'String Join',
             'description' => 'Join an array of strings into a single string using a glue separator.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Date Format',
             'description' => 'Format a date string or timestamp using a PHP date format string.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Date Diff',
             'description' => 'Calculate the absolute difference between two dates in the requested unit.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Date Add',
             'description' => 'Add a specified amount of time to a date and format the result.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Slugify',
             'description' => 'Convert a string to a URL-friendly slug using WordPress sanitize_title().',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Math Calculate',
             'description' => 'Perform a numeric math operation between two values.',

clautron/tags/1.5.0/includes/primitives/class-primitive-ui.php

-              r3691441
+              r3784837
             'category'    => 'ui',
             'phase'       => 'compile',
+            'effects'     => [ 'writes_database' ],
             'label'       => 'Add Metabox',
             'description' => 'Add a custom metabox panel to the post edit screen for one or more post types.',
 …
+                }
             },
+            'verify' => static function ( array $config ): array {
+                $box_id = sanitize_key( $config['id'] ?? '' );
+                if ( ! $box_id ) {
+                    return [];
+                }
+                // Handler registers with the 'clautron-' prefix (see above) —
+                // the check must look for the same id it was actually
+                // registered under.
+                $mbid = 'clautron-' . $box_id;
+                $pts  = (array) ( $config['post_types'] ?? [ 'post' ] );
+                $pt   = $pts[0] ?? 'post';
+                if ( ! is_admin() ) {
+                    return [ [ 'status' => 'warning', 'label' => "add_metabox:{$mbid}", 'reason' => 'skipped (requires admin context; will work correctly on post edit screens).' ] ];
+                }
+                $hook_name = 'add_meta_boxes_' . $pt;
+                do_action( $hook_name, null );
+                do_action( 'add_meta_boxes', $pt, null );
+                global $wp_meta_boxes;
+                $found = false;
+                foreach ( $wp_meta_boxes[ $pt ] ?? [] as $context_boxes ) {
+                    foreach ( $context_boxes as $priority_boxes ) {
+                        if ( isset( $priority_boxes[ $mbid ] ) ) {
+                            $found = true;
+                            break 2;
+                        }
+                    }
+                }
+                if ( $found ) {
+                    return [ [ 'status' => 'passed', 'label' => "add_metabox:{$mbid}" ] ];
+                }
+                return [ [ 'status' => 'failed', 'label' => "add_metabox:{$mbid}", 'reason' => "not found in wp_meta_boxes for post type '{$pt}'." ] ];
+            },
         ] );
+    }
 …
             'category'    => 'ui',
             'phase'       => 'compile',
+            'effects'     => [],
             'label'       => 'Add Admin Column',
             'description' => 'Add a custom column to the WordPress admin list table for a post type.',
 …
+                }
             },
+            'verify' => static function ( array $config ): array {
+                $pts   = (array) ( $config['post_types'] ?? [] );
+                $items = [];
+                foreach ( $pts as $pt ) {
+                    $filter = "manage_{$pt}_posts_columns";
+                    if ( has_filter( $filter ) ) {
+                        $items[] = [ 'status' => 'passed', 'label' => "add_admin_column:{$pt}" ];
+                    } else {
+                        $items[] = [ 'status' => 'failed', 'label' => "add_admin_column:{$pt}", 'reason' => "filter '{$filter}' not hooked." ];
+                    }
+                }
+                return $items;
+            },
         ] );
+    }
 …
             'category'    => 'ui',
             'phase'       => 'compile',
+            'effects'     => [],
             'label'       => 'Add Admin Filter',
             'description' => 'Add a custom dropdown filter to the WordPress admin post list table.',
 …
             'category'    => 'ui',
             'phase'       => 'runtime',
+            'effects'     => [ 'executes_code' ],
+            'safe'        => false,
             'label'       => 'Add Admin Notice',
             'description' => 'Display an admin notice (info, success, warning, error).',
 …
             'category'    => 'ui',
             'phase'       => 'compile',
+            'effects'     => [ 'writes_database' ],
             'label'       => 'Add Bulk Action',
             'description' => 'Add a custom bulk action to a post type list table.',
 …
             'category'    => 'ui',
             'phase'       => 'compile',
+            'effects'     => [],
             'label'       => 'Add Report Page',
             'description' => 'Add a stats/report section to the Clautron Reports admin page. Renders metric cards with post counts based on configurable queries.',
 …
             'category'    => 'ui',
             'phase'       => 'compile',
+            'effects'     => [ 'writes_database' ],
             'label'       => 'Add Row Action',
             'description' => 'Add a custom action link to post row actions in the list table (e.g. Clone).',
 …
                 } );
             },
+            'verify' => static function ( array $config ): array {
+                $pts   = (array) ( $config['post_types'] ?? [] );
+                $items = [];
+                foreach ( $pts as $pt ) {
+                    if ( has_filter( 'post_row_actions' ) || has_filter( "{$pt}_row_actions" ) ) {
+                        $items[] = [ 'status' => 'passed', 'label' => "add_row_action:{$pt}" ];
+                    } else {
+                        $items[] = [ 'status' => 'warning', 'label' => "add_row_action:{$pt}", 'reason' => 'row action filter not detected (may still work).' ];
+                    }
+                }
+                return $items;
+            },
         ] );
+    }
 …
             'category'    => 'ui',
             'phase'       => 'compile',
+            'effects'     => [ 'writes_database' ],
             'label'       => 'Add Options Page',
             'description' => 'Add a site-wide settings page under wp-admin (not tied to any single post). Uses the same field types as add_metabox\'s fields template: text, textarea, checkbox, select, radio, image, repeater. Each field is saved as its own option: clautron_opt_{menu_slug}_{field_key}.',

clautron/tags/1.5.0/includes/primitives/class-primitive-user.php

-              r3582869
+              r3784837
             'category'    => 'user',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Read User Meta',
             'description' => 'Read a user meta field and store the value in a context variable.',
 …
             'category'    => 'user',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database' ],
             'label'       => 'Write User Meta',
             'description' => 'Write or update a user meta value. All fields support {{variable}} syntax.',
 …
             'category'    => 'user',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database' ],
             'label'       => 'Update User Role',
             'description' => 'Change a user\'s WordPress role. Allowed roles: subscriber, contributor, author, editor. Cannot promote to administrator.',
 …
             'category'    => 'user',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database', 'deletes_data' ],
             'label'       => 'Delete User (Safe)',
             'description' => 'Delete a WordPress user. By default, skipped if the user has any published posts or approved comments. Set force=true to override.',
 …
             'category'    => 'user',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Get Current User',
             'description' => 'Store the currently logged-in user\'s data (id, login, email, display_name, roles) in a context variable.',
 …
             'category'    => 'user',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Check User Capability',
             'description' => 'Check if a user has a specific capability. Writes true/false to output_variable.',
 …
             'category'    => 'user',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Check User Role',
             'description' => 'Check if a user has a specific role. Writes true/false to output_variable.',

clautron/tags/1.5.0/includes/primitives/class-primitive-webhook.php

r3691441	r3784837
38	38	'category' => 'http',
39	39	'phase' => 'compile',
	40	'effects' => [ 'writes_database', 'changes_schema' ],
40	41	'safe' => false,
41	42	'label' => 'Register Payment Webhook',

clautron/tags/1.5.0/includes/primitives/class-primitive-woocommerce.php

-              r3691441
+              r3784837
             'category'    => 'woocommerce',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Query Orders',
             'description' => 'Query WooCommerce orders with filters. Returns array of orders (id, status, total, currency, customer_id, customer_email, date_created, items_count) stored in a context variable.',
 …
             'category'    => 'woocommerce',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Query Products',
             'description' => 'Query WooCommerce products with filters. Returns array of products (id, name, sku, price, regular_price, stock_status, stock_quantity, type, status) stored in a context variable.',
 …
             'category'    => 'woocommerce',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database', 'external_requests' ],
             'label'       => 'Update Order Status',
             'description' => 'Move a WooCommerce order to another standard status (pending, processing, on-hold, completed, cancelled, refunded, failed). Adds an order note attributing the change to the Clautron workflow. Trashing/deleting orders is intentionally not supported.',

clautron/tags/1.5.0/includes/primitives/class-primitive-wordpress.php

-              r3691441
+              r3784837
             'category'    => 'wordpress',
             'phase'       => 'compile',
+            // A custom capability_type grants its caps to administrator, which
+            // WordPress stores in wp_user_roles: that outlives deactivation.
+            'effects'     => static fn( array $c ): array => in_array( trim( explode( ',', (string) ( $c['capability_type'] ?? 'post' ) )[0] ), [ 'post', 'page' ], true ) ? [ 'changes_schema' ] : [ 'changes_schema', 'writes_database' ],
+            'effects_max' => [ 'changes_schema', 'writes_database' ],
             'label'       => 'Register Custom Post Type',
             'description' => 'Register a new custom post type in WordPress.',
 …
                 } );
             },
+            'verify' => static function ( array $config ): array {
+                $pt = $config['post_type'] ?? '';
+                if ( ! $pt ) {
+                    return [];
+                }
+                if ( get_post_type_object( $pt ) ) {
+                    return [ [ 'status' => 'passed', 'label' => "register_cpt:{$pt}" ] ];
+                }
+                return [ [ 'status' => 'failed', 'label' => "register_cpt:{$pt}", 'reason' => 'post type not registered.' ] ];
+            },
         ] );
+    }
 …
      * type they just asked for. Grant the mapped capabilities to
      * administrator; add_cap() is idempotent, safe to call every request.
+     *
+     * Only primitive capabilities. edit_post, read_post and delete_post are
+     * meta capabilities that map_meta_cap() resolves per post; a role must
+     * never hold them literally. WP_Role::has_cap() can't see them either,
+     * so granting them would rewrite wp_user_roles on every request, even
+     * for capability_type "post".
      */
     public static function grant_cpt_capabilities_to_admin( \WP_Post_Type $post_type_obj ): void {
 …
             return;
+        }
+        foreach ( (array) $post_type_obj->cap as $cap ) {
+        $primitive = array_diff_key( (array) $post_type_obj->cap, array_flip( [ 'edit_post', 'read_post', 'delete_post' ] ) );
+        foreach ( $primitive as $cap ) {
             if ( is_string( $cap ) && ! $role->has_cap( $cap ) ) {
                 $role->add_cap( $cap );
+            }
+        }
+    }
+    /**
+     * Effects of giving a post $status: trash removes it from the site, and
+     * publishing makes WordPress ping (update services, pingbacks,
+     * enclosures). An empty status leaves it unchanged. A value with a
+     * {{placeholder}} is only known at run time (and sanitize_key() turns
+     * "{{trash}}" into "trash"), so it gets the worst case. Core re-pinging
+     * when an already published post is saved again is not counted.
+     */
+    public static function post_status_effects( string $status ): array {
+        if ( str_contains( $status, '{{' ) ) {
+            return [ 'writes_database', 'deletes_data', 'external_requests' ];
+        }
+        return [
+            'trash'   => [ 'writes_database', 'deletes_data' ],
+            'publish' => [ 'writes_database', 'external_requests' ],
+        ][ sanitize_key( $status ) ] ?? [ 'writes_database' ];
+    }
 …
             'category'    => 'wordpress',
             'phase'       => 'compile',
+            'effects'     => [ 'changes_schema' ],
             'label'       => 'Register Taxonomy',
             'description' => 'Register a custom taxonomy for one or more post types.',
 …
                     register_taxonomy( $taxonomy, $post_types, self::build_taxonomy_args( $config, $label, $taxonomy ) );
                 } );
+            },
+            'verify' => static function ( array $config ): array {
+                $tax = $config['taxonomy'] ?? '';
+                if ( ! $tax ) {
+                    return [];
+                }
+                if ( taxonomy_exists( $tax ) ) {
+                    return [ [ 'status' => 'passed', 'label' => "register_taxonomy:{$tax}" ] ];
+                }
+                return [ [ 'status' => 'failed', 'label' => "register_taxonomy:{$tax}", 'reason' => 'taxonomy not registered.' ] ];
             },
         ] );
 …
             'category'    => 'wordpress',
             'phase'       => 'compile',
+            'effects'     => [ 'changes_schema' ],
             'label'       => 'Register Meta Field',
             'description' => 'Register a meta field for posts, users, or terms with type and schema.',
 …
                 } );
             },
+            'verify' => static function ( array $config ): array {
+                $key = $config['meta_key'] ?? '';
+                if ( ! $key ) {
+                    return [];
+                }
+                $pts        = (array) ( $config['post_types'] ?? [ 'post' ] );
+                $registered = registered_meta_key_exists( 'post', $key, $pts[0] ?? '' );
+                if ( $registered ) {
+                    return [ [ 'status' => 'passed', 'label' => "register_meta:{$key}" ] ];
+                }
+                return [ [ 'status' => 'warning', 'label' => "register_meta:{$key}", 'reason' => 'not found in registered meta (may still work via update_post_meta).' ] ];
+            },
         ] );
+    }
 …
             'category'    => 'wordpress',
             'phase'       => 'compile',
+            'effects'     => [ 'changes_schema' ],
             'safe'        => false,
             'label'       => 'Register REST Route',
 …
                 } );
             },
+            'verify' => static function ( array $config ): array {
+                $route = $config['route'] ?? '';
+                if ( ! $route ) {
+                    return [];
+                }
+                $routes    = rest_get_server()->get_routes();
+                $full_path = '/clautron/v1/' . ltrim( $route, '/' );
+                if ( isset( $routes[ $full_path ] ) ) {
+                    return [ [ 'status' => 'passed', 'label' => "register_rest_route:{$route}" ] ];
+                }
+                return [ [ 'status' => 'warning', 'label' => "register_rest_route:{$route}", 'reason' => 'not found in registered routes (REST server may not be initialized yet).' ] ];
+            },
         ] );
+    }
 …
             'category'    => 'wordpress',
             'phase'       => 'compile',
+            'effects'     => [ 'writes_database' ],
             'label'       => 'Schedule Post Expiry',
             'description' => 'Automatically change post status on its expiry date (stored in meta).',
 …
             'category'    => 'wordpress',
             'phase'       => 'runtime',
+            // The handler only allows draft/publish/pending/private (anything else
+            // becomes draft), so a new post can be published but never trashed.
+            'effects'     => static fn( array $c ): array => array_values( array_diff( self::post_status_effects( (string) ( $c['post_status'] ?? 'draft' ) ), [ 'deletes_data' ] ) ),
+            'effects_max' => [ 'writes_database', 'external_requests' ],
+            'safe'        => false,
             'label'       => 'Create Post',
             'description' => 'Create a new WordPress post (any type / status). Supports deduplication by post meta key + value to avoid creating duplicate posts across job runs.',
 …
             'category'    => 'wordpress',
             'phase'       => 'runtime',
+            'effects'     => static fn( array $c ): array => self::post_status_effects( (string) ( $c['post_status'] ?? '' ) ),
+            'effects_max' => [ 'writes_database', 'deletes_data', 'external_requests' ],
             'label'       => 'Update Post',
             'description' => 'Update fields on an existing WordPress post. Only provided fields are changed.',
 …
             'category'    => 'wordpress',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database', 'deletes_data' ],
             'label'       => 'Delete Post',
             'description' => 'Move a post to trash (force=false) or permanently delete it (force=true).',
 …
             'category'    => 'wordpress',
             'phase'       => 'runtime',
+            'effects'     => static fn( array $c ): array => self::post_status_effects( (string) ( $c['status'] ?? '' ) ),
+            'effects_max' => [ 'writes_database', 'deletes_data', 'external_requests' ],
             'label'       => 'Set Post Status',
             'description' => 'Change the status of a post (draft, publish, pending, private, trash).',
 …
             'category'    => 'wordpress',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Check WooCommerce HPOS',
             'description' => 'Detects whether WooCommerce High Performance Order Storage (HPOS) is active. Stores true/false in a context variable. Use with if_else to branch between HPOS and legacy wp_posts order queries.',
 …
             'category'    => 'wordpress',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database' ],
             'label'       => 'Schedule Single Event',
             'description' => 'Schedule a one-time WP-Cron event to fire at a future time. The hook name must start with "clautron_" for safety. The arg is resolved as an integer (post/order ID).',

clautron/tags/1.5.0/includes/primitives/class-primitive-workflow.php

-              r3582869
+              r3784837
             'category'    => 'workflow',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Validate Field',
             'description' => 'Validate a value against rules (required, min_length, max_length, email, url, numeric, regex). Writes true/false to output_variable. Writes error message to error_variable if set.',
 …
             'category'    => 'workflow',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database' ],
             'label'       => 'Request Review',
             'description' => 'Flag a post for editorial review by setting its status to \'pending\' and storing a review request note in meta.',
 …
             'category'    => 'workflow',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database', 'deletes_data', 'external_requests' ], // deletes the review note; publishing pings
             'label'       => 'Approve Content',
             'description' => 'Approve content by publishing a pending post and clearing the review note.',
 …
             'category'    => 'workflow',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database' ],
             'label'       => 'Reject Content',
             'description' => 'Reject content by reverting a pending post to draft and storing a rejection reason.',

clautron/tags/1.5.0/includes/registry/class-primitive-registry.php

-              r3582869
+              r3784837
      *   @type string   $description One-sentence description for the AI prompt catalog.
      *   @type string   $dependency  null | 'woocommerce' | 'acf' | ...
+     *   @type callable|null $verify function( array $config ): array — used by
+     *                               CLAUTRON_Smoke_Tester. Returns zero or more
+     *                               check items { status: passed|failed|warning,
+     *                               label: string, reason?: string }. Return []
+     *                               when there's nothing meaningful to check for
+     *                               a given config (e.g. a required field is
+     *                               empty). Omit entirely (leave null) if this
+     *                               primitive type has no verification yet — it
+     *                               will show up as 'unavailable' rather than
+     *                               being silently skipped.
+     *   @type string[]|Closure|null $effects  Which of self::EFFECTS the primitive
+     *                               has, e.g. [ 'writes_database' ]; [] = none.
+     *                               A Closure( array $config ): string[] when
+     *                               they depend on config. null (omitted) =
+     *                               undeclared, which consumers must treat as
+     *                               "could be anything". An unknown effect name
+     *                               is reported with _doing_it_wrong() and makes
+     *                               the primitive undeclared, never "no effect".
+     *   @type string[] $effects_max Required with a Closure: every effect any
+     *                               config can produce. The catalog publishes
+     *                               this worst case; the abilities still answer
+     *                               per call from the real config.
+     *   @type bool|Closure|null $reversible  Whether deactivating removes every
+     *                               trace. Omitted = derived from effects (no
+     *                               data written, deleted or sent away). Set it
+     *                               when something outlives deactivation that
+     *                               effects can't express (a cookie, HSTS).
+     *   @type array[]  $examples    Example configs. Omitted = the
+     *                               clautron/primitives-list ability falls back
+     *                               to configs found in the shipped demos.
      * }
      */
 …
             'description' => '',
             'dependency'  => null,
+            'verify'      => null,
+            'effects'     => null,
+            'effects_max' => null,
+            'reversible'  => null,
+            'examples'    => [],
         ] );
         self::$primitives[ $type ]['type'] = $type;
+        self::check_effects( $type );
+    }
+    /**
+     * A typo in an effect name must not quietly read as "no effect" (and so
+     * as reversible): report it and treat the primitive as undeclared.
+     */
+    private static function check_effects( string $type ): void {
+        $def     = self::$primitives[ $type ];
+        $unknown = [];
+        foreach ( [ 'effects', 'effects_max' ] as $key ) {
+            if ( is_array( $def[ $key ] ) ) {
+                $unknown = array_merge( $unknown, array_diff( $def[ $key ], self::EFFECTS ) );
+            }
+        }
+        if ( $unknown ) {
+            self::$primitives[ $type ]['effects'] = null;
+            self::doing_it_wrong( "Primitive '{$type}' declares unknown effects: " . implode( ', ', array_unique( $unknown ) ) . '. Allowed: ' . implode( ', ', self::EFFECTS ) . '.' );
+        } elseif ( $def['effects'] instanceof Closure && ! is_array( $def['effects_max'] ) ) {
+            self::doing_it_wrong( "Primitive '{$type}' computes its effects from config but declares no effects_max; the catalog will list its effects as unknown." );
+        }
+    }
+    private static function doing_it_wrong( string $message ): void {
+        if ( function_exists( '_doing_it_wrong' ) ) {
+            _doing_it_wrong( 'CLAUTRON_Primitive_Registry::register', esc_html( $message ), '1.5.0' );
+        }
+    }
+    /**
+     * Effect vocabulary, the same keys a capability manifest's `effects` uses
+     * (Capability Contract v1), so a consumer reads both the same way:
+     *   writes_database    creates or changes content, meta, options, users,
+     *                      terms, comments, orders, events or transients
+     *   writes_files       writes or deletes files on disk
+     *   deletes_data       removes or trashes site data
+     *   external_requests  sends data off the site (HTTP, email, AI provider),
+     *                      including what WordPress itself sends because of
+     *                      it: pings when a post gets published, the post
+     *                      author's email when a comment is approved
+     *   executes_code      outputs markup or script taken from its config
+     *   changes_schema     changes the content model or API surface (post
+     *                      types, taxonomies, registered meta, REST routes)
+     */
+    public const EFFECTS = [ 'writes_database', 'writes_files', 'deletes_data', 'external_requests', 'executes_code', 'changes_schema' ];
+    /** Effects that make deactivation an incomplete undo when nothing else is declared. */
+    private const PERSISTENT_EFFECTS = [ 'writes_database', 'writes_files', 'deletes_data', 'external_requests' ];
+    /**
+     * Effects of one node, as EFFECTS => bool, or null when the primitive
+     * (or the type itself) is unknown or declares none.
+     */
+    public static function node_effects( string $type, array $config = [] ): ?array {
+        $def = self::get( $type );
+        if ( ! $def || null === $def['effects'] ) {
+            return null;
+        }
+        $list = $def['effects'] instanceof Closure ? (array) ( $def['effects'] )( $config ) : (array) $def['effects'];
+        if ( array_diff( $list, self::EFFECTS ) ) {
+            self::doing_it_wrong( "Primitive '{$type}' computed unknown effects: " . implode( ', ', array_diff( $list, self::EFFECTS ) ) . '.' );
+            return null;
+        }
+        return array_combine( self::EFFECTS, array_map( static fn( string $e ): bool => in_array( $e, $list, true ), self::EFFECTS ) );
+    }
+    /**
+     * Every effect the primitive can have with any config: effects_max for a
+     * config-dependent declaration, the static list otherwise. null when
+     * undeclared or when a Closure has no effects_max.
+     *
+     * @return string[]|null
+     */
+    public static function max_effects( string $type ): ?array {
+        $def = self::get( $type );
+        if ( ! $def || null === $def['effects'] ) {
+            return null;
+        }
+        if ( $def['effects'] instanceof Closure ) {
+            return is_array( $def['effects_max'] ) ? array_values( $def['effects_max'] ) : null;
+        }
+        return array_values( (array) $def['effects'] );
+    }
+    /** Whether deactivating undoes the primitive with every config (false when any config can't). */
+    private static function always_reversible( array $def, ?array $max ): bool {
+        if ( null === $max || $def['reversible'] instanceof Closure ) {
+            return false;
+        }
+        if ( null !== $def['reversible'] ) {
+            return (bool) $def['reversible'];
+        }
+        return ! array_intersect( $max, self::PERSISTENT_EFFECTS );
+    }
+    /**
+     * Combined effects of every node in a blueprint (structures, conditions,
+     * actions), whether deactivating it would undo all of them, and which
+     * node types declare no effects (consumers should treat those as risky).
+     *
+     * @return array{effects: array<string,bool>, reversible: bool, undeclared: string[]}
+     */
+    public static function effects_of( array $blueprint ): array {
+        $effects    = array_fill_keys( self::EFFECTS, false );
+        $reversible = true;
+        $undeclared = [];
+        foreach ( [ 'structures', 'conditions', 'actions' ] as $list ) {
+            foreach ( (array) ( $blueprint[ $list ] ?? [] ) as $node ) {
+                $type   = (string) ( $node['type'] ?? '' );
+                $config = (array) ( $node['config'] ?? [] );
+                $node_effects = self::node_effects( $type, $config );
+                if ( null === $node_effects ) {
+                    $undeclared[] = $type;
+                    $reversible   = false;
+                    continue;
+                }
+                foreach ( $node_effects as $effect => $has ) {
+                    $effects[ $effect ] = $effects[ $effect ] || $has;
+                }
+                $reversible = $reversible && self::node_reversible( $type, $config, $node_effects );
+            }
+        }
+        return [ 'effects' => $effects, 'reversible' => $reversible, 'undeclared' => array_values( array_unique( $undeclared ) ) ];
+    }
+    private static function node_reversible( string $type, array $config, array $effects ): bool {
+        $declared = self::$primitives[ $type ]['reversible'];
+        if ( $declared instanceof Closure ) {
+            return (bool) $declared( $config );
+        }
+        if ( null !== $declared ) {
+            return (bool) $declared;
+        }
+        return ! array_filter( array_intersect_key( $effects, array_flip( self::PERSISTENT_EFFECTS ) ) );
+    }
 …
     /**
+     * Build the capability catalog injected into the AI system prompt.
+     * Returns a lightweight array — type, category, description, schema.
+     * Build the capability catalog injected into the AI system prompt and
+     * returned by the clautron/primitives-list ability.
+     *
+     * `safe` false = needs explicit approval before use; `verifiable` = the
+     * primitive declares a verify check, so a smoke test can confirm it.
+     * `effects` is the worst case over every config (null when undeclared or
+     * unknown) and `reversible` is true only when deactivating undoes it with
+     * every config; `effects_vary` = some config values are milder, so ask
+     * effects_of() for the real config (the abilities return it per call).
+     *
      * @return array[]
 …
         $catalog = [];
         foreach ( self::$primitives as $type => $def ) {
+            $max       = self::max_effects( $type );
             $catalog[] = [
+                'type'        => $type,
+                'category'    => $def['category'],
+                'phase'       => $def['phase'],
+                'label'       => $def['label'],
+                'description' => $def['description'],
+                'schema'      => $def['schema'],
+                'dependency'  => $def['dependency'],
+                'type'         => $type,
+                'category'     => $def['category'],
+                'phase'        => $def['phase'],
+                'label'        => $def['label'],
+                'description'  => $def['description'],
+                'schema'       => $def['schema'],
+                'dependency'   => $def['dependency'],
+                'safe'         => (bool) $def['safe'],
+                'verifiable'   => is_callable( $def['verify'] ),
+                'effects'      => null === $max ? null : array_values( array_intersect( self::EFFECTS, $max ) ),
+                'effects_vary' => $def['effects'] instanceof Closure || $def['reversible'] instanceof Closure,
+                'reversible'   => self::always_reversible( $def, $max ),
+                'examples'     => array_values( (array) $def['examples'] ),
             ];
+        }

clautron/tags/1.5.0/readme.txt

-              r3691450
+              r3784837
 Tags: capability, automation, security, no-code, ai
 Requires at least: 7.0
 Tested up to: 7.0
 Stable tag: 1.2.0
+Tested up to: 7.1
+Stable tag: 1.5.0
 Requires PHP: 8.1
 License: GPL-2.0-or-later
 …
 **One secure layer. Thousands of capabilities.**
 Every capability Clautron builds can be activated, deactivated, and rolled back the same predictable way. Before you turn one on, you can see what it reads, what it writes, what it connects to, and how much it changes.
+Every capability Clautron builds can be activated and deactivated the same predictable way, without touching any data it wrote while it was on. Before you turn one on, you can see what it reads, what it writes, what it connects to, and how much it changes.
 **Key features:**
 …
 * **Search first, generate second:** Clautron checks what already exists before generating anything new; when it does generate something, you review it before it runs
 * **Know what runs on your site:** every capability is built from a declared, inspectable set of primitives
+* **Reversible by design:** activate, deactivate, or roll back any capability without digging through code
+* **Deactivate without data loss:** turn any capability off without digging through code. Nothing it wrote while active is touched, and turning it back on reactivates the same capability instead of starting over
+* **Machine-readable capability manifest:** each capability can declare its own version, requirements, required permissions, and effects (what it reads, writes, or connects to). External tools like AICOM can inspect and manage capabilities through this same contract, without hardcoded per-capability logic
+* **Know what a capability does before you turn it on:** every building block declares whether it writes data, deletes data, sends data off the site or outputs code, and whether turning it off fully undoes it
+* **Security hardening without a security plugin:** stop username discovery, add the missing security headers and hide the WordPress version, each as a small capability you can switch off again
+* **Ready for AI agents:** every Clautron operation is a WordPress Ability with its own schema, so AI agents and tools like AICOM can find and use them without custom integration code
 * **Scheduled jobs and reports:** recurring automations and on-demand data queries, without a separate plugin for each
 * **Safe by construction:** a safety policy layer blocks dangerous operations before they run
 …
 = What are primitives, and what's a capability? =
 Primitives are the small, reusable building blocks Clautron composes things from: custom post types, meta fields, admin columns, scheduled tasks, and more. A capability is what you actually get: a specific piece of functionality (a redirect, an admin column, a WooCommerce rule) built from one or more primitives, that you can activate, deactivate, or roll back as one unit.
+Primitives are the small, reusable building blocks Clautron composes things from: custom post types, meta fields, admin columns, scheduled tasks, and more. A capability is what you actually get: a specific piece of functionality (a redirect, an admin column, a WooCommerce rule) built from one or more primitives, that you can activate or deactivate as one unit. Some capabilities also carry a manifest (a declared version, requirements, and effects) that lets external tools install, inspect, update, and deactivate them without capability-specific code.
 = Does this plugin store data in the database? =
 Yes. Clautron creates its own database tables (prefixed with `wp_clautron_`) to store blueprints, conversation history, scheduled jobs, workflow state, and execution logs. All data is removed if you uninstall the plugin.
+Yes. Clautron creates its own database tables (prefixed with `wp_clautron_`) to store blueprints, conversation history, scheduled jobs, workflow state, capability install state, and execution logs. All data is removed if you uninstall the plugin.
 = What permissions are required? =
 Clautron is accessible only to administrators (`manage_options` capability). No frontend functionality or public-facing pages are added to your site.
+Clautron's own screens are only available to administrators (`manage_options` capability). Clautron adds nothing to the frontend by itself: visitors only see changes from capabilities you activate, such as a consent banner, a redirect or security headers.
 == External Services ==
 …
 == Changelog ==
+= 1.5.0 =
+* Added harden_user_enumeration: stops anonymous visitors from discovering usernames. Logged-out requests to the /wp/v2/users REST endpoints get a 401 (logged-in users and the block editor keep working), every author archive returns a 404, the users sitemap is removed, oEmbed shows the site instead of the author, and the login form gives the same error for an unknown username and a wrong password.
+* Added security_headers: sends Referrer-Policy, X-Content-Type-Options, X-Frame-Options and Permissions-Policy, plus Strict-Transport-Security (HSTS) on HTTPS when you opt in. Its check loads your homepage to confirm the headers actually reach visitors, so a page cache or CDN that drops them is reported.
+* Added hide_wp_version: removes the WordPress, WooCommerce and Elementor generator tags from pages and feeds, and masks the WordPress version in asset URLs while keeping browser caches working. Optionally deletes readme.html, and deletes it again after each WordPress update.
+* Added a ready-made Security Hardening capability built from these three primitives.
+* Every Clautron operation (catalog, install, inspect, update, deactivate, blueprints, events) is now a WordPress Ability with its own input schema and behavior annotations, so AI agents and management tools such as AICOM can discover and call them without Clautron-specific code. New: primitive-apply, which applies a single primitive as its own capability, validated and verified.
+* Every primitive now declares its effects: whether it writes data, writes files, deletes data, sends data off the site, outputs code from its configuration, or changes the content model, and whether turning it off fully undoes it. Installing, applying or ensuring a capability reports these effects, in a dry run too, together with the step that reverses the change.
+* Fixed ensuring a deactivated custom capability creating a second copy of it: it is now reactivated.
+* Fixed register_cpt writing the edit_post, read_post and delete_post meta capabilities into the administrator role on every page load.
+* http_request, fetch_feed, create_post and add_admin_notice are now flagged as needing approval, like the other primitives that can send data off the site, delete data or output code.
+= 1.4.0 =
+* Added consent_banner: a category-based cookie-consent banner (necessary/analytics/marketing) with an anonymous REST endpoint to record the visitor's choice, a full audit trail (who consented to what, when, from which source) in the events store, and automatic opt-out when the visitor's browser sends the Global Privacy Control (Sec-GPC) signal.
+* Added gate_script_by_consent: outputs a script or HTML block only once its required consent category has been granted, reading the same cookie consent_banner writes.
+* consent_banner can emit Google Consent Mode v2 signals (gtag consent default/update), mapping consent categories to Google's ad_storage/analytics_storage/ad_user_data/ad_personalization signals for GA4 and Ads.
+* Fixed handle_upload's internal failure closure declaring a standalone `false` return type, valid only since PHP 8.2, which fataled on activation despite the plugin declaring Requires PHP 8.1.
+= 1.3.0 =
+* Added a machine-readable capability manifest (version, platform/PHP/WordPress requirements, required permissions, declared effects, reversibility), kept separate from a capability's blueprint and joined only by capability_id. Lets external tools like AICOM install, inspect, update, and deactivate capabilities through one consistent contract instead of capability-specific code.
+* Added a new `wp_clautron_capabilities` table tracking each capability's installed version and status separately from its blueprint. This enables comparing installed vs. available version and reinstalling a deactivated capability without losing its edit history.
+* Added a deactivate operation: stops a capability from being re-applied on future requests without touching any data it wrote while active. Reinstalling afterward reactivates the same capability rather than creating a duplicate.
+* Added an update operation: re-syncs an installed capability to its manifest's current declared version in place.
+* Primitive verification (used to confirm a compiled capability is correctly wired into WordPress) is no longer a fixed, hardcoded checklist covering a handful of primitive types: each primitive now declares its own check, and any primitive without one is reported explicitly rather than silently skipped.
+* Fixed the metabox verification check to look up the actual registered meta box ID (it was checking an ID that never matched, so it could never report success).
 = 1.2.0 =
 …
 == Upgrade Notice ==
+= 1.5.0 =
+Adds security hardening primitives, WordPress Abilities for every operation, and declared effects for every primitive. No breaking changes.
+= 1.3.0 =
+Adds a capability manifest, deactivate/update operations, and per-primitive verification. No breaking changes.
 = 1.1.0 =
 Adds Elementor and WordPress widget primitives. No breaking changes.

clautron/tags/1.5.0/uninstall.php

r3582869	r3784837
16	16
17	17	delete_option( 'clautron_settings' );
	18	delete_option( 'clautron_readme_removed_for' ); // hide_wp_version's remove_readme bookkeeping
18	19	delete_transient( 'clautron_active_workflows' );

clautron/trunk/clautron.php

-              r3691450
+              r3784837
  * Plugin URI:        https://wordpress.org/plugins/clautron/
  * Description:       Get the feature. Not the plugin. Add exactly the WordPress capability you need: inspectable, secure, reversible.
  * Version:           1.2.0
+ * Version:           1.5.0
  * Author:            Clautron
  * Author URI:        https://profiles.wordpress.org/dudaster/
 …
 // ─── Constants ───────────────────────────────────────────────────────────────
 define( 'CLAUTRON_VERSION',     '1.2.0' );
+define( 'CLAUTRON_VERSION',     '1.5.0' );
 define( 'CLAUTRON_FILE',        __FILE__ );
 define( 'CLAUTRON_DIR',         plugin_dir_path( __FILE__ ) );
 define( 'CLAUTRON_URL',         plugin_dir_url( __FILE__ ) );
 define( 'CLAUTRON_DB_VERSION',  '4' );
+define( 'CLAUTRON_DB_VERSION',  '5' );
 // ─── Autoloader ──────────────────────────────────────────────────────────────
 …
         'primitive-cookie'     => 'includes/primitives/class-primitive-cookie.php',
+        // Consent (cookie-consent banner + category-gated script output)
+        'primitive-consent'    => 'includes/primitives/class-primitive-consent.php',
         // Language (multilingual query filtering)
         'primitive-language'   => 'includes/primitives/class-primitive-language.php',
 …
         'catalog'              => 'includes/class-catalog.php',
+        // Capability Manifest (machine-readable contract: version, requirements, scopes, effects)
+        'manifest-registry'    => 'includes/registry/class-manifest-registry.php',
+        'capability-store'     => 'includes/class-capability-store.php',
         // Smoke Tester (verify compiled blueprints are wired correctly)
         'smoke-tester'         => 'includes/class-smoke-tester.php',
+        // Abilities (every operation above as a self-describing WordPress Ability)
+        'abilities'            => 'includes/class-abilities.php',
         // Admin

clautron/trunk/demo/blueprint-cookie-consent.json

-              r3691441
+              r3784837
   "id": "f2a3b4c5-d6e7-4890-b123-c45678901bcd",
   "object_type": "feature",
   "name": "Cookie Consent Banner",
   "description": "Shows a GDPR-style cookie consent banner in the footer with an Accept link. Clicking it stores consent in a first-party cookie for 365 days, which also suppresses the banner on return visits. Replaces a basic cookie-notice plugin.",
+  "name": "GDPR Consent Banner",
+  "description": "Cookie-consent banner with per-category consent (necessary/analytics/marketing), a full audit trail of who consented to what and when, automatic opt-out when the visitor's browser sends Global Privacy Control (Sec-GPC), and Google Consent Mode v2 signals for GA4/Ads. Replaces a dedicated cookie-consent plugin for the common case.",
   "capability_id": "cookie-consent-banner",
   "provides": {},
   "status": "draft",
   "source": "manual",
   "nl_input": "Show a cookie consent banner on the site with an accept button that remembers the choice for a year.",
+  "nl_input": "Show a GDPR cookie consent banner with analytics/marketing categories, honor Global Privacy Control automatically, and signal Google Consent Mode.",
   "structures": [
+    {
       "id": "s-banner",
       "type": "inject_wp_footer",
+      "type": "consent_banner",
       "config": {
+        "template": "<div id=\"clautron-cookie-banner\" style=\"position:fixed;bottom:0;left:0;right:0;background:#222;color:#fff;padding:14px 20px;font-size:14px;z-index:9999;\">This site uses cookies to improve your experience. <a href=\"?clautron_action=accept_cookies\" style=\"color:#8ecdf7;\">Accept</a></div>",
+        "suppress_if_cookie": "cookie_consent"
+        "categories": [
+          { "key": "necessary", "label": "Necessary", "description": "Required for the site to function.", "required": true },
+          { "key": "analytics", "label": "Analytics", "description": "Helps us understand site usage." },
+          { "key": "marketing", "label": "Marketing", "description": "Used for ad personalization." }
+        ],
+        "policy_version": "1",
+        "banner_text": "This site uses cookies. Choose which categories you're OK with.",
+        "position": "bottom",
+        "days": 180,
+        "endpoint_path": "consent",
+        "honor_gpc": true,
+        "consent_mode_map": {
+          "analytics": ["analytics_storage"],
+          "marketing": ["ad_storage", "ad_user_data", "ad_personalization"]
+        }
+      }
+    },
+    {
+      "id": "s-analytics-script",
+      "type": "gate_script_by_consent",
+      "config": {
+        "category": "analytics",
+        "html": "<!-- Load your analytics script here — it only outputs once \"analytics\" consent is granted -->",
+        "placement": "head"
+      }
+    }
-  ],
-  "trigger": { "type": "hook", "config": { "hook": "template_redirect" } },
-  "conditions": [
-    { "id": "c1", "type": "read_request_param", "config": { "source": "get", "param": "clautron_action", "output_variable": "action", "default": "" } },
-    { "id": "c2", "type": "if_else", "config": { "field": "{{action}}", "operator": "eq", "value": "accept_cookies", "pass_branch": ["a1"], "fail_branch": [] } }
-  ],
-  "actions": [
-    { "id": "a1", "type": "write_cookie", "config": { "name": "cookie_consent", "value": "accepted", "days": 365 } }
+  ]
+}

clautron/trunk/includes/class-catalog.php

-              r3582869
+              r3784837
  *  - Active capabilities (compiled + running on this site).
  *  - Available templates (demo blueprints not yet installed).
+ *  - inspect(): install/version/compatibility state for one capability_id.
+ *
+ * When a capability_id has a manifest (demo/capabilities/*.manifest.json,
+ * loaded via CLAUTRON_Manifest_Registry), catalog entries carry it under
+ * 'manifest' plus a 'has_manifest' flag — additive, so capabilities without
+ * a manifest keep working exactly as before.
+ *
  * External systems (e.g. AICOM) call these methods directly — no HTTP needed.
 …
                 continue;
+            }
+            $manifest = class_exists( 'CLAUTRON_Manifest_Registry' ) ? CLAUTRON_Manifest_Registry::get( $data['capability_id'] ) : null;
             $active[] = [
                 'capability_id' => $data['capability_id'],
 …
                 'provides'      => $data['provides'] ?? [],
                 'llm_guide'     => $data['llm_guide'] ?? '',
+                'manifest'      => $manifest,
+                'has_manifest'  => $manifest !== null,
             ];
+        }
 …
                 continue;
+            }
+            $manifest = class_exists( 'CLAUTRON_Manifest_Registry' ) ? CLAUTRON_Manifest_Registry::get( $data['capability_id'] ) : null;
             $templates[] = [
                 'capability_id' => $data['capability_id'],
 …
                 'provides'      => $data['provides'] ?? [],
                 'llm_guide'     => $data['llm_guide'] ?? '',
+                'manifest'      => $manifest,
+                'has_manifest'  => $manifest !== null,
             ];
+        }
 …
+        }
+        // Find template file.
+        $demo_dir = CLAUTRON_DIR . 'demo/';
+        $template = null;
+        foreach ( glob( $demo_dir . '*.json' ) ?: [] as $path ) {
+            $data = json_decode( file_get_contents( $path ), true );
+            if ( is_array( $data ) && ( $data['capability_id'] ?? '' ) === $capability_id ) {
+                $template = $data;
+                break;
+            }
+        }
+        // Known but not active (e.g. deactivated) — reactivate the SAME
+        // blueprint instead of creating a new one, so version history and
+        // the blueprint's own identity survive a deactivate → install cycle.
+        $known = class_exists( 'CLAUTRON_Capability_Store' )
+            ? CLAUTRON_Capability_Store::find_by_capability_id( $capability_id )
+            : null;
+        if ( $known ) {
+            $existing_blueprint_id = (int) $known->blueprint_id;
+            $existing_row          = CLAUTRON_Blueprint_Store::get( $existing_blueprint_id );
+            if ( $existing_row ) {
+                $result = CLAUTRON_Plugin::make_compiler()->compile( $existing_blueprint_id );
+                if ( ! empty( $result->get_errors() ) ) {
+                    return [
+                        'success'       => false,
+                        'blueprint_id'  => $existing_blueprint_id,
+                        'compiled'      => false,
+                        'capability_id' => $capability_id,
+                        'error'         => implode( '; ', $result->get_errors() ),
+                    ];
+                }
+                self::record_installed_instance( $capability_id, $existing_blueprint_id );
+                return [
+                    'success'       => true,
+                    'blueprint_id'  => $existing_blueprint_id,
+                    'compiled'      => true,
+                    'capability_id' => $capability_id,
+                    'note'          => 'Reactivated existing blueprint.',
+                    'warnings'      => $result->get_warnings(),
+                ];
+            }
+            // Fall through to a fresh template install if the known
+            // blueprint row itself is gone (shouldn't normally happen).
+        }
+        $template = self::find_template_data( $capability_id );
         if ( ! $template ) {
 …
+        }
+        self::record_installed_instance( $capability_id, $blueprint_id );
         return [
             'success'       => true,
 …
+    }
+    /**
+     * Update an already-installed capability to its manifest's current
+     * declared version, in place — same blueprint row, new blueprint_json,
+     * recompiled. Distinct from install(): requires the capability to
+     * already be installed, and requires a manifest (the target version
+     * always comes from the manifest's own 'version' field — there's no
+     * store of multiple historical template versions to pick from).
+     *
+     * @return array {
+     *   @type bool        $success
+     *   @type string      $status         'already_current' | 'updated' (only on success)
+     *   @type int|null    $blueprint_id
+     *   @type string|null $from_version
+     *   @type string|null $to_version
+     *   @type string      $error          (only on failure)
+     * }
+     */
+    public static function update( string $capability_id ): array {
+        $installed = class_exists( 'CLAUTRON_Capability_Store' )
+            ? CLAUTRON_Capability_Store::find_by_capability_id( $capability_id )
+            : null;
+        if ( ! $installed ) {
+            return [
+                'success' => false,
+                'error'   => "Capability '{$capability_id}' is not installed. Use clautron.catalog.install first.",
+                'code'    => 'not_installed',
+            ];
+        }
+        $manifest = class_exists( 'CLAUTRON_Manifest_Registry' ) ? CLAUTRON_Manifest_Registry::get( $capability_id ) : null;
+        if ( ! $manifest ) {
+            return [
+                'success' => false,
+                'error'   => "Capability '{$capability_id}' has no manifest, so it has no declared target version to update to.",
+                'code'    => 'no_manifest',
+            ];
+        }
+        $from_version = $installed->installed_version;
+        $to_version   = $manifest['version'];
+        if ( $from_version === $to_version ) {
+            return [
+                'success'      => true,
+                'status'       => 'already_current',
+                'blueprint_id' => (int) $installed->blueprint_id,
+                'from_version' => $from_version,
+                'to_version'   => $to_version,
+            ];
+        }
+        $template = self::find_template_data( $capability_id );
+        if ( ! $template ) {
+            return [
+                'success' => false,
+                'error'   => "No template found for capability_id '{$capability_id}'.",
+                'code'    => 'template_missing',
+            ];
+        }
+        $blueprint_id = (int) $installed->blueprint_id;
+        $blueprint_row = CLAUTRON_Blueprint_Store::get( $blueprint_id );
+        if ( ! $blueprint_row ) {
+            return [
+                'success' => false,
+                'error'   => "Installed blueprint (id {$blueprint_id}) no longer exists.",
+                'code'    => 'blueprint_missing',
+            ];
+        }
+        // In-place edit: keep the existing blueprint's own UUID — this
+        // updates the same blueprint row, it doesn't create a new one.
+        $template['id'] = $blueprint_row->uuid;
+        $validation_blueprint = new CLAUTRON_Blueprint( $template );
+        $validation           = CLAUTRON_Blueprint_Validator::validate( $validation_blueprint );
+        if ( ! $validation->is_valid() ) {
+            return [
+                'success' => false,
+                'error'   => 'Updated template failed validation: ' . implode( '; ', $validation->get_errors() ),
+                'code'    => 'validation_failed',
+            ];
+        }
+        $encoded = wp_json_encode( $template );
+        $saved   = CLAUTRON_Blueprint_Store::update_json( $blueprint_id, $encoded, "Updated to v{$to_version} via Capability Contract" );
+        if ( ! $saved ) {
+            return [
+                'success' => false,
+                'error'   => 'Failed to save updated blueprint to database.',
+                'code'    => 'save_failed',
+            ];
+        }
+        $result = CLAUTRON_Plugin::make_compiler()->compile( $blueprint_id );
+        if ( ! empty( $result->get_errors() ) ) {
+            return [
+                'success'      => false,
+                'blueprint_id' => $blueprint_id,
+                'from_version' => $from_version,
+                'to_version'   => $to_version,
+                'error'        => implode( '; ', $result->get_errors() ),
+                'code'         => 'compile_failed',
+            ];
+        }
+        self::record_installed_instance( $capability_id, $blueprint_id );
+        return [
+            'success'      => true,
+            'status'       => 'updated',
+            'blueprint_id' => $blueprint_id,
+            'from_version' => $from_version,
+            'to_version'   => $to_version,
+            'warnings'     => $result->get_warnings(),
+        ];
+    }
+    /**
+     * Deactivate an installed capability — stops its compile-phase
+     * primitives from being re-applied on the next request
+     * (CLAUTRON_Runtime_Engine::boot() only replays workflows with
+     * status='active'; CLAUTRON_Compiler::decompile() removes the
+     * workflow row and pauses the blueprint). Never touches data: no
+     * postmeta, terms, or custom table rows written while the capability
+     * was active are read or modified. Always allowed, regardless of
+     * reversibility.strategy — that field describes what a future
+     * `rollback` action would (not) be able to undo, it does not gate
+     * deactivate.
+     *
+     * @return array {
+     *   @type bool     $success
+     *   @type string   $status           'deactivated' (only on success)
+     *   @type int|null $blueprint_id
+     *   @type bool     $data_preserved   Always true on success.
+     *   @type string[] $residual_effects Human-readable notes derived from the manifest's 'effects', if any.
+     *   @type string   $error            (only on failure)
+     * }
+     */
+    public static function deactivate( string $capability_id ): array {
+        $installed = class_exists( 'CLAUTRON_Capability_Store' )
+            ? CLAUTRON_Capability_Store::find_by_capability_id( $capability_id )
+            : null;
+        if ( ! $installed || $installed->status !== 'active' ) {
+            return [
+                'success' => false,
+                'error'   => "Capability '{$capability_id}' is not currently active.",
+                'code'    => 'not_active',
+            ];
+        }
+        $blueprint_id = (int) $installed->blueprint_id;
+        CLAUTRON_Plugin::make_compiler()->decompile( $blueprint_id );
+        // Covers decompile()'s one confirmed gap: it doesn't flush rewrite
+        // rules, so a register_cpt/register_taxonomy with a custom slug
+        // can leave stale permalinks until the next flush. Cheap enough
+        // for a rare, explicit operation.
+        flush_rewrite_rules( false );
+        CLAUTRON_Capability_Store::update_status( $capability_id, 'paused' );
+        $manifest          = class_exists( 'CLAUTRON_Manifest_Registry' ) ? CLAUTRON_Manifest_Registry::get( $capability_id ) : null;
+        $residual_effects  = self::describe_residual_effects( $manifest['effects'] ?? [] );
+        return [
+            'success'          => true,
+            'status'           => 'deactivated',
+            'blueprint_id'     => $blueprint_id,
+            'data_preserved'   => true,
+            'residual_effects' => $residual_effects,
+        ];
+    }
+    /**
+     * Translate a manifest's declared 'effects' into human-readable notes
+     * about what deactivate does NOT undo — derived from data already
+     * declared on the manifest, no new metadata needed.
+     */
+    private static function describe_residual_effects( array $effects ): array {
+        $notes = [];
+        if ( ! empty( $effects['writes_database'] ) ) {
+            $notes[] = 'Data written while active (e.g. post meta) is preserved and not reverted.';
+        }
+        if ( ! empty( $effects['changes_schema'] ) ) {
+            $notes[] = 'Any schema changes made while active (e.g. new fields/columns) are preserved.';
+        }
+        if ( ! empty( $effects['writes_files'] ) ) {
+            $notes[] = 'Files written while active are preserved on disk.';
+        }
+        return $notes;
+    }
+    /**
+     * Locate a demo template's decoded JSON by capability_id, or null.
+     */
+    private static function find_template_data( string $capability_id ): ?array {
+        $demo_dir = CLAUTRON_DIR . 'demo/';
+        foreach ( glob( $demo_dir . '*.json' ) ?: [] as $path ) {
+            $data = json_decode( file_get_contents( $path ), true );
+            if ( is_array( $data ) && ( $data['capability_id'] ?? '' ) === $capability_id ) {
+                return $data;
+            }
+        }
+        return null;
+    }
+    /**
+     * Upsert the installed-instance row (wp_clautron_capabilities) after a
+     * successful install/compile — separate from the generic blueprint row,
+     * see CLAUTRON_Capability_Store.
+     */
+    private static function record_installed_instance( string $capability_id, int $blueprint_id ): void {
+        if ( ! class_exists( 'CLAUTRON_Capability_Store' ) ) {
+            return;
+        }
+        $manifest = class_exists( 'CLAUTRON_Manifest_Registry' ) ? CLAUTRON_Manifest_Registry::get( $capability_id ) : null;
+        CLAUTRON_Capability_Store::upsert( [
+            'capability_id'     => $capability_id,
+            'blueprint_id'      => $blueprint_id,
+            'installed_version' => $manifest['version'] ?? 'unknown',
+            'status'            => 'active',
+            'reversibility'     => $manifest['reversibility']['strategy'] ?? 'none',
+        ] );
+    }
     // ── Idempotent provisioning ───────────────────────────────────────────────
     /**
+     * Ensure a capability exists and is active. Idempotent — safe to call repeatedly.
+     * What ensure() would do for a capability_id, without doing it. ensure()
+     * itself follows this, so a dry run can never disagree with the real call.
+     *
      * Resolution order:
+     *  1. Already active with this capability_id → return it unchanged.
+     *  2. Available as a demo template → install it.
+     *  3. blueprint_json provided → create + compile (capability_id is forced into the JSON).
+     *  1. already_active   — active with this capability_id: nothing to do.
+     *  2. reactivate       — known but deactivated, blueprint still there:
+     *                        install() recompiles the SAME blueprint. Without
+     *                        this a custom (non-template) capability would get
+     *                        a second blueprint every time it was ensured
+     *                        after a deactivate.
+     *  3. install_template — a demo template: install it.
+     *  4. create           — create + compile the caller's blueprint_json.
+     *
+     * @return array{action: string, blueprint_id: ?int}
+     */
+    public static function ensure_plan( string $capability_id ): array {
+        $cap = self::find_active( $capability_id );
+        if ( $cap ) {
+            return [ 'action' => 'already_active', 'blueprint_id' => (int) $cap['blueprint_id'] ];
+        }
+        $known = CLAUTRON_Capability_Store::find_by_capability_id( $capability_id );
+        if ( $known && CLAUTRON_Blueprint_Store::get( (int) $known->blueprint_id ) ) {
+            return [ 'action' => 'reactivate', 'blueprint_id' => (int) $known->blueprint_id ];
+        }
+        if ( in_array( $capability_id, array_column( self::get_templates(), 'capability_id' ), true ) ) {
+            return [ 'action' => 'install_template', 'blueprint_id' => null ];
+        }
+        return [ 'action' => 'create', 'blueprint_id' => null ];
+    }
+    /**
+     * Ensure a capability exists and is active. Idempotent — safe to call
+     * repeatedly. Resolution order: see ensure_plan().
+     *
      * @param string $capability_id  Unique slug identifying this capability.
 …
      * @return array {
      *   @type bool   $success
      *   @type string $status        'already_active' | 'installed_from_template' | 'created_and_compiled'
+     *   @type string $status        'already_active' | 'reactivated' | 'installed_from_template' | 'created_and_compiled'
      *   @type string $capability_id
      *   @type int    $blueprint_id
 …
      */
     public static function ensure( string $capability_id, string $blueprint_json = '' ): array {
         // ── 1. Already active ─────────────────────────────────────────────────
+        $cap = self::find_active( $capability_id );
         if ( $cap ) {
+        $plan = self::ensure_plan( $capability_id );
+        if ( 'already_active' === $plan['action'] ) {
             return [
                 'success'       => true,
                 'status'        => 'already_active',
                 'capability_id' => $capability_id,
+                'blueprint_id'  => $cap['blueprint_id'],
+            ];
+        }
+        // ── 2. Available as template ──────────────────────────────────────────
+        $templates = self::get_templates();
+        foreach ( $templates as $tpl ) {
+            if ( $tpl['capability_id'] === $capability_id ) {
+                $result           = self::install( $capability_id );
+                $result['status'] = $result['success'] ? 'installed_from_template' : ( $result['status'] ?? 'error' );
+                return $result;
+            }
+        }
+        // ── 3. Create from provided blueprint_json ────────────────────────────
+                'blueprint_id'  => $plan['blueprint_id'],
+            ];
+        }
+        if ( 'reactivate' === $plan['action'] || 'install_template' === $plan['action'] ) {
+            $result           = self::install( $capability_id );
+            $result['status'] = $result['success']
+                ? ( 'reactivate' === $plan['action'] ? 'reactivated' : 'installed_from_template' )
+                : ( $result['status'] ?? 'error' );
+            return $result;
+        }
+        // ── create: from the provided blueprint_json ──────────────────────────
         if ( ! $blueprint_json ) {
             return [
 …
+        }
+        self::record_installed_instance( $capability_id, $blueprint_id );
         return [
             'success'       => true,
 …
+    }
+    // ── Inspect ───────────────────────────────────────────────────────────────
+    /**
+     * Contract-level actions that always work for any capability_id,
+     * manifest or not — they're generic lookups, never gated by what a
+     * specific manifest opts into declaring.
+     */
+    private const ALWAYS_AVAILABLE_ACTIONS = [ 'discover', 'inspect' ];
+    /**
+     * Per-capability lifecycle actions the Capability Contract currently
+     * has a real, working executor for. A manifest may *declare* more
+     * (e.g. "update", "verify", "remove") than the contract can actually
+     * run yet — available_actions only ever advertises the intersection,
+     * so a caller never gets pointed at an action that would just fail.
+     */
+    private const IMPLEMENTED_LIFECYCLE_ACTIONS = [ 'install', 'update', 'deactivate' ];
+    /**
+     * Resolve current install/version/compatibility state for a capability_id.
+     *
+     * @return array {
+     *   @type bool        $installed
+     *   @type string|null $installed_version
+     *   @type string|null $available_version   From the manifest, if one exists.
+     *   @type bool        $compatible           True if no unmet requirements (or no manifest to check).
+     *   @type string      $status               not_installed|active|paused|removed
+     *   @type string[]    $available_actions    ALWAYS_AVAILABLE_ACTIONS + (manifest actions ∩ IMPLEMENTED_LIFECYCLE_ACTIONS).
+     *   @type string[]    $unmet_requirements
+     * }
+     */
+    public static function inspect( string $capability_id ): array {
+        $manifest = class_exists( 'CLAUTRON_Manifest_Registry' ) ? CLAUTRON_Manifest_Registry::get( $capability_id ) : null;
+        $installed_row = class_exists( 'CLAUTRON_Capability_Store' )
+            ? CLAUTRON_Capability_Store::find_by_capability_id( $capability_id )
+            : null;
+        $unmet = ( $manifest && class_exists( 'CLAUTRON_Manifest_Registry' ) )
+            ? CLAUTRON_Manifest_Registry::check_requirements( $manifest )
+            : [];
+        $declared_actions  = $manifest['actions'] ?? [];
+        $available_actions = array_values( array_unique( array_merge(
+            self::ALWAYS_AVAILABLE_ACTIONS,
+            array_intersect( $declared_actions, self::IMPLEMENTED_LIFECYCLE_ACTIONS )
+        ) ) );
+        return [
+            'installed'          => $installed_row !== null,
+            'installed_version'  => $installed_row->installed_version ?? null,
+            'available_version'  => $manifest['version'] ?? null,
+            'compatible'         => empty( $unmet ),
+            'status'             => $installed_row->status ?? 'not_installed',
+            'available_actions'  => $available_actions,
+            'unmet_requirements' => $unmet,
+        ];
+    }
     // ── Helpers ───────────────────────────────────────────────────────────────

clautron/trunk/includes/class-db.php

-              r3582869
+              r3784837
  *   3 — add last_error column to jobs table
  *   4 — add clautron_events time-series table
+ *   5 — add clautron_capabilities table (installed-instance state, separate
+ *       from the source/template manifest — see docs/schemas/capability_manifest.json)
  */
 class CLAUTRON_DB {
 …
         ) $charset;" );
+        // ── capabilities ──────────────────────────────────────────────────────
+        // Installed-instance state for a capability, separate from the
+        // source/template manifest (demo/capabilities/*.manifest.json) and
+        // from the generic blueprints table, which serves every blueprint
+        // whether or not it's a governed capability. One row per capability_id
+        // currently installed on this site.
+        dbDelta( "CREATE TABLE {$pfx}capabilities (
+            id                 BIGINT UNSIGNED  NOT NULL AUTO_INCREMENT,
+            capability_id      VARCHAR(191)     NOT NULL,
+            blueprint_id       BIGINT UNSIGNED  NOT NULL,
+            installed_version  VARCHAR(20)      NOT NULL DEFAULT 'unknown',
+            status             VARCHAR(20)      NOT NULL DEFAULT 'active',
+            reversibility      VARCHAR(10)      NOT NULL DEFAULT 'none',
+            installed_at       DATETIME         NOT NULL,
+            updated_at         DATETIME         NOT NULL,
+            PRIMARY KEY  (id),
+            UNIQUE KEY   capability_id (capability_id),
+            KEY          blueprint_id (blueprint_id)
+        ) $charset;" );
         // ── In-place migrations for existing installs ─────────────────────────
         // dbDelta reliably creates tables but does NOT add missing columns.
 …
+        }
+        // v5: backfill capabilities table for blueprints that were installed
+        // (compiled + active, with a capability_id) before this table existed.
+        // Preserves continuity — nothing about an already-installed capability
+        // changes on upgrade, it just becomes visible to the new inspect()/
+        // versioning machinery.
+        self::backfill_capabilities();
         update_option( 'clautron_db_version', CLAUTRON_DB_VERSION );
+    }
+    /**
+     * One-time backfill: for every active blueprint that already declares a
+     * capability_id but has no row yet in the capabilities table, insert one.
+     * Safe to call repeatedly — skips capability_ids that already have a row.
+     */
+    private static function backfill_capabilities(): void {
+        global $wpdb;
+        $existing_ids = $wpdb->get_col( $wpdb->prepare( 'SELECT capability_id FROM %i', self::capabilities() ) );
+        $rows = $wpdb->get_results( $wpdb->prepare(
+            'SELECT id, blueprint_json FROM %i WHERE status = %s',
+            self::blueprints(),
+            'active'
+        ) );
+        $now = current_time( 'mysql', true );
+        foreach ( $rows as $row ) {
+            $data = json_decode( $row->blueprint_json, true );
+            if ( ! is_array( $data ) || empty( $data['capability_id'] ) ) {
+                continue;
+            }
+            if ( in_array( $data['capability_id'], $existing_ids, true ) ) {
+                continue;
+            }
+            $manifest          = class_exists( 'CLAUTRON_Manifest_Registry' ) ? CLAUTRON_Manifest_Registry::get( $data['capability_id'] ) : null;
+            $installed_version = $manifest['version'] ?? 'unknown';
+            $reversibility     = $manifest['reversibility']['strategy'] ?? 'none';
+            $wpdb->insert(
+                self::capabilities(),
+                [
+                    'capability_id'     => $data['capability_id'],
+                    'blueprint_id'      => (int) $row->id,
+                    'installed_version' => $installed_version,
+                    'status'            => 'active',
+                    'reversibility'     => $reversibility,
+                    'installed_at'      => $now,
+                    'updated_at'        => $now,
+                ],
+                [ '%s', '%d', '%s', '%s', '%s', '%s', '%s' ]
+            );
+        }
+    }
 …
         global $wpdb;
         $pfx    = $wpdb->prefix . 'clautron_';
         $tables = [ 'events', 'jobs', 'ai_requests', 'conversations', 'execution_logs', 'workflows', 'versions', 'blueprints' ];
+        $tables = [ 'capabilities', 'events', 'jobs', 'ai_requests', 'conversations', 'execution_logs', 'workflows', 'versions', 'blueprints' ];
         foreach ( $tables as $t ) {
             $wpdb->query( $wpdb->prepare( 'DROP TABLE IF EXISTS %i', $pfx . $t ) );
 …
     public static function jobs(): string          { global $wpdb; return $wpdb->prefix . 'clautron_jobs'; }
     public static function events(): string        { global $wpdb; return $wpdb->prefix . 'clautron_events'; }
+    public static function capabilities(): string  { global $wpdb; return $wpdb->prefix . 'clautron_capabilities'; }
+}

clautron/trunk/includes/class-plugin.php

-              r3691441
+              r3784837
         CLAUTRON_Primitive_Redirect::register_all();
         CLAUTRON_Primitive_Cookie::register_all();
+        CLAUTRON_Primitive_Consent::register_all();
         CLAUTRON_Primitive_Language::register_all();
         CLAUTRON_Primitive_Request::register_all();
 …
         // ── 3. Boot job runner ───────────────────────────────────────────────
         CLAUTRON_Job_Runner::boot();
+        // ── 3b. Expose operations as WordPress Abilities ─────────────────────
+        CLAUTRON_Abilities::boot();
         // ── 4b. Boot runtime engine ──────────────────────────────────────────

clautron/trunk/includes/class-smoke-tester.php

-              r3582869
+              r3784837
  * Smoke Tester — verifies that a compiled blueprint is correctly wired into WordPress.
+ *
+ * Checks are lightweight WordPress-introspection only (no HTTP requests).
+ * Each check inspects the WordPress state that the compile-phase primitives
+ * should have set up: post types, taxonomies, meta boxes, columns, hooks, etc.
+ * Generic executor: each compile-phase structure node is checked by its own
+ * primitive's declared `verify` callable (CLAUTRON_Primitive_Registry). A
+ * primitive type with no `verify` declared lands in `unavailable`, not
+ * silently dropped — see the primitive's own file for its check, and
+ * CLAUTRON_Primitive_Registry::register()'s docblock for the `verify`
+ * contract. Part of the AICOM-Clautron Capability Contract v1.
  */
 class CLAUTRON_Smoke_Tester {
 …
      *   @type string[] $failed
      *   @type string[] $warnings
+     *   @type string[] $unavailable  Structures whose primitive type has no declared verify check.
      *   @type string   $summary
      * }
 …
         $row = CLAUTRON_Blueprint_Store::get( $blueprint_id );
         if ( ! $row ) {
             return self::result( [], [], [ "Blueprint {$blueprint_id} not found." ], 0, 0 );
+            return self::result( [], [], [ "Blueprint {$blueprint_id} not found." ], [] );
+        }
         $data = json_decode( $row->blueprint_json, true );
         if ( ! is_array( $data ) ) {
             return self::result( [], [], [ 'blueprint_json is not valid JSON.' ], 0, 0 );
+            return self::result( [], [], [ 'blueprint_json is not valid JSON.' ], [] );
+        }
         if ( $row->status !== 'active' ) {
             return self::result( [], [], [ "Blueprint is '{$row->status}', not active — compile it first." ], 0, 0 );
+            return self::result( [], [], [ "Blueprint is '{$row->status}', not active — compile it first." ], [] );
+        }
+        $passed   = [];
+        $failed   = [];
+        $warnings = [];
+        $passed      = [];
+        $failed      = [];
+        $warnings    = [];
+        $unavailable = [];
         // ── Check trigger ──────────────────────────────────────────────────────
+        // Not a primitive — the blueprint's own trigger field, checked directly.
         $trigger = $data['trigger'] ?? null;
         if ( $trigger ) {
 …
             $id     = $node['id'] ?? $type;
             switch ( $type ) {
+            $def = class_exists( 'CLAUTRON_Primitive_Registry' ) ? CLAUTRON_Primitive_Registry::get( $type ) : null;
+                case 'register_cpt': {
+                    $pt = $config['post_type'] ?? '';
+                    if ( $pt && get_post_type_object( $pt ) ) {
+                        $passed[] = "register_cpt:{$pt}";
+                    } elseif ( $pt ) {
+                        $failed[] = "register_cpt:{$pt} — post type not registered.";
+                    }
+                    break;
+                }
+            if ( ! $def ) {
+                $unavailable[] = "{$type}:{$id} — primitive type not registered.";
+                continue;
+            }
+                case 'register_taxonomy': {
+                    $tax = $config['taxonomy'] ?? '';
+                    if ( $tax && taxonomy_exists( $tax ) ) {
+                        $passed[] = "register_taxonomy:{$tax}";
+                    } elseif ( $tax ) {
+                        $failed[] = "register_taxonomy:{$tax} — taxonomy not registered.";
+                    }
+                    break;
+                }
+            if ( empty( $def['verify'] ) || ! is_callable( $def['verify'] ) ) {
+                $unavailable[] = "{$type}:{$id} — no verification declared for this primitive type.";
+                continue;
+            }
+                case 'register_meta': {
+                    $key = $config['meta_key'] ?? '';
+                    $pts = (array) ( $config['post_types'] ?? [ 'post' ] );
+                    if ( $key ) {
+                        $registered = registered_meta_key_exists( 'post', $key, $pts[0] ?? '' );
+                        if ( $registered ) {
+                            $passed[] = "register_meta:{$key}";
+                        } else {
+                            $warnings[] = "register_meta:{$key} — not found in registered meta (may still work via update_post_meta).";
+                        }
+                    }
+                    break;
+                }
+            $items = call_user_func( $def['verify'], $config );
+            foreach ( (array) $items as $item ) {
+                $label  = $item['label']  ?? "{$type}:{$id}";
+                $reason = $item['reason'] ?? null;
+                $line   = $reason ? "{$label} — {$reason}" : $label;
+                case 'add_metabox': {
+                    $mbid = $config['id'] ?? '';
+                    $pts  = (array) ( $config['post_types'] ?? [ 'post' ] );
+                    $pt   = $pts[0] ?? 'post';
+                    // Meta boxes are only registered in admin context.
+                    if ( ! is_admin() ) {
+                        $warnings[] = "add_metabox:{$mbid} — skipped (requires admin context; will work correctly on post edit screens).";
+                switch ( $item['status'] ?? 'warning' ) {
+                    case 'passed':
+                        $passed[] = $line;
                         break;
+                    }
+                    $hook_name = 'add_meta_boxes_' . $pt;
+                    do_action( $hook_name, null );
+                    do_action( 'add_meta_boxes', $pt, null );
+                    global $wp_meta_boxes;
+                    $found = false;
+                    foreach ( $wp_meta_boxes[ $pt ] ?? [] as $context ) {
+                        foreach ( $context as $priority ) {
+                            if ( isset( $priority[ $mbid ] ) ) {
+                                $found = true;
+                                break 2;
+                            }
+                        }
+                    }
+                    if ( $found ) {
+                        $passed[] = "add_metabox:{$mbid}";
+                    } else {
+                        $failed[] = "add_metabox:{$mbid} — not found in wp_meta_boxes for post type '{$pt}'.";
+                    }
+                    break;
+                }
+                case 'add_admin_column': {
+                    $pts = (array) ( $config['post_types'] ?? [] );
+                    foreach ( $pts as $pt ) {
+                        $filter = "manage_{$pt}_posts_columns";
+                        if ( has_filter( $filter ) ) {
+                            $passed[] = "add_admin_column:{$pt}";
+                        } else {
+                            $failed[] = "add_admin_column:{$pt} — filter '{$filter}' not hooked.";
+                        }
+                    }
+                    break;
+                }
+                case 'inject_wp_head': {
+                    $priority = (int) ( $config['priority'] ?? 5 );
+                    if ( has_action( 'wp_head' ) ) {
+                        $passed[] = "inject_wp_head (priority:{$priority})";
+                    } else {
+                        $failed[] = 'inject_wp_head — no actions registered on wp_head.';
+                    }
+                    break;
+                }
+                case 'inject_wp_footer': {
+                    if ( has_action( 'wp_footer' ) ) {
+                        $passed[] = 'inject_wp_footer';
+                    } else {
+                        $failed[] = 'inject_wp_footer — no actions registered on wp_footer.';
+                    }
+                    break;
+                }
+                case 'register_rest_route': {
+                    $route = $config['route'] ?? '';
+                    if ( $route ) {
+                        $routes    = rest_get_server()->get_routes();
+                        $full_path = '/clautron/v1/' . ltrim( $route, '/' );
+                        if ( isset( $routes[ $full_path ] ) ) {
+                            $passed[] = "register_rest_route:{$route}";
+                        } else {
+                            $warnings[] = "register_rest_route:{$route} — not found in registered routes (REST server may not be initialized yet).";
+                        }
+                    }
+                    break;
+                }
+                case 'add_row_action': {
+                    $pts = (array) ( $config['post_types'] ?? [] );
+                    foreach ( $pts as $pt ) {
+                        $filter = "post_row_actions";
+                        if ( has_filter( $filter ) || has_filter( "{$pt}_row_actions" ) ) {
+                            $passed[] = "add_row_action:{$pt}";
+                        } else {
+                            $warnings[] = "add_row_action:{$pt} — row action filter not detected (may still work).";
+                        }
+                    }
+                    break;
+                }
+                case 'gate_publish': {
+                    if ( has_action( 'admin_notices' ) ) {
+                        $passed[] = 'gate_publish';
+                    } else {
+                        $warnings[] = 'gate_publish — admin_notices hook not detected in current context.';
+                    }
+                    break;
+                    case 'failed':
+                        $failed[] = $line;
+                        break;
+                    default:
+                        $warnings[] = $line;
+                        break;
+                }
+            }
+        }
+        $total = count( $passed ) + count( $failed );
+        return self::result( $passed, $failed, $warnings, count( $passed ), $total );
+        return self::result( $passed, $failed, $warnings, $unavailable );
+    }
 …
         array $failed,
         array $warnings,
+        int   $pass_count,
+        int   $total
+        array $unavailable
     ): array {
+        $pass_count = count( $passed );
+        $total      = $pass_count + count( $failed );
         if ( $total === 0 ) {
             $summary = 'No checkable structures found.';
+            $summary = empty( $unavailable ) ? 'No checkable structures found.' : 'No checks could run.';
         } elseif ( empty( $failed ) ) {
             $summary = "All checks passed ({$pass_count}/{$total}).";
 …
+        }
+        if ( ! empty( $unavailable ) ) {
+            $summary .= ' ' . count( $unavailable ) . ' structure(s) have no verification declared.';
+        }
         return [
+            'passed'   => $passed,
+            'failed'   => $failed,
+            'warnings' => $warnings,
+            'summary'  => $summary,
+            'passed'      => $passed,
+            'failed'      => $failed,
+            'warnings'    => $warnings,
+            'unavailable' => $unavailable,
+            'summary'     => $summary,
         ];
+    }

clautron/trunk/includes/primitives/class-primitive-ai.php

r3691441	r3784837
27	27	'category' => 'ai',
28	28	'phase' => 'runtime',
	29	'effects' => [ 'external_requests' ],
29	30	'label' => 'AI Generate',
30	31	'description' => 'Generate text with the WordPress AI Client (site-configured provider) and store the result in a context variable. Use for excerpts, meta descriptions, alt text, translations, summaries. Prompt supports {{variable}} placeholders. Output is plain text only.',

clautron/trunk/includes/primitives/class-primitive-comments.php

-              r3691441
+              r3784837
             'category'    => 'comments',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Query Comments',
             'description' => 'Query WordPress comments with filters. Returns array of comments (id, post_id, author, author_email, content, status, date, parent_id) stored in a context variable.',
 …
             'category'    => 'comments',
             'phase'       => 'runtime',
+            // approve: core emails the post author (wp_set_comment_status → wp_new_comment_notify_postauthor).
+            'effects'     => static fn( array $c ): array => [ 'trash' => [ 'writes_database', 'deletes_data' ], 'approve' => [ 'writes_database', 'external_requests' ] ][ $c['status'] ?? '' ] ?? [ 'writes_database' ],
+            'effects_max' => [ 'writes_database', 'deletes_data', 'external_requests' ],
             'label'       => 'Moderate Comment',
             'description' => 'Change a comment\'s moderation status. Allowed statuses: approve, hold, spam, trash. Hard deletion is intentionally not supported.',
 …
             'category'    => 'comments',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database' ],
             'label'       => 'Create Comment',
             'description' => 'Insert a comment (or a threaded reply via parent_id) on a post. Content supports {{variable}} placeholders.',

clautron/trunk/includes/primitives/class-primitive-cookie.php

-              r3691441
+              r3784837
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
+            'reversible'  => false,
             'safe'        => false,
             'label'       => 'Write Cookie',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Read Cookie',
             'description' => 'Read a clautron_-prefixed cookie into a workflow variable. Resolves to null if the cookie is not set.',

clautron/trunk/includes/primitives/class-primitive-data.php

-              r3582869
+              r3784837
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Read Post Field',
             'description' => 'Read a field from the current post (ID, title, content, status, author, etc.) and store it in a variable.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database' ],
             'label'       => 'Write Meta',
             'description' => 'Write a meta value to a post, user, or term.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Read Meta',
             'description' => 'Read a meta value from a post, user, or term and store it in a variable.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database' ],
             'safe'        => false,
             'label'       => 'Write Option',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Read Option',
             'description' => 'Read a WordPress option and store it in a variable.',
 …
             'category'    => 'wordpress',
             'phase'       => 'compile',
+            'effects'     => [ 'writes_database' ],
             'label'       => 'Gate Publish',
             'description' => 'Block or warn when publishing a post that fails completeness checks.',
 …
                     echo '</p></div>';
                 } );
+            },
+            'verify' => static function ( array $config ): array {
+                if ( has_action( 'admin_notices' ) ) {
+                    return [ [ 'status' => 'passed', 'label' => 'gate_publish' ] ];
+                }
+                return [ [ 'status' => 'warning', 'label' => 'gate_publish', 'reason' => 'admin_notices hook not detected in current context.' ] ];
             },
         ] );
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database' ],
             'label'       => 'Check Fields Completeness',
             'description' => 'Evaluate a list of post fields and calculate a completeness score (0-100). Saves the score to a meta key and an output variable.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Run Report',
             'description' => 'Execute a saved report blueprint and store its result rows in a context variable. Use with foreach_query_result to process each row.',

clautron/trunk/includes/primitives/class-primitive-elementor.php

-              r3592659
+              r3784837
             'category'    => 'elementor',
             'phase'       => 'compile',
+            'effects'     => [ 'executes_code' ],
             'label'       => 'Elementor Widget',
             'description' => 'Create a custom Elementor widget with content controls, style tab sections, and a server-rendered HTML template. Appears under the "Clautron" category in the Elementor panel.',
 …
             'category'    => 'wordpress',
             'phase'       => 'compile',
+            'effects'     => [ 'executes_code' ],
             'label'       => 'WordPress Widget',
             'description' => 'Register a native WordPress sidebar widget (WP_Widget) usable in Appearance > Widgets and any theme sidebar. Supports text, textarea, number, url, color, checkbox, and select controls. Use {{key}} (escaped), {{{key}}} (HTML), {{key.url}} (URL), and {{#if key}}...{{/if}} in the template.',

clautron/trunk/includes/primitives/class-primitive-email.php

-              r3691441
+              r3784837
             'category'    => 'communication',
             'phase'       => 'runtime',
+            'effects'     => [ 'external_requests' ],
             'label'       => 'Send Email',
             'description' => 'Send an email via wp_mail(). All fields support {{variable}} template syntax.',
 …
             'category'    => 'communication',
             'phase'       => 'runtime',
+            'effects'     => [ 'external_requests' ],
             'label'       => 'Notify User',
             'description' => 'Send a notification email to a WordPress user by their user ID. Subject and body support {{variable}} template syntax.',
 …
             'category'    => 'communication',
             'phase'       => 'compile',
+            'effects'     => [ 'external_requests' ],
             'safe'        => false,
             'label'       => 'Configure SMTP',

clautron/trunk/includes/primitives/class-primitive-events.php

-              r3691441
+              r3784837
             'category'    => 'events',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database' ],
             'label'       => 'Track Event',
             'description' => 'Write one event to the clautron_events time-series store. Use this inside any blueprint trigger to record that something happened (a pageview, a login failure, an order, a cron run, etc.).',
 …
             'category'    => 'events',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Query Events',
             'description' => 'Read raw event rows from the clautron_events store. Results are stored in output_variable for use in subsequent primitives (foreach_query_result, send_email, etc.).',
 …
             'category'    => 'events',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Aggregate Events',
             'description' => 'Group and aggregate event data: total counts, sums, averages, grouped by time period or object. Returns an array of {period, value} rows in output_variable.',
 …
             'category'    => 'events',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database', 'deletes_data' ],
             'label'       => 'Purge Events',
             'description' => 'Delete old events for retention management. Use inside a recurring job (e.g. weekly). Returns the count of deleted rows in output_variable.',
 …
             'category'    => 'events',
             'phase'       => 'compile',
+            'effects'     => [ 'writes_database' ],
             'safe'        => false,
             'label'       => 'Log All Outgoing Email',
 …
             'category'    => 'events',
             'phase'       => 'compile',
+            'effects'     => [ 'writes_database' ],
             'safe'        => false,
             'label'       => 'Log Site Activity',

clautron/trunk/includes/primitives/class-primitive-filter.php

r3691441	r3784837
33	33	'category' => 'frontend',
34	34	'phase' => 'compile',
	35	'effects' => [],
35	36	'label' => 'Filter Query by Request Parameters',
36	37	'description' => 'Restrict frontend main queries (archives, search, home) using one or more filter rules read from GET parameters: taxonomy facets, exact meta match, or numeric meta range. Built for shop/archive filter sidebars (category, in-stock, price range). Never touches wp-admin or REST requests.',

clautron/trunk/includes/primitives/class-primitive-frontend.php

-              r3691441
+              r3784837
             'category'    => 'frontend',
             'phase'       => 'compile',
+            'effects'     => [ 'executes_code' ],
             'label'       => 'Inject into <head>',
             'description' => 'Output HTML into wp_head on singular post/page views. Supports {{post.field}}, {{site.field}}, and {{_meta_key}} placeholders. Optionally outputs a Schema.org JSON-LD block via json_ld config.',
 …
                 }, $priority );
             },
+            'verify' => static function ( array $config ): array {
+                $priority = (int) ( $config['priority'] ?? 5 );
+                if ( has_action( 'wp_head' ) ) {
+                    return [ [ 'status' => 'passed', 'label' => "inject_wp_head (priority:{$priority})" ] ];
+                }
+                return [ [ 'status' => 'failed', 'label' => 'inject_wp_head', 'reason' => 'no actions registered on wp_head.' ] ];
+            },
         ] );
+    }
 …
             'category'    => 'frontend',
             'phase'       => 'compile',
+            'effects'     => [ 'executes_code' ],
             'label'       => 'Inject before </body>',
             'description' => 'Output HTML into wp_footer. Same {{variable}} resolution as inject_wp_head (post.*, site.*, meta keys). Leave post_types empty to render on every frontend page (banners, popups, share widgets) — set it to restrict to singular views of those post types, where {{post.*}}/meta-key tokens resolve against the viewed post. Set suppress_if_cookie to hide the whole block once a clautron_-prefixed cookie (e.g. one set by write_cookie) has any non-empty value — the standard pattern for "don\'t show this again after accept/dismiss".',
 …
                 }, $priority );
             },
+            'verify' => static function ( array $config ): array {
+                if ( has_action( 'wp_footer' ) ) {
+                    return [ [ 'status' => 'passed', 'label' => 'inject_wp_footer' ] ];
+                }
+                return [ [ 'status' => 'failed', 'label' => 'inject_wp_footer', 'reason' => 'no actions registered on wp_footer.' ] ];
+            },
         ] );
+    }
 …
             'category'    => 'frontend',
             'phase'       => 'compile',
+            'effects'     => [ 'executes_code' ],
             'label'       => 'Register Shortcode',
             'description' => 'Register a WordPress [shortcode] rendered from an HTML template. Attributes become template tokens: {{attr}} escaped text, {{{attr}}} sanitized HTML, {{attr.url}} URL, {{#if attr}}...{{/if}} conditionals. Enclosed content is available as {{{content}}}.',
 …
             'category'    => 'frontend',
             'phase'       => 'compile',
+            'effects'     => [],
             'label'       => 'Enqueue Registered Asset',
             'description' => 'Load CSS/JS assets that are ALREADY registered on the site (by core, the theme, or plugins) onto frontend pages, by handle. Never loads external URLs or new code — only activates assets the site already ships (e.g. dashicons, wp-block-library, swiper, theme handles). Use widget/shortcode templates with the classes those assets provide.',

clautron/trunk/includes/primitives/class-primitive-http.php

-              r3582869
+              r3784837
             'category'    => 'http',
             'phase'       => 'runtime',
+            'effects'     => [ 'external_requests' ],
+            'safe'        => false,
             'label'       => 'HTTP Request',
             'description' => 'Send an HTTP request (GET, POST, PUT, DELETE, PATCH) and store the response body and status code in context variables.',
 …
             'category'    => 'http',
             'phase'       => 'runtime',
+            'effects'     => [ 'external_requests', 'writes_database' ], // SimplePie caches the feed in transients
+            'safe'        => false,
             'label'       => 'Fetch RSS/Atom Feed',
             'description' => 'Fetch an RSS or Atom feed and store items as an array of {title, link, description, pubdate} objects.',
-            'safe'        => true,
             'schema'      => [
                 'url'             => [ 'type' => 'string',  'required' => true, 'description' => 'Feed URL. Supports {{variable}}.' ],
 …
             'category'    => 'http',
             'phase'       => 'runtime',
+            'effects'     => [ 'external_requests' ],
             'label'       => 'Send Webhook',
             'description' => 'POST a JSON payload to a webhook URL. Supports {{variable}} in URL and payload values.',

clautron/trunk/includes/primitives/class-primitive-language.php

r3691441	r3784837
29	29	'category' => 'frontend',
30	30	'phase' => 'compile',
	31	'effects' => [],
31	32	'label' => 'Filter Query by Language',
32	33	'description' => 'Restrict frontend main queries (archives, search, home, singular) to posts tagged with one term of a language taxonomy. Language is resolved from a URL query var, falling back to a cookie, falling back to a configured default. Never touches wp-admin or REST requests.',

clautron/trunk/includes/primitives/class-primitive-logic.php

-              r3582869
+              r3784837
             'category'    => 'logic',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'If / Else',
             'description' => 'Evaluate a condition. Execute pass_branch nodes if true, fail_branch nodes if false.',
 …
             'category'    => 'logic',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Stop Execution',
             'description' => 'Halt workflow execution immediately. No further nodes will run.',
 …
             'category'    => 'logic',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Set Variable',
             'description' => 'Assign a literal or resolved value to a context variable for use in later nodes.',
 …
             'category'    => 'logic',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'For Each Row',
             'description' => 'Iterate over rows from a query result stored in a context variable. Each row\'s columns become available as {{row.column_name}} for the body nodes.',
 …
             'category'    => 'logic',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Switch / Case',
             'description' => 'Evaluate a value against multiple cases and execute the matching branch. Falls through to default_branch if no case matches.',

clautron/trunk/includes/primitives/class-primitive-media.php

-              r3691441
+              r3784837
             'category'    => 'media',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database', 'writes_files', 'external_requests' ],
             'label'       => 'Create Media from URL',
             'description' => 'Download an image from a URL and add it to the WordPress media library. Returns the new attachment ID.',
 …
             'category'    => 'media',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database' ],
             'label'       => 'Set Featured Image',
             'description' => 'Set the featured image (thumbnail) of a post to a given attachment ID.',
 …
             'category'    => 'media',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Get Image URL',
             'description' => 'Get the URL of an attachment image at a given size.',
 …
             'category'    => 'media',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database', 'writes_files' ],
             'safe'        => false,
             'label'       => 'Handle File Upload',
 …
             'handler' => static function ( array $config, CLAUTRON_Workflow_Context $ctx ): int|false {
                 $out_var = $config['output_variable'] ?? 'uploaded_attachment_id';
                 $fail    = static function () use ( $ctx, $out_var ): false {
+                $fail    = static function () use ( $ctx, $out_var ): bool {
                     if ( $out_var ) {
                         $ctx->write_variable( $out_var, false );

clautron/trunk/includes/primitives/class-primitive-query.php

-              r3691441
+              r3784837
             'category'    => 'query',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Query Posts',
             'description' => 'Query WordPress posts with flexible filters. Returns array of post objects (id, title, content, excerpt, status, type, author, date, permalink) stored in a context variable.',
 …
             'category'    => 'query',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Get Post',
             'description' => 'Fetch a single post by ID and store its fields in a context variable.',
 …
             'category'    => 'query',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Count Posts',
             'description' => 'Count posts matching given criteria. Writes integer to output_variable.',
 …
             'category'    => 'query',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Query Users',
             'description' => 'Query WordPress users with flexible filters. Returns array of user objects.',
 …
             'category'    => 'query',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Get User',
             'description' => 'Fetch a single user by ID and store their data in a context variable.',
 …
             'category'    => 'query',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Query Terms',
             'description' => 'Query taxonomy terms. Returns array of term objects.',

clautron/trunk/includes/primitives/class-primitive-redirect.php

-              r3691441
+              r3784837
             'category'    => 'frontend',
             'phase'       => 'compile',
+            'effects'     => [],
+            // Browsers cache permanent redirects indefinitely; removing the rule doesn't reach them.
+            'reversible'  => static fn( array $c ): bool => ! in_array( (int) ( $c['status'] ?? 301 ), [ 301, 308 ], true ),
             'label'       => 'Redirect URL',
             'description' => 'Redirect requests from one path to another. Refuses redirects that would break wp-admin/login/REST access or create a loop.',

clautron/trunk/includes/primitives/class-primitive-request.php

r3691441	r3784837
25	25	'category' => 'data',
26	26	'phase' => 'runtime',
	27	'effects' => [],
27	28	'safe' => false,
28	29	'label' => 'Read Request Parameter',

clautron/trunk/includes/primitives/class-primitive-security.php

-              r3691441
+              r3784837
 /**
  * Security Primitives — abuse throttling.
+ * Security Primitives — abuse throttling and information-disclosure hardening.
+ *
  * Registered primitives:
+ *   - rate_limit_check   Fixed-window counter (transient-backed) keyed by an
+ *                         identifier (defaults to client IP). Use as a
+ *                         condition to gate login/comment/form actions.
+ *   - rate_limit_check          Fixed-window counter (transient-backed) keyed by an
+ *                                identifier (defaults to client IP). Use as a
+ *                                condition to gate login/comment/form actions.
+ *   - harden_user_enumeration   Stop anonymous visitors from discovering usernames
+ *                                (REST users endpoint, author archives, oEmbed
+ *                                author, login error messages).
+ *   - security_headers          Send Referrer-Policy, X-Content-Type-Options,
+ *                                X-Frame-Options and Permissions-Policy on
+ *                                frontend responses, and HSTS on HTTPS (opt-in).
+ *   - hide_wp_version           Remove generator tags, mask the WordPress
+ *                                version in core asset URLs and, opt-in,
+ *                                delete readme.html.
+ *
+ * The hardening primitives hook named static methods rather than closures
+ * wherever the callback needs no config: add_filter() with the same callable
+ * and priority is idempotent, so two blueprints declaring the same primitive
+ * do not stack duplicate callbacks, and verify can check the exact callable
+ * with has_filter() instead of "something is hooked here".
  */
 class CLAUTRON_Primitive_Security extends CLAUTRON_Abstract_Primitive {
+    /** Login error codes that reveal whether a username/email exists. */
+    private const LOGIN_ENUMERATION_CODES = [ 'invalid_username', 'invalid_email', 'incorrect_password' ];
+    private const REFERRER_POLICIES = [
+        'no-referrer', 'no-referrer-when-downgrade', 'origin', 'origin-when-cross-origin',
+        'same-origin', 'strict-origin', 'strict-origin-when-cross-origin', 'unsafe-url',
+    ];
+    private const FRAME_OPTIONS = [ 'SAMEORIGIN', 'DENY' ];
+    private const PERMISSIONS_POLICY = 'camera=(), microphone=()';
+    /** WordPress version readme.html was last removed for (see remove_core_readme()). */
+    private const README_OPTION = 'clautron_readme_removed_for';
+    /** Headers merged from every active security_headers structure; the first one to set a header wins. */
+    private static array $security_headers = [];
     public static function register_all(): void {
         self::register_rate_limit_check();
+        self::register_harden_user_enumeration();
+        self::register_security_headers();
+        self::register_hide_wp_version();
+    }
 …
             'category'    => 'security',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database' ],
             'safe'        => false,
             'label'       => 'Rate Limit Check',
 …
         return false;
+    }
+    // ── harden_user_enumeration ──────────────────────────────────────────────
+    private static function register_harden_user_enumeration(): void {
+        CLAUTRON_Primitive_Registry::register( 'harden_user_enumeration', [
+            'category'    => 'security',
+            'phase'       => 'compile',
+            'effects'     => [],
+            'safe'        => false,
+            'label'       => 'Harden User Enumeration',
+            'description' => 'Stop anonymous visitors from discovering usernames. Blocks the /wp/v2/users REST endpoints for logged-out requests (logged-in users, including the block editor author picker, keep working); returns 404 for every author archive (?author=N, ?author_name=, /author/slug/ and their feeds), drops the users sitemap and points author links at the homepage; replaces the post author in oEmbed responses with the site name; and gives the same login error for an unknown username and a wrong password. Each part can be switched off individually.',
+            'schema'      => [
+                'block_rest_users'        => [ 'type' => 'boolean', 'default' => true, 'description' => '401 on every /wp/v2/users route for logged-out requests.' ],
+                'disable_author_archives' => [ 'type' => 'boolean', 'default' => true, 'description' => '404 on all author archives for everyone, remove the users sitemap, point author links to the homepage.' ],
+                'strip_oembed_author'     => [ 'type' => 'boolean', 'default' => true, 'description' => 'oEmbed responses show the site name and homepage instead of the post author.' ],
+                'generic_login_errors'    => [ 'type' => 'boolean', 'default' => true, 'description' => 'Same login error whether the username/email is unknown or the password is wrong.' ],
+            ],
+            'examples'    => [
+                [],
+                [ 'disable_author_archives' => false ],
+            ],
+            'handler' => static function ( array $config ): void {
+                if ( $config['block_rest_users'] ?? true ) {
+                    add_filter( 'rest_request_before_callbacks', [ self::class, 'gate_rest_users' ], 10, 3 );
+                }
+                if ( $config['disable_author_archives'] ?? true ) {
+                    add_filter( 'request', [ self::class, 'block_author_request' ] );
+                    add_filter( 'wp_sitemaps_add_provider', [ self::class, 'drop_users_sitemap' ], 10, 2 );
+                    add_filter( 'author_link', [ self::class, 'neutral_author_link' ] );
+                }
+                if ( $config['strip_oembed_author'] ?? true ) {
+                    add_filter( 'oembed_response_data', [ self::class, 'neutral_oembed_author' ] );
+                }
+                if ( $config['generic_login_errors'] ?? true ) {
+                    // After every core authenticator (20) and the spam check (99).
+                    add_filter( 'authenticate', [ self::class, 'generic_login_error' ], 100 );
+                }
+            },
+            'verify' => static function ( array $config ): array {
+                $items  = [];
+                $checks = [
+                    'block_rest_users'        => [ 'rest_request_before_callbacks', 'gate_rest_users' ],
+                    'disable_author_archives' => [ 'request', 'block_author_request' ],
+                    'strip_oembed_author'     => [ 'oembed_response_data', 'neutral_oembed_author' ],
+                    'generic_login_errors'    => [ 'authenticate', 'generic_login_error' ],
+                ];
+                foreach ( $checks as $option => [ $hook, $method ] ) {
+                    if ( ! ( $config[ $option ] ?? true ) ) {
+                        continue;
+                    }
+                    $items[] = false !== has_filter( $hook, [ self::class, $method ] )
+                        ? [ 'status' => 'passed', 'label' => "harden_user_enumeration:{$option}" ]
+                        : [ 'status' => 'failed', 'label' => "harden_user_enumeration:{$option}", 'reason' => "not hooked on {$hook}." ];
+                }
+                if ( $config['block_rest_users'] ?? true ) {
+                    $status  = self::anonymous_rest_status( '/wp/v2/users' );
+                    $items[] = in_array( $status, [ 401, 403 ], true )
+                        ? [ 'status' => 'passed', 'label' => "anonymous GET /wp/v2/users → {$status}" ]
+                        : [ 'status' => 'failed', 'label' => 'anonymous GET /wp/v2/users', 'reason' => "expected 401, got {$status}." ];
+                }
+                if ( $config['disable_author_archives'] ?? true ) {
+                    $vars    = self::author_query_vars( [ 'author' => '1' ], false );
+                    $items[] = ( $vars['error'] ?? '' ) === '404'
+                        ? [ 'status' => 'passed', 'label' => '?author=1 resolves to 404' ]
+                        : [ 'status' => 'failed', 'label' => '?author=1', 'reason' => 'author query was not turned into a 404.' ];
+                }
+                return $items;
+            },
+        ] );
+    }
+    /**
+     * rest_request_before_callbacks: refuse every route served by the core
+     * users controller to logged-out requests.
+     *
+     * Keyed on the controller that matched, not on the URL: WordPress matches
+     * routes case-insensitively (/wp/v2/USERS works) and also accepts
+     * ?rest_route=, so a path check would have to replicate the router to be
+     * airtight. Whatever spelling reached the users controller is caught here.
+     */
+    public static function gate_rest_users( mixed $response, array $handler, WP_REST_Request $request ): mixed {
+        $callback = $handler['callback'] ?? null;
+        if ( ! is_array( $callback ) || ! ( $callback[0] ?? null ) instanceof WP_REST_Users_Controller ) {
+            return $response;
+        }
+        if ( is_user_logged_in() ) {
+            return $response;
+        }
+        return new WP_Error(
+            'rest_forbidden',
+            __( 'Sorry, you are not allowed to do that.', 'clautron' ),
+            [ 'status' => rest_authorization_required_code() ]
+        );
+    }
+    /** request filter: wiring for author_query_vars(). */
+    public static function block_author_request( array $query_vars ): array {
+        return self::author_query_vars( $query_vars, is_admin() );
+    }
+    /**
+     * Replace any author-archive query with a plain 404. Public for unit
+     * testing (see CLAUTRON_Primitive_WordPress::build_cpt_args()).
+     *
+     * Runs on `request`, before WP_Query exists, so every way of asking for an
+     * author archive is covered by one check: ?author=N, ?author_name=slug,
+     * /author/slug/ (rewrite sets author_name) and their /feed/ variants.
+     * Blocking only the canonical redirect is not enough: an author without
+     * published posts gets no redirect, but the archive still prints the slug
+     * in <title> and body_class.
+     *
+     * Left alone:
+     *   - wp-admin, because edit.php?author=N calls wp() and goes through this
+     *     same filter to filter the posts list;
+     *   - REST requests, because /wp-json/wp/v2/posts?author=N is a legitimate
+     *     filter and `author` is a public query var.
+     */
+    public static function author_query_vars( array $query_vars, bool $in_admin ): array {
+        if ( $in_admin || isset( $query_vars['rest_route'] ) ) {
+            return $query_vars;
+        }
+        if ( empty( $query_vars['author'] ) && empty( $query_vars['author_name'] ) ) {
+            return $query_vars;
+        }
+        // Same shape WP::parse_request() produces for an unmatched URL, so
+        // WP::send_headers() sends the 404 status and nocache headers itself.
+        return [ 'error' => '404' ];
+    }
+    /** wp_sitemaps_add_provider: the users sitemap only lists author archive URLs. */
+    public static function drop_users_sitemap( mixed $provider, string $name ): mixed {
+        return 'users' === $name ? false : $provider;
+    }
+    /** author_link: author archives are gone, and the link itself carries the slug. */
+    public static function neutral_author_link(): string {
+        return home_url( '/' );
+    }
+    /**
+     * oembed_response_data: use the values core itself falls back to when a
+     * post has no author, instead of display_name + author archive URL.
+     */
+    public static function neutral_oembed_author( array $data ): array {
+        if ( isset( $data['author_name'] ) || isset( $data['author_url'] ) ) {
+            $data['author_name'] = get_bloginfo( 'name' );
+            $data['author_url']  = get_home_url();
+        }
+        return $data;
+    }
+    /**
+     * authenticate: collapse "unknown username", "unknown email" and "wrong
+     * password" into one error.
+     *
+     * Reuses core's own 'invalidcombo' code: it is already in wp-login.php's
+     * shake list, and it keeps wp-login.php from pre-filling the username
+     * field only on a wrong password, which would otherwise leak the same
+     * information through the form instead of the message.
+     */
+    public static function generic_login_error( mixed $user ): mixed {
+        if ( ! is_wp_error( $user ) || ! array_intersect( $user->get_error_codes(), self::LOGIN_ENUMERATION_CODES ) ) {
+            return $user;
+        }
+        return new WP_Error(
+            'invalidcombo',
+            __( '<strong>Error:</strong> The username, email address or password is incorrect.', 'clautron' )
+        );
+    }
+    /** Dispatch a GET as a logged-out visitor and return the HTTP status. */
+    private static function anonymous_rest_status( string $route ): int {
+        $previous_user = get_current_user_id();
+        wp_set_current_user( 0 );
+        try {
+            return rest_do_request( new WP_REST_Request( 'GET', $route ) )->get_status();
+        } finally {
+            wp_set_current_user( $previous_user );
+        }
+    }
+    // ── security_headers ─────────────────────────────────────────────────────
+    private static function register_security_headers(): void {
+        CLAUTRON_Primitive_Registry::register( 'security_headers', [
+            'category'    => 'security',
+            'phase'       => 'compile',
+            'effects'     => [],
+            // Browsers keep honouring HSTS for max-age after the header stops.
+            'reversible'  => static fn( array $c ): bool => (int) ( $c['hsts_max_age'] ?? 0 ) <= 0,
+            'safe'        => false,
+            'label'       => 'Security Headers',
+            'description' => 'Send Referrer-Policy, X-Content-Type-Options, X-Frame-Options and Permissions-Policy on frontend responses, plus Strict-Transport-Security (HSTS) on HTTPS when opted in. A header already set by another plugin through wp_headers is left as is. Headers are sent from PHP, so pages served straight from a page cache or CDN without running WordPress will not carry them; verify loads the homepage to detect that.',
+            'schema'      => [
+                'referrer_policy'         => [ 'type' => 'string',  'default' => 'strict-origin-when-cross-origin', 'description' => 'Any standard Referrer-Policy value. Empty = do not send. strict-origin-when-cross-origin matches what WordPress core sends in wp-admin; no-referrer breaks YouTube embeds and referral analytics.' ],
+                'content_type_options'    => [ 'type' => 'boolean', 'default' => true, 'description' => 'Send X-Content-Type-Options: nosniff.' ],
+                'frame_options'           => [ 'type' => 'string',  'default' => 'SAMEORIGIN', 'description' => 'SAMEORIGIN, DENY, or empty to not send. SAMEORIGIN keeps the Customizer and page-builder previews working.' ],
+                'permissions_policy'      => [ 'type' => 'string',  'default' => self::PERMISSIONS_POLICY, 'description' => 'Permissions-Policy value, e.g. "camera=(), microphone=(), geolocation=(self)". Empty = do not send; an invalid value is not sent. The default turns off camera and microphone only: blocking geolocation would break store/branch locators, and payment would break Apple Pay / Google Pay buttons.' ],
+                'hsts_max_age'            => [ 'type' => 'integer', 'default' => 0, 'description' => 'Opt-in Strict-Transport-Security max-age in seconds (31536000 = one year). 0 = do not send. Only sent over HTTPS. Browsers then refuse plain HTTP for that long and deactivating does not undo it, so turn it on only when the whole site works over HTTPS.' ],
+                'hsts_include_subdomains' => [ 'type' => 'boolean', 'default' => false, 'description' => 'Add includeSubDomains to HSTS. Only when every subdomain serves HTTPS.' ],
+            ],
+            'examples'    => [
+                [],
+                [ 'permissions_policy' => 'camera=(), microphone=(), geolocation=(self)', 'hsts_max_age' => 31536000 ],
+            ],
+            'handler' => static function ( array $config ): void {
+                $headers = self::build_security_headers( $config );
+                if ( ! $headers ) {
+                    return;
+                }
+                self::$security_headers = self::merge_headers( self::$security_headers, $headers );
+                add_filter( 'wp_headers', [ self::class, 'send_security_headers' ] );
+            },
+            'verify' => static function ( array $config ): array {
+                $expected = self::build_security_headers( $config );
+                if ( ! $expected ) {
+                    return [];
+                }
+                if ( false === has_filter( 'wp_headers', [ self::class, 'send_security_headers' ] ) ) {
+                    return [ [ 'status' => 'failed', 'label' => 'security_headers', 'reason' => 'not hooked on wp_headers.' ] ];
+                }
+                $items = [];
+                foreach ( $expected as $name => $value ) {
+                    if ( ( self::$security_headers[ $name ] ?? null ) !== $value ) {
+                        $items[] = [ 'status' => 'warning', 'label' => "security_headers:{$name}", 'reason' => 'another security_headers capability already sets it to "' . ( self::$security_headers[ $name ] ?? '' ) . '"; the first one wins.' ];
+                    }
+                }
+                $https = 'https' === wp_parse_url( home_url(), PHP_URL_SCHEME );
+                if ( isset( $expected['Strict-Transport-Security'] ) && ! $https ) {
+                    $items[] = [ 'status' => 'warning', 'label' => 'security_headers:Strict-Transport-Security', 'reason' => 'HSTS is only sent over HTTPS and this site\'s address is http://.' ];
+                    unset( $expected['Strict-Transport-Security'] );
+                }
+                $response = wp_remote_get( home_url( '/' ), [ 'timeout' => 5, 'redirection' => 3 ] );
+                if ( is_wp_error( $response ) ) {
+                    $items[] = [ 'status' => 'warning', 'label' => 'security_headers:live', 'reason' => 'could not load the homepage to confirm the headers reach visitors: ' . $response->get_error_message() ];
+                    return $items;
+                }
+                foreach ( $expected as $name => $value ) {
+                    $items[] = '' !== wp_remote_retrieve_header( $response, $name )
+                        ? [ 'status' => 'passed', 'label' => "{$name} on homepage" ]
+                        : [ 'status' => 'warning', 'label' => "{$name} on homepage", 'reason' => 'set by WordPress but missing from the live response; a page cache, CDN or proxy is serving the page without PHP or stripping the header. Set it at that layer too.' ];
+                }
+                return $items;
+            },
+        ] );
+    }
+    /**
+     * wp_headers: everything active security_headers structures asked for.
+     * One named callback (not a closure per structure) so verify can check
+     * that this primitive, not just any plugin, is hooked.
+     */
+    public static function send_security_headers( array $headers ): array {
+        $ours = self::$security_headers;
+        if ( ! is_ssl() ) {
+            unset( $ours['Strict-Transport-Security'] );
+        }
+        return self::merge_headers( $headers, $ours );
+    }
+    /**
+     * Header name → value from a security_headers config. Invalid values are
+     * dropped rather than sent, since a malformed Referrer-Policy or
+     * X-Frame-Options is ignored by browsers anyway. Public for unit testing.
+     */
+    public static function build_security_headers( array $config ): array {
+        $headers = [];
+        $referrer = strtolower( trim( (string) ( $config['referrer_policy'] ?? 'strict-origin-when-cross-origin' ) ) );
+        if ( in_array( $referrer, self::REFERRER_POLICIES, true ) ) {
+            $headers['Referrer-Policy'] = $referrer;
+        }
+        if ( $config['content_type_options'] ?? true ) {
+            $headers['X-Content-Type-Options'] = 'nosniff';
+        }
+        $frame = strtoupper( trim( (string) ( $config['frame_options'] ?? 'SAMEORIGIN' ) ) );
+        if ( in_array( $frame, self::FRAME_OPTIONS, true ) ) {
+            $headers['X-Frame-Options'] = $frame;
+        }
+        $permissions = trim( (string) ( $config['permissions_policy'] ?? self::PERMISSIONS_POLICY ) );
+        $directive   = '[a-z0-9-]+=(?:\*|\((?:[ \t]*(?:self|src|\*|"https?:\/\/[^"\s]+"))*[ \t]*\))';
+        if ( preg_match( '/^' . $directive . '(?:[ \t]*,[ \t]*' . $directive . ')*$/D', $permissions ) ) {
+            $headers['Permissions-Policy'] = $permissions;
+        }
+        $max_age = min( 63072000, (int) ( $config['hsts_max_age'] ?? 0 ) );
+        if ( $max_age > 0 ) {
+            $headers['Strict-Transport-Security'] = "max-age={$max_age}" . ( empty( $config['hsts_include_subdomains'] ) ? '' : '; includeSubDomains' );
+        }
+        return $headers;
+    }
+    /**
+     * Add $ours to $existing without overriding a header someone else already
+     * set (case-insensitive, like HTTP header names). Overriding could weaken
+     * a stricter choice, e.g. a security plugin's X-Frame-Options: DENY.
+     */
+    public static function merge_headers( array $existing, array $ours ): array {
+        $taken = array_change_key_case( $existing, CASE_LOWER );
+        foreach ( $ours as $name => $value ) {
+            if ( ! isset( $taken[ strtolower( $name ) ] ) ) {
+                $existing[ $name ] = $value;
+            }
+        }
+        return $existing;
+    }
+    // ── hide_wp_version ──────────────────────────────────────────────────────
+    private static function register_hide_wp_version(): void {
+        CLAUTRON_Primitive_Registry::register( 'hide_wp_version', [
+            'category'    => 'security',
+            'phase'       => 'compile',
+            'effects'     => static fn( array $c ): array => empty( $c['remove_readme'] ) ? [] : [ 'writes_files', 'writes_database' ],
+            'effects_max' => [ 'writes_files', 'writes_database' ],
+            'safe'        => false,
+            'label'       => 'Hide WordPress Version',
+            'description' => 'Stop advertising the WordPress version. Removes the generator meta tag and the feed <generator> element (which also drops WooCommerce\'s generator line), turns off Elementor\'s generator tag without changing its saved setting, and replaces ?ver=<WordPress version> on asset URLs with a site-specific hash that still changes on every update, so browser caches are still refreshed. readme.html in the site root also states the version, but the web server serves it without WordPress, so nothing above hides it: set remove_readme to delete it (opt-in, a file deletion that deactivating does not undo).',
+            'schema'      => [
+                'remove_generator'    => [ 'type' => 'boolean', 'default' => true, 'description' => 'Remove generator tags (WordPress, WooCommerce, Elementor) from pages and feeds.' ],
+                'mask_asset_versions' => [ 'type' => 'boolean', 'default' => true, 'description' => 'Replace ?ver=<WordPress version> on script/style URLs with a hash of it.' ],
+                'remove_readme'       => [ 'type' => 'boolean', 'default' => false, 'description' => 'Delete readme.html from the site root, and again after every WordPress update (which restores it). Works on any web server. Deactivating does not bring the file back; the next WordPress update does.' ],
+            ],
+            'examples'    => [
+                [],
+                [ 'remove_readme' => true ],
+            ],
+            'handler' => static function ( array $config ): void {
+                if ( ! empty( $config['remove_readme'] ) ) {
+                    add_action( 'init', [ self::class, 'maybe_remove_core_readme' ] );
+                }
+                if ( $config['remove_generator'] ?? true ) {
+                    add_filter( 'the_generator', '__return_empty_string' );
+                    // Elementor prints its own tag on wp_head unless this option is '1'.
+                    // pre_option_ overrides it for as long as the feature is active and
+                    // leaves the stored value untouched when it is deactivated.
+                    add_filter( 'pre_option_elementor_meta_generator_tag', [ self::class, 'elementor_generator_off' ] );
+                }
+                if ( $config['mask_asset_versions'] ?? true ) {
+                    add_filter( 'script_loader_src', [ self::class, 'mask_core_version' ] );
+                    add_filter( 'style_loader_src', [ self::class, 'mask_core_version' ] );
+                }
+            },
+            'verify' => static function ( array $config ): array {
+                $items = [];
+                if ( $config['remove_generator'] ?? true ) {
+                    $items[] = false !== has_filter( 'the_generator', '__return_empty_string' )
+                        ? [ 'status' => 'passed', 'label' => 'hide_wp_version:remove_generator' ]
+                        : [ 'status' => 'failed', 'label' => 'hide_wp_version:remove_generator', 'reason' => 'not hooked on the_generator.' ];
+                }
+                if ( $config['mask_asset_versions'] ?? true ) {
+                    $version = get_bloginfo( 'version' );
+                    $masked  = self::mask_core_version( includes_url( 'js/jquery/jquery.min.js?ver=' . $version ) );
+                    $items[] = false !== has_filter( 'script_loader_src', [ self::class, 'mask_core_version' ] ) && ! str_contains( $masked, $version )
+                        ? [ 'status' => 'passed', 'label' => 'hide_wp_version:mask_asset_versions' ]
+                        : [ 'status' => 'failed', 'label' => 'hide_wp_version:mask_asset_versions', 'reason' => 'asset URLs still carry the WordPress version.' ];
+                }
+                if ( ! empty( $config['remove_readme'] ) ) {
+                    $items[] = ! file_exists( ABSPATH . 'readme.html' )
+                        ? [ 'status' => 'passed', 'label' => 'hide_wp_version:remove_readme' ]
+                        : [ 'status' => 'failed', 'label' => 'hide_wp_version:remove_readme', 'reason' => 'readme.html is still in the site root; WordPress could not delete it (file permissions). Delete it by hand or deny it at the web server.' ];
+                }
+                return $items;
+            },
+        ] );
+    }
+    /** init: wiring for remove_core_readme(). */
+    public static function maybe_remove_core_readme(): void {
+        self::remove_core_readme( ABSPATH . 'readme.html', (string) get_bloginfo( 'version' ) );
+    }
+    /**
+     * Delete $path once per WordPress version. Every core update (one-click,
+     * WP-CLI or files copied by hand) puts readme.html back and changes the
+     * version, so keying on the version catches all of them for the price of
+     * one autoloaded option read per request, not a file stat. A failed
+     * delete is not recorded, so it is retried. Public for unit testing.
+     */
+    public static function remove_core_readme( string $path, string $version ): bool {
+        if ( get_option( self::README_OPTION ) === $version ) {
+            return false;
+        }
+        if ( file_exists( $path ) ) {
+            wp_delete_file( $path );
+        }
+        if ( file_exists( $path ) ) {
+            return false;
+        }
+        update_option( self::README_OPTION, $version, true );
+        return true;
+    }
+    /** pre_option_elementor_meta_generator_tag: '1' is Elementor's "disabled". */
+    public static function elementor_generator_off(): string {
+        return '1';
+    }
+    /**
+     * script_loader_src / style_loader_src: swap ver=<WordPress version> for a
+     * salted hash of it. Assets enqueued without an explicit version get the
+     * WordPress version by default, so they are masked too. Other versions
+     * (a plugin's own) are left alone. Public for unit testing.
+     */
+    public static function mask_core_version( mixed $src ): mixed {
+        if ( ! is_string( $src ) || '' === $src ) {
+            return $src;
+        }
+        $version = get_bloginfo( 'version' );
+        parse_str( (string) wp_parse_url( $src, PHP_URL_QUERY ), $query );
+        if ( ( $query['ver'] ?? null ) !== $version ) {
+            return $src;
+        }
+        return add_query_arg( 'ver', substr( wp_hash( $version ), 0, 8 ), $src );
+    }
+}

clautron/trunk/includes/primitives/class-primitive-sitemap.php

r3691441	r3784837
30	30	'category' => 'frontend',
31	31	'phase' => 'compile',
	32	'effects' => [],
32	33	'safe' => false,
33	34	'label' => 'Register XML Sitemap',

clautron/trunk/includes/primitives/class-primitive-taxonomy.php

-              r3582869
+              r3784837
             'category'    => 'taxonomy',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database' ],
             'label'       => 'Set Post Terms',
             'description' => 'Assign taxonomy terms to a post. Accepts term IDs, slugs, or names.',
 …
             'category'    => 'taxonomy',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Get Post Terms',
             'description' => 'Get all terms assigned to a post for a given taxonomy.',
 …
             'category'    => 'taxonomy',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database' ],
             'label'       => 'Create Term',
             'description' => 'Create a new taxonomy term if it does not already exist. Returns the term ID.',
 …
             'category'    => 'taxonomy',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Term Exists',
             'description' => 'Check if a term exists in a taxonomy. Writes term ID (int) or 0 if not found.',

clautron/trunk/includes/primitives/class-primitive-transform.php

-              r3582869
+              r3784837
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Parse JSON',
             'description' => 'Decode a JSON string into an associative array and store it in a context variable.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'To JSON',
             'description' => 'Encode a context variable as a JSON string and store it in another variable.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Map Fields',
             'description' => 'Remap an array of objects to a new shape. Each output key\'s value is a source field name or a {{expr}} template evaluated per item.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Filter Array',
             'description' => 'Filter an array of objects by a field condition. Supported operators: eq, neq, gt, gte, lt, lte, contains, not_contains, empty, not_empty.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Array Pluck',
             'description' => 'Extract a single field from each item in an array, producing a flat array of values.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Array Merge',
             'description' => 'Merge multiple array variables into one combined array.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Array Unique',
             'description' => 'Remove duplicate values from a flat array and reindex.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Array Sort',
             'description' => 'Sort an array. If field is set, sort an array of objects by that field. Otherwise sort a flat array.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Array Slice',
             'description' => 'Return a portion of an array starting at offset for a given length.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Count Array',
             'description' => 'Count the number of items in an array variable and store the integer.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'String Format',
             'description' => 'Render a template string with {{variable}} placeholders and store the result.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'String Truncate',
             'description' => 'Truncate a string to a maximum character length, appending a suffix when truncated.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'String Replace',
             'description' => 'Find and replace a substring within a string.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'String Split',
             'description' => 'Split a string by a delimiter into an array. Empty elements are removed.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'String Join',
             'description' => 'Join an array of strings into a single string using a glue separator.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Date Format',
             'description' => 'Format a date string or timestamp using a PHP date format string.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Date Diff',
             'description' => 'Calculate the absolute difference between two dates in the requested unit.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Date Add',
             'description' => 'Add a specified amount of time to a date and format the result.',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Slugify',
             'description' => 'Convert a string to a URL-friendly slug using WordPress sanitize_title().',
 …
             'category'    => 'data',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Math Calculate',
             'description' => 'Perform a numeric math operation between two values.',

clautron/trunk/includes/primitives/class-primitive-ui.php

-              r3691441
+              r3784837
             'category'    => 'ui',
             'phase'       => 'compile',
+            'effects'     => [ 'writes_database' ],
             'label'       => 'Add Metabox',
             'description' => 'Add a custom metabox panel to the post edit screen for one or more post types.',
 …
+                }
             },
+            'verify' => static function ( array $config ): array {
+                $box_id = sanitize_key( $config['id'] ?? '' );
+                if ( ! $box_id ) {
+                    return [];
+                }
+                // Handler registers with the 'clautron-' prefix (see above) —
+                // the check must look for the same id it was actually
+                // registered under.
+                $mbid = 'clautron-' . $box_id;
+                $pts  = (array) ( $config['post_types'] ?? [ 'post' ] );
+                $pt   = $pts[0] ?? 'post';
+                if ( ! is_admin() ) {
+                    return [ [ 'status' => 'warning', 'label' => "add_metabox:{$mbid}", 'reason' => 'skipped (requires admin context; will work correctly on post edit screens).' ] ];
+                }
+                $hook_name = 'add_meta_boxes_' . $pt;
+                do_action( $hook_name, null );
+                do_action( 'add_meta_boxes', $pt, null );
+                global $wp_meta_boxes;
+                $found = false;
+                foreach ( $wp_meta_boxes[ $pt ] ?? [] as $context_boxes ) {
+                    foreach ( $context_boxes as $priority_boxes ) {
+                        if ( isset( $priority_boxes[ $mbid ] ) ) {
+                            $found = true;
+                            break 2;
+                        }
+                    }
+                }
+                if ( $found ) {
+                    return [ [ 'status' => 'passed', 'label' => "add_metabox:{$mbid}" ] ];
+                }
+                return [ [ 'status' => 'failed', 'label' => "add_metabox:{$mbid}", 'reason' => "not found in wp_meta_boxes for post type '{$pt}'." ] ];
+            },
         ] );
+    }
 …
             'category'    => 'ui',
             'phase'       => 'compile',
+            'effects'     => [],
             'label'       => 'Add Admin Column',
             'description' => 'Add a custom column to the WordPress admin list table for a post type.',
 …
+                }
             },
+            'verify' => static function ( array $config ): array {
+                $pts   = (array) ( $config['post_types'] ?? [] );
+                $items = [];
+                foreach ( $pts as $pt ) {
+                    $filter = "manage_{$pt}_posts_columns";
+                    if ( has_filter( $filter ) ) {
+                        $items[] = [ 'status' => 'passed', 'label' => "add_admin_column:{$pt}" ];
+                    } else {
+                        $items[] = [ 'status' => 'failed', 'label' => "add_admin_column:{$pt}", 'reason' => "filter '{$filter}' not hooked." ];
+                    }
+                }
+                return $items;
+            },
         ] );
+    }
 …
             'category'    => 'ui',
             'phase'       => 'compile',
+            'effects'     => [],
             'label'       => 'Add Admin Filter',
             'description' => 'Add a custom dropdown filter to the WordPress admin post list table.',
 …
             'category'    => 'ui',
             'phase'       => 'runtime',
+            'effects'     => [ 'executes_code' ],
+            'safe'        => false,
             'label'       => 'Add Admin Notice',
             'description' => 'Display an admin notice (info, success, warning, error).',
 …
             'category'    => 'ui',
             'phase'       => 'compile',
+            'effects'     => [ 'writes_database' ],
             'label'       => 'Add Bulk Action',
             'description' => 'Add a custom bulk action to a post type list table.',
 …
             'category'    => 'ui',
             'phase'       => 'compile',
+            'effects'     => [],
             'label'       => 'Add Report Page',
             'description' => 'Add a stats/report section to the Clautron Reports admin page. Renders metric cards with post counts based on configurable queries.',
 …
             'category'    => 'ui',
             'phase'       => 'compile',
+            'effects'     => [ 'writes_database' ],
             'label'       => 'Add Row Action',
             'description' => 'Add a custom action link to post row actions in the list table (e.g. Clone).',
 …
                 } );
             },
+            'verify' => static function ( array $config ): array {
+                $pts   = (array) ( $config['post_types'] ?? [] );
+                $items = [];
+                foreach ( $pts as $pt ) {
+                    if ( has_filter( 'post_row_actions' ) || has_filter( "{$pt}_row_actions" ) ) {
+                        $items[] = [ 'status' => 'passed', 'label' => "add_row_action:{$pt}" ];
+                    } else {
+                        $items[] = [ 'status' => 'warning', 'label' => "add_row_action:{$pt}", 'reason' => 'row action filter not detected (may still work).' ];
+                    }
+                }
+                return $items;
+            },
         ] );
+    }
 …
             'category'    => 'ui',
             'phase'       => 'compile',
+            'effects'     => [ 'writes_database' ],
             'label'       => 'Add Options Page',
             'description' => 'Add a site-wide settings page under wp-admin (not tied to any single post). Uses the same field types as add_metabox\'s fields template: text, textarea, checkbox, select, radio, image, repeater. Each field is saved as its own option: clautron_opt_{menu_slug}_{field_key}.',

clautron/trunk/includes/primitives/class-primitive-user.php

-              r3582869
+              r3784837
             'category'    => 'user',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Read User Meta',
             'description' => 'Read a user meta field and store the value in a context variable.',
 …
             'category'    => 'user',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database' ],
             'label'       => 'Write User Meta',
             'description' => 'Write or update a user meta value. All fields support {{variable}} syntax.',
 …
             'category'    => 'user',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database' ],
             'label'       => 'Update User Role',
             'description' => 'Change a user\'s WordPress role. Allowed roles: subscriber, contributor, author, editor. Cannot promote to administrator.',
 …
             'category'    => 'user',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database', 'deletes_data' ],
             'label'       => 'Delete User (Safe)',
             'description' => 'Delete a WordPress user. By default, skipped if the user has any published posts or approved comments. Set force=true to override.',
 …
             'category'    => 'user',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Get Current User',
             'description' => 'Store the currently logged-in user\'s data (id, login, email, display_name, roles) in a context variable.',
 …
             'category'    => 'user',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Check User Capability',
             'description' => 'Check if a user has a specific capability. Writes true/false to output_variable.',
 …
             'category'    => 'user',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Check User Role',
             'description' => 'Check if a user has a specific role. Writes true/false to output_variable.',

clautron/trunk/includes/primitives/class-primitive-webhook.php

r3691441	r3784837
38	38	'category' => 'http',
39	39	'phase' => 'compile',
	40	'effects' => [ 'writes_database', 'changes_schema' ],
40	41	'safe' => false,
41	42	'label' => 'Register Payment Webhook',

clautron/trunk/includes/primitives/class-primitive-woocommerce.php

-              r3691441
+              r3784837
             'category'    => 'woocommerce',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Query Orders',
             'description' => 'Query WooCommerce orders with filters. Returns array of orders (id, status, total, currency, customer_id, customer_email, date_created, items_count) stored in a context variable.',
 …
             'category'    => 'woocommerce',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Query Products',
             'description' => 'Query WooCommerce products with filters. Returns array of products (id, name, sku, price, regular_price, stock_status, stock_quantity, type, status) stored in a context variable.',
 …
             'category'    => 'woocommerce',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database', 'external_requests' ],
             'label'       => 'Update Order Status',
             'description' => 'Move a WooCommerce order to another standard status (pending, processing, on-hold, completed, cancelled, refunded, failed). Adds an order note attributing the change to the Clautron workflow. Trashing/deleting orders is intentionally not supported.',

clautron/trunk/includes/primitives/class-primitive-wordpress.php

-              r3691441
+              r3784837
             'category'    => 'wordpress',
             'phase'       => 'compile',
+            // A custom capability_type grants its caps to administrator, which
+            // WordPress stores in wp_user_roles: that outlives deactivation.
+            'effects'     => static fn( array $c ): array => in_array( trim( explode( ',', (string) ( $c['capability_type'] ?? 'post' ) )[0] ), [ 'post', 'page' ], true ) ? [ 'changes_schema' ] : [ 'changes_schema', 'writes_database' ],
+            'effects_max' => [ 'changes_schema', 'writes_database' ],
             'label'       => 'Register Custom Post Type',
             'description' => 'Register a new custom post type in WordPress.',
 …
                 } );
             },
+            'verify' => static function ( array $config ): array {
+                $pt = $config['post_type'] ?? '';
+                if ( ! $pt ) {
+                    return [];
+                }
+                if ( get_post_type_object( $pt ) ) {
+                    return [ [ 'status' => 'passed', 'label' => "register_cpt:{$pt}" ] ];
+                }
+                return [ [ 'status' => 'failed', 'label' => "register_cpt:{$pt}", 'reason' => 'post type not registered.' ] ];
+            },
         ] );
+    }
 …
      * type they just asked for. Grant the mapped capabilities to
      * administrator; add_cap() is idempotent, safe to call every request.
+     *
+     * Only primitive capabilities. edit_post, read_post and delete_post are
+     * meta capabilities that map_meta_cap() resolves per post; a role must
+     * never hold them literally. WP_Role::has_cap() can't see them either,
+     * so granting them would rewrite wp_user_roles on every request, even
+     * for capability_type "post".
      */
     public static function grant_cpt_capabilities_to_admin( \WP_Post_Type $post_type_obj ): void {
 …
             return;
+        }
+        foreach ( (array) $post_type_obj->cap as $cap ) {
+        $primitive = array_diff_key( (array) $post_type_obj->cap, array_flip( [ 'edit_post', 'read_post', 'delete_post' ] ) );
+        foreach ( $primitive as $cap ) {
             if ( is_string( $cap ) && ! $role->has_cap( $cap ) ) {
                 $role->add_cap( $cap );
+            }
+        }
+    }
+    /**
+     * Effects of giving a post $status: trash removes it from the site, and
+     * publishing makes WordPress ping (update services, pingbacks,
+     * enclosures). An empty status leaves it unchanged. A value with a
+     * {{placeholder}} is only known at run time (and sanitize_key() turns
+     * "{{trash}}" into "trash"), so it gets the worst case. Core re-pinging
+     * when an already published post is saved again is not counted.
+     */
+    public static function post_status_effects( string $status ): array {
+        if ( str_contains( $status, '{{' ) ) {
+            return [ 'writes_database', 'deletes_data', 'external_requests' ];
+        }
+        return [
+            'trash'   => [ 'writes_database', 'deletes_data' ],
+            'publish' => [ 'writes_database', 'external_requests' ],
+        ][ sanitize_key( $status ) ] ?? [ 'writes_database' ];
+    }
 …
             'category'    => 'wordpress',
             'phase'       => 'compile',
+            'effects'     => [ 'changes_schema' ],
             'label'       => 'Register Taxonomy',
             'description' => 'Register a custom taxonomy for one or more post types.',
 …
                     register_taxonomy( $taxonomy, $post_types, self::build_taxonomy_args( $config, $label, $taxonomy ) );
                 } );
+            },
+            'verify' => static function ( array $config ): array {
+                $tax = $config['taxonomy'] ?? '';
+                if ( ! $tax ) {
+                    return [];
+                }
+                if ( taxonomy_exists( $tax ) ) {
+                    return [ [ 'status' => 'passed', 'label' => "register_taxonomy:{$tax}" ] ];
+                }
+                return [ [ 'status' => 'failed', 'label' => "register_taxonomy:{$tax}", 'reason' => 'taxonomy not registered.' ] ];
             },
         ] );
 …
             'category'    => 'wordpress',
             'phase'       => 'compile',
+            'effects'     => [ 'changes_schema' ],
             'label'       => 'Register Meta Field',
             'description' => 'Register a meta field for posts, users, or terms with type and schema.',
 …
                 } );
             },
+            'verify' => static function ( array $config ): array {
+                $key = $config['meta_key'] ?? '';
+                if ( ! $key ) {
+                    return [];
+                }
+                $pts        = (array) ( $config['post_types'] ?? [ 'post' ] );
+                $registered = registered_meta_key_exists( 'post', $key, $pts[0] ?? '' );
+                if ( $registered ) {
+                    return [ [ 'status' => 'passed', 'label' => "register_meta:{$key}" ] ];
+                }
+                return [ [ 'status' => 'warning', 'label' => "register_meta:{$key}", 'reason' => 'not found in registered meta (may still work via update_post_meta).' ] ];
+            },
         ] );
+    }
 …
             'category'    => 'wordpress',
             'phase'       => 'compile',
+            'effects'     => [ 'changes_schema' ],
             'safe'        => false,
             'label'       => 'Register REST Route',
 …
                 } );
             },
+            'verify' => static function ( array $config ): array {
+                $route = $config['route'] ?? '';
+                if ( ! $route ) {
+                    return [];
+                }
+                $routes    = rest_get_server()->get_routes();
+                $full_path = '/clautron/v1/' . ltrim( $route, '/' );
+                if ( isset( $routes[ $full_path ] ) ) {
+                    return [ [ 'status' => 'passed', 'label' => "register_rest_route:{$route}" ] ];
+                }
+                return [ [ 'status' => 'warning', 'label' => "register_rest_route:{$route}", 'reason' => 'not found in registered routes (REST server may not be initialized yet).' ] ];
+            },
         ] );
+    }
 …
             'category'    => 'wordpress',
             'phase'       => 'compile',
+            'effects'     => [ 'writes_database' ],
             'label'       => 'Schedule Post Expiry',
             'description' => 'Automatically change post status on its expiry date (stored in meta).',
 …
             'category'    => 'wordpress',
             'phase'       => 'runtime',
+            // The handler only allows draft/publish/pending/private (anything else
+            // becomes draft), so a new post can be published but never trashed.
+            'effects'     => static fn( array $c ): array => array_values( array_diff( self::post_status_effects( (string) ( $c['post_status'] ?? 'draft' ) ), [ 'deletes_data' ] ) ),
+            'effects_max' => [ 'writes_database', 'external_requests' ],
+            'safe'        => false,
             'label'       => 'Create Post',
             'description' => 'Create a new WordPress post (any type / status). Supports deduplication by post meta key + value to avoid creating duplicate posts across job runs.',
 …
             'category'    => 'wordpress',
             'phase'       => 'runtime',
+            'effects'     => static fn( array $c ): array => self::post_status_effects( (string) ( $c['post_status'] ?? '' ) ),
+            'effects_max' => [ 'writes_database', 'deletes_data', 'external_requests' ],
             'label'       => 'Update Post',
             'description' => 'Update fields on an existing WordPress post. Only provided fields are changed.',
 …
             'category'    => 'wordpress',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database', 'deletes_data' ],
             'label'       => 'Delete Post',
             'description' => 'Move a post to trash (force=false) or permanently delete it (force=true).',
 …
             'category'    => 'wordpress',
             'phase'       => 'runtime',
+            'effects'     => static fn( array $c ): array => self::post_status_effects( (string) ( $c['status'] ?? '' ) ),
+            'effects_max' => [ 'writes_database', 'deletes_data', 'external_requests' ],
             'label'       => 'Set Post Status',
             'description' => 'Change the status of a post (draft, publish, pending, private, trash).',
 …
             'category'    => 'wordpress',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Check WooCommerce HPOS',
             'description' => 'Detects whether WooCommerce High Performance Order Storage (HPOS) is active. Stores true/false in a context variable. Use with if_else to branch between HPOS and legacy wp_posts order queries.',
 …
             'category'    => 'wordpress',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database' ],
             'label'       => 'Schedule Single Event',
             'description' => 'Schedule a one-time WP-Cron event to fire at a future time. The hook name must start with "clautron_" for safety. The arg is resolved as an integer (post/order ID).',

clautron/trunk/includes/primitives/class-primitive-workflow.php

-              r3582869
+              r3784837
             'category'    => 'workflow',
             'phase'       => 'runtime',
+            'effects'     => [],
             'label'       => 'Validate Field',
             'description' => 'Validate a value against rules (required, min_length, max_length, email, url, numeric, regex). Writes true/false to output_variable. Writes error message to error_variable if set.',
 …
             'category'    => 'workflow',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database' ],
             'label'       => 'Request Review',
             'description' => 'Flag a post for editorial review by setting its status to \'pending\' and storing a review request note in meta.',
 …
             'category'    => 'workflow',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database', 'deletes_data', 'external_requests' ], // deletes the review note; publishing pings
             'label'       => 'Approve Content',
             'description' => 'Approve content by publishing a pending post and clearing the review note.',
 …
             'category'    => 'workflow',
             'phase'       => 'runtime',
+            'effects'     => [ 'writes_database' ],
             'label'       => 'Reject Content',
             'description' => 'Reject content by reverting a pending post to draft and storing a rejection reason.',

clautron/trunk/includes/registry/class-primitive-registry.php

-              r3582869
+              r3784837
      *   @type string   $description One-sentence description for the AI prompt catalog.
      *   @type string   $dependency  null | 'woocommerce' | 'acf' | ...
+     *   @type callable|null $verify function( array $config ): array — used by
+     *                               CLAUTRON_Smoke_Tester. Returns zero or more
+     *                               check items { status: passed|failed|warning,
+     *                               label: string, reason?: string }. Return []
+     *                               when there's nothing meaningful to check for
+     *                               a given config (e.g. a required field is
+     *                               empty). Omit entirely (leave null) if this
+     *                               primitive type has no verification yet — it
+     *                               will show up as 'unavailable' rather than
+     *                               being silently skipped.
+     *   @type string[]|Closure|null $effects  Which of self::EFFECTS the primitive
+     *                               has, e.g. [ 'writes_database' ]; [] = none.
+     *                               A Closure( array $config ): string[] when
+     *                               they depend on config. null (omitted) =
+     *                               undeclared, which consumers must treat as
+     *                               "could be anything". An unknown effect name
+     *                               is reported with _doing_it_wrong() and makes
+     *                               the primitive undeclared, never "no effect".
+     *   @type string[] $effects_max Required with a Closure: every effect any
+     *                               config can produce. The catalog publishes
+     *                               this worst case; the abilities still answer
+     *                               per call from the real config.
+     *   @type bool|Closure|null $reversible  Whether deactivating removes every
+     *                               trace. Omitted = derived from effects (no
+     *                               data written, deleted or sent away). Set it
+     *                               when something outlives deactivation that
+     *                               effects can't express (a cookie, HSTS).
+     *   @type array[]  $examples    Example configs. Omitted = the
+     *                               clautron/primitives-list ability falls back
+     *                               to configs found in the shipped demos.
      * }
      */
 …
             'description' => '',
             'dependency'  => null,
+            'verify'      => null,
+            'effects'     => null,
+            'effects_max' => null,
+            'reversible'  => null,
+            'examples'    => [],
         ] );
         self::$primitives[ $type ]['type'] = $type;
+        self::check_effects( $type );
+    }
+    /**
+     * A typo in an effect name must not quietly read as "no effect" (and so
+     * as reversible): report it and treat the primitive as undeclared.
+     */
+    private static function check_effects( string $type ): void {
+        $def     = self::$primitives[ $type ];
+        $unknown = [];
+        foreach ( [ 'effects', 'effects_max' ] as $key ) {
+            if ( is_array( $def[ $key ] ) ) {
+                $unknown = array_merge( $unknown, array_diff( $def[ $key ], self::EFFECTS ) );
+            }
+        }
+        if ( $unknown ) {
+            self::$primitives[ $type ]['effects'] = null;
+            self::doing_it_wrong( "Primitive '{$type}' declares unknown effects: " . implode( ', ', array_unique( $unknown ) ) . '. Allowed: ' . implode( ', ', self::EFFECTS ) . '.' );
+        } elseif ( $def['effects'] instanceof Closure && ! is_array( $def['effects_max'] ) ) {
+            self::doing_it_wrong( "Primitive '{$type}' computes its effects from config but declares no effects_max; the catalog will list its effects as unknown." );
+        }
+    }
+    private static function doing_it_wrong( string $message ): void {
+        if ( function_exists( '_doing_it_wrong' ) ) {
+            _doing_it_wrong( 'CLAUTRON_Primitive_Registry::register', esc_html( $message ), '1.5.0' );
+        }
+    }
+    /**
+     * Effect vocabulary, the same keys a capability manifest's `effects` uses
+     * (Capability Contract v1), so a consumer reads both the same way:
+     *   writes_database    creates or changes content, meta, options, users,
+     *                      terms, comments, orders, events or transients
+     *   writes_files       writes or deletes files on disk
+     *   deletes_data       removes or trashes site data
+     *   external_requests  sends data off the site (HTTP, email, AI provider),
+     *                      including what WordPress itself sends because of
+     *                      it: pings when a post gets published, the post
+     *                      author's email when a comment is approved
+     *   executes_code      outputs markup or script taken from its config
+     *   changes_schema     changes the content model or API surface (post
+     *                      types, taxonomies, registered meta, REST routes)
+     */
+    public const EFFECTS = [ 'writes_database', 'writes_files', 'deletes_data', 'external_requests', 'executes_code', 'changes_schema' ];
+    /** Effects that make deactivation an incomplete undo when nothing else is declared. */
+    private const PERSISTENT_EFFECTS = [ 'writes_database', 'writes_files', 'deletes_data', 'external_requests' ];
+    /**
+     * Effects of one node, as EFFECTS => bool, or null when the primitive
+     * (or the type itself) is unknown or declares none.
+     */
+    public static function node_effects( string $type, array $config = [] ): ?array {
+        $def = self::get( $type );
+        if ( ! $def || null === $def['effects'] ) {
+            return null;
+        }
+        $list = $def['effects'] instanceof Closure ? (array) ( $def['effects'] )( $config ) : (array) $def['effects'];
+        if ( array_diff( $list, self::EFFECTS ) ) {
+            self::doing_it_wrong( "Primitive '{$type}' computed unknown effects: " . implode( ', ', array_diff( $list, self::EFFECTS ) ) . '.' );
+            return null;
+        }
+        return array_combine( self::EFFECTS, array_map( static fn( string $e ): bool => in_array( $e, $list, true ), self::EFFECTS ) );
+    }
+    /**
+     * Every effect the primitive can have with any config: effects_max for a
+     * config-dependent declaration, the static list otherwise. null when
+     * undeclared or when a Closure has no effects_max.
+     *
+     * @return string[]|null
+     */
+    public static function max_effects( string $type ): ?array {
+        $def = self::get( $type );
+        if ( ! $def || null === $def['effects'] ) {
+            return null;
+        }
+        if ( $def['effects'] instanceof Closure ) {
+            return is_array( $def['effects_max'] ) ? array_values( $def['effects_max'] ) : null;
+        }
+        return array_values( (array) $def['effects'] );
+    }
+    /** Whether deactivating undoes the primitive with every config (false when any config can't). */
+    private static function always_reversible( array $def, ?array $max ): bool {
+        if ( null === $max || $def['reversible'] instanceof Closure ) {
+            return false;
+        }
+        if ( null !== $def['reversible'] ) {
+            return (bool) $def['reversible'];
+        }
+        return ! array_intersect( $max, self::PERSISTENT_EFFECTS );
+    }
+    /**
+     * Combined effects of every node in a blueprint (structures, conditions,
+     * actions), whether deactivating it would undo all of them, and which
+     * node types declare no effects (consumers should treat those as risky).
+     *
+     * @return array{effects: array<string,bool>, reversible: bool, undeclared: string[]}
+     */
+    public static function effects_of( array $blueprint ): array {
+        $effects    = array_fill_keys( self::EFFECTS, false );
+        $reversible = true;
+        $undeclared = [];
+        foreach ( [ 'structures', 'conditions', 'actions' ] as $list ) {
+            foreach ( (array) ( $blueprint[ $list ] ?? [] ) as $node ) {
+                $type   = (string) ( $node['type'] ?? '' );
+                $config = (array) ( $node['config'] ?? [] );
+                $node_effects = self::node_effects( $type, $config );
+                if ( null === $node_effects ) {
+                    $undeclared[] = $type;
+                    $reversible   = false;
+                    continue;
+                }
+                foreach ( $node_effects as $effect => $has ) {
+                    $effects[ $effect ] = $effects[ $effect ] || $has;
+                }
+                $reversible = $reversible && self::node_reversible( $type, $config, $node_effects );
+            }
+        }
+        return [ 'effects' => $effects, 'reversible' => $reversible, 'undeclared' => array_values( array_unique( $undeclared ) ) ];
+    }
+    private static function node_reversible( string $type, array $config, array $effects ): bool {
+        $declared = self::$primitives[ $type ]['reversible'];
+        if ( $declared instanceof Closure ) {
+            return (bool) $declared( $config );
+        }
+        if ( null !== $declared ) {
+            return (bool) $declared;
+        }
+        return ! array_filter( array_intersect_key( $effects, array_flip( self::PERSISTENT_EFFECTS ) ) );
+    }
 …
     /**
+     * Build the capability catalog injected into the AI system prompt.
+     * Returns a lightweight array — type, category, description, schema.
+     * Build the capability catalog injected into the AI system prompt and
+     * returned by the clautron/primitives-list ability.
+     *
+     * `safe` false = needs explicit approval before use; `verifiable` = the
+     * primitive declares a verify check, so a smoke test can confirm it.
+     * `effects` is the worst case over every config (null when undeclared or
+     * unknown) and `reversible` is true only when deactivating undoes it with
+     * every config; `effects_vary` = some config values are milder, so ask
+     * effects_of() for the real config (the abilities return it per call).
+     *
      * @return array[]
 …
         $catalog = [];
         foreach ( self::$primitives as $type => $def ) {
+            $max       = self::max_effects( $type );
             $catalog[] = [
+                'type'        => $type,
+                'category'    => $def['category'],
+                'phase'       => $def['phase'],
+                'label'       => $def['label'],
+                'description' => $def['description'],
+                'schema'      => $def['schema'],
+                'dependency'  => $def['dependency'],
+                'type'         => $type,
+                'category'     => $def['category'],
+                'phase'        => $def['phase'],
+                'label'        => $def['label'],
+                'description'  => $def['description'],
+                'schema'       => $def['schema'],
+                'dependency'   => $def['dependency'],
+                'safe'         => (bool) $def['safe'],
+                'verifiable'   => is_callable( $def['verify'] ),
+                'effects'      => null === $max ? null : array_values( array_intersect( self::EFFECTS, $max ) ),
+                'effects_vary' => $def['effects'] instanceof Closure || $def['reversible'] instanceof Closure,
+                'reversible'   => self::always_reversible( $def, $max ),
+                'examples'     => array_values( (array) $def['examples'] ),
             ];
+        }

clautron/trunk/readme.txt

-              r3691450
+              r3784837
 Tags: capability, automation, security, no-code, ai
 Requires at least: 7.0
 Tested up to: 7.0
 Stable tag: 1.2.0
+Tested up to: 7.1
+Stable tag: 1.5.0
 Requires PHP: 8.1
 License: GPL-2.0-or-later
 …
 **One secure layer. Thousands of capabilities.**
 Every capability Clautron builds can be activated, deactivated, and rolled back the same predictable way. Before you turn one on, you can see what it reads, what it writes, what it connects to, and how much it changes.
+Every capability Clautron builds can be activated and deactivated the same predictable way, without touching any data it wrote while it was on. Before you turn one on, you can see what it reads, what it writes, what it connects to, and how much it changes.
 **Key features:**
 …
 * **Search first, generate second:** Clautron checks what already exists before generating anything new; when it does generate something, you review it before it runs
 * **Know what runs on your site:** every capability is built from a declared, inspectable set of primitives
+* **Reversible by design:** activate, deactivate, or roll back any capability without digging through code
+* **Deactivate without data loss:** turn any capability off without digging through code. Nothing it wrote while active is touched, and turning it back on reactivates the same capability instead of starting over
+* **Machine-readable capability manifest:** each capability can declare its own version, requirements, required permissions, and effects (what it reads, writes, or connects to). External tools like AICOM can inspect and manage capabilities through this same contract, without hardcoded per-capability logic
+* **Know what a capability does before you turn it on:** every building block declares whether it writes data, deletes data, sends data off the site or outputs code, and whether turning it off fully undoes it
+* **Security hardening without a security plugin:** stop username discovery, add the missing security headers and hide the WordPress version, each as a small capability you can switch off again
+* **Ready for AI agents:** every Clautron operation is a WordPress Ability with its own schema, so AI agents and tools like AICOM can find and use them without custom integration code
 * **Scheduled jobs and reports:** recurring automations and on-demand data queries, without a separate plugin for each
 * **Safe by construction:** a safety policy layer blocks dangerous operations before they run
 …
 = What are primitives, and what's a capability? =
 Primitives are the small, reusable building blocks Clautron composes things from: custom post types, meta fields, admin columns, scheduled tasks, and more. A capability is what you actually get: a specific piece of functionality (a redirect, an admin column, a WooCommerce rule) built from one or more primitives, that you can activate, deactivate, or roll back as one unit.
+Primitives are the small, reusable building blocks Clautron composes things from: custom post types, meta fields, admin columns, scheduled tasks, and more. A capability is what you actually get: a specific piece of functionality (a redirect, an admin column, a WooCommerce rule) built from one or more primitives, that you can activate or deactivate as one unit. Some capabilities also carry a manifest (a declared version, requirements, and effects) that lets external tools install, inspect, update, and deactivate them without capability-specific code.
 = Does this plugin store data in the database? =
 Yes. Clautron creates its own database tables (prefixed with `wp_clautron_`) to store blueprints, conversation history, scheduled jobs, workflow state, and execution logs. All data is removed if you uninstall the plugin.
+Yes. Clautron creates its own database tables (prefixed with `wp_clautron_`) to store blueprints, conversation history, scheduled jobs, workflow state, capability install state, and execution logs. All data is removed if you uninstall the plugin.
 = What permissions are required? =
 Clautron is accessible only to administrators (`manage_options` capability). No frontend functionality or public-facing pages are added to your site.
+Clautron's own screens are only available to administrators (`manage_options` capability). Clautron adds nothing to the frontend by itself: visitors only see changes from capabilities you activate, such as a consent banner, a redirect or security headers.
 == External Services ==
 …
 == Changelog ==
+= 1.5.0 =
+* Added harden_user_enumeration: stops anonymous visitors from discovering usernames. Logged-out requests to the /wp/v2/users REST endpoints get a 401 (logged-in users and the block editor keep working), every author archive returns a 404, the users sitemap is removed, oEmbed shows the site instead of the author, and the login form gives the same error for an unknown username and a wrong password.
+* Added security_headers: sends Referrer-Policy, X-Content-Type-Options, X-Frame-Options and Permissions-Policy, plus Strict-Transport-Security (HSTS) on HTTPS when you opt in. Its check loads your homepage to confirm the headers actually reach visitors, so a page cache or CDN that drops them is reported.
+* Added hide_wp_version: removes the WordPress, WooCommerce and Elementor generator tags from pages and feeds, and masks the WordPress version in asset URLs while keeping browser caches working. Optionally deletes readme.html, and deletes it again after each WordPress update.
+* Added a ready-made Security Hardening capability built from these three primitives.
+* Every Clautron operation (catalog, install, inspect, update, deactivate, blueprints, events) is now a WordPress Ability with its own input schema and behavior annotations, so AI agents and management tools such as AICOM can discover and call them without Clautron-specific code. New: primitive-apply, which applies a single primitive as its own capability, validated and verified.
+* Every primitive now declares its effects: whether it writes data, writes files, deletes data, sends data off the site, outputs code from its configuration, or changes the content model, and whether turning it off fully undoes it. Installing, applying or ensuring a capability reports these effects, in a dry run too, together with the step that reverses the change.
+* Fixed ensuring a deactivated custom capability creating a second copy of it: it is now reactivated.
+* Fixed register_cpt writing the edit_post, read_post and delete_post meta capabilities into the administrator role on every page load.
+* http_request, fetch_feed, create_post and add_admin_notice are now flagged as needing approval, like the other primitives that can send data off the site, delete data or output code.
+= 1.4.0 =
+* Added consent_banner: a category-based cookie-consent banner (necessary/analytics/marketing) with an anonymous REST endpoint to record the visitor's choice, a full audit trail (who consented to what, when, from which source) in the events store, and automatic opt-out when the visitor's browser sends the Global Privacy Control (Sec-GPC) signal.
+* Added gate_script_by_consent: outputs a script or HTML block only once its required consent category has been granted, reading the same cookie consent_banner writes.
+* consent_banner can emit Google Consent Mode v2 signals (gtag consent default/update), mapping consent categories to Google's ad_storage/analytics_storage/ad_user_data/ad_personalization signals for GA4 and Ads.
+* Fixed handle_upload's internal failure closure declaring a standalone `false` return type, valid only since PHP 8.2, which fataled on activation despite the plugin declaring Requires PHP 8.1.
+= 1.3.0 =
+* Added a machine-readable capability manifest (version, platform/PHP/WordPress requirements, required permissions, declared effects, reversibility), kept separate from a capability's blueprint and joined only by capability_id. Lets external tools like AICOM install, inspect, update, and deactivate capabilities through one consistent contract instead of capability-specific code.
+* Added a new `wp_clautron_capabilities` table tracking each capability's installed version and status separately from its blueprint. This enables comparing installed vs. available version and reinstalling a deactivated capability without losing its edit history.
+* Added a deactivate operation: stops a capability from being re-applied on future requests without touching any data it wrote while active. Reinstalling afterward reactivates the same capability rather than creating a duplicate.
+* Added an update operation: re-syncs an installed capability to its manifest's current declared version in place.
+* Primitive verification (used to confirm a compiled capability is correctly wired into WordPress) is no longer a fixed, hardcoded checklist covering a handful of primitive types: each primitive now declares its own check, and any primitive without one is reported explicitly rather than silently skipped.
+* Fixed the metabox verification check to look up the actual registered meta box ID (it was checking an ID that never matched, so it could never report success).
 = 1.2.0 =
 …
 == Upgrade Notice ==
+= 1.5.0 =
+Adds security hardening primitives, WordPress Abilities for every operation, and declared effects for every primitive. No breaking changes.
+= 1.3.0 =
+Adds a capability manifest, deactivate/update operations, and per-primitive verification. No breaking changes.
 = 1.1.0 =
 Adds Elementor and WordPress widget primitives. No breaking changes.

clautron/trunk/uninstall.php

r3582869	r3784837
16	16
17	17	delete_option( 'clautron_settings' );
	18	delete_option( 'clautron_readme_removed_for' ); // hide_wp_version's remove_readme bookkeeping
18	19	delete_transient( 'clautron_active_workflows' );

Context Navigation

Legend:

Download in other formats: