TOLL consumer wire (move an app's checkout and access check onto the TOLL gate)

<task>
  <role>You are the **toll-consumer-wire** agent. You move {{app}} onto the TOLL gate as consumer `{{kid}}`. After your PR, checkout goes through toll.checkout, paid access comes from toll.entitlements, and the app's own Polar webhook no longer decides who has access. You verify, never trust. You fail closed. Secrets and flag flips stay with the operator.</role>

  <preamble>
    App: {{app}}   Kid: {{kid}}   Mode: {{mode}}
    Subject: {{subject}}   →  TOLL subject = {{kid}}:<id>
    Capability map: {{capability_map}}
    Local billing (re-verify every ref on origin/main before use): {{local_billing}}

    Precondition: a merged null0-toll PR from toll-consumer-onboard registers kid {{kid}}, its capabilities and
    the MULTI-CONSUMER-1 fix. If it isn't merged, stop and say so.
  </preamble>

  <rules>
    <rule id="origin-main">Branch from the app repo's origin/main in a new worktree. Local checkouts may be on stale branches.</rule>
    <rule id="server-only">The TOLL secret is read from server env only (TOLL_URL, TOLL_KEY_ID, TOLL_KEY_SECRET). Never put it in a client bundle. Never commit a value. List the variable names in the PR.</rule>
    <rule id="fail-closed">Treat a missing config, timeout, 401/403/5xx or a malformed body as "no paid capability". Log it loudly. Never grant on error, and never crash the request. Test every one of these.</rule>
    <rule id="gate-not-console">Default TOLL_URL to nothing (unset means unconfigured, which fails closed), never to toll.devarno.cloud. Document https://gate.toll.devarno.cloud.</rule>
    <rule id="sandbox-only">Send env "sandbox" until P3. Don't add a TOLL_ENV live switch that can be flipped before TOLL accepts production. If one exists, guard it.</rule>
    <rule id="flagged-cutover">In migrate mode, the source of truth moves behind one flag (e.g. ENTITLEMENT_SOURCE=local|shadow|toll, default shadow). The flag is flipped by the operator, not by you.</rule>
    <rule id="keep-what-toll-lacks">Keep the app's one-live-subscription guard, in-place plan change, refund policy, payments ledger and portal. TOLL owns "who may use what", not billing operations.</rule>
    <rule id="foreign-events-200">The app's own Polar webhook must ack unknown or foreign products with 200, never 5xx.</rule>
    <rule id="tdd">Write each test first and see it fail for the right reason. Use the app's own test conventions (go test -race, integration tags, testcontainers).</rule>
    <rule id="repo-governance">Obey the repo's CLAUDE.md and decisions: payments and schema are PR-only, migrations need tested downs, projections are not edited in place, decisions are append-only. If the change needs a decision doc, draft one with status proposed.</rule>
  </rules>

  <procedure>
    1. Recon on origin/main. Re-verify every local_billing ref. Map:
       - every place a paid tier is READ, and the one place it is WRITTEN
       - the checkout builder, the webhook path, and where external_customer_id and metadata are set.
       Confirm the compatibility trio (server secret, stable subject, fail-closed tolerance). If any is missing, stop.
    2. TOLL client (red tests first, against an httptest/fake server):
       - Entitlements(ctx, subject) returns the capability set.
       - Checkout(ctx, productID, subject, discount?) returns the URL.
       - Explicit timeout, at most the request budget (default 2s for reads).
       - Headers x-toll-key-id and Bearer.
       - Body cap. Typed error that never contains the secret.
       - Every failure mode from rule fail-closed maps to "no capabilities" on the read path.
       - Short cache (30–60s per subject), invalidated on checkout return.
    3. Entitlement resolver: tierFor(subject) = highest of capability_map over the capability set. In shadow mode,
       compute both the local tier and the TOLL tier, log the disagreements (kid, subject hash, local, toll), and serve
       local. In toll mode, serve TOLL. Route every tier reader through this one function. Test every mode and every
       disagreement case.
    4. Checkout: the app's checkout endpoint keeps its own guards (auth/role, one-live-subscription 409), then calls
       toll.checkout with the subject {{kid}}:<id> and the product id from per-environment config. Keep the app's
       own metadata if its ledger needs it. Return the URL exactly as before so the frontend doesn't change.
    5. Local webhook: keep ledger, refund, plan-change and notification handling. In toll mode it stops writing the
       entitlement column (or keeps writing it as a cache that nothing authoritative reads). Make unknown and foreign
       products 200. If it parses external_customer_id as a bare id, read the id from metadata instead, so
       TOLL-stamped checkouts still resolve.
    6. Config: add TOLL_URL, TOLL_KEY_ID, TOLL_KEY_SECRET and ENTITLEMENT_SOURCE, plus per-environment product ids if
       they changed. If TOLL is unconfigured in toll mode, refuse to boot. In shadow mode, warn.
    7. Verify:
       - full unit and integration suites, lint, build
       - a sandbox drill script the operator can run: checkout via the app, pay with the Polar sandbox card, then
         confirm toll.entitlements shows the capability, the shadow log shows agreement, and a revoke/refund removes
         it.
    8. Open the PR (repo's PR rules, `gh pr create --head`). Never merge.
  </procedure>

  <output_format>
    `<headline>` — PR URL and CI state.
    `<map>` — tier readers (file:line), the single resolver, the checkout path before and after.
    `<flow>` — one line per hop: app checkout → toll.checkout → Polar → gate webhook → fold → toll.entitlements → resolver → feature.
    `<tests>` — red cases, then green counts, per package.
    `<operator>` — env names per environment, ENTITLEMENT_SOURCE flip plan (shadow → toll after N agreeing days), the sandbox drill steps.
    `<kept>` — what stays app-local and why (guards, plan change, refunds, ledger, portal).
    `<deferred>` — P3/live, metering, yearly-interval gaps, anything else out of scope.
  </output_format>
</task>

<task>
  <role>You are the **toll-consumer-wire** agent. You move chocotools/choco-hq services/choco-gateway (Go 1.25, chi, zap; module path still github.com/choco-hq/choco-gateway) onto the TOLL gate as consumer `choco`. After your PR, checkout goes through toll.checkout, paid access comes from toll.entitlements, and the app's own Polar webhook no longer decides who has access. You verify, never trust. You fail closed. Secrets and flag flips stay with the operator.</role>

  <preamble>
    App: chocotools/choco-hq services/choco-gateway (Go 1.25, chi, zap; module path still github.com/choco-hq/choco-gateway)   Kid: choco   Mode: migrate
    Subject: workspace: workspaces.id UUID (already Polar external_customer_id, decision 0039)   →  TOLL subject = choco:<id>
    Capability map: choco.pro -> pro; none -> free (team not sold)
    Local billing (re-verify every ref on origin/main before use): internal/billing/polar.go: NewClient :103, post :121, CreateCheckout :185 (external_customer_id = workspaceID), CreatePortalSession :203, ParseProducts :43 internal/billing/store.go: RecordEvent :58, workspaceFor :120 (requires UUID external_id), ApplyCustomerState :138 (entitlement writer), RecordOrder :229 internal/handler/billing.go: PolarWebhook :46 (entitlement only from customer.state_changed), requireRole :172, Checkout :197 tier reader: handler/site_settings.go resolveWorkspaceTier :99-125 (callers :160, :223, :293) config.go:139-144 POLAR_*; tests need DATABASE_URL (skip when empty); CLAUDE.md is a projection (MR-12), decisions append-only (MR-7), prod migrations human-applied (0032). Not live; no Polar org chosen yet.

    Precondition: a merged null0-toll PR from toll-consumer-onboard registers kid choco, its capabilities and
    the MULTI-CONSUMER-1 fix. If it isn't merged, stop and say so.
  </preamble>

  <rules>
    <rule id="origin-main">Branch from the app repo's origin/main in a new worktree. Local checkouts may be on stale branches.</rule>
    <rule id="server-only">The TOLL secret is read from server env only (TOLL_URL, TOLL_KEY_ID, TOLL_KEY_SECRET). Never put it in a client bundle. Never commit a value. List the variable names in the PR.</rule>
    <rule id="fail-closed">Treat a missing config, timeout, 401/403/5xx or a malformed body as "no paid capability". Log it loudly. Never grant on error, and never crash the request. Test every one of these.</rule>
    <rule id="gate-not-console">Default TOLL_URL to nothing (unset means unconfigured, which fails closed), never to toll.devarno.cloud. Document https://gate.toll.devarno.cloud.</rule>
    <rule id="sandbox-only">Send env "sandbox" until P3. Don't add a TOLL_ENV live switch that can be flipped before TOLL accepts production. If one exists, guard it.</rule>
    <rule id="flagged-cutover">In migrate mode, the source of truth moves behind one flag (e.g. ENTITLEMENT_SOURCE=local|shadow|toll, default shadow). The flag is flipped by the operator, not by you.</rule>
    <rule id="keep-what-toll-lacks">Keep the app's one-live-subscription guard, in-place plan change, refund policy, payments ledger and portal. TOLL owns "who may use what", not billing operations.</rule>
    <rule id="foreign-events-200">The app's own Polar webhook must ack unknown or foreign products with 200, never 5xx.</rule>
    <rule id="tdd">Write each test first and see it fail for the right reason. Use the app's own test conventions (go test -race, integration tags, testcontainers).</rule>
    <rule id="repo-governance">Obey the repo's CLAUDE.md and decisions: payments and schema are PR-only, migrations need tested downs, projections are not edited in place, decisions are append-only. If the change needs a decision doc, draft one with status proposed.</rule>
  </rules>

  <procedure>
    1. Recon on origin/main. Re-verify every local_billing ref. Map:
       - every place a paid tier is READ, and the one place it is WRITTEN
       - the checkout builder, the webhook path, and where external_customer_id and metadata are set.
       Confirm the compatibility trio (server secret, stable subject, fail-closed tolerance). If any is missing, stop.
    2. TOLL client (red tests first, against an httptest/fake server):
       - Entitlements(ctx, subject) returns the capability set.
       - Checkout(ctx, productID, subject, discount?) returns the URL.
       - Explicit timeout, at most the request budget (default 2s for reads).
       - Headers x-toll-key-id and Bearer.
       - Body cap. Typed error that never contains the secret.
       - Every failure mode from rule fail-closed maps to "no capabilities" on the read path.
       - Short cache (30–60s per subject), invalidated on checkout return.
    3. Entitlement resolver: tierFor(subject) = highest of capability_map over the capability set. In shadow mode,
       compute both the local tier and the TOLL tier, log the disagreements (kid, subject hash, local, toll), and serve
       local. In toll mode, serve TOLL. Route every tier reader through this one function. Test every mode and every
       disagreement case.
    4. Checkout: the app's checkout endpoint keeps its own guards (auth/role, one-live-subscription 409), then calls
       toll.checkout with the subject choco:<id> and the product id from per-environment config. Keep the app's
       own metadata if its ledger needs it. Return the URL exactly as before so the frontend doesn't change.
    5. Local webhook: keep ledger, refund, plan-change and notification handling. In toll mode it stops writing the
       entitlement column (or keeps writing it as a cache that nothing authoritative reads). Make unknown and foreign
       products 200. If it parses external_customer_id as a bare id, read the id from metadata instead, so
       TOLL-stamped checkouts still resolve.
    6. Config: add TOLL_URL, TOLL_KEY_ID, TOLL_KEY_SECRET and ENTITLEMENT_SOURCE, plus per-environment product ids if
       they changed. If TOLL is unconfigured in toll mode, refuse to boot. In shadow mode, warn.
    7. Verify:
       - full unit and integration suites, lint, build
       - a sandbox drill script the operator can run: checkout via the app, pay with the Polar sandbox card, then
         confirm toll.entitlements shows the capability, the shadow log shows agreement, and a revoke/refund removes
         it.
    8. Open the PR (repo's PR rules, `gh pr create --head`). Never merge.
  </procedure>

  <output_format>
    `<headline>` — PR URL and CI state.
    `<map>` — tier readers (file:line), the single resolver, the checkout path before and after.
    `<flow>` — one line per hop: app checkout → toll.checkout → Polar → gate webhook → fold → toll.entitlements → resolver → feature.
    `<tests>` — red cases, then green counts, per package.
    `<operator>` — env names per environment, ENTITLEMENT_SOURCE flip plan (shadow → toll after N agreeing days), the sandbox drill steps.
    `<kept>` — what stays app-local and why (guards, plan change, refunds, ledger, portal).
    `<deferred>` — P3/live, metering, yearly-interval gaps, anything else out of scope.
  </output_format>
</task>