index.md

HTML wrapper for HTML-only fetchers; content is shown verbatim.

Raw file

Links (extracted)

Clickable list for reviewers; avoids copy/paste line-wrap issues.
# InfraFabric dossier addendum (v5 single-file pack)

Generated (UTC): 2026-01-11

Status: ADDENDUM (single-file pack with embedded artifacts)

Black/white boundary: published receipts (when present) can prove the bytes you downloaded match a public hash. They do not prove factual correctness, safety, compliance, or intent.

## Source dossier

- filename: `DANNY_STOCKER_INFRAFABRIC_DOSSIER_20251223-1925CET.md`
- submitted_utc: 2025-12-23
- local_sha256: d7832c254ae95da2ec1e2026a3bff8748596b3cc3983673fd027f6e437b13f46

## Registry excerpt

This pack embeds a registry excerpt so the reader doesn’t need to fetch it.

Canonical public mirror (if network is available):

https://infrafabric.io/llm/if.registry.json

Embedded excerpt (selected products/modules only):

```json
[
  {
    "brand": "IF.api (integrations)",
    "bundle_slug": "if-api-demo-bundle",
    "description": "Integration inventory + adapters for external APIs. Not shipped as a runnable module on the current host.",
    "kind": "product",
    "path": "/if/api",
    "product_id": "if.api",
    "slug": "if-api",
    "status": "roadmap"
  },
  {
    "brand": "IF.bus",
    "bundle_slug": "if-bus-demo-bundle",
    "description": "Integration bus concept (message normalization + routing). Not shipped on the current host.",
    "kind": "product",
    "path": "/if/bus",
    "product_id": "if.bus",
    "slug": "if-bus",
    "status": "roadmap"
  },
  {
    "brand": "IF.emotion",
    "bundle_slug": "if-emotion-demo-bundle",
    "description": "Wellbeing-aware interaction layer (non-clinical) and governance-seat outputs with explicit safety boundaries; not diagnosis/therapy; not compliance guarantees.",
    "kind": "product",
    "path": "/if/emotion",
    "product_id": "if.emotion",
    "slug": "if-emotion",
    "status": "preview",
    "uses_receipts_from": [
      "if.trace"
    ]
  },
  {
    "brand": "IF.GOV",
    "bundle_slug": "if-gov-demo-bundle",
    "description": "Governance packs (triage/decision/external challenge) bound to receipts; not compliance guarantees.",
    "kind": "product",
    "path": "/if/gov",
    "product_id": "if.gov",
    "slug": "if-gov",
    "status": "preview",
    "uses_receipts_from": [
      "if.trace"
    ]
  },
  {
    "brand": "if.intelligence",
    "bundle_slug": "if-intelligence-demo-bundle",
    "description": "Research orchestration module (roadmap only; no receipt-backed demo published yet).",
    "kind": "module",
    "path": "/if/intelligence",
    "product_id": "if.intelligence",
    "slug": "if-intelligence",
    "status": "roadmap",
    "uses_receipts_from": [
      "if.trace"
    ]
  },
  {
    "brand": "if.kb",
    "bundle_slug": "if-kb-demo-bundle",
    "description": "Build-time developer knowledge base (KB) artifacts generated via `if.knowledge` (static Markdown/HTML; no runtime fetches). Preview: a bus/api KB snapshot is published; no deployed KB service on this host.",
    "kind": "module",
    "path": "/if/kb",
    "product_id": "if.kb",
    "slug": "if-kb",
    "status": "preview",
    "uses_receipts_from": [
      "if.trace"
    ]
  },
  {
    "brand": "if.knowledge",
    "bundle_slug": "if-knowledge-demo-bundle",
    "description": "Build-time documentation pipeline (registry-driven; static Markdown/HTML; no runtime fetches). Roadmap: no public demo artifacts published yet; no deployed service on this host.",
    "kind": "module",
    "path": "/if/knowledge",
    "product_id": "if.knowledge",
    "slug": "if-knowledge",
    "status": "roadmap",
    "uses_receipts_from": [
      "if.trace"
    ]
  },
  {
    "brand": "if.search",
    "bundle_slug": "if-search-demo-bundle",
    "description": "Multi-pass investigation/search workflow module (roadmap only; no receipt-backed demo published yet).",
    "kind": "module",
    "path": "/if/search",
    "product_id": "if.search",
    "slug": "if-search",
    "status": "roadmap",
    "uses_receipts_from": [
      "if.trace"
    ]
  },
  {
    "brand": "if.security",
    "bundle_slug": "if-security-demo-bundle",
    "description": "Cross-cutting security posture for InfraFabric modules (signals + evidence-typed actuation + containment mapping). Roadmap only; no deployed security runtime on this host.",
    "kind": "module",
    "path": "/if/security",
    "product_id": "if.security",
    "slug": "if-security",
    "status": "roadmap",
    "uses_receipts_from": [
      "if.trace"
    ]
  },
  {
    "brand": "if.yologuard",
    "bundle_slug": "if-security-secrets-detect-demo-bundle",
    "description": "Receipt-backed secrets detection (audit mode, redacted outputs). Preview demo exists; not CI-integrated or 'live'.",
    "kind": "module",
    "path": "/if/security/secrets/detect",
    "product_id": "if.security.secrets.detect",
    "repo_dir": "src/armour/secrets",
    "slug": "if-security-secrets-detect",
    "status": "preview",
    "uses_receipts_from": [
      "if.trace"
    ],
    "vendored_engine_dir": "armour/yologuard"
  },
  {
    "brand": "ShadowRT",
    "bundle_slug": "if-shadowrt-demo-bundle",
    "description": "Publishing/review UI that makes if.trace legible via dossiers/packs and routes reviewers to receipts.",
    "kind": "surface",
    "path": "/review/shadowrt",
    "product_id": "if.shadowrt",
    "slug": "if-shadowrt",
    "status": "shipped",
    "uses_receipts_from": [
      "if.trace"
    ]
  },
  {
    "brand": "if.story",
    "bundle_slug": "if-story-demo-bundle",
    "description": "Narrative logging protocol module (vector vs bitmap). Roadmap only; no receipt-backed demo published yet.",
    "kind": "module",
    "path": "/if/story",
    "product_id": "if.story",
    "slug": "if-story",
    "status": "roadmap",
    "uses_receipts_from": [
      "if.trace"
    ]
  },
  {
    "brand": "if.swarm",
    "bundle_slug": "if-swarm-demo-bundle",
    "description": "Multi-agent/swarm execution module (roadmap only; no receipt-backed demo published yet).",
    "kind": "module",
    "path": "/if/swarm",
    "product_id": "if.swarm",
    "slug": "if-swarm",
    "status": "roadmap",
    "uses_receipts_from": [
      "if.trace"
    ]
  },
  {
    "brand": "if.trace",
    "bundle_slug": "if-trace-demo-bundle",
    "description": "Public receipt surface (hashes; signatures only when present and verifiable). Proof of bytes/integrity, not correctness.",
    "kind": "product",
    "path": "/if/trace",
    "product_id": "if.trace",
    "slug": "if-trace",
    "status": "shipped"
  },
  {
    "brand": "iftypeset",
    "bundle_slug": "if-typeset-demo-bundle",
    "description": "Deterministic document CI (lint \u2192 render HTML/PDF \u2192 QA) for review-proof packs.",
    "kind": "product",
    "path": "/if/typeset",
    "product_id": "if.typeset",
    "repo_dir": "ai-workspace/iftypeset",
    "slug": "if-typeset",
    "status": "preview"
  }
]
```

## Task board excerpt (if.knowledge chain)

Canonical public snapshot (if network is available):

https://infrafabric.io/llm/task-board.html

This addendum pack is built in the same posture as `if.knowledge`: deterministic generation and strict black/white wording.

Key chain items:

- IF-322: deterministic addendum generator + linter (stdlib-only)
- IF-330: gov-first one-page system map (reviewer navigation)
- IF-331: `if.gov` portfolio-based council structure (design target)
- IF-333: addendum v2 (adds `if.gov` dev + cost posture)
- IF-334: addendum v3 (adds deeper “why security” + “why bus safe path” explanation)
- IF-335: addendum v4 (adds diagrams + deeper platform-agnostic narrative)

## Evidence (verified facts only)

This v5 pack embeds the underlying Markdown artifacts (as text) so reviewers can read without following links.

If links are available, the live HTML wrappers for these artifacts are discoverable via:

https://infrafabric.io/llm/

## Interpretation (clearly labeled)

This section is intentionally “interpretation”: it explains the design logic and how the pieces fit together. It is not presented as proof.

### A) What InfraFabric is trying to do (in one paragraph)

InfraFabric is an attempt to turn raw research on “Constitutional AI for the subjects” into composable products where:
- governance is reproducible without needing the same black-box model later,
- infrastructure choice is a detail (platform-agnostic),
- and the long-run operating cost trends toward deterministic, low-token, auditable workflows.

### B) Synthetic debate (compressed)

- Governance reviewer: lead with `if.gov` as the decision contract; show how decision packs can be replayed without a model.
- Security engineer: explain security as actuation control + containment (prevent silent failure), not compliance theater.
- Integration architect: show why a stable envelope + transport abstraction avoids lock-in and absorbs infrastructure churn.
- Skeptical operator: insist on black/white boundaries and failure modes that degrade safely (pause/quarantine/replay).
- Technical writer: include a 1-page map and diagrams so the reader doesn’t misread modularity as sprawl.

Outcome: the “gov-first” ordering is the best way to reduce sprawl perception while keeping the system legible to non-experts.

### C) The core thesis sentence

Security isn’t a tax; it’s a seatbelt—insurance against silent failure that reduces likelihood and blast radius, making incidents auditable.

### D) What it means for `if.bus` to make the safe path the easy path

The intent is not to make compliance “virtuous”, but to make it operationally cheaper than non-compliance:
- explicit schemas as the compatibility boundary,
- deterministic feedback (DLQ/acks/counters) instead of silent failure,
- budgets and backpressure as first-class constraints,
- and local dev ergonomics (in-memory transport) so the contract is easy to adopt.

## Open questions / next steps

- Publish a minimal `if.gov` “actuation gate” demo pack: show a rejection where only HYPOTHESIS evidence is available (design target from `if.security` posture).
- Publish a minimal “adapter safe path checklist” for `if.api` → `if.bus` (schema + idempotency + budgets + DLQ posture).
- Decide whether to keep diagrams Mermaid-only (current wrappers) or add a build-time SVG renderer (D2/Graphviz) for higher aesthetic control.

