JanusState

Trust outcomes, not claims.

An independent outcome-verification layer for AI agents.

Watch the Devpost demo · View the public repository

Table of Contents

• Why JanusState
• How It Works
• Key Functionality
• Architecture
• Three-Minute Demo Path
• Stack
• Setup
• Fictional Demo Data
• API Reference
• Trust and Security
• Built with Codex and GPT-56
• Verification
• Limitations and Roadmap
• Devpost Details
• License

Why JanusState

JanusState independently verifies AI-agent completion claims against business-system evidence, applies deterministic contract assertions, and generates integrity-checked receipts.

The problem

An agent can confidently report success while async or downstream work is still incomplete. A payment submission may be accepted while settlement remains pending; a CRM update may succeed while a required inventory reservation fails. Tool success is not business-outcome proof.

JanusState is the independent verifier. It does not perform the worker agent's business task.

How It Works

1. A worker or fulfillment agent submits an untrusted completion claim.
2. JanusState reads independent, read-only connector evidence.
3. Deterministic assertions compare expected and observed state.
4. Policy returns exactly VERIFIED, PARTIAL, FAILED, or UNCERTAIN.
5. A Janus Receipt records cited provenance and a SHA-256 integrity hash.

Key Functionality

• Gemini-assisted, schema-constrained verification-contract drafting.
• Browser-local human editing and authoritative structural validation of a temporary candidate.
• Provider-neutral AI boundaries for contract drafting and the fictional Fulfillment Agent.
• Idempotent completion-event ingestion and process-local orchestration.
• Fictional read-only CRM, payments, inventory, and messaging connectors.
• Deterministic assertion evaluation, evidence normalization, and verdict aggregation.
• Safe verification detail views plus integrity-checked receipt viewing and JSON export.
• Agent Reliability Lab: honest completion → VERIFIED; premature payment success → PARTIAL.

Architecture

flowchart LR
  A[Customer or worker agent] --> B[JanusState API]
  B --> C[Verification contract]
  C --> D[Read-only connectors]
  D --> E[Deterministic evaluator]
  E --> F[Verdict policy]
  F --> G[Janus Receipt with SHA-256 integrity]

Loading

The contract determines what to check; the claim never supplies evidence or decides the verdict. See Architecture.md, PRD.md, Design.md, and Rules.md for the authoritative product and trust boundaries.

Three-Minute Demo Path

1. Open Overview (/) to establish the claim → evidence → policy → receipt model.
2. Open Contracts (/contracts) and draft/review/validate a temporary contract candidate. Validation does not save, activate, or execute it.
3. Open Agent Lab (/agent-lab) and run Honest completion.
4. Observe the fictional agent's COMPLETED report and JanusState's independent VERIFIED result.
5. Run Premature payment success. The agent reports completion after payment submission, while independent payment state is pending; JanusState returns PARTIAL.
6. Open the verification detail and the integrity-checked receipt link from the result.

All scenarios, connector records, and agent-visible transcripts are fictional demonstration data.

Stack

Area	Technology
Application	Next.js 16 App Router, React 19, TypeScript
Validation	Zod
Optional runtime AI	Gemini via @google/genai (gemini-flash-lite-latest)
Data boundary	Prisma / PostgreSQL-ready boundary; no durable runtime persistence yet
Testing	Vitest, Playwright
Quality	ESLint, Prettier
Runtime	Node.js 24

Setup

Prerequisites

• Node.js 24.18.0 (see .nvmrc); the project engine range is >=24 <25.
• npm 11 or newer.
• A modern Chromium-based browser for the tested UI.
• Optional: a Gemini API key for live contract drafting or Agent Lab calls.

Install and run

git clone <your-fork-or-clone-url>
cd JanusState
nvm use
npm install
cp .env.example .env.local
npm run dev

On Windows PowerShell, invoke npm through npm.cmd without changing execution policy:

nvm use
npm.cmd install
Copy-Item .env.example .env.local
npm.cmd run dev

Open http://localhost:3000. The health check is available at http://localhost:3000/api/health.

Environment variables

Copy .env.example and keep .env.local private. GEMINI_API_KEY stays server-side and must never be committed or placed in browser code.

Variable	Required for	Notes
GEMINI_API_KEY	Live Gemini contract drafting and Agent Lab calls	Optional; missing configuration returns a safe unavailable state.
AI_PROVIDER=gemini	Gemini provider selection	The only configured runtime provider.
AI_CONTRACT_DRAFTING_ENABLED=true	Contract-drafting UI/API	Does not activate or execute contracts.
GEMINI_MODEL	Optional model override	Defaults to gemini-flash-lite-latest.
DATABASE_URL	Prisma validation tooling	Use a safe local non-production URL for validation; no hosted database connection is required.
OPENAI_API_KEY	Reserved future OpenAI/GPT-5.6 runtime adapter	Not used by the current Gemini runtime.

Validation commands

npm run format
npm run lint
npm run typecheck
npm test
npm run test:e2e
npm run prisma:validate
npm run build

For a safe Prisma validation command without a real database credential:

$env:DATABASE_URL = "postgresql://USER:PASSWORD@localhost:5432/janusstate"
npm.cmd run prisma:validate

Use npm.cmd in Windows PowerShell for every npm command. Playwright is configured for Chromium and starts its local server unless an external server is configured.

Fictional Demo Data

JanusState ships only clearly fictional mock systems:

