feat(server): expose the exact HTTP runtime contract (draft tracker)

[dnlrsls]

🔗 Linked Issue

Closes #1350

🏷️ PR Type

• type:bug — Bug fix
• type:feature — New feature
• type:question — Question requiring tracked work
• type:docs — Documentation only
• type:refactor — Code refactoring (no behavior change)
• type:chore — Maintenance, dependencies, tooling
• type:breaking-change — Breaking change

---

📝 Summary

• Add the Go-owned exact HTTP runtime projection and read-only contract endpoint.
• Register the existing 27 HTTP routes from typed metadata without changing their authentication policy.
• Keep this endpoint-only seed draft: generator and Pi qualification remain in dependent fork PRs.

📂 Changes

File	Change
internal/server/runtime_contract.go	Projection, route registry and read-only endpoint
internal/server/server.go	Register the same 27 relocated bindings with preserved auth policy
internal/server/runtime_contract_test.go	Public metadata, digest/identity, method and bearer guards
docs/RUNTIME-CONTRACT.md, DOCS.md	Final-integration contract documentation and index

🧪 Test Plan

• Focused regression: go test ./internal/server -run '^TestRuntimeContract' -count=1 — 3 tests PASS, exit 0.
• Affected package: go test ./internal/server -count=1 — authorized fresh 60-second-cap run PASS (22.811 s); the earlier 20-second timeout remains failed history.
• Independent verification: the three focused contract tests PASS (1.057 s); source review confirms all 27 relocated route bindings/authentication policies. This is not functional execution of every route.
• Preserved the reviewed source and protected worktree/ref evidence while packaging this commit.
• GitHub full unit/E2E/lint/platform and current-main compatibility — pending actual CI. Live Pi SDK qualification is not claimed.

---

🤖 Automated Checks

After pushing/opening the PR, GitHub CI runs the broad unit/E2E/lint and applicable platform checks. These automated statuses remain pending until the actual checks run; do not claim a pass from local evidence. Windows checks run for PRs but not merge groups, and are not among the six required contexts. Lint and Check PR Has No Transient Artifacts also run for PRs but are not required contexts; Lint also runs on pushes to main. All required checks must pass before merge:

Check	What it verifies	Status
Check Issue Reference	PR body contains Closes #N / Fixes #N / Resolves #N	⏳
Check Issue Has status:approved	Linked issue has status:approved label	⏳
Check PR Has type: Label*	Canonical labels, applicability, and cardinality	⏳
Check PR Has No Transient Artifacts	PR files comply with the Transient Artifact Policy	⏳
Unit Tests	go test ./... passes	⏳
E2E Tests	go test -tags e2e ./internal/server/... passes	⏳
Plugin Tests	npm test passes in plugin/pi	⏳
Lint	golangci-lint reports no new findings	⏳
Windows Setup Test	Windows setup preserves absolute paths and MCP job-object parent-lifetime tests pass	⏳
Cloud Sync Wrapper Tests (Windows)	Cloud sync wrapper and missing-PowerShell-Engram tests pass on Windows	⏳

---

✅ Contributor Checklist

• I linked approved upstream issue feat(protocol): negotiate agent contract compatibility at runtime #1350 above.
• I added exactly one type:* label to this PR
• I recorded actual focused regression and affected package test commands/outcomes for behavior changes, or N/A for docs-only changes
• I recorded additional applicable local checks for an unpushed/no-PR or high-risk change, and identified any missing CI evidence
• Docs updated (if behavior changed)
• Commits follow conventional commits format
• No Co-Authored-By trailers in commits
• I checked every changed path against the Transient Artifact Policy

---

💬 Notes for Reviewers

No merge or issue closure is authorized. The tracker must remain draft/incomplete until the complete feature is integrated and separately authorized. Child PRs target their immediate parent, not main. These branches retain the reviewed pinned base; current-main compatibility, full Go/E2E/lint/platform CI and live Pi SDK qualification are not claimed. Native assessment offered no new review (reviewDue:false); each unit instead has the required independent verification. The prior whole-candidate native acknowledgement is not approval of these intermediate slices. Historical setup/timeouts remain failed evidence, not retroactive passes.

This seed implements only the Go endpoint. The generation command and Pi qualification documented here belong to the following children and are absent from this seed; do not treat final-integration documentation as current seed feature proof.

