VERITAS OS v2.0 — Decision Governance and Bind-Boundary Control Plane for AI Agents

Reviewable, traceable, replayable, auditable, and enforceable AI decisions through decision and bind boundaries before real-world effect.

VERITAS OS is a Decision Governance and Bind-Boundary Control Plane for AI agents. Instead of passing model output directly to execution, VERITAS routes each decision through a reproducible, fail-closed, safety-gated, hash-chained governance pipeline with an operator-facing governance surface in Mission Control and governance APIs.

Architecture at a Glance

AI / Agent Output
  ↓
Decision Candidate
  ↓
Governance Evaluation
  ↓
Human Approval / Authority Evidence
  ↓
Evidence Chain
  ↓
Bind Boundary
  ↓
Execution Intent
  ↓
Outcome Receipt
  ↓
Reviewer Evidence Packet
  ↓
Validation Report

Layer	Purpose
Decision Candidate	Structured pre-execution decision object.
Governance Evaluation	Policy, authority, evidence, and approval checks.
Human Approval / Authority Evidence	Binds human authority and approval proof.
Evidence Chain	Preserves hashes, manifests, and verification links.
Bind Boundary	Final pre-execution control point.
Execution Intent	Allowed action after governance checks.
Outcome Receipt	Records the observed outcome.
Reviewer Evidence Packet	Reviewer-facing evidence bundle.
Validation Report	Deterministic validation result and failure reasons.

For deeper reviewer evidence context, see the Reviewer Evidence Index, Reviewer Evidence Assurance Overview, and Reviewer Evidence Packet.

External bind adapter reference

WebhookBindAdapter is the first reference adapter for external bind execution. It demonstrates how VERITAS can treat AI output as a Decision Candidate and gate an external HTTPS side effect at the Bind Boundary through snapshot, governed action, postcondition verification, deterministic idempotency, HMAC signing, and fail-closed compensation semantics before claiming a committed outcome.

This is a reference integration pattern, not production certification, regulatory approval, or proof of a production deployment. When compensation is absent or cannot be verified, the adapter does not claim rollback.

Minimal Python SDK reference

The minimal Python SDK reference is a dependency-free Python client for calling VERITAS /v1/decide, with import-safe examples and a non-executing bind payload preparation pattern. This is a reference integration aid, not a production-certified SDK: AI output remains a Decision Candidate, /v1/decide does not authorize external side effects, and external execution must still cross the Bind Boundary. WebhookBindAdapter remains the reference external bind adapter pattern.

Official Website: https://veritas-website-navy.vercel.app/

This project is not only about running agents. It is about making AI decisions reviewable, traceable, replayable, auditable, and enforceable inside real organizational workflows before they have real-world effect, with bind artifacts exposed as full bind receipts and compact bind summaries.

Mental model: LLM = CPU, VERITAS OS = Decision / Agent Governance OS on top

For external reviewers, start with docs/REVIEWER_ENTRYPOINT.md.

Reviewer Evidence Documentation

For reviewer-facing evidence assurance, validation, failure reason taxonomy, generated catalogs, and demo validation reports, start here:

External reviewer fast path

For a 10-minute implementation snapshot, start here:

External reviewers can start with the External Reviewer Quickstart v1, which explains how to inspect the golden fixture, run the validation report, review the JSON Schema, and understand the local/offline evidence chain in 10–15 minutes. See also the External Reviewer Artifact Index.

Evidence Bundle verification separates file/hash integrity from manifest authenticity and supports strict Ed25519 manifest verification using a trusted public key; start from the Technical Proof Pack for the reviewer checklist, signature verification demo, sample outputs, and external audit readiness. For the complete checked-in sample flow, use the Reviewer Handoff Sample Quickstart. This is reviewer-facing verification support, not regulatory certification or completed third-party audit approval; trusted public keys must come from an out-of-band reviewer/operator trust channel.

For a concise business-facing overview, see Enterprise Value Brief. 日本語補助版: 企業向け価値説明ブリーフ

External Validation Brief
Current Implementation Matrix
Authority Evidence Ingestion (local/offline): docs/en/architecture/authority-evidence-ingestion.md
Human Approval Receipt v1 (local/offline): docs/en/architecture/human-approval-receipt.md
Outcome Receipt v1 (local/offline): docs/en/architecture/outcome-receipt.md
Evidence Chain Manifest v1 (local/offline): docs/en/architecture/evidence-chain-manifest.md
Evidence Chain Verifier v1 (local/offline): docs/en/architecture/evidence-chain-verifier.md
Regulated Action Governance Proof Pack
AML/KYC Reviewer Handoff Pack
AML/KYC 1-day PoC Quickstart
SaaS Permission-Change Governed Demo (local/offline)
Reviewer Evidence Packet v1 (local/offline)
External Reviewer Quickstart v1
External Reviewer Artifact Index v1
Bind Coverage Registry v1 (local/offline): docs/en/architecture/bind-coverage-registry.md
LLM-to-Control-Plane Contract: docs/en/architecture/llm-to-control-plane-contract.md
- 日本語補助版: docs/ja/architecture/llm-to-control-plane-contract.md

Boundary:

This is not legal advice.
This is not regulatory approval.
This is not third-party certification.
Fixture-backed PoC evidence should not be presented as live bank-side integration.

LLM-to-Control-Plane Boundary

VERITAS does not ask an LLM to govern itself. LLM or agent output is treated as a proposal. Before it can become an executable governance input, it must cross a structured control-plane boundary:

flowchart TD
    A[LLM / Agent Proposal] --> B[DecisionCandidate]
    B --> C[Normalize]
    C --> D[Validate]
    D -->|Incomplete or ambiguous| E[DecisionCandidateRefusalArtifact]
    D -->|Valid and complete| F[ExecutionIntent]
    E --> G[Reviewer Evidence Packet]
    F --> H[Bind Adjudication]

If the candidate is incomplete, ambiguous, missing required authority or human approval context, or relies only on natural-language rationale, it is not promoted to ExecutionIntent. It may instead become a DecisionCandidateRefusalArtifact, which records why the candidate was refused or sent to human review.

This artifact is pre-ExecutionIntent reviewer evidence. It is not a BindReceipt, does not imply execution was attempted, and does not perform live LLM extraction, live authority-source validation, or bind adjudication. It is not legal advice, regulatory approval, third-party certification, or a claim of live IAM, IdP, SaaS, bank, sanctions, or customer-system integration.

Evaluation Governance reviewer artifacts

VERITAS includes a reviewer-facing Evaluation Governance artifact chain for inspecting how authority, evaluator definition, evaluation receipts, outcome deltas, evaluator drift, trajectory movement, and legitimacy-impacting changes can be represented for external review.

These artifacts are non-enforcing in v1. They do not change /v1/decide, do not automatically establish legitimacy, and do not certify regulatory compliance. They are intended to make architecture-hardening evidence explicit, versioned, challengeable, and auditable.

Evaluation Governance overview: docs/en/architecture/evaluation-governance-overview-v1.md
Evaluation Governance reviewer demo quickstart: docs/en/demo/evaluation-governance-reviewer-demo-quickstart-v1.md
Evaluation Function Governance v1
Evaluation Receipt v1
Outcome Delta Attribution v1
Evaluation Drift Detection v1
Trajectory-Level Admissibility Monitor v1
Legitimacy Impact Review v1
Adversarial Architecture Test Matrix v1
Adversarial Scenario Fixtures v1
Reviewer Evidence Packet v1
Reviewer Evidence Packet example with Evaluation Governance attachments

Authority Evidence Ingestion

VERITAS now includes a deterministic local/offline Authority Evidence ingestion adapter for bind-time governance. It normalizes external-style or mock authority facts into the existing AuthorityEvidence artifact model, computes a deterministic evidence hash, and preserves fail-closed behavior for missing, invalid, expired, stale, or indeterminate authority evidence.

The adapter also validates that requested scopes are granted by AuthorityEvidence.scope_grants and not blocked by AuthorityEvidence.scope_limitations before runtime authority can pass. This helps demonstrate how external authority facts can enter VERITAS without treating fixture/mock evidence as live production integration.

Implementation: veritas_os/governance/authority_evidence_ingestion.py
Architecture note: docs/en/architecture/authority-evidence-ingestion.md
Focused tests: tests/governance/test_authority_evidence_ingestion.py

Boundary:

Local/offline normalization only
No live SaaS, bank, sanctions, identity-provider, or customer-system integration
Not legal advice, regulatory approval, third-party certification, or production authority-source validation

Human Approval Receipt v1

VERITAS now includes a local/offline Human Approval Receipt v1 artifact. It represents human approval as a deterministic, hashable, scope-bound, expiry-aware governance artifact. Dev/test local workflows may convert receipts into compatibility human_approval_state dictionaries for demos, fixtures, and migration, but secure/prod posture requires an explicit HumanApprovalReceipt object with verifier-derived provenance, a signed approval artifact plus production verifier, or a sealed verified proof when human approval is needed. TestHumanApprovalSignatureVerifier is blocked in secure/prod; production deployments must provide their own verifier bound to KMS/HSM or trusted public-key infrastructure. The approval_validation_hash is tamper-evident metadata, not a substitute for cryptographic receipt verification. This does not add live IdP, SSO, IAM, KMS/HSM, e-signature, or production approval workflow integration.

Boundary:

Local/offline deterministic artifact only
No live IdP, SSO, IAM, KMS/HSM, or e-signature integration
Not legal advice, regulatory approval, third-party certification, or production approval validation

Outcome Receipt v1

VERITAS includes a local/offline Outcome Receipt v1 artifact that records post-execution outcome evidence for governed execution attempts. It captures final outcome, commit/block/rollback status, postcondition status, state fingerprints, observed effects, and deterministic outcome hashing. This is a local/offline evidence artifact, not proof of live production execution.

SaaS Permission-Change Governed Execution Demo

VERITAS includes a local/offline SaaS permission-change governed execution demo where an AI agent attempts to grant admin access to an external contractor. The demo shows AuthorityEvidence and HumanApprovalReceipt checks before commit, with missing/expired/scope-mismatched evidence failing closed.

Demo walkthrough: docs/en/demo/saas-permission-change-governed-demo.md
Script: scripts/demo/saas_permission_change_governed_demo.py
Test: tests/demo/test_saas_permission_change_governed_demo.py

Boundary:

Local/offline fixture only
No live SaaS, IAM, IdP, SSO, customer directory, or production approval workflow integration
Not legal advice, regulatory approval, third-party certification, or production access-control validation

Reviewer Evidence Packet v1

VERITAS includes a local/offline Reviewer Evidence Packet v1 export for the SaaS permission-change governed execution demo. It packages case outcomes, AuthorityEvidence/HumanApproval summaries, OutcomeReceipt summaries, EvidenceChainManifest summaries, EvidenceChainVerification summaries, aggregate counts, reviewer notes, and a deterministic packet hash into one JSON-friendly artifact. This is a local/offline review packet, not proof of live production deployment or audit certification.

Documentation: docs/en/demo/reviewer-evidence-packet.md
External Reviewer Quickstart: docs/en/demo/external-reviewer-quickstart.md
External Reviewer Artifact Index: docs/en/demo/external-reviewer-artifact-index.md
Validation report: docs/en/demo/reviewer-evidence-packet-validation-report.md
Bundle docs: docs/en/demo/reviewer-evidence-bundle.md
Script: scripts/demo/export_reviewer_evidence_packet.py
Validator script: scripts/demo/validate_reviewer_evidence_packet.py
Local bundle builder: scripts/demo/build_reviewer_evidence_bundle.py
CI gate: .github/workflows/reviewer-evidence-packet-validation.yml
CI artifacts: reviewer-evidence-packet-validation-artifacts
CI artifact manifest: reviewer-evidence-artifact-manifest.json
CI artifact manifest verifier: scripts/demo/verify_reviewer_evidence_artifact_manifest.py
Golden fixture: docs/en/demo/fixtures/reviewer-evidence-packet-saas-permission-change-v1.json
Schema: docs/en/demo/schemas/reviewer-evidence-packet-v1.schema.json
Test: tests/demo/test_reviewer_evidence_packet.py

A deterministic golden fixture is also checked in so reviewers can inspect the generated packet without running the exporter. A JSON Schema is checked in for Reviewer Evidence Packet v1 so reviewers can inspect the packet contract and CI can detect unintended shape changes. CI tests verify that the generated packet matches the fixture.

A local/offline validation report is also available. It verifies that the generated packet matches the golden fixture, recomputes the packet hash, validates the packet shape against the JSON Schema when possible, checks deterministic case expectations, and emits a reviewer-facing pass/fail JSON report.

A dedicated CI gate runs the Reviewer Evidence Packet validation report so the reviewer-facing packet, fixture, schema/fallback validation, case expectations, and evidence-chain verification summaries are continuously checked.

The Reviewer Evidence Packet Validation workflow also uploads reviewer evidence artifacts, including the generated validation report, generated packet, golden fixture, and schema, so reviewers can inspect the exact CI-produced outputs. The uploaded CI artifact also includes reviewer-evidence-artifact-manifest.json, a deterministic manifest listing each uploaded reviewer artifact, its role, source, sha256 hash, and size. The CI workflow also verifies reviewer-evidence-artifact-manifest.json before upload by recomputing the manifest hash, file hashes, and file sizes against the actual artifact directory.

Reviewers can also reproduce the CI reviewer evidence artifact locally with the Reviewer Evidence Bundle builder. It generates the validation report, generated packet, fixture copy, schema copy, artifact manifest, manifest verification report, and step summary into one local directory.

Bind Coverage Registry v1

VERITAS includes a local/offline Bind Coverage Registry v1 that records which effect-bearing operations are expected to be governed by bind-time controls. The registry helps reviewers inspect whether high-impact actions require bind governance, AuthorityEvidence, HumanApprovalReceipt, policy snapshots, and fail-closed behavior. It is a deterministic coverage artifact, not a live route scanner or proof of production deployment.

Evidence Chain Manifest v1

VERITAS includes a local/offline Evidence Chain Manifest v1 artifact that links AuthorityEvidence, HumanApprovalReceipt, bind-time decision evidence, OutcomeReceipt, and operation coverage metadata for a governed execution attempt. It helps reviewers inspect a complete evidence chain from pre-execution authority and approval through bind-time decisioning to post-execution outcome evidence. This is a local/offline manifest, not proof of live production execution.

VERITAS includes a local/offline Evidence Chain Verifier v1 that checks whether an EvidenceChainManifest matches the supplied governance artifacts. It recomputes or reads deterministic artifact hashes and reports verified, missing, mismatched, or indeterminate links. This is a local/offline verifier, not proof of live production audit certification.

One-Day PoC Evidence Packet

For external reviewers, HPAN, enterprise stakeholders, and investor diligence, use the one-day PoC smoke script to generate a sanitized evidence packet from a running VERITAS API server.

One-Day PoC Evidence Pack / Checklist: reviewer-facing checklist and success/failure criteria (distinct from generated evidence packet output) — docs/en/poc/one-day-poc-evidence-pack.md
One-Day PoC Operator Runbook: docs/en/poc/one-day-poc-operator-runbook.md
One-Day PoC Reviewer Handoff Template: docs/en/poc/one-day-poc-reviewer-handoff-template.md

