fix(contract): close the last duplications and make the .shape trap impossible (#9762)

[JSONbored]

Closes #9762.

Stacked on #9757 (which closes #9750). Base is that branch, so this diff shows only #9762's change; GitHub retargets it to main when #9757 merges. The dependency is real: PUBLIC_SURFACE_SKIP_REASONS only reaches the contract in #9757.

#9515's premise is that no tool, schema, or enum in this repo is written down twice. Every sub-issue had landed and the premise was still not true in two ways.

The .shape trap — 27 sites, not the 4 the issue estimated

registerTool accepts either a ZodObject or a raw .shape, and re-wraps a raw shape in a plain z.object that discards the catchall. A looseObject input therefore gets advertised and enforced as additionalProperties: false, and every field the payload carries beyond the modelled set becomes a -32602 the caller cannot act on. That is #9518's defect class, found the hard way.

My issue text said four sites. Writing the guard found 27 — I'd grepped a pattern that matched only some of them. All 27 now pass the schema object.

None of those inputs is loose today, so nothing was broken. That is precisely what makes it worth closing: the sites were indistinguishable from the correct ones by reading, and the day one of those inputs becomes loose the failure is silent and remote. The guard walks every server source under src/mcp, packages/loopover-mcp/{bin,lib}, and packages/loopover-miner/lib, so it cannot be dodged by adding a file — and it leaves a composed { ...X.shape, extra } alone, since that genuinely builds a new shape rather than defeating one.

Six literal enum copies

Contract export	Was duplicated at
AGENT_ACTION_CLASSES	src/openapi/schemas.ts (autonomy record keys)
AUTONOMY_LEVELS	src/openapi/schemas.ts, the stdio bin
MAINTAIN_ACTION_CLASSES	the stdio bin
PUBLIC_SURFACE_SKIP_REASONS	src/openapi/schemas.ts, src/openapi/spec.ts
FEASIBILITY_VERDICTS	src/openapi/schemas.ts
ROTATABLE_SECRET_NAMES	src/mcp/server.ts

The two in the stdio bin carried a comment justifying them: the bin resolves @loopover/engine through the published package, whose export map does not surface AUTONOMY_LEVELS (#6153). True of the engine — never true of the contract, which that file already imports. The comment went with the literals; a load-bearing comment that is no longer true is worse than no comment.

AGENT_ACTION_CLASSES joins the contract as its own pinned copy, because the settings response schema needs the engine's full list and cannot import it. It is pinned against the engine's, alongside two new pins that state the things "just sync it to the engine" would break: MAINTAIN_ACTION_CLASSES is deliberately a strict subset (the operator-settable classes; widening it would offer switches the surface cannot honor), and PROPOSE_ACTION_CLASSES is that subset plus review_state_label.

What I checked and did not change

My scan flagged three ["global", "repo", "none"] literals in packages/loopover-miner/lib/ as CONFIG_ADMIN_WRITE_SCOPES. They are kill-switch scopes — a different concept that happens to share a two-value prefix. Left alone.

Validation

• All four new assertions fail on the pre-fix tree, including expected [ …(27) ] to deeply equal [] for the shape guard.
• The regenerated openapi.json is byte-identical — every substitution has the same members in the same order, which is what makes this a substitution and not a schema change.
• npx vitest run --changed: 2336 passed, 166 files. tsc --noEmit clean; validate:mcp passes.

[loopover-orb]

Warning

⏸️ LoopOver review result - manual review recommended

_{Review updated: 2026-07-29 09:23:28 UTC}

7 files · 1 AI reviewer · no blockers · CI green · clean

⏸️ Suggested Action - Manual Review

• Required AI review was skipped by a submitter-reputation downgrade: This repository requires blocking AI review, and the submitter's recent-submission signal downgraded this PR to deterministic-only checks. Those checks do not read code semantics, so the gate is held for human review instead of passing automatically.

Review summary
This PR replaces 27 `.shape`-passing registerTool call sites in src/mcp/server.ts with the ZodObject itself, closes six literal enum duplications (AGENT_ACTION_CLASSES, AUTONOMY_LEVELS, MAINTAIN_ACTION_CLASSES, PUBLIC_SURFACE_SKIP_REASONS, FEASIBILITY_VERDICTS, ROTATABLE_SECRET_NAMES) by sourcing them from @​loopover/contract, and adds a regex-based guard test plus meta-tests pinning the contract copies against the engine's canonical lists. The `.shape` fix is real and well-targeted — the SDK's re-wrap-and-discard-catchall behavior is a legitimate defect class (cites #9518), and the guard test's file-walk + regex approach is reasonable at preventing regression, though it's line-pattern matching rather than AST-based so it could theoretically be fooled by unusual formatting. The enum-deduplication work is mechanical and low-risk, with meta-tests verifying parity against the engine's own lists.

Nits — 7 non-blocking

• The guard test's regex `/\b(?:input|output)Schema:\s*[A-Za-z0-9_]+\.shape\b/` in test/unit/mcp-register-tool-shape-guard.test.ts only matches a single-identifier `.shape` access on the same line as the key — a `.shape` reference split across lines or reached via a local alias would silently evade the guard.
• This PR is described as stacked on feat(contract): give the request schemas, the control plane, and the self-host endpoints one contract (#9750) #9757/contract: close the last ten duplications and make the .shape trap impossible #9762 and the base branch is 4 commits behind default — worth confirming the diff shown here doesn't omit context that already landed upstream before merging.
• packages/loopover-mcp/bin/loopover-mcp.ts imports `AUTONOMY_LEVELS as MAINTAIN_AUTONOMY_LEVELS` but the diff's comment block still refers to it only by its old name in prose — minor comment/code naming mismatch worth a second look for readability.
• Consider hardening the shape-guard regex to also catch `.shape` access via destructuring or intermediate variables, or add a short comment in the test noting its scope is intentionally limited to the direct literal pattern.
• Given src/mcp/server.ts and src/openapi/schemas.ts are already very large files, consider whether future contract-migration PRs in this series should extract the registerTool call table into a smaller generated/declarative structure to reduce this file's ongoing growth.
• PR author also opened the linked issue — Link an issue that was opened by a different contributor, or provide a rationale for why this self-authored issue represents genuine discovery work.
• Required AI review was skipped by a submitter-reputation downgrade — Review this PR manually, or run AI review with a trusted override, before merging.

Decision drivers

• ✅ Code review — No blockers (1 reviewer)
• ⚠️ Gate result — Not blocking (Advisory; not blocking this PR.)

Context & advisory signals — never blocks the verdict

Signal	Result	Evidence
Linked issue	✅ Linked	#9762, #9750
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (2 linked issues).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 14 registered-repo PR(s), 13 merged, 370 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 14 PR(s), 370 issue(s).
Improvement	✅ Minor	risk: clean · value: minor

Linked issue satisfaction

Partially addressed
The PR thoroughly closes the .shape trap (found and fixed far more sites than the issue estimated) and substitutes AUTONOMY_LEVELS, MAINTAIN_ACTION_CLASSES, AGENT_ACTION_CLASSES (with a new pinned meta-test), PUBLIC_SURFACE_SKIP_REASONS, FEASIBILITY_VERDICTS, and ROTATABLE_SECRET_NAMES for their contract imports, plus adds the required guard test. However, the issue's table also explicitly lists C

Review context

• Author: JSONbored
• Role context: owner (maintainer lane)
• Public audience mode: oss maintainer
• Lane context: Repository is registered but has no active allocation in the current snapshot.
• Public profile languages: Python, TypeScript, Ruby, Go, MDX, Shell, Solidity, JavaScript
• Official Gittensor activity: 14 PR(s), 370 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Start here: Treat this as maintainer-lane context rather than normal contributor-lane activity.
• Then work through the remaining 2 steps in the Signals table above.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

🧪 Chat with LoopOver

Ask LoopOver a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.

• @loopover ask <question> answers contribution-quality Q&A with source citations and freshness.
• @loopover chat <question> answers in natural prose from cached decision-pack facts via local inference (maintainer/collaborator; read-only).
• A plain-language @loopover mention with a real question is routed to the closest matching read-only command automatically — no exact syntax required.

Full command reference: https://loopover.ai/docs/loopover-commands

🧪 Experimental — new and may change.

Decision record

• action: hold · clause: ai_review_inconclusive
• config: e49c987acac1f3bd596faa7992bcba58c038801a29ac1e852318847a905b0e9d · pack: oss-anti-slop · ci: failed
• record: 5387e83708b07172378d51cf7bad30b2d848e21164e6d3a7fe4630e8320421f5 (schema v5, head 1031e00)

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by LoopOver, a quiet PR intelligence layer for OSS maintainers.

• Re-run LoopOver review

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	loopover-ui	fdbdbf8	Commit Preview URL Branch Preview URL	Jul 29 2026, 09:08 AM

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.33%. Comparing base (5220a35) to head (fdbdbf8).
⚠️ Report is 2 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #9765      +/-   ##
==========================================
- Coverage   90.33%   90.33%   -0.01%     
==========================================
  Files         917      917              
  Lines      113904   113902       -2     
  Branches    26966    26966              
==========================================
- Hits       102894   102888       -6     
  Misses       9681     9681              
- Partials     1329     1333       +4     

Flag	Coverage Δ
backend	95.56% <100.00%> (-0.01%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
packages/loopover-contract/src/enums.ts	100.00% <100.00%> (ø)
packages/loopover-mcp/bin/loopover-mcp.ts	67.21% <ø> (-0.05%)	⬇️
src/mcp/server.ts	97.36% <ø> (ø)
src/openapi/schemas.ts	100.00% <ø> (ø)
src/openapi/spec.ts	99.27% <ø> (ø)

... and 1 file with indirect coverage changes

[loopover-orb]

LoopOver approves — the gate is satisfied and CI is green.

The merge-base changed after approval.