voidforge-build 23.10.0 → 23.11.1

package/dist/docs/patterns/audit-log.ts

@@ -0,0 +1,132 @@
+/**
+ * Pattern: Audit Log (system-event NULL trap + integrity)
+ *
+ * Source: Field report #319 §6. `audit_log.org_id INTEGER NOT NULL DEFAULT 1`
+ * rejects explicit NULL inserts. Spec called for `org_id=NULL` for system
+ * events; code wrote `None`; PG raised IntegrityError; an `except Exception:
+ * pass` swallowed it; the audit row was silently lost on every system event.
+ *
+ * The audit table cannot be a system of record AND a tenant-scoped table at
+ * the same time. This pattern documents the two valid resolutions and the
+ * integrity properties any audit pipeline must hold.
+ *
+ * Pairs with /docs/patterns/financial-transaction.ts (hash-chained append)
+ * for higher-stakes audit trails.
+ */
+
+// ── The Two Valid Patterns ────────────────────────────────────────────────
+
+// Pattern 1: Schema relaxation — make org_id nullable, write NULL for system
+// events. Most explicit. Visible in `\d audit_log`. Migration cost.
+//
+//     ALTER TABLE audit_log ALTER COLUMN org_id DROP NOT NULL;
+//     -- Operators query: WHERE org_id IS NULL
+//
+// Pattern 2: Sentinel + tag — write the placeholder DEFAULT (e.g., 1) plus a
+// `decisions.system_event = true` JSONB flag. Cheaper, reversible. Operators
+// query: WHERE (decisions->>'system_event')::boolean = true.
+
+// ── TypeScript implementation (Pattern 2 — sentinel + tag) ───────────────
+
+export type AuditEntry = {
+  org_id: number;            // Schema DEFAULT for system events; real org id otherwise
+  user_id: string | null;    // null for system events
+  action: string;
+  resource_type: string;
+  resource_id: string | null;
+  decisions: AuditDecisions;
+  occurred_at: Date;
+};
+
+export type AuditDecisions = {
+  system_event?: true;       // Tag for system-scope writes (Pattern 2)
+  reason?: string;
+  actor_role?: string;
+  // Free-form context — keep keys stable so operator queries don't drift
+  [key: string]: unknown;
+};
+
+const SYSTEM_ORG_ID_PLACEHOLDER = 1; // Must match the schema DEFAULT
+
+export async function writeAudit(
+  db: { execute: (sql: string, params: unknown[]) => Promise<void> },
+  entry: Omit<AuditEntry, 'occurred_at'>,
+): Promise<void> {
+  // Mark system events explicitly. Pattern 2 invariant: every system_event=true
+  // row uses SYSTEM_ORG_ID_PLACEHOLDER as org_id.
+  if (entry.decisions.system_event && entry.org_id !== SYSTEM_ORG_ID_PLACEHOLDER) {
+    throw new Error(
+      `audit-log invariant: system_event=true requires org_id=${SYSTEM_ORG_ID_PLACEHOLDER}, got ${entry.org_id}`,
+    );
+  }
+
+  await db.execute(
+    `INSERT INTO audit_log (org_id, user_id, action, resource_type, resource_id, decisions, occurred_at)
+     VALUES ($1, $2, $3, $4, $5, $6, NOW())`,
+    [
+      entry.org_id,
+      entry.user_id,
+      entry.action,
+      entry.resource_type,
+      entry.resource_id,
+      JSON.stringify(entry.decisions),
+    ],
+  );
+}
+
+// Convenience wrappers — make system vs tenant calls obvious at the call site.
+
+export const writeSystemAudit = (
+  db: Parameters<typeof writeAudit>[0],
+  entry: Omit<AuditEntry, 'org_id' | 'occurred_at' | 'user_id' | 'decisions'> & {
+    decisions: Omit<AuditDecisions, 'system_event'>;
+  },
+) =>
+  writeAudit(db, {
+    ...entry,
+    org_id: SYSTEM_ORG_ID_PLACEHOLDER,
+    user_id: null,
+    decisions: { ...entry.decisions, system_event: true },
+  });
+
+export const writeTenantAudit = (
+  db: Parameters<typeof writeAudit>[0],
+  entry: Omit<AuditEntry, 'occurred_at'> & { org_id: number; user_id: string },
+) => writeAudit(db, entry);
+
+// ── Integrity properties (assert in tests) ────────────────────────────────
+//
+// 1. NEVER `try { ... } catch { /* ignore */ }` around audit writes.
+//    Audit-write failures are themselves the most important class of audit
+//    event. If the audit pipeline can fail silently, you have no audit.
+//
+// 2. Audit writes inside the same transaction as the action they describe.
+//    A separate transaction risks the action committing while the audit
+//    rolls back (or vice versa).
+//
+// 3. Append-only at the application layer (no UPDATE/DELETE on audit_log).
+//    Enforce via revoked grants on the runtime role:
+//      REVOKE UPDATE, DELETE ON audit_log FROM <runtime_role>;
+//
+// 4. Tests assert: writeSystemAudit + writeTenantAudit produce
+//    distinguishable rows. Operator query against `decisions->>'system_event'`
+//    must surface system events without false positives from real org=1.
+
+// ── Anti-patterns ─────────────────────────────────────────────────────────
+//
+// - `org_id INTEGER NOT NULL DEFAULT N` + `INSERT ... VALUES (NULL, ...)`
+//   → IntegrityError. Pick Pattern 1 (drop NOT NULL) or Pattern 2 (write N
+//     + tag). Don't try to do both halfway.
+//
+// - System events written with a real user's `org_id` "for convenience."
+//   The audit trail conflates platform actions with tenant actions; legal
+//   discovery cannot separate them.
+//
+// - JSONB tag without a stable key. `decisions.systemEvent` vs
+//   `decisions.system_event` vs `decisions.is_system` — operator queries
+//   break across versions. Lock the key in this file and keep it.
+//
+// - Wave 3 convergence (field report #319): Riker, Kenobi, Hawkgirl, Loki
+//   each independently flagged the NULL trap. When 3+ reviewers agree on
+//   the same finding, it is real, not stylistic — promote to a pattern,
+//   not a one-off fix.