---


## Appendix A — InfraFabric system map (gov-first)

Embedded from: `/root/docs/93-infrafabric-system-map-onepage.md`

---

# InfraFabric system map (gov-first)

Last updated (UTC): 2026-01-11

Purpose: one-page navigation to reduce “module sprawl” perception. This page introduces the system in a deliberate order and links to deeper review packs.

Registry (source of truth):
https://infrafabric.io/llm/if.registry.json

Black/white reminder:
- Receipts prove byte integrity (hashes match), not factual correctness, safety, compliance, or intent.
- Status labels come from the registry: shipped / preview / roadmap.

---

## 1) `if.gov` (preview) — decision contract layer

What it is: governance-as-a-pack. A decision pack is the unit of record: structured inputs, explicit evidence links, deterministic checks where possible, preserved dissent, and receipt-bound integrity via `if.trace`.

LLM posture: LLMs (when used) are optional and untrusted (draft/summarize only). A decision should be checkable later without requiring the same model.

Evidence gating (design target): typed evidence (OBSERVED / DERIVED / HYPOTHESIS) is defined in `if.security` posture (roadmap) and is a design target for actuation gates (HYPOTHESIS must not trigger automation).

SKUs (roadmap; design targets until standalone demo packs exist):
- `if.gov.triage` — fast preflight and stop conditions (deliberation target: milliseconds)
- `if.gov.council` — bounded options + explicit vote artifact (deliberation target: milliseconds)
- `if.gov.council.extended` — adapts from ms → minutes when verification/research is required

Deep dives:
https://infrafabric.io/if/gov/
https://infrafabric.io/llm/products/if-gov/
https://infrafabric.io/static/hosted/review/if-gov-decision-pack-demo/2026-01-05/index.html
https://infrafabric.io/llm/products/if-gov/council-seats/2026-01-08/index.html
https://infrafabric.io/llm/products/if-gov/triage-council-extended-spec/2026-01-10/index.html

---

## 2) `if.trace` (shipped) — integrity receipts

What it is: no-login receipts that let third parties verify byte integrity later.

Deep dives:
https://infrafabric.io/if/trace/
https://infrafabric.io/llm/products/if-trace/
https://infrafabric.io/static/trace/6qRgcR01kw_qNo63Dbs_ob9n
https://infrafabric.io/static/hosted/iftrace.html

---

## 3) `if.security` (roadmap) — cross-cutting posture

What it is: a shared posture across modules (evidence typing, containment mapping, and a security signal primitive). This page is a posture explainer; it does not claim a deployed security runtime on this host.

Preview module:
- `if.security.secrets.detect` (preview) — secrets detection demo posture (brand: if.yologuard)

Deep dives:
https://infrafabric.io/if/security/
https://infrafabric.io/llm/products/if-security/
https://infrafabric.io/llm/products/if-security/security-posture/2026-01-11/index.html
https://infrafabric.io/if/security/secrets/detect/

---

## 4) `if.bus` (roadmap) — transport layer (event spine)

What it is: a transport-agnostic event spine with a single stable envelope as the compatibility boundary. It is designed “inside-out” (assume compromise), with budgets + security signals + structured DLQ + control-plane commands as first-class primitives.

Deep dives:
https://infrafabric.io/if/bus/
https://infrafabric.io/static/hosted/review/if-bus-whitepaper/2026-01-05/index.html
https://infrafabric.io/llm/products/if-bus/bus-runtime-spec/2026-01-11/index.html
https://infrafabric.io/llm/products/if-bus/whitepaper-source-pack/2026-01-11/index.html
https://infrafabric.io/llm/products/if-bus/runtime-sandbox/2026-01-10/index.html

---

## 5) `if.api` (roadmap) — integration layer (adapters)

What it is: adapter inventory + demos for external services. When outputs matter, the posture is deterministic transforms + receipt-bound integrity.

Deep dives:
https://infrafabric.io/if/api/
https://infrafabric.io/llm/products/if-api/
https://infrafabric.io/static/hosted/review/if-api-integrations-inventory/2026-01-05/index.html
https://infrafabric.io/static/hosted/review/if-api-github-webhook-demo/2026-01-05/index.html
https://infrafabric.io/static/hosted/review/if-bus-api-kb/2026-01-07/index.html

---

## Supporting modules

### `if.emotion` (preview) — wellbeing-aware interaction (non-clinical)
https://infrafabric.io/if/emotion/
https://infrafabric.io/llm/products/if-emotion/
Embedded update: see Appendix G (clinical prescreening support; public synthetic bundle; GitHub-style recurrence heatmaps).

### `if.typeset` (preview) — deterministic document CI
https://infrafabric.io/if/typeset/
https://infrafabric.io/llm/products/if-typeset/

### `if.kb` (preview) — build-time developer KB artifacts
https://infrafabric.io/if/kb/
https://infrafabric.io/llm/products/if-kb/

### `if.knowledge` (roadmap) — build-time documentation pipeline
https://infrafabric.io/if/knowledge/
https://infrafabric.io/llm/products/if-knowledge/

### `if.story` (roadmap) — narrative logging protocol (vector vs bitmap)
https://infrafabric.io/if/story/
https://infrafabric.io/llm/products/if-story/

### `if.search` / `if.intelligence` / `if.swarm` (roadmap) — capability demos
https://infrafabric.io/llm/products/if-search/
https://infrafabric.io/llm/products/if-intelligence/
https://infrafabric.io/llm/products/if-swarm/

### `if.shadowrt` (shipped surface) — review UI
https://infrafabric.io/review/shadowrt/


## Appendix B — if.security posture (cross-cutting)

Embedded from: `/root/docs/89-if-security-posture.md`

---

# if.security posture (design; not deployed)

Generated (UTC): 2026-01-11  
Scope: cross-cutting security posture for InfraFabric modules (signals + evidence-typed actuation + containment mapping). This is a posture doc meant for external review.

Reality gate (single-host): `docs/22-ifttt-handover-and-roadmap.md`  
Naming (enforced): `AGENTS.md` + `if.registry.json`

---

## Status (black/white)

Registry status (source of truth):
- `if.security` is `roadmap` in `if.registry.json` (no claim of a deployed security runtime).
- `if.security.secrets.detect` is `preview` in `if.registry.json` (receipt-backed demo exists; not CI-integrated or “live”).

This document is:
- a cross-cutting posture and a contract for **how modules describe security-relevant findings**
- a mapping between:
  - `if.bus` (event envelope + control plane)
  - `if.gov` (deliberation + decision packs)
  - `if.trace` (integrity receipts: bytes match hash)

This document is not:
- proof that any security product is deployed or prevents incidents
- a compliance guarantee
- a claim of correctness, safety, or intent verification

---

## Public context links (HTML-first)

Registry (public mirror):
https://infrafabric.io/grok/if.registry.json

Receipt verification explainer:
https://infrafabric.io/if/trace/

`if.bus` runtime spec (control plane + security signals):
https://infrafabric.io/grok/products/if-bus/bus-runtime-spec/2026-01-11/index.html

`if.gov` deliberation spec (triage/council/extended):
https://infrafabric.io/grok/products/if-gov/triage-council-extended-spec/2026-01-10/index.html

`if.gov` council seats (coded seats + posture):
https://infrafabric.io/grok/products/if-gov/council-seats/2026-01-08/index.html

`if.security.secrets.detect` demo receipt (integrity only):
https://infrafabric.io/static/trace/n6DSejaslZrB2ciVjLiBCg

---

## 1) Goal (one posture, many modules)

We do not want “security posture” re-authored per product.

We want:
- one cross-cutting posture doc (`if.security`) that defines the minimal shared primitives and black/white boundaries
- module-specific integration profiles (short sections) that reference this posture

This matches InfraFabric’s design preference:
- a small number of stable contracts
- composable modules
- verifiable artifacts when outputs matter

---

## 2) Core shared primitive: `if.bus.security_signal`

The ecosystem-wide “atomic unit” of security telemetry is a **security signal**.

Source schema (repo):
- `schemas/if-bus/security_signal.schema.json`

Black/white constraints:
- Signals are **public-safe** (redacted; no secrets).
- Signals can be emitted by any detector observing bus traffic, adapter inputs/outputs, or published artifacts.
- Signals are evidence for monitoring and triage; they do not, by themselves, prove root cause or intent.

Key fields (from schema):
- `detector.detector_id` (example: `secrets.detect`)
- `severity` (`low|medium|high|critical`)
- `finding_type` (short token)
- `summary` (public-safe)
- optional `recommended_action` (example: `quarantine`)
- optional `redactions.redacted_excerpt` (must not contain the secret)
- optional `related_event_id` (data-plane linkage)
- `extensions` (namespaced, for additional context)

---

## 3) Evidence posture (grounding + actuation rules)

### 3.1 Evidence kinds (convention; not enforced by schema)

`if.security` uses a three-tier evidence posture to reduce “vibes”:

- **OBSERVED**: direct detector observation of bytes (example: a token-like pattern match).
- **DERIVED**: computed from observed artifacts (example: “high leak probability” from multiple observed hits).
- **HYPOTHESIS**: inference that requires human review or additional evidence.

Suggested encoding (convention):
- Put `evidence_kind` in `extensions.if_security.evidence_kind` with one of:
  - `observed`
  - `derived`
  - `hypothesis`

Black/white: this convention is a posture target. The schema permits arbitrary `extensions`, but nothing forces emitters to use these keys yet.

### 3.2 Automation allowed rule (fail-closed)

Automation is allowed only for:
- OBSERVED
- DERIVED

Automation is not allowed for:
- HYPOTHESIS

“Automation” means any action with side effects (pausing topics, quarantining workflows, blocking ingress, etc.).

---

## 4) Containment mapping (how to act without over-claiming)

`if.security` defines a containment mapping that reuses existing contracts instead of inventing a new runtime:

### 4.1 Containment states (posture)

- **WATCH**: record signals; no actuation.
- **CONTAIN**: isolate a topic/workflow; block propagation; preserve evidence for review.
- **HALT**: stop processing that scope; require explicit human decision to resume.

### 4.2 Mapping to `if.bus` control plane (design target)

`if.bus` already defines async control commands (see the runtime spec):
- `quarantine` / `unquarantine` (scope: topic)
- `pause` / `resume` (scope: topic; modes include `hold` and `drain`)
- structured DLQ events (`if.bus.dead_letter_event`) for failures and policy violations

Suggested mapping:
- WATCH → emit `if.bus.security_signal` only
- CONTAIN → issue `control_command`:
  - `quarantine` OR `pause(mode=hold)` depending on the blast radius
