lib.harness

@lssm-tech/lib.harness

The ./harness/* entries own the existing Harness operation, event, capability, view and presentation declarations and explicit registration helpers. ./harness/types preserves the original scenario and suite registry classes using the canonical portable registry base, alongside AssuranceSpec model types. Legacy ContractSpec imports forward to these same objects. Runtime orchestration uses these local registries without depending on the compatibility facade.

Website: https://contractspec.io

Harness orchestration, policy, evidence normalization, replay bundling, and evaluation runtime for controlled inspection and proof generation.

What It Provides

• Provides the mode-agnostic harness core used by higher-level runtime adapters and harness-aware workflows.
• Exports focused surfaces for assertions, evidence normalization, orchestration, policy classification, replay bundles, and shared types.
• Acts as the central execution model for controlled evaluation, proof generation, and inspection flows.
• Normalizes specialized Harness results into canonical QualityCheckResultV1 and QualityRunReceiptV1 evidence without redefining the quality protocol.
• Retries are explicit, recovered scenarios are reported as flaky, and real suite statistics remain separate from a single successful retry.
• Executes scenario setup and reset hooks through an explicit HarnessScenarioHookExecutor, enforces required evidence, and applies scenario success rules during evaluation.
• Runs agent-specific trials and graders with replay refs, artifact/evidence attachments, cost/latency aggregation, and redaction-leak checks.
• src/adapters/ contains runtime, provider, or environment-specific adapters.

Installation

npm install @lssm-tech/lib.harness

or

bun add @lssm-tech/lib.harness

Usage

Import the root entrypoint from @lssm-tech/lib.harness, or choose a documented subpath when you only need one part of the package surface.

Architecture

• src/assertions/ contains assertion-engine logic.
• src/evidence/ normalizes harness evidence into runtime-friendly shapes.
• src/orchestration/ runs suites and evaluation pipelines.
• src/policy/ classifies and applies harness policies.
• src/replay/ packages replay bundles and reproducible outputs.
• src/agent-evals/ runs deterministic or injected live agent evaluations and produces recommendation evidence.
• src/types.ts contains shared public types.

Public Entry Points

• Exports the root harness runtime plus assertion, evidence, orchestration, policy, replay, and type subpaths.
• Export . resolves through ./src/index.ts.
• Export ./assertions/engine resolves through ./src/assertions/engine.ts.
• Export ./evidence/normalizer resolves through ./src/evidence/normalizer.ts.
• Export ./orchestration/evaluation-runner resolves through ./src/orchestration/evaluation-runner.ts.
• Export ./orchestration/runner resolves through ./src/orchestration/runner.ts.
• Export ./policy/classifier resolves through ./src/policy/classifier.ts.
• Export ./policy/local-runtime resolves through ./src/policy/local-runtime.ts (local auto-approval gateway: login/form-submit on loopback, .local, .test or allowlisted preview/task/sandbox targets; scenario/suite mode selection).
• Export ./replay/bundle resolves through ./src/replay/bundle.ts.
• Export ./types resolves through ./src/types.ts.

Local Commands

• bun run dev — contractspec-bun-build dev
• bun run build — contractspec-bun-build build
• bun run test — bun test --pass-with-no-tests
• bun run lint — bun run lint:fix
• bun run lint:check — biome check .
• bun run lint:fix — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
• bun run typecheck — tsgo --noEmit
• bun run publish:pkg — bun publish --tolerate-republish --ignore-scripts --verbose
• bun run publish:pkg:canary — bun publish:pkg --tag canary
• bun run clean — rimraf dist .turbo
• bun run build:bundle — contractspec-bun-build transpile
• bun run build:types — contractspec-bun-build types
• bun run prebuild — contractspec-bun-build prebuild

Recent Updates

• Replace eslint+prettier by biomejs to optimize speed.
• Add a first-class harness system for controlled inspection, testing, evaluation, and proof generation.
• Implement scenario setup/reset hooks, required evidence checks, success-rule evaluation, and suite mode/target propagation.

Notes

• Works alongside @lssm-tech/lib.contracts-spec, @lssm-tech/tool.bun, @lssm-tech/tool.typescript.
• Hook execution is intentionally injected through HarnessScenarioHookExecutor; the harness core does not import operation registries or application runtimes implicitly.

Canonical Names and Shim Mapping

For VoiceOps hackathon consumers — this section explains the canonical export names and shows how to create local shims when your codebase uses different names.

src/index.ts uses export * barrels, so all canonical names are importable directly from @lssm-tech/lib.harness.

Name Map

classifyHarnessStep — evaluates a single scenario step against policy rules and returns a HarnessPolicyDecision (verdict: 'autonomous' | 'assist' | 'blocked', requiresApproval, reasons).

createHarnessReplayBundle — assembles a HarnessReplayBundle from a completed run record, assertion results, and captured artifacts. Body bytes are stripped from the artifact list so bundles are safe to serialize and store.

normalizeArtifact / normalizeArtifacts — converts raw HarnessCapturedArtifact inputs into fully-formed HarnessStoredArtifact values, generating stable ids, timestamps, and SHA-256 content hashes when callers do not supply them. normalizeArtifacts is the batch wrapper over normalizeArtifact.

Copy-pastable shim file

Create src/lssm-shims.ts in your hackathon repo to re-export the canonical names under the aliases your team already uses:

// src/lssm-shims.ts
// Local aliases for @lssm-tech/lib.harness canonical exports.
// DO NOT change the canonical package — add aliases here instead.

export {
  classifyHarnessStep as classifyAction,
  canFallbackToVisual,
} from "@lssm-tech/lib.harness";

export {
  createHarnessReplayBundle as buildReplayBundle,
  summarizeHarnessReplayBundle,
} from "@lssm-tech/lib.harness";

export {
  normalizeArtifact as normalizeEvidence,
  normalizeArtifacts,
} from "@lssm-tech/lib.harness";

// Re-export shared types so consumers only import from one shim path.
export type {
  HarnessPolicyDecision,
  HarnessReplayBundle,
  HarnessStoredArtifact,
} from "@lssm-tech/lib.harness";

Then in your hackathon code, import from the shim instead of the package directly:

import { classifyAction, buildReplayBundle, normalizeEvidence } from "./lssm-shims";

This keeps your team's preferred names without modifying the upstream package or touching src/index.ts.