Engine Primitives

Low-level building blocks exposed from @withboundary/contract. All are pure, synchronous, and side-effect free.

import {
  clean,
  verify,
  classify,
  repair,
  instructions,
  createConsoleLogger,
} from "@withboundary/contract";

Usage guide: Engine primitives.

`clean`

function clean(raw: string | null): unknown;

Normalize raw LLM output into a parsed JSON value.

Input	Output
`null` / `""`	`null`
"```json\n{\"a\":1}\n```"	`{ a: 1 }`
`"Here's the answer: {\"a\":1}"`	`{ a: 1 }`
`"no json here"`	`null`
Malformed JSON	`null` (or the original raw — callers should still validate)

`verify`

function verify<T>(
  data: unknown,
  schema: ZodType<T>,
  rules?: Rule<T>[],
): ContractResult<T>;

Validate data against schema and, if provided, every rule. Returns the same ContractResult<T> shape contract.accept returns. No LLM involved.

result.ok === true → data passed schema and all rules. result.data is typed T.
result.ok === false → result.error.attempts[0] has the failure category ("VALIDATION_ERROR" or "RULE_ERROR") and the list of issues.

`classify`

function classify(raw: string, cleaned: unknown): FailureCategory;

Categorize a failed response. Returns one of:

"EMPTY_RESPONSE" | "REFUSAL" | "NO_JSON" | "TRUNCATED" |
"PARSE_ERROR" | "VALIDATION_ERROR" | "RULE_ERROR" | "RUN_ERROR"

Based on the combination of raw string and parsed result:

`raw`	`cleaned`	Category
`""` / `null`	—	`EMPTY_RESPONSE`
contains refusal language	`null`	`REFUSAL`
has text but no JSON	`null`	`NO_JSON`
starts valid, ends mid-token	`null` / partial	`TRUNCATED`
malformed JSON	`null`	`PARSE_ERROR`
valid JSON, wrong types	`unknown`	`VALIDATION_ERROR`
right types, rule failed	`T`	`RULE_ERROR`

`repair`

function repair(
  detail: AttemptDetail,
  overrides?: Partial<Record<FailureCategory, RepairFn | false>>,
): Message[] | false;

Generate repair messages for a failed attempt. Returns:

Message[] — messages to feed back to the model.
false — the category is disabled (via overrides[category] = false), caller should not retry.

`overrides` shape

type RepairFn = (detail: AttemptDetail) => Message[];

type RepairOverrides = Partial<Record<FailureCategory, RepairFn | false>>;

false — skip retry for this category.
(detail) => Message[] — build custom repair messages for this category.

`instructions`

function instructions<T>(
  schema: ZodType<T>,
  options?: { suffix?: string },
): string;

Generate prompt text from a Zod schema. Includes field types, enums, ranges, and .describe() annotations.

const schema = z.object({
  tier: z.enum(["hot", "warm", "cold"]).describe("lead temperature"),
  score: z.number().min(0).max(100),
});

console.log(instructions(schema));
// Return JSON matching:
// {
//   "tier": one of "hot" | "warm" | "cold" — lead temperature,
//   "score": number (0-100)
// }

The suffix option appends additional text verbatim:

instructions(schema, { suffix: "\nBe concise." });

Called automatically inside contract.accept and available on attempt.instructions.

`createConsoleLogger`

function createConsoleLogger<T = unknown>(
  options?: ConsoleLoggerOptions,
): ContractLogger<T>;

Built-in human-readable logger. Implements the full ContractLogger surface and prints formatted traces to console.log.

`ConsoleLoggerOptions`

Option	Type	Default	Description
`prefix`	`string`	`"[contract]"`	Prepended to every line
`showInstructions`	`boolean`	`false`	Print the auto-generated prompt on `onAttemptStart`
`showRepairs`	`boolean`	`false`	Print repair messages on `onRepairGenerated`
`showRawOutput`	`boolean`	`false`	Print `raw` on `onRawOutput`
`showCleanedOutput`	`boolean`	`false`	Print `cleaned` on `onCleanedOutput`
`showSuccessData`	`boolean`	`false`	Print the accepted `data` on `onRunSuccess`
`maxStringLength`	`number`	`1000`	Truncate printed strings over this length

defineContract({
  schema,
  rules,
  logger: createConsoleLogger({
    showInstructions: true,
    showRepairs: true,
    maxStringLength: 500,
  }),
});

The debug: true option on defineContract / enforce is equivalent to logger: createConsoleLogger().