package/dist/docs/patterns/llm-state-dedup.ts

@@ -0,0 +1,246 @@
+/**
+ * Pattern: LLM State Dedup — IDs are NOT keys
+ *
+ * Rule: LLM-emitted identifiers are display labels, not primary keys.
+ *
+ * Why: each LLM invocation is stateless from the model's perspective. Two
+ * cycles that propose the same fix will produce DIFFERENT id strings, even
+ * for substantively identical commands. The model has no memory of prior
+ * ids; it generates a fresh string from current context, drifts every cycle.
+ *
+ * Field report #330 (threadplex-ops): an hourly run asked Claude to emit
+ * `approval_needed[]` entries with an `id` field. The runtime keyed dedup
+ * on `id`. Over 5 hours of identical context, Claude emitted ids:
+ *
+ *   `a3f9c2` (cycle 1)
+ *   `a3f7c2` (cycle 2)
+ *   `a3f7b2` (cycle 3)
+ *   `a3f9c1` (cycle 4)
+ *
+ * Four proposals to stop the same container. Four Telegram approval cards.
+ * Zero collapse. The dedup key was wrong by construction.
+ *
+ * This pattern applies to ANY VoidForge project using an LLM as a decision
+ * engine that emits actionable items (approvals, tickets, tasks, queued ops).
+ *
+ * Agents: Hari Seldon (AI architecture), Bayta Darell (eval), Stark (backend)
+ */
+
+import { createHash } from 'node:crypto'
+
+// --- The rule ---
+
+/**
+ * Dedup keys must be derived from the OPERATIVE CONTENT, not from the LLM's
+ * id field. The operative content is the part of the proposal that, if
+ * executed, would produce the same observable outcome.
+ *
+ * For shell commands: the canonical command string.
+ * For HTTP requests: (method, path, normalized body).
+ * For database operations: (table, primary key, op-type).
+ * For user notifications: (recipient, channel, message-hash).
+ */
+
+export interface ProposalDedupKey {
+  /** Content-hash of the operative payload — the actual dedup key. */
+  contentHash: string
+
+  /**
+   * Optional looser key for command-string drift collapse — `docker stop X`,
+   * `docker compose stop X`, `docker rm -f X` all collapse to the same
+   * (verb, target) tuple even though contentHash differs.
+   */
+  logicalKey?: string
+
+  /** The LLM-emitted id, retained as a display label only. NEVER as primary key. */
+  displayId?: string
+}
+
+// --- Hash the operative content ---
+
+/**
+ * For shell commands: hash the canonical command string. Normalize whitespace
+ * and quoting before hashing so cosmetically-different but semantically-
+ * identical commands collapse.
+ */
+export function shellCommandHash(command: string): string {
+  const canonical = command
+    .trim()
+    .replace(/\s+/g, ' ')         // Collapse whitespace
+    .replace(/(['"])\s+/g, '$1 ') // Normalize quote-adjacent spaces
+
+  return createHash('sha256').update(canonical).digest('hex').slice(0, 12)
+}
+
+/**
+ * For HTTP request proposals: hash (method, path, sorted-body-keys).
+ * Sort body keys so `{a: 1, b: 2}` and `{b: 2, a: 1}` hash identically.
+ */
+export function httpRequestHash(req: {
+  method: string
+  path: string
+  body?: Record<string, unknown>
+}): string {
+  const sortedBody = req.body
+    ? JSON.stringify(req.body, Object.keys(req.body).sort())
+    : ''
+  const canonical = `${req.method.toUpperCase()} ${req.path} ${sortedBody}`
+  return createHash('sha256').update(canonical).digest('hex').slice(0, 12)
+}
+
+// --- Logical-key fallback for command-string drift ---
+
+/**
+ * Some commands have multiple syntactic forms that produce the same outcome.
+ * Extract (verb, target) tuple so all forms collapse to the same logical key.
+ *
+ * Examples that all map to ('stop', 'kometa-run'):
+ *   docker stop kometa-run
+ *   docker compose stop kometa-run
+ *   docker rm -f kometa-run     (different verb but same target — flag separately)
+ */
+export function dockerLogicalKey(command: string): string | null {
+  const verbs = ['stop', 'start', 'restart', 'rm', 'kill', 'pause']
+  for (const verb of verbs) {
+    const re = new RegExp(`\\bdocker\\s+(?:compose\\s+)?${verb}\\b\\s+(?:-\\S+\\s+)*([\\w.-]+)`, 'i')
+    const m = command.match(re)
+    if (m) return `${verb}:${m[1]}`
+  }
+  return null
+}
+
+// --- Lifecycle states must enumerate every in-flight status ---
+
+/**
+ * Even with correct dedup keys, the snapshot used for dedup-comparison must
+ * cover ALL operator-visible in-flight states — not just `pending`.
+ *
+ * Field report #330: the threadplex-ops snapshot filtered only
+ * `status == "pending"`, missing `executing` and `interrupted` rows that
+ * were also operator-visible. The dedup key was correct but the snapshot
+ * was incomplete, producing the same duplication symptom.
+ *
+ * The lifecycle table below is the reference. Extend per-project.
+ */
+export const PROPOSAL_LIFECYCLE_STATES = [
+  'pending',      // Awaiting operator approval
+  'executing',    // Operator approved; runtime executing the action
+  'interrupted',  // Execution paused (operator pause, system pause, retry-backoff)
+  'completed',    // Execution succeeded
+  'failed',       // Execution failed (terminal — operator must re-issue)
+  'cancelled',    // Operator cancelled before execution
+  'expired',      // Approval window timed out
+] as const
+
+export type LifecycleState = typeof PROPOSAL_LIFECYCLE_STATES[number]
+
+/** In-flight states the dedup snapshot must include to prevent duplicate proposals. */
+export const IN_FLIGHT_STATES: readonly LifecycleState[] = [
+  'pending',
+  'executing',
+  'interrupted',
+]
+
+// --- AUTHORITY-style contract: tell the LLM the key shape ---
+
+/**
+ * The LLM cannot enforce a dedup contract it doesn't know about. Document
+ * the contract in the agent's authority/instruction document so the LLM
+ * understands what "same target" means.
+ *
+ * Example AUTHORITY.md fragment:
+ *
+ *   ## Approval Identifier Contract
+ *
+ *   Each proposal you emit MUST include both:
+ *
+ *     id          — a human-readable display label. NOT a key. You may
+ *                   emit any short label that helps the operator scan.
+ *
+ *     cmd_hash    — sha256(command)[:12]. The runtime keys dedup on this.
+ *                   Two proposals with the same cmd_hash collapse into one
+ *                   approval card.
+ *
+ *   The runtime also computes a logical_key from the command verb + target
+ *   name. Proposals with the same logical_key are surfaced as a cluster
+ *   even if cmd_hash differs (e.g., `docker stop X` and `docker rm -f X`
+ *   both target X with different verbs — operator sees both, decides once).
+ */
+
+export const AUTHORITY_FRAGMENT_TEMPLATE = `
+## Approval Identifier Contract
+
+Each proposal MUST include:
+
+  id          — display label. Not a key. You may emit any short label.
+  cmd_hash    — sha256(command)[:12]. The runtime keys dedup on this.
+
+The runtime also computes a logical_key from (verb, target). Proposals
+sharing logical_key are surfaced as a cluster even with different
+cmd_hash values.
+`.trim()
+
+// --- Putting it together ---
+
+export interface ApprovalProposal {
+  id: string                    // Display only — DO NOT USE AS KEY
+  cmdHash: string               // Primary dedup key
+  logicalKey: string | null     // Secondary cluster key
+  command: string
+  proposedAt: string            // ISO timestamp
+  state: LifecycleState
+}
+
+export function dedupProposals(
+  newProposal: { id: string; command: string },
+  existing: ApprovalProposal[]
+): { duplicate: boolean; collapsedInto?: ApprovalProposal; logicalCluster?: ApprovalProposal[] } {
+  const cmdHash = shellCommandHash(newProposal.command)
+  const logicalKey = dockerLogicalKey(newProposal.command)
+
+  // Snapshot covers ALL in-flight states — not just pending
+  const inFlight = existing.filter((p) => IN_FLIGHT_STATES.includes(p.state))
+
+  // Hard duplicate: same cmd_hash
+  const exact = inFlight.find((p) => p.cmdHash === cmdHash)
+  if (exact) {
+    return { duplicate: true, collapsedInto: exact }
+  }
+
+  // Soft cluster: same logical_key, different command form
+  if (logicalKey) {
+    const cluster = inFlight.filter((p) => p.logicalKey === logicalKey)
+    if (cluster.length > 0) {
+      return { duplicate: false, logicalCluster: cluster }
+    }
+  }
+
+  return { duplicate: false }
+}
+
+// --- Anti-patterns ---
+
+/* ANTI-PATTERN 1: LLM ids as primary keys
+ *   `INSERT INTO approvals (id, ...) VALUES (?, ...)` where `id` is the
+ *   LLM-emitted string. Two LLM calls with substantively identical input
+ *   will produce different ids; the database rows do NOT collapse.
+ *
+ *   Fix: store `cmd_hash` as the PK and `display_id` as a label column.
+ */
+
+/* ANTI-PATTERN 2: Dedup snapshot filtered to a single state
+ *   `SELECT * FROM approvals WHERE state = 'pending'` for dedup comparison.
+ *   Misses `executing` and `interrupted` rows that are operator-visible.
+ *
+ *   Fix: use IN_FLIGHT_STATES list. Document which states are excluded
+ *   from dedup (typically `completed`, `failed`, `cancelled`, `expired`).
+ */
+
+/* ANTI-PATTERN 3: Hash the LLM's whole emitted JSON
+ *   `sha256(JSON.stringify(proposal))` includes display_id, timestamps,
+ *   reasoning prose — all of which drift per cycle even when the action
+ *   is identical. Hash explodes; collapse never happens.
+ *
+ *   Fix: hash only the operative payload (the command, the request body,
+ *   the target identifier — never the LLM's free-text fields).
+ */

package/dist/docs/patterns/middleware.ts

@@ -154,6 +154,89 @@ export function withRequestLogging(
   }
 }
 
+// --- Hot-path logging gate (fire-once / rate-limited) ---
+//
+// Source: Field report #319 §5. Stark's RlsDeadlineMiddleware originally
+// emitted `logger.critical(...)` on every 503 — at 100 rps × 24h = 8.6M
+// critical-level lines/day. No rate-limit, no fire-once. Would crater the
+// log aggregator and Sentry quota.
+//
+// ANY middleware that emits log lines on a hot path (every request, every
+// connection) MUST gate the emission. Two acceptable patterns:
+//
+// 1. Fire-once flag (preferred for state transitions): emit once when
+//    state changes, then suppress until reset. Pair with an audit row
+//    + Sentry capture inside the same fire-once branch.
+// 2. Rate-limit window (sample-based): emit at most N per window via a
+//    token-bucket or last-emit-timestamp gate.
+//
+// Naked `logger.critical(...)` per-request is a denial-of-service vector
+// against your own observability pipeline.
+
+type FireOnceState = { fired: boolean; firedAt: number | null };
+const fireOnceStates = new Map<string, FireOnceState>();
+
+/**
+ * Fire-once gate. Returns true if the caller should emit; false if
+ * emission has already happened for this key (until reset()).
+ *
+ * Use for state-transition events (deadline tripped, circuit opened,
+ * degraded mode entered) where the climactic event matters once.
+ */
+export function fireOnce(key: string): boolean {
+  const state = fireOnceStates.get(key) ?? { fired: false, firedAt: null };
+  if (state.fired) return false;
+  state.fired = true;
+  state.firedAt = Date.now();
+  fireOnceStates.set(key, state);
+  return true;
+}
+
+export function resetFireOnce(key: string): void {
+  fireOnceStates.delete(key);
+}
+
+/**
+ * Token-bucket rate limiter for hot-path logs. Returns true if the caller
+ * should emit; false if the bucket is empty.
+ *
+ * Use for sampled logging where you want N emissions per window
+ * (e.g., 1 per minute, 10 per hour).
+ */
+const tokenBuckets = new Map<string, { tokens: number; lastRefill: number }>();
+
+export function shouldEmit(
+  key: string,
+  maxPerWindow: number,
+  windowMs: number,
+): boolean {
+  const now = Date.now();
+  const bucket = tokenBuckets.get(key) ?? { tokens: maxPerWindow, lastRefill: now };
+  const elapsed = now - bucket.lastRefill;
+  if (elapsed >= windowMs) {
+    bucket.tokens = maxPerWindow;
+    bucket.lastRefill = now;
+  }
+  if (bucket.tokens > 0) {
+    bucket.tokens -= 1;
+    tokenBuckets.set(key, bucket);
+    return true;
+  }
+  tokenBuckets.set(key, bucket);
+  return false;
+}
+
+// Usage example: 503 deadline middleware
+//
+//   if (deadlinePassed) {
+//     if (fireOnce('rls-deadline-tripped')) {
+//       logger.fatal({ deadline_iso, evidence }, 'RLS migration deadline tripped');
+//       writeAuditRow({ action: 'rls_deadline_tripped', decisions: { ... } });
+//       Sentry.captureMessage('rls_deadline_tripped', 'fatal');
+//     }
+//     return new Response('Service Unavailable', { status: 503 });
+//   }
+
 // --- Rate limiting middleware ---
 // Simple in-memory rate limiter. Replace with Redis for multi-instance.
 const rateLimitMap = new Map<string, { count: number; resetAt: number }>()

package/dist/docs/patterns/multi-tenant-pool-bypass.ts

@@ -0,0 +1,134 @@
+/**
+ * Pattern: Multi-Tenant Pool Bypass (pre-org-resolution scope)
+ *
+ * Source: Field report #316 §8 (Union Station, M-04c W2). FORCE RLS with a
+ * non-owner runtime role means every connection acquired from the tenant
+ * pool MUST have `app.current_org_id` set before the first query. But some
+ * code paths legitimately need cross-tenant access:
+ *
+ *   - Auth pre-resolution (looking up which org a session belongs to)
+ *   - System daemons (queue cleanup, retention sweeps, leader-elected work)
+ *   - Admin endpoints (cross-tenant reports, ops tooling)
+ *
+ * These can't set org_id (they don't have one), so they need to bypass the
+ * tenant pool entirely and acquire from the admin pool. The
+ * `pre_org_resolution_scope` ContextVar wrapper makes this explicit and
+ * mechanically enforceable.
+ *
+ * The TS version below is illustrative; the canonical implementation in
+ * Union Station is Python (asyncpg). Same shape ports cleanly.
+ */
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+// ── ContextVar / AsyncLocalStorage ────────────────────────────────────────
+
+type TenantContext = {
+  org_id: number | null;       // null when in pre-resolution scope
+  pre_resolution: boolean;     // true ⇒ acquire from admin pool, not tenant pool
+};
+
+const tenantContext = new AsyncLocalStorage<TenantContext>();
+
+// ── Tenant scope (per-request, normal path) ──────────────────────────────
+
+export async function withTenant<T>(
+  org_id: number,
+  fn: () => Promise<T>,
+): Promise<T> {
+  return tenantContext.run({ org_id, pre_resolution: false }, fn);
+}
+
+// ── Pre-org-resolution scope (cross-tenant or auth lookup) ───────────────
+
+export async function preOrgResolutionScope<T>(fn: () => Promise<T>): Promise<T> {
+  return tenantContext.run({ org_id: null, pre_resolution: true }, fn);
+}
+
+// ── Pool acquisition routes by ContextVar ─────────────────────────────────
+
+import type { Pool, PoolClient } from 'pg'; // illustrative — real types vary
+
+declare const tenantPool: Pool;     // BYPASSRLS=f, RLS enforced
+declare const adminPool: Pool;      // BYPASSRLS=t, cross-tenant work
+
+export async function acquireConnection(): Promise<PoolClient> {
+  const ctx = tenantContext.getStore();
+
+  if (!ctx) {
+    throw new Error(
+      'acquireConnection called outside any tenant context. ' +
+      'Wrap caller with withTenant(orgId, ...) or preOrgResolutionScope(...).',
+    );
+  }
+
+  if (ctx.pre_resolution) {
+    // Cross-tenant work — acquire from the admin pool.
+    return adminPool.connect();
+  }
+
+  // Normal request — acquire from the tenant pool. The pool callback is
+  // expected to SET app.current_org_id so RLS policies can reference it.
+  if (ctx.org_id === null) {
+    throw new Error(
+      'Tenant context missing org_id outside pre_resolution scope. ' +
+      'This indicates a callsite that should have called preOrgResolutionScope().',
+    );
+  }
+  return tenantPool.connect();
+}
+
+// ── Usage examples ────────────────────────────────────────────────────────
+
+// 1. HTTP middleware (per-request)
+//
+//    app.use(async (req, res, next) => {
+//      await withTenant(req.user.org_id, () => next());
+//    });
+//
+// 2. Daemon (cross-tenant queue cleanup)
+//
+//    cron.schedule('*/5 * * * *', async () => {
+//      await preOrgResolutionScope(async () => {
+//        const conn = await acquireConnection(); // → admin pool
+//        await conn.query('DELETE FROM job_queue WHERE completed_at < NOW() - INTERVAL \'30 days\'');
+//        conn.release();
+//      });
+//    });
+//
+// 3. Auth lookup (caller doesn't yet know org_id)
+//
+//    async function resolveSession(sessionToken: string): Promise<{ org_id: number; user_id: string }> {
+//      return preOrgResolutionScope(async () => {
+//        const conn = await acquireConnection(); // → admin pool
+//        try {
+//          const row = await conn.query(
+//            'SELECT org_id, user_id FROM sessions WHERE token = $1 AND expires_at > NOW()',
+//            [sessionToken],
+//          );
+//          return row.rows[0];
+//        } finally {
+//          conn.release();
+//        }
+//      });
+//    }
+
+// ── Anti-patterns ─────────────────────────────────────────────────────────
+//
+// 1. Acquiring from the tenant pool in a daemon. Without org_id set, the RLS
+//    policy denies every query → daemon crashes on first tick. Or worse:
+//    the policy uses a fail-open arm and the daemon silently sees zero rows.
+//
+// 2. Bypassing FORCE RLS by hard-coding the connection string with the
+//    runtime role's password. The whole point of the admin pool is the
+//    BYPASSRLS=t identity — preserve that boundary.
+//
+// 3. preOrgResolutionScope wrapping per-request handlers. The middleware
+//    already set the tenant context; switching to admin pool there is a
+//    privilege escalation. preOrgResolutionScope is for code paths that
+//    legitimately don't have an org_id yet (or never will).
+//
+// 4. Forgetting to wrap lifespan startup. Field report #319 §2: 4 lifespan
+//    paths in Union Station's M-05 cutover failed-fast immediately because
+//    the RLS-strict role rejected unscoped queries. See BACKEND_ENGINEER.md
+//    "Lifespan & Daemon ContextVar Coverage" for the sweep checklist.