@oriro/orirocli 0.1.0

package/skills/craft/master-architect/references/languages.md

@@ -0,0 +1,748 @@
+# Language Reference — Deep Patterns & Best Practices
+
+## JAVA 21 (Current LTS)
+
+### Modern Java Patterns
+
+```java
+// Records (replace Lombok @Data)
+record TransactionDto(String id, BigDecimal amount, String currency, Instant createdAt) {}
+
+// Sealed classes (exhaustive type hierarchies)
+sealed interface PaymentResult permits PaymentSuccess, PaymentFailure, PaymentPending {}
+record PaymentSuccess(String transactionId) implements PaymentResult {}
+record PaymentFailure(String errorCode, String message) implements PaymentResult {}
+
+// Pattern matching switch (exhaustive, compiler-checked)
+String describe(PaymentResult result) {
+    return switch (result) {
+        case PaymentSuccess s  -> "Approved: " + s.transactionId();
+        case PaymentFailure f  -> "Declined: " + f.message();
+        case PaymentPending p  -> "Processing";
+    };
+}
+
+// Virtual threads (Project Loom) — handle 1M+ concurrent connections
+try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+    IntStream.range(0, 100_000).forEach(i ->
+        executor.submit(() -> handleRequest(i))
+    );
+}
+
+// Text blocks
+String json = """
+    {
+        "type": "fraud_detected",
+        "transactionId": "%s"
+    }
+    """.formatted(txId);
+```
+
+### Spring Boot 3.x Essentials
+
+```java
+// Minimal REST controller
+@RestController @RequestMapping("/api/v1/transactions")
+@RequiredArgsConstructor
+public class TransactionController {
+    private final TransactionService service;
+
+    @GetMapping
+    public Page<TransactionDto> list(
+        @AuthenticationPrincipal UserDetails user,
+        @RequestParam(defaultValue = "0") int page,
+        @RequestParam(defaultValue = "20") int size
+    ) {
+        return service.findByUser(user.getUsername(), PageRequest.of(page, size));
+    }
+
+    @PostMapping
+    @ResponseStatus(HttpStatus.CREATED)
+    public TransactionDto create(@Valid @RequestBody CreateTransactionRequest req,
+                                  @AuthenticationPrincipal UserDetails user) {
+        return service.create(req, user.getUsername());
+    }
+}
+
+// Global exception handler
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+    @ExceptionHandler(NotFoundException.class)
+    @ResponseStatus(HttpStatus.NOT_FOUND)
+    public ProblemDetail handleNotFound(NotFoundException ex) {
+        return ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
+    }
+}
+```
+
+### Java Pitfalls
+
+```
+BigDecimal for money:   NEVER double/float. new BigDecimal("19.99") not new BigDecimal(19.99)
+Optional correctly:     Never as method param. Never .get() without .isPresent(). Use .orElseThrow()
+String concatenation:   StringBuilder in loops. Never "str" + var in loop body.
+equals/hashCode:        Always override together. Records do this automatically.
+Static analysis:        SpotBugs + CheckStyle + SonarQube — run in CI.
+```
+
+---
+
+## PYTHON 3.12+
+
+### Modern Python Patterns
+
+```python
+from __future__ import annotations
+from typing import TypeVar, Generic
+from dataclasses import dataclass, field
+from datetime import datetime
+import asyncio
+
+# Dataclasses (not dicts for structured data)
+@dataclass(frozen=True, slots=True)  # frozen=immutable, slots=memory-efficient
+class Transaction:
+    id: str
+    amount: Decimal
+    currency: str
+    created_at: datetime = field(default_factory=datetime.utcnow)
+
+# Type aliases and generics
+type UserId = str
+type TransactionId = str
+
+# Structural pattern matching (3.10+)
+match result:
+    case {"status": "success", "data": data}:
+        process(data)
+    case {"status": "error", "code": code} if code >= 500:
+        alert_team(code)
+    case _:
+        log_unknown(result)
+
+# Async patterns (always use async for I/O)
+async def fetch_fraud_signals(tx_ids: list[str]) -> dict[str, float]:
+    async with aiohttp.ClientSession() as session:
+        tasks = [fetch_signal(session, tx_id) for tx_id in tx_ids]
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+        return {
+            tx_id: score
+            for tx_id, score in zip(tx_ids, results)
+            if not isinstance(score, Exception)
+        }
+```
+
+### FastAPI (Production Patterns)
+
+```python
+from fastapi import FastAPI, Depends, HTTPException, status
+from fastapi.middleware.cors import CORSMiddleware
+from contextlib import asynccontextmanager
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup
+    await db.connect()
+    await redis.ping()
+    yield
+    # Shutdown
+    await db.disconnect()
+    await redis.aclose()
+
+app = FastAPI(lifespan=lifespan)
+
+# Dependency injection
+async def get_current_user(token: str = Depends(oauth2_scheme), db = Depends(get_db)):
+    payload = verify_jwt(token)
+    user = await db.users.get(payload["sub"])
+    if not user:
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED)
+    return user
+
+@app.get("/transactions", response_model=Page[TransactionResponse])
+async def list_transactions(
+    page: int = Query(1, ge=1),
+    limit: int = Query(20, le=100),
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db)
+):
+    return await transaction_service.paginate(db, current_user.id, page, limit)
+```
+
+### Python Pitfalls
+
+```python
+# Mutable default args — classic bug
+def bad(items=[]):    items.append(1); return items  # SAME list across calls
+def good(items=None): items = items or []; items.append(1); return items
+
+# Late binding closures
+# bad: all lambdas capture same i
+funcs = [lambda: i for i in range(3)]  # all return 2
+# good: capture by value
+funcs = [lambda i=i: i for i in range(3)]  # 0, 1, 2
+
+# Blocking in async — kills performance
+async def bad(): time.sleep(1)          # blocks entire event loop
+async def good(): await asyncio.sleep(1) # yields to other coroutines
+
+# String formatting — always f-strings (fastest)
+name = "World"
+bad  = "Hello, " + name   # concatenation
+bad  = "Hello, %s" % name  # old style
+good = f"Hello, {name}"    # f-strings — fastest, most readable
+```
+
+---
+
+## TYPESCRIPT (Strict Mode Always)
+
+### Type System Mastery
+
+```typescript
+// Discriminated unions — exhaustive pattern matching
+type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };
+
+function divide(a: number, b: number): Result<number> {
+  if (b === 0) return { ok: false, error: new Error("Division by zero") };
+  return { ok: true, value: a / b };
+}
+
+// Template literal types — type-safe event names
+type EventName = `${string}.created` | `${string}.updated` | `${string}.deleted`;
+type UserEvent = `user.${"created" | "updated" | "deleted"}`;
+
+// Conditional types — advanced type transformations
+type NonNullable<T> = T extends null | undefined ? never : T;
+type ReturnType<T> = T extends (...args: any[]) => infer R ? R : never;
+type Awaited<T> = T extends Promise<infer U> ? Awaited<U> : T;
+
+// Branded types — prevent primitive obsession
+type UserId = string & { readonly _brand: "UserId" };
+type Amount = number & { readonly _brand: "Amount" };
+const userId = "abc-123" as UserId; // explicit cast required
+function getUser(id: UserId) {} // compiler prevents passing arbitrary string
+
+// Satisfies operator (4.9+) — check type without widening
+const config = {
+  db: { host: "localhost", port: 5432 },
+  redis: { host: "localhost", port: 6379 },
+} satisfies Record<string, { host: string; port: number }>;
+// config.db.host is still string literal type (not widened to string)
+```
+
+### Next.js 14 App Router Patterns
+
+```typescript
+// Server component (default — zero JS sent to client)
+async function TransactionList({ userId }: { userId: string }) {
+  const transactions = await db.transaction.findMany({ where: { userId } })
+  return <ul>{transactions.map(tx => <TransactionItem key={tx.id} tx={tx} />)}</ul>
+}
+
+// Server action (form mutation without API route)
+async function createTransaction(formData: FormData) {
+  'use server'
+  const amount = formData.get('amount') as string
+  await db.transaction.create({ data: { amount: parseFloat(amount), userId: await getUserId() }})
+  revalidatePath('/dashboard')
+}
+
+// Route handler with proper error handling
+export async function POST(request: Request) {
+  try {
+    const body = await request.json()
+    const validated = schema.parse(body)  // Zod validation
+    const result = await service.create(validated)
+    return Response.json(result, { status: 201 })
+  } catch (err) {
+    if (err instanceof ZodError) {
+      return Response.json({ error: err.errors }, { status: 400 })
+    }
+    return Response.json({ error: 'Internal error' }, { status: 500 })
+  }
+}
+```
+
+---
+
+## GO 1.22+
+
+### Production Patterns
+
+```go
+// Error handling — always explicit, never ignore
+func getUser(ctx context.Context, id string) (*User, error) {
+    user, err := db.QueryRowContext(ctx, "SELECT * FROM users WHERE id = $1", id).Scan(&user)
+    if err != nil {
+        if errors.Is(err, sql.ErrNoRows) {
+            return nil, fmt.Errorf("user %s: %w", id, ErrNotFound) // wrap for context
+        }
+        return nil, fmt.Errorf("query user %s: %w", id, err)
+    }
+    return user, nil
+}
+
+// Context propagation — always pass ctx as first param
+func (s *Service) ProcessTransaction(ctx context.Context, req Request) (*Response, error) {
+    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+    defer cancel()
+    // All downstream calls use this ctx — cancellation propagates automatically
+    return s.repo.Create(ctx, req)
+}
+
+// Goroutine leak prevention — always use errgroup or WaitGroup
+func fetchAll(ctx context.Context, ids []string) ([]Result, error) {
+    g, ctx := errgroup.WithContext(ctx)
+    results := make([]Result, len(ids))
+    for i, id := range ids {
+        i, id := i, id  // capture loop vars
+        g.Go(func() error {
+            result, err := fetch(ctx, id)
+            if err != nil { return err }
+            results[i] = result
+            return nil
+        })
+    }
+    return results, g.Wait()
+}
+
+// Struct embedding for interfaces
+type Service struct {
+    db     *sql.DB
+    cache  Cache          // interface — easy to mock in tests
+    logger *slog.Logger   // structured logging — use slog (stdlib since 1.21)
+}
+```
+
+### Go Pitfalls
+
+```
+Goroutine leaks:    Always defer cancel() after context.WithTimeout/WithCancel
+Slice gotchas:      append may or may not create new backing array — use copy() when in doubt
+Interface nil:      var err *MyError = nil; var i error = err; i != nil is TRUE (interface type != nil)
+Map not safe:       sync.Map or mutex for concurrent map access
+String conversion:  []byte(str) copies — use unsafe.Slice for zero-copy in hot paths
+```
+
+---
+
+## RUST (2021 Edition)
+
+### Core Patterns
+
+```rust
+// Result and Option — no null pointer exceptions, ever
+fn parse_amount(s: &str) -> Result<f64, ParseError> {
+    s.trim().parse::<f64>().map_err(|e| ParseError::InvalidAmount(e.to_string()))
+}
+
+// Ownership-safe shared state
+use std::sync::{Arc, RwLock};
+#[derive(Clone)]
+struct AppState { db: Arc<Pool<Postgres>>, cache: Arc<RwLock<HashMap<String, Value>>> }
+
+// Axum web handler (async, zero-cost)
+async fn create_transaction(
+    State(state): State<AppState>,
+    Json(payload): Json<CreateRequest>,
+) -> Result<Json<Transaction>, AppError> {
+    let tx = sqlx::query_as::<_, Transaction>("INSERT INTO transactions ...")
+        .bind(&payload.amount)
+        .fetch_one(&*state.db)
+        .await?;
+    Ok(Json(tx))
+}
+
+// Traits for behavior abstraction
+trait FraudDetector: Send + Sync {
+    async fn score(&self, tx: &Transaction) -> Result<f64, Error>;
+}
+```
+
+---
+
+## SQL — PRODUCTION PATTERNS
+
+### Query Optimization
+
+```sql
+-- EXPLAIN ANALYZE every new query in production
+EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
+SELECT * FROM transactions WHERE user_id = $1 AND created_at > $2;
+
+-- Index design rules:
+-- 1. Index columns used in WHERE, JOIN ON, ORDER BY
+-- 2. Composite index: put highest-selectivity column first
+-- 3. Partial index for filtered queries:
+CREATE INDEX idx_pending_transactions ON transactions (created_at)
+WHERE status = 'pending';  -- Only indexes pending rows
+
+-- 4. Index for LIKE prefix search:
+CREATE INDEX idx_email_prefix ON users (email text_pattern_ops);
+-- Supports: WHERE email LIKE 'user@%'
+
+-- Avoid N+1: use JOIN or subquery instead
+-- BAD (N+1):
+SELECT * FROM orders;  -- then for each order:
+SELECT * FROM order_items WHERE order_id = $1;
+
+-- GOOD (1 query):
+SELECT o.*, json_agg(i.*) as items
+FROM orders o
+LEFT JOIN order_items i ON i.order_id = o.id
+WHERE o.user_id = $1
+GROUP BY o.id;
+```
+
+### PostgreSQL Power Features
+
+```sql
+-- Row-level security (multi-tenant isolation)
+ALTER TABLE transactions ENABLE ROW LEVEL SECURITY;
+CREATE POLICY tenant_isolation ON transactions
+    USING (org_id = current_setting('app.current_org_id')::uuid);
+
+-- JSONB for flexible metadata (indexed)
+ALTER TABLE transactions ADD COLUMN metadata JSONB DEFAULT '{}';
+CREATE INDEX idx_tx_metadata_gin ON transactions USING gin(metadata);
+-- Query: WHERE metadata @> '{"source": "mobile"}'
+
+-- Window functions (analytics without GROUP BY collapse)
+SELECT
+    user_id,
+    amount,
+    SUM(amount) OVER (PARTITION BY user_id ORDER BY created_at) as running_total,
+    ROW_NUMBER() OVER (PARTITION BY user_id ORDER BY created_at DESC) as rn
+FROM transactions;
+
+-- CTEs for readability (optimizer inlines them in PG 12+)
+WITH high_risk AS (
+    SELECT user_id, COUNT(*) as flagged_count
+    FROM transactions WHERE risk_score > 0.8
+    GROUP BY user_id HAVING COUNT(*) > 3
+)
+SELECT u.email, h.flagged_count
+FROM users u JOIN high_risk h USING (user_id);
+
+-- Advisory locks for distributed mutex (no external Redis needed for simple cases)
+SELECT pg_advisory_lock(hashtext('process-transaction-' || transaction_id));
+-- ... do work ...
+SELECT pg_advisory_unlock(hashtext('process-transaction-' || transaction_id));
+```
+
+---
+
+## BASH — PRODUCTION SCRIPTS
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail  # e=exit on error, u=error on unset vars, o pipefail=pipe errors propagate
+IFS=$'\n\t'        # Safer word splitting
+
+# Always quote variables
+file="${1:-}"
+if [[ -z "$file" ]]; then
+    echo "Usage: $0 <filename>" >&2
+    exit 1
+fi
+
+# Functions for reuse
+log() { echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] $*" >&2; }
+die() { log "ERROR: $*"; exit 1; }
+
+# Trap for cleanup
+tmp_dir=$(mktemp -d)
+trap 'rm -rf "$tmp_dir"' EXIT
+
+# Check dependencies
+command -v jq >/dev/null || die "jq is required but not installed"
+command -v gcloud >/dev/null || die "gcloud is required but not installed"
+
+# Process with error handling
+if ! result=$(some_command 2>&1); then
+    die "Command failed: $result"
+fi
+
+log "Completed successfully"
+```
+
+---
+
+## ELIXIR / ERLANG (Real-Time Systems)
+
+```elixir
+# Phoenix LiveView — real-time UI without JS complexity
+defmodule FraudDashboardLive do
+  use Phoenix.LiveView
+
+  def mount(_params, _session, socket) do
+    if connected?(socket), do: Phoenix.PubSub.subscribe(App.PubSub, "fraud_alerts")
+    {:ok, assign(socket, alerts: load_recent_alerts())}
+  end
+
+  # Handles real-time messages from PubSub
+  def handle_info({:new_alert, alert}, socket) do
+    {:noreply, update(socket, :alerts, &[alert | &1])}
+  end
+end
+```
+
+Use Elixir when: real-time features (chat, live dashboards, presence), high-concurrency (millions of connections), fault-tolerant distributed systems, IoT backends.
+
+---
+
+## WEBASSEMBLY (WASM)
+
+Modern use cases:
+
+- Run CPU-intensive code in the browser (image processing, crypto, compression)
+- Compile Rust/C/C++ to WASM for near-native browser performance
+- WASI for server-side sandboxed plugins
+
+```rust
+// Rust → WASM via wasm-pack
+use wasm_bindgen::prelude::*;
+
+#[wasm_bindgen]
+pub fn process_transactions(data: &[u8]) -> Vec<u8> {
+    // CPU-intensive processing — runs in browser at near-native speed
+    let transactions: Vec<Transaction> = serde_json::from_slice(data).unwrap();
+    let results = transactions.iter().map(score_transaction).collect::<Vec<_>>();
+    serde_json::to_vec(&results).unwrap()
+}
+```
+
+---
+
+## DART (Flutter)
+
+```dart
+// Null safety — always enabled (Dart 3+)
+String? maybeNull = null;
+String definitelyNotNull = maybeNull ?? 'default';
+String guaranteed = maybeNull!;  // throws if null — use sparingly
+
+// Records (Dart 3) — lightweight data structures
+(String name, int age) person = ('<user>', 40);
+print(person.$1);  // '<user>'
+
+// Sealed classes — exhaustive pattern matching
+sealed class PaymentResult {}
+class Success extends PaymentResult { final String txId; Success(this.txId); }
+class Failure extends PaymentResult { final String error; Failure(this.error); }
+
+String describe(PaymentResult r) => switch(r) {
+  Success s => 'OK: ${s.txId}',
+  Failure f => 'Error: ${f.error}',
+};  // Compiler error if not exhaustive
+
+// Async/await — same as JS/TS
+Future<List<Transaction>> fetchTransactions(String userId) async {
+  final response = await http.get(Uri.parse('$baseUrl/transactions?userId=$userId'));
+  if (response.statusCode != 200) throw ApiException(response.statusCode);
+  return (jsonDecode(response.body) as List)
+      .map((e) => Transaction.fromJson(e))
+      .toList();
+}
+
+// Streams — reactive data
+Stream<int> countUp(int max) async* {
+  for (var i = 0; i < max; i++) {
+    await Future.delayed(const Duration(seconds: 1));
+    yield i;
+  }
+}
+```
+
+---
+
+## SOLIDITY (Smart Contracts / Web3)
+
+```solidity
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+import "@openzeppelin/contracts/token/ERC20/ERC20.sol";
+import "@openzeppelin/contracts/access/Ownable.sol";
+import "@openzeppelin/contracts/utils/ReentrancyGuard.sol";
+
+// Security patterns — ALWAYS use these in production contracts
+contract SecureToken is ERC20, Ownable, ReentrancyGuard {
+    uint256 public constant MAX_SUPPLY = 1_000_000 * 10**18;
+    mapping(address => bool) public blacklisted;
+
+    event Blacklisted(address indexed account);
+
+    constructor() ERC20("MyToken", "MTK") Ownable(msg.sender) {}
+
+    // Checks-Effects-Interactions pattern (prevent reentrancy)
+    function mint(address to, uint256 amount) external onlyOwner nonReentrant {
+        require(!blacklisted[to], "Blacklisted address");    // CHECK
+        require(totalSupply() + amount <= MAX_SUPPLY, "Exceeds max supply");  // CHECK
+        _mint(to, amount);                                   // EFFECT (state change)
+        // No external calls after state changes (prevent reentrancy)
+    }
+
+    // Custom errors (cheaper than strings — Solidity 0.8+)
+    error Unauthorized(address caller);
+    error InsufficientBalance(uint256 available, uint256 required);
+
+    function _update(address from, address to, uint256 value)
+        internal override
+    {
+        if (blacklisted[from] || blacklisted[to]) revert Unauthorized(from);
+        super._update(from, to, value);
+    }
+}
+```
+
+**Solidity Security Checklist:**
+
+```
+□ Reentrancy:       ReentrancyGuard on all state-changing external calls
+□ Integer overflow: Solidity 0.8+ has built-in. Use SafeMath only for older.
+□ Access control:   OpenZeppelin Ownable/AccessControl. Never trust msg.sender without check.
+□ Oracle manipulation: Never use single oracle (Chainlink preferred, time-weighted for DEX)
+□ Front-running:    Commit-reveal scheme for sensitive operations
+□ Audit:            ALWAYS audit before mainnet. CertiK, Trail of Bits, OpenZeppelin audits.
+□ Testing:          Hardhat + Foundry. 100% branch coverage. Fuzzing required.
+□ Upgrades:         Proxy pattern (OpenZeppelin UUPS/Transparent) with timelocks
+```
+
+---
+
+## GRAPHQL — PRODUCTION PATTERNS
+
+```typescript
+// Schema-first design (use SDL, not code-first for large schemas)
+// schema.graphql
+type Transaction {
+  id: ID!
+  amount: Float!
+  currency: String!
+  status: TransactionStatus!
+  user: User!
+  riskScore: Float
+  createdAt: DateTime!
+}
+
+enum TransactionStatus { PENDING COMPLETED FAILED REFUNDED }
+
+type Query {
+  transaction(id: ID!): Transaction
+  transactions(
+    filter: TransactionFilter
+    first: Int = 20
+    after: String    # Cursor-based pagination
+  ): TransactionConnection!
+}
+
+type Mutation {
+  createTransaction(input: CreateTransactionInput!): TransactionResult!
+}
+
+type Subscription {
+  transactionUpdated(orgId: ID!): Transaction!  # Real-time updates
+}
+
+# --- Resolver (TypeScript with DataLoader) ---
+import DataLoader from 'dataloader'
+
+// N+1 problem solution — batch all user lookups into one query
+const userLoader = new DataLoader<string, User>(async (userIds) => {
+  const users = await db.user.findMany({ where: { id: { in: [...userIds] }}})
+  return userIds.map(id => users.find(u => u.id === id) ?? new Error(`User ${id} not found`))
+})
+
+const resolvers = {
+  Transaction: {
+    user: (tx: Transaction) => userLoader.load(tx.userId),  // Batched automatically
+    riskScore: async (tx: Transaction, _, { user }) => {
+      // Field-level auth — only admins see risk scores
+      if (!user.isAdmin) return null
+      return fraudService.getScore(tx.id)
+    }
+  }
+}
+
+// Persisted queries — prevent arbitrary query abuse in production
+// Client sends query hash, not query string → server looks up allowed query
+```
+
+### GraphQL Security
+
+```
+Depth limiting:      Max query depth = 10 (prevent deeply nested abuse queries)
+Complexity limits:   Assign cost to fields, reject queries over budget
+Introspection:       DISABLE in production (hides schema from attackers)
+Rate limiting:       Per-field and per-operation, not just per-request
+Auth:                Resolve auth in context (not in each resolver) — consistent
+Field-level auth:    Use @auth directive or resolver-level checks per field
+Query allowlisting:  Production uses persisted queries only
+```
+
+---
+
+## gRPC — SERVICE-TO-SERVICE
+
+```protobuf
+// fraud.proto
+syntax = "proto3";
+package fraud.v1;
+
+import "google/protobuf/timestamp.proto";
+
+service FraudDetector {
+  rpc ScoreTransaction(ScoreRequest) returns (ScoreResponse);
+  rpc StreamAlerts(AlertStreamRequest) returns (stream FraudAlert);  // Server streaming
+  rpc BatchScore(stream ScoreRequest) returns (stream ScoreResponse); // Bidirectional
+}
+
+message ScoreRequest {
+  string transaction_id = 1;
+  double amount = 2;
+  string currency = 3;
+  string user_id = 4;
+  google.protobuf.Timestamp created_at = 5;
+  map<string, string> metadata = 6;
+}
+
+message ScoreResponse {
+  string transaction_id = 1;
+  double risk_score = 2;
+  repeated string risk_factors = 3;
+  bool should_block = 4;
+}
+```
+
+```typescript
+// TypeScript gRPC server
+import * as grpc from "@grpc/grpc-js";
+import * as protoLoader from "@grpc/proto-loader";
+
+const packageDef = protoLoader.loadSync("fraud.proto", { keepCase: true });
+const fraudProto = grpc.loadPackageDefinition(packageDef).fraud.v1 as any;
+
+const server = new grpc.Server();
+server.addService(fraudProto.FraudDetector.service, {
+  async scoreTransaction(call: any, callback: any) {
+    const { transaction_id, amount, user_id } = call.request;
+    try {
+      const score = await fraudEngine.score({
+        transactionId: transaction_id,
+        amount,
+        userId: user_id,
+      });
+      callback(null, { transaction_id, risk_score: score.value, should_block: score.value > 0.9 });
+    } catch (err) {
+      callback({ code: grpc.status.INTERNAL, message: err.message });
+    }
+  },
+});
+
+// Interceptor for auth + logging (gRPC middleware equivalent)
+server.addService(
+  fraudProto.FraudDetector.service,
+  withInterceptors([authInterceptor, loggingInterceptor, tracingInterceptor], handlers),
+);
+```