Chain Context

Field	Value
Chain	#1350 exact HTTP runtime negotiation — Feature Branch Chain
Tracker PR	#1876
Position	1 of 3
Base	main
Depends on	Approved #1350; no earlier chain PR
Follow-up	dnlrsls#15 then dnlrsls#16
Review budget	436 / 400; explicit maintainer size:exception accepted for this cut
Starts at	Pinned 3d94ad24, then immediate-parent work-unit commit
Ends with	Go handler contract endpoint and authentication-preserving route metadata

Chain Overview

main
 └── https://github.com/Gentleman-Programming/engram/pull/1876 feat/issue-1350-runtime-contract (draft; Go endpoint 436)
      └── https://github.com/dnlrsls/engram/pull/15 feat/issue-1350-runtime-01-generator (412)
           └── https://github.com/dnlrsls/engram/pull/16 feat/issue-1350-runtime-02-pi (817)

Scope

• Includes: only this measured cohesive behavior/test/documentation unit.
• Excludes: merges, issue closure, rebases, unrelated fixes and automatic corrective retries.

Autonomy

• CI has not yet been established; consult actual provider checks and the cross-repository metadata limitation below.
• This PR has one deliverable scope.
• This unit can be held/reverted without unrelated feature changes; dependent children must remain unmerged.
• Tests and independent verification cover the unit within the explicitly stated boundaries.

Cross-repository publication boundary

The draft Go tracker targets Gentleman-Programming/engram:main from dnlrsls/engram:feat/issue-1350-runtime-contract. Generator and Pi PRs live in dnlrsls/engram and target their exact immediate-parent feature branches, not the fork's older main. All three exact commits retain the reviewed pinned base; neither repository's main is changed. The accepted review budgets are 436 / 412 / 817 lines, including generated output.

The canonical approved issue is #1350. Fork children use a fully qualified closing reference so they do not accidentally refer to a different fork issue. The inspected legacy metadata workflow only parses bare Closes #N and looks up issues in the PR destination repository; cross-repository approval validation is therefore not established and may fail. No fake local issue, workflow weakening, settings change, merge or issue closure is authorized. CI results remain pending until observed.

All three PR cross-links above use their actual repository-qualified URLs. Future child integration or growth of the upstream tracker remains a separate decision; this does not authorize a new 1,665-line publication exception.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[barbatdev]

Fleet review (deepseek)

Adds a Go-owned Pi HTTP runtime contract: a typed route registry (registerRuntimeRoutes) that re-binds the same 27 routes with the same auth policy, a read-only GET /runtime-contract that projects a stable contract (contract_id/revision/status/digest/operations/supporting_routes) plus the dynamic instance_id, and docs. I verified the relocation is faithful: the 27 registry entries match the 27 removed bindings one-for-one, DELETE /observations/{id} is still the only one behind requireAuth, no route is registered twice (Go 1.22 mux would panic), and session-owned 401s come from the existing Handler() middleware. The digest is computed over the marshaled contract with digest omitted, which is deterministic for these types. One robustness nit in the new file.

Suggestion (1)

• Supporting-route lookup does not verify the id exists (internal/server/runtime_contract.go:139): The operations loop (lines 128-136) rejects an unknown route id with an error, but the supporting-routes loop assigns contract.SupportingRoutes[id] = routes[id] without the same check. A renamed or typo'd id would therefore silently publish an empty RuntimeRouteDescriptor ({method:"", path:"", server_contract:""}) inside the advertised contract instead of failing generation, which is exactly the drift this endpoint is meant to prevent. Mirror the operations loop's existence check before the assignment.

Verdict: clean

[barbatdev]

Fleet review (qwen)

Expose exact HTTP runtime contract: registers 27 HTTP routes from typed metadata, adds runtime_contract.go and tests. Feature PR with pending CI. Documentation updates included. Clean endpoint-only seed draft as specified.

Suggestion (1)

• Route metadata could be validated at startup (internal/server/runtime_contract.go:1): The 27 routes are registered from typed metadata. If any route registration silently ignores invalid metadata, the gap would be invisible. Consider a startup check that validates every metadata entry can be registered against the router, so broken metadata is caught immediately rather than only when a route is first exercised.

Verdict: clean