Ruo Supabase Mutation Audit

RUO Supabase Mutation Handoff Audit

Use this skill automatically whenever a RUO Peptides / PeptraLabs Supabase mutation is proposed. It converts the requested change into a validated instruction set for Hermes, the sole Supabase mutation owner.

This skill is a pre-handoff audit layer. It never authorizes Codex, Claude Code, Genie, or another non-Hermes agent to execute a mutation. Always apply ruo-supabase-guardrails first; if the two skills conflict, the stricter read-only rule wins.

Enforcement Boundary

This skill enforces behavior at the agent workflow and skill-selection layer. It does not revoke credentials or create a database trigger. Technical separation requires non-Hermes runtimes to lack write-capable credentials and to use only read-only or Hermes-mediated access.

Quick Rule

A mutation request can produce only one of these preparing-agent outcomes:

• READ_ONLY_NO_HANDOFF_REQUIRED
• DRAFT_AWAITING_PAFI_APPROVAL
• HANDOFF_BLOCKED
• HANDOFF_READY

HANDOFF_READY means the instruction set is complete enough to deliver to Hermes. It does not authorize the preparing agent to execute anything.

Mutation Surfaces

Classify every request:

Read-only selects, exports, checksums, diffs, and schema inspection return READ_ONLY_NO_HANDOFF_REQUIRED.

Hermes Supabase Mutation Instruction Set

The packet is a typed inter-agent contract:

contract_version: hermes-supabase-instruction.v1
instruction_set_id: stable unique reference
execution_owner: Hermes-main
executor: hermes
executor_profile: default
codex_direct_write_forbidden: true
approval_explicit: true
approval_source: exact chat/thread/channel/message or approval artifact
approval_timestamp: ISO timestamp
operation: insert/update/upsert/delete/migration/config/storage/rpc/rls/runtime_config/dashboard_sync
surface: one mutation surface from the table above
objects: exact tables, rows, buckets, policies, functions, config objects, or artifacts
scope: exact IDs or precise filters
expected_count: exact number of rows/objects expected to change
payload_summary: redacted business description
mutation_steps: ordered operations containing object, operation, scope, and intended values
preflight_diff: observed current state versus intended state
required_markers: Pafi-authorized plus Hermes owner attribution
idempotency: approval ID, unique reference, checksum, or duplicate-detection rule
rollback: precise undo or compensating plan
domain_invariants: applicable money/stock/account/config/compliance checks
post_write_verification: exact read-back queries/checks and expected result
artifact_sync: required follow-up surfaces or explicit no-sync reason
return_contract: structured execution evidence Hermes must return

Packets must not contain credentials, secret values, or unnecessary raw PII. Secret references are owner-managed handles, never values.

If Pafi has not approved the exact business mutation, prepare a non-executable draft with approval_explicit: false and return DRAFT_AWAITING_PAFI_APPROVAL. Do not send it to Hermes as executable.

Mandatory Executor Checks

The deterministic validator must block unless:

• contract_version is hermes-supabase-instruction.v1;
• execution_owner is Hermes-main and executor_profile is default;
• executor is exactly hermes;
• codex_direct_write_forbidden is exactly true;
• exact Pafi approval exists for the requested mutation;
• scope and expected_count are precise;
• mutation_steps are non-empty and target only the declared objects;
• rollback, idempotency, invariants, read-back, and return evidence are specified; and
• the packet contains no likely secret value.

Any actor_path or marker that says Codex/API/Pafi agent will execute is a policy violation. The validator blocks all known legacy direct-API actor paths, preparing-agent performer markers, and API-only approval markers.

Audit Workflow

1. Classify the request as read-only or mutation.

2. Load guardrails and confirm the preparing runtime is read-only.

3. Preflight read-only state using the narrowest technically read-only path. If unavailable, instruct Hermes to perform the preflight.

4. Apply domain controls such as ruo-financial-audit-controller for money, stock, balance, cost, or published-audit changes.

5. Assemble the instruction set without secrets or unnecessary PII.

6. Run deterministic validation:

   python3 scripts/validate_mutation_packet.py packet.json
   