Connector	Evidence demonstrated
Mock CRM	Order ID, status, customer ID, update time
Mock Payments	Order ID, payment status, integer minor amount, currency, reference, settlement/update times
Mock Inventory	Order, reservation, SKU, requested/reserved quantities, reservation status, update time
Mock Messaging	Order, message/channel/recipient, delivery status, sent/delivered/update times

Fixed scenarios:

• Honest completion: CRM completed, payment settled, inventory reserved, message delivered → VERIFIED.
• Premature payment success: payment submission is accepted, but settlement is pending → PARTIAL despite the agent's COMPLETED claim.

Pending or failed business states are evidence, not connector outages. Record-not-found and source-unavailable remain distinct evidence states.

API Reference

All mutable endpoints validate input and use Cache-Control: no-store plus X-Content-Type-Options: nosniff where applicable. Process-local storage means data is non-durable and not cross-instance safe.

Route	Purpose	Important limitation
GET /api/health	Application health response	Does not inspect external systems.
POST /api/verifications	Ingest an idempotent completion event	Creates RECEIVED; generic HTTP ingestion does not start orchestration.
GET /api/verifications	Bounded safe run list	Process-local records only.
GET /api/verifications/:id	Safe run status projection	Excludes claims, evidence, and internal errors.
GET /api/verifications/:id/detail	Safe detail/assertion/provenance projection	Read-only; does not trigger verification.
GET /api/verifications/:id/receipt	Integrity-check and return/download a stored receipt	Missing or damaged receipts are not regenerated.
POST /api/demo/scenarios/:id/run	Run fixed deterministic Demo Lab scenarios	Only VERIFIED_ORDER and PENDING_PAYMENT_FALSE_SUCCESS.
POST /api/demo/agent-scenarios/:id/run	Run fixed fictional Fulfillment Agent scenarios	Requires configured Gemini; only HONEST_COMPLETION and PREMATURE_PAYMENT_SUCCESS.
POST /api/contracts/draft	Create a temporary AI-assisted proposal	Never saves, activates, or executes a contract.
POST /api/contracts/accept	Structurally validate a temporary edited candidate	Returns temporary validation metadata only; no persistence or activation.

Supported Platforms

• Local Windows, macOS, and Linux environments with Node.js 24.
• Modern Chromium-based browser for the tested interactive UI.
• A deployable Next.js runtime, with an important limitation: runs, receipts, and idempotency are process-local, non-durable, and single-instance. Durable multi-instance or serverless deployment requires persistence first.

Trust and Security

• Worker and Fulfillment Agent claims never become evidence.
• Model confidence never affects deterministic verdicts.
• AI may draft or report within a bounded schema; it cannot activate contracts or decide verdicts.
• Mock connectors are read-only toward fictional business systems.
• The receipt's SHA-256 checksum detects changes to a canonical payload. It is not a signature, blockchain proof, legal attestation, or persistence guarantee.
• Secrets remain server-side; no credentials are intentionally placed in client bundles, receipts, public API projections, or repository documentation.

Built with Codex and GPT-5.6

Codex using GPT-5.6 accelerated the implementation of product and architecture planning, runtime schemas and trust boundaries, deterministic truth tables, connector and evidence abstractions, idempotency and orchestration, receipt canonicalization, adversarial unit/integration/end-to-end testing, accessibility and responsive UI work, and the provider-neutral agent boundary.

Key decisions remained human-reviewed and are recorded in Architecture.md, Rules.md, Tasks.md, and Memory.md.

Runtime contract drafting and the Agent Reliability Lab use Gemini because the hackathon credits were Codex credits, not runtime OpenAI API credits. GPT-5.6 was used extensively through Codex to build the project; it is not represented as the current live runtime provider.

Verification

The following are the latest recorded, scoped results in Memory.md; no unrecorded full-suite total is claimed after P4.3 changes.

Scope	Recorded result
Agent Reliability Lab UI	Prettier PASS; focused ESLint PASS; TypeScript PASS; Playwright PASS — 3 tests in 8.5s; production build PASS — Next.js 16.2.10 in 40.1s.
Agent-scenario HTTP boundary and composition	Focused Vitest PASS — 8 tests in 3.34s; existing Demo and agent boundary Vitest PASS — 11 tests in 5.07s; production build PASS — Next.js 16.2.10 in 99.5s.
Contract workflow regression	Last recorded full Vitest run: 22 files, 186 tests in 17.32s; external-server Playwright: 15 tests in 27.3s; Prisma validation and production build passed at that checkpoint.

No live Gemini request was made in the recorded P4.3 implementation or browser tests.

Limitations and Roadmap

Current limitations:

• No durable PostgreSQL persistence for runs, receipts, or idempotency.
• No authentication, authorization, tenant isolation, or rate limiting.
• Only fictional read-only connector fixtures; no real connector plugins.
• No SDK packages for external callers.
• No webhooks, queue workers, or durable cross-instance idempotency.
• Contract candidates are temporary and browser-local; validation does not save, activate, or execute them.
• Receipt checksums are integrity hashes, not signing or attestation.

Production roadmap: add durable PostgreSQL state, authentication and tenant isolation, registered real read-only connector plugins, public SDK packages, webhook/queue execution, durable idempotency, and managed signing/attestation only if required.

Devpost Details

Field	Submission value
Hackathon category	Developer Tools
Public demo	This prototype is not hosted. Follow the local setup instructions below to run it.
YouTube demo	JanusState: Trust Outcomes, Not Claims
Public repository	github.com/Nathan-Asif/JanusState
Codex /feedback session ID	019f6cf8-2e3c-7041-9259-22d1c4392fbf

License

Released under the MIT License.