Introduction

The document site for light-portal application.

Architecture

Design

Light Portal is an application that connect the providers to the consumers, and it contains many components or applications. Each component will have some API endpoints and a user interface in the portal view single page application.

To allow the users to understand each component in detail in term of design, we have collected all the design documents in this section.

Portal View

Mutliple Environment

This document outlines the necessary changes to configure portal view to work dynamically across different environments (sdx, dev, non-prod, prod) using environment-specific configuration.

1. Environment Variables Setup

Create .env File

Create environment-specific .env files in project root:

# Environment variables
# VITE_BASE_PATH is used as the base URL prefix for API calls.
VITE_BASE_PATH=/bff/admin/
# VITE_PORTAL_URL is the full absolute URL where the frontend static files are served
VITE_PORTAL_URL=https://sdx.lightapi.net/bff

Required Environment Variables

• VITE_BASE_PATH: Defines the sub-path where your application is deployed.
• VITE_PORTAL_URL: The API endpoint base URL.

Benefits of .env Configuration

• Switch environments without code changes
• Maintain a single codebase for all environments

2. Vite Configuration Changes

File: vite.config.js Location: Project root

Required Change:

import { defineConfig, loadEnv } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), '');

  return {
    plugins: [react()],
    base: env.VITE_BASE_PATH || "/",
    // ... other configurations
  };
});

Why This Change is Necessary?

The Problem Without base Configuration

When your application is deployed to a sub-path rather than the domain root, all asset references break.

What base Affects

The base configuration controls how Vite prefixes:

• Static asset URLs (JavaScript, CSS, images, fonts)
• Client-side routing paths
• Public folder references

Example: Without vs With base

Without base Configuration:

• App hosted at: https://example.com/portal/
• Vite generates: <script src="/assets/index.js">
• Browser requests: https://example.com/assets/index.js
• Result: 404 Not Found ❌

With base: “/portal/”:

• App hosted at: https://example.com/portal/
• Vite generates: <script src="/portal/assets/index.js">
• Browser requests: https://example.com/portal/assets/index.js
• Result: Success ✅

3. React Router Configuration Changes

File: App.tsx Location: src/App.tsx

Required Change:

import { BrowserRouter } from 'react-router-dom';

function App() {
  const basename = import.meta.env.VITE_BASE_PATH || "/";

  return (
    <BrowserRouter basename={basename}>
      {/* Your app routes and components */}
    </BrowserRouter>
  );
}

export default App;

What basename Does

The basename prop tells React Router the base URL prefix for all routes in your application.

Routing Behavior Comparison

Why It’s Required

