[wip] Add local-canvases protocol contract (LC-17)

[Ulugbek Abdullaev (ulugbekna)]

Summary

Introduces a versioned, renderer-neutral ahp-canvas: channel for local extension/package-rendered canvas surfaces, promoting the VS Code local-canvas PoC transport into the canonical AHP contract (LC-17). This is coordinated with an independent VS Code local-canvas integration; the VS Code side is expected to sync this contract via the repo's existing protocol-sync script once merged.

What's included

• Stable identity — CanvasIdentityKey (exact backing chat, extension/package source, canvas type, instance id) plus a host-assigned, opaque incarnation token that MUST NOT be reused for a superseded logical instance. CanvasPackageSource carries a dedicated sourceId distinct from display-only packageName/version, since the same package name can be installed in more than one scope.
• Lifecycle state — CanvasTrustState (trusted/pending/blocked) and CanvasAvailabilityState (unsupported/notLoaded/loading/empty/ready/failed) are independent axes. SessionState.canvases is durable membership, distinct from the new read-only listCanvasTypes type-discovery catalogue.
• Commands:
  • listCanvasTypes — read-only discovery of canvas types available for a chat; never opens/materializes anything.
  • openCanvas — requestId-scoped idempotency (same requestId + identical params dedupes; different params rejects Conflict; a genuinely new requestId for an already-open identity may re-invoke the provider without creating a second logical identity).
  • resolveCanvasSource — read-only current-state/live-endpoint read (CanvasSourcePresentation { url, expiresAt? }, renderer-neutral and never persisted); never opens/resumes/restarts anything. Also used for client-local page reload and unavailable-source retry.
  • invokeCanvasAction — required incarnation precondition (rejects Conflict if stale); no exactly-once-across-crash promise; result never persisted into durable state.
  • restartCanvasProvider — the only operation that intentionally bumps incarnation; required requestId + incarnation preconditions.
  • closeCanvas — required revision precondition; logical close (durable membership removal), distinct from a client merely hiding a tab/view.
• Capability — new server/runtime-side CanvasCapabilities / InitializeResult.canvases, independent of the existing client-side ClientCapabilities.canvases and of protocol-version negotiation alone. A protocol version does not by itself imply a working canvas runtime.
• Bounds — declared, enforceable size/depth limits (CANVAS_REQUEST_ID_MAX_LENGTH, CANVAS_IDENTITY_FIELD_MAX_LENGTH, CANVAS_SCHEMA_MAX_PROPERTIES/CANVAS_SCHEMA_MAX_DEPTH, CANVAS_MAX_DECLARED_ACTIONS, CANVAS_INPUT_MAX_LENGTH/CANVAS_RESULT_MAX_LENGTH) plus an isCanvasSchemaWithinLimits enforcement helper, to give hosts a precise contract for LC-28.
• Consistent staleness rejection — canvasReducer and sessionReducer's session/canvasSet branch both reject any action/update whose asserted revision is not strictly greater than the current revision, uniformly across all fields (not just incarnation).

Version / generation

• Keeps PROTOCOL_VERSION at 0.9.0, following the existing protocol version policy. The provisional 0.10.0 bump was removed; runtime canvas capability negotiation remains mandatory.
• All 6 client mirrors (Rust, Kotlin, Swift, Go, .NET, TypeScript), JSON schemas, and docs regenerated via npm run generate — no generated file was hand-edited.
• New reducer fixtures (types/test-cases/reducers/280-290) and a new boundary-test suite (types/channels-canvas.test.ts) exercise the new channel's reducer logic and size/depth limits directly, not just the existing coverage-gate shim.
• Adds docs/.changes/ fragments describing the contract and native-client fixes. No invented release heading or release-time fragment collapse is included.

Validation

• npm run typecheck ✅
• npm run lint ✅
• npm run generate ✅ (clean, idempotent)
• npm run verify:release-metadata ✅
• npm run verify:change-fragments ✅
• npm run verify:generated ✅
• Node test suite: 476/476 passing, 100% coverage on the types/reducers.ts gate
• All seven language/check CI jobs pass at 46a47524: check, TypeScript, Swift, Rust, Kotlin, Go and .NET.
• Follow-up repairs cover missing generated imports/discriminators, Swift reserved words, native reducers and fixture dispatch, lossless canvas snapshots, Go empty-catalog preservation, and single/multi-host mirror revision/isolation behavior.
• The former changelog/version gate is resolved by removing the unauthorized version bump, not by adding a fake release heading. Only the human PR review policy remains pending.

Open items for reviewers

• No docs/guide/*.md canvas guide page yet (would need a new per-channel doc-generator function).
• ChatState intentionally does not carry a parallel canvases list; SessionState.canvases remains the single authoritative catalogue.
• Renderer choice (VS Code Webviews vs. Integrated Browser) is left open by design — every canvas type in this contract (especially CanvasSourcePresentation) is renderer-neutral and does not require that choice to be resolved.