7. Block or draft missing approval, unclear scope, contradictory source authority, missing invariants, or unsafe credentials.

8. Deliver only HANDOFF_READY packets to Hermes through the configured cross-agent channel. If Hermes is unavailable, return a ready-to-send packet and report the delivery failure.

9. Wait for Hermes evidence. Do not infer success from delivery or acceptance.

10. Independently verify read-only when possible. A mismatch creates a new Hermes instruction set; the preparing agent never repairs it directly.

Hermes Return Contract

Hermes must return a structured result containing:

instruction_set_id
execution_owner: Hermes-main
executor: hermes
executor_profile: default
status: executed_verified/executed_rolled_back/blocked/failed
started_at
completed_at
affected_objects
affected_ids_or_filters
affected_count
redacted_before_after
audit_actor_and_markers
idempotency_result
post_write_readback
domain_invariant_results
rollback_status
artifact_sync_status
exceptions

The preparing agent may report HERMES_EXECUTION_REPORTED only from this evidence. It may report INDEPENDENTLY_VERIFIED only after its own read-only check.

Domain Constraints

• Airtable remains frozen legacy evidence; new RUO operational state belongs in Supabase only through Hermes.
• Account and finance instructions must use the RUO account-ledger contract and full propagation matrix.
• Stock instructions must respect location ownership: Bucharest/main uses skus.stock_qty; Ibiza/other locations use location_stock.qty; v_stock_by_location composes both.
• Financial, stock, SKU, participant balance, customer credit, restock, pricing-control, batch/COA, and proof/reference changes require the financial audit controller or equivalent invariant checks.
• Runtime/config instructions must preserve read-only credentials for every non-Hermes agent.

Output Contract

For read-only:

Mode: READ_ONLY_NO_HANDOFF_REQUIRED
Reason: ...
Supabase writes performed: none

For an unapproved draft:

Mode: DRAFT_AWAITING_PAFI_APPROVAL
Instruction set: ...
Hermes delivery: not executable
Supabase writes performed: none

For a blocked handoff:

Mode: HANDOFF_BLOCKED
Surface: ...
Missing/failed checks: ...
Supabase writes performed: none

For a validated handoff:

Mode: HANDOFF_READY
Executor: Hermes
Instruction set ID: ...
Approval/surface/objects/scope: ...
Expected diff: ...
Rollback/idempotency/invariants: ...
Required Hermes return evidence: ...
Supabase writes performed by preparing agent: none

For Hermes evidence:

Mode: HERMES_EXECUTION_REPORTED
Hermes status/read-back/invariants: ...
Independent verification: verified/not_run/exception
Residual exceptions: ...
Supabase writes performed by preparing agent: none

Bundled Helper

scripts/validate_mutation_packet.py validates instruction-set structure only. It never contacts Supabase, dispatches Hermes, or authorizes execution.

Expected helper statuses:

• READ_ONLY_NO_HANDOFF_REQUIRED
• DRAFT_AWAITING_PAFI_APPROVAL
• HANDOFF_READY
• BLOCKED

Test Cases

1. Read-only schema inspection returns READ_ONLY_NO_HANDOFF_REQUIRED; a packet labeled read-only that also contains mutation intent returns BLOCKED.
2. A complete packet with executor=hermes returns HANDOFF_READY.
3. A complete packet with executor=codex, a legacy API-only actor path, or codex_direct_write_forbidden=false returns BLOCKED.
4. A packet without exact approval returns DRAFT_AWAITING_PAFI_APPROVAL only when all non-approval fields are complete; otherwise it is BLOCKED.
5. A financial/stock packet without money/stock/account invariants returns BLOCKED.
6. A schema/config packet without compatibility and rollback checks returns BLOCKED.

When to Use vs Alternatives

• This skill: prepare and validate a Hermes handoff for any RUO Supabase mutation.
• ruo-supabase-guardrails: always use first for the read-only credential and executor boundary.
• ruo-financial-audit-controller: use for money, stock, balances, costs, and published audit propagation.
• audit-pro: use when changing this skill, its procedure, or its validator; not for every mutation request.