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, use portal-config-loc. Its deployment script downloads released service and UI archives from the configured CDN.

1. Initialize Workspace

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

cd ~
mkdir -p lightapi
cd lightapi

# Clone the local deployment configuration
git clone [email protected]:lightapi/portal-config-loc.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

For a full deployment, deploy-local.sh downloads events.zip from the CDN and defaults IMPORT_EVENTS to auto. It imports the extracted events.json only when the event store is empty. Set IMPORT_EVENTS=force only when you intentionally need to replay the released baseline into a non-empty store.

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.

Why Rust

Light-Fabric is written in Rust. Not because Rust is fashionable, and not because the team enjoys fighting a borrow checker, but because the platform is built for a specific world: enterprise backend services and agentic workflows that are increasingly written by AI agents and verified by automated gates rather than read line-by-line by humans.

In that world the traditional trade-off — “Python is faster to write, Rust is faster to run” — no longer holds the way it did. The cost of writing code is collapsing. The cost of running it, trusting it, and operating it is not. This document explains the reasoning.

1. The premise has changed

The classic argument for Python and JavaScript on the backend was never really about the machine. It was about people:

• Fewer lines to type, so features ship faster.
• A larger hiring pool, so code is easier to staff and maintain.
• A shallower learning curve, so review and onboarding are cheap.

Every one of those advantages is a human throughput argument, and human throughput is exactly what stopped being the bottleneck. When a model writes the first draft, another model reviews it, and CI gates decide whether it merges, “how long does it take a developer to type this” is no longer the constraint worth optimizing. What remains is what the machine has to do afterwards, forever: execute it, pay for it, and not break in production at 3 a.m.

Rust wins on everything that is left.

2. The compiler is the cheapest reviewer we have

An AI agent is a probabilistic writer. It produces plausible code. The engineering question is not “will it make mistakes” — it will — but how early and how cheaply the mistakes are caught.

Light-Fabric’s quality pipeline has several gates: cargo build, clippy with warnings denied, unit and integration tests, contract/conformance suites, and a model-based review pass. They are not equally priced:

The compiler is the only gate that is free, total and deterministic. It does not sample, it does not get tired, and it does not need a test case to have been written in advance. In a dynamic language, every class of error the Rust compiler rejects outright must instead be caught by a test someone remembered to write or by a reviewer who happened to look — and in an agentic pipeline, both of those are paid for in tokens.

Rust’s type system also encodes decisions the platform actually cares about and that reviewers routinely miss:

• Result<T, E> makes every failure path explicit; an ignored error is a compile-time warning, not a silent production incident.
• Option<T> eliminates the null-dereference class entirely.
• Send/Sync and the borrow checker make data races across the thousands of concurrent agent sessions Light-Fabric runs unrepresentable, not merely “unlikely if the code is careful”.
• Exhaustive match means adding a new variant to an event, message or state enum forces every handler to be revisited. Across a workspace this large, that single property has caught more would-be regressions than any test suite.

This is the real answer to “if it compiles, it runs.” It is not that Rust code is bug-free. It is that a whole family of bugs cannot reach the tests, the reviewer, or production, so the expensive gates spend their budget on logic and design instead of on null checks and race conditions.

3. Verbosity is a one-time cost; runtime is a forever cost

The standard objection is the “token tax”: Rust is more verbose, so agents spend more tokens generating it. That was a real argument. It has weakened considerably, and it was always measured against the wrong denominator.

The generation cost is paid once per change. The runtime cost is paid on every request, in every environment, for the life of the service. Light-Fabric runs gateways, agent runtimes and workflow engines that sit on the hot path of every call in the fabric; the asymmetry is not close:

• Memory. Rust services hold a resident set measured in tens of megabytes, with no GC heap to size and no GC pause to tune. The equivalent JVM or Python service reserves an order of magnitude more before it serves a single request. On a per-pod basis in Kubernetes, that is the difference between packing dozens of services on a node and packing a handful.
• Latency tail. There is no stop-the-world collector, so p99 tracks p50 instead of spiking. For a gateway that fronts every LLM and MCP call, tail latency is the product.
• Startup. A statically linked binary is serving traffic in milliseconds. This is what makes scale-to-zero, fast rollouts, and short-lived sandboxed workers practical rather than theoretical.
• Footprint. A single self-contained binary with no runtime, no interpreter, and no dependency tree to install at deploy time. Containers are small, the attack surface is small, and the supply chain is one artifact.

There is also a second-order effect that matters specifically for an AI platform: compute spent on the runtime is compute not spent on inference. Every gigabyte and every core the control plane does not consume is budget available to the models the platform exists to serve.

4. Verbosity is also, increasingly, an illusion

Rust reads as verbose next to a Python one-liner, but the comparison usually omits what the Python one-liner postponed: the type annotations added later, the validation, the error handling, the test that exists only to catch a None, and the runtime guard for the concurrency case. Light-Fabric’s Rust states those up front, where the compiler can enforce them, instead of scattering them through tests and incident reports.

The asymmetry is also shrinking on the model side. Frontier models generate idiomatic Rust competently today, and the “compiler loop” failure — an agent thrashing against lifetime errors — is now mostly a symptom of poor architecture rather than of the language. In practice it is contained by the same design rules that make the code good for humans: prefer owned data and Arc at boundaries, keep lifetimes out of public APIs, keep functions small, and let clippy steer idiom. Where a module does provoke thrashing, that is a signal about the design, and a useful one.

5. Where Rust would be the wrong answer, and what we do instead

This is a considered choice, not a purity rule. Rust is the wrong tool in three places, and Light-Fabric does not pretend otherwise:

• The browser. The web is JavaScript and TypeScript. UIs for the portal and consoles belong there, and WASM does not change that.
• Glue, scripting and one-off automation. Build helpers, migration scripts, data wrangling and repo tooling are written in whatever is shortest — shell or Python. They are not on the hot path, they are not mission-critical, and compiling them buys nothing.
• The ML/data ecosystem. Where a mature Python library is the state of the art, the right move is to call it across a process or service boundary, not to reimplement it.

The rule is a boundary, not a language ban: anything on the request path, holding state, enforcing a security decision, or running unattended in production is Rust. Everything around it can be whatever is convenient. The platform is the compiled tier; the conveniences live outside it.

6. What this buys Light-Fabric concretely

The architecture depends on properties that are difficult or expensive to obtain elsewhere:

• Shared engines, many services. light-agent, light-agent-worker, light-agent-channel, light-gateway and light-workflow are thin trust-boundary executables over shared domain crates. Cargo’s workspace and the type system make that sharing safe: a contract change in a shared crate fails to compile in every consumer that has not been updated. See Agent Engine Pattern.
• Hot-reload without restarts. Configuration, rules and agent metadata swap under live traffic via arc-swap, with the type system guaranteeing readers never observe a torn state.
• Gateway-grade proxying. frameworks/light-pingora builds on Cloudflare’s Pingora, a proxy engine that exists in Rust because that class of workload cannot afford a garbage collector.
• Massive concurrency per instance. tokio lets one instance carry thousands of concurrent agent sessions and streaming LLM responses on a small footprint, with the borrow checker — not convention — preventing the races.
• Enterprise security posture. Memory-safety defects are the dominant class of exploitable vulnerability in C and C++ infrastructure, and the class Rust removes by construction. For software that terminates TLS, holds credentials and enforces authorization, that is a compliance argument as much as an engineering one.

7. The longer arc

The direction of travel is toward specifications and exit criteria as the real source of truth, with the implementation language demoted to an artifact of the build. Light-Fabric is already organized that way in places: the metadata-driven agent engine, the rule specification, and the workflow specification all describe what should happen, while Rust implements the engine that makes it happen safely and quickly.

If that arc completes and the implementation tier eventually becomes something lower-level still, the property being preserved is not “we write Rust” — it is machine-checkable correctness at the boundary between a probabilistic author and a deterministic machine. Today, Rust is the most practical, widely supported, production-proven form of that guarantee. It also happens to be the fastest and leanest option on the table, which makes the choice easy rather than merely defensible.

Summary

Human readability was the argument for dynamic languages, and human readability is the constraint that is going away. What remains is execution cost and verifiable correctness — and those are the two things Rust was built to win.

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.

HTTP routing and policy identity

Handler selection and HTTP ACL resolution are independent. A handler route such as /github/repos/* selects a shared chain; it does not become an ACL grant. The Gateway retains its routing endpoint for router rewrites, metrics, LLM routing policy, and evidence. The access-control handler uses the original URI path without the query and the original HTTP method, captured before header, path, or upstream method rewriting. Verified caller claims remain the rule input.

Ordinary HTTP policies resolve in this order:

1. An exact path for that method wins, including over templates.
2. A unique matching full-path {parameter} template wins over literal prefixes. Multiple matching templates deny, even if one has longer parameter names or more literals. Resolve overlap with an exact policy or disjoint templates.
3. Existing literal parent-path policies retain longest-prefix semantics, with a / boundary and the same method. They explicitly authorize descendants; default-deny cannot make an endpoint unknown beneath such a configured grant.
4. With no match, retain the concrete path@method identity and apply configured defaultDeny. No wildcard handler fallback supplies permission.

Methods compare case-insensitively; policies differing only in method case are ambiguous and deny. Ambiguity never falls back to a broader prefix or to defaultDeny: false. An exact policy resolves otherwise overlapping templates. Paths remain case-sensitive. Gateway preserves the received URI: routing uses legacy raw matching and forwarding retains punctuation, escapes, repeated and trailing slashes, apart from existing configured routing rewrites. There is no ingress rewrite or new path-signing requirement. Ordinary HTTP ACL lookup uses a separate policy identity: decode one level, validate UTF-8, retain URI segment characters, and use uppercase escapes for space/UTF-8 data. Encoded unreserved aliases select their stricter exact policy. A single trailing slash is equivalent for policy lookup only; the wire slash remains, preserving directory redirects and signed paths.

On a chain containing access-control, ambiguous separators, dot segments, malformed escapes, ASCII controls, invalid UTF-8, decoded percent signs and repeated slashes reject. Literal or encoded semicolons also reject on these chains: some upstream routers strip segment path parameters, which could let /api/private;x=1 miss an exact policy and select a broader prefix. This restriction includes semicolons intended as literal segment data. If raw routing would select an unprotected chain but an alias would select an ACL chain, a guard rejects before dispatch. Its conservative alias probe is never used for forwarding or handler selection; it honors route order and recognizes separators, double encoding, segment parameters and dot collapse. Parameter stripping is only a denial probe; raw unprotected paths such as /x/;jsessionid=... remain unchanged unless their alias crosses an ACL boundary. Protected route patterns and base paths are validated and compiled once at load/reload; invalid candidates fail with diagnostics and retain the active runtime. Unprotected patterns are not canonicalized or silently dropped. An explicitly spelled unprotected alias route (for example /open%2Fprivate) fails load/reload if its alias overlaps a protected route or default chain without earlier complete unprotected coverage. Validation respects methods, route order, base paths, segment templates and terminal wildcards; partial unprotected coverage is conservatively insufficient. Use an unambiguous route spelling or explicitly protect the route, retaining endpoint-specific ACL policies. Do not broaden grants to silence this diagnostic. Rejected reloads retain the active handler set and pinned requests. Dynamic aliases in ordinary template/wildcard captures remain guarded at request time. Normal route matching performs no per-pattern canonicalization.

Spaces and UTF-8 remain supported in ACL-protected segment data. Queries are unchanged. Direct /branches/feature%2Ftopic remains restricted on an ACL chain, because upstream separator/data interpretation is not uniform. An applicable query ref is unchanged; it does not make the direct branch endpoint supported. Unprotected %2F, %25 and repeated slashes retain legacy behavior unless an alias would cross into an ACL chain. HMAC sees the original request path.

The legacy /@method policy matches the root itself; it does not implicitly grant all descendants. A non-root trailing slash selects its canonical policy. skipPathPrefixes is checked against the canonical concrete identity and the selected policy, and disabled/skipped ACLs retain their shared request/response gates.

The selected endpoint key and immutable ACL runtime generation are retained for request authorization and response filtering. Ordinary body-bearing proxy/router requests are bounded and authorized before upstream dispatch, then replayed through Pingora’s existing prebuffered-body hook. Earlier tokenization is applied once before authorization, as in the former body-filter path. Portal command/query envelope decoding, MCP tool identities, A2A policy identities, and the MCP/LLM-owned body authorization paths keep their protocol-specific behavior.

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.

Ordinary HTTP capture and chain compatibility

Wildcard handler routes (including /github/repos/* for every method) are independent of ACL keys and remain supported. Wildcard ordinary HTTP ACL keys containing * are unsupported: startup/reload rejects them with a migration diagnostic under both default-deny modes. Migrate ACL rules to exact paths, full-path templates, or deliberate literal-prefix policies; do not change wildcard handler routing or broaden grants. A rejected reload retains the valid active ACL runtime. Already admitted requests retain their selected key and runtime for both authorization and response filtering across a valid reload.

access-control.yml has two explicit capture settings, independent of HMAC, LLM, and tokenizer configuration:

bodyReadTimeoutMillis: 10000
maxBufferedBodyBytes: 268435456

Both must be positive. Ordinary HTTP ACL retains its 10 MiB per-body limit. Declared lengths reject before allocation/interim responses; streamed bytes remain bounded. The deadline covers the entire body read, including writing 100 Continue. An aggregate permit accounts for retained payload bytes and is released with request ownership on completion, denial, failure, timeout, or cancellation. HMAC-captured originals keep their existing HMAC permit; shared Bytes avoid a second original-body allocation. ACL-transform output reserves its configured tokenizer maximum (capped by the ACL limit) before tokenization, then reduces its charge to actual retained output. Budget exhaustion returns 503, size excess 413, and read timeout 408. These payload quotas are not a process-RSS bound: protocol chunks, allocator slack, JSON parsing/serialization, and token-vault operations have separate resource costs. The capture deadline does not bound token-vault database operations or rule evaluation.

Supported body chains authenticate first, run tokenize before access-control, and dispatch only after authorization. HMAC (standalone or through unified-security/unified) authenticates original bytes before ACL capture; ACL observes tokenized bytes and upstream receives the cached transformation once. Downstream framing is preserved until capture; transformed upstream framing is updated independently. Detokenization requests uncompressed upstream responses even when ACL has already authorized the body. Empty-body DELETE remains valid. HMAC checks signature/selector/delivery-header syntax before body capture but validates the MAC only over original captured bytes.

Startup and handler/security reload reject tokenizer-after-body-capturing-ACL, recognized-security-gate-after-ACL, or tokenizer-before-HMAC/unified orders with precise order diagnostics. jwt is a security alias. Existing HMAC validation also rejects duplicate entry points or simultaneous standalone HMAC and unified security on the same effective chain. The recognized gates are hmac, security, jwt, unified-security and unified; this is not a validator of all authentication handlers (such as stateless, token, Basic or API-key). GET/HEAD ACL evaluates query/header data and does not require tokenizer-before-ACL; other gates and original-byte HMAC order still apply. Wildcard-method routes remain unsupported by handler configuration loading; the body-order helper treats a wildcard conservatively when called directly. HMAC terminal chains remain router-only. The shared MCP/A2A matcher is unchanged.

Deferred tokenization uses chunked HTTP/1.1 upstream framing or HTTP/2 DATA frames, selected from the actual negotiated protocol, not its configuration preference. Known empty bodies retain length zero; preauthorized transformed bodies retain their exact length. Deferred transformation over HTTP/1.0 is unsupported and fails explicitly.

The 10-second capture deadline is total elapsed read time, unlike an idle timeout that resets after every chunk. Slow uploads that previously progressed indefinitely can now receive 408. The ACL body ceiling remains 10 MiB; the tokenizer default is 1 MiB. Owners should explicitly select a total deadline for supported upload sizes and minimum acceptable throughput before rollout, without changing unrelated proxy idle settings. Reserving a full tokenizer output maximum under the default 256 MiB budget reduces concurrent upload capacity: each original plus its maximum output is charged until transformation completes. This conservative reservation also accounts for originals shared from HMAC through its independent budget; the combined budgets are not one process-wide memory ceiling.

Local regression commands (no live requests):

rtk cargo test -p light-gateway http_acl -- --test-threads=2
rtk cargo test -p light-pingora --lib http_policy -- --test-threads=2
rtk cargo test -p light-pingora --lib capture_headers -- --test-threads=2
rtk cargo test -p light-gateway -- --test-threads=2
rtk cargo test -p light-pingora --lib -- --test-threads=2

The cache-only composition fixture is enabled by a development-only test-support dependency. It uses seeded token-cache entries and a disconnected pool, exercises production Gateway/tokenizer methods, and does not qualify a PostgreSQL vault or any deployed runtime. Recorder finish requires stopped producers, drains a nonblocking OS listener through WouldBlock, and joins every accepted worker. A pending asynchronous accept is never treated as queue proof.

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 current Hindsight tables are integrated into the Portal-era multi-tenant schema. In the target architecture, immutable memory policy and hard directives are published through Config Server, while concrete banks, memory content, session history, provenance, reflection, and erasure state are owned by a tenant operational Memory API and store. See Control Plane And Operational Data.

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.

User, Application, And Workflow Authorization

Historical design baseline. The A1 credential broker described below was retired by Workflow Invoke. Its browser callback and backend enrollment routes are no longer part of Workflow. For the current Gateway-to-Workflow user-token contract, see Workflow Invoke. The A1 qualification report and its activation receipt preserve historical evidence.

Historical status: accepted design, September 13, 2026. The A0 contract baseline v1 records the then-selected issuer profiles, contracts and migration inventory. A1–A3 qualification was pending at that checkpoint. This design was a foundation for issue #374 and the subsequent orchestration work. The unattended grant and renewal contract below was superseded by Workflow Invoke; its historical qualification claims do not describe the current deployment.

Scope And Related Designs

Cover user and immediate-caller identity at API/MCP and Resource/Knowledge boundaries, original-token forwarding, scheduled and long-running execution, credential renewal, revocation, and replacement of workflow-issued lad1 delegation tokens. Apply the same contracts to personal and enterprise profiles.

LLM User and Agent Authorization covers interactive model calls and explicitly excludes unattended delegation. Its user/workload separation, model assignments, billing principal, and alias restrictions remain applicable. Access Control and Fine-Grained Authorization provide the existing policy context; this design does not introduce a parallel role or ACL system.

The personal and enterprise orchestration designs own feature stages, reviews, budgets, and publication. Their grant references and reauthorization transitions depend on this design. Enterprise execution envelopes and accounting receipts remain separate from the user and app credentials specified here.

Decisions

1. Preserve the original user access token in Authorization during an interactive call chain within explicitly approved forwarding destinations, where issuer audience and sender-binding rules permit. The local issuer’s shared audience does not by itself approve a destination or calling app. Evaluate trusted uid, role, grp, pos, att, and other policy claims.
2. Put the immediate caller’s independently verified app credential in X-Scope-Token. Every forwarding component supplies its own app token.
3. A valid user token does not bypass an endpoint’s allowed-caller policy. Gateway-only API/MCP endpoints reject direct agent, workflow, and test-tool calls unless a separate route profile explicitly authorizes them.
4. Obtain fresh short-lived user credentials under a renewable, revocable grant for unattended work. The original expired JWT cannot remain the credential. Preserve the authenticated user identity and approved authority, not the original token bytes indefinitely.
5. The OAuth issuer issues credentials. Workflow must not extend expiry, disable expiry checks, sign copied user claims itself, or substitute a service account when user authorization expires. Keep the issuer’s auth_refresh_token_t records and rotation, but load current user status and authorization claims on every refresh; saved claims are not continuing permission authority.
6. Separate credential replay protection, request authorization, and durable effect idempotency. Removing lad1 must preserve or explicitly replace its request binding, replay, and workflow-permit protections.

Historical implementation boundary (2026-09-13)

Source inspected September 13, 2026. These are source observations, not a claim that current deployment settings or external identity providers are qualified.

Inventory each affected API/MCP/Knowledge route before rollout. Existing support at Workflow ingress or the LLM gateway does not prove every resource verifies both identities or enforces a gateway-only caller policy.

Supported Issuer Grants And Token Profiles

Trusted-client custom claims remain supported for specialized integrations. Registered application metadata is owned by client administration; mutable user permissions are owned by their authoritative identity/policy source. Claims used for authorization need an explicit owner and update rule even when custom claims are uncommon. Do not require all application metadata to come from user tables, or let it silently override current user permissions.

client_authenticated_user remains a specialized issuer-approved assertion grant. It is not used by the proposed Workflow broker and is not a fallback for expired, revoked, or missing user authorization. long_lived remains supported for app credentials in X-Scope-Token. Its custom uid/role/grp/pos/att fields do not convert an app token into a user session or a WorkflowGrant.

For the unattended profile, the issuer restricts the broker client to its approved enrollment and refresh grants. Workflow enrollment verifies grant provenance through issuer-owned grant/session metadata, including grant type, eligible client, subject/tenant, and consent. An ordinary signed JWT with a uid is insufficient enrollment evidence. Build and qualify this metadata lookup with the issuer in A1; the current handlers do not provide this contract. Specialized clients retain their separately approved use cases; disabling those features across the platform is not a prerequisite.

User and app verification profiles must be distinguishable using issuer-owned token-purpose/key-purpose metadata or a qualified issuer lookup. Header position, token lifetime, or the presence of uid alone is insufficient. Reject app credentials presented as user credentials, including long-lived tokens carrying user-like custom claims. These rules prevent substitution without removing trusted-client customization. JWT validation profiles

The local A0 profile selects issuer-signed token_use=user|app, reserved against custom-claim overrides, with A1 issuance and shared verifier implementation. The A0 purpose contract defines grant mapping and the app-only legacy long-lived key-purpose exception. User purpose does not replace issuer provenance checks for Workflow enrollment.

User And Immediate Caller Identity

Each receiver validates signature, issuer, audience, expiry, and applicable host/environment constraints independently for both tokens. Bind identities to trusted issuer and tenant context; a bare uid from different issuers is not a globally unique identity. Normalize claims through configured issuer mappings. Never merge app roles into the user’s claims or accept unsigned identity headers.

Keep three concepts distinct: the application that obtained the login token, the workload authorized to act for the user, and the immediate calling service. The login JWT’s client_id does not establish the immediate caller. A trusted service registration maps app-token identity, including the existing sid where applicable, to the route’s allowed callers.

If a delegated JWT uses the RFC 8693 act claim, validate the current actor under that issuer’s profile; prior actor history is audit information. It does not replace authentication of the immediate hop. A profile that binds the user token to a particular sender may require another issuer exchange before a different service forwards it.

For gateway-only MCP access, both conditions are required: the current user may call the tool, and the authenticated app is an allowed gateway. The gateway evaluates the selected tool and request against existing fine-grained policy. The resource still enforces its user/resource ACL and caller restriction. Possession of a valid gateway token does not mean every user request is permitted.

Service-to-service forwarding replaces client-supplied scope headers with the forwarder’s own credential. Reject duplicate/malformed credentials and do not fall back from failed app authentication to user-only authentication. Direct interactive ingress uses its own explicit profile; a browser receives no gateway app secret to satisfy a downstream gateway-only rule.

Credential-Based Agent Execution Origin

For the initial profile, deploy separate interactive and workflow Agent service instances using the same binary but distinct app registrations, scope tokens, mTLS identities, and secret mounts. The workflow instance cannot access the interactive instance’s credentials. Trusted admission selects the instance; prompts, request headers, and tool arguments cannot select the credential profile. The interactive instance accepts the approved Chat ingress and rejects Workflow dispatch callers; it cannot provide a second route for running workflow jobs.

Gateway classifies the verified issuer/client identity through an administrator- owned registration mapping, checking its mTLS peer binding. Calls from Workflow or the workflow Agent registration always require an active action reference, including model, API/MCP, and Knowledge calls. Missing or invalid references deny the request even on an interactive URL. Root interactive admission accepts only its allowed registrations and ingress profile. Rewriting a mode header or path cannot turn a workflow credential into an interactive one.

The same verified app identity cannot be registered in both profiles in this pilot. A shared Agent runtime that holds both credentials and chooses between them from caller input is not qualified. A future shared-runtime design needs an independently verified job binding; it is not required for the pilot.

Gateway-Only Transport And App Credential Lifetime

A bearer token proves possession, not the physical origin of a request. Enforce the gateway-only boundary with backend ingress restrictions and authenticated service transport. The target profile uses mTLS, binding the allowed gateway workload to its peer identity and, where supported, certificate-bound app access tokens. A copied bearer alone must not allow an unapproved peer to impersonate the gateway. Any weaker rollout profile must state its residual replay exposure. Check that the authenticated peer maps to the same registered app as the scope token; accepting any certificate from the platform CA is insufficient. At a TLS terminator, propagate peer identity only through an authenticated internal path that strips externally supplied certificate/identity headers.

Use distinct app registrations and credentials for Gateway, Workflow, Agent, and authorized test clients. The personal/local-issuer profile supports existing long-lived app tokens with mTLS and app/peer binding. Short-lived client_credentials tokens are an optional alternative; migrating to them is not a prerequisite. Long-lived tokens still require expiry validation and an operational revocation/replacement path. Keep official-environment tokens and client keys/secrets in protected runtime configuration.

Checked-in app tokens and certificates may remain deliberate local-development fixtures so developers can start the stack without repeated credential setup. Treat them as public credentials: official environments must use independent keys/credentials and reject development fixtures. Native workers and test tools use their own registered identities; sharing a fixture gateway identity is not proof that gateway-only authentication has been qualified.

Shared Audience And Forwarding Destinations

The local issuer intentionally uses a shared platform audience because a user token traverses multiple services. Keep that audience and validate it at every receiver. Qualify a bounded set of trusted services for original-user-token forwarding through an administrator-controlled route/credential policy; an audience match or MCP registration alone does not enroll a recipient.

That policy binds each destination’s service identity and allowed origin/path to its credential profile. A demo or third-party MCP server does not receive the platform user bearer merely because it is behind Gateway. For destinations outside the approved set, use their own authorization flow or an issuer-qualified resource-specific exchange. The current local user-token grants do not provide that exchange; block user-token forwarding until an appropriate profile exists. Do not replace the missing profile with a service account and copied user claims.

Forward user tokens only to trusted configured destinations accepted by their issuer/audience and sender-binding rules. Do not disable audience validation or follow credential-bearing redirects to make forwarding work. Every recipient in the shared audience still enforces user policy and allowed-caller rules. A compromised approved recipient can expose a broadly usable user bearer; mTLS/app checks reduce where it can be replayed but do not make that bearer resource-specific. This is an explicit trust-domain tradeoff, not proof of isolation between every platform service. OAuth audience restrictions

Grant Ownership And Credential Storage

Use a trusted Workflow credential broker to mediate unattended user renewal. For the first implementation it is a module hosted by light-workflow, using shared OAuth client/provider code; it does not require a new deployed service. It is separate from model prompts, native worker execution, ordinary workflow inputs, and the artifact store. The OAuth issuer remains the token authority.

A WorkflowGrant records its ID/generation, verified subject and issuer mapping, host, authorized backend client, workflow definition/version or approved schedule, allowed targets/resources/actions, authorization ceiling, consent evidence, validity period, revocation state, and opaque renewal-credential reference. These are proposed schema fields, not existing configuration keys.

Store refresh credentials in a dedicated encrypted credential store controlled by the broker; keep encryption keys outside workflow definitions and ordinary database rows. Persist only references and authorization metadata in workflow state. Neither a grant ID nor a workflow ID is bearer authority: broker access requires an authenticated allowed workload bound to that grant and execution.

Access tokens may be cached briefly in trusted service memory. Keep all reusable credentials out of prompts, conversations, review artifacts, issue comments, logs, and ordinary task results. Audit subject/app/grant/action identifiers, policy decisions, generations, and failure reasons without token bytes.

Interactive, Scheduled, And Long-Running Execution

Interactive execution may forward a currently valid original token. If it expires without an unattended grant, require authenticated renewal or pause. Do not turn a normal interactive login into unlimited background authority.

For unattended user-authorized work:

1. While the user is present, obtain authorization for a bounded workflow or schedule. Use an approved confidential backend OAuth client to establish a renewable grant. Preserve the user’s identity and issuer-approved claims.
2. Prefer an issuer-qualified token exchange profile that can issue a renewable grant for offline use. If the issuer instead requires a backend authorization code flow, complete that flow for the backend client. Do not copy a refresh token issued to the SPA into an unrelated client’s credential store.
3. At a scheduled start, create the run bound to the grant and check its current status, generation, scope, and deadline. Acquire a fresh short-lived user token before dispatching protected calls; the old browser token is unnecessary.
4. During execution, obtain or reuse a sufficiently fresh token for each target. Attach the immediate service’s own app token and apply current authorization and the run’s approved ceiling before every protected action.
5. On one-off completion/cancellation, disable further use of that run’s grant binding. An approved recurring schedule may retain its parent grant until expiry/revocation; each scheduled run has separate execution/action identities.

sequenceDiagram
    participant U as User
    participant W as Workflow and credential broker
    participant O as OAuth issuer
    participant G as light-gateway
    participant R as API or MCP resource
    U->>W: Authorize bounded workflow or schedule
    W->>O: Establish approved renewable user grant
    O-->>W: Backend-bound renewal credential
    Note over W,O: Later, the original access token has expired
    W->>O: Redeem active grant with issuer-verified mTLS client authentication
    O-->>W: Fresh short-lived user access token
    W->>G: User token plus Workflow app token and action reference
    G->>G: Validate identities, destination profile, and tool policy
    G->>W: Fixed action-decision API with Gateway identity and user token
    W->>W: Check live grant, run, dependency, and budget; claim dispatch
    W-->>G: Bound decision, pinned target, depth, and dispatch lease
    G->>G: Validate decision binding
    G->>W: Begin dispatch for the same attempt and decision
    W->>W: Recheck authority and atomically persist send intent
    W-->>G: Acknowledge newly recorded send intent
    G->>G: Acquire connection, complete TLS, and obtain required capacity
    G->>G: Atomically check deadline and transition send guard at write boundary
    alt Deadline valid and send guard acquired
        G->>R: Accepted user token plus Gateway app token
        R->>R: Validate caller and user/resource authorization
        R-->>G: Result
        G-->>W: Result and action evidence
    else Deadline elapsed and request never initiated
        G->>G: Atomically close send guard
        G->>W: complete(NOT_INITIATED) for the same owner and generation
        W->>W: Record outcome and release unused reservation
        W-->>G: Safe to seek fresh authorization under retry policy
    end

The final forwarding edge assumes an approved forwarding destination and a valid token for that resource. A required external-resource exchange must be qualified before enabling that route. The action-decision callback is the internal service operation defined below, not another workflow or MCP dispatch.

An organization-owned schedule may instead run under an explicitly authorized service identity and its own permissions. Record the human creator for audit, but do not fabricate their uid or impersonate an administrator. The execution mode is fixed at authorization time; expiry cannot switch modes automatically.

RFC 8693 defines token exchange and permits refresh tokens for offline cases, but does not require issuers to provide them. A one-time exchange into another short-lived token is not an unattended renewal strategy. Issuer support for this profile must be qualified before enabling scheduled user execution. RFC 8693, section 2.2.1

Refresh-Token Claims And Authorization Freshness

Keep auth_refresh_token_t and refresh-token rotation. Change the source of authorization claims when issuing a refreshed access token: query current authoritative user status and permissions instead of treating the stored snapshot as current authority. The record remains necessary to validate the renewal credential, bind it to its user/client/provider/tenant and session, preserve the approved grant scope, and support rotation and revocation. This issuer-side record is separate from the Workflow broker’s protected store of client-held renewal credentials.

Current Issuer Behavior

In portal-service, the normal username/password authorization-code login already queries the database. portal-core::login_user_by_email assembles roles, groups, positions, and attributes from user and relationship tables. light-oauth::post_code copies these values into the authorization-code record; handle_authorization_code then copies them into auth_refresh_token_t. Creating that refresh record uses the code’s snapshot without another live permission query.

On refresh, get_refresh_token_detail reads the refresh record, and issue_access_token_from_refresh_token builds the access token from its saved roles and other claims. handle_refresh_token copies those fields into the replacement record. replace_refresh_token inserts the replacement, deletes the old record using its aggregate version, and writes session/audit updates in one transaction. Rotation therefore changes the credential, not the freshness of the permission data.

The issuer also has a configurable duplicate-retry grace path: find_recent_refresh_token_rotation can resolve a recently consumed token to its replacement, and the same issuance helper mints another access token from that replacement’s claims and returns the live replacement refresh token. Client authentication happens first, so possession of the old token alone is not sufficient for a confidential client. However, a presenter able to authenticate as that client can follow the rotation within the grace window. Rechecking claims does not restore theft detection. Retained interactive grace profiles need current authorization checks; unattended grants use the strict profile below.

A removed role can consequently survive repeated refreshes unless another mechanism revokes the session or grant. The exposure can last for the renewable session’s lifetime, not just one access token’s lifetime.

Alternatives And Tradeoffs

Start with live claims on each refresh. Refresh already reads and writes the database; the incremental cost is resolving the current authorization context, not introducing the first database call. This occurs at renewal, not on every API request. Measure query cost before adding a versioned cache. Explicit session/grant revocation remains available alongside the live-query approach.

Required Refresh Behavior

1. Authenticate the OAuth client and validate the refresh credential’s client/provider, subject/tenant, session/grant status, lifetime, and applicable sender binding. A successful credential lookup alone is insufficient.
2. Load current account status and authorization context using the verified issuer/provider mapping and the record’s stable user_id and host_id. Reject disabled, locked, removed, or otherwise ineligible users and invalid tenant memberships. Resolve currently effective roles, groups, positions, attributes, and other policy-bearing claims from their authoritative sources.
3. Issue a short-lived access token with that verified identity and current claims, constrained by current client policy and the existing OAuth grant. A refresh request cannot expand the originally granted scopes. Keep the workflow’s approved tools/resources/actions as a separate ceiling: newly acquired user permissions do not expand an already approved workflow. RFC 6749, section 6
4. On normal refresh, atomically persist the replacement credential, consume the old one, and record the rotation/session audit before returning success. Preserve grant bindings and revocation semantics across generations. If claims columns remain, populate the replacement with the current snapshot; do not copy old permission values forward as authority.
5. If a separately qualified interactive profile permits duplicate retries, recheck current status and claims before minting against the replacement. Never enter that grace path for an unattended grant. Neither profile may restore removed permissions or revive a revoked session.
6. If the authoritative status/claims source is unavailable, fail renewal with an appropriate retryable outcome; do not fall back to saved permissions. Coordinate this with the broker’s bounded retry and expiry behavior below.

The implementation needs a dedicated tenant-bound authorization-context query. The existing get_user_by_id returns NULL for roles, groups, positions, and attributes, and selects the user’s currently chosen host. Reusing it would not load the required claims. Nor should refresh simply call the email login query: switching the user’s current Portal host must not move an existing grant to a different tenant. Apply the relevant account, membership, and relationship eligibility rules explicitly.

Classify stored claims during migration. Immutable grant bindings and approved scope remain authoritative grant data; mutable permission claims must be reloaded. Policy-bearing values in custom_claim need the same treatment as role, grp, pos, and att. Existing snapshot columns may remain for compatibility or controlled historical use, but renewal must not authorize from them. Dropping the table or its claim columns is not required for this change.

For third-party identities, the live source may be the external issuer, an approved federation service, or a qualified synchronized authorization store. Portal’s database is authoritative only for claims it actually owns. Qualify provider mappings, account-status checks, and any synchronization delay before enabling unattended renewal.

Strict Rotation For Unattended Grants

The initial Workflow broker profile uses confidential-client authentication bound to its registered mTLS workload/key, one-time refresh rotation, and no replacement-token recovery through a consumed token. The issuer selects this policy from protected client/grant metadata, including retained consumed-token history; request parameters cannot opt into an interactive grace profile. Per-client/grant selection is new A1 work, not an existing override of the global refreshTokenRotationGraceSeconds setting.

Implement issuer-side OAuth tls_client_auth for the broker, not just mTLS between Workflow and Gateway. The initial local-issuer profile terminates TLS at a dedicated light-oauth broker listener, validates the client certificate chain and validity, and passes verified peer identity to the handler through server request context. Match the certificate’s registered subject/SAN to the client/provider/tenant and enforce the configured certificate revocation policy. Do not accept certificate identity from caller-supplied HTTP headers. OAuth mTLS client authentication

Persist the broker client’s authentication method and certificate identity in issuer-controlled registration metadata. Every broker token, grant-lookup, and revocation operation requires that method. A correct client secret without the registered certificate fails, including at legacy token URLs; there is no secret-only fallback for this client. Other clients retain their configured authentication methods. A1 includes listener/trust configuration, handler peer identity plumbing, registration/schema publication, broker certificate/key loading, and certificate renewal/revocation qualification. This client authentication requirement does not automatically bind the forwarded user access token to the broker’s certificate; access-token sender binding is a separate issuer profile.

This protects against theft of the refresh token and client secret without the mTLS key. Full host compromise can still use or steal a software-held key; profiles requiring protection against key export need an isolated or non-exportable key facility. Do not claim that mTLS alone prevents that attack.

Keep enough family/session and consumed-token history to detect reuse across rotations. An authenticated replay by the bound client returns invalid_grant, revokes the affected refresh family, and records the event without returning its live replacement. An unauthenticated or wrong-client request cannot obtain replacement credentials or revoke another client’s family. Continue checking current user authority on every successful refresh. Rotation and sender binding serve complementary purposes. Refresh-token protection

The broker serializes renewal across replicas and durably records the attempt and credential generation. If a response is lost after possible issuer commit, or the broker crashes before saving the replacement, mark the credential state uncertain, fence its use, and require reauthorization for the initial profile. Revoke the uncertain family through an authenticated issuer operation. Do not retry the old token or create a new grant automatically. Retry is safe only when the issuer contract or transport establishes that no rotation occurred. For the local provider, a connection-establishment failure (is_connect) or a JWKS failure before the token POST is NOT_SENT. Only the same live renewal owner/boot, attempt and generation may atomically restore an unrevoked grant to ACTIVE, preserving its encrypted token and recording that outcome. Lost owner proof, post-send failures and crashes still use the uncertain path. An HTTP error response alone does not prove no commit.

Fetch/cache verification keys before rotating (five-minute cache lifetime), with one refetch for an unknown signing key ID. Publish new issuer keys before use. A failed refetch or invalid token after rotation remains uncertain. Recovery store errors are logged and retried on the next periodic tick; they must not close admission for unrelated workflows. Configuration errors remain startup failures. Save a valid rotation for its shared grant even if its requesting run was canceled, then deny that run the access token. Grant revocation and expired renewal ownership still prevent saving the rotation.

The retired enrollment API accepted an optional credentialBroker.legacyLongLivedAppKeys list of approved issuer/key-ID pairs, default empty. This permitted only the A0 local long-lived app fixtures in X-Scope-Token; signatures, expiry, caller service identity and explicit purpose markers remained enforced. It never relaxed Authorization. This setting and enrollment API are no longer deployed.

A future recovery protocol must bind a durable refresh operation and its result to the original authenticated sender/key, recheck current grant state, and prevent a consumed token from retrieving its successor by itself. It requires separate qualification; an idempotency key or a time-based grace window alone does not supply that proof.

Permission Freshness, Revocation, And Recovery

Authorization requires all applicable checks: current user policy/ACL, allowed calling app, the approved grant/run ceiling, and the current action permit and budget. Newly acquired roles cannot silently widen the approved workflow. Removed roles, disabled accounts, and revoked grants must stop or narrow future actions according to current policy.

The live refresh query changes future tokens; it does not rewrite or invalidate an already issued access token. A resource that only checks a self-contained JWT may continue accepting its old claims until expiry. Earlier enforcement requires a current policy/status, authorization-version, revocation, or introspection check at the authorization boundary. A policy check using only the old JWT’s attributes cannot discover changed user membership. State the maximum enforcement delay for each qualified profile, including changes racing with token issuance; refresh-time checks alone are not immediate revocation. RFC 7009, section 3

Workflow and Gateway check current grant/run/action state before dispatching workflow-originated protected calls. Do not trust a caller-supplied invocation ID without checking the actor, tenant, target, request binding, and generation. For the initial unattended profile, failure to establish current grant authority blocks new dispatch. Any later caching profile must specify its maximum revocation delay; a self-contained JWT alone cannot prove immediate revocation.

Changes to stable user claims require authorization re-evaluation against the accepted disclosure ceiling. The current status API’s exact claims-digest check is not a general renewal protocol. Reauthorization records a verified new binding and decision; it cannot silently rewrite accepted inputs or reset workflow budgets, action identities, or review state.

Renewal is single-flight per credential generation, including across Workflow replicas. Persist replacement credentials atomically with their generation. A lost response during refresh-token rotation is uncertain credential state: the initial unattended profile requires reauthorization as specified above. Transient failures known not to have rotated the credential may retry within bounded limits while credentials remain valid. After expiry, or when the grant is fenced/revoked, stop protected dispatch and enter REAUTHORIZATION_REQUIRED or an explicit retryable wait appropriate to the failure.

Reauthorization requires the same verified user/tenant and the necessary current grant. Grant revocation does not become permission to auto-create a new one. Unknown in-flight effects remain fenced and reconciled; renewed credentials must not replay those effects under a new attempt identity. Local saved work can remain recoverable while new model/tool/API actions wait for authorization.

Replay, Action Authorization, And Accounting

Short token lifetime limits exposure but does not stop a stolen bearer from being reused before expiry. Use protected transport, sender-constrained tokens where supported, and client-bound renewal credentials with appropriate rotation. OAuth Security BCP and certificate-bound access tokens describe those credential protections.

Separately, persist each workflow action’s identity and request digest, bound to the host, subject, app, invocation, target, and fencing/budget generations. Gateway validates an active server-owned action permit and records permit/deny with its policy/permit version and reason. Authentication success is not an authorization decision. A request reference selects state; it does not grant authority by itself.

For effects, an identical retry reconciles the recorded result or uncertain execution; the same action identity with a different request digest fails. Changing a client-supplied idempotency key cannot allocate an additional authorized workflow attempt or budget. Revalidate access before disclosing a cached result. Do not mark the user access token itself as consumed after one request: it can legitimately authorize several calls.

Keep invocation depth/class, policy and response ceilings, action reservations, budget ledger/generation, and live cancellation state in authoritative workflow records or separately qualified execution envelopes. Do not clone them into user tokens as mutable authorization truth. Gateway must resolve or validate them at decision time when replacing the current delegation verifier.

Gateway To Workflow Action Decisions

Implement fixed internal HTTP operations in light-workflow, proposed as POST /internal/workflow/actions/authorize, .../begin-dispatch, .../complete, and .../status, with a trusted Gateway client. These are service operations, not model-visible tools, workflow definitions, or calls routed back through Gateway. Workflow owns the state and transactions; Gateway receives bounded results and needs no direct database credentials.

Before outbound dispatch, Workflow reserves an action against the admitted run and its pinned dependency/budget records. Calls carry an opaque action reference alongside the user and immediate-app tokens. Workflow and workflow-bound Agent registrations require this reference, using the credential-based origin rules above. Omitting it must not reclassify the request as a root interactive call.

Gateway validates the incoming user and app credentials, app/peer binding, destination profile, and tool policy, then calls the fixed operation directly over authenticated service transport. It sends the current user token in Authorization and its own app token in X-Scope-Token; Workflow verifies both and requires an allowed Gateway peer matching that app. This internal caller profile permits only these fixed control operations, not arbitrary bypass of Gateway-protected business APIs.

The request includes the action reference, invocation/tenant, canonical request digest, selected logical tool/operation and target, verified original calling app, and a durable Gateway dispatch-attempt/replica identity. Original-caller fields are assertions from this authenticated Gateway, checked against the action’s stored actor binding; public request headers are not authority. Workflow compares the user identity and current claims with the admitted grant and applies the claims-change rules above.

In one transaction against authoritative current state, Workflow locks the relevant grant, run, action, and budget records, validates their generations, deadline, cancellation/revocation status, actor, request digest, and pinned dependency, and atomically claims the dispatch against its budget reservation. It must not authorize from a lagging read replica or a Gateway cache. The decision returns the bound subject/app/tenant, action and attempt IDs, grant/ run/budget/fencing generations, exact tool reference and target/contract digest, execution class, parent/child depth where applicable, policy/disclosure ceilings, and a short dispatch lease. Persist allow/deny evidence with the decision ID; only an allow creates an AUTHORIZED dispatch-ledger row. The result is authenticated service data, not a replacement user JWT or a transferable bearer credential.

Durable Dispatch Ledger And Recovery

Use a new workflow_action_dispatch_t table in Workflow’s operational PostgreSQL database, owned and migrated by light-workflow. It is distinct from Gateway’s agent_delegation_replay_t and survives removal of that table. Gateway durably records intent by calling the fixed API; no local file, memory cache, or additional Gateway database is the authority. Database unavailability blocks sending. A2 must build the table, APIs, Gateway client, and recovery logic.

The ledger binds tenant, action, canonical effect/dispatch-attempt ID, request digest, target, decision/lease generation, Gateway owner/boot identity and fencing generation, reservation, state, and outcome/evidence references. Uniqueness and compare-and-set transitions allow only one active dispatch attempt per action. Keep transition history and retain unresolved rows irrespective of lease expiry; retain terminal evidence for the invocation’s recovery/audit period. No tokens or private keys are stored in this ledger.

Before sending, Gateway calls begin-dispatch for the authorized attempt. Workflow checks ownership, generations, lease, live grant/run/action state and budget again, then atomically changes AUTHORIZED to SEND_INTENT. Only the acknowledgement of that new transition permits the owner to send. A duplicate call reports existing state; it does not issue another send permission. Gateway records the outcome through complete, transitioning to a known terminal state or UNCERTAIN, or recording retryable NOT_INITIATED as specified below. Status/result reads recheck caller and disclosure authority. Completion reporting uses a dedicated service profile: the authenticated Gateway may record evidence for its stored send-intent binding after user-token expiry or grant revocation. It cannot authorize another send or disclose a business result. Such reporting does not require renewed user authority; authorize/begin and business-result disclosure retain their current user checks.

complete(NOT_INITIATED) handles deadline expiry before the target request starts, including during connection preparation or after a late send-intent acknowledgement. Before reporting it, the original live Gateway owner must atomically close a local send guard: NOT_STARTED -> ABORTED_NOT_INITIATED competes exclusively with NOT_STARTED -> STARTED. Keep the guard NOT_STARTED while acquiring the pooled connection, completing TLS/protocol setup, and obtaining all capacity permits. Preparation may establish a connection but must not send the target operation’s headers or body, including through early data or automatic retries.

At the final transport write boundary, use one guarded operation to check the original monotonic deadline and transition NOT_STARTED -> STARTED only if the deadline is still valid and the send-intent acknowledgement is valid. Immediately initiate the first request write on the prepared connection, with no intervening queue, connection/permit acquisition, handshake, or asynchronous yield. This guard belongs inside the transport at that boundary; wrapping a high-level HTTP client’s queued send call is insufficient. Disable automatic request retries for these routes throughout the outbound transport, including retrying a failed reused connection on a fresh connection. A send-intent acknowledgement permits only one guarded request initiation; client or proxy retry logic cannot obtain another by resetting the local guard.

Expiry before this transition closes the guard as ABORTED_NOT_INITIATED and allows the owner completion. Closing it prevents late callbacks or queued continuations from sending. Once STARTED wins, failure or expiry remains UNCERTAIN unless the outcome is known; the guard never authorizes a late write or an automatic retry. Abort further initiation if the deadline has elapsed. A transport timeout, absent result, or lack of a receipt is not proof of non-initiation. If the guard was crossed or its state is unknown, use UNCERTAIN instead.

Workflow accepts this completion only from the authenticated Gateway whose owner, boot, fencing, decision/lease, action, and attempt identities match the current SEND_INTENT record. Lease expiry alone does not prohibit this cleanup, but a superseded owner/generation cannot assert it. In one transaction record NOT_INITIATED, invalidate that send permission, and release the unused reservation exactly once. A repeated accepted completion returns its receipt; it cannot release a newer generation’s reservation or change another outcome. The trusted owner’s assertion is required; Workflow cannot infer it from time.

Recovery is state-based across all Gateway replicas:

• AUTHORIZED with no send intent: after fencing the old owner, fresh online authorization may replace the expired lease under the same canonical attempt and budget reservation. The old decision generation can no longer begin a send.
• NOT_INITIATED: the recorded owner completion proves that this send was abandoned before transport initiation. Under normal backoff and retry limits, fresh online authorization may reuse the same canonical action/effect attempt and request digest with a new decision/lease and reservation generation. It must reacquire available budget and recheck current grant/run authority; incurred costs and retry counters are not reset. No operator is needed.
• SEND_INTENT or UNCERTAIN: a send may have happened, even if an acknowledgement was lost. A status read or Gateway restart never authorizes another send. Reconcile through a target receipt or qualified target idempotency protocol using the same effect identity; otherwise require operator resolution.
• Known terminal outcome: return or reconcile recorded evidence after current authorization checks, without executing the effect again.

Lost authorize/begin/complete responses and a crash before or after a network send follow these rules. If the owner crashes before NOT_INITIATED is durably accepted, a new boot or another replica cannot reconstruct the local guard and assert non-initiation. If the completion committed but its response was lost, the recorded NOT_INITIATED receipt is sufficient for the safe retry path. Do not reset an ambiguous attempt to AUTHORIZED, allocate another reservation, or infer that lease expiry proves no effect. Admission failure known to precede send intent settles the unused reservation.

Qualified receiver reconciliation uses the existing complete operation, not a new dispatch operation. It authenticates the receiver app and its exact mTLS peer, checks that the receiver is registered for the action’s pinned tool, and accepts only a terminal evidence digest for the same action and generation while that generation is UNCERTAIN. It can settle the retained reservation after the user token or run deadline expires, but it cannot authorize, begin, retry, read a business result, or change an existing terminal receipt. An identical receipt is idempotent; conflicting evidence fails closed.

Dispatch Lease Without Cross-Host Clock Comparison

There is no positive authorization cache. Gateway records local monotonic time t0 immediately before sending authorize, and its send deadline is t0 + 5 seconds. Count authorization latency, local admission, the begin-dispatch round trip, connection/TLS/protocol preparation, capacity acquisition, and all intervening waits against that same budget. Check the deadline and transition the send guard together at the final write boundary described above, after all preparation. A response received after the deadline cannot permit a send. Do not reset t0 on retries or on receipt of either response. Since the Workflow decision occurs after t0, this conservatively bounds decision-to-send elapsed time to five seconds without subtracting timestamps from different hosts.

Workflow separately expires its authorization lease at its own decision time plus five seconds, or the earlier grant/run/action deadline, using its database clock sampled after acquiring the relevant locks. begin-dispatch rejects a late claim on that clock and rechecks current authority in the same transaction as SEND_INTENT. It also returns the remaining authorized duration after applying those deadlines. Gateway sets its deadline to the earlier of t0 + 5 seconds and the monotonic begin-request start plus that duration; it never extends the original limit. UTC times are useful for audit and issuer expiry checks, not for reconstructing the Gateway elapsed timer.

Gateway restart, suspend/resume, migration, or loss of timer continuity invalidates the outstanding local lease. Recovery consults the durable ledger; it cannot rebuild a send deadline from wall-clock timestamps. A fresh lease requires the safe AUTHORIZED or recorded NOT_INITIATED recovery path above. Unknown references, invalid responses, unavailable storage, or elapsed deadlines fail closed before sending. An elapsed deadline after send-intent acknowledgement uses NOT_INITIATED only when the original owner can close the unstarted send guard; otherwise it retains the uncertain-execution recovery path.

begin-dispatch is the final authorization decision point. Revocation committed before it denies the action; afterwards the action is admitted/in flight and subject to cancellation/fencing. The lease bounds initiation of the request, not network delivery, completion, or rollback of an already sent effect. Long-running work rechecks permits at subsequent protected actions.

Nested Depth, Capacity, And Private Version Targets

Replace each use of context.delegation in Gateway’s workflow admission with the verified action context, not fields copied from the user JWT or request. Only an independently admitted root starts at depth zero. Workflow derives a nested workflow’s depth with checked parent.permit_depth + 1, bounds it by the parent grant/dependency ceiling and the target’s maximum_delegation_depth, and preserves the permitted execution class and remaining deadline. Missing context, depth overflow, or an unknown class denies the nested call; it must not silently select root defaults.

Gateway continues selecting the synchronous permit pool by the verified child depth. Preserve the existing nonblocking try_acquire_owned behavior: an absent pool or exhausted capacity returns the defined capacity error. A parent holding a synchronous permit must not make its child wait for that same pool. Async children also obey the depth/lineage limits. When Gateway starts a child through StartInvocationRequest, carry the parent action/decision reference; Workflow revalidates it and atomically binds the child to that action and lineage. Retries cannot create another child or reset depth, class, or budget.

For privateVersionTarget, Workflow resolves the exact target from the admitted run’s pinned dependency registry. Gateway compares the verified stableToolRef, private target name/version, endpoint, and contract digest with its published mapping and authorizes using the logical authorizationToolName. An invocation ID or tool reference supplied by a caller is insufficient. Keep private targets out of public discovery; direct guesses, cross-run/tenant references, wrong versions, and binding drift fail without revealing the private target. Valid pinned calls remain reachable even when a public alias advances to a new version.

Implementation Order And Exit Gates

A0: Freeze Contracts And Issuer Profiles

The A0 baseline captures the initial local-issuer selection, current client inventory, contract records, claim ownership, transport inventory and deployment-manifest requirements. It selects backend authorization-code enrollment with PKCE S256 for the broker; the issuer must persist and validate the challenge and consent/provenance in A1. This baseline does not qualify a running stack or an external issuer.

Define the identity context, allowed-caller rules, grant/action schemas, credential-store boundary, issuer mappings, renewal/revocation behavior, and failure states. Inventory existing endpoint bypasses and all lad1 consumers. Pin the supported light-oauth and third-party issuer profiles. Provider settings or a token-exchange handler alone do not satisfy offline execution qualification. Classify grant bindings versus mutable claims, identify each claim’s authoritative source, and define tenant binding and permission-change enforcement delays. Inventory trusted clients and their client_authenticated_user, long_lived, exchange, and refresh permissions. Freeze the broker’s eligible grant provenance, strict refresh policy, user/app verification profiles, shared-audience forwarding destinations, separate Agent registrations/admission, issuer mTLS registration, and the internal action-decision/dispatch-ledger contracts. Define the local monotonic deadline and restart/fencing rules without a cross-host skew allowance.

A1: Implement Issuer Grants And Broker Renewal

See the A1 implementation and qualification report for source changes, test evidence and the remaining selected-stack activation gate.

Implement the A0 token_use marker in every local access-token issuance path, including refresh and specialized grants. Derive it from validated grant semantics, reserve it against registered/request custom claims, and implement shared verifier checks for user versus app positions. Preserve only the explicit legacy long-lived app key-purpose exception; markerless short-lived tokens do not gain user authority from their claims or shared signing key. A2 must wire these checks at every receiver in the selected profile.

Emit purpose as a dedicated JwtClaims field serialized as token_use, with the validated purpose passed explicitly to generate_jwt_with_key. Keep the name reserved in custom claims, but do not insert the issuer value into extra: the helper applies remove_reserved_claims(extra) before signing and would remove it. A1 tests must verify exactly one correct purpose marker in the actual signed token after filtering and serialization, including override cases.

Implement the shared OAuth acquisition/provider layer and Workflow-hosted broker, encrypted renewal storage, grant lifecycle, and serialized refresh recovery. Extend/qualify the local issuer for backend-bound unattended grants, revocation, and the live refresh behavior above. Implement the tenant-bound authorization-context query for normal refresh and any retained interactive grace profile. Implement broker-client grant restrictions, issuer grant-provenance lookup, and strict unattended rotation with consumed-token history and family revocation. The broker must fence uncertain rotations and require reauthorization instead of recovering through the legacy grace path. Retain transactional rotation and grant ceilings. Implement tls_client_auth at light-oauth’s dedicated broker listener, verified TLS-peer request context, registered certificate identities/authentication methods, revocation checks, and broker key/certificate loading. Publish and wire the listener, trust, registration, and certificate-rotation settings in the selected stack. All broker grant/refresh/lookup/revocation paths enforce the registered method, including requests sent to legacy endpoints. Wire trusted client settings and runtime-secret mounts without placing client secrets in workflow definitions.

Exit gate: after the original user JWT expires and the browser disconnects, a scheduled run and an hours-long run obtain valid credentials under the same approved identity/ceiling. Test restart, key rotation, concurrent renewal, lost refresh responses, revoked grants, disabled users, removed roles, and issuer outage. No stale-claim or service-account fallback is accepted.

For a multi-hour normal-load soak, record elapsed run-hours, renewal lead time, refresh attempts, successful rotations, uncertain rotations, and reauthorization counts/reasons. Report uncertainty per refresh attempt and the fraction of runs requiring reauthorization. Report injected lost-response cases separately from ordinary-load observations. With 600-second tokens, renewal occurs before each expiry, so an hours-long run crosses many rotation boundaries. Measure this operational cost without weakening strict rotation or treating a short, failure-free sample as a production reliability guarantee.

Issuer-specific checks must also prove that:

• A client_credentials token carrying registered uid/role claims still has token_use=app and fails user Authorization verification. Registered and request-supplied purpose overrides cannot alter issuer purpose. Exercise all issuance/refresh paths, missing/unknown/conflicting markers, user tokens in X-Scope-Token, and markerless long-lived fixtures under the explicit app-only key-purpose profile. The exception never admits a token as a user.
• Removing a role/group/position or changing an authorization attribute affects the next refreshed token, including through any retained interactive grace path; unattended grants can never opt into that path.
• Locked/deleted users, removed tenant membership, and revoked sessions cannot renew; changing the current Portal host cannot change the grant’s tenant.
• Added user permissions cannot expand the OAuth grant or workflow ceiling; permission-bearing custom claims cannot bypass the live query.
• A failed authorization query returns no token based on saved claims, and failed/concurrent rotation cannot return an uncommitted replacement.
• Authenticated reuse of a consumed unattended refresh token fails and revokes its family even inside the interactive grace window. Wrong-client and unauthenticated requests neither retrieve replacements nor revoke that family.
• The broker succeeds with its registered mTLS identity. Missing certificates, a different client’s certificate, invalid/revoked certificates, forged peer headers, and secret-only requests fail before issuing or rotating a token, including at legacy endpoints. Exercise approved certificate renewal and retirement; stolen refresh-token/client-secret material without the mTLS key cannot renew. Existing non-broker client authentication remains compatible.
• Lost refresh responses and a crash before broker persistence fence the grant and require reauthorization; no automatic old-token retry retrieves a successor.
• Workflow enrollment rejects app tokens containing user-like custom claims and ineligible assertion grants. The broker client cannot use specialized grants to manufacture a substitute user session; separately approved clients retain their supported specialized use cases.
• An existing access token and a permission change racing with refresh obey the profile’s documented enforcement delay; renewal is not claimed to revoke all previously issued access tokens.

A2: Enforce Both Identities And Replace Nested Delegation

Apply the per-route user/app contract to Workflow, Agent, Gateway, API/MCP, and Resource/Knowledge paths that the feature uses. Replace nested MCP minting with broker-provided user credentials and the workflow’s own app credential. Integrate the fixed Workflow authorize/begin/complete/status APIs and Gateway client, workflow_action_dispatch_t migrations and durable transitions, online dispatch claims, audit decisions, and effect reconciliation. Implement the monotonic send deadline, transport-level atomic send guard after connection/capacity preparation, owner-only NOT_INITIATED completion, and recovery/fencing rules. For the selected Pingora/reqwest outbound paths, identify and qualify the transport write hook or adapter against pinned dependency versions. A custom connector alone is sufficient only if it controls that final write boundary, including reused connections. Explicitly wire and verify the route-specific retry settings at every client/proxy layer; a handler-level guard or reliance on default retry behavior does not qualify the path. Provision separate interactive and workflow Agent registrations/instances, isolated credentials, peer mappings, and admission policies; Gateway classifies origin from verified credentials. Replace delegated depth/class and private-target checks with the verified action context, including Workflow-side child-lineage validation.

Exit gate: direct calls using a valid user token and an unauthorized app fail; permitted gateway calls still require user tool/resource permission. A copied gateway bearer from an unapproved transport peer fails the qualified gateway-only profile. Test wrong issuer/audience/host, duplicate headers, missing claims, renewal during a tool loop, replay across replicas, changed request payloads, revoked action permits, exhausted budgets, and cancellation races.

Additional exit cases:

• Approved shared-audience service chains retain original-token forwarding; an unapproved demo/third-party target receives no platform bearer. App tokens cannot authenticate as users, and valid certificates from the wrong workload cannot authenticate as Gateway.
• A workflow Agent credential with no action reference, a forged interactive header, or an interactive URL is denied. Workflow callers cannot enter through the Chat Agent or select its credentials. Normal Chat still succeeds with its own registration; workflow Agent calls succeed only with active bound actions.
• Nested sync and async calls retain increasing depth and inherited limits; missing context, overflow, and excess depth deny admission. Saturating a root sync pool still permits a qualified child in its separate depth pool; a full child pool fails promptly without waiting on the parent. Restart/retry cannot reset depth or create a second child.
• Valid pinned private-version calls succeed and stay absent from discovery. Guessed IDs/names, wrong tenants/runs/versions, and dependency/contract drift fail; updating the public alias does not redirect an accepted pinned call.
• Across Gateway replicas, duplicate action claims authorize at most one dispatch. Workflow outage, stale generations, altered request digests, expired leases, and a lost decision response cannot bypass authorization or replay an uncertain effect. Crash before send intent, after its commit but before its acknowledgement, after sending, and before completion persistence. Recover on a different Gateway replica from the Workflow ledger; never resend a possibly executed effect without qualified reconciliation. Repeat with the old delegation replay table absent and with the new store unavailable.
• Use independently controlled wall clocks and local elapsed timers: large host clock offsets and wall-clock jumps cannot extend Gateway’s five-second bound. Delayed authorize/begin replies, lock waits, local pauses, and earlier grant deadlines cause timely rejection. Restart or timer discontinuity invalidates local leases. Verify late begin claims fail on Workflow’s own clock and retries cannot reset the original timer. Test revocation before and after the SEND_INTENT transaction, with no cached approvals.
• Delay the send-intent acknowledgement beyond Gateway’s deadline: assert zero target requests, accepted owner-only NOT_INITIATED, one reservation release, and successful fresh authorization of the same canonical attempt without an operator. Also delay pooled-connection acquisition, TLS/protocol readiness, and capacity preparation after send intent: the guard stays NOT_STARTED, expiry produces NOT_INITIATED, and no target operation headers/body are sent. Race readiness and the deadline at the final write boundary: exactly one local guard transition wins, with no further queueing before the write. A started request cannot report NOT_INITIATED; expiry after that transition cannot trigger a late write or automatic resend. Duplicate completions cannot double-release; stale owners/boots/generations are rejected. Test a lost completion response, a crash before completion persistence, and grant revocation before retry: only recorded non-initiation enables this safe retry of a SEND_INTENT attempt, and fresh authorization still enforces revocation and retry budgets.
• Fail a reused upstream connection at the first write and after a partial write. Verify the actual configured transport never replays the operation on a fresh connection, even if the request body is replayable. Count outbound request initiations as well as target observations: only one initiation may cross the guard, and an unknown outcome remains UNCERTAIN. Exercise each qualified outbound client/proxy path with its effective retry settings.

A3: Migrate, Remove Old Authority, And Qualify Orchestration

Migrate active invocations to valid grant references through authorized reauthorization or drain them; an expired persisted bearer is not enrollment proof. Stop persisting reusable access tokens in ordinary invocation state. Coordinate sender/receiver rollout so routes cannot fall back to weaker authentication when a new credential fails.

Inventory the app tokens, issuer/signing trust, mTLS identities, and forwarding profiles used by the selected stack. Keep deliberate local-development fixtures in Git; official installations use independent runtime credentials and reject those fixtures. If an official installation has reused development credentials or exposed its own tokens, replace/revoke the affected credentials and remove their trust before qualification. A long expiry alone is not a reason to remove the supported app-token profile, and blanket rotation of development fixtures is not a prerequisite. Test the actual user/app/certificate combinations at the official boundary rather than relying on a dev label.

Remove workflow delegation signer/verifier wiring, its deployment secrets, and crates/agent-delegation/agent_delegation_replay_t only after verifying no remaining consumer and qualifying their replacement protections. Preserve active evidence and recovery behavior during schema/config migration. Install and qualify workflow_action_dispatch_t and all fixed dispatch APIs before removing the old replay table. Drain/reconcile old delegation attempts first; their replay rows cannot be treated as evidence of send outcome. The new ledger and its unresolved attempts are retained across A3 and subsequent restarts.

Exit gate: run the complete authenticated API/MCP/Knowledge paths, scheduled execution, renewal, revocation, and effect-recovery cases on the selected stack. Verify that specialized grant support, local shared-audience forwarding, and development startup remain compatible with the explicitly selected profiles. Then admit development orchestration Phase 1. Enterprise accounting and sandbox qualification remain additional profile gates, not replacements for this work.

References

• Issue #374
• LLM User and Agent Authorization
• Workflow-Backed MCP Tools
• Stateless Auth Handler
• MSAL Exchange Handler
• Token Handler

Authorization A0: Contracts And Issuer Profiles

Frozen historical baseline. The browser authentication, registered callback, and credential-broker provisioning below describe the original A0 proposal. Workflow Invoke later retired both browser callback and backend broker enrollment. See Workflow Invoke for the current user-token and LONG registration contracts. The frozen text below remains for provenance and is not current deployment guidance.

Status: A0 contract baseline v1 frozen after review, September 13, 2026. The qualified-receiver complete variant recorded below is part of the frozen A0 contract; it does not change the frozen operation set or authorize sends. It defines the initial implementation contracts for the accepted authorization design. It records source and local registration evidence, not completed A1–A3 runtime qualification. Personal orchestration Phase 1 remains gated on those phases.

The baseline selects portal-config-loc/all-in-lt with local light-oauth for the first unattended user profile. light-portal-install must publish the same contracts when that distribution is qualified. External issuers and official environments need their own completed profile manifest and qualification record; neither inherits approval from a working local login.

Baseline And Evidence

These identify inspected source, not a claim that running images were built from those commits. The running Compose project was confirmed as portal-config-loc/all-in-lt, including its runner credentials override. No credentials are included in this record or the accompanying inventory.

The client inventory contains the 32 active provider/client bindings read from local configserver.auth_client_t joined to configserver.auth_provider_client_t for host 01964b05-552a-7c4b-9184-6857e7f3dc5f. Both rows must be active. The export includes IDs, names, types, profiles, exchange types, scopes and aggregate versions; it excludes secrets, custom-claim values and user information. Thirty-one bindings use provider AZZRJE52eXu3t1hseacnGQ; one uses AZ7MrzXYcz2X8kdd44FPLw. Only the former is selected below.

For the selected provider, 30 clients are trusted and one is confidential. Light Portal Client has exchange type msal; pylon has ccac; the other bindings have no exchange type. These are observed registrations, not proof that their traffic uses every grant available to them. In current light-oauth:

• password, client_authenticated_user and long_lived check client_type == trusted; client_profile == service does not disable them.
• Exchange is selected by token_ex_type. It is not a general offline grant.
• Refresh requires an authenticated client and a matching refresh record. The registry has no broker-specific strict-rotation or mTLS-authentication fields yet. A1 must add and enforce those restrictions.

Selected Issuer Profiles

The following names identify this document’s profiles, not existing config keys.

The selected local provider uses issuer urn:com:networknt:oauth2:v1, shared user audience urn:com.networknt, and provider ID AZZRJE52eXu3t1hseacnGQ. The checked-in public issuer base is https://oauth.localhost; the provider’s discovery URL is not a substitute for the configured JWT issuer. Retain the issuer’s RS256 verification profile and separate long-lived app signing-key purpose. Issuer-owned purpose/provenance must distinguish user tokens from app tokens, including short-lived client-credentials tokens; uid, sub, token lifetime or the header carrying a token is not sufficient evidence.

Freeze the local purpose marker as an issuer-signed token_use claim with exact values user and app. A1 adds it to every local access-token issuance path: user grants and their refreshes emit user; client_credentials and long_lived emit app. Specialized user assertion/exchange grants retain their supported user-token purpose, but that marker alone never proves eligibility for Workflow enrollment; issuer grant provenance remains mandatory.

The issuer derives purpose from the validated grant/issuance path. Reserve token_use against both registered custom claims and request extra claims, and emit it as a dedicated JwtClaims field, separate from filtered extra. generate_jwt_with_key calls remove_reserved_claims(extra) internally, so inserting the reserved marker into extra would strip it before signing. Pass the validated purpose explicitly into issuance and serialize it once as token_use. Refresh must not derive it from a saved custom-claim snapshot. A1 implements shared verifier checks; A2 wires them at every selected receiver: user Authorization requires user, and X-Scope-Token requires app. Unknown, malformed or conflicting purpose is rejected. Markerless user or short-lived app tokens require new issuance; they cannot fall back to uid, role or the shared provider key. Existing markerless long-lived app fixtures may retain the explicitly registered issuer/key-purpose app verification profile, only in the app position. A conflicting marker is rejected even there; the normal shared signing key never qualifies for this exception.

For local-workflow-user-v1, freeze these choices:

1. Create a dedicated broker registration. Allow only its backend code grant and refresh grant; reject password, client_authenticated_user, client_credentials, long_lived and exchange for this client. Do not repurpose either existing Workflow app registration from the inventory.
2. The issuer authenticates the user and records explicit workflow/schedule consent. Bind the code to the broker, provider, user, tenant, exact registered callback and enrollment intent. Use one-time state and PKCE S256, with the verifier retained by the broker. The browser supplies neither a refresh token nor a broker credential. A1 must implement the complete challenge path: current post_code stores code_challenge and challenge_method as None, even though redemption has a verify_pkce helper. Test code substitution, missing/wrong verifier, replay and consent/tenant mismatch. See PKCE and authorization-code protections.
3. Use the dedicated issuer TLS listener for broker token, provenance lookup and revocation operations. Match the actual verified certificate to issuer registration; reject secret-only broker requests at every legacy URL too. This is mTLS client authentication, not automatic certificate binding of the forwarded user’s access token.
4. Issue a bounded renewable family for this consent and backend client. Keep auth_refresh_token_t; apply live tenant-bound user/claim lookup on renewal, strict one-time rotation and no consumed-token successor recovery. A1 must expose issuer-owned provenance and authenticated family revocation. An existing refresh token with no eligible provenance cannot be enrolled.
5. Keep the initial user access-token lifetime at 600 seconds, matching current local issuance. Grant expiry and any shorter issuer limit cap renewal. An hours-long workflow does not obtain a longer-lived user access token.
6. Preserve the shared audience only inside explicitly approved forwarding destinations. Start with an empty destination allowlist until A2 publishes exact routes and receiver identities. Demo or third-party targets do not receive the platform user token merely because Gateway can reach them.

The broker’s callback address, new client UUID, certificate identities, trust roots and secret references are deployment bindings, not values to guess from client names. A1 provisions them in the versioned manifest below. Enrollment must fail while a required binding is absent.

Claim Ownership And Freshness

portal-core::login_user_by_email shows the relationship sources but selects the current host and has login-specific filtering. get_user_by_id returns NULL permission columns and also selects the current host. A1 needs a dedicated authorization-context query; neither helper is the refresh contract unchanged. Absent memberships mean an empty permission set, not permission to reuse the old snapshot. Failed lookups issue no replacement token.

Freeze the initial freshness mode as live refresh, existing access tokens bounded by expiry. Re-read applicable live policy/ACL data at each resource decision. This does not discover a changed claim if that policy only consumes the old JWT. The deployment manifest must record validator expiry leeway and qualified issuer/receiver clock error; the worst-case old-claim interval is the 600-second token lifetime plus those allowances. No immediate user-role revocation claim is made. A stronger online user-status/version profile needs separate qualification, not an undocumented cache assumption.

Workflow grant/run/action revocation has no positive authorization cache: authorize and begin-dispatch read current primary-store state. A revocation committed before begin denies a new send intent; a later revocation follows the accepted in-flight cancellation rules. The local five-second initiation deadline has no cross-host clock-skew allowance.

Identity And Caller Contract

All new service records use contractVersion: 1, camelCase property names, explicit tagged variants and rejection of unknown versions/fields. UUIDs are opaque identities; counters are nonnegative integers with checked increment, and overflow fails closed. Timestamps are UTC audit/expiry values. They never reconstruct a Gateway monotonic lease after restart. An ID alone grants nothing.

VerifiedIdentityContext is constructed by trusted credential validation, never deserialized as authority from public request headers:

For the SYSTEM variant, a verified service subject replaces user; it has no impersonated user claims. That separate execution profile is not enabled by selecting local-workflow-user-v1.

The local user subject is the verified uid mapped under the issuer profile; client_id/cid identifies the login client, not the immediate workload. The app sid is checked against registration, client and actual mTLS peer. Conflicting identity claims fail instead of being merged. Existing Knowledge subject/group/organization normalization and disclosure rules must be preserved by the issuer mapping and verified policy context, not caller assertions.

For the initial gateway-only profile, migrate Agent Knowledge calls through Gateway with the same dual-token and disclosure checks. Do not leave the old direct Agent-to-Knowledge lad1 route as a workflow bypass. Any future direct interactive Knowledge route needs an explicitly qualified separate profile. Native personal workers remain consumers of admitted local work; they receive no refresh credentials or authority to choose a caller profile.

Grant, Action And Credential Records

These are new logical schemas. A1/A2 migrations and shared Rust types implement them; this document does not claim the fields already exist in configuration.

Grant admission requires ACTIVE; REAUTHORIZATION_REQUIRED, REVOKED and EXPIRED forbid new protected actions. Reauthorization binds the same verified user/tenant under a new generation without resetting budgets or uncertain effects. One-off run completion retires that run binding; a recurring schedule’s parent grant survives only within its original consent and expiry.

The broker stores a durable renewal attempt before redeeming a refresh token. Only the lease/fence owner may commit its replacement generation. A crash or lost response after possible issuer commit fences the credential as uncertain, requests family revocation and requires reauthorization. A database restore must not resurrect an older refresh generation. Revocation retry cannot make the fenced credential usable while the issuer is unavailable.

Encryption keys are outside ordinary database rows; ciphertext is separate from ordinary workflow state. Access tokens may exist briefly in trusted memory. Prompts, worker sessions, artifacts, logs, results and GitHub comments contain no reusable credentials. The issuer keeps its own refresh/family history; the Workflow broker store does not replace auth_refresh_token_t.

Action Decision And Dispatch Contract

Freeze the four fixed internal POST operations from the accepted design:

Workflow creates action records against admitted run/job and pinned dependency records before protected dispatch. The executor and trusted Agent adapter pass the resulting opaque action reference; it is not model-selected authority. Each concrete protected operation has its own binding. Reserving a turn does not authorize arbitrary later tool names, parameters or destinations. The original caller in the internal request is an authenticated Gateway assertion checked against that record, not a forwarded public identity header.

Required request/version/binding fields cannot be omitted or defaulted. A duplicate begin reports existing state, not a fresh send acknowledgement. A conflicting body or owner/generation fails. Lost responses recover through the ledger; neither generic HTTP retries nor a status result authorizes replay. complete distinguishes known terminal outcome, UNCERTAIN and owner-proven NOT_INITIATED; business-result disclosure always needs current authorization.

For JSON request digests, reuse workflow-invocation-contract’s strict rfc8785-safe-json-v1 canonicalizer and sha256: lowercase-hex format. Keep requestDigest separate from user-token bytes and from the logical input digest: bind the pinned operation/target, actual method/path/query, effect-bearing headers and payload. Credential headers are verified separately. Preserve query/array order where meaningful. Binary payloads use a byte digest within the canonical descriptor. A2 must verify the final request against this binding after tool-to-HTTP mapping; changed targets, aliases or bodies cannot reuse it. Unsupported/non-materializable request forms fail qualification rather than omitting part of the operation from the digest.

Uniqueness is scoped to tenant/action/canonical attempt, with only one live dispatch generation per action. Workflow locks current grant/run/action/budget state in its operational PostgreSQL transaction. No lagging replica or positive Gateway cache supplies approval. Lease expiry never deletes unresolved evidence.

The five-second timer starts before authorize and includes both control RPCs, connection/TLS/protocol preparation and capacity waits. Only at the final transport write boundary may the atomic deadline/acknowledgement check change NOT_STARTED to STARTED. Expiry before it can close as ABORTED_NOT_INITIATED; failure after it cannot claim non-initiation. Follow the accepted design’s owner/boot/fence checks, duration shortening and uncertain recovery rules. No automatic request retry or redirect can introduce a second send. Safe NOT_INITIATED retry retains incurred costs and retry counters.

Preserve existing ExecutionClass values interactive, standard, batch, the checked u16 depth ceiling and separate nonblocking synchronous pools per depth. StartInvocationRequest needs verified parent action/decision binding before replacing delegation-derived depth. Root classification is independent admission; omission cannot reset a child to depth zero. Pin private-version targets and their logical authorization name across alias changes.

Migration And Transport Inventory

Paths below are source evidence relative to light-fabric unless prefixed with another repository. Removal is gated on replacement behavior, not on a text search for the word delegation becoming empty.

The selected dependency baseline in Cargo.lock is Pingora/core 0.8.1, local patches/pingora-proxy 0.8.1, reqwest 0.12.28, and hyper-util 0.1.20. Hyper 0.14.32 and 1.9.0 both occur; trace the actual outbound path instead of assuming either one owns every write. Dependency changes require repeating transport qualification with the replacement lockfile.

A2 must exercise new and reused connections, first/partial write failures, delayed TLS/connection/capacity, replayable bodies, no hidden retries, and monotonic deadline races on each qualified path. Count initiations as well as target receipts. Until the required write boundary is controlled, that path is not enabled for this profile.

Deployment Manifest And Phase Handoff

A1/A2 must materialize one versioned, non-secret manifest for the selected stack. Freeze its required content now:

• Issuer/profile/provider/tenant, allowed JWT algorithms, token_use enforcement and any explicit legacy long-lived app key-purpose mapping, broker registration/allowed grants, exact callback and issuer endpoints, certificate registration/trust/revocation settings and opaque secret references.
• Token lifetime, validator leeway, qualified clock-error bound and resulting maximum old-claim interval; current claim sources and custom-claim ownership.
• Exact Gateway, Workflow, interactive Agent and workflow-Agent client/service IDs, certificate peers, environment and allowed-caller/route mappings. Client names and Compose service names are inventory hints, not authentication.
• Exact approved forwarding destinations, pinned tool/endpoint/contract versions, resource/disclosure ceilings, supported transport paths and retry settings.
• Source revisions, built image digests, published configuration versions, migration versions, gate results and retained evidence references.

The current local startup defaults include com.networknt.portal.gateway-1.0.0, com.networknt.workflow-1.0.0, com.networknt.agent.codex-personal-1.0.0 and com.networknt.agent.claude-personal-1.0.0. They do not yet establish the new workflow-only registrations. Gateway’s startup environment defaults to loc while Workflow/Agents default to dev; reconcile and validate the effective published peer mappings during provisioning, not by weakening equality checks. Neither existing Workflow client name proves it is the new broker.

Each isolated workflow Agent also needs its own service ID in codingProfile.workspaceBindings[].agents and runner-local RunnerWorkspaceConfig.bindings[].agents, with the complete bindings equal. Keep intentional dev credential fixtures; official profiles must reject their trust and use independent credentials.

A1’s purpose matrix must include a client_credentials token with registered uid/role claims: it remains token_use=app and is rejected in user Authorization. Test custom/request attempts to override purpose, every issuance/refresh path, missing/unknown markers, user tokens in the app position, and the narrowly scoped legacy long-lived app exception. A2 repeats receiver integration tests. Inspect the actual signed JWT payload to prove exactly one issuer-selected token_use survives filtering and serialization, including custom-claim override attempts. A1 also records refresh attempts, uncertain rotations and reauthorizations during a multi-hour soak, separating ordinary-load observations from injected response loss; see the parent design’s A1 exit gate.

Changes to contract meaning, issuer grant eligibility or recovery transitions require a new baseline revision and affected gate review. Reassigning environment bindings also requires requalification of those bindings; it cannot silently change origin classification, token purpose or lifecycle transitions.

A1 Implementation And Qualification Status

Historical record. This report records the former A1 credential-broker implementation and its 2026 qualification evidence. Workflow Invoke later retired the broker, including both browser callback and backend enrollment routes. Current invocation sends the acting user’s bearer through Gateway to Workflow. Asynchronous workflow_start runs that can outlive that bearer may use a LONG registration exchanged through light-oauth; synchronous workflow_invoke does not register LONG. See Workflow Invoke. The historical commands, deployment steps, and acceptance plans below are not instructions for the current stack. The linked activation receipt retains its original observations, including the retired callback, as audit evidence.

Historical status: A1 source implementation complete; scope-consent reuse correction qualified in the short integration suite and deployed locally before broker retirement.

Historical acceptance amendment (2026-09-14)

The user requires only the existing Portal portal.r / portal.w scope consent. There must be no additional workflow-specific consent screen or second login. Workflow identity, policy binding, credential ceilings, expiry and revocation remain backend enforcement requirements; existing scope consent is not permission to skip issuer provenance validation.

The user waived scheduled and hours-long renewal qualification after the original user token expires. Record these tests as waived / not run, not passed; they are no longer A1 acceptance blockers. Historical requirements below describe the previous baseline and are superseded by this amendment.

The extra Portal enrollment prompt and generated Gateway workflow_authorize tool remained removed. At that time, root HTTPS Workflow invocation without a supplied grant acquired one internally through /workflow/credentials/enroll. Workflow used the issuer’s mTLS /oauth2/{provider}/workflow/enrollments/acquire endpoint, then redeemed the returned one-time PKCE code server-to-server. Only a grant UUID was returned to Gateway; no redirect, password or second consent was involved.

The issuer records SHA-256 access-token fingerprints in ordinary authorization-code and refresh issuance audits. Acquisition requires exact issuance evidence tied to an active authorization-code session, matching user/Host/client/provider and scope ceilings. Tokens issued before this change need a normal Portal refresh to obtain this evidence; unsigned claims, app tokens and unrecorded user tokens cannot bootstrap renewal. Acquired grants retain the source-session relationship; revocation, scope removal or missing provenance blocks renewal. Legacy browser grants require their original login evidence and remain only for compatibility.

Short real-HTTPS/mTLS integration passed: initial acquisition, acquisition after normal Portal refresh, direct broker renewal, scope-expansion rejection, wrong Host rejection, unrecorded-token rejection, missing-provenance rejection and source-session revocation. OAuth unit tests: 22 passed, 2 ignored. Workflow library: 86 passed. MCP module: 175 passed, 3 ignored. Scheduled/hours-long tests were waived, not passed. No live personal/native workflow was launched for this change.

At that checkpoint, the updated OAuth, Workflow and Gateway binaries were running locally with zero restarts; the unauthenticated enrollment probe returned 403. This was container-layer qualification, not a rebuilt release image, and would have been lost on container recreation. Rollback binaries were recorded under /tmp/phase1-backend-acquisition.4FBLYy/; their current presence is not assumed. Snapshot 01a0a222-a6dc-7288-9845-f709ead64d8e was current at the time. The editable instance property then contained an enrollment ACL assignment; its present state requires a separate check. Application databases were not wiped. A separate oauth_a1_qualification database held schema-only fixtures and test evidence.

The implementation follows the frozen A0 baseline. It does not admit personal orchestration Phase 1: production receiver enforcement and dispatch are A2/A3, and live deployment qualification remains separate.

Historical implementation

• Issuer: dedicated, reserved JwtClaims.token_use; live tenant-bound refresh authority; explicit custom-claim sources; PKCE and browser consent; dedicated certificate-authenticated broker listener; strict rotation, consumed-token history, grant lookup and revocation. Broker clients cannot use secret-only authentication through another provider binding. Specialized non-broker grants retain their supported behavior.
• Recovery: revocation tombstones serialize with enrollment and redemption, including when revocation arrives before the grant exists. Uncertain refreshes require reauthorization; the broker never retrieves a replacement through interactive retry grace.
• Workflow: encrypted credential storage, a store-to-issuer/client binding, durable enrollment and renewal ownership, run binding, key rotation, restart recovery, cancellation/revocation fencing, and retryable issuer revocation. At the time, enrollment APIs returned references and an authorization URL, never refresh credentials. The browser callback used a separate optional TLS listener with stored OAuth state and backend PKCE. Both enrollment routes and the callback listener have since been retired.
• Shared client/verifiers: fixed HTTPS endpoints, explicit CA trust, mTLS, bounded responses, signed-token validation and disabled redirects/retries; user/app purpose validation including duplicate-marker rejection and the explicit app-only legacy-key exception. Receiver-wide wiring remains A2.
• Deployment: the canonical Portal patch and fresh schema, regenerated bootstrap SQL for both distributions, a separate credential database/runtime principal, private mount preparation and ownership, registration/replay checks, certificate/key rotation procedures, opt-in Compose overlays, and a null-default Portal configuration catalog delta. The OAuth image build now includes the complete external Cargo path-dependency manifests needed by A1.

The former issuer schema came from portal-db/postgres/patch_20260913_01_workflow_broker.sql and was once reflected in canonical DDL and distribution bootstrap SQL. The later portal-db/postgres/migrations/patch_20260928_04_retire_workflow_broker.sql dropped the broker tables. The old patch and bootstrap state are historical evidence, not installation instructions; applying the old patch would recreate retired tables.

The former Workflow credential schema was light-fabric/apps/light-workflow/migrations/credential_broker.sql. Provisioning assets formerly lived in light-fabric/deployment/workflow-broker and the matching local and installer overlays. These source assets were retired; the paths here identify historical qualification inputs.

Historical qualification

Machine-readable results and local image IDs and working-tree source hashes identify the earlier qualified artifacts. The image IDs are local builds, not published registry receipts, and predate the availability fixes below. That historical issuer image was not a release qualification and is no longer a deployment target.

The HTTP tests use the real Workflow broker and local issuer together, with PostgreSQL and actual TLS handshakes. Faults are injected around transport delivery or database persistence, rather than replacing renewal with a mock success. These are isolated integration tests, not a claim that the live Portal frontend and deployed configuration have been qualified.

The historical issuer/Workflow integration gates used portal-service/apps/light-oauth/scripts/run-a1-gates.sh. That script was removed with the broker; the deferred two-hour soak was never recorded as passed.

The historical gate used the disposable oauth_a1_qualification database with a schema-only configserver fixture. Credentials were supplied privately. The script recorded base revisions and working-tree source hashes and rejected source drift during qualification. The A1 source was later committed and retired; the recorded base revision alone was not qualification evidence. Remote GitHub CI had not been run at the time.

Availability Review Follow-up

Both portal-service availability findings are fixed:

• The broker listener starts TLS handshakes and certificate extraction in separate tasks, capped at 128 pending handshakes with a five-second timeout per task. Silent peers do not serialize acceptance. A real mTLS regression keeps four earlier TCP connections idle while an authenticated request completes.
• Broker redemption and renewal use their existing transaction connection for session authority, live claims, custom-claim sources and signing-key reads. They never acquire another pool connection while holding rotation locks. Twelve concurrent redemptions, then twelve concurrent renewals, complete with a one-connection pool alongside ordinary issuance. Strict reuse detection is preserved.

The complete short gate suite passed again on a fresh isolated PostgreSQL database: 21 OAuth unit tests, explicit live-authority and workload-compatibility tests, and real HTTPS/mTLS broker integration including the new contention regression. Source hashes for this follow-up identify this tested revision. The earlier image receipts and partial soak describe older source; no images or soak were rebuilt/rerun for this follow-up. The deployed scheduled and hours-long runs remain pending, and the A1 exit gate has not passed. The subsequent Workflow/client review below refines pre-request error classification.

Workflow And Client Review Follow-up

All five light-fabric findings are addressed:

• Periodic recovery logs store failures and retries; it no longer terminates the managed task and closes unrelated Workflow admission. Startup configuration validation remains strict.
• Connection refusal, TLS establishment failure and pre-request JWKS failures return NotSent. The same live owner atomically records NOT_SENT and restores ACTIVE without changing the token or generation. Later caller attempts may retry. Post-send failures and lost ownership still fence the grant.
• Verification keys are cached for five minutes before rotation, with one refetch for an unknown key ID. A post-rotation verification failure remains uncertain; issuers must publish new keys before using them.
• Canceling one run preserves a valid committed shared-grant rotation and denies only that run’s token. A sibling run can renew; grant revocation and owner fencing still reject late responses.
• At that time, credentialBroker.legacyLongLivedAppKeys configured approved local issuer/key pairs for markerless app fixtures. It defaulted empty, applied only to X-Scope-Token, and cannot override explicit invalid purpose markers or authenticate a user. Former distribution preparation scripts carried the setting.

Short gates passed on a disposable PostgreSQL database with actual HTTPS/mTLS: 21 OAuth unit tests, explicit live-authority/workload tests, full broker integration, 80 Workflow library tests, 20 light-client tests, 17 security tests, two purpose contract tests, and two preparation tests. The integration exercises refused and failed-TLS connections without token POSTs, JWKS outage/rollover, post-rotation verification failure, recovery store failure, sibling-run cancellation, and the actual API legacy-key allowlist. Source hashes identify this follow-up. No soak or deployed-stack acceptance was run. Both previous image receipts predate these fixes and require rebuilding/requalification. At that stage, the credential-store SQL (the NOT_SENT result constraint) and issuer database patch were prerequisites for the then-current images. Both broker paths were retired later. No live database or service was changed in this follow-up.

Local Database Migration Applied

At this historical migration checkpoint, the local all-in-lt PostgreSQL instance had the issuer patch in configserver.configserver and the credential migration in the newly provisioned workflow_credentials.workflow_secret. All seven issuer tables, five credential tables, the NOT_SENT constraint, runtime password authentication and restricted role privileges were verified. Cascade validation passes after repairing three stale A2A schema references and adding four missing canonical gateway policies. Migration receipt records hashes and checks without secrets. The runtime URL is in the ignored mode-0600 file portal-config-loc/all-in-lt/postgres-db/secrets/workflow-broker-database-url. That file was an input to the retired broker preparation, not a current setup input.

This supersedes earlier statements that no live database was changed. No images were rebuilt and no application services were restarted. Broker registration, certificates, configuration activation and selected-stack qualification remain pending; the broker profile is not enabled by this migration alone.

Historical local broker activation

The user rebuilt the issuer and Workflow images. At the time, the local broker was enabled with a dedicated private client CA and a registered 180-day client certificate. The existing local issuer HTTPS certificate is used for its internal server and localhost callback. Private mounts remain ignored by Git, directories 0700 and files 0600, owned by the measured service UID/GID 999:999. No user grant was created.

The catalog and instance configuration were imported through event-importer using the registered ConfigInstanceCreatedEvent with commandkind: MUTATION for the instance property. Workflow snapshot 04c798da-c95b-499f-9167-a86bd248a145 is active. The broker JWKS URL uses light-oauth:6881 inside Docker; its authorization URL uses localhost:6881 for the browser. The local legacy app exception is restricted to the verified LC signing key. OAuth and Workflow were recreated and are healthy with zero restarts. Registered mTLS reaches grant lookup; no certificate fails TLS, wrong client and secret-only broker authentication return 401. JWKS returns 200. The callback returns 400 without state/code over verified HTTPS.

Activation receipt records image IDs, snapshot IDs and certificate fingerprint from that historical activation. At the time, deploy-local.sh lt included a broker overlay when the ignored workflow-broker/.runtime/enabled marker existed; the overlay was later removed. At the time, the host system trust store did not trust the local issuer CA; explicit CA-file verification passed. The browser consent path was later retired.

This activation supersedes the historical no-import/no-restart statements above. The live preflight returned nine unclassified names on four clients: Support Triage Local Demo, Tech Support LLM Workload Dev, mcp379-local-qualification and pylon. No claim-source classifications were changed. The broker has no custom claims, so these do not block its registration or activation.

Superseded selected-stack acceptance plan

The former selected-stack plan called for reviewing custom-claim sources, enrolling a user through Gateway and a browser authorization flow, and running scheduled and hours-long renewal qualification. Those steps were not completed as an A1 exit gate. Workflow Invoke subsequently retired that enrollment flow, so this plan is no longer a deployment or test procedure.

The A1 implementation described here was later committed and retired.

Authorization A2 Implementation Progress

Historical progress snapshot. The broker grant, enrollment, and renewal paths described below predate Workflow Invoke and were later retired. See Workflow Invoke for current Gateway-to-Workflow invocation and LONG registration. The old gates below are not instructions for the current stack.

Historical status: the A2 source foundation and selected personal coding paths were implemented, and all selected services, including both workflow-only Agents, passed local runtime qualification; selected-stack A2 acceptance had not passed. At that checkpoint, the remaining authorize/begin/send/complete, renewal, revocation, receiver and recovery matrix was still required. This record did not admit personal orchestration Phase 1.

Historical implemented foundation

• workflow-action defines server-owned action bindings, canonical attempts, owner/boot/fencing identities, exact-byte request digests and child-lineage validation. Opaque references resolve stored permits; callers cannot supply replacement depth, class, grant or budget authority.
• The PostgreSQL ledger implements authorize, begin-dispatch, completion and status. Concurrent duplicates replay the same authorization; only a new SEND_INTENT acknowledgement permits initiation. Owner-bound NOT_INITIATED completion releases once and permits a new authorization generation. Historical completion receipts cannot release a newer reservation. UNCERTAIN cannot become retryable by lease expiry.
• Migration 0007_workflow_action_dispatch adds authority, permit, dispatch and audit tables. It is present in canonical operational-store schema bundle 2.2.0, with matching manifest/order/checksums. That schema-bundle version is independent of the container image release tag; the selected deployment uses image tag 2.3.5-dev.20260909.2338. The local operational database has the schema and its canonical migration-ledger receipt.
• light-security::dual_identity checks separate user/app purposes, explicit issuer/audience/tenant, route-approved app service IDs and verified TLS peer fingerprints. Duplicate/coalesced credential headers are rejected. Workflow and receiver origins require an action reference. Missing verified peer context is rejected before any issuer/JWKS work. This helper does not replace route policy authorization.
• light-axum::mtls provides a certificate-verifying listener with bounded, concurrent handshakes and peer fingerprints from TLS, not forwarded headers.
• Workflow has a dedicated, optional mTLS action API and a fixed HTTPS control client in light-client. Authorize/begin/status verify user claims and hold broker grant/run read locks while checking the ledger. Completion authenticates the original service/peer without requiring an unexpired user token.
• workflow.actionAuthorization defaults to null. Enabling the listener requires the action migration, broker and strict JWT expiry verification. This switch alone does not establish a working A2 deployment.
• Pingora core 0.8.1 is vendored with an optional socket-level guard below TLS and buffering. Connection/TLS preparation precedes the guard; deadline check and first socket poll happen synchronously. Cancellation/expiry fences cleanup writes. Guarded HTTP/2 and unknown/custom transports fail closed.
• The proxy patch passes an optional guard to HTTP/1 and disables its default reused-connection retry for guarded requests. The new guarded_http adapter makes one connection attempt and one guarded send, with bounded response size and timeout, no redirects and no retry loop.

Verification performed

These are source/foundation checks, not deployed-stack acceptance:

The PostgreSQL test uses its own disposable database, not the live operational or credential stores. It covers simultaneous duplicate authorization/begin, conflicting owners and changed bindings, opaque-reference mismatches, non-initiation replay and reservation release, stale decisions, cancellation in the foundation authority table, uncertain outcomes, child-run lineage, and idempotent qualified-receiver reconciliation with conflicting evidence rejected. The second pass extends this test to actual invocation cancellation and the existing budget ledger, as described below.

Transport tests cover real plain connection reuse, TLS buffering after expiry, pending writes, cancellation cleanup, and partial-send failure of a replayable body without reconnection in the adapter. Full Gateway proxy-path first-write and partial-write failure tests, with its actual retry configuration, remain pending.

Reproducible bounded checks are in scripts/run-authorization-a2-foundation-gates.sh. The PostgreSQL test requires an explicit empty disposable database URL; absence is reported as not run. No A1 soak is started by this script.

Integration added in the second implementation pass

This pass adds real call-site wiring, but does not complete A2.

• Invocation admission accepts renewableGrantId only in the explicitly enabled A2 profile. The broker checks the exact consent binding, and the operational transaction installs run authority alongside invocation acceptance. Repeated broker run binding requires the same grant, user, tenant, work binding and expiry. Consent binding is {profile: "workflow-action-v1", workflowDefinitionId, definitionDigest, policyDigest, responsePolicyDigest}.
• The action ledger locks the actual workflow_invocation_t and workflow_invocation_budget_t records. Actual cancellation, deadline, policy, subject and budget-generation checks now apply. Action reservations charge the existing nested-call, byte and cost counters. Non-initiation refunds once; uncertainty retains the reservation. Initiated effects conservatively consume their configured byte/cost bounds until qualified actual-cost receipts exist.
• bound_mcp::Runtime is installed on the Workflow executor when A2 is enabled. It resolves the published dependency, renews through the broker, creates the action permit, and sends the original user credential plus the Workflow app credential over mTLS. Model-supplied authorization headers are not used on this path. The current producer supports root-run MCP tool actions only.
• Workflow’s dedicated mTLS action listener also serves protected invocation routes. The ordinary listener rejects A2 invocation requests without verified peer context. Retrieval/cancellation/result routes receive the same strict user/app check. Existing route-level invocation authorization still applies.
• Gateway loads the restart-required gateway.workflowActions profile from workflow-actions.yml. Its TLS listener requests certificates from the configured client CA; ordinary browser connections may omit a certificate, but strict MCP routes require an approved verified peer. Origin is classified from verified credentials. X-Workflow-Grant selects a grant for root invocation; it is only a reference, and Workflow verifies the actual consent binding.
• The MCP request context now carries the verified A2 caller. Private targets inspect the stored action and require matching stable tool and contract metadata. Existing MCP policy and argument-mapping checks are retained. HTTP-tool and stateless MCP backend branches call the fixed action client and guarded transport. The destination registry checks the exact outbound URL. Platform credentials are stripped for destinations not configured for original user forwarding.
• Gateway boot registration is durable. The client generates a fresh boot ID; Workflow assigns a fencing generation. Repeated registrations replay, while a superseded boot cannot regain ownership. Authorize, begin and completion lock the current owner within their dispatch transaction. A new replica/boot can query latest state without acquiring send permission for an uncertain effect.
• Gateway does not treat HTTP 202 Accepted, informational responses or redirects as terminal execution evidence. These responses retain an uncertain reservation and do not complete the Workflow step. A focused regression test covers these classifications. Target-receipt reconciliation remains pending.
• The socket guard now checks the deadline throughout request writes, including after a successful TLS control-record write. This conservative implementation also bounds request-body writing to the lease; response reads may take longer.

The PostgreSQL test now installs the real Workflow schema and constraints, seeds an actual invocation/budget, and tests real cancellation, reservations and boot replacement. It passed. Workflow’s 81 tests, invocation-contract’s 4 tests, and proxy-framework’s 448 tests passed (5 existing proxy tests ignored). The core socket guard now has 5 passing tests. Combined Workflow/Gateway compilation passed. These checks do not constitute an end-to-end A2 deployment test.

Integration added in the third implementation pass

• Nested Workflow starts now carry parentActionId. Gateway derives depth, execution class and deadline from the verified parent binding, sends the child start through the guarded action transport, and includes the parent in its idempotency digest. Workflow proves the current Gateway owner and SEND_INTENT, verifies the child invocation fields, records parent action/run lineage, and inherits the exact renewable grant without copying refresh material.
• Workflow service Agent jobs are limited to bound coding/workspace inputs in the A2 profile. Separate interactive and workflow Agent instances use immutable service/definition/origin configuration, distinct credentials and verified mTLS listeners. Interactive instances do not consume the workflow job queue; workflow instances reject Chat, A2A, UI and upload ingress. Workflow checks the job’s live invocation, grant, cancellation, deadline, depth and exact published Agent definition both before turn creation and before coding dispatch.
• Knowledge has an optional restart-required receiver profile and dedicated mTLS listener. Gateway forwards the current user token, its own scope token and the opaque action reference only to approved internal targets. Knowledge verifies Gateway user/app/peer identity, then uses its separate receiver identity to ask Workflow for the live action binding. Exact tool/contract/policy/disclosure mappings are checked before existing Knowledge user/resource ACLs run. When the profile is enabled, failure cannot fall back to the old lad1 delegation.
• The frozen complete contract also accepts a qualified receiver receipt for an already UNCERTAIN generation. Workflow authenticates the receiver app and exact mTLS peer, checks its registered tool set, and accepts only terminal evidence for the same generation. Identical receipts replay; conflicting evidence fails; the retained reservation is settled once. Receivers cannot authorize or begin a dispatch through this path.
• Gateway terminal-response classification is target-specific. Informational, redirect and generic 202 responses are not completion evidence. A Workflow child 202 qualifies only when its bounded response contains the exact stable tool, a non-nil instance and a positive durable state version.

Selected-stack runtime check on 2026-09-14

After rebuilding the selected local images and restoring the disposable operational schemas, ./scripts/deploy-local.sh lt start exited successfully and reported that the required Compose services passed runtime qualification. PostgreSQL, Config Server, Workflow, Gateway, Knowledge Admin, and the ordinary interactive Agents were running; Gateway loaded its authorization policy and registered with Controller.

On a subsequent 2026-09-14 run, both workflow-only snapshots were published, their app credentials gained the required execution.invoke scope, and both services registered with Controller without execution-result authorization errors. The deployment qualification contract now includes both services when the A2 profile is active. This is still not the A2 exit gate: no complete authorize/begin/send/complete, renewal, revocation, receiver receipt, or recovery matrix was completed in that run.

Required work before A2 acceptance

1. Exercise the two workflow-only Agents through real Workflow job admission, coding dispatch, cancellation and result reconciliation. Startup and Controller registration alone do not qualify those paths.
2. Connect any asynchronous effect receiver that needs automatic recovery to the qualified complete receipt contract. Synchronous Knowledge responses and durable Workflow acceptance have immediate receipt policies; other unknown effects correctly remain non-retryable until their receiver supplies evidence.
3. Add and run the complete A2 integration/security/race matrix against the real receiving and sending paths. Existing regression suites predominantly exercise the default profile; they are not evidence that the new enabled profile works end to end. GitNexus reports critical aggregate change risk because Gateway and Workflow entry points, MCP dispatch, and Agent/Knowledge admission are all in scope. Do not remove legacy delegation before its replacement qualifies.

Deployment state

The qualified-receiver completion contract is frozen. The local database contains the A2 action migration and receipt. Portal contains separate codex-wf and claude-wf definitions with service IDs com.networknt.agent.codex-personal-workflow-1.0.0 and com.networknt.agent.claude-personal-workflow-1.0.0. Portal and runner-local workspace bindings use authorization revision 3 and grant both interactive and workflow-only identities. The local distribution has an enabled, ignored A2 runtime package containing marked app credentials, mTLS identities and exact peer mappings; the installer contains the matching non-secret provisioning assets. The rebuilt selected services pass local runtime qualification, including the workflow-only identities. Their full A2 action and job paths remain unqualified. No commit or push was performed.

The 2026-09-13 local inventory confirms that the published Codex and Claude coding profiles and the owner workspace grant the existing com.networknt.agent.codex-personal-1.0.0 and com.networknt.agent.claude-personal-1.0.0 identities. Those running definitions already have pre-A2 history and cannot be relabeled as workflow-only instances. Those identities remain interactive. The separately published workflow-only definitions preserve their history boundary; configuration aliases or a caller-supplied origin header cannot cross it.

Authorization A3 Migration and Removal Progress

Historical progress snapshot. This record predates Workflow Invoke and the retirement of the A1 credential broker. Its grant-backed enrollment and renewal gates are superseded; see Workflow Invoke for the current invocation and LONG credential flow.

Historical status: A3 had started; removal was not yet safe. The selected local A2 stack used separate workflow-only Agent identities, and grant-backed action invocations no longer persisted the caller’s reusable access token in ordinary Workflow invocation state. The complete A2 integration matrix and A3 consumer drain remained open at that checkpoint.

First migration slice

• Workflow action admission still authenticates the current user and immediate caller, binds the run to the approved renewable grant, and records the action authority and dispatch ledger.
• For the dedicated grant-backed action listener, user_authorization and user_authorization_exp are inserted as null. The broker remains the source of fresh credentials for bound MCP actions and workflow Agent jobs.
• A later authenticated status read cannot repopulate a deliberately null token. Ordinary interactive invocations retain the existing token behavior until a qualified non-durable credential handoff replaces it.
• Terminal cleanup remains idempotent. Existing active rows have not been rewritten: rows with valid grant authority must be migrated, while legacy rows without it must drain or be reauthorized.

Selected-stack credential inventory

The local preparation tool generates separate app tokens and mTLS material for these identities. Gateway and Workflow keep portal.r portal.w; only the two Agent identities receive execution.invoke. Private PKI remains runtime-owned and is not checked into Git.

Legacy authority still present

The agent-delegation crate still has five direct package consumers: light-agent, light-workflow, light-gateway, light-knowledge, and light-pingora. Workflow still has signer configuration; Gateway and Knowledge still verify legacy delegation; Pingora still derives nested workflow context from it. The Agent now requires its legacy signer only when a direct Knowledge endpoint is configured, which removes the dependency from workflow-only Agents without weakening configured Knowledge access.

agent_delegation_replay_t also remains in the Agent operational schema and its validation/reset tooling. It cannot be dropped until old attempts are drained and the workflow_action_dispatch_t evidence/recovery path passes the selected stack’s first-write, partial-write, uncertainty, restart and receiver-receipt tests.

Superseded gate plan before removal

The following list records the former A3 plan and is not a current rollout procedure.

1. Run the complete A2 authenticated action matrix, including workflow Agent and Knowledge paths, cancellation, unauthorized callers, nested depth, private targets and effect recovery.
2. Qualify enrollment, scheduled renewal, rotation, revocation, permission changes and crash recovery against the selected issuer profile.
3. Migrate active grant-backed invocation rows to null token storage. Drain or explicitly reauthorize active legacy rows that have no valid grant authority.
4. Replace each remaining Gateway/Pingora/Knowledge delegation decision with the live action and receiver contracts, then prove no legacy consumer remains.
5. Remove signer/verifier configuration and deployment secrets in one coordinated rollout. Only then remove agent-delegation and apply a migration that drops agent_delegation_replay_t while retaining the action ledger and unresolved dispatch evidence.

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.

LLM Gateway

Status: design proposal, 2026-09-19. Nothing below is implemented. It records the intended direction for the LLM data plane as agent traffic grows beyond single request/response routing, and the boundary decisions that follow. The current implementation boundary is recorded at the end of this document; do not read any section here as a description of shipped behaviour.

This document covers the LLM data plane shared by every agent profile. The per-feature agent lifecycle lives in Light-Agent Execution, and durable business process state lives in Light-Workflow Runner.

Decision And Scope

Agents address one normalized inference interface. The gateway owns provider adaptation, routing, admission, usage accounting, and audit. It does not own the semantic content of an agent’s conversation.

Two deployment profiles are recognized as first-class, not as a temporary split. In the enterprise profile the gateway is inline on the inference path. In the personal/subscription profile the model call egresses directly to the provider and the gateway is a control plane only. The same agent binary must work in both; the only difference is whether the model call passes through the gateway.

Context caching, compression, and compaction are in scope as derived optimizations over content the agent supplied. Authoritative ownership of conversation state is out of scope for third-party agents, and optional for first-party agents.

Ownership

The gateway never decides what is semantically safe to drop from a conversation. It cannot see task intent, and a silent semantic edit surfaces later as an unexplained agent failure with no traceable cause.

What A Standard Interface Can And Cannot Do

A normalized wire interface is achievable and worth building. Model portability is not achievable at the wire level, and the design must not assume it.

When a coding agent degrades against a different provider’s model, the cause is usually post-training, not protocol shape. Frontier models are trained against specific tool schemas, specific edit formats (str_replace versus whole-file versus unified diff), specific shell interaction patterns, and specific reasoning-token semantics. Normalizing the envelope does not normalize any of that away.

The useful consequence is that the per-model adaptation layer belongs in the gateway: tool-schema dialects, prompt scaffolding, preferred edit format, reasoning handling, and cache-breakpoint placement. The agent addresses one interface; the gateway owns what each model needs in order to perform well. crates/model-provider already carries per-provider adapters along these lines, including CLI-shaped providers.

An agent must therefore be able to ask the gateway for its adaptation profile without issuing an inference request, because in the subscription profile the agent applies that profile itself before calling the provider directly.

Context Ownership

The Stateless API Reality

The Anthropic Messages API and OpenAI Chat Completions are stateless: the client sends the complete message array on every turn. An agent that “manages context” is deciding what to place in that array, not holding a server-side session. There is consequently no authoritative conversation on the gateway that could drift out of sync with the agent’s — the agent restates the whole conversation on every request.

OpenAI’s Responses API with previous_response_id is the exception. Treat any provider-side conversation state as pass-through; do not attempt to mirror it.

Derived State, Not Synchronized State

Derived state cannot desynchronize; authoritative state can. Whatever the gateway retains about a conversation must be a pure function of what the client sent, keyed by content digest. If a retained entry ever disagrees with the incoming request, it is discarded and recomputed. No synchronization protocol is required, or permitted.

The derived mode is the one that covers the fleet and is therefore the one that ships first. The authoritative mode buys simpler first-party agent code and fewer bytes on the agent-to-gateway hop; it does not buy anything the derived mode cannot already deliver on the inference path, and it converts a horizontally scalable stateless service into a sticky one. Adopt it only for first-party agents, and only after the derived path is qualified.

Compress On Entry, Then Freeze

Provider prefix caching requires the cached prefix to be byte-identical across requests. Rewriting earlier turns to save tokens is the single most cache-destructive operation available, so token reduction and cache-hit rate are in tension unless reduction happens exactly once, at the point new content first enters the context.

The rule is: compress a tool result the first time it arrives, then never touch it again. Tool results — file contents, test output, build logs, search dumps — carry nearly all of the reducible volume in an agent loop, and each one is appended exactly once.

Three requirements follow, and the second is a performance trap rather than a correctness one:

1. The compressor is a pure deterministic function, versioned, and pinned per session. Upgrading a compressor mid-session invalidates every downstream cache entry and mutates history under the model.
2. The mapping from original content digest to compressed bytes is cached. A naive implementation recompresses the entire accumulated history on every request; by turn eighty of a coding session that is significant latency for no benefit. This cache is what makes the derived mode viable, not merely correct.
3. Anthropic cache_control breakpoints are placed by the client. Rewriting content beneath them can strand a breakpoint mid-prefix and lose the cache the rewrite was meant to protect. Breakpoints must be re-placed as part of the same deterministic transformation.

Accept one consequence deliberately: after a rewrite, the agent’s record of what it sent no longer matches what the model saw. This is usually harmless, but it invalidates agent-side token accounting and any client-side caching the agent performs.

Sealing Instead Of Storing

Where the gateway must carry state across turns without becoming stateful, prefer the sealed-envelope pattern already used by reasoning_seal.rs: authenticated, encrypted state bound to tenant, alias, and route, returned to the client and replayed on the next request. This keeps the data plane horizontally scalable and gives the same recovery properties as a stateless service. A compression dictionary version, a compaction generation, or a context digest chain can travel this way.

Compaction Is Agent-Initiated

Deterministic, structural reduction is a gateway concern: it is task-agnostic, reversible in principle, debuggable, and safe. Semantic reduction — deciding that a file read forty turns ago no longer matters — is an agent concern, because only the agent knows the task.

A background process that rewrites live context with a cheap model is explicitly rejected. It is lossy, it is invisible at failure time, and it destroys the prefix cache it is nominally protecting.

The supported flow is a signal, not an action: the gateway reports context pressure and may propose a compaction; the agent decides and issues it. A compaction is then a deliberate new prefix whose cache cost is amortized intentionally, rather than a random invalidation.

Two Levels Of Context

Process context and conversation context are separate, with separate owners and lifetimes.

flowchart TD
    W[light-workflow: durable process context] --> S1[Step: agent A, model M, resume session X]
    W --> S2[Step: agent B, model N, new session Y]
    S1 --> G[llm-gateway: per-session conversation]
    S2 --> G
    G --> P[Provider inference and prefix cache]

light-workflow owns which step is active, which agent and model serve it, and whether the step resumes an existing session or starts a new one. It does not observe individual model interactions.

Session identity is workflow-issued, not gateway-generated, so the workflow can resume, fence, and cancel deterministically, consistent with the claim and fencing semantics in Light-Workflow Runner.

A session must be reconstructable from durable inputs. If the gateway loses conversation state, the workflow replays accepted artifacts to rebuild it; a lost cache degrades cost and latency, never correctness. This is the same principle applied to phase handoffs in the development workflow design, where a new stage reconstructs from accepted artifacts rather than depending on a surviving conversation.

Transport

Retain request/response HTTP with a session identifier, and SSE for streaming. Do not adopt WebSocket for the inference path.

A persistent connection is not required for server-side context retention; a session header achieves the same thing, and HTTP/2 already keeps connections warm. WebSocket earns its cost only when the server must initiate messages.

The cost is specific to this platform. Authorization is per-request today — dual identity, scope tokens, and action authorization, qualified as part of the workflow authorization work. Moving the inference path onto long-lived connections means re-implementing authorization at the message level inside a connection, plus reconnect and resume semantics, and it complicates load balancing and per-request tracing. That is a meaningful security surface in exchange for a capability a header already provides.

Revisit only if server-initiated push becomes a real requirement.

Deployment Profiles

Subscription credentials authenticate a consumer plan and are bound to the provider’s own endpoint. Routing that traffic through a proxy is a licensing and account-standing question, not merely a technical one, and it is not a posture this platform will adopt on a customer’s behalf. API-key traffic carries no such constraint.

This is not a concession. Unattended, automated workflow traffic is precisely what consumer subscriptions exclude, and the personal pilot design already records that personal subscriptions do not authorize Portal or API access. The enterprise product is the API-key path, where the gateway is inline by construction. Subscriptions serve the interactive personal profile.

The routing decision remains centralized even where the data path is not: the gateway and workflow decide that an interactive job runs on a developer’s own subscription seat while an unattended job runs API-key through the gateway. Centralized decision with a bypassing data path is a supported outcome, not a degraded one.

Packaging

Build a separate llm-gateway binary composing the shared crates. Do not continue growing the LLM data plane as middleware inside light-gateway.

The LLM data plane and the API data plane have diverging runtime shapes. The API gateway is stateless and request-scoped. The LLM path already holds long-lived streams, large per-request bodies, replay buffers, an embedding admission lane with multi-gigabyte ingress bounds, and its own audit WAL; adding context retention makes it durably stateful. Capacity for the two scales on different axes — requests per second against concurrent sessions and token volume — and co-tenancy means planning for the worse of both. Memory pressure or an OOM on the LLM path should not remove API routing.

The split is cheap today because the crate boundary already exists and is already thin: crates/llm-gateway carries the runtime, streaming, routing, usage, and audit surfaces, while apps/light-gateway references llm_gateway:: in a small number of places. A separate binary is largely a new composition root over light-pingora, llm-gateway, and config-loader, not a refactor. That apps/light-gateway/src/main.rs has grown past half a megabyte is a further argument against adding responsibility to it.

The real risk of splitting is divergent security middleware, and it is manageable only if handled deliberately: the shared security and authorization chain must live in a crate that both binaries compose, never reimplemented in the new one. The documented handler order — correlation, unified-security, limit, access-control, then the LLM handler — must remain a single shared definition. If that chain cannot be factored cleanly, treat the difficulty as a signal to defer the split rather than to fork the middleware.

Trigger: split when the first durably stateful feature lands, which is the session context store described above. That is the point where the runtime profiles genuinely diverge.

Current Implementation Boundary

Checked 2026-09-19 against the working tree.

Open Questions

• Whether the adaptation profile is served as a typed API for subscription agents, or compiled into the agent from the same immutable snapshot.
• Whether compression dictionaries are per-tenant or global, and how a dictionary version is pinned across a long session without a stateful store.
• How usage reconciliation from provider telemetry is attributed to a workflow step when the gateway never observed the call.
• Whether first-party authoritative sessions justify their operational cost at all, once derived-mode compression is qualified.

References

• Light-Agent Execution
• Agent Engine Pattern
• Light-Workflow Runner
• MCP Router
• Handler Chain
• PII Tokenization
• User, Application, And Workflow Authorization
• Personal Development Workflow Orchestration

Light CLI

Status: implemented in apps/light-cli (binary light). Revised 2026-09-22: the CLI is a public client. It has no certificate and no enrollment: it signs the user in with the OAuth device grant and calls the Gateway with the user’s own access token alone. It still carries the dev application token (below), a public identifier that config-server and, later, controller-rs ask for. The sections that describe a per-install certificate, the bootstrap token, the issuer, renewal and the dual-identity contract for the CLI (Identity Model, The Peer Pinning Problem, Enrollment And Revocation, and the flow in Bootstrap And Connection Flow) record the design this replaced; they still describe how a controlled workload (an agent, a runner) is enrolled, and are kept for that and for history. See Revision 2026-09-22.

This document covers a first-party command-line client for workflow interaction: starting stages, answering human-in-the-loop decisions, and operator recovery. The web surface in portal-view remains the primary interface for enterprise approvers; see Interfaces And Personas for the boundary between them.

Revision 2026-09-22: A Public Client

The first design gave every install a certificate from light-identity-issuer, enrolled once with an app token packaged in the download, and had the Gateway trust the CLI by CA. The reasoning was that the application leg tells the Gateway which program is calling. That does not survive an open-source, downloadable client:

• The enrolling credential ships in a download anyone can take, so anyone can enroll. A certificate proves that some program enrolled, not that it is the real CLI. It is friction, not a defence, and the same is true of the app token itself.
• OAuth’s guidance for native apps (RFC 8252) is the same: they cannot keep secrets, so they are public clients acting for a user. That is how portal-view’s browser already works: it holds no application credential either.
• The certificate cost a CA, a bootstrap secret, Gateway trust configuration and a renewal protocol, for no security the user’s own token does not already provide.

So the CLI carries only the user’s login. What it may do is decided by that user’s roles and the route’s ACL, never by a claim about which program it is. Consequences:

• CLI: no bootstrap or renew, and no key or certificate store. Exit code 4 (“not enrolled”) is retired. It keeps the long-lived dev application token in start-cli.sh (checked in on purpose, so a checkout works out of the box). That token identifies the program, is public by nature (it ships in a download) and authorises nothing on the user’s behalf. It is what the services that ask “which application is this” are given: the config server today (it reads the CLI’s settings with it), and controller-rs when the CLI registers. It is never sent to the Gateway or to light-oauth, and the tests check that.
• Gateway: /mcp with workflow actions enabled used to require an app token, a verified peer and a user token from every caller. RoutePolicy.interactiveUserOnly (off by default) admits a caller that presents no application credential on its user token alone, as an interactive caller with no action reference. A caller that does present one is judged exactly as before, and a request that claims a workflow action without one is refused. See dual_identity::admit.
• light-identity-issuer stays, for agents and runners deployed in a controlled pipeline, where the delivery of the credential can be trusted.

Revision 2026-09-23: One Persistent Session

light is one long-lived terminal, like Claude Code, that stays open until /exit. The one-shot subcommands (light auth login, light gateway check, …) are gone; every capability is a slash command inside the session, and start-cli.sh just starts it. The reason is what the CLI is for: a workflow reaches a human-in-the-loop step and the person should see it and answer it where they already are, chat with an agent across many turns, and look at status and audit without a fresh process (and a fresh login check) per question.

• Commands (implemented): /login, /logout, /whoami, /agents, /chat [agent], /new, /disconnect, /tools, /help, /exit. Anything that is not a command is said to the agent you are chatting with; //x says a message that begins with a slash. The prompt shows the agent.
• Same engine three ways. The terminal (line editor, history, replies printed above the line being typed), piped input, and light -c '<line>' all drive one Shell, so a script behaves like a person and a test drives it line by line. In a script, a message waits for the agent’s reply before the next line runs, so /exit cannot cut it off. Exit code is that of the first failing line; /whoami when signed out counts (6), so light -c /whoami still answers “am I signed in”.
• Not a TUI. No full-screen layout, panes or mouse. It is a scrolling terminal with a prompt; ordinary terminal features (scrollback, copy, pipes) keep working.
• --json is gone with the subcommands. Structured output comes back per command when a command needs it for scripting; nothing asks for it yet.
• Agent chat (chat.rs) uses the Gateway’s /chat WebSocket as a native client: only Authorization: Bearer <user token>, none of what the Gateway takes for a browser (Origin, the CSRF cookie or subprotocol), and never the token in the URL. The frames are the ones portal-view’s chat page uses. When the login’s access token expires (authentication_required or close code 4401) it fetches a fresh token and reconnects with the same sessionId. A message the server may have accepted is never sent again automatically: the person is told whether it was refused (send it again) or may have arrived (check before repeating). Reconnects are bounded. Text from an agent is untrusted and is stripped of terminal control sequences (ESC, C1, bidi and zero-width characters) before it is printed.
• Approvals from the CLI are allowed, as the same audited operation the web UI performs, and each one will require explicit confirmation naming what is being approved. Not built yet.
• Agents come from cli.agentServiceIds (comma-separated service ids; the config server can set it). Discovery from the Portal’s instance registry is later, and needs /portal/query to accept a bearer token on the Gateway.

Next, in order: the human-task inbox (list, claim, choose an option, comment, complete, with confirmation), workflow status and audit views, log follow, then controller registration.

Decision And Scope

Provide a CLI, not a TUI. The CLI connects to light-gateway over the same MCP/action surface portal-view already uses, never directly to light-workflow. It authenticates as the signed-in user with a user access token (see the revision above; the original design also had a per-install certificate for an application leg, which was dropped).

The CLI carries no authority of its own. It acts as the signed-in user with that user’s existing grants. It never fabricates, auto-enrolls, or escalates a grant, consistent with the decision already recorded for the Portal enrollment prompt.

Out of scope: a full-screen TUI (the interactive session described in the 2026-09-23 revision is a scrolling prompt, not a TUI); replacing the worklist for enterprise approvers; direct access to Workflow’s internal routes; any long-lived static application secret distributed with the binary.

Interfaces And Personas

The CLI is additive. Where both surfaces expose an action they must call the same Gateway operation, so authorization and audit cannot drift between them.

Why Gateway, Not Workflow

flowchart LR
    CLI[light CLI] -- mTLS + user token --> G[light-gateway]
    WEB[portal-view] -- session + server ingress --> G
    G -- A2 profile, mTLS --> W[light-workflow]
    G -. CEL endpoint rules, Tool ACL, default deny .-> G

light-gateway is already the single authorization chokepoint: CEL endpoint rules, default-deny access control, Tool ACL, and the A2 workflow-actions profile that reaches Workflow over verified mTLS. Pointing the CLI there means one authorization implementation, one audit path, and no second copy of the policy chain to keep in sync.

Connecting directly to Workflow’s listener would bypass that chain, couple the CLI to internal route shapes, and require Workflow to grow a second caller contract. Both are rejected.

This also matches the commercial boundary: the CLI and Gateway are open source in light-fabric, while the policy that governs them — tenancy, grants, access-control snapshots, audit retention — is published by the commercial control plane. The client is free; the governed backend is the product.

Identity Model

dual_identity::authenticate requires, and this design does not weaken:

• a verified TLS peer fingerprint taken from transport context only, never a header or forwarded assertion, failing closed when absent;
• a registered application service ID whose profile lists approved peer fingerprints;
• a user bearer token validated against the route policy issuer and audience.

The CLI therefore needs two credentials, and neither may be embedded in a distributed binary:

The install certificate identifies the installation, not the person. The user token identifies the person. Neither alone is sufficient, which is the property that makes a stolen token or a copied binary insufficient on its own.

Registered origin is Interactive, alongside the existing Portal ingress identity — not Workflow, which additionally requires an action reference and is reserved for service-origin callers.

The Peer Pinning Problem

This is the decision the CLI forces, and it should be settled before implementation.

AppProfile.peer_sha256 is a list of exact SHA-256 leaf fingerprints, validated as 64 hex characters and required to be non-empty. That model is sound for a small set of long-lived services. It does not scale to a CLI: every developer installation produces a new leaf, so every install would append an entry to a published access-control snapshot, and every revocation would require republishing it.

Three options:

1. CA-based peer trust (recommended). Extend AppProfile with a variant that trusts an enrollment CA and requires a verified certificate attribute binding the leaf to the CLI service ID, plus revocation checking. Peer identity stays transport-derived and fail-closed; only the matching rule changes from “this exact leaf” to “issued by this CA for this service ID.”
2. Enrollment-managed fingerprint list (interim). Keep leaf pinning, and have enrollment append the new fingerprint to a CLI-specific service ID with a bounded list size and expiry. Acceptable for the single-VM pilot, operationally unacceptable at fleet scale.
3. Brokered ingress. A server-side component holds one application credential on behalf of many CLIs, as portal-view’s Vite ingress does today. This relocates the problem rather than solving it, adds a hop, and creates a trusted intermediary that can act for any user.

Recommend (1), with (2) as an explicitly time-boxed interim for the pilot. Do not adopt (3) for the CLI; the browser needed it because a browser cannot hold a client certificate, and a CLI can.

Obtaining The User Leg Without A Browser Redirect

Decided 2026-09-21: the RFC 8628 device authorization grant, served by light-oauth. The full design, the security analysis and the protocol are in light-portal-doc/src/design/light-oauth/device-authorization.md; this section records only what the CLI does with it.

The earlier options are superseded. A loopback redirect does not work on a VM without a browser; a pasted cookie or token does not either, because the browser session’s tokens are short-lived and the CLI cannot renew them; and Portal-initiated pairing needs a new code type. The device grant is the standard answer, covers cloud and enterprise sign-in (including SSO and MFA, which happen in the user’s own browser), and needs no browser on the CLI’s machine.

The CLI is a public client (no secret) of light-oauth, reached through the Gateway like everything else; the standard grant needs nothing else. It also presents its install certificate on those requests, so a Gateway that wants only enrolled installs to be able to start a sign-in can require it. The user approves on portal-view’s /device page. Signing in lasts one day, or 90 days if the user ticks “remember me”; both lengths are light-oauth server settings, the end is enforced by the server, and it does not slide. The CLI never prompts for a password, never opens a browser unless asked (--open, and never over SSH), and never accepts a token typed by the user. light auth login shows a code; the user approves it in any browser.

Enrollment And Revocation

Enrollment mirrors the runner enrollment precedent in controller-rs, which already issues a durable per-instance identity bound to an approved peer.

1. The CLI generates a key pair locally and produces a CSR. The private key never leaves the host.
2. Pairing (or device grant) authenticates the user leg and authorizes enrollment for that user and Host.
3. The broker issues a certificate bound to an install ID, user, and Host, and registers it under the CLI service ID according to the peer-trust decision above.
4. The CLI stores the install ID and credentials, and obtains short-lived access tokens thereafter.

Refresh is bound to the install certificate as proof of possession, so a captured refresh token alone cannot mint access tokens. The issuer records token fingerprints rather than bearer values, consistent with existing behaviour. Portal lists a user’s enrolled installs with last-seen data and can revoke one without disturbing the others; revocation must take effect at the Gateway without requiring a client to cooperate.

Credential storage uses the OS keychain where available and a 0600 file fallback otherwise. Credentials are never logged, never placed in argv, and never emitted in diagnostics.

Bootstrap And Connection Flow