Witnora Framework

Open contracts and customer-owned runtime components for verifiable AI-agent assurance.

Witnora Framework helps teams record covered Agent activity, place consequential actions behind an explicit control boundary, independently observe outcomes, and verify the resulting evidence without trusting a hosted dashboard or a language model's summary.

It is the public, Apache-2.0 foundation used by the commercial Witnora product. The Framework is useful on its own for inspectable integrations and offline verification; Hosted Witnora adds the multi-tenant Control Plane, Nora, missions, customer workflows, and production operations.

Coverage is explicit. Witnora makes claims only about declared, instrumented, and reconciled action paths. It does not claim that an entire Agent is reliable or safe.

Why this exists

Ordinary traces can show that an Agent called a tool. They do not, by themselves, prove that the Agent was authorized, that the action was forced through a controlled credential boundary, or that the expected business result was independently observed.

Witnora Framework separates those claims and gives each one a portable, machine-verifiable record:

1. Identity and scope — which Agent, version, environment, task, and action path the record covers.
2. Authority — which policy, mandate, approval, or execution grant allowed the action.
3. Execution — whether the action was merely reported, recorded by a customer-owned boundary, or enforced through a controlled adapter.
4. Outcome — whether a separate read-only Probe observed the expected state.
5. Evidence — canonical records, signatures, hash-linked events, limitations, and offline verification.

Evidence is not a single boolean

The Framework preserves the strongest claim actually supported by the collected evidence. A weaker record is never silently promoted to a stronger one.

Level	What it establishes
REPORTED	An Agent, test, or producer reported an event.
RECORDED	A trusted customer-operated recorder captured and reconciled it.
ENFORCED	The action passed through the declared controlled execution boundary.
OUTCOME_VERIFIED	A separate read-only observation confirmed the bound result.
INDEPENDENTLY_REVIEWED	An independent reviewer assessed a defined evidence scope.

RECORDED is not ENFORCED. ENFORCED is not OUTCOME_VERIFIED. Automated testing is not an independent review.

How the pieces fit together

flowchart LR
    A["Customer Agent"] --> B["SDK or MCP adapter"]
    B --> C["Customer-owned Gateway / Runtime"]
    C -->|"controlled action"| D["Business system"]
    C --> E["Signed records"]
    P["Read-only Probe"] -->|"independent read"| D
    P --> F["Signed outcome attestation"]
    E --> V["Offline verifier"]
    F --> V
    E -. "optional metadata" .-> H["Hosted Witnora"]
    F -. "optional attestation" .-> H

Loading

The Agent does not approve its own high-risk action. The Probe does not receive write credentials. Hosted Witnora cannot replace customer signatures, policy decisions, or observed outcomes with model-generated claims.

Choose the right entry point

Goal	Start here
Record tool and run metadata from TypeScript	packages/agentcert-sdk
Instrument LangGraph, OpenAI Agents SDK, browser-use, or Python tools	packages/agentcert-sdk-python
Wrap MCP tool calls with the same assurance semantics	packages/agentcert-mcp-adapter
Build a controlled action boundary, Replay, or Shadow evaluation	packages/onegent-runtime
Observe an outcome with a separate read-only service	packages/witnora-probe
Verify canonical records, signatures, revocations, and event chains offline	packages/witnora-verifier-python
Implement the v0.2 protocols in another language	docs/specifications and test-vectors

Some package and schema identifiers retain the historical agentcert name for wire compatibility. New product-facing integrations should use the Witnora name; compatibility identifiers are documented rather than silently renamed.

Five-minute Zero-to-Receipt

The fastest way to see why Witnora is more than Agent logging is to run one real, local control loop. The example uses a sandbox purchase-order system and no external credentials:

git clone https://github.com/Kakarottoooo/witnora-framework.git
cd witnora-framework
npm run demo:zero-to-receipt

Review the exact action in the terminal and type y to approve it. The example then:

1. binds the Agent request to a signed mandate;
2. records a separate human approval;
3. executes through a credential-isolated controlled adapter;
4. uses a separate read-only Probe to observe DRAFT -> SUBMITTED;
5. verifies the customer signature and writes a human-readable receipt.

Open .witnora/zero-to-receipt/receipt.html. The accompanying receipt.json, hash-linked journal, and full audit packet remain available for machine verification. Rejecting the prompt performs no write and issues no outcome receipt.

This public walkthrough produces a customer-signed local receipt at OUTCOME_VERIFIED. Hosted Witnora additionally binds Project, Agent version, Business Task, approval grant, execution, Probe result, and server attestation into a server-issued Action Assurance Receipt. The local example does not claim that Hosted issuance or independent third-party review occurred.

Full Framework quick start

1. Clone and check the complete public Framework

Requirements: Node.js 20+ and Python 3.10+.

git clone https://github.com/Kakarottoooo/witnora-framework.git
cd witnora-framework

npm run install:js
npm run check:js
python -m pip install -e packages/witnora-verifier-python
python -m unittest discover -s packages/witnora-verifier-python/tests -v

The JavaScript check builds and tests the public Runtime, TypeScript SDK, Probe, and MCP adapter. The Python tests exercise strict canonicalization, trust roots, signatures, revocation, Probe binding, event chains, and offline verification.

2. Verify the shared conformance corpus offline

witnora-verify conformance test-vectors/witnora-v0.2-conformance

No network access or Witnora account is required. The fixture contains deterministic test keys only. A trust root carried inside an evidence packet cannot authorize itself; callers must pin the trust root they accept.

3. Inspect one covered-action receipt

The repository includes valid, revoked, disputed, and tampered receipt fixtures:

schemas/action-assurance-receipt/v0.1/
├── valid/enforced-receipt.json
├── revoked/revoked-receipt.json
├── disputed/disputed-receipt.json
└── invalid/tampered-receipt.json

Use these fixtures with the schema and verifier when implementing a compatible producer, gateway, receipt viewer, or audit export.

Use it with Hosted Witnora

The supported end-user setup path is the packaged Witnora CLI, not manual assembly of SDK credentials:

npx witnora@latest onboard --project <project-id>

The CLI authorizes one repository, starts the customer-owned Gateway, detects local Agent metadata, and writes missing-only integration files. Hosted Witnora then turns signed Framework records into Agent views, responsibility decisions, human-readable evidence, and shareable receipts.

The hosted product is optional for offline verification and custom Framework integrations. It is required for Witnora's managed Control Plane, Nora, hosted approval workflow, and commercial operations.

Public modules

Contracts and schemas

schemas contains versioned contracts for identity, mandates, assurance scope, evidence, signatures, receipts, approvals, execution grants, change manifests, deployment enforcement, and Probe attestations.

The schemas describe the record shape. They do not prove that a producer actually controlled an external system; that depends on the runtime boundary and evidence attached to the claim.

Customer integration SDKs

The TypeScript and Python SDKs provide bounded run recording, tool semantics, runtime context, privacy-aware envelopes, and framework adapters. Approval tools are intentionally absent from Agent credentials.

Producer-side wrappers can establish REPORTED or RECORDED evidence. Stronger claims require a credential-isolated controlled adapter and, for business outcomes, a separate Probe.

MCP adapter

The MCP adapter applies the same capability and event semantics to MCP tools. Unknown or newly discovered tools remain pending until they are mapped and reviewed; an Agent credential cannot approve its own capability.

Runtime safety core

packages/onegent-runtime contains inspectable primitives for:

• policies, immutable mandates, risk decisions, and approvals;
• credential-isolated controlled adapters and idempotent execution;
• signed action records and crash-recoverable journals;
• sandbox enforcement and adapter conformance;
• Business Task Replay and zero-write Shadow evaluation;
• independent outcome verification contracts.

The checked-in adapters and examples are deterministic local infrastructure. Commercial Provider implementations and customer production credentials are not part of this repository.

Customer-operated Probe