- HALT → issue `control_command`:
  - `pause(mode=drain)` + `quarantine` (fail-closed), then require explicit resume

Black/white: this is a mapping between contracts, not a claim that an automated containment system is deployed.

### 4.3 When to escalate to `if.gov`

Escalate to `if.gov` (triage or council) when:
- actions have external impact (customers, third parties)
- actions involve ambiguous evidence or high false-positive risk
- actions require policy interpretation (not a simple containment move)

Black/white: `if.gov` packs can be receipt-bound (integrity only); they still do not prove truth or compliance.

---

## 5) Integration profiles (minimal)

### 5.1 `if.security.secrets.detect` (preview demo)

Role:
- emit `if.bus.security_signal` when secret-like material is detected
- keep outputs redacted and public-safe

What can be verified today (black/white):
- a demo receipt exists (integrity receipt): the output bytes match the receipt hash

https://infrafabric.io/static/trace/n6DSejaslZrB2ciVjLiBCg

What is not claimed:
- that the detector is complete or tuned for production
- that it prevents leaks (it’s a detector, not a guardrail)

### 5.2 `if.bus` (roadmap runtime)

Role:
- carry `security_signal` as a first-class schema
- provide the control-plane primitives needed for containment (pause/quarantine/replay)

### 5.3 `if.api` (adapter layer; roadmap)

Role (posture target):
- deterministic transforms where possible
- emit `security_signal` on PII/secret detections and schema violations
- use receipts when adapter outputs matter (integrity only)

### 5.4 Other modules (roadmap profiles)

Roadmap modules can reference the same posture without new names:
- `if.search` / `if.intelligence` / `if.swarm`
- `if.emotion`
- `if.story`

For LLM-based modules, the posture target is:
- no secrets in prompts by default
- no shared conversation state across unrelated jobs (orchestrator-side)
- outputs treated as untrusted until bounded by deterministic checks and/or receipts

Black/white: this is a design constraint; it does not claim anything about model training data or “no external knowledge”.

---

## 6) External review questions

1) Is `if.bus.security_signal` sufficient as the cross-cutting “atomic unit”, or do we need a second schema for security actions?
2) Is the evidence posture (OBSERVED/DERIVED/HYPOTHESIS) the right minimum to prevent “vibes” automation?
3) Is the containment mapping too conservative for single-host reality, or not conservative enough?
4) What would you require before allowing automated CONTAIN/HALT actions on the bus control plane?


## Appendix C — if.bus runtime spec (source)

Embedded from: `/root/docs/85-if-bus-runtime-spec.md`

---

# if.bus runtime spec (design; not deployed)

Generated (UTC): 2026-01-10  
Scope: a forward-looking runtime spec for `if.bus` (event spine + control plane) intended to survive 5 years of growth **without breaking the core envelope**.

Reality gate (single-host): `docs/22-ifttt-handover-and-roadmap.md`  
Naming (enforced): `AGENTS.md` + `if.registry.json`

---

## Status (black/white)

Registry status (source of truth):
- `if.bus` is `roadmap` in `if.registry.json` (no claim of a deployed bus runtime).
- `if.api` is `roadmap` in `if.registry.json` (no claim of a deployed adapter runtime).

This document is:
- a design spec and a contract proposal
- meant for external critique and iteration

This document is not:
- proof that the runtime exists
- a claim of production readiness

---

## Public context links (HTML-first)

Registry (public mirror):
https://infrafabric.io/grok/if.registry.json

`if.bus` whitepaper extract (public-safe):
https://infrafabric.io/static/hosted/review/if-bus-whitepaper/2026-01-05/index.html

`if.bus` + `if.api` developer KB (build-time, static):
https://infrafabric.io/static/hosted/review/if-bus-api-kb/2026-01-07/index.html

`if.api` integrations inventory (snapshot):
https://infrafabric.io/static/hosted/review/if-api-integrations-inventory/2026-01-05/index.html

`if.trace` verification explainer:
https://infrafabric.io/if/trace/

---

## 1) Problem statement (what the bus must solve)

We need an integration backbone that:
- normalizes inbound events from many systems into one envelope
- routes events predictably (topics + filters + fan-out)
- supports **bidirectional** integrations (webhooks in, actions out)
- makes outputs easier to verify later (via `if.trace` receipts, integrity only)

The core failure mode to avoid (5-year horizon):
- “adapter sprawl” where each integration invents its own payloads, retries, and audit story

---

## 2) Design principles (future-backwards)

These are “future-backwards” constraints: if we violate them now, we will be forced into a breaking redesign later.

### 2.1 One stable envelope (versioned, extensible)

- A single **event envelope** contract is the compatibility boundary.
- New capabilities must arrive via:
  - additive fields
  - `extensions` map (namespaced keys)
  - new `schema_version` (without breaking v1 consumers)

### 2.2 Split data-plane and control-plane

- The bus carries two distinct kinds of messages:
  - **data-plane events** (domain events and delivery events)
  - **control-plane commands** (pause, replay, quarantine, budget changes)
- Control is asynchronous: commands are acknowledged and tracked like events.

### 2.3 Determinism where it matters

- If a transformation is used to justify a decision, publish deterministic artifacts and bind them to `if.trace`.
- Receipts prove byte integrity (hash match), not correctness or compliance.
- If a post-quantum signature receipt exists for a trace, label it **QUANTUM READY** (not a claim of quantum security).

### 2.4 Security and budgets are first-class fields, not afterthoughts

- Security monitoring must be able to observe:
  - the envelope
  - payload hashes
  - where secrets/PII were detected (redacted)
- Pre-emptive budget monitoring must exist before we have “expensive” adapters:
  - cost estimates before executing an action
  - hard and soft limits per workflow/tenant/adapter
  - a standard signal when budgets are near exhaustion

---

## 3) Runtime components (conceptual)

Black/white: these are design targets, not deployment claims.

### 3.0 Transport abstraction (runtime-internal; not the protocol)

The protocol boundary is the **envelope + topics + control semantics**. The underlying transport is an implementation choice.

The runtime MUST be implemented behind a transport abstraction with backend-agnostic primitives:

- `publish(topic, envelope, options)`
- `subscribe(topic, consumer_group, handler, options)`
- `ack(message_id)` / `nack(message_id, retry_delay_seconds)`
- `fetch(stream_id, offset, limit)` (for replay/debug)
- `replay(topic, from_offset, to_offset, filter)` (control-plane driven)

Black/white: different transports provide different guarantees. The abstraction does not “upgrade” a backend to provide guarantees it does not have (e.g. exactly-once).

Optional flow-control posture (backend-agnostic):
- `subscribe(..., options)` SHOULD support a bounded in-flight setting (e.g., `max_inflight`) so runtimes can apply backpressure before queues explode.
- Coarse flow control is also first-class via control-plane commands (`pause` / `resume`) and quotas (see `schemas/if-bus/runtime_config.schema.json`).

#### Dev-mode transport (`in_memory`)

The runtime MUST ship an `in_memory` transport for local development and CI:

- runs fully in-process (no Docker required)
- simulates durable subscriptions + ack/nack + bounded retries
- supports deterministic replay for tests (bounded retention in memory)

#### Reference backend (design target only)

For v1, the reference backend for the *reference implementation* SHOULD be NATS JetStream because it provides a practical baseline for:

- low latency publish/subscribe
- durable consumer groups
- operational simplicity (single binary)

This is a design/implementation default, not a protocol requirement and not a claim of a deployed public runtime.

#### Transport evaluation checklist (backend-agnostic)

This is the neutral checklist to evaluate any transport backend without lock-in:

1) **Durable consumer groups** (or equivalent) with explicit delivery state.
2) **Ack/Nack** semantics with retry delay support (or a deterministic fallback).
3) **Replay / fetch** by offset/sequence for audit and recovery.
4) **Structured DLQ** support (failed events become processable `if.bus.dead_letter_event` envelopes, not log lines).
5) **Explicit retention controls** (age/bytes/messages) with black/white behavior when exceeded.
6) **Multi-tenancy isolation** (accounts/ACLs) scoped by `{tenant_id, topic prefix}` at minimum.
7) **Observability hooks** for backlog/lag and end-to-end correlation (best-effort trace context propagation).
8) **Flow control / backpressure** primitives (bounded in-flight, pause/resume, quotas).
9) **Security posture** (TLS-in-transit, authn, auditable admin operations).
10) **Operational simplicity** for the intended deployment model (single-host reality gate first; scale later).

#### Transport candidate notes (design guidance; not protocol)

- **NATS JetStream** (reference backend for v1 skeleton): strong fit for low-latency bidirectional traffic + durable consumers + simple ops. Can also support async replication via stream mirroring (design target).
- **Kafka** (secondary): mature ecosystem and tooling; heavier ops footprint; strong for long retention and replay when you need it.
- **Pulsar** (future candidate): native multi-tenancy + tiered storage are attractive, but adoption cost is higher; evaluate when cold storage becomes a requirement.
- **Redis/Valkey Streams** (not the spine): useful as a sidecar cache, short-lived buffer, or prototyping backend. Not recommended as the core event log when you need durable retention + multi-tenancy + replay/DLQ without significant custom scaffolding.

### 3.1 Event plane

- **Ingress**: adapters ingest external events (webhooks, polling, batch imports).
- **Validator**: validates envelope schema + size constraints.
- **Router**: selects destinations based on topics, filters, and rules.
- **Executors**: consumers that produce outputs (deliveries, packs, reports, triggers).
- **Receipter** (optional): binds selected outputs to `if.trace` receipts (integrity only).

### 3.2 Control plane (async control)

- **Command intake**: operators / automation submit control commands.
- **Command tracker**: commands have status and final ack objects.
- **Runtime actuators**: enforce:
  - pause/resume
  - retry/replay
  - quarantine/hold
  - budget throttles
  - emergency stop / circuit breaker

### 3.3 Observability plane (real-time ops)

- **State stream**: health and backlog metrics by topic/consumer group.
- **Event audit**: stable correlation IDs between:
  - ingress payload hash
  - envelope event ID
  - any derived artifacts
  - any receipt shareIds (when published)

---

## 4) Contracts (schemas)

All schemas are JSON Schema draft 2020-12 and include `x_if` metadata.

### 4.1 Data-plane envelope

Schema path:
- `schemas/if-bus/envelope.schema.json`