When your app is hosted at a sub-path (e.g., https://example.com/portal/), React Router needs to know that /portal is the deployment prefix, not part of your route definitions.

Without basename:

1. You define <Route path="/dashboard" />
2. User visits /portal/dashboard
3. React Router sees /portal/dashboard → no match → Route Not Found ❌

With basename="/portal":

1. React Router strips /portal from the URL
2. Sees /dashboard → matches your route → Success ✅

4. API Call Configuration

Current Behavior Issue

Without a configured base URL, the browser constructs API request URLs relative to the current page origin.

Example:

• App running at: https://example.com/portal/dashboard
• API call: fetch('/api/users')
• Browser sends request to: https://example.com/api/users

This may work in some cases but breaks when:

• API is hosted on a different domain/subdomain
• API has a different base path
• Cross-environment consistency is needed

Solution: Custom Fetch Wrapper

File: src/utils/fetchClient.js

const BASE_URL = import.meta.env.VITE_API_BASE_URL || "";

/**
 * Custom fetch wrapper with automatic base URL prefixing
 * @param {string} endpoint - API endpoint path (e.g., '/api/users')
 * @param {Object} options - Fetch options (method, headers, body, etc.)
 * @returns {Promise} - Response JSON
 */
async function fetchClient(endpoint, options = {}) {
  const url = `${BASE_URL}${endpoint}`;

  const defaultHeaders = {
    "Content-Type": "application/json",
  };

  const config = {
    ...options,
    headers: {
      ...defaultHeaders,
      ...options.headers,
    },
  };

  const response = await fetch(url, config);

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  return response.json();
}

export default fetchClient;

Usage Example

import fetchClient from './utils/fetchClient';

// GET request
const users = await fetchClient('/api/users');

// POST request
const newUser = await fetchClient('/api/users', {
  method: 'POST',
  body: JSON.stringify({ name: 'John Doe', email: '[email protected]' }),
});

// With custom headers
const data = await fetchClient('/api/protected', {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

Benefits

• Consistency: All API calls use the same base URL
• Environment flexibility: Different API endpoints per environment
• Maintainability: Single place to update API configuration
• Error handling: Centralized response validation

5. Build and Deployment Steps

Step 1: Change the .env variables for specific environment (sdx, dev, prod etc.)

VITE_BASE_PATH=/ (base path)
VITE_PORTAL_URL=https://example.com (endpoint URL)

Step 2: Build

npm run build

MCP Registry Design for AI Gateway

This document outlines the registration and management strategy for Model Context Protocol (MCP) tools within the AI Gateway.

Registration Strategy: The Hybrid Model

For a robust and scalable AI Gateway, the recommended approach is a Hybrid Model: Register the MCP Server as the primary entity, but manage and expose the Tools individually.

This approach balances the technical requirements of connectivity with the operational requirements of governance, security, and performance.

1. Register the Server (The “Connection” Layer)

The MCP Server should be treated as the source of truth and the primary unit of connectivity.

• Centralized Configuration: Authentication (API keys, OAuth), base URLs, transport protocols (SSE or Stdio), and environment variables are defined at the server level.
• Connectivity Management: A single server acts as a wrapper around related APIs. Registering tools individually would create significant overhead and redundant connections.
• Lifecycle & Health Monitoring: If an MCP server goes down, all its tools become unavailable. It is more efficient to monitor health and availability at the server level.
• Dynamic Discovery: The MCP protocol includes a tools/list capability. By registering the server, the gateway can automatically sync and discover new tools when the server is updated, eliminating the need for manual registration of every new function.

2. Expose Tools Individually (The “Governance” Layer)

While the gateway connects to the server, it should expose and manage tools as individual objects. This is crucial for:

• Granular Permissions (RBAC): Access control can be applied at the tool level. For example, a “Finance” team might be granted access to a get-invoice tool but restricted from a modify-ledger tool, even if both reside on the same ERP server.
• Context Window Optimization: Large Language Models (LLMs) have limited context windows. Sending all 50 tools from a large server to an LLM wastes tokens and increases the “lost in the middle” effect. The Gateway should allow for the activation of specific subsets of tools for a given AI session or agent.
• Rate Limiting & Cost Control: High-compute or high-cost tools (e.g., generate-video) can be rate-limited or billed differently compared to lightweight tools (e.g., get-weather).
• Safety & Compliance: Metadata can be attached to individual tools to flag them as Read-Only, Destructive, or Sensitive, enabling specific security flows (like “Human-in-the-loop” approvals) for risky operations.

Recommended Architecture: The “Catalog” Pattern

The implementation should follow a “Catalog” or “App Store” pattern:

1. Provider/Server Registration: An admin registers a server (e.g., “The GitHub MCP Server”) with its credentials.
2. Automated Discovery: The Gateway calls the server’s list_tools method and populates a tool catalog.
3. Governance & Activation: Admins “enable” specific tools for specific model configurations or user groups.
4. Routing Layer: When a model requests a tool, the Gateway resolves the request to the owning Server and handles the underlying communication.

Comparison of Approaches

Data Model & Schema Design

The AI Gateway leverages the existing API registry schema used by light-gateway, with specific enhancements to accommodate the unique requirements of the MCP protocol.

Conceptual Mapping

Core Tables & Enhancements

To support MCP, the following schema adjustments are implemented:

1. API Version (Server Connection)

The api_version_t table is enhanced to store transport-level configurations for stdio or SSE connections.

ALTER TABLE api_version_t ADD COLUMN transport_config TEXT;
-- JSON Example for transport_config: 
-- {"transport": "stdio", "command": "npx", "args": ["-y", "@mcp/server-google"]}

2. API Endpoint (Tool Definition)

The api_endpoint_t table acts as the tool registry. We relax the traditional HTTP method constraints and add fields for MCP tool metadata.

-- Allow 'call' as a valid operation for MCP tools
ALTER TABLE api_endpoint_t DROP CONSTRAINT api_endpoint_t_http_method_check;
ALTER TABLE api_endpoint_t ADD CHECK ( http_method IN ( 'delete', 'get', 'patch', 'post', 'put', 'call' ) );

-- Store the Tool Schema (for LLM validation) and Metadata (for safety flags)
ALTER TABLE api_endpoint_t ADD COLUMN tool_schema TEXT;   -- JSON Schema of the tool inputs
ALTER TABLE api_endpoint_t ADD COLUMN tool_metadata TEXT; -- e.g., {"destructive": true, "read_only": false}

Full Registry Schema Reference

-- API Definition (The MCP Server)
CREATE TABLE api_t (
    host_id                 UUID NOT NULL,
    api_id                  VARCHAR(16) NOT NULL,
    api_name                VARCHAR(128) NOT NULL,
    api_desc                VARCHAR(1024),
    api_status              VARCHAR(32) NOT NULL,
    active                  BOOLEAN NOT NULL DEFAULT TRUE,
    PRIMARY KEY (host_id, api_id)
);

-- API Version (The Connection/Transport)
CREATE TABLE api_version_t (
    host_id                 UUID NOT NULL,
    api_version_id          UUID NOT NULL,
    api_id                  VARCHAR(16) NOT NULL,
    api_version             VARCHAR(16) NOT NULL,
    api_type                VARCHAR(7) NOT NULL,    -- 'mcp', 'openapi', etc.
    transport_config        TEXT,                   -- MCP-specific connection data
    spec                    TEXT,                   -- Full tool manifest (optional)
    active                  BOOLEAN NOT NULL DEFAULT TRUE,
    PRIMARY KEY(host_id, api_version_id),
    FOREIGN KEY(host_id, api_id) REFERENCES api_t(host_id, api_id) ON DELETE CASCADE
);

-- API Endpoint (The Individual Tool)
CREATE TABLE api_endpoint_t (
    host_id              UUID NOT NULL,
    endpoint_id          UUID NOT NULL,
    api_version_id       UUID NOT NULL,
    endpoint             VARCHAR(1024) NOT NULL,  -- Tool Name
    http_method          VARCHAR(10),             -- 'call' for MCP
    endpoint_name        VARCHAR(128) NOT NULL,
    endpoint_desc        TEXT,
    tool_schema          TEXT,                    -- Input parameter validation
    tool_metadata        TEXT,                    -- Safety and cost metadata
    active               BOOLEAN NOT NULL DEFAULT TRUE,
    PRIMARY KEY(host_id, endpoint_id),
    FOREIGN KEY(host_id, api_version_id) REFERENCES api_version_t(host_id, api_version_id) ON DELETE CASCADE
);

Tool Metadata & Synchronization

Populating the api_endpoint_t table involves coordinating data from the MCP Server with operational policies defined within the AI Gateway.

Sources of Metadata

The metadata for each tool is synthesized from three primary sources:

1. Standard MCP Server Response (Automated)

When the Gateway performs a tools/list call, the MCP server provides the baseline technical definition for each tool.

• Source Fields: name, description, inputSchema.
• Mapping: These are mapped directly to endpoint, endpoint_desc, and tool_schema respectively.

2. Gateway Operational Enrichment (Manual/Policy)

Since the standard MCP protocol does not include operational flags (like safety or cost), the AI Gateway manages these in the tool_metadata JSON column.

• Administrative Enrichment: Platform admins use the Gateway UI to tag specific tools. Common tags include:
  • destructive: true: Triggers a warning or confirmation flow.
  • human_approval_required: true: Places the request in a queue for manual sign-off.
  • cost_tier: "high": Used for rate-limiting or internal billing.
• Heuristic Auto-Tagging: The Gateway can automatically infer metadata based on patterns. For example, any tool starting with get_ or list_ is auto-flagged as read_only: true.

3. Protocol Extensions (Custom)

The MCP specification allows for additional properties in the tool object. If a custom MCP server includes an extra metadata or annotations block, the Gateway’s synchronization logic can be configured to capture and store these directly.

Synchronization Workflow

The following lifecycle ensures the Gateway’s registry remains accurate:

1. Connection: The Gateway establishes a connection to the server using the transport_config.
2. Discovery (Sync): The Gateway calls tools/list and performs an “upsert” for all tools found.
   • Existing tools have their tool_schema and endpoint_desc updated.
   • New tools are created with a default active status and baseline tool_metadata.
3. Review: An administrator reviews the newly discovered tools in the Gateway dashboard.
4. Governance Policy: The administrator “enables” the tool for specific roles and configures any required safety metadata (e.g., flagging the drop_table tool as destructive).
5. LLM Execution: When a model calls the tool, the Gateway uses the stored tool_schema for pre-flight validation and the tool_metadata to enforce security policies.

Too Many Pages/Forms

The portal has accumulated many pages, generated forms, custom admin screens, and feature-specific entry points. The sidebar can expose these pages, but it does not help a user understand which pages are required to finish a real business task. The MCP Gateway quick start wizard is a useful experiment, but it also shows the limitation of a rigid linear wizard: real tasks have optional steps, pre-existing data, and multiple valid starting points.

This document proposes a task-oriented navigation layer for portal-view.

Problem

Users currently need to know the portal information architecture before they can complete a task. For example, onboarding an API to MCP Gateway may require some combination of:

• create or select an API
• create or select an API version
• link the API version to a gateway or sidecar instance
• select MCP tools
• configure access control
• revisit instance, API, or role administration later

The same pattern exists across other areas. A task is not a single route; it is a sequence of related pages and forms. The current navigation model makes users pick pages first, then infer the task process themselves.

Current MCP Wizard Observation

The MCP Gateway wizard already has useful building blocks:

• flowConfig.tsx keeps step metadata in one place.
• McpServerForm.tsx renders a generic wizard shell.
• useMcpPrefill.ts can resume from URL context such as apiId, apiVersionId, and instanceApiId.
• Several steps are marked skippable.

However, the wizard is still too rigid:

• Step order is linear even when the task is naturally conditional.
• Initial step selection relies on hard-coded step numbers.
• Optional work is represented as skip buttons instead of task state.
• The wizard duplicates or wraps existing forms instead of treating existing pages/forms as first-class task steps.
• The solution is specific to MCP Gateway and does not help users navigate the rest of the portal.

Design Goals

• Let users start from a task, not a page name.
• Keep existing pages and generated forms as the source of truth.
• Support multiple entry points into the same task.
• Detect what has already been completed and show only relevant next actions.
• Support optional, required, blocked, complete, and skipped steps.
• Preserve role-based visibility and host-specific context.
• Allow users to leave a task, return later, and continue from context.
• Make the approach reusable for MCP, API publishing, access control, deployment, config promotion, migration, and admin workflows.

Non-Goals

• Do not replace every admin page with a wizard.
• Do not create a separate custom form for each task if an existing generated form already works.
• Do not use the sidebar as the only navigation surface.
• Do not force a strict step sequence when the data model allows safe jumping.

Proposed Solution

Add a task-oriented navigation layer above the current pages/forms.

The main pieces are:

1. Task Center
2. Task Registry
3. Task Progress Resolver
4. Task Navigation Shell
5. Global Search and Command Palette
6. Contextual Next Actions

Task Center

The Task Center is a page where users choose what they want to accomplish. It should group work by intent, not by implementation table.

Example task groups:

• API Marketplace
  • Register a new API
  • Add an API version
  • Publish an API
  • Review API details
• MCP Gateway
  • Onboard an existing API to MCP Gateway
  • Register a standalone MCP server
  • Configure MCP tools
  • Configure MCP access control
• Access Control
  • Create role
  • Assign permissions
  • Configure endpoint access
• Platform Operations
  • Register controller/gateway instance
  • Link API version to instance
  • Promote configuration
• Portal Administration
  • Manage host users
  • Export/import portal data
  • Convert migration snapshot

Each task card should show:

• title
• short description
• required role
• common starting object, such as API, instance, host, or client
• progress status when the current context is known
• primary action such as Start, Continue, Review, or Fix Missing Step

Task Registry

Introduce a registry that describes tasks and steps declaratively. This is the generalized version of the current MCP flowConfig.tsx, but it should route to existing pages/forms instead of rendering every step inside one wizard.

Example TypeScript shape:

export type TaskDefinition = {
  id: string;
  title: string;
  description: string;
  category: string;
  roles?: string[];
  keywords: string[];
  entryPoints: TaskEntryPoint[];
  steps: TaskStep[];
};

export type TaskStep = {
  id: string;
  title: string;
  description?: string;
  required: boolean;
  dependsOn?: string[];
  route: (ctx: TaskContext) => string;
  formId?: string;
  completeWhen?: TaskCompletionCheck;
  visibleWhen?: TaskVisibilityCheck;
  blockedWhen?: TaskBlockedCheck;
};

The task registry should live close to portal navigation code, for example:

src/tasks/taskRegistry.ts
src/tasks/taskTypes.ts
src/tasks/resolvers/
src/pages/tasks/TaskCenter.tsx
src/pages/tasks/TaskDetail.tsx

Page And Form Metadata

To make search and tasks work well, pages and generated forms need metadata.

For generated forms, the metadata can come from Forms.json plus a small registry override when the form title is not enough.

For custom pages, add a route/page registry:

export type PageDefinition = {
  route: string;
  title: string;
  description?: string;
  category: string;
  roles?: string[];
  keywords: string[];
  entities?: string[];
};

This registry can feed:

• sidebar sections
• Task Center
• command palette
• page breadcrumbs
• contextual next actions

The important rule is that page/form metadata should be reused, not copied into each wizard.

Task Progress Resolver

A task should not blindly ask users to complete steps that are already done. Each task can have a resolver that checks the current host and entity context.

For MCP Gateway, the resolver can check:

• API exists
• API version exists
• instance API link exists
• MCP tool configuration exists
• access control exists

The UI then marks each step:

• Complete
• Required
• Optional
• Blocked
• Skipped
• Needs review

The resolver should use existing query endpoints where possible. The first implementation can query on page load. Later, it can cache per task/session.

Task Navigation Shell

Instead of a full-screen wizard that owns all steps, use a task shell that can wrap or accompany existing pages.

Recommended behavior:

• A task detail page shows the checklist and current state.
• Selecting a step navigates to the existing page/form with task context in the URL or router state.
• The target page shows a compact “Task” panel or return link.
• After save, the user can return to the checklist or continue to the next recommended step.

Example URL:

/app/form/createService?task=mcp-onboard-api&returnTo=/app/tasks/mcp-onboard-api

This keeps existing page behavior intact while adding guided navigation.

Global Search And Command Palette

The portal should have a global launcher. It should search tasks, pages, forms, and entities.

Examples:

• “onboard mcp”
• “create api”
• “auth client”
• “relation type”
• “instance api”
• “export snapshot”

Search results should be role-aware and host-aware.

Result types:

• Task
• Page
• Form
• Entity
• Recent item

This is the fastest way to help expert users without forcing them through a wizard.

Contextual Next Actions

Detail pages should expose next actions based on the current entity.

Examples:

• API detail
  • Add version
  • Link version to gateway
  • Configure MCP tools
  • Configure access control
• Instance detail
  • Link API version
  • Configure MCP tools
  • View gateway servers
• Auth client detail
  • Assign owner
  • Review sessions
  • Review audit
• Snapshot export
  • Convert snapshot
  • Import snapshot

These actions should come from the same task registry, not from one-off buttons hard-coded on every page.

MCP Gateway Example

The MCP Gateway quick start can be rebuilt as a task:

Task: Onboard API to MCP Gateway

Steps:
1. Select or create API
2. Select or create API version
3. Choose deployment mode
4. Link API version to gateway or sidecar instance
5. Select MCP tools
6. Configure access control

Step behavior:

• API selection is required unless apiId is already provided.
• API version is required unless apiVersionId is already provided.
• Spec upload is optional and only shown when creating a new API/version.
• Deployment mode is required when the version is not linked.
• Gateway selection is required only for centralized deployment.
• Tool selection is optional if users only want to register the server first.
• Access control is optional but should be shown as a recommended final step.

This task can support several entry points:

/app/tasks/mcp-onboard-api
/app/tasks/mcp-onboard-api?apiId=...
/app/tasks/mcp-onboard-api?apiId=...&apiVersionId=...
/app/tasks/mcp-onboard-api?instanceApiId=...

The UI should not rely on fixed step numbers. It should compute visible steps from the task context and completion state.

Task State

Start with client-side state:

• URL query parameters for entity context
• sessionStorage for in-progress task context
• existing backend records for real completion state

Later, add persisted task state if needed:

• user id
• host id
• task id
• context JSON
• skipped step ids
• last active step
• updated timestamp

Persisting task state should not become the source of truth for business data. It should only remember navigation state and user choices. Completion should be derived from actual portal records.

Sidebar Role

The sidebar should become smaller and more stable. It should expose major areas, not every page/form.

Recommended sidebar sections:

• Home
• Tasks
• Marketplace
• MCP Gateway
• Operations
• Administration

Deep links should still exist, but they should be discoverable through search, contextual actions, and task detail pages.

Implementation Plan

Phase 1: Inventory And Metadata

• Create page/form metadata registry.
• Add task registry types.
• Register the most-used pages and forms.
• Add global search over registered tasks/pages/forms.

Phase 2: Task Center

• Add /app/tasks.
• Add task category cards.
• Add task detail checklist page.
• Implement client-side task context with URL parameters and session storage.

Phase 3: MCP Gateway Task

• Convert the current MCP wizard flow into mcp-onboard-api task definition.
• Reuse existing MCP components for the pages that still need custom UI.
• Replace hard-coded step numbers with resolver-driven visible steps.
• Add return-to-task behavior after saves.

Phase 4: Contextual Actions

• Add task actions to API detail and instance detail pages.
• Add task actions to access control and config pages where appropriate.
• Use the task registry to drive action visibility.

Phase 5: Broader Rollout

• Add tasks for API publishing, config promotion, host/user management, and snapshot export/import.
• Reduce sidebar clutter once task/search usage is available.
• Add persisted task state only if session storage is not enough.

Risks And Mitigations

Recommendation

Keep the MCP Gateway wizard as a prototype, but do not build more isolated wizards in the same style. The long-term solution should be:

• a task registry
• a Task Center
• resolver-driven progress
• global search
• contextual next actions
• reuse of existing pages and generated forms

This gives new users guided paths while still letting experienced users jump directly to the page or form they already know.

Config Update Page

The current portal-view configuration admin area is complete but split across many table pages and generated forms. A customer Settings page shows a denser workflow: list applicable config properties in a tree, edit scalar values inline, and open a modal for list/map values. This document proposes a similar page for portal-view that can update config property overrides at the environment, product, product version, instance, API, app, and app-api levels. In this document, API, app, and app-api mean the instance-linked config override scopes represented by instanceApiId, instanceAppId, and instanceApiId + instanceAppId.

Current Implementation

The customer Settings implementation is centered on these files:

• Settings.jsx
• SettingsListView.jsx
• SettingsListMapModal.jsx
• InputForm.jsx
• JsonSchemaForm.jsx

The useful behavior is:

• one page loads applicable config properties and the current custom values
• properties are displayed as a tree under configName
• scalar values are edited inline
• list and map values open a modal with form, raw JSON, and raw YAML tabs
• save chooses create or update based on whether the override exists
• delete removes the override and lets the inherited value show again

The customer implementation currently handles instance, instance API, instance app, and instance app API targets. It chooses the query/write action from instanceId, instanceApiId, and instanceAppId.

portal-view already has separate config override pages:

• src/pages/config/ConfigEnvironment.tsx
• src/pages/config/ConfigProduct.tsx
• src/pages/config/ConfigProductVersion.tsx
• src/pages/config/ConfigInstance.tsx
• src/pages/config/ConfigInstanceApi.tsx
• src/pages/config/ConfigInstanceApp.tsx
• src/pages/config/ConfigInstanceAppApi.tsx

Those pages use Material React Table, fetch one override aggregate at a time, and navigate to generated react-schema-form routes for create/update. The form definitions live in src/data/Forms.json, and the generic form runner is src/components/Form/Form.tsx.

The existing form approach works for CRUD, but it is inefficient for config editing because the user must pick a config, pick a property, leave the list page, edit one value, and return.

Goals

• Provide a single task-oriented config editor for the seven override scopes.
• Show the property catalog and current override values together.
• Preserve the existing config-command write APIs.
• Preserve optimistic concurrency by carrying aggregateVersion for existing override rows.
• Avoid client-side joins across independently paginated result sets.
• Keep existing table pages and generated forms available as admin fallback routes.
• Support scalar editing inline and structured list/map editing in a modal.
• Show inherited/default value and custom override value separately.
• Make delete/reset mean “remove this override”, not “delete the base property”.
• Support read-only and hidden states when the user lacks write permission for a scope or target.

Non-Goals

• Do not replace react-schema-form globally.
• Do not replace the existing config list pages during the first release.
• Do not edit File or Cert property values inline in the first release. Those can continue to use existing generated forms.
• Do not require every config property to have a typed form schema before the page is useful.
• Do not add a bulk transaction command in the first release. The UI can stage multiple changes and then orchestrate the existing single-row commands.

Recommended UX

Add a Config Update page under the configuration task area. The first row is a scope and target selector:

• Scope: Environment, Product, Product Version, Instance, API, App, App API
• Target: the selected scope’s identity, such as environment, productId, productVersionId, instanceId, instanceApiId, instanceAppId, or both app/API ids for app-api
• Optional filters: config phase, config type, property type, resource type, and “show overridden only”
• Save mode: staged changes by default, with optional single-row Apply for quick edits

Below the selectors, render a tree/table:

• group rows by configName
• property leaf rows show propertyName
• columns: value type, inherited value, override value, effective source, required, resource type, config phase, description, status
• row status: inherited, overridden, dirty, saving, conflict, error
• toolbar actions: expand all, collapse all, refresh, reset override, review changes, apply changes
• row action menu: view history, open fallback form, copy identifiers

Editing behavior:

• string: inline text editor or larger popover editor for long values
• boolean: select true/false
• integer and float: numeric editor with validation before save
• list and map: open a structured modal
• unsupported valueType: view-only with a link to the existing form route
• propertyType File or Cert: open the existing create/update form in a drawer or modal overlay

The page should keep the inherited/default value visible while editing an override. If the override is deleted, the row remains visible and falls back to the inherited value.

The staged-change panel should list every pending create, update, and reset before applying. This matters for coordinated changes such as enabling a flag and setting a related URL. The backend commands can still run one by one, but the user gets a review step and can see partial failures without losing the full set of intended changes.

The row action menu should include View History. It should link to the audit log or history page pre-filtered by configId, propertyId, and the selected scope target. The row already shows updateUser and updateTs; history gives operators the deeper trail they need when debugging production configuration changes.

Structured Value Modal

The modal should start with raw JSON and raw YAML tabs. If a schema is available for the property, add a Form tab.

The customer code loads schema assets with:

schemas/<propertyName>/<propertyName>.json
schemas/<propertyName>/config.js

portal-view does not currently have this property-schema convention, so the first implementation should not depend on local schema assets. Use raw JSON/YAML with syntax and JSON validation first. Typed form support should come from the light-portal schema registry through schema-query, schema-command, and schema_t.

If a row has a schemaId and schemaVersion, the dialog should lazily fetch the published schema body from schema-query when the user opens the structured editor. The main getConfigUpdateProperties response should include schema metadata but not schemaBody, so the paginated table does not move large schema documents unnecessarily.

The schema association should key by configId + propertyId. Human-friendly keys such as configName + propertyName can be shown in the UI, but should not be used as the durable validation key.

List/map values should be saved as compact JSON strings because the command APIs store propertyValue as a string.

Schema Registry Validation

The schema registry should be used for structured map and list values once the registry is hardened enough for production validation. The config update page should treat the registry as optional per property: rows with no schema still use valueType validation and raw JSON/YAML editing.

getConfigUpdateProperties should return lightweight schema metadata:

{
  "schemaId": "security-jwt-claim-mapping",
  "schemaVersion": "1.0.0",
  "schemaType": "json",
  "schemaStatus": "P",
  "hasSchema": true
}

The UI should enable the Form tab only when the schema exists, is published, and is compatible with the property value type. Schema documents should be cached by hostId + schemaId + schemaVersion, with host-specific lookup falling back to a global schema.

Validation must run in both places:

• frontend validation gives immediate editor feedback and highlights the JSON path that failed
• backend validation remains authoritative in the config command handlers before a create or update override is accepted

Backend validation should parse propertyValue according to valueType before running JSON Schema validation. The UI should normalize YAML input to compact JSON before sending the command payload, so the command APIs continue to receive string values.

The schema registry needs a config-property binding before this can be enabled. The preferred minimal binding is schemaId + schemaVersion on the base config property definition. If tenant-specific schemas are needed later, schema lookup can resolve the same schema id/version against the selected hostId first and then fall back to the global row.

API Matrix

The write side can reuse the current command APIs.

For existing override rows, the update/delete payload must include the current aggregateVersion so the event persistence layer can enforce the monotonic version check. For new override rows, the page sends the scope identity, configId, propertyId, and propertyValue.

Security And RBAC

The page must not assume that a user who can view configuration can write every override scope. The selected scope and target should be checked against the same permission model used by the existing config admin routes and command handlers.

Recommended behavior:

• hide scopes the user cannot see
• show read-only rows for scopes the user can read but cannot update
• disable apply/reset controls when the selected target is not writable
• show a lock icon or tooltip for read-only rows
• keep backend command authorization authoritative, even when the UI already filtered the control

Unauthorized command responses should be mapped back to the row that triggered the command. The page should not fail the entire table because one row is not writable.

Read Model

The instance-facing scopes already have applicable-property queries:

• getApplicableConfigPropertiesForInstance
• getApplicableConfigPropertiesForInstanceApi
• getApplicableConfigPropertiesForInstanceApp
• getApplicableConfigPropertiesForInstanceAppApi

These queries return property metadata and inherited/effective values, including:

• configId
• configName
• configPhase
• configType
• propertyId
• propertyName
• propertyType
• propertyValue
• propertySource
• propertySourceType
• valueType
• resourceType
• required
• displayOrder

The same page needs current override metadata from:

• getConfigInstance
• getConfigInstanceApi
• getConfigInstanceApp
• getConfigInstanceAppApi

The page should not join applicable rows and override rows across separately paginated API calls. That produces brittle pagination, filtering, sorting, and row-count behavior. Instead, Phase 1 should add a merged backend read model that returns one row per configurable property with inherited value, override value, effective value, override metadata, and permission hints.

Environment, product, and product version currently have list/getFresh queries for existing overrides, but they do not have equivalent applicable-property queries:

• getConfigEnvironment
• getConfigProduct
• getConfigProductVersion

The new merged query should cover these scopes before they are exposed in the new page. A temporary client merge is acceptable only for a local prototype with unpaginated data; it should not be shipped as the production page behavior.

Proposed Generic Query

Add a Phase 1 query such as getConfigUpdateProperties in config-query.

Request:

{
  "hostId": "host uuid",
  "scope": "instance",
  "target": {
    "instanceId": "instance uuid"
  },
  "filters": {
    "configPhases": ["R"],
    "propertyTypes": ["Config"],
    "resourceTypes": ["all"]
  },
  "offset": 0,
  "limit": 1000,
  "active": true
}

Response:

{
  "total": 1,
  "properties": [
    {
      "scope": "instance",
      "hostId": "host uuid",
      "configId": "config uuid",
      "configName": "security.yml",
      "configPhase": "R",
      "propertyId": "property uuid",
      "propertyName": "jwt.clockSkew",
      "propertyType": "Config",
      "valueType": "integer",
      "resourceType": "all",
      "required": false,
      "schemaId": "security-jwt-clock-skew",
      "schemaVersion": "1.0.0",
      "schemaType": "json",
      "schemaStatus": "P",
      "defaultValue": "60",
      "defaultSourceType": "config_property",
      "overrideValue": "120",
      "overrideAggregateVersion": 3,
      "effectiveValue": "120",
      "effectiveSourceType": "config_instance",
      "canUpdate": true,
      "canDeleteOverride": true
    }
  ]
}

This query should be read-only. It does not need new write commands.

The query owns inheritance and candidate selection. The frontend owns presentation, editing state, and calls to the existing command APIs.

Frontend Structure

Recommended files:

src/pages/config/update/ConfigUpdatePage.tsx
src/pages/config/update/ConfigUpdateTable.tsx
src/pages/config/update/ConfigValueEditor.tsx
src/pages/config/update/ConfigStructuredValueDialog.tsx
src/pages/config/update/configUpdateScopes.ts
src/pages/config/update/configUpdateApi.ts
src/pages/config/update/configValue.ts
src/pages/config/update/configUpdateDraft.ts

configUpdateScopes.ts should be the single source of truth for scope metadata:

type ConfigUpdateScope = {
  id: 'environment' | 'product' | 'productVersion' | 'instance' | 'api' | 'app' | 'appApi';
  label: string;
  targetKeys: string[];
  applicableQuery?: string;
  overrideQuery: string;
  overrideResponseKey: string;
  createAction: string;
  updateAction: string;
  deleteAction: string;
  getFreshAction?: string;
  defaultResourceTypes?: string[];
  defaultConfigPhases?: string[];
};

The page should avoid hard-coding create/update/delete branching inside cell handlers. The handler asks the selected scope metadata which action and keys to use.

Draft And Apply Flow

The default edit mode should stage changes locally. A dirty row is not saved until the user chooses Apply for that row or Review & Apply from the toolbar.

The draft model should track:

• operation: create, update, reset
• previous effective value
• next override value
• scope target keys
• configId
• propertyId
• current aggregateVersion
• validation state

The review dialog should group changes by operation and show enough context for operators to catch mistakes before applying. If multiple commands are applied and one fails, the dialog should show which rows succeeded and which rows need attention. The page should refetch or refresh successful rows and leave failed rows dirty with their error state intact.

Save Flow

1. User edits a row.
2. UI validates the value against valueType and the schema registry when a published schema is attached to the property.
3. UI marks the row dirty and stores a draft operation.
4. User applies a row or opens Review & Apply.
5. UI builds payload from selected scope, row configId, row propertyId, and normalized propertyValue.
6. If an active override row exists, call the update action and include aggregateVersion.
7. If no active override row exists, call the create action.
8. On success, update the row with returned aggregate version or refetch that row.
9. On conflict or error, keep the draft value, restore the displayed committed value, and show the row error.

The local override map should store the full override row, not just the string value. At minimum it needs:

• propertyValue
• aggregateVersion
• active
• scope identity fields
• updateUser
• updateTs

Before update or delete, the UI should support the same getFresh* pattern used by the existing admin pages. If the row has been open for a while, the Apply action can fetch the latest row to get the freshest aggregateVersion. At minimum, a version conflict must offer a “Refresh Row & Try Again” action that reloads that row, compares the current backend value with the user’s draft, and lets the user reapply intentionally.

Validation errors should stay close to the edited cell. For example, an invalid integer should keep the cell in edit/error state with a short message. Backend validation, authorization, and conflict errors should be attached to the row that caused them, not only shown as a global toast.

Reset Flow

Reset means delete the override for the selected target and property.

1. User selects an overridden row.
2. UI calls the scope’s delete action with target keys, propertyId, and aggregateVersion.
3. On success, clear overrideValue and overrideAggregateVersion.
4. The displayed effective value reverts to the inherited/default value.

Rows with no override should not allow reset.

Like update, reset should support getFresh* before delete or expose the same “Refresh Row & Try Again” conflict path.

Routing

Add a route such as:

/app/config/update

The route should accept task context and target context through query params:

/app/config/update?scope=api&instanceApiId=...&task=mcp-onboard-api

Existing config table pages can link to it when they already have target context. Existing generated forms should remain available from row overflow actions for advanced edits and File/Cert values.

The View History row action should preserve context by opening the audit trail in a drawer, modal, or task-aware route with filters already applied. The filter payload should include the selected scope, target keys, configId, and propertyId.

For fallback forms, prefer opening the existing react-schema-form experience inside a drawer or modal over navigating away from the table. That keeps the user’s current scope, filters, expansion state, selected row, and staged changes intact. Full-page navigation can remain as a secondary fallback for complex forms that cannot safely render in an overlay.

Implementation Plan

Phase 0: schema registry foundation for config validation

• Harden schema-query, schema-command, and schema_t enough for production JSON Schema lookup.
• Add a durable config-property-to-schema association with schemaId and schemaVersion.
• Make schema lookup tenant-aware: host-specific schema first, global schema second.
• Validate schema bodies on schema create/update.
• Add backend config value validation for create/update override commands.
• Add tests for schema CRUD, tenant/global lookup, version pinning, and invalid config property values.

Phase 1: merged read model and instance-facing MVP

• Add getConfigUpdateProperties or an equivalent merged query in config-query.
• Return candidate properties, inherited values, current override values, override metadata, schema metadata, and permission hints in one paginated/sortable result.
• Build the page for Instance, API, App, and App API.
• Use existing command APIs for create/update/delete.
• Support scalar inline edits.
• Support list/map raw JSON/YAML modal.
• Support staged changes and Review & Apply.
• Support row-level validation/error/conflict states.
• Enable the typed Form tab only for properties with a published schema.

Phase 2: higher-level scopes

• Add Environment, Product, and Product Version selectors.
• Expose each scope only through the merged read model, not a client-side paginated join.
• Ensure product version respects product-version config/property mappings where available.

Phase 3: typed structured forms

• Use the schema registry for list/map config properties.
• Support custom validators by property key.
• Add tests for string array, object array, map, and malformed JSON/YAML values.

Phase 4: task integration

• Link from configuration task panels to /app/config/update.
• Add contextual next actions from instance, API, app, and app-api pages.
• Keep generated create/update forms as drawer/modal fallback actions.

Risks And Open Questions

• Environment inheritance needs a precise target rule. Existing applicable instance queries include environment_property as an inherited source, but the target environment is not selected by the current instance-facing query contract.
• Product and product-version candidate lists can be too broad if they are loaded from all config properties. Product version should eventually use the product version config mappings.
• The customer Settings code stores custom values in a map keyed by propertyId; for portal-view, the key should include scope target plus propertyId to avoid collisions when multiple targets are loaded.
• propertyId is the stable merge key only after the candidate list has been constrained to the selected target. If multiple configs can contain the same property id in unusual imports, use configId + propertyId.
• The page should avoid silently editing File or Cert values as plain text.
• Staged apply is not atomic until a bulk command exists. The UI must show partial success and partial failure clearly.
• Overlaying generated forms in a drawer depends on the form runner handling router state, success/failure navigation, and task context without forcing a full-page transition.
• The schema registry is not fully implemented and tested yet. Schema-backed validation should not be enabled until tenant-aware lookup, version pinning, and backend command validation are in place.

Recommendation

Build the page as a new task-oriented editor, not as a rewrite of the existing config admin tables. Make the merged getConfigUpdateProperties read model a Phase 1 backend requirement so the frontend does not perform brittle pagination-sensitive joins. Start frontend exposure with the four instance-facing scopes, then add environment, product, and product version once the same merged query handles their inheritance and candidate-selection rules.

Implement the minimal schema registry foundation before enabling schema-backed validation in the config update page. The raw JSON/YAML editor and scalar valueType validation can be built in parallel, but the Form tab and backend schema enforcement should wait for the registry work.

Config Snapshot Output and Comparison

The /app/config/configSnapshot page lists effective configuration snapshots and links to the raw snapshot tables, but it does not show the final values.yml represented by a snapshot. It also requires users to inspect snapshots one at a time. This document adds a deterministic values.yml output for each row and a comparison workflow for two to four snapshots. The same comparison engine supports historical selection from the snapshot page and current-snapshot selection across instances from /app/instance/instanceAdmin.

Decision Summary

• Add a View values.yml row action. It opens a read-only preview with Copy and Download actions.
• Generate the YAML on the server from the complete snapshot. Do not assemble it from the paginated property table in the browser.
• Select historical data by explicit hostId + snapshotId; do not reuse the runtime query that implicitly selects only the snapshot marked current.
• Add Compare current snapshots to InstanceAdmin. It resolves the current snapshot for each selected instance, then opens the same comparison route with exact snapshot ids.
• Define one canonical YAML contract for the portal query and both the Java and Rust config servers. The Java services share one codec; the Rust service implements the same contract against the same golden test vectors.
• Let users compare two, three, or four snapshots in a semantic property matrix. Two snapshots remain the normal and simplest case.
• Offer a literal side-by-side YAML diff only when exactly two snapshots are selected. Three or four full YAML panes are too narrow to read reliably.
• Compare effective typed values by default and show source-only changes separately.

Pre-Implementation Baseline

This section records the baseline that motivated the design. The feature has since been implemented; the authoritative implementation and acceptance state is recorded in the two linked implementation plans and their shared 2026-07-14-config-snapshot-live-acceptance.md evidence record.

portal-view/src/pages/snapshot/ConfigSnapshot.tsx renders a server-paginated Material React Table. It calls lightapi.net/config/getConfigSnapshot/0.1.0, defaults the current filter to true, and identifies each row by instanceId + snapshotId. Existing row actions update or delete the header and navigate to the effective property, file, deployment, API, app, app-api, instance, environment, product, and product-version snapshot tables.

portal-view/src/pages/instance/InstanceAdmin.tsx is also server-paginated. Its rows already contain hostId, instanceId, instanceName, serviceId, and envTag, and each row has a Snapshot action that opens the snapshot page for that instance. It does not currently support row selection. Its current field belongs to the instance record and is not a config snapshot id or proof that config_snapshot_t contains a current row.

Snapshot creation calls the PostgreSQL create_snapshot procedure. The procedure copies the raw override levels and materializes one effective row per snapshotId + configPhase + configId + propertyId in config_snapshot_property_t. Each effective row records:

• config_phase
• config_id and property_id
• property_name and property_type
• property_value and value_type
• source_level

The Java light-config-server already turns current snapshot rows into YAML. Its snapshot query joins config_snapshot_property_t to config_t, emits the key as configName.propertyName for Config properties, orders by the emitted key, parses values according to value_type, and writes a # source_level comment before each entry. However, that query locates a snapshot indirectly with current = true, serviceId, and environment. It cannot output a specific historical row selected in portal-view.

The Rust config server in portal-service/apps/config-server independently exposes /config-server/configs. It loads current snapshot rows through portal-service/crates/portal-core, then currently formats each property_value directly into YAML without using the returned value_type. It cannot consume a Java shared utility class, so it requires a Rust canonical codec and cross-language parity fixtures if both config-server implementations are supported.

The current PostgreSQL schema does not enforce the resolver’s cardinality assumption. config_snapshot_t has no index beginning with (host_id, instance_id, current) and no partial uniqueness constraint for current rows. Its broader scope index begins with host_id, environment, so it does not directly cover a host/instance/current lookup. The Java persistence path attempts to clear an older current row, but its update is scoped by instance_id rather than the full host_id + instance_id identity. The database can therefore contain duplicate current rows and the resolver must not depend on application convention alone.

The existing getConfigSnapshotProperty action is not an appropriate export API. It is paginated, accepts only snapshotId, returns stored strings rather than typed values, and does not enforce the full YAML serialization contract. Using it from the browser could silently omit properties or produce values whose YAML types differ from runtime configuration.

Goals

• Let an authorized user view, copy, and download the runtime values.yml for any current or historical configuration snapshot.
• Make output deterministic so two semantically identical snapshots generate identical YAML and the same digest.
• Make effective configuration drift visible without requiring users to open every snapshot property page.
• Let users compare the current effective configuration of two to four same-service instances directly from InstanceAdmin.
• Support the common two-snapshot comparison and useful three- or four-snapshot comparisons without making the page unreadable.
• Keep snapshot metadata visible so users know which instance, environment, timestamp, and current state each value belongs to.
• Preserve value types, nested maps, and list order.
• Prevent cross-host snapshot access and avoid persisting sensitive output in browser storage.

Non-Goals

• Do not compare raw override tables in the first release. The comparison is of the effective values.yml materialized in config_snapshot_property_t.
• Do not include File or Cert snapshot rows in values.yml. The existing Snapshot Files action remains the inspection path for those artifacts.
• Do not compare more than four snapshots on screen.
• Do not edit or restore configuration from the comparison page.
• Do not treat YAML formatting differences as configuration changes.
• Do not replace the existing snapshot property pages.
• Do not turn the feature into a general instance-drift comparison for files, certificates, deployments, APIs, apps, or other instance state.
• Do not compare instances with different serviceId values in the first release.

Repository Scope

• portal-db for current-snapshot integrity audits, remediation tooling, and the database-enforced current-row invariant
• light-portal for the Java canonical codec and snapshot persistence contract
• config-query for the historical snapshot output/comparison query
• light-config-server for Java runtime values.yml parity
• portal-service for Rust runtime values.yml parity
• portal-view for snapshot-page and InstanceAdmin selection plus the shared output/comparison experience
• deployment/config repositories for packaging and live verification

Why Support More Than Two Snapshots

Two snapshots answer the most common question: “what changed?” Three snapshots also have clear operational uses:

• before, candidate, and current
• dev, QA, and production
• last known good, failed rollout, and repaired rollout

Four columns are still usable in a full-width property matrix and cover a typical staged rollout. Beyond four, value columns become too narrow and users lose the baseline while horizontally scrolling. Larger comparisons are better handled later as a downloadable report or drift dashboard.

The initial limit should therefore be:

values.yml Row Action

Add a row action with tooltip View values.yml. Selecting it requests the snapshot by its explicit hostId and snapshotId and opens a large dialog or right-side drawer containing:

• snapshot timestamp, snapshot id, instance name/id, environment, service id, and whether it is current
• configuration phase, initially fixed to runtime phase R
• property count and SHA-256 digest
• a read-only monospace YAML preview
• Copy and Download buttons
• a link back to Snapshot Properties for source-level inspection

The preview must show the entire output, not only the current table page. While loading, disable Copy and Download. If the snapshot contains no runtime Config properties, show an explicit empty-state message rather than an empty dialog that looks like a failed request.

Use a stable, filesystem-safe download name such as:

values-<instanceName>-<snapshotTs>-<snapshotId>.yml

The downloaded media type should be application/yaml;charset=utf-8. The file should end with one newline.

The download helper must remove its temporary anchor and call URL.revokeObjectURL(...) in a finally block after triggering the download. This follows the cleanup pattern already used by portal-view’s downloadJson helper and prevents repeated exports from retaining Blob URLs in the single-page application.

The snapshot procedure captures both runtime and promote phases, but values.yml is the runtime startup artifact. Phase R is therefore the first release contract. A later phase selector can expose P if operators establish a concrete promote-time verification use case.

Canonical YAML Contract

The output and comparison API must use the same typed conversion rules as the config server:

Canonicalization rules are:

1. Include only config_phase = 'R' and property_type = 'Config'.
2. Form the top-level key as configName.propertyName, matching the current config-server behavior.
3. Sort top-level entries by that complete emitted key, not by property_name alone.
4. Sort keys recursively inside map values.
5. Preserve list order because sequence order can be semantically significant.
6. Preserve the effective source_level as the comment immediately before its property.
7. Use fixed block style, two-space indentation, stable quoting rules, UTF-8, and a single final newline.
8. Reject an invalid stored value for its declared type. Do not quietly coerce it to a string or omit it.
9. Reject duplicate emitted keys instead of letting one overwrite another.
10. Require source_level to be non-blank and single-line before inserting it into a YAML comment.

Map key order does not change YAML meaning, but recursive sorting prevents nested map insertion order from creating noisy diffs. Source comments are useful diagnostics, but a source-comment change alone is not an effective value change.

Move or extract the current Java typed YAML conversion in ServiceConfigurationUtil into a shared canonical serializer that both light-config-server and config-query can call. A suitable home is the shared light-portal utility/domain layer already used by both Java services.

Implement the same contract in Rust, preferably beside ConfigEntry and the snapshot query in portal-service/crates/portal-core, and make portal-service/apps/config-server call it instead of formatting raw values. Because Java and Rust cannot share a runtime class, both codecs must consume the same language-neutral input/output test vectors, including expected UTF-8 YAML bytes and digest.

The fixture corpus has an explicit contract version and a machine-readable manifest containing the SHA-256 of the raw rows and expected YAML. Vendored copies live in the Java and Rust test suites so unit tests remain hermetic. A cross-repository CI job checks the copies from explicitly checked-out revisions for byte equality. Tests must not download fixtures from a mutable branch or a latest raw URL because that would make an otherwise unchanged build depend on network availability and moving remote state.

For a current snapshot, add parity tests proving the portal output and the Java and Rust config-server outputs are byte-for-byte identical. This is the strongest check that the preview represents the artifact a runtime service receives regardless of which supported config server is deployed.

Query API

Add a read action:

lightapi.net/config/getConfigSnapshotValues/0.1.0

It should retain the existing portal.r scope and use a batch-shaped request for both output and comparison:

{
  "hostId": "019...",
  "snapshotIds": ["019...", "019..."],
  "configPhase": "R",
  "include": ["entries"]
}

snapshotIds must contain between one and four unique ids. include may contain entries, yaml, or both. The output dialog requests yaml; the comparison matrix requests entries; the two-pane YAML tab loads yaml only when opened. This avoids sending both a large structured representation and a duplicate YAML string when only one is needed.

The response preserves request order:

{
  "configPhase": "R",
  "snapshots": [
    {
      "snapshotId": "019...",
      "snapshotTs": "2026-07-13T14:30:00Z",
      "instanceId": "019...",
      "instanceName": "light-gateway-dev",
      "environment": "dev",
      "serviceId": "com.networknt.light-gateway-1.0.0",
      "current": false,
      "propertyCount": 2,
      "sha256": "sha256:...",
      "entries": [
        {
          "key": "server.enableHttp",
          "value": true,
          "valueType": "boolean",
          "sourceLevel": "instance"
        },
        {
          "key": "server.httpPort",
          "value": 8080,
          "valueType": "integer",
          "sourceLevel": "default"
        }
      ]
    }
  ]
}

When yaml is requested, each snapshot object also contains the canonical yaml string. The digest is calculated from the exact UTF-8 YAML bytes.

The persistence query should join config_snapshot_t, instance_t, config_snapshot_property_t, and config_t, scope every selected id by cs.host_id = ?, and apply the same InstanceAdmin ownership predicate to instance_t for owner-scoped users. admin and host-admin retain host-wide scope. It must not require current = true. Load all requested metadata and properties in bounded batch queries rather than one query per snapshot.

Reject the whole request if any selected snapshot is missing, belongs to another host, has malformed typed data, or exceeds the configured response limit. A partial comparison can look authoritative while silently omitting a column, so partial success is unsafe here.

Snapshot-Page Selection

Enable row selection on ConfigSnapshot.tsx and add a Compare selected toolbar button. It is disabled until at least two snapshots are selected.

The current getConfigSnapshot response does not contain a property count. Extend it additively with propertyCount, defined as the count of phase R, type Config rows for that snapshot, and a response-level comparisonLimits.maxProperties sourced from the same backend configuration used by getConfigSnapshotValues. Load page counts in one aggregate query, not one count query per row.

The selection state retains propertyCount. Disable Compare selected when the sum across selected snapshots exceeds maxProperties and explain the configured limit in the button tooltip. This check is advisory: the API still enforces both property and serialized-byte limits and remains authoritative. If it returns 413 because the byte limit is exceeded or metadata changed, show an actionable error that suggests selecting fewer snapshots or downloading them individually.

The page uses server-side pagination, so selected snapshot metadata must be stored independently of the currently loaded data array. Selection should survive paging and sorting and should be cleared explicitly by the user or when the host changes. Reject a fifth selection with a short explanation.

The page currently defaults current to true, which often exposes only one snapshot per instance. When compare mode is activated with fewer than two visible candidates, show a Show snapshot history action that removes the current filter. Do not silently change a filter merely because one checkbox was selected.

Same-instance history is the default use case. Cross-instance comparison is also valuable for environment drift, so permit it when all selected snapshots have the same serviceId. Show a Cross-instance comparison banner and keep instance and environment metadata pinned above each column. Reject snapshots with different service ids in the first release; comparing unrelated services mostly produces missing-key noise and is better handled as separate exports.

All selected snapshots must belong to the signed-in host and be visible under the caller’s effective instance ownership scope. This is enforced by the server even though the list query is already scoped. A hidden snapshot id and an unknown snapshot id both return the same unavailable response.

InstanceAdmin Current-Snapshot Entry Point

Add controlled row selection and a Compare current snapshots toolbar action to /app/instance/instanceAdmin. This is a second selector for the shared comparison page, not a separate comparison implementation.

Selection rules are:

• select two to four unique instances
• preserve selection across server-side pagination and sorting
• clear selection when the authenticated host changes
• require a non-empty, identical serviceId across all selected instances
• use only rows visible under the existing InstanceAdmin read/ownership scope
• do not infer config snapshot availability from the instance row’s current field

Reject a fifth instance and mixed-service selections before making a resolver request. Show selected instance names, environments, and a Clear action in the toolbar. Do not silently change the page’s active/current filters when compare mode is enabled.

Current-Snapshot Resolver API

Add a read action:

lightapi.net/config/getCurrentConfigSnapshotsByInstances/0.1.0

Request:

{
  "hostId": "019...",
  "instanceIds": ["019...", "019..."],
  "configPhase": "R"
}

instanceIds must contain two to four unique ids. The handler validates the authenticated host and instance-read scope, then resolves all ids in one bounded query against config_snapshot_t and instance_t. It requires cs.current = true, phase R property counts, and one current config snapshot per selected instance. It must preserve request order and must not issue one query per instance.

Response:

{
  "resolvedAt": "2026-07-13T18:30:00Z",
  "comparisonLimits": {
    "maxProperties": 10000,
    "maxResponseBytes": 5242880
  },
  "snapshots": [
    {
      "instanceId": "019...",
      "instanceName": "light-gateway-dev",
      "serviceId": "com.networknt.light-gateway-1.0.0",
      "environment": "dev",
      "snapshotId": "019...",
      "snapshotTs": "2026-07-13T18:00:00Z",
      "propertyCount": 125
    }
  ]
}

The server revalidates that all resolved snapshots have the same non-empty serviceId; the UI check is only an early usability check. Resolution is all-or-nothing. A missing instance, missing current snapshot, multiple current snapshots, mixed service ids, ownership failure, or property-limit violation must not produce a partial set. Error responses contain ids and counts only, never configuration values.

Stable unavailable/cardinality behavior is:

• 404 CURRENT_CONFIG_SNAPSHOT_UNAVAILABLE when an instance is missing, hidden by owner scope, or has no current snapshot
• 409 CURRENT_CONFIG_SNAPSHOT_CARDINALITY when an instance has multiple current snapshots
• 409 CURRENT_CONFIG_SNAPSHOT_SERVICE_MISMATCH when current snapshot and instance service ids disagree

Before enabling the resolver, add a partial unique index matching the intended identity and access path:

CREATE UNIQUE INDEX uq_config_snapshot_current_instance
ON config_snapshot_t (host_id, instance_id)
WHERE current IS TRUE;

This both supports the resolver query and guarantees at most one current snapshot per host/instance. Deployment must first audit every target database for duplicate current rows and for current snapshot rows whose service_id does not match the authoritative instance_t.service_id. Any current-row violation blocks rollout until an operator reviews and applies an idempotent, recorded remediation. Historical service-id mismatches are reported separately and are not rewritten automatically: historical snapshot metadata is evidence of the captured state and needs an explicitly approved migration if the product decides it is corrupt. Verify the final resolver with EXPLAIN (ANALYZE, BUFFERS) on representative data and require an index-backed plan without per-instance queries.

After successful resolution, navigate to:

/app/config/configSnapshotCompare?snapshotIds=<id1>,<id2>[,<id3>,<id4>]&source=current-instances

The comparison request continues to use explicit snapshot ids. This freezes the result to the snapshots that were current when the user started the comparison and keeps refresh/deep links reproducible. If one becomes non-current before or after the values request, show its normal current badge as false and offer Refresh current snapshots, which resolves the instance ids from the loaded snapshot metadata again. Never silently replace a comparison column while the user is inspecting it.

Comparison Page

Add a route such as:

/app/config/configSnapshotCompare?snapshotIds=<id1>,<id2>[,<id3>,<id4>]

Keeping the ids in the URL makes refresh and task-aware navigation reliable. The host continues to come from authenticated user context and is not trusted from the URL.

The page header contains ordered snapshot cards. Each card shows:

• a short label (A, B, C, or D)
• instance and environment
• snapshot timestamp and id
• description, snapshot type, and current badge
• property count and digest

The snapshot list continues to show the stored userId as the authoritative audit identity. The first release does not resolve it through a user-profile service: display names can change, and profile availability must not affect snapshot inspection. A later enhancement may show a human-readable name alongside the raw userId, but must not replace or obscure the identifier.

The user can choose any selected snapshot as the baseline and reorder the cards. The initial baseline is the oldest selected snapshot, using snapshotTs and then snapshotId as a deterministic tie-breaker.

Effective Property Matrix

The default view is a table built from the union of every emitted key:

Each value cell renders scalars compactly and maps/lists in an expandable formatted block. It also shows valueType and sourceLevel as secondary text. Use typed deep equality after canonicalizing map keys; never compare JSON or YAML strings. Equal-looking values with different types remain changes: for example, integer 1 differs from float 1.0, and string "true" differs from boolean true.

Status rules are:

• Same: the key exists in all snapshots with the same type and value.
• Value changed: at least two selected snapshots have different typed values or value types.
• Missing: the key is absent from at least one selected snapshot.
• Source changed: all effective values match but sourceLevel differs.

For three or four snapshots, the row status describes the selected set and each non-baseline cell additionally receives a same/changed/missing marker relative to the baseline.

Provide filters for All, Changed, Missing, Source changed, and Same, plus a key search. Default to Changed + Missing so the first view focuses on drift. Keep unchanged rows available because users also need to prove that a critical property did not change.

Two-Snapshot YAML Diff

When exactly two snapshots are selected, add a YAML diff tab with synchronized left and right panes. Both panes use canonical YAML, so line differences are meaningful. Support wrapping, next/previous difference, copy, and download.

Use the official CodeMirror MergeView API from @codemirror/merge as the preferred implementation because the application already uses CodeMirror 6 and the YAML language extension. Configure both editors as read-only, set bounded scanLimit and timeout diff options for large or highly divergent files, lazy-load the merge module with the YAML tab, and call destroy() when the tab unmounts. Phase 0 still verifies accessibility, license, bundle impact, and compatibility before freezing the dependency.

Do not show this tab for three or four snapshots. The property matrix is the side-by-side representation for those counts.

Security and Privacy

Snapshot values can contain credentials and other sensitive configuration.

• Enforce both authorization layers: gateway endpoint policy requires portal.r and one of admin, config-admin, or config-viewer; the handler then validates authenticated host access and applies InstanceAdmin owner scope for every requested snapshot or instance. admin and host-admin are the owner-scope bypass roles at the persistence layer.
• Return Cache-Control: no-store through the portal query path.
• Do not write YAML, typed values, or comparison responses to application logs.
• Do not store selected values or YAML in localStorage, sessionStorage, task context, or analytics events.
• Store only snapshot ids in the URL.
• Make Copy and Download explicit user actions.
• Preserve normal portal session expiry and CSRF behavior.

If fine-grained config-read permissions are introduced later, this endpoint must use the same effective permission as the runtime snapshot property view, not a weaker generic page permission.

Performance and Limits

• Cap the request at four snapshots.
• Apply the proposed 10,000-property cap to the total entries across the request, not independently to each snapshot.
• Batch metadata and property loading.
• Return only requested representations through include.
• Enable HTTP compression for JSON/YAML responses.
• Virtualize or paginate the rendered comparison rows in the browser, but build the comparison from the complete server response.
• Abort an in-flight request when the user changes selection or leaves the page.
• Enforce a configurable property-count and serialized-response-size limit and return an explicit error instead of truncating.
• Build the sorted key union, typed deep comparisons, and row classifications in a module Web Worker. Use request generations, ignore stale replies, and terminate the worker when the request changes or the page unmounts.
• Keep React rendering, progress/error state, and the virtualized matrix on the main thread. useTransition may lower the priority of committing a completed result or changing filters, but it does not replace the worker for the comparison calculation itself.

The server must never paginate the data used to calculate a comparison. A rendered table may paginate after the full key union is known.

Implementation Areas

light-portal

• Add a host-scoped persistence method that loads one to four snapshots by explicit id, including metadata and effective Config rows.
• Add the method to PortalDbProvider and PortalDbProviderImpl.
• Extract the canonical typed YAML serializer into a shared utility/domain class.
• Add a host-scoped batch resolver that maps two to four instance ids to exactly one current snapshot each and returns runtime property counts in request order.
• Scope current-snapshot reset/update statements by both host_id and instance_id so the write path matches the database identity.

portal-db

• Add pre-deployment audits for duplicate current rows and current/historical snapshot-to-instance service_id mismatches.
• Add an operator-reviewed, idempotent remediation path for blocking current rows; do not silently choose a duplicate winner or rewrite history.
• Add the partial unique current-snapshot index to baseline DDL and an additive patch, with a deployment choice between concurrent creation and a maintenance window based on table size and patch-runner transaction constraints.
• Add schema and query-plan gates proving duplicate current rows are rejected and the resolver lookup uses the new index.
• Register both additive query actions in the endpoint/access-control catalog, mirroring the established config-query request-access rule and config roles.

light-config-server

• Update the Java config-server path to use the shared Java serializer.
• Run the shared golden test vectors through the Java runtime path.

portal-service

• Add the Rust implementation of the canonical typed YAML contract, preferably in crates/portal-core beside the snapshot row model.
• Update apps/config-server to use the Rust codec instead of interpolating raw property_value strings.
• Run the same golden test vectors through the Rust runtime path.

config-query

• Add GetConfigSnapshotValues and register lightapi.net/config/getConfigSnapshotValues/0.1.0 in spec.yaml.
• Validate snapshot count, duplicates, phase, include, and host ownership.
• Return ordered snapshot objects and stable error responses.
• Add GetCurrentConfigSnapshotsByInstances, reuse the comparison limit model, enforce host/instance-read scope, and return only resolver metadata.

portal-view

• Add a values.yml row action, preview component, copy helper, and YAML download helper.
• Add cross-page row-selection state with a four-snapshot cap.
• Add the Compare selected toolbar action and Show snapshot history helper.
• Add ConfigSnapshotCompare.tsx, its route, task/page registry metadata, and contextual help registration.
• Add reusable typed-value and source-change comparison helpers.
• Add cross-page InstanceAdmin selection, same-service validation, the current-snapshot resolver call, and navigation into the shared comparison route.

No new table or column is required because effective typed values and snapshot metadata are already materialized. The dependent cross-instance workflow does require the partial unique current-snapshot index above; the per-snapshot output/comparison workflow can ship independently of that index.

Testing

Backend

• An explicit historical snapshotId is returned even when current = false.
• A snapshot outside hostId is rejected.
• One to four ids are accepted in request order; zero, five, duplicates, and unknown ids are rejected.
• Only runtime Config rows are emitted.
• Top-level and nested map keys are stable and sorted while list order is preserved.
• String, boolean, integer, float, map, and list values retain their types.
• Integer 1 and float 1.0, and string "true" and boolean true, remain distinct typed values.
• Invalid typed values and duplicate emitted keys fail loudly.
• Source comments are emitted deterministically.
• The current snapshot output is byte-for-byte equal to both supported config-server implementations’ values.yml output.
• Batch loading does not execute one property query per selected snapshot.
• Snapshot list counts include only phase R Config rows and are loaded without an N+1 query.
• The instance resolver returns one ordered current snapshot per selected instance and rejects missing, duplicate-current, mixed-service, cross-host, and unauthorized selections without partial output.
• The database rejects a second current snapshot for the same host/instance while allowing current rows for different host/instance pairs.
• The resolver’s representative EXPLAIN (ANALYZE, BUFFERS) plan uses the partial current-snapshot index and the resolver remains free of N+1 queries.
• Pre-deployment audits classify duplicate current rows and current versus historical service-id mismatches without mutating data by default.

Frontend

• The row action requests the clicked snapshot id, including a historical row.
• Preview loading, empty, error, Copy, and Download states work.
• The download has the expected filename, MIME type, and bytes.
• Selection survives server-side paging and rejects a fifth snapshot.
• Selection proactively blocks a total over the server-provided property cap, while a later authoritative 413 still produces actionable guidance.
• Show snapshot history removes only the current filter.
• Different-service selections are rejected; same-service cross-instance selections show a warning.
• Two, three, and four snapshot matrices use the complete key union.
• Value, missing, and source-only changes are classified correctly.
• Map key order does not create a false change and list order does.
• Equal-looking cross-type values are marked changed and display their types.
• Worst-case permitted comparison computation runs in the worker, ignores stale replies, and terminates on selection change or unmount.
• The YAML diff tab appears only for exactly two snapshots.
• The merge view is read-only, uses bounded diff work, and is destroyed on unmount.
• Every download revokes its Blob URL and removes its temporary anchor on success or failure.
• A comparison URL restores selection after refresh without storing values.
• InstanceAdmin selection survives paging, rejects mixed services and a fifth instance, and never treats the instance current flag as snapshot state.
• Current-instance resolution navigates with exact snapshot ids and an source=current-instances marker.
• A snapshot that becomes non-current remains visible as the resolved artifact; refresh requires an explicit user action.

Acceptance Criteria

• Every row on /app/config/configSnapshot can output a complete, sorted, type-correct runtime values.yml for that exact snapshot.
• Output for a current snapshot matches what both supported config-server implementations serve for the same service and environment.
• Users can select two to four snapshots and compare all effective keys in one view.
• Oversized selections are rejected proactively when counts prove they exceed the property cap, without weakening the API’s count and byte-limit checks.
• Users can select two to four same-service instances in InstanceAdmin and compare the snapshots that were current when comparison started.
• The database enforces at most one current config snapshot per host_id + instance_id, and resolver rollout is blocked by unresolved current-row integrity violations.
• Two selected snapshots can also be inspected as a canonical side-by-side YAML diff.
• The comparison clearly distinguishes value changes, missing keys, and source-only changes.
• Requests cannot read snapshots from another host or outside the caller’s effective instance ownership scope, and no sensitive value is persisted in browser storage.

Rollout

1. Freeze the canonical contract and cross-language golden test vectors.
2. Add the shared Java serializer, equivalent Rust serializer, explicit snapshot query, parity tests, and the getConfigSnapshotValues action.
3. Add the per-row values.yml preview, Copy, and Download actions.
4. Add selection and the two-snapshot property matrix/YAML diff.
5. Enable the already-designed third and fourth matrix columns after the same comparison tests pass with dynamic columns.
6. Audit current-snapshot integrity in each target database, apply reviewed remediation for blocking current rows, deploy the partial unique index, and verify the resolver query plan.
7. Add InstanceAdmin current-snapshot resolution and selection after the shared comparison route, backend values API, and database gates have passed.
8. Apply portal-db/postgres/patch_20260714_02_config_snapshot_compare_endpoints.sql to register both actions in the portal endpoint/access-control catalog, run normal syncConfigInstanceApi for config API LPS1120/1.0.0 on each affected gateway, create and promote a new gateway configuration snapshot, and restart or reload the gateway so its effective endpoint rules contain both actions.
9. Deploy the portal bundle to the actual served/mounted dist and verify its asset hash before acceptance.

The API and selection cap support four snapshots from the beginning, even if the UI rollout enables two first. This avoids an API redesign while still allowing the simpler two-snapshot experience to be validated independently.

Rust Controller Logging

The controller service dashboard already has a logger page for Java runtimes. That page is built around Logback concepts: named loggers, per-logger levels, historical log content, and live streaming through controller-mediated MCP tools. Rust products need a similar operator workflow, but the underlying logging model is different. Rust services use tracing targets and one runtime logging.filter expression instead of mutable Logback logger objects.

This document proposes a Rust-aware logger page for gateway, agent, API, deployer, and workflow runtimes:

• gtw: light-gateway
• agt: light-agent
• api: Rust API services built on light-axum or light-runtime
• dpl: light-deployer
• wf: light-workflow

The goal is to keep the existing controller page entry point while switching the page behavior based on runtime capabilities.

Current State

portal-view has a unified controller logger page at /app/controller/logger. The page receives a runtime instance from the control pane dashboard and uses controller MCP tools:

• get_loggers
• set_loggers
• get_log_content
• start_logs
• stop_logs

Those contracts work for Java services where the runtime can inspect and update Logback logger levels.

Rust services already expose live logging filter control through the light-runtime MCP handler:

• get_logging_filter
• set_logging_filter
• reload_modules with modules: ["runtime/logging"]

The tested config server baseline is:

logging.filter: info,light_pingora::security=debug

This keeps the process at info by default and enables debug only for the gateway security target.

Goals

• Provide one operator page for Rust log filter control, time-based history, and live streaming.
• Reuse the controller-mediated MCP path instead of adding direct browser access to runtime instances.
• Preserve the existing Java logger page behavior.
• Use Rust tracing vocabulary in the UI: target, level, filter expression, and source.
• Let operators build common filters without memorizing module paths.
• Keep an advanced filter input for exact EnvFilter expressions.
• Support time-range log lookup from the running process.
• Support live log streaming through notifications/log.
• Make reset behavior explicit: live filter changes are temporary unless the instance configuration is updated separately.

Non-Goals

• Do not replace Java Logback logger management.
• Do not make the browser connect directly to pods, services, or container runtimes.
• Do not keep historical logs in portal-view or controller memory.
• Do not store full authorization headers, tokens, cookies, request bodies, or other secrets in log files, log responses, or live stream payloads.

Runtime Detection

The logger page should select the Rust experience when either condition is true:

• the selected runtime instance advertises product type gtw, agt, api, dpl, or wf
• the runtime MCP tools/list or controller tool discovery includes get_logging_filter

If detection is uncertain, portal-view can attempt get_logging_filter and fall back to the Java logger page if the response says logging control is not available.

The page should show a capability banner when a selected runtime supports only some features:

Page Layout

Use the current logger page route and high-level structure, but render Rust content when the selected instance is Rust.

Header:

• service label
• runtime instance ID
• service ID
• product type
• address and port
• connection status
• logging capability status

Tabs:

• Filter
• History
• Live Stream

The Java page can keep Config, History, and Live Stream; the Rust page uses Filter instead of Config because the operator edits one tracing filter expression, not a list of Logback logger objects.

Filter Tab

The filter tab controls the active runtime logging.filter.

Controls:

• current effective filter
• filter source, such as values.yml:logging.filter, env:RUST_LOG, or mcp:set_logging_filter
• default level selector
• target rows for common Rust modules
• advanced filter text area
• Apply Live
• Reset From Config

Levels:

• error
• warn
• info
• debug
• trace
• off

Recommended default level is info.

Example generated filter:

info,light_pingora::security=debug

Apply flow:

operator changes target rows
  -> portal-view builds EnvFilter expression
  -> controller calls runtime set_logging_filter
  -> runtime validates and applies the filter immediately
  -> portal-view refreshes get_logging_filter

Reset flow:

operator clicks Reset From Config
  -> controller calls reload_modules with runtime/logging
  -> runtime reloads logging.filter from current resolved values
  -> portal-view refreshes get_logging_filter

Baseline changes are handled outside this page. If an operator wants the filter to survive restart or reset, they should update the selected instance configuration, for example:

logging.filter: info,light_pingora::security=debug

Target Presets

The advanced filter must accept any valid Rust tracing target. The module picker should be backed by reference data so new targets can be added without a portal-view deployment.

Portal-view should load the dropdown from:

/r/data?name=logging_target

Recommended reference table mapping:

The simplest page can load all active targets from /r/data?name=logging_target and group them client-side by product. If product-specific filtering is needed later, add a reference relation such as logging-target-product that links each target to common, gtw, agt, api, dpl, or wf. Operators can still type a custom target if the target is not present in the reference table.

Suggested seed data:

Common targets:

Gateway targets:

Agent targets:

API targets:

Deployer targets:

Workflow targets:

The UI can also learn targets from returned history and live rows. Any target seen in logs can become a temporary suggestion for that browser session, but the authoritative dropdown source is the logging_target reference table.

History Tab

The history tab fetches logs from the running application for a time range.

Controls:

• presets: last 5, 10, 30, and 60 minutes
• required start time
• optional end time
• minimum level
• optional target filter
• text search
• result limit

Request:

{
  "runtimeInstanceId": "019...",
  "startTime": "2026-06-17T21:30:00Z",
  "endTime": "2026-06-17T21:45:00Z",
  "loggerLevel": "debug",
  "loggerName": "light_pingora::security",
  "limit": 1000
}

For compatibility, loggerName maps to the Rust target and loggerLevel maps to the minimum tracing level. The controller can keep the existing get_log_content tool name.

Recommended normalized row shape:

{
  "timestamp": "2026-06-17T21:37:43.147463Z",
  "level": "DEBUG",
  "logger": "light_pingora::security",
  "target": "light_pingora::security",
  "message": "JWT validation failed after JWKS refresh: InvalidSignature",
  "fields": {
    "error": "InvalidSignature"
  }
}

The response can preserve the current grouped shape for compatibility:

{
  "content": {
    "light_pingora::security": {
      "logs": [
        {
          "timestamp": "2026-06-17T21:37:43.147463Z",
          "level": "DEBUG",
          "message": "JWT validation failed after JWKS refresh: InvalidSignature"
        }
      ]
    }
  }
}

Portal-view should flatten the grouped response into rows, as the current Java page already does.

History source selection:

1. If a JSON log file is configured, parse that file first. This should be the preferred source because the same file can be collected by Splunk or another logging system.
2. If no log file is configured, use Kubernetes pod logs or container logs when the controller/runtime environment can access them.
3. If neither source is available, return an explicit unsupported response.

The browser must not read Kubernetes or container logs directly. The controller or runtime-side tool should own that platform access and return the normalized row shape above.

When reading a JSON log file, the reader should filter by timestamp, level, target, and text search. If the file format is line-oriented JSON, each line should contain at least timestamp, level, target, and message.

Live Stream Tab

The live stream tab starts and stops log streaming for the selected runtime instance.

Controls:

• full filter expression
• start
• stop
• clear
• auto-scroll toggle
• bounded client buffer
• stream status

Request:

{
  "runtimeInstanceId": "019...",
  "filter": "info,light_pingora::security=debug"
}

start_logs should accept the full Rust filter expression because this is the syntax Rust operators already use. For backward compatibility, the controller can still accept level and loggerName, then translate them into a filter expression.

The stream filter controls which events are sent to that stream subscription. It must not change the process-wide logging.filter; process-wide changes still go through set_logging_filter. Because tracing filters can suppress events before stream filtering sees them, the UI should warn when the stream filter is more verbose than the current active runtime filter.

Notification:

{
  "method": "notifications/log",
  "params": {
    "runtimeInstanceId": "019...",
    "timestamp": "2026-06-17T21:37:43.147463Z",
    "level": "DEBUG",
    "logger": "light_pingora::security",
    "target": "light_pingora::security",
    "message": "JWT validation failed after JWKS refresh: InvalidSignature"
  }
}

The portal-view live buffer should remain bounded. The current 1000-row FIFO buffer is a good default.

Each browser/controller session must have its own stream subscription. Starting a stream from one operator must not replace another operator’s stream for the same runtime instance.

Runtime Implementation

Add shared Rust logging support to light-runtime, not separately in every product.

Recommended components:

• LoggingControl: existing active EnvFilter control.
• JsonLogWriter: optional line-oriented JSON file writer for services that need historical lookup or Splunk ingestion.
• LogFileReader: reads and filters configured JSON log files.
• PlatformLogProvider: controller-side or runtime-side abstraction for Kubernetes pod logs and container logs when no log file is configured.
• LogStreamHub: per-client subscriptions for live streaming.
• LogRecord: normalized timestamp, level, target, message, fields, and optional span/correlation fields.

Recommended runtime MCP tools:

The JSON log file should be configurable:

logging.file.enabled: true
logging.file.path: /var/log/light-gateway/app.log
logging.file.format: json
logging.file.maxBytes: 104857600
logging.file.maxFiles: 10
logging.stream.maxSubscribers: 20

Defaults should be conservative. If no JSON log file and no platform log provider are available, get_log_content should return a clear unsupported response instead of an empty success that looks like there were no logs.

Controller Changes

The controller should expose Rust logging tools through the same callTool path used by the existing logger page.

Add or pass through these tool names:

• get_logging_filter
• set_logging_filter
• reload_modules
• get_log_content
• start_logs
• stop_logs

For Rust runtimes, get_loggers and set_loggers are not the primary control surface. The UI should use get_logging_filter and set_logging_filter instead. The controller may keep get_loggers and set_loggers for Java compatibility.

The controller should route notifications/log back to the portal-view websocket with the originating runtimeInstanceId so the page can ignore logs from other selected services.

For history, the controller should resolve sources in this order:

1. configured JSON log file
2. Kubernetes or container log provider
3. unsupported response with a clear reason

Portal-View Implementation

Recommended structure:

• keep /app/controller/logger as the route
• keep the existing Logger component as the shell
• split Java and Rust behavior into child panels:
  • JavaLoggerPanel
  • RustLoggerPanel
• reuse the current history and live table rendering where possible
• add a Rust filter builder for logging.filter

Rust filter builder state:

type RustFilterDraft = {
  defaultLevel: "error" | "warn" | "info" | "debug" | "trace" | "off";
  targets: Array<{ target: string; level: string }>;
  advanced: string;
  mode: "builder" | "advanced";
};

In builder mode, portal-view generates the expression:

<defaultLevel>,<target>=<level>,<target>=<level>

In advanced mode, portal-view sends the text exactly as entered and lets the runtime validate it.

The page should show a warning when the current source is mcp:set_logging_filter, because that indicates a live override that can be lost on restart or reset by reloading runtime/logging.

Baseline Configuration

Live debug changes should call set_logging_filter; they should not update config server by default.

To persist a baseline filter, the operator should use the instance configuration page and update:

logging.filter: info,light_pingora::security=debug

After saving the instance configuration, the config update flow can call:

{
  "name": "reload_modules",
  "arguments": {
    "modules": ["runtime/logging"]
  }
}

This makes the saved config the active baseline. Alternatively, the operator can return to the logger page and use Reset From Config to reload only runtime/logging.

The Rust logger page can link to the selected instance configuration, but it should not write baseline config itself.

Security And Safety

• Gate filter changes and log access behind the same controller permissions as the Java logger page.
• Treat logs as sensitive operational data.
• Do not render raw ANSI escape sequences as HTML.
• Truncate very large messages and expose an expand action.
• Mask obvious token and secret fields in JSON log output, history responses, and live stream payloads.
• Rate-limit live streams per runtime instance and per controller client.
• Show a warning before enabling broad trace filters.

Rollout Plan

1. Add controller pass-through for get_logging_filter and set_logging_filter.
2. Add RustLoggerPanel in portal-view with filter control only.
3. Add JSON file logging and a get_log_content reader for Rust services.
4. Add Kubernetes/container log fallback when no log file is configured.
5. Add Rust start_logs and stop_logs backed by per-client stream subscriptions.
6. Seed the logging_target reference data and load dropdown options from /r/data?name=logging_target.
7. Enable product-specific target presets for gtw, agt, api, dpl, and wf.

Resolved Decisions

• Historical logs are not kept in memory. Use a configured JSON log file first; if there is no file, fall back to Kubernetes or container logs when they are available.
• start_logs accepts a full filter expression. Compatibility fields such as level and loggerName can be translated by the controller.
• The module dropdown is backed by the logging_target reference table exposed through /r/data?name=logging_target.
• The logger page does not save a baseline. Baseline changes belong in instance configuration.

Human Task UI

ask is the workflow task type that pauses execution for human input. The runtime can now create task_asst_t and worklist_t rows when an ask task waits, so portal-view needs a generic human-task interface that lets an assigned user open the task, provide the requested answer, and resume the workflow.

This document proposes the portal UI and service contracts for that interface.

Current State

The workflow engine persists waiting ask tasks in task_info_t. The ask configuration is stored in task_info_t.task_output.ask, and the workflow runtime context remains on process_info_t.context_data.

The assignment layer is separate:

• worklist_t represents a user/category worklist.
• task_asst_t represents a concrete task assignment.
• Role assignment is resolved by the workflow runtime into one task assignment per active user in the role.

The Worklist page can show assigned tasks, but it does not yet provide a generic input screen for the user to approve or enter data.

Goals

• Provide one generic page for all human-input workflow tasks.
• Render the input controls from the ask task definition, not from a workflow-specific page.
• Let users open tasks from the Worklist page.
• Keep assignment, claim, completion, and authorization checks on the service side.
• Support role-assigned tasks where multiple users may receive the same work.
• Resume the workflow through the existing completeTask command.
• Keep the UI useful for approval tasks first while leaving room for richer object-input tasks.

Non-Goals

• Do not create a custom approval page for each workflow.
• Do not make every workflow task human-actionable; only ask tasks use this interface.
• Do not expose raw database rows directly to the page.
• Do not overload the engine locked field for human claims; that field is already used by the workflow executor as a worker lease.
• Do not replace the existing Worklist administration page in the first phase.

User Flow

The primary flow is:

Worklist
  -> open assigned task
  -> Human Task detail
  -> render prompt and input controls from ask metadata
  -> submit answer
  -> completeTask command
  -> workflow executor resumes the process

For a simple approval workflow, the user sees the prompt and two action buttons derived from the ask options. For structured input, the same page renders a schema-driven form.

The runtime flow for a role-assigned ask task is:

1. The workflow executor creates one task_asst_t row per assignee and keeps the parent task_info_t row waiting for input.
2. The assigned user opens the row from Worklist.
3. getHumanTask loads the assignment, task state, workflow metadata, and process context into one stable page payload.
4. The user submits an answer through completeTask.
5. completeTask validates assignment ownership, locks the parent task row, records the result, and deactivates or cancels sibling assignments in the same transaction.
6. The workflow executor observes the completed ask task and resumes the process with the submitted answer.

Route Design

Add a human task detail route:

/app/workflow/HumanTask

The route should accept taskAsstId and task context through query parameters or router state:

/app/workflow/HumanTask?taskAsstId=...&taskId=...

The Worklist page should route to this detail page for actionable task rows. Worklist administration actions such as create, update, and delete worklists should remain separate from human task completion.

If a dedicated inbox page is needed later, add:

/app/workflow/HumanTasks

That page can list only actionable assigned tasks, while the existing Worklist page can remain the administrative view of worklist definitions.

Data Model Decisions

task_info_t remains the canonical workflow engine task state. Its locked column must stay reserved for executor leasing. Human task claims must not set task_info_t.locked = 'Y', because that would make the executor treat the row as worker-owned runtime work.

Useful existing task_info_t fields for the human task page are:

• status_code: parent task state. Waiting ask tasks should be open for input; completed ask tasks should be read-only.
• deadline_ts: optional due or expiry timestamp to show in the UI.
• locking_user and locking_role: possible global claim metadata if claim is implemented, but not a replacement for assignment-level authorization.
• task_output: source of the ask metadata.
• result_code: submitted answer envelope after completion.

task_asst_t remains the assignment layer. The current active flag and unassigned_reason can hide completed assignments from Worklist, but they are too loose to represent claim, release, expiry, and reporting states cleanly. Add an explicit assignment status early in development so the query and command contracts are built on the final assignment state model:

ALTER TABLE task_asst_t
  ADD COLUMN status_code VARCHAR(16) NOT NULL DEFAULT 'ASSIGNED',
  ADD COLUMN claimed_by VARCHAR(126),
  ADD COLUMN claimed_ts TIMESTAMP WITH TIME ZONE,
  ADD COLUMN claim_expires_ts TIMESTAMP WITH TIME ZONE;

Recommended assignment statuses:

Keep active as a fast visibility/backward-compatibility flag. Use status_code for business state and audit/reporting semantics.

Query Contract

The UI should not assemble a human task by calling several generic table queries. Add a normalized query action such as getHumanTask.

Request:

{
  "hostId": "...",
  "taskAsstId": "..."
}

Response:

{
  "hostId": "...",
  "taskAsstId": "...",
  "taskId": "...",
  "processId": "...",
  "wfInstanceId": "...",
  "wfTaskId": "requestApproval",
  "assignedTs": "...",
  "assigneeId": "...",
  "assignmentStatusCode": "ASSIGNED",
  "claimedBy": null,
  "claimedTs": null,
  "deadlineTs": "2026-05-23T14:30:00Z",
  "categoryCode": "approval",
  "reasonCode": "human-approval",
  "taskStatusCode": "W",
  "workflow": {
    "wfDefId": "...",
    "namespace": "light-portal",
    "name": "human-approval",
    "version": "1.0.0"
  },
  "ask": {
    "prompt": "Review the workflow request and choose a decision.",
    "mode": "approval",
    "options": [
      {
        "label": "Approve",
        "value": "APPROVED",
        "description": "Continue the request."
      },
      {
        "label": "Reject",
        "value": "REJECTED",
        "description": "Stop the request."
      }
    ],
    "required": true,
    "allowComment": true,
    "contextKeys": ["requestId", "summary"]
  },
  "contextSummary": {
    "requestId": "REQ-001",
    "summary": "..."
  },
  "context": {
    "requestId": "REQ-001",
    "summary": "..."
  }
}

The service should read from task_asst_t, task_info_t, process_info_t, and wf_definition_t, then return a stable task-detail view. The UI should treat this response as the source of truth.

The query should return a curated contextSummary when the ask metadata defines contextKeys. It may also include the raw context object for administrator troubleshooting or for workflows that have not yet declared a curated context shape. The default user view should prefer contextSummary.

For a list page, add getHumanTaskList later. It should return only active assignments for the current user unless the caller has an administrative permission.

Input Rendering

The page renders controls from ask.mode, ask.options, and ask.schema.

If ask.mode is missing, default to text. If approval has no options, the UI may render default APPROVED and REJECTED actions.

Comments should be configurable per ask task. The recommended metadata is:

{
  "allowComment": true,
  "commentRequired": false
}

approval and confirm should default to allowing comments. Other modes can opt in when the workflow author wants users to explain the submitted value.

Answer Shape

Use a consistent answer envelope for completeTask.

{
  "value": "APPROVED",
  "comment": "Looks good.",
  "submittedAt": "2026-05-22T14:30:00Z"
}

For object input, value is the submitted object:

{
  "value": {
    "approvedLimit": 5000,
    "expirationDate": "2026-06-30"
  },
  "comment": "Approved with a reduced limit.",
  "submittedAt": "2026-05-22T14:30:00Z"
}

The workflow receives this object as the ask task output. A workflow that needs only the selected value can export .output.value; a workflow that wants the full audit envelope can export .output.

Completion Command

The detail page submits through completeTask:

{
  "host": "lightapi.net",
  "service": "workflow",
  "action": "completeTask",
  "version": "0.1.0",
  "data": {
    "hostId": "...",
    "taskId": "...",
    "taskAsstId": "...",
    "statusCode": "C",
    "completedTs": "2026-05-22T14:30:00Z",
    "response": {
      "value": "APPROVED",
      "comment": "Looks good.",
      "submittedAt": "2026-05-22T14:30:00Z"
    }
  }
}

The command should verify that:

• the assignment exists and is active
• the assignment status allows submission
• the current user is the assignee or has an administrative permission
• the task is an ask task
• the task is still waiting for input
• the submitted answer matches ask.mode, ask.options, and ask.schema

The browser may send taskAsstId, taskId, and the answer, but it must not be trusted to identify the completing user. The command service should derive the user id and roles from the authenticated token. A client-supplied completedUser value should be ignored for normal human-task completion.

Completion must be atomic. In one database transaction:

1. Load the task_asst_t row and verify it belongs to the current user, unless the caller has an explicit administrative override permission.
2. Lock the parent task_info_t row, for example with SELECT ... FOR UPDATE.
3. Reject the command if the parent task is already completed or no longer waiting for input.
4. Validate the answer against the ask metadata and, for object mode, the JSON schema.
5. Update task_info_t with status C, completed_ts, completed_user, and the answer envelope in result_code.
6. Mark the selected assignment COMPLETED and inactive.
7. Mark sibling active assignments for the same task_id as CANCELLED, inactive, and unassigned_reason = 'completed_by_other_user'.

If another user completes the same parent task first, return a stale-task conflict response, preferably HTTP 409, and leave the duplicate submission unapplied.

Claim And Concurrency

Role assignment can create several active assignments for the same task_id. The first user-input page should use optimistic completion with a server-side final check: only the first valid completion succeeds, and later submissions receive a stale-task conflict response. This proves the core flow before adding the operational complexity of explicit claim/release commands.

For a better user experience, add an optional claimHumanTask command.

Recommended claim behavior:

• claim records the current user on the human-task assignment path with task_asst_t.status_code = 'CLAIMED', claimed_by, and claimed_ts
• claim does not set task_info_t.locked = 'Y'
• claim expires after a short timeout or can be released
• completion still performs the final status check

The engine locked column should remain reserved for executor leasing. Human claims should use either assignment-specific fields added later or locking_user/locking_role without changing the executor lease flag.

When claim is enabled for role-assigned tasks, sibling assignment rows should be visible as claimed or unavailable instead of letting users submit stale answers. Live refresh should use the existing portal notification channel if one is available. If workflow tasks need their own lightweight channel later, prefer server-sent events before adding a separate websocket service.

Assignment Cleanup

When a human task is completed:

• the selected assignment should no longer appear as actionable
• sibling active assignments for the same task_id should also disappear
• the task completion result should remain on task_info_t

With the current table shape, the minimal implementation can deactivate active task_asst_t rows for the task and set unassigned_reason to completed or completed_by_other_user. A later schema iteration can add explicit assignment status fields if the UI needs richer assignment history.

With the recommended status column, cleanup should use structured states:

• selected assignment: status_code = 'COMPLETED', active = false, unassigned_reason = 'completed'
• sibling assignments: status_code = 'CANCELLED', active = false, unassigned_reason = 'completed_by_other_user'

Authorization

Normal users should only query and complete assignments where task_asst_t.assignee_id matches their user id. Administrative users may view all assignments for the host if the workflow task endpoints allow it.

The browser should send taskAsstId, but the service should not trust the browser to identify the assignee. It should resolve the current user from the authenticated token and compare it to the assignment row.

Administrative completion on behalf of another user should require a distinct permission, not just the ability to query workflow tasks. The command should record both the authenticated actor and the effective completed user if override support is added.

Recommended authorization model:

• normal completion requires the endpoint write scope and task_asst_t.assignee_id = authenticated user id
• administrative override requires workflow.task.override
• a host or portal administrator, such as the configured portal.admin, may be treated as satisfying the override permission if that is the established portal authorization convention

Use a broad scope such as workflow.write for access to the write endpoint if the service defines workflow-specific scopes. If the current service only has a portal-level write scope, keep the OAuth scope broad and enforce workflow.task.override as the fine-grained application permission.

Page Layout

The detail page should be compact and task-oriented:

• header with workflow name, task name, status, and due date if deadlineTs is present
• assignment summary with assignee and category
• prompt panel
• context panel with selected workflow/process fields
• input area rendered from ask metadata
• sticky submit actions for long forms
• error or stale-task state

The context panel should show enough data for the user to decide, but it should not dump the full context_data object by default. The first phase can show common fields and provide a collapsible raw context view for administrators.

Timeout handling should be visible as read-only metadata as soon as task_info_t.deadline_ts is available. The UI can show due date or expiry status without implying that automatic runtime timeout processing has already been implemented.

Error States

The page should handle these states explicitly:

• assignment not found
• assignment no longer active
• task already completed
• task is not an ask task
• ask metadata missing or invalid
• validation failed
• submit conflict because another user completed the task first
• workflow resume failed after completion

The submit conflict case should take the user back to the worklist after showing that the task is no longer available.

Implementation Phases

Phase 1:

• Add the task_asst_t.status_code migration before building the query and command handlers.
• Add getHumanTask.
• Add /app/workflow/HumanTask.
• Link actionable Worklist task rows to the detail page.
• Render approval, choice, multiChoice, confirm, and text.
• Submit through completeTask.
• Validate assignment ownership and ask metadata in the command layer.
• Complete the parent task and assignment cleanup in one transaction.
• Return stale-task conflicts for duplicate submissions.
• Hide completed and sibling-cancelled assignments from the worklist.

Phase 2:

• Add schema-driven object input.
• Add JSON schema validation on the command side.
• Add curated context metadata such as ask.contextKeys.

Phase 3:

• Add optional claimHumanTask and releaseHumanTask.
• Add claim expiry handling.
• Add a dedicated human task inbox.
• Add assignment history and richer audit display.
• Add live Worklist refresh for claim/completion events through the existing portal notification channel, with server-sent events as the fallback.
• Add file input if workflow use cases require it.

Resolved Questions

• task_asst_t should gain explicit assignment status fields. active remains useful for filtering but should not be the only state model.
• The human task query should return curated context when workflow metadata defines it, with raw context available for administrative troubleshooting.
• Comments should be configurable. Approval and confirm modes should default to allowing comments.
• Timeout metadata should be visible as read-only UI state before automatic timeout processing is implemented.
• Administrative override should use the fine-grained permission workflow.task.override, with portal.admin as the broad administrator path if the portal authorization layer already uses it.
• Claim/release should remain Phase 3. Phase 1 should rely on optimistic completion and atomic duplicate-submit rejection.
• Live Worklist refresh should use the existing portal notification channel first. If there is no reusable channel, use server-sent events before adding a dedicated websocket service.

User Filter

As more portal users manage their own APIs, clients, instances, schedules, and configuration records, giving every operator a broad admin role becomes too coarse. A broad admin can see and modify records created by other admins on the same host. This document proposes an incremental owner-scoped filtering model for portal-view.

The first step is a UI-side filter based on the user recorded on each row, such as update_user. This is not a complete security boundary. The same rule must eventually be enforced in the query and command services with fine-grained authorization from the rule engine. The UI implementation is still useful because it improves day-to-day user experience and gives us a concrete policy shape to move into the service layer.

Problem

Portal admin pages were originally designed for a small set of trusted operators. Many tables expose all host-scoped records once the user can access the admin page.

That model creates problems as adoption grows:

• application owners need to manage their own APIs, clients, and instances
• broad admin roles expose unrelated records from other teams
• users can accidentally edit or delete records owned by another user or team
• creating one role per page, such as api-admin or instance-admin, still does not solve row ownership
• service-layer fine-grained authorization is not available everywhere yet

The immediate need is to let users use admin-like pages while limiting the rows they see and act on.

Current Experiment

Schedule.tsx is the first experimental page. The idea is:

• users can access the schedule admin surface
• normal users only see schedules where updateUser matches their user id
• global admins or schedule admins can still see all schedules
• the updateUser column can be hidden for normal users
• create/update/delete actions are available only on the visible set

One implementation detail matters: ownership filters must be added before the request payload serializes the filters array.

const apiFilters = [];

if (ownedOnly && userId) {
  apiFilters.push({ id: "updateUser", value: userId });
}

const cmdData = {
  filters: JSON.stringify(apiFilters),
};

Adding the filter after cmdData.filters is built will not send it to the backend.

Design Goals

• Allow regular users to manage records they created or updated.
• Avoid giving every self-service user broad all-record admin visibility.
• Keep the admin table implementation familiar and incremental.
• Centralize the owner filter logic instead of duplicating it page by page.
• Make the UI rule match the future service-layer rule as closely as possible.
• Preserve host scoping and existing role-based page visibility.
• Avoid presenting UI-side filtering as a security boundary.

Non-Goals

• Do not claim UI filtering is sufficient authorization.
• Do not replace service-layer rule-engine enforcement.
• Do not solve full team ownership in the first UI-only pass.
• Do not migrate every admin page in one large change.
• Do not overload update_user as the permanent ownership model if a better owner field exists or can be added.

Ownership Model

There are several possible ownership signals. They should be treated in this order of preference.

update_user is acceptable for the first UI experiment because many tables already have it. However, it has an important semantic problem: ownership moves to whoever last updated the row. If Alice creates an API and Bob updates it, Bob becomes the owner under an update_user rule.

The long-term model should add explicit owner fields where needed:

owner_user_id
owner_position_id

owner_group_id is intentionally deferred. Groups are still useful for flat team membership, but position ownership fits the portal authorization model better when access should follow the organization hierarchy. owner_org_id is also deferred because normal portal records are already scoped by host_id, and host_t links back to org_t through the host domain. Add organization-level ownership only if a future cross-host/global ownership use case requires it.

Do not add created_by and updated_by as authorization fields in Phase 4. The existing update_user and update_ts columns remain the last-updater audit trail. If creator audit becomes important, add create_user and create_ts as audit fields later, not as substitutes for stable ownership.

Until explicit owner columns exist, each page should declare which field is used for interim UI owner filtering.

Role Model

Use one page per entity type, but separate page visibility from row scope.

Do not give every user account access to every admin page. Only pages that are safe for self-service ownership should be exposed to user, and each of those pages must apply the owner filter and action guards.

The admin role can be repurposed as the global all-record role once the sidebar stops using it as a broad menu marker. Role checks must use exact role tokens. A role such as schedule-admin must not match admin through substring checks.

Access Modes

The UI should support three access modes.

Owner-Scoped Admin

This is the default self-service mode. The user can open admin pages, but rows are filtered to records they own.

Example:

roles: user
scope: owned
filter: updateUser = current user id

All-Scope Admin

This is for operators who can see and manage every record on the current host.

Example roles:

admin
schedule-admin

The default all-scope role is admin. Page-specific roles such as schedule-admin can opt a user into all-record visibility for one area. Do not use platform-admin as a global all-scope role because the portal already has a Platform Admin page for deployment platform management.

Read-Only or Support View

Some users may need to see records without modifying them. This can be added later with separate flags:

canReadAll = true
canWriteOwned = true
canWriteAll = false

Proposed UI Architecture

Add a small ownership-scope helper used by admin pages.

Example shape:

type OwnershipScopeOptions = {
  roles?: string | null;
  userId?: string | null;
  ownerField: string;
  allScopeRoles?: string[];
};

type OwnershipScope = {
  ownedOnly: boolean;
  ownerFilter: { id: string; value: string } | null;
  canWriteAll: boolean;
};

Example usage:

import {
  applyOwnershipFilter,
  defaultAllScopeRoles,
  ownershipScope,
} from "../utils/ownershipScope";

const ownership = ownershipScope({
  roles,
  userId,
  ownerField: "updateUser",
  allScopeRoles: [...defaultAllScopeRoles, "schedule-admin"],
});

const apiFilters = applyOwnershipFilter(columnFiltersWithoutActive, ownership);

This helper should live near other portal navigation/task utilities or in a small access utility module, for example:

src/utils/ownershipScope.ts

or:

src/tasks/accessScope.ts

The helper should not call the backend. It only computes the UI filter and UI capabilities from the current user state.

Sidebar Behavior

The sidebar should not use admin as a marker on every admin menu link. That made the whole Administration group disappear for normal users and prevented owner-scoped self-service pages from being reachable.

Recommended behavior:

• admin users see every Administration link.
• non-admin users see only Administration links explicitly marked with user or a matching entity role, such as role: "user schedule-admin".
• only add user to a link after that page has owner-scoped filtering and action guards.
• remove role: "admin" from individual menu links.
• use exact role-token matching instead of string includes, so schedule-admin does not accidentally grant admin.

At the Phase 3 rollout point, the following Administration links are safe to expose to user because the pages apply the shared owner-scope helper and action guards:

• API Admin
• API Detail
• OAuth Auth Client and Client Token
• App Admin
• Instance Admin, Runtime Instance, and instance relationship pages
• Schedule Admin
• Workflow Definition

Configuration, platform admin, user/role admin, workflow process/task/audit pages, and lower-volume metadata pages should remain admin-only until they have the same owner-scope treatment or a separate support/read-only policy.

Admin Page Behavior

For an owner-scoped user:

• add the owner filter before the query payload is serialized
• hide the owner column if it does not add useful information
• show a small scope label such as “My records”
• keep create actions available
• allow update/delete only for rows matching the ownership rule
• preserve normal table sorting, pagination, and global filter behavior

For an all-scope admin:

• do not add the owner filter
• show a scope label such as “All host records”
• show the owner/update columns
• allow existing admin actions

For a user without enough context:

• if userId is missing, do not run an owner-scoped query
• show a clear message that user context is required
• avoid falling back to all-record visibility

Action-Level Guard

List filtering is not enough for a good UI. Row actions should also check the same scope.

Example:

const canUpdateRow =
  ownership.canWriteAll ||
  row.original.updateUser === userId;

For rows the user cannot modify:

• hide destructive actions, or
• disable them with a tooltip explaining the scope

Even after service-layer authorization is implemented, the UI should keep these guards so users understand why an action is unavailable.

Phase 4 Ownership Columns

For high-value entity tables, add canonical owner columns directly on the entity row:

owner_user_id UUID NULL
owner_position_id VARCHAR(128) NULL

Recommended constraints where the table has host_id:

FOREIGN KEY (host_id, owner_user_id)
  REFERENCES user_host_t(host_id, user_id)

FOREIGN KEY (host_id, owner_position_id)
  REFERENCES position_t(host_id, position_id)

Both owner columns should be nullable during migration. New records should get owner_user_id from the authenticated user on the service side by default. Do not trust a browser-submitted owner user id unless the caller has permission to assign ownership.

owner_position_id should be optional on create. The UI can show a host position dropdown populated from the user’s allowed positions. If the user has exactly one effective position and the page is configured for position ownership, the UI can default to that position. If the user has multiple positions, require an explicit choice when position ownership is desired.

For portal forms, the optional position owner field should be exposed as ownerPositionId and backed by the existing position label dynaselect query. The form action uses the position/getPositionLabel endpoint, which is backed by the queryPositionLabel persistence method and returns the id/label pairs needed by the select control.

Do not expose ownerUserId as a normal create/update form field. The command path must derive owner_user_id from the authenticated user in the event context. If an owner-transfer use case is needed later, implement it as a separate command with explicit authorization and audit behavior.

Normal update forms may update owner_position_id when the page allows the caller to choose or clear the owning position. update_user changes on every update and remains audit metadata. owner_user_id should not change on normal update; it changes only through an explicit owner-transfer action restricted to the current owner, admin, or the relevant entity-admin role.

Existing rows should be migrated conservatively:

• if update_user can be resolved to a user in the host, it can be used as an initial owner_user_id
• leave owner_position_id null unless there is a reliable source for the owning position
• rows with no owner columns populated should be treated as unassigned legacy rows, visible only to all-scope admins until an owner is assigned

Service-Layer Target

The UI filter is an interim step. The durable solution belongs in the query and command services.

The service layer should eventually:

• derive user id, roles, host id, and scopes from JWT claims
• ignore client-supplied owner filters as an authorization source
• inject owner predicates into query handlers based on the authenticated user
• reject update/delete commands when the user does not own the row and lacks all-scope permission
• use rule-engine policies for exceptions and domain-specific ownership

Once service-side owner enforcement is implemented, the UI should no longer be the source of authorization predicates. The service should inject the ownership predicate from authenticated user context and rule-engine decisions.

The UI should still keep owner-aware behavior for usability:

• show “My records” or “Admin View” scope labels
• hide or show owner columns based on the user’s scope
• disable update/delete actions that the current user cannot take
• optionally send a simple view hint such as scope=owned or scope=all

The service must treat any UI-supplied scope or owner filter as a hint only. It must ignore, override, or reject filters that would expand the caller’s authorized scope.

For owner-scoped users, the service-side predicate should be an OR condition:

owner_user_id = current_user_id
OR owner_position_id IN current_user_effective_positions

For all-scope admins, such as admin or the relevant entity-admin role, the service should omit this owner predicate and return all rows within the normal host scope.

The UI and backend should share the same policy concepts:

host scope
entity type
owner field
owned-only permission
all-record permission
read vs write capability

Position hierarchy must be resolved by the service layer or rule engine. A JWT claim such as pos=ai-engineer only grants exact-position access unless the service expands it to effective positions from position_t and user_position_t. If hierarchy is enabled, the effective position set should include inherited positions according to the existing position inheritance rules.

Rows with owner_position_id IS NULL are not position-owned. A user can still see the row if owner_user_id matches their user id. Rows where both owner_user_id and owner_position_id are null are unassigned legacy rows and should not be visible to normal owner-scoped users by default.

Rule Engine Direction

The rule engine can express policies such as:

user can read API when api.owner_user_id == user.user_id
user can update API when api.owner_user_id == user.user_id
admin can read all APIs on host
admin can update all APIs on host
api-admin can read all APIs on host
api-admin can update all APIs on host
support can read all APIs but cannot update

For tables that do not yet have explicit ownership fields, the policy can temporarily map ownership to update_user.

Rollout Plan

Phase 1: Fix Schedule Experiment

• Fix filter ordering so updateUser is included in the request.
• Use roles plus user id to decide owner-scoped vs all-scope mode.
• Add action-level guards for update/delete.
• Keep the current route behavior unchanged.

Phase 2: Add Reusable UI Helper

• Create a shared ownership-scope helper.
• Add unit-level coverage if the repo has a practical test pattern.
• Document default all-scope roles.
• Keep owner field configurable per page.

Phase 3: Apply To High-Value Admin Pages

Start with pages where users commonly manage their own records:

• API admin
• API detail/version admin
• OAuth clients
• client apps
• instances
• instance API links
• schedules
• workflow definitions

Then expand to lower-volume metadata pages.

Current implementation status:

• src/utils/ownershipScope.ts centralizes exact role matching, owner-scope calculation, owner filter injection, and owner-column hiding.
• Sidebar access now exposes only scoped links to user or matching entity-admin roles, while exact admin continues to see all Administration links.
• API pages use admin and api-admin for all-record scope, with user limited by updateUser.
• OAuth client pages use admin and oauth-client-admin for all-record scope, with user limited by updateUser.
• Client app pages use admin and app-admin for all-record scope, with user limited by updateUser.
• Instance pages use admin and instance-admin for all-record scope, with user limited by updateUser.
• Schedule pages use admin and schedule-admin for all-record scope, with user limited by updateUser.
• Workflow Definition uses admin and workflow-admin for all-record scope, with user limited by updateUser.
• Task/page search registries use exact role-token checks so schedule-admin or another entity-admin role does not accidentally match global admin, while exact admin still has global visibility.

Deferred from this phase:

• Workflow Process, Task, Worklist, Work, Audit, and Trace remain admin-only until their ownership rules are defined and implemented.
• Configuration and platform pages remain admin-only because their ownership model is not yet defined.
• User and role administration remain admin-only because exposing them to self-service users would require a separate delegated-administration model.

Phase 4: Add Explicit Ownership Fields

Where update_user is too weak, add proper owner fields through the database and services.

Candidate fields:

owner_user_id
owner_position_id

Apply these first to the high-value tables that already have owner-scoped admin pages. Keep the fields nullable during migration, default owner_user_id from the authenticated user on create, and make owner transfer explicit.

Current implementation status:

• portal-db adds nullable owner_user_id and owner_position_id columns to the high-value portal tables used by the owner-scoped admin pages.
• The migration backfills owner_user_id from update_user only when update_user is already a UUID. Non-UUID audit values remain unassigned instead of blocking the migration.
• A database insert trigger defaults owner_user_id from update_user for new rows when the command path writes the authenticated user id into update_user.
• Query projections for the scoped UI pages now return ownerUserId and ownerPositionId, and UUID filtering recognizes ownerUserId.
• portal-view now uses ownerUserId for ownership checks on action controls. The UI no longer sends an owner filter for service-enforced pages because service-side scope must include both direct user ownership and position ownership.
• Owner-aware create/update forms expose optional ownerPositionId with a host-scoped position dynaselect backed by queryPositionLabel.
• Command schemas allow optional ownerPositionId for the owner-aware create and update commands. They do not accept ownerUserId; owner_user_id comes from the authenticated event user.
• light-portal persistence writes owner_user_id from the event user on create and writes owner_position_id from ownerPositionId on create/update.
• Schedule query is the first service-enforced owner-scope path. Non all-scope users are filtered by owner_user_id = current_user_id OR owner_position_id IN effective positions based on authenticated audit context.

Remaining rollout work:

• Add explicit owner-transfer commands instead of changing ownership through normal update forms.

Phase 5: Enforce In Services

• Add query-side owner predicates.
• Add command-side ownership checks.
• Move policy decisions into rule-engine configuration.
• Keep the UI filters as usability hints, not authorization.

Current implementation status:

• Query-side owner predicates are implemented for Schedule, API, API Version, App, OAuth Client, Client Token, Instance, Instance API, Instance API Path Prefix, Instance App, Instance App API, Runtime Instance, and Workflow Definition.
• Query handlers derive scope from the authenticated audit attachment. Users with the global admin role or the entity-specific all-scope role bypass the owner predicate; other users are scoped by user id or effective positions.
• The UI keeps owner-aware action guards, but it does not send the owner filter as a request filter for service-enforced pages. That keeps position-owned rows visible when the service grants access by owner_position_id.
• The db-provider keeps backward-compatible query methods and adds owner-aware overloads so query services can roll forward independently.

Remaining service rollout work:

• Add command-side ownership checks before update/delete actions.
• Add explicit owner-transfer commands and audit events.
• Move the all-scope role and position hierarchy decisions from Java guards into rule-engine policy once the service-side rule context is ready.

Future Improvement: Entity Access Grants

Do not introduce a generic ownership table in Phase 4. It adds query joins, pagination complexity, and weaker referential integrity before we have a clear sharing use case.

A generic table can be added later for secondary grants, sharing, and delegated administration. It should supplement the canonical owner columns rather than replace them.

Possible future shape:

entity_access_t
  host_id
  entity_type
  entity_id
  principal_type   -- user, position, group, role
  principal_id
  access_level     -- owner, maintainer, viewer

Use this only when we need use cases such as:

• share one API with another position or group
• give support read-only access to a selected set of records
• delegate maintenance without transferring the canonical owner
• manage record-specific exceptions from an Access Admin page

Risks And Mitigations

Recommendation

Use owner-scoped filtering as the first UI step, but centralize it immediately. Do not copy the Schedule.tsx logic into every page by hand.

The recommended path is:

1. fix the schedule filter ordering
2. introduce a reusable ownership-scope helper
3. apply it to the most common self-service admin pages
4. add explicit owner fields where update_user is not good enough
5. enforce the same rules in query and command services through the rule engine

This gives users a safer admin experience now while creating a clear migration path to real fine-grained authorization.

Contextual Help Links

portal-view has many pages, generated forms, task flows, and admin tables. Even with the task-oriented navigation work, users still need page-specific and form-specific help when they are making a decision or filling a field. This document proposes a contextual help-link model for pages and forms.

Problem

Users often need help at the exact point where they are working:

• what this page is for
• when to use this form
• what required fields mean
• which optional fields matter
• what permissions or ownership rules apply
• what happens after submit
• how this page fits into a larger task

Today, help is usually outside the UI context. Users must know where to look, which document applies, and which page or form name maps to the screen in front of them.

Design Goals

• Add a clear help entry point to every major page and generated form.
• Keep help content close to the product documentation source of truth.
• Avoid bloating the portal-view application bundle with documentation.
• Allow documentation-only updates without rebuilding portal-view.
• Make help links declarative so page, form, and task metadata can drive them.
• Keep link identifiers stable even if routes or component names change.
• Support future documentation search, related topics, and task-specific help.
• Preserve the ability to run the app locally with a configurable docs base URL.

Non-Goals

• Do not build a full documentation authoring system inside portal-view.
• Do not duplicate long user guides in component source files.
• Do not block a page or form rollout because full documentation is missing.
• Do not use contextual help as a replacement for better labels, validation, or field-level error messages.

Documentation Location Decision

The help content should live in light-portal-doc. portal-view should store only metadata that points to the relevant help page.

Recommended split:

light-portal-doc
  src/help/portal-view/
    pages/
    forms/
    tasks/
    concepts/

portal-view
  page registry, task registry, and form metadata with help ids or help paths

Why light-portal-doc

Pros:

• Keeps user-facing documentation in the documentation repo.
• Allows documentation changes without rebuilding or redeploying portal-view.
• Avoids increasing the app bundle with markdown content.
• Supports documentation search, navigation, publishing, and review workflows.
• Allows the same help content to be linked from support tickets, onboarding, release notes, and external docs.
• Fits the existing pattern where portal-view design docs already live in light-portal-doc.

Cons:

• Requires stable published URLs.
• Requires a configurable docs base URL for local and deployed environments.
• Can drift from UI behavior unless we add link validation and ownership rules.

Why Not portal-view/docs

Pros:

• Easy to review UI and docs in one PR.
• Help content can be tightly coupled to the component version.
• Local development does not need a separate docs deployment.

Cons:

• Documentation-only changes require app rebuilds and deployments.
• Large markdown content can bloat the frontend repo and build context.
• It is harder to provide a proper documentation navigation/search experience.
• It encourages implementation notes and user help to mix in the same repo.

Recommendation: use light-portal-doc for content and keep portal-view limited to stable link metadata.

Help Content Structure

Create a user-facing help tree separate from design docs:

src/help/portal-view/
  pages/
    api-admin.md
    api-detail.md
    instance-admin.md
    schedule-admin.md
  forms/
    create-api.md
    update-api.md
    create-client.md
    update-instance.md
  tasks/
    mcp-onboard-api.md
    register-standalone-mcp-server.md
  concepts/
    ownership-and-positions.md
    hosts-and-user-hosts.md
    api-versioning.md

Use page-level help for screen orientation and form-level help for submission semantics. Use concept help for reusable explanations that should not be copied into many page/form documents.

URL Strategy

Help URLs should be stable and human-readable.

Recommended public URL shape:

/help/portal-view/pages/api-admin
/help/portal-view/forms/create-api
/help/portal-view/tasks/mcp-onboard-api
/help/portal-view/concepts/ownership-and-positions

Do not make the public URL depend on React route internals or component names. If a route changes from /app/api to another route later, the help URL should not need to change.

portal-view should build the absolute link from a runtime config value:

PORTAL_DOC_BASE_URL=https://doc.lightapi.net

or for Vite:

VITE_PORTAL_DOC_BASE_URL=https://doc.lightapi.net

Local development can point to a local docs server:

VITE_PORTAL_DOC_BASE_URL=http://localhost:3000

Metadata Contract

Use a stable help id or help path in the app metadata. A help path is more direct and easier to validate.

Page registry example:

{
  id: "api-admin",
  title: "API Admin",
  route: "/app/apis",
  helpPath: "/help/portal-view/pages/api-admin",
}

Task registry example:

{
  id: "mcp-onboard-api",
  title: "Onboard API to MCP Gateway",
  helpPath: "/help/portal-view/tasks/mcp-onboard-api",
}

Form metadata example:

{
  "formId": "createApi",
  "helpPath": "/help/portal-view/forms/create-api",
  "actions": []
}

If we need indirection later, we can change to helpId and resolve it through a small registry:

{
  helpId: "forms.create-api"
}

Start with helpPath because it is simple, transparent, and works well with static documentation.

Portal UI Behavior

Each page and generated form should have a small help action in a predictable location.

Recommended behavior:

• open help in a new browser tab
• use an external-link icon or help icon with an accessible label
• keep the help action near the page title or form title
• if a form is opened inside a task shell, prefer form-specific help first and show task help as a secondary link
• if no specific help exists yet, fall back to the nearest page or concept help

Example resolution order for a form opened from a task:

1. form helpPath
2. current task helpPath
3. current page helpPath
4. generic portal help landing page

Do not render a broken link. If a help path is missing, hide the action or show the fallback help link.

Generated Forms

Generated forms should support a top-level helpPath field in Forms.json. The renderer can read it and show a help action in the form header.

For example:

{
  "formId": "createSchedule",
  "helpPath": "/help/portal-view/forms/create-schedule",
  "schema": {},
  "form": []
}

Field-level help can be added later, but it should not be the first step. Many field descriptions can stay in the JSON schema title/description. Use field-level help only for fields where a short description is not enough, such as security, ownership, deployment, or advanced configuration fields.

Possible future field shape:

{
  "key": "ownerPositionId",
  "helpPath": "/help/portal-view/concepts/ownership-and-positions"
}

Task-Aware Help

The task-oriented navigation layer should support task help separately from page or form help. A user working on the same form may need different context depending on the task.

Example:

• createApi opened from “Register a new API” links to create API form help.
• createApi opened from “Onboard API to MCP Gateway” can also link to MCP onboarding task help.

The UI should pass task context through existing task URL parameters and layout state, then render both links when useful:

Help: Create API
Related: Onboard API to MCP Gateway

Authoring Guidelines

Each page help document should include:

• what the page is used for
• who can access it
• what records are visible
• common actions
• links to related forms and tasks

Each form help document should include:

• when to use the form
• what happens after submit
• required fields
• important optional fields
• ownership and permission behavior
• validation or troubleshooting notes

Keep help content user-facing. Do not put implementation details, class names, or database internals in the main help body unless they are truly needed for an operator.

Validation

To prevent link drift, add a lightweight validation step once the first help docs exist.

Validation should check:

• every helpPath in portal-view points to a markdown source in light-portal-doc
• every high-value page has page help
• every high-value form has form help
• no help path uses a route-specific or component-specific unstable name

This can start as a script in light-portal-doc or a shared CI check that accepts both repo paths.

Rollout Plan

Phase 1: Documentation Structure

• Create src/help/portal-view/pages.
• Create src/help/portal-view/forms.
• Create src/help/portal-view/tasks.
• Create src/help/portal-view/concepts.
• Add placeholder help pages for the high-value admin pages and forms.

Phase 2: App Metadata

• Add optional helpPath to pageRegistry.ts.
• Add optional helpPath to taskRegistry.ts.
• Add optional top-level helpPath to generated form metadata.
• Add a docs base URL runtime config.

Phase 3: UI Components

• Add a reusable help-link component.
• Render page help near page titles.
• Render form help in the generated form header.
• Render task help in the task navigation shell.
• Add fallback behavior when a specific help link is missing.

Phase 4: Coverage And Validation

• Add help paths for all self-service owner-scoped admin pages.
• Add help paths for all high-value create/update forms.
• Add a validation script for help path coverage and broken links.
• Add missing docs over time as pages move into the task-oriented model.

Initial Scope

Start with the pages and forms most likely to be used by self-service users:

• API Admin and API Detail
• create/update API
• create/update API Version
• App Admin
• create/update App
• OAuth Client and Client Token
• create/update Client
• create Client Token
• Instance Admin and relationship pages
• create/update Instance
• create Instance API
• create/update Instance API Path Prefix
• create Instance App
• create Instance App API
• Schedule Admin
• create/update Schedule
• Workflow Definition
• create/update Workflow Definition

Then expand to admin-only pages after their ownership and access model is clear.

MVP Decisions

Use these decisions for the first implementation.

Missing Help Links

Do not hide the help action when a specific page, form, or task help path is missing. Fall back to the generic portal-view help landing page:

/help/portal-view/index

This keeps the UI consistent. A missing specific help page should degrade to general help instead of making the help affordance disappear.

Help Presentation

Open help in a new browser tab for the MVP. Do not build an embedded markdown viewer, side drawer, or iframe-based documentation panel in the first version.

This keeps portal-view small and avoids adding documentation rendering, iframe, routing, and panel-state complexity to the app. A side panel can be revisited later if users need in-page help while editing long forms.

JSON Schema Descriptions

Do not auto-generate full form help pages from JSON schema descriptions. Schema titles and descriptions are best used for inline labels, helper text, or field-level tooltips.

Form-level help should explain why the form exists, when to use it, what happens after submit, and how the form fits into a larger workflow. It should not simply repeat field types and required flags.

Documentation Versioning

Use latest documentation URLs for the MVP. Do not introduce release-versioned help URLs in the first implementation.

The portal will likely support both cloud SaaS deployments and enterprise on-premise deployments. SaaS users normally interact with the latest deployed portal, but enterprise customers may run older portal versions for a longer period. Versioned docs are therefore a good future requirement, but they should not block the first help-link rollout.

Keep helpPath values relative and version-neutral:

/help/portal-view/forms/create-api

Then versioning can be introduced later by changing only the configured docs base URL:

PORTAL_DOC_BASE_URL=https://doc.lightapi.net/v2.0

This keeps the app metadata stable while allowing SaaS to use latest docs and on-premise builds to point at version-specific documentation.

Future Enhancements

In-Page Help Drawer

Add an optional in-page help drawer after the helpPath metadata is stable and the first new-tab implementation has proven useful.

The drawer should be opt-in, not the default for every form. Long or complex configuration forms can declare:

{
  "helpPath": "/help/portal-view/forms/update-instance",
  "inPageHelp": true
}

When enabled, the UI can render a right-side drawer that displays the help document through an iframe or a lightweight markdown renderer. This avoids constant tab switching for complex forms while keeping the MVP simple.

Field-Level Help Paths

Add field-level help paths sparingly for complex fields and architectural concepts. Standard fields should continue to use JSON schema titles, descriptions, helper text, or tooltips.

Example future field metadata:

{
  "key": "ownerPositionId",
  "helpPath": "/help/portal-view/concepts/ownership-and-positions"
}

The UI can render a small help icon next to the field label when a field-level helpPath exists. Good candidates include ownership, security, OAuth token exchange, deployment target, transport configuration, and workflow definition fields.

Versioned Documentation

Add release-versioned documentation when multiple portal versions must be supported at the same time, especially for on-premise enterprise deployments.

The relative helpPath values should remain unchanged. The deployment or build configuration should select the versioned docs base URL:

SaaS/latest:
PORTAL_DOC_BASE_URL=https://doc.lightapi.net

On-premise v2.0:
PORTAL_DOC_BASE_URL=https://doc.lightapi.net/v2.0

This gives cloud deployments a simple latest-docs experience and gives enterprise deployments a path to version-matched help without changing portal-view metadata.

Recommendation

Store user-facing help content in light-portal-doc and add declarative helpPath metadata in portal-view. This keeps documentation maintainable and publishable while allowing every page, form, and task to provide context-aware help from the UI.

Event Processing Notifications

Portal commands are event driven. After a command is submitted, one or more CloudEvents are written to event_store_t and outbox_message_t. The hybrid-query event consumer later processes the outbox rows and updates the projection tables used by portal-view.

The notification page in the user profile is intended to show the user the recent processing result for those events. Today the table and read path exist, but notification_t is not populated consistently, so the page cannot provide meaningful status.

Current State

The command path already writes events through the common command handler:

1. The command handler validates and enriches the request.
2. It builds one or more CloudEvents.
3. It inserts those events into event_store_t and outbox_message_t.
4. The command returns before the query-side projection has necessarily run.

The query side can run through either event-processing pipeline, selected by configuration:

• Pg-notify pipeline: DbEventConsumerStartupHook polls outbox_message_t, uses the table’s gapless c_offset, groups rows by transaction_id, and writes failed transactions to the database dead_letter_queue.
• Kafka pipeline: a connector publishes rows from outbox_message_t to Kafka. PortalEventConsumerStartupHook consumes those records, groups records by the command-side transaction_id, and produces failed transactions to the Kafka DLQ topic when DLQ is enabled.

Both pipelines eventually call PortalDbProvider.handleEvent(conn, event). handleEvent dispatches the event to the projection method for that event type. Because both pipelines process the same outbox-backed events, they should share the same user-facing notification status model.

The notification pieces are partially present:

• notification_t exists in portal-db.
• NotificationDataPersistenceImpl can query notification_t.
• NotificationServiceImpl can insert a notification row.
• user-query exposes getNotification.
• portal-view has a notification table page.

The current gap is that notification rows are not created at the central event processing boundary.

There is also a separate UI error in MailMenu: it calls getPrivateMessage, whose handler currently returns an empty response. That explains the browser error Unexpected end of JSON input, but it is separate from the notification status design.

Goals

• Show the current user the latest event processing results in the profile notification page.
• Record both successful and failed projection processing.
• Preserve event processing correctness even if notification insertion fails.
• Keep notification creation centralized instead of adding calls to every projection method.
• Support commands that emit multiple events.
• Make the read API filter by host and user by default.
• Keep enough diagnostic data to debug failed projections.
• Keep notification writes idempotent so event replay is safe.

Non-Goals

• Do not replace event_store_t, outbox_message_t, or dead_letter_queue.
• Do not use notifications as the source of truth for projection state.
• Do not build a real-time push channel in the first phase.
• Do not add notification logic manually to every projection method.
• Do not expose other users’ processing history to non-admin users.

Recommended Design

Use notification_t as an operational projection-status table. The command side creates PENDING rows at the central event publication boundary, and the hybrid-query event consumer updates those rows with the processing result.

The primary processing-result write point should be the centralized outbox consumer path, around the call to PortalDbProvider.handleEvent(conn, event).

Recommended lifecycle:

command handler
  -> event_store_t
  -> outbox_message_t
  -> notification_t PENDING row
  -> response to caller

hybrid-query consumer
  -> read outbox_message_t
  -> handleEvent(conn, event)
  -> projection table write
  -> notification_t status row

For command-side publication, insert or update one notification row for each CloudEvent with status PENDING in the same transaction that writes event_store_t and outbox_message_t. Leave event_partition and event_offset null for this first insert, because the consumer has not observed the event position yet.

For successful projection processing, update the notification row for the CloudEvent to status SUCCEEDED and populate event_partition and event_offset from the active processor’s outbox position.

For failed projection processing, insert or update one notification row for each failed CloudEvent with status FAILED or DLQ, and store the exception message. Populate event_partition and event_offset when the processor has that information.

Status Model

Use one explicit status field. Do not keep is_processed; this feature is being implemented for the first time, and a boolean cannot distinguish pending, success, retry, DLQ, and skipped outcomes.

Recommended statuses:

The UI should show the status labels, not the underlying event pipeline. The same status meanings apply to both pg-notify and Kafka processing.

Schema

The existing table is close, but it is too small for operational status and has nonce as INTEGER while event tables use BIGINT.

Recommended table shape:

CREATE TABLE notification_t (
    id                  UUID NOT NULL,
    host_id             UUID NOT NULL,
    user_id             UUID NOT NULL,
    nonce               BIGINT NOT NULL,
    event_class         VARCHAR(255) NOT NULL,
    event_json          TEXT NOT NULL,
    event_ts            TIMESTAMP WITH TIME ZONE NULL,
    process_ts          TIMESTAMP WITH TIME ZONE NOT NULL,
    status              VARCHAR(16) NOT NULL,
    error               VARCHAR(2048) NULL,
    aggregate_id        VARCHAR(255) NULL,
    aggregate_type      VARCHAR(255) NULL,
    aggregate_version   BIGINT NULL,
    event_partition     INTEGER NULL,
    event_offset        BIGINT NULL,
    transaction_id      UUID NULL,
    read_ts             TIMESTAMP WITH TIME ZONE NULL,
    PRIMARY KEY (host_id, id),
    FOREIGN KEY (host_id) REFERENCES host_t(host_id) ON DELETE CASCADE
);

user_id is intentionally not a foreign key to user_t. PENDING rows are inserted on the command side before projection tables are updated, so enforcing that projection FK would break commands such as user creation before the projection catches up.

Recommended indexes:

CREATE INDEX idx_notification_user_process_ts
    ON notification_t (host_id, user_id, process_ts DESC);

CREATE INDEX idx_notification_status_process_ts
    ON notification_t (host_id, status, process_ts DESC);

CREATE INDEX idx_notification_transaction
    ON notification_t (host_id, transaction_id);

CREATE INDEX idx_notification_event_position
    ON notification_t (host_id, event_partition, event_offset);

CREATE INDEX idx_notification_unread_failure
    ON notification_t (host_id, user_id, process_ts DESC)
    WHERE read_ts IS NULL AND status IN ('FAILED', 'DLQ');

event_partition and event_offset are intentionally generic processing position fields. They are useful for operator diagnostics, but the UI should not label them as pg-notify or Kafka details. In the pg-notify processor, event_partition is the configured logical consumer partition and event_offset is outbox_message_t.c_offset. In the Kafka processor, event_partition and event_offset are the consumed Kafka record partition and offset.

Both columns are nullable. PENDING rows should leave them empty at initial insert time. They are filled later by the pg-notify or Kafka processor when the processing result changes the row to SUCCEEDED, FAILED, DLQ, or SKIPPED.

transaction_id remains a UUID because it is generated by the command side and used by both event processors.

Do not store pipeline name, source topic/channel name, or DLQ destination in notification_t. Those are implementation details of the configured event pipeline. Operators can use service configuration and logs when they need pipeline-specific diagnostics.

For existing installations, ship this as a patch:

ALTER TABLE notification_t ALTER COLUMN nonce TYPE BIGINT;
ALTER TABLE notification_t ADD COLUMN IF NOT EXISTS status VARCHAR(16);
ALTER TABLE notification_t ADD COLUMN IF NOT EXISTS event_ts TIMESTAMP WITH TIME ZONE;
ALTER TABLE notification_t ADD COLUMN IF NOT EXISTS aggregate_id VARCHAR(255);
ALTER TABLE notification_t ADD COLUMN IF NOT EXISTS aggregate_type VARCHAR(255);
ALTER TABLE notification_t ADD COLUMN IF NOT EXISTS aggregate_version BIGINT;
ALTER TABLE notification_t ADD COLUMN IF NOT EXISTS event_partition INTEGER;
ALTER TABLE notification_t ADD COLUMN IF NOT EXISTS event_offset BIGINT;
ALTER TABLE notification_t ADD COLUMN IF NOT EXISTS transaction_id UUID;
ALTER TABLE notification_t ADD COLUMN IF NOT EXISTS read_ts TIMESTAMP WITH TIME ZONE;

ALTER TABLE notification_t DROP CONSTRAINT IF EXISTS notification_t_user_id_fkey;
ALTER TABLE notification_t DROP COLUMN IF EXISTS is_processed;
ALTER TABLE notification_t ALTER COLUMN status SET NOT NULL;

CREATE INDEX IF NOT EXISTS idx_notification_unread_failure
    ON notification_t (host_id, user_id, process_ts DESC)
    WHERE read_ts IS NULL AND status IN ('FAILED', 'DLQ');

Write Path

Notification writes need an explicit transaction policy. A single rule cannot cover every status:

• Failure and DLQ notifications must be durable even when projection writes are rolled back.
• Success notifications must not claim success until the projection write has committed.
• Notification write failures should not break projection processing.

Use a REQUIRES_NEW style helper for notification writes that must survive a projection rollback. In plain JDBC, this means opening a separate connection with its own commit/rollback boundary.

For success rows, there are two safe options:

1. Commit the projection transaction first, then write SUCCEEDED in a separate notification transaction.
2. Write SUCCEEDED inside the projection transaction, but wrap it in a savepoint and treat notification insert failure as non-fatal.

The first option is the recommended default because notification failures cannot roll back projection updates. The tradeoff is a small window where projection has committed but the success notification is missing. That is acceptable because event_store_t remains the source of truth and success notifications are user feedback, not projection correctness.

Recommended service methods:

void recordPending(Map<String, Object> event, UUID transactionId);

void recordSuccess(Map<String, Object> event, EventMetadata metadata);

void recordFailure(Map<String, Object> event, EventMetadata metadata, String error, String status);

recordPending should participate in the command-side transaction that writes event_store_t and outbox_message_t. It may store transaction_id, because that value is generated by the command side, but it must leave event_partition and event_offset null. recordSuccess and recordFailure should use the event-processing transaction policy described below.

EventMetadata should carry only pipeline-neutral data that is not inside the CloudEvent map:

• eventPartition: the active processor’s partition value. For pg-notify this is the configured logical consumer partition; for Kafka this is the consumed Kafka record partition.
• eventOffset: the active processor’s offset value. For pg-notify this is outbox_message_t.c_offset; for Kafka this is the consumed Kafka record offset.
• transactionId: the command-side transaction UUID used by both processors.

Both consumers should build this metadata before calling handleEvent, so the failure path still has offset and transaction context after the projection transaction is rolled back.

Use an idempotent upsert:

INSERT INTO notification_t (...)
VALUES (...)
ON CONFLICT (host_id, id) DO UPDATE SET
    process_ts = EXCLUDED.process_ts,
    status = EXCLUDED.status,
    error = EXCLUDED.error,
    event_partition = EXCLUDED.event_partition,
    event_offset = EXCLUDED.event_offset,
    transaction_id = EXCLUDED.transaction_id;

This makes replay and fallback processing safe.

Success Handling

In the normal batch path:

begin projection transaction
for each event from the active pipeline:
  parse CloudEvent
  handleEvent(conn, event)
commit projection transaction

for each successfully committed event:
  recordSuccess(event, metadata) in separate notification transaction

Do not write SUCCEEDED before the projection transaction commits unless it is part of the same transaction. If it is written in the same transaction, a projection rollback must roll back the success row too.

The implementation can keep an in-memory list of successfully applied events while processing the batch. After commit, loop through that list and upsert the success notifications. If a success notification write fails, log it and continue; do not retry the projection.

Failure Handling

Failure rows must be written outside the failed projection transaction.

In fallback mode, processing is retried per transaction. For a failed transaction:

begin projection transaction
savepoint projection_attempt
  process transaction events
on exception:
  rollback to projection_attempt or rollback projection transaction
  write failed events to database DLQ or Kafka DLQ topic
  recordFailure(event, metadata, error, "DLQ") in separate notification transaction

For pg-notify, the DLQ destination is the database dead_letter_queue table. For Kafka, the DLQ destination is the configured Kafka DLQ topic. The failure notification can be committed with the database DLQ transaction for pg-notify, or in a separate notification transaction immediately after the Kafka DLQ produce request is accepted. The key requirement is that it must not be part of the projection work that is being rolled back.

If the database connection enters an unrecoverable error state, close it and open a fresh connection for the DLQ and failure notification writes.

If the payload cannot be parsed as a CloudEvent, the consumer may not know the CloudEvent id or event type. In that case, the DLQ remains the primary failure record. If the consumer metadata still has host, user, partition, offset, and transaction id, the consumer can create a diagnostic notification with a generated id, but this should be treated as a best-effort operational row.

Pending Handling

PENDING is part of phase one. Add pending rows at the central command-side publication boundary that writes event_store_t and outbox_message_t.

The pending notification should be written in the same command-side transaction as the event-store and outbox rows. If the command rolls back, the pending notification must roll back too. Do not add pending writes to individual command handlers.

At this stage, the notification row should contain command-known fields only: CloudEvent id, host id, user id, nonce, event class, event JSON, event timestamp, and transaction id. The processor-owned event_partition and event_offset fields remain null until event processing updates the row.

Read API

Keep getNotification as the main query endpoint, but tighten its contract.

Recommended request fields:

{
  "hostId": "uuid",
  "userId": "uuid",
  "offset": 0,
  "limit": 25,
  "status": "SUCCEEDED",
  "eventClass": "ClientCreatedEvent",
  "nonce": "123",
  "fromTs": "2026-05-08T00:00:00Z",
  "toTs": "2026-05-08T23:59:59Z",
  "error": "duplicate key"
}

Recommended response:

{
  "total": 1,
  "notifications": [
    {
      "id": "uuid",
      "hostId": "uuid",
      "userId": "uuid",
      "nonce": 123,
      "eventClass": "ClientCreatedEvent",
      "status": "SUCCEEDED",
      "processTs": "2026-05-08T16:12:00Z",
      "aggregateId": "host|client",
      "aggregateType": "Client",
      "aggregateVersion": 2,
      "transactionId": "uuid",
      "eventPartition": 0,
      "eventOffset": 1001,
      "error": null,
      "eventJson": "{...}"
    }
  ]
}

eventPartition and eventOffset are intentionally displayed as generic position fields regardless of which event pipeline is configured. The main list can hide them by default and show them in the detail view.

userId is a filter on getNotification, not a separate endpoint contract. The profile notification page should always send the logged-in user’s userId. The admin notification page can omit userId to request host-wide results, or pass a specific userId to narrow the host-wide view to one user.

Authorization rules:

• Normal users can query only their own token user_id within the selected hostId. If the request omits userId, the backend should apply the token user_id; if the request supplies another userId, the backend should reject it or override it with the token user_id.
• Admin users can query all users for the host by omitting userId, or filter to a specific user by providing userId.
• The backend should enforce this using token claims, not only UI filters.

Portal View

The profile notification page should become a processing-status view.

Recommended columns:

• Time
• Status
• Event
• Aggregate
• Nonce
• Error
• Details

Recommended default filters:

• hostId from the selected host.
• userId from the logged-in user.
• No default status filter.
• Most recent first.
• Last 25 rows.

The UI should display concise summaries and keep full eventJson behind an expandable detail row or dialog.

Show all events associated with the user, including successful, failed, and derived events. Derived events should be visible as their own rows instead of being collapsed under the original command transaction.

The current processFlag filter should be replaced by status. No is_processed compatibility mapping is needed because this feature has not yet started populating notification_t.

The header MailMenu should not call getPrivateMessage unless that handler is restored. For notification status, add a small notification badge endpoint or reuse getNotification with limit = 5.

The header badge should count only unread failure notifications, such as FAILED and DLQ, and display the count in red when the count is greater than zero.

In the list, FAILED and DLQ status badges should also use red styling.

Phase 2 adds two narrow user-query RPCs:

• getUnreadNotificationCount: returns unread FAILED and DLQ notifications for the current hostId and userId.
• markFailureNotificationsRead: sets read_ts on unread FAILED and DLQ notifications for the current hostId and userId.

The header uses the count endpoint for its badge and marks failures read when the user opens the notification menu. The notification page also marks failures read when it is opened.

Admin Notification Page

Phase 3 should add a separate admin notification page instead of overloading the profile notification page. The recommended location is:

• Route: /app/event/notifications
• Menu: Administration -> Event Admin -> Notifications

This page should reuse the same notification table and getNotification read API, but with admin defaults:

• hostId from the selected host.
• No default userId filter, so admins see host-wide results.
• Default status filter for FAILED and DLQ, with an option to show all statuses.
• Filters for userId, eventClass, status, transactionId, aggregateId, processing position, time range, and error text.
• No unread badge behavior and no call to markFailureNotificationsRead.

The page should clearly identify itself as an admin view, such as “Admin View: Host Notifications”. Host-wide access must still be enforced by the backend using token roles.

Operational Cleanup

Notifications are operational history. They should not grow forever.

Recommended retention:

• Keep successful notifications for 30 to 90 days.
• Keep failed and DLQ notifications longer, such as 180 days.
• Allow host-level configuration later if needed.

Cleanup should be implemented as a generic operational cleanup process, not as notification-specific UI or command-handler logic. The first cleanup target is notification_t, but the same framework should also support other operational tables such as message_t for private messages.

Recommended implementation:

• Add an OperationalCleanupStartupHook on the query side.
• Run cleanup on a fixed interval, such as daily, with config-driven enablement, interval, batch size, and per-target retention days.
• Use a single cleanup coordinator that owns multiple cleanup targets. Each target defines its table, timestamp column, status/type conditions if needed, retention duration, and batch delete SQL.
• Use a database lock, such as a PostgreSQL advisory lock or a dedicated cleanup lock row, so only one service instance performs cleanup at a time.
• Delete in bounded batches to avoid long table locks and large transactions.
• Use a separate database connection and transaction for cleanup work.
• Log cleanup failures and continue service startup; cleanup failure must not block query APIs or event processing.

Do not use schedule_t directly for this cleanup. That scheduler is business workflow infrastructure that emits events into event_store_t and outbox_message_t. Operational cleanup is local maintenance and should stay out of the event-processing path.

Example notification cleanup:

WITH doomed AS (
    SELECT host_id, id
    FROM notification_t
    WHERE (status IN ('SUCCEEDED', 'SKIPPED') AND process_ts < ?)
       OR (status IN ('FAILED', 'DLQ') AND process_ts < ?)
    ORDER BY process_ts
    LIMIT ?
)
DELETE FROM notification_t n
USING doomed d
WHERE n.host_id = d.host_id
  AND n.id = d.id;

Private-message cleanup can be another target using message_t.send_time:

WITH doomed AS (
    SELECT host_id, from_id, nonce
    FROM message_t
    WHERE send_time < ?
    ORDER BY send_time
    LIMIT ?
)
DELETE FROM message_t m
USING doomed d
WHERE m.host_id = d.host_id
  AND m.from_id = d.from_id
  AND m.nonce = d.nonce;

Recommended default cleanup targets:

Do not delete recent PENDING notifications. Old PENDING rows should be treated as an operational signal first because they may indicate that the event consumer is stopped or lagging. If a hard cap is needed later, make it a separate, longer retention policy.

Snapshot and Promotion

notification_t should be treated as an operational table, not a promoted projection table.

It should be excluded from global snapshot export and conversion alongside event_store_t, outbox_message_t, dead_letter_queue, log_counter, and consumer_offsets.

Rollout Plan

Phase 1: Make Notifications Useful

• Add status and diagnostic columns to notification_t.
• Add pipeline-neutral event_partition, event_offset, and transaction_id metadata.
• Change NotificationService to support separate notification transactions.
• Insert PENDING rows at the central command-side outbox publication boundary.
• Insert SUCCEEDED rows after successful handleEvent.
• Insert DLQ rows in fallback failure handling.
• Update getNotification to support status and correct timestamp fields.
• Update portal-view to use status, default to the current user, and show all user-associated events including derived events.

Phase 2: Improve User Feedback

• Add an unread marker with read_ts.
• Add a small header badge query for unread FAILED and DLQ notifications and render the badge in red.
• Mark unread failure notifications as read when the user opens the header menu or the notification page.

Phase 3: Operations

• Add a generic operational cleanup startup hook with retention targets for notification_t and message_t.
• Make cleanup configurable by enablement, interval, batch size, and per-target retention days.
• Add a database lock so only one service instance runs cleanup at a time.
• Add an admin notification page under Event Admin that uses getNotification without a userId filter for host-wide failures.
• Add dashboards or alerts for repeated DLQ statuses.

Risks and Mitigations

API Marketplace Catalog

Context

The portal already has a Marketplace navigation group and an api-marketplace page registry entry. The current API administration page is table-oriented and is useful for owners, but it is not a consumer catalog. A Marketplace API catalog should let users discover APIs by business category, capability, protocol, lifecycle status, and governance metadata.

API create and update forms already use the standardized taxonomy fields:

• categoryIds for selected category identifiers.
• tagIds for selected tag identifiers.
• getCategoryLabelByType with entityType = "api" for category options.
• getTagLabelByType with entityType = "api" for tag options.

The service query layer also returns categoryIds, categories, tagIds, and tags for API rows. The catalog should use those fields for display and filtering instead of reintroducing the legacy apiTags string field.

Goals

• Add a Marketplace menu entry for an API catalog.
• Use database-backed categories and tags, not hard-coded UI lists.
• Keep categories and tags reusable across future catalog pages.
• Keep API create/update forms as the source of truth for taxonomy assignment.
• Give consumers a browse-first experience instead of an admin table.
• Support deep links from a catalog listing to API detail, versions, endpoints, runtime bindings, and owner actions.
• Preserve host scope and ownership rules already used by API administration.

Non-Goals

• Do not replace API administration pages with the catalog.
• Do not store display names in API rows when they can be resolved from category_t, tag_t, entity_category_t, and entity_tag_t.
• Do not use the old apiTags field for catalog filtering.
• Do not make taxonomy values static frontend constants.
• Do not expose private tenant APIs through a public catalog without an explicit visibility and authorization decision.

Current Building Blocks

User Experience

The first screen under Marketplace should be the usable catalog, not a landing page. The recommended route is:

/app/marketplace/api

The sidebar can keep the existing Marketplace group, but its children should move from API-type-only links to intent-based entries:

• API Catalog
• API Clients
• Schema Catalog
• YAML Rule
• Schema Form

The API Catalog page should provide:

• Search across API id, name, description, business group, line of business, capability, platform, git repository, categories, and tags.
• Category tabs or a category rail based on getCategoryLabelByType.
• Grouped tag filters based on getTagLabelByType.
• Filter chips for active category and tag selections.
• A compact card or list row per API with name, description, status, categories, tags, owner, business group, and latest version summary.
• Actions to view details, review versions, create a new version, update the API metadata, and open related runtime or access-control pages when the user has permission.

The catalog should support an Uncategorized bucket for active APIs without category assignments. This avoids hiding incomplete data and gives admins an easy cleanup target.

Categories And Tags

Categories should be stable browse buckets. Tags should be flexible facets. Both are stored with entityType = "api" so the same tag names can be reused for other entity types without forcing cross-catalog semantics.

Recommended initial API categories:

The stored category_name must stay lower-case and URL-friendly. The display labels above are UI labels derived from those values.

Recommended initial API tag groups:

Stored tag names must stay lower-case and URL-friendly. If a display label needs capitalization, the UI should format it or the label endpoint should provide a separate display field later.

Tags without tag_group_code or tag_group_label should be shown under a General filter group in the catalog UI. Configured groups should appear first by group_sort_order; the General group should appear after configured groups, matching the current label query behavior where null group sort values sort last.

Data Flow

Catalog filter option loading:

portal-view
  -> category/getCategoryLabelByType(hostId, entityType = "api")
  -> tag/getTagLabelByType(hostId, entityType = "api")

Catalog result loading:

portal-view
  -> service/getApi(hostId, offset, limit, active, filters, globalFilter, sorting)
  -> api rows with categoryIds, categories, tagIds, tags

The catalog should prefer server-side pagination and filtering. Client-side filtering is acceptable only for a small first pass because it breaks as soon as the API count exceeds one fetched page.

Query Contract

The existing getApi contract already supports filters, globalFilter, sorting, offset, limit, hostId, and active. To make the catalog work well at scale, add first-class filter support for taxonomy fields:

{
  "hostId": "01964b05-552a-7c4b-9184-6857e7f3dc5f",
  "offset": 0,
  "limit": 20,
  "active": true,
  "categoryIds": ["..."],
  "tagIds": ["..."],
  "tagMatch": "all",
  "globalFilter": "payment"
}

Recommended semantics:

• categoryIds uses OR semantics by default. An API in any selected category is returned.
• tagIds should support tagMatch = "all" and tagMatch = "any".
• Category and tag filters should use EXISTS against entity_category_t and entity_tag_t with entity_type = 'api' and active = TRUE.
• Display arrays should continue to be returned as categories and tags.
• Form update payloads should continue to submit identifiers only through categoryIds and tagIds.

Page Design

The API Catalog page can be implemented as a dedicated page rather than trying to stretch the current API admin table.

Proposed files:

src/pages/marketplace/ApiCatalog.tsx
src/pages/marketplace/components/ApiCatalogFilters.tsx
src/pages/marketplace/components/ApiCatalogCard.tsx
src/pages/marketplace/hooks/useApiCatalog.ts

Page state:

• search text
• selected category ids
• selected tag ids
• tag match mode
• active status
• pagination
• sorting
• view mode, either compact list or card grid

Catalog state should be URL-driven from Phase 1. Search text, selected categories, selected tags, tag match mode, active status, sorting, and pagination should be encoded in the query string so users can refresh the page, use browser navigation, and share filtered catalog URLs. Example:

/app/marketplace/api?q=payment&category=public-api&tag=oauth2&tag=mtls&tagMatch=all&page=1

The page should still reuse existing infrastructure:

• fetchClient for portal query calls.
• useUserState for host and user context.
• buildTaskAwareRoute for deep links.
• ownership utilities for update/delete action visibility.
• TaskActionPanel for publisher/admin next actions.
• pageRegistry and contextual help metadata.

Routing And Navigation

Add or update these portal-view entries:

The existing /app/marketplace route can redirect to /app/marketplace/api or remain a broader Marketplace landing page later. For the first API catalog implementation, redirecting keeps the behavior simple.

Backend Changes

The backend already persists API category and tag relationships. The main backend change is query filtering:

1. Extend service-query spec for optional categoryIds, tagIds, and tagMatch.
2. Update GetApi to pass those optional fields to the DB provider.
3. Update PortalDbProvider#getApi and ApiServicePersistenceImpl#getApi.
4. Add SQL predicates over entity_category_t and entity_tag_t.
5. Verify or add compound indexes for taxonomy filtering.
6. Add tests for category-only, tag-any, tag-all, combined taxonomy filters, and APIs with no taxonomy assignments.

The existing join-table indexes are useful for entity lookups and label resolution, but catalog filtering also needs indexes that start with filter fields. Before implementing Phase 2, verify the query plan and add indexes if needed:

CREATE INDEX idx_entity_tag_filter
ON entity_tag_t (entity_type, tag_id, entity_id)
WHERE active = TRUE;

CREATE INDEX idx_entity_category_filter
ON entity_category_t (entity_type, category_id, entity_id)
WHERE active = TRUE;

For tagMatch = "all", prefer a single grouped subquery over generating one EXISTS predicate per selected tag when the selected tag set can grow. A common shape is to filter entity_tag_t by selected tag ids, group by entity_id, and require COUNT(DISTINCT tag_id) = selectedTagCount.

The query response should continue to include both identifiers and labels:

{
  "apiId": "0001",
  "apiName": "Petstore",
  "categoryIds": ["..."],
  "categories": ["public-api"],
  "tagIds": ["..."],
  "tags": ["openapi", "oauth2"]
}

Implementation Phases

Phase 1: Catalog Page

• Add the API Catalog route and Marketplace menu entry.
• Load category and tag options from the existing label endpoints.
• Load APIs with service/getApi.
• Render search, category filter, grouped tag filter, and API list/card results.
• Store catalog filters, search text, sorting, and pagination in the URL query string.
• Use current query response labels for display.
• Deep-link to existing API detail and update forms.

Phase 2: Server-Side Taxonomy Filters

• Add categoryIds, tagIds, and tagMatch to service-query.
• Implement SQL filtering in ApiServicePersistenceImpl.
• Keep current table filtering support for admin use.
• Add DB provider and handler tests.

Phase 3: Catalog Polish

• Add API detail summary panels with versions, endpoint count, runtime exposure, and access-control hints.
• Add help docs and task links.
• Add optional counts per category and tag if the catalog needs faceted counts.

Open Questions

• Should Marketplace API Catalog show only active APIs by default? The recommendation is yes, with an admin-visible inactive filter.
• Should unauthenticated users ever see catalog data? The recommendation is no until a separate public visibility model is designed.
• Should category selection be single-select or multi-select? The recommendation is multi-select OR semantics for flexibility.
• Should tags use all-match or any-match by default? The recommendation is all for precision, with a visible toggle if users need broader searches.
• Should OpenAPI tags imported from specs automatically create API catalog tags? The recommendation is no for the first pass. Spec tags are often endpoint-level groupings and should not automatically become curated catalog taxonomy.

AI Agent Registration In Task Center

Status

Initial Task Center implementation is available. The first version uses the existing API-version and agent-definition commands with backend validation guardrails. A dedicated composite registration command remains a later automation enhancement.

Context

Light Portal treats an AI agent as an API. The API record provides the stable catalog identity, ownership, display name, marketplace metadata, and lifecycle. The API version record provides the deployable version identity. The agent definition record is an agent-specific profile extension for the same API version.

The current data model already reflects this relationship:

• api_t owns the logical API and display name.
• api_version_t owns the API version identity.
• agent_definition_t.agent_def_id stores the same UUID as api_version_t.api_version_id.
• agent_definition_t stores model and runtime profile fields such as model_provider, model_name, api_key_ref, temperature, and max_tokens.
• Agent query paths join agent_definition_t to api_version_t and api_t to expose the effective agent metadata.

The registration UX should make this model explicit. Operators should not have to understand the table split. They should see one task: register an AI agent.

Goals

• Add a focused Task Center flow named Register AI Agent.
• Register the agent first as an API and API version.
• Create the agent definition profile using the same ID as the API version.
• Keep event sourcing and replay clean by using domain events instead of direct table writes.
• Avoid duplicating mutable display name fields between api_t and agent_definition_t.
• Allow skills, tools, memory, access control, and deployment links to be added after the base agent is registered.

Non-Goals

• Do not create a second standalone agent registry independent from APIs.
• Do not make AgentDefinitionCreatedEvent create api_version_t.
• Do not make ApiVersionCreatedEvent directly write agent_definition_t unless the event schema is intentionally expanded later.
• Do not require all skill and tool assignments during the initial registration.
• Do not replace the existing Manage GenAI Assets task. That task remains the broader maintenance flow.

Identity Model

The agent identity is the API version identity.

api_t
  host_id
  api_id
  api_name              # canonical agent display name

api_version_t
  host_id
  api_version_id        # canonical agent definition id
  api_id
  api_version
  api_type = "agt"      # or accepted legacy value "agent"

agent_definition_t
  host_id
  agent_def_id          # same value as api_version_t.api_version_id
  model_provider
  model_name
  api_key_ref
  temperature
  max_tokens

agent_definition_t should remain a profile extension. It should not duplicate the agent name. Reads can continue to expose agentName, but the value should come from api_t.api_name.

API Type

Use agt as the canonical API type for AI agents if the reference data uses the short code model. During migration, command handlers and queries can accept both agt and agent to avoid breaking existing test data or early records.

The Portal UI should display this as Agent and submit the canonical value. Database columns use snake case such as api_type; event payloads and command requests use camel case such as apiType. The mapper must preserve this translation and normalize agent type values consistently.

When registering an agent against an existing API, the backend must validate the existing API-version family. A logical API should not mix unrelated version types. If the selected api_t already has active versions, they must all be agent versions before an agt version can be added. The reverse should also be enforced: once an API has an active agent version, non-agent API versions should not be added under the same api_id.

Event Model

The Task Center flow should produce two domain events for the required base registration:

1. ApiVersionCreatedEvent
2. AgentDefinitionCreatedEvent

The two-event design is preferred because these are two separate domain facts:

• an API version exists and can participate in the API catalog;
• that API version has an agent runtime profile.

This should not be modeled as two direct table writes from one handler. The event processor should continue to populate projection tables during normal processing and replay.

Event Order

ApiVersionCreatedEvent must be persisted and projected before AgentDefinitionCreatedEvent, because agent_definition_t has a foreign key to api_version_t.

Register AI Agent
  -> ApiCreatedEvent, if the logical API does not already exist
  -> ApiVersionCreatedEvent
  -> AgentDefinitionCreatedEvent
  -> optional AgentSkillCreatedEvent events
  -> optional access-control events

The minimum required sequence for an existing API is:

ApiVersionCreatedEvent
AgentDefinitionCreatedEvent

Aggregate IDs

ApiVersionCreatedEvent keeps the API version aggregate identity:

{
  "aggregateType": "ApiVersion",
  "subject": "<apiVersionId>",
  "data": {
    "hostId": "<hostId>",
    "apiId": "<apiId>",
    "apiVersionId": "<apiVersionId>",
    "apiVersion": "1.0.0",
    "apiType": "agt"
  }
}

AgentDefinitionCreatedEvent uses the same UUID for its aggregate identity:

{
  "aggregateType": "AgentDefinition",
  "subject": "<apiVersionId>",
  "data": {
    "hostId": "<hostId>",
    "agentDefId": "<apiVersionId>",
    "apiVersionId": "<apiVersionId>",
    "modelProvider": "openai",
    "modelName": "gpt-4.1",
    "apiKeyRef": "secret://openai/default",
    "temperature": 0.7,
    "maxTokens": 4096
  }
}

The event utility should continue to accept either agentDefId or apiVersionId for AgentDefinition aggregate ID calculation, but the canonical payload should include both during migration and treat them as equal.

Task Center Flow

Add a Task Center definition:

id: register-ai-agent
title: Register AI Agent
category: API Marketplace or Portal Administration
roles: user, admin
keywords: agent, ai, genai, model, skill, tool

The task should guide the operator through a narrow registration path. It is different from Manage GenAI Assets, which is a broad maintenance task for agents, skills, tools, memory, and session history.

Steps

Task Context

The task context should carry IDs from one step to the next:

{
  "hostId": "<hostId>",
  "apiId": "<apiId>",
  "apiVersionId": "<apiVersionId>",
  "agentDefId": "<apiVersionId>",
  "serviceId": "<serviceId>",
  "providerId": "<modelProvider>",
  "apiType": "agt"
}

When the API version step completes, apiVersionId should be copied to agentDefId automatically before launching the agent definition step.

Incomplete Registration Handling

If the UI calls createApiVersion and then fails before createAgentDefinition is processed, the system can contain an agent API version without an agent definition. This is an incomplete registration, not a valid runnable agent.

The UI and query layer should treat these rows explicitly:

• Agent list views should be able to detect agent API versions missing matching agent_definition_t rows by left joining api_version_t to agent_definition_t.
• The row should be shown as Incomplete or Profile missing, not as a ready agent.
• The primary action should be Complete profile, prefilled with agentDefId = apiVersionId.
• A secondary action can delete or deactivate the orphaned API version if the operator abandons the registration.
• Runtime catalog reads should not expose incomplete agents as executable.

This requirement makes the UI-orchestrated implementation safe enough for the first Task Center version. The long-term backend command should still create the version and profile in one ordered command to reduce orphan creation.

Frontend Design

Phase 1: Task Registry Only

The first implementation can add a Task Center entry that reuses existing pages and forms:

• createApi
• createApiVersion
• createAgentDefinition
• AgentSkill
• SkillTool
• rolePermission
• InstanceApi

This is low risk and aligns with the current task-oriented navigation model.

The createApiVersion form should support prefilled apiType=agt from the task route. The form completion handler should save returned apiVersionId into the task context.

The createAgentDefinition form should accept apiVersionId or agentDefId from task context and submit both values, with agentDefId equal to apiVersionId.

Phase 2: Dedicated Registration Wizard

After the flow is validated, add a dedicated wizard route such as:

/app/genai/register-agent

The wizard can reduce clicks by combining API version and agent profile fields on one page while still submitting separate commands or a composite command.

Recommended sections:

• API identity: API name, API ID, status, owner.
• Version identity: version, service ID, environment tag, target host.
• Model profile: provider, model, API key reference, temperature, max tokens.
• Optional skills: selected skill IDs.
• Optional deployment: instance or gateway link.

Secret Reference Selection

apiKeyRef is a secret reference, not a secret value. The UI should not ask operators to paste raw provider keys into the agent definition form.

The preferred control is a selector populated from the configured secret catalog, config-server reference data, or vault integration available to the current host. The selected value should be stored as a reference such as:

secret://openai/default

If manual entry is temporarily supported, it should be an advanced path with validation. The command should reject values that look like raw API keys and should accept only approved reference schemes.

Secure Default Access

The access-control step is optional for registration completeness, but runtime execution must be secure by default. A newly registered agent should not be publicly invokable just because the API version and profile exist.

Default behavior:

• management is limited to the creator, owner, or admin roles according to the existing ownership model;
• runtime invocation is denied until an explicit role, scope, policy, or runtime assignment grants access;
• skill and tool assignment does not override access control;
• if no access policy exists, the gateway or agent runtime should treat the effective execution policy as deny-all.

Backend Command Options

Option 1: UI-Orchestrated Existing Commands

The Task Center flow calls existing commands in sequence:

1. createApi, if a new API is needed.
2. createApiVersion.
3. createAgentDefinition.
4. Optional createAgentSkill events.

This is the recommended initial implementation. It avoids changing command handler infrastructure and uses existing event types.

This option must include incomplete-registration handling. Without that, a browser failure or second-command validation error can leave an agent API version without an agent definition. That state is repairable, but the UI must surface it clearly and runtime catalog reads must ignore it.

Option 2: Composite Register Command

Add a composite command such as:

lightapi.net/genai/registerAiAgent/0.1.0

The command would validate the combined request and emit ordered events:

1. ApiVersionCreatedEvent.
2. AgentDefinitionCreatedEvent.
3. Optional AgentSkillCreatedEvent events.

This improves user experience for automation and API consumers, but it requires the command layer to support a multi-event result in one request. The command must not bypass event processing or write projection tables directly.

The initial composite command should require an existing apiId. Keeping API creation as a separate command keeps the backend contract smaller and preserves the existing API ownership workflow. A later full registration command can add ApiCreatedEvent if automation needs to create the logical API and agent version in one request.

Recommendation

Start with Option 1 only if incomplete registrations are visible and repairable. Prioritize Option 2 before exposing a one-click production registration wizard, because it gives the backend one validation boundary for the API version and agent profile.

Validation Rules

Command handlers should enforce these rules server-side:

• Agent API versions must use apiType = agt or an accepted compatible value.
• New writes should use canonical agt. Legacy agent should be accepted only for migration, import, or replay compatibility.
• A logical API should not mix active agent and non-agent API versions.
• agentDefId must equal apiVersionId when both are present.
• The referenced API version must exist before creating the agent definition.
• The referenced API version must belong to the same hostId.
• The referenced API version must have agent API type.
• modelProvider and modelName are required for creation.
• apiKeyRef, when present, must be a secret reference and not a raw provider key.
• temperature, when provided, must be in the supported provider range.
• maxTokens, when provided, must be positive.
• Optional skill IDs must reference active skills in the same host scope.

The UI should guide the user, but the command and persistence layers should remain authoritative.

Query And Display

Agent list and detail views should display a joined projection:

The Agent Definition page should make the API identity read-only once selected. Mutable profile fields should remain editable through AgentDefinitionUpdatedEvent.

Delete And Update Semantics

Updating the API name should update the visible agent name because the display name comes from api_t.api_name.

Updating the API version should not implicitly update model settings. Model profile changes should use AgentDefinitionUpdatedEvent.

Deleting or deactivating the API version should cascade or hide the agent definition through the existing API-version relationship. Explicit AgentDefinitionDeletedEvent remains useful when the operator wants to disable the agent profile while keeping the API version.

Migration Notes

• Existing rows that use api_type = agent can remain readable while the UI moves toward canonical agt.
• Projection builders can normalize legacy agent events to agt in api_version_t after the migration window. Event streams remain immutable, but new command writes should use only agt.
• Existing task contexts may carry either apiVersionId or agentDefId. Task utilities should normalize both values to the same ID.
• Documentation and form labels should say Agent API version id where the ID is exposed.
• Import/export and event replay should preserve event order for agent registration bundles.

Implementation Plan

1. Add Register AI Agent to portal-view/src/tasks/taskRegistry.ts.
2. Add help content under src/help/portal-view/tasks/register-ai-agent.md.
3. Ensure createApiVersion can be launched with apiType=agt.
4. Ensure form completion stores apiVersionId into task context.
5. Ensure createAgentDefinition can prefill agentDefId from apiVersionId.
6. Add server-side validation that agentDefId == apiVersionId.
7. Add compatibility handling for agt and agent API type values.
8. Add incomplete-registration detection and repair actions for agent API versions that do not have a matching agent definition.
9. Add secure-by-default invocation checks for agents with no explicit access policy.
10. Add integration tests for the two-event registration sequence.
11. Add a composite registerAiAgent command for API-version plus profile creation.

Resolved Recommendations

• Persist agt as the canonical API type after migration. Keep agent readable for replay, import, and old data, but reject new command writes using agent after the migration window.
• Put Register AI Agent under API Marketplace initially because the agent is registered as an API and should be discoverable through the API catalog. If a dedicated GenAI Assets category is added later, the task can move there without changing the backend model.
• Keep skill assignment optional. An agent can be useful as an LLM-only worker, and required skill assignment would block simple conversational agents.
• The first composite command should require an existing API and emit ApiVersionCreatedEvent plus AgentDefinitionCreatedEvent. Keep ApiCreatedEvent separate until automation needs a full create-everything command.

Decision Summary

Register AI agents through a Task Center flow that starts from API and API version registration. Create api_version_t first, then create agent_definition_t with agentDefId equal to apiVersionId. Use two domain events for the two required facts, keep projection writes behind event processing, reject mixed API-type families, treat incomplete version-only registrations as repairable but non-runnable, default runtime invocation to deny-all, and make the broader skill/tool/access setup optional follow-up steps.

OAuth Kafka

Token Exchange

This document outlines the design decisions and implementation details for supporting multiple token exchange flows in the oauth-kafka module.

Comparison of Detection Methods

When implementing token exchange (RFC 8693), the server must determine which identity provider (IdP) issued the subject_token to verify it correctly and map claims.

Implementation Strategy

Our implementation in ProviderIdTokenPostHandler uses Option 4: Client Context as the primary strategy:

1. Database-Driven Configuration: A new column token_ex_type has been added to the auth_client_t table to specify the supported exchange type for each client.

   ALTER TABLE auth_client_t ADD COLUMN token_ex_type VARCHAR(64);
   

2. Supported Exchange Types:
   • msal: Microsoft Authentication Library based exchange.
   • ccac: Client Credentials to Authorization Code exchange.
3. Flow Determination: Instead of relying on client-supplied parameters like requested_token_type, the server retrieves the token_ex_type from the client context in the database to decide which handler to use. This ensures that only authorized exchange types are performed for each specific client.

Recommendation

For the light-portal ecosystem:

• Option 4: Client Context is the selected method. It provides the highest level of security by ensuring that token exchange flows are explicitly configured and restricted on a per-client basis in the database.
• token_ex_type should be populated for any client that requires token exchange functionality. Clients without this configuration will not be allowed to perform token exchange.

Future Considerations

• Implement automated issuer discovery if the number of external providers grows.
• Support “opaque” token exchange by integrating with introspection endpoints of external IdPs.
• Extend the auth_client_t configuration to support multiple allowed exchange types per client if needed.

Light OAuth

Light OAuth IPv6 Support

Problem

The Rust light-oauth service binds its HTTPS listener to 0.0.0.0. That is correct for IPv4, but it does not accept connections sent to an IPv6 address.

In a dual-stack container network, Docker DNS can return the IPv6 address for light-oauth before the IPv4 address. A client that does not retry the next address can fail even though the service is healthy on IPv4. One observed failure is the gateway proxying /oauth2/{providerId}/code to https://light-oauth:6881 and receiving ECONNREFUSED on the IPv6 address.

Goals

• Allow light-oauth to bind IPv4, IPv6, or a specific interface from config.
• Keep the current default behavior as IPv4 wildcard binding.
• Avoid breaking existing deployments whose server.yml does not contain the new property.
• Build the listener address with SocketAddr so IPv6 addresses are parsed correctly.

Non-Goals

• Do not enable IPv6 for every deployment by default.
• Do not change TLS, OIDC, token, or database behavior.
• Do not change gateway upstream retry behavior in this change.

Configuration

light-oauth adds a server bind IP property:

ip: ${server_ip:0.0.0.0}

The default value remains:

server_ip: "0.0.0.0"

To listen on IPv6 wildcard:

server_ip: "::"

To listen on a specific IPv4 or IPv6 address:

server_ip: "172.16.1.3"

server_ip: "fdd0:0:0:1::3"

Implementation

The Rust config model includes an ip field with a default of 0.0.0.0. The default keeps old external server.yml files working.

The listener address is built as:

#![allow(unused)]
fn main() {
let ip = config.ip.parse::<IpAddr>()?;
let addr = SocketAddr::new(ip, config.port);
}

This avoids string formatting problems with IPv6 addresses. For example, :: plus port 6881 must become [::]:6881, not :::6881.

Deployment Guidance

Use IPv6 binding only when the runtime network is intentionally dual-stack and other services can reach the IPv6 address. In a container environment, confirm that:

• the container network has IPv6 enabled;
• the service has an IPv6 address;
• clients resolve or connect to the same address family;
• health checks cover the chosen address family.

For local or single-stack deployments, keep the default IPv4 binding.

Verification

For IPv4 default:

curl -k https://light-oauth:6881/oauth2/<providerId>/keys

For IPv6 wildcard binding in a dual-stack network, verify from another container:

curl -k -g https://[<light-oauth-ipv6>]:6881/oauth2/<providerId>/keys

If the client uses service DNS, verify that the first returned address family is reachable:

getent ahosts light-oauth
curl -k -v https://light-oauth:6881/oauth2/<providerId>/keys

Light Controller

Light Controller IPv6 Support

Problem

The Rust controller-rs service is the control-plane endpoint for runtime registration, discovery, MCP admin traffic, and portal event streams. In dual-stack deployments, clients can resolve the controller hostname to either IPv4 or IPv6. The controller listener and its TLS configuration must therefore support IPv6 without changing the existing IPv4 deployment defaults.

The important distinction is between socket addresses and service metadata:

• the controller listener uses a socket address such as 0.0.0.0:8438 or [::]:8438;
• registered runtime instances publish a host address string plus a separate port, such as fdd0:0:0:1::3 and 8443.

Current Behavior

controller-rs already stores its bind address as a Rust SocketAddr. The default remains IPv4 wildcard binding:

0.0.0.0:8438

The listener address can be overridden with CONTROLLER_ADDR. For IPv6, the value must use bracketed socket-address syntax:

CONTROLLER_ADDR='[::]:8438'

This value is used directly by both server modes:

• HTTPS/WSS mode uses axum_server::bind(settings.listen_addr).
• HTTP/WS mode uses tokio::net::TcpListener::bind(settings.listen_addr).

There is no string concatenation of IP and port in the controller listener path, so the common IPv6 failure form :::8438 is avoided.

Goals

• Support IPv4, IPv6, and dual-stack controller listener binding.
• Keep the current default as IPv4 wildcard binding.
• Keep the existing CONTROLLER_ADDR configuration contract.
• Accept runtime registration metadata that uses IPv4 literals, IPv6 literals, or DNS hostnames.
• Reject unspecified runtime registration addresses such as 0.0.0.0 and ::, because those are bind addresses, not reachable service addresses.

Non-Goals

• Do not enable IPv6 by default.
• Do not change controller WebSocket paths or JSON-RPC contracts.
• Do not change the runtime registration metadata shape.
• Do not add client-side IPv4 fallback in this change.

Listener Configuration

Default IPv4 listener:

CONTROLLER_ADDR='0.0.0.0:8438'

IPv6 wildcard listener:

CONTROLLER_ADDR='[::]:8438'

Specific IPv6 interface:

CONTROLLER_ADDR='[fdd0:0:0:1::10]:8438'

Specific IPv4 interface:

CONTROLLER_ADDR='172.16.1.10:8438'

The brackets are required only because CONTROLLER_ADDR is a full socket address. They separate the IPv6 literal from the port.

TLS Configuration

The controller starts with TLS enabled by default. IPv6 listener support does not remove the normal TLS hostname requirements.

For production, provide a certificate whose Subject Alternative Name covers the DNS name or IP address clients use to reach the controller:

CONTROLLER_TLS_CERT_PATH=/config/server.pem
CONTROLLER_TLS_KEY_PATH=/config/server.key
CONTROLLER_TLS_TRUST_CERT_PATH=/config/ca.pem

For generated local self-signed certificates, include any IPv6 literal that clients will use:

CONTROLLER_TLS_SERVER_NAME=localhost
CONTROLLER_TLS_ALT_NAMES='localhost,127.0.0.1,::1'

If clients connect by DNS name, prefer adding that DNS name to the certificate SAN and keep clients using the name instead of a raw IP literal.

Runtime Registration Metadata

Runtime services connect outbound to Light Controller and send service/register metadata. The registration address is not a socket address; the address and port are separate fields.

IPv6 registration metadata should use the raw IPv6 literal:

{
  "serviceId": "com.networknt.light-gateway-1.0.0",
  "protocol": "https",
  "address": "fdd0:0:0:1::3",
  "port": 8443
}

Do not use brackets in the address field:

{
  "address": "[fdd0:0:0:1::3]"
}

Brackets are only used when constructing URL authorities or socket addresses. The controller validates registration addresses as IP literals or DNS hostnames and rejects unspecified bind addresses such as 0.0.0.0 and ::.

Discovery Behavior

Discovery returns the registered address and port separately. Downstream clients, such as light-gateway, are responsible for building a reachable upstream authority. For IPv6 literals, clients must bracket the address when they construct a URL or host:port authority:

address = fdd0:0:0:1::3
port    = 8443
target  = [fdd0:0:0:1::3]:8443

Deployment Guidance

Only configure the controller with CONTROLLER_ADDR='[::]:8438' when the host, container network, Kubernetes Service, and ingress path are intended to accept IPv6 traffic.

In a dual-stack environment, verify all of these:

• the controller process is listening on IPv6;
• DNS returns the expected address family;
• TLS SANs cover the hostname or IP clients use;
• runtime services can open outbound WebSocket connections to the controller;
• registered service metadata publishes reachable addresses, not wildcard bind addresses.

Verification

From a peer in the same network:

getent ahosts <controller-host>
curl -k -g https://[<controller-ipv6>]:8438/health
curl -k -v https://<controller-host>:8438/health

For WebSocket clients, verify the same address family through the real endpoint:

wss://<controller-host>:8438/ws/microservice
wss://<controller-host>:8438/ws/discovery
wss://<controller-host>:8438/ctrl/mcp

If a TLS client connects by IPv6 literal and fails certificate validation, check the certificate SANs before changing the controller listener.

Configurable Controller Transport and Codec Profiles

Status

This document defines a layered controller communication architecture in which application semantics, serialization, framing, transport, and gateway routing are separate decisions. It covers both the Rust runtime control channel and the browser MCP path through light-gateway.

• Status: proposed future transport architecture; the active production milestone is JSON/WebSocket Control Plane V1. WebTransport remains blocked, and the N5 codec decision did not authorize a production rkyv canary
• Protocol baseline tested: 2026-07-16
• Implementation gate: WebTransport implementation remains blocked until a future Phase 0 rerun satisfies the browser, native-library, and current-draft contracts
• Controller: controller-rs
• Rust runtime client: light-fabric/crates/portal-registry
• Browser client: portal-view
• Gateway/BFF: light-fabric/apps/light-gateway
• Existing compatibility paths: MCP-style JSON-RPC over WebSocket and runtime JSON-RPC over WebSocket
• Experimental transports and codecs: WebTransport and rkyv
• Out of scope: metrics ingestion, distributed controller state, browser rkyv, and automatic translation between different transports or codecs

WebTransport remains disabled. WebSocket and JSON remain the defaults until a future feasibility run satisfies protocol compatibility, browser authentication, gateway routing, deployment support, and performance gates.

Completed implementation status

The WebSocket-only near-term sequence N0 through N5 is complete:

• N0 froze the comparable JSON/WebSocket workload and baseline;
• N1 extracted codec-neutral session inputs and outputs;
• N2 added explicit WebSocket profile negotiation and handshake authentication;
• N3 completed the opt-in rkyv-over-WebSocket vertical slice;
• N4 completed bounded decoding, fuzzing, and resilience gates; and
• N5 found no qualifying material codec benefit and selected KEEP_JSON_WEBSOCKET_DEFAULT_NO_CANARY.

N6 is not authorized. The dormant rkyv implementation remains disabled and is not an available production profile. Reopening it requires a new comparable N5 result that satisfies the existing material-benefit threshold. Reopening WebTransport separately requires a new Phase 0 result that satisfies the browser, native Rust, gateway, and deployment contracts.

Active JSON/WebSocket Control Plane V1 Contract

This section is normative for the stabilization milestone. The remainder of this document describes both the current baseline and possible future profiles; where a future-profile section conflicts with this section, this V1 contract wins for production configuration.

Enabled surfaces and profiles

CONTROLLER_WEBSOCKET_BINARY_PROFILES is empty, runtime controlCandidates do not select rkyv, and no WebTransport listener, capability endpoint, browser ticket, QUIC route, or HTTP/3 inference is enabled. /ctrl/mcp is the single browser control and notification socket; the obsolete /ws/mcp and /ws/portal-events split is not a supported V1 topology.

Cumulative authorization boundaries

The gateway makes one connection decision before discovery, connection permit acquisition, or upstream connection. It constructs the canonical policy key /ctrl/mcp@connect from the matched /ctrl/mcp route and admits only an exact admin, host-admin, or instance-admin role token. Missing, invalid, or unavailable policy denies when defaultDeny is true. Service-to-service routes remain outside this human-role decision.

The gateway registers and enables the shared access-control runtime, injects it into WebSocketRouterRuntime, and does not also run the generic HTTP access-control handler in the normal chat chain. That chain remains exception -> stateless -> security -> websocket.

The gateway remains payload-opaque after upgrade. The controller independently verifies the forwarded Bearer JWT, requires portal.r for MCP connection/read operations, and requires portal.w for mutations. Gateway roles never replace controller scopes. The exhaustive controller tool policy is frozen as data in implementation/light-controller/stabilization/s0/fixtures/controller-tool-policy-v1.json. Any catalog change must update that manifest and its conformance cases in the same pull request.

The Rust OAuth issuer advertises portal.r and portal.w, validates requested scopes as complete tokens rather than substrings, and grants portal.w only to registered clients/users that are entitled to it. Tokens with write authority contain both portal.r and portal.w.

All runtime mutation requires CONTROLLER_MCP_MUTATIONS_ENABLED=true plus portal.w. Shutdown additionally requires CONTROLLER_MCP_SHUTDOWN_ENABLED=true; chaos mutation/fault injection additionally requires CONTROLLER_MCP_CHAOS_ENABLED=true. All three settings default to false. Reading chaos configuration remains a read operation but is hidden unless the chaos feature is enabled.

Browser handshake and Origin

The browser supplies its CSRF token through the existing WebSocket subprotocol mechanism. The gateway validates exactly one matching CSRF token, removes it from the upstream protocol offer, strips browser Cookie/Authorization and untrusted identity headers, and injects only trusted routing context and the gateway-produced Bearer token.

websocket-router.originAllowlist[/ctrl/mcp] is non-empty. The gateway compares the complete normalized scheme, host, and effective port. Missing, opaque/null, malformed, suffix, substring, or unlisted Origins deny before upstream connection. The controller listener is not exposed to the browser network.

MCP lifecycle, messages, and errors

The external session moves through connecting, awaiting-initialize-result, sending-initialized, and ready. Before ready, only initialize, the subsequent notifications/initialized, and WebSocket control frames are valid. The V1 MCP protocol version is 2025-11-25.

Requests and responses use JSON-RPC 2.0. IDs are strings or numbers and are never reused while pending. Notifications omit id. Parse error, invalid-request, method-not-found, invalid-params, internal, timeout, unavailable, resource-limit, and structured tool-error outcomes are bounded and must not expose credentials or full sensitive arguments. An unsupported or unavailable runtime capability never becomes generic success.

Notification ownership

Host lifecycle notices may reach every admitted MCP connection for that host. Log and other runtime streams are bounded per-connection subscriptions keyed by runtime instance and notification class. start_logs adds only the caller’s subscription; stop_logs removes only that caller’s subscription. If the runtime stream is shared, controller reference counting prevents one caller from stopping another. Disconnect, token expiry, runtime reconnect, or explicit stop revokes the affected subscription.

Notification delivery is at-most-once and has no durable cursor in V1. A disconnect may lose notifications. After reconnect, portal-view must complete MCP initialization, rerun the authoritative hybrid query, refresh runtime capabilities, reconcile the live overlay, and only then recreate the user’s requested stream subscriptions. It must not replay mutations or assume an old start_logs subscription survived the connection.

Runtime list and host binding

lightapi.net/instance/getRuntimeInstance/0.1.0 is the authoritative set of UI runtime rows. Its gateway req-acc rule admits the same three administrative roles. The handler reads the independently verified host claim and requires an exact match with requested data.hostId; missing, malformed, mismatched, or client-only host context fails closed even for admin. Controller live state may update only IDs already returned by the hybrid query and never creates a new row.

Non-administrative user/position ownership is deferred until a durable runtime-to-configured-instance association and authoritative human owner source exist. V1 does not widen /ctrl/mcp or this control-page query to those users. V1 also has no cross-host wildcard, portal.global_r bypass, or super-admin exception. A future global view requires a separate design for issuer grants, audit, query fan-out, pagination, failure isolation, and per-host enforcement; it must not weaken the exact verified-host rule in place.

Limits and policy convergence

The controller enforces a 1 MiB MCP JSON message/frame limit plus bounded connections, pending commands, queues, subscriptions, initialization, and request deadlines. The payload-opaque gateway enforces transport/header, connection, rate, idle, upstream-connect, and read/write limits; it does not claim application-message parsing.

An authenticated MCP connection is limited to one active dispatch, 32 requests per second with a burst of 64, and JSON nesting depth 128. Controller-wide MCP admission is limited to 1,024 requests per second with a burst of 2,048. Exceeding a request bound returns a resource-limit outcome; repeated abuse closes the connection. These limits apply before expensive tool dispatch and are independent of the runtime command permits.

A valid policy reload applies atomically to new upgrades. A malformed reload retains the last known-good revision. Existing opaque tunnels are not force-closed by reload; their effective lifetime is the lesser of the verified JWT lifetime and websocket-router.maxConnectionDurationMs=900000. Immediate incident revocation disables the external route or restarts the gateway. Critical off-boarding must use that immediate operational path; routine policy reload alone is not an immediate revocation mechanism for an existing tunnel.

The immutable V1 examples, authorization corpora, limit contract, tool-policy manifest, and baseline gate live under implementation/light-controller/stabilization/s0. They are contract inputs, not runtime dependencies shared between TypeScript and Rust.

Problem

Rust services currently connect to controller-rs through /ws/microservice. The channel carries JSON-RPC messages for:

• service/register and its acknowledgement;
• service/update_metadata;
• discovery lookup and subscriptions;
• controller-to-runtime commands;
• runtime-to-controller command responses;
• runtime notifications such as notifications/log;
• liveness messages.

The browser separately connects to /ctrl/mcp on light-gateway. The gateway’s WebSocket router authenticates and resolves the target during the HTTP/1 upgrade, then Pingora tunnels the upgraded connection to controller-rs without parsing MCP messages.

Both paths currently bind several independent choices together:

• MCP and runtime-control application semantics;
• JSON-RPC serialization;
• WebSocket message framing;
• TCP/TLS transport;
• gateway routing and authentication.

That coupling makes it difficult to determine whether a measured improvement comes from QUIC multiplexing, a binary codec, or both. It also makes a future browser WebTransport path appear to require rkyv, although the browser should continue to use MCP JSON.

The current runtime channel is reliable and portable, but all messages in one direction share one ordered WebSocket byte stream and JSON parsing. A high-volume runtime notification can therefore delay a command response traveling in the same service-to-controller direction.

The commonly cited example of an inbound log blocking an outbound controller command is not precise. TCP is full-duplex: runtime logs travel toward the controller while the command request travels toward the runtime. The risk that must be measured is same-direction queueing, especially command responses sharing the runtime’s outbound path with log notifications.

The design must not assume that WebTransport or rkyv is faster for this workload. Registration also includes JWT validation and persistence, and many command results contain arbitrary JSON. Benchmarks must vary transport and codec independently so the source of any improvement is measurable.

Current Boundaries

The current end-to-end surfaces are:

This proposal keeps every existing endpoint and payload contract. It adds an experimental WebTransport binding for runtime control and defines a future MCP JSON binding through a WebTransport-aware gateway router. /ws/discovery remains WebSocket-only in the initial implementation.

MCP remains the external command surface and JSON-RPC message contract. rkyv is a serialization codec for the private Rust runtime-control profile; it is not a replacement encoding for standard MCP clients.

The private Rust runtime-control profile includes registration, registry and discovery operations carried on that controller connection, commands, responses, and runtime notifications. It does not change general application service-to-service APIs. Standalone discovery clients and non-Rust controller clients remain on their explicitly supported JSON profiles unless a later design adds another interoperable codec.

The existing ServiceMetadata.protocol field describes the runtime’s advertised application protocol, such as https. It must not be reused to record the controller connection transport or wire codec.

Layered Model

The implementation separates five layers:

MCP handlers or runtime-control handlers
  -> logical requests, responses, notifications, and lifecycle events
  -> negotiated wire profile and codec
  -> message framing and logical channel mapping
  -> WebSocket or WebTransport session adapter
  -> optional light-gateway route resolver and transport proxy

The terms used by this document are:

• Application protocol: MCP or the private runtime-control protocol.
• Codec: JSON-RPC/JSON or the versioned rkyv wire schema.
• Wire profile: the complete application message contract, codec, framing, validation rules, limits, and version. A profile does not select a transport.
• Transport: WebSocket or WebTransport.
• Router: a gateway component that authenticates the incoming session, selects an upstream, and proxies the selected transport.

Transport configuration selects how a session is carried. Protocol negotiation selects how its bytes are interpreted. A server accepts only explicitly allowed profile and transport pairs; configurability does not imply support for every Cartesian product.

Supported Profile Matrix

The current WebSocket paths predate profile negotiation. Absence of a profile token on those paths means the existing JSON behavior. New binary behavior requires an explicit negotiated token and must never be inferred from the first payload bytes.

Goals

• Make transport and codec selection independent while preserving allowlisted combinations.
• Add a multiplexed Rust-to-Rust control transport without removing the current WebSocket contract.
• Define MCP JSON over WebTransport without requiring browser rkyv.
• Reuse gateway route resolution, discovery, authorization, and limits without treating the current HTTP/1 upgrade tunnel as a WebTransport implementation.
• Keep controller business behavior identical across transports and codecs.
• Isolate controller commands and their responses from asynchronous runtime notifications.
• Use a validated, explicitly versioned rkyv format for stable Rust wire types.
• Support rolling upgrades where old Rust clients and all Java clients continue to use WebSocket.
• Configure accepted transports per controller surface so browser MCP, Rust runtime control, and standalone discovery can evolve independently.
• Let portal-view discover the gateway’s current end-to-end MCP candidates at runtime instead of baking deployment readiness into the UI bundle.
• Bound memory, stream concurrency, message size, and validation work before accepting untrusted input.
• Provide explicit rollout, fallback, observability, and rollback behavior.
• Measure JSON over WebTransport and rkyv over WebSocket so codec and transport effects are isolated.
• Require measured improvement before changing any default.

Non-Goals

• Do not replace /ctrl/mcp or its JSON-RPC payload contract.
• Do not describe a private rkyv encoding as standard MCP.
• Do not implement browser-side rkyv or require a WebAssembly decoder.
• Do not translate WebSocket to WebTransport or JSON to rkyv in the first gateway implementation.
• Do not require every allowed codec to use every transport.
• Do not require Java or other non-Rust runtimes to implement rkyv.
• Do not send general metrics or traces to controller-rs in the first release.
• Do not claim zero allocation or zero head-of-line blocking.
• Do not solve multi-replica command routing in this change.
• Do not automatically switch an established session between transports.
• Do not infer WebTransport availability from the HTTP version used to load the page or an unrelated UI resource.
• Do not use unchecked rkyv access for network data.
• Do not enable WebTransport by default in production deployments.

Options Considered

WebTransport is justified only if independent streams, HTTP/3 integration, or browser support provide value beyond raw QUIC or multiple WebSockets. The runtime implementation spike must compare those alternatives rather than treating WebTransport plus rkyv as one indivisible decision.

Decision

Implement the layered profile model with these constraints:

1. Keep /ws/microservice unchanged, enabled by default, and available throughout migration. It may be disabled for the runtime surface only after that surface’s client-fleet and network compatibility gates pass.
2. Keep /ctrl/mcp as MCP-style JSON-RPC regardless of transport.
3. Add https://<controller-authority>/wt/microservice over HTTP/3 and QUIC and support both runtime JSON and runtime rkyv profiles on it.
4. Permit the runtime rkyv profile over WebSocket binary frames for isolation testing, without changing the legacy JSON default.
5. Add browser MCP over WebTransport only after the gateway router and browser ticket-authentication flow pass their release gates.
6. Negotiate one immutable wire profile before decoding non-legacy payloads.
7. Use reliable streams for all initial WebTransport behavior; datagrams remain disabled.
8. Preserve the current ControllerCommand correlation, timeout, response, and connection-ID-guarded cleanup semantics inside controller-rs. The bounded admission controls in this design intentionally replace unbounded pending-state admission; preserving semantics does not mean preserving the absence of those limits.
9. Keep arbitrary tool arguments and results as bounded UTF-8 JSON bytes where the existing runtime contract is dynamic.
10. Keep the gateway payload-opaque in the initial WebTransport implementation; cross-transport and cross-codec translation require a separate decision.
11. Advance beyond experimental status only after compatibility, security, deployment, and benchmark gates pass.

High-Level Architecture

browser MCP path
  portal-view
    -> MCP JSON codec
    -> selected WebSocket or WebTransport adapter
    -> light-gateway matching transport router
    -> same transport and MCP JSON profile
    -> controller-rs /ctrl/mcp
    -> CommandRouter

runtime control path
  light-fabric portal-registry
    -> logical runtime-control messages
    -> selected JSON or rkyv codec
    -> selected WebSocket or WebTransport adapter
    -> controller-rs shared registration and command services

controller command path
  CommandRouter
    -> ControllerCommand channel
    -> selected live runtime session driver

The transport drivers must call the same controller service functions for:

• JWT identity checks;
• registration persistence;
• instance insertion and removal;
• portal and discovery notifications;
• metadata updates;
• pending-command completion and timeout handling;
• disconnect cleanup.

Transport- or codec-specific code must not duplicate those business rules.

Gateway and BFF Routing

The current light-gateway WebSocket router is a payload-opaque HTTP/1 upgrade proxy. It resolves a service from headers, query parameters, or path-prefix configuration, applies authorization and connection limits, selects a discovered upstream, and lets Pingora tunnel the upgraded connection. It does not terminate MCP or translate JSON-RPC messages.

The WebTransport router should preserve that payload-opaque property, but it cannot reuse the HTTP/1 tunnel implementation. It needs an HTTP/3/QUIC listener and must act as a WebTransport server toward the browser and as a WebTransport client toward controller-rs.

The reusable gateway boundary is a transport-neutral route resolver containing:

• path-prefix, header, and query-based service selection;
• discovery and direct-registry target selection;
• authentication and access-control decisions;
• connection and admission limits;
• routing-header cleanup, metrics, and reload behavior.

The WebSocket and WebTransport routers use that resolver but own separate listener, handshake, timeout, and proxy state. The initial WebTransport router:

1. accepts an authenticated WebTransport CONNECT request;
2. selects the controller using the shared route resolver;
3. opens an upstream WebTransport session using the same wire profile;
4. maps the downstream MCP or runtime-control stream to its upstream peer;
5. maps each additional reliable stream with the same direction and role;
6. propagates backpressure, stream resets, draining, and session close reasons;
7. rejects datagrams because version 1 does not define a datagram mapping.

Path-based routing, BFF authentication, and profile negotiation are encrypted inside HTTP/3, so a generic UDP forwarder cannot replace this router. A pure QUIC layer-4 path is acceptable only for deployments with a fixed upstream that do not need BFF policy or path-based service selection.

For the first implementation, transport must match across the gateway:

WebSocket client -> WebSocket router -> WebSocket controller endpoint
WebTransport client -> WebTransport router -> WebTransport controller endpoint

Supporting WebSocket-to-WebTransport, WebTransport-to-WebSocket, JSON-to-rkyv, or rkyv-to-JSON would turn the gateway into an application relay. That requires message decoding, identity and cancellation mapping, independent buffering on both sides, and a separate design and benchmark.

The current Pingora integration has no HTTP/3 or QUIC listener. The experimental WebTransport service therefore runs alongside the existing Pingora TCP service and shares only routing, policy, configuration, and observability components. It must not delay or destabilize the existing HTTPS/WebSocket listener when the feature is disabled or fails to initialize.

Browser Transport Capability Discovery

The browser cannot discover the controller transport directly. It can detect its local WebTransport API, but it cannot infer the selected controller, the gateway-to-controller transport, enterprise UDP policy, or current route readiness. light-gateway therefore exposes an authenticated HTTPS capability resource on the controller BFF authority. That authority is same-origin by default and is resolved as defined in Browser BFF Authority:

GET /ctrl/mcp/capabilities

An example response is:

{
  "revision": "gw-42:controllers-17",
  "generatedAt": "2026-07-15T14:00:00Z",
  "expiresAt": "2026-07-15T14:00:30Z",
  "wireProfile": "light-controller-mcp-json-v1",
  "policy": "preferWebTransport",
  "candidates": [
    {
      "transport": "webtransport",
      "endpoint": "/ctrl/mcp",
      "ticketEndpoint": "/ctrl/mcp/ticket",
      "ready": true
    },
    {
      "transport": "websocket",
      "endpoint": "/ctrl/mcp",
      "negotiation": "legacy",
      "ready": true
    }
  ],
  "maxAgeSeconds": 30
}

revision is an opaque aggregate revision that changes whenever gateway policy, listener or router readiness, the eligible target set, or any target’s controller capability revision changes. generatedAt and expiresAt use UTC. The gateway also returns ETag: "<revision>". Version 1 always returns a complete 200 representation after HTTP-cache expiry rather than a bodyless 304, because the body carries an absolute expiry. Conditional revalidation requires a later contract for refreshing that absolute expiry without retaining a stale body.

The response is gateway-derived deployment state, not a copy of browser feature detection or raw controller configuration. A candidate is ready only when:

• the corresponding gateway listener and router are enabled and healthy;
• authentication, ticket issuance when applicable, and the allowed wire profile are configured;
• the shared route resolver has a healthy controller target that accepts the same transport and profile; and
• a recent same-transport synthetic probe has verified the gateway-to-controller leg.

Controller support is not inferred from route naming, a generic health response, or deployment-wide configuration. Every controller instance exposes an authenticated internal capability resource over its existing HTTPS listener:

GET /internal/controller/capabilities

It returns instanceId, an opaque revision, generation and expiry timestamps, listener readiness, and the enabled transport/profile set for each of mcp, runtime, and standaloneDiscovery. It also reports draining state. The revision changes whenever startup configuration, listener readiness, or draining state changes; a process restart creates a new instanceId. For example:

{
  "schemaVersion": 1,
  "instanceId": "controller-7f8c",
  "revision": "17",
  "generatedAt": "2026-07-15T14:00:00Z",
  "expiresAt": "2026-07-15T14:00:15Z",
  "draining": false,
  "listeners": {
    "websocket": { "ready": true },
    "webtransport": { "ready": true }
  },
  "surfaces": {
    "mcp": [
      {
        "transport": "websocket",
        "wireProfiles": ["light-controller-mcp-json-v1"]
      },
      {
        "transport": "webtransport",
        "wireProfiles": ["light-controller-mcp-json-v1"]
      }
    ],
    "runtime": [
      {
        "transport": "websocket",
        "wireProfiles": ["light-controller-runtime-json-v1"]
      },
      {
        "transport": "webtransport",
        "wireProfiles": [
          "light-controller-runtime-json-v1",
          "light-controller-runtime-rkyv-v1"
        ]
      }
    ],
    "standaloneDiscovery": [
      {
        "transport": "websocket",
        "wireProfiles": ["light-controller-runtime-json-v1"]
      }
    ]
  }
}

Unknown schema versions, expired responses, duplicate combinations, a transport whose listener is not ready, or a draining instance are ineligible for new sessions. The resource is available only to the gateway through the deployment’s approved service credential or mTLS identity; browser credentials and browser connection tickets are not accepted.

For each candidate, the gateway intersects that instance declaration with its own policy and route configuration, then runs a bounded transport-native probe against a dedicated gateway-authenticated probe resource on the same controller listener. The probe requests one surface and wire profile, completes transport and profile negotiation, returns the controller capability revision, and closes. It does not register a runtime, create an MCP session, enqueue a command, or mutate controller state. Probe credentials, intervals, timeouts, concurrency, and logs are bounded and independently configurable.

Because the first gateway implementation does not relay across transports, it must never advertise a WebSocket candidate backed only by a WebTransport controller endpoint, or the reverse. During a rolling controller upgrade, the gateway builds a candidate-specific eligible target pool from per-instance capability and probe results. It advertises the candidate only when that pool is non-empty and pins each accepted session to a target from that pool for the session lifetime. An instance that becomes stale, unready, or draining is removed from new-session selection and changes the aggregate capability revision; an existing session follows the draining rules rather than being silently moved to another target.

The response uses Cache-Control: private, max-age=30 or a shorter configured value and Vary: Origin, Cookie where those fields affect authorization or candidate policy. portal-view refreshes it after a failed candidate attempt or cache expiry. A normal refresh or an authenticated runtime configuration signal may reveal a new aggregate revision; when it does, the client discards candidates from the old revision. Capability discovery reduces expected failures but does not replace the actual handshake; a network path can change after the response is generated.

Capability-fetch failure does not authorize a blind transport attempt. In auto mode:

• 401 or 403 is an authentication or authorization failure; do not try a transport and wait for the login state to change;
• a malformed or semantically invalid response is Internal; reject it and do not infer a candidate;
• timeout, network failure, 429, or 5xx may use a still-fresh previously validated capability response, but otherwise no session is attempted and the client retries discovery with the existing jittered exponential backoff; and
• 404 or 501 means the gateway does not implement capability discovery. The auto-mode UI fails closed; an explicitly forced websocket build override is the compatibility escape for an old gateway.

Deploy the capability resource before deploying an auto-mode UI that depends on it. These rules prevent a transient gateway failure from silently weakening a requireWebTransport policy or guessing that legacy WebSocket is acceptable.

Browser BFF Authority

All browser controller resources use one controller BFF authority and ingress path prefix. portal-view resolves it with the same shared helper for capability fetch, ticket issuance, WebSocket, and WebTransport:

1. use the configured VITE_API_BASE_URL, including its path prefix, when it is non-empty; otherwise
2. use window.location.origin and the deployment’s normal ingress prefix.

Capability and ticket requests remain HTTPS requests with credentials: include and the existing CSRF rules. The WebSocket URL changes only the scheme to ws or wss; the WebTransport URL remains https. Redirects to a different authority are rejected for ticket issuance and WebTransport establishment.

Same-origin deployment is the version 1 production recommendation. A deployment that intentionally uses a different API authority must explicitly provide all of the following before browser WebTransport is ready:

• credentialed CORS for capability and ticket HTTPS requests with an explicit portal Origin, never *;
• compatible secure cookie Domain and SameSite attributes for the authenticated BFF requests;
• the existing CSRF validation on ticket issuance;
• an Origin allowlist for WebSocket and WebTransport establishment; and
• browser and integration tests covering the exact portal and API authorities.

If any cross-origin prerequisite is absent, capability readiness is false and the UI fails closed instead of constructing URLs from mixed authorities.

The HTTP version used for the page navigation or an ordinary API request is not a selection signal. A page loaded over HTTP/2 can open a separate HTTP/3 WebTransport session, while an HTTP/3 page load does not prove that WebTransport CONNECT, ticket authentication, or the gateway-to-controller QUIC leg works. nextHopProtocol may be recorded as bounded diagnostic context only.

The gateway may advertise HTTP/3 for ordinary HTTPS traffic, and the browser may select it automatically. portal-view does not force the HTTP version of normal fetches. Only the WebTransport session requires the HTTP/3/QUIC behavior defined by this design through requireUnreliable: true and the resulting reliability check.

WebTransport Protocol Maturity

At the time of this design update, WebTransport over HTTP/3 is still an active IETF Internet-Draft. Draft versions can use different HTTP/3 settings and wire codepoints. The selected Rust library must be verified against the exact draft implemented by both peers and any intermediary.

Generic HTTP/3 support is not sufficient. The current WebTransport draft also requires extended CONNECT, WebTransport settings, HTTP/3 datagrams, QUIC datagrams, and stream-reset support. End-to-end interoperability must be tested through every supported load balancer or proxy.

The required Phase 0 interoperability target is draft-ietf-webtrans-http3-16. The 2026-07-15 spike did not find a supportable tuple for that target: the tested Rust crates use legacy WebTransport-over-HTTP/3 codepoints, and the tested Chrome did not implement the required CONNECT header, selected-protocol, and reliability API contract. Draft 16 is therefore a target, not a verified baseline. A future implementation must pin and record the exact WebTransport draft, Rust library version, browser version, and intermediary behavior in the release notes and compatibility matrix. A change to any of them requires rerunning the interoperability gate.

Endpoint and Wire Profile Negotiation

The WebTransport resources are:

https://<controller-authority>/wt/microservice  # runtime control
https://<gateway-authority>/ctrl/mcp             # browser MCP through BFF

The corresponding controller-side MCP resource remains /ctrl/mcp. The path identifies the application surface; it does not select JSON versus rkyv.

Clients offer one or more wire profiles such as:

light-controller-mcp-json-v1
light-controller-runtime-json-v1
light-controller-runtime-rkyv-v1

For WebTransport, the client sends profiles through the draft’s WT-Available-Protocols header and the server confirms one with WT-Protocol. Browser JavaScript supplies this offer with WebTransportOptions.protocols; it must not attempt to set WT-Available-Protocols directly in WebTransportOptions.headers. After ready resolves, the browser verifies that the selected transport.protocol is the single expected MCP profile.

For new WebSocket profiles, the client and server use Sec-WebSocket-Protocol. Existing JSON WebSocket clients that do not offer a wire profile retain their current behavior. The existing browser CSRF value in this header is authentication metadata, not a wire profile. The gateway uses the following deterministic rules:

1. Parse all offered tokens instead of selecting the first token.
2. Extract and validate exactly one csrf.<value> token when the browser path requires it.
3. Remove the CSRF token before forwarding a negotiated profile offer upstream.
4. Forward only recognized, endpoint-allowed wire-profile tokens.
5. Return only the profile selected by the upstream controller for a negotiated session; never echo a CSRF token as the selected wire profile.
6. Preserve the current CSRF-only behavior for legacy browser clients that do not offer a wire profile.

A server rejects a new negotiated session when no common allowed profile exists or when the selected profile is not permitted on that endpoint and transport. An explicit negotiated candidate never treats an absent selected token as a successful negotiation. Legacy JSON is represented by an explicit client candidate with negotiation: legacy; it sends no wire-profile token and is the only candidate allowed to accept the existing no-profile response.

The negotiated token selects the complete application wire profile, including:

• application semantics and codec;
• frame header layout;
• numeric message kinds;
• archived type definitions;
• rkyv version and format-control features;
• validation and size limits;
• logical channel roles and error semantics.

Transport-specific details such as WebSocket frames versus WebTransport streams remain the responsibility of the session adapter. A profile token must not encode websocket or webtransport; the same profile may be allowed on either transport by server policy.

Supporting a new incompatible wire shape requires a new profile token. During a rolling upgrade, the controller should support the current and immediately previous wire-profile versions.

Runtime Authentication and Registration

Every non-legacy negotiated runtime session carries the service JWT in its transport handshake:

Authorization: Bearer <service-jwt>

For WebTransport this is the CONNECT request. For WebSocket it is the HTTP upgrade request. The controller performs signature, issuer, audience, expiry, and other token checks before accepting application messages. The accepted claims are retained only for the pending session and are bound to the registration that follows.

The current WebSocket path continues to carry the JWT in service/register.params.jwt; that contract is unchanged. The runtime JSON profile retains this field on WebTransport so its JSON bytes and behavior remain comparable with the legacy path. When both handshake and registration JWTs are present, they must identify the same service and environment; a mismatch closes the session.

The runtime rkyv profile carries no JWT in ClientHelloV1 and therefore always requires handshake authentication on WebSocket and WebTransport.

The negotiated registration sequence is:

1. The client sends the WebSocket upgrade or WebTransport CONNECT request with the service JWT and offered wire profiles.
2. The controller validates the JWT and selects an endpoint-allowed wire profile before completing the handshake.
3. The controller rejects the handshake if authentication fails or no allowed profile can be selected; otherwise it accepts the transport session.
4. The client opens the session-control stream within the independent registration deadline.
5. The controller reads and validates ClientHelloV1.
6. It matches service_id and environment to the authenticated JWT claims using the same identity rules as the WebSocket path.
7. It validates address syntax, port, tags, and all other registration fields. Version 1 does not perform an active reachability probe during registration.
8. It persists registration and inserts the live instance.
9. It sends ServerHelloV1 containing runtime_instance_id and connection settings.
10. It permits command and event streams only after the acknowledgement is sent.

An invalid JWT, identity mismatch, or invalid registration closes the session. The client must not fall back to WebSocket for these failures because fallback would mask an authentication or configuration error.

Authorization headers, JWTs, and registration payloads must be redacted from normal logs and metrics labels.

Browser and BFF Authentication

The current browser WebSocket path depends on behavior that does not carry over to WebTransport:

• the browser automatically includes the accessToken cookie in the WebSocket upgrade;
• portal-view offers csrf.<token> through Sec-WebSocket-Protocol;
• the BFF validates the cookie and CSRF value and injects the authenticated bearer token into the upstream WebSocket handshake.

Browser WebTransport requests use Fetch credentials mode omit; cookies and HTTP authentication are not sent automatically. The WebTransport profile token also has real protocol-negotiation semantics and must not be overloaded with a CSRF secret.

The browser path therefore uses a short-lived, single-use connection ticket. Version 1 preserves the controller’s current Bearer-token validation contract; it does not introduce a second gateway identity envelope:

1. An authenticated browser sends POST /ctrl/mcp/ticket through the existing HTTPS BFF path with its normal cookies and X-CSRF-TOKEN protection.
2. The BFF validates or refreshes the current login exactly as it does for other protected HTTPS requests.
3. The BFF creates an opaque, cryptographically random ticket bound to the authenticated subject, roles, client, allowed Origin, /ctrl/mcp, selected wire profile, token expiry, and a nonce.
4. The BFF stores the ticket in a bounded replay cache together with the current validated or refreshed access token, its expiry, and the authenticated principal. The record has a configurable lifetime no greater than 60 seconds and is consumed atomically on first use. The access token is never placed in the browser-visible ticket. If the replay cache cannot prove a successful write with the required TTL, ticket issuance fails closed.
5. The browser opens WebTransport and supplies Authorization: WebTransport <ticket> in the CONNECT request headers.
6. The gateway validates the Origin allowlist, consumes the ticket, restores the authenticated principal, applies normal access control, and establishes the upstream WebTransport session.
7. The gateway injects the retained access token as Authorization: Bearer <access-token> in the upstream controller handshake, exactly as the current WebSocket BFF path does. The controller independently validates issuer, audience, expiry, required portal.r scope, subject, and client identity. The browser ticket is never forwarded to the controller.
8. Gateway role-based policy uses the restored principal. It must not assert roles to the controller until a separately reviewed controller claim-mapping contract exists.

The replay cache is security-sensitive credential storage. It must restrict read access to the ticket consumer, encrypt or equivalently protect records at rest and in transit, redact all values, and delete the complete record on consumption or expiry. A cache implementation that cannot provide those properties is not eligible for browser WebTransport.

Ticket consumption also fails closed when the replay cache is unavailable, degraded, returns an ambiguous result, or cannot perform atomic consume. It must not fall back to a process-local cache or accept a self-contained ticket without replay protection.

All gateway nodes must synchronize UTC through the deployment’s approved time service and expose clock-synchronization health. The cache TTL is authoritative, and each record also carries an absolute ticket expiry and access-token expiry; the consumer enforces the earliest deadline. A positive expiry grace period is not allowed because it could extend the 60-second hard maximum. If measured clock error exceeds the configured readiness threshold, ticket issuance and consumption fail closed until synchronization is healthy.

Target browser support for WebTransportOptions.headers, protocols, requireUnreliable, the selected protocol, and the resulting reliability value is a release gate. The browser constructs the session with the ticket header, protocols: ["light-controller-mcp-json-v1"], and requireUnreliable: true. After connection it requires reliability == "supports-unreliable"; a reliable-only connection is not accepted as the HTTP/3/QUIC profile described by this document. Do not put the ticket in a URL query parameter as a compatibility fallback because URLs are commonly retained in proxy, access, and diagnostic logs. If the target browser cannot meet this contract, browser WebTransport remains disabled or falls back according to its configured mode.

POST /ctrl/mcp/ticket terminates in the authenticated HTTPS BFF handler before route-prefix processing. Only a WebTransport CONNECT request for /ctrl/mcp enters the WebTransport router. Method-aware tests must prove that ticket POSTs cannot be proxied, upgraded, or rejected by the session router.

In a multi-replica gateway deployment, ticket issuance and consumption require a shared replay cache or a proven affinity mechanism covering both requests. A self-contained signed ticket without replay protection is insufficient because it can be reused during its validity window.

The accepted WebTransport session must not outlive either the access-token expiry or a configurable maximum session duration. The gateway arms that deadline when it consumes the ticket, closes the session at the deadline, and requires a new ticket before reconnecting. Immediate authorization revocation is guaranteed only when the deployment provides a concrete revocation signal or introspection mechanism consumed by the gateway. Without one, version 1 claims expiry enforcement, not immediate revocation. Ticket values, user access tokens, CSRF values, and upstream authorization headers are always redacted.

Logical Channels and Transport Mapping

Version 1 uses reliable delivery only. Applications operate on logical channels; the transport adapter decides whether those channels share a connection or use independent streams.

WebSocket preserves message boundaries but provides one ordered data path per direction. WebTransport streams are ordered byte streams and do not preserve application message boundaries. Their adapters must apply the framing defined by the negotiated wire profile.

The rkyv over WebSocket profile isolates codec cost for measurement; it does not provide independent command and event streams. Avoid claiming WebTransport multiplexing benefits for that combination.

MCP Session Channel

The browser and controller exchange the existing MCP JSON-RPC messages without semantic translation. WebSocket carries one JSON-RPC message per text frame. WebTransport carries the same messages on one long-lived bidirectional stream using the JSON framing below. Server notifications share that stream.

The first MCP request remains initialize according to the current controller contract. A second MCP stream in the same WebTransport session is a protocol violation in version 1.

Runtime Session Control Channel

For WebTransport, the runtime opens this stream first. Registration must be its first frame. The stream remains open for the session and carries low-volume ordered control messages. Only one runtime session-control stream is allowed.

For WebSocket, these logical messages continue to share the existing runtime connection. Registration and acknowledgement ordering remain unchanged.

Runtime Command Channels

On WebTransport, the controller opens a new bidirectional stream for each command. It writes one command request, closes its send direction, reads one command response, and then releases the stream. JSON and rkyv profiles use the same stream lifecycle with different payload framing.

On WebSocket, commands and responses remain messages on the existing connection. The request ID is mandatory on every transport. It preserves audit correlation, timeout handling, and late-response detection.

Command concurrency remains bounded by controller configuration and negotiated limits. A command that cannot obtain transport capacity before its dispatch deadline fails with a transport error; it must not wait indefinitely.

Runtime Event Channel

On WebTransport, the runtime opens one unidirectional event stream after registration. It carries framed asynchronous notifications separately from command responses, so log traffic cannot sit in front of a command response in the same application stream. On WebSocket, event messages remain on the shared ordered connection.

The event path is reliable and flow-controlled. It is not fire-and-forget. The runtime must use a bounded outbound event queue:

• control and lifecycle notifications are never silently dropped;
• log records may be dropped at the source when their queue is full;
• every dropped-log interval emits a counter and a sequence gap visible to the controller;
• a persistently blocked event stream is reset and the session is reconnected.

The controller continues to translate accepted runtime notifications to the existing external MCP notification shape.

JSON Wire Profile Framing

Existing JSON WebSocket behavior is unchanged: one UTF-8 JSON-RPC value is sent in each text frame and binary frames are rejected for legacy sessions.

On WebTransport, each JSON message is encoded as:

4-byte unsigned big-endian payload length
exactly that many UTF-8 JSON bytes

The length excludes the four-byte prefix. The receiver rejects a value above the endpoint-specific message limit before allocating, reads exactly the declared length with a deadline, validates UTF-8, and parses exactly one JSON value. EOF before the complete payload is a truncated-message error. Zero-length messages and trailing non-whitespace bytes are invalid.

This framing applies to both light-controller-mcp-json-v1 and light-controller-runtime-json-v1 over WebTransport. It is part of those wire profiles, not a generic property of WebTransport.

rkyv Binary Frame Format

Every light-controller-runtime-rkyv-v1 message begins with a fixed 16-byte header encoded without rkyv:

The payload immediately follows the header and contains exactly one archived root object. The payload length excludes the header. WebSocket/TLS and WebTransport/QUIC already provide cryptographic integrity, so the application frame does not add a checksum.

The receiver must:

1. Read the complete header with a deadline.
2. Validate magic, version, flags, message kind, and reserved bytes.
3. Reject a length above the limit before allocating the payload buffer.
4. Allocate an appropriately aligned buffer and read exactly the declared payload length.
5. Validate the archived root with bytecheck through a safe rkyv API.
6. Apply semantic limits such as string length, tag count, and allowed command names.
7. Copy only the fields that must survive the receive buffer or cross an asynchronous boundary.

On WebSocket, one binary message contains exactly one header and payload. On WebTransport, EOF before the complete payload is a truncated-frame error. Extra bytes are the start of the next frame only on long-lived control or event streams.

Message Kind Registry

Version 1 reserves these message kinds:

Unknown kinds are rejected before archived access. Adding a new kind does not change an existing archived root type. Existing version 1 root types are immutable after release.

runtime-rkyv-v1 Wire Types

The type names below describe shared wire types for light-controller-runtime-rkyv-v1, not the existing application structs in either repository. Field order is part of the archived schema and is frozen when that profile is released.

Registration Types

ClientHelloV1 contains:

The JWT is not present in ClientHelloV1; it comes from the authenticated WebSocket upgrade or WebTransport CONNECT request.

ServerHelloV1 contains:

WireTagV1 contains UTF-8 key and value strings. Each is limited to 256 bytes. Duplicate keys are invalid.

Metadata and Discovery Types

MetadataUpdateV1 contains optional service_version, application_protocol, port, and complete replacement tags fields. The same limits and validation rules as registration apply. None means no change. Some(empty tags) clears all tags; empty strings and port zero are invalid.

DiscoveryRequestV1 contains:

DiscoveryResponseV1 contains the request ID, an optional DiscoverySnapshotV1, and an optional WireErrorV1. Exactly one of snapshot or error must be present.

DiscoveryChangedV1 contains one DiscoverySnapshotV1. A discovery snapshot contains the requested service ID, optional environment and application protocol filters, and a bounded vector of DiscoveryNodeV1 values. Each node contains the current runtime instance ID, service identity, environment, version, application protocol, address, port, tags, connection timestamps, and connected state needed by the existing discovery contract.

The initial maximum number of nodes in one snapshot is 10,000. A larger result is a resource-limit error rather than a partially serialized snapshot. The frame-size limit also applies, and the receiver enforces whichever limit is reached first.

Liveness and Error Types

PingV1 and PongV1 contain the same u64 nonce and signed 64-bit Unix millisecond timestamp. A pong with an unexpected nonce does not satisfy the heartbeat.

SessionErrorV1 and command failures use WireErrorV1:

Error messages must not contain JWTs, authorization headers, or unredacted sensitive payloads.

ServerDrainingV1 contains a signed 64-bit Unix millisecond drain deadline and a safe reason string limited to 1,024 bytes. A client stops issuing new control requests, lets active command streams finish until that deadline, and reconnects after the server closes the session.

Command and Notification Types

CommandRequestV1 contains a request ID limited to 128 bytes, a tool name limited to 256 bytes, and arguments_json. CommandResponseV1 contains the same request ID, completion timestamp, and exactly one of result_json or WireErrorV1.

RuntimeNotificationV1 contains a method name limited to 256 bytes, params_json, and monotonically increasing u64 sequence number for the current event stream. Sequence numbers restart at zero on a new registered session. A gap tells the controller that the runtime dropped one or more notifications before transmission.

All *_json fields are UTF-8 byte vectors containing exactly one valid JSON value. Their content is validated only after the enclosing archive and byte limits pass.

Version 1 deliberately uses numeric operation and message-kind fields rather than a shared archived envelope enum. New independent kinds can be registered without changing the layout of existing roots. Unknown numeric values are errors; they are never mapped to a default operation.

rkyv Wire Profile

The shared wire crate owns the only rkyv dependency used for this protocol. Both controller and runtime consume the same published or otherwise pinned crate version.

Version 1 fixes these format choices:

rkyv major version: 0.8
endianness: little_endian
alignment: aligned
relative pointer width: pointer_width_32
validation: bytecheck enabled
UUID integration: uuid-1 enabled

Cargo feature unification must not silently change this profile. CI checks cargo tree -e features for the controller and runtime release graphs and rejects conflicting endianness, alignment, or pointer-width features.

Payloads are read directly into an aligned buffer. Network input always uses validated access such as rkyv::access; unchecked access and unchecked deserialization are prohibited.

Wire types must:

• use fixed-width integers instead of usize or isize;
• represent UUIDs consistently through the shared crate;
• represent timestamps as signed 64-bit Unix milliseconds;
• use sorted key-value vectors instead of unordered maps when deterministic bytes are required;
• avoid recursive or attacker-controlled deeply nested structures;
• avoid references to application structs whose layout can change independently;
• define semantic maximums for strings, lists, tags, and JSON byte fields.

Validation proves that bytes form a structurally valid archive. It does not prove that a service ID, address, port, tool name, or authorization decision is valid. Normal application validation remains mandatory.

Archived references borrow the receive buffer. They must not be stored in controller state, moved into a spawned task, or held across an .await that can outlive the buffer. Values needed by persistence, event publication, or the existing JSON/MCP surfaces are converted into owned application types.

This boundary means the design is not zero-allocation end to end. It avoids parsing and allocation only where handlers can consume archived values directly.

Dynamic JSON Payloads

The existing command layer includes dynamic MCP arguments and results. Version 1 preserves them as bounded UTF-8 JSON byte fields inside otherwise typed wire messages:

CommandRequestV1
  request_id
  tool_name
  arguments_json

CommandResponseV1
  request_id
  completed_at
  result_json or structured error

RuntimeNotificationV1
  method
  params_json
  sequence

The receiver validates UTF-8 and parses JSON only when the existing handler requires serde_json::Value. This preserves current command extensibility and makes the performance limitation explicit. A future wire-profile version may add typed payload kinds for measured hot paths without changing version 1.

Schema Ownership and Evolution

Create a dependency-light shared crate, referred to here as controller-wire, containing:

• wire-profile identifiers and compatibility metadata;
• the JSON length-prefix encoder and decoder;
• the 16-byte rkyv frame header encoder and decoder;
• runtime protocol and message-kind constants;
• immutable v1 archived root types;
• semantic validation helpers;
• golden JSON and rkyv encoded fixtures;
• compatibility tests.

The crate must not depend on controller-rs, portal-registry, Tokio, Axum, or a particular WebTransport implementation.

The existing duplicate registration structs in controller-rs and portal-registry must not become independent rkyv schemas. Each side converts between its application types and the shared wire types.

Versioning rules are:

• never add, remove, reorder, or change fields in a released archived root;
• never add a variant to a released archived enum;
• add a new message kind for a new independent payload;
• add a new wire-profile major version for an incompatible replacement;
• keep golden bytes for every released root type;
• test old-client/new-server and new-client/old-server negotiation;
• keep at least the current and previous wire-profile versions during rolling upgrades.

Transport-Neutral Application Boundary

controller-rs already stores an mpsc::Sender<ControllerCommand> in each live instance. Preserve this boundary. Application services exchange owned logical messages and lifecycle events without importing Axum WebSocket, Tungstenite, QUIC, WebTransport, or rkyv types.

The useful abstractions are deliberately small:

• an application session for registration, commands, responses, notifications, authentication state, and cleanup;
• a wire-profile adapter that encodes and decodes owned logical messages;
• a transport session that opens or accepts logical channels and moves bounded encoded messages;
• transport capabilities describing independent streams and datagrams.

A broad application-wide Connection trait is not required. The application must not assume every transport supports independent streams, and the transport must not inspect MCP methods or runtime command payloads.

On the Rust client, replace the WebSocket-specific outbound mpsc::Sender<tungstenite::Message> boundary with a logical outbound enum. The selected wire-profile adapter converts that enum to bounded bytes. The selected transport adapter then maps those bytes to WebSocket messages or WebTransport streams. Codec selection must not occur inside the transport driver.

On the controller, refactor the current WebSocket handlers so all transports and codecs call shared functions for registration, inbound messages, pending command completion, notification publication, and disconnect cleanup.

The gateway is intentionally below this application boundary. Its initial WebSocket and WebTransport routers forward payload bytes and do not instantiate the MCP or runtime codecs.

All supported profile and transport adapters must produce the same observable application behavior for:

• registration acknowledgement;
• runtime_instance_id assignment;
• metadata and discovery updates;
• command results and timeouts;
• notifications;
• liveness timestamps;
• disconnect events and pending-command failure.

Expected Implementation Surfaces

The initial implementation is cross-repository work.

In controller-rs, the main change surfaces are:

• Cargo.toml for the selected HTTP/3/WebTransport, JSON framing, and wire dependencies;
• src/config.rs for listeners, allowed profile pairs, and limits;
• src/lib.rs and src/tls.rs for coordinated TCP and UDP listeners;
• an authenticated internal capability handler and transport-native probe resources for per-instance transport/profile readiness;
• src/routes/microservice.rs to extract shared session behavior from the WebSocket driver;
• src/routes/mcp.rs to extract shared MCP behavior for WebSocket and WebTransport session adapters;
• src/auth.rs to separate token verification from post-CONNECT registration identity matching;
• src/state.rs, src/types.rs, and src/command_router.rs to preserve the existing command channel and connection-ID cleanup rules;
• integration tests for profile, transport, and fallback parity.

In light-fabric, the main change surfaces are:

• crates/portal-registry/Cargo.toml;
• crates/portal-registry/src/client.rs for transport-neutral logical queues plus independent codec and transport selection;
• crates/portal-registry/src/protocol.rs for conversion to the shared wire crate rather than a second archived schema;
• crates/light-runtime/src/config.rs and runtime.rs for client selection, URL derivation, TLS assets, and fallback settings;
• frameworks/light-pingora/src/websocket.rs to extract reusable route resolution without changing existing WebSocket behavior;
• a WebTransport router module and UDP/HTTP3 service with transport-specific limits and stream relay;
• apps/light-gateway/src/main.rs for coordinated TCP and UDP startup, readiness, reload, and shutdown;
• BFF ticket issuance, bounded replay-cache storage, Origin validation, and restoration of the authenticated principal;
• runtime handlers and tests for command, discovery, notification, heartbeat, reconnect, and draining parity.

In portal-view, the main change surfaces are:

• the controller context for transport preference and serial fallback;
• an authenticated capability client for /ctrl/mcp/capabilities, with the optional VITE_CONTROLLER_TRANSPORT override;
• one controller-BFF authority resolver shared by capability, ticket, WebSocket, and WebTransport URLs;
• an MCP session interface shared by WebSocket and WebTransport clients;
• the HTTPS ticket request and WebTransport CONNECT header;
• WebTransport JSON framing and notification handling;
• browser capability, authentication, reconnect, and cleanup tests.

Deployment repositories must add UDP exposure for each enabled WebTransport listener and router. light-4j requires compatibility tests but no rkyv or WebTransport implementation for the initial release.

Initial Limits

All limits are configurable, but the server must start with finite defaults.

Additional per-IP, per-user, per-Origin, and per-service session and ticket limits must be set from load-test results before internet-facing deployment. A length or count limit is checked before allocation or iteration wherever possible.

The command queue capacity, in-flight-command limit, and concurrent-stream limit are separate controls. The existing COMMAND_CHANNEL_CAPACITY describes a bounded queue; it must not be reused as proof that pending commands or open streams are bounded. Admission reserves an in-flight slot before inserting a pending response entry or opening a command stream. When either the per-session or global limit is reached, dispatch fails immediately with Resource limit and does not enqueue or insert pending state.

Both WebSocket and WebTransport MCP handlers explicitly enforce the 16 MiB MCP application-message limit. The implementation configures the WebSocket frame/message limit rather than relying on a framework default, and the WebTransport length prefix is rejected before allocation when it exceeds the same limit.

Liveness, Errors, and Cleanup

Transport-level TCP or QUIC activity is not sufficient to prove that the application loop is healthy. The runtime sends the profile-specific ping message on the session-control channel and expects its matching pong within the heartbeat deadline. For rkyv these are PingV1 and PongV1; the JSON profile uses the existing JSON-RPC liveness messages. Any valid application message also updates the instance’s last-seen time.

Browser MCP sessions retain the existing MCP ping behavior and are also subject to the gateway’s idle and maximum-connection-duration limits.

Errors are classified as:

• Unavailable: UDP blocked, timeout, no route, or listener unavailable;
• Unsupported: the transport, wire profile, or allowed profile/transport pair is not supported;
• Establishment failed: the browser reported an opaque WebTransport failure before the session became ready and did not expose a more specific cause;
• Unauthorized: JWT is missing, invalid, or expired;
• Invalid registration: authenticated claims and registration disagree;
• Protocol violation: invalid frame, logical channel, ordering, or message kind;
• Resource limit: frame, queue, session, or stream limit exceeded;
• Internal: persistence or controller failure.

A malformed WebTransport command stream is reset without immediately killing a healthy session when isolation is safe. Authentication failures, invalid registration, duplicate required channels, repeated malformed frames, or session-wide resource abuse close the entire session.

The browser error surface cannot reliably map every failed WebTransport CONNECT to an HTTP status or server-side category. responseHeaders are available only after the session is established, and a pre-establishment ready rejection may deliberately hide whether the endpoint was unreachable or unwilling to accept the session. Browser fallback therefore uses only client-observable facts:

• capability-fetch and ticket-issuance HTTP responses retain their explicit Unauthorized, Unsupported, Resource limit, or Internal categories;
• a synchronous absence of the required constructor or constructor option is Unsupported;
• a rejection before ready resolves, after successful capability and ticket requests, is Establishment failed; the browser must not relabel it as Unauthorized, Unavailable, or Internal;
• preferWebTransport may serially fall back to an advertised WebSocket candidate for Establishment failed, while requireWebTransport never does; and
• after ready resolves, profile negotiation and application errors are structured and follow the no-fallback rules.

The gateway and controller retain the authoritative server-side cause in bounded telemetry even when the browser sees only Establishment failed. Both transports enforce the same authentication and authorization policy, so browser fallback is not an authorization bypass. Operators who cannot accept an opaque pre-establishment downgrade must select requireWebTransport.

Disconnect cleanup must remain connection-ID guarded so a late task from an old transport cannot remove a newly registered replacement connection.

Transport and Profile Selection

Transport and codec remain independent, but fallback ordering must be unambiguous. Clients therefore use an ordered list of explicit candidate pairs:

portalRegistry:
  portalUrl: https://controller:8438
  controlCandidates:
    - transport: webtransport
      wireProfile: light-controller-runtime-rkyv-v1
      negotiation: required
    - transport: websocket
      wireProfile: light-controller-runtime-rkyv-v1
      negotiation: required
    - transport: websocket
      wireProfile: light-controller-runtime-json-v1
      negotiation: legacy

The production default contains only the legacy-compatible pair:

controlCandidates:
  - transport: websocket
    wireProfile: light-controller-runtime-json-v1
    negotiation: legacy

negotiation: required sends the profile offer and requires the peer to select that profile. negotiation: legacy is valid only for an existing JSON WebSocket contract; it sends no wire-profile token and accepts the existing no-profile handshake. This makes new-client-to-old-controller compatibility explicit without allowing an absent selection to downgrade a binary or WebTransport candidate.

Convenience modes such as websocket, preferWebTransport, and requireWebTransport may be retained, but configuration loading must expand them into and expose the ordered candidate pairs. The same rule applies to a preferRkyv convenience setting. Operators must be able to see the effective order and must not depend on an undocumented Cartesian-product ordering.

The existing portalUrl remains the base controller URL, including any ingress path prefix. The client derives /wt/microservice and /ws/microservice without discarding that prefix.

portal-view has one fixed wire profile, light-controller-mcp-json-v1. Its default local mode is auto: fetch /ctrl/mcp/capabilities, intersect the ready candidates with browser support, and follow the gateway policy. The gateway policies are:

The optional build-time override VITE_CONTROLLER_TRANSPORT=auto|websocket|webtransport is intended for local development, emergency compatibility, and controlled tests. auto is the default. websocket forces the legacy WebSocket candidate; webtransport requires WebTransport and does not silently fall back. The build variable is not the source of deployment readiness: the same UI bundle should work when gateway routes or controller transport sets change without a rebuild. A future runtime-injected UI configuration may provide the same override without changing the capability contract.

In auto mode, portal-view performs these steps after authentication and when the first controller consumer requests a connection:

1. Fetch the authenticated capability resource. If there is no valid response or still-fresh cached response, apply the capability-fetch failure rules, schedule jittered backoff, and return without attempting either transport.
2. Check for the required local WebTransport constructor and option support.
3. If policy and candidates permit it, request a ticket and attempt WebTransport with a bounded connection timeout.
4. Require light-controller-mcp-json-v1 as the selected protocol and supports-unreliable as the reliability mode before MCP initialization.
5. Fall back to the advertised legacy WebSocket candidate only for observable Unavailable or Unsupported failures, or for the explicitly opaque Establishment failed category under preferWebTransport.
6. Do not fall back for authentication, authorization, protocol, resource-limit, or internal errors.

The actual attempt, not user-agent sniffing, page nextHopProtocol, or a cached previous success, determines whether the current enterprise network supports the WebTransport path.

The gateway initially uses matchIngress upstream selection: WebSocket ingress uses a WebSocket upstream and WebTransport ingress uses a WebTransport upstream. No automatic cross-transport relay is allowed.

Fallback rules are:

• attempts are serial, never parallel;
• fallback is allowed only before runtime registration acknowledgement or MCP initialization succeeds;
• browser preferWebTransport may fall back for an opaque pre-ready Establishment failed; requireWebTransport may not;
• do not fall back for Unauthorized, invalid registration, protocol violation, resource-limit, or internal errors;
• browser ticket authentication or Origin failure is Unauthorized, not an indication that WebTransport is unsupported;
• log and count the normalized fallback reason without logging secrets;
• after an established session disconnects, retry its selected transport first with the existing jittered exponential backoff;
• do not keep two live registrations for the same client attempt;
• never try a transport/profile pair that is absent from the configured candidate list;
• requireWebTransport and required-profile policies prevent a network attacker or deployment error from silently forcing a downgrade.

Java light-4j clients do not receive the new setting and continue to use WebSocket.

Controller Configuration

Proposed server settings are:

CONTROLLER_MCP_TRANSPORTS=websocket
CONTROLLER_RUNTIME_TRANSPORTS=websocket
CONTROLLER_STANDALONE_DISCOVERY_TRANSPORTS=websocket
CONTROLLER_WEBTRANSPORT_ADDR=<CONTROLLER_ADDR>
CONTROLLER_WEBTRANSPORT_MAX_SESSIONS=1000
CONTROLLER_WEBTRANSPORT_MAX_COMMAND_STREAMS=64
CONTROLLER_COMMAND_QUEUE_CAPACITY=64
CONTROLLER_MAX_IN_FLIGHT_COMMANDS_PER_SESSION=64
CONTROLLER_MAX_IN_FLIGHT_COMMANDS_GLOBAL=4096
CONTROLLER_REGISTRATION_TIMEOUT_MS=5000
CONTROLLER_MCP_MAX_MESSAGE_BYTES=16777216
CONTROLLER_WEBTRANSPORT_RUNTIME_PROFILES=light-controller-runtime-json-v1,light-controller-runtime-rkyv-v1
CONTROLLER_WEBTRANSPORT_MCP_PROFILES=light-controller-mcp-json-v1
CONTROLLER_WEBSOCKET_BINARY_PROFILES=

The three transport settings are comma-separated enabled sets; server-side order has no preference semantics, duplicate values are invalid, and diagnostics emit their normalized effective values. Runtime registry and discovery messages use CONTROLLER_RUNTIME_TRANSPORTS; CONTROLLER_STANDALONE_DISCOVERY_TRANSPORTS controls only /ws/discovery and any future binding of that standalone surface. These settings apply only to persistent controller communication surfaces; disabling WebSocket for one of them does not disable the controller’s normal HTTPS health or administrative endpoints. Initial production settings contain only websocket. A dual migration configuration can use:

CONTROLLER_MCP_TRANSPORTS=websocket,webtransport
CONTROLLER_RUNTIME_TRANSPORTS=webtransport,websocket
CONTROLLER_STANDALONE_DISCOVERY_TRANSPORTS=websocket

This permits the browser to fall back on enterprise networks while Rust runtime clients prefer WebTransport. A surface may be configured as WebTransport-only after every client and network path for that surface is proven. In particular, CONTROLLER_MCP_TRANSPORTS=webtransport removes browser WebSocket fallback under the initial same-transport gateway design. Java and other clients that do not implement WebTransport require a WebSocket-enabled surface.

CONTROLLER_WEBTRANSPORT_ADDR is a UDP socket address. It may use the same numeric host and port as the existing TCP listener because TCP and UDP have separate port spaces.

In version 1, controller listener addresses, enabled transport sets, and allowed profile sets are startup-only. Changing them requires a controller restart and produces a new controller capability revision. Client preference remains owned by the ordered controlCandidates list; browser preference remains owned by gateway mcpTransportPolicy. Server enabled sets do not create a third preference source.

The WebTransport listener reuses the configured controller certificate and private key but creates a QUIC-compatible TLS 1.3 configuration with HTTP/3 ALPN. Adding h3 to the existing Axum TCP TLS configuration is not sufficient.

The WebTransport listener is enabled when any surface enabled set contains webtransport. Startup is fail-fast when that listener, its TLS identity, or required protocol extensions cannot be initialized. When no surface enables WebTransport, failure to initialize experimental WebTransport code must not affect the existing HTTPS/WebSocket listener.

Allowed-profile lists are deny-by-default. An empty MCP list disables direct MCP WebTransport on the controller even when the runtime WebTransport listener is enabled. CONTROLLER_WEBSOCKET_BINARY_PROFILES remains empty in production until rkyv over WebSocket testing is explicitly approved.

Gateway Configuration

Add a webtransport-router.yml module with route-resolution fields compatible with websocket-router.yml and WebTransport-specific session and stream limits. For example:

defaultProtocol: https
defaultEnvTag: dev
pathPrefixService:
  /ctrl/mcp:
    serviceId: com.networknt.controller-1.0.0
    protocol: https
    envTag: dev
allowedProfiles:
  /ctrl/mcp:
    - light-controller-mcp-json-v1
mcpTransportPolicy: websocket
capabilityMaxAgeSeconds: 30
controllerCapabilityPath: /internal/controller/capabilities
controllerCapabilityStaleMs: 15000
controllerProbeIntervalMs: 5000
controllerProbeTimeoutMs: 2000
maxActiveSessions: 1000
maxStreamsPerSession: 1
ticketTtlMs: 30000
ticketClockSkewReadyMs: 2000
allowedOrigins:
  - https://portal.example.com

mcpTransportPolicy and capabilityMaxAgeSeconds are shared BFF policy settings even if configuration composition presents them beside the WebTransport router. They are not owned by only one router. The WebSocket and WebTransport routers publish bounded readiness state to one capability aggregator, which combines it with route and controller health.

The configuration shape is illustrative until implementation review, but these contracts are required:

• POST /ctrl/mcp/ticket is handled by the HTTPS BFF before this route table, while WebTransport CONNECT for /ctrl/mcp enters this router;
• GET /ctrl/mcp/capabilities is handled by the authenticated BFF and reports only end-to-end candidates supported by the configured policy, healthy listeners, route resolver, and controller targets;
• controller capability responses and transport-native probe results must both be current within their configured stale thresholds before a target is eligible;
• route resolution code is shared with the WebSocket router rather than copied;
• activation follows the gateway handler/module model rather than an unrelated second enable flag;
• WebTransport-specific limits and allowed profiles are explicit;
• an empty or absent Origin allowlist rejects browser WebTransport;
• replay-cache unavailability, ambiguous atomic-consume results, or clock error beyond ticketClockSkewReadyMs makes ticket readiness false and fails ticket issuance and consumption closed;
• invalid startup config fails startup, while an invalid reload retains the last valid runtime;
• WebSocket and WebTransport route tables may differ, but drift is visible in diagnostics and configuration tests.

Gateway route, policy, limit, and capability configuration is reloadable. A valid reload applies to new sessions and immediately removes disabled or unready candidates from capability responses, producing a new aggregate revision. Existing sessions remain pinned and continue until normal close, token or maximum-duration expiry, target drain, or an explicit security revocation. A routine policy reload does not reinterpret or migrate an established session. When a route or listener must be removed, the gateway marks it draining, stops new admission, waits for the configured drain deadline, and then closes any remaining sessions with a categorized reason. An invalid reload keeps the last valid configuration and revision.

Deployment Requirements

Every supported controller deployment must explicitly expose every transport enabled by its per-surface sets. A dual configuration exposes:

ports:
  - "8438:8438/tcp"
  - "8438:8438/udp"

Kubernetes Services, firewall rules, security groups, ingress or Gateway API resources, and load balancers must also permit UDP on the controller port. The TCP listener remains available for normal HTTPS health and administrative traffic even when all persistent controller surfaces are WebTransport-only.

A browser deployment additionally exposes the gateway’s public HTTPS port over both TCP and UDP, normally 443/tcp and 443/udp. The gateway-to-controller network path must separately permit QUIC to the controller UDP port. Proving the browser-to-gateway leg does not prove the gateway-to-controller leg.

An AWS Application Load Balancer is not the assumed WebTransport path. Use a QUIC-aware Network Load Balancer or another proven end-to-end topology. Generic HTTP/3 termination in Nginx or HAProxy is acceptable only after an integration test proves the required WebTransport draft, extended CONNECT, datagrams, stream resets, connection IDs, and draining behavior.

Existing HTTPS health endpoints prove TCP listeners only. Add WebTransport readiness signals or synthetic probes for both the gateway and controller so operators can distinguish:

• controller healthy, WebTransport disabled;
• controller healthy, WebTransport ready;
• controller healthy, WebTransport failed;
• gateway healthy, WebTransport router disabled;
• gateway healthy, browser ticket and upstream WebTransport route ready;
• gateway healthy, one WebTransport leg failed;
• complete controller failure.

Multi-Replica Constraint

Current live instances, command senders, and pending requests are held in one controller-rs process. PostgreSQL records audit and projection data; it is not a live command router.

Until a separate distributed-session design is implemented:

• run one active controller replica for command routing; or
• provide an external routing mechanism that can direct every command to the process owning the target runtime session.

Load-balancer affinity for a QUIC connection keeps that connection on one controller pod, but it does not make an MCP request arriving at another pod able to use the session. QUIC connection migration also does not migrate application state between controller pods.

This proposal must not be presented as enabling active-active controller replicas.

Graceful Draining

Gateway or controller shutdown follows this order:

1. Mark the affected WebTransport readiness false.
2. Stop issuing browser tickets and accepting new WebTransport sessions.
3. Stop opening new upstream gateway sessions and new runtime command channels.
4. Send the profile-specific runtime draining message; for rkyv this is ServerDrainingV1.
5. Allow in-flight MCP requests and runtime commands to complete for a bounded grace period.
6. Fail remaining pending work with a transport error.
7. Close upstream and downstream WebTransport sessions with explicit reasons, then close WebSocket sessions under the existing policy.
8. Let clients reconnect with jittered backoff and obtain a new browser ticket where required.

Connection draining is not transparent failover. A reconnected runtime must perform registration again and receive the authoritative connection ID.

Security Requirements

• Use TLS 1.3 and normal certificate and hostname verification.
• Apply the existing JWT issuer, audience, expiry, service identity, and environment checks.
• Require a non-empty Origin allowlist for browser WebTransport and compare the complete normalized origin, not a suffix or substring.
• Authenticate the public browser capability resource and expose only public endpoints, bounded policy names, profile tokens, and readiness; do not expose upstream controller addresses, instance IDs, or probe details.
• Authenticate the internal controller capability and probe resources with a dedicated least-privilege gateway service identity or mTLS identity, restrict them to the gateway network path, reject browser tickets and user credentials, rate-limit them, and redact probe credentials. The internal instanceId and revision must never be copied into the public capability response.
• Protect ticket issuance with the existing cookie authentication and CSRF checks; bind tickets to one route, origin, principal, profile, expiry, and use.
• Consume tickets atomically from a bounded replay cache and never accept them from URL query parameters.
• Fail ticket issuance and consumption closed when the replay cache is unavailable, degraded, or cannot prove atomic single-use behavior; never use a local-cache or unprotected signed-ticket fallback.
• Require synchronized gateway clocks, enforce the earliest cache, ticket, and access-token deadline, and do not extend the ticket hard maximum with clock tolerance.
• Treat replay-cache records as credential storage when they retain an upstream access token: restrict access, protect data at rest and in transit, and delete the complete record on consumption or expiry.
• Do not assume browser WebTransport carries cookies or HTTP authentication.
• Require the gateway to inject the retained Bearer token upstream and the controller to validate it independently; restored gateway roles are not controller claims.
• Enforce access-token expiry and maximum session duration with a gateway timer; claim immediate revocation only when a concrete signal or introspection mechanism is configured and tested.
• Authenticate before accepting application streams or allocating large application buffers beyond the strict handshake allowance.
• Enable QUIC address validation or Retry for untrusted network exposure when supported by the selected implementation.
• Limit unauthenticated connections, authenticated sessions, streams, frame sizes, queue sizes, tickets, and bytes per time window.
• Validate JSON length, UTF-8, and one-value framing before dispatch.
• Validate every rkyv archived root with bytecheck and then apply semantic validation.
• Never invoke rkyv unchecked access on network bytes.
• Reject endpoint, transport, and wire-profile combinations that are not explicitly allowlisted.
• Treat downgrade from a required transport or profile as an error, not an automatic fallback.
• Redact tickets, JWTs, cookies, CSRF values, authorization headers, and sensitive command payloads.
• Treat unknown wire-profile versions and message kinds as errors, not as a reason to guess a Rust type.
• Fuzz JSON framing, binary frame parsing, and archived validation with arbitrary bytes.
• Close sessions that repeatedly violate limits instead of continuing to allocate and log indefinitely.

Backpressure and Fairness

Independent QUIC streams remove retransmission ordering between streams, but they share connection congestion control and implementation scheduling. WebTransport does not automatically make a command high priority.

The implementation must:

• reserve bounded capacity for command streams;
• prevent the event reader from monopolizing the controller task executor;
• use bounded browser, gateway, controller, and runtime queues;
• apply backpressure across both legs of a proxied WebTransport stream rather than buffering an unbounded slow side;
• cap streams waiting for an upstream mapping and fail closed when the upstream session cannot accept more;
• expose queue saturation and stream-acquisition latency;
• avoid spawning an unbounded task for every incoming stream;
• time out stalled reads and writes;
• test fairness under log load and packet loss.

If the selected library exposes stream scheduling, the policy may prefer command streams over runtime events. Correctness must not depend on nonstandard priority behavior.

Datagrams and Telemetry

Version 1 does not use WebTransport datagrams.

QUIC datagrams are unreliable and unordered. They have no explicit flow control, cannot be fragmented across QUIC packets, and may be delayed or dropped by the sender or receiver under congestion. Their use requires an application contract for maximum size, batching, sequence numbers, timestamps, loss accounting, and overload behavior.

Metrics and traces already have dedicated ecosystem protocols. Sending them to controller-rs would expand the controller into a telemetry ingestion service and could couple telemetry load to command availability. Any future datagram use requires a separate design comparing at least OTLP, Prometheus-compatible delivery, and a dedicated collector.

If datagram metrics are ever approved, cumulative snapshots are preferred over loss-sensitive deltas, with periodic reliable checkpoints.

Observability

Add metrics with bounded labels for:

• active sessions by component, hop, transport, and negotiated wire profile;
• connection attempts, accepted sessions, and categorized failures;
• fallback count and reason;
• capability responses and refreshes by bounded policy and candidate set, plus candidate attempts rejected because readiness changed before handshake;
• capability-fetch failures and discovery backoff by bounded error category;
• registration and authentication latency;
• browser ticket issuance, consumption, expiry, replay rejection, and Origin rejection without ticket or Origin values as labels;
• replay-cache health, atomic-consume failures, and gateway clock-synchronization readiness without cache keys or ticket values as labels;
• current in-flight commands by session and globally, plus rejections by queue, in-flight, stream, and session limit;
• gateway downstream-to-upstream session and stream mapping failures;
• command stream acquisition, command latency, timeout, and reset count;
• JSON and rkyv frame validation, semantic validation, and size-limit failures;
• active and blocked streams;
• event queue depth and dropped log records;
• bytes sent and received by logical channel and gateway hop;
• QUIC RTT, loss, and migration when exposed by the library;
• drain duration and forced session closes.

Structured logs should include connection ID, runtime instance ID after registration, gateway hop, transport, wire profile, logical channel, and normalized error category. Do not use ticket IDs, service JWTs, user tokens, full payloads, Origin values, or unbounded peer values as metric labels.

The runtime instance’s application protocol metadata remains unchanged. Expose the controller transport through diagnostics or a separate optional controlTransport field only after checking event, database, and UI consumers.

Rollout Plan

Phase 0: Feasibility and Baseline Gate

• Measure allocations, CPU, memory, throughput, and command latency on the existing WebSocket path.
• Include idle connections, registration storms, command traffic, and concurrent log notifications.
• Record payload sizes and identify how much time is actually spent in JSON.
• Pin one Rust WebTransport implementation and prove controller and Rust-client interoperability against the exact supported draft.
• Prove payload-opaque, same-transport WebTransport stream relay across both gateway legs, including reset, backpressure, close, and draining.
• Prove that the gateway capability resource reflects end-to-end route and per-instance controller readiness, revisions, candidate-specific target pools, and transport-native probes, and never treats a page’s HTTP version as availability.
• Prove browser ticket issuance, atomic consumption, protected credential storage, upstream Bearer injection, Origin enforcement, profile selection, requireUnreliable, and expiry-driven session close in every target browser.
• Prove the target browser’s observable failure behavior: explicit capability and ticket HTTP failures retain their categories, pre-ready WebTransport rejection becomes Establishment failed, preference mode may fall back, and required mode may not.
• Prove the shared controller-BFF authority resolver in the supported same-origin deployment and in every explicitly supported cross-origin deployment.
• Prove the required UDP, HTTP/3, certificate, and WebTransport behavior through each supported development and production load-balancer topology.
• Select the shared replay cache and prove atomic fail-closed behavior, synchronized-clock readiness, and hard-expiry enforcement; decide the owner and release process for controller-wire and the benchmark workload.

Phase 0 is an approval gate. Phase 1 must not begin until these artifacts are reviewed, the pinned compatibility tuple is recorded, and no unresolved item requires changing the authentication trust model, gateway topology, or wire profile boundaries. A failed spike keeps WebTransport disabled. A shared-session refactor may still proceed when it is separately justified as WebSocket hardening or preparation for binary WebSocket/raw QUIC evaluation, but it must not introduce or assume WebTransport behavior.

The 2026-07-15 Phase 0 implementation produced that failed-spike result. Native direct and same-transport relay mechanics, current certificate reuse, bounded reconnect, and Redis atomic consume passed. Chrome 150 did not send the supplied Authorization header. The server observed the supplied profile offer, and stream echo/reset/close passed, but Chrome did not expose the selected protocol, response headers, or required reliability result. The pinned wtransport 0.7.1 native client also discarded response headers, and its protocol generation did not implement draft 16. Production WebTransport remains disabled and Phase 1 was not approved on a WebTransport justification. The executable evidence and closure decision are in implementation/light-controller/phase0.

The separately justified WebSocket-only Phase 1 extraction completed on 2026-07-15. It introduced bounded command admission, explicit WebSocket message limits, transport-neutral controller session modules, a logical-message PortalRegistryClient, a private WebSocket adapter, and shared legacy JSON fixtures. It did not enable WebTransport or change the Phase 0 decision. The closure record and executable gates are in implementation/light-controller/phase1.

The transport-independent shared wire-profile foundation completed on 2026-07-15. light-fabric/crates/controller-wire now exclusively owns the version 1 profile tokens, framing, immutable archived roots, bounded validation, semantic limits, golden bytes, dependency-purity policy, and pinned rkyv feature policy. Both portal-registry and controller-rs compile and test owned conversion boundaries against the same fixtures. This completes implementation-plan Phase 2, not the broader design Phase 2 below: no listener, negotiation, binary WebSocket profile, or WebTransport behavior is enabled. The closure record and executable gates are in implementation/light-controller/phase2.

Phase 1: Extract Shared Session Behavior

• Refactor controller-rs runtime and MCP message handling into transport- and codec-neutral service functions.
• Replace the Rust client’s tungstenite-specific outbound channel with logical messages.
• Separate wire-profile adapters from WebSocket and WebTransport session adapters.
• Keep behavior and wire output unchanged.
• Run the complete existing WebSocket test suite.

Gateway route-resolver extraction remains part of the later gateway phase; it was not required for the controller/client shared-session boundary.

Phase 2: Runtime Profile Matrix

The shared crate and conformance portion is complete. Every transport-enabling item in this design phase remains blocked by the Phase 0 no-go.

• Add the shared controller-wire crate and golden fixtures.
• Add the UDP/HTTP3 listener, enabled when any controller surface enabled set contains webtransport.
• Implement runtime JSON over WebTransport first.
• Implement runtime rkyv over WebSocket binary frames and WebTransport.
• Verify that JSON and rkyv use the same logical WebTransport channel model.
• Add ordered transport/profile candidates to the Rust client.
• Keep all production configurations in websocket mode.

Phase 3: Browser MCP and Gateway Router

• Add the gateway UDP/HTTP3 service and payload-opaque WebTransport router.
• Add the authenticated MCP capability resource and short-lived readiness synthesis across both gateway legs.
• Add ticket issuance, shared replay-cache behavior, Origin enforcement, and authenticated-principal restoration.
• Add MCP JSON framing and WebTransport support to portal-view and controller-rs.
• Add portal-view auto-selection and its build-time force override without changing MCP/JSON-RPC 2.0 application semantics.
• Require WebTransport header and protocol-negotiation support in every target browser.
• Keep browser production configuration in websocket mode.

Phase 4: Controlled Opt-In

• Enable approved candidate pairs for selected Rust services in a deployment with verified UDP routing.
• Enable preferWebTransport for a small browser cohort only after both gateway legs and ticket authentication are proven.
• Observe fallback, ticket, validation, queue, memory, and command-latency metrics by profile and hop.
• Exercise rolling upgrades, draining, UDP blocking, and rollback.

Phase 5: Default Decision

Make no default change unless:

• behavior parity and compatibility tests pass;
• fuzzing finds no panic or unsafe-access path;
• supported deployment topologies pass end-to-end tests;
• target browsers support the required WebTransport headers, protocols, requireUnreliable, selected-protocol, and reliability checks;
• ticket replay and multi-replica gateway tests pass;
• the measured benefit is material for the target workload;
• per-session memory and operational complexity are acceptable;
• rollback to WebSocket has been exercised.

If these gates fail, retain WebSocket or choose the simpler binary-WebSocket or raw-QUIC alternative.

Verification Plan

Protocol and Unit Tests

• Allowed and rejected endpoint/transport/profile combinations.
• Per-surface transport enabled sets enable only the configured MCP, runtime, and standalone-discovery endpoints and derive WebTransport listener activation correctly.
• Legacy WebSocket clients without a profile retain existing JSON behavior.
• WebSocket and WebTransport profile negotiation select the same wire contract.
• WebSocket token permutations prove that csrf.* is consumed only as authentication metadata, is never selected as a negotiated wire profile, and does not depend on client token ordering.
• Required negotiation rejects an absent selected token; only an explicit negotiation: legacy JSON WebSocket candidate accepts the no-profile path.
• Ordered candidate expansion and downgrade-policy tests.
• Capability-response construction includes only policy-allowed, healthy, same-transport end-to-end candidates and applies revision, ETag, generation, expiry, private-cache, and Vary rules.
• Internal controller capabilities reject unauthorized callers, validate schema and expiry, change revision for readiness and draining changes, and describe only enabled transport/profile pairs.
• Transport-native probes authenticate, negotiate the requested surface and profile, return the matching controller revision, obey bounds, and never mutate registration, MCP, command, or discovery state.
• Capability-fetch 401/403, 404/501, 429, timeout, malformed response, and 5xx cases follow the specified no-guessing and backoff behavior.
• portal-view auto, forced-WebSocket, and required-WebTransport overrides produce the expected ordered attempts without changing the wire profile.
• The controller-BFF authority resolver preserves configured ingress prefixes, uses one authority for all four browser controller operations, rejects cross-authority redirects, and fails closed when cross-origin prerequisites are absent.
• Server enabled-set permutations produce the same result regardless of input order; duplicate or unknown transports are rejected. Client candidate order remains observable and authoritative.
• JSON length-prefix round trips, partial prefixes, invalid UTF-8, oversized lengths, empty payloads, trailing bytes, and multiple values.
• Golden bytes for every version 1 root type.
• Header round trips and rejection of invalid magic, flags, lengths, kinds, and reserved bytes.
• Cross-target fixture reads for all supported release targets.
• Schema compatibility checks using old committed fixtures.
• Semantic limits for strings, tags, lists, JSON, and timestamps.
• No unchecked rkyv access in production modules.
• Fuzz arbitrary headers and payloads without panic, excessive allocation, or unbounded validation work.

Integration Tests

• WebSocket registration and commands remain unchanged.
• Runtime JSON over WebTransport registration, metadata, discovery, commands, responses, notifications, heartbeat, and cleanup match JSON over WebSocket.
• Runtime rkyv over WebSocket and WebTransport produces the same application behavior as runtime JSON.
• Browser MCP JSON requests, responses, notifications, cancellation, reconnect, and close behavior match across WebSocket and WebTransport.
• Capability refresh, stale readiness, controller rolling upgrades, and a route becoming unavailable between discovery and handshake produce categorized retry or fallback behavior.
• Mixed controller revisions create candidate-specific target pools; sessions are pinned to eligible targets, draining or stale targets receive no new sessions, and aggregate revision changes invalidate old candidates.
• The gateway WebTransport router maps reliable streams, reset, backpressure, draining, and close without parsing MCP JSON.
• Cross-transport and cross-codec gateway routes are rejected.
• Ticket expiry, replay, wrong route, wrong Origin, wrong profile, token expiry, and concurrent consumption are rejected.
• Replay-cache write failure, outage, degradation, ambiguous consume, and loss of atomicity fail ticket issuance or consumption closed without a local fallback.
• Gateway clock error below, at, and above the readiness threshold never extends the ticket hard maximum and enforces the earliest applicable deadline.
• Multi-replica ticket issuance and consumption uses the configured shared cache or proven affinity behavior.
• Ticket consumption injects the retained Bearer token upstream, the controller independently validates it, credential cache records are deleted, and the session closes no later than token expiry or maximum duration.
• Browser WebTransport rejects a wrong selected profile and a reliable-only session; requireUnreliable and the target-browser API contract are tested.
• Controller restart and client reconnect.
• Registration timeout and partial frames.
• Invalid, expired, wrong-audience, wrong-service, and wrong-environment JWTs.
• Oversized frames, too many streams, stalled readers, and blocked writers.
• Queue, per-session in-flight, global in-flight, stream, and session limits are exercised independently, including admission races and cleanup after timeout.
• Command timeout, late response, stream reset, and session close races.
• Serial candidate fallback when UDP is blocked or a profile is unsupported.
• An opaque browser pre-ready rejection falls back only in preferWebTransport; requireWebTransport fails without a WebSocket attempt.
• Explicit capability or ticket authentication, authorization, resource, and internal failures never enter the opaque-establishment fallback path.
• HTTP/2 page plus successful WebTransport, and HTTP/3 page plus failed WebTransport CONNECT or upstream QUIC, prove that page nextHopProtocol does not select the controller transport.
• No fallback for observable authentication, registration, protocol, resource, or internal failures before establishment, or for their structured forms after establishment.
• Old Rust client to new controller, new Rust client to old controller, and Java client to new controller.
• Controller drain with in-flight commands.
• Gateway policy reload affects new admission and capability revision without reinterpreting established sessions; listener removal drains and closes at the configured deadline; invalid reload retains the last valid revision.

Deployment Tests

• Direct TCP and UDP access on the same numeric port.
• Docker Compose with explicit TCP and UDP mappings.
• Every supported Kubernetes and load-balancer topology.
• Browser-to-gateway and gateway-to-controller QUIC tested independently and together.
• Enterprise-network profiles that block UDP or WebTransport CONNECT fall back to an advertised WebSocket candidate without requiring a UI rebuild.
• Target browser matrix for CONNECT headers, profile negotiation, certificate validation, stream behavior, and network fallback.
• QUIC connection-ID routing and migration where claimed.
• TCP health remains available when experimental WebTransport is disabled.
• Synthetic probes distinguish gateway ingress, gateway upstream, and controller UDP or HTTP/3 failure.

Benchmark Profiles

Compare at least:

1. runtime JSON-RPC over the legacy single-channel WebSocket;
2. runtime JSON-RPC over WebTransport using one ordered bidirectional stream;
3. runtime JSON-RPC over WebTransport using the proposed multiplexed topology;
4. runtime rkyv over one binary WebSocket channel;
5. runtime rkyv over WebTransport using one ordered bidirectional stream;
6. runtime rkyv over WebTransport using the proposed multiplexed topology;
7. runtime rkyv over raw QUIC with the closest equivalent single-stream and multiplexed topologies;
8. browser MCP JSON over WebSocket through light-gateway;
9. browser MCP JSON over WebTransport through light-gateway.

Treat codec, transport, framing, and stream topology as separate benchmark variables:

• JSON versus rkyv on the same transport and topology measures codec cost.
• Single-stream versus multiplexed WebTransport with the same codec measures topology and head-of-line effects.
• Single-channel WebSocket versus single-stream WebTransport is the closest transport comparison, but native framing still differs and must be reported; it must not be described as a pure transport-only measurement.
• Legacy WebSocket versus multiplexed WebTransport measures the complete proposed operational change, not one isolated variable.

All paired cases use identical logical messages, concurrency, payload mixes, warmup, and connection counts. Results report the selected wire profile, transport, topology, WebTransport draft/library tuple, and browser reliability mode so a reliable-only implementation cannot be mislabeled as the QUIC case.

Run profiles for:

• many idle registered sessions;
• registration bursts;
• small commands and responses;
• large dynamic JSON results;
• command responses concurrent with runtime log notifications;
• packet loss, reordering, and constrained bandwidth.

Record CPU and memory separately for browser, gateway, controller, and runtime, plus allocations, bytes on the wire for each hop, registration rate, ticket latency, command p50/p95/p99 latency, event drops, and reconnect time. Publish the hardware, message mix, connection count, browser version, and network conditions with results.

Risks and Mitigations

Phase 0 Decisions and Reopen Questions

The failed feasibility run locks the following decisions without authorizing production implementation:

• WebTransport remains disabled and WebSocket/JSON remains the production path.
• Planned gateway replacement uses drain when possible and bounded client reconnect after interruption. There is no zero-downtime QUIC preservation claim.
• The replay-store candidate is a shared Redis-compatible service using hash-only keys, protected values, hard TTL, SET NX PX, atomic GETDEL, TLS, ACLs, and fail-closed outage behavior. There is no local production fallback.
• Internal capability and probe resources use a dedicated gateway mTLS identity.
• controller-wire remains a dependency-light, independently versioned crate owned by light-fabric and consumed by controller-rs.
• WebSocket and WebTransport route files remain separate initially with a shared resolver and enforced parity diagnostics.
• The nine-case benchmark manifest and required workload/metric set are locked by the Phase 0 evidence package.

Reopen WebTransport feasibility only when a candidate Rust stack implements the selected current draft and exposes request/response negotiation in both roles, and a target shipping browser passes CONNECT headers, profile negotiation, requireUnreliable, reliability, reset, close, and stream tests end to end. Deployment environments, enterprise UDP/CONNECT behavior, production load targets, and any distributed controller session router remain later questions because the mandatory local tuple failed first.

References

• WebTransport over HTTP/3, current IETF draft
• W3C WebTransport API
• QUIC transport, RFC 9000
• QUIC datagrams, RFC 9221
• rkyv documentation
• rkyv format documentation
• Protocol Buffers overview
• AWS Application Load Balancer listeners
• AWS Network Load Balancer listeners

Agent Skill And API Endpoint Discovery

Problem

The GenAI chat flow has two separate concepts that are easy to confuse:

• The light-gateway MCP endpoint is the runtime server that lists and executes tools. An agent should call the gateway for tools/list and tools/call. A listed tool may be backed by a downstream MCP server or by a gateway-routed HTTP/OpenAPI endpoint.
• Portal-query is the catalog service for skills, tools, and agent assignments. The agent should read this catalog through the genai-query API, cache it locally, and search it during chat.
• The controller registry remains a runtime control-plane service for registration, discovery, and cache-management commands. It should not own the portal skill/tool catalog and should not execute downstream MCP or REST calls.

During chat, light-agent should use its local catalog cache to find relevant skills, then call tools/list on the gateway to verify executable tools. Tool execution still goes through the gateway. If the catalog cache is empty or stale, the agent should refresh it from portal-query. If portal-query is temporarily unavailable, the agent should still be able to use the gateway tool list directly.

The missing piece is a portal-managed catalog that explains which API endpoints exist, which endpoint projections are invokable by agents, which skills they belong to, and which agents are allowed or expected to use those skills. Without that catalog, the agent can list executable gateway tools, but it has no domain guidance beyond each tool description.

Goals

• Keep the gateway as the runtime source of truth for MCP tool execution.
• Keep direct gateway tools/list and tools/call working even when no skills have been authored.
• Treat API endpoints as the generic capability unit. MCP tools, OpenAPI operations, JSON-RPC methods, and future protocol operations should all become endpoint-level capabilities before they are exposed to agents.
• Populate a portal endpoint and tool catalog from API version parsing, LightAPI descriptions, gateway-discovered MCP tools, manually pasted MCP tools/list payloads, and gateway-routed REST tools.
• Let portal users create skills that contain instructions and curated tool selections.
• Let portal users assign skills to agent definitions.
• Use the genai-query API and spec as the portal-query access surface for skills, tools, and agent assignments.
• Let the agent cache the effective catalog locally and reload it when controller cache-management invalidation is triggered.
• Make skills useful for progressive disclosure without requiring every MCP tool to be wrapped before it can be called.
• Store semantic routing metadata for endpoint capabilities so the agent or portal-query can perform macro-filtering, keyword search, vector ranking, context viability checks, and safety filtering.

Non-Goals

• Do not move MCP request routing or downstream REST calls into the controller.
• Do not implement skill/search in controller-rs. Controller-rs can invalidate the agent cache, but portal-query owns catalog reads.
• Do not use config-server as the first delivery path for the skills/tools catalog. The agent can fetch from portal-query and cache locally.
• Do not require every gateway tool to have a skill before it is executable.
• Do not replace the existing MCP Gateway registry design. This design extends it with agent-facing skill curation.
• Do not implement embeddings in the first phase. Keyword search is enough for the initial local catalog search.
• Do not limit the catalog to MCP tools. The UI may use “tool” when referring to LLM tool-calling, but the persistent capability model should be endpoint first.
• Do not use skill assignments as the only authorization control. Gateway policy and downstream authorization still apply at execution time.

Concepts

Target Architecture

The target flow keeps runtime execution and control-plane metadata separate.

Portal UI
  -> writes api_endpoint_t, tool_t, tool_param_t, skill_t, skill_tool_t, skill_workflow_t, agent_skill_t

light-gateway /mcp
  -> lists executable tools from mcp-router.tools and downstream MCP servers
  -> executes tools/call against downstream MCP or REST services

light-workflow
  -> owns deterministic multi-step workflow execution, task state, and audit events

portal-query genai-query API
  -> serves skill/tool/agent-skill catalog reads from portal data

controller-rs portal registry
  -> registers agents and sends cache-management invalidation commands

light-agent
  -> loads assigned skills and mapped tools from portal-query
  -> caches the effective catalog locally
  -> searches cached skills during chat
  -> lists executable tools from light-gateway
  -> calls selected tools through light-gateway

For the account-agent example:

1. The gateway exposes account tools such as getAccounts and getAccountByNo.
2. Portal stores the canonical endpoint rows in api_endpoint_t.
3. Portal publishes selected endpoint rows into tool_t as agent-invokable capabilities.
4. An operator creates an “Account Management” skill in skill_t.
5. Portal links that skill to the account tools through skill_tool_t.
6. Portal assigns the skill to the account agent through agent_skill_t.
7. At startup or cache reload, the agent reads the assigned catalog through genai-query and caches it locally.
8. At chat time, the agent searches its local catalog cache.
9. The agent combines matched skill instructions with the gateway tool definitions.
10. Any tool call still goes to light-gateway tools/call.

Source Of Truth

The gateway is the runtime source of truth for executable tools. If a tool is not available from the gateway, the agent should not be able to execute it just because it exists in the portal database.

api_endpoint_t is the canonical portal endpoint catalog. It stores the endpoint identity, protocol method, path, logical tool schema, endpoint description, and raw tool metadata for one API version.

tool_t is the agent-facing projection of an endpoint. It stores the tool name, agent description, implementation type, optional endpoint reference, response schema, active flag, semantic routing fields, and semantic embedding. The full metadata object should still be preserved in api_endpoint_t.tool_metadata for import/export and agent cache payloads.

The portal database is the control-plane catalog. It stores:

• operator-friendly descriptions,
• skill instructions,
• agent assignments,
• governance metadata,
• cached or imported tool schemas.

Tool sync should be idempotent. The recommended unique identity is:

host_id + api_version_id + endpoint

Gateway exposure is a separate deployment selection. The catalog should sync all endpoint rows for an API version, then let the user choose which endpoint/tool projections are deployed to a specific gateway instance.

For runtime-executable projections, the gateway identity is:

hostId + serviceId + envTag

The access token used for portal catalog or gateway deployment APIs should carry matching host, sid, and env claims. Portal-query must verify those claims against the requested hostId, serviceId, and envTag before returning or changing catalog data.

Runtime verification means checking whether an endpoint projection is actually listed by a deployed gateway through tools/list. This should be done against the selected gateway instance when an operator is preparing or reviewing a gateway deployment. A later host-wide diagnostics view can aggregate all registered gateways, but phase 2 does not need host-wide verification as the default.

Runtime verification is not part of the persistence projection. The persistence layer should store catalog state, endpoint/tool metadata, and inactive drift state, but it should not call a live gateway. The portal UI, deployment review flow, or a diagnostics endpoint should call the selected gateway’s tools/list with the operator or service credential, compare the returned tool names and schemas with the catalog, and surface the result as deployment drift.

If a previously imported endpoint or tool disappears from the gateway, the sync process should mark the catalog projection inactive instead of deleting it immediately. This preserves skill mappings and gives operators a clear drift signal.

Current Data Model

The database already has the main tables needed for this design:

• skill_t: skill name, description, content_markdown, embedding placeholder, version, and active flag.
• tool_t: agent-facing tool catalog with name, description, implementation metadata, endpoint reference, and response schema.
• tool_param_t: parameter-level metadata and validation schema.
• agent_skill_t: maps agent definitions to skills.
• skill_tool_t: maps skills to tools for progressive disclosure.
• api_endpoint_t: MCP or REST endpoint metadata, including tool_schema and tool_metadata.
• wf_definition_t: stores workflow definitions as YAML for the light-workflow runtime.

Phase 3.5 should add a skill-to-workflow mapping table rather than storing workflow YAML inside skill_t. The recommended table is:

The current phase 2 persistence path can preserve semantic metadata in api_endpoint_t.tool_metadata before dedicated routing columns exist. That is acceptable for import/export compatibility and for small catalogs searched from the agent’s local cache. It should not be treated as the final indexed search shape. Before portal-query performs database-side macro-filtering over large catalogs or before vector ranking becomes a production dependency, promote the high-use routing fields to first-class columns or indexed relationships and backfill them from tool_metadata.

The existing MCP Registry design already maps MCP tools into api_endpoint_t. OpenAPI parsing also creates endpoint rows. This design uses tool_t as the agent-facing catalog row and links it back to api_endpoint_t when the tool originates from an API endpoint.

Recommended mapping for gateway-imported tools: