@tracegate/core

Core contracts, schemas, and policy primitives for TraceGate.

TraceGate core includes framework-neutral contracts, runtime wrapping, configurable policy defaults, redaction, replay fixture contracts, trace sinks, and matrix case schemas.

Use createHarness() and wrapTool() to validate tool input, evaluate policy, redact traces, record evidence, and emit ordered trace events. Use createRuntimeGate() when you need to observe, shadow, or enforce TraceGate behavior around an existing production tool dispatcher before migrating to a full harness integration. For client or host-dispatched tools, use preflightToolCall() before the host handler and reconcileToolCall() after output/evidence is available. Use createRuntimeReplayRecorder() to capture sanitized runtime-gate events and summaries that can become tracegate replay-runtime fixtures.

Install

pnpm add @tracegate/core

Example

import { createHarness, defineToolContract } from "@tracegate/core";
import { z } from "zod";

const contract = defineToolContract({
  name: "searchKnowledgeBase",
  riskTier: "read",
  inputSchema: z.object({ query: z.string() }),
});

const harness = createHarness();
const searchKnowledgeBase = harness.wrapTool(contract, async ({ query }) => {
  return { query, hits: [] };
});

CommonJS Apps

@tracegate/core is ESM-first. CommonJS apps can lazy-load the runtime helper without changing the whole project to moduleResolution: "node16" or moduleResolution: "nodenext":

import type { TraceGateCoreModule } from "@tracegate/core/cjs";

const { loadTraceGateCore } = require("@tracegate/core/cjs") as {
  loadTraceGateCore(): Promise<TraceGateCoreModule>;
};

async function main() {
  const { createRuntimeGate, defineToolContract } = await loadTraceGateCore();
}

This pattern is intended for legacy CommonJS/Jest hosts. New ESM projects should prefer static imports from @tracegate/core.

Exports

• tool contracts and risk tiers
• manifest and registry contract adapters
• harness runtime and trace sinks
• runtime gate rollout helpers
• multi-stage pre-call and post-call evidence reconciliation
• runtime replay recording helpers
• policy and approval helpers
• structured policy diagnostics
• redaction and placeholder-aware secret-leak detection
• standalone evidence record creation
• matrix case schemas
• replay fixture schemas, flexible output assertions, and JSONL parsers