High-level requirements:
- stable `event_id` + `emitted_utc`
- explicit `producer` and `event` identity
- routing metadata (topic + partition key)
- payload hash (`payload_sha256`) for audit without leaking payload
- optional `payload_ref` pointer for large/redacted payloads (static metadata; no runtime fetch requirement)
- optional `budget` object (pre-emptive guardrails)
- optional `security` pointers (signals are separate events)
- `extensions` for future growth without breaking v1

#### Large payloads + redaction posture (`payload_ref`)

When a payload is too large to inline (or must be redacted), the publisher MAY omit or redact `payload` and instead include `payload_ref`.

Black/white requirements:
- `payload_sha256` is authoritative for audit; it MUST be present.
- If `payload_ref` is present, `payload_ref.sha256` MUST match `payload_sha256`.
- `payload_ref` is static metadata. No runtime component is required to fetch `payload_ref.source_url`.

Optional fields in `payload_ref`:
- `source_url` MAY be a public URL for the stored bytes (no auth implied).
- `content_encoding` MAY declare how the stored bytes are encoded (`identity|gzip|zstd`).
- `content_sha256` MAY provide the hash of the stored bytes (before decoding), enabling integrity checks without requiring inline payloads.

#### Streaming/chunking posture (AI-native; additive)

Some use cases produce partial outputs (streaming responses, large artifacts, multi-step tool calls). The v1 protocol does not require a special “stream transport”; instead:

- publish a sequence of envelopes that share a stable `correlation.correlation_id`
- carry chunk metadata in a namespaced `extensions` object (one possible shape):
  - `extensions.if_bus_stream.stream_id`
  - `extensions.if_bus_stream.sequence`
  - `extensions.if_bus_stream.is_final`

Black/white:
- chunking is an interoperability posture, not a delivery guarantee.
- each envelope chunk still has its own `event_id` and `payload_sha256`.

#### Topic taxonomy (multi-tenant; transport-compatible)

The runtime MUST treat topics as a **stable routing surface** that maps cleanly to:
- NATS subjects
- Kafka topics
- other backends with topic/subject routing

Canonical topic shape (dot-separated tokens):

```text
if.bus.{tenant_id}.{environment}.{domain}.{event_type}
```

Notes:
- `tenant_id` is REQUIRED for multi-tenancy and isolation.
- `environment` is REQUIRED (`dev|staging|prod|preview|roadmap` etc; runtime-defined).
- `domain` SHOULD be a short namespace that can be dotted (e.g. `ingress.github`, `egress.docusign`, `control.runtime`).
- `event_type` SHOULD be a stable token (`push`, `envelope_created`, `delivery_failed`).

Wildcards are transport-specific (e.g., NATS subscribers may use `if.bus.acme.*` patterns). The envelope stores the concrete topic string (no wildcards).

#### QoS mapping for `routing.priority` (hint + deterministic fallback)

`routing.priority` is a **hint** (0–10). The protocol does not guarantee strict priority ordering across transports.

To make priority implementable across backends, the runtime MUST define a deterministic fallback when native priority queues are unavailable:

- If backend has no native priority (e.g., NATS): publish to derived subjects by inserting a priority token after `{environment}`:
  - `if.bus.{tenant}.{env}.p{priority}.{domain}.{event_type}`
- If backend supports priority natively (e.g., RabbitMQ): map `routing.priority` to backend priority features and MAY keep the base topic unchanged.

Consumers that care about priority MUST subscribe to the appropriate set of derived topics (or backend-native priority queues).

### 4.2 Control-plane command

Schema path:
- `schemas/if-bus/control_command.schema.json`

Required capabilities:
- async pause/resume/replay/quarantine
- budget adjustments (by scope)
- idempotency keys (safe retries)

#### Reference runtime control surface (v1 skeleton)

Control topics (reference implementation defaults):

```text
if.bus.control.command
if.bus.control.ack
```

Supported `command.name` values (v1 skeleton):
- `pause` (`parameters.mode=hold|drain`, optional `ttl_seconds`, `hold_delay_seconds`, `max_hold_attempts`)
- `resume`
- `quarantine` (optional `ttl_seconds`, optional `reason`)
- `unquarantine` (alias: `release`)
- `replay` (`parameters.limit`, optional `start_after`, optional `publish_to`)
- `metrics` (returns counters + best-effort backlog snapshot in `control_ack.extensions.metrics`)

Black/white scope:
- `pause(mode=hold)` is bounded by `max_hold_attempts` to reduce abuse; when exceeded, the message is dead-lettered.
- `replay` republishes messages and can produce duplicates; v1 does not claim exactly-once delivery.
- When emitting runtime-generated events (DLQ and control acks), trace context in `extensions.otel.*` is propagated best-effort (no OTel stack required).
- Optional control-plane auth gate (reference runtime skeleton): when `control_auth` is configured (see `schemas/if-bus/runtime_config.schema.json`), unsigned/invalid control commands MUST be rejected with an auditable `control_ack` and MUST have no side effects. The reference HMAC signature is computed over canonical JSON bytes of the control command with `extensions.auth` removed.

### 4.3 Control-plane acknowledgement

Schema path:
- `schemas/if-bus/control_ack.schema.json`

Required capabilities:
- accepted/rejected/in-progress/completed
- explicit error codes and retryability flags
- stable linkage to `command_id`

### 4.4 Budget telemetry (pre-emptive)

Schema path:
- `schemas/if-bus/budget_event.schema.json`

Required capabilities:
- cost estimate (preflight) + cost actual (postflight)
- soft-limit warnings + hard-stop signals
- scoped budgets (tenant/workflow/adapter)
- optional resource caps (api_calls/bytes/tokens/compute) to remain stable when vendor pricing changes
- optional replenishment schedule metadata (window resets)
- optional reconciliation linkage (preflight → postflight deltas)

### 4.5 Security signals (`if.security` hooks)

Schema path:
- `schemas/if-bus/security_signal.schema.json`

Required capabilities:
- detector identity + version
- severity + finding type
- redacted evidence pointers (no secrets in the signal payload)

### 4.6 Dead-letter envelope (DLQ is a first-class event)

Schema path:
- `schemas/if-bus/dead_letter_event.schema.json`

Required capabilities:
- wraps the **original envelope**
- includes a black/white `error_context.kind` classifier
- includes `retry_history` (even if empty)
- includes transport metadata (`source_transport`) for debugging and replay

### 4.7 Runtime config (retention policy is mandatory)

Schema path:
- `schemas/if-bus/runtime_config.schema.json`

Required capabilities:
- `retention_policy.limits` (bytes/messages/age) and an explicit `when_exceeded` behavior
- DLQ topic configuration
- transport configuration (implementation detail; not part of the envelope protocol)
- optional control-plane auth configuration (`control_auth`) for the reference runtime skeleton
- optional ingress quotas/backpressure configuration (`quotas`) for the reference runtime skeleton

---

## 5) Reliability semantics (must be explicit)

The bus spec must state the defaults clearly:

- Delivery semantics: **at-least-once** by default.
- Deduplication: supported via `idempotency_key` (control plane) and `event_id` (data plane).
- Ordering: best-effort ordering only within a `partition_key`.
- Retries: bounded retry policy with exponential backoff and max attempts.
- Dead-letter: failed deliveries must emit a structured failure event (not just logs).
- Replay: replay is a control-plane command with audited outcomes.

Retention MUST be explicit:
- A runtime instance must have a configured retention policy (`schemas/if-bus/runtime_config.schema.json`).
- When retention limits are hit, the behavior must be black/white (`discard_oldest` or `reject_new`).

Non-goals for v1 (explicitly):
- exactly-once semantics across systems
- distributed transactions

---

## 6) Security + scalability hardening (gaps addressed)

These sections are intentionally “non-breaking”: they add requirements and guidance without forcing breaking changes to the v1 envelope.

### 6.1 Producer/consumer authentication (data plane)

Black/white requirement: producers and consumers MUST authenticate to the bus transport.

Implementation choices (not protocol):
- mTLS (service identity)
- signed tokens (short-lived; audience-scoped)
- transport-native accounts/tenants (e.g., NATS accounts)

Authorization MUST be scoped at minimum by:
- `tenant_id` (from the topic taxonomy)
- topic prefix (publish vs subscribe)

### 6.2 Control-plane authorization (RBAC, separate from data plane)

Control-plane commands are more dangerous than data-plane events. The runtime MUST implement explicit authorization for:
- submitting control commands (pause/resume/replay/quarantine/budget)
- reading control status and command audit logs

Recommended RBAC scope model (illustrative; runtime-defined):
- `control:pause:{tenant}:{topic}`
- `control:replay:{tenant}:{topic}`
- `control:quarantine:{tenant}:{topic}`
- `control:budget:{tenant}:{budget_id}`

Black/white requirement: unauthorized control requests MUST fail closed and MUST be auditable (who/when/what was denied).

Reference implementation note (v1 runtime skeleton): an HMAC gate can provide a minimal “fail-closed” posture for control-plane commands on a single host. This is authentication/integrity only (shared secret), not RBAC: it does not express “who can do what”, only whether a command is authorized by possession of the secret.

### 6.3 Trace context propagation (OpenTelemetry / W3C Trace Context)

To support end-to-end audit and debugging, the runtime SHOULD propagate trace context across adapters and executions.

Compatibility rule: to avoid breaking the v1 envelope, trace context SHOULD be carried in namespaced `extensions` keys (examples):
- `extensions.otel.traceparent` (W3C `traceparent`)
- `extensions.otel.tracestate` (W3C `tracestate`)

### 6.4 Ingress/egress quotas + backpressure (anti-abuse)

The runtime MUST define black/white behavior under load to prevent queue poisoning and cost blowouts:

- per-tenant quotas (messages/sec, bytes/sec, concurrent actions)
- per-adapter quotas (e.g., max outbound calls/minute)
- backpressure behavior (reject, slow, quarantine, or dead-letter)

Flow control note (design posture):
- Prefer bounded in-flight consumption (`max_inflight`) and explicit pause/resume over unbounded buffering.
- When a consumer falls behind, it is acceptable to pause ingress and record the reason (control ack + DLQ events), rather than “silently accumulate risk”.

When rejecting, the runtime SHOULD emit an auditable signal event (or control ack) explaining:
- what limit was exceeded
- which scope was applied (tenant/workflow/adapter)
- whether retry is safe (and suggested delay)

Reference runtime skeleton (this repo): quotas are optional and configured via `schemas/if-bus/runtime_config.schema.json` (`quotas`). When exceeded, the reference runtime emits a DLQ event with `error_context.kind=quota_exceeded` and then acks the original message (fail-closed). Quotas are keyed per `{tenant_id,topic}` and enforce both messages/sec and bytes/sec.

### 6.5 Retention defaults (hot store; explicit)

Retention is mandatory and configured via `schemas/if-bus/runtime_config.schema.json`.

Design target defaults (runtime-configurable):
- hot retention age: `72h`
- when exceeded: `discard_oldest`

Black/white: a runtime instance MUST declare its retention behavior; “infinite retention by accident” is a bug.

### 6.6 CloudEvents mapping (compatibility note; not a rename)

The envelope can be mapped into CloudEvents for compatibility with existing tooling. This is guidance only; the envelope is not renamed.

Suggested mapping (non-normative):
- CloudEvents `id` → `event_id`
- CloudEvents `type` → `event.name`
- CloudEvents `time` → `emitted_utc`
- CloudEvents `source` → `{producer.kind}:{producer.id}`
- CloudEvents `subject` → `{subject.kind}:{subject.id}` (when present)
- CloudEvents `datacontenttype` → `payload_media_type`
- CloudEvents `data` → `payload` (note: payload may be redacted; `payload_sha256` is authoritative)
- CloudEvents extensions → `extensions.*`

### 6.7 Geo/DR posture (single-host reality gate)

Black/white reality gate:
- v1 is a single-host environment. This spec does not claim a deployed multi-region bus runtime.

Non-breaking design target (future-backwards): replication should be achieved **below** the envelope, at the transport/log layer, so clients and adapters do not need to change.

Candidate approaches (implementation, not protocol):
- NATS JetStream: stream mirroring / sources (async)
- Kafka: mirror maker / cross-cluster replication (async)
- Periodic export of retained messages + deterministic replay (slow but simple)

DR goals (design targets only; not claimed as shipped):
- RPO: minutes (bounded by replication lag)
- RTO: tens of minutes (bring up transport + replay)

Black/white restore story (minimal):
1) Recover the transport/event log in the DR site.
2) Rehydrate the DLQ + retained stream (mirror or restore).
3) Restart adapters/consumers and replay from a known offset using a control command.

---

## 7) Five-year “no-break” compatibility rules

If we want five years without breaking changes, we need rules that are annoying now but save us later.

- Never change the meaning of an existing field.
- Never re-use an enum value with a new meaning.
- Never require a previously optional field.
- Prefer new schema versions over breaking v1.
- Require `extensions` keys to be namespaced (e.g., `vendor.*` or `org.*`).
- Provide a stable mapping from `event_id` → derived artifact IDs.
- For any event with a registered payload schema (see `schemas/if-bus/payload_registry.json`), treat the payload schema as **additive-only** in v1 (new optional fields only).

---

## 8) External feedback request (x‑multiplier prompt)

If you are reviewing this spec, please respond with:

1) **Missing requirements** (top 10) you believe will bite within 5 years.
2) **Breaking-change risks** in the proposed envelope and control plane.
3) **Operational failure modes** we did not specify (backpressure, replay abuse, queue poisoning).
4) **Security gaps** for a hostile internet environment (replay, injection, secret leakage, auth boundaries).
5) **Budget model critique**: what we should measure, how we should cap, and where preflight estimates fail.
6) **Minimal shippable runtime**: smallest subset that is still worth shipping.

Suggested format (copy/paste):

```text
Reviewer:
Date (UTC):

Top 10 missing requirements:
1)
2)
...

Breaking-change risks:
- ...

Operational failure modes:
- ...

Security gaps:
- ...

Budget model critique:
- ...

Minimal shippable runtime (v1):
- ...
```

---

## 9) Open questions (explicitly unresolved)

- Should the envelope hash be defined over:
  - canonical JSON bytes
  - raw payload bytes
  - both (recommended: both, with explicit fields)?
- What is the minimum set of control commands required for the first end-to-end demo?
- Should security scanning be:
  - inline (blocking)
  - async (signal-only)
  - both (recommended: both, with per-topic policy)?
- What is the right default budget scope:
  - per tenant
  - per workflow
  - per adapter?


## Appendix D — if.gov triage/council/extended intermediary spec (source)

Embedded from: `/root/docs/75-ifgov-triage-council-extended-intermediary-spec.md`

---

# IF.GOV triage + council + extended: intermediary spec (external review pack)

**Generated (UTC):** 2026-01-10  
**Audience:** external reviewers (humans + LLMs)  
**Purpose:** propose a reviewer-proof, non-drifting contract for `if.gov.triage`, `if.gov.council`, and `if.gov.council.extended` (inputs → outputs, seat model, audit trail), without claiming a shipped runtime.

This pack is **black/white**: it separates what is **verified** (registry status, public artifacts) from what is **proposed** (the spec).

---

## 0) Black / white primer

- **Receipts prove** byte integrity: the bytes you download match the hashes on the receipt (and signatures when present and verifiable).
- **Receipts do not prove** factual correctness, safety, compliance, or intent.
- **QUANTUM READY** means: a post‑quantum signature receipt exists for the trace. It is not a claim of “quantum security”.
- **Link hygiene:** one URL per line; prefer HTML views because some sandboxes block downloads.

---

## 1) Registry snapshot (scope and naming)

Source of truth:

https://infrafabric.io/grok/if.registry.json

Registry entries in scope (as of this document):

- `if.gov` — path `/if/gov` — status `preview`
- `if.gov.triage` — path `/if/gov/triage` — status `roadmap`
- `if.gov.council` — path `/if/gov/council` — status `roadmap`
- `if.gov.council.extended` — path `/if/gov/council/extended` — status `roadmap`
- `if.trace` — path `/if/trace` — status `shipped` (receipt surface used by governance artifacts)

Landing pages (public):

https://infrafabric.io/if/gov/
https://infrafabric.io/if/trace/

---

## 2) What is verified today (relevant public evidence)

### 2.1 A reviewable `if.gov` demo pack exists (evidence of intended deliverable shape)

https://infrafabric.io/static/hosted/review/if-gov-decision-pack-demo/2026-01-05/index.html

### 2.2 The “philosophy foundation” pack exists (context on drift + proposed controls)

https://infrafabric.io/grok/philosophy/2026-01-08/

### 2.3 Reality gate

The registry marks `if.gov.triage`, `if.gov.council`, and `if.gov.council.extended` as `roadmap`.  
This document is therefore a **spec proposal**, not a deployment claim.

### 2.4 A council seats bundle exists (macro/pragmatist, contrarian, jester)

https://infrafabric.io/grok/products/if-gov/council-seats/2026-01-08/index.html

---

## 3) Problem statement (why an intermediary spec)

We want a governance system that:
- scales to many products without “persona theater”,
- is legible to compliance boards (no criminal-intent framing),
- produces artifacts that are externally reviewable (HTML-first, no-login),
- and does not drift every time the council is run.

The drift risks we’re explicitly addressing:
- inconsistent seat rosters (who is “in the room” changes without a contract),
- inconsistent weighting/thresholds (votes can’t be compared across sessions),
- inconsistent claims (mixing “verified by receipts” with interpretation),
- and inconsistent “real-person inspired” naming (implied endorsement/impersonation risk).

---

## 4) Terms (minimal)

- **Casefile**: the input dossier describing a decision/problem to evaluate (question, context, constraints, evidence links).
- **Seat**: a role with a charter (repeatable questions + required outputs) that produces a vote or a memo.
- **Panel spec**: versioned roster + weights + trigger rules + thresholds.
- **Decision pack**: the council’s primary output (Markdown + HTML wrapper), including votes, rationale, and explicit stop conditions.
- **Publication safety**: classification for what can be published without exposing secrets or person-specific allegations.

---

## 5) Output contracts (triage → council → extended)

### 5.0 Deliberation timing targets (design intent; data pending)

Black/white: these are target envelopes for convening a decision loop. They do not imply measured latency or a deployed runtime.

- `if.gov.triage`: milliseconds (local-only routing + stop conditions; no extended research).
- `if.gov.council`: milliseconds (core roster; no extended research).
- `if.gov.council.extended`: adaptive ms → minutes, depending on whether real-time verification or supplemental data is required.

### 5.1 `if.gov.triage` (roadmap): decide *how* to run governance, not *what* to decide

**Inputs (minimum):**
- casefile (Markdown or JSON)
- registry snapshot (product IDs, statuses, paths)

**Outputs (minimum):**
- `triage_report.md` (human-readable)
- `triage_summary.json` (machine-readable)

**Triage report must contain:**
- decision type classification (e.g., product messaging, security posture, money movement, policy)
- impact assessment (who/what is affected; including “public user-facing” yes/no)
- recommended panel template (see §6)
- required seats (trigger rules)
- publication safety plan (what must be redacted; what can be public)
- stop conditions (what must be true before council can approve)

**Non-negotiable triage rule:** a council cannot be “approved” if triage produced unresolved stop conditions.

### 5.2 `if.gov.council` (roadmap): produce a decision pack with a stable audit trail

**Inputs (minimum):**
- triage outputs
- panel spec (versioned)
- casefile

**Outputs (minimum):**
- `decision_pack.md` (primary)
- `votes.json` (machine-readable vote + weights + thresholds)
- `artifacts.json` (links to receipts/packs; one URL per line in the Markdown)

**Decision pack must contain:**
- black/white section: what is verified vs interpretation
- per-seat outputs (or a summarized excerpt + link to full transcript)
- a vote table (votes + weights + rationale)
- stop conditions + their resolution status
- explicit “what changed / what to verify” list (commands, if any)

### 5.3 `if.gov.council.extended` (roadmap): add domain expertise without exploding baseline complexity

Extended council adds **on-demand expert modules** (see §7) driven by triage triggers, not by hand-waving.

**Additional outputs (minimum):**
- `expert_modules.json` (which modules were invoked and why)
- “expert dissent” section (what experts disagreed with and what evidence would change their view)

---

## 6) Seat model (stable baseline)

This spec proposes the following baseline seat classes:

### 6.1 Core guardians (voting)

Six core voting seats with charters (technical, ethical, legal, scientific, business, coordination).

### 6.2 Philosophy priors (voting; recommended: 6 tradition priors)

Recommended: 6 voting “tradition priors” rather than 12 named philosophers:
- Western: empiricism, rationalism, pragmatism
- Eastern: buddhism, daoism, confucianism

Rationale: keeps philosophy as an enforceable constraint without seat explosion.

### 6.3 IF.CEO (voting; executive tradeoff lens, not a person)

Recommended default: 8 facets (4 “light” + 4 “dark”) as a single executive layer.

