Architecture

Compatibility: Pactmark 0.1.x. All packages share one release version for the v0.1 line and are published with per-package provenance.

The shape of the system

Figure 1. The kernel is provider-neutral by construction. core, runtime, policy, evidence and agent avoid Node built-ins, environment reads and provider SDKs, which is what lets the same agent implementation run on Node, a Next.js route and a Cloudflare Worker.

What each layer owns

Portable kernel — core, runtime, policy, evidence, agent

core holds the domain: schemas, ports, events, authority types and the stable KAF_* error registry. runtime orchestrates runs over those ports. policy implements default-deny decisions, grants, canonicalization, kill switches and effect strategies. evidence handles content-addressed artifacts, verification, redaction and pattern maturity. agent is the ergonomic authoring surface most applications import.

Execution and test — executor-in-process, testing

executor-in-process runs declared tools in-process and provides fail-closed egress brokers. testing supplies fake clocks, deterministic IDs, fake model drivers, crash injection and reusable adapter contract suites — and is never part of a production export.

Storage and workers — store-memory, store-postgres, driver-postgres-worker

store-memory is deterministic, tenant-scoped and explicitly ephemeral. store-postgres provides durable tenant-scoped stores. driver-postgres-worker implements the fenced lease loop that lets a wake-up be claimed by exactly one worker.

Transport and protocol — http, node, vercel, cloudflare, mcp

http implements Web-standard handlers for the whole command surface. node bridges to node:http with graceful shutdown. vercel is a thin Next.js route adapter. cloudflare is the experimental Worker subset. mcp is a guarded Model Context Protocol client that treats all discovered metadata as untrusted.

Integration and tooling — ai-sdk, otel, cli, create-pactmark

ai-sdk adapts the Vercel AI SDK without letting its types enter core APIs. otel emits opt-in, metadata-only telemetry. cli provides the pactmark binary over injected host adapters. create-pactmark is the deterministic offline initializer.

The dependency rule that keeps it honest

Core must not depend on a proprietary model gateway, provider HTTP client, platform SDK, deployment CLI, telemetry exporter, or hosted database SDK.

This is enforced by dependency-boundary checks in CI, not by review discipline. Practically it means you can swap Postgres for another durable store, or the AI SDK for a direct provider client, without touching a single line of run semantics.

Dependency	Owning package	Why it is allowed there
Zod	`core` and schema-owning packages	One runtime-validation truth with TypeScript inference
Postgres driver	`store-postgres`	Durable stores over a conventional `DATABASE_URL`, not a vendor
Vercel AI SDK	`ai-sdk`	Optional peer; its types never enter core APIs
MCP TypeScript SDK	`mcp`	Optional and guarded; server output stays untrusted
OpenTelemetry API	`otel`	Optional peer; remote export is off by default

What you actually import

For most applications the answer is short:

// Authoring and running
import { defineAgent, defineTool, createRuntime } from "@pactmark/agent";

// Executing declared tools with a fail-closed egress broker
import {
  createDeclaredToolExecutor,
  createDenyAllEgressBroker,
} from "@pactmark/executor-in-process";

// Exposing it over HTTP
import { createAgentFetchHandler } from "@pactmark/http";

Everything else — stores, workers, telemetry, MCP — is added when you need that specific capability, and each one arrives as an explicit constructor argument rather than a hidden default.

How a run moves through the layers

Figure 2. Read the third column as the answer to “which package is responsible when this stage refuses”. Nothing in it belongs to the model adapter.

Portability in practice

The portable-agent example calls one unchanged agent implementation through Node, Vercel and Cloudflare-shaped entrypoints, using the same deterministic fixture, and returns a normalized contract result from all three.

Portability is about the kernel, not about capability. A Cloudflare Worker cannot offer Node-only executors, stdio MCP, local filesystem assumptions or the Postgres worker. Unsupported capability metadata fails closed rather than degrading — see Cloudflare Worker preview.

Package reference

All nineteen packages with their exports and boundaries.

Production data flow

The same architecture annotated with trust boundaries and operator responsibilities.

Getting started

Core concepts

Guides

Deployment

Production

Security

The shape of the system

What each layer owns

The dependency rule that keeps it honest

What you actually import

How a run moves through the layers

Portability in practice

Package reference

Production data flow

​The shape of the system

​What each layer owns

​The dependency rule that keeps it honest

​What you actually import

​How a run moves through the layers

​Portability in practice

Package reference

Production data flow

The shape of the system

What each layer owns

The dependency rule that keeps it honest

What you actually import

How a run moves through the layers

Portability in practice