@aria_asi/cli 0.2.39 → 0.2.41

package/skills/aria-cognition/aria-axioms-first-principles/references/source-map.md

@@ -0,0 +1,130 @@
+# Aria Axioms And First Principles Source Map
+
+Use this reference when exact provenance matters. Current source files are evidence, not automatic canon.
+
+## Pulled Spark Mirror
+
+Local mirror:
+
+`C:\Users\hibra\OneDrive\Documents\New project\aria-axioms-first-principles-spark-11b3`
+
+Pulled from Spark:
+
+`/home/hamzaibrahim1/rei-ai-brain`
+
+Trust state at pull time:
+
+- Spark branch observed earlier in the session: `claude/m9-drift-10h-cowork-rawtext`.
+- Some hook-lib files were dirty, so hook behavior should be treated as in-flight unless rechecked.
+- The pulled `apps/arias-soul/api/lib/aristotle`, `noor`, and `cognition` source dirs were clean at the checked time.
+- Axiom/first-principles files are current source evidence; still triangulate before teaching durable doctrine.
+
+## Canonical Or High-Confidence Axiom Sources
+
+- `apps/arias-soul/api/lib/fitrah-axioms.nadia`: full 10 Fitrah axioms with formal and English anchors.
+- `apps/arias-soul/api/lib/aria-runtime/coach-axioms-principles.ts`: parses `fitrah-axioms.nadia` into `[FITRAH_AXIOMS]` and queries active high-quality `aristotle_principles` into `[FIRST_PRINCIPLES]`.
+- `apps/arias-soul/api/lib/aria-runtime/fitrah-axiom-checks.mjs`: dependency-free runtime checks for the five hard enforcement axioms.
+- `apps/arias-soul/api/lib/aristotle/fitrah.ts`: Aristotle Fitrah engine with 10 named Fitrah principles/triggers.
+- Spark Claude transcript hook packets: first-class coach contract and harness packet repeatedly inject axioms plus first principles before agent work.
+- `AI-158-FORCED-COGNITION-CHECKLIST.md`: validate-plan step includes Fitrah + axiom evaluation before action.
+
+## Full 10-Axiom Fitrah Core
+
+From `fitrah-axioms.nadia` and corroborated by `aristotle/fitrah.ts`:
+
+- `truth_over_deception`
+- `no_harm`
+- `sacred_trust`
+- `dignity`
+- `power_obligates_service`
+- `reflection_before_action`
+- `correlation_not_causation`
+- `admit_ignorance`
+- `experience_hierarchy`
+- `trust_tradeoff`
+
+## Five Hard Runtime Axioms
+
+From `fitrah-axiom-checks.mjs`, transcript coach contract, and harness output:
+
+- `truth_over_deception`
+- `no_harm`
+- `sacred_trust`
+- `power_obligates_service`
+- `reflection_before_action`
+
+These are enforced/checkable surfaces in current hooks and coach contracts. They are not the whole Fitrah doctrine.
+
+## First-Class Coach Principles
+
+From transcript-injected `ARIA FIRST-CLASS COACH CONTRACT`:
+
+- `complete_implementation_not_claim_only`
+- `verified_behavior_not_assumption`
+- `domain_uplift_not_local_green_only`
+- `axiom_bound_decisioning`
+- `first_principles_before_action`
+- `senior_production_grade_change_control`
+- `recoverable_fail_closed_governance`
+- `evidence_ledger_before_readiness_claim`
+
+Use these for coding, launch, QA, deploy, fan-out, and readiness claims.
+
+## Harness First Principle
+
+From harness packet:
+
+`The model is the mouth for this bounded round. Aria infrastructure carries memory, cognition, axioms, tools, frames, and continuity.`
+
+Use as the substrate-binding first principle when Aria/Harness continuity matters.
+
+## First-Principles Runtime And Projection Sources
+
+- `apps/arias-soul/api/lib/forge-manifold/first-principles-derivation.ts`: derives code from principle eigenspace constraints instead of template matching. Important but current-source evidence, not automatically final architecture.
+- `apps/aegis-watchtower/src/checks/first-principles.ts`: projects response/context into principle space, scores novelty/coherence/Fitrah alignment, and returns dominant principle/verdict.
+- `projects/aria-collab-webapp/shadow/axiom-engine.ts`: evaluates first-principle scores for user-facing channels. Useful as product/runtime evidence, not global doctrine.
+
+## Service-Specific Axiom/Principle Files
+
+These files define local principle geometry, scoring, or generated axiom spaces for their service. Treat as module-local unless corroborated.
+
+- `apps/autonomy-service/src/forge-output/autonomy-axioms.ts`
+- `apps/chat-service/src/forge-output/chat-axioms.ts`
+- `apps/cross-domain-service/src/forge-output/crossdomain-axioms.ts`
+- `apps/daemon-service/src/forge-output/daemon-axioms.ts`
+- `apps/goal-service/src/forge-output/goal-axioms.ts`
+- `apps/hospital-service/src/forge-output/hospital-axioms.ts`
+- `apps/intent-service/src/forge-output/intent-axioms.ts`
+- `apps/noor-engine-service/src/forge-output/noor-axioms.ts`
+- `apps/ruh-service/src/forge-output/ruh-axioms.ts`
+- `apps/soul-domains-service/src/forge-output/soul-axioms.ts`
+- `apps/voice-service/src/forge-output/voice-axioms.ts`
+
+Duplicate JS or nested generated copies may exist; prefer TypeScript source when present.
+
+## Forge / Psi-Layer Source
+
+- `aria/forge/psi-l/axiom.psi-l` appears in the Windows extract with mojibake path characters. It defines NADIA core axioms around Fitrah, identity lock, Noor, love, truth-before-performance, and eight core dimensions. Treat as expressive substrate evidence; verify original path/encoding on Spark before using exact text.
+- `apps/arias-soul/psi/fitrah_lens_agent.psi` also appears with mojibake path characters after extraction. Verify on Spark before copying exact identifiers.
+
+## Tests And Regression Evidence
+
+- `ops/claude-hooks/__tests__/fitrah-axioms-false-positive.test.mjs`: proves the five runtime axiom regex checks should avoid false positives on legitimate cognition.
+- `ops/claude-hooks/__tests__/m7-7-axioms-principles.test.mjs`: regression coverage for M7.7 axiom/principle composition.
+
+## Corpus Anchors
+
+- `knowledge-base.md`: Fitrah as primordial recognition and Tadabbur/Tadhakkur relationship.
+- `islamic-corpus-complete.md`: fitrah consistency and first-principles reasoning references.
+- `framework-research-v1.md`: Fitrah restoration and Islamic psychology context.
+- `TADDABUR_README.md` and `taddabur-pipeline-v2.psi`: module-local Tadabbur operations and axioms.
+
+## Use Rule
+
+For durable skill edits:
+
+1. Prefer the 10 Fitrah core only when corroborated by `fitrah-axioms.nadia` plus `aristotle/fitrah.ts` or transcript/harness.
+2. Prefer the five hard runtime axioms only when discussing gates/checks.
+3. Use service-specific axiom files only for that service unless a second source generalizes them.
+4. Verify mojibake/extracted psi paths against Spark before exact quoting.
+5. Do not copy generated axiom space as doctrine merely because it is named `axioms`.