Escalation: 16 facets may exist as an “expanded mode” for high-stakes decisions, but should be explicitly triggered and versioned (not always-on).

### 6.4 Contrarian (voting; veto mechanism for extreme consensus)

Contrarian veto rule (proposal):
- if weighted approval ≥ 95%, trigger a cooling-off decision: approve/hold/reject, with explicit rationale.

### 6.5 Preview runtime cut (fast preview; implementation target)

Black/white: this is the smallest plausible roster for a preview runtime, not the full baseline seat model above.

Initial roster (implemented seats + their voting posture):
- `cabinet.macro.merchant_pragmatist` — voting.
- `cabinet.contrarian.reframing` — voting.
- `cabinet.jester.narrative_stress_test` — non-voting (memo to the Contrarian).

All other seats/roles are simulated initially to preserve the *shape* of the decision pack, and then replaced over time with static JSON personas grounded in empirical data (with coverage manifests + checkers to prevent drift).

---

## 7) Council Red Team (non‑voting) and integrity/capture handling

To avoid criminal-intent framing, “corruption” is handled as **integrity/capture risk**, not as an accusation about a person.

### 7.1 Council Red Team (non-voting) output contract

The Red Team produces a memo with findings using:
- stable `finding_id`
- category (e.g., conflict of interest, resource leakage, process capture, insider threat)
- severity + confidence
- verified evidence handles (or `none`)
- stop conditions + required controls
- publication safety (`public_ok | redact_details | private_only`)

### 7.2 How an integrity/capture finding is processed in the meeting

1) Red Team memo is produced (non‑voting).
2) Publication safety is applied (avoid person-specific allegations in public artifacts).
3) Contrarian response is mandatory: for each `finding_id`, the Contrarian must either:
   - accept the stop condition (hold/cooling‑off until satisfied), or
   - override (rare) with a black/white justification and falsifiability criteria.
4) Council cannot “approve” while any high/critical stop condition is unresolved.
5) Decision pack must include a “findings response table” linking `finding_id` → disposition.

---

## 8) Execution modes: simulation vs multi-model (how to run this)

### 8.1 Mode A — single-provider simulation

One model simulates all seats (separate charters/prompts) and produces artifacts per seat.
Best for iterating contracts, triggers, and lint rules.

### 8.2 Mode B — per-seat models/providers (stronger independence)

Different models/providers are assigned per seat.
Seats run in parallel; orchestrator collects outputs and computes the weighted vote.
Best for reducing correlated blind spots for high-stakes decisions.

Open question: what triage threshold should force Mode B?

---

## 9) Drift controls (must exist before claiming “formalized” governance)

This intermediary spec assumes the following controls are required:

1) **Versioned panel spec** (roster + weights + thresholds + trigger rules).
2) **Lint**: fail if a seat exists without a charter, weight, trigger rule, and required outputs.
3) **Public artifacts**: publish panel specs + decision packs HTML-first.
4) **Black/white enforcement**: linter rejects claims that exceed what receipts verify.
5) **Link hygiene enforcement**: one URL per line; no internal URI schemes.

---

## 10) Reviewer questions (what we want external critique on)

1) Should philosophy be 1 seat, 2 seats (west/east), 6 priors, or 12 philosophers? Why?
2) Should IF.CEO be 8 facets, 16 facets, or on-demand only? Why?
3) What is the minimum viable extended “cabinet” module set, and what should trigger it?
4) What exact veto/cooling-off rules make sense for the Contrarian?
5) What publication safety policy should govern Red Team findings?

---

## 11) Reviewer prompt (copy/paste)

Please respond with this header block:

```text
llm_name:
probable_model:
cutoff_date:
response_date_utc:
web_access_used: yes|no
```

And then:
- Provide a recommended spec delta (what to add/remove/change) in plain English.
- If you propose concrete artifacts (YAML/JSON schemas), ensure they are valid JSON/YAML (no comments in JSON).
- Separate “verified” vs “judgment” in your response.


## Appendix E — if.gov portfolio-based council structure (source)

Embedded from: `/root/docs/94-ifgov-portfolio-council-structure.md`

---

# `if.gov` council structure (portfolio-based, design target)

Last updated (UTC): 2026-01-11

Reality gate (single-host): `docs/22-ifttt-handover-and-roadmap.md`

---

## Status (black/white)

This document is:
- a design target for how `if.gov` councils can be made legible to non-experts (“subjects”) without relying on philosophy jargon
- a progressive path from simulated seats → deterministic checkers (model-agnostic)

This document is not:
- a claim that these seats exist as implemented runtime code today
- a claim that `if.gov` is “compliance” or “truth” infrastructure

Registry status reminder:
- `if.gov` is `preview` (decision-pack demo exists)
- `if.gov.triage`, `if.gov.council`, `if.gov.council.extended` are SKUs with `roadmap` status (design targets)

---

## Why portfolio-based seats

If a nurse, a farmer, or a civil servant reads a decision pack, “Finance” and “Legal” are immediately understandable.

Portfolio seats:
- reduce the perception of “LLM governance theater”
- make the council map to real organizations (budget, legal, operations, safety)
- allow progressive determinism: each seat can evolve from a simulated role into a checker-backed contract

---

## Current preview posture (what exists today)

From the public `if.gov` page: the preview runtime posture is “coded seats + simulated roles”.

Current coded seats (implemented today as council-seat artifacts; see the `if.gov` packs for details):
- pragmatist / macro-merchant (voting)
- contrarian / reframing (voting)
- court jester / narrative stress test (non-voting)

Black/white: other roles may be simulated during preview and replaced over time by empirical static JSON personas and/or deterministic checkers.

---

## Evidence gating (design target, cross-cutting)

The non-negotiable safety posture is that **HYPOTHESIS must not trigger automation**.

Evidence typing is defined in `if.security` posture:
- OBSERVED
- DERIVED
- HYPOTHESIS

Design target: actuation gates in `if.gov` and control-plane actions in `if.bus` should treat HYPOTHESIS as “cannot automate”.

---

## Proposed council roster (design target)

This roster is intentionally phrased as government portfolios. The goal is not to mimic any one country; it is to be legible.

### Core (always present)

1) Executive synthesis (Prime Minister / Chair)
- Responsibilities: ensure the pack is complete, dissent is preserved, reversibility is explicit.

2) Coordination / cabinet secretary
- Responsibilities: make sure required portfolios were invoked; enforce process rules.

### “Gov-grade” portfolios (activate by trigger)

3) Finance / Treasury
- Trigger: budget, procurement, ongoing operational costs.

4) Central bank / monetary conditions
- Trigger: currency risk, long-tail cost exposure, liquidity constraints (where relevant).

5) Justice / legal affairs
- Trigger: liability, jurisdiction, due process, contracts.

6) Interior / home affairs (safety + public order)
- Trigger: physical safety, security posture, incident response.

7) Foreign affairs
- Trigger: cross-border impacts, international partners, sanctions/embargo sensitivity.

8) Defense / risk management
- Trigger: adversarial threat models, critical infrastructure, escalation risk.

9) Digital / technology
- Trigger: buildability, operability, failure modes, attack surfaces.

10) Public service / transparency
- Trigger: explainability to subjects, audit readiness, disclosure posture.

11) Health / social care (where relevant)
- Trigger: wellbeing, safety boundaries, high-stakes human outcomes.

12) Labour / employment
- Trigger: workforce impact, incentives, labor risk.

13) Industry / commerce
- Trigger: competitive impact, vendor lock-in, procurement realities.

14) Infrastructure / transport
- Trigger: physical logistics, reliability, continuity planning.

15) Environment / sustainability
- Trigger: resource constraints, long-term externalities.

16) Education / research
- Trigger: epistemic posture, research integrity, knowledge provenance.

17) Agriculture / resources
- Trigger: resource policy, food/water/land impacts.

18) Culture / heritage
- Trigger: communication risks, narrative impact, societal legitimacy.

Black/white note: the above is a **seat taxonomy**, not a claim that the roles are staffed or empirically grounded yet.

---

## Progressive determinism (how seats stop being “vibes”)

Each seat can evolve through phases:

Phase 1 — simulated seat (LLM optional)
- Output is schema-constrained JSON (even if generated by a model).
- The seat must label its statements as evidence-linked vs interpretation.

Phase 2 — structured charter
- “Must evaluate” questions are explicit.
- Outputs must include a vote + rationale + stop conditions.

Phase 3 — deterministic checkers (preferred end state)
- A seat has one or more stdlib-only checkers that validate:
  - evidence sufficiency (OBSERVED/DERIVED)
  - budget/risk thresholds
  - forbidden claims (“cannot automate from HYPOTHESIS”)
- LLMs become optional drafters/summarizers only.

---

## Links (HTML-first)

`if.gov` page:
https://infrafabric.io/if/gov/

`if.gov` review pack:
https://infrafabric.io/llm/products/if-gov/

Decision-pack demo:
https://infrafabric.io/static/hosted/review/if-gov-decision-pack-demo/2026-01-05/index.html

Council seats pack:
https://infrafabric.io/llm/products/if-gov/council-seats/2026-01-08/index.html

Triage/council/extended intermediary spec:
https://infrafabric.io/llm/products/if-gov/triage-council-extended-spec/2026-01-10/index.html

`if.security` posture (evidence typing):
https://infrafabric.io/llm/products/if-security/security-posture/2026-01-11/index.html


## Appendix F — IF.GOV decision pack demo (source)

Embedded from: `/root/docs/33-ifgov-decision-pack-demo.md`

---

# IF.GOV Decision Pack (demo) — “Acme Support Copilot” (fictional)

**Audience:** external reviewers + operators  
**Reality gate:** `docs/22-ifttt-handover-and-roadmap.md` (single-host; receipts-first)  
**Not legal advice.** This is a governance deliverable template + demo.

This is a *demo* decision pack for a fictional casefile:
- Input casefile: `docs/33-ifgov-decision-pack-demo-input.md`

---

## 0) Links (HTML-first; one per line)

Decision pack (hosted-static HTML):
https://infrafabric.io/static/hosted/review/if-gov-decision-pack-demo/2026-01-05/index.html

`if.trace` receipt (brand `if.trace`) (shareId):
https://infrafabric.io/static/trace/zxWjdzxZd2FiuYpfS90ETFMj

Pack (HTML view):
https://infrafabric.io/static/pack/zxWjdzxZd2FiuYpfS90ETFMj

Pack (raw Markdown):
https://infrafabric.io/static/pack/zxWjdzxZd2FiuYpfS90ETFMj.md

