voidmachine 6.0.0 → 7.0.1

package/core-assets/packs/pack-monorepo/skills/void-dependency-direction/SKILL.md

@@ -1,160 +1,41 @@
 ---
 name: void-dependency-direction
-description: Enforce the @repo/* import direction in a Turborepo workspace. Concrete violations + fixes. Composes with core:hexagonal-architecture and the boundary-direction-check hook.
+description: Declare cross-package dependencies explicitly and preserve domain-owned ports. Use when crossing a workspace package boundary or fixing boundary-direction-check.
 ---
 
 # dependency-direction
 
-Use when adding an `import` statement that crosses a package boundary, or when fixing a `boundary-direction-check` hook violation. This skill is the **operational guide** for the rules core `void-hexagonal-architecture` and `boundary-direction-check` enforce mechanically.
+The package's `package.json` owns its permitted package dependencies. The project's
+architecture owns which dependencies make sense. A universal star topology through
+`@repo/core` is not imposed by the harness.
 
-## The rule
+## Before adding an import
 
-```
-@repo/core    →   nothing internal
-@repo/auth    →   @repo/core
-@repo/db      →   @repo/core
-@repo/ui      →   @repo/core
-@repo/<feat>  →   @repo/core   (and only @repo/core)
-apps/<app>    →   any @repo/*
-```
+1. Read the consuming package's manifest and project architecture.
+2. Keep domain code independent of concrete infrastructure; compose adapters through
+   domain-owned ports, per `void-hexagonal-architecture`.
+3. Declare an accepted dependency in the appropriate manifest section. Types create
+   dependencies too. Import the package's public API, not a sibling's private files.
+4. If the dependency would violate an accepted project boundary, reshape the port
+   and compose at the application edge. A structural exception follows `void-decide`.
+5. Run the affected package's typecheck and behavior tests.
 
-**No `@repo/*` package imports another `@repo/*` except `@repo/core`.** All composition happens at the app level. If `@repo/billing` needs the user, it defines a port; the consuming app wires `@repo/auth`'s adapter into that port.
+## Mechanical scope
 
-This sounds restrictive. It is. It is what keeps the monorepo from collapsing into a hairball.
+The shared Node `boundary-direction-check` rule rejects detected scoped imports
+that the nearest readable package manifest does not declare. It accepts self-imports
+and dependencies, devDependencies, peerDependencies and optionalDependencies.
+It skips tests/generated files and allows when no manifest can be read. Its lexical
+matcher is a guardrail, not a complete import graph or internal-layer validator.
+An `allow-boundary:` comment is a narrow escape recognized by the existing rule;
+it does not approve an architectural exception or make a missing dependency buildable.
 
-## Why core is the only allowed dependency
-
-`@repo/core` ships **primitives** with no internal deps:
-
-- `logger` (pino)
-- `env` (Zod-validated env)
-- `errors` (typed error classes)
-- `Result`, `Option`, `pipe` (functional utilities)
-
-These are leaf utilities. Everything else is composition.
-
-## Common violation: `@repo/billing` wants the user
-
-**Wrong**:
-```ts
-// packages/billing/src/billing.service.ts
-import { db } from '@repo/db';                  // ✗
-import { getCurrentUser } from '@repo/auth';    // ✗
-
-export async function cancelSubscription() {
-  const user = await getCurrentUser();
-  await db.update(subscriptions)...
-}
-```
-
-**Right** — define the port in `@repo/billing`, wire the adapter in the app:
-
-```ts
-// packages/billing/src/billing.types.ts (port)
-export interface BillingPorts {
-  readonly userRepo: { findById(id: string): Promise<User | null> };
-  readonly subscriptionRepo: { update(id: string, p: Partial<Sub>): Promise<void> };
-}
-
-// packages/billing/src/billing.service.ts (pure)
-export function makeBillingService(ports: BillingPorts) {
-  return {
-    async cancelSubscription(userId: string) {
-      const user = await ports.userRepo.findById(userId);
-      // ... domain logic only
-    },
-  };
-}
-
-// apps/web/src/adapters/billing.ts (composition)
-import { makeBillingService } from '@repo/billing';
-import { db } from '@repo/db';
-import { userRepo, subRepo } from '@/repositories';
-export const billing = makeBillingService({ userRepo, subscriptionRepo: subRepo });
-```
-
-The app is the integration point. Packages are pure capabilities.
-
-## Common violation: types from another package
-
-**Wrong**:
-```ts
-// packages/billing/src/billing.types.ts
-import type { User } from '@repo/auth';  // ✗ types still create coupling
-```
-
-**Right** — declare your own User type narrowed to what billing needs:
-
-```ts
-// packages/billing/src/billing.types.ts
-export interface BillingUser {
-  readonly id: string;
-  readonly email: string;
-  readonly orgId: string;
-}
-```
-
-If `@repo/auth`'s `User` and `@repo/billing`'s `BillingUser` should be the same shape, factor the shape into `@repo/core/types`. But almost always, each package wants a narrower projection — that's good.
-
-## Common violation: `@repo/ui` calls a service
-
-**Wrong**:
-```tsx
-// packages/ui/src/UserAvatar.tsx
-import { getCurrentUser } from '@repo/auth';   // ✗
-export function UserAvatar() {
-  const user = use(getCurrentUser());          // ✗ side effect in UI
-  return <Avatar src={user.avatarUrl} />;
-}
-```
-
-**Right**:
-```tsx
-// packages/ui/src/Avatar.tsx (dumb prop-driven)
-export function Avatar({ src, fallback }: { src: string; fallback: string }) {
-  return <img src={src} alt={fallback} />;
-}
-
-// apps/web/src/components/CurrentUserAvatar.tsx (binding, NOT in @repo/ui)
-import { Avatar } from '@repo/ui';
-import { useCurrentUser } from '@/hooks';
-export function CurrentUserAvatar() {
-  const user = useCurrentUser();
-  return <Avatar src={user.avatarUrl} fallback={user.name} />;
-}
-```
-
-`@repo/ui` exports primitives with no I/O. Bindings to actual data live in apps.
-
-## The `apps/<app>` → `apps/<other-app>` rule
-
-**Never** import from another app:
-
-```ts
-// apps/web/src/foo.ts
-import { whatever } from '../../mobile/src/...';  // ✗ — even via @repo/* alias if you set it up
-```
-
-If two apps need the same code, that code goes in a `@repo/*` package. There is no "shared/" directory between apps.
-
-## When you genuinely need cross-package access
-
-You don't. Re-read the section on ports. If after that you still think you do, write an ADR (`void-decide`) documenting the exception with the reversal cost. 90% of "I need this" turns out to be "I forgot to define the port".
-
-## Mechanical enforcement
-
-The `boundary-direction-check` hook (core) blocks Edit/Write that introduces a forbidden import. Override by tagging the import line `// allow-boundary: <reason>` — but think hard first, because each exception is a small future grind.
-
-## Workflow
-
-1. **Before adding the import**, ask: does this cross a `@repo/*` boundary?
-2. **If yes**, ask: is the destination `@repo/core`? OK. Anything else? Stop.
-3. **Define a port** in your package, wire the adapter in the app.
-4. **If the hook complains**, do not tag-and-move-on. Refactor.
+A `tsconfig` path alias changes resolution, not permission. It cannot prove a
+package boundary. Project-specific cycle or layer checks must be explicitly wired
+and verified before claiming deterministic enforcement.
 
 ## Composition
 
-- `void-hexagonal-architecture` — doctrine on ports + adapters direction (core).
-- `boundary-direction-check` hook (core) — mechanical gate.
-- `void-package-extraction` — most boundary problems come from premature extraction.
-- `void-service-package` — the 5+5 layout includes a `<name>.types.ts` precisely for owning your own types.
+- `void-hexagonal-architecture` owns ports and dependency direction inside a domain.
+- `void-service-package` applies the project package layout.
+- `void-package-extraction` decides whether a shared package is warranted.

package/core-assets/packs/pack-monorepo/skills/void-service-package/SKILL.md

@@ -52,15 +52,12 @@ service ─→ repository (port)   service ─→ helper   service ─→ types
 
 If your package needs `@repo/db` directly: stop. Move the DB-touching code into an adapter in the consuming app. The package owns the **port**, not the adapter.
 
-## Allowed imports (enforced by `boundary-direction-check`)
+## Allowed imports
 
-| This package | May import |
-|---|---|
-| `@repo/<name>` | `@repo/core` (logger, env, errors, Result/Option/pipe). Nothing else `@repo/*`. |
-
-If you find yourself needing to import another `@repo/*`, you are blurring layers. Two valid fixes:
-- Move the shared concept into `@repo/core`
-- Reshape the boundary so the consumer composes the two packages explicitly
+Follow `void-dependency-direction`: the package manifest declares dependencies;
+the project's architecture decides whether they belong. This service convention
+prefers domain-owned ports and app composition. It does not claim the shared hook
+forbids every dependency except `@repo/core`.
 
 ## `package.json` template
 

package/core-assets/packs/pack-server/skills/void-webhook-handler-pattern/.source

@@ -1,7 +1,9 @@
 Sources for `void-webhook-handler-pattern` skill (see `docs/plans/skill-audits/void-webhook-handler-pattern.md` for the full audit):
 
-- No external source audited — native distillation of canonical per-source webhook patterns.
-- Per-source patterns referenced (not vendored): Stripe, Resend, GitHub signature/idempotency/retry semantics.
+- Official provider contracts checked for the 2026-10-30 coherence correction:
+- Stripe: https://docs.stripe.com/webhooks#preventing-replay-attacks
+- GitHub: https://docs.github.com/en/webhooks/using-webhooks/handling-failed-webhook-deliveries
+- Provider code is not vendored; verifier and durable store remain consumer-owned.
 - Doctrine referenced: `void-async-safety` (stack-agnostic retry/idempotency/dead-letter).
 
 Strategy: distill. Per-source handler patterns distilled into the 5 non-negotiable layers; no upstream skill was copied.

package/core-assets/packs/pack-server/skills/void-webhook-handler-pattern/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: void-webhook-handler-pattern
-description: Build a webhook handler with signature verification, idempotency, and dead-letter routing. Per-source patterns (Stripe, Resend, GitHub). Self-contained — no harness wrappers required.
+description: Build a webhook handler with signature verification, idempotency, and dead-letter routing. Per-source patterns (Stripe, Resend, GitHub). Uses the shared async-safety contract.
 ---
 
 # webhook-handler-pattern
@@ -15,91 +15,22 @@ apps/<app>/src/app/api/webhooks/<source>/route.ts
 
 One folder per source. Path stable (external systems POST to a fixed URL — never rename without coordinating).
 
-## The 5 non-negotiable layers
+## Handler contract
 
-```
-1. Signature verification  — verify the event came from the source
-2. Idempotency             — same event delivered twice = one effect
-3. Zod validation          — parsed shape matches what handler expects
-4. Service call            — the business work (in apps/<app>/src/services/)
-5. Acknowledgment          — return 2xx on success; specific codes on failure
-```
+Compose `void-async-safety` for the canonical executable `withWebhookSafety` example
+and its `IdempotencyStore` contract. Keep signature/freshness verification in the provider
+SDK adapter, validate its decoded data at that boundary, and map the typed outcome to HTTP.
+Do not copy a second verify/claim/handle/mark implementation into this skill.
 
-Skipping ANY of these is a Sev-2 waiting. The pattern below shows the 5 layers explicit — no wrapper assumed.
-
-## Canonical handler (explicit, self-contained)
-
-```ts
-// apps/web/src/app/api/webhooks/stripe/route.ts
-import { NextRequest, NextResponse } from 'next/server';
-import Stripe from 'stripe';
-import { z } from 'zod';
-import { db } from '@/adapters/db';
-import { env, logger } from '@repo/core';
-import * as Sentry from '@sentry/nextjs';
-import { handleStripeEvent } from '@/services/billing/stripe';
-
-const stripe = new Stripe(env.STRIPE_SECRET_KEY);
-
-// 3. Zod schema for the parsed Stripe event (defense in depth — Stripe's
-//    own parser is trusted, but we re-shape to our service contract).
-const EventSchema = z.object({
-  id: z.string(),
-  type: z.string(),
-  data: z.object({ object: z.unknown() }),
-  livemode: z.boolean(),
-});
-
-export async function POST(req: NextRequest) {
-  const sig = req.headers.get('stripe-signature');
-  const body = await req.text();
-  const idempotencyKey = `stripe:${req.headers.get('stripe-signature')?.slice(0, 16) ?? ''}`;
-
-  let stripeEvent: Stripe.Event;
-  try {
-    // 1. Signature verification (Stripe-specific)
-    if (!sig) {
-      return NextResponse.json({ error: 'missing signature' }, { status: 401 });
-    }
-    stripeEvent = stripe.webhooks.constructEvent(body, sig, env.STRIPE_WEBHOOK_SECRET);
-  } catch (err) {
-    logger.warn({ event: 'webhook.signature_invalid', source: 'stripe' });
-    return NextResponse.json({ error: 'invalid signature' }, { status: 401 });
-  }
-
-  // 2. Idempotency — Stripe's event.id is globally unique
-  const inboxKey = `stripe:${stripeEvent.id}`;
-  const inserted = await db
-    .insert(webhookInbox)
-    .values({ key: inboxKey, source: 'stripe', eventType: stripeEvent.type, payload: stripeEvent })
-    .onConflictDoNothing()
-    .returning();
-
-  if (inserted.length === 0) {
-    // Already seen — return 2xx to stop Stripe retrying
-    logger.info({ event: 'webhook.duplicate', source: 'stripe', eventId: stripeEvent.id });
-    return NextResponse.json({ ok: true, duplicate: true });
-  }
-
-  // 3. Re-validate with our schema
-  const event = EventSchema.parse(stripeEvent);
-
-  // 4. Service call — pure dispatch
-  logger.info({ event: 'webhook.received', source: 'stripe', type: event.type, eventId: event.id });
-  try {
-    await handleStripeEvent(event);
-    await db.update(webhookInbox).set({ committedAt: new Date() }).where(eq(webhookInbox.key, inboxKey));
-    // 5. Ack
-    return NextResponse.json({ ok: true });
-  } catch (err) {
-    Sentry.captureException(err, { tags: { webhook: 'stripe', eventType: event.type } });
-    // Retryable: return 5xx so Stripe retries with backoff
-    return NextResponse.json({ ok: false }, { status: 500 });
-  }
-}
-```
+The handler's business effects and deduplication must share a transaction/outbox or use
+the same stable idempotency key. A received or pending inbox row is **not** proof of a
+completed event. Failed processing and failed completion persistence remain non-success
+and retryable; only completed events may be acknowledged as duplicates. An in-flight
+concurrent delivery must not report that unfinished processing as success.
 
-The 5 layers are explicit. No wrapper is required. If your project ships its own `withWebhookSafety` helper that bundles these 5, that's a convenience — but the pattern is the substance, and it's the same.
+A project may provide its own wrapper with this contract. The optional Next.js pack
+exports the tested implementation; it does not supply the project's verifier or durable
+store. No universal event-age limit is invented by the wrapper.
 
 ## Per-source notes
 
@@ -114,13 +45,13 @@ The 5 layers are explicit. No wrapper is required. If your project ships its own
 
 - Signature: `svix-id`, `svix-timestamp`, `svix-signature` headers → `new Webhook(secret).verify(body, headers)` from `svix` package
 - Idempotency: `svix-id` header
-- Retry: Svix retries automatically; you only see the first failure if your endpoint returns 5xx
+- Retry: use the provider's current retry schedule and delivery diagnostics; do not infer completion from receipt.
 
 ### GitHub
 
 - Signature: `x-hub-signature-256` header (HMAC SHA-256 of the body with your secret)
 - Idempotency: `x-github-delivery` header (UUID)
-- Retry: GitHub does NOT auto-retry. If you return 5xx, the event is lost. Make sure dead-letter is robust.
+- Retry: GitHub does not automatically redeliver failed deliveries; arrange manual or automated redelivery from its delivery records. A failure response is not durable acceptance.
 
 ### Custom (internal services calling each other)
 
@@ -128,64 +59,33 @@ The 5 layers are explicit. No wrapper is required. If your project ships its own
 - Idempotency: caller-generated UUID v7 in `x-idempotency-key`
 - Retry: caller's responsibility; receiver acknowledges with 2xx + the key it already saw
 
-## Inbox table
+## Durable inbox
 
-The idempotency check needs persistent storage:
-
-```sql
-CREATE TABLE webhook_inbox (
-  key text PRIMARY KEY,                         -- e.g., "stripe:evt_xxx"
-  source text NOT NULL,
-  event_type text NOT NULL,
-  received_at timestamptz NOT NULL DEFAULT now(),
-  committed_at timestamptz,
-  payload jsonb NOT NULL
-);
-CREATE INDEX idx_webhook_inbox_received ON webhook_inbox (received_at);
-```
-
-Migration follows the safe-migration pattern (see `void-drizzle-migration-safe` skill).
+Use the application's existing durable store following `void-async-safety`. Its state
+must distinguish pending claims from completed events and release/expire failed claims
+for retry. A unique key alone cannot express completion. Apply schema changes through
+`void-drizzle-migration-safe`; this skill supplies no independently evolving SQL schema.
 
 ## Dead-letter routing
 
-When the handler decides the error is permanent (validation failure, downstream API said 4xx):
-
-```ts
-catch (err) {
-  if (isPermanentFailure(err)) {
-    await db.insert(webhookDeadLetter).values({
-      key: inboxKey,
-      source: 'stripe',
-      error: err.message,
-      payload: event,
-      receivedAt: new Date(),
-    });
-    return NextResponse.json({ ok: false, retry: false }, { status: 400 });
-    // 4xx tells Stripe "permanent — stop retrying"
-  }
-  throw err;   // retryable — let the 5xx propagate
-}
-```
-
-Dead letter = a queue/table the team reviews. UI: `Settings → Webhook DLQ`. Never silently drop.
-
-## Error response codes
+A permanent failure may be recorded in a durable dead-letter destination for an operator
+before applying the provider's acknowledgment policy. Never interpret an HTTP status as
+a universal instruction to stop delivery: Stripe retries non-2xx responses, including 4xx;
+GitHub does not automatically redeliver failures. Keep provider-specific retries explicit.
+Never acknowledge a malformed event as successfully processed or silently drop a failure.
 
-| Code | Means | Sender behavior |
-|---|---|---|
-| 200/202 | Accepted | Stops retrying |
-| 401 | Invalid signature | Stops retrying (Stripe, GitHub will flag the endpoint) |
-| 4xx (other) | Permanent failure (bad event shape) | Stops retrying — log this for investigation |
-| 5xx | Transient failure | Retries with backoff (Stripe/Svix); GitHub doesn't retry |
+## Error responses
 
-NEVER return 200 to a malformed event (you'd accept invalid data). 4xx with a logged DLQ entry is the right pattern.
+The canonical wrapper rejects verifier failures with 400 and returns 500 for handler or
+store failures. The HTTP adapter preserves those outcomes. A 200 means completed work or
+a previously completed duplicate, never an in-progress claim. If a queue/outbox is used,
+its separate acceptance contract must mean durable responsibility for eventual processing.
 
 ## Anti-patterns
 
 - ✗ **No signature verification** — anyone with the URL can forge events
 - ✗ **Idempotency key = `Date.now()`** — re-delivery NOT detected; double-charges
-- ✗ **Calling services synchronously for slow work** — if the handler takes > 10s, the sender retries. Enqueue background jobs for slow work (see `void-background-job-pattern`).
-- ✗ **Returning 5xx to "make sender retry" without enqueueing** — sender's backoff is unpredictable; use your own queue
+- ✗ **Calling services synchronously for slow work** — work exceeding the provider's response deadline is a failed delivery; retry policy varies by provider. Enqueue background jobs for slow work (see `void-background-job-pattern`).
 - ✗ **One handler for all sources** (`/api/webhooks/route.ts` switching on `source`) — different signatures, different idempotency keys, different retry semantics. One folder per source.
 - ✗ **`==` for HMAC comparison** — use `crypto.timingSafeEqual`. Constant-time compare prevents timing attacks.
 

package/core-assets/skills/void-accessibility/SKILL.md

@@ -198,7 +198,7 @@ Every UI is designed mobile-first AND must reach first-class quality on both vie
 - No mobile-only nor desktop-only features without an explicit decision recorded through the `void-decide` skill.
 - Both viewports screenshot-reviewed before merge.
 
-The companion `viewport-screenshot-gate` hook (shared with `void-frontend-design`) fails PRs lacking both screenshots.
+The companion `viewport-screenshot-gate` hook (shared with `void-frontend-design`) is an optional PR-text heuristic; it does not validate images or enforce a native/CI gate. Review the actual mobile and desktop captures before merge.
 
 ---
 
@@ -229,7 +229,7 @@ The design system handles this by default in `pack-nextjs`. Specific animations
 ## Companion hooks
 
 - `axe-precommit` (pre-commit on UI changes) — axe-core static analysis, blocks on AA violations. ≤ 80 LOC.
-- `viewport-screenshot-gate` (pre-PR on UI changes, shared with `void-frontend-design`) — fails PRs lacking both mobile and desktop screenshots. ≤ 60 LOC.
+- `viewport-screenshot-gate` (pre-PR on UI changes, shared with `void-frontend-design`) — optional PR-text heuristic, not a wired native/CI gate or image validation. Review actual captures.
 
 ---
 

package/core-assets/skills/void-async-safety/SKILL.md

@@ -23,7 +23,7 @@ Exactly-once delivery requires two-phase commits across systems — extreme effo
 
 Every webhook handler does FOUR things, IN THIS ORDER:
 
-1. **Verify signature** (HMAC + timestamp window)
+1. **Verify authenticity and replay policy** using the provider contract (authenticated timestamp when available)
 2. **Check idempotency key** (claim atomically; if already processed, return success without re-processing)
 3. **Handle the event** (business logic)
 4. **Mark idempotency key as completed** (or release on failure for retry)
@@ -31,55 +31,68 @@ Every webhook handler does FOUR things, IN THIS ORDER:
 The `pack-nextjs` provides a `withWebhookSafety()` wrapper:
 
 ```typescript
-import { withWebhookSafety } from '@repo/async';
+import { withWebhookSafety } from '@voidcorp/pack-nextjs/async';
 
-export const POST = withWebhookSafety({
+const handleWebhook = withWebhookSafety({
   verify: (req) => verifyStripeSignature(req, env.STRIPE_WEBHOOK_SECRET),
   dedupKey: (event) => event.id,                  // Stripe event ID
-  replayWindowMs: 5 * 60 * 1000,                  // 5 minutes
   store: stripeIdempotencyStore,                  // injected
   handler: async (event) => handleStripeEvent(deps, event),
 });
+
+export async function POST(req: Request): Promise<Response> {
+  const outcome = await handleWebhook(req);
+  return Response.json(outcome.body, { status: outcome.status });
+}
 ```
 
-The wrapper enforces the order. Business handler stays pure.
+The wrapper owns verify → claim → handle → mark and returns a typed outcome; the HTTP
+adapter maps its status and body. Verification and handling return `Result`, not an
+untyped event or success by absence of an exception. Signature verification belongs to
+the provider SDK adapter passed as `verify`; it runs before any claim or business effect.
 
 ### Replay window enforcement
 
-Reject events older than the configured window (default 5 minutes). Stripe and most webhook sources include a timestamp; the wrapper checks it. Composes with `void-security-guidance` (replay attack protection).
+The verifier must use the provider SDK's authenticated delivery metadata and freshness policy.
+For Stripe, check the signed delivery timestamp through its SDK; do not reject an old
+business event merely because its creation time is old. Retries are new signed deliveries.
+The wrapper has no `replayWindowMs` option and supplies no universal five-minute policy.
+A verifier failure is rejected before deduplication or business handling. Providers without
+a signed timestamp require their documented replay/deduplication policy, not a fabricated
+timestamp check. See the provider reference in this skill's `.source`.
 
 ### Banned
 
 - State mutation BEFORE signature verification.
 - Hand-rolled signature check (use the wrapper / the provider's official lib).
 - In-memory `Set` for dedup (lost on process restart).
-- No replay window (forever-replayable).
+- Ignoring the provider's authenticated freshness policy when one exists, or omitting durable event deduplication.
 
 ---
 
 ## Idempotency keys — port + store
 
-`IdempotencyStore` is a port (composes with `void-hexagonal-architecture`):
-
-```typescript
-interface IdempotencyStore {
-  tryClaim(key: string, ttl: Duration): Promise<Result<'claimed' | 'already-processed', StoreError>>;
-  markCompleted(key: string): Promise<Result<void, StoreError>>;
-  release(key: string): Promise<Result<void, StoreError>>;
-}
-```
-
-Adapters (provided by packs):
+The exported `IdempotencyStore` in `@voidcorp/pack-nextjs/async` owns this contract:
 
-- **Redis adapter** — high volume, low latency
-- **Postgres adapter** — default for low-volume webhooks (uses `INSERT ... ON CONFLICT DO NOTHING` for atomic claim)
-- **In-memory adapter** — tests only (composes with `void-testing` nullable infrastructure)
+- `tryClaim` atomically claims a new key. `already-processed` means **completed**, never
+  merely received or in progress. A pending claim returns a retryable store error.
+- A failed handler releases its claim. A failed completion write returns non-success and
+  releases for retry. Release failure never turns the operation into success.
+- The consumer provides a durable adapter; the harness does not ship a Redis/Postgres store.
+  Tests may use an in-memory implementation of the same contract.
+- A claim cannot make an external effect atomic with its completion record. Use a shared
+  transaction/outbox where possible, or make the business effect idempotent by the stable
+  event key. After an uncertain completion, a retry may execute the handler again.
 
-The store is the consumer dedup substrate. Process restart does not lose claims.
+Do not implement deduplication as "inbox row exists → acknowledge": an unfinished row
+must remain retryable. This is the single safety contract used by the webhook handler skill.
 
-### Default TTL: 7 days
+### Deduplication retention
 
-Long enough for most provider retry windows. Override per handler.
+Choose retention from the provider's automatic and manual redelivery windows and the
+business invariant. The wrapper passes `dedupTtlMs` (default seven days) to the
+store; the durable adapter must enforce that retention. Override it when the
+provider contract or business invariant requires a longer window.
 
 ---