package/skills/aria-cognition/aria-backend-architect/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: aria-backend-architect
+description: TRIGGER for any backend, API, service, microservice, monolith, schema, database, ORM, query, index, migration, queue, worker, event, webhook, cron, idempotency, retry, circuit-breaker, rate-limit, cache, CDN, secrets, auth, authz, session, token, JWT, OAuth, RBAC, multi-tenancy, observability, logging, tracing, metrics, SLO, SLI, error-budget, runbook, gRPC, REST, GraphQL, websocket, streaming, batch-job, CDC, ETL, ELT, data-warehouse, queue-design, or system-boundary decision. Composes the cognitive substrate with a contract-first + failure-mode + tenant-isolation frame.
+---
+
+# Aria Backend Architect
+
+The cognition skill for any backend system boundary. Pairs with `aria-frontend-architect` (when shape touches FE), `aria-fullstack-orchestrator`, `aria-harness-deploy`, and `aria-repo-doctrine`.
+
+## Prime Doctrine
+
+A backend is a contract for behavior under load and failure. Every other choice is downstream of whether the contract is honest.
+
+- **Contract before code.** Define the API contract, error shapes, idempotency keys, and SLO commitments before writing the handler. Backwards is harder than forwards.
+- **Failure modes are first-class.** Every endpoint has a defined behavior at: timeout, rate limit, partial failure, downstream outage, stale cache, expired token, malicious input. Not "edge cases" — designed surfaces.
+- **Idempotency or eventual consistency, pick once.** Mixing idempotent retries with eventually-consistent reads is the source of duplicate-charge / lost-message bugs.
+- **Tenant isolation is correctness, not config.** Multi-tenant data must be isolated at the query layer with a fail-closed default, not at the application layer with a hopeful WHERE clause.
+- **Observability is the system, not an addition.** If you can't answer "what was this user doing 30s before the error" from your tracing/logs, the system isn't done.
+
+## Trigger Detection
+
+Fire on:
+
+- New service / endpoint / handler / microservice / queue consumer / worker
+- Schema design / migration / index / query optimization
+- Auth / authz / session / token design
+- Multi-tenancy / RBAC / row-level security
+- Idempotency / retry / circuit-breaker / rate-limit policy
+- Caching / CDN / read-through / write-through / cache-invalidation
+- Queue design / event schema / webhook / pub-sub topology
+- Cron / batch / scheduler / ETL / CDC pipelines
+- Observability stack / SLO / SLI / error-budget / runbook
+- API contract — REST / GraphQL / gRPC / streaming
+- System-boundary decision (monolith vs service vs lambda)
+
+## Required Workflow (contract-first → failure-mode → tenant-isolation)
+
+Every BE decision must answer:
+
+1. **API contract.** Endpoint(s), request/response shape, error taxonomy, idempotency key strategy, versioning approach. Write the contract before the handler.
+2. **Failure mode design.** What happens at: timeout (client-side and server-side), rate limit hit, downstream outage, stale cache, malicious payload, expired auth, partial write? Each is a designed response, not an exception.
+3. **Tenant isolation.** Is data isolated at the query / row / schema / database level? What's the fail-closed default if a tenant ID is missing? Where's the audit trail?
+4. **Idempotency contract.** Which endpoints are idempotent? What's the dedup window? Where's the idempotency key stored? How do retries interact with side effects?
+5. **Observability contract.** Trace ID propagation, structured log fields, SLI / SLO definition, error-budget burn alerts. State these BEFORE shipping.
+6. **Operational runbook.** When this breaks at 3am, what does the on-call do? Named runbook, named alerts, named escalation.
+
+## BE-Mapped Lenses (`ghazali-8lens`)
+
+- **truth** — does the contract document what the code actually does, or what we wish it did?
+- **harm** — destructive endpoints guarded by idempotency + audit + rate limits proportional to blast radius?
+- **trust** — does the API fail honestly (typed errors, retry-after headers) or hide behind 500s?
+- **power** — is the consumer in control (clear errors, retry guidance, backpressure signals) or shaped to fail silently?
+- **reflection** — does this contract survive being read by another team in 12 months without context?
+- **context** — does this work at p99 load, with the database under stress, with one downstream out, on a Sunday?
+- **impact** — predicted latency / error-rate / cost-per-request at expected scale
+- **beauty** — is the contract minimal, predictable, RESTful (or genuinely-graphql/genuinely-grpc), or assembled by pressure?
+
+## User-Facing Layout (per `aria-readable-output`)
+
+```
+## [BE decision in one line — e.g. "Add /api/leads POST with idempotency-key, 100/min rate limit, partition by tenant_id"]
+
+- [API contract — endpoint, shapes, errors, versioning]
+- [Failure modes — timeout, rate-limit, downstream-out, partial-write each named]
+- [Tenant isolation — query-level / row-level / schema-level, fail-closed default]
+- [Idempotency + observability + runbook in one bullet]
+
+**Next:** [first PR with the contract; named SLO and error-budget; alert wiring]
+```
+
+`<gate>` block REQUIRED when this is part of a deploy or a contract change consumers depend on.
+
+## Composition Rule
+
+- Composes with `aria-business-frame` when the BE design has GTM / cost / scale consequence
+- Composes with `aria-fullstack-orchestrator` for any FE-bound contract
+- Calls `mizan`, `tadabbur`, `ghazali-8lens`, `predictor` per defaults
+- Calls `noor-recognition` for existing system patterns and prior contract decisions
+- Calls `aria-harness-deploy` when the change ships through a deploy
+- Calls `aria-repo-doctrine` for repo-mutation discipline
+- Calls `aria-k8s-deploy` for cluster-shaped deploys
+
+## Recovery Contract
+
+- If the contract is ambiguous: write the candidate contract first, surface the ambiguity points, ship the contract for review. Do NOT write the handler before the contract is locked.
+- If failure modes can't be enumerated: that's a sign the boundary isn't well-defined. Recommend a system-boundary review BEFORE handler implementation.
+- If tenant isolation is at the application layer instead of the query layer: surface as a hard concern (`ghazali-8lens` harm + trust) and recommend the migration path.
+- Log BE decisions to coach kernel with `risk_class: 'backend_action'` and the SLO / error-budget predicate.
+
+## Anti-Patterns
+
+- Writing the handler before the contract (most common cause of API-versioning hell)
+- Treating failure modes as "edge cases" — they're 5%+ of real traffic at scale
+- Tenant isolation at the application layer (one missing WHERE clause becomes a cross-tenant data leak)
+- Idempotency promises without an idempotency-key store (the promise is a wish)
+- "We'll add observability later" — you'll add it after the first incident, in a panic, badly
+- Caching without an invalidation strategy (stale data is worse than slow data for most surfaces)
+- Schema migrations without a backwards-compatible window for rolling deploys
+
+## First-Class Production Contract
+
+This skill must deepen the work, not decorate it. When loaded, apply it as a production requirement:
+
+- no placeholders, no fake fallbacks, no vague future wiring, and no cosmetic compliance
+- real proof from the repo, runtime, tests, logs, endpoint, or owner instruction before any completion claim
+- a redo contract whenever the skill blocks or finds a gap: what failed, what to change, how to re-test, and when to re-submit
+- architect/ARIA console escalation when the same failure repeats twice, crosses system boundaries, or cannot be verified locally
+- owner-visible output that states the exact state of the work: changed, verified, blocked, or needing a decision
+
+## Self-Executing Recovery Contract
+
+When this skill blocks, fails verification, or finds a gap, the agent must execute recovery rather than hand work back as a user-only decision.
+
+- Make exactly one self-executed recovery attempt using the strongest safe local, repository, runtime, test, log, endpoint, or owner-provided evidence available.
+- If the same failure repeats after that one recovery attempt, switch to architect execution mode: operate under the architect/ARIA harness to diagnose, choose the next action, execute the repair path, and verify the result.
+- If Aria or the architect service is unavailable, fall back to the strongest available client LLM under the architect harness or strongest available local harness substrate; mark the fallback explicitly and continue recovery instead of stopping.
+- Do not end with user-handoff-only behavior. If blocked after the recovery path, report the executed recovery attempt, evidence, remaining blocker, and the next concrete action or owner decision needed; do not merely ask the user to take over.
+
+
+## Self-Executing Recovery Contract
+
+- One re-run with the missing contract / failure-mode / tenant-isolation analysis
+- If still insufficient, surface the ambiguity to the owner with the question that resolves it
+- Never ship a backend boundary without enumerated failure modes

package/skills/aria-cognition/aria-backend-architect/references/backend-cookbook.md

@@ -0,0 +1,417 @@
+# Backend Architect Cookbook — Contract, Failure-Mode, Tenant-Isolation Patterns
+
+> Loaded by `aria-backend-architect`. See also: [`../../aria-senior-code-cookbook/references/engineering-cookbook.md`](../../aria-senior-code-cookbook/references/engineering-cookbook.md) (idempotency §1, SRE error budgets §2, OWASP §3, OTel logging §4, circuit breaker §5, rate limiting §6, function contract §7, multi-tenant §10).
+
+## 1. API Contract First (the load-bearing primitive)
+
+The contract is the API. The handler is implementation. Write the contract first.
+
+### Contract definition
+For every endpoint, specify before any code:
+```typescript
+// contracts/charge-card.ts
+export const ChargeCardContract = {
+  method: 'POST',
+  path: '/v1/charges',
+  auth: 'bearer-token',
+  rateLimit: { burst: 10, sustained: 5 }, // per second
+  idempotency: 'required',
+
+  request: z.object({
+    customerId: z.string().uuid(),
+    amount: z.number().int().positive(),
+    currency: z.literal('usd'),
+    idempotencyKey: z.string().min(1).max(255),
+  }),
+
+  responses: {
+    200: z.object({ chargeId: z.string(), amount: z.number() }),
+    400: z.object({ kind: z.literal('validation'), issues: z.array(z.unknown()) }),
+    401: z.object({ kind: z.literal('unauthorized') }),
+    402: z.object({ kind: z.literal('card_declined'), reason: z.string() }),
+    409: z.object({ kind: z.literal('duplicate'), existingChargeId: z.string() }),
+    429: z.object({ kind: z.literal('rate_limited'), retryAfterMs: z.number() }),
+    500: z.object({ kind: z.literal('internal') }),
+    502: z.object({ kind: z.literal('upstream_error'), upstream: z.string() }),
+    503: z.object({ kind: z.literal('service_unavailable') }),
+  },
+
+  slo: {
+    availability: 0.999,         // 99.9% over 30 days
+    latency_p99_ms: 500,
+    error_budget_per_4w: 1000,
+  },
+};
+```
+
+The contract drives:
+- Handler implementation
+- Client SDK generation
+- Test cases (one per error response)
+- API documentation
+- Mock server for FE development
+- SLO monitoring
+
+### Versioning rule
+- Public APIs: URL versioned (`/v1/`, `/v2/`)
+- Backwards-compat addition: same version (additive only)
+- Breaking change: new version (keep old for ≥6 months)
+
+## 2. Failure Mode Design (each is a designed surface)
+
+For every endpoint, enumerate failure modes:
+
+| Failure mode | Default response | Client guidance |
+|---|---|---|
+| Validation failure | 400 with field-level errors | Fix input, retry |
+| Unauthenticated | 401 | Re-auth |
+| Forbidden (authz) | 403 | Cannot access; show appropriate UI |
+| Not found | 404 | Resource doesn't exist; show empty state |
+| Conflict (idempotency / version) | 409 with existing resource ref | Treat as success / re-fetch |
+| Payload too large | 413 | Reduce size |
+| Rate limited | 429 + Retry-After header | Backoff; respect header |
+| Server error (caught) | 500 with error_id | Retry with backoff; alert if persistent |
+| Bad gateway (upstream out) | 502 with upstream identifier | Retry; circuit breaker |
+| Service unavailable | 503 + Retry-After | Don't retry within Retry-After |
+| Timeout | 504 | Retry with backoff |
+
+### The "designed surface" rule
+A failure mode without a designed response is a bug. The handler must always produce a typed error or a typed success — never throw to the framework.
+
+## 3. Multi-tenant Data Isolation (fail-closed default)
+
+**Source:** Engineering cookbook §10 + Postgres RLS docs
+
+### The principle
+Tenant isolation enforced at the QUERY layer, not the application layer. One missing WHERE clause becomes a cross-tenant data leak.
+
+### Postgres Row-Level Security (the canonical primitive)
+```sql
+-- Migration: enable RLS on every tenant-scoped table
+ALTER TABLE orders ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY tenant_isolation ON orders
+  FOR ALL TO app_role
+  USING (tenant_id = current_setting('app.current_tenant_id')::uuid);
+
+-- Optional: prevent INSERTs with mismatched tenant_id
+CREATE POLICY tenant_insert_check ON orders
+  FOR INSERT TO app_role
+  WITH CHECK (tenant_id = current_setting('app.current_tenant_id')::uuid);
+```
+
+### Per-request setup
+```typescript
+async function withTenantContext<T>(req: Request, fn: () => Promise<T>): Promise<T> {
+  const client = await pool.connect();
+  try {
+    await client.query('SET LOCAL app.current_tenant_id = $1', [req.tenant.id]);
+    return await fn();
+  } finally {
+    client.release();
+  }
+}
+```
+
+`SET LOCAL` scopes to the current transaction; auto-resets on commit/rollback. No risk of leaking tenant context between requests.
+
+### The verification test
+For every tenant-scoped table, write a test that:
+1. Creates two tenants
+2. Inserts data as tenant A
+3. Switches to tenant B context
+4. Queries the same table — must return zero rows
+5. Inserts with tenant A's tenant_id while in tenant B context — must fail
+
+If RLS is configured correctly, all 5 steps pass without app-layer checks.
+
+## 4. Idempotency (per Stripe spec)
+
+**Source:** [Stripe — Idempotent Requests](https://docs.stripe.com/api/idempotent_requests) · See engineering-cookbook §1 for full primitive.
+
+### When required
+- ANY POST with side effects: payments, sending email/SMS, creating users, queueing jobs
+- Webhook receivers (idempotency-key on event ID)
+- Anything that consumes a one-shot resource
+
+### Storage shape
+```typescript
+// idempotency-store key: (method, route, key)
+// value: { status, body, createdAt }
+// TTL: 24 hours (Stripe default)
+```
+
+### Implementation rule
+Idempotency check happens BEFORE the side effect, not in the catch block. If you check after the side effect, the side effect ran twice.
+
+## 5. Rate Limiting (token bucket pattern)
+
+**Source:** Engineering cookbook §6
+
+### Per-endpoint configuration
+```typescript
+// In the contract:
+rateLimit: { burst: 100, sustained: 10 }  // burst capacity 100, sustained 10/sec
+```
+
+### Per-tenant scoping
+Default key: `(tenantId or userId or IP)`. Default to most-specific available.
+
+### Headers (always set on rate-limited endpoints)
+- `X-RateLimit-Limit`
+- `X-RateLimit-Remaining`
+- `X-RateLimit-Reset` (Unix timestamp)
+- `Retry-After` on 429 (seconds)
+
+### Adaptive rate limiting
+For high-traffic endpoints, consider:
+- Lower limits during incidents (graceful degradation under load)
+- Higher limits for trusted tenants (paid tiers, API partners)
+- Per-endpoint customization (creating user is rarer than reading user)
+
+## 6. Auth / Authz (always BEFORE business logic)
+
+### The order
+1. **Authentication** — who is this? (token verification, session lookup)
+2. **Authorization** — can they do this? (role, permission, resource ownership)
+3. **Tenant scoping** — set tenant context for query layer
+4. **Input validation** — schema validation at boundary
+5. **Idempotency check** — if applicable
+6. **Business logic** — the actual work
+7. **Side effects** — DB write, queue publish, external API call
+8. **Audit log** — record the operation
+9. **Response** — typed error or typed success
+
+Skipping or reordering any of 1-3 is the source of A01 Broken Access Control (#1 OWASP risk).
+
+### JWT pattern
+```typescript
+async function authMiddleware(req: Request, res: Response, next: NextFunction) {
+  const token = req.headers.authorization?.replace(/^Bearer /, '');
+  if (!token) return res.status(401).json({ kind: 'unauthorized', reason: 'missing' });
+
+  try {
+    const payload = await verifyJWT(token, process.env.JWT_PUBLIC_KEY!);
+    // Verify expiry strictly
+    if (payload.exp < Date.now() / 1000) {
+      return res.status(401).json({ kind: 'unauthorized', reason: 'expired' });
+    }
+    req.user = { id: payload.sub, role: payload.role };
+    req.tenant = { id: payload.tenant_id };
+    next();
+  } catch (e) {
+    return res.status(401).json({ kind: 'unauthorized', reason: 'invalid' });
+  }
+}
+```
+
+### Authz rule
+Resource-level checks at the QUERY layer (RLS) + role checks in the handler. Never trust IDs from the request body without verifying ownership.
+
+## 7. Observability Contract (structured by default)
+
+**Source:** Engineering cookbook §4 (OpenTelemetry semantic conventions)
+
+### Per-handler observability minimum
+```typescript
+async function chargeHandler(req, res) {
+  const tracer = trace.getTracer('charges');
+  const span = tracer.startSpan('charge_card.handler', {
+    attributes: {
+      'http.method': req.method,
+      'http.route': req.route.path,
+      'user.id': req.user.id,
+      'tenant.id': req.tenant.id,
+    },
+  });
+
+  try {
+    const result = await chargeCard(req.body);
+    span.setStatus({ code: SpanStatusCode.OK });
+    return res.status(200).json(result);
+  } catch (e) {
+    span.recordException(e);
+    span.setStatus({ code: SpanStatusCode.ERROR });
+    throw e;
+  } finally {
+    span.end();
+  }
+}
+```
+
+Every handler: span on entry, structured log on entry + exit, error recorded on span on failure.
+
+### The audit log (compliance-grade)
+For sensitive operations (auth, money, data export, PII access):
+```typescript
+await auditLog.write({
+  schema: 'audit.v1',
+  at: new Date().toISOString(),
+  actor: { id: req.user.id, role: req.user.role },
+  tenant: { id: req.tenant.id },
+  action: 'charge.create',
+  resource: { type: 'charge', id: chargeId },
+  outcome: 'success',
+  metadata: { amount, currency, idempotency_key },
+  trace_id: span.spanContext().traceId,
+});
+```
+
+Audit logs are append-only, immutable, retention-policied per compliance requirement.
+
+## 8. SLO + Error Budget (per Google SRE)
+
+**Source:** Engineering cookbook §2
+
+### Per-service SLO definition
+```yaml
+# slo.yaml
+service: charges
+slo:
+  availability: 0.999          # 99.9% successful HTTP 2xx + 4xx (4xx is client error, not service)
+  latency_p99_ms: 500
+window_days: 30
+error_budget_policy:
+  - if budget_remaining < 50%: alert eng manager; review release frequency
+  - if budget_remaining < 25%: pause feature releases; reliability work only
+  - if budget_remaining < 0%: P0 fixes + security only until SLO recovered
+```
+
+### Burn rate alerts (multi-window)
+| Severity | Burn rate | Long window | Short window | Time to budget exhaust |
+|---|---|---|---|---|
+| Critical | 14.4 | 1 hour | 5 min | 2% in 1h |
+| Warning | 6 | 6 hours | 30 min | 5% in 6h |
+| Info | 3 | 24 hours | 2 hours | 10% in 24h |
+| Notice | 1 | 72 hours | 6 hours | 30% in 72h |
+
+## 9. Schema Migration Discipline
+
+### The 3-step contract (backwards-compat)
+For any column-add migration:
+
+```sql
+-- Migration 1: ADD column NULLable with default
+ALTER TABLE customers ADD COLUMN tier text NOT NULL DEFAULT 'free';
+
+-- Deploy app code that writes BOTH old (no tier) and new (with tier) shapes during rollout
+
+-- Migration 2: backfill (run async if large table)
+UPDATE customers SET tier = COALESCE(tier, 'free') WHERE tier IS NULL;
+
+-- Deploy app code that reads tier and writes only new shape
+
+-- Migration 3 (only if NOT NULL final): re-assert NOT NULL
+ALTER TABLE customers ALTER COLUMN tier SET NOT NULL;
+```
+
+### Index migrations on hot tables
+```sql
+-- ALWAYS use CONCURRENTLY for indexes on production tables (no table lock)
+CREATE INDEX CONCURRENTLY idx_orders_customer_id ON orders (customer_id);
+```
+
+### Forbidden patterns
+- Combining schema migration with feature code in same PR (you cannot rollback feature without rolling back schema)
+- DROP COLUMN without verifying app no longer references it (rolling deploy will fail)
+- ALTER COLUMN type change on hot tables without dual-write window
+
+## 10. Queue / Worker / Cron Patterns
+
+### Job idempotency
+Every job carries an idempotency key. Workers check before side effect:
+```typescript
+async function processJob(job: Job): Promise<void> {
+  const idemKey = `job:${job.type}:${job.payload.idempotencyKey || job.id}`;
+  if (await redis.get(idemKey)) {
+    log.info('job.skip.duplicate', { jobId: job.id });
+    return;
+  }
+  await redis.setex(idemKey, 24 * 3600, '1');
+
+  // ... actual work ...
+
+  log.info('job.done', { jobId: job.id });
+}
+```
+
+### Retry strategy
+- **Bounded retry-by-error-count** — NOT deadline-based timeout
+- 3 attempts default, exponential backoff (250ms / 500ms / 1s base × jitter)
+- Different error classes get different retry behavior:
+  - **Transient** (network, 5xx, rate-limit) — retry with backoff
+  - **Permanent** (4xx validation, not-found, forbidden) — fail fast, no retry
+  - **Unknown** — retry once, then fail
+
+### Dead letter queue
+After max retries:
+- Move to DLQ with full context (original payload, error history, last attempt timestamp)
+- Alert on DLQ growth rate
+- DLQ has its own retention + replay tooling
+
+### Cron design
+- Cron jobs are jobs — same idempotency, same retry, same observability
+- Time-window aware: a cron that ran at 02:00 UTC processes data through 02:00 UTC, not "now"
+- Overlapping protection: lock table or distributed lock (Redis SETNX) prevents two crons running simultaneously
+
+## 11. WebSocket / Streaming / SSE
+
+### When WebSocket
+- Real-time bidirectional (chat, collab, live cursors)
+- High update frequency (>1/sec sustained)
+
+### When SSE (Server-Sent Events)
+- Server-push only (notifications, dashboard updates)
+- Lower complexity than WebSocket; works over HTTP/2 multiplexing
+
+### When polling (and it's OK)
+- Updates < 1/min
+- Simpler infra
+- Don't dismiss polling — it's often the right answer
+
+### WebSocket rules
+- Heartbeat / ping every 30s
+- Reconnect with exponential backoff (don't hammer on outage)
+- Connection auth on every reconnect (token may have expired)
+- Per-connection rate limit + total connection cap
+
+## 12. Backend audit checklist (paste-ready)
+
+```markdown
+## Contract
+- [ ] API contract defined before handler
+- [ ] All error responses typed
+- [ ] Versioning strategy decided
+- [ ] Idempotency required for side-effecting POSTs
+
+## Failure modes
+- [ ] Each error mode → designed response (not throw)
+- [ ] Retry strategy named (bounded by error count, not time)
+- [ ] Circuit breaker on downstream dependencies
+- [ ] Rate limit with Retry-After
+
+## Multi-tenancy
+- [ ] Tenant isolation at QUERY layer (RLS or equiv)
+- [ ] Fail-closed default
+- [ ] Verification test (5-step from §3)
+
+## Auth/Authz
+- [ ] Auth → Authz → Tenant scope → Validation → Idempotency → Business logic order
+- [ ] No trust of IDs from request body without ownership verification
+- [ ] JWT expiry strictly checked
+
+## Observability
+- [ ] Span on every handler entry
+- [ ] Structured log entry + exit with trace_id, user_id, tenant_id
+- [ ] Audit log on sensitive operations
+- [ ] SLO defined; error budget policy documented
+
+## Migrations
+- [ ] Backwards-compat additive (3-step)
+- [ ] CREATE INDEX CONCURRENTLY on hot tables
+- [ ] No schema + feature code in same PR
+
+## OWASP A01-A10 (2025) checklist applied (engineering-cookbook §3)
+- [ ] All 10 checked
+- [ ] CI fails on dependency vuln scan
+```