Prerequisites:

VERITAS API server is running.
VERITAS_API_KEY is set.
The API key maps to a role that includes governance_read (for example auditor or admin).

Run:

VERITAS_API_KEY=... python scripts/demo/one_day_poc_smoke.py \
  --json \
  --evidence-json /tmp/veritas_poc_evidence.json \
  --evidence-md /tmp/veritas_poc_evidence.md

Outputs:

JSON evidence packet
Markdown evidence packet
With --json, stdout contains only the JSON summary; status messages are written to stderr.

Security boundaries:

API keys are not written into evidence files.
Raw exporter endpoint URLs are not written.
Raw environment values are not written.
Raw request/response bodies are not copied.
Tokens, cookies, passwords, secrets, and authorization headers are not included.

Limitations:

Not production certification.
Jaeger/Grafana/OTLP deployment is not included.
Cryptographic human-approval signatures are not included.
Final enterprise SLA/certification is not included.

See full walkthroughs:

Maintainer handoff and support-continuity guidance is documented in Maintainer Handoff and Support Continuity Runbook. This runbook reduces handoff friction but does not claim to eliminate bus-factor risk or provide a staffed support organization/SLA.

Maintainer handoff / support continuity の日本語補助説明は Maintainer Handoff（日本語補助）にあります。

For lightweight local performance measurements, run python scripts/demo/one_day_poc_benchmark.py and see the performance report docs above.

Performance Metrics and One-Day PoC benchmark artifacts are local/reviewer-facing measurements only. They are not a production SLA, third-party certification, or customer environment measurements.

Performance Metrics: docs/en/benchmarks/performance-metrics.md / docs/ja/benchmarks/performance-metrics.md
Latest Local Performance Metrics Artifact: docs/en/benchmarks/local-performance-metrics.latest.md / docs/en/benchmarks/local-performance-metrics.latest.json

Sample sanitized evidence packets are available for reviewers who want to preview the deliverable format before running the smoke script. Evidence JSON follows schemas/poc/one_day_poc_evidence.v1.schema.json. To print the repo-local schema path: python scripts/demo/one_day_poc_smoke.py --print-schema-path. To validate a generated evidence packet offline: python scripts/demo/one_day_poc_smoke.py --validate-evidence /tmp/veritas_poc_evidence.json. CLI validation is a lightweight stdlib contract check aligned with the v1 schema; it does not add a jsonschema dependency. The generated_at field uses fixed UTC Z format: YYYY-MM-DDTHH:MM:SSZ. To generate and self-validate JSON evidence in one run, add --validate-generated-evidence together with --evidence-json.

AML/KYC Reviewer Walkthrough Quickstart

VERITAS now includes a deterministic AML/KYC reviewer walkthrough for external reviewers, enterprise stakeholders, and investors who need to verify value in under 10 minutes.

Open:

/?demo_scenario=aml_kyc_reviewer_walkthrough

What to verify:

Authority Evidence: missing
Bind result: block
Safe audit link is available
Evidence bundle summary is visible
Source-state remains fixture/demo, not live

What this demonstrates:

AI agent attempts a regulated AML/KYC action
Required Authority Evidence is missing
VERITAS blocks before commit at the Bind Boundary
The path remains reviewable through deterministic audit trace

Separately, the Authority Evidence ingestion adapter shows how external-style authority facts can be normalized into bind-time AuthorityEvidence artifacts for fail-closed validation.

Boundary (important):

Fixture/demo only
Not legal advice
Not regulatory approval
Not third-party certification
Not connected to real bank systems, sanctions APIs, or customer data

Related reviewer docs:

Governance Review Workflow

VERITAS OS does not only record governance artifacts. It connects them into a Mission Control → Audit review workflow:

flowchart LR
  A[Mission Control<br/>Live governance snapshot] --> B[Governance artifacts panel<br/>pre-bind source / bind reason / target metadata / check results]
  B --> C[Safe operator actions<br/>internal /audit?... links]
  C --> D[Audit<br/>query validation]
  D --> E{Supported artifact}
  E -->|decision_id| F[Auto-load latest logs<br/>focus matching timeline item]
  E -->|bind_receipt_id| G[Dedicated bind receipt lookup<br/>fallback detail]
  E -->|execution_intent_id| I[Auto-load latest logs<br/>timeline focus or unavailable]
  E -->|invalid or unsafe| H[Reject<br/>no fake route]

Mission Control receives a live governance snapshot from /v1/governance/live-snapshot.
The UI surfaces governance artifact metadata, including pre-bind source, bind reason, target metadata, check results, and safe operator actions.
Operator actions provide safe internal /audit?... links for supported artifacts (bind_receipt_id, decision_id, execution_intent_id).
Audit consumes supported query parameters and applies query validation before lookup/navigation.
Decision traces auto-load latest logs and focus matching timeline artifacts when available, with direct lookup fallback when timeline data does not contain the decision.
Bind receipt traces use dedicated lookup and render fallback detail when timeline items do not contain the target receipt.
Unsafe links, external/protocol URLs, malformed hrefs, and fake routes are not generated.

Local workflow check:

bash scripts/demo_mission_audit_workflow.sh

A successful run should complete the focused checks for Mission Control actions, Audit page tracing, Audit hook behavior, and safe link validation:

Running VERITAS Mission Control → Audit workflow demo checks...
✓ Mission Control artifact actions
✓ Audit page decision / bind receipt tracing
✓ Audit hook query workflow
✓ Governance link safety validation
Mission Control → Audit workflow demo checks completed.

Development-time Observe Mode

VERITAS distinguishes production enforcement from development observation. Production governance remains fail-closed. Observe Mode support is a foundation semantics (default off) for development/test/sandbox contexts that records would_have_blocked outcomes without hiding violations. See docs/governance/observe_mode.md.

Covered by focused frontend tests:

frontend/components/mission-page.test.tsx
frontend/app/audit/page.test.tsx
frontend/app/audit/hooks/useAuditData.test.ts
frontend/lib/governance-link-utils.test.ts

See docs/ui/README_UI.md for implementation details.

Version

Version: 2.0.0
Release Status: Beta
Author: Takeshi Fujishita

What VERITAS OS is

VERITAS OS is a Decision Governance and Bind-Boundary Control Plane for AI Agents. It is the governance layer from decision adjudication through bind-time boundary checks: it determines whether an AI decision may proceed and whether an approved decision can be committed, blocked, escalated, rolled back, or fail safely at bind time before real-world effect. It now also exposes an additive pre-bind schema surface for participation admissibility signals without changing the existing bind-time commitment contract.

What problem it solves

In enterprise and regulated environments, the key failure mode is often not model intelligence but uncontrolled execution. VERITAS addresses this by making decisions:

Reviewable before action
Traceable to evidence and policy context
Replayable with divergence awareness
Auditable through tamper-evident artifacts
Enforceable through fail-closed policy and safety gates

Why bind-boundary control matters

Decision approval alone is not commitment. VERITAS keeps this boundary explicit by carrying governance lineage from decision adjudication into bind-time control, so operators can verify whether an approved decision was committed, blocked, escalated, rolled back, or failed safely before real-world effect.

How it differs from runtime/orchestration tools

Many agent stacks optimize task execution and tool wiring. VERITAS OS focuses on decision governance and bind-boundary control:

Governance controls are applied before real-world effect.
FUJI gate behavior is fail-closed by default on unsafe/undefined paths.
TrustLog + governance identity create audit-grade decision lineage.
Mission Control + governance APIs provide an operator-facing governance surface with bind-phase outcomes, bind receipts, and compact bind summaries, not only developer telemetry.
/v1/decide now follows a shared operator-facing contract pattern: *_operator_summary is minimal-by-default, while *_operator_detail is only emitted when operator_verbosity=expanded and role policy permits.

Why this fits regulated / enterprise use

Explicit approval boundaries and policy enforcement points
Evidence capture and replay pathways for post-incident review
Signed and hash-linked governance artifacts for accountability
Posture-based secure/prod startup checks to reduce permissive misconfiguration

This opening reflects current implemented fact: bind-governed adjudication is already active on at least five operator-governed effect paths, while broader effect-path coverage remains roadmap direction.

VERITAS OS includes a Regulated Action Governance Kernel for selected AI-agent action paths. It uses Action Class Contracts, Authority Evidence, Runtime Authority Validation, Admissibility Predicates, and Irreversible Commit Boundary checks to determine whether an execution intent should commit, block, escalate, or refuse at the bind boundary, including an AML/KYC customer risk escalation fixture path.

Audit Log records what happened. Authority Evidence records why an action was authorized and admissible at bind time; audit log records alone do not authorize commit.

This is not legal advice, not regulatory approval, not third-party certification, or a claim of compliance by itself. VERITAS helps produce inspectable audit/control evidence for EU AI Act-aligned workflows and is not legal certification, a conformity assessment, an EU Declaration of Conformity, CE marking, or notified-body/regulatory approval.

External reviewers can start from the Regulated Action Governance External Review Handoff Pack, which links the implemented AML/KYC action path, evidence artifacts, quality gate, and known limitations. External reviewers can use the Regulated Action Governance External Reviewer Feedback Template to record review scope, assessment criteria, findings, evidence requests, and recommendations.

What VERITAS OS is / is not

Is: a Decision Governance and Bind-Boundary Control Plane for AI agents, covering decision governance and bind-boundary governance before real-world effect.
Is not: a replacement for all agent runtimes, nor only an orchestration convenience wrapper.

Fact vs roadmap (read this first)

Current fact (beta): Core decision pipeline, bind artifact lineage (decision -> execution_intent -> bind_receipt), bind-time admissibility checks, FUJI fail-closed gating, TrustLog lineage, Mission Control workflows, and governance endpoints are implemented.
Current fact (bind policy surface): Bind-boundary adjudication is currently wired on at least five operator-governed effect paths:
1. PUT /v1/governance/policy (governance policy update path),
2. POST /v1/governance/policy-bundles/promote (policy bundle promotion path), and
3. PUT /v1/compliance/config (runtime compliance config mutation path), and
4. POST /v1/system/halt (operator emergency halt mutation path), and
5. POST /v1/system/resume (operator system resume mutation path).
Current fact (bind outcome public contract): Governance bind responses expose legacy flat bind fields (bind_outcome, bind_failure_reason, bind_reason_code, execution_intent_id, bind_receipt_id) and additive bind_summary objects as a shared compact bind vocabulary.
Current fact (bind coverage registry): VERITAS maintains a tested bind coverage registry for API effect paths. Effect-bearing routes must be classified as bind_governed or explicitly documented as audited_exemption with reason/risk metadata, reducing the risk that recorded decisions are treated as execution permission without a binding artifact.
Current fact (bind artifact family): BindReceipt is persisted as a full governance artifact and carries canonical target metadata as part of the artifact contract.
Current fact (pre-bind participation schema): /v1/decide supports an optional additive participation_signal object as an upstream signal family (participation_signal -> decision -> execution_intent -> bind_receipt) for participation admissibility; bind-time commitment admissibility remains unchanged.
Current fact (pre-bind structural detection): /v1/decide can emit optional additive pre_bind_detection_summary / pre_bind_detection_detail fields that classify structural participation state (informative|participatory|decision_shaping) from the participation signal family; this is upstream-only and does not change bind-time governance.
Current fact (pre-bind preservation layer): /v1/decide can emit optional additive pre_bind_preservation_summary / pre_bind_preservation_detail fields that classify governability-preservation state (open|degrading|collapsed) and intervention viability; this is distinct from detection and does not replace bind-time governance.
Current fact (covered transition-path refusal): On the covered /v1/decide transition path, lineage promotability now prevents non-promotable pre-bind formation lineage from constructing an ExecutionIntent, with additive transition_refusal diagnostics.
Current fact (transition/actionability consistency): On the covered /v1/decide path, formation transition refusal also normalizes actionability so structurally refused lineage is not presented as actionable after bind.
Current fact (operator recovery normalization): On the covered /v1/decide path, formation transition refusal now normalizes operator recovery semantics to HOLD and RECONSTRUCT_FROM_ELIGIBLE_FORMATION_LINEAGE.
Current fact (completed pre-bind formation refusal operator flow): On the covered /v1/decide path, non-promotable pre-bind formation lineage is structurally refused before ExecutionIntent construction. The response withholds ExecutionIntent / BindReceipt fields, normalizes actionability to formation_transition_refused, sets operator recovery to RECONSTRUCT_FROM_ELIGIBLE_FORMATION_LINEAGE, and the Console displays this as pre-bind formation refusal rather than bind failure.
Current fact (OpenAPI parity): openapi.yaml now explicitly declares the additive /v1/decide pre-bind surfaces (participation_signal, pre_bind_detection_summary/detail, pre_bind_preservation_summary/detail) as optional fields, aligned with runtime and architecture vocabulary.
Current fact (replay/operator flow): Operator surfaces expose bind artifacts via list/export/detail endpoints (/v1/governance/bind-receipts, /v1/governance/bind-receipts/export, /v1/governance/bind-receipts/{bind_receipt_id}), with mutation/export responses reusing bind_summary for triage and audit workflows.
Current fact (boundary): Production readiness still depends on environment-specific hardening, integration, and operational controls.
Roadmap / future direction: Bind-boundary policy surface is expected to expand to more effect paths and become a broader standardization framework for multi-path effect governance; this is direction, not a claim of full completion today.
Roadmap: Expanded enterprise integrations (for example deeper IdP/JWT scope models and broader distributed failure-mode validation).

Regulated action governance fact (implemented)

Action Class Contract
AML/KYC Customer Risk Escalation contract
Authority Evidence artifact
Runtime Authority Validation
Admissibility Predicate evaluation
Commit Boundary Evaluator
BindReceipt / BindSummary regulated-action fields
AML/KYC deterministic regulated action path
Mission Control / Bind Cockpit regulated action display
Proof Pack / Quality Gate docs

Regulated action governance roadmap (not yet implemented)

Real external authority source integration
Real bank / sanctions / compliance system integration
Third-party review
Broader regulated action-class coverage
Production customer workflow validation

Technical Maturity Snapshot (internal)

This is a self-assessment / internal re-evaluation summary (not third-party certification), published as a conservative internal snapshot.

Latest internal re-evaluation date: 2026-04-15
Internal overall snapshot: 85 / 100 (from 82 on 2026-03-15)
Full internal table, change log, and residual risks: docs/en/positioning/public-positioning.md

Quick Links