@witnora/probe is a separate read-only observation sidecar. It verifies tightly bound signed requests, resolves the read credential only inside the customer environment, stores raw observations locally, and returns a signed commitment-based attestation.

The Probe never accepts a credential value in an observation request. Its attestation proves only the configured read and predicate; it does not authorize the original write.

Offline verifier and conformance vectors

The Python verifier fails closed on duplicate JSON keys, ambiguous numbers, invalid signatures, untrusted roots, revoked keys, broken event chains, expired requests, and mismatched Probe bindings.

The shared vectors allow independent implementations to reproduce the canonical bytes and verification result without contacting Witnora.

Security and privacy model

• Customer write and read credentials stay in customer-controlled processes.
• Probe requests carry credential references, never credential values.
• Raw target observations remain in encrypted customer-controlled storage.
• Public fixtures use synthetic data and deterministic test keys.
• Unknown capabilities and invalid bindings fail closed.
• Canonical records are signed and important sequences are hash-linked.
• Replay uses sanitized historical or synthetic inputs.
• Shadow observes candidate behavior without exposing a production write path.
• Model output cannot sign evidence, approve an action, or create a trust root.

Custom adapters are part of the trust boundary. Their operators remain responsible for credential scope, target allowlists, redaction, storage, deployment isolation, and accurately declaring what the adapter controls.

Read the security material before connecting a real system:

• Privacy and egress matrix
• Probe isolation
• Trust bootstrap
• Trust root and key lifecycle
• Crash recovery and reconciliation

What this repository does not contain

• the hosted multi-tenant Control Plane or Dashboard;
• Nora intelligence, mission orchestration, or model routing;
• customer datasets or scenario-learning operations;
• commercial Provider implementations;
• production deployment, billing, support, or tenant operations;
• a universal guarantee that an Agent is safe or reliable;
• an official certification against AIUC-1, NIST, OWASP, or another standard.

The standards documents are implementation mappings and review aids, not claims of endorsement or certification.

Repository map

packages/
  agentcert-sdk/              TypeScript integration and customer Gateway primitives
  agentcert-sdk-python/       Python client and Agent framework adapters
  agentcert-mcp-adapter/      MCP coverage adapter
  onegent-runtime/            Controlled runtime, sandbox, Replay, and Shadow core
  witnora-probe/              Customer-operated read-only outcome observer
  witnora-verifier-python/    Independent offline verifier
schemas/                      Portable evidence and control contracts
test-vectors/                 Cross-implementation canonical fixtures
formal/                       TLA+ privacy-verifiable action-loop model
docs/adr/                     Public architectural decisions
docs/specifications/          Versioned protocol specifications
docs/security/                Threat models and privacy boundaries
docs/standards/               Non-certifying standards mappings

Open-core relationship and provenance

This repository is a curated, reproducible public projection of the private commercial Witnora monorepo. This prevents public and commercial editions from developing two competing policy engines, receipt formats, or state machines.

FRAMEWORK_SOURCE.json identifies the exact commercial source commit used for an export. OPEN_CORE_BOUNDARY.md defines the stable split. The export rejects closed paths and forbidden commercial references before publication.

Commercial implementations consume versioned public interfaces. They may derive views and recommendations from Framework records, but cannot replace their signatures, policy decisions, receipts, or observed outcomes.

Contributing

Issues and focused contributions to public contracts, SDKs, Runtime primitives, Probe behavior, verifier behavior, documentation, and conformance vectors are welcome in this repository.

Before proposing a change:

npm run install:js
npm run check:js
python -m pip install -e packages/witnora-verifier-python
python -m unittest discover -s packages/witnora-verifier-python/tests -v

Protocol changes should include a versioned specification, positive and negative vectors, and an independently executable verifier path. Security changes should state the exact claim boundary and the failure behavior.

Because this is a generated public projection, maintainers may land the canonical implementation in the commercial source repository and publish a new projection rather than editing generated provenance by hand.

License and trademarks

Framework code and documentation are licensed under the Apache License 2.0. “Witnora” and related marks are governed separately by TRADEMARKS.md.