---

## 1) What this pack proves (black/white)

Proves:
- The published bytes of this decision pack match the hashes on the `if.trace` receipt.
- The input casefile bytes (if published) match the hashes on the `if.trace` receipt.
- Where signatures exist and keys are discoverable, signatures can be verified.

Does not prove:
- That any narrative statement here is true.
- That Acme will comply with anything.
- That the system is safe, secure, or deployed.

“QUANTUM READY” means: a post‑quantum signature receipt exists for this trace (verification may require PQ tooling). It is not a claim of quantum security.

---

## 2) Executive summary (decision)

Decision: **Approve with conditions** (demo).

Why:
- Drafting + summarization can reduce support load *if* humans remain the final decision-maker.
- The main failure modes are governance failures (scope creep, weak review gating, poor evaluation), not “model choice”.

Conditions (must be true before rollout):
1) Human review is enforced in UI and logs (no auto-send).
2) A small evaluation set exists with clear pass/fail criteria.
3) A “bad draft shipped” incident procedure exists (stop button + escalation).
4) Data-handling mode is chosen explicitly (see §6).

---

## 3) Scope and non-goals

In-scope:
- draft reply suggestions
- internal summaries for support agents
- ticket triage suggestions (human-confirmed)

Out-of-scope:
- autonomous replies
- access to payment systems or production databases
- “compliance certification” claims

---

## 4) Risk register (top risks)

Risk 1 — Hallucinated commitments (refunds / SLAs / policy promises)
- Likelihood: medium
- Impact: high
- Mitigation: “draft-only” UI, mandatory human review, forbidden-claim linting in templates, audit sampling.

Risk 2 — Sensitive data disclosure (PII, internal incident notes)
- Likelihood: medium
- Impact: high
- Mitigation: redact/guardrails at intake; no-retention preferred; logging discipline; role separation.

Risk 3 — Scope creep (draft-only becomes “auto-send”)
- Likelihood: high
- Impact: high
- Mitigation: hard policy gate; require IF.GOV re-review for any automation step-change.

Risk 4 — Evaluation theater (no real pass/fail)
- Likelihood: high
- Impact: medium
- Mitigation: publish evaluation plan and require evidence artifacts; bind outputs to receipts.

Risk 5 — Incident response gap (“bad draft shipped” has no owner)
- Likelihood: medium
- Impact: high
- Mitigation: explicit owner + playbook + stop conditions + logging for audit.

---

## 5) Control plan (gates and stop conditions)

Gate A — Draft-only enforcement
- Required: the system cannot send without a human confirmation action.
- Evidence: UI screenshots are not sufficient; require an auditable event log and a spot-check procedure.

Gate B — Forbidden claim linting
- Required: detect and block drafts that include forbidden commitments (“refund approved”, “SLA guaranteed”) unless a human overrides with justification.
- Evidence: show the rule list and override logs.

Gate C — Evaluation pass/fail
- Required: the evaluation set is defined and results are recorded.
- Evidence: evaluation report + raw inputs/outputs (as permitted) + receipt links.

Stop condition 1 — Repeat critical failure
- Trigger: ≥2 critical incidents in a rolling 7-day window (e.g., leaked incident details, hallucinated refund promise shipped).
- Action: disable copilot for external-facing replies until IF.GOV re-review.

Stop condition 2 — Data-handling breach
- Trigger: evidence of retention beyond the selected mode (see §6).
- Action: stop + investigate + publish a delta pack if the decision changes.

---

## 6) Data-handling mode (choose explicitly)

Mode 1 — No retention (hash-only):
- Store only hashes + receipt metadata.

Mode 2 — Retention window:
- Store inputs/outputs for a fixed time window (e.g., 7/30/90 days).

Mode 3 — Client-hosted export-only:
- Client holds the bundles; we keep only hashes.

This demo does not choose a mode; a real pack must.

---

## 7) Evaluation plan (minimum viable)

Define:
- ticket categories in scope (start with a narrow subset)
- “known bad outcomes” list (refund promises, policy misquotes, sensitive disclosure)
- pass/fail criteria per category

Minimum tests:
1) Draft quality: human rating rubric (clarity, correctness, tone).
2) Safety: forbidden-claims detection rate (and override rate).
3) Privacy: redaction effectiveness (no secrets/PII beyond what the agent already sees).
4) Reliability: degraded mode behavior (copilot down → manual workflow still works).

Outputs to publish (demo/real):
- evaluation report
- receipts that bind evaluation artifacts (hash-only if needed)

---

## 8) Assumptions + what would change our mind

Assumptions:
- Human review is enforced, not optional.
- Rollout is scoped and staged.

Would change our mind:
- If the business demands autonomous sending without compensating controls.
- If evaluation cannot be made auditable.
- If data-handling requirements cannot be satisfied on the current single-host deployment.

---

## 9) Receipt block (fill in per pack)

Receipt surface (one per line):
https://infrafabric.io/static/trace/zxWjdzxZd2FiuYpfS90ETFMj
https://infrafabric.io/static/pack/zxWjdzxZd2FiuYpfS90ETFMj

---

## Appendix G — `if.emotion` update: clinical intake prescreening support (public synthetic bundle)

This appendix embeds a **public, synthetic** clinical prescreening demo bundle. It is included here because reviewer environments often fail to follow links or download archives.

Black/white boundary:
- This is **non-diagnostic** clinician review support (marker surfacing), not a screening test.
- This appendix includes **no real chat history** and makes **no clinical efficacy claims**.
- The original private bundle (with real message histories) is not publishable; do not infer its contents from this appendix.

Why this is relevant to `if.emotion` (preview):
- It demonstrates a recurring systems failure mode in wellbeing tooling: **context collapse** (state → trait), especially under safety constraints.
- It shows one concrete mitigation pattern: **context windowing** (prompt + user message) so a clinician can see why a marker fired.
- It introduces **GitHub-style daily heatmaps** to visualize whether detections recur (persistence) or spike (episodic), and to separate “exposure” (message volume) from “signal” (marker density).
- It supports the broader InfraFabric posture: **governance for the subjects** (humans can audit “what happened and why”) and “security isn’t a tax; it’s a seatbelt” (reduce silent failure, bound blast radius, keep incidents auditable).

Embedded files (verbatim):

---

### `public_bundle/WHITEPAPER_Clinical_Prescreening_PUBLIC.md`

# Clinical Intake Pre‑Screening Support From Chat Histories (Public Demo)
## An Offline Hybrid NLP Pipeline for Marker Surfacing Across ASD & Personality Pathology Domains

**Document type:** Technical / clinical operations white paper (implementation-ready)  
**Status:** Prototype (non-validated; non-diagnostic)  
**Primary demo outputs:** `examples/output/Clinical_Assessment_Prep_SYNTHETIC.html`, `examples/output/Clinical_Assessment_Prep_Table_SYNTHETIC.html`  
**Reference implementation:** `clinical_assessment_prep.py`  
**Demo dataset:** Synthetic only (included)

---

## Clinical disclaimer (must read)
This system **does not diagnose** Autism Spectrum Disorder (ASD), Personality Disorders, or any other condition. It produces **non‑diagnostic “Marker Identified / Trait Pattern” flags** intended to help clinicians and clinical assistants **locate potentially relevant excerpts** in large text histories during intake review.

Outputs:
- are **not probabilities**
- are **not validated screening results**
- should not be used for automated decisions

If you use the term “pre‑screening,” it should be constrained to **“pre‑screening support for clinician review (non‑diagnostic)”**.

---

## 1) Executive Summary
Psychiatric intake increasingly involves high-volume patient narratives (journals, messaging logs, chat histories). These are temporally rich but challenging to review efficiently. This pipeline aims to reduce review burden by surfacing:

- **Possible linguistic markers** aligned with selected clinical domains (ASD and personality pathology frameworks)
- **Context windows** (AI prompt + user response) to reduce misinterpretation
- **Temporal structure** (GitHub-style daily heatmaps) to distinguish persistent vs episodic patterns and to separate “exposure” (message volume) from “signal” (marker density)

The system is a **hybrid**:
1. **Regex patterns** (interpretable; highlightable trigger spans)
2. **Semantic concept retrieval** via local ChromaDB (concept anchors, nearest neighbors)

Outputs are standalone HTML files designed for clinician review support.

---

## 2) Intended Use
### 2.1 Intended use (appropriate)
- Intake preparation and triage
- Rapid retrieval of supporting excerpts for interview planning
- Temporal review: identifying whether markers cluster around periods of stress, change, or increased symptom reporting

### 2.2 Not intended (inappropriate)
- Automated diagnosis or screening test claims
- Risk stratification or imminence determination
- Replacing structured assessment instruments (ADOS‑2/ADI‑R; SCID‑5‑PD; PID‑5 inventory)

---

## 3) System Overview
### 3.1 Inputs
The reference script supports:
- Chat history exports in JSONL (conversation headers + conversation bodies)
- A local embedded **ChromaDB** persistent directory (no server required)

**Important constraint:** only `role == 'user'` is analyzed. Assistant text is used only as context.

### 3.2 Outputs
Two HTML deliverables:
- **Main report**: dashboard + temporal overview + timeline + evidence cards
- **Table report**: one row per flag with expandable prompt/user text (assistant-friendly)

---

## 4) Clinical Taxonomy (Search Logic)
This prototype covers:

### ASD / Neurodevelopmental
- Social communication (e.g., “can’t read the room,” masking, eye contact, social exhaustion)
- Sensory/routine (e.g., sensory overload, texture aversion, distress with routine change)

### DSM‑5 Personality Pathology (selected clusters)
- Cluster A (prototype): suspiciousness / odd beliefs markers
- Cluster B: identity/self markers and interpersonal/emotional dysregulation markers
- Cluster C: avoidant/perfectionism/control markers

### PID‑5 trait domains (selected)
- Negative affectivity
- Detachment
- Disinhibition

### Safety
- Self-harm / suicidality language markers (review needed; not an assessment)

The taxonomy is heuristic and must be iteratively tuned with clinician oversight (see Validation Plan).

---

## 5) Hybrid Matching Method
### 5.1 Layer 1 — Regex evidence
Regex patterns aim to capture **structured relationships** rather than single keywords (e.g., “eye contact” + “hard/avoid/can’t”). When matched, the pipeline stores:
- pattern name
- matched phrase
- character span (for highlighting)

### 5.2 Layer 2 — Semantic evidence (ChromaDB)
Semantic retrieval helps capture:
- paraphrases that do not match regex
- idiosyncratic descriptions

