kandev/docs/plans/plugin-backed-canvases/task-04-browser-data-state.md

id, title, status, wave, depends_on, plan, requirements, acceptance_criteria, system_design

id	title	status	wave	depends_on	plan	requirements	acceptance_criteria	system_design
04-browser-data-state	Browser application protocol	completed	4	03-isolated-browser-runtime	plan.md	REQ-PLUGINS-ISOLATED-WEB-APPS-004 REQ-PLUGINS-ISOLATED-WEB-APPS-005	AC-PLUGINS-ISOLATED-WEB-APPS-004.1 AC-PLUGINS-ISOLATED-WEB-APPS-004.2 AC-PLUGINS-ISOLATED-WEB-APPS-004.3 AC-PLUGINS-ISOLATED-WEB-APPS-004.4 AC-PLUGINS-ISOLATED-WEB-APPS-004.5 AC-PLUGINS-ISOLATED-WEB-APPS-004.6 AC-PLUGINS-ISOLATED-WEB-APPS-004.7 AC-PLUGINS-ISOLATED-WEB-APPS-004.8 AC-PLUGINS-ISOLATED-WEB-APPS-005.1 AC-PLUGINS-ISOLATED-WEB-APPS-005.2 AC-PLUGINS-ISOLATED-WEB-APPS-005.3 AC-PLUGINS-ISOLATED-WEB-APPS-005.4 AC-PLUGINS-ISOLATED-WEB-APPS-005.5	../../specs/plugins/system-design/isolated-web-app-contributions.md

Task 04: Browser application protocol

Summary

Add the versioned relative data, message, action, and instance-state routes. Reuse shared Plugin Host services and DTOs.

In scope

• Extract shared capability-gated Host data services.
• Add workflow_step_id to task read DTOs and adapters.
• Add relative task, workflow, workflow-step, and task-message routes.
• Route task updates and messages through normal domain services.
• Add instance JSON state with revision preconditions.
• Add stable safe errors, body limits, deadlines, and cancellation.
• Add browser and gRPC parity contract tests.

Out of scope

• Live event transport, canvas lifecycle, source publishing, and user interface.

Acceptance

• Browser and gRPC adapters return equivalent task and workflow data.
• A static application can send a task prompt and move a task through services.
• A stale state write returns the current revision without overwriting state.

Verification

cd apps/backend && go test ./internal/plugins/... ./pkg/pluginsdk/...

Files likely touched

• apps/backend/proto/kandev/plugin/v1/plugin.proto
• apps/backend/pkg/pluginsdk/data_types.go
• apps/backend/internal/plugins/host_data_*.go
• apps/backend/internal/plugins/host_write.go
• apps/backend/internal/plugins/webapp/data_handlers.go
• apps/backend/internal/plugins/webapp/state_handlers.go
• apps/backend/internal/plugins/action_handlers.go

Dependencies

• Task 03 provides the authorized runtime request context.

Risks

• A browser adapter can bypass service events or scope checks.
• A task projection without its workflow step makes ordered movement ambiguous.
• A delayed mutation response can overwrite a newer event without ordering data.

Parallelism

sequential

Inputs

• Browser data, shared state, managed action, and failure sections.
• ADR 0043 and current Host data, message, state, and wire tests.

Results

Completed on 2026-08-28. Added the relative versioned browser protocol for context, task and workflow data, workflow steps, task messages, actions, and revisioned instance state. Requests use authenticated capability bindings, bounded bodies and responses, cancellation deadlines, stable errors, and optimistic If-Match revisions. Focused and package-wide plugin tests pass.