diff --git a/rag-agentic-dashboard/data/prompt-mgmt-arch.json b/rag-agentic-dashboard/data/prompt-mgmt-arch.json new file mode 100644 index 0000000..55a7e5e --- /dev/null +++ b/rag-agentic-dashboard/data/prompt-mgmt-arch.json @@ -0,0 +1,1894 @@ +{ + "docRef": "PROMPT-MGMT-ARCH-WP-043", + "version": "1.0.0", + "horizon": "2026-2030", + "classification": "CONFIDENTIAL \u2014 Product / CAIO / CISO / DPO / Head of Engineering / Internal Audit", + "title": "Prompt Management & Reporting Application \u2014 End-to-End Technical & Governance Architecture", + "subtitle": "Advanced Prompt Engineering, AI Safety Governance, Collaborative Refinement, RBAC, Audit, Distributed Tracing, Personas, Version Control, Markdown/PDF Export, and Firestore-Backed Report Versioning", + "owner": "VP Product + CAIO; co-signed by CISO, DPO, Head of Platform Engineering, Head of Internal Audit, AI Safety Lead", + "buildsOn": [ + "WP-035 ENT-AGI-GOV-MASTER", + "WP-036 WFAP-GEMINI-IMPL", + "WP-037 GSIFI-AIMS-BLUEPRINT", + "WP-038 AGI-REG-RESILIENT", + "WP-039 INST-AGI-MASTER", + "WP-040 ENT-AGI-REF-IMPL", + "WP-041 TIER13-FULLSTACK", + "WP-042 SENTINEL-V24-DEEPDIVE" + ], + "regimes": [ + "EU AI Act 2026 (Arts 9, 10, 13, 14, 50, 53, 55)", + "NIST AI RMF 1.0 (Govern/Map/Measure/Manage)", + "ISO/IEC 42001 (AIMS)", + "ISO/IEC 23894 (AI risk management)", + "ISO/IEC 27001/27701 (ISMS / PIMS)", + "ISO/IEC 5338 (AI lifecycle)", + "GDPR Arts 5, 6, 22, 25, 32, 35", + "WCAG 2.2 AA (accessibility)", + "SOC 2 Type II (Security/Availability/Confidentiality/Privacy)", + "OWASP LLM Top 10 (2025)", + "OpenTelemetry semantic conventions for GenAI", + "FIPS 140-3 (KMS / HSM)", + "OECD AI Principles" + ], + "apiPrefix": "/api/prompt-mgmt-arch", + "personas": [ + { + "id": "PERSONA-PE", + "name": "Prompt Engineer", + "scope": "Authors, refines, A/B tests prompts; manages variables and templates" + }, + { + "id": "PERSONA-RV", + "name": "Reviewer / SME", + "scope": "Approves prompt changes; signs off on safety & compliance gates" + }, + { + "id": "PERSONA-AN", + "name": "Analyst / Reporter", + "scope": "Generates reports, exports PDF, consumes Markdown\u2192HTML output" + }, + { + "id": "PERSONA-OP", + "name": "MLOps / Model Steward", + "scope": "Operates model registry, deploys models, manages keys" + }, + { + "id": "PERSONA-AD", + "name": "Admin", + "scope": "Manages RBAC, tenants, audit retention, key rotation" + }, + { + "id": "PERSONA-AU", + "name": "Auditor / Compliance", + "scope": "Read-only WORM audit, exports evidence packs" + }, + { + "id": "PERSONA-EU", + "name": "End User / Consumer", + "scope": "Runs published prompts; receives outputs and reports" + } + ], + "counts": { + "modules": 14, + "sections": 59, + "schemas": 12, + "codeExamples": 16, + "caseStudies": 6, + "kpis": 22, + "rbacRoles": 9, + "dataFlows": 6, + "threats": 8, + "traceabilityRows": 10, + "apiRoutes": 96 + }, + "modules": [ + { + "id": "M1", + "title": "M1 \u2014 System Context, Personas & Reference Architecture", + "summary": "End-to-end context diagram, personas, tenancy model, and the layered reference architecture that ties prompt engineering, model operations, and reporting under a unified governance plane.", + "covers": [ + "context diagram", + "personas", + "multi-tenancy", + "reference architecture" + ], + "sections": [ + { + "id": "M1-S1", + "title": "Context Diagram (logical)", + "content": { + "actors": [ + "Prompt Engineer", + "Reviewer", + "Analyst", + "MLOps", + "Admin", + "Auditor", + "End User" + ], + "edgeSystems": [ + "IdP (OIDC / SAML)", + "Model Registry", + "LLM Providers", + "Vector DB / RAG store", + "Firestore (versioned reports)", + "KMS / HSM (FIPS 140-3)", + "SIEM", + "Object storage (PDF exports)" + ], + "trustBoundaries": [ + "Browser \u2194 Edge", + "Edge \u2194 App API", + "App API \u2194 Model Gateway", + "App API \u2194 Firestore", + "App API \u2194 KMS", + "App API \u2194 Audit (WORM)" + ] + } + }, + { + "id": "M1-S2", + "title": "Layered Reference Architecture", + "content": [ + "L0 Identity & Tenancy: OIDC/SAML SSO, MFA, SCIM, tenant isolation by Firestore parent path + IAM", + "L1 Edge: WAF, CDN, CSP, COOP/COEP, rate limit, bot mgmt; static SPA + signed cookies", + "L2 App API (Node.js): Express/Fastify; AuthN/Z; orchestrates prompts, variables, runs, reports", + "L3 Model Gateway: provider abstraction (OpenAI/Anthropic/Vertex/Bedrock/local); policy enforcement; PII redaction; cost guardrails", + "L4 Governance Plane: OPA/Rego, Sentinel sidecar, Cognitive Resonance Monitor, kill-switch, RBAC, secret broker", + "L5 Data Plane: Firestore (prompts, runs, reports, versions), Vector DB (RAG), Object store (PDFs, attachments), KMS", + "L6 Observability: OpenTelemetry GenAI, distributed tracing for agent swarms, structured logs, metrics, WORM audit" + ] + }, + { + "id": "M1-S3", + "title": "Multi-Tenancy & Isolation", + "content": { + "tenantModel": "tenants/{tid}/{collection}/...", + "isolation": [ + "per-tenant CMK in KMS", + "per-tenant Firestore rules", + "per-tenant rate limits", + "per-tenant audit topic key in WORM" + ], + "noisyNeighbor": "Token-bucket per tenant + cost ceiling per persona" + } + }, + { + "id": "M1-S4", + "title": "Personas", + "content": [ + { + "id": "PERSONA-PE", + "name": "Prompt Engineer", + "scope": "Authors, refines, A/B tests prompts; manages variables and templates" + }, + { + "id": "PERSONA-RV", + "name": "Reviewer / SME", + "scope": "Approves prompt changes; signs off on safety & compliance gates" + }, + { + "id": "PERSONA-AN", + "name": "Analyst / Reporter", + "scope": "Generates reports, exports PDF, consumes Markdown\u2192HTML output" + }, + { + "id": "PERSONA-OP", + "name": "MLOps / Model Steward", + "scope": "Operates model registry, deploys models, manages keys" + }, + { + "id": "PERSONA-AD", + "name": "Admin", + "scope": "Manages RBAC, tenants, audit retention, key rotation" + }, + { + "id": "PERSONA-AU", + "name": "Auditor / Compliance", + "scope": "Read-only WORM audit, exports evidence packs" + }, + { + "id": "PERSONA-EU", + "name": "End User / Consumer", + "scope": "Runs published prompts; receives outputs and reports" + } + ] + }, + { + "id": "M1-S5", + "title": "Tech Stack Summary", + "content": { + "frontend": "React + Vite + TypeScript; Tailwind CSS; shadcn/ui; React Router; React Query; @marked/marked + sanitize-html; highlight.js / Shiki; jsPDF + html2canvas (or server-side puppeteer)", + "backend": "Node.js (Express/Fastify), TypeScript, Zod for schema validation; Pino logger; OpenTelemetry SDK", + "data": "Firestore (versioned reports, prompts), Cloud Storage (PDF), Pinecone/PGVector (RAG), Kafka WORM (audit)", + "infra": "Kubernetes + OPA Gatekeeper; Terraform IaC; PM2/systemd in dev; sidecars for Sentinel governance" + } + } + ] + }, + { + "id": "M2", + "title": "M2 \u2014 Prompt Authoring, Templates, Variables & Variable Linking", + "summary": "Schema-first prompt template system with typed variables, cross-prompt variable linking, library taxonomy, search, and lint rules.", + "covers": [ + "prompt template", + "variables", + "linking", + "lint", + "search" + ], + "sections": [ + { + "id": "M2-S1", + "title": "Prompt Template Schema (canonical)", + "content": { + "fields": [ + "id", + "tenantId", + "name", + "description", + "tags[]", + "categoryPath", + "personaTargets[]", + "modelHints[]", + "body (Markdown+Liquid)", + "variables[]", + "linkedVariables[]", + "personaId", + "safetyTier", + "version", + "parentVersionId", + "createdBy", + "createdAt", + "checksum (sha256)", + "owners[]", + "approvers[]", + "status (draft|in_review|approved|deprecated)" + ], + "bodyLanguage": "Markdown with Liquid-style {{var}} placeholders + {% if %}/{% for %} for control flow; sandboxed eval" + } + }, + { + "id": "M2-S2", + "title": "Variable Definitions & Linking", + "content": { + "variableSchema": [ + "id", + "name", + "type (string|number|boolean|enum|json|file|secret-ref)", + "default", + "validation (regex/min/max)", + "redactionPolicy", + "description", + "scope (template|prompt|tenant|global)", + "linkedFromTemplateId?", + "linkedField?", + "writeable" + ], + "linkingRules": [ + "Linked variables resolve at render time via DAG; cycles rejected at save", + "Cross-template links require both templates to be in the same tenant or shared library", + "Secret-ref variables resolve via KMS-backed secret broker; raw value never persisted with prompt" + ] + } + }, + { + "id": "M2-S3", + "title": "Template Library & Search", + "content": { + "indexes": [ + "Firestore composite index on (tenantId, status, tags)", + "OpenSearch / Algolia: full-text on name+description+body+tags", + "Vector index on embeddings (semantic search)" + ], + "rankSignals": [ + "recency", + "approval status", + "popularity (runs)", + "win-rate from A/B tests", + "compliance score" + ] + } + }, + { + "id": "M2-S4", + "title": "Lint & Quality Rules", + "content": [ + "PII pattern scan (emails, SSN, IBAN, card) \u2014 blocks save unless redacted/masked", + "Prompt-injection canary lint (e.g., 'ignore previous', 'system override') flagged", + "Token-budget lint: warns when expected tokens > model context * 0.7", + "Variable hygiene: every {{var}} must be declared; no unused declared variables", + "Bias-sensitive language detector (configurable allowlists per tenant)" + ] + }, + { + "id": "M2-S5", + "title": "Authoring UX", + "content": { + "editor": "Monaco with Markdown + Liquid grammar; inline variable chips; live preview pane with sanitized Markdown\u2192HTML; keyboard shortcuts; offline-safe drafts", + "accessibility": "ARIA roles for landmarks; focus traps in dialogs; high-contrast theme; reduced-motion; keyboard-only flows verified to WCAG 2.2 AA" + } + } + ] + }, + { + "id": "M3", + "title": "M3 \u2014 Collaborative Prompt Refinement", + "summary": "Real-time co-editing, suggestion-mode reviews, threaded comments, AI co-pilot suggestions, and conflict resolution under audit.", + "covers": [ + "co-editing", + "comments", + "suggestion mode", + "AI co-pilot" + ], + "sections": [ + { + "id": "M3-S1", + "title": "CRDT-Based Co-Editing", + "content": { + "engine": "Yjs (Y.Doc) over WebSocket with auth token; per-document awareness channel", + "persistence": "Firestore snapshot every N edits; full Yjs update log appended to WORM audit", + "presence": "User cursors, selection, color; idle timeout 5 min; sticky reviewer locks" + } + }, + { + "id": "M3-S2", + "title": "Suggestion Mode & Review Workflow", + "content": [ + "Edits in 'review' branch produce diff hunks; reviewer accepts/rejects per hunk", + "Two-eyes principle: high-risk templates require \u2265 2 reviewer approvals (Reviewer + AI Safety Lead)", + "Reviewer comments are first-class entities (id, refSpan, threadId, resolved?)" + ] + }, + { + "id": "M3-S3", + "title": "AI Co-Pilot Suggestions", + "content": { + "scopes": [ + "clarity rewrite", + "shorten/lengthen", + "add chain-of-thought scaffolding", + "guardrail injection (system message)", + "few-shot synthesizer" + ], + "controls": [ + "co-pilot output passes the same lint pipeline as human edits", + "all co-pilot suggestions are tagged with model+version+temperature in audit" + ] + } + }, + { + "id": "M3-S4", + "title": "Conflict Resolution & Branching", + "content": [ + "Branches: main, draft/, review/; merge via 3-way diff with semantic Liquid awareness", + "Forced override only by Admin + reason of record; recorded as SEV-2 audit event" + ] + } + ] + }, + { + "id": "M4", + "title": "M4 \u2014 Prompt Version Control, History & Testing", + "summary": "Immutable, hash-chained prompt versions; semantic version graph; A/B and regression test harness; replay & golden-set fixtures.", + "covers": [ + "version control", + "history", + "A/B test", + "replay", + "golden set" + ], + "sections": [ + { + "id": "M4-S1", + "title": "Version Graph", + "content": { + "model": "DAG of versions with parentId; semantic tags vMAJOR.MINOR.PATCH; immutable after publish", + "hashChain": "sha256(prevHash || canonical(body+vars+config)); root anchored daily to public chain via Merkle proof (LEC/ICGC)" + } + }, + { + "id": "M4-S2", + "title": "History Browser", + "content": [ + "Time-travel: view any historic version with inline diff to current", + "Blame: per-line author + commit (Yjs aware) using stable Liquid tokenization", + "Restore: creates a new patch version (no rewrite); requires reviewer approval" + ] + }, + { + "id": "M4-S3", + "title": "Test Harness", + "content": { + "fixtures": "Golden-set inputs + expected outputs (or regex/JSON-Schema matchers); stored per template", + "metrics": [ + "exact-match", + "BLEU/ROUGE for free-text", + "JSON-schema validity", + "tool-call coverage", + "latency p95", + "cost/run", + "PII leakage rate", + "blocked-harm rate" + ], + "modes": [ + "unit (single fixture)", + "regression (full set)", + "A/B (compare two versions on identical batch)" + ], + "ci": "GitHub Actions / GitLab CI gate: regression must not regress >0.5% on any metric or PR is blocked" + } + }, + { + "id": "M4-S4", + "title": "Deterministic Replay", + "content": [ + "Every run captures: prompt version, variables, model version, temperature, seed, tool versions, system fingerprint", + "Replay endpoint reconstructs the exact run from the Decision Envelope; guaranteed bit-for-bit on deterministic providers" + ] + } + ] + }, + { + "id": "M5", + "title": "M5 \u2014 AI Personas & Workflow Recommendation Engine", + "summary": "Persona-aware prompt selection, an AI workflow recommendation engine that proposes prompt chains, and accessible onboarding.", + "covers": [ + "personas", + "recommendations", + "onboarding", + "accessibility" + ], + "sections": [ + { + "id": "M5-S1", + "title": "Persona Model", + "content": { + "schema": [ + "id", + "name", + "role", + "skillProfile[]", + "preferredTone", + "redactionLevel", + "defaultModelTier", + "guardrailsBundle" + ], + "binding": "Personas link to RBAC role and to default prompt library scope" + } + }, + { + "id": "M5-S2", + "title": "Workflow Recommendation Engine", + "content": { + "approach": "Hybrid: (1) collaborative filtering over historical run graph; (2) embedding similarity over goal+context; (3) LLM planner that composes a chain from approved templates only", + "outputs": "Ranked workflow proposals = ordered list of {templateId, version, variableBindings, estCost, estLatency, riskScore}", + "guardrails": "Planner cannot reference unapproved/deprecated templates; risky chains require human approval gate" + } + }, + { + "id": "M5-S3", + "title": "Onboarding Flow", + "content": [ + "Progressive disclosure: 5-step wizard (role \u2192 goals \u2192 data sources \u2192 tone \u2192 safety preferences)", + "Live demo prompt with synthetic data only; no production data in onboarding", + "Skip & resume; saves to per-user profile; emits audit 'onboarding.completed' event" + ] + }, + { + "id": "M5-S4", + "title": "Accessibility (WCAG 2.2 AA)", + "content": { + "requirements": [ + "all interactive elements keyboard reachable", + "focus-visible style", + "color contrast \u2265 4.5:1 (text)", + "ARIA live regions for run status", + "screen-reader labels for variable chips and inline diffs", + "captions/transcripts for any media", + "reduced-motion respected", + "form errors announced via aria-live" + ], + "testing": "axe-core in CI on every PR; manual NVDA + VoiceOver smoke tests each release" + } + } + ] + }, + { + "id": "M6", + "title": "M6 \u2014 Model Registry Integration & Lifecycle", + "summary": "Pluggable model registry binding with version pinning, capability negotiation, evaluation gates, and shadow deploy for prompt-template compatibility.", + "covers": [ + "model registry", + "capabilities", + "evaluation", + "shadow" + ], + "sections": [ + { + "id": "M6-S1", + "title": "Registry Binding", + "content": { + "supported": [ + "MLflow Model Registry", + "Vertex AI Model Registry", + "SageMaker Model Registry", + "Azure ML Registry", + "in-house Sentinel Registry (WP-040 M3)" + ], + "binding": "ModelRef = { provider, registryId, modelName, versionPin, capabilities, hash }; persisted with prompt run" + } + }, + { + "id": "M6-S2", + "title": "Capability Negotiation", + "content": [ + "Templates declare required capabilities (tools, JSON-mode, vision, max_ctx)", + "Resolver picks the cheapest model that satisfies caps + safetyTier; cached per tenant", + "Mismatch produces a deterministic error before billing/usage" + ] + }, + { + "id": "M6-S3", + "title": "Evaluation Gates (pre-promotion)", + "content": [ + "Bias eval suite (Stereoset / BBQ-style for relevant domains)", + "Toxicity (Perspective-style) + jailbreak resistance (DAN/PAIR battery)", + "Hallucination/faithfulness on golden RAG set \u2265 0.92", + "Cost/latency budget envelope", + "Sign-off: ML steward + AI Safety Lead (multisig)" + ] + }, + { + "id": "M6-S4", + "title": "Shadow & Canary", + "content": { + "shadow": "All approved prompts routed to candidate model in parallel; outputs compared, never returned to user", + "canary": "1% \u2192 10% \u2192 50% with auto-rollback on KPI breach (faithfulness, drift, cost)" + } + } + ] + }, + { + "id": "M7", + "title": "M7 \u2014 RBAC for Model Operations & Prompt Lifecycle", + "summary": "Fine-grained role-based access control with policy-as-code, just-in-time elevation, and segregation of duties for prompt and model operations.", + "covers": [ + "RBAC", + "ABAC", + "OPA", + "JIT", + "SoD" + ], + "sections": [ + { + "id": "M7-S1", + "title": "Role Catalogue", + "content": [ + "viewer (read prompts, read reports)", + "engineer (CRUD draft prompts, run tests)", + "reviewer (approve/reject, comment)", + "publisher (publish approved versions)", + "model_steward (manage model registry bindings, deploy)", + "secrets_admin (rotate API keys, manage KMS aliases)", + "tenant_admin (manage users, roles, tenant config)", + "auditor (read-only WORM audit, export evidence)", + "ai_safety_lead (kill-switch, incident command)" + ] + }, + { + "id": "M7-S2", + "title": "Policy-as-Code (OPA/Rego sketch)", + "content": { + "snippet": "package promptmgmt.rbac\n\ndefault allow = false\n\nallow {\n input.action == \"prompt.publish\"\n input.user.role == \"publisher\"\n input.resource.status == \"approved\"\n count(input.resource.approvers) >= 2\n}\n\nallow {\n input.action == \"key.rotate\"\n input.user.role == \"secrets_admin\"\n time.now_ns() - input.user.last_mfa_ns < 300_000_000_000\n}" + } + }, + { + "id": "M7-S3", + "title": "Segregation of Duties", + "content": [ + "Author cannot self-approve, self-publish", + "Secrets admin cannot read prompt outputs (no run/report scope)", + "Auditor cannot edit, only export", + "Kill-switch requires AI Safety Lead + 1 of {CISO, CRO}" + ] + }, + { + "id": "M7-S4", + "title": "Just-In-Time Elevation", + "content": { + "flow": "Engineer requests temp publish role \u2192 reason of record + ticket id \u2192 Approver grants for \u2264 30 min \u2192 all actions logged with elevatedSession=true", + "controls": "Hard cap of 4 elevations / user / 24h; auto-revoke on idle 5 min" + } + } + ] + }, + { + "id": "M8", + "title": "M8 \u2014 Secure API Key Management & Secret Broker", + "summary": "KMS-backed secret broker with FIPS 140-3 protection, per-tenant CMKs, short-lived tokens, leak detection, and zero-touch rotation.", + "covers": [ + "KMS", + "secrets", + "rotation", + "leak detection" + ], + "sections": [ + { + "id": "M8-S1", + "title": "Architecture", + "content": { + "components": [ + "KMS (Cloud KMS / AWS KMS / Vault Transit) FIPS 140-3 L2/L3", + "Secret broker service (issues short-lived tokens to Model Gateway)", + "Tenant CMK with envelope encryption", + "Hardware-backed root of trust" + ], + "neverInPrompt": "API keys never appear in prompt body or variables; only secret-ref placeholders resolved server-side at run time" + } + }, + { + "id": "M8-S2", + "title": "Lifecycle", + "content": [ + "Provision: secrets_admin creates alias + maps to provider credential; written via KMS Encrypt only", + "Use: Model Gateway requests a 5-min token bound to (tenantId, modelRef, runId); rate-limited", + "Rotate: automated 90-day rotation; dual-write window of 24h; old version revoked & WORM-logged", + "Revoke: instant invalidation; downstream caches purged \u2264 60s" + ] + }, + { + "id": "M8-S3", + "title": "Leak Detection", + "content": { + "egress": "DLP scan on all outbound responses for known key prefixes (sk-, AIza, akia)", + "git": "Pre-commit + server-side hooks scan for secrets", + "telemetry": "Counter on secret broker per (alias, source IP); anomaly = SEV-1" + } + }, + { + "id": "M8-S4", + "title": "Threat Model (STRIDE)", + "content": [ + "Spoofing: mTLS + workload identity (SPIFFE) for broker callers", + "Tampering: signed tokens + replay nonce", + "Repudiation: every issuance hash-chained to WORM", + "Info disclosure: keys never logged; redaction filter at Pino layer", + "DoS: token bucket per alias; circuit breaker", + "Elevation: deny path if MFA age > 5 min for sensitive ops" + ] + } + ] + }, + { + "id": "M9", + "title": "M9 \u2014 Enhanced Audit Logging (WORM, Hash-Chained, Tamper-Evident)", + "summary": "Immutable Decision Envelope per run/edit, append-only Kafka topics with ACLs, daily Merkle anchoring, and regulator-grade evidence packs.", + "covers": [ + "WORM", + "hash chain", + "Merkle", + "evidence pack" + ], + "sections": [ + { + "id": "M9-S1", + "title": "Decision Envelope (per event)", + "content": { + "fields": [ + "envelopeId", + "tenantId", + "actor (userId/svcId)", + "action", + "resourceRef", + "promptVersion", + "modelRef", + "inputHash", + "outputHash", + "policyDecisions[]", + "fairness?", + "explanations?", + "redactionsApplied", + "prevHash", + "thisHash", + "signatures[]", + "ts" + ], + "signing": "Ed25519 (hot) + ML-DSA-65 (post-quantum cold sign in batch)" + } + }, + { + "id": "M9-S2", + "title": "Storage", + "content": [ + "Kafka WORM topic per tenant; broker ACL: producer=app-gw, consumer=auditor (read-only), no delete/compact", + "S3/GCS WORM bucket lock for cold tier; lifecycle to Glacier after 90d; retention \u2265 7 years", + "Daily Merkle root anchored to Sentinel ICGC ledger and (optionally) public chain" + ] + }, + { + "id": "M9-S3", + "title": "Querying & Evidence Packs", + "content": [ + "Auditor UI builds an evidence pack: filtered events + Merkle inclusion proofs + signed manifest", + "Pack format: ZIP with .jsonl + manifest.sig + chain.proof + README.md mapping events \u2192 regulatory clauses", + "Reproducibility: any run can be replayed from envelope alone (M4-S4)" + ] + }, + { + "id": "M9-S4", + "title": "Privacy in Audit", + "content": [ + "PII never raw in audit; pseudonyms via per-tenant HMAC + KMS-held salt", + "Right-to-erasure: hash-only retention; lookup table erased on DSAR; WORM stays intact (privacy-by-design GDPR Art 25)" + ] + } + ] + }, + { + "id": "M10", + "title": "M10 \u2014 Distributed Tracing for Agent Swarms (OpenTelemetry GenAI)", + "summary": "Semantic-conventions-compliant tracing for multi-agent / tool-use workflows, with span hierarchy, baggage, and cost/latency analytics.", + "covers": [ + "OpenTelemetry", + "GenAI conventions", + "agent swarm", + "trace mining" + ], + "sections": [ + { + "id": "M10-S1", + "title": "Span Model", + "content": { + "rootSpan": "workflow.run (attrs: workflow.id, version, tenantId, runId)", + "childSpans": [ + "agent.invoke (gen_ai.system, gen_ai.request.model, gen_ai.usage.*)", + "tool.call (tool.name, args.hash)", + "rag.retrieve (vector.k, score.min)", + "policy.evaluate (opa.bundle, decision)", + "model.gateway.call (provider, attempt)" + ], + "attributesAlwaysOn": [ + "gen_ai.system", + "gen_ai.request.model", + "gen_ai.usage.prompt_tokens", + "gen_ai.usage.completion_tokens", + "gen_ai.response.id", + "tenant.id", + "persona.id" + ] + } + }, + { + "id": "M10-S2", + "title": "Baggage & Correlation", + "content": [ + "Inject baggage: runId, tenantId, persona, safetyTier, traceId (W3C)", + "Correlate logs \u2194 traces \u2194 metrics \u2194 audit envelope via runId/envelopeId" + ] + }, + { + "id": "M10-S3", + "title": "Backends", + "content": [ + "OTLP \u2192 Tempo/Jaeger for traces; Loki for logs; Prometheus/Mimir for metrics", + "Sampling: tail-based with bias toward errors, high cost, policy denials, drift alerts" + ] + }, + { + "id": "M10-S4", + "title": "Trace Mining for Governance", + "content": [ + "Detect runaway loops (depth > N, repeated tool.call signatures)", + "Detect prompt-injection success (policy.deny \u2192 still completed)", + "Cost & latency outliers per persona / per template", + "Auto-link incident \u2192 top-K traces in evidence pack" + ] + } + ] + }, + { + "id": "M11", + "title": "M11 \u2014 Reporting: Markdown\u2192HTML (Tailwind), Code Highlighting & PDF Export", + "summary": "Safe Markdown rendering with sanitization, Tailwind typography, syntax highlighting, and reproducible PDF export with embedded provenance.", + "covers": [ + "Markdown", + "Tailwind", + "highlighting", + "PDF", + "provenance" + ], + "sections": [ + { + "id": "M11-S1", + "title": "Markdown Pipeline (server)", + "content": [ + "Parser: marked / markdown-it with safe defaults (no raw HTML unless allowlisted)", + "Sanitization: DOMPurify (jsdom) with whitelist; strip