autotel 3.2.0 → 3.3.0

package/dist/workflow-distributed.cjs

@@ -2,11 +2,11 @@
 
 var chunk4P6ZOARG_cjs = require('./chunk-4P6ZOARG.cjs');
 var chunkINJD3G4K_cjs = require('./chunk-INJD3G4K.cjs');
-var chunkEEQHQKPP_cjs = require('./chunk-EEQHQKPP.cjs');
+var chunkU72TGONP_cjs = require('./chunk-U72TGONP.cjs');
 require('./chunk-2GIBANLB.cjs');
 require('./chunk-VQTCQKHQ.cjs');
-require('./chunk-UV64CWMA.cjs');
-require('./chunk-KKIYPZOP.cjs');
+require('./chunk-DQSVSGK3.cjs');
+require('./chunk-QJYWKAC5.cjs');
 require('./chunk-FEEVB2GV.cjs');
 require('./chunk-CEAQK2QY.cjs');
 require('./chunk-ZNMBW67B.cjs');
@@ -58,7 +58,7 @@ var WorkflowBaggage = chunkINJD3G4K_cjs.createSafeBaggageSchema(workflowBaggageF
 function traceDistributedWorkflow(config) {
   const spanName = `workflow.${config.name}`;
   return (fnFactory) => {
-    return chunkEEQHQKPP_cjs.trace(
+    return chunkU72TGONP_cjs.trace(
       { name: spanName, spanKind: api.SpanKind.INTERNAL },
       (baseCtx) => {
         return async (...args) => {
@@ -157,7 +157,7 @@ function traceDistributedWorkflow(config) {
 function traceDistributedStep(config) {
   const spanName = `workflow.step.${config.name}`;
   return (fnFactory) => {
-    return chunkEEQHQKPP_cjs.trace(
+    return chunkU72TGONP_cjs.trace(
       { name: spanName, spanKind: api.SpanKind.INTERNAL },
       (baseCtx) => {
         return async (...args) => {

package/dist/workflow-distributed.js

@@ -1,10 +1,10 @@
 import { emitCorrelatedEvent } from './chunk-KIL5CUN6.js';
 import { createSafeBaggageSchema } from './chunk-4IFSYQVX.js';
-import { trace } from './chunk-FVA2YDEQ.js';
+import { trace } from './chunk-U4D5IBSB.js';
 import './chunk-HLZ7H3VZ.js';
 import './chunk-SEO6NAQT.js';
-import './chunk-7EVW3Z37.js';
-import './chunk-ZKKJQS6R.js';
+import './chunk-TGV2XF57.js';
+import './chunk-32AXF4MA.js';
 import './chunk-643PQG3Y.js';
 import './chunk-A4E5AQFK.js';
 import './chunk-WGWSHJ2N.js';

package/dist/workflow.cjs

@@ -1,12 +1,12 @@
 'use strict';
 
-var chunk5RZ3NZ2M_cjs = require('./chunk-5RZ3NZ2M.cjs');
+var chunk4RA6HIYF_cjs = require('./chunk-4RA6HIYF.cjs');
 require('./chunk-4P6ZOARG.cjs');
-require('./chunk-EEQHQKPP.cjs');
+require('./chunk-U72TGONP.cjs');
 require('./chunk-2GIBANLB.cjs');
 require('./chunk-VQTCQKHQ.cjs');
-require('./chunk-UV64CWMA.cjs');
-require('./chunk-KKIYPZOP.cjs');
+require('./chunk-DQSVSGK3.cjs');
+require('./chunk-QJYWKAC5.cjs');
 require('./chunk-FEEVB2GV.cjs');
 require('./chunk-CEAQK2QY.cjs');
 require('./chunk-ZNMBW67B.cjs');
@@ -24,19 +24,19 @@ require('./chunk-YREV3LGG.cjs');
 
 Object.defineProperty(exports, "getCurrentWorkflowContext", {
   enumerable: true,
-  get: function () { return chunk5RZ3NZ2M_cjs.getCurrentWorkflowContext; }
+  get: function () { return chunk4RA6HIYF_cjs.getCurrentWorkflowContext; }
 });
 Object.defineProperty(exports, "isInWorkflow", {
   enumerable: true,
-  get: function () { return chunk5RZ3NZ2M_cjs.isInWorkflow; }
+  get: function () { return chunk4RA6HIYF_cjs.isInWorkflow; }
 });
 Object.defineProperty(exports, "traceStep", {
   enumerable: true,
-  get: function () { return chunk5RZ3NZ2M_cjs.traceStep; }
+  get: function () { return chunk4RA6HIYF_cjs.traceStep; }
 });
 Object.defineProperty(exports, "traceWorkflow", {
   enumerable: true,
-  get: function () { return chunk5RZ3NZ2M_cjs.traceWorkflow; }
+  get: function () { return chunk4RA6HIYF_cjs.traceWorkflow; }
 });
 //# sourceMappingURL=workflow.cjs.map
 //# sourceMappingURL=workflow.cjs.map

package/dist/workflow.js

@@ -1,10 +1,10 @@
-export { getCurrentWorkflowContext, isInWorkflow, traceStep, traceWorkflow } from './chunk-IS2QJ44P.js';
+export { getCurrentWorkflowContext, isInWorkflow, traceStep, traceWorkflow } from './chunk-FZROHTZZ.js';
 import './chunk-KIL5CUN6.js';
-import './chunk-FVA2YDEQ.js';
+import './chunk-U4D5IBSB.js';
 import './chunk-HLZ7H3VZ.js';
 import './chunk-SEO6NAQT.js';
-import './chunk-7EVW3Z37.js';
-import './chunk-ZKKJQS6R.js';
+import './chunk-TGV2XF57.js';
+import './chunk-32AXF4MA.js';
 import './chunk-643PQG3Y.js';
 import './chunk-A4E5AQFK.js';
 import './chunk-WGWSHJ2N.js';

package/dist/yaml-config.d.cts

@@ -1,4 +1,4 @@
-import { A as AutotelConfig } from './init-D9Bxx39e.cjs';
+import { A as AutotelConfig } from './init-gyesUMwz.cjs';
 import { SamplingPreset } from './sampling.cjs';
 import '@opentelemetry/sdk-trace-base';
 import '@opentelemetry/sdk-node';

package/dist/yaml-config.d.ts

@@ -1,4 +1,4 @@
-import { A as AutotelConfig } from './init-BSyIyDs5.js';
+import { A as AutotelConfig } from './init-DyE43paw.js';
 import { SamplingPreset } from './sampling.js';
 import '@opentelemetry/sdk-trace-base';
 import '@opentelemetry/sdk-node';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autotel",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "Write Once, Observe Anywhere",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/skills/build-audit-trails/SKILL.md

@@ -1,11 +1,17 @@
 ---
 name: build-audit-trails
 description: >
-  Design tamper-aware audit trails on top of OpenTelemetry spans using
-  autotel. Covers what counts as auditable, the audit-only span discipline,
-  signing and tamper-detection, denial logging, redaction, retention,
-  separation of concerns from operational telemetry, and framework wiring
-  (Next.js, Nuxt, Hono, Express, Cloudflare Workers).
+  Build or review tamper-aware audit trails on top of OpenTelemetry spans
+  using autotel and the autotel-audit package (`withAudit`,
+  `setAuditAttributes`, `forceKeepAuditEvent`). Covers what counts as
+  auditable, the audit-only span discipline, sampling bypass, HMAC and
+  hash-chain signing with tamper detection, denial logging, redaction,
+  retention, GDPR right-to-erasure via crypto-shredding, separation from
+  operational telemetry, testing audit spans, backend-agnostic audit queries,
+  a production-readiness checklist, and framework wiring (Next.js, Nuxt,
+  Nitro, NestJS, Express, Fastify, Hono, Cloudflare Workers, AWS Lambda,
+  standalone). Use it to design new audit trails or review existing ones for
+  GDPR, HIPAA, SOC 2, PCI-DSS, ISO 27001, SOX, and GxP compliance.
 license: MIT
 ---
 
@@ -21,6 +27,46 @@ autotel lets you express both with the same primitive — a span — but you sho
 - Adding "who did what" trails for admin actions, access reviews, payments
 - Recording authorization decisions (allow + deny)
 - Building immutable evidence for incident response
+- Reviewing an existing audit trail for compliance gaps (see "Review an existing audit trail")
+
+## Quick reference
+
+| Situation                                                | Use                                                              |
+| -------------------------------------------------------- | ---------------------------------------------------------------- |
+| Wrap an action so success/failure is audited + kept      | `withAudit(metadata, fn)` from `autotel-audit`                   |
+| Tag the active span with `audit.*` attributes only       | `setAuditAttributes(metadata)`                                   |
+| Make sure an audit span survives tail sampling           | `forceKeepAuditEvent()`                                          |
+| Record an authorization denial                           | `audit({ …, outcome: 'deny', reason })` (Step 1 helper)          |
+| Full control / framework-agnostic span helper            | hand-rolled `audit()` (Step 1)                                   |
+| Keep audit data off ops dashboards                       | `FilteringSpanProcessor` split (Step 3)                          |
+| Prove a record was not altered                           | HMAC or hash-chain signature (Step 4)                            |
+| Honor a GDPR erasure request on an append-only log       | crypto-shredding (Step 6.5)                                      |
+| Assert the trail in tests                                | `createTraceCollector()` from `autotel/testing` (Step 8)         |
+
+## The shortest path: the `autotel-audit` package
+
+`autotel-audit` ships this discipline as helpers. Reach for these before hand-rolling:
+
+```typescript
+import {
+  withAudit,
+  setAuditAttributes,
+  forceKeepAuditEvent,
+} from 'autotel-audit';
+
+// Wrap the action: sets audit.* attributes, force-keeps past tail sampling,
+// and tags outcome 'success' / 'failure' automatically.
+await withAudit(
+  { action: 'user.delete', resource: 'user', actorId: 'usr_42', category: 'admin' },
+  async () => db.user.delete({ where: { id } }),
+);
+
+// Or tag the current span yourself and opt out of sampling:
+setAuditAttributes({ action: 'secret.read', resource: 'sec_abc', actorId: 'usr_42' });
+forceKeepAuditEvent();
+```
+
+`withAudit` marks the span with `autotel.audit = true` and sets the tail-sampling keep flags via `forceKeepAuditEvent`, so audit events are never dropped. The rest of this guide builds the same model from raw spans when you need full control over the schema, signing, and the pipeline split. If you use the package, filter on `autotel.audit` (not `audit`) in Step 3.
 
 ## The audit span discipline
 
@@ -122,6 +168,17 @@ Critical: route audit spans to a **different processor and backend** so:
 - They are not subject to development-mode debug exporters.
 - They go to a write-once / append-only store (S3 Object Lock, immutable bucket, dedicated audit DB).
 
+How a span flows once you split the pipeline:
+
+```text
+audit(payload)
+  └─ span.attributes['audit'] = true   (or autotel.audit via the package)
+       │
+       ├─► FilteringSpanProcessor include: audit === true  ─► auditExporter ─► append-only store
+       │
+       └─► FilteringSpanProcessor exclude: audit === true  ─► opsExporter  (PII-redacted dashboards)
+```
+
 ```typescript
 import {
   composeSpanProcessors,
@@ -221,8 +278,31 @@ Audit retention is set by regulation, not engineering taste. Common minimums:
 
 Express retention as a backend lifecycle policy (S3 Object Lock COMPLIANCE mode, BigQuery `--time_partitioning_expiration`), not application code.
 
+## Step 6.5: GDPR and the right to erasure
+
+An append-only audit log and GDPR Article 17 ("right to be forgotten") look like a contradiction: you must keep the audit record, but the subject can demand their personal data be erased. Resolve it with **crypto-shredding** rather than deleting rows.
+
+- Store the immutable facts in the clear: `audit.action`, `audit.outcome`, timestamps, `audit.resource.id`.
+- Encrypt any personal data (names, emails, free-form context) with a **per-subject key**, and store only the ciphertext on the span (or a reference to it).
+- Keep per-subject keys in a separate key store. To honor an erasure request, delete that subject's key. The audit record stays intact and tamper-evident; the personal fields become permanently unrecoverable.
+
+```typescript
+// Never put raw PII on the span. Store a reference and shred the key on request.
+setAuditAttributes({
+  action: 'profile.update',
+  resource: 'user',
+  actorId: 'usr_42',
+  'subject.id': 'usr_42', // internal id, safe to retain
+  'pii.ref': 'kms://subjects/usr_42/v3', // ciphertext lives off-span, keyed per subject
+});
+```
+
+This keeps the chain of custody and signatures valid (you never mutate a signed record) while making erasure a key-management operation. Confirm the approach with your DPO; some regulators accept crypto-shredding as erasure, others want documented justification.
+
 ## Step 7: Framework wiring
 
+The handlers below are the common cases. For Nuxt, Nitro, NestJS, Fastify, AWS Lambda, and standalone jobs, see [references/framework-wiring.md](references/framework-wiring.md).
+
 ### Next.js
 
 ```typescript
@@ -286,6 +366,62 @@ export default defineWorkerFetch(
 );
 ```
 
+## Step 8: Test the trail
+
+An audit trail you have not tested is a compliance risk. The two tests that matter most: the denial path is recorded, and the audit attributes are present and correct. Use `createTraceCollector()` from `autotel/testing` to assert on emitted spans.
+
+```typescript
+import { describe, it, expect, beforeEach } from 'vitest';
+import { createTraceCollector, type TraceCollector } from 'autotel/testing';
+
+describe('audit trail', () => {
+  let collector: TraceCollector;
+  beforeEach(() => {
+    collector = createTraceCollector();
+  });
+
+  it('records a denial with reason and actor', async () => {
+    await expect(deleteUser(forbiddenReq)).rejects.toMatchObject({ status: 403 });
+
+    const [span] = collector.getSpansByAttributes({ 'audit.outcome': 'deny' });
+    expect(span).toBeDefined();
+    expect(span.attributes['audit.action']).toBe('user.delete');
+    expect(span.attributes['audit.reason']).toBeTruthy();
+    expect(span.attributes['enduser.id']).toBe('usr_42');
+  });
+
+  it('records the success path on allow', async () => {
+    await deleteUser(allowedReq);
+    expect(collector.getSpansByAttributes({ 'audit.outcome': 'allow' })).toHaveLength(1);
+  });
+});
+```
+
+Test the signature too: build an audit span, recompute the HMAC over the sorted attributes, and assert it matches; then mutate one attribute and assert it no longer does.
+
+## Review an existing audit trail
+
+When the task is to audit existing code rather than build new, work these four passes in order and report findings as you go.
+
+1. **Pipeline.** Grep for where audit spans are produced (`audit(`, `withAudit`, `setAuditAttributes`). Confirm a `FilteringSpanProcessor` routes them to a separate, append-only backend, and that ops never receives them. Flag any audit span subject to sampling.
+2. **Coverage.** List every `audit(`/`withAudit` call site. Are denials logged, not just successes? Are mutating admin actions, access reviews, payments, and data exports all covered? Flag audit-on-every-read noise.
+3. **Integrity + redaction.** Is there a signature (HMAC or hash-chain) where storage is shared with the producer? Are raw payloads, secrets, or emails on the span instead of references and internal ids? Is the ops branch redacted?
+4. **Tests + retention.** Is there a denial-path test and a signature-verification test? Is retention enforced at the storage layer (lifecycle policy), not in code?
+
+## Production checklist
+
+- [ ] Audit spans marked (`audit` / `autotel.audit`) and force-kept past sampling
+- [ ] Separate processor and backend from ops; ops branch redacted
+- [ ] Both allow and deny outcomes recorded
+- [ ] No secrets, tokens, raw payloads, or emails on spans (references and internal ids only)
+- [ ] Signature (HMAC or hash-chain) where storage is shared with the producer; keys rotated
+- [ ] Retention set as a storage lifecycle policy per regulation
+- [ ] GDPR erasure plan (crypto-shredding) for personal fields
+- [ ] Multi-tenant isolation on the audit store
+- [ ] Denial-path and signature-verification tests in CI
+
+To query the trail (denials, per-actor history, tamper detection) across Honeycomb, Grafana Tempo, or Datadog, see [references/audit-queries.md](references/audit-queries.md).
+
 ## Anti-patterns
 
 | Anti-pattern                                   | Fix                                                            |
@@ -300,3 +436,12 @@ export default defineWorkerFetch(
 | Audit on every read of harmless data           | Audit _meaningful_ events; not every list call                 |
 | Audit row tied to a specific framework         | The `audit()` function is framework-agnostic                   |
 | `enduser.id` = email                           | Use the internal id; emails go in a separate identity table    |
+
+## Glossary
+
+- **Audit span** — an OpenTelemetry span that records who did what to which resource, marked `audit` / `autotel.audit` so it is routed and retained separately from ops telemetry.
+- **Force-keep** — opting a span out of tail sampling so it is always exported; `forceKeepAuditEvent()` sets the autotel tail-keep flags.
+- **Denial** — an authorization decision that blocked an action; recorded with `audit.outcome = 'deny'` and a reason. Logging denials is as important as logging successes.
+- **Hash-chain** — linking each audit record to the hash of the previous one so removing or reordering records is detectable.
+- **Crypto-shredding** — satisfying an erasure request by destroying the per-subject encryption key rather than deleting the immutable record.
+- **Append-only store** — a backend that rejects updates and deletes (S3 Object Lock, immutable bucket, WORM storage), the destination for audit spans.

package/skills/build-audit-trails/references/audit-queries.md

@@ -0,0 +1,73 @@
+# Querying the audit trail
+
+Because audit events are OpenTelemetry spans, you query them with the same tools as the rest of your telemetry, no separate audit UI required. The attribute names below match the skill: `audit.action`, `audit.outcome`, `audit.resource.id`, `enduser.id`, `autotel.audit`, and `audit.signature.value`.
+
+Run these against the **audit backend** (the append-only one), not your ops backend.
+
+## Find all denials in a window
+
+A spike in denials is a security signal (credential stuffing, privilege probing).
+
+- **Honeycomb** — filter `autotel.audit = true` AND `audit.outcome = deny`, group by `audit.action` and `enduser.id`, visualize `COUNT`.
+- **Grafana Tempo (TraceQL)**:
+  ```
+  { span.autotel.audit = true && span.audit.outcome = "deny" }
+  ```
+- **Datadog (spans search)**:
+  ```
+  @autotel.audit:true @audit.outcome:deny
+  ```
+
+## Trace one actor across every resource
+
+Answer "everything user X did" for an access review or incident.
+
+- **Honeycomb** — filter `enduser.id = "usr_42"`, group by `audit.action`, `audit.resource.type`, order by timestamp.
+- **TraceQL**:
+  ```
+  { span.enduser.id = "usr_42" && span.autotel.audit = true }
+  ```
+- **Datadog**:
+  ```
+  @enduser.id:usr_42 @autotel.audit:true
+  ```
+
+## Who touched one resource
+
+Answer "everyone who accessed secret `sec_abc`".
+
+- **TraceQL**:
+  ```
+  { span.audit.resource.id = "sec_abc" && span.autotel.audit = true }
+  ```
+- **Datadog**:
+  ```
+  @audit.resource.id:sec_abc @autotel.audit:true
+  ```
+
+## Spot coverage gaps
+
+Confirm sensitive actions are actually being recorded. Group audit spans by `audit.action` and compare against your list of auditable actions. An action that never appears is either never exercised or never audited; both deserve a look.
+
+- **Honeycomb** — group by `audit.action`, `COUNT`, over 30 days.
+
+## Detect tampering or missing signatures
+
+In a shared-storage setup every audit span should carry `audit.signature.value`. Spans without one, or whose recomputed HMAC does not match, are suspect.
+
+- **Find unsigned audit spans (TraceQL)**:
+  ```
+  { span.autotel.audit = true && span.audit.signature.value = nil }
+  ```
+- **Datadog**:
+  ```
+  @autotel.audit:true -@audit.signature.value:*
+  ```
+
+Verification itself happens in code: export the spans, recompute the HMAC over the sorted attribute set (excluding `audit.signature.value`), and flag mismatches. A scheduled job that does this and writes its own audit span (`action: 'audit.integrity.check'`) gives you meta-auditing.
+
+## Tips
+
+- Pin the time range explicitly; audit queries often span months, well past hot-storage windows.
+- Export results to CSV/NDJSON for auditors who need evidence outside the observability tool.
+- Keep these queries in version control next to the audit code so reviewers can reproduce them.

package/skills/build-audit-trails/references/framework-wiring.md

@@ -0,0 +1,187 @@
+# Framework wiring for audit trails
+
+Each handler below records an authorization decision (allow and deny) and emits one audit span. They assume the `audit()` / `withAuthz()` helpers from Step 1–2 of the skill, or the `withAudit` helper from `autotel-audit`. Keep the audit call inside the traced request so it inherits the trace context.
+
+The rule across every framework is the same: wrap the authorization decision so both branches reach the audit pipeline, and never put raw payloads on the span.
+
+## Next.js (App Router)
+
+```typescript
+// app/admin/users/[id]/route.ts
+import { withAuthz } from '@/lib/audit';
+
+export async function DELETE(req: Request, { params }: { params: { id: string } }) {
+  return withAuthz(
+    {
+      action: 'user.delete',
+      resource: { type: 'user', id: params.id },
+      actor: { id: req.headers.get('x-user-id')!, role: 'admin' },
+    },
+    async () => ({ allow: await canDelete(req, params.id) }),
+    async () => {
+      await db.user.delete({ where: { id: params.id } });
+      return Response.json({ ok: true });
+    },
+  );
+}
+```
+
+## Nuxt / Nitro
+
+```typescript
+// server/api/secrets/[id].delete.ts
+import { withAuthz } from '~/server/utils/audit';
+
+export default defineEventHandler((event) =>
+  withAuthz(
+    {
+      action: 'secret.delete',
+      resource: { type: 'secret', id: getRouterParam(event, 'id')! },
+      actor: { id: event.context.user.id, role: event.context.user.role },
+    },
+    async () => ({ allow: await canManageSecret(event) }),
+    async () => {
+      await secrets.delete(getRouterParam(event, 'id')!);
+      return { ok: true };
+    },
+  ),
+);
+```
+
+## NestJS
+
+Wrap the audited work inside the service or an interceptor. The decision lives next to the business logic:
+
+```typescript
+@Injectable()
+export class UsersService {
+  async remove(id: string, actor: Actor) {
+    return withAuthz(
+      { action: 'user.delete', resource: { type: 'user', id }, actor },
+      async () => ({ allow: actor.role === 'admin' }),
+      async () => this.repo.delete(id),
+    );
+  }
+}
+```
+
+## Express
+
+```typescript
+import { withAuthz } from './audit';
+
+app.delete('/admin/users/:id', async (req, res, next) => {
+  try {
+    await withAuthz(
+      {
+        action: 'user.delete',
+        resource: { type: 'user', id: req.params.id },
+        actor: { id: req.user.id, role: req.user.role },
+      },
+      async () => ({ allow: req.user.role === 'admin' }),
+      async () => db.user.delete({ where: { id: req.params.id } }),
+    );
+    res.json({ ok: true });
+  } catch (err) {
+    next(err);
+  }
+});
+```
+
+## Fastify
+
+```typescript
+import { withAuthz } from './audit';
+
+fastify.delete('/admin/users/:id', async (request, reply) => {
+  await withAuthz(
+    {
+      action: 'user.delete',
+      resource: { type: 'user', id: (request.params as { id: string }).id },
+      actor: { id: request.user.id, role: request.user.role },
+    },
+    async () => ({ allow: request.user.role === 'admin' }),
+    async () => db.user.delete({ where: { id: (request.params as { id: string }).id } }),
+  );
+  return { ok: true };
+});
+```
+
+## Hono
+
+```typescript
+import { withAuthz } from './audit';
+
+app.post('/secrets/:id/read', (c) =>
+  withAuthz(
+    {
+      action: 'secret.read',
+      resource: { type: 'secret', id: c.req.param('id') },
+      actor: { id: c.var.user.id, role: c.var.user.role },
+    },
+    () => requireScope(c, 'secrets:read'),
+    async () => c.json({ value: await secrets.read(c.req.param('id')) }),
+  ),
+);
+```
+
+## Cloudflare Workers
+
+Audit from inside `defineWorkerFetch` so `ctx.waitUntil` exports the audit span before the response returns:
+
+```typescript
+import { defineWorkerFetch } from 'autotel-cloudflare';
+import { withAuthz } from './audit';
+
+export default defineWorkerFetch(
+  { service: { name: 'admin-api' } },
+  async (request, env, ctx, log) =>
+    withAuthz(
+      {
+        action: 'data.export',
+        resource: { type: 'project', id: 'p_123' },
+        actor: { id: 'usr_42' },
+      },
+      async () => ({ allow: true }),
+      async () => Response.json({ ok: true }),
+    ),
+);
+```
+
+## AWS Lambda
+
+Wrap the traced handler; the audit span is flushed when the handler settles:
+
+```typescript
+import { withAuthz } from './audit';
+
+export const handler = async (event: APIGatewayProxyEventV2) =>
+  withAuthz(
+    {
+      action: 'invoice.void',
+      resource: { type: 'invoice', id: event.pathParameters!.id! },
+      actor: { id: event.requestContext.authorizer!.userId },
+    },
+    async () => ({ allow: await canVoid(event) }),
+    async () => {
+      await invoices.void(event.pathParameters!.id!);
+      return { statusCode: 200, body: JSON.stringify({ ok: true }) };
+    },
+  );
+```
+
+## Standalone scripts and cron jobs
+
+Outside a request there is no ambient trace context. Wrap the job in `trace()` first so the audit span has a parent, and set the actor to the system principal:
+
+```typescript
+import { trace } from 'autotel';
+import { withAudit } from 'autotel-audit';
+
+export const nightlyPurge = trace(async function nightlyPurge() {
+  await withAudit(
+    { action: 'data.purge', resource: 'expired-sessions', actorId: 'system:cron', category: 'maintenance' },
+    async () => sessions.purgeExpired(),
+  );
+});
+```

package/skills/review-otel-patterns/SKILL.md

@@ -7,6 +7,7 @@ description: >
   missing span attributes, manual exporter setup, broken context propagation, exposed PII, and ad-hoc
   error handling. Covers spans, metrics, logs, structured errors, the autotel processor pipeline
   (tail-sampling, attribute redaction, span-name normalisation, filtering, baggage),
+  built-in enrichers (user agent, geo, request size) and custom `defineEnricher`,
   `defineWorkerFetch` for Cloudflare async drains, multi-vendor OTLP backends (Honeycomb, Datadog,
   Grafana Cloud, Sentry, Axiom, HyperDX), `composeSpanProcessors` / `composeSubscribers` /
   `composePostProcessors` for pipelines, AI SDK observability with gen-ai semantic conventions, and
@@ -232,6 +233,46 @@ All options work with `init()`, framework adapters, and `wrapModule` / `defineWo
 
 ---
 
+## Built-in enrichers
+
+Enrichers turn raw request data into standard, low-cardinality span attributes. Import the helpers from `autotel/enrichers` and spread their output onto the active span or request logger. Each returns `undefined` when there is nothing to add, so spreading is safe.
+
+| Helper                                       | Returns attributes                                                   | Source                                  |
+| -------------------------------------------- | -------------------------------------------------------------------- | --------------------------------------- |
+| `userAgent(headers)`                         | `user_agent.raw`, `user_agent.browser`, `user_agent.os`, `user_agent.device` | `user-agent` request header     |
+| `geo(headers)`                               | `geo.country`, `geo.region`, `geo.city`, `geo.latitude`, `geo.longitude`     | Vercel / Cloudflare geo headers |
+| `requestSize(reqHeaders, resHeaders?)`       | `http.request.body.size`, `http.response.body.size`                  | `content-length` headers                |
+
+```typescript
+import { userAgent, geo, requestSize } from 'autotel/enrichers';
+
+export const handler = trace((ctx) => async (request: Request) => {
+  ctx.setAttributes({
+    ...userAgent(request.headers),
+    ...geo(request.headers),
+    ...requestSize(request.headers),
+  });
+  // ... handle request
+});
+```
+
+For your own derived fields on a request's wide event, build a reusable enricher with `defineEnricher` (from `autotel`) instead of scattering ad-hoc field writes. `compute` returns an object that is merged into the named `field`; return `undefined` to skip. Keep the output low-cardinality (bucket or hash high-cardinality values):
+
+```typescript
+import { defineEnricher } from 'autotel';
+
+// Merge a derived, low-cardinality object into event.user on each request.
+const enrichTier = defineEnricher<{ user?: { plan?: string } }, { tier: string }>({
+  name: 'user-tier',
+  field: 'user',
+  compute: ({ event }) => ({ tier: event.user?.plan ?? 'anonymous' }),
+});
+```
+
+**Review checks:** raw `User-Agent` strings stored verbatim (use `userAgent()` to parse), geo data hand-parsed per framework (use `geo()`), and high-cardinality values (full URLs, emails, ids) set directly as attributes instead of being bucketed or hashed.
+
+---
+
 ## Backends (multi-vendor OTLP)
 
 Switch backends with **no code changes** — autotel speaks OTLP HTTP/JSON and HTTP/protobuf out of the box.