AML/KYC Beachhead (1-day PoC quickstart): docs/en/guides/poc-pack-financial-quickstart.md
AML/KYC Governance Template Contract: docs/en/guides/financial-governance-templates.md
External Audit / Evidence Bundle Readiness: docs/en/validation/external-audit-readiness.md
Evidence Bundle Signature Verification Demo: docs/en/validation/evidence-bundle-signature-verification.md
Reviewer Key Provenance Walkthrough: docs/en/validation/reviewer-key-provenance-walkthrough.md
External Technical Proof Pack (review/pilot/DD/audit): docs/en/validation/technical-proof-pack.md
Third-Party Review Readiness (compact index): docs/en/validation/third-party-review-readiness.md
Current Implementation Matrix (external reviewer snapshot): docs/en/validation/current-implementation-matrix.md
AML/KYC Short Positioning (customer / operator / investor): docs/en/positioning/aml-kyc-beachhead-short-positioning.md
Official Website: https://veritas-website-navy.vercel.app/
GitHub: https://github.com/veritasfuji-japan/veritas_os
Zenodo paper (EN): https://doi.org/10.5281/zenodo.17838349
Zenodo paper (JP): https://doi.org/10.5281/zenodo.17838456
Japanese README: README_JP.md
User Manual (JP): docs/ja/guides/user-manual.md
Contributing: CONTRIBUTING.md
Security Policy: SECURITY.md
Documentation Index: docs/INDEX.md
PostgreSQL Production Guide: docs/en/operations/postgresql-production-guide.md
PostgreSQL Drill Runbook: docs/en/operations/postgresql-drill-runbook.md
Security Hardening: docs/en/operations/security-hardening.md
External Security Review Remediation Summary: docs/en/security/external-security-remediation-summary.md / docs/ja/security/external-security-remediation-summary.md
Database Migrations: docs/en/operations/database-migrations.md
Backend Parity Coverage: docs/en/validation/backend-parity-coverage.md
PostgreSQL Production Proof Map (compact): docs/en/validation/postgresql-production-proof-map.md
Release Gate Recovery Case Study — a real failure-to-green example showing how VERITAS OS blocks release promotion until governance backend, Docker runtime, and test isolation failures are fixed.
Live PostgreSQL Validation Evidence: docs/live-postgresql-validation.md
Legacy Path Cleanup: docs/en/operations/legacy-path-cleanup.md
Review Document Map: docs/ja/reviews/code-review-document-map.md
Documentation Hub (EN): docs/en/README.md
Documentation Hub (JA): docs/ja/README.md
Public Positioning Guide (EN): docs/en/positioning/public-positioning.md
Public Positioning Guide (JA): docs/ja/positioning/public-positioning.md
Decision Semantics Contract: docs/en/architecture/decision-semantics.md
Bind-Boundary Governance Artifacts: docs/en/architecture/bind-boundary-governance-artifacts.md
Bind-Time Admissibility Evaluator: docs/en/architecture/bind_time_admissibility_evaluator.md
Pre-Bind Participation Signals: docs/en/architecture/pre-bind-participation-signals.md
Pre-Bind Canonical Proof Cases: docs/en/proofs/pre_bind_canonical_cases_proof.md
Pre-Boundary Collapse Demo: docs/en/demos/pre_boundary_collapse_demo.md
- Intervention Actionability Map v0 now has a schema and golden fixture contract. The contract keeps marker-to-intervention guidance deterministic, inspectable, and explicitly non-enforcement.
- Intervention Actionability Map schema: docs/en/demo/schemas/intervention-actionability-map-v0.schema.json
- Intervention Actionability Map fixture: docs/en/demo/fixtures/intervention-actionability-map-v0.json
- Governance Evidence Packet v0 now has a reviewer-ready contract that keeps the deterministic representative reviewer packet structurally stable and explicitly limited to non-certifying review guidance.
- Governance Evidence Packet schema: docs/en/demo/schemas/governance-evidence-packet-v0.schema.json
- Governance Evidence Packet fixture: docs/en/demo/fixtures/governance-evidence-packet-v0.json
- Governance Evidence Packet contract test: frontend/app/api/veritas/v1/report/governance/governance-evidence-packet-contract.test.ts
- Non-claims: not certification; not production security guarantee; not automatic enforcement; not scoring model; not legal conclusion.
- VERITAS also documents Governance Recognizability Conditions v0, clarifying that visibility conditions can become a governance function when reviewers must later recognize maneuverability contraction despite procedural admissibility.
- VERITAS also documents Reviewer-Facing Visibility Roadmap v0, a docs-only roadmap for distinguishing procedural admissibility evidence, maneuverability contraction evidence, and recognizability evidence before any future packet expansion.
Mini proof: covered /v1/decide pre-bind formation refusal: docs/en/validation/pre-bind-formation-refusal-mini-proof.md
Regulated Action Governance Kernel: docs/en/architecture/regulated-action-governance-kernel.md
Authority Evidence vs Audit Log: docs/en/architecture/authority-evidence-vs-audit-log.md
AML/KYC Regulated Action Path (Use Case): docs/en/use-cases/aml-kyc-regulated-action-path.md
Regulated Action Governance Proof Pack: docs/en/validation/regulated-action-governance-proof-pack.md
Regulated Action Governance Quality Gate: docs/en/validation/regulated-action-governance-quality-gate.md
Regulated Action Governance External Review Handoff Pack: docs/en/validation/external-review-handoff-regulated-action-governance.md
Regulated Action Governance External Reviewer Feedback Template: docs/en/validation/external-reviewer-feedback-template-regulated-action-governance.md
Required Evidence Taxonomy v0: docs/en/governance/required-evidence-taxonomy.md
AML/KYC contract hardening (canonical gate + evidence profile): docs/en/guides/financial-governance-templates.md
Documentation Map: docs/DOCUMENTATION_MAP.md
Operations Runbook: docs/ja/operations/enterprise_slo_sli_runbook_ja.md
Governance Signing Runbook: docs/en/operations/governance-artifact-signing.md
Governance Upgrade Press Summary: docs/press/governance_control_plane_upgrade_2026-04.md

AML/KYC Beachhead PoC Pack (what you can run in 1 day)

For regulated teams evaluating VERITAS OS in AML/KYC workflows, the beachhead pack is documented as an executable path, not only positioning text:

Run the 1-day PoC fixture set and quantify pass/fail/warning outcomes.
Review operator checkpoints (fail-closed gate, evidence-first deltas, replay consistency).
Produce evidence-bundle handoff artifacts for external review readiness.

Start here:

1-day PoC Quickstart
Deterministic fixture scenario: scripts/run_aml_kyc_poc_fixture.py with veritas_os/sample_data/governance/aml_kyc_poc_pack/
Financial Governance Templates
External Audit Readiness
Short Positioning by audience

🚀 Quick Start (TL;DR)

# Clone & start with Docker Compose (recommended)
git clone https://github.com/veritasfuji-japan/veritas_os.git
cd veritas_os
cp .env.example .env        # Edit: set OPENAI_API_KEY, VERITAS_API_KEY, VERITAS_API_SECRET
docker compose up --build

# Backend: http://localhost:8000 (Swagger UI: /docs)
# Frontend: http://localhost:3000 (Mission Control)
# PostgreSQL: localhost:5432 (auto-configured as default storage backend)

Docker Compose defaults to PostgreSQL for both Memory and TrustLog backends. Verify with: curl -s http://localhost:8000/health | python3 -c "import json,sys; print(json.load(sys.stdin)['storage_backends'])"

To use lightweight file-based backends instead, set in your .env:
VERITAS_MEMORY_BACKEND=json
VERITAS_TRUSTLOG_BACKEND=jsonl

Prerequisites: Docker 20+ and Docker Compose v2. For local dev: Python 3.11+, Node.js 20+, pnpm.

PostgreSQL Production Path & Validation Status

For this repository, PostgreSQL backend is the formal production path for both MemoryOS and TrustLog. JSON/JSONL backends remain available for local lightweight development and migration workflows, not as the recommended production baseline.

Default in Docker Compose: VERITAS_MEMORY_BACKEND=postgresql and VERITAS_TRUSTLOG_BACKEND=postgresql are set in docker-compose.yml.
Runtime verification point: check /health → storage_backends to confirm the active backend at runtime.
Live PostgreSQL validation exists in multiple layers: CI smoke (pytest -m smoke), production-like validation (pytest -m "production or smoke"), and live validation entry points (make validate-postgresql-live, make validate-live, workflow production-validation.yml).

Verification-oriented docs:

Guarantee boundary (current)

Guaranteed: PostgreSQL is the documented production path, Docker Compose defaults to PostgreSQL, backend parity expectations are documented, and production validation documentation includes continuous/live validation paths.
Not guaranteed yet: this README section alone does not guarantee environment-specific HA/DR posture, cloud-managed service configuration correctness, or operator runbook execution quality in your target production environment.

Beta at a Glance
Why VERITAS?
What It Does
Quick Start
Project Structure
Frontend — Mission Control Dashboard
API Overview
Docker Compose (Full Stack)
Docker (Backend Only)
Architecture (High-Level)
TrustLog (Hash-Chained Audit Log)
Continuation Runtime
Tests
Environment Variables Reference
Security Notes (Important)
Roadmap (Near-Term)
License
Contributing
Citation (BibTeX)

📊 Beta at a Glance

Area	Current beta posture
Core decision path	End-to-end `/v1/decide` pipeline is implemented with orchestration, gating, persistence, and replay hooks.
Governance	Policy updates, approval workflow, audit trail, and compliance export paths are already first-class.
Frontend	Mission Control is feature-rich enough for operator workflows, not just a demo shell.
Safety stance	Fail-closed behavior is preferred over permissive fallback across FUJI-, replay-, and TrustLog-adjacent flows.
Deployment expectation	Suitable for evaluation, staging, internal pilots, and guarded beta programs; production use still requires environment-specific hardening and operational review.

What "beta" means here

The architecture is broad and already integrated across backend, frontend, replay, governance, and compliance surfaces.
The project is not positioned as an alpha prototype anymore; it already contains substantial operational and audit infrastructure.
You should still expect active iteration in policy packs, deployment defaults, and environment-specific integrations.

🔒 Runtime Posture Guarantees

VERITAS OS uses a single runtime posture (VERITAS_POSTURE) to control governance-critical defaults. Set it once; every safety flag derives from it.

Posture	Governance controls	Startup behaviour	Escape hatches
dev (default)	All off unless explicitly enabled	Relaxed — warnings only	N/A
staging	All off unless explicitly enabled	Relaxed — warnings only	N/A
secure	All on by default	Fail-closed — refuses on missing integrations	`VERITAS_POSTURE_OVERRIDE_*` accepted
prod	All on, no exceptions	Fail-closed — refuses on missing integrations	Overrides are ignored

Controls governed by posture

Control	Env var (explicit override)	What it enforces
Policy runtime enforcement	`VERITAS_POLICY_RUNTIME_ENFORCE`	Compiled policy deny/halt/escalate/require_human_review decisions enforced in pipeline
External secret manager	`VERITAS_ENFORCE_EXTERNAL_SECRET_MANAGER`	Require Vault/KMS/cloud secret manager at startup
Transparency log anchoring	`VERITAS_TRUSTLOG_TRANSPARENCY_REQUIRED`	TrustLog writes fail when transparency anchor is missing
WORM hard-fail	`VERITAS_TRUSTLOG_WORM_HARD_FAIL`	TrustLog writes fail when WORM mirror write fails
Strict replay	`VERITAS_REPLAY_STRICT`	Critical replay divergences abort
Governance artifact signatures	`VERITAS_POLICY_VERIFY_KEY` (+ posture strictness)	In secure/prod, reject unsigned or non-Ed25519 governance policy bundles

Governance artifact identity in decision outputs

When compiled policy governance is active, /v1/decide responses include governance_identity with:

policy_version
digest (compiled bundle semantic hash)
signature_verified
signer_id (if bundle metadata provides signing.key_id)
verified_at

This identity is threaded into decision, replay, and audit artifacts so that operators can prove which governance control-plane asset was in force.

What causes startup refusal (secure/prod)

The startup validator uses a capability-aware model. Rather than checking vendor names directly, it verifies that each configured backend declares the security capabilities required by the posture. Startup will refuse with an actionable error when any required capability is missing:

Required capability	What it means	Current implementation
`managed_signing`	Signing key material held in a managed HSM/KMS	`aws_kms` signer backend
`immutable_retention`	Tamper-proof, append-only retention enforced by storage service	`s3_object_lock` mirror backend
`transparency_anchoring`	Verifiable proof-of-existence anchor (when required)	`local` / `tsa` anchor backends
`fail_closed`	Errors result in hard refusal, never silent pass	All secure/prod backends

Additionally, startup refuses when:

VERITAS_SECRET_PROVIDER is not set (external secret manager enforcement)
VERITAS_API_SECRET_REF is not set (external secret manager enforcement)
Backend-specific configuration is incomplete (e.g. missing VERITAS_TRUSTLOG_KMS_KEY_ID for aws_kms, missing S3 bucket/prefix for s3_object_lock)

TrustLog strict mirror capabilities in secure/prod

In secure/prod posture, TrustLog startup validation fails closed unless the selected mirror backend advertises both immutable_retention and fail_closed. The current production-supported backend satisfying this strict capability set is s3_object_lock, configured with VERITAS_TRUSTLOG_MIRROR_BACKEND=s3_object_lock, VERITAS_TRUSTLOG_S3_BUCKET, and VERITAS_TRUSTLOG_S3_PREFIX (plus VERITAS_TRUSTLOG_S3_OBJECT_LOCK_MODE and VERITAS_TRUSTLOG_S3_RETENTION_DAYS according to the deployment retention policy). Local WORM mirror is not secure/prod compliant in this release. Production-like postures require a backend that actually provides and advertises the full strict capability set (immutable_retention and fail_closed). The current production-supported backend is s3_object_lock.

Note: In prod posture, VERITAS_TRUSTLOG_ALLOW_INSECURE_SIGNER_IN_PROD is unconditionally ignored — there is no break-glass for insecure signers in production. In secure posture this override remains available as an unsupported emergency escape hatch.

Escape hatches (secure posture only)

In secure posture, individual controls may be disabled for pre-production testing:

VERITAS_POSTURE_OVERRIDE_POLICY_ENFORCE=0
VERITAS_POSTURE_OVERRIDE_EXTERNAL_SECRET_MGR=0
VERITAS_POSTURE_OVERRIDE_TRUSTLOG_TRANSPARENCY=0
VERITAS_POSTURE_OVERRIDE_TRUSTLOG_WORM=0
VERITAS_POSTURE_OVERRIDE_REPLAY_STRICT=0

These overrides are silently ignored in prod posture.

🎯 Why VERITAS?

Most "agent frameworks" optimize autonomy and tool use. VERITAS optimizes for governance:

Fail-closed safety & compliance enforced by a final gate (FUJI Gate) with PII detection, harmful content blocking, prompt injection defense, toxicity filtering for web search results, and policy-driven rules — all safety paths return rejected / risk=1.0 on exception (fail-closed)
High-fidelity reproducible decision pipeline (17 traced stages, structured outputs, replay with divergence detection, retrieval snapshot checksum, model version verification)
Auditability via a hash-chained TrustLog (tamper-evident, Ed25519-signed, WORM hard-fail mirror, Transparency log anchor, W3C PROV export)
Enterprise governance — 4-eyes approval for policy changes, RBAC/ABAC access control, SSE real-time governance alerts, external secret manager enforcement
Memory & world state as first-class inputs (MemoryOS with vector search + WorldModel with causal transitions)
Operational visibility via a full-stack Mission Control dashboard (Next.js) with real-time event streaming, risk analytics, and governance policy management
Bind-boundary visibility in Mission Control via bind-phase outcomes (COMMITTED/BLOCKED/ESCALATED/ROLLED_BACK/APPLY_FAILED/SNAPSHOT_FAILED/PRECONDITION_FAILED) with execution intent and bind receipt lineage pointers
EU AI Act-aligned governance support — built-in audit/reporting exports and deployment readiness checks that support compliance workflows

