voidmachine 0.0.0 → 4.0.0

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

@@ -0,0 +1,287 @@
+---
+name: void-async-safety
+description: Idempotency by design. At-least-once with consumer dedup. Signature verify, replay window, idempotency keys, outbox, bounded retries, DLQ. Use for async/webhook/job/cron code.
+---
+
+# async-safety — voidcorp craftsman edition
+
+The network is unreliable. Webhooks redeliver. Jobs restart mid-run. Crons stack when one runs slow. Without idempotency by design, every re-delivery becomes a corruption risk. This skill codifies the patterns so handlers are safe by construction.
+
+**Attribution**: see `.source`. Foundation: Stripe webhook patterns + Outbox pattern (Microservices.io) + Pat Helland "Life Beyond Distributed Transactions" + Bryan Cantrill on distributed failure modes.
+
+---
+
+## At-least-once is the default
+
+Assume every message can be delivered N times. The consumer handles dedup.
+
+Exactly-once delivery requires two-phase commits across systems — extreme effort, rarely worth it. At-least-once + consumer dedup covers > 99% of real cases at a fraction of the cost.
+
+---
+
+## Webhook safety — the canonical pattern
+
+Every webhook handler does FOUR things, IN THIS ORDER:
+
+1. **Verify signature** (HMAC + timestamp window)
+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)
+
+The `pack-nextjs` provides a `withWebhookSafety()` wrapper:
+
+```typescript
+import { withWebhookSafety } from '@repo/async';
+
+export const POST = 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),
+});
+```
+
+The wrapper enforces the order. Business handler stays pure.
+
+### 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).
+
+### 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).
+
+---
+
+## 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):
+
+- **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)
+
+The store is the consumer dedup substrate. Process restart does not lose claims.
+
+### Default TTL: 7 days
+
+Long enough for most provider retry windows. Override per handler.
+
+---
+
+## Outbox pattern — for "DB write + external notification"
+
+When a business operation must (a) update the DB AND (b) notify an external system, doing them in sequence creates an inconsistency window:
+
+```typescript
+// banned (without outbox)
+await db.transaction(async (tx) => {
+  await tx.insert(orders).values(order);
+});
+await stripe.refunds.create({ charge: order.chargeId });
+// if Stripe call fails, DB has the refund record but Stripe doesn't
+```
+
+### With outbox
+
+The DB write AND the "event to publish" sit in the SAME transaction:
+
+```typescript
+await db.transaction(async (tx) => {
+  await tx.insert(orders).values(order);
+  await tx.insert(domain_events).values({
+    aggregate_id: order.id,
+    event_type: 'OrderRefunded',
+    payload: { chargeId: order.chargeId, amount: order.amount },
+  });
+});
+
+// later: a background dispatcher reads domain_events and publishes
+//        (composes with the outbox dispatcher in pack-monorepo / pack-nextjs)
+```
+
+If the transaction commits, the event is durable. If it fails, neither happened. The dispatcher retries the publish until success.
+
+The `domain_events` table schema lives in `pack-monorepo` (composes with `void-migrations`).
+
+---
+
+## Fail-soft outbound HTTP — for a third party you don't control
+
+The outbox is for a write that **must** eventually happen. The mirror case is a **read** on the request path that you can survive without: an FX rate, a recommendation, an enrichment lookup. A synchronous call to a vendor you don't control must never be allowed to hang or fail the whole request when that vendor is slow or down.
+
+```typescript
+// banned: no timeout, no fallback — a flaky vendor takes down your request
+const rates = await fetch('https://fx.example/rates').then((r) => r.json());
+
+// fail-soft: bounded time + graceful degrade
+async function getRates(cache: RatesCache): Promise<Rates> {
+  try {
+    const res = await fetch('https://fx.example/rates', { signal: AbortSignal.timeout(2000) });
+    if (!res.ok) throw new Error(`fx ${res.status}`);
+    const rates = parseRates(await res.json());
+    await cache.set(rates); // refresh the fallback for next time
+    return rates;
+  } catch (err) {
+    logger.warn('fx rates degraded, serving last-known', { err }); // observable, not silent
+    return cache.getLastKnown() ?? DEFAULT_RATES; // degrade, do not fail the request
+  }
+}
+```
+
+Three rules:
+
+1. **Always bound the time** — `AbortSignal.timeout(ms)`. An unbounded `fetch` inherits the vendor's worst day.
+2. **Retry only idempotent reads, with a cap** — a bounded retry (2-3, with backoff) for a GET; never auto-retry a non-idempotent POST (that is the outbox's job, with a dedup key).
+3. **Decide critical vs degradable up front.** Critical (payment authorize) → surface the failure to the caller, do not fake success. Degradable (rates, recommendations) → fall back to a cached/default value and log the degradation. The failure mode is a deliberate choice, never an unhandled throw.
+
+This composes with `void-observability` (the degradation is a structured warn, never swallowed) and `void-functional` (the outcome is a value — `Rates` or the fallback — not an exception that escapes the boundary).
+
+---
+
+## Job safety — the canonical pattern
+
+Same shape as webhooks, with explicit state machine (composes with `void-functional` discriminated unions):
+
+```typescript
+type JobState =
+  | { kind: 'queued'; id: JobId; payload: unknown; queuedAt: IsoDate }
+  | { kind: 'in-flight'; id: JobId; startedAt: IsoDate; attempt: number }
+  | { kind: 'completed'; id: JobId; completedAt: IsoDate; result: unknown }
+  | { kind: 'failed'; id: JobId; failedAt: IsoDate; attempt: number; lastError: string }
+  | { kind: 'dead-lettered'; id: JobId; finalError: string; attempts: number };
+```
+
+Transitions are explicit. No "did it succeed? unclear" state.
+
+The target shape is a `withJobSafety()` wrapper. **Not yet shipped** — `pack-nextjs`
+ships `withWebhookSafety` today; `withJobSafety` / `withCronSafety` are the planned
+Phase E form (see the pack README). Until they land, apply this shape by hand; do
+not import a wrapper that does not exist yet.
+
+```typescript
+export const refundOrderJob = withJobSafety({
+  dedupKey: (input) => `refund:${input.orderId}`,
+  maxAttempts: 5,
+  backoff: 'exponential-with-jitter',
+  store: jobIdempotencyStore,
+  handler: async (input) => refundOrder(deps, input),
+});
+```
+
+---
+
+## Retries — exponential backoff + jitter
+
+```
+attempt 1: 1s + jitter(0–1s)
+attempt 2: 2s + jitter(0–2s)
+attempt 3: 4s + jitter(0–4s)
+attempt 4: 8s + jitter(0–8s)
+attempt 5: 16s + jitter(0–16s)
+DLQ
+```
+
+Jitter prevents thundering herd (multiple jobs failing simultaneously and retrying in sync).
+
+### Max attempts default: 3–5
+
+After exhaustion, dead-letter and alert. Beyond that, the failure is structural; a human must look.
+
+### Banned
+
+- Unbounded retries
+- Custom retry loops in business code (use the queue library's semantics)
+- Catching exceptions and silently retrying
+
+---
+
+## Cron safety — overlap protection
+
+Same status as `withJobSafety` above: `withCronSafety` is the planned Phase E shape,
+not yet shipped by `pack-nextjs`. Apply it by hand until it lands.
+
+```typescript
+export const dailyReportCron = withCronSafety({
+  name: 'daily-report',
+  overlapStrategy: 'skip-if-running',  // or 'queue-up'
+  handler: async () => generateDailyReport(deps),
+});
+```
+
+The wrapper acquires a Postgres advisory lock keyed by cron name. If the previous run is still in flight, skip with a structured log entry. Composes with `void-observability`.
+
+### Banned
+
+- Cron jobs that take longer than the cron interval without overlap protection — they will stack and crash the workers.
+
+---
+
+## Composition with other skills
+
+- **With `void-observability`**: trace propagates across job / webhook / queue boundaries via the message envelope. Job lifecycle events (queued / in-flight / completed / failed / dead-lettered) are structured logs.
+- **With `void-security-guidance`**: signature verification + replay window + signed message envelopes.
+- **With `void-migrations`**: `domain_events` outbox table schema goes through the migrations discipline.
+- **With `void-tdd`**: idempotency is testable. Test: same event delivered twice → same final state. Test: signature missing → reject.
+- **With `void-hexagonal-architecture`**: webhook handler at adapter boundary, business logic in use-case. `IdempotencyStore` as port.
+- **With `void-functional`**: job state as discriminated union. `Result<JobOutcome, JobError>` everywhere.
+- **With `void-code-review`**: flags missing signature verification, missing idempotency check, save-then-publish without outbox, custom retry loops in business code.
+- **With `void-commit-discipline`**: webhook handler commits' "why" mentions the provider + the idempotency strategy.
+
+---
+
+## Companion hooks
+
+None directly in core. The discipline is encoded in `pack-monorepo` / `pack-nextjs` wrappers (`withWebhookSafety`, `withJobSafety`, `withCronSafety`) and surfaced via `void-code-review` flags.
+
+---
+
+## Anti-rules
+
+- MUST NOT decide queue technology (pack concern — BullMQ vs Inngest vs Trigger.dev vs Vercel Cron).
+- MUST NOT decide alerting thresholds (ops concern).
+- MUST NOT silently allow non-idempotent handlers.
+- MUST NOT skip signature verification.
+- MUST NOT use in-memory dedup that loses state on restart.
+- MUST NOT permit unbounded retries.
+- MUST NOT skip the outbox pattern when DB + external are both modified.
+- MUST NOT call an outbound third party on the request path without a timeout and a decided failure mode (surface if critical, degrade if not).
+
+---
+
+## When you are stuck
+
+| Problem | Solution |
+|---|---|
+| Same Stripe event processed twice | Idempotency key not stored, or check happens after mutation. Order: verify → dedup → handle. |
+| Webhook handler slow → timeout → retry → duplicate work | Make handler fast: enqueue a job and return 200 immediately. The job handles idempotency. |
+| A vendor API call sometimes hangs and stalls the whole request | Bound it with `AbortSignal.timeout`; decide critical (surface) vs degradable (cached/default fallback + a warn log). See "Fail-soft outbound HTTP". |
+| Job lost after worker crash | Queue lib should re-deliver. Verify your queue is durable (BullMQ default is durable). |
+| Cron stacking | `withCronSafety()` with skip-if-running. |
+| External call fails after DB commit | Outbox pattern. Both in one transaction. |
+| Need exactly-once | You probably don't. At-least-once + dedup covers the case. If truly required, consult the queue library's two-phase commit story. |
+
+---
+
+## Final rule
+
+```
+Every async boundary → verify, dedup, handle, mark. Outbox for DB+notify. Bounded retries with backoff+jitter. DLQ on exhaustion.
+Otherwise → it is not voidcorp async-safety.
+```
+
+The network does not care about your assumptions. Code as if every message arrives N times.

package/core-assets/skills/void-async-safety/harness.yaml

@@ -0,0 +1,16 @@
+# Harness metadata for this skill. Not part of the Agent Skills
+# specification, and never copied into a consumer project: the SKILL.md
+# beside it stays portable and validates against the official six fields.
+# Read by this repository's graph, and by the installer for `runtimes`.
+kind: standard
+triggers:
+  globs: ["**/webhooks/**", "**/jobs/**", "**/queues/**", "**/workers/**", "**/cron/**", "**/*.worker.ts"]
+owner: folpe
+runtimes: [claude, codex]
+enforcement:
+  floor: ci
+  inline:
+    claude: active
+    codex: active
+    hermes: ci-only
+eval_targets: [claude/anthropic/opus]

package/core-assets/skills/void-audit/.source

@@ -0,0 +1,15 @@
+Sources for `void-audit` (see `docs/plans/skill-audits/void-audit.md` for the full audit).
+
+Original to void-machine. It wraps this repository's own CLI, so there is no upstream skill to
+distil: the subject did not exist anywhere else.
+
+Provenance rather than inspiration: it was a slash command under `packages/core/commands/`,
+shipped there on 2026-06-04 because the plugin carried no in-session ergonomics at the time and a
+skill was not invocable from the keyboard. Claude Code has since merged commands into skills, and
+neither Codex nor Kimi ever had the command format, so the command was Claude-only for a reason
+that had expired. Converted on 2026-08-19, keeping its name and its `allowed-tools`, gaining
+`disable-model-invocation: true` — the gesture is typed by a human, never guessed by the model.
+
+Rejected while converting: letting the model invoke it on its own. A health check, an audit or a
+graph report that fires unprompted arrives when nobody asked and nobody acts on it, and it spends
+a screen doing so.

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

@@ -0,0 +1,83 @@
+---
+name: void-audit
+description: Run the outbound audit over local mission events and surface skills that never fire, upstream deprecations and matrix conflicts, as proposals a human disposes of.
+allowed-tools: Bash(void-machine:*) Bash(npx:*)
+---
+
+# void-audit
+
+The harness accumulates. This asks which parts of it are still earning their place.
+
+**Attribution**: see `.source`.
+
+---
+
+## When it fires
+
+Only when a human asks. A harness that audits itself unprompted starts proposing deletions in
+the middle of someone's work, which is the surest way to have every proposal ignored.
+
+The moment worth running it is periodic and deliberate: alongside `void-retrospective`, or before a
+release, when there is appetite to actually remove something.
+
+---
+
+## Run it
+
+```
+void-machine audit
+```
+
+Or `npx voidmachine audit` when the CLI is not on PATH.
+
+It reads local mission events from `.void/machine/runs/<mission-id>/events.jsonl`, written by the
+activation meter, plus read-only legacy usage logs. Everything is local; nothing is sent
+anywhere.
+
+---
+
+## Read it
+
+The report joins skills, agents, hooks, their graph relations, human-session activations, outcomes,
+and static cost. It proposes one of five actions: repair telemetry, repair failures, wire an orphan,
+tune/fuse low-yield overlap, or review retirement. Three things to say about it, in this order:
+
+1. **What the data can support.** A skill absent from the events is a skill that did not fire in
+   the observed window. It is not a skill nobody needs, and the difference is the whole
+   interpretation. Say the window and the event count.
+2. **What is worth proposing.** A wiring fix, trigger tuning, fusion, rewrite, or retirement review.
+   One line each, with what it would cost to be wrong. Ordinary tuning needs the behavior window;
+   retirement needs at least twenty human sessions.
+3. **What the data cannot support yet.** Insufficient events is a finding, not a failure: it
+   means the harness has not been used enough in this project for the question to have an
+   answer.
+
+---
+
+## What it must not do
+
+**Nothing is applied.** Every output is a proposal; a human turns it into a pull request or
+declines it. Auto-applying a deprecation from usage data would delete the skill that fires twice
+a year and matters both times.
+
+**No inference from silence.** A component absent from the events is absent from the events.
+Self-host and smoke missions never count as human adoption evidence. A whole component family with
+broken telemetry is repaired before any member is judged.
+
+---
+
+## Red flags
+
+| Rationalization | Reality |
+|---|---|
+| "Nothing invoked it, remove it" | Removal is a human decision with its own reasoning. Propose it; say what breaks if the reading is wrong. |
+| "Insufficient data, so the audit failed" | It succeeded and reported an absence of evidence. That is the honest answer. |
+| "I'll open the PR while I'm here" | The proposal is the deliverable. The PR is a separate, deliberate act. |
+
+---
+
+## Composition
+
+Upstream: the activation meter writes the events this reads. Adjacent: `void-retrospective` looks at a
+window of engineering signals, this looks at the harness itself. Downstream: an accepted proposal
+is filed through `void-learn`, which owns the HITL capture.

package/core-assets/skills/void-audit/harness.yaml

@@ -0,0 +1,14 @@
+# Harness metadata for this skill. Not part of the Agent Skills
+# specification, and never copied into a consumer project: the SKILL.md
+# beside it stays portable and validates against the official six fields.
+# Read by this repository's graph, and by the installer for `runtimes`.
+kind: action
+owner: folpe
+runtimes: [claude, codex]
+enforcement:
+  floor: ci
+  inline:
+    claude: active
+    codex: active
+    hermes: ci-only
+eval_targets: [claude/anthropic/opus]

package/core-assets/skills/void-autopilot/.source

@@ -0,0 +1,21 @@
+Sources for `void-autopilot` (see `docs/plans/skill-audits/void-autopilot.md` for the audit):
+
+- void-machine `backlog-autopilot`, then the cluster engine that replaced it (this repo) — the
+  attended parallel burst, its worktree isolation and its footprint collisions. The continuous
+  loop keeps the isolation and the collisions, and drops the integration pull request, its
+  reconciliation and its grant.
+- TypeSafe, "Introducing System One models and Jev"
+  (https://typesafe.ai/blog/introducing-system-one-models-and-jev) — the cursor between code and
+  model: the model renders narrow typed judgments, the code applies the policy. Adapted: each
+  judgment is admitted by a Zod schema in the CLI, and a refused answer is never read charitably.
+- GitHub merge queue and auto-merge
+  (https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue)
+  — the combined commit is rebuilt and retested before every merge, which replaces the
+  reconciliation this repo wrote itself. Checks in the queue answer `merge_group`, and a commit
+  status triggers no workflow, hence the reviewer's re-run of `independent-review`.
+- git worktrees (native) — per-ticket isolation so parallel edits cannot corrupt one working
+  tree. Real filesystem isolation for the working tree, the index and `HEAD`, and nothing else:
+  the shared refs and config are fingerprinted around each unit.
+- Codex subagents (native) — workers when no cockpit surface is available. Subagents share
+  filesystem access, so the isolation comes from the pre-created worktrees and explicit workdirs,
+  never from an assumed sandbox.