Approach:
- define “concept anchors” (short clinical phrases) per category
- query the collection for nearest neighbors per anchor
- restrict retrieval to `role == 'user'` via metadata filtering
- compute a **relative confidence** within each anchor’s top‑N distance distribution

**Relative confidence is not a calibrated probability.** It is a within-query ranking normalization to prioritize review.

### 5.3 Evidence aggregation
A message can yield:
- Regex only
- Semantic only
- Regex + semantic

Multiple categories can fire on the same message; therefore, daily “flag counts” may exceed daily message counts.

---

## 6) Context Windowing (Safety Against Misreadings)
For every flagged user message, the report includes:
- the **preceding non-user** message (often the AI prompt)
- the user text with highlighted spans (if regex evidence exists)

This helps clinicians detect:
- quoted material
- hypothetical statements
- prompt-induced content

---

## 7) Temporal Visualization (GitHub-style Daily Heatmaps)
The report includes three daily calendars:

1. **User messages per day** (exposure)
2. **Marker flags per day** (raw marker volume)
3. **Flag rate per day** (flags per 100 user messages; density)

Why this matters:
- High volume alone can create more flags; density helps compare across time.
- “Hot” density days may indicate concentrated reporting, but can also occur on low-volume days; the tool is a pointer to open evidence cards.

Optional: group-specific daily flag heatmaps (ASD vs Cluster A/B/C vs PID‑5 vs Safety).

---

## 8) Demo Dataset (Synthetic)
This public bundle includes a synthetic demo under `examples/`:

- `examples/synthetic_export/` — JSONL files matching the expected schema
- `examples/synthetic_chroma/` — a small Chroma collection built from the synthetic user messages
- `examples/output/` — pre-generated demo HTML outputs

The demo Chroma uses `--semantic-mode hash` (deterministic hashing-vector embedding) to avoid requiring downloads of external embedding models. This mode is for demos/tests only and should not be considered a clinically meaningful semantic model.

---

## 9) Validation & Governance Plan (Required Before Clinical Claims)
To use beyond exploratory support, implement:

### 9.1 Adjudicated labeling
- clinician labels per excerpt: marker present/absent/unclear
- track inter-rater agreement (e.g., Cohen’s kappa)

### 9.2 Metrics
- precision/recall per category
- false-positive review (negation, quotations, sarcasm)
- stability over time (embedding/model drift)
- time savings vs missed safety items

### 9.3 Governance
- taxonomy versioning and changelog
- audit trails and role-based access
- explicit policy for retention and sharing

---

## 10) Risks & Ethical Considerations
### 10.1 Key risks
- Overinterpretation (flags treated as diagnosis)
- Confirmation bias (clinician anchors on flagged domains)
- Context collapse (sarcasm, hypothetical, quoting others)
- Embedding bias and cultural language variation

### 10.2 Mitigations
- strong non-diagnostic labeling in the UI
- always show prompt + user context
- encourage sampling of non-flagged content
- structured clinician feedback loop to refine patterns

---

## 11) Implementation Notes
### 11.1 Run the synthetic demo (offline)
See `README.md`.

### 11.2 Run on real data (sensitive)
Use `--semantic-mode chroma_text` (default), and keep all outputs internal.

---

## Appendix A — Terminology
- **Marker flag:** surfaced excerpt aligned to a clinical construct; requires human review.
- **Regex evidence:** direct text match with span highlighting.
- **Semantic evidence:** nearest-neighbor retrieval for a concept anchor.
- **Relative confidence:** within-anchor ranking normalization (prototype).

---

### `public_bundle/KNOWN_GAPS_AND_LIMITATIONS.md`

# Known Gaps & Limitations (Prototype)

This is a **prototype** intended for clinician review support. Before any clinical claims, it requires validation, governance, and hardening.

## Clinical/interpretation gaps
- **No diagnosis inference.** The tool does not and should not infer diagnoses; it flags “Marker Identified / Trait Pattern.”
- **Negation is limited.** Example: “I’m not suicidal” can still be mishandled without explicit negation logic.
- **Quotation attribution is limited.** Quoting another person’s words may be flagged as the user’s marker.
- **Sarcasm/figurative language not detected.** Context must be reviewed.
- **No severity/imminence assessment.** Safety markers are language-level flags only.

## Data and privacy gaps
- HTML reports can contain raw text; treat as PHI/PII-equivalent.
- “Anonymized embeddings” can still leak information under some threat models (membership inference, linkage).

## Methodological gaps
- “Relative confidence” is not calibrated; it is a within-query ranking normalization.
- Taxonomy is heuristic; patterns and anchors require clinician-led tuning.

## Ingestion and context gaps
- Export schemas vary; ordering can be imperfect in some structures.
- Context window is minimal (immediate preceding non-user message only).
- Branching/multi-thread chats are not fully modeled.

## Operational gaps
- No incremental caching; re-runs recompute semantic queries.
- No built-in adjudication UI (“true marker / false positive / unclear”).
- No EHR integration (HTML only in this demo).

---

### `public_bundle/PUBLIC_RELEASE_CHECKLIST.md`

# Public Release Checklist (Do Not Skip)

This demo bundle is safe to publish only if it contains **synthetic data only**.

## Must NOT be included in a public tar / repo
- Any real JSONL exports (`*__headers.jsonl`, `*__conversations.jsonl`) from a real account
- Any generated HTML report from real data (`Clinical_Assessment_Prep*.html`)
- Any Chroma directories built from real data (even “anonymized” embeddings can leak information)
- Any raw logs or screenshots that include sensitive text

## Before publishing, verify
1. `examples/synthetic_export/` contains only the synthetic demo files.
2. `examples/output/` contains only the `_SYNTHETIC.html` demo outputs.
3. No other `.jsonl` files exist in the bundle.
4. No other `.html` files exist in the bundle besides the synthetic demo outputs.
5. No `echoes_chroma*` directories exist in the bundle other than `examples/synthetic_chroma/`.

## Recommended (extra safety)
- Add a CI job that fails if unexpected `.jsonl` or `.html` files are present.
- Publish **code + docs + synthetic examples only**; keep patient-derived data out of source control and public hosting.

---

### `public_bundle/BUNDLE_CONTENTS.md`

# Public Bundle Contents

## Code
- `clinical_assessment_prep.py` — main pipeline (HTML report generator)
- `anonymize_echoes_chroma.py` — utility to create an anonymized ChromaDB copy (not used in the public demo)

## Synthetic demo
- `examples/generate_synthetic_demo.py` — generates synthetic JSONL + synthetic ChromaDB
- `examples/synthetic_export/` — synthetic JSONL inputs
- `examples/synthetic_chroma/` — synthetic ChromaDB directory
- `examples/output/` — synthetic demo HTML outputs

## Documentation
- `README.md` — how to run the demo
- `WHITEPAPER_Clinical_Prescreening_PUBLIC.md` — detailed method + governance notes
- `CHROMA_USAGE_QUICKSTART.md` — Chroma usage snippets
- `KNOWN_GAPS_AND_LIMITATIONS.md` — limitations and risks
- `PUBLIC_RELEASE_CHECKLIST.md` — what to exclude from public release

## Dependencies
- `requirements_symptom_cluster.txt`

---

### `public_bundle/CHROMA_USAGE_QUICKSTART.md`

# ChromaDB Usage Quickstart (Local Embedded)

This demo uses a local **embedded** ChromaDB directory (no server required).

## Connect and inspect

```python
import chromadb
from chromadb.config import Settings

client = chromadb.PersistentClient(
    path="examples/synthetic_chroma",
    settings=Settings(anonymized_telemetry=False),
)

print([c.name for c in client.list_collections()])
col = client.get_collection("echoes_messages")
print("count:", col.count())
```

## Query by concept (semantic retrieval)
```python
results = col.query(
    query_texts=["Fear of abandonment and rejection"],
    n_results=10,
    where={"role": "user"},     # critical: user messages only
    include=["distances", "metadatas", "documents"],
)
```

Notes:
- Chroma “distance” is not a clinical probability.
- This demo bundle runs the pipeline with `--semantic-mode hash` (querying by `query_embeddings`) to remain fully offline without downloading an embedding model.

## Filter by metadata
```python
results = col.get(
    where={"role": "user"},
    limit=5,
    include=["metadatas"],
)
```

---

### `public_bundle/README.md`

# Public Demo Bundle — Clinical Intake Pre‑Screening Support (Non‑Diagnostic)

This bundle is safe to publish because it includes **only synthetic demo data** (no real chat history). It demonstrates an offline analysis pipeline that flags **non‑diagnostic “Marker Identified / Trait Pattern”** signals for clinician review support.

## Quick start (run the synthetic demo)
1) Create a venv and install deps:
```bash
python -m venv .venv_prescreen
./.venv_prescreen/bin/python -m pip install -U pip
./.venv_prescreen/bin/python -m pip install -r requirements_symptom_cluster.txt
```

2) (Optional) Regenerate the synthetic export + synthetic Chroma:
```bash
./.venv_prescreen/bin/python examples/generate_synthetic_demo.py
```

3) Generate the demo reports:
```bash
./.venv_prescreen/bin/python clinical_assessment_prep.py \
  --headers examples/synthetic_export/ChatGPTConvHistorySearchDB__headers.jsonl \
  --conversations examples/synthetic_export/ChatGPTConvHistorySearchDB__conversations.jsonl \
  --chroma-path examples/synthetic_chroma \
  --collection echoes_messages \
  --semantic-mode hash \
  --hash-embed-dim 256 \
  --output examples/output/Clinical_Assessment_Prep_SYNTHETIC.html \
  --table-output examples/output/Clinical_Assessment_Prep_Table_SYNTHETIC.html
```

4) Open:
- `examples/output/Clinical_Assessment_Prep_SYNTHETIC.html`
- `examples/output/Clinical_Assessment_Prep_Table_SYNTHETIC.html`

## Running on real data (do not publish outputs)
If you use real JSONL exports + a real Chroma store, use:
- `--semantic-mode chroma_text` (default) so Chroma embeds query text using the collection’s embedding function.

**Do not upload** the resulting HTML reports, JSONL exports, or Chroma directories publicly.

## Docs
- `WHITEPAPER_Clinical_Prescreening_PUBLIC.md` (detailed method + governance notes)
- `CHROMA_USAGE_QUICKSTART.md` (how to connect/query Chroma)
- `KNOWN_GAPS_AND_LIMITATIONS.md` (prototype limitations)
- `PUBLIC_RELEASE_CHECKLIST.md` (what not to include online)