Target users

AI safety / agent researchers
Teams operating LLMs in regulated or high-stakes environments
Governance / compliance teams building "policy-driven" LLM systems

💡 What It Does

`/v1/decide` — Full Decision Loop (Structured JSON)

POST /v1/decide returns a structured decision record.

Key fields (simplified):

Field	Meaning
`chosen`	Selected action + rationale, uncertainty, utility, risk
`alternatives[]`	Other candidate actions
`evidence[]`	Evidence used (MemoryOS / WorldModel / web search)
`critique[]`	Self-critique & weaknesses
`debate[]`	Pro/con/third-party viewpoints
`telos_score`	Alignment score vs ValueCore
`fuji`	FUJI Gate result (allow / modify / rejected)
`gate.decision_status`	Normalized final status (`DecisionStatus`)
`gate_decision`	Public gate outcome (`allow`/`hold`/`deny`/`block`...). `allow` means response generation can proceed, not case approval.
`business_decision`	Case lifecycle status (`APPROVE`/`HOLD`/`REVIEW_REQUIRED`/`DENY`/...)
`next_action`	Recommended next operator/system action (separate from business state)
`required_evidence[]`	Evidence keys required by current policy/risk boundary
`human_review_required`	Explicit human-review requirement flag
`trust_log`	Hash-chained TrustLog entry (`sha256_prev`)
`bind_outcome`	Bind-phase terminal outcome (`COMMITTED` / `BLOCKED` / `ESCALATED` / `ROLLED_BACK` / `APPLY_FAILED` / `SNAPSHOT_FAILED` / `PRECONDITION_FAILED`)
`execution_intent_id`	Lineage pointer to bind attempt context
`bind_receipt_id`	Lineage pointer to TrustLog-linked bind receipt artifact
`bind_failure_reason`	Operator-facing reason when bind-phase is blocked/escalated/rolled back/fails safely
`extras.metrics`	Per-stage latency, memory hits, web hits

Decision output semantics:

FujiGate owns safety/policy gate adjudication and emits gate_decision.
Value Core compares option value and informs business_decision + next_action.
UI must show gate_decision, business_decision, and next_action as different concepts.
allow is gate-level permissive status only; it must not be presented as case approval.
Bind-phase outcomes (COMMITTED/BLOCKED/ESCALATED/ROLLED_BACK/APPLY_FAILED/SNAPSHOT_FAILED/PRECONDITION_FAILED) are a separate adjudication layer from decision-phase approval.
Financial/regulatory governance prompt templates are available as canonical fixtures for regression and demo workflows (veritas_os/sample_data/governance/financial_regulatory_templates.json); see docs/en/guides/financial-governance-templates.md.

Pipeline stages:

Input Normalize → Memory Retrieval → Web Search → Options Normalize
  → Core Execute → Absorb Results → Fallback Alternatives → Model Boost
  → Debate → Critique → FUJI Precheck → ValueCore → Gate Decision
  → Value Learning (EMA) → Compute Metrics → Evidence Hardening
  → Response Assembly → Persist (Audit + Memory + World) → Finalize Evidence
  → Build Replay Snapshot

Bundled subsystems:

Responsibility boundaries that matter

These boundaries are enforced in code and tests, and they are important when extending the system:

Component	Owns	Should not absorb	Recommended extension direction
Planner	Planning structure, action-plan generation, planner-oriented summaries	Kernel orchestration, FUJI policy logic, Memory persistence internals	Planner helpers / planner normalization layers
Kernel	Decision computation, scoring, debate wiring, rationale assembly	API orchestration, persistence, direct governance storage concerns	Kernel stages / QA helpers / contracts
FUJI	Final safety and policy gating, rejection semantics, audit-facing gate status	Memory management, planner branching, general persistence workflows	FUJI policy, safety-head, and helper modules
MemoryOS	Memory storage, retrieval, summarization, lifecycle, security controls	Planner policy, kernel decision policy, FUJI gate logic	Memory store / search / lifecycle / security helpers

This separation is one of the reasons VERITAS is easier to audit and safer to evolve than a single-file "agent loop."

Subsystem	Purpose
MemoryOS	Episodic/semantic/procedural/affective memory with vector search (sentence-transformers), retention classes, legal hold, and PII masking
WorldModel	World state snapshots, causal transitions, project scoping, hypothetical simulation
ValueCore	Value function with 14 weighted dimensions (9 core ethical + 5 policy-level), online learning via EMA, auto-rebalancing from TrustLog feedback. Context-aware domain profiles (medical/financial/legal/safety), policy-aware score floors (strict/balanced/permissive), per-factor contribution explainability, and auditable weight adjustment trail
FUJI Gate	Multi-layer safety gate — PII detection, harmful content blocking, sensitive domain filtering, prompt injection defense, confusable character detection, LLM safety head, and policy-driven YAML rules
TrustLog	Append-only hash-chained audit log (JSONL) with SHA-256 integrity, Ed25519 signatures, WORM hard-fail mirror, Transparency log anchor, and automatic PII data classification
Debate	Multi-viewpoint reasoning (pro/con/third-party) for transparent decision rationale
Critique	Self-critique generation with severity-ranked issues and fix suggestions
Planner	Action plan generation with step-by-step execution strategies
Replay Engine	High-fidelity reproducible replay of past decisions with diff reporting, retrieval snapshot checksum, model version verification, and dependency version tracking for audit verification
Policy Compiler	YAML/JSON policy → intermediate representation → compiled rules with Ed25519-signed bundles, runtime enforcement adapter, and auto-generated tests
Compliance	EU AI Act-aligned workflow support reports, internal governance reports, and deployment readiness checks

📁 Project Structure

veritas_os/                  ← Monorepo root
├── veritas_os/              ← Python backend (FastAPI)
│   ├── api/                 ← REST API server, schemas, governance
│   │   ├── server.py        ← FastAPI app with 37 endpoints
│   │   ├── routes_decide.py ← Decision & replay endpoints
│   │   ├── routes_trust.py  ← TrustLog & audit endpoints
│   │   ├── routes_memory.py ← Memory CRUD endpoints
│   │   ├── routes_governance.py ← Governance & policy endpoints
│   │   ├── routes_system.py ← Health, metrics, compliance, SSE, halt
│   │   ├── schemas.py       ← Pydantic v2 request/response models
│   │   └── governance.py    ← Policy management with audit trail
│   ├── core/                ← Decision engine
│   │   ├── kernel.py        ← Decision computation engine
│   │   ├── kernel_*.py      ← Kernel extensions (doctor, intent, QA, stages, episode, post_choice)
│   │   ├── pipeline/        ← 17-stage orchestrator (package with stage modules)
│   │   ├── fuji/            ← FUJI safety gate (package — policy, injection, safety head)
│   │   ├── memory/          ← MemoryOS (package — store, vector, search, security, compliance)
│   │   ├── continuation_runtime/ ← Chain-level continuation observation (Phase-1)
│   │   ├── value_core.py    ← Value alignment & online learning
│   │   ├── world.py         ← WorldModel (state management)
│   │   ├── llm_client.py    ← Multi-provider LLM gateway
│   │   ├── debate.py        ← Debate mechanism
│   │   ├── critique.py      ← Critique generation
│   │   ├── planner.py       ← Action planning (+ planner_helpers, planner_json, planner_normalization)
│   │   └── sanitize.py      ← PII masking & content safety
│   ├── policy/              ← Policy compiler, signing, runtime adapter, bundle
│   ├── logging/             ← TrustLog, dataset writer, encryption, rotation
│   ├── audit/               ← Signed audit log (Ed25519)
│   ├── compliance/          ← EU AI Act report engine
│   ├── security/            ← SHA-256 hashing, Ed25519 signing
│   ├── tools/               ← Web search, GitHub search, LLM safety
│   ├── replay/              ← Deterministic replay engine
│   ├── observability/       ← OpenTelemetry metrics, middleware
│   ├── storage/             ← Pluggable storage backends (JSONL, PostgreSQL, Alembic migrations)
│   ├── prompts/             ← Prompt templates for LLM interactions
│   ├── reporting/           ← Report generation utilities
│   ├── benchmarks/          ← Performance benchmark data
│   └── tests/               ← 6600+ Python tests (+ top-level tests/)
├── frontend/                ← Next.js 16 Mission Control dashboard
│   ├── app/                 ← Pages (Home, Console, Audit, Governance, Risk)
│   ├── components/          ← Shared React components
│   ├── features/console/    ← Decision Console feature module
│   ├── lib/                 ← API client, validators, utilities
│   ├── locales/             ← i18n (Japanese / English)
│   └── e2e/                 ← Playwright E2E tests
├── packages/
│   ├── types/               ← Shared TypeScript types & runtime validators
│   └── design-system/       ← Card, Button, AppShell components
├── spec/                    ← OpenAPI specification (MIT)
├── sdk/                     ← SDK interface layer (MIT)
├── cli/                     ← CLI interface layer (MIT)
├── policies/                ← Policy templates (examples are MIT)
├── config/                  ← Test and runtime configuration
├── scripts/                 ← Architecture, quality, and security validation scripts
├── docs/                    ← Architecture docs, reviews, user manual, coverage reports
├── openapi.yaml             ← OpenAPI 3.x specification
├── docker-compose.yml       ← Full-stack orchestration
├── Makefile                 ← Dev/test/deploy commands
└── pyproject.toml           ← Python project config

💾 Storage Backends

VERITAS OS uses a pluggable storage backend pattern for MemoryOS and TrustLog persistence.

Positioning: PostgreSQL is the official production backend path in this repository. JSON/JSONL is retained for local/dev and migration compatibility workflows.

Backend	MemoryOS	TrustLog	Default (local/CLI)	Default (Docker Compose)	Use case
JSON / JSONL (file-based)	`JsonMemoryStore`	`JsonlTrustLogStore`	✅ Yes	—	Single-process dev, demo, air-gapped
PostgreSQL	`PostgresMemoryStore`	`PostgresTrustLogStore`	—	✅ Yes	Multi-worker production, durable audit

Docker Compose defaults to PostgreSQL. File-based backends are the default when running via python -m veritas_os or uvicorn without overriding env vars.

Environment matrix

Environment	Recommended backend	Config source
Local dev (no Docker)	JSON / JSONL	`.env` defaults
Local dev (Docker Compose)	PostgreSQL	`.env` copied from `.env.example`; explicit compose credentials required
Staging	PostgreSQL	Explicit env vars
Secure / Prod	PostgreSQL	External secret manager

Quick switch

# Use PostgreSQL for both backends
VERITAS_MEMORY_BACKEND=postgresql
VERITAS_TRUSTLOG_BACKEND=postgresql
VERITAS_DATABASE_URL=postgresql://veritas:CHANGE_ME_generate_a_strong_local_password@localhost:5432/veritas

# Apply schema
make db-upgrade

Migrating existing data (JSONL → PostgreSQL)

# 1. Dry-run to validate source files
veritas-migrate trustlog --source runtime/trustlog/trust_log.jsonl --dry-run
veritas-migrate memory   --source runtime/memory/memory.json      --dry-run

# 2. Import with post-migration hash-chain verification
veritas-migrate trustlog --source runtime/trustlog/trust_log.jsonl --verify
veritas-migrate memory   --source runtime/memory/memory.json

# 3. Verify via smoke tests
VERITAS_MEMORY_BACKEND=postgresql VERITAS_TRUSTLOG_BACKEND=postgresql \
  pytest -m smoke veritas_os/tests/ -q

The veritas-migrate CLI is idempotent — re-running after a partial failure safely resumes by skipping already-imported entries. See docs/postgresql-production-guide.md §11 for the full procedure including rollback.

Verification tools

Tool	Purpose	Invocation
`veritas-trustlog-verify`	Standalone TrustLog chain integrity verifier	`veritas-trustlog-verify --log-dir <path>`
`veritas-migrate --verify`	Post-import hash-chain check (PostgreSQL)	`veritas-migrate trustlog --source … --verify`
`/v1/trustlog/verify`	REST API chain verification	`curl -H "X-API-Key: …" http://host:8000/v1/trustlog/verify`
`/v1/metrics`	Pool utilization, health, pg_stat_activity	`curl -H "X-API-Key: …" http://host:8000/v1/metrics`
`drill_postgres_recovery.sh`	End-to-end backup → restore → verify	`make drill-recovery` or `make drill-recovery-ci`
`pytest -m smoke`	Governance invariant smoke tests	`pytest -m smoke veritas_os/tests/`
`pytest -m production`	Production-like validation suite	`make test-production`

Key features of the PostgreSQL backend

Alembic-managed schema — reproducible migrations with upgrade / downgrade paths.
Advisory-lock chain serialization — TrustLog hash-chain integrity guaranteed under concurrent writes via pg_advisory_xact_lock.
JSONB storage — queryable payloads with GIN indexes.
Full parity test suite — 195+ tests verify identical semantics across backends.
psycopg 3 — modern async PostgreSQL driver with connection pooling (psycopg-pool).
JSONL → PostgreSQL import — idempotent veritas-migrate CLI with dry-run, resume, and post-import hash-chain verification.
Contention testing — 25 tests in test_pg_trustlog_contention.py verify chain integrity under concurrent/burst/failure scenarios.
Observability — /v1/metrics exposes pool utilization, health, and pg_stat_activity (long-running queries, idle-in-tx, advisory lock waiters). 28 tests in test_pg_metrics.py.
Recovery drill — scripts/drill_postgres_recovery.sh automates backup → restore → verify cycle. 31 tests in test_drill_postgres_recovery.py.

Production deployment

See docs/postgresql-production-guide.md for:

Pool sizing, SSL/TLS, statement timeout configuration
Backup/restore, replication/HA guidance
JSONL → PostgreSQL import via veritas-migrate CLI (dry-run, resume, rollback, verification)
Smoke test and release validation relationship
Legacy path cleanup status
Secure/prod posture recommended settings
Contention test coverage and known limitations
Metrics reference (JSON fields, Prometheus gauges, interpretation guide)
Known limitations and future work (pgvector, partitioning, CDC)

See docs/postgresql-drill-runbook.md for:

Backup / restore / recovery drill procedures and scripts
Safe / unsafe HA boundaries for TrustLog writes
Incident response playbooks (corruption, tampering)
make drill-backup, make drill-restore, make drill-recovery, make drill-recovery-ci

See also: docs/database-migrations.md | docs/BACKEND_PARITY_COVERAGE.md | docs/legacy-path-cleanup.md

🖥️ Frontend — Mission Control Dashboard

The frontend is a Next.js 16 (React 18, TypeScript) dashboard that provides operational visibility into the decision pipeline.

Tech Stack

Layer	Technology
Framework	Next.js 16.2.3 (App Router)
Language	TypeScript 5.7
Styling	Tailwind CSS 3.4 + CVA (class-variance-authority)
Icons	Lucide React
Testing	Vitest + Testing Library (unit), Playwright + axe-core (E2E + accessibility)
i18n	Custom React Context (Japanese default, English)
Security	CSP with per-request nonce, httpOnly BFF cookies, HSTS, X-Frame-Options
Design System	`@veritas/design-system` (Card, Button, AppShell)
Shared Types	`@veritas/types` with runtime type guards
Lint Config	eslint-config-next 15.5.10

