lib.harness
Harness orchestration, policy, evidence, and evaluation runtime.
@lssm-tech/lib.harnessbun add @lssm-tech/lib.harnessManifest declarations describe the current workspace; they do not verify registry publication or runtime execution.
Package guide
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
QualityCheckResultV1andQualityRunReceiptV1evidence 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
setupandresethooks through an explicitHarnessScenarioHookExecutor, 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.tscontains 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/engineresolves through./src/assertions/engine.ts. - Export
./evidence/normalizerresolves through./src/evidence/normalizer.ts. - Export
./orchestration/evaluation-runnerresolves through./src/orchestration/evaluation-runner.ts. - Export
./orchestration/runnerresolves through./src/orchestration/runner.ts. - Export
./policy/classifierresolves through./src/policy/classifier.ts. - Export
./policy/local-runtimeresolves through./src/policy/local-runtime.ts(local auto-approval gateway: login/form-submit on loopback,.local,.testor allowlisted preview/task/sandbox targets; scenario/suite mode selection). - Export
./replay/bundleresolves through./src/replay/bundle.ts. - Export
./typesresolves through./src/types.ts.
Local Commands
bun run dev— contractspec-bun-build devbun run build— contractspec-bun-build buildbun run test— bun test --pass-with-no-testsbun run lint— bun run lint:fixbun run lint:check— biome check .bun run lint:fix— biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .bun run typecheck— tsgo --noEmitbun run publish:pkg— bun publish --tolerate-republish --ignore-scripts --verbosebun run publish:pkg:canary— bun publish:pkg --tag canarybun run clean— rimraf dist .turbobun run build:bundle— contractspec-bun-build transpilebun run build:types— contractspec-bun-build typesbun 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
| Wished-for name | Canonical export | Source file |
|---|---|---|
classifyAction | classifyHarnessStep | src/policy/classifier.ts |
buildReplayBundle | createHarnessReplayBundle | src/replay/bundle.ts |
normalizeEvidence | normalizeArtifact / normalizeArtifacts | src/evidence/normalizer.ts |
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.
Relationships
Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.
7 declarations
@lssm-tech/lib.assurance-specworkspace:^
Read the package manual ↗@lssm-tech/lib.contracts-spec-coreworkspace:^
Read the package manual ↗@lssm-tech/lib.crypto-utilsworkspace:^
Read the package manual ↗@lssm-tech/lib.contracts-runtime-kernelworkspace:^
Read the package manual ↗@lssm-tech/lib.contracts-runtime-coreworkspace:^
Read the package manual ↗@lssm-tech/lib.surface-runtimeworkspace:^
Read the package manual ↗
Declared capabilities
Harness orchestration, policy, evidence, and evaluation runtime.
Scripts
publish:pkgbun publish --tolerate-republish --ignore-scripts --verbosepublish:pkg:canarybun publish:pkg --tag canarybuildcontractspec-bun-build buildbuild:bundlecontractspec-bun-build transpilebuild:typescontractspec-bun-build typesdevcontractspec-bun-build devcleanrimraf dist .turbolintbun run lint:fixlint:fixnode ../../../../scripts/biome.cjs check --write --unsafe --only=nursery/useSortedClasses . && node ../../../../scripts/biome.cjs check --write .lint:checknode ../../../../scripts/biome.cjs check .testbun test --pass-with-no-testsprebuildcontractspec-bun-build prebuildtypechecktsgo --noEmit