Known gaps

This page exists because a documentation site that hides the rough edges makes them cost more, not less. Everything here was found by reading source and, where the entry says verified, by running it.

Reviewed 2026-08-18 against @pragyacyber/engine-contract@1.5.1, @pragyacyber/harness-sdk@1.2.0 and @pragyacyber/mcp-sdk@0.1.0.

Thirteen of the seventeen gaps this page listed in its first edition are now closed. They are recorded in What was fixed rather than deleted, because knowing a trap existed is how you recognise its shape when it reappears somewhere else.

Open

1. @pragyacyber/mcp-sdk's server does not speak MCP

Severity: real bug. Do not deploy buildMcpServer.

buildMcpServer's POST /mcp dispatches on { method: 'list_tools' | 'call_tool' } — plain JSON, not JSON-RPC 2.0. The engine's three-gate probe and the harness SDK's McpClient both send real MCP: initialize, notifications/initialized, tools/list, tools/call.

Verified by building one and probing it both ways:

GET  /healthz                                     200
GET  /test                                        200
POST /mcp {"method":"list_tools"}                 200  {"tools":[…]}
POST /mcp {"jsonrpc":"2.0","method":"initialize"} 400  {"ok":false,"error":"unknown method 'initialize'"}
POST /mcp {"jsonrpc":"2.0","method":"tools/list"} 400  {"ok":false,"error":"unknown method 'tools/list'"}

So a server built with it passes gates 1 and 2, fails gate 3, and no harness can call it. It is the same mistake gate 3 itself once made in the other direction — a probe written against a guessed protocol that every real server answered 400 to. That one was caught by running it against a live container; this one survives because it has never been run against anything. A component wired to nothing still passes all of its tests.

defineMcp's authoring-time refusals are correct and worth copying; they are taught on the MCP pages.

Fix shape: replace the handler with real JSON-RPC (initialize → notifications/initialized → tools/list / tools/call), SSE-capable, honouring mcp-session-id and both Accept types — or drop buildMcpServer and keep defineMcp + probeStatelessness as the authoring half only.

2. The MCP call timeout is not reachable from runHarness

Severity: moderate. Partially fixed.

McpClientOptions.timeoutMs is now a real option and createMcpResolver threads it through — so a harness that builds its own resolver can raise the 300 s default.

But runHarness(harness, manifest, channel, opts) has no timeoutMs in opts, and runHarness is what builds the resolver behind ctx.mcp(). Through the normal container entrypoint the ceiling is still 300 s with no hook, which is why the production ASM harness clamps every command to 285 s server-side.

Fix shape: an mcpTimeoutMs in runHarness's opts, or better, a manifest field so an operator can raise it for a slow estate without a redeploy.

3. Evidence has no author-facing path

Severity: moderate. Unchanged.

zEvidence is fully specified — content-addressed by sha256, with a storageRef and a redacted flag — and zFinding.evidenceIds exists. But emitFinding has no evidence parameter and the normaliser sets evidenceIds: [] unconditionally. The same is true of reproSteps and references, and of location.port, location.method and cvss: all present in zFinding, none reachable from what a harness emits.

For a security platform, "here is the HTTP transcript that proves it" is not a nice-to-have. Note location.port in particular — the contract keeps it explicitly because v1 stripped ports and rescanned :8443 as :443, and a harness still cannot set it.

You can attach evidence informally: zRawFinding is .passthrough(), so an extra key survives the schema. It will not be normalised into an Evidence record.

4. The HITL approval token has no transport to an MCP

Severity: unresolved design question. Unchanged.

The rule appears in three places — a destructive tool requires an approved HITL token in the CallContext. But CallContext exists only in mcp-sdk, whose server should not be deployed; neither asm/server.py nor kali/server.py accepts or checks a token; and McpSlot.call(tool, args) has no way to pass one out of band. The proto carries ApprovalRequest / ApprovalDecision between the harness and the engine, not between the harness and an MCP.

So the enforcement point is currently the harness, on the honour system. If you are writing a destructive tool, ask rather than building against an assumed mechanism.

5. No over-the-wire statelessness runner

Severity: moderate. Unchanged.

probeStatelessness(mcp, opts) takes an in-process TypeScript Mcp object and calls tool.handler directly. Every MCP that exists is Python, so the one check gating shared — whose failure mode at shareScope: 'global' is a cross-tenant data leak — has no runnable implementation for any server in production.

The engine's mcp-live.e2e.test.ts exercises the three gates against a real container; that is a different check. Write the interleaved two-session test yourself and say how you tested it. The design is documented.

Note the schema does its half correctly: zMcpRegistration refuses shared outright, so nothing can be registered as shared on an assertion. The gap is that nothing can earn it automatically either.

6. No bridge from HarnessDefinition to zHarness

Severity: moderate. Partially fixed.

What you write in defineHarness and what gets registered are still different objects with different field names, and nothing converts one to the other:

The live trap inside it is fixed: defineHarness now validates phase order as a positive integer, matching zPhase, so numbering from zero fails on your machine rather than at registration.

Also note zHarnessRegistration — what a caller actually POSTs — is much narrower than zHarness, carrying only id, name, image, imageDigest and an optional semver. Everything else on the stored record has to arrive some other way, and how a harness's declared slots and model roles reach the registry is not something this site could verify.

Fix shape: a toRegistryHarness(def, { id, imageDigest }) helper in the SDK.

7. The conformance runner is not a runner you can run

Severity: moderate. Unchanged.

threeGateProbe is the correct arbiter and is genuinely language-neutral, but it is a function inside the engine repository — not a published package, not a CLI. An external MCP author cannot npx it. The two options today are hand-rolled curl (documented on Conformance) or registering and using the engine's probe route.

8. Engagement → Assessment is renamed in the contract only

Severity: known and tracked. Unchanged.

The contract calls it Assessment. The product UI and the production databases still carry engagementId. The schemas are .strict() so a stray engagementId fails loudly, which is the right handling — but a newcomer reading both will not know which is current. The contract is the target state.

9. ctx.policy is delivered and enforced by nobody

Severity: low, but easy to misread.

ctx.policy.allowedActions / deniedActions are free strings the SDK never reads. ctx.policy.redaction likewise: the SDK's own scrub is collectRunSecrets + redact, which does not consult it. If your harness takes actions a rule of engagement could forbid, you must honour it yourself.

What was fixed

Kept for shape recognition. Each entry says what closed it.

What this site still could not verify

• The engine-side registration and Service composition flow end to end. The routes and schemas were read and the schemas were exercised; no registration was run against a live engine.
• How a harness's declared slots, model roles and phases reach the registry, given that zHarnessRegistration carries none of them.
• Whether any open item above is already fixed on an unmerged branch. Everything here was read from the working tree.