Pages

Route	Page	Description
`/`	Command Dashboard	Live event stream (FUJI rejects, policy updates, chain breaks), global health summary, critical rail metrics, operational priorities
`/console`	Decision Console	Interactive decision pipeline — enter a query, watch 8-stage pipeline execute in real-time, view FUJI gate decision, chosen/alternatives/rejected, cost-benefit analysis, replay diff
`/audit`	TrustLog Explorer	Browse hash-chained audit trail, verify chain integrity (verified/broken/missing/orphan), stage filtering, regulatory report export (JSON/CSV with PII redaction)
`/governance`	Governance Control	Edit FUJI rules (8 safety gates), risk thresholds, auto-stop circuit breaker, log retention. Standard and EU AI Act modes. Draft → approval workflow with diff viewer and version history
`/risk`	Risk Dashboard	24-hour streaming risk/uncertainty chart, severity clustering, flagged request drilldown, anomaly pattern analysis

Architecture

BFF (Backend-for-Frontend) pattern: all API requests proxied through Next.js (/api/veritas/*), browser never sees API credentials
httpOnly session cookie (__veritas_bff) for authentication, scoped to /api/veritas/*
Runtime type guards validate every API response before rendering (isDecideResponse, isTrustLogsResponse, validateGovernancePolicyResponse, etc.)
SSE + WebSocket for real-time event streaming (live FUJI rejects, trust log updates, risk bursts)
XSS defense via sanitizeText() on all API response rendering

📡 API Overview

All protected endpoints require X-API-Key. The full list of endpoints:

Decision

Method	Path	Description
POST	`/v1/decide`	Full decision pipeline
POST	`/v1/fuji/validate`	Validate a single action via FUJI Gate
POST	`/v1/replay/{decision_id}`	Deterministic replay with diff report
POST	`/v1/decision/replay/{decision_id}`	Alternative replay with mock support

Memory

Method	Path	Description
POST	`/v1/memory/put`	Store memory (episodic/semantic/procedural/affective)
POST	`/v1/memory/get`	Retrieve memory by key
POST	`/v1/memory/search`	Vector search with user_id filtering
POST	`/v1/memory/erase`	Erase user memories (legal hold protected)

Trust & Audit

Method	Path	Description
GET	`/v1/trust/logs`	List trust log entries
GET	`/v1/trust/{request_id}`	Get single trust log entry
POST	`/v1/trust/feedback`	User satisfaction feedback on decisions
GET	`/v1/trust/stats`	Trust log statistics
GET	`/v1/trustlog/verify`	Verify hash chain integrity
GET	`/v1/trustlog/export`	Export signed trustlog
GET	`/v1/trust/{request_id}/prov`	W3C PROV-JSON export for audit interoperability

Governance

Method	Path	Description
GET	`/v1/governance/policy`	Retrieve current governance policy
PUT	`/v1/governance/policy`	Update governance policy (hot-reload, 4-eyes approval required; bind-governed mutation response includes bind lineage fields + `bind_summary`)
GET	`/v1/governance/policy/history`	Policy change audit trail (with digest transitions)
GET	`/v1/governance/value-drift`	Monitor value weight EMA drift
GET	`/v1/governance/decisions/export`	Export decisions for governance audit, including bind lineage fields and additive `bind_summary` vocabulary
POST	`/v1/governance/policy-bundles/promote`	Execute policy bundle promotion as a bind-boundary governance workflow (returns bind receipt lineage and additive `bind_summary`; requires governance write permission)
GET	`/v1/governance/bind-receipts`	List bind receipts (decision/execution lineage + canonical target/outcome/reason/failed/recent/sort/limit filters)
GET	`/v1/governance/bind-receipts/export`	Export bind receipts for operator/audit pipelines using the same filter vocabulary as list
GET	`/v1/governance/bind-receipts/{bind_receipt_id}`	Retrieve a single full bind receipt artifact (including canonical target metadata and bind checks)

Bind artifact family: operator meaning

BindReceipt is the full bind artifact used for reviewable/auditable lineage and replay-oriented investigation.
bind_summary is the compact shared bind vocabulary reused across bind-governed mutation and export responses.
This separation keeps decision approval and bind commitment distinct on the operator-facing governance surface (Mission Control + APIs).

Operator workflow: promote a policy bundle

Use POST /v1/governance/policy-bundles/promote when you need to promote the active policy bundle pointer via the existing bind-boundary path.

Request accepts exactly one selector: bundle_id or bundle_dir_name.
Arbitrary filesystem paths are rejected (/, \, ., .. are not accepted in selectors).
Response includes bind lineage fields (bind_outcome, bind_receipt_id, execution_intent_id), additive bind_summary, and the full bind_receipt.
Use GET /v1/governance/bind-receipts, GET /v1/governance/bind-receipts/export, or GET /v1/governance/bind-receipts/{bind_receipt_id} to inspect/export resulting artifacts.

curl -X POST "http://127.0.0.1:8000/v1/governance/policy-bundles/promote" \
  -H "X-API-Key: ${VERITAS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "bundle_id": "bundle-v2",
    "decision_id": "dec-promote-1",
    "request_id": "req-promote-1",
    "policy_snapshot_id": "snap-promote-1",
    "decision_hash": "hash-promote-1"
  }'

For operator guidance and outcome interpretation, see docs/en/guides/governance-policy-bundle-promotion.md.

Signed governance artifacts — In secure/prod posture, policy bundles must be Ed25519-signed. Decision artifacts include a governance_identity field showing which governance policy was in force (version, digest, signature verification result, signer identity). See docs/governance_artifact_lifecycle.md for the full lifecycle, key management, and migration guide.

Compliance & Reporting

Method	Path	Description
GET	`/v1/report/eu_ai_act/{decision_id}`	EU AI Act-aligned governance evidence report
GET	`/v1/report/governance`	Internal governance report
GET	`/v1/compliance/deployment-readiness`	Pre-deployment compliance check
GET	`/v1/compliance/config`	Retrieve compliance configuration
PUT	`/v1/compliance/config`	Update compliance configuration (bind-governed mutation response includes bind lineage fields + `bind_summary`)

System

Method	Path	Description
GET	`/health`, `/v1/health`	Health check
GET	`/status`, `/v1/status`	Extended status with pipeline/config health
GET	`/v1/metrics`	Operational metrics
GET	`/v1/events`	SSE stream for real-time UI updates
WS	`/v1/ws/trustlog`	WebSocket for live trust log streaming
POST	`/v1/system/halt`	Emergency halt (persists halt state)
POST	`/v1/system/resume`	Resume after halt
GET	`/v1/system/halt-status`	Current halt state

Replay

POST /v1/replay/{decision_id} re-executes a stored decision using the original recorded inputs and writes a replay artifact to REPLAY_REPORT_DIR (audit/replay_reports by default) as replay_{decision_id}_{YYYYMMDD_HHMMSS}.json.

Replay snapshots include retrieval_snapshot_checksum (SHA-256 deterministic hash), external_dependency_versions, and model_version for reproducibility verification. Model version mismatch is checked by default; snapshots without model_version are rejected by default (VERITAS_REPLAY_REQUIRE_MODEL_VERSION=1).

Note: LLM responses are inherently non-deterministic even at temperature=0. VERITAS Replay is designed as high-fidelity reproducible re-execution with divergence detection, not strict deterministic replay.

When VERITAS_REPLAY_STRICT=1, replay enforces deterministic settings (temperature=0, fixed seed, and mocked external retrieval side effects).

BODY='{"strict":true}'
TS=$(date +%s)
NONCE="replay-$(uuidgen | tr '[:upper:]' '[:lower:]')"
SIG=$(python - <<'PY'
import hashlib
import hmac
import os

secret=os.environ["VERITAS_API_SECRET"].encode("utf-8")
ts=os.environ["TS"]
nonce=os.environ["NONCE"]
body=os.environ["BODY"]
payload=f"{ts}\n{nonce}\n{body}"
print(hmac.new(secret, payload.encode("utf-8"), hashlib.sha256).hexdigest())
PY
)

curl -X POST "http://127.0.0.1:8000/v1/replay/DECISION_ID" \
  -H "X-API-Key: ${VERITAS_API_KEY}" \
  -H "X-VERITAS-TIMESTAMP: ${TS}" \
  -H "X-VERITAS-NONCE: ${NONCE}" \
  -H "X-VERITAS-SIGNATURE: ${SIG}" \
  -H "Content-Type: application/json" \
  -d "${BODY}"

EU AI Act report generation already reads replay_{decision_id}_*.json, so invoking the Replay API updates replay verification data consumed by compliance reporting automatically.

🚀 Quick Start

Option A: Docker Compose (Recommended)

Start both backend and frontend with a single command:

git clone https://github.com/veritasfuji-japan/veritas_os.git
cd veritas_os

# Copy and edit environment variables
cp .env.example .env
# Edit .env — set OPENAI_API_KEY, VERITAS_API_KEY, VERITAS_API_SECRET

docker compose up --build

Backend: http://localhost:8000 (Swagger UI at /docs)
Frontend: http://localhost:3000 (Mission Control dashboard)

Option B: Local Development

Backend

git clone https://github.com/veritasfuji-japan/veritas_os.git
cd veritas_os

python3.11 -m venv .venv
source .venv/bin/activate
pip install -e ".[full]"     # all features (recommended)
# pip install -e .           # core-only (API server + OpenAI)
# pip install -e ".[ml]"    # core + ML tooling

See docs/dependency-profiles.md for all install profiles and the dependency classification table.

Warning

Avoid placing secrets directly in shell history. Prefer a .env file (git-ignored) or a secrets manager for production environments.

Set environment variables (or use a .env file):

export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
export VERITAS_API_KEY="your-secret-api-key"
export VERITAS_API_SECRET="your-long-random-secret"
export LLM_PROVIDER="openai"
export LLM_MODEL="gpt-4.1-mini"

Start the backend:

python -m uvicorn veritas_os.api.server:app --reload --port 8000

Frontend

# From the repository root (requires Node.js 20+ and pnpm)
corepack enable
pnpm install --frozen-lockfile
pnpm ui:dev

The frontend starts at http://localhost:3000.

Set VERITAS_API_BASE_URL if the frontend BFF should reach a backend other than http://localhost:8000. Do not set NEXT_PUBLIC_* API base URL variables in production because they can expose internal routing details and now trigger BFF fail-closed behavior.

Makefile shortcuts

make setup         # Initialize environment
make dev           # Start backend (port 8000)
make dev-frontend  # Start frontend (port 3000)
make dev-all       # Start both

Local Mac Development (No Docker)

A validated end-to-end flow for running VERITAS OS natively on macOS without Docker.

1. Create .env — copy .env.example and fill in the required values:

cp .env.example .env
# Edit .env — set at minimum:
#   OPENAI_API_KEY, VERITAS_API_KEY, VERITAS_API_SECRET, VERITAS_ENCRYPTION_KEY

Generate an encryption key if you don't have one:

python -c "from veritas_os.logging.encryption import generate_key; print(generate_key())"

Add TrustLog WORM mirror and transparency log paths for local dev:

# Append to .env
VERITAS_TRUSTLOG_MIRROR_BACKEND=local
VERITAS_TRUSTLOG_WORM_MIRROR_PATH=runtime/dev/logs/trustlog_worm.jsonl
VERITAS_TRUSTLOG_ANCHOR_BACKEND=local
VERITAS_TRUSTLOG_TRANSPARENCY_LOG_PATH=runtime/dev/logs/trustlog_transparency.jsonl

2. Launch backend — .env must be sourced into the shell:

set -a && source .env && set +a
python -m uvicorn veritas_os.api.server:app --reload --port 8000
# Or simply: make dev   (Makefile sources .env automatically)

3. Launch frontend — in a separate terminal:

# Frontend reads frontend/.env.development automatically via Next.js.
# Ensure VERITAS_API_KEY in frontend/.env.development matches your backend.
set -a && source .env && set +a
pnpm ui:dev

4. BFF authentication — the frontend BFF proxy requires a valid auth token. frontend/.env.development ships with dev defaults (VERITAS_BFF_AUTH_TOKENS_JSON and VERITAS_BFF_SESSION_TOKEN). For browser access, visit http://localhost:3000/api/auth/dev-login to mint the __veritas_bff httpOnly cookie, which authenticates all subsequent /api/veritas/* requests.

5. Verified working features:

Feature	Endpoint / Path
Decision	`POST /v1/decide`
SSE events	`GET /v1/events`
TrustLog save	Automatic on decide
WORM mirror	`VERITAS_TRUSTLOG_WORM_MIRROR_PATH`
Transparency log	`VERITAS_TRUSTLOG_TRANSPARENCY_LOG_PATH`

6. Dev artifact locations — with default settings, runtime data writes to:

Path	Contents
`runtime/dev/logs/`	TrustLog JSONL, WORM mirror, transparency log
`runtime/dev/logs/DASH/`	Shadow decide outputs, datasets
`runtime/dev/logs/keys/`	Ed25519 signing key material (auto-generated)

Tip

The runtime/ directory is namespace-separated (dev, test, demo, prod) via VERITAS_RUNTIME_NAMESPACE or the VERITAS_ENV mapping. Default is dev.

Try the API

Open Swagger UI at http://127.0.0.1:8000/docs, authorize with X-API-Key, and run POST /v1/decide:

{
  "query": "Should I check tomorrow's weather before going out?",
  "context": {
    "user_id": "test_user",
    "goals": ["health", "efficiency"],
    "constraints": ["time limit"],
    "affect_hint": "focused"
  }
}

🐳 Docker Compose (Full Stack)

docker-compose.yml orchestrates three services:

Service	Port	Description
`postgres`	5432	PostgreSQL 16 (auto-configured, health-checked, resource-limited)
`backend`	8000	FastAPI server (built from `Dockerfile`) with health check, depends on `postgres`
`frontend`	3000	Next.js dev server (Node.js 20), waits for backend to be healthy

docker compose up --build   # Start
docker compose down         # Stop
docker compose logs -f      # Follow logs

Environment variables (set in .env or shell):

Variable	Default	Description
`OPENAI_API_KEY`	—	OpenAI API key (required)
`VERITAS_API_KEY`	—	Backend API authentication key
`VERITAS_API_SECRET`	`change-me`	HMAC signing secret (32+ chars recommended)
`VERITAS_CORS_ALLOW_ORIGINS`	`http://localhost:3000,http://127.0.0.1:3000`	CORS allow-list
`VERITAS_API_BASE_URL`	`http://backend:8000`	Frontend BFF (server-only) → backend URL
`VERITAS_MEMORY_BACKEND`	`postgresql`	Memory storage backend (`json` or `postgresql`)
`VERITAS_TRUSTLOG_BACKEND`	`postgresql`	TrustLog storage backend (`jsonl` or `postgresql`)
`VERITAS_DATABASE_URL`	required for PostgreSQL	PostgreSQL DSN; for Docker Compose set this in `.env` using a non-default password
`LLM_PROVIDER`	`openai`	LLM provider
`LLM_MODEL`	`gpt-4.1-mini`	LLM model name

Docker Compose no longer ships default database or admin BFF credentials. Copy .env.example to .env and replace every CHANGE_ME value before running compose. See docs/en/operations/docker-compose-security.md.

🐳 Docker (Backend Only)

Pull the latest image:

docker pull ghcr.io/veritasfuji-japan/veritas_os:latest

Run the API server:

docker run --rm -p 8000:8000 \
  -e OPENAI_API_KEY="YOUR_OPENAI_API_KEY" \
  -e VERITAS_API_KEY="your-secret-api-key" \
  -e LLM_PROVIDER="openai" \
  -e LLM_MODEL="gpt-4.1-mini" \
  ghcr.io/veritasfuji-japan/veritas_os:latest

If your FastAPI entrypoint differs from veritas_os.api.server:app, update the Dockerfile CMD accordingly before building the image.

🏗️ Architecture (High-Level)

┌──────────────────────────────────────────────────────┐
│  Frontend (Next.js 16 / React 18 / TypeScript)       │
│  ┌────────┬──────────┬───────────┬──────────┬──────┐ │
│  │  Home  │ Console  │   Audit   │Governance│ Risk │ │
│  └────┬───┴────┬─────┴─────┬─────┴────┬─────┴──┬───┘ │
│       │ BFF Proxy (httpOnly cookie, CSP nonce)  │     │
│       └─────────────────┬───────────────────────┘     │
└─────────────────────────┼─────────────────────────────┘
                          │ /api/veritas/*
┌─────────────────────────┼─────────────────────────────┐
│  Backend (FastAPI / Python 3.11+)                      │
│       ┌─────────────────┴─────────────────────┐       │
│       │           API Server (server.py)       │       │
│       │   Auth · Rate Limit · CORS · PII mask  │       │
│       └────┬──────┬──────┬──────┬──────┬──────┘       │
│            │      │      │      │      │              │
│  ┌─────────┴┐ ┌───┴───┐ ┌┴─────┐ ┌────┴──┐ ┌────────┴┐│
│  │ Pipeline ││Govern- ││Memory││Trust  ││Compli-  ││
│  │Orchestr. ││ ance   ││ API  ││ API   ││ ance    ││
│  └────┬─────┘└────────┘└──┬───┘└───┬───┘└─────────┘│
│       │                    │       │               │
│  ┌────┴────────────────────┴───────┴────────────┐  │
│  │            Core Decision Engine               │  │
│  │  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │  │
│  │  │ Kernel │ │ Debate │ │Critique│ │Planner │ │  │
│  │  └────┬───┘ └────────┘ └────────┘ └────────┘ │  │
│  │       │                                       │  │
│  │  ┌────┴───┐ ┌────────┐ ┌────────┐ ┌────────┐ │  │
│  │  │  FUJI  │ │Value   │ │MemoryOS│ │ World  │ │  │
│  │  │  Gate  │ │ Core   │ │(Vector)│ │ Model  │ │  │
│  │  └────────┘ └────────┘ └────────┘ └────────┘ │  │
│  └──────────────────┬───────────────────────────┘  │
│                     │                              │
│  ┌──────────────────┴───────────────────────────┐  │
│  │  Infrastructure                               │  │
│  │  LLM Client · TrustLog · Replay · Sanitize   │  │
│  │  Atomic I/O · Signing · Tools (Web/GitHub)    │  │
│  └───────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘

Core execution path

Module	Responsibility
`veritas_os/core/kernel.py`	Decision computation — intent detection, option generation, alternative scoring
`veritas_os/core/pipeline/`	17-stage orchestrator for `/v1/decide` — validation through audit persistence (package with per-stage modules)
`veritas_os/core/llm_client.py`	Multi-provider LLM gateway with connection pooling, circuit breaker, retry with backoff

Safety & governance

Module	Responsibility
`veritas_os/core/fuji/`	Multi-layer fail-closed safety gate — PII, harmful content, sensitive domains, prompt injection, confusable chars, LLM safety head, policy rules. All exceptions return `rejected` / `risk=1.0`
`veritas_os/core/value_core.py`	Value function with 14 weighted dimensions (9 core ethical + 5 policy-level), online learning via EMA, auto-rebalance from TrustLog. Supports context-aware domain profiles, policy-aware score floors, per-factor contribution explainability, and auditable weight adjustment trail
`veritas_os/api/governance.py`	Policy CRUD with hot-reload, 4-eyes approval (2 approvers, no duplicates), change callbacks, audit trail, value drift monitoring, RBAC/ABAC access control
`veritas_os/logging/trust_log.py`	Hash-chain TrustLog `h_t = SHA256(h_{t-1} ∥ r_t)` with thread-safe append
`veritas_os/audit/trustlog_signed.py`	Ed25519-signed TrustLog with WORM hard-fail mirror, Transparency log anchor, automatic PII data classification
`veritas_os/policy/`	Policy compiler — YAML/JSON → IR → compiled rules, Ed25519-signed bundles, runtime enforcement adapter

Memory & world state

Module	Responsibility
`veritas_os/core/memory/`	Unified episodic/semantic/procedural/affective memory with vector search (sentence-transformers, 384-dim), retention classes, legal hold, PII masking
`veritas_os/core/world.py`	World state snapshots, causal transitions, project scoping, hypothetical simulation

Reasoning

Module	Responsibility
`veritas_os/core/debate.py`	Multi-viewpoint debate (pro/con/third-party)
`veritas_os/core/critique.py`	Self-critique with severity-ranked issues and fix suggestions
`veritas_os/core/planner.py`	Action plan generation

LLM Client

Supports multiple providers via LLM_PROVIDER environment variable. Each provider has a support tier that indicates its production readiness:

Tier	Meaning
production	CI-tested, production-deployment target, covered by SLA
planned	Code paths implemented but not verified in production; may lag behind upstream API changes
experimental	Minimal scaffold only; subject to breaking changes; not for production use

Provider	Model	Tier
`openai`	GPT-4.1-mini (default)	production
`anthropic`	Claude	planned
`google`	Gemini	planned
`ollama`	Local models	experimental
`openrouter`	Aggregator	experimental

Current model-provider support is documented in docs/en/operations/provider-support-matrix.md. OpenAI is the current production-tier provider; other providers are planned or experimental unless explicitly documented otherwise.

Runtime notice: Using a non-production provider emits a UserWarning so callers are aware of the tier boundary.

Promoting a provider to production requires: (1) integration test suite with ≥ 90 % path coverage for the provider, (2) successful staging deployment for ≥ 2 weeks, (3) API-compatibility review against upstream changelog, and (4) explicit approval in a pull request.

Features: shared httpx.Client with connection pooling (LLM_POOL_MAX_CONNECTIONS=20), retry with configurable backoff (LLM_MAX_RETRIES=3), response size guard (16 MB), circuit breaker per provider, monkeypatchable for testing.

🔗 TrustLog (Hash-Chained Audit Log)

TrustLog is a secure-by-default, encrypted, hash-chained audit log.

Security pipeline (per entry)

entry → redact(PII + secrets) → canonicalize(RFC 8785) → chain hash → encrypt → append

Redact — PII (email, phone, address) and secrets (API keys, bearer tokens) are automatically masked before any persistence.
Canonicalize — RFC 8785 canonical JSON ensures deterministic hashing.
Chain hash — h_t = SHA256(h_{t-1} || r_t) provides tamper-evident linking.
Encrypt — Mandatory at-rest encryption (AES-256-GCM or HMAC-SHA256 CTR-mode). Plaintext storage is not possible without explicitly opting out.
Append — Encrypted line written to JSONL with fsync for durability.

Setup

# Generate an encryption key (required)
python -c "from veritas_os.logging.encryption import generate_key; print(generate_key())"

# Set the key (required for TrustLog to function)
export VERITAS_ENCRYPTION_KEY="<generated-key>"

Warning: Without VERITAS_ENCRYPTION_KEY, TrustLog writes will fail with EncryptionKeyMissing. This is by design — plaintext audit logs are prohibited.

Verification

# Verify hash chain integrity (requires decryption key)
python -m veritas_os.scripts.verify_trust_log

Key features:

Cryptographic chain — RFC 8785 canonical JSON, deterministic SHA-256
Thread-safe — RLock protection with atomic file writes
Dual persistence — in-memory cache (max 2000 items) + persistent JSONL ledger
Signed export — Ed25519 digital signatures for tamper-proof distribution
Chain verification — GET /v1/trustlog/verify validates the full chain
Transparency log anchor — external log integration for independent audit verification (VERITAS_TRUSTLOG_TRANSPARENCY_REQUIRED=1 for fail-closed operation)
WORM hard-fail — write failures to WORM mirror raise SignedTrustLogWriteError (VERITAS_TRUSTLOG_WORM_HARD_FAIL=1)
W3C PROV export — GET /v1/trust/{request_id}/prov returns PROV-JSON for audit tool interoperability
PII masking & classification — automatic PII/secret redaction with data classification tagging (18 PII patterns including email, credit card, phone, address, IP, passport)
Frontend visualization — TrustLog Explorer at /audit with chain integrity status (verified/broken/missing/orphan)

🔄 Continuation Runtime

VERITAS includes a chain-level continuation observation and limited enforcement layer that runs beside (not inside) the existing step-level decision infrastructure.

Modes

Mode	Behavior	Default in posture
Observe (Phase-1)	Shadow only — no enforcement, no refusal gating	dev, staging
Advisory (Phase-2)	Emits enforcement events as advisories; no blocking	secure, prod
Enforce (Phase-2)	Limited enforcement: may block/halt for high-confidence conditions	(opt-in via env)

Aspect	Status
FUJI	Unchanged — remains the final safety/policy gate for each step
`gate.decision_status`	Unchanged — no new values, no reinterpretation
Feature flag off	Zero change to response, logs, UI, or behavior
Purpose	Detect and (optionally) enforce when a chain's continuation standing weakens

Enforcement Actions (Phase-2)

The enforcement engine triggers only for high-confidence, explainable conditions:

Condition	Action	When
Repeated high-risk degradation	`require_human_review`	≥3 consecutive degraded/escalated/halted receipts
Approval-required without approval	`halt_chain`	Scope requires escalation but no approval provided
Replay divergence exceeded	`escalate_alert`	Divergence ratio >0.3 for sensitive paths
Policy boundary violation	`halt_chain`	Policy violation detected in continuation state

What causes `require_human_review` vs `halt_chain`?

require_human_review: Triggered by accumulated degradation — a pattern of weakening that suggests drift, not a single critical failure. The chain is paused pending operator review.
halt_chain: Triggered by deterministic governance failures — missing approval for an approval-required transition, or a detected policy boundary violation. The chain is stopped immediately.
escalate_alert: Triggered by replay divergence — the continuation path is diverging from expected replay behavior, suggesting environmental or configuration drift.

Configuration

Variable	Default	Description
`VERITAS_CAP_CONTINUATION_RUNTIME`	`0`	Enable Continuation Runtime
`VERITAS_CONTINUATION_ENFORCEMENT_MODE`	`observe`	Enforcement mode (`observe`, `advisory`, `enforce`)

Posture-based defaults:

dev/staging: observe (no enforcement)
secure/prod: advisory (emit events, no blocking)
Set VERITAS_CONTINUATION_ENFORCEMENT_MODE=enforce to enable limited enforcement in any posture.

Observed Posture vs Enforced Posture

Setting VERITAS_POSTURE=prod does not by itself make continuation governance enforcement blocking. If VERITAS_CONTINUATION_ENFORCEMENT_MODE=advisory, VERITAS emits governance events but does not block execution. This is an observed posture, not an enforced governance posture. Regulated deployments should use VERITAS_CONTINUATION_ENFORCEMENT_MODE=enforce, or explicitly document advisory mode as a temporary evaluation posture.

Both observe and advisory are non-blocking continuation modes. observe is observation-only and remains the legacy/default non-blocking mode. advisory is the explicit governance-advisory non-blocking mode surfaced by posture classification. enforce is the only blocking continuation governance mode.

VERITAS_POSTURE	VERITAS_CONTINUATION_ENFORCEMENT_MODE	Meaning
any	observe	Observation-only mode; non-blocking
dev/local	advisory	Development/evaluation advisory mode; non-blocking
prod/secure	advisory	Production observation/advisory mode; non-blocking; not enforced governance
prod/secure	enforce	Production enforcement mode; blocking governance active

Key Concepts

Snapshot (state): minimal governable facts — support basis, scope, burden, headroom, law version
Receipt (audit witness): how revalidation was conducted, divergence flags, reason codes, receipt chain linkage
Enforcement Event (audit artifact): every enforcement action is logged, attributable, replay-visible, and operator-visible
The snapshot is not a receipt. The receipt is not a state store. Enforcement events are separate from both.
Revalidation runs before step-level merit evaluation (pre-merit placement)
Continuation-level enforcement is conceptually separate from FUJI step-level safety gating

Every Enforcement Event Is:

Logged — via Python logging + trustlog-ready structure
Attributable — carries claim_lineage_id, receipt_id, chain_id
Replay-visible — carries snapshot_id, receipt_id, law_version
Operator-visible — carries action, reasoning, severity, conditions_met

Design Note

See: docs/architecture/continuation_enforcement_design_note.md

Enable with: VERITAS_CAP_CONTINUATION_RUNTIME=1 (default: off)

See also: docs/architecture/continuation_runtime_adr.md, docs/architecture/continuation_runtime_architecture_note.md

🧪 Tests

Backend (Python)

Recommended (reproducible via uv):

make test
make test-cov

These targets use uv with PYTHON_VERSION=3.12.12 and automatically download the interpreter if it is not already installed. make test-cov now mirrors the CI coverage gate (--cov-fail-under=85, veritas_os/tests/.coveragerc, XML/HTML reports, and -m "not slow"), and explicitly executes both Python test roots: veritas_os/tests/ and top-level tests/.

# Optional: override the local gate/marker to troubleshoot
make test-cov COVERAGE_FAIL_UNDER=0 PYTEST_MARKEXPR=""

Fast smoke check:

make test TEST_ARGS="-q veritas_os/tests/test_api_constants.py"

Optional overrides:

make test TEST_ARGS="-q veritas_os/tests/test_time_utils.py"
make test PYTHON_VERSION=3.11

Frontend (TypeScript)

# Unit tests (Vitest + Testing Library)
pnpm ui:test

# Type checking
pnpm ui:typecheck

# E2E tests (Playwright + axe-core accessibility)
pnpm --filter frontend e2e:install
pnpm --filter frontend e2e

CI / Quality Gate

VERITAS OS uses a three-tier CI/release validation model with explicit blocking semantics:

Tier	Workflow	Trigger	Blocking?
Tier 1	`main.yml`	Every PR + push to `main`	✅ Blocks merge
Tier 2	`release-gate.yml`	`v*` tag push	✅ Blocks release
Tier 3	`production-validation.yml`	Weekly + manual	⚠️ Advisory

Additional CI workflows:

Workflow	Trigger	Purpose
`codeql.yml`	PR + push to `main`	CodeQL security analysis
`publish-ghcr.yml`	Release / tag push	Docker image publishing to GHCR
`security-gates.yml`	PR + push to `main`	Security gate checks (dependency audit, secret scanning)
`runtime-pickle-guard.yml`	PR + push to `main`	Block runtime pickle/joblib artifacts
`sbom-nightly.yml`	Nightly schedule	SBOM generation and vulnerability scan

Tier 1 (main.yml) — every PR is blocked until all of the following pass:

Ruff lint + Bandit + architecture/security script checks
Dependency CVE audit (Python + Node)
governance-smoke: explicit fast smoke gate (pytest -m smoke, ~2 min)
Full unit test matrix (Python 3.11 + 3.12, 85% coverage gate)
Frontend lint / Vitest / Playwright E2E

Tier 2 (release-gate.yml) — every v* tag is blocked until all of the following pass:

Tier 1 checks repeated at release time
Production-like test suite (pytest -m "production or smoke" + TLS + load)
Full-stack Docker Compose health check
Governance readiness report artifact generated and uploaded
Human-readable release-proof-summary.md generated for enterprise review / diligence handoff

Tier 3 (production-validation.yml) — weekly schedule + manual dispatch:

Long-running production tests, load tests, external live tests
Includes live-provider validation entry points used for ongoing PostgreSQL-backed production-path operational verification
Advisory: failures are visible but do not block release

See docs/PRODUCTION_VALIDATION.md for the complete tier model and docs/RELEASE_PROCESS.md for the release process.

Type safety baseline command (incremental, not repository-wide strict typing):

python -m scripts.quality.check_type_baseline

This is currently an incremental developer/DD baseline for selected PoC/demo helper paths. It should not be read as repository-wide strict typing or as a Tier 1 CI gate unless the workflow explicitly runs it.

mypy is included in the repository development/full dependency manifests for repeatable quality checks. This baseline does not change runtime behavior or application code paths; production image dependency minimization should be handled separately if needed.

How to tell if a release is governance-ready

Find the Release Gate workflow run for the target tag in the Actions tab
The ✅ Release Readiness Gate job must show 🟢 RELEASE IS GOVERNANCE-READY
Download the release-governance-readiness-report artifact and verify "governance_ready": true
Read release-proof-summary.md for check-class pass/fail/skipped counts and assurance-boundary wording for external technical review

Production-like Validation

Beyond the unit/integration test suite, VERITAS includes production-like validation that exercises real subsystems (TrustLog, encryption, governance API, web search security) through production-equivalent code paths:

# Run production-like tests (no external deps needed)
make test-production

# Run smoke tests only
make test-smoke

# Full validation including Docker Compose (requires Docker)
make validate

Production validation is also available as a separate CI workflow (production-validation.yml) triggered manually or on a weekly schedule. See docs/PRODUCTION_VALIDATION.md for the complete strategy, verification matrix, and remaining production risks.

For backend semantics parity scope, see docs/BACKEND_PARITY_COVERAGE.md.

⚙️ Environment Variables Reference

All environment variables in one place. Set these in .env (git-ignored) or your secrets manager.

Required

Variable	Description	Example
`OPENAI_API_KEY`	OpenAI API key	`sk-...`
`VERITAS_API_KEY`	Backend API authentication key	Random string
`VERITAS_API_SECRET`	HMAC signing secret (32+ chars)	Random 64-char hex
`VERITAS_ENCRYPTION_KEY`	TrustLog encryption key (base64-encoded 32 bytes)	Use `generate_key()`

LLM Provider

Variable	Default	Description
`LLM_PROVIDER`	`openai`	LLM provider (`openai`, `anthropic`, `google`, `ollama`, `openrouter`)
`LLM_MODEL`	`gpt-4.1-mini`	Model name
`LLM_POOL_MAX_CONNECTIONS`	`20`	httpx connection pool size
`LLM_MAX_RETRIES`	`3`	Retry count with exponential backoff

Storage Backends

Variable	Default	Description
`VERITAS_MEMORY_BACKEND`	`json` (local) / `postgresql` (Docker)	Memory storage backend (`json` or `postgresql`)
`VERITAS_TRUSTLOG_BACKEND`	`jsonl` (local) / `postgresql` (Docker)	TrustLog storage backend (`jsonl` or `postgresql`)
`VERITAS_DATABASE_URL`	—	PostgreSQL connection URL (required when using `postgresql` backend)
`VERITAS_DB_POOL_MIN_SIZE`	`2`	PostgreSQL connection pool minimum size
`VERITAS_DB_POOL_MAX_SIZE`	`10`	PostgreSQL connection pool maximum size
`VERITAS_DB_SSLMODE`	`prefer`	PostgreSQL SSL mode (`prefer`, `require`, `verify-full`)
`VERITAS_DB_AUTO_MIGRATE`	`false` (local) / `true` (Docker)	Auto-run Alembic migrations on startup

Network & CORS

Variable	Default	Description
`VERITAS_CORS_ALLOW_ORIGINS`	`http://localhost:3000,http://127.0.0.1:3000`	CORS allow-list
`VERITAS_API_BASE_URL`	`http://backend:8000`	Frontend BFF → backend URL (server-only)
`VERITAS_MAX_REQUEST_BODY_SIZE`	`10485760` (10 MB)	Max request body size

Safety & Governance

Variable	Default	Description
`VERITAS_ENABLE_DIRECT_FUJI_API`	`0`	Enable `/v1/fuji/validate` endpoint
`VERITAS_ENFORCE_EXTERNAL_SECRET_MANAGER`	`0` (posture: `1` in secure/prod)	Block startup without Vault/KMS
`VERITAS_WEBSEARCH_ENABLE_TOXICITY_FILTER`	`1`	Web search toxicity filter (fail-closed)
`VERITAS_CAP_CONTINUATION_RUNTIME`	`0`	Enable Continuation Runtime
`VERITAS_CONTINUATION_ENFORCEMENT_MODE`	`observe`	Continuation enforcement mode (`observe`, `advisory`, `enforce`)

Policy Signing & Enforcement

Variable	Default	Description
`VERITAS_POLICY_VERIFY_KEY`	—	Path to Ed25519 public key PEM file for policy bundle signature verification
`VERITAS_POLICY_RUNTIME_ENFORCE`	`0` (posture: `1` in secure/prod)	Enable runtime enforcement of compiled policy decisions (deny/halt/escalate/require_human_review)
`VERITAS_POLICY_REQUIRE_ED25519`	`0`	Require Ed25519 signature verification; reject manifests when no key is available

Posture-aware enforcement: In secure/prod posture, SHA-256-only (unsigned) policy bundles are rejected by the runtime adapter. Only Ed25519-signed bundles pass verification. In dev/staging, SHA-256 integrity checks are accepted with a warning. Governance rollback operations follow the same 4-eyes approval and audit requirements as updates.

TrustLog & Audit

Variable	Default	Description
`VERITAS_TRUSTLOG_TRANSPARENCY_REQUIRED`	`0` (posture: `1` in secure/prod)	Require transparency log anchoring (fail-closed)
`VERITAS_TRUSTLOG_WORM_HARD_FAIL`	`0` (posture: `1` in secure/prod)	WORM mirror write failure raises error
`VERITAS_TRUSTLOG_MIRROR_BACKEND`	`local`	TrustLog mirror backend (`local` or `s3_object_lock`)
`VERITAS_TRUSTLOG_WORM_MIRROR_PATH`	—	Local append mirror destination path (used when backend is `local`)
`VERITAS_TRUSTLOG_S3_BUCKET`	—	S3 bucket name for TrustLog mirror writes (`s3_object_lock` backend)
`VERITAS_TRUSTLOG_S3_PREFIX`	—	S3 object key prefix for append-only TrustLog objects
`VERITAS_TRUSTLOG_ANCHOR_BACKEND`	`local`	TrustLog anchor backend (`local` or `noop`)
`VERITAS_TRUSTLOG_TRANSPARENCY_LOG_PATH`	—	Local transparency anchor path (required when anchor backend is `local` and transparency is required)
`VERITAS_TRUSTLOG_S3_REGION`	—	AWS region override for S3 client
`VERITAS_TRUSTLOG_S3_OBJECT_LOCK_MODE`	—	Object Lock mode (`GOVERNANCE` or `COMPLIANCE`)
`VERITAS_TRUSTLOG_S3_RETENTION_DAYS`	—	Retention period in days for S3 Object Lock
`VERITAS_TRUSTLOG_VERIFY_MIRROR_REMOTE`	`0`	Enable remote S3 mirror verification during TrustLog verification
`VERITAS_TRUSTLOG_VERIFY_MIRROR_S3_STRICT`	`0`	Strict mirror verification: fail on missing receipts (legacy entries) and retention gaps
`VERITAS_TRUSTLOG_VERIFY_MIRROR_S3_REQUIRE_LEGAL_HOLD`	`0`	Require S3 Object Legal Hold (`ON`) when remote mirror verification is enabled
`VERITAS_TRUSTLOG_SIGNER_BACKEND`	`file`	TrustLog signer backend (`file` or `aws_kms`)
`VERITAS_TRUSTLOG_KMS_KEY_ID`	—	AWS KMS key id/ARN (required when `VERITAS_TRUSTLOG_SIGNER_BACKEND=aws_kms`)

TrustLog mirror migration notes

Existing deployments continue to work with no change because VERITAS_TRUSTLOG_MIRROR_BACKEND defaults to local and keeps VERITAS_TRUSTLOG_WORM_MIRROR_PATH behavior.
To migrate to S3 Object Lock, set VERITAS_TRUSTLOG_MIRROR_BACKEND=s3_object_lock and provide at minimum VERITAS_TRUSTLOG_S3_BUCKET (plus optional prefix/region/retention settings).
VERITAS_TRUSTLOG_WORM_HARD_FAIL semantics are unchanged and apply to both backends.
In secure/prod, the startup validator requires mirror backends with both immutable_retention and fail_closed. Local WORM mirror is not secure/prod compliant in this release. The current production-supported backend satisfying this strict capability set is s3_object_lock; both VERITAS_TRUSTLOG_S3_BUCKET and VERITAS_TRUSTLOG_S3_PREFIX must be set.

TrustLog mirror verification modes

Offline mode (default): VERITAS_TRUSTLOG_VERIFY_MIRROR_REMOTE=0 validates receipt schema only and keeps legacy compatibility.
Remote mode: VERITAS_TRUSTLOG_VERIFY_MIRROR_REMOTE=1 performs S3-backed checks for s3_object_lock receipts:
- object existence (Bucket + Key)
- version_id match (when receipt has version_id)
- etag match (when receipt has etag)
- retention state (when receipt records retention metadata)
Strict mode: VERITAS_TRUSTLOG_VERIFY_MIRROR_S3_STRICT=1 is intended for high-assurance/prod verification jobs:
- fails entries with missing mirror receipts (mirror_receipt_missing)
- fails retention verification gaps (mirror_retention_missing)
- can break verification for old ledgers created before receipt support.
Legal hold enforcement: VERITAS_TRUSTLOG_VERIFY_MIRROR_S3_REQUIRE_LEGAL_HOLD=1 additionally requires object legal hold to be ON (mirror_legal_hold_missing).

Security caveat: remote verification depends on live AWS API access and IAM permissions (s3:HeadObject, s3:GetObjectRetention, s3:GetObjectLegalHold). Use least privilege and isolate verifier credentials.

Replay

Variable	Default	Description
`VERITAS_REPLAY_STRICT`	`0` (posture: `1` in secure/prod)	Enforce deterministic replay settings
`VERITAS_REPLAY_REQUIRE_MODEL_VERSION`	`1`	Reject snapshots without model_version

Runtime

Variable	Default	Description
`VERITAS_POSTURE`	`dev`	Runtime posture (`dev`/`staging`/`secure`/`prod`). See Runtime Posture Guarantees.
`VERITAS_RUNTIME_ROOT`	`runtime/`	Root directory for runtime data
`VERITAS_RUNTIME_NAMESPACE`	`dev`	Runtime namespace (`dev`/`test`/`demo`/`prod`)

See .env.example for a complete template.

🔐 Security Notes (Important)

Warning

VERITAS is designed to fail closed, but safe-by-default does not mean safe-without-configuration. Before any beta deployment, verify secrets handling, encryption keys, WORM/transparency settings, and network exposure in your own environment.

Key beta-era security warnings

Do not expose the backend with placeholder secrets such as VERITAS_API_SECRET=change-me.
TrustLog encryption is mandatory in secure mode; missing VERITAS_ENCRYPTION_KEY will break writes by design rather than silently downgrading security.
Treat legacy pickle migration in MemoryOS as a temporary migration-only path because deserialization pathways are high risk.
Review BFF/server routing carefully; leaking internal API topology via public NEXT_PUBLIC_* variables weakens the intended boundary.

Credential and key management

API keys: Avoid exporting secrets directly in shell history where possible. Prefer .env files (git-ignored) or secret managers and inject them at runtime. Rotate keys regularly and limit scope/permissions.
Never use placeholder or short secrets: VERITAS_API_SECRET should be a long, random value (32+ chars recommended). Placeholder or short secrets can effectively disable or weaken HMAC protection.

API and browser-facing protections

CORS safety: avoid wildcard origins (*) when allow_credentials is enabled. Configure explicit trusted origins only via VERITAS_CORS_ALLOW_ORIGINS.
Content Security Policy (CSP): the frontend middleware injects per-request nonce-based CSP headers. connect-src 'self' restricts XHR/fetch to same origin.
BFF session cookie: __veritas_bff is httpOnly, Secure, SameSite=strict in production. Browser never sees API credentials.
Security headers: HSTS (1-year, preload), X-Frame-Options DENY, X-Content-Type-Options nosniff, Permissions-Policy (camera/mic/geo disabled).
Rate limiting & auth failure tracking: per-key rate limits with exponential backoff on repeated auth failures.
Nonce replay protection: critical operations protected by HMAC-signed nonces with TTL cleanup.
Request body size limit: configurable via VERITAS_MAX_REQUEST_BODY_SIZE (default 10 MB).

Data safety and persistence

TrustLog data: TrustLog is encrypted by default (secure-by-default). All entries are automatically redacted for PII/secrets and encrypted before persistence. VERITAS_ENCRYPTION_KEY must be set; without it, writes fail.
Automatic PII/secret redaction: Email, phone, address, API keys, bearer tokens, and secret-like strings are masked before storage — no manual redact() call required.
Encryption at rest (mandatory): Set VERITAS_ENCRYPTION_KEY (base64-encoded 32-byte key). Use generate_key() to create one. Store keys in a vault/KMS, never in source control.
Operational logs are excluded from Git: runtime logs (for example, runtime/<namespace>/.../*.jsonl) are ignored via .gitignore; anonymized samples live under veritas_os/sample_data/memory/.
Runtime namespaces are separated by purpose: default local paths are runtime/dev, runtime/test, runtime/demo, runtime/prod. You can override with VERITAS_RUNTIME_ROOT and VERITAS_RUNTIME_NAMESPACE.
Fresh-clone cleanup command: use python scripts/reset_repo_runtime.py --dry-run and python scripts/reset_repo_runtime.py --apply to remove generated runtime data. See also docs/ja/operations/runtime-data-policy.md.

Fail-closed safety pipeline

FUJI Gate fail-closed: all safety judgment exceptions return status=rejected, risk=1.0. No silent pass-through on error.
Governance boundary guard: /v1/fuji/validate returns 403 by default — explicit opt-in required (VERITAS_ENABLE_DIRECT_FUJI_API=1).
4-eyes approval: governance policy updates require 2 distinct approvers (no duplicates, enabled by default).
RBAC/ABAC: require_governance_access guard on governance management endpoints with role + tenant verification.
External secret manager enforcement: VERITAS_ENFORCE_EXTERNAL_SECRET_MANAGER=1 blocks startup without Vault/KMS integration.
Web search toxicity filter: retrieval poisoning / prompt injection heuristics with NFKC normalization, URL decode, base64 decode, and leet-speak detection. Enabled by default (fail-closed); disable with VERITAS_WEBSEARCH_ENABLE_TOXICITY_FILTER=0.

Migration safety

Legacy pickle migration is risky: if you enable legacy pickle migration for MemoryOS, treat it as a short-lived migration path and disable it afterward. Legacy pickle/joblib loading is blocked at runtime to prevent RCE.

🗺️ Roadmap (Near-Term)

Already delivered (previously listed as roadmap items):

✅ CI (GitHub Actions): three-tier validation model with pytest + coverage + artifact reports
✅ Security hardening: input validation, secret/log hygiene, runtime posture system
✅ Policy-as-Code: YAML/JSON → IR → compiled rules with Ed25519-signed bundles and auto-generated tests
✅ Multi-provider LLM: OpenAI (production), Anthropic/Google (planned), Ollama/OpenRouter (experimental)
✅ PostgreSQL storage backend: pluggable backend for MemoryOS and TrustLog with Alembic migrations, advisory-lock chain serialization, and full parity test suite (195+ tests). Includes JSONL → PostgreSQL import procedure, smoke/release validation integration, and legacy path cleanup. See docs/postgresql-production-guide.md.
✅ PostgreSQL production hardening: contention tests (25 tests), pool/activity metrics (28 tests), backup/restore/recovery drill scripts and tests (31 tests). See docs/postgresql-drill-runbook.md.
✅ Continuation Runtime (Phase-1): chain-level continuation observation layer with snapshot/receipt/enforcement event architecture. See docs/architecture/continuation_runtime_adr.md.
✅ Governance artifact signing: Ed25519-signed policy bundles, runtime signature verification, governance identity in decision outputs. See docs/governance_artifact_lifecycle.md.
✅ S3 Object Lock TrustLog mirror: WORM-compliant mirror backend with retention, legal hold, and remote verification. See docs/postgresql-drill-runbook.md.

Next milestones:

Promote Anthropic / Google LLM providers to production tier
Automatic coverage badge update from CI artifacts
pgvector integration for MemoryOS vector similarity search
Phased move from mono-repo licensing (Plan B) to multi-repo split (Plan A)
Continuation Runtime Phase-2 enforcement graduation from advisory to enforce-by-default in secure/prod posture

📄 License

This repository is a multi-license repository with clear directory scope.

日本語補助: このリポジトリは「Coreはプロプライエタリ」「Interfaceはオープン」の二層ライセンスです。

License matrix (scope by directory)

Scope	License	Commercial use	Redistribution	Notes
Default (entire repo unless overridden)	VERITAS Core Proprietary EULA (`/LICENSE`)	Contract required	Not permitted without written permission	Includes Core decision logic and pipeline
`spec/`	MIT (`/spec/LICENSE`)	Permitted	Permitted	Open interface artifacts
`sdk/`	MIT (`/sdk/LICENSE`)	Permitted	Permitted	SDK interface layer
`cli/`	MIT (`/cli/LICENSE`)	Permitted	Permitted	CLI interface layer
`policies/examples/`	MIT (`/policies/examples/LICENSE`)	Permitted	Permitted	Policy templates/examples

Core abuse-prevention restrictions (high level)

Under the Core Proprietary EULA, you may not:

provide Core (or substantially similar functionality) as a competing managed service;
bypass license keys, metering, or other technical protection controls;
remove copyright, attribution, proprietary notice, or trademark markings;
redistribute Core or use Core for commercial production use without a commercial agreement.

See LICENSE, TRADEMARKS, and NOTICE.

Transition note for existing users

The current structure formalizes existing intent into a clearer two-tier model:

Core remains proprietary by default.
Interface assets are explicitly open-licensed by directory.
No Core logic (Planner/Kernel/FUJI/TrustLog pipeline internals) is open-sourced by this change.

Roadmap: phased move from mono-repo licensing (Plan B) to multi-repo split (Plan A)

Phase 1 (current):

Directory-scoped licensing in this mono-repo (Core proprietary + interface MIT)

Phase 2 (upcoming):

veritas-spec (OpenAPI/schema)
veritas-sdk-python, veritas-sdk-js
veritas-cli
veritas-policy-templates
Keep veritas_os focused on proprietary Core only

For academic use, please cite the Zenodo DOI.

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines, including:

Repository license model (Core is proprietary; interfaces are MIT)
Development setup and coding standards
Pull request workflow and review process
Security vulnerability reporting via SECURITY.md

📝 Citation (BibTeX)

@software{veritas_os_2025,
  author = {Fujishita, Takeshi},
  title  = {VERITAS OS: Auditable Decision OS for LLM Agents},
  year   = {2025},
  doi    = {10.5281/zenodo.17838349},
  url    = {https://github.com/veritasfuji-japan/veritas_os}
}

📞 Contact

Issues: https://github.com/veritasfuji-japan/veritas_os/issues
Email: veritas.fuji@gmail.com

Reviewer Evidence Packet key provenance references

An illustrative sample artifact chain is available in samples/evidence_bundle/key_provenance_review/. Use it only to inspect expected file relationships; the samples do not create trust, do not replace out-of-band public key trust, do not prove regulatory certification, and are not completed third-party audit approval. Matching fingerprints support correlation only, not standalone trust. The sample set now includes sample-artifact-manifest.json to index expected artifacts, roles, schemas, and SHA-256 digests, plus reviewer-handoff-review-result.json as a reviewer Review Result / Acceptance Record and saved reviewer result validation reports (reviewer-review-result-validation.json and reviewer-review-result-report-validation.json), plus the saved package validation report reviewer-handoff-package-validation.json. These saved reports demonstrate validation output shape and validation status only; they do not create trust, replace out-of-band public key trust, prove regulatory certification, represent completed third-party audit approval, or establish cryptographic truth by themselves. CI validates the sample artifact chain, manifest, and artifact hashes for structure, JSON Schema conformance, fixed artifact references, and forbidden sensitive/raw diagnostic patterns only; hash matching supports sample integrity, not standalone trust. CI validation does not create trust, replace out-of-band public key trust, prove regulatory certification, or indicate completed third-party audit approval. The reviewer result records what was checked and a decision of ACCEPT, REJECT, or NEEDS_FOLLOW_UP; it is not certification by itself, not regulatory approval, not completed third-party audit approval, and not cryptographic truth by itself. Reviewer decisions depend on reviewer scope and out-of-band public key trust context. Use veritas-evidence-bundle validate-review-result --result reviewer-handoff-review-result.json --json --output reviewer-review-result-validation.json to validate the saved review result artifact, its schema conformance, acknowledgement structure, required artifact references, decision value, and forbidden sensitive/raw diagnostic patterns. The --json output has a stable JSON Schema contract at schemas/reviewer_handoff_review_result_validation_report.schema.json, which validates the validation report shape. The command records validation status and checks review-result structure only: it does not create trust, does not replace out-of-band public key trust, does not prove regulatory certification, is not completed third-party audit approval, and does not establish cryptographic truth by itself. Use veritas-evidence-bundle validate-review-result-report --result reviewer-review-result-validation.json --json --output reviewer-review-result-report-validation.json to validate the saved validation report emitted by validate-review-result --json. This second-level command validates report shape only; it does not re-run reviewer review, create trust, replace out-of-band public key trust, prove regulatory certification, indicate completed third-party audit approval, or establish cryptographic truth. It records validation-report structure, not cryptographic truth by itself. Its JSON output has a stable JSON Schema contract at schemas/reviewer_handoff_review_result_report_validation_report.schema.json and remains boolean-only with fixed diagnostics. Use veritas-evidence-bundle validate-reviewer-handoff-package --manifest samples/evidence_bundle/key_provenance_review/sample-artifact-manifest.json --base-dir samples/evidence_bundle/key_provenance_review --json --output reviewer-handoff-package-validation.json to validate the illustrative sample handoff package structure from the manifest. The command checks manifest parsing, manifest schema conformance, artifact containment, artifact presence, SHA-256 digests, applicable schemas, expected names/roles/schema IDs, validator fields, synthetic placeholder fingerprints, and safety boundaries. Its report records validation status only and the checked-in sample demonstrates the output shape of validate-reviewer-handoff-package --json; it does not create trust, replace out-of-band public key trust, prove regulatory certification, indicate completed third-party audit approval, or establish cryptographic truth by itself. Sample hashes support sample integrity only. The reviewer handoff quickstart command guard also supports --json and optional --output reviewer-handoff-quickstart-command-validation.json for a machine-readable report under schemas/reviewer_handoff_quickstart_command_validation_report.schema.json. The sample package includes checked-in reviewer-handoff-quickstart-command-validation.json so reviewers can inspect the expected machine-readable report shape, and CI validates it with the sample manifest. The saved quickstart command validation report can now be independently validated with veritas-evidence-bundle validate-quickstart-command-report --result samples/evidence_bundle/key_provenance_review/reviewer-handoff-quickstart-command-validation.json --json --output samples/evidence_bundle/key_provenance_review/reviewer-handoff-quickstart-command-report-validation.json. The second-level report validates the saved report shape and fixed metadata only. The checked-in quickstart command validation report and its second-level validation report are sample validation artifacts and are not trust sources by themselves. They record validation status only, do not create trust, do not replace out-of-band public key trust, do not prove regulatory certification, are not completed third-party audit approval, and do not establish cryptographic truth by themselves.

The checked-in reviewer handoff sample validation reports are CI-validated and also regeneration-checked against current CLI behavior. The regeneration gate recreates reviewer-review-result-validation.json, reviewer-review-result-report-validation.json, reviewer-handoff-package-validation.json, reviewer-handoff-quickstart-command-validation.json, and reviewer-handoff-quickstart-command-report-validation.json in a temporary directory and compares normalized JSON with the repository copies. This reduces drift between CLI output and documented samples, but validates sample reproducibility only. It does not create trust, replace out-of-band public key trust, prove regulatory certification, indicate completed third-party audit approval, or establish cryptographic truth. Sample hashes support sample integrity only, and validation reports record validation status, not cryptographic truth by themselves.

Reviewer Evidence Packets may include optional Trusted Public Key Provenance validation artifact references (trusted-public-key-provenance.json, key-provenance-validation.json, and key-provenance-result-validation.json). Use the Reviewer Key Provenance Walkthrough for the copyable review sequence and the Reviewer Handoff Guide for what to send, what to verify, and what not to infer. These references help reviewers check public key trust provenance, but the packet does not create trust, does not re-run cryptographic verification, does not replace out-of-band public key trust, is not regulatory certification, and is not completed third-party audit approval. Matching fingerprints support correlation only; they are not standalone trust proof. Reviewer Evidence Packets reference artifacts; they do not prove trust alone. Packet metadata references fixed artifact names and schema identifiers only, not raw fingerprints, raw local paths, exception text, schema validator messages, or externally supplied JSON values.

Name		Name	Last commit message	Last commit date
.chainlit		.chainlit
.github		.github
alembic		alembic
artifacts/real-decision-to-effect-e2e		artifacts/real-decision-to-effect-e2e
cli		cli
config		config
configs		configs
docs		docs
examples		examples
fixtures		fixtures
frontend		frontend
licenses		licenses
packages		packages
policies		policies
runtime		runtime
samples/evidence_bundle/key_provenance_review		samples/evidence_bundle/key_provenance_review
schemas		schemas
scripts		scripts
sdk		sdk
security/sbom		security/sbom
spec		spec
tests		tests
veritas_os		veritas_os
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.gitleaks.toml		.gitleaks.toml
.pre-commit-config.yaml		.pre-commit-config.yaml
.python-version		.python-version
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
Dockerfile.verifier		Dockerfile.verifier
LICENSE		LICENSE
Makefile		Makefile
NOTICE		NOTICE
README.md		README.md
README_JP.md		README_JP.md
SECURITY.md		SECURITY.md
THIRD_PARTY_NOTICES		THIRD_PARTY_NOTICES
TRADEMARKS		TRADEMARKS
alembic.ini		alembic.ini
chainlit_app.py		chainlit_app.py
docker-compose.yml		docker-compose.yml
docs_repo_consistency_review_2026-04-14.md		docs_repo_consistency_review_2026-04-14.md
openapi.yaml		openapi.yaml
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
pyproject.toml		pyproject.toml
requirements-dev.txt		requirements-dev.txt
ruff.toml		ruff.toml
setup.sh		setup.sh

Latest commit

History

Folders and files

Repository files navigation

VERITAS OS v2.0 — Decision Governance and Bind-Boundary Control Plane for AI Agents

Architecture at a Glance

External bind adapter reference

Minimal Python SDK reference

Reviewer Evidence Documentation

External reviewer fast path

LLM-to-Control-Plane Boundary

Evaluation Governance reviewer artifacts

Authority Evidence Ingestion

Human Approval Receipt v1

Outcome Receipt v1

SaaS Permission-Change Governed Execution Demo

Reviewer Evidence Packet v1

Bind Coverage Registry v1

Evidence Chain Manifest v1

One-Day PoC Evidence Packet

AML/KYC Reviewer Walkthrough Quickstart

Governance Review Workflow

Development-time Observe Mode

Version

What VERITAS OS is

What problem it solves

Why bind-boundary control matters

How it differs from runtime/orchestration tools

Why this fits regulated / enterprise use

What VERITAS OS is / is not

Fact vs roadmap (read this first)

Regulated action governance fact (implemented)

Regulated action governance roadmap (not yet implemented)

Technical Maturity Snapshot (internal)

Quick Links

AML/KYC Beachhead PoC Pack (what you can run in 1 day)

🚀 Quick Start (TL;DR)

PostgreSQL Production Path & Validation Status

Guarantee boundary (current)

Contents

📊 Beta at a Glance

🔒 Runtime Posture Guarantees

Controls governed by posture

Governance artifact identity in decision outputs

What causes startup refusal (secure/prod)

TrustLog strict mirror capabilities in secure/prod

Escape hatches (secure posture only)

🎯 Why VERITAS?

💡 What It Does

/v1/decide — Full Decision Loop (Structured JSON)

Responsibility boundaries that matter

📁 Project Structure

💾 Storage Backends

Environment matrix

Quick switch

Migrating existing data (JSONL → PostgreSQL)

Verification tools

Key features of the PostgreSQL backend

Production deployment

🖥️ Frontend — Mission Control Dashboard

Tech Stack

Pages

Architecture

📡 API Overview

Decision

Memory

Trust & Audit

Governance

Bind artifact family: operator meaning

Operator workflow: promote a policy bundle

Compliance & Reporting

System

Replay

🚀 Quick Start

Option A: Docker Compose (Recommended)

Option B: Local Development

Backend

Frontend

Makefile shortcuts

Local Mac Development (No Docker)

`/v1/decide` — Full Decision Loop (Structured JSON)

What causes `require_human_review` vs `halt_chain`?