Source provenance — VERIFI SDK docs

Every page here was written by reading source, not by recalling an API. This page records what was read so a later reader can re-verify, and so a stale page is detectable.

Written: 2026-08-17. Revised: 2026-08-18 against @pragyacyber/engine-contract@1.5.1, @pragyacyber/harness-sdk@1.2.0 and @pragyacyber/mcp-sdk@0.1.0.

NOTE

The harness-sdk 1.0.0 → 1.1.0 change is confined to the model path. src/model-client.ts and src/runtime.ts were re-read at 1.1.0; the rest of the SDK surface is byte-identical to 1.0.0, so the executed transcripts below (which make no model call) still stand. The 1.1.0 model-path claims are read from source, not re-executed against a live provider — a live Bedrock invocation was out of scope for this pass and is noted as such.

NOTE: The 1.1.0 → 1.2.0 change is likewise confined to the model path — one function, createModelResolver in src/model-client.ts, which now reads per-role VERIFI_MODEL_<ROLE>_PROVIDER / _BASEURL / _APIKEY env vars so a keyed provider role works from a harness. That file was re-read at 1.2.0; the rest of the SDK surface is byte-identical to 1.1.0. The 1.2.0 claim is read from source, not re-executed — a live end-to-end run against a keyed NIM provider is still pending and is noted as such.

Files read in full

`@pragyacyber/harness-sdk` @ 1.2.0

File	Pages it grounds
`src/index.ts`	export surface
`src/define-harness.ts`	defineHarness
`src/runtime.ts`	Run lifecycle, Models — the credential resolver
`src/mcp-client.ts`	Tools and slots
`src/failover.ts`	Tools and slots
`src/budget-ledger.ts`	The budget ledger
`src/grpc-channel.ts`	The engine channel
`src/model-client.ts`	Models — re-read at 1.1.0 for the contract-routed model path, and again at 1.2.0 for the per-role keyed-model env resolution in `createModelResolver`
`README.md`	corroboration

`@pragyacyber/engine-contract` @ 1.5.1

File	Pages it grounds
`src/index.ts`, `src/version.ts`	Contract overview
`src/enums.ts`	Contract overview, The three gates
`src/reference.ts`	Registry objects
`src/registration.ts` + `registration.test.ts`	Registering a component
`src/model-invocation.ts` + `model-invocation.test.ts`	Models
`src/raw-finding.ts` + `raw-finding.test.ts`	Findings and events, The finding model
`src/service.ts`, `src/run.ts`, `src/domain.ts`	Service, TestInput, Run
`src/finding.ts`	The finding model
`src/event.ts`	Events and alerts
`src/budget.ts`	The budget ledger
`proto/engine_channel.proto`	The engine channel
`README.md`	corroboration

Exported but not documented, because they are outside what a harness or MCP author needs: src/schedule.ts, src/approval.ts, src/residency.ts. src/contract-diff.ts is a build tool and is not exported from the package root.

`verifi-engine`

File	Pages it grounds
`src/registry/three-gate-probe.ts`	The three gates, Conformance
`src/registry/model-probe.ts`	Models, Operating principles
`src/registry/harness-probe.ts`	Packaging and boot
`src/registry/registry.ts`, `slot-resolver.ts`, `preflight.ts`	Registry objects, Conformance
`src/api/orchestrator-routes.ts` (the `/registries` routes)	Registering a component, Conformance
`src/findings/finding-store.ts` (`normaliseFinding`, the severity allow-list)	Findings and events

`harnesses/asm-harness` — the reference harness

File	Pages it grounds
`sdk/harness.ts`	every harness page
`sdk/main.ts`	Packaging and boot
`sdk/findings.ts`	Findings and events
`sdk/kali-fs-sync.ts`	Tools and slots
`Dockerfile`, `package.json`, `README.md`	Packaging and boot

`verifi-mcps` — the reference MCPs

File	Pages it grounds
`asm/server.py`	Building an MCP, The three gates
`kali/server.py`	Building an MCP, Tools and HITL, Statelessness

`@pragyacyber/mcp-sdk` @ 0.1.0

Now read in full and documented, including the reason its server is not a deployment path.

File	Pages it grounds
`src/define-mcp.ts`	Authoring rules the SDK enforces
`src/server.ts`	The TypeScript MCP SDK, Known gaps
`src/conformance.ts`	Statelessness and sharing

How claims were checked

Three levels, and the pages say which applies.

Executed. The Quickstart harness and its local runner were written into a scratch project against the built harness-sdk@1.0.0 and a 1.5.1 build of the contract, type-checked with tsc --noEmit (exit 0), and run with tsx on Node 22. The console output shown on that page is the real output of that run, on both the normal and the dry-run path.

Contract invariants were checked by parsing real objects and calling real functions against 1.5.1. Abridged:

CONTRACT_VERSION 1.5.1
isCompatible 1.0.0 -> true | 2.0.0 -> false | 1.0 -> false

buildModelRequest bedrock 'anthropic.claude-3-5-sonnet-…'  -> anthropic body
buildModelRequest bedrock 'us.anthropic.claude-opus-4-8'   -> anthropic body, path keeps 'us.'
buildModelRequest bedrock '{eu,apac,global,us-gov}.amazon.nova-pro-v1:0' -> nova body
buildModelRequest bedrock 'us.meta.llama3-1-70b-…'         -> THROWS (unknown family)
modelEndpoint openai_compat {}                             -> THROWS (needs baseUrl)
modelEndpoint bedrock {}                                   -> THROWS (needs region)
parseModelResponse anthropic { nonsense: true }            -> 0 tokens, no guess

zModelRegistration + {status|probe|probeInvoked|tools|authRef|lastProbedAt}  -> all REFUSED
zModelRegistration bedrock without region                  -> REFUSED
zModelRegistration keyed without apiKey                    -> REFUSED
zModelRegistration without capabilities/costModel          -> accepted (1.4.3)
zMcpRegistration with neither endpoint nor image           -> REFUSED
zMcpRegistration concurrencyModel:'shared'                 -> REFUSED
zMcpRegistration defaults                                  -> transport http, sidecar
zHarnessRegistration imageDigest 'v1.2.0'                  -> REFUSED "must be a sha256 digest, not a tag"
zHarnessRegistration imageDigest omitted                   -> REFUSED
zRawFinding severity 'info' / 'informational'              -> accepted / REFUSED
zRawFinding + {reviewStatus|publishedAt|reviewedBy|clientVisible} -> all REFUSED
zRawFinding + rawOutput:{…}                                -> accepted (.passthrough)
zRawFinding affected:'https://x'                           -> REFUSED (must be an array of objects)
zEventType tool_error · mcp.fallback_used · mcp.no_healthy_tool
          · model_call · model_error · model_price_unknown -> all members (21 total)
computeDedupeKey(a, l, 'DNS') === computeDedupeKey(a, l, 'dns')
crossedThresholds([1,5,25], 6, [1]) -> [5]

defineHarness refusals were exercised directly: order: 0 and order: 1.5 throw, duplicate orders throw, models: [] throws, version: '1.0' throws. collectRunSecrets() was run against a synthetic environment — it collects MY_API_KEY and DB_PASSWORD and correctly ignores AWS_ACCESS_KEY_ID, KB_ENDPOINT_URL, a three-character SHORT_TOKEN, and NVIDIA_API_KEY=disabled.

The mcp-sdk finding on Known gaps was produced by building a server with defineMcp + buildMcpServer, starting it, and issuing both wire shapes against it. The transcript on that page is real output.

The SDK export lists on this site are enumerated, not transcribed:

node -e "import('@pragyacyber/harness-sdk').then(m=>console.log(Object.keys(m).sort().join('\n')))"
node -e "import('@pragyacyber/engine-contract').then(m=>console.log(Object.keys(m).sort().join('\n')))"

Read. Schema shapes, error messages, endpoint behaviour and Python MCP structure are quoted or paraphrased from source read in this pass. Code excerpts are verbatim or lightly elided, and elisions are marked.

Unverified. Anything that could not be checked is marked UNVERIFIED inline or listed on Known gaps. The main ones: how a HITL approval token reaches an MCP; whether any evidence-attachment path exists for a harness; whether an over-the-wire statelessness test exists anywhere; the engine-side registration and Service composition flow end to end; and how a harness's declared slots, model roles and phases reach the registry given that zHarnessRegistration carries none of them.

The diagrams

Every figure on this site is hand-authored inline SVG generated at build time from lib/diagrams.ts. Nothing in a diagram is decorative: each one is drawn from the same source read that produced the surrounding prose, and the labels carry real identifiers — mcp.fallback_used, computeDedupeKey, slotFills, threshold_breach — rather than paraphrases.

They carry no literal colours. Every stroke, fill and label resolves to a --c-* theme token, so the light and dark renderings are the same drawing and cannot drift apart.

Package access

The Getting the packages page describes GitHub Packages behaviour — the read:packages scope, the .npmrc variable expansion, cross-repo Actions grants, and the BuildKit secret pattern. The BuildKit Dockerfile fragment is adapted from a real, working harness image build, including the comment explaining why the token is a secret and not an ARG, and why pnpm gets the value inline in a discarded stage.

What is deliberately absent

Any credential, real or fake. No sample on this site contains a key, a token, a connection string, or a plausible-looking placeholder for one. Credentials appear only as authRef / credRef indirections and environment variable names.

@pragyacyber/mcp-sdk's buildMcpServer as a deployment path. It is documented, with the reason and the transcript, and then explicitly not recommended. Its defineMcp rules are taught throughout the Python chapters.