Shimpz
Read-only source reference

Prove Salesnator safely.

Evaluate one synthetic Meta Ads campaign snapshot, produce a deterministic recommendation, and request at most one owner notification for the same run—without a provider token or campaign mutation.

Authority

Ask Services for two narrow operations

  • meta-ads.read represents a mediated, read-only campaign snapshot.
  • notifications.send represents one owner notification request.
  • customer-ad-account and owner-channel are opaque binding names, not keys.
  • The Assistant declares no direct egress and never receives a provider credential.
  • No update, publish, budget, ad, ad-set, or campaign mutation operation is declared.
Synthetic proof

Make the failure case deterministic

The campaign and ad set are active, the ad has issues, spend is 12,000 cents, and leads are zero. No customer identifier, creative, audience, token, or personal data is present.

campaign-health.json json 
{
  "assistant_id": "salesnator",
  "capsule_id": "demo-capsule",
  "run_id": "run-20260715t120000z",
  "scheduled_at": "2026-07-15T12:00:00Z",
  "campaign": { "status": "ACTIVE" },
  "adset": { "status": "ACTIVE" },
  "ad": { "status": "WITH_ISSUES" },
  "metrics": {
    "spend_cents": 12000,
    "leads": 0
  }
}

The operation returns the same core verdict every time:

campaign-health verdict · JSON json 
{
  "audit": {
    "assistant_id": "salesnator",
    "capsule_id": "demo-capsule",
    "run_id": "run-20260715t120000z",
    "operation": "campaign-health",
    "result": "blocked"
  },
  "effective_status": "blocked",
  "cpl_cents": null,
  "recommendation": "review",
  "mutation_performed": false,
  "notification": {
    "idempotency_key": "salesnator:campaign-health:run-20260715t120000z",
    "enqueued": true
  }
}

A repeated run_id keeps the verdict unchanged and sets notification.enqueued to false. The example proves that behavior in one process; a future controller and Notifications Service must persist the idempotency key across restarts.

Validation

Run the complete local proof

From a checked-out shimpz-sdk repository:

Terminal · Salesnator
SHIMPZ_LIB=$PWD/rootfs/opt/shimpz-lib python3 rootfs/usr/local/bin/shimpz-assistant validate examples/salesnator/shimpz.assistant.toml
PYTHONPATH=examples/salesnator python3 -m unittest discover -s examples/salesnator/tests

The tests use no provider, network mock, monkeypatch, or customer data. They execute the processor and a real loopback HTTP server, prove the closed route, and verify notification deduplication.

Routine

Keep campaign-watch owner-disabled

The manifest requests campaign-watch every 3,600 seconds with timeout, jitter, single-flight, and a scheduled-time idempotency key. It starts disabled. The SDK validates those fields; it does not schedule the operation or grant either Service capability.

Read the complete Salesnator source.