App Engine Contract Gap Closure Report

Date: 2026-05-13
Owner: OMX implementation team
Scope: Highest-priority P0/P1 gaps from docs/app-engine-api-sync-gap-audit.md.

Executive summary

Implemented the highest-priority app-to-engine sync gaps that were explicitly listed in the audit:

• WebView/module runtime token exchange now uses app-engine scoped module tokens instead of exposing the app/Firebase auth token to module code.
• App-engine module-token issuance now fails closed unless the signed-in user is an active family member and the requested module is actively installed for that family.
• WebView runtime data get/set/list/delete calls now route through app-engine runtime data APIs.
• Runtime handlers now centralize permission checks for data.read, data.write, activity.write, and notifications.send.
• Marketplace install/uninstall app calls now use existing app-engine family module routes.
• Engine chat vote/proposal crash paths were replaced with engine-backed typed message send/response/close flows, including JSONB persistence on app-engine.
• Public docs were synced and this closure report was mirrored into membloc-docs.

No production deploy, release tags, secrets, Firebase project config, OCI config, or branch protection were touched. Legacy Firebase paths remain intact.

Closed gaps

Gap	Status	Evidence	Tests
Marketplace install/uninstall still app-only/Firebase-adjacent	Closed for app API-client layer	membloc-app commit af16bd2; lib/core/services/marketplace_api.dart; test/repositories/marketplace_api_test.dart	Marketplace + EngineHttpClient targeted Flutter tests pass
WebView auth.getAccessToken returned app/Firebase token instead of module runtime token	Closed for app bridge path	membloc-app commits 9a7c829, 6c14d93; lib/core/services/module_instance_service.dart; lib/core/modules/js_bridge_controller.dart; lib/core/services/module_runtime_api.dart	flutter test test/module_webview_runtime_bridge_test.dart passes
Module-token endpoint lacked active family/module-install access gate	Closed	membloc-app-engine commit 29a7129; internal/handler/auth.go; internal/handler/auth_module_token_test.go	go test ./internal/handler passes
Runtime data handlers did not consistently enforce data.read/data.write	Closed for handler permission gate	membloc-app-engine commit 29a7129; internal/handler/runtime.go; internal/handler/runtime_test.go	go test ./internal/handler passes
WebView runtime data bridge returned placeholder data/TODOs	Closed for runtime data CRUD	membloc-app commits 9a7c829, 6c14d93; JsBridgeController delegates data methods to ModuleRuntimeApi	Runtime bridge Flutter tests pass
Engine chat vote/proposal methods crashed with UnimplementedError	Closed for typed send/response/close	membloc-app commit 18c849a; membloc-app-engine commit 4fe35d4; EngineChannelRepository; app-engine channel handler/service/repository tests	Targeted Flutter checks and Go channel/service tests passed in worker lane
Docs sync for audit/closure evidence	Closed	membloc-docs commit 6e8a90a plus this updated sync	npm run sync-docs; npm run build

Remaining gaps and risks

• Full go test ./... is still blocked locally by PostgreSQL CREATE DATABASE privilege failures in internal/household/http and internal/lineage/http (SQLSTATE 42501). A CREATEDB-capable test role/DSN is needed for full engine integration verification.
• Runtime storage, runtime settings, ui.showConfirm, ui.shareToChannel, and real family/member/auth-info bridge payloads remain outside this P0/P1 implementation slice.
• Runtime activity and notifications now enforce permissions, but broader side effects/persistence/dispatch behavior still need product-specific implementation or explicit docs.
• Live WebView end-to-end testing against a running app-engine was not performed; verification is contract/unit-level.
• flutter analyze without --no-fatal-infos still reports seven pre-existing info-level lints outside these slices.
• membloc-docs build passes with a non-fatal Turbopack/NFT warning involving docs tracing.

Changed commits by repo

membloc-app

• af16bd2 - Wire module installs through the engine
• 9a7c829 - Make WebView modules use scoped runtime data tokens
• 18c849a - Stop engine chat vote and proposal actions from crashing
• 6c14d93 - Keep WebView runtime data on scoped module tokens

Primary files:

• lib/core/services/marketplace_api.dart
• test/repositories/marketplace_api_test.dart
• lib/core/services/module_instance_service.dart
• lib/core/services/module_runtime_api.dart
• lib/core/modules/js_bridge_controller.dart
• test/module_webview_runtime_bridge_test.dart
• lib/core/repositories/engine_channel_repository.dart
• lib/core/utils/firestore_date.dart

membloc-app-engine

• 4fe35d4 - Persist engine chat vote and proposal payloads
• 29a7129 - Gate module runtime tokens to installed family access

Primary files:

• internal/handler/auth.go
• internal/handler/auth_module_token_test.go
• internal/handler/runtime.go
• internal/handler/runtime_test.go
• internal/handler/channel.go
• internal/repository/channel.go
• internal/service/channel.go
• internal/service/channel_test.go
• cmd/server/main.go

membloc-docs

• 6e8a90a - Publish contract gap closure evidence
• Current sync mirrors this updated root report into content/platform/app-engine-contract-gap-closure-report.md.

Verification evidence

Repo	Command	Result
membloc-app-engine	go test ./internal/handler ./internal/service	Passed
membloc-app-engine	go vet ./...	Passed
membloc-app-engine	go build -o /tmp/membloc-app-engine-server ./cmd/server	Passed; tracked server binary clean
membloc-app-engine	go test ./...	Blocked only by local PostgreSQL CREATEDB privilege in household/lineage integration suites
membloc-app	flutter test test/module_webview_runtime_bridge_test.dart test/repositories/marketplace_api_test.dart test/repositories/engine_http_client_test.dart	Passed
membloc-app	flutter test	Passed; 359 tests
membloc-app	flutter analyze --no-fatal-infos	Passed with 7 known info lints
membloc-sdk	node membloc-sdk/membloc-sdk.test.cjs	Passed; 2 tests
membloc-developer-portal	npm run lint	Passed
membloc-developer-portal	npm run build	Passed
membloc-docs	npm run sync-docs	Passed
membloc-docs	npm run build	Passed with non-fatal Turbopack/NFT warning

Follow-up backlog

1. Provide a CREATEDB-capable local engine test database role and rerun go test ./....
2. Add live WebView/runtime E2E coverage against a running app-engine instance.
3. Implement or explicitly deprecate runtime storage/settings/confirm/share APIs.
4. Replace placeholder auth/family/member bridge responses with repository-backed data.
5. Define persistence/dispatch behavior for runtime activity and notifications.
6. Decide whether vote/proposal promote/retry should create calendar/task artifacts or remain best-effort no-op when no promoted event exists.