Light-Fabric

Light-Fabric is a high-performance, unified platform for managing the lifecycle, governance, and orchestration of enterprise AI services including agentic services, agents, tools, skills, memories, MCP servers, APIs, gateways and workflows.

Why Light-Fabric?

We chose the name Light-Fabric because it embodies the "Unified Governance" required for enterprise-grade AI:

• Unified Control Plane: Light-Fabric provides a single point of truth for discovering, governing, and auditing agents, MCP servers, and APIs via the light-portal.
• Enterprise Governance: It prioritizes security and policy enforcement (such as fine-grained authorization) over pure decentralized autonomy, making it safe for corporate environments.
• Integrated Ecosystem: It "weaves" together distributed components—from memory units (Hindsight) to centralized skills—into a cohesive, observable system.
• Durable Identity: The name emphasizes the platform's role as the infrastructure foundation, remaining relevant regardless of the underlying implementation details.

Technical Advantages

By building Light-Fabric on a Rust foundation, we achieve:

• Performance: Built on top of tokio and axum for maximum throughput and memory safety.
• Native Intelligence: Specialized crates for Hindsight memory, tool calling, and workflow orchestration.
• Production Ready: Includes robust features like retries, failover, and observability out of the box.

Core Components

The Light-Fabric is composed of modular crates, infrastructure frameworks, and reference applications:

Crates

• crates/model-provider: A unified interface for multiple LLM providers (Ollama, etc.).
• crates/hindsight-client: Client for the Hindsight biomimetic memory system.
• crates/mcp-client: Implementation of the Model Context Protocol (MCP) for tool discovery and execution.
• crates/portal-registry: Integration with the Light-Portal for service registration and discovery.
• crates/light-runtime: Core runtime foundation for building agentic and microservice components.
• crates/light-rule: High-performance rule engine for fine-grained authorization and data filtering.
• crates/workflow-core & workflow-builder: Core engine and builder for complex agentic workflows.
• crates/config-loader: Flexible configuration management for enterprise environments.
• crates/asymmetric-decryptor & symmetric-decryptor: Security utilities for sensitive data handling.

Frameworks

• frameworks/light-axum: A specialized microservice & agentic framework built on top of the Axum web ecosystem.
• frameworks/light-pingora: High-performance proxy and gateway framework built on top of Cloudflare's Pingora.

Applications

• apps/light-agent: A managed AI agent capable of using tools, accessing memory, and executing complex tasks.
• apps/light-gateway: An enterprise-grade gateway for securing and governing API and agent traffic.
• apps/light-workflow: A service for orchestrating and executing long-running agentic workflows.

Getting Started with Light-Fabric

This guide will help you set up a local development environment for Light-Fabric, including the AI Gateway, Agent Engine, and the management Portal.

Prerequisites

• Rust: Latest stable version.
• Docker: For running database and backend services.
• Node.js: For running the portal-view UI.
• Git: To clone the necessary repositories.

Local Development Setup

To run the entire ecosystem locally, we use the portal-config-loc and service-asset repositories to manage configuration and pre-built assets.

1. Initialize Workspace

Create a unified workspace directory (e.g., ~/lightapi) and clone the core management repositories:

cd ~
mkdir -p lightapi
cd lightapi

# Clone configuration and assets
git clone [email protected]:lightapi/portal-config-loc.git
git clone [email protected]:lightapi/service-asset.git

2. Deploy Local Services

Light-Fabric services are orchestrated via Docker Compose scripts in portal-config-loc. The following command starts the PostgreSQL database and the core services (including the Rust-based components):

cd ~/lightapi/portal-config-loc
./scripts/deploy-local.sh pg rust

3. Import Initial Data

Use the importer script in service-asset to populate the local database with initial events, users, and configurations:

cd ~/lightapi/service-asset
./importer.sh -f events.json

4. Update /etc/hosts

The platform uses virtual hosts for local routing. Add the following entry to your /etc/hosts file (replace with your actual local IP if necessary):

127.0.0.1  local.lightapi.net locsignin.lightapi.net

Running the Management Portal

The Light-Portal provides a unified UI for onboarding MCP servers, configuring AI Gateways, and interacting with agents.

cd ~/lightapi
git clone [email protected]:lightapi/portal-view.git
cd portal-view
npm install
npm run dev

Navigate to https://localhost:3000 and log in with your developer credentials.

Cloud Development (Coming Soon)

We are currently preparing a Cloud Development Server. This will allow developers to:

• Connect to a shared, high-performance AI Gateway.
• Onboard and test MCP servers without a full local installation.
• Collaborate on shared agentic workflows and Hindsight memory banks.

Stay tuned for the connection details and onboarding guide for the cloud environment.

Contributing to Light-Fabric

If you are developing for the Rust crates specifically:

cd ~/lightapi
git clone [email protected]:networknt/light-fabric.git
cd light-fabric
cargo build

Model Providers

Light-Fabric provides a unified, high-performance interface for interacting with diverse Large Language Model (LLM) providers. This abstraction is centered around the Provider trait, allowing applications to remain model-agnostic while leveraging advanced capabilities like native tool calling and prompt caching.

The Provider Trait

All model integrations implement the Provider trait, which supports:

• One-shot and Multi-turn Chat: Simplified APIs for simple prompts and full conversation histories.
• Structured Tool Calling: Native integration for function calling (OpenAI-style).
• Capabilities Detection: Programmatic checks for vision, native tool support, and prompt caching.

Supported Cloud Providers

Light-Fabric supports all major LLM providers. Because the Provider trait is model-agnostic, the framework is compatible with the latest flagship releases as soon as they are available.

• OpenAI: Native support for the GPT-5 series (5.4, mini, nano), the o4 reasoning models, and full legacy support for GPT-4o and GPT-4 Turbo.
• Anthropic: Support for the Claude 4 generation, including Opus 4.7, Sonnet, and Haiku.
• Google Gemini: Support for Gemini 3.1 Pro and Flash, leveraging Vertex AI or AI Studio for multi-modal and long-context tasks.
• Azure OpenAI: Enterprise-grade OpenAI deployments with support for the latest model deployments.
• AWS Bedrock: Access to the latest Claude and Titan models hosted on Amazon Web Services.
• OpenRouter: Access to hundreds of open-source and proprietary models via a single unified API.
• Telnyx: Support for models hosted on the Telnyx platform.
• GLM (Zhipu AI): Support for the ChatGLM/GLM-5 series of models.

Local & Specialized Providers

• Ollama: Seamless integration with local models running on your machine.
• OpenAI-Compatible: A generic CompatibleProvider for any service implementing the OpenAI REST API.
• GitHub Copilot: Integration with GitHub Copilot Chat for developer-centric workflows.

Meta-Providers (Orchestration)

These providers wrap other providers to add resilient or intelligent behavior:

• ReliableProvider: Enhances any base provider with retries, exponential backoff, and automatic failover to fallback models.
• RouterProvider: Dynamically routes requests to different models based on hints or input complexity.

CLI & Tooling Integrations

Light-Fabric includes specialized integrations for developer tools and terminal environments:

• Claude Code CLI: Integration with Anthropic's Claude Code environment.
• Gemini CLI: Terminal-based access to Google's Gemini models.
• KiloCLI: Light-Fabric's native CLI integration for rapid testing and automation.

Key Capabilities

Providers can be queried for their support of advanced features:

• Native Tool Calling: Efficiently generate structured function calls.
• Vision: Process images alongside text prompts.
• Prompt Caching: Leverage provider-side caching to reduce latency and costs for long contexts.

Agentic Workflow Design

Hybrid Agentic Workflow Specification

Agentic Workflow in Light-Fabric implements a hybrid orchestration model for enterprise business processes. The workflow is deterministic, auditable, and stateful, while selected steps can be executed by agents, API calls, rule engine checks, or humans.

The design goal is not to replace enterprise process control with an open-ended agent loop. The goal is to let agents work inside a managed process that has clear state, clear ownership, repeatable execution, and human approval where needed.

Enterprise Challenge

In regulated or operationally sensitive environments, a purely autonomous AI agent is not enough for long-running business work.

• Compliance requires deterministic process paths, approval records, and audit history.
• Reliability requires long-running state to survive process restarts, UI disconnects, and agent failures.
• Safety requires human-in-the-loop checkpoints for decisions with business, security, or financial impact.
• Coordination requires multiple humans and roles to participate in the same process.
• Testing requires the same workflow to run interactively with humans or headlessly with example data.

Light-Fabric solves this by separating orchestration from execution.

Hybrid Model

The workflow is the deterministic process manager. It defines the ordered steps, conditions, retries, error handling, human checkpoints, and outputs.

Agents are workers inside that process. They can reason, call tools, ask for missing data, and use skills, but they do not own the overall process state.

Core Separation

There are two related specifications:

1. Agentic Workflow Specification Describes orchestration: task order, branching, human input, assertions, API calls, retries, errors, exports, and state transitions.

2. LightAPI Description Specification Describes API capabilities at the endpoint level: how an endpoint is invoked, what inputs it accepts, what result shape it returns, examples, behavior notes, and result expectations.

This separation is important. The workflow should not duplicate every endpoint contract. It should reference endpoint descriptions and use them to invoke calls, guide agents, and verify results.

Endpoint-Level Consumption

Light-Portal manages API descriptions at the endpoint level, not only at the whole API level.

This is necessary because real workflows often combine one endpoint from one API with one endpoint from another API. For example, onboarding an API to an AI gateway may involve:

1. register an API
2. create an API version from a specification
3. create a development API instance
4. configure the API through config server
5. link the API instance to a gateway instance
6. select endpoints to expose as MCP tools
7. create a gateway config snapshot
8. reload the gateway through controller
9. run MCP tests against the gateway

Each step may come from a different API surface. The workflow consumes only the endpoints it needs.

The recommended model is:

• API-level descriptions can be authored for convenience and consistency.
• Endpoint-level descriptions are published and consumed by agents and workflows.
• Endpoint descriptions inherit shared context such as authentication, environments, sources, and secrets from an API catalog.
• Agents progressively load endpoint information by disclosure level instead of receiving the entire catalog up front.

Progressive Disclosure

Endpoint descriptions should be disclosed to agents in layers:

• index: operation id, title, tags, visibility
• summary: purpose, capability group, lifecycle
• invocation: input shape, request mapping, auth, examples
• behavior: result cases, errors, edge cases, assertions
• full: complete description for debugging or generation

This allows the agent to discover capabilities cheaply, load invocation details only for selected endpoints, and load behavior details only when verification or failure analysis needs it.

Workflow Task Types

The updated workflow specification adds first-class support for the task types needed by agentic API workflows.

Ask Task

ask pauses the workflow and waits for human input. It supports prompts, choices, validation, defaults, timeouts, and sensitive input.

The task returns the user's answer as task output. The normal export block should move the answer into workflow context.

Example:

- ask-authz:
    ask:
      prompt: Do you want to configure endpoint authorization?
      mode: choice
      options:
        - label: Configure authorization
          value: configure
        - label: Skip
          value: skip
    export:
      as:
        authzChoice: ${ .result }

Assert Task

assert validates workflow state or API results. It is used for both live tests and interactive workflows.

It supports simple comparisons, JSONPath-style checks, length checks, regex checks, and rule-engine-backed assertions for complex business logic.

Assertion failures should produce structured, catchable errors so workflows can route failures to remediation, task creation, or agent investigation. Complex business assertions can delegate to Light-Rule.

API Call Tasks

The workflow supports direct and description-backed API calls:

• HTTP / OpenAPI
• JSON-RPC
• OpenRPC
• gRPC
• MCP tool/resource/prompt calls

For direct internal calls, jsonrpc can be used with an endpoint, method, params, id, notification flag, and error policy.

For cataloged JSON-RPC, openrpc references an OpenRPC document and method.

For MCP, the workflow references a tool, resource, or prompt and passes arguments. MCP capability descriptions belong in the API description layer; the workflow only selects and invokes them.

Explanation Metadata

Tasks can include explain metadata to help an agent or UI explain what is happening.

Useful fields include:

• purpose
• visible
• before
• success
• failure
• requires

Example:

explain:
  purpose: Link the API instance to the development gateway.
  visible: true
  requires:
    - portal-command-token authentication
    - apiInstanceId from prior step

Human Task State

Human-in-the-loop behavior must be represented as durable workflow state.

Recommended task states:

A = active
W = waiting for input
C = completed
F = failed
X = canceled

When an ask or approval task reaches W, the process remains active but the task is no longer picked up by the executor. A user, CLI, scheduler, or agent must complete the task through the workflow API.

Waiting tasks should carry:

• prompt
• input mode
• options
• validation rules
• default value
• sensitive flag
• assignment metadata
• explanation metadata
• timeout policy

Assignment And Worklist

Enterprise workflows need more than chat. Some tasks must be assigned to roles or users and coordinated across multiple humans.

Human tasks should support:

• assigned user
• assigned role
• candidate roles
• claimed by
• claimed timestamp
• due timestamp
• priority
• comments
• audit trail

A role-based task appears in the worklist for users with a matching role. Once claimed, it belongs to the claiming user until completed, released, delegated, or timed out.

Client Architecture

light-workflow should run as a containerized backend service alongside other portal services. It owns workflow execution and state. Portal chat, worklist, CLI, scheduler, and agents are all clients of the same workflow APIs.

The client surfaces are:

• Portal Chat: conversational guidance for a single user.
• Worklist: role-based task inbox for approvals, reviews, and coordination.
• CLI: developer, CI/CD, live test, and automation interface.
• Scheduler: periodic headless execution, such as hourly live integration tests.
• Agent: task executor that can call APIs, use skills, and report results back to the workflow.

See Workflow Client Architecture for the dedicated client design.

Workflow Service API

The workflow service should expose one stable API boundary for all clients.

Core operations:

workflow.start
workflow.getInstance
workflow.listInstances
workflow.getEvents
workflow.listTasks
workflow.getTask
workflow.claimTask
workflow.releaseTask
workflow.completeTask
workflow.delegateTask
workflow.cancelInstance

Streaming clients should subscribe to workflow events through Server-Sent Events, WebSocket, or another portal-standard event mechanism.

Important event types:

• workflow started
• task started
• task completed
• task failed
• task waiting for input
• task assigned
• task claimed
• task completed by human
• agent started
• agent completed
• workflow completed
• workflow failed

Live Testing

The same workflow runtime should support interactive runs and headless live tests.

Interactive workflows use ask tasks when decisions or missing values are needed.

Live tests should use example data from LightAPI endpoint descriptions and workflow input fixtures instead of asking the user. Assertions should verify results through assert tasks or rule-engine checks.

This lets the scheduler run workflows every hour against the latest deployed services. When a test fails, the workflow can create a task with the failure detail and assign an agent or human to investigate.

Example: API Onboarding To AI Gateway

An API onboarding workflow can guide a user through a complex multi-endpoint process without requiring a dedicated UI for every operation.

The workflow can:

1. ask for or infer the API metadata
2. call the register API endpoint
3. create an API version from an OpenAPI specification
4. create a development API instance
5. configure the API
6. ask whether fine-grained authorization should be configured
7. route to create or select authorization rules
8. link the API instance to the development AI gateway
9. select endpoints to expose as MCP tools
10. create a gateway config snapshot
11. reload the gateway through controller
12. run MCP tests through the gateway
13. assert expected results
14. report success or create remediation tasks

The same workflow can run interactively through portal chat, be managed through the worklist, or run headlessly with examples as a live test.

Technical Implementation

The Light-Fabric implementation is split across:

• workflow-core: Rust models for the workflow specification.
• workflow-builder: fluent builders for programmatic workflow construction.
• light-workflow: runtime service and executor.
• light-agent: agent execution surface for delegated agent tasks.
• light-rule: rule engine used by workflow and assertion tasks. See Light-Rule Design.

Runtime responsibilities include:

• deserializing workflow definitions
• claiming active tasks
• executing supported task types
• storing task output
• applying exports into process context
• creating next tasks
• pausing waiting tasks
• resuming after human completion
• failing or completing process instances
• exposing workflow APIs to clients

The current executable slice supports API invocation and verification tasks such as HTTP, JSON-RPC, OpenRPC, MCP over enterprise HTTP transports, rules, assertions, and waiting human input. MCP stdio transport is intentionally not a priority for enterprise deployment.

Design Rule

There must be one workflow runtime and one task state model.

Chat, worklist, CLI, scheduler, and agents should never implement their own workflow execution. They should all use the same light-workflow service APIs.

This keeps enterprise workflow behavior auditable, testable, and consistent regardless of how a process is started, resumed, or observed.

Workflow Client Architecture

Light-Fabric workflow execution should run as a containerized backend service, not as logic embedded in a portal screen, CLI, scheduler, or agent. The workflow service owns process state, task state, audit records, API invocation, agent invocation, and human-in-the-loop transitions. Clients are thin interaction surfaces over the same service APIs.

This separation lets the same workflow instance be driven by a portal chat session, a worklist user, a CLI command, a scheduler, or an AI agent without creating multiple execution models.

Goals

• Provide one authoritative workflow runtime for long-running enterprise processes.
• Support human-in-the-loop tasks from both conversational and worklist interfaces.
• Support headless execution for live tests, scheduled runs, and CI/CD.
• Keep all clients stateless or lightly stateful; workflow state lives in light-workflow.
• Make role assignment, audit, and retry behavior consistent across UI, CLI, scheduler, and agent use.

Runtime Service

light-workflow should be deployed as a portal service in a container alongside the other portal services. It should expose APIs for workflow definitions, workflow instances, task claiming, task completion, event streaming, and operational control.

The service is responsible for:

• loading workflow definitions
• starting workflow instances
• persisting process_info_t and task_info_t
• executing API calls and assertions
• invoking agents for agent-owned tasks
• pausing on ask and approval tasks
• assigning human tasks to users or roles
• resuming workflows when a human answer is submitted
• emitting workflow and task events
• recording audit history

Clients should never execute workflow steps themselves. They should only start workflows, inspect workflow state, and complete assigned tasks.

Client Surfaces

Portal Chat

The portal chat client is the guided conversational interface for a single user working through a process. It is useful when the workflow needs to ask clarifying questions, explain the next action, or guide a user through a complex multi-endpoint operation.

Typical uses:

• API onboarding
• API endpoint publication to an AI gateway
• guided configuration
• troubleshooting and remediation workflows
• interactive approval with explanation

The chat client should call the workflow service for current state and submit answers to waiting tasks. It may stream workflow events and render agent explanations, but it should not own workflow state.

Worklist

The worklist is the enterprise task inbox. It is the right interface for multi-user coordination, role-based assignment, approvals, escalations, and audit-sensitive operations.

Typical uses:

• approval tasks
• compliance review
• operations handoff
• role-based queue processing
• task claim and release
• delegated work
• due-date and priority management

The worklist should be built around waiting human tasks. A task may have:

• assigned user
• candidate roles
• assigned role
• priority
• due time
• claim status
• comments
• completion payload
• audit trail

The worklist is especially important because many enterprise workflows are not purely conversational. They need accountable ownership and coordination between multiple humans.

CLI

The CLI is a developer and automation client. It should use the same workflow service APIs as portal-view and should not contain separate execution logic.

Typical uses:

• local workflow testing
• live parity tests
• CI/CD automation
• scheduled headless runs
• debugging stuck workflow instances
• submitting test data
• completing simple waiting tasks from scripts

Example commands:

light-workflow start portal.onboard-api --input input.yaml
light-workflow status <instance-id>
light-workflow tasks --role portal-admin
light-workflow claim <task-id>
light-workflow answer <task-id> --value approve
light-workflow logs <instance-id>
light-workflow cancel <instance-id>

The CLI should be added after the workflow APIs stabilize. It will be valuable for developers and automation, but the worklist and portal chat should drive the primary enterprise UX.

API Boundary

The workflow service should expose a stable API boundary that all clients use. The API can be HTTP, JSON-RPC, or both, but the concepts should remain the same.

Core operations:

workflow.start
workflow.getInstance
workflow.listInstances
workflow.getEvents
workflow.listTasks
workflow.getTask
workflow.claimTask
workflow.releaseTask
workflow.completeTask
workflow.delegateTask
workflow.cancelInstance

For streaming clients, the service should expose workflow events through Server-Sent Events, WebSocket, or another portal-standard event mechanism.

Important event types:

• workflow started
• task started
• task completed
• task failed
• task waiting for input
• task assigned
• task claimed
• task completed by human
• agent started
• agent completed
• workflow completed
• workflow failed

Human Task State

ask and approval-style tasks should enter a waiting state. While waiting, the workflow instance remains active, but the task is no longer executable by the worker loop until a human answer is submitted.

Recommended states:

A = active
W = waiting for input
C = completed
F = failed
X = canceled

The waiting task should include enough metadata for all clients:

• prompt
• input mode
• options
• validation rules
• default value
• sensitivity flag
• assignment metadata
• explanation metadata
• timeout policy

The completion API should validate submitted input against the task definition before resuming the workflow.

Assignment Model

Human tasks should support both direct assignment and role-based queues.

Recommended fields:

assigned_user
assigned_role
candidate_roles
claimed_by
claimed_ts
due_ts
priority
comments

A role-based task can appear in the worklist for all users with a matching role. Once a user claims it, the task becomes owned by that user until completed, released, delegated, or timed out.

Recommended Build Order

1. Implement stable workflow service APIs for start, status, events, task list, task claim, and task completion.
2. Harden the ask resume path and waiting task state machine.
3. Build the worklist because it forces the assignment, audit, and state model to be correct.
4. Build the portal chat workflow interaction on top of the same task APIs.
5. Add the CLI after the API shape stabilizes.
6. Add scheduler integration for hourly live tests and headless workflow runs.

Design Rule

There must be one workflow runtime and one task state model. Chat, worklist, CLI, scheduler, and agents are only clients of that runtime.

This keeps enterprise workflow behavior auditable, testable, and consistent regardless of how a workflow is started or resumed.

LightAPI Description Design

lightapi-description-specification

LightAPI Description is the endpoint capability specification used by Light-Fabric agents, workflows, live tests, and portal API administration.

It describes how an API endpoint is discovered, invoked, explained, and verified. It is intentionally separate from the Agentic Workflow Specification. Workflow describes process orchestration. LightAPI describes endpoint capability.

Why LightAPI

OpenAPI is useful for REST APIs, and OpenRPC is useful for JSON-RPC APIs, but Light-Fabric needs a common description model across multiple enterprise protocols:

• REST / HTTP
• OpenAPI-described HTTP
• JSON-RPC 2.0
• OpenRPC-described JSON-RPC
• gRPC
• MCP tools, resources, and prompts

LightAPI provides a single agent-facing and workflow-facing description layer over these protocols.

The goal is not to replace OpenAPI or OpenRPC. The goal is to reference them where they exist and add the missing information needed by agents and workflow live tests.

API-Level Authoring, Endpoint-Level Consumption

Light-Portal may let teams author descriptions at the API level for convenience. However, workflows and agents consume descriptions at the endpoint level.

This distinction is important because real workflow processes rarely use a whole API. They usually combine selected endpoints from multiple APIs.

For example, onboarding an API to an AI gateway may consume:

• one endpoint from API registration
• one endpoint from API version management
• one endpoint from API instance management
• one endpoint from config server
• one endpoint from gateway linking
• one endpoint from controller reload
• one or more MCP tools exposed through the gateway

Each consumed operation should have an endpoint-level description with a stable endpointId.

API-level descriptions are still useful as catalogs. Endpoint-level descriptions may inherit shared API context such as:

• environments
• authentication
• secrets
• sources
• common tags
• lifecycle metadata

Relationship To Agentic Workflow

Agentic Workflow and LightAPI have different responsibilities.

In live tests, the workflow should use example data from LightAPI descriptions and workflow fixtures instead of asking for user input.

In interactive runs, the workflow may ask the user for missing values, then invoke endpoints described by LightAPI.

Relationship To Centralized Agent Skills

LightAPI endpoint descriptions are a source of agent skills.

The centralized skill registry should not require every API operation to be manually rewritten as a separate skill. Instead, Light-Portal can publish selected LightAPI endpoint descriptions into the skill registry as invokable capabilities.

The skill registry adds:

• permission-aware discovery
• semantic search
• skill grouping
• agent persona scoping
• audit around skill disclosure and execution

LightAPI provides:

• endpoint identity
• protocol details
• input schema
• request mapping
• result shape
• examples
• behavior notes
• result cases

Together, they allow an agent to discover a capability as a skill, progressively load only the endpoint details it needs, and execute through the workflow or controller runtime.

See Centralized Agentic Skill Registry for the skill registry design.

Core Document Concepts

A LightAPI document should support both API-level catalogs and endpoint-level documents.

Important top-level concepts:

• lightapi: specification version
• profile: api or endpoint
• info: name, title, version, namespace, owner, contact
• context: inherited catalog context for endpoint-level documents
• sources: OpenAPI, OpenRPC, protobuf, MCP, or raw protocol references
• environments: environment-specific server details
• secrets: required secret names
• authentications: reusable authentication policies
• operations: endpoint operation descriptions
• testSequences: linear endpoint test sequences
• agent: progressive disclosure and skill metadata

For profile: endpoint, the document should describe at most one operation.

Operation Model

Each operation represents one endpoint-level capability.

Common fields include:

• operationId: local operation identifier
• endpointId: globally stable endpoint identifier
• title
• summary
• description
• visibility
• lifecycle
• tags
• capability
• agent
• input
• request
• result
• examples

The input section describes the logical interface the agent or workflow sees.

The request section describes how logical input maps to the wire protocol.

The result section describes expected output, result cases, and failure shapes.

Protocol Coverage

HTTP And OpenAPI

For raw HTTP, the operation describes method, endpoint, headers, query, path, and body mappings.

For OpenAPI, LightAPI references the OpenAPI document and operation, then adds agent-oriented behavior, examples, and result expectations.

JSON-RPC And OpenRPC

For direct JSON-RPC, the operation describes endpoint, method, params, id behavior, notification behavior, and error policy.

For OpenRPC, LightAPI references the OpenRPC document and method. The workflow runtime can use the OpenRPC document to validate that the method exists and that required params are present before calling it.

gRPC

For gRPC, the operation describes service, method, protobuf source, transport, metadata, request mapping, and result mapping.

For browser or gateway-mediated enterprise deployments, gRPC over WebSocket can be represented as a transport on the structured protocol operation.

MCP

For MCP, the operation describes tool, resource, or prompt invocation.

Tool listing alone is not enough. The description must also include:

• input schema
• result shape
• examples
• behavior differences for important input cases
• error cases
• verification expectations

MCP stdio is not a priority for enterprise portal deployment. HTTP and streamable HTTP transports should be the main runtime targets.

Result Cases And Verification

LightAPI should describe expected result behavior, but Agentic Workflow should execute the actual assertions.

This keeps verification orchestration in one place.

Recommended model:

• LightAPI operation result cases describe expected outputs, failure shapes, and examples.
• Workflow test steps invoke the operation.
• Workflow assert tasks verify actual output against expected result cases.
• Complex business checks can call the rule engine.

This allows the same endpoint description to support:

• agent skill usage
• workflow execution
• live integration testing
• failure diagnosis

Progressive Disclosure For Agents

A LightAPI document should support progressive disclosure so an agent can load only the information needed at each stage.

Recommended levels:

• index: endpoint id, title, tags, visibility
• summary: purpose, capability group, lifecycle
• invocation: input schema, request mapping, authentication, examples
• behavior: result cases, edge cases, errors, assertions
• full: complete endpoint description

The portal can expose query APIs such as:

lightapi.listOperations
lightapi.getOperation
lightapi.getCapabilityGroup

Agents should start with index or summary data, load invocation details only for selected endpoints, and load behavior details only for testing, troubleshooting, or failure repair.

Portal Publishing Flow

Light-Portal should manage endpoint descriptions as part of API endpoint administration.

Recommended flow:

1. API owner creates or imports API metadata.
2. Portal extracts initial endpoint descriptions from OpenAPI, OpenRPC, protobuf, MCP, or raw endpoint configuration.
3. API owner enriches endpoint descriptions with examples, behavior notes, result cases, and visibility.
4. Portal stores endpoint-level LightAPI descriptions.
5. Authorized agents and workflows query descriptions by endpoint, tag, lifecycle, visibility, or capability.
6. Selected endpoints can be published into the centralized skill registry.
7. Workflow instances reference endpoint descriptions during execution and live testing.

Live Test Use

Live tests should be workflow-driven.

LightAPI supplies:

• example input data
• expected result cases
• protocol invocation details
• error behavior

Agentic Workflow supplies:

• sequence
• fixtures
• environment selection
• endpoint invocation
• assertions
• failure routing
• task creation
• agent assignment

This avoids building a second test runner model outside the workflow engine.

Design Rule

LightAPI describes endpoint capability. Agentic Workflow orchestrates endpoint use. Centralized Skills expose selected capabilities to agents.

Keeping these responsibilities separate lets Light-Fabric support API administration, agent skill discovery, workflow execution, and live integration testing without duplicating endpoint definitions across multiple systems.

Light-Rule Design

rule-specification

Light-Rule is the local YAML rule engine used by Light-Fabric services and workflows for deterministic business checks, transformations, authorization decisions, and workflow assertions.

It complements agentic workflow by keeping critical decisions explicit, repeatable, and auditable. Agents can propose or select rules, but the rule engine executes the deterministic logic.

Purpose

Light-Rule is designed for enterprise services that need fast local policy and transformation logic without a database call on every request.

Primary uses:

• fine-grained authorization
• request transformation
• response transformation
• response row and column filtering
• workflow assertions
• business validation
• permission and filter injection
• reusable rule templates selected from Light-Portal

The rule configuration is loaded locally by the target service. When permissions or rule mappings change, the controller can trigger a config reload so the service swaps to the latest rules.

Relationship To Agentic Workflow

Agentic Workflow orchestrates process steps. Light-Rule evaluates deterministic logic inside those steps.

Workflow uses Light-Rule in two main ways:

1. Rule call task A workflow task can call a named rule to validate or mutate workflow context.

2. Assert task extension Simple checks can be handled directly by assert, while complex business checks can delegate to Light-Rule.

This separation keeps workflows readable. The workflow says when a check happens; Light-Rule defines the reusable business logic for the check.

Example workflow responsibilities:

• decide when authorization configuration is needed
• select or create a rule
• invoke a rule during live testing
• route failures to a human or agent

Example Light-Rule responsibilities:

• evaluate role, group, position, or attribute checks
• inject endpoint permissions into the context
• compute row or column filters
• execute transformation plugins
• return pass/fail for business assertions

See Agentic Workflow Design for the workflow orchestration model.

Relationship To LightAPI

LightAPI endpoint descriptions describe endpoint invocation and expected result behavior. Light-Rule can implement complex result checks that are too business-specific for simple schema assertions.

Recommended model:

• LightAPI describes endpoint result cases and expected behavior.
• Agentic Workflow invokes the endpoint and runs assert tasks.
• assert handles simple checks directly.
• Light-Rule handles complex checks, authorization logic, row filters, column filters, and reusable business policies.

See LightAPI Description Design for endpoint capability descriptions.

Rule Specification

Rules are described by the rule specification in rule-specification/schema/rule.yaml.

The top-level configuration contains:

• ruleBodies: named rule definitions
• endpointRules: endpoint-to-rule mappings

Each rule can contain:

• ruleId
• ruleDesc
• ruleType
• version
• author
• updatedAt
• conditions
• conditionLanguage
• conditionSecurityProfile
• expression
• actions

Each endpoint mapping can contain:

• req-tra: request transformation rules
• res-tra: response transformation rules
• req-acc: request access rules
• res-fil: response filter rules
• access-control: legacy or compatibility access control rules
• permission: permission values injected into context
• x-*: extension rule phases

Rule Conditions

Conditions evaluate fields in the input context.

Light-Fabric supports CEL rule conditions only. A Light-Fabric rule uses conditionLanguage: cel and a single boolean expression, with an optional conditionSecurityProfile.

The native condition-row format with operand, operator, expected, and joinCode is a legacy format from the Java yaml-rule implementation. It can be documented for migration and compatibility, but it is not supported by Light-Fabric rule execution. Keep the detailed CEL contract in CEL Rule Conditions; this page documents how CEL fits into the broader Light-Rule model.

Legacy Native Conditions

Supported operand forms:

• direct field: role
• dotted path: user.role
• JSON Pointer: /user/role
• JSONPath-like path: $.user.roles[0]

Supported operators:

==
!=
>
<
>=
<=
eq
ne
contains
matches
startsWith
endsWith
exists
notExists

expected is typed and may be a string, number, boolean, array, object, or null.

Flat condition arrays are evaluated left-to-right. joinCode combines the current condition with the previous result.

A AND B OR C

is evaluated as:

(A AND B) OR C

If explicit grouping is required, split logic into multiple rules and combine them through endpoint mapping or workflow orchestration.

These native condition rows are included here only to document the legacy Java yaml-rule shape. New Light-Fabric rules must use CEL.

CEL Conditions

CEL rules use conditionLanguage: cel and store the predicate in expression. The expression must evaluate to a boolean. If it evaluates to false, the rule actions do not run.

ruleBodies:
  allowOfferSearch:
    ruleId: allowOfferSearch
    ruleType: req-acc
    conditionLanguage: cel
    conditionSecurityProfile: strict
    expression: >
      auditInfo.subject_claims.ClaimsMap.role != null
      && toolArguments.category == "travel"
    actions:
      - actionClassName: com.networknt.rule.RoleBasedAccessControlAction

CEL expressions should be used for rule eligibility and business predicates. Endpoint-specific role lists, row filters, column filters, and similar policy values should still live under permission so API owners can change policy data without editing the reusable rule body.

CEL must not be used as a general JSON mutation language. A CEL expression can answer whether a rule applies, or whether a specific row should be kept when an action provides a row-scoped CEL context. It should not directly rewrite responseBody, add or remove fields, or execute side effects.

Rule Actions

Actions execute plugin logic after conditions pass.

An action contains:

• actionId
• actionClassName
• actionValues

actionClassName identifies the registered plugin. actionValues carries plugin-specific configuration.

Typical action plugins:

• add values to request context
• inject permission attributes
• compute filters
• transform request body
• transform response body
• call a local business function

Actions are intentionally plugin-based so the schema remains stable while implementation logic can evolve.

For response filtering, standard actions remain the transformation boundary. ResponseRowFilterAction and ResponseColumnFilterAction own row and column mutation, shape-specific handling, failure behavior, and audit logging. If a use case needs richer row predicates, add a CEL-aware action such as ResponseCelRowFilterAction that evaluates a CEL predicate for each row. Do not expose raw response-body mutation functions to CEL.

Response filtering should parse the response JSON once for the whole res-fil phase, pass the mutable JSON value through the ordered action pipeline, and serialize once at the end. Individual actions should not repeatedly parse and serialize responseBody when multiple filters are configured on the same endpoint.

Endpoint Rule Phases

Endpoint mappings define when rules run.

Request Transformation

req-tra rules run before the service handles the request. They can enrich or transform request context.

Response Transformation

res-tra rules run after the service produces a response. They can filter, redact, or reshape response data.

Request Access

req-acc rules validate whether a request is allowed before the target handler or backend service runs. These rules normally run in parallel because they should not mutate shared state.

access-control can be accepted as a compatibility phase by runtimes that need to load older configuration, but new endpoint mappings should use req-acc.

Response Filtering

res-fil rules run after the target service produces a response and before the caller receives it. They are used for row filters, column filters, response masking, and other response-reduction policies that should not be implemented inside the business API.

res-fil rules always execute as a sequential pipeline in the order listed on the endpoint. accessRuleLogic applies only to req-acc; it does not change response-filter execution semantics.

Permission Injection

permission values are injected into the evaluation context before rule execution. This lets API owners configure roles, groups, attributes, row filters, or column filters without editing the technical rule body.

Extension Phases

Custom phases must use the x-* prefix. This avoids silent typos in standard phase names while preserving controlled extensibility.

Execution Model

The Rust implementation lives in crates/light-rule.

Core components:

• RuleConfig: top-level config model
• Rule: rule definition
• RuleCondition: condition model
• RuleAction: action model
• RuleEngine: evaluates one rule
• ActionRegistry: maps action class names to plugins
• MultiThreadRuleExecutor: executes rule lists and endpoint phase mappings

Sequential phases such as req-tra and res-tra should run with all semantics so transformations happen in order.

Access control can run in parallel because it should be a validation step rather than a mutation step.

Response filtering should run sequentially when multiple filters can depend on the same fields. For example, a row filter that checks active == true must run before a column filter that removes the active field from the final response.

Why Not Replace With Cedar Or Casbin

Cedar and Casbin are strong policy engines, but Light-Rule has a different role in this platform.

Light-Rule supports:

• local YAML configuration
• request and response transformation
• permission injection
• row and column filters
• endpoint-specific rule selection
• technical-team-authored reusable rules
• API-owner-selected rule parameters
• config reload through controller

Cedar is excellent for authorization policy, but it does not naturally cover transformation, row filter, and column filter use cases. Casbin is strong for policy enforcement, but it introduces a different policy storage and matching model.

Light-Rule should remain the built-in rule engine for Light-Fabric service configuration and workflow assertions. External policy engines can still be integrated as action plugins if needed.

Governance

Rule bodies should be authored and reviewed like code or controlled configuration.

Recommended governance metadata:

• version
• author
• updatedAt
• ruleDesc

Recommended operational controls:

• validate rule YAML against the schema before publishing
• reject endpoint phase typos
• keep ruleId equal to the ruleBodies map key
• audit rule publication and reload events
• test rules with representative input contexts
• use workflow live tests to verify rules in integrated environments

Workflow Live Testing

Light-Rule is useful in live tests because it can express business checks that are more specific than generic JSON assertions.

Example flow:

1. Workflow invokes an endpoint using LightAPI description.
2. Workflow captures the endpoint response.
3. assert verifies simple fields.
4. A rule task validates business-specific behavior.
5. On failure, workflow creates a task for a human or agent to investigate.

This keeps live test orchestration in workflow while preserving reusable business rules in Light-Rule.

Design Rule

Use workflow for process control. Use LightAPI for endpoint capability. Use Light-Rule for deterministic business logic.

Agents may select, explain, or help author rules, but the rule engine should execute the final deterministic decision.

CEL Rule Conditions

Light-Fabric supports CEL rule conditions only. A Light-Fabric rule uses conditionLanguage: cel and one rule-level CEL boolean expression.

The old native condition schema with condition rows, operators, and joinCode is a legacy Java yaml-rule format. It can still be documented for migration and Java compatibility, but it is not a supported Light-Fabric runtime condition format.

Each Light-Fabric rule should therefore use CEL. Mixing native condition rows and CEL expressions inside the same rule is not a canonical model because it makes portal authoring, validation, and runtime dispatch harder to reason about.

Goals

• support CEL expressions as the Light-Fabric rule-level condition language
• reuse the existing rule context for gateway, workflow, and test execution
• preserve existing actions, endpointRules, and rule phase semantics
• let Light-Portal choose the correct editor from rule metadata without parsing arbitrary rule bodies
• validate CEL before publishing or reloading rules where possible
• keep CEL execution deterministic and side-effect free

Non-Goals

• replacing actions with CEL
• allowing CEL expressions to perform I/O, network calls, mutation, or service lookups
• allowing CEL expressions to directly mutate responseBody or perform general JSON transformations
• supporting the legacy Java yaml-rule native condition-row format in Light-Fabric
• supporting mixed native and CEL condition blocks in the canonical portal authoring flow

Current Model

The legacy Java yaml-rule model contains an optional flat list of native conditions:

ruleBodies:
  allowMcpReader:
    common: Y
    ruleId: allowMcpReader
    ruleName: Allow MCP reader
    ruleType: req-acc
    conditions:
      - operatorCode: isNotNull
        propertyPath: auditInfo.subject_claims.ClaimsMap.role
    actions:
      - actionClassName: com.networknt.rule.RoleBasedAccessControlAction

Each legacy native condition contains:

• operator
• operand
• expected
• joinCode

The Java yaml-rule engine evaluates conditions left-to-right. joinCode combines each condition with the accumulated result. This format is shown here only as migration context.

Portal persistence stores rule metadata in rule_t and the executable rule JSON in rule_t.rule_body. Today there is no dedicated column that tells the portal which condition editor to render, so the UI would have to inspect rule_body.

Proposed Rule Shape

Use a rule-level condition language flag. Light-Fabric accepts cel for a single CEL expression. native is reserved for legacy Java yaml-rule data and must not be emitted to Light-Fabric runtime configuration.

Persist the flag in both places:

• rule_t.condition_language: indexed/listable portal metadata
• ruleBody.conditionLanguage: self-contained exported runtime configuration

Recommended Light-Fabric value:

cel

Legacy Java yaml-rule native rule body:

ruleBodies:
  allowMcpReader:
    common: Y
    ruleId: allowMcpReader
    ruleName: Allow MCP reader
    ruleType: req-acc
    conditionLanguage: native
    conditions:
      - operatorCode: isNotNull
        propertyPath: auditInfo.subject_claims.ClaimsMap.role
    actions:
      - actionClassName: com.networknt.rule.RoleBasedAccessControlAction

CEL rule body:

ruleBodies:
  allowApprovedTransfer:
    common: Y
    ruleId: allowApprovedTransfer
    ruleName: Allow approved transfer
    ruleType: req-acc
    conditionLanguage: cel
    conditionSecurityProfile: strict
    expression: >
      auditInfo.subject_claims.ClaimsMap.role != null
      && 'roles' in permission
      && permission.roles != null
      && permission.roles.exists(r, r == auditInfo.subject_claims.ClaimsMap.role)
    actions:
      - actionClassName: com.networknt.rule.RoleBasedAccessControlAction

Recommended database shape:

ALTER TABLE rule_t
ADD COLUMN condition_language VARCHAR(16) DEFAULT 'cel' NOT NULL;

ALTER TABLE rule_t
ADD COLUMN condition_security_profile VARCHAR(32);

ALTER TABLE rule_t
ADD CONSTRAINT rule_t_condition_language_check
CHECK (condition_language IN ('cel'));

ALTER TABLE rule_t
ADD CONSTRAINT rule_t_condition_security_profile_check
CHECK (
  condition_security_profile IS NULL
  OR condition_security_profile IN ('strict', 'standard', 'internal-admin')
);

Recommended schema rules:

• conditionLanguage is optional and defaults to cel
• conditionLanguage: cel requires expression and rejects conditions
• conditionSecurityProfile is optional and names a runtime-defined profile
• conditionLanguage: native is rejected by Light-Fabric runtime config
• unknown rule and condition fields should continue to be rejected by the schema
• command handlers should reject requests where the DB metadata and rule body condition language disagree

This can be represented with conditional validation in rule-specification/schema/rule.yaml:

allOf:
  - if:
      properties:
        conditionLanguage:
          const: cel
      required: [conditionLanguage]
    then:
      required: [expression]
      not:
        required: [conditions]
    else:
      properties:
        conditionLanguage:
          const: cel

The Rust model can add optional fields to Rule:

#![allow(unused)]
fn main() {
pub condition_language: Option<String>,
pub condition_security_profile: Option<String>,
pub expression: Option<String>,
}

This is less disruptive than changing RuleCondition into an enum and keeps old rule bodies valid.

Cross-Repository Scope

This change crosses the rule specification, runtime engines, portal services, and portal UI. The implementation should be tracked as a coordinated change rather than a light-fabric-only feature.

portal-db is listed even though it is not a rule engine because rule_t lives there. Without the DB column, portal-view would need to parse the compact rule body to choose the editor, which is the coupling this design is trying to avoid.

Operator Alias Alternative

Another possible shape is to add operatorCode: cel and store the CEL expression in expected inside conditions:

conditions:
  - operatorCode: cel
    expected: >
      context.toolArguments.amount < 1000
      || ('roles' in context.permission
          && context.permission.roles != null
          && context.permission.roles.exists(r, r == "approver"))

This has one advantage for legacy Java yaml-rule imports: operator, operand, and expected already exist. It is not useful as the Light-Fabric runtime contract because Light-Fabric does not support native condition rows.

It should not be the canonical schema because:

• CEL is a full boolean expression, not a comparison operator
• overloading expected makes validation and portal rendering less clear
• operand becomes ignored or artificial
• the UI still has to draw a condition-row editor even though the rule is really a single expression
• future expression languages would continue overloading legacy native condition fields

The recommended contract is therefore:

• canonical form: conditionLanguage: cel plus rule-level expression
• reject operatorCode: cel for Light-Fabric runtime config
• normalize any legacy import to the canonical rule-level CEL model before persistence or runtime export

Mixed Conditions Alternative

Another possible shape is to allow native and CEL conditions in the same conditions array. Light-Fabric should not support this. Native condition rows belong to the legacy Java yaml-rule model only.

Reasons to avoid canonical mixed rules:

• Light-Portal would need a hybrid editor that switches row-by-row
• validation errors become harder to explain to non-technical users
• joinCode semantics across native and CEL expressions are correct but subtle
• users may expect CEL operator precedence inside the whole rule even though native joinCode remains left-to-right
• runtime dispatch is simpler and faster when the rule selects one evaluator

If mixed rules are accepted from an import path, they must be normalized to a single rule-level CEL expression before they are persisted or exported to Light-Fabric runtime configuration.

Execution Model

Rule execution should dispatch by conditionLanguage once per rule:

RuleEngine::execute_rule
  -> conditionLanguage == cel
     -> evaluate rule expression
  -> execute actions when conditions pass

The outer behavior stays unchanged:

• rules with no conditions continue to run actions
• CEL rules without an expression fail validation before runtime
• failed conditions skip actions
• failed action execution fails the rule
• endpoint rule ordering and access-control logic stay unchanged
• req-tra and res-tra continue to run sequentially
• access-control rules can still be evaluated independently

Runtime should treat a missing conditionLanguage as cel only when an expression is present. Native condition-row payloads must be rejected by Light-Fabric config validation.

CEL And Response Filtering

CEL is the rule predicate language, not the response mutation engine. A rule-level CEL expression decides whether a res-fil rule applies. The response body is then transformed by a standard action.

This keeps the contract narrow:

• CEL expressions are side-effect free and return booleans.
• Actions own mutation of responseBody.
• Actions decide how JSON arrays, JSON objects, and malformed payloads are handled.
• Actions provide stable audit and failure behavior.
• The runtime can compile and cache rule-level CEL independently from response-body parsing.
• The response-filter pipeline parses JSON once, lets actions mutate the same in-memory value, and serializes once after all res-fil actions complete.
• The parsed mutable response value is action-owned state and must not be exposed as a rule-level CEL mutation target.

The default response-filter actions should stay declarative:

• ResponseRowFilterAction: applies permission-defined row filters.
• ResponseColumnFilterAction: applies permission-defined column keep or remove lists.

Rule bodies should keep using the actions[].actionClassName field even when the runtime is Rust. In Rust this value is not a Java class name. It is a stable action registry key that selects the Rust action implementation. The Rust gateway registers both the Java-compatible fully qualified names and short aliases:

• com.networknt.rule.ResponseRowFilterAction
• ResponseRowFilterAction
• com.networknt.rule.ResponseColumnFilterAction
• ResponseColumnFilterAction
• com.networknt.rule.ResponseCelRowFilterAction
• ResponseCelRowFilterAction

For portal-authored and exported rules, prefer the fully qualified Java-compatible names. They preserve compatibility with existing yaml-rule configuration, schemas, import/export flows, and any Java runtime that reads the same rule bodies:

ruleBodies:
  rowFilterByJwtClaims:
    common: Y
    ruleId: rowFilterByJwtClaims
    ruleName: Row filter by JWT claims
    ruleType: res-fil
    conditionLanguage: cel
    conditionSecurityProfile: strict
    expression: >
      row != null
      && (
        ("role" in row && "role" in auditInfo.subject_claims.ClaimsMap)
        || ("group" in row
            && ("grp" in auditInfo.subject_claims.ClaimsMap
                || "group" in auditInfo.subject_claims.ClaimsMap))
        || ("position" in row
            && ("pos" in auditInfo.subject_claims.ClaimsMap
                || "position" in auditInfo.subject_claims.ClaimsMap))
        || ("attribute" in row
            && ("att" in auditInfo.subject_claims.ClaimsMap
                || "attribute" in auditInfo.subject_claims.ClaimsMap))
      )
    actions:
      - actionClassName: com.networknt.rule.ResponseRowFilterAction

  colFilterByJwtClaims:
    common: Y
    ruleId: colFilterByJwtClaims
    ruleName: Column filter by JWT claims
    ruleType: res-fil
    conditionLanguage: cel
    conditionSecurityProfile: strict
    expression: >
      col != null
      && (
        ("role" in col && "role" in auditInfo.subject_claims.ClaimsMap)
        || ("group" in col
            && ("grp" in auditInfo.subject_claims.ClaimsMap
                || "group" in auditInfo.subject_claims.ClaimsMap))
        || ("position" in col
            && ("pos" in auditInfo.subject_claims.ClaimsMap
                || "position" in auditInfo.subject_claims.ClaimsMap))
        || ("attribute" in col
            && ("att" in auditInfo.subject_claims.ClaimsMap
                || "attribute" in auditInfo.subject_claims.ClaimsMap))
      )
    actions:
      - actionClassName: com.networknt.rule.ResponseColumnFilterAction

The rule-level CEL expression only decides whether the response-filter action runs. The action reads the endpoint permission.row or permission.col configuration and matches it against JWT claims. The response-filter action understands these permission dimensions:

• role: matched against the JWT role claim
• group: matched against grp or group
• position: matched against pos or position
• attribute: matched against att or attribute
• user: matched against uid, user_id, or sub

For example:

endpointRules:
  /v1/accounts@get:
    res-fil:
      - rowFilterByJwtClaims
      - colFilterByJwtClaims
    permission:
      row:
        role:
          manager:
            - colName: status
              operator: =
              colValue: ACTIVE
        group:
          finance:
            - colName: department
              operator: =
              colValue: FIN
        position:
          director:
            - colName: level
              operator: ">="
              colValue: "5"
        attribute:
          region-east:
            - colName: region
              operator: =
              colValue: EAST
      col:
        role:
          manager: id,name,status,department
        group:
          finance: id,name,balance,status
        position:
          director: id,name,balance,status,level
        attribute:
          region-east: id,name,region,status

If a row predicate needs CEL, add an explicit CEL-aware action rather than turning rule-level CEL into a JSON transformation DSL:

ruleBodies:
  filterOfferRows:
    ruleId: filterOfferRows
    ruleType: res-fil
    conditionLanguage: cel
    conditionSecurityProfile: strict
    expression: >
      statusCode == 200 && responseBody != ""
    actions:
      - actionClassName: com.networknt.rule.ResponseCelRowFilterAction
        actionValues:
          rowExpression: >
            auditInfo.subject_claims.ClaimsMap.role == "offer-admin"
            || (row.priority < 50 && row.active == true)

ResponseCelRowFilterAction would compile rowExpression at rule-load time and evaluate it once per candidate row with a curated context containing row, auditInfo, headers, endpoint, permission, and request metadata. The implementation should avoid deep-cloning the full base context for every row. Use a child CEL context that shadows row, or reuse one mutable evaluation context and replace only the row variable before each evaluation.

Row-level CEL evaluation errors should be row-local by default. If a row is missing a referenced field or its predicate evaluation returns an error, drop that row and emit debug or trace diagnostics with the rule id and field error. Only configuration errors, such as an invalid rowExpression that fails to compile, should fail the entire action closed.

Column filtering should remain declarative unless there is a proven use case for dynamic column predicates. Role, group, attribute, user, and position based field lists are easier to review, safer to render in Portal, and cheaper to execute than arbitrary column-level CEL.

Column filtering must also support top-level JSON objects, not only arrays or objects containing items. Single-object responses such as GET /offers/123 still need field hiding. Row filtering also treats a top-level JSON object as a single candidate row. HTTP filtering replaces a denied object with an empty object, while MCP filtering returns a tool error with isError: true.

Rule Context

CEL should evaluate against the rule engine JSON context. For gateway access-control and response filtering, this includes fields such as:

• auditInfo
• headers
• endpoint
• toolName
• toolArguments
• correlationId
• responseBody
• statusCode

Endpoint permission values are merged into the root context as their configured keys. For example, permission.roles in endpointRules is available to conditions as roles, response row filters are available as row, and column filters are available as col. A future runtime can also expose a namespaced permission object as an additive convenience, but CEL support should not require that shape to preserve compatibility with existing actions.

For standard and internal-admin profiles, the CEL environment can expose variables in two ways:

• top-level context fields as direct CEL variables, such as auditInfo, toolArguments, and roles
• the full root object as context, so expressions can use explicit paths such as context.toolArguments.amount

Direct variables keep expressions concise. The context variable is safer for generated expressions, collision avoidance, and future fields that are not valid CEL identifiers.

For the strict profile, the runtime should expose only curated root variables such as auditInfo, headers, toolArguments, endpoint metadata, and permission values needed by the rule phase. It should not expose the full context object by default. This prevents future internal runtime metadata from becoming visible to tenant-authored CEL just because it was appended to the root request context.

The context contract should be documented as part of Light-Rule because CEL expressions depend on stable field names. Adding fields is compatible. Renaming or changing field shapes is a breaking change for CEL rules.

Type Mapping

The CEL evaluator should receive deterministic values converted from serde_json::Value:

• JSON object to CEL map
• JSON array to CEL list
• JSON string to CEL string
• JSON number to CEL integer or double
• JSON boolean to CEL bool
• JSON null to CEL null

Missing fields should evaluate according to the chosen CEL implementation's standard behavior. The rule test API should expose these failures clearly so authors can distinguish "expression false" from "expression invalid".

Authors should guard optional fields explicitly. Depending on the selected CEL runtime and the field shape, this can use presence checks such as has(...) or map membership checks such as:

"role" in auditInfo.subject_claims.ClaimsMap
  && auditInfo.subject_claims.ClaimsMap.role == "admin"

The portal rule tester should surface missing-field evaluation errors and suggest guarded expressions instead of letting these failures look like ordinary denied rules.

Context Injection Performance

CEL expressions run on request paths, so context conversion must be controlled. The implementation should not recursively deep-clone and convert large JSON payloads separately for every CEL rule evaluation.

Recommended approach:

• compile expressions once at rule load
• build the rule context once per request or response phase
• reuse converted CEL variables across evaluations in the same request or response phase when possible
• prefer lazy or reference-backed variable resolution if the selected CEL crate supports it
• if eager conversion is required, convert only the variables exposed to CEL and avoid parsing large string fields such as responseBody unless an expression explicitly needs structured access to them
• for per-row CEL, avoid cloning the full base context for each row; use a child context or reusable mutable context that changes only the row binding
• benchmark access-control and response-filter scenarios before enabling CEL by default in high-throughput paths

The initial implementation can be pragmatic, but performance tests should guard against accidentally making CEL expression evaluation proportional to the full response body size when the expression only needs claims or endpoint metadata.

Validation

CEL should be validated earlier than request execution.

Recommended validation points:

• portal rule editor
• rule command create/update handler
• rule test API
• runtime config reload

Validation must enforce the Light-Fabric rule shape:

• cel: expression is required, conditions is rejected
• native: rejected by Light-Fabric runtime config
• persisted rule_t.condition_language must match ruleBody.conditionLanguage
• persisted rule_t.condition_security_profile must match ruleBody.conditionSecurityProfile when either side is present

Runtime reload should reject invalid CEL when strict validation is enabled. If a service must preserve availability, it can keep the last known-good rule set and report the new config as rejected.

Approval workflow should not bypass validation. For profile escalation requests, the command path should validate the submitted rule shape and expression before creating the approval task. Final approval should revalidate the exact submitted rule body before emitting the active rule event.

Validation output should include:

• rule id
• condition language
• parse or type error
• source offset when provided by the CEL implementation

Compilation And Caching

Do not compile CEL on every request. Compile once per rule load and cache the compiled program with the loaded rule set.

Recommended cache key:

ruleId + expression hash + effective profile

The compiled expression cache should be replaced atomically when the rule config reloads. It should not outlive the rule version it was compiled from. Old compiled entries must be evicted during reload so repeated rule updates cannot leak memory through stale expression hashes.

Rust CEL Library

Light-Rule uses the cel crate for the Rust implementation. It provides Program::compile(...), Program::execute(...), a Context for variables and functions, and compiled Program values that are Send + Sync.

Implementation should still be isolated behind a small internal trait:

CelEvaluator
  -> compile(ruleId, expression) -> compiled expression
  -> evaluate(compiled expression, serde_json::Value context) -> bool

This keeps Light-Rule from leaking third-party crate types through its public model and allows the implementation to change if CEL crate maturity, feature flags, or Java parity requirements change.

Legacy Operator Migration

Legacy Java yaml-rule native conditions include operators that may not map one-to-one to the selected CEL runtime. Examples include:

• containsIgnoreCase
• matches and notMatch
• inList and notInList
• containsAny, containsAll, and containsNone
• date-style comparisons such as before, after, and on

Before importing legacy native rules into Light-Fabric, the implementation should define a small compatibility function registry for any gaps and convert the rule to CEL. Candidate pure helper functions include:

contains_ignore_case(value, substring)
matches(value, pattern)
in_list(value, values)
contains_any(value, values)
contains_all(value, values)

These functions must be deterministic, side-effect free, and shared by the rule tester and runtime evaluator. If Java parity is required, the same function names and edge-case behavior should be implemented in the Java runtime.

Safety

CEL support should be deterministic and sandboxed.

The evaluator does not need an operating-system sandbox for normal trusted/admin-authored rule configuration. CEL is an interpreted expression language, not arbitrary Rust or JavaScript execution, and expressions can only resolve variables and functions registered in the CEL context. The CEL context is therefore the primary sandbox boundary.

For the Rust cel integration, context construction should be explicit. Context::default() exposes standard pure CEL functions such as size, contains, string helpers, type conversions, regex matches, and time parsing helpers depending on enabled crate features. If a service accepts tenant-authored or otherwise untrusted CEL, prefer Context::empty() and add only platform-approved helper functions.

Security policy should be engine-owned. A rule may request a named condition security profile, but it must not define its own function allowlist, size limits, resource limits, or isolation mode. If a rule author controls the rule body, then inline security settings are also attacker-controlled.

Recommended policy model:

runtime config defines profiles:
  strict
  standard
  internal-admin

rule optionally requests:
  conditionSecurityProfile: strict

effective policy:
  runtime maximum profile intersected with requested profile

If a rule omits conditionSecurityProfile, the runtime default applies. If a rule requests a profile that the service, tenant, or rule phase does not allow, the rule config should be rejected during validation or runtime reload. The engine may choose a stricter profile than requested, but it must never choose a weaker one because the rule requested it.

Recommended profiles:

• strict: default for tenant-authored, portal self-service, imported, or marketplace-style CEL. Use an empty CEL context, expose only approved variables, add only pure helper functions, and enforce tight size and expression-shape limits. Do not expose the full context root, and disable regex until both Java and Rust provide matching bounded or linear-time behavior.
• standard: default for internal business rules. Keep allowlists and resource limits, but permit common pure helpers such as size, contains, startsWith, endsWith, contains_ignore_case, and bounded regex support if needed.
• internal-admin: limited to trusted operator-maintained rules. This may be closer to the selected CEL runtime's default behavior, but should still compile during rule load, validate references, enforce maximum input size, and protect reloads with the last known-good rule set.

Allowed:

• boolean logic
• comparisons
• arithmetic supported by the CEL implementation
• string operations
• list and map predicates
• approved pure helper functions

Not allowed:

• file access
• network access
• database access
• current time unless explicitly added as an input field
• random values
• mutation of the rule context
• action execution from inside CEL
• response-body mutation or field removal from CEL

Custom functions should be added conservatively. Standard Light-Rule actions remain the extension point for side effects and transformations.

The core runtime object should be a policy-driven condition evaluator rather than ad hoc logic embedded directly in RuleEngine:

RuleEngineOptions
  -> ConditionExecutionPolicy
      -> defaultCelProfile
      -> allowRuleProfileSelection
      -> profiles[name] = CelSecurityProfile

CelSecurityProfile
  -> allowedFunctions
  -> allowedRootVariables
  -> exposeContextRoot
  -> exposeTopLevelAliases
  -> maxExpressionBytes
  -> maxContextBytes
  -> maxStringBytes
  -> maxCollectionItems
  -> allowRegex
  -> allowTimeParsing
  -> allowComprehensions
  -> maxComprehensionNesting

CEL still needs resource and robustness controls because expressions run on request paths and can iterate over input data. Runtime and publish-time validation should:

• allow-list functions and variables, using compiled expression references where available
• reject functions that perform I/O, mutation, service lookup, action execution, random generation, or implicit current-time access
• cap expression length and input context size
• reject or limit expensive access to large request or response bodies
• compile during rule load and fail invalid expression shapes before request execution
• keep the last known-good rule set if reload validation fails

Phase ceilings should be enforced by runtime policy. Response phases such as res-tra and res-fil should default to a strict ceiling or tight maxContextBytes limits because they can include large response payloads. Access-control phases may allow standard only when the exposed context is small and bounded. A rule request for a stronger profile than the phase ceiling must be rejected or downgraded to the stricter effective profile.

For fully untrusted public input, evaluate CEL in a separate worker, process, or another resource-isolated execution path with CPU and memory limits. A Tokio timeout alone is not a complete guard for synchronous CPU-bound expression evaluation.

Portal Experience

Light-Portal should use conditionLanguage to choose the rule editor. For Light-Fabric, the only supported editor is the CEL editor. Any native condition builder must be scoped to legacy Java yaml-rule authoring and must not export native condition rows to Light-Fabric runtime config.

Recommended authoring modes:

• CEL: advanced text area for one rule-level CEL expression.
• Builder: legacy Java yaml-rule-only condition rows with operand, operator, expected, and join controls.

Recommended behavior:

• default new Light-Fabric rules to cel
• render a CEL expression text area only for conditionLanguage: cel
• reject conditionLanguage: native for Light-Fabric rule publishing
• require confirmation when switching modes if the existing mode has content
• do not try to round-trip arbitrary CEL into native builder rows
• store the selected mode in rule_t.condition_language and in the JSON rule body as conditionLanguage
• for CEL rules, store only the selected profile name in rule_t.condition_security_profile and in the JSON rule body as conditionSecurityProfile; do not expose raw policy limits in the form
• do not show internal-admin in standard self-service forms; allow it only through checked-in runtime configuration or an explicitly authorized internal admin JWT/role path

The CEL editor should provide:

• syntax validation
• test context input
• expression result preview
• visible context field reference
• selected and effective security profile display
• rule test execution against the same backend evaluator used by runtime

Profile Approval Workflow

Light-Portal may allow a user to select a CEL security profile, but the selected profile is only a request. Runtime policy still computes the effective profile from the requested profile, the service maximum, the tenant maximum, and the rule phase ceiling.

Recommended publish behavior:

• strict: direct publish. If schema, CEL validation, and command authorization pass, create or update the rule immediately.
• standard: approval required. Submit the proposed rule change, create a worklist task for rule-admin and admin, and keep the change pending until approval.
• internal-admin: hidden from standard self-service authoring. If exposed to an operator-only flow, require stronger approval and never allow ordinary self-service users to request it.

For approval-required changes, the command side should not emit the final active RuleCreated or RuleUpdated event at submission time. It should emit a submission event such as RuleChangeSubmittedEvent or RuleApprovalRequestedEvent, store the proposed rule body and requested profile, and create the human-in-the-loop worklist task. Only approval should emit the active rule event. Rejection should emit a rejection event and leave the active rule unchanged.

Assistant tasks can help the approver by summarizing the CEL expression, rule phase, requested profile, referenced context roots, use of response body fields, regex usage, and any runtime ceiling that would downgrade the effective profile. The assistant output is advisory only; the human approver remains responsible for the approval decision.

Recommended approval rules:

• changing the expression, action list, rule phase, requested profile, or exposed context assumptions invalidates prior approval
• downgrading from standard to strict can publish directly after validation
• upgrading from strict to standard or internal-admin requires approval
• requester and approver should be different users except for an explicit break-glass workflow
• approval audit should record requested profile, effective profile, requester, approver, approval time, assistant-task summary id, and approval comments
• pending rules must not be exported to runtime endpoint rule config until approved

Compatibility

Existing Light-Fabric rule YAML must use CEL conditions.

Rules without conditionLanguage can be treated as cel only when a valid expression is present. Rules containing legacy native conditions must be rejected by Light-Fabric runtime config validation or converted to CEL before publish. The database migration should add rule_t.condition_language with default cel.

Rules without conditionSecurityProfile use the runtime default CEL profile. The field is meaningful only for CEL rules.

Native condition aliases are legacy Java yaml-rule import details only:

• operatorCode as alias for operator
• propertyPath as alias for operand
• actionClassName as alias for actionRef

CEL is the Light-Fabric capability. If the Java yaml-rule runtime needs to execute the same rules, it must implement the same CEL rule shape. Until then, Java runtimes must fail closed with a clear capability error, such as UnsupportedConditionLanguageException, when loading or executing a rule with conditionLanguage: cel. A runtime must not silently ignore a CEL rule because that can fail open for access-control rules.

Java parity is feasible because Google maintains CEL-Java under the dev.cel Maven group, including the dev.cel:cel artifact with compiler and runtime APIs. The compatibility requirement is therefore mostly about aligning the rule schema, context shape, custom functions, and error handling across the Rust and Java runtimes.

Example: Access Control

ruleBodies:
  allowEndpointClaims:
    common: Y
    ruleId: allowEndpointClaims
    ruleName: Allow request when endpoint permission matches JWT claims
    ruleType: req-acc
    conditionLanguage: cel
    conditionSecurityProfile: strict
    expression: >
      (
        !("role" in permission)
        || (
          ("roles" in auditInfo.subject_claims.ClaimsMap
            && permission.role in auditInfo.subject_claims.ClaimsMap.roles)
          || ("role" in auditInfo.subject_claims.ClaimsMap
            && permission.role == auditInfo.subject_claims.ClaimsMap.role)
        )
      )
      && (
        !("group" in permission)
        || (
          ("groups" in auditInfo.subject_claims.ClaimsMap
            && permission.group in auditInfo.subject_claims.ClaimsMap.groups)
          || ("scp" in auditInfo.subject_claims.ClaimsMap
            && permission.group in auditInfo.subject_claims.ClaimsMap.scp)
          || ("group" in auditInfo.subject_claims.ClaimsMap
            && permission.group == auditInfo.subject_claims.ClaimsMap.group)
          || ("grp" in auditInfo.subject_claims.ClaimsMap
            && permission.group == auditInfo.subject_claims.ClaimsMap.grp)
        )
      )
      && (
        !("position" in permission)
        || (
          ("positions" in auditInfo.subject_claims.ClaimsMap
            && permission.position in auditInfo.subject_claims.ClaimsMap.positions)
          || ("position" in auditInfo.subject_claims.ClaimsMap
            && permission.position == auditInfo.subject_claims.ClaimsMap.position)
          || ("pos" in auditInfo.subject_claims.ClaimsMap
            && permission.position == auditInfo.subject_claims.ClaimsMap.pos)
        )
      )
      && (
        !("attribute" in permission)
        || (
          ("attributes" in auditInfo.subject_claims.ClaimsMap
            && permission.attribute.key
              in auditInfo.subject_claims.ClaimsMap.attributes
            && auditInfo.subject_claims.ClaimsMap.attributes[
              permission.attribute.key
            ] == permission.attribute.value)
          || ("attribute" in auditInfo.subject_claims.ClaimsMap
            && permission.attribute.value
              == auditInfo.subject_claims.ClaimsMap.attribute)
          || ("att" in auditInfo.subject_claims.ClaimsMap
            && permission.attribute.value == auditInfo.subject_claims.ClaimsMap.att)
        )
      )
    actions: []

endpointRules:
  /v1/claims/{claimId}@post:
    req-acc:
      - allowEndpointClaims
    permission:
      role: claims-approver
      group: claims.write
      position: adjuster
      attribute:
        key: region
        value: east

The endpoint above matches a caller JWT with claims like:

{
  "roles": ["claims-approver"],
  "groups": ["claims.write"],
  "positions": ["adjuster"],
  "attributes": {
    "region": "east"
  }
}

With this reusable req-acc rule, the technical rule body stays stable and API owners define the required authorization dimensions at the endpoint. The example above allows the request only when all configured endpoint permissions match claims from the caller JWT.

Example: Response Filter Guard

ruleBodies:
  filterAccountsForPortalUsers:
    common: Y
    ruleId: filterAccountsForPortalUsers
    ruleName: Filter accounts for portal users
    ruleType: res-fil
    conditionLanguage: cel
    conditionSecurityProfile: strict
    expression: >
      statusCode == 200
      && responseBody != ""
      && auditInfo.subject_claims.ClaimsMap.role != null
    actions:
      - actionClassName: com.networknt.rule.ResponseRowFilterAction

Rollout Plan

1. Add rule_t.condition_language with default cel, optional rule_t.condition_security_profile, and check constraints.
2. Extend the rule specification with CEL rule validation plus optional conditionSecurityProfile, and reject native condition rows for Light-Fabric runtime config.
3. Add conditionLanguage, conditionSecurityProfile, and expression fields to the Rust Rule model.
4. Update command/query APIs so the portal can persist and read the condition language, security profile, and approval state without parsing ruleBody.
5. Reject operatorCode: cel in runtime config and normalize any legacy import to the rule-level CEL shape before publishing.
6. Choose and pin the Rust CEL crate behind an internal evaluator abstraction.
7. Add runtime-owned CEL security profiles and policy-driven context building.
8. Add approval workflow integration for standard and internal-admin profile requests, including worklist and assistant-task support.
9. Dispatch inside RuleEngine::execute_rule based on conditionLanguage.
10. Compile and cache CEL expressions during rule config load.
11. Add unit tests for CEL true, CEL false, invalid expression, mode validation, and missing-field behavior.
12. Add tests for custom legacy-operator compatibility helper functions.
13. Add performance tests for context conversion with large toolArguments and response payloads.
14. Add gateway integration tests using the existing rule context and the context root variable.
15. Add rule test API support so Light-Portal can validate CEL before publish.
16. Add CEL rule editing, a controlled CEL profile selector, and approval UX for stronger profile requests.
17. Document runtime compatibility and Java parity requirements.

Decision

Support CEL conditions as the only Light-Fabric rule condition language. Native condition rows remain a legacy Java yaml-rule format and must not be emitted to Light-Fabric runtime configuration. A Light-Fabric rule should use conditionLanguage: cel; mixed native/CEL condition arrays are not a supported authoring or runtime model.

Debugging CEL Rules

Status

The short-term referenced-context trace logging described here is implemented. Structured decision outcomes and the rule-test API remain proposed long-term work.

Problem

The Light-Gateway access-control handler and MCP router both evaluate CEL rules through the shared access-control runtime. When a request is denied, a rule author usually sees only a generic access-denied response. That response does not distinguish among these cases:

• the CEL expression evaluated successfully and returned false
• CEL compilation or evaluation failed
• the expression returned a non-boolean value
• the endpoint referenced a missing rule
• an action rejected the rule after its CEL condition matched
• accessRuleLogic: all or accessRuleLogic: any produced the final denial
• defaultDeny applied because no endpoint or req-acc rule matched
• MCP tools/list hid a tool because of policy, an unknown rule, or the maxCelEvaluations limit

These cases must remain fail-closed, but they should not be indistinguishable to an authorized operator or rule author.

Printing the complete request on every denial is not an acceptable solution. Access control runs after security, so its CEL context should contain normalized identity claims and policy inputs rather than raw authentication credentials. Diagnostics can then project only the properties referenced by the expression instead of copying unrelated claims, headers, tool arguments, request data, or response data.

Current Behavior

The current implementation already provides a useful starting point:

• RuleEngine catches CEL execution errors and interpreter panics.
• Failed CEL evaluations and false results can emit a separate TRACE event containing only statically referenced context properties. Metadata is logged by default; logFullCelContext: true logs bounded values.
• Context diagnostics bound depth, node count, collection size, string length, key length, and null-path traversal.
• Access-control context construction excludes authorization, proxy authorization, cookie, set-cookie, and API-key headers.
• Successful CEL evaluation returns only a boolean.
• The shared access-control runtime converts a missing rule or any rule-engine error into false for request authorization.
• The final HTTP and MCP denial responses deliberately avoid exposing internal policy details.

The main gap is therefore not only context visibility. It is loss of structured decision information between CEL execution and the final access decision.

Goals

• Explain why an HTTP request, MCP tool call, or MCP tool-list entry was allowed, denied, hidden, or filtered.
• Distinguish a valid false result from a malformed rule or runtime error.
• Show the effective CEL context during local and development rule testing.
• Use the exact runtime evaluator for pre-deployment rule testing.
• Correlate diagnostics with the request, policy revision, endpoint, tool, and rule version that produced the decision.
• Preserve current fail-closed authorization behavior.
• Keep diagnostic overhead negligible when debugging is disabled.
• Share the implementation between HTTP access control and MCP routing.
• Keep raw credentials and other security-handler inputs out of the CEL context.

Non-Goals

• Return policy internals or request context to ordinary API or MCP callers.
• Log complete request, response, token, or tool-argument payloads by default.
• Rewrite CEL expressions into simpler expressions for diagnostic evaluation. Rewriting could change short-circuiting, macros, presence behavior, or types.
• Turn CEL into a mutation or general scripting language.
• Guarantee a natural-language proof for every false result. The first implementation should report facts and outcomes rather than speculate.
• Weaken strict profile field exposure to make debugging easier.
• Support CEL rules that inspect raw authorization headers, cookies, API keys, tokens, or other authentication credentials.

Design Principles

Separate enforcement from explanation

Authorization still maps every non-matching or erroneous outcome to deny when the policy requires fail-closed behavior. A separate diagnostic result retains the reason for authorized consumers.

Prefer pre-deployment testing

The best production diagnostic is a rule that was tested before publication. Runtime diagnostics remain necessary because live tokens, headers, endpoint resolution, and tool arguments can differ from test fixtures.

Report facts, not invented explanations

For a false result, report the expression, statically referenced paths, structural metadata or full values according to logFullCelContext, profile, and rule-combination behavior. Do not claim that a particular clause caused the result because the current CEL evaluator has no execution observer that can prove it.

Outcome Model

The boolean returned by the current rule path should be replaced internally by a structured outcome. The exact Rust types can evolve, but the semantic model should be stable:

#![allow(unused)]
fn main() {
enum RuleConditionOutcome {
    Matched,
    NotMatched,
    CompileError { message: String, source: Option<SourceLocation> },
    EvaluationError { message: String },
    NonBoolean { actual_type: String },
    SecurityProfileRejected { message: String },
}

enum RuleExecutionOutcome {
    Matched,
    ConditionNotMatched,
    ConditionError(RuleConditionOutcome),
    ActionRejected { action_ref: String },
    ActionError { action_ref: String, message: String },
    ActionNotFound { action_ref: String },
    RuleNotFound,
}
}

RuleEngine::execute_rule should return a structured result. Compatibility wrappers can continue returning bool where callers do not need diagnostics.

The shared access-control runtime should then build an aggregate decision:

#![allow(unused)]
fn main() {
struct AccessEvaluation {
    decision: AccessDecision,
    reason: AccessDecisionReason,
    rules: Vec<RuleEvaluation>,
    skipped_rule_ids: Vec<String>,
}
}

AccessDecision remains the enforcement projection. AccessEvaluation is the diagnostic projection.

Rule Aggregation Trace

The trace must preserve accessRuleLogic behavior:

• With all, evaluation stops at the first rule that does not match or errors. Remaining rule IDs are recorded as skipped because of short-circuiting.
• With any, evaluation stops at the first matching rule. Remaining rule IDs are recorded as skipped because of short-circuiting.
• A rule-engine error is recorded as an error outcome even when the enforcement projection treats it like false.
• A missing rule body is recorded as rule_not_found, not not_matched.
• defaultDeny decisions are recorded without fabricating a rule evaluation.

Actions can mutate the rule context, so the existing candidate-context behavior for any must remain unchanged. Diagnostic collection must observe the same execution and must not evaluate a rule a second time.

Decision Trace

A decision trace should use a stable structured shape suitable for JSON logs and the future rule-test API:

{
  "timestamp": "2026-07-24T15:42:11.184Z",
  "correlationId": "request-123",
  "serviceId": "com.networknt.gateway-1.0.0",
  "policyRevision": "sha256...",
  "surface": "mcp-tools-call",
  "endpoint": "/config/query@post",
  "toolName": "queryConfig",
  "ruleType": "req-acc",
  "ruleLogic": "all",
  "decision": "denied",
  "reason": "condition_not_matched",
  "rules": [
    {
      "ruleId": "allow-config-read",
      "expressionHash": "sha256...",
      "requestedProfile": "strict",
      "effectiveProfile": "strict",
      "outcome": "condition_not_matched",
      "contextMode": "full",
      "referencedPaths": [
        "permission.roles",
        "auditInfo.subject_claims.ClaimsMap.roles"
      ],
      "referencedValues": {
        "permission.roles": ["config-admin"],
        "auditInfo.subject_claims.ClaimsMap.roles": ["developer"]
      },
      "contextTruncated": false
    }
  ],
  "skippedRuleIds": [],
  "referenceAnalysisIncomplete": false,
  "traceTruncated": false
}

Trace logs can include the expression text because this feature is intended for local and development use. They should also include ruleId, expression hash, and policy revision so that a diagnostic can be tied to the exact loaded policy.

Diagnostic Context Modes

The runtime has two context projections:

Full context must never mean an unbounded raw dump. Both modes use the same CEL-profile projection and diagnostic budgets as evaluator-error diagnostics.

CEL Reference Discovery

light-rule currently pins cel 0.14.0. That crate exposes two relevant APIs:

• Program::references() returns the root variables and functions referenced by the compiled expression. For auditInfo.subject_claims.ClaimsMap.roles, it reports the root variable auditInfo.
• Program::expression() exposes the public parsed AST. Expr::Select nodes contain their operand and selected field, so Light-Fabric can walk the AST and recover the complete static member path auditInfo.subject_claims.ClaimsMap.roles.

The crate does not expose an evaluation observer or a list of properties actually read at runtime. Reference discovery is therefore static: it includes properties in branches that short-circuit evaluation and cannot always resolve computed map keys.

The compiled-program cache should store a reference projection alongside each program:

#![allow(unused)]
fn main() {
struct CelProgramEntry {
    program: Arc<CelProgram>,
    referenced_roots: Vec<String>,
    referenced_paths: Vec<String>,
    reference_analysis_incomplete: bool,
}
}

Static dot selections and indexes with literal string keys should produce exact paths. For dynamic indexing, the projection should fall back to the smallest known root or static prefix and set referenceAnalysisIncomplete: true. Macro and comprehension-local variables must not be mistaken for root context variables.

This fallback deliberately broadens full mode. For example, ClaimsMap[claimName] cannot identify the selected claim statically, so full mode emits the bounded ClaimsMap parent object as well as claimName. Metadata mode emits only the parent's type and size. Rule authors should prefer literal indexes or dot selections when they want the narrowest diagnostic projection.

The reference walker is coupled to the public AST and operator names in the pinned cel 0.14.0 crate. A CEL dependency upgrade must revalidate the walker and its literal-index, dynamic-index, and comprehension tests.

Access-Control Context Boundary

Security authenticates the request before access control runs. The security handler should expose normalized identity and authorization facts through auditInfo.subject_claims.ClaimsMap; it should not forward the credential used to establish those facts into CEL.

The access-control CEL context must therefore exclude raw values such as:

• Authorization and Proxy-Authorization headers
• cookies and session tokens
• API keys and client secrets
• private keys or credential material owned by an earlier handler

If a rule needs an identity fact derived from one of these inputs, the security handler should expose the normalized claim instead. For example, a rule should read a roles claim from auditInfo, not parse the bearer token.

Other CEL inputs should be policy-oriented: endpoint and tool identity, permissions, selected non-sensitive headers, correlation metadata, referenced tool arguments, and the request or response properties required by the rule phase.

Referenced Context Projection

Diagnostics start from the variables exposed by the effective CEL security profile and keep only the statically referenced properties. A diagnostic cannot include an unrelated property merely because it exists in the root context.

The projection then keeps only the statically referenced properties. Most current request-access rules reference JWT claims below auditInfo.subject_claims.ClaimsMap, so a rule that reads only the caller's roles should not cause unrelated headers, claims, or tool arguments to be logged.

The diagnostic path does not add header or JSON-path masking. Sensitive credentials are excluded when the access-control context is constructed, and reference projection removes unrelated properties. logFullCelContext: true can therefore emit the actual values of referenced policy properties. It is intentionally a local and development-only setting and must emit a startup warning.

Values that require special handling

• JWT claims and toolArguments include only statically referenced properties.
• responseBody and responseBodyJson include only statically referenced properties.
• A row-level CEL filter captures at most the current bounded row and should not repeat the shared context for every rejected row.
• Binary data is represented by type and length, not encoded into the trace.

Bounds

Reuse the existing limits for diagnostic context depth, nodes, collection items, string characters, key characters, null paths, and null-path traversal. Add an overall serialized trace byte limit. Every limit must have a corresponding truncation field so an operator can distinguish absent data from omitted data.

Runtime Configuration

The short-term configuration should be one root-level property in access-control.yml:

logFullCelContext: false

This property does not enable trace logging. The logging filter still controls whether CEL trace events are emitted, for example:

RUST_LOG=light_rule::cel=trace,info

The property controls only the context projection used by those events:

• false or absent: emit referenced paths and structural metadata without property values at TRACE
• true: emit actual values for the referenced CEL properties at TRACE for local or development use

No mode performs diagnostic masking. The serialized trace remains size-limited and reports truncation, but full-mode values are otherwise emitted as they appear in the credential-free access-control context.

The runtime should emit a prominent startup warning when logFullCelContext: true is loaded:

Full CEL context logging is enabled. This setting is intended only for local or development environments.

Trace events should cover CEL evaluation errors and successful evaluations that return false. A per-rule false event must be labeled as a rule outcome, not as a final access denial, because accessRuleLogic: any can allow the request through a later rule.

This changes earlier evaluator-error logging behavior: bounded context and candidate-null-path diagnostics previously appeared with the WARN or ERROR event. They now appear only in the separate light_rule::cel TRACE event; the warning or error retains the expression and failure details without request context. Operators who relied on warning-level context must enable the trace target while diagnosing CEL failures.

Rule-Test API

Rule authors should be able to test before publishing. The test path must use the same light-rule evaluator, profile enforcement, context conversion, and action registry as the target runtime.

Suggested request:

{
  "rule": {
    "ruleId": "allow-config-read",
    "ruleType": "req-acc",
    "conditionLanguage": "cel",
    "conditionSecurityProfile": "strict",
    "expression": "permission.roles.exists(r, r in auditInfo.subject_claims.ClaimsMap.roles)"
  },
  "context": {
    "auditInfo": {
      "subject_claims": {
        "ClaimsMap": {
          "roles": ["developer"]
        }
      }
    },
    "permission": {
      "roles": ["config-admin"]
    },
    "endpoint": "/config/query@post",
    "toolName": "queryConfig",
    "toolArguments": {}
  }
}

Suggested response:

{
  "outcome": "condition_not_matched",
  "requestedProfile": "strict",
  "effectiveProfile": "strict",
  "referencedPaths": [
    "permission.roles",
    "auditInfo.subject_claims.ClaimsMap.roles"
  ],
  "referencedValues": {
    "permission.roles": ["config-admin"],
    "auditInfo.subject_claims.ClaimsMap.roles": ["developer"]
  },
  "warnings": [],
  "contextTruncated": false
}

The API should support two modes:

• isolated rule evaluation for the editor
• endpoint-policy evaluation using a selected configuration snapshot, including rule ordering, all or any, permissions, and default-deny behavior

The endpoint-policy mode is essential because a rule can work in isolation but still not be selected for the deployed endpoint.

The test API must not accept arbitrary production credentials or fetch live requests. Test contexts are explicit input, access-controlled, size-limited, and excluded from ordinary logs.

Portal Experience

The CEL editor should present:

• the documented context schema for the selected rule phase
• requested and effective security profiles
• syntax and profile validation before publication
• an editable constructed test context
• matched, not-matched, or error as distinct states
• per-rule endpoint-policy results and short-circuiting
• referenced paths beside their constructed test values
• missing-field, null-receiver, type, and non-boolean errors

A production denial shown to an ordinary caller remains generic. Rule testing uses a constructed context in the Portal rather than retrieving a live request context from the gateway.

MCP-Specific Behavior

The same trace model applies to MCP with a surface field that identifies:

• mcp-tools-call
• mcp-tools-list
• mcp-response-filter

For tools/call, include the resolved configured tool name and endpoint, but include only tool-argument properties referenced by the CEL expression.

For CEL-based tools/list, one request can evaluate many tools. Do not emit one large context event per hidden tool by default. Emit a bounded aggregate summary with counts and keep any per-tool trace detail bounded. Distinguish:

• hidden by a CEL false result
• hidden by CEL error
• hidden by unknown-rule fallback
• skipped after maxCelEvaluations
• served from the tools-list visibility cache

If a result came from cache, include the policy revision and cache outcome. Do not claim that CEL was evaluated for that request.

Response-Filter Behavior

Response filtering needs separate outcomes because false can mean different things at different layers:

• rule-level CEL condition did not select the filter
• a response-filter action rejected execution
• a row-level CEL expression excluded a row
• a row-level expression failed and the row was excluded fail-closed
• the complete top-level object was denied

Row filtering can evaluate the same expression hundreds or thousands of times. Capture the first bounded failure sample, total matched/excluded/error counts, and the number of suppressed diagnostics. Never emit the entire response body.

Logs, Metrics, and Audit

Use stable tracing targets and event names rather than prose-only messages:

target: light_rule::decision
event: cel_rule_decision

Summary events should contain scalar fields that remain useful in text and JSON logging. Detailed context can be a bounded JSON field.

Recommended counters:

• CEL evaluations by outcome, rule type, and security profile
• access decisions by reason and surface
• diagnostic traces captured, truncated, sampled out, or rate-limited
• rule-test requests by outcome
• tools-list evaluations skipped by maxCelEvaluations

Do not use rule IDs, endpoints, tool names, correlation IDs, or user identities as unbounded metric labels. Those belong in logs or traces.

Individual rule evaluations normally remain operational tracing events, not durable security audit records, unless deployment policy requires otherwise.

Performance and Abuse Controls

• When TRACE is disabled for the CEL tracing target, avoid cloning or serializing context solely for diagnostics.
• Build a context projection only after confirming that the trace event is enabled.
• Reuse the compiled CEL program and any compile-time reference analysis.
• Never reevaluate a CEL expression to explain its first result.
• Bound trace size, row samples, and tools-list samples.
• Rate-limit rule-test execution.
• Apply existing CEL profile and expression-complexity limits to test requests.
• Record when sampling or limits omitted diagnostic data.

Failure Behavior

Diagnostics must never change the access decision. If reference analysis, serialization, or log emission fails:

1. preserve the original allow or deny result
2. emit a bounded diagnostic-system error without request context
3. increment a diagnostic failure counter
4. do not retry on the request path

The diagnostic system itself should be panic-contained where it processes untrusted context values.

Implementation Phases

Phase 1: Preserve outcomes

• Introduce structured condition and rule outcomes in light-rule.
• Stop collapsing every RuleEngine error into an unexplained false inside the shared access-control runtime.
• Preserve boolean compatibility wrappers for unrelated callers.
• Add aggregate outcomes for all, any, missing rules, and default deny.
• Emit safe summary tracing events for errors and denials.

Phase 2: Referenced diagnostic projection

Implemented for the short-term runtime diagnostic path:

• Exclude raw credentials when constructing the access-control CEL context.
• Centralize context reference analysis, projection, and bounds.
• Apply the same safe projection to existing CEL error and panic logs.
• Use Program::references() and the public AST to extract referenced roots and static member paths.
• Add the root-level logFullCelContext configuration to access-control.yml.

Remaining enhancements:

• Add expression hashes, policy revisions, and stable reason codes.
• Add MCP tools-list aggregation and response-row sampling.

Phase 3: Authoring workflow

• Add isolated-rule and endpoint-policy test APIs.
• Integrate the APIs into the Portal CEL editor.
• Validate rules with the target runtime evaluator before publication.

Testing Strategy

Outcome tests

• CEL true and false
• compile error, evaluation error, panic, and non-boolean result
• missing rule and missing action
• action rejection and action error
• all and any short-circuit traces
• default allow and default deny
• HTTP, MCP tools/call, MCP tools/list, and response-filter surfaces

Security tests

• raw authorization headers, cookies, API keys, and credentials never enter the access-control CEL context
• strict diagnostics never expose roots unavailable to strict CEL
• unrelated headers, claims, tool arguments, and response fields are absent
• metadata mode reports structure without property values
• full mode reports values only for referenced properties
• request input cannot enable full context logging
• truncation flags are correct

Parity tests

• rule-test and runtime execution return the same outcome for the same rule, context, profile, and policy revision
• diagnostic collection does not change action mutation or short-circuiting
• cached MCP tools-list decisions are labeled as cached and are not reported as fresh evaluations

Performance tests

• disabled trace logging has no material request-path allocation regression
• metadata and full trace logging remain within defined latency budgets
• large contexts, large rows, and tools-list fan-out remain bounded

Resolved Decisions

1. The pinned cel 0.14.0 crate exposes referenced root variables and a public AST, so Light-Fabric will statically extract related context paths and log only those properties. It does not expose actual runtime property reads.
2. The diagnostic path will not add masking. Access-control context construction excludes raw credentials, and full mode logs the actual bounded values of referenced policy properties.
3. The design does not add log retention or audit requirements. Local logging and its existing rotation policy own trace retention.

Recommended Default

The referenced-context trace logging and root-level logFullCelContext switch are the short-term implementation. Next, add structured outcomes, then the rule-test API and Portal editor support.

This sequence fixes the information-loss problem, gives authors a safe way to inspect rule context during local development and test rules before deployment, and can adopt runtime property-read tracing later if the CEL evaluator adds a trustworthy observer API.

Access Control Handler Design

The access-control handler enforces fine-grained authorization for normal HTTP API endpoints. It should reuse the same Light-Rule policy model that the MCP router uses for tool authorization:

• access-control.yml controls whether policy is enabled, whether missing endpoint rules deny by default, how multiple request access rules combine, and which endpoint prefixes are skipped.
• rule.yml contains CEL rule bodies and endpoint mappings.
• req-acc rules run before the upstream API endpoint is called.
• res-fil rules run after the upstream API endpoint responds and before the response is returned to the caller.

The access-control handler and the MCP router should share the same frameworks/light-pingora/src/access_control.rs runtime. The difference is the boundary where that runtime is applied. The MCP router protects MCP tools. The access-control handler protects API endpoints in the normal handler chain.

Goals

• Enforce fine-grained access control for REST or HTTP API endpoints.
• Reuse the existing req-acc and res-fil rule phases.
• Reuse the built-in action classes: RoleBasedAccessControlAction, ResponseRowFilterAction, and ResponseColumnFilterAction.
• Keep rule definitions portable between gateway products when the endpoint key and context fields are equivalent.
• Support exact endpoint rules, Java-style path templates, and parent path entries.
• Keep the business API unaware of caller-specific row and column filtering.

Non-Goals

• Do not create a second rule engine for HTTP APIs.
• Do not support the legacy native condition-row format in Light-Fabric. Light-Fabric rules must use conditionLanguage: cel.
• Do not replace base authentication. The access-control handler assumes an earlier security handler has already built the caller principal.
• Do not push row or column filtering into business handlers.

Handler Placement

The access-control handler should run after authentication and before routing to the upstream API service:

request
  -> TLS / CORS / rate-limit / header handlers
  -> security or unified-security handler
  -> access-control req-acc
  -> proxy or route handler
  -> access-control res-fil
  -> response

If no authenticated principal is available, a req-acc rule can still evaluate headers and endpoint metadata, but role, group, user, and claim-based rules will normally fail closed.

Shared Runtime

The existing runtime already models the common policy engine:

#![allow(unused)]
fn main() {
AccessControlRuntime
  -> authorize_tool(...)
  -> filter_mcp_response(...)
}

For API endpoints, these functions should be generalized rather than duplicated. The MCP-specific names can remain as compatibility wrappers, but the shared runtime should expose endpoint-neutral operations:

#![allow(unused)]
fn main() {
authorize_request(
  endpoint,
  headers,
  auth,
  request_context,
  correlation_id
)

filter_response(
  endpoint,
  headers,
  auth,
  request_context,
  response_status,
  response_body,
  correlation_id
)
}

The MCP router can keep passing toolName and toolArguments. The API handler should pass API-oriented values such as path parameters, query parameters, request method, and request body metadata.

Endpoint Keys

Endpoint rule keys should use the same stable format as the MCP router:

{path}@{method}

Examples:

/offers@get
/v1/accounts/{accountId}@get
/v1/accounts@post

The query string must not be part of the endpoint key. Query parameters belong in the rule context so CEL can inspect them without multiplying endpoint rule entries.

Endpoint matching order should remain:

1. Exact endpoint key.
2. Java-style path template match, such as /v1/accounts/{id}@get.
3. Parent path entry, such as /v1/accounts@get for /v1/accounts/123@get.

Configuration

access-control.yml is the handler-level switch:

enabled: true
accessRuleLogic: any
defaultDeny: true
defaultInclude: false
skipPathPrefixes:
  - /health
  - /adm
claimMappings: {}

Fields:

• enabled: when false, the handler allows requests and does not filter responses.
• accessRuleLogic: any allows a request if any req-acc rule passes; all requires every listed req-acc rule to pass. This setting applies only to req-acc; it does not apply to res-fil.
• defaultDeny: when true, a request with no matching endpoint rule or no req-acc rule is denied.
• defaultInclude: controls response row-filter behavior when a row filter is configured but no caller claim matches any configured row-filter entry. When false, the row filter returns no rows. When true, the row filter preserves the legacy include-all behavior.
• skipPathPrefixes: endpoint prefixes that bypass access-control entirely.
• claimMappings: maps permission dimensions to JWT claim names for built-in request-access, row-filter, column-filter, and MCP tool-visibility behavior. Standard keys are roles, groups, positions, attributes, and users. Custom row or column dimensions use the dimension name as the mapping key.

For example, a deployment with custom role and tenant claims can use:

claimMappings:
  roles:
    - custom_roles
  tenant:
    - tenant_id

Standard aliases remain active when a dimension has no configured mapping. Existing toolsListAccessControl.claimMappings configuration remains supported as a compatibility fallback, but top-level claimMappings takes precedence and applies consistently to authorization and response filtering.

rule.yml contains the reusable rules and endpoint policy:

ruleBodies:
  allowOfferRead:
    common: Y
    ruleId: allowOfferRead
    ruleName: Allow offer read
    ruleType: req-acc
    conditionLanguage: cel
    conditionSecurityProfile: strict
    expression: >
      auditInfo.subject_claims.ClaimsMap.role != null
    actions:
      - actionClassName: com.networknt.rule.RoleBasedAccessControlAction

  filterOfferRows:
    common: Y
    ruleId: filterOfferRows
    ruleName: Filter offer rows
    ruleType: res-fil
    conditionLanguage: cel
    conditionSecurityProfile: strict
    expression: >
      statusCode == 200
      && responseBody != ""
      && auditInfo.subject_claims.ClaimsMap.role != null
    actions:
      - actionClassName: com.networknt.rule.ResponseRowFilterAction

  filterOfferColumns:
    common: Y
    ruleId: filterOfferColumns
    ruleName: Filter offer columns
    ruleType: res-fil
    conditionLanguage: cel
    conditionSecurityProfile: strict
    expression: >
      statusCode == 200
      && responseBody != ""
      && auditInfo.subject_claims.ClaimsMap.role != null
    actions:
      - actionClassName: com.networknt.rule.ResponseColumnFilterAction

endpointRules:
  /offers@get:
    req-acc:
      - allowOfferRead
    res-fil:
      - filterOfferRows
      - filterOfferColumns
    permission:
      roles: offer-viewer offer-admin
      row:
        role:
          offer-viewer:
            - colName: priority
              operator: "<"
              colValue: 50
            - colName: active
              operator: "="
              colValue: true
      col:
        role:
          offer-viewer: offerId,title,segment,state,category,priority

In this example, offer-viewer can call GET /offers but only receives active offers with priority below 50, and the active field is removed from the final payload. With defaultInclude: false, offer-admin can call the same endpoint only if a matching row-filter entry exists or the endpoint omits row filtering. If an endpoint has a row block but no row entry matches the caller's role, group, position, attribute, or user claim, the filtered result is empty. Set defaultInclude: true only when a deployment intentionally wants the legacy include-all behavior for unmatched row-filter claims.

Rule Context

The access-control handler should build the same core context shape as the MCP router so existing CEL rules and actions stay reusable:

For API endpoints, add API-specific fields:

The existing MCP fields can remain optional:

Permission values should continue to be injected twice:

• as the namespaced permission object
• as top-level convenience fields, such as roles, row, and col

This preserves compatibility with existing rule bodies and built-in action classes. Runtime-owned context fields are the exception: permission keys named auditInfo, headers, endpoint, toolName, toolArguments, correlationId, permission, responseBody, responseBodyJson, statusCode, or accessControl remain available under permission but are not promoted to the top level. This prevents endpoint configuration from replacing verified identity, request, or response context.

Request Access

req-acc runs before the upstream API call.

The handler should:

1. Build the endpoint key from request path and method.
2. Skip the request if the endpoint matches skipPathPrefixes.
3. Find endpoint rules by exact, template, or parent match.
4. Deny when defaultDeny: true and no matching req-acc rule exists.
5. Build the rule context from auth, headers, endpoint, request fields, and endpoint permissions.
6. Execute the listed req-acc rules with accessRuleLogic.
7. Return 403 when access is denied.

When accessRuleLogic: any, each candidate rule should receive a cloned context, and the first passing rule should win. When accessRuleLogic: all, rules should run sequentially against the same context and all must pass.

Response Filtering

res-fil runs after the upstream API response returns.

The handler should:

1. Only filter response payloads that are safe and useful to parse, starting with JSON arrays, JSON objects containing an items array, and single JSON objects for column filtering.
2. Buffer the full response body before filtering.
3. Decode or avoid upstream compression before JSON parsing.
4. Add statusCode, responseBody, and the parsed mutable JSON value to the same rule context shape.
5. Execute res-fil rules sequentially in the order listed on the endpoint.
6. Serialize the filtered JSON once after all res-fil actions complete.
7. Replace the response body with the final filtered JSON.
8. Recompute response headers that depend on body size, such as content-length.

Ordering matters. Row filters must run before column filters when the row predicate depends on a field that should be hidden in the final response. For example, a row filter can use active == true, and the later column filter can remove active from the returned rows.

res-fil is always a sequential all pipeline. accessRuleLogic: any applies only to req-acc; response filters never use any semantics.

Response filtering requires a full payload. It is not compatible with streaming or indefinite responses unless the gateway buffers the entire response first. For Transfer-Encoding: chunked, the gateway must buffer and then emit a normal filtered response. Server-Sent Events and other long-lived streaming responses should bypass res-fil or be rejected when an endpoint requires response filtering.

Compressed upstream responses need explicit handling. The gateway should either strip or normalize Accept-Encoding on the upstream request so the backend returns plaintext JSON, or it must decompress before filtering and recompress afterward. Filtering compressed gzip, br, or deflate bytes as JSON must fail closed.

If a res-fil rule is missing, fails, or returns false, the handler should fail closed for protected API endpoints. For early rollout, a deployment can choose a fail-open compatibility mode only if it is explicit in configuration and emits a high-severity log or module-registry status.

CEL must not directly rewrite the HTTP response body. A res-fil rule-level CEL expression decides whether the filter action should run. The response-filter pipeline owns JSON parsing, final serialization, response body replacement, and header updates such as content-length. Actions own row or column mutation of the parsed response value.

The default model should remain declarative:

• ResponseRowFilterAction applies permission-defined row filters.
• ResponseColumnFilterAction applies permission-defined field keep or remove lists.

Row Filter Default Behavior

Row filtering must fail closed by default. If ResponseRowFilterAction runs for an endpoint with a configured permission.row block, but the caller has no matching entry under any supported dimension (role, group, position, attribute, or user), the action must return an empty row set when defaultInclude: false.

This prevents a common policy gap:

permission:
  row:
    role:
      teller:
        - colName: accountType
          operator: "="
          colValue: C

In the legacy include-all behavior, a caller without the teller role would match no row-filter entry and receive every row. With defaultInclude: false, the same caller receives no rows. A caller with the teller role receives only rows where accountType == "C".

defaultInclude applies only to row-filter miss behavior:

• false: unmatched row-filter dimensions retain no rows. This is the secure default and should be used for new deployments.
• true: unmatched row-filter dimensions retain all rows. This is a compatibility mode for deployments that relied on the old behavior.

If a row-filter entry matches the caller, normal row predicate evaluation still applies. If multiple dimensions match, the configured filter groups are combined with the existing sequential all behavior so a row must satisfy every matched group.

If an API needs a richer row predicate, add a CEL-aware action rather than making rule-level CEL mutate JSON:

ruleBodies:
  filterOfferRowsWithCel:
    ruleId: filterOfferRowsWithCel
    ruleType: res-fil
    conditionLanguage: cel
    conditionSecurityProfile: strict
    expression: >
      statusCode == 200 && responseBody != ""
    actions:
      - actionClassName: com.networknt.rule.ResponseCelRowFilterAction
        actionValues:
          rowExpression: >
            auditInfo.subject_claims.ClaimsMap.role == "offer-admin"
            || (row.priority < 50 && row.active == true)

ResponseCelRowFilterAction should compile rowExpression during rule load and evaluate it once per row with a curated context containing row, auditInfo, headers, endpoint, permission, and API request metadata. It owns row retention and failure handling for the parsed response value. It should not deep-clone the full base context for every row; use a child context that shadows row, or reuse one mutable context and update only the row binding.

If a row-level CEL evaluation fails for one row, for example because priority is missing, the action should drop that row and continue. Compile errors, invalid actionValues, or other configuration errors should fail the whole action closed.

MCP Router Comparison

The MCP router and access-control handler should share configuration and runtime semantics:

This split keeps MCP behavior specialized for JSON-RPC tool calls while letting API endpoint authorization use the same policy and action implementation.

Reload And Observability

The loader should continue to support both standalone files and values.yml projection:

• access-control.yml or access-control.yaml
• rule.yml or rule.yaml
• access-control.* values in values.yml
• rule.ruleBodies and rule.endpointRules values in values.yml

The root-level access-control setting below controls CEL context trace detail:

logFullCelContext: false

At the default false, failed or rejected CEL expressions log referenced paths and structural metadata at TRACE. When set to true, the same event includes bounded values for only the referenced properties. Full mode is intended only for local or development environments. Access-control context construction excludes credential headers in both modes.

The module registry should report:

• whether access control is enabled
• whether rule config is loaded
• number of rule bodies
• number of endpoint mappings
• last reload status
• validation errors for rejected CEL, missing rule ids, or invalid endpoint keys

Config reload should build a new immutable runtime and swap it atomically after validation succeeds. If validation fails, the handler should keep the last known-good runtime.

Implementation Notes

The current AccessControlRuntime is already close to the shared runtime. The main implementation work is to remove MCP-specific naming from the reusable API and add an HTTP response-body adapter:

• Keep authorize_tool and filter_mcp_response as wrappers for the MCP router.
• Add endpoint-neutral authorization and response-filter methods.
• Add API-specific request context fields without changing the existing auditInfo, headers, endpoint, permission, responseBody, and statusCode fields.
• Reuse find_service_entry, rule_ids_for, permission_for, and the default action registry.
• Reuse ResponseRowFilterAction for JSON arrays, object payloads with an items array, and single top-level JSON objects. A denied single object is replaced with an empty object for HTTP responses; the MCP adapter returns a tool error with isError: true.
• Reuse ResponseColumnFilterAction for JSON arrays, object payloads with an items array, and single top-level JSON objects.
• Add handler-level tests for exact endpoint, path template endpoint, parent path endpoint, default deny, skip prefixes, row filtering, and column filtering.

Design Document: Centralized Agentic Skill Registry

Subject: Transitioning from File-Based Markdown Skills to a Database-Backed Skill Registry

1. Executive Summary

Currently, most AI agent frameworks rely on localized Markdown (.md) files to define agent "skills." While Markdown is highly LLM-native and human-readable, it creates significant bottlenecks at an enterprise scale regarding strict typing, API integration, and context window limits.

This document proposes transitioning to an Agentic Control Plane (Centralized Skill Registry) backed by a database. By decoupling skill metadata, schemas, and instructions, and by utilizing dynamic routing, we will achieve hierarchical structuring, strict schema enforcement, and progressive disclosure of tools to agents.

The registry serves enterprise business agents, native workflow agents, coding agents, and personal assistants. It stores governed content and immutable package references; profile-specific runtime hosts materialize the selected skill. See Light-Agent Execution for those runtime and isolation boundaries.

2. Problem Statement

Managing agent skills as flat Markdown files introduces several scaling challenges:

1. Lack of Strict Typing: Markdown cannot enforce data types (e.g., ensuring a parameter is an integer vs. string), leading to hallucinated or malformed tool inputs.
2. Context Window Exhaustion: Loading dozens or hundreds of skill definitions at startup overwhelms the LLM context window, increasing latency, token costs, and tool-misuse.
3. Static Deployments: Updating a skill or changing access permissions requires a full application redeploy.
4. Poor Discoverability: Flat file structures offer no native mechanism for progressive disclosure or tool search.

3. Data Models & Formats

To solve the limitations of purely text-based skills, we will adopt a hybrid, structured format stored within a database (e.g., PostgreSQL/MongoDB). The architecture uses the right format for the right job:

• JSON Schema: Used strictly for defining parameters, inputs, and tool shapes. Natively supported by OpenAI/Anthropic/Google tool-calling APIs.
• LightAPI Description (YAML/JSON): Used to map endpoint-level API capabilities to skills across REST, JSON-RPC, gRPC, and MCP.
• OpenAPI / OpenRPC / Protobuf: Referenced by LightAPI where protocol-native specifications already exist.
• Immutable Execution Artifact / Endpoint Reference: API skills reference a governed endpoint. Scripted skills reference a signed, content-addressed package and entrypoint; mutable source code is not executed directly from a database row.
• Markdown: Retained only for the instructions or prompt fields, as LLMs excel at parsing markdown headers and lists for constraints and persona instructions.

LightAPI is the preferred source format for API-backed skills because it describes endpoint identity, protocol invocation, input schema, request mapping, result shape, examples, and behavior notes in one agent-oriented document. See LightAPI Description Design for the endpoint description model.

YAML and JSON are the external skill document formats. In the portal database, they should not replace the Markdown instruction field. The normalized model is structured columns and relationships for identity, versioning, taxonomy, tools, and execution metadata, plus content_markdown for the LLM-facing instruction body. If the portal later needs to persist a full structured skill document, add a nullable JSONB skill-spec column beside content_markdown and normalize YAML imports to JSON.

3.1 Proposed Database Schema Structure

Light Portal stores skills in structured catalog tables. Below is a representation of the skill payload:

{
  "skill_id": "sk_finance_001",
  "name": "generate_financial_report",
  "version": "1.2.0",
  "tags": ["finance", "reporting"],
  "tool_schema": {
    "type": "function",
    "function": {
      "name": "generate_financial_report",
      "description": "Generates a Q3 report based on ticker symbol.",
      "parameters": {
        "type": "object",
        "properties": {
          "ticker": {"type": "string", "description": "The stock ticker"}
        },
        "required": ["ticker"]
      },
      "response_schema": {
        "type": "object",
        "properties": {
          "report_url": {"type": "string"},
          "status": {"type": "string"}
        }
      }
    }
  },
  "execution": {
    "type": "rest_api",
    "endpoint_id": "ep_finance_report_001",
    "endpoint": "https://internal-api.company.com/v1/finance/report",
    "method": "POST"
  },
  "instructions": "## Role\nYou are a financial analyst.\n## Constraints\n- Never hallucinate financial data.\n- Always return exact numbers."
}

3.2 Skill Authority And Executable Packages

A skill is discovery and guidance content. Assignment of a skill never grants tools, credentials, network, filesystem, workflow, or model-provider access. The effective capability is always the intersection of caller authority, agent-definition policy, skill policy, live gateway/controller policy, and the selected execution profile.

Each tool link resolves to a stable internal tool reference with a server-owned execution placement (gateway, runner, workflow, or fixed-service), model-facing alias, and schema digest. Materialization cannot change that placement. Gateway tools intersect live gateway tools/list; runner tools intersect execution policy, lease allowedTools, the approved runtime-tool manifest, and live local availability. The independently authorized sets may be combined only after alias collisions are rejected or resolved by deterministic server-owned aliases. One placement never grants another placement's tool by name coincidence.

Keep skill_t.content_markdown as the instruction source. Add a separate skill_package_t only for skills that require scripts, binaries, templates, or other runtime assets. A package record should contain:

• host, skill, semantic version, package ID, and immutable artifact URI;
• SHA-256 digest, media type, size, and entrypoint;
• supported runtime profiles and required capability names;
• minimum sandbox boundary, network, workspace, and credential requirements;
• provenance/attestation reference, signer, scanner result, and review state;
• created, deprecated, revoked, and retention state.

The package bytes belong in immutable artifact storage, not a TEXT column. The portal may store authoring source separately, but only a reviewed, signed, scanned, active package can be materialized for execution. The runtime host verifies the package, lease, policy digest, and entrypoint before mounting it read-only.

Existing tool_t.script_content is a legacy authoring/runtime shortcut. It must not become the production execution path for untrusted Python or JavaScript. Publication should compile or package that source into an immutable artifact and require runner placement.

4. Hierarchical Structure & Progressive Disclosure

Dumping 500 JSON schemas into an LLM's context window will cause system failure. The Centralized Controller will act as a mediator, enforcing hierarchy and progressive disclosure (giving the agent only the schemas it needs, exactly when it needs them).

4.1 Implementing Hierarchy & Tagging

Because JSON Schema does not have built-in folders, hierarchy and categorization are enforced via the platform's global entity management system:

1. Namespacing: Tool names follow a strict convention: [domain]_[subdomain]_[action] (e.g., aws_rds_provision).
2. Tags & Categories: Instead of hardcoded columns, the registry utilizes the entity_tag_t and entity_category_t tables (with entity_type = 'skill'). This allows for unlimited flat tagging and deep hierarchical folder structures that are consistent across the entire portal.
3. Discovery API: Portal-query filters by these tags/categories to scoped skill sets for specific agent personas. Agents cache the effective catalog locally and reload it when runtime cache-management invalidation is triggered.

4.2 Progressive Disclosure Patterns

Agents should not load every executable tool into the LLM context. Instead, they should load their assigned skill/tool catalog from the portal API, cache it locally, and use one of the following progressive disclosure patterns:

Phase 5 starts with the Rust light-agent. The agent loads genai-query/getEffectiveAgentCatalog, keeps a local cache keyed by hostId + agentDefId + serviceId + envTag, ranks cached skill/tool entries with keyword and routing-field matching, and intersects the selected tool names with the live gateway tools/list result before giving schemas to the model. Execution remains gateway tools/call.

Pattern A: Meta-Tools (Dynamic Injection)

The agent is booted with only two "meta-tools" designed for discovery.

1. Local catalog search: Agent searches its cached assigned skills. The cache contains lightweight summaries and mapped tool names.
2. Schema loading: Once the agent identifies the correct tool, it loads the schema from the local catalog cache or refreshes the cache from portal-query.

Pattern B: Semantic Tool RAG (Zero-Shot Discovery)

For highly complex systems with thousands of skills:

1. Tool descriptions are embedded into a Vector Database (e.g., pgvector).
2. When the user prompts the system (e.g., "Reset my AWS password"), portal-query or the agent's local cache performs semantic search and retrieves the Top-3 most relevant JSON Schemas.
3. The agent boots with only those 3 tools in its context.

Pattern C: Multi-Agent Orchestration (Supervisor / Worker)

Hierarchy is mapped to agent teams.

1. A Supervisor Agent holds routing tools (e.g., delegate_to_finance, delegate_to_devops).
2. When delegate_to_devops is triggered, the supervisor routes to a DevOps Worker Agent, loading only the specific DevOps JSON schemas into its context.

4.3 Runtime Profiles And Materialization

One centrally assigned skill can serve several agent products without forcing every runtime to consume the same physical format.

Materializers are deterministic and versioned. Their output digest becomes part of the turn/runtime policy snapshot. Runtime-specific rendering may adapt file names or metadata, but it cannot add a tool or capability absent from the effective catalog.

For sandboxed profiles, the materializer emits immutable skill-package references, digests, sizes, and mount/entrypoint policy; it does not fetch from inside the sandbox. Trusted light-workflow-runner code downloads each package before sandbox creation, verifies digest/signature/provenance/scan bindings and archive safety, and stages it as a read-only mount with nodev, nosuid, and noexec unless a reviewed entrypoint requires execution. The worker may revalidate the mounted manifest, but neither the worker nor generated code receives artifact-store credentials or package-download egress. Verification or staging failure prevents the sandbox from starting.

Use the following content precedence, from strongest to weakest:

1. server and execution policy;
2. signed platform/tenant skill versions assigned to the agent;
3. reviewed user-specific skill configuration;
4. repository or workspace-local instructions;
5. prompts, retrieved data, messages, and tool output.

Repository-local and user-generated skills are useful context but untrusted. An agent-generated skill is stored as an inactive proposal. It becomes usable only after schema validation, security scanning, human or policy review, immutable packaging, and explicit assignment. Self-modification never hot-activates new authority in the current turn.

5. Example Flow: Dynamic Loading in Action

User: "I need to provision a new database for the marketing team."

1. Turn 1: Discovery
   • Agent Context: Has a local cache of assigned skill summaries.
   • Agent Action: Searches the local cache for provision database.
2. Turn 2: High-Level Awareness
   • Local Cache Result: Returns token-efficient summaries from the portal catalog: [{"name": "aws_rds_provision", "description": "Creates AWS RDS DB"}, {"name": "mongo_atlas_create", "description": "Creates Mongo cluster"}]
   • Agent Action: Decides AWS is needed and loads the cached schema for aws_rds_provision.
3. Turn 3: Strict Execution
   • Agent Catalog: Provides the full JSON schema (requiring instance_type, storage_gb).
   • Agent Action: Understands parameters and safely executes aws_rds_provision through the gateway tools/call path.

6. Operational Benefits & Security

By centralizing skills in a database, the platform gains enterprise-grade operational capabilities:

• Dynamic Updates: API endpoints, instructions, and schemas can be updated in the database without restarting agents.
• Permission-Aware Discovery (RBAC): By linking skills to LightAPI endpoint descriptions and api_endpoint_t, portal-query can limit catalog disclosure to the current agent or tenant, while runtime gateway policy still authorizes execution.
• A/B Testing: Portal catalog metadata can route 50% of an agent's requests to skill_v1 and 50% to skill_v2 to measure prompt/tool efficacy.
• Audit Logging: Catalog disclosure and gateway execution can be logged separately, preserving a compliance trail without moving tool execution into the registry.
• Distilled Memory RAG: Following the "Hindsight" pattern, raw conversation history (agent_session_history_t) is separated from RAG-optimized memory (session_memory_t). This prevents the "noisy context" problem while maintaining a perfect audit trail.
• Profile Reuse Without Privilege Reuse: The same logical skill can be rendered for enterprise, coding, workflow, or personal-assistant runtimes, while each runtime receives only its independently authorized tools and execution capabilities.
• Supply-Chain Controls: Executable packages are content-addressed, signed, scanned, reviewable, revocable, staged by the trusted runner before sandbox creation, mounted read-only, and always run through an approved sandbox profile.

7. LightAPI As Skill Source

API-backed skills should be generated from endpoint-level LightAPI descriptions whenever possible.

The skill registry should store skill metadata, access control, grouping, and agent-facing instructions. The LightAPI description should remain the source of truth for endpoint invocation and verification details.

Recommended flow:

1. Light-Portal creates or imports endpoint-level LightAPI descriptions.
2. API owners enrich endpoint descriptions with examples, behavior notes, result cases, and visibility.
3. Approved endpoint descriptions are published as agent skills.
4. The agent loads assigned skill summaries from portal-query and caches them locally.
5. When the agent selects a skill, it loads the relevant LightAPI disclosure level from the local cache or refreshes from portal-query.
6. Execution goes through the gateway tools/call path, preserving runtime policy and downstream authorization.

This avoids manually duplicating every API endpoint as a separate hand-written skill while still giving agents strict schemas and progressive disclosure.

8. Workflow-Backed Skills

Some skills need more than instructions and a curated tool set. A skill that must orchestrate several tools, wait for human approval, retry failed steps, run assertions, or preserve a durable audit trail should be backed by light-workflow.

The boundary should stay clear:

Workflow backing should be optional. Simple skills can stay as instructions plus tool mappings. Durable or regulated processes should link to workflow definitions and let light-workflow own execution.

Recommended storage:

1. Keep wf_definition_t.definition as the canonical workflow YAML.
2. Keep skill_t.content_markdown as the LLM-facing skill instruction body.
3. Add skill_workflow_t to link skills to workflow definitions with a role such as primary, validation, remediation, or test.
4. Treat skill_tool_t as the allowed tool set for a workflow-backed skill. Validation should flag workflow tool-call steps that are not linked to the skill.

The Portal Skill Workspace should embed a generic Workflow Editor instead of creating a skill-specific workflow runtime. The editor provides YAML editing, step preview, reference lookup, validation, and test runs. Skill authoring provides the surrounding context: skill metadata, taxonomy, allowed tools, effective prompt preview, and workflow link configuration.

9. Next Steps

1. Complete phase 3 by adding category and tag assignment to existing skill create/update forms, backed by entity_category_t and entity_tag_t with entity_type = 'skill'.
2. Save skill taxonomy through a composite skill command so the skill row and selected taxonomy associations are emitted from the same user action.
3. Move the richer authoring workspace, effective prompt preview, skill_tool_t.config formalization, workflow-backed skills, and "create skill from LightAPI/tool" flows to phase 3.5.
4. Build the generic Workflow Editor for YAML editing, parsed step preview, catalog references, validation, and workflow test runs.
5. Complete phase 4 agent assignment by improving the agent_skill_t UI, adding an Agent Definition assignment context, and adding a batch assignment composite command that emits one AgentSkillCreatedEvent per selected skill.
6. Enforce phase 4 assignment validation in command handlers and UI preflight: assigned skills must be active and must have at least one active direct skill_tool_t link. Workflow-backed skills still rely on skill_tool_t as the allowed tool set.
7. Keep live gateway tools/list runtime executability checks as a diagnostics or governance concern, not as phase 4 persistence validation.
8. Complete phase 5 for the Rust agent with the genai-query getEffectiveAgentCatalog endpoint, claim checks against host, sid, and env, local catalog caching, keyword/routing search, gateway tools/list intersection, and controller-driven cache invalidation.
9. Complete phase 6 governance for the Rust agent only: normalize sensitivity tiers to public, internal, confidential, and restricted; filter blocked tools before catalog disclosure; compare the effective catalog with gateway tools/list through /diagnostics/tools; and keep execution through gateway tools/call.
10. Enforce destructive, approval-required, and sensitivity metadata at the gateway with debug/auditInfo fields when a call is blocked. Do not use workflow audit_log_t for catalog disclosure; use auditInfo/file logging until a generic governance audit table is introduced.
11. Keep current active row plus aggregate version as the approval/version boundary until workflow-owned approval state is implemented.
12. Add publishing from LightAPI endpoint descriptions into the skill registry.
13. Migrate existing file-based skills into structured catalog payloads, keeping instructions in Markdown and converting parameters to JSON Schema.
14. Implement Pattern B (Semantic Tool RAG) after indexed catalog fields and embeddings are ready for production search.
15. Add runtime-profile compatibility, stable tool references, server-owned gateway/runner/workflow/fixed-service placement, schema/alias digests, and deterministic materializer metadata without overloading content_markdown or relying on a tool name as authority.
16. Add skill_package_t, immutable artifact publication, signature and scan verification, revocation, trusted runner-side download/safe extraction, read-only staging, and runner-only package execution. Workers receive no artifact-store credential or package-download authority.
17. Add reviewed proposal lifecycle for repository-local and agent-generated skills; never activate generated content automatically.
18. Add materializer conformance fixtures proving that enterprise, workflow, coding, personal-assistant, and external-adapter outputs preserve the same skill version and cannot widen its effective capability set.

Skill Workflow Orchestration

Status

Proposed demo design.

Executive Summary

This design describes a focused demo for agent-driven orchestration in Light-Fabric. The demo uses one agent with two skills:

1. A skill that starts a workflow which calls two REST APIs directly.
2. A skill that starts a workflow which calls the same two REST APIs through the MCP router.

Both paths solve the same business use case and return the same output. The visible difference is the execution trace:

• The REST workflow shows light-workflow invoking HTTP endpoints directly.
• The MCP workflow shows light-workflow invoking MCP tools/call, with light-gateway routing each tool call to the same backend REST APIs.

This demonstrates that skills provide agent-facing guidance and discovery, workflows provide durable orchestration, and the gateway provides the MCP data plane for tool execution.

Goals

• Show one agent selecting between two assigned skills.
• Show a workflow that orchestrates multiple REST APIs directly.
• Show a second workflow that orchestrates the same APIs through MCP tools.
• Keep the input and output contract identical across both workflows.
• Keep the demo small enough to explain in a few minutes.
• Preserve the runtime boundary: skills guide, workflows orchestrate, gateway executes MCP tool calls.

Non-Goals

• Do not benchmark REST versus MCP latency.
• Do not claim that MCP replaces REST. The demo shows two supported access patterns over the same backend capabilities.
• Do not require every skill to be workflow-backed. Simple skills can remain instructions plus allowed tools.
• Do not move MCP tool execution into the portal registry or agent catalog. Runtime tool execution stays on the gateway tools/call path.
• Do not make the demo depend on a large endpoint catalog.

Recommendation

Use two APIs, not one.

A one-API demo can show sequencing, but it does not clearly prove cross-service orchestration. Two APIs show a more realistic enterprise shape: the workflow has to collect data from one business capability and make a decision through another capability.

Use four endpoints for the base demo.

The base demo should be small enough to run repeatedly while still proving meaningful orchestration behavior.

General Agent And Workflow Boundary

The demo illustrates one direction of a bidirectional integration. The same boundary applies to enterprise, coding, and personal-assistant profiles:

The existing call.agent behavior remains the backward-compatible native-workflow mode. It runs inside light-workflow and validates schema-bound JSON. A future explicit agent-service mode submits a typed job to light-agent. The selected agent definition and policy—not the workflow prompt—decide whether light-agent handles the job in its service or through a runner sandbox.

The handoff includes authenticated caller and tenant context, correlation ID, input and output schemas, deadline, idempotency key, cost/action budget, cancellation behavior, and bounded delegation depth. light-workflow never spawns Codex, Pi, Claude Code, Hermes, OpenClaw, or another external agent binary directly. Those products can only run behind a registered light-agent runtime adapter in an approved execution profile.

Do not convert every agent turn into a workflow. Conversation history, streaming, interruptions, tool correction, personal channel delivery, and workspace-aware model loops remain agent-domain concerns. Conversely, an agent that starts a workflow stores the workflow reference and observes its public result; it does not reproduce the workflow state machine in its own context.

Reject cyclic or unbounded agent/workflow delegation. A child handoff inherits or narrows the initiating deadline, budget, data boundary, and authorization.

Demo Scenario

The demo domain is personalized offer recommendation.

The agent receives a prompt such as:

Recommend an offer for customer CUST-1001.

The agent can use either skill:

• Personalized Offer via REST Workflow
• Personalized Offer via MCP Router

If the prompt does not specify REST or MCP, the demo agent should not pick a path at random. It should ask a short clarification question:

Do you want to run this through the direct REST workflow or through the MCP
router workflow?

Scripted demos can avoid the clarification by naming the path in the prompt.

Both skills start a workflow that:

1. Loads the customer profile.
2. Loads customer preferences and consent.
3. Stops if the customer has not consented.
4. Searches for eligible offers.
5. Selects the best offer.
6. Records the offer decision.
7. Returns a normalized decision payload.

APIs And Endpoints

Customer Profile API

The Customer Profile API owns customer data and preferences.

Offer Decision API

The Offer Decision API owns eligible offer lookup and decision recording.

Demo API Runtime Services

The two business APIs should be implemented as real Rust services using the light-axum framework, not as ad hoc mocks. This keeps the demo aligned with normal Light-Fabric service lifecycle behavior:

• load runtime configuration from config-server
• bind HTTP using configured server settings
• register with controller through portal-registry
• appear in the control panel service-discovery view
• support gateway service discovery by serviceId and envTag

Recommended demo apps:

The ports are config defaults only. They must be configurable through config-server values so local, Docker, Kubernetes, and shared demo environments can choose different ports without recompiling.

Both services should expose:

GET /health

The API endpoints should return deterministic demo data. A database is not required for the first demo; in-memory seed data is enough as long as the data is stable and documented. If later demos need persistence, keep it behind the same endpoint contract.

Light-Axum Bootstrap

Each demo API should follow the normal light-axum pattern: implement AxumApp, return an axum::Router, and let LightRuntimeBuilder own binding, configuration, shutdown, and controller registration.

The service should read config from the same runtime config files used by other Light-Fabric services:

startup.yml
server.yml
portal-registry.yml

Example config-server values for the Customer Profile API:

startup.host: dev.lightapi.net
startup.externalConfigDir: /var/lib/demo-customer-profile-api/config-cache

light-config-server-uri: https://config-server.lightapi.svc.cluster.local:8435

server.serviceId: com.networknt.demo.customer-profile-1.0.0
server.environment: demo
server.ip: 0.0.0.0
server.advertisedAddress: demo-customer-profile-api
server.httpPort: 8085
server.enableHttp: true
server.enableHttps: false
server.enableRegistry: true
server.startOnRegistryFailure: true

portalRegistry.portalUrl: https://controller.lightapi.svc.cluster.local:8438

Example config-server values for the Offer Decision API:

startup.host: dev.lightapi.net
startup.externalConfigDir: /var/lib/demo-offer-decision-api/config-cache

light-config-server-uri: https://config-server.lightapi.svc.cluster.local:8435

server.serviceId: com.networknt.demo.offer-decision-1.0.0
server.environment: demo
server.ip: 0.0.0.0
server.advertisedAddress: demo-offer-decision-api
server.httpPort: 8086
server.enableHttp: true
server.enableHttps: false
server.enableRegistry: true
server.startOnRegistryFailure: true

portalRegistry.portalUrl: https://controller.lightapi.svc.cluster.local:8438

server.advertisedAddress must be a reachable address, not 0.0.0.0. In Kubernetes, use the Service DNS name. In local Docker Compose, use the Compose service name. In a native VM demo, use the VM hostname or another reachable address.

Controller Registration

The services should register with controller using the runtime's portal-registry integration. The controller registration payload must include at least:

• serviceId
• envTag
• protocol
• advertised address
• port
• discovery token or portal registry token, according to environment policy

After startup, the control panel should show two registered service instances:

com.networknt.demo.customer-profile-1.0.0 / demo
com.networknt.demo.offer-decision-1.0.0 / demo

The MCP router configuration should prefer these service IDs over fixed targetHost values where service discovery is available. Fixed targetHost values are still useful for a minimal local smoke test.

Optional Advanced Endpoints

The base demo should start with four endpoints. If we later want to demonstrate more workflow shapes, add one or two optional endpoints:

Agent, Skills, And Workflows

Use one agent so the demo highlights skill selection rather than agent handoff.

The skill registry should link each skill to its workflow definition through skill_workflow_t. The workflow definition remains canonical in wf_definition_t.definition. The skill content_markdown remains agent-facing guidance, not the executable workflow source.

Execution Paths

Direct REST Workflow

User prompt
  -> Demo Orchestration Agent
  -> Personalized Offer via REST Workflow skill
  -> light-workflow
  -> Customer Profile API
  -> Offer Decision API
  -> normalized decision result

This path is useful for showing direct, durable API orchestration.

MCP Router Workflow

User prompt
  -> Demo Orchestration Agent
  -> Personalized Offer via MCP Router skill
  -> light-workflow
  -> MCP tools/call
  -> light-gateway MCP router
  -> Customer Profile API
  -> Offer Decision API
  -> normalized decision result

This path is useful for showing MCP protocol orchestration over the same backend API capabilities.

Common Workflow Contract

Both workflows should accept the same input:

{
  "customerId": "CUST-1001",
  "channel": "portal"
}

Both workflows should return the same successful output shape:

{
  "status": "APPROVED",
  "customerId": "CUST-1001",
  "selectedOfferId": "OFFER-TRAVEL-01",
  "decisionId": "DEC-1001"
}

Both workflows should return comparable business outcomes for known edge cases:

{
  "status": "NO_CONSENT",
  "customerId": "CUST-3003",
  "reason": "Customer has not consented to personalized offers."
}

{
  "status": "NO_ELIGIBLE_OFFER",
  "customerId": "CUST-2002",
  "reason": "No active offer matches the customer profile and preferences."
}

Workflow Shape

The REST and MCP workflows should have the same logical steps.

The workflow should own branching, retries, and output normalization. The agent should not manually sequence each API call after the workflow starts.

Error Handling And Retries

Business outcomes and technical failures should be treated differently.

Business outcomes are expected workflow results and should not be retried:

• NO_CONSENT
• NO_ELIGIBLE_OFFER

Technical failures should use bounded workflow retries:

Recommended transient retry status codes:

408, 429, 502, 503, 504

The POST /offer-decisions step should include an idempotency key derived from the workflow instance id and selected offer id. This prevents duplicate decisions when a retry happens after the backend processed the first request but the response was lost.

For parity, the REST and MCP workflows should use the same retry policy. In the MCP path, the gateway should preserve enough error detail for the workflow trace to show the tool name, mapped backend endpoint, status code, and correlation id.

MCP Tool Mapping

The MCP workflow should use a small, explicit tool set.

The MCP tool input schemas should be normalized JSON objects. The gateway router maps those objects to path parameters, query parameters, or request bodies for the backend REST APIs.

The MCP skill should list these tools in skill_tool_t as its allowed runtime tool set. Workflow validation should flag an MCP tool-call step if it references a tool that is not linked to the skill.

Gateway Tool Configuration Example

Current gateway HTTP tool execution maps GET arguments to query parameters and sends non-GET arguments as JSON request bodies. To support endpoint shapes such as GET /customers/{customerId} without changing the backend API, the demo should add or configure explicit path-template substitution before the request is sent.

Recommended minimal mapping shape:

mcp-router.tools:
  - name: customer_get_profile
    description: Get a customer profile by id.
    protocol: http
    serviceId: com.networknt.demo.customer-profile-1.0.0
    envTag: demo
    path: /customers/{customerId}
    method: GET
    apiType: http
    inputSchema:
      type: object
      required:
        - customerId
      properties:
        customerId:
          type: string
    toolMetadata:
      pathParams:
        - customerId

With this mapping, the MCP tool call:

{
  "name": "customer_get_profile",
  "arguments": {
    "customerId": "CUST-1001"
  }
}

should be routed to:

GET /customers/CUST-1001

The path parameter should not also be appended as a query parameter. Arguments not listed under pathParams can still be appended as query parameters for GET requests or sent as JSON body fields for POST requests.

Skill Content Markdown Guidance

The skill content_markdown should explain when and how the agent should use the skill. It should not duplicate the workflow definition or the full API contract.

Example REST skill content:

## Purpose
Use this skill when the user asks for a personalized offer decision through the
direct REST workflow.

## Inputs
- customerId: customer identifier, such as CUST-1001
- channel: request channel, default portal

## Behavior
- Start workflow personalized-offer-rest-v1.
- Return the workflow result as the answer.
- Do not manually call offer APIs outside the workflow.
- If the user does not specify REST or MCP, ask which execution path they want.

Example MCP skill content:

## Purpose
Use this skill when the user asks to demonstrate MCP router orchestration for a
personalized offer decision.

## Inputs
- customerId: customer identifier, such as CUST-1001
- channel: request channel, default portal

## Behavior
- Start workflow personalized-offer-mcp-v1.
- The workflow will call MCP tools through the gateway.
- Return the workflow result as the answer.
- If the user does not specify REST or MCP, ask which execution path they want.

Structured execution metadata belongs in registry rows and workflow definitions, not only in markdown. The markdown is the LLM-facing explanation.

Output Normalization

The workflows should not pass raw endpoint responses directly to the agent. They should normalize backend responses into a stable business result.

Example raw POST /offer-decisions response:

{
  "decisionId": "DEC-1001",
  "customerId": "CUST-1001",
  "offerId": "OFFER-TRAVEL-01",
  "decision": "approved",
  "createdAt": "2026-05-25T14:12:00Z",
  "auditRef": "AUD-7788"
}

Normalized workflow output:

{
  "status": "APPROVED",
  "customerId": "CUST-1001",
  "selectedOfferId": "OFFER-TRAVEL-01",
  "decisionId": "DEC-1001"
}

The workflow should own this transformation so the REST and MCP variants produce identical final results even if their intermediate transport envelopes are different.

Demo Data

Use deterministic seed data so the demo is repeatable.

Seed offers:

Demo Script

Run the REST workflow path first:

Use the REST workflow skill to recommend an offer for CUST-1001.

Expected observation:

• The agent selects Personalized Offer via REST Workflow.
• The workflow trace shows direct HTTP calls to the Customer Profile API and Offer Decision API.
• The final response contains status=APPROVED and a decision id.

Run the MCP workflow path second:

Use the MCP router skill to recommend an offer for CUST-1001.

Expected observation:

• The agent selects Personalized Offer via MCP Router.
• The workflow trace shows MCP tools/call invocations.
• The gateway trace shows those tool calls routed to the same backend REST endpoints.
• The final response uses the same output shape as the REST workflow.

Then run one edge case:

Use either skill to recommend an offer for CUST-3003.

Expected observation:

• The workflow stops after the consent check.
• No offer decision is recorded.
• The result is NO_CONSENT.

Run one ambiguity case:

Recommend an offer for CUST-1001.

Expected observation:

• The agent asks whether to use the direct REST workflow or the MCP router workflow.
• After the user chooses, the agent starts the selected workflow.

Run one technical failure case:

Use the MCP router skill to recommend an offer for CUST-1001 while the Offer
Decision API returns one transient 503.

Expected observation:

• The workflow retries the failed tool-call step.
• The gateway trace records the failed offer_record_decision call and the successful retry.
• The final response still uses the normalized APPROVED output shape.

Portal Authoring Flow

The portal should make the demo visible from the existing GenAI and workflow surfaces:

1. Create or import the two REST APIs and four endpoint descriptions.
2. Implement the two APIs as light-axum services.
3. Add config-server values for both API services.
4. Start both services and verify controller registration.
5. Publish MCP router tools for the same four endpoints.
6. Create personalized-offer-rest-v1 in the workflow catalog.
7. Create personalized-offer-mcp-v1 in the workflow catalog.
8. Create the two skills in the skill registry.
9. Link each skill to its primary workflow through skill_workflow_t.
10. Link the MCP skill to its allowed tool set through skill_tool_t.
11. Assign both skills to Demo Orchestration Agent.
12. Use Skill Workspace preview and test panels to validate the effective prompt, workflow link, allowed tools, and sample test input.

Validation Rules

The authoring experience should validate the following before the demo is considered complete:

• Each skill has exactly one primary workflow link.
• The REST workflow does not require MCP tools.
• The MCP workflow references only MCP tools linked through skill_tool_t.
• Both workflows declare the same input schema.
• Both workflows declare the same normalized output shape.
• The four backend endpoint descriptions are active.
• Both demo API services load config from config-server.
• Both demo API services register with controller and appear in the control panel service-discovery view.
• The MCP router tools/list result includes the four expected tool names.
• MCP router tools resolve the demo APIs by serviceId and envTag in the service-discovery environment.
• MCP path-parameter mappings are validated before the workflow test run.
• POST /offer-decisions includes an idempotency key for retry safety.
• Test runs for CUST-1001, CUST-2002, and CUST-3003 produce the expected outcomes.

Observability

The demo should show three different traces:

1. Agent trace: which skill the agent selected and what workflow it started.
2. Workflow trace: step order, branches, retries, and final output.
3. Gateway trace: MCP tool name, mapped backend endpoint, status, duration, and correlation id for the MCP path.

Use the same correlation id across the agent request, workflow instance, and gateway calls where possible. This makes the REST and MCP execution paths easy to compare.

Security And Authorization

Authorization should be enforced at each layer:

• The agent can discover only assigned skills.
• The workflow can start only definitions visible to the authenticated caller or service identity.
• The MCP skill can expose only tools linked to the skill and allowed for the agent.
• The gateway still performs runtime MCP access checks before executing tools/call.
• Backend REST APIs continue to enforce their own authorization policies.

The skill registry is not a runtime bypass. It narrows discovery and guidance, while the workflow and gateway remain responsible for execution-time controls.

Context And Auth Propagation

The demo should explicitly show that caller context is preserved.

For direct REST workflow steps:

1. The workflow start request records the initiating user, host, tenant, correlation id, and authorization context.
2. The workflow executor exchanges the initiating authorization for a short-lived audience- and operation-scoped delegation token, or uses a workload identity whose on-behalf-of claims preserve the initiating subject, workflow instance, task, policy digest, and data boundary. It does not forward the caller's unrestricted bearer token.
3. Backend APIs enforce their normal authorization policies.

For MCP workflow steps:

1. light-workflow calls the gateway MCP endpoint with the same correlation, tenant, locale, and a short-lived workflow-task-scoped delegation token.
2. light-gateway validates the MCP request and runtime tool authorization.
3. The MCP router forwards only approved identity/delegation context to the backend REST API while regenerating transport-specific headers such as Host, Content-Length, and connection management headers.
4. Backend APIs see the same business identity context they would see on the direct REST path.

The trace should show this propagation without exposing sensitive token values.

Acceptance Criteria

• One demo agent has both skills assigned.
• The REST skill starts personalized-offer-rest-v1.
• The MCP skill starts personalized-offer-mcp-v1.
• Both workflows accept the same input JSON.
• Both workflows return the same normalized output shape.
• The REST workflow trace shows direct REST calls to two APIs.
• The MCP workflow trace shows MCP tools/call routed through the gateway to the same two APIs.
• The two APIs run as light-axum services with config-server supplied HTTP ports.
• The two APIs register with controller and are visible in the control panel service-discovery view.
• The demo succeeds for CUST-1001.
• The demo returns controlled business outcomes for CUST-2002 and CUST-3003.
• Ambiguous user prompts trigger a clarification question instead of random skill selection.
• A transient 503 from the Offer Decision API is retried and appears in the workflow trace.
• The MCP path preserves caller context through workflow, gateway, and backend REST calls.
• Neither workflow path can directly launch an external agent binary; a future service-mode agent task must enter light-agent through the typed job contract.
• Agent/workflow delegation preserves correlation and cannot exceed the initiating deadline, budget, authorization, or maximum delegation depth.

Related Designs

• Agentic Workflow
• Workflow Client Architecture
• Centralized Skills
• Light-Agent Execution
• LightAPI Description
• MCP Router

Hindsight Memory

Hindsight Memory is the core memory system for light-rs, designed to move beyond simple chat logs. Instead of just remembering what was said, the agent learns and forms mental models over time.

This design is strongly inspired by the paper Hindsight is 20/20: Building Agent Memory that Retains, Recalls, and Reflects and extends it with multi-tenant support.

1. Core Concepts

Hindsight memory organizes information into three distinct "Pathway" types:

1. World Facts: Objective truths about the environment (e.g., "The production server is in US-East-1").
2. Experiences: The agent's own history of actions and results (e.g., "I tried to deploy to US-East-1 and it failed due to a timeout").
3. Mental Models: Synthesized understandings formed by reflecting on facts and experiences (e.g., "Deployments to US-East-1 are unstable during peak hours").

2. The Three Operations

Interaction with the memory system is standardized into three primary operations:

Retain (Storage)

The retain operation ingests information. Behind the scenes, the system:

• Extracts entities and relationships.
• Normalizes time and temporal data.
• Stores the data in agent_memory_unit_t.

Recall (Retrieval)

The recall operation retrieves relevant context using a hybrid strategy:

• Semantic: Vector similarity using the hnsw index.
• Graph: Following links in agent_memory_link_t (causes, enables, prevents).
• Temporal: Time-series filtering.

Reflect (Synthesis)

The reflect operation performs "deep thinking." It analyzes existing memories to generate new insights, which are stored in agent_memory_reflection_t.

3. Database Architecture

The Hindsight system is fully integrated into the portal's multi-tenant schema:

4. Privacy & Multi-Tenancy

Isolation is managed at the Bank level using three scoping tiers:

1. Global Host Bank (user_id IS NULL, agent_def_id IS NULL):
   • Knowledge shared across all users and all agents within a specific host_id.
   • Ideal for organization-wide SOPs, common facts, and shared documentation.
2. Shared Agent Bank (user_id IS NULL, agent_def_id IS NOT NULL):
   • Knowledge shared by all users interacting with a specific agent type.
   • Used for maintaining a consistent agent "Persona" or specialized domain expertise.
3. Private User Bank (user_id IS NOT NULL):
   • Knowledge unique to a specific user.
   • Can be scoped further by agent_def_id to provide user-specific memory within a particular agent persona.
   • Used for personal preferences, private history, and individualized learning.

Memory-bank identity is not proof of access. Every recall, retain, reflection, export, resume, and deletion operation must derive host, principal, agent, and retention authority from authenticated server-side state. Personal-assistant profiles should default to a private user-and-agent bank unless an explicit sharing policy selects a broader scope.

Recalled memory is untrusted model context, not a system instruction or authorization grant. It cannot add tools, skills, credentials, network access, filesystem access, channel destinations, or execution capabilities.

5. Implementation Guide

To implement a "Learning Agent," follow this sequence in your application logic:

1. Ingestion: After an interaction or action result is durably accepted into the agent session event stream, call retain with its source class and correlation. Never let a memory-write failure retry an effectful action.
2. Context Loading: Before calling the LLM, call recall to fetch the most relevant 3-5 memories for the current prompt.
3. Scheduled Reflection: Run the reflect operation during idle time to compress raw experiences into high-level mental models.

Fine-Grained Authorization

The following is the raw material collected when I chat with AI about migrating the light-4j fine-grained authorization to light-rs to secure light-agent and light-gateway.

The information needs to be organized and documented into a design document for light-rs fine-grained authorization.

Question: We have a Java implementation of fine-grained authorization that we want to migrate to light-rs. In our java implementation, we have a middleware handler to verify the custom claims like role, group, attribute etc in the jwt token against endpoint specific rules defined in database and cached at the service. How should we handle the same requirement in rust?

Response:

In Rust, bridging the gap between dynamic, database-driven rules and high-performance web requests is a well-solved problem. If you are coming from Java, the architecture translates very cleanly, but takes advantage of Rust's async runtime and thread-safe concurrency primitives.

To handle fine-grained authorization (Attribute-Based Access Control / ABAC or Role-Based Access Control / RBAC) where rules are cached locally but backed by a database, you have two primary paths in Rust:

1. The Custom Middleware Approach (Closest to your current Java implementation)
2. The Policy Engine Approach (Using an industry-standard Rust authorization crate)

Here is how you handle this requirement idiomatically in Rust, assuming you are using Axum (the current standard web framework in Rust).

Approach 1: Custom Middleware with Async Caching

In Java, you likely used something like Guava or Caffeine for your local cache. In Rust, the exact equivalent for high-performance, concurrent, async-aware caching is the moka crate.

Here is the architectural blueprint:

1. Define your custom claims using serde.
2. Setup a shared Application State holding your Database connection pool (e.g., sqlx) and your local Cache (moka).
3. Create an Axum Middleware to intercept the request, parse the JWT, consult the cache based on the route, and authorize the request.

1. Dependencies (Cargo.toml)

axum = "0.7"
jsonwebtoken = "9.0"
moka = { version = "0.12", features = ["future"] } # Async cache (Rust's Caffeine)
sqlx = { version = "0.7", features = ["postgres", "runtime-tokio"] }
serde = { version = "1.0", features = ["derive"] }

2. Defining Claims and State

#![allow(unused)]
fn main() {
use axum::{extract::State, http::Request, middleware::Next, response::Response};
use moka::future::Cache;
use serde::{Deserialize, Serialize};
use sqlx::PgPool;
use std::sync::Arc;

// 1. Define your custom JWT claims
#[derive(Debug, Serialize, Deserialize, Clone)]
struct CustomClaims {
    sub: String,
    roles: Vec<String>,
    groups: Vec<String>,
    attributes: std::collections::HashMap<String, String>,
    exp: usize,
}

// 2. Define the Endpoint Rule (what you fetch from DB)
#[derive(Clone)]
struct EndpointRule {
    required_roles: Vec<String>,
    // add required_groups, attributes, etc.
}

// 3. Define the Application State to share across your app
struct AppState {
    db: PgPool,
    // Cache keyed by String (e.g., "GET:/api/data") returning an EndpointRule
    rule_cache: Cache<String, EndpointRule>,
}
}

3. The Authorization Middleware

In Axum, middleware is written as an asynchronous function that takes the request, does some work, and either rejects it or passes it to the Next handler.

#![allow(unused)]
fn main() {
use axum::http::StatusCode;
use axum::response::IntoResponse;

async fn fine_grained_authz_middleware(
    State(state): State<Arc<AppState>>,
    req: Request<axum::body::Body>,
    next: Next,
) -> Result<Response, StatusCode> {
    
    // 1. Extract and decode the JWT from Authorization header
    let auth_header = req.headers().get("Authorization").and_then(|h| h.to_str().ok());
    let claims = decode_jwt(auth_header).ok_or(StatusCode::UNAUTHORIZED)?;

    // 2. Identify the endpoint being accessed (e.g., "GET:/api/users/123")
    // Note: In practice, use req.extensions() to get the matched generic route template
    // rather than the raw URI so "/api/users/123" matches "/api/users/{id}"
    let endpoint_key = format!("{}:{}", req.method(), req.uri().path());

    // 3. Check Cache or Fallback to DB
    let rule = match state.rule_cache.get(&endpoint_key).await {
        Some(cached_rule) => cached_rule,
        None => {
            // Cache miss: Fetch from database
            let db_rule = fetch_rule_from_db(&state.db, &endpoint_key)
                .await
                .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?;
            
            // Populate cache
            state.rule_cache.insert(endpoint_key, db_rule.clone()).await;
            db_rule
        }
    };

    // 4. Execute Fine-Grained Authorization Logic
    let is_authorized = rule.required_roles.iter().any(|role| claims.roles.contains(role));
    // ... check groups, evaluate custom attribute expressions, etc.

    if !is_authorized {
        return Err(StatusCode::FORBIDDEN);
    }

    // 5. Pass to the actual route handler!
    Ok(next.run(req).await)
}

// Dummy helper functions to make the example compile mentally
fn decode_jwt(_header: Option<&str>) -> Option<CustomClaims> { /* ... */ unimplemented!() }
async fn fetch_rule_from_db(_db: &PgPool, _key: &str) -> Result<EndpointRule, ()> { /* ... */ unimplemented!() }
}

4. Wiring it up

use axum::{routing::get, Router};

#[tokio::main]
async fn main() {
    let state = Arc::new(AppState {
        db: PgPool::connect("postgres://...").await.unwrap(),
        rule_cache: Cache::builder()
            .max_capacity(10_000)
            .time_to_live(std::time::Duration::from_secs(300)) // 5 minute TTL
            .build(),
    });

    let app = Router::new()
        .route("/api/secure-data", get(|| async { "Secret Data" }))
        // Apply the middleware to all routes above this line
        .route_layer(axum::middleware::from_fn_with_state(state.clone(), fine_grained_authz_middleware))
        .with_state(state);

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

Approach 2: Using a Dedicated Policy Engine (Recommended for complex rules)

If your endpoint-specific rules are highly complex (e.g., "User must be in Group X AND have Attribute Y = 'finance', UNLESS Role is 'Admin'"), writing that evaluation logic manually in Rust gets messy.

Instead of writing custom evaluation logic, the Rust ecosystem heavily relies on external Policy Engines for ABAC/RBAC. The two leaders are:

1. AWS Cedar (cedar-policy) - Highly Recommended

Developed by Amazon Web Services in Rust, Cedar is a blazing-fast language for defining permissions.

• You store your Cedar policies in your database as text.
• Your Rust middleware fetches the Cedar policy string from the DB, compiles it (and caches the compiled policy using moka).
• You pass the JWT CustomClaims into the Cedar engine as a context entity.
• Cedar evaluates the claims against the policy in microseconds.

2. Casbin (casbin)

Casbin is a very popular authorization library that exists in Java, Go, and Rust.

• It supports ACL, RBAC, and ABAC.
• It has native adapters for sqlx (Postgres/MySQL). You don't even need to write the caching logic yourself; casbin-rs handles reading the rules from the database and keeping them cached in memory automatically.

Summary

• For simple Role/Group matching: Stick to the Custom Middleware approach using moka for async caching and axum::middleware to intercept requests. It is functionally identical to your Java approach but extremely fast.
• For complex Attribute evaluation: Use your middleware to parse the JWT, but delegate the actual rule evaluation to cedar-policy or casbin.

Question: Could you please provide some examples for cedar-policy and casbin? For example, what is the format in database? In our system, we are using a yaml rule engine to evaluate the fine-grained authorization. We create some rules users can choose and they can also create their own rules if necessary.

Response:

Transitioning from a custom YAML rule engine to an industry-standard policy engine is a fantastic move. Both AWS Cedar and Casbin are designed precisely for this kind of "user-defined fine-grained rules" requirement, but they take very different approaches to how rules are written and stored.

Here is a breakdown of how both engines work, what their database format looks like, and how you map your JWT claims to them in Rust.

1. AWS Cedar (cedar-policy) - Best for Complex/Custom Rules

Cedar uses a custom, highly readable Domain Specific Language (DSL). It is specifically built to evaluate ABAC (Attribute-Based Access Control) using contextual data like JWT claims.

The Format (In the Database)

In your database, you do not need complex tables. You simply store the Cedar policies as plain text strings in a standard TEXT or VARCHAR column.

If a user wants to create a custom rule saying, "Allow access if the user's JWT has the 'finance' group and a clearance level greater than 3," the Cedar policy stored in the DB looks like this:

// Database column: policy_text
permit (
    principal,
    action == Action::"read_data",
    resource == Resource::"secure_endpoint"
)
when {
    context.jwt.groups contains "finance" &&
    context.jwt.attributes.clearance_level > 3
};

For "predefined rules that users can choose," Cedar has Policy Templates. You store the template once, and users just link their parameters to it.

// Template: "Require specific group"
permit(principal, action, resource)
when { context.jwt.groups contains ?required_group };

How you execute it in Rust

When a request comes in, you fetch the relevant Cedar text strings from your database, pass in the JWT claims as the Context, and let Cedar evaluate it.

#![allow(unused)]
fn main() {
use cedar_policy::{Authorizer, Context, Decision, Entities, PolicySet, Request};
use serde_json::json;
use std::str::FromStr;

fn evaluate_cedar_rule(db_policy_text: &str, jwt_claims: &serde_json::Value) {
    // 1. Parse the text policy from the database
    let policies = PolicySet::from_str(db_policy_text).expect("Invalid policy format");

    // 2. Map your JWT claims directly into the Cedar "Context" using JSON
    let context_json = json!({
        "jwt": jwt_claims
    });
    let context = Context::from_json_value(context_json, None).unwrap();

    // 3. Create the evaluation request
    let request = Request::new(
        Some("User::\"Alice\"".parse().unwrap()), 
        Some("Action::\"read_data\"".parse().unwrap()), 
        Some("Resource::\"secure_endpoint\"".parse().unwrap()), 
        context,
        None,
    ).unwrap();

    // 4. Evaluate
    let authorizer = Authorizer::new();
    let entities = Entities::empty(); // Used if fetching hierarchical data
    let answer = authorizer.is_authorized(&request, &policies, &entities);

    if answer.decision() == Decision::Allow {
        println!("Access Granted!");
    } else {
        println!("Access Denied. Failed policies: {:?}", answer.diagnostics().errors());
    }
}
}

2. Casbin (casbin-rs) - Best for Tabular/Database-Native Rules

Casbin works fundamentally differently. It splits authorization into two parts: the Model (a config file defining the structure of your rules) and the Policies/Rules (the actual data stored in the database).

The Format (In the Database)

Casbin doesn't store a DSL string. Instead, it natively connects to your database using an adapter (like sqlx-adapter) and creates a table usually called casbin_rule.

The table structure looks exactly like a CSV file, with columns: ptype, v0, v1, v2, v3, v4, v5.

If a user selects a predefined rule to allow the finance_admin role to read /api/data, Casbin inserts a row into your database like this:

If a user writes a custom ABAC rule using a UI (e.g., clearance > 3), Casbin can store the evaluation expression as a string in one of the columns (evaluated internally via the rhai scripting language):

How you execute it in Rust

To make Casbin evaluate JWT attributes dynamically, you define a model.conf file that tells Casbin to evaluate (eval) the string stored in the database.

The model.conf File:

[request_definition]
r = sub, obj, act

[policy_definition]
p = sub_rule, obj, act

[policy_effect]
e = some(where (p.eft == allow))

[matchers]
# This matcher says: check if the object and action match, 
# AND evaluate the ABAC rule stored in the database (p.sub_rule) against the request subject (r.sub)
m = r.obj == p.obj && r.act == p.act && eval(p.sub_rule) 

The Rust Code:

#![allow(unused)]
fn main() {
use casbin::{CoreApi, Enforcer, DefaultModel};
use sqlx_adapter::SqlxAdapter;
use std::collections::HashMap;

// A struct representing your JWT Claims
#[derive(Clone)]
struct JwtClaims {
    groups: Vec<String>,
    clearance: i32,
}

async fn evaluate_casbin() {
    // 1. Connect to DB. The adapter automatically fetches the rules from the `casbin_rule` table.
    let adapter = SqlxAdapter::new("postgres://user:pass@localhost/db", 8).await.unwrap();
    let mut enforcer = Enforcer::new("model.conf", adapter).await.unwrap();

    // 2. Parse the JWT for the incoming request
    let claims = JwtClaims {
        groups: vec!["finance".to_string()],
        clearance: 5,
    };

    // 3. Casbin in Rust uses `rhai` under the hood for dynamic object evaluation.
    // You map your JWT fields into a format the engine understands.
    let mut sub_map = HashMap::new();
    sub_map.insert("groups", claims.groups);
    sub_map.insert("clearance", claims.clearance);

    // 4. Enforce the rules against the DB
    // Request is: Subject (JWT Claims Map), Object (/api/data), Action (read)
    if enforcer.enforce((sub_map, "/api/data", "read")).unwrap() {
        println!("Access Granted!");
    } else {
        println!("Access Denied!");
    }
}
}

Which one maps better to your YAML Rule Engine?

AWS Cedar is highly recommended for your use case.

Because you currently use a YAML rule engine where users define complex logical rules, your users are already accustomed to defining logical expressions.

1. Translation: It is very easy to write a script that takes your existing YAML definitions and converts them into Cedar text policies.
2. Safety: Cedar is statically typed and formally verified. If a user writes an invalid custom rule, Cedar will fail to parse it instantly and give you a helpful error message to show in your UI. Casbin's eval() logic can sometimes be brittle at runtime if the user types bad syntax.
3. Database Schema: With Cedar, you control your database schema. You just add a policy_text column to your existing "Rules" table. Casbin requires taking over a table (casbin_rule) to map to its strict CSV-like format.

Question: In our current implementation, we define all the persmissions and filters from UI and save the permissions and picked up rule in database. During server startup, it load everything locally in yaml format like the following. One of the pros is that our technical team write the rules, and the user or api owner just define the roles, groups, positions, attributes for the endpoint. The rule will be executed locally on the target server without going to the database so the performance is very good. If any permission changed for the target server, we can trigger a config reload from controller to ask the server to reload the config/permission. I am not sure if we should replace this implementation with Cedar. One of the feature we have is the column and row filter and I don't think Cedar support it. What do you think?

rule.endpointRules:
  echo@call:
    req-acc:
    - allow-role-based-access-control.lightapi.net
    permission:
      roles: mcp-reader
  /v1/pets@get:
    req-acc:
    - allow-role-based-access-control.lightapi.net
    permission:
      roles: host-admin
  /v1/accounts@get:
    req-acc:
    - allow-role-based-access-control.lightapi.net
    res-fil:
    - response-column-filter.lightapi.net
    - response-row-filter.lightapi.net
    permission:
      col:
        role:
          teller: '["accountNo","userId","accountType","firstName","lastName"]'
          account-manager: '["accountNo","userId","accountType","firstName","lastName","status"]'
      row:
        role:
          teller:
          - colName: accountType
            colValue: C
            operator: =
      roles: account-manager teller

Response:

You have excellent architectural instincts. You are absolutely right to hesitate, and your concern about column and row filtering is the exact reason you probably should not replace your current system with Cedar.

Your current design is actually highly sophisticated. Let’s break down why your current implementation is so strong, why Cedar would struggle with your specific requirements, and how you should idiomatically build your current design in Rust.

Why Cedar is NOT a drop-in replacement for your system

AWS Cedar (and most standard policy engines like Casbin or OPA) are designed as Binary Decision Engines. You give them a Request, and they return an Allow or Deny.

The Missing Feature: Data Filtering (Masking) Your system handles two fundamentally different concerns in one elegant YAML file:

1. Access Control (req-acc): Can the user access the /v1/accounts endpoint? (Cedar does this perfectly).
2. Data Filtering (res-fil): Which rows and columns can the user see in the response? (Cedar does not do this natively).

If you forced Cedar to do column filtering, you would have to misuse its "Annotations" feature to attach custom metadata to policies, read the output, and then write a custom Rust engine to parse that metadata and filter the JSON anyway. You would essentially be rebuilding your existing system, just with Cedar awkwardly wedged in the middle.

Strengths of your current architecture

What you have built is essentially a custom API Gateway / Sidecar Data Masking Engine.

1. Performance: Loading rules into memory at startup means zero network latency. (Matches Cedar).
2. Hot Reloading: Fetching updates via a controller is standard cloud-native practice. (Matches Cedar).
3. Separation of Concerns: Tech team writes the underlying engine logic (allow-role-based-access-control), while API owners just write YAML configs. (Matches Cedar’s Policy Templates).
4. Row/Column filtering: Natively understood by your engine. (Far exceeds Cedar).

Verdict: Do not switch to Cedar. Your current YAML-based, locally cached evaluation engine is a perfect fit for your business requirements.

How to implement your architecture in Rust

Since you are migrating to or building in Rust, your current Java-based architecture translates beautifully. In fact, Rust will make this system significantly faster and more memory-efficient.

Here is how you replicate your exact Java architecture—including the hot-reloading and filtering—in Rust.

1. Hot-Reloading using arc-swap

In Java, hot-reloading configuration safely across threads can be tricky. In Rust, the industry standard for "read-heavy, occasionally-updated" memory structures is the arc-swap crate. It allows your web server to read the YAML rules lock-free at millions of requests per second, while your controller can swap out the rules in the background instantly.

#![allow(unused)]
fn main() {
use arc_swap::ArcSwap;
use serde::Deserialize;
use std::sync::Arc;
use std::collections::HashMap;

// 1. Map your YAML exactly to Rust Structs
#[derive(Deserialize, Debug, Clone)]
struct EndpointRule {
    #[serde(rename = "req-acc")]
    req_acc: Option<Vec<String>>,
    #[serde(rename = "res-fil")]
    res_fil: Option<Vec<String>>,
    permission: PermissionConfig,
}

#[derive(Deserialize, Debug, Clone)]
struct PermissionConfig {
    roles: String,
    col: Option<HashMap<String, HashMap<String, String>>>, // Map for roles to column JSON strings
}

// 2. Wrap your entire config in an ArcSwap
lazy_static::lazy_static! {
    static ref CONFIG: ArcSwap<HashMap<String, EndpointRule>> = ArcSwap::from_pointee(HashMap::new());
}

// 3. Background task to listen to the Controller and Hot-Reload
async fn reload_config_from_controller(new_yaml_str: &str) {
    let new_config: HashMap<String, EndpointRule> = serde_yaml::from_str(new_yaml_str).unwrap();
    // Swaps the pointer atomically. 
    // All new requests see the new rules instantly. Old requests finish using the old rules.
    CONFIG.store(Arc::new(new_config));
}
}

2. The Request Access (req-acc) Middleware

You would write an Axum middleware that intercepts the request, looks up the current endpoint in the arc-swap configuration, checks the JWT roles against permission.roles, and rejects the request if it fails.

#![allow(unused)]
fn main() {
// Inside your Axum middleware
let current_config = CONFIG.load();
if let Some(rule) = current_config.get("/v1/accounts@get") {
    let required_roles: Vec<&str> = rule.permission.roles.split_whitespace().collect();
    if !user_roles.iter().any(|r| required_roles.contains(&r.as_str())) {
        return Err(StatusCode::FORBIDDEN); // req-acc fails
    }
}
}

3. The Response Filtering (res-fil) Middleware

This is where Rust shines. Because Axum and Actix allow you to intercept the response body after the handler completes but before it goes to the user, you can apply your column filtering dynamically.

Using serde_json, you can strip out columns that the user isn't allowed to see based on the col mapping in your YAML.

#![allow(unused)]
fn main() {
use serde_json::Value;

fn apply_column_filter(mut response_json: Value, allowed_columns_json: &str) -> Value {
    // 1. Parse the allowed columns from the YAML string (e.g., '["accountNo","firstName"]')
    let allowed_cols: Vec<String> = serde_json::from_str(allowed_columns_json).unwrap();

    // 2. Filter the JSON object
    if let Value::Object(ref mut map) = response_json {
        // Retain only the keys that are in the allowed_cols list
        map.retain(|key, _| allowed_cols.contains(key));
    }
    
    response_json
}
}

Summary

Keep your current system!

1. The YAML approach is great. It acts as a perfect declarative contract between your API owners and your technical rules engine.
2. Cedar is the wrong tool for Data Masking. Cedar is for strict Allow/Deny decisions, not mutating response bodies or filtering data.
3. Rust will supercharge this. By using serde_yaml to parse your config, arc-swap for lock-free hot-reloading, and serde_json for column masking inside an Axum middleware, you will get a system that does exactly what your Java system does, but with significantly less memory overhead and higher throughput.

Agent Engine Pattern

The Agent Engine Pattern is the architectural standard for building industrial-grade, metadata-driven AI platforms within the Light-Fabric ecosystem.

In this model, the Rust Runtime acts as a high-performance Orchestrator, while the Application Logic resides in externalized metadata (JSON/YAML) and the Hindsight Memory database.

1. Why the Metadata-Driven Approach?

• Separation of Concerns: Complex platform logic (security, retries, database connectivity, LLM integration) is implemented once in Rust. Business logic—defining agent personas, goals, and steps—is "programmed" via JSON or Database records.
• Hot-Reloading: Using the arc-swap crate and YAML-based rule engines, agent personas, model parameters, and tool access can be updated in real-time without a server restart.
• Elastic Scalability: Deploy one shared agent engine and specialize it from registry metadata. The public light-agent service owns sessions and reasoning, light-agent-worker hosts sandboxed coding/runtime adapters, and the optional light-agent-channel owns messaging connections. These are thin trust-boundary executables over shared domain crates, not separate persona engines.
• High Performance: Rust's asynchronous tokio runtime allows a single engine instance to manage thousands of concurrent agentic sessions with minimal memory overhead.

2. The Core Architecture: Engine vs. Content

To function as a generic interpreter, the Light-Fabric Engine relies on four primary components:

A. The Tool & Skill Registry (The "Hands")

The engine maps string identifiers in the workflow JSON (e.g., "call": "get_customer_data") to governed API/MCP capabilities, fixed actions, or immutable sandbox packages.

• Implementation: Uses a ToolRegistry with trait objects (Box<dyn Tool>) or dynamic dispatch to MCP (Model Context Protocol) servers.
• Logic: When the LLM requests a tool call, the engine verifies permissions via Fine-Grained Authorization, executes the tool, and feeds the result back into the context.

The registry is not an authorization or execution boundary. Mutable script source is never trusted because it appears in metadata; executable packages must be content-addressed, reviewed, and run through an approved ExecutionBackend.

B. Hindsight State Manager (The "Memory")

Unlike simple session storage, the state manager persists every step of the agentic interaction into biomimetic memory banks.

• Implementation: Every "turn" in the conversation is saved as a unit_t in the Hindsight database.
• Benefit: Provides fault tolerance (resuming from a crashed step) and "Recall" capabilities, allowing agents to remember past interactions across different sessions.

C. Prompt Templating (The "Mind")

System prompts and instructions are stored as templates rather than hardcoded strings.

• Implementation: Uses the tera or rinja engines for high-performance string interpolation.
• Example: "You are a {{agent_role}}. Your current objective is to {{agent_goal}}."
• Rust Logic: The engine merges runtime context (user input, memory recall, tool results) into the template before calling the LLM.

D. Policy Engine (The "Shield")

Before any tool execution or data retrieval, the engine consults the Light-Rule middleware.

• Logic: Ensures the agent has the authority to access specific data or execute specific functions, preventing "prompt injection" from leading to unauthorized actions.

3. Conceptual Implementation in Rust

The AgentEngine in Light-Fabric follows a non-blocking, async loop:

#![allow(unused)]
fn main() {
pub struct AgentEngine {
    registry: Arc<ToolRegistry>,
    memory: Arc<HindsightClient>,
    rules: Arc<RuleEngine>,
}

impl AgentEngine {
    pub async fn execute_step(&self, session_id: Uuid, task: Task) -> anyhow::Result<()> {
        // 1. Fetch current context from Hindsight Memory
        let mut context = self.memory.get_context(session_id).await?;

        // 2. Resolve Task Type (Agentic vs. Tool Call)
        match task {
            Task::LlmCall { agent_id, prompt_template } => {
                // Render prompt with Tera
                let prompt = self.render_prompt(prompt_template, &context)?;

                // Call LLM Provider
                let response = self.llm_provider.chat(prompt, &context).await?;

                // Retain turn in Hindsight
                self.memory.retain_turn(session_id, response).await?;
            },
            Task::ToolCall { tool_name, params } => {
                // 3. Enforce Fine-Grained Authorization
                if self.rules.authorize(session_id, &tool_name).await? {
                    let result = self.registry.call(&tool_name, params).await?;
                    context.add_result(tool_name, result);
                }
            }
        }

        // 4. Update Session State
        self.memory.checkpoint(session_id, context).await
    }
}
}

4. Operational Challenges & Solutions

1. Tool Versioning: As the platform evolves, tools may change. Light-Fabric handles this by versioning tool definitions in the Registry, ensuring old workflows remain compatible with the tools they were designed for.
2. Safe Execution: A logical agent does not automatically own a sandbox. Remote model and gateway-only work can remain in the long-lived service; shell, filesystem, browser, local MCP, CLI-model, or untrusted execution uses an approved ExecutionBackend such as a microVM, rootless container, Kubernetes Job, dedicated VM, or fixed external action. The effective policy must match the backend's proven boundary.
3. Observability: Because the engine is generic, tracing is built into light-runtime. Traces record session, turn, model-call, tool-action, policy, lease, and result metadata without treating private hidden reasoning as an observable platform contract.

The Recommendation

Light-Fabric adopts this "Engine-first" philosophy to keep one durable agent model across enterprise, coding, and personal-assistant profiles. Agent definitions and skills are data; shared Rust crates implement sessions, policy, memory, runtime protocols, and audit; thin service, sandbox-worker, and channel binaries enforce their distinct lifecycles and trust boundaries.

See Light-Agent Execution for the concrete service, session, turn, tool, runner, and sandbox boundaries.

Light-Agent Execution

Status

Proposed.

This design defines how interactive Light agents are hosted, how agent turns and tool actions are authorized and recovered, and when execution must move from a long-lived agent service into a runner-managed sandbox.

It complements:

• Light-Workflow Runner
• Execution Backends And Sandbox Execution
• Agent Engine Pattern
• Hindsight Memory

Decision

A logical agent is not an isolation unit.

Do not create a container, VM, or sandbox for every agent definition by default. Use a hybrid model:

• run interactive API-based agents in a long-lived light-agent service;
• group service instances by tenant, trust, model-provider, network, and data boundary;
• execute local CLI providers, code, shell, browser, filesystem, private local MCP, and other effectful work through the shared controller/runner execution substrate;
• select the sandbox backend from server-owned policy and runner capabilities;
• use a dedicated VM or external fixed service only when the workload, credential, regulatory, or host-exposure requirement justifies it.

The same agent session may use more than one execution boundary. A remote model call can remain in the service, an HTTP or MCP API tool can run through light-gateway, a code-repair action can run in a Cube or Docker sandbox, and a publish action can run in a separate fixed service.

Support three product profiles through the same agent control plane:

• enterprise business agents use remote model providers and typed API/MCP tools through light-gateway;
• coding agents run a workspace-aware model/tool loop in a runner-managed sandbox;
• personal assistants use the same session, memory, policy, and skill model, but receive messages and proactive triggers through a separately deployed channel gateway and use an edge runner for local-device effects.

These are runtime profiles, not forks of the agent engine. Share the durable agent domain model, policy evaluator, skill resolver, runtime protocol, and audit vocabulary. Add a separate executable only where the trust boundary or process lifecycle is materially different.

Problem

Agent definitions, chat sessions, model calls, tool calls, and local execution have different lifecycles and trust boundaries. Treating all of them as one process creates two bad extremes:

1. one shared process receives every tenant credential, workspace, tool, and side effect; or
2. every logical agent permanently owns a container or VM even when it only makes a bounded remote model call.

The first is unsafe. The second is expensive, slow to scale, and ties metadata to infrastructure unnecessarily.

Agent execution also differs from a workflow task:

• a session can contain many turns;
• a turn can contain several model calls and tool actions;
• the client expects interactive streaming and cancellation;
• multiple turns may share conversation memory;
• a coding session may optionally reuse a workspace;
• an agent can ask for human approval without keeping compute alive.

The execution substrate can be shared with workflows, but session and turn orchestration remain owned by light-agent.

Current Runtime Boundary

The current apps/light-agent executable is a long-lived Axum service.

At startup it creates one process-wide AgentState containing:

• one model provider and model;
• one MCP gateway client;
• one portal query client and portal credential;
• one PostgreSQL pool and memory store;
• one host identity;
• one optional agent definition ID;
• one catalog cache.

The service exposes a WebSocket chat route. Each connection:

1. accepts or creates a session ID;
2. uses the session UUID as its memory-bank ID;
3. loads conversation history;
4. accepts user messages sequentially on that socket;
5. recalls memory;
6. selects portal catalog tools and, because every currently executable entry is gateway-placed, intersects them with gateway tools/list;
7. runs up to ten model/tool iterations;
8. calls selected tools through light-gateway;
9. persists the final conversation history and experience.

Docker Compose and Kubernetes deploy light-agent as a persistent service. The current account, advisor, and technical-support scripts use distinct service identities, which makes one deployment per configured agent profile the practical short-term model.

This implementation is a useful service foundation, but it is not yet a durable or strongly isolated agent execution engine.

Current Gaps

The first implementation work must close these gaps before broad multi-user or effectful use:

1. A caller-supplied sessionId is not bound inside light-agent to an authenticated user and agent definition before memory is loaded.
2. The existing memory schema can store user_id and agent_def_id, but current session-bank creation does not populate those ownership fields.
3. Catalog selection limits the tool specifications shown to the model, but a returned tool name is not revalidated against the accepted set immediately before tools/call.
4. Tool arguments fall back to an empty object on malformed JSON instead of failing closed and being checked against the selected input schema.
5. There is no durable agent-turn or tool-attempt record. A crash after an effectful tool call and before history persistence can leave an unknown outcome that a reconnect may repeat.
6. Concurrent connections using the same session can race history updates.
7. Turn-level deadlines, token/cost budgets, tool-call budgets, cancellation, output limits, and concurrency quotas are incomplete.
8. Tool results are inserted into model context without a strict byte/token limit or an explicit untrusted-content boundary.
9. CLI providers spawn local child processes. A child inherits the service environment unless explicitly scrubbed and can therefore see process-wide credentials.
10. Claude Code agent mode currently requests its permission-bypass mode. It must never run inside a shared credential-bearing agent service.
11. Local helper scripts contain default bearer-token literals. Those values must be removed and rotated regardless of whether they were intended only for development.
12. Portal-command is the production memory-write default. Direct PostgreSQL writes are retained only as an explicitly enabled local/development compatibility mode.
13. The current MCP client path forwards the caller Authorization header to light-gateway. It does not yet exchange it for a token narrowed to the agent, turn/action, tool, data boundary, and policy digest.

Goals

• Preserve low-latency interactive chat and streaming.
• Keep logical agent definitions independent from deployment units.
• Bind every session and turn to authenticated tenant, host, user, agent, and policy identities.
• Serialize concurrent same-session prompts through a bounded durable queue.
• Provide durable, idempotent turn and tool-action state.
• Reuse runner registration, scheduling, leases, fencing, watchdog, artifact, credential, and backend contracts.
• Keep workflow tasks and agent turns under their respective orchestrators.
• Route remote API tools through light-gateway.
• Downscope caller authority to the exact agent turn/action and data boundary before gateway dispatch.
• Route local or effectful execution through an approved ExecutionBackend.
• Support task-scoped and bounded session-scoped sandboxes.
• Support enterprise, coding, and personal-assistant profiles without forking the agent domain model.
• Treat Codex, Pi, Claude Code, Gemini CLI, Kilo, and similar products as agent runtime adapters rather than ordinary model providers.
• Materialize one centrally governed skill into profile-specific prompt, schema, package, and sandbox inputs.
• Normalize messaging channels and proactive triggers into authenticated, idempotent agent turns.
• Allow typed agent-to-workflow and workflow-to-agent handoffs without moving interactive turn ownership into light-workflow.
• Fail closed when a deployment cannot satisfy the required boundary.
• Release action leases, model channels, and action credentials while waiting for human approval. Clean task sandboxes; retain a non-secret session workspace only through a distinct bounded hold/checkpoint policy.

Non-Goals

• Do not convert every chat message into a workflow instance.
• Do not give every agent definition a permanent container or VM.
• Do not make controller-rs the owner of conversation or workflow state.
• Do not let the model choose its isolation boundary or credentials.
• Do not let local runner configuration weaken server-owned policy.
• Do not treat a Docker container, Kubernetes pod, or Toolbx as a universal security boundary.
• Do not expose publish, signing, deployment, or unrestricted shell credentials to a general agent loop.
• Do not require a sandbox for a bounded remote model call with no local effects.
• Do not rely on the UI disabling the composer to serialize session mutations.
• Do not use a workflow instance as the inner loop for every chat message, coding command, or personal-assistant action.
• Do not let light-workflow or a channel gateway directly spawn an external agent CLI.
• Do not treat a skill package, repository instruction, plugin, or generated skill as authorization to gain tools, credentials, network, or filesystem access.
• Do not place messaging-channel credentials, model-provider credentials, tenant API credentials, and unrestricted local-device access in one shared process.

Concepts

Agent Definition

Versioned metadata describing instructions, skills, model policy, tool policy, memory policy, data boundary, and default execution profile.

An agent definition is content. It does not own a process.

Agent Product Profile

A server-owned profile selecting the turn lifecycle, ingress surfaces, runtime placement, default tools, memory policy, sandbox requirements, and deployment boundary for an agent definition.

The initial values are enterprise, coding, and personal-assistant. A profile narrows the effective policy; it does not grant authority by itself.

Agent Runtime Adapter

A versioned adapter that runs one model/tool loop and emits normalized runtime events. Native light-agent reasoning, Pi RPC/SDK, Codex, Claude Code, Gemini CLI, and other external harnesses implement this boundary.

An agent runtime is not a model provider. A model provider performs inference; an agent runtime may own a session, tools, local state, approvals, and repeated model calls.

Agent Runtime Host

The small light-agent-worker executable launched inside a runner-managed sandbox. It verifies the leased runtime specification, materializes approved skills and context, starts exactly one runtime adapter, streams normalized events, and exits or checkpoints at the lease boundary.

It does not authenticate end users, own conversation history, choose policy, or accept arbitrary executable paths from a prompt.

Channel Gateway

The optional light-agent-channel executable that owns messaging-platform connections, webhook verification, user/channel pairing, delivery receipts, and channel credentials. It converts inbound messages, scheduled triggers, and connector events into authenticated idempotent turn requests.

It is an ingress and delivery adapter, not an agent engine and not a general execution environment.

Agent Service Instance

A long-lived light-agent process or replica serving compatible agent definitions and sessions. An instance has one deployment trust boundary, network zone, service identity, and set of provider/credential capabilities.

The current implementation has one model/provider and one optional agent definition per instance. Supporting multiple definitions in one pool requires request-time immutable definition resolution and a cache keyed by host and agent definition.

Agent Session

An authenticated conversation scope bound to:

• tenant and host;
• user or service principal;
• agent definition and version;
• memory policy and bank;
• data boundary;
• optional sandbox session;
• creation, idle, and maximum lifetime;
• optimistic version or active-turn fence.

A session ID is an opaque server-issued reference, not proof of access.

Agent Turn

One accepted user or service request and its resulting model/tool loop. A turn has a durable ID, idempotency key, policy snapshot, budgets, state, timestamps, and terminal result.

Agent Action Attempt

One effectful tool or local execution attempt within a turn. It has an idempotency key, attempt number, lease, fencing token, approval state, result, and reconciliation state.

Read-only remote gateway calls may use a lighter audit record, but side-effecting or sandboxed actions require a durable attempt.

Execution Subject

The origin-neutral identity carried by the controller/runner protocol:

subject.kind = workflow-task | agent-turn | agent-action
subject.id
subject.attempt
origin.service
origin.instance

Workflow correlation and agent-session correlation are optional typed extensions. They are not mandatory fields in the runner transport.

Sandbox Session

An optional backend environment reused across related turns or actions under one immutable policy, principal, agent definition, workspace base, and expiry. It is separate from the chat session. Most chat sessions need no sandbox.

Ownership

controller-rs and the runner are origin-neutral. They do not advance an agent turn or workflow task. The origin service reconciles the fenced result into its own state.

Execution Modes

Use explicit modes. Do not silently redirect one mode to another.

Native Workflow Agent

Keep bounded workflow reasoning in light-workflow. It receives workflow-safe context, calls an approved remote model, validates structured output, and returns control to explicit workflow tasks.

It receives no filesystem, local shell, dynamic tools, tenant workspace, or release credentials.

Agent Service

Use a long-lived light-agent service for interactive sessions:

• WebSocket or streaming chat;
• Hindsight memory;
• remote model providers;
• portal catalog caching;
• dynamic gateway tools/list and tools/call;
• independently scaled specialist agents.

The service container is an application isolation boundary, not a safe place to execute arbitrary code. It should have no workspace mount, host container socket, build tools, browser automation, or unrestricted local MCP server.

Runner Agent

Use runner-agent mode when a turn needs:

• checked-out repositories or mutable files;
• shell or language runtimes;
• browser automation;
• CLI-based model agents;
• local MCP servers;
• private tenant network access;
• code generation, repair, or tests;
• untrusted tool packages or scripts.

For these cases, either:

1. keep the model loop in light-agent and lease individual local actions; or
2. place the entire model/tool loop in the sandbox when a CLI agent or workspace-aware model must observe and mutate local state.

The second model is required for Codex-, Pi-, and Claude Code-style execution. Host it with light-agent-worker; do not start a second copy of the public light-agent service inside the sandbox. The shared service must not spawn an external agent CLI with its own environment.

Per-action leasing remains useful for a native service-side loop that needs one isolated command. A workspace-aware external runtime receives one bounded agent-turn lease, with optional policy-compatible session reuse, because its filesystem observations, command sequence, and model context form one local execution loop.

Fixed Action

Publishing, signing, deployment, final tags, branch push, and pull-request creation use fixed actions with structured inputs. They consume immutable artifacts or an accepted canonical patch and receive a fresh scoped credential.

They do not execute arbitrary commands from the agent or mutable workspace.

Recommended Architecture

Portal / CLI / API                 Messaging / schedule / connector event
         |                                      |
         |                         light-agent-channel
         |                                      |
         +------------- authenticated turn ----+
                                |
                                v
                          light-agent
                       session and policy
               +-------------+-------------+
               |             |             |
               v             v             v
        model provider  light-gateway  light-workflow
                          API / MCP       durable process
                                |
                                v
                          controller-rs
                                |
                                v
                     light-workflow-runner
                                |
                                v
                        ExecutionBackend
                                |
                                v
                   task/session sandbox
                                |
                                v
                     light-agent-worker
                     + runtime adapter

Fixed high-value effects remain separate typed services/actions.

The normal interactive path does not allocate a sandbox. A sandbox is allocated only when effective policy and the requested action require local execution.

Product Profiles

Enterprise Business Agent

Use the enterprise profile for API- and MCP-centered business processing. The model loop stays in the long-lived light-agent service. The effective catalog exposes only assigned and currently executable gateway tools. Durable or regulated multi-step processing is delegated to light-workflow.

This profile has no workspace mount, local shell, browser process, external agent CLI, or personal channel credential.

Coding Agent

Use the coding profile for repository inspection, code changes, builds, tests, local MCP, and developer tooling. The whole workspace-aware loop runs through light-agent-worker in a task-scoped sandbox by default. A bounded session-scoped workspace is an optimization that requires the same principal, agent definition, repository base, policy, runtime adapter, backend, and expiry.

The runtime adapter may be native or may wrap an external harness such as Pi, Codex, or Claude Code. The adapter is selected by immutable server policy and image/package identity, never by a prompt-supplied command. Provider access is brokered by a runner-owned service outside the untrusted payload boundary; raw provider keys and reusable proxy bearer tokens are not copied into the sandbox. The worker receives only a peer-bound local channel for the current attempt, model allowlist, data-boundary and policy digests, token/cost budget, rate, and expiry. The generated-code process runs under a different identity and process/mount namespace and cannot inspect, reconnect to, or inherit that channel.

The untrusted workspace can produce a patch and diagnostic artifacts. Trusted runner code computes the canonical diff, enforces protected paths, and exports immutable artifacts. Branch, pull-request, push, publish, signing, and deploy remain fixed actions over the accepted patch or commit.

Personal Assistant

Use the personal-assistant profile for long-lived user memory, messaging channels, proactive schedules, personal connectors, browser tasks, and optional local-device access.

light-agent-channel owns platform-specific connections and principal pairing. It does not hold model-provider or general tenant credentials. Typed remote connectors execute through light-gateway. Browser, filesystem, desktop, home-automation, or other user-local effects execute through a dedicated or user-owned edge runner with an explicit capability policy.

A logical personal assistant does not require a permanent VM. A dedicated service or runner is required when personal OAuth grants, private-network access, legal boundaries, or local-device capabilities cannot share a service pool safely.

Scheduled and connector-triggered turns enter the same durable per-session queue as user prompts, carry an origin and idempotency key, and obey quiet hours, rate, cost, approval, and notification policy. A proactive trigger cannot interrupt an active turn or silently act as the user.

Agent Runtime Protocol

Define a versioned agent-runtime-protocol shared by light-agent, light-agent-worker, runner adapters, and test fixtures. It is separate from the model-provider trait and from the controller/runner lease protocol.

The runtime specification includes:

• runtime adapter ID, version, immutable image/package digest, and capability digest;
• agent, session, turn, and execution correlation;
• bounded context and selected skill-package digests;
• workspace base, writable roots, protected paths, and change policy;
• model, tool, network, credential, approval, resource, artifact, and deadline policy;
• optional checkpoint/session identity and compatibility digest;
• a one-time event-stream authentication handle.

The runtime emits ordered, bounded events such as:

• runtime.started and runtime.ready;
• model.started, model.delta, model.completed, and usage;
• tool.requested, tool.started, tool.result, and tool.failed;
• approval.requested and approval.resolved;
• workspace.changed and artifact.proposed;
• checkpoint.created;
• turn.completed, turn.failed, turn.cancelled, or turn.unknown.

Each event carries the execution ID, turn/action identity, monotonically increasing sequence, event ID, policy digest, timestamp, and bounded payload or artifact reference. Duplicate events are idempotent. Missing sequences can be resumed from the worker journal. An event is evidence; only light-agent can accept it into agent-domain state.

The protocol supports start, cancel, inspect, checkpoint, resume, and bounded input/approval responses. It does not expose a generic remote shell endpoint.

Runtime Capabilities And Adapters

A runtime capability document declares whether the adapter supports workspace mutation, native tools, streaming, interruption, approval suspension, checkpoint/resume, project-local instructions, local MCP, and session reuse. Server-owned compatibility policy maps a tested adapter version to the capabilities it may claim.

For local execution it also carries an immutable runtime-tool manifest: stable internal tool reference, model-facing alias, input/output schema digests, effect class, required capability, and dispatch adapter for each shell, filesystem, browser, or local-MCP operation. At turn admission, server policy intersects that manifest with the execution profile and lease allowedTools; where the runtime supports live enumeration, the worker intersects it again with the current local tool set. A runtime self-report can narrow availability but cannot add authority absent from the server-owned compatibility record.

The first adapters should be:

1. a deterministic mock adapter for protocol, recovery, and fencing tests;
2. a native bounded adapter using shared Light-Agent core logic;
3. one SDK/RPC-based coding adapter, with Pi as the preferred first candidate;
4. subprocess adapters for Codex, Claude Code, Gemini CLI, or Kilo only after their non-interactive event and approval contracts are pinned and tested.

Do not scrape terminal presentation output when a structured SDK, RPC, or JSON event mode exists. Never enable a permission-bypass flag as a substitute for the platform sandbox and approval policy.

Agent And Workflow Interoperation

Agent and workflow orchestration are bidirectional but retain separate domain ownership.

An agent starts a workflow through a typed gateway/API tool when a skill needs durable branching, retries, assertions, human tasks, or long waits. The agent stores the workflow instance reference and may stream or poll its public status; it does not reproduce the workflow steps in its own model loop.

The existing workflow call.agent behavior remains the backward-compatible native-workflow mode: light-workflow performs a bounded model call and validates schema-bound JSON without an interactive session or local tools. A future explicit agent-service mode submits a typed agent job to light-agent. Light-agent may satisfy that job in its service or through runner-agent placement according to the selected definition and policy.

light-workflow never directly launches an external agent binary and never mutates agent session history. light-agent never advances workflow tasks. Handoffs carry a correlation ID, caller and tenant binding, input/output schema, deadline, idempotency key, budget, cancellation policy, and bounded delegation depth. Cyclic delegation and unbounded agent/workflow recursion are rejected.

Shared Runner Contract

The workflow runner protocol should be origin-neutral before its first stable version. Do not require processId and taskId in every wire message.

Every scheduling request and lease carries:

• execution ID;
• origin service and authenticated origin instance;
• subject kind, ID, and attempt;
• tenant and host derived from trusted identity;
• policy snapshot and digest;
• execution profile and compatibility digest;
• runner/backend selection;
• lease ID and fencing token;
• deadlines and cleanup policy;
• idempotency key;
• optional typed workflow or agent correlation.

Example standalone agent action:

{
  "executionId": "01970f5d-2222-7000-8000-000000000001",
  "origin": {
    "service": "light-agent",
    "instance": "account-agent-east"
  },
  "subject": {
    "kind": "agent-action",
    "id": "01970f5d-2222-7000-8000-000000000020",
    "attempt": 1
  },
  "agent": {
    "sessionId": "01970f5d-2222-7000-8000-000000000010",
    "turnId": "01970f5d-2222-7000-8000-000000000011",
    "agentDefId": "01970f5d-2222-7000-8000-000000000012"
  },
  "leaseId": "01970f5d-2222-7000-8000-000000000030",
  "fencingToken": 19,
  "policyDigest": "sha256:...",
  "executionProfile": "agent-microvm",
  "commandTemplateId": "agent-tool-cargo-test",
  "deadlineAt": "2026-07-10T20:30:00Z",
  "expiresAt": "2026-07-10T20:10:30Z"
}

The controller authenticates which services may submit each subject kind. light-agent cannot submit workflow-task work, and light-workflow cannot mutate an agent turn merely because both use the same runner.

Persistence Split

Use common execution tables for controller/runner state:

• runner_scheduling_request_t;
• execution_attempt_t;
• runner session/backend capability records;
• execution session, artifact, and runtime audit records where sharing is appropriate.

Use origin-specific tables for domain state:

• task_info_t and workflow approval/transition records for workflow tasks;
• agent_session_t, agent_turn_t, agent_action_attempt_t, and the ordered session event stream for agent work.

The common attempt stores subject identity, lease, fencing, backend, normalized result, and cleanup. The origin transaction conditionally accepts that result and advances only its own domain object.

This split is a design decision:

• every runner-backed agent action references one shared execution_attempt_t row;
• execution_attempt_t contains only controller/runner concerns such as origin, subject, attempt, reservation, lease, fencing, runner/backend, normalized result, and cleanup;
• agent_action_attempt_t contains agent-domain concerns such as tool identity, model iteration, argument digest, effect class, approval, budgets, recovery policy, and acceptance into the turn;
• gateway-only actions can have an agent_action_attempt_t without an execution_attempt_t and instead record the gateway request/idempotency identity;
• controller-rs never writes agent turn, history, or approval state.

Result-Ready Wakeup

The common execution row remains the durable source of truth. In the same PostgreSQL transaction that conditionally stores a newly terminal execution_attempt_t, controller-rs emits a versioned execution_result_ready_v1 notification containing only the attempt ID, authenticated origin, subject kind, and correlation ID. It contains no result bytes, tenant content, or authorization.

light-agent listens for the notification, loads the authoritative row, verifies origin/subject/fencing bindings, and conditionally accepts the result in its own domain transaction. It must also scan indexed unaccepted terminal attempts at startup and periodically. The listener uses a dedicated connection and, on startup or reconnect, establishes LISTEN before its catch-up scan so a commit in that handoff window is either scanned or queued. LISTEN/NOTIFY is only a low-latency wakeup: delivery can be missed, duplicated, or reordered. A future typed controller callback may provide another wakeup, but it cannot replace the authoritative query or make controller-rs write agent tables.

Session And Turn Model

Session Admission

The front door authenticates the caller before accepting or resuming a session. The server derives:

• tenant and host;
• user or service principal;
• allowed agent definition;
• model/provider and data-boundary policy;
• memory scope;
• maximum session and idle lifetime.

On new session, light-agent creates a server-issued session ID and stores the ownership binding. On resume, all binding fields must match. A valid UUID alone never grants access.

The existing agent_memory_bank_t.user_id and agent_def_id fields should be populated. agent_session_history_t should either gain explicit ownership columns or reference a new agent_session_t that contains them.

Proposed Agent Tables

agent_session_t:

• tenant, host, session, user/service principal, and agent definition;
• definition, model, tool, memory, and execution policy digests;
• memory bank ID;
• optional execution session ID;
• state, optimistic version, active turn, created/last/idle/max expiry;
• cancellation, revocation, and retention state;
• durable execution-session cleanup request, state, and evidence correlation.

agent_turn_t:

• session and monotonically increasing turn sequence;
• origin kind such as user, channel, workflow, scheduler, or connector plus an immutable origin reference and bounded delegation depth;
• client message ID and idempotency key;
• immutable prompt/input reference and policy snapshot;
• model/provider reference and data boundary;
• QUEUED, RECEIVED, RUNNING_MODEL, WAITING_ACTION, RUNNING_ACTION, WAITING_RECONCILIATION, WAITING_APPROVAL, COMPLETED, FAILED, CANCELLED, or UNKNOWN state;
• enqueue sequence, queue deadline, activation time, and optional cancellation reason;
• token, cost, model-call, action-call, and wall-clock budgets;
• accepted result, error class, timestamps, and audit correlation.

agent_action_attempt_t:

• turn and action/tool identity;
• stable internal tool reference, model-facing alias, tool source, schema digest, effect classification, and selected execution placement;
• optional runtime adapter ID/version, runtime action ID, and capability digest;
• input schema and canonical argument digest;
• approval requirement and binding;
• numbered logical attempt and optional superseded/resumed-from attempt;
• nullable execution_attempt_id referencing the common execution_attempt_t row where runner-backed;
• gateway request/idempotency identity where remotely executed;
• known-success, known-failure, cancelled, or unknown outcome;
• recovery classification and remaining correction budget;
• bounded result/artifact references and reconciliation state.

agent_approval_t:

• approval ID, session, turn, canonical action intent and argument digest;
• tool/operation, destination, data-boundary and policy digests, artifact or patch bindings where applicable, actor authority, state, and expiry;
• source attempt when a running runtime discovered the approval boundary;
• optional execution-session approval-hold ID and bounded hold expiry;
• consuming post-approval agent-action and common execution-attempt IDs;
• a unique active approval per exact subject and single-use consumption.

agent_session_event_t, or an equivalent append-only portal event stream:

• session sequence, event ID, turn ID, optional action-attempt ID, and event type;
• USER_MESSAGE, MODEL_RESPONSE, ACTION_DISPATCHED, ACTION_RESULT, APPROVAL_REQUESTED, APPROVAL_DECIDED, TURN_TERMINAL, or SYSTEM event;
• immutable content reference/digest, source class, policy digest, timestamp, and actor;
• unique action-result event per accepted agent action attempt.

agent_session_history_t is a rebuildable conversation-context projection over the ordered event stream. It is not the authoritative ledger proving that an effectful action occurred.

Personal-assistant deployments also require channel-domain records, either in the GenAI schema or a dedicated channel service:

• agent_channel_binding_t binds tenant, principal, agent, platform, channel, remote identity, pairing/verification state, and revocation without storing raw channel secrets;
• agent_channel_delivery_t deduplicates inbound platform events and outbound responses, records delivery state, and references the resulting turn;
• scheduled trigger records bind agent, session/origin, schedule, quiet-hours, notification, idempotency, and maximum-delay policy.

Channel records do not replace agent turns. They prove ingress and delivery; light-agent remains authoritative for reasoning and action state.

Turn State Machine

QUEUED -> RECEIVED -> RUNNING_MODEL
RUNNING_MODEL -- no tool --> COMPLETED
RUNNING_MODEL -- tool --> WAITING_ACTION
WAITING_ACTION -- no approval --> RUNNING_ACTION
WAITING_ACTION -- approval required --> WAITING_APPROVAL
WAITING_APPROVAL -- approved; allocate new attempts --> RUNNING_ACTION
WAITING_APPROVAL -- rejected --> RUNNING_MODEL or FAILED by policy
RUNNING_ACTION -- known success/recoverable failure --> RUNNING_MODEL
RUNNING_ACTION -- uncertain outcome --> WAITING_RECONCILIATION
WAITING_RECONCILIATION -- known recoverable result --> RUNNING_MODEL
WAITING_RECONCILIATION -- terminal/unsafe --> FAILED
WAITING_RECONCILIATION -- cannot determine --> UNKNOWN

Any active state -- accepted cancellation --> CANCELLED
Policy/security violation or exhausted hard budget --> FAILED

A model call may be safely retried only when it has no external effect or the provider request is idempotent. An action with an unknown outcome is inspected or reconciled before another attempt.

An action failure does not automatically fail the turn. A known, policy-allowed recoverable failure such as a compiler error, failed test, linter result, or non-zero diagnostic command is persisted as untrusted tool output and returned to RUNNING_MODEL when correction budgets remain. The model may explain the failure or propose a new action.

The turn becomes FAILED or CANCELLED when:

• policy, authentication, schema, or security enforcement rejects the action;
• approval is rejected and policy treats rejection as terminal;
• a hard turn deadline or token/cost/action budget is exhausted;
• the client or control plane cancels the turn;
• the action is classified non-recoverable;
• an unknown side effect cannot be reconciled and policy requires termination.

A correction is a new action identity. Reusing an attempt is allowed only when the backend/external operation has a proven idempotency or inspection contract. maxCorrectionActions and per-tool retry limits prevent an agent from looping on the same failure. A turn may still finish COMPLETED with a user-facing explanation that one or more actions failed; completion means the response was durably delivered, not that every action succeeded.

WAITING_APPROVAL is durable agent state. It always ends the current action lease, model-broker capability, and action credential. A task-scoped sandbox is cleaned after its required evidence is exported.

A reusable agent-session workspace has a separate lifecycle. Under an explicit bounded non-secret retention policy, its execution_session_t may enter IDLE_APPROVAL_HOLD with no executable action, tool credential, or model channel. The hold expires at the earliest of approval expiry, session idle/max expiry, cost/retention policy, broker/credential boundary, and backend-native TTL. Pause or a verified checkpoint is preferred over consuming active compute. Absence of an action lease is not by itself a session-cleanup signal.

The origin may renew the session-retention record only from authenticated session activity and never beyond the fixed maximum; it must not fake action lease heartbeats while a person decides. If the backend cannot safely retain or checkpoint the non-secret workspace, the runner exports an approved immutable patch/checkpoint and cleans the sandbox. Preserving important uncommitted work must not depend only on a live sandbox.

The origin transition into WAITING_APPROVAL atomically persists exactly one session disposition: cleanup, or a policy-valid bounded hold. If common session state later lives in another database, use an idempotent transactional outbox. There must be no interval where a session reaper can interpret the ended action lease as abandonment before the hold is durable.

Approval never reactivates an execution attempt. If policy knows approval is required before dispatch, light-agent records the bound action intent and approval but creates no common execution attempt. If a running runtime discovers an approval boundary, it returns a known approval_required terminal result; controller-rs ends the action lease and the runner revokes grants and cleans or checkpoints according to policy. After approval, light-agent consumes the approval into a new numbered agent action attempt and a new common execution attempt with a fresh lease and monotonic fencing token. The previous attempt and its backend handle, grants, and fencing token remain immutable and cannot resume execution. A retained session workspace is reused only after principal/base/policy/runtime/expiry compatibility and cleanup state are revalidated; otherwise the new action starts in a fresh sandbox and restores only a verified policy-permitted checkpoint or patch.

Concurrency

Only one mutating turn should own a session version at a time by default. Multiple WebSockets or replicas must not overwrite the same history.

The default user experience is a bounded durable server-side FIFO per session, not immediate rejection:

1. Authenticate and authorize the prompt, deduplicate its client message ID, assign the next session enqueue sequence, and persist a QUEUED turn.
2. Return the turn ID, state, queue position, and estimated/retry timing to the client. The UI may disable or label the composer, but correctness does not depend on client-side serialization.
3. When no active mutating turn exists, conditionally acquire the session version, revalidate revocation and current policy, snapshot the effective turn policy, and activate the oldest non-expired queued turn.
4. Allow a user to cancel a queued turn. Interrupting an active turn requires an explicit cancel-and-enqueue operation; a second prompt never implicitly cancels in-flight work.

A queued prompt is durable but is not added to the active turn's model context or mutable history projection. It becomes eligible for conversation context only after it wins FIFO activation, so a later prompt cannot change the meaning of an in-flight action.

Queue depth and wait time are bounded per tenant, principal, agent, and session. A full queue returns a retryable admission response such as 429 with retryAfter. A 409 is reserved for a stale explicit session version or an operation that semantically requires exclusive ownership; it is not the normal second-prompt response.

Use a conditional active-turn or aggregate-version update across replicas. A read-only secondary view can stream state, but it cannot bypass the FIFO or append another active user turn without winning session activation.

Agent Definition And Policy Snapshot

Resolve and snapshot at turn admission:

• agent definition/version;
• system instructions and selected skills;
• model/provider and regional/data-boundary policy;
• memory scope and retention;
• permitted catalog and tool policy;
• action execution profile;
• network and credential profile;
• turn/model/tool/token/cost limits;
• approval rules;
• protected workspace policy;
• artifact and audit policy.

Do not execute a long turn from mutable current rows. A catalog refresh may narrow executable tools immediately for emergency revocation, but it cannot widen the accepted snapshot without a new authorization decision.

For future multi-agent pooling, cache by host, agent definition ID, version, and policy digest. Never use one global catalog entry across definitions.

Centralized Skills Across Profiles

The centralized registry is the source of assigned skill identity, version, instructions, taxonomy, tool/workflow links, runtime compatibility, and governance metadata. It is not the process that executes a skill.

At turn admission, light-agent resolves an immutable effective skill set and records every selected version and digest. A profile-specific materializer then produces only the inputs required by the selected runtime:

Skill content is layered in decreasing authority:

1. server and execution policy;
2. signed platform/tenant skill versions assigned to the agent;
3. reviewed user-specific skill configuration;
4. repository or workspace-local instructions;
5. user prompts, retrieved content, and tool output.

Lower layers cannot override higher-layer policy. Repository instructions and downloaded or generated skills are untrusted content even when useful to the model. A self-generated skill is stored as an inactive proposal and requires validation, scanning, review, immutable packaging, and an explicit assignment before another turn can load it.

Do not execute source code copied directly from a mutable database row. Script or binary content belongs in an immutable artifact with digest, provenance, scanner results, entrypoint metadata, and a required sandbox profile. The trusted runner—not light-agent-worker or generated code—downloads the selected immutable packages before sandbox creation, verifies their digest/signature/size and archive safety, and stages them as read-only mounts with nodev, nosuid, and noexec unless a reviewed profile requires an executable entrypoint. The worker revalidates the mounted manifest before use. Neither the worker nor payload receives artifact-store credentials or package download egress.

See Centralized Skills for the catalog and package model and Skill Workflow Orchestration for workflow-backed skills.

Tool Authorization And Execution

Treat model tool calls as untrusted requests.

For each model iteration:

1. Resolve the effective catalog for the authenticated agent and turn.
2. Apply lifecycle, sensitivity, effect, approval, tenant, cost, and network policy.
3. Partition candidates by the server-owned execution placement recorded in the catalog/policy snapshot: gateway, runner, workflow, or fixed service.
4. For gateway candidates, intersect with live gateway tools/list and toolsListAccessControl under the downscoped turn identity.
5. For runner candidates, intersect with the execution profile, lease allowedTools, server-approved runtime-tool manifest, and live worker or sandbox-local MCP enumeration where supported. Do not require these tools to exist in gateway tools/list.
6. Expose workflow and fixed-service candidates only through their typed contracts; they are never converted to free-form local or gateway tools.
7. Form a collision-free union. Bind each model-facing name to its internal tool reference, placement, schema digest, and policy snapshot. A duplicate alias across placements fails closed unless server policy assigned distinct deterministic aliases.
8. Send only that accepted set to the model.
9. On returned tool call, recheck that the exact bound tool remains in the accepted set.
10. Parse arguments strictly. Malformed JSON fails; it does not become an empty object.
11. Validate arguments against the accepted input schema and routing metadata.
12. Re-evaluate effect, approval, quotas, cancellation, policy revocation, and destination immediately before dispatch.
13. Compute the effective delegation as the intersection of caller authority, agent-definition policy, turn/action policy, tool policy, and current revocation state.
14. For gateway execution, exchange the caller identity for a short-lived downscoped gateway token bound to the turn or exact action.
15. Create a durable attempt and idempotency key when the action can have an effect.
16. Dispatch only through the placement bound at disclosure; model output cannot change the route.
17. Bound, redact, classify, and persist the result before giving it back to the model.

The gateway remains the final API authorization and routing boundary. Agent catalog policy is an additional restriction and must not be bypassed merely because the gateway would accept a broader caller token.

The runner lease and runtime-tool manifest are the corresponding final local availability boundaries. A local tool name is not authority by itself, and the model broker, credential broker, runner control socket, and backend lifecycle API are never included in the tool union.

Gateway Delegation

Production agent calls do not forward the caller's full bearer token directly to light-gateway. light-agent uses a trusted token-exchange or credential-broker service to mint a signed, short-lived delegated token whose authority can only narrow the caller.

The effective authority is:

caller grants
  intersect agent-definition policy
  intersect turn/action policy
  intersect tool and data-boundary policy
  intersect current revocation and quota state

A tools/list token is scoped to the turn and accepted tool set. A tools/call token should be scoped to one action and include or cryptographically bind:

• gateway audience;
• tenant, host, caller subject, and light-agent actor identity;
• agent definition, session, turn, and action IDs;
• exact tool or narrowly bounded tool set;
• allowed scopes, destination/service, sensitivity ceiling, and data boundary;
• policy snapshot/digest and argument or request digest where practical;
• issued-at, short expiry, unique token ID, and replay/idempotency binding.

light-gateway validates the signature, audience, expiry, actor/delegation chain, policy binding, tool, destination, and current authorization. It intersects the delegated token with its own access-control and tool metadata; possession of a more powerful original user token cannot widen an agent turn.

If token exchange is unavailable or a requested binding cannot be enforced, the production call fails closed. Direct forwarding may exist only as an explicit local-development compatibility mode and must never be the default for effectful or sensitive tools.

Placement

Tool Results

Tool output is untrusted content even when the tool is authorized.

Result handling distinguishes action outcome from turn outcome:

• known success is persisted and normally returns to RUNNING_MODEL;

• known recoverable failure is persisted with bounded diagnostics and returns to RUNNING_MODEL when correction policy and budgets allow;

• known terminal failure ends or cancels the turn according to policy;

• unknown outcome enters WAITING_RECONCILIATION and cannot be represented to the model as if the action definitely failed;

• a new corrective tool call receives a new action ID and idempotency decision.

• enforce byte, item, nesting, and token limits;

• preserve truncation markers and full artifact references when policy permits;

• separate tool data from system instructions;

• do not follow instructions found in tool output unless the agent policy explicitly treats that source as instructions;

• redact secrets before persistence and again before model context;

• store the action ID, tool/version, argument digest, authorization decision, destination, result digest, and model iteration.

Model Provider Boundary

Remote API Providers

Remote API providers can run from the long-lived service when:

• the service data boundary permits the prompt;
• provider credentials are service-owned or tenant-approved;
• no local executable is spawned;
• the turn has token, cost, timeout, and concurrency limits;
• response and tool calls are treated as untrusted.

Do not send tenant-local repositories, private logs, or private-network data to a SaaS provider unless the effective policy authorizes that transfer.

CLI And External Agent Runtimes

Codex, Pi, Claude Code, Gemini CLI, Kilo CLI, and similar harnesses are agent runtimes, not ordinary model API adapters. Existing CLI implementations under model-provider are compatibility code and should migrate behind the agent-runtime adapter boundary.

They run under light-agent-worker with runner-agent placement and require:

• fresh task or bounded session sandbox;
• minimal allowlisted environment;
• no inherited portal token, database URL, unrelated provider keys, or controller credential;
• explicit workspace, network, tool, and resource policy;
• local deadline and process-tree cancellation;
• bounded stdout/stderr;
• immutable binary/image identity and capability digest;
• structured SDK, RPC, or JSON event integration where available;
• normalized approval, cancellation, usage, patch, and terminal events;
• cleanup journal and backend-native expiry.

Model access for these runtimes terminates at a runner-owned broker. Prefer a preconnected descriptor, peer-credential-checked Unix-domain socket, vsock, or an equivalent backend-local transport. A socket pathname alone is not an authorization boundary: the broker authenticates the attempt and peer, and the runner prevents descriptor inheritance, cross-process /proc inspection, and ptrace. The broker independently enforces the approved model, data boundary, policy digest, token/cost budget, rate, cancellation, and expiry. An adapter that can operate only with an extractable provider key is ineligible for an untrusted coding profile.

Permission-bypass flags are prohibited. If an adapter needs an unattended mode, the platform sandbox and approval policy—not a CLI bypass option—provide the effective boundary. The shared service never invokes these binaries directly, and light-workflow never invokes them at all.

Sandbox Scope And Backend

Backend and session scope are separate decisions.

The deployment advertises available backends. Server-owned policy chooses an eligible backend or defers/denies execution. It never silently downgrades.

Session Reuse

An agent sandbox session can be reused only when all of these match:

• tenant, host, principal, agent definition, and policy digest;
• workspace base revision and change policy;
• backend, template/image, and compatibility digest;
• network, credential, model-provider, and tool policy;
• maximum lifetime, idle timeout, and cleanup state.

Credentials remain task-scoped even when the workspace is reused. A session that received a high-value credential is destroyed after the action unless an explicit policy proves safe cleanup.

The effective physical-session expiry is the earliest of the agent session's idle/max expiry, execution-session policy, broker/grant expiry, and backend-native TTL. An approval hold can preserve a compatible non-secret workspace only until that same effective expiry; it does not refresh or extend the fixed maximum and it carries no action credential or model channel.

When light-agent closes, revokes, or expires a logical session, the same durable transaction creates an idempotent common execution-session cleanup request. controller-rs immediately fences and cancels active attempts and dispatches cleanup; the runner destroys the backend session and records evidence. Cleanup is retried across restarts and the backend TTL remains only a final fail-safe, not the expected reclamation path. An EXPIRED agent session whose physical sandbox is merely waiting for its independent TTL is a reconciliation defect.

Memory Boundary

Conversation history and distilled memory are domain state, not sandbox state. The sandbox may receive a bounded prompt/context projection, but it does not own the memory database.

Required controls:

• bind memory bank and session history to authenticated host, user/principal, and agent definition;
• authorize every resume, recall, retain, and history update;
• apply optimistic versioning to conversation projections;
• keep accepted action attempts and append-only session events authoritative over the mutable history projection;
• distinguish user-authored, tool-derived, model-derived, and operator instruction sources;
• prevent tool output or retrieved memory from becoming privileged system instructions;
• enforce retention, deletion, legal hold, export, and audit policy;
• redact or tokenize sensitive values before embedding or cross-boundary model transfer.

History Conflict After An Effect

An optimistic history conflict must never cause an effectful action to be forgotten or repeated.

When an action reaches a known terminal result, light-agent performs an idempotent origin-acceptance transaction that:

1. conditionally accepts the current agent_action_attempt_t;
2. records or references the common execution_attempt_t/gateway result;
3. appends one ACTION_RESULT event with the action/result digest;
4. advances the agent turn to RUNNING_MODEL, WAITING_RECONCILIATION, or a terminal state.

Updating agent_session_history_t is a projection step after that transaction. If its expected version is stale, the projector rereads the ordered session events, deterministically rebuilds or merges the conversation context, and retries the projection. It does not redispatch the tool and does not overwrite another accepted user message.

Until the projection catches up, clients can reconstruct the authoritative timeline from turn/action/session events. The UI may show a temporary history-sync state, but the accepted action and audit record remain visible. Projection lag or conflict is an operational error, not an action retry signal.

Portal-command memory writes are the production default because they preserve event, authorization, and audit boundaries. Direct PostgreSQL mode remains an explicitly enabled local/development compatibility profile. Longer term, memory recall should also use a scoped service API so the general agent pod does not require a database password.

Authentication And Session Security

• Authenticate before WebSocket upgrade or before accepting the first message.
• Derive tenant, host, user, and allowed agent definition from trusted claims and server-side mappings.
• Issue an opaque session handle or signed resume token with audience, expiry, principal, and agent binding.
• Never use caller-provided tenant, host, user, agent, or memory-bank IDs as authority.
• Rotate the session handle after privilege or policy changes.
• Revoke active sessions on user, agent, provider, or policy revocation.
• Serialize concurrent mutating prompts through the bounded durable per-session FIFO; only the active turn acquires the session version.
• Remove committed/default bearer tokens and rotate any token that may have been usable.

Credentials

The long-lived service should contain only credentials required for its service profile. It should not hold credentials for possible future tools.

• Prefer workload identity and brokered short-lived grants.
• Keep end-user authorization separate from the service's portal identity.
• Exchange user authorization for a signed, short-lived, audience-restricted, turn/action-scoped light-gateway delegation token. Do not forward the unrestricted user token in production.
• Never forward SaaS model credentials into tenant runner sandboxes.
• Do not replace provider keys with a reusable proxy bearer token visible to the worker or generated payload. Use the protected, peer-bound runner broker channel and enforce budget and expiry at the broker.
• Never let a CLI child inherit the service environment.
• Project action credentials after policy approval and revoke them at terminal state or lease loss.
• Publish/sign/deploy credentials exist only in fixed actions.
• Do not place raw secrets in prompts, session history, memory, tool arguments, logs, artifacts, environment snapshots, or execution journals.

Failure And Recovery

Service Restart

The session and turn are reconstructed from durable state. An incomplete turn is not automatically replayed:

• RUNNING_MODEL with no action may be safely failed or retried by policy;
• RUNNING_ACTION queries the gateway idempotency record or runner attempt;
• an accepted ACTION_RESULT with stale history resumes projection/rebuild and never redispatches the action;
• UNKNOWN action outcome requires inspection or operator decision;
• COMPLETED result can be streamed again idempotently;
• WAITING_APPROVAL has no action compute or credentials; an explicitly retained session workspace remains paused/checkpointed under its independent bounded hold and expiry.

Client Disconnect

Policy decides whether the turn:

• cancels immediately;
• continues to a durable result for later resume; or
• continues only through the current non-effectful model call.

The decision is recorded at admission. A disconnect does not silently broaden the deadline.

Runner Or Backend Disconnect

Use the same lease, fencing, journal, inspection, watchdog, native TTL, and cleanup contract as workflow execution. light-agent accepts a result only for the current action attempt and fencing token. Result-ready notifications only wake reconciliation; startup and periodic scans of authoritative terminal attempts recover any notification lost while light-agent was disconnected.

Duplicate Client Message

The client supplies a message ID scoped to the session. A duplicate returns the existing turn or result. It does not create a second effectful action.

Limits And Admission

Every service profile and turn policy defines:

• maximum concurrent sessions and turns;
• maximum queued prompts per session/principal/agent and maximum queue wait;
• per-principal and per-agent quotas;
• maximum input/history/retrieval/tool-output tokens;
• maximum model calls and tool calls per turn;
• maximum correction actions and per-tool recovery attempts;
• model and total wall-clock deadlines;
• cost/token budget;
• maximum pending approval time;
• sandbox queue and runtime deadline;
• session idle and maximum lifetime;
• artifact and log limits.

Saturation is not a model or tool failure. Queue or reject before starting more work than the service, provider, gateway, or runner can support.

Audit And Observability

Record:

• authenticated session admission and resume;
• agent definition, model, catalog, memory, and execution-policy digests;
• turn state and idempotency decision;
• model provider/model, latency, token usage, and cost without hidden reasoning content;
• selected, hidden, and attempted tools;
• argument and result digests, effect class, approval, destination, and placement;
• runner/backend/lease/fencing identity for sandboxed work;
• cancellation, unknown outcome, retry, and reconciliation;
• memory recall/retain source classes;
• sandbox cleanup and artifact evidence.

Metrics include active sessions, turn latency/state, model/tool counts and budgets, per-session queue depth/wait, session activation conflicts, unauthorized resume attempts, rejected model tool names, malformed/schema-invalid arguments, downscoped-token issuance/rejection, recoverable action failures, unknown actions, history projection lag/conflict, approval wait, runner queue time, runtime-event lag/gaps, adapter failures, skill-package verification failures, channel duplicate/replay rejection, delivery latency/failure, scheduled-turn deferral, result-wakeup/catch-up latency, oldest unaccepted terminal attempt, model-broker denial/budget exhaustion, session-to-sandbox expiry skew, approval-held session count/age/cost, checkpoint/restore failures, and cleanup request latency/backlog.

Deployment Profiles

Shared Tenant Agent Service

One horizontally scalable deployment serves compatible enterprise and personal-assistant reasoning sessions for one tenant or strong tenant partition. It uses remote model APIs and gateway-only tools. It has no local workspace or external agent runtime.

Dedicated Agent Service

Use a separate long-lived deployment when an agent requires a distinct:

• tenant or legal boundary;
• model provider credential or regional endpoint;
• private network zone;
• service identity;
• latency/scaling profile;
• memory retention policy.

This is a deployment profile, not a requirement for every logical agent.

Coding Agent Worker Pool

light-agent submits agent-turn or agent-action execution subjects to controller-rs. The tenant runner selects an approved backend, creates a task- or session-scoped environment, and starts light-agent-worker with the pinned runtime adapter. Worker pools are grouped by real backend, network, workspace, model-proxy, and data-boundary compatibility, not by logical agent name.

Personal Assistant Channel Gateway

Deploy light-agent-channel separately from the reasoning service. Pool only channels and users whose webhook exposure, credential store, retention, regional, and delivery policies are compatible. Channel delivery can continue while a reasoning replica restarts because accepted messages and responses are durable.

Personal Edge Runner

Use a dedicated user- or tenant-owned runner when a personal assistant needs a local browser profile, desktop, filesystem, home network, or device access. The edge runner advertises explicit capabilities and receives short-lived leases; it is not a permanently authorized remote shell.

The implemented edge binding is principal-specific and names the exact runner, backend, execution profile, action allowlist, required capabilities, compatibility digest, and expiry. Light-Agent converts an allowed local effect to a fixed light-edge-action structured command and Controller refuses to reserve it on any other runner or backend. Revoked/expired bindings and action or capability mismatches fail before scheduling.

Release Agent

Use a dedicated runner pool and strong sandbox/VM profile. The agent can inspect and patch a copy-on-write workspace, but trusted fixed actions apply the accepted patch, create a branch/PR, publish, sign, or deploy. Approval is bound to immutable subjects and waits without an active lease.

Implementation Plan

The detailed repository and pull-request sequence is maintained in implementation/light-agent/2026-07-10-LightAgentRuntimeAndProfilesImplementationPlan.md.

Phase 0: Harden The Current Service

• Remove and rotate embedded default bearer tokens.
• Authenticate session admission and bind host/user/agent ownership.
• Populate memory-bank ownership and reject unauthorized resume.
• Revalidate model tool names against the accepted per-turn set.
• Strictly parse and schema-validate arguments.
• Exchange caller authorization for downscoped gateway delegation tokens.
• Bound/redact tool output and retrieved memory.
• Add overall turn timeout, cancellation, action/model-call limits, and a bounded per-session FIFO with one active mutating turn.
• Disable CLI providers in shared-service profiles.

Phase 1: Durable Sessions And Turns

• Add agent_session_t, agent_turn_t, agent_action_attempt_t, and the append-only agent session event stream/projection.
• Add message idempotency, durable FIFO sequencing, and optimistic session activation/versioning.
• Snapshot definition, catalog, model, memory, and execution policy.
• Persist model/action state and normalized bounded results; accept an action and append its ACTION_RESULT event before updating conversation history.
• Rebuild the history projection from ordered events after a version conflict.
• Add approval wait without compute.
• Distinguish action-lease release from a bounded execution-session IDLE_APPROVAL_HOLD; task sandboxes clean immediately while an eligible non-secret session workspace may pause/checkpoint until its independent effective expiry.
• Bind approvals to immutable action intents and consume approval into a new action/common execution attempt with fresh fencing; never reopen an earlier attempt.
• On session close, revocation, or expiry, atomically create an idempotent common execution-session cleanup request.
• Move production memory writes to portal-command mode.

Phase 2: Origin-Neutral Runner Contract

• Add execution subject and origin types to execution-runner-protocol.
• Make controller scheduling and common execution attempts origin-neutral.
• Reference shared execution_attempt_t from runner-backed agent_action_attempt_t rows while keeping agent-domain fields out of the common table.
• Authenticate allowed subject kinds per origin service.
• Keep workflow and agent domain transitions separate.
• Emit identifiers-only execution_result_ready_v1 PostgreSQL wakeups in the common terminal-result transaction. Add light-agent LISTEN handling plus startup and periodic indexed catch-up; notification delivery is never the source of truth.
• Add durable execution-session cleanup dispatch and evidence reconciliation.

Phase 3: Agent Runtime Protocol And Worker

• Add agent-runtime-protocol, ordered runtime events, and capability documents.
• Add stable tool-source/placement identities and an immutable local runtime-tool manifest. Gateway candidates intersect gateway tools/list; local candidates intersect server compatibility, execution policy, lease allowedTools, and live worker/local-MCP enumeration.
• Add a deterministic mock adapter and the light-agent-worker executable.
• Route command, filesystem, browser, local MCP, and external agent runtimes through ExecutionBackend.
• Add a runner-owned model-broker transport contract with peer/attempt binding, no payload-visible reusable bearer, separate worker/payload identities, and broker-enforced model and budget policy.
• Reconcile worker events into agent-domain state without giving the worker direct database ownership.

Phase 4: Skill Packages And Materialization

• Add runtime compatibility and immutable skill-package records.
• Verify digest, provenance, scan result, entrypoint, and sandbox policy before read-only materialization.
• Make the trusted runner download, safely extract, verify, and stage selected packages before sandbox creation. The worker only revalidates mounted bytes and has no artifact-store credential or download path.
• Implement enterprise, workflow, coding, and personal-assistant materializers.
• Treat generated and repository-local skills as untrusted proposals/content.

Phase 5: Coding Agent Profile

• Enable Cube Sandbox for untrusted task-scoped coding turns.
• Add the first structured SDK/RPC coding adapter, preferably Pi.
• Add optional bounded workspace-session reuse.
• Add bounded approval-hold, pause/checkpoint, restore, expiry, cost, and cleanup semantics without renewing an action lease.
• Add protected runner-brokered model access, canonical patch export, protected paths, artifacts, watchdog, origin-driven session cleanup, native TTL backstop, and cleanup evidence.
• Migrate direct CLI model-provider implementations behind runtime adapters and disable their shared-service execution path.

Phase 6: Multi-Agent Service Pooling

• Resolve an authorized agent definition per session/turn.
• Cache immutable definitions/catalogs by host, ID, version, and digest.
• Route provider/data-boundary profiles without sharing incompatible secrets.
• Scale replicas with durable session admission rather than in-memory affinity.

Phase 7: Personal Assistant Profile

• Add light-agent-channel, channel/principal binding, webhook verification, delivery idempotency, and proactive trigger policy.
• Add typed connector tools and optional dedicated personal edge runners.
• Add quiet hours, notification policy, scheduled-turn admission, and connector credential brokering.

Phase 8: Workflow Bridge And Fixed High-Value Actions

• Keep existing call.agent behavior as native-workflow by default.

• Add an explicit agent-service job mode with schema, deadline, idempotency, cancellation, correlation, and delegation-depth controls.

• Expose workflow start/status/cancel as typed agent tools.

• Add accepted-patch, branch/PR, publish, sign, and deploy contracts.

• Require immutable input, approval, provenance, and fresh action-scoped credentials.

• Consume every approval into a new numbered domain action and common execution attempt with a fresh lease and fencing token.

• Reuse the trusted fresh-checkout and protected-path design.

• Rebuild releases from reviewed immutable commits.

Acceptance And Failure-Injection Tests

• A valid session cannot be resumed by another principal, agent, host, or tenant.
• Concurrent prompts from one or more replicas receive durable FIFO sequence; one turn becomes active and the rest remain queued in order.
• Queue-full admission is bounded and retryable; it does not drop or silently execute a prompt.
• Duplicate client delivery resolves to the existing turn and cannot create a second action.
• A model-returned hidden or unadvertised tool is rejected before gateway dispatch.
• A gateway-only tool absent from gateway tools/list is hidden without removing an independently authorized runner tool; a runner tool absent from the lease/runtime/local manifest is hidden even if the gateway has the same name.
• Model-facing alias collisions across placements fail closed, and a returned tool call cannot switch its snapshotted gateway/runner/workflow/fixed-service dispatch route.
• Malformed or schema-invalid arguments never become an empty object.
• Gateway authorization remains effective even when the catalog is stale.
• Tool and memory output cannot exceed context limits or become system instructions.
• A known recoverable command failure returns to the model within correction budgets; it does not automatically fail the turn.
• An unknown action is reconciled and cannot be repeated or described as a definite failure.
• A successful effect followed by a history-version conflict remains present in agent_action_attempt_t and the session event stream; projection recovery never redispatches it.
• Gateway calls use a signed token narrowed to the caller, agent, turn/action, tool, data boundary, policy digest, audience, and expiry; the original broad user token is not forwarded.
• Service restart during model-only work follows the configured retry policy.
• Restart after effectful dispatch reconciles instead of blindly repeating.
• Terminal result committed while light-agent is offline is found by indexed catch-up and accepted once; dropped, duplicate, and reordered notifications do not change correctness.
• WAITING_APPROVAL holds no active action lease, model-broker channel, or action credential. A task sandbox is cleaned; an eligible non-secret session workspace is retained only through a separately persisted bounded hold or verified checkpoint.
• Missing an action lease does not clean an approval-held session, while hold expiry, logical session close/revocation, or policy mismatch does. Approval cannot extend the session maximum lifetime.
• Approval creates a fresh post-approval action/common execution attempt and fencing token; the pre-approval attempt, handle, and grant remain unusable.
• CLI provider processes receive only an allowlisted environment inside a sandbox.
• Generated code cannot read a provider/proxy bearer, inspect or inherit the worker's model-broker channel, impersonate another attempt, choose an unauthorized model, or exceed broker-enforced token/cost limits.
• A CLI/provider timeout kills the process tree and triggers cleanup.
• A shared light-agent process cannot directly start an external agent runtime.
• Worker runtime events are ordered, resumable, bounded, and cannot mutate an agent turn without origin-side acceptance.
• A runtime adapter cannot claim an unapproved capability or select a weaker sandbox than the turn policy requires.
• A coding turn receives only the selected immutable skill packages and workspace-local instructions cannot grant additional authority.
• Package download, digest/signature mismatch, unsafe archive entries, or staging failure occurs before sandbox start; sandbox code has no artifact-store credential or package-download egress.
• A generated skill remains inactive until it is scanned, reviewed, packaged, and assigned.
• A sandboxed turn survives controller and runner reconnect without accepting a stale fencing token.
• A session-scoped workspace cannot be reused across principal, agent, base, policy, backend, or expiry changes.
• Closing, revoking, or expiring an agent session durably fences active work and reclaims its physical sandbox without waiting for backend-native TTL; cleanup survives controller and runner restart.
• Toolbx and ordinary containers cannot satisfy a microVM requirement.
• A spoofed channel user, replayed webhook, duplicate delivery, or scheduled trigger cannot create an unauthorized or duplicate turn.
• A personal channel gateway has no model-provider key, unrestricted shell, or tenant-wide connector credential.
• A native-workflow agent call remains backward compatible and a service-mode call cannot cause an unbounded agent/workflow delegation cycle.
• Publish/sign/deploy cannot be invoked as a free-form agent tool.
• Secret scanning finds no credential in prompts, history, memory, logs, artifacts, journal, or child environment.

Open Decisions

• Whether the first production deployment remains one agent definition per service or introduces request-time multi-agent pooling immediately.
• Which session-scoped backends support safe checkpoint/restore.
• Which structured coding adapter is enabled first after the mock and native adapters, and which versioned SDK/RPC contract is pinned.
• Which runner-owned model broker and protected local transport are supported first on each backend: preconnected descriptor, peer-checked Unix-domain socket, vsock, or backend-native equivalent.
• Which object store, signer, scanner, and review service own immutable skill packages.
• Which channel bindings and personal connector grants remain in GenAI domain tables versus a dedicated channel/identity service.
• Which exact workflow syntax selects agent-service while preserving the existing native-workflow default.
• Which model providers support useful request idempotency.
• Whether client disconnect defaults to cancel or durable continuation.
• Which memory read service replaces direct PostgreSQL recall.
• Which agent actions require workflow-owned approval versus standalone agent-owned approval.

Recommendation

Keep light-agent as the interactive session, durable turn, policy, memory, and model orchestration service for all profiles. Do not assign infrastructure per agent definition or fork separate enterprise, coding, and personal-assistant engines. Deploy service pools by real trust and data boundaries.

Use the shared controller/runner/ExecutionBackend path whenever an agent needs local execution or stronger isolation. Host workspace-aware loops in the small sandbox-side light-agent-worker; host messaging connections in the separate light-agent-channel; keep external agent products behind runtime adapters. Make the runner protocol origin-neutral so workflows and standalone agent turns share capacity, fencing, backend lifecycle, watchdog, credentials, artifacts, and cleanup without sharing domain ownership.

Database Design

The Light-Fabric utilizes a robust PostgreSQL schema to manage the entire lifecycle of agentic workflows, skills, agent execution, channels, and the biomimetic Hindsight memory system. The schema is organized into five logical layers:

1. Workflow Engine

These tables manage the definition and execution of long-running agentic workflows.

wf_definition_t

Stores the Agentic Workflow DSL (YAML) that defines the high-level orchestration logic.

process_info_t & task_info_t

Manage the runtime state of workflow instances (processes) and individual steps (tasks). They include input_data, context_data, and error_info to provide a resilient "scratchpad" for intermediate variables.

worklist_t & worklist_asst_t

Manage task assignments and visibility for human-in-the-loop interactions.

2. Agentic Core (The "Brain & Skills")

These tables define the identity, expertise, and capabilities of individual agents.

agent_definition_t

Defines the agent's persona, product profile, model policy, default execution profile, data boundary, and runtime limits. Enterprise, coding, and personal-assistant definitions share this table; a definition does not own a process or sandbox.

skill_t

Stores the "Expertise" of an agent in Markdown format. Skills are hierarchical and versioned.

tool_t & tool_param_t

The "Hands" of the agent. Defines governed REST/MCP capabilities and typed execution metadata. A tool row or script field is not authority to execute code; untrusted executable assets require an immutable reviewed package and an approved runner sandbox. The target model adds or derives a stable internal tool reference and records a server-owned gateway, runner, workflow, or fixed-service placement, model alias, schema digest, effect class, and dispatch-policy binding. Existing rows with proven current gateway-config linkage migrate as gateway. Ambiguous legacy script rows remain undisclosed until reviewed.

agent_skill_t & skill_tool_t

Maps agents to skills and skills to tools, implementing the Progressive Disclosure pattern where agents only see the tools required for their current skill context.

skill_package_t (proposed)

References immutable signed/scanned skill assets for coding, personal, or external runtime adapters. Package bytes live in object storage. The row binds digest, provenance, entrypoint, compatible profiles, required capabilities, review, revocation, and retention.

3. Hindsight Memory System

A biomimetic memory architecture that transitions from flat logs to structured "atoms of thought."

agent_memory_bank_t

Profiles for memory banks, defining the "Personality and Disposition" (e.g., skepticism, empathy) of the memory layer.

agent_memory_unit_t

The individual "Atoms" of memory. Each unit contains content and a vector embedding (384-dim) for semantic retrieval.

agent_memory_entity_t & agent_memory_link_t

A Knowledge Graph layer that resolves entities and causal/semantic relationships between memory units.

4. Agent Session And Execution

agent_session_t, agent_turn_t, agent_action_attempt_t, and agent_approval_t (proposed)

Store authenticated session ownership, durable FIFO turns, effectful action attempts, policy snapshots, budgets, bound single-use approvals, reconciliation, and terminal results. Runner-backed actions reference the shared execution_attempt_t, but agent-domain fields remain owned by light-agent. Post-approval dispatch creates a new numbered agent action and a new common execution attempt; it never reopens the pre-approval attempt.

Shared runner execution records (proposed)

runner_scheduling_request_t, execution_attempt_t, execution_session_t, execution_session_cleanup_request_t, and execution_input_t store origin-neutral capacity, fencing, normalized results, bounded session cleanup, immutable staged inputs, and session state/version/fencing. Reused sessions can enter a bounded IDLE_APPROVAL_HOLD with hold ID/expiry, cost policy, and checkpoint/patch evidence while the action lease and credentials are gone. Zero active attempts does not imply cleanup for a valid held session; the hold cannot extend idle/max expiry or override close/revocation. Origin services retain their own workflow or agent state. A terminal-attempt transaction emits an identifiers-only wakeup; origins query the authoritative row and use startup/periodic catch-up rather than treating notification delivery as durable state.

agent_session_event_t (proposed)

An append-only authoritative ledger for accepted user messages, model results, actions, approvals, and terminal turn events. It is the source used to rebuild conversation context after a projection conflict.

agent_session_history_t

The materialized transcript used for active conversation context, linked to the session's Hindsight memory bank. It is not the authoritative proof of an effectful tool action. Agent action attempts and append-only session events survive history-version conflicts and can rebuild this projection. See Light-Agent Execution.

5. Personal Assistant Channels And Triggers

agent_channel_binding_t and agent_channel_delivery_t (proposed)

Bind a verified messaging identity to a principal and agent, and deduplicate inbound events/outbound responses. They store credential references rather than channel secrets and do not replace agent turns.

agent_trigger_t (proposed)

Stores scheduled or connector-triggered turn policy, including timezone, quiet hours, rate/cost limits, notification destination, idempotency, and maximum delay.

See Light-Agent Execution and the dedicated Light-Agent runtime implementation plan for constraints and phased rollout.

DDL Specification

-- Workflow Definitions: Stores the Agentic Workflow JSON
CREATE TABLE wf_definition_t (
    host_id             UUID NOT NULL,
    wf_def_id           UUID NOT NULL,
    namespace           VARCHAR(126) NOT NULL,
    name                VARCHAR(126) NOT NULL,
    version             VARCHAR(20) NOT NULL,
    definition          TEXT NOT NULL, -- The Agentic Workflow DSL in YAML
    aggregate_version    BIGINT DEFAULT 1 NOT NULL,
    active              BOOLEAN DEFAULT TRUE,
    update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user         VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY(host_id, wf_def_id),
    UNIQUE(host_id, namespace, name, version)
);

CREATE TABLE worklist_t (
  host_id              UUID NOT NULL,
  assignee_id          VARCHAR(126) NOT NULL,
  category_id          VARCHAR(126) DEFAULT '(all)' NOT NULL,
  status_code          VARCHAR(10) DEFAULT 'Active' NOT NULL,
  app_id               VARCHAR(512) DEFAULT 'global' NOT NULL,
  aggregate_version    BIGINT DEFAULT 1 NOT NULL,
  active               BOOLEAN NOT NULL DEFAULT TRUE,
  update_user          VARCHAR (255) DEFAULT SESSION_USER NOT NULL,
  update_ts            TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP NOT NULL,
  PRIMARY KEY(host_id, assignee_id, category_id)
);

CREATE TABLE worklist_column_t (
  host_id               UUID NOT NULL,
  assignee_id           VARCHAR(126) NOT NULL,
  category_id           VARCHAR(126) DEFAULT '(all)' NOT NULL,
  sequence_id           INTEGER NOT NULL,
  column_id             VARCHAR(126) NOT NULL,
  aggregate_version     BIGINT DEFAULT 1 NOT NULL,
  active                BOOLEAN DEFAULT TRUE,
  update_ts             TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
  update_user           VARCHAR(126) DEFAULT SESSION_USER,
  PRIMARY KEY(host_id, assignee_id, category_id, sequence_id),
  FOREIGN KEY(host_id, assignee_id, category_id) REFERENCES worklist_t(host_id, assignee_id, category_id) ON DELETE CASCADE
);

CREATE TABLE process_info_t (
  host_id                    UUID NOT NULL,
  process_id                 UUID NOT NULL, -- generated uuid
  wf_def_id                  UUID NOT NULL, -- workflow definition id
  wf_instance_id             VARCHAR(126)       NOT NULL, -- workflow intance id
  app_id                     VARCHAR(512)       NOT NULL, -- application id
  process_type               VARCHAR(126)      NOT NULL,
  status_code                CHAR(1)            NOT NULL, -- process status code 'A', 'C'
  started_ts                 TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP NOT NULL,
  ex_trigger_ts              TIMESTAMP WITH TIME ZONE          NOT NULL,
  custom_status_code         VARCHAR(126),
  completed_ts               TIMESTAMP WITH TIME ZONE,
  result_code                VARCHAR(126),
  source_id                  VARCHAR(126),
  branch_code                VARCHAR(126),
  rr_code                    VARCHAR(126),
  party_id                   VARCHAR(126),
  party_name                 VARCHAR(126),
  counter_party_id           VARCHAR(126),
  counter_party_name         VARCHAR(126),
  txn_id                     VARCHAR(126),
  txn_name                   VARCHAR(126),
  product_id                 VARCHAR(126),
  product_name               VARCHAR(126),
  product_type               VARCHAR(126),
  group_name                 VARCHAR(126),
  subgroup_name              VARCHAR(126),
  event_start_ts             TIMESTAMP WITH TIME ZONE,
  event_end_ts               TIMESTAMP WITH TIME ZONE,
  event_other_ts             TIMESTAMP WITH TIME ZONE,
  event_other                VARCHAR(126),
  risk                       NUMERIC,
  risk_scale                 INTEGER,
  price                      NUMERIC,
  price_scale                INTEGER, -- Scale (number of digits to the right of the decimal) of the risk column. NULL implies zero
  product_qy                 NUMERIC,
  currency_code              CHAR(3),
  ex_ref_id                  VARCHAR(126),
  ex_ref_code                VARCHAR(126),
  product_qy_scale           INTEGER,
  parent_process_id          VARCHAR(22),
  deadline_ts                TIMESTAMP WITH TIME ZONE,
  parent_group_id            NUMERIC,
  process_subtype_code       VARCHAR(126),
  owning_group_name          VARCHAR(126), -- Name of the group that owns the process
  input_data                 JSONB,        -- The initial data that triggered the workflow
  context_data               JSONB,        -- The runtime "scratchpad" for intermediate variables
  error_info                 TEXT,         -- Detailed error or stack trace if the process fails
  aggregate_version   BIGINT DEFAULT 1 NOT NULL,
  active              BOOLEAN DEFAULT TRUE,
  update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
  update_user         VARCHAR(126) DEFAULT SESSION_USER,
  PRIMARY KEY(host_id, process_id),
  FOREIGN KEY(host_id, wf_def_id) REFERENCES wf_definition_t(host_id, wf_def_id) ON DELETE CASCADE
);

CREATE TABLE task_info_t
(
    host_id             UUID NOT NULL,
    task_id             UUID NOT NULL,
    task_type           VARCHAR(126) NOT NULL,
    process_id          UUID NOT NULL,
    wf_instance_id      VARCHAR(126) NOT NULL,
    wf_task_id          VARCHAR(126) NOT NULL,
    status_code         CHAR(1)       NOT NULL, -- U, A, C
    started_ts          TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP NOT NULL,
    locked              CHAR(1)       NOT NULL,
    priority            INTEGER        NOT NULL,
    completed_ts        TIMESTAMP WITH TIME ZONE      NULL,
    completed_user      VARCHAR(126)     NULL,
    result_code         VARCHAR(126)     NULL,
    locking_user        VARCHAR(126)     NULL,
    locking_role        VARCHAR(126)     NULL,
    deadline_ts         TIMESTAMP WITH TIME ZONE      NULL,
    lock_group          VARCHAR(126)     NULL,
    task_input          JSONB,           -- Specific data passed to the task
    task_output         JSONB,           -- Result returned by the task action
    aggregate_version   BIGINT DEFAULT 1 NOT NULL,
    active              BOOLEAN DEFAULT TRUE,
    update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user         VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY(host_id, task_id),
    FOREIGN KEY (host_id, process_id) REFERENCES process_info_t(host_id, process_id) ON DELETE CASCADE
);

CREATE TABLE task_asst_t
(
    host_id             UUID NOT NULL,
    task_asst_id         UUID NOT NULL,
    task_id              UUID NOT NULL,
    assigned_ts          TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP NOT NULL,
    assignee_id          VARCHAR(126) NOT NULL,
    reason_code          VARCHAR(126) NOT NULL,
    unassigned_ts        TIMESTAMP WITH TIME ZONE      NULL,
    unassigned_reason    VARCHAR(126)     NULL,
    category_code        VARCHAR(126)     NULL,
    aggregate_version    BIGINT DEFAULT 1 NOT NULL,
    active               BOOLEAN DEFAULT TRUE,
    update_ts            TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user          VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY(host_id, task_asst_id),
    FOREIGN KEY(host_id, task_id) REFERENCES task_info_t(host_id, task_id) ON DELETE CASCADE
);

CREATE TABLE audit_log_t
(
    host_id             UUID NOT NULL,
    audit_log_id        UUID NOT NULL,
    source_type_id      VARCHAR(126)      NULL,
    correlation_id      VARCHAR(126)      NULL,
    user_id             VARCHAR(126)     NULL,
    event_ts            TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP NOT NULL,
    success             CHAR(1)           NULL,
    message0            VARCHAR(126)     NULL,
    message1            VARCHAR(126)     NULL,
    message2            VARCHAR(126)     NULL,
    message3            VARCHAR(126)     NULL,
    message             VARCHAR(500)     NULL,
    user_comment        VARCHAR(500)     NULL,
    PRIMARY KEY(host_id, audit_log_id)
);

CREATE INDEX audit_log_idx1 ON audit_log_t (source_type_id, correlation_id, event_ts, user_id);

-- Agent Definitions: Stores the "Brain" configuration
CREATE TABLE agent_definition_t (
    host_id             UUID NOT NULL,
    agent_def_id        UUID NOT NULL,
    agent_name          VARCHAR(126) NOT NULL,
    model_provider      VARCHAR(64) NOT NULL,  -- 'openai', 'anthropic', etc.
    model_name          VARCHAR(126) NOT NULL, -- 'gpt-4o', 'claude-3-5-sonnet'
    api_key_ref         VARCHAR(126),          -- Reference to Secret Manager key
    temperature         NUMERIC(3,2) DEFAULT 0.7,
    max_tokens          INTEGER,               -- max number of tokens can be used
    aggregate_version    BIGINT DEFAULT 1 NOT NULL,
    active              BOOLEAN DEFAULT TRUE,
    update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user         VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY(host_id, agent_def_id),
    UNIQUE(host_id, agent_name)
);


-- Skills: Stores Instructions and Domain Knowledge (The "Expertise")
-- Note: Use entity_tag_t and entity_category_t with entity_type = 'skill'
-- for flat tagging and hierarchical folder structure of skills.
CREATE TABLE skill_t (
    host_id             UUID NOT NULL,
    skill_id            UUID NOT NULL,
    parent_skill_id     UUID,                  -- Self-reference for Hierarchy
    name                VARCHAR(126) NOT NULL,
    description         VARCHAR(500),          -- High-level description for the initial LLM prompt
    content_markdown    TEXT NOT NULL,         -- The actual instructions/prompts

    description_embedding VECTOR(384),          -- For semantic lookup/discovery
    version             VARCHAR(20) DEFAULT '1.0.0',
    aggregate_version    BIGINT DEFAULT 1 NOT NULL,
    active              BOOLEAN DEFAULT true,
    update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user         VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY(host_id, skill_id),
    FOREIGN KEY(host_id, parent_skill_id) REFERENCES skill_t(host_id, skill_id)
);

CREATE INDEX idx_skill_active ON skill_t(active);
CREATE INDEX idx_skill_name ON skill_t(name);

-- Tools: Stores Executable Functions (The "Hands")
CREATE TABLE tool_t (
    host_id             UUID NOT NULL,
    tool_id             UUID NOT NULL,
    name                VARCHAR(126) NOT NULL,
    description         TEXT NOT NULL,         -- Instructions for LLM on when/how to use this tool

    -- Implementation specifics
    implementation_type VARCHAR(50),           -- 'java', 'mcp_server', 'rest', 'python', 'javascript'
    implementation_class VARCHAR(500),         -- FQCN if 'java'
    mcp_server_name      VARCHAR(126),         -- MCP server name if 'mcp_server'
    api_endpoint        VARCHAR(1024),         -- URL if 'rest'
    api_method          VARCHAR(10),           -- HTTP Method if 'rest'
    endpoint_id         UUID,                  -- Reference to fine-grained auth endpoint
    script_content      TEXT,                  -- Source code if 'python'/'javascript'
    response_schema     JSONB,                 -- Strict output schema for tool results

    description_embedding VECTOR(384),          -- For semantic lookup/discovery
    version             VARCHAR(20) DEFAULT '1.0.0',
    aggregate_version   BIGINT DEFAULT 1 NOT NULL,
    active              BOOLEAN DEFAULT true,
    update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user         VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY(host_id, tool_id),
    FOREIGN KEY(host_id, endpoint_id) REFERENCES api_endpoint_t(host_id, endpoint_id) ON DELETE CASCADE
);

CREATE INDEX idx_tool_host_endpoint ON tool_t(host_id, endpoint_id);
CREATE INDEX idx_tool_active ON tool_t(active);
CREATE INDEX idx_tool_name ON tool_t(name);

-- Tool Parameters: Defines the arguments for each tool
CREATE TABLE tool_param_t (
    host_id             UUID NOT NULL,
    param_id            UUID NOT NULL,
    tool_id             UUID NOT NULL,
    name                VARCHAR(255) NOT NULL,
    param_type          VARCHAR(50) NOT NULL,      -- 'string', 'number', 'boolean', 'object', 'array'
    required            BOOLEAN DEFAULT true,
    default_value       JSONB,
    description         TEXT,                      -- Helps LLM understand what value to extract
    validation_schema   JSONB,                     -- JSON Schema for complex validation
    order_index         INTEGER DEFAULT 0,
    aggregate_version   BIGINT DEFAULT 1 NOT NULL,
    active              BOOLEAN DEFAULT true,
    update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user         VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY(host_id, param_id),
    FOREIGN KEY(host_id, tool_id) REFERENCES tool_t(host_id, tool_id) ON DELETE CASCADE
);

-- Skill Dependencies: Manages hierarchies where one skill requires another
CREATE TABLE skill_dependency_t (
    host_id             UUID NOT NULL,
    skill_id            UUID NOT NULL,
    depends_on_skill_id UUID NOT NULL,
    required            BOOLEAN DEFAULT true,
    aggregate_version   BIGINT DEFAULT 1 NOT NULL,
    active              BOOLEAN DEFAULT true,
    update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user         VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY (host_id, skill_id, depends_on_skill_id),
    FOREIGN KEY(host_id, skill_id) REFERENCES skill_t(host_id, skill_id),
    FOREIGN KEY(host_id, depends_on_skill_id) REFERENCES skill_t(host_id, skill_id)
);

-- Agent-Skill Mapping: Links Agents to their Skills
CREATE TABLE agent_skill_t (
    host_id             UUID NOT NULL,
    agent_def_id        UUID NOT NULL,
    skill_id            UUID NOT NULL,

    config              JSONB DEFAULT '{}',
    priority            INTEGER DEFAULT 0,
    sequence_id         INTEGER DEFAULT 0,     -- Order in which skills are concatenated

    aggregate_version    BIGINT DEFAULT 1 NOT NULL,
    active              BOOLEAN DEFAULT true,
    update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user         VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY(host_id, agent_def_id, skill_id),
    FOREIGN KEY(host_id, agent_def_id) REFERENCES agent_definition_t(host_id, agent_def_id) ON DELETE CASCADE,
    FOREIGN KEY(host_id, skill_id) REFERENCES skill_t(host_id, skill_id) ON DELETE CASCADE
);
CREATE INDEX idx_agent_skill_agent ON agent_skill_t(agent_def_id);

-- Skill-Tool Mapping: Implements Progressive Disclosure
CREATE TABLE skill_tool_t (
    host_id             UUID NOT NULL,
    skill_id            UUID NOT NULL,
    tool_id             UUID NOT NULL,

    config              JSONB DEFAULT '{}',
    access_level        VARCHAR(20) DEFAULT 'read', -- e.g., 'read', 'write', 'execute'

    aggregate_version   BIGINT DEFAULT 1 NOT NULL,
    active              BOOLEAN DEFAULT true,
    update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user         VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY(host_id, skill_id, tool_id),
    FOREIGN KEY(host_id, skill_id) REFERENCES skill_t(host_id, skill_id) ON DELETE CASCADE,
    FOREIGN KEY(host_id, tool_id) REFERENCES tool_t(host_id, tool_id) ON DELETE CASCADE
);
CREATE INDEX idx_skill_tool_skill ON skill_tool_t(skill_id);

-- -- Hindsight Advanced Memory System
-- Transitioned from flat logs to biomimetic memory banks (World, Experiences, Mental Models)

-- Memory bank profiles (Personality & Disposition)
CREATE TABLE agent_memory_bank_t (
    host_id             UUID NOT NULL,
    bank_id             UUID NOT NULL,
    agent_def_id        UUID,                  -- NULL if bank is shared across agents
    user_id             UUID,                  -- NULL if bank is global for the host/agent
    bank_name           VARCHAR(126) NOT NULL,
    disposition         JSONB NOT NULL DEFAULT '{"skepticism": 3, "literalism": 3, "empathy": 3}'::jsonb,
    background          TEXT,
    aggregate_version   BIGINT DEFAULT 1 NOT NULL,
    active              BOOLEAN DEFAULT true,
    update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user         VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY(host_id, bank_id),
    FOREIGN KEY(host_id) REFERENCES host_t(host_id) ON DELETE CASCADE,
    FOREIGN KEY(host_id, agent_def_id) REFERENCES agent_definition_t(host_id, agent_def_id) ON DELETE CASCADE,
    FOREIGN KEY(user_id) REFERENCES user_t(user_id) ON DELETE CASCADE
);

-- Source documents for memory units
CREATE TABLE agent_memory_doc_t (
    host_id             UUID NOT NULL,
    doc_id              UUID NOT NULL,
    bank_id             UUID NOT NULL,
    original_text       TEXT,
    content_hash        TEXT,
    aggregate_version   BIGINT DEFAULT 1 NOT NULL,
    active              BOOLEAN DEFAULT true,
    update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user         VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY (host_id, bank_id, doc_id),
    FOREIGN KEY (host_id, bank_id) REFERENCES agent_memory_bank_t(host_id, bank_id) ON DELETE CASCADE
);

-- Individual sentence-level memories (The "Atoms" of thought)
CREATE TABLE agent_memory_unit_t (
    host_id             UUID NOT NULL,
    unit_id             UUID NOT NULL,
    bank_id             UUID NOT NULL,
    doc_id              UUID,
    content             TEXT NOT NULL,
    embedding           vector(384),
    context             TEXT,
    event_date          TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(),
    occurred_start      TIMESTAMP WITH TIME ZONE,
    occurred_end        TIMESTAMP WITH TIME ZONE,
    mentioned_at        TIMESTAMP WITH TIME ZONE,
    fact_type           VARCHAR(32) NOT NULL DEFAULT 'world' CHECK (fact_type IN ('world', 'experience', 'opinion', 'observation', 'mental_model')),
    metadata            JSONB DEFAULT '{}'::jsonb,
    proof_count         INT DEFAULT 1,
    source_memory_ids   UUID[] DEFAULT ARRAY[]::UUID[],
    aggregate_version   BIGINT DEFAULT 1 NOT NULL,
    active              BOOLEAN DEFAULT true,
    update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user         VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY(host_id, bank_id, unit_id),
    FOREIGN KEY(host_id, bank_id) REFERENCES agent_memory_bank_t(host_id, bank_id) ON DELETE CASCADE,
    FOREIGN KEY(host_id, bank_id, doc_id) REFERENCES agent_memory_doc_t(host_id, bank_id, doc_id) ON DELETE CASCADE
);

CREATE INDEX idx_mem_unit_bank ON agent_memory_unit_t(bank_id);
CREATE INDEX idx_mem_unit_embedding ON agent_memory_unit_t USING hnsw (embedding vector_cosine_ops);

-- Resolved entities (Knowledge Graph Nodes)
CREATE TABLE agent_memory_entity_t (
    host_id             UUID NOT NULL,
    entity_id           UUID NOT NULL,
    bank_id             UUID NOT NULL,
    user_id             UUID,                  -- Link to user_t if this entity is a platform user
    canonical_name      TEXT NOT NULL,
    mention_count       INT DEFAULT 1,
    metadata            JSONB DEFAULT '{}'::jsonb,
    aggregate_version   BIGINT DEFAULT 1 NOT NULL,
    active              BOOLEAN DEFAULT true,
    update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user         VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY (host_id, bank_id, entity_id),
    FOREIGN KEY (host_id, bank_id) REFERENCES agent_memory_bank_t(host_id, bank_id) ON DELETE CASCADE,
    FOREIGN KEY (user_id) REFERENCES user_t(user_id) ON DELETE CASCADE
);

-- Association between memory units and entities
CREATE TABLE agent_memory_unit_entity_t (
    host_id             UUID NOT NULL,
    bank_id             UUID NOT NULL,
    unit_id             UUID NOT NULL,
    entity_id           UUID NOT NULL,
    PRIMARY KEY (host_id, bank_id, unit_id, entity_id),
    FOREIGN KEY (host_id, bank_id, unit_id) REFERENCES agent_memory_unit_t(host_id, bank_id, unit_id) ON DELETE CASCADE,
    FOREIGN KEY (host_id, bank_id, entity_id) REFERENCES agent_memory_entity_t(host_id, bank_id, entity_id) ON DELETE CASCADE
);

-- Cache of entity co-occurrences (Concept Relationship Graph)
CREATE TABLE agent_memory_entity_cooccur_t (
    host_id             UUID NOT NULL,
    bank_id             UUID NOT NULL,
    entity_id_1         UUID NOT NULL,
    entity_id_2         UUID NOT NULL,
    cooccur_count       INT DEFAULT 1,
    last_cooccurred     TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    aggregate_version   BIGINT DEFAULT 1 NOT NULL,
    active              BOOLEAN DEFAULT true,
    update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user         VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY (host_id, bank_id, entity_id_1, entity_id_2),
    CONSTRAINT entity_cooccur_order_check CHECK (entity_id_1 < entity_id_2),
    FOREIGN KEY (host_id, bank_id, entity_id_1) REFERENCES agent_memory_entity_t(host_id, bank_id, entity_id) ON DELETE CASCADE,
    FOREIGN KEY (host_id, bank_id, entity_id_2) REFERENCES agent_memory_entity_t(host_id, bank_id, entity_id) ON DELETE CASCADE
);

CREATE INDEX idx_mem_cooccur_e1 ON agent_memory_entity_cooccur_t(host_id, entity_id_1);
CREATE INDEX idx_mem_cooccur_e2 ON agent_memory_entity_cooccur_t(host_id, entity_id_2);

-- Links between memory units (Semantic & Causal relationships)
CREATE TABLE agent_memory_link_t (
    host_id             UUID NOT NULL,
    bank_id             UUID NOT NULL,
    from_unit_id        UUID NOT NULL,
    to_unit_id          UUID NOT NULL,
    link_type           VARCHAR(32) NOT NULL,
    weight              FLOAT NOT NULL DEFAULT 1.0,
    aggregate_version   BIGINT DEFAULT 1 NOT NULL,
    active              BOOLEAN DEFAULT true,
    update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user         VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY (host_id, bank_id, from_unit_id, to_unit_id, link_type),
    CONSTRAINT memory_links_type_check CHECK (link_type IN ('temporal', 'semantic', 'entity', 'causes', 'caused_by', 'enables', 'prevents')),
    FOREIGN KEY (host_id, bank_id, from_unit_id) REFERENCES agent_memory_unit_t(host_id, bank_id, unit_id) ON DELETE CASCADE,
    FOREIGN KEY (host_id, bank_id, to_unit_id) REFERENCES agent_memory_unit_t(host_id, bank_id, unit_id) ON DELETE CASCADE
);

-- Directives (Hard rules that override probabilistic learning)
CREATE TABLE agent_memory_directive_t (
    host_id             UUID NOT NULL,
    directive_id        UUID NOT NULL,
    bank_id             UUID NOT NULL,
    name                VARCHAR(256) NOT NULL,
    content             TEXT NOT NULL,
    priority            INT NOT NULL DEFAULT 0,
    aggregate_version   BIGINT DEFAULT 1 NOT NULL,
    active              BOOLEAN DEFAULT true,
    update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user         VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY(host_id, bank_id, directive_id),
    FOREIGN KEY(host_id, bank_id) REFERENCES agent_memory_bank_t(host_id, bank_id) ON DELETE CASCADE
);

-- Reflections (Synthesized knowledge and high-level observations)
CREATE TABLE agent_memory_reflection_t (
    host_id             UUID NOT NULL,
    reflection_id       UUID NOT NULL,
    bank_id             UUID NOT NULL,
    content             TEXT NOT NULL,
    embedding           vector(384),
    aggregate_version   BIGINT DEFAULT 1 NOT NULL,
    active              BOOLEAN DEFAULT true,
    update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user         VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY(host_id, bank_id, reflection_id),
    FOREIGN KEY(host_id, bank_id) REFERENCES agent_memory_bank_t(host_id, bank_id) ON DELETE CASCADE
);

CREATE INDEX idx_mem_reflection_embedding ON agent_memory_reflection_t USING hnsw (embedding vector_cosine_ops);

-- Raw Session History (The source of Truth for active conversations)
CREATE TABLE agent_session_history_t (
    host_id             UUID NOT NULL,
    session_id          UUID NOT NULL,
    bank_id             UUID NOT NULL,         -- Links the session to a Hindsight bank
    messages            JSONB NOT NULL DEFAULT '[]'::jsonb,
    metadata            JSONB DEFAULT '{}'::jsonb,
    aggregate_version   BIGINT DEFAULT 1 NOT NULL,
    active              BOOLEAN DEFAULT true,
    update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user         VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY(host_id, bank_id, session_id),
    FOREIGN KEY(host_id, bank_id) REFERENCES agent_memory_bank_t(host_id, bank_id) ON DELETE CASCADE
);

CREATE INDEX idx_session_bank ON agent_session_history_t(host_id, bank_id);

Light-Deployer Design

light-deployer is the cluster-local Kubernetes deployment executor in Light Fabric.

This document focuses only on the deployer service that lives in apps/light-deployer. The broader Light Portal deployment workflow, approval flow, deployment history model, controller routing, and portal UI are covered outside this repository.

Purpose

light-deployer receives a deployment command, fetches Kubernetes templates, renders them with deployment values, validates the resulting resources, applies or deletes resources in the target Kubernetes cluster, and returns safe status details.

It is intentionally narrow. It does not decide whether a user is allowed to deploy an instance, does not own portal deployment history, and does not create tenant business workflows. Those decisions belong to Light Portal, Light Controller, and the workflow engine.

Service Boundary

light-deployer owns:

• local deployment policy enforcement
• template repository fetch
• YAML template rendering
• manifest parsing and resource summary generation
• Kubernetes dry-run, apply, delete, status, and pruning
• safe event and error reporting
• direct local/MicroK8s deployment endpoints

light-deployer does not own:

• tenant authorization
• instance metadata
• deployment approval
• deployment history persistence
• config snapshot creation
• long-running human workflow decisions

The deployer should reject commands outside its local policy even if an upstream service sends them.

Runtime Model

The service follows the same runtime pattern as light-agent.

main.rs builds the domain service and starts it through:

#![allow(unused)]
fn main() {
LightRuntimeBuilder::new(AxumTransport::new(app))
}

The HTTP listener is owned by light-runtime and light-axum, not by service-specific socket code. Bind address, HTTP/HTTPS ports, service identity, and registry settings live in runtime config files.

Default config files:

• config/server.yml
• config/deployer.yml
• config/portal-registry.yml

Local cargo run resolves config from apps/light-deployer/config when run from the workspace root. The container image runs from /app and uses /app/config.

Public Endpoints

Phase 1 exposes a direct HTTP surface for local and MicroK8s testing:

GET  /health
GET  /ready
POST /mcp
GET  /mcp/tools
GET  /mcp/tools/list
GET  /mcp/tools/{tool}
POST /deployments
POST /mcp/tools/{tool}
GET  /events?request_id=...

POST /mcp is the MCP JSON-RPC 2.0 endpoint. It supports tools/list, tools/call, and a minimal initialize response. This is the endpoint that MCP clients, Light Portal, and AI agents should use.

/deployments accepts the canonical deployment request directly. /mcp/tools/{tool} maps tool names onto the same internal service functions as a REST-style local debugging convenience. The convenience tool-list endpoints return metadata with name, description, inputSchema, endpoint, and method, but they are not the MCP protocol endpoint.

Supported tool names:

• deployment.render
• deployment.dryRun
• deployment.diff
• deployment.apply
• deployment.delete
• deployment.status
• deployment.rollback

The direct HTTP mode is useful for development and managed environments. The same internal command handling should later be reused by controller-mediated WebSocket/MCP routing.

Request Model

A deployment request is explicit and auditable.

{
  "requestId": "01964b05-0000-7000-8000-000000000001",
  "hostId": "01964b05-552a-7c4b-9184-6857e7f3dc5f",
  "instanceId": "petstore-dev",
  "environment": "dev",
  "clusterId": "microk8s-local",
  "namespace": "petstore-dev",
  "action": "deploy",
  "values": {
    "name": "petstore",
    "image": {
      "repository": "networknt/openapi-petstore",
      "tag": "latest"
    }
  },
  "template": {
    "repoUrl": "https://github.com/networknt/openapi-petstore.git",
    "ref": "master",
    "path": "k8s"
  },
  "options": {
    "dryRun": false,
    "waitForRollout": true,
    "timeoutSeconds": 300,
    "pruneOverride": false
  }
}

The current implementation supports inline values. The request model also contains fields for future values references and immutable snapshot metadata so it can align with the full portal deployment workflow.

When invoking a specific /mcp/tools/{tool} endpoint, callers do not need to send action. The deployer derives the action from the tool name. The generic /deployments endpoint still expects an explicit action in the request body.

For the MCP endpoint, callers use JSON-RPC:

{
  "jsonrpc": "2.0",
  "id": "tools-list-1",
  "method": "tools/list",
  "params": {}
}

Tool invocation uses tools/call:

{
  "jsonrpc": "2.0",
  "id": "render-1",
  "method": "tools/call",
  "params": {
    "name": "deployment.render",
    "arguments": {
      "hostId": "local-host",
      "instanceId": "petstore-dev",
      "environment": "dev",
      "clusterId": "local",
      "namespace": "light-deployer",
      "values": {},
      "template": {
        "repoUrl": "local",
        "ref": "main",
        "path": "k8s"
      }
    }
  }
}

tools/call derives the deployment action from params.name; callers should not provide an action field in arguments.

Actions

render : Fetch templates, render manifests, add namespaces and management labels, and return resource summaries plus a manifest hash.

dryRun : Render manifests and validate them against Kubernetes using server-side dry-run.

diff : Render manifests, fetch current managed resources, calculate additions, modifications, and pruned resources, and return a redacted diff summary.

deploy : Accept the request, run the deployment in the background, apply manifests, prune removed managed resources, and stream events.

undeploy : Delete resources associated with the deployment.

status : Return current managed resource status.

rollback : Reserved for redeploying a previous immutable portal snapshot. Native Kubernetes rollout undo is not the target rollback model because it does not restore ConfigMaps, Secrets, or values snapshots.

Template Fetching

Templates are loaded through the TemplateSource trait.

The current source supports two modes:

• local template root through LIGHT_DEPLOYER_TEMPLATE_BASE_DIR
• remote HTTPS Git clone through gix

For remote repositories, the deployment request provides:

{
  "template": {
    "repoUrl": "https://github.com/networknt/openapi-petstore.git",
    "ref": "master",
    "path": "k8s"
  }
}

Private HTTPS Git access is controlled by environment variables:

• LIGHT_DEPLOYER_GIT_TOKEN: token or app password
• LIGHT_DEPLOYER_GIT_USERNAME: optional username override

Defaults:

• GitHub uses x-access-token
• Bitbucket Cloud uses x-token-auth

SSH authentication is intentionally deferred because it requires private key handling and strict known_hosts validation.

Template Format

The built-in renderer uses simple placeholders:

image: ${image.repository}:${image.tag:latest}

Supported behavior:

• nested paths such as image.repository
• default values after :
• render failure when a required value is missing
• placeholder replacement only inside YAML string scalar values

The renderer parses YAML into serde_yaml::Value, traverses the AST, replaces placeholders, and serializes or applies structured YAML values afterward. This avoids the most common raw string replacement bugs around quoting, indentation, certificates, and multi-line values.

Because placeholders currently produce strings, templates should avoid placeholders in numeric-only Kubernetes fields unless Kubernetes accepts a string value there. For example, containerPort should be fixed or rendered by a future typed placeholder extension.

Resource Metadata

After rendering, the deployer ensures every resource has the target namespace and adds management labels:

• app.kubernetes.io/managed-by=light-deployer
• lightapi.net/host-id
• lightapi.net/instance-id
• lightapi.net/request-id

These labels are used for status lookup and pruning.

Kubernetes Execution

Kubernetes execution is behind the KubeExecutor trait.

Current implementations:

• KubeRsExecutor: real Kubernetes API execution through kube-rs
• NoopKubeExecutor: local render/test mode

Execution mode:

• LIGHT_DEPLOYER_KUBE_MODE=real: force real Kubernetes mode
• LIGHT_DEPLOYER_KUBE_MODE=noop: force no-op mode
• default: real mode when KUBERNETES_SERVICE_HOST is present, otherwise no-op

The production path uses kube-rs, not kubectl.

Kubernetes operations should use:

• in-cluster ServiceAccount auth when running as a pod
• server-side dry-run for validation
• server-side apply with field manager light-deployer
• structured status and error handling

Pruning

The deployer is declarative. If a previously managed resource is no longer rendered from the template, it should be considered for pruning.

Pruning is calculated by comparing:

• current resources in the namespace with lightapi.net/instance-id
• resources rendered from the new template

The policy layer enforces blast-radius protection:

• maximum delete percentage
• sensitive kinds requiring override
• explicit pruneOverride in deployment options

This prevents stale resources while still protecting against accidental large-scale deletion.

Policy

The local deployer.yml policy constrains what a deployer is allowed to do.

Policy dimensions:

• allowed namespaces
• allowed repository hosts
• allowed repository URL prefixes
• allowed image registries
• allowed actions
• allowed Kubernetes kinds
• blocked Kubernetes kinds
• prune settings
• development insecure mode

Version 1 allows application-level resource kinds by default:

• Deployment
• Service
• Ingress
• ConfigMap
• Secret

Cluster-scoped and control-plane resources are blocked by default:

• Namespace
• ClusterRole
• ClusterRoleBinding
• CustomResourceDefinition
• admission webhooks

Security

The deployer can mutate a Kubernetes cluster, so its default posture must be conservative.

Required practices:

• run in Kubernetes with a dedicated ServiceAccount
• prefer namespace-scoped Role and RoleBinding
• restrict allowed namespaces and resource kinds
• restrict template repository hosts or prefixes in production
• restrict image registries in production
• never log raw rendered Secret manifests
• never log raw Kubernetes patch/apply payloads containing Secret data
• return redacted summaries and diffs

Secret values in rendered manifests are redacted before being included in responses or diffs. Kubernetes Secret values are base64 encoded, not encrypted, so they must be treated as plaintext for logging purposes.

Response Model

Responses include enough detail for callers to understand what happened without exposing secrets.

Important fields:

• requestId
• action
• status
• deployerId
• clusterId
• namespace
• manifestHash
• templateCommitSha
• resources
• diff
• events
• error

Resource summaries contain kind, namespace, name, apiVersion, and action. Full rendered manifests should not be returned or persisted by default.

Event Model

Long-running operations return quickly and continue in the background.

Clients can subscribe to:

GET /events?request_id=...

Events contain:

• request ID
• timestamp
• status
• message
• optional resource identity

The event stream is currently direct SSE. Controller-mediated mode can forward the same event shape later.

Installation

The app includes Kubernetes install manifests under apps/light-deployer/k8s:

• namespace
• RBAC
• deployment
• service

The deployment runs the container with LIGHT_DEPLOYER_KUBE_MODE=real. The image contains /app/config, and server.yml defaults the HTTP port to 7088.

For MicroK8s testing:

./apps/light-deployer/build.sh latest
docker save networknt/light-deployer:latest | microk8s ctr image import -
microk8s kubectl apply -f apps/light-deployer/k8s/namespace.yaml
microk8s kubectl apply -f apps/light-deployer/k8s/rbac.yaml
microk8s kubectl apply -f apps/light-deployer/k8s/deployment.yaml
microk8s kubectl apply -f apps/light-deployer/k8s/service.yaml

Current Limitations

• Direct HTTP/MCP-style mode is implemented first; controller-mediated WebSocket routing is a later integration step.
• Inline values are implemented; config-server valuesRef fetching is still a future integration point.
• Rollback is represented in the model but needs portal snapshot integration.
• Helm and Kustomize are not implemented yet.
• Typed placeholders are not implemented yet.
• Rollout watch depth is intentionally basic in the first phase.

Design Direction

Keep light-deployer small and cluster-local.

The deployer should execute precise deployment commands, enforce local safety policy, and report structured results. It should not grow into a portal, workflow engine, or deployment database. That separation keeps the service easy to install inside customer clusters and reduces the security blast radius.

Module Registry

Status: Phase 4 implemented for light-gateway/gateway; additional module reloaders remain planned.

Purpose

Light Fabric needs a runtime module registry equivalent to the ModuleRegistry feature in light-4j.

In light-4j, each active component registers its runtime configuration when the component loads. Older integrations exposed this through the /adm/server/info REST endpoint, but the current control-plane path uses MCP tools through portal-registry. The same registry is also used by the config-reload operation to decide which modules can reload configuration from the config server.

Light Fabric already has structured config files and a shared runtime startup flow, but it does not yet have a central registry that answers these operational questions:

• which modules are active in this running instance
• which config file each module loaded
• what masked runtime config is currently active
• which modules can be reloaded without restarting the process
• what happened during the last reload attempt

This document proposes a registry in light-runtime so every Light Fabric application can expose the same control-plane behavior.

Goals

• Register built-in runtime configs such as startup, server, client, and portal-registry.
• Register application configs such as gateway, deployer, ollama, and mcp-client.
• Store only masked config snapshots in the registry.
• Expose a Java-compatible server-info payload through the get_service_info MCP tool.
• Expose a module list through the get_modules MCP tool for config reload selection.
• Support control-plane reload requests for one module, several modules, or all modules through the reload_modules MCP tool. Phase 3 reports non-reloadable modules as skipped. Phase 4 adds real hot reload for light-gateway/gateway.
• Keep the feature transport-neutral by routing management requests through portal-registry, not through framework-specific REST routes.

Non-Goals

• Do not make every config hot-reloadable in the first phase.
• Do not rebind server ports or TLS listeners unless a transport explicitly supports it.
• Do not expose decrypted secrets through diagnostics.
• Do not make Rust type names part of the public control-plane contract.
• Do not add /adm/... REST endpoints for Light Fabric.

Current Light Fabric Runtime Shape

The natural home for this feature is crates/light-runtime.

LightRuntimeBuilder already owns the startup sequence:

1. load local bootstrap config
2. optionally fetch remote config from config server
3. build RuntimeConfig
4. call registered runtime modules
5. bind the transport
6. register the running instance with the controller
7. mark the runtime ready

RuntimeConfig already carries the merged resolved_values, config_dir, and external_config_dir. Application code can use those fields to load resolved application config without reparsing values.yml.

The config registry should build on that runtime boundary instead of creating a separate app-local registry per product.

Registry Model

Add a shared registry type in light-runtime.

#![allow(unused)]
fn main() {
pub struct ModuleRegistry {
    entries: RwLock<BTreeMap<String, ModuleEntry>>,
    reloaders: RwLock<BTreeMap<String, Arc<dyn ReloadableModule>>>,
}

pub struct ModuleEntry {
    pub module_id: String,
    pub config_name: String,
    pub kind: ModuleKind,
    pub active: bool,
    pub enabled: Option<bool>,
    pub reloadable: bool,
    pub config: serde_json::Value,
    pub masks: Vec<MaskSpec>,
    pub loaded_at: DateTime<Utc>,
    pub last_reload: Option<ReloadStatus>,
}

pub enum ModuleKind {
    Core,
    Framework,
    Application,
    Plugin,
}
}

Use stable module IDs instead of Rust type names. Java uses class names because they are stable operational identifiers in the JVM. Rust type names are not a good public API and can change during refactoring.

Example module IDs:

• light-runtime/startup
• light-runtime/server
• light-client/client
• light-runtime/portal-registry
• light-gateway/gateway
• light-deployer/deployer
• light-agent/ollama
• light-agent/mcp-client

The registry key should be module_id. Each entry also carries config_name so the server-info response can preserve the Java-style component map keyed by config name.

Registered Config Loading

Add a small registered-loader API around the existing ConfigLoader behavior.

#![allow(unused)]
fn main() {
let gateway_config: GatewayConfig = context
    .config()
    .load_registered(
        "gateway",
        "light-gateway/gateway",
        [MaskSpec::key("password")],
    )?;
}

The helper should:

1. merge the base file from config_dir
2. overlay the external file from external_config_dir
3. resolve variables from RuntimeConfig.resolved_values
4. deserialize the typed config
5. serialize the resolved config to serde_json::Value
6. apply masks to the serialized copy
7. store only the masked copy in ModuleRegistry
8. return the typed config to the caller

This keeps the app code simple and prevents accidental registry entries that contain raw secrets.

Phase 2 added this shared registered-loader path in ModuleRegistry and attached the registry to RuntimeConfig so apps that load after runtime bootstrap can register resolved config through the same runtime-owned registry. Apps that load before runtime startup can create the registry first, register their application configs, and pass that registry into LightRuntimeBuilder. For modules that must validate typed config before changing the registry snapshot, the same loader is also available as load_config(...) followed by register_loaded_config(...) after validation succeeds.

Masking

Masking must happen at registration time. The registry should not store raw config and then mask it later.

Support two mask forms:

#![allow(unused)]
fn main() {
pub enum MaskSpec {
    Key(String),
    Path(String),
}
}

MaskSpec::Key("password") masks every matching key recursively, matching the current light-4j behavior.

MaskSpec::Path("oauth.clientSecret") masks a precise path for configs where a generic key would be too broad.

Suggested default masks:

• authorization
• password
• secret
• clientSecret
• apiKey
• token
• portalToken
• controllerDiscoveryToken
• privateKey
• tlsKeyPath
• bootstrapKeyPath

Add a runtime flag such as server.maskConfigProperties or admin.maskConfigProperties, defaulting to true, for parity with the Java server.maskConfigProperties behavior. Even if this flag is disabled, the control-plane documentation should treat unmasked output as a local debugging mode only.

Server Info MCP Response

The get_service_info MCP tool response should preserve the same logical shape that portal-view already understands from Java instances.

{
  "deployment": {
    "apiVersion": "0.1.0",
    "frameworkVersion": "0.1.0"
  },
  "environment": {
    "host": {
      "ip": "127.0.0.1",
      "hostname": "light-gateway-0"
    },
    "runtime": {},
    "system": {}
  },
  "security": {},
  "component": {
    "server": {},
    "gateway": {}
  },
  "plugin": {},
  "plugins": [],
  "modules": []
}

component should remain keyed by config_name for compatibility.

modules should provide richer Rust metadata:

[
  {
    "moduleId": "light-gateway/gateway",
    "configName": "gateway",
    "kind": "application",
    "active": true,
    "enabled": true,
    "reloadable": true,
    "loadedAt": "2026-05-07T14:30:00Z",
    "lastReload": {
      "status": "success",
      "message": "reloaded from config server",
      "completedAt": "2026-05-07T14:45:00Z"
    }
  }
]

MCP Access

Expose the registry only through MCP tools served by the runtime's portal-registry connection.

MCP tools:

get_service_info
get_modules
reload_modules

These are invoked through standard MCP JSON-RPC calls:

{
  "jsonrpc": "2.0",
  "id": "info-1",
  "method": "tools/call",
  "params": {
    "name": "get_service_info",
    "arguments": {}
  }
}

The controller remains the management channel. portal-registry receives the MCP request from the controller, dispatches it to the local runtime registry, and returns the result through the same websocket session. Light Fabric should not expose a parallel REST admin surface for this feature.

For compatibility with the existing Java and portal-view workflow, get_modules returns a string list of module IDs:

{
  "modules": [
    "light-runtime/server",
    "light-gateway/gateway"
  ]
}

The richer module metadata remains available in the modules field of get_service_info.

Reload Request

The reload_modules tool should accept omitted arguments, ALL, or explicit module IDs.

{
  "modules": [
    "light-gateway/gateway",
    "light-runtime/portal-registry"
  ]
}

An omitted modules value, an empty array, or ["ALL"] targets all registered modules. Registered modules without concrete reload implementations are reported as skipped instead of being marked as reloaded.

The response should be explicit about what happened:

{
  "modules": ["light-gateway/gateway"],
  "reloaded": ["light-gateway/gateway"],
  "skipped": [
    {
      "moduleId": "light-runtime/server",
      "reason": "requiresRestart"
    }
  ],
  "failed": [
    {
      "moduleId": "light-agent/ollama",
      "message": "missing ollama.yml"
    }
  ]
}

modules is a Java-compatible alias for the successfully reloaded module IDs and is the field portal-view reads today. reloaded, skipped, and failed carry the more explicit Rust result details.

Reload Implementation

Phase 4 adds a reload trait for modules that can safely swap runtime config.

#![allow(unused)]
fn main() {
#[async_trait]
pub trait ReloadableModule: Send + Sync {
    async fn reload(&self, ctx: ReloadContext) -> Result<ReloadOutcome, RuntimeError>;
}
}

ReloadContext includes:

• a refreshed RuntimeConfig
• updated resolved_values
• the existing config_dir
• the existing external_config_dir
• the shared ModuleRegistry

Reload flow:

1. Re-fetch values.yml, certs, and files from the config server into external_config_dir.
2. Rebuild the merged resolved_values.
3. Resolve requested module IDs.
4. For each reloadable module, call its reload implementation.
5. Each module validates the new typed config before swapping it into live state.
6. Update the registry entry and last_reload status.
7. Return a detailed reload result.

Use ConfigManager<T> or another ArcSwap-backed holder for modules that need hot reload. This avoids locking the request path while still allowing atomic config replacement.

Phase 4 implements this with ConfigManager<T> in light-runtime. It stores an Arc<T> behind a short-lived RwLock, so request handlers clone the current config quickly and reloaders replace the entire typed config only after the new config has loaded and validated.

Reloadability Rules

Classify configs by reload safety.

Reloadable candidates:

• light-gateway/gateway
• light-deployer/deployer
• light-agent/ollama
• light-agent/mcp-client
• route, policy, provider, or rule configs that are already read through swappable state

Requires restart by default:

• bind IP
• HTTP/HTTPS port
• protocol enablement
• TLS certificate path used by the listener
• runtime config directory
• config-server bootstrap identity
• controller registration identity

Some server.yml fields can still be reloadable later, such as shutdownGracefulPeriod, but listener-affecting fields should stay requiresRestart until each transport supports safe rebinding.

Framework Integration

The registry should not require each framework to expose admin routes.

light-runtime should attach an MCP-capable RegistryHandler to the portal-registry client. When the controller invokes tools/list or tools/call, the handler can advertise and execute the local management tools without involving light-axum or light-pingora request routing.

This keeps light-axum and light-pingora focused on application traffic. It also avoids adding service ports, Kubernetes routes, or Pingora request filters only for control-plane operations.

Application Integration

light-gateway is integrated first because it already loads gateway.yml from RuntimeConfig.resolved_values, config_dir, and external_config_dir. It loads the resolved typed config, validates upstreams, and then stores the masked registry snapshot. In Phase 4, light-gateway/gateway also registers a ReloadableModule that reloads and validates gateway.yml, updates the masked registry snapshot, and swaps the live GatewayConfig through ConfigManager.

light-deployer loads deployer.yml before the runtime is started, so it creates a ModuleRegistry before loading its config, registers the final env-overridden deployer config, and passes the same registry to LightRuntimeBuilder.

light-agent also loads application configs before runtime startup. It now registers ollama.yml and mcp-client.yml in the pre-runtime registry and passes that registry into LightRuntimeBuilder. The existing manual PortalRegistryClient setup is unchanged so the registry feature does not reintroduce duplicate controller registration.

Current Registered Modules

Phase 4 registers these modules:

The application modules are visible in get_service_info once their owning application loads them. get_modules returns the corresponding module ID strings for portal-view selection. light-gateway/gateway can reload without a restart. Other application modules keep reloadable=false until their runtime state is moved behind swappable holders.

Rollout Plan

Phase 1: Registry and Masked Info

• Implemented: ModuleRegistry, ModuleEntry, and mask utilities in light-runtime.
• Implemented: built-in runtime config registration.
• Implemented: tests proving raw secrets are not stored in registry entries.
• Implemented: Java-compatible server-info response assembly.
• Implemented: module-list response.
• Implemented: a portal-registry MCP handler that exposes get_service_info and get_modules.

Phase 2: Application Registration

• Implemented: convert light-gateway/gateway to registered config loading.
• Implemented: convert light-deployer/deployer.
• Implemented: convert light-agent/ollama and light-agent/mcp-client.
• Implemented: add docs showing module IDs and reloadability.

Phase 3: Controller Operations

• Implemented: add MCP tools/list and tools/call support for reload_modules.
• Implemented: align portal-view calls so Java and Rust instances can be managed with the same control-plane workflow.
• Implemented: return Java-compatible modules string lists while preserving detailed reloaded, skipped, and failed reload result fields.

Phase 4: Hot Reload

• Implemented: add ReloadableModule, ReloadContext, and ReloadOutcome.
• Implemented: add ConfigManager<T> for swappable typed configs.
• Implemented: implement reload for light-gateway/gateway.
• Implemented: add reload result tracking in the registry.
• Implemented: add tests for registry reload results, gateway live config swapping, and config-server-backed reload context refresh.

Open Questions

• Should module IDs be centrally reserved in light-runtime, or should each application own its ID namespace?
• Should the Java-compatible component map include only active modules, while modules includes inactive-but-known modules?
• Should MCP tool execution be enabled whenever portal-registry is enabled, or guarded by a separate admin-tools flag?
• Should server.maskConfigProperties=false be allowed in production builds, or should Rust always mask known dangerous keys?

Implementation Sequence

Phase 1 implemented registry and masked server info first, without hot reload.

Phase 2 added application registration, so portal-view can display Rust application modules next to Java modules once it calls the MCP tools through portal-registry.

Phase 3 added the controller-facing reload_modules tool and Java-compatible module ID lists.

Phase 4 added the first real hot reload implementation for light-gateway/gateway. The next implementation step is to move additional application configs, such as light-deployer/deployer, light-agent/ollama, and light-agent/mcp-client, behind swappable runtime state before marking them reloadable.

Module Hot Reload

This document describes the design and implementation of the hot reload mechanism in Light Fabric, explaining how modules reload configuration at runtime without requiring a full process restart.

Overview

In Light Fabric, certain configurations can be updated dynamically at runtime to support continuous delivery and quick configuration tuning (e.g., routing changes, CORS policies, security settings, or service discovery URLs). The system provides a unified Module Registry and Reloadable Modules architecture that allows the control plane (via MCP tools) to trigger config reloads.

Reload Flow

When the reload_modules MCP tool is invoked, the control plane initiates the following sequence:

sequenceDiagram
    participant ControlPlane as Control Plane / Portal Registry
    participant Handler as Runtime MCP Handler
    participant Config as RuntimeConfig
    participant Registry as Module Registry
    participant Reloader as Module Reloaders
    
    ControlPlane->>Handler: Call reload_modules
    Handler->>Config: reload_context()
    Note over Config: Re-fetch remote files,<br/>re-read local config yml,<br/>and build ReloadContext
    Config-->>Handler: Return ReloadContext
    Handler->>Registry: reload_modules(context, target_modules)
    Note over Registry: Update direct-registry & client configs
    loop For each reloadable module
        Registry->>Reloader: reload(context)
        Reloader->>Config: Load new file config
        Reloader->>Registry: register_loaded_config(...)
        Note over Reloader: Store fresh config in ConfigManager
    end
    Registry-->>Handler: Return ReloadModulesResult
    Handler-->>ControlPlane: Return result JSON

1. Build Reload Context: The runtime constructs a ReloadContext containing a fresh RuntimeConfig by parsing the updated config files (local or fetched from the config server) and merging dynamic values.yml parameters.
2. Pre-update Built-in Configs: The core configurations stored inside ModuleRegistry (such as light-client/client and light-runtime/direct-registry) are updated in-memory using the reloaded config.
3. Dispatch to Module Reloaders: The registry iterates over the target modules and invokes the corresponding ReloadableModule::reload implementation.
4. Atomic State Swap: Inside each reloader, the new configuration is parsed, validated, registered in the registry, and swapped atomically using ConfigManager<T>.

ConfigManager and Thread Safety

To prevent request latency during reloads, Light Fabric uses a thread-safe ConfigManager<T> to manage dynamic configurations.

ConfigManager wraps an Arc<T> with a short-lived RwLock. Request handlers clone the Arc instantly (a simple reference count increment) without blocking, while the reloader replaces the entire Arc<T> atomically after the new configuration is successfully parsed and validated.

Core Hot Reload Implementations

Direct Registry Reload (light-runtime/direct-registry)

The direct registry maps service IDs to direct URLs for service discovery.

• Reload Process: The direct URLs are updated in values.yml (either locally or on a remote config server). On reload, ReloadContext parses the new URLs, and reload_modules updates the registered config for "light-runtime/direct-registry" in the ModuleRegistry.
• Propagation: Runtimes such as the McpRouterRuntime or the TokenRuntime re-read the updated direct_registry config from the fresh RuntimeConfig when they are reloaded.

Client Configuration Reload (light-client/client)

The client configuration contains TLS settings and OAuth token provider configurations.

• Reloadable Flag: The client module is registered with reloadable: true at startup.
• Reload Process: The ReloadContext re-loads client.yml from disk, applying new TLS properties or OAuth credentials. The reload_modules function updates the registered client configuration (applying proper masks to client secrets and certificates).
• Reloader: A registered ClientReloader marks the transition success. Dependent modules (like light-pingora/mcp-router and light-pingora/token) query the new client configuration from the context upon reload.

Reloadable vs. Non-Reloadable Configs

[!NOTE] Modifying non-reloadable configurations requires a full restart of the gateway process to bind new server listeners or configure registry websocket connections securely.

Verification & Testing

Module hot-reloading can be verified using the following automated test suites:

• Direct Registry Test: reload_modules_updates_direct_registry_config (defined in crates/light-runtime/src/module_registry.rs) asserts that updated direct discovery URLs are correctly reflected in the registry.
• Client Config Test: gateway_client_config_reload (defined in apps/light-gateway/src/main.rs) asserts that updated TLS verification settings in client.yml are loaded and reflected in the registry.

Controller Registry Client

The Controller Registry Client (portal-registry) manages the connection between a gateway (or agent) instance and the Light Portal control plane. It enables runtime instance registration, service discovery queries, and dynamic configuration synchronization over a secure WebSocket connection.

Architecture Overview

The registry client operates as a background service inside the runtime. It establishes a persistent connection to the controller and handles bidirectional communication.

sequenceDiagram
    participant Instance as Gateway / Agent
    participant Client as Portal Registry Client
    participant Controller as Control Plane / Portal
    
    Instance->>Client: Initialize and run()
    loop Connection Loop
        Client->>Controller: WebSocket Handshake (WSS)
        Note over Client,Controller: Negotiate TLS & Custom Certificates
        
        alt Connection Succeeded
            Client->>Controller: service/register (JSON-RPC Request)
            Controller-->>Client: Registration Response (Instance ID)
            Note over Client: State = Registered
            
            loop Active Connection (tokio::select!)
                alt Heartbeat interval (30s)
                    Client->>Controller: Ping
                    Controller-->>Client: Pong
                end
                
                alt Server Request
                    Controller->>Client: JSON-RPC Request / Notification
                    Client->>Controller: Response
                end
            end
        else Connection Failed / Severed
            Note over Client: State = Disconnected
            Note over Client: Calculate backoff + jitter
            Client->>Client: Sleep before retry
        end
    end

Core Features

1. WebSocket Protocol & Handshake

The connection is established over standard WebSocket (secured via TLS: wss://). Once connected, the client performs an initial JSON-RPC handshake:

• Method: service/register
• Parameters: ServiceRegistrationParams (containing serviceId, version, host address, listening port, tags, envTag, and a verification jwt token).
• Result: RegistrationResponse returning a unique runtimeInstanceId assigned by the control plane.

2. Heartbeat (Ping/Pong)

To prevent network firewalls from dropping inactive connections and to detect silent TCP half-open connection drops, the client sends a WebSocket Ping frame every 30 seconds.

• If the control plane fails to reply, or the socket write fails, the connection loop is terminated immediately to initiate reconnection.
• The client also responds immediately with a Pong to any inbound Ping frames received from the controller.

3. Exponential Backoff with Jitter

When a connection is lost, terminated, or fails to initialize, the client retries using an exponential backoff strategy:

• Base delay starts at 1 second and doubles on subsequent retries up to a maximum of 60 seconds.
• Random Jitter of 0-1000 milliseconds is added to each sleep duration.
• Thundering Herd Prevention: Jitter prevents synchronized gateway instances (e.g., in a Kubernetes cluster) from flooding the control plane with connection requests at the exact same moment when it restarts.

4. TLS & Certificate Verification

The client supports establishing WSS connections with two cert verification modes:

• Standard Verification (verifyHostname: true): Validates the server certificate chain against loaded CA certificates and verifies that the certificate hostname matches the controller domain.
• No-Hostname Verification (verifyHostname: false): Useful in local development or custom routing networks. It validates the certificate chain against the trusted CA bundle but bypasses hostname verification.

Component Configuration

Registry settings are loaded from portal-registry.yml or mapped in startup configuration:

Verification & Testing

The registry client behaves predictably under connection drops and can be verified via:

• Handshake Verification: registration_and_metadata_update_match_controller_protocol (defined in crates/portal-registry/src/client.rs) asserts correct JSON-RPC registration format and success handling.
• WebSocket Gateway integration: websocket_gateway_proxies_text_binary_close_subprotocol_and_headers (defined in apps/light-gateway/src/main.rs) tests end-to-end WebSocket proxying alongside a mock controller registry.
• Reconnect Loop Verification: test_registry_client_reconnects_and_reregisters_on_run_level (defined in crates/portal-registry/src/client.rs) verifies that client terminates connection on socket drop, calculates backoff delay, reconnects, and re-registers automatically.
• Heartbeat Timeout Verification: test_heartbeat_timeout_detects_silent_controller_loss (defined in crates/portal-registry/src/client.rs) tests that the client detects silent connection drops by terminating and transitioning to Disconnected if the controller does not respond to Ping within the configured heartbeat timeout window.

Cache Control Plane

Status: Proposed

Purpose

Light Fabric should expose the same cache operations through the portal control plane that Java services expose through light-4j and portal-registry.

Today, portal-view can list caches and inspect cache entries for a running service instance. The next required operation is clearing a cache so cached data can be reloaded from its source of truth after operational data changes. A common case is clearing the reference-data cache in portal-service after reference tables are changed from light-portal.

The feature should be generic. It should not be a portal-service only endpoint. Any Java or Rust service that registers with the controller and has named local caches should be manageable through the same MCP tool contract.

Current Shape

The Java implementation already has most of the control-plane pieces:

• light-4j/cache-manager defines the generic CacheManager API.
• light-4j/caffeine-cache provides the Caffeine-backed implementation.
• light-4j/portal-registry exposes MCP tools such as list_caches and get_cache_entries.
• controller-rs and the Java controller forward instance-specific MCP tool calls by runtimeInstanceId.
• portal-view calls the controller MCP websocket and passes runtimeInstanceId for cache exploration.

The main semantic gap is that CacheManager.removeCache(name) removes the cache from the manager in the Caffeine implementation. For a control-plane clear operation, the desired behavior is different: invalidate all entries while keeping the configured cache alive so the next application read repopulates it.

Goals

• Add a generic whole-cache clear operation.
• Keep the control-plane contract compatible between Java services and Light Fabric services.
• Expose cache operations through portal-registry and controller MCP routing, not through service-specific REST endpoints.
• Let portal-view clear a selected cache from the existing Cache Explorer page.
• Use the same feature for portal-service reference data caching.
• Preserve existing cache inspection behavior.

Non-Goals

• Do not remove or unregister a configured cache when clearing entries.
• Do not require every service to use the same cache backend.
• Do not expose raw secrets or unsafe object internals through cache inspection.
• Do not build event-driven cross-service cache invalidation in the first phase.
• Do not confuse runtime data caches with the config-cache directory used for remote configuration files.

MCP Tool Contract

Add a new generic tool:

{
  "name": "clear_cache",
  "description": "Clear all entries from a named cache on a live runtime instance.",
  "inputSchema": {
    "type": "object",
    "required": ["runtimeInstanceId", "name"],
    "properties": {
      "runtimeInstanceId": { "type": "string", "format": "uuid" },
      "name": { "type": "string" }
    }
  }
}

The controller accepts runtimeInstanceId, removes it from the forwarded arguments, and sends this to the target runtime:

{
  "name": "clear_cache",
  "arguments": {
    "name": "reference-data"
  }
}

Recommended success response:

{
  "supported": true,
  "status": "success",
  "name": "reference-data",
  "beforeSize": 42,
  "afterSize": 0
}

Recommended unsupported response:

{
  "supported": false,
  "status": "unsupported",
  "name": "reference-data",
  "message": "Cache support is not available on this service."
}

Key-level invalidation can be added later as a separate invalidate_cache_entry tool with { "name": "...", "key": "..." }. Whole-cache clear should be implemented first because it solves the reference data reload case without introducing cache-key UX and serialization questions.

Java Compatibility Work

In light-4j, add an explicit clear operation to the generic cache API:

void clear(String cacheName);

The Caffeine implementation should call cache.invalidateAll() and keep the cache in the manager. It may call cache.cleanUp() before returning size data. removeCache(name) should keep its existing unregister/remove semantics.

portal-registry should advertise clear_cache in tools/list and handle it in tools/call by using CacheManager.getInstance(). The handler should return supported: false when cache classes or a cache manager are not available, matching the current list_caches and get_cache_entries behavior.

The controller catalogs need the same tool so portal-view can call it through the normal controller websocket:

• controller-rs tool catalog and command serialization
• Java light-controller tool catalog and routed-call handling, if it remains a supported control-plane runtime

Light Fabric Runtime Design

Light Fabric should provide a small cache abstraction at the runtime layer so applications do not each define a different operational surface.

A practical shape is:

#![allow(unused)]
fn main() {
#[async_trait::async_trait]
pub trait RuntimeCache: Send + Sync {
    async fn len(&self) -> usize;
    async fn entries_summary(&self) -> serde_json::Value;
    async fn clear(&self);
}

#[derive(Default)]
pub struct CacheRegistry {
    caches: RwLock<BTreeMap<String, Arc<dyn RuntimeCache>>>,
}
}

The registry should support:

• register named cache
• list cache names
• get summarized entries
• clear a named cache

moka is the preferred default backend for async Rust services because it maps well to the Caffeine use case. Applications should still be free to register custom cache wrappers as long as they implement the runtime trait.

RuntimeMcpHandler in light-runtime should expose the same tools as Java:

• list_caches
• get_cache_entries
• clear_cache

If a runtime has no cache registry, these tools should return supported: false rather than failing the request.

Portal Service Reference Data Cache

portal-service can use the generic Light Fabric cache for /r/data.

Suggested cache names:

• reference-data
• reference-data-relation

Suggested keys:

• host:{hostId|global}:lang:{lang}:table:{name}
• host:{hostId|global}:lang:{lang}:table:{name}:rela:{rela}:from:{from}

The request flow becomes:

1. /r/data receives a reference-data request.
2. ReferenceService builds a stable cache key from host, language, table, relation, and source value.
3. On cache hit, return cached reference data.
4. On cache miss, query Postgres, cache the result, and return it.
5. When reference data changes in light-portal, an operator clears reference-data or reference-data-relation for the target portal-service runtime instance from portal-view.
6. The next /r/data call reloads from Postgres.

This keeps the first implementation manual and deterministic. A later phase can subscribe to reference-table change events and clear matching caches automatically.

Portal View UX

The existing Cache Explorer page should stay the main UI.

Add a clear action for the selected cache:

• show the selected cache name
• require confirmation before clearing
• disable the button while the request is running
• call clear_cache with { runtimeInstanceId, name }
• show success or error status
• refetch cache entries after a successful clear

The UI should not require users to know whether the target service is Java or Rust. Unsupported runtimes should show the returned unsupported message.

Implementation Phases

Phase 1: Java clear support

• Add CacheManager.clear(cacheName).
• Implement it in caffeine-cache.
• Add clear_cache to portal-registry MCP tools.
• Add targeted tests for clearing while preserving the configured cache.

Phase 2: Controller and portal-view

• Add clear_cache to controller tool catalogs and command routing.
• Add the Cache Explorer clear button and confirmation.
• Verify the existing runtimeInstanceId forwarding path is reused.

Phase 3: Light Fabric generic cache

• Add a runtime cache registry and trait.
• Add moka backed cache support.
• Expose list_caches, get_cache_entries, and clear_cache from RuntimeMcpHandler.
• Add focused light-runtime tests for supported and unsupported cache cases.

Phase 4: Portal service reference data

• Register reference-data and reference-data-relation caches.
• Cache /r/data query results.
• Clear the cache from portal-view and verify the next request reloads from Postgres.

Verification

Recommended targeted checks:

mvn -q -pl cache-manager,caffeine-cache,portal-registry test
cargo test -p light-runtime
cargo check --workspace
yarn build

Use the Maven command in light-4j, the Cargo commands in light-fabric and portal-service as appropriate, and the frontend build in portal-view.

Client Configuration And Modules

Status

Brainstorming proposal for standardizing client.yml across Light Fabric runtime, framework modules, and products.

The immediate trigger is that different Rust modules currently interpret client.yml differently. For example, light-runtime reads a small top-level verifyHostname field for controller and config-server clients, while light-pingora token and SPA modules read a Java-style nested tls section. That split makes a single client.verifyHostname: false value unreliable.

This document proposes a common contract so every Rust module uses the same client.yml file and the same typed configuration model.

Purpose

client.yml should describe outbound client behavior for a running service:

• TLS trust, hostname verification, and optional client identity.
• HTTP request timeout, retry, circuit breaker, connection pool, and HTTP/2 behavior.
• OAuth 2.0 token, key, sign, dereference, and provider-selection behavior.
• Path-prefix-to-service mapping used when different downstream services use different OAuth providers.

The file should be loaded once through the runtime configuration system, registered once in the module registry with secrets masked, then shared by all modules that make outbound calls.

Compatibility Contract

The Java light-4j client.yml remains the compatibility baseline. Rust can clean up the internal model, but it should not remove behavior that Java http-client and client-config expose.

Important Java sections:

tls:
  verifyHostname: ${client.verifyHostname:true}
  loadDefaultTrustStore: ${client.loadDefaultTrustStore:true}
  loadTrustStore: ${client.loadTrustStore:true}
  trustStore: ${client.trustStore:client.truststore}
  trustStorePass: ${client.trustStorePass:password}
  loadKeyStore: ${client.loadKeyStore:false}
  keyStore: ${client.keyStore:client.keystore}
  keyStorePass: ${client.keyStorePass:password}
  keyPass: ${client.keyPass:password}
  defaultCertPassword: ${client.defaultCertPassword:changeit}
  tlsVersion: ${client.tlsVersion:TLSv1.3}

oauth:
  multipleAuthServers: ${client.multipleAuthServers:false}
  token:
    cache:
      capacity: ${client.tokenCacheCapacity:200}
    tokenRenewBeforeExpired: ${client.tokenRenewBeforeExpired:60000}
    expiredRefreshRetryDelay: ${client.expiredRefreshRetryDelay:2000}
    earlyRefreshRetryDelay: ${client.earlyRefreshRetryDelay:4000}
    server_url: ${client.tokenServerUrl:}
    serviceId: ${client.tokenServiceId:com.networknt.oauth2-token-1.0.0}
    proxyHost: ${client.tokenProxyHost:}
    proxyPort: ${client.tokenProxyPort:}
    enableHttp2: ${client.tokenEnableHttp2:true}
    authorization_code: {}
    client_credentials: {}
    refresh_token: {}
    token_exchange: {}
    key: {}
  sign: {}
  deref: {}

pathPrefixServices: ${client.pathPrefixServices:}

request:
  errorThreshold: ${client.errorThreshold:2}
  connectTimeout: ${client.connectTimeout:2000}
  timeout: ${client.timeout:3000}
  resetTimeout: ${client.resetTimeout:7000}
  injectOpenTracing: ${client.injectOpenTracing:false}
  injectCallerId: ${client.injectCallerId:false}
  enableHttp2: ${client.enableHttp2:true}
  connectionPoolSize: ${client.connectionPoolSize:1000}
  connectionExpireTime: ${client.connectionExpireTime:1800000}
  maxReqPerConn: ${client.maxReqPerConn:1000000}
  maxConnectionNumPerHost: ${client.maxConnectionNumPerHost:1000}
  minConnectionNumPerHost: ${client.minConnectionNumPerHost:250}
  maxRequestRetry: ${client.maxRequestRetry:3}
  requestRetryDelay: ${client.requestRetryDelay:1000}
  poolMetricsEnabled: ${client.poolMetricsEnabled:false}
  poolWarmUpEnabled: ${client.poolWarmUpEnabled:false}
  poolWarmUpSize: ${client.poolWarmUpSize:1}
  healthCheckEnabled: ${client.healthCheckEnabled:true}
  healthCheckIntervalMs: ${client.healthCheckIntervalMs:30000}

Rust should add fields such as tls.caCertPath, tls.clientCertPath, and tls.clientKeyPath because PEM files are the native Rust deployment shape. Rust does not need to support Java-specific JKS/JCEKS truststore or keystore formats. If those Java-only fields appear in a Rust client.yml, they can be ignored because config-server should control which fields it injects for Rust services.

Initial Rust Gaps

At the start of this migration, the Rust implementation had three separate interpretations of client configuration:

Before this design, Rust support was also partial compared with Java:

Goals

• Keep client.yml as the only config file for outbound client behavior.
• Make the Java nested shape canonical: tls.verifyHostname, not top-level verifyHostname.
• Load and register the resolved client.yml once through light-runtime.
• Share one typed ClientConfig across runtime, Pingora, gateway, agent, deployer, MCP clients, model-provider clients, and future products.
• Preserve Java-compatible field names and config-server placeholder names.
• Support direct URL, direct registry, and portal registry service discovery consistently for token, key, sign, deref, and generic outbound calls.
• Keep secrets masked in module registry snapshots and logs.
• Make invalid active client config fail startup or reject reload before it changes live runtime behavior.
• Allow Rust-native PEM fields without forcing Java keystore names into every Rust deployment.

Non-Goals

• Do not move handler activation into client.yml. Handler-specific files such as token.yml, statelessAuth.yml, and msal-exchange.yml still decide whether a handler runs.
• Do not implement every Java-only low-level connection-pool behavior in the first phase. The shared schema should include the fields so config is not lost, but unsupported fields can be ignored deliberately until the transport supports them.
• Do not expose decrypted client secrets, tokens, or legacy Java password fields through module registry, MCP tools, logs, metrics, or cache output.
• Do not require every module to use OAuth. The shared config must support simple TLS-only clients too.

Resolved Decisions

• Create a separate light-client crate now so the shared config, HTTP client factory, OAuth client, and provider resolver can be reused without coupling every consumer to light-runtime.
• Standardize Rust outbound TLS material on PEM paths. Java truststore and keystore formats are not required for Rust services.
• client.yml reload should not force an immediate portal-registry reconnect. Reload is primarily for newly onboarded JWKS/JWT access and future outbound requests. Existing long-lived controller connections can keep running until their normal reconnect or service restart.
• Unsupported Java fields can be ignored by Rust. Config-server should avoid injecting unsupported fields into Rust service config.
• Ignored Java-only fields should be ignored silently. Rust startup does not need to warn about fields that config-server may omit for Rust services.
• oauth.multipleAuthServers remains accepted for Java compatibility, but Rust should infer multi-provider mode when serviceIdAuthServers is configured.
• pathPrefixServices stays in client.yml. It is outbound-client provider selection and is different from inbound path routing to downstream services.
• Circuit breaker behavior is only needed by Pingora. Shared request config can carry the Java-compatible fields, but non-Pingora clients do not need to own circuit breaker state.
• SAML bearer is not required for Light Fabric and should remain out of scope unless a future product explicitly needs it.

Proposed Canonical Shape

The canonical Rust client.yml should stay close to Java:

tls:
  verifyHostname: ${client.verifyHostname:true}
  caCertPath: ${client.caCertPath:}
  clientCertPath: ${client.clientCertPath:}
  clientKeyPath: ${client.clientKeyPath:}
  tlsVersion: ${client.tlsVersion:TLSv1.3}

request:
  connectTimeout: ${client.connectTimeout:2000}
  timeout: ${client.timeout:3000}
  maxRequestRetry: ${client.maxRequestRetry:3}
  requestRetryDelay: ${client.requestRetryDelay:1000}
  errorThreshold: ${client.errorThreshold:2}
  resetTimeout: ${client.resetTimeout:7000}
  injectCallerId: ${client.injectCallerId:false}
  enableHttp2: ${client.enableHttp2:true}
  connectionPoolSize: ${client.connectionPoolSize:1000}
  connectionExpireTime: ${client.connectionExpireTime:1800000}
  maxReqPerConn: ${client.maxReqPerConn:1000000}
  maxConnectionNumPerHost: ${client.maxConnectionNumPerHost:1000}
  minConnectionNumPerHost: ${client.minConnectionNumPerHost:250}
  poolMetricsEnabled: ${client.poolMetricsEnabled:false}
  poolWarmUpEnabled: ${client.poolWarmUpEnabled:false}
  poolWarmUpSize: ${client.poolWarmUpSize:1}
  healthCheckEnabled: ${client.healthCheckEnabled:true}
  healthCheckIntervalMs: ${client.healthCheckIntervalMs:30000}

oauth:
  multipleAuthServers: ${client.multipleAuthServers:false}
  token:
    cache:
      capacity: ${client.tokenCacheCapacity:200}
    tokenRenewBeforeExpired: ${client.tokenRenewBeforeExpired:60000}
    expiredRefreshRetryDelay: ${client.expiredRefreshRetryDelay:2000}
    earlyRefreshRetryDelay: ${client.earlyRefreshRetryDelay:4000}
    server_url: ${client.tokenServerUrl:}
    serviceId: ${client.tokenServiceId:com.networknt.oauth2-token-1.0.0}
    proxyHost: ${client.tokenProxyHost:}
    proxyPort: ${client.tokenProxyPort:}
    enableHttp2: ${client.tokenEnableHttp2:true}
    authorization_code:
      uri: ${client.tokenAcUri:/oauth2/token}
      client_id: ${client.tokenAcClientId:}
      client_secret: ${client.tokenAcClientSecret:}
      redirect_uri: ${client.tokenAcRedirectUri:}
      scope: ${client.tokenAcScope:}
    client_credentials:
      uri: ${client.tokenCcUri:/oauth2/token}
      client_id: ${client.tokenCcClientId:}
      client_secret: ${client.tokenCcClientSecret:}
      scope: ${client.tokenCcScope:}
      serviceIdAuthServers: ${client.tokenCcServiceIdAuthServers:}
    refresh_token:
      uri: ${client.tokenRtUri:/oauth2/token}
      client_id: ${client.tokenRtClientId:}
      client_secret: ${client.tokenRtClientSecret:}
      scope: ${client.tokenRtScope:}
    token_exchange:
      uri: ${client.tokenExUri:/oauth2/token}
      client_id: ${client.tokenExClientId:}
      client_secret: ${client.tokenExClientSecret:}
      scope: ${client.tokenExScope:}
      subjectToken: ${client.subjectToken:}
      subjectTokenType: ${client.subjectTokenType:urn:ietf:params:oauth:token-type:jwt}
      requestedTokenType: ${client.requestedTokenType:}
      audience: ${client.tokenExAudience:}
    key:
      server_url: ${client.tokenKeyServerUrl:}
      serviceId: ${client.tokenKeyServiceId:com.networknt.oauth2-key-1.0.0}
      uri: ${client.tokenKeyUri:/oauth2/key}
      client_id: ${client.tokenKeyClientId:}
      client_secret: ${client.tokenKeyClientSecret:}
      enableHttp2: ${client.tokenKeyEnableHttp2:true}
      serviceIdAuthServers: ${client.tokenKeyServiceIdAuthServers:}
      audience: ${client.tokenKeyAudience:}
  sign:
    server_url: ${client.signServerUrl:}
    serviceId: ${client.signServiceId:com.networknt.oauth2-token-1.0.0}
    uri: ${client.signUri:/oauth2/sign}
    timeout: ${client.signTimeout:2000}
    client_id: ${client.signClientId:}
    client_secret: ${client.signClientSecret:}
    proxyHost: ${client.signProxyHost:}
    proxyPort: ${client.signProxyPort:}
    enableHttp2: ${client.signEnableHttp2:true}
    key:
      server_url: ${client.signKeyServerUrl:}
      serviceId: ${client.signKeyServiceId:com.networknt.oauth2-key-1.0.0}
      uri: ${client.signKeyUri:/oauth2/key}
      client_id: ${client.signKeyClientId:}
      client_secret: ${client.signKeyClientSecret:}
      enableHttp2: ${client.signKeyEnableHttp2:true}
      audience: ${client.signKeyAudience:}
  deref:
    server_url: ${client.derefServerUrl:}
    serviceId: ${client.derefServiceId:com.networknt.oauth2-token-1.0.0}
    uri: ${client.derefUri:/oauth2/deref}
    client_id: ${client.derefClientId:}
    client_secret: ${client.derefClientSecret:}
    proxyHost: ${client.derefProxyHost:}
    proxyPort: ${client.derefProxyPort:}
    enableHttp2: ${client.derefEnableHttp2:true}

pathPrefixServices: ${client.pathPrefixServices:}

Compatibility aliases:

• Accept serverUrl in addition to Java server_url for Rust callers.
• Accept clientId and clientSecret in addition to Java client_id and client_secret only as aliases. The emitted template should keep Java names.
• Temporarily accept top-level verifyHostname only as a migration fallback, but register a warning and normalize it into tls.verifyHostname.

Serde strategy for the top-level verifyHostname fallback:

• The shared ClientConfig should deserialize into a struct that has a tls.verifyHostname field and a separate #[serde(default)] top-level verify_hostname field.
• After deserialization, a post-parse normalization step should check whether the top-level field was explicitly set. If so, it logs a deprecation warning and copies the value into tls.verify_hostname only when the nested field was not also explicitly set.
• When both the top-level and nested fields are present, the nested tls.verifyHostname value wins. The top-level value is ignored after the warning.
• Do not rely on two competing #[serde(default)] fields resolving the conflict. Use a custom Deserialize impl or an explicit post-parse step.

Serde strategy for Java-compatible but unimplemented sections:

• Do not use #[serde(deny_unknown_fields)] for the top-level ClientConfig or OAuth section during Phase 1.
• Known but not-yet-implemented Java sections such as oauth.sign and oauth.deref should deserialize into typed structs or serde_json::Value placeholders so representative Java fixtures load successfully.
• Demand-driven validation decides whether a section is required. If no active module consumes oauth.sign or oauth.deref, those sections can be present and ignored silently.

Proposed Rust Modules

Shared Config Model

Create one shared typed config model outside light-pingora and light-runtime:

crates/light-client/src/lib.rs
crates/light-client/src/config.rs
crates/light-client/src/http.rs
crates/light-client/src/oauth.rs
crates/light-client/src/provider.rs

light-runtime should use light-client for loading, validating, and building outbound clients, but the reusable client model should not live inside the runtime crate.

Core types:

#![allow(unused)]
fn main() {
pub struct ClientConfig {
    pub tls: ClientTlsConfig,
    pub request: ClientRequestConfig,
    pub oauth: ClientOauthConfig,
    pub path_prefix_services: BTreeMap<String, String>,
}

pub struct ClientTlsConfig {
    pub verify_hostname: bool,
    pub ca_cert_path: Option<PathBuf>,
    pub client_cert_path: Option<PathBuf>,
    pub client_key_path: Option<PathBuf>,
    pub tls_version: Option<TlsVersion>,
}

pub struct ClientRequestConfig {
    pub connect_timeout_ms: u64,
    pub timeout_ms: u64,
    pub max_request_retry: u32,
    pub request_retry_delay_ms: u64,
    pub error_threshold: u32,
    pub reset_timeout_ms: u64,
    pub inject_caller_id: bool,
    pub enable_http2: bool,
    pub pool: ClientPoolConfig,
}
}

TlsVersion should be an enum with serde names for Java-compatible strings such as TLSv1.2 and TLSv1.3, rather than a raw string in runtime code.

Secrets should use a type that serializes as masked data for registry output, or the registry masks should cover every secret field recursively.

Runtime Loader

light-runtime should own the startup lifecycle for client.yml loading, but delegate parsing and validation to light-client:

1. Load local values.yml.
2. Load local startup.yml.
3. Load local client.yml with resolved values for config-server bootstrap.
4. Fetch remote config if configured.
5. Rebuild the final RuntimeConfig with the remote client.yml overlay.
6. Register masked light-client/client in ModuleRegistry.

Every runtime client should use this shared config:

• config-server fetch client
• portal-registry WebSocket client
• MCP client
• future model-provider outbound clients
• framework/application clients through RuntimeConfig.client

For the earlier hostname-verification bug, the controller client should read:

runtime_config.client.tls.verify_hostname

not a separate top-level ClientConfig.verify_hostname.

HTTP Client Factory

Add a small factory that converts ClientConfig plus optional per-endpoint overrides into concrete clients:

#![allow(unused)]
fn main() {
pub struct ClientFactory {
    config: Arc<ClientConfig>,
    direct_registry: DirectRegistryConfig,
    registry_client: Option<Arc<PortalRegistryClient>>,
}

pub struct EndpointOptions {
    pub server_url: Option<String>,
    pub service_id: Option<String>,
    pub proxy_host: Option<String>,
    pub proxy_port: Option<u16>,
    pub enable_http2: Option<bool>,
    pub timeout_ms: Option<u64>,
}
}

Responsibilities:

• Build reqwest::Client with consistent TLS, timeout, proxy, HTTP/2, retry, and pool settings for non-Pingora consumers.
• Build Pingora HttpPeer options from the same TLS config for gateway upstream proxying.
• Resolve endpoint base URL by priority:
  1. direct server_url
  2. direct-registry.yml
  3. portal-registry discovery by serviceId
• Apply per-service AuthServerConfig overrides without duplicating resolver logic in each handler.

The config-server bootstrap path still starts from BootstrapConfig because it needs enough client settings before remote client.yml has been fetched. To keep light-client independent from light-runtime, the factory should not take a BootstrapConfig type directly. Instead, light-runtime should adapt BootstrapConfig.connect_timeout, BootstrapConfig.timeout, authorization, and bootstrap CA path into EndpointOptions or a small bootstrap options type owned by light-client.

OAuth Client

Add a shared OAuth client module that implements Java http-client behavior:

oauth/client_credentials
oauth/authorization_code
oauth/refresh_token
oauth/token_exchange
oauth/key
oauth/sign
oauth/deref

The existing light-pingora SpaTokenClient, token handler client credentials code, and security JWKS fetcher should delegate to this shared module. Handler modules still own request-path decisions, cookies, headers, and rejection mapping.

OAuth provider selection should be one reusable resolver:

#![allow(unused)]
fn main() {
pub struct OAuthProviderResolver {
    client: Arc<ClientConfig>,
}

impl OAuthProviderResolver {
    pub fn service_for_path(&self, path: &str) -> Option<&str>;
    pub fn client_credentials_provider(&self, service_id: Option<&str>) -> Result<AuthServerConfig>;
    pub fn key_provider(&self, service_id: Option<&str>) -> Result<AuthServerConfig>;
}
}

Rules:

• Single-provider mode uses global oauth.token.* defaults.
• Multi-provider mode is enabled when oauth.multipleAuthServers: true or when relevant serviceIdAuthServers maps are non-empty.
• Multi-provider mode selects the service id from an explicit request header first, then outbound pathPrefixServices.
• client_credentials.serviceIdAuthServers[serviceId] selects the token provider.
• key.serviceIdAuthServers[serviceId] selects the JWKS/key provider.
• Per-service config inherits unset values from global oauth.token defaults.
• Path-prefix matching should be boundary-aware in Rust. Java uses startsWith; the Rust implementation can be stricter as an intentional improvement. Exact rule: a prefix matches when the request path equals the prefix or starts with prefix + "/". Therefore /api matches /api and /api/orders, but does not match /api-v2.
• pathPrefixServices is not an inbound routing table. It maps outbound request paths to service ids only for client-side OAuth provider selection.

Consumer Modules

All modules should consume the same shared config:

Reload Behavior

client.yml should be reloadable as a module, but reload must be conservative:

1. Load and validate the new config into a fresh ClientConfig.
2. Build new shared client factories and OAuth clients.
3. Swap the config atomically for future requests.
4. Clear OAuth token caches because client credentials, scopes, providers, or trust settings may have changed.
5. Keep old in-flight requests on their existing client instances.
6. Reject the reload if active modules cannot build required clients from the new config.

Reload atomicity: all runtimes that consume client.yml must be swapped together in the same reload callback. Today, the gateway TokenReloader already rebuilds token_runtime, stateless_auth, and msal_exchange as a unit. This must remain a hard requirement. A reload that updates the client config without also rebuilding dependent runtimes would leave stale TLS or OAuth state in the old runtime instances.

Controller registration is long-lived. Reloading client.yml should not force an immediate portal-registry reconnect. New TLS and request settings should apply to future outbound clients and the next normal controller reconnect, but the active controller WebSocket can remain open.

Validation Rules

Base validation:

• tls.verifyHostname: false requires explicit trust material unless the transport has a clear dev-only mode.
• If Rust-native mTLS is configured, both client certificate and client key paths are required.
• request.connectTimeout and request.timeout must be positive.
• proxyPort must be 0 to 65535.
• pathPrefixServices keys must start with /.
• Secret fields may be empty only when the consuming active module does not need that grant.

OAuth validation should be demand-driven:

• If token handler is active and enabled, validate client_credentials.
• If stateless-auth is active, validate authorization_code and refresh_token.
• If msal-exchange is active, validate token_exchange.
• If security.yml enables JWKS bootstrap from key service, validate oauth.token.key.
• If a future sign module is active, validate oauth.sign.
• If a future deref module is active, validate oauth.deref.

This avoids forcing every service to configure every Java OAuth section.

Validation failure behavior:

• At startup, validation failures are fatal. The process must exit with a clear error message identifying which active module requires which missing or invalid client config section.
• On reload, validation failures are non-fatal. The reload is rejected, the old config stays live, and the rejection reason is logged and reported through the module registry reload outcome.

Masking

Mask these fields recursively in registry output:

• client_secret
• clientSecret
• trustStorePass
• keyStorePass
• keyPass
• defaultCertPassword
• subjectToken
• access_token
• refresh_token
• id_token
• authorization
• any field ending in Token whose value is a scalar string (not a nested object, list, or URN-typed field like subjectTokenType or requestedTokenType)
• any field ending in Secret

Explicit exclusions from suffix matching:

• subjectTokenType - a URN string, not a secret.
• requestedTokenType - a URN string, not a secret.

The registry should store only the masked snapshot. It should not store raw config and mask later.

Migration Plan

Phase 0: Deprecation Logging

• Add a tracing::warn! in light-gateway where it reads resolved_values["client.verifyHostname"] to alert operators that this path is deprecated and will be replaced by runtime_config.client.tls.verify_hostname.
• This gives operators visibility into the migration before behavior changes.

Phase 1: Unify The Schema

• Add the light-client crate with the full shared ClientConfig type.
• Make light-runtime load nested tls.verifyHostname.
• Keep top-level verifyHostname as a temporary compatibility fallback.
• Update Rust config templates to include only the canonical nested shape.
• Add tests proving client.verifyHostname: false reaches config-server, portal-registry, token, security JWKS, SPA auth, and gateway proxy clients.

Phase 2: Move Consumers To Shared Config

• Replace light-pingora::token::ClientTokenConfig with the light-client shared type or a type alias.
• Replace gateway direct resolved_values["client.verifyHostname"] lookup with runtime_config.client.tls.verify_hostname.
• Move JWKS, token, and SPA token HTTP client construction behind the shared client factory.
• Register one masked light-client/client module instead of separate partial client registry entries.

Phase 3: Shared OAuth Provider Resolver

• Extract provider selection from the token handler.
• Support token.key.serviceIdAuthServers and audience.
• Use the same resolver for token injection and JWT key lookup.
• Keep Java field names and config-server placeholders.

Phase 4: Java Feature Completion

• Implemented sign client support in light-client.
• Implemented deref client support in light-client.
• Implemented Rust-native PEM mTLS for reqwest clients and Pingora upstreams.
• Implemented retry, circuit breaker, and pool behavior where the Rust transport supports them.

Open Questions

None at this stage.

Test Plan

Unit tests:

• Parse the Java client.yml template into the shared Rust config.
• Parse the current Rust client.yml template into the shared Rust config.
• Resolve client.verifyHostname into tls.verifyHostname.
• Accept top-level verifyHostname only as a fallback and prefer nested TLS when both are set.
• Mask every secret field in the module registry snapshot.
• Validate provider selection by service id and path prefix.
• Validate per-service override inheritance for token and key providers.

Runtime tests:

• Config-server bootstrap uses tls.verifyHostname.
• Portal-registry controller WebSocket uses tls.verifyHostname.
• Gateway upstream proxy uses tls.verifyHostname.
• Token handler, stateless auth, MSAL exchange, and security JWKS all receive the same ClientConfig instance or snapshot.
• Client reload clears token caches and rejects invalid active grant config.
• Reload round-trip: verify that reloading from config A to config B swaps the ClientConfig, creates fresh token caches, and that in-flight requests on the old config are not affected. Verify that a reload from valid config to invalid config is rejected and the old config stays live.

Compatibility tests:

• Reuse representative Java client.yml fixtures for single provider, multiple providers, proxy, token key, sign, and deref sections.
• Confirm Java-compatible form bodies for authorization_code, client_credentials, refresh_token, and token_exchange.
• Confirm config-server injected YAML strings and structured YAML maps both deserialize for serviceIdAuthServers and pathPrefixServices.

Embedded Configuration Templates

Status

Initial implementation completed. Rust applications in light-fabric and related portal-service applications keep template configuration files under each app's config directory. Container images may copy those files into /app/config-defaults, then runtime overlays local config, downloaded config-cache, remote values.yml, and environment variables.

That works well for container deployments. It is awkward for native binary deployments on a VM because the operator must copy a full template directory beside the binary even when they only want to provide values.yml, certs, or a small local override.

This design embeds the template files into the Rust binary while keeping the app config directories in source control as the readable template source.

Purpose

Embedded configuration templates should make the Rust deployment model match the Java module model more closely:

1. The application binary carries its default template files.
2. Operators provide only overrides, usually values.yml, startup.yml, certs, keys, or environment variables.
3. Config-server can still return values.yml after bootstrap, plus external files for explicit migration or operational exceptions.
4. Developers and operators can still inspect the app's config directory in source control to learn supported properties.

The embedded files are defaults. They are not runtime state and should not be written out automatically unless an explicit diagnostic/export command is added later.

Current Model

The current runtime model has these filesystem layers:

For light-fabric runtime applications, LightRuntimeBuilder passes default_config_dir, config_dir, and external_config_dir into light-runtime. load_bootstrap_config() reads bootstrap-time values.yml, startup.yml, and client.yml before remote config-server bootstrap. After remote bootstrap, runtime config loads server.yml, client.yml, portal-registry.yml, and framework/application module files through the same merged configuration path.

Some portal-service apps share the light-runtime path, while standalone apps such as config-server and light-oauth have local helper functions that merge config-defaults and config.

Goals

• Allow a native binary deployment to start with embedded templates and a small external config/values.yml.
• Keep apps/<app>/config/*.yml as the source of truth for template content.
• Keep container deployment behavior compatible with the current /app/config-defaults copy.
• Preserve the existing overlay order and placeholder expansion behavior.
• Support bootstrap-time files such as startup.yml and client.yml.
• Support runtime module files such as handler.yml, proxy.yml, model-provider.yml, provider configs, and product-specific files.
• Provide one reusable loading abstraction for light-fabric and portal-service instead of app-specific parsing logic.
• Avoid writing embedded templates to disk during normal startup.

Non-Goals

• Do not embed secrets, certificates, private keys, trust bundles, static web assets, or downloaded config-server files.
• Do not remove the source config directories. They remain the reviewable, documented template source.
• Do not make values.yml mandatory. Apps should keep current defaults where they are already valid.
• Do not make config-server responsible for delivering template files that are already part of the binary.
• Do not change the meaning of values.yml placeholders or environment variable expansion.

Proposed Layer Order

The new effective source order should be:

1. Embedded template file from the binary.
2. Filesystem default template from config-defaults, if present.
3. Local operator file from config.
4. External/cache file from config-cache, when runtime loading supports it.
5. Remote values.yml payload from config-server.
6. Environment variables during placeholder resolution.

This keeps existing container images compatible. If config-defaults exists, it can override the embedded template. That gives operators and image builders a transition path and a deliberate escape hatch for patched images.

For native binary deployment, config-defaults is simply absent and the binary falls back to embedded templates.

Structured config files and values.yml should use different overlay semantics: