MetaHarnessClient identity/bridge/API core (ADR-0026a)

[ruvnet]

Milestone: M4 | Mission: Cognitum Agentic SDK Integration

Implement the product boundary/naming, public client operations and domain types, the structured child-process bridge, error/cancellation/event semantics, and determinism/manifest/witness-truth guarantees for the local harness factory bridge.

Governing ADR: 0026a (D1-D7). Blocked on #1.

---

Filed from the reviewed mission plan. Routes to Project #1 (Product Roadmap).

[ruvnet]

Note: the "Blocked on #1" reference is stale — #1 is an unrelated already-merged docs PR from before real issue numbers were assigned (same pattern found on #59/#60/#61 earlier this mission). The real blockers are the 7 explicit upstream gaps listed in ADR-0026a §D7, most critically #2: "no versioned JSONL bridge covers the SDK operations" — the actual metaharness npm package does not yet implement the bridge --stdio protocol (or any equivalent) this client is specified to talk to. Real scaffold/analyze/score/witness-verify operations cannot be honestly implemented against a protocol that doesn't exist upstream yet.

Scoping the first slice to what §D1/§D3 make genuinely buildable without the bridge: MetaHarnessClient construction (zero I/O, matching the established pattern from MetaLlmClient/MetaProxyClient) and the domain type definitions (MetaHarnessConfig, RepositorySource, ScaffoldRequestV1/ScaffoldPlan/ApplyApproval/ScaffoldResult, WitnessVerification). All actual bridge-communicating methods (capabilities(), analyzeRepository(), scaffold(), etc.) remain blocked until upstream ships blockers 1-7, tracked here.

[ruvnet]

M4 start: MetaHarnessClient construction + domain types (PR #98)

Opened a draft PR implementing the only tractable slice of ADR-0026a right now: #98

What was built (all 3 SDKs: node, python, rust)

• §D1 construction — MetaHarnessClient constructors resolve configuration only, zero I/O (no npm access, process spawn, repository read, filesystem write, capability probe, login, or prompt). Node's construction reuses Meta Proxy's exact browser-guard pattern (PR feat(meta-proxy): consent gating + browser rejection guard (ADR-0025a D9/D10 tractable slice, M3 continuation) #96) — UnsupportedRuntimeError fires before config resolution in a browser-like runtime. Python/Rust have no browser surface (documented, matching Meta Proxy's own precedent).
• §D3 domain types — pure data shapes, no bridge dependency: MetaHarnessConfig, RepositorySource (LocalRepository | GitRepository tagged union), ScaffoldRequestV1, ScaffoldPlan, ApplyApproval, ScaffoldResult, WitnessVerification (wraps ADR-0028's existing VerificationResult — reused, not duplicated). Exact schema literals included (cognitum.metaharness.scaffold-{request,plan,result}.v1). Unknown additive fields/enum variants preserved via a raw/rawUnknown convention; an unrecognized verification level fails closed to none/invalid rather than being passed through as a trust claim.
• §D2 methods as fail-closed stubs — capabilities(), listTemplates(), listHosts(), analyzeRepository(), scoreRepository(), planScaffold(), scaffold(), inspectManifest(), validateHarness(), compareHarnesses(), verifyWitness() all have their real declared signatures, but every single one — including capabilities() itself — throws a typed UnsupportedCapabilityError (Node/Python) / returns AgenticError{kind: UnsupportedCapability} (Rust) citing the exact missing §D7 capability (e.g. metaharness.scaffold.plan) and blocker number(s), before any process/network/filesystem access. close() is a real no-op.

The 7 upstream blockers (ADR-0026a §D7) — why nothing more is possible yet

1. reviewed 0.4.1 is not published at the registry state
2. no versioned JSONL bridge covers the SDK operations
3. package/generator/template versions disagree and output/cancel is nonuniform
4. from-repo is mutable and unresolved variables do not fail by default
5. witness docs, runtime shape, verification, and publish claims disagree
6. wrapper result/dependency is stale and private CLI collides/process-exits
7. external-template and full-eject flags overstate implemented behavior

Until all seven close, the ADR itself says a released SDK can offer at most a feature-flagged read-only preview — this pass ships the visible API shape with every operation failing closed, not even that preview yet. No real npm acquisition (ADR-0026b), no child-process/bridge I/O, no real scaffold/analyze/score/witness logic, and no MetaHarnessProxyLifecycleProvider adapter (needs ADR-0025b) were attempted, per the ADR's own scope boundary.

Verification (real output)

Node (sdks/node): npm run build && npm run typecheck && npm run lint && SKIP_SEED_INTEGRATION=1 npx vitest run

• Build: all subpaths built clean, including the new ./metaharness export
• Typecheck: clean
• Lint: clean
• Tests: 439 passed, 8 skipped (0 failed)

Python (sdks/python): SKIP_SEED_INTEGRATION=1 pytest, ruff check ., mypy

• Pytest: 492 passed, 11 skipped (0 failed)
• Ruff: all checks passed
• Mypy: confirmed via git stash -u + rerun against this branch's parent commit — baseline is 24 pre-existing errors (unrelated files), and this branch also shows 24 errors → zero new mypy errors introduced by the metaharness code

Rust (sdks/rust): added a new metaharness Cargo feature (zero new deps — only serde_json, already a base dependency), wired into both the main rust CI job's feature list and the rust-feature-matrix array

• cargo build --features "...,metaharness": clean
• cargo test --features "...,metaharness": all green (27 new metaharness tests + full existing suite, 0 failures)
• cargo clippy --all-targets --features "...,metaharness" -- -D warnings: clean
• cargo build --features metaharness (standalone, matching the feature-matrix job): clean

Tests added

• Zero-I/O construction tests (all 3 languages)
• Browser-rejection test (Node) — mirrors Meta Proxy's guard test exactly
• Domain-type round-trip / unknown-field-preservation tests (all 3 languages) — including a fail-closed test for an unrecognized MetaHarness-ADR-011-alternate-shape witness verification level
• One test per stubbed §D2 method proving it throws/returns the correct typed error, with an explicit structural assertion (subprocess/fetch spy) that no I/O was ever attempted

PR: #98

[ruvnet]

PR #98 merged — ADR-0026a §D1/§D3 tractable slice: zero-I/O `MetaHarnessClient` construction, domain types (`MetaHarnessConfig`, `RepositorySource`, `ScaffoldRequestV1`/`Plan`/`Result`, `WitnessVerification` reusing each language's existing ADR-0028 `VerificationResult`), and §D2's full method surface as fail-closed stubs that error before any I/O — confirmed via import-absence (zero `child_process`/`fs`/`fetch` in the module) that this is structurally guaranteed, not just tested.

Independent review confirmed no regressions from the implementer's self-reported `cargo fmt`-reformatted-then-reverted incident (diffed the full PR against main: exactly the intended 32 files, nothing stray left behind) and that the new `metaharness` Rust feature is genuinely wired into CI and self-contained. Two minor nits filed as #102 (a Rust `verifyWitness` signature gap in a currently-dead stub path, and a tautological Node test).

Remaining scope: this milestone is now blocked on real upstream work — ADR-0026a's own §D7 documents 7 explicit upstream blockers, most critically that the real `metaharness` npm package doesn't yet implement any versioned JSONL bridge protocol for this client to talk to. No further SDK-side work is possible here until upstream ships fixes for those 7 gaps.