# Wippy - Complete Documentation

# What Is Wippy? Concepts and Runtime Overview

## About Wippy


Wippy is an open-source actor-model runtime for applications whose behavior changes while they run. It is designed for automation systems, AI agents, plugin architectures, and other applications that need to evolve without rebuilding or redeploying the runtime.

The foundation is the actor model. Code runs in isolated processes that communicate through messages, with each process managing its own state. Supervised process services can be restarted according to their lifecycle policy.

```lua
local worker, err = process.spawn("app.workers:handler", "app:processes")
if not worker then
    return nil, err
end

local ok, monitor_err = process.monitor(worker)
if not ok then
    return nil, monitor_err
end

return process.send(worker, "task", {id = 1, data = payload})
```

Runtime definitions live in a central registry. For entry kinds dispatched through the event bus, registered handlers reconcile accepted changes without restarting the entire application. Some internal entry kinds intentionally bypass event dispatch.

```lua
local db, err = registry.get("app.db:postgres")
if not db then
    return nil, err
end

local cache, cache_err = registry.get("app.cache:redis")
if not cache then
    return nil, cache_err
end
```

For operations that must recover from infrastructure failures, durable workflows persist execution state. This model suits payment flows, multi-step processes, and long-running agent tasks that may need to resume after a restart.

The runtime is distributed as a single binary and configured through project files.

For the project overview and design notes, see [About Wippy](https://wippy.ai/about).



---

# "Installation"

### Install


```bash
curl -fsSL https://hub.wippy.ai/install.sh | bash
```

The install script requires a POSIX shell. On Windows, download the runtime from
[hub.wippy.ai/releases](https://hub.wippy.ai/releases) and place `wippy.exe` on
`PATH`.



### Verify


```bash
wippy version
```



### Initialize Dependency Metadata


```bash


## Create a project directory

mkdir myapp
cd myapp



## Create or update wippy.lock

wippy init
```

`wippy init` writes the dependency lock and its source and module directory settings. It does not scaffold application source files or registry entries. Follow [Hello World](tutorials/hello-world.md) to create a runnable application, then start it with `wippy run`.

The runtime includes HTTP, SQL, storage, and process-hosting capabilities. Add framework modules from the Hub when the application needs them:

```bash
wippy add wippy/test
wippy install
```



### Commands Overview


| Command | Description |
| --------- | ------------- |
| `wippy init` | Create or update `wippy.lock` |
| `wippy run` | Start the runtime |
| `wippy test` | Run the test entrypoint |
| `wippy lint` | Check code for errors |
| `wippy add` | Add a dependency |
| `wippy install` | Install dependencies |
| `wippy update` | Update dependencies |
| `wippy artifacts` | Materialize build-time filesystem artifacts |
| `wippy pack` | Create a snapshot |
| `wippy publish` | Publish to hub |
| `wippy search` | Search for modules |
| `wippy readme` | Fetch a module README from the hub |
| `wippy registry` | Inspect loaded registry entries |
| `wippy auth` | Manage authentication |
| `wippy version` | Print version info |

See [CLI Reference](guides/cli.md) for full documentation.



### Troubleshooting


If the shell cannot find `wippy` after installation, reopen the shell and verify that the installation directory is on `PATH`.



### Next Steps


- [Hello World](../tutorials/hello-world.md) — Create your first application
- [Project Structure](start/structure.md) — Understand the project layout
- [CLI Reference](guides/cli.md) — Review all commands and options



---

# "YAML & Project Structure"

### Directory Layout


```
myapp/
├── .wippy.yaml          # Runtime configuration
├── wippy.lock           # Source directories and locked modules
├── .wippy/              # Installed modules
└── src/                 # Application source
    ├── _index.yaml      # Entry definitions
    ├── api/
    │   ├── _index.yaml
    │   └── *.lua
    └── workers/
        ├── _index.yaml
        └── *.lua
```



### YAML Definition Files


<note>
YAML definitions are loaded into the registry at startup. The registry is the source of truth; YAML files are one way to populate it. Entries can also come from other sources or be created programmatically.
</note>



#### Definition File Format


A definition file contains a `namespace` and either an `entries` array or top-level `name` and `kind` fields. The optional `version` marker is conventionally `"1.0"`; the v0.3.32a loader does not require it.

```yaml
version: "1.0"
namespace: app.api

entries:
  - name: get_user
    kind: function.lua
    meta:
      comment: Fetches user by ID
    source: file://get_user.lua
    method: handler
    modules:
      - sql
      - json

  - name: get_user.endpoint
    kind: http.endpoint
    meta:
      comment: User API endpoint
    method: GET
    path: /users/{id}
    func: get_user
```

| Field | Required | Description |
|-------|----------|-------------|
| `version` | No | Manifest version marker (conventionally `"1.0"`) |
| `namespace` | Yes | Entry namespace for this file |
| `entries` | Conditional | Array of entry definitions; omit only when using top-level `name` and `kind` |



#### Naming Convention


Use dots (`.`) for semantic separation and underscores (`_`) for words:

```yaml


## Function and its endpoint

- name: get_user              # The function
- name: get_user.endpoint     # Its HTTP endpoint



## Multiple endpoints for same function

- name: list_orders
- name: list_orders.endpoint.get
- name: list_orders.endpoint.post



## Routers

- name: api.public            # Public API router
- name: api.admin             # Admin API router
```

<tip>
Pattern: <code>base_name.variant</code> — dots separate semantic parts, while underscores separate words within a part.
</tip>



#### Namespaces


Namespaces are dot-separated identifiers:

```
app
app.api
app.api.v2
app.workers
```

Entry full ID combines namespace and name: `app.api:get_user`



#### The Lock File


`wippy.lock` records where Wippy loads definitions from and which module versions are selected:

```yaml
directories:
  modules: .wippy
  src: ./src
options:
  unpack_modules: false
modules:
  - name: acme/http
    version: v1.2.0
    hash: 4ea816fe84ca58a1f0869e5ca6afa93d6ddd72fa09e1162d9e600a7fbf39f0a2
```

| Field | Description |
|-------|-------------|
| `directories.src` | Application source directory, scanned recursively for YAML definition files |
| `directories.modules` | Base directory for vendored modules; packs land under `<modules>/vendor/` |
| `options.unpack_modules` | Extract each `.wapp` into a directory beside it instead of loading the pack directly (default `false`) |
| `modules[].name` | Module identifier in `org/module` form |
| `modules[].version` | Selected version |
| `modules[].hash` | Artifact digest the vendored pack must match |
| `modules[].root` | Marks the selected deployment root; at most one module may carry it |

Vendored packs are kept as `.wapp` files. With `unpack_modules: true`, each module is also extracted into a directory, and the verified `.wapp` stays beside it — installation looks for the pack, so a directory whose pack is missing is downloaded again.

A `replacements:` section in `wippy.lock` is deprecated. It still loads, with a warning; declare local module overrides under `workspace.replacements` in a runtime config file instead. See [Dependency Management](guides/dependency-management.md#local-development-with-replacements).



### Entry Definitions


Each item in the `entries` array defines one entry. Kind-specific fields can appear beside `name`, `kind`, and `meta`, as in this example:

```yaml
entries:
  - name: hello
    kind: function.lua
    meta:
      comment: Returns hello world
    source: file://hello.lua
    method: handler
    modules:
      - http
      - json

  - name: hello.endpoint
    kind: http.endpoint
    meta:
      comment: Hello endpoint
    method: GET
    path: /hello
    func: hello
```

An explicit `data:` field is also supported. When present, its value is the complete kind-specific payload, so do not mix it with sibling kind-specific fields:

```yaml
entries:
  - name: config
    kind: registry.entry
    data:
      environment: production
      features:
        dark_mode: true
```



#### Metadata


Use `meta` for UI-friendly information:

```yaml
- name: payment_handler
  kind: function.lua
  meta:
    title: Payment Processor
    comment: Handles Stripe payments
  source: file://payment.lua
```

Use `meta.title` and `meta.comment` for descriptive information that registry consumers and management interfaces can display.



#### Application Entries


Use `registry.entry` kind for application-level configuration:

```yaml
- name: config
  kind: registry.entry
  meta:
    title: Application Settings
    type: application
  environment: production
  features:
    dark_mode: true
    beta_access: false
```



### Common Entry Kinds


| Kind | Purpose |
|------|---------|
| `registry.entry` | General-purpose data stored without normal event dispatch |
| `function.lua` | Callable Lua function |
| `process.lua` | Long-running process |
| `http.service` | HTTP server |
| `http.router` | Route group |
| `http.endpoint` | HTTP handler |
| `process.host` | Process execution host |

See the [Entry Kinds Guide](guides/entry-kinds.md) for the entry-kind reference.



#### .wippy.yaml


Runtime configuration at project root:

```yaml
version: "1.0"

logger:
  encoding: json

logmanager:
  min_level: 0

supervisor:
  host:
    worker_count: 16
```

See the [Configuration Guide](guides/configuration.md) for runtime configuration fields.



#### wippy.lock


Source directories and the selected module graph — see [The Lock File](#the-lock-file) above.



### Referencing Entries


Reference entries by full ID or relative name where the entry kind supports it. HTTP routers and endpoints attach through `meta.server` and `meta.router`, rather than through parent-side child lists:

```yaml


## Router declares itself against a server

- name: api
  kind: http.router
  meta:
    server: app:gateway
  prefix: /api



## Endpoint references router by registry ID (cross-namespace works the same way)

- name: get_user.endpoint
  kind: http.endpoint
  meta:
    router: app.api:api
  method: GET
  path: /users/{id}
  func: app.api:get_user
```



### Example Project


```
myapp/
├── .wippy.yaml
├── wippy.lock
└── src/
    ├── _index.yaml           # namespace: app
    ├── api/
    │   ├── _index.yaml       # namespace: app.api
    │   ├── users.lua
    │   └── orders.lua
    ├── lib/
    │   ├── _index.yaml       # namespace: app.lib
    │   └── database.lua
    └── workers/
        ├── _index.yaml       # namespace: app.workers
        └── email_sender.lua
```



### See Also


- [Application Architecture](concepts/architecture.md) — Organize an application into slices and layers
- [Entry Kinds Guide](guides/entry-kinds.md) — Review available entry kinds
- [Configuration Guide](guides/configuration.md) — Configure runtime options
- [Custom Entry Kinds](internals/kinds.md) — Implement handlers (advanced)



---

# "CLI Reference"

## CLI Reference


Use the Wippy CLI to initialize projects, run the runtime, manage dependencies, inspect registry entries, and publish modules.

This is a command reference. The examples assume an existing project or module
when the command operates on source, a lock file, registry entries, or publish
metadata; they are not a single end-to-end project.



### Global Flags


Available on all commands:

| Flag | Short | Description |
|------|-------|-------------|
| `--config` | | Config file, repeatable; later files override earlier ones (default: .wippy.yaml). `wippy publish` defines a different command-local option. |
| `--verbose` | `-v` | Enable debug logging |
| `--very-verbose` | | Debug with stack traces |
| `--console` | `-c` | Colorful console logging |
| `--silent` | `-s` | Disable console logging |
| `--event-streams` | `-e` | Stream logs to event bus |
| `--profiler` | `-p` | Enable pprof on localhost:6060 |
| `--memory-limit` | `-m` | Memory limit (e.g., 1G, 512M) |

Memory-limit precedence is `--memory-limit`, then `GOMEMLIMIT`, then the 1 GB default.

The global `--config` option may be passed multiple times to compose config files. Files merge left to right: later files override matching values and keep everything else. Every explicitly named file must exist; without `--config`, the default `.wippy.yaml` is optional. The first file anchors the directory used to resolve relative paths. Configuration applies in order: file composition, then `--profile` selections, then `--set` overrides. See [Configuration](guides/configuration.md#config-composition).

`wippy publish` shadows the global option with a command-local `--config <dir>` option. For that command, the value is the directory containing `wippy.yaml`, not a repeatable runtime configuration file.



### wippy init


Create `wippy.lock`, or update its source and module directory settings if it already exists. This command does not scaffold application source files or registry entries.

```bash
wippy init
wippy init --src-dir ./src --modules-dir .wippy
```

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--src-dir` | `-d` | ./src | Source directory |
| `--modules-dir` | | .wippy | Modules directory |
| `--lock-file` | `-l` | wippy.lock | Lock file path |



### wippy run


Start the runtime or execute a command.

```bash
wippy run                                   # Start runtime
wippy run list                              # List available commands
wippy run migrate                           # Run a named custom command
wippy run snapshot.wapp                     # Run from pack file
wippy run acme/http                         # Run module from hub
wippy run acme/http@1.2.3                   # Run specific version
wippy run --exec app:worker                 # Start runtime and execute a single process
```

| Flag | Short | Description |
|------|-------|-------------|
| `--override` | `-o` | Override entry values (`namespace:entry:field=value`); `field` may be `kind` to change the entry kind |
| `--set` | | Override a config value (`section.path=value`, repeatable, takes precedence over the config file) |
| `--exec` | `-x` | Execute process and exit (`namespace:entry`) |
| `--host` | | Terminal host ID for `--exec` (auto-detected if only one `terminal.host` exists) |
| `--registry` | | Registry URL for hub modules |
| `--profile` | | Apply a runtime profile from `.wippy.yaml` or packed runtime metadata (repeatable, applied in order) |

Running a hub module (`wippy run org/module`) resolves it once, records it in `wippy.lock`, and vendors the verified packs locally. Subsequent runs of the same reference start from the lock — no network needed. A version selector that no longer matches the lock is rejected with a hint to run `wippy update`.

For a local application, `wippy run` repairs a stale lock before any runtime service starts. It loads the source dependency declarations, and when the lock already satisfies them it re-resolves the graph from local and installed evidence only (verified-offline access, no network). If that offline resolution matches the lock, boot continues unchanged. If it succeeds but differs, it becomes the candidate graph; the hub is asked to resolve only when the offline pass fails or the lock no longer satisfies the source declarations. Packs the candidate graph is missing are downloaded and verified, and only then is `wippy.lock` rewritten. A lock that selects a deployment root is authoritative and is never re-resolved.

`--exec` blocks until the launched process produces its result, then propagates the process exit code as the CLI exit code. Ctrl-C during `--exec` cancels the running process and the runtime still shuts down gracefully; a second signal forces exit.

`--set` writes any runtime configuration value from the command line, merged over `.wippy.yaml` per leaf:

```bash
wippy run --set cluster.enabled=true \
          --set cluster.membership.join_addrs=node-2:7946,node-3:7946 \
          --set cluster.raft.bootstrap_expect=3
```

Values are coerced by shape: `true` and `false` become booleans, integers and floats become numbers, and other values remain strings. Fields that expect durations parse values such as `5s`.



### wippy test


Run the test entrypoint: the process entry declaring the `test` use case. The runtime boots, executes that entry, and exits. `wippy run` does not auto-run test entrypoints; testing always goes through `wippy test`.

```bash
wippy test                     # Run tests from the local project
wippy test snapshot.wapp       # Run tests from a pack file
wippy test acme/module@1.2.3   # Run tests from a hub module
```

| Flag | Short | Description |
|------|-------|-------------|
| `--override` | `-o` | Override entry values (`namespace:entry:field=value`) |
| `--host` | | Terminal host ID (auto-detected if only one `terminal.host` exists) |
| `--registry` | | Registry URL for hub modules |
| `--set` | | Override a config value (`section.path=value`, repeatable) |
| `--profile` | | Apply a runtime profile (repeatable, applied in order) |



### wippy lint


Check Lua code for type errors and warnings.

```bash
wippy lint
wippy lint --level warning
wippy lint --json
wippy lint --rules
```

Validates source-bearing `function.lua`, `library.lua`, `process.lua`, and
`workflow.lua` entries. Precompiled `.bc` entries do not contain parseable source
and are skipped.

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--lock-file` | `-l` | `wippy.lock` | Lock file path |
| `--level` | | `warning` | Minimum severity: `error`, `warning`, `hint` |
| `--ns` | | | Filter by namespace patterns (e.g. `app`, `lib.*`) |
| `--code` | | | Filter by error codes (e.g. `E0001,E0004`) |
| `--rules` | | `false` | Enable style/quality lint rules |
| `--summary` | | `false` | Group output by error code |
| `--limit` | | `0` | Max diagnostics shown (0 = unlimited) |
| `--json` | | `false` | JSON output |
| `--no-color` | | `false` | Disable colored output |
| `--cache-reset` | | `false` | Clear Lua cache before linting |
| `--profile` | | | Apply a workspace profile from the merged runtime config (repeatable) |
| `--set` | | | Override a merged runtime config value (`section.path=value`, repeatable) |



### wippy add


Add a module dependency.

```bash
wippy add acme/http
wippy add acme/http@1.2.3
wippy add acme/http@latest
```

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--lock-file` | `-l` | wippy.lock | Lock file path |
| `--registry` | | | Registry URL |



### wippy install


Install dependencies from lock file.

```bash
wippy install                            # Install all
wippy install acme/http                  # Install specific module
wippy install --refresh acme/http        # Re-fetch a specific module
```

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--lock-file` | `-l` | wippy.lock | Lock file path |
| `--refresh` | | false | Re-fetch the named modules, or every locked module when no names are supplied, bypassing cache |
| `--force` | | false | Alias for `--refresh` |
| `--repair` | | false | Alias for `--refresh` |
| `--registry` | | | Registry URL |
| `--profile` | | | Apply a workspace profile from the merged runtime config (repeatable) |
| `--set` | | | Override a merged runtime config value (`section.path=value`, repeatable) |



### wippy update


Update dependencies and regenerate lock file.

```bash
wippy update                      # Update all
wippy update acme/http            # Update specific module
wippy update acme/http demo/sql   # Update multiple
```

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--lock-file` | `-l` | wippy.lock | Lock file path |
| `--src-dir` | `-d` | ./src | Source directory |
| `--modules-dir` | | .wippy | Modules directory |
| `--registry` | | | Registry URL |
| `--profile` | | | Apply a workspace profile from the merged runtime config (repeatable) |
| `--set` | | | Override a merged runtime config value (`section.path=value`, repeatable) |



### wippy artifacts


Work with build-time filesystem artifacts.



#### wippy artifacts materialize


Validate and materialize one artifact filesystem out of an existing pack.

```bash
wippy artifacts materialize snapshot.wapp app:package_fs
wippy artifacts materialize snapshot.wapp app:package_fs --root build
```

| Flag | Default | Description |
|------|---------|-------------|
| `--root` | `.wippy` | Materialization root |

The resource is addressed by its full `namespace:name`, must declare `meta.artifact.format`, and that format must be registered in the CLI. The command resolves no module dependencies, does not mutate `wippy.lock`, invokes no package managers, and takes no part in runtime composition. See [Build-time artifacts](guides/artifacts.md#materializing-explicitly).



### wippy pack


Create a snapshot pack (.wapp file).

```bash
wippy pack snapshot.wapp
wippy pack release.wapp --description "Release 1.0"
wippy pack app.wapp --embed app:assets --bytecode "**"
```

| Flag | Short | Description |
|------|-------|-------------|
| `--lock-file` | `-l` | Lock file path |
| `--description` | `-d` | Pack description |
| `--tags` | `-t` | Pack tags (comma-separated) |
| `--meta` | | Custom metadata (key=value) |
| `--embed` | | Embed fs.directory entries (patterns) |
| `--embed-all` | | Embed all fs.directory entries (cannot combine with `--embed`) |
| `--list` | | List fs.directory entries (dry-run) |
| `--exclude-ns` | | Exclude namespaces (patterns) |
| `--exclude` | | Exclude entries (patterns) |
| `--bytecode` | | Compile Lua to bytecode (** for all) |
| `--profile` | | Apply a runtime profile from `.wippy.yaml` before packing (repeatable, applied in order) |

Without `--embed` or `--embed-all`, embed patterns fall back to the `embed:` section of the module manifest `wippy.yaml`. Packing an application also carries embedded resources from its dependency packs, and only the main module's commands are exposed by the resulting pack.

The output file is written atomically: the pack is built into a temporary file in the destination directory, synced, verified, and only then renamed over the target, inheriting the existing file's permissions when one is present. A failed pack leaves the previous file untouched. Naming an output that is also one of the pack's inputs — the same path, or a hard link or symlink resolving to the same file — is refused rather than truncating the input mid-read.

`--meta` cannot write reserved metadata. The key `registry`, and anything under the `wippy.` or `system.` prefixes, is owned by the pack format and rejected.

Resources declaring `meta.artifact.format` are validated while packing, so a malformed artifact fails here rather than in a consumer. See [Build-time artifacts](guides/artifacts.md).



### wippy publish


Publish module to the hub.

```bash
wippy publish
wippy publish --version 1.0.0
wippy publish --dry-run
```

This command reads `wippy.yaml` from the current directory.

| Flag | Description |
|------|-------------|
| `--version` | Version to publish |
| `--dry-run` | Validate without publishing |
| `--label` | Publish as mutable label instead of version |
| `--release-notes` | Release notes |
| `--protected` | Mark version as protected |
| `--embed` | Embed fs.directory entries by id or name |
| `--config` | Path to directory containing wippy.yaml (default: .) |
| `--registry` | Registry URL |
| `--create` | Create the module on the registry if it does not yet exist |
| `--module-visibility` | Visibility for newly created modules (`--create` only): `public` or `private` (default: private) |
| `--module-type` | Module type: `library`, `application`, `agent`, or `plugin` (overrides `type:` in wippy.yaml) |
| `--module-display-name` | Display name for newly created modules (`--create` only) |

The module type is normally declared as `type:` in `wippy.yaml` (see [Publishing](./publishing.md#wippyyaml)); `--module-type` overrides it for a single publish. When neither is set, newly created modules default to `application` with a deprecation warning.



### wippy search


Search for modules in the hub.

Search uses the stored authentication token for the selected registry, when
available. Authenticate with `wippy auth login` to search with your registry
identity; `--registry` selects which registry's credentials are used.

```bash
wippy search http
wippy search "sql driver" --limit 20
wippy search auth --json
```

| Flag | Default | Description |
|------|---------|-------------|
| `--json` | false | Output as JSON |
| `--limit` | 20 | Maximum results |
| `--registry` | | Registry URL |



### wippy auth


Manage registry authentication.



#### wippy auth login


```bash
wippy auth login
wippy auth login --token YOUR_TOKEN
```

| Flag | Description |
|------|-------------|
| `--token` | API token |
| `--registry` | Registry URL |
| `--local` | Store credentials locally |



#### wippy auth logout


```bash
wippy auth logout
```

| Flag | Description |
|------|-------------|
| `--registry` | Registry URL |
| `--local` | Remove local credentials |



#### wippy auth status


```bash
wippy auth status
wippy auth status --json
```

| Flag | Description |
|------|-------------|
| `--json` | Output as JSON |



### wippy readme


Fetch a module README from the hub.

```bash
wippy readme wippy/terminal
wippy readme wippy/terminal@1.2.3
wippy readme --json wippy/terminal@latest
```

| Flag | Description |
|------|-------------|
| `--json` | Output as JSON |
| `--registry` | Registry URL (default: from credentials) |



### wippy registry


Query and inspect registry entries. Both subcommands accept `--profile` and `--set` to control the merged runtime configuration used to load entries.



#### wippy registry list


```bash
wippy registry list
wippy registry list --kind "function.lua.*"
wippy registry list --ns "app.*" --json
wippy registry list --meta "type=api" --meta "enabled=true"
```

| Flag | Short | Description |
|------|-------|-------------|
| `--kind` | `-k` | Filter by kind (glob pattern) |
| `--ns` | `-n` | Filter by namespace (glob pattern) |
| `--name` | | Filter by name (glob pattern) |
| `--meta` | | Filter by metadata (repeatable) |
| `--json` | | Output as JSON |
| `--yaml` | | Output as YAML |
| `--registry-meta` | | Include registry-owned metadata (`owner`, `root`) in JSON or YAML output; requires `--json` or `--yaml` |
| `--lock-file` | `-l` | Lock file path |

Metadata operators for `--meta`:

| Operator | Meaning |
|----------|---------|
| `field=value` | Exact match |
| `field~regex` | Regex match |
| `field*substr` | Contains substring |
| `field^prefix` | Starts with prefix |
| `field$suffix` | Ends with suffix |



#### wippy registry show


```bash
wippy registry show app:http:handler
wippy registry show app:config --yaml
```

| Flag | Short | Description |
|------|-------|-------------|
| `--field` | `-f` | Show specific field |
| `--json` | | Output as JSON |
| `--yaml` | | Output as YAML |
| `--raw` | | Raw output |
| `--lock-file` | `-l` | Lock file path |



### wippy version


Print version information.

```bash
wippy version
wippy version --short
```



### Custom Commands


Any `process.lua` or `process.wasm` entry can be registered as a named command by adding `command` metadata:

```yaml
entries:
  - name: migrate_runner
    kind: process.lua
    meta:
      command:
        name: migrate
        short: Run database migrations
        security:
          actor:
            id: app:migrations
          policies:
            - app.security:migrations
          groups:
            - app.security:operators
    source: file://runner.lua
    method: main
    modules:
      - io
      - registry
      - funcs
```

Run it with:

```bash
wippy run migrate
```

List all available commands:

```bash
wippy run list
```

`wippy run list` accepts `--profile` and `--set` so the listing reflects the same merged runtime config `wippy run` would use.



#### Command Metadata Fields


| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Command name used with `wippy run <name>` |
| `short` | No | Short description shown in `wippy run list` |
| `main` | No | Mark this entry as the default entrypoint. When a pack or hub module is run without a command name, the single `main` entry of that use case is executed; a lone entrypoint is picked even without `main`, and several entrypoints with no `main` is an error |
| `use_case` | No | Entrypoint category, default `run`. The entry declaring `use_case: test` is what `wippy test` executes |
| `security` | No | Security context the command runs under when launched from the CLI |

Any process entry kind works (`process.lua`, `process.wasm`). Command names are not checked for uniqueness; when several loaded entries declare the same name, the first match in registry order runs. Arguments after the command name are passed to the process as string payloads.



#### Command security


A command entry declares the actor and policy scope its CLI launch runs under:

```yaml
entries:
  - name: migrate_runner
    kind: process.lua
    meta:
      command:
        name: migrate
        short: Run database migrations
        security:
          actor:
            id: system.migrations
            meta:
              role: operator
          policies:
            - app.security:migrations_policy
          groups:
            - app.security:operators
    source: file://runner.lua
    method: main
```

| Field | Description |
|-------|-------------|
| `actor.id` | Actor identity for the launched process |
| `actor.meta` | Actor attributes evaluated by policies |
| `policies` | Registry IDs (`namespace:name`) of individual policies added to the scope |
| `groups` | Registry IDs of policy groups whose policies are added to the scope |

The block lives inside `meta.command` because it applies only to the CLI launch path — the operator started the command on their own deployment, which is the trust anchor. It has no effect on ordinary spawns of the same process entry; those follow the entry's own [`security:` block](guides/entry-kinds.md#process-security).

Declaration is fail-closed and validated before the process starts:

- Unknown fields inside `security` are rejected.
- An empty `security` block (no actor, no policies, no groups) is rejected.
- `security` without a `name` is rejected — a command must be nameable to be launched.
- A policy or group that cannot be resolved refuses the launch; resolution is atomic, so a partial scope is never installed.

When the block omits `actor`, the caller's actor is inherited. When it omits both `policies` and `groups`, the caller's scope is inherited.



#### Development Workflow


```bash


## Initialize dependency lock metadata

wippy init
wippy add wippy/test
wippy add wippy/llm
wippy install



## Check for errors

wippy lint



## Run with debug output

wippy run -c -v



## Override config for local dev

wippy run -o app:db:host=localhost -o app:db:port=5432
```



#### Production Deployment


```bash


## Create release pack with bytecode

wippy pack release.wapp --bytecode "**" --exclude-ns "test.**"



## Run from pack with memory limit

wippy run release.wapp -m 2G
```



#### Debugging


```bash


## Execute single process

wippy run --exec app:worker



## With profiler enabled

wippy run -p -v


## Then: go tool pprof http://localhost:6060/debug/pprof/heap

```



#### Dependency Management


```bash


## Add new dependency

wippy add acme/http@latest



## Force re-download

wippy install --force



## Update specific module

wippy update acme/http
```



#### Publishing


```bash


## Login to hub

wippy auth login



## Validate module

wippy publish --dry-run



## Publish

wippy publish --version 1.0.0 --release-notes "Initial release"
```



### Environment Variables


| Variable | Effect |
|----------|--------|
| `WIPPY_TOKEN` | Registry auth token; overrides stored credentials (a token pushed via `hub.auth.authenticate` ranks higher still) |
| `WIPPY_REGISTRY` | Default registry URL (overridden by `--registry`) |
| `WIPPY_CACHE_DIR` | Cache directory for hub modules run via `wippy run org/module` (default: `~/.wippy/cache`) |
| `GOMEMLIMIT` | Memory-limit fallback when `--memory-limit` is not set |

Values in `.wippy.yaml` may reference OS environment variables with `${env:NAME}`, resolved at file load; a missing variable fails config loading. Bare `${name}` references resolve from the config's `vars:` section instead.



### Configuration File


Create `.wippy.yaml` for persistent settings:

```yaml
logger:
  encoding: console

logmanager:
  stream_to_events: true

profiler:
  enabled: true
  address: localhost:6060

override:
  app:gateway:addr: ":9090"
  app:db:host: "localhost"
```



### See Also


- [Configuration](guides/configuration.md) — Configuration file reference
- [Observability](guides/observability.md) — Monitoring and logging



---

# "Configuration Reference"

## Configuration Reference


Wippy reads runtime configuration from `.wippy.yaml` files.

Use the repeatable `wippy run --set section.path=value` option to override the configuration fields below at launch. To override individual registry *entries* rather than configuration sections, use the `override:` section or `-o`; see [Overriding Entries](guides/entry-kinds.md#overriding-entries).



### Config Composition


`--config` is repeatable; files compose left to right using the same schema:

```bash
wippy run --config .wippy.yaml --config .wippy.local.yaml
```

- Later files override matching values and keep everything else.
- Every explicitly named file must exist. Without `--config`, the default `.wippy.yaml` is optional.
- The first file anchors the directory used to resolve relative paths.
- Filenames carry no reserved meaning; nothing besides the default is auto-discovered.

Configuration applies in this order: composed files, selected `--profile` overlays, and then `--set` overrides. For applications run from packs, packed runtime defaults have lower precedence than all three; see [Publishing Runtime Defaults](guides/publishing.md#publishing-runtime-defaults).



### Profiles


A configuration file may declare named overlays under `profiles:`. Each profile body mirrors the standard configuration sections. Selecting it with `--profile <name>` applies those values over the merged base configuration:

```yaml
version: "1.0"

vars:
  port: 8085

override:
  app:db:kind: db.sql.sqlite

disable:
  namespaces: ["legacy.**"]

profiles:
  pg:
    vars:
      port: 18085
    override:
      app:db:kind: db.sql.postgres
    disable:
      namespaces.add: ["experimental.**"]
```

```bash
wippy run --profile pg
```

- `--profile` is repeatable; profiles compose left to right, after file composition and before `--set`. An unknown name is an error.
- Values merge per leaf (last writer wins). The `profiles:` section itself is stripped from the resolved config.
- The `disable` section supports list operations inside profiles — `namespaces.add`, `namespaces.remove`, `entries.add`, `entries.remove` — so a profile can adjust the base list instead of replacing it.
- `${name}` references interpolate from the merged `vars:` section. OS environment references are not allowed inside profile vars; use `${env:NAME}` in the base config, resolved at file load.

`wippy run`, `test`, and `pack` accept `--profile`; `run list`, `install`, `update`, `lint`, and `registry` accept it as well for workspace profiles (together with `--set`). Applications can ship profiles inside packs — see [Publishing Profiles](guides/publishing.md#publishing-profiles).



### Logger


Controls the zap logger encoder. CLI flags (`-v`, `-c`, `-s`) override the level and output; encoding is the only YAML-configured option.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `encoding` | string | console | Encoder: `console` (humanized) or `json` (structured) |

```yaml
logger:
  encoding: json
```



### Log Manager


Controls runtime log routing. Console output is configured via [CLI flags](guides/cli.md) (`-v`, `-c`, `-s`).

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `propagate_downstream` | bool | true | Send logs to console/file output |
| `stream_to_events` | bool | false | Publish logs to event bus for programmatic access |
| `min_level` | int | 0 (`-1` with `-v`) | Minimum level: -1=debug, 0=info, 1=warn, 2=error. The CLI writes this key from its flags after the file is read, so a file value is ignored; change it with `--set logmanager.min_level=<n>` |

```yaml
logmanager:
  propagate_downstream: true
  stream_to_events: false
```

See: [Logger Module](lua/system/logger.md)



### Profiler


Go pprof HTTP server for CPU/memory profiling. Enable with `-p` flag or config.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | bool | false | Start profiler server |
| `address` | string | localhost:6060 | Listen address |
| `read_timeout` | duration | 15s | HTTP read timeout |
| `write_timeout` | duration | 15s | HTTP write timeout |
| `idle_timeout` | duration | 60s | Keep-alive timeout |

```yaml
profiler:
  enabled: true
  address: "localhost:6060"
```

When enabled with the default address, the profiler is available at `http://localhost:6060/debug/pprof/`.



### Security


Global security behavior. Individual policies are defined as [security.policy entries](guides/entry-kinds.md).

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `strict_mode` | bool | true | Deny access when the security context is incomplete |

```yaml
security:
  strict_mode: false
```

See: [Security System](system/security.md), [Security Module](lua/security/security.md)



### Registry


Entry storage and version history. The registry holds all configuration entries.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enable_history` | bool | true | Track entry versions |
| `history_type` | string | memory | Storage: `memory`, `sqlite`, `postgres`, `nil` |
| `history_path` | string | .wippy/registry.db | SQLite file path (used when `history_type: sqlite`) |
| `history_dsn` | string | | Postgres DSN (used when `history_type: postgres`) |
| `history_schema` | string | | Postgres schema name (used when `history_type: postgres`) |
| `event_wait_timeout` | duration | 30s | Per-operation wait for listener acknowledgement during a registry apply |
| `dispatch_internal_kinds` | string[] | `[registry.entry, ns.dependency, ns.requirement, ns.definition]` | Entry kinds handled internally instead of dispatched to component listeners |
| `dependency_resolve_timeout` | duration | 0 (none) | Bound on dependency resolution |
| `dependency_download_timeout` | duration | 0 (none) | Bound on each module download and download-URL request |
| `dependency_lock_path` | string | discovered `wippy.lock` | Lock file the dependency handler reads and writes |
| `dependency_vendor_dir` | string | `<lock dir>/<directories.modules>/vendor` | Directory holding downloaded module packs |

```yaml
registry:
  history_type: sqlite
  history_path: /var/lib/wippy/registry.db
```

```yaml
registry:
  history_type: postgres
  history_dsn: ${env:WIPPY_REGISTRY_HISTORY_DSN}
  history_schema: wippy_registry
```

See: [Registry Concept](concepts/registry.md), [Registry Module](lua/core/registry.md)



### Artifact


Output root for materialized [build-time artifacts](guides/artifacts.md).

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `materialization_root` | string | parent of the dependency vendor directory | Application-owned root under which each artifact format writes its own subtree |

```yaml
artifact:
  materialization_root: build/wippy
```

See: [Build-time artifacts](guides/artifacts.md#where-output-lands)



### Workspace


Local module replacements, keyed by `org/module`. Values are directories; relative paths resolve against the first `--config` file's directory, and `null` disables a replacement inherited from an earlier config layer or profile.

```yaml
workspace:
  replacements:
    acme/http: ../local-http
    acme/sql: null
```

Replacements are never written to `wippy.lock`. See [Local Development with Replacements](guides/dependency-management.md#local-development-with-replacements).



### Relay


Message routing between processes across nodes.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `node_name` | string | derived per-instance ID | Identifier for this relay node (default: UUIDv5 of machine-id/hostname + working dir; overridable via `WIPPY_NODE_ID` / `WIPPY_RELAY_NODE_NAME`) |

```yaml
relay:
  node_name: worker-1
```

See: [Process Model](concepts/process-model.md)



### Supervisor


Service lifecycle management. Controls the supervisor's internal control mailbox used to dispatch lifecycle events.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `host.buffer_size` | int | 1024 | Internal control mailbox capacity |
| `host.worker_count` | int | 16 | Concurrent dispatcher workers |

```yaml
supervisor:
  host:
    buffer_size: 2048
    worker_count: 32
```

See: [Supervision Guide](guides/supervision.md)

<note>
Per-`process.host` workers and queues are configured on the entry itself (`workers`, `queue_size`, `local_queue_size`), not in this global section. See the [Process Host](system/process-host.md) entry kind.
</note>



### Lua Runtime


Lua VM caching and expression evaluation.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `cache.enabled` | bool | `type_system.enabled` | Persist compiled bytecode/typecheck cache to disk; follows `type_system.enabled` unless set explicitly |
| `cache.dir` | string | `.wippy/cache/lua` | Cache directory path (relative to the config/working directory) |
| `cache.mode` | string | `readwrite` | Cache mode: `readwrite` (default), `readonly`, `off`; unknown values fall back to `readwrite` |
| `cache.compile.enabled` | bool | true | Persist compiled bytecode (when `cache.enabled`) |
| `cache.typecheck.enabled` | bool | true | Persist typecheck results (when `cache.enabled`) |
| `cache.max_bytes` | int | 1073741824 | On-disk cache size ceiling in bytes |
| `cache.max_entries` | int | 20000 | Maximum cached entries |
| `cache.prune_interval` | int | 256 | Writes between cache prune passes |
| `type_system.enabled` | bool | false | Enable static type checking |
| `type_system.strict` | bool | false | Treat type warnings as errors |
| `invalidation_wait_timeout` | duration | `registry.event_wait_timeout` (30s) | Wait for code invalidation to be acknowledged after an entry changes |
| `eval.max_steps` | int | 10000 | Default scheduler-step budget for an `eval` run; negative values are rejected |
| `eval.cache_size` | int | 256 | Compiled-program cache entries for evaluated source |
| `eval.cache_ttl` | duration | 0 (no expiry) | Lifetime of a cached compiled program |

```yaml
lua:
  cache:
    enabled: true
    dir: .cache/lua
  type_system:
    enabled: true
```

See: [Lua Overview](lua/overview.md)



### Scheduler


Core partitioning for the WASM runtime. When enabled, `reserved_cores` CPUs are set aside for WASM execution and the rest serve the actor scheduler; an invalid split (for example more reserved cores than available) is logged and ignored.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `wasm_isolation.enabled` | bool | false | Partition cores between WASM and actor work |
| `wasm_isolation.reserved_cores` | int | 1 | Cores reserved for WASM execution |

```yaml
scheduler:
  wasm_isolation:
    enabled: true
    reserved_cores: 2
```



### Finder


Registry search caching. Used internally for entry lookups.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `query_cache_size` | int | 1000 | Cached query results |
| `regex_cache_size` | int | 100 | Compiled regex patterns |

```yaml
finder:
  query_cache_size: 2000
```



### OpenTelemetry


Distributed tracing and metrics export via OTLP.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | bool | false | Enable OTEL |
| `endpoint` | string | localhost:4318 | OTLP endpoint |
| `protocol` | string | http/protobuf | Protocol: grpc, http/protobuf |
| `service_name` | string | wippy-runtime | Service identifier |
| `service_version` | string | | Service version tag |
| `insecure` | bool | true | Allow plaintext OTLP connection |
| `sample_rate` | float | 1.0 | Trace sampling (0.0-1.0) |
| `propagators` | string[] | `[tracecontext, baggage]` | Context propagators |
| `traces_enabled` | bool | true | Export traces |
| `metrics_enabled` | bool | false | Export metrics |
| `http.enabled` | bool | true | Trace HTTP requests |
| `http.extract_headers` | bool | true | Extract trace context from inbound headers |
| `http.inject_headers` | bool | true | Inject trace context into the HTTP response |
| `process.enabled` | bool | true | Trace process lifecycle |
| `process.trace_lifecycle` | bool | true | Emit spans for spawn/terminate |
| `interceptor.enabled` | bool | true | Trace function calls |
| `interceptor.order` | int | 100 | Decoded compatibility field; runtime v0.3.32a registers the interceptor at order 100 regardless of this value |
| `queue.enabled` | bool | true | Trace queue publish/consume |
| `temporal.enabled` | bool | false | Trace Temporal workflows |

```yaml
otel:
  enabled: true
  endpoint: "http://jaeger:4318"
  traces_enabled: true
  process:
    trace_lifecycle: true
```

Standard OTEL environment variables (`OTEL_SDK_DISABLED`, `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_PROTOCOL`, `OTEL_EXPORTER_OTLP_INSECURE`, `OTEL_SERVICE_NAME`, `OTEL_SERVICE_VERSION`, `OTEL_TRACES_SAMPLER`, `OTEL_TRACES_SAMPLER_ARG`, `OTEL_PROPAGATORS`) override the matching fields.

See: [Observability Guide](guides/observability.md)



### Shutdown


Graceful shutdown behavior.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `timeout` | duration | 30s | Max wait for components to stop |

```yaml
shutdown:
  timeout: 60s
```



### Metrics


Internal metrics collection buffer.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `buffer.size` | int | 10000 | Metrics buffer capacity |
| `interceptor.enabled` | bool | true | Auto-track function calls |

```yaml
metrics:
  buffer:
    size: 20000
  interceptor:
    enabled: true
```

See: [Metrics Module](lua/system/metrics.md), [Observability Guide](guides/observability.md)



### Prometheus


Prometheus metrics endpoint.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | bool | false | Start metrics server |
| `address` | string | | Listen address; must be set explicitly when `enabled: true`, otherwise the metrics server does not start |
| `max_cardinality` | int | 1024 | Distinct label sets retained per metric (LRU); `0` or less uses the default |

```yaml
prometheus:
  enabled: true
  address: "0.0.0.0:9090"
```

Exposes `/metrics` endpoint for Prometheus scraping, plus `/livez`.

See: [Observability Guide](guides/observability.md)



### Cluster


Multi-node clustering: gossip membership plus a bounded Raft consensus core. See the [Cluster Guide](guides/cluster.md) for the architecture and operational model; this section is the config-key reference.



#### Top-level


| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | bool | false | Enable clustering |
| `name` | string | hostname | Node name; must be unique across the cluster |
| `failure_domain` | string | | Zone/rack label; advertised in gossip so voters spread across domains |
| `kv_crdt_tombstone_retention` | duration | 0 | Age after which `store.kv.crdt` delete tombstones are reclaimed; `0` disables age-based GC |
| `kv_crdt_tombstone_gc_alive_peers` | bool | false | Use the current alive membership as the tombstone acknowledgement set |



#### Membership (gossip)


SWIM gossip via memberlist. Used for node discovery, failure detection, and metadata dissemination.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `membership.bind_addr` | string | 0.0.0.0 | Gossip bind address |
| `membership.bind_port` | int | 7946 | Gossip bind port (TCP+UDP) |
| `membership.advertise_addr` | string | | Address peers use to reach this node (NAT/k8s) |
| `membership.join_addrs` | string | | Comma-separated seed `host:port` pairs |
| `membership.secret_key` | string | | Base64-encoded gossip encryption key (inline) |
| `membership.secret_file` | string | | Path to file holding the gossip encryption key |
| `membership.gossip_interval` | duration | 500ms | Gossip dissemination period |
| `membership.push_pull_interval` | duration | 5s | Full state sync period |
| `membership.dead_node_reclaim_time` | duration | 30s | When a dead node's name/address can be reclaimed |
| `membership.probe_interval` | duration | 1s | Failure-detection probe cycle |
| `membership.probe_timeout` | duration | 200ms | Ack wait per probe |
| `membership.tcp_timeout` | duration | 1s | TCP fallback probe timeout |
| `membership.suspicion_mult` | int | 3 | Suspicion timeout multiplier |

A gossip secret is required. Set `membership.secret_key` or `membership.secret_file` (the file wins if both are given); with neither, the cluster component fails to start. The value is base64-encoded.

The four probe keys inherit memberlist's local-network defaults when unset; raise them for high-latency links (e.g. `probe_interval: 2s`, `probe_timeout: 500ms`, `suspicion_mult: 5`).



#### Internode (transport)


TCP mesh carrying the relay and Raft traffic between nodes. Raft rides this mesh over internode request/reply; there is no separate Raft port.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `internode.bind_addr` | string | 0.0.0.0 | Mesh bind address |
| `internode.bind_port` | int | 0 | Mesh port (0 = auto: 7950-7959, then ephemeral) |
| `internode.auto_port` | bool | true | Discover the actual port at boot, pin it, and advertise it in gossip |
| `internode.advertise_addr` | string | | Additional relay endpoint (IP or DNS name) published for upgraded peers — for NAT or load-balanced reachability |
| `internode.advertise_port` | int | 0 | Port for `advertise_addr` (0 = bind port; requires `advertise_addr`) |
| `internode.identity_key` | string | | Base64-encoded ed25519 private key identifying this node (inline) |
| `internode.identity_key_file` | string | | Path to a file holding that key |
| `internode.trusted_peer_keys` | map | | Base64-encoded ed25519 public key per node name, including this node |
| `internode.tls.enabled` | bool | false | Enable mutual TLS on the internode TCP mesh |
| `internode.tls.cert_file` | string | | PEM node certificate; required with TLS |
| `internode.tls.key_file` | string | | Matching private key; required with TLS |
| `internode.tls.ca_file` | string | | PEM CA bundle for client and server verification; required with TLS |

`advertise_addr`/`advertise_port` publish an additive endpoint in node metadata while the bind endpoint stays advertised unchanged, so mixed-version clusters keep connecting during a rolling upgrade.

Internode identity is mandatory whenever clustering is enabled. `identity_key` and `identity_key_file` are mutually exclusive and one of them must be present; the value decodes (standard or raw base64) to either a 32-byte ed25519 seed or a 64-byte ed25519 private key. `trusted_peer_keys` maps each node name to that node's 32-byte ed25519 public key, and must contain an entry for the local `cluster.name` whose value matches the local identity — otherwise startup fails. See the [Cluster Guide](guides/cluster.md#internode-identity).

TLS requires all three credential paths and TLS 1.2 or later. Unknown settings,
invalid values, unreadable or invalid credentials, and credential paths supplied
while TLS is disabled fail startup. The ed25519 identity configuration remains
required. See [Internode TLS](guides/cluster.md#internode-tls) for an example.



#### Raft (consensus)


The bounded Raft core stores durable state under `raft.data_dir` by default (`~/.wippy/store`). A restarted node rejoins quorum from its peers. [`store.kv.raft`](system/store.md#cluster-kv-stores) entries replicate through this core, and gossip coordinates bootstrap using a `bootstrap_expect` model.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `raft.data_dir` | string | `~/.wippy/store` | Directory for fs-durable Raft state and durable CRDT snapshots (under `<data_dir>/_sys/`). Diskless only when no path resolves (no home dir and none set) |
| `raft.enabled` | bool | true | Run a Raft node; `false` makes this a gossip-only client |
| `raft.role` | string | server | `server` runs a Raft node; `client` is gossip-only |
| `raft.eligible` | bool | true | Whether this node may be selected as a voter or standby; false keeps it outside Raft as a client |
| `raft.priority` | int | 100 | Voter selection priority (lower is preferred) |
| `raft.bootstrap_expect` | int | 1 | Initial quorum size: `0`=join existing, `1`=single-node, `N`=wait for N eligible nodes including the local node, then form quorum |
| `raft.max_voters` | int | 5 | Voter ceiling (must be odd); up to `max_standbys` additional eligible nodes become standbys, and the rest remain clients |
| `raft.max_standbys` | int | 4 | Non-voting members kept warm for promotion; nodes beyond voters+standbys are not Raft members |
| `raft.reconcile_debounce` | duration | 2s | Coalesce window after a gossip event before the voter reconciler runs |
| `raft.reconcile_timeout` | duration | 2s | Bound per reconcile pass |
| `raft.heartbeat_timeout` | duration | 3s | Follower idle wait before starting an election |
| `raft.election_timeout` | duration | 3s | Candidate election timeout (clamped to >= heartbeat) |
| `raft.commit_timeout` | duration | 500ms | Idle leader heartbeat cadence |
| `raft.snapshot_threshold` | uint64 | 8192 | Log entries since last snapshot before a new one |
| `raft.snapshot_interval` | duration | 2m | Snapshot check interval |
| `raft.snapshot_retain` | int | 3 | Snapshots retained |
| `raft.trailing_logs` | uint64 | 10240 | Log entries retained after a snapshot |
| `raft.max_append_entries` | int | 16 | Max entries per AppendEntries RPC |
| `raft.leader_probe_interval` | duration | 3s | Global-registry leader-reachability probe cadence |
| `raft.leader_probe_grace` | int | 3 | Consecutive probe failures before leader is declared unreachable |
| `raft.registry_backend` | string | kv | Cluster name-registry implementation: `kv` (shared kv keyspace) or `fsm` (dedicated Raft FSM) |
| `raft.global_dissem_tombstone_retention` | duration | 0 | How long the global-name dissemination cache keeps delete tombstones |

Single-node (development) — clustering on, bootstraps itself immediately:

```yaml
cluster:
  enabled: true
  name: dev
  membership:
    secret_key: "d2lwcHktZG9jcy1nb3NzaXAtc2VjcmV0LTMyYnl0ZXM="
  internode:
    identity_key: "d2lwcHktZG9jcy1kZXYtbm9kZS1leGFtcGxlc2VlZCE="
    trusted_peer_keys:
      dev: "rNqImcjOzef28dzvma80mSrCW1px5LBAc5TbaYqAgm0="
  raft:
    bootstrap_expect: 1
```

Three-node voting cluster — each node lists the others as seeds and waits for all three before forming quorum. Every node carries the same `trusted_peer_keys` map and its own private key:

```yaml
cluster:
  enabled: true
  name: node-1
  failure_domain: us-east-1a
  membership:
    bind_port: 7946
    join_addrs: "node-2:7946,node-3:7946"
    secret_file: /etc/wippy/cluster.key
  internode:
    identity_key_file: /etc/wippy/node-1.key
    trusted_peer_keys:
      node-1: "okmamN3PKkMpPwPBurknHy2Wi3dwp/rz+uTM2fF9aD0="
      node-2: "PWX+oOYrFdtjUxbgmTkXCFI0KEvG++ZM52HOWfDkqP8="
      node-3: "QfP0fgllbj4s95VAztTORhy3bv9mst1l0lwuUNvO/hE="
  raft:
    bootstrap_expect: 3
    max_voters: 5
```

Gossip-only client — joins the cluster for naming/messaging but never runs Raft. It still needs its own identity and must appear in every node's trusted map:

```yaml
cluster:
  enabled: true
  name: edge-7
  membership:
    join_addrs: "node-1:7946,node-2:7946"
    secret_file: /etc/wippy/cluster.key
  internode:
    identity_key_file: /etc/wippy/edge-7.key
    trusted_peer_keys:
      node-1: "okmamN3PKkMpPwPBurknHy2Wi3dwp/rz+uTM2fF9aD0="
      node-2: "PWX+oOYrFdtjUxbgmTkXCFI0KEvG++ZM52HOWfDkqP8="
      node-3: "QfP0fgllbj4s95VAztTORhy3bv9mst1l0lwuUNvO/hE="
      edge-7: "7lzP4jBAkC3P+0jq4vtMsC45571BlVXk3mSlOD/Z0SA="
  raft:
    role: client
```



### LSP


Language Server Protocol server for editor integrations.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | bool | false | Enable the LSP service and TCP server; the HTTP transport also requires this |
| `address` | string | :7777 | TCP listen address |
| `http_enabled` | bool | false | Enable the HTTP transport |
| `http_address` | string | :7778 | HTTP listen address |
| `http_path` | string | /lsp | HTTP endpoint path |
| `http_allow_origin` | string | * | CORS allowed origin |
| `max_message_bytes` | int | 8388608 | Max incoming message size |

```yaml
lsp:
  enabled: true
  address: ":7777"
  http_enabled: true
```

See: [LSP Guide](guides/lsp.md)



### Network Service


Overlay network manager (SOCKS5, I2P, Tailscale drivers).

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `state_dir` | string | .wippy/net | Driver state storage directory |
| `default_network` | string | | Default network ID applied when entries omit `network` |

```yaml
network_service:
  state_dir: /var/lib/wippy/net
  default_network: app:tailscale
```

See: [Network Overlays](system/network.md)



### HTTP Dispatcher


Tuning for the shared HTTP client pool used by HTTP-dispatched functions and outbound requests.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `dispatcher.http.timeout` | duration | 0 (none) | Per-request timeout |
| `dispatcher.http.max_idle_conns` | int | 0 (stdlib) | Max idle connections across all hosts |
| `dispatcher.http.max_idle_per_host` | int | 0 (stdlib) | Max idle connections per host |
| `dispatcher.http.idle_conn_timeout` | duration | 0 (stdlib) | Idle connection timeout |
| `dispatcher.http.max_clients` | int | 0 (unbounded) | Max distinct pooled clients |

```yaml
dispatcher:
  http:
    timeout: 30s
    max_idle_per_host: 32
```



### Modules


Module registry client used by `wippy install`/`update`.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `registry_url` | string | https://hub.wippy.ai | Registry endpoint |

```yaml
modules:
  registry_url: https://internal-registry.example.com
```



### Extensions


Native Go plugin extensions loaded at boot (Unix only).

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | bool | true | Load extensions |
| `paths` | string[] | | Plugin file paths (relative to config dir) |

```yaml
extensions:
  enabled: true
  paths:
    - ./extensions/myplugin.so
```



### Environment Variables


| Variable | Description |
|----------|-------------|
| `GOMEMLIMIT` | Memory limit fallback when `--memory-limit` flag is not set (precedence: `--memory-limit` flag > `GOMEMLIMIT` > 1G default) |



### See Also


- [CLI Reference](guides/cli.md) — Command-line options
- [Cluster Guide](guides/cluster.md) — Clustering architecture and operations
- [Entry Kinds](guides/entry-kinds.md) — Entry types and fields
- [Observability Guide](guides/observability.md) — Logging, metrics, and tracing



---

# "Cluster"

## Cluster


Wippy runs as a single node by default. Enabling clustering connects nodes through gossip membership and a bounded Raft consensus core, supporting cluster-wide process names, distributed locks, and process-group messaging.

Clustering is disabled until `cluster.enabled` is set to `true`.



### Cluster Capabilities


- **Membership** — every node knows the live set of peers through gossip, with fast failure detection.
- **Cluster-wide process names** — register a process under a name that resolves from any node, with a choice of consistency guarantees (see [Naming](#naming-and-name-scopes)).
- **Distributed locks** — `system.lock` provides cluster-wide mutual exclusion with automatic release when the holder dies (see [Distributed locks](#distributed-locks)).
- **Process groups** — publish to every member of a named group across all nodes (see [Process groups](#process-groups)).
- **Replicated key-value stores** — `store.kv.raft` (strong) and `store.kv.crdt` (eventual) replicate KV data across nodes (see [Store](system/store.md#cluster-kv-stores)).
- **A consensus core** — a small, bounded Raft cluster provides the linearizable backbone the naming and lock primitives build on.



### Architecture: Bounded Raft


Wippy limits Raft membership to a fixed-size core so the leader does not replicate every log entry to every node. Other nodes participate through gossip. Each node has one of three roles in the Raft configuration:

| Role | Count (default) | In Raft config | Receives log replication | Votes |
|------|-----------------|----------------|--------------------------|-------|
| **Voter** | up to 5 (`max_voters`, odd) | yes | yes | yes |
| **Standby** | up to 4 (`max_standbys`) | yes | yes | no |
| **Client** | unbounded | no | no | no |

- **Voters** form the quorum. Writes commit once a majority of voters acknowledge them. `max_voters` is normalized to an odd cap (default 5). With at least three eligible nodes, the reconciler also chooses an odd voter count. With two eligible nodes and a cap greater than one, both are voters; `max_voters: 1` keeps a single voter.
- **Standbys** are non-voting members kept fully replicated and warm. When a voter departs, the leader promotes the highest-ranked standby into the open voter slot, so quorum recovers without waiting for a fresh node to catch up.
- **Clients** are nodes beyond `voters + standbys`. They are not in the Raft configuration, so the leader does not send them log entries. They participate in gossip and route writes to a Raft member, keeping Raft replication bounded by the configured core size.

The `max_voters` and `max_standbys` settings cap the consensus core independently of the total cluster size.



#### Voter Selection


The leader runs a reconciler that, on every membership change (debounced by `raft.reconcile_debounce`, default 2s), recomputes which nodes should be voters and applies the minimal set of promote/demote operations. Selection is deterministic — every node derives the same ordering from the same gossip view — and is driven by three gossip-advertised hints:

- `raft.eligible` — a node with `eligible: false` is excluded from both voter and standby selection and remains outside Raft as a client. Keep a node eligible but below the voter cutoff when it should serve as a standby.
- `raft.priority` — lower value is preferred when filling voter slots; ties break by node ID.
- `failure_domain` — voters are spread across distinct domains (zones/racks) first, reducing the risk that one domain failure removes a voter majority.

Operations are applied in a quorum-preserving order: adds and promotions first, then demotions, then removals.



### Membership and Gossip


Membership uses SWIM gossip (HashiCorp memberlist). Each node binds a gossip port (default **7946**) and continuously exchanges small messages with peers to detect failures and disseminate metadata.

A node joins by pointing at one or more existing nodes:

```yaml
cluster:
  enabled: true
  name: node-2
  membership:
    join_addrs: "node-1:7946"
    secret_file: /etc/wippy/cluster.key
  internode:
    identity_key_file: /etc/wippy/node-2.key
    trusted_peer_keys:
      node-1: "okmamN3PKkMpPwPBurknHy2Wi3dwp/rz+uTM2fF9aD0="
      node-2: "PWX+oOYrFdtjUxbgmTkXCFI0KEvG++ZM52HOWfDkqP8="
```

The first node needs no `join_addrs`; it starts as a seed. Joins retry with backoff, and an isolated node periodically attempts to rejoin. This supports nodes that restart with a new IP, as commonly occurs in Kubernetes.

Gossip is always encrypted with a shared key. Supply it inline as `membership.secret_key` or from a file as `membership.secret_file`; a node started with neither fails to bring the cluster component up. The value is base64-encoded and identical on every node.

Membership changes (`NodeJoined`, `NodeLeft`, `NodeUpdated`) are the events that drive Raft bootstrap, voter reconciliation, process-group sync, and automatic cleanup of names owned by a departed node.



### Internode identity


Every node holds an ed25519 key pair, and every node carries the map of public keys it trusts. Both are mandatory when `cluster.enabled: true`.

```yaml
cluster:
  internode:
    identity_key_file: /etc/wippy/node-1.key
    trusted_peer_keys:
      node-1: "okmamN3PKkMpPwPBurknHy2Wi3dwp/rz+uTM2fF9aD0="
      node-2: "PWX+oOYrFdtjUxbgmTkXCFI0KEvG++ZM52HOWfDkqP8="
      node-3: "QfP0fgllbj4s95VAztTORhy3bv9mst1l0lwuUNvO/hE="
```

| Key | Content |
|-----|---------|
| `internode.identity_key` | The node's private key, inline |
| `internode.identity_key_file` | Path to a file holding that key |
| `internode.trusted_peer_keys` | Node name to public key, for every node in the mesh including this one |

Key format: base64, standard or raw (unpadded) encoding. A private key decodes to either a 32-byte ed25519 seed or a full 64-byte ed25519 private key; a trusted peer key decodes to a 32-byte ed25519 public key. There is no key-generation subcommand — mint keys with any ed25519 tool and base64 the raw bytes:

```bash


## 32-byte seed and its public key, base64-encoded

openssl genpkey -algorithm ed25519 -out node-1.pem
openssl pkey -in node-1.pem -outform DER \
  | tail -c 32 | base64 > node-1.key
openssl pkey -in node-1.pem -pubout -outform DER \
  | tail -c 32 | base64
```

`identity_key` and `identity_key_file` are mutually exclusive, and one of them is required. `trusted_peer_keys` must contain an entry for the local `cluster.name` whose value is this node's own public key; a missing or mismatched self entry aborts startup. This makes the trusted map a single artifact you can distribute unchanged to every node.

The mesh handshake is mutual. Each side proves knowledge of the shared gossip secret with an HMAC over a transcript binding both node IDs and both nonces, and signs that transcript with its identity key; the peer verifies the signature against the public key it has for that node ID and against the key the peer advertises in gossip. Either check failing closes the connection.

Consequences to plan for:

- The mesh does not interoperate with a node that has no identity. Every node in the cluster must be configured with one.
- A peer whose node ID is absent from `trusted_peer_keys` is rejected, as is one whose gossip-advertised public key disagrees with the trusted entry. Adding a node means distributing its public key to the existing nodes.
- A node ID must be present in the live gossip membership before its key resolves, so a peer that has not joined gossip cannot open a mesh connection.



### Internode TLS


Enable mutual TLS for the internode TCP mesh under `cluster.internode.tls`.
This also protects the relay and Raft traffic carried by that mesh. Add the
following settings to your existing cluster configuration:

```yaml
cluster:
  internode:
    tls:
      enabled: true
      cert_file: /etc/wippy/node.crt
      key_file: /etc/wippy/node.key
      ca_file: /etc/wippy/cluster-ca.pem
```

TLS is disabled by default. Enabling it requires all three nonempty file paths:
a PEM certificate and matching private key, and a PEM CA bundle used to verify
both server and client certificates. The minimum protocol version is TLS 1.2.
Configure compatible certificates and trust roots on every connecting peer.
The ed25519 internode identity and trusted peer map described above are still
required; TLS adds transport protection to the existing mesh authentication.

Unknown TLS settings, invalid types, missing credentials, malformed CA bundles,
and credential paths supplied without `enabled: true` fail startup. An invalid
explicit configuration never silently falls back to plaintext.



### Bootstrap


The initial cluster forms through gossip rather than a static peer list. With the Consul/Nomad-style `bootstrap_expect` setting, each starting node waits until the configured number of eligible nodes, including itself, is visible before forming quorum.

| `bootstrap_expect` | Behavior |
|--------------------|----------|
| `0` | Never self-bootstrap; only join a cluster that already exists |
| `1` | Single-node; bootstrap immediately with self as the only voter |
| `N` | Wait until `N` eligible nodes, including the local node, are stably visible in gossip, then all derive the same voter list and form quorum |

For an `N`-node bootstrap, set the same `bootstrap_expect: N` on every initial node. Each advertises a "pre-bootstrap" status in gossip; once exactly `N` such nodes, including itself, are visible for a short stability window, every node independently computes the identical sorted voter set and forms the cluster. The stability window prevents a brief, partial view from triggering bootstrap early.

Nodes that start later see an already-formed cluster and skip bootstrap entirely — the leader's reconciler adds them as voters or standbys.



### Raft Consensus Core


Raft state is **fs-durable by default**: logs and snapshots are persisted under `cluster.raft.data_dir` (default `~/.wippy/store`, in `_sys/raft`), and [`store.kv.raft`](system/store.md#cluster-kv-stores) replicates through the same core. A restarting node still rejoins gossip and catches up from its peers, so the cluster also tolerates losing a node's disk; durability comes from both the live quorum and on-disk state. A node runs diskless only when no data directory resolves (no configured path and no home directory) — see [Recovery](#recovery-and-failure-modes).

Raft does not open its own listening port. It rides the **internode mesh** — the same TCP connections used for relay traffic between nodes — carrying its RPCs as internode request/reply frames over the mesh's reliable per-class channels. The internode port is auto-selected at boot (range 7950-7959, then ephemeral), pinned, and advertised in gossip so peers can reach it. Nodes must be mutually reachable on both the gossip port and their advertised internode TCP ports.

The Raft FSM holds the global name registry: active `name -> PID` bindings plus in-flight strong reservations. That is what the naming primitives below read and write.



### Naming and Name Scopes


A process can be registered and addressed by name instead of its raw PID. Its **scope** selects the consistency and coordination behavior. Four scopes are available, ordered from local to strongest:

| Scope | Backed by | Visibility | Guarantee |
|-------|-----------|------------|-----------|
| **Local** | per-node map | this node only | Instant, node-local; no coordination |
| **Eventual** | gossip CRDT | cluster-wide | Eventually consistent; converges after gossip rounds |
| **Consistent** | Raft | cluster-wide | Linearizable writes; unique singleton across the cluster |
| **Strong** | Raft + all-node ack | cluster-wide | Consistent, plus every live node acknowledges before the name is active |

How to choose:

- **Local** — names meaningful only on one node, such as a per-node helper. Released when the process exits and requires no cluster coordination.
- **Eventual** — cluster-wide service, group, and presence names where a brief stale window is acceptable. The binding set is fully replicated to every node, so it fits a bounded namespace — not one name per high-cardinality entity such as a per-session process (address those directly by PID). When two origins register the same name, conflict resolution picks a winner and the losing process receives a cancel event (`process.event.CANCEL`) carrying the reason `name revoked: <name>`; it keeps running and can re-register. Names release when the owning node leaves.
- **Consistent** — the standard choice for cluster-wide named singletons. First-write-wins: a second registration of the same name to a different PID fails with "already exists" and returns the current owner. Writes need a quorum, so they stall in a minority partition. Reads come from the local Raft replica and may lag a write by a few milliseconds.
- **Strong** — the small set of control-plane singletons where even a momentary stale read is dangerous. On top of the Consistent guarantee, the registration opens a reservation that every live node must acknowledge before the name becomes authoritative; any node already holding a conflicting binding rejects it immediately. If the deadline passes before all nodes ack, the registration expires and reports which nodes were missing.

Names are released automatically: Local on process exit; Consistent and Strong on process exit (via topology monitoring) and on node departure; Eventual on node departure. Resolution for messaging (`process.send`, `process.terminate`, and similar) consults the planes most-authoritative first — Consistent and Strong (Raft), then Eventual (gossip), then Local — so a cluster-wide name shadows a local one with the same string.

The Lua surface for naming lives on `process.registry` (register/lookup/unregister with a scope) — see the [Process](lua/core/process.md) reference.



### Process Groups


Process groups are a cluster-aware publish/subscribe and membership facility modeled on Erlang's `pg`. A process joins a named group; a broadcast fans out over the internode mesh to the group's members across all nodes, delivered best-effort. Groups are eventually consistent and independent of Raft — they use the gossip membership view to choose recipients — so they keep working even while the consensus core is converging.

Typical operations: join/leave a group, broadcast to all members (or local members only), list members, and monitor a group for join/leave events. On a new node joining, groups reconcile their membership through a direct sync handshake, and a background anti-entropy loop repairs any divergence over time.

See [Process Groups](lua/core/pg.md) for the Lua API and the [`pg.scope` entry kind](system/process-groups.md) for configuration.



### Distributed Locks


`system.lock` is cluster-wide mutual exclusion built on a raft-linearizable conditional write in the shared key-value store. Acquiring a lock performs a set-if-absent of the holder PID at `_sys:lock:<name>`; releasing deletes that entry if it is still held by the caller. Because the conditional write goes through Raft (with off-leader writes forwarded to the leader), it is linearizable, so at most one holder can exist cluster-wide.

```lua
local ok, err = system.lock.acquire("orders.migration")
if not ok then
  -- err has kind errors.ALREADY_EXISTS when another process holds the lock.
  -- Apply the caller's retry and backoff policy for that case if needed.
  return nil, err
end

-- critical section: only one holder cluster-wide
local released, release_err = system.lock.release("orders.migration")
if release_err then
  return nil, release_err
end
return released
```

Acquire is fail-fast (non-blocking): if the lock is held, it returns immediately, so callers provide their own retry and backoff. The lock is released if the holder process exits or its node leaves. See the [System](lua/system/system.md) reference for exact signatures.



### Configuration


See [Configuration](guides/configuration.md#cluster) for related cluster settings. These minimal shapes include the mandatory internode identity settings.

These are configuration fragments, not a complete deployment manifest. Replace
node names, addresses, failure domains, paths, and every `${env:...}` identity
placeholder with values generated and distributed for your own cluster.

Single node (development):

```yaml
cluster:
  enabled: true
  name: dev
  membership:
    secret_key: "d2lwcHktZG9jcy1nb3NzaXAtc2VjcmV0LTMyYnl0ZXM="
  internode:
    identity_key: "d2lwcHktZG9jcy1kZXYtbm9kZS1leGFtcGxlc2VlZCE="
    trusted_peer_keys:
      dev: "rNqImcjOzef28dzvma80mSrCW1px5LBAc5TbaYqAgm0="
  raft:
    bootstrap_expect: 1
```

Three-node voting cluster (`node-2` and `node-3` differ only in `name`, `identity_key_file`, and `join_addrs`):

```yaml
cluster:
  enabled: true
  name: node-1
  failure_domain: us-east-1a
  membership:
    join_addrs: "node-2:7946,node-3:7946"
    secret_file: /etc/wippy/cluster.key
  internode:
    identity_key_file: /etc/wippy/node-1.key
    trusted_peer_keys:
      node-1: "okmamN3PKkMpPwPBurknHy2Wi3dwp/rz+uTM2fF9aD0="
      node-2: "PWX+oOYrFdtjUxbgmTkXCFI0KEvG++ZM52HOWfDkqP8="
      node-3: "QfP0fgllbj4s95VAztTORhy3bv9mst1l0lwuUNvO/hE="
  raft:
    bootstrap_expect: 3
```

Gossip-only client (joins for naming/messaging, never runs Raft). It still needs an identity, and the voters need its public key in their own maps:

```yaml
cluster:
  enabled: true
  name: edge-7
  membership:
    join_addrs: "node-1:7946,node-2:7946"
    secret_file: /etc/wippy/cluster.key
  internode:
    identity_key_file: /etc/wippy/edge-7.key
    trusted_peer_keys:
      node-1: "okmamN3PKkMpPwPBurknHy2Wi3dwp/rz+uTM2fF9aD0="
      node-2: "PWX+oOYrFdtjUxbgmTkXCFI0KEvG++ZM52HOWfDkqP8="
      node-3: "QfP0fgllbj4s95VAztTORhy3bv9mst1l0lwuUNvO/hE="
      edge-7: "7lzP4jBAkC3P+0jq4vtMsC45571BlVXk3mSlOD/Z0SA="
  raft:
    role: client
```



### Ports


| Purpose | Port | Protocol | Config key |
|---------|------|----------|------------|
| Gossip (membership) | 7946 | TCP + UDP | `cluster.membership.bind_port` |
| Internode mesh (relay + Raft) | auto | TCP | `cluster.internode.bind_port` |

Raft is multiplexed over the internode mesh rather than using a separate port. The internode port is assigned automatically and advertised through gossip. The gossip port is predictable by default, but peers must also be able to reach each node's advertised internode TCP port.



### Observability


Cluster health is exposed through the standard [Prometheus endpoint](guides/observability.md) and through liveness health checks.

Key metrics to watch:

| Metric | Meaning |
|--------|---------|
| `raft_state` | 0 = follower, 1 = candidate, 2 = leader |
| `raft_term` | Current Raft term; rapid increases signal election churn |
| `raft_voters` / `raft_non_voters` | Live voters and standbys in the configuration |
| `raft_leader_changes_total` | Leader transitions; should be near-flat in a healthy cluster |
| `raft_voter_churn_burst_total` | Bursts of voter add/remove operations; sustained churn indicates instability |
| `gossip_members{state}` | Counts by state (alive/suspect/dead/left) |
| `gossip_convergence_seconds` | Time between gossip events |

Built-in liveness checks (wired to the liveness endpoint):

- **gossip** — healthy while the node's gossip health score stays low, with a boot grace window so a rejoining node is not killed prematurely.
- **raft last-contact** — a voting follower fails if it has not heard from a leader recently; a standby tolerates a much longer gap; leaders always pass.
- **process-group broadcast** — fails when the process-group service has neither sent nor received any broadcast for its activity ceiling, catching a wedged service or a persistent partition.



### Recovery and Failure Modes


Raft state is fs-durable, but the cluster's primary durability still comes from a live quorum. The practical rules:

- Keep a voter majority alive. With 5 voters you tolerate 2 simultaneous voter failures; standbys are promoted to refill open slots. Drop below a majority and writes (new Consistent/Strong registrations and lock acquisitions) stall until quorum returns. Locally replicated state can still answer some reads, but do not treat those reads as proof that a partitioned node has the latest value.
- The leader proactively evicts a voter that is both heartbeat-silent and gossip-dead, so a dead voter does not permanently block quorum while a standby is promoted in.
- To recover a cluster that has lost quorum, restart the failed nodes. They rejoin gossip and the surviving members fold them back in. Spreading voters across `failure_domain`s reduces the chance that a single zone failure causes quorum loss.



### See Also


- [Configuration](guides/configuration.md#cluster) — related cluster settings
- [Process](lua/core/process.md) — registering and resolving processes by name
- [System](lua/system/system.md) — `system.cluster`, `system.raft`, `system.node`, `system.lock`
- [Observability](guides/observability.md) — metrics and health endpoints
- [Process Model](concepts/process-model.md) — actors, PIDs, and messaging



---

# "Linter"

## Linter


Run `wippy lint` to type-check and statically analyze Lua entries.



### Usage


```bash
wippy lint                        # Check all Lua entries
wippy lint --level hint           # Show all diagnostics including hints
wippy lint --json                 # Output in JSON format
wippy lint --ns app               # Check only the app namespace
wippy lint --summary              # Group results by error code
```



### What Gets Checked


The linter validates all Lua entry kinds:

- `function.lua` — Functions
- `library.lua` — Libraries
- `process.lua` — Processes
- `workflow.lua` — Workflows

Bytecode entries hold compiled bytecode (fs/path/hash), not source, so they cannot be parsed or type-checked; the linter only checks source-bearing Lua entries (their `.bc` variants are skipped, though they may still appear in the total entry count).

Each entry is parsed, type-checked, and analyzed for correctness issues.



### Severity Levels


Diagnostics have three severity levels:

| Level | Description |
|-------|-------------|
| `error` | Type errors and correctness issues that must be fixed |
| `warning` | Likely bugs or problematic patterns |
| `hint` | Style suggestions and informational notes |

Control which levels appear with `--level`:

```bash
wippy lint --level error          # Errors only
wippy lint --level warning        # Warnings and errors (default)
wippy lint --level hint           # Everything
```



#### Parse Errors


| Code | Description |
|------|-------------|
| `P0001` | Lua syntax error - source cannot be parsed |



#### Type Check Errors (E-series)


Type checker errors (`E0001`+) report issues found by the type system: type mismatches, undefined variables, invalid operations, and similar correctness problems. These are always reported as errors.

```lua
local x: number = "hello"         -- E: string not assignable to number

local function add(a: number, b: number): number
    return a + b
end

add("one", "two")                  -- E: string not assignable to number
```



#### Undeclared Requires


A string-literal `require("name")` whose module is neither in the entry's `imports`/`modules` declarations nor an ambient builtin fails with:

```
require("name") is not declared in _index.yaml imports or modules
```

This check always runs (it is not gated behind `--rules`) and reports as an error. Declare the module to satisfy it:

```yaml
imports:
  json: wippy.stdlib:json    # alias -> registry id
modules:
  - funcs                    # bare module name
```

Dynamic requires (`require(variable)`) are not inspected. The linter and runtime share the ambient module set, which includes modules available without declaration, such as `process` in executable kinds.



#### Lint Rule Warnings (W-series)


Lint rules provide style and quality checks. Enable them with `--rules`:

```bash
wippy lint --rules
```

| Code | Rule | Description |
|------|------|-------------|
| `W0001` | no-empty-blocks | Empty block statements |
| `W0002` | no-global-assign | Assignment to global variables |
| `W0003` | no-self-compare | Comparison of a value with itself |
| `W0004` | no-unused-vars | Unused local variables |
| `W0005` | no-unused-params | Unused function parameters |
| `W0006` | no-unused-imports | Unused import statements |
| `W0007` | no-shadowed-vars | Variable shadowing outer scope |

Without `--rules`, only type checking (P and E codes) is performed.



#### By Namespace


Check specific namespaces using `--ns`:

```bash
wippy lint --ns app               # Exact namespace match
wippy lint --ns "app.*"           # All under app
wippy lint --ns app --ns lib      # Multiple namespaces
```

Dependencies of selected entries are loaded for type checking but their diagnostics are not reported.



#### By Error Code


Filter diagnostics by code:

```bash
wippy lint --code E0001
wippy lint --code E0001 --code E0004
```



#### By Count


Limit the number of diagnostics shown:

```bash
wippy lint --limit 10             # Show first 10 issues
```



#### Table Format (Default)


Each diagnostic is displayed with source context, file location, and the error message. Results are sorted by entry, severity, and line number.

A summary line shows totals:

```
Checked 42 entries: 5 errors, 12 warnings
```



#### Summary Format


Group diagnostics by namespace and error code:

```bash
wippy lint --summary
```

```
By namespace:

  app                              15 issues (5 errors, 10 warnings)
  lib                               2 issues (2 warnings)

By error code:

  E0001      [error  ]    5 occurrences
  E0004      [error  ]    3 occurrences

Checked 42 entries: 5 errors, 12 warnings
```



#### JSON Format


Machine-readable output for CI/CD processing:

```bash
wippy lint --json
```

```json
{
  "diagnostics": [
    {
      "entry_id": "app:handler",
      "code": "E0001",
      "severity": "error",
      "message": "string not assignable to number",
      "line": 10,
      "column": 5
    }
  ],
  "total_entries": 42,
  "error_count": 5,
  "warning_count": 12,
  "hint_count": 0
}
```



### Caching


The linter caches results between runs. Cache keys include the source hash, method name, dependencies, and type-system configuration.

Clear the cache if results seem stale:

```bash
wippy lint --cache-reset
```



### CI Integration


In table and summary modes, the command exits non-zero when the filtered result contains errors. Warnings and hints do not affect the exit code, even when `--level warning` or `--level hint` displays them.

JSON mode is different: after successfully encoding the result, `wippy lint --json` exits with code 0 even when `error_count` is non-zero. A CI job using JSON output must parse `error_count` itself. To use the command's exit status as the gate, run a non-JSON invocation:

```bash
wippy lint --level error
```

You can produce a report separately without treating its exit status as the lint result:

```bash
wippy lint --json --level error > lint-results.json
```

Example GitHub Actions step:

```yaml
- name: Lint
  run: wippy lint --level warning
```



### Flags Reference


| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--level` | | warning | Minimum severity level (error, warning, hint) |
| `--json` | | false | Output in JSON format |
| `--ns` | | | Filter by namespace patterns |
| `--code` | | | Filter by error codes |
| `--limit` | | 0 | Max diagnostics to show (0 = unlimited) |
| `--summary` | | false | Group by error code |
| `--no-color` | | false | Disable colored output |
| `--rules` | | false | Enable lint rules (W-series style/quality checks) |
| `--cache-reset` | | false | Clear cache before linting |
| `--profile` | | | Apply a workspace profile from merged runtime configuration; repeat to apply profiles in order |
| `--set` | | | Override a merged configuration value as `section.path=value`; repeat for multiple overrides |
| `--lock-file` | `-l` | wippy.lock | Path to lock file |
| `--profile` | | | Apply a workspace profile from the merged runtime config (repeatable, applied in order) |
| `--set` | | | Override a merged runtime config value (`section.path=value`, repeatable) |



### See Also


- [CLI](guides/cli.md) — Full CLI reference
- [Types](lua/types.md) — Type-system documentation
- [LSP](guides/lsp.md) — Editor integration with live diagnostics



---

# "Language Server"

## Language Server


Wippy includes a Language Server Protocol (LSP) server for Lua editor features. It runs as part of the Wippy runtime and accepts editor connections over TCP or HTTP.



### Features


- Code completion with type-aware suggestions
- Hover information showing types and signatures
- Go to definition
- Find references
- Document and workspace symbols
- Call hierarchy (incoming and outgoing calls)
- Pull diagnostics for type errors in the current editor overlay after successful parsing
- Signature help for function parameters



### Configuration


Enable the LSP server in `.wippy.yaml`:

```yaml
lsp:
  enabled: true
  address: ":7777"
```



#### Configuration Fields


| Field | Default | Description |
|-------|---------|-------------|
| `enabled` | false | Enable the LSP service and TCP server |
| `address` | :7777 | TCP listen address |
| `http_enabled` | false | Enable the HTTP transport |
| `http_address` | :7778 | HTTP listen address |
| `http_path` | /lsp | HTTP endpoint path |
| `http_allow_origin` | * | CORS allowed origin |
| `max_message_bytes` | 8388608 | Max incoming message size (bytes) |



#### TCP Transport


The TCP server speaks JSON-RPC 2.0 with standard LSP message framing (Content-Length headers). This is the primary transport for editor integrations.



#### HTTP Transport


The HTTP transport accepts POST requests with JSON-RPC payloads. It supports browser-based editors and web tools, answers CORS preflight `OPTIONS` requests, and includes CORS headers for cross-origin access.

```yaml
lsp:
  enabled: true
  http_enabled: true
  http_address: ":7778"
  http_path: "/lsp"
  http_allow_origin: "*"
```



### Document URI Scheme


The LSP server uses the `wippy://` URI scheme to identify registry entries:

```
wippy://namespace:entry_name
```

Editors map these URIs to entry IDs in the registry. Both `wippy://` scheme and raw `namespace:entry_name` formats are accepted.



### Indexing


The LSP server maintains an index of code entries. Multiple workers update the index in the background.

Key behaviors:

- Entries are indexed in dependency order (dependencies first)
- Changes trigger re-indexing of affected entries
- Unsaved editor changes are stored in an overlay
- Indexing is incremental; only changed entries are reprocessed



### Supported LSP Methods


| Method | Description |
|--------|-------------|
| `initialize` | Capability negotiation |
| `initialized` | Initialization-complete notification |
| `shutdown` | Shut down the protocol session |
| `exit` | Exit notification |
| `textDocument/didOpen` | Track opened documents |
| `textDocument/didChange` | Full document sync |
| `textDocument/didClose` | Release documents |
| `textDocument/hover` | Type info at cursor |
| `textDocument/definition` | Jump to definition |
| `textDocument/references` | Find all references |
| `textDocument/completion` | Code completion |
| `textDocument/signatureHelp` | Function signatures |
| `textDocument/diagnostic` | File diagnostics |
| `textDocument/documentSymbol` | File symbols |
| `workspace/symbol` | Global symbol search |
| `textDocument/prepareCallHierarchy` | Call hierarchy |
| `callHierarchy/incomingCalls` | Find callers |
| `callHierarchy/outgoingCalls` | Find callees |



### Completion


The completion engine resolves types through the code graph. It provides:

- Member completion after `.` and `:` (fields, methods)
- Local variable completion
- Module-level symbol completion
- Trigger characters: `.`, `:`



### Diagnostics


After a document parses successfully, indexing stores type-checking diagnostics such as mismatches and undefined symbols. Diagnostics use the standard error, warning, information, and hint severities.

Full-document change notifications update the overlay used for diagnostics. Clients retrieve the current stored result with `textDocument/diagnostic`; this server does not push `textDocument/publishDiagnostics` notifications. A parse failure aborts re-indexing before new diagnostics are stored, so the pull result does not report that syntax error and can retain the previous successful result.



### See Also


- [Linter](guides/linter.md) — CLI-based code checking
- [Types](lua/types.md) — Type-system documentation
- [Configuration](guides/configuration.md) — Runtime configuration



---

# "Dependency Management"

## Dependency Management


Wippy resolves module dependencies from source declarations and records exact versions in `wippy.lock`. Published modules are downloaded from the Hub into the project's module directory.

The `acme/*` module names, versions, hashes, and local paths below are illustrative.
Substitute modules and verified digests from your own project or the Hub.



#### wippy.lock


The lock file tracks your project's directory layout and pinned dependencies:

```yaml
directories:
  modules: .wippy
  src: ./src
modules:
  - name: acme/http
    version: v1.2.0
    hash: 4ea816fe84ca58a1f0869e5ca6afa93d6ddd72fa09e1162d9e600a7fbf39f0a2
  - name: acme/sql
    version: v2.0.1
    hash: b3f9c8e12a456d7890abcdef1234567890abcdef1234567890abcdef12345678
```

| Field | Description |
|-------|-------------|
| `directories.modules` | Where downloaded modules are stored (default: `.wippy`) |
| `directories.src` | Where your source code lives (default: `./src`) |
| `modules[].name` | Module identifier in `org/module` format |
| `modules[].version` | Pinned semantic version |
| `modules[].hash` | Artifact digest the downloaded pack must match; a bare hex value is read as `sha256` |
| `modules[].root` | Marks the selected deployment root; at most one module may carry it |
| `options.unpack_modules` | Extract packs into directories instead of loading them as `.wapp` files (default: `false`) |



#### wippy.yaml


Module metadata for publishing. Required only when you publish your own module:

```yaml
organization: acme
module: http
version: 1.2.0
description: HTTP utilities for Wippy
license: MIT
repository: https://github.com/acme/wippy-http
keywords:
  - http
  - web
```

| Field | Required | Description |
|-------|----------|-------------|
| `organization` | Yes | Lowercase, alphanumeric with hyphens |
| `module` | Yes | Lowercase, alphanumeric with hyphens |
| `version` | No | Semantic version (set at publish time) |
| `description` | No | Module description |
| `license` | No | SPDX license identifier |
| `repository` | No | Source repository URL |
| `homepage` | No | Project homepage |
| `keywords` | No | Discovery keywords |
| `authors` | No | Author list |



### Declaring Dependencies


Add `ns.dependency` entries in your `_index.yaml`:

```yaml
version: "1.0"
namespace: app
entries:
  - name: dependency.http
    kind: ns.dependency
    component: acme/http
    version: "^1.0.0"

  - name: dependency.sql
    kind: ns.dependency
    component: acme/sql
    version: ">=2.0.0"
```



#### Version Constraints


| Constraint | Example | Matches |
|------------|---------|---------|
| Exact | `1.2.3` | Only 1.2.3 |
| Caret | `^1.2.0` | >=1.2.0, <2.0.0 |
| Tilde | `~1.2.0` | >=1.2.0, <1.3.0 |
| Range | `>=1.0.0` | 1.0.0 and above |
| Wildcard | `*` | Any version (picks highest) |
| Combined | `>=1.0.0 <2.0.0` | Between 1.0.0 and 2.0.0 |



#### Resolution Rules


- Each module resolves against the **intersection of all declared ranges** across the dependency graph. Incompatible ranges (diamond conflicts) fail resolution with an explicit error rather than silently picking one side.
- A full `wippy update` solves every module from its declared ranges; a targeted update and boot-time repair keep a pinned version that still satisfies every live range.
- **Root parameters win over transitive ones**: when your app and a dependency both bind the same requirement, the parameters on your `ns.dependency` take precedence. Version ranges are never overridden; every declaration joins the intersection.
- A component declared by several root `ns.dependency` entries is controlled by one of them — established declarations before new ones, parameter carriers before plain ones, ties on the lowest entry ID — and the others fold into references to it. A duplicate whose parameters disagree with the controlling declaration is rejected with a conflict error; update the existing dependency instead.

Two resolution failures are reported distinctly. A constraint expression that cannot be satisfied by any release ever — the intersection of live ranges is empty — is a conflict, and the error names the module and every requester that contributed a range. A valid range set for which the hub currently publishes no matching version is an availability failure instead: a later release can make it resolvable without any change to the declarations.

The runtime persists each resolved graph in its registry history and replays it at boot instead of re-solving, so a deployed application boots with exactly the versions that were resolved when the dependency change was applied. `wippy.lock` remains the portable snapshot for source projects.



#### Entry provenance


Provenance is registry-owned, not entry metadata. When entries are loaded, the registry stamps each one with the deployment source that supplied it:

| Field | Description |
|-------|-------------|
| `registry.owner` | Module name (`org/module`) that supplied the entry; empty for application source |
| `registry.root` | Set on `ns.dependency` entries supplied by the deployment root, marking them as root declarations |

Entry authors never write these fields; they are assigned during loading and cannot be forged from an `_index.yaml`. Inspect them with `wippy registry list --registry-meta --json`.



#### Starting a New Project


```bash
wippy init
```

Creates a `wippy.lock` with default directories.



#### Adding Dependencies


```bash
wippy add acme/http               # Latest version
wippy add acme/http@1.2.3         # Exact version
wippy add acme/http@latest         # Latest label
```

This updates the lock file. Then install:

```bash
wippy install
```



#### Resolving from Source


If your source already declares `ns.dependency` entries:

```bash
wippy update
```

This scans your source directory, resolves all dependency constraints, updates the lock file, and installs modules.



#### Updating Dependencies


```bash
wippy update                       # Re-resolve all dependencies
wippy update acme/http             # Update only acme/http
wippy update acme/http acme/sql    # Update specific modules
```

When updating specific modules, other modules stay pinned to their current versions. If the update would require changing non-target modules, you are prompted for confirmation.



#### Installing from Lock File


```bash
wippy install                      # Install all from lock
wippy install --refresh            # Re-fetch every module (--force and --repair are aliases)
```



### Module Storage


Downloaded modules are stored under the `.wippy/vendor/` directory:

```
project/
  wippy.lock
  src/
    _index.yaml
  .wippy/
    vendor/
      acme/
        http-v1.2.0.wapp
        sql-v2.0.1.wapp
```

By default, modules are kept as `.wapp` files. To extract them into directories:

```yaml


## wippy.lock

options:
  unpack_modules: true
```

With unpacking enabled:

```
.wippy/
  vendor/
    acme/
      http-v1.2.0.wapp
      http/
        wippy.yaml
        src/
          _index.yaml
          ...
```

Unpacking never discards the pack. The canonical verified `.wapp` stays beside the extracted directory because it is the only content-addressed evidence for the module, and artifact materialization and repair read resources back out of it. The `.wapp` is what installation checks for: a directory whose pack is missing counts as not installed, and the module is downloaded again. Each install extracts the directory afresh from the verified archive, so hand-edits to a vendored directory do not survive.

Modules resolved from a [workspace replacement](#local-development-with-replacements) are never downloaded or vendored; they load from the local path.



### Local Development with Replacements


For local development, map Hub modules to local directories in the `workspace` section of a runtime configuration file. This is typically a private, ignored file composed over `.wippy.yaml`:

```yaml


## .wippy.workspace.yaml

version: "1.0"
workspace:
  replacements:
    acme/http: ../local-http
    acme/sql: ../local-sql
```

```bash
wippy run --config .wippy.yaml --config .wippy.workspace.yaml
```

Keys are `org/module`, values are directories (relative paths resolve against the first `--config` file's directory). Setting a replacement to `null` disables one inherited from an earlier config layer or profile. Replacements can also live inside a [profile](guides/configuration.md#profiles) so they activate only with `--profile workspace`.

The path is required to exist, and to be a directory, only for a module the lock graph actually selects. A replacement declared for a module that nothing depends on is a resolution input, not a boot input: it can point at a directory that is not checked out on this machine without failing validation.

A replacement changes where a module's source comes from, not which release was chosen. It keeps the selected version, while reconciliation snapshots the current local tree and records its digest and size as the replacement identity. Entries loaded from it shadow the vendored ones with the same ID. When a replacement is declared for a module the lock does not pin a version for, resolution asks the hub for a release version, and until stronger evidence selects one it holds a local-only zero version.

Workspace replacements affect the load graph at boot and are never written to `wippy.lock`. Changes to the local source are reconciled directly, without contacting the hub. The module's source `exclude:` globs from `wippy.yaml` apply to replacement directories too, both when loading entries and when hashing content.

The `replacements:` section in `wippy.lock` is deprecated. It still loads with a warning; move those entries to `workspace.replacements` in a configuration file.



### Load Order


At boot, Wippy loads entries from directories in this order:

1. Source directory (`src`)
2. Replacement directories
3. Vendored module directories

Modules with active replacements skip their vendor path.



### Integrity Verification


Every module in the lock file carries an artifact digest. Boot refuses to load a module whose lock entry has none; `wippy install` accepts such an entry and records the digest the hub serves with the download.

At boot, downloads are staged: the pack is written to a temporary file next to its final location, verified against both the digest pinned in `wippy.lock` and the digest the hub served with the download URL (plus the served size), and only then renamed into place. A staged file that fails verification is deleted. `wippy install` renames the download into its vendor path before verifying it, checks it against the served digest and size only, deletes it on failure, and replaces a lock digest that differs from the served one rather than enforcing it.

A digest mismatch is a hard, non-retryable failure. At boot it is `PermissionDenied`, "module integrity verification failed", raised for a fresh download and for an already-vendored pack, which is re-verified against the lock digest before entries are loaded. `wippy install` reports it as `Internal`: "failed to store module" wrapping "verify cached WAPP: digest mismatch" for a pack already in the vendor directory, and "failed to download module" wrapping "verify downloaded WAPP: digest mismatch" for a fresh download. Nothing retries, re-downloads over the mismatch, or falls back to the served content.

The same check guards resolution. When the hub serves a manifest whose digest differs from the one the lock pins, the manifest cache is refreshed once and re-compared; if it still disagrees, resolution fails naming both digests.

Extracted directories carry their own recorded digest, size, and tree digest, and are re-verified against the recorded values, so a modified vendored tree is detected rather than loaded.

Replacement sources are content-addressed per reconciliation attempt. The runtime
snapshots the current local tree, then verifies that same digest and size before
loading it. A concurrent change fails validation instead of mixing two source
generations. A later reconciliation can accept a new local tree; its old recorded
digest is a checkpoint, not an immutable Hub artifact identity.

On restart, immutable historical artifacts are prefetched separately. Historical
local replacements are reconciled against the final dependency declarations
before loading, so a removed replacement does not require its old directory to
remain on disk. A replacement still selected by the final graph must be present
and valid.



### Build-time Artifacts


A module can ship a filesystem resource marked with `meta.artifact.format` that consumers materialize onto disk instead of reading at runtime. Full and targeted `wippy install` and `wippy update`, cold boot, and runtime dependency operations reconcile those outputs as part of the same transaction that changes the module graph; `artifact.materialization_root` sets the output root. See [Build-time artifacts](guides/artifacts.md).



### See Also


- [Build-time artifacts](guides/artifacts.md) - Declaring, materializing and reconciling artifact resources
- [Building Components](guides/components.md) - The author side: `ns.requirement` and supplying values via `parameters`
- [CLI](guides/cli.md) - Command reference
- [Publishing](guides/publishing.md) - Publishing modules to the hub
- [Project Structure](start/structure.md) - Project layout



---

# "Build-time artifacts"

## Build-time artifacts


A module can ship a directory that consumers use **at build time** rather than
at runtime — most usefully, a package that other modules compile against. Wippy
calls these **artifacts**: ordinary WAPP filesystem resources marked with
`meta.artifact.format`.

This is how a shared package reaches a module in a different repository. A path
alias only resolves inside one repo; an artifact travels with the module.

[The Design Layer](../frontend/design-layer.md) explains *what* belongs in such
a package and what does not; this page is the mechanism that ships it.



### Declaring an artifact


The producer declares a normal `fs.directory` and marks it with a format:

```yaml


## src/_index.yaml

entries:
  - name: package_fs
    kind: fs.directory
    meta:
      comment: The npm package consumers materialize at build time.
      artifact:
        format: node-package
    directory: ./package
```

Nothing else changes: the resource is embedded into the WAPP like any other
`fs.directory` — list it under `embed:` in `wippy.yaml` or pass `--embed` to
`wippy publish` and `wippy pack`; a directory that is not embedded is neither
packed nor validated. Declared artifacts are **validated during module publish
and application pack**, so a malformed one fails at publish rather than in a
consumer.



### Formats


A format adapter decides how a directory is validated, what identity it has,
and where it lands. Wippy ships one built-in:

| Format | Owns subtree | Validates |
|---|---|---|
| `node-package` | `npm/` | `package.json` |

`node-package` requires a `name` and a semantic `version`, and **rejects
`preinstall`, `install`, `postinstall` and `prepare` lifecycle scripts** — a
materialized package may not execute anything on install. It writes to
`npm/<package name>` under the materialization root.

The format must be registered in the binary doing the work. Hosts may register
additional formats; duplicate names and overlapping roots are rejected.



### Materializing


Most of the time you do not run anything. Materialized outputs are reconciled
automatically during:

- full and targeted `wippy install` and `wippy update`
- cold boot
- Hub-backed dynamic install, update and uninstall

Full install, update, cold boot and runtime dependency reconciliation are
*exact*: stale outputs are pruned. A **targeted** install overlays only the
selected modules and preserves outputs belonging to modules it did not select.

Local module replacements go through the same validation and materialization
lifecycle as packed resources, so a replaced module's artifact behaves like a
published one.



#### Materializing explicitly


For a build step that needs the artifact before the runtime is involved, the
CLI exposes it directly:

```bash
wippy artifacts materialize <pack.wapp> <namespace:name> [--root <directory>]
```

`--root` defaults to `.wippy`. The resource must declare `meta.artifact.format`
and that format must be registered in this CLI.

Be clear about what this command deliberately does **not** do: it does not
resolve module dependencies, does not mutate `wippy.lock`, does not invoke
package managers, and does not participate in runtime composition. It validates
one artifact out of one WAPP and writes it to disk.



#### Where output lands


`artifact.materialization_root` configures the application-owned output root.
Its default is the parent of the dependency vendor directory. Each format owns
a non-overlapping subtree beneath it, so `node-package` output is always under
`<root>/npm/`.

Materialization is transactional. Content is validated and staged, managed
roots are swapped atomically under a process lock, a failure rolls back with
the surrounding registry transaction, and an interrupted swap is recovered on
the next run.



### Worked example: a shared frontend package


A producer module whose only job is to publish a package — it serves nothing at
runtime:

```yaml


## platform/ui-kit/src/_index.yaml

version: "1.0"
namespace: kickside.ui_kit

entries:
  - name: package_fs
    kind: fs.directory
    meta:
      artifact:
        format: node-package
    directory: ./package
```

A consumer materializes it into its own tree before installing dependencies:

```bash
wippy artifacts materialize kickside-ui-kit-1.5.0.wapp \
  kickside.ui_kit:package_fs --root ./.wippy
```

That writes `./.wippy/npm/@kickside/ui-kit`. The consumer picks it up with an
ordinary workspaces glob, so resolution is plain node resolution from there on:

```json
{
  "workspaces": ["./.wippy/npm/@*/*"]
}
```

```bash
npm install
```

Two things worth copying from this shape:

- **The package is its own module, not a directory inside a bigger one.** The
  artifact carries its own `package.json` version, and tying it to a module
  that changes for unrelated reasons forces a release of one every time the
  other moves.
- **The consumer resolves it as a normal dependency.** Once materialized there
  is no Wippy-specific import path, which is what lets the same source build
  inside the monorepo and outside it.



#### Authoring the producer


For a package artifact there is usually **nothing to build** — the directory is
the deliverable. A CSS vocabulary package is just files plus a manifest:

```text
platform/ui-kit/
├── src/_index.yaml      # declares package_fs as the artifact
└── package/             # the directory that becomes the npm package
    ├── package.json
    ├── kx-card.css
    └── kx-state.css
```

```json
{
  "name": "@kickside/ui-kit",
  "version": "1.5.0",
  "type": "module",
  "sideEffects": ["*.css"],
  "exports": {
    "./kx-card.css": "./kx-card.css",
    "./kx-state.css": "./kx-state.css"
  },
  "files": ["kx-card.css", "kx-state.css", "package.json"]
}
```

`sideEffects` matters for a CSS-only package: without it a bundler is free to
treat an imported stylesheet as dead code and drop it.

**The package version must equal the module version.** `wippy publish`
validates this and refuses a mismatch, so bump both together. This is also the
reason to give a shared package its *own* module rather than nesting it inside
a larger one — otherwise every unrelated change to the host module forces a
release of the package, and vice versa.



#### Publishing


```bash


## validate without publishing

wippy publish --dry-run --version 1.5.0 --embed package_fs



## publish

wippy publish --create --module-type library --module-visibility public --version 1.5.0 --embed package_fs
```

Declared artifacts are validated as part of publish, so a package.json that
fails the format's rules is rejected here rather than in a consumer's build.



#### The dev loop


Publishing on every edit is not a dev loop. Pack the producer locally and point
the consumer's materialize step at that file instead:

```bash


## from the producer module

wippy pack /tmp/ui-kit-dev.wapp --embed package_fs



## consumers materialize from the local pack rather than the published one

UI_KIT_WAPP=/tmp/ui-kit-dev.wapp make ui-kit MOD=workflows
```

Keep that override as the *only* difference between the dev path and CI — an
environment variable that selects the pack file, with everything downstream
identical. A dev loop that materializes differently from CI stops predicting
CI.



#### Wiring it into make and CI


Make the materialize step a **prerequisite of the consumer's build**, not a
thing a person remembers to run:

```make
UI_KIT_WAPP ?=

build:
	@case " $(UI_KIT_CONSUMERS) " in *" $(MOD) "*) $(MAKE) ui-kit MOD=$(MOD);; esac
	cd $(call fe_dir,$(MOD)) && npm run build
```

CI then needs no artifact-specific step at all: it runs the same `make build`,
`UI_KIT_WAPP` is unset, so the fetch-and-materialize path runs against the
published version pinned in `build-inputs`. A fresh checkout cannot compile
against a stale or missing package, and a contributor who has never heard of
artifacts still gets a correct build.



### What you still have to hand-roll


`wippy artifacts materialize` is deliberately narrow, so a build that consumes
an artifact currently glues four steps together itself. Knowing which four
saves rediscovering them:

**1. Getting the `.wapp`.** The command takes a *pack file path*, not a module
reference, and does not resolve dependencies — so something has to fetch the
producer first. The workable pattern is a tiny Wippy project whose only job is
to pin and download it:

```yaml


## build-inputs/wippy.lock — a project that exists only to fetch

directories:
  modules: .wippy
  src: ./src
modules:
  - name: kickside/ui-kit
    version: 1.5.0
    hash: be1eafd5…
```

```bash
( cd build-inputs && wippy install )
wapp=$(ls build-inputs/.wippy/vendor/kickside/ui-kit-*.wapp | grep -v sha256 | sort | tail -1)
```

Pinning it here rather than in the application lock keeps a build-time input
out of the runtime dependency graph.

**2. Materializing once per consumer**, into a root the consumer's package
manager can see:

```bash
wippy artifacts materialize "$wapp" kickside.ui_kit:package_fs --root ./ui/.wippy
```

**3. Wiring the consumer's `package.json`.** Materializing writes files; it
does not edit manifests. npm links the package only if the consumer declares
*both* the workspace glob and the dependency:

```json
{
  "workspaces": ["./.wippy/npm/@*/*"],
  "dependencies": { "@kickside/ui-kit": "*" }
}
```

The version is `*` because the materialized package carries its own. Script
this and make it idempotent — if the wiring is missing, the build fails much
later with a bare `ENOENT` on a stylesheet, which reads as a missing file
rather than as missing wiring.

**4. Running the package manager.** `materialize` does not invoke one, so
`npm install` is yours to call, after step 3.

Together, in a target that takes the consuming module as a parameter:

```make
ui-kit:
	@set -e; \
	( cd build-inputs && $(WIPPY) install ); \
	wapp=$$(ls build-inputs/.wippy/vendor/kickside/ui-kit-*.wapp | grep -v sha256 | sort | tail -1); \
	test -n "$$wapp" || { echo "no ui-kit .wapp; is the module published?"; exit 1; }; \
	$(WIPPY) artifacts materialize "$$wapp" kickside.ui_kit:package_fs --root $(DIR)/.wippy; \
	cd $(DIR) && node ../../scripts/wire-ui-kit.mjs && npm install --no-audit --no-fund
```

Make the whole target a prerequisite of the consumer's build, so a fresh
checkout cannot compile against a stale or absent package.



### Out of scope


Artifacts intentionally do not introduce a second resolver, package registry,
archive format, lock schema, Hub API, or module manifest. Build-only dependency
semantics, redistribution policy and host ABI validation are separate concerns
and are not solved here.



### Related


- [Dependency Management](./dependency-management.md) — resolving modules and
  local replacements
- [Publishing](./publishing.md) — what a published module contains
- [The Design Layer](../frontend/design-layer.md) — why a shared frontend
  vocabulary ships as a package in the first place



---

# "Building Components"

## Building Components


A **component** is a reusable Wippy module published to the Hub and mounted into a host application. A component can depend on a database, process host, or router without knowing the host's entry IDs. It declares these dependencies through a **requirement interface**, and the host supplies their values.

This guide covers the author side: declaring that interface and understanding how values flow into your entries. For the consumer side (lock files, version constraints, `wippy add`/`update`) see [Dependency Management](guides/dependency-management.md). For how a component is structured internally see [Application Architecture](concepts/architecture.md).



### The Three Entry Kinds


| Kind | Side | Role |
|------|------|------|
| `ns.definition` | component | Module metadata; required to publish. |
| `ns.requirement` | component | A hole the host must fill, and where to inject the value. |
| `ns.dependency` | host | Mounts a component and supplies values for its requirements. |



### ns.definition


Each published module must have exactly one definition. The definition can carry module metadata, a README reference, and wiki page references.

```yaml
- name: definition
  kind: ns.definition
  module: jobs                # optional module metadata
  readme: file://README.md    # path to the module's documentation
  meta:
    title: Durable Jobs
    description: Leased job queue with retry and dead-lettering.
```

`module`, `readme`, and `wiki` are definition data; all are optional. `meta` is ordinary entry metadata for management UIs. Release notes are supplied at publish time, not here.



### ns.requirement


A requirement is a **named value with a list of injection targets**. The host supplies the value, and the runtime writes it into each target entry at the specified path.

```yaml
- name: target_db
  kind: ns.requirement
  meta:
    description: SQL database backing every table in this module.
  default: app:db
  targets:
    - entry: app.jobs.migrations:schema
      path: .meta.target_db
    - entry: app.jobs.persist:lifecycle
      path: .db
```



#### `default`: Mandatory or Optional


The `default` field decides whether the host *must* supply a value:

- **`default` present with a non-null value** (including an empty string) → the requirement is **optional**. If the host supplies nothing, the default is used.
- **`default` absent** → the requirement is **mandatory**. With nothing supplied, linking fails under strict mode (and warns otherwise).

<note>
An explicitly empty default (<code>default: ""</code>) is distinct from an
absent or null default. Empty-string means "optional, falls back to nothing";
absent and <code>default: null</code> both mean "the host must provide this."
Use a non-null default for infrastructure that has a sane in-app convention
(<code>app:db</code>, <code>app:processes</code>); omit it for values only the
host can know.
</note>



#### `targets`: Injection Locations


Each target is an `{entry, path}` pair:

- **`entry`** — the entry the value is injected into. A bare name (`schema`) resolves within the requirement's own namespace; a fully-qualified id (`app.jobs.migrations:schema`) targets that entry exactly, across namespaces.
- **`path`** — a dot path into the target entry, e.g. `.meta.target_db`, `.host`, `.database.url`. The leading dot is conventional.

A requirement must declare at least one target.

Append instead of set with the `+=` suffix on the path — useful when several requirements contribute to one list (e.g. middleware):

```yaml
targets:
  - entry: app.api:router
    path: .middleware+=     # appends the value to the list at .middleware
```



#### One Requirement, Multiple Targets


Group targets that need the same value under one requirement. For example, `target_db` can supply every migration's `.meta.target_db` and persistence library's `.db`; `process_host` can supply each supervised service's `.host`; and `api_router` can supply each endpoint's `.meta.router`:

```yaml
- name: process_host
  kind: ns.requirement
  default: app:processes
  targets:
    - { entry: app.jobs.service:worker.service, path: .host }
    - { entry: app.jobs.service:sweeper.service, path: .host }
```

The host supplies one value, and the runtime writes it to every declared target. The requirement entry contains this wiring directly.



### Consuming a Component


The host mounts a component with `ns.dependency` and fills its requirements through `parameters`:

```yaml
version: "1.0"
namespace: app
entries:
  - name: dep.jobs
    kind: ns.dependency
    component: acme/jobs
    version: "^1.0.0"
    parameters:
      - name: target_db
        value: app:db
      - name: process_host
        value: app:processes
      - name: api_router
        value: app:api
```

Each `parameter.name` matches a requirement; its `value` is what gets injected into that requirement's targets. Requirements with a default may be omitted; mandatory ones must be supplied.



#### Parameter Name Matching


How a parameter name binds to a requirement:

- **Bare name** (`target_db`) matches a requirement of that name belonging to the component being mounted. It does not cross into a different module's requirements.
- **Qualified name** (`acme.jobs:target_db`) matches that requirement id exactly. Use this to disambiguate when wiring transitive dependencies.

If two dependencies supply **different** values for the same requirement, that is a conflict and is reported (identical values are fine).



### When Values Resolve


Injection happens at the **Link stage** of the build pipeline — at publish, during dependency expansion, and at boot — not at runtime. The stage:

1. Collects every `ns.requirement` and every `ns.dependency` with its parameters.
2. For each requirement, resolves a value: a matching parameter wins; otherwise the default; otherwise (no default) it is unresolved.
3. Writes the resolved value into each target entry at its path (set, or append for `+=`).

Under **strict requirements** an unresolved mandatory requirement fails the build; otherwise it logs a warning and proceeds. By the time entries reach the runtime, every filled requirement has already been baked into its targets.



### Verify Integration with a Mount Test


Unit tests do not verify the assembled module's registry relationships. Add a packaging or mount test against the requirement-injected registry to verify that:

- every supervised `service` points at a process entry that exists,
- every spawned or scheduled id resolves to a real entry,
- every `env.variable`'s storage is registered.

This catches unresolved relationships such as a supervisor referencing an unregistered worker or a test fixture using a harness-only storage ID. See [Supervision](guides/supervision.md) and the [Testing](framework/testing.md) framework.



### See Also


- [Application Architecture](concepts/architecture.md) — how a component is structured internally
- [Dependency Management](guides/dependency-management.md) — lock files, versions, the consumer workflow
- [Publishing Modules](guides/publishing.md) — putting a component on the hub
- [Entry Kinds Guide](guides/entry-kinds.md) — `ns.definition`, `ns.requirement`, `ns.dependency` reference



---

# "Entry Kinds Reference"

## Entry Kinds Reference


This page summarizes the available entry kinds and links to their detailed module and system references.

The YAML and Lua blocks are reference fragments, not one application. Registry IDs,
credentials, data objects, and helpers such as `get_users` or `delete_user` are
illustrative; use the linked module pages for complete return and error contracts.

> Entries reference one another using `namespace:name`. The registry uses these references to resolve dependencies and initialization order.



### See Also


- [Registry](concepts/registry.md) — How entries are stored and resolved
- [Configuration](guides/configuration.md) — YAML configuration format



### Lua Runtime


| Kind | Description |
|------|-------------|
| `function.lua` | Lua function entry point |
| `process.lua` | Long-running Lua process |
| `workflow.lua` | Temporal workflow (deterministic) |
| `library.lua` | Shared Lua library |
| `module.lua` | Lua module surface |
| `function.lua.bc` | Precompiled function bytecode |
| `library.lua.bc` | Precompiled library bytecode |
| `process.lua.bc` | Precompiled process bytecode |
| `workflow.lua.bc` | Precompiled workflow bytecode |

```yaml
- name: handler
  kind: function.lua
  source: file://handler.lua
  method: main
  modules:
    - http
    - json
  imports:
    utils: app.lib:helpers  # Import another entry as module
```

<tip>
Use <code>imports</code> to reference other Lua entries. They become available via <code>require("alias_name")</code> in your code.
</tip>



### HTTP Services


| Kind | Description |
|------|-------------|
| `http.service` | HTTP server (binds port) |
| `http.router` | Route prefix and middleware |
| `http.endpoint` | HTTP endpoint (method + path) |
| `http.static` | Static file serving |

```yaml


## HTTP server

- name: gateway
  kind: http.service
  addr: ":8080"
  lifecycle:
    auto_start: true



## Router with middleware

- name: api
  kind: http.router
  meta:
    server: gateway
  prefix: /api
  middleware:
    - cors
    - ratelimit



## Endpoint

- name: users_list
  kind: http.endpoint
  meta:
    router: app:api
  method: GET
  path: /users
  func: list_handler
```

**Lua API:** See [HTTP Module](lua/http/http.md)

```lua
local http = require("http")
local req = http.request()
local resp = http.response()

resp:set_status(200)
resp:write_json({users = get_users()})
```



### Databases


| Kind | Description |
|------|-------------|
| `db.sql.sqlite` | SQLite database |
| `db.sql.postgres` | PostgreSQL database |
| `db.sql.mysql` | MySQL database |
| `db.cdc.postgres` | Postgres Change Data Capture source (see [CDC](system/cdc.md)) |
| `db.cdc.sqlite` | SQLite Change Data Capture source (see [CDC](system/cdc.md)) |



#### SQLite


```yaml
- name: database
  kind: db.sql.sqlite
  file: "./data/app.db"
  lifecycle:
    auto_start: true



## In-memory for testing

- name: testdb
  kind: db.sql.sqlite
  file: ":memory:"
```



#### PostgreSQL


```yaml
- name: database
  kind: db.sql.postgres
  host: localhost
  port: 5432
  database: dbname
  username: user
  password: pass
  options:
    sslmode: disable
  pool:
    max_open: 25
    max_idle: 5
    max_lifetime: "30m"
  lifecycle:
    auto_start: true
```



#### MySQL


```yaml
- name: database
  kind: db.sql.mysql
  host: localhost
  port: 3306
  database: dbname
  username: user
  password: pass
  options:
    parseTime: "true"
  lifecycle:
    auto_start: true
```

See [Database](system/database.md) for `${env:NAME}` secret references, TLS options, and connection pool tuning. When an env-backed value behind a database entry changes, the pool swaps live — active borrows finish against the old connection settings.

**Lua API:** See [SQL Module](lua/storage/sql.md)

```lua
local sql = require("sql")
local db, err = sql.get("app:database")

local rows, err = db:query("SELECT * FROM users WHERE id = ?", {user_id})
db:execute("INSERT INTO logs (msg) VALUES (?)", {message})
```




### Key-Value Stores


| Kind | Description |
|------|-------------|
| `store.memory` | In-memory key-value store |
| `store.sql` | SQL-backed key-value store |
| `store.kv.raft` | Cluster-replicated, strongly-consistent KV (shared Raft) |
| `store.kv.crdt` | Cluster-replicated, eventually-consistent KV (gossip/CRDT) |

```yaml


## Memory store

- name: cache
  kind: store.memory
  lifecycle:
    auto_start: true



## SQL-backed store

- name: persistent_store
  kind: store.sql
  database: app:database
  table_name: kv_store
  lifecycle:
    auto_start: true



## Cluster-replicated store (requires clustering)

- name: deployments
  kind: store.kv.raft
  namespace: deploy
```

The `store.kv.*` kinds need [clustering](guides/cluster.md) enabled. See [Store](system/store.md#cluster-kv-stores) for the consistency tradeoffs.

**Lua API:** See [Store Module](lua/storage/store.md)

```lua
local store = require("store")
local s, err = store.get("app:cache")

s:set("user:123", user_data, 3600)  -- TTL in seconds
local data = s:get("user:123")
```



### Queues


| Kind | Description |
|------|-------------|
| `queue.driver.memory` | In-memory queue driver |
| `queue.driver.amqp` | AMQP (RabbitMQ) driver |
| `queue.driver.sqs` | AWS SQS driver |
| `queue.queue` | Queue declaration |
| `queue.consumer` | Queue consumer |

```yaml


## Driver

- name: queue_driver
  kind: queue.driver.memory
  lifecycle:
    auto_start: true



## Queue

- name: jobs
  kind: queue.queue
  driver: queue_driver



## Consumer

- name: job_consumer
  kind: queue.consumer
  queue: app:jobs
  func: job_handler
  concurrency: 4
  prefetch: 10
  lifecycle:
    auto_start: true
```

**Lua API:** See [Queue Module](lua/storage/queue.md)

```lua
local queue = require("queue")

-- Publish a message
queue.publish("app:jobs", {task = "process", id = 123})

-- In a consumer handler: the message body is the handler's argument
local function main(data)
    -- access delivery metadata via the current message
    local msg = queue.message()
    local id = msg:id()
    local priority = msg:header("priority")
    msg:ack()
end
```

<note>
The consumer's <code>func</code> is invoked once per message with the message body as its argument. Use <code>queue.message()</code> inside the handler for the delivery's <code>id()</code>, <code>header()</code>/<code>headers()</code>, and <code>ack()</code>/<code>nack()</code>.
</note>



### Process Management


| Kind | Description |
|------|-------------|
| `process.host` | Process execution host |
| `process.service` | Supervised process (wraps process.lua) |
| `terminal.host` | Terminal/CLI host |
| `pg.scope` | Process-group scope (see [Process Groups](system/process-groups.md)) |

```yaml


## Process host (where processes run)

- name: processes
  kind: process.host
  host:
    workers: 32             # Worker goroutines (default: NumCPU)
    queue_size: 1024        # Global queue capacity
    local_queue_size: 256   # Per-worker queue
  lifecycle:
    auto_start: true



## Process definition

- name: worker_process
  kind: process.lua
  source: file://worker.lua
  method: main



## Supervised process service

- name: worker
  kind: process.service
  process: app:worker_process
  host: app:processes
  input: ["arg1", "arg2"]
  lifecycle:
    auto_start: true
    restart:
      max_attempts: 10

- name: terminal
  kind: terminal.host
  lifecycle:
    auto_start: true
```

<tip>
Use <code>process.service</code> when you need a process to run as a supervised service with automatic restart. The <code>process</code> field references a <code>process.lua</code> entry.
</tip>

Updating a live `process.host` entry rescales `host.workers` in place — running processes, PIDs, and queues are preserved. `host.queue_size`, `host.local_queue_size`, and `lifecycle` are fixed at construction: a live update changing them is rejected, as is resizing workers on a host whose workers are affinity-managed.



#### Process security


`process.lua` and `process.lua.bc` entries accept a top-level `security:` block. It is part of the entry, so it applies to every spawn of that process, on both `process.host` and `terminal.host`:

```yaml
- name: worker_process
  kind: process.lua
  source: file://worker.lua
  method: main
  security:
    actor:
      id: system.worker
      meta:
        tenant: acme
    policies:
      - app.security:worker_policy
    groups:
      - app.security:background_jobs
```

| Field | Description |
|-------|-------------|
| `actor.id` | Actor identity the process runs as; replaces the inherited actor |
| `actor.meta` | Actor attributes policies evaluate |
| `policies` | Registry IDs (`namespace:name`) of policies merged into the scope |
| `groups` | Registry IDs of policy groups whose policies are merged into the scope |

Resolution happens as the process starts and is atomic: if any listed policy or group cannot be resolved, the spawn fails and no partial context is installed. Omitting `actor` inherits the spawner's actor; omitting both `policies` and `groups` inherits the spawner's scope. `function.lua`, `function.lua.bc`, `process.lua`, and `process.lua.bc` all accept the block.

A command entry can additionally declare `meta.command.security`, which applies only when the entry is launched as a CLI command — see [Command security](guides/cli.md#command-security). It does not affect ordinary spawns.

See [Security](system/security.md).



### Temporal (Workflows)


| Kind | Description |
|------|-------------|
| `temporal.client` | Temporal client connection |
| `temporal.worker` | Temporal worker |

```yaml
- name: temporal_client
  kind: temporal.client
  address: "localhost:7233"
  namespace: "default"
  auth:
    type: none  # none, api_key, mtls
  lifecycle:
    auto_start: true

- name: temporal_worker
  kind: temporal.worker
  client: temporal_client
  task_queue: "main-queue"
  lifecycle:
    auto_start: true
```



### Cloud Storage


| Kind | Description |
|------|-------------|
| `config.aws` | AWS configuration |
| `cloudstorage.s3` | S3 bucket access |

```yaml
- name: aws
  kind: config.aws
  region: "us-east-1"
  access_key_id: ${env:AWS_ACCESS_KEY_ID}
  secret_access_key: ${env:AWS_SECRET_ACCESS_KEY}

- name: uploads
  kind: cloudstorage.s3
  config: app:aws
  bucket: "my-uploads"
  endpoint: ""  # Optional, for S3-compatible services
```

**Lua API:** See [Cloud Storage Module](lua/storage/cloud.md)

```lua
local cloudstorage = require("cloudstorage")
local storage, err = cloudstorage.get("app:uploads")

storage:upload_object("files/doc.pdf", file_content)
local url = storage:presigned_get_url("files/doc.pdf", {expiration = 3600})  -- seconds, default 3600
```

<tip>
Use <code>endpoint</code> to connect to S3-compatible services like MinIO or DigitalOcean Spaces.
</tip>



### File Systems


| Kind | Description |
|------|-------------|
| `fs.directory` | Directory access |
| `fs.embed` | Read-only embedded filesystem |

```yaml
- name: data_dir
  kind: fs.directory
  directory: "./data"
  auto_init: true   # Create if not exists
  mode: "0755"      # Permissions
```

**Lua API:** See [Filesystem Module](lua/storage/filesystem.md)

```lua
local fs = require("fs")
local filesystem, err = fs.get("app:data_dir")

local file = filesystem:open("output.txt", "w")
file:write("Hello, World!")
file:close()
```



### Environment


| Kind | Description |
|------|-------------|
| `env.storage.memory` | In-memory env storage |
| `env.storage.file` | File-based env storage |
| `env.storage.os` | OS environment |
| `env.storage.static` | Read-only static key-value storage |
| `env.storage.router` | Env router (multiple storages) |
| `env.variable` | Environment variable |

```yaml
- name: os_env
  kind: env.storage.os

- name: file_env
  kind: env.storage.file
  file_path: ".env"
  auto_create: true

- name: defaults
  kind: env.storage.static
  values:
    PUBLIC_API_HOST: "https://api.example.com"
    APP_ENV: "production"

- name: app_env
  kind: env.storage.router
  storages:
    - app:os_env
    - app:file_env
    - app:defaults
```

**Lua API:** See [Env Module](lua/system/env.md)

```lua
local env = require("env")

local api_key = env.get("API_KEY")
env.set("CACHE_TTL", "3600")
```

<note>
The router tries storages in order. First match wins for reads; writes go to the first storage in the list.
</note>



### Templates


| Kind | Description |
|------|-------------|
| `template.jet` | Individual Jet template |
| `template.set` | Template set configuration |

```yaml


## Template set with engine configuration

- name: templates
  kind: template.set
  engine:
    development_mode: false
    extensions:
      - ".jet"
      - ".html.jet"



## Individual template

- name: email_template
  kind: template.jet
  source: file://templates/email.jet
  set: app:templates
```

**Lua API:** See [Template Module](lua/text/template.md)

```lua
local templates = require("templates")
local set, err = templates.get("app:templates")

local html = set:render("email", {
    user = "Alice",
    message = "Welcome!"
})
```



### Security


| Kind | Description |
|------|-------------|
| `security.policy` | Security policy with conditions |
| `security.policy.expr` | Expression-based policy |
| `security.token_store` | Token storage |

```yaml


## Condition-based policy

- name: admin_policy
  kind: security.policy
  policy:
    actions: "*"
    resources: "*"
    effect: allow
    conditions:
      - field: "actor.meta.role"
        operator: eq
        value: "admin"



## Expression-based policy

- name: owner_policy
  kind: security.policy.expr
  policy:
    actions: "*"
    resources: "*"
    effect: allow
    expression: 'actor.id == meta.owner_id || actor.meta.role == "admin"'
  groups:
    - operators
```

Policy groups are formed by the policies themselves: a policy lists the group IDs it belongs to under `groups:`, and a group is the set of policies naming it. There is no separate group entry kind. Group IDs are registry IDs — a bare name resolves in the declaring policy's namespace, so `operators` above becomes `app.security:operators` when declared in namespace `app.security`. Entries reference groups by their full `namespace:name`.

**Lua API:** See [Security Module](lua/security/security.md)

```lua
local security = require("security")

-- Check permission before action
if security.can("delete", "users", {user_id = id}) then
    delete_user(id)
end

-- Get current actor
local actor = security.actor()
```

<warning>
Every policy in scope is evaluated. A <code>deny</code> from any matching policy wins over every <code>allow</code>; with no deny, a matching <code>allow</code> grants access. Order does not matter.
</warning>



### Contracts (Dependency Injection)


| Kind | Description |
|------|-------------|
| `contract.definition` | Interface with method specifications |
| `contract.binding` | Maps contract methods to function implementations |

```yaml


## Define the contract interface

- name: greeter
  kind: contract.definition
  methods:
    - name: greet
      description: Returns a greeting message
    - name: greet_with_name
      description: Returns a personalized greeting
      input_schemas:
        - format: "application/schema+json"
          definition: {"type": "string"}
      output_schemas:
        - format: "application/schema+json"
          definition: {"type": "string"}



## Implementation functions

- name: greeter_greet
  kind: function.lua
  source: file://greeter_greet.lua
  method: main

- name: greeter_greet_name
  kind: function.lua
  source: file://greeter_greet_name.lua
  method: main



## Bind contract methods to implementations

- name: greeter_impl
  kind: contract.binding
  contracts:
    - contract: app:greeter
      default: true
      methods:
        greet: app:greeter_greet
        greet_with_name: app:greeter_greet_name
```

Usage from Lua:

```lua
local contract = require("contract")

-- Open binding by ID
local greeter, err = contract.open("app:greeter_impl")

-- Call methods
local result = greeter:greet()
local personalized = greeter:greet_with_name("Alice")

-- Check if instance implements contract
local is_greeter = contract.is(greeter, "app:greeter")
```

**Lua API:** See [Contract Module](lua/core/contract.md)

<tip>
Mark one binding as <code>default: true</code> to use it when opening a contract without specifying a binding ID. A contract may have only one default binding.
</tip>



### Execution


| Kind | Description |
|------|-------------|
| `exec.native` | Native command execution |
| `exec.docker` | Docker container execution |

```yaml
- name: native_exec
  kind: exec.native
  default_work_dir: "/app"
  command_whitelist:
    - "ls"
    - "cat"

- name: docker_exec
  kind: exec.docker
  image: "python:3.11-slim"
  default_work_dir: "/workspace"
  auto_remove: true
  memory_limit: 536870912  # 512MB
  command_whitelist:
    - "python"
```



### WASM Runtime


| Kind | Description |
|------|-------------|
| `function.wat` | WebAssembly function (WAT text format) |
| `function.wasm` | WebAssembly function (binary) |
| `process.wasm` | WebAssembly process |

```yaml


## WAT text is inline source

- name: sum_wat
  kind: function.wat
  source: file://sum.wat
  method: sum
  transport: payload   # or wasi-http



## Binary WASM is loaded from a filesystem entry and verified by hash

- name: sum
  kind: function.wasm
  fs: app:modules
  path: sum.wasm
  hash: sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae
  method: sum
  transport: payload
```

`function.wasm` and `process.wasm` take `fs`, `path`, and `hash` — there is no `source` field on a binary entry; `source` belongs to `function.wat` only. `hash` is required and must be `sha256:<hex>`; the module is rejected if the bytes do not match.

See [WASM Overview](wasm/overview.md).



### Networks


| Kind | Description |
|------|-------------|
| `network` | Base network overlay |
| `network.socks5` | SOCKS5 proxy overlay |
| `network.i2p` | I2P network overlay |
| `network.tailscale` | Tailscale overlay |

Referenced by `http.service` via `network:`, by `funcs`/`process` via the `network` option, and by `http_client` via the `overlay_network` option. See [Network](system/network.md).



### Registry Primitives


| Kind | Description |
|------|-------------|
| `registry.entry` | Plain data entry with no service behind it (app-specific config) |
| `ns.definition` | Namespace definition |
| `ns.requirement` | Namespace requirement declaration |
| `ns.dependency` | Namespace dependency |

The `ns.*` kinds are authored like any other entry: a component declares `ns.definition` and `ns.requirement`, and a host declares `ns.dependency`. See [Building Components](guides/components.md).



### Lifecycle Configuration


Supervisor-managed service entries expose lifecycle configuration. The block below belongs inside a service entry that supports it:

```yaml
lifecycle:
  auto_start: true          # Start automatically
  start_timeout: 10s        # Max startup time
  stop_timeout: 10s         # Max shutdown time
  stable_threshold: 5s      # Uninterrupted run time before retry accounting resets
  requires:
    - app:database
  restart:                  # Retry policy
    initial_delay: 1s
    max_delay: 90s
    backoff_factor: 2.0
    max_attempts: 0         # 0 = infinite
```

<note>
Use <code>depends_on</code> to ensure entries start in the correct order. The supervisor starts a dependent entry only after each of its dependencies has completed its own start.
</note>



### Entry Reference Format


Entries are referenced using `namespace:name` format:

```yaml


## Definition

namespace: app.users
entries:
  - name: handler
    kind: function.lua



## Reference from another entry

func: app.users:handler
```



### Overriding Entries


Any entry's fields — including its `kind` — can be overridden at launch without editing the source YAML, using the `override:` config section or the `-o` CLI flag. Keys use `namespace:entry:path` format:

```yaml
override:
  app:gateway:addr: ":9090"        # data field (a bare path targets data.*)
  app:worker:meta.priority: high    # meta field
  app:db:kind: db.sql.postgres      # the entry's typed kind
  app:db:data.kind: custom          # a payload field literally named "kind"
```

| Path | Targets |
|------|---------|
| `kind` | The entry's typed kind (must be a non-empty string) |
| `data.<field>` or bare `<field>` | A field in the entry's data payload |
| `meta.<field>` | A field in the entry's metadata |

The same overrides apply from the CLI:

```bash
wippy run -o app:db:kind=db.sql.postgres -o app:gateway:addr=:9090
```

CLI (`-o`) values coerce by shape (`true`/`false` to bool, numbers to numbers, otherwise string); `override:` section values keep their YAML type. To override global [configuration](guides/configuration.md) sections instead of entries, use `--set`.



---

# "Observability"

## Observability


Wippy exposes application and runtime behavior through logging, metrics, distributed tracing, and runtime statistics.



### Overview


Three observability areas are configured at boot:

| Pillar | Backend | Configuration |
|--------|---------|---------------|
| Logging | Zap (JSON structured) | `logger` and `logmanager` |
| Metrics | Prometheus | `prometheus` |
| Tracing | OpenTelemetry | `otel` |



#### Logger Encoding


```yaml
logger:
  encoding: json       # json or console
```

Level and output are controlled by CLI flags (`-v`, `-c`, `-s`); only `encoding` is read from YAML.



#### Log Manager


The log manager controls log propagation and event streaming:

```yaml
logmanager:
  propagate_downstream: true   # Propagate to child components
  stream_to_events: false      # Forward logs to event bus
  min_level: 0                 # -1=debug, 0=info, 1=warn, 2=error (wippy run sets 0, or -1 with -v)
```

When `stream_to_events` is enabled, log entries become events that processes can subscribe to via the event bus.

The embedded log-manager default is `-1`, but `wippy run` applies its CLI logging choice at startup: info (`0`) by default and debug (`-1`) with `-v` or `--very-verbose`.



#### Automatic Context


Logs emitted from Lua via the [logger module](lua/system/logger.md) automatically include:

- `pid` - Current process PID
- `location` - Entry ID and caller line (e.g., `app.api:handler:45`)



### Prometheus Metrics


```yaml
prometheus:
  enabled: true
  address: "localhost:9090"
```

Metrics are exposed at `/metrics` on the configured address; the same listener serves `/livez`. `max_cardinality` (default 1024) caps the number of live label sets per exporter; the least recently updated series are evicted beyond it.



#### Scrape Configuration


```yaml


## prometheus.yml

scrape_configs:
  - job_name: 'wippy'
    static_configs:
      - targets: ['localhost:9090']
    scrape_interval: 15s
```

For the Lua metrics API, see [Metrics Module](lua/system/metrics.md).



### OpenTelemetry


OpenTelemetry (OTEL) provides distributed tracing and optional metrics export.



#### Basic Configuration


```yaml
otel:
  enabled: true
  endpoint: "localhost:4318"
  protocol: http/protobuf      # grpc or http/protobuf
  service_name: my-app
  service_version: "1.0.0"
  insecure: true               # Use plaintext for a local collector
  sample_rate: 1.0             # 0.0 to 1.0
  traces_enabled: true
  metrics_enabled: false
  propagators:
    - tracecontext
    - baggage
```



#### Trace Sources


All trace sources are on by default once `otel.enabled` is true; each can be disabled individually:

```yaml
otel:
  enabled: true
  endpoint: "localhost:4318"
  service_name: my-app

  # HTTP request tracing
  http:
    enabled: true
    extract_headers: true      # Read incoming trace context
    inject_headers: true       # Write trace context to the HTTP response

  # Process lifecycle tracing
  process:
    enabled: true
    trace_lifecycle: true      # Trace spawn/exit events

  # Queue message tracing
  queue:
    enabled: true

  # Function call tracing
  interceptor:
    enabled: true
```

When OTEL is enabled, HTTP tracing and propagation, process tracing and lifecycle spans, function interception, queue tracing, and trace export are enabled by default. Temporal tracing and metric export default to disabled. The pinned runtime registers the function interceptor at order 100; although an `interceptor.order` value can be decoded from configuration, it does not change that registration order.



#### Temporal Workflows


Enable tracing for Temporal workflows:

```yaml
otel:
  enabled: true
  endpoint: "localhost:4318"
  service_name: my-app

  temporal:
    enabled: true
```

When enabled, the Temporal SDK's tracing interceptor is registered for both client and worker operations.

Traced operations include:

- Workflow starts and completions
- Activity executions
- Child workflow calls
- Signal and query handling



#### What Gets Traced


| Component | Span Name | Attributes |
|-----------|-----------|------------|
| HTTP requests | `{METHOD} {route}` | http.method, http.url, http.host, http.route |
| Function calls | Function ID | process.pid, frame.id |
| Process lifecycle | `{source}.started/terminated` | process.pid |
| Queue messages | `{queue}.publish` | messaging.operation, messaging.destination.name |
| Temporal workflows | Workflow/Activity name | workflow.id, run.id |



#### Context Propagation


The configured integrations propagate trace context through:

- **HTTP → Function**: W3C Trace Context headers
- **Function → Function**: Frame context inheritance
- **Process → Process**: Spawn context
- **Queue publish → consume**: Message headers



#### Environment Variables


OTEL can be configured via environment:

| Variable | Description |
|----------|-------------|
| `OTEL_SDK_DISABLED` | Set to `true` to disable OTEL |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Collector endpoint; an `http://` or `https://` scheme is removed before exporter setup |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | `grpc` or `http/protobuf` |
| `OTEL_EXPORTER_OTLP_INSECURE` | Set to `true` to use a plaintext collector connection |
| `OTEL_SERVICE_NAME` | Service name |
| `OTEL_SERVICE_VERSION` | Service version |
| `OTEL_TRACES_SAMPLER` | `always_on`, `always_off`, `traceidratio`, or `parentbased_traceidratio` |
| `OTEL_TRACES_SAMPLER_ARG` | Sample rate (0.0-1.0) |
| `OTEL_TRACES_SAMPLER` | `always_on`, `always_off`, `traceidratio`, or `parentbased_traceidratio` (ratio from `OTEL_TRACES_SAMPLER_ARG`) |
| `OTEL_EXPORTER_OTLP_INSECURE` | Set to `true` to allow non-TLS connections |
| `OTEL_PROPAGATORS` | Propagator list |



### Runtime Statistics


The `system` module provides internal runtime statistics:

```lua
local system = require("system")

-- Memory statistics
local mem, mem_err = system.memory.stats()
-- mem.alloc, mem.heap_alloc, mem.heap_objects, etc.

-- Goroutine count
local count, count_err = system.runtime.goroutines()

-- Supervisor states
local states, states_err = system.supervisor.states()
```

These functions return `value, error`. They require the `system.read` permission in the current security scope.



### See Also


- [Logger Module](lua/system/logger.md) — Lua logging API
- [Metrics Module](lua/system/metrics.md) — Lua metrics API
- [System Module](lua/system/system.md) — Runtime statistics



---

# "Queue Consumers"

## Queue Consumers


Queue consumers deliver messages from a queue to function handlers through a configurable worker pool.



### Overview


```mermaid
flowchart LR
    subgraph Consumer
        QD[Queue Driver] --> DC[Delivery Channel<br/>prefetch=10]
        DC --> WP[Worker Pool<br/>concurrency]
        WP --> FH[Function Handler]
        FH --> AN[Ack/Nack]
    end
```



### Configuration


| Option | Default | Max | Description |
|--------|---------|-----|-------------|
| `queue` | Required | - | Queue registry ID |
| `func` | Required | - | Handler function registry ID |
| `concurrency` | 1 | 1000 | Worker count |
| `prefetch` | 10 | 10000 | Message buffer size |
| `auto_ack` | false | - | Driver-level auto-ack (AMQP `Consume` autoAck; ignored by the memory driver) |
| `driver_options` | `{}` | - | Driver-specific consumer options |



### Entry Definition


```yaml
- name: order_consumer
  kind: queue.consumer
  queue: app:orders
  func: app:process_order
  concurrency: 5
  prefetch: 20
  lifecycle:
    auto_start: true
    requires:
      - app:orders
```



### Handler Function


The handler function receives the body after the queue's codec decodes it. Use `queue.message()` to access the current delivery and its metadata:

```lua
-- process_order.lua
local queue = require("queue")
local logger = require("logger")

local function main(order)
    local msg, msg_err = queue.message()
    if msg_err then
        return nil, msg_err
    end

    logger:info("processing order", {
        message_id = msg:id(),
        order_id = order.id
    })

    return {processed = true, order_id = order.id}
end

return {main = main}
```

```yaml
- name: process_order
  kind: function.lua
  source: file://process_order.lua
  method: main
  modules:
    - queue
    - logger
```



### Acknowledgment


Unless the handler explicitly settles the delivery, the consumer uses the function invocation result:

| Handler outcome | Action | Effect |
|-----------------|--------|--------|
| Completes without an invocation error | Ack | Message removed from queue |
| Returns or raises an invocation error | Nack | Redelivery is driver-dependent |

Ordinary return values, including `false`, do not select acknowledgment behavior. Call `msg:ack()` or `msg:nack()` to settle explicitly. Settlement is single-shot: the first settlement wins. With AMQP `auto_ack: true`, the broker acknowledges on delivery, so a later handler failure cannot cause broker redelivery.

The handler can settle the message itself with `queue.message()` and `msg:ack()` / `msg:nack()`; the consumer then skips its own ack/nack.



### Worker Pool


- Workers run as concurrent goroutines.
- Each worker processes one message at a time.
- Workers pull from a shared delivery channel. The next idle worker receives the next message, without guaranteed ordering or rotation across workers.
- The prefetch buffer allows the driver to deliver messages ahead of processing.



#### Example


```
concurrency: 3
prefetch: 10

Flow:
1. Driver delivers up to 10 messages to buffer
2. 3 workers pull from buffer concurrently
3. As workers finish, buffer refills
4. Backpressure when all workers busy and buffer full
```



### Graceful Shutdown


During shutdown, the consumer:

1. Stops accepting new deliveries
2. Cancels worker contexts
3. Waits for in-flight handlers, up to the stop timeout
4. Returns a timeout error if workers do not finish



### Queue Declaration


```yaml


## Queue driver (memory for dev/test)

- name: queue_driver
  kind: queue.driver.memory
  lifecycle:
    auto_start: true



## Queue definition

- name: orders
  kind: queue.queue
  driver: app:queue_driver
  queue_name: orders        # Override name (default: entry name)
  codec: json/plain         # Payload codec (optional; json/plain is the default)
  dead_letter:              # Accepted configuration; not enforced by built-in drivers
    queue: app:dlq
    max_attempts: 5
  driver_options:
    memory:
      max_length: 10000     # Memory driver: bounded queue size
```

| Field | Description |
|-------|-------------|
| `queue_name` | Override queue name (default: entry ID name) |
| `codec` | Payload codec name |
| `dead_letter.queue` | Registry ID accepted for a dead-letter queue; not enforced by built-in drivers |
| `dead_letter.max_attempts` | Attempt count accepted in configuration; not enforced by built-in drivers |
| `driver_options` | Driver-specific settings keyed by driver name |

<note>
No built-in driver currently counts attempts or routes messages from the `dead_letter` block. The runtime does not translate that block into AMQP queue arguments, and ordinary AMQP consumer failures request requeue. Broker-side dead-lettering must therefore be configured and triggered outside this block. The memory driver does not route to a DLQ.
</note>



### Memory Driver


The built-in in-memory driver is intended for development and testing:

- Its kind is `queue.driver.memory`.
- Messages are stored in memory.
- Nack attempts to re-enqueue a cloned message at the end of the queue; that attempt can fail when the bounded queue is full.
- Messages do not persist across restarts.



### See Also


- [Message Queue](lua/storage/queue.md) — Queue module reference
- [Queue Configuration](system/queue.md) — Queue drivers and entry definitions
- [Supervision](guides/supervision.md) — Consumer lifecycle
- [Process Management](lua/core/process.md) — Process spawning and communication



---

# "Supervision"

## Supervision


The supervisor manages service startup, dependency order, restarts, and graceful shutdown. Services with `auto_start: true` start when the application boots.



### Lifecycle Configuration


Services register with the supervisor using a `lifecycle` block. For processes, use `process.service` to wrap a process definition:

```yaml


## Process definition (the code)

- name: worker_process
  kind: process.lua
  source: file://worker.lua
  method: main



## Supervised service (wraps the process with lifecycle management)

- name: worker
  kind: process.service
  process: app:worker_process
  host: app:processes
  lifecycle:
    auto_start: true
    startup: required
    start_timeout: 30s
    stop_timeout: 10s
    stable_threshold: 5s
    requires:
      - app:database
    restart:
      initial_delay: 2s
      max_delay: 60s
      max_attempts: 10
```

`host` must reference a configured process host. The `requires` entry must resolve either to another supervised service or, through registry dependency extraction, to a supervised service that owns the referenced resource.

| Field | Default | Description |
|-------|---------|-------------|
| `auto_start` | `false` | Start automatically when supervisor starts |
| `startup` | `required` | Startup policy for an auto-start root: `required` blocks boot on failure; `optional` may fail and keep retrying without blocking independent branches |
| `start_timeout` | `10s` | Maximum time allowed for startup |
| `stop_timeout` | `10s` | Maximum time for graceful shutdown |
| `stable_threshold` | `5s` | Runtime after which a later failure resets the retry counter |
| `requires` | `[]` | Services that must be running first (legacy alias: `depends_on`) |
| `startup` | `required` | `required` reports a failed or blocked auto-start as a transaction error; `optional` lets the service keep retrying in the background without failing the batch |



### Dependency Resolution


The supervisor resolves dependencies from two sources:

1. **Explicit dependencies** declared in `requires` (or the legacy `depends_on`)
2. **Registry-extracted dependencies** from entry references (e.g., `database: app:db` in your config)

```mermaid
graph LR
    A[HTTP Server] --> B[Router]
    B --> C[Handler Function]
    C --> D[Database]
    C --> E[Cache]
```

Dependencies start before their dependents. If Service C depends on A and B, both dependencies must reach the `Running` state before C starts.

<tip>
You do not need to repeat an infrastructure reference in <code>requires</code> when registry dependency extraction can trace that reference to a supervised service. Use <code>requires</code> for lifecycle dependencies that are not already expressed by entry references.
</tip>



### Restart Policy


When a service fails, the supervisor retries according to its `restart` block:

```yaml
lifecycle:
  restart:
    initial_delay: 1s      # First retry wait
    max_delay: 90s         # Accepted backoff cap; see current behavior below
    backoff_factor: 2.0    # Accepted multiplier; see current behavior below
    jitter: 0.1            # ±10% randomization
    max_attempts: 0        # 0 = infinite retries
```

In runtime v0.3.32a, the supervisor constructs a new backoff calculator for each retry and takes only its first interval. Each retry therefore waits `initial_delay` with the configured jitter (0.9s–1.1s for the values above). `backoff_factor` and `max_delay` are accepted configuration fields but do not change this schedule in the pinned runtime.

`max_attempts` counts the initial failed start. A value of `1` permits no retry, and `10` permits at most nine follow-up starts. A value of `0` allows unlimited attempts.

When a service runs longer than `stable_threshold`, its retry counter resets, so later failures start from the initial retry delay.



#### Terminal Errors


These errors stop retry attempts:

- Context cancellation
- Explicit termination request
- Errors marked as non-retryable



### Security Context


Services can run with a specific security identity:

```yaml


## Process definition

- name: admin_worker_process
  kind: process.lua
  source: file://admin_worker.lua
  method: main



## Supervised service with security context

- name: admin_worker
  kind: process.service
  process: app:admin_worker_process
  host: app:processes
  lifecycle:
    auto_start: true
    security:
      actor:
        id: "service:admin-worker"
        meta:
          role: admin
      groups:
        - app:admin_policies
      policies:
        - app:data_access
```

The security context defines:

| Field | Description |
|-------|-------------|
| `actor.id` | Identity string for this service |
| `actor.meta` | Key-value metadata (role, permissions, etc.) |
| `groups` | Policy groups to apply |
| `policies` | Individual policies to apply |

Code running in the service inherits this security context. The `security` module can use it for permission checks:

```lua
local security = require("security")

if security.can("delete", "users") then
    -- allowed
end
```

<note>
When no security block is configured, the supervisor adds no service-specific actor or policy scope; any security values already present in the parent context remain inherited. In strict mode (default), a check with an incomplete resulting security context is denied. Configure a complete service security context for services that need authorization.
</note>



### Re-registration and Replacement


A registry change can re-register an ID that already has a running controller. If the registration carries the same service instance, nothing is disturbed. If it carries a **different** instance — the manager rebuilt the service because its configuration changed — the supervisor retires the existing controller and adopts the replacement.

Retirement covers more than the one service. A running dependent captured the superseded instance, so it cannot keep running against a service that is being replaced underneath it; the retirement closure is the replaced service plus every running service that depends on it, stopped in dependency order (dependents first). Services already stopped are not stopped a second time — a manager that stops its own instance before re-registering does not see a redundant `Stop`.

The handover is transactional:

1. The plan is computed without touching anything, so a planning failure leaves the running set intact.
2. The stop batch runs. **If any stop fails, the handover is rejected**: the services the batch already stopped are brought back up and the error is reported. A service that could not be brought back is named in that error. The supervisor ends up owning the same running set it had before the commit, never a half-retired one.
3. Only after the batch succeeds are the retired controllers dropped and canceled, freeing the superseded service instances.
4. The replacement is created and started through the same dependency-aware sequencer as any other start, and the dependents that were stopped for the handover come back up against the adopted instance.

A service that was running before the replacement is restarted afterwards even when the new registration sets `auto_start: false` — replacing an active service is an update, not an implicit stop. Restarting a stopped dependent is governed by its own restart policy and does not gate the commit.



### Service States


```mermaid
stateDiagram-v2
    [*] --> Unknown
    Unknown --> Starting
    Starting --> Running
    Running --> Stopping
    Stopping --> Stopped
    Stopping --> Failed : timeout/cancel
    Stopped --> [*]

    Running --> Failed
    Starting --> Failed
    Failed --> Starting : retry
    Running --> Exited
    Starting --> Exited
    Exited --> [*]
```

The supervisor transitions services through these states:

| State | Description |
|-------|-------------|
| `Unknown` | Registered but not started |
| `Starting` | Startup in progress |
| `Running` | Operating normally |
| `Stopping` | Graceful shutdown in progress |
| `Stopped` | Stop operation completed; service-reported stop details may still contain an error |
| `Exited` | Terminated by explicit request or a non-retryable/terminal error |
| `Failed` | Error occurred, may retry |



### Startup and Shutdown Order


**Startup:** Dependencies start before dependents. Services at the same dependency level can start in parallel.

**Shutdown:** Dependents stop before dependencies, allowing dependent services to finish first.

```
Startup:  database → cache → handler → http_server
Shutdown: http_server → handler → cache → database
```

On SIGINT or SIGTERM the runtime begins a graceful shutdown and the whole sequence runs under a single budget, `shutdown.timeout` in the runtime config (default 30s). That budget is a fresh deadline that does not inherit the interrupted context, so a Ctrl-C does not cut component shutdown short; per-service `stop_timeout` still bounds each individual stop within it. A second signal skips the sequence and exits immediately.

```yaml


## .wippy.yaml

shutdown:
  timeout: 60s
```



### See Also


- [Process Model](concepts/process-model.md) — Process lifecycle
- [Configuration](guides/configuration.md) — YAML configuration format
- [Security Module](lua/security/security.md) — Permission checks in Lua



---

# "Publishing Modules"

## Publishing Modules


Publishing packages a module and makes a version or mutable label available through the Wippy Hub.

This is a publishing workflow and reference. The `acme/*` modules, URLs, tokens,
credentials, and example source are illustrative; replace them with resources owned
by your organization.



### Prerequisites


1. Create an account on [hub.wippy.ai](https://hub.wippy.ai)
2. Create an organization or join one
3. Have permission to create modules in that organization — the first `wippy publish` registers the module automatically



### Module Structure


```
mymodule/
├── wippy.yaml      # Module manifest
├── src/
│   ├── _index.yaml # Entry definitions
│   └── *.lua       # Source files
└── README.md       # Documentation (optional)
```



### wippy.yaml


Define module metadata in `wippy.yaml`:

```yaml
organization: acme
module: http-utils
type: library
description: HTTP utilities and helpers
license: MIT
repository: https://github.com/acme/http-utils
homepage: https://acme.dev
keywords:
  - http
  - utilities
authors:
  - Acme Engineering <eng@acme.dev>
embed:
  - acme.http:assets
exclude:
  - test/**
  - "*.test.lua"
  - acme.http:debug_handler
exclude_meta:
  stage:
    - experimental
metadata:
  support_url: https://acme.dev/support
```

| Field | Required | Description |
|-------|----------|-------------|
| `organization` | Yes | Organization name on the Hub |
| `module` | Yes | Module name |
| `type` | No | Module type: `library`, `application`, `agent`, or `plugin` |
| `description` | No | Short description |
| `license` | No | SPDX identifier (MIT, Apache-2.0) |
| `repository` | No | Source repository URL |
| `homepage` | No | Project homepage |
| `keywords` | No | Search keywords |
| `authors` | No | Author list |
| `version` | No | Semantic version; `--version` overrides it |
| `exclude` | No | Patterns to drop: values containing `:` are entry IDs, everything else is a source-file glob |
| `embed` | No | Default `fs.directory` embed patterns when `--embed` is not passed |
| `exclude_meta` | No | Metadata field to values map; entries whose metadata matches are dropped |
| `metadata` | No | Arbitrary key/value metadata carried with the published module |
| `publish.profiles` | No | Which config profiles to ship in the pack (see [Publishing Profiles](#publishing-profiles)) |
| `publish.runtime` | No | Which runtime config sections to ship as pack defaults; `type: application` only |

`exclude` splits by shape rather than by a separate field. `_old/**`, `test/**` and `*.test.lua` filter source files as they are collected; `acme.http:debug_handler` disables a registry entry after entries are decoded. A `**` segment spans any number of directory segments.

`type` controls how the Hub classifies the module and can be changed in a later publish. The `--module-type` flag overrides it for one publish. When omitted, a newly created module defaults to `application` with a deprecation warning.



### Entry Definitions


Define the module's entries in `_index.yaml`:

```yaml
version: "1.0"
namespace: acme.http

entries:
  - name: definition
    kind: ns.definition
    meta:
      title: HTTP Utilities
      description: Helpers for HTTP operations
    readme: file://README.md
    wiki:
      GUIDE.md: file://docs/GUIDE.md
      examples/auth.md: file://docs/auth.md

  - name: client
    kind: library.lua
    source: file://client.lua
    modules:
      - http_client
      - json
```

The `wiki:` map on `ns.definition` publishes documentation pages alongside the README. Keys are page paths, and values are `file://` references. Contents are inlined during packing and served by the Hub as a module wiki.



### Dependencies


Declare dependencies on other modules:

```yaml
entries:
  - name: __dependency.wippy.test
    kind: ns.dependency
    meta:
      description: Testing framework
    component: wippy/test
    version: ">=0.3.0"
```

Version constraints:

| Constraint | Meaning |
|------------|---------|
| `*` | Any version |
| `1.0.0` | Exact version |
| `>=1.0.0` | Minimum version |
| `^1.0.0` | Compatible (same major) |



### Requirements


Define configuration that consumers must provide:

```yaml
entries:
  - name: api_endpoint
    kind: ns.requirement
    meta:
      description: API endpoint URL
    targets:
      - entry: acme.http:client
        path: ".meta.endpoint"
    default: "https://api.example.com"
```

Targets specify where the value is injected:

- `entry` — Full entry ID to configure
- `path` — Dot path into the target entry for value injection

`default` accepts any scalar type — `default: 20` flows into a numeric target as a number, not a string. The same applies to `parameters[].value` on `ns.dependency` entries, and both accept `${env:NAME}` references, carried verbatim and resolved when the target entry is decoded.

Consumers can configure the target through an override. The `-o` flag accepts a `namespace:entry:field=value` value:

```bash
wippy run -o acme.http:client:meta.endpoint=https://custom.api.com
```



### Imports


Reference other entries:

```yaml
- name: handler
  kind: function.lua
  source: file://handler.lua
  modules:
    - json
  imports:
    client: acme.http:client           # Same namespace
    utils: acme.utils:helpers          # Different namespace
    base_registry: :registry           # Built-in
```

In Lua:

```lua
local client = require("client")
local utils = require("utils")
```



### Contracts


Define public interfaces:

```yaml
- name: http_contract
  kind: contract.definition
  meta:
    name: HTTP Client Contract
  methods:
    - name: get
      description: Perform GET request
    - name: post
      description: Perform POST request

- name: http_contract_binding
  kind: contract.binding
  contracts:
    - contract: acme.http:http_contract
      methods:
        get: acme.http:get_handler
        post: acme.http:post_handler
```



#### 1. Authenticate


```bash
wippy auth login
```



#### 2. Prepare


```bash
wippy init
wippy update
wippy lint
```



#### 3. Validate


```bash
wippy publish --dry-run
```

Publish builds the pack the same way with or without `--dry-run`, so validation covers everything the real publish would produce:

- `organization` and `module` must be lowercase alphanumeric with interior hyphens, `version` must be semver, and `type` must be one of the four module types.
- `publish.runtime` is application-owned: declaring `source`, `sections`, or `vars` under it without `type: application` fails.
- Every resource declaring `meta.artifact.format` is inspected by that format. A malformed artifact fails here rather than in a consumer, and two artifacts whose outputs would land in overlapping directories are rejected.
- The `node-package` format additionally requires `package.json` to carry a semantic `version` that **equals the module version being published**, a valid package `name`, and no `preinstall`, `install`, `postinstall`, or `prepare` lifecycle script.

The last rule is the one that bites during a release: bump `version` in `wippy.yaml` and in the artifact's `package.json` together, or the publish stops.



#### 4. Publish


```bash
wippy publish --version 1.0.0
```

With release notes:

```bash
wippy publish --version 1.0.0 --release-notes "Initial release"
```



#### Publish Flags


| Flag | Description |
|------|-------------|
| `--label <name>` | Publish as a mutable label (e.g. `latest`, `beta`) instead of an immutable version |
| `--protected` | Mark the published version as protected (cannot be deleted or overwritten) |
| `--registry <url>` | Override the registry URL for this publish |
| `--config <dir>` | Directory containing `wippy.yaml` (default: current dir) |
| `--create` | Register the module on the hub if it does not exist yet, then publish |
| `--module-visibility <v>` | Visibility for `--create`: `private` (default) or `public` |
| `--module-type <t>` | Module type: `library`, `application`, `agent`, or `plugin` (overrides `type:` in wippy.yaml) |
| `--module-display-name <n>` | Display name for `--create` |



#### Embed Static Files


Modules with `fs.directory` entries (static assets, templates, public files) must use `--embed` to include them in the published package. Without it, an `fs.directory` entry is packed without its directory contents.

```bash
wippy publish --version 1.0.0 --embed app:public_files
wippy publish --version 1.0.0 --embed app:assets,app:templates
```

The manifest list and `--embed` flag accept entry IDs or names matching
`fs.directory` entries. The same CLI flag is available on `wippy pack`; a CLI
selection overrides the manifest list for that invocation.



#### First Publish


On its first publish, a module is registered on the Hub as private by default, and the publish retries once. Use `--create` to register it before publishing and set its properties:

```bash
wippy publish --create --version 0.1.0 \
  --module-visibility public \
  --module-type library \
  --module-display-name "HTTP Utils"
```

`--create` is idempotent — for an already-registered module the create step is a no-op. If your account cannot create modules in the organization, the hub returns a permission error instead of publishing.



#### Publishing to a Local Hub


Point `--registry` at a locally running Hub to publish and install without using the public registry. Plain HTTP is allowed only for local hosts: `localhost`, `127.0.0.1`, and the container aliases `host.docker.internal` (Docker Desktop or OrbStack) and `host.containers.internal` (Podman). Other hosts must use HTTPS.

```bash
wippy auth login --registry http://localhost:8080 --token wpy_xxx
wippy publish --registry http://localhost:8080 --create --version 0.1.0
```

The registry and token can also come from the `WIPPY_REGISTRY` and `WIPPY_TOKEN` environment variables. When unset, the registry defaults to `https://hub.wippy.ai`.



#### Quotas


If the organization's private-module quota is exhausted, publishing fails with a message such as `cannot publish: Private-module quota exhausted (5 of 5)...`. Make the module public or ask an organization administrator to raise the quota. Uploads and downloads retry automatically after transient network errors.



### Publishing Runtime Defaults


Applications with `type: application` can include runtime configuration defaults in their packs through `publish.runtime` in `wippy.yaml`:

```yaml
type: application
publish:
  runtime:
    source: .wippy.yaml            # default: .wippy.yaml
    sections: [security, registry, override]
    vars: [public_url]
```

| Field | Description |
|-------|-------------|
| `source` | Config file the sections are read from (default: `.wippy.yaml`) |
| `sections` | Runtime config sections copied into pack metadata as defaults |
| `vars` | Explicit allowlist of variables to pack even when unreferenced |

Rules:

- Only variables referenced by the selected sections or published profiles are packed (followed transitively); everything else needs a `vars` entry.
- `${env:...}` references in exported config are rejected — publisher environment never leaks into a pack.
- The machine-local sections `boot`, `extensions`, and `workspace` cannot be exported.
- Only the main application pack provides host runtime defaults; runtime metadata in dependency packs is ignored.

At the destination, configuration precedence runs from application-pack defaults through runtime defaults, local configuration files, selected profiles, and finally CLI overrides.



### Publishing Profiles


Root application profiles are exported into the pack's `runtime.profiles` metadata. Publishing does not select or bake a profile — consumers pick one at run time with `wippy run --profile <name>`:

```yaml
publish:
  profiles:
    enabled: true
    source: config/profiles.yaml   # default: .wippy.yaml
    include: [production]          # omit to publish all non-workspace profiles
```

`include: []` publishes none; an unknown name fails the publish. `workspace` sub-sections are never exported, even inside a published profile. See [Configuration](guides/configuration.md#profiles) for declaring profiles.



#### Add Dependency


```bash
wippy add acme/http-utils
wippy add acme/http-utils@1.0.0
wippy install
```



#### Configure Requirements


Override values at runtime:

```bash
wippy run -o acme.http:client:meta.endpoint=https://my.api.com
```

Or in `.wippy.yaml`:

```yaml
override:
  acme.http:client:meta.endpoint: "https://my.api.com"
```



#### Import in Your Code


```yaml


## your src/_index.yaml

entries:
  - name: __dependency.acme.http
    kind: ns.dependency
    component: acme/http-utils
    version: ">=1.0.0"

  - name: my_handler
    kind: function.lua
    source: file://handler.lua
    imports:
      http: acme.http:client
```



### Example Module


**wippy.yaml:**
```yaml
organization: acme
module: cache
type: library
description: In-memory caching with TTL
license: MIT
keywords:
  - cache
  - memory
```

**src/_index.yaml:**
```yaml
version: "1.0"
namespace: acme.cache

entries:
  - name: definition
    kind: ns.definition
    meta:
      title: Cache Module

  - name: cache
    kind: library.lua
    source: file://cache.lua
    modules:
      - time
```

**src/cache.lua:**
```lua
local time = require("time")

local cache = {}
local store = {}

function cache.set(key, value, ttl)
    store[key] = {
        value = value,
        expires = ttl and (time.now():unix() + ttl) or nil
    }
end

function cache.get(key)
    local entry = store[key]
    if not entry then return nil end
    if entry.expires and time.now():unix() > entry.expires then
        store[key] = nil
        return nil
    end
    return entry.value
end

return cache
```

Publish:

```bash
wippy init
wippy update
wippy lint
wippy publish --version 1.0.0
```



### See Also


- [CLI Reference](guides/cli.md) — Publishing commands and flags
- [Entry Kinds](guides/entry-kinds.md) — Module and dependency entries
- [Configuration](guides/configuration.md) — Runtime configuration and profiles



---

# "Compute Units"

## Compute Units


Wippy provides three ways to run code: functions, processes, and workflows. They share the same underlying machinery but differ in how long they live, where their state goes, and what happens when things fail.



### Functions


Functions run when called and return a result. Treat each call as stateless:
durable or shared state belongs in a database or store. Function pools can
reuse Lua states, so module globals and closure upvalues are worker-local and
are not a reliable cross-call store.

```lua
local funcs = require("funcs")

local result, err = funcs.call("app.math:add", 2, 3)
if err then
    return nil, err
end
```

Functions execute in the caller's context. If the caller is canceled or exits, its running function calls are canceled as well.

<tip>
Use functions for HTTP handlers, data transformations, and anything that should complete quickly and return a result.
</tip>



### Processes


Processes are actors. They maintain state across multiple messages, run independently of whoever started them, and communicate through message passing.

```lua
local pid, err = process.spawn("app.workers:handler", "app:processes")
if err then return nil, err end

local ok, send_err = process.send(pid, "job", {task = "process_data"})
if send_err then return nil, send_err end
return ok
```

After being spawned, a process runs independently of the code that created it. Processes can monitor or link to one another and can participate in supervision trees that restart failed children.

The scheduler multiplexes thousands of processes across a worker pool. Each process yields when waiting for I/O, letting others run.

<tip>
Use processes for background jobs, service daemons, and anything that needs to outlive its creator or maintain state across messages.
</tip>



### Workflows


Workflows are for durable operations that must recover from interruptions. A
workflow provider such as Temporal records execution history and replays it to
rebuild state after crashes, restarts, or infrastructure changes.

```lua
-- The provider records this workflow so a worker restart can replay it.
local pid, err = process.spawn("app.orders:process", "app:temporal_worker", order_id)
if err then return nil, err end
return pid
```

Durability adds latency because workflow operations are recorded. Use workflows when recovery is more important than the lower latency of functions or processes, such as for multi-step business processes and long-running orchestration.

<note>
Wippy records supported workflow operations so they produce the same results during replay. Workflow code uses the same Lua syntax as other compute units.
</note>



### How They Compare


| | Functions | Processes | Workflows |
|---|---|---|---|
| **State** | Call-local; do not depend on worker reuse | In memory | Rebuilt from persisted history |
| **Lifetime** | Single call | Until exit or crash | Persists across restarts |
| **Communication** | Return value + messages | Message passing | Activity calls + messages |
| **Failure handling** | Caller handles | Supervision trees | Provider recovery; retries follow policy |
| **Latency** | Lowest | Low | Higher |



### Same Code, Different Behavior


Many modules adapt to their context automatically. For example, `time.sleep()`
yields in both functions and processes so other work can run; in a workflow,
the provider also records the timer so replay does not start a second timer.



---

# "Application Architecture"

## Application Architecture


A Wippy application is a **graph of registry entries** represented by source files. Code lives in entries such as `function.lua` and `process.lua`; `_index.yaml` files declare how functions, routes, services, and libraries connect. Application structure determines how that graph is divided into namespaces so it remains composable, testable, and bootable as it grows.

This page explains one way to organize that graph. For file format, naming, and `_index.yaml` placement, see [YAML & Project Structure](start/structure.md). For entry definitions, see the [Entry Kinds Guide](guides/entry-kinds.md).



### Feature Slices


A useful default is to organize by **feature** rather than file type. A slice owns one capability end to end—its database access, long-running processes, HTTP surface, and shared vocabulary—and lives under one namespace prefix:

```
src/app/jobs/          namespace: app.jobs
src/app/auth/          namespace: app.auth
src/app/billing/       namespace: app.billing
```

Feature slices keep related behavior within one folder, making a capability easier to read, test, change, or remove without tracing it across top-level `handlers/`, `models/`, and `services/` directories.



### Layers within a slice


For larger slices, separate code by **what touches the outside world**. This applies ports-and-adapters (hexagonal) architecture through **sub-namespaces**:

```
src/app/jobs/                  namespace: app.jobs          ← shared vocabulary
  consts.lua  config.lua  types.lua
  persist/                     namespace: app.jobs.persist  ← database adapters (sql)
  service/                     namespace: app.jobs.service  ← processes, workers
  api/                         namespace: app.jobs.api      ← http.endpoints
```

Keep imports flowing from outer layers toward inner layers:

```
api  →  service  →  persist  →  { consts, config, types }
```

The slice root contains shared vocabulary and does not import its own children. Children may import the root. Avoid direct imports between slices; place shared definitions in a common parent namespace such as `app.core:types`.

<note>
Namespaces organize entry IDs but do not create dependencies or injection seams by themselves. Explicit <code>imports</code>, kind-specific references, and <code>ns.requirement</code> targets create those relationships. A consistent direction keeps the resulting graph explicit. See <a href="#why-this-shape">Why this shape</a>.
</note>

A small slice can use one `_index.yaml` for its libraries and endpoint. The important property is the **import direction**, not the number of folders.



### Shared Vocabulary


Three files commonly appear at the root of a slice. They contain definitions shared by the slice's layers:

| File | Holds | Capabilities |
|------|-------|--------------|
| `consts.lua` | State machines, enums, queue tiers, registry IDs of processes. The values that mirror your database `CHECK` constraints. | none |
| `config.lua` | Env-tunable knobs with a helper that applies a code default only when `env.get(KEY)` returns `errors.NOT_FOUND` and propagates permission or backend errors. No `env.variable` entry is required for a value to be optional. | `env` |
| `types.lua` | Entity shapes (`type Job = { ... }`) — the rows the persistence layer returns. | none |

`consts` and `types` declare **no host capabilities**; they are pure `library.lua` entries that return a table. Keeping domain vocabulary free of I/O also makes it testable without a database or process host.

Keep this vocabulary **slice-private**. Place constants and types shared across slices in a common parent namespace and import them rather than copying them.



### Capabilities by Layer


Lua entries declare non-ambient modules in `modules:` and registry-backed dependencies in `imports:`. A layered slice can keep those dependencies aligned with responsibility:

- `persist/*` declares `sql`, keeping database access in the persistence layer.
- `service/*` keeps process orchestration and service dependencies in the service layer. The `process` and `channel` globals are ambient and do not need `modules:` declarations.
- `api/*` declares modules such as `http` and imports the functions or libraries it calls.
- The root vocabulary needs no non-ambient modules or infrastructure imports.

This limits module visibility to a known layer. It is not an authorization grant: ABAC policies independently decide whether guarded operations such as `db.get` are allowed at runtime. To review code that can request a database handle, inspect `persist/`, its declared modules, and the policies attached to its execution context.



### Applications and Components


The same shape can support a single application or a published library; the difference is **who supplies its dependencies**.

An **application** is the top-level, deployable graph. It owns the concrete infrastructure — the `http.service`, the `process.host`, the database connection — under a root namespace (conventionally `app`), and wires everything together itself.

A **component** is a publishable module mounted into a host. Because it does not know the host's database or router IDs, it declares an interface of `ns.requirement` entries that the host supplies. Internally, a component can use the same layers, vocabulary, and import direction as an application slice.

These are two points on a spectrum:

- **Single app, internal slices** — slices live under `src/app/`, share the app's infrastructure directly by referencing `app:db`, `app:processes`. No requirement interface is needed because nothing external mounts them.
- **Multi-component composition** — each component is its own publishable module with an `ns.definition` and an `ns.requirement` interface, composed by a host through `ns.dependency`. The host fills each requirement (database, process host, router) once.

Choose based on whether the slice will be **consumed by a host you do not control**. Reusable components need a requirement interface; internal slices can reference application infrastructure directly. The packaging changes with reuse, while the internal layering can remain the same.

See [Building Components](guides/components.md) for the requirement/dependency mechanism, and [Dependency Management](guides/dependency-management.md) for the lock-file side.



### Why Use This Shape :id=why-this-shape


This structure supports composition, capability review, and boot-order analysis:

**Requirement targets are the injection seam.** Distinct namespaces make target IDs legible, but `ns.requirement.targets` performs the injection. A host can supply a database ID to persistence entries and a process-host ID to service entries. Directly referencing `app:db` instead couples the component to that host convention.

**One-way references keep registry transitions resolvable.** The registry extracts declared dependency paths and topologically orders changes so dependencies are created before their dependents and deleted after them. The direction `api → service → persist → root` helps keep that graph acyclic. A parent namespace is only an organizational convention; the shared entries still need explicit references.

**Modules scoped by layer have a clear boundary.** Each Lua chunk can resolve its declared imports and non-ambient modules; undeclared registry modules fail closed at module resolution. Runtime policy checks remain a separate boundary. When persistence entries alone declare `sql`, the code that can request a database handle is easier to identify and audit.

**The layering supports different test scopes.** Vocabulary can be tested without infrastructure. Persistence tests can use a database without starting workers. A whole-module **mount test** then checks the integration seams: every supervised service points to a process, every spawned ID resolves, and every requirement is filled.



### See Also


- [YAML & Project Structure](start/structure.md) — file format, naming, namespaces
- [Building Components](guides/components.md) — `ns.definition`, `ns.requirement`, mounting
- [Dependency Management](guides/dependency-management.md) — lock files, consuming modules
- [Registry](concepts/registry.md) — how entries are stored and resolved
- [Entry Kinds Guide](guides/entry-kinds.md) — every entry kind
- [Process Model](concepts/process-model.md) — services, supervision, hosts



---

# "Registry"

## Registry


The registry is Wippy's versioned store for entry points, services, resources, and other runtime definitions. Most runtime entry kinds are reconciled through event-bus transactions; internal kinds such as `registry.entry` and namespace metadata bypass event dispatch by default.



### Entries


The registry holds **entries**—typed definitions with unique IDs:

```
app.api:get_user          → HTTP handler
app.workers:email_sender  → Background process
app:database              → Database connection
app:templates             → Template set
```

Each entry has an `ID` (namespace:name format), a `kind` that determines its handler, arbitrary `meta` fields, and kind-specific `data`.

Alongside that authored content the registry keeps its own provenance for each entry: the `owner`, meaning the deployment source the entry came from, and `root`, marking a dependency declaration the deployment selected. This state is assigned by the registry, not written by the entry author, and it is kept separate from `meta` so the two can never be confused. It is read through the snapshot state API rather than the ordinary entry APIs—see [Registry module](lua/core/registry.md#snapshot-state).

For how the registry functions as an authorization layer, see the [Security Model](concepts/security-model.md).



### Kind Handlers


When a dispatched entry is submitted, its `kind` selects the registered handler. The handler validates and reconciles the corresponding runtime resource: an `http.service` entry manages an HTTP server, a `function.lua` entry manages a function pool, and a `db.sql.postgres` entry manages a connection pool. See the [Entry Kinds Guide](guides/entry-kinds.md) for available kinds and [Custom Entry Kinds](internals/kinds.md) for handler implementation.



### Live Updates


Entries can be added, updated, or removed while the system runs. For dispatched kinds, a registry transaction asks participating handlers to accept or reject each operation before commit. A rejection discards the transaction and applies the inverse transition. Related topology changes produce one new registry version.

Version history supports backward and forward transitions when history is enabled. Memory history is the default and lasts for the process lifetime; SQLite and PostgreSQL backends persist history across restarts.

YAML and JSON definition files are source manifests that the boot loader converts into entries. They are not serialized registry snapshots. See [Registry module](lua/core/registry.md) for programmatic access.



### See Also


- [YAML & Project Structure](start/structure.md) — Definition files
- [Custom Entry Kinds](internals/kinds.md) — Implement kind handlers
- [Process Model](concepts/process-model.md) — Understand process execution



---

# Security Model - Process Isolation, Capability Control, and Data Boundaries

## Security Model


Wippy's security model defines what your code can access, what it cannot, and who enforces those boundaries. It is worth reading before you build, because it works at two layers that most frameworks collapse into one: the runtime isolates each process so dangerous capabilities are simply absent, and an attribute-based policy layer governs which registry capabilities a process is allowed to use. Understanding both changes how you structure an application.



### Trust Model


Wippy's isolation layer gives a process no ambient authority. A fresh Lua or WASM process cannot touch the file system, the network, the host OS, or other processes' memory, because those capabilities are not present in its environment. Capabilities arrive only through the registry: functions, tools, connections, and configuration the process is explicitly granted.

On top of that, access to registry capabilities is governed by attribute-based access control (ABAC). Every guarded operation is checked against the current actor's security scope, a set of policies that allow or deny an action on a resource, optionally conditioned on actor and resource metadata. This is declarative: you define policies in configuration, not in application code.

When a process runs with both an actor and a scope, access is deny-by-default: a request is allowed only if a policy explicitly permits it and none denies it. **Strict mode** governs the incomplete case, when no actor or scope is established. It is **on by default**, so an incomplete context is denied; setting `security.strict_mode: false` in the runtime config opts into the permissive behavior instead. The consequence to plan for is that a process with no declared security context fails every check under the default — give such a process a `security:` block on its entry, or start it through a path that supplies one. Combined with least-privilege policies, this gives you fail-closed authorization on top of deny-by-absence isolation. See the [Security reference](system/security.md) for policy syntax, evaluation rules, and the shape of the `security:` block.



### Process Isolation


Every unit of execution in Wippy runs in an isolated process with its own embedded interpreter (Lua or WASM).

**What a process has:** its own memory space (a baseline overhead of ~13 KB for Lua). A scoped view of the registry. An actor identity and a security scope. A supervised lifecycle with crash recovery and restart limits.

**What a process does not have:** access to the file system (except through registry-controlled filesystem entries). Access to the network (except through granted HTTP client or tool modules). Access to other processes' memory. Access to the Go runtime hosting it. Access to environment variables (except through granted environment entries).

**How isolation is enforced:** each Lua process starts from a minimal standard library. File I/O, OS process access, dynamic code loading, and networking are never loaded, so they are not present in the environment, and the process cannot restore what does not exist. Module loading is restricted: `require` resolves only the modules and registry entries the process is explicitly granted, with no file system search path. WASM processes achieve equivalent isolation through WASI: only the host functions and mounted filesystem entries configured for that entry are reachable.

This is not sandboxing via runtime permissions (like seccomp or AppArmor). It is sandboxing via absence. Dangerous capabilities are never loaded, so they cannot be exploited, bypassed, or escalated.



### Capability Control


The registry is Wippy's capability store, and security policies are its authorization layer.

**Every capability is a registry entry.** Functions, tools, agent definitions, database connections, environment references, configuration values, and scheduled tasks are all registry entries with a declared kind, schema, and metadata. Entries are validated by their kind handler when registered.

**Entry IDs are namespaced.** An ID has the form `namespace:name` with a single colon, and namespaces are hierarchical via dot-separated segments, for example `tenant_acme.tools:read` (namespace `tenant_acme.tools`, name `read`). Policies match actions and resources, and resource patterns can target a namespace prefix, so a single rule can cover an entire namespace.

**Policies decide access.** Each capability access (a registry lookup, a function call, a database handle, a file open) is checked against the actor's scope. A policy declares the actions and resources it covers, an allow or deny effect, and optional conditions on actor and resource metadata. Evaluation happens per access, not once at startup: if any policy denies, access is denied; if at least one allows and none denies, it is allowed; if no policy matches, access is denied. (When the context has no actor or scope at all, that incomplete case is resolved by strict mode rather than by policy evaluation.)

**A context is declared, not inherited from thin air.** Functions inherit the caller's actor and scope. A spawned process inherits them too: its frame is forked from the spawner's, and the `security:` block on its own entry then modifies that inherited context — an `actor` it names replaces the inherited actor, and the policies and policy groups it lists by registry ID are merged into the inherited scope. Resolution is atomic — if any named policy or group is missing, the spawn fails rather than proceeding with a partial scope. A CLI command can additionally declare `meta.command.security`, applied only on the trusted launch path where the operator started the command themselves.

**Tool arguments are schema-shaped.** A tool declares a JSON Schema for its inputs. That schema is given to the model so it generates conforming arguments, and access to the tool is policy-checked before the call runs.



### Data Boundaries


**Database connections are registry entries.** A process does not assemble its own connection string. It requests a connection by registry ID, and that request is policy-checked before a handle is returned. A process whose policies do not grant Tenant B's database entry cannot obtain a handle to it.

**LLM API keys live in the environment system.** Keys for Claude, GPT, and other providers are read from the environment system (for example OS environment variables exposed through an `env.storage.os` entry, referenced by `env.variable` entries whose reads are policy-checked via the `env.get` action). The provider reads them internally; they are not passed in process arguments or returned to calling code.

**File and blob storage follow the same model.** A process reads or writes through filesystem or cloud-storage registry entries, each access policy-checked. WASM processes access files only through filesystem entries explicitly mounted for that entry.



### Agent Security


Agents are LLM-powered processes with tool use. They make decisions at runtime that your code does not directly control, so their boundaries matter. Wippy handles this through the same registry and policy mechanisms as any other process.

**Tool access.** An agent can only invoke tools listed in its definition, and each tool execution runs through `funcs.call`, which is policy-checked. A denied call fails before the tool function runs. An agent designed to read customer data but not delete it either has no delete tool in its definition or is denied that action by policy.

**External and MCP tools.** Wippy can consume external tools and expose its own over the Model Context Protocol. Consumed tools run through the same function-call path and policy checks as native tools. Tools Wippy exposes to external MCP clients are gated by scoped, revocable access tokens that limit which actions a client may perform.

**Structured output.** The LLM module can request schema-constrained (structured) output using the provider's native structured-output support, so an agent's output can be held to a declared shape.

**Observability.** With OpenTelemetry enabled, LLM provider calls and tool invocations are traced, and token usage is recorded through the usage-tracker contract. This gives you an audit trail of what an agent called and what it spent. See [Observability](guides/observability.md).

**Self-modification boundaries.** An agent permitted to create tools in one namespace can be denied write access to its own definition in another. Registry writes are policy-checked actions, so a deny policy on the agent's own namespace prevents it from editing itself or granting itself new access.



### Multi-Tenant Enforcement


For deployments where multiple customers share a single Wippy instance, isolation is enforced by policy evaluation before any operation runs, not by application code checking tenant IDs.

**Tenant isolation is policy-enforced.** Give each tenant an actor and a scope whose policies cover only that tenant's namespaces. With strict mode on, a tenant's process is denied access to resources outside its scope before its code runs. Effective isolation depends on writing those per-tenant policies; the runtime enforces them, but it does not infer tenancy for you.

**Cross-tenant access is explicit.** A capability shared across tenants lives in a shared namespace that each tenant's policies allow. Sharing is opt-in per namespace.

**Concurrency is bounded at the host.** Process hosts bound concurrency through worker pools. Process groups (`pg.scope`) provide isolated, cluster-wide membership and broadcast namespaces and can cap group and member counts. Per-tenant CPU or memory ceilings are not a built-in runtime feature; enforce those at the infrastructure layer.

A dedicated Multi-Tenant Architecture guide is planned.



### Scope and Limitations


Wippy's security model covers process isolation, capability control, and data boundaries. The following are outside the runtime's scope and remain your infrastructure's responsibility.

**Data encryption at rest.** Database, disk, and blob-storage encryption are handled by the underlying infrastructure (PostgreSQL TDE, disk encryption, and similar). Wippy assumes the storage layer handles encryption.

**Network-level isolation.** Process isolation happens at the application layer. Network segmentation between Wippy and its dependencies (database, LLM APIs, external services) is handled by infrastructure: VPCs, security groups, firewalls.

**Identity management.** Authentication (verifying who a user is) is handled by your auth layer. Wippy's security model starts after authentication: it controls what an authenticated user's processes can do, not who the user is. Tokens that carry an actor and scope can be issued and validated through a token store.

**Infrastructure audit logs.** Wippy's tracing covers process-level operations: function calls, tool calls, process activity. Infrastructure-level access (SSH to the server, database admin operations) should be audited by infrastructure tools.



### Common Questions


**Can one tenant's agent access another tenant's data?**
Not when each tenant's resources are scoped by policy. With per-tenant policies and strict mode, the runtime denies access to resources outside the tenant's scope before the agent's code runs.

**Can an agent escalate its own permissions?**
Only if its policies allow writing to its own definition. Registry writes are policy-checked, so a deny policy on the agent's own namespace prevents self-modification. An agent that can create tools in one namespace cannot grant itself access to namespaces its scope does not already cover.

**How do I see what an agent did?**
With OpenTelemetry enabled, LLM and tool calls are traced, and token usage is recorded through the usage-tracker contract. See [Observability](guides/observability.md).

**What happens if an agent behaves unexpectedly?**
It is contained by the sandbox: no file system, no network, no OS, no access to other processes beyond what it was granted. It can only call tools in its definition that policy permits, and those calls are logged.

**Is tenant isolation enforced by my code or by the runtime?**
By the runtime. The policy engine evaluates each access before the operation runs. Your job is to write the per-tenant policies; the runtime enforces them.

**How are external MCP tools secured?**
Tools consumed over MCP run through the same function-call path and policy checks as native tools. Tools Wippy exposes to external MCP clients are gated by scoped, revocable access tokens. Connecting an MCP service does not bypass the security model.



### Security Reference


| Concern | Wippy's approach |
|---------|------------------|
| Process isolation | Separate interpreter per process (Lua or WASM), no shared memory |
| Default access | Unmatched policies deny when both an actor and a scope are set; strict mode, on by default, denies when no actor or scope is established |
| Context declaration | `security:` block on the entry (actor, policies, groups); resolution is atomic and fail-closed |
| Supply chain | Module packs verified by digest at install and at boot; a mismatch refuses the module |
| Node-to-node trust | Mutually authenticated internode mesh; ed25519 identity per node, explicit trusted-peer map |
| Workflow propagation | Actor and scope carried to Temporal as a signed, audience-bound header; verification failure fails the execution |
| Capability control | Registry entries governed by attribute-based security policies (actor, scope, action, resource) |
| Data boundaries | Connections and storage are registry entries; each access is policy-checked by entry ID |
| API key management | Stored in the environment system, read internally by providers, not exposed to process code |
| Agent tool control | Tools limited to the agent's definition; each call checked via `funcs.call` policy |
| External tools (MCP) | Same function-call path and policy checks; exposed tools gated by scoped tokens |
| Agent audit trail | OpenTelemetry tracing (when enabled) plus usage-tracker records |
| Multi-tenant isolation | Per-tenant policies and scopes evaluated by the runtime before each operation |
| Concurrency limits | Bounded by host worker pools; no per-tenant CPU/memory ceilings built in |
| Self-modification | Deny policies on registry-write actions prevent agents from editing their own definitions |



### See Also


- [Security reference](system/security.md) - Policies, scopes, actors, token stores, and the `security:` block
- [Dependency Management](guides/dependency-management.md#integrity-verification) - Module digest verification
- [Cluster](guides/cluster.md#internode-identity) - Internode identity and peer trust
- [Temporal Workflows](temporal/workflows.md#security-context) - Signed context propagation
- [Registry](concepts/registry.md) - The capability store
- [Process Model](concepts/process-model.md) - Process isolation and lifecycle
- [Agents](framework/agents.md) - Agent definitions and tool use



---

# "Process Model"

## Process Model


Wippy executes code in isolated processes: lightweight state machines that communicate through messages rather than shared memory. This actor model gives each process its own state and lifecycle.

This page explains the lifecycle and isolation model. Use the [Process Management reference](../lua/core/process.md) for spawn, messaging, monitoring, registry, and upgrade APIs. See [Process Host and Services](../system/process-host.md) for runtime-managed service fields.



### State Machine Execution


Each process initializes, advances through execution, yields on blocking operations, and closes when complete. The scheduler multiplexes processes across a worker pool and runs other work while a process waits for I/O.

Processes support multiple concurrent yields, allowing code to start several asynchronous operations and wait for any or all of them without spawning additional processes.

```mermaid
flowchart LR
    Ready --> Running
    Running --> Blocked
    Running --> Idle
    Blocked --> Running
    Idle --> Running
    Running --> Complete
```

Processes are not limited to Lua. The runtime also supports WebAssembly modules through the `process.wasm` kind, and its process architecture can support other state-machine implementations.

<warning>
Processes are lightweight but not free. Each process carries a small baseline cost for its state, inbox, and scheduler bookkeeping, and dynamic allocations grow that footprint during execution.
</warning>



### Process Hosts


Wippy can run multiple process hosts within one runtime, each with its own capabilities and security boundaries. Privileged system processes can run in a host separate from hosts that execute user sessions.

Some hosts are specialized. The Terminal host, for example, uses one scheduler
worker and supplies terminal I/O context to accepted processes; it does not
enforce a one-process lifetime limit. Separate hosts allow one deployment to
run processes with different trust levels.



### Security Model


Each process executes under an actor identity and security policy. This is typically the user who initiated the call, while system processes use a system actor with different privileges.

Access control applies at multiple levels. Security policy can restrict individual process operations and message delivery between hosts. The policy attached to the current actor determines which operations are permitted.

For the security implications of process isolation, see the [Security Model](concepts/security-model.md).



### Spawning Processes


Create background processes with `process.spawn()`:

```lua
local pid, err = process.spawn("app.workers:handler", "app:processes", arg1, arg2)
if err then return nil, err end
return pid
```

The first argument is the registry entry, the second is the process host, and remaining arguments pass to the process.

Spawn variants control lifecycle relationships:

| Function | Behavior |
|----------|----------|
| `spawn` | Start an independent process |
| `spawn_monitored` | Receive EXIT events when child exits |
| `spawn_linked` | Abnormal exit propagates in either direction; with `trap_links: true`, the peer receives `LINK_DOWN` instead of failing |



### Message Passing


Processes communicate through messages rather than shared memory:

```lua
local ok, err = process.send(target_pid, "topic", payload)
if err then return nil, err end
return ok
```

Messages from the same sender arrive in order. Messages from different senders may interleave. Delivery is fire-and-forget—use request-response patterns when you need confirmation.

<note>
Processes can register in a local name registry and be addressed by name instead of PID (e.g., `session_manager`). Names can also be registered cluster-wide for cross-node addressing via `process.registry` using EVENTUAL (gossip-based), CONSISTENT, or STRONG (both Raft-backed) scopes.
</note>



### Supervision


Any process can supervise other processes by monitoring them. A supervisor starts monitored children, watches for EXIT events, and decides whether to restart them after failure.

```lua
local worker, spawn_err = process.spawn_monitored("app.workers:handler", "app:processes")
if spawn_err then return nil, spawn_err end

local event, open = process.events():receive()
if not open then return nil, errors.new("process event channel closed") end

if event.kind == process.event.EXIT and event.result.error then
    local replacement, restart_err = process.spawn_monitored("app.workers:handler", "app:processes")
    if restart_err then return nil, restart_err end
    worker = replacement
end
```

At the runtime level, services can start and supervise long-running processes. Define a `process.service` entry to have the runtime manage a process:

```yaml
- name: worker.service
  kind: process.service
  process: app.workers:handler
  host: app:processes
  lifecycle:
    auto_start: true
    restart:
      max_attempts: 5
      initial_delay: 1s
```

The service starts automatically and integrates with the runtime's lifecycle management. At the pinned runtime, the initial failed start counts toward `max_attempts`, so `5` permits at most four follow-up starts. Each retry waits for `initial_delay` with jitter; the delay does not increase between attempts.



### Process Upgrading


Running processes can upgrade their code without losing identity. Call `process.upgrade()` to swap to a new definition while preserving PID, mailbox, and supervision relationships:

```lua
process.upgrade("app.workers:v2", current_state)
```

The first argument is the new registry entry (or nil to reload the current definition). Additional arguments pass to the new version, letting you carry state across the upgrade. The process resumes execution with the new code immediately.

The runtime caches compiled prototypes to avoid repeated compilation. If an upgrade fails, the process crashes and normal supervision behavior applies; a monitoring parent can restart it or escalate the failure.



### Scheduling


The actor scheduler uses work-stealing across CPU cores. Each worker has a local queue for cache locality, plus a global queue for distributing work. Processes yield on blocking operations so other processes can run on the worker pool.



---

# "Cluster"

## Cluster


A single Wippy node is a complete runtime. A **cluster** connects several nodes so processes can use cluster-wide names, route messages across nodes, and coordinate through locks, groups, and a shared consensus core.

Clustering is opt-in (`cluster.enabled`). This page explains the model your code sees; for topology, configuration, and operations see the [Cluster Guide](guides/cluster.md).



### Cluster Model


Nodes discover one another through **gossip** (SWIM). A node joins through a seed, after which membership and failure information converge without a central coordinator. A bounded **Raft** core provides linearizable consensus through a dynamically reconciled voter set, while other nodes participate through gossip.

The application-facing model has three parts: **names**, **routing**, and **coordination primitives**.



### Naming


A process is normally addressed by its PID. In a cluster, it can also be registered under a **name** and reached by that name from other nodes. The selected **scope** determines the consistency guarantee and coordination cost:

| Scope | Visibility | Guarantee | Use it for |
|-------|------------|-----------|------------|
| **Local** | this node | instant, no coordination | node-local helpers |
| **Eventual** | cluster-wide | converges after gossip; conflicts resolve and notify the loser | service, group, and bounded presence names |
| **Consistent** | cluster-wide | linearizable singleton via Raft | the standard cluster-wide named service |
| **Strong** | cluster-wide | Consistent, plus every live node acknowledges before the name is active | control-plane singletons and locks |

The scopes are ordered as `Local < Eventual < Consistent < Strong` by consistency and coordination cost. Select the least costly scope that meets the required guarantee. Names are registered through [`process.registry`](lua/core/process.md). Local names are removed when the process exits; Consistent and Strong names are also reaped on process exit or node departure. Eventual names are removed explicitly or when their origin node leaves, not automatically when only the owning process exits.



### Routing


Routing connects a registered name to the process that owns it:

- **Reads are local.** Every node resolves a name from its own replica or gossip-disseminated cache — no network round-trip to look up a name. This keeps resolution fast and keeps working during partitions.
- **Resolution has a fixed order.** A name is resolved across the planes most-authoritative first — Consistent and Strong (Raft), then Eventual (gossip), then Local — so a cluster-wide name shadows a local one of the same string.
- **Writes route to the authority.** A Consistent or Strong registration goes through the Raft leader; a node that isn't the leader forwards the write and waits for the result. Once committed, the active binding is disseminated over gossip so every node — including those not in the Raft core — can resolve the name locally afterward.
- **Messaging routes by PID.** When you `process.send` to a name, it resolves to a PID and the relay delivers the message to the owning node. Your code addresses a process the same way whether it lives on this node or another — location is transparent.

Applications register and resolve names without addressing the authority node directly. After resolution, messages route to the node that owns the target PID.



### Primitives


Clustering exposes a small set of coordination building blocks:

- **Membership and identity** — the live set of nodes and this node's identity and role. Use it to discover peers or shard work. See [`system.cluster`](lua/system/system.md) and [`system.node`](lua/system/system.md).
- **Consensus state** — the Raft leader, term, and this node's role, for diagnostics and leader-aware logic. See [`system.raft`](lua/system/system.md).
- **Cluster-wide names** — register and resolve processes by name and scope, the foundation everything else builds on. See [`process.registry`](lua/core/process.md).
- **Distributed locks** — cluster-wide mutual exclusion with at most one holder, released automatically if the holder dies. See [`system.lock`](lua/system/system.md).
- **Process groups** — join named groups and broadcast to every member across all nodes, Erlang-style. See [Process Groups](lua/core/pg.md).

These primitives share membership and routing infrastructure. Consistent and Strong names and distributed locks use the Raft core. Process groups use gossip membership to discover peers, send changes over the relay, and periodically exchange full state for convergence.



### See Also


- [Cluster Guide](guides/cluster.md) — Topology, configuration, and operations
- [Process Management](lua/core/process.md) — Spawning, messaging, and the name registry
- [Process Groups](lua/core/pg.md) — Named groups and broadcast
- [System](lua/system/system.md) — `system.cluster`, `system.node`, `system.raft`, `system.lock`
- [Process Model](concepts/process-model.md) — Processes, PIDs, and messaging



---

# "Functions"

## Functions


Functions are call-and-return entry points. A function inherits its caller's
context and is canceled when the caller is canceled. Pools can reuse Lua states,
so module globals and closure upvalues may survive on one worker but are not
shared consistently across calls. Store durable or shared state outside the
function. Use functions for HTTP handlers, API endpoints, and other operations
that complete within a request lifecycle.



### Calling Functions


Call functions synchronously with `funcs.call()`:

```lua
local funcs = require("funcs")
local result, err = funcs.call("app.api:get_user", user_id)
if err then return nil, err end
return result
```

For non-blocking execution, use `funcs.async()`:

```lua
local future, err = funcs.async("app.process:analyze", data)
if err then
    return nil, err
end

local ch = future:response()
local payload, open = ch:receive()
if not open then
    return nil, "future response channel closed"
end

local result, err = payload:data()
if err then
    return nil, err
end
```

See the [funcs module](lua/core/funcs.md) for function invocation and executor options.



### Context Propagation


Each call creates a frame with its own context scope. Child functions inherit parent context without explicit passing:

```lua
local ctx = require("ctx")

local trace_id = ctx.get("trace_id")
local user_id = ctx.get("user_id")
```

Add context when calling:

```lua
local funcs = require("funcs")

local exec, err = funcs.new():with_context({trace_id = "abc-123"})
if err then return nil, err end

local result, err = exec:call("app.api:process", data)
if err then return nil, err end
return result
```

Security context propagates the same way. Called functions see the caller's actor and can check permissions. See the [security module](lua/security/security.md) for access control APIs.



### Registry Definition


At the registry level, a function entry looks like this:

```yaml
- name: get_user
  kind: function.lua
  source: file://handlers/user.lua
  method: get
  pool:
    type: lazy
    max_size: 16
```

Functions can be invoked by other runtime components—HTTP handlers, queue consumers, scheduled jobs—and are subject to permission checks based on the caller's security context.



### Pools


Functions run on pools that manage execution. The pool type determines scaling behavior.

**Inline** runs in the caller's goroutine without a worker pool. It is used for embedded contexts.

**Static** maintains a fixed number of workers. Requests queue when all workers are busy, which keeps worker concurrency fixed.

```yaml
pool:
  type: static
  size: 8
  buffer: 512
```

**Lazy** starts without workers and creates them on demand. Idle workers are removed after a timeout.

```yaml
pool:
  type: lazy
  max_size: 32
```

**Adaptive** adjusts the worker count based on measured throughput and current load.

```yaml
pool:
  type: adaptive
  max_size: 256
```

<tip>
If you don't specify a pool type, the runtime selects one based on your configuration. Set `workers` for static, `max_size` for lazy, or explicitly set `type` for full control. With neither set, the pool is lazy with a maximum of 16 workers.
</tip>



### Interceptors


Function calls pass through an interceptor chain. Interceptors can handle cross-cutting concerns separately from the function implementation.

```yaml
- name: my_function
  kind: function.lua
  source: file://handler.lua
  method: main
  meta:
    options:
      retry:
        max_attempts: 3
        initial_delay: 100
        backoff_factor: 2.0
```

Built-in interceptors include retry with exponential backoff. Runtime
integrations written in Go can register additional interceptors for logging,
metrics, tracing, authorization, circuit breaking, or request transformation;
Lua application entries can configure only interceptors installed by the
runtime.

The chain runs before and after each call. Each interceptor can modify the request, short-circuit execution, or wrap the response.



### Contracts


Functions can expose their input/output schemas as contracts. Contracts define method signatures that enable runtime validation and documentation generation.

```lua
local contract = require("contract")
local sender, err = contract.get("app.email:sender")
if err then return nil, err end

local email, err = sender:open("app.email:sender_impl")
if err then return nil, err end

local result, err = email:send({to = "user@example.com", subject = "Hello"})
if err then return nil, err end
return result
```

Contracts allow callers to use an interface while selecting an implementation separately. This supports testing, multi-tenant deployments, and gradual migrations.



### Functions vs Processes


Functions inherit the caller's context and lifecycle. When the caller is canceled, its function calls are canceled as well. This suits execution within HTTP handlers and queue consumers.

Processes run independently with host context. They outlive their creator and communicate through messages. Use processes for background work; use functions for request-scoped operations.



---

# "Workflows"

## Workflows


Workflows persist the state of long-running operations so execution can recover after crashes and restarts. They suit processes such as payments, order fulfillment, and multi-step approvals.



### Why Use Workflows


Functions keep in-flight state in memory, while workflows persist execution state:

| Aspect | Functions | Workflows |
|--------|-----------|-----------|
| State | Call-local | Rebuilt from persisted history |
| Worker crash | In-flight call fails | Replays from recorded history |
| Duration | Seconds to minutes | Hours to months |
| Application failure | Returned to caller | Ends or retries according to provider policy |



### How Workflows Work


Workflow code looks like regular Lua code:

```lua
local funcs = require("funcs")
local time = require("time")

local result, err = funcs.call("app.api:charge_card", payment)
if err then return nil, err end

time.sleep("24h")

local status, err = funcs.call("app.api:check_status", result.id)
if err then return nil, err end

if status == "failed" then
    local _, refund_err = funcs.call("app.api:refund", result.id)
    if refund_err then return nil, refund_err end
end

return status
```

The workflow engine intercepts calls and records their results. After a crash, it replays execution from the recorded history.

Inside a workflow, each `funcs.call()` target runs as a Temporal activity. A
target `function.*` entry must register with a worker through
`meta.temporal.activity.worker`; unregistered entries are not available to the
workflow. A `process.*` activity target additionally needs
`meta.options.default_host` (or the legacy `meta.default_host`) so it is
registered in the function registry used by the Temporal worker. See
[Activities](../temporal/activities.md) for the function activity example and
activity options.

<note>
Workflow authors must still write deterministic code. Wippy limits workflow
modules to those classified as Deterministic or Workflow and supplies
replay-safe implementations for supported operations. <code>funcs.call()</code>
runs a recorded activity, <code>time.sleep()</code> uses a workflow timer,
<code>uuid.v4()</code> records a side effect, and <code>time.now()</code> reads the
workflow's deterministic time reference.
</note>



#### Saga Pattern


Compensate on failure:

```lua
local funcs = require("funcs")

local inventory, err = funcs.call("app.inventory:reserve", items)
if err then return nil, err end

local payment, err = funcs.call("app.payments:charge", amount)
if err then
    local _, compensation_err = funcs.call("app.inventory:release", inventory.id)
    return nil, compensation_err or err
end

local shipping, err = funcs.call("app.shipping:create", order)
if err then
    local _, refund_err = funcs.call("app.payments:refund", payment.id)
    local _, release_err = funcs.call("app.inventory:release", inventory.id)
    return nil, refund_err or release_err or err
end

return {inventory = inventory, payment = payment, shipping = shipping}
```



#### Waiting for Signals


Wait for external events (approval decisions, webhooks, user actions):

```lua
local funcs = require("funcs")

local _, err = funcs.call("app.approvals:submit", request)
if err then return nil, err end

local inbox = process.inbox()
local msg, open = inbox:receive()  -- blocks until signal arrives
if not open then return nil, errors.new("workflow inbox closed") end

local decision, payload_err = msg:payload():data()
if payload_err then return nil, payload_err end

if decision.approved then
    return funcs.call("app.orders:fulfill", request.order_id)
else
    return funcs.call("app.notifications:send_rejection", request)
end
```



### Choosing a Compute Model


| Use Case | Choose |
|----------|--------|
| HTTP request handling | Functions |
| Data transformation | Functions |
| Background jobs | Processes |
| User session state | Processes |
| Real-time messaging | Processes |
| Payment processing | Workflows |
| Order fulfillment | Workflows |
| Multi-day approvals | Workflows |



### Starting Workflows


Workflows use `process.spawn()` with a workflow host:

```lua
-- Spawn workflow on temporal worker
local pid, err = process.spawn("app.workflows:order_processor", "app:temporal_worker", order_data)
if err then return nil, err end

-- Send signals to workflow
local ok, err = process.send(pid, "update", {status = "approved"})
if err then return nil, err end
return ok
```

The caller uses the same spawn API. The host determines whether the entry runs
on a `temporal.worker` or a `process.host`. Persisted history and replay apply
only to the Temporal-hosted path. A workflow entry run through an ordinary
process host has in-memory process semantics and does not gain Temporal
durability.

<tip>
When a workflow spawns children via <code>process.spawn()</code>, they become child workflows on the same provider, maintaining durability guarantees.
</tip>



### Failure and Supervision


Processes can run as supervised services using `process.service`:

```yaml


## Process definition

- name: session_handler
  kind: process.lua
  source: file://session_handler.lua
  method: main



## Supervised service wrapping the process

- name: session_manager
  kind: process.service
  process: app:session_handler
  host: app:processes
  lifecycle:
    auto_start: true
    restart:
      max_attempts: 10
```

Workflows do not use process supervision trees. The workflow provider manages
persistence and recovery; application-level retries follow the configured
workflow and activity policies.



### Configuration


Workflow definition (spawned dynamically):

```yaml
- name: order_processor
  kind: workflow.lua
  source: file://order_processor.lua
  method: main
  meta:
    temporal:
      workflow:
        worker: app:temporal_worker
  modules:
    - funcs
    - time
```

Every function or process invoked through `funcs.call()` also declares the
activity worker. For example:

```yaml
- name: charge_card
  kind: function.lua
  source: file://charge_card.lua
  method: main
  meta:
    temporal:
      activity:
        worker: app:temporal_worker
```

Workflow provider:

```yaml
- name: temporal_worker
  kind: temporal.worker
  client: app:temporal_client
  task_queue: "orders"
  lifecycle:
    auto_start: true
```

See [Temporal](https://temporal.io) for production workflow infrastructure.



### See Also


- [Functions](concepts/functions.md) — Request-scoped calls
- [Process Model](concepts/process-model.md) — Stateful background work
- [Supervision](guides/supervision.md) — Process restart policies



---

# "Lua Runtime"

## Lua Runtime


Lua is Wippy's primary runtime for I/O-bound work and business logic. Code runs in isolated processes that communicate through message passing rather than shared memory.

This page is a conceptual overview. Its code blocks are isolated reference snippets; names such as `inbox`, `events`, and `handle_message` stand for values or callbacks supplied by the surrounding application.

For the design tradeoffs behind Lua and its relationship to WebAssembly, see [Why Wippy Uses Lua](why-lua.md).



### Processes


Lua code runs inside **processes**: isolated execution contexts managed by the scheduler. Each process:

- has its own memory space;
- yields during blocking operations such as I/O and channel access;
- can be monitored and supervised; and
- can run alongside thousands of other processes on one machine.

```lua
local pid, err = process.spawn("app.workers:handler", "app:processes")
if err then
    return nil, err
end

local sent, send_err = process.send(pid, "task", {data = "work"})
if send_err then
    return nil, send_err
end
```

Executable Lua entries receive `process` as an ambient global. It can also be loaded with `require("process")` without adding it to the entry's `modules` list. See [Process Management](lua/core/process.md) for spawning, linking, and supervision.



### Channels


Channels provide communication between concurrent tasks:

```lua
local sync_ch = channel.new()   -- unbuffered
local buffered = channel.new(10)

buffered:send("work")           -- completes while buffer space is available
local val, ok = buffered:receive()  -- val is "work" and ok is true
```

See [Channels](lua/core/channel.md) for select and patterns.



### Coroutines


Within a process, use lightweight coroutines for concurrent work:

```lua
coroutine.spawn(function()
    local data = fetch_data()
    ch:send(data)
end)

do_other_work()  -- continues immediately
```

The scheduler manages spawned coroutines, so callers do not manually yield or resume them.



### Select


Use `channel.select` to wait for multiple event sources:

```lua
local r = channel.select {
    inbox:case_receive(),
    events:case_receive(),
    timeout:case_receive()
}

if r.channel == timeout then
    -- timed out
elseif r.channel == events then
    handle_event(r.value)
else
    handle_message(r.value)
end
```



### Globals


The following globals are available without `require` and do not need to be listed in `modules:`:

- `channel` - Go-style channels
- `payload` - the entry's input payload
- `process` - process spawning, messaging, monitoring, and lifecycle operations
- `print`, `subscribe`, `unsubscribe` - logging and pub/sub
- `os`, `table`, `math`, `string`, `coroutine`, `errors` - standard libraries



### Modules


Built-in runtime modules that are not ambient are loaded with `require()` and must appear in the entry's `modules:` allowlist. Executable entries receive `process` as an ambient global; `require("process")` is also allowed and does not require a `modules:` declaration.

```lua
local process = require("process")
local json = require("json")
local sql = require("sql")
local http = require("http_client")
```

Available modules depend on entry configuration. See [Entry Definitions](lua/entries.md).

Registry libraries use the same `require("alias")` syntax but are declared separately in the entry's `imports:` map.



### Language and Library Support


Wippy uses Lua 5.3 syntax with a [gradual type system](lua/types.md) inspired by Luau. Types are first-class runtime values that can be used for validation, passed as arguments, and inspected at runtime.

External Lua libraries (LuaRocks, etc.) are not supported. The runtime provides its own module system with built-in extensions for I/O, networking, and system integration.

For custom extensions, see [Modules](internals/modules.md) in the internals documentation.



### Error Handling


Functions commonly return `result, error` pairs:

```lua
local data, err = json.decode(input)
if err then
    return nil, errors.wrap(err, "decode failed")
end
```

This snippet assumes `json` is enabled in the entry's `modules` list and `input` contains the string to decode. See [Error Handling](lua/core/errors.md) for patterns.



### What's Next


- [Entry Definitions](lua/entries.md) - Configure entry points
- [Channels](lua/core/channel.md) - Channel patterns
- [Process Management](lua/core/process.md) - Spawning and supervision
- [Functions](lua/core/funcs.md) - Cross-process calls



---

# "Why Wippy Uses Lua"

## Why Wippy Uses Lua


Wippy uses Lua as its primary runtime language because it fits the platform's process-isolation and embedding requirements. This page explains that design choice and its tradeoffs; it is not a general ranking of programming languages.

This is a conceptual design note rather than a runnable tutorial. It describes runtime properties and points to the reference pages that define the concrete APIs.



### Runtime Requirements


Wippy runs user-defined logic in isolated processes. Each process has its own memory and receives only the capabilities exposed by the runtime. Because many processes can run concurrently, the embedded language must support:

- **Low per-process overhead.** Memory use must remain practical as process counts grow.
- **Capability isolation.** The runtime must control the modules, functions, and system operations available to each process.
- **In-process embedding.** Wippy's Go core must be able to create, configure, and stop a language environment for each process.
- **Controlled module loading.** Modules must come from the runtime's allowlist or declared registry imports rather than arbitrary file-system paths.
- **A small language surface.** Application code should remain readable and straightforward to generate, review, and lint.



#### Python


Python offers a large application and data ecosystem, but its interpreter, import model, and package assumptions do not match Wippy's per-process embedding and capability model. Python services can still integrate with Wippy over explicit service boundaries.



#### JavaScript


JavaScript runtimes offer several embedding options. Their module and package ecosystems, however, require a separate integration layer to provide the registry-scoped loading model Wippy uses. Wippy chose Lua's smaller host-controlled runtime surface for application code.



#### Go


Go is used for Wippy's core runtime. Compiled Go code and plugins do not provide the same isolated, per-process embedded environment required for user-defined application logic.



#### WebAssembly


WebAssembly fills a complementary role rather than replacing Lua as the primary authoring language. Its division of responsibilities is described in [Lua and WebAssembly](#lua-and-webassembly).



#### Host-Controlled Embedding


Lua is designed to run inside a host application. Wippy creates an environment for each process, connects it to the scheduler and registry, and controls its globals and module loader. `require` reads only modules already installed in that environment: the always-available base modules and standard libraries, the executable entry's ambient `process` module, built-in runtime modules allowed by `modules:`, and registry libraries declared through `imports:`. It does not search file-system paths or install packages from the network. Different entries can therefore receive different module sets without application-level loading rules.



#### Language Surface


Lua has a compact syntax and a small standard environment. Wippy adds type annotations and linting so code can be checked incrementally without changing the underlying execution model.



#### Cooperative Scheduling


Lua coroutines map to Wippy's cooperative scheduling model. A process can yield during channel or I/O operations while the scheduler runs other work.



### Tradeoffs


Lua does not provide an in-process package ecosystem comparable to pip or npm. Wippy supplies built-in runtime modules through an allowlist and application libraries through registry imports rather than installing packages from the network. Workloads that depend on large external libraries can run as services or as WebAssembly components.

Lua may also be unfamiliar to developers coming from other languages. The syntax is compact, but teams still need conventions, review, and linting for production code.



### Lua and WebAssembly


Wippy provides two complementary runtimes:

- **Lua** is the primary runtime for application logic, tools, and agents.
- **WebAssembly** runs compiled workloads and existing code that can target WASM.

Lua and WASM process entries use Wippy's process model; Lua and WASM functions are exposed through registered function entries. Both integrations are configured through the registry and runtime security policies. Lua code can call registered WASM functions, and WASM processes can call registered Lua functions.



### See Also


- [Lua Runtime Overview](lua/overview.md) - The Lua runtime and its modules
- [Types](lua/types.md) - Type annotations, generics, and unions
- [Linter](guides/linter.md) - Static analysis for Lua
- [WASM Runtime](wasm/overview.md) - Running compiled code in the sandbox



---

# "Type System"

## Type System


> **Experimental.** The type system is still evolving, and some limitations are expected.

Wippy's gradual type system supports incremental annotations and flow-sensitive checking. Types are non-nullable by default.

This page is a language reference, not a complete program. Each code block is an isolated type-checking example, and alternatives within a block are not necessarily meant to be combined. Names such as `get_data`, `get_user`, `call`, and `User` represent application code; lines marked `ERROR` intentionally demonstrate diagnostics. These examples use language syntax and built-in type values, so they do not require runtime modules.



### Primitives


```lua
local n: number = 3.14
local i: integer = 42         -- integer is subtype of number
local s: string = "hello"
local b: boolean = true
local a: any = "anything"     -- dynamic member and method access
local u: unknown = { source = "example" }  -- must narrow before use
```



#### `any` and `unknown`


```lua
-- any: dynamic member and method access
local a: any = get_data()
a.foo.bar.baz()              -- no error, may crash at runtime
local s: string = a          -- ERROR: any is not assignable to string

-- unknown: safe unknown, must narrow before use as a concrete type
local u: unknown = get_data()
u.foo                        -- no error: member access on unknown behaves like any
local n: number = u          -- ERROR: unknown not assignable to number, narrow first
if type(u) == "table" then
    -- u narrowed to table here
end
```



### Nil Safety


Types are non-nullable by default. Use `?` for optional values:

```lua
local x: number = nil         -- ERROR: nil not assignable to number
local y: number? = nil        -- OK: number? means "number or nil"
local z: number? = 42         -- OK
```



#### Control Flow Narrowing


The type checker tracks control flow:

```lua
local function process(x: number?): number
    if x ~= nil then
        return x              -- x is number here
    end
    return 0
end

-- Early return pattern
local user, err = get_user(123)
if err then return nil, err end
-- user narrowed to non-nil here

-- Or default
local val = get_value() or 0  -- val: number
```



### Union Types


```lua
local val: number | string = get_value()

if type(val) == "number" then
    print(val + 1)            -- val: number
else
    print(val:upper())        -- val: string
end
```



#### Literal Types


```lua
type Status = "pending" | "active" | "done"

local s: Status = "pending"   -- OK
local s: Status = "invalid"   -- ERROR
```



### Function Types


```lua
local function add(a: number, b: number): number
    return a + b
end

-- Multiple returns
local function div_mod(a: number, b: number): (number, number)
    return math.floor(a / b), a % b
end

-- Error returns (Lua idiom)
local function fetch(url: string): (string?, error?)
    -- returns (data, nil) or (nil, error)
end

-- First-class function types
local double: (number) -> number = function(x: number): number
    return x * 2
end
```



#### Variadic Functions


```lua
local function sum(...: number): number
    local total: number = 0
    for _, v in ipairs({...}) do
        total = total + v
    end
    return total
end
```



### Record Types


```lua
type User = {name: string, age: number}

local u: User = {name = "alice", age = 25}
```



#### Optional Fields


```lua
type Config = {
    host: string,
    port: number,
    timeout?: number,
    debug?: boolean
}

local cfg: Config = {host = "localhost", port = 8080}  -- OK
```



### Generics


```lua
local function identity<T>(x: T): T
    return x
end

local n: number = identity(42)
local s: string = identity("hello")
```



#### Constrained Generics


```lua
type HasName = {name: string}

local function greet<T: HasName>(obj: T): string
    return "Hello, " .. obj.name
end

greet({name = "Alice"})       -- OK
greet({age = 30})             -- ERROR: missing 'name'
```



### Intersection Types


Combine multiple types:

```lua
type Named = {name: string}
type Aged = {age: number}
type Person = Named & Aged

local p: Person = {name = "Alice", age = 30}
```



### Tagged Unions


```lua
type Result<T, E> =
    {ok: true, value: T}
    | {ok: false, error: E}

type LoadState =
    {status: "loading"}
    | {status: "loaded", data: User}
    | {status: "error", message: string}

local function render(state: LoadState): string
    if state.status == "loading" then
        return "Loading..."
    elseif state.status == "loaded" then
        return "Hello, " .. state.data.name
    elseif state.status == "error" then
        return "Error: " .. state.message
    end
end
```



### The `never` Type


`never` is the bottom type: it has no possible values.

```lua
function fail(msg: string): never
    error(msg)
end
```



### Error Handling Pattern


The checker understands the common Lua `value, error` return pattern:

```lua
local value, err = call()
if err then
    -- value is nil here
    return nil, err
end
-- value is non-nil here, err is nil
print(value)
```



### Non-Nil Assertion


Use `!` to assert an expression is non-nil:

```lua
local user: User? = get_user()
local name = (user!).name            -- assert user is non-nil
```

`!` is a type-checker assertion only - it narrows the type to non-nil but emits no runtime check. If the value is actually nil, the following operation fails with the usual error (e.g. indexing nil). Use when you know a value cannot be nil but the type checker cannot prove it.



#### Runtime Validation


Call a type as a function to validate a value. Validation returns the original value with the requested static type; it does not convert or coerce the value:

```lua
local data: any = get_json()
local user = User(data)              -- validates and returns User
local name = user.name               -- safe field access
```

This works with primitives and custom types:

```lua
local x: any = get_value()
local s = string(x)                  -- requires an existing string
local n = integer(x)                 -- requires an existing integer
local b = boolean(x)                 -- requires an existing boolean

type Point = {x: number, y: number}
local p = Point(data)                -- validates record structure
```

For example, `string(42)` raises a validation error; use `tostring(42)` when conversion is intended.



#### Type:is() Method


`Type:is` validates without throwing and returns either `(value, nil)` or `(nil, error)`:

```lua
type Point = {x: number, y: number}
local data: any = get_input()

local p, err = Point:is(data)
if p then
    local sum = p.x + p.y            -- p is valid Point
else
    return nil, err                  -- validation failed
end
```

The result narrows in conditionals:

```lua
if Point:is(data) then
    local p: Point = data            -- data narrowed to Point
end
```



#### Unsafe Cast


Use `::` or `as` for unchecked casts:

```lua
local data: any = get_data()
local user = data :: User            -- no runtime check
local user = data as User            -- same as ::
```

Use sparingly. Unsafe casts bypass validation and can cause runtime errors if the value doesn't match the type.



### Type Reflection


Types are first-class values that provide introspection methods.



#### Kind and Name


```lua
type Num = number

print(Num:kind())                    -- "number"
print(Point:kind())                  -- "record"
print(Point:name())                  -- "Point"
```



#### Record Fields


Iterate over record fields:

```lua
type User = {name: string, age: number}

for name, typ in User:fields() do
    print(name, typ:kind())
end
-- name    string
-- age     number
```

Access individual field types:

```lua
local nameType = User.name           -- type of 'name' field
print(nameType:kind())               -- "string"
```



#### Collection Types


```lua
type NumberList = {number}
print(NumberList:elem():kind())      -- "number"

type ScoreMap = {[string]: number}
print(ScoreMap:key():kind())         -- "string"
print(ScoreMap:val():kind())         -- "number"
```



#### Optional Types


```lua
type MaybeNumber = number?
print(MaybeNumber:kind())            -- "optional"
print(MaybeNumber:inner():kind())    -- "number"
```



#### Union Types


```lua
type Status = "pending" | "active" | "done"

for variant in Status:variants() do
    print(variant)
end
```



#### Function Types


```lua
type Predicate = (number, string) -> boolean

for param in Predicate:params() do
    print(param:kind())
end
print(Predicate:ret():kind())        -- "boolean"
```

`typeof(expression)` is type syntax, not a runtime reflection function. Use it in an alias such as `type Config = typeof(default_config)`; the resulting alias is the runtime type value.



#### Type Comparison


```lua
type Num = number
type Int = integer

print(Num == Num)                    -- true
print(Int <= Num)                    -- true (subtype)
print(Int < Num)                     -- true (strict subtype)
```



#### Types as Table Keys


```lua
type Point = {x: number, y: number}
type Line = {from: Point, to: Point}

local handlers = {}
handlers[Point] = function() return "point handler" end
handlers[Line] = function() return "line handler" end

local h = handlers[Point]
if h then h() end
```



### Type Annotations


Add types to function signatures:

```lua
-- Parameter and return types
local function process(input: string): number
    return #input
end

-- Local variable types
local count: number = 0

-- Type aliases
type StringArray = {string}
type StringMap = {[string]: number}
```



### Type Validators


Attach validation constraints to type aliases with annotations, then call the type or use `Type:is()` to enforce them at runtime:

```lua
type NonNegative = number @min(0)
type Percentage = number @min(0) @max(100)
type Email = string @pattern("^.+@.+$")

local x = NonNegative(1)
local percent, err = Percentage:is(50)
local email = Email("test@example.com")
```

An annotation on a local variable is checked statically by the linter. It does not insert an automatic runtime check at assignment; runtime enforcement occurs when a type value validates a value.



#### Built-in Validators


| Validator | Applies to | Example |
|-----------|------------|---------|
| `@min(n)` | number | `type Positive = number @min(1)` |
| `@max(n)` | number | `type Percentage = number @max(100)` |
| `@min_len(n)` | string, array | `type NonEmpty = string @min_len(1)` |
| `@max_len(n)` | string, array | `type ShortName = string @max_len(10)` |
| `@pattern(regex)` | string | `type Email = string @pattern("^.+@.+$")` |



#### Record Field Validators


```lua
type User = {
    age: number @min(0) @max(150),
    name: string @min_len(1) @max_len(100)
}
```



#### Array Element Validators


```lua
local scores: {number @min(0) @max(100)} = {85, 90}
```



#### Union Member Validators


```lua
local id: number @min(1) | string @min_len(1) = 1
```



### Variance Rules


| Position | Variance | Description |
|----------|----------|-------------|
| Readonly field | Covariant | Can use subtype |
| Mutable field | Quasi-invariant | Normally invariant; fresh literals and refinements may widen to their base type |
| Function parameter | Contravariant | Can use supertype |
| Function return | Covariant | Can use subtype |



### Subtyping


- `integer` is a subtype of `number`
- `never` is a subtype of all types
- All types are subtypes of `any`
- Union subtyping: `A` is subtype of `A | B`



### Gradual Adoption


Types can be added incrementally; untyped code continues to work:

```lua
-- Existing code works unchanged
function old_function(x)
    return x + 1
end

-- New code gets types
function new_function(x: number): number
    return x + 1
end
```

Useful starting points include:

1. Function signatures at API boundaries
2. HTTP handlers and queue consumers
3. Critical business logic



### Type Checking


Run the type checker with:

```bash
wippy lint
```

The command reports type errors without executing the code.



---

# "Lua Entry Kinds"

## Lua Entry Kinds


Lua entry kinds define how source code is loaded and executed as a function, process, workflow, or library.

This page is a configuration reference. YAML blocks are partial entry definitions intended to be placed under an `entries:` mapping in a Wippy index; they are not complete applications by themselves. Referenced source files, imports, dependencies, process hosts, and security policies must exist in the surrounding project.



### Entry Kinds


| Kind | Description |
|------|-------------|
| `function.lua` | Stateless function, runs on demand |
| `process.lua` | Long-running actor with state |
| `workflow.lua` | Durable workflow (Temporal) |
| `library.lua` | Shared code imported by other entries |

Each kind has a precompiled bytecode counterpart (`function.lua.bc`, `library.lua.bc`, `process.lua.bc`, `workflow.lua.bc`) produced by `wippy pack --bytecode '**'` (or a pattern like `--bytecode 'app:**'`). Authors write `.lua` entries; the bytecode kinds are emitted when packing with that flag.

`module.lua` is reserved for built-in module definitions created by the runtime. It is not an authorable source entry and has no bytecode counterpart.



### Common Fields


All Lua entries share these fields:

| Field | Required | Description |
|-------|----------|-------------|
| `name` | yes | Unique name within namespace |
| `kind` | yes | One of the Lua kinds above |
| `source` | yes | Inline Lua source or a `file://path.lua` reference resolved when the registry is loaded |
| `method` | function/process/workflow | Function to export (libraries don't use it) |
| `modules` | no | Allowed modules for `require()` |
| `imports` | no | Other entries as local modules |
| `meta` | no | Searchable metadata |

`pool` applies only to `function.lua`. `security` applies to `function.lua` and `process.lua`.



### `function.lua`


A `function.lua` entry runs on demand, with each invocation handled independently.

```yaml
- name: handler
  kind: function.lua
  source: file://handler.lua
  method: main
  modules:
    - http
    - json
```

Use functions for HTTP handlers, data transformations, and utilities.



### `process.lua`


A `process.lua` entry is a long-running actor that maintains state and communicates through messages.

```yaml
- name: worker
  kind: process.lua
  source: file://worker.lua
  method: main
  modules:
    - sql
```

Choose a process for background workers, service daemons, and stateful actors.

To run as a supervised service:

```yaml
- name: worker_service
  kind: process.service
  process: app:worker
  host: app:processes
  lifecycle:
    auto_start: true
    restart:
      max_attempts: 10
```



### `workflow.lua`


A `workflow.lua` entry defines a durable workflow whose state is persisted to Temporal.

```yaml
- name: order_processor
  kind: workflow.lua
  source: file://order_workflow.lua
  method: main
  modules:
    - workflow
    - time
```

Use workflows for multi-step business processes and long-running orchestration.



### `library.lua`


A `library.lua` entry provides shared code that other entries can import.

```yaml
- name: helpers
  kind: library.lua
  source: file://helpers.lua
  modules:
    - json
    - base64
```

Other entries reference it via `imports`:

```yaml
- name: handler
  kind: function.lua
  source: file://handler.lua
  method: main
  imports:
    helpers: app.lib:helpers
```

In Lua code:

```lua
local helpers = require("helpers")
helpers.format_date(timestamp)
```



### Modules


The `modules` field controls which modules can be loaded with `require()`:

```yaml
modules:
  - http
  - json
  - sql
```

`channel`, `payload`, `print`, `process`, `subscribe`, and `unsubscribe` are loaded as Lua globals — they don't need to appear in `modules:`. `require("process")` is also allowed without a `modules:` declaration.

Only listed built-in modules and aliases declared under `imports` are available. The module allowlist limits access to runtime capabilities, makes dependencies explicit, and restricts workflows to workflow-compatible module classes.

See [Lua Runtime](lua/overview.md) for available modules.



### Imports


Import other entries as local modules:

```yaml
imports:
  utils: app.lib:utils       # require("utils")
  auth: app.auth:helpers     # require("auth")
```

The key becomes the module name in Lua code. The value is the entry ID (`namespace:name`).



### Function Pools


Use `pool` to configure how a function entry executes:

```yaml
- name: handler
  kind: function.lua
  source: file://handler.lua
  method: main
  pool:
    type: adaptive    # explicit; omit to use auto-select (lazy)
    max_size: 16      # cap for elastic growth
```

| Field | Pools | Description |
|-------|-------|-------------|
| `type` | all | Scheduler implementation (see table below) |
| `workers` | static | Worker thread count (falls back to `size`, then 8) |
| `size` | static | Worker count when `workers` is unset; with `type` omitted, `size` without `max_size` selects an inline pool |
| `buffer` | static | Task queue capacity (default: `workers * 64`) |
| `max_size` | lazy, adaptive | Upper bound for elastic growth (default: 16; 100 when `type` is omitted) |

| Type | Behavior |
|------|----------|
| `inline` | Synchronous execution in the caller's goroutine. No isolation between calls. |
| `lazy` | Zero idle workers, spawn on demand, tear down when idle. |
| `static` | Fixed-size channel-based pool. Predictable under steady load. |
| `adaptive` | Auto-scaling pool — grows under load, shrinks when idle. |

When `type` is omitted, the pool is auto-selected from the other fields: a lazy pool by default, a static pool if `workers` is set, an inline pool if only `size` is set.



### Metadata


Use `meta` to attach searchable routing and discovery fields:

```yaml
- name: api_handler
  kind: function.lua
  meta:
    type: handler
    version: "2.0"
    tags: [api, users]
  source: file://api.lua
  method: handle
  modules:
    - http
    - json
    - registry
```

Metadata is searchable via the registry:

```lua
local registry = require("registry")
local handlers, err = registry.find({["meta.type"] = "handler"})
if err then
    return nil, err
end
```

The query returns all matching registry entries. The Lua code belongs to an executable entry whose `modules` list includes `registry`, such as the `api_handler` entry above.



### See Also


- [Entry Kinds](guides/entry-kinds.md) - Reference for all entry kinds
- [Compute Units](concepts/compute-units.md) - Functions vs processes vs workflows
- [Lua Runtime](lua/overview.md) - Available modules



---

# "Standard Lua Libraries"

## Standard Lua Libraries

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="workflow"/>

These core Lua libraries are available in every executable Lua entry without `require()`.

This is an API reference. Signature blocks list available functions, while the longer blocks are isolated examples or partial patterns rather than complete entries. Names such as `check_health` and `process_request` represent application callbacks.



#### Type and Conversion


```lua
type(value)         -- Returns: "nil", "number", "string", "boolean", "table", "function", "thread", "userdata"
tonumber(s [,base]) -- Convert to number, optional base (2-36)
tostring(value)     -- Convert to string, calls __tostring metamethod
```



#### Assertions and Errors


```lua
assert(v [,msg])    -- Raises error if v is false/nil, returns v otherwise
error(msg [,level]) -- Raises error at specified stack level (default 1)
pcall(fn, ...)      -- Protected call, returns ok, result_or_error
xpcall(fn, errh)    -- Protected call with error handler function
```



#### Table Iteration


```lua
pairs(t)            -- Iterate all key-value pairs
ipairs(t)           -- Iterate array portion (1, 2, 3, ...)
next(t [,index])    -- Get next key-value pair after index
```



#### Metatables


```lua
getmetatable(obj)       -- Get metatable (or __metatable field if protected)
setmetatable(t, mt)     -- Set metatable, returns t
```



#### Raw Table Access


Bypass metamethods for direct table access:

```lua
rawget(t, k)        -- Get t[k] without __index
rawset(t, k, v)     -- Set t[k]=v without __newindex
rawequal(a, b)      -- Compare without __eq
```



#### Utilities


```lua
select(index, ...)  -- Return args from index onwards
select("#", ...)    -- Return number of args
unpack(t [,i [,j]]) -- Return t[i] through t[j] as multiple values
print(...)          -- Print values (uses structured logging in Wippy)
```



#### Global Variables


```lua
_G        -- The global environment table
_VERSION  -- Lua version string
```



### Table Manipulation


The `table` library provides in-place array operations, sorting, concatenation, and unpacking:

```lua
table.insert(t, [pos,] value)  -- Insert value at pos (default: end)
table.remove(t [,pos])         -- Remove and return element at pos (default: last)
table.concat(t [,sep [,i [,j]]]) -- Concatenate array elements with separator
table.sort(t [,comp])          -- Sort in place, comp(a,b) returns true if a < b
table.unpack(t [,i [,j]])      -- Unpack table elements as multiple values
table.create(narr, nhash)      -- Preallocate table with array and hash capacity
table.freeze(t)                -- Make table immutable, returns t
table.isfrozen(t)              -- true if table is immutable
```

```lua
local items = {"a", "b", "c"}

table.insert(items, "d")           -- {"a", "b", "c", "d"}
table.insert(items, 2, "x")        -- {"a", "x", "b", "c", "d"}
table.remove(items, 2)             -- {"a", "b", "c", "d"}, returns "x"

local csv = table.concat(items, ",")  -- "a,b,c,d"

table.sort(items, function(a, b)
    return a > b  -- Descending order
end)
```



### String Operations


String functions are also available as methods on string values.



#### Pattern Matching


```lua
string.find(s, pattern [,init [,plain]])   -- Find pattern, returns start, end, captures
string.match(s, pattern [,init])           -- Extract matching substring
string.gmatch(s, pattern)                  -- Iterator over all matches
string.gsub(s, pattern, repl [,n])         -- Replace matches, returns string, count
```



#### Case Conversion


```lua
string.upper(s)   -- Convert to uppercase
string.lower(s)   -- Convert to lowercase
```



#### Substrings and Characters


```lua
string.sub(s, i [,j])      -- Substring from i to j (negative indexes from end)
string.len(s)              -- String length (or use #s)
string.byte(s [,i [,j]])   -- Numeric codes of characters
string.char(...)           -- Create string from character codes
string.rep(s, n)           -- Repeat string n times
string.reverse(s)          -- Reverse string
```



#### Formatting


```lua
string.format(fmt, ...)    -- Printf-style formatting
string.pack(fmt, ...)      -- Pack values into a binary string
string.unpack(fmt, s [,pos]) -- Unpack binary string, returns values and next position
string.packsize(fmt)       -- Size in bytes of a packed format
```

Format specifiers: `%d` (integer), `%f` (float), `%s` (string), `%q` (quoted), `%x` (hex), `%o` (octal), `%e` (scientific), `%%` (literal %)

```lua
local s = "Hello, World!"

-- Pattern matching
local start, stop = string.find(s, "World")  -- 8, 12
local word = string.match(s, "%w+")          -- "Hello"

-- Substitution
local new = string.gsub(s, "World", "Wippy") -- "Hello, Wippy!"

-- Method syntax
local upper = s:upper()                       -- "HELLO, WORLD!"
local part = s:sub(1, 5)                      -- "Hello"
```



#### Patterns


| Pattern | Matches |
|---------|---------|
| `.` | Any character |
| `%a` | Letters |
| `%d` | Digits |
| `%w` | Alphanumeric |
| `%s` | Whitespace |
| `%p` | Punctuation |
| `%c` | Control characters |
| `%x` | Hexadecimal digits |
| `%z` | Zero (null) |
| `[set]` | Character class |
| `[^set]` | Negated class |
| `*` | 0 or more (greedy) |
| `+` | 1 or more (greedy) |
| `-` | 0 or more (lazy) |
| `?` | 0 or 1 |
| `^` | Start of string |
| `$` | End of string |
| `%b()` | Balanced pair |
| `(...)` | Capture group |

Uppercase versions (`%A`, `%D`, etc.) match the complement.



### Math Functions


The `math` library provides numeric constants and common mathematical operations.



#### Constants {id="math-constants"}


```lua
math.pi       -- 3.14159...
math.huge     -- Largest representable float
math.mininteger  -- Minimum integer
math.maxinteger  -- Maximum integer
```



#### Basic Operations


```lua
math.abs(x)           -- Absolute value
math.min(...)         -- Minimum of arguments
math.max(...)         -- Maximum of arguments
math.floor(x)         -- Round down
math.ceil(x)          -- Round up
math.modf(x)          -- Integer and fractional parts
math.fmod(x, y)       -- Floating-point remainder
```



#### Powers and Roots


```lua
math.sqrt(x)          -- Square root
math.pow(x, y)        -- x^y (or use x^y operator)
math.exp(x)           -- e^x
math.log(x)           -- Natural log
math.log10(x)         -- Base-10 log
math.frexp(x)         -- Mantissa and exponent
math.ldexp(m, e)      -- m * 2^e
```



#### Trigonometry


```lua
math.sin(x)   math.cos(x)   math.tan(x)    -- Radians
math.asin(x)  math.acos(x)  math.atan(x)
math.atan2(y, x)                            -- Arc tangent of y/x
math.sinh(x)  math.cosh(x)  math.tanh(x)   -- Hyperbolic
math.deg(r)   -- Radians to degrees
math.rad(d)   -- Degrees to radians
```



#### Random Numbers


```lua
math.random()         -- Random float [0,1)
math.random(n)        -- Random integer [1,n]
math.random(m, n)     -- Random integer [m,n]
math.randomseed(x)    -- No effect; the generator is auto-seeded
```

`math.random` is nondeterministic. Do not use it for decisions that must replay identically in a workflow; `math.randomseed` cannot make it deterministic.



#### Type Conversion


```lua
math.tointeger(x)     -- Convert to integer or nil
math.type(x)          -- "integer", "float", or nil
math.ult(m, n)        -- Unsigned less-than comparison
```



### Coroutines


The `coroutine` library provides coroutine creation and control. See [Channels and Coroutines](lua/core/channel.md) for channel-based concurrency patterns.

```lua
coroutine.create(fn)        -- Create coroutine from function
coroutine.resume(co, ...)   -- Start/continue coroutine
coroutine.yield(...)        -- Suspend coroutine, return values to resume
coroutine.status(co)        -- "running", "suspended", "normal", "dead"
coroutine.running()         -- Current coroutine (nil if main thread)
coroutine.wrap(fn)          -- Create coroutine as callable function
```



#### Spawning Concurrent Coroutines


Wippy adds `coroutine.spawn` for scheduler-managed concurrent work:

```lua
coroutine.spawn(fn)         -- Spawn function as concurrent coroutine
```

```lua
local time = require("time")

-- Spawn background task
coroutine.spawn(function()
    while true do
        check_health()
        time.sleep("30s")
    end
end)

-- Continue main execution immediately
process_request()
```

This partial pattern assumes the entry lists `time` in `modules:` and provides the `check_health` and `process_request` functions. The spawned coroutine runs concurrently in the same Lua process; `process_request()` is reached immediately, and each health check is followed by a 30-second sleep.



### Error Handling


The global `errors` table creates and classifies structured errors. See [Error Handling](lua/core/errors.md) for the complete API.



#### Constants {id="error-constants"}


```lua
errors.UNKNOWN           -- Unclassified error
errors.INVALID           -- Invalid argument or input
errors.NOT_FOUND         -- Resource not found
errors.ALREADY_EXISTS    -- Resource already exists
errors.PERMISSION_DENIED -- Permission denied
errors.TIMEOUT           -- Operation timed out
errors.CANCELED          -- Operation cancelled
errors.UNAVAILABLE       -- Service unavailable
errors.INTERNAL          -- Internal error
errors.CONFLICT          -- Conflict (e.g., concurrent modification)
errors.RATE_LIMITED      -- Rate limit exceeded
```



#### Functions {id="error-functions"}


```lua
-- Create error from string
local err = errors.new("something went wrong")

-- Create error with metadata
local err = errors.new({
    message = "User not found",
    kind = errors.NOT_FOUND,
    retryable = false,
    details = {user_id = 123}
})

-- Wrap existing error with context
local wrapped = errors.wrap(err, "failed to load profile")

-- Check error kind
if errors.is(err, errors.NOT_FOUND) then
    -- handle not found
end

-- Get call stack from error
local stack = errors.call_stack(err)
```



#### Error Methods


```lua
err:message()    -- Get error message string
err:kind()       -- Get error kind (e.g., "NOT_FOUND")
err:retryable()  -- true, false, or nil (unknown)
err:details()    -- Get details table or nil
err:stack()      -- Get stack trace as string
```



### Restricted Features


The following standard Lua features are unavailable in Wippy processes:

| Feature | Alternative |
|---------|-------------|
| `load`, `loadstring`, `loadfile`, `dofile` | Use [Dynamic Evaluation](lua/dynamic/eval.md) module |
| `collectgarbage` | Automatic GC |
| `rawlen` | Use `#` operator |
| Standard `io.*` file library | Use [File System](lua/storage/filesystem.md) module; the `io` module in Wippy is [Terminal I/O](lua/system/io.md) |
| `os.execute`, `os.exit`, `os.getenv`, `os.remove`, `os.rename`, `os.tmpname` | Use [Command Execution](lua/dynamic/exec.md), [Environment](lua/system/env.md) modules |
| `string.dump` | Not available |
| `debug.*` | Not available |
| `utf8.*` | Not available |
| `package.loadlib` | Native libraries not supported |



### See Also


- [Channels and Coroutines](lua/core/channel.md) - Go-style channels for concurrency
- [Error Handling](lua/core/errors.md) - Creating and handling structured errors
- [OS Time](lua/system/ostime.md) - System time functions



---

# "Errors"

## Errors

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="workflow"/>

The global `errors` table creates and inspects structured errors with categories, details, and retry metadata. It is available without `require`.

This is an API reference. Each code block is an isolated snippet, not a complete entry. Variables such as `err` refer to an error returned or created by surrounding application code; the wrapping example assumes `db` is an application-provided database client.



### Creating Errors


```lua
-- Simple message (kind defaults to UNKNOWN)
local err = errors.new("something went wrong")

-- With kind, retryable, and details
local err = errors.new({
    message = "user not found",
    kind = errors.NOT_FOUND,
    retryable = false,
    details = {user_id = 123}
})
```

`errors.new` accepts either a string message or a table with at least a `message` field. The `(kind, message)` form is not supported.



### Wrapping Errors


Wrap an error to add context while preserving its kind, retry metadata, and details:

```lua
local data, err = db:query("SELECT * FROM users")
if err then
    return nil, errors.wrap(err, "failed to load users")
end
```



### Error Methods


| Method | Returns | Description |
|--------|---------|-------------|
| `err:kind()` | string | Error category |
| `err:message()` | string | Error message |
| `err:retryable()` | boolean/nil | Whether operation can be retried |
| `err:details()` | table/nil | Structured metadata |
| `err:stack()` | string | Lua stack trace |
| `tostring(err)` | string | Full representation |



### Checking Kind


```lua
if errors.is(err, errors.INVALID) then
    -- handle invalid input
end

-- Or compare directly
if err:kind() == errors.NOT_FOUND then
    -- handle missing resource
end
```



### Error Kinds


| Constant | Use Case |
|----------|----------|
| `errors.NOT_FOUND` | Resource doesn't exist |
| `errors.ALREADY_EXISTS` | Resource already exists |
| `errors.INVALID` | Bad input or arguments |
| `errors.PERMISSION_DENIED` | Access denied |
| `errors.UNAVAILABLE` | Service temporarily down |
| `errors.INTERNAL` | Internal error |
| `errors.CANCELED` | Operation was canceled |
| `errors.CONFLICT` | Resource state conflict |
| `errors.TIMEOUT` | Operation timed out |
| `errors.RATE_LIMITED` | Too many requests |
| `errors.UNKNOWN` | Unspecified error |



### Call Stack


Use `errors.call_stack` to inspect a structured call stack:

```lua
local stack = errors.call_stack(err)
if stack then
    print("Thread:", stack.thread)
    for _, frame in ipairs(stack.frames) do
        print(frame.source .. ":" .. frame.line, frame.name)
    end
end
```



### Retryable Errors


Retryability is error metadata, not a property guaranteed by an error kind. Check the value returned by `err:retryable()` rather than inferring it from `err:kind()`. A result of `nil` means the error does not specify whether retrying is appropriate.

```lua
if err:retryable() then
    -- safe to retry
end
```



### Error Details


```lua
local err = errors.new({
    message = "validation failed",
    kind = errors.INVALID,
    details = {
        errors = {
            {field = "email", message = "invalid format"},
            {field = "age", message = "must be positive"}
        }
    }
})

local details = err:details()
for _, e in ipairs(details.errors) do
    print(e.field, e.message)
end
```



---

# "Time & Duration"

## Time & Duration

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="workflow"/>

The `time` module provides time values, durations, time-zone handling, parsing, formatting, sleeps, and timers. Supported workflow time calls are recorded so they can replay deterministically.

This is an API reference. Code blocks are isolated examples or partial scheduling patterns, not a complete entry. Names such as `do_work`, `try_operation`, `make_request`, `send_reminder`, `user_activity`, `check_health`, and `process` represent application callbacks, channels, or data. Where a snippet assigns an error return to `_`, it assumes the shown literal is valid; handle errors when values can come from input or configuration.



### Loading


```lua
local time = require("time")
```

Add `time` to the executable entry's `modules:` list before requiring it. The ambient `channel` and `errors` globals used by scheduling examples need no module declaration.



#### `now`


Returns the current time. In workflows, it returns the recorded workflow time reference so execution can replay deterministically.

```lua
local t = time.now()
print(t:format_rfc3339())  -- "2024-12-29T15:04:05Z"

-- Measure elapsed time
local start = time.now()
do_work()
local elapsed = time.now():sub(start)
print("Took " .. elapsed:milliseconds() .. "ms")
```

The timestamp and elapsed-time output are illustrative; `time.now()` supplies the current or recorded workflow time.

**Returns:** `Time`



#### Create from Components


```lua
-- Create specific date/time in UTC
local t = time.date(2024, time.DECEMBER, 25, 10, 30, 0, 0, time.utc)
print(t:format_rfc3339())  -- "2024-12-25T10:30:00Z"

-- Create in specific timezone
local ny, err = time.load_location("America/New_York")
if err then
    return nil, err
end
local meeting = time.date(2024, time.JANUARY, 15, 14, 0, 0, 0, ny)

-- Defaults to local timezone if not specified
local t = time.date(2024, 1, 15, 12, 0, 0, 0)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `year` | number | Year |
| `month` | number | Month (1-12 or `time.JANUARY` etc) |
| `day` | number | Day of month |
| `hour` | number | Hour (0-23) |
| `minute` | number | Minute (0-59) |
| `second` | number | Second (0-59) |
| `nanosecond` | number | Nanosecond (0-999999999) |
| `location` | Location | Timezone (optional, defaults to local) |

**Returns:** `Time`



#### Create from a Unix Timestamp


```lua
-- From seconds since epoch
local t = time.unix(1703862245, 0)
print(t:utc():format_rfc3339())  -- "2023-12-29T15:04:05Z"

-- With nanoseconds
local t = time.unix(1703862245, 500000000)  -- +500ms

-- Convert JavaScript timestamp (milliseconds)
local js_timestamp = 1703862245000
local t = time.unix(js_timestamp // 1000, (js_timestamp % 1000) * 1000000)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `sec` | number | Unix seconds |
| `nsec` | number | Nanoseconds offset |

**Returns:** `Time`



#### Parse from a String


Parse time strings using Go's reference time format: `Mon Jan 2 15:04:05 MST 2006`.

```lua
-- Parse RFC3339
local t, err = time.parse(time.RFC3339, "2024-12-29T15:04:05Z")
if err then
    return nil, err
end

-- Parse custom format
local t, err = time.parse("2006-01-02", "2024-12-29")
local t, err = time.parse("15:04:05", "14:30:00")
local t, err = time.parse("2006-01-02 15:04:05 MST", "2024-12-29 14:30:00 EST")

-- Parse in specific timezone
local ny, _ = time.load_location("America/New_York")
local t, err = time.parse("2006-01-02 15:04", "2024-12-29 14:30", ny)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `layout` | string | Go time format layout |
| `value` | string | String to parse |
| `location` | Location | Default time zone (optional) |

**Returns:** `Time, error`



#### Arithmetic


```lua
local t = time.now()

-- Add duration (accepts number, string, or Duration)
local tomorrow = t:add("24h")
local later = t:add(5 * time.MINUTE)
local d, _ = time.parse_duration("1h30m")
local future = t:add(d)

-- Subtract time to get duration
local diff = tomorrow:sub(t)  -- returns Duration
print(diff:hours())           -- 24

-- Add calendar units (handles month boundaries correctly)
local next_month = t:add_date(0, 1, 0)   -- add 1 month
local next_year = t:add_date(1, 0, 0)    -- add 1 year
local last_week = t:add_date(0, 0, -7)   -- subtract 7 days
```

| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| `add(duration)` | number/string/Duration | Time | Add duration |
| `sub(time)` | Time | Duration | Difference between times |
| `add_date(years, months, days)` | numbers | Time | Add calendar units |



#### Comparison


```lua
local t1 = time.date(2024, 1, 1, 0, 0, 0, 0, time.utc)
local t2 = time.date(2024, 1, 2, 0, 0, 0, 0, time.utc)

t1:before(t2)   -- true
t2:after(t1)    -- true
t1:equal(t1)    -- true
```

| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| `before(time)` | Time | boolean | Whether this time is before the other value |
| `after(time)` | Time | boolean | Whether this time is after the other value |
| `equal(time)` | Time | boolean | Whether the two values represent the same time |



#### Formatting


```lua
local t = time.now()

t:format_rfc3339()              -- "2024-12-29T15:04:05Z"
t:format(time.DATE_ONLY)        -- "2024-12-29"
t:format(time.TIME_ONLY)        -- "15:04:05"
t:format("Mon Jan 2, 2006")     -- "Sun Dec 29, 2024"
```

| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| `format(layout)` | string | string | Format using Go layout |
| `format_rfc3339()` | - | string | Format as RFC3339 |



#### Unix Timestamps


```lua
local t = time.now()

t:unix()       -- seconds since epoch
t:unix_nano()  -- nanoseconds since epoch
```



#### Components


```lua
local t = time.now()

-- Get date parts
local year, month, day = t:date()

-- Get time parts
local hour, min, sec = t:clock()

-- Individual accessors
t:year()        -- e.g., 2024
t:month()       -- 1-12
t:day()         -- 1-31
t:hour()        -- 0-23
t:minute()      -- 0-59
t:second()      -- 0-59
t:nanosecond()  -- 0-999999999
t:weekday()     -- 0=Sunday .. 6=Saturday
t:year_day()    -- 1-366
t:is_zero()     -- true if zero value
```



#### Time-Zone Conversion


```lua
local t = time.now()

t:utc()                    -- convert to UTC
t:in_local()               -- convert to local timezone
t:in_location(ny)          -- convert to specific timezone
t:location()               -- get current Location
t:location():string()      -- get timezone name
```

| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| `utc()` | - | Time | Convert to UTC |
| `in_local()` | - | Time | Convert to the local time zone |
| `in_location(loc)` | Location | Time | Convert to a specified time zone |
| `location()` | - | Location | Return the current time zone |



#### Rounding


Round or truncate to duration boundaries. **Requires Duration userdata** (not number or string).

```lua
local t = time.now()
local hour_duration, _ = time.parse_duration("1h")
local minute_duration, _ = time.parse_duration("15m")

t:round(hour_duration)       -- round to nearest hour
t:truncate(minute_duration)  -- truncate to 15-minute boundary
```

| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| `round(duration)` | Duration | Time | Round to nearest multiple |
| `truncate(duration)` | Duration | Time | Truncate to multiple |



#### Create a Duration


```lua
-- Parse from string
local d, err = time.parse_duration("1h30m45s")
local d, err = time.parse_duration("500ms")
local d, err = time.parse_duration("2h30m45s500ms")

-- From number (nanoseconds)
local d, err = time.parse_duration(time.SECOND)
local d, err = time.parse_duration(5 * time.MINUTE)

-- Valid units: ns, us, ms, s, m, h
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `value` | number/string/Duration | Duration to parse |

**Returns:** `Duration, error`



#### Duration Methods


```lua
local d, _ = time.parse_duration("1h30m45s500ms")

d:hours()         -- 1.5126...
d:minutes()       -- 90.75...
d:seconds()       -- 5445.5
d:milliseconds()  -- 5445500
d:microseconds()  -- 5445500000
d:nanoseconds()   -- 5445500000000
```



#### Named Locations


Load a time zone by its IANA name, such as `America/New_York`, `Europe/London`, or `Asia/Tokyo`.

```lua
local ny, err = time.load_location("America/New_York")
if err then
    return nil, err
end

local tokyo, _ = time.load_location("Asia/Tokyo")
local london, _ = time.load_location("Europe/London")

-- Convert between timezones
local t = time.now():utc()
print("UTC:", t:format(time.TIME_ONLY))
print("New York:", t:in_location(ny):format(time.TIME_ONLY))
print("Tokyo:", t:in_location(tokyo):format(time.TIME_ONLY))
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | string | IANA time-zone name |

**Returns:** `Location, error`



#### Fixed-Offset Locations


Create a time zone with a fixed UTC offset.

```lua
-- UTC+5:30 (India Standard Time)
local ist = time.fixed_zone("IST", 5*3600 + 30*60)

-- UTC-8 (Pacific Standard Time)
local pst = time.fixed_zone("PST", -8*3600)

local t = time.date(2024, 1, 15, 12, 0, 0, 0, ist)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | string | Zone name |
| `offset` | number | UTC offset in seconds |

**Returns:** `Location`



#### Built-In Locations


```lua
time.utc      -- UTC timezone
time.localtz  -- Local system timezone
```



#### `sleep`


Suspend execution for the specified duration. Workflow execution records the sleep for deterministic replay.

```lua
time.sleep("5s")
time.sleep(500 * time.MILLISECOND)

-- Backoff pattern
for attempt = 1, 3 do
    local ok = try_operation()
    if ok then break end
    time.sleep(tostring(attempt) .. "s")
end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `duration` | number/string/Duration | Sleep time |



#### `after`


Returns a channel that receives one value after the duration. The channel can be used with `channel.select`.

```lua
-- Simple timeout
local timeout, err = time.after("5s")
if err then return nil, err end
timeout:receive()  -- blocks for 5 seconds

-- Timeout with select
local response_ch = make_request()
local timeout_ch, err = time.after("30s")
if err then return nil, err end

local result = channel.select{
    response_ch:case_receive(),
    timeout_ch:case_receive()
}

if result.channel == timeout_ch then
    return nil, errors.new({message = "Request timed out", kind = errors.TIMEOUT})
end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `duration` | number/string/Duration | Time to wait |

**Returns:** `Channel, error`



#### `timer`


Creates a one-shot timer that fires after the specified duration and can be stopped or reset.

```lua
local timer, err = time.timer("5s")
if err then
    return nil, err
end

-- Wait for timer
timer:response():receive()
send_reminder()

-- Reset on activity
local idle_timer, err = time.timer("5m")
if err then
    return nil, err
end
local idle_ch = idle_timer:response()
while true do
    local r = channel.select{
        user_activity:case_receive(),
        idle_ch:case_receive()
    }
    if r.channel == idle_ch then
        logout_user()
        break
    end
    idle_timer:reset("5m")
end

-- Stop timer
timer:stop()
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `duration` | number/string/Duration | Time until fire |

**Returns:** `Timer, error`

| Timer Method | Parameters | Returns | Description |
|--------------|------------|---------|-------------|
| `response()` | - | Channel | Get timer channel |
| `channel()` | - | Channel | Alias for response() |
| `stop()` | - | boolean | Cancel timer |
| `reset(duration)` | number/string/Duration | boolean | Reset with new duration |



#### `ticker`


Creates a repeating timer that fires at regular intervals.

```lua
-- Periodic task
local ticker, err = time.ticker("30s")
if err then
    return nil, err
end
local ch = ticker:response()

while true do
    local tick_time = ch:receive()
    check_health()
end
```

The loop above is intended for a long-running process. A separate finite rate-limiting pattern is:

```lua
-- Rate limiting
local ticker, err = time.ticker("100ms")
if err then
    return nil, err
end
for _, item in ipairs(items) do
    ticker:response():receive()
    process(item)
end
ticker:stop()
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `duration` | number/string/Duration | Interval between ticks |

**Returns:** `Ticker, error`

| Ticker Method | Parameters | Returns | Description |
|---------------|------------|---------|-------------|
| `response()` | - | Channel | Get ticker channel |
| `channel()` | - | Channel | Alias for response() |
| `stop()` | - | boolean | Stop ticker |



#### Duration Units


Duration constants are expressed in nanoseconds and can be combined with arithmetic.

```lua
time.NANOSECOND    -- 1
time.MICROSECOND   -- 1,000
time.MILLISECOND   -- 1,000,000
time.SECOND        -- 1,000,000,000
time.MINUTE        -- 60 * SECOND
time.HOUR          -- 60 * MINUTE

-- Example usage
time.sleep(5 * time.SECOND)
local timeout, err = time.after(30 * time.SECOND)
if err then return nil, err end
```



#### Format Layouts


```lua
time.RFC3339       -- "2006-01-02T15:04:05Z07:00"
time.RFC3339NANO   -- "2006-01-02T15:04:05.999999999Z07:00"
time.RFC822        -- "02 Jan 06 15:04 MST"
time.RFC822Z       -- "02 Jan 06 15:04 -0700"
time.RFC850        -- "Monday, 02-Jan-06 15:04:05 MST"
time.RFC1123       -- "Mon, 02 Jan 2006 15:04:05 MST"
time.RFC1123Z      -- "Mon, 02 Jan 2006 15:04:05 -0700"
time.DATE_TIME     -- "2006-01-02 15:04:05"
time.DATE_ONLY     -- "2006-01-02"
time.TIME_ONLY     -- "15:04:05"
time.KITCHEN       -- "3:04PM"
time.STAMP         -- "Jan _2 15:04:05"
time.STAMP_MILLI   -- "Jan _2 15:04:05.000"
time.STAMP_MICRO   -- "Jan _2 15:04:05.000000"
time.STAMP_NANO    -- "Jan _2 15:04:05.000000000"
```



#### Months


```lua
time.JANUARY    -- 1
time.FEBRUARY   -- 2
time.MARCH      -- 3
time.APRIL      -- 4
time.MAY        -- 5
time.JUNE       -- 6
time.JULY       -- 7
time.AUGUST     -- 8
time.SEPTEMBER  -- 9
time.OCTOBER    -- 10
time.NOVEMBER   -- 11
time.DECEMBER   -- 12
```



#### Weekdays


```lua
time.SUNDAY     -- 0
time.MONDAY     -- 1
time.TUESDAY    -- 2
time.WEDNESDAY  -- 3
time.THURSDAY   -- 4
time.FRIDAY     -- 5
time.SATURDAY   -- 6
```



### Errors


| Condition | Kind | Retryable |
|-----------|------|-----------|
| Invalid duration format | `errors.INVALID` | no |
| Parse failed | `errors.INVALID` | no |
| Empty location name | `errors.INVALID` | no |
| Location not found | `errors.NOT_FOUND` | no |
| Duration <= 0 (timer/ticker) | `errors.INVALID` | no |

```lua
local t, err = time.parse(time.RFC3339, "invalid")
if err then
    if errors.is(err, errors.INVALID) then
        print("Invalid format:", err:message())
    end
    return nil, err
end

local loc, err = time.load_location("Unknown/Zone")
if err then
    if errors.is(err, errors.NOT_FOUND) then
        print("Location not found:", err:message())
    end
    return nil, err
end
```

See [Error Handling](lua/core/errors.md) for working with errors.



---

# "Channels and Coroutines"

## Channels and Coroutines

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="workflow"/>

Channels exchange values between concurrent tasks. They can be buffered or unbuffered and can be combined with `channel.select` to coordinate multiple operations.

This is an API reference. The basic blocks are isolated snippets; the timeout, fan-in, and non-blocking sections are partial patterns whose named channels and callbacks come from the surrounding application. The worker-pool block is a complete in-process example.

The `channel` and `coroutine` globals are always available. Channels coordinate coroutines within one Lua process; use process messaging, functions, or queues across process boundaries.



### Creating Channels


An unbuffered channel (size 0) requires a sender and receiver to be ready before a transfer completes. A buffered channel allows sends to complete while buffer space is available.

```lua
-- Unbuffered: synchronizes sender and receiver
local sync_ch = channel.new()

-- Buffered: queue up to 10 messages
local work_queue = channel.new(10)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `size` | integer | Buffer capacity (default: 0 for unbuffered) |

**Returns:** `channel`



### Sending Values


Sending blocks until a receiver is ready on an unbuffered channel or until buffer space is available on a buffered channel.

```lua
-- Send work to a worker pool
local tasks = {"task-a", "task-b"}
local jobs = channel.new(100)
for i, task in ipairs(tasks) do
    jobs:send(task)  -- Blocks if buffer full
end
jobs:close()  -- Signal no more work
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `value` | any | Value to send |

**Returns:** `boolean`

Sending to a closed channel raises an error.



### Receiving Values


Receiving blocks until a value is available or the channel is closed.

```lua
-- Worker consuming from job queue
while true do
    local job, ok = jobs:receive()
    if not ok then
        break  -- Channel closed, no more work
    end
    process(job)
end
```

Here, `jobs` is the application-provided queue and `process` is its task-processing callback.

**Returns:** `any, boolean`

- `value, true` — a value was received
- `nil, false` — the channel is closed and empty



### Closing Channels


Closing a channel causes pending senders to receive an error and pending receivers to receive `nil, false`. Closing an already closed channel is a no-op.

```lua
local results = channel.new(10)

-- Producer fills results
for _, item in ipairs(data) do
    results:send(process(item))
end
results:close()  -- Signal completion
```

This isolated producer snippet assumes `data` and the `process` callback are provided by the application.



### Selecting from Multiple Channels


`channel.select` waits on multiple channel operations at the same time. It can coordinate event sources, timeouts, and non-blocking checks.

```lua
local result = channel.select(cases)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `cases` | table | Array of select cases |
| `default` | boolean | If true, returns immediately when no case ready |

**Returns:** `table`

- For a channel case: `{channel, value, ok}` — `channel` is the case's channel, `value` is the received/sent value, `ok` is false for a closed-channel receive.
- For the default branch (when no case is ready and `default = true`): `{default = true, ok = true}`.



#### Timeout Pattern


Use `time.after()` to add a timeout to a channel wait.

```lua
local time = require("time")

local result_ch = application_response_channel
local timeout, err = time.after("5s")
if err then
    return nil, err
end

local r = channel.select {
    result_ch:case_receive(),
    timeout:case_receive()
}

if r.channel == timeout then
    return nil, errors.new({ kind = errors.TIMEOUT, message = "Operation timed out" })
end
return r.value
```

This partial pattern assumes the entry lists `time` in `modules:` and the application supplies `application_response_channel`. `time.after` returns one channel on success; invalid or non-positive durations return `nil, error`.



#### Fan-in Pattern


Handle values from multiple sources in one loop.

This process-entry pattern uses ambient `process`, while the application supplies the shutdown signal and the two handler functions.

```lua
local events = process.events()
local inbox = process.inbox()
local shutdown = channel.new()

while true do
    local r = channel.select {
        events:case_receive(),
        inbox:case_receive(),
        shutdown:case_receive()
    }

    if r.channel == shutdown then
        break
    elseif r.channel == events then
        handle_event(r.value)
    else
        handle_message(r.value)
    end
end
```



#### Non-Blocking Check


Use a default case to check for available data without blocking.

In this isolated pattern, `ch` and the `process` callback come from the application.

```lua
local r = channel.select {
    ch:case_receive(),
    default = true
}

if r.default then
    -- Nothing available, do something else
elseif not r.ok then
    -- The channel is closed
else
    process(r.value)
end
```



### Creating Select Cases


Create send and receive cases for `channel.select`:

```lua
-- Send case - completes when channel can accept value
ch:case_send(value)

-- Receive case - completes when value available
ch:case_receive()
```

Values in the cases table that are not send or receive cases are ignored. Make sure the table contains at least one valid case unless it also has a default branch.



### Worker Pool Pattern


```lua
local items = {1, 2, 3, 4}
local num_workers = 2

local function process_item(item)
    return item * 2
end

local work = channel.new(#items)
local results = channel.new(#items)

-- Spawn workers
for _ = 1, num_workers do
    coroutine.spawn(function()
        while true do
            local item, ok = work:receive()
            if not ok then
                return
            end
            results:send(process_item(item))
        end
    end)
end

-- Feed work
for _, item in ipairs(items) do
    work:send(item)
end
work:close()

-- Collect results
local processed = {}
while #processed < #items do
    local result, ok = results:receive()
    if not ok then break end
    table.insert(processed, result)
end
```

After the loop, `processed` contains `2`, `4`, `6`, and `8`; result order depends on coroutine scheduling. The workers share channels because they are coroutines in the same Lua process.



### Errors


| Condition | Kind | Retryable |
|-----------|------|-----------|
| Send on closed channel | runtime error | no |
| `cases` argument to select is not a table | runtime error | no |



### See Also


- [Process Management](lua/core/process.md) - Process spawning and communication
- [Message Queue](lua/storage/queue.md) - Queue-based messaging
- [Functions](lua/core/funcs.md) - Function invocation



---

# "Process Management"

## Process Management

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="workflow"/>
<secondary-label ref="permissions"/>

The `process` global provides process spawning, messaging, monitoring, linking, naming, and lifecycle control.

It is available without `require()` and does not need to be listed in `modules:`.

This is an API reference. Its call-form blocks use placeholders such as `id`, `host`, `destination`, `topic`, and `name` for values supplied by application code; they are not standalone programs. Calls shown with an `err` result return their documented value on success or a failure sentinel plus `error`; the sentinel is normally `nil`, while `process.set_options` returns `false`. Application control flow should handle the error.



### Process Information


Read the current frame ID or process ID:

```lua
local frame_id, err = process.id()  -- Registry ID of the current function, process, or workflow definition
if err then return nil, err end

local pid, err = process.pid()      -- Process ID
if err then return nil, err end
```



### Sending Messages


Send one or more payload values to a process by PID or registered name:

```lua
local ok, err = process.send(destination, topic, ...)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `destination` | string | PID or registered name |
| `topic` | string | Topic name (cannot start with `@`) |
| `...` | any | Payload values |

**Permission:** `process.send` on target PID



### Spawning Processes


```lua
-- Basic spawn
local pid, err = process.spawn(id, host, ...)

-- With monitoring (receive EXIT events)
local pid, err = process.spawn_monitored(id, host, ...)

-- With linking (receive LINK_DOWN on abnormal exit)
local pid, err = process.spawn_linked(id, host, ...)

-- Both linked and monitored
local pid, err = process.spawn_linked_monitored(id, host, ...)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | string | Process source ID (e.g., `"app.workers:handler"`) |
| `host` | string | Host ID (e.g., `"app:processes"`) |
| `...` | any | Arguments passed to spawned process |

All variants require `process.spawn` on the process ID. The monitored variants also require `process.spawn.monitored`, and the linked variants require `process.spawn.linked`. At runtime v0.3.32a, only the module-level `spawn()` checks `process.host` on the host ID; the specialized module-level variants do not perform that host permission check.



### Process Control


```lua
-- Forcefully terminate a process
local ok, err = process.terminate(destination)

-- Request graceful cancellation with an optional reason
local ok, err = process.cancel(destination, "shutting down")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `destination` | string | PID or registered name |
| `reason` | string | Optional reason delivered to the target |

**Permissions:** `process.terminate`, `process.cancel` on target PID



### Monitoring and Linking


Add or remove monitoring and links for an existing process:

```lua
-- Monitoring: receive EXIT events when target exits
local ok, err = process.monitor(destination)
local ok, err = process.unmonitor(destination)

-- Linking: bidirectional, receive LINK_DOWN on abnormal exit
local ok, err = process.link(destination)
local ok, err = process.unlink(destination)
```

**Permissions:** `process.monitor`, `process.unmonitor`, `process.link`, `process.unlink` on target PID



### Process Options


```lua
local options = process.get_options()
local ok, err = process.set_options({trap_links = true})
```

| Field | Type | Description |
|-------|------|-------------|
| `trap_links` | boolean | Whether LINK_DOWN events are delivered to events channel |
| `upgradable` | boolean | Opt in to OUTDATED events when the process's code is invalidated |



### Inbox and Events


Use the inbox and event channels to receive messages and lifecycle events:

```lua
local inbox = process.inbox()    -- Message objects from @inbox topic
local events = process.events()  -- Lifecycle events from @events topic
```



#### Event Types


| Constant | Description |
|----------|-------------|
| `process.event.CANCEL` | Cancellation requested |
| `process.event.EXIT` | Monitored process exited |
| `process.event.LINK_DOWN` | Linked process terminated abnormally |
| `process.event.OUTDATED` | The process's code or an imported dependency changed in the registry |



#### Event Fields


| Field | Type | Description |
|-------|------|-------------|
| `kind` | string | Event type constant |
| `from` | string | Source PID (absent for OUTDATED) |
| `result` | table | For EXIT/LINK_DOWN: a {value, error} record; the process return value is at `result.value` and any error at `result.error` |
| `reason` | string | For CANCEL: why the process is being cancelled |
| `sources` | string[] | For OUTDATED: registry IDs that changed or were transitively affected |

`OUTDATED` is delivered only to processes that opt in with `process.set_options({upgradable = true})`. Multiple invalidations are combined into one pending event containing the union of their `sources`. Handle the event by calling [`process.upgrade`](#process-upgrade).



### Topic Subscription


Subscribe to a custom message topic:

```lua
local ch, err = process.listen(topic, options)
if err then return nil, err end

local ok, err = process.unlisten(ch)
if err then return nil, err end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `topic` | string | Topic name (cannot start with `@`) |
| `options.message` | boolean | If true, receive Message objects; if false, raw payloads |



### Message Objects


The inbox and listeners configured with `{message = true}` return message objects:

```lua
local msg = inbox:receive()

msg:topic()            -- string: topic name
msg:from()             -- string: sender PID (empty string when unknown)
msg:payload()          -- Payload: wrapper (call :data() to extract); nil when empty, table of wrappers for several values
msg:payload():data()   -- any: actual payload value
```



### Synchronous Call


`process.exec` spawns a process and waits for its result:

```lua
local result, err = process.exec(id, host, ...)
```

**Permissions:** `process.exec` on process id, `process.host` on host id



### Process Upgrade


Upgrade the current process while preserving its PID:

The two snippets below are alternative call forms, not sequential operations.

```lua
-- Upgrade to new version, passing state
process.upgrade(id, ...)
```

```lua
-- Keep same definition, re-run with new state
process.upgrade(nil, preserved_state)
```

`process.upgrade` is a terminal control transfer: it clears the current execution and starts the requested definition with the same PID. Code after the call does not run in the old execution.



### Context Spawner


Create a spawner that supplies custom context to child processes:

```lua
local spawner = process.with_context({request_id = "123"})
```

**Permission:** `process.context` on "context"



#### Spawner with Options


`process.with_options(options)` creates a spawner with spawn-time options, such as a network selector, rather than context values:

```lua
local spawner = process.with_options({network = "app:tor_proxy"})
```

| Option | Type | Description |
|--------|------|-------------|
| `network` | string | Registry ID of a `network.*` entry to use for the child's outbound connections |
| `terminal` | string | Viewport grant that attaches a virtual terminal to the child |

**Permission:** `process.context` on "context"; selecting a network additionally requires `network.select` on that network ID.



#### Terminal Attachment


A `terminal` grant comes from `viewport:grant()` and gives the child a terminal port of its own, so it can use the [TTY](lua/system/tty.md) module exactly as it would on a terminal host:

```lua
local view = assert(tty.viewport({width = 80, height = 24}))
local child = assert(process.with_options({terminal = assert(view:grant())})
    :spawn_monitored("app:child", "app:workers"))
```

The grant is one-shot and is consumed at admission: a rejected start leaves it unresolved and reusable, a child that resolves the port consumes it permanently, and a host that does not support terminal attachments rejects the spawn rather than dropping the option. The spawning process keeps reading the child's frames through the viewport it created. See [Terminal](system/terminal.md#composable-terminals).



#### SpawnBuilder Methods


`SpawnBuilder` is immutable; each configuration method returns a new instance:

```lua
spawner:with_context(values)      -- Add context values
spawner:with_actor(actor)         -- Set security actor
spawner:with_scope(scope)         -- Set security scope
spawner:with_name(name)           -- Register name at start; if taken, spawn returns the existing PID and queued messages go to it
spawner:with_message(topic, ...)  -- Queue message to send after spawn
spawner:with_options(options)     -- Merge spawn-time options (e.g. network)
```

**Permission:** `process.security` on "security" for `:with_actor()` and `:with_scope()`



#### Spawner Spawn Methods


```lua
spawner:spawn(id, host, ...)
spawner:spawn_monitored(id, host, ...)
spawner:spawn_linked(id, host, ...)
spawner:spawn_linked_monitored(id, host, ...)
```

All `SpawnBuilder` spawn methods require `process.host` on the host ID in addition to the applicable `process.spawn`, `process.spawn.monitored`, and `process.spawn.linked` permissions.



#### Spawner Exec


```lua
local result, err = spawner:exec(id, host, ...)
```

This method runs the target process synchronously with the builder's context, actor, and scope, then returns its result. A deferred worker can use `with_actor` and `with_scope` to execute with an owner's identity.

**Permissions:** `process.exec` on process id, `process.host` on host id



### Name Registry


Register a process under a name so callers can use the name instead of its PID. Functions that accept a `destination`, including `send`, `terminate`, `cancel`, `monitor`, and `link`, also accept registered names.

```lua
local ok, err = process.registry.register(name)               -- self, local scope
local pid, err = process.registry.lookup(name)
local ok, err = process.registry.unregister(name)
```



#### Scope


The optional `scope` argument selects the name's consistency guarantee and defaults to `LOCAL`. See the [Cluster Guide](guides/cluster.md#naming-and-name-scopes) for the complete model.

| Constant | Visibility | Guarantee |
|----------|------------|-----------|
| `process.registry.LOCAL` | this node only | Instant, node-local |
| `process.registry.EVENTUAL` | cluster-wide | Eventually consistent (gossip) |
| `process.registry.CONSISTENT` | cluster-wide | Linearizable singleton (Raft) |
| `process.registry.STRONG` | cluster-wide | Consistent + every live node acknowledges |

On a standalone node, only `LOCAL` is available; cluster scopes require [clustering](guides/cluster.md).



#### register


```lua
local ok, err = process.registry.register(name, pid, scope)
```

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `name` | string | yes | | Name to register |
| `pid` | string | no | self | PID to register; defaults to the calling process |
| `scope` | number | no | `LOCAL` | One of the scope constants above |

Returns `true` on success, or `nil, error` on failure. Conflicts (name already registered to a different PID) return `errors.ALREADY_EXISTS`. Registering the same name to the same PID is idempotent. A `STRONG` registration blocks until every live node acknowledges or the reservation deadline expires; on timeout it returns an error.

Registering on behalf of a different PID additionally requires the `process.registry.foreign` permission on the target PID.



#### lookup


```lua
local pid, err = process.registry.lookup(name)
```

Returns the registered PID string, or `nil, error` with kind `errors.NOT_FOUND` when the name is not registered.



#### unregister


```lua
local ok, err = process.registry.unregister(name, scope)
```

`scope` defaults to `LOCAL` and must match the scope the name was registered under. For `CONSISTENT` and `STRONG`, the owning process is the one allowed to unregister; unregistering a name owned by another PID returns `false`. Names also release automatically when the owning process exits (and, for cluster scopes, when its node leaves), so explicit unregister is for early release.



### Permissions


Permission checks evaluate the caller's security actor against the target resource.



#### Policy Evaluation


Policies can allow or deny an operation based on:

- **Actor**: The security principal making the request
- **Action**: The operation being performed (e.g., `process.send`)
- **Resource**: The target (PID, process id, host id, or name)
- **Attributes**: Additional context including `pid` (caller's process ID)



#### Permission Reference


| Permission | Functions | Resource |
|------------|-----------|----------|
| `process.spawn` | `spawn*()` | process id |
| `process.spawn.monitored` | `spawn_monitored()`, `spawn_linked_monitored()` | process id |
| `process.spawn.linked` | `spawn_linked()`, `spawn_linked_monitored()` | process id |
| `process.host` | module-level `spawn()`, all `SpawnBuilder` spawn methods, `exec()` | host id |
| `process.send` | `send()` | target PID |
| `process.exec` | `exec()` | process id |
| `process.terminate` | `terminate()` | target PID |
| `process.cancel` | `cancel()` | target PID |
| `process.monitor` | `monitor()` | target PID |
| `process.unmonitor` | `unmonitor()` | target PID |
| `process.link` | `link()` | target PID |
| `process.unlink` | `unlink()` | target PID |
| `process.context` | `with_context()`, `with_options()` | "context" |
| `process.security` | `:with_actor()`, `:with_scope()` | "security" |
| `process.registry.register` | `registry.register()` | name |
| `process.registry.unregister` | `registry.unregister()` | name |
| `process.registry.foreign` | `registry.register()` | target PID |

Cluster name scopes are authorized by scope-suffixed variants of these actions (`process.registry.register.eventual`, `.consistent`, `.strong`, and the matching `unregister` actions), so a policy can grant local naming separately from cluster-wide naming.



#### Multiple Permissions


Some operations require multiple permissions:

| Operation | Required Permissions |
|-----------|---------------------|
| `spawn()` | `process.spawn` + `process.host` |
| module-level `spawn_monitored()` | `process.spawn` + `process.spawn.monitored` |
| module-level `spawn_linked()` | `process.spawn` + `process.spawn.linked` |
| module-level `spawn_linked_monitored()` | `process.spawn` + `process.spawn.monitored` + `process.spawn.linked` |
| `SpawnBuilder:spawn()` | `process.spawn` + `process.host` |
| `SpawnBuilder:spawn_monitored()` | `process.spawn` + `process.spawn.monitored` + `process.host` |
| `SpawnBuilder:spawn_linked()` | `process.spawn` + `process.spawn.linked` + `process.host` |
| `SpawnBuilder:spawn_linked_monitored()` | `process.spawn` + `process.spawn.monitored` + `process.spawn.linked` + `process.host` |
| `exec()` | `process.exec` + `process.host` |
| spawn with custom actor/scope | spawn permissions + `process.security` |



### Errors


| Condition | Kind |
|-----------|------|
| No context found | `errors.INTERNAL` |
| Frame context not found | `errors.INTERNAL` |
| Missing required arguments | `errors.INVALID` |
| Reserved topic prefix (`@`) | `errors.INVALID` |
| Destination is neither a PID nor a registered name | `errors.NOT_FOUND` |
| Name not registered | `errors.NOT_FOUND` |
| Permission denied | `errors.PERMISSION_DENIED` |
| Name already registered | `errors.ALREADY_EXISTS` |

See [Error Handling](lua/core/errors.md) for working with errors.



### See Also


- [Channels](lua/core/channel.md) - In-process coroutine coordination
- [Message Queue](lua/storage/queue.md) - Queue-based messaging
- [Functions](lua/core/funcs.md) - Function invocation
- [Supervision](guides/supervision.md) - Process lifecycle management
- [Cluster](guides/cluster.md) - Name scopes and cluster-wide naming



---

# "Process Groups"

## Process Groups

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="permissions"/>

Process groups organize processes under dynamic names and broadcast messages to group members across the cluster. A process can join multiple groups, and cluster-wide membership is eventually consistent.

This is an API reference. Its snippets assume an existing `pg.scope`, an executable entry running with process context, and policies that authorize the documented operations. The blocks demonstrate individual calls or partial subscription flows rather than a standalone application.

For the scope entry kind and its configuration, see [Process Groups](system/process-groups.md). For the broader clustering model, see the [Cluster Guide](guides/cluster.md).



### Loading


```lua
local pg = require("pg")
```

Add `pg` to the executable entry's `modules:` list before requiring it.



### Opening a Scope


A process group belongs to a **scope**, represented by a `pg.scope` registry entry. Open the scope to obtain an instance for group operations:

```lua
local group, err = pg.open("app:pg")
if err then
    return nil, err
end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | string | Scope entry ID (format: `"namespace:name"`) |

**Returns:** `pg.Instance, error`

**Permission:** `pg.open` on the scope `id`

The instance is released automatically during execution-frame cleanup. Call `release()` to release it earlier. Other operations are methods on the instance and use `:` syntax.



### Joining and Leaving


The calls below are independent forms; choose the single-group or batch join needed by the application and pair it with the corresponding leave operations.

```lua
local ok, err = group:join("workers")           -- single group
if err then return nil, err end
```

```lua
local ok, err = group:join({"workers", "all"})  -- batch
if err then return nil, err end
```

```lua
local ok, err = group:leave("workers")
if err then return nil, err end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `group` | string \| string[] | Group name, or a list of names for a batch operation |

**Returns:** `boolean, error`

A process can join the same group more than once and must leave the same number of times to depart fully. For a batch, `leave` is best-effort and returns an error only when the process was not a member of any named group.

**Permissions:** `pg.join` / `pg.leave` on each group name



### Listing Members


```lua
local members, err = group:get_members("workers")        -- all nodes
if err then return nil, err end

local local_members, err = group:get_local_members("workers")  -- this node only
if err then return nil, err end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `group` | string | Group name |

**Returns:** `string[], error` — an array of PID strings (empty for an unknown group)

**Permissions:** `pg.get_members` / `pg.get_local_members` on the group name



### Listing Groups


```lua
local groups, err = group:which_groups()         -- all groups in the cluster
if err then return nil, err end

local local_groups, err = group:which_local_groups()  -- groups with a local member
if err then return nil, err end
```

**Returns:** `string[], error` — group names that currently have at least one member

**Permissions:** `pg.which_groups` / `pg.which_local_groups`



### Broadcasting


Broadcast sends a message from the calling process to every group member under `topic`. Members receive it with `process.listen(topic)`.

```lua
local ok, err = group:broadcast("workers", "task", {id = 42})   -- all nodes
if err then return nil, err end

ok, err = group:broadcast_local("workers", "task", {id = 42})  -- this node only
if err then return nil, err end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `group` | string | Target group |
| `topic` | string | Message topic |
| `...` | any | Zero or more payload values |

**Returns:** `boolean, error`

**Permissions:** `pg.broadcast` / `pg.broadcast_local` on the group name



### Monitoring a Group


`monitor` subscribes to join and leave events for one group and returns an atomic snapshot of its current members. No membership change can occur between the snapshot and subscription setup without being observed.

```lua
local sub, members, err = group:monitor("workers")
if err then
    return nil, err
end

for _, pid in ipairs(members) do
    -- current members at subscription time
end

local ch = sub:channel()
local event, open = ch:receive()  -- {kind = "member.joined" | "member.left", path = "workers", data = {...}}
if not open then
    return nil, errors.new("Process-group subscription closed")
end

sub:close()  -- unsubscribe; sub:close({flush = true}) drains queued events first
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `group` | string | Group to watch |

**Returns:** `pg.Subscription, string[], error` — the subscription and a snapshot of current members

**Permission:** `pg.monitor` on the group name



### Watching All Groups


`events` subscribes to membership changes for every group in the scope and returns a snapshot mapping groups to their members.

```lua
local sub, snapshot, err = group:events()
if err then
    return nil, err
end
-- snapshot: { ["workers"] = {pid, ...}, ["all"] = {pid, ...} }

local event, open = sub:channel():receive()
if not open then
    return nil, errors.new("Process-group subscription closed")
end
sub:close()
```

**Returns:** `pg.Subscription, table, error`

**Permission:** `pg.events`



#### Event Fields


Events delivered on a subscription channel carry:

| Field | Type | Description |
|-------|------|-------------|
| `system` | string | Always `"pg"` |
| `kind` | string | `"member.joined"` or `"member.left"` |
| `path` | string | The group name |
| `data` | table | `{Group = string, PIDs = string[]}` — the affected members |

Subscription channels are buffered (capacity 64). If a slow consumer fills the buffer, further events are retained in the process mailbox in order and delivered once the consumer drains the channel (the subscription stalls rather than dropping events).



### Releasing


```lua
group:release()
```

`release` frees the instance immediately and is idempotent. After release, every other group operation returns an error. Cleanup also runs automatically at the end of the execution frame.

**Returns:** `boolean`



### Permissions


| Permission | Method | Resource |
|------------|--------|----------|
| `pg.open` | `pg.open()` | scope id |
| `pg.join` | `join()` | group name |
| `pg.leave` | `leave()` | group name |
| `pg.get_members` | `get_members()` | group name |
| `pg.get_local_members` | `get_local_members()` | group name |
| `pg.which_groups` | `which_groups()` | (none) |
| `pg.which_local_groups` | `which_local_groups()` | (none) |
| `pg.broadcast` | `broadcast()` | group name |
| `pg.broadcast_local` | `broadcast_local()` | group name |
| `pg.monitor` | `monitor()` | group name |
| `pg.events` | `events()` | (none) |



### Errors


| Condition | Kind |
|-----------|------|
| Permission denied | `errors.PERMISSION_DENIED` |
| Missing or empty argument | `errors.INVALID` |
| Scope not found | `errors.INTERNAL` |
| Leave a group with no membership | `errors.NOT_FOUND` |
| Instance released | `errors.INVALID` |
| Group/member or action-queue limit reached | `errors.RATE_LIMITED` (retryable) |
| Service stopped, backpressure, or open circuit | `errors.UNAVAILABLE` |
| Broadcast timed out | `errors.TIMEOUT` (retryable) |

See [Error Handling](lua/core/errors.md) for working with errors.



### See Also


- [Process Groups](system/process-groups.md) - Scope entry kind and configuration
- [Cluster](guides/cluster.md) - Membership, naming, and the clustering model
- [Process Management](lua/core/process.md) - Spawning and messaging individual processes



---

# "Function Invocation"

## Function Invocation

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="workflow"/>

The `funcs` module calls registered functions synchronously or asynchronously. An executor can propagate request context, security identity, and implementation-specific call options. This page is an API reference; target IDs, arguments, and application data represent surrounding code.



### Loading


```lua
local funcs = require("funcs")
```



### `call`


Calls a registered function synchronously and waits for its result.

```lua
local result, err = funcs.call("app.api:get_user", user_id)
if err then
    return nil, err
end
print(result.name)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `target` | string | Function ID in format "namespace:name" |
| `...args` | any | Arguments passed to the function |

**Returns:** `result, error`

The target uses the `namespace:name` format.



### `async`


Starts a function call and returns a `Future` immediately. Futures allow other work to continue while the call runs and support multiple concurrent calls.

```lua
-- Start heavy computation without blocking
local future, err = funcs.async("app.process:analyze_data", large_dataset)
if err then
    return nil, err
end

-- Do other work while computation runs...

-- Wait for result when ready
local ch = future:response()
local _, open = ch:receive()
if not open then
    return nil, errors.new("future response channel closed")
end

local payload, result_err = future:result()
if result_err then
    return nil, result_err
end
local result, data_err = payload:data()
if data_err then return nil, data_err end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `target` | string | Function ID in format "namespace:name" |
| `...args` | any | Arguments passed to the function |

**Returns:** `Future, error`



### `new`


Creates an `Executor` for calls that need custom context, security identity, or call options.

```lua
local exec = funcs.new()
```

**Returns:** `Executor`



### Executor


An executor stores call context and options. Its configuration methods return new executor instances, allowing a base configuration to be reused.



#### `with_context`


Adds request-scoped values that will be available to the called function, such as trace IDs, session data, or feature flags.

```lua
local ctx = require("ctx")

-- Propagate request context to downstream services
local request_id, ctx_err = ctx.get("request_id")
if ctx_err then return nil, ctx_err end

local exec, err = funcs.new():with_context({
    request_id = request_id,
    feature_flags = {dark_mode = true}
})
if err then return nil, err end

local user, err = exec:call("app.api:get_user", user_id)
if err then return nil, err end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `values` | table | Key-value pairs to add to context |

**Returns:** `Executor, error`



#### `with_actor`


Sets the security actor used for authorization checks in the called function.

```lua
local security = require("security")
local actor = security.actor()  -- Get current user's actor

-- Call admin function with user's credentials
local exec, err = funcs.new():with_actor(actor)
if err then return nil, err end
local result, err = exec:call("app.admin:delete_record", record_id)
if err and err:kind() == errors.PERMISSION_DENIED then
    return nil, errors.new({kind = errors.PERMISSION_DENIED, message = "User cannot delete records"})
end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `actor` | Actor | Security actor (from security module) |

**Returns:** `Executor, error`



#### `with_scope`


Sets the security scope for called functions. The scope defines the permissions available to the call.

```lua
local security = require("security")
local scope = security.new_scope()

local exec, err = funcs.new():with_scope(scope)
if err then return nil, err end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `scope` | Scope | Security scope (from security module) |

**Returns:** `Executor, error`



#### `with_options`


Sets call options such as the retry policy or the overlay network. Options are merged over any preset options of the target function entry.

```lua
-- Retry transient failures up to 5 times with exponential backoff
local exec = funcs.new():with_options({
    retry = { max_attempts = 5, initial_delay = 100 }
})
local result, err = exec:call("app.external:fetch_data", query)
if err then
    -- All attempts failed, or the error was not retryable
end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `options` | table | Call options |

| Option | Type | Description |
|--------|------|-------------|
| `retry.max_attempts` | int | Maximum attempts including the first (1 disables retry) |
| `retry.initial_delay` | int/duration | Delay before first retry (ms or duration string), default `100` |
| `retry.max_delay` | int/duration | Upper bound for the backoff delay (ms or duration string), default `10s` |
| `retry.backoff_factor` | number | Multiplier applied to the delay after each attempt, default `2.0` |
| `retry.jitter` | number | Random jitter fraction applied to each delay, default `0.1` |
| `retry.retry_kinds` | string[] | Only retry errors of these kinds; by default every kind except `Invalid`, `PermissionDenied` and `Internal` is retried |
| `retry.skip_kinds` | string[] | Never retry errors of these kinds |
| `network` | string | Registry ID of an overlay network to route the call's outbound traffic through; requires the `network.select` permission |

Only retryable errors trigger retries; non-retryable errors surface immediately. Temporal activity options are described in [Activities](temporal/activities.md).

The runtime-defined option is:

| Recognized option | Type | Description |
|-------------------|------|-------------|
| `network` | string | Registry ID of the outbound `network.*` entry |

**Returns:** `Executor, error`

Selecting a network requires `network.select` permission on that network ID.



#### `call` and `async`


The executor versions of `call` and `async` use its configured context and options.

```lua
-- Build reusable executor with context
local exec = funcs.new()
    :with_context({trace_id = "abc-123"})
    :with_options({retry = {max_attempts = 3}})

-- Make multiple calls with same context
local users, users_err = exec:call("app.api:list_users")
if users_err then return nil, users_err end
local posts, posts_err = exec:call("app.api:list_posts")
if posts_err then return nil, posts_err end
```



### Future Invocation Summary


`async()` returns a future representing an in-progress invocation. The methods below cover the caller-facing steps for receiving, inspecting, or canceling that invocation. See [Future](./future.md) for the Future object reference.



#### `response` and `channel`


Returns the channel used to receive the result.

```lua
local time = require("time")

local future, err = funcs.async("app.api:slow_operation", data)
if err then
    return nil, err
end
local ch = future:response()  -- or future:channel()

local timeout, err = time.after("5s")
if err then
    return nil, err
end

local result = channel.select {
    ch:case_receive(),
    timeout:case_receive()
}
```

**Returns:** `Channel`

The response channel signals completion. After it becomes ready, call `future:result()` to obtain the cached value or the called function's error.



#### `is_complete`


Checks whether the future has completed without blocking.

```lua
while not future:is_complete() do
    -- do other work
    local _, sleep_err = time.sleep("100ms")
    if sleep_err then return nil, sleep_err end
end
local result, err = future:result()
```

**Returns:** `boolean`



#### `is_canceled`


Returns `true` if the future has been marked canceled by its provider. See the cancellation limitation below.

```lua
if future:is_canceled() then
    print("Operation was canceled")
end
```

**Returns:** `boolean`



#### `result`


Returns the cached result when complete or `nil` while the operation is pending.

```lua
local value, err = future:result()
if err then
    print("Failed:", err:message())
elseif value then
    local data, data_err = value:data()
    if data_err then return nil, data_err end
    print("Got:", data)
end
```

**Returns:** `Payload|table|nil, error|nil`



#### `error`


Returns the operation error when the future has failed.

```lua
local err, has_error = future:error()
if has_error then
    print("Error kind:", err:kind())
end
```

**Returns:** `error|nil, boolean`

This method returns a non-retryable `INTERNAL` wrapper for a failed operation. Use `result()` to preserve the called function's original error metadata.



#### `cancel`


Requests cancellation of the asynchronous operation.

```lua
local canceled, err = future:cancel()
if err then return nil, err end
```

**Returns:** `boolean, error`

<warning>
In runtime v0.3.32a, function and contract futures share one process-global cancellation callback. When both providers are loaded, <code>cancel()</code> and <code>is_canceled()</code> are not a stable cross-provider contract. Do not use cancellation for application correctness; time out locally and ignore a late result until the runtime separates provider cancellation.
</warning>



### Parallel Operations


Combine `async` with `channel.select` to run and collect multiple calls concurrently.

```lua
-- Start multiple operations in parallel
local f1, err = funcs.async("app.api:get_user", user_id)
if err then return nil, err end
local f2, err = funcs.async("app.api:get_orders", user_id)
if err then return nil, err end
local f3, err = funcs.async("app.api:get_preferences", user_id)
if err then return nil, err end

-- Wait for all to complete using channels
local user_ch = f1:channel()
local orders_ch = f2:channel()
local prefs_ch = f3:channel()

local pending = {
    [user_ch] = {name = "user", future = f1},
    [orders_ch] = {name = "orders", future = f2},
    [prefs_ch] = {name = "preferences", future = f3}
}
local results = {}
while next(pending) do
    local cases = {}
    for ch in pairs(pending) do
        cases[#cases + 1] = ch:case_receive()
    end

    local r = channel.select(cases)
    local completed = pending[r.channel]
    pending[r.channel] = nil

    local payload, result_err = completed.future:result()
    if result_err then
        return nil, result_err
    end
    local data, data_err = payload:data()
    if data_err then
        return nil, data_err
    end
    results[completed.name] = data
end
```



### Permissions


Function operations are subject to security policy evaluation.

| Action | Resource | Description |
|--------|----------|-------------|
| `funcs.call` | Function ID | Call a specific function |
| `funcs.context` | `context` | Use `with_context()` to set custom context |
| `funcs.security` | `security` | Use `with_actor()` or `with_scope()` |
| `network.select` | Network ID | Use `with_options({network = ...})` to select an overlay network |



### Errors


| Condition | Kind | Retryable |
|-----------|------|-----------|
| Target empty | `errors.INVALID` | no |
| Namespace missing | `errors.INVALID` | no |
| Name missing | `errors.INVALID` | no |
| Permission denied | `errors.PERMISSION_DENIED` | no |
| Async outside a process | `errors.INTERNAL` | no |
| Subscribe failed | `errors.INTERNAL` | no |
| Async start dispatch failed | `errors.INTERNAL` | no |
| Function error | varies | varies |

See [Error Handling](lua/core/errors.md) for working with errors.



---

# "Futures"

## Futures

<secondary-label ref="function"/>
<secondary-label ref="process"/>

Futures represent asynchronous operation results. They are returned by `funcs.async()` and asynchronous contract calls. This page is an API reference; the target IDs and arguments in its patterns are application-defined.



### Loading


Futures are not loaded as a module; asynchronous operations create them:

```lua
local funcs = require("funcs")
local future, err = funcs.async("app.compute:task", data)
if err then
    return nil, err
end
```



### Response Channel


Use the response channel to wait for completion, then read the cached result from the future:

```lua
local ch = future:response()
local _, open = ch:receive()
if not open then
    return nil, errors.new("future response channel closed")
end

local payload, err = future:result()
if err then
    return nil, err
end
local result, data_err = payload:data()
if data_err then return nil, data_err end
```

`channel()` is an alias for `response()`.

The channel value is the operation's payload, payload table, or error. Calling `result()` after the channel becomes ready provides one consistent success/error interface and returns the cached value even after the channel is drained.



### Completion Check


Check whether the future has completed without blocking:

```lua
if future:is_complete() then
    local result, err = future:result()
end
```



### Cancellation Check


Check whether the future has been marked canceled by its provider:

```lua
if future:is_canceled() then
    print("Operation was canceled")
end
```



### Getting Result


Read the cached result without blocking:

```lua
local val, err = future:result()
```

**Returns:**

- Not complete: `nil, nil`
- Canceled: `nil, error` (kind `CANCELED`)
- Error: `nil, error`
- Success: `Payload, nil` or `table, nil` (multiple payloads)



### Getting Error


Read the error when the future has failed:

```lua
local err, has_error = future:error()
if has_error then
    print("Failed:", err:message())
end
```

**Returns:** `error, boolean`

When an operation fails, `error()` returns a non-retryable `INTERNAL` wrapper. Use `result()` when the called function's original error kind and retryability must be preserved.



### Canceling


Request cancellation of the asynchronous operation on a best-effort basis:

```lua
local canceled, err = future:cancel()
```

**Returns:** `boolean, error`

Operation may still complete if already in progress.



### Timeout Pattern


```lua
local time = require("time")

local future, err = funcs.async("app.compute:slow", data)
if err then
    return nil, err
end

local timeout, err = time.after("5s")
if err then
    return nil, err
end

local r = channel.select {
    future:channel():case_receive(),
    timeout:case_receive()
}

if r.channel == timeout then
    future:cancel()
    return nil, errors.new({ kind = errors.TIMEOUT, message = "Operation timed out" })
end

local payload, result_err = future:result()
if result_err then
    return nil, result_err
end
local value, data_err = payload:data()
if data_err then return nil, data_err end
return value
```



### First-to-Complete


```lua
local f1, err = funcs.async("app.cache:get", key)
if err then
    return nil, err
end
local f2, err = funcs.async("app.db:get", key)
if err then
    return nil, err
end

local ch1 = f1:channel()
local ch2 = f2:channel()

local r = channel.select {
    ch1:case_receive(),
    ch2:case_receive()
}

-- The slower operation may still complete; this caller ignores its result.
local winner
if r.channel == ch1 then
    winner = f1
else
    winner = f2
end

local payload, result_err = winner:result()
if result_err then
    return nil, result_err
end
local value, data_err = payload:data()
if data_err then return nil, data_err end
return value
```



### Errors


| Condition | Kind |
|-----------|------|
| Operation canceled | `CANCELED` |
| Async operation failed | `result()` preserves the operation's kind; `error()` reports `INTERNAL` |



---

# "Streams"

## Streams

<secondary-label ref="function"/>
<secondary-label ref="process"/>

Streams provide incremental I/O for HTTP, filesystem, and other modules. The modules that own the underlying data create stream objects. This page is an API reference; the scanner loop uses an application-defined `process(token)` callback.



### Obtaining a Stream


```lua
-- From HTTP request body
local stream, err = req:stream()
if err then return nil, err end

-- From filesystem
local fs = require("fs")
local volume, err = fs.get("app:data")
if err then return nil, err end

local stream, err = volume:open("/file.txt", "r")
if err then return nil, err end
```



### Reading


```lua
local chunk, err = stream:read(size)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `size` | integer | Bytes to read (0 = default 32KB chunk) |

**Returns:** `string, error` — `nil, nil` on EOF



### Writing


```lua
local bytes, err = stream:write(data)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | Data to write |

**Returns:** `integer, error` — bytes written



### Seeking


```lua
local pos, err = stream:seek(whence, offset)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `whence` | string | `"set"`, `"cur"`, or `"end"` |
| `offset` | integer | Offset in bytes |

**Returns:** `integer, error` — new position



### Flushing


```lua
local ok, err = stream:flush()
```

`flush` writes buffered data to the underlying destination.



### Stream Information


```lua
local info, err = stream:stat()
```

| Field | Type | Description |
|-------|------|-------------|
| `size` | integer | Total size (-1 if unknown) |
| `position` | integer | Current position |
| `readable` | boolean | Can read |
| `writable` | boolean | Can write |
| `seekable` | boolean | Can seek |



### Closing


```lua
local ok, err = stream:close()
```

`close` releases the stream's resources and can be called more than once.



### Scanner


Create a scanner that tokenizes stream content:

```lua
local scanner, err = stream:scanner(split)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `split` | string | `"lines"`, `"words"`, `"bytes"`, `"runes"` |



#### Scanner Methods


```lua
local has_more, err = scanner:scan()  -- advance to next token
local token = scanner:text()           -- current token
local err_msg = scanner:err()          -- scanner error if any
```

```lua
while true do
    local has_token, err = scanner:scan()
    if err then return nil, err end
    if not has_token then
        local scan_err = scanner:err()
        if scan_err then return nil, scan_err end  -- raw scanner error string
        break  -- clean EOF
    end
    process(scanner:text())
end
```

When `scan()` returns `false`, check `scanner:err()` before treating the result
as EOF. Tokenization and underlying read failures are stored on the scanner and
do not appear in `scan()`'s second return value.



### Errors


| Condition | Kind |
|-----------|------|
| Invalid whence/split type | raised as a Lua error (not returned) |
| Stream closed | `INTERNAL` |
| Not readable/writable | `INTERNAL` |
| Read/write failure | `INTERNAL` |



---

# "Request Context"

## Request Context

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="workflow"/>

The `ctx` module reads request-scoped values propagated through [function calls](lua/core/funcs.md) or [process operations](lua/core/process.md). This page is an API reference; the snippets show individual calls inside an executable Lua entry.



### Loading


```lua
local ctx = require("ctx")
```



#### Get a Value


```lua
local value, err = ctx.get("key")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `key` | string | Context key |

**Returns:** `any, error`



#### Get All Values


```lua
local values, err = ctx.all()
```

**Returns:** `table, error`

`ctx.all()` returns an empty table when an execution context is present but has no request values. A missing execution context returns `nil, errors.INTERNAL`.



### Errors


| Condition | Kind | Retryable |
|-----------|------|-----------|
| Empty key | `errors.INVALID` | no |
| Key not found | `errors.NOT_FOUND` | no |
| No execution context available | `errors.INTERNAL` | no |

See [Error Handling](lua/core/errors.md) for working with errors.



---

# "Event Bus"

## Event Bus

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="permissions"/>

The event bus publishes runtime and application activity for monitoring, logging, metrics, and reactive side effects. This page is an API reference; the snippets assume an executable Lua entry with the listed module and permissions.

<note>
The event bus is a best-effort publish/subscribe channel, not a reliable transport. Do not depend on it for business-critical delivery. Use process messaging (`process.send`), channels, or the [message queue](lua/storage/queue.md) when delivery is part of application correctness.
</note>



### Loading


```lua
local events = require("events")
```



### Subscribing to Events


Subscribe to one system or a system pattern, with an optional event-kind filter:

```lua
-- Subscribe to all order events
local sub, err = events.subscribe("orders.*")
if err then
    return nil, err
end

-- Process events
local ch = sub:channel()
while true do
    local evt, ok = ch:receive()
    if not ok then break end

    print(evt.system, evt.kind, evt.path)
    -- Process evt.data when the publisher supplied a payload.
end
```

Pass a second argument to restrict delivery to one kind, for example
`events.subscribe("users", "user.created")`. An omitted kind accepts every
kind from the matching system.

| Parameter | Type | Description |
|-----------|------|-------------|
| `system` | string | System pattern (supports wildcards like "test.*") |
| `kind` | string | Event kind filter (optional) |

**Returns:** `Subscription, error`



### Publishing Events


Publish an event to the event bus:

```lua
-- Send order created event
local ok, err = events.send("orders", "order.created", "/orders/123", {
    order_id = "123",
    customer_id = "456",
    total = 99.99
})
if err then
    return nil, err
end

-- Send without data
local heartbeat_sent, heartbeat_err = events.send("system", "heartbeat", "/health")
if heartbeat_err then
    return nil, heartbeat_err
end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `system` | string | System identifier |
| `kind` | string | Event kind/type |
| `path` | string | Event path for routing |
| `data` | any | Event payload (optional) |

**Returns:** `boolean, error`

A successful return confirms that the runtime accepted the send. It does not
confirm that any subscriber received or processed the event.



#### Receive Channel


Use the subscription channel to receive events:

```lua
local json = require("json")
local ch = sub:channel()

local evt, ok = ch:receive()
if ok then
    print("System:", evt.system)
    print("Kind:", evt.kind)
    print("Path:", evt.path)
    local encoded, encode_err = json.encode(evt.data)
    if encode_err then return nil, encode_err end
    print("Data:", encoded)
end
```

Each event contains `system`, `kind`, and `path`. The `data` field is present
only when the publisher supplied a non-nil payload.



#### Close a Subscription


Close the subscription to unsubscribe and close its channel:

```lua
local closed = sub:close() -- true
```

Closing is idempotent. After the channel is closed, `receive()` returns
`nil, false` once buffered events are drained.



### Permissions


| Action | Resource | Description |
|--------|----------|-------------|
| `events.subscribe` | system | Subscribe to events from a system |
| `events.send` | system | Send events to a system |



### Errors


| Condition | Kind | Retryable |
|-----------|------|-----------|
| Empty system | `errors.INVALID` | no |
| Empty send kind | `errors.INVALID` | no |
| Empty path | `errors.INVALID` | no |
| Policy denied | `errors.INVALID` | no |
| Missing execution or process context | `errors.INTERNAL` | no |

See [Error Handling](lua/core/errors.md) for working with errors.



---

# "Entry Registry"

## Entry Registry

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="permissions"/>

Query and modify registered entries. Access metadata, snapshots, and version history.



### Loading


```lua
local registry = require("registry")
```



### Entry Structure


```lua
{
    id = "app.lib:assert",     -- string: "namespace:name"
    kind = "function.lua",     -- string: entry type
    meta = {type = "test"},    -- table: searchable metadata
    data = {...}               -- any: entry payload
}
```

Entries read back from `registry.get`, `registry.find`, `snap:entries()`, `snap:get()`, `snap:namespace()` and `snap:find()` carry only these four author-facing fields.

`dependency_root` is a write-side field accepted by `changes:create()` and `changes:update()`. It is a boolean that marks an `ns.dependency` entry as a deployment root. It is never returned by the entry APIs; registry-owned state is read through [`snap:state()`](lua/core/registry.md#snapshot-state).



### Get Entry


```lua
local entry, err = registry.get("app.lib:assert")
```

**Permission:** `registry.get` on entry ID



### Find Entries


```lua
local entries, err = registry.find({[".kind"] = "function.lua"})
local entries, err = registry.find({[".kind"] = "http.endpoint", [".ns"] = "app.api"})
```

Keys prefixed with `.` match entry fields (`.kind`, `.ns`, `.name`, `.id`) and accept `*` globs. Keys prefixed with `meta.` match entry metadata; a leading `~`, `*`, `^` or `$` on a `meta.` key selects regex, contains, prefix or suffix matching. Keys with neither prefix are ignored.



### Parse ID


```lua
local id = registry.parse_id("app.lib:assert")
-- id.ns = "app.lib", id.name = "assert"
```



### Snapshots


Point-in-time view of the registry:

```lua
local snap, err = registry.snapshot()           -- current state
local snap, err = registry.snapshot_at(5)       -- at version 5
```



#### Snapshot Methods


| Method | Returns | Description |
|--------|---------|-------------|
| `snap:entries()` | `Entry[], error` | All accessible entries |
| `snap:state()` | `State, error` | Entries with registry-owned metadata, plus the resolved module graph |
| `snap:get(id)` | `Entry, error` | Single entry by ID |
| `snap:find(filter)` | `Entry[]` | Filter entries |
| `snap:namespace(ns)` | `Entry[]` | Entries in namespace |
| `snap:version()` | `Version` | Snapshot version |
| `snap:changes()` | `Changes` | Create changeset |



#### Snapshot State


`snap:state()` returns the entry state together with the module graph selected for the snapshot version. Registry-owned provenance is carried on each entry rather than merged into `meta`, so it cannot be confused with authored metadata.

```lua
local snap, err = registry.snapshot()
local state, err = snap:state()

for _, entry in ipairs(state.entries) do
    print(entry.id, entry.registry.owner, entry.registry.root)
end

if state.resolution then
    print(state.resolution.digest, state.resolution.input_digest)
    for _, module in ipairs(state.resolution.modules) do
        print(module.name, module.version)
    end
end
```

Each entry in `state.entries` has the four author-facing fields plus:

- `registry.owner` - deployment source that supplied the entry
- `registry.root` - `true` when the entry is a dependency declaration selected by the deployment

`state.resolution` describes the module graph of a `registry.snapshot()` view. It is absent on snapshots that carry no graph of their own, including `registry.snapshot_at()` and overlay snapshots:

| Field | Type | Description |
|-------|------|-------------|
| `digest` | string | Content digest of the complete immutable selection |
| `input_digest` | string | Digest of the declared root set |
| `baseline_digest` | string | Digest of the deployment baseline the graph was solved against; omitted when unbound |
| `roots` | array | Authored dependency declarations used as solver inputs |
| `references` | array | Root-shaped declarations folded into an existing root for the same component; omitted when empty |
| `modules` | array | Selected modules |

`roots` and `references` entries have `id`, `component` and `version`. `modules` entries have `name` and `version`, plus `version_id`, `source`, `digest`, `size_bytes` and `protected` when set.



### Versions


```lua
local version, err = registry.current_version()
local versions, err = registry.versions()

print(version:id())       -- numeric ID
print(version:string())   -- display string
local prev = version:previous()  -- previous version or nil
local next = version:next()      -- next version or nil
```



### History


```lua
local hist, err = registry.history()
local versions, err = hist:versions()
local version, err = hist:get_version(5)
local snap, err = hist:snapshot_at(version)
```



### Changesets


Build and apply modifications:

```lua
local snap, err = registry.snapshot()
local changes = snap:changes()

changes:create({
    id = "test:new_entry",
    kind = "test.kind",
    meta = {type = "test"},
    data = {config = "value"}
})

changes:update({
    id = "test:existing",
    kind = "test.kind",
    meta = {updated = true},
    data = {new_value = true}
})

changes:delete("test:old_entry")

local new_version, err = changes:apply()
```

**Permission:** `registry.apply` for `changes:apply()`



#### Deleting Entries


`changes:delete()` accepts an ID string, a table with an `id` string, a table with `ns` and `name` strings, or an array of any of those. Arrays may nest, and duplicate IDs collapse into a single delete operation.

```lua
changes:delete("test:old_entry")
changes:delete({id = "test:old_entry"})
changes:delete({ns = "test", name = "old_entry"})
changes:delete({"test:a", {ns = "test", name = "b"}, {"test:c"}})
```

An empty list, a table that references itself, and a value that is neither a string nor a table are rejected with `errors.INVALID`.



#### Changes Methods


| Method | Description |
|--------|-------------|
| `changes:create(entry)` | Add create operation |
| `changes:update(entry)` | Add update operation |
| `changes:delete(id)` | Add delete operation |
| `changes:ops()` | Get pending operations |
| `changes:apply()` | Apply changes, returns new Version |



### Apply Version


Roll back or forward to a specific version:

```lua
local prev = current_version:previous()
local ok, err = registry.apply_version(prev)
```

**Permission:** `registry.apply_version`



### Build Delta


Compute operations to transition between states:

```lua
local from = {{id = "test:a", kind = "test", meta = {}, data = {}}}
local to = {{id = "test:b", kind = "test", meta = {}, data = {}}}

local ops, err = registry.build_delta(from, to)
for _, op in ipairs(ops) do
    print(op.kind, op.entry.id)  -- "entry.create", "entry.update", "entry.delete"
end
```



### Overlays


An overlay is a process-local set of registry entries owned by a logical identity. Overlay entries take part in ordinary topology and handler transitions, so services start and stop for them exactly as for durable entries, but they never advance registry history and never appear in a version. They exist only in the running process and are empty after a cold boot, so the owning control service reconciles them on startup.

```lua
local snap, err = registry.overlay("data-sources:crm")
```

**Returns:** `Snapshot, error`

The snapshot exposes the owner's overlay entries through the usual methods and reports the current registry version from `snap:version()`. It also captures the overlay generation at the moment it is opened, which is what makes writes safe.

```lua
local snap, err = registry.overlay("data-sources:crm")
if err then return nil, err end

local changes = snap:changes()
changes:create({
    id = "data.crm:connection",
    kind = "registry.entry",
    meta = {},
    data = {endpoint = "https://crm.internal"}
})

local version, err = changes:apply()
```

`changes:apply()` on an overlay snapshot writes the overlay and returns the current registry version. No history version is created, so the returned version is unchanged unless a durable change happened concurrently.



#### Concurrency


Each overlay carries a generation counter that increases on every successful apply. `changes:apply()` succeeds only if the generation still matches the one captured when the snapshot was opened. A concurrent apply to the same overlay fails with `errors.CONFLICT` marked retryable: reopen the overlay and rebuild the changeset.

```lua
local last_err
for _ = 1, 3 do
    local snap, err = registry.overlay("data-sources:crm")
    if err then return nil, err end

    local _, apply_err = snap:changes():delete("data.crm:connection"):apply()
    if not apply_err then return true end
    if not apply_err:retryable() then return nil, apply_err end
    last_err = apply_err
end
return nil, last_err
```



#### Restrictions


- The owner string is required and must not be blank.
- A changeset must be non-empty and must not name the same entry twice.
- `create` fails when the ID already exists in durable state or in any overlay.
- `update` and `delete` only work on entries this owner created; any other ID fails with `errors.NOT_FOUND`.
- Overlay entries cannot set `dependency_root` or any other registry-owned metadata.
- Overlay entries cannot use kinds owned by a registry directive, such as `ns.dependency`.
- A delete that removes an entry a surviving entry depends on is rejected.
- Dependencies cannot cross overlay owner boundaries, and durable entries cannot depend on overlay entries.

The rest surface as `errors.CONFLICT` or `errors.INVALID`, and none are retryable: only the generation mismatch above is.

**Permissions:** `registry.overlay.get` on the owner to open and read, `registry.overlay.apply` on the owner to write, and `registry.overlay.<create|update|delete>.<kind>` on each entry ID in the changeset.



### Permissions


| Permission | Resource | Description |
|------------|----------|-------------|
| `registry.get` | entry ID | Read entry (also filters find/entries results) |
| `registry.apply` | - | Apply changeset |
| `registry.apply_version` | - | Apply/rollback version |
| `registry.overlay.get` | owner ID | Open and read an overlay snapshot |
| `registry.overlay.apply` | owner ID | Apply an overlay changeset |
| `registry.overlay.create.<kind>` | entry ID | Create an overlay entry of that kind |
| `registry.overlay.update.<kind>` | entry ID | Update an overlay entry of that kind |
| `registry.overlay.delete.<kind>` | entry ID | Delete an overlay entry of that kind |



### Errors


| Condition | Kind |
|-----------|------|
| Entry not found | `errors.NOT_FOUND` |
| Version not found | `errors.NOT_FOUND` |
| Permission denied | `errors.PERMISSION_DENIED` |
| Invalid parameter | `errors.INVALID` |
| No changes to apply | `errors.INVALID` |
| Overlay changed during apply | `errors.CONFLICT` (retryable) |
| Overlay entry owned elsewhere or conflicts with durable state | `errors.CONFLICT` |
| Registry not available | `errors.INTERNAL` |

See [Error Handling](lua/core/errors.md) for working with errors.



---

# "Contracts"

## Contracts

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="workflow"/>
<secondary-label ref="permissions"/>

The `contract` module opens typed service bindings for remote APIs, workflows, and functions. Contracts support schema validation, asynchronous calls, and call-context propagation. This page is an API reference; IDs and values such as `current_user` represent application-owned entries and surrounding handler state.



### Loading


```lua
local contract = require("contract")
```



### Opening a Binding


Open a binding by its registry ID:

```lua
local greeter, err = contract.open("app.services:greeter")
if err then
    return nil, err
end

local result, err = greeter:say_hello("Alice")
if err then
    return nil, err
end
```

Bindings can also receive scope values, query parameters, or call options:

```lua
-- With scope table
local svc, err = contract.open("app.services:user", {
    tenant_id = "acme",
    region = "us-east"
})

-- With query parameters (auto-converted: "true"→bool, numbers→int/float)
local api, err = contract.open("app.services:api?debug=true&timeout=5000")

-- With call options (third argument)
local inst, err = contract.open("app.services:flaky", nil, {
    retry = { max_attempts = 5, initial_delay = 100 }
})
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `binding_id` | string | Binding ID; query parameters are supported |
| `scope` | table | Context values (optional, overrides query params) |
| `options` | table | Call options (optional) — e.g. `retry.max_attempts`, `retry.initial_delay` |

**Returns:** `Instance, error`



### Getting a Contract


Retrieve a contract definition for introspection:

```lua
local c, err = contract.get("app.services:greeter")
if err then
    return nil, err
end

print(c:id())  -- "app.services:greeter"

local methods = c:methods()
for _, m in ipairs(methods) do
    print(m.name, m.description)
end

local method, err = c:method("say_hello")
if err then
    return nil, err
end
```



#### Method Definition


| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Method name |
| `description` | string | Method description |
| `input_schemas` | table[] | Input schema definitions (absent when the method declares none) |
| `output_schemas` | table[] | Output schema definitions (absent when the method declares none) |



### Finding Implementations


List the bindings that implement a contract:

```lua
local bindings, err = contract.find_implementations("app.services:greeter")
if err then
    return nil, err
end

for _, binding_id in ipairs(bindings) do
    print(binding_id)
end
```

The same lookup is available on a contract object:

```lua
local c, err = contract.get("app.services:greeter")
if err then
    return nil, err
end
local bindings, err = c:implementations()
if err then
    return nil, err
end
```



### Checking Implementation


Check whether an already opened instance implements a contract:

```lua
if contract.is(instance, "app.services:greeter") then
    instance:say_hello("World")
end
```



### Calling Methods


A synchronous method call blocks until it completes:

```lua
local calc, err = contract.open("app.services:calculator")
if err then
    return nil, err
end

local sum, err = calc:add(10, 20)
if err then
    return nil, err
end
local product, err = calc:multiply(5, 6)
if err then
    return nil, err
end
```



### Async Calls


Append `_async` to a method name to start it asynchronously:

```lua
local processor, err = contract.open("app.services:processor")
if err then
    return nil, err
end

local future, err = processor:process_async(large_dataset)
if err then
    return nil, err
end

-- Do other work...

-- Wait for result
local ch = future:response()
local _, open = ch:receive()
if not open then
    return nil, errors.new("future response channel closed")
end

local payload, result_err = future:result()
if result_err then return nil, result_err end
local result, data_err = payload:data()
if data_err then return nil, data_err end
```

See [Futures](lua/core/future.md) for future methods.



### Opening via Contract


Open a binding through a contract object. The calls below are alternatives; check the error returned by `contract.get()` and by the selected `open()` call before using the instance.

```lua
local c, err = contract.get("app.services:user")
if err then
    return nil, err
end

-- Default binding
local instance, err = c:open()

-- Specific binding
local instance, err = c:open("app.services:user_impl")

-- With scope
local instance, err = c:open(nil, {user_id = 123})
local instance, err = c:open("app.services:user_impl", {user_id = 123})
```



### Adding Context


Create a wrapper with preconfigured context values:

```lua
local ctx = require("ctx")
local c, err = contract.get("app.services:user")
if err then return nil, err end

local request_id, ctx_err = ctx.get("request_id")
if ctx_err then return nil, ctx_err end

local wrapped, err = c:with_context({
    request_id = request_id,
    user_id = current_user.id
})
if err then return nil, err end

local instance, err = wrapped:open()
```



### Call Options


Use `with_options` to configure retries and other call behavior:

```lua
local c, err = contract.get("app.services:flaky")
if err then return nil, err end

local configured = c:with_options({
    retry = { max_attempts = 5, initial_delay = 100 }
})
local inst, err = configured:open("app.services:flaky_impl")
if err then return nil, err end

local result, err = inst:call()
```

Options apply to every method call on the returned instance. Only retryable errors trigger retries; non-retryable errors return immediately. `with_options` can be chained with `with_context`, `with_actor`, and `with_scope`.

| Option | Type | Description |
|--------|------|-------------|
| `retry.max_attempts` | int | Maximum attempts including the first (1 disables retry) |
| `retry.initial_delay` | int/duration | Delay before first retry (ms or duration string), default `100` |
| `retry.max_delay` | int/duration | Upper bound for the backoff delay (ms or duration string), default `10s` |
| `retry.backoff_factor` | number | Multiplier applied to the delay after each attempt, default `2.0` |
| `retry.jitter` | number | Random jitter fraction applied to each delay, default `0.1` |
| `retry.retry_kinds` | string[] | Only retry errors of these kinds; by default every kind except `Invalid`, `PermissionDenied` and `Internal` is retried |
| `retry.skip_kinds` | string[] | Never retry errors of these kinds |



### Security Context


Set the actor and scope used for authorization:

```lua
local security = require("security")
local c, err = contract.get("app.services:admin")
if err then return nil, err end

local secured, err = c:with_actor(security.actor())
if err then return nil, err end

secured, err = secured:with_scope(security.scope())
if err then return nil, err end

local admin, err = secured:open()
if err then return nil, err end
```

Without explicit `with_actor`/`with_scope`, an opened contract inherits the caller's ambient actor and scope. When set, they propagate to the bound implementation functions — every method call on the instance executes under that identity.



### Permissions


| Permission | Resource | Functions |
|------------|----------|-----------|
| `contract.get` | contract id | `get()` |
| `contract.open` | binding id | `open()`, `Contract:open()` |
| `contract.implementations` | contract id | `find_implementations()`, `Contract:implementations()` |
| `contract.call` | method name | sync and async method calls |
| `contract.context` | "context" | `Contract:with_context()` |
| `contract.security` | "security" | `Contract:with_actor()`, `Contract:with_scope()` |



### Errors


| Condition | Kind |
|-----------|------|
| Invalid binding ID format | `errors.INVALID` |
| Contract not found | `errors.NOT_FOUND` |
| Binding not found | `errors.NOT_FOUND` |
| Method not found | `errors.NOT_FOUND` |
| No default binding | `errors.NOT_FOUND` |
| Permission denied | `errors.PERMISSION_DENIED` |
| Call failed | kind of the implementation's error (preserved); `errors.INTERNAL` for dispatch failures |



---

# "JSON Encoding"

## JSON Encoding

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="workflow"/>
<secondary-label ref="encoding"/>

The `json` module encodes Lua values as JSON, decodes JSON strings, and validates data with JSON Schema.

This is an API reference. Short expression examples show successful return values; examples that consume the result capture the optional second `error` return.



### Loading


```lua
local json = require("json")
```

Add `json` to the executable entry's `modules:` list before requiring it.



#### `encode`


Encode a Lua value as a JSON string:

```lua
-- Simple values
json.encode("hello")        -- '"hello"'
json.encode(42)             -- '42'
json.encode(true)           -- 'true'
json.encode(nil)            -- 'null'

-- Arrays (sequential numeric keys)
json.encode({1, 2, 3})      -- '[1,2,3]'
json.encode({"a", "b"})     -- '["a","b"]'

-- Objects (string keys)
local user = {name = "Alice", age = 30}
json.encode(user)           -- JSON object with name="Alice" and age=30; member order is unspecified

-- Nested structures
local order = {
    id = "ord-123",
    items = {
        {sku = "ABC", qty = 2},
        {sku = "XYZ", qty = 1}
    },
    total = 99.50
}
json.encode(order)
-- Structurally equivalent JSON; object-member order is unspecified
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `value` | any | Lua value to encode |

**Returns:** `string, error`

Encoding follows these rules:

- `nil` becomes `null`
- Empty tables become `[]` (or `{}` if created with string keys)
- Tables with sequential 1-based keys become arrays
- Tables with string keys become objects
- Mixed numeric and string keys cause an error
- Sparse arrays (gaps in indices) cause an error
- Inf/NaN numbers become `null`
- Recursive table references cause an error
- Maximum nesting depth is 128 levels



#### `decode`


Decode a JSON string into a Lua value:

```lua
-- Parse object
local user, err = json.decode('{"name":"Bob","active":true}')
if err then
    return nil, err
end
print(user.name)    -- "Bob"
print(user.active)  -- true

-- Parse array
local items, items_err = json.decode('[10, 20, 30]')
if items_err then return nil, items_err end
print(items[1])     -- 10
print(#items)       -- 3

-- Parse nested data
local response, response_err = json.decode([[
{
    "status": "ok",
    "data": {
        "users": [
            {"id": 1, "name": "Alice"},
            {"id": 2, "name": "Bob"}
        ]
    }
}
]])
if response_err then return nil, response_err end
print(response.data.users[1].name)  -- "Alice"

-- Handle errors
local data, err = json.decode("not valid json")
if err then
    print(err:kind())     -- "Internal" (errors.INTERNAL)
    print(err:message())  -- parse error details
end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `str` | string | JSON string to decode |

**Returns:** `any, error`



#### `validate`


Validate a Lua value against a JSON Schema:

```lua
-- Define a schema
local user_schema = {
    type = "object",
    properties = {
        name = {type = "string", minLength = 1},
        email = {type = "string", format = "email"},
        age = {type = "integer", minimum = 0, maximum = 150}
    },
    required = {"name", "email"}
}

-- Valid data passes
local valid, err = json.validate(user_schema, {
    name = "Alice",
    email = "alice@example.com",
    age = 30
})
if err then return nil, err end
print(valid)  -- true

-- Invalid data fails with details
local valid, err = json.validate(user_schema, {
    name = "",
    email = "not-an-email"
})
if not valid then
    print(err:message())  -- validation error details
end

-- Schema can also be a JSON string
local schema_json = '{"type":"number","minimum":0}'
local valid, schema_err = json.validate(schema_json, 42)
if schema_err then return nil, schema_err end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `schema` | table or string | JSON Schema definition |
| `data` | any | Value to validate |

**Returns:** `boolean, error`

Schemas are cached by content hash for performance.



#### `validate_string`


Validate a JSON string against a schema without first returning a decoded value:

```lua
local schema = {
    type = "object",
    properties = {
        action = {type = "string", enum = {"create", "update", "delete"}}
    },
    required = {"action"}
}

-- Validate raw JSON from request body
local body = '{"action":"create","data":{}}'
local valid, err = json.validate_string(schema, body)
if not valid then
    return nil, errors.new("Invalid request: " .. err:message()):kind(errors.INVALID)
end

-- Now safe to decode
local request, decode_err = json.decode(body)
if decode_err then return nil, decode_err end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `schema` | table or string | JSON Schema definition |
| `json_str` | string | JSON string to validate |

**Returns:** `boolean, error`



### Errors


| Condition | Kind | Retryable |
|-----------|------|-----------|
| Recursive table reference | `errors.INTERNAL` | no |
| Sparse array (gaps in indices) | `errors.INTERNAL` | no |
| Mixed key types in table | `errors.INTERNAL` | no |
| Nesting exceeds 128 levels | `errors.INTERNAL` | no |
| Invalid JSON syntax | `errors.INTERNAL` | no |
| Input not a string or empty string (decode) | `errors.INVALID` | no |
| Schema compilation failed | `errors.INVALID` | no |
| Validation failed | `errors.INVALID` | no |

See [Error Handling](lua/core/errors.md) for working with errors.



---

# "YAML Encoding"

## YAML Encoding

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="workflow"/>
<secondary-label ref="encoding"/>

The `yaml` module serializes Lua tables as YAML and parses YAML documents into Lua values.

This is an API reference. Output-only expressions illustrate successful encoding; examples that consume a value capture the optional second `error` return.



### Loading


```lua
local yaml = require("yaml")
```

Add `yaml` to the executable entry's `modules:` list before requiring it.



#### `encode`


Encode a Lua table as YAML:

```lua
-- Simple key-value
local config = {
    name = "myapp",
    port = 8080,
    debug = true
}
local out, err = yaml.encode(config)
if err then return nil, err end
-- YAML mapping containing name, port, and debug.

-- Arrays become YAML lists
local items = {"apple", "banana", "cherry"}
yaml.encode(items)
-- - apple
-- - banana
-- - cherry

-- Nested structures
local server = {
    http = {
        address = ":8080",
        timeout = "30s"
    },
    database = {
        host = "localhost",
        port = 5432
    }
}
yaml.encode(server)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | table | Lua table to encode |
| `options` | table? | Optional encoding options |



##### Options


| Field | Type | Description |
|-------|------|-------------|
| `field_order` | string[] | Custom field order; listed fields appear in this order |
| `sort_unordered` | boolean | Sort fields not in `field_order` alphabetically |

```lua
-- Control field order in output
local entry = {
    zebra = 1,
    alpha = 2,
    name = "test",
    kind = "demo"
}

-- Fields appear in specified order, remaining sorted alphabetically
local result, encode_err = yaml.encode(entry, {
    field_order = {"name", "kind"},
    sort_unordered = true
})
if encode_err then return nil, encode_err end
-- name: test
-- kind: demo
-- alpha: 2
-- zebra: 1

-- Just sort all fields alphabetically
yaml.encode(entry, {sort_unordered = true})
-- alpha: 2
-- kind: demo
-- name: test
-- zebra: 1
```

**Returns:** `string, error`



#### `decode`


Parse a YAML string into a Lua value:

```lua
-- Parse configuration
local config, err = yaml.decode([[
server:
  host: localhost
  port: 8080
features:
  - auth
  - logging
  - metrics
]])
if err then
    return nil, err
end

print(config.server.host)     -- "localhost"
print(config.server.port)     -- 8080
print(config.features[1])     -- "auth"

-- Parse from file content
local content = fs.get("app:config"):readfile("config.yaml")
local settings, err = yaml.decode(content)
if err then
    return nil, errors.wrap(err, "invalid config file")
end

-- Handle mixed types
local data, data_err = yaml.decode([[
name: test
count: 42
ratio: 3.14
enabled: true
tags:
  - lua
  - wippy
]])
if data_err then return nil, data_err end
print(type(data.count))    -- "number"
print(type(data.enabled))  -- "boolean"
print(type(data.tags))     -- "table"
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | YAML string to parse |

**Returns:** `any, error` — the value type depends on the YAML content



### Errors


| Condition | Kind | Retryable |
|-----------|------|-----------|
| Input not a table (encode) | `errors.INVALID` | no |
| Input not a string (decode) | `errors.INVALID` | no |
| Empty string (decode) | `errors.INVALID` | no |
| Invalid YAML syntax | `errors.INTERNAL` | no |

See [Error Handling](lua/core/errors.md) for working with errors.



---

# "Base64 Encoding"

## Base64 Encoding

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="workflow"/>
<secondary-label ref="encoding"/>

The `base64` module encodes strings and binary data using standard RFC 4648 Base64 and decodes them back to bytes.

This is an API reference. Output-only expressions show successful values; filesystem and transport examples check the optional second `error` return before consuming data. Names such as `username`, `password`, `encoded_image`, and `user_input` are application-supplied strings.

Base64 is an encoding, not encryption or authentication. Do not use it to conceal secrets or to verify that data has not been modified. Send Basic authentication credentials only over TLS and obtain them from application-owned secret storage rather than literals.



### Loading


```lua
local base64 = require("base64")
```

Add `base64` to the executable entry's `modules:` list before requiring it. Filesystem and JSON examples also require `fs` and `json` respectively.



#### `encode`


Encodes a string, including binary data, as Base64.

```lua
-- Encode text
local encoded, err = base64.encode("Hello, World!")
if err then return nil, err end
print(encoded)  -- "SGVsbG8sIFdvcmxkIQ=="

-- Encode binary data (e.g., from file)
local image_data = fs.get("app:data"):readfile("photo.jpg")
local image_b64 = base64.encode(image_data)

-- Encode JSON for transport
local json = require("json")
local payload, json_err = json.encode({user = "alice", action = "login"})
if json_err then return nil, json_err end
local token_part, token_err = base64.encode(payload)
if token_err then return nil, token_err end

-- Encode credentials
local credentials, credentials_err = base64.encode(username .. ":" .. password)
if credentials_err then return nil, credentials_err end
local auth_header = "Basic " .. credentials
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | Data to encode (text or binary) |

**Returns:** `string, error` — an empty input returns an empty string



#### `decode`


Decodes a Base64 string to its original bytes.

```lua
-- Decode text
local decoded, decode_err = base64.decode("SGVsbG8sIFdvcmxkIQ==")
if decode_err then return nil, decode_err end
print(decoded)  -- "Hello, World!"

-- Decode with error handling
local data, err = base64.decode(user_input)
if err then
    return nil, errors.new("Invalid base64 data"):kind(errors.INVALID)
end

-- Decode binary data
local image_data, err = base64.decode(encoded_image)
if err then
    return nil, err
end
fs.get("app:data"):writefile("output.jpg", image_data)

-- Decode a base64-wrapped JSON document
local json = require("json")
local doc = json.decode(base64.decode(encoded_json))
```

The final block demonstrates delimiter handling only. It does not parse or verify a signed token format.

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | Base64-encoded string |

**Returns:** `string, error` — an empty input returns an empty string



### Errors


| Condition | Kind | Retryable |
|-----------|------|-----------|
| Input not a string | `errors.INVALID` | no |
| Invalid base64 characters | `errors.INVALID` | no |
| Corrupted padding | `errors.INVALID` | no |

See [Error Handling](lua/core/errors.md) for working with errors.



---

# "Compression"

## Compression

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="workflow"/>
<secondary-label ref="encoding"/>

The `compress` module encodes and decodes strings with gzip, Brotli, Zstandard, raw DEFLATE, and zlib.

This is an API reference with partial HTTP and storage recipes. Every operation materializes its complete input and output as Lua strings; use the archive or stream APIs when data must remain streaming. The examples assume the entry enables `compress` and any separately required modules such as `json` or `http`.



### Loading


```lua
local compress = require("compress")
```

Add `compress` to the executable entry's `modules:` list before requiring it.



### GZIP


Gzip is defined by RFC 1952.



#### Compress {id="gzip-compress"}


```lua
-- Compress for HTTP response
local body, json_err = json.encode(large_response)
if json_err then return nil, json_err end
local compressed, err = compress.gzip.encode(body)
if err then
    return nil, err
end

-- Set Content-Encoding header
local header_err = res:set_header("Content-Encoding", "gzip")
if header_err then return nil, header_err end
local write_err = res:write(compressed)
if write_err then return nil, write_err end

-- Maximum compression for storage
local archived, archive_err = compress.gzip.encode(data, {level = 9})
if archive_err then return nil, archive_err end

-- Fast compression for real-time
local fast, fast_err = compress.gzip.encode(data, {level = 1})
if fast_err then return nil, fast_err end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | Data to compress |
| `options` | table? | Optional encoding options |



##### Options {id="gzip-compress-options"}


| Field | Type | Description |
|-------|------|-------------|
| `level` | integer | Compression level 1-9 (default: 6) |

**Returns:** `string, error`



#### Decompress {id="gzip-decompress"}


```lua
-- Decompress HTTP request
local content_encoding, header_err = req:header("Content-Encoding")
if header_err then return nil, header_err end
if content_encoding == "gzip" then
    local body, body_err = req:body()
    if body_err then return nil, body_err end
    local decompressed, err = compress.gzip.decode(body)
    if err then
        return nil, errors.new("Invalid gzip data"):kind(errors.INVALID)
    end
    body = decompressed
end

-- Decompress with size limit (prevent zip bombs)
local decompressed, err = compress.gzip.decode(data, {max_size = 10 * 1024 * 1024})
if err then
    return nil, errors.new("Decompressed size exceeds 10MB limit"):kind(errors.INVALID)
end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | GZIP compressed data |
| `options` | table? | Optional decoding options |



##### Options {id="gzip-decompress-options"}


| Field | Type | Description |
|-------|------|-------------|
| `max_size` | integer | Max decompressed size in bytes (default: 128MB, max: 1GB) |

**Returns:** `string, error`



### Brotli


Brotli is defined by RFC 7932 and is commonly used for compressed text content.



#### Compress {id="brotli-compress"}


```lua
-- Best for static assets and text content
local compressed, err = compress.brotli.encode(html_content, {level = 11})
if err then return nil, err end

-- Store `compressed` through the application's cache contract if needed.

-- Moderate compression for API responses
local compressed, err = compress.brotli.encode(json_data, {level = 4})
if err then return nil, err end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | Data to compress |
| `options` | table? | Optional encoding options |



##### Options {id="brotli-compress-options"}


| Field | Type | Description |
|-------|------|-------------|
| `level` | integer | Compression level 0-11 (default: 6) |

**Returns:** `string, error`



#### Decompress {id="brotli-decompress"}


```lua
local decompressed, err = compress.brotli.decode(compressed_data)
if err then
    return nil, err
end

-- With size limit
local decompressed, err = compress.brotli.decode(data, {max_size = 50 * 1024 * 1024})
if err then return nil, err end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | Brotli compressed data |
| `options` | table? | Optional decoding options |



##### Options {id="brotli-decompress-options"}


| Field | Type | Description |
|-------|------|-------------|
| `max_size` | integer | Max decompressed size in bytes (default: 128MB, max: 1GB) |

**Returns:** `string, error`



### Zstandard


Zstandard is a general-purpose compression format defined by RFC 8878.



#### Compress {id="zstd-compress"}


```lua
-- Good balance of speed and ratio
local compressed, err = compress.zstd.encode(binary_data)
if err then return nil, err end

-- Higher compression for archival
local archived, archive_err = compress.zstd.encode(data, {level = 19})
if archive_err then return nil, archive_err end

-- Fast mode for latency-sensitive payloads
local fast, fast_err = compress.zstd.encode(data, {level = 1})
if fast_err then return nil, fast_err end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | Data to compress |
| `options` | table? | Optional encoding options |



##### Options {id="zstd-compress-options"}


| Field | Type | Description |
|-------|------|-------------|
| `level` | integer | Compression level 1-22 (default: 3) |
| `dict` | string? | Zstd dictionary bytes from `train_dict` (default: none) |

**Returns:** `string, error`



#### Decompress {id="zstd-decompress"}


```lua
local decompressed, err = compress.zstd.decode(compressed_data)
if err then
    return nil, err
end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | Zstandard compressed data |
| `options` | table? | Optional decoding options |



##### Options {id="zstd-decompress-options"}


| Field | Type | Description |
|-------|------|-------------|
| `max_size` | integer | Max decompressed size in bytes (default: 128MB, max: 1GB) |
| `dict` | string? | Zstd dictionary bytes (must match the dict used to encode) |

**Returns:** `string, error`



#### Dictionaries {id="zstd-dictionaries"}


Train a dictionary from similar sample payloads, then pass it through the `dict` option to `encode` and `decode`. Decoding requires the same dictionary used for encoding.

```lua
local dict, err = compress.zstd.train_dict(samples, { size = 112640 })
if err then return nil, err end
local packed, pack_err = compress.zstd.encode(data, { dict = dict })
if pack_err then return nil, pack_err end
local original, decode_err = compress.zstd.decode(packed, { dict = dict })
if decode_err then return nil, decode_err end
```



##### train_dict(samples, options?)


| Parameter | Type | Description |
|-----------|------|-------------|
| `samples` | string[] | Training samples (at least one >= 8 bytes) |
| `options` | table? | `size` (integer, target dict bytes, 256-1048576, default 114688), `id` (integer, default 0), `level` (integer, 1-22) |

**Returns:** `string, error` (the dictionary bytes)



##### inspect_dict(dict)


| Parameter | Type | Description |
|-----------|------|-------------|
| `dict` | string | Dictionary bytes |

**Returns:** `table, error` — `{id: integer, content_size: integer}`



### Deflate


Raw DEFLATE is defined by RFC 1951 and is also used inside other formats.



#### Compress {id="deflate-compress"}


```lua
local compressed, err = compress.deflate.encode(data, {level = 6})
if err then return nil, err end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | Data to compress |
| `options` | table? | Optional encoding options |



##### Options {id="deflate-compress-options"}


| Field | Type | Description |
|-------|------|-------------|
| `level` | integer | Compression level 1-9 (default: 6) |

**Returns:** `string, error`



#### Decompress {id="deflate-decompress"}


```lua
local decompressed, err = compress.deflate.decode(compressed)
if err then return nil, err end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | DEFLATE compressed data |
| `options` | table? | Optional decoding options |



##### Options {id="deflate-decompress-options"}


| Field | Type | Description |
|-------|------|-------------|
| `max_size` | integer | Max decompressed size in bytes (default: 128MB, max: 1GB) |

**Returns:** `string, error`



### Zlib


Zlib wraps DEFLATE data with a header and checksum as defined by RFC 1950.



#### Compress {id="zlib-compress"}


```lua
local compressed, err = compress.zlib.encode(data, {level = 6})
if err then return nil, err end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | Data to compress |
| `options` | table? | Optional encoding options |



##### Options {id="zlib-compress-options"}


| Field | Type | Description |
|-------|------|-------------|
| `level` | integer | Compression level 1-9 (default: 6) |

**Returns:** `string, error`



#### Decompress {id="zlib-decompress"}


```lua
local decompressed, err = compress.zlib.decode(compressed)
if err then return nil, err end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | Zlib compressed data |
| `options` | table? | Optional decoding options |



##### Options {id="zlib-decompress-options"}


| Field | Type | Description |
|-------|------|-------------|
| `max_size` | integer | Max decompressed size in bytes (default: 128MB, max: 1GB) |

**Returns:** `string, error`



### Choosing an Algorithm


| Algorithm | Best For | Speed | Ratio | Level Range |
|-----------|----------|-------|-------|-------------|
| gzip | HTTP, wide compatibility | Medium | Good | 1-9 |
| brotli | Static assets, text | Slow | Best | 0-11 |
| zstd | Binary payloads, fast compression | Fast | Good | 1-22 |
| deflate/zlib | Low-level, specific protocols | Medium | Good | 1-9 |

```lua
-- HTTP response based on Accept-Encoding
local accept, header_err = req:header("Accept-Encoding")
if header_err then return nil, header_err end
accept = accept or ""
local body, json_err = json.encode(response_data)
if json_err then return nil, json_err end

local qualities = {}
for item in accept:gmatch("[^,]+") do
    local coding = item:match("^%s*([^;%s]+)")
    local has_q = item:match(";%s*[qQ]%s*=") ~= nil
    local q_text = item:match(";%s*[qQ]%s*=%s*([^;%s,]+)")
    local q
    if not has_q then
        q = 1
    elseif q_text == "0" or q_text == "1" or
           (q_text and q_text:match("^0%.%d?%d?%d?$")) or
           (q_text and q_text:match("^1%.0?0?0?$")) then
        q = tonumber(q_text)
    end
    if coding and q and q >= 0 and q <= 1 then
        coding = coding:lower()
        qualities[coding] = math.max(qualities[coding] or 0, q)
    end
end

local function quality(coding)
    if qualities[coding] ~= nil then return qualities[coding] end
    if coding == "identity" then
        return qualities["*"] == 0 and 0 or 1
    end
    return qualities["*"] or 0
end

local selected, selected_q = nil, -1
for _, coding in ipairs({"br", "gzip", "identity"}) do
    local q = quality(coding)
    if q > selected_q then
        selected, selected_q = coding, q
    end
end

-- Include every field used by this handler or its surrounding middleware.
local vary_fields = {"Accept-Encoding"}
local vary_err = res:set_header("Vary", table.concat(vary_fields, ", "))
if vary_err then return nil, vary_err end

if selected_q <= 0 then
    local status_err = res:set_status(http.STATUS.NOT_ACCEPTABLE)
    if status_err then return nil, status_err end
    local write_err = res:write("No acceptable content encoding")
    if write_err then return nil, write_err end
elseif selected == "br" then
    local compressed, compress_err = compress.brotli.encode(body)
    if compress_err then return nil, compress_err end
    local set_err = res:set_header("Content-Encoding", "br")
    if set_err then return nil, set_err end
    local write_err = res:write(compressed)
    if write_err then return nil, write_err end
elseif selected == "gzip" then
    local compressed, compress_err = compress.gzip.encode(body)
    if compress_err then return nil, compress_err end
    local set_err = res:set_header("Content-Encoding", "gzip")
    if set_err then return nil, set_err end
    local write_err = res:write(compressed)
    if write_err then return nil, write_err end
else
    local write_err = res:write(body)
    if write_err then return nil, write_err end
end
```

This partial handler parses exact coding tokens and RFC q-values, honors explicit rejections such as `br;q=0`, and emits `Vary: Accept-Encoding`. `set_header` replaces an existing `Vary` value, so add every other field used by surrounding middleware to `vary_fields` before setting it. A full HTTP stack may provide a shared negotiation helper instead.



### Errors


| Condition | Kind | Retryable |
|-----------|------|-----------|
| Empty input | `errors.INVALID` | no |
| Level out of range | `errors.INVALID` | no |
| Invalid compressed data | `errors.INVALID` | no |
| Decompressed size exceeds limit | `errors.INTERNAL` (gzip, zlib, zstd) / `errors.INVALID` (deflate, brotli) | no |

See [Error Handling](lua/core/errors.md) for working with errors.



---

# "Archive"

## Archive

<secondary-label ref="function"/>
<secondary-label ref="io"/>
<secondary-label ref="encoding"/>

Read and write zip/tar archives with bounded memory. Archives are never loaded into RAM nor extracted to disk — peak memory is independent of archive and entry size, so multi-GB archives run on a low-RAM server.



### Loading


```lua
local archive = require("archive")
```



### Formats


Built-in formats are detected by magic bytes, or forced with `opts.format`:

| Format | Random read | Sequential scan | Write |
|--------|:-----------:|:---------------:|:-----:|
| `zip` | yes | yes (local headers) | yes |
| `tar` | yes | yes | yes |
| `tar.gz` | no | yes | yes |
| `tar.zst` | no | yes | yes |

`archive.formats()` returns the list of registered format names.

```lua
local names = archive.formats()  -- {"zip", "tar", "tar.gz", "tar.zst", ...}
```



### Options


All entrypoints accept an optional `opts` table:

| Key | Default | Meaning |
|-----|---------|---------|
| `format` | auto | `"zip"`, `"tar"`, `"tar.gz"`, `"tar.zst"`; auto = sniff magic, else extension |
| `max_entries` | 100000 | Reject archives with more entries (decompression-bomb defense) |
| `max_total_bytes` | 2 GiB | Cap on cumulative uncompressed output during read/extract |
| `max_file_bytes` | 1 GiB | Cap on a single entry's uncompressed size |
| `max_inline_bytes` | 16 MiB | Hard cap for the RAM-materializing `read()` call; above it, use `stream()`/`extract()` |
| `buffer_bytes` | 64 KiB | Streaming copy buffer for read/extract/add |

`max_total_bytes`/`max_file_bytes` are work caps, not RAM caps — streaming an entry never holds more than `buffer_bytes` plus the codec's decompression window. The only RAM-sizing knob is `max_inline_bytes`.



### Reading — Random Access


`archive.open(source, ...)` opens a **seekable** source for full random access (zip central directory is read up front; entries decompress on demand). The source may be an `fs.FS` handle plus a path, an open `fs.File`, raw bytes (bytes hold the whole archive in RAM — small archives only), or any random-access reader handed over by another module.

A reader from another module qualifies when it implements `io.ReaderAt` and reports its `Size`; an optional `Name` is used for extension sniffing when `opts.format` is omitted. [`cloudstorage`](lua/storage/cloud.md) `open_reader` is one, which reads a multi-GB archive directly out of object storage. The archive opens nothing in that case and never closes the reader — its owner does.

```lua
local fs = require("fs")
local archive = require("archive")

-- Open by fs handle + path (the module opens the file and owns its lifecycle)
local r, err = archive.open(fs.get("app:uploads"), "incoming.zip")
-- Or from an already-open seekable fs.File
-- local r = archive.open(fs:get("app:uploads"):open("x.zip"))
-- Or from raw bytes (small archives only)
-- local r = archive.open(zip_bytes, { format = "zip" })
-- Or from a random-access reader owned by another module
-- local reader = cloudstorage.get("app:files"):open_reader("incoming.zip")
-- local r = archive.open(reader)
```

**Returns:** `Reader, error`

**Permission:** `archive.read`



#### entries


Iterate the directory (metadata only — no decompression):

```lua
for e in r:entries() do
    -- e: name, size, compressed_size, is_dir, mode, modified, method, crc32, type
    print(e.name, e.size, e.is_dir)
end
```



#### stat


Get entry metadata by name (no decompression):

```lua
local info, err = r:stat("docs/readme.md")
```



#### read


Materialize a single entry as a Lua string. Errors (`kind = Invalid`) above `max_inline_bytes` — for anything large, use `stream()` or `extract()`:

```lua
local data, err = r:read("docs/readme.md")  -- small entries only
```



#### stream


Return the entry as a `stream.Stream` that decompresses on demand. Composes everywhere a stream does — `:scanner()`, `fs:writefile()`, or handed to another module:

```lua
local es, err = r:stream("big.csv")
while true do
    local chunk = es:read(65536)
    if not chunk then break end
    process(chunk)
end
es:close()
```



#### extract


Stream one entry into a destination filesystem:

```lua
local ok, err = r:extract("docs/readme.md", fs.get("app:out"))
-- optional destination path:
-- r:extract("docs/readme.md", fs.get("app:out"), "readme.md")
```



#### extract_all


Stream every entry into a destination filesystem:

```lua
local count, err = r:extract_all(fs.get("app:out"), {
    prefix = "job123/",          -- prepend to each destination path
    strip  = 1,                  -- drop N leading path components
    filter = function(e) return not e.is_dir end,
})
```

Entry names are sanitized on extract — `..` segments, absolute paths, and Windows drive/UNC prefixes are rejected (zip-slip defense).



#### close


Close the reader. Idempotent; also auto-closed at task scope.

```lua
r:close()
```



### Reading — Sequential Scan


`archive.scan(source, opts?)` opens a **forward-only** stream (an HTTP upload body, a multipart file stream). Entries are visited in archive order; each entry's reader is valid only until you advance. No random `read(name)`.

```lua
local up = form.files.upload[1]:stream()        -- stream.Stream
local s, err = archive.scan(up, { format = "zip" })

for e, entry in s:walk() do                      -- entry is a stream.Stream
    if not e.is_dir then
        fs.get("app:uploads"):writefile("job123/" .. e.name, entry)
    end
end
s:close()
```

**Returns:** `Walker, error`

**Permission:** `archive.read`

A walker also supports `extract_all` with the same options as the random-access reader, streaming every entry into a destination filesystem in one call:

```lua
local count, err = s:extract_all(fs.get("app:uploads"), { prefix = "job123/" })
```

`tar`, `tar.gz`, and `tar.zst` stream natively. `zip` is parsed via per-entry local headers; entries written with a streaming data descriptor (size/CRC trailing the data) are read by decompressing to the entry boundary. For robust zip handling of large uploads, land the upload as a file first (a bounded sequential copy) then use `archive.open`:

```lua
local dst = fs.get("app:tmp")
dst:writefile("u.zip", req:stream())   -- streaming copy upload → fs file
local r = archive.open(dst, "u.zip")   -- robust random access
-- ... entries / extract_all ...
r:close()
dst:remove("u.zip")
```



### Writing


`archive.create(dest, ...)` builds an archive by streaming entries into a destination — a file in an fs (with a path) or a writable `stream.Stream` (e.g. an HTTP response), so a download `.zip` is generated straight to the wire with bounded memory.

```lua
local w, err = archive.create(fs.get("app:tmp"), "out.zip", { format = "zip" })
-- or stream to a response:
-- local w = archive.create(res:stream(), { format = "zip" })
```

**Returns:** `Writer, error`

**Permission:** `archive.write`



#### add


Add an entry from a string, bytes, reader, or `stream.Stream`:

```lua
w:add("notes.txt", "hello")
w:add("from_upload", some_stream, { method = "deflate", mode = tonumber("644", 8) })
```



#### add_file


Stream an entry from a file in a filesystem:

```lua
w:add_file("data/big.bin", fs.get("app:data"), "big.bin")
```



#### add_dir


Add a directory entry:

```lua
w:add_dir("empty/")
```



#### close


Finalize the archive (writes the central directory for zip). Idempotent; also auto-closed at task scope.

```lua
w:close()
```

`add*` options: `{ method = "store"|"deflate", mode, size }`. Tar formats need the entry size up front, so `add()` from a stream or reader into a `tar*` archive requires `size` (strings and `add_file` supply it). The zip writer streams to non-seekable writers using data descriptors, so writing to a response stream works.



### Errors


| Condition | Kind |
|-----------|------|
| Source is not an fs handle, an fs file, bytes or a random-access reader | `errors.INVALID` |
| Unknown / mismatched format | `errors.INVALID` |
| Corrupt or truncated archive | `errors.INVALID` |
| Limit exceeded (entries / total / file / inline) | `errors.INVALID` |
| Random access on a stream-only format (use `scan`) | `errors.UNAVAILABLE` |
| Entry name not found | `errors.NOT_FOUND` |
| Source not readable / destination not writable | `errors.PERMISSION_DENIED` |
| Read a stale streamed entry after the walk advanced | `errors.INTERNAL` |

See [Error Handling](lua/core/errors.md) for working with errors.



### See Also


- [Filesystem](lua/storage/filesystem.md) - Source and destination filesystems
- [Stream](lua/core/stream.md) - Stream objects handed to and from archives
- [Compression](lua/data/compress.md) - In-memory gzip/deflate/zstd
- [Cloud Storage](lua/storage/cloud.md) - `open_reader` as a random-access archive source



---

# "Payload Encoding"

## Payload Encoding

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="workflow"/>

Payloads carry typed values between functions, processes, services, and workflows. They can be inspected, extracted, or transcoded between supported formats.

This is an API reference with partial transport recipes. Values such as `p`, `input_data`, and the asynchronous target entry come from the surrounding application.



### Loading


`payload` is a global namespace and does not require `require()`.

```lua
payload.new(...)  -- direct access
```



### Format Constants


The following constants identify payload formats:

```lua
payload.format.JSON     -- "json/plain"
payload.format.YAML     -- "yaml/plain"
payload.format.STRING   -- "text/plain"
payload.format.BYTES    -- "application/octet-stream"
payload.format.MSGPACK  -- "application/msgpack"
payload.format.LUA      -- "lua/any"
payload.format.GOLANG   -- "golang/any"
payload.format.ERROR    -- "golang/error"
```



### Creating Payloads


Create a payload from a Lua value:

```lua
-- From table
local p = payload.new({
    user_id = 123,
    name = "Alice",
    roles = {"admin", "user"}
})

-- From string
local str_p = payload.new("Hello, World!")

-- From number
local num_p = payload.new(42.5)

-- From boolean
local bool_p = payload.new(true)

-- From nil
local nil_p = payload.new(nil)

-- From error
local err_p = payload.new(errors.new("something failed"))
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `value` | any | Lua value (string, number, boolean, table, nil, or error) |

**Returns:** `Payload`



### Getting Format


Read the payload's format identifier:

```lua
local p = payload.new({name = "test"})
local format = p:get_format()  -- "lua/any"

local str_p = payload.new("hello")
local format2 = str_p:get_format()  -- "lua/any"

local err_p = payload.new(errors.new("failed"))
local format3 = err_p:get_format()  -- "golang/error"
```

**Returns:** `string` - one of `payload.format.*` constants



### Extracting Data


Extract the payload's Lua value, transcoding when needed:

```lua
local p = payload.new({
    items = {1, 2, 3},
    total = 100
})

local data, err = p:data()
if err then
    return nil, err
end

print(data.total)        -- 100
print(data.items[1])     -- 1
```

**Returns:** `any, error`



### Transcoding Payloads


Transcode a payload to another supported format:

```lua
local p = payload.new({
    name = "test",
    value = 123
})

-- Convert to JSON
local json_p, err = p:transcode(payload.format.JSON)
if err then
    return nil, err
end
print(json_p:get_format())  -- "json/plain"

-- Convert to MessagePack (compact binary)
local msgpack_p, err = p:transcode(payload.format.MSGPACK)
if err then
    return nil, err
end

-- Convert to YAML
local yaml_p, yaml_err = p:transcode(payload.format.YAML)
if yaml_err then
    return nil, yaml_err
end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `format` | string | Target format from `payload.format.*` |

**Returns:** `Payload, error`



### Unmarshalling


Decode a payload to a Lua value regardless of its source format:

```lua
local data, err = p:unmarshal()
if err then
    return nil, err
end
```

`unmarshal()` behaves like `data()`: both transcode non-Lua payloads to the Lua format and return the resulting Lua value. The only difference is that `unmarshal()` returns an error when the transcoded data is not a valid Lua value, whereas `data()` returns `nil`.

**Returns:** `any, error`



### Async Results


Asynchronous function calls return their values in payloads:

This example assumes `app.process:compute` returns exactly one value. With no result, `future:result()` returns `nil`; with multiple results, it returns a Lua table rather than one `Payload`, so callers must handle those shapes separately.

```lua
local funcs = require("funcs")

local future, err = funcs.async("app.process:compute", input_data)
if err then
    return nil, err
end

-- Wait for result
local ch = future:response()
local _, ok = ch:receive()
if not ok then
    return nil, errors.new("channel closed")
end

local result_payload, result_err = future:result()
if result_err then
    return nil, result_err
end
if result_payload == nil then
    return nil, errors.new("compute returned no result")
end

-- Extract data from payload
local result, err = result_payload:data()
if err then
    return nil, err
end

print(result.computed_value)
```



### Errors


| Condition | Kind | Retryable |
|-----------|------|-----------|
| Transcoding failure | `errors.INTERNAL` | no |
| Result not valid Lua value | `errors.INTERNAL` | no |

See [Error Handling](lua/core/errors.md) for working with errors.



---

# "Excel Spreadsheets"

## Excel Spreadsheets

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="io"/>
<secondary-label ref="external"/>

Read and write Microsoft Excel files (.xlsx). Create workbooks, manage sheets, read cell values, and generate reports with formatting support.



### Loading


```lua
local excel = require("excel")
```



#### New Workbook


Creates a new empty Excel workbook.

```lua
local wb, err = excel.new()
if err then
    return nil, err
end

-- Create sheets and add data
wb:new_sheet("Report")
wb:set_cell_value("Report", "A1", "Title")

wb:close()
```

**Returns:** `Workbook, error`



#### Open Workbook


Opens an Excel workbook from a reader object.

```lua
local fs = require("fs")

local vol, err = fs.get("app:data")
if err then
    return nil, err
end

local file, err = vol:open("/reports/sales.xlsx", "r")
if err then
    return nil, err
end

local wb, err = excel.open(file)
if err then
    file:close()
    return nil, err
end

-- Read data from workbook
local rows = wb:get_rows("Sheet1")
for i, row in ipairs(rows) do
    print("Row " .. i .. ": " .. table.concat(row, ", "))
end

wb:close()
file:close()
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `reader` | File | Must implement io.Reader (e.g., fs.File) |

**Returns:** `Workbook, error`



#### Create Sheet


Creates a new sheet or returns existing sheet index.

```lua
local wb = excel.new()

-- Create sheets
local idx1 = wb:new_sheet("Summary")
local idx2 = wb:new_sheet("Details")
local idx3 = wb:new_sheet("Charts")

-- If sheet exists, returns its index
local existing = wb:new_sheet("Summary")  -- returns same as idx1
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | string | Sheet name |

**Returns:** `integer, error`



#### List Sheets


Returns list of all sheet names in workbook.

```lua
local wb = excel.new()
wb:new_sheet("Sales")
wb:new_sheet("Expenses")
wb:new_sheet("Summary")

local sheets = wb:get_sheet_list()
-- sheets = {"Sheet1", "Sales", "Expenses", "Summary"}

for _, name in ipairs(sheets) do
    print("Sheet:", name)
end
```

**Returns:** `string[], error`



#### Set Cell Value


Sets value of a single cell.

```lua
local wb = excel.new()
wb:new_sheet("Data")

-- Set different value types
wb:set_cell_value("Data", "A1", "Product Name")  -- string
wb:set_cell_value("Data", "B1", "Price")         -- string
wb:set_cell_value("Data", "C1", "In Stock")      -- string

wb:set_cell_value("Data", "A2", "Widget")
wb:set_cell_value("Data", "B2", 29.99)           -- number
wb:set_cell_value("Data", "C2", true)            -- boolean

wb:set_cell_value("Data", "A3", "Gadget")
wb:set_cell_value("Data", "B3", 49.99)
wb:set_cell_value("Data", "C3", false)

-- Cell references support columns beyond Z
wb:set_cell_value("Data", "AA1", "Extended Column")
wb:set_cell_value("Data", "AB100", "Far cell")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `sheet` | string | Sheet name |
| `cell` | string | Cell reference ("A1", "B2", "AA100") |
| `value` | any | string, integer, number, or boolean |

**Returns:** `error`



#### Get All Rows


Gets all rows from a sheet as 2D array.

```lua
local wb = excel.new()
wb:new_sheet("Report")
wb:set_cell_value("Report", "A1", "Name")
wb:set_cell_value("Report", "B1", "Score")
wb:set_cell_value("Report", "A2", "Alice")
wb:set_cell_value("Report", "B2", 95)
wb:set_cell_value("Report", "A3", "Bob")
wb:set_cell_value("Report", "B3", 87)

local rows, err = wb:get_rows("Report")
if err then
    return nil, err
end

-- rows[1] = {"Name", "Score"}
-- rows[2] = {"Alice", "95"}
-- rows[3] = {"Bob", "87"}

for i, row in ipairs(rows) do
    if i == 1 then
        print("Headers:", row[1], row[2])
    else
        print("Data:", row[1], "scored", row[2])
    end
end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `sheet` | string | Sheet name |

**Returns:** `string[][], error`

All cell values returned as strings. Booleans as "TRUE" or "FALSE", numbers as string representation.



#### Stream Rows


`wb:rows(sheet)` opens a streaming cursor over one sheet. The sheet is decoded incrementally in constant memory, unlike `get_rows` which materializes the entire sheet:

```lua
local cursor, err = wb:rows("Report")
if err then
    return nil, err
end

while true do
    local batch, err = cursor:read(500)
    if err then
        cursor:close()
        return nil, err
    end
    if not batch then
        break                       -- end of sheet
    end
    for _, row in ipairs(batch) do
        process(row)
    end
end
cursor:close()
```

| Method | Description |
|--------|-------------|
| `cursor:read(n?)` | Read the next batch of up to `n` rows (default 1, max 10000). Returns `string[][], error`; `nil, nil` at end of sheet |
| `cursor:close()` | Release the cursor (idempotent; cursors also close with the workbook) |

Cell values format identically to `get_rows`. Empty rows come back as empty tables, and trailing empty rows are preserved rather than trimmed. After end-of-sheet or an error, subsequent reads keep returning that same state.



#### Write to File


Writes workbook to a writer object.

```lua
local fs = require("fs")
local wb = excel.new()

-- Build report
wb:new_sheet("Monthly Report")
wb:set_cell_value("Monthly Report", "A1", "Month")
wb:set_cell_value("Monthly Report", "B1", "Revenue")
wb:set_cell_value("Monthly Report", "A2", "January")
wb:set_cell_value("Monthly Report", "B2", 45000)
wb:set_cell_value("Monthly Report", "A3", "February")
wb:set_cell_value("Monthly Report", "B3", 52000)

-- Write to file
local vol, err = fs.get("app:output")
if err then
    wb:close()
    return nil, err
end

local file, err = vol:open("/reports/monthly.xlsx", "w")
if err then
    wb:close()
    return nil, err
end

local err = wb:write_to(file)
file:close()
wb:close()

if err then
    return nil, err
end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `writer` | File | Must implement io.Writer (e.g., fs.File) |

**Returns:** `error`



#### Serialize to a String


Renders the workbook into an `xlsx` byte string, without a filesystem or a writer. Use it to hand a workbook to an HTTP response, an object store or a queue message.

```lua
local cloudstorage = require("cloudstorage")

local wb = excel.new()
wb:new_sheet("Report")
wb:set_cell_value("Report", "A1", "Total")
wb:set_cell_value("Report", "B1", 45000)

local data, err = wb:bytes()
wb:close()
if err then
    return nil, err
end

local storage = cloudstorage.get("app.infra:files")
storage:upload_object("reports/monthly.xlsx", data, {
    content_type = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
})
storage:release()
```

**Returns:** `string, error`

The whole workbook is materialized in memory. `write_to` builds the same in-memory buffer and then copies it to the writer, so it saves the Lua string but does not stream a large workbook.

Calling `bytes()` on a closed workbook returns an `errors.INTERNAL` error.



#### Close Workbook


Closes workbook and releases resources.

```lua
local wb = excel.new()
-- ... work with workbook ...
wb:close()

-- Safe to call multiple times
wb:close()
```

**Returns:** `error`



### Errors


| Condition | Kind | Retryable |
|-----------|------|-----------|
| No context | `errors.INTERNAL` | no |
| Invalid workbook | `errors.INVALID` | no |
| Workbook closed | `errors.INTERNAL` (`errors.INVALID` from `rows`) | no |
| Not a writer (`write_to`) | `errors.INTERNAL` | no |
| Not a reader (`open`) | raised as an argument error | no |
| Invalid Excel file | `errors.INTERNAL` | no |
| Non-existent sheet | `errors.INTERNAL` (`errors.INVALID` from `rows`) | no |
| Invalid cell reference | `errors.INTERNAL` | no |
| Write failed | `errors.INTERNAL` | no |

See [Error Handling](lua/core/errors.md) for working with errors.



### See Also


- [Filesystem](lua/storage/filesystem.md) - File operations for reading/writing Excel files



---

# "HTTP"

## HTTP

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="io"/>

The `http` module reads the current server-side request and builds its response, including headers, route data, body content, streaming output, and Server-Sent Events.

This is an API reference with partial handler recipes. Names such as `id`, `data`, `token`, and application callbacks come from the surrounding handler. Request accessors generally return `value, error`, and response mutations return `error`; examples that consume a result check those errors.

For server configuration, see [HTTP Server](http/server.md).



### Loading


```lua
local http = require("http")
```

Add `http` to the executable entry's `modules:` list before requiring it. Examples using `uuid`, `fs`, or `time` require those modules separately.



### Accessing the Request


Read the current HTTP request context:

```lua
local req, err = http.request({
    timeout = 5000,        -- 5 second body read timeout
    max_body = 10485760    -- 10MB max body
})
if err then return nil, err end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `options.timeout` | integer | Body read timeout in ms (default: 300000 / 5 min) |
| `options.max_body` | integer | Max body size in bytes (default: 120MB) |

**Returns:** `Request, error`



### Accessing the Response


Read the current HTTP response context:

```lua
local res, err = http.response()
if err then return nil, err end
```

**Returns:** `Response, error`



#### `method`


Return the request's HTTP method.

```lua
local method, method_err = req:method()
if method_err then return nil, method_err end

if method == http.METHOD.GET then
    return get_resource(id)
elseif method == http.METHOD.POST then
    local data, body_err = req:body_json()
    if body_err then return nil, body_err end
    return create_resource(data)
elseif method == http.METHOD.PUT then
    local data, body_err = req:body_json()
    if body_err then return nil, body_err end
    return update_resource(id, data)
elseif method == http.METHOD.DELETE then
    return delete_resource(id)
end
```



#### `path`


Return the request path.

```lua
local path, err = req:path()
if err then return nil, err end
print(path)  -- "/api/users/123"

-- Route based on path
if path:match("^/api/") then
    return handle_api(req)
end
```



#### `query`


Return one query parameter:

```lua
-- GET /search?q=hello&page=2&limit=10
local query, query_err = req:query("q")
if query_err then return nil, query_err end

-- With defaults
local page_text, page_err = req:query("page")
if page_err then return nil, page_err end
local page = tonumber(page_text) or 1
```



#### `query_params`


Return all query parameters. Multiple values for one key are joined with commas.

```lua
-- GET /search?tags=lua&tags=go&active=true
local params, err = req:query_params()
if err then return nil, err end
-- {tags = "lua,go", active = "true"}

for key, value in pairs(params) do
    print(key .. ": " .. value)
end
```



#### `header`


Return one request header by name.

```lua
local uuid = require("uuid")

local auth, auth_err = req:header("Authorization")
if auth_err then return nil, auth_err end
if not auth then
    local type_err = res:set_content_type(http.CONTENT.JSON)
    if type_err then return nil, type_err end
    local status_err = res:set_status(http.STATUS.UNAUTHORIZED)
    if status_err then return nil, status_err end
    return res:write_json({error = "Missing authorization"})
end

local correlation_id, correlation_err = req:header("X-Correlation-ID")
if correlation_err then return nil, correlation_err end
if not correlation_id then
    correlation_id, correlation_err = uuid.v4()
    if correlation_err then return nil, correlation_err end
end
```

Lookup is case-insensitive: `req:header("content-type")` and `req:header("Content-Type")` return the same value. A header sent more than once returns its values joined with `", "`. A header that is not present returns `nil`.



#### headers


Gets every request header.

```lua
local headers, err = req:headers()
for name, value in pairs(headers) do
    print(name .. ": " .. value)
end
```

**Returns:** `table, error`

Keys are canonical header names (`Content-Type`, `X-Correlation-ID`), regardless of the casing the client sent. Repeated headers are joined with `", "`, as in `req:header()`.



#### content_type


Return the `Content-Type` header:

```lua
local ct, type_err = req:content_type()  -- "application/json; charset=utf-8" or nil
if type_err then return nil, type_err end
```



#### `content_length`


Return the `Content-Length` header value:

```lua
local length, length_err = req:content_length()  -- number of bytes
if length_err then return nil, length_err end
```



#### `host`


Return the `Host` header:

```lua
local host, host_err = req:host()  -- "example.com:8080"
if host_err then return nil, host_err end
```



#### `param`


Return one route parameter from a path pattern such as `/users/:id`:

```lua
-- Route: /users/:id/posts/:post_id
local id, param_err = req:param("id")
if param_err then return nil, param_err end
local valid = false
if id then
    local validate_err
    valid, validate_err = uuid.validate(id)
    if validate_err then return nil, validate_err end
end
if not valid then
    local type_err = res:set_content_type(http.CONTENT.JSON)
    if type_err then return nil, type_err end
    local status_err = res:set_status(http.STATUS.BAD_REQUEST)
    if status_err then return nil, status_err end
    return res:write_json({error = "Invalid ID format"})
end
```



#### `params`


Return all route parameters:

```lua
-- Route: /orgs/:org/repos/:repo/issues/:issue
local p, err = req:params()
if err then return nil, err end
-- {org = "acme", repo = "widget", issue = "123"}

local issue = get_issue(p.org, p.repo, p.issue)
```



#### `body`


Read the full request body as a string:

```lua
local body, err = req:body()
if err then return nil, err end

-- Parse XML manually
local is_xml, type_err = req:is_content_type("application/xml")
if type_err then return nil, type_err end
if is_xml then
    local data = parse_xml(body)
end

-- Avoid logging raw request bodies; record only non-sensitive metadata.
logger.debug("Request body read", {length = #body})
```

`body()`, `body_json()`, `stream()`, and `parse_multipart()` consume the same request body. Choose one body-reading path per handler. `body()` and `body_json()` enforce the request object's timeout and size limit; `stream()` is incremental and does not apply those two options.



#### `body_json`


Read and parse the request body as JSON:

```lua
local data, err = req:body_json()
if err then
    local type_err = res:set_content_type(http.CONTENT.JSON)
    if type_err then return nil, type_err end
    local status_err = res:set_status(http.STATUS.BAD_REQUEST)
    if status_err then return nil, status_err end
    return res:write_json({error = "Invalid JSON: " .. err:message()})
end

-- Validate required fields
if not data.name or not data.email then
    local type_err = res:set_content_type(http.CONTENT.JSON)
    if type_err then return nil, type_err end
    local status_err = res:set_status(http.STATUS.BAD_REQUEST)
    if status_err then return nil, status_err end
    return res:write_json({error = "Missing required fields"})
end

local user = create_user(data)
```



#### `has_body`


Check whether the request has a body.

```lua
local has_body, body_state_err = req:has_body()
if body_state_err then return nil, body_state_err end
if has_body then
    local data, body_err = req:body_json()
    if body_err then return nil, body_err end
    process(data)
else
    local type_err = res:set_content_type(http.CONTENT.JSON)
    if type_err then return nil, type_err end
    local status_err = res:set_status(http.STATUS.BAD_REQUEST)
    if status_err then return nil, status_err end
    return res:write_json({error = "Request body required"})
end
```

`has_body()` returns `true` only when the request has a body object and a positive `Content-Length`. A chunked request or another request with unknown length can return `false`; handlers that permit such bodies should attempt their chosen body reader and handle its error instead.



#### `is_content_type`


Check whether the request has the specified content type.

```lua
local is_json, type_check_err = req:is_content_type("application/json")
if type_check_err then return nil, type_check_err end
if not is_json then
    local type_err = res:set_content_type(http.CONTENT.JSON)
    if type_err then return nil, type_err end
    local status_err = res:set_status(415)
    if status_err then return nil, status_err end
    return res:write_json({error = "Content-Type must be application/json"})
end
```



#### `accepts`


Check whether the request accepts the specified content type.

```lua
local accepts_json, json_accept_err = req:accepts("application/json")
if json_accept_err then return nil, json_accept_err end
local accepts_html, html_accept_err = req:accepts("text/html")
if html_accept_err then return nil, html_accept_err end

if accepts_json then
    return res:write_json(data)
elseif accepts_html then
    local type_err = res:set_content_type("text/html; charset=utf-8")
    if type_err then return nil, type_err end
    return res:write(render_html(data))
else
    local type_err = res:set_content_type(http.CONTENT.JSON)
    if type_err then return nil, type_err end
    local status_err = res:set_status(http.STATUS.NOT_ACCEPTABLE)
    if status_err then return nil, status_err end
    return res:write_json({error = "Cannot produce acceptable response"})
end
```

The pinned `accepts()` helper performs exact comma-separated matches plus `*/*`; it does not process media-type parameters, subtype wildcards, or quality weights, and a missing `Accept` header returns `false`. Use application-owned negotiation when those HTTP semantics matter.



#### `remote_addr`


Return the client's remote network address.

```lua
local addr, addr_err = req:remote_addr()  -- "192.168.1.100:54321"
if addr_err then return nil, addr_err end

-- Extract the host from IPv4 and bracketed IPv6 addresses
local ip = addr:match("^%[([^%]]+)%]:%d+$")
    or addr:match("^([^:]+):%d+$")
    or addr

-- Rate limiting by IP
if rate_limiter:is_limited(ip) then
    local type_err = res:set_content_type(http.CONTENT.JSON)
    if type_err then return nil, type_err end
    local status_err = res:set_status(http.STATUS.TOO_MANY_REQUESTS)
    if status_err then return nil, status_err end
    return res:write_json({error = "Too many requests"})
end
```



#### `parse_multipart`


Parse multipart form data, including file uploads. The optional `max_memory` argument sets the number of bytes held in memory before data spills to temporary files; the default is 32 MB.

```lua
local uuid = require("uuid")

local form, err = req:parse_multipart()  -- or req:parse_multipart(8 * 1024 * 1024)
if err then
    local type_err = res:set_content_type(http.CONTENT.JSON)
    if type_err then return nil, type_err end
    local status_err = res:set_status(http.STATUS.BAD_REQUEST)
    if status_err then return nil, status_err end
    return res:write_json({error = "Invalid form data"})
end

-- Access form values
local title = form.values.title
local description = form.values.description

-- Access uploaded files
if form.files.avatar then
    local file = form.files.avatar[1]
    local filename, name_err = file:name()        -- untrusted client metadata
    if name_err then return nil, name_err end
    local size, size_err = file:size()
    if size_err then return nil, size_err end
    local content_type, header_err = file:header("Content-Type")  -- "image/jpeg"
    if header_err then return nil, header_err end

    -- Read file content
    local stream = file:stream()
    local parts = {}
    while true do
        local chunk, err = stream:read(65536)
        if err or not chunk then break end
        parts[#parts + 1] = chunk
    end
    stream:close()
    local content = table.concat(parts)

    local stream, stream_err = file:stream()
    if stream_err then return nil, stream_err end
    local stored_name, id_err = uuid.v7()
    if id_err then
        stream:close()
        return nil, id_err
    end
    local _, write_err = uploads:writefile(stored_name, stream, "wx")
    local _, close_err = stream:close()
    if write_err then return nil, write_err end
    if close_err then return nil, close_err end
end

-- Handle multiple files
if form.files.documents then
    for _, file in ipairs(form.files.documents) do
        process_document(file)
    end
end
```

Multipart field values are strings when a field occurs once and arrays when it occurs repeatedly. Treat uploaded filenames and `Content-Type` values as untrusted metadata; generate the storage name and inspect the content independently when its type matters.

The exclusive `wx` write prevents overwriting an existing object. A failed write does not prove that the target belongs to this request, so the failure path must not remove it blindly. Applications that need cleanup after partial writes should stage uploads under an ownership-tracked temporary name and promote them only after the write succeeds.



#### `stream`


Read the request body as a stream:

```lua
local stream, stream_err = req:stream()
if stream_err then return nil, stream_err end

-- Process in chunks
local read_err
while true do
    local chunk
    chunk, read_err = stream:read(65536)  -- 64KB chunks
    if read_err or not chunk then break end
    process_chunk(chunk)
end
local _, close_err = stream:close()
if read_err then return nil, read_err end
if close_err then return nil, close_err end
```



#### `set_status`


Set the response status code.

`set_status()` writes the status and commits the response headers immediately. Call `set_header()`, `set_content_type()`, or `set_transfer()` first; later header changes return `errors.INVALID`.

```lua
local status_err = res:set_status(http.STATUS.CREATED)
if status_err then return nil, status_err end

-- Other common choices: 204 No Content, 400 Bad Request,
-- 401 Unauthorized, 403 Forbidden, 404 Not Found, and 500 Internal Error.
```



#### `set_header`


Set one response header.

```lua
local request_id_err = res:set_header("X-Request-ID", correlation_id)
if request_id_err then return nil, request_id_err end
local cache_err = res:set_header("Cache-Control", "max-age=3600")
if cache_err then return nil, cache_err end
local rate_err = res:set_header("X-RateLimit-Remaining", tostring(remaining))
if rate_err then return nil, rate_err end

-- CORS headers
local origin_err = res:set_header("Access-Control-Allow-Origin", "*")
if origin_err then return nil, origin_err end
local methods_err = res:set_header("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE")
if methods_err then return nil, methods_err end
local headers_err = res:set_header("Access-Control-Allow-Headers", "Content-Type, Authorization")
if headers_err then return nil, headers_err end
```



#### `set_content_type`


Set the response content type.

```lua
local type_err = res:set_content_type(http.CONTENT.JSON)
if type_err then return nil, type_err end

-- Other examples: "text/html; charset=utf-8" or "application/pdf".
```



#### `write`


Write to the response body:

```lua
local write_err = res:write("Hello, World!")
if write_err then return nil, write_err end

-- Build response incrementally
for _, fragment in ipairs({
    "<html><body>",
    "<h1>Title</h1>",
    "<p>Content</p>",
    "</body></html>"
}) do
    local fragment_err = res:write(fragment)
    if fragment_err then return nil, fragment_err end
end
```



#### `write_json`


Encode a value as JSON and write it to the response:

```lua
-- Success response
local write_err = res:write_json({
    data = users,
    total = count,
    page = page
})
if write_err then return nil, write_err end

-- Error response
local type_err = res:set_content_type(http.CONTENT.JSON)
if type_err then return nil, type_err end
local status_err = res:set_status(http.STATUS.BAD_REQUEST)
if status_err then return nil, status_err end
local error_write_err = res:write_json({
    error = "Validation failed",
    details = {
        {field = "email", message = "Invalid format"},
        {field = "age", message = "Must be positive"}
    }
})
if error_write_err then return nil, error_write_err end
```

`write()`, `write_json()`, `flush()`, and `write_event()` also commit headers. `write_json()` sets `Content-Type: application/json` only when headers have not already been committed.



#### `flush`


Flush buffered response data to the client:

<code-block lang="lua">
-- Stream progress updates
for i = 1, 100 do
    local write_err = res:write(string.format("Progress: %d%%\n", i))
    if write_err then return nil, write_err end
    local flush_err = res:flush()
    if flush_err then return nil, flush_err end
    local _, sleep_err = time.sleep("100ms")
    if sleep_err then return nil, sleep_err end
end
</code-block>



#### `set_transfer`


Set the transfer mode for a streaming response:

```lua
-- Chunked transfer
local transfer_err = res:set_transfer(http.TRANSFER.CHUNKED)
if transfer_err then return nil, transfer_err end
for chunk in get_chunks() do
    local write_err = res:write(chunk)
    if write_err then return nil, write_err end
    local flush_err = res:flush()
    if flush_err then return nil, flush_err end
end

-- Server-Sent Events
local sse_err = res:set_transfer(http.TRANSFER.SSE)
if sse_err then return nil, sse_err end
```



#### `write_event`


Write a Server-Sent Event:

```lua
-- Real-time updates
local transfer_err = res:set_transfer(http.TRANSFER.SSE)
if transfer_err then return nil, transfer_err end

local connected_err = res:write_event({name = "connected", data = {client_id = client_id}})
if connected_err then return nil, connected_err end

for progress in task:progress() do
    local event_err = res:write_event({name = "progress", data = {percent = progress}})
    if event_err then return nil, event_err end
end

local complete_err = res:write_event({name = "complete", data = {result = result}})
if complete_err then return nil, complete_err end

-- Chat messages
local message_err = res:write_event({name = "message", data = {
    from = "alice",
    text = "Hello!",
    timestamp = time.now():unix()
}})
if message_err then return nil, message_err end
```



#### HTTP Methods


```lua
http.METHOD.GET
http.METHOD.POST
http.METHOD.PUT
http.METHOD.DELETE
http.METHOD.PATCH
http.METHOD.HEAD
http.METHOD.OPTIONS
```



#### Status Codes


```lua
-- Success (2xx)
http.STATUS.OK                   -- 200
http.STATUS.CREATED              -- 201
http.STATUS.ACCEPTED             -- 202
http.STATUS.NO_CONTENT           -- 204
http.STATUS.PARTIAL_CONTENT      -- 206

-- Redirect (3xx)
http.STATUS.MOVED_PERMANENTLY    -- 301
http.STATUS.FOUND                -- 302
http.STATUS.SEE_OTHER            -- 303
http.STATUS.NOT_MODIFIED         -- 304
http.STATUS.TEMPORARY_REDIRECT   -- 307
http.STATUS.PERMANENT_REDIRECT   -- 308

-- Client Error (4xx)
http.STATUS.BAD_REQUEST          -- 400
http.STATUS.UNAUTHORIZED         -- 401
http.STATUS.PAYMENT_REQUIRED     -- 402
http.STATUS.FORBIDDEN            -- 403
http.STATUS.NOT_FOUND            -- 404
http.STATUS.METHOD_NOT_ALLOWED   -- 405
http.STATUS.NOT_ACCEPTABLE       -- 406
http.STATUS.CONFLICT             -- 409
http.STATUS.GONE                 -- 410
http.STATUS.UNPROCESSABLE        -- 422
http.STATUS.TOO_MANY_REQUESTS    -- 429

-- Server Error (5xx)
http.STATUS.INTERNAL_ERROR       -- 500 (alias: INTERNAL_SERVER_ERROR)
http.STATUS.NOT_IMPLEMENTED      -- 501
http.STATUS.BAD_GATEWAY          -- 502
http.STATUS.SERVICE_UNAVAILABLE  -- 503
http.STATUS.GATEWAY_TIMEOUT      -- 504
http.STATUS.VERSION_NOT_SUPPORTED -- 505
```



#### Content Types


```lua
http.CONTENT.JSON       -- "application/json"
http.CONTENT.FORM       -- "application/x-www-form-urlencoded"
http.CONTENT.MULTIPART  -- "multipart/form-data"
http.CONTENT.TEXT       -- "text/plain"
http.CONTENT.STREAM     -- "application/octet-stream"
```



#### Transfer Modes


```lua
http.TRANSFER.CHUNKED   -- "chunked"
http.TRANSFER.SSE       -- "sse"
```



#### Legacy Error-Type Constants


The module exports these compatibility strings, but current request and response methods do not return them. Runtime failures use the structured `errors.*` kinds described below.

```lua
http.ERROR.PARSE_FAILED   -- Form/multipart parse error
http.ERROR.INVALID_STATE  -- Invalid response state
http.ERROR.WRITE_FAILED   -- Response write error
http.ERROR.STREAM_ERROR   -- Body stream error
```



### Errors


| Condition | Kind | Retryable |
|-----------|------|-----------|
| No HTTP context | `errors.INTERNAL` | no |
| Body too large | `errors.INVALID` | no |
| Read timeout | `errors.INTERNAL` | no |
| Invalid JSON | `errors.INVALID` | no |
| Not multipart | `errors.INVALID` | no |
| Headers already sent | `errors.INVALID` | no |
| Write failed | `errors.INTERNAL` | no |

See [Error Handling](lua/core/errors.md) for working with errors.



---

# "HTTP Client"

## HTTP Client

<secondary-label ref="network"/>
<secondary-label ref="io"/>
<secondary-label ref="permissions"/>

The `http_client` module sends HTTP requests with headers, query parameters, forms, file uploads, authentication, TLS options, streaming responses, and concurrent batches.

This is an API reference with partial request recipes. URLs, tokens, credentials, request data, and certificate material come from the surrounding application. Examples check `Response, error` before consuming a response and close streamed bodies explicitly.



### Loading


```lua
local http_client = require("http_client")
```

Add `http_client` to the executable entry's `modules:` list before requiring it. JSON and filesystem recipes also require `json` and `fs`.



### HTTP Methods


Convenience methods use the `method(url, options?)` signature and return `Response, error`.



#### GET


Send a `GET` request.

```lua
local resp, err = http_client.get("https://api.example.com/users")
if err then
    return nil, err
end

print(resp.status_code)  -- 200
print(resp.body)         -- response body
```



#### POST


Send a `POST` request.

```lua
local json = require("json")

local body, body_err = json.encode({name = "Alice", email = "alice@example.com"})
if body_err then return nil, body_err end
local resp, err = http_client.post("https://api.example.com/users", {
    headers = {["Content-Type"] = "application/json"},
    body = body
})
if err then return nil, err end
```



#### PUT


Send a `PUT` request.

```lua
local body, body_err = json.encode({name = "Alice Smith"})
if body_err then return nil, body_err end
local resp, err = http_client.put("https://api.example.com/users/123", {
    headers = {["Content-Type"] = "application/json"},
    body = body
})
if err then return nil, err end
```



#### PATCH


Send a `PATCH` request.

```lua
local body, body_err = json.encode({status = "active"})
if body_err then return nil, body_err end
local resp, err = http_client.patch("https://api.example.com/users/123", {
    headers = {["Content-Type"] = "application/json"},
    body = body
})
if err then return nil, err end
```



#### DELETE


Send a `DELETE` request.

```lua
local resp, err = http_client.delete("https://api.example.com/users/123", {
    headers = {["Authorization"] = "Bearer " .. token}
})
if err then return nil, err end
```



#### HEAD


A `HEAD` request returns headers without a response body.

```lua
local resp, err = http_client.head("https://cdn.example.com/file.zip")
if err then return nil, err end
local size = resp.headers["Content-Length"]
```



#### Custom Methods


Send a request using an explicit HTTP method string.

```lua
local resp, err = http_client.request("PROPFIND", "https://dav.example.com/folder", {
    headers = {["Depth"] = "1"}
})
if err then return nil, err end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `method` | string | HTTP method |
| `url` | string | Request URL |
| `options` | table | Request options (optional) |



### Request Options


| Field | Type | Description |
|-------|------|-------------|
| `headers` | table | Request headers `{["Name"] = "value"}` |
| `body` | string | Request body |
| `query` | table | Query parameters `{key = "value"}` |
| `form` | table | Form data (sets Content-Type automatically) |
| `files` | table | File uploads (array of file definitions) |
| `cookies` | table | Request cookies `{name = "value"}` |
| `auth` | table | Basic auth `{user = "name", pass = "secret"}` |
| `timeout` | number/string | Timeout: number in seconds, or string like `"30s"`, `"1m"` |
| `stream` | boolean | Stream response body instead of buffering |
| `max_response_body` | number | Max response size in bytes (0 = default) |
| `unix_socket` | string | Connect via Unix socket path |
| `tls` | table | Per-request TLS configuration (see [TLS Options](#tls-options)) |
| `overlay_network` | string | Route through a [network overlay](system/network.md) — registry ID of a `network.socks5` / `network.tailscale` / `network.i2p` entry |

Selecting `overlay_network` requires `network.select` permission on that network ID.



#### Query Parameters


```lua
local resp, err = http_client.get("https://api.example.com/search", {
    query = {
        q = "lua programming",
        page = "1",
        limit = "20"
    }
})
if err then return nil, err end
```



#### Headers and Authentication


```lua
local resp, err = http_client.get("https://api.example.com/data", {
    headers = {
        ["Authorization"] = "Bearer " .. token,
        ["Accept"] = "application/json"
    }
})
if err then return nil, err end

-- Or use basic auth
local resp, err = http_client.get("https://api.example.com/data", {
    auth = {user = service_user, pass = service_password}
})
if err then return nil, err end
```

Load authentication values from application-owned secret storage and send them only over TLS.



#### Form Data


```lua
local resp, err = http_client.post("https://api.example.com/login", {
    form = {
        username = username,
        password = password
    }
})
if err then return nil, err end
```



#### File Upload


```lua
local resp, err = http_client.post("https://api.example.com/upload", {
    form = {title = "My Document"},
    files = {
        {
            name = "attachment",      -- form field name
            filename = "report.pdf",  -- original filename
            content = pdf_data,       -- file content
            content_type = "application/pdf"
        }
    }
})
if err then return nil, err end
```

| File Field | Type | Required | Description |
|------------|------|----------|-------------|
| `name` | string | yes | Form field name |
| `filename` | string | no | Original filename |
| `content` | string | yes* | File content |
| `reader` | userdata | yes* | Alternative: io.Reader for content |
| `content_type` | string | no | Currently ignored: each uploaded part is always sent with `Content-Type: application/octet-stream` regardless of this field |

\* Either `content` or `reader` is required.

The pinned runtime fully reads a `reader` into memory before dispatch, does not close it, and does not surface a non-EOF read failure separately; it can send the bytes accumulated before that failure. Prefer `content` for already-bounded data, and close caller-owned readers after the request. The `content_type` field is parsed but not forwarded by runtime `v0.3.32a`, so uploaded parts use the transport default.

Reader-backed files are supported only by single-request calls in this release. `request_batch` forwards the `content` field but drops a parsed `reader`, so batch file uploads must provide `content`.



#### Timeout


```lua
-- Number: seconds
local resp, err = http_client.get(url, {timeout = 30})
if err then return nil, err end

-- String alternatives use Go duration format: "30s", "1m30s", or "1h".
```



#### TLS Options


Configure mutual TLS and custom CA certificates for one request.

| Field | Type | Description |
|-------|------|-------------|
| `cert` | string | Client certificate in PEM format |
| `key` | string | Client private key in PEM format |
| `ca` | string | Custom CA certificate in PEM format |
| `server_name` | string | Server name for SNI verification |
| `insecure_skip_verify` | boolean | Skip TLS certificate verification |

For mutual TLS, provide `cert` and `key` together. The `ca` field replaces the system certificate pool with a custom CA.



##### mTLS Authentication


```lua
local fs = require("fs")
local certs, volume_err = fs.get("app:certs")
if volume_err then return nil, volume_err end
local cert_pem, cert_err = certs:readfile("client.crt")
if cert_err then return nil, cert_err end
local key_pem, key_err = certs:readfile("client.key")
if key_err then return nil, key_err end

local resp, err = http_client.get("https://secure.example.com/api", {
    tls = {
        cert = cert_pem,
        key = key_pem,
    }
})
if err then return nil, err end
```



##### Custom CA


```lua
local fs = require("fs")
local certs, volume_err = fs.get("app:certs")
if volume_err then return nil, volume_err end
local ca_pem, ca_err = certs:readfile("internal-ca.crt")
if ca_err then return nil, ca_err end

local resp, err = http_client.get("https://internal.example.com/api", {
    tls = {
        ca = ca_pem,
        server_name = "internal.example.com",
    }
})
if err then return nil, err end
```



##### Insecure Skip Verify


`insecure_skip_verify` disables TLS verification and requires the `http_client.insecure_tls` security permission.

```lua
local resp, err = http_client.get("https://localhost:8443/api", {
    tls = {
        insecure_skip_verify = true,
    }
})
if err then return nil, err end
```

Use `insecure_skip_verify` only for a controlled diagnostic endpoint. It disables both certificate-chain and hostname verification.



### Response Object


| Field | Type | Description |
|-------|------|-------------|
| `status_code` | number | HTTP status code |
| `body` | string | Response body (if not streaming) |
| `body_size` | number | Body size in bytes (-1 if streaming) |
| `headers` | table | Response headers |
| `cookies` | table | Response cookies |
| `url` | string | Final URL (after redirects) |
| `stream` | Stream | Stream object (if `stream = true`) |

```lua
local resp, err = http_client.get("https://api.example.com/data")
if err then
    return nil, err
end

if resp.status_code == 200 then
    local data, decode_err = json.decode(resp.body)
    if decode_err then return nil, decode_err end
    print("Content-Type:", resp.headers["Content-Type"])
end
```



### Streaming Responses


Set `stream = true` to process a response incrementally rather than buffering its full body.

```lua
local resp, err = http_client.get("https://cdn.example.com/large-file.zip", {
    stream = true
})
if err then
    return nil, err
end

-- Process in chunks
local read_err
while true do
    local chunk
    chunk, read_err = resp.stream:read(65536)
    if read_err or not chunk then break end
    -- process chunk
end
local _, close_err = resp.stream:close()
if read_err then return nil, read_err end
if close_err then return nil, close_err end
```

| Stream Method | Returns | Description |
|---------------|---------|-------------|
| `read(n?)` | string, error | Read up to `n` bytes (default: implementation buffer) |
| `close()` | boolean, error | Close the stream |

`resp.stream` is a full [stream](lua/core/stream.md) object — `seek`, `stat`, and `scanner` are also available. The caller owns a streamed response body and should close it on every exit; task cleanup is a fallback, not a substitute for prompt release.



### Batch Requests


`request_batch` executes multiple requests concurrently.

```lua
local requests = {
    {"GET", "https://api.example.com/users"},
    {"GET", "https://api.example.com/products"},
    {"POST", "https://api.example.com/log", {body = "event"}}
}
local responses, batch_errors = http_client.request_batch(requests)

if not responses then
    return nil, batch_errors  -- whole-batch dispatch or validation failure
end

if batch_errors then
    for i = 1, #requests do
        local err = batch_errors[i]
        if err then
            print("Request " .. i .. " failed:", err)
        end
    end
else
    -- All succeeded
    for i, resp in ipairs(responses) do
        print("Response " .. i .. ":", resp.status_code)
    end
end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `requests` | table | Array of `{method, url, options?}` |

**Returns:** `responses, errors` — arrays indexed by request position

**Notes:**

- Requests execute concurrently
- Streaming (`stream = true`) is not supported in batch
- Reader-backed file uploads are not supported in batch; use `files[].content`
- Result arrays match request order (1-indexed)



#### Encode


Encode a string for inclusion in a URL.

```lua
local encoded = http_client.encode_uri("hello world")
-- "hello+world"

local url = "https://api.example.com/search?q=" .. http_client.encode_uri(query)
```



#### Decode


Decode a string previously encoded with `http_client.encode_uri`.

```lua
local decoded, err = http_client.decode_uri("hello+world")
if err then return nil, err end
-- "hello world"
```



### Permissions


HTTP requests are evaluated against the active security policy.



#### Security Actions


| Action | Resource | Description |
|--------|----------|-------------|
| `http_client.request` | URL | Allow/deny requests to specific URLs |
| `http_client.unix_socket` | Socket path | Allow/deny Unix socket connections |
| `http_client.private_ip` | IP address | Allow/deny access to private IP ranges |
| `http_client.insecure_tls` | URL | Allow/deny insecure TLS (skip verification) |
| `network.select` | Network entry ID | Allow/deny routing through the `overlay_network` given in the request |



#### Checking Access


```lua
local security = require("security")

if security.can("http_client.request", "https://api.example.com/users") then
    local resp, request_err = http_client.get("https://api.example.com/users")
    if request_err then return nil, request_err end
end
```



#### SSRF Protection


Non-public IP ranges are blocked by default. Access requires the `http_client.private_ip` permission on the address:

- loopback, private (10.x, 172.16-31.x, 192.168.x), link-local unicast and multicast, and the unspecified address
- carrier-grade NAT `100.64.0.0/10`, `192.0.0.0/24`, multicast `224.0.0.0/4`, reserved `240.0.0.0/4`
- documentation and benchmarking ranges `192.0.2.0/24`, `198.18.0.0/15`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32`
- IPv6 multicast `ff00::/8`

```lua
local resp, err = http_client.get("http://192.168.1.1/admin")
-- Error: not allowed: private IP 192.168.1.1
```

The check runs at dial time, not on the URL string, and it covers every address the host resolves to. A hostname that resolves to several addresses is checked address by address: a denied address is skipped and the next one is tried, and the request fails only when every candidate is denied or unreachable. A public hostname that resolves to a private address is therefore blocked exactly like a private IP literal.



#### Redirects


Up to nine redirects are followed; the tenth fails with `stopped after 10 redirects`, a count that includes the original request.

Every hop is authorized on its own. Before following a redirect the client evaluates `http_client.request` against the target URL and applies the private-IP check to it, so a permitted URL cannot be used to reach a denied one by redirection. A hop that fails either check aborts the request.

See [Security Model](system/security.md) for policy configuration.



### Errors


| Condition | Kind | Retryable |
|-----------|------|-----------|
| Security policy denied | `errors.PERMISSION_DENIED` | no |
| Private IP blocked | `errors.PERMISSION_DENIED` | no |
| Unix socket denied | `errors.PERMISSION_DENIED` | no |
| Insecure TLS denied | `errors.PERMISSION_DENIED` | no |
| Invalid batch item, batch streaming, or invalid URI escape | `errors.INVALID` | no |
| No context | `errors.INTERNAL` | no |
| Malformed transport URL or network failure | `errors.INTERNAL` | yes |
| Timeout | `errors.INTERNAL` | yes |

Many unsupported option values are ignored rather than returned as structured errors. Invalid Lua argument types and an empty batch raise Lua argument errors. Validate application-supplied option tables before calling the client.

```lua
local resp, err = http_client.get(url)
if err then
    if errors.is(err, errors.PERMISSION_DENIED) then
        print("Access denied:", err:message())
    elseif err:retryable() then
        print("Temporary error:", err:message())
    end
    return nil, err
end
```

See [Error Handling](lua/core/errors.md) for working with errors.



---

# "WebSocket Client"

## WebSocket Client

<secondary-label ref="network"/>
<secondary-label ref="io"/>
<secondary-label ref="permissions"/>

The `websocket` module creates bidirectional client connections to WebSocket servers.

This is an API reference with partial connection and subscription recipes. Endpoint URLs, tokens, message handlers, and application data come from the surrounding application. The lifecycle examples close the client on every terminal or checked error path; smaller method snippets assume an enclosing owner performs that cleanup.



### Loading


```lua
local websocket = require("websocket")
```

Add `websocket` to the executable entry's `modules:` list before requiring it. The `channel` global is always available; JSON and timeout recipes also require `json` and `time`.



#### `connect`


Open a WebSocket connection with the default options:

```lua
local client, err = websocket.connect("wss://api.example.com/ws")
if err then
    return nil, err
end
```

Pass an options table to configure the connection:

```lua
local client, err = websocket.connect("wss://api.example.com/ws", {
    headers = {
        ["Authorization"] = "Bearer " .. token
    },
    protocols = {"graphql-ws"},
    dial_timeout = "10s",
    read_timeout = "30s",
    compression = websocket.COMPRESSION.CONTEXT_TAKEOVER
})
if err then
    return nil, err
end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `url` | string | WebSocket URL (ws:// or wss://) |
| `options` | table | Connection options (optional) |

**Returns:** `Client, error`



##### Connection Options


| Option | Type | Description |
|--------|------|-------------|
| `headers` | table | HTTP headers for handshake |
| `protocols` | table | WebSocket subprotocols |
| `dial_timeout` | number/string | Connection timeout (ms or "5s") |
| `read_timeout` | number/string | Read timeout |
| `write_timeout` | number/string | Write timeout |
| `compression` | number/string | Compression mode (see Constants), or `"disabled"`, `"context_takeover"`, `"no_context_takeover"` |
| `compression_threshold` | number | Min size to compress (0-100MB) |
| `read_limit` | number | Max message size (0-128MB) |
| `channel_capacity` | number | Receive channel buffer (1-10000) |

**Timeout format:** Numbers are milliseconds. Strings use Go duration syntax such as `"5s"` or `"1m"`.

Invalid timeout strings and out-of-range or unsupported option values are ignored, leaving the corresponding default in effect.



#### Text Messages


Send a text message.

```lua
local json = require("json")

client:send("Hello, Server!")

-- Send JSON
local payload, encode_err = json.encode({
    type = "subscribe",
    channel = "orders"
})
if encode_err then return nil, encode_err end
client:send(payload)
```



#### Binary Messages


Send a binary message by specifying `websocket.BINARY`.

```lua
client:send(binary_data, websocket.BINARY)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | Message content |
| `type` | number | `websocket.TEXT` (1) or `websocket.BINARY` (2) |

Yields until the message is sent. Returns no values.



#### Ping


Send a ping frame.

```lua
client:ping()
```

Yields until the ping is sent. Returns no values.



### Receiving Messages


`channel()` returns the receive channel, and `receive()` is an alias. The first call yields while the runtime creates the subscription; later calls return the same channel immediately. A subscription failure returns `nil, error`. The channel can be used with `channel.select`.



#### Basic Receive


```lua
local ch, err = client:channel()
if err then
    client:close()
    return nil, err
end

local msg, ok = ch:receive()
if ok then
    print("Type:", msg.type)  -- "text" or "binary"
    print("Data:", msg.data)
end

local _, close_err = client:close()
if close_err then return nil, close_err end
```



#### Message Loop


```lua
local json = require("json")

local ch, err = client:channel()
if err then
    client:close()
    return nil, err
end

while true do
    local msg, ok = ch:receive()
    if not ok then
        break  -- Connection closed
    end

    if msg.type == "text" then
        local data, decode_err = json.decode(msg.data)
        if decode_err then
            client:close()
            return nil, decode_err
        end
        handle_message(data)
    end
end

local _, close_err = client:close()
if close_err then return nil, close_err end
```



#### With Select


```lua
local json = require("json")
local time = require("time")

local ch, ch_err = client:channel()
if ch_err then
    client:close()
    return nil, ch_err
end

local timeout, timeout_err = time.after("30s")
if timeout_err then
    client:close()
    return nil, timeout_err
end

while true do
    local r = channel.select {
        ch:case_receive(),
        timeout:case_receive()
    }

    if r.channel == timeout then
        client:ping()  -- Keep-alive
        timeout, timeout_err = time.after("30s")
        if timeout_err then
            client:close()
            return nil, timeout_err
        end
    elseif not r.ok then
        break
    else
        local data, decode_err = json.decode(r.value.data)
        if decode_err then
            client:close()
            return nil, decode_err
        end
        process(data)
    end
end

local _, close_err = client:close()
if close_err then return nil, close_err end
```



#### Message Object


| Field | Type | Description |
|-------|------|-------------|
| `type` | string | `"text"` or `"binary"` |
| `data` | string? | Message content (nil for unknown payload types) |



### Closing Connection


Close the connection with an optional status code and reason:

```lua
local _, close_err = client:close(websocket.CLOSE_CODES.NORMAL, "Session ended")
if close_err then return nil, close_err end

-- Omitting both arguments also uses normal close code 1000.
-- Use INTERNAL_ERROR with an application-owned reason for a failed session.
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `code` | number | Close code (1000-4999), default 1000 |
| `reason` | string | Close reason (optional) |

The call yields until the close command completes. Success returns no values; a close failure returns `nil, error`. Capture two results when checking it, because the error is the second result. Values outside the accepted numeric range are ignored and the default code `1000` is used.

The receive channel is owned by the client; do not close it directly. A remote terminal event closes the channel. Calling `client:close()` unsubscribes the receive channel and stops the client-side producer, so use it promptly rather than relying on process shutdown cleanup.



#### Message Types


```lua
-- Numeric (for send)
websocket.TEXT    -- 1
websocket.BINARY  -- 2

-- Compatibility string constants
websocket.TYPE_TEXT    -- "text"
websocket.TYPE_BINARY  -- "binary"
websocket.TYPE_PING    -- "ping"
websocket.TYPE_PONG    -- "pong"
websocket.TYPE_CLOSE   -- "close"
```

Receive-channel message objects use only `"text"` and `"binary"`. Ping and pong frames are handled by the transport, and a terminal event closes the channel instead of producing a `"close"` message object.



#### Compression Modes


```lua
websocket.COMPRESSION.DISABLED         -- 0 (no compression)
websocket.COMPRESSION.CONTEXT_TAKEOVER -- 1 (sliding window)
websocket.COMPRESSION.NO_CONTEXT       -- 2 (per-message)
```



#### Close Codes


| Constant | Code | Description |
|----------|------|-------------|
| `NORMAL` | 1000 | Normal closure |
| `GOING_AWAY` | 1001 | Server shutting down |
| `PROTOCOL_ERROR` | 1002 | Protocol error |
| `UNSUPPORTED_DATA` | 1003 | Unsupported data type |
| `RESERVED` | 1004 | Reserved |
| `NO_STATUS` | 1005 | No status received |
| `ABNORMAL_CLOSURE` | 1006 | Connection lost |
| `INVALID_PAYLOAD` | 1007 | Invalid frame payload |
| `POLICY_VIOLATION` | 1008 | Policy violation |
| `MESSAGE_TOO_BIG` | 1009 | Message too large |
| `MANDATORY_EXTENSION` | 1010 | Required extension not negotiated |
| `INTERNAL_ERROR` | 1011 | Server error |
| `SERVICE_RESTART` | 1012 | Server restarting |
| `TRY_AGAIN_LATER` | 1013 | Server overloaded |
| `BAD_GATEWAY` | 1014 | Gateway error |
| `TLS_HANDSHAKE` | 1015 | TLS handshake failure |

```lua
local _, close_err = client:close(websocket.CLOSE_CODES.NORMAL, "Done")
if close_err then return nil, close_err end
```



#### Real-Time Chat


```lua
local json = require("json")

local function connect_chat(room_id, token, on_message)
    local client, err = websocket.connect("wss://chat.example.com/ws", {
        headers = {["Authorization"] = "Bearer " .. token}
    })
    if err then
        return nil, err
    end

    -- Join room. Runtime v0.3.32a does not expose transport send failures.
    local join_payload, encode_err = json.encode({
        type = "join",
        room = room_id
    })
    if encode_err then
        client:close()
        return nil, encode_err
    end
    client:send(join_payload)

    -- Message loop
    local ch, channel_err = client:channel()
    if channel_err then
        client:close()
        return nil, channel_err
    end
    while true do
        local msg, ok = ch:receive()
        if not ok then break end

        local data, decode_err = json.decode(msg.data)
        if decode_err then
            client:close()
            return nil, decode_err
        end
        on_message(data)
    end

    local _, close_err = client:close()
    if close_err then return nil, close_err end
    return true
end
```



#### Price Stream with Keep-Alive


```lua
local json = require("json")
local time = require("time")

local client, err = websocket.connect("wss://stream.example.com/prices")
if err then
    return nil, err
end

local subscribe_payload, encode_err = json.encode({
    action = "subscribe",
    symbols = {"BTC-USD", "ETH-USD"}
})
if encode_err then
    client:close()
    return nil, encode_err
end
client:send(subscribe_payload)

local ch, channel_err = client:channel()
if channel_err then
    client:close()
    return nil, channel_err
end

local heartbeat, heartbeat_err = time.after("30s")
if heartbeat_err then
    client:close()
    return nil, heartbeat_err
end

while true do
    local r = channel.select {
        ch:case_receive(),
        heartbeat:case_receive()
    }

    if r.channel == heartbeat then
        client:ping()
        heartbeat, heartbeat_err = time.after("30s")
        if heartbeat_err then
            client:close()
            return nil, heartbeat_err
        end
    elseif not r.ok then
        break  -- Connection closed
    else
        local price, decode_err = json.decode(r.value.data)
        if decode_err then
            client:close()
            return nil, decode_err
        end
        update_price(price.symbol, price.value)
    end
end

local _, close_err = client:close()
if close_err then return nil, close_err end
```



### Permissions


WebSocket connections are evaluated against the active security policy.



#### Security Actions


| Action | Resource | Description |
|--------|----------|-------------|
| `websocket.connect` | - | Allow/deny WebSocket connections |
| `websocket.connect.url` | URL | Allow/deny connections to specific URLs |

See [Security Model](system/security.md) for policy configuration.



### Errors


| Condition | Kind | Retryable |
|-----------|------|-----------|
| Connections disabled | `errors.PERMISSION_DENIED` | no |
| URL not allowed | `errors.PERMISSION_DENIED` | no |
| No context | `errors.INTERNAL` | no |
| Connection failed | `errors.INTERNAL` | yes |
| Invalid connection ID returned by the dispatcher | `errors.INTERNAL` | no |
| Subscription failed | `errors.INTERNAL` | yes |
| Missing process context during subscription | `errors.INTERNAL` | no |
| Close failed | `errors.INTERNAL` | no |

An empty URL, a non-table options value, invalid argument types, and a missing execution context or process PID when requesting the receive channel raise Lua errors. They are not returned as structured errors. Runtime `v0.3.32a` does not expose send or ping transport failures to Lua callers.

```lua
local client, err = websocket.connect(url)
if err then
    if errors.is(err, errors.PERMISSION_DENIED) then
        print("Access denied:", err:message())
    elseif err:retryable() then
        print("Temporary error:", err:message())
    end
    return nil, err
end
```

See [Error Handling](lua/core/errors.md) for working with errors.



---

# "HTML Sanitization"

## HTML Sanitization

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="workflow"/>

The `html` module sanitizes untrusted HTML with policies based on [bluemonday](https://github.com/microcosm-cc/bluemonday).

Sanitization parses an HTML fragment and filters it through an allowlist policy. Elements and attributes that the policy does not allow are removed, and the remaining fragment is normalized during serialization.

This is an API reference. Constructor blocks are self-contained policy snippets; later method blocks are partial configuration snippets that assume `policy` is an already-created policy. Sanitized output is suitable only for an HTML element-content context. It is not safe for JavaScript, CSS, URL, or HTML attribute interpolation; use an encoder for the actual output context.



### Loading


```lua
local html = require("html")
```

Add `html` to the executable entry's `modules:` list before requiring it.



### Preset Policies


The module provides three preset policy constructors:

| Policy | Use Case | Allows |
|--------|----------|--------|
| `new_policy` | Custom sanitization | Nothing (build from scratch) |
| `ugc_policy` | User comments, forums | Common formatting (`p`, `b`, `i`, `a`, lists, etc.) |
| `strict_policy` | Plain text extraction | Nothing (strips all HTML) |

All three constructors return `Policy, nil`; policy construction does not currently fail.



#### Empty Policy


Create an empty policy, then add the elements and attributes it should allow:

```lua
local policy, err = html.sanitize.new_policy()
if err then return nil, err end

policy:allow_elements("p", "strong", "em")
policy:allow_attrs("class"):globally()

local clean = policy:sanitize(user_input)
```

**Returns:** `Policy, error`



#### User Content Policy


Create a policy configured for common user-generated formatting:

```lua
local policy, err = html.sanitize.ugc_policy()
if err then return nil, err end

local safe = policy:sanitize('<p>Hello <strong>world</strong></p>')
-- '<p>Hello <strong>world</strong></p>'

local xss = policy:sanitize('<p>Hello <script>alert("xss")</script></p>')
-- '<p>Hello </p>'
```

**Returns:** `Policy, error`



#### Strict Policy


Create a strict policy that removes HTML and returns plain text:

```lua
local policy, err = html.sanitize.strict_policy()
if err then return nil, err end

local text = policy:sanitize('<p>Hello <b>world</b>!</p>')
-- 'Hello world!'
```

**Returns:** `Policy, error`



#### Allow Elements


Allow specific HTML elements:

```lua
local policy, err = html.sanitize.new_policy()
if err then return nil, err end
policy:allow_elements("p", "strong", "em", "br")
policy:allow_elements("h1", "h2", "h3")
policy:allow_elements("a", "img")

local result = policy:sanitize('<p>Hello <strong>world</strong></p>')
-- '<p>Hello <strong>world</strong></p>'
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `...` | string | Element tag names |

**Returns:** `Policy`



#### Allow Attributes


Start an attribute rule, then apply it with `on_elements()` or `globally()`:

```lua
policy:allow_attrs("href"):on_elements("a")
policy:allow_attrs("src", "alt"):on_elements("img")
policy:allow_attrs("class", "id"):globally()
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `...` | string | Attribute names |

**Returns:** `AttrBuilder`



#### On Specific Elements


Allow attributes only on specified elements:

```lua
policy:allow_elements("a", "img")
policy:allow_attrs("href", "target"):on_elements("a")
policy:allow_attrs("src", "alt", "width", "height"):on_elements("img")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `...` | string | Element tag names |

**Returns:** `Policy`



#### On All Elements


Allow attributes on every permitted element:

```lua
policy:allow_attrs("class"):globally()
policy:allow_attrs("id"):globally()
```

**Returns:** `Policy`



#### With Pattern Matching


Require attribute values to match a regular expression:

```lua
-- Only allow hex colors in style
local builder, err = policy:allow_attrs("style"):matching("^color:#[0-9a-fA-F]{6}$")
if err then
    return nil, err
end
builder:on_elements("span")

policy:sanitize('<span style="color:#ff0000">Red</span>')
-- '<span style="color:#ff0000">Red</span>'

policy:sanitize('<span style="background:red">Bad</span>')
-- '<span>Bad</span>'
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `pattern` | string | Go RE2-compatible regular expression |

**Returns:** `AttrBuilder, error`



#### Standard URLs


Enable the standard URL-handling policy. It requires parseable URLs, permits relative URLs plus `mailto`, `http`, and `https`, and adds `rel="nofollow"` to allowed linking elements:

```lua
policy:allow_elements("a")
policy:allow_attrs("href"):on_elements("a")
policy:allow_standard_urls()
```

**Returns:** `Policy`



#### URL Schemes


Allow specific URL schemes:

```lua
policy:allow_url_schemes("https", "mailto")

policy:sanitize('<a href="https://example.com">OK</a>')
-- '<a href="https://example.com">OK</a>'

policy:sanitize('<a href="javascript:alert(1)">XSS</a>')
-- '<a>XSS</a>'
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `...` | string | Schemes to allow |

**Returns:** `Policy`



#### Relative URLs


Configure whether relative URLs are allowed:

```lua
policy:allow_relative_urls(true)

policy:sanitize('<a href="/page">Link</a>')
-- '<a href="/page">Link</a>'
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `allow` | boolean | Allow relative URLs |

**Returns:** `Policy`



#### Require Parseable URLs


Reject URLs that fail to parse cleanly. With `true`, attribute URLs that the HTML sanitizer cannot parse are stripped instead of passed through.

```lua
policy:require_parseable_urls(true)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `require` | boolean | Require URLs to be parseable |

**Returns:** `Policy`



#### Nofollow Links


Add `rel="nofollow"` to links:

```lua
policy:allow_attrs("href", "rel"):on_elements("a")
policy:allow_url_schemes("https")
policy:require_parseable_urls(true)
policy:require_nofollow_on_links(true)

policy:sanitize('<a href="https://example.com">Link</a>')
-- '<a href="https://example.com" rel="nofollow">Link</a>'
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `require` | boolean | Add nofollow |

**Returns:** `Policy`



#### Noreferrer Links


Add `rel="noreferrer"` to links:

```lua
policy:require_noreferrer_on_links(true)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `require` | boolean | Add noreferrer |

**Returns:** `Policy`



#### External Links in New Tab


Add `target="_blank"` to fully qualified URLs:

```lua
policy:allow_attrs("href", "target"):on_elements("a")
policy:allow_url_schemes("https")
policy:require_parseable_urls(true)
policy:add_target_blank_to_fully_qualified_links(true)

policy:sanitize('<a href="https://example.com">Link</a>')
-- '<a href="https://example.com" target="_blank" rel="noopener">Link</a>'
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `add` | boolean | Add target blank |

**Returns:** `Policy`

When opening untrusted links in a new tab, also enable `require_noreferrer_on_links(true)` to suppress referrer leakage and mitigate opener access.



#### Allow Images


Permit `<img>` with `align`, `alt`, `height`, `width`, and `src`. This helper also enables the standard URL policy but does not allow data URI images.

```lua
policy:allow_images()

policy:sanitize('<img src="photo.jpg" alt="Photo">')
-- '<img src="photo.jpg" alt="Photo">'
```

**Returns:** `Policy`



#### Allow Data URI Images


Permit syntactically valid Base64-encoded `gif`, `jpeg`, `png`, `svg+xml`, or `webp` data URI images. The sanitizer validates the media type and Base64 encoding, not the decoded image contents. Data URIs can carry active content, so enable them only for content whose image data you trust:

```lua
policy:allow_elements("img")
policy:allow_attrs("src"):on_elements("img")
policy:allow_data_uri_images()

local input = '<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAusB9Wl2O9sAAAAASUVORK5CYII=">'
policy:sanitize(input)
-- The data URI is preserved.
```

**Returns:** `Policy`



#### Allow Lists


Permit `ul`, `ol`, `li`, `dl`, `dt`, and `dd`. The helper also allows validated `type` attributes on `ul`, `ol`, and `li`, plus an integer `value` attribute on `li`.

```lua
policy:allow_lists()

policy:sanitize('<ul><li>Item 1</li><li>Item 2</li></ul>')
-- '<ul><li>Item 1</li><li>Item 2</li></ul>'
```

**Returns:** `Policy`



#### Allow Tables


Permit table elements: `table`, `caption`, `col`, `colgroup`, `thead`, `tbody`, `tfoot`, `tr`, `td`, `th`.

```lua
policy:allow_tables()

policy:sanitize('<table><tr><td>Cell</td></tr></table>')
-- '<table><tr><td>Cell</td></tr></table>'
```

**Returns:** `Policy`



#### Allow Standard Attributes


Permit common attributes: `id`, `title`, `dir`, `lang`.

```lua
policy:allow_elements("p")
policy:allow_standard_attributes()

policy:sanitize('<p id="intro" class="text" title="Introduction">Hello</p>')
-- '<p id="intro" title="Introduction">Hello</p>'
```

**Returns:** `Policy`



### Sanitize


Apply a policy to an HTML string:

```lua
local policy, err = html.sanitize.ugc_policy()
if err then return nil, err end
policy:require_nofollow_on_links(true)

local dirty = '<p>Hello</p><script>alert("xss")</script>'
local clean = policy:sanitize(dirty)
-- '<p>Hello</p>'
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `html` | string | HTML to sanitize |

**Returns:** `string`

`sanitize` returns only a string. In runtime `v0.3.32a`, the underlying fragment parser can turn malformed input that it cannot parse into an empty string, and the Lua wrapper cannot distinguish that case from valid input whose content the policy removed. Treat sanitization as output filtering, not input validation; validate required content separately when an empty result matters.



### Errors


| Condition | Kind | Retryable |
|-----------|------|-----------|
| Invalid regex pattern | `errors.INVALID` | no |

See [Error Handling](lua/core/errors.md) for working with errors.



---

# "SQL Database"

## SQL Database

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="io"/>
<secondary-label ref="permissions"/>

The `sql` module runs queries against configured PostgreSQL, MySQL, and SQLite databases. It supports parameterized queries, transactions, prepared statements, and query builders.

This page is an API reference. Its snippets assume a configured database, permission to acquire it, and any tables named by the query. They illustrate individual calls rather than a standalone application. The combined recipe at the end states its additional schema and driver assumptions.

For database configuration, see [Database](system/database.md).



### Loading


```lua
local sql = require("sql")
```



### `sql.get`


Acquire a database connection from the resource registry:

```lua
local db, err = sql.get("app.db:main")
if err then
    return nil, err
end

local function finish(value, primary_err)
    local _, release_err = db:release()
    if primary_err then return nil, primary_err end
    if release_err then return nil, release_err end
    return value
end

local rows, err = db:query("SELECT * FROM users WHERE active = ?", {1})
if err then
    return finish(nil, err)
end

return finish(rows)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | string | Resource ID (e.g., "app.db:main") |

**Returns:** `DB, error`

<note>
Database leases are released during execution-frame cleanup. Call `db:release()` explicitly when database work finishes, especially in long-running operations.
</note>

<note>
Placeholders are passed to the database driver unchanged; the runtime does not rewrite them. SQLite and MySQL use `?`, PostgreSQL uses `$1, $2` — write them in the form your driver expects. The examples below use `?` (SQLite/MySQL). For queries that target more than one engine, build them with the [query builder](#query-builder): `run_with` rewrites placeholders to `$1, $2` when the handle is PostgreSQL, and `to_sql` uses the builder's `placeholder_format`.
</note>



#### Database Types


```lua
sql.type.POSTGRES    -- "postgres"
sql.type.MYSQL       -- "mysql"
sql.type.SQLITE      -- "sqlite"
sql.type.UNKNOWN     -- "unknown"
```



#### Isolation Levels


```lua
sql.isolation.DEFAULT           -- "default"
sql.isolation.READ_UNCOMMITTED  -- "read_uncommitted"
sql.isolation.READ_COMMITTED    -- "read_committed"
sql.isolation.WRITE_COMMITTED   -- "write_committed"
sql.isolation.REPEATABLE_READ   -- "repeatable_read"
sql.isolation.SERIALIZABLE      -- "serializable"
```



#### NULL Value


```lua
local insert = sql.builder.insert("users")
    :columns("name", "email")
    :values("alice", sql.NULL)
```



#### `sql.as.int`


Coerce a value to the SQL integer type.

```lua
local value = sql.as.int(42)
```

**Returns:** `userdata`



#### `sql.as.float`


Coerce a value to the SQL float type.

```lua
local value = sql.as.float(19.99)
```

**Returns:** `userdata`



#### `sql.as.text`


Coerce a value to the SQL text type.

```lua
local value = sql.as.text("hello")
```

**Returns:** `userdata`



#### `sql.as.binary`


Coerce a value to the SQL binary type.

```lua
local value = sql.as.binary("binary data")
```

**Returns:** `userdata`



#### `sql.as.null`


Return the SQL `NULL` marker.

```lua
local value = sql.as.null()
```

**Returns:** `userdata`



#### `sql.builder.select`


Create a `SELECT` query builder.

```lua
local query = sql.builder.select("id", "name")
    :from("users")
    :where({active = 1})
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `columns` | ...string | Column names (optional) |

**Returns:** `SelectBuilder`



#### `sql.builder.insert`


Create an `INSERT` query builder.

```lua
local query = sql.builder.insert("users")
    :columns("name", "email")
    :values("alice", "alice@example.com")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `table` | string | Table name (optional) |

**Returns:** `InsertBuilder`



#### `sql.builder.update`


Create an `UPDATE` query builder.

```lua
local query = sql.builder.update("users")
    :set("status", "active")
    :where({id = 123})
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `table` | string | Table name (optional) |

**Returns:** `UpdateBuilder`



#### `sql.builder.delete`


Create a `DELETE` query builder.

```lua
local query = sql.builder.delete("users")
    :where({active = 0})
    :limit(100)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `table` | string | Table name (optional) |

**Returns:** `DeleteBuilder`



#### `sql.builder.expr`


Create a raw SQL expression for use in `WHERE` or `HAVING` clauses.

```lua
local expr = sql.builder.expr("score BETWEEN ? AND ?", 80, 90)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `sql` | string | SQL expression with ? placeholders |
| `args` | ...any | Bind arguments (optional) |

**Returns:** `Sqlizer`



#### `sql.builder.eq`


Create equality conditions from a table.

```lua
local cond = sql.builder.eq({active = 1, status = "open"})
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `map` | table | {column = value} pairs |

**Returns:** `Sqlizer`



#### `sql.builder.not_eq`


Create inequality conditions from a table.

```lua
local cond = sql.builder.not_eq({status = "closed"})
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `map` | table | {column = value} pairs |

**Returns:** `Sqlizer`



#### `sql.builder.lt`


Create less-than conditions from a table.

```lua
local cond = sql.builder.lt({age = 18})
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `map` | table | {column = value} pairs |

**Returns:** `Sqlizer`



#### `sql.builder.lte`


Create less-than-or-equal conditions from a table.

```lua
local cond = sql.builder.lte({price = 100})
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `map` | table | {column = value} pairs |

**Returns:** `Sqlizer`



#### `sql.builder.gt`


Create greater-than conditions from a table.

```lua
local cond = sql.builder.gt({score = 80})
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `map` | table | {column = value} pairs |

**Returns:** `Sqlizer`



#### `sql.builder.gte`


Create greater-than-or-equal conditions from a table.

```lua
local cond = sql.builder.gte({age = 21})
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `map` | table | {column = value} pairs |

**Returns:** `Sqlizer`



#### `sql.builder.like`


Create `LIKE` conditions from a table.

```lua
local cond = sql.builder.like({name = "john%"})
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `map` | table | {column = value} pairs |

**Returns:** `Sqlizer`



#### `sql.builder.not_like`


Create `NOT LIKE` conditions from a table.

```lua
local cond = sql.builder.not_like({email = "%@spam.com"})
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `map` | table | {column = value} pairs |

**Returns:** `Sqlizer`



#### `sql.builder.and_`


Combine multiple conditions with `AND`.

```lua
local cond = sql.builder.and_({
    sql.builder.eq({active = 1}),
    sql.builder.gt({score = 80})
})
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `conditions` | table | Array of Sqlizer or table conditions |

**Returns:** `Sqlizer`



#### `sql.builder.or_`


Combine multiple conditions with `OR`.

```lua
local cond = sql.builder.or_({
    sql.builder.eq({status = "pending"}),
    sql.builder.eq({status = "active"})
})
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `conditions` | table | Array of Sqlizer or table conditions |

**Returns:** `Sqlizer`



### sqlizer:to_sql


Generates the SQL fragment and bind arguments of a condition.

```lua
local frag, args = sql.builder.eq({active = 1}):to_sql()
```

**Returns:** `string, table`



### builder.question


Use `?` placeholders (default). This format is also available as `sql.builder.default_placeholder`.

```lua
local query = sql.builder.select("*")
    :from("users")
    :placeholder_format(sql.builder.question)
```



#### `sql.builder.dollar`


Use `$1, $2, ...` placeholders.

```lua
local query = sql.builder.select("*")
    :from("users")
    :placeholder_format(sql.builder.dollar)
```



#### `sql.builder.at`


Use `@p1, @p2, ...` placeholders (SQL Server style). Pass this format to `placeholder_format` like the formats above.



#### `sql.builder.colon`


Use `:1, :2, ...` placeholders. Pass this format to `placeholder_format` like the formats above.



### Connection Methods


A connection handle returned by `sql.get()` provides query, transaction, statement, and pool operations.



#### `db:type`


Return the database type constant.

```lua
local dbtype, err = db:type()
```

**Returns:** `string, error`



#### `db:query`


Run a `SELECT` query and return its rows.

```lua
local rows, err = db:query("SELECT id, name FROM users WHERE active = ?", {1})
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `sql` | string | SQL query with ? placeholders |
| `params` | table | Array of bind parameters (optional) |

**Returns:** `table[], error`



#### `db:execute`


Run an `INSERT`, `UPDATE`, or `DELETE` statement.

```lua
local result, err = db:execute("INSERT INTO users (name) VALUES (?)", {"alice"})
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `sql` | string | SQL statement with ? placeholders |
| `params` | table | Array of bind parameters (optional) |

**Returns:** `table, error`

Returns table with fields:
- `last_insert_id` - Last inserted ID
- `rows_affected` - Number of rows affected



#### `db:prepare`


Create a prepared statement for repeated execution.

```lua
local stmt, err = db:prepare("SELECT * FROM users WHERE id = ?")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `sql` | string | SQL with ? placeholders |

**Returns:** `Statement, error`



#### `db:begin`


Begin a database transaction.

```lua
local tx, err = db:begin({
    isolation = sql.isolation.SERIALIZABLE,
    read_only = false
})
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `options` | table | Transaction options (optional) |

Options table fields:
- `isolation` - Isolation level from sql.isolation.* (default: DEFAULT)
- `read_only` - Read-only transaction flag (default: false)

**Returns:** `Transaction, error`



#### `db:release`


Release the database resource back to the pool.

```lua
local ok, err = db:release()
```

**Returns:** `boolean, error`

The operation is idempotent.



#### `db:stats`


Return connection-pool statistics.

```lua
local stats, err = db:stats()
```

**Returns:** `table, error`

Returns table with fields:
- `max_open_connections` - Max allowed open connections
- `open_connections` - Current open connections
- `in_use` - Connections currently in use
- `idle` - Idle connections in pool
- `wait_count` - Total connection wait count
- `wait_duration` - Total wait duration
- `max_idle_closed` - Connections closed due to max idle
- `max_idle_time_closed` - Connections closed due to idle timeout
- `max_lifetime_closed` - Connections closed due to max lifetime



### Prepared Statements


A prepared statement returned by `db:prepare()` can be queried or executed repeatedly.



#### `stmt:query`


Run the prepared statement as a `SELECT` query.

```lua
local rows, err = stmt:query({123})
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `params` | table | Array of bind parameters (optional) |

**Returns:** `table[], error`



#### `stmt:execute`


Run the prepared statement as an `INSERT`, `UPDATE`, or `DELETE` statement.

```lua
local result, err = stmt:execute({"alice"})
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `params` | table | Array of bind parameters (optional) |

**Returns:** `table, error`

Returns table with fields:
- `last_insert_id` - Last inserted ID
- `rows_affected` - Number of rows affected



#### `stmt:close`


Close the prepared statement.

```lua
local ok, err = stmt:close()
```

**Returns:** `boolean, error`



### Transactions


A transaction returned by `db:begin()` provides query, statement, savepoint, commit, and rollback operations.

An active transaction is rolled back automatically during execution-frame cleanup. Commit or roll it back explicitly as soon as its work is complete.



#### `tx:db_type`


Return the database type constant.

```lua
local dbtype, err = tx:db_type()
```

**Returns:** `string, error`



#### `tx:query`


Run a `SELECT` query within the transaction.

```lua
local rows, err = tx:query("SELECT id, name FROM users WHERE active = ?", {1})
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `sql` | string | SQL query with ? placeholders |
| `params` | table | Array of bind parameters (optional) |

**Returns:** `table[], error`



#### `tx:execute`


Run an `INSERT`, `UPDATE`, or `DELETE` statement within the transaction.

```lua
local result, err = tx:execute("INSERT INTO users (name) VALUES (?)", {"alice"})
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `sql` | string | SQL statement with ? placeholders |
| `params` | table | Array of bind parameters (optional) |

**Returns:** `table, error`

Returns table with fields:
- `last_insert_id` - Last inserted ID
- `rows_affected` - Number of rows affected



#### `tx:prepare`


Create a prepared statement within the transaction.

```lua
local stmt, err = tx:prepare("SELECT * FROM users WHERE id = ?")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `sql` | string | SQL with ? placeholders |

**Returns:** `Statement, error`



#### `tx:commit`


Commit the transaction.

```lua
local ok, err = tx:commit()
```

**Returns:** `boolean, error`



#### `tx:rollback`


Roll back the transaction.

```lua
local ok, err = tx:rollback()
```

**Returns:** `boolean, error`



#### `tx:savepoint`


Create a named savepoint within the transaction.

```lua
local ok, err = tx:savepoint("sp1")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | string | Savepoint name (alphanumeric and underscore only) |

**Returns:** `boolean, error`



#### `tx:rollback_to`


Roll back to a named savepoint.

```lua
local ok, err = tx:rollback_to("sp1")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | string | Savepoint name |

**Returns:** `boolean, error`



#### `tx:release`


Release a savepoint.

```lua
local ok, err = tx:release("sp1")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | string | Savepoint name |

**Returns:** `boolean, error`



### SELECT Builder


Build a `SELECT` query one clause at a time.



#### `select:from`


Set the `FROM` clause.

```lua
local query = sql.builder.select("id", "name"):from("users")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `table` | string | Table name |

**Returns:** `SelectBuilder`



#### `select:join`


Add a `JOIN` clause.

```lua
local query = sql.builder.select("*")
    :from("users")
    :join("orders ON orders.user_id = users.id")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `join` | string | JOIN clause with ? placeholders |
| `args` | ...any | Bind arguments (optional) |

**Returns:** `SelectBuilder`



#### `select:left_join`


Add a `LEFT JOIN` clause.

```lua
local query = sql.builder.select("*")
    :from("users")
    :left_join("orders ON orders.user_id = users.id")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `join` | string | JOIN clause with ? placeholders |
| `args` | ...any | Bind arguments (optional) |

**Returns:** `SelectBuilder`



#### `select:right_join`


Add a `RIGHT JOIN` clause.

```lua
local query = sql.builder.select("*")
    :from("users")
    :right_join("orders ON orders.user_id = users.id")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `join` | string | JOIN clause with ? placeholders |
| `args` | ...any | Bind arguments (optional) |

**Returns:** `SelectBuilder`



#### `select:inner_join`


Add an `INNER JOIN` clause.

```lua
local query = sql.builder.select("*")
    :from("users")
    :inner_join("orders ON orders.user_id = users.id")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `join` | string | JOIN clause with ? placeholders |
| `args` | ...any | Bind arguments (optional) |

**Returns:** `SelectBuilder`



#### `select:where`


Add a `WHERE` condition.

```lua
local query = sql.builder.select("*")
    :from("users")
    :where({active = 1})
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `condition` | string\|table\|Sqlizer | WHERE condition |
| `args` | ...any | Bind arguments (optional, when using string) |

The method accepts three formats:
- String: `where("status = ?", "active")`
- Table: `where({status = "active"})`
- Sqlizer: `where(sql.builder.gt({score = 80}))`

**Returns:** `SelectBuilder`



#### `select:order_by`


Add an `ORDER BY` clause.

```lua
local query = sql.builder.select("*")
    :from("users")
    :order_by("name ASC", "created_at DESC")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `columns` | ...string | Column names with optional ASC/DESC |

**Returns:** `SelectBuilder`



#### `select:group_by`


Add a `GROUP BY` clause.

```lua
local query = sql.builder.select("status", "COUNT(*)")
    :from("users")
    :group_by("status")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `columns` | ...string | Column names |

**Returns:** `SelectBuilder`



#### `select:having`


Add a `HAVING` condition.

```lua
local query = sql.builder.select("status", "COUNT(*) as cnt")
    :from("users")
    :group_by("status")
    :having(sql.builder.gt({cnt = 10}))
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `condition` | string\|table\|Sqlizer | HAVING condition |
| `args` | ...any | Bind arguments (optional, when using string) |

**Returns:** `SelectBuilder`



#### `select:limit`


Set the `LIMIT` value.

```lua
local query = sql.builder.select("*")
    :from("users")
    :limit(10)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `n` | integer | Limit value |

**Returns:** `SelectBuilder`



#### `select:offset`


Set the `OFFSET` value.

```lua
local query = sql.builder.select("*")
    :from("users")
    :offset(20)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `n` | integer | Offset value |

**Returns:** `SelectBuilder`



#### `select:columns`


Add columns to the `SELECT` list.

```lua
local query = sql.builder.select():columns("id", "name", "email")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `columns` | ...string | Column names |

**Returns:** `SelectBuilder`



#### `select:distinct`


Add the `DISTINCT` modifier.

```lua
local query = sql.builder.select("status")
    :from("users")
    :distinct()
```

**Returns:** `SelectBuilder`



#### `select:suffix`


Add an SQL suffix.

```lua
local query = sql.builder.select("*")
    :from("users")
    :suffix("FOR UPDATE")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `sql` | string | SQL suffix with ? placeholders |
| `args` | ...any | Bind arguments (optional) |

**Returns:** `SelectBuilder`



#### `select:placeholder_format`


Set the placeholder format.

```lua
local query = sql.builder.select("*")
    :from("users")
    :placeholder_format(sql.builder.dollar)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `format` | userdata | Placeholder format (sql.builder.*) |

**Returns:** `SelectBuilder`



#### `select:to_sql`


Generate the SQL string and bind arguments.

```lua
local sql_str, args = query:to_sql()
```

**Returns:** `string, table` on success; `nil, error` for an invalid builder state



#### `select:run_with`


Create an executor for the query.

```lua
local executor, err = query:run_with(db)
if err then
    return nil, err
end
local rows, err = executor:query()
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `db` | DB\|Transaction | Database or transaction handle |

**Returns:** `QueryExecutor, error`



### INSERT Builder


Build an `INSERT` query one clause at a time.



#### `insert:into`


Set the table name.

```lua
local query = sql.builder.insert():into("users")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `table` | string | Table name |

**Returns:** `InsertBuilder`



#### `insert:columns`


Set the column names.

```lua
local query = sql.builder.insert("users"):columns("name", "email")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `columns` | ...string | Column names |

**Returns:** `InsertBuilder`



#### `insert:values`


Add row values.

```lua
local query = sql.builder.insert("users")
    :columns("name", "email")
    :values("alice", "alice@example.com")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `values` | ...any | Row values |

**Returns:** `InsertBuilder`



#### `insert:set_map`


Set columns and values from a table.

```lua
local query = sql.builder.insert("users")
    :set_map({name = "alice", email = "alice@example.com"})
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `map` | table | {column = value} pairs |

**Returns:** `InsertBuilder`



#### `insert:select`


Insert rows from a `SELECT` query.

```lua
local select_query = sql.builder.select("name", "email"):from("temp_users")
local query = sql.builder.insert("users")
    :columns("name", "email")
    :select(select_query)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `query` | SelectBuilder | SELECT query |

**Returns:** `InsertBuilder`



#### `insert:prefix`


Add an SQL prefix.

```lua
local query = sql.builder.insert("users")
    :prefix("/* audit import */")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `sql` | string | SQL prefix with ? placeholders |
| `args` | ...any | Bind arguments (optional) |

**Returns:** `InsertBuilder`



#### `insert:suffix`


Add an SQL suffix.

```lua
local query = sql.builder.insert("users")
    :columns("name")
    :values("alice")
    :suffix("RETURNING id")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `sql` | string | SQL suffix with ? placeholders |
| `args` | ...any | Bind arguments (optional) |

**Returns:** `InsertBuilder`



#### `insert:options`


Add `INSERT` options.

```lua
local query = sql.builder.insert("users")
    :options("DELAYED", "IGNORE")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `options` | ...string | INSERT options |

**Returns:** `InsertBuilder`



#### `insert:placeholder_format`


Set the placeholder format.

```lua
local query = sql.builder.insert("users")
    :placeholder_format(sql.builder.dollar)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `format` | userdata | Placeholder format (sql.builder.*) |

**Returns:** `InsertBuilder`



#### `insert:to_sql`


Generate the SQL string and bind arguments.

```lua
local sql_str, args = query:to_sql()
```

**Returns:** `string, table` on success; `nil, error` for an invalid builder state



#### `insert:run_with`


Create an executor for the query.

```lua
local executor, err = query:run_with(db)
if err then
    return nil, err
end
local result, err = executor:exec()
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `db` | DB\|Transaction | Database or transaction handle |

**Returns:** `QueryExecutor, error`



### UPDATE Builder


Build an `UPDATE` query one clause at a time.



#### `update:table`


Set the table name.

```lua
local query = sql.builder.update():table("users")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `table` | string | Table name |

**Returns:** `UpdateBuilder`



#### `update:set`


Set a column value.

```lua
local query = sql.builder.update("users")
    :set("status", "active")
    :set("updated_at", sql.builder.expr("NOW()"))
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `column` | string | Column name |
| `value` | any | Column value |

**Returns:** `UpdateBuilder`



#### `update:set_map`


Set multiple columns from a table.

```lua
local query = sql.builder.update("users")
    :set_map({status = "active", login_count = 0})
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `map` | table | {column = value} pairs; values are plain values, `sql.NULL`, or `sql.as.*` (use `set` for expressions) |

**Returns:** `UpdateBuilder`



#### `update:where`


Add a `WHERE` condition.

```lua
local query = sql.builder.update("users")
    :set("status", "active")
    :where({id = 123})
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `condition` | string\|table\|Sqlizer | WHERE condition |
| `args` | ...any | Bind arguments (optional, when using string) |

**Returns:** `UpdateBuilder`



#### `update:order_by`


Add an `ORDER BY` clause.

```lua
local query = sql.builder.update("users")
    :set("rank", 1)
    :order_by("score DESC")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `columns` | ...string | Column names with optional ASC/DESC |

**Returns:** `UpdateBuilder`



#### `update:limit`


Set the `LIMIT` value.

```lua
local query = sql.builder.update("users")
    :set("status", "active")
    :limit(10)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `n` | integer | Limit value |

**Returns:** `UpdateBuilder`



#### `update:offset`


Set the `OFFSET` value.

```lua
local query = sql.builder.update("users")
    :set("status", "active")
    :offset(5)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `n` | integer | Offset value |

**Returns:** `UpdateBuilder`



#### `update:suffix`


Add an SQL suffix.

```lua
local query = sql.builder.update("users")
    :set("status", "active")
    :suffix("RETURNING id")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `sql` | string | SQL suffix with ? placeholders |
| `args` | ...any | Bind arguments (optional) |

**Returns:** `UpdateBuilder`



#### `update:from`


Add a `FROM` clause.

```lua
local query = sql.builder.update("users")
    :set("status", "active")
    :from("other_table")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `table` | string | Table name |

**Returns:** `UpdateBuilder`



#### `update:from_select`


Update rows from a `SELECT` query.

```lua
local select_query = sql.builder.select("*"):from("temp_users")
local query = sql.builder.update("users")
    :set("status", "active")
    :from_select(select_query, "t")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `query` | SelectBuilder | SELECT query |
| `alias` | string | Table alias |

**Returns:** `UpdateBuilder`



#### `update:placeholder_format`


Set the placeholder format.

```lua
local query = sql.builder.update("users")
    :placeholder_format(sql.builder.dollar)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `format` | userdata | Placeholder format (sql.builder.*) |

**Returns:** `UpdateBuilder`



#### `update:to_sql`


Generate the SQL string and bind arguments.

```lua
local sql_str, args = query:to_sql()
```

**Returns:** `string, table` on success; `nil, error` for an invalid builder state



#### `update:run_with`


Create an executor for the query.

```lua
local executor, err = query:run_with(db)
if err then
    return nil, err
end
local result, err = executor:exec()
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `db` | DB\|Transaction | Database or transaction handle |

**Returns:** `QueryExecutor, error`



### DELETE Builder


Build a `DELETE` query one clause at a time.



#### `delete:from`


Set the table name.

```lua
local query = sql.builder.delete():from("users")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `table` | string | Table name |

**Returns:** `DeleteBuilder`



#### `delete:where`


Add a `WHERE` condition.

```lua
local query = sql.builder.delete("users")
    :where({active = 0})
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `condition` | string\|table\|Sqlizer | WHERE condition |
| `args` | ...any | Bind arguments (optional, when using string) |

**Returns:** `DeleteBuilder`



#### `delete:order_by`


Add an `ORDER BY` clause.

```lua
local query = sql.builder.delete("users")
    :where({active = 0})
    :order_by("created_at ASC")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `columns` | ...string | Column names with optional ASC/DESC |

**Returns:** `DeleteBuilder`



#### `delete:limit`


Set the `LIMIT` value.

```lua
local query = sql.builder.delete("users")
    :where({active = 0})
    :limit(100)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `n` | integer | Limit value |

**Returns:** `DeleteBuilder`



#### `delete:offset`


Set the `OFFSET` value.

```lua
local query = sql.builder.delete("users")
    :where({active = 0})
    :offset(10)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `n` | integer | Offset value |

**Returns:** `DeleteBuilder`



#### `delete:suffix`


Add an SQL suffix.

```lua
local query = sql.builder.delete("users")
    :where({active = 0})
    :suffix("RETURNING id")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `sql` | string | SQL suffix with ? placeholders |
| `args` | ...any | Bind arguments (optional) |

**Returns:** `DeleteBuilder`



#### `delete:placeholder_format`


Set the placeholder format.

```lua
local query = sql.builder.delete("users")
    :placeholder_format(sql.builder.dollar)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `format` | userdata | Placeholder format (sql.builder.*) |

**Returns:** `DeleteBuilder`



#### `delete:to_sql`


Generate the SQL string and bind arguments.

```lua
local sql_str, args = query:to_sql()
```

**Returns:** `string, table` on success; `nil, error` for an invalid builder state



#### `delete:run_with`


Create an executor for the query.

```lua
local executor, err = query:run_with(db)
if err then
    return nil, err
end
local result, err = executor:exec()
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `db` | DB\|Transaction | Database or transaction handle |

**Returns:** `QueryExecutor, error`



### Executing Queries


The query executor runs builder-generated queries.



#### `executor:query`


Run the query and return rows for a `SELECT` statement.

```lua
local rows, err = executor:query()
```

**Returns:** `table[], error`



#### `executor:exec`


Run the query and return the result of an `INSERT`, `UPDATE`, or `DELETE` statement.

```lua
local result, err = executor:exec()
```

**Returns:** `table, error`

Returns table with fields:
- `last_insert_id` - Last inserted ID
- `rows_affected` - Number of rows affected



#### `executor:to_sql`


Return the generated SQL and arguments without executing the query.

```lua
local sql_str, args = executor:to_sql()
```

**Returns:** `string, table`



### Permissions


Database access is subject to security policy evaluation.

| Action | Resource | Description |
|--------|----------|-------------|
| `db.get` | Database ID | Acquire database connection |



### Errors


| Condition | Kind | Retryable |
|-----------|------|-----------|
| Empty resource ID | `errors.INVALID` | no |
| Permission denied | `errors.PERMISSION_DENIED` | no |
| Resource not found | `errors.NOT_FOUND` | no |
| Resource not database | `errors.INVALID` | no |
| Invalid parameters | `errors.INVALID` | no |
| SQL syntax error | `errors.UNKNOWN` | nil |
| Statement closed | `errors.INVALID` | no |
| Transaction not active | `errors.INVALID` | no |
| Invalid savepoint name | `errors.INVALID` | no |
| Query execution error | `errors.UNKNOWN` | nil |

See [Error Handling](lua/core/errors.md) for working with errors.



### Combined Partial Recipe


This recipe assumes `app.db:main` is a configured SQLite or MySQL database and already contains `users`, `orders`, and `logs` tables with the referenced columns. It uses `?` placeholders; use `$1`, `$2`, and so on for a PostgreSQL resource. Returned rows depend on the application's data. The surrounding application supplies `report_cleanup_error(err)` so rollback or close failures are observable without replacing the initiating operation error.

```lua
local sql = require("sql")

local db, err = sql.get("app.db:main")
if err then return nil, err end

local function finish(value, primary_err)
    local _, release_err = db:release()
    if primary_err then return nil, primary_err end
    if release_err then return nil, release_err end
    return value
end

-- Direct query
local users, err = db:query("SELECT id, name FROM users WHERE active = ?", {1})
if err then
    return finish(nil, err)
end

for _, user in ipairs(users) do
    print(user.id, user.name)
end

-- Builder pattern
local query = sql.builder.select("u.id", "u.name", "COUNT(o.id) as order_count")
    :from("users u")
    :left_join("orders o ON o.user_id = u.id")
    :where(sql.builder.and_({
        sql.builder.eq({["u.active"] = 1}),
        sql.builder.gte({["u.score"] = 80})
    }))
    :group_by("u.id", "u.name")
    :having(sql.builder.gt({["COUNT(o.id)"] = 0}))
    :order_by("order_count DESC")
    :limit(10)

local executor, build_err = query:run_with(db)
if build_err then
    return finish(nil, build_err)
end
local results, err = executor:query()
if err then
    return finish(nil, err)
end

-- Transaction
local tx, err = db:begin({isolation = sql.isolation.SERIALIZABLE})
if err then
    return finish(nil, err)
end

local _, err = tx:execute("INSERT INTO users (name) VALUES (?)", {"alice"})
if err then
    local _, rollback_err = tx:rollback()
    if rollback_err then report_cleanup_error(rollback_err) end
    return finish(nil, err)
end

local _, commit_err = tx:commit()
if commit_err then
    return finish(nil, commit_err)
end

-- Prepared statements
local stmt, err = db:prepare("INSERT INTO logs (message, level) VALUES (?, ?)")
if err then
    return finish(nil, err)
end

for i = 1, 3 do
    local _, err = stmt:execute({"log message " .. i, "info"})
    if err then
        local _, close_err = stmt:close()
        if close_err then report_cleanup_error(close_err) end
        return finish(nil, err)
    end
end

local _, close_err = stmt:close()
if close_err then
    return finish(nil, close_err)
end

return finish({users = users, ranked_users = results})
```



---

# "Key-Value Store"

## Key-Value Store

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="io"/>
<secondary-label ref="permissions"/>

The `store` module provides key-value storage with optional TTLs. It can hold cached data, sessions, and other temporary state.

This page is an API reference. Its snippets assume a configured store, the permissions listed below, and application-provided values such as `owner` or `new_value`. Snippets after acquisition use an existing live `cache` handle and are not standalone functions.

For store configuration, see [Store](system/store.md).



### Loading


```lua
local store = require("store")
```



### Acquiring a Store


Acquire a store resource by registry ID:

```lua
local cache, err = store.get("app:cache")
if err then
    return nil, err
end

local _, set_err = cache:set("user:123", {name = "Alice"}, 3600)
if set_err then
    cache:release()
    return nil, set_err
end

local user, get_err = cache:get("user:123")

cache:release()
if get_err then return nil, get_err end
return user
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | string | Store resource ID |

**Returns:** `Store, error`



### Storing Values


Store a value with an optional TTL:

```lua
-- Simple set
local _, err = cache:set("user:123:name", "Alice")
if err then return nil, err end

-- Set with TTL (expires in 300 seconds)
local ok, ttl_err = cache:set("session:abc", {user_id = 123, role = "admin"}, 300)
if ttl_err then return nil, ttl_err end
return ok
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `key` | string | Key |
| `value` | any | Value (tables, strings, numbers, booleans) |
| `ttl` | number | TTL in seconds (optional, 0 = no expiry) |

**Returns:** `boolean, error`



### Retrieving Values


Retrieve a value by key:

```lua
local errors = require("errors")

local user, err = cache:get("user:123")
if err then
    if err:kind() == errors.NOT_FOUND then
        return nil -- key missing or expired
    end
    return nil, err
end
return user
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `key` | string | Key to retrieve |

**Returns:** `any, error`

The method returns `nil` and an `errors.NOT_FOUND` error when the key does not exist or has expired.



### Checking Existence


Check whether a key exists without retrieving its value:

```lua
if cache:has("lock:" .. resource_id) then
    return nil, errors.new({ kind = errors.CONFLICT, message = "Resource is locked" })
end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `key` | string | Key to check |

**Returns:** `boolean, error`



### Deleting Keys


Remove a key from the store:

```lua
local deleted, err = cache:delete("session:" .. session_id)
if err then return nil, err end
return deleted
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `key` | string | Key to delete |

**Returns:** `boolean, error`

The method returns `true` when it deletes the key and `false` when the key does not exist.



### Reading Entry Metadata


`entry` returns the value together with its `version` — an opaque string used for optimistic concurrency:

```lua
local e, err = cache:entry("user:123")
if err then return nil, err end
if e then
    print(e.key, e.value, e.version)
end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `key` | string | Key to read |

**Returns:** `Entry, error` — `{key: string, value: any, version: string}`



### Listing Keys


List entries in deterministic key order with pagination:

```lua
local page, err = cache:list({ prefix = "session:", limit = 100 })
if err then return nil, err end
for _, e in ipairs(page.items) do
    print(e.key, e.value)
end

-- next page
if page.has_more then
    local next_page, next_err = cache:list({ prefix = "session:", after = page.cursor })
    if next_err then return nil, next_err end
    page = next_page
end
```

| Option | Type | Description |
|--------|------|-------------|
| `prefix` | string | Only keys with this prefix |
| `after` | string | Continue after this cursor (from a previous page) |
| `limit` | integer | Max items per page |

**Returns:** `Page, error` — `{items: Entry[], cursor: string, has_more: boolean}`



### Conditional Writes


`put` writes a value and returns its new `Entry`. Options enable optimistic concurrency:

```lua
local errors = require("errors")

-- create only if the key does not exist
local e, err = cache:put("lock:job-1", owner, { only_if_absent = true })
if err and err:kind() == errors.ALREADY_EXISTS then
    -- someone else holds it
elseif err then
    return nil, err
end

-- compare-and-set: write only if the version still matches
local cur, read_err = cache:entry("config")
if read_err then return nil, read_err end
local e2, err2 = cache:put("config", new_value, { if_version = cur.version })
if err2 and err2:kind() == errors.CONFLICT then
    -- a concurrent writer changed it; re-read and retry
elseif err2 then
    return nil, err2
end
```

| Option | Type | Description |
|--------|------|-------------|
| `ttl` | number | TTL in seconds |
| `only_if_absent` | boolean | Write only if the key does not exist |
| `if_version` | string | Write only if the current version matches |

`only_if_absent` and `if_version` are mutually exclusive.

**Returns:** `Entry, error`

<warning>
Conditional writes require a store whose <code>info().conditional_put</code> is true (the memory and <code>store.kv.raft</code> stores). On <code>store.kv.crdt</code> and <code>store.sql</code> they return an <code>errors.INVALID</code> error — use <code>store.kv.raft</code> when you need conditional writes.
</warning>



### Store Capabilities


`info` reports the backend and what it supports, so code can adapt to whichever store is bound:

```lua
local info, err = cache:info()
if err then return nil, err end
-- info.backend      -> one of store.backend.* (e.g. "kv.raft")
-- info.consistency  -> one of store.consistency.* (e.g. "linearizable")
-- info.durable / info.list / info.versioned / info.conditional_put / info.ttl  (booleans)
```

**Returns:** `Info, error` — `{id, backend, consistency, durable, list, versioned, conditional_put, ttl}`



#### Constants


| Constant | Values |
|----------|--------|
| `store.backend` | `MEMORY`, `SQL`, `KV_RAFT`, `KV_CRDT`, `UNKNOWN` |
| `store.consistency` | `LINEARIZABLE`, `EVENTUAL`, `LOCAL`, `UNKNOWN` |

```lua
local info, err = cache:info()
if err then return nil, err end
if info.consistency == store.consistency.LINEARIZABLE then
    -- safe to use compare-and-set
end
```



### Store Methods


| Method | Returns | Description |
|--------|---------|-------------|
| `get(key)` | `any, error` | Retrieve value by key |
| `entry(key)` | `Entry, error` | Retrieve value with version metadata |
| `set(key, value, ttl?)` | `boolean, error` | Store value with optional TTL |
| `put(key, value, opts?)` | `Entry, error` | Conditional/versioned write, returns the new entry |
| `list(opts?)` | `Page, error` | Paged listing in key order |
| `has(key)` | `boolean, error` | Check if key exists |
| `delete(key)` | `boolean, error` | Remove key |
| `info()` | `Info, error` | Backend, consistency, and capability flags |
| `release()` | `boolean` | Release store back to pool |



### Permissions


Security policy evaluation applies to store operations.

| Action | Resource | Attributes | Description |
|--------|----------|------------|-------------|
| `store.get` | Store ID | - | Acquire a store resource |
| `store.info` | Store ID | - | Inspect store capabilities |
| `store.key.get` | Store ID | `key` | Read a key value (also `entry`) |
| `store.key.set` | Store ID | `key` | Write a key value (also `put`) |
| `store.key.delete` | Store ID | `key` | Delete a key |
| `store.key.has` | Store ID | `key` | Check key existence |
| `store.key.list` | Store ID | `prefix` | List entries |

Permission denials from `store.get`, `get`, `set`, `delete`, and `has` raise a Lua error. The `info`, `entry`, `list`, and `put` methods instead return an `errors.PERMISSION_DENIED` error. Grant the required actions before calling code that cannot tolerate a raised denial.



### Errors


`store.get()` and all methods on the store handle (`get`, `entry`, `set`, `put`, `list`, `has`, `delete`, `info`) return structured errors (use `err:kind()`), except that a permission denial in `store.get`, `get`, `set`, `has` and `delete` raises a Lua error instead.

| Condition | Kind | Retryable |
|-----------|------|-----------|
| Empty resource ID | `errors.INVALID` | no |
| Resource not found | `errors.INTERNAL` | no |
| Store released | `errors.INVALID` | no |
| Permission denied (`entry`, `put`, `list`, `info`) | `errors.PERMISSION_DENIED` | no |
| `only_if_absent` and key exists | `errors.ALREADY_EXISTS` | no |
| `if_version` mismatch | `errors.CONFLICT` | yes |
| Conditional write on a store without support | `errors.INVALID` | no |

See [Error Handling](lua/core/errors.md) for working with errors.



---

# "Filesystem"

## Filesystem

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="io"/>
<secondary-label ref="permissions"/>

The `fs` module reads, writes, and manages files within configured filesystem volumes.

This page is an API reference. Its snippets assume a configured volume and permission to acquire it. Each block is an isolated operation or partial recipe; application values and callbacks such as `config`, `message`, `process`, and `report_cleanup_error` must already exist. `report_cleanup_error(err)` records a close failure without replacing an operation error that already occurred.

For filesystem configuration, see [Filesystem](system/filesystem.md).



### Loading


```lua
local fs = require("fs")
```



### Acquiring a Volume


Acquire a filesystem volume by registry ID:

```lua
local vol, err = fs.get("app:storage")
if err then
    return nil, err
end

local content, read_err = vol:readfile("/config.json")
if read_err then return nil, read_err end
return content
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | string | Volume registry ID |

**Returns:** `FS, error`

<note>
Volumes do not require explicit release. The system manages them, and a volume becomes unavailable when its filesystem is detached from the registry.
</note>



### Reading Files


Read an entire file:

```lua
local json = require("json")

local vol, get_err = fs.get("app:config")
if get_err then return nil, get_err end

local data, err = vol:readfile("/settings.json")
if err then
    return nil, err
end

local config, decode_err = json.decode(data)
if decode_err then return nil, decode_err end
return config
```

Use `open()` to stream a large file:

```lua
local errors = require("errors")

local file, err = vol:open("/data/large.csv", "r")
if err then
    return nil, err
end

while true do
    local chunk, err = file:read(65536)
    if err then
        if err:kind() == errors.NOT_FOUND then
            break -- EOF
        end
        local _, close_err = file:close()
        if close_err then report_cleanup_error(close_err) end
        return nil, err
    end
    process(chunk)
end

local _, close_err = file:close()
if close_err then return nil, close_err end
```



### Writing Files


Write a string or reader-backed stream to a file:

```lua
local json = require("json")

local vol, get_err = fs.get("app:data")
if get_err then return nil, get_err end

-- Overwrite (default)
local encoded, encode_err = json.encode(config)
if encode_err then return nil, encode_err end
local _, write_err = vol:writefile("/config.json", encoded)
if write_err then return nil, write_err end

-- Append
local _, append_err = vol:writefile("/logs/app.log", message .. "\n", "a")
if append_err then return nil, append_err end

-- Exclusive write (fails if exists)
local ok, err = vol:writefile("/lock.pid", tostring(pid), "wx")
if err then return nil, err end

-- Copy from an open file or another reader-backed value
local source, err = vol:open("/incoming/report.csv", "r")
if err then
    return nil, err
end
local copied, err = vol:writefile("/archive/report.csv", source)
local _, close_err = source:close()
if err then
    if close_err then report_cleanup_error(close_err) end
    return nil, err
end
if close_err then return nil, close_err end
return copied
```

| Mode | Description |
|------|-------------|
| `"w"` | Overwrite (default) |
| `"a"` | Append |
| `"wx"` | Exclusive write (fails if file exists) |

Use a file handle for streaming writes:

```lua
local file, open_err = vol:open("/output/report.txt", "w")
if open_err then return nil, open_err end
local _, header_err = file:write("Header\n")
if header_err then
    local _, close_err = file:close()
    if close_err then report_cleanup_error(close_err) end
    return nil, header_err
end
local _, data_err = file:write("Data: " .. value .. "\n")
if data_err then
    local _, close_err = file:close()
    if close_err then report_cleanup_error(close_err) end
    return nil, data_err
end
local _, sync_err = file:sync()
if sync_err then
    local _, close_err = file:close()
    if close_err then report_cleanup_error(close_err) end
    return nil, sync_err
end
local _, close_err = file:close()
if close_err then return nil, close_err end
```



### Checking Paths


```lua
local vol, get_err = fs.get("app:data")
if get_err then return nil, get_err end

-- Check existence
local exists, exists_err = vol:exists("/cache/results.json")
if exists_err then return nil, exists_err end
if exists then
    return vol:readfile("/cache/results.json")
end

-- Check if directory
local is_dir, isdir_err = vol:isdir(path)
if isdir_err then return nil, isdir_err end
if is_dir then
    process_directory(path)
end

-- Get file info
local info, stat_err = vol:stat("/documents/report.pdf")
if stat_err then return nil, stat_err end
print(info.size, info.modified, info.type)
```

**Stat fields:** `name`, `size`, `mode`, `modified`, `is_dir`, `type`



### Directory Operations


```lua
local vol, get_err = fs.get("app:data")
if get_err then return nil, get_err end

-- Create directory
local _, mkdir_err = vol:mkdir("/uploads/" .. user_id)
if mkdir_err then return nil, mkdir_err end

-- List directory contents
local iter, state = vol:readdir("/documents")
if not iter then return nil, state end
for entry in iter, state do
    print(entry.name, entry.type)
end

-- Remove file or empty directory
local removed, remove_err = vol:remove("/temp/file.txt")
if remove_err then return nil, remove_err end
return removed
```

Entry fields: `name`, `type` ("file" or "directory")

`mkdir` creates one directory and does not create missing parents. `remove` accepts files and empty directories only.



### File Handle Methods


When using `vol:open()` for streaming:

| Method | Description |
|--------|-------------|
| `read(size?)` | Read bytes (default: 4096) |
| `write(data)` | Write string data |
| `seek(whence, offset)` | Set position ("set", "cur", "end") |
| `stat()` | Get file info (same fields as `vol:stat`) |
| `sync()` | Flush to storage |
| `close()` | Release file handle |
| `scanner(split?)` | Create line/word scanner |

Call `close()` after finishing with a file handle.



### Scanner


Use a scanner for line-by-line processing:

```lua
local file, err = vol:open("/data/users.csv", "r")
if err then
    return nil, err
end
local scanner, err = file:scanner("lines")
if err then
    local _, close_err = file:close()
    if close_err then report_cleanup_error(close_err) end
    return nil, err
end

scanner:scan()  -- skip header

while scanner:scan() do
    local line = scanner:text()
    process(line)
end

local scan_err = scanner:err()
if scan_err then
    local _, close_err = file:close()
    if close_err then report_cleanup_error(close_err) end
    return nil, scan_err
end

local _, close_err = file:close()
if close_err then return nil, close_err end
```

Split modes: `"lines"` (default), `"words"`, `"bytes"`, `"runes"`

`scanner:scan()` returns only a boolean. When it returns `false`, call `scanner:err()` to distinguish clean EOF from a tokenization or underlying read failure. `scanner:err()` returns a structured `INTERNAL` error or `nil`; unlike a stream scanner, a file scanner has no separate scan-dispatch error return.



### Constants


```lua
fs.type.FILE      -- "file"
fs.type.DIR       -- "directory"

fs.seek.SET       -- from start
fs.seek.CUR       -- from current
fs.seek.END       -- from end
```



### FS Methods


| Method | Returns | Description |
|--------|---------|-------------|
| `readfile(path)` / `read_file(path)` | `string, error` | Read entire file |
| `writefile(path, data, mode?)` / `write_file(path, data, mode?)` | `boolean, error` | Write a string or reader-backed value |
| `exists(path)` | `boolean, error` | Check if path exists |
| `stat(path)` | `table, error` | Get file info |
| `isdir(path)` | `boolean, error` | Check if directory |
| `mkdir(path)` | `boolean, error` | Create directory |
| `remove(path)` | `boolean, error` | Remove file/empty dir |
| `readdir(path)` | `iterator, state` | List directory (use in generic `for` loop) |
| `open(path, mode)` | `File, error` | Open file handle |
| `chdir(path)` | `boolean, error` | Change working dir |
| `pwd()` | `string, error` | Get working dir |



### Permissions


Security policy evaluation applies when a volume is acquired.

| Action | Resource | Description |
|--------|----------|-------------|
| `fs.get` | Volume ID | Acquire filesystem volume |



### Errors


| Condition | Kind | Retryable |
|-----------|------|-----------|
| Empty path | `errors.INVALID` | unspecified |
| Path contains a null byte | `errors.INVALID` | no |
| Invalid mode | `errors.INVALID` | unspecified |
| `scanner()` called on a closed file | `errors.INVALID` | unspecified |
| Read, write, seek, stat, or sync called on a closed file | `errors.INTERNAL` | no |
| `close()` called on an already closed file | succeeds | not applicable |
| File-handle read reached EOF | `errors.NOT_FOUND` | unspecified |
| Path not found | `errors.NOT_FOUND` | preserved from the underlying error when available |
| Path already exists | `errors.ALREADY_EXISTS` | unspecified |
| Permission denied | `errors.PERMISSION_DENIED` | no |
| File scanner tokenization or read failed | `errors.INTERNAL` | preserved from the underlying error when available |

`unspecified` means `err:retryable()` returns `nil`; it is not equivalent to `false`.

See [Error Handling](lua/core/errors.md) for working with errors.



---

# "Cloud Storage"

## Cloud Storage

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="io"/>
<secondary-label ref="external"/>
<secondary-label ref="permissions"/>

Access S3-compatible object storage. Upload, download, list, and manage objects, presign download, upload and multipart-part URLs, and read objects with random access.

For storage configuration, see [Cloud Storage](system/cloudstorage.md).



### Loading


```lua
local cloudstorage = require("cloudstorage")
```



### Acquiring Storage


Acquire a cloud storage resource by registry ID:

```lua
local storage, err = cloudstorage.get("app.infra:files")
if err then
    return nil, err
end

local uploaded, upload_err = storage:upload_object("data/file.txt", "content")
storage:release()
if upload_err then return nil, upload_err end
return uploaded
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | string | Storage resource ID |

**Returns:** `Storage, error`



### Uploading Objects


Upload content from a string or file:

```lua
local json = require("json")

local storage, storage_err = cloudstorage.get("app.infra:files")
if storage_err then return nil, storage_err end

-- Upload string content
local body, encode_err = json.encode({
    date = "2024-01-15",
    total = 1234
})
if encode_err then
    storage:release()
    return nil, encode_err
end
local ok, err = storage:upload_object("reports/daily.json", body)
if err then
    storage:release()
    return nil, err
end

-- Upload from file
local fs = require("fs")
local vol, fs_err = fs.get("app:data")
if fs_err then
    storage:release()
    return nil, fs_err
end
local file, open_err = vol:open("/large-file.bin", "r")
if open_err then
    storage:release()
    return nil, open_err
end

local uploaded, file_upload_err = storage:upload_object("backups/large-file.bin", file)
local _, close_err = file:close()

storage:release()
if file_upload_err then
    if close_err then report_cleanup_error(close_err) end
    return nil, file_upload_err
end
if close_err then return nil, close_err end
return uploaded
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `key` | string | Object key/path |
| `content` | string or Reader | Content as string or file reader |
| `options` | table | Optional metadata and conditional write options |

**Returns:** `boolean, error`



#### Upload Options


Attach metadata or guard the write with an options table:

```lua
local uploaded, err = storage:upload_object("reports/daily.json", body, {
    content_type = "application/json",
    cache_control = "max-age=3600",
    metadata = { owner = "team-a", run_id = "1234" },  -- stored as x-amz-meta-*
    only_if_absent = true                              -- fail if the key already exists
})
if err then return nil, err end
return uploaded
```

| Option | Type | Description |
|--------|------|-------------|
| `content_type` | string | MIME type |
| `cache_control` | string | Cache-Control header |
| `content_disposition` | string | Content-Disposition header |
| `content_encoding` | string | Content-Encoding header |
| `metadata` | table | User metadata (string keys/values), stored as `x-amz-meta-*` |
| `headers` | table | Additional request headers (string keys/values) |
| `if_match` | string | Write only if the current object ETag matches |
| `if_none_match` | string | Write only if no object matches the ETag (`"*"` means any) |
| `only_if_absent` | boolean | Write only if the key does not exist (alias for `if_none_match = "*"`) |

A conditional write that fails its precondition returns a `precondition_failed` error.



### Downloading Objects


Download an object to a file writer:

```lua
local fs = require("fs")
local storage, storage_err = cloudstorage.get("app.infra:files")
if storage_err then return nil, storage_err end
local vol, fs_err = fs.get("app:temp")
if fs_err then
    storage:release()
    return nil, fs_err
end

local file, open_err = vol:open("/downloaded.json", "w")
if open_err then
    storage:release()
    return nil, open_err
end
local ok, err = storage:download_object("reports/daily.json", file)
local _, close_err = file:close()
if err then
    if close_err then report_cleanup_error(close_err) end
    storage:release()
    return nil, err
end
if close_err then
    storage:release()
    return nil, close_err
end

-- Download partial content (first 1KB)
local partial, partial_open_err = vol:open("/partial.bin", "w")
if partial_open_err then
    storage:release()
    return nil, partial_open_err
end
local partial_ok, partial_err = storage:download_object("backups/large-file.bin", partial, {
    range = "bytes=0-1023"
})
local _, partial_close_err = partial:close()

storage:release()
if partial_err then
    if partial_close_err then report_cleanup_error(partial_close_err) end
    return nil, partial_err
end
if partial_close_err then return nil, partial_close_err end
return partial_ok
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `key` | string | Object key to download |
| `writer` | Writer | Destination file writer |
| `options.range` | string | Byte range (e.g., "bytes=0-1023") |
| `options.if_match` | string | Download only if the object ETag matches |
| `options.if_none_match` | string | Download only if the ETag does not match |

**Returns:** `boolean, error`

A failed precondition (`if_match`/`if_none_match`) returns a `precondition_failed` error.



### Listing Objects


List objects with optional prefix filtering:

```lua
local storage, storage_err = cloudstorage.get("app.infra:files")
if storage_err then return nil, storage_err end

local result, err = storage:list_objects({
    prefix = "reports/2024/",
    max_keys = 100
})
if err then
    storage:release()
    return nil, err
end

for _, obj in ipairs(result.objects) do
    print(obj.key, obj.size, obj.etag)
end

-- Paginate through large results
local token = nil
repeat
    local page, page_err = storage:list_objects({
        prefix = "logs/",
        max_keys = 1000,
        continuation_token = token
    })
    if page_err then
        storage:release()
        return nil, page_err
    end
    for _, obj in ipairs(page.objects) do
        process(obj)
    end
    token = page.next_continuation_token
    if not page.is_truncated then break end
until false

storage:release()
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `options.prefix` | string | Filter by key prefix |
| `options.max_keys` | integer | Maximum objects to return |
| `options.continuation_token` | string | Pagination token |
| `options.include_owner` | boolean | Include each object's `owner` (`id`, `display_name`) |
| `options.include_versions` | boolean | List object versions; each item includes `version_id` |

**Returns:** `table, error`

Result contains `objects`, `is_truncated`, `next_continuation_token`. Each object has `key`, `size`, `etag`, `storage_class`, and optional `last_modified`, `version_id`, and `owner`.

<note>
In list results <code>content_type</code> is always empty — S3 list operations do not return it. Use <code>head_object</code> to read an object's content type and metadata.
</note>



### Object Metadata


Fetch a single object's metadata without downloading its body:

```lua
local storage, storage_err = cloudstorage.get("app.infra:files")
if storage_err then return nil, storage_err end

local meta, err = storage:head_object("reports/daily.json")
if err then
    storage:release()
    return nil, err
end

print(meta.size, meta.etag, meta.content_type)
for k, v in pairs(meta.metadata) do
    print("meta", k, v)
end

storage:release()
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `key` | string | Object key |

**Returns:** `table, error`

Result fields:

| Field | Type | Description |
|-------|------|-------------|
| `size` | integer | Object size in bytes |
| `etag` | string | Entity tag |
| `content_type` | string | MIME type |
| `cache_control` | string | Cache-Control header |
| `content_disposition` | string | Content-Disposition header |
| `content_encoding` | string | Content-Encoding header |
| `storage_class` | string | Storage class |
| `version_id` | string | Version ID (present when versioning is enabled) |
| `last_modified` | integer | Last modified time (Unix seconds) |
| `metadata` | table | User metadata (`x-amz-meta-*`) |
| `headers` | table | Raw response headers (lowercased keys) |

A missing object returns a `not_found` error.



### Deleting Objects


Remove multiple objects:

```lua
local storage, storage_err = cloudstorage.get("app.infra:files")
if storage_err then return nil, storage_err end

local deleted, err = storage:delete_objects({
    "temp/file1.txt",
    "temp/file2.txt",
    "temp/file3.txt"
})

storage:release()
if err then return nil, err end
return deleted
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `keys` | string[] | Array of object keys to delete |

**Returns:** `boolean, error`

Every key is attempted. Deleting a key that does not exist is not an error. When the provider reports per-key failures, the call returns a single error naming each failed key and its provider error code.



### Download URLs


Create a temporary URL that permits downloading an object without storage credentials. A client can use the URL until it expires.

```lua
local storage, err = cloudstorage.get("app.infra:files")
if err then
    return nil, err
end

local url, err = storage:presigned_get_url("reports/quarterly.pdf", {
    expiration = 3600
})

storage:release()

if err then
    return nil, err
end

-- Return URL to client for direct download
return {download_url = url}
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `key` | string | Object key |
| `options.expiration` | integer | Seconds until URL expires (default: 3600) |

**Returns:** `string, error`



### Upload URLs


Create a temporary URL that permits uploading an object without storage credentials. A client can upload directly to storage until the URL expires.

```lua
local storage, err = cloudstorage.get("app.infra:files")
if err then
    return nil, err
end

local url, err = storage:presigned_put_url("uploads/user-123/avatar.jpg", {
    expiration = 600,
    content_type = "image/jpeg",
    content_length = 1024 * 1024
})

storage:release()

if err then
    return nil, err
end

-- Return URL to client for direct upload
return {upload_url = url}
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `key` | string | Object key |
| `options.expiration` | integer | Seconds until URL expires (default: 3600) |
| `options.content_type` | string | Required content type for upload |
| `options.content_length` | integer | Expected upload size in bytes |

**Returns:** `string, error`



### Multipart Uploads


A single presigned PUT caps an object at 5 GiB. A presigned multipart upload splits a larger object into parts that a client uploads directly, then assembles them server-side. Multipart is a provider capability: S3 implements it, and providers without it return `errors.UNAVAILABLE`.

```lua
local storage = cloudstorage.get("app.infra:files")

local mp, err = storage:create_multipart_upload("backups/huge.zip", {
    content_type = "application/zip",
    metadata = { source = "uploader" },
})
if err then return nil, err end

local urls, err = storage:presigned_part_urls("backups/huge.zip", mp.upload_id, {
    count = 3,
    expiration = 900,
})
if err then
    storage:abort_multipart_upload("backups/huge.zip", mp.upload_id)
    return nil, err
end

-- The client PUTs each url and returns the ETag from the response headers.
local done, err = storage:complete_multipart_upload("backups/huge.zip", mp.upload_id, {
    { part_number = 1, etag = etag1 },
    { part_number = 2, etag = etag2 },
    { part_number = 3, etag = etag3 },
})

storage:release()
```



#### create_multipart_upload


Start a multipart upload for a key.

| Parameter | Type | Description |
|-----------|------|-------------|
| `key` | string | Object key of the final object |
| `options` | table | `content_type`, `cache_control`, `content_disposition`, `content_encoding`, `metadata`, `headers` - same semantics as `upload_object` |

**Returns:** `table, error` - the table carries `upload_id`, which identifies the upload for every later part, complete and abort call.

Conditional writes (`if_match`, `if_none_match`, `only_if_absent`) are not part of the multipart protocol and are not accepted here.



#### presigned_part_urls


Generate presigned PUT URLs for parts of an in-progress upload. Each URL is uploaded to with a plain HTTP PUT; the uploader must keep the `ETag` response header of each part for `complete_multipart_upload`.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `key` | string | required | Object key |
| `upload_id` | string | required | From `create_multipart_upload` |
| `options.parts` | int[] | - | Explicit part numbers (1-10000, no duplicates) |
| `options.count` | int | - | Presign parts `1..count` |
| `options.headers` | table | - | Headers required on each part request; they are signed and must also be sent by the uploader |
| `options.expiration` | int | 3600 | Seconds until the URLs expire |

Exactly one of `parts` or `count` is required, and a single call presigns at most 1000 URLs - presign in pages for very large objects.

**Returns:** `table, error` - an array of `{ part_number, url }`.

Every part except the last must be at least 5 MiB; the provider enforces this at completion time.



#### complete_multipart_upload


Assemble the final object from its uploaded parts. Parts may be reported in any order and are sorted by part number before completion.

| Parameter | Type | Description |
|-----------|------|-------------|
| `key` | string | Object key |
| `upload_id` | string | From `create_multipart_upload` |
| `parts` | table | Array of `{ part_number = int, etag = string }` |

**Returns:** `table, error` - `etag`, plus `version_id` and `location` when the provider reports them. An unknown upload ID returns `errors.NOT_FOUND`.



#### abort_multipart_upload


Discard an in-progress upload and free its stored parts.

| Parameter | Type | Description |
|-----------|------|-------------|
| `key` | string | Object key |
| `upload_id` | string | From `create_multipart_upload` |

**Returns:** `boolean, error`

An upload that is never completed keeps its parts stored, and billed, until it is aborted. Abort on every failure path, and configure a bucket lifecycle rule as a backstop - see [Cloud Storage](system/cloudstorage.md#multipart-uploads).



### Ranged Readers


`open_reader` opens random access over an object using ranged GETs - no local staging and no full download. Its main consumer is [`archive.open`](lua/data/archive.md), which reads multi-GB archives straight out of object storage with bounded memory.

```lua
local archive = require("archive")
local storage = cloudstorage.get("app.infra:files")

local reader, err = storage:open_reader("uploads/huge.zip", {
    block_size = 8 * 1024 * 1024,
    cache_blocks = 4,
})
if err then return nil, err end

local r = assert(archive.open(reader))
for e in r:entries() do
    print(e.name, e.size)
end
r:close()
reader:close()

storage:release()
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `key` | string | required | Object key |
| `options.block_size` | int | 8388608 | Ranged-GET unit in bytes (64 KiB to 128 MiB) |
| `options.cache_blocks` | int | 4 | Resident LRU blocks (1 to 64) |

`block_size * cache_blocks` may not exceed 256 MiB. A missing object returns `errors.NOT_FOUND`.

**Returns:** `Reader, error`

The object's ETag is pinned when the reader opens and sent as `If-Match` on every ranged read, so an object overwritten mid-read fails the read with the provider's precondition error instead of serving a mix of two object generations; `archive` surfaces it as `errors.INTERNAL`. A provider that cannot supply an ETag returns `errors.UNAVAILABLE`; the reader never serves an unpinned object.

Cache-miss reads perform blocking network IO in the calling task and serialize concurrent readers, so sequential per-entry access - the archive pattern - is the intended shape.



#### Reader Methods


| Method | Returns | Description |
|--------|---------|-------------|
| `size()` | `integer` | Object size in bytes, from the open-time stat |
| `key()` | `string` | Object key the reader reads from |
| `close()` | `boolean, error` | Release the block cache; idempotent |

The reader is closed automatically at task scope if it is not closed explicitly.



### Storage Methods


| Method | Returns | Description |
|--------|---------|-------------|
| `upload_object(key, content, opts?)` | `boolean, error` | Upload string or file content |
| `download_object(key, writer, opts?)` | `boolean, error` | Download to file writer |
| `head_object(key)` | `table, error` | Fetch object metadata |
| `list_objects(opts?)` | `table, error` | List objects with prefix filter |
| `delete_objects(keys)` | `boolean, error` | Delete multiple objects |
| `presigned_get_url(key, opts?)` | `string, error` | Generate temporary download URL |
| `presigned_put_url(key, opts?)` | `string, error` | Generate temporary upload URL |
| `create_multipart_upload(key, opts?)` | `table, error` | Start a presigned multipart upload |
| `presigned_part_urls(key, upload_id, opts)` | `table, error` | Presign PUT URLs for upload parts |
| `complete_multipart_upload(key, upload_id, parts)` | `table, error` | Assemble the object from uploaded parts |
| `abort_multipart_upload(key, upload_id)` | `boolean, error` | Discard an in-progress multipart upload |
| `open_reader(key, opts?)` | `Reader, error` | Open a ranged random-access reader |
| `release()` | `boolean` | Release storage resource |



### Permissions


Security policy evaluation applies to cloud storage operations.

| Action | Resource | Description |
|--------|----------|-------------|
| `cloudstorage.get` | Storage ID | Acquire a storage resource |



### Errors


| Condition | Kind | Retryable |
|-----------|------|-----------|
| Empty resource ID | `errors.INVALID` | no |
| Resource not found | `errors.NOT_FOUND` | no |
| Not a cloud storage resource | `errors.INVALID` | no |
| Storage released | `errors.INVALID` | no |
| Empty key | `errors.INVALID` | no |
| Content nil | `errors.INVALID` | no |
| Writer not valid | `errors.INVALID` | no |
| Object not found | `errors.NOT_FOUND` | no |
| Unknown upload ID | `errors.NOT_FOUND` | no |
| Conditional precondition failed | `errors.CONFLICT` | no |
| Object overwritten during a ranged read (surfaced by `archive`) | `errors.INTERNAL` | no |
| Provider does not support multipart uploads | `errors.UNAVAILABLE` | no |
| Provider supplies no ETag for `open_reader` | `errors.UNAVAILABLE` | no |
| Permission denied | raised as a Lua error, not returned | - |
| Provider operation failed | `errors.UNKNOWN` | unset |

See [Error Handling](lua/core/errors.md) for working with errors.



---

# "Message Queue"

## Message Queue

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="io"/>
<secondary-label ref="permissions"/>

The `queue` module publishes messages and processes deliveries from configured distributed queues, including RabbitMQ and other AMQP-compatible brokers.

This page is an API reference. Publishing snippets assume the queue entries and permissions already exist. The consumer section is a partial recipe for a handler invoked by `queue.consumer`; it is not a standalone queue deployment.

For queue configuration, see [Queue](system/queue.md).



### Loading


```lua
local queue = require("queue")
```



### Publishing Messages


Publish a message to a queue by ID:

```lua
local ok, err = queue.publish("app:tasks", {
    action = "send_email",
    user_id = 456,
    template = "welcome"
})
if err then
    return nil, err
end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `queue_id` | string | Queue identifier (format: "namespace:name") |
| `data` | any | Message data (tables, strings, numbers, booleans) |
| `headers` | table | Optional message headers |

**Returns:** `boolean, error`



#### Message Headers


Headers carry routing, priority, and tracing metadata. Keys must be strings, and publisher values may be strings, integers, numbers, or booleans:

```lua
local ok, err = queue.publish("app:notifications", {
    type = "order_shipped",
    order_id = order.id
}, {
    priority = 5,
    correlation_id = request_id
})
if err then return nil, err end
```

Consumers receive every header value as a string. The `x_original_queue`, `x_dead_letter_reason`, `x_dead_letter_time`, and `attempts` keys are reserved for delivery and dead-letter bookkeeping and must not be set by publishers.



### Accessing Delivery Context


Access the current delivery from within a queue consumer:

```lua
local msg, err = queue.message()
if err then
    return nil, err
end

local msg_id, id_err = msg:id()
if id_err then return nil, id_err end
local priority, header_err = msg:header("priority")
if header_err then return nil, header_err end
local all_headers, headers_err = msg:headers()
if headers_err then return nil, headers_err end
```

**Returns:** `Message, error`

This function is available only while a queue consumer is processing a message.



### Message Methods


| Method | Returns | Description |
|--------|---------|-------------|
| `id()` | `string, error` | Unique message identifier |
| `header(key)` | `string, error` | Single header value as a string (nil if missing) |
| `headers()` | `table, error` | All message headers |
| `ack()` | `boolean, error` | Acknowledge processing (single-shot) |
| `nack()` | `boolean, error` | Signal failure for redelivery or dead-letter (single-shot) |

The runtime auto-acks on handler success and auto-nacks on handler error. Call `ack`/`nack` only to settle early. Settlement is single-shot, and a `Message` is invalid after its consumer handler returns.



### Queue Info


```lua
local stats, err = queue.info("app:tasks")
if err then return nil, err end
-- stats may contain: message_count, consumer_count, ready (driver-dependent)
```

**Returns:** `table, error`



### Consumer Pattern


A `queue.consumer` entry binds a queue to the handler referenced by `func`. The handler receives the message payload directly:

```yaml
entries:
  - kind: queue.consumer
    name: email_worker
    queue: app:emails
    func: app:email_handler
```

This fragment assumes `app:emails` and the `app:email_handler` function entry already exist. The function source below assumes the application supplies `deliver_email(payload)` and grants any permissions it needs.

```lua
local queue = require("queue")
local logger = require("logger")

local function main(payload)
    local msg, msg_err = queue.message()
    if msg_err then return nil, msg_err end

    local message_id, id_err = msg:id()
    if id_err then return nil, id_err end

    logger:info("Processing", {
        message_id = message_id,
        to = payload.to
    })

    local ok, send_err = deliver_email(payload)
    if send_err then return nil, send_err end
    return ok
end

return {main = main}
```

Returning an invocation error causes the consumer to nack the unsettled delivery. Redelivery then follows the selected driver's behavior; the built-in dead-letter configuration is not enforced in this release.



### Permissions


Security policy evaluation applies to queue operations.

| Action | Resource | Description |
|--------|----------|-------------|
| `queue.publish` | - | General permission to publish messages |
| `queue.publish.queue` | Queue ID | Publish to specific queue |

The runtime checks the general permission first and the queue-specific permission second.



### Errors


| Condition | Kind | Retryable |
|-----------|------|-----------|
| Queue ID empty | `errors.INVALID` | no |
| Message argument missing or an empty table | `errors.INVALID` | no |
| No delivery context | `errors.INVALID` | no |
| Message released or already settled | `errors.INVALID` | no |
| Publish not allowed | `errors.INVALID` | no |
| Publish failed | `errors.INTERNAL` | no |
| Queue or driver not found for `info` | `errors.INTERNAL` | no |

See [Error Handling](lua/core/errors.md) for working with errors.



### See Also


- [Queue Configuration](system/queue.md) - Queue drivers and entry definitions
- [Queue Consumers Guide](guides/queue-consumers.md) - Consumer patterns and worker pools
- [Process Management](lua/core/process.md) - Process spawning and communication
- [Channels](lua/core/channel.md) - Inter-process communication patterns
- [Functions](lua/core/funcs.md) - Async function invocation



---

# "CDC"

## CDC

<secondary-label ref="storage"/>
<secondary-label ref="stream"/>
<secondary-label ref="nondeterministic"/>

Subscribe to Change Data Capture streams from [`db.cdc.postgres`](system/cdc.md) and [`db.cdc.sqlite`](system/cdc.md) sources. List configured sources, open a stream, and receive row-level change events over a channel. The API is driver-neutral: both kinds return the same source info and the same change events, and differ only in the [capabilities](system/cdc.md#capabilities) they publish.



### Loading


```lua
local cdc = require("cdc")
```



### `list_sources`


List the configured CDC sources the caller is allowed to see:

```lua
local sources, err = cdc.list_sources()
if err then return nil, err end
for _, s in ipairs(sources) do
    print(s.id, s.kind, s.state, s.capabilities.before_images)
end
```

Sources the caller lacks `cdc.source` on are omitted rather than reported as an error.

**Returns:** `table, error`



### `source`


Retrieve one source by its registry entry ID or replication slot name:

```lua
local info, err = cdc.source("app:pg_cdc")
if err then return nil, err end
if info == nil then
    -- no such source
end
```

**Returns:** `table, error` (source info, or `nil` if not found)



### `stream`


Open a change stream on a source. The returned `cdc.Stream` exposes a channel that delivers change events:

```lua
local stream, err = cdc.stream("app:pg_cdc", {
    tables = { "public.users", "public.orders" },
    ops    = { "insert", "update" },
    buffer = 128,
})
if err then return nil, err end

-- The caller owns stream until close(), release(), or task cleanup.
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `name` | string | required | Source name (entry ID) |
| `opts.tables` | []string | - | Filter to these tables (omit for all captured tables) |
| `opts.ops` | []string | - | Filter to these operations: `insert`, `update`, `delete`, `truncate` |
| `opts.buffer` | int | 64 | Backlog item capacity (1-65536) |
| `opts.max_bytes` | int | 1048576 | Backlog byte budget for this subscriber (1 MiB) |
| `opts.snapshot` | bool | entry default | Request the snapshot/live handoff for this stream |
| `opts.after` | string | - | Opaque resume cursor from a previous event's `cursor` |

Unknown option keys are rejected with `errors.INVALID`. Table names are matched case-insensitively against both the qualified relation and the bare table name. Snapshot rows are filtered by `tables` only; `ops` applies to live changes.

A stream receives a snapshot when either `opts.snapshot` is true or the source entry's `snapshot` field is set; snapshot rows arrive first with `op = "snapshot"`, then the stream continues into live changes with no gap. `opts.after` is reserved for drivers that resume from a cursor — every driver shipped today returns `errors.INVALID` ("cdc operation is not supported by this source") for it, including `db.cdc.postgres` when it reports `capture_resume`.

Filters narrow delivery only. Access to a source is granted by the `cdc.subscribe` permission, never by a filter.

**Returns:** `Stream, error`

The Lua delivery channel has a separate fixed capacity of 64. The `buffer` option controls the PostgreSQL source subscription, not that channel.



#### `channel`


Return the channel that receives change events. The first call subscribes to the source and yields; subsequent calls return the same channel. The first call can return a subscription error. Channel `:receive()` returns `value, true` for a change or `nil, false` when the stream ends:

```lua
local stream, stream_err = cdc.stream("app:pg_cdc")
if stream_err then return nil, stream_err end
local ch, subscribe_err = stream:channel()
if subscribe_err then
    stream:close()
    return nil, subscribe_err
end

while true do
    local change, ok = ch:receive()
    if not ok then break end

    if change.op == "snapshot" then
        seed_row(change.table, change.after)
    elseif change.op == "insert" then
        handle_new_user(change.table, change.after)
    elseif change.op == "update" then
        handle_update(change.table, change.before, change.after)
    elseif change.op == "delete" then
        handle_delete(change.table, change.before)
    end
end

local _, close_err = stream:close()
if close_err then return nil, close_err end
```

The stream is lazy: construct it, then call `channel()` before generating the writes it should observe. This is live observation, not replay of changes made before the subscription.

When a source terminates a stream with a failure, the channel delivers an error value before it closes. `receive` is an alias for `channel`.



#### `close`


Stop the subscription and release the stream. The method is idempotent, and the runtime also closes the stream at the end of the task scope. `release` is an alias for `close`.

```lua
local _, err = stream:close()
if err then return nil, err end
```



### Change Event


Each message received on the channel is a change table:

| Field | Description |
|-------|-------------|
| `op` | Operation: `insert`, `update`, `delete`, `snapshot` or `truncate` |
| `schema` | Table schema |
| `table` | Table name |
| `relation` | Qualified relation name |
| `before` | Row state before the change (`update`, `delete`). A full row image is guaranteed only when the source has the `before_images` capability; `db.cdc.postgres` fills it from whatever old tuple the WAL carries, which the table's `REPLICA IDENTITY` controls |
| `after` | Row state after the change (`insert`, `update`, `snapshot`; absent for `delete`) |
| `source` | Source entry ID |
| `source_id` | Source entry ID, as a registry ID |
| `generation` | Source generation that produced the event |
| `cursor` | Opaque per-event position within the source |
| `transaction` | Transaction identifier, when the driver reports one |
| `lsn` | Log sequence number of the change (`db.cdc.postgres`) |
| `commit_lsn` | LSN of the committing transaction (when applicable) |
| `xid` | Transaction ID (when applicable) |
| `unchanged` | Columns whose value was not transmitted (unchanged TOAST values) |
| `error` | Driver-reported error description carried on the event |

`before` and `after` are row maps keyed by column name.



### Source Info


`cdc.source` and each entry of `cdc.list_sources` return the same record:

| Field | Description |
|-------|-------------|
| `id` | Entry ID |
| `kind` | `db.cdc.postgres` or `db.cdc.sqlite` |
| `name` | Source name (the entry ID) |
| `state` | `unknown`, `starting`, `running`, `faulted` or `stopped` |
| `generation` | Current source generation |
| `epoch` | Same value as `generation` |
| `engine` | Engine name, when the driver reports one |
| `db_resource` | Observed SQL resource entry ID (`db.cdc.sqlite`) |
| `slot` | Replication slot name (`db.cdc.postgres`) |
| `publication` | Postgres publication, when configured |
| `tables` | Captured tables, when configured |
| `streaming` | `db.cdc.sqlite`: whether the source is running; `db.cdc.postgres`: the entry's `streaming` protocol setting |
| `failover` | Failover slot mode (`db.cdc.postgres`) |
| `temporary` | Temporary slot (`db.cdc.postgres`) |
| `snapshot` | Entry-level snapshot default |
| `faulted` | Whether the source is in the `faulted` state |
| `error` | Last source error, when one is recorded |
| `admission` | `active`, `snapshots`, `reserved_bytes`, `rejected` |
| `capabilities` | `snapshot`, `capture_resume`, `replayable`, `captures_external_writes`, `before_images`, `coalesced` |

Branch on `capabilities` rather than on `kind`:

```lua
local info = cdc.source("app:changes")
if not info.capabilities.before_images then
    -- before is not a guaranteed full row image; keep your own last-known state
end
```

See [CDC sources](system/cdc.md#source-info) for field semantics.



### Permissions


| Action | Resource | Description |
|--------|----------|-------------|
| `cdc.source` | Source entry ID | `cdc.source`; also filters `cdc.list_sources` |
| `cdc.subscribe` | Source entry ID | `cdc.stream`, checked again when the subscription is established |

A denied action returns `errors.PERMISSION_DENIED`.



### Errors


| Condition | Kind |
|-----------|------|
| No context | `errors.INTERNAL` |
| Source name required | `errors.INVALID` |
| Invalid or unknown stream option | `errors.INVALID` |
| `after` on a source without `capture_resume` | `errors.INVALID` |
| Source not registered | `errors.NOT_FOUND` |
| Source not started or replacing | `errors.UNAVAILABLE` |
| Subscription capacity exhausted | `errors.UNAVAILABLE` |
| Permission denied | `errors.PERMISSION_DENIED` |

See [Error Handling](lua/core/errors.md) for working with errors.



### See Also


- [Change Data Capture](system/cdc.md) - Source configuration and capabilities
- [Channel](lua/core/channel.md) - Channel semantics
- [Database](system/database.md) - SQL database services



---

# "System"

## System

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="permissions"/>

The `system` module reports runtime, memory, process, host, supervisor, and cluster state. It also exposes selected runtime controls.

This is an API reference. Most snippets show one isolated operation; controls such as shutdown, runtime tuning, and distributed locks require explicit policy authorization and application-specific failure handling.



### Loading


```lua
local system = require("system")
```



### Shutdown


Request system shutdown with an exit code. Calling this function from any process or actor terminates the entire system:

```lua
local ok, err = system.exit(0)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `code` | integer | Exit code (0 = success), defaults to 0 |

**Returns:** `boolean, error`



### Listing Modules


List the loaded Lua modules and their metadata:

```lua
local mods, err = system.modules()
```

**Returns:** `table[], error`

Each module table contains:

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Module name |
| `description` | string | Module description |
| `class` | string[] | Module classification tags |



### Deployment Sources


The `system.source` sub-table reads the normalized deployment baseline: the entry set produced by the sources the application was assembled from, before any registry history is applied.

```lua
local loaded, err = system.source.load()
```

**Returns:** `table, error`

| Field | Type | Description |
|-------|------|-------------|
| `owners` | string[] | Source owners authoritative over the baseline entries |
| `entries` | table[] | Baseline entries with `id`, `kind`, `meta`, `data` |

`owners` is sorted with the application owner first, then the remaining owners alphabetically. The application owner is the string `"application"`.

```lua
local loaded, err = system.source.load()
if err then return nil, err end

for _, owner in ipairs(loaded.owners) do
    print(owner)
end

for _, entry in ipairs(loaded.entries) do
    print(entry.id, entry.kind)
end
```

The load is taken from one stable source generation, so entries and owners always describe the same baseline. Filesystem paths behind each source are runtime-private and are not exposed; a failed load reports a generic internal error rather than leaking the backing path.

**Permission:** `system.read` on `sources`



### Memory Statistics


Read detailed memory statistics:

```lua
local stats, err = system.memory.stats()
```

**Returns:** `table, error`

The statistics table contains:

| Field | Type | Description |
|-------|------|-------------|
| `alloc` | number | Bytes allocated and in use |
| `total_alloc` | number | Cumulative bytes allocated |
| `sys` | number | Bytes obtained from system |
| `heap_alloc` | number | Bytes allocated on heap |
| `heap_sys` | number | Bytes obtained for heap from system |
| `heap_idle` | number | Bytes in idle spans |
| `heap_in_use` | number | Bytes in non-idle spans |
| `heap_released` | number | Bytes released to OS |
| `heap_objects` | number | Number of allocated heap objects |
| `stack_in_use` | number | Bytes used by stack allocator |
| `stack_sys` | number | Bytes obtained for stack from system |
| `mspan_in_use` | number | Bytes of mspan structures in use |
| `mspan_sys` | number | Bytes obtained for mspan from system |
| `num_gc` | number | Number of completed GC cycles |
| `next_gc` | number | Target heap size for next GC |



### Current Allocation


Read the number of bytes currently allocated:

```lua
local bytes, err = system.memory.allocated()
```

**Returns:** `number, error`



### Heap Objects


Read the number of allocated heap objects:

```lua
local count, err = system.memory.heap_objects()
```

**Returns:** `number, error`



### Memory Limit


Set the memory limit and return its previous value:

```lua
local prev, err = system.memory.set_limit(1024 * 1024 * 100)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `limit` | integer | Memory limit in bytes, -1 for unlimited |

**Returns:** `number, error`

Read the current memory limit:

```lua
local limit, err = system.memory.get_limit()
```

**Returns:** `number, error`



### Force GC


Run garbage collection immediately:

```lua
local ok, err = system.gc.collect()
```

**Returns:** `boolean, error`



### GC Target Percentage


Set the garbage-collection target percentage and return its previous value. A value of 100 triggers collection when the heap doubles:

```lua
local prev, err = system.gc.set_percent(200)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `percent` | integer | GC target percentage |

**Returns:** `number, error`

Read the current garbage-collection target percentage:

```lua
local percent, err = system.gc.get_percent()
```

**Returns:** `number, error`



### Goroutine Count


Read the number of active goroutines:

```lua
local count, err = system.runtime.goroutines()
```

**Returns:** `number, error`



### GOMAXPROCS


Read or set the `GOMAXPROCS` value:

```lua
-- Get current value
local current, err = system.runtime.max_procs()

-- Set new value
local prev, err = system.runtime.max_procs(4)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `n` | integer | If provided, sets GOMAXPROCS (must be > 0) |

**Returns:** `number, error`



### CPU Count


Read the number of logical CPUs:

```lua
local cpus, err = system.runtime.cpu_count()
```

**Returns:** `number, error`



### Process ID


Read the current operating-system process ID:

```lua
local pid, err = system.process.pid()
```

**Returns:** `number, error`



### Hostname


Read the system hostname:

```lua
local hostname, err = system.process.hostname()
```

**Returns:** `string, error`



### Working Directory


Read the runtime's current working directory:

```lua
local dir, err = system.process.cwd()
```

**Returns:** `string, error`



### Process Hosts


List process hosts with worker and queue statistics:

```lua
local hosts, err = system.hosts.list()
```

**Returns:** `table[], error`

Each host table contains:

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Host registry ID |
| `workers` | number | Worker pool size |
| `processes` | number | Active processes on this host |
| `executed` | number | Total steps executed |
| `stolen` | number | Steps stolen from other hosts |
| `queue_depth` | number | Pending items in the host queue |

List processes running on a specific host:

```lua
local procs, err = system.hosts.processes("app:host")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `host_id` | string | Host registry ID |

**Returns:** `table[], error`

Each process table contains:

| Field | Type | Description |
|-------|------|-------------|
| `pid` | string | Process ID |
| `host` | string | Host ID |
| `source` | string | Source entry ID |
| `state` | string | Process state |
| `steps` | number | Steps executed |
| `started_at` | number | Start timestamp (nanoseconds) |
| `parent` | string | Parent PID (omitted if none) |
| `actor_id` | string | Actor ID (omitted if none) |
| `stats` | table | Process-specific stats (optional) |



### Service State


Read the state of a supervised service:

```lua
local state, err = system.supervisor.state("namespace:service")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `service_id` | string | Service ID (e.g., "namespace:service") |

**Returns:** `table, error`

The state table contains:

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Service ID |
| `status` | string | Current status |
| `desired` | string | Desired status |
| `retry_count` | number | Number of retries |
| `last_update` | number | Last update timestamp (nanoseconds) |
| `started_at` | number | Start timestamp (nanoseconds) |
| `details` | string | Optional details (formatted) |



### All Service States


List the states of all supervised services:

```lua
local states, err = system.supervisor.states()
```

**Returns:** `table[], error`

Each state table has the same format as `system.supervisor.state()`.



### Cluster Primitives


The `system.node`, `system.cluster`, `system.raft`, and `system.lock` sub-tables expose the clustering layer. They are most useful when [clustering is enabled](guides/cluster.md); on a standalone node they degrade predictably — `system.raft.*` reports "raft not available", `system.cluster` reports just the local node, and `system.lock` requires the Raft-backed KV store that clustering provides.

Read calls report this node's local view of committed state and do not block on the network.



#### Node Identity


`system.node` reports the current node's identity in the cluster.

```lua
local id, err = system.node.id()      -- this node's ID
local addr, err = system.node.addr()  -- advertised network address
local role, err = system.node.role()  -- "leader" | "voter" | "standby" | "non-member"
```

| Function | Returns | Notes |
|----------|---------|-------|
| `system.node.id()` | `string, error` | Node ID from the relay context |
| `system.node.addr()` | `string, error` | Advertised address (e.g. `10.0.0.1:7946`); errors if membership is unavailable |
| `system.node.role()` | `string, error` | Raft role of this node; returns `"non-member"` (no error) when Raft is not running |

**Permission:** `system.read` on `node`.



#### Cluster Membership


`system.cluster` reports cluster membership and the current leader.

```lua
local members, err = system.cluster.members()  -- array of node tables
local leader, err = system.cluster.leader()    -- leader node ID, or "" if unknown
local n, err = system.cluster.size()           -- count of visible members
```

`system.cluster.members()` returns an array of node tables. The local node is included once and sorts first.

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Node ID |
| `is_local` | boolean | True for the calling node |
| `addr` | string | Advertised address (omitted when unknown) |
| `meta` | table | String-to-string gossip metadata (omitted when none) |

| Function | Returns | Notes |
|----------|---------|-------|
| `system.cluster.members()` | `table[], error` | Errors if no membership information is reachable |
| `system.cluster.leader()` | `string, error` | Current Raft leader's ID; `""` (no error) when the leader is unknown or Raft is absent |
| `system.cluster.size()` | `number, error` | Count of visible members; `0` when no membership info is available |

**Permission:** `system.read` on `cluster`.



#### Raft State


`system.raft` reads this node's local view of the Raft consensus core. Every function returns `nil, error` ("raft not available") when Raft is not running on this node.

```lua
local leader, err = system.raft.is_leader()      -- boolean
local member, err = system.raft.is_member()      -- boolean: voter or standby
local role, err = system.raft.role()             -- same values as system.node.role()
local term, err = system.raft.term()             -- current Raft term
local idx, err = system.raft.commit_index()      -- highest committed log index
local stats, err = system.raft.stats()           -- raw stats map (string -> string)
```

| Function | Returns | Notes |
|----------|---------|-------|
| `system.raft.is_leader()` | `boolean, error` | True iff this node is the current leader |
| `system.raft.is_member()` | `boolean, error` | True iff this node is a voter or standby in the committed configuration |
| `system.raft.role()` | `string, error` | `"leader"` / `"voter"` / `"standby"` / `"non-member"` |
| `system.raft.term()` | `number, error` | Current term; `0` if unavailable from stats |
| `system.raft.commit_index()` | `number, error` | Highest committed log index on this node |
| `system.raft.stats()` | `table, error` | Full raw stats map; keys and values are strings |

**Permission:** `system.read` on `raft`, except `system.raft.stats()` which requires `system.read` on `raft_stats`.



#### Distributed Locks


`system.lock` provides cluster-wide mutual exclusion. A lock is a globally unique name owned by the calling process. It is built on the Raft-replicated system KV store, so at most one holder can exist across the cluster, and the lock auto-releases when the holder process exits or its node leaves — there is no stuck lock to clean up.

```lua
local ok, err = system.lock.acquire("orders.migration")
if not ok then
  -- err has kind errors.ALREADY_EXISTS when another process holds the lock.
  -- Apply the caller's retry and backoff policy for that case if needed.
  return nil, err
end

-- critical section: only one holder cluster-wide
local released, release_err = system.lock.release("orders.migration")
if release_err then
  return nil, release_err
end
return released
```

Acquisition is fail-fast: when a lock is already held, the call returns `false` immediately instead of blocking. Callers provide any required retry and backoff. Only the current holder can release a lock; a release attempt by another process is a no-op.

| Function | Returns | Outcomes |
|----------|---------|----------|
| `system.lock.acquire(name)` | `boolean, error` | `true, nil` acquired; `false, error` already held (kind `errors.ALREADY_EXISTS`); `nil, error` on failure |
| `system.lock.release(name)` | `boolean, error` | `true, nil` released; `false, nil` not held or held by another process; `nil, error` on failure |

| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | string | Cluster-wide lock name |

**Permission:** `system.lock` on the lock `name` (so policy can restrict which names a caller may lock).



### Permissions


Security policy evaluation applies to system operations.

| Action | Resource | Description |
|--------|----------|-------------|
| `system.read` | `memory` | Read memory statistics |
| `system.read` | `memory_limit` | Read memory limit |
| `system.control` | `memory_limit` | Set memory limit |
| `system.read` | `gc_percent` | Read GC percentage |
| `system.gc` | `gc` | Force garbage collection |
| `system.gc` | `gc_percent` | Set GC percentage |
| `system.read` | `goroutines` | Read goroutine count |
| `system.read` | `gomaxprocs` | Read GOMAXPROCS |
| `system.control` | `gomaxprocs` | Set GOMAXPROCS |
| `system.read` | `cpu` | Read CPU count |
| `system.read` | `pid` | Read process ID |
| `system.read` | `hostname` | Read hostname |
| `system.read` | `cwd` | Read working directory |
| `system.read` | `hosts` | List hosts / host processes |
| `system.read` | `modules` | List loaded modules |
| `system.read` | `sources` | Load the deployment source baseline |
| `system.read` | `supervisor` | Read supervisor state |
| `system.read` | `node` | Read this node's identity |
| `system.read` | `cluster` | Read cluster membership and leader |
| `system.read` | `raft` | Read Raft state |
| `system.read` | `raft_stats` | Read the raw Raft stats map |
| `system.lock` | `<lock name>` | Acquire or release a distributed lock |
| `system.exit` | - | Trigger system shutdown |



### Errors


| Condition | Kind | Retryable |
|-----------|------|-----------|
| Permission denied (`system.source.load`, `system.lock.*`) | `errors.PERMISSION_DENIED` | no |
| Permission denied (all other calls) | `errors.INVALID` | no |
| Invalid argument | `errors.INVALID` | no |
| Missing required argument | `errors.INVALID` | no |
| Code manager unavailable | `errors.INTERNAL` | no |
| Service info unavailable | `errors.INTERNAL` | no |
| OS error (hostname, cwd) | `errors.INTERNAL` | no |
| Raft not running on this node | `errors.INTERNAL` | no |
| Membership unavailable | `errors.INTERNAL` | no |
| Lock already held | `errors.ALREADY_EXISTS` | no |
| Lock service unavailable (no Raft on this node) | `errors.INTERNAL` | no |

See [Error Handling](lua/core/errors.md) for working with errors.



---

# "Environment Variables"

## Environment Variables

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="permissions"/>

The `env` module reads and updates environment variables exposed by the runtime.

This is an API reference. Its snippets are isolated operations and assume the named variables and security policies already exist.

Variables must be defined in the [Environment System](system/env.md) before they can be accessed. The system controls which storage backends (OS, file, memory) provide values and whether variables are read-only.



### Loading


```lua
local env = require("env")
```



### `get`


Retrieve an environment variable.

```lua
-- Get database connection string
local db_url = env.get("DATABASE_URL")
if not db_url then
    return nil, errors.new({ kind = errors.INVALID, message = "DATABASE_URL not configured" })
end

local port, port_err = get_or("PORT", "8080")
if port_err then return nil, port_err end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `key` | string | Variable name |

**Returns:** `string, error`

The function returns `nil, error` when the variable does not exist.



### `set`


Set an environment variable.

```lua
-- Set runtime configuration
local updated, set_err = env.set("APP_MODE", "production")
if set_err then return nil, set_err end
return updated
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `key` | string | Variable name |
| `value` | string | Value to set |

**Returns:** `boolean, error`



### `get_all`


Retrieve all environment variables accessible to the caller.

```lua
local logger = require("logger")

local vars, vars_err = env.get_all()
if vars_err then return nil, vars_err end

-- Log names only. Values such as connection URLs may contain credentials even
-- when their keys do not include words like SECRET or KEY.
local accessible_keys = {}
for key in pairs(vars) do table.insert(accessible_keys, key) end
logger:debug("accessible environment variables", {keys = accessible_keys})

-- Check required variables
local required = {"DATABASE_URL", "REDIS_URL", "API_KEY"}
for _, key in ipairs(required) do
    if not vars[key] then
        return nil, errors.new({ kind = errors.INVALID, message = "Missing required env var: " .. key })
    end
end
```

**Returns:** `table, error`



### Permissions


Security policy evaluation applies to environment access.



#### Security Actions


| Action | Resource | Description |
|--------|----------|-------------|
| `env.get` | Variable name | Read environment variable |
| `env.set` | Variable name | Write environment variable |

`get_all` has no dedicated security action: it returns only the variables for which the `env.get` action is permitted, filtering each variable name through `env.get`.



#### Checking Access


```lua
local security = require("security")

if security.can("env.get", "DATABASE_URL") then
    local url = env.get("DATABASE_URL")
end
```

See [Security Model](system/security.md) for policy configuration.



### Errors


| Condition | Kind | Retryable |
|-----------|------|-----------|
| Empty key | `errors.INVALID` | no |
| Variable not found | `errors.NOT_FOUND` | no |
| Permission denied | `errors.PERMISSION_DENIED` | no |

See [Error Handling](lua/core/errors.md) for working with errors.



### See Also


- [Environment System](system/env.md) - Configure storage backends and variable definitions



---

# "Logging"

## Logging

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="io"/>

The `logger` module writes structured messages at debug, info, warn, and error levels.

This is an API reference. Each snippet is an isolated logging operation and assumes an execution context with the desired logger configuration.

Log calls return no values. When the execution context provides them, each call also adds the process `pid` and the source `location` derived from the current frame.



### Loading


```lua
local logger = require("logger")
```



#### `logger:debug`


Write a debug-level log message.

```lua
logger:debug("message", {key = "value"})
```



#### `logger:info`


Write an info-level log message.

```lua
logger:info("message", {key = "value"})
```



#### `logger:warn`


Write a warning-level log message.

```lua
logger:warn("message", {key = "value"})
```



#### `logger:error`


Write an error-level log message.

```lua
logger:error("message", {key = "value"})
```

All four log-level methods accept the same parameters:

| Parameter | Type | Description |
|-----------|------|-------------|
| `message` | string | Log message |
| `fields` | table? | Contextual key-value pairs |

Only string keys become field names. Strings, numbers, integers, booleans, errors, and structured Lua values are converted to log fields; non-string keys are ignored.

For `logger:error`, a field named `error` is emitted as an error field and removed from the supplied table before the remaining fields are processed. Do not reuse that table if the `error` entry must remain intact.



#### `logger:with`


Create a child logger that adds the same fields to every message.

```lua
local function request_logger(request_id)
    return logger:with({request_id = request_id})
end

request_logger("req-123"):info("message")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `fields` | table | Fields to attach to all logs |

**Returns:** `Logger`

The original logger is unchanged. Child loggers can be chained with additional `with` and `named` calls.



#### `logger:named`


Create a child logger with a name.

```lua
local named = logger:named("auth")
named:info("message")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | string | Logger name |

**Returns:** `Logger`

An empty name raises a Lua argument error. It is not returned as a structured `errors.INVALID` value.

`logger:named("")` raises a Lua argument error (`name cannot be empty`) instead of returning an error value. Logging methods return nothing.

See [Error Handling](lua/core/errors.md) for working with errors.



---

# "Terminal I/O"

## Terminal I/O

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="io"/>

The `io` module reads from standard input and writes to standard output and standard error in terminal applications.

This is an API reference. Its snippets are isolated calls; a terminal process should propagate returned structured Lua errors when the result affects control flow.

<note>
This module is available only to processes running on a <a href="../../system/terminal.md">Terminal Host</a>, not to regular functions.
</note>



### Loading


```lua
local io = require("io")
```



### Writing to Stdout


Write values to standard output without a trailing newline:

```lua
local ok, err = io.write("text", "more")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `...` | any | Variable number of values to write (coerced to string) |

**Returns:** `boolean, error`



### Print with Newline


Write values to standard output, separated by tabs and followed by a newline:

```lua
io.print("value1", "value2", 123)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `...` | any | Variable number of values to print |

**Returns:** `boolean, error`

After terminal context lookup succeeds, output write errors are ignored and the function returns `true`. A missing terminal context returns `nil, "no terminal context"`.



### Writing to Stderr


Write values to standard error, separated by tabs and followed by a newline:

```lua
io.eprint("Error:", message)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `...` | any | Variable number of values to print |

**Returns:** `boolean, error`

After terminal context lookup succeeds, output write errors are ignored and the function returns `true`. A missing terminal context returns `nil, "no terminal context"`.



### Reading Bytes


Read up to `n` bytes from standard input:

```lua
local data, err = io.read(1024)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `n` | integer | Number of bytes to read (default: 1024, values <= 0 become 1024) |

**Returns:** `string, error`. A successful read may return fewer than `n` bytes or an empty string.



### Reading a Line


Read one line from standard input:

```lua
local line, err = io.readline()
```

**Returns:** `string, error`. The trailing `\n` and `\r` are removed. EOF after partial input returns that partial line; EOF without input returns `nil` and a structured error.



### Raw Mode


Enable or disable raw terminal mode, which disables line buffering and echo:

```lua
local ok, err = io.raw(true)   -- enable
local ok, err = io.raw(false)  -- disable
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `enable` | boolean | `true` to enable, `false` to disable (default: `true`) |

**Returns:** `boolean, error`

Raw mode is reference-counted: each `io.raw(true)` call must be matched by an `io.raw(false)` call. The terminal returns to normal mode automatically when the process exits.



### Flushing Output


Flush the standard-output buffer:

```lua
local ok, err = io.flush()
```

**Returns:** `boolean, error`. The call is a successful no-op when standard output does not implement `Sync()`.



### Command Line Arguments


Retrieve the command-line arguments:

```lua
local args = io.args()
```

**Returns:** `string[]`

`io.args()` never fails. It returns an empty table when no terminal context is available.



### Errors


This module returns structured Lua errors. A missing terminal context uses `errors.UNAVAILABLE`; direct write/flush and invalid yield-response failures use `errors.INTERNAL`. Dispatcher-backed read, readline, and raw-mode failures preserve underlying error metadata when available. `io.args()` has no error return.



---

# "Metrics & Telemetry"

## Metrics & Telemetry

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="io"/>

The `metrics` module records application counters, gauges, and histogram observations.

This is an API reference. The snippets show one observation at a time and propagate collector errors.

Every function returns `true, nil` after passing the observation to the active collector. If the execution context has no collector, it returns `nil` and a non-retryable `errors.INTERNAL` error.

Labels are optional. Only entries with both a string key and a string value are recorded; other entries are silently ignored. A non-table labels argument is treated as if no labels were supplied.

Metric names are forwarded without local validation.



### Loading


```lua
local metrics = require("metrics")
```



#### `metrics.counter_inc`


Increment a counter by one.

```lua
local recorded, err = metrics.counter_inc("requests_total", {method = "POST"})
if err then return nil, err end
return recorded
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | string | Metric name |
| `labels` | table? | Label key-value pairs |

**Returns:** `boolean, error`



#### `metrics.counter_add`


Add a value to a counter.

```lua
local recorded, err = metrics.counter_add("bytes_total", 1024, {direction = "out"})
if err then return nil, err end
return recorded
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | string | Metric name |
| `value` | number | Value to add |
| `labels` | table? | Label key-value pairs |

**Returns:** `boolean, error`

The runtime forwards the value unchanged and does not require it to be positive.



#### `metrics.gauge_set`


Set a gauge to the current value.

```lua
local recorded, err = metrics.gauge_set("queue_depth", 42, {queue = "emails"})
if err then return nil, err end
return recorded
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | string | Metric name |
| `value` | number | Current value |
| `labels` | table? | Label key-value pairs |

**Returns:** `boolean, error`



#### `metrics.gauge_inc`


Increment a gauge by one.

```lua
local recorded, err = metrics.gauge_inc("connections", {pool = "db"})
if err then return nil, err end
return recorded
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | string | Metric name |
| `labels` | table? | Label key-value pairs |

**Returns:** `boolean, error`



#### `metrics.gauge_dec`


Decrement a gauge by one.

```lua
local recorded, err = metrics.gauge_dec("connections", {pool = "db"})
if err then return nil, err end
return recorded
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | string | Metric name |
| `labels` | table? | Label key-value pairs |

**Returns:** `boolean, error`



#### `metrics.histogram`


Record a histogram observation.

```lua
local recorded, err = metrics.histogram("duration_seconds", 0.123, {method = "GET"})
if err then return nil, err end
return recorded
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | string | Metric name |
| `value` | number | Observed value |
| `labels` | table? | Label key-value pairs |

**Returns:** `boolean, error`



### Errors


| Condition | Kind | Retryable |
|-----------|------|-----------|
| Collector not available | `errors.INTERNAL` | no |

Invalid name or value types raise Lua argument errors instead of returning structured errors.

See [Error Handling](lua/core/errors.md) for working with errors.



---

# "OS Time"

## OS Time

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="workflow"/>

The global `os` table provides timestamps, date formatting, elapsed-time measurement, and time-difference calculations. In a workflow, current-time reads use the workflow's time reference; outside a workflow they use the system clock.

This is an API reference. Timestamp literals and formatted outputs are illustrative; current values depend on the runtime or workflow clock and timezone.



### Loading


The `os` table is global and does not require loading with `require`.

```lua
os.time()
os.date()
os.clock()
os.difftime()
```



### Getting Timestamps


Read a Unix timestamp in seconds since January 1, 1970 UTC:

```lua
-- Current timestamp
local now = os.time()  -- 1718462445

-- Specific date/time
local t = os.time({
    year = 2024,
    month = 12,
    day = 25,
    hour = 10,
    min = 30,
    sec = 0
})
```

**Signature:** `os.time([spec]) -> number`

**Parameters:**

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `year` | number | current year | Four-digit year (e.g., 2024) |
| `month` | number | current month | Month 1-12 |
| `day` | number | current day | Day of month 1-31 |
| `hour` | number | 0 | Hour 0-23 |
| `min` | number | 0 | Minute 0-59 |
| `sec` | number | 0 | Second 0-59 |

With no arguments, `os.time()` returns the current Unix timestamp.

When called with a table, missing fields use the defaults shown above. The `year`, `month`, and `day` fields use the current date when omitted.

```lua
-- Just date (time defaults to midnight)
os.time({year = 2024, month = 6, day = 15})

-- Partial (fills in current year/month)
os.time({day = 1})  -- first of current month
```



### Formatting Dates


Format a timestamp as a string or return its date fields in a table:

<code-block lang="lua">
local now = os.time()

-- Default format
os.date()  -- "Sat Jun 15 14:30:45 2024"

-- Custom format
os.date("%Y-%m-%d", now)           -- "2024-06-15"
os.date("%H:%M:%S", now)           -- "14:30:45"
os.date("%Y-%m-%dT%H:%M:%S", now)  -- "2024-06-15T14:30:45"

-- UTC time (prefix format with !)
os.date("!%Y-%m-%d %H:%M:%S", now)  -- UTC instead of local

-- Date table
local t = os.date("*t", now)
</code-block>

**Signature:** `os.date([format], [timestamp]) -> string | table`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `format` | string | `"%c"` | Format string, `"*t"` for table |
| `timestamp` | number | current time | Unix timestamp to format |



#### Format Specifiers


| Code | Output | Example |
|------|--------|---------|
| `%Y` | 4-digit year | 2024 |
| `%y` | 2-digit year | 24 |
| `%m` | Month (01-12) | 06 |
| `%d` | Day (01-31) | 15 |
| `%H` | Hour 24h (00-23) | 14 |
| `%I` | Hour 12h (01-12) | 02 |
| `%M` | Minute (00-59) | 30 |
| `%S` | Second (00-59) | 45 |
| `%p` | AM/PM | PM |
| `%A` | Weekday name | Saturday |
| `%a` | Weekday short | Sat |
| `%B` | Month name | June |
| `%b` | Month short | Jun |
| `%w` | Weekday (0-6, Sunday=0) | 6 |
| `%j` | Day of year (001-366) | 167 |
| `%U` | ISO 8601 week number (01-53, week starts Monday) | 24 |
| `%W` | ISO 8601 week number (01-53, week starts Monday) | 24 |
| `%z` | Timezone offset | -0700 |
| `%Z` | Timezone name | PDT |
| `%c` | Full date/time | Sat Jun 15 14:30:45 2024 |
| `%x` | Date only | 06/15/24 |
| `%X` | Time only | 14:30:45 |
| `%%` | Literal % | % |



#### Date Table


When the format is `"*t"`, `os.date()` returns a table:

```lua
local t = os.date("*t")
```

| Field | Type | Description | Example |
|-------|------|-------------|---------|
| `year` | number | Four-digit year | 2024 |
| `month` | number | Month (1-12) | 6 |
| `day` | number | Day of month (1-31) | 15 |
| `hour` | number | Hour (0-23) | 14 |
| `min` | number | Minute (0-59) | 30 |
| `sec` | number | Second (0-59) | 45 |
| `wday` | number | Weekday (1-7, Sunday=1) | 7 |
| `yday` | number | Day of year (1-366) | 167 |
| `isdst` | boolean | `true` when the zone's UTC offset is nonzero in this release; not a reliable DST indicator | false |

Use `"!*t"` for UTC date table.



### Measuring Elapsed Time


Read the seconds between the current runtime time reference and the OS-time module's initialization time:

```lua
local start = os.clock()

-- do work
for i = 1, 1000000 do end

local elapsed = os.clock() - start
print(string.format("Took %.3f seconds", elapsed))
```

**Signature:** `os.clock() -> number`

Unlike standard Lua's CPU-time definition, this implementation is based on elapsed time. In workflows, it uses the workflow time reference.



### Time Difference


Calculate the difference between two timestamps in seconds:

```lua
local t1 = os.time({year = 2024, month = 1, day = 1})
local t2 = os.time({year = 2024, month = 12, day = 31})

local diff = os.difftime(t2, t1)  -- t2 - t1
local days = diff / 86400
print(days)  -- 365
```

**Signature:** `os.difftime(t2, t1) -> number`

| Parameter | Type | Description |
|-----------|------|-------------|
| `t2` | number | Later timestamp |
| `t1` | number | Earlier timestamp |

The result is `t2 - t1` in seconds and is negative when `t1 > t2`.



### Platform Constant


The `os.platform` constant identifies the runtime:

```lua
os.platform  -- "wippy"
```



---

# "TTY"

## TTY

<secondary-label ref="process"/>
<secondary-label ref="io"/>

Terminal input events, styled output, presentation surfaces, and local virtual viewports.

<note>
Every function resolves the terminal port attached to the calling process frame. A process on a <a href="system/terminal.md">Terminal Host</a> owns the physical terminal; a <code>process.lua</code> on a regular <code>process.host</code> owns a virtual terminal when it is spawned with a viewport grant. Without either attachment the module returns "no terminal context".
</note>



### Loading


```lua
local tty = require("tty")
```



### Model


A **Surface** is one process's exclusive presentation lease on its terminal port. It publishes complete row snapshots; the backend owns diffing and terminal recovery. Only one surface may be open on a port at a time.

A **Canvas** is an in-process styled-cell composition buffer. It clips at cell boundaries and never emits terminal control commands of its own.

A **Viewport** is a local, structured terminal boundary that lets one process host another process's surface without sharing byte streams. The shell decides where viewport content appears and translates input into the child's coordinates; the child sees an ordinary terminal port and does not know whether it is full-screen, tiled, tabbed, or hidden.

Viewports are local to one runtime node. Grants and handles are opaque local capabilities, not serializable network references.



### Input Loop


Start input delivery, subscribe to events, and process them in a loop:

```lua
local tty = require("tty")
local io = require("io")

local function handler()
    local events = tty.events()
    tty.start()

    while true do
        local ev, open = events:receive()
        if not open then break end

        if ev.type == "key" then
            if ev.key == "q" or (ev.ctrl and ev.key == "c") then
                break
            end
            local _, print_err = io.print("Key: " .. ev.key)
            if print_err then loop_err = print_err; break end

        elseif ev.type == "resize" then
            local _, print_err = io.print("Size: " .. ev.width .. "x" .. ev.height)
            if print_err then loop_err = print_err; break end
        end
    end

    local _, stop_err = tty.stop()
    if loop_err then return nil, loop_err end
    if stop_err then return nil, stop_err end
    return started
end
```

Call `events()` before `start()` so a consumer is ready when the first events arrive. On a virtual port, `start()` opens viewer-to-producer event delivery and `stop()` closes it: a `Viewport:send()` outside that interval fails instead of silently dropping input. Resize delivery is independent of input state.



#### `tty.start()`


Start input delivery for the current port. A physical terminal switches to raw mode.

```lua
local ok, err = tty.start()
```

**Returns:** `boolean, error`



#### `tty.stop()`


Stop input delivery and restore the terminal to normal mode.

```lua
local ok, err = tty.stop()
```

**Returns:** `boolean, error`



#### `tty.events()`


Subscribe to the port's terminal events and return a channel. Events are delivered as tables with a `type` field. Subscribe once and reuse the channel.

```lua
local events, err = tty.events()
```

**Returns:** `EventChannel, error`

`EventChannel` has `receive()` and `case_receive()`, so it composes with `channel.select`.



#### tty.screen_size()


Read the current terminal dimensions.

```lua
local width, height, err = tty.screen_size()
```

**Returns:** `number, number, error`



#### `tty.mouse(enable)`


Enable or disable mouse event tracking.

```lua
local ok, err = tty.mouse(true)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `enable` | boolean | `true` to enable, `false` to disable |

**Returns:** `boolean, error`



### Surface


A surface is the port's presentation lease. Acquire one, publish complete frames, and close it when done.



#### tty.surface(options?)


```lua
local surface, err = tty.surface({
    alternate_screen = true,
    hide_cursor = true,
    synchronized_output = true,
})
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `alternate_screen` | boolean | false | Present on the terminal's alternate screen buffer |
| `hide_cursor` | boolean | false | Hide the terminal cursor while the surface is open |
| `synchronized_output` | boolean | false | Wrap each frame in synchronized-output markers |

**Returns:** `Surface, error`

Opening a second surface on a port that already has one fails. A virtual port keeps the options as surface metadata; a physical port translates them into terminal modes and restores them on close.



#### surface:present(rows, options?)


Publish a complete array of row strings. Row `1` is the top line.

```lua
local stats, err = surface:present(rows, {
    cursor = {x = 12, y = 3, visible = true},
    images = {
        {placement_id = "logo", image = logo, x = 2, y = 2, cols = 20, rows = 8, alt = "Logo"},
    },
})
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `rows` | string[] | Complete frame, at most 16384 rows |
| `options.cursor` | table | `{x, y, visible}` in one-based surface coordinates |
| `options.images` | table[] | Complete retained-image placement set for the frame |

Omitting `cursor` preserves the last explicit cursor state. All three cursor fields are required when `cursor` is present.

**Returns:** `stats, error` — an immutable record with `rows`, `changed_rows`, and `bytes_written`. A physical frame identical to the previous one writes nothing.



#### surface:invalidate()


Forget backend presentation state without erasing the logical frame. The next `present` commits even when its rows are unchanged. Use it after an outer terminal resize or when another owner may have disturbed physical state.

**Returns:** `boolean`



#### surface:close()


Release the lease. Idempotent: later calls return the first close result. A physical backend restores terminal modes.

**Returns:** `boolean, error`



#### surface:capabilities()


Return `{images = "native" | "kitty" | "pending" | "none"}`. Start terminal
input before probing. A physical backend may briefly return `pending` while it
queries the terminal; virtual surfaces retain images without probing.

**Returns:** `table, error`



#### surface:clipboard(text)


Write an OSC 52 clipboard request on a physical surface. Text must be valid
UTF-8 and at most 65,536 bytes. Success means the terminal output accepted the
request; terminal policy may still ignore it. Virtual surfaces return an
unsupported error, and the API provides no clipboard read or acknowledgement.

**Returns:** `boolean, error`



### Retained Images


Import a PNG into bounded runtime storage, then place its handle in a complete
surface frame:

```lua
local image = assert(tty.image(png_bytes))
local info = image:info() -- id, format, width, height, bytes

assert(surface:present(rows, {images = {{
    placement_id = "preview",
    image = image,
    x = 1, y = 1, cols = 40, rows = 12,
    src = {x = 0, y = 0, width = info.width, height = info.height},
    z = 1,
    alt = "Preview",
}}}))
```

`tty.image()` validates PNG bytes asynchronously. `image:read()` explicitly
exports the encoded bytes and `image:close()` releases the reference. Source
pixel coordinates are zero-based; destination cell coordinates are one-based.
Omitting `images` from a later `present` clears prior placements. Unsupported
physical terminals display the placement's `alt` text, while virtual surfaces
keep the image resource for viewers.



### Canvas


A canvas is a bounded styled-cell buffer used to compose a frame before presenting it.



#### tty.canvas(width, height)


```lua
local canvas = tty.canvas(width, height)
```

Width is capped at 16384 columns, height at 16384 rows, and the area at 262,144 cells. Out-of-range arguments raise an argument error.

**Returns:** `Canvas`

Drawing accepts styled text, not terminal commands. SGR colors and OSC 8 links are preserved; erase, cursor-motion, and other control-only output is not emitted. Each placement is clipped independently at cell boundaries with grapheme-width awareness, so a clipped escape sequence cannot leak into neighboring content.



#### canvas:clear(fill?)


Clear every cell. An optional styled `fill` string is repeated across each row.

```lua
canvas:clear()
canvas:clear(tty.style():background("#1a1a1a"):render(" "))
```

**Returns:** `boolean`



#### canvas:put(x, y, text, width?)


Place one styled row at one-based `x`, `y` and clip it to `width` cells (default: the canvas width). Coordinates may be negative or past the edge; the placement is clipped rather than rejected. A newline ends the row, so use `put_rows` for multi-row content.

```lua
canvas:put(3, 1, tty.style():bold():render("Title"), 40)
```

**Returns:** `boolean`



#### canvas:put_rows(x, y, rows, width?)


Place an array of styled rows starting at `x`, `y`, one row per line downward. Every entry is validated before anything is drawn.

```lua
canvas:put_rows(2, 2, child_rows, inner_width)
```

**Returns:** `boolean`



#### canvas:rows()


Render the complete row array, ready for `surface:present`.

**Returns:** `string[]`



### Viewport


A viewport is a virtual terminal port. The creating process is its first viewer; the process admitted with its grant is its producer.



#### tty.viewport(options?)


```lua
local view, err = tty.viewport({
    width = 80,
    height = 24,
    page = {foreground = "#e0def4", background = "#191724"},
})
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `width` | number | 80 | Columns, 1 to 65535 |
| `height` | number | 24 | Rows, 1 to 65535 |
| `page` | table | none | Opaque `#RRGGBB` foreground and background defaults |

The area is capped at 262,144 cells.

**Returns:** `Viewport, error`



#### tty.attach(handle)


Add another local viewer to an existing viewport. A handle grants viewing, never presentation ownership, and is not valid on another node.

```lua
local view, err = tty.attach(handle)
```

**Returns:** `Viewport, error`



#### viewport:grant()


Return the one-shot producer capability. Pass it as the `terminal` spawn option:

```lua
local grant = assert(view:grant())
local child = assert(process.with_options({terminal = grant})
    :spawn_monitored("app:child", "app:workers"))
```

Admission consumes the grant transactionally: a rejected start restores an unresolved grant, while a process that has resolved the port consumes it permanently. A host that does not support terminal attachments rejects the spawn instead of dropping the option. See [Processes](lua/core/process.md#spawner-with-options).

**Returns:** `string, error`



#### viewport:handle()


Return the local viewer handle for `tty.attach`.

**Returns:** `string`



#### viewport:snapshot(after_revision?)


Read the current dimensions, rows, cursor, and revision. With `after_revision`, return `nil` when the revision is unchanged.

```lua
local frame = view:snapshot(revision)
if frame then
    revision = frame.revision
    canvas:put_rows(2, 2, frame.rows, inner_width)
end
```

**Returns:** `snapshot` or `nil`

| Field | Type | Description |
|-------|------|-------------|
| `revision` | number | Monotonic revision of this frame |
| `width` | number | Viewport columns |
| `height` | number | Viewport rows |
| `rows` | string[] | Rows last published by the producer |
| `cursor` | table | `{x, y, visible}` in one-based coordinates, absent until the producer publishes explicit cursor state |
| `images` | table[] | Retained image placement metadata |
| `layers` | table[] | Ordered presentation layers |
| `images_omitted` | boolean | Image resources exist but are not retained by this plain snapshot |

A page resolves terminal-default cells and omitted rows to explicit colors. The
creator can change it with `viewport:set_page(page)`; passing `nil` restores the
producer's original rows. Page changes advance the revision without requiring
the producer to repaint.



#### viewport:updates()


Return a channel of coalesced revision watermarks. `receive()` yields the revision number; `case_receive()` composes with `channel.select`.

```lua
local updates = assert(view:updates())
```

Updates are bounded hints, not an event log. A slow viewer receives only the newest watermark and must call `snapshot()` for state. Presentation and resize never block on a slow viewer.

**Returns:** `ViewportUpdateChannel, error`



#### viewport:send(event)


Forward a validated event record to the producer. The producer must have called `tty.start()`; otherwise the call fails rather than dropping the event.

```lua
assert(view:send(event))
assert(view:send({type = "close"}))
```

**Returns:** `boolean, error`



#### viewport:resize(width, height)


Update the viewport geometry. When the size changes, viewers get a new revision and the producer receives a `resize` event.

**Returns:** `boolean, error`



#### viewport:close()


Detach this viewer only. Closing the last viewer does not kill a live producer, and closing the producer's port does not destroy state while viewers remain.

**Returns:** `boolean, error`



#### viewport:mount(recipient_pid, rights)


Issue a process-bound reference for a local or remote viewer. Rights are
independent and default to false:

```lua
local observation = assert(view:mount(agent_pid, {observe = true}))
local control = assert(view:mount(agent_pid, {input = true, resize = true}))

-- In the exact recipient process, on this node or an authenticated mesh peer:
local observer = assert(tty.attach(observation))
local controller = assert(tty.attach(control))
```

A mount is bound to the recipient's full PID and can be redeemed only once.
Mounted viewers cannot create producer grants or delegate further mounts.
Remote mounts use a renewable lease; reconnecting requires a fresh mount and
cannot replay terminal input. Use `viewport:revoke(reference)` to revoke an
issued mount. Closing the owner viewport or ending the owner process revokes
its mounts.



#### viewport:capture()


Atomically pin a viewport revision and its retained image resources:

```lua
local capture = assert(view:capture())
local snapshot = capture:snapshot()
local image = assert(capture:image(snapshot.images[1].image_id))
assert(capture:close())
```

A plain `snapshot()` does not retain image bytes. A capture does until closed;
image handles already acquired from it remain independently owned.



### Event Types


Events are tables with a `type` field that determines which other fields are present. Coordinates are one-based. The same records are accepted by `viewport:send()`.



#### Key Event


```lua
{
    type = "key",
    key = "a",           -- printable character or key name
    key_type = "runes",  -- "runes" for printable, or special key name
    action = "press",    -- "press" or "release"
    alt = false,
    ctrl = false,
    shift = false
}
```



#### Mouse Event


Requires `tty.mouse(true)`.

```lua
{
    type = "mouse",
    action = "press",    -- "press", "release", "motion", "wheel"
    button = "left",     -- button name
    x = 10,
    y = 5,
    alt = false,
    ctrl = false,
    shift = false
}
```



#### Resize Event


```lua
{type = "resize", width = 120, height = 40}
```



#### Start Event


Emitted once after `tty.start()` with initial dimensions.

```lua
{type = "start", width = 120, height = 40}
```



#### Focus Event


Reports keyboard ownership.

```lua
{type = "focus", focused = true}
```



#### Visibility Event


Reports whether repainting is useful. It does not prescribe application lifecycle or background computation.

```lua
{type = "visibility", visible = true}
```



#### Paste Event


```lua
{type = "paste", text = "pasted content"}
```



#### Close Event


Asks the producer to shut down. A shell sends it through `viewport:send` to request a graceful child exit.

```lua
{type = "close"}
```



### Key Bindings


Create reusable key bindings that match against key events:

```lua
local quit = tty.bind({
    keys = {"q", "ctrl+c"},
    help = {key = "q/ctrl+c", desc = "quit"}
})

-- In event loop
if quit:matches(ev) then
    break
end
```



#### `tty.bind(config)`


| Field | Type | Description |
|-------|------|-------------|
| `keys` | string[] | Required. Key patterns to match (e.g. `"a"`, `"ctrl+c"`, `"enter"`) |
| `help` | table | Optional. `{key = "...", desc = "..."}` for help text |

**Returns:** `KeyBinding`

The type schema requires `keys`. At runtime, an omitted or empty `keys` table creates a binding that never matches.



#### KeyBinding Methods


| Method | Returns | Description |
|--------|---------|-------------|
| `matches(event)` | boolean | Test if a key event matches this binding |
| `set_enabled(bool)` | self | Enable or disable the binding |
| `is_enabled()` | boolean | Check if the binding is enabled |
| `help()` | table | Returns `{key, desc}` help info |



### Styles


Create styled terminal output. Style values are immutable, so each style method returns a new value.

```lua
local tty = require("tty")
local io = require("io")

local title = tty.style()
    :bold()
    :foreground("#FF0000")
    :padding(0, 1)

local box = tty.style()
    :border(tty.borders.ROUNDED)
    :border_foreground("#00FF00")
    :width(40)
    :padding(1, 2)

local _, print_err = io.print(box:render(title:render("Hello"), "World"))
if print_err then return nil, print_err end
```



#### `tty.style()`


Create an empty style.

**Returns:** `Style`



#### Style Methods


All methods return a new `Style` and can be chained.



##### Text Decoration


| Method | Parameter | Description |
|--------|-----------|-------------|
| `foreground(color)` | string | Text color (hex `"#FF0000"`, ANSI `"9"`, or name) |
| `background(color)` | string | Background color |
| `bold(enable?)` | boolean | Bold text (default: true) |
| `italic(enable?)` | boolean | Italic text |
| `underline(enable?)` | boolean | Underline text |
| `strikethrough(enable?)` | boolean | Strikethrough text |
| `faint(enable?)` | boolean | Dimmed text |
| `blink(enable?)` | boolean | Blinking text |
| `reverse(enable?)` | boolean | Swap foreground/background |



##### Layout


| Method | Parameter | Description |
|--------|-----------|-------------|
| `width(n)` | number | Fixed width |
| `height(n)` | number | Fixed height |
| `max_width(n)` | number | Maximum width |
| `max_height(n)` | number | Maximum height |
| `padding(...)` | numbers | Padding (CSS-style: top, right, bottom, left) |
| `margin(...)` | numbers | Margin (CSS-style) |
| `align(pos)` | number | Horizontal alignment |
| `align_vertical(pos)` | number | Vertical alignment |
| `inline(enable?)` | boolean | Inline rendering mode |



##### Borders


| Method | Parameter | Description |
|--------|-----------|-------------|
| `border(name, ...)` | string, booleans | Border style, optional per-side toggles |
| `border_foreground(...)` | strings | Border color(s) |
| `border_background(...)` | strings | Border background color(s) |



##### Other


| Method | Description |
|--------|-------------|
| `render(...)` | Render strings with this style applied |
| `copy()` | Create a copy of this style |



#### Border Constants


```lua
tty.borders.NORMAL
tty.borders.ROUNDED
tty.borders.THICK
tty.borders.DOUBLE
tty.borders.HIDDEN
```



#### Alignment Constants


```lua
tty.align.LEFT    -- 0
tty.align.CENTER  -- 0.5
tty.align.RIGHT   -- 1
```



### Text Utilities


The `tty.text` subtable provides layout and measurement functions for styled text.



#### Measurement


```lua
local w = tty.text.width("hello")         -- printable width (ANSI-aware)
local h = tty.text.height("a\nb\nc")      -- line count
local w, h = tty.text.size("hello\nworld") -- both
```



#### Clipping


```lua
-- Truncate to a printable width, with an optional tail
local head = tty.text.truncate(line, 40)
local head = tty.text.truncate(line, 40, "…")

-- Take the printable cell range [left, right)
local middle = tty.text.cut(line, 10, 30)
```

Both preserve ANSI state and grapheme boundaries, so styled text can be clipped and spliced without breaking escape sequences. `truncate` returns an empty string for a width of zero or less; `cut` returns an empty string when `right` is not greater than `left`.



#### Joining


```lua
-- Join side by side, aligned at top
local row = tty.text.join_horizontal(tty.text.position.TOP, left, right)

-- Stack vertically, centered
local col = tty.text.join_vertical(tty.text.position.CENTER, top, bottom)
```



#### Max Dimensions


```lua
local w = tty.text.max_width({"short", "a longer string"})   -- widest
local h = tty.text.max_height({"one\ntwo", "single"})         -- tallest
```



#### Placement


Place a string within a box with the given dimensions:

```lua
-- Center in a 80x24 box
local out = tty.text.place(80, 24, tty.text.position.CENTER, tty.text.position.CENTER, content)

-- Horizontal only
local out = tty.text.place_horizontal(80, tty.text.position.RIGHT, content)

-- Vertical only
local out = tty.text.place_vertical(24, tty.text.position.BOTTOM, content)
```



#### Position Constants


```lua
tty.text.position.TOP      -- 0
tty.text.position.LEFT     -- 0
tty.text.position.CENTER   -- 0.5
tty.text.position.BOTTOM   -- 1
tty.text.position.RIGHT    -- 1
```



### Permissions


Access to a physical terminal comes from the process frame. Attaching a
producer with `process.with_options({terminal = grant})` requires
`process.context` on the spawning side. Delegated viewports additionally check:

| Action | Resource | Description |
|--------|----------|-------------|
| `tty.mount` | Owner viewport handle | Issue a process-bound mount |
| `tty.observe` | Owner viewport handle | Read snapshots, updates, and captures |
| `tty.input` | Owner viewport handle | Forward input events |
| `tty.resize` | Owner viewport handle | Resize the viewport |



### See Also


- [Terminal UI](tutorials/tty.md) — build a shell that hosts a child in a viewport
- [Terminal I/O](lua/system/io.md) — stdin/stdout/stderr operations
- [Terminal Host](system/terminal.md) — Terminal host configuration
- [Command Execution](lua/dynamic/exec.md) — PTY processes and terminal sessions
- [Processes](lua/core/process.md) — spawn options, monitoring, lifecycle events



---

# "Hub"

## Hub


The `hub` module reads Wippy Hub modules, versions, dependencies, files, artifacts, and READMEs. It also manages the runtime's Hub credential override and can remove unpinned artifacts from the local cache.

This is an API reference. Catalog coordinates are illustrative; artifact, authentication, and cache operations require matching network access, credentials, lock state, and security policies.



### Loading


```lua
local hub = require("hub")
```



### Per-call Options


Network-backed catalog and artifact calls accept an optional options table with these common keys:

| Key | Type | Description |
|-----|------|-------------|
| `registry` | string | Registry URL override |
| `token` | string | API token override |
| `timeout` | duration/number | Request timeout (e.g. `"3m"` or seconds) |

Pagination-aware calls also accept `page` and `page_size`.

Authentication calls take a registry URL directly. Cache calls and package-handle methods use their own options described below.



### Modules


```lua
local result, err = hub.modules.list({
    org = "wippy",
    visibility = "public",
    type = "library",
    sort_order = "downloads_desc",
    page = 1,
    page_size = 20,
})
-- result = { items, total, page, page_size }
```

| Function | Description |
|----------|-------------|
| `hub.modules.list(opts?)` | List modules with filters |
| `hub.modules.search(query, opts?)` | Search by query string |
| `hub.modules.get(module, opts?)` | Fetch module by `org/name` or module id |
| `hub.modules.readme(module, opts?)` | Fetch README; returns `{content, filename, version}` |



#### List/Search Options


| Option | Values |
|--------|--------|
| `organization_id` / `org` | string |
| `visibility` | `public`, `private`, `internal` |
| `type` | `library`, `application`, `agent`, `plugin` |
| `sort_order` | `name_asc`, `name_desc`, `created_desc`, `updated_desc`, `downloads_desc` |
| `keywords` (search) | array of strings |
| `license` (search) | string |
| `include_deprecated` (search) | boolean |



#### README


```lua
local readme, err = hub.modules.readme("wippy/terminal", {
    version = "1.2.3"
})
if err then return nil, err end
print(readme.content)
```

The `version` option accepts either a version string or a table like `{id, version, label}`.



### Versions


```lua
local versions, err = hub.versions.list("wippy/terminal", {
    include_yanked = false,
    page_size = 50,
})

local v, err = hub.versions.get("wippy/terminal", "1.0.0")
```

| Function | Description |
|----------|-------------|
| `hub.versions.list(module, opts?)` | List versions for a module |
| `hub.versions.get(module, version, opts?)` | Fetch a specific version |
| `hub.versions.inspect(module, version, opts?)` | Inspect a version's artifact (downloads and reads the bundle) |
| `hub.versions.open(module, version, opts?)` | Open a version's artifact as a package handle |



#### Package Handle


`hub.versions.open` downloads an artifact and returns a handle with the fields `version`, `digest`, and `packed`:

```lua
local pkg, err = hub.versions.open("wippy/terminal", "1.2.3")
if err then return nil, err end

local entries, entries_err = pkg:entries({
    kind = "function.lua",       -- string or string[], omit for all kinds
    include_data = false,        -- default true
})
-- each entry: { id = "ns:name", kind = "...", meta = {...}, data = <any> }
local _, close_err = pkg:close()
if entries_err then return nil, entries_err end
if close_err then return nil, close_err end
return entries
```

| Method | Description |
|--------|-------------|
| `pkg:metadata()` | Pack metadata map |
| `pkg:entries(opts?)` | Registry entries in the artifact; `opts.kind` filters, `opts.include_data` (default true) controls the `data` field |
| `pkg:resources()` | Embedded resources list |
| `pkg:fs(resource)` | Filesystem handle for an embedded resource |
| `pkg:close()` | Release the handle |

Entry `data` is returned without resolving `${env:...}` references.



### Local Artifact Cache


```lua
local entries, err = hub.cache.list()

local removed, err = hub.cache.remove("wippy/terminal", "1.2.3", {
    force = false,
})

local candidates, err = hub.cache.prune({
    dry_run = true,
})
```

| Function | Description |
|----------|-------------|
| `hub.cache.list()` | List cached artifacts as `{module, version, size, pinned}` records |
| `hub.cache.remove(module, version, opts?)` | Remove one cached artifact; `opts.force = true` permits removal when the lock file pins it |
| `hub.cache.prune(opts?)` | Remove artifacts not referenced by the lock file; `opts.dry_run = true` only reports candidates |

`hub.cache.remove` and `hub.cache.prune` delete files from the lock-resolved vendor directory unless their dry-run or pin protections apply.



### Dependencies


```lua
local deps, err = hub.dependencies.get("wippy/terminal", "1.0.0")
local users, err = hub.dependents.get("wippy/terminal")
```

| Function | Description |
|----------|-------------|
| `hub.dependencies.get(module, version?, opts?)` | Dependencies for a module version |
| `hub.dependents.get(module, opts?)` | Modules that depend on this one |



### Files


```lua
local files, err = hub.files.list("wippy/terminal", "1.0.0")
```

| Function | Description |
|----------|-------------|
| `hub.files.list(module, version, opts?)` | List files for a version (`version` required); returns `{items, total, page, page_size}` |



### Cache


```lua
local cached, err = hub.cache.list()
-- each entry: { module, version, size, pinned }

local ok, err = hub.cache.remove("wippy/terminal", "1.2.3", { force = true })
local pruned, err = hub.cache.prune({ dry_run = true })
```

| Function | Description |
|----------|-------------|
| `hub.cache.list(opts?)` | List cached artifacts under the vendor directory; `pinned` is `true` when the lock file references the artifact |
| `hub.cache.remove(module, version, opts?)` | Remove one cached artifact; refuses a lock-pinned artifact (kind `errors.CONFLICT`) unless `opts.force` is `true`; returns `true` |
| `hub.cache.prune(opts?)` | Remove every cached artifact the lock file does not reference; with `opts.dry_run = true` nothing is deleted; returns the pruned (or would-be-pruned) entries |

**Permissions:** `hub.cache.list`, `hub.cache.remove` (resource: module name), `hub.cache.prune`



### Authentication


Install a registry token as a runtime override. Hub consumers use it on subsequent calls without requiring a restart:

```lua
local status, err = hub.auth.authenticate("wpy_xxx")          -- default registry
local status, err = hub.auth.authenticate("wpy_xxx", "https://hub.example.com")

local status, err = hub.auth.status()
local ok, err = hub.auth.logout()
```

The token strings above are placeholders. Load real credentials from a secret-backed environment entry or another protected source; do not commit them in Lua or registry YAML.

| Function | Description |
|----------|-------------|
| `hub.auth.authenticate(token, registry?)` | Validate the token against the registry and, on success, install it as the runtime override |
| `hub.auth.status(registry?)` | Live-validate the current credential |
| `hub.auth.logout(registry?)` | Clear the runtime token override |

`status` contains `authenticated`, `registry`, and `orgs`. Identity fields (`username`, `user_id`, `scope`, `expires_at`, `expired`) are present only when authenticated. A token that fails validation is not stored; `authenticate` returns `authenticated = false`. The runtime override takes precedence over `WIPPY_TOKEN` and stored credentials.



### Permissions


Each top-level `hub.*` operation checks the matching action name, such as `hub.modules.list`, `hub.versions.open`, `hub.dependencies.get`, `hub.files.list`, `hub.auth.status`, or `hub.cache.prune`. Actions that address a module use the supplied module reference as the security resource; authentication actions use the registry URL. Package-handle methods do not perform another permission check after the authorized `hub.versions.open` call.



### See Also


- [CLI Reference](guides/cli.md) — `wippy readme`, `wippy search`, `wippy publish`
- [Publishing Guide](guides/publishing.md)



---

# "Text Processing"

## Text Processing

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="workflow"/>

The `text` module provides regular expressions, text comparison and patching, and document splitting. This page is an API reference. Its short blocks are isolated calls; longer splitting blocks are partial recipes whose documents, configured filesystem resources, and downstream processing belong to the surrounding application.



### Loading


```lua
local text = require("text")
```



#### `text.regexp.compile`


Compile an RE2-compatible regular expression.

```lua
local re, err = text.regexp.compile("[0-9]+")
if err then
    return nil, err
end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `pattern` | string | RE2 compatible regex pattern |

**Returns:** `Regexp, error`



#### `re:match_string`


Match a string against the compiled expression.

```lua
local ok = re:match_string("abc123")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `s` | string | String to match |

**Returns:** `boolean`



#### `re:find_string`


Find the first matching substring.

```lua
local match = re:find_string("abc123def")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `s` | string | String to search |

**Returns:** `string | nil`

At this runtime pin, an empty-string match is also represented as `nil`; use a pattern that consumes at least one character when an empty match must be distinguished from no match.



#### `re:find_all_string`


Find all matching substrings.

```lua
local matches = re:find_all_string("a1b2c3")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `s` | string | String to search |

**Returns:** `string[]`



#### `re:find_string_submatch`


Find the first match and its capture groups.

```lua
local match = re:find_string_submatch("user@example.com")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `s` | string | String to search |

**Returns:** `string[] | nil` (full match + capture groups)



#### `re:find_all_string_submatch`


Find all matches and their capture groups.

```lua
local matches = re:find_all_string_submatch("a=1 b=2")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `s` | string | String to search |

**Returns:** `string[][]`



#### `re:find_string_index`


Find the 1-based bounds of the first match.

```lua
local pos = re:find_string_index("abc123")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `s` | string | String to search |

**Returns:** `table | nil` ({start, end}, 1-based)



#### `re:find_all_string_index`


Find the bounds of all matches.

```lua
local positions = re:find_all_string_index("a1b2c3")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `s` | string | String to search |

**Returns:** `table[] | nil` (nil when there are no matches)



#### `re:replace_all_string`


Replace every matching substring.

```lua
local result = re:replace_all_string("a1b2", "X")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `s` | string | Input string |
| `repl` | string | Replacement string |

**Returns:** `string`



#### `re:split`


Split a string at matches of the compiled expression.

```lua
local parts = re:split("a,b,c", -1)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `s` | string | String to split |
| `n` | integer | Max parts, -1 for all |

**Returns:** `string[]`



#### `re:num_subexp`


Return the number of capturing subexpressions.

```lua
local count = re:num_subexp()
```

**Returns:** `number`



#### `re:subexp_names`


Return the names of capturing subexpressions.

```lua
local names = re:subexp_names()
```

**Returns:** `string[]`



#### `re:string`


Return the compiled pattern string.

```lua
local pattern = re:string()
```

**Returns:** `string`



### Text Diffing


Compare text versions and generate patches with [go-diff](https://github.com/sergi/go-diff), an implementation of Google's diff-match-patch algorithm.



#### `text.diff.new`


Create a text differ with default or custom options.

```lua
local diff, err = text.diff.new()
local diff, err = text.diff.new(options)
```

**Returns:** `Differ, error`



##### Options {id="diff-options"}


| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `diff_timeout` | number | 1.0 | Timeout in seconds |
| `diff_edit_cost` | integer | 4 | Cost of an empty edit |
| `match_threshold` | number | 0.5 | Match tolerance 0-1 |
| `match_distance` | integer | 1000 | Distance to search for match |
| `patch_delete_threshold` | number | 0.5 | Delete threshold |
| `patch_margin` | integer | 4 | Context margin |



#### `diff:compare`


Compare two strings and return operations that transform `text1` into `text2`.

```lua
local diff, diff_err = text.diff.new()
if diff_err then
    return nil, diff_err
end
local diffs, err = diff:compare("hello world", "hello there")
if err then
    return nil, err
end

-- diffs contains:
-- {operation = "equal", text = "hello "}
-- {operation = "delete", text = "world"}
-- {operation = "insert", text = "there"}
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `text1` | string | Original text |
| `text2` | string | Modified text |

**Returns:** `table, error` (array of {operation, text})

Operations: `"equal"`, `"delete"`, `"insert"`



#### `diff:summarize`


Count the unchanged, inserted, and deleted UTF-8 bytes. For non-ASCII text, these totals are not Unicode code-point or grapheme counts.

```lua
-- `diffs` is the checked result from diff:compare.
local summary = diff:summarize(diffs)

-- summary.equals = 6 (bytes unchanged)
-- summary.deletions = 5 (bytes removed)
-- summary.insertions = 5 (bytes added)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `diffs` | table | Diff array from compare |

**Returns:** `table` ({insertions, deletions, equals})



#### `diff:pretty_text`


Format a diff with ANSI colors for terminal output.

```lua
local formatted, err = diff:pretty_text(diffs)
if err then
    return nil, err
end
print(formatted)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `diffs` | table | Diff array from compare |

**Returns:** `string, error`



#### `diff:pretty_html`


Format a diff as HTML with `<del>` and `<ins>` elements.

```lua
local html, err = diff:pretty_html(diffs)
if err then
    return nil, err
end
-- `html` is an HTML fragment with equal, deleted, and inserted spans.
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `diffs` | table | Diff array from compare |

**Returns:** `string, error`



#### `diff:patch_make`


Create patches that transform one string into another. The patches can be serialized and applied later.

```lua
local text1 = "The quick brown fox jumps over the lazy dog"
local text2 = "The quick red fox jumps over the lazy cat"

local patches, err = diff:patch_make(text1, text2)
if err then
    return nil, err
end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `text1` | string | Original text |
| `text2` | string | Modified text |

**Returns:** `table, error`



#### `diff:patch_apply`


Apply patches to a string and return the result and whether every patch succeeded.

```lua
local result, success = diff:patch_apply(patches, text1)
-- result = "The quick red fox jumps over the lazy cat"
-- success = true
```

Check `success` before treating `result` as the requested transformation. Pass patch tables produced by `patch_make`; at this runtime pin, malformed serialized patch text inside a hand-built table can be skipped rather than reported separately.

| Parameter | Type | Description |
|-----------|------|-------------|
| `patches` | table | Patches from patch_make |
| `text` | string | Text to apply patches to |

**Returns:** `string, boolean`



### Text Splitting


Split documents into chunks while preserving semantic boundaries. The splitters are based on the [langchaingo](https://github.com/tmc/langchaingo) implementation.



#### `text.splitter.recursive`


The recursive splitter tries double newlines, single newlines, spaces, and then individual characters. It moves to the next separator when a chunk exceeds the size limit.

```lua
local splitter, err = text.splitter.recursive({
    chunk_size = 1000,
    chunk_overlap = 100
})
if err then
    return nil, err
end

local long_text = "This is a long text that needs splitting..."
local chunks, split_err = splitter:split_text(long_text)
if split_err then
    return nil, split_err
end
```

**Returns:** `Splitter, error`



##### Options {id="recursive-splitter-options"}


| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `chunk_size` | integer | 4000 | Max characters per chunk |
| `chunk_overlap` | integer | 200 | Characters repeated between adjacent chunks |
| `keep_separator` | boolean | false | Keep separators in output |
| `separators` | string[] | nil | Custom separator list |



#### `text.splitter.markdown`


The Markdown splitter can keep headings with their content, preserve code blocks, and group table rows.

```lua
local splitter, err = text.splitter.markdown({
    chunk_size = 2000,
    code_blocks = true,
    heading_hierarchy = true
})
if err then
    return nil, err
end

local readme = fs.get("app:docs"):readfile("README.md")
local chunks, err = splitter:split_text(readme)
```

This partial recipe requires the entry to enable both `text` and `fs`, a configured `app:docs` filesystem resource, and a readable `README.md` within that resource.

**Returns:** `Splitter, error`



##### Options {id="markdown-splitter-options"}


| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `chunk_size` | integer | 4000 | Max characters per chunk |
| `chunk_overlap` | integer | 200 | Characters repeated between adjacent chunks |
| `code_blocks` | boolean | false | Keep code blocks together |
| `reference_links` | boolean | false | Preserve reference links |
| `heading_hierarchy` | boolean | false | Respect heading levels |
| `join_table_rows` | boolean | false | Keep table rows together |
| `separators` | string[] | nil | Custom separator list |



#### `splitter:split_text`


Split a single document into an array of chunks.

```lua
local chunks, err = splitter:split_text(document)
if err then
    return nil, err
end

for i, chunk in ipairs(chunks) do
    -- Process each chunk (e.g., create embedding, send to LLM)
    process(chunk)
end
```

Here, `splitter` is a successfully created splitter, while `document` and `process` are supplied by the application.

| Parameter | Type | Description |
|-----------|------|-------------|
| `text` | string | Text to split |

**Returns:** `string[], error`



#### `splitter:split_batch`


Split multiple documents while preserving their metadata. One input document can produce several chunks, each with the source document's metadata.

```lua
-- Input: pages from a PDF with page numbers
local pages = {
    {content = "First page content...", metadata = {page = 1}},
    {content = "Second page content...", metadata = {page = 2}}
}

local chunks, err = splitter:split_batch(pages)
if err then
    return nil, err
end

-- Output: each chunk knows which page it came from
for _, chunk in ipairs(chunks) do
    print("Page " .. chunk.metadata.page .. ": " .. chunk.content:sub(1, 50))
end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `pages` | table | Array of {content, metadata} |

**Returns:** `table, error` (array of {content, metadata})

`split_batch` silently skips an item when the item is not a table, its `content` field is missing, empty, or not a string, or splitting that item fails. It still returns the remaining chunks with a `nil` error. Validate every input item before the call and verify any cardinality requirements in application code; do not treat a successful call as proof that every input was represented.



### Errors


| Condition | Kind | Retryable |
|-----------|------|-----------|
| Invalid pattern syntax | `errors.INVALID` | no |
| Internal error | `errors.INTERNAL` | no |

See [Error Handling](lua/core/errors.md) for working with errors.



---

# "Template Engine"

## Template Engine

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="external"/>

The `templates` module renders [Jet](https://github.com/CloudyKit/jet) templates from configured sets. Templates can use inheritance and includes. This page is an API reference with isolated rendering examples, not a standalone template deployment. The registry IDs and template sources must already be configured, and the executable entry must enable `templates` and have `template.get` permission for the requested set.

For template set configuration, see [Template Engine](system/template.md).



### Loading


```lua
local templates = require("templates")
```



### `templates.get`


Acquire a template set by registry ID:

```lua
local set, err = templates.get("app.views:emails")
if err then
    return nil, err
end

-- Use the set...

return set:release()
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | string | Template set registry ID |

**Returns:** `Set, error`



### `set:render`


Render a template by name with data:

```lua
local set, get_err = templates.get("app.views:emails")
if get_err then
    return nil, get_err
end

local html, err = set:render("welcome", {
    user = {name = "Alice", email = "alice@example.com"},
    activation_url = "https://example.invalid/activate"
})

set:release()
if err then
    return nil, err
end

return html
```

The caller owns every acquired set until `release()` is called. Release it after the final render, including checked error paths; repeated releases are safe. Rendering does not make application-provided values safe for every output context. Keep secrets and one-time URLs out of logs, and apply the escaping or sanitization required where the rendered string is consumed.

| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | string | Template name within the set |
| `data` | table | Variables to pass to template (optional) |

**Returns:** `string, error`



### Set Method Summary


The set handle provides these methods:

| Method | Returns | Description |
|--------|---------|-------------|
| `render(name, data?)` | `string, error` | Render template with data |
| `release()` | `boolean` | Release set back to pool |



### Jet Syntax Reference


Jet uses `{{ }}` for expressions and control structures and `{* *}` for comments.



#### Variables


```html
{{ user.name }}
{{ user.email }}
{{ items[0].price }}
```



#### Conditionals


```html
{{ if order.shipped }}
    <p>Shipped!</p>
{{ else if order.processing }}
    <p>Processing...</p>
{{ else }}
    <p>Received.</p>
{{ end }}
```



#### Loops


```html
{{ range items }}
    <li>{{ .name }} - ${{ .price }}</li>
{{ end }}

{{ range i, item := items }}
    <p>{{ i }}. {{ item.name }}</p>
{{ end }}
```



#### Inheritance


```html
{* Parent: layout.jet *}
<html>
<head><title>{{ yield title() }}</title></head>
<body>{{ yield body() }}</body>
</html>

{* Child: page.jet *}
{{ extends "layout" }}
{{ block title() }}My Page{{ end }}
{{ block body() }}<p>Content</p>{{ end }}
```



#### Includes


```html
{{ include "partials/header" }}
<main>Content</main>
{{ include "partials/footer" }}
```



### Errors


| Condition | Kind | Retryable |
|-----------|------|-----------|
| Empty ID | `errors.INVALID` | no |
| Empty template name | `errors.INVALID` | no |
| Permission denied | `errors.PERMISSION_DENIED` | no |
| Template set missing, unavailable, or wrong resource type | `errors.INTERNAL` | no |
| Template not found | `errors.NOT_FOUND` | no |
| Render error | `errors.INTERNAL` | no |
| Render attempted after the set was released | `errors.INTERNAL` | no |

See [Error Handling](lua/core/errors.md) for working with errors.



---

# "Tree-sitter Parsing"

## Tree-sitter Parsing

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="workflow"/>

The `treesitter` module parses source code into concrete syntax trees with [Tree-sitter](https://tree-sitter.github.io/tree-sitter/) through the [go-tree-sitter](https://github.com/tree-sitter/go-tree-sitter) bindings.

This page is an API reference with partial parsing recipes. Source strings and query patterns are application input, and node-level snippets assume a live tree from an earlier checked parse. Parsers, trees, queries, and cursors are owned resources: close every successfully created handle when its last dependent operation is complete.

The resulting syntax trees:
- Represent the full structure of source code
- Update incrementally as code changes
- Are robust to syntax errors (partial parsing)
- Support pattern-based queries using S-expressions



### Loading


```lua
local treesitter = require("treesitter")
```

<note>
The `treesitter` module is optional and is present only in builds that include the `treesitter` build tag. Official Wippy binaries include it. Source builds can use `make build-wippy` or `go build -tags treesitter`; without the tag, `require("treesitter")` is unavailable.
</note>



### Supported Languages


| Language | Aliases | Root Node |
|----------|---------|-----------|
| Go | `go`, `golang` | `source_file` |
| JavaScript | `js`, `javascript` | `program` |
| TypeScript | `ts`, `typescript` | `program` |
| TSX | `tsx` | `program` |
| Python | `python`, `py` | `module` |
| Lua | `lua` | `chunk` |
| PHP | `php` | `program` |
| C# | `csharp`, `cs`, `c#` | `compilation_unit` |
| HTML | `html`, `html5` | `document` |
| Markdown | `markdown`, `md` | `document` |
| SQL | `sql` | - |

```lua
local langs = treesitter.supported_languages()
-- {go = true, javascript = true, python = true, ...}
```



#### Parse Code


```lua
local code = [[
func hello() {
    return "Hello!"
}
]]

local tree, err = treesitter.parse("go", code)
if err then
    return nil, err
end

local root, root_err = tree:root_node()
if root_err then
    tree:close()
    return nil, root_err
end
print(root:kind())        -- "source_file"
print(root:child_count()) -- number of top-level declarations
tree:close()
```



#### Query Syntax Tree


```lua
local code = [[
func hello() {}
func world() {}
]]

local tree, parse_err = treesitter.parse("go", code)
if parse_err then
    return nil, parse_err
end
local root, root_err = tree:root_node()
if root_err then
    tree:close()
    return nil, root_err
end

-- Find all function names
local query, query_err = treesitter.query("go", [[
    (function_declaration name: (identifier) @func_name)
]])
if query_err then
    tree:close()
    return nil, query_err
end

local captures, captures_err = query:captures(root, code)
if captures_err then
    query:close()
    tree:close()
    return nil, captures_err
end
for _, capture in ipairs(captures) do
    print(capture.name, capture.text)
end
-- "func_name"  "hello"
-- "func_name"  "world"
query:close()
tree:close()
```



#### Simple Parse


Parse source code with a temporary internal parser.

```lua
local tree, err = treesitter.parse("go", code)
if err then
    return nil, err
end
-- Use the tree, then call tree:close().
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `language` | string | Language name or alias |
| `code` | string | Source code |

**Returns:** `Tree, error`



#### Reusable Parser


Create a reusable parser for repeated parsing or incremental updates.

```lua
local parser, parser_err = treesitter.parser()
if parser_err then
    return nil, parser_err
end
local _, language_err = parser:set_language("go")
if language_err then
    parser:close()
    return nil, language_err
end

local tree1, first_err = parser:parse("package main")
if first_err then
    parser:close()
    return nil, first_err
end

-- Parse another source with the reusable parser. For an incremental update,
-- edit the old tree first as shown in the complete recipe below.
local tree2, second_err = parser:parse("package main\nfunc foo() {}")
if second_err then
    tree1:close()
    parser:close()
    return nil, second_err
end

tree2:close()
tree1:close()
parser:close()
```

**Returns:** `Parser, error`



#### Parser Methods


| Method | Description |
|--------|-------------|
| `set_language(lang)` | Set parser language, returns `boolean, error` |
| `get_language()` | Get current language name |
| `parse(code, old_tree?)` | Parse code, optionally with old tree for incremental parsing |
| `set_timeout(duration)` | Set parse timeout (string like `"1s"` or nanoseconds) |
| `set_ranges(ranges)` | Set byte ranges to parse |
| `reset()` | Reset parser state |
| `close()` | Release parser resources |

Trees created by a reusable parser and the parser itself are independently owned; close each successful handle. Nodes borrow their tree's storage and must not be used after that tree is closed. Cursors borrow a tree as well, so close them before the tree. Queries own separate native resources and also require `close()`; close a query after its captures or matches are no longer needed. Explicit cleanup is deterministic, while the process resource store is only a fallback for handles left open at process teardown.



#### Get Root Node


```lua
local tree, err = treesitter.parse("go", "package main")
if err then
    return nil, err
end
local root, root_err = tree:root_node()
if root_err then
    tree:close()
    return nil, root_err
end

print(root:kind())  -- "source_file"
local source_text, text_err = root:text()
if text_err then
    tree:close()
    return nil, text_err
end
print(source_text)  -- "package main"
tree:close()
```



#### Tree Methods


| Method | Description |
|--------|-------------|
| `root_node()` | Get root node of tree |
| `root_node_with_offset(bytes, point)` | Get root with offset applied |
| `language()` | Get tree's language object |
| `copy()` | Create deep copy of tree |
| `walk()` | Create cursor for traversal |
| `edit(edit_table)` | Apply incremental edit |
| `changed_ranges(other_tree)` | Get ranges that changed |
| `included_ranges()` | Get ranges included during parsing |
| `dot_graph()` | Get DOT graph representation |
| `close()` | Release tree resources |



#### Incremental Editing


Apply an edit before reparsing changed source code:

```lua
local code = "func main() { x := 1 }"
local tree, parse_err = treesitter.parse("go", code)
if parse_err then
    return nil, parse_err
end

-- Mark edit: changed "1" to "100" at byte 19
local _, edit_err = tree:edit({
    start_byte = 19,
    old_end_byte = 20,
    new_end_byte = 22,
    start_row = 0,
    start_column = 19,
    old_end_row = 0,
    old_end_column = 20,
    new_end_row = 0,
    new_end_column = 22
})
if edit_err then
    tree:close()
    return nil, edit_err
end

-- Re-parse with edited tree (faster than full parse)
local parser, parser_err = treesitter.parser()
if parser_err then
    tree:close()
    return nil, parser_err
end
local _, language_err = parser:set_language("go")
if language_err then
    parser:close()
    tree:close()
    return nil, language_err
end
local new_tree, new_tree_err = parser:parse("func main() { x := 100 }", tree)
if new_tree_err then
    parser:close()
    tree:close()
    return nil, new_tree_err
end

new_tree:close()
parser:close()
tree:close()
```



### Nodes


Nodes represent elements in the syntax tree. In the isolated snippets below, `root`, `node`, and `func_decl` are application-selected nodes borrowed from a still-open tree.



#### Node Types


```lua
local node = root:child(0)

-- Type information
print(node:kind())        -- "package_clause"
print(node:type())        -- same as kind()
print(node:is_named())    -- true for significant nodes
print(node:grammar_name()) -- grammar rule name
```



#### Navigation


```lua
-- Children
local child = node:child(0)           -- by index (0-based)
local named = node:named_child(0)     -- named children only
local count = node:child_count()
local named_count = node:named_child_count()

-- Siblings
local next = node:next_sibling()
local prev = node:prev_sibling()
local next_named = node:next_named_sibling()
local prev_named = node:prev_named_sibling()

-- Parent
local parent = node:parent()

-- By field name
local name_node = func_decl:child_by_field_name("name")
local field = node:field_name_for_child(0)
```



#### Position Information


```lua
-- Byte offsets
local start = node:start_byte()
local end_ = node:end_byte()

-- Row/column positions (0-based)
local start_pt = node:start_point()  -- {row = 0, column = 0}
local end_pt = node:end_point()      -- {row = 0, column = 12}

-- Source text
local source_text, err = node:text()
if err then
    return nil, err
end
```



#### Error Detection


```lua
if root:has_error() then
    -- Tree contains syntax errors
end

if node:is_error() then
    -- This specific node is an error
end

if node:is_missing() then
    -- Parser inserted this to recover from error
end

if node:is_extra() then
    -- Node is an "extra" (e.g. a comment) not required by the grammar
end
```

Other node methods: `descendant_count()` and `named_descendant_for_point_range(start_pt, end_pt)`.



#### S-Expression


```lua
local sexp = node:to_sexp()
-- "(source_file (package_clause (package_identifier)))"
```



### Queries


Tree-sitter queries match syntax-tree patterns written as S-expressions.



#### Create Query


```lua
local query, err = treesitter.query("go", [[
    (function_declaration
        name: (identifier) @func_name
        parameters: (parameter_list) @params
    )
]])
if err then
    return nil, err
end
-- The owner calls query:close() after the final query operation.
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `language` | string | Language name |
| `pattern` | string | Query pattern in S-expression syntax |

**Returns:** `Query, error`



#### Execute Query


```lua
-- Get all captures (flattened)
local captures, captures_err = query:captures(root, source_code)
if captures_err then
    query:close()
    tree:close()
    return nil, captures_err
end
for _, capture in ipairs(captures) do
    print(capture.name)   -- "func_name"
    print(capture.text)   -- actual text
    print(capture.index)  -- capture index
    -- capture.node is the Node object
end

-- Get matches (grouped by pattern)
local matches, matches_err = query:matches(root, source_code)
if matches_err then
    query:close()
    tree:close()
    return nil, matches_err
end
for _, match in ipairs(matches) do
    print(match.id, match.pattern)
    for _, capture in ipairs(match.captures) do
        local captured_text, text_err = capture.node:text()
        if text_err then
            query:close()
            tree:close()
            return nil, text_err
        end
        print(capture.name, captured_text)
    end
end

query:close()
tree:close()
```

Passing userdata of the wrong type instead of a Tree-sitter `Node` returns `nil, error`; passing a primitive or table raises a Lua argument error before that check. `root`, `source_code`, and `query` here must come from a still-open tree and a successfully created query. The snippet uses the owning `tree` handle to close both resources before it returns.



#### Query Control


```lua
-- Limit query scope
query:set_byte_range(0, 1000)
query:set_point_range({row = 0, column = 0}, {row = 10, column = 0})

-- Limit matches
query:set_match_limit(100)
if query:did_exceed_match_limit() then
    -- More matches exist
end

-- Timeout (string duration or nanoseconds)
query:set_timeout("500ms")
query:set_timeout(1000000000)  -- 1 second in nanoseconds

-- Disable patterns/captures
query:disable_pattern(0)
query:disable_capture("func_name")
```



#### Query Inspection


```lua
local pattern_count = query:pattern_count()
local capture_count = query:capture_count()
local name = query:capture_name_for_id(0)
local id = query:capture_index_for_name("func_name")
```

Further inspection methods: `string_count()`, `start_byte_for_pattern(i)`, `end_byte_for_pattern(i)`, `get_match_limit()`, `get_timeout()`, `is_pattern_rooted(i)`, `is_pattern_non_local(i)`, `is_pattern_guaranteed(i)`, `capture_quantifier(pattern, capture)`, `set_max_start_depth(n)`, `get_property_predicates(i)`, `get_property_settings(i)`, `get_text_predicates(i)`.



### Tree Cursor


A tree cursor traverses a tree without creating a node object at every step.



#### Basic Traversal


```lua
local cursor, err = tree:walk()
if err then
    return nil, err
end

-- Start at root
print(cursor:current_node():kind())  -- "source_file"
print(cursor:current_depth())        -- 0

-- Navigate
if cursor:goto_first_child() then
    print(cursor:current_node():kind())
    print(cursor:current_depth())  -- 1
end

if cursor:goto_next_sibling() then
    -- moved to next sibling
end

cursor:goto_parent()  -- back to parent

cursor:close()
```



#### Cursor Methods


| Method | Returns | Description |
|--------|---------|-------------|
| `current_node()` | `Node` | Node at cursor position |
| `current_depth()` | `integer` | Depth (0 = root) |
| `current_field_name()` | `string?` | Field name if any |
| `current_field_id()` | `integer` | Field ID (0 if none) |
| `current_descendant_index()` | `integer` | Descendant index of current node |
| `goto_parent()` | `boolean` | Move to parent |
| `goto_first_child()` | `boolean` | Move to first child |
| `goto_last_child()` | `boolean` | Move to last child |
| `goto_next_sibling()` | `boolean` | Move to next sibling |
| `goto_previous_sibling()` | `boolean` | Move to previous sibling |
| `goto_descendant(index)` | - | Move to descendant by index |
| `goto_first_child_for_byte(n)` | `integer?` | Move to child containing byte |
| `goto_first_child_for_point(pt)` | `integer?` | Move to child containing point |
| `reset(node)` | - | Reset cursor to node |
| `reset_to(cursor)` | - | Reset cursor to another cursor's position |
| `copy()` | `Cursor` | Create copy of cursor |
| `close()` | - | Release resources |



### Language Metadata


```lua
local lang, err = treesitter.language("go")
if err then
    return nil, err
end

print(lang:version())           -- ABI version
print(lang:node_kind_count())   -- number of node types
print(lang:field_count())       -- number of fields
print(lang:parse_state_count()) -- number of parse states

-- Node kind lookup
local kind = lang:node_kind_for_id(1)
local id = lang:id_for_node_kind("identifier", true)
local is_named = lang:node_kind_is_named(1)

-- Field lookup
local field_name = lang:field_name_for_id(1)
local field_id = lang:field_id_for_name("name")
```



### Errors


| Condition | Kind | Retryable |
|-----------|------|-----------|
| Language not supported | `errors.INVALID` | no |
| Language has no binding | `errors.INVALID` | no |
| Invalid query pattern | `errors.INVALID` | no |
| Invalid positions | `errors.INVALID` | no |
| Parse failed | `errors.INTERNAL` | no |
| No execution context | `errors.INTERNAL` | no |

Closing an already closed parser, tree, query, or cursor is safe. Calling any other method on a closed handle raises a Lua argument error.

See [Error Handling](lua/core/errors.md) for working with errors.



### Query Syntax Reference


Tree-sitter queries use S-expression patterns:

```
; Match a node type
(identifier)

; Match with field names
(function_declaration name: (identifier))

; Capture with @name
(function_declaration name: (identifier) @func_name)

; Multiple patterns
[
  (function_declaration)
  (method_declaration)
] @declaration

; Wildcards
(_)           ; any node
(identifier)+ ; one or more
(identifier)* ; zero or more
(identifier)? ; optional

; Predicates
((identifier) @var
  (#match? @var "^_"))  ; regex match
```

See [Tree-sitter Query Syntax](https://tree-sitter.github.io/tree-sitter/using-parsers#query-syntax) for complete documentation.



---

# "Security & Access Control"

## Security & Access Control

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="permissions"/>

The `security` module exposes authentication actors, authorization scopes, policies, and token stores. This page is an API reference with partial authorization recipes. Registry IDs, actors, request metadata, token values, application objects such as `user` and `doc`, and callbacks such as `show_admin_features` come from the surrounding application; the examples are not a complete authentication deployment.

Wippy runs in strict security mode by default. The executable entry must enable `security`, have an actor and scope, and authorize the exact operations it calls. In particular, construction and scope changes need `security.actor.create` or `security.scope.create`; registry lookup needs `security.policy.get` or `security.policy_group.get`; token work needs `security.token_store.get` plus the operation-specific token permission. `new_actor`, `new_scope`, `scope:with`, `scope:without`, and permission-denied `token_store` acquisition raise a Lua error instead of returning a structured `error`. Grant these prerequisites in the entry's security context rather than trying to recover after a denial. See [Security Model](system/security.md) for configuration.



### Loading


```lua
local security = require("security")
```



### `actor`


Return the current security actor from the execution context.

```lua
local actor = security.actor()
if actor then
    local id = actor:id()
    local meta = actor:meta()
    -- Use only the fields required for authorization or application logic.
    local role = meta.role
end
```

Actor metadata can contain identifiers or personal data. Do not log the complete metadata table or copy secrets into it.

**Returns:** `Actor|nil`



### `scope`


Return the current security scope from the execution context.

```lua
local scope = security.scope()
if scope then
    local policies = scope:policies()
    for _, policy in ipairs(policies) do
        print("Active policy:", policy:id())
    end
end
```

**Returns:** `Scope|nil`



### `can`


Check whether the current context allows an action on a resource.

```lua
-- Check read permission
if not security.can("read", "user:" .. user_id) then
    return nil, errors.new("Cannot read user data"):kind(errors.PERMISSION_DENIED)
end

-- Check write permission
if not security.can("write", "order:" .. order_id) then
    return nil, errors.new("Cannot modify order"):kind(errors.PERMISSION_DENIED)
end

-- Check with metadata
local allowed = security.can("delete", "document:" .. doc_id, {
    owner_id = doc.owner_id,
    department = doc.department
})
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `action` | string | Action to check |
| `resource` | string | Resource identifier |
| `meta` | table | Additional metadata (optional) |

**Returns:** `boolean`



### `new_actor`


Create an actor with an ID and metadata.

```lua
-- Create user actor
local actor = security.new_actor("user:" .. user.id, {
    role = user.role,
    department = user.department,
    email = user.email
})

-- Create service actor
local service_actor = security.new_actor("service:payment-processor", {
    type = "service",
    version = "1.0.0"
})
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | string | Unique actor identifier |
| `meta` | table | Metadata key-value pairs |

**Returns:** `Actor`



### `new_scope`


Create a custom scope.

```lua
-- Empty scope
local scope = security.new_scope()

-- Scope with policies
local read_policy, read_err = security.policy("app:read-only")
if read_err then
    return nil, read_err
end
local scope = security.new_scope({read_policy})

-- Build scope incrementally
local scope = security.new_scope()
local policy1, policy1_err = security.policy("app:read")
if policy1_err then
    return nil, policy1_err
end
local policy2, policy2_err = security.policy("app:write")
if policy2_err then
    return nil, policy2_err
end
scope = scope:with(policy1):with(policy2)
```

Each alternative above is an isolated construction pattern. `new_scope` and `scope:with` can raise on missing context or permission denial; they do not return `nil, error` for those checks.

**Returns:** `Scope`



### `policy`


Retrieve a policy from the registry.

```lua
local policy, err = security.policy("app:admin-access")
if err then
    return nil, err
end

-- Evaluate policy
local result = policy:evaluate(actor, "delete", "user:123")
if result == "allow" then
    -- permitted
elseif result == "deny" then
    -- forbidden
else
    -- undefined, check other policies
end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | string | Policy ID "namespace:name" |

**Returns:** `Policy, error`



### `named_scope`


Retrieve a predefined policy group.

```lua
-- Get admin scope
local admin_scope, err = security.named_scope("app:admin")
if err then
    return nil, err
end

-- Use for elevated operations
local result = admin_scope:evaluate(actor, "delete", "user:123")
```

Loading a scope does not elevate the current execution context. It produces a value for explicit evaluation or for an API that accepts a scope; the caller still needs permission to perform the protected operation.

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | string | Policy group ID |

**Returns:** `Scope, error`



### `token_store`


Acquire a token store for managing authentication tokens.

```lua
local store, err = security.token_store("app:tokens")
if err then
    return nil, err
end

-- Use store...
return store:close()
```

The caller owns an acquired token store until `close()` is called. Close it after the final operation on every checked success or error path; repeated closes are safe. A permission denial during acquisition raises a Lua error, while lookup and resource failures return `nil, error`.

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | string | Token store ID "namespace:name" |

**Returns:** `TokenStore, error`



### `Actor` Methods


| Method | Returns | Description |
|--------|---------|-------------|
| `actor:id()` | string | Actor identifier |
| `actor:meta()` | table | Actor metadata |



#### `with` / `without`


Add or remove policies from scope.

```lua
local scope = security.new_scope()

-- Add policy
local write_policy, err = security.policy("app:write")
if err then
    return nil, err
end
scope = scope:with(write_policy)

-- Remove policy
scope = scope:without("app:read-only")
```

`with` and `without` return new immutable scope values and raise when `security.scope.create` is not allowed for the `with` or `without` resource.



#### `evaluate`


Evaluate all policies in scope.

```lua
local result = scope:evaluate(actor, "read", "document:123")
-- "allow", "deny", or "undefined"

if result ~= "allow" then
    return nil, errors.new("Access denied"):kind(errors.PERMISSION_DENIED)
end
```



#### `contains`


Check whether the scope contains a policy.

```lua
if scope:contains("app:admin") then
    show_admin_features()
end
```



#### `policies`


Return all policies in the scope.

```lua
local policies = scope:policies()
for _, policy in ipairs(policies) do
    print(policy:id())
end
```

**Returns:** `Policy[]`



### `Policy` Methods


| Method | Returns | Description |
|--------|---------|-------------|
| `policy:id()` | string | Policy identifier |
| `policy:evaluate(actor, action, resource, meta?)` | string | `"allow"`, `"deny"`, or `"undefined"` |



#### `create`


Create an authentication token.

```lua
local actor = security.new_actor("user:123", {role = "user"})
local scope, scope_err = security.named_scope("app:default")
if scope_err then
    return nil, scope_err
end
local store, store_err = security.token_store("app:tokens")
if store_err then
    return nil, store_err
end

local token, err = store:create(actor, scope, {
    expiration = "24h",  -- or milliseconds
    meta = {
        login_ip = request_ip,
        user_agent = user_agent
    }
})
store:close()
if err then
    return nil, err
end
return token
```

`request_ip` and `user_agent` are application-provided request values. Store only metadata needed for security decisions, apply retention limits, and never log or persist the returned bearer token outside the intended credential store.

| Parameter | Type | Description |
|-----------|------|-------------|
| `actor` | Actor | Actor for the token |
| `scope` | Scope | Permissions scope |
| `options.expiration` | string/number | Duration string or ms |
| `options.meta` | table | Token metadata |

**Returns:** `string, error`



#### `validate`


Validate a token and return its actor and scope.

```lua
local actor, scope, err = store:validate(token)
store:close()
if err then
    return nil, errors.new("Invalid token"):kind(errors.PERMISSION_DENIED)
end
```

Here and below, `store` is a live owned handle and `token` is an untrusted bearer credential supplied by the caller. Do not log the token, including on validation or revocation errors.

**Returns:** `Actor, Scope, error`



#### `revoke`


Invalidate a token.

```lua
local ok, err = store:revoke(token)
store:close()
if err then
    return nil, err
end
```

**Returns:** `boolean, error`



#### `close`


Release the token store resource.

```lua
store:close()
```

**Returns:** `boolean`



### Permissions


Security policy evaluation applies to security operations.



#### Security Actions


| Action | Resource | Description |
|--------|----------|-------------|
| `security.policy.get` | Policy ID | Access policy definitions |
| `security.policy_group.get` | Group ID | Access named scopes |
| `security.scope.create` | `custom`, `with`, `without` | Create custom scopes (`new_scope`) and add/remove policies (`scope:with`, `scope:without`) |
| `security.actor.create` | Actor ID | Create actors |
| `security.token_store.get` | Store ID | Access token stores |
| `security.token.validate` | Store ID | Validate tokens |
| `security.token.create` | Store ID | Create tokens |
| `security.token.revoke` | Store ID | Revoke tokens |

See [Security Model](system/security.md) for policy configuration.



### Errors


| Condition | Kind | Retryable |
|-----------|------|-----------|
| No context | `errors.INTERNAL` | no |
| Empty token store ID | `errors.INVALID` | no |
| Permission denied (`policy`, `named_scope`, token `create`/`validate`/`revoke`) | `errors.INVALID` | no |
| Permission denied (`new_scope`, `new_actor`, `token_store`, `scope:with`/`without`) | raised as a Lua error | no |
| Policy not found | `errors.INTERNAL` | no |
| Token store not found | `errors.INTERNAL` | no |
| Token store closed | `errors.INTERNAL` | no |
| Invalid expiration format | `errors.INVALID` | no |
| Token validation failed | `errors.INTERNAL` | no |

```lua
local store, err = security.token_store("app:tokens")
if err then
    if errors.is(err, errors.INVALID) then
        print("Invalid request:", err:message())
    end
    return nil, err
end
store:close()
```

See [Error Handling](lua/core/errors.md) for working with errors.



### See Also


- [Security Model](../../system/security.md) - Actors, policies, scopes configuration
- [HTTP Middleware](http/middleware.md) - Endpoint and resource firewall



---

# "Encryption & Signing"

## Encryption & Signing

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="workflow"/>
<secondary-label ref="io"/>

The `crypto` module generates random values, computes HMACs, encrypts and decrypts data, encodes and verifies JWTs, and derives keys. In deterministic workflows, random generation and encryption (which creates a random nonce) run as recorded side effects; replay returns the recorded bytes. Other operations, including HMAC, decryption, JWT processing, PBKDF2, and comparison, run directly.

This page is an API reference. Each code block is an isolated call, not a complete key-management or authentication system. Names such as `data`, `key`, `aad`, `payload`, and `token` are application-provided values. Load keys and passwords through the application's secret-management boundary; do not hard-code, log, or return them in diagnostics. Before consuming any `value, error` result shown here, propagate or handle the error.



### Loading


```lua
local crypto = require("crypto")
```



#### Random Bytes


```lua
local bytes, err = crypto.random.bytes(32)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `length` | integer | Number of bytes (1 to 1,048,576) |

**Returns:** `string, error`



#### Random String


```lua
local str, err = crypto.random.string(32)
local str, err = crypto.random.string(32, "0123456789abcdef")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `length` | integer | Output length in bytes (1 to 1,048,576) |
| `charset` | string? | ASCII byte alphabet to use (default: alphanumeric) |

**Returns:** `string, error`

The implementation selects bytes from the supplied alphabet. A non-ASCII alphabet can be split into invalid UTF-8, and modulo selection is exactly uniform only when the alphabet's byte length divides 256. For uniformly random secret material, use `crypto.random.bytes` and encode the result for the required transport format.



#### Random UUID


```lua
local id, err = crypto.random.uuid()
```

**Returns:** `string, error`



#### HMAC-SHA256


```lua
local hex, err = crypto.hmac.sha256(key, data)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `key` | string | HMAC key |
| `data` | string | Data to authenticate |

**Returns:** `string, error`



#### HMAC-SHA512


```lua
local hex, err = crypto.hmac.sha512(key, data)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `key` | string | HMAC key |
| `data` | string | Data to authenticate |

**Returns:** `string, error`



#### AES-GCM {id="encrypt-aes-gcm"}


```lua
local encrypted, err = crypto.encrypt.aes(data, key)
local encrypted, err = crypto.encrypt.aes(data, key, aad)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | Plaintext to encrypt |
| `key` | string | 16, 24, or 32 bytes (AES-128/192/256) |
| `aad` | string? | Additional authenticated data |

**Returns:** `string, error` (nonce prepended)

Both encryption functions generate a nonce and prepend it to the ciphertext. Do not remove or reuse it, and use the same AAD during decryption. Ciphertext is not a secret-free log value: it can expose length and correlation information.



#### ChaCha20-Poly1305 {id="encrypt-chacha20"}


```lua
local encrypted, err = crypto.encrypt.chacha20(data, key)
local encrypted, err = crypto.encrypt.chacha20(data, key, aad)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | Plaintext to encrypt |
| `key` | string | Must be 32 bytes |
| `aad` | string? | Additional authenticated data |

**Returns:** `string, error` (nonce prepended)



#### AES-GCM {id="decrypt-aes-gcm"}


```lua
local plaintext, err = crypto.decrypt.aes(encrypted, key)
local plaintext, err = crypto.decrypt.aes(encrypted, key, aad)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | Encrypted data from encrypt.aes |
| `key` | string | Same key used for encryption |
| `aad` | string? | Must match AAD used in encryption |

**Returns:** `string, error`



#### ChaCha20-Poly1305 {id="decrypt-chacha20"}


```lua
local plaintext, err = crypto.decrypt.chacha20(encrypted, key)
local plaintext, err = crypto.decrypt.chacha20(encrypted, key, aad)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | Encrypted data from encrypt.chacha20 |
| `key` | string | Same key used for encryption |
| `aad` | string? | Must match AAD used in encryption |

**Returns:** `string, error`



#### Encode


```lua
local token, err = crypto.jwt.encode(payload, secret)
local token, err = crypto.jwt.encode(payload, secret, "HS256")
local token, err = crypto.jwt.encode(payload, private_key_pem, "RS256")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `payload` | table | JWT claims (`_header` for custom header) |
| `key` | string | Secret (HMAC) or PEM private key (RSA) |
| `alg` | string? | HS256, HS384, HS512, RS256 (default: HS256) |

**Returns:** `string, error`

Pass only one of the documented algorithm names. At this runtime pin, an unsupported value passed to `encode` falls back to HS256 instead of returning an error. Validate any configurable algorithm before this call, and do not copy untrusted fields into `_header`; in particular, do not let input override reserved JWT headers such as `alg`.



#### Verify


```lua
local claims, err = crypto.jwt.verify(token, secret)
local claims, err = crypto.jwt.verify(token, secret, "HS256", false)
local claims, err = crypto.jwt.verify(token, public_key_pem, "RS256")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `token` | string | JWT token to verify |
| `key` | string | Secret (HMAC) or PEM public key (RSA) |
| `alg` | string? | Expected algorithm (default: HS256) |
| `require_exp` | boolean? | Require an `exp` claim to be present (default: true); an `exp` that is present is always validated |

**Returns:** `table, error`

Whenever present, `exp` and `nbf` are validated against the JWT library's current wall clock, not the workflow time reference. Setting `require_exp = false` permits a missing `exp` claim; it does not disable validation of a claim that is present. Do not use either time-dependent result for replay-sensitive workflow control; perform the check in an activity or validate time against an explicitly replay-safe value.

Always pass the algorithm expected by the issuer; verification restricts the token to that exact method. Treat returned claims as authenticated data, not automatically authorized application input, and still validate issuer, audience, subject, and application-specific constraints.



#### PBKDF2


```lua
local key, err = crypto.pbkdf2(password, salt, iterations, key_length)
local key, err = crypto.pbkdf2(password, salt, iterations, key_length, "sha512")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `password` | string | Password/passphrase |
| `salt` | string | Salt value |
| `iterations` | integer | Iteration count (max 10,000,000) |
| `key_length` | integer | Desired key length in bytes |
| `hash` | string? | sha256 or sha512 (default: sha256) |

**Returns:** `string, error`

The derived key is raw bytes. Use a fresh random salt for each stored password verifier and store the salt and work-factor parameters alongside the verifier; the salt need not be secret. Do not use a fixed example salt for production password storage.



#### Constant-Time Compare


```lua
local equal = crypto.constant_time_compare(a, b)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `a` | string | First string |
| `b` | string | Second string |

**Returns:** `boolean`

The result is `false` when lengths differ. The underlying constant-time comparison guarantee applies to equal-length inputs, so compare fixed-length digests or other same-length secrets.



### Errors


| Condition | Kind | Retryable |
|-----------|------|-----------|
| Invalid length | `errors.INVALID` | no |
| Empty key | `errors.INVALID` | no |
| Invalid key size | `errors.INVALID` | no |
| Decryption failed | `errors.INTERNAL` | no |
| Token expired | `errors.INTERNAL` | no |

See [Error Handling](lua/core/errors.md) for working with errors.



---

# "Hash Functions"

## Hash Functions

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="workflow"/>
<secondary-label ref="encoding"/>

The `hash` module computes cryptographic hashes, HMAC values, PBKDF2-derived keys, and non-cryptographic FNV-1 hashes. This page is an API reference of isolated calls. Literal inputs illustrate successful use; when data, secrets, passwords, or salts come from the application, capture and handle the documented second `error` return before consuming the result.

A hash is not encryption and does not conceal low-entropy input. Do not log passwords, HMAC keys, derived keys, or raw secret-dependent digests. Use HMAC-SHA256 or HMAC-SHA512 for new message-authentication designs and PBKDF2 with a unique random salt for password verifiers.



### Loading


```lua
local hash = require("hash")
```



#### MD5


MD5 is not collision-resistant. Use it only for compatibility with protocols that require MD5, not for security decisions.

```lua
local hex = hash.md5("data")
local raw = hash.md5("data", true)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | Data to hash |
| `raw` | boolean? | Return raw bytes instead of hex |

**Returns:** `string, error`



#### SHA-1


SHA-1 is not collision-resistant. Use it only for compatibility with protocols that require SHA-1, not for security decisions.

```lua
local hex = hash.sha1("data")
local raw = hash.sha1("data", true)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | Data to hash |
| `raw` | boolean? | Return raw bytes instead of hex |

**Returns:** `string, error`



#### SHA-256


```lua
local hex = hash.sha256("data")
local raw = hash.sha256("data", true)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | Data to hash |
| `raw` | boolean? | Return raw bytes instead of hex |

**Returns:** `string, error`



#### SHA-512


```lua
local hex = hash.sha512("data")
local raw = hash.sha512("data", true)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | Data to hash |
| `raw` | boolean? | Return raw bytes instead of hex |

**Returns:** `string, error`



#### HMAC-MD5


Use HMAC-MD5 only for compatibility with a protocol that requires it; prefer HMAC-SHA256 or HMAC-SHA512 for new designs.

```lua
local hex = hash.hmac_md5("message", "secret")
local raw = hash.hmac_md5("message", "secret", true)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | Message to authenticate |
| `secret` | string | Secret key |
| `raw` | boolean? | Return raw bytes instead of hex |

**Returns:** `string, error`



#### HMAC-SHA1


Use HMAC-SHA1 only for compatibility with a protocol that requires it; prefer HMAC-SHA256 or HMAC-SHA512 for new designs.

```lua
local hex = hash.hmac_sha1("message", "secret")
local raw = hash.hmac_sha1("message", "secret", true)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | Message to authenticate |
| `secret` | string | Secret key |
| `raw` | boolean? | Return raw bytes instead of hex |

**Returns:** `string, error`



#### HMAC-SHA256


```lua
local hex = hash.hmac_sha256("message", "secret")
local raw = hash.hmac_sha256("message", "secret", true)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | Message to authenticate |
| `secret` | string | Secret key |
| `raw` | boolean? | Return raw bytes instead of hex |

**Returns:** `string, error`



#### HMAC-SHA512


```lua
local hex = hash.hmac_sha512("message", "secret")
local raw = hash.hmac_sha512("message", "secret", true)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | Message to authenticate |
| `secret` | string | Secret key |
| `raw` | boolean? | Return raw bytes instead of hex |

**Returns:** `string, error`



#### FNV-1 32-bit


Compute a hash for uses such as hash tables and partitioning.

```lua
local n = hash.fnv32("data")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | Data to hash |

**Returns:** `number, error`



#### FNV-1 64-bit


Compute a wider hash for uses such as hash tables and partitioning, reducing collision probability.

```lua
local n = hash.fnv64("data")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | string | Data to hash |

**Returns:** `number, error`



#### PBKDF2


```lua
local key, err = hash.pbkdf2(password, salt, iterations, key_length)
local key, err = hash.pbkdf2(password, salt, iterations, key_length, "sha512")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `password` | string | Password/passphrase (non-empty) |
| `salt` | string | Salt value (non-empty) |
| `iterations` | integer | Iteration count (1 to 10,000,000) |
| `key_length` | integer | Desired key length in bytes |
| `hash` | string? | `sha256` or `sha512` (default: `sha256`) |

**Returns:** `string, error` (raw key bytes)



### Errors


| Condition | Kind | Retryable |
|-----------|------|-----------|
| Input not a string | `errors.INVALID` | no |
| Secret not a string (HMAC) | `errors.INVALID` | no |
| Empty password/salt, non-positive or excessive iterations, unsupported hash (PBKDF2) | `errors.INVALID` | no |

See [Error Handling](lua/core/errors.md) for working with errors.



---

# "UUID Generation"

## UUID Generation

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="workflow"/>

The `uuid` module generates, validates, inspects, parses, and formats UUIDs. In deterministic workflows, v1, v4, and v7 generation runs as a recorded side effect and returns the recorded value during replay. Namespace-based v3 and v5 generation is deterministic and runs directly.

This page is an API reference of isolated calls. Values such as `namespace`, `name`, `input`, and `id` come from the surrounding application. Capture and handle the second `error` return before consuming generated, parsed, inspected, or formatted results. UUIDs are identifiers, not bearer credentials; do not use any UUID version as an authentication token or secret.



### Loading


```lua
local uuid = require("uuid")
```



#### Version 1


Time-based UUID with timestamp and node ID.

Version 1 exposes its creation time and node identifier. Avoid it where those details are sensitive; prefer v4 when only an opaque identifier is needed.

```lua
local id, err = uuid.v1()
```

**Returns:** `string, error`



#### Version 4


Random UUID.

```lua
local id, err = uuid.v4()
```

**Returns:** `string, error`



#### Version 7


A time-ordered UUID that encodes its creation time for chronological indexing. Do not rely on it as a strictly monotonic sequence, especially for values generated within the same timestamp interval.

```lua
local id, err = uuid.v7()
```

**Returns:** `string, error`



#### Version 3


Deterministic UUID from namespace and name using MD5.

```lua
local id, err = uuid.v3(namespace, name)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `namespace` | string | Valid UUID string |
| `name` | string | Value to hash |

**Returns:** `string, error`



#### Version 5


Deterministic UUID from namespace and name using SHA-1.

```lua
local NS_URL = "6ba7b811-9dad-11d1-80b4-00c04fd430c8"
local id, err = uuid.v5(NS_URL, "https://example.com/resource")
if err then
    return nil, err
end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `namespace` | string | Valid UUID string |
| `name` | string | Value to hash |

**Returns:** `string, error`



#### `validate`


```lua
local valid = uuid.validate(input)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `input` | any | Value to check |

**Returns:** `boolean, nil`. Non-string and malformed inputs return `false`; validation does not raise a structured error.



#### `version`


```lua
local ver, err = uuid.version(id)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `uuid` | string | Valid UUID string |

**Returns:** `integer, error`



#### `variant`


```lua
local var, err = uuid.variant(id)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `uuid` | string | Valid UUID string |

**Returns:** `string, error` (RFC4122, Reserved, Microsoft, Future, NCS, or Invalid)



#### `parse`


```lua
local info, err = uuid.parse(id)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `uuid` | string | Valid UUID string |

**Returns:** `table, error`

Returned table fields:
- `version` (integer): UUID version (1, 3, 4, 5, or 7)
- `variant` (string): RFC4122, Reserved, Microsoft, Future, NCS, or Invalid
- `timestamp` (integer): Unix timestamp (v1 and v7 only)
- `node` (string): 6 raw node ID bytes (v1 only)



#### `format`


```lua
local formatted, err = uuid.format(id, "standard")
local formatted, err = uuid.format(id, "simple")
local formatted, err = uuid.format(id, "urn")
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `uuid` | string | Valid UUID string |
| `format` | string? | standard (default), simple, or urn |

**Returns:** `string, error`



### Errors


| Condition | Kind | Retryable |
|-----------|------|-----------|
| Invalid input type | `errors.INVALID` | no |
| Invalid UUID format | `errors.INVALID` | no |
| Unsupported format type | `errors.INVALID` | no |
| Generation failed | `errors.INTERNAL` | no |

See [Error Handling](lua/core/errors.md) for working with errors.



---

# "Dynamic Evaluation"

## Dynamic Evaluation


Execute code dynamically at runtime with sandboxed environments and controlled module access.



### Two Systems


Wippy provides two evaluation systems:

| System | Purpose | Use Case |
|--------|---------|----------|
| `expr` | Expression evaluation | Config, templates, simple calculations |
| `eval_runner` | Full Lua execution | Plugins, user scripts, dynamic code |



### expr Module


Lightweight expression evaluation using the expr-lang syntax.

```lua
local expr = require("expr")

local result, err = expr.eval("x + y * 2", {x = 10, y = 5})
-- result = 20
```



#### Compiling Expressions


Compile once, run many times:

```lua
local program, err = expr.compile("price * quantity")

local total1 = program:run({price = 10, quantity = 5})
local total2 = program:run({price = 20, quantity = 3})
```



#### Supported Syntax


```lua
-- Arithmetic
expr.eval("1 + 2 * 3")           -- 7
expr.eval("10 / 2 - 1")          -- 4
expr.eval("10 % 3")              -- 1

-- Comparison
expr.eval("x > 5", {x = 10})     -- true
expr.eval("x == y", {x = 1, y = 1}) -- true

-- Boolean
expr.eval("a && b", {a = true, b = false})  -- false
expr.eval("a || b", {a = true, b = false})  -- true
expr.eval("!a", {a = false})     -- true

-- Ternary
expr.eval("x > 0 ? 'positive' : 'negative'", {x = 5})

-- Functions
expr.eval("max(1, 5, 3)")        -- 5
expr.eval("min(1, 5, 3)")        -- 1
expr.eval("len([1, 2, 3])")      -- 3

-- Arrays
expr.eval("[1, 2, 3][0]")        -- 1

-- String concatenation
expr.eval("'hello' + ' ' + 'world'")
```



### eval_runner Module


Full Lua execution with security controls.

```lua
local runner = require("eval_runner")

local result, err = runner.run({
    source = [[
        local function double(x)
            return x * 2
        end
        return { double = double }
    ]],
    method = "double",
    args = {21}
})
-- result = 42
```



#### Configuration


| Parameter | Type | Description |
|-----------|------|-------------|
| `source` | string | Lua source code (required) |
| `method` | string | Function to call in returned table |
| `args` | any[] | Arguments passed to function |
| `modules` | string[] | Allowed builtin modules |
| `imports` | table | Registry entries to import |
| `context` | table | Values available as `ctx` |
| `allow_classes` | string[] | Additional module classes |
| `custom_modules` | table | Custom tables as modules |
| `limits` | table | Execution limits for this run |



#### Step Limit


`limits.max_steps` bounds how long one `runner.run` may execute:

```lua
local result, err = runner.run({
    source = user_source,
    method = "main",
    limits = {max_steps = 500}
})
```

A step is one turn of the eval scheduler: the program advances until it yields or finishes, and each resume consumes one step. Pure computation between yields counts as one step no matter how long it runs, so the limit bounds scheduling turns, not CPU time.

When the count exceeds the limit the run stops and returns `errors.INTERNAL` with `eval exceeded maximum step limit`.

`max_steps = 0` means unlimited. Omitting `limits` inherits the host default:

```yaml


## .wippy.yaml

lua:
  eval:
    max_steps: 10000  # default budget for runs without limits.max_steps
                      # 0 = unlimited; a negative value fails boot
```

`limits` applies to `runner.run` only; `runner.compile` accepts no limits. `limits` must be a table containing only `max_steps`, and `max_steps` must be a non-negative integer — anything else returns `errors.INVALID` before the program runs.



#### Module Access


Whitelist allowed modules:

```lua
runner.run({
    source = [[
        local json = require("json")
        return json.encode({hello = "world"})
    ]],
    modules = {"json"}
})
```

Modules not in the list cannot be required.



#### Registry Imports


Import entries from the registry:

```lua
runner.run({
    source = [[
        local data = ...
        local utils = require("utils")
        return utils.format(data)
    ]],
    imports = {
        utils = "app.lib:utilities"
    },
    args = {{key = "value"}}
})
```



#### Privileged Imports


An import can be granted modules the eval'd code itself cannot see. Use the table form with `id` and `modules`:

```lua
runner.run({
    source = [[
        local pricing = require("pricing")
        return pricing.quote(...)
    ]],
    modules = {"json"},
    imports = {
        pricing = { id = "app.lib:pricing", modules = {"funcs"} }
    },
})
```

The `pricing` library executes in its own scoped environment where `funcs` is available; the eval'd source cannot require or reach `funcs` directly. Granting a module to an import requires the caller to hold `eval.module` permission for that module — capabilities cannot be delegated beyond what the caller itself is allowed.



#### Custom Modules


Inject custom tables:

```lua
runner.run({
    source = [[
        return sdk.version
    ]],
    custom_modules = {
        sdk = {version = "1.0.0", api_key = "xxx"}
    }
})
```



#### Context Values


Pass data accessible as `ctx`:

```lua
runner.run({
    source = [[
        return "Hello, " .. ctx.get("user")
    ]],
    context = {user = "Alice"}
})
```



#### Compiling Programs


`runner.compile` validates source and reports its entrypoint and modules without running it:

```lua
local program, err = runner.compile([[
    local function process(x)
        return x * 2
    end
    return { process = process }
]], "process", {modules = {"json"}})

program:method()   -- "process"  (string)
program:modules()  -- {"json"}    (string[])
```

The options table accepts the same `modules` and `imports` fields as `runner.run`, and the same `eval.module` and `eval.import` permission checks apply. The compiled program is informational; execute by calling `runner.run` with the source and method.



#### Module Classes


Modules are categorized by capability:

| Class | Description | Default |
|-------|-------------|---------|
| `deterministic` | Pure functions | Allowed |
| `encoding` | Data encoding | Allowed |
| `time` | Time operations | Allowed |
| `nondeterministic` | Random, etc. | Allowed |
| `process` | Spawn, registry | Blocked |
| `storage` | File, database | Blocked |
| `network` | HTTP, sockets | Blocked |



#### Enabling Blocked Classes


```lua
runner.run({
    source = [[
        local http = require("http_client")
        return http.get("https://api.example.com")
    ]],
    modules = {"http_client"},
    allow_classes = {"network"}
})
```



#### Permission Checks


The system checks permissions for:

- `eval.compile` - Before compilation
- `eval.run` - Before execution
- `eval.module` - For each module in whitelist, and for each module granted to a privileged import
- `eval.import` - For each registry import
- `eval.class` - For each allowed class

Configure in security policies.



### Compile Cache


Compiled programs are cached in an LRU keyed by source, method, modules, and allowed classes — repeated runs of identical code skip recompilation. Imports and context are bound at run time and do not affect the cache key.

```yaml


## .wippy.yaml

lua:
  eval:
    cache_size: 256   # entries; 0 or less disables caching (default: 256)
    cache_ttl: 0      # expiry; 0 = no expiry (default: 0)
```



### Error Handling


```lua
local result, err = runner.run({...})
if err then
    if err:kind() == errors.PERMISSION_DENIED then
        -- Access denied by security policy
    elseif err:kind() == errors.INVALID then
        -- Invalid source or configuration
    elseif err:kind() == errors.INTERNAL then
        -- Execution or compilation error
    end
end
```



#### Plugin System


```lua
local plugins = registry.find({meta = {type = "plugin"}})

for _, plugin in ipairs(plugins) do
    local source = plugin:data().source
    runner.run({
        source = source,
        method = "init",
        modules = {"json", "time"},
        context = {config = app_config}
    })
end
```



#### Template Evaluation


```lua
local template = "Hello, {{name}}! You have {{count}} messages."
local compiled = expr.compile("name")

-- Fast repeated evaluation
for _, user in ipairs(users) do
    local greeting = compiled:run({name = user.name})
end
```



#### User Scripts


```lua
local user_code = request:body()

local result, err = runner.run({
    source = user_code,
    modules = {"json", "text"},  -- Safe modules only
    context = {data = input_data}
})
```



### See Also


- [Expression](lua/dynamic/expression.md) - Expression language reference
- [Exec](lua/dynamic/exec.md) - System command execution
- [Security](lua/security/security.md) - Security policies



---

# "Command Execution"

## Command Execution

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="io"/>
<secondary-label ref="permissions"/>

Execute external commands and shell scripts with full control over I/O streams.

For executor configuration, see [Executor](system/exec.md).



### Loading


```lua
local exec = require("exec")
```



### Acquiring an Executor


Get a process executor resource by ID:

```lua
local executor, err = exec.get("app:exec")
if err then
    return nil, err
end

-- Use executor
local proc = executor:exec("ls -la")
-- ...

-- Release when done
executor:release()
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | string | Resource ID |

**Returns:** `Executor, error`



### Creating a Process


Create a new process with the specified command:

```lua
-- Simple command
local proc, err = executor:exec("echo 'Hello, World!'")

-- With working directory
local proc = executor:exec("npm install", {
    work_dir = "/app/project"
})

-- With environment variables
local proc = executor:exec("python script.py", {
    work_dir = "/scripts",
    env = {
        PYTHONPATH = "/app/lib",
        DEBUG = "true",
        API_KEY = api_key
    }
})

-- Run shell script
local proc = executor:exec("./deploy.sh production", {
    work_dir = "/app/scripts",
    env = {
        DEPLOY_ENV = "production"
    }
})
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `cmd` | string | Executable and literal arguments |
| `options.work_dir` | string | Working directory |
| `options.env` | table | Environment variables |
| `options.pty` | table | Allocate a pseudo-terminal for the child |
| `options.process_group` | boolean | Start the child in its own process group so signals also reach descendants; unsupported on Windows |

**Returns:** `Process, error`

The process is created but not started.



#### Command Parsing


`cmd` is split into an executable and literal arguments using shell-like quoting: single and double quotes group a word, and a backslash escapes the following character. There is no shell, so no variable expansion, globbing, pipes, or redirection happens. An unclosed quote returns `errors.INVALID`.

```lua
-- One argument containing a space, passed literally
local proc = executor:exec("grep 'hello world' notes.txt")

-- $HOME is passed as the five characters $HOME, not expanded
local proc = executor:exec("echo $HOME")
```

To use shell features, invoke a shell explicitly:

```lua
local proc = executor:exec("/bin/sh -c 'ls *.log | wc -l'")
```



#### PTY Options


Allocating a PTY gives the child a real terminal: line editing, job control, and full-screen programs work as they do in a shell.

```lua
local proc = executor:exec("/bin/bash --noprofile --norc", {
    pty = {width = 100, height = 30, term = "xterm-256color"},
})
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `width` | number | 80 | Initial PTY columns, 1 to 65535 |
| `height` | number | 24 | Initial PTY rows, 1 to 65535 |
| `term` | string | none | Child `TERM` value |

Width times height may not exceed 262,144 cells. A PTY-backed process merges the child's output into a single terminal stream; drive it with [resize](#resize) and [attach_terminal](#attach_terminal) rather than the stdin/stdout pipe methods.



### start / wait


Start the process and wait for completion.

```lua
local proc = executor:exec("./build.sh")

local ok, err = proc:start()
if err then
    return nil, err
end

local exit_code, err = proc:wait()
if err then
    return nil, err
end

if exit_code ~= 0 then
    return nil, errors.new({ kind = errors.INTERNAL, message = "Build failed with exit code: " .. exit_code })
end
```



### stdout_stream / stderr_stream


Get streams to read process output.

```lua
local proc = executor:exec("./process-data.sh")

local stdout = proc:stdout_stream()
local stderr = proc:stderr_stream()

proc:start()

-- Read all stdout
local output = {}
while true do
    local chunk = stdout:read(4096)
    if not chunk then break end
    table.insert(output, chunk)
end
local result = table.concat(output)

-- Check for errors
local err_output = {}
while true do
    local chunk = stderr:read(4096)
    if not chunk then break end
    table.insert(err_output, chunk)
end

local exit_code = proc:wait()

stdout:close()
stderr:close()

if exit_code ~= 0 then
    return nil, errors.new({ kind = errors.INTERNAL, message = table.concat(err_output) })
end

return result
```



### write_stdin


Write data to process stdin.

```lua
local proc = executor:exec("head -n 3")
local stdout = proc:stdout_stream()

proc:start()

proc:write_stdin("banana\napple\ncherry\n")

local lines = stdout:read()

proc:wait()
stdout:close()
```

Each call writes the given bytes and returns. Call `close_stdin()` when the child
must see EOF:

```lua
local proc = assert(executor:exec("sort"))
local stdout = assert(proc:stdout_stream())
assert(proc:start())
assert(proc:write_stdin("banana\napple\n"))
assert(proc:close_stdin())
local sorted = assert(stdout:read())
```

`close_stdin()` is idempotent. Later writes fail because the input side is
closed. PTY-backed processes do not expose this pipe operation.



### done


Use `done()` to observe exit without consuming the process handle:

```lua
local proc = assert(executor:exec("./worker"))
assert(proc:start())
local exits = assert(proc:done())

local status, open = exits:receive()
if open then
    print(status.code, status.signal, status.error)
end
```

The returned channel delivers one exit record and then closes. Repeated calls
return the same channel. The record contains `code`, optional `signal`, and an
`error` only when the runtime could not observe the exit. A signal exit uses
`128 + signal` as its code. Unlike `wait()`, `done()` leaves the handle usable,
so streams, `signal()`, and `close()` remain available. `wait()` after delivery
returns the recorded code.



### signal / close


Send signals or release the process.

```lua
local proc = executor:exec("./long-running-server.sh")
proc:start()

-- ... later, need to stop it ...

-- Send SIGTERM and release the handle
proc:close()

-- Send SIGKILL and release the handle
proc:close(true)

-- Or send a specific signal and keep the handle
local SIGINT = 2
proc:signal(SIGINT)
```

`close(force?)` signals a started child with `SIGTERM`, or `SIGKILL` when `force` is true, then reaps it in the background so the call does not block. A child still running after a grace period is killed so the reap always completes. An unstarted handle is simply invalidated, and closing twice is not an error. When `process_group` is enabled, signals target the group and still reach descendants after the leader exits.

Streams acquired before reaping remain readable until their last writer closes,
including a descendant that inherited the pipe. After `close()`, process methods
report `process closed`; use `done()` when the exit matters and the handle must
remain usable.



### resize


Resize the PTY of a PTY-backed process. A pipe-backed process returns an error.

```lua
local ok, err = proc:resize(120, 40)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `width` | number | Columns, 1 to 65535 |
| `height` | number | Rows, 1 to 65535 |

**Returns:** `boolean, error`

Use it to set the initial geometry before handing the process to a terminal session. Once a session owns the process, send it a `resize` event instead.



### attach_terminal


Attach an unstarted PTY-backed process to the calling process's terminal and return a `TerminalSession`.

```lua
local exec = require("exec")
local tty = require("tty")

local executor = assert(exec.get("app:exec"))
local proc = assert(executor:exec("/bin/bash --noprofile --norc", {
    pty = {term = "xterm-256color"},
}))
local session = assert(proc:attach_terminal())
```

**Returns:** `TerminalSession, error`

The call consumes the process: the session becomes its sole lifecycle owner and the original handle can no longer be used. The session opens a surface on the current terminal port and owns PTY emulation, input encoding, resize, graceful and forced termination, and reaping. It needs a terminal port — a [terminal host](system/terminal.md) process, or a process spawned with a [viewport grant](lua/system/tty.md#viewport) — and fails when the port has no input controller or already has an open surface.



#### TerminalSession


| Method | Returns | Description |
|--------|---------|-------------|
| `send(event)` | `boolean, error` | Forward one canonical TTY event to the child |
| `done()` | channel | Channel that fires once when the child finishes |
| `status()` | `string, error` | `"running"` or `"done"`, with the failure error when it failed |
| `close()` | `boolean, error` | Request termination of a running child |

`send` accepts the key, mouse, resize, focus, and paste records described in [TTY](lua/system/tty.md#event-types). Sending after the child has finished returns an error.

```lua
local channel = require("channel")

local events = assert(tty.events())
assert(tty.start())
local done = session:done()

while true do
    local selected = channel.select({
        events:case_receive(),
        done:case_receive(),
    })
    if not selected.ok or selected.channel == done then break end
    if selected.value.type == "close" then break end
    assert(session:send(selected.value))
end

assert(session:close())
```



### Permissions


Exec operations are subject to security policy evaluation.

| Action | Resource | Description |
|--------|----------|-------------|
| `exec.get` | Executor ID | Acquire an executor resource |
| `exec.run` | Command | Execute a specific command |

`exec.run` is evaluated against the raw command string, with the requested options as metadata:

| Key | Type | Description |
|-----|------|-------------|
| `work_dir` | string | Requested working directory, empty when unset |
| `env_names` | string[] | Names of the environment variables passed, sorted; values are not exposed |
| `pty.requested` | boolean | Whether a PTY was requested |
| `pty.width` | number | Resolved PTY columns, present when requested |
| `pty.height` | number | Resolved PTY rows, present when requested |
| `pty.term` | string | Requested `TERM` value, present when requested |

A policy can therefore allow plain commands while restricting the ones that ask for a terminal or a particular working directory.



### Errors


| Condition | Kind | Retryable |
|-----------|------|-----------|
| Invalid ID | `errors.INVALID` | no |
| Permission denied | `errors.INVALID` | no |
| Process closed | `errors.INVALID` | no |
| Process not started | `errors.INVALID` | no |
| Already started | `errors.INVALID` | no |
| Unclosed quote in command | `errors.INVALID` | no |
| No PTY on the process | `errors.INVALID` | no |
| Terminal port unavailable | `errors.UNAVAILABLE` | no |

See [Error Handling](lua/core/errors.md) for working with errors.



### See Also


- [Executor](system/exec.md) — executor configuration
- [TTY](lua/system/tty.md) — terminal events, surfaces, and viewports
- [Terminal UI](tutorials/tty.md) — a shell that hosts a PTY child in a viewport



---

# "Expression Language"

## Expression Language

<secondary-label ref="function"/>
<secondary-label ref="process"/>
<secondary-label ref="workflow"/>

The `expr` module compiles and evaluates [expr-lang](https://expr-lang.org/) expressions for filtering, validation, calculations, and rule evaluation without running Lua source code. This page is the canonical Lua API reference; its examples run inside an existing Wippy Lua process whose entry declares the `expr` module, but they are not standalone Wippy applications. See [Dynamic Evaluation](./eval.md) when choosing between expressions and capability-restricted Lua.



### Loading


```lua
local expr = require("expr")
```



### Caching


`expr.eval` keeps an internal LRU cache of compiled expressions (default capacity 1000). The cache is built into the module and requires no configuration.



### Evaluating Expressions


Evaluate an expression string and return its result. The function uses the internal cache of compiled expressions:

```lua
-- Simple math
local result, err = expr.eval("1 + 2 * 3")
if err then
    return nil, err
end
-- result == 7

-- With variables
local total, total_err = expr.eval("price * quantity", {
    price = 29.99,
    quantity = 3
})
if total_err then
    return nil, total_err
end
-- total == 89.97

-- Ternary operator
local label, label_err = expr.eval('score > 90 ? "A" : score > 80 ? "B" : "C"', {
    score = 85
})
if label_err then
    return nil, label_err
end
-- label == "B"
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `expression` | string | expr-lang syntax expression |
| `env` | `any` | Variable environment for the expression (optional; normally a table) |

**Returns:** `any, error`



### Compiling Expressions


Compile an expression into a reusable `Program` for repeated evaluation:

```lua
-- Compile once for repeated use
local discount_calc, err = expr.compile("price * (1 - discount_rate)")
if err then
    return nil, err
end

-- Reuse with different inputs
local price1, run_err = discount_calc:run({price = 100, discount_rate = 0.1})
if run_err then
    return nil, run_err
end

local price2, second_run_err = discount_calc:run({price = 50, discount_rate = 0.2})
if second_run_err then
    return nil, second_run_err
end
-- price1 == 90 and price2 == 40
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `expression` | string | expr-lang syntax expression |
| `env` | `any` | Type-hint environment for compilation (optional; normally a table) |

**Returns:** `Program, error`



### Running Compiled Programs


Run a compiled expression with the provided environment:

```lua
-- Validation rule
local validator, compile_err = expr.compile("len(password) >= 8 and len(password) <= 128")
if compile_err then
    return nil, compile_err
end

local valid, run_err = validator:run({password = "securepass123"})
if run_err then
    return nil, run_err
end
-- valid == true

-- Pricing rule
local pricer, pricing_compile_err = expr.compile([[
    base_price * quantity * (1 - bulk_discount) + shipping
]])
if pricing_compile_err then
    return nil, pricing_compile_err
end

local order_total, pricing_run_err = pricer:run({
    base_price = 25.00,
    quantity = 10,
    bulk_discount = 0.15,
    shipping = 12.50
})
if pricing_run_err then
    return nil, pricing_run_err
end
-- order_total == 225.00
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `env` | `any` | Variable environment for the expression (optional; normally a table) |

**Returns:** `any, error`



### Built-in Functions


Expr-lang includes built-in functions for common operations:

```lua
local maximum, max_err = expr.eval("max(1, 5, 3)")
if max_err then
    return nil, max_err
end

local uppercase, upper_err = expr.eval('upper("hello")')
if upper_err then
    return nil, upper_err
end

local total, sum_err = expr.eval("sum(values)", {values = {1, 2, 3, 4}})
if sum_err then
    return nil, sum_err
end
-- maximum == 5, uppercase == "HELLO", and total == 10
```

Other built-ins include `min`, `abs`, `ceil`, `floor`, `len`, `lower`, and
`trim`. Expr-lang also provides operators such as `contains` for strings and
`in` for membership tests.



### Errors


| Condition | Kind | Retryable |
|-----------|------|-----------|
| Expression is empty | `errors.INVALID` | no |
| Expression syntax invalid | `errors.INTERNAL` | no |
| Expression evaluation fails | `errors.INTERNAL` | no |
| Result conversion fails | `errors.INTERNAL` | no |

See [Error Handling](lua/core/errors.md) for working with errors.



---

# "WebAssembly Runtime"

## WebAssembly Runtime


> The WASM runtime is an experimental extension. Configuration is stable, but runtime internals may change between releases.

Wippy registers WebAssembly modules alongside Lua code. Function entries join
the function registry and run through function pools. Process entries register
factories for persistent WASM actors: each PID owns one isolated module
instance and bounded mailbox until it exits. Both use the runtime scheduler and
security model.

**Classification: conceptual overview.** The Lua block contains independent call
patterns and assumes the named WASM entries and their WIT contracts are already
registered. See the Rust/WASM tutorial for a project with a compiled component.



### Entry Kinds


| Kind | Description |
|------|-------------|
| `function.wat` | Inline WebAssembly Text format function defined in YAML |
| `function.wasm` | Precompiled WASM binary loaded from a filesystem entry |
| `process.wasm` | Stateful WASM actor with one module instance per PID |



### How It Works


1. WASM modules are declared as registry entries in `_index.yaml`
2. At boot, `function.wat` and `function.wasm` entries are compiled, registered as functions, and placed into their configured function pools
3. Lua calls those function entries through `funcs.call()`
4. `process.wasm` entries register actor factories and are spawned under a process host; each PID keeps its module state across messages
5. Function arguments and return values are mapped between Lua tables and WIT types
6. Supported dispatcher-bridged operations, including clock polling and outgoing HTTP, yield so the scheduler can run other work



### Component Model


Wippy supports the WebAssembly Component Model with WIT (WebAssembly Interface Types). Component modules map these types between the host and guest:

- Records map to Lua tables with named fields
- Lists map to Lua arrays
- Results map to `(value, error)` return tuples
- Primitives (`s32`, `f64`, `string`, etc.) map directly

Raw/core WASM modules are also supported with explicit WIT signatures.



### Calling WASM from Lua


Call a WASM function by its registry ID through `funcs.call()`:

```lua
local funcs = require("funcs")

-- No arguments
local result, err = funcs.call("myns:answer_wat")
if err then return nil, err end

-- With arguments
local computed, compute_err = funcs.call("myns:compute", 6, 7)
if compute_err then return nil, compute_err end

-- With complex data
local users = {
    {id = 1, name = "Alice", tags = {"admin"}, active = true},
    {id = 2, name = "Bob", tags = {"user"}, active = false},
}
local transformed, err = funcs.call("myns:transform_users", users)
if err then return nil, err end
```



### Security


WASM executions inherit the caller's security context by default:

- Actor identity is inherited
- Scope is inherited
- Request context is inherited

Host capabilities are opt-in through explicit imports. Each entry declares the host profiles it needs, such as `funcs`, `wippy:actor`, `wasi1`, `wasi:cli`, or `wasi:filesystem`, limiting the module's access surface. Enabling a profile does not bypass runtime security checks on operations such as process messaging, function calls, sockets, or outgoing HTTP.

A guest that imports `funcs` can call back into the registry. Each call is policy-checked as `funcs.call` against the target ID, so the reachable set is exactly what the inherited scope already permits. Socket dials are authorized the same way, by the [network service](system/network.md), against the `socket.*` permissions.



### See Also


- [Functions](wasm/functions.md) - WASM function entry configuration
- [Host Functions](wasm/hosts.md) - Available WASI and Wippy host interfaces
- [Processes](wasm/processes.md) - Running WASM as long-lived processes
- [Rust/WASM Tutorial](../tutorials/rust-wasm.md) - Build and register a component



---

# "WASM Functions"

## WASM Functions


Use `function.wat` for inline WebAssembly Text source and `function.wasm` for precompiled binaries.

**Classification: function configuration reference.** WAT blocks are small
registry examples. Precompiled examples assume an external component build, a
filesystem entry, exported methods matching the guest WIT, and a SHA-256 digest
calculated from the exact binary. Real-looking sample hashes are illustrative.



### Inline WAT Functions


Define a WAT function directly in `_index.yaml`:

```yaml
entries:
  - name: answer
    kind: function.wat
    source: |
      (module
        (func (export "answer") (result i32)
          i32.const 42
        )
      )
    wit: |
      answer: func() -> s32;
    method: answer
    pool:
      type: inline
```

For larger WAT sources, use a file reference:

```yaml
  - name: answer
    kind: function.wat
    source: file://answer.wat
    wit: |
      answer: func() -> s32;
    method: answer
    pool:
      type: inline
```



#### WAT Configuration Fields


| Field | Required | Description |
|-------|----------|-------------|
| `source` | Yes | Inline WAT source or `file://` reference |
| `method` | Yes | Exported function name to call |
| `wit` | No | WIT signature for raw/core modules |
| `pool` | No | Worker pool configuration |
| `transport` | No | Input/output mapping (default: `payload`) |
| `imports` | No | Host imports to enable (e.g., `wasi:cli`, `wasi:io`) |
| `wasi` | No | WASI configuration (args, env, mounts) |
| `options.limits` | No | Execution limits (`limits` remains a deprecated compatibility spelling) |



### Precompiled WASM Functions


Load compiled `.wasm` binaries from a filesystem entry:

```yaml
entries:
  - name: assets
    kind: fs.directory
    directory: ./wasm

  - name: compute
    kind: function.wasm
    fs: myns:assets
    path: /compute.wasm
    hash: sha256:292b796376f8b4cc360acf2ea6b82d1084871c3607a079f30b446da8e5c984a4
    method: compute
    pool:
      type: lazy
      max_size: 4
```



#### WASM Configuration Fields


| Field | Required | Description |
|-------|----------|-------------|
| `fs` | Yes | Filesystem entry ID containing the binary |
| `path` | Yes | Path to `.wasm` file within the filesystem |
| `hash` | Yes | SHA-256 hash for integrity verification (`sha256:...`) |
| `method` | Yes | Exported function name to call |
| `wit` | No | WIT signature for raw/core modules |
| `pool` | No | Worker pool configuration |
| `transport` | No | Input/output mapping (default: `payload`) |
| `imports` | No | Host imports to enable |
| `wasi` | No | WASI configuration |
| `options.limits` | No | Execution limits (`limits` remains a deprecated compatibility spelling) |



### Worker Pools


Each WASM function uses a pool of pre-compiled instances. The pool type controls concurrency and resource usage.

| Type | Description |
|------|-------------|
| `inline` | Mutex-serialized. Synchronous and asyncified calls reuse one warm instance; retained-memory policy or an execution failure can trigger replacement. |
| `lazy` | Zero idle workers. Scales on demand up to `max_size`. |
| `static` | Fixed number of workers with request queue. |
| `adaptive` | Auto-scaling elastic pool. |



#### Pool Configuration


```yaml
pool:
  type: static
  size: 4            # Total pool size
  workers: 2         # Worker threads
  buffer: 16         # Request queue buffer (default: workers * 64)
```

```yaml
pool:
  type: lazy
  max_size: 8        # Maximum concurrent instances
```

```yaml
pool:
  type: adaptive
  max_size: 16       # Upper scaling bound
```

The 100-worker default applies only to the implicitly selected pool (when no `type` is set). When you explicitly set `type: lazy` or `type: adaptive` without `max_size`, the default maximum is 16 workers.



#### Worker Classes and Core Affinity


Setting `pool.worker_class` routes the function to a dedicated pool of OS-thread-pinned workers instead of the shared pool types above (`type` is ignored when set; conventional name: `wasm`):

```yaml
pool:
  worker_class: wasm
  workers: 8         # optional; defaults to reserved cores, else min(NumCPU, 4)
```

Core isolation is opted into per runtime in `.wippy.yaml`:

```yaml
scheduler:
  wasm_isolation:
    enabled: true      # default: false
    reserved_cores: 2  # cores reserved for WASM pools (default: 1)
```

With isolation enabled, the actor scheduler and the pinned WASM pools run on disjoint CPU sets (`sched_setaffinity`, Linux only — other platforms size the pools but do not bind threads). Long-running WASM calls then cannot starve actor scheduling.



### Transports


Transports control how input and output are mapped between the runtime and the WASM module.

| Transport | Description |
|-----------|-------------|
| `payload` | Maps runtime payloads directly to WASM call arguments (default) |
| `wasi-http` | Maps HTTP request/response context to WASM arguments and results |



#### Payload Transport


The default transport passes arguments directly. Lua values are transcoded to Go types, then lowered to WIT types:

```yaml
  - name: compute
    kind: function.wasm
    fs: myns:assets
    path: /compute.wasm
    hash: sha256:...
    method: compute
    pool:
      type: inline
```

```lua
-- Arguments passed directly as WASM function parameters
local result, err = funcs.call("myns:compute", 6, 7)
if err then return nil, err end
-- result: 42
```



#### WASI HTTP Transport


The `wasi-http` transport maps HTTP requests to WASM and writes results back to the HTTP response. Use this to expose WASM functions as HTTP endpoints:

```yaml
  - name: greet_wasm
    kind: function.wasm
    fs: myns:assets
    path: /greet.wasm
    hash: sha256:...
    method: greet
    transport: wasi-http
    pool:
      type: inline

  - name: greet_endpoint
    kind: http.endpoint
    meta:
      router: myns:api
    method: POST
    path: /api/greet
    func: greet_wasm
```



### Execution Limits


The `options.limits` block bounds a function's execution time, its warm-worker memory, and the sockets it may open:

```yaml
options:
  limits:
    max_execution_ms: 5000
    max_retained_memory_bytes: 134217728
    retained_memory_check_interval: 32
    max_open_sockets: 8
    socket_timeout_ms: 5000
```

| Field | Default | Description |
|-------|---------|-------------|
| `max_execution_ms` | unlimited | Wall-clock budget for one call. When exceeded, the execution is cancelled and an error is returned. |
| `max_retained_memory_bytes` | `67108864` (64 MiB) | Post-call recycling trigger. A warm worker whose linear memory exceeds this is retired after the call instead of being reused. An explicit `0` disables retained-memory recycling. |
| `retained_memory_check_interval` | `16` with the built-in limit, every call with an explicit limit | Number of calls between post-call memory inspections. |
| `max_open_sockets` | `16` | Concurrently open connections per instance for the `socket` host. |
| `socket_timeout_ms` | `30000` | Deadline for a `socket` dial and for each send/receive. |

Negative values are rejected at boot.

The root `limits` and `meta.options.limits` spellings are accepted temporarily
with a deprecation warning. Keep `pool` at the entry root; it has not moved
under `options`.



### WASI Configuration


Configure WASI capabilities for the guest module:

```yaml
wasi:
  args: ["--verbose"]
  cwd: "/app"
  env:
    - id: myns:api_key
      name: API_KEY
      required: true
    - id: myns:debug_mode
      name: DEBUG
  mounts:
    - fs: myns:data_files
      guest: /data
      read_only: true
    - fs: myns:output
      guest: /output
```

| Field | Description |
|-------|-------------|
| `args` | Command-line arguments passed to the guest |
| `cwd` | Working directory inside the guest (must be absolute) |
| `env` | Environment variables mapped from registry env entries |
| `mounts` | Filesystem mounts from registry filesystem entries |

Environment variables are resolved from the environment registry at call time. Required variables cause an error if not found.

Mount paths must be absolute and unique. Each mount maps a runtime filesystem entry to a guest directory path.



#### Data Transformation Pipeline


```yaml
entries:
  - name: wasm_binaries
    kind: fs.directory
    directory: ./wasm

  - name: transform_users
    kind: function.wasm
    fs: myns:wasm_binaries
    path: /mapper.wasm
    hash: sha256:7304fc7d19778605458ae5804dae9a7343dcd3f5fc22bcc9415e98b5047192dd
    method: transform-users
    pool:
      type: lazy
      max_size: 4

  - name: filter_active
    kind: function.wasm
    fs: myns:wasm_binaries
    path: /mapper.wasm
    hash: sha256:7304fc7d19778605458ae5804dae9a7343dcd3f5fc22bcc9415e98b5047192dd
    method: filter-active
    pool:
      type: lazy
      max_size: 4
```

```lua
local funcs = require("funcs")

local users = {
    {id = 1, name = "Alice", tags = {"admin", "dev"}, active = true},
    {id = 2, name = "Bob", tags = {"user"}, active = false},
    {id = 3, name = "Carol", tags = {"dev"}, active = true},
}

-- Transform: adds display field and tag count
local transformed, err = funcs.call("myns:transform_users", users)
if err then return nil, err end

-- Filter: returns only active users
local active, filter_err = funcs.call("myns:filter_active", users)
if filter_err then return nil, filter_err end
```



#### Async Sleep with WASI Clocks


WASM components that import `wasi:clocks`, `wasi:io` and `wasi:poll` can use clocks and polling. The async yield mechanism integrates with the Wippy dispatcher:

```yaml
  - name: sleep_ms
    kind: function.wasm
    fs: myns:wasm_binaries
    path: /sleep_test.wasm
    hash: sha256:...
    method: "test-sleep#sleep-ms"
    imports:
      - wasi:io
      - wasi:poll
      - wasi:clocks
    pool:
      type: inline
```

The `#` separator in the method field references an interface method: `test-sleep#sleep-ms` calls the `sleep-ms` function from the `test-sleep` interface.



### See Also


- [Overview](wasm/overview.md) - WebAssembly runtime overview
- [Host Functions](wasm/hosts.md) - Available host interfaces
- [Processes](wasm/processes.md) - Running WASM as processes
- [Entry Kinds](guides/entry-kinds.md) - All registry entry kinds



---

# "Host Functions"

## Host Functions


WASM modules access runtime capabilities through host function imports. Each import is declared explicitly per entry in the `imports` list.



### Import Types


| Import | Namespace | Module kind | Description |
|--------|-----------|-------------|-------------|
| `wasi:cli` | `wasi:cli/*` | component | Environment, exit, stdin/stdout/stderr, terminal |
| `wasi:io` | `wasi:io/error`, `wasi:io/streams` | component | Streams and error handling |
| `wasi:poll` | `wasi:io/poll` | component | Async polling / cooperative yielding |
| `wasi:clocks` | `wasi:clocks/*` | component | Wall clock and monotonic clock |
| `wasi:filesystem` | `wasi:filesystem/*` | component | File system access through mounted directories |
| `wasi:random` | `wasi:random/*` | component | Cryptographically secure and insecure random numbers |
| `wasi:sockets` | `wasi:sockets/*` | component | TCP/UDP networking and DNS resolution |
| `wasi:http` | `wasi:http/*` | component | Outgoing HTTP client requests |
| `funcs` | `wippy:runtime/funcs@0.1.0` | component | Calling registry functions from the guest |
| `wippy:actor` | `wippy:actor/process@0.1.0` | component | PID identity and bounded actor mailbox messaging |
| `wasi1` | `wasi_snapshot_preview1` | core | WASI Preview 1 compatibility imports |
| `socket` | `wippy:runtime/socket@0.1.0` | core | Instance-owned outbound TCP through integer-only imports |

The eight `wasi:*` profiles, `funcs`, and `wippy:actor` are component-only:
declaring one on a core module fails the entry. `wasi1` and `socket` expose core
imports.

Each profile resolves under its short name, under any of the interface namespaces it provides, and under a versioned namespace. The version suffix is stripped before lookup, so `wasi:io/poll`, `wasi:io/poll@0.2.3` and `wasi:poll` all select the same profile.

An import that resolves to no profile fails the entry with `unsupported wasm host import: <id>`; a component-only profile on a core module fails with `wasm host import requires component module: <id>`.

Enable imports in your entry configuration:

```yaml
  - name: my_function
    kind: function.wasm
    fs: myns:assets
    path: /module.wasm
    hash: sha256:...
    method: run
    imports:
      - wasi:cli
      - wasi:io
      - wasi:clocks
      - wasi:filesystem
    pool:
      type: inline
```

Only declare the imports your module actually needs.



### WASI Imports


Each `wasi:*` import enables a group of related WASI Preview 2 interfaces.



#### wasi:clocks


**Interfaces:** `wasi:clocks/wall-clock`, `wasi:clocks/monotonic-clock`

Wall clock and monotonic clock for time operations. Monotonic clock integrates with the Wippy dispatcher for async sleep.



#### wasi:io


**Interfaces:** `wasi:io/error`, `wasi:io/streams`

Stream read/write operations and error handling. The `wasi:io/poll` interface is provided separately by the `wasi:poll` import.



#### wasi:poll


**Interfaces:** `wasi:io/poll`

Async polling. The poll interface enables cooperative yielding through the dispatcher.



#### wasi:cli


**Interfaces:** `wasi:cli/environment`, `wasi:cli/exit`, `wasi:cli/stdin`, `wasi:cli/stdout`, `wasi:cli/stderr`, `wasi:cli/terminal-stdin`, `wasi:cli/terminal-stdout`, `wasi:cli/terminal-stderr`

Access to environment variables, process exit codes, and standard I/O streams. Environment variables are mapped from the Wippy environment registry through WASI configuration.



#### wasi:filesystem


**Interfaces:** `wasi:filesystem/types`, `wasi:filesystem/preopens`

File system access through mounted directories. Mounts are configured per-entry and map Wippy filesystem entries to guest paths.

```yaml
wasi:
  mounts:
    - fs: myns:data
      guest: /data
      read_only: true
```



#### wasi:random


**Interfaces:** `wasi:random/random`, `wasi:random/insecure`, `wasi:random/insecure-seed`

Cryptographically secure and insecure random number generation.



#### wasi:sockets


**Interfaces:** `wasi:sockets/instance-network`, `wasi:sockets/ip-name-lookup`, `wasi:sockets/tcp`, `wasi:sockets/tcp-create-socket`, `wasi:sockets/udp`, `wasi:sockets/udp-create-socket`

TCP and UDP networking with DNS resolution. Socket operations suspend the guest and run through the dispatcher, which performs every dial, bind and lookup on the [network service](system/network.md).



#### wasi:http


**Interfaces:** `wasi:http/types`, `wasi:http/outgoing-handler`

Outgoing HTTP client requests from within WASM modules. Supports request/response types defined by the WASI HTTP specification.



### funcs


**Namespace:** `wippy:runtime/funcs@0.1.0`

Calls registry functions from a component guest. Two entry points are exposed:

```wit
interface funcs {
  call-string: func(target: string, input: string) -> result<string, string>;
  call-bytes: func(target: string, input: list<u8>) -> result<list<u8>, string>;
}
```

`target` is a registry ID in `namespace:name` form. Every call is policy-checked as `funcs.call` against that target, so a guest can only reach functions the caller's scope already permits.



### wippy:actor


**Namespace:** `wippy:actor/process@0.1.0`

Provides messaging for a component running as `process.wasm`:

```wit
interface process {
  use wasi:io/poll@0.2.8.{pollable};

  type pid = string;
  record payload { format: string, data: list<u8> }
  record message { %from: pid, topic: string, payloads: list<payload> }

  self: func() -> pid;
  send: func(target: pid, topic: string, payloads: list<payload>)
    -> result<bool, string>;
  try-receive: func() -> result<option<message>, string>;
  receive: func() -> result<message, string>;
  subscribe: func() -> pollable;
}
```

`receive` suspends the actor until its mailbox has a message; `try-receive`
never waits. `subscribe` lets a guest wait on mailbox readiness together with
other pollables. `send` accepts `bytes`, `text`, and `json` payload formats and
is policy-checked as `process.send` against the target PID. The profile requires
an actor context and is intended for `process.wasm` entries.



### wasi1


**Namespace:** `wasi_snapshot_preview1`

Declares that a core module links against WASI Preview 1. The profile also resolves under `preview1` and `wasi-preview1`. It registers no hosts of its own; Preview 1 imports are satisfied by the underlying WASM runtime.



### socket


**Namespace:** `wippy:runtime/socket@0.1.0`

Outbound TCP for core (non-component) modules. The host exports four integer-only functions, so a guest needs no component tooling to use it:

| Function | Signature | Result |
|----------|-----------|--------|
| `connect` | `(host_ptr: i32, host_len: i32, port: i32, timeout_ms: i32) -> i64` | `status << 32 \| handle` |
| `send` | `(handle: i32, buf_ptr: i32, buf_len: i32) -> i64` | `status << 32 \| written` |
| `recv` | `(handle: i32, out_ptr: i32, out_cap: i32) -> i64` | `status << 32 \| read` |
| `close` | `(handle: i32) -> i32` | `status` |

The high 32 bits of the 64-bit result carry the status; the low 32 bits carry the value.

| Status | Value | Meaning |
|--------|-------|---------|
| `OK` | 0 | Operation succeeded |
| `Invalid` | 1 | Bad arguments or an out-of-range memory region |
| `Denied` | 2 | The network service denied the dial |
| `Failed` | 3 | The operation failed |
| `UnknownHandle` | 4 | The handle is not an open connection of this instance |
| `Limit` | 5 | `max_open_sockets` reached |
| `Timeout` | 6 | The dial or the read/write deadline expired |

`connect` reads the host name from guest memory; `host_len` must be between 1 and 253 bytes and `port` between 1 and 65535. `timeout_ms` narrows the dial deadline: the effective deadline is the smaller of `timeout_ms` and the entry's `socket_timeout_ms`. `send` and `recv` are bounded by `socket_timeout_ms`. `recv` reports a clean end of stream as `OK` with a read count of 0.

Connections are owned by the instance that opened them. A handle is meaningless to another instance, the open-socket count is counted per instance, and every connection is closed when the instance is closed or the warm worker is recycled.



### Network Authorization


Neither socket host decides access itself. Every dial, bind and lookup goes through the runtime network service, which checks the `socket.connect`, `socket.listen` and `socket.resolve` permissions, applies the private-IP policy, and routes through an [overlay network](system/network.md) when one is selected. `wasi:sockets` additionally pre-checks `socket.resolve` before a DNS lookup and `socket.listen` before a UDP bind.



### See Also


- [Overview](wasm/overview.md) - WebAssembly runtime overview
- [Functions](wasm/functions.md) - WASM function configuration
- [Processes](wasm/processes.md) - Running WASM as processes
- [Network Overlays](system/network.md) - Overlay selection and socket permissions



---

# "WASM Processes"

## WASM Processes


A `process.wasm` entry creates a persistent, isolated WASM actor under a Wippy
process host. One module instance lives for the PID lifetime, keeps its guest
state between messages, and participates in spawning, monitoring, messaging,
and supervised shutdown.

**Classification: process configuration and lifecycle reference.** Binary-backed
blocks assume an external component build and application-owned filesystem,
process host, environment, and policy entries. Placeholder hashes must be
replaced with the exact binary digest.



### Entry Configuration


```yaml
entries:
  - name: wasm_binaries
    kind: fs.directory
    directory: ./wasm

  - name: compute_worker
    kind: process.wasm
    fs: myns:wasm_binaries
    path: /worker.wasm
    hash: sha256:292b796376f8b4cc360acf2ea6b82d1084871c3607a079f30b446da8e5c984a4
    method: run
    imports:
      - wippy:actor
      - wasi:io
      - wasi:poll
    options:
      limits:
        memory_bytes: 67108864
      mailbox:
        capacity: 128
        bytes: 8388608
        message_bytes: 1048576
```



#### Configuration Fields


| Field | Required | Description |
|-------|----------|-------------|
| `fs` | Yes | Filesystem entry ID containing the binary |
| `path` | Yes | Path to `.wasm` file within the filesystem |
| `hash` | Yes | SHA-256 hash for integrity verification |
| `method` | Yes | Exported function name to execute |
| `transport` | No | Invocation transport: `payload` (default) or `wasi-http` |
| `wit` | No | WIT signature for raw/core modules |
| `imports` | No | Host imports to enable |
| `wasi` | No | WASI configuration (`args`, `cwd`, `env`, and `mounts`) |
| `options` | No | Actor controls: `worker_class`, `limits`, and `mailbox` |

<note>
`process.wasm` actors own one instance for their whole PID lifetime, so function
pooling does not apply. A root `pool` block is rejected. Put actor limits under
`options.limits`; the old root `limits` and `meta.options` spellings are accepted
temporarily with a deprecation warning.
</note>



### Stateful Actors and Messaging


Import `wippy:actor` in a component guest to access the current PID and its
bounded mailbox. The `wippy:actor/process@0.1.0` interface provides:

| Function | Behavior |
|----------|----------|
| `self()` | Return the current actor PID as a string |
| `send(target, topic, payloads)` | Send a policy-checked message to another PID |
| `try-receive()` | Return the next message immediately, or `none` |
| `receive()` | Suspend until a message is available |
| `subscribe()` | Return a `wasi:io/poll` pollable for mailbox readiness |

Messages contain the sender PID, a topic, and up to 16 payloads. Payload formats
are `bytes`, UTF-8 `text`, and UTF-8 `json`. Sending is authorized as
`process.send` against the target PID. Mailbox admission rejects malformed,
oversized, and over-capacity messages before the guest receives them.

The guest normally exports a long-running `run` function. For example:

```wit
package example:worker;

world worker {
  import wippy:actor/process@0.1.0;
  import wasi:io/poll@0.2.8;
  export run: func() -> result<_, string>;
}
```

Inside `run`, call `receive()` in a loop, update guest state, and use `send()`
to reply to `message.from`. Returning from `run` exits the process.



### Actor Controls


Configure persistent resource and mailbox budgets under `options`:

```yaml
options:
  worker_class: wasm
  limits:
    memory_bytes: 67108864
    host_buffer_bytes: 8388608
    asyncify_stack_bytes: 65536
    max_execution_ms: 0
    max_open_sockets: 16
    socket_timeout_ms: 30000
  mailbox:
    capacity: 128
    bytes: 8388608
    message_bytes: 1048576
```

| Field | Default | Description |
|-------|---------|-------------|
| `worker_class` | `wasm` | Dedicated scheduler worker class; `wasm` is currently the only supported value |
| `limits.memory_bytes` | 64 MiB | Guest linear-memory ceiling; a positive 64 KiB multiple, at most 4 GiB |
| `limits.host_buffer_bytes` | unlimited | Accounted resident host-buffer ceiling; `0` disables this byte ceiling |
| `limits.asyncify_stack_bytes` | runtime default (64 KiB) | Owned suspension storage for a core module |
| `limits.max_execution_ms` | unlimited | Wall-clock lifetime for the actor; `0` means no deadline |
| `limits.max_open_sockets` | 16 | Concurrent open sockets owned by the actor |
| `limits.socket_timeout_ms` | 30000 | Socket operation timeout in milliseconds |
| `mailbox.capacity` | 128 | Maximum queued messages |
| `mailbox.bytes` | 8 MiB | Aggregate queued-message budget |
| `mailbox.message_bytes` | 1 MiB | Per-message budget, including framing overhead |

`mailbox.message_bytes` cannot exceed `mailbox.bytes`. The capacity must also
fit the byte budget's minimum 256-byte accounting per queued message. Unknown
fields and invalid values fail entry admission.



### CLI Commands


Register a WASM process as a named command with `meta.command`:

```yaml
  - name: greet
    kind: process.wasm
    meta:
      command:
        name: greet
        short: Greet someone via WASM
    fs: myns:wasm_binaries
    path: /component.wasm
    hash: sha256:...
    method: greet
```

Run it with:

```bash
wippy run greet
```

List available commands:

```bash
wippy run list
```

| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Command name used with `wippy run <name>` |
| `short` | No | Short description shown in `wippy run list` |
| `main` | No | Mark the entry as the default command for a pack or hub module |
| `use_case` | No | Entrypoint category; defaults to `run` |
| `security` | No | Security context applied only when the trusted terminal launcher starts this command |

A `terminal.host` must be present for CLI commands to work; it is the process host that runs the command.



### Process Lifecycle


WASM processes follow the Init/Step/Close lifecycle model:

1. **Init** - Call context, method, and input arguments are captured
2. **Step** - The first step instantiates and starts the module. Later steps advance dispatcher-bridged operations; a synchronous execution can complete in the first step.
3. **Close** - Instance resources are released



### Spawning from Lua


Spawn a WASM process and monitor it for completion:

```lua
local errors = require("errors")

-- Spawn with monitoring
local pid, err = process.spawn_monitored(
    "myns:compute_worker",   -- entry ID
    "myns:processes",        -- process host
    6, 7                     -- arguments passed to the WASM function
)

if err then
    return nil, err
end

-- Wait for the process to complete
local events = process.events()
while true do
    local event, open = events:receive()
    if not open then return nil, errors.new("process event channel closed") end
    if event.kind == process.event.EXIT and event.from == pid then
        local result = event.result.value  -- return value from the WASM function
        return result, event.result.error
    end
end
```



### Async Execution


WASM actors yield for host operations that the runtime bridges through the
dispatcher, including mailbox receive/send, polling, clocks, sockets, DNS,
filesystem streams, and outgoing HTTP. The scheduler suspends the process until
the pending operation completes, then resumes the same guest instance:

```yaml
  - name: http_worker
    kind: process.wasm
    fs: myns:wasm_binaries
    path: /http_worker.wasm
    hash: sha256:...
    method: run
    imports:
      - wasi:io
      - wasi:cli
      - wasi:http
    wasi:
      env:
        - id: myns:api_url
          name: API_URL
          required: true
```

The yield/resume mechanism is transparent to an asyncified core module or a
component using the supported pollable interfaces.



### WASI Configuration


Processes support the same WASI configuration as functions:

```yaml
  - name: file_processor
    kind: process.wasm
    fs: myns:wasm_binaries
    path: /processor.wasm
    hash: sha256:...
    method: process
    imports:
      - wasi:cli
      - wasi:io
      - wasi:clocks
      - wasi:filesystem
    wasi:
      args: ["--input", "/data/input.csv"]
      cwd: "/app"
      env:
        - id: myns:output_format
          name: OUTPUT_FORMAT
      mounts:
        - fs: myns:input_data
          guest: /data
          read_only: true
        - fs: myns:output_dir
          guest: /output
```



### See Also


- [Overview](wasm/overview.md) - WebAssembly runtime overview
- [Functions](wasm/functions.md) - WASM function configuration
- [Host Functions](wasm/hosts.md) - Available host interfaces
- [Process Model](concepts/process-model.md) - Process lifecycle
- [Supervision](guides/supervision.md) - Process supervision trees



---

# "Framework"

## Framework


Official framework modules are published through the Wippy Hub under the `wippy` organization.

This page is a module-management reference for an existing Wippy project. The commands are runnable from the project root; the YAML and import blocks are independent reference snippets rather than a complete application.



### Adding Framework Modules


```bash
wippy add wippy/test
wippy install
```

This adds the module to your lock file and downloads it to `.wippy/vendor/`.



### Declaring Dependencies in Source


Framework modules can also be declared as dependencies in your `_index.yaml`:

```yaml
version: "1.0"
namespace: app

entries:
  - name: dependency.test
    kind: ns.dependency
    component: wippy/test
    version: "*"
```

Then resolve and install:

```bash
wippy update
```



### Importing Framework Libraries


Once installed, import framework libraries into your entries:

```yaml
entries:
  - name: my_test
    kind: function.lua
    meta:
      type: test
      suite: my-suite
    source: file://my_test.lua
    method: run
    imports:
      test: wippy.test:test
```

The import maps `wippy.test:test` (the `test` entry from the `wippy.test` namespace) to the local name `test`, which you then `require("test")` in Lua.



### Available Modules


| Module | Description |
|--------|-------------|
| `wippy/llm` | Unified LLM interface with generation, streaming, tool calling, structured output |
| `wippy/agent` | Agent framework with tools, delegates, traits, and memory |
| `wippy/embeddings` | Vector embeddings storage and similarity search |
| `wippy/test` | BDD-style testing framework with assertions and mocking |
| `wippy/dataflow` | Workflow orchestration with DAG-based node execution |
| `wippy/relay` | WebSocket relay with per-user hubs and plugin routing |
| `wippy/views` | Virtual page/component system with template rendering |
| `wippy/facade` | Frontend host configuration, theming, and config endpoint |
| `wippy/terminal` | Terminal UI components |
| `wippy/migration` | Database schema migrations |
| `wippy/security` | Actor scopes, policy bundles, and security helpers |
| `wippy/usage` | Token and cost usage accounting for LLM calls |

Search the Hub for the current module catalog:

```bash
wippy search wippy
```



### See Also


- [Dependency Management](guides/dependency-management.md) — Lock files and version constraints
- [Publishing](guides/publishing.md) — Publish a module
- [CLI Reference](guides/cli.md) — Module-management commands



---

# "LLM"

## LLM


The `wippy/llm` module provides one interface for language models from OpenAI, Anthropic, Google, and local providers. It supports text generation, tool calling, structured output, embeddings, and streaming.

This page is an API primer with composable reference snippets, not a standalone tutorial. The snippets assume an existing Wippy project, a registered model and provider, and any credentials required by that provider. Replace example model names with one your registry exposes; remote generation and embedding calls may incur provider charges. For a complete runnable project, follow [Build an LLM Agent](tutorials/llm-agent.md).



### Setup


Add the module to your project:

```bash
wippy add wippy/llm
wippy install
```

Declare the dependency in your `_index.yaml`:

```yaml
version: "1.0"
namespace: app

entries:
  - name: dep.llm
    kind: ns.dependency
    component: wippy/llm
    version: "*"
```

The module supplies an OS environment storage and defaults its background
process host to `wippy.terminal:host`. Override the `env_storage` or
`process_host` dependency parameter only when the application needs a different
entry. Set provider API keys through variables such as `OPENAI_API_KEY` and
`ANTHROPIC_API_KEY`.



### Text Generation


Import the `llm` library into your entry and call `generate()`:

```yaml
entries:
  - name: ask
    kind: function.lua
    source: file://ask.lua
    method: handler
    imports:
      llm: wippy.llm:llm
```

```lua
local llm = require("llm")

local function handler()
    local response, err = llm.generate("What are the three laws of robotics?", {
        model = "gpt-4o"
    })

    if err then
        return nil, err
    end

    return response.result
end

return { handler = handler }
```

The first argument to `generate()` can be a string prompt, a prompt builder, or a table of messages. The second argument is an options table.



#### Generate Options


| Option | Type | Description |
|--------|------|-------------|
| `model` | string | Model name or class (required) |
| `temperature` | number | Randomness control, 0-2 (provider support may vary) |
| `max_tokens` | number | Maximum tokens to generate |
| `top_p` | number | Nucleus sampling parameter |
| `top_k` | number | Top-k filtering |
| `thinking_effort` | number | Thinking depth 0-100 (models with thinking capability) |
| `tools` | table | Array of tool definitions |
| `tool_choice` | string | `"auto"`, `"none"`, `"any"`, or tool name |
| `stream` | table | Streaming config: `{ reply_to, topic, buffer_size }` |
| `timeout` | number | Request timeout in seconds (default 600) |



#### Response Structure


| Field | Type | Description |
|-------|------|-------------|
| `result` | string | Generated text content |
| `tokens` | table | Token usage: `prompt_tokens`, `completion_tokens`, `thinking_tokens`, `total_tokens`, plus optional `cache_read_input_tokens`, `cache_read_tokens`, `cache_creation_input_tokens`, `cache_write_tokens` |
| `finish_reason` | string | Why generation stopped: `"stop"`, `"length"`, `"tool_call"`, `"filtered"`, `"error"` |
| `tool_calls` | table? | Array of tool calls (if model invoked tools) |
| `metadata` | table | Provider-specific metadata |
| `usage_record` | table? | Usage tracking record |



### Prompt Builder


Use the prompt builder to construct multi-turn conversations and structured messages:

```yaml
imports:
  llm: wippy.llm:llm
  prompt: wippy.llm:prompt
```

```lua
local llm = require("llm")
local prompt = require("prompt")

local conversation = prompt.new()
conversation:add_system("You are a helpful assistant.")
conversation:add_user("What is the capital of France?")

local response, err = llm.generate(conversation, {
    model = "gpt-4o",
    temperature = 0.7,
    max_tokens = 500
})
```



#### Builder Methods


| Method | Description |
|--------|-------------|
| `prompt.new()` | Create empty builder |
| `prompt.with_system(content)` | Create builder with system message |
| `:add_system(content, meta?)` | Add system message |
| `:add_user(content, meta?)` | Add user message |
| `:add_assistant(content, meta?)` | Add assistant message |
| `:add_developer(content, meta?)` | Add developer message |
| `:add_message(role, content_parts, name?, meta?)` | Add message with role and content parts |
| `:add_function_call(name, arguments, id?, options?)` | Add tool call from assistant (`arguments` is the raw JSON string) |
| `:add_function_result(name, result, id?)` | Add tool execution result |
| `:add_cache_marker(id?)` | Mark cache boundary (Claude models) |
| `:get_messages()` | Get message array |
| `:build()` | Get `{ messages = ... }` table for `llm.generate()` |
| `:clone()` | Deep copy the builder |
| `:clear()` | Remove all messages |

All `add_*` methods return the builder for chaining.



#### Multi-Turn Conversations


Build up context across turns by appending messages:

```lua
local conversation = prompt.new()
conversation:add_system("You are a helpful assistant.")

-- first turn
conversation:add_user("What is Lua?")
local r1 = llm.generate(conversation, { model = "gpt-4o" })
conversation:add_assistant(r1.result)

-- second turn with full context
conversation:add_user("What makes it different from Python?")
local r2 = llm.generate(conversation, { model = "gpt-4o" })
```



#### Multimodal Content


Combine text and images in a single message:

```lua
local conversation = prompt.new()
conversation:add_message(prompt.ROLE.USER, {
    prompt.text("What's in this image?"),
    prompt.image("https://example.com/photo.jpg")
})
```

| Function | Description |
|----------|-------------|
| `prompt.text(content)` | Text content part |
| `prompt.image(url, mime_type?)` | Image from URL |
| `prompt.image_base64(mime_type, data)` | Base64-encoded image |



#### Role Constants


| Constant | Value |
|----------|-------|
| `prompt.ROLE.SYSTEM` | `"system"` |
| `prompt.ROLE.USER` | `"user"` |
| `prompt.ROLE.ASSISTANT` | `"assistant"` |
| `prompt.ROLE.DEVELOPER` | `"developer"` |
| `prompt.ROLE.FUNCTION_CALL` | `"function_call"` |
| `prompt.ROLE.FUNCTION_RESULT` | `"function_result"` |
| `prompt.ROLE.CACHE_MARKER` | `"cache_marker"` |



#### Cloning


Clone a builder to create independent variations:

```lua
local base = prompt.new()
base:add_system("You are a helpful assistant.")

local conv1 = base:clone()
conv1:add_user("What is AI?")

local conv2 = base:clone()
conv2:add_user("What is ML?")
```



### Streaming


Stream responses through process communication. Streaming requires a `process.lua` entry:

```lua
local llm = require("llm")

local TOPIC = "llm_stream"

local function main()
    local stream_ch, listen_err = process.listen(TOPIC)
    if listen_err then
        return nil, listen_err
    end

    local function finish(text, response, err)
        local ok, cleanup_err = process.unlisten(stream_ch)
        if not ok then
            cleanup_err = cleanup_err or "Failed to remove LLM stream listener"
            if err then
                return nil, tostring(err) .. "; cleanup failed: " .. tostring(cleanup_err)
            end
            return nil, cleanup_err
        end
        if err then
            return nil, err
        end
        return text, response
    end

    local self_pid, pid_err = process.pid()
    if pid_err then
        return finish(nil, nil, pid_err)
    end

    local done_ch = channel.new(1)
    coroutine.spawn(function()
        local response, err = llm.generate("Write a short story", {
            model = "gpt-4o",
            stream = {
                reply_to = self_pid,
                topic = TOPIC,
            },
        })
        done_ch:send({ response = response, err = err })
    end)

    local full_text = ""
    local generation_result = nil
    local stream_done = false
    local stream_err = nil

    while true do
        local cases = {}
        if not stream_done then
            table.insert(cases, stream_ch:case_receive())
        end
        if not generation_result then
            table.insert(cases, done_ch:case_receive())
        end

        local result = channel.select(cases)
        if not result.ok then
            return finish(nil, nil, "LLM stream closed before completion")
        end

        if result.channel == done_ch then
            generation_result = result.value
            if generation_result.err then
                return finish(nil, nil, generation_result.err)
            end
            if stream_done then
                return finish(full_text, generation_result.response, stream_err)
            end
        else
            local chunk = result.value
            if chunk.type == "chunk" then
                local content = chunk.content or ""
                print(content)
                full_text = full_text .. content
            elseif chunk.type == "thinking" then
                print(chunk.content or "")
            elseif chunk.type == "error" then
                stream_done = true
                stream_err = chunk.error and chunk.error.message or "LLM stream failed"
            elseif chunk.type == "done" then
                stream_done = true
            end

            if stream_done and generation_result then
                return finish(full_text, generation_result.response, stream_err)
            end
        end
    end
end
```



#### Chunk Types


| Type | Fields | Description |
|------|--------|-------------|
| `"chunk"` | `content` | Text content fragment |
| `"thinking"` | `content` | Model thinking process |
| `"tool_call"` | `name`, `arguments`, `id` | Tool invocation |
| `"error"` | `error.message`, `error.type` | Stream error |
| `"done"` | `meta` | Stream complete |

<note>
Streaming requires a <code>process.lua</code> entry because it uses Wippy's process communication system (<code>process.pid()</code>, <code>process.listen()</code>).
Run generation in a separate coroutine so the listener drains chunks concurrently, and remove the listener on every return path.
</note>



### Tool Calling


Define tools with inline schemas and pass them to `generate()`:

```lua
local llm = require("llm")
local prompt = require("prompt")
local json = require("json")

local tools = {
    {
        name = "get_weather",
        description = "Get current weather for a location",
        schema = {
            type = "object",
            properties = {
                location = { type = "string", description = "City name" },
            },
            required = { "location" },
        },
    },
}

local conversation = prompt.new()
conversation:add_user("What's the weather in Tokyo?")

local response = llm.generate(conversation, {
    model = "gpt-4o",
    tools = tools,
    tool_choice = "auto",
})

if response.tool_calls and #response.tool_calls > 0 then
    for _, tc in ipairs(response.tool_calls) do
        -- execute the tool and get a result
        local result = { temperature = 22, condition = "sunny" }

        -- add the exchange to the conversation
        conversation:add_function_call(tc.name, json.encode(tc.arguments), tc.id)
        conversation:add_function_result(tc.name, json.encode(result), tc.id)
    end

    -- continue generation with tool results
    local final = llm.generate(conversation, { model = "gpt-4o" })
    print(final.result)
end
```



#### Tool Call Fields


| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique call identifier |
| `name` | string | Tool name |
| `arguments` | table | Parsed arguments matching the schema |



#### Tool Choice


| Value | Behavior |
|-------|----------|
| `"auto"` | Model decides when to use tools (default) |
| `"none"` | Never use tools |
| `"any"` | Must use at least one tool |
| `"tool_name"` | Must use the specified tool |



### Structured Output


Generate JSON validated against a schema:

```lua
local llm = require("llm")

local schema = {
    type = "object",
    properties = {
        name = { type = "string" },
        age = { type = "number" },
        hobbies = {
            type = "array",
            items = { type = "string" },
        },
    },
    required = { "name", "age", "hobbies" },
    additionalProperties = false,
}

local response, err = llm.structured_output(schema, "Describe a fictional character", {
    model = "gpt-4o",
})

if not err then
    print(response.result.name)
    print(response.result.age)
end
```

<tip>
For OpenAI models, all properties must be in the <code>required</code> array. Use union types for optional fields: <code>type = {"string", "null"}</code>. Set <code>additionalProperties = false</code>.
</tip>



### Model Configuration


Define models as registry entries with `meta.type: llm.model`:

```yaml
entries:
  - name: gpt-4o
    kind: registry.entry
    meta:
      name: gpt-4o
      type: llm.model
      title: GPT-4o
      comment: OpenAI's flagship model
      capabilities:
        - generate
        - tool_use
        - structured_output
        - vision
      class:
        - balanced
      priority: 100
    max_tokens: 128000
    output_tokens: 16384
    pricing:
      input: 2.5
      output: 10
    providers:
      - id: wippy.llm.openai:provider
        provider_model: gpt-4o
```



#### Model Entry Fields


| Field | Description |
|-------|-------------|
| `meta.name` | Model identifier used in API calls |
| `meta.type` | Must be `llm.model` |
| `meta.capabilities` | Feature list: `generate`, `tool_use`, `structured_output`, `embed`, `thinking`, `vision`, `caching` |
| `meta.class` | Class membership: `fast`, `balanced`, `reasoning`, etc. |
| `meta.priority` | Numeric priority for class-based resolution (higher wins) |
| `max_tokens` | Maximum context window |
| `output_tokens` | Maximum output tokens |
| `pricing` | Cost per million tokens: `input`, `output` |
| `providers` | Array with `id` (provider entry) and `provider_model` (provider-specific model name) |



#### Local Models


For locally hosted models (LM Studio, Ollama), define a separate provider entry with a custom `base_url`:

```yaml
  - name: local_provider
    kind: registry.entry
    meta:
      name: ollama
      type: llm.provider
      title: Ollama Local
    driver:
      id: wippy.llm.openai:driver
      options:
        api_key_env: none
        base_url: http://127.0.0.1:11434/v1

  - name: local-llama
    kind: registry.entry
    meta:
      name: local-llama
      type: llm.model
      title: Local Llama
      capabilities:
        - generate
    max_tokens: 4096
    output_tokens: 4096
    pricing:
      input: 0
      output: 0
    providers:
      - id: app:local_provider
        provider_model: llama-3.2
```



### Model Resolution


Models can be referenced by exact name, class, or explicit class prefix:

```lua
-- exact model name
llm.generate("Hello", { model = "gpt-4o" })

-- model class (picks highest priority in that class)
llm.generate("Hello", { model = "fast" })

-- explicit class syntax
llm.generate("Hello", { model = "class:reasoning" })
```

Resolution order:
1. Match by exact `meta.name`
2. Match by class name (highest `meta.priority` wins)
3. With `class:` prefix, search only in that class



### Model Discovery


Query available models and their capabilities at runtime:

```lua
local llm = require("llm")

-- all models
local models = llm.available_models()

-- filter by capability
local tool_models = llm.available_models("tool_use")
local embed_models = llm.available_models("embed")

-- list model classes
local classes = llm.get_classes()
for _, c in ipairs(classes) do
    print(c.name .. ": " .. c.title)
end
```



### Embeddings


Generate vector embeddings for semantic search:

```lua
local llm = require("llm")

-- A single input still returns an array of vectors.
local single_response, single_err = llm.embed("The quick brown fox", {
    model = "text-embedding-3-small",
    dimensions = 512,
})
if single_err then
    error("Embedding failed: " .. tostring(single_err))
end
local vector = single_response.result[1]

-- Multiple inputs return one vector per input.
local batch_response, batch_err = llm.embed({
    "First document",
    "Second document",
}, { model = "text-embedding-3-small" })
if batch_err then
    error("Batch embedding failed: " .. tostring(batch_err))
end
local vectors = batch_response.result
```



### Provider Status


Probe a provider before sending work, such as during readiness checks:

```lua
local status, err = llm.status({
    model = "gpt-4o",
})
```

| Option | Description |
|--------|-------------|
| `model` | Required. Model to check. |
| `provider_id` | Optional. Skip model resolution and target a specific provider. |

Returns the provider's `StatusResponse` (contents are provider-dependent).



### Error Handling


Errors are returned as the second return value. On error, the first return value is `nil`:

```lua
local response, err = llm.generate("Hello", { model = "gpt-4o" })

if err then
    print("Error: " .. tostring(err))
    return
end

print(response.result)
```



#### Error Types


| Constant | Description |
|----------|-------------|
| `llm.ERROR_TYPE.INVALID_REQUEST` | Malformed request |
| `llm.ERROR_TYPE.AUTHENTICATION` | Invalid API key |
| `llm.ERROR_TYPE.RATE_LIMIT` | Provider rate limit exceeded |
| `llm.ERROR_TYPE.SERVER_ERROR` | Provider server error |
| `llm.ERROR_TYPE.CONTEXT_LENGTH` | Input exceeds context window |
| `llm.ERROR_TYPE.CONTENT_FILTER` | Content filtered by safety systems |
| `llm.ERROR_TYPE.TIMEOUT` | Request timed out |
| `llm.ERROR_TYPE.MODEL_ERROR` | Invalid or unavailable model |



#### Finish Reasons


| Constant | Description |
|----------|-------------|
| `llm.FINISH_REASON.STOP` | Normal completion |
| `llm.FINISH_REASON.LENGTH` | Reached max tokens |
| `llm.FINISH_REASON.CONTENT_FILTER` | Content filtered |
| `llm.FINISH_REASON.TOOL_CALL` | Model made a tool call |
| `llm.FINISH_REASON.ERROR` | Error during generation |



### Capabilities


| Constant | Description |
|----------|-------------|
| `llm.CAPABILITY.GENERATE` | Text generation |
| `llm.CAPABILITY.TOOL_USE` | Tool/function calling |
| `llm.CAPABILITY.STRUCTURED_OUTPUT` | JSON structured output |
| `llm.CAPABILITY.EMBED` | Vector embeddings |
| `llm.CAPABILITY.THINKING` | Extended thinking |
| `llm.CAPABILITY.VISION` | Image understanding |
| `llm.CAPABILITY.CACHING` | Prompt caching |



### See Also


- [Agents](framework/agents.md) — Agent framework with tools, delegates, and memory
- [Building an LLM Agent](../tutorials/llm-agent.md) — Build an agent step by step
- [Framework Overview](framework/overview.md) — Install and import framework modules



---

# "Agents"

## Agents


The `wippy/agent` module defines agents declaratively and runs them through a context and runner. Agents can use tools, stream responses, delegate work, apply traits, and recall memory.

This page is an API primer with composable reference snippets, not a standalone tutorial. The snippets assume an existing Wippy project, a registered LLM model and provider, configured provider credentials, and the agent, tool, or resolver entries referenced by each example. Later snippets build on variables such as `ctx`, `runner`, and `conversation` created in earlier sections. For a complete runnable project, follow [Build an LLM Agent](tutorials/llm-agent.md).



### Setup


Add the module to your project:

```bash
wippy add wippy/agent
wippy install
```

The agent module declares its `wippy/llm` dependency itself. Add the agent
dependency to source when it is not already present:

```yaml
version: "1.0"
namespace: app

entries:
  - name: dep.agent
    kind: ns.dependency
    component: wippy/agent
    version: "*"
```



### Agent Definitions


Agents are registry entries with `meta.type: agent.gen1`:

```yaml
entries:
  - name: assistant
    kind: registry.entry
    meta:
      type: agent.gen1
      name: assistant
      title: Assistant
      comment: A helpful chat assistant
    prompt: |
      You are a helpful assistant. Be concise and direct.
      Answer questions clearly.
    model: gpt-4o
    max_tokens: 1024
    temperature: 0.7
```



#### Agent Fields


| Field | Type | Description |
|-------|------|-------------|
| `meta.type` | string | Must be `agent.gen1` |
| `meta.name` | string | Agent identifier |
| `prompt` | string | System prompt |
| `model` | string | Model name or class |
| `max_tokens` | number | Maximum output tokens (default `512`) |
| `temperature` | number | Optional sampling temperature; omitted by default, with range and support determined by the provider |
| `thinking_effort` | number | Forwarded to the model only when `> 0` (provider-defined scale) |
| `tools` | array | Tool registry IDs |
| `traits` | array | Trait references |
| `delegates` | array | Delegate agent references |
| `memory` | array | Static memory items (strings) |
| `memory_contract` | table | Dynamic memory configuration |



### Agent Context


Create an agent context, configure it as needed, and then load an agent:

```yaml
imports:
  agent_context: wippy.agent:context
  prompt: wippy.llm:prompt
```

```lua
local agent_context = require("agent_context")

local ctx = agent_context.new()
local runner, err = ctx:load_agent("app:assistant")
if err then
    error("Failed to load agent: " .. tostring(err))
end
```



#### Context Methods


| Method | Description |
|--------|-------------|
| `agent_context.new(options?)` | Create new context |
| `:add_tools(specs)` | Add tools at runtime |
| `:add_delegates(specs)` | Add delegate agents |
| `:configure_delegate_tools(config)` | Configure how delegates expose themselves as tools |
| `:set_memory_contract(config)` | Configure dynamic memory |
| `:set_context_merger(fn)` | Provide a function to merge runtime context updates |
| `:update_context(updates)` | Update runtime context |
| `:load_agent(spec_or_id, options?)` | Load and compile agent, returns runner |
| `:switch_to_agent(id, options?)` | Switch to different agent, returns `(boolean, string?)` |
| `:switch_to_model(name)` | Change model on current agent, returns `(boolean, string?)` |
| `:get_current_agent()` | Get current runner |
| `:get_config()` | Return a summary of the context configuration |



#### Context Options


```lua
local ctx = agent_context.new({
    context = { session_id = "abc", user_id = "u1" },
    delegate_tools = { enabled = true },
    enable_cache = true,
})
```

| Option | Description |
|--------|-------------|
| `context` | Base runtime context forwarded to tools and delegates |
| `delegate_tools` | Default delegate-tool configuration (overridden by `configure_delegate_tools`) |
| `enable_cache` | Prompt cache marker setting for Claude models. The current implementation always enables markers, including when this option is `false`. |



#### Loading by Inline Spec


Load an agent without a registry entry:

```lua
local runner, err = ctx:load_agent({
    id = "inline-agent",
    name = "helper",
    prompt = "You are a helpful assistant.",
    model = "gpt-4o",
    max_tokens = 1024,
    tools = { "app.tools:search" },
})
```



### Running Steps


The runner executes one agent step from a prompt-builder conversation:

```lua
local prompt = require("prompt")

local conversation = prompt.new()
conversation:add_user("What is the capital of France?")

local response, err = runner:step(conversation)
if err then
    error(tostring(err))
end

print(response.result)
```



#### Step Options


```lua
local self_pid, pid_err = process.pid()
if pid_err then
    error("Failed to get process PID: " .. tostring(pid_err))
end

local response, err = runner:step(conversation, {
    context = { session_id = "abc" },
    stream_target = { reply_to = self_pid, topic = "stream" },
    tool_call = "auto",
})
if err then
    error("Agent step failed: " .. tostring(err))
end
```

| Option | Type | Description |
|--------|------|-------------|
| `context` | table | Runtime context merged with agent context |
| `stream_target` | table | Streaming: `{ reply_to, topic }` |
| `tool_call` | string | `"auto"`, `"any"`, `"none"`, or a tool name |



#### Step Response


| Field | Type | Description |
|-------|------|-------------|
| `result` | string | Generated text |
| `tokens` | table | Token usage |
| `finish_reason` | string | Stop reason |
| `tool_calls` | table? | Tool calls to execute |
| `delegate_calls` | table? | Delegate invocations |



#### Runner Stats


```lua
local stats = runner:get_stats()
-- stats.id, stats.name, stats.total_tokens
```



### Tool Definitions


Tools are `function.lua` entries with `meta.type: tool`. Define them in a separate `_index.yaml`:

```yaml
version: "1.0"
namespace: app.tools

entries:
  - name: calculate
    kind: function.lua
    meta:
      type: tool
      title: Calculate
      input_schema: |
        {
          "type": "object",
          "properties": {
            "expression": {
              "type": "string",
              "description": "Math expression to evaluate"
            }
          },
          "required": ["expression"],
          "additionalProperties": false
        }
      llm_alias: calculate
      llm_description: Evaluate a mathematical expression.
    source: file://calculate.lua
    modules: [expr]
    method: handler
```

```lua
local expr = require("expr")

local function handler(args)
    local result, err = expr.eval(args.expression)
    if err then
        return { error = tostring(err) }
    end
    return { result = result }
end

return { handler = handler }
```



#### Tool Metadata


| Field | Type | Description |
|-------|------|-------------|
| `meta.type` | string | Must be `tool` |
| `meta.input_schema` | string/table | JSON Schema for tool arguments |
| `meta.llm_alias` | string | Name exposed to the LLM |
| `meta.llm_description` | string | Description exposed to the LLM |
| `meta.exclusive` | boolean | If true, cancels concurrent tool calls |



#### Referencing Tools in Agents


List tool registry IDs in the agent definition:

```yaml
  - name: assistant
    kind: registry.entry
    meta:
      type: agent.gen1
      name: assistant
    prompt: You are a helpful assistant with tools.
    model: gpt-4o
    max_tokens: 1024
    tools:
      - app.tools:calculate
      - app.tools:search
      - app.tools:*          # wildcard: all tools in namespace
```

Tools can also be referenced with custom aliases and context:

```yaml
    tools:
      - id: app.tools:search
        alias: web_search
        context:
          api_key: "${SEARCH_API_KEY}"
```



### Tool Execution


When an agent step returns `tool_calls`, execute the calls and add their results to the conversation:

```lua
local json = require("json")
local funcs = require("funcs")

local function execute_and_continue(runner, conversation)
    while true do
        local response, err = runner:step(conversation)
        if err then return nil, err end

        local tool_calls = response.tool_calls
        if not tool_calls or #tool_calls == 0 then
            return response.result, nil
        end

        for _, tc in ipairs(tool_calls) do
            local result, call_err = funcs.call(tc.registry_id, tc.arguments)
            local result_str
            if call_err then
                result_str = json.encode({ error = tostring(call_err) })
            else
                result_str = json.encode(result)
            end

            conversation:add_function_call(tc.name, json.encode(tc.arguments), tc.id)
            conversation:add_function_result(tc.name, result_str, tc.id)
        end
    end
end
```



#### Tool Call Fields


| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique call identifier |
| `name` | string | Tool name (alias or llm_alias) |
| `arguments` | table | Parsed arguments |
| `registry_id` | string | Full registry ID for `funcs.call()` |

<note>
Use <code>funcs.call(tc.registry_id, tc.arguments)</code> to execute tools. The <code>registry_id</code> field maps directly to the tool's entry in the registry.
</note>

For how agent tool access and observability are secured, see the [Security Model](concepts/security-model.md).



### Streaming


Stream agent responses through `stream_target`:

```lua
local TOPIC = "agent_stream"

local function stream_step(runner, conversation)
    local stream_ch, listen_err = process.listen(TOPIC)
    if listen_err then
        return nil, nil, listen_err
    end

    local function finish(text, response, err)
        local ok, cleanup_err = process.unlisten(stream_ch)
        if not ok then
            cleanup_err = cleanup_err or "Failed to remove agent stream listener"
            if err then
                return text, nil, tostring(err) .. "; cleanup failed: " .. tostring(cleanup_err)
            end
            return text, nil, cleanup_err
        end
        if err then
            return text, nil, err
        end
        return text, response, nil
    end

    local self_pid, pid_err = process.pid()
    if pid_err then
        return finish("", nil, pid_err)
    end

    local done_ch = channel.new(1)
    coroutine.spawn(function()
        local response, err = runner:step(conversation, {
            stream_target = {
                reply_to = self_pid,
                topic = TOPIC,
            },
        })
        done_ch:send({ response = response, err = err })
    end)

    local full_text = ""
    local step_result = nil
    local stream_done = false
    local stream_err = nil

    while true do
        local cases = {}
        if not stream_done then
            table.insert(cases, stream_ch:case_receive())
        end
        if not step_result then
            table.insert(cases, done_ch:case_receive())
        end

        local result = channel.select(cases)
        if not result.ok then
            return finish(full_text, nil, "Agent stream closed before completion")
        end

        if result.channel == done_ch then
            step_result = result.value
            if step_result.err then
                return finish(full_text, nil, step_result.err)
            end
            if stream_done then
                return finish(full_text, step_result.response, stream_err)
            end
        else
            local chunk = result.value
            if chunk.type == "chunk" then
                local content = chunk.content or ""
                print(content)
                full_text = full_text .. content
            elseif chunk.type == "error" then
                stream_done = true
                stream_err = chunk.error and chunk.error.message or "Agent stream failed"
            elseif chunk.type == "done" then
                stream_done = true
            end

            if stream_done and step_result then
                return finish(full_text, step_result.response, stream_err)
            end
        end
    end
end
```

The stream uses the same chunk types as direct LLM streaming: `"chunk"`, `"thinking"`, `"tool_call"`, `"error"`, `"done"`.

<tip>
Use <code>coroutine.spawn</code> to run <code>runner:step()</code> in a separate coroutine so you can receive stream chunks concurrently. Use <code>channel.select</code> to multiplex the stream and completion channels.
</tip>



### Delegates


Agents can delegate to other agents. Delegates appear as tools to the parent agent:

```yaml
  - name: coordinator
    kind: registry.entry
    meta:
      type: agent.gen1
      name: coordinator
    prompt: Route questions to the right specialist.
    model: gpt-4o
    max_tokens: 1024
    delegates:
      - id: app:code_agent
        name: ask_coder
        rule: for programming questions
      - id: app:math_agent
        name: ask_mathematician
        rule: for math problems
```

Delegate calls appear in `response.delegate_calls`:

```lua
local response, err = runner:step(conversation)
if err then
    error("Delegate step failed: " .. tostring(err))
end

if response.delegate_calls then
    for _, dc in ipairs(response.delegate_calls) do
        -- dc.agent_id - target agent registry ID
        -- dc.name - delegate tool name
        -- dc.arguments - forwarded message
    end
end
```

Delegates can also be added at runtime:

```lua
ctx:add_delegates({
    { id = "app:specialist", name = "ask_specialist", rule = "for domain questions" },
})
```



### Traits


Traits are reusable definitions that contribute prompts, tools, and behavior to agents:

```yaml
  - name: assistant
    kind: registry.entry
    meta:
      type: agent.gen1
      name: assistant
    prompt: You are a helpful assistant.
    model: gpt-4o
    traits:
      - time_aware
      - id: custom_trait
        context:
          key: value
```



#### Built-in Traits


| Trait | Description |
|-------|-------------|
| `time_aware` | Injects current date and time into the prompt |

The `time_aware` trait accepts context options:

```yaml
    traits:
      - id: time_aware
        context:
          timezone: America/New_York
          time_interval: 15
```



#### Custom Traits


Traits are registry entries with `meta.type: agent.trait`. They can contribute:
- **prompt** - static text appended to the system prompt
- **build_func_id** - function called at compile time to contribute tools, prompts, delegates
- **prompt_func_id** - function called at each step to inject dynamic content
- **step_func_id** - function called at each step for side effects



#### Static Memory


Static memory items are appended to the system prompt:

```yaml
  - name: assistant
    kind: registry.entry
    meta:
      type: agent.gen1
      name: assistant
    prompt: You are a helpful assistant.
    model: gpt-4o
    memory:
      - "User prefers concise answers"
      - "Always cite sources when possible"
```



#### Dynamic Memory Contract


Configure dynamic memory recall through an external implementation:

```yaml
    memory_contract:
      implementation_id: app:memory_store
      context:
        user_id: "${user_id}"
      options:
        max_items: 3
        max_length: 1000
        recall_cooldown: 1
        min_conversation_length: 2
```

The memory contract is called during `runner:step()` to recall relevant items based on the conversation context. Results are injected as developer messages.

| Option | Default | Description |
|--------|---------|-------------|
| `max_items` | `3` | Maximum memory items per recall |
| `max_length` | `1000` | Maximum total character length |
| `recall_cooldown` | `1` | Minimum steps between recalls |
| `min_conversation_length` | `2` | Minimum conversation turns before first recall |



### Resolver Contract


When `load_agent()` receives a string identifier, it first tries to resolve it through the `wippy.agent:resolver` contract. If no resolver is bound or the resolver returns nil, it falls back to the registry lookup.

This allows applications to implement custom agent resolution, such as loading agent definitions from a database.



#### Binding a Resolver


Define a resolver function and bind it to the contract:

```yaml
entries:
  - name: agent_resolver.resolve
    kind: function.lua
    source: file://agent_resolver.lua
    method: resolve
    modules:
      - logger
    imports:
      agent_registry: wippy.agent.discovery:registry

  - name: agent_resolver_binding
    kind: contract.binding
    contracts:
      - contract: wippy.agent:resolver
        default: true
        methods:
          resolve: app:agent_resolver.resolve
```



#### Resolver Implementation


The resolver receives `{ agent_id = "..." }` and returns an agent spec table or nil:

```lua
local agent_registry = require("agent_registry")

local CUSTOM_PREFIX = "custom:"

function resolve(args)
    local agent_id = args.agent_id
    if not agent_id then
        return nil, "agent_id is required"
    end

    if agent_id:sub(1, #CUSTOM_PREFIX) == CUSTOM_PREFIX then
        local id = agent_id:sub(#CUSTOM_PREFIX + 1)

        -- load from database, config file, or any other source
        return {
            id = agent_id,
            name = "custom-agent",
            prompt = "You are a custom agent.",
            model = "class:balanced",
            max_tokens = 1024,
            tools = {},
        }
    end

    -- fall back to registry
    local spec, err = agent_registry.get_by_id(agent_id)
    if not spec then
        spec, err = agent_registry.get_by_name(agent_id)
    end
    return spec, err
end

return {
    resolve = resolve,
}
```



#### Resolution Order


1. Try `wippy.agent:resolver` contract (if bound)
2. Try registry lookup by ID
3. Try registry lookup by name
4. Return error if not found

Custom resolution can load agent definitions outside the framework registry, including definitions scoped by user or workspace.



### See Also


- [LLM](framework/llm.md) — Underlying model interface
- [Building an LLM Agent](../tutorials/llm-agent.md) — Build an agent step by step
- [Framework Overview](framework/overview.md) — Install and import framework modules



---

# "Test Framework"

## Test Framework


The `wippy/test` module provides BDD suites, assertions, lifecycle hooks, mocks, and a runner for test entries.

This page is an API primer. Its Lua, YAML, output, and project-layout blocks are reference snippets that can be combined in an existing Wippy project; they are not one copy-and-run project. Names such as `validate`, `format_name`, `db`, `connect`, and `notify_user` stand for application functions or modules supplied by the test subject. For a complete runnable example, follow [Testing a Wippy Application](../tutorials/testing.md).



### Setup


Add the dependency:

```bash
wippy add wippy/test
wippy install
```

The module registers the test entrypoint automatically (a command with `use_case: test`). Once installed, `wippy test` discovers and runs all test entries in your project.



### Defining Tests


Tests are `function.lua` entries with `meta.type: test`:

```yaml
version: "1.0"
namespace: app.test

entries:
  - name: math
    kind: function.lua
    meta:
      type: test
      suite: math
      name: Math operations
    source: file://math_test.lua
    method: main
    imports:
      test: wippy.test:test
```



#### Test Metadata


| Field | Required | Description |
|-------|----------|-------------|
| `type` | Yes | Must be `"test"` for the runner to discover it |
| `suite` | No | Groups tests in the runner output |
| `name` | No | Display name shown in runner output |
| `order` | No | Sort order within a suite (lower runs first) |



#### BDD Style


Use `describe` and `it` blocks to structure tests:

```lua
local test = require("test")

local function define_tests()
    test.describe("calculator", function()
        test.it("adds numbers", function()
            test.eq(1 + 1, 2)
        end)

        test.it("multiplies numbers", function()
            test.eq(3 * 4, 12)
        end)
    end)
end

local run_cases = test.run_cases(define_tests)

local function run(options)
    local result = run_cases(options)
    if result.failed_tests > 0 then
        error("tests failed: " .. result.failed_tests)
    end
    return result
end

return { run = run }
```



#### Nested Suites


Suites can be nested to group related behavior:

```lua
test.describe("user", function()
    test.describe("validation", function()
        test.it("requires name", function()
            test.ok(validate({}).error)
        end)

        test.it("accepts valid input", function()
            test.is_nil(validate({name = "Alice"}).error)
        end)
    end)

    test.describe("formatting", function()
        test.it("formats display name", function()
            test.eq(format_name("alice"), "Alice")
        end)
    end)
end)
```



#### Skipping Tests


```lua
test.it_skip("not implemented yet", function()
    test.fail("TODO")
end)
```

Skipped tests appear in the output but do not count as failures.



#### Suite Aliases


`test.spec` and `test.context` are aliases for `test.describe`:

```lua
test.spec("feature", function()
    test.context("when valid input", function()
        test.it("succeeds", function()
            test.ok(true)
        end)
    end)
end)
```



#### Equality


```lua
test.eq(actual, expected, msg?)       -- actual == expected
test.neq(actual, expected, msg?)      -- actual ~= expected
```



#### Truthiness


```lua
test.ok(val, msg?)                    -- val is truthy
test.fail(msg?)                       -- unconditional failure
```



#### Nil Checks


```lua
test.is_nil(val, msg?)                -- val == nil
test.not_nil(val, msg?)               -- val ~= nil
```



#### Type Checks


```lua
test.is_true(val, msg?)               -- val == true
test.is_false(val, msg?)              -- val == false
test.is_string(val, msg?)
test.is_number(val, msg?)
test.is_table(val, msg?)
test.is_function(val, msg?)
test.is_boolean(val, msg?)
```



#### Strings and Collections


```lua
test.contains(str, substr, msg?)      -- substring match
test.matches(str, pattern, msg?)      -- Lua pattern match
test.has_key(tbl, key, msg?)          -- table key exists
test.len(val, expected, msg?)         -- #val == expected
```



#### Numeric Comparisons


```lua
test.gt(a, b, msg?)                   -- a > b
test.gte(a, b, msg?)                  -- a >= b
test.lt(a, b, msg?)                   -- a < b
test.lte(a, b, msg?)                  -- a <= b
```



#### Error Handling


```lua
test.throws(fn, msg?)                 -- fn() raises error, returns it
test.has_error(val, err, msg?)        -- val is nil, err is not nil
test.no_error(val, err, msg?)         -- err is nil
```

All assertions accept an optional message as the last argument. On failure, the message is included in the error output.



### Lifecycle Hooks


```lua
test.describe("database", function()
    test.before_all(function()
        -- runs once before the suite
        db = connect()
    end)

    test.after_all(function()
        -- runs once after the suite
        db:close()
    end)

    test.before_each(function()
        -- runs before each test
        db:begin_transaction()
    end)

    test.after_each(function()
        -- runs after each test
        db:rollback()
    end)

    test.it("inserts a record", function()
        db:exec("INSERT INTO users (name) VALUES ('Alice')")
        local count = db:query_row("SELECT COUNT(*) FROM users")
        test.eq(count, 1)
    end)
end)
```

Hooks in nested suites execute in order: parent `before_each` runs before child `before_each`, and child `after_each` runs before parent `after_each`.



### Mocking


The mock system replaces global object fields and restores them after each test.



#### Basic Mocking


```lua
test.describe("notifications", function()
    test.it("sends message", function()
        local sent = false
        test.mock("process.send", function(pid, topic, payload)
            sent = true
        end)

        notify_user("hello")
        test.is_true(sent)
        -- mock is auto-restored after this test
    end)
end)
```



#### Mock API


```lua
test.mock("object.field", replacement)    -- replace a global field
test.mock_process("field", replacement)   -- shorthand for process fields
test.restore_mock("object.field")         -- restore one mock
test.restore_all_mocks()                  -- restore all mocks
```

Mock paths use dot notation: `"process.send"` replaces `_G.process.send`.

Mocks for `process.send` automatically proxy test framework messages through the original function, so test event reporting continues to work when process.send is mocked.

All mocks are automatically restored after each test via the `after_each` hook.



#### Run All Tests


```bash
wippy test
```



#### Filter by Pattern


```bash
wippy test math
wippy test user validation
```

Filters match literal substrings of entry IDs. When you provide multiple
patterns, an entry runs if its ID matches any of them.



#### Example Output


```
3 tests in 1 suites

  calculator
    + adds numbers                           0ms
    + multiplies numbers                     0ms
    - divides by zero                        1ms
      Error: expected error, got nil

  1 suite | 2 passed | 1 failed | 0 skipped | 3ms
```



### Simple Tests


For tests that do not need BDD suites, define a function that returns `true` or raises an error:

```lua
local funcs = require("funcs")

local function main()
    local result, err = funcs.call("app:my_function", "input")
    if err then
        error("call failed: " .. tostring(err))
    end
    if result ~= "expected" then
        error("expected 'expected', got: " .. tostring(result))
    end
    return true
end

return { main = main }
```

```yaml
  - name: integration
    kind: function.lua
    meta:
      type: test
      suite: integration
    source: file://integration_test.lua
    method: main
    modules:
      - funcs
```

The runner detects whether a test uses BDD case events or returns a simple value. Both patterns work with `wippy test`.



### Project Structure


A typical test layout:

```
src/
  _index.yaml
  app.lua
  test/
    _index.yaml          # test entries
    math_test.lua
    user_test.lua
    integration_test.lua
```

The test `_index.yaml` defines the test namespace and entries:

```yaml
version: "1.0"
namespace: app.test

entries:
  - name: math
    kind: function.lua
    meta:
      type: test
      suite: math
    source: file://math_test.lua
    method: main
    imports:
      test: wippy.test:test

  - name: user
    kind: function.lua
    meta:
      type: test
      suite: user
    source: file://user_test.lua
    method: main
    imports:
      test: wippy.test:test
```



### Terminal Host


`wippy/test` depends on `wippy/terminal`, which supplies the auto-starting
`wippy.terminal:host` used by the CLI runner. Applications do not need to
declare a separate process or terminal host solely to run `wippy test`.



### See Also


- [Framework Overview](framework/overview.md) — Install and import framework modules
- [CLI Reference](guides/cli.md) — Test command and flags
- [Functions](concepts/functions.md) — Function entries and invocation



---

# "Dataflow"

## Dataflow


The `wippy/dataflow` module provides a workflow orchestration engine based on directed acyclic graphs (DAGs). Workflows are composed of nodes — functions, agents, cycles, and parallel processors — connected by typed data routes. The orchestrator manages execution, state persistence, and recovery.



### Setup


Add the module to your project:

```bash
wippy add wippy/dataflow
wippy install
```

Declare the dependency:

```yaml
version: "1.0"
namespace: app

entries:
  - name: dep.dataflow
    kind: ns.dependency
    component: wippy/dataflow
    version: "*"
```

The dataflow module depends on `wippy/agent`, `wippy/llm`, and `wippy/session` — these are resolved automatically when you run `wippy install`. The module requires a database resource at `app:db` for workflow persistence and runs migrations automatically via `wippy/migration`.

The module publishes an `env.variable` entry `userspace.dataflow.env:web_host_origin` (default `https://front.wippy.ai`) that downstream flows can read for building public URLs. Override it through the env router or a requirement.



### Flow Builder


The flow builder provides a fluent interface for composing workflows. Import it into your entry:

```yaml
imports:
  flow: userspace.dataflow.flow:flow
```

```lua
local flow = require("flow")
```



#### Core API


```lua
flow.create()
    :with_title(title)
    :with_metadata(metadata)
    :with_input(data)
    :with_data(data)
    :[operation](config)
    :as(name)
    :to(target, input_key, transform)
    :error_to(target, input_key, transform)
    :when(condition)
    :run()   -- synchronous
    :start() -- asynchronous

flow.template()
    :[operations]...
```



#### Linear Pipeline


Nodes chain automatically when no explicit routing is defined. Output of each node flows to the next:

```lua
local result, err = flow.create()
    :with_input({ text = "Hello world" })
    :func("app:tokenize")
    :func("app:translate", { args = { target_lang = "fr" } })
    :func("app:format_output")
    :run()
```



#### Named Routing


Use `:as()` to name nodes and `:to()` to route data between them. Only use `:as()` when the node needs to be referenced:

```lua
local result, err = flow.create()
    :with_input(task)
        :to("router")

    :func("app:router"):as("router")
        :to("context", "routing")
        :to("dev", "routing")

    :agent("app:context_agent"):as("context")
        :to("dev", "gathered_context")

    :agent("app:dev_agent"):as("dev")
        :to("@success")

    :run()
```

The second parameter to `:to()` is the **discriminator** — the input key at the receiving node. When a node receives multiple inputs, they are collected as a table keyed by discriminator.



#### Workflow Input and Static Data


`:with_input()` is the single primary input to the workflow. `:with_data()` creates independent static data sources:

```lua
flow.create()
    :with_input(task)
        :to("router")

    :with_data(config):as("cfg")
        :to("dev", "config")
        :to("logger", "config")

    :with_data(branch):as("branch_data")
        :to("checker", "branch")

    :func("app:router"):as("router")
        :to("dev", "task")

    :func("app:dev"):as("dev")
        :to("@success")
        :error_to("@fail")

    :run()
```

Use `:with_input()` for external data entering the workflow. Use `:with_data()` for config, constants, and reference data shared across multiple nodes. Static data uses reference optimization — the first route creates actual data, subsequent routes create lightweight references.



#### Conditional Routing


Use `:when()` after `:to()` to add conditions. Conditions evaluate against the node's output using `expr` syntax:

```lua
flow.create()
    :with_input(data)
    :func("app:classify"):as("classify")
        :to("handler_a"):when("output.category == 'a'")
        :to("handler_b"):when("output.category == 'b'")
        :to("fallback")
    :func("app:handler_a"):as("handler_a"):to("@success")
    :func("app:handler_b"):as("handler_b"):to("@success")
    :func("app:fallback"):as("fallback"):to("@success")
    :run()
```

Conditions can combine with inline transforms for more complex routing:

```lua
:func("app:decompose"):as("decompose")
    :to("@success", nil, "{passed: true, feedback: nil}"):when("len(output.items) == 0")
    :to("processor", "items", "output.items")
```

Conditional expressions support: comparisons (`output.score > 0.8`), logical operators (`output.valid && output.count > 5`), array functions (`len(output.items) > 0`, `any(output.errors, {.critical})`), string operations (`output.status contains 'success'`), and optional chaining (`output.data?.nested?.value`).



#### Workflow Terminals


Route to `@success` or `@fail` to terminate the workflow explicitly. In nested contexts (cycles, parallel), terminals create node outputs instead of workflow outputs:

```lua
:func("app:final_step"):to("@success")
:func("app:handler"):error_to("@fail")
```



#### Error Routing


Use `:error_to()` to route node errors to a handler. Errors can be routed as normal inputs to recovery nodes:

```lua
:agent("app:gpt_planner", { model = "gpt-5" }):as("gpt_planner")
    :to("consolidator", "gpt_plan")
    :error_to("consolidator", "gpt_plan")

:agent("app:claude_planner", { model = "claude-4-5-sonnet" }):as("claude_planner")
    :to("consolidator", "claude_plan")
    :error_to("consolidator", "claude_plan")

:agent("app:consolidator", {
    inputs = { required = { "gpt_plan", "claude_plan" } }
}):as("consolidator")
```

This pattern runs both planners in parallel — if one fails, its error becomes the input for the consolidator, which proceeds with whatever results are available.



### Input Merging


How nodes receive inputs depends on discriminators and whether `args` is configured.

**Without args — single default input:**

```lua
:func("source"):to("target")
-- target receives: raw content (unwrapped)
```

**Without args — single named input:**

```lua
:func("source"):to("target", "task")
-- target receives: { task = content }
```

**Without args — multiple inputs:**

```lua
:func("source1"):to("target", "data")
:func("source2"):to("target", "config")
-- target receives: { data = content1, config = content2 }
```

**With args — inputs merge into base:**

```lua
:func("app:api_client", {
    args = { base_url = "https://api.com", timeout = 5000 }
})
-- with :to("api_client", "body") from upstream
-- api_client receives: { base_url = "https://api.com", timeout = 5000, body = content }
```

<note>
Nodes with <code>args</code> cannot receive inputs with the <code>"default"</code> discriminator. Use named discriminators with <code>:to(target, "input_key")</code> instead.
</note>



### Input Transforms


Transform data before it reaches a node:

```lua
-- String transform: single expression
:func("app:step", { input_transform = "input.nested.field" })

-- Table transform: named expressions
:func("app:step", {
    input_transform = {
        task = "inputs.task",
        config = "inputs.settings",
        priority = "output.score > 0.8 ? 'high' : 'normal'"
    }
})
```

Context variables available in transforms: `input` (workflow input), `inputs` (all incoming node inputs), `output` (current node's output when routing).



#### Inline Route Transforms


The third parameter to `:to()` is an inline transform expression:

```lua
:func("source"):as("source")
    :to("target", nil, "output.data")
    :to("other", nil, "{passed: true, value: output.x}")
    :to("list", nil, "map(output.items, {.id})")
```



#### Function Node


Executes a registered `function.lua` entry:

```lua
:func("app:my_function", {
    args = { key = "value" },
    inputs = { required = { "task", "config" } },
    context = { session_id = "abc" },
    input_transform = { task = "inputs.prompt" },
    metadata = { title = "Process Data" }
})
```

| Option | Type | Description |
|--------|------|-------------|
| `args` | table | Base arguments merged with node inputs |
| `inputs` | table | Input requirements: `{ required = {...}, optional = {...} }` |
| `context` | table | Execution context passed to function |
| `input_transform` | string/table | Expression to transform inputs |
| `metadata` | table | Node metadata (e.g., `{ title = "..." }`) |

If the function returns `{ _control = { commands = [...] } }`, the orchestrator spawns a child workflow. This is how nested flows work.



#### Agent Node


Executes an agent with tool calling and optional structured exit:

```lua
:agent("app:content_writer", {
    model = "gpt-5",
    inputs = { required = { "context", "content_plan", "analysis" } },
    arena = {
        prompt = "Write content based on the provided context.",
        max_iterations = 12,
        tool_calling = "any",
        exit_schema = {
            type = "object",
            properties = {
                content = { type = "string" },
                title = { type = "string" }
            },
            required = { "content", "title" }
        }
    },
    show_tool_calls = true,
    metadata = { title = "Content Writer" }
})
```

| Option | Type | Description |
|--------|------|-------------|
| `model` | string | Override model |
| `arena.prompt` | string | System prompt |
| `arena.max_iterations` | number | Max reasoning loops (default: 32) |
| `arena.min_iterations` | number | Min iterations before exit (default: 1) |
| `arena.tool_calling` | string | `"auto"`, `"any"` (requires `exit_schema`), `"none"` (rejects `exit_schema`) |
| `arena.tools` | array | Tool registry IDs |
| `arena.exit_schema` | table | JSON schema for structured exit |
| `arena.exit_func_id` | string | Function to validate exit output |
| `arena.context` | table | Additional context |
| `inputs` | table | Input requirements |
| `show_tool_calls` | boolean | Include tool calls in output |
| `input_transform` | string/table | Transform inputs |
| `metadata` | table | Node metadata |

**Dynamic agent selection:** Pass an empty string as agent ID and resolve it via `input_transform`:

```lua
:agent("", {
    inputs = { required = { "spec", "task" } },
    input_transform = {
        agent_id = "inputs.spec.agent_id",
        task = "inputs.task"
    },
    arena = {
        prompt = "Process according to spec",
        max_iterations = 25
    }
})
```

**Exit validation:** When `exit_func_id` is set, the function validates the agent's exit output. On validation failure, the agent receives the error as observation and continues (up to `max_iterations`).



#### Cycle Node


Iterates a function or template repeatedly with persistent state:

```lua
:cycle({
    func_id = "app:content_cycle",
    max_iterations = 3,
    initial_state = {
        entry_id = entry_id,
        content_prompt = prompt,
        min_score = 8.0,
        feedback_history = {}
    }
})
```

The cycle function receives on each iteration:

```lua
{
    input = <workflow_input>,  -- only on the first iteration (iteration == 1); nil thereafter
    state = <accumulated_state>,
    last_result = <previous_iteration_output>,
    iteration = <current_iteration_number>
}
```

`input` carries the workflow input only on the first iteration and is `nil` thereafter; persist anything needed across iterations into `state`.

The function controls continuation:

```lua
function my_cycle(cycle_context)
    -- stop if approved
    if cycle_context.last_result and cycle_context.last_result.approved then
        return {
            state = cycle_context.state,
            result = cycle_context.last_result,
            continue = false
        }
    end

    -- spawn child workflow for this iteration
    -- task is read from state since cycle_context.input is nil after iteration 1
    return flow.create()
        :with_input({ task = cycle_context.state.task })
        :agent("app:worker")
        :agent("app:qa")
        :run()
end
```

| Option | Type | Description |
|--------|------|-------------|
| `func_id` | string | Iteration function (mutually exclusive with `template`) |
| `template` | FlowBuilder | Template for each iteration (mutually exclusive with `func_id`) |
| `max_iterations` | number | Maximum iterations |
| `initial_state` | table | Starting state |
| `continue_condition` | string | Expression: continue while true |

**Template-based cycle:**

```lua
:cycle({
    template = flow.template()
        :agent("app:worker")
        :func("app:validator"),
    max_iterations = 5
})
```



#### Parallel Node


Map-reduce pattern over arrays:

```lua
:parallel({
    inputs = { required = { "specs", "task" } },
    source_array_key = "specs",
    iteration_input_key = "spec",
    passthrough_keys = { "task" },
    batch_size = 10,
    on_error = "collect_errors",
    filter = "successes",
    unwrap = true,
    template = flow.template()
        :agent("app:processor", {
            inputs = { required = { "spec", "task" } },
            input_transform = {
                agent_id = "inputs.spec.agent_id",
                task = "inputs.task"
            },
            arena = {
                prompt = "Process according to spec",
                max_iterations = 25
            }
        })
        :to("@success"),
    metadata = { title = "Process Specs" }
})
```

| Option | Type | Description |
|--------|------|-------------|
| `source_array_key` | string | Input key containing the array (required) |
| `template` | FlowBuilder | Template for each item (required, must route to `@success`) |
| `iteration_input_key` | string | Input key for current item (default: `"default"`) |
| `batch_size` | number | Items per parallel batch (default: 1 = sequential) |
| `on_error` | string | `"collect_errors"` (default) or `"fail_fast"` |
| `filter` | string | `"all"` (default), `"successes"`, `"failures"` |
| `unwrap` | boolean | Return raw results instead of wrapped metadata (default: false) |
| `passthrough_keys` | array | Input keys forwarded to every iteration |

**Passthrough keys** provide shared context (config, task description) to every iteration without duplicating data in the source array:

```lua
:with_data(file_list):as("files"):to("processor", "files")
:with_data("secret"):as("api_key"):to("processor", "api_key")

:parallel({
    inputs = { required = { "files", "api_key" } },
    source_array_key = "files",
    iteration_input_key = "filename",
    passthrough_keys = { "api_key" },
    template = flow.template()
        :func("app:upload", {
            inputs = { required = { "filename", "api_key" } }
        })
        :to("@success")
}):as("processor")
```



#### Signal Node


Pauses execution until an external signal arrives. Use for human approvals, external events, or staged workflows:

```lua
:signal({
    signal_id = "approval",
    inputs = { required = { "draft" } },
    metadata = { title = "Wait for approval" }
})
```

| Option | Type | Description |
|--------|------|-------------|
| `signal_id` | string | Signal name matched against `client:signal()`. If empty or omitted, a UUID v7 is generated at runtime |
| `inputs` | table | Input requirements |
| `input_transform` | string/table | Transform inputs before the node receives them |
| `metadata` | table | Node metadata |

Send the signal from outside the workflow using the client API (see `client:signal()` below).



##### Behavior


The node yields with `wait_for_signal = true` and persists that yield in the workflow state. The orchestrator resumes the node when a matching `NODE_SIGNAL` commit arrives.

- The signal is satisfied by any non-`nil` payload. `false`, `0`, `""`, and `{}` all satisfy the yield; only `nil` keeps it pending.
- A signal yield blocks `COMPLETE_WORKFLOW` but does not block other pending nodes — parallel branches continue to execute while one branch waits.
- Signals can be pre-queued before `:start()`: if a matching `NODE_SIGNAL` commit arrives before the signal node reaches the yield, it is delivered the moment the yield is tracked.
- Only one signal satisfies each yield. If a second signal with the same `signal_id` arrives before the yield is satisfied, it overwrites the first.
- When multiple signal yields share the same `signal_id`, the first matching yield receives the data.
- If the `signal_id` field is absent, matching falls back to the node's discriminator.
- Delivered signal data is passed to the node's output as the signal payload.



##### Durability and recovery


The signal yield is part of the workflow state, persisted through the same outbox mechanism as every other command. If the orchestrator process is killed while waiting:

- The pending yield is restored on restart.
- Signals delivered during the outage are queued and applied when the state reloads.
- Compound pipelines (`func → signal → signal → func`) recover step-by-step — each signal can be delivered across a separate restart.

Orphaned signal yields (yields whose parent process exited without completion) are cleaned up by the workflow state's process exit handler.



##### Pipeline patterns


Signal nodes participate in any topology:

```lua
-- Human-in-the-loop approval between two functions
flow.create()
    :func("app:draft")
    :signal({ signal_id = "approve_draft" })
    :func("app:publish")
    :run()

-- Two parallel approvals that must both arrive before release
flow.create()
    :with_input({ doc = "release-notes" })
        :as("trigger")
        :to("legal", "doc")
        :to("finance", "doc")

    :signal({ signal_id = "legal_ok", inputs = { required = { "doc" } } })
        :as("legal")
        :to("gate", "legal")

    :signal({ signal_id = "finance_ok", inputs = { required = { "doc" } } })
        :as("finance")
        :to("gate", "finance")

    :join({ inputs = { required = { "legal", "finance" } } })
        :as("gate")
        :to("release")

    :func("app:release"):as("release"):to("@success")
    :run()
```

Signal data is exposed as the node output, so downstream nodes receive whatever was passed to `client:signal()`.



#### Join Node


Collects multiple inputs before proceeding:

```lua
:join({
    inputs = { required = { "source1", "source2" } },
    output_mode = "object",
    ignored_keys = { "triggered" }
})
```

| Option | Type | Description |
|--------|------|-------------|
| `output_mode` | string | `"object"` (default) or `"array"` (arrival order) |
| `ignored_keys` | array | Input keys excluded from output |
| `inputs` | table | Input requirements |



### Templates


Templates define reusable sub-workflows. Use `flow.template()` to create, `:use()` to inline:

```lua
local preprocessor = flow.template()
    :func("app:clean")
    :func("app:tokenize")

flow.create()
    :with_input(data)
    :use(preprocessor)
    :func("app:process")
    :run()
```

Templates inline their operations into the parent flow at compile time.



### Nested Workflows


Functions used in cycles and parallel nodes can spawn child workflows by returning `flow.create():run()`:

```lua
function my_processor(input)
    return flow.create()
        :with_input(input)
        :func("app:step_a")
        :func("app:step_b")
        :run()
end
```

When `:run()` executes inside an existing dataflow context, it returns `{ _control = { commands = [...] } }` instead of executing directly. The orchestrator handles the child workflow through the yield mechanism.

<note>
Functions that participate in dataflow composition <strong>must</strong> return <code>flow.create():run()</code>. Functions returning anything else cannot spawn child workflows.
</note>



### Synchronous vs Asynchronous


`:run()` blocks until the workflow completes and returns output:

```lua
local result, err = flow.create()
    :with_input({ text = "hello" })
    :func("app:process")
    :run()
```

`:start()` returns immediately with a workflow ID:

```lua
local dataflow_id, err = flow.create()
    :with_input({ text = "hello" })
    :func("app:process")
    :start()
```

`:start()` cannot be used in nested contexts.



### Client API


For programmatic workflow management:

```yaml
imports:
  client: userspace.dataflow:client
```

```lua
local client = require("client")

local c, err = client.new()
```

| Method | Description |
|--------|-------------|
| `client.new()` | Create client (requires security actor) |
| `:create_workflow(commands, options?)` | Create workflow, returns `dataflow_id` |
| `:execute(dataflow_id, options?)` | Run synchronously, returns result |
| `:start(dataflow_id, options?)` | Run asynchronously, returns `dataflow_id` |
| `:output(dataflow_id)` | Fetch workflow outputs |
| `:get_status(dataflow_id)` | Get current status |
| `:cancel(dataflow_id, timeout?)` | Gracefully cancel (default: 30s) |
| `:terminate(dataflow_id)` | Force terminate |
| `:signal(dataflow_id, signal_id, data?)` | Deliver an external signal to a waiting signal node |



### Workflow Status


| Status | Description |
|--------|-------------|
| `template` | Node is a template instance |
| `pending` | Waiting for inputs |
| `ready` | Inputs collected, ready to execute |
| `running` | Actively executing |
| `paused` | Yielded, waiting for child workflow |
| `completed` | Finished successfully |
| `failed` | Failed |
| `cancelled` | User cancelled |
| `skipped` | Conditional branch not taken |
| `terminated` | Force terminated |



### Metadata


```lua
flow.create()
    :with_title("Document Processing Pipeline")
    :with_metadata({ source = "api", priority = "high" })
    :func("app:process", { metadata = { title = "Process Document" } })
    :run()
```

Title defaults to "Flow Builder Workflow" if not provided.



### Validation Rules


The compiler validates workflows at compile time:

- All `:as(name)` names must be unique
- All `:to()` and `:error_to()` targets must reference existing names (except `@success`, `@fail`)
- Graph must be acyclic
- All nodes must have incoming routes (from another node, workflow input, or static data)
- `:cycle()` requires `func_id` or `template` (not both)
- `:parallel()` requires `source_array_key` and `template`
- At least one path must lead to `@success` or have auto-output
- `:when()` only follows `:to()` or `:error_to()` from nodes (not static data)
- Nodes with `args` cannot receive inputs with `"default"` discriminator



### Expression Reference


Expressions use the `expr` module syntax, available in `:when()` conditions and `input_transform` values.

**Operators:** `+`, `-`, `*`, `/`, `%`, `**`, `==`, `!=`, `<`, `<=`, `>`, `>=`, `&&`, `||`, `!`, `contains`, `startsWith`, `endsWith`

**Array functions:** `all()`, `any()`, `none()`, `one()`, `filter()`, `map()`, `count()`, `len()`, `first()`, `last()`

**Math functions:** `max()`, `min()`, `abs()`, `ceil()`, `floor()`, `round()`, `sqrt()`, `pow()`

**String functions:** `len()`, `upper()`, `lower()`, `trim()`, `split()`, `join()`

**Type functions:** `type()`, `int()`, `float()`, `string()`

**Literals:** numbers, strings, booleans (`true`/`false`), null (`nil`), arrays (`[1, 2, 3]`), objects (`{key: value}`)

**Ternary:** `output.age >= 18 ? output.verified : false`

**Optional chaining:** `output.data?.nested?.value`



### Error Handling


Both `:run()` and `:start()` follow standard Lua error conventions:

- Success: `data, nil` (run) or `dataflow_id, nil` (start)
- Failure: `nil, error_message`

Error categories: compilation errors, client errors, workflow creation errors, execution errors, and workflow failures.



### See Also


- [Agents](framework/agents.md) - Agent framework used by agent nodes
- [LLM](framework/llm.md) - LLM module
- [Framework Overview](framework/overview.md) - Framework module usage



---

# "Relay"

## Relay


The `wippy/relay` module routes WebSocket connections through a central hub and per-user hubs. User hubs manage client connections and dispatch messages to prefixed plugins.

This page is a partial integration recipe and protocol reference, not a standalone WebSocket application. The setup and plugin blocks assume an existing Wippy project, a real security scope at the configured `user_security_scope`, and an HTTP WebSocket endpoint connected to the relay as described in [WebSocket Relay](http/websocket-relay.md). Protocol payloads and lifecycle blocks are reference shapes.



### Architecture


```
Central Hub
├── User Hub (alice)
│   ├── Plugin: session_
│   ├── Plugin: ai_
│   ├── WebSocket Client 1
│   └── WebSocket Client 2
├── User Hub (bob)
│   ├── Plugin: session_
│   └── WebSocket Client 1
└── ...
```

The central hub runs as a service. When a WebSocket client connects, it finds or creates a hub for that user. The user hub manages the connection lifecycle and routes messages by command prefix.



### Setup


Add the module to your project:

```bash
wippy add wippy/relay
wippy install
```

Declare the dependency with required parameters:

```yaml
version: "1.0"
namespace: app

entries:
  - name: os_env
    kind: env.storage.os

  - name: processes
    kind: process.host
    lifecycle:
      auto_start: true

  - name: dep.relay
    kind: ns.dependency
    component: wippy/relay
    version: "*"
    parameters:
      - name: application_host
        value: app:processes
      - name: env_storage
        value: app:os_env
      - name: user_security_scope
        value: app.security:user_scope
```



#### Configuration Parameters


| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `application_host` | yes | — | Process host for relay processes |
| `env_storage` | no | internal | Environment variable storage |
| `user_security_scope` | yes | — | Security scope for user hubs |
| `max_connections_per_user` | no | `5` | WebSocket connections per user |
| `queue_multiplier` | no | `100` | Message queue = connections × multiplier |
| `user_hub_inactivity_timeout` | no | `7200s` | Idle time before hub cleanup |



### Client Connection Flow


1. WebSocket client connects with `user_id` in metadata
2. Central hub validates the connection and checks per-user limits
3. Central hub creates or reuses a user hub for the user
4. User hub sends a `welcome` message to the client:

```json
{
    "user_id": "alice",
    "client_count": 1,
    "plugins": [
        { "prefix": "session_", "process_id": "...", "status": "running" },
        { "prefix": "ai_", "process_id": "...", "status": "pending" }
    ]
}
```

Plugin `status` can be `"not_started"` (registered but never spawned), `"pending"` (spawn in progress), `"running"`, `"failed"`, or `"stopped"`.



### Message Routing


Clients send JSON messages with a `type` field. The user hub matches the type prefix against registered plugins and routes the message:

```json
{ "type": "session_get_state", "data": { "key": "value" } }
```

The `session_` prefix selects the session plugin. The hub removes the prefix and sends the message to the plugin process, using the remaining type as the topic:

```lua
-- process topic: "get_state"
-- payload:
{
    conn_pid = client_pid,
    type = "session_get_state",  -- original full type preserved
    data = { key = "value" },
    request_id = "...",
    session_id = "..."
}
```

Plugins respond by sending messages back to `conn_pid`.



### Plugins


Plugins are `process.lua` entries with `meta.type: relay.plugin`:

```yaml
entries:
  - name: session_plugin
    kind: process.lua
    meta:
      type: relay.plugin
      command_prefix: session_
      auto_start: true
    source: file://session_plugin.lua
    modules: [json, time, logger]
    method: run
```



#### Plugin Metadata


| Field | Type | Description |
|-------|------|-------------|
| `meta.type` | string | Must be `relay.plugin` |
| `meta.command_prefix` | string | Message type prefix this plugin handles |
| `meta.auto_start` | boolean | Start when user hub initializes |
| `meta.default_host` | string | Override process host |



#### Plugin Lifecycle


The user hub spawns each plugin with these startup arguments:

```lua
function run(args)
    local user_id = args.user_id
    local user_metadata = args.user_metadata
    local user_hub_pid = args.user_hub_pid
    local config = args.config
end
```

The `session_` plugin receives lifecycle messages:

| Message | When |
|---------|------|
| `"resume"` | First client connects to user hub |
| `"shutdown"` | Last client disconnects from user hub |

Plugins get 1 automatic restart on crash. After a second crash, the plugin is marked as `"failed"` and not restarted.



#### Plugin Implementation


Plugins receive messages through their process inbox. Each message has a topic derived from the command type and a payload containing the original message data and `conn_pid` for responses.

```lua
local json = require("json")

local function handle_message(topic, payload)
    if topic == "get_state" then
        if not payload.conn_pid then
            return nil, "Relay message is missing conn_pid"
        end

        local encoded, encode_err = json.encode({
            type = "session_state",
            data = { status = "active" }
        })
        if encode_err then
            return nil, encode_err
        end

        local sent, send_err = process.send(payload.conn_pid, "ws.message", encoded)
        if not sent then
            return nil, send_err or "Relay response was not sent"
        end
    end

    return true
end

local function run(args)
    local user_id = args.user_id
    local inbox = process.inbox()
    local events = process.events()

    while true do
        local result = channel.select({
            inbox:case_receive(),
            events:case_receive()
        })
        if not result.ok then break end

        if result.channel == inbox then
            local msg = result.value
            local topic = msg:topic()
            local payload = msg:payload():data()

            if topic == "resume" then
                -- first client connected
            elseif topic == "shutdown" then
                -- last client disconnected
            else
                local ok, err = handle_message(topic, payload)
                if not ok then
                    error("Failed to handle relay message: " .. tostring(err))
                end
            end
        elseif result.channel == events then
            local event = result.value
            if event.kind == process.event.CANCEL then
                break
            end
        end
    end
end

return { run = run }
```



### Error Handling


The relay reports client errors using these codes:

| Error Code | Description |
|------------|-------------|
| `max_connections_reached` | User at connection limit |
| `missing_user_id` | No user_id in connection metadata |
| `hub_creation_failed` | Failed to spawn user hub |
| `invalid_json` | Message decode error |
| `unknown_command` | Message missing type field |
| `plugin_not_found` | No plugin matches the command prefix |
| `plugin_failed` | Plugin unavailable or crashed |



#### User Hub Creation


The first client connection for a user creates that user's hub. The hub runs with the user's security actor and scope.



#### Garbage Collection


The central hub periodically checks for inactive user hubs. A hub with no connected clients for longer than `user_hub_inactivity_timeout` (default 2 hours) is gracefully terminated with a 10-second cancel timeout.

The GC check interval is automatically derived: `inactivity_timeout / 2.5`.



#### Security


The central hub runs under its own security group (`wippy.relay.security:root`) with full access. Each user hub spawns with the configured `user_security_scope`, isolating user-level operations.



### Internal Topics


| Topic | Direction | Description |
|-------|-----------|-------------|
| `ws.join` | Client → Central/User Hub | Connection request |
| `ws.leave` | Client → Central/User Hub | Disconnection |
| `ws.message` | Client → User Hub | WebSocket message |
| `ws.cancel` | Central → User Hub | Graceful shutdown |
| `ws.control` | Central → Client | Redirects the client connection's target PID to its user hub |
| `hub.activity_update` | User Hub → Central | Client count update |



### See Also


- [WebSocket Relay](../http/websocket-relay.md) — HTTP WebSocket endpoint configuration
- [Process Model](concepts/process-model.md) — Process lifecycle and messaging
- [Security](system/security.md) — Security actors and scopes
- [Framework Overview](framework/overview.md) — Install and import framework modules



---

# "Views"

## Views


The `wippy/views` module defines pages and components, manages their resources, and maps environment variables into rendered output. It supports two page models:

- **Jet template pages** (`kind: template.jet`) render HTML on the server after assembling the page's data and resources. See [Template Pages](#template-pages).
- **Registry-entry frontends** (`kind: registry.entry`) describe micro frontend applications (`view.page`) and reusable web components (`view.component`) served from a CDN or static mount. The registry entry contains routing and deployment policy. Frontend-owned metadata comes from the package's generated `wippy-meta.json`, with explicit registry fields taking precedence. See [Component Pages](#component-pages) and [View Components](#view-components).

This page is a registry and HTTP API reference. Its YAML, HTML, and JSON blocks are independent reference snippets, not one runnable project. Before adapting them, provide the `http.router`, environment storage, and HTTP service referenced by the dependency, plus any template sets, functions, resources, or frontend bundles named by the selected example.



### Setup


Add the module to your project:

```bash
wippy add wippy/views
wippy install
```

Declare the dependency:

```yaml
version: "1.0"
namespace: app

entries:
  - name: dep.views
    kind: ns.dependency
    component: wippy/views
    version: "*"
    parameters:
      - name: api_router
        value: app:api.public
      - name: env_storage
        value: app:env.storage
```

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `api_router` | yes | — | HTTP router for view API endpoints |
| `env_storage` | yes | — | Environment storage backing the `PUBLIC_API_URL` variable |
| `server` | no | `app:gateway` | HTTP service the self-mounted [Web Fragments gateway](#web-fragments-gateway) router (`/@fragment`) binds to. Override only if your `http.service` id differs from `app:gateway`. |



### Template Pages


> **Server-rendered model.** `wippy/views` assembles template data and resources on the server, then renders the final HTML with Jet. The response is plain HTML and does not use an iframe proxy or client-side micro frontend. For external SPAs and components, see [Component Pages](#component-pages).

Template pages render server-side using Jet templates. Data is injected via `data.set`, `data.data_func`, and `data.resources` (server-side resource injection):

```yaml
entries:
  - name: contact_page
    kind: template.jet
    meta:
      type: view.page
      name: contact
      title: Contact Us
      icon: mail
      order: 5
      group: main
      group_icon: layout-grid
      group_order: 1
      announced: true
      secure: false
    data:
      set: app.templates:default
      data_func: app:contact_data
      resources:
        - contact_styles
```



#### Page Metadata


| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `meta.type` | string | — | Must be `view.page` |
| `meta.name` | string | entry name | Page identifier |
| `meta.title` | string | — | Display title |
| `meta.icon` | string | — | Icon identifier |
| `meta.order` | number | `9999` | Sort order within group |
| `meta.group` | string | — | Group category |
| `meta.group_icon` | string | — | Group icon |
| `meta.group_order` | number | `9999` | Group sort order |
| `meta.group_placement` | string | `"default"` | Placement: `"default"`, `"sidebar"` |
| `meta.secure` | boolean | `false` | Requires authentication |
| `meta.public` | boolean | `false` | Makes the page announced when true; it does not bypass `meta.secure` access control |
| `meta.announced` | boolean | `false` | Show in navigation. The current resolver uses `announced or public`, so `public: true` overrides an explicit `announced: false` |
| `meta.inline` | boolean | `false` | Returned by `/pages/list` as the numeric `hidden` marker |
| `meta.content_type` | string | `text/html` | Response MIME type |
| `meta.parent` | string | — | Parent page ID |



#### Template Data


| Field | Description |
|-------|-------------|
| `data.set` | Required template set registry ID |
| `data.data_func` | Function ID that returns page data |
| `data.resources` | Array of resource registry IDs |

The `data_func` receives `{ params, query }` and returns a table that becomes the `data` context in the template. Omitting `data.data_func`, or returning `nil` from it, produces an empty table. A configured function that cannot be resolved, or a function that returns an error, aborts rendering.



#### Rendering Pipeline


1. Load page from registry
2. Check access (security)
3. Call `data_func` if defined
4. Collect resources: globals + template set resources + page-specific resources
5. Load environment variables (mapping failures are logged and produce an empty `env` table)
6. Render Jet template with context: `{ data, resources, query_params, route_params, env }`



### Component Pages


Component pages point to external single-page applications (SPAs or micro frontends) that the Web Host loads with its configured page engine: an iframe by default, or a Web Fragment when enabled. Their registry entries define URL serving, access control, the mount route, and per-page configuration overrides:

> **Required registry shape:** component pages are `kind: registry.entry` with `meta.type: view.page`. `view.page` is never a `kind` value. Proxy deployment overrides live at `meta.proxy`, not `data.proxy`.

```yaml
entries:
  - name: dashboard
    kind: registry.entry
    meta:
      type: view.page
      name: dashboard
      title: Dashboard
      icon: chart-bar
      url: /app
      base_path: app/dashboard
      entry_point: index.html
      mountRoute: /dashboard/:part(.*)*
      secure: true
      announced: true
      config_overrides:
        customization:
          cssVariables:
            "--p-primary": "#7c9ed9"
```

The API returns a component descriptor with the resolved base URL. The Web Host then renders the SPA with the selected iframe or Web Fragment engine. Iframe pages apply the proxy injections requested by the frontend package; the Fragment gateway uses its own fixed transformation and Host-CSS injection path.



#### Component Page Fields


| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `meta.name` | string | — | Page name. Keep it in registry YAML because `/pages/list` does not load bundled metadata |
| `meta.title` | string | — | Display title. Keep it in registry YAML because `/pages/list` sorts raw registry titles |
| `meta.url` | string | — | Base URL prefix where the bundle is mounted (CDN origin or `http.static` path) |
| `meta.base_path` | string | — | Subdirectory within the static mount |
| `meta.entry_point` | string | bundled `wippy.path`, then `index.html` | HTML entry file; combined as `<url>/<base_path>/<entry_point>` |
| `meta.mountRoute` | string | — | Claims a URL path in the host router; only the catch-all form `/:part(.*)*` (root) or `/<literal-prefix>/:part(.*)*` is allowed — arbitrary Vue Router patterns are rejected (HTTP 500). See [view-page.md](../frontend/frontend-registry/view-page.md) / [dynamic-routing.md](../frontend/frontend-registry/dynamic-routing.md) |
| `meta.announced` | boolean | `announced or public or false` | Show in navigation and `/pages/list`; `public: true` wins over an explicit `announced: false` |
| `meta.secure` | boolean | `false` | Requires authentication |
| `meta.render_engine` | string | bundled `wippy.renderEngine` | Per-page engine preference: `auto`, `iframe`, or `fragment` |
| `meta.config_overrides` | object | — | Per-page AppConfig overrides (camelCase), deep-merged over the bundled defaults |

For component pages, `wippy/views` requests `wippy-meta.json` from the resolved bundle root when building the content descriptor. Registry YAML wins field by field; bundled metadata fills omitted frontend-owned fields such as package version, entry path, proxy settings, render engine, and config overrides. If the metadata file cannot be used, the module falls back to the legacy YAML descriptor. Keep `meta.name` and `meta.title` in registry YAML: `/pages/list` consumes raw registry fields without fetching the bundle metadata, and missing titles can break same-order sorting. `config_overrides` supports `customization`, `axiosDefaults`, `routePrefix`, `apiRoutes`, and `themeMode`.



#### Proxy Injection


For SPA pages, configure proxy injection in the frontend package's camelCase `wippy.proxy.injections` block. The build records this configuration in `wippy-meta.json`. A deployment can override it with a camelCase `proxy:` block under the registry entry's `meta:` field, using the same shape and `injections` wrapper as the package's `wippy.proxy` block. The host deep-merges the deployment value over the bundled configuration, with YAML values taking precedence at each nested key. There is no snake_case form or casing normalization. `config_overrides` deep-merges only `customization`, `axiosDefaults`, `routePrefix`, `apiRoutes`, and `themeMode`; it does not affect `proxy.injections`. See [Micro Frontend Apps (view.page)](../frontend/frontend-registry/view-page.md) and [CSS Injection](../frontend/web-host/css-injection.md).

Deployment override example:

```yaml
entries:
  - name: dashboard
    kind: registry.entry
    meta:
      type: view.page
      proxy:
        injections:
          css:
            themeConfig: true
            customCss: true
            customVariables: true
          tailwindConfig: false
```



### View Components


View components are reusable custom elements (web components or micro frontends) that the Web Host discovers and registers. They are not pages and do not have navigation entries. As with component pages, their registry entries define routing and deployment policy:

```yaml
entries:
  - name: reaction-bar
    kind: registry.entry
    meta:
      type: view.component
      name: reaction-bar
      tag_name: example-reaction-bar
      announced: true
      auto_register: true
      secure: false
      url: /app/wc/reaction-bar
      entry_point: index.js
```

Components use `meta.type: view.component` instead of `view.page`. YAML can override `tag_name`, `entry_point`, `props`, and `events`; otherwise those frontend-owned fields come from `wippy-meta.json`, with `index.js` as the final entry-point fallback. Components do not use the page iframe's proxy-injection block. Shadow-DOM platform CSS is requested by the component implementation through `hostCssKeys`. See [Web Components (view.component)](../frontend/frontend-registry/view-component.md) and [CSS Injection](../frontend/web-host/css-injection.md).



### Resources


Resources are CSS, JS, and font files associated with pages:

```yaml
entries:
  - name: global_styles
    kind: registry.entry
    meta:
      type: view.resource
      name: Global Styles
      resource_type: style
      global: true
      order: 1
      url: https://cdn.example.com/global.css

  - name: app_script
    kind: registry.entry
    meta:
      type: view.resource
      name: App Script
      resource_type: script
      template_set: app.templates:default
      order: 10
      url: https://cdn.example.com/app.js
      defer: true
```



#### Resource Fields


| Field | Type | Description |
|-------|------|-------------|
| `meta.type` | string | Must be `view.resource` |
| `meta.resource_type` | string | Free-form (defaults to `"other"`); common values are `"style"`, `"script"`, `"font"` |
| `meta.order` | number | Sort order within type |
| `meta.global` | boolean | Applied to all pages |
| `meta.template_set` | string | Specific to a template set |
| `meta.url` | string | Resource URL |
| `meta.integrity` | string | SRI hash |
| `meta.crossorigin` | string | `"anonymous"` or `"use-credentials"` |
| `meta.media` | string | CSS media query |
| `meta.defer` | boolean | Deferred script loading |
| `meta.async` | boolean | Async script loading |



#### Resource Collection


Resources are selected cumulatively from three sources:

1. **Global resources** — `global: true`, applied to all pages
2. **Template set resources** — matched by `template_set` ID
3. **Page resources** — listed in `data.resources` array

After collection, resources are grouped by `resource_type` and each group is sorted by `order`. The three source layers do not establish a separate output order.



### Environment Variable Mapping


The env loader maps environment variables to template context keys through a priority-based system.



#### Defining Mappings


```yaml
entries:
  - name: app_env
    kind: registry.entry
    meta:
      type: view.env_mapping
      priority: 20
    data:
      mappings:
        api_endpoint: API_BASE_URL
        app_title: APP_NAME
        debug_mode: DEBUG_ENABLED
```

Each mapping entry associates context keys (used in templates as `env.api_endpoint`) with environment variable names.



#### Priority System


| Range | Category | Description |
|-------|----------|-------------|
| 0–9 | Framework defaults | Built-in framework mappings |
| 10–19 | System overrides | System-level configuration |
| 20–29 | Application mappings | Application-specific mappings |
| 30–100 | Environment overrides | Runtime overrides |

Higher priority wins when multiple mappings define the same context key. Do not define the same key more than once at a single priority: equal-priority ordering is not defined.



#### Using in Templates


Resolved environment values are available in the `env` context object:

```html
<script>
    window.API_URL = "{{ env.api_endpoint }}";
    document.title = "{{ env.app_title }}";
</script>
```



### HTTP API Endpoints


The views module registers these endpoints on the configured router:

| Method | Path | Description |
|--------|------|-------------|
| GET | `/pages/list` | List accessible, announced pages |
| GET | `/components/list` | List accessible, announced view components |
| GET | `/pages/content/{id}` | Render page or return component descriptor |
| GET | `/pages/public/{id}` | Get component base URL |
| GET | `/components/by-tag/{tag}` | Resolve a custom-element tag name to its `view.component` descriptor (used by host `loadByTagName`) |
| GET | `/pages/routes` | Return the `mountRoute` → `pageId` map; HTTP 500 on invalid or duplicate `mountRoute`. Not filtered by `announced` (hidden pages still need URL resolution); access control applies to secure pages |



#### Render Response


For template pages, returns rendered HTML with the page's `content_type`.

For component pages, returns a descriptor:

```json
{
    "name": "dashboard",
    "version": "1.0.0",
    "specification": "wippy-component-1.0",
    "title": "Dashboard",
    "baseUrl": "https://cdn.example.com/dashboard/",
    "wippy": {
        "type": "page",
        "path": "index.html",
        "proxy": {
            "enabled": true,
            "injections": {
                "css": { "themeConfig": true, "iframe": true },
                "tailwindConfig": false,
                "resizeObserver": true,
                "preventLinkClicks": true
            }
        }
    }
}
```

The `css` injection flags are `themeConfig`, `iframe`, `primevue`, `markdown`, `customCss`, and `customVariables`. There is no `fonts` flag — Google Fonts are delivered via `theming.global.customCSS` (an `@import` rule), injected by `customCss`.



### Web Fragments Gateway


When the Web Host renders a page with the [fragment render engine](../frontend/web-host/render-engines.md), the page is mounted as `<web-fragment src="/@fragment/{id}/">`. `wippy/views` serves that reframing contract through a dedicated gateway endpoint at **`/@fragment/{id}/{path...}`**.

Unlike the view API, which mounts on the consumer's `api_router`, the gateway declares its own top-level `/@fragment` `http.router`, making it CDN-cache-routable and independent of `token_auth`. Authentication is handled client-side through the injected fragment proxy's handshake with the host. Consumers do not need a router entry or `fragment_router` parameter, and applications using the iframe engine do not require fragment configuration.

The self-mounted router binds to a `server` requirement that defaults to `app:gateway`. If the application's `http.service` entry has another ID, set the `wippy/views` `server` parameter to that entry:

```yaml
entries:
  - name: dep.views
    kind: ns.dependency
    component: wippy/views
    version: "*"
    parameters:
      - name: api_router
        value: app:api.public
      - name: env_storage
        value: app:env.storage
      - name: server                 # optional — only if your http.service id ≠ app:gateway
        value: app:my_http_service
```

> **Fragment availability.** A page that sets `wippy.renderEngine: "fragment"` in an otherwise iframe-based deployment uses a runtime capability probe. If the gateway or `proxy-fragment.js` is unavailable, the page remains on the iframe engine without reporting an error. The global `render_engine: fragment` setting does not perform this probe.



#### Reframing Contract


The gateway answers the same `/@fragment/{id}/` URL three ways, discriminated by the request's `Sec-Fetch-Dest` header and subpath:

| Request | Response |
|---------|----------|
| Realm iframe load (`Sec-Fetch-Dest: iframe`) | A tiny **reframed stub** carrying the host import map + `loading.js` + `proxy-fragment.js`. |
| Document fetch (empty subpath) | The page's app HTML, transformed for the realm: remove the first import map and development placeholder, rewrite relative `href="./…"` and `src="./…"` attributes, inject Host CSS links, and rename `<html>`/`<head>`/`<body>` to `<wf-*>`. The gateway does not inject `<base>`. |
| Asset (non-empty subpath) | Proxied to the page's real `base_url` + subpath. |

Responses carry `Cache-Control`: the stub is shared-cacheable (`public, max-age=300`); the access-gated document and assets are `private` (they pass a per-user `can_access` check, so a shared cache would leak across users). Runtime errors are explicit HTTP responses — `400 Missing fragment id`, `404 Fragment page not found`, `401 Access denied`, `502 Fragment document fetch failed: … (url: …)`.

The FE selects the engine and mounts the fragment — see [Render Engines](../frontend/web-host/render-engines.md).



### Access Control


Pages with `secure: true` require authentication. The page registry checks `security.can("view", "page:<page_id>")` against the current actor and scope.

Non-secure pages are always accessible. The `announced` flag controls visibility in navigation listings without affecting access.



### ID Qualification


Relative IDs in page definitions are qualified with the entry's namespace:

```yaml


## In namespace "app"

data:
  data_func: my_data_func       # resolves to app:my_data_func
  set: templates:default         # stays as templates:default (already qualified)
  resources:
    - page_styles                # resolves to app:page_styles
```



### See Also


- [Facade](./facade.md) — Frontend facade and navigation sidebar
- [Template](../system/template.md) — Jet template engine
- [Security](../system/security.md) — Security actors and access control
- [Environment](../system/env.md) — Environment variable storage
- [Framework Overview](./overview.md) — Framework module usage
- [Micro Frontend Apps (`view.page`)](../frontend/frontend-registry/view-page.md) — Full `view.page` metadata and proxy injection reference
- [Web Components (`view.component`)](../frontend/frontend-registry/view-component.md) — Full `view.component` autoload and props reference
- [Render Engines](../frontend/web-host/render-engines.md) — Iframe and Web Fragment page rendering



---

# "Facade"

## Facade


The `wippy/facade` module serves a page that loads and configures the Wippy Web Host from a CDN. The page loads `module.js` for the default compatibility shell or `managed-layout.js` for managed mode, handles authentication, and passes backend configuration to the frontend. The loaded module controls the page and its browser history.

For isolated or partial-page integrations, the host can still be embedded manually through `iframe.html` and a `SetConfig` postMessage handshake. The facade itself does not use this delivery mode.

This page is a partial deployment recipe and configuration reference. The setup block can be adapted to an existing Wippy project, while the theming, config-response, navigation, and publishing blocks are independent reference snippets. Provide any login page, filesystem entries, static assets, and frontend view entries that an adapted snippet names. For a complete runnable facade project, follow [Serve the Web Host with Facade](../tutorials/facade.md).



### Setup


Add the module to your project:

```bash
wippy add wippy/facade
wippy install
```

Declare the dependency:

```yaml
version: "1.0"
namespace: app

entries:
  - name: gateway
    kind: http.service
    addr: :8090
    lifecycle:
      auto_start: true

  - name: api
    kind: http.router
    meta:
      server: app:gateway
    prefix: /api/public

  - name: dep.facade
    kind: ns.dependency
    component: wippy/facade
    version: "*"
    parameters:
      - name: server
        value: app:gateway
      - name: router
        value: app:api
```



#### Configuration Parameters


| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `server` | yes | — | HTTP server for static and page serving |
| `router` | yes | — | Public API router for config endpoint |
| `fe_facade_url` | no | `https://web-host.wippy.ai/webcomponents-1.0.56` | Base CDN URL for the frontend bundle |
| `fe_entry_path` | no | `/iframe.html` | Path to the **iframe** entry on the bundle, used by the iframe embedding mode. The current facade's page loads the JS-module entry (`module.js`/`managed-layout.js`) instead; this iframe path remains available for manual, facade-less iframe embeddings. |
| `fe_mode` | no | `compat` | Which shell the facade page loads: `compat` loads `module.js` (the default chat shell); `managed` loads `managed-layout.js` (opt-in declarative multi-panel layout). Surfaced on `/facade/config` as `mode`/`module_file`. |
| `host_config_layout` | no | `{}` | JSON layout config emitted as `hostConfig.layout`; consumed by the **managed** shell only. |
| `render_engine` | no | `iframe` | Page render engine, emitted as `hostConfig.renderEngine`. See [Render engine](#render-engine). |
| `login_path` | no | `/login.html` | Path on the page's origin to redirect unauthenticated users to; works with `login_redirect_param`. |
| `login_redirect_param` | no | `""` (off) | Query-parameter name to append the post-login return URL to when redirecting to `login_path`. Empty disables the return-URL append. |
| `extra_scripts` | no | `[]` | JSON array of extra script URLs the facade page loads; emitted on `/facade/config` as `extraScripts`. |



#### Render Engine


`render_engine` selects the [page render engine](../frontend/web-host/render-engines.md) for the whole deployment. It is emitted as `hostConfig.renderEngine` and read by the Web Host at its single page-render fork.

| Value | Effect |
|-------|--------|
| `iframe` _(default)_ | Pages render as srcdoc iframes — the main (default) engine. |
| `fragment` | Pages render as [Web Fragments](../frontend/web-host/render-engines.md) (a `reframed` realm reflected into a shadow root). |

Only the exact string `fragment` opts in; **any other value — including a typo like `fragmnet` — is clamped to `iframe`** (fail-safe, but silent). Enabling the fragment engine also requires the [`/@fragment` gateway](./views.md#web-fragments-gateway), which is self-provided by `wippy/views` (≥ 0.5.9) — no consumer wiring. A page can override the deployment default per-page with [`wippy.renderEngine`](../frontend/frontend-registry/view-page.md#render-engine).



#### App Identity


| Parameter | Default | Description |
|-----------|---------|-------------|
| `app_title` | `Wippy` | Title shown in sidebar |
| `app_name` | `Wippy AI` | Full application name |
| `app_icon` | `wippy:logo` | Iconify icon reference |



#### Feature Flags


| Parameter | Default | Description |
|-----------|---------|-------------|
| `hide_nav_bar` | `false` | Hide the left navigation sidebar |
| `disable_right_panel` | `false` | Disable the right sidebar panel |
| `start_nav_open` | `false` | Navigation drawer open by default |
| `show_admin` | `true` | Show admin panel toggle |
| `allow_select_model` | `false` | Allow user to select LLM model |
| `session_type` | `non-persistent` | Web Host session policy: `cookie` stores a secondary token cookie; any other value is normalized to `non-persistent` and does not use that cookie. |
| `history_mode` | `hash` | Browser history mode: `hash` or `browser`. The Web Host treats any value other than `browser` as `hash`. |
| `hide_session_selector` | `false` | Hide the session picker UI |

The facade shell's bootstrap token is separate from `session_type`. The shell always reads `localStorage["@wippy_token_info"]`, parses its JSON `token` field, and redirects to `login_path` when the value is missing or invalid. It passes that token to the Web Host. In `cookie` mode the Web Host also stores the token in its `@wippy-gen2/token` cookie; in `non-persistent` mode it does not use that secondary cookie.



#### Theming


Three scopes apply: **global** (everywhere), **host** (the Web Host chrome — sidebar, chat, page area), and **children** (child `view.page` render contexts and `view.component` web components). For which surface each knob reaches, see the [CSS Delivery Matrix](../frontend/web-host/css-injection.md#css-delivery-matrix).

| Parameter | Scope | Default | Description |
|-----------|-------|---------|-------------|
| `custom_css` | global | Google Fonts import | Global CSS — reaches host chrome, `view.page` render contexts, and `view.component` shadow roots (1.0.43+). |
| `css_variables` | global | `{}` | JSON map of arbitrary CSS custom properties; compiled for Auto and forced modes and bridged into component shadow roots. |
| `icon_sets` | global | `{}` | Iconify icon sets keyed by prefix (inline JSON only — no `fs://`) |
| `host_custom_css` | host | `""` | CSS for the host chrome only — not children. Scope class-based rules to `.wippy-host-app`. |
| `host_css_variables` | host | `{}` | CSS custom properties for the host chrome only |
| `host_icon_sets` | host | `{}` | Icon sets keyed by prefix for host only (inline JSON only) |
| `children_custom_css` | children | `""` | CSS for children only — injected into `view.page` render contexts and `view.component` shadow roots (1.0.43+), not host chrome |
| `children_css_variables` | children | `{}` | CSS custom properties for children only |

Put shared brand styling in the global `custom_css` and `css_variables` parameters so it reaches every surface. Use `host_custom_css` and `host_css_variables` for host-only elements such as the sidebar, chat panel, and splitters. A `view.component` can opt out of shadow-root `*_custom_css` with `customCss: false`.



##### Theme Mode and Persistence


| Parameter | Default | Description |
|-----------|---------|-------------|
| `theme_mode` | `auto` | Forced theme for host + children: `auto` (follow OS), `light`, or `dark`. Emitted on `/facade/config` as `themeMode`. |
| `theme_persist` | `none` | Persist the user's chosen theme across reloads: `none`, `cookie`, or `localStorage`. In `cookie` mode the Jet-rendered shell reads the cookie server-side and applies the `w-theme-*` class before the first paint (no flash). Emitted as `themePersist`. |
| `theme_storage_key` | `@wippy-theme-mode` | Cookie / localStorage key the mode is stored under. Emitted as `themeStorageKey` and baked into the generated `/facade/theme-persist.js`. |

Theme persistence is **opt-in**: `theme_persist` defaults to `none`, so nothing is stored until a deployment sets it to `cookie` or `localStorage`. When enabled the facade serves a ready-made script at **`GET /facade/theme-persist.js`** with the key and mode baked in; include it on any page that should share the theme. See [Theme Persistence](../frontend/web-host/theme-persistence.md) for the full model, the `themeChanged` host event, and non-Wippy-page integration.



##### Reusing Facade Theming on Non-Web-Host Pages


A page served outside the Web Host, such as `login.html`, an error page, or an email confirmation page, can reuse the facade theme. This keeps brand tokens and custom rules in one place.

First, keep `custom_css` and `css_variables` in standalone files rather than inlining them, and point the parameters at those files with `fs://` plus a `content_fs` filesystem:

```yaml
custom_css:    fs://custom-css.facade.css
css_variables: fs://css-variables.facade.json
content_fs:    app:app_fs
```

Use `fs://` (resolved by `content_fs` at runtime), **not** `file://` — `file://` is inlined by the wippy loader relative to the YAML at load time. Keep the files in the same static folder your `login_path` page is served from (in `app`, `static/` served at `/app`).

`fs://` resolution applies to exactly the **six theming parameters** — `custom_css`, `css_variables`, `host_custom_css`, `host_css_variables`, `children_custom_css`, `children_css_variables` (CSS strings are read verbatim; JSON `*_css_variables` files are parsed as the variable map). `icon_sets` / `host_icon_sets` and every other JSON parameter (`api_routes`, `chat`, `tanstack`, …) are **inline-only**; `fs://` is not resolved there.

A standalone page then links both:

- **`custom_css`** — already a `.css` file, so link it directly from where it is served.
- **`css_variables`** — JSON, so it is not linkable as-is. The facade renders it at **`GET /facade/variables.css`** as base plus effective Auto-light, Auto-dark, forced Light, and forced Dark blocks. Top-level values apply everywhere; `@light` / `@dark` replace selected names. The sheet is cached for 1h and registered on the same public router as `/facade/config`, so it carries the router prefix.

```html
<!-- in login.html, served outside the Web Host -->
<link rel="stylesheet" href="/api/public/facade/variables.css">  <!-- css_variables, generated CSS -->
<link rel="stylesheet" href="/app/custom-css.facade.css">        <!-- custom_css file -->
```

To also share the **theme mode** (so a `login.html` honours and persists the same light/dark choice as the host), add the generated theme-persist script and call its `write()` from your switcher:

```html
<script src="/api/public/facade/theme-persist.js"></script>
<!-- early-applies the stored theme and exposes window.wippyThemePersist -->
```

See [Theme Persistence → Non-Wippy-hosted pages](../frontend/web-host/theme-persistence.md) for a complete switcher example.



#### Optional JSON Parameters


Each of the following is a JSON-encoded string parameter; defaults are empty (`{}` or `[]`).

These four are surfaced verbatim under `hostConfig` for the frontend:

| Parameter | Default | Description |
|-----------|---------|-------------|
| `additional_nav_items` | `[]` | Extra sidebar entries |
| `state_cache` | `{}` | Frontend state cache configuration |
| `allow_additional_tags` | `{}` | HTML sanitizer tag whitelist (`Record<string, string[]>`, tag → allowed attributes) |
| `chat` | `{}` | Chat UI overrides |

These three are emitted as **top-level** `AppConfig` fields (siblings of `hostConfig`), not under `hostConfig`:

| Parameter | Emitted as | Default | Description |
|-----------|------------|---------|-------------|
| `api_routes` | `apiRoutes` | `{}` | Route overrides for the frontend |
| `axios_defaults` | `axiosDefaults` | `{}` | Frontend axios HTTP client defaults |
| `tanstack` | `tanstack` | `{}` | TanStack Query defaults: `{ default?, content?, lists? }`. `default` applies to all queries; `content` targets single-resource renders, `lists` targets navigation/index queries. Host default is `refetchOnWindowFocus:false` |



### Config Endpoint


The facade registers `GET /facade/config` on the configured public router, so the effective URL includes that router's prefix. With the `/api/public` prefix from [Setup](#setup), the page fetches `/api/public/facade/config`. The same router exposes `GET /facade/variables.css`, which renders `css_variables` as a `text/css` stylesheet for pages outside the Web Host. See [Reusing Facade Theming on Non-Web-Host Pages](#reusing-facade-theming-on-non-web-host-pages). The frontend fetches the configuration on load:

```json
{
    "facade_url": "https://web-host.wippy.ai/webcomponents-1.0.56",
    "iframe_origin": "https://web-host.wippy.ai",
    "iframe_url": "https://web-host.wippy.ai/webcomponents-1.0.56/iframe.html?waitForCustomConfig",
    "login_path": "/login.html",
    "login_redirect_param": null,
    "mode": "compat",
    "module_file": "/module.js",
    "extraScripts": null,
    "env": {
        "APP_API_URL": "https://api.example.com",
        "APP_AUTH_API_URL": "https://api.example.com",
        "APP_WEBSOCKET_URL": "wss://api.example.com"
    },
    "routePrefix": "https://api.example.com",
    "themeMode": "auto",
    "themePersist": "none",
    "themeStorageKey": "@wippy-theme-mode",
    "apiRoutes":     { "...": "..." },
    "axiosDefaults": { "...": "..." },
    "tanstack":      { "lists": { "refetchOnWindowFocus": true } },
    "theming": {
        "global":  { "customCSS": "...", "cssVariables": {}, "iconSets": {} },
        "host":    { "customCSS": "...", "cssVariables": {}, "iconSets": {}, "i18n": { "app": { "title": "Wippy", "icon": "wippy:logo", "appName": "Wippy AI" } } },
        "children": { "customCSS": "...", "cssVariables": {} }
    },
    "hostConfig": {
        "session": { "type": "non-persistent" },
        "history": "hash",
        "renderEngine": "iframe",
        "showAdmin": true,
        "allowSelectModel": false,
        "startNavOpen": false,
        "hideNavBar": false,
        "disableRightPanel": false,
        "hideSessionSelector": false,
        "additionalNavItems": [],
        "stateCache":        { "...": "..." },
        "allowAdditionalTags": { "w-chart": ["data", "type"] },
        "chat":              { "...": "..." }
    }
}
```

The API URL is read from the `PUBLIC_API_URL` environment variable; `APP_WEBSOCKET_URL` is derived by replacing `http://` with `ws://` or `https://` with `wss://`. Theming has three scopes (`global`, `host`, `children`) — `host.i18n` carries app branding. `hostConfig` keys are camelCased and assembled from facade parameters: `session_type`, `history_mode`, `render_engine`, `show_admin`, `allow_select_model`, `start_nav_open`, `hide_nav_bar`, `disable_right_panel`, `hide_session_selector`, plus optional `additional_nav_items`, `state_cache`, `allow_additional_tags`, and `chat`. `render_engine` becomes `renderEngine` (see [Render engine](#render-engine)). The `api_routes`, `axios_defaults`, and `tanstack` parameters are emitted as top-level `AppConfig` fields (`apiRoutes`, `axiosDefaults`, `tanstack`), siblings of `hostConfig`, not inside it.

The `facade_url`, `iframe_origin`, `iframe_url`, `login_path`, `mode`, and `module_file` fields are **shell-level** fields used by the embedding page to build itself — they are not part of the child `AppConfig` that the host initializes with. The `iframe_origin`/`iframe_url` fields are consumed only by manual, facade-less iframe embeddings (see [Facade Entry Point](../frontend/web-host/entry-point.md)). The `mode` field is the normalized `fe_mode` (`compat` or `managed`), and `module_file` is the JS-module entry the facade page loads — `/module.js` for compat, `/managed-layout.js` for managed.



### Navigation Sidebar


Pages registered via `wippy/views` appear in the sidebar automatically based on their metadata:

```yaml
entries:
  - name: dashboard
    kind: registry.entry
    meta:
      type: view.page
      name: dashboard
      title: Dashboard
      icon: tabler:chart-bar
      group: Analytics
      group_icon: tabler:chart-dots
      group_order: 10
      order: 1
      announced: true
      secure: true
      url: https://cdn.example.com/dashboard/
```



#### Sidebar Groups


Pages with the same `group` value are collected into collapsible sections. Groups are sorted by `group_order` (lower first), pages within groups by `order`.

| Field | Description |
|-------|-------------|
| `group` | Category name displayed in sidebar |
| `group_icon` | Icon for the category header |
| `group_order` | Sort position of the group (lower = higher) |
| `group_placement` | `"sidebar"` (in sidebar) or `"default"` (main area only) |

Pages without a `group` appear as top-level items.



#### Controlling Visibility


| Field | Effect |
|-------|--------|
| `announced: true` | Page appears in sidebar navigation |
| `announced: false` | Page hidden from navigation but still accessible via URL |
| `inline: true` | Internal page, hidden from all UI listings |
| `hide_nav_bar: true` | Facade parameter — hides the entire left sidebar |



### Publishing with Embedded Assets


When publishing a component that includes static files (like the facade's `public/` directory), use `--embed` to include `fs.directory` entries in the package:

```bash
wippy publish --embed facade:public_files
```

Without `--embed`, `fs.directory` entries are excluded from the published package. The `--embed` flag accepts entry IDs or names matching `fs.directory` entries.



### See Also


- [Views](./views.md) — Page and component system
- [HTTP Server](../http/server.md) — HTTP service configuration
- [Framework Overview](./overview.md) — Framework module usage
- [Facade Entry Point](../frontend/web-host/entry-point.md) — How the facade starts the Web Host
- [CSS Injection](../frontend/web-host/css-injection.md) — How facade theming reaches child iframes
- [Render Engines](../frontend/web-host/render-engines.md) — Iframe and Web Fragment page rendering



---

# "Embeddings"

## Embeddings


The `wippy/embeddings` module generates embeddings through `wippy/llm`, stores them in an application database, and performs vector similarity searches. It supports PostgreSQL with pgvector and SQLite with sqlite-vec.

This page is an API primer with reference snippets, not a standalone tutorial. The snippets assume an existing Wippy project, a configured database, and the embedding model, provider, and credentials described below. Remote embedding calls may incur provider charges. For a complete application that indexes and searches content, follow [Build a RAG Pipeline](../tutorials/rag.md).



### Setup


Add the module to your project:

```bash
wippy add wippy/embeddings
wippy install
```



#### Required Model and Provider


Before calling the embeddings API, register an `llm.model` whose `meta.name` is `text-embedding-3-small`, whose capabilities include `embed`, and whose provider mapping resolves to an embedding provider. Configure that provider's credentials, such as `OPENAI_API_KEY`, through the environment storage used by `wippy/llm`. See [LLM model configuration](./llm.md#model-configuration).



#### Database Dependency


Declare the dependency and set its `target_db` parameter to the application database:

```yaml
version: "1.0"
namespace: app

entries:
  - name: app_db
    kind: db.sql.sqlite
    file: ./data/app.db

  - name: dep.embeddings
    kind: ns.dependency
    component: wippy/embeddings
    version: "*"
    parameters:
      - name: target_db
        value: app:app_db
```

On startup, `wippy/migration` picks up the `01_create_embeddings_table` migration and creates the `embeddings_512` table for the configured database driver.

If you use the relative SQLite path shown above, create the `data` directory before starting the application.



### Current Fixed Constants


The module currently defines these private constants; they are not dependency parameters:

| Constant | Default | Description |
|----------|---------|-------------|
| `EMBEDDING_MODEL` | `text-embedding-3-small` | LLM model used to generate vectors |
| `EMBEDDING_DIMENSIONS` | `512` | Vector size passed to the model |
| `MAX_TOKENS_PER_REQUEST` | `8000` | Per-call token budget; large batches are split |
| `DEFAULT_SEARCH_LIMIT` | `10` | Default number of hits returned by `search` |

Tokens are estimated as `ceil(#text / 4)`. Oversized batches are split between items. An individual item larger than the budget is not split and causes that sub-batch to fail before the LLM call.



### Import


```yaml
entries:
  - name: my_app
    kind: library.lua
    source: file://my_app.lua
    imports:
      embeddings: wippy.embeddings:embeddings
```

```lua
local embeddings = require("embeddings")
```



#### add


```lua
local result, err = embeddings.add(content, content_type, origin_id, context_id, meta)
```

Generates an embedding for `content` and persists it.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `content` | string | yes | Text to embed |
| `content_type` | string | yes | Label such as `"document_chunk"` or `"question"`; PostgreSQL limits it to 32 characters |
| `origin_id` | string | yes | Identifier for the source document or record; must be a UUID when `target_db` is PostgreSQL |
| `context_id` | string | no | Additional scoping key (section, chat, tenant) |
| `meta` | table | no | Arbitrary JSON-serialisable metadata |

Returns `{ entry_id, origin_id, content_type, context_id }` or `nil, err`.

<warning>
At the pinned framework baseline, the single-item helper passes the nested result from `llm.embed()` to the repository instead of its first vector, so `embeddings.add()` cannot persist successfully. Use `embeddings.add_batch()` with one item, or call `llm.embed()` and pass `response.result[1]` to `embedding_repo.add()`, until the framework implementation is corrected.
</warning>



#### add_batch


The following uses SQLite-compatible application IDs. For PostgreSQL, replace `doc-1` with a UUID because the PostgreSQL schema stores `origin_id` as `UUID`.

```lua
local result, err = embeddings.add_batch({
    { content = "...", content_type = "chunk", origin_id = "doc-1" },
    { content = "...", content_type = "chunk", origin_id = "doc-1", context_id = "s1" },
})
```

Embeds and stores multiple items in one call. If the total estimated token count exceeds `MAX_TOKENS_PER_REQUEST`, the method splits the batch into chunks. Each repository chunk is transactional, but a split high-level batch is not atomic across chunks: earlier chunks remain stored if a later chunk fails. Returns `{ count, items = { ... } }`.

To remove records created while testing, use the repository API's `delete_by_origin(origin_id)` method for each sample origin.



#### search


```lua
local hits, err = embeddings.search("how do migrations work?", {
    content_type = "document_chunk",
    origin_id    = "doc-1",
    context_id   = "section-2",
    limit        = 10,
})
```

Embeds the query string and performs a similarity search against stored vectors. All filters are optional; matching records are ordered by similarity.

`origin_id` may be a string or a non-empty array of strings. Each hit contains `entry_id`, `origin_id`, `content_type`, `context_id`, `content`, decoded `meta`, timestamps, and `similarity`.



#### find_by_type


```lua
local hits, err = embeddings.find_by_type(
    "how do migrations work?",
    "document_chunk",
    { limit = 10 }
)
```

Calls `search` with a single `content_type`. The default limit is `10`.



#### find_by_origin


```lua
local hits, err = embeddings.find_by_origin("how do migrations work?", "doc-1", {
    content_type = "document_chunk",
    context_id   = "section-2",
    limit        = 5,
})
```

Calls `search` with a single `origin_id` and optional `content_type` and `context_id` filters. The default limit is `5`.



### Repository API (`wippy.embeddings:embedding_repo`)


Use the repository directly when you already have a vector and want to skip embedding generation. Raw embeddings must contain exactly 512 numeric values:

| Function | Description |
|----------|-------------|
| `embedding_repo.add(content, content_type, origin_id, context_id, meta, embedding)` | Insert a precomputed vector |
| `embedding_repo.add_batch(batch)` | Insert many precomputed vectors in one transaction |
| `embedding_repo.get_by_origin(origin_id)` | List all records for a given origin |
| `embedding_repo.delete_by_origin(origin_id)` | Remove all records for a given origin |
| `embedding_repo.delete_by_entry(entry_id)` | Remove a single record by its row id |
| `embedding_repo.search_by_embedding(vector, options)` | Similarity search against a raw vector |

`search_by_embedding` accepts `{ content_type, origin_id, context_id, limit }`.



### Database Support


The migration creates the schema appropriate for the database driver at `target_db`:

- **PostgreSQL** — `embeddings_512` table with a `vector(512)` column and an IVFFlat cosine index. The migration attempts to install the `vector` extension, so the database role must either be allowed to create it or the extension must already exist. PostgreSQL stores `origin_id` as `UUID`.
- **SQLite** — `embeddings_512` `vec0` virtual table holding the `embedding float[512]` vector column alongside the metadata and content columns for KNN search.



### See Also


- [LLM](framework/llm.md) — `llm.embed(...)` for raw embedding generation
- [Migrations](framework/migration.md) — Migration runner that provisions the table
- [Framework Overview](framework/overview.md) — Framework module usage



---

# "Bootloader"

## Bootloader


The `wippy/bootloader` module discovers and runs application initialization functions in a defined order at startup. Framework modules use bootloaders for tasks such as encryption-key setup and database migrations.

This page is a partial integration recipe and API reference, not a standalone application. The definition below is structurally complete, but `apply_seed()` represents application code that must implement the actual seed operation and its idempotency check. Any persistent cleanup or reversal depends on that application-specific operation.



### Setup


Add the module to your project:

```bash
wippy add wippy/bootloader
wippy install
```

Declare the dependency and the required application host:

```yaml
version: "1.0"
namespace: app

entries:
  - name: processes
    kind: process.host
    lifecycle:
      auto_start: true

  - name: os_env
    kind: env.storage.os

  - name: dep.bootloader
    kind: ns.dependency
    component: wippy/bootloader
    version: "*"
    parameters:
      - name: application_host
        value: app:processes
      - name: env_storage
        value: app:os_env
```

The dependency activates `wippy.bootloader:bootloader.service`, a `process.service` with `auto_start: true`.



### How It Works


At startup the bootloader:

1. Discovers every entry with `meta.type: bootloader` from the registry.
2. Sorts them by `meta.order` ascending (lowest first).
3. Executes each one sequentially as a Lua function.
4. Stops the remaining bootloader sequence on the first result with `status = "error"`.
5. Reports total, successful, failed, and skipped counts when finished.

Each bootloader checks its own conditions, performs its work, and reports a structured result.



### Defining a Bootloader


A bootloader is any `function.*` entry with `meta.type: bootloader`. Most application bootloaders use `function.lua`:

```yaml
- name: seed_defaults
  kind: function.lua
  meta:
    type: bootloader
    order: 50
    description: Seed default rows for a new install
  source: file://seed_defaults.lua
  method: run
  modules:
    - logger
  imports:
    sql: :sql
```

| Field | Required | Description |
|-------|----------|-------------|
| `meta.type` | Yes | Must be `bootloader` |
| `meta.order` | No | Execution order (default `999`); lower runs first |
| `meta.description` | No | Human-readable summary |
| `meta.requires` | No | One ID or an array of bootloader/service IDs. Earlier bootloaders must have returned `success` or `skipped`; service requirements must exist in the registry. An unmet requirement stops the remaining sequence. |

Dependency type is determined from the referenced registry entry: `meta.type: bootloader` identifies a bootloader, while other resolved entries are treated as services. If an ID cannot be resolved, the fallback treats a dotted namespace as a bootloader ID and another colon-qualified ID as a service ID. A service check waits up to 20 attempts at 500 ms intervals, but it checks registry presence, not runtime health.



#### Return Contract


The `method` returns a table describing the outcome:

```lua
local function run()
    local ok, err = apply_seed()
    if err then
        return {
            status = "error",
            message = "seed failed: " .. tostring(err)
        }
    end

    if not ok then
        return {
            status = "skipped",
            message = "already seeded"
        }
    end

    return {
        status = "success",
        message = "seeded default rows"
    }
end

return { run = run }
```

| Status | Meaning |
|--------|---------|
| `success` | Work completed |
| `skipped` | No-op (already done, precondition unmet) |
| `error` | Failure — stops the remaining bootloader sequence |

A bootloader that raises a Lua error, returns an execution error, or returns a non-table value is converted to an `error` result. The orchestrator measures and overwrites `duration`; a returned `details` value is preserved for logging.

Use the three status strings exactly. Another value is logged as `UNKNOWN`, is not included in a status counter, and does not currently stop later bootloaders.



### Execution Order


Lower `order` values run first. Reserve low orders for infrastructure:

| Order | Typical Use |
|-------|-------------|
| `10` | Secrets and encryption keys (provided by the module) |
| `20` | Schema migrations (provided by `wippy/migration`) |
| `50` | Data seeding, search index warmup |
| `100` | Application-level tasks (convention) |

When two bootloaders share an order, they run in alphabetical order by their fully-qualified entry ID.



#### Encryption Key (order `10`)


Generates 32 random bytes, encodes them as a 64-character hexadecimal `ENCRYPTION_KEY`, and stores the value through the configured `env_storage` if no value is present. Skipped when the variable already exists.



#### Migration Bootloader (order `20`)


Provided by `wippy/migration`. Discovers every entry with `meta.type: migration`, groups them by `meta.target_db`, and applies the pending ones. See [Migrations](framework/migration.md).



### Observing Boot Status


The service logs the discovery count, then one result line per executed bootloader (`SUCCESS`, `FAILED`, `SKIPPED`) with the entry ID, order, and duration. The final summary reports executed and per-status counts. A failed bootloader stops later bootloaders and makes the orchestrator return `false` with its statistics; it does not raise a Lua process error by itself.

<tip>
Keep bootloaders idempotent. They run again whenever `bootloader.service` is started again, so check preconditions (row exists, file present, env var set) before doing work.
</tip>



### See Also


- [Migrations](framework/migration.md) — Migration bootloader and DSL
- [Supervision](guides/supervision.md) — Service lifecycle and restart policy
- [Framework Overview](framework/overview.md) — Framework module usage



---

# "Migrations"

## Migrations


The `wippy/migration` module provides a database migration framework with a small DSL for defining schema changes, a runner that discovers and executes them, and a bootloader that runs pending migrations for every `target_db` registered in the project.

Migrations support SQLite, PostgreSQL, and MySQL, with per-driver `up`/`down` implementations defined side by side.



### Setup


Add the module to your project:

```bash
wippy add wippy/migration
wippy install
```

Declare the dependency and the application database the migrations target:

```yaml
version: "1.0"
namespace: app

entries:
  - name: app_db
    kind: db.sql.sqlite
    path: ./data/app.db

  - name: dep.migration
    kind: ns.dependency
    component: wippy/migration
    version: "*"
```

The migration bootloader registers with `wippy/bootloader` at order `20`. When the application starts, it discovers every migration entry in the registry, groups them by `meta.target_db`, and runs pending migrations against each database.



### Defining a Migration


A migration is a `function.lua` entry with `meta.type: migration`. The entry returns a function produced by `migration.define(...)`.

```yaml
entries:
  - name: 01_create_users_table
    kind: function.lua
    meta:
      type: migration
      target_db: app:app_db
      timestamp: "2025-01-15T10:00:00Z"
    source: file://01_create_users_table.lua
    imports:
      migration: wippy.migration:migration
```

```lua
return require("migration").define(function()
    migration("Create users table", function()
        database("sqlite", function()
            up(function(db)
                local ok, err = db:execute([[
                    CREATE TABLE users (
                        id    INTEGER PRIMARY KEY,
                        name  TEXT NOT NULL,
                        email TEXT NOT NULL UNIQUE
                    )
                ]])
                if err then error(err) end
            end)

            down(function(db)
                db:execute("DROP TABLE IF EXISTS users")
            end)
        end)

        database("postgres", function()
            up(function(db)
                db:execute([[
                    CREATE TABLE users (
                        id    SERIAL PRIMARY KEY,
                        name  TEXT NOT NULL,
                        email TEXT NOT NULL UNIQUE
                    )
                ]])
            end)

            down(function(db)
                db:execute("DROP TABLE IF EXISTS users")
            end)
        end)
    end)
end)
```



#### Required Metadata


| Field | Required | Description |
|-------|----------|-------------|
| `meta.type` | yes | Must be `"migration"` for discovery |
| `meta.target_db` | yes | Registry ID of the database to run against |
| `meta.timestamp` | no | ISO-8601 timestamp used for ordering when multiple migrations target the same database |
| `meta.tags` | no | Array of tags; the runner can filter migrations by tag |

Migrations for a database run in ascending `meta.timestamp` order. `meta.timestamp` is optional; the full entry id is the tie-breaker, so migrations with equal or absent timestamps still run in a stable, deterministic order.



### DSL


Inside the function passed to `migration.define`, the following nested functions are available:

| Function | Description |
|----------|-------------|
| `migration(description, fn)` | Open a new migration with a human-readable description |
| `database(type, fn)` | Declare an implementation for `"sqlite"`, `"postgres"`, or `"mysql"` |
| `up(fn)` / `down(fn)` | Define forward and rollback functions |
| `after(fn)` | Optional post-migration hook (same transaction) |

Each `up`/`down`/`after` function receives a transaction object, not a raw connection. All three operations run in a single transaction that rolls back on error.



#### Transaction Methods


```lua
local rows, err  = db:query(sql, params)    -- SELECT, returns array of rows
local result, err = db:execute(sql, params) -- INSERT/UPDATE/DDL, returns { rows_affected, last_insert_id }
local stmt, err  = db:prepare(sql)          -- prepared statement
```

Always use parameterised queries:

```lua
db:execute("INSERT INTO users (name, email) VALUES (?, ?)", { "Alice", "alice@example.com" })
```



#### Error Handling


Calling `error(...)` aborts the migration and rolls back the transaction. Wrap every statement that may fail:

```lua
up(function(db)
    local _, err = db:execute("CREATE TABLE ...")
    if err then error(err) end
end)
```



### Runner API


The runner is exposed as a library for programmatic use:

```yaml
imports:
  runner: wippy.migration:runner
```

```lua
local runner = require("runner").setup("app:app_db")

local result = runner:run()      -- apply all pending migrations
local result = runner:run_next() -- apply the next pending migration
local result = runner:rollback() -- roll back the most recently applied migration
local status = runner:status()   -- list applied + pending migrations
```



#### `runner:run(options)`


Applies every pending migration for the configured database. Returns a summary:

```lua
{
    status = "complete",            -- "complete" or "error"
    migrations_found = 3,
    migrations_applied = 2,
    migrations_skipped = 1,
    migrations_failed = 0,
    duration = 0.123,
    migrations = { ... },           -- per-migration status
    skipped_details = { ... },
}
```

Options:

| Option | Description |
|--------|-------------|
| `tags` | Array of tags; only migrations whose `meta.tags` intersect are considered |



#### `runner:rollback(options)`


Rolls back applied migrations in reverse order of application. With no options it reverts the single most recently applied migration:

```lua
runner:rollback()                                            -- roll back the last migration
runner:rollback({ count = 3 })                               -- roll back the last 3
runner:rollback({ allowed_ids = { "app:01_create_users_table" } }) -- restrict to specific ids
```

Options:

| Option | Description |
|--------|-------------|
| `count` | Number of migrations to roll back; defaults to `1` |
| `allowed_ids` | Array of migration ids; only these are eligible for rollback |



#### `runner:status(options)`


Returns a status report describing every migration for the database:

```lua
{
    database_id        = "app:app_db",
    db_type            = "sqlite",
    total_migrations   = 3,
    applied_migrations = 2,
    pending_migrations = 1,
    migrations = {
        { id = "app:01_...", description = "...", timestamp = "...",
          tags = {}, status = "applied", applied_at = ... },
        -- ...
    },
}
```

Applied migrations are listed first (ordered by `applied_at`), followed by pending ones (ordered by `meta.timestamp`, then by id).



### Registry API


`wippy.migration:registry` offers direct registry queries:

| Function | Description |
|----------|-------------|
| `registry.find({ target_db, tags })` | Return all migration entries matching the criteria |
| `registry.get(id)` | Return a single migration entry by id |
| `registry.get_target_dbs()` | Return every unique `meta.target_db` present in migrations |
| `registry.get_tags()` | Return every unique tag present on migrations |

The bootloader uses these to discover the full set of target databases at startup.



### Migration Tracking


The runner creates a `_migrations` table in each target database on first run. Applied migrations are recorded by id so subsequent runs skip them. The tracking table is created automatically; do not write your own migration to create it.



### Best Practices


- **One logical change per migration** - create one table, add one column, create one index.
- **Write a real `down`** - if rollback is impossible (data loss), document that and raise an error rather than silently succeeding.
- **Prefer idempotency** - `CREATE TABLE IF NOT EXISTS` and `DROP TABLE IF EXISTS` survive reruns without special handling.
- **Keep DDL and DML separate** - don't seed data in the same migration that creates a table when you can avoid it.
- **Test both directions** - apply the migration, roll it back, and verify the schema matches the starting state.



### See Also


- [SQL Driver](system/database.md) - Database resource configuration
- [Bootloader](framework/bootloader.md) - Bootloader ordering and hooks
- [Framework Overview](framework/overview.md) - Framework module usage



---

# "Usage Tracking"

## Usage Tracking


The `wippy/usage` module records LLM token consumption and provides aggregate queries by time interval, model, or user. It is the default implementation of the `wippy.llm:usage_tracker` contract, so calls made through the LLM module produce usage records automatically.

This page is an API primer with reference snippets, not a standalone tutorial. The snippets assume an existing Wippy project, a configured SQL database, and `wippy/llm` when automatic tracking is required. Usage rows persist in the selected database; remove sample rows through your normal database-maintenance workflow when testing is complete.



### Setup


Add the module to your project:

```bash
wippy add wippy/usage
wippy install
```

Declare the dependency and set `target_db` to the database that will store usage records:

```yaml
version: "1.0"
namespace: app

entries:
  - name: app_db
    kind: db.sql.sqlite
    file: ./data/app.db

  - name: dep.usage
    kind: ns.dependency
    component: wippy/usage
    version: "*"
    parameters:
      - name: target_db
        value: app:app_db
```

When the application starts, `wippy/migration` runs the module's `01_create_token_usage_table` migration, which creates the `token_usage` table along with indexes on `user_id`, `context_id`, `model_id`, and `timestamp`.

If you use the relative SQLite path shown above, create the `data` directory before starting the application.



### Schema


```
token_usage
├── usage_id           text primary key (uuid v7)
├── user_id            text not null
├── context_id         text
├── model_id           text not null
├── prompt_tokens      integer
├── completion_tokens  integer
├── thinking_tokens    integer default 0
├── cache_read_tokens  integer default 0
├── cache_write_tokens integer default 0
├── timestamp          timestamp
└── meta               text (JSON)
```



### Automatic Tracking


`wippy/llm` resolves the `wippy.llm:usage_tracker` contract before each generation. `wippy/usage` binds its implementation as the default:

```yaml
contracts:
  - contract: wippy.llm:usage_tracker
    default: true
    methods:
      track_usage: wippy.usage:usage_tracker
```

Every successful LLM call invokes `track_usage` with the model id, token counts, and an optional `context_id`. The `user_id` is taken from the active security actor; calls outside of a user context are recorded as `"system"`.



### Tracker API


Import the tracker directly to record usage outside the LLM flow:

```yaml
imports:
  usage_tracker: wippy.usage:usage_tracker
```

```lua
local tracker = require("usage_tracker")

-- Numeric counts supplied by the caller or model provider.
local prompt_tokens, completion_tokens = 120, 40
local thinking_tokens = 0
local cache_read_tokens, cache_write_tokens = 0, 0

local usage_id, err = tracker.track_usage(
    "openai:gpt-4o",
    prompt_tokens,
    completion_tokens,
    thinking_tokens,
    cache_read_tokens,
    cache_write_tokens,
    { context_id = "chat-42", metadata = { feature = "summary" } }
)
if err then
    error("Failed to record usage: " .. tostring(err))
end
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `model_id` | string | Canonical model id |
| `prompt_tokens` | number | Input tokens |
| `completion_tokens` | number | Output tokens |
| `thinking_tokens` | number | Reasoning tokens (0 when not reported) |
| `cache_read_tokens` | number | Prompt-cache hits |
| `cache_write_tokens` | number | Prompt-cache writes |
| `options.context_id` | string | Free-form tag; falls back to `ctx.get("context_id")` |
| `options.timestamp` | number | Unix timestamp; defaults to now (UTC) |
| `options.metadata` | table | Arbitrary JSON metadata stored alongside the record |

Returns `usage_id` or `nil, err`.



### Repository API


`wippy.usage:token_usage_repo` offers aggregate queries:

```yaml
modules:
  - time
imports:
  usage: wippy.usage:token_usage_repo
```

```lua
local usage = require("usage")
local time = require("time")

-- Inclusive query bounds expressed as UNIX timestamps.
local end_unix = time.now():unix()
local start_unix = end_unix - (24 * 60 * 60)

local function require_result(value, err)
    if err then
        error("Usage query failed: " .. tostring(err))
    end
    return value
end

local summary  = require_result(usage.get_summary(start_unix, end_unix))
local by_time  = require_result(usage.get_usage_by_time(start_unix, end_unix, usage.INTERVAL.DAY))
local by_model = require_result(usage.get_usage_by_model(start_unix, end_unix))
local by_user  = require_result(usage.get_usage_by_user(start_unix, end_unix))
```



#### Functions


| Function | Returns |
|----------|---------|
| `get_summary(start, end)` | Totals across the range: prompt/completion/thinking/cache tokens, request count, `total_tokens` (prompt + completion + thinking) |
| `get_usage_by_time(start, end, interval)` | Array of buckets, one per interval; missing buckets return zeroes |
| `get_usage_by_model(start, end)` | Per-model totals, ordered by `total_tokens` descending |
| `get_usage_by_user(start, end)` | Per-user totals, ordered by `total_tokens` descending |
| `create(user_id, model_id, prompt, completion, options)` | Low-level insert used by the tracker |



#### Intervals


```lua
usage.INTERVAL.HOUR   -- "hour"
usage.INTERVAL.DAY    -- "day"
usage.INTERVAL.WEEK   -- "week"
usage.INTERVAL.MONTH  -- "month"
```

`get_usage_by_time` aligns buckets to the configured interval. On PostgreSQL it uses `generate_series` with interval arithmetic; on SQLite it uses a recursive CTE over UNIX timestamps. `total_tokens` in each bucket excludes cache tokens.



#### Time Ranges


Both the tracker and the repository accept UNIX timestamps at the public API boundary. Internally the repository converts to RFC3339 strings for storage and querying. Pass `os.time()` or `time.now():unix()` values, not formatted strings.



### Metadata and Context


The `meta` column stores free-form JSON for correlating records with application events:

```lua
local usage_id, err = tracker.track_usage("openai:gpt-4o", 120, 40, 0, 0, 0, {
    context_id = "chat-42",
    metadata   = {
        session_id = "s-7",
        route      = "/api/summarise",
        agent_id   = "writer",
    },
})
if err then
    error("Failed to record usage metadata: " .. tostring(err))
end
```

`context_id` is a top-level column and can be indexed; `metadata` is stored as text and is intended for display, not filtering.



### See Also


- [LLM](framework/llm.md) — LLM generation and the `usage_tracker` contract
- [Migrations](framework/migration.md) — Migration runner that creates the schema
- [Framework Overview](framework/overview.md) — Framework module usage



---

# "Frontend Contract: Start Here"

## Frontend Contract: Start Here


This page is an orientation guide and navigation reference. It identifies the
contracts a frontend module must follow; it is not a build tutorial or a
complete application example.

Wippy frontend modules are portable by default. A module must continue to work when it is imported into another Wippy project whose facade supplies a different compliant PrimeVue theme and no project-private CSS.



### Choose the correct path


1. Use a `view.page` for an application rendered by the configured page engine: a legacy `about:srcdoc` iframe or a Web Fragment.
2. Use a `view.component` for a custom element rendered in the host document, normally with a shadow root.
3. If the UI renders a button, input, form field, menu, overlay, or another PrimeVue-like control, use PrimeVue unless it cannot provide the required semantics and affordance.
4. A content-only component, such as a Chart.js visualization with no controls, may omit PrimeVue and Tailwind.
5. If a custom control is necessary, follow the [Portable UI Contract](./portable-ui-contract.md) and [Custom Composites](./micro-frontends/custom-composites.md).

PrimeVue is the shared component vocabulary. The Wippy Tailwind preset is a supported build-time vocabulary. Only utilities documented as runtime-backed remain responsive to facade theme changes after compilation.



### Ownership map


```text
module source
  -> build command
  -> emitted artifact
  -> registry owner
  -> served URL
  -> Web Host
  -> page surface (srcdoc iframe or Web Fragment) or component shadow root
  -> AppConfig / router / theme delivery
```

Do not infer one stage from another. Before debugging a missing asset, identify the source package, build target, emitted file, registry entry, filesystem mount, and served URL.



### Contract pages


- [Platform Topology](./platform-topology.md): runtime boundaries, routing, CSS delivery, overlays, and ownership.
- [Portable UI Contract](./portable-ui-contract.md): normative component and styling rules.
- [Theme Authoring](./micro-frontends/theming.md): what belongs in facade `custom_css`, PrimeVue theme CSS, or a module.
- [Tailwind Contract](./micro-frontends/tailwind-contract.md): runtime-backed utilities versus compiled constants.
- [Token Catalogue](./micro-frontends/token-catalogue.md): generated token reference and provenance.
- [The Design Layer](./design-layer.md): where something belongs when several of your own modules need it and the theme has no component for it.
- [Page Recipe](./micro-frontends/micro-frontend-app.md) and [Web Component Recipe](./micro-frontends/web-component.md).
- [Build and Dependency Contract](./micro-frontends/build-system.md).
- [Configuration and Casing](./micro-frontends/configuration-casing.md).
- [Compliance Rule Index](./micro-frontends/compliance-checklist.md).



### Non-negotiable checks


- Never invent a PrimeVue prop, component API, CSS variable, or Tailwind semantic utility. Verify it in the selected package source and generated catalogue.
- Never construct a `--p-*` token name by analogy.
- Never require an arbitrary facade class from a portable module.
- Never infer host route context from browser location. Pages receive host context through AppConfig and use `@wippy-fe/router`.
- Rebuild the exact owning package into the served output before browser verification.
- Verify the browser console after navigation and material interaction.

Project-bound modules are outside the portable contract. They are documented only on the [Unsupported Project-Bound Modules](./micro-frontends/unsupported-project-bound.md) page; standard compliance returns `UNSUPPORTED` and standard CI fails.



---

# "Platform Topology"

## Platform Topology


This page is an architecture and diagnostic reference. The delivery chain and
diagrams describe system boundaries; they do not provide a runnable project.



### Delivery chain


| Stage | Owner | Verification |
|---|---|---|
| Source and package build | Frontend module | The package build emits the expected entry file. |
| Artifact location | Deployment build target | The build command receives `--outDir`; Vite does not hardcode it. |
| Registry entry | Backend module | `view.page` or `view.component` points at the emitted entry. |
| Served URL | Filesystem and HTTP registry entries | A direct asset request returns the built JavaScript or HTML. |
| Runtime container | Web Host | A page uses the configured page engine: a legacy `about:srcdoc` iframe or a Web Fragment. A component uses a custom element, normally with shadow DOM. |
| Context | AppConfig and Wippy packages | Routing, API access, and theme data arrive through supported packages. |

The presence of source, a successful build, or a valid registry entry does not prove the next stage. Verify each boundary.



### Pages


A `view.page` runs through one of two engines: a legacy `about:srcdoc` iframe or
a Web Fragment. The global `hostConfig.renderEngine` setting selects the
baseline; a page's `wippy.renderEngine` can follow it, opt out to `iframe`, or
request `fragment` when the deployment supports it. Application code stays
engine-agnostic. In neither engine is browser location the supported child-route
contract. Use AppConfig and `@wippy-fe/router`; the package handles Wippy route
integration.

The `iframe` CSS injection currently provides default themed scrollbar styling. Its name is historical and broader than its present purpose. Keep it enabled for scrollbar consistency; do not describe it as a layout reset.



### Web components


A `view.component` runs in the host document and normally owns a shadow root. CSS selectors do not cascade through a shadow boundary. The Web Host may deliver approved stylesheets and facade CSS into that root according to component configuration.

CSS variable inheritance and stylesheet injection are different mechanisms:

- Public inherited variables can cross the host-to-shadow boundary.
- Selector rules affect a shadow root only when delivered into that root.
- Delivery does not make an arbitrary selector a portable API.



### Theme and overlays


The facade supplies the PrimeVue theme. Shared `.p-*` rules in facade `custom_css` are valid theme implementation and may be global when intended for host and children. Use `.wippy-host-app` only for host-specific chrome.

Theme mode is AppConfig state, not a CSS-class API. Applications, components,
fixtures, and browser tests switch mode with
`host.setThemeMode('auto' | 'light' | 'dark')` from `@wippy-fe/proxy`, then wait
for `@theme` and verify `host.getThemeMode()`. AppConfig carries the change
through the host-to-child transport. The host updates its document,
re-broadcasts AppConfig to live iframe and Web Fragment page realms, and mirrors
the mode into web-component roots.
Never force `w-theme-dark` or `w-theme-light` classes directly.

PrimeVue overlays may be teleported. Verify the actual overlay root in the top document, iframe documents, and recursively discovered shadow roots. Do not assume generic PrimeVue placement.



### Runtime debugging order


1. Confirm the backend is listening.
2. Inspect backend logs for unexpected 5xx responses.
3. Confirm the registry owner and served asset URL.
4. Confirm the exact package build emitted that asset.
5. Load the host root before navigating through the SPA when direct deep links are unsupported.
6. Inspect console and network errors after navigation and interaction.
7. For theme scenarios, call the public proxy theme method, observe `@theme`,
   and verify `host.getThemeMode()` before accepting a screenshot.



---

# "Portable UI Contract"

## Portable UI Contract


This page is a normative contract reference. Its rule IDs define review and
acceptance requirements rather than an implementation tutorial.

The following IDs are the canonical owners of their rules.



#### FE-PORT-001: Portable is the default


A compliant module works with another compliant facade theme without module edits and without project-private facade classes.



#### FE-STYLE-001: No private facade dependency


Portable modules cannot require arbitrary classes or selectors defined only by one facade. Shared PrimeVue `.p-*` theme rules are not private classes. Non-PrimeVue styling required by one module belongs in that module, but should be minimized by conforming to shared components and semantics.

When *several* of your own modules need the same non-PrimeVue styling, it belongs in neither the facade nor each module: see [The Design Layer](./design-layer.md).



#### FE-UI-001: Use PrimeVue when it satisfies the control


If PrimeVue provides the required semantics, interaction, and intended affordance, the module must use it.



#### FE-UI-002: Data shape is not affordance


The ability to represent the same values does not make two controls equivalent. A `SelectButton` is not automatically a substitute for a sliding three-position toggle when the intended affordance is visibly and behaviorally a toggle.



#### FE-UI-003: Same semantics and affordance means same appearance


Equivalent controls must share sizes, spacing, colors, typography, borders, shadows, focus, hover, disabled, invalid, and motion behavior. A custom composite names its PrimeVue visual sibling and inherits every applicable shared runtime property.



#### FE-UI-004: PrimeVue omission is narrow


PrimeVue may be omitted only when the module renders nothing that is physically or semantically PrimeVue-like. A chart-only component qualifies; a chart with a button or form field does not.



#### FE-UI-005: Never invent component APIs


An undocumented prop or behavior is not a shortcut. PrimeVue `ToggleSwitch` does not become a three-position control by inventing a new positions prop. When no PrimeVue component or composition supplies the required affordance, use the reviewed custom-sibling process.



#### FE-TW-001: Wippy Tailwind is supported


The shared Wippy preset is a supported build-time contract. Modules may use its documented utilities and extend it for domain layout, application-specific breakpoints, decoration, and novel visualization.



#### FE-TW-002: Compiled values are not runtime tokens


Utilities such as `px-3`, `rounded-md`, and `duration-200` normally compile to constants. They provide a consistent baseline but do not change when a facade swaps runtime theme variables.



#### FE-TW-003: Shared sibling appearance tracks runtime semantics


When an appearance property must track a PrimeVue sibling across themes, use a documented runtime-backed semantic utility or a direct public token. A fixed utility is allowed only when the property is explicitly classified `platform-invariant`.



#### FE-TW-004: Protected mappings keep their meaning


Modules may extend the preset but cannot redefine protected primary, surface, severity, text, content, highlight, or portable-control semantics incompatibly.



#### FE-TOKEN-001: Every token must exist


Every `--p-*` reference must be present in the selected generated manifest.



#### FE-TOKEN-002: Token names are not guessable APIs


Never construct a token by analogy. Search the [Token Catalogue](./micro-frontends/token-catalogue.md) or the selected package manifest.



#### FE-A11Y-001: Custom is not an accessibility waiver


A custom-control exception must preserve valid HTML, keyboard interaction, focus, accessible name, state, and disabled behavior. Interactive elements must not be nested.



---

# "The Design Layer"

## The Design Layer


This page is a design-ownership decision guide. Its CSS and component snippets
are partial patterns that assume an existing Wippy frontend package and build.

A Wippy frontend can contain many independently published modules in one
application. The **theme** reaches every surface, while each **module** owns its
local presentation. A **shared design layer** covers the narrower case where
several modules share a concept that the theme does not provide.



### The layers


| Layer | Reaches | Owns |
|---|---|---|
| **Theme** | *Every* surface, including modules you do not own | PrimeVue components, the shared semantic tokens, documented classes |
| **Shared design layer** | Only the modules that opt in | Vocabulary those modules share that has no themed component behind it |
| **Module** | Itself | What is genuinely specific to one surface |



#### The theme is universal, and that is the constraint


The theme styles markup **you do not own**. Any module — including a
third-party plugin written by someone who has never seen your app — renders
into the same host and is painted by the same theme. That is what makes the
theme the universal layer, and it cuts both ways:

**Nothing app-specific may go into the theme**, because it would be imposed on
every module that never asked for it.

**A module may not depend on anything app-specific being in the theme.** The
contract is *PrimeVue components + the shared Wippy semantic tokens +
documented classes* — nothing an application added on top. Note that PrimeVue's
own presets are not the contract either: Wippy runs PrimeVue with
`theme: 'none'`, so it is the Wippy semantic tokens you rely on.

```css
/* GOOD — shared Wippy semantic tokens, present for every module */
.my-panel {
  color: var(--p-text-color);
  background: var(--p-content-background);
  border: 1px solid var(--p-content-border-color);
}

/* BAD — an application-specific token. Your module now only works inside
   one app, and silently loses the declaration anywhere else: an undefined
   custom property makes the declaration invalid at computed-value time, so
   it drops and the element quietly inherits instead. */
.my-panel { background: var(--kx-surface-2); }
```

This is also the answer to *"can I put our shared vocabulary in the facade?"*
Only if it must genuinely reach arbitrary, unowned markup. If it is scoped to
*your* set of modules, it does not belong in the theme — it belongs in the
layer below.



#### The backbone, and when a component may opt out


PrimeVue and Tailwind, as shipped by the host, are the recommended backbone for
any component. A component **may** opt out — but the opt-out narrows the moment
it renders anything conventional, and the ladder only goes one way:

| The component… | Then it must load |
|---|---|
| is presentation-neutral — canvas, SVG, a chart with no controls, no tokens, no utilities, no scrolling | nothing: `hostCssKeys: []` |
| consumes semantic tokens or dark mode | `themeConfigUrl` |
| can scroll | `iframeCssUrl` |
| renders markdown | `markdownCssUrl` |
| chooses Tailwind utilities for routine layout or spacing | `primeVueCssUrl` (the Host bundles Tailwind with this asset) |
| renders anything **PrimeVue** ships a component for — button, input, form, table, dialog, menu, tag, tooltip, any feedback control | `primeVueCssUrl` **and** `PrimeVuePlugin` |

A chart on a canvas is the archetypal legitimate opt-out: it has no classic UI,
so it needs none of the backbone. Give that same chart a toolbar and it is no
longer presentation-neutral — the button is a PrimeVue button, and the whole
integration comes with it.

Note the coupling: **Tailwind utilities are delivered with `primeVueCssUrl`.**
There is no separate Tailwind host CSS key, so in practice a component that
chooses Tailwind is loading the PrimeVue asset too. Prefer utilities for
ordinary layout and spacing when they keep the component clear, but portable
module-owned CSS remains valid when a utility is not the best expression of the
design. (`preflightCssUrl` is not part of the key union; if Tailwind preflight
is genuinely required inside the shadow root, load it imperatively — rarely
needed.)

The practical consequence for this page: **most of what a module wants already
exists in the backbone.** The shared design layer is a narrow band above it, not
a place to re-do what PrimeVue and Tailwind already cover. See
[CSS Injection](./web-host/css-injection.md) for the mechanics.



#### The shared design layer


Some ideas recur across a known set of modules and have no application-level
contract in the theme: a domain-specific match summary, a surface header row,
an empty state, or a project-specific tag-sizing vocabulary. These concepts
belong in the shared design layer.

They ship as a **published package**, materialized into each consumer at build
time. It must be a package rather than a path alias because consumers live in
different repositories. A module in another repository, with no path access to
the producer, must be able to consume the vocabulary and build.

The producing module declares the package as a **build-time artifact** and each
consumer materializes it into its own tree. See
[Build-time Artifacts](../guides/artifacts.md) for the declaration, the
`node-package` format, what the runtime reconciles for you, and the glue a
build still has to supply itself.



#### The module


Everything else, plus every deliberate divergence from the shared vocabulary.



### Deciding where something belongs


Ask in order. First yes wins.

1. **Is it a value?** Colour, radius, spacing, elevation, severity.
   → **Theme.** Read a semantic token. Never a literal.
2. **Does the theme already ship a component for this?** Button, Dialog,
   Select, Tag. → **Theme.** Use the component. Style it by putting a class
   *on* it — never rebuild it.
3. **Do two or more of your modules need this same concept, with no themed
   component behind it?** → **Shared design layer.**
4. Otherwise → **Module.**



### Worked examples


The examples use the `kx-` prefix for application-specific classes and
stylesheet names. The placement rules apply to any Wippy application.



#### Never rebuild a themed component


PrimeVue ships `Button`. Replacing it with `.kx-btn` on a native `<button>`
creates a second implementation whose interaction and appearance can drift
from the themed component.

**Bad:** a native `button` element carrying `.kx-btn .kx-btn-primary` — a second
implementation of a component the theme already ships.

**Good:** the themed component, with a class on it when you need to adjust it.

```vue
<Button label="Save" class="kx-save" />
```

When the themed component does not fit, that is not a licence to rebuild it.
Put a class on the component and style that class — in the facade if the
adjustment is app-wide, in the module if it is local.



#### Severity is the theme's, not yours


Severity — `success`, `danger`, `warn`, `info` — is theme semantics with
published ramps. Re-deriving it under module-local names creates competing
definitions that can diverge across modules.

```css
/* BAD — severity re-derived under a module-local name */
.tone-gn { color: #16a34a; }

/* GOOD — severity from the theme */
.status-dot.success { background: var(--p-success-500); }
```

A *tone* may still exist in the shared layer — but only as **decorative
category colour**, never as severity. If it can mean "this failed", it is
severity and it is the theme's.



#### Shared vocabulary the theme has no seat for


```css
/* GOOD — this application-specific card contract and empty-state vocabulary
   recur across modules. PrimeVue's generic Card does not define these domain
   semantics, so the shared layer owns them. */
@import "@kickside/ui-kit/kx-card.css";
@import "@kickside/ui-kit/kx-state.css";
```



#### Adopting means import *and delete*


A CSS `@import` must precede every other rule in a sheet. The shared sheet
therefore always lands **first**, and anything the module declares afterwards
beats it at equal specificity. A module that imports the package and keeps its
own copy has changed nothing at all.

```css
/* BAD — the import is inert; the local copy still wins */
@import "@kickside/ui-kit/kx-card.css";
.kx-card { border-radius: 14px; border: 1px solid var(--p-content-border-color); }

/* GOOD — import, delete the local copy, keep only a documented delta */
@import "@kickside/ui-kit/kx-card.css";
/* This surface's cards are inline in a dense list, so they lose the lift. */
.kx-card:hover { transform: none; }
```

Keep the **delta only** — never restate the whole body. And never fold two
intents into one name: if a class name means different things in two modules,
that is two concepts wearing one name. Split the name; do not pick a winner and
repaint the loser.



#### Specificity against the theme


The module's CSS is injected into the shadow root first; the theme's PrimeVue
sheet is appended afterwards. Both are `<style>` elements, so **document order
decides and the theme is second**. A module rule that must beat a themed
component class needs more *specificity* — not a later line in the file.
(`adoptedStyleSheets` carries the facade's custom CSS, not the theme, so
reaching for an adopted sheet does not win this either.)

This is most visible with pass-through classes, where your class lands *on* a
themed element:

```css
/* BAD — this class is applied to PrimeVue's own footer element, so at equal
   specificity the theme wins and the padding never applies. */
.kx-modal-foot { padding: 14px 18px; }

/* GOOD — scoped under the dialog root, so it out-specifies the theme */
.kx-modal > .kx-modal-foot { padding: 14px 18px; }
```



### What the shared layer may contain


Everything a set of modules genuinely shares and the theme does not own: CSS
vocabulary, derived tokens, internal components, helpers, and test harnesses.

**Use semantic chunks.** Each unit should be one named concept a
consumer can reason about — `kx-card`, `kx-state`, `kx-tag`. Prefer
finer-grained packages so a consumer takes only what it needs; a single package
shipping several clearly-named units is workable, but it is not the shape to
aim for.

**Use specific names.** Avoid catch-all units such as `common`, `shared`,
`misc`, or `utils`. A unit whose name does not describe its contents will
accumulate unrelated concepts and recreate the duplication this layer is meant
to remove.



### Normalising is a visual change


Consolidating drifted copies can change rendering. Compare every definition,
choose the canonical version, record the reason, keep deliberate divergence as
a documented override, and inspect the result visually. Unit tests cannot see
layout.



### Related


- [Theming](./micro-frontends/theming.md) — the token catalogue, and how the
  theme reaches both host and children
- [Compliance checklist](./micro-frontends/compliance-checklist.md) — the
  per-module rules a frontend is checked against
- [Build-time Artifacts](../guides/artifacts.md) — declaring the package, and
  materializing it into a consumer
- [Dependency Management](../guides/dependency-management.md) — declaring and
  resolving what a module consumes



---

# "Registry Entries"

## Registry Entries


A registry entry declares a frontend artifact to the Wippy backend so the Web
Host can discover and serve it. The artifact can be a micro frontend app or a
reusable web component. Its declaration spans the module's `_index.yaml`, the
`wippy` block in `package.json`, and the generated `wippy-meta.json` file.

For the `wippy/views` module setup that processes these entries at runtime, see [Views](../../framework/views.md).



### What a Registry Entry Is


Every frontend artifact is declared as a `registry.entry` in the module's `_index.yaml`. The `kind: registry.entry` marker tells the Wippy registry that this entry carries metadata consumed by other modules rather than defining a Lua component directly.

> **Common trap:** `view.page` and `view.component` are **not** `kind` values. Always write `kind: registry.entry` and put the frontend artifact type in `meta.type`. `kind: view.page` and `kind: view.component` are invalid shapes.

Minimal correct shape:

```yaml
- name: main
  kind: registry.entry
  meta:
    type: view.page
```

```yaml
version: "1.0"
namespace: app.views

entries:
  - name: main
    kind: registry.entry
    meta:
      type: view.page
      name: main
      title: Admin Panel
      icon: tabler:layout-dashboard
      order: 0
      announced: true
      secure: false
      url: /app
      base_path: app/main
      entry_point: app.html
      mountRoute: /home/:part(.*)*
```

The `meta` block is what `wippy/views` reads. The `meta.type` field discriminates between the two supported artifact kinds.



### The `meta.type` Discriminator


| Value | Meaning |
|---|---|
| `view.page` | A micro frontend app (full SPA), rendered through the page's selected iframe or Web Fragment engine |
| `view.component` | A Web Component (custom element) that can be embedded anywhere in a page |

Every other field in `meta` is interpreted in the context of this type. Fields that apply to one type and not the other are described in the per-type reference pages ([view.page](./view-page.md), [view.component](./view-component.md)).



### The `specification` Marker


Frontend packages should declare `"specification": "wippy-component-1.0"` at the top level of `package.json`. The marker identifies the package metadata and API response shape. `@wippy-fe/vite-plugin` validates the value when it is present.

```json
{
  "name": "@wippy/example-widget",
  "version": "1.0.0",
  "specification": "wippy-component-1.0",
  "browser": "dist/index.js",
  "wippy": {
    "type": "component",
    "tagName": "example-widget"
  }
}
```

The marker does not change rendering behavior. `wippy/views` carries the bundled value into page and component descriptors, or supplies `wippy-component-1.0` for legacy bundles that omit it; registry YAML validation does not depend on this field.



### The `wippy-meta.json` Contract


`@wippy-fe/vite-plugin` emits a `wippy-meta.json` file alongside the built
bundle. It is the canonical source for the artifact-authored runtime metadata:
props schema, events schema, title, icon, and proxy injection settings.

Metadata responsibilities:

- **Emitted by:** `wippyPagePlugin()` for `view.page` apps and `wippyComponentPlugin()` for `view.component` web components.
- **Generated from:** `package.json`; do not hand-author `wippy-meta.json`.
- **Consumed by:** `wippy/views`, which reads it from the served bundle root when building page/component descriptors and API responses.
- **Overridden by:** `_index.yaml`, which remains authoritative for deployment policy and every field it explicitly declares.

When `wippy/views` loads a `registry.entry`, it reads `wippy-meta.json` from the artifact's served bundle root (`url + base_path`) for both pages and components. YAML always wins: `_index.yaml` takes precedence for every field it declares. `wippy-meta.json` provides the defaults that `wippy/views` reads when no YAML override is present for a given field. Deployment-policy fields — `announced`, `secure`, `url`, `mountRoute`, and `base_path` — must be set in `_index.yaml` because they express operator decisions rather than component authorship; there is no `package.json`/`wippy-meta.json` authoring surface for them. (`base_path` is honored for both pages and components; the current app-template component entries simply omit it.)

By contrast, `entry_point` is FE-authored *and* YAML-overridable. For pages it comes from `wippy.path` (which `@wippy-fe/vite-plugin` **requires**; omitting it makes the plugin throw `wippy.path is required for a page package`). For components it comes from the top-level `browser` field; `wippy.tagName` declares the custom-element name separately. The `meta.entry_point` field in `_index.yaml` is an optional per-deployment override on top of that authored default; it is not a YAML-only field.

A component author writes display metadata once in the `wippy` block of
`package.json`, and the vite plugin records it in `wippy-meta.json` as the
author defaults. The operator sets routing and access policy in YAML and can
also override display fields there.



### Common Fields


These fields appear in the `meta` block for both `view.page` and `view.component` entries.

| Field | Type | Default | Description |
|---|---|---|---|
| `type` | string | — | `view.page` or `view.component` (required) |
| `name` | string | entry name | Identifier used in API responses |
| `title` | string | — | Human-readable display name |
| `icon` | string | — | Iconify reference, e.g. `tabler:layout-dashboard` |
| `announced` | boolean | — | Controls visibility in listing APIs; semantics differ by type (see below) |
| `secure` | boolean | `false` | Requires authentication to access |
| `url` | string | — | Base URL prefix for static file serving (CDN origin or local mount path) |
| `entry_point` | string | `index.html` / `index.js` | Entry file name within the static directory |



#### `announced` Semantics by Type


The `announced` flag has different consequences depending on `meta.type`:

- **`view.page`**: controls whether the page appears in the navigation sidebar (`GET /api/public/pages/list`). Setting `announced: false` hides the page from navigation but the page still loads if accessed directly. This is a legitimate pattern for embedded or auxiliary pages.

- **`view.component`**: gates inclusion in `GET /api/public/components/list`. If `announced: false`, the component is excluded from that endpoint entirely, which means the Web Host never injects its script tag and `customElements.get(tagName)` stays undefined. For components that need autoload, `announced: true` is required — see [view.component](./view-component.md) for details.



### How Serving Fields Combine


For micro frontend apps, the three fields compose to produce the HTML URL the Web Host loads:

```
<url>/<base_path>/<entry_point>
```

For example, with `url: /app`, `base_path: app/main`, `entry_point: app.html`, the host fetches `/app/app/main/app.html`.

The separation between `base_path` and `entry_point` is intentional. The Web Host injects `<url>/<base_path>/` as an HTML `<base>` tag into the loaded page, which governs how the browser resolves all relative URLs inside that page. The entry file may sit in a subdirectory of the base — what matters is that the base points to the common root from which all resources can be reached relatively.

For example, if a bundle has this layout:

```
static/
  shared/
    vendor.js
  app/
    index.html    ← entry_point: app/index.html
    app.js
```

and `index.html` references `../shared/vendor.js`, then `base_path` must point to `static/` (the directory containing both `app/` and `shared/`), not to `app/`. Setting `base_path: app` would make `../shared/vendor.js` resolve outside the served directory and 404.

In the common case where all assets sit alongside the entry file, `base_path` and the directory containing `entry_point` are the same level, so the distinction is invisible. It only matters when a bundle shares resources across sibling directories.

For web components, the host composes the served URL the same way:

```
<url>/<base_path>/<entry_point>
```

The current app-template component entries omit `base_path`, but it is supported and composes the same way (`<url>/<base_path>/<entry_point>`) — so in those entries the URL collapses to `<url>/<entry_point>`. The difference from pages is that a component is injected as a `<script type="module">` rather than getting its own injected HTML `<base>` tag.



---

# "Micro Frontend Apps (view.page)"

## Micro Frontend Apps (view.page)


A `view.page` entry describes a full single-page application that the Web Host
loads through the selected iframe or Web Fragment engine. Each entry can claim
a path in the host router and receives CSS, configuration, and host APIs through
the engine's proxy adapter.



### Frontend Fields (package.json wippy block)


These fields are authored by the FE developer in the `wippy` block of `package.json`. The vite plugin bakes them into `wippy-meta.json` at build time, and `wippy/views` reads them from there as defaults.

> **All fields in this section can be overridden by the operator in `_index.yaml`. YAML always takes precedence.**



#### Display and Navigation


| Field | Type | Default | Description |
|---|---|---|---|
| `title` | string | — | Label shown in the navigation sidebar and browser tab |
| `icon` | string | — | Iconify icon reference, e.g. `tabler:layout-dashboard` |
| `type` | string | — | Must be `"page"` |
| `path` | string | — | Path to the built HTML entry file within the bundle output directory |



#### Render engine


`renderEngine` selects the [page render engine](../web-host/render-engines.md) for this page (`view.page` only). The proxy API is portable across engines, but browser layout and DOM behavior can differ; review the fragment limitations before opting a page into that engine.

| Value | Effect |
|-------|--------|
| `"auto"` _(default, or omitted)_ | Follow the deployment's global switch (`hostConfig.renderEngine`, set by the facade [`render_engine`](../../framework/facade.md#render-engine) parameter). |
| `"iframe"` | Always render as a srcdoc iframe, regardless of the switch. Use for pages with reframed-incompatible tech — pointer hit-testing (`elementFromPoint`), viewport-unit (`vh`/`vw`, `matchMedia`) layout, `position: fixed`. |
| `"fragment"` | Prefer the [Web Fragment](../web-host/render-engines.md) engine. Under a global-`fragment` deployment: always. Under a global-`iframe` deployment: only if a runtime capability probe confirms the [`/@fragment` gateway](../../framework/views.md#web-fragments-gateway) + proxy are present (fail-safe to iframe otherwise). |

```json
{
  "wippy": {
    "type": "page",
    "renderEngine": "auto"
  }
}
```

See [Render Engines](../web-host/render-engines.md) for the full engine model and fragment limitations.



#### Proxy Configuration


Proxy injection has two surfaces. The FE developer authors defaults in the
frontend `package.json` `wippy` block with lower-camel-case keys
(`themeConfig`, `primevue`, `customCss`); the Vite plugin bakes them into
`wippy-meta.json`. The operator overrides them with a `proxy:` block under
`meta:` in registry YAML. Registry fields follow their documented schema rather
than a universal casing rule. Nested proxy keys retain their defined
lower-camel-case names, and the host deep-merges that YAML over the baked
frontend defaults without converting keys.

```json
{
  "wippy": {
    "type": "page",
    "proxy": {
      "enabled": true,
      "injections": {
        "css": {
          "themeConfig": true,
          "iframe": true,
          "primevue": true,
          "markdown": false,
          "customCss": true,
          "customVariables": true
        },
        "tailwindConfig": false,
        "resizeObserver": false,
        "preventLinkClicks": false,
        "iconifyIcons": false,
        "errorCapture": true
      }
    }
  }
}
```

In the iframe engine, `proxy.injections` configures the assets added by the
srcdoc proxy. If it is omitted, that adapter uses permissive defaults and
enables most injections. Web Host 1.0.56 carries `proxy.enabled` as metadata but
does not use it as a runtime toggle.

Web Host 1.0.56 does not translate these flags to the Fragment engine. The
Fragment gateway always supplies `loading.js`, `proxy-fragment.js`, and the four
Host stylesheets (theme config, iframe scrollbar styles, PrimeVue/Tailwind, and
Markdown); its proxy also installs error capture unconditionally. A page that
can fall back to iframe should still declare its iframe injection intent
explicitly.

The list below shows the **recommended explicit iframe values for a typical
Vite micro frontend app** — not the runtime defaults — so package reviewers can
see the page's fallback behavior.



##### Recommended explicit injection values


These are the flags a micro frontend app typically declares for its iframe
delivery path. They are not the runtime defaults, and Web Host 1.0.56's Fragment
gateway does not use them.

- `css.themeConfig` (`true`) — CSS custom properties for the active theme
- `css.iframe` (`true`) — required default themed scrollbar styling; `iframe` is a historical name and the current sheet does not provide layout resets
- `css.primevue` (`true`) — PrimeVue component base styles
- `css.markdown` (`false`) — markdown rendering styles
- `css.customCss` (`true`) — child-projected custom CSS
- `css.customVariables` (`true`) — child-projected CSS variable overrides
- `tailwindConfig` (`false`) — host Tailwind config object (CDN Tailwind only)
- `resizeObserver` (`false` for full SPAs) — child body-size updates to the host
- `preventLinkClicks` (`false` for pages) — install the iframe engine's raw-`<a>` classifier hook; use `@wippy-fe/router` for portable link classification across engines
- `iconifyIcons` (`false`) — pre-load host Iconify collections
- `errorCapture` (`true`) — forward uncaught page errors to the host

Most full SPA pages set `resizeObserver: false` and `preventLinkClicks: false` because they manage their own layout and routing. The `main` app in the template sets `errorCapture: true` to surface uncaught errors during development.

There is no dedicated web-font injection flag. Google Fonts are delivered through `theming.global.customCSS` (an `@import` in the theme's custom CSS), injected by the existing `css.customCss` flag.

Full flag reference and runtime defaults: [CSS Injection](../web-host/css-injection.md).



### Operator Configuration (_index.yaml)


These fields are set by the operator in the `meta` block of the `_index.yaml` registry entry. Most of them — `announced`, `secure`, `url`, `base_path`, `mountRoute`, `auto_register`, `inline` — represent deployment policy (routing, access control, and serving) that only makes sense at deploy time and has no `package.json` authoring surface. The one exception is `entry_point`: it is **FE-authored** (the vite plugin requires `wippy.path` in `package.json` and bakes it into `wippy-meta.json`), and the `meta.entry_point` field is only an **optional per-deployment override** of that baked default.

> **Required YAML shape:** a page entry is `kind: registry.entry` with `meta.type: view.page`. Do not write `kind: view.page`.

```yaml
- name: main
  kind: registry.entry
  meta:
    type: view.page
    name: main
```



#### URL and File Serving


| Field | Type | Default | Description |
|---|---|---|---|
| `url` | string | — | Base URL prefix where the bundle is mounted (CDN origin or local `http.static` path). YAML-only — no `package.json` surface |
| `base_path` | string | — | Subdirectory within the static mount. YAML-only — no `package.json` surface |
| `entry_point` | string | `index.html` | HTML file to load; combined with `url` and `base_path`. FE-authored as `wippy.path` in `package.json` (baked into `wippy-meta.json`); the YAML value is an optional per-deployment override |

The resolved entry URL is `<url>/<base_path>/<entry_point>`. An operator deploys the same bundle under multiple entries by pointing different `_index.yaml` entries at the same `base_path` with different `entry_point` or `config_overrides` values.

Unlike `url` and `base_path`, `entry_point` is not a deploy-only field. It is authored by the FE developer as `wippy.path` in the `package.json` `wippy` block and baked into `wippy-meta.json` by the vite plugin — the plugin **requires** it and throws `wippy.path is required for a page package` if it is omitted. The `meta.entry_point` field in `_index.yaml` only overrides that baked default per deployment; the resolution order is YAML `entry_point` → bundled `wippy.path` → `index.html`.



#### Visibility and Access


| Field | Type | Default | Description |
|---|---|---|---|
| `announced` | boolean | — | `true` → page appears in `GET /api/public/pages/list` and the nav sidebar |
| `secure` | boolean | `false` | `true` → requires authentication; unauthenticated requests get a 401 |
| `inline` | boolean | `false` | `true` → page is hidden from all listings (sidebar, API); use for embedded artifact viewers or auxiliary routes |

`announced: false` hides the page from navigation but does not prevent loading. The page can still be embedded or reached through its route. `inline: true` is stricter — it suppresses the page from all public-facing listings.



#### Mount Route


| Field | Type | Default | Description |
|---|---|---|---|
| `mountRoute` | string | — | Claims a URL path in the host router; the host renders this page when the browser navigates to a matching path |

> **Casing exception:** the current registry schema reads `meta.mountRoute` and
> stores it in the registry's internal `mount_route` field; API output uses
> `mountRoute` again. Use the authored lower-camel-case spelling shown here.

`mountRoute` accepts only the v1 catch-all form — `/:part(.*)*` (root) or `/<literal-prefix>/:part(.*)*`, where the prefix is one or more lowercase-alphanumeric-plus-hyphen segments ending in the required `:part(.*)*` wildcard. Arbitrary Vue Router patterns — named params, custom regex, or a different param name (e.g. `/home/:id`, `/users/:userId(\d+)`) — are rejected: the backend records a `syntax` mount-route conflict, `GET /api/public/pages/routes` returns HTTP 500, and Host startup stops with the error relayed through the Host error handler. The `:part(.*)*` wildcard lets the child application manage its own sub-routes while the host keeps ownership of the top-level path.

```yaml
mountRoute: /home/:part(.*)*
```

When the Web Host starts, it fetches `GET /api/public/pages/routes` and calls `router.addRoute()` for each entry that has a `mountRoute`. See [Dynamic Routing](./dynamic-routing.md) for the full sync mechanism.



#### Per-Page Configuration Overrides


| Field | Type | Description |
|---|---|---|
| `config_overrides` | object | Deep-merged over the AppConfig values the Web Host injects into the page context |

`config_overrides` is the registry wrapper name. Its nested object already uses
the frontend schema's lower-camel-case keys, such as
`customization.customCSS` and `customization.cssVariables`. The Web Host
deep-merges those exact keys on top of bundled `wippy.configOverrides` from
`wippy-meta.json`; the YAML value wins per nested key.

`config_overrides` changes the page's injected AppConfig. It does **not** change proxy injection flags. In particular, `config_overrides` never affects `proxy.injections`, `wippy.proxy.injections`, or the runtime defaults for CSS/script injection. To override proxy injection flags for a deployment, use `meta.proxy` as described in [Operator proxy override](#operator-proxy-override-_indexyaml).

A typical use case is running the same bundle with a custom colour palette:

```yaml
- name: iframe-demo-themed
  kind: registry.entry
  meta:
    type: view.page
    name: iframe-demo-themed
    title: Iframe Demo (Custom Palette)
    icon: tabler:paint
    order: 4
    announced: false
    secure: false
    url: /app
    base_path: app/iframe-demo
    entry_point: app.html
    mountRoute: /demo-themed/:part(.*)*
    config_overrides:
      customization:
        cssVariables:
          "--p-primary": "#7c9ed9"
          "--p-primary-color": "#7c9ed9"
          "--p-danger": "#e8a0a0"
        customCSS: |
          /* Palette values here are an intentional page-theme definition, not module CSS. */
          :root { font-family: var(--wippy-brand-font, sans-serif); }
```

Note that `announced: false` is valid for `view.page` entries — the page is reachable via its `mountRoute` but does not appear in the sidebar.



#### Operator proxy override (_index.yaml)


The proxy injection defaults baked into `wippy-meta.json` (from the
`package.json` `wippy` block) can be overridden per deployment with a `proxy:`
block placed **under `meta:`** in the registry entry. Facade requirement names
use their documented snake_case names. The wrapper is `config_overrides`, while
the registry schema defines the route field as `mountRoute`, stores it in the
registry's internal `mount_route` field, and emits `mountRoute` in API output.
Nested proxy/config objects are passed through and retain their defined
lower-camel-case keys. The host deep-merges `meta.proxy` over bundled
`wippy.proxy`.

Use `meta.proxy`, not `data.proxy`. Keep top-level backend fields
such as `config_overrides` in snake_case, but preserve nested proxy/config keys
such as `themeConfig` and `customCss`; keep the `injections` wrapper.
Do not invent `meta.config` or `meta.configOverrides`; the exact per-page
override wrapper is `meta.config_overrides`.

Keep the two frontend spellings distinct:

- Backend `meta.proxy.injections.css.customCss` remains
  `wippy.proxy.injections.css.customCss`.
- Backend `meta.config_overrides.customization.customCSS` projects to
  frontend `wippy.configOverrides.customization.customCSS` and runtime
  `config.theming.global.customCSS`.
- Do not invent an `appConfig` wrapper around either frontend shape.

```yaml
- name: dashboard
  kind: registry.entry
  meta:
    type: view.page
    name: dashboard
    url: /app
    base_path: app/dashboard
    entry_point: app.html
    proxy:
      enabled: true
      injections:
        css:
          themeConfig: true
          iframe: true
          primevue: true
          customCss: true
          customVariables: true
        tailwindConfig: false
        iconifyIcons: false
```

Only the keys you set are overridden; everything else keeps the value baked into `wippy-meta.json`. Full flag reference and runtime defaults: [CSS Injection](../web-host/css-injection.md).



---

# "Web Components (view.component)"

## Web Components (view.component)


A `view.component` entry describes a reusable custom element that the Web Host
can discover, inject, and register automatically. Unlike a page, a component
has no iframe of its own. It is a custom HTML tag that can appear wherever a
page or host template places it.

For guidance on writing the component implementation, see [Web Component](../micro-frontends/web-component.md).



### Frontend Fields (package.json wippy block)


These fields are authored by the FE developer in the `wippy` block of `package.json`. The vite plugin bakes them into `wippy-meta.json` at build time, and `wippy/views` reads them from there as defaults.

> **YAML can override `tagName`, `props`, and `events` through `meta.tag_name`, `meta.props`, and `meta.events`.** Build configuration selects `wippyComponentPlugin()`. The optional package `type` is metadata that the selected plugin validates when present; it has no separate YAML override.

| Field | Type | Default | Description |
|---|---|---|---|
| `type` | string | `"widget"` in the runtime descriptor | Optional; when present, must be `"component"` or `"widget"`. Build configuration, not this field, selects the Vite plugin |
| `tagName` | string | — | Custom element name. The 0.0.56 plugin requires a lowercase ASCII name that starts with a letter, contains a hyphen, uses only letters/digits/hyphens, and is not an HTML reserved custom-element name |
| `props` | object | — | JSON Schema describing the component's accepted attributes |
| `events` | object | — | JSON Schema describing the custom DOM events the component emits |



#### `wippy.type` in `package.json`


Web component packages may set `"type": "widget"` or `"type": "component"`
(not `"page"`) inside their `wippy` block. The app template uses `"widget"`;
the component plugin accepts either value or an omitted field and rejects page
metadata.

```json
{
  "specification": "wippy-component-1.0",
  "wippy": {
    "tagName": "example-reaction-bar",
    "type": "widget",
    "props": {
      "type": "object",
      "properties": {}
    },
    "events": {
      "type": "object",
      "properties": {}
    }
  }
}
```

At deploy time, the operator's YAML `meta.tag_name` is authoritative and
overrides the bundled value. `wippy.tagName`, baked into `wippy-meta.json` from
`package.json`, is the fallback when the YAML entry omits `tag_name` (resolution
order: YAML `meta.tag_name` → bundled `wippy.tagName`). Keep the values
synchronized; YAML wins if they differ.



#### Props Schema


The `wippy.props` key in `package.json` is a JSON Schema object describing the component's accepted attributes. The vite plugin includes it in `wippy-meta.json`, and the Web Host uses it when exposing component metadata to consumers such as the chat artifact renderer and the tag sanitizer (which needs to know which attributes are legitimate so it doesn't strip them).

```json
{
  "wippy": {
    "props": {
      "type": "object",
      "properties": {
        "reactions": {
          "type": "array",
          "items": { "type": "string" },
          "default": ["👍", "👎", "❤️", "🎉", "🤔"],
          "description": "Array of emoji reactions to display"
        },
        "allow-multiple": {
          "type": "boolean",
          "default": false,
          "description": "Whether multiple reactions can be active simultaneously"
        }
      }
    }
  }
}
```

Attribute names in `properties` use the HTML attribute convention (kebab-case). The schema's `default` values are also applied at runtime by the web-component prop parser when an attribute is absent.



#### Events Schema


The `wippy.events` key mirrors the props shape but describes custom DOM events the component emits via `useEvents()`. Each key is an event name; the value is a JSON Schema for the event's detail payload.

```json
{
  "wippy": {
    "events": {
      "type": "object",
      "properties": {
        "reaction": {
          "type": "object",
          "properties": {
            "emoji": { "type": "string" },
            "count": { "type": "number" },
            "active": { "type": "boolean" }
          },
          "description": "Fired when a reaction is toggled"
        }
      }
    }
  }
}
```

The Web Host's chat message sanitizer allowlists component attributes from the
projected descriptor's `wippy.props.properties`. Registry `meta.props` overrides
the bundled `wippy.props` value before that descriptor reaches the Host. Event
schemas document emitted custom events for tooling and consumers; they are not
used to allow DOM event listener attributes through sanitized chat content.



### Operator Configuration (_index.yaml)


These fields are set by the operator in the `meta` block of the `_index.yaml` registry entry. Most represent pure deployment policy — routing, access control, and serving — that only makes sense at deploy time and has no `package.json` authoring surface (`announced`, `secure`, `url`, `auto_register`). Two fields, `tag_name` and `entry_point`, are different: they are **FE-authored** in `package.json` (baked into `wippy-meta.json`) and the YAML keys are only **optional per-deployment overrides** of those bundled values.

| Field | Type | Default | Description |
|---|---|---|---|
| `tag_name` | string | `wippy.tagName` | FE-authored as `wippy.tagName` in `package.json` (required by the vite plugin); the YAML key overrides the bundled value. Keep the override browser-valid and synchronized with the plugin-safe authored name |
| `announced` | boolean | `false` | Must be `true` for the component to appear in `/api/public/components/list`. Falls back to `meta.public` if that is set. |
| `auto_register` | boolean | `false` | `true` → Web Host autoloads and registers the component at startup |
| `secure` | boolean | `false` | Requires authentication |
| `url` | string | — | Static mount path for the component's built bundle |
| `base_path` | string | `""` | Optional subpath appended to `url` to form the project root; the resolved bundle URL composes as `<url>/<base_path>/<entry_point>`. Honored identically to pages, though current app-template component entries omit it |
| `entry_point` | string | `wippy.browser` → `index.js` | FE-authored as the top-level `browser` field in `package.json` (baked into `wippy-meta.json`); the YAML key overrides the bundled value, falling back to `index.js`. Entry module file; the host injects this as a `<script type="module">` |

A minimal entry looks like this:

```yaml
- name: reaction-bar
  kind: registry.entry
  meta:
    type: view.component
    name: reaction-bar
    tag_name: example-reaction-bar
    announced: true
    secure: false
    auto_register: true
    url: /app/wc/reaction-bar
    entry_point: index.js
```



### The Three Gates for Autoload


For the Web Host to autoload a component, all three conditions must hold simultaneously:

1. **`announced: true`** — `wippy/views` filters by this flag server-side in `list_components.lua`. There is no query parameter to bypass it. A component with `announced: false` never appears in `/api/public/components/list` regardless of any other setting.

2. **`auto_register: true`** — the host's `loadGlobalAutoloadWidgets` function queries the list endpoint with `?auto_register=true`. Components without this flag are excluded from that filtered response.

3. **The tag is not yet registered** — before injecting the script, the host checks `customElements.get(tagName)`. If the tag is already defined (e.g. from a previous navigation), the host skips the injection to avoid double-defining.

If any gate is missing the component is silently absent. To verify: `curl /api/public/components/list?auto_register=true` — your tag must appear in the response.



### The Autoload Sequence


During Web Host runtime initialization, each context that owns global autoload runs the following sequence. It is not triggered after every page mount:

1. `GET /api/public/components/list?auto_register=true` — fetches all announced, auto-registering components.

2. For each component whose `customElements.get(tagName)` is `undefined`, the host appends to `document.head`:

   ```html
   <script type="module" src="/app/wc/reaction-bar/index.js?declare-tag=example-reaction-bar"></script>
   ```

   The `?declare-tag=` query parameter is the channel that tells the entry chunk which custom element name to register under.

3. The entry chunk calls `define(import.meta.url, ElementClass)`. Component authors import `define` from `@wippy-fe/webcomponent-vue` (or `@wippy-fe/webcomponent-core`), which re-export the proxy's `define`; at runtime the import map resolves it to the single `@wippy-fe/proxy` instance. The `define` helper reads `new URL(import.meta.url).searchParams.get('declare-tag')` and calls `customElements.define(tagName, ElementClass)`.

4. Vue (or any framework) renders a `<example-reaction-bar>` element. The browser upgrades the element, `connectedCallback` fires, and `WippyVueElement` mounts its Vue app inside a shadow root.



### When to use `auto_register: false`


Setting `auto_register: false` excludes the component from the global autoload sweep. This is appropriate when:

- The component is large and should only load on pages that explicitly need it.
- The component is registered programmatically via `loadByTagName('example-heavy-chart')` (imported from `@wippy-fe/proxy`) at the call site.
- The component is an internal building block used only within another bundle, not as a standalone custom element.

```ts
import { loadByTagName } from '@wippy-fe/proxy'

await loadByTagName('example-heavy-chart')
```

Lazy registration lets the initial page load stay lightweight. The component still needs `announced: true` for `loadByTagName()` to resolve it through the API — the `GET /components/by-tag/{tag}` endpoint returns `404 "Component is not announced"` when the flag is `false`.



---

# "Dynamic Routing"

## Dynamic Routing


The Web Host combines statically defined system routes with page mount routes
fetched from the backend at startup. A new `view.page` entry with a `mountRoute`
claim therefore takes effect without a Web Host bundle change.

![Mount route sync](../diagrams/mountroute-sync.svg)



### Mount Route Sync at Startup


When the Web Host application initialises, before it renders any navigation, it calls:

```
GET /api/public/pages/routes
```

The response is an envelope `{ success, count, routes }`, where `routes` is a map of mount-route pattern → page id (it includes hidden/unannounced pages that still claim a URL). For each entry, the host registers a Vue Router route that maps the declared path to the page loader component, adding it as a child of the `'app'` parent route.

```typescript
// Simplified from the Web Host bootstrap
const { data } = await api.get('/api/public/pages/routes')
for (const [mountRoute, pageId] of Object.entries(data.routes)) {
  router.addRoute('app', {
    path: mountRoute,
    component: MountRoutePage,
    props: () => ({ pageId }),
  })
}
```

After this point, navigating to `/home/anything` causes the router to render the `main` page through its selected engine, and navigating to `/demo/anything` does the same for the `iframe-demo` page — without any hard-coded knowledge of those paths in the host bundle.



### Claiming a Path with `mountRoute`


A `view.page` entry claims a host router path by setting `mountRoute` in its `_index.yaml` `meta` block:

```yaml
- name: main
  kind: registry.entry
  meta:
    type: view.page
    mountRoute: /home/:part(.*)*
```

The current registry schema reads the authored field as `mountRoute`, stores it
in the registry's internal `mount_route` field, and emits `mountRoute` in API
output. Use the lower-camel-case spelling shown above.

`mountRoute` accepts only the catch-all forms `/:part(.*)*` (root) or `/<literal-prefix>/:part(.*)*`, where the prefix is one or more lowercase-alphanumeric-plus-hyphen literal segments ending in the required `:part(.*)*` wildcard. Arbitrary Vue Router patterns — named params, custom regex, or different param names (e.g. `/home/:id`, `/users/:userId(\d+)`) — are rejected. For backend `view.page` entries, `validate_mount_route_syntax` makes `GET /api/public/pages/routes` return HTTP 500, so Host startup stops before those entries reach its router. After a successful response and configuration merge, the Host separately validates the resulting route set, including syntax and conflicts with system routes. The wildcard segment `:part(.*)*` lets the child application manage its own sub-routes (e.g. `/settings`, `/profile/edit`) while the host owns the `/home` prefix.

Two entries must not claim the same route. If two `view.page` entries claim the
**same** `mountRoute`, the backend validator (`validate_mount_routes` in
`page_registry.lua`) records a duplicate-route conflict in the same issues list
as syntax errors. `GET /api/public/pages/routes` then returns HTTP 500, Host
startup stops, and the error is relayed through the Host error handler. The
duplicate is **not** silently ignored.

Vue Router route-resolution precedence still applies between a root catch-all (`/:part(.*)*`) and a more-specific system route (`chat`, `c`, `web`, `page`, `keeper`, `login`, `logout`) or a longer literal-prefix mount: the more-specific route matches. That priority is not duplicate-route handling.



### The URL Sync Loop


Once a page is loaded in its runtime context, the child application navigates
internally with its own router. The host reflects those navigations in its URL
bar so the browser's back button, bookmarks, and copied URLs work correctly.
The proxy bridge synchronizes the two routers for both page engines.

![Frontend Registry](../diagrams/frontend-registry.svg)



#### Child → Host: `CmdRouteChanged`


When the child application's router commits a navigation (e.g. the user moves
from `/settings` to `/profile` under the `/home` mount), it reports the internal route through
the proxy bridge. The iframe adapter posts to `window.parent`; the Fragment
adapter routes the same protocol to its captured host window:

```typescript
// In the child application, on internal route change.
// App code must never post these messages directly — use the proxy API:
import { host } from '@wippy-fe/proxy'

host.onRouteChanged('/profile', navId)   // internal route only; the host prepends the mount prefix. navId is an optional number
```

The proxy serializes this over an internal wire envelope. That protocol is not an application API: do not copy it or call `window.parent.postMessage` directly.

The host's message handler intercepts this, calls `router.push(path)` to update the URL bar via an SPA route change (adding a browser-history entry) without triggering a full page reload, and then posts back:



#### Host → Child: `UrlWasUpdatedInParent`


After the host updates its URL bar, the proxy emits `@history` to the child. `@wippy-fe/router` consumes that event and reconciles the memory router.

The host sends back the child's **internal** route (the sub-path after the mount prefix), not the full host path — so the round-trip is symmetric: the child posts `internalRoute: '/profile'`, the host sets its URL bar to `/home/profile`, and echoes `path: '/profile'` back, which the child's memory router pushes verbatim. The child listens via the `@history` event channel and treats it as confirmation that the host's URL is now consistent with its internal state.

The round-trip keeps the host URL bar, the child router, and the browser history entry in sync without the host needing to know anything about the child's internal routing structure.



### `classifyLink`


In the iframe engine, `preventLinkClicks: true` installs a document-level hook that intercepts raw `<a>` clicks before the browser handles them (see [view.page](./view-page.md)). The Web Fragment adapter in Web Host 1.0.56 does not install this raw-click hook. For portable Vue navigation, use `AutoRouterLink` from `@wippy-fe/router`; it calls the same `classifyLink` API in either engine.

The classifier returns one of four results:

| `LinkKind` | Condition | Action |
|---|---|---|
| `host-nav` | Top path segment matches a known `mountRoute` literal, a baked-in system route (`chat`, `c`, `web`, `page`, `keeper`, `login`, `logout`), or a root-mount catch-all | `preventDefault` + `host.navigate(normalizedPath)` |
| `child-nav` | The child router resolves the path to a real (non-catch-all) route, or nothing else has claimed it | The subapp's router decides in-app; the host does NOT `preventDefault` or reload the page context |
| `external` | Different origin, or a non-`http` scheme (`javascript`/`mailto`/`tel`/`sms`/`ftp`/`file`/`data`/`blob`) | Browser default (e.g. opens in a new tab) |
| `ignore` | Empty `href` or a pure hash (`#…`) | `preventDefault` |

The classifier checks the page's local router first, so a link the child can resolve itself stays in-app.

`classifyLink` consults the same routes list fetched at startup. If the child
router does not claim `/demo/step-2`, the link is classified as `host-nav`
because `/demo/:part(.*)*` is a registered mount route — the host navigates to
the `iframe-demo` page rather than doing a full page reload.

This means a child application does not need to know about other pages in the
system. In an iframe with `preventLinkClicks: true`, an ordinary
`<a href="/demo/step-2">` is intercepted and classified. Use `AutoRouterLink`
when the same navigation must work in both page engines.



---

# "Web Host Overview"

## Web Host Overview


This page is an architecture reference. It explains deployment boundaries and
entry points; setup belongs in the linked facade and micro-frontend guides.

The Wippy Web Host is a Vue 3 single-page application built with the
Feature-Sliced Design methodology and delivered from
`https://web-host.wippy.ai`. It hosts the user-facing pages and UI components
of a Wippy application. Configure it through the `wippy/facade` backend module;
you do not build or deploy it with the application.

![Wippy FE architecture](../diagrams/fe-arch-overview.svg)



### Three-Layer Model


A running Wippy application is composed of three nested layers:

**Layer 1 — Page served by `wippy/facade`.** This is your backend-rendered HTML page. The `wippy/facade` module registers a static file server and a `/facade/config` endpoint on your Wippy gateway. When a user navigates to your application, `wippy/facade` serves a thin HTML page that loads the Web Host JS-module entry from the CDN (`module.js` for compat, `managed-layout.js` for managed) and initializes it with config from `/facade/config`. The page itself carries no Vue or React — it is intentionally thin.

**Layer 2 — Web Host.** The Web Host bundle loads as a JS module that takes over
the entire page and its browser history. It owns the Wippy chrome: navigation,
chat, session management, and the page rendering surface. It receives its full
configuration from the page's init call and contains no deployment-specific
URLs or tokens. The same CDN bundle can therefore serve different deployments.
For manual, facade-less embeddings, the host can run inside an iframe through
the `iframe.html` entry described below.

**Layer 3 — Child micro-frontends.** The Web Host renders `view.page` modules
through the configured page engine: a legacy srcdoc iframe or a Web Fragment.
It mounts `view.component` modules as custom elements. The iframe engine provides
a separate browsing context. A Web Fragment uses a reframed realm reflected
into the host document and is not an isolation boundary; a component's shadow
root isolates selectors, not authority. Each surface receives the appropriate
proxy adapter for Wippy API access, authentication context, theme delivery, and
communication without needing deployment-specific URLs.

```
Page (wippy/facade HTML — loads module.js / managed-layout.js)
  └─ Web Host (takes over the page + browser history)
       ├─ Chat UI, navigation, sidebar
       └─ Child micro-frontends
            ├─ view.page → srcdoc iframe or Web Fragment + proxy adapter
            └─ view.component → custom element + @wippy-fe/proxy ESM
```



### Entry Points


The Web Host CDN serves several entry points from the same versioned directory.
Choose one according to the integration. Each entry is available at
`<release-tag>/<entry>`, such as `/<release-tag>/module.js`.

| Entry | Use case |
|-------|----------|
| `module.js` | Full app in **compat** mode — the standard nav-sidebar + page-area + chat-right-panel shell. Mounted directly into the page via `window.initWippyApp()`; takes over the whole page and its browser history. This is the entry the current `wippy/facade` serves by default. |
| `managed-layout.js` | Full app in **managed** mode — the declarative multi-panel layout. Served by the facade when `fe_mode = managed`. Early access (see [Multi-Panel Layout](./multi-panel-layout.md)). |
| `iframe.html` | Full app run **inside an iframe** for isolation or partial-page embedding. Use it for manual, facade-less embeddings where you supply config via a `SetConfig` PostMessage handshake. The facade itself loads the JS-module entries above, not this one. |
| `chat-iframe.html` | Minimal chat interface without sidebar or pages. Useful for embedding a focused chat widget. |
| `chat.js` | Headless ESM module exposing chat stores and WebSocket client. Use for building completely custom UIs. |
| `ws.js` | Standalone WebSocket service with no Vue or Pinia dependency. Use for low-level real-time integrations. |

For standard `wippy/facade`-based deployments you never reference these paths directly. The facade reads `fe_facade_url` from its configuration, selects the JS-module entry that matches `fe_mode` (`module.js` for compat, `managed-layout.js` for managed), and constructs the correct URL automatically.



### CDN Versioning


The Web Host is versioned by git tag. The canonical production URL pattern is:

```
https://web-host.wippy.ai/<release-tag>/
```

Where `<release-tag>` is the Web Host git release tag — either a stable release or a feature-branch preview deploy. The staging CDN is at `https://web-host.staging.wippy.ai/<release-tag>/`.

Normally, the `wippy/facade` module selects the version through its default
`fe_facade_url`, which points to a matching Web Host build. Updating
`wippy/facade` therefore moves the deployment to its corresponding Web Host
version. Child apps that share vendor libraries through the import map receive
the versions provided by that build.

To pin a specific Web Host version — to stay on a known-good build, or to opt into a feature-branch / early-access tag — override the `fe_facade_url` parameter:

```yaml
- name: fe_facade_url
  value: https://web-host.wippy.ai/<release-tag>
```

This pins the entire deployment to that build. See [CLI overrides](../../guides/cli.md) for the `-o` / `--override` syntax to set it at runtime instead.



### Tech Stack


The Web Host is built with Vue 3 (Composition API), PrimeVue + Tailwind CSS 3 for UI components, Pinia for state management, Vue Router for navigation, and Axios for HTTP.



#### Child dependency externalization


During development, fetch `<fe_facade_url>/import-map.json` and put every key from its `imports` object in Rollup externals, even if the current artifact does not import that key. Bundle an imported dependency only when its exact specifier is absent. Re-fetch when the Web Host tag changes or a new dependency is added.



### See Also


- [Facade Entry Point](./entry-point.md) — how the facade delivers the Web Host to users and what the config flow looks like
- [Bootstrap Sequence](./bootstrap.md) — what happens inside the Web Host after it receives configuration
- [Multi-Panel Layout](./multi-panel-layout.md) — managed layout mode for custom multi-panel shells
- [Packages](./packages.md) — the `@wippy-fe/*` npm packages available to child app developers
- [Facade module](../../framework/facade.md) — backend setup for `wippy/facade`
- [Render Engines](./render-engines.md) — the two page-render engines (srcdoc iframe vs Web Fragment)



---

# "Facade Entry Point"

## Facade Entry Point


This page is an integration reference. The shell bootstrap and manual iframe
blocks isolate specific contracts; they are not substitutes for a complete
login flow or application project.

The `wippy/facade` backend module delivers the Web Host to users. It serves the
HTML shell and `/facade/config`. The shell loads the Web Host module, checks the
browser's stored authentication token, redirects unauthenticated users, and
assembles deployment-specific configuration for the CDN-hosted frontend bundle.
The bundle itself contains no deployment-specific configuration.

![Facade entry point](../diagrams/facade-entry-point.svg)



### The HTML Page


When a user navigates to a Wippy application, the Web Host module takes over the
page and its browser history, so the host runs as the application rather than
inside an iframe.

The facade loads one of two JS-module entries depending on the configured `fe_mode`:

- **`module.js`** — the **compat** shell (default): the standard nav-sidebar + page-area + chat-right-panel layout.
- **`managed-layout.js`** — the **managed** shell (opt-in, early access): the declarative multi-panel layout.

A simplified version of the bootstrap call looks like this. The shipped shell
also loads configured extra scripts, installs the Web Host import map, handles
errors, and applies the persisted theme before this call:

```javascript
const response = await fetch('/api/public/facade/config')
if (!response.ok)
  throw new Error(`Facade config request failed: ${response.status}`)
const cfg = await response.json()

const storedAuth = localStorage.getItem('@wippy_token_info')
if (!storedAuth)
  throw new Error('Authentication is required before bootstrapping the host')
const { token } = JSON.parse(storedAuth)
if (typeof token !== 'string' || token.length === 0)
  throw new Error('Stored authentication does not contain a token')

await import(cfg.facade_url + cfg.module_file)

const appConfig = {
  $schema: `${cfg.facade_url}/schemas/wippy-context-2.0.xsd`,
  auth: {
    token,
    expiresAt: new Date(Date.now() + 86_400_000).toISOString(),
  },
  env: cfg.env,
  routePrefix: cfg.routePrefix,
  themeMode: window.wippyThemePersist?.read() || cfg.themeMode,
  apiRoutes: cfg.apiRoutes,
  axiosDefaults: cfg.axiosDefaults,
  theming: cfg.theming,
  hostConfig: cfg.hostConfig,
  context: { resourceId: '', resourceType: 'page' },
}

window.initWippyApp(appConfig, '#app')
```

> **Fetch path.** `/facade/config` is the path the facade registers on the
> public router. The requested URL also includes that router's prefix. With the
> example prefix `/api/public`, request `/api/public/facade/config`, as the
> shipped facade page and bootstrap example do. Contract descriptions below use
> the registry-local path.



### The Config Flow


The config flow has four steps:

1. The page's inline JavaScript calls `GET /facade/config` on the same origin as the page. This endpoint is registered by `wippy/facade` on the public router.
2. The shell reads `@wippy_token_info` from localStorage. If the value is missing or cannot be decoded, the browser redirects to `login_path`.
3. The shell loads `extraScripts`, installs the Web Host import map, and imports the module selected by `module_file`.
4. The shell adds `$schema`, `auth`, and `context` to the supported deployment fields, then calls `window.initWippyApp(appConfig, rootContainer?)`.

The Web Host receives that assembled `AppConfig` and proceeds with full initialization. From this point forward the page script is passive — all user interaction happens inside the mounted host.

The CDN-hosted bundle is identical across deployments; deployment-specific
URLs and branding arrive in the config response, while the bearer token comes
from browser storage.

> **Config response vs `AppConfig`.** `/facade/config` does not return a complete
> `AppConfig`: it has no `$schema`, `auth`, or `context`. Fields such as
> `facade_url`, `iframe_origin`, `iframe_url`, and `login_path` are shell settings,
> while `env`, `theming`, and `hostConfig` are inputs to the assembled `AppConfig`.



### The `/facade/config` Response


The config endpoint returns shell settings and Web Host configuration assembled
by `wippy/facade` from module parameters and the running environment. This is an
example configured response; optional JSON blocks that remain empty are omitted:

```json
{
  "facade_url": "https://web-host.wippy.ai/<release-tag>",
  "iframe_origin": "https://web-host.wippy.ai",
  "iframe_url": "https://web-host.wippy.ai/<release-tag>/iframe.html?waitForCustomConfig",
  "login_path": "/login.html",
  "login_redirect_param": "return_to",
  "mode": "compat",
  "module_file": "/module.js",
  "env": {
    "APP_API_URL": "https://api.example.com",
    "APP_AUTH_API_URL": "https://api.example.com",
    "APP_WEBSOCKET_URL": "wss://api.example.com"
  },
  "routePrefix": "https://api.example.com",
  "themeMode": "auto",
  "themePersist": "localStorage",
  "themeStorageKey": "@wippy-theme-mode",
  "axiosDefaults": { "timeout": 30000 },
  "apiRoutes": { "agents": { "list": "/custom/agents" } },
  "tanstack": { "lists": { "refetchOnWindowFocus": true } },
  "extraScripts": ["/monitoring.js"],
  "theming": {
    "global": {
      "customCSS": "@import url('https://fonts.googleapis.com/...');",
      "cssVariables": { "--p-primary": "#6366f1" },
      "iconSets": {}
    },
    "host": {
      "customCSS": ".wippy-host-app .chat-container { background: var(--p-content-background); }",
      "cssVariables": {},
      "iconSets": {},
      "i18n": {
        "app": {
          "title": "My App",
          "icon": "wippy:logo",
          "appName": "My Application"
        }
      }
    },
    "children": {
      "customCSS": "",
      "cssVariables": {}
    }
  },
  "hostConfig": {
    "session": { "type": "non-persistent" },
    "history": "hash",
    "renderEngine": "iframe",
    "showAdmin": true,
    "allowSelectModel": false,
    "startNavOpen": false,
    "hideNavBar": false,
    "disableRightPanel": false,
    "hideSessionSelector": false,
    "additionalNavItems": [
      { "id": "reports", "name": "Reports", "title": "Reports", "icon": "tabler:report", "order": 10 }
    ],
    "stateCache": { "maxPages": 50, "maxSizePerPage": 1048576 },
    "allowAdditionalTags": { "w-chart": ["data", "type"] },
    "chat": { "convertPasteToFile": { "enabled": true, "minFileSize": 1024, "allowHtml": false } }
  }
}
```



#### Field Reference


**Shell and integration fields** — used by the standard shell or a custom embedder:

| Field | Description |
|-------|-------------|
| `facade_url` | Base CDN URL for the Web Host bundle. Used to resolve the module entry and vendor scripts. |
| `iframe_origin` | `Origin` header value of the CDN. Used as the `targetOrigin` for PostMessage in manual iframe embeddings (see below). |
| `iframe_url` | Full iframe `src` including `?waitForCustomConfig`. Used only by manual, facade-less iframe embeddings (see below). |
| `login_path` | Path on the page's origin to redirect unauthenticated users to. |
| `login_redirect_param` | Optional query parameter that receives the requested relative URL during the client-side login redirect. |
| `mode` | Normalized frontend mode: `compat` or `managed`. |
| `module_file` | Module selected by `mode`: `/module.js` or `/managed-layout.js`. |
| `themePersist` | Configured theme persistence mode, also available to external pages. |
| `themeStorageKey` | Configured cookie or localStorage key, also available to external pages. |
| `extraScripts` | Optional scripts the shell loads before the Web Host module. |

**Web Host fields returned by the endpoint** — copied selectively into the
`AppConfig` assembled by the page:

| Field | Description |
|-------|-------------|
| `env` | Runtime URLs injected as top-level `AppConfig.env`. |
| `routePrefix` | API URL prefix forwarded to child apps. |
| `themeMode` | Initial theme mode: `auto`, `light`, or `dark`. A persisted choice takes precedence in the standard shell. |
| `axiosDefaults` | Axios instance defaults forwarded to child apps. |
| `apiRoutes` | Override individual API endpoint paths (top-level `AppConfig` field). |
| `tanstack` | TanStack Query defaults returned by the endpoint. See the forwarding limitation below. |
| `theming` | CSS customization split into three scopes. |
| `hostConfig` | Web Host feature flags and UI configuration. |

The standard shell itself adds these required `AppConfig` fields:

| Field | Source |
|-------|--------|
| `$schema` | `<facade_url>/schemas/wippy-context-2.0.xsd` |
| `auth` | Token read from `@wippy_token_info`; the current shell synthesizes an expiry one day from initialization. |
| `context` | `{ resourceId: '', resourceType: 'page' }` |

> **Current `tanstack` forwarding limitation.** The config handler returns a
> configured `tanstack` object, and Web Host accepts `AppConfig.tanstack`. The
> standard facade shell does not currently copy `cfg.tanstack` into its
> `initWippyApp` argument, so the facade parameter has no effect on that path.
> A manual embedder may include `tanstack: cfg.tanstack` in its assembled
> `AppConfig`.

**`env` fields:**

| Field | Source | Description |
|-------|--------|-------------|
| `APP_API_URL` | `PUBLIC_API_URL` env var | Base URL for all backend HTTP calls |
| `APP_AUTH_API_URL` | Same as `APP_API_URL` | Auth endpoint URL (may differ in custom setups) |
| `APP_WEBSOCKET_URL` | Derived from `APP_API_URL` | `http://` → `ws://`, `https://` → `wss://` |

**`theming` scopes:**

| Scope | Applied to |
|-------|-----------|
| `global` | Both the host chrome and all child page render contexts |
| `host` | Host chrome only. Also carries `i18n.app` for the app title, icon, and name shown in the sidebar. |
| `children` | Child page render contexts (srcdoc iframes or Web Fragments) |

**`hostConfig` fields:**

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `session.type` | `"non-persistent"` \| `"cookie"` | `"non-persistent"` | Token storage mode |
| `history` | `"hash"` \| `"browser"` | `"hash"` | Vue Router history mode |
| `renderEngine` | `"iframe"` \| `"fragment"` | `"iframe"` | Render engine for packaged `view.page` applications |
| `showAdmin` | boolean | `true` | Show admin features in UI |
| `allowSelectModel` | boolean | `false` | Show LLM model picker |
| `startNavOpen` | boolean | `false` | Expand nav sidebar on load |
| `hideNavBar` | boolean | `false` | Hide left navigation sidebar entirely |
| `disableRightPanel` | boolean | `false` | Disable right artifact panel |
| `hideSessionSelector` | boolean | `false` | Hide the chat session picker |
| `additionalNavItems` | array | `[]` | Extra items injected into the sidebar |
| `stateCache` | object | `{}` | LRU cache config for child page state |
| `allowAdditionalTags` | object | `{}` | HTML sanitizer tag whitelist (`Record<string, string[]>`, tag → allowed attributes) |
| `chat` | object | `{}` | Chat UI overrides (paste-to-file behavior, etc.) |



### Authentication Flow


The facade serves the HTML shell and public config response before it knows the
client-held bearer token. In the browser, the shell reads
`@wippy_token_info` from localStorage. A missing value or invalid JSON triggers a
redirect to `login_path`. If `login_redirect_param` is configured, the shell
adds the current path, query, and hash so the login flow can return the user to
the requested URL.

For a valid stored value, the shell copies its `token` into `AppConfig.auth` and
synthesizes `expiresAt` as one day after initialization. The config endpoint
itself contains neither the token nor user-specific auth state. `APP_API_URL`
and `APP_WEBSOCKET_URL` are deployment settings, not per-user values.



### The Module Init Function


Both JS-module entries register the same `window.initWippyApp` function. The
choice of module determines which shell renders and is independent of the
embedding style (JS-module page vs manual iframe).

`initWippyApp(appConfig, rootContainer?)` returns a simple event emitter:

```javascript
const events = window.initWippyApp(appConfig, '#app')
events.on('ready', () => console.log('Wippy loaded'))
events.on('error', err => console.error('Failed to load:', err))
```

When called without a root container, the host mounts into a default element.



### Manual (facade-less) iframe embedding


The JS-module page above is the standard, recommended path and the one the current facade uses. There is also a second embedding mechanism for cases where you want to run the full host **inside an iframe** — for example to occupy only part of a page with stronger isolation from the surrounding application. In this mode you embed the host yourself; the facade does not produce this page.

![Manual iframe embedding](../diagrams/manual-iframe-embedding.svg)

You can still reuse the facade's `/facade/config` endpoint to obtain deployment
settings. Its `iframe_url` (the host's `iframe.html` entry with
`?waitForCustomConfig` appended) and `iframe_origin` (the PostMessage
`targetOrigin`) support this path. The parent must obtain auth through its own
client flow and assemble a complete `AppConfig` before answering the handshake.

Unlike the JS-module path, the host inside the iframe **requests** its config: it boots and posts a `get-config` message to the parent, and the parent replies with `set-config`. Given an `<iframe id="wippy"></iframe>` in the parent document, listen for the request rather than pushing config blindly on `load`:

```javascript
async function mountWippyIframe(auth) {
  const response = await fetch('/api/public/facade/config')
  if (!response.ok)
    throw new Error(`Facade config request failed: ${response.status}`)
  const cfg = await response.json()
  const iframe = document.getElementById('wippy')
  if (!(iframe instanceof HTMLIFrameElement))
    throw new Error('Expected <iframe id="wippy">')

  const iframeUrl = new URL(cfg.iframe_url)
  if (iframeUrl.origin !== cfg.iframe_origin)
    throw new Error('iframe_url and iframe_origin must identify the same origin')

  const appConfig = {
    $schema: `${cfg.facade_url}/schemas/wippy-context-2.0.xsd`,
    auth,
    env: cfg.env,
    routePrefix: cfg.routePrefix,
    themeMode: cfg.themeMode,
    apiRoutes: cfg.apiRoutes,
    axiosDefaults: cfg.axiosDefaults,
    tanstack: cfg.tanstack,
    theming: cfg.theming,
    hostConfig: cfg.hostConfig,
    context: { resourceId: '', resourceType: 'page' },
  }

  function onMessage(event) {
    if (event.origin !== cfg.iframe_origin || event.source !== iframe.contentWindow)
      return

    let message
    try {
      message = typeof event.data === 'string' ? JSON.parse(event.data) : event.data
    }
    catch {
      return
    }
    if (message?.type === '@gen2-chat' && message.action === 'get-config') {
      event.source.postMessage(
        JSON.stringify({ type: '@gen2-chat', action: 'set-config', ...appConfig }),
        cfg.iframe_origin,
      )
    }
  }

  window.addEventListener('message', onMessage)

  // iframe_url already includes ?waitForCustomConfig
  iframe.src = iframeUrl.href

  return function unmount() {
    window.removeEventListener('message', onMessage)
    iframe.remove()
  }
}
```

Call `mountWippyIframe` with an `auth` object containing the current bearer
`token` and an ISO 8601 `expiresAt`. Do not source that token from
`/facade/config`; the endpoint does not return one. Retain the returned
`unmount` function and call it when the embedding surface is removed so the
window listener and iframe do not survive their owner.

The parent-side checks above protect the parent from accepting messages from a
different frame. At Web Host 1.0.56, the iframe's inbound `SetConfig` handler
checks only the envelope `type` and `action`; it does not authenticate
`event.origin` or `event.source`, and a later matching message can replace the
configuration. Treat every script or window that can message the iframe as part
of the trusted configuration boundary. Iframe DOM and style isolation is not
configuration-authority isolation.

The `?waitForCustomConfig` query parameter (already present in `iframe_url`) is the key signal. It tells the Web Host to pause initialization — the app mounts but deliberately does not attempt to resolve authentication or load routes until it receives a `set-config` message. Without it the Web Host would try to read auth tokens from URL parameters or defaults, which is not appropriate for embedded deployments.

The handshake uses the `@gen2-chat` PostMessage protocol:

1. The parent fetches `GET /facade/config` (or supplies equivalent deployment settings), assembles a complete `AppConfig`, and creates the iframe pointing at `iframe_url`.
2. The booting iframe posts `{ type: '@gen2-chat', action: 'get-config' }` to the parent.
3. The parent's `message` listener responds with `{ type: '@gen2-chat', action: 'set-config', ...appConfig }`, targeted at `iframe_origin`.

The Web Host extracts the `AppConfig` payload and proceeds with full initialization. For the full message protocol (`@gen2-chat` envelope and the `IFrameMessageType` enum), see [Proxy & Isolation](./proxy-isolation.md). This `SetConfig` handshake is specific to manual, facade-less embedding; the `wippy/facade` module loads the Web Host as a JS module instead.



### Configuring the Facade Module


Set the `wippy/facade` parameters that produce the config response in
`_index.yaml`. This example comes from `app-template`:

```yaml
- name: facade
  kind: ns.dependency
  component: wippy/facade
  version: '0.6.37'
  parameters:
    - name: server
      value: app:gateway
    - name: router
      value: app:api.public
    - name: app_title
      value: Wippy App
    - name: app_name
      value: Wippy App
    - name: app_icon
      value: "wippy:logo"
    - name: show_admin
      value: "false"
    - name: hide_nav_bar
      value: "true"
    - name: login_path
      value: /app/login.html
    - name: session_type
      value: non-persistent
    - name: history_mode
      value: browser
    - name: custom_css
      value: "@import url('https://fonts.googleapis.com/css2?family=Poppins...');
             body { font-family: 'Poppins', sans-serif; }"
    - name: css_variables
      value: '{"--p-primary":"#6366f1"}'
    - name: host_custom_css
      value: ".wippy-host-app .chat-container { background: var(--p-content-background); }"
```

For the full list of available parameters and their defaults, see the [Facade module reference](../../framework/facade.md).



---

# "Bootstrap Sequence"

## Bootstrap Sequence


This page is a lifecycle and configuration reference. The sequence diagrams
describe Host initialization; they are not application bootstrap code to copy.

After receiving its configuration, the Web Host runs a fixed initialization
sequence before rendering the full interface. Configuration arrives either
through a JS module that takes over the page or through a manually embedded
iframe. The internal steps are identical once configuration is available.



### Path A — JS Module (Standard, facade path)


The current `wippy/facade` uses this path. It serves a page that loads a Web
Host JS-module entry: `module.js` for **compat** mode or `managed-layout.js` for
**managed** mode. The module then takes over the page and its browser history.

1. **Page loads the module.** The script registers `window.initWippyApp` on the page's `window`.

2. **Page assembles `AppConfig` and calls `initWippyApp(appConfig, rootContainer?)`.** The shell fetches `/facade/config`, reads the bearer token from the `@wippy_token_info` localStorage entry, adds `$schema`, `auth`, and `context`, and forwards the supported response fields. There is no PostMessage handshake.
   ```javascript
   const events = window.initWippyApp(appConfig, '#app')
   events.on('ready', () => console.log('App ready'))
   ```

3. **Initialization proceeds** — see [Internal Init Sequence](#internal-init-sequence) below.



### Path B — Iframe (manual, facade-less)


Use this path to embed the full host inside an iframe for partial-page rendering
with stronger isolation. It loads `iframe.html?waitForCustomConfig` and receives
configuration through a `SetConfig` PostMessage. The current facade does not
produce this embedding.

1. **Iframe loads.** The Web Host loads in the browser. Because `?waitForCustomConfig` is present in the URL, the app mounts a minimal skeleton and suspends — it does not attempt to read auth tokens or call any API endpoints yet.

2. **Parent sends `SetConfig`.** The parent supplies a complete `AppConfig`. A `/facade/config` response can provide the deployment settings, but the parent must add `$schema`, `auth`, and `context` before replying:
   ```javascript
   iframe.contentWindow.postMessage(
     JSON.stringify({ type: '@gen2-chat', action: 'set-config', ...appConfig }),
     cfg.iframe_origin
   )
   ```

3. **Web Host receives `AppConfig`.** The message handler validates the envelope
   type and action, then extracts the configuration object. At Web Host 1.0.56,
   this inbound handler does not authenticate `event.origin` or `event.source`,
   and a later matching `SetConfig` can replace the configuration. The parent
   must restrict who can message the iframe and treat that whole message
   environment as trusted. Iframe DOM and style isolation is not configuration-
   authority isolation.

4. **Initialization proceeds** — the internal path is identical to Path A from this point forward.



### Internal Init Sequence


Once `AppConfig` is available (via either path), the Web Host runs the following
startup sequence:

**1. Resolve and normalize configuration.**
`resolveConfig()` initializes and merges the supplied configuration, applies
schema migrations, normalizes session policy, and populates the configuration,
authentication, and environment state used by the rest of the Host.

**2. Fetch backend page routes.**
Before creating or mounting the Vue application, the Host awaits
`GET /api/public/pages/routes`. A backend syntax or duplicate-route error aborts
startup and is relayed through the Host error path; it is not a post-mount route
installation step.

**3. Create the application and router.**
The Vue application is created. The router uses the history mode from
`AppConfig.hostConfig.history` and registers both static system routes and the
backend mount routes before the application mounts.

**4. Install application providers.**
`setupApp()` installs Pinia, configures Axios and authentication, installs
PrimeVue and the theme providers, and wires the remaining application services.
Child applications receive the configured API surface through the proxy layer.

**5. Mount and resolve the current URL.**
Only after configuration, route loading, router creation, and provider setup
have completed does the module entry mount `App.vue`. The router then resolves
the current browser or hash URL against the complete route table.

**6. Create WebSocket clients when requested.**
WebSocket setup is consumer-driven rather than a fixed final bootstrap step.
`useWsClientRaw()` creates the client when a consuming component or composable
requests it. The connection starts eagerly unless `hostConfig.lazyWS` is true;
with lazy mode, it starts when a subscription requires it.



### AppConfig TypeScript Interface


The following abridged declaration shows the main configuration fields accepted
by both `initWippyApp` and `SetConfig`. Supporting types and less commonly used
fields remain authoritative in the pinned Web Host `app-config/types.ts`; do not
treat this excerpt as a replacement for the shipped schema. There is no
`feature` or `fe_mode` field in `AppConfig` — `fe_mode` is a facade requirement
parameter that selects the module entry, and managed mode is conveyed through
`hostConfig.layout`:

```typescript
interface AppConfig {
  $schema: string             // current facade: <facade_url>/schemas/wippy-context-2.0.xsd
  auth: AppAuthConfig
  env: AppEnv
  axiosDefaults?: Partial<AxiosDefaults>
  routePrefix?: string
  apiRoutes?: ApiRoutesOverride
  tanstack?: TanstackConfig    // TanStack Query defaults (global + per role-based category)
  themeMode?: 'auto' | 'light' | 'dark'
  theming: AppTheming
  hostConfig: HostConfig
  context: AppContext
}

interface AppAuthConfig {
  token: string            // Bearer token
  expiresAt: string        // ISO 8601 expiry timestamp
}

interface AppEnv {
  APP_API_URL: string
  APP_AUTH_API_URL: string
  APP_WEBSOCKET_URL: string
}

interface AppTheming {
  global?: ThemingScope
  host?: HostThemingScope
  children?: ChildrenThemingScope
}

interface CssVariablesMap {
  [key: string]: string | Record<string, string> | undefined
  '@dark'?: Record<string, string>
  '@light'?: Record<string, string>
}

interface ThemingScope {
  customCSS?: string
  cssVariables?: CssVariablesMap
  fonts?: FontConfig[]
  icons?: Record<string, unknown>
  iconSets?: Record<string, Record<string, unknown>>
}

interface HostThemingScope extends ThemingScope {
  i18n?: Partial<I18NTextTypes>
}

interface ChildrenThemingScope {
  customCSS?: string
  cssVariables?: CssVariablesMap
  fonts?: FontConfig[]
}

interface HostConfig {
  session?: { type: 'non-persistent' | 'cookie' }
  history?: 'browser' | 'hash'
  showAdmin?: boolean
  allowSelectModel?: boolean
  startNavOpen?: boolean
  hideNavBar?: boolean
  disableRightPanel?: boolean
  hideSessionSelector?: boolean
  renderEngine?: 'iframe' | 'fragment'
  lazyWS?: boolean
  additionalNavItems?: PageApi.Page[]
  stateCache?: { maxPages?: number; maxSizePerPage?: number }
  allowAdditionalTags?: Record<string, string[]>   // tag → allowed attributes
  chat?: {
    convertPasteToFile?: {
      enabled: boolean
      minFileSize: number
      allowHtml: boolean
    }
  }
  layout?: HostLayoutDeclaration
}

// TanStack Query defaults. A top-level field (shared by host + children, like
// apiRoutes). Default behavior (no config) is refetchOnWindowFocus: false so
// alt-tabbing back doesn't reload in-flight content.
interface TanstackConfig {
  default?: TanstackQueryOptions   // overrides the global query defaults
  content?: TanstackQueryOptions   // single-resource renders (page/artifact/session/entry/model/upload)
  lists?: TanstackQueryOptions     // navigation / index / list queries
}

// JSON-safe subset of TanStack query options (no functions — config is JSON).
interface TanstackQueryOptions {
  refetchOnWindowFocus?: boolean
  refetchOnReconnect?: boolean
  refetchOnMount?: boolean
  staleTime?: number
  gcTime?: number
  retry?: boolean | number
  refetchInterval?: number | false
}

interface AppContext {
  resourceId: string
  resourceType: 'page' | 'artifact'
  route?: string
  parentResourceId?: string
  nestingDepth?: number
  isNavOwner?: boolean
  layoutPanelId?: string
  layoutId?: string
  layout?: unknown
  extensions?: Record<string, unknown>
}
```

> **Current facade limitation.** Web Host accepts `AppConfig.tanstack`, and the
> facade config endpoint returns the configured `tanstack` object. The standard
> facade shell does not currently copy that field into the `AppConfig` passed to
> `initWippyApp`. Do not rely on the facade `tanstack` parameter on the standard
> shell path until that forwarding is implemented. A manual embedder can include
> it in the `AppConfig` it assembles.



### Configuration Sources and Priority


The Web Host resolves configuration from multiple sources, in priority order from lowest to highest:

1. **Built-in defaults** — defined in the Web Host bundle itself.
2. **URL query parameters** — `?token=<token>`, `?expiresAt=<timestamp>`, `?persist` for cookie sessions. Useful for direct development access without a parent page.
3. **`initWippyApp()` argument** — the `AppConfig` assembled by the standard facade shell; takes precedence over URL parameters.
4. **PostMessage `SetConfig`** — the manual, facade-less iframe path, used when `?waitForCustomConfig` is present.

In practice, production deployments always use `initWippyApp()` (the facade path) or PostMessage (manual iframe embedding). URL parameters are a development convenience for loading the host directly in the browser with a token.



### Bootstrap Diagram


The standard facade (JS-module) path:

```
module.js / managed-layout.js loaded on the page
  │
  ├─ shell assembles AppConfig from /facade/config + local auth
  ├─ window.initWippyApp(appConfig, '#app')
  │     appConfig = { $schema, auth, env, theming, hostConfig, context, ... }
  │
  ├─ resolveConfig() → migrate, normalize, and populate config/auth/env state
  ├─ await GET /api/public/pages/routes
  ├─ create Vue app + router
  │     static system routes + validated backend mount routes
  ├─ setupApp() → Pinia, Axios, PrimeVue, theming, and other providers
  ├─ mount App.vue → resolve the current URL
  └─ consuming components request WebSocket clients
        eager connection unless hostConfig.lazyWS is true
```



### See Also


- [Facade Entry Point](./entry-point.md) — how `AppConfig` is constructed and delivered by `wippy/facade`
- [Multi-Panel Layout](./multi-panel-layout.md) — the managed-layout boot path served by `managed-layout.js`
- [Render Engines](./render-engines.md) — how a page renders once loaded (srcdoc iframe vs Web Fragment)



---

# "Multi-Panel Layout"

## Multi-Panel Layout


This page is an early-access configuration and API reference. The YAML and
TypeScript blocks are partial declarations and integration patterns, not a
production-ready shell by themselves.

> **Status: Draft 1 preview — early access, not for production.** The
> managed-layout API is available but has not been validated with a production
> consumer. Field names, defaults, and validation rules may change between
> minor releases. Pin an exact CDN version until this label is removed. Use the
> standard `compat` mode for production unless the application must compose the
> host chrome itself.

Managed-layout mode replaces the standard Wippy chrome with a declarative panel
tree. Define the named panels in backend YAML; the Web Host assembles and
validates the layout at boot, then maintains it reactively at runtime. Panels
can be resized, collapsed, swapped, added, and removed without a page reload.



### When to Use Managed Layout


The standard `compat` mode is the default production mode. It provides the
fixed Wippy shell: navigation sidebar, chat panel, page area, and right artifact
panel.

Opt in to `fe_mode = managed` (early access) only when you need to compose the chrome itself:

| Need | Compat | Managed |
|------|--------|---------|
| Standard Wippy chat + nav | Yes | Replaceable |
| Multiple page slots side by side | No | Yes |
| Custom sidebar or coordinator component | Limited | Yes — any panel kind |
| Responsive layouts per breakpoint | No | Yes |
| Floating overlay panels | No | Yes |
| Headless coordinator component | No | Yes (`coordinators`) |
| Per-panel URL-aware routing | Main panel only | Every `kind: page` panel |
| Cross-panel message bus | No | Yes (`broadcast`/`send`/`on`) |



### Compatibility


Managed layout spans the Web Host, facade, and several `@wippy-fe/*` packages. Use one compatible package family for the exact target Web Host release and verify its served import map; do not mix package versions from unrelated releases.



#### Release map


| Release | Managed-layout additions |
|---|---|
| Web Host `1.0.50`, Wippy FE `0.0.50` | Typed compat intents, `@HOST/compat-coordinator`, browser URL and Back/Forward synchronization, built-in panel tabs, anchored floating panels, and `useSwapBuffer()`. |
| Web Host `1.0.51`, Wippy FE `0.0.51` | Reactive and race-safe `<wippy-chat>` session/token control, opt-in themed splitter handles, split-axis-only size constraints, drawer geometry/stacking fixes, and the packaged proxy source map. |
| Web Host `1.0.52`, Wippy FE `0.0.52` | Typed retained-WC visibility and `useHostVisibilityRefresh()`, immediate page readiness instead of waiting for the 14-second fallback, stale renderer-key rejection, in-place component prop updates, and the isolated splitter layer with `--wippy-layout-splitter-z-index`. |
| Web Host `1.0.53`, Wippy FE `0.0.53` | Configured theme tokens propagate correctly when light or dark mode is forced. |
| Web Host `1.0.54`, Wippy FE `0.0.54` | Surface portability contract v1 for iframe and Web Fragment pages, including managed-layout registration and reactive sizing changes. |
| Web Host `1.0.55`, Wippy FE `0.0.55` | Managed artifact and standalone chat contracts, cold deep-link preservation, stable managed artifact rendering, and themed splitter handles. |
| Web Host `1.0.56`, Wippy FE `0.0.56` | Managed artifact/modal rendering fixes, published artifact-open reasons, and chat selector and slot-lifecycle fixes. |

The 14-second page reveal is a Web Host `1.0.52` fallback, not a 1.0.51
feature or an application loading delay.

Retained direct-web-component visibility requires Web Host `1.0.52` and
`@wippy-fe/webcomponent-core`, `@wippy-fe/webcomponent-vue`, and
`@wippy-fe/shared` `0.0.52`. Earlier managed-layout releases do not provide the
typed `data-wippy-visible` contract or `useHostVisibilityRefresh()`.



#### Retained web-component activity


Managed layouts keep panels mounted across buffer swaps, breakpoint changes,
and drawer close/open cycles. The host sets
`data-wippy-visible="true" | "false"` before connecting a direct custom element
and updates it in place when logical ownership changes. This is not CSS,
viewport, or document visibility, and it never implies a remount.

Vue components read the state with `useHostVisibility()` or combine ordinary
initial loading with reveal refreshes through `useHostVisibilityRefresh(task)`.
The latter runs after mount and then only on exact `false -> true`. Do not use
the proxy `@visibility` topic in a direct WC; it is the iframe/Web Fragment
message channel.

Pin to an exact CDN tag until the Draft 1 label is removed. This reference is
validated against `https://web-host.wippy.ai/webcomponents-1.0.56` and the
matching `@wippy-fe/*` `0.0.56` family. Retained direct-web-component visibility
still requires at least 1.0.52/0.0.52.



### Enabling Managed Layout


Enable the managed entry in your facade configuration and provide a backend `host_config.layout` declaration:

```yaml
host_config:
  layout:
    layouts:
      default:
        direction: horizontal
        children:
          - panel: nav
            size: 240px
          - panel: main
            size: 1fr
            main: true
    panels:
      nav:  { kind: builtin, id: '@HOST/nav-sidebar' }
      main: { kind: page,    id: home }
```

When the managed entry is selected, the facade serves `managed-layout.js` instead of `module.js`. `fe_mode` is a current facade requirement parameter (default `compat`, opt-in `managed`); it is set on the `wippy.facade` requirement, not carried inside the `AppConfig` payload. There is no `AppConfig.feature` field — the managed layout is conveyed to the child entirely through `AppConfig.hostConfig.layout`. The proxy API *surface* is identical in both modes, but some commands only take effect in one mode — see [What works in which mode](#what-works-in-which-mode).



### The `HostLayoutDeclaration`


The entire layout is described by a single `HostLayoutDeclaration` object nested under backend `host_config.layout` in your facade configuration and projected to frontend `AppConfig.hostConfig.layout`. The host validates it before mounting — any `LayoutValidationError` surfaces in the browser console with `{ kind, message, panelId? }`.

| Field | Type | Description |
|-------|------|-------------|
| `layouts` | `Record<string, PanelTree> & { default: PanelTree }` | Breakpoint-keyed panel trees. The `default` key is required. |
| `breakpoints?` | `Record<string, number>` | Pixel widths that activate non-default layout keys. |
| `panels` | `Record<string, HostPanelDef>` | Named panel content definitions. |
| `floating?` | `Record<string, HostFloatingDef>` | Boot-time floating overlay panels. |
| `modals?` | `Record<string, HostModalDef>` | Boot-time modal definitions. |
| `coordinators?` | `Record<string, HostCoordinatorDef>` | Headless coordinator components. |
| `services?` | `Record<string, HostCoordinatorDef>` | Deprecated alias for `coordinators`; new declarations must use `coordinators`. |
| `dragEnabled?` | boolean | Allow user-driven splitter drag. Default `true`. |



### Panel Kinds


Each entry in `panels`, `floating`, `modals`, and `coordinators` is a tagged union on `kind`:

| Kind | Description | Required fields |
|------|-------------|-----------------|
| `page` | A Wippy page module mounted through its selected iframe or Web Fragment engine | `id` (page registry id) |
| `artifact` | A Wippy artifact rendered through the host artifact/page resolver | `id` (artifact UUID) |
| `component` | A web component mounted directly in host DOM | `tagName` |
| `builtin` | A framework-owned host component (see below) | `id` |

Exactly one panel in the layout tree must carry `main: true`. Browser URL ownership still requires route synchronization through `@HOST/compat-coordinator` or equivalent consumer coordination. All other page panels route independently inside their selected page realms.



#### Built-in Panel IDs


`kind: builtin` accepts the following `id` values. The `@HOST/` prefix is reserved for framework-owned panels:

| ID | What it renders |
|----|-----------------|
| `@HOST/nav-sidebar` | Standard Wippy nav sidebar (sessions, pages, settings) |
| `@HOST/chat-wrapper` | Standard Wippy chat panel for the active session |
| `@HOST/artifact-viewer` | Generic artifact viewer (pair with route `/:uuid`) |
| `@HOST/session-selector` | Session list and picker |
| `@HOST/compat-coordinator` | Headless compat-intent and main-route coordinator; declare under `coordinators` |
| `@HOST/panel-tab` | Edge tab for revealing a collapsed panel; declare under `floating` |

An unknown `@HOST/<id>` causes a `LayoutValidationError` at declaration-load rather than silently rendering an empty slot.



### Breakpoint-Keyed Layouts


The `layouts` field maps breakpoint keys to panel trees. `default` is always used unless a narrower breakpoint matches. Breakpoint pixel widths are defined under `breakpoints`:

```yaml
host_config:
  layout:
    breakpoints:
      sm: 768
    layouts:
      default:
        direction: horizontal
        children:
          - panel: side
            size: 300px
          - panel: main
            size: 1fr
            main: true
      sm:
        direction: vertical
        children:
          - panel: main
            size: 1fr
            main: true
          - panel: side
            display: drawer-left
            drawerSize: { width: 320px }
    panels:
      side: { kind: page, id: app-sidebar, route: / }
      main: { kind: page, id: app-home,    route: / }
```

When the breakpoint changes, panels with the same `id` keep one stable content host that visually tracks the active slot without reparenting. Iframe `contentWindow`, web-component state, Vue state, and scroll position survive the transition; reparenting via Teleport is intentionally avoided because removing and reinserting an iframe reloads it.



#### Drawer-Mode Panels


A panel slot can declare `display: 'drawer-left' | 'drawer-right' | 'drawer-bottom'` to render as a slide-in overlay instead of an inline flex item. Drawer panels:

- Do not participate in their parent container's track sizing (`size` is ignored)
- Render as absolutely-positioned overlays anchored to the named edge
- Have an open/close state toggled via `host.layout.openDrawer(id)` / `closeDrawer(id)` / `toggleDrawer(id)`
- Show a backdrop when open; clicking the backdrop closes all open drawers

`main: true` slots cannot be drawer-mode — host validation throws. The `drawerSize.width` field controls the width for left/right drawers; `drawerSize.height` for bottom drawers. Default is `320px`.



### Floating Panels


Floating panels are free-positioned overlays declared under `floating`. They do not participate in the flex layout tree and can be added or removed at runtime:

```yaml
floating:
  flap:
    kind: component
    tagName: my-right-flap
    position: { x: 0, y: 200 }
    size: { width: 48, height: 80 }
```

Runtime management:
```typescript
// Add a floating panel
host.layout.addFloating('inspector', {
  kind: 'component',
  tagName: 'my-inspector',
  position: { x: 100, y: 100 },
  size: { width: 400, height: 300 },
})

// Remove it
host.layout.removeFloating('inspector')
```



### Headless Coordinators


Coordinators are components mounted in a hidden host. They have no visible slot but receive the panel-scoped host API. Use them for cross-cutting logic so display panels stay focused on rendering. The older `services` field remains a deprecated compatibility alias.

```yaml
coordinators:
  coordinator:
    kind: component
    tagName: my-coordinator
```

A coordinator component receives the panel-scoped host wrapper and can subscribe to bus channels immediately in `onMount`:

```typescript
import { WippyElement } from '@wippy-fe/webcomponent-core'

class MyCoordinator extends WippyElement {
  private offOpenChat: (() => void) | null = null

  protected onMount() {
    this.offOpenChat = this.host?.layout.on('open-chat', ({ payload }) => {
      this.host?.layout.updatePanel('right', { route: `/open-chat/${payload.token}` })
      this.host?.layout.expandPanel('right')
    }) ?? null
  }
  protected onUnmount() {
    this.offOpenChat?.()
    this.offOpenChat = null
  }
  static get wippyConfig() { return { propsSchema: { properties: {} } } }
}
customElements.define('my-coordinator', MyCoordinator)
```



#### Shipped compat coordinator


Managed layout contains only declared surfaces. Calls such as
`host.openArtifact()`, `host.startChat()`, `host.openSession()`, and
`host.navigate()` therefore publish typed intents on the reserved
`@HOST/intent` channel. Declare the shipped coordinator to act on them and to
bind the browser URL to the main panel:

```yaml
coordinators:
  compat:
    kind: builtin
    id: '@HOST/compat-coordinator'
    props:
      artifactPanel: right
      chatPanel: chat
      modalId: artifact-modal
      routeSync: true
      wsActions: true
```

Keep `routeSync: true` when using the standard navigation contract. Without a
coordinator or equivalent consumer logic, deep links, Back/Forward, and
`@HOST/nav-sidebar` navigation have no panel route to drive. Intents raised
during child boot are held in a bounded queue until the first coordinator
subscribes.

`@HOST/` is reserved in both directions: ordinary panels cannot publish system
traffic, and only entries under `coordinators` receive it through supported
host APIs. This boundary is enforced for iframe/Web Fragment panels. A direct
component mounted in the host realm shares the host DOM and is not a security
sandbox. At boot the host prints a parity table when coordinator handling, a
modal target surface, main-panel URL binding, or a declared coordinator tag is
missing; a complete declaration produces no warning.



### The In-Tab Broadcast Bus


Panels communicate through a bus scoped to the current browser tab. The bus never crosses to other tabs — use a custom WebSocket topic if you need multi-tab sync.

| Method | Description |
|--------|-------------|
| `host.layout.broadcast(channel, payload)` | Publish to all panels; sender excluded |
| `host.layout.send(targetPanelId, channel, payload)` | Publish to one specific panel |
| `host.layout.on(channel, handler)` | Subscribe; returns `off()` unsubscribe function |

The `sourcePanelId` on received messages is set by the host from the publishing window and cannot be spoofed. Channel names are case-sensitive plain strings.

**Important:** Components that import `host` directly from `@wippy-fe/proxy` bypass panel scoping — bus calls go through but lose `sourcePanelId`. Always use the panel-scoped wrapper instead:

```typescript
// raw HTMLElement
import { getWippyHost } from '@wippy-fe/webcomponent-core'
const host = getWippyHost(this)

// WippyElement subclass — this.host is already panel-scoped
this.host?.layout.broadcast('open-chat', { token: 'abc' })

// Vue component
import { useHost } from '@wippy-fe/webcomponent-vue'
// ProxyApiInstance is an ambient global type (from @wippy-fe/types-global-proxy) — reference it without an import.
const host = useHost<ProxyApiInstance['host']>()
host?.layout.broadcast('open-chat', { token: 'abc' })
```



### Layout API Reference (`host.layout`)


| Method | Description |
|--------|-------------|
| `.snapshot` | Synchronous getter returning the full layout snapshot, or `null` outside managed-layout mode |
| `.resizePanel(id, size)` | Resize the named panel in the active breakpoint |
| `.collapsePanel(id)` | Collapse a panel declared `collapsible: true` |
| `.expandPanel(id)` | Expand a collapsed panel |
| `.openDrawer(id)` | Open a drawer-mode panel |
| `.closeDrawer(id)` | Close a drawer-mode panel |
| `.toggleDrawer(id)` | Toggle a drawer-mode panel |
| `.movePanel(id, target)` | Move panel to a new tree position |
| `.removePanel(id)` | Remove panel from all breakpoint layouts |
| `.updatePanel(id, def)` | Patch panel definition at runtime; `props` shallow-merges, top-level fields replace |
| `.addFloating(id, def)` | Add a floating panel |
| `.removeFloating(id)` | Remove a floating panel |
| `.openModal(id, def)` | Open a modal. The public 0.0.56 TypeScript API requires `def`; the host merges it over any declaration with the same id. Native `<dialog>.showModal()` is the default; pass `useNativeDialog: false` for the legacy div overlay. Re-opening an open id is a silent no-op. |
| `.closeModal(id)` | Close an open modal |
| `.broadcast(channel, payload)` | Publish to all panels |
| `.send(target, channel, payload)` | Publish to one panel |
| `.on(channel, handler)` | Subscribe to a bus channel |

`openModal()` documents host-internal layout infrastructure, not an application-component recipe. Shipped Vue product UI should use PrimeVue `Dialog` or the host confirmation API rather than cloning this native-dialog behavior with custom modal styling.



#### `updatePanel` Merge Semantics


`host.layout.updatePanel(id, def)` patches an existing panel def — it does not replace it. The `props` object is **shallow-merged** into the panel's current props: supplied keys are added or overwritten, omitted keys are preserved. Every **other** top-level field of `def` (`route`, `kind`, `id`, `tagName`, `title`, `icon`, …) **replaces** the current value wholesale.

Given a panel whose current props are `{ artifactId: 'old', zoom: 2 }`:

```typescript
// props shallow-merges → { artifactId: 'abc', zoom: 2 }
host.layout.updatePanel('right', { props: { artifactId: 'abc' } })

// route replaces wholesale; props left untouched
host.layout.updatePanel('right', { route: '/x' })
```

Two caveats: the props merge is **shallow** — a nested object inside `props` is replaced entirely, not deep-merged — and a shallow merge cannot delete a prop key (you can only overwrite it).



### Vue Composables — `@wippy-fe/vue-host`


These composables wrap the proxy layout API in reactive Vue 3 refs. The underlying subscription is module-scoped and lives for the iframe's lifetime, so there is no per-component cleanup on unmount:

| Composable | Returns |
|------------|---------|
| `useWippyLayout()` | Full layout state and mutation methods |
| `useWippyPanel(panelId)` | Named panel's live state (`panelId` is required — `string`, `Ref<string>`, or getter) |
| `useWippyBreakpoint()` | Active breakpoint name as a reactive ref |
| `useWippyMainRoute()` | Reactive ref to the main panel's current route |

The composables never return `null` — they always hand back objects/refs whose inner `.value` degrades when no managed-layout host is present: `useWippyLayout().snapshot.value` is `null` (and `isManaged.value` is `false`, so mutations are silent no-ops), `useWippyBreakpoint().value` and `useWippyMainRoute().value` are empty strings, and `useWippyPanel(id).value` is `null` when the id is absent. Guard host presence with `layout.isManaged.value` (or `layout.snapshot.value !== null`) rather than a `=== null` check on the return value. This keeps the composables usable in standalone playgrounds and unit tests where no managed-layout host is present.



### Swap buffering without remounts


`useSwapBuffer()` from `@wippy-fe/layout` keeps the outgoing surface mounted
until incoming content reports readiness, with an explicit timeout ceiling.
Use immutable `slot.index` as the DOM key, pass both index and content key to
`markReady()` / `markFailed()` so stale async signals are rejected, and keep
errors scoped per buffer. Content identity belongs in `keyOf`; changing the DOM
key would reinsert an iframe and destroy the state buffering is meant to retain.

```typescript
const swap = useSwapBuffer<Surface>({
  keyOf: surface => surface.ownerId,
  buffers: 2,
  readyTimeoutMs: 8_000,
  loaderDelayMs: 250,
  loaderMinMs: 400,
})

const slot = swap.push(surface)
swap.markReady(slot.index, slot.key)
// or: swap.markFailed(slot.index, error, slot.key)
```

The values shown are the defaults. A readiness timeout reveals the content by
default rather than leaving stale content behind a loader. Bind loading UI to
`swap.showLoader`, not directly to readiness. A failed buffer remains isolated
from its sibling; after handling the error, call `clearError(index)` to retry.



#### Web Host page readiness


Web Host uses the same keyed readiness discipline for managed page surfaces,
with a 14-second final reveal ceiling. Page and direct Web Component renderers
emit `load` / `error` through Vue event listeners and include the immutable
content key owned by that renderer. Painted content is therefore revealed
immediately; the ceiling is only a fallback for content that never reports.
A late event from an evicted renderer is rejected when its buffer index has
already been reused.

Do not use the 14-second host ceiling as an application loading delay, and do
not add a second timer around normal page readiness. A page that regularly
reaches the ceiling has a broken readiness or lifecycle path that should be
fixed at its owner.



#### Stable component updates and panel sizing


For `kind: component`, changing panel `props` updates or removes attributes on
the existing custom element. The host replaces the element only when `tagName`
changes. This preserves element-owned state during `updatePanel()` calls and
breakpoint transitions.

`minSize` and `maxSize` constrain only the active split axis: width in a
horizontal tree and height in a vertical tree. They do not cap the cross axis,
so navigation, chat, and other full-height mounts can fill their track. Drawer
mounts follow the animated drawer geometry and are promoted above their anchor
and backdrop only while open, without remounting their content.



### Splitter and handle styling


The splitter hit area is wider than its visible line and lives in the package's
isolated layer stack. `--wippy-layout-splitter-z-index` defaults to `700`, below
drawers and modal backdrops. The circular handle is opt-in:

| Variable | Default | Purpose |
|---|---|---|
| `--wippy-layout-splitter-size` | `1px` | Visible splitter line thickness |
| `--wippy-layout-splitter-hit-size` | `10px` | Pointer hit area around the line; `24px` on coarse pointers |
| `--wippy-layout-splitter-z-index` | `700` | Splitter and handle layer |
| `--wippy-layout-splitter-handle-size` | `0` | Handle diameter; `0` disables it |
| `--wippy-layout-splitter-handle-bg` | `transparent` | Handle fill |
| `--wippy-layout-splitter-handle-border` | `0 solid transparent` | Border shorthand |
| `--wippy-layout-splitter-handle-shadow` | `none` | Handle shadow |
| `--wippy-layout-splitter-handle-icon-color` | `transparent` | Theme-aware SVG color via `currentColor` |

Set size, fill, border/shadow, and icon color together when opting in. The SVG
rotates 90 degrees for vertical splitters and remains hidden for locked splits.



### What works in which mode


The proxy API *surface* is identical in compat and managed mode: the same
`@wippy-fe/proxy` imports resolve in both. Two parts of the API are
**mode-specific in effect**, so account for the active mode when moving an
application to managed layout.



#### `host.layout` takes effect only in managed mode


The host installs the layout receiver **only when a layout is declared** (the managed entry, gated on `hostConfig.layout`). In compat mode `host.layout` still exists, but `host.layout.snapshot` is `null` and every mutation and bus call (`resizePanel`, `updatePanel`, `movePanel`, `openModal`, `addFloating`, `broadcast`, `send`, `on`, …) is a **silent no-op** — the message is posted but nothing on the host is listening. Gate on the snapshot before mutating:

```typescript
if (host.layout.snapshot) {
  host.layout.updatePanel('right', { route: '/details' })   // managed only
}
// Vue: const { isManaged } = useWippyLayout(); if (isManaged.value) { … }
```

(Separately — a different axis — `addPanel` and `setLayout` are not exposed over the proxy *at all*, in either mode; see [Known Limitations](#known-limitations).)



#### `host.*` commands that assume the compat shell


The managed shell renders **only your declared layout**. Starting with Web Host 1.0.50, commands that normally target compat chrome publish typed `@HOST/intent` messages instead of failing silently. Declare `@HOST/compat-coordinator` or implement an equivalent coordinator to map those intents to your panels:

| `host.*` command | Compat (default) | Managed |
|---|---|---|
| `setContext`, `toast`, `confirm`, `handleError`, `logout`, `bridge.*`, top-level `state` / `ws` / `on` | Works | Works directly; managed mounts the global toast and confirmation surfaces |
| `openArtifact(id, ...)` | Opens in the right panel or a modal | Publishes an intent; the compat coordinator targets `artifactPanel` or `modalId` |
| `startChat(token)` / `openSession(uuid)` | Opens and displays the session | Publishes an intent; the compat coordinator resolves start tokens and updates the declared `chatPanel` |
| `navigate(url)` | Pushes the compat root router | Publishes an intent; `routeSync` applies it to the main panel and keeps browser history aligned |
| `onRouteChanged(route, navId?)` | Drives the host browser URL | Updates panel route state; `routeSync` projects the main panel route to the browser URL |

If no coordinator is available yet, boot-time intents are held in a bounded queue for the first coordinator subscription. A declaration with no handler is reported by the boot parity table. Reserved intents are readable only by `coordinators` entries and cannot be forged by ordinary panels.



### State Management Approach


Three tiers, in order of preference:

**Route** — If the user could meaningfully bookmark or share the state, put it in the URL. Each `kind: page` panel runs its own router and reacts to `@history` events. This is decoupled, deep-linkable, and browser-history-aware.

**Layout snapshot** — If it affects layout shape (sizes, collapsed flags, component props), put it in the snapshot via `updatePanel` or `resizePanel`. Every subscribed panel sees every snapshot change, so keep payloads small.

**Panel-local** — Everything else (form drafts, modal state, transient UI) stays inside the panel's own Pinia stores or refs and never leaves the panel.



### Canonical Coordination Pattern


The recommended pattern for cross-panel interaction is: bus event → coordinator service → `updatePanel` → panel reacts via its own router.

```typescript
// In the coordinator service
this.host?.layout.on('open-chat', ({ payload }) => {
  this.host?.layout.updatePanel('right', { route: `/open-chat/${payload.token}` })
  this.host?.layout.expandPanel('right')
})

// In the right-panel app (a normal Vue page module)
const router = createAppRouter([...])
// createAppRouter already mirrors host history events into the router
// with an echo/current-route guard; add no manual routing subscription.
```

Keep coordinators thin. Keep panels owning their own UI.



### Known Limitations


As of Draft 1, the following are not yet implemented:

- **`addPanel` / `setLayout` over the proxy** — not shipped. These exist only on the internal `@wippy-fe/layout` `LayoutManager` and are not exposed across the iframe proxy boundary. (`openModal`, `closeModal`, and `movePanel` are shipped — see the Layout API Reference.)
- **Panel drag-to-rearrange UI** — the data model and `movePanel()` API work; user-facing drag is not yet implemented.
- **Tabbed-container primitive** — not yet implemented. The shipped `@HOST/panel-tab` is an edge control for revealing a collapsed panel, not a general tabbed layout container.
- **Grid-tile container** — not yet implemented.
- **Runtime mutation persistence** — mutations are not persisted across reloads. Persist manually if needed:
  ```typescript
  on('@layout-change', () =>
    state.set('layout', host.layout.snapshot)
  )
  ```
- **`nav-sidebar` header slot extension points** — logo, app-name, and toggle button positions are fixed in this draft.



### See Also


- [Facade Entry Point](./entry-point.md) — how the facade loads the JS-module entry and delivers config
- [Bootstrap Sequence](./bootstrap.md) — how the host dispatches to the managed-layout entry at boot
- [Packages](./packages.md) — `@wippy-fe/layout`, `@wippy-fe/vue-host`, `@wippy-fe/webcomponent-core`, `@wippy-fe/webcomponent-vue`



---

# "Render Engines"

## Render Engines


This page is a render-engine selection and compatibility reference. It explains
operator and package settings; it is not a standalone deployment recipe.

The Wippy Web Host renders a micro frontend app (`view.page`) through one of **two page-render engines**. The engine is a delivery concern chosen by an operator switch, with an optional per-page override. Portable apps use the Wippy proxy and router APIs so their behavior does not depend on a particular engine.

| Engine | How a page renders | Isolation | Routing |
|--------|--------------------|-----------|---------|
| **Iframe** (default) | A srcdoc `<iframe>` with `proxy.js` injected | Full document isolation | Memory-history only (srcdoc has no real URL) |
| **Web Fragment** | A [`reframed`](https://web-fragments.dev) same-origin realm reflected into a `<web-fragment>` shadow root, with `proxy-fragment.js` | Realm isolation, shared DOM tree | Real `window.history` (URL routers work) |

Both engines support the Wippy application services used by portable apps: authenticated API, WebSocket, host-mediated state, confirm/bridge dialogs, `@history`/`@visibility` events, title propagation, error capture, platform CSS and theme delivery, content-mode auto-height, and nested `<w-artifact>` embeds. Delivery and control are engine-specific: iframe CSS and error capture honor proxy injection flags, while the Fragment gateway installs its platform CSS and error capture unconditionally. See [CSS Injection](./css-injection.md). Browser-history capabilities also differ, as shown in the table.

Use `createAppRouter()` from `@wippy-fe/router` for an app that can run under either engine. The current factory uses memory history, receives its initial route from `AppConfig.context.route`, and synchronizes with the host over `@history`. A direct `createWebHistory()` router is Fragment-only and is not portable to iframe or `auto` deployments that may fall back to iframe.



### How a fragment renders


A `view.page` selected for the fragment engine is mounted as `<web-fragment src="/@fragment/{id}/">`. The [`/@fragment` gateway](../../framework/views.md#web-fragments-gateway) in `wippy/views` serves the reframing contract; the `reframed` client creates a hidden same-origin realm iframe (`wf:<id>`), streams the gateway's transformed HTML into the fragment's shadow root, and runs `proxy-fragment.js` (a `@wippy-fe/proxy` adapter) inside the realm to provide the `$W` proxy API. The adapter routes the shared `postMessage` protocol to the captured same-origin Host window instead of relying on the realm's patched `window.parent`.

The same page under the iframe engine is a srcdoc `<iframe>` with `proxy.js` injected — see [Proxy & Isolation](./proxy-isolation.md).



#### Global switch (operator)


The engine for a whole deployment is the facade `render_engine` requirement → `hostConfig.renderEngine`. The default is `iframe`; only the exact string `fragment` opts a deployment into the fragment engine (any other value, including a typo, is treated as `iframe`).

```bash
wippy run -c -o wippy.facade:render_engine:default=fragment
```

See [Facade → Render engine](../../framework/facade.md#render-engine) for the parameter.



#### Per-page override (app author)


A page opts in or out with `wippy.renderEngine` in its `package.json` `wippy` block:

| Value | Behavior |
|-------|----------|
| `"auto"` (default) | Follow the global switch. |
| `"iframe"` | Always render as a srcdoc iframe — opt out of fragments regardless of the switch. |
| `"fragment"` | Prefer the fragment engine. Under a global-`fragment` deployment: always. Under a global-`iframe` deployment: only if a runtime **capability probe** (`GET /@fragment/{id}/`, cached per session) confirms the gateway + proxy are present; otherwise falls back to iframe (fail-safe). |

See [Micro Frontend Apps → Render engine](../frontend-registry/view-page.md#render-engine).



### Fragment limitations


Some browser APIs behave **incorrectly — and silently — inside a reframed realm**. A page that depends on any of these should pin `wippy.renderEngine: "iframe"`.

| API / feature | Behavior in a realm | Impact |
|---------------|---------------------|--------|
| `document.elementFromPoint` | Returns `null` — **regardless of panel size** | Breaks pointer hit-testing: drag & drop, sortable lists, Popper/floating-ui, virtual scrollers |
| `matchMedia`, `vh`/`vw` units, `position: fixed` | Resolve against the **host** viewport, not the fragment panel | Off by ~1px in a full-size panel; materially wrong in a small panel (sidebar/modal) |
| `window.scrollX/Y`, `scrollTo` | Target the hidden realm window (always `0`) | Scroll-driven UI reads the wrong geometry |
| Web Workers, Canvas, WebGL, WASM | **Work normally** | — |

`vh`/`vw` and `matchMedia` appear here because they ask about the **window**. An app that sizes itself against its allocated *surface* instead — container queries on `wippy-surface`, and the `--wippy-surface-*` variables — resolves identically under both engines and needs no pinning. See [Surface Portability](../micro-frontends/surface-portability.md), and [Surface Migration](../micro-frontends/surface-migration.md) to convert an existing app. `position: fixed` and `elementFromPoint` have no portable form and remain genuine reasons to pin.

Two detectors surface these at authoring time (they detect *app-code incompatibility*, not deployment mistakes):

- **Build-time** (`@wippy-fe/vite-plugin`): scans page source and emits a build **warning** naming the API, suggesting `wippy.renderEngine: "iframe"`.
- **Dev-runtime** (fragment proxy, DEV only): patches those APIs to `console.warn` once on an actual call.



### Enabling fragments — setup summary


Enabling the fragment engine in a consuming application requires compatible
framework modules plus the operator switch; no additional router or parameter
wiring is required:

1. **Framework modules** — use a current compatible `wippy/facade` and `wippy/views` pair that exposes the `render_engine` switch and self-mounting fragment gateway. Verify the exact release in current Wippy module documentation.
2. **The switch** — set the facade `render_engine` to `fragment` (globally) or opt pages in per-page with `wippy.renderEngine`.

> The `/@fragment` gateway is self-provided by current `wippy/views`: the module declares its own top-level router and binds it to a `server` requirement defaulting to `app:gateway`. A consumer needs no fragment wiring and boots normally on the iframe engine whether or not fragments are enabled; override the `server` parameter only if your `http.service` id differs from `app:gateway`. When a page opts into fragments per-page on an otherwise iframe deployment, a runtime capability probe confirms the gateway + `proxy-fragment.js` before switching and otherwise stays on the iframe engine. The global `render_engine: fragment` switch trusts the operator and does not probe. See [Views → Web Fragments gateway](../../framework/views.md#web-fragments-gateway).

The frontend app itself needs no fragment-specific code; `proxy-fragment.js` is a host artifact served from the CDN, not something the app bundles.



### See Also


- [Facade](../../framework/facade.md) — the `render_engine` operator switch and `hostConfig.renderEngine`
- [Views](../../framework/views.md) — the self-mounting `/@fragment` gateway and its `server` binding
- [Micro Frontend Apps (view.page)](../frontend-registry/view-page.md) — the per-page `wippy.renderEngine` field
- [Proxy & Isolation](./proxy-isolation.md) — the shared proxy API (both engines) and the iframe engine
- [Web Host Overview](./overview.md) — how the host loads and renders pages



---

# "Proxy & Isolation"

## Proxy & Isolation


This page is an API and internal-transport reference. Its snippets assume an
existing hosted page or component; they are partial integrations rather than a
complete application.

The Web Host connects page applications and web components to host services
through the **Proxy API**. A packaged page runs in either a sandboxed `srcdoc`
iframe or a Web Fragment realm, according to `hostConfig.renderEngine`. A web
component runs in the host page's DOM. All three contexts import the API from
**`@wippy-fe/proxy`**.

![Proxy API injection and nesting](../diagrams/proxy-layers.svg)



### The Proxy API


The Proxy API is your entry point to the host. An engine-specific runtime puts
the API and current child configuration in the page context and exposes them
through **`@wippy-fe/proxy`**.

- For a `view.page` using the **iframe engine**, the host injects `proxy.js` into the page's `srcdoc`.
- For a `view.page` using the **Web Fragment engine**, the fragment gateway loads `proxy-fragment.js` in the reframed realm.
- For a **web component** (`view.component`), the runtime is already present in the host page — the component mounts in the host DOM, not a separate iframe.

Your code consumes it through the sync getters exported by `@wippy-fe/proxy`:

```ts
import { host, api, on, config } from '@wippy-fe/proxy'

host.navigate('/dashboard')
const data = await api.get('/api/v1/agents')   // api is an axios instance; the await is the HTTP call
on('@visibility', (visible) => { /* pause or resume work */ })
```

Portable Vue routing is the exception: `@wippy-fe/router` consumes `@history` and reports local navigation for you. Do not add manual routing subscriptions around it.

These getters are **synchronous** once application code runs: `host`, `api`,
`on`, `config`, and the rest need no application-managed handshake. The iframe
engine starts from pre-injected config; the fragment runtime resolves its config
with the host before building the API. Mark `@wippy-fe/proxy` as `external` in
your Vite build — the host provides it through the import map. See [Proxy
API](../micro-frontends/proxy-api.md) for the full surface.



#### Iframe engine


When the host loads a `view.page`, it builds a `srcdoc` and injects, **in order, before your app's script**:

```html
<!-- 1. The child AppConfig — set synchronously, before the runtime loads -->
<script>window.__WIPPY_APP_CONFIG__ = { /* auth, env, theming, context */ }</script>
<!-- 2. The CSS-injection flags for this page -->
<script>window.__WIPPY_PROXY_CONFIG__ = { injections: { css: { themeConfig: true, primevue: true /* … */ } } }</script>
<!-- 3. The runtime (preceded by loading.js) -->
<script src="/.../loading.js"></script>
<script src="/.../proxy.js"></script>
```

Because the config global is set **before** `proxy.js` runs, the runtime initializes synchronously and the `@wippy-fe/proxy` getters work immediately — no handshake. Pages don't reference these scripts directly; the `<script data-role="@wippy/scripts">` placeholder is replaced by the host with the correct ordered tags. Per-page overrides arrive as `window.__WIPPY_CONFIG_OVERRIDES__` (see [Proxy API — Config overrides](../micro-frontends/proxy-api.md#config-overrides)).



#### Web Fragment engine


The fragment gateway serves a reframed realm stub with the Web Host import map,
`loading.js`, and `proxy-fragment.js`. The server cannot inject the client-held
auth token, so the fragment runtime obtains the child config through the
`GetConfig`/`SetConfig` handshake over its same-origin channel to the host. It
then builds the same authenticated API and config globals used by
`@wippy-fe/proxy`.

A web component sees the host page's existing API and config globals because it
runs in that page rather than in a separate page realm.



### How apps and web components differ


Both import the same API from `@wippy-fe/proxy`. They differ in execution context and how styles are delivered:

| | Page: iframe engine | Page: Web Fragment engine | Web component |
|---|---|---|---|
| Runs in | sandboxed `srcdoc` iframe | reframed same-origin realm reflected into a shadow root | host page DOM (Shadow DOM) |
| Runtime delivery | `proxy.js` injected into `srcdoc` | fragment gateway loads `proxy-fragment.js` | runtime already present in the host page |
| Config delivery | synchronous global, followed by non-blocking handshake updates | blocking host handshake owned by the fragment runtime | host page globals |
| CSS | client injection pipeline — see [CSS Injection](./css-injection.md) | gateway and fragment-realm injection — see [CSS Injection](./css-injection.md) | `hostCssKeys` into the Shadow DOM — see [Theming: Web Components](../micro-frontends/web-component-theming.md) |



### Composition & nesting


Children compose. A micro frontend app or a web component can itself host children — again micro frontend apps or web components — which can host their own, to any depth. Every level uses the same `@wippy-fe/proxy` API.

How a node hosts a child depends on the child's kind:

- **A page or HTML child** goes through `<w-iframe>`, `<w-artifact>`, or
  `html.inject`. In iframe mode these build a `srcdoc` with the base URL, import
  map, runtime, and config. In fragment mode, a nested registered `view.page`
  renders as a Web Fragment; inline HTML and other non-page content remain
  `srcdoc`. In either case its proxy bridges through the parent to the host.
- **A web component child** needs none of that. Render its tag — or load it with `loadWebComponent` / `loadByTagName` — and it runs in the same DOM, importing the Proxy API directly.

The child's own code is identical whether it runs at the top level or nested several deep: import from `@wippy-fe/proxy` and use it. There are no special nesting rules.

See [`<w-iframe>`](#w-iframe-custom-element), [`<w-artifact>`](#w-artifact-custom-element), and [Advanced HTML Injection](#advanced-html-injection) below for the mechanics.



### Internals — do not read or override


`proxy.js` or `proxy-fragment.js` installs the following globals for its own use. **Application and
component code must not read or assign them**; use `@wippy-fe/proxy` instead.
The names are listed here to prevent collisions:

| Global | What it is |
|---|---|
| `window.$W` | Async accessor object (`$W.host()`, `$W.api()`, …). Internal; `@wippy-fe/proxy` is the supported surface. |
| `window.getWippyApi` / `window.initWippyApi` | Async "resolve the instance" functions. Internal (`initWippyApi` is deprecated). |
| `window.__WIPPY_APP_API__` | The resolved proxy instance. |
| `window.__WIPPY_APP_CONFIG__` | The child `AppConfig` snapshot. |
| `window.__WIPPY_PROXY_CONFIG__` / `window.__WIPPY_CONFIG_OVERRIDES__` | CSS-injection flags and per-page overrides. |
| `window.__WIPPY_WEB_COMPONENT_CACHE__` | Loaded-component cache. |

Two entry points make up the public JavaScript API: `initWippyApp(config, rootContainer?)` mounts the whole Web Host (the module-embed entry the facade uses; see [Facade Entry Point](./entry-point.md)), and **`@wippy-fe/proxy`** is the sync API for child apps and components. Everything in the table above is internal.



### PostMessage Protocol (`IFrameMessageType`) — internal transport


This is the wire protocol the runtime uses internally; **application code never sends or receives these messages** — `@wippy-fe/proxy` handles them for you.

For a host-injected `srcdoc` page, config is present synchronously as
`window.__WIPPY_APP_CONFIG__` before `proxy.js` runs. The iframe runtime still
sends `get-config`, but that exchange is a non-blocking re-sync and live-update
channel after the initial instance exists.

For a Web Fragment page, the handshake is the initial config source: the realm
runtime requests `AppConfig`, including client-held auth, over its same-origin
channel to the host before it builds the proxy instance. The handshake is also
blocking for the manual whole-host iframe (`iframe.html?waitForCustomConfig`),
where the embedding parent must answer the first `get-config` request (see
[Facade Entry Point § Manual iframe embedding](./entry-point.md#manual-facade-less-iframe-embedding)).

Every message is a JSON envelope with shape `{ type: '@gen2-chat', action: IFrameMessageType.*, ...payload }`. The `type` field is configurable via `APP_CONFIG_IFRAME_EVENT_TYPE` but defaults to `'@gen2-chat'`.

The table lists the transport members needed to explain the public behavior on
this page. It is intentionally not an exhaustive mirror of the internal enum,
which also contains host lifecycle, chat, download, logging, bridge-response,
nav-owner, layout-mutation, breakpoint, drawer/modal, and theme-mode messages.
Those members may change without becoming an application API.

| Enum member | Wire value | Direction | Description |
|-------------|------------|-----------|-------------|
| `GetConfig` | `get-config` | Child → Host | Initial handshake: child requests its `AppConfig` |
| `SetConfig` | `set-config` | Host → Child | Host delivers `AppConfig` in response to `GetConfig` |
| `UrlWasUpdatedInParent` | `url-was-updated-in-parent` | Host → Child | Host URL changed; fires child's `@history` event |
| `VisibilityWasUpdatedInParent` | `visibility-was-updated-in-parent` | Host → Child | Iframe visibility changed; fires child's `@visibility` event |
| `TopicWasReceivedInParent` | `topic-was-received-in-parent` | Host → Child | Delivers a WebSocket topic event to subscribed children |
| `CmdRouteChanged` | `cmd-route-changed` | Child → Host | Child's internal route changed; host updates browser URL |
| `CmdTitleChanged` | `cmd-title-changed` | Child → Host | Child's `document.title` changed; host updates page title |
| `CmdStartChat` | `cmd-start-chat` | Child → Host | Open a new chat session |
| `CmdOpenSession` | `cmd-open-session` | Child → Host | Navigate to an existing chat session |
| `CmdOpenArtifact` | `cmd-open-artifact` | Child → Host | Open an artifact in sidebar or modal |
| `CmdNavigate` | `cmd-navigate` | Child → Host | SPA navigation request |
| `CmdShowToast` | `cmd-show-toast` | Child → Host | Show a toast notification |
| `CmdShowConfirm` | `cmd-show-confirm` | Child → Host | Show a confirmation dialog |
| `OnConfirmResult` | `on-confirm-result` | Host → Child | Delivers confirm dialog result |
| `CmdSetContext` | `cmd-set-context` | Child → Host | Send context to a chat session |
| `CmdHandleError` | `cmd-handle-error` | Child → Host | Report an error to the host |
| `CmdLogout` | `cmd-logout` | Child → Host | Trigger logout |
| `CmdSubscribe` | `cmd-subscribe` | Child → Host | Subscribe to a WebSocket topic |
| `CmdUnSubscribe` | `cmd-unsubscribe` | Child → Host | Unsubscribe from a topic |
| `OnSubscription` | `on-subscription` | Host → Child | Deliver subscription event data |
| `CmdStateGet` | `cmd-state-get` | Child → Host | Read a persisted state key |
| `CmdStateSet` | `cmd-state-set` | Child → Host | Write a persisted state key |
| `CmdStateRemove` | `cmd-state-remove` | Child → Host | Delete a persisted state key |
| `CmdStateClear` | `cmd-state-clear` | Child → Host | Clear all state for this page |
| `CmdStateGetAll` | `cmd-state-get-all` | Child → Host | Read all persisted state |
| `OnStateResult` | `on-state-result` | Host → Child | Delivers state read result |
| `OnStateError` | `on-state-error` | Host → Child | Reports state operation failure |
| `CmdWsSend` | `cmd-ws-send` | Child → Host | Forward a WebSocket command through host connection |
| `CmdBodySize` | `cmd-body-size` | Child → Host | Report body size for `auto-height` |
| `CmdBridgePost` | `cmd-bridge-post` | Child ↔ Parent | Fire-and-forget channel message via `host.bridge` |
| `CmdBridgeRequest` | `cmd-bridge-request` | Child ↔ Parent | Request/response channel message via `host.bridge` |
| `CmdClaimNavOwner` | `cmd-claim-nav-owner` | Child → Host | Claim navigation ownership (nav-owner mode) |
| `CmdReleaseNavOwner` | `cmd-release-nav-owner` | Child → Host | Release navigation ownership |
| `CmdLayoutSubscribe` | `cmd-layout-subscribe` | Child → Host | Subscribe to managed-layout updates |
| `CmdLayoutUpdatePanel` | `cmd-layout-update-panel` | Child → Host | Patch a panel definition |
| `CmdLayoutBroadcast` | `cmd-layout-broadcast` | Child ↔ Host | In-tab layout bus message |
| `OnLayoutChange` | `on-layout-change` | Host → Child | Full layout snapshot update |
| `OnLayoutPanelChanged` | `on-layout-panel-changed` | Host → Child | Per-panel live state delta |
| `OnLayoutBroadcast` | `on-layout-broadcast` | Host → Child | Layout bus broadcast delivery |



### `<w-iframe>` Custom Element :id=w-iframe-custom-element


`<w-iframe>` is the low-level child-page primitive built into the proxy runtime.
It accepts raw source HTML and, in the normal iframe path, injects the full Wippy
runtime (base URL, import map, `loading.js`, `proxy.js`, and child config) into a
sandboxed `srcdoc` iframe. Inside a fragment-rendered page, a nested registered
`view.page` instead uses a nested Web Fragment; inline HTML and other content
continue to use `srcdoc`.

Use `<w-iframe>` when you have source HTML and want the same runtime behavior that Wippy micro frontend apps get automatically: authenticated API, state relay, WebSocket relay, nav-owner routing, and parent-child bridge messaging.



#### Attributes and properties


| Attribute / property | Required | Default | Description |
|----------------------|----------|---------|-------------|
| `src` | No | — | URL to fetch as raw source HTML through the proxy `api`. |
| `srcdoc` | No | — | Raw source HTML. Also settable as `element.srcdoc = html` for large strings. |
| `base-url` | No | Derived from `src` or `document.baseURI` | `<base href>` injected for relative asset resolution. |
| `resource-id` | No | Element `id`, then `src` | Child context identifier; sets default state and log scope. |
| `resource-type` | No | `page` | Child context type: `page` or `artifact`. |
| `sub-path` | No | Parent route | Initial child route. Forwarded as `config.context.route` in the `GetConfig` handshake. |
| `auto-height` | No | `false` | Resizes the iframe height to match child `CmdBodySize` reports. |
| `nav-owner` | No | `false` | Intercepts child `CmdRouteChanged` and dispatches `nav-owner-route` DOM events instead of mutating host URL. |

JS properties accepted on the element:

```typescript
const frame = document.querySelector('w-iframe')
frame.proxyConfig = { injections: { css: { markdown: false } } }
frame.configOverrides = { customization: { customCSS: ':root { --brand: red }' } }
frame.srcdoc = sourceHtml
```



#### Events and methods


| Event | Detail | Description |
|-------|--------|-------------|
| `loading` | — | Fired before fetch/process/render starts. |
| `load` | — | Fired after the sandbox iframe loads. |
| `error` | Original error | Fired when fetch, injection, or load fails. |
| `nav-owner-route` | `{ path: string, navId?: number }` | Child route change when `nav-owner` is set. The event bubbles and is `composed`. |
| `wippy-message` | `{ channel, payload, requestId?, respond?, reject? }` | Bridge message from the child. |

| Method | Description |
|--------|-------------|
| `post(channel, payload?)` | Fire-and-forget bridge message to the child. |
| `request<T>(channel, payload?, { timeoutMs }?)` | Request/response bridge message; resolves with handler return value. |

Shadow parts: `loader`, `error`, `frame`.

When `nav-owner` is set, the default route-sync round-trip is fully suppressed: the host does **not** update its own URL bar and does **not** post `UrlWasUpdatedInParent` back to the child. Navigation ownership is delegated entirely to the parent code listening for `nav-owner-route`. The `path` in the event detail is the child's **raw internal route** exactly as the child passed it to `host.onRouteChanged(internalRoute, navId?)` — it is **not** mount-prefixed (unlike the default `CmdRouteChanged` path, where the host prepends the page's mount prefix). The embedding parent is responsible for any prefixing or router mapping:

```typescript
const frame = document.querySelector('w-iframe')
frame.addEventListener('nav-owner-route', (event) => {
  const { path, navId } = event.detail
  myRouter.push(path)
})
```



#### Parent-child bridge


The bridge uses named channels so neither side needs raw `postMessage` envelopes.

Parent side:
```typescript
const frame = document.querySelector('w-iframe')

frame.addEventListener('wippy-message', async (event) => {
  const { channel, payload, respond, reject } = event.detail

  if (channel === 'pick-file') {
    try {
      respond({ id: 'file-1', name: 'data.csv' })
    } catch (error) {
      reject(error)
    }
  }
})

frame.post('refresh', { reason: 'parent-click' })
const result = await frame.request('get-selection', undefined, { timeoutMs: 5000 })
```

Child side:
```typescript
import { host } from '@wippy-fe/proxy'

host.bridge.post('ready', { value: 1 })
const file = await host.bridge.request('pick-file', { accept: '.csv' })

const off = host.bridge.on('refresh', async (payload) => {
  console.log('refresh requested', payload)
  return { ok: true }
})

// Later, dispose this listener when the owning component or page scope is torn down:
// off()
```

`host.bridge.on()` returns an unsubscribe function (`() => void`). **One channel = one active handler.** If multiple handlers are registered for the same channel, the most recently registered one wins and handles **all** incoming messages on that channel — both fire-and-forget `post()` and `request()`. `on()` is not additive: earlier handlers are shadowed (not removed) and do not run while a newer handler exists, and the proxy logs a `console.warn` on duplicate registration. If the newest handler unsubscribes, the previous handler for that channel becomes active again. Use distinct channel names if you need multiple independent listeners.

If you omit `options.timeoutMs`, `host.bridge.request()` (and the parent-side `frame.request()`) default to a 10-second (`10000` ms) deadline. On timeout the returned Promise rejects with an `Error` whose message is `Bridge request <id> timed out after <ms>ms`. A request to a channel the other side has no handler for rejects immediately with `No handler registered for channel "<channel>"` rather than waiting out the deadline.



### `<w-artifact>` Custom Element :id=w-artifact-custom-element


`<w-artifact>` resolves artifact or page metadata and content, then delegates iframe-backed types to `<w-iframe>` internally. It handles content-type detection (HTML, Markdown, web page packages, ESM packages, direct-tag components) and provides a higher-level API than raw `<w-iframe>`.



#### Attributes


| Attribute | Required | Values | Default | Description |
|-----------|----------|--------|---------|-------------|
| `id` | Yes | Artifact / Page UUID | — | Content identifier. |
| `type` | No | `artifact` \| `page` | `artifact` | Determines the REST endpoint called: `/api/v1/artifact/<id>/content` or `/api/public/pages/content/<id>`. |
| `auto-height` | No | boolean flag | `false` | Forwarded to inner `<w-iframe>` for `CmdBodySize` height sync. |
| `url` | No | Any URL | — | Fetch content directly from this URL; ignores `id`/`type`. |
| `sub-path` | No | Path string | — | Forwarded to inner `<w-iframe>` as initial child route. |
| `nav-owner` | No | boolean flag | `false` | Forwarded to inner `<w-iframe>`; child route changes dispatch `nav-owner-route`. |



#### Events


| Event | When | Detail |
|-------|------|--------|
| `loading` | Before fetch starts | — |
| `load` | After iframe loads | — |
| `error` | Fetch or render fails | Original error |
| `nav-owner-route` | Nav-owner child route changes | `{ path: string, navId?: number }` |
| `wippy-message` | Bridge message from nested iframe | `{ channel, payload, requestId?, respond?, reject? }` |



#### CSS status and parts


The element sets a `status` attribute (`loading`, `ready`, `error`) and exposes shadow parts:

```css
w-artifact[status="loading"] { opacity: 0.5; }
w-artifact[status="error"]   { border: 1px solid var(--p-danger-color); }

w-artifact::part(loader) { font-size: 1rem; }
w-artifact::part(frame)  { border: 0; }
```



### `<w-iframe>` vs `<w-artifact>` vs raw `<iframe>`


| Feature | `<w-iframe>` | `<w-artifact>` | Raw `<iframe>` |
|---------|-------------|----------------|----------------|
| Injects Wippy runtime | Yes | Yes (via `<w-iframe>`) | No |
| Resolves artifact/page metadata | No | Yes | No |
| Authenticated content fetch | Yes (raw HTML) | Yes (full resolver) | No |
| State relay | Yes | Yes | No |
| WebSocket relay | Yes | Yes | No |
| Parent-child bridge | Yes | Yes (forwarded) | No |
| Nav-owner support | Yes | Yes | No |
| Content-type detection | No | Yes | No |
| CSS shadow parts | `loader`, `error`, `frame` | `loader`, `error`, `frame` | — |
| `status` attribute | Yes | Yes | No |

Use `<w-artifact>` when you have a Wippy artifact UUID or page ID and want the platform to handle all resolution. Use `<w-iframe>` when you already have source HTML and want direct runtime injection. Use a raw `<iframe>` only for completely external content that does not need the Wippy API.



### Advanced HTML Injection


For cases where you need the source-HTML-to-srcdoc transform without mounting an element, the proxy exposes `html.inject(...)`:

```typescript
import { html } from '@wippy-fe/proxy'

const processed = await html.inject(sourceHtml, {
  baseUrl: 'https://example.com/app/',
  resourceId: 'child-id',
  resourceType: 'page',
  route: '/initial',
})
```

The same function is accessible as `instance.html.inject`, `$W.html`, and `import { html } from '@wippy-fe/proxy'`. Prefer `<w-iframe>` for normal mounting; use `html.inject(...)` only when building custom hosting infrastructure.



---

# "CSS Injection"

## CSS Injection


This page is the configuration reference for Host-delivered CSS. JSON and
TypeScript blocks show individual settings and component contracts, not a
complete frontend package.

For iframe pages, the Web Host uses a layered injection pipeline to give the
child document the same visual theme as the host. Because an iframe does not
inherit CSS from its parent document, the host injects style assets into the
child's `srcdoc`; `ProxyConfig` controls those iframe layers. Web Fragment
pages use a separate delivery path described below.

This page documents the injection pipeline, all available flags, and how to customize styles at the global, host-chrome, or per-page level. It is the **canonical reference for the `proxy.injections` CSS flags and their runtime defaults** — authoring docs that show recommended explicit values link back here. For the developer-facing theming guide (CSS variable tokens, Tailwind mapping, web component patterns), see [Theming](../micro-frontends/theming.md).



### CSS Delivery Matrix


The facade exposes theming through three scopes — **global** (`custom_css`, `css_variables`, `icon_sets`), **host** (`host_custom_css`, `host_css_variables`, `host_icon_sets`), and **children** (`children_custom_css`, `children_css_variables`). The Web Host composes them per surface. Two rules govern everything below:

- **CSS custom properties (`*_css_variables`) inherit to a WC host.** WippyElement bridges names from the effective global and children/page maps through its forced-theme inner root so local theme defaults cannot reset them. This is independent of `customCss`; host-only names rely on ordinary inheritance and can be shadowed if local theme CSS redeclares them on the inner root.
- **CSS selector rules (`*_custom_css`) do not cross an iframe or shadow boundary by themselves.** The runtime injects them into the selected `view.page` realm and — **as of Web Host 1.0.43** — into each `view.component` shadow root (opt-out via the component's `customCss` flag). Before 1.0.43, only variables reached a component shadow root.

| Facade knob | Delivers | Host shell doc | `view.page` child realm | `view.component` shadow root |
|---|---|---|---|---|
| `custom_css` (global) | selector rules | ✓ injected | ✓ injected¹ | ✓ injected (1.0.43+, opt-out)¹ |
| `css_variables` (global) | custom properties | ✓ effective mode blocks | ✓ effective mode blocks | ✓ inherited + bridged |
| `host_custom_css` (host) | selector rules | ✓ injected | ✗ | ✗ |
| `host_css_variables` (host) | custom properties | ✓ `:root` | ✗ | host-mounted WCs only² |
| `children_custom_css` (children) | selector rules | ✗ | ✓ injected¹ | ✓ injected (1.0.43+, opt-out)¹ |
| `children_css_variables` (children) | custom properties | ✗ | ✓ `:root` | page WCs only² |

¹ The Web Host **composes** what a child receives: a `view.page` under either
engine and a `view.component` get **global + children** custom CSS merged into
one sheet (`children_custom_css` appended after `custom_css`). The iframe and
component `customCss` flags are gates, not literal single-scope injects; the
Web Fragment adapter applies its composed page sheet without that iframe flag.

² A web component inherits custom **properties** from the `:root` of wherever it is mounted: a host-chrome WC inherits **global + host** vars from the host document; a WC inside a `view.page` inherits **global + children** vars from that page realm. The inner-root bridge covers global and children/page variable names, not host-only names. Its injected custom **CSS** is always the children scope (global + children). Keep shared styling in `custom_css` / `css_variables` (global) — those reach every surface regardless of mount location.

**`fs://` file support:** the six theming knobs above accept an `fs://<path>` value resolved at request time from the `content_fs` filesystem — see [Facade → Reusing facade theming on non-Web-Host pages](../../framework/facade.md#reusing-facade-theming-on-non-web-host-pages). `icon_sets` / `host_icon_sets` and every non-theming JSON parameter are inline-only.

For more than a few overrides, keep CSS and JSON in separate files behind `content_fs` and reference them with `fs://`. This keeps theme assets reviewable and reusable. Do not substitute `file://`: that is a loader-time inlining mechanism, not the facade's request-time theming contract.



### The iframe injection pipeline


Styles are injected in this logical layering. The first four layers are plain
`<style>`/`<link>` elements. `cssVariables` and the non-`@import` declarations
from `customCSS` are placed in the iframe document's `adoptedStyleSheets` (see
[Override mechanism](#override-mechanism-adopted-stylesheets) below), so those
declarations win regardless of `<head>` source order. Constructable stylesheets
cannot contain `@import`, so the proxy extracts those rules into an ordinary
`<head>` style whose cascade follows normal document order:

The `view.page` iframe pipeline is `themeConfig` → `primevue`/`tailwind` →
`iframe` → `markdown` → `customVariables` → `customCss` in logical cascade
order. Configuration precedence is separate: facade theme → page
`config_overrides` → runtime override decides **which values** become
`customVariables` and `customCss`, not where the resulting styles sit in the
iframe cascade.

```
1. theme-config.css      — CSS custom properties (--p-primary-*, --p-surface-*, --p-secondary-*)
2. primevue.css          — PrimeVue component styles scoped via those variables
   tailwind.css          — Tailwind utility classes (same bundle as primevue.css)
3. iframe.css            — Default themed scrollbar styling (historical name; no iframe layout reset)
4. markdown.css          — .data-body rendering styles for Markdown content
5. cssVariables          — effective base + Auto/forced mode blocks from AppConfig.theming.global.cssVariables (adopted stylesheet)
6. customCSS             — Non-@import CSS in an adopted stylesheet; extracted @import rules use a head style
```

This list shows the logical override order, not the literal `<head>` insertion
order. The adopted-stylesheet cascade determines the precedence of
`cssVariables` and non-`@import` custom declarations; extracted imports remain
ordinary document styles. See [Override mechanism](#override-mechanism-adopted-stylesheets).

Each child iframe receives its own copies of the platform bundles enabled for that page rather than inheriting them through the host document's cascade. The Host, iframe pages, Web Fragments, and web-component shadow roots then receive their scope-specific global, host, or children customization through the delivery paths shown above; their complete style sets are not identical.



### `ProxyConfig.injections.css` Flags


These nested flags are lower camelCase in both backend registry YAML and frontend `package.json` under `wippy.proxy.injections.css`. Facade requirement names use their documented snake_case names, while registry fields follow their individual schema. Nested proxy objects are passed through without key conversion. YAML wins per nested key. See [Micro Frontend Apps (view.page) § Operator proxy override](../frontend-registry/view-page.md#operator-proxy-override-_indexyaml).

```yaml
meta:
  type: view.page
  # ...
  proxy:
    enabled: true
    injections:
      css:
        themeConfig: true
        primevue: true
        customCss: true
      tailwindConfig: false
```

```json
{
  "wippy": {
    "proxy": {
      "injections": {
        "css": {
          "themeConfig": true,
          "iframe": true,
          "primevue": true,
          "markdown": true,
          "customCss": true,
          "customVariables": true
        },
        "tailwindConfig": true,
        "resizeObserver": true,
        "preventLinkClicks": true,
        "iconifyIcons": true,
        "refreshWhenVisible": true,
        "historyPolyfill": true,
        "errorCapture": true
      }
    }
  }
}
```



#### CSS flags


| Flag | Default | What it injects |
|------|---------|-----------------|
| `themeConfig` | `true` | `theme-config.css` — all `--p-primary-*`, `--p-surface-*`, `--p-secondary-*`, and PrimeVue semantic variables. Disabling it removes this platform theme layer; enabled `customVariables` and `customCss` still apply independently. |
| `iframe` | `true` | `iframe.css` — default themed scrollbar styling. The name is historical and does not imply iframe layout rules. Keep enabled for every page for scrollbar consistency. |
| `primevue` | `true` | `primevue.css` + `tailwind.css` — PrimeVue component styles and Tailwind v3 utilities. Disable only while the entire artifact has no PrimeVue-like product UI. Framework choice alone is not an exception. |
| `markdown` | `true` | `markdown.css` — `.data-body` markdown rendering styles used by chat artifact display. |
| `customCss` | `true` | The `customCSS` string from the child-projected `AppConfig.theming.global`. |
| `customVariables` | `true` | The child-projected `cssVariables` map, compiled as effective base, Auto-light/dark, and forced Light/Dark blocks for every configured custom-property name. |

There is no dedicated fonts flag. Google Fonts are delivered through `theming.global.customCSS` (an `@import` rule), which the iframe injects via the existing `customCss` flag.



#### Non-CSS injection flags


These flags sit alongside `css` in the `injections` block:

| Flag | Default | What it does |
|------|---------|--------------|
| `tailwindConfig` | `true` | Exposes `window.tailwind.config` for apps that use the CDN Tailwind runtime (`<script src="https://cdn.tailwindcss.com">`). Not needed for Vite builds that compile Tailwind at build time. |
| `resizeObserver` | `true` | Observe the child document body and send size updates to the host. This is a body-size relay, not a browser API polyfill. |
| `preventLinkClicks` | `true` | Intercept all `<a>` clicks inside the iframe and classify them through `host.classifyLink()` before navigating. Useful for pages with external Markdown content that may contain host-navigable links. |
| `iconifyIcons` | `true` | Inject registered Iconify icon sets so `<iconify-icon>` elements work offline. |
| `refreshWhenVisible` | `true` | Reload the child window when the host's `@visibility` event changes to `true`. Disable it when a retained iframe must resume without a reload. |
| `historyPolyfill` | `true` | **No-op today.** The history polyfill is intentionally disabled for `srcdoc` iframes (`window.location` is non-configurable), so this flag has no runtime effect. The runtime always installs a history *guard* instead, which stubs `window.history` methods and warns to use memory-history routing — apps must use memory mode (e.g. `createAppRouter` memory history). Setting this flag does **not** make SPA route changes observable by the host. |
| `errorCapture` | `true` | Attach `window.onerror` and `window.onunhandledrejection` handlers that forward uncaught errors to the host via `logger.captureException`. Enable in production for centralized error collection. |

If a page omits `wippy.proxy.injections`, the iframe proxy has permissive runtime defaults and enables most injections. Vite micro frontend apps should still declare the explicit values they rely on so a package review can see whether the app expects host CSS, link interception, body-size reporting, or error capture.



#### Web Fragment delivery


Web Fragment pages do not use the iframe CSS-injection switches. The framework
gateway adds the fixed Web Host CSS assets while it rewrites the page, and the
fragment adapter applies the effective `cssVariables` and `customCSS` as
ordinary `<style>` elements in the reflected head after the AppConfig
handshake. The `proxy.injections.css` flags therefore do not gate the platform
CSS delivered to a fragment. Fragment error capture is installed
unconditionally rather than controlled by the iframe `errorCapture` flag.

See [Rendering Engines](./render-engines.md) for the engine boundary and
[Framework Views](../../framework/views.md) for the gateway configuration.



#### Disabling unwanted injections


A page may disable PrimeVue injection only while it contains no standard product controls or surfaces that PrimeVue provides. A canvas/SVG/chart-only page is valid. Once it gains a button, input, form, table, dialog, menu, tag, tooltip, or feedback control, use PrimeVue and keep the injection enabled; framework choice alone is not an omission reason.

```json
{
  "wippy": {
    "proxy": {
      "injections": {
        "css": {
          "primevue": false,
          "themeConfig": false
        }
      }
    }
  }
}
```

With both disabled the page still receives `customCSS`, `cssVariables`, and `iframe.css` (themed scrollbar styling) unless those are also turned off. The proxy API, state relay, and WebSocket bridge are unaffected by CSS flags.



### Web Components: facade custom CSS + `hostCssKeys`


Web components do not go through the iframe injection pipeline. Two channels bring the theme into a component's shadow root:

- **Configured variables + facade custom CSS.** `@wippy-fe/webcomponent-core` enumerates every effective global/children/page custom-property name, including names under `@light` / `@dark`, and installs a generic inheritance bridge after platform theme defaults. It then installs composed global + children `customCSS` as the final layer. `customCss: false` disables only the selector-rule layer; it does not disable configured-variable propagation.
- **Platform CSS assets (`hostCssKeys`).** `theme-config.css`, PrimeVue, markdown, and iframe/scrollbar styles are **static bundle assets**, not the facade's configured CSS. A component requests the ones it needs by URL through `wippyConfig.hostCssKeys` (or fetches them ad hoc with `loadCss()` from `@wippy-fe/proxy`), and the runtime injects them into the shadow root.

```typescript
static get wippyConfig() {
  return {
    hostCssKeys: ['themeConfigUrl', 'primeVueCssUrl'] as const,
  }
}
```

Use declarative `hostCssKeys` for normal component authoring. `loadCss()` is an integration escape hatch; never rewrite a mounted shadow tree with `shadowRoot.innerHTML`.

Available `hostCss` keys:

| Key | Content | Bundle impact |
|-----|---------|---------------|
| `hostCss.themeConfigUrl` | CSS variables (`--p-primary-*`, light + dark) | Small |
| `hostCss.primeVueCssUrl` | PrimeVue components + Tailwind utilities | Large |
| `hostCss.markdownCssUrl` | `.data-body` markdown rendering styles | Small |
| `hostCss.iframeCssUrl` | Scrollbar styling using `--p-surface-*` | Tiny |
| `hostCss.preflightCssUrl` | Tailwind/PrimeVue preflight base reset (normalize/reset) | Small |

A web component that wants host-faithful rendering may need to fetch `hostCss.preflightCssUrl` with `loadCss()` and insert the returned text with `injectInlineCss(shadow, css)`, because the host's base preflight reset does **not** cross the shadow boundary.

For guidance on which keys to request and when — including the decision tree for balancing style fidelity against Shadow DOM bundle size — see [WC Theming § hostCssKeys decision tree](../micro-frontends/web-component-theming.md).



### `AppConfig.theming` projection


The facade config exposes three theming scopes: `theming.global`, `theming.host`, and `theming.children`. Before a page receives its child config, the host projects the effective child theme into `AppConfig.theming.global`. The selected page engine applies that child global scope through its custom-CSS and custom-variable delivery path.

Keys are CSS variable names exactly as they should appear in CSS:

```typescript
// In the facade configuration or SetConfig PostMessage payload.
theming: {
  global: {
    cssVariables: {
      '--p-primary': 'rgb(220, 38, 38)',
      '--p-surface-0': '#0f0f0f',
      '--p-content-border-radius': '2px',
    }
  }
}
```

For iframe delivery, the compiler normalizes leading `--`, merges the top-level base with `@light` / `@dark`, and emits effective Auto-light, Auto-dark, forced Light, and forced Dark blocks in the iframe's adopted stylesheet. It is variable-agnostic: palette bases, direct shades/aliases, surfaces, typography, host tokens, and application-specific properties follow the same path. The override does not depend on `<head>` source order — see [Override mechanism](#override-mechanism-adopted-stylesheets).



#### Override mechanism: adopted stylesheets


In iframe delivery, `cssVariables` and non-`@import` declarations from
`customCSS` are **not** ordinary `<head>` `<style>`/`<link>` elements. The proxy
places them in the iframe document's
[`adoptedStyleSheets`](https://developer.mozilla.org/en-US/docs/Web/API/Document/adoptedStyleSheets)
(constructable stylesheets). Per the CSS cascade, adopted stylesheets order
**after** document stylesheets regardless of insertion order, so those
declarations win over `theme-config.css`, `primevue.css`, `iframe.css`, and
`markdown.css`. The proxy extracts `@import` rules from `customCSS` into an
ordinary `<head>` style instead; imports therefore do not receive this adopted-
stylesheet ordering guarantee. Web Fragment delivery uses ordinary `<style>`
elements in its reflected head.

Between the two iframe adopted layers, **non-`@import` `customCSS` overrides
`cssVariables`**: the sheets are ordered `cssVariables` first, then `customCSS`,
and later adopted sheets have higher priority. If the same `--p-*` token is set
in both, the non-import `customCSS` value wins.



#### Three theming scopes


The facade supports three `cssVariables` scopes to target different rendering layers:

| Scope key | Injected into | Use case |
|-----------|---------------|----------|
| `theming.global` | Host chrome and every child page | Brand colors, primary palette, shared icon sets |
| `theming.host` | Host chrome only | Sidebar, header, chat, and app-title overrides |
| `theming.children` | Child pages only | Child-only CSS variables and CSS overrides |

Child pages do not receive `theming.host` or `theming.children` as separate scopes. They receive the merged child-facing result as `config.theming.global`.



#### Per-page overrides


Individual pages can override variables via `window.__WIPPY_CONFIG_OVERRIDES__` (set in the page's registry entry as `meta.config_overrides`, or in `package.json` as `wippy.configOverrides`):

```typescript
window.__WIPPY_CONFIG_OVERRIDES__ = {
  customization: {
    cssVariables: {
      '--p-primary': '#ff6b00',
    },
    customCSS: '.my-page-header { border-radius: 12px; }',
  },
}
```

Backend YAML `config_overrides.customization` is the per-page authoring surface. Its `cssVariables` and `customCSS` keys project into frontend `theming.global.cssVariables` and `customCSS` before the page receives AppConfig, replacing the inherited child values for that page. Because the override is merged into `theming.global`, it **propagates down the whole nested sub-tree**: every child the page embeds — `<w-iframe>`, `<w-artifact>`, and `html.inject` content — is built from the page's already-merged config and inherits the theme, recursively. So a page (or a module shipping several such pages) themes everything beneath it, not just itself.



### `--wippy-host-*` Variables


The host exposes a set of `--wippy-host-*` CSS variables for customizing Web Host chrome elements — sidebar, chat bubbles, input bar, panel dividers — without touching child-page styles. Override them via `customCSS` or `cssVariables` scoped to `:root` (the variables are already prefixed and are not projected into child pages):

```typescript
theming: {
  host: {
    customCSS: `
    :root {
      --wippy-host-sidebar-width-open: 20rem;
      --wippy-host-splitter-color: transparent;
      --wippy-host-message-radius: 0.5rem;
      --wippy-host-message-user-bg: var(--p-info-100);
      --wippy-host-message-agent-bg: var(--p-warn-100);
    }
    /* Class selectors must be scoped to .wippy-host-app */
    .wippy-host-app .chat-message__footer { display: none; }
  `
  }
}
```



#### Layout variables


| Variable | Default | Description |
|----------|---------|-------------|
| `--wippy-host-sidebar-width-open` | `16rem` | Sidebar width when expanded |
| `--wippy-host-sidebar-width-closed` | `3.5rem` | Sidebar width when collapsed |
| `--wippy-host-splitter-width` | `1px` | Panel divider line width |
| `--wippy-host-splitter-hit-area` | `10px` | Panel divider drag area |
| `--wippy-host-splitter-color` | `surface-200/600` | Panel divider color |
| `--wippy-host-chat-bg` | `surface-50/700` | Chat container background |
| `--wippy-host-chat-padding-x` | `10px` | Message list horizontal padding |
| `--wippy-host-meta-bar-border-color` | `surface-200/600` | Agent/model bar border |



#### Message variables


| Variable | Default | Description |
|----------|---------|-------------|
| `--wippy-host-message-bg` | `surface-50/700` | Default message background |
| `--wippy-host-message-border-color` | `surface-200/600` | Message bubble border |
| `--wippy-host-message-shadow` | `0 1px 2px 0 rgba(...)` | Message bubble shadow |
| `--wippy-host-message-font-size` | `0.875rem` | Message body text size |
| `--wippy-host-message-radius` | `1rem` | Message bubble corners |
| `--wippy-host-message-padding-x` | `1rem` | Message horizontal padding |
| `--wippy-host-message-padding-y` | `0.5rem` | Message vertical padding |
| `--wippy-host-message-gap` | `0.5rem` | Gap between avatar and bubble |
| `--wippy-host-message-spacing` | `1rem` | Vertical spacing between messages |
| `--wippy-host-message-user-bg` | `primary-50` | User message background |
| `--wippy-host-message-agent-bg` | `yellow-50/surface-800` | Agent message background |
| `--wippy-host-tool-bg` | `help-50` | Tool call background |
| `--wippy-host-tool-border` | `help-300` | Tool call left border |
| `--wippy-host-avatar-size` | `2rem` | Message avatar diameter |



#### Input variables


| Variable | Default | Description |
|----------|---------|-------------|
| `--wippy-host-input-bg` | `surface-50/700` | Input bar background |
| `--wippy-host-input-border-color` | `surface-200/600` | Input bar top border |
| `--wippy-host-input-group-bg` | `surface-0/800` | Input field background |
| `--wippy-host-input-group-border-color` | `surface-300/700` | Input field border |
| `--wippy-host-input-group-radius` | `0.375rem` | Input field corners |
| `--wippy-host-input-min-height` | `2.5rem` | Textarea initial height |
| `--wippy-host-input-max-height` | `10rem` | Textarea max height |



#### Prompt variables


| Variable | Default | Description |
|----------|---------|-------------|
| `--wippy-host-prompt-bg` | `surface-100/800` | Prompt suggestion background |
| `--wippy-host-prompt-border-color` | `surface-300/600` | Prompt suggestion border |
| `--wippy-host-prompt-radius` | `0.5rem` | Prompt suggestion corners |

These variables only affect the host chrome. Child-page styles are unaffected.



### See Also


- [Theming](../micro-frontends/theming.md) — CSS token reference, Tailwind mapping, and web component style patterns
- [Proxy & Isolation](./proxy-isolation.md) — how the proxy injection pipeline works and what `ProxyConfig` controls at the protocol level
- [Render Engines](./render-engines.md) — host CSS reaches both srcdoc iframes and Web Fragment shadow roots



---

# "Theme Persistence"

## Theme Persistence


This page is a facade configuration guide. The external-page HTML block is a
partial integration example and assumes the facade endpoints already exist.

By default, the Web Host resolves light or dark mode from `theme_mode` (the
facade default) and keeps the choice in memory. An explicit user choice is
therefore lost on reload. Theme persistence stores the choice in a **cookie**
or **localStorage** and loads it early so the wrong theme does not flash.

Persistence lives entirely in the facade. The Web Host stays storage-agnostic: it only emits a
`themeChanged` event that the facade (or any embedder) uses to persist the choice.

> **Opt-in.** `theme_persist` defaults to **`none`** — persistence is **off** unless a deployment
> explicitly sets it to `cookie` or `localStorage`. With the default, the theme
> comes from `theme_mode` and is not remembered across reloads. Nothing is
> stored, no cookie is written, and the generated script is a no-op.



### Configuration


Two facade parameters control it (see [Frontend Facade](../../framework/facade.md)):

| Parameter | Default | Values | Description |
|-----------|---------|--------|-------------|
| `theme_persist` | `none` | `none` \| `cookie` \| `localStorage` | Where the chosen mode is stored. `none` = current behavior. |
| `theme_storage_key` | `@wippy-theme-mode` | string | Cookie / localStorage key. |

Both are returned by the public config endpoint as `themePersist` and `themeStorageKey`, so pages
served outside the Web Host can read them too.

```yaml


## in your facade dependency parameters

- name: theme_persist
  value: cookie
- name: theme_storage_key
  value: "@wippy-theme-mode"
```



#### Cookie vs localStorage


- **`cookie`** — the Jet-rendered host shell reads the cookie **server-side** and writes the
  `w-theme-*` class onto `<html>` before the response is sent, so the very first paint is already
  themed. This avoids a theme flash and is the preferred persistence option when
  first-paint consistency matters.
- **`localStorage`** — the server can't read localStorage, so the shipped shell loads
  `theme-persist.js` synchronously as the first script in `<head>`. It applies the
  stored class before the brand stylesheet, loading UI, or Web Host bundle renders.



### The generated script


When persistence is enabled the facade **generates and serves** a small script at:

```
GET /api/public/facade/theme-persist.js
```

The configured key and mode are baked in — there is nothing to configure on the page. Include it
once, as early as possible in `<head>`:

```html
<script src="/api/public/facade/theme-persist.js"></script>
```

On load it reads the stored value and applies the `w-theme-*` class, then exposes a small API:

```js
window.wippyThemePersist = {
  mode,            // 'none' | 'cookie' | 'localStorage'
  key,             // the storage key
  read(),          // -> 'auto' | 'light' | 'dark' | null
  write(mode),     // persist a mode (no-op when mode === 'none')
  apply(mode),     // toggle the w-theme-* class on <html>
}
```

The host shell (`index.html` / the Jet `index.jet`) already includes this script,
seeds the stored value into the application, and persists changes. The sections
below apply to **other** pages.



### How it fits together (host shell)


1. **First paint** — cookie mode: the server set `<html class="w-theme-dark">`. localStorage mode:
   the early-apply script set it. Either way the page is themed before the bundle loads.
2. **Bootstrap** — the shell seeds the persisted value into the host:
   `themeMode: window.wippyThemePersist.read() ?? cfg.themeMode`, so the host applies the same mode.
3. **On change** — the host emits `themeChanged(mode)`; the shell persists it:
   `events.on('themeChanged', window.wippyThemePersist.write)`.



#### The `themeChanged` host event


`globalEvents` — the emitter returned by `window.initWippyApp(...)` — fires `themeChanged(mode)`
(`'auto' | 'light' | 'dark'`) on init and on every theme change. It is persist-agnostic: the host
never touches storage; embedders decide what to do with it.

```js
const events = window.initWippyApp(config, '#app')
events.on('themeChanged', (mode) => {
  // e.g. persist, or notify a parent window
})
```



### Non-Wippy-hosted pages


A document outside the Wippy portable-module contract can honour and persist
the same theme. The native buttons below are appropriate only for such an
external static document. A Wippy page or component with these controls must
use PrimeVue under the [Portable UI Contract](../portable-ui-contract.md).
Include the generated script and call `write()` from your own switcher:

```html
<head>
  <!-- as early as possible: applies the stored theme + exposes window.wippyThemePersist -->
  <script src="/api/public/facade/theme-persist.js"></script>
  <!-- optional: reuse the facade brand theme too -->
  <link rel="stylesheet" href="/api/public/facade/variables.css">
</head>
<body>
  <button type="button" data-mode="auto">Auto</button>
  <button type="button" data-mode="light">Light</button>
  <button type="button" data-mode="dark">Dark</button>

  <script>
    document.querySelectorAll('[data-mode]').forEach((btn) => {
      btn.addEventListener('click', () => {
        const mode = btn.dataset.mode
        window.wippyThemePersist.apply(mode)   // update <html> now
        window.wippyThemePersist.write(mode)   // persist for next load / the host
      })
    })
  </script>
</body>
```

Because the key and storage mode are shared, a choice made on the login page
carries into the Web Host, and vice versa. The script receives both values from
the same facade configuration.

> Alternatively, fetch `/api/public/facade/config`, read `themePersist` and
> `themeStorageKey`, and implement storage directly. The generated script keeps
> that logic in one place.



### Server-side cookie rendering (zero flash)


For a custom server-rendered page (e.g. a Jet login template) you can apply the theme server-side,
exactly like the host shell does: read the cookie named by `theme_storage_key` from the request and
emit the matching class on `<html>`:

```html
<html lang="en"{{ if hasTheme }} class="{{ themeClass }}" style="color-scheme: {{ colorScheme }};"{{ end }}>
```

where the handler set `themeClass` to `w-theme-dark` / `w-theme-light` (and `colorScheme` to
`dark` / `light`) based on the cookie. Still include `theme-persist.js` so the page can write
changes back.



---

# "@wippy-fe Packages"

## @wippy-fe Packages


This page is a package API reference. Its snippets demonstrate isolated API
contracts and assume an existing package, Host import map, and application
lifecycle.

Public `@wippy-fe/*` packages provide the contracts used by `view.page`
applications and `view.component` web components. Web Host source also consumes
workspace builds of several of these packages. Public packages are versioned in
lockstep; this page targets Web Host 1.0.56 and public package version 0.0.56.
Host-only bundles are identified separately below and are not installable npm
packages.

Install the packages you need:

```bash
npm install @wippy-fe/proxy@0.0.56 @wippy-fe/webcomponent-vue@0.0.56 @wippy-fe/router@0.0.56
```



### Accessing the host — `@wippy-fe/proxy`


Both micro frontend apps (`view.page`) and web components (`view.component`) talk to the host the same way: synchronous named imports from `@wippy-fe/proxy`, used directly. Application code does not await an API getter or manage the runtime handshake; the selected engine's proxy adapter initializes the API before the app bundle runs.

| Goal | Import from `@wippy-fe/proxy` |
|---|---|
| Authenticated HTTP | `api` (an axios instance) |
| Host communication | `host` |
| Event subscriptions | `on` |
| Page/artifact-scoped Host-backed state | `state` |
| WebSocket | `ws` |
| Logging | `logger` |
| Child config | `config` |

Related helpers (not proxy access):

| Goal | Where |
|---|---|
| Vue routing | `createAppRouter()` + `<HostRouterLink>` from `@wippy-fe/router` |
| Web component base | `WippyVueElement` from `@wippy-fe/webcomponent-vue` |
| Component props/events | `useProps()` / `useEvents()` from `@wippy-fe/webcomponent-vue` (commonly wrapped as `useComponentProps()` / `useComponentEvents()` in your `src/constants.ts`) |
| TypeScript types | ambient via `@wippy-fe/types-global-proxy` (add to tsconfig `types`) — `AppConfig` / `ProxyApiInstance` become globals; `HostApi` = `ProxyApiInstance['host']` |
| Loading/error screens | `<wippy-loading>` / `<wippy-error>` from `@wippy-fe/loading` |

`window.$W` and `window.getWippyApi` are **internal** globals installed by the
runtime. Do not use them directly (see
[Proxy & Isolation § Internals](./proxy-isolation.md#internals-do-not-read-or-override)).



#### `@wippy-fe/proxy`


The Proxy API module — the primary package every child micro-frontend uses to talk to the Wippy host. It is a thin **synchronous** facade over the active proxy runtime (`proxy.js` for iframe pages or `proxy-fragment.js` for Web Fragments): the runtime installs the API onto internal globals, and `@wippy-fe/proxy` re-exports it as sync getters. Micro frontend apps and web components import the same getters — synchronous, with no `await` to obtain them:

```typescript
import { host, api, ws, on, state, html, sanitize } from '@wippy-fe/proxy'

// Navigate the host
host.navigate('/some-path')

// Call a backend API endpoint
const { data } = await api.get('/api/v1/agents/list')

// Send a WebSocket command
ws.sendCommand(sessionId, { command: 'stop' })

// Subscribe to a non-routing host event
on('@visibility', (visible) => { /* pause or resume work */ })

// Host-backed state in this page or artifact scope
await state.set('my-key', { value: 42 })
const value = await state.get('my-key')
console.log(value)
```

Without an explicit `scope` option, the Host keys state by the current page or
artifact resource. Instances in that same resource scope share values; unrelated
pages and artifacts do not. Pass an explicit, globally unique custom scope only
when state must cross that default boundary.

Key exports: `host`, `api`, `ws`, `on`, `state`, `html`, `sanitize`, `loadByTagName`, `loadWebComponent`, `classifyLink`.

Mark `@wippy-fe/proxy` as `external` in your Vite config — the host provides it via import map and you must not bundle your own copy.



#### `@wippy-fe/router`


Drop-in Vue Router helpers that handle the host-navigation awareness that standard `<RouterLink>` does not provide. Provides `createAppRouter()` for creating portable memory-history routers; `AutoRouterLink` (also exported as the deprecated alias `RouterLink`), a classifying drop-in replacement for vue-router's `<RouterLink>` that inspects each target and routes it as `host-nav`, `child-nav`, `external`, or `ignore`; and `HostRouterLink`, an explicit link that always forwards navigation to the host via `host.navigate()` (use it when you want host-level navigation regardless of nesting).

```typescript
import { config } from '@wippy-fe/proxy'
import { createAppRouter } from '@wippy-fe/router'

const router = createAppRouter(
  [
    { path: '/', component: Home },
    { path: '/settings', component: Settings },
  ],
  { initialPath: config.context?.route ?? '/' },
)
```

`createAppRouter()` uses memory history so the same app remains portable across iframe, Fragment, and `auto` delivery. Pass `config.context?.route` as `initialPath`; the factory synchronizes its internal route with the host via `@history` events. Direct `createWebHistory()` is Fragment-only and must not be used by an app that can fall back to iframe.



#### `@wippy-fe/theme`


Theme CSS variables, the Tailwind CSS configuration object, and PrimeVue styling integration. Exposes `PrimeVuePlugin` for installing PrimeVue into a Vue app with the correct Wippy theme preset. Provides the `theme-config.css` file containing all `--p-primary-*`, `--p-surface-*`, and `--p-secondary-*` palette variables, and the Tailwind config that maps those variables to utility classes.

JavaScript externalization and CSS delivery are separate decisions. Externalize the `@wippy-fe/theme` JavaScript specifier only when that exact key exists in the pinned Web Host import map; otherwise bundle it when imported. For a web component, separately request the CSS assets its shadow root needs through `hostCssKeys` (for example `themeConfigUrl` or `primeVueCssUrl`). See [Theming](../micro-frontends/theming.md) for the CSS pipeline.



#### `@wippy-fe/webcomponent-core`


Framework-agnostic base class for building Wippy web components. Provides `WippyElement`, which extends `HTMLElement` with lifecycle hooks (`onMount`, `onUnmount`), panel-context wiring (`this.host` for the panel-scoped proxy API wrapper), and opt-in reactive prop and event bindings.

```typescript
import { api } from '@wippy-fe/proxy'
import { WippyElement } from '@wippy-fe/webcomponent-core'

class MyWidget extends WippyElement {
  private offUpdate: (() => void) | null = null
  private loadEpoch = 0

  protected onMount(_shadow: ShadowRoot, container: HTMLElement) {
    const epoch = ++this.loadEpoch
    void this.loadName(container, epoch)
    this.offUpdate = this.host?.layout.on('update', ({ payload }) => {
      // react to cross-panel messages
    }) ?? null
  }
  protected onUnmount() {
    ++this.loadEpoch
    this.offUpdate?.()
    this.offUpdate = null
  }
  private async loadName(container: HTMLElement, epoch: number) {
    try {
      const { data } = await api.get('/api/v1/ping')
      if (this.isConnected && epoch === this.loadEpoch)
        container.textContent = `Hello from ${data.name}`
    }
    catch {
      if (this.isConnected && epoch === this.loadEpoch)
        container.textContent = 'Could not load the service name.'
    }
  }
  static get wippyConfig() {
    return { propsSchema: { properties: { label: { type: 'string' } } } }
  }
}
customElements.define('my-widget', MyWidget)
```

Also exports `getWippyHost(el)`, `getWippyHostBus(el)`, and `getWippyPanelId(el)` for raw `HTMLElement` subclasses that do not extend `WippyElement`. In 0.0.56, `WippyElement.hostVisible`, `onHostVisibilityChanged(visible, previous)`, and `reactive.hostVisibility` expose retained logical activity without treating the reserved attribute as a component prop.



#### `@wippy-fe/webcomponent-vue`


Vue 3 integration layer for Wippy web components. Provides `WippyVueElement` (a `WippyElement` subclass that mounts a Vue app into a shadow root), `define()` for registering the custom element, and composables for accessing host context inside Vue components. The exported composables are `useProps`, `useEvents`, `usePropsErrors`, `useContent`, `useHost`, `useHostVisibility`, `useHostVisibilityRefresh`, `usePanelId`, and `useLayoutBus`.

```typescript
import { define, WippyVueElement, useProps, useEvents, useHost } from '@wippy-fe/webcomponent-vue'
// ProxyApiInstance is an ambient global type from @wippy-fe/types-global-proxy (tsconfig "types") — no import
import MyApp from './MyApp.vue'

class MyVueWidget extends WippyVueElement {
  static get vueConfig() {
    return { rootComponent: MyApp }
  }
  static get wippyConfig() {
    return { propsSchema: { properties: { label: { type: 'string' } } } }
  }
}

// Standard autoload pattern — reads ?declare-tag=tagName from the URL at runtime
define(import.meta.url, MyVueWidget)
// Manual registration (use only outside the autoload system):
// define('my-vue-widget', MyVueWidget)
```

`define` has two calling conventions:

- `define(import.meta.url, Class)` — the standard autoload pattern. The function reads the `?declare-tag=tagName` query parameter from the module URL to determine the element name. Use this in all Wippy components built for autoload — it is the only form that works correctly with `wippy/views` auto-registration.
- `define('tag-name', Class)` — direct registration. Registers the custom element immediately under the given name, bypassing the `?declare-tag=` mechanism. Use only for programmatic or manual registration outside the autoload system (e.g. a standalone playground, a test harness).

Inside `MyApp.vue`:
```typescript
import { useProps, useEvents, useHost } from '@wippy-fe/webcomponent-vue'

// Read props declared in wippyConfig.propsSchema
const props = useProps<{ label: string }>()

// Emit events to the host
const emit = useEvents()
emit('selected', { id: 42 })

// Access the panel-scoped host wrapper
const host = useHost<ProxyApiInstance['host']>()
host?.layout.broadcast('my-event', { data: 'hello' })
```

`useProps()` and `useEvents()` are the library composables. Projects commonly add thin type-bound wrappers — `useComponentProps()` / `useComponentEvents()` — in their own `src/constants.ts` (e.g. `export const useComponentProps = () => useProps<ComponentProps>()`); those names are project-local, not exports of `@wippy-fe/webcomponent-vue`.

`useContent()` is also available for reading `slot`-like content injected by the host into the component.

`useHostVisibility()` returns the host-owned logical activity ref for a retained
custom element. `useHostVisibilityRefresh(task)` runs `task` after mount and
again only on an exact `false -> true` reveal, without replacing the element.
It serializes an in-flight task and coalesces intervening reveals into one
trailing refresh.
These exports are present in `@wippy-fe/webcomponent-vue` 0.0.56.



#### `@wippy-fe/layout`


Pure, framework-agnostic layout primitives used internally by the Web Host's managed-layout engine. Most child app developers use this indirectly through `@wippy-fe/vue-host` composables. Direct use is appropriate when building layout-aware tooling or custom shells.

Provides `LayoutManager` — the core class that manages the panel tree, handles breakpoint switching, validates `HostLayoutDeclaration`, and executes mutations like `resizePanel` and `collapsePanel`. Zero Vue dependency.

Direct shell authors use `LayoutManagerView` for stable panel mounts and
`useSwapBuffer()` for retained content swaps without flashing. In 0.0.56,
async readiness can be guarded by both immutable buffer index and content key,
and the splitter stack exposes `--wippy-layout-splitter-z-index`. The circular
splitter handle remains opt-in through
`--wippy-layout-splitter-handle-size` (`0` by default).



#### `@wippy-fe/vue-host`


Vue 3 composables wrapping the proxy layout API in reactive refs for use inside page modules running in managed-layout panels. The composables never return `null` — they always return objects/refs whose inner `.value` degrades when no managed-layout host is present: `snapshot.value` is `null` and `isManaged.value` is `false` (mutations become silent no-ops), `useWippyBreakpoint().value` and `useWippyMainRoute().value` are empty strings, and `useWippyPanel(id).value` is `null` for an absent id. Guard host presence with `layout.isManaged.value` (or `layout.snapshot.value !== null`), not a `=== null` check on the return value. The underlying layout subscription is module-scoped and lives for the page runtime's lifetime — there is no per-component cleanup on unmount.

| Composable | Returns |
|------------|---------|
| `useWippyLayout()` | Reactive `snapshot`, `activeBreakpoint`, `panels`, and `isManaged`, plus the surfaced mutations: `resizePanel`, `collapsePanel`, `expandPanel`, `movePanel`, `removePanel`, `closeModal`, `removeFloating` |
| `useWippyPanel(panelId)` | A `ComputedRef` to the named panel's live state (or `null` if absent); `panelId` is a required `string \| Ref<string> \| getter` |
| `useWippyBreakpoint()` | Active breakpoint name |
| `useWippyMainRoute()` | Reactive ref to the main panel's current route |



#### `@wippy-fe/shared`


Cross-boundary contract types, global-name constants, and dependency-free DOM helpers shared between the host and the `@wippy-fe/*` packages. It exports the layout-bus types (`BroadcastEnvelope`, `LayoutBusBound`, `PanelTarget`, `DropPosition`, `SizeValue`, `PixelSize`) and global-name constants (`GLOBAL_API_PROVIDER`, `GLOBAL_CONFIG_VAR`, …). In 0.0.56, it also exports `readWippyVisibility`, `setWippyVisibility`, and `WIPPY_VISIBILITY_ATTRIBUTE` for the retained-WC contract. It does **not** export `AppConfig` / `ProxyApiInstance` / `HostApi` — those are ambient types from `@wippy-fe/types-global-proxy` (below).



#### `@wippy-fe/types-global-proxy`


TypeScript ambient declarations for the proxy runtime's internal globals, including `window.$W`, `window.getWippyApi()`, `window.__WIPPY_APP_CONFIG__`, `window.__WIPPY_APP_API__`, and `window.__WIPPY_PROXY_CONFIG__`. Individual runtime globals are engine-dependent and remain internal; use the package primarily for its ambient types and use `@wippy-fe/proxy` for runtime access. Add it to `devDependencies` and reference it in `tsconfig.json`. It makes `AppConfig`, `ProxyApiInstance`, `StateApi`, `ProxyWsApi`, and the WebSocket message types available as **ambient types** you can annotate with directly (no import).

```json
{
  "compilerOptions": {
    "types": ["@wippy-fe/types-global-proxy"]
  }
}
```



#### `@wippy-fe/pinia-persist`


Pinia plugin for Host-backed state persistence. Routes Pinia store writes through the proxy's `state` API so page state survives navigation or remounting and can be shared across panels. Useful for preserving form drafts or user preferences without implementing custom persistence logic.

```typescript
import { createPinia } from 'pinia'
import { createWippyPersist, preloadWippyState } from '@wippy-fe/pinia-persist'

const pinia = createPinia()
const preloaded = await preloadWippyState()
pinia.use(createWippyPersist(preloaded))
```

Stores opt in by declaring `wippyPersist: true` in their `defineStore` options (not `persist: true`). Custom `scope` values are auto-prefixed with `@custom:` to avoid collisions with system (page/artifact UUID) scopes and must be globally unique; give two store instances separate buckets by passing a distinct per-instance `scope`.



#### `@wippy-fe/vue-utils`


Small utilities for Vue 3 apps running as Wippy pages. Currently exports `installVueWarnSuppressor(app)`, which takes your Vue app and suppresses `[Vue warn]: Failed to resolve component` warnings for kebab-named custom-element tags registered via `customElements.define(...)` (system tags `w-iframe` / `w-artifact` / `wippy-loading` / `wippy-error`, plus autoload tags). Call it once at app boot, passing the app instance:

```typescript
import { installVueWarnSuppressor } from '@wippy-fe/vue-utils'
import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App)
installVueWarnSuppressor(app)
app.mount('#app')
```

Without it you may see `[Vue warn]: Failed to resolve component` noise in the console for custom-element tags Vue's template compiler does not recognize (the elements render correctly regardless). PascalCase component typos still warn, preserving that signal. The `@wippy-fe/proxy` package re-exports this helper for convenience.



#### `@wippy-fe/vite-plugin`


Vite plugins that handle the build-time requirements for Wippy micro-frontends. Provides two plugins:

`wippyPagePlugin()` — for `view.page` modules. Reads and validates the `wippy` field in `package.json`, resolves supported `file://` references, emits `wippy-meta.json`, and injects host-less package metadata into the built HTML. It does **not** configure Rollup externals; the application must match its externals to the target Web Host import map.

`wippyComponentPlugin()` — for `view.component` modules. Similar to `wippyPagePlugin()` but targets web component output format (ESM, no HTML shell). Also emits `wippy-meta.json` with the component's `tagName` and schema.

```typescript
// vite.config.ts for a view.page module
import { wippyPagePlugin } from '@wippy-fe/vite-plugin'

export default {
  plugins: [
    vue(),
    wippyPagePlugin(),
  ],
}
```



#### `@wippy-fe/log`


Structured logger with zero production dependencies. Provides `debug`, `info`, `warn`, `error` log functions, `captureException` for error reporting, and a breadcrumb trail. Supports pluggable transports: console (default), Sentry, and GELF. Log calls include context tags that the host can use to correlate entries from child page contexts with their parent session.

```typescript
import { createChildLogger } from '@wippy-fe/log/logger'

const log = createChildLogger({ resourceId: 'my-widget' })
log.info('Widget mounted', { panelId: 'main' })
log.error('Request failed', { url: '/api/data', status: 500 })
```



#### `@wippy-fe/loading`


Zero-dependency `<wippy-loading>` and `<wippy-error>` custom elements delivered as an IIFE (`loading.js`). The host injects `loading.js` into both page engines before the engine adapter (`proxy.js` for an iframe, `proxy-fragment.js` for a Web Fragment), so these elements are available in child apps without an import.

`<wippy-loading>` — fullscreen loading spinner. Attributes: `title`, `subtitle`, `no-bg` (overlay mode without background).

`<wippy-error>` — fullscreen error display. Attributes: `title`, `message`, `icon` (`circle` | `triangle` | `sad`), `severity` (`danger` | `warning`).

```html
<!-- Show while loading -->
<wippy-loading title="Loading data..." subtitle="Please wait"></wippy-loading>

<!-- Show on error -->
<wippy-error
  title="Something went wrong"
  message="Could not load the dashboard."
  icon="sad"
  severity="danger">
</wippy-error>
```

These elements are also registered in the host itself for use in fatal-error states.



#### `@wippy-fe/chat` (not published to npm)


A set of composable chat custom elements — `<wippy-chat>`, `<wippy-chat-messages>`, `<wippy-chat-input>`, and `<wippy-session-selector>` — delivered by the Host's `chat.js` bundle. In Web Host 1.0.56 the source package is private and is not installable from npm. The iframe engine injects the shell and auto-registers the tags; the Web Fragment gateway deliberately omits `chat.js`, so fragment pages must not assume these tags are present. The heavy chat internals (Vue + PrimeVue/Shiki/markdown) are code-split and lazy-loaded on first mount.

In Web Host 1.0.56, `<wippy-chat>` reacts to `session-id` and `start-token` without
requiring element replacement. Clearing or removing a previously controlled
session starts a new token-backed chat when a token is present, while reconnects
do not replay an already consumed token. Superseded starts are race-safe.

```html
<wippy-session-selector></wippy-session-selector>
<wippy-chat></wippy-chat>
```

See [Chat Web Components](../micro-frontends/chat-web-components.md) for the full element reference — attributes, events, composition, and theming.



#### `@wippy-fe/markdown-iframe` (not published to npm)


Heavy markdown rendering bundle (markdown-it + Shiki syntax highlighting) built by the Web Host and dynamically imported by `<w-artifact>` when it renders Markdown in an iframe artifact. Web Host 1.0.56 has no public npm package manifest for this bundle; child apps should use their own markdown dependency rather than declaring `@wippy-fe/markdown-iframe` as an npm dependency.

---



### Host Import Map


Use the same pinned `<version-tag>` as `fe_facade_url` and fetch the release artifact once during development:

```bash
curl.exe -fsS "https://web-host.wippy.ai/<version-tag>/import-map.json" -o import-map.json
```

For this page's baseline, `<version-tag>` is `webcomponents-1.0.56`.

The exact keys of the fetched `imports` object are the JavaScript externalization contract:

- Put **every key** in `build.rollupOptions.external`, including packages the current application does not import. The host map is append-only, so do not maintain a smaller hand-curated subset.
- Copy the same complete `imports` object into the host-less `app.html`.
- Bundle an imported specifier only when its exact bare specifier is absent from the pinned map.
- Re-fetch when the Web Host tag changes or when adding a dependency, to check whether its exact specifier can be external.
- PrimeVue follows the same exact-subpath rule: `primevue/button` does not imply `primevue/dialog`.

Use a complete import map. A partial or placeholder
`<script type="importmap">` with JSON comments or ellipsis entries is invalid.
Use the complete fetched object for one explicit tag, or fetch and copy it
verbatim.

```typescript
// vite.config.ts
import { readFileSync } from 'node:fs'

const hostImportMap = JSON.parse(
  readFileSync(new URL('./import-map.json', import.meta.url), 'utf8'),
) as { imports: Record<string, string> }

const hostExternals = Object.keys(hostImportMap.imports)

export default {
  build: {
    rollupOptions: {
      external: hostExternals,
    },
  },
}
```

`peerDependencies` are not an identical copy of this list. Declare only npm package roots the artifact actually imports; import-map subpaths such as `@wippy-fe/log/logger` are not separate peer packages.

This contract does not define a universal host-versus-app merge or override precedence. Hosted mode uses the map delivered by the pinned Web Host release. Standalone mode uses the complete copied map in `app.html`.



---

# "Wippy Micro Frontends"

## Wippy Micro Frontends


**Classification: conceptual decision guide.** This page compares the two
artifact types and routes readers to the build and API references; it is not a
standalone project tutorial.

Wippy frontend code runs inside the Web Host's isolation boundary. You can
build two artifact types: **micro frontend apps** and **web components**. Both
are independent Vite projects, communicate with the platform through
`@wippy-fe/proxy`, and are declared to the backend in a `_index.yaml` registry
entry. They differ in how they are rendered and where they are used.



### Micro frontend app vs web component


| | Micro Frontend App (`view.page`) | Web component (`view.component`) |
|---|---|---|
| **Rendered as** | Page surface: srcdoc iframe or Web Fragment | Custom element in Shadow DOM, inside a page |
| **Has its own URL / nav entry** | Yes — claims a backend `mountRoute` | No — embedded inside another page or chat artifact |
| **Internal routing** | Yes — `vue-router` with memory history | No — single component, no router |
| **Controls its allocated surface** | Yes — the surface may be one panel, not the browser viewport | No — sized by the surrounding layout |
| **Reusable across pages** | No — one URL, one place | Yes — any page can embed the tag |
| **Receives typed props** | No — reads `AppConfig` | Yes — schema-declared HTML attributes |
| **Emits typed events** | No — communicates via proxy API | Yes — schema-declared `CustomEvent`s |
| **CSS isolation** | Engine-dependent: iframe boundary; a Web Fragment shares the host document | Shadow DOM selector boundary |

**Quick rule:** use a micro frontend app when it needs `vue-router`, a
dedicated URL, or ownership of a routed page surface. Use a web component when
it must be embeddable, reusable, and self-contained.



### What to read next


[Quickstart](./quickstart.md) provides minimal end-to-end examples for a Vue
micro frontend app and a Vue web component, with links to the public
[`app`](https://github.com/wippyai/app) repository.

Build a micro frontend app:

1. [Micro Frontend App](./micro-frontend-app.md) — scaffold, `package.json` wippy block, Vite config, bootstrap sequence, router sync
2. [Build System](./build-system.md) — `@wippy-fe/vite-plugin`, `wippy-meta.json`, externals
3. [Proxy API](./proxy-api.md) — `@wippy-fe/proxy` reference for communicating with the host
4. [Theming](./theming.md) → [Theming: Micro Frontend Apps](./micro-frontend-app-theming.md) — CSS variable catalog, then how to receive it via proxy injections

Build a web component:

1. [Web Component](./web-component.md) — scaffold, `WippyVueElement`, props, events, shadow DOM CSS
2. [Build System](./build-system.md) — same Vite toolchain, different plugin and output format
3. [Proxy API](./proxy-api.md) — same API, imported directly from `@wippy-fe/proxy`
4. [Theming](./theming.md) → [Theming: Web Components](./web-component-theming.md) — CSS variable catalog, then how to receive it across the shadow DOM boundary

Both:

- [Host-less Mode](./host-less-mode.md) — develop and test without running the full Web Host
- [Compliance Rule Index](./compliance-checklist.md) — canonical rule owners and deterministic gates
- [Debugging](./debugging.md) — symptom-first guide for the most common failure scenarios



### Prerequisites


- Wippy backend module with `wippy/views` declared as a dependency (see [Views](../../framework/views.md))
- `wippy/facade` for the Web Host entry point (see [Facade Entry Point](../web-host/entry-point.md))
- Node.js 22.12 or newer and Vite 7 for this documentation baseline. The Host
  source package declares Node 22+ and uses Vite 7; Vite 7 itself requires
  Node 20.19+ or 22.12+. `@wippy-fe/vite-plugin` 0.0.56 also accepts Vite 5 and
  6, but consumers choosing those versions must follow that Vite release's Node
  requirements



---

# "Quickstart"

## Quickstart


This page presents two condensed Vue integration recipes adapted from the public
[`wippyai/app`](https://github.com/wippyai/app) repository: a **micro frontend
app** and a **web component**. The snippets target Web Host 1.0.56 and the
public `@wippy-fe/*` 0.0.56 package family. They focus on the Wippy-specific
metadata, entry code, and registry declarations; they omit ordinary Vite
scaffolding, dependency installation, and backend setup. Use the linked
repository for complete applications rather than treating these excerpts as
standalone projects.



### Prerequisites


- A Wippy backend with the [`wippy/views`](../../framework/views.md) and
  [`wippy/facade`](../../framework/facade.md) modules wired up.
- Node.js 22.12 or newer and Vite 7 for these examples. Vite 7 requires Node
  20.19+ or 22.12+; this documentation uses the Node 22 release line.
- `@wippy-fe/vite-plugin` 0.0.56 also accepts Vite 5 and 6. If you select one of
  those versions, follow that Vite release's Node requirements.
- A coherent `@wippy-fe/*` package family selected for the target Web Host. For
  this baseline, use public packages at exactly `0.0.56` with Web Host `1.0.56`.
- The target Web Host's `import-map.json`. Externalize every listed key,
  including unused ones, and bundle an imported exact specifier only when it is
  absent.

The consumer toolchain is constrained by its selected Vite version; the Web
Host source repository has its own Node/Vite development toolchain. Verify both
when changing the target release. See [Build System](./build-system.md) for the
complete toolchain contract.

---



### Recipe 1: Micro frontend app (Vue)


A full Vue 3 SPA the Web Host renders through its selected page engine (an iframe by default, or a Web Fragment). Repo: [`frontend/applications/main`](https://github.com/wippyai/app/tree/master/frontend/applications/main).

**`package.json`** — the `wippy` block declares it a page and which CSS the host injects:

```json
{
  "name": "@example/admin",
  "version": "1.0.0",
  "specification": "wippy-component-1.0",
  "wippy": {
    "type": "page",
    "title": "Admin",
    "icon": "tabler:layout-dashboard",
    "path": "dist/app.html",
    "proxy": {
      "enabled": true,
      "injections": {
        "css": { "themeConfig": true, "iframe": true, "primevue": true }
      }
    }
  }
}
```

**`src/app.ts`** — resolve host services, mount, and wire the mandatory two-way route sync:

```ts
import { config } from '@wippy-fe/proxy'   // sync getter — no await to obtain it
import { createApp } from 'vue'
import { createAppRouter } from '@wippy-fe/router'
import App from './app/app.vue'
import { routes } from './router'

export function createMainApp() {
  const app = createApp(App)
  const initialPath = config.context?.route ?? '/'
  const router = createAppRouter(routes, { initialPath })

  app.use(router)
  app.mount('#app')
  return { app, router }
}
```

**Register it** in your module's `_index.yaml` (this is operator/deployment policy — see [Micro Frontend Apps (view.page)](../frontend-registry/view-page.md)):

```yaml
- name: admin
  kind: registry.entry
  meta:
    type: view.page
    name: admin
    announced: true        # show in the host nav sidebar
    url: /app
    base_path: app/admin
    entry_point: app.html
    mountRoute: /admin/:part(.*)*
```

Invoke the module's Make target to build into the served directory. Serve the
output where `url + base_path` points; the host then renders it at `/admin`.
The Makefile recipe uses
`npm run build -- --outDir <abs-or-relative> --emptyOutDir`; `make.ps1`
implements the same target for Windows, and `make.bat` only invokes
`make.ps1`. Full walkthrough: [Micro Frontend App](./micro-frontend-app.md).

---



### Recipe 2: Web component (Vue)


A custom element the host mounts in the page DOM (Shadow DOM), embeddable from any page or chat artifact. Repo: [`frontend/web-components/reaction-bar`](https://github.com/wippyai/app/tree/master/frontend/web-components/reaction-bar).

**`package.json`** — `wippy` block declares the tag, props (HTML attributes), and events:

```json
{
  "name": "@example/reaction-bar",
  "version": "1.0.0",
  "specification": "wippy-component-1.0",
  "browser": "dist/index.js",
  "wippy": {
    "tagName": "example-reaction-bar",
    "type": "widget",
    "props": {
      "type": "object",
      "properties": {
        "reactions": { "type": "array", "items": { "type": "string" }, "default": ["👍", "👎", "❤️"] },
        "allow-multiple": { "type": "boolean", "default": false }
      }
    },
    "events": {
      "type": "object",
      "properties": { "reaction": { "type": "object", "description": "Fired when a reaction is toggled" } }
    }
  }
}
```

**`src/index.ts`** — wrap a Vue component in `WippyVueElement` and register it. `define(import.meta.url, …)` reads the `?declare-tag=` query the host appends, which is why it must use `import.meta.url`:

```ts
import { WippyVueElement, define } from '@wippy-fe/webcomponent-vue'
import { PrimeVuePlugin } from '@wippy-fe/theme/primevue-plugin'
import ReactionBar from './app/reaction-bar.vue'
import stylesText from './styles.css?inline'
import pkg from '../package.json'

class ReactionBarElement extends WippyVueElement {
  static get wippyConfig() {
    return {
      propsSchema: pkg.wippy.props,
      hostCssKeys: ['themeConfigUrl', 'primeVueCssUrl'] as const, // pull host theme + PrimeVue into the shadow root
      inlineCss: stylesText,
    }
  }
  static get vueConfig() {
    return { rootComponent: ReactionBar, plugins: [PrimeVuePlugin] }
  }
}

export async function webComponent() {
  return ReactionBarElement
}

define(import.meta.url, ReactionBarElement)
```

**`src/app/reaction-bar.vue`** — read props and emit events with the `@wippy-fe/webcomponent-vue` composables:

```vue
<script setup lang="ts">
import Button from 'primevue/button'
import { ref, computed } from 'vue'
import { useComponentProps, useComponentEvents } from '../constants'

const props = useComponentProps()
const emit = useComponentEvents()
const active = ref(new Set<string>())
const reactions = computed(() => props.value.reactions ?? [])

function toggle(emoji: string) {
  active.value.has(emoji) ? active.value.delete(emoji) : active.value.add(emoji)
  active.value = new Set(active.value)
  emit('reaction', { emoji, count: active.value.has(emoji) ? 1 : 0, active: active.value.has(emoji) })
}
</script>

<template>
  <Button
    v-for="emoji in reactions"
    :key="emoji"
    :label="emoji"
    :aria-label="`Toggle ${emoji} reaction`"
    :aria-pressed="active.has(emoji)"
    text
    @click="toggle(emoji)"
  />
</template>
```

(`useComponentProps` / `useComponentEvents` are thin `useProps()` / `useEvents()` wrappers defined in `src/constants.ts`.)

**Register it** as a `view.component` (all three gates are required for autoload — see [Web Components (view.component)](../frontend-registry/view-component.md)):

```yaml
- name: reaction-bar
  kind: registry.entry
  meta:
    type: view.component
    name: reaction-bar
    tag_name: example-reaction-bar
    announced: true
    auto_register: true
    url: /app/wc/reaction-bar
    entry_point: index.js
```

After the build, any page or chat artifact can use the tag:

```html
<example-reaction-bar reactions='["👍","🎉"]'></example-reaction-bar>
```

Full walkthrough: [Web Component](./web-component.md).

---



### Explore more


The [`app`](https://github.com/wippyai/app) repo ships several runnable web components under [`frontend/web-components/`](https://github.com/wippyai/app/tree/master/frontend/web-components):

| Component | Demonstrates |
|---|---|
| `reaction-bar` | Props + event emission |
| `counter-persist` | State that survives reloads via `@wippy-fe/pinia-persist` |
| `chart-circle` | Bundling a third-party library (Chart.js) in the Shadow DOM |
| `mermaid` | Children content (`<template data-type="…">`) + a lazy fallback bundle |
| `markdown` | `markdown-it` + `sanitize-html` |
| `websocket-log` | Live data via `on(...)` topic subscriptions |
| `model-gallery` | Authenticated API calls through the proxy + PrimeVue in Shadow DOM |

For theming either artifact, read [Theming](./theming.md) → [Theming: Micro Frontend Apps](./micro-frontend-app-theming.md) / [Theming: Web Components](./web-component-theming.md). To run locally without the full host, see [Host-less Mode](./host-less-mode.md).



---

# "Page Recipe"

## Page Recipe


A page is a Vite-built application rendered through either the legacy
`about:srcdoc` iframe engine or the Web Fragment engine. Its route and host
context come from Wippy AppConfig and packages, not from browser location.

This is an integration recipe for an existing Vue/Vite project. It identifies
the Wippy-specific entry code and deployment contract; it does not provide a
standalone project scaffold or backend setup.



### Required setup


1. Register a `view.page` and its serving filesystem/router entries.
2. Enable required CSS delivery. When the iframe engine may be selected, keep the `iframe` CSS block enabled for default scrollbar consistency.
3. Use `@wippy-fe/router` for Vue routing.
4. Install PrimeVue and the Wippy PrimeVue plugin when the page renders any PrimeVue-like control.
5. Use the shared Wippy Tailwind preset when the page authors Tailwind utilities.
6. Generate externals from the pinned Web Host import-map snapshot.
7. Mount the application at `#app`; content-sized Web Fragments require that exact root id.
8. Build into the deployment-selected output directory.

```ts
import { createApp } from 'vue'
import PrimeVue from '@wippy-fe/theme/primevue-plugin'
import { createAppRouter } from '@wippy-fe/router'
import { config } from '@wippy-fe/proxy'
import App from './App.vue'
import { routes } from './routes'

const app = createApp(App)
app.use(PrimeVue)
app.use(createAppRouter(routes, {
  initialPath: config.context?.route ?? '/',
}))
app.mount('#app')
```

Verify the exact exported signatures against the selected package version. Do not create a local router synchronization layer.



### Theme injection


The page consumes the facade theme delivered into its selected page realm. Use public PrimeVue components, public theme variables, documented runtime-backed Tailwind utilities, and explicitly invariant compile-time utilities.

Do not use a host query parameter as an application fixture. AppConfig owns host context.



### Build


Invoke the Wippy module repository's Make target. Its recipe supplies the
deployment output with:

```text
npm run build -- --outDir <target> --emptyOutDir
```

`vite.config.ts` keeps relative asset behavior and does not hardcode deployment `outDir`.

Do not invoke the underlying package-manager or Vite build command directly.
On Windows, invoke `make.bat`; it delegates to the target's `make.ps1`
implementation.

See [Build and Dependency Contract](./build-system.md), [Platform Topology](../platform-topology.md), and [Configuration and Casing](./configuration-casing.md).



---

# "Web Component Recipe"

## Web Component Recipe


A web component is registered as `view.component` and normally renders in a shadow root. Choose the smallest valid setup.

These are integration recipes for an existing Vue/Vite project. They show the
Wippy-specific element, metadata, and build configuration rather than a
standalone project scaffold.



### Variant A: content-only


A chart, diagram, renderer, or visualization may omit PrimeVue and Tailwind when it renders no control and authors no shared Tailwind utility.

It still must:

- Publish a valid custom-element tag.
- Preserve accessibility for rendered content.
- Use supported Wippy configuration and CSS delivery.
- Avoid project-private facade classes.
- Build through the Wippy module repository's canonical Make target.

If a button, input, form, menu, or other PrimeVue-like control is later added, this exemption ends.



### Variant B: control-bearing


A component with controls must install PrimeVue through the Wippy PrimeVue
plugin and receive the host's theme and PrimeVue CSS. The web-component package
loads all host CSS keys by default; the explicit list below narrows that default
to the assets this example uses plus the shared iframe/scrollbar CSS:

```ts
import { defineComponent, h } from 'vue'
import Button from 'primevue/button'
import { PrimeVuePlugin } from '@wippy-fe/theme/primevue-plugin'
import {
  WippyVueElement,
  define,
  type WippyElementConfig,
} from '@wippy-fe/webcomponent-vue'
import pkg from '../package.json'

const Root = defineComponent({
  name: 'ExampleControlsRoot',
  setup() {
    return () => h(Button, { label: 'Save' })
  },
})

class ExampleControlsElement extends WippyVueElement {
  static get wippyConfig(): WippyElementConfig {
    return {
      propsSchema: pkg.wippy.props,
      hostCssKeys: ['themeConfigUrl', 'primeVueCssUrl', 'iframeCssUrl'],
    }
  }

  static get vueConfig() {
    return {
      rootComponent: Root,
      plugins: [PrimeVuePlugin],
    }
  }
}

export async function webComponent() {
  return ExampleControlsElement
}

define(import.meta.url, ExampleControlsElement)
```



#### Package metadata contract


The package metadata must identify the same custom element:

```json
{
  "name": "@example/controls",
  "version": "0.1.0",
  "type": "module",
  "specification": "wippy-component-1.0",
  "browser": "dist/index.js",
  "wippy": {
    "type": "component",
    "tagName": "example-controls",
    "props": {
      "type": "object",
      "properties": {},
      "additionalProperties": false
    }
  }
}
```

Valid package `wippy.type` values are `"component"` and `"widget"`. Do not use
the registry kind `view.component` as a package `wippy.type` value.

The component build uses the strict Wippy component plugin and the complete
pinned target-host import-map snapshot:

```ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { wippyComponentPlugin } from '@wippy-fe/vite-plugin'
import hostImportMap from './wippy-import-map.json'

export default defineConfig({
  plugins: [vue(), wippyComponentPlugin({ required: true })],
  build: {
    lib: {
      entry: 'src/element.ts',
      formats: ['es'],
      fileName: 'index',
    },
    rollupOptions: {
      external: Object.keys(hostImportMap.imports),
      preserveEntrySignatures: 'strict',
    },
  },
})
```

Keep `preserveEntrySignatures: 'strict'`. Other Rollup values do not satisfy the
Wippy component build contract documented here.

Use the shared Wippy Tailwind preset when this component authors Tailwind
utilities. PrimeVue itself does not require a module to invent Tailwind
utilities.



### Shadow-root rules


- Public CSS variables may inherit into the shadow root.
- Selector rules take effect only if the host delivers them into the root.
- Shared PrimeVue theme CSS is a supported dependency.
- Arbitrary facade classes are not portable APIs.
- Overlay placement must be verified in the real runtime; do not force a generic placement recipe.



### Metadata and build


Document props and events in package metadata. A registry entry may repeat them
as deployment-specific `meta.props` and `meta.events` overrides; when present,
those overrides take precedence over the bundled metadata. Invoke the module
repository's Make target; its recipe uses:

```text
npm run build -- --outDir <target> --emptyOutDir
```

Do not invoke that underlying command directly. On Windows, invoke
`make.bat`; it delegates to `make.ps1`.

See [Theme Authoring](./theming.md), [Tailwind Contract](./tailwind-contract.md), and [Build and Dependency Contract](./build-system.md).



---

# "Chat Web Components"

## Chat Web Components


**Classification: API reference with partial embedding examples.** The HTML
and JavaScript blocks assume a hosted child where the chat element shell is
available, a valid session UUID or agent start token, and application-owned
mount and teardown code.

The Wippy chat UI is available as **composable custom elements** in contexts
where the Host injects the chat shell. A srcdoc iframe child can embed live
chat by tag without Vue imports or registration. The elements use the same chat
components and `ChatTransport` → `SessionManager` data layer as the host.

These are host-provided elements to consume. Unlike a
[Web Component](./web-component.md) that you build yourself, you do not author
or register them. The srcdoc iframe injector makes them available by tag. The
Web Fragment gateway in the pinned Framework release deliberately omits
`chat.js`, so a Fragment page cannot assume these tags exist; use the host chat
controls there instead (see [How they load](#how-they-load)).

> Use these when you want a chat surface *inside your own page or panel*. To open the host's own chat panel imperatively instead, use `host.startChat(token)` / `host.openSession(sessionUUID)` from `@wippy-fe/proxy` (see [Proxy API](./proxy-api.md)).



### The elements


| Tag | Renders | Key attributes | Events |
|-----|---------|----------------|--------|
| `<wippy-chat>` | Full chat — header + messages + input | `session-id`, `start-token`, `agent`, `show-selector`, `hide-header` | `session-started`, `error` |
| `<wippy-chat-messages>` | Message list only | `session-id` | — |
| `<wippy-chat-input>` | Composer only | `session-id` | — |
| `<wippy-session-selector>` | Session picker | `active-session-id` | `select` |

Every element also accepts two per-instance theming attributes — **`custom-css`** and **`css-variables`** — covered in [Theming](#theming).



### How they load


The chat elements ship like
[`<wippy-loading>`](../web-host/packages.md#wippy-feloading): a small
`@wippy-fe/chat.js` shell auto-registers all four tags. The srcdoc iframe
injector includes it in the host `scripts` array alongside `loading.js` and
`proxy.js`, so iframe-delivered pages do not install a package or call
`customElements.define()`.

The Framework's Web Fragment gateway injects `loading.js` and
`proxy-fragment.js`, but not `chat.js`. Fragment-delivered pages should use
`host.startChat()` or `host.openSession()` unless a later platform contract
adds an explicit chat-shell opt-in. Direct web components mounted in the host
document must likewise not assume that another child realm registered the tags.

The implementation dependencies are code-split into a separate `chat-internals.[hash].js` chunk and **lazy-loaded on first mount**. While the chunk downloads, the element shows a `<wippy-loading>` placeholder; if the load fails it shows `<wippy-error>`. Pages that never mount a chat tag do not load the internals.



### `<wippy-chat>`


Reactive session control requires Web Host `1.0.51` or newer. The element shell
is a Host-injected asset rather than a public `@wippy-fe/chat` package; older
Host releases only support the initial mount reliably.

The full chat surface: header, scrollable message list, and composer.

| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| `session-id` | string | — | Render this existing session (a session UUID). |
| `start-token` | string | — | Agent start token; starts a **new** session on mount when no `session-id` is set. |
| `agent` | string | — | Agent name (or title) to pre-select in the empty state, shown when no session is open. |
| `show-selector` | boolean | `false` | Render the built-in session selector in the header. |
| `hide-header` | boolean | `false` | Hide the agent/model header bar (for compact embeds). |

**Events** (dispatched as `CustomEvent`s on the element; read `event.detail`):

| Event | `detail` | When |
|-------|----------|------|
| `session-started` | `{ sessionId: string }` | A session is started — from `start-token` on mount, or by user action. |
| `error` | `{ message: string }` | Session initialization fails (e.g. an invalid `start-token`). |

```html
<!-- Start a new session from an agent start token -->
<wippy-chat start-token="agent-start-token" agent="researcher"></wippy-chat>

<!-- Pin an existing session -->
<wippy-chat session-id="019eb2ae-1234-5678-abcd-ef1234567890"></wippy-chat>

<!-- Built-in selector, no header bar -->
<wippy-chat show-selector hide-header></wippy-chat>
```

```javascript
document.querySelector('wippy-chat')
  .addEventListener('session-started', (e) => {
    console.log('session:', e.detail.sessionId)
  })
```



#### Reactive control without remounting


Keep one `<wippy-chat>` element mounted and update its attributes. A changed
`session-id` opens that session in place. Setting `session-id=""` or removing a
previously controlled attribute is an explicit **New Chat** transition: it
clears both the pinned and shared active session. An element that never had a
`session-id` remains selector-driven instead; absence on first mount is not a
clear command.

When a `start-token` is present, clearing `session-id` starts from that token
again. Changing the token also starts in place. The element consumes a token
once per custom-element host, so reconnecting or moving the same element does
not replay a live start. If a newer token, controlled session, manual selection,
or disconnect supersedes an in-flight start, the stale result cannot replace
the current session; any late-created session is closed.

```javascript
const chat = document.querySelector('wippy-chat')

chat.setAttribute('session-id', existingSessionId)

// New Chat with an agent. No element replacement is required.
chat.setAttribute('start-token', agentStartToken)
chat.removeAttribute('session-id')
```

Managed-layout component resolvers update and remove props on the existing
custom element. They remount only when `tagName` changes, preserving the chat
input, scroll position, and element-owned lifecycle state across panel updates.



### `<wippy-chat-messages>` and `<wippy-chat-input>`


The message list and the composer as separate elements, so you can lay them out yourself. Each takes a single `session-id`; with no explicit `session-id` they follow the [shared active session](#composition-and-shared-session) set by a `<wippy-session-selector>`. Neither emits events.

```html
<!-- Custom layout: messages above, composer below -->
<div style="display:flex; flex-direction:column; height:100%;">
  <wippy-chat-messages session-id="019eb2ae-…"></wippy-chat-messages>
  <wippy-chat-input    session-id="019eb2ae-…"></wippy-chat-input>
</div>
```



### `<wippy-session-selector>`


A session picker. It drives the shared active session that other elements follow.

| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| `active-session-id` | string | — | Highlight this session as active. |

**Event:**

| Event | `detail` | When |
|-------|----------|------|
| `select` | `{ sessionId: string }` | The user picks a session. The picked session becomes the shared active session. |

```html
<wippy-session-selector></wippy-session-selector>
```

```javascript
document.querySelector('wippy-session-selector')
  .addEventListener('select', (e) => {
    console.log('picked:', e.detail.sessionId)
  })
```



### Composition and shared session


Elements with **no explicit `session-id`** follow the `<wippy-session-selector>`'s pick via the manager's shared `activeSessionId`. So a selector plus a chat (or a selector plus a separate messages + input) on one page stay in sync — pick a session in the selector and the others update. Elements that **do** carry an explicit `session-id` (or `start-token`) are pinned and ignore the selector.

```html
<!-- Selector + chat: the chat follows the picked session -->
<wippy-session-selector></wippy-session-selector>
<wippy-chat></wippy-chat>

<!-- Selector + split message list / composer, all following the selector -->
<wippy-session-selector></wippy-session-selector>
<wippy-chat-messages></wippy-chat-messages>
<wippy-chat-input></wippy-chat-input>

<!-- Pinned chat alongside a selector-driven one -->
<wippy-chat session-id="019eb2ae-…"></wippy-chat>  <!-- ignores the selector -->
<wippy-chat></wippy-chat>                            <!-- follows the selector -->
```



### Theming


Each element renders in a shadow root, so host page styles do not leak in or out. Two mechanisms apply theme:

- **Inherited CSS variables.** Theme custom properties (`--p-primary-*`, `--p-text-color`, …) inherit across the shadow boundary from the host theme, so the chat follows the active palette and dark/light mode. Selector-based styles (PrimeVue, markdown, Tailwind) are bundled into a `chat-elements.css` sheet and injected into the shadow root. `PrimeVuePlugin` redirects the default body/null Portal target to a pinned overlay layer inside the owning shadow root. Do not set `appendTo: 'self'` routinely: that is an explicit inline-placement opt-in and can clip inside scrolling Dialog or Drawer content. Toasts are delegated to the **host's native toast** over the proxy rather than rendered in-shadow.
- **Per-instance overrides.** Every element accepts two attributes:

| Attribute | Type | Effect |
|-----------|------|--------|
| `custom-css` | string | Raw CSS appended **last** into the element's shadow root, so it wins by order. |
| `css-variables` | object (JSON) | Per-instance CSS variable overrides applied to `:host`. Keys may omit the leading `--`. |

Treat both attributes as trusted application configuration. Do not copy
untrusted user input into raw CSS or variable values; CSS can alter or obscure
the embedded interface and can initiate external resource requests.

```html
<wippy-chat
  session-id="019eb2ae-…"
  custom-css=".message-item { max-width: 80%; }"
></wippy-chat>
```

Omitting `css-variables` is the normal facade-respecting path. Per-instance color overrides are for deliberate embedding isolation, not routine restyling.

For the full theming model — semantic variables, dark/light flipping, and how the host injects shadow-DOM CSS — see [Theming: Web Components](./web-component-theming.md).



### Runtime wiring


Inside a srcdoc iframe child, the elements require no additional setup. Auth
and config come from the injected proxy runtime; REST and WebSocket use the
config's environment URLs. When a chat tag mounts, the already-registered
shell loads the internals on demand and connects with the child's existing
session. Web Fragment and direct-host contexts have the availability limits
described in [How they load](#how-they-load).



### See Also


- [Web Component (`view.component`)](./web-component.md) — building your own custom element
- [@wippy-fe Packages](../web-host/packages.md) — the host import map and injected element shells (`@wippy-fe/chat`, `@wippy-fe/loading`)
- [Theming: Web Components](./web-component-theming.md) — shadow-DOM CSS and semantic variables
- [Proxy API](./proxy-api.md) — `host.startChat` / `host.openSession` and the rest of `@wippy-fe/proxy`
- [Proxy & Isolation](../web-host/proxy-isolation.md) — how the host injects scripts and config into children



---

# "Proxy API"

## Proxy API


**Classification: API reference with partial integration snippets.** The
examples assume a Host-delivered child, valid deployment URLs and credentials,
and application values such as `file`, `uuid`, event handlers, and routes. They
show one API operation at a time rather than a standalone project.

Child apps and web components communicate with the Wippy host through the proxy runtime (`proxy.js`). Application code uses named getters from **`@wippy-fe/proxy`**, its thin synchronous facade. The same imports work for both surfaces:

- **Micro Frontend Apps (`view.page`)** run through the selected srcdoc iframe or Web Fragment adapter, which provides the same proxy contract.
- **Web components (`view.component`)** run as ESM modules in the host page; the host provides `@wippy-fe/proxy` through the import map.

For how the runtime is loaded into each context, see [Proxy & Isolation](../web-host/proxy-isolation.md).



### Initialization


`@wippy-fe/proxy` exports synchronous getters — `host`, `api`, `on`, `config`, `state`, `ws`, `logger`, `sanitize`, `html`, `loadCss`, `loadWebComponent`, `loadByTagName`, `hostCss`, `define`, `classifyLink`, `installVueWarnSuppressor`, `addIcons`, `tailwindConfig`. Import what you need and use it directly. The host injects the child config before the runtime loads for both `view.page` apps and `view.component` web components, so the getters are available when application code runs. There is **no** `getWippyApi`, no `instance`, and no `GetConfig`/`SetConfig` handshake to wait on. Await only actual asynchronous operations such as HTTP calls and state reads.

```ts
import { host, api, config, state, ws, logger } from '@wippy-fe/proxy'

host.navigate('/dashboard')
const agents = await api.get('/api/v1/agents')   // api is axios; the await is the HTTP call, not obtaining `api`
const token = config.auth.token
```

Iframe and Web Fragment apps receive lifecycle visibility through the proxy
`@visibility` topic. Direct web components do not: use `useHostVisibility()`
or `useHostVisibilityRefresh()` from `@wippy-fe/webcomponent-vue`, or the
equivalent `WippyElement` APIs.

Fetch the target Web Host release's `import-map.json` once during development
and use every key in its `imports` object as a Rollup external. This includes
`@wippy-fe/proxy`; do not maintain a one-package or imported-only external
list. Re-fetch only when the Web Host tag changes or when adding a dependency
to check whether its exact specifier can be external:

```typescript
// vite.config.ts (after saving the fetched response as import-map.json)
import { readFileSync } from 'node:fs'

const hostImportMap = JSON.parse(
  readFileSync(new URL('./import-map.json', import.meta.url), 'utf8'),
)

export default defineConfig({
  build: {
    rollupOptions: {
      external: Object.keys(hostImportMap.imports),
    },
  },
})
```



#### TypeScript types


The proxy types — `AppConfig`, `ProxyApiInstance`, `StateApi`, `ProxyWsApi`, and the WebSocket message types — ship as **ambient declarations** in `@wippy-fe/types-global-proxy`, not as named exports of any package. Add it to your `tsconfig.json` `types` (or use a triple-slash reference) and they are available globally — no import:

```jsonc
// tsconfig.json
{ "compilerOptions": { "types": ["@wippy-fe/types-global-proxy"] } }
```

```typescript
// AppConfig, ProxyApiInstance, … are ambient globals — annotate with them directly, no import:
function render(cfg: AppConfig) { /* … */ }
type HostApi = ProxyApiInstance['host']   // HostApi is this indexed type, not a separate export
```

There is **no** `import … from '@wippy-fe/shared'` for the proxy APIs above. `@wippy-fe/shared` carries cross-package types and `GLOBAL_*` name constants; starting with `0.0.52`, it also exports the runtime retained-WC
helpers `readWippyVisibility`, `setWippyVisibility`, and
`WIPPY_VISIBILITY_ATTRIBUTE`. Direct WC authors normally use
`useHostVisibility()` or `useHostVisibilityRefresh()` from
`@wippy-fe/webcomponent-vue`; the proxy `@visibility` event remains an
iframe/Web Fragment channel.



#### Internals (do not use)


The runtime installs a handful of globals for its own use — `window.$W`, `window.getWippyApi`, `window.initWippyApi`, and the `window.__WIPPY_*` set. **Application and component code must never read or override them.** Always go through `@wippy-fe/proxy` instead. The names are listed to prevent collisions; see [Proxy & Isolation § Internals](../web-host/proxy-isolation.md#internals-do-not-read-or-override).

> `@wippy-fe/proxy` (documented here) is the API your child code uses. The host's own bootstrap, `initWippyApp(config, rootContainer?)`, mounts the whole Web Host on the module-embed / facade path — child app code never calls it.

---



#### `config`


The child application configuration delivered by the host. It is a plain object (not a function), imported directly and ready to read synchronously. This page documents only the current `wippy-context-2.0` contract.

```typescript
import { config } from '@wippy-fe/proxy'

const token = config.auth.token
```

```typescript
interface ChildAppConfig {
  $schema: 'wippy-context-2.0'
  auth: {
    token: string
    expiresAt: string
  }
  env: {
    APP_API_URL: string
    APP_AUTH_API_URL: string
    APP_WEBSOCKET_URL: string
    [key: string]: string | undefined
  }
  axiosDefaults?: Partial<AxiosDefaults>
  routePrefix?: string
  apiRoutes?: Record<string, string>
  themeMode?: 'auto' | 'light' | 'dark'
  theming: {
    global?: {
      customCSS?: string
      cssVariables?: Record<string, string>
      icons?: Record<string, unknown>
      iconSets?: Record<string, Record<string, unknown>>
    }
  }
  context: {
    resourceId: string
    resourceType: 'page' | 'artifact'
    route?: string
    [key: string]: unknown
  }
  selfPageId?: string
  mountRoutes?: Record<string, string>
}
```

For dynamic pages, if the host URL is `/c/page-id/something/else?foo=1`:
- `config.context?.route` carries `/something/else?foo=1`.
- `config.path` is a deprecated compatibility field from pre-`wippy-context-2.0` payloads and should not be used in new code.

---



#### `host`


The host communication API (`HostApi`). Imported directly and used synchronously.

```typescript
import { host } from '@wippy-fe/proxy'
```

---



#### `host.setThemeMode(mode)` and `host.getThemeMode()`


Theme mode is host state carried by AppConfig. Switch it only through the
public proxy API:

```typescript
import { host, on } from '@wippy-fe/proxy'

async function setThemeMode(mode: 'auto' | 'light' | 'dark') {
  if (host.getThemeMode() === mode) return

  await new Promise<void>((resolve, reject) => {
    let settled = false
    let unsubscribe = () => {}
    const finish = (error?: unknown) => {
      if (settled) return
      settled = true
      window.clearTimeout(timeout)
      unsubscribe()
      if (error) reject(error)
      else resolve()
    }
    const timeout = window.setTimeout(
      () => finish(new Error(`Timed out waiting for theme mode: ${mode}`)),
      5_000,
    )

    unsubscribe = on('@theme', (appliedMode) => {
      if (appliedMode !== mode) return
      finish()
    })

    // Subscribe before the command so a fast propagation event cannot be lost.
    try {
      host.setThemeMode(mode)
    } catch (error) {
      finish(error)
    }
  })
}

await setThemeMode('dark')
```

The accepted modes are `auto`, `light`, and `dark`. `auto` follows the
operating-system preference. A change is applied to the host, written back to
AppConfig, broadcast to live iframe and Web Fragment page realms and direct web
components, and forwarded through nested Wippy containers. Subscribe to
`@theme` when code needs to wait for the applied child state. Release the
subscription during component unmount.

The host does not own persistence. The embedding facade listens for the host
theme-change event and persists the user choice as described in
[Theme Persistence](../web-host/theme-persistence.md).

Do not add or remove `w-theme-dark` / `w-theme-light` classes, call the internal
`applyThemeMode`, mutate AppConfig stores, synthesize proxy messages, or use
`window.getWippyApi`. Those are Web Host implementation details, not application
or browser-test APIs. Runtime tests must exercise `host.setThemeMode()`, wait
for the propagated `@theme` event, and verify `host.getThemeMode()` before
capturing appearance. AppConfig is the host-to-child transport; do not mutate
its internal store or rely on an earlier imported config snapshot as the
completion signal.

There is no `host.applyTheme()` method.

---



#### `host.startChat(agentToken, options?)`


Opens a new chat session using the provided agent start token.

```typescript
host.startChat(agentToken: string, options?: { sidebar?: boolean }): void
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `agentToken` | `string` | — | Token that identifies which agent to start |
| `options.sidebar` | `boolean` | `false` | `true` opens the chat in the right sidebar panel; `false` opens in the main area |

```typescript
host.startChat('my-agent-token')                     // Main area
host.startChat('my-agent-token', { sidebar: true })  // Right sidebar
```

---



#### `host.openSession(sessionId, options?)`


Opens an existing chat session by UUID.

```typescript
host.openSession(sessionId: string, options?: { sidebar?: boolean }): void
```

```typescript
host.openSession('abc-123-uuid', { sidebar: false })
```

---



#### `host.navigate(url)`


Requests SPA navigation from the host. Supported patterns:

- `/c/<page-id>` — navigate to a dynamic page
- `/c/<page-id>/<sub-path>` — dynamic page with sub-path
- `/chat/<session-id>` — open a chat session
- Any mount route claimed by a page with `mountRoute` in its registry entry

```typescript
host.navigate(url: string): void
```

```typescript
host.navigate('/c/my-page-id')
host.navigate('/chat/session-uuid')
host.navigate('/keeper')
```

> **Managed-layout caveat.** `startChat`, `openSession`, `openArtifact`, and
> `navigate` act directly on the standard compat shell. In `fe_mode = managed`
> they publish typed `@HOST/intent` messages. Declare the shipped
> `@HOST/compat-coordinator`, or an equivalent coordinator, to map those intents
> to declared chat, artifact, modal, and main-route panels. Managed mode has no
> implicit compat chrome; without a coordinator the intents are published but
> nothing renders them. See [Multi-Panel Layout § What works in which mode](../web-host/multi-panel-layout.md#what-works-in-which-mode).

---



#### `host.onRouteChanged(internalRoute, navId?)` — low-level router integration


Notifies the host when the page's internal route changes. The host updates the browser URL bar to include the child's route. This call is **required** — without it the host URL stays on the page root and the browser back button does not work for child navigation.

```typescript
host.onRouteChanged(internalRoute: string, navId?: number): void
```

Portable Vue applications use `createAppRouter()` from `@wippy-fe/router`; the package owns this call, the matching `@history` subscription, normalization, and echo-loop suppression. Do not wire those pieces manually in application code. This method remains documented for platform adapter authors and non-Vue integrations.

---



#### `host.confirm(options)` → `Promise<boolean>`


Shows a PrimeVue confirmation dialog. Resolves `true` if the user accepts, `false` if they reject or dismiss.

```typescript
host.confirm(options: LimitedConfirmationOptions): Promise<boolean>
```

```typescript
const confirmed = await host.confirm({
  message: 'Delete this item permanently?',
  header: 'Confirm Delete',
  icon: 'tabler:trash',
  acceptLabel: 'Delete',
  rejectLabel: 'Cancel',
  acceptClass: 'p-button-danger',
})

if (confirmed) {
  await api.delete('/api/v1/items/123')
}
```

---



#### `host.toast(options)`


Shows a PrimeVue toast notification.

```typescript
host.toast(options: ToastMessageOptions): void
```

| `severity` | Appearance |
|------------|-----------|
| `success` | Green |
| `info` | Blue |
| `warn` | Yellow |
| `error` | Red |

```typescript
host.toast({
  severity: 'success',
  summary: 'Saved',
  detail: 'Your changes have been saved.',
  life: 3000,
})
```

---



#### `host.openArtifact(artifactUUID, options?)`


Opens an artifact in the sidebar or a modal.

```typescript
host.openArtifact(
  artifactUUID: string,
  options?: { target?: 'sidebar' | 'modal' }
): void
```

The default target is `'sidebar'`.

```typescript
host.openArtifact('artifact-uuid-123', { target: 'modal' })
```

---



#### `host.setContext(context, sessionUUID?, source?)`


Sends context data to the current chat session. If no session is open yet, the context is queued and applied to the next session opened via `startChat` or `openSession`. Optionally scope the context to a specific session UUID or mark it with a source descriptor.

```typescript
host.setContext(
  context: Record<string, unknown>,
  sessionUUID?: string,
  source?: { type: 'page' | 'artifact', uuid: string, instanceUUID?: string }
): void
```

```typescript
host.setContext({
  currentPage: 'dashboard',
  selectedItemIds: [1, 2, 3],
})
```

---



#### `host.classifyLink(url)` → `LinkClassification`


Classifies an href as host-nav, child-nav, external, or ignore. Uses `mountRoutes` and `routePrefix` from the child config plus baked-in system route segments. Pure function — no side effects.

```typescript
host.classifyLink(href: string): LinkClassification

interface LinkClassification {
  kind: 'host-nav' | 'child-nav' | 'external' | 'ignore'
  href: string
  normalizedPath?: string
  targetPageId?: string  // set when host-nav matched a specific mountRoute
}
```

```typescript
// Classifier-aware anchor handler
import { host } from '@wippy-fe/proxy'

document.addEventListener('click', (ev) => {
  const a = (ev.target as HTMLElement)?.closest('a')
  if (!a) return
  const cls = host.classifyLink(a.getAttribute('href') ?? '')

  if (cls.kind === 'host-nav') {
    ev.preventDefault()
    host.navigate(cls.normalizedPath ?? cls.href)
  }
  // child-nav / external / ignore: let existing handlers run
})
```

For Vue apps, replace `RouterLink` from `vue-router` with `RouterLink` from `@wippy-fe/router` — it uses `classifyLink` internally and is prop-compatible with the real `RouterLink`.

---



#### `host.handleError(code, error)`


Reports an error to the host for centralized handling.

```typescript
host.handleError(
  code: 'auth-expired' | 'other',
  error: Record<string, unknown>
): void
```

- `'auth-expired'` — triggers the host re-authentication flow
- `'other'` — general error; logged and shown to the user if appropriate

```typescript
try {
  await api.get('/protected-endpoint')
} catch (error) {
  // Same-origin 401 responses already trigger the proxy's single-flight
  // auth-expired flow. Report only application-specific non-auth failures.
  if ((error as any).response?.status !== 401) {
    host.handleError('other', error as Record<string, unknown>)
  }
}
```

The proxy adds the Wippy bearer token to same-origin requests and invokes the
host's `auth-expired` flow once when such a request returns 401. Set
`skipDefaultAuth: true` only for a request that intentionally bypasses both
behaviors. Fully qualified cross-origin requests skip them automatically so the
Wippy token is not sent to another origin.

---



#### `host.logout()`


Signs the current user out and ends their session.

```typescript
host.logout(): void
```

---



#### `host.bridge`


Channel-based parent-child messaging when the page is embedded inside a `<w-iframe>`. See [Proxy & Isolation § Parent-child bridge](../web-host/proxy-isolation.md#parent-child-bridge) for the full protocol.

```typescript
// Fire-and-forget to parent
host.bridge.post(channel: string, payload?: unknown): void

// Request/response (resolves with parent handler's return value)
host.bridge.request<T>(
  channel: string,
  payload?: unknown,
  options?: { timeoutMs?: number }
): Promise<T>

// Register a handler for incoming messages from parent
host.bridge.on(
  channel: string,
  handler: (payload: unknown) => unknown | Promise<unknown>
): () => void  // returns unsubscribe
```

If you omit `options.timeoutMs`, `host.bridge.request()` defaults to a 10-second (`10000` ms) deadline. On timeout the returned promise rejects with an `Error` whose message is `` Bridge request <id> timed out after <ms>ms ``. A request to a channel the parent has no handler for rejects immediately with `` No handler registered for channel "<channel>" `` rather than waiting out the deadline.

---



#### `host.layout`


Access to the managed-layout API. Only available when `hostConfig.layout` is set (i.e., `fe_mode = managed`). Outside that context, `host.layout.snapshot` is `null` and mutation calls are no-ops.

```typescript
const layout = host.layout

// Read current snapshot
if (layout.snapshot) {
  console.log(layout.snapshot.activeBreakpoint)  // 'default' | 'sm' | ...
  console.log(layout.snapshot.panels)             // panel definition map
  console.log(layout.snapshot.layouts)            // breakpoint-keyed panel trees
}

// Subscribe to changes (the fresh snapshot is passed to the handler)
import { on } from '@wippy-fe/proxy'

const stopLayoutChanges = on('@layout-change', (snapshot) => {
  console.log(snapshot.activeBreakpoint)
})

// Call stopLayoutChanges() when the owning page or component tears down.

// Mutations
layout.resizePanel('right', '40%')
layout.collapsePanel('nav')
layout.expandPanel('nav')
layout.movePanel('right', { relativeTo: 'main', position: 'after' })
layout.removePanel('right')
layout.updatePanel('right', { kind: 'page', id: 'chat-panel' })  // {kind,id} replaces content wholesale
layout.updatePanel('right', { props: { artifactId: 'abc-123' } })  // {props} shallow-merges into existing props

layout.addFloating('flap', {
  kind: 'component',
  tagName: 'w-right-flap',
  position: { x: 0, y: 200 },
  size: { width: 48, height: 80 },
  dismissable: false,
})
layout.removeFloating('flap')
layout.closeModal('confirm-discard')

// In-tab bus
layout.broadcast('open-chat', { token: 'abc' })       // 1:N (sender excluded)
layout.send('right', 'open-chat', { token: 'abc' })   // 1:1 to named panel

const off = layout.on('open-chat', ({ payload, sourcePanelId, targetPanelId }) => {
  // handle
})
off()  // unsubscribe
```

For the full managed-layout model, see [Multi-Panel Layout](../web-host/multi-panel-layout.md).

---



#### `api`


A pre-configured axios instance with:
- Base URL from the deployment environment
- Automatic `Authorization: Bearer <token>` injection for same-origin requests
  unless `skipDefaultAuth: true`; cross-origin requests do not receive the
  Wippy token

```typescript
import { api } from '@wippy-fe/proxy'

const response = await api.get('/api/v1/users')
const result   = await api.post('/api/v1/items', { name: 'New item' })
```



#### File upload


```typescript
import { api, on } from '@wippy-fe/proxy'

const formData = new FormData()
formData.append('file', file)

const abort = new AbortController()

const response = await api.post('/api/v1/uploads', formData, {
  signal: abort.signal,
  headers: { 'Content-Type': 'multipart/form-data' },
  onUploadProgress: (evt) => {
    if (!evt.total) return
    const pct = Math.round((evt.loaded * 100) / evt.total)
    uploadProgress.value = pct
  },
})

const uploadedUuid = response.data.uuid  // { success: boolean, uuid: string }

// Track processing status via WebSocket. Retain and call the unsubscribe on
// completion, failure, cancellation, or component teardown.
const stopUploadStatus = on(`upload:${uploadedUuid}`, (msg) => {
  // msg.data.status: 'uploaded' | 'completed' | 'error' | 'processing'
})

```

Call `abort.abort()` from the application's cancel action while the POST is
still pending. An abort after the awaited response has settled cannot cancel
the completed upload. Call `stopUploadStatus()` when processing reaches a
terminal status or when the owning component tears down.

The Host's built-in upload UI rejects files larger than 100 MB. The proxy
axios instance does not enforce that limit; a custom endpoint or child UI must
apply its own documented client and server limits.



#### File download


```typescript
const response = await api.get(`/api/v1/uploads/${uuid}/download`, {
  responseType: 'blob',
})

const url = URL.createObjectURL(response.data)
const a = document.createElement('a')
a.href = url
a.download = 'filename.pdf'
a.click()
URL.revokeObjectURL(url)
```



#### Retrieve upload info


```typescript
// Paginated list
const list = await api.get('/api/v1/uploads/list', {
  params: { limit: 10, offset: 0 },
})
// list.data.uploads: Array<{ uuid, mime_type, size, status, meta: { filename } }>

// Single upload
const upload = await api.get(`/api/v1/uploads/${uuid}`)
// upload.data: { uuid, mime_type, size, status, meta: { filename, content_sample? } }
```



#### SSE streaming


The proxy `api` supports server-sent event streams via the fetch adapter. Use this for token-by-token LLM completions, long-running progress streams, or any `text/event-stream` response.

> Do not use the browser's native `EventSource` — it cannot attach custom headers and therefore cannot carry the proxy's `Authorization: Bearer` token.

```typescript
import { api } from '@wippy-fe/proxy'

const abort = new AbortController()

const response = await api.post('/api/v1/agents/stream', { prompt: 'Hello' }, {
  adapter: 'fetch',          // required — the default xhr adapter buffers the full body
  responseType: 'stream',
  headers: { Accept: 'text/event-stream' },
  signal: abort.signal,
})

const reader = (response.data as ReadableStream<Uint8Array>).getReader()
const decoder = new TextDecoder()
let buffer = ''
let endedByMarker = false

try {
  stream: while (true) {
    const { done, value } = await reader.read()
    if (done) break

    buffer += decoder.decode(value, { stream: true })
    // SSE permits CRLF. Normalize before looking for blank-line delimiters.
    buffer = buffer.replace(/\r\n/g, '\n')

    while (true) {
      const sep = buffer.indexOf('\n\n')
      if (sep === -1) break
      const rawEvent = buffer.slice(0, sep)
      buffer = buffer.slice(sep + 2)

      const dataLines = rawEvent
        .split('\n')
        .filter(line => line.startsWith('data:'))
        .map(line => line.slice(5).trimStart())

      if (dataLines.length === 0) continue
      const payload = dataLines.join('\n')
      if (payload === '[DONE]') {
        endedByMarker = true
        break stream
      }

      let evt: unknown
      try {
        evt = JSON.parse(payload)
      } catch {
        handleText(payload)
        continue
      }
      handleEvent(evt)
    }
  }
} finally {
  try {
    if (endedByMarker) await reader.cancel()
  } finally {
    reader.releaseLock()
  }
}
```

Call `abort.abort()` from the owning cancel or teardown path while the read
loop is active. The resulting abort rejection should be treated as expected
only when that path initiated it; report other stream failures normally.

To default all requests to the fetch adapter:

```jsonc
// In package.json → wippy.configOverrides, or window.__WIPPY_CONFIG_OVERRIDES__
{
  "axiosDefaults": { "adapter": "fetch" }
}
```

---



### Surface


Geometry of the area the Web Host allocated to this app. That area is usually **not** the browser window — the app may be one panel of several — so `window.innerWidth` and viewport units are the wrong things to size against. See [Surface Portability](./surface-portability.md) for the full contract and [Surface Migration](./surface-migration.md) for conversion recipes.



#### `host.surface.snapshot`


Current geometry, read back out of the same computed custom properties the app's CSS resolves — so it cannot drift from what `@container wippy-surface (…)` and `cqw` see.

```typescript
const { contract, revision, engine, sizing, width, widthUnit, height, heightUnit } = host.surface.snapshot
```

| Field | Type | Notes |
|-------|------|-------|
| `contract` | `1` | contract version |
| `revision` | `number` | monotonic; advances when the geometry changes |
| `engine` | `'iframe' \| 'fragment' \| 'host'` | `host` means no surface was allocated |
| `sizing` | `'container' \| 'content'` | |
| `width` / `widthUnit` | `number` | full width, and 1% of it, in CSS pixels |
| `height` / `heightUnit` | `number \| null` | `null` in content sizing — the block axis is genuinely unavailable |



#### `host.surface.onChange(listener)` → `() => void`


Subscribe to geometry changes. Returns an idempotent unsubscribe that **must** be called on teardown.

```typescript
const off = host.surface.onChange((snapshot) => {
  canvas.width = snapshot.width
})
```



#### `host.surface.supports(capability)` → `boolean`


```typescript
if (host.surface.supports('block-size')) {
  // the block axis is available (container sizing)
}
```

Capabilities: `block-size` and `surface-scroll` are answered truthfully today. `registered-hit-testing`, `native-document-hit-testing` and `owner-visibility` are reserved vocabulary and always report `false`.

Prefer `supports()` over branching on `engine` — what matters is whether a capability is available, not which engine is rendering.



#### `host.surface.engine` and `host.surface.sizing`


Read-only shortcuts for the same values on the snapshot. `engine: 'host'` means the code is mounted directly into the host document (or running under the standalone dev proxy) with no allocated surface; the snapshot reports `width: 0` and `sizing: 'content'` by design.

`engine` is not a reliable test for "was a surface allocated". A page embedded via `<w-iframe>`/`<w-artifact>` also receives no surface — nested embeds opt out until nested-surface support ships — yet reports `engine: 'iframe'` with `width: 0`. Check `snapshot.width` when that distinction matters.

---



#### `on(topic, handler)` → `() => void`


`on` subscribes to events from the host's WebSocket layer or internal proxy events. Returns an unsubscribe function.

```typescript
on(topic: string, handler: (event: unknown) => void): () => void
```

Topics use colon-separated segments. `*` is a single-segment wildcard. The pattern must have the same number of segments as the topic it matches.

```typescript
import { on } from '@wippy-fe/proxy'

// Unsubscribe when done
const unsub = on('session:abc:message:*', (msg) => {
  console.log(msg.data)
})
unsub()
```

Every `on()` call returns an unsubscribe function. Always call it when the component unmounts to prevent leaks. On iframe unload, remaining subscriptions are auto-cleaned, but explicit cleanup is still required for components that mount and unmount within a long-lived iframe.

```typescript
// Vue Composition API
import { onUnmounted } from 'vue'

const unsub1 = on('session:*:message:*', handler)
const unsub2 = on('artifact:*', handler)

onUnmounted(() => {
  unsub1()
  unsub2()
})
```

```typescript
// Vanilla / Web Component
import { on } from '@wippy-fe/proxy'

class MyEl extends HTMLElement {
  private unsubs: Array<() => void> = []

  connectedCallback() {
    this.unsubs.push(on('session:*:message:*', handler))
  }

  disconnectedCallback() {
    this.unsubs.forEach(fn => fn())
    this.unsubs = []
  }
}
```



#### Built-in topics


| Topic | Handler payload | Description |
|-------|-----------------|-------------|
| `@history` | `{ path: string }` | Host URL changed (SPA navigation). Fires when the parent pushes a new route. |
| `@visibility` | `boolean` | Iframe/Web Fragment visibility changed. Direct web components use the typed host-visibility contract instead. |
| `@theme` | `'auto' \| 'light' \| 'dark'` | Applied theme mode propagated by the Host. |
| `@message` | Full WS message | All WebSocket messages. Internally subscribes to `*`, `*:*`, `*:*:*`, `*:*:*:*`. |
| `@state-error` | `{ error: string, key?: string }` | State save operation failed (quota exceeded, serialization error). |
| `@layout-change` | `LayoutSnapshot` | Managed-layout snapshot updated; the fresh snapshot is passed to the handler. Equivalent to reading `host.layout.snapshot`. |
| `@layout-breakpoint` | `{ name: string, width: number }` | Active managed-layout breakpoint changed; `name` is the new breakpoint, `width` its threshold (px). |



#### Wildcard patterns


```typescript
// Iframe/Web Fragment pages only; direct WCs use useHostVisibility().
on('@visibility', (visible: boolean) => { /* shown or hidden */ })

// All session messages in a specific session
on('session:abc-123:message:*', (msg) => { /* ... */ })

// All messages across all sessions
on('@message', (msg) => { /* ... */ })

// Topics whose parts contain ':' must be encoded
on(`session:${encodeURIComponent('id:with:colons')}:message:*`, handler)
```

`@history` is listed for protocol completeness. Portable Vue applications must let `@wippy-fe/router` subscribe to it; do not add a second application-owned handler.

Subscribing to the same topic multiple times from the same frame is safe. The proxy deduplicates at the host level. Each `on()` call still gets its own independent unsubscribe handle.

---



#### `state` — host-mediated key-value persistence


`state` provides host-mediated storage that survives page-realm destruction. State is scoped per page or artifact UUID; each app gets an isolated namespace.

All methods accept an optional `{ scope?: string }` option to override the default scope. Use `scope` when multiple instances of the same component need separate state buckets.

> **Scope uniqueness:** scope values are passed as-is by the raw `state` API and must be globally unique across your application. The `@wippy-fe/pinia-persist` plugin automatically prefixes custom scopes with `@custom:` to prevent collisions with system scopes.

```typescript
import { state } from '@wippy-fe/proxy'

// Write (fire-and-forget; @state-error fires on quota exceeded)
await state.set('filters', { search: 'john', status: 'active' })

// Read (returns null if key not found)
const filters = await state.get<{ search: string, status: string }>('filters')

// Delete a key
await state.remove('filters')

// Clear all state for this page
await state.clear()

// Read all at once (useful for bulk hydration)
const all = await state.getAll()

// Custom scope
await state.set('count', 42, { scope: 'my-widget-instance-1' })
const count = await state.get<number>('count', { scope: 'my-widget-instance-1' })
```

**Method signatures:**

```typescript
state.get<T = unknown>(key: string, options?: { scope?: string }): Promise<T | null>
state.set(key: string, value: unknown, options?: { scope?: string }): Promise<void>
state.remove(key: string, options?: { scope?: string }): Promise<void>
state.clear(options?: { scope?: string }): Promise<void>
state.getAll(options?: { scope?: string }): Promise<Record<string, unknown>>
```

**Recommended iframe/Web Fragment save pattern** — save when the page goes to background rather than on every change. Direct WCs use `useHostVisibility()` for the same lifecycle decision:

```typescript
const stopVisibility = on('@visibility', async (visible) => {
  if (!visible) {
    await state.set('scrollY', document.documentElement.scrollTop)
    await state.set('formData', currentFormData)
  }
})

// Call stopVisibility() when the owning page or component tears down.
```

**Limits:** 2 MB per page (JSON-serialized, configurable by the host through `hostConfig.stateCache`). State lives in host memory — survives iframe reload but not a full browser page refresh.



#### Pinia integration


For Vue apps using Pinia, `@wippy-fe/pinia-persist` automates persistence:

```typescript
import { createWippyPersist, preloadWippyState } from '@wippy-fe/pinia-persist'

const preloaded = await preloadWippyState()
const pinia = createPinia()
pinia.use(createWippyPersist(preloaded))
app.use(pinia)
```

Then mark stores:

```typescript
const useMyStore = defineStore('my-store', () => {
  const filters = ref({ search: '' })
  return { filters }
}, {
  wippyPersist: true,
  // or: wippyPersist: { pick: ['filters'], debounce: 500 }
})
```

---



#### `ws`


`ws` sends commands through the host's WebSocket connection. Responses arrive via `on()` topic subscriptions.



#### `ws.send(command)`


Fire-and-forget. No response delivery — subscribe to the relevant topic first.

```typescript
ws.send(command: WsCommand): void
```

```typescript
import { ws, on } from '@wippy-fe/proxy'

const stopMessages = on('session:my-session:message:*', (msg) => {
  console.log('Response:', msg.data)
})

ws.send({
  type: 'session_message',
  session_id: 'my-session',
  message_id: crypto.randomUUID(),
  data: { text: 'Hello from child app' },
})
```

Keep `stopMessages` and call it when the owning component or page tears down;
do not unsubscribe immediately after `send()` if the response is still needed.



#### `ws.sendWithResponse(command)` → `Promise<WsMessage>`


Sends a command and waits for the matching server response. Times out after 30 seconds.

```typescript
ws.sendWithResponse(command: WsCommand): Promise<WsMessage>
```

```typescript
const response = await ws.sendWithResponse({
  type: 'session_open',
  start_token: 'my-token',
})
console.log('Session opened:', response.data)
```



#### `ws.sendCommand(sessionId, data)`


Convenience wrapper for session control commands.

```typescript
ws.sendCommand(sessionId: string, data: { command: string, [key: string]: unknown }): void
```

```typescript
ws.sendCommand('session-uuid', { command: 'stop' })
ws.sendCommand('session-uuid', { command: 'model', name: 'gpt-4' })
ws.sendCommand('session-uuid', { command: 'agent', name: 'my-agent' })
```

---



#### `logger`


Structured logging that traverses child-to-host boundaries. Logs flow child → host → parent website where transports (Sentry, Graylog, console) process them. Each child's context (`resourceId`, `resourceType`, nesting depth) is automatically attached to every log entry.

Use `logger` instead of `console.log/error` for anything you want to appear in production monitoring.

```typescript
import { logger } from '@wippy-fe/proxy'

logger.debug('Component mounted', { pageId: 'abc' })
logger.info('User loaded page', { pageId: 'abc' })
logger.warn('Slow API response', { ms: 3200 })
logger.error('Failed to save', { endpoint: '/api/save' })
```



#### `logger.captureException(error, context?)`


Captures and forwards an exception. Unhandled errors (`window.onerror`, `unhandledrejection`) are automatically captured when `ProxyConfig.injections.errorCapture` is `true`.

```typescript
try {
  await riskyOperation()
} catch (error) {
  logger.captureException(error, { operation: 'riskyOperation' })
}
```



#### Breadcrumbs and context


```typescript
// Breadcrumbs attach to the next exception for debugging context
logger.addBreadcrumb({ category: 'navigation', message: 'Navigated to /settings' })
logger.addBreadcrumb({ category: 'ui', message: 'Clicked Save button' })

// Persistent context — attached to all subsequent logs from this child
logger.setContext('user', { id: 'user-123', role: 'admin' })

// Tags — key/value pairs for filtering and search
logger.setTag('version', '1.2.0')
logger.setTag('feature', 'dashboard')
```

---



#### `loadByTagName(tagName, options?)` → `Promise<void>`


Loads and registers a peer web component by its HTML tag name. Resolves after `customElements.define` fires — it is safe to `document.createElement(tagName)` immediately after. The tag is added to the `sanitize` allowlist automatically on success.

```typescript
import { loadByTagName } from '@wippy-fe/proxy'

await loadByTagName('wc-thread-picker')
await loadByTagName('wc-slow-pkg', { timeoutMs: 60_000 })

// Safe to use immediately
document.body.appendChild(document.createElement('wc-thread-picker'))
```

`options.timeoutMs` overrides the default 30-second deadline for waiting on `customElements.define` after the script is appended. Surfaces stuck or broken components (404, parse error, missing `define` call) as a rejection rather than an indefinite hang.



#### `loadWebComponent(componentId, tagName?)` → `Promise<void>`


Loads a web component by its Wippy registry artifact id rather than its tag name. Useful when you have a registry id from a config value or backend response.

```typescript
import { loadWebComponent } from '@wippy-fe/proxy'

await loadWebComponent('wippy.components:my-chart')
```



#### DOM-scan loader (`<script type="wippy-components-loader">`)


For pages that need multiple components, the proxy scans for these script tags on init and loads each entry through `loadWebComponent`:

```html
<script type="wippy-components-loader">
{ "wc-foo": "wippy.components:foo", "wc-bar": "wippy.components:bar" }
</script>
```

Same deduplication and allowlist auto-update behavior as `loadByTagName`.

---



#### `sanitize(html, options?)` → `string`


Default-allowlisted HTML sanitizer scoped to the current proxy context. Combines the chat-rendering defaults (`<p>`, `<a>`, `<code>`, `<table>`, etc.) with every web component tag currently registered in this runtime.

```typescript
import { sanitize, loadByTagName } from '@wippy-fe/proxy'

const safe = sanitize('<p>hi</p><script>alert(1)</script>')
// → '<p>hi</p>'

// After loadByTagName, the tag is automatically allowed:
await loadByTagName('wc-thread-picker')
sanitize('<wc-thread-picker thread-id="42"></wc-thread-picker>')
// → '<wc-thread-picker thread-id="42"></wc-thread-picker>'

// One-off extra tags
sanitize(dialogBody, { extraTags: { 'iconify-icon': ['icon'] } })
```

`sanitize` re-reads the tag allowlist on every call, so tags registered after import are still picked up.



#### `html.inject(sourceHtml, options)` → `Promise<string>`


Applies the source-HTML-to-srcdoc transform without mounting an element. Prefer `<w-iframe>` for normal use; use this only when building custom hosting infrastructure.

```typescript
import { html } from '@wippy-fe/proxy'

const processed = await html.inject(sourceHtml, {
  baseUrl: 'https://example.com/app/',
  resourceId: 'child-id',
  resourceType: 'page',
  route: '/initial',
})
```

---



### Config Overrides


Pages can override selected child-facing config fields per page without a separate deployment. The override shape still uses `customization` for compatibility, and the host projects those values into the current child `theming.global` result before the page receives `wippy-context-2.0` config.



#### Setting overrides


**Registry pages (recommended):** Set `meta.config_overrides` in the page's `_index.yaml`. The host includes it in the content API response and injects it automatically.

**Standalone packages:** Set `wippy.configOverrides` in the page's `package.json`.

**Manual / testing:** Set `window.__WIPPY_CONFIG_OVERRIDES__` in a `<script>` tag that runs before `proxy.js`.

```typescript
window.__WIPPY_CONFIG_OVERRIDES__ = {
  customization: {
    cssVariables: {
      '--p-primary': '#ff6b00',
    },
    customCSS: '.my-page-header { border-radius: 12px; }',
  },
}
```



#### Merge rules


| Field | Merge behavior |
|-------|---------------|
| `cssVariables` | **Replaces** the host's values — the page provides its own theme |
| `customCSS` | **Replaces** the host's value |
| `iconSets` | **Merged** additively |
| `axiosDefaults` | **Deep merged** |
| `routePrefix` | **Replaced** |
| `apiRoutes` | **Deep merged** |

Every nested child the page embeds — `<w-iframe>`, `<w-artifact>`, and `html.inject` content — is built from the page's already-merged config and inherits it automatically, recursively down the sub-tree. So a page's overrides (especially theming) propagate to everything beneath it, not just to the page itself.

---



#### `installVueWarnSuppressor(app)`


Available in the current coherent `@wippy-fe/proxy` family. Silences `[Vue warn]: Failed to resolve component: foo-bar` for tags registered via `customElements.define(...)` rather than `app.component(...)`. Vue's template compiler emits these warnings for web component tags it does not recognize; the elements render correctly, but the console receives non-actionable warnings.

```typescript
import { installVueWarnSuppressor } from '@wippy-fe/proxy'
import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App)
installVueWarnSuppressor(app)
app.use(router)
app.mount('#app')
```

What it suppresses:

- Tags already registered via `customElements.define(...)` — system tags (`w-iframe`, `w-artifact`, `wippy-loading`, `wippy-error`) and every tag registered by the autoload pipeline (`loadByTagName`, scanner).
- Tags matching the custom element naming shape (`^[a-z][a-z0-9]*-[a-z0-9-]*$`) that are not yet registered — covers the race window where Vue renders before the autoload script lands.

What still warns:

- **PascalCase component typos** (`<UsreCard />`). The suppressor does not match these against the kebab pattern and `customElements.get` returns `undefined`, so they pass through to the console — preserving the signal that distinguishes real bugs from noise.

The function is idempotent: a second call on the same `app` is a true no-op. A `Symbol.for('@wippy-fe/proxy/vue-warn-suppressor-installed')` marker is planted on `app.config`; the marker is exported as `VUE_WARN_SUPPRESSOR_INSTALLED_MARKER` for test setups that need to clear it across reloads.

If a `warnHandler` was already installed, it is preserved as `previous` and called for warnings the suppressor does not silence.



#### `createAppRouter(routes, options?)` from `@wippy-fe/router`


Memory-router factory for `view.page` applications in either render engine. It provides memory history, `afterEach` route synchronization with the host, and an `@history` subscription:

```typescript
import { createAppRouter } from '@wippy-fe/router'
import { config } from '@wippy-fe/proxy'
import { routes } from './routes'

const router = createAppRouter(routes, {
  initialPath: config.context?.route,
})
app.use(router)
```

---



### Loading and Error Components


Two web components are auto-registered via `loading.js` (injected before `proxy.js`). No imports or manual registration needed.



#### `<wippy-loading>`


Fullscreen loading spinner with theme-aware colors.

| Attribute | Description |
|-----------|-------------|
| `title` | Main text (e.g., "Loading...") |
| `subtitle` | Secondary text |
| `no-bg` | Boolean — transparent background for overlay use |

```html
<wippy-loading title="Loading..." subtitle="Please wait"></wippy-loading>
<wippy-loading no-bg title="Loading page content..."></wippy-loading>
```



#### `<wippy-error>`


Fullscreen error display with severity-based coloring.

| Attribute | Values | Default |
|-----------|--------|---------|
| `title` | Any string | "Something went wrong" |
| `message` | Any string | (empty) |
| `icon` | `circle`, `triangle`, `sad` | `circle` |
| `severity` | `danger`, `warning` | `danger` |
| `no-bg` | Boolean | (absent) |

```html
<wippy-error title="Failed to load" message="Server returned 500" severity="danger"></wippy-error>
<wippy-error title="Connection Lost" message="Retrying..." icon="triangle" severity="warning"></wippy-error>
```

Both components use Shadow DOM with CSS variables from `@wippy-fe/theme` and include hardcoded fallbacks for pre-theme contexts.

**Recommended pattern for vanilla HTML pages:**

```html
<body>
  <wippy-loading id="loader" title="Loading..."></wippy-loading>
  <div id="content" style="display:none"><!-- content --></div>

  <script type="module">
    import { api, host } from '@wippy-fe/proxy'

    async function init() {
      try {
        // fetch data, set up page...
        document.getElementById('loader').remove()
        document.getElementById('content').style.display = 'block'
      } catch (error) {
        const errorEl = document.createElement('wippy-error')
        errorEl.setAttribute('title', 'Initialization failed')
        errorEl.setAttribute('message', error.message)
        document.getElementById('loader').replaceWith(errorEl)
      }
    }
    init()
  </script>
</body>
```

**Vue 3 — `app.html` entry:**
```html
<div id="app">
  <wippy-loading title="Loading..."></wippy-loading>
</div>
<script type="module" src="./src/app.ts"></script>
```

When Vue mounts into `#app` it replaces the `<wippy-loading>` element automatically.



---

# "Surface Portability"

## Surface Portability


**Classification: rendering contract reference with focused examples.** The
CSS, JavaScript, and package metadata blocks illustrate individual contract
rules; they are not a complete application fixture.

A micro frontend app receives a **surface**: the rectangular area the Web Host allocates to it. That area is usually **not** the browser window. The app may be one panel among several in a [multi-panel layout](../web-host/multi-panel-layout.md), and the same app may be rendered by either [render engine](../web-host/render-engines.md) at different sizes on the same screen.

Sizing a layout to the window is therefore wrong in both engines. The surface contract gives you a portable alternative in CSS and in JavaScript.

> **Status:** contract 1, shipped. Tailwind `surface-*` variants, host-mediated scrolling, and deep hit testing are **not yet shipped**; this page documents only what exists today.



#### Container queries


The host names the app's box `wippy-surface`, so it can be queried like any CSS container:

```css
@container wippy-surface (min-width: 640px) {
  .sidebar { display: block; }
}
```

Use this instead of `@media (min-width: 640px)` for anything that responds to the space the app occupies. Native container units resolve against the same box:

```css
.hero { inline-size: 50cqw; }
```



#### Surface variables


Four custom properties carry the geometry as plain pixel lengths:

| Property | Meaning |
|----------|---------|
| `--wippy-surface-width` | full surface width |
| `--wippy-surface-width-unit` | 1% of the surface width |
| `--wippy-surface-height` | full surface height (container sizing only) |
| `--wippy-surface-height-unit` | 1% of the surface height (container sizing only) |

They are the portable replacement for `vw` / `vh`:

```css
/* was: inline-size: 50vw */
.panel { inline-size: calc(var(--wippy-surface-width-unit) * 50); }
```

The values inherit, so any element in the app can read them. They report the query box's **content box**, which is the same box `100cqw` resolves against.

Applications must **not** declare or assign these four names. A descendant declaration shadows the inherited value and silently unpins the app from the surface.

They must also stay **unregistered**. Do not describe them with `@property` or `CSS.registerProperty()`. The host marks the block axis unavailable by assigning a guaranteed-invalid value, which computes to the empty string only while the property is unregistered. Give one an `initial-value` and it computes to that instead, so a content-sized app reports itself as container-sized and `supports('block-size')` starts returning `true` — with no error anywhere.

Two caveats before comparing these values to `100cqw` pixel-for-pixel. The **first frame can be wider**: the boot value is seeded from the host-side `<iframe>` element before the app's document exists, so it cannot know whether the content will raise a scrollbar. That value is baked into the document's CSS, so the first layout uses it and is corrected one frame later. And values are **quantized to 1/64 px**, so compare with a tolerance.



### Container sizing and content sizing


| | Inline axis | Block axis |
|---|---|---|
| **Container sizing** — the host imposes both dimensions | available | available |
| **Content sizing** — the app's content decides the height | available | **not available** |

In content sizing the height properties are deliberately invalid, so `var(--wippy-surface-height, 400px)` falls back rather than reporting a number, and `@container wippy-surface (min-height: …)` never matches.

**Which one an app gets is not the author's choice**, and nothing in `package.json` changes it. Sizing is set by *where the Web Host renders the app*:

| Rendered as | Sizing |
|---|---|
| a routed page, a layout panel, the right panel, a registry tab | **container** |
| an embedded artifact, an inline artifact block, a navbar widget | **content** |

So the same package is container-sized on its own route and content-sized when someone embeds it. An app that needs the block axis must therefore tolerate not having it, or declare the requirement (below) so it is refused rather than rendered broken. Read the current mode with `host.surface.snapshot.sizing`, and gate behavior on `host.surface.supports('block-size')` — never assume.

`cqh` behaves worse than "unavailable": container units fall back to the **small viewport** when no container supplies the axis they need, so `cqh` silently produces a plausible number unrelated to the surface. Prefer `var(--wippy-surface-height, <fallback>)`, which is root-pinned and visibly falls back. The same trap appears inside an app that declares `container-type: inline-size` on an intermediate element and then uses `cqh` below it.



### Declaring requirements


Optional, in the app's `package.json`:

```json
{
  "wippy": {
    "path": "index.html",
    "surface": {
      "contract": 1,
      "requirements": ["block-size"]
    }
  }
}
```

Accepted tokens are `block-size` and `surface-scroll`, both of which require container sizing and are rejected when the instance is content-sized. `registered-hit-testing`, `native-document-hit-testing` and `owner-visibility` are reserved vocabulary and are rejected as unimplemented rather than silently ignored.

Validation runs before startup, so an unsatisfiable declaration fails visibly instead of rendering an app whose block-axis queries never match. An app without a `surface` block still renders and still receives the query box and variables; it simply advertises no portability.

`surface-scroll` is accepted and reported by `supports()`, but this release ships **no** host-mediated scroll API — declaring it asserts an intent, it does not unlock a method.



### Reading the surface from JavaScript


See [Proxy API → Surface](./proxy-api.md#surface) for the full signature.

```js
const { width, widthUnit, height, sizing } = host.surface.snapshot

if (host.surface.supports('block-size')) {
  // safe to rely on the block axis
}

const off = host.surface.onChange((s) => reposition(s.width, s.height))
// call off() on teardown
```

The snapshot is read back out of the same computed custom properties the CSS resolves, so it cannot drift from what `@container` and `cqw` see.

Prefer CSS for layout. Reach for the JavaScript API where CSS cannot go: canvas sizing, virtualization maths, resource selection, and styles generated at runtime.



#### `engine: 'host'`


`host.surface.engine` reports `iframe`, `fragment`, or `host`. The last is not a page engine — it means the code is running where no surface was allocated:

- a web component mounted directly into the host document rather than into a page;
- the standalone dev proxy, with no Web Host at all.

There, the snapshot reports `width: 0`, `height: null`, `sizing: 'content'`, and `supports()` is `false` for everything. That is deliberate: substituting the browser window would be the false equivalence the contract exists to avoid. A directly-mounted component should measure its own root instead.



### What the contract does not cover


Container queries replace media queries in **CSS**. These mechanisms live outside CSS and keep following the browser window:

| Mechanism | Why | What to do |
|---|---|---|
| `<picture>` / `<source media>` | HTML resource selection; no container-query form | Drive from `host.surface.onChange`, or move art direction to a CSS `background-image` under `@container` |
| `srcset` + `sizes` | resolve against the viewport | Derive `sizes` from the surface, or set the source from JS |
| `matchMedia()` | asks the window by definition | Use `host.surface.onChange` for geometry; keep `matchMedia` for preferences |



### Overlays


The surface contract does **not** capture `position: fixed`. `container-type` establishes an independent formatting context without layout containment, so a query container computes `contain: none` and anchors nothing. PrimeVue overlays and hand-rolled fixed overlays both keep working, unchanged.

Engine behavior is a separate matter: in the Web Fragment engine `position: fixed` resolves against the **host window** rather than the app's panel. See [Render Engines](../web-host/render-engines.md) and pin the app with `wippy.renderEngine: "iframe"` if exact viewport anchoring matters.

Sizing an overlay is a different question from anchoring it. For a backdrop or drawer that should cover exactly the surface, drop viewport units and use `inset: 0` — but pair it with the positioning scheme that matches how portable the app must be:

```css
/* Portable across BOTH engines: resolves against the app's own root rather
   than against whatever `fixed` happens to be relative to.
   `min-block-size: 100%` is load-bearing — see below. */
.app-root { position: relative; min-block-size: 100%; }
.backdrop { position: absolute; inset: 0; }
```

The containing block is the **app's root**, not the surface, so the overlay covers the surface only if that root does. In content sizing it does automatically (the content *is* the height). In container sizing the host imposes a height on the query box that the app's root does not inherit, so without `min-block-size: 100%` the backdrop stops short even though the `fixed` version would cover the surface. The two also differ in behavior: `absolute` scrolls with the content, while `fixed` stays pinned.

Put `min-block-size: 100%` on the **outermost** element inside the surface. A percentage height needs an unbroken chain of definite heights above it, so applying it to a component root nested inside an auto-height `#app` resolves to zero and reintroduces the same gap. Verified across Chromium, Firefox and WebKit, with the no-`min` case as a control.

```css
/* Iframe engine only. `fixed` resolves against the child viewport, which IS
   the surface there — but against the HOST WINDOW in the fragment engine,
   where this covers the whole application instead of the panel. */
.backdrop { position: fixed; inset: 0; }
```

Avoid `var(--wippy-surface-height)` for this: it is unavailable in content sizing, so a backdrop written that way collapses on content-sized pages.



### The app root element (`#app`)


**The Web Fragment engine requires your root element to be `id="app"`.** Not
`#root`, not `#main`, not `<main>` — the id is matched literally.

The engine binds the page height chain to that selector and measures your
content height through it. The reflected document exposes `wf-html`/`wf-body`
rather than `html`/`body`, so you cannot build the chain from the document root
the way you can inside an iframe.

**Symptom when it is wrong:** a content-sized fragment page whose root is
`#root` (or anything else) renders at **zero height** — blank panel, no error in
your own code. The host logs an error naming the requirement. The iframe engine
is unaffected, because it takes height from `CmdBodySize`, so the same package
may appear correct there and be blank as a fragment.

```html
<!-- correct -->
<body><div id="app"></div></body>
```

```js
createApp(App).mount('#app')
```

**Do not try to fix a zero-height fragment by giving `#root` a height.** Adding
`height: 100%`, `min-height: 100dvh` or `100vh` to a differently-named root does
not make the engine measure it. Viewport units describe the browser window, not
the allocated surface.
Rename the element to `app` instead.



### Limitations


- **Body box.** In the iframe engine the host zeroes `margin`, `padding` and `border` on the app's `body` so the allocated surface is well defined. Put page padding on your own root element. The fragment engine does not do this, so an app relying on body padding renders slightly differently between engines. There is no build-time diagnostic for this yet.
- **`body > *` selectors, and rules targeting `html`/`body`.** In the **iframe** engine the host wraps body content in the surface box, so direct-child selectors rooted at `body` no longer match app elements, and `body`/`html` become *ancestors* of the query box — a `@container` rule targeting them never applies. The **fragment** engine has the opposite topology (the query box sits above the reflected tree), but a literal `body` selector still fails there because the reflected document is renamed `wf-html`/`wf-body`. Put such rules on your own root element inside the surface; that is correct in both engines.
- **Anything rendered through `<w-iframe>` / `<w-artifact>` gets no surface — including a top-level managed panel.** These elements always build their child document with the surface bootstrap disabled and nothing measures them, so `host.surface` reports `width: 0` and `sizing: 'content'` — but with `engine: 'iframe'`, not `engine: 'host'`. Check `snapshot.width` rather than `engine` if your component can be embedded that way. That is expected for a *nested* embed; it is easy to miss for a managed layout panel declared as `{ kind: 'component', tagName: 'w-artifact' }`, which is a full-size top-level slot yet still gets no contract. Use `kind: 'page'` for content that needs one.
- **No block axis in content sizing.**
- **Fragment root selector.** Fragment apps must mount at `#app`; see [The app root element (`#app`)](#the-app-root-element-app) for the height-chain requirement and zero-height symptom.
- **The deprecated `/page/:id` route gets no surface.** It renders into a bare iframe that never measures anything, so it opts out completely — no query box, no wrapper, no change to the app's DOM. An app behaves there exactly as it did before this contract existed. Use `/c/:id` to get a surface. Like nested embeds, it still reports `engine: 'iframe'`, so test `snapshot.width` rather than the engine name.
- **The two engines can differ by a scrollbar.** The iframe engine measures the inline axis from the query box *inside* the app's document, so a document scrollbar narrows it. The fragment engine measures a host-document wrapper, which the reflected content's scrolling does not narrow. Same allocated panel and scrolling content: the fragment engine reports the slightly wider number.
- **Not an isolation boundary.** The contract governs layout. It does not give a fragment an independent document, viewport, selection, top layer, or origin.



### Migration


[Surface Migration](./surface-migration.md) has recipe-by-recipe conversions for existing apps, each labelled automatic, conditional, manual, or not convertible.



---

# "Surface Migration"

## Surface Migration


**Classification: partial migration recipe collection.** Each before/after
block converts one isolated pattern. Apply the decision tree to the complete
stylesheet, then verify the page in both render engines and both sizing modes.

Recipes for converting an existing micro frontend app from viewport-based
responsiveness to the [surface contract](./surface-portability.md).

Every recipe is labelled:

| Label | Meaning |
| --- | --- |
| **automatic** | Mechanical. The converted rule means the same thing. |
| **conditional** | Safe only when a stated precondition holds. Check it. |
| **manual** | Needs a human decision; there is no single correct rewrite. |
| **not convertible** | No container-query form exists. Use `host.surface` or keep the viewport behavior deliberately. |

Each recipe below presents one technique in isolation. The Web Host repository
includes a runnable page that combines them and is covered by its test suite.

> Recipes that depend on unshipped work — Tailwind `surface-*` variants, build-time
> diagnostics, host-mediated scrolling, hit testing — are marked **not yet shipped**
> and describe only what exists today.

---



### Decision tree: what is this rule about?


Before converting anything, classify the intent. A mechanically correct
conversion is still wrong when the original rule was not surface-relative.

```text
Does the rule respond to how much room THIS PAGE has?
├── yes → convert to @container wippy-surface        (recipes 1-8)
├── no, it responds to one COMPONENT's width
│        → give that component its own container      (recipe 22)
├── no, it responds to a user/device PREFERENCE
│        → leave it as @media                         (recipe 13)
└── no, it deliberately tracks the BROWSER WINDOW
         (a true full-window overlay)
         → leave it, and document why
```

If you cannot tell, leave it and revisit. An unconverted media query is merely
non-portable; a wrongly-converted one is silently broken.

---



### 1. `max-width` → `inline-size <=` — **automatic**


```css
/* before */ @media (max-width: 640px)                      { .nav { display: none } }
/* after  */ @container wippy-surface (max-width: 640px)    { .nav { display: none } }
```



### 2. `min-width` → `inline-size >=` — **automatic**


```css
/* before */ @media (min-width: 640px)                      { .sidebar { display: block } }
/* after  */ @container wippy-surface (min-width: 640px)    { .sidebar { display: block } }
```



### 3. A bounded width range — **automatic**


```css
/* before */ @media (min-width: 640px) and (max-width: 1024px) { … }
/* after  */ @container wippy-surface (640px <= width <= 1024px) { … }
```

The range syntax is supported in all engines the surface contract targets. The
`and` form also works if you prefer it.



### 4. Multiple breakpoints, cascade order preserved — **automatic**


Container queries do not change specificity or ordering. Convert each block and
keep them in the same source order:

```css
@container wippy-surface (min-width: 480px)  { .grid { grid-template-columns: repeat(2, 1fr) } }
@container wippy-surface (min-width: 900px)  { .grid { grid-template-columns: repeat(4, 1fr) } }
```



### 5. Height queries — **conditional** (container sizing only)


```css
/* after */ @container wippy-surface (min-height: 500px) { .tall-only { display: block } }
```

Precondition: the page is **container-sized**. In content sizing the page's
height is its own content, so height queries never match. Declare the dependency
so it fails loudly rather than silently:

```json
{ "wippy": { "surface": { "contract": 1, "requirements": ["block-size"] } } }
```



### 6. Aspect-ratio queries — **conditional** (container sizing only)


```css
/* before */ @media (min-aspect-ratio: 16/9)                     { … }
/* after  */ @container wippy-surface (min-aspect-ratio: 16/9)   { … }
```

Same precondition as recipe 5: aspect ratio needs both axes.



### 7. Orientation queries — **conditional** (container sizing only)


`@container wippy-surface (orientation: landscape)` describes *your panel's*
shape, which is usually what you meant. If you genuinely meant the device,
that is a media query — keep it (recipe 13).



### 8. Height / aspect / orientation in content sizing — **not convertible**


There is no block axis to query. Restructure so the layout depends on the inline
axis. Do not fake it with `cqh` — see recipe 22.

You cannot switch the app to container sizing yourself: sizing is set by where
the Web Host renders the app, not by anything in its package. If the layout truly
cannot work without the block axis, declare `requirements: ["block-size"]` so a
content-sized placement is refused outright instead of rendering wrong, and get
the app rendered in a container-sized context (its own route or a layout panel).
See "Container sizing and content sizing" in
[Surface Portability](./surface-portability.md).



### 9. Geometry nested inside an environmental media query — **manual**


```css
/* before */
@media (prefers-color-scheme: dark) and (min-width: 640px) { .panel { … } }

/* after — split: the preference stays, the geometry moves */
@media (prefers-color-scheme: dark) {
  @container wippy-surface (min-width: 640px) { .panel { … } }
}
```

Manual because nesting order can change which declarations win when the two
conditions previously combined in one prelude. Re-check the result.



### 10. Comma-OR branches — **manual**


```css
/* before */ @media (max-width: 480px), (min-width: 1200px) { … }
```

A comma is OR. Splitting it into two `@container` blocks preserves OR **only if
the two blocks are otherwise identical and adjacent**; if you accidentally nest
them you have turned OR into AND, which matches nothing. Duplicate the
declarations into two sibling blocks:

```css
@container wippy-surface (max-width: 480px)  { … }
@container wippy-surface (min-width: 1200px) { … }
```



### 11. `not`, `only`, complex Boolean — **manual**


`only` is a media-type artifact and has no container equivalent — drop it.
`not` inverts the whole condition in both syntaxes, but precedence differs once
you mix `and`/`or`; parenthesise explicitly rather than trusting the original
grouping.



### 12. `screen` / `print` combined with geometry — **manual**


Media *types* have no container form. Keep the type as a media query and nest
the geometry inside it (as in recipe 9). Print layout in particular should
usually stay entirely viewport/page-based.



### 13. Preferences stay media queries — **not convertible** (and correct as-is)


`prefers-color-scheme`, `prefers-contrast`, `prefers-reduced-motion`,
`forced-colors`, `hover`, `pointer`, `any-pointer`. `@container` supports size
features only. Converting these produces a rule that never matches.



### 14. `em` breakpoints — **manual**


`@media (min-width: 40em)` resolves `em` against the initial font size.
`@container wippy-surface (min-width: 40em)` resolves it against the
**container's** font size. If those differ, your breakpoint moves silently.
Convert to `px`, or verify the container's computed `font-size` first.



### 15. `rem` breakpoints — **manual**


`rem` is **not** root-relative inside `@media`. Media-query conditions resolve
both `em` and `rem` against the *initial* font size — the browser default,
independent of any author CSS — while `@container` resolves them the ordinary
way, against the actual computed root/container font size.

So the two are already unequal the moment your root font size differs from the
browser default, with nothing changing at runtime. The common `html { font-size:
62.5% }` reset is enough to move a converted breakpoint from 640px to 400px.

"Nothing changes the root font size" is therefore **not** a sufficient
precondition. Convert to `px`, exactly as for `em` (recipe 14), unless the
root's computed font size provably equals the browser default.



### 16. Viewport vs content-box scrollbar boundary — **conditional**


`100vw` includes the classic scrollbar gutter. In the **iframe engine** the
surface width is the query box's **content box** inside the app's document, so
it does not: on a page with a document scrollbar the converted value is narrower
by the scrollbar width, which is usually the correction you wanted (`100vw`
causing horizontal overflow is a classic bug).

The **fragment engine** measures a host-document wrapper that the content's
scrolling does not narrow, so it does not apply that correction. Same panel,
same scrolling content, widths differing by a scrollbar. The condition on this
recipe is therefore *which engine the app runs in*, not merely whether the
alignment is pixel-exact.



### 17. Rules targeting `html` / `body` — **manual**


A container query never styles its own container, and a rule aimed at `html` or
`body` fails in both engines — for different reasons:

- **Iframe engine:** the host wraps your body content in the surface box, so
  `html` and `body` are *ancestors* of the query container. A `@container` rule
  cannot reach an ancestor.
- **Fragment engine:** the opposite topology — the query box is a host-document
  wrapper *above* your content — but a literal `body` selector still fails,
  because the reflected document is renamed to `wf-html` / `wf-body`.

Either way the fix is the same, and it is engine-safe:

```css
/* ✗ silently never matches */
@container wippy-surface (min-width: 640px) { body { display: flex } }

/* ✓ move it to your own root inside the surface */
@container wippy-surface (min-width: 640px) { #app { display: flex } }
```



### 18. `<picture><source media>` and `<link media>` — **not convertible**


HTML-level resource selection has no container-query form. Either drive it from
JS with `host.surface.onChange`, or move the art direction into CSS
(`background-image` under an `@container` rule) where the contract applies.



### 19. Geometry `matchMedia()` → `host.surface` — **automatic**


```js
// before
const mq = matchMedia('(min-width: 640px)')
mq.addEventListener('change', render)

// after
import { host } from '@wippy-fe/proxy'

const off = host.surface.onChange(s => render(s.width >= 640))
render(host.surface.snapshot.width >= 640)
// call off() on teardown
```

Keep `matchMedia` for preference queries — it is only geometry that is wrong.



### 20. Runtime CSS, adopted stylesheets, CSS-in-JS — **manual**


Prefer emitting `@container wippy-surface (...)` rules and letting CSS respond.
If you compute pixels in JS, regenerate from `onChange` — a value read once from
`snapshot` is frozen and desyncs on the next resize. Never emit the four
reserved `--wippy-surface-*` names yourself, and never register them with `@property` / `CSS.registerProperty()` — registration defeats the host's "block axis unavailable" signal, so a content-sized app silently reports itself as container-sized; a descendant declaration shadows the
inherited value and unpins your page from the surface.



### 21. Third-party bundled CSS — **manual**


You usually cannot edit it. In order of preference: configure the library to
accept a breakpoint/width you supply from `host.surface`; wrap it in your own
container and translate; or pin the page to the iframe engine
(`wippy.renderEngine: "iframe"`) and accept window-based behavior. Build-time
scanning to find these automatically is **not yet shipped**.



### 22. Nested containers and the `cq*` fallback trap — **manual**


Container units resolve against the *nearest* container that has the axis they
need. Two consequences:

```css
.card { container-type: inline-size; }   /* has NO block axis */
.card .thing { block-size: 25cqh; }      /* ✗ silently uses the small viewport */
```

`cqh`/`cqb` do not error when no block-axis container is found — they fall back
to the small viewport and render a plausible wrong number. Use
`var(--wippy-surface-height, <fallback>)` when you want the surface's block axis:
it is root-pinned, so a nearer container cannot intercept it, and it visibly
falls back when unavailable.

Component queries are additive, not a replacement: `wippy-surface` still refers
to the page's area from inside a nested container.

---



### Viewport units


| Was | Use | Notes |
| --- | --- | --- |
| `100vw` | `var(--wippy-surface-width)` | content box; see recipe 16 |
| `1vw` / `37vw` | `calc(var(--wippy-surface-width-unit) * 37)` or `37cqw` | unit is 1% |
| `100vh` | `var(--wippy-surface-height)` | container sizing only |
| `1vh` / `37vh` | `calc(var(--wippy-surface-height-unit) * 37)` | container sizing only |
| `vmin` | `min(var(--wippy-surface-width), var(--wippy-surface-height))` | container sizing only — needs both axes |
| `vmax` | `max(var(--wippy-surface-width), var(--wippy-surface-height))` | container sizing only |
| `vi` / `vb` | `cqi` / `cqb`, or the physical variables | logical; the surface variables are physical |
| `sv*` / `lv*` / `dv*` | `var(--wippy-surface-*)` | **no separate equivalents.** These describe browser-chrome states a panel does not have; the surface has one size |

`sv*`/`lv*` are real CSS units — they do **not** mean "surface".



#### Calculations


```css
/* before */ block-size: calc(100vh - 4rem);
/* after  */ block-size: calc(var(--wippy-surface-height, 400px) - 4rem);
```

The fallback is deliberately fixed and obviously wrong rather than `100vh` — see "Do not hide a missing contract behind a fallback" below. That matters more on the block axis than the inline one: the height is invalid on **every** content-sized placement, not only where the contract is absent, so a `100vh` fallback silently renders window height the first time the app is embedded.

`min()`/`max()`/`clamp()` convert unchanged; substitute the units inside them.



#### When `100%` is better than a surface value


If an element should fill its **parent**, use `100%` or `w-full`. Reach for
`--wippy-surface-width` only when you need the *page's* area specifically —
typically because an ancestor is narrower and you want to escape it. Root-pinning
something that should be parent-relative is how a layout ends up correct at one
nesting depth and wrong at another.



#### Do not hide a missing contract behind a fallback


```css
/* ✗ */ inline-size: var(--wippy-surface-width, 100vw);
```

That renders window-width when the contract is absent — the exact bug the
contract exists to prevent, made invisible. Let it fail visibly, or pick a fixed
fallback that is obviously wrong (`400px`) so it is noticed.

---



### Overlays


The surface contract does **not** capture `position: fixed` — `container-type`
establishes an independent formatting context without layout containment, so a
query container computes `contain: none` and anchors nothing. This is verified
across Chromium, Firefox and WebKit. PrimeVue overlays and hand-rolled fixed
overlays both keep working, so **positioning needs no migration**.

Their *sizing* does. An overlay meant to cover the surface should use `inset: 0`
— not `100vw`/`100vh`, which measure the browser window and overshoot in a
multi-panel host, and not `var(--wippy-surface-height)`, which is unavailable in
content sizing. Pair `inset: 0` with `position: absolute` inside a
`position: relative` root of the app's own if it must work in both engines;
`position: fixed` is correct only in the iframe engine, for the reason directly
below.

What does need attention is the engine, not the contract: in the Web Fragment
engine `position: fixed` resolves against the **host window**, not your panel.
See [Render Engines](../web-host/render-engines.md) and pin the app with
`wippy.renderEngine: "iframe"` if that matters.

Host-mediated overlay placement and `host.surface` scroll helpers are
**not yet shipped**.

---



### Checklist


1. Classify each rule (page / component / preference / deliberate window).
2. Convert page-intent geometry to `@container wippy-surface`.
3. Replace viewport units with the surface variables.
4. Move any rule that targeted `html`/`body` onto your own root element.
5. Re-check `em` breakpoints.
6. Declare `requirements` if you depend on the block axis.
7. Run the page in both engines **and in both sizings** — container and content
   are what this migration actually turns on, and an app is content-sized
   whenever it is embedded rather than routed. Check which one you are in with
   `host.surface.snapshot.sizing`, and gate block-axis behavior on
   `host.surface.supports('block-size')`.



---

# "Theme Authoring"

## Theme Authoring


**Classification: theme ownership and runtime contract reference.** The mode
switching block demonstrates one public API flow; it assumes a running Host and
does not configure a facade or build a module by itself.

The facade authors a PrimeVue theme. Modules consume it rather than defining an independent design system.

Wippy currently runs PrimeVue with `theme: 'none'`. Component appearance is supplied by Wippy’s Tailwind-authored PrimeVue CSS, public runtime variables, and facade customization.



### Where styling belongs


| Styling concern | Owner |
|---|---|
| PrimeVue component appearance shared across the product | Facade PrimeVue theme in `custom_css` and public theme variables |
| Host shell chrome only | Facade CSS scoped to `.wippy-host-app` |
| A shared `.p-*` rule intended for host and child roots | Global facade `custom_css`; no host scope required |
| Page-only theme override | Page configuration using supported frontend casing |
| Domain layout or novel structure | Module CSS or Tailwind |
| A necessary non-PrimeVue custom part | Module CSS, reusing public tokens and documented invariant utilities |
| The same non-PrimeVue part needed by several of your own modules | A shared package — see [The Design Layer](../design-layer.md) |
| An arbitrary class expected from one facade | Not portable; prohibited by FE-STYLE-001 |

A global `.p-drawer-content` rule is valid theme implementation when it is intended for every Drawer in host and child roots. `.wippy-host-app .p-drawer-content` is appropriate only when the rule is host-specific.

Moving duplicated module CSS into facade CSS does not eliminate the dependency. If the selector is not part of the shared PrimeVue theme vocabulary, it creates a private facade contract. The place for vocabulary shared by your own modules but absent from the theme is a published package: see [The Design Layer](../design-layer.md).



### Semantic equality


Semantically equivalent controls should look equivalent. Prefer PrimeVue components directly. When a genuinely custom control is needed, identify its PrimeVue visual sibling and use the same public runtime properties for color, border, focus, state, and any geometry classified theme-variable.

The custom part may own only the novel structure that the sibling does not provide. Reuse documented theme padding, dimensions, typography, radius, shadow, focus, and motion contracts wherever they exist. A literal copied from generated component CSS does not inherit future theme changes.



### Runtime versus invariant properties


Each shared appearance property has one policy:

- `theme-variable`: it must resolve through a documented public runtime variable.
- `platform-invariant`: the shared compiled Tailwind value is deliberately stable across every compliant theme.

Do not add runtime tokens for theoretical flexibility. Add or adopt a token only when a real runtime gap, an exact supported path, a real consumer, and mutation evidence are documented.



### CSS transport is not permission


Page style transport follows the selected rendering engine: iframe pages use
the proxy injection pipeline, while Web Fragment pages receive platform CSS
from the fragment gateway and page overrides in the reflected head. Web
components may receive styles inside a shadow root. These mechanisms explain
where CSS can take effect; they do not authorize a module to depend on
arbitrary facade selectors.



### Runtime mode switching


The public theme-mode contract is AppConfig plus `@wippy-fe/proxy`:

```typescript
import { host, on } from '@wippy-fe/proxy'

async function setThemeMode(mode: 'auto' | 'light' | 'dark') {
  if (host.getThemeMode() === mode) return

  await new Promise<void>((resolve, reject) => {
    let settled = false
    let stop = () => {}
    const finish = (error?: unknown) => {
      if (settled) return
      settled = true
      window.clearTimeout(timeout)
      stop()
      if (error) reject(error)
      else resolve()
    }
    const timeout = window.setTimeout(
      () => finish(new Error(`Timed out waiting for theme mode: ${mode}`)),
      5_000,
    )

    stop = on('@theme', (appliedMode) => {
      if (appliedMode !== mode) return
      finish()
    })

    try {
      host.setThemeMode(mode)
    } catch (error) {
      finish(error)
    }
  })
}

await setThemeMode('dark')
```

Use only `auto`, `light`, or `dark`. The host owns application and recursive
child propagation; the facade/embedder owns persistence. Directly editing
`w-theme-dark` / `w-theme-light`, calling internal theme helpers, writing
AppConfig globals, or posting host messages bypasses that contract and is
non-compliant. Visual evidence is valid only after the public API reports the
propagated mode.

See [Tailwind Contract](./tailwind-contract.md), [Token Catalogue](./token-catalogue.md), and [Portable UI Contract](../portable-ui-contract.md).



---

# "Tailwind Contract"

## Tailwind Contract


**Classification: generated contract reference.** The prose explains how to
interpret the catalogue; the generated rows report the pinned theme package's
compiled evidence and are not a Tailwind setup tutorial.

“Tailwind token” is ambiguous. Use these four terms instead.

| Layer | Example | Theme behavior |
|---|---|---|
| Utility name | `px-3`, `rounded-md`, `bg-primary` | Source vocabulary only |
| Compile-time Tailwind value | `px-3` emits a fixed spacing value | Embedded in the module bundle |
| Runtime-backed utility | `bg-primary` emits a reference to a public `--p-*` variable | Responds to facade runtime theme changes |
| Public portable contract | A deliberately documented Wippy token or semantic utility | Stable for supported portable consumers |

Tailwind 3 is a zero-runtime compiler. Do not infer runtime behavior from a utility name; inspect the emitted declaration.



### Runtime semantic utilities


The generated utility catalogue is the authority for exact mappings. It classifies current primary, surface, severity, text, content, highlight, and radius utilities by their emitted CSS and public variable dependency.

Examples of the intended categories include semantic colors, content borders, muted text, and `rounded-border` when the generated source confirms its mapping. An entry appears here only when generated from the selected preset and package versions.



### Compile-time baseline


The generated catalogue separately records spacing, sizing, default radii, font sizes, shadows, transition durations, and timing functions that compile to constants.

> Build-time baseline. This value is embedded in the module bundle and does not react to a facade theme change.

Compile-time values are valid for properties classified `platform-invariant`. They are insufficient for a property required to track a PrimeVue sibling under another facade theme.

`rounded-md` and `rounded-border` are not equivalent contracts even if they currently resolve to the same number: one is a compiled default and the other is runtime-backed. Equal current values also do not prove equal semantic roles.



### Protected mappings


Modules may extend the shared preset. They must not redefine protected Wippy meanings for:

- Primary and surface families.
- Severity families.
- Text, content, and highlight semantics.
- Published portable-control semantics.

Compliance resolves the actual module Tailwind configuration and rejects incompatible replacement of protected mappings.



### Custom siblings


A portable custom sibling may use:

- Runtime-backed semantic utilities listed in the generated catalogue.
- Direct public variables listed in the selected token manifest.
- Compile-time utilities for properties explicitly classified `platform-invariant`.
- Module-local utilities for genuinely novel structure.

It may not copy fixed dimensions, radii, or durations for properties expected to track its PrimeVue sibling. If no public runtime semantic exists, record a theme-contract gap; do not invent a utility or token.



### Generated utility catalogue


The checked-in snapshot is generated from:

- The exact Tailwind version selected by `@wippy-fe/theme`.
- The exact `tailwindcss-primeui` version.
- Wippy’s shared `tailwind.config.ts`.
- Wippy extensions.

Each generated row contains the utility, emitted property, resolved value, runtime dependency, intended use, allowed consumer, stability, package compatibility tuple, and source hashes.

<!-- GENERATED:TAILWIND-CONTRACT:BEGIN -->
Generated from @wippy-fe/theme 0.0.56. Every representative mapping below is checked against CSS compiled by Tailwind 3.4.19 with tailwindcss-primeui 0.6.1.

Source hashes: theme contract `b910b2d9fd11d82747da7adb13067deefb4319f8d88cf7551ce7a84e5e20b76a`; theme config `9b484e9da76871d11edda5a555b0d0443a262acd80fb42c74c4fd78e2b23b5ae`; Tailwind config `f1e862105254f082a78823ea685e3c6dc3ff5822516b7434a1e1141c976adc1d`; reference theme sources `aura/index.mjs=d1a1a574cf1a15aad8aee4cb3fa169aa97bf4029e9f858b84245e7f0b933d5ca; aura/base/index.mjs=9fec80a7ffbd5fb0229da666c1472c27c9a0a6a7ef3bb0a84bd7b070601e4198; aura/inputtext/index.mjs=5c5a4af9bacf0d585120b119bb7bfb02c7deedd9714b131d7009ff6e95f818e8; aura/toggleswitch/index.mjs=1e068fd0ede48eeeca4d10571940d65dadb3450b2ee51a39d09b33dda9da6e66; aura/button/index.mjs=44d8fd7f7ae163ce2653de8c6eb8af097fc453b4c60f702fcf76845be6ec9393`.



#### Runtime-backed semantic utilities


| Utility | CSS property | Resolved value | Runtime dependency | Classification | Allowed consumer | Stability | Intended use |
|---|---|---|---|---|---|---|---|
| `bg-danger-500` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-danger-500) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-danger-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `bg-emphasis` | background / color | `var(--p-content-hover-background) / var(--p-content-hover-color)` | --p-content-hover-background, --p-content-hover-color | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | public | Hovered or emphasized content |
| `bg-help-500` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-help-500) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-help-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `bg-highlight` | background / color | `var(--p-highlight-background) / var(--p-highlight-color)` | --p-highlight-background, --p-highlight-color | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | public | Selected or highlighted content |
| `bg-highlight-emphasis` | background / color | `var(--p-highlight-focus-background) / var(--p-highlight-focus-color)` | --p-highlight-focus-background, --p-highlight-focus-color | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | public | Focused highlighted content |
| `bg-info-500` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-info-500) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-info-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `bg-primary` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-primary-color) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-primary-color | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | public | Default primary action and emphasis color |
| `bg-primary-emphasis` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-primary-hover-color) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-primary-hover-color | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | public | Primary hover or emphasis state |
| `bg-success-500` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-success-500) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-success-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `bg-surface-0` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-surface-0) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-surface-0 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `bg-surface-100` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-surface-100) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-surface-100 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `bg-surface-200` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-surface-200) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-surface-200 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `bg-surface-300` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-surface-300) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-surface-300 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `bg-surface-400` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-surface-400) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-surface-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `bg-surface-50` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-surface-50) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-surface-50 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `bg-surface-700` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-surface-700) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-surface-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `bg-surface-950` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-surface-950) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-surface-950 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `bg-warn-500` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-warn-500) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-warn-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `border-danger-200` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-danger-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-danger-200 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `border-danger-400` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-danger-400) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-danger-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `border-danger-500` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-danger-500) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-danger-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `border-help-200` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-help-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-help-200 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `border-help-500` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-help-500) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-help-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `border-info-200` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-info-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-info-200 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `border-info-500` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-info-500) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-info-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `border-primary` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-primary-color) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-primary-color | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `border-primary-200` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-primary-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-primary-200 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `border-success-200` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-success-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-success-200 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `border-success-500` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-success-500) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-success-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `border-surface` | border-color | `var(--p-content-border-color)` | --p-content-border-color | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | public | Shared content and control borders |
| `border-surface-100` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-surface-100) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-surface-100 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `border-surface-200` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-surface-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-surface-200 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `border-surface-300` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-surface-300) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-surface-300 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `border-surface-700` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-surface-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-surface-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `border-surface-950` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-surface-950) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-surface-950 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `border-warn-200` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-warn-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-warn-200 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `border-warn-500` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-warn-500) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-warn-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:bg-danger-400` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-danger-400) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-danger-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:bg-help-400` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-help-400) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-help-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:bg-info-400` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-info-400) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-info-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:bg-success-400` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-success-400) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-success-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:bg-surface-0` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-surface-0) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-surface-0 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:bg-surface-300` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-surface-300) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-surface-300 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:bg-surface-400` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-surface-400) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-surface-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:bg-surface-600` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-surface-600) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-surface-600 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:bg-surface-700` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-surface-700) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-surface-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:bg-surface-800` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-surface-800) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-surface-800 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:bg-surface-900` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-surface-900) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-surface-900 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:bg-warn-400` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-warn-400) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-warn-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:border-danger-300` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-danger-300) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-danger-300 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:border-danger-400` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-danger-400) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-danger-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:border-danger-700` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-danger-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-danger-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:border-help-400` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-help-400) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-help-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:border-help-700` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-help-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-help-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:border-info-400` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-info-400) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-info-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:border-info-700` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-info-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-info-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:border-primary-700` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-primary-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-primary-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:border-success-400` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-success-400) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-success-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:border-success-700` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-success-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-success-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:border-surface-100` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-surface-100) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-surface-100 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:border-surface-500` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-surface-500) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-surface-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:border-surface-600` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-surface-600) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-surface-600 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:border-surface-700` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-surface-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-surface-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:border-surface-800` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-surface-800) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-surface-800 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:border-warn-400` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-warn-400) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-warn-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:border-warn-700` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-warn-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-warn-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:disabled:bg-surface-700` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-surface-700) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-surface-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:disabled:text-surface-400` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-surface-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-surface-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:bg-danger-200` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-danger-200) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-danger-200 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:bg-danger-400/15` | background-color | `color-mix(in srgb, var(--p-danger-400) calc(100% * 0.15), transparent)` | --p-danger-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:bg-help-200` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-help-200) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-help-200 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:bg-help-400/15` | background-color | `color-mix(in srgb, var(--p-help-400) calc(100% * 0.15), transparent)` | --p-help-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:bg-info-200` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-info-200) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-info-200 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:bg-info-400/15` | background-color | `color-mix(in srgb, var(--p-info-400) calc(100% * 0.15), transparent)` | --p-info-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:bg-primary/15` | background-color | `color-mix(in srgb, var(--p-primary-color) calc(100% * 0.15), transparent)` | --p-primary-color | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:bg-success-200` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-success-200) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-success-200 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:bg-success-400/15` | background-color | `color-mix(in srgb, var(--p-success-400) calc(100% * 0.15), transparent)` | --p-success-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:bg-surface-200` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-surface-200) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-surface-200 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:bg-surface-600` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-surface-600) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-surface-600 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:bg-surface-700` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-surface-700) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-surface-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:bg-warn-200` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-warn-200) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-warn-200 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:bg-warn-400/15` | background-color | `color-mix(in srgb, var(--p-warn-400) calc(100% * 0.15), transparent)` | --p-warn-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:border-danger-200` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-danger-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-danger-200 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:border-danger-700` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-danger-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-danger-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:border-help-200` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-help-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-help-200 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:border-help-700` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-help-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-help-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:border-info-200` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-info-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-info-200 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:border-info-700` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-info-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-info-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:border-primary-700` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-primary-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-primary-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:border-success-200` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-success-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-success-200 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:border-success-700` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-success-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-success-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:border-surface-300` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-surface-300) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-surface-300 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:border-surface-500` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-surface-500) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-surface-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:border-surface-600` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-surface-600) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-surface-600 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:border-surface-700` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-surface-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-surface-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:border-warn-200` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-warn-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-warn-200 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:border-warn-700` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-warn-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-warn-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:text-danger-400` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-danger-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-danger-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:text-danger-950` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-danger-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-danger-950 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:text-help-400` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-help-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-help-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:text-help-950` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-help-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-help-950 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:text-info-400` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-info-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-info-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:text-info-950` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-info-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-info-950 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:text-primary` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-primary-color) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-primary-color | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:text-success-400` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-success-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-success-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:text-success-950` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-success-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-success-950 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:text-surface-0` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-surface-0) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-surface-0 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:text-surface-100` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-surface-100) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-surface-100 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:text-surface-400` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-surface-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-surface-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:text-surface-950` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-surface-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-surface-950 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:text-warn-400` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-warn-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-warn-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:text-warn-950` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-warn-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-warn-950 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:focus:border-primary` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-primary-color) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-primary-color | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:bg-danger-300` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-danger-300) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-danger-300 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:bg-danger-400/5` | background-color | `color-mix(in srgb, var(--p-danger-400) calc(100% * 0.05), transparent)` | --p-danger-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:bg-help-300` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-help-300) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-help-300 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:bg-help-400/5` | background-color | `color-mix(in srgb, var(--p-help-400) calc(100% * 0.05), transparent)` | --p-help-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:bg-info-300` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-info-300) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-info-300 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:bg-info-400/5` | background-color | `color-mix(in srgb, var(--p-info-400) calc(100% * 0.05), transparent)` | --p-info-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:bg-primary/5` | background-color | `color-mix(in srgb, var(--p-primary-color) calc(100% * 0.05), transparent)` | --p-primary-color | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:bg-success-300` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-success-300) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-success-300 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:bg-success-400/5` | background-color | `color-mix(in srgb, var(--p-success-400) calc(100% * 0.05), transparent)` | --p-success-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:bg-surface-100` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-surface-100) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-surface-100 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:bg-surface-700` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-surface-700) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-surface-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:bg-surface-800` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-surface-800) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-surface-800 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:bg-warn-300` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-warn-300) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-warn-300 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:bg-warn-400/5` | background-color | `color-mix(in srgb, var(--p-warn-400) calc(100% * 0.05), transparent)` | --p-warn-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:border-danger-300` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-danger-300) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-danger-300 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:border-danger-700` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-danger-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-danger-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:border-help-300` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-help-300) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-help-300 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:border-help-700` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-help-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-help-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:border-info-300` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-info-300) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-info-300 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:border-info-700` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-info-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-info-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:border-primary-700` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-primary-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-primary-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:border-success-300` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-success-300) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-success-300 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:border-success-700` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-success-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-success-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:border-surface-200` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-surface-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-surface-200 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:border-surface-500` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-surface-500) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-surface-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:border-surface-600` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-surface-600) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-surface-600 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:border-surface-700` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-surface-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-surface-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:border-warn-300` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-warn-300) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-warn-300 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:border-warn-700` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-warn-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-warn-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:text-danger-400` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-danger-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-danger-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:text-danger-950` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-danger-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-danger-950 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:text-help-400` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-help-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-help-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:text-help-950` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-help-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-help-950 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:text-info-400` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-info-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-info-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:text-info-950` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-info-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-info-950 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:text-primary` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-primary-color) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-primary-color | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:text-success-400` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-success-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-success-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:text-success-950` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-success-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-success-950 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:text-surface-0` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-surface-0) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-surface-0 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:text-surface-200` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-surface-200) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-surface-200 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:text-surface-400` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-surface-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-surface-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:text-surface-950` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-surface-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-surface-950 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:text-warn-400` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-warn-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-warn-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:text-warn-950` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-warn-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-warn-950 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:focus-visible:outline-danger-400` | outline-color | `color-mix(in srgb, var(--p-danger-400) calc(100% * 1), transparent)` | --p-danger-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:focus-visible:outline-help-400` | outline-color | `color-mix(in srgb, var(--p-help-400) calc(100% * 1), transparent)` | --p-help-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:focus-visible:outline-info-400` | outline-color | `color-mix(in srgb, var(--p-info-400) calc(100% * 1), transparent)` | --p-info-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:focus-visible:outline-success-400` | outline-color | `color-mix(in srgb, var(--p-success-400) calc(100% * 1), transparent)` | --p-success-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:focus-visible:outline-surface-0` | outline-color | `color-mix(in srgb, var(--p-surface-0) calc(100% * 1), transparent)` | --p-surface-0 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:focus-visible:outline-surface-300` | outline-color | `color-mix(in srgb, var(--p-surface-300) calc(100% * 1), transparent)` | --p-surface-300 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:focus-visible:outline-warn-400` | outline-color | `color-mix(in srgb, var(--p-warn-400) calc(100% * 1), transparent)` | --p-warn-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:placeholder:text-surface-400` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-surface-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-surface-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:text-danger-400` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-danger-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-danger-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:text-danger-950` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-danger-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-danger-950 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:text-help-400` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-help-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-help-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:text-help-950` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-help-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-help-950 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:text-info-400` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-info-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-info-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:text-info-950` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-info-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-info-950 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:text-primary` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-primary-color) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-primary-color | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:text-success-400` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-success-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-success-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:text-success-950` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-success-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-success-950 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:text-surface-0` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-surface-0) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-surface-0 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:text-surface-300` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-surface-300) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-surface-300 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:text-surface-400` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-surface-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-surface-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:text-surface-800` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-surface-800) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-surface-800 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:text-surface-900` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-surface-900) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-surface-900 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:text-surface-950` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-surface-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-surface-950 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:text-warn-400` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-warn-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-warn-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:text-warn-950` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-warn-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-warn-950 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `disabled:bg-surface-200` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-surface-200) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-surface-200 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `disabled:text-surface-500` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-surface-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-surface-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:bg-danger-100` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-danger-100) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-danger-100 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:bg-danger-700` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-danger-700) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-danger-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:bg-help-100` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-help-100) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-help-100 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:bg-help-700` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-help-700) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-help-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:bg-info-100` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-info-100) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-info-100 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:bg-info-700` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-info-700) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-info-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:bg-primary-100` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-primary-100) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-primary-100 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:bg-primary-emphasis-alt` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-primary-active-color) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-primary-active-color | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:bg-success-100` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-success-100) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-success-100 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:bg-success-700` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-success-700) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-success-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:bg-surface-100` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-surface-100) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-surface-100 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:bg-surface-300` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-surface-300) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-surface-300 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:bg-surface-800` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-surface-800) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-surface-800 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:bg-warn-100` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-warn-100) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-warn-100 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:bg-warn-700` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-warn-700) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-warn-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:border-danger-200` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-danger-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-danger-200 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:border-danger-700` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-danger-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-danger-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:border-help-200` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-help-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-help-200 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:border-help-700` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-help-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-help-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:border-info-200` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-info-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-info-200 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:border-info-700` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-info-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-info-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:border-primary-200` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-primary-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-primary-200 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:border-primary-emphasis-alt` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-primary-active-color) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-primary-active-color | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:border-success-200` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-success-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-success-200 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:border-success-700` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-success-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-success-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:border-surface-200` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-surface-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-surface-200 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:border-surface-300` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-surface-300) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-surface-300 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:border-surface-700` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-surface-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-surface-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:border-surface-800` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-surface-800) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-surface-800 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:border-warn-200` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-warn-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-warn-200 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:border-warn-700` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-warn-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-warn-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:text-danger-500` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-danger-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-danger-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:text-help-500` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-help-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-help-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:text-info-500` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-info-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-info-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:text-primary` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-primary-color) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-primary-color | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:text-success-500` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-success-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-success-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:text-surface-500` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-surface-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-surface-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:text-surface-700` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-surface-700) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-surface-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:text-surface-800` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-surface-800) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-surface-800 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:text-surface-950` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-surface-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-surface-950 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:text-warn-500` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-warn-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-warn-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:focus:border-primary` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-primary-color) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-primary-color | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:bg-danger-50` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-danger-50) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-danger-50 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:bg-danger-600` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-danger-600) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-danger-600 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:bg-help-50` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-help-50) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-help-50 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:bg-help-600` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-help-600) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-help-600 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:bg-info-50` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-info-50) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-info-50 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:bg-info-600` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-info-600) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-info-600 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:bg-primary-50` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-primary-50) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-primary-50 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:bg-primary-emphasis` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-primary-hover-color) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-primary-hover-color | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:bg-success-50` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-success-50) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-success-50 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:bg-success-600` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-success-600) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-success-600 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:bg-surface-200` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-surface-200) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-surface-200 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:bg-surface-50` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-surface-50) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-surface-50 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:bg-surface-900` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-surface-900) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-surface-900 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:bg-warn-50` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-warn-50) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-warn-50 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:bg-warn-600` | --tw-bg-opacity / background-color | `1 / color-mix(in srgb, var(--p-warn-600) calc(100% * var(--tw-bg-opacity, 1)), transparent)` | --p-warn-600 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:border-danger-200` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-danger-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-danger-200 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:border-danger-600` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-danger-600) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-danger-600 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:border-help-200` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-help-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-help-200 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:border-help-600` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-help-600) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-help-600 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:border-info-200` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-info-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-info-200 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:border-info-600` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-info-600) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-info-600 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:border-primary-200` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-primary-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-primary-200 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:border-primary-emphasis` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-primary-hover-color) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-primary-hover-color | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:border-success-200` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-success-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-success-200 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:border-success-600` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-success-600) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-success-600 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:border-surface-200` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-surface-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-surface-200 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:border-surface-400` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-surface-400) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-surface-400 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:border-surface-700` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-surface-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-surface-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:border-surface-900` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-surface-900) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-surface-900 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:border-warn-200` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-warn-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-warn-200 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:border-warn-600` | --tw-border-opacity / border-color | `1 / color-mix(in srgb, var(--p-warn-600) calc(100% * var(--tw-border-opacity, 1)), transparent)` | --p-warn-600 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:text-danger-500` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-danger-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-danger-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:text-help-500` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-help-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-help-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:text-info-500` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-info-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-info-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:text-primary` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-primary-color) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-primary-color | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:text-success-500` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-success-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-success-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:text-surface-500` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-surface-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-surface-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:text-surface-700` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-surface-700) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-surface-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:text-surface-950` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-surface-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-surface-950 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:text-warn-500` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-warn-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-warn-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `focus-visible:outline-danger-500` | outline-color | `color-mix(in srgb, var(--p-danger-500) calc(100% * 1), transparent)` | --p-danger-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `focus-visible:outline-help-500` | outline-color | `color-mix(in srgb, var(--p-help-500) calc(100% * 1), transparent)` | --p-help-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `focus-visible:outline-info-500` | outline-color | `color-mix(in srgb, var(--p-info-500) calc(100% * 1), transparent)` | --p-info-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `focus-visible:outline-primary` | outline-color | `color-mix(in srgb, var(--p-primary-color) calc(100% * 1), transparent)` | --p-primary-color | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `focus-visible:outline-success-500` | outline-color | `color-mix(in srgb, var(--p-success-500) calc(100% * 1), transparent)` | --p-success-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `focus-visible:outline-surface-600` | outline-color | `color-mix(in srgb, var(--p-surface-600) calc(100% * 1), transparent)` | --p-surface-600 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `focus-visible:outline-surface-950` | outline-color | `color-mix(in srgb, var(--p-surface-950) calc(100% * 1), transparent)` | --p-surface-950 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `focus-visible:outline-warn-500` | outline-color | `color-mix(in srgb, var(--p-warn-500) calc(100% * 1), transparent)` | --p-warn-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `placeholder:text-surface-500` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-surface-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-surface-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `rounded-border` | border-radius | `var(--p-content-border-radius)` | --p-content-border-radius | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | public | Generic content radius, not an automatic form-control radius |
| `text-color` | color | `var(--p-text-color)` | --p-text-color | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | public | Primary content text |
| `text-color-emphasis` | color | `var(--p-text-hover-color)` | --p-text-hover-color | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | public | Emphasized content text |
| `text-danger-500` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-danger-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-danger-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `text-help-500` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-help-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-help-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `text-info-500` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-info-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-info-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `text-muted-color` | color | `var(--p-text-muted-color)` | --p-text-muted-color | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | public | Secondary content text |
| `text-muted-color-emphasis` | color | `var(--p-text-hover-muted-color)` | --p-text-hover-muted-color | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | public | Emphasized secondary text |
| `text-primary` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-primary-color) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-primary-color | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | public | Default primary action and emphasis color |
| `text-primary-contrast` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-primary-contrast-color) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-primary-contrast-color | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | public | Foreground paired with the primary background |
| `text-primary-emphasis` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-primary-hover-color) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-primary-hover-color | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `text-success-500` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-success-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-success-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `text-surface-500` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-surface-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-surface-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `text-surface-600` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-surface-600) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-surface-600 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `text-surface-700` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-surface-700) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-surface-700 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `text-surface-950` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-surface-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-surface-950 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `text-warn-500` | --tw-text-opacity / color | `1 / color-mix(in srgb, var(--p-warn-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` | --p-warn-500 | runtime-variable | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |



#### Compile-time baselines


> Build-time baseline. This value is embedded in the module bundle and does not react to a facade theme change.

| Utility | CSS property | Resolved value | Runtime dependency | Classification | Allowed consumer | Stability | Intended use |
|---|---|---|---|---|---|---|---|
| `absolute` | position | `absolute` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `appearance-none` | appearance | `none` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `bg-transparent` | background-color | `transparent` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `border` | border-width | `1px` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `border-transparent` | border-color | `transparent` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `cursor-pointer` | cursor | `pointer` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:bg-transparent` | background-color | `transparent` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:border-transparent` | border-color | `transparent` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:bg-white/15` | background-color | `rgb(255 255 255 / 0.15)` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:active:border-transparent` | border-color | `transparent` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:bg-white/5` | background-color | `rgb(255 255 255 / 0.05)` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `dark:enabled:hover:border-transparent` | border-color | `transparent` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `disabled:cursor-default` | cursor | `default` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `disabled:opacity-100` | opacity | `1` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `duration-200` | transition-duration | `200ms` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | platform-invariant-only | Static Tailwind motion baseline |
| `ease-in-out` | transition-timing-function | `cubic-bezier(0.4, 0, 0.2, 1)` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | platform-invariant-only | Static Tailwind timing baseline |
| `enabled:active:bg-transparent` | background-color | `transparent` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:border-transparent` | border-color | `transparent` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:active:text-white` | --tw-text-opacity / color | `1 / rgb(255 255 255 / var(--tw-text-opacity, 1))` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:bg-transparent` | background-color | `transparent` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:border-transparent` | border-color | `transparent` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `enabled:hover:text-white` | --tw-text-opacity / color | `1 / rgb(255 255 255 / var(--tw-text-opacity, 1))` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `flex` | display | `flex` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `flex-col` | flex-direction | `column` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `focus-visible:outline` | outline-style | `solid` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `focus-visible:outline-1` | outline-width | `1px` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `focus-visible:outline-offset-2` | outline-offset | `2px` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `font-medium` | font-weight | `500` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `gap-0` | gap | `0px` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `gap-2` | gap | `0.5rem` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | platform-invariant-only | Static Tailwind spacing baseline |
| `h-10` | height | `2.5rem` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `h-4` | height | `1rem` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `h-6` | height | `1.5rem` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | platform-invariant-only | Static Tailwind sizing baseline |
| `h-full` | height | `100%` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `inline-block` | display | `inline-block` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `inline-flex` | display | `inline-flex` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `invisible` | visibility | `hidden` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `items-center` | align-items | `center` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `justify-center` | justify-content | `center` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `leading-4` | line-height | `1rem` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `m-0` | margin | `0px` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `min-w-4` | min-width | `1rem` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `opacity-0` | opacity | `0` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `opacity-100` | opacity | `1` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `order-1` | order | `1` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `order-2` | order | `2` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `order-[-1]` | order | `-1` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `outline-1` | outline-width | `1px` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | platform-invariant-only | Static Tailwind focus geometry baseline |
| `outline-none` | outline / outline-offset | `2px solid transparent / 2px` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `outline-offset-2` | outline-offset | `2px` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | platform-invariant-only | Static Tailwind focus geometry baseline |
| `overflow-hidden` | overflow | `hidden` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `p-0` | padding | `0px` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `px-0` | padding-left / padding-right | `0px / 0px` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `px-2` | padding-left / padding-right | `0.5rem / 0.5rem` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `px-3` | padding-left / padding-right | `0.75rem / 0.75rem` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | platform-invariant-only | Static Tailwind spacing baseline |
| `px-[0.625rem]` | padding-left / padding-right | `0.625rem / 0.625rem` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `px-[0.875rem]` | padding-left / padding-right | `0.875rem / 0.875rem` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `py-1` | padding-top / padding-bottom | `0.25rem / 0.25rem` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `py-2` | padding-top / padding-bottom | `0.5rem / 0.5rem` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | platform-invariant-only | Static Tailwind spacing baseline |
| `py-[0.375rem]` | padding-top / padding-bottom | `0.375rem / 0.375rem` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `py-[0.625rem]` | padding-top / padding-bottom | `0.625rem / 0.625rem` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `relative` | position | `relative` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `rounded-[2rem]` | border-radius | `2rem` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `rounded-full` | border-radius | `9999px` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `rounded-md` | border-radius | `0.375rem` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | platform-invariant-only | Static Tailwind radius baseline |
| `select-none` | user-select | `none` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `shadow-[0_3px_1px_-2px_rgba(0,0,0,0.2),0_2px_2px_0_rgba(0,0,0,0.14),0_1px_5px_0_rgba(0,0,0,0.12)]` | --tw-shadow / --tw-shadow-colored / box-shadow | `0 3px 1px -2px rgba(0,0,0,0.2),0 2px 2px 0 rgba(0,0,0,0.14),0 1px 5px 0 rgba(0,0,0,0.12) / 0 3px 1px -2px var(--tw-shadow-color), 0 2px 2px 0 var(--tw-shadow-color), 0 1px 5px 0 var(--tw-shadow-color) / var(--tw-ring-offset-shadow, 0 0 #0000), var(--tw-ring-shadow, 0 0 #0000), var(--tw-shadow)` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `start-0` | inset-inline-start | `0px` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `text-[1.125rem]` | font-size | `1.125rem` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `text-lg` | font-size / line-height | `1.125rem / 1.75rem` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `text-sm` | font-size / line-height | `0.875rem / 1.25rem` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | platform-invariant-only | Static Tailwind typography baseline |
| `text-white` | --tw-text-opacity / color | `1 / rgb(255 255 255 / var(--tw-text-opacity, 1))` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `text-xs` | font-size / line-height | `0.75rem / 1rem` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `top-0` | top | `0px` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `top-1/2` | top | `50%` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `transition-[background,color,left]` | transition-property / transition-timing-function / transition-duration | `background,color,left / cubic-bezier(0.4, 0, 0.2, 1) / 150ms` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `transition-colors` | transition-property / transition-timing-function / transition-duration | `color, background-color, border-color, text-decoration-color, fill, stroke / cubic-bezier(0.4, 0, 0.2, 1) / 150ms` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `underline` | text-decoration-line | `underline` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `w-0` | width | `0px` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `w-10` | width | `2.5rem` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | platform-invariant-only | Static Tailwind sizing baseline |
| `w-full` | width | `100%` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |
| `z-10` | z-index | `10` | none | compile-time-constant | portable module when semantic use matches; fixed values only after invariant review | generated-representative | Representative utility; review semantic use at the consumer |



#### Internal or transient utilities


| Utility | CSS property | Resolved value | Runtime dependency | Classification | Allowed consumer | Stability | Intended use |
|---|---|---|---|---|---|---|---|



#### Compiled representative probes


| Utility | Emitted declarations |
|---|---|
| `absolute` | `position: absolute` |
| `appearance-none` | `appearance: none` |
| `bg-danger-500` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-danger-500) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `bg-emphasis` | `background: var(--p-content-hover-background); color: var(--p-content-hover-color)` |
| `bg-help-500` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-help-500) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `bg-highlight` | `background: var(--p-highlight-background); color: var(--p-highlight-color)` |
| `bg-highlight-emphasis` | `background: var(--p-highlight-focus-background); color: var(--p-highlight-focus-color)` |
| `bg-info-500` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-info-500) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `bg-primary` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-primary-color) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `bg-primary-emphasis` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-primary-hover-color) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `bg-success-500` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-success-500) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `bg-surface-0` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-surface-0) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `bg-surface-100` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-surface-100) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `bg-surface-200` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-surface-200) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `bg-surface-300` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-surface-300) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `bg-surface-400` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-surface-400) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `bg-surface-50` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-surface-50) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `bg-surface-700` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-surface-700) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `bg-surface-950` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-surface-950) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `bg-transparent` | `background-color: transparent` |
| `bg-warn-500` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-warn-500) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `border` | `border-width: 1px` |
| `border-danger-200` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-danger-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `border-danger-400` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-danger-400) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `border-danger-500` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-danger-500) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `border-help-200` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-help-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `border-help-500` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-help-500) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `border-info-200` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-info-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `border-info-500` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-info-500) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `border-primary` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-primary-color) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `border-primary-200` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-primary-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `border-success-200` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-success-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `border-success-500` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-success-500) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `border-surface` | `border-color: var(--p-content-border-color)` |
| `border-surface-100` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-surface-100) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `border-surface-200` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-surface-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `border-surface-300` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-surface-300) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `border-surface-700` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-surface-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `border-surface-950` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-surface-950) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `border-transparent` | `border-color: transparent` |
| `border-warn-200` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-warn-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `border-warn-500` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-warn-500) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `cursor-pointer` | `cursor: pointer` |
| `dark:bg-danger-400` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-danger-400) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `dark:bg-help-400` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-help-400) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `dark:bg-info-400` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-info-400) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `dark:bg-success-400` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-success-400) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `dark:bg-surface-0` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-surface-0) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `dark:bg-surface-300` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-surface-300) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `dark:bg-surface-400` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-surface-400) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `dark:bg-surface-600` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-surface-600) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `dark:bg-surface-700` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-surface-700) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `dark:bg-surface-800` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-surface-800) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `dark:bg-surface-900` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-surface-900) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `dark:bg-transparent` | `background-color: transparent` |
| `dark:bg-warn-400` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-warn-400) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `dark:border-danger-300` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-danger-300) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:border-danger-400` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-danger-400) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:border-danger-700` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-danger-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:border-help-400` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-help-400) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:border-help-700` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-help-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:border-info-400` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-info-400) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:border-info-700` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-info-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:border-primary-700` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-primary-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:border-success-400` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-success-400) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:border-success-700` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-success-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:border-surface-100` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-surface-100) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:border-surface-500` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-surface-500) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:border-surface-600` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-surface-600) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:border-surface-700` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-surface-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:border-surface-800` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-surface-800) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:border-transparent` | `border-color: transparent` |
| `dark:border-warn-400` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-warn-400) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:border-warn-700` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-warn-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:disabled:bg-surface-700` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-surface-700) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `dark:disabled:text-surface-400` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-surface-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:enabled:active:bg-danger-200` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-danger-200) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `dark:enabled:active:bg-danger-400/15` | `background-color: color-mix(in srgb, var(--p-danger-400) calc(100% * 0.15), transparent)` |
| `dark:enabled:active:bg-help-200` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-help-200) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `dark:enabled:active:bg-help-400/15` | `background-color: color-mix(in srgb, var(--p-help-400) calc(100% * 0.15), transparent)` |
| `dark:enabled:active:bg-info-200` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-info-200) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `dark:enabled:active:bg-info-400/15` | `background-color: color-mix(in srgb, var(--p-info-400) calc(100% * 0.15), transparent)` |
| `dark:enabled:active:bg-primary/15` | `background-color: color-mix(in srgb, var(--p-primary-color) calc(100% * 0.15), transparent)` |
| `dark:enabled:active:bg-success-200` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-success-200) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `dark:enabled:active:bg-success-400/15` | `background-color: color-mix(in srgb, var(--p-success-400) calc(100% * 0.15), transparent)` |
| `dark:enabled:active:bg-surface-200` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-surface-200) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `dark:enabled:active:bg-surface-600` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-surface-600) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `dark:enabled:active:bg-surface-700` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-surface-700) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `dark:enabled:active:bg-warn-200` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-warn-200) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `dark:enabled:active:bg-warn-400/15` | `background-color: color-mix(in srgb, var(--p-warn-400) calc(100% * 0.15), transparent)` |
| `dark:enabled:active:bg-white/15` | `background-color: rgb(255 255 255 / 0.15)` |
| `dark:enabled:active:border-danger-200` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-danger-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:enabled:active:border-danger-700` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-danger-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:enabled:active:border-help-200` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-help-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:enabled:active:border-help-700` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-help-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:enabled:active:border-info-200` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-info-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:enabled:active:border-info-700` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-info-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:enabled:active:border-primary-700` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-primary-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:enabled:active:border-success-200` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-success-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:enabled:active:border-success-700` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-success-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:enabled:active:border-surface-300` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-surface-300) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:enabled:active:border-surface-500` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-surface-500) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:enabled:active:border-surface-600` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-surface-600) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:enabled:active:border-surface-700` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-surface-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:enabled:active:border-transparent` | `border-color: transparent` |
| `dark:enabled:active:border-warn-200` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-warn-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:enabled:active:border-warn-700` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-warn-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:enabled:active:text-danger-400` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-danger-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:enabled:active:text-danger-950` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-danger-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:enabled:active:text-help-400` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-help-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:enabled:active:text-help-950` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-help-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:enabled:active:text-info-400` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-info-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:enabled:active:text-info-950` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-info-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:enabled:active:text-primary` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-primary-color) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:enabled:active:text-success-400` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-success-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:enabled:active:text-success-950` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-success-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:enabled:active:text-surface-0` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-surface-0) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:enabled:active:text-surface-100` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-surface-100) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:enabled:active:text-surface-400` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-surface-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:enabled:active:text-surface-950` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-surface-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:enabled:active:text-warn-400` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-warn-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:enabled:active:text-warn-950` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-warn-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:enabled:focus:border-primary` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-primary-color) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:enabled:hover:bg-danger-300` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-danger-300) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `dark:enabled:hover:bg-danger-400/5` | `background-color: color-mix(in srgb, var(--p-danger-400) calc(100% * 0.05), transparent)` |
| `dark:enabled:hover:bg-help-300` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-help-300) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `dark:enabled:hover:bg-help-400/5` | `background-color: color-mix(in srgb, var(--p-help-400) calc(100% * 0.05), transparent)` |
| `dark:enabled:hover:bg-info-300` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-info-300) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `dark:enabled:hover:bg-info-400/5` | `background-color: color-mix(in srgb, var(--p-info-400) calc(100% * 0.05), transparent)` |
| `dark:enabled:hover:bg-primary/5` | `background-color: color-mix(in srgb, var(--p-primary-color) calc(100% * 0.05), transparent)` |
| `dark:enabled:hover:bg-success-300` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-success-300) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `dark:enabled:hover:bg-success-400/5` | `background-color: color-mix(in srgb, var(--p-success-400) calc(100% * 0.05), transparent)` |
| `dark:enabled:hover:bg-surface-100` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-surface-100) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `dark:enabled:hover:bg-surface-700` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-surface-700) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `dark:enabled:hover:bg-surface-800` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-surface-800) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `dark:enabled:hover:bg-warn-300` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-warn-300) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `dark:enabled:hover:bg-warn-400/5` | `background-color: color-mix(in srgb, var(--p-warn-400) calc(100% * 0.05), transparent)` |
| `dark:enabled:hover:bg-white/5` | `background-color: rgb(255 255 255 / 0.05)` |
| `dark:enabled:hover:border-danger-300` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-danger-300) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:enabled:hover:border-danger-700` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-danger-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:enabled:hover:border-help-300` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-help-300) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:enabled:hover:border-help-700` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-help-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:enabled:hover:border-info-300` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-info-300) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:enabled:hover:border-info-700` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-info-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:enabled:hover:border-primary-700` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-primary-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:enabled:hover:border-success-300` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-success-300) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:enabled:hover:border-success-700` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-success-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:enabled:hover:border-surface-200` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-surface-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:enabled:hover:border-surface-500` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-surface-500) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:enabled:hover:border-surface-600` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-surface-600) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:enabled:hover:border-surface-700` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-surface-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:enabled:hover:border-transparent` | `border-color: transparent` |
| `dark:enabled:hover:border-warn-300` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-warn-300) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:enabled:hover:border-warn-700` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-warn-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `dark:enabled:hover:text-danger-400` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-danger-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:enabled:hover:text-danger-950` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-danger-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:enabled:hover:text-help-400` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-help-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:enabled:hover:text-help-950` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-help-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:enabled:hover:text-info-400` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-info-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:enabled:hover:text-info-950` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-info-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:enabled:hover:text-primary` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-primary-color) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:enabled:hover:text-success-400` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-success-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:enabled:hover:text-success-950` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-success-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:enabled:hover:text-surface-0` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-surface-0) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:enabled:hover:text-surface-200` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-surface-200) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:enabled:hover:text-surface-400` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-surface-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:enabled:hover:text-surface-950` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-surface-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:enabled:hover:text-warn-400` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-warn-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:enabled:hover:text-warn-950` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-warn-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:focus-visible:outline-danger-400` | `outline-color: color-mix(in srgb, var(--p-danger-400) calc(100% * 1), transparent)` |
| `dark:focus-visible:outline-help-400` | `outline-color: color-mix(in srgb, var(--p-help-400) calc(100% * 1), transparent)` |
| `dark:focus-visible:outline-info-400` | `outline-color: color-mix(in srgb, var(--p-info-400) calc(100% * 1), transparent)` |
| `dark:focus-visible:outline-success-400` | `outline-color: color-mix(in srgb, var(--p-success-400) calc(100% * 1), transparent)` |
| `dark:focus-visible:outline-surface-0` | `outline-color: color-mix(in srgb, var(--p-surface-0) calc(100% * 1), transparent)` |
| `dark:focus-visible:outline-surface-300` | `outline-color: color-mix(in srgb, var(--p-surface-300) calc(100% * 1), transparent)` |
| `dark:focus-visible:outline-warn-400` | `outline-color: color-mix(in srgb, var(--p-warn-400) calc(100% * 1), transparent)` |
| `dark:placeholder:text-surface-400` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-surface-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:text-danger-400` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-danger-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:text-danger-950` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-danger-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:text-help-400` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-help-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:text-help-950` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-help-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:text-info-400` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-info-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:text-info-950` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-info-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:text-primary` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-primary-color) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:text-success-400` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-success-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:text-success-950` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-success-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:text-surface-0` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-surface-0) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:text-surface-300` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-surface-300) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:text-surface-400` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-surface-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:text-surface-800` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-surface-800) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:text-surface-900` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-surface-900) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:text-surface-950` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-surface-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:text-warn-400` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-warn-400) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `dark:text-warn-950` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-warn-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `disabled:bg-surface-200` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-surface-200) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `disabled:cursor-default` | `cursor: default` |
| `disabled:opacity-100` | `opacity: 1` |
| `disabled:text-surface-500` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-surface-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `duration-200` | `transition-duration: 200ms` |
| `ease-in-out` | `transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1)` |
| `enabled:active:bg-danger-100` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-danger-100) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `enabled:active:bg-danger-700` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-danger-700) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `enabled:active:bg-help-100` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-help-100) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `enabled:active:bg-help-700` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-help-700) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `enabled:active:bg-info-100` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-info-100) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `enabled:active:bg-info-700` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-info-700) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `enabled:active:bg-primary-100` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-primary-100) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `enabled:active:bg-primary-emphasis-alt` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-primary-active-color) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `enabled:active:bg-success-100` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-success-100) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `enabled:active:bg-success-700` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-success-700) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `enabled:active:bg-surface-100` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-surface-100) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `enabled:active:bg-surface-300` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-surface-300) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `enabled:active:bg-surface-800` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-surface-800) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `enabled:active:bg-transparent` | `background-color: transparent` |
| `enabled:active:bg-warn-100` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-warn-100) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `enabled:active:bg-warn-700` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-warn-700) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `enabled:active:border-danger-200` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-danger-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `enabled:active:border-danger-700` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-danger-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `enabled:active:border-help-200` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-help-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `enabled:active:border-help-700` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-help-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `enabled:active:border-info-200` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-info-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `enabled:active:border-info-700` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-info-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `enabled:active:border-primary-200` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-primary-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `enabled:active:border-primary-emphasis-alt` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-primary-active-color) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `enabled:active:border-success-200` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-success-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `enabled:active:border-success-700` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-success-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `enabled:active:border-surface-200` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-surface-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `enabled:active:border-surface-300` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-surface-300) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `enabled:active:border-surface-700` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-surface-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `enabled:active:border-surface-800` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-surface-800) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `enabled:active:border-transparent` | `border-color: transparent` |
| `enabled:active:border-warn-200` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-warn-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `enabled:active:border-warn-700` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-warn-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `enabled:active:text-danger-500` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-danger-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `enabled:active:text-help-500` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-help-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `enabled:active:text-info-500` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-info-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `enabled:active:text-primary` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-primary-color) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `enabled:active:text-success-500` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-success-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `enabled:active:text-surface-500` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-surface-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `enabled:active:text-surface-700` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-surface-700) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `enabled:active:text-surface-800` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-surface-800) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `enabled:active:text-surface-950` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-surface-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `enabled:active:text-warn-500` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-warn-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `enabled:active:text-white` | `--tw-text-opacity: 1; color: rgb(255 255 255 / var(--tw-text-opacity, 1))` |
| `enabled:focus:border-primary` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-primary-color) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `enabled:hover:bg-danger-50` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-danger-50) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `enabled:hover:bg-danger-600` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-danger-600) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `enabled:hover:bg-help-50` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-help-50) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `enabled:hover:bg-help-600` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-help-600) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `enabled:hover:bg-info-50` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-info-50) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `enabled:hover:bg-info-600` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-info-600) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `enabled:hover:bg-primary-50` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-primary-50) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `enabled:hover:bg-primary-emphasis` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-primary-hover-color) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `enabled:hover:bg-success-50` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-success-50) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `enabled:hover:bg-success-600` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-success-600) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `enabled:hover:bg-surface-200` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-surface-200) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `enabled:hover:bg-surface-50` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-surface-50) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `enabled:hover:bg-surface-900` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-surface-900) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `enabled:hover:bg-transparent` | `background-color: transparent` |
| `enabled:hover:bg-warn-50` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-warn-50) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `enabled:hover:bg-warn-600` | `--tw-bg-opacity: 1; background-color: color-mix(in srgb, var(--p-warn-600) calc(100% * var(--tw-bg-opacity, 1)), transparent)` |
| `enabled:hover:border-danger-200` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-danger-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `enabled:hover:border-danger-600` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-danger-600) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `enabled:hover:border-help-200` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-help-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `enabled:hover:border-help-600` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-help-600) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `enabled:hover:border-info-200` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-info-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `enabled:hover:border-info-600` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-info-600) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `enabled:hover:border-primary-200` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-primary-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `enabled:hover:border-primary-emphasis` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-primary-hover-color) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `enabled:hover:border-success-200` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-success-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `enabled:hover:border-success-600` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-success-600) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `enabled:hover:border-surface-200` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-surface-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `enabled:hover:border-surface-400` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-surface-400) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `enabled:hover:border-surface-700` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-surface-700) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `enabled:hover:border-surface-900` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-surface-900) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `enabled:hover:border-transparent` | `border-color: transparent` |
| `enabled:hover:border-warn-200` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-warn-200) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `enabled:hover:border-warn-600` | `--tw-border-opacity: 1; border-color: color-mix(in srgb, var(--p-warn-600) calc(100% * var(--tw-border-opacity, 1)), transparent)` |
| `enabled:hover:text-danger-500` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-danger-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `enabled:hover:text-help-500` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-help-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `enabled:hover:text-info-500` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-info-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `enabled:hover:text-primary` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-primary-color) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `enabled:hover:text-success-500` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-success-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `enabled:hover:text-surface-500` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-surface-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `enabled:hover:text-surface-700` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-surface-700) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `enabled:hover:text-surface-950` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-surface-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `enabled:hover:text-warn-500` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-warn-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `enabled:hover:text-white` | `--tw-text-opacity: 1; color: rgb(255 255 255 / var(--tw-text-opacity, 1))` |
| `flex` | `display: flex` |
| `flex-col` | `flex-direction: column` |
| `focus-visible:outline` | `outline-style: solid` |
| `focus-visible:outline-1` | `outline-width: 1px` |
| `focus-visible:outline-danger-500` | `outline-color: color-mix(in srgb, var(--p-danger-500) calc(100% * 1), transparent)` |
| `focus-visible:outline-help-500` | `outline-color: color-mix(in srgb, var(--p-help-500) calc(100% * 1), transparent)` |
| `focus-visible:outline-info-500` | `outline-color: color-mix(in srgb, var(--p-info-500) calc(100% * 1), transparent)` |
| `focus-visible:outline-offset-2` | `outline-offset: 2px` |
| `focus-visible:outline-primary` | `outline-color: color-mix(in srgb, var(--p-primary-color) calc(100% * 1), transparent)` |
| `focus-visible:outline-success-500` | `outline-color: color-mix(in srgb, var(--p-success-500) calc(100% * 1), transparent)` |
| `focus-visible:outline-surface-600` | `outline-color: color-mix(in srgb, var(--p-surface-600) calc(100% * 1), transparent)` |
| `focus-visible:outline-surface-950` | `outline-color: color-mix(in srgb, var(--p-surface-950) calc(100% * 1), transparent)` |
| `focus-visible:outline-warn-500` | `outline-color: color-mix(in srgb, var(--p-warn-500) calc(100% * 1), transparent)` |
| `font-medium` | `font-weight: 500` |
| `gap-0` | `gap: 0px` |
| `gap-2` | `gap: 0.5rem` |
| `h-10` | `height: 2.5rem` |
| `h-4` | `height: 1rem` |
| `h-6` | `height: 1.5rem` |
| `h-full` | `height: 100%` |
| `inline-block` | `display: inline-block` |
| `inline-flex` | `display: inline-flex` |
| `invisible` | `visibility: hidden` |
| `items-center` | `align-items: center` |
| `justify-center` | `justify-content: center` |
| `leading-4` | `line-height: 1rem` |
| `m-0` | `margin: 0px` |
| `min-w-4` | `min-width: 1rem` |
| `opacity-0` | `opacity: 0` |
| `opacity-100` | `opacity: 1` |
| `order-1` | `order: 1` |
| `order-2` | `order: 2` |
| `order-[-1]` | `order: -1` |
| `outline-1` | `outline-width: 1px` |
| `outline-none` | `outline: 2px solid transparent; outline-offset: 2px` |
| `outline-offset-2` | `outline-offset: 2px` |
| `overflow-hidden` | `overflow: hidden` |
| `p-0` | `padding: 0px` |
| `placeholder:text-surface-500` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-surface-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `px-0` | `padding-left: 0px; padding-right: 0px` |
| `px-2` | `padding-left: 0.5rem; padding-right: 0.5rem` |
| `px-3` | `padding-left: 0.75rem; padding-right: 0.75rem` |
| `px-[0.625rem]` | `padding-left: 0.625rem; padding-right: 0.625rem` |
| `px-[0.875rem]` | `padding-left: 0.875rem; padding-right: 0.875rem` |
| `py-1` | `padding-top: 0.25rem; padding-bottom: 0.25rem` |
| `py-2` | `padding-top: 0.5rem; padding-bottom: 0.5rem` |
| `py-[0.375rem]` | `padding-top: 0.375rem; padding-bottom: 0.375rem` |
| `py-[0.625rem]` | `padding-top: 0.625rem; padding-bottom: 0.625rem` |
| `relative` | `position: relative` |
| `rounded-[2rem]` | `border-radius: 2rem` |
| `rounded-border` | `border-radius: var(--p-content-border-radius)` |
| `rounded-full` | `border-radius: 9999px` |
| `rounded-md` | `border-radius: 0.375rem` |
| `select-none` | `user-select: none` |
| `shadow-[0_3px_1px_-2px_rgba(0,0,0,0.2),0_2px_2px_0_rgba(0,0,0,0.14),0_1px_5px_0_rgba(0,0,0,0.12)]` | `--tw-shadow: 0 3px 1px -2px rgba(0,0,0,0.2),0 2px 2px 0 rgba(0,0,0,0.14),0 1px 5px 0 rgba(0,0,0,0.12); --tw-shadow-colored: 0 3px 1px -2px var(--tw-shadow-color), 0 2px 2px 0 var(--tw-shadow-color), 0 1px 5px 0 var(--tw-shadow-color); box-shadow: var(--tw-ring-offset-shadow, 0 0 #0000), var(--tw-ring-shadow, 0 0 #0000), var(--tw-shadow)` |
| `start-0` | `inset-inline-start: 0px` |
| `text-[1.125rem]` | `font-size: 1.125rem` |
| `text-color` | `color: var(--p-text-color)` |
| `text-color-emphasis` | `color: var(--p-text-hover-color)` |
| `text-danger-500` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-danger-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `text-help-500` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-help-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `text-info-500` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-info-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `text-lg` | `font-size: 1.125rem; line-height: 1.75rem` |
| `text-muted-color` | `color: var(--p-text-muted-color)` |
| `text-muted-color-emphasis` | `color: var(--p-text-hover-muted-color)` |
| `text-primary` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-primary-color) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `text-primary-contrast` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-primary-contrast-color) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `text-primary-emphasis` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-primary-hover-color) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `text-sm` | `font-size: 0.875rem; line-height: 1.25rem` |
| `text-success-500` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-success-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `text-surface-500` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-surface-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `text-surface-600` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-surface-600) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `text-surface-700` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-surface-700) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `text-surface-950` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-surface-950) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `text-warn-500` | `--tw-text-opacity: 1; color: color-mix(in srgb, var(--p-warn-500) calc(100% * var(--tw-text-opacity, 1)), transparent)` |
| `text-white` | `--tw-text-opacity: 1; color: rgb(255 255 255 / var(--tw-text-opacity, 1))` |
| `text-xs` | `font-size: 0.75rem; line-height: 1rem` |
| `top-0` | `top: 0px` |
| `top-1/2` | `top: 50%` |
| `transition-[background,color,left]` | `transition-property: background,color,left; transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1); transition-duration: 150ms` |
| `transition-colors` | `transition-property: color, background-color, border-color, text-decoration-color, fill, stroke; transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1); transition-duration: 150ms` |
| `underline` | `text-decoration-line: underline` |
| `w-0` | `width: 0px` |
| `w-10` | `width: 2.5rem` |
| `w-full` | `width: 100%` |
| `z-10` | `z-index: 10` |
<!-- GENERATED:TAILWIND-CONTRACT:END -->



---

# "Token Catalogue"

## Token Catalogue


**Classification: generated token reference.** Use it to select an existing
public token and inspect its provenance. It does not teach facade theme setup or
authorize names absent from the generated package manifest.

> Never construct a token name by analogy. Search this catalogue or the selected package manifest.

This page is a checked-in projection of the structured token source in `@wippy-fe/theme`. Normative prose lives in Wippy Docs; token names, values, consumers, and source provenance are generated from package sources.

Every generated row includes:

- Exact CSS variable name and stable identity. Reviewed semantic/component
  contracts use their authored ID; palette and inherited entries use an ID
  derived deterministically from the public variable name.
- Official PrimeVue or PrimeUIX path when the selected manifest publishes one.
- Layer and semantic purpose.
- Default, light, and dark mappings.
- Declared coverage separately from browser-accepted runtime coverage.
- PrimeVue CSS consumers separately from portable custom-sibling contract
  consumers.
- Stability from the selected manifest; absent lifecycle metadata is not
  invented.

The snapshot header must record `schemaVersion`, `packageVersion`, `implementationRelease`, Tailwind, PrimeUI plugin, PrimeVue, PrimeUIX package versions, and source hashes. A package version and a manifest schema version are different values.

Declared does not mean effective. Generated package coverage remains
`inherited`; publication separately requires external, content-hashed
computed-style and visual evidence for every committed acceptance requirement.
Local evidence is never projected into this checked-in catalogue. Temporary
animation variables are classified internal unless Wippy deliberately
publishes them.



### Effective-contract ledger


Token additions begin with evidence, not proposed names. For every audited
appearance declaration or Tailwind utility in Button, form fields,
ToggleSwitch, and their focus states, the generated ledger records the stable
ID, source file or upstream object, selector or PrimeVue path, authored
property/utility, resolved value where available, referenced runtime variables,
semantic-review state, mutation state, disposition, and source evidence.

`runtime-covered-existing` is static emitted-CSS proof that the declaration
depends on a public runtime variable. It is not browser acceptance. Token
coverage remains `inherited`, and mutation remains `pending-browser-proof`,
until computed-style mutation succeeds.

Allowed dispositions are:

- `runtime-covered-existing`
- `compile-baseline-platform-invariant`
- `compile-baseline-insufficient`
- `partly-covered-needs-semantic-indirection`
- `official-semantic-gap-used`
- `official-component-gap-used`
- `literal-needs-contract`
- `internal-transient`
- `declared-unconsumed`
- `unused-upstream`
- `legacy`
- `semantic-mismatch`
- `name-collision`

A new public token is allowed only when the property must change at runtime, the current utility compiles to a constant, no existing public semantic matches, the exact upstream path is verified or a Wippy extension is separately reviewed, a real Wippy CSS consumer exists, and mutation testing proves the expected computed property changes.

Equal current values do not establish equal semantics. In particular, a generic content radius cannot become the radius contract for every control without an explicit structured relationship.



### Runtime evidence


The generated ledger records runtime proof as `pending-browser-proof` until a
visible-browser test renders the actual component, reads the original computed
property, mutates the token, verifies the expected property changes, and
restores the value. A pending record is not runtime acceptance evidence.

Publication additionally requires an alternate test theme that changes more
than palette colors: selected radius, form-field padding, focus geometry,
ToggleSwitch geometry, and any shadow or motion property classified
`theme-variable`. This prevents color coverage from hiding geometry gaps.

<!-- GENERATED:TOKEN-CATALOGUE:BEGIN -->
Generated from @wippy-fe/theme 0.0.56; schema 1.0.0; implementation 1.0.56.

Compatibility: Tailwind 3.4.19, tailwindcss-primeui 0.6.1, PrimeVue 4.5.5, @primeuix/styles 2.0.3, @primeuix/styled 0.7.4, reference @primeuix/themes 2.0.3.

Source hashes: theme contract `b910b2d9fd11d82747da7adb13067deefb4319f8d88cf7551ce7a84e5e20b76a`; theme config `9b484e9da76871d11edda5a555b0d0443a262acd80fb42c74c4fd78e2b23b5ae`; Tailwind config `f1e862105254f082a78823ea685e3c6dc3ff5822516b7434a1e1141c976adc1d`; reference theme sources `aura/index.mjs=d1a1a574cf1a15aad8aee4cb3fa169aa97bf4029e9f858b84245e7f0b933d5ca; aura/base/index.mjs=9fec80a7ffbd5fb0229da666c1472c27c9a0a6a7ef3bb0a84bd7b070601e4198; aura/inputtext/index.mjs=5c5a4af9bacf0d585120b119bb7bfb02c7deedd9714b131d7009ff6e95f818e8; aura/toggleswitch/index.mjs=1e068fd0ede48eeeca4d10571940d65dadb3450b2ee51a39d09b33dda9da6e66; aura/button/index.mjs=44d8fd7f7ae163ce2653de8c6eb8af097fc453b4c60f702fcf76845be6ec9393`.

| Stable ID | Token | Layer | Official path | Default | Light | Dark | Declared coverage | Package coverage | Purpose | PrimeVue consumers | Portable-contract consumers | Stability |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| `token.accent` | `--p-accent` | base | — | `rgb(20, 184, 166)` | `rgb(20, 184, 166)` | `rgb(20, 184, 166)` | declared | declared-unconsumed | accent palette base | none recorded | none recorded | public generated |
| `token.accent.100` | `--p-accent-100` | scale | — | `color-mix(in srgb, var(--p-accent) 10%, white)` | `color-mix(in srgb, var(--p-accent) 10%, white)` | `color-mix(in srgb, var(--p-accent) 10%, white)` | declared | declared-unconsumed | accent palette shade 100 | none recorded | none recorded | public generated |
| `token.accent.200` | `--p-accent-200` | scale | — | `color-mix(in srgb, var(--p-accent) 20%, white)` | `color-mix(in srgb, var(--p-accent) 20%, white)` | `color-mix(in srgb, var(--p-accent) 20%, white)` | declared | declared-unconsumed | accent palette shade 200 | none recorded | none recorded | public generated |
| `token.accent.300` | `--p-accent-300` | scale | — | `color-mix(in srgb, var(--p-accent) 30%, white)` | `color-mix(in srgb, var(--p-accent) 30%, white)` | `color-mix(in srgb, var(--p-accent) 30%, white)` | declared | declared-unconsumed | accent palette shade 300 | none recorded | none recorded | public generated |
| `token.accent.400` | `--p-accent-400` | scale | — | `color-mix(in srgb, var(--p-accent) 40%, white)` | `color-mix(in srgb, var(--p-accent) 40%, white)` | `color-mix(in srgb, var(--p-accent) 40%, white)` | declared | declared-unconsumed | accent palette shade 400 | none recorded | none recorded | public generated |
| `token.accent.50` | `--p-accent-50` | scale | — | `color-mix(in srgb, var(--p-accent) 5%, white)` | `color-mix(in srgb, var(--p-accent) 5%, white)` | `color-mix(in srgb, var(--p-accent) 5%, white)` | declared | declared-unconsumed | accent palette shade 50 | none recorded | none recorded | public generated |
| `token.accent.500` | `--p-accent-500` | scale | — | `var(--p-accent)` | `var(--p-accent)` | `var(--p-accent)` | declared | declared-unconsumed | accent palette shade 500 | none recorded | none recorded | public generated |
| `token.accent.600` | `--p-accent-600` | scale | — | `color-mix(in srgb, var(--p-accent) 80%, black)` | `color-mix(in srgb, var(--p-accent) 80%, black)` | `color-mix(in srgb, var(--p-accent) 80%, black)` | declared | declared-unconsumed | accent palette shade 600 | none recorded | none recorded | public generated |
| `token.accent.700` | `--p-accent-700` | scale | — | `color-mix(in srgb, var(--p-accent) 70%, black)` | `color-mix(in srgb, var(--p-accent) 70%, black)` | `color-mix(in srgb, var(--p-accent) 70%, black)` | declared | declared-unconsumed | accent palette shade 700 | none recorded | none recorded | public generated |
| `token.accent.800` | `--p-accent-800` | scale | — | `color-mix(in srgb, var(--p-accent) 60%, black)` | `color-mix(in srgb, var(--p-accent) 60%, black)` | `color-mix(in srgb, var(--p-accent) 60%, black)` | declared | declared-unconsumed | accent palette shade 800 | none recorded | none recorded | public generated |
| `token.accent.900` | `--p-accent-900` | scale | — | `color-mix(in srgb, var(--p-accent) 50%, black)` | `color-mix(in srgb, var(--p-accent) 50%, black)` | `color-mix(in srgb, var(--p-accent) 50%, black)` | declared | declared-unconsumed | accent palette shade 900 | none recorded | none recorded | public generated |
| `token.accent.950` | `--p-accent-950` | scale | — | `color-mix(in srgb, var(--p-accent) 40%, black)` | `color-mix(in srgb, var(--p-accent) 40%, black)` | `color-mix(in srgb, var(--p-accent) 40%, black)` | declared | declared-unconsumed | accent palette shade 950 | none recorded | none recorded | public generated |
| `token.accent.active.color` | `--p-accent-active-color` | alias | — | `var(--p-accent-700)` | `var(--p-accent-700)` | `var(--p-accent-200)` | declared | declared-unconsumed | accent active color | none recorded | none recorded | public generated |
| `token.accent.color` | `--p-accent-color` | alias | — | `var(--p-accent-500)` | `var(--p-accent-500)` | `var(--p-accent-400)` | declared | declared-unconsumed | accent color | none recorded | none recorded | public generated |
| `token.accent.contrast.color` | `--p-accent-contrast-color` | alias | — | `var(--p-surface-0)` | `var(--p-surface-0)` | `var(--p-surface-900)` | declared | declared-unconsumed | accent contrast color | none recorded | none recorded | public generated |
| `token.accent.hover.color` | `--p-accent-hover-color` | alias | — | `var(--p-accent-600)` | `var(--p-accent-600)` | `var(--p-accent-300)` | declared | declared-unconsumed | accent hover color | none recorded | none recorded | public generated |
| `token.content.background` | `--p-content-background` | semantic | — | `var(--p-surface-0)` | `var(--p-surface-0)` | `var(--p-surface-900)` | declared | declared-unconsumed | content background | none recorded | none recorded | public generated |
| `token.content.border.color` | `--p-content-border-color` | semantic | — | `var(--p-surface-200)` | `var(--p-surface-200)` | `var(--p-surface-700)` | declared | declared-unconsumed | content border color | none recorded | none recorded | public generated |
| `token.content.border.radius` | `--p-content-border-radius` | semantic | — | `6px` | `6px` | `6px` | declared | declared-unconsumed | content border radius | none recorded | none recorded | public generated |
| `token.content.hover.background` | `--p-content-hover-background` | semantic | — | `var(--p-surface-100)` | `var(--p-surface-100)` | `var(--p-surface-800)` | declared | declared-unconsumed | content hover background | none recorded | none recorded | public generated |
| `token.content.hover.color` | `--p-content-hover-color` | semantic | — | `var(--p-surface-800)` | `var(--p-surface-800)` | `var(--p-surface-0)` | declared | declared-unconsumed | content hover color | none recorded | none recorded | public generated |
| `token.danger` | `--p-danger` | base | — | `rgb(239, 68, 68)` | `rgb(239, 68, 68)` | `rgb(239, 68, 68)` | declared | declared-unconsumed | danger palette base | none recorded | none recorded | public generated |
| `token.danger.100` | `--p-danger-100` | scale | — | `color-mix(in srgb, var(--p-danger) 10%, white)` | `color-mix(in srgb, var(--p-danger) 10%, white)` | `color-mix(in srgb, var(--p-danger) 10%, white)` | declared | inherited | danger palette shade 100 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.danger.200` | `--p-danger-200` | scale | — | `color-mix(in srgb, var(--p-danger) 20%, white)` | `color-mix(in srgb, var(--p-danger) 20%, white)` | `color-mix(in srgb, var(--p-danger) 20%, white)` | declared | inherited | danger palette shade 200 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.danger.300` | `--p-danger-300` | scale | — | `color-mix(in srgb, var(--p-danger) 30%, white)` | `color-mix(in srgb, var(--p-danger) 30%, white)` | `color-mix(in srgb, var(--p-danger) 30%, white)` | declared | inherited | danger palette shade 300 | npm/@wippy-fe--theme/primevue/inputtext.css, npm/@wippy-fe--theme/primevue/toggleswitch.css, npm/@wippy-fe--theme/primevue/button.css | primevue.toggleswitch.portable-appearance:track.invalid-border | public generated |
| `token.danger.400` | `--p-danger-400` | scale | — | `color-mix(in srgb, var(--p-danger) 40%, white)` | `color-mix(in srgb, var(--p-danger) 40%, white)` | `color-mix(in srgb, var(--p-danger) 40%, white)` | declared | inherited | danger palette shade 400 | npm/@wippy-fe--theme/primevue/inputtext.css, npm/@wippy-fe--theme/primevue/toggleswitch.css, npm/@wippy-fe--theme/primevue/button.css | primevue.toggleswitch.portable-appearance:track.invalid-border | public generated |
| `token.danger.50` | `--p-danger-50` | scale | — | `color-mix(in srgb, var(--p-danger) 5%, white)` | `color-mix(in srgb, var(--p-danger) 5%, white)` | `color-mix(in srgb, var(--p-danger) 5%, white)` | declared | inherited | danger palette shade 50 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.danger.500` | `--p-danger-500` | scale | — | `var(--p-danger)` | `var(--p-danger)` | `var(--p-danger)` | declared | inherited | danger palette shade 500 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.danger.600` | `--p-danger-600` | scale | — | `color-mix(in srgb, var(--p-danger) 80%, black)` | `color-mix(in srgb, var(--p-danger) 80%, black)` | `color-mix(in srgb, var(--p-danger) 80%, black)` | declared | inherited | danger palette shade 600 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.danger.700` | `--p-danger-700` | scale | — | `color-mix(in srgb, var(--p-danger) 70%, black)` | `color-mix(in srgb, var(--p-danger) 70%, black)` | `color-mix(in srgb, var(--p-danger) 70%, black)` | declared | inherited | danger palette shade 700 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.danger.800` | `--p-danger-800` | scale | — | `color-mix(in srgb, var(--p-danger) 60%, black)` | `color-mix(in srgb, var(--p-danger) 60%, black)` | `color-mix(in srgb, var(--p-danger) 60%, black)` | declared | declared-unconsumed | danger palette shade 800 | none recorded | none recorded | public generated |
| `token.danger.900` | `--p-danger-900` | scale | — | `color-mix(in srgb, var(--p-danger) 50%, black)` | `color-mix(in srgb, var(--p-danger) 50%, black)` | `color-mix(in srgb, var(--p-danger) 50%, black)` | declared | declared-unconsumed | danger palette shade 900 | none recorded | none recorded | public generated |
| `token.danger.950` | `--p-danger-950` | scale | — | `color-mix(in srgb, var(--p-danger) 40%, black)` | `color-mix(in srgb, var(--p-danger) 40%, black)` | `color-mix(in srgb, var(--p-danger) 40%, black)` | declared | inherited | danger palette shade 950 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.danger.active.color` | `--p-danger-active-color` | alias | — | `var(--p-danger-700)` | `var(--p-danger-700)` | `var(--p-danger-200)` | declared | declared-unconsumed | danger active color | none recorded | none recorded | public generated |
| `token.danger.color` | `--p-danger-color` | alias | — | `var(--p-danger-500)` | `var(--p-danger-500)` | `var(--p-danger-400)` | declared | declared-unconsumed | danger color | none recorded | none recorded | public generated |
| `token.danger.contrast.color` | `--p-danger-contrast-color` | alias | — | `var(--p-surface-0)` | `var(--p-surface-0)` | `var(--p-surface-900)` | declared | declared-unconsumed | danger contrast color | none recorded | none recorded | public generated |
| `token.danger.hover.color` | `--p-danger-hover-color` | alias | — | `var(--p-danger-600)` | `var(--p-danger-600)` | `var(--p-danger-300)` | declared | declared-unconsumed | danger hover color | none recorded | none recorded | public generated |
| `semantic.focus-ring.color` | `--p-focus-ring-color` | semantic | `focus.ring.color` | `color-mix(in srgb, var(--p-primary-color) 100%, transparent)` | `color-mix(in srgb, var(--p-primary-color) 100%, transparent)` | `color-mix(in srgb, var(--p-primary-color) 100%, transparent)` | inherited | inherited | focus ring color | primevue/toggleswitch.css, npm/@wippy-fe--theme/primevue/toggleswitch.css | primevue.toggleswitch.portable-appearance:focus.color | public reviewed |
| `semantic.focus-ring.offset` | `--p-focus-ring-offset` | semantic | `focus.ring.offset` | `2px` | `2px` | `2px` | inherited | inherited | focus ring offset | primevue/toggleswitch.css, npm/@wippy-fe--theme/primevue/toggleswitch.css | primevue.toggleswitch.portable-appearance:focus.offset | public reviewed |
| `semantic.focus-ring.style` | `--p-focus-ring-style` | semantic | `focus.ring.style` | `solid` | `solid` | `solid` | inherited | inherited | focus ring style | primevue/toggleswitch.css, npm/@wippy-fe--theme/primevue/toggleswitch.css | primevue.toggleswitch.portable-appearance:focus.style | public reviewed |
| `semantic.focus-ring.width` | `--p-focus-ring-width` | semantic | `focus.ring.width` | `1px` | `1px` | `1px` | inherited | inherited | focus ring width | primevue/toggleswitch.css, npm/@wippy-fe--theme/primevue/toggleswitch.css | primevue.toggleswitch.portable-appearance:focus.width | public reviewed |
| `token.font.body.letter.spacing` | `--p-font-body-letter-spacing` | font | — | `normal` | `normal` | `normal` | declared | declared-unconsumed | body typography letter-spacing | none recorded | none recorded | public generated |
| `token.font.body.line.height` | `--p-font-body-line-height` | font | — | `1.5` | `1.5` | `1.5` | declared | declared-unconsumed | body typography line-height | none recorded | none recorded | public generated |
| `token.font.body.scale` | `--p-font-body-scale` | font | — | `1` | `1` | `1` | declared | declared-unconsumed | body typography scale | none recorded | none recorded | public generated |
| `token.font.body.stretch` | `--p-font-body-stretch` | font | — | `normal` | `normal` | `normal` | declared | declared-unconsumed | body typography stretch | none recorded | none recorded | public generated |
| `token.font.body.variation.settings` | `--p-font-body-variation-settings` | font | — | `normal` | `normal` | `normal` | declared | declared-unconsumed | body typography variation-settings | none recorded | none recorded | public generated |
| `token.font.heading.family` | `--p-font-heading-family` | font | — | `var(--v-font-family-head, Arial)` | `var(--v-font-family-head, Arial)` | `var(--v-font-family-head, Arial)` | declared | declared-unconsumed | heading typography family | none recorded | none recorded | public generated |
| `token.font.heading.letter.spacing` | `--p-font-heading-letter-spacing` | font | — | `normal` | `normal` | `normal` | declared | declared-unconsumed | heading typography letter-spacing | none recorded | none recorded | public generated |
| `token.font.heading.line.height` | `--p-font-heading-line-height` | font | — | `1.5` | `1.5` | `1.5` | declared | declared-unconsumed | heading typography line-height | none recorded | none recorded | public generated |
| `token.font.heading.scale` | `--p-font-heading-scale` | font | — | `1` | `1` | `1` | declared | declared-unconsumed | heading typography scale | none recorded | none recorded | public generated |
| `token.font.heading.stretch` | `--p-font-heading-stretch` | font | — | `normal` | `normal` | `normal` | declared | declared-unconsumed | heading typography stretch | none recorded | none recorded | public generated |
| `token.font.heading.variation.settings` | `--p-font-heading-variation-settings` | font | — | `normal` | `normal` | `normal` | declared | declared-unconsumed | heading typography variation-settings | none recorded | none recorded | public generated |
| `token.font.mono.family` | `--p-font-mono-family` | font | — | `ui-monospace` | `ui-monospace` | `ui-monospace` | declared | declared-unconsumed | mono typography family | none recorded | none recorded | public generated |
| `semantic.form-field.border-radius` | `--p-form-field-border-radius` | semantic | `form.field.border.radius` | `0.375rem` | `0.375rem` | `0.375rem` | inherited | inherited | form field border radius | primevue/inputtext.css, npm/@wippy-fe--theme/primevue/inputtext.css | none recorded | public reviewed |
| `semantic.form-field.lg-padding-x` | `--p-form-field-lg-padding-x` | semantic | `form.field.lg.padding.x` | `0.875rem` | `0.875rem` | `0.875rem` | inherited | inherited | form field lg padding x | primevue/inputtext.css, npm/@wippy-fe--theme/primevue/inputtext.css | none recorded | public reviewed |
| `semantic.form-field.lg-padding-y` | `--p-form-field-lg-padding-y` | semantic | `form.field.lg.padding.y` | `0.625rem` | `0.625rem` | `0.625rem` | inherited | inherited | form field lg padding y | primevue/inputtext.css, npm/@wippy-fe--theme/primevue/inputtext.css | none recorded | public reviewed |
| `semantic.form-field.padding-x` | `--p-form-field-padding-x` | semantic | `form.field.padding.x` | `0.75rem` | `0.75rem` | `0.75rem` | inherited | inherited | form field padding x | primevue/inputtext.css, npm/@wippy-fe--theme/primevue/inputtext.css | none recorded | public reviewed |
| `semantic.form-field.padding-y` | `--p-form-field-padding-y` | semantic | `form.field.padding.y` | `0.5rem` | `0.5rem` | `0.5rem` | inherited | inherited | form field padding y | primevue/inputtext.css, npm/@wippy-fe--theme/primevue/inputtext.css | none recorded | public reviewed |
| `semantic.form-field.shadow` | `--p-form-field-shadow` | semantic | `form.field.shadow` | `var(--tw-ring-offset-shadow, 0 0 #0000), var(--tw-ring-shadow, 0 0 #0000), 0 1px 2px 0 rgba(18, 18, 23, 0.05)` | `var(--tw-ring-offset-shadow, 0 0 #0000), var(--tw-ring-shadow, 0 0 #0000), 0 1px 2px 0 rgba(18, 18, 23, 0.05)` | `var(--tw-ring-offset-shadow, 0 0 #0000), var(--tw-ring-shadow, 0 0 #0000), 0 1px 2px 0 rgba(18, 18, 23, 0.05)` | inherited | inherited | form field shadow | primevue/inputtext.css, primevue/toggleswitch.css, npm/@wippy-fe--theme/primevue/inputtext.css, npm/@wippy-fe--theme/primevue/toggleswitch.css | primevue.toggleswitch.portable-appearance:track.shadow | public reviewed |
| `semantic.form-field.sm-padding-x` | `--p-form-field-sm-padding-x` | semantic | `form.field.sm.padding.x` | `0.625rem` | `0.625rem` | `0.625rem` | inherited | inherited | form field sm padding x | primevue/inputtext.css, npm/@wippy-fe--theme/primevue/inputtext.css | none recorded | public reviewed |
| `semantic.form-field.sm-padding-y` | `--p-form-field-sm-padding-y` | semantic | `form.field.sm.padding.y` | `0.375rem` | `0.375rem` | `0.375rem` | inherited | inherited | form field sm padding y | primevue/inputtext.css, npm/@wippy-fe--theme/primevue/inputtext.css | none recorded | public reviewed |
| `semantic.form-field.transition-duration` | `--p-form-field-transition-duration` | semantic | `form.field.transition.duration` | `0.2s` | `0.2s` | `0.2s` | inherited | inherited | form field transition duration | primevue/inputtext.css, npm/@wippy-fe--theme/primevue/inputtext.css | none recorded | public reviewed |
| `token.help` | `--p-help` | base | — | `rgb(168, 85, 247)` | `rgb(168, 85, 247)` | `rgb(168, 85, 247)` | declared | declared-unconsumed | help palette base | none recorded | none recorded | public generated |
| `token.help.100` | `--p-help-100` | scale | — | `color-mix(in srgb, var(--p-help) 10%, white)` | `color-mix(in srgb, var(--p-help) 10%, white)` | `color-mix(in srgb, var(--p-help) 10%, white)` | declared | inherited | help palette shade 100 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.help.200` | `--p-help-200` | scale | — | `color-mix(in srgb, var(--p-help) 20%, white)` | `color-mix(in srgb, var(--p-help) 20%, white)` | `color-mix(in srgb, var(--p-help) 20%, white)` | declared | inherited | help palette shade 200 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.help.300` | `--p-help-300` | scale | — | `color-mix(in srgb, var(--p-help) 30%, white)` | `color-mix(in srgb, var(--p-help) 30%, white)` | `color-mix(in srgb, var(--p-help) 30%, white)` | declared | inherited | help palette shade 300 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.help.400` | `--p-help-400` | scale | — | `color-mix(in srgb, var(--p-help) 40%, white)` | `color-mix(in srgb, var(--p-help) 40%, white)` | `color-mix(in srgb, var(--p-help) 40%, white)` | declared | inherited | help palette shade 400 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.help.50` | `--p-help-50` | scale | — | `color-mix(in srgb, var(--p-help) 5%, white)` | `color-mix(in srgb, var(--p-help) 5%, white)` | `color-mix(in srgb, var(--p-help) 5%, white)` | declared | inherited | help palette shade 50 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.help.500` | `--p-help-500` | scale | — | `var(--p-help)` | `var(--p-help)` | `var(--p-help)` | declared | inherited | help palette shade 500 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.help.600` | `--p-help-600` | scale | — | `color-mix(in srgb, var(--p-help) 80%, black)` | `color-mix(in srgb, var(--p-help) 80%, black)` | `color-mix(in srgb, var(--p-help) 80%, black)` | declared | inherited | help palette shade 600 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.help.700` | `--p-help-700` | scale | — | `color-mix(in srgb, var(--p-help) 70%, black)` | `color-mix(in srgb, var(--p-help) 70%, black)` | `color-mix(in srgb, var(--p-help) 70%, black)` | declared | inherited | help palette shade 700 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.help.800` | `--p-help-800` | scale | — | `color-mix(in srgb, var(--p-help) 60%, black)` | `color-mix(in srgb, var(--p-help) 60%, black)` | `color-mix(in srgb, var(--p-help) 60%, black)` | declared | declared-unconsumed | help palette shade 800 | none recorded | none recorded | public generated |
| `token.help.900` | `--p-help-900` | scale | — | `color-mix(in srgb, var(--p-help) 50%, black)` | `color-mix(in srgb, var(--p-help) 50%, black)` | `color-mix(in srgb, var(--p-help) 50%, black)` | declared | declared-unconsumed | help palette shade 900 | none recorded | none recorded | public generated |
| `token.help.950` | `--p-help-950` | scale | — | `color-mix(in srgb, var(--p-help) 40%, black)` | `color-mix(in srgb, var(--p-help) 40%, black)` | `color-mix(in srgb, var(--p-help) 40%, black)` | declared | inherited | help palette shade 950 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.help.active.color` | `--p-help-active-color` | alias | — | `var(--p-help-700)` | `var(--p-help-700)` | `var(--p-help-200)` | declared | declared-unconsumed | help active color | none recorded | none recorded | public generated |
| `token.help.color` | `--p-help-color` | alias | — | `var(--p-help-500)` | `var(--p-help-500)` | `var(--p-help-400)` | declared | declared-unconsumed | help color | none recorded | none recorded | public generated |
| `token.help.contrast.color` | `--p-help-contrast-color` | alias | — | `var(--p-surface-0)` | `var(--p-surface-0)` | `var(--p-surface-900)` | declared | declared-unconsumed | help contrast color | none recorded | none recorded | public generated |
| `token.help.hover.color` | `--p-help-hover-color` | alias | — | `var(--p-help-600)` | `var(--p-help-600)` | `var(--p-help-300)` | declared | declared-unconsumed | help hover color | none recorded | none recorded | public generated |
| `token.highlight.background` | `--p-highlight-background` | semantic | — | `var(--p-primary-50)` | `var(--p-primary-50)` | `color-mix(in srgb, var(--p-primary-400), transparent 84%)` | declared | declared-unconsumed | highlight background | none recorded | none recorded | public generated |
| `token.highlight.color` | `--p-highlight-color` | semantic | — | `var(--p-primary-700)` | `var(--p-primary-700)` | `rgba(255, 255, 255, 87%)` | declared | declared-unconsumed | highlight color | none recorded | none recorded | public generated |
| `token.highlight.focus.background` | `--p-highlight-focus-background` | semantic | — | `var(--p-primary-100)` | `var(--p-primary-100)` | `color-mix(in srgb, var(--p-primary-400), transparent 76%)` | declared | declared-unconsumed | highlight focus background | none recorded | none recorded | public generated |
| `token.highlight.focus.color` | `--p-highlight-focus-color` | semantic | — | `var(--p-primary-800)` | `var(--p-primary-800)` | `rgba(255, 255, 255, 87%)` | declared | declared-unconsumed | highlight focus color | none recorded | none recorded | public generated |
| `token.info` | `--p-info` | base | — | `rgb(14, 165, 233)` | `rgb(14, 165, 233)` | `rgb(14, 165, 233)` | declared | declared-unconsumed | info palette base | none recorded | none recorded | public generated |
| `token.info.100` | `--p-info-100` | scale | — | `color-mix(in srgb, var(--p-info) 10%, white)` | `color-mix(in srgb, var(--p-info) 10%, white)` | `color-mix(in srgb, var(--p-info) 10%, white)` | declared | inherited | info palette shade 100 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.info.200` | `--p-info-200` | scale | — | `color-mix(in srgb, var(--p-info) 20%, white)` | `color-mix(in srgb, var(--p-info) 20%, white)` | `color-mix(in srgb, var(--p-info) 20%, white)` | declared | inherited | info palette shade 200 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.info.300` | `--p-info-300` | scale | — | `color-mix(in srgb, var(--p-info) 30%, white)` | `color-mix(in srgb, var(--p-info) 30%, white)` | `color-mix(in srgb, var(--p-info) 30%, white)` | declared | inherited | info palette shade 300 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.info.400` | `--p-info-400` | scale | — | `color-mix(in srgb, var(--p-info) 40%, white)` | `color-mix(in srgb, var(--p-info) 40%, white)` | `color-mix(in srgb, var(--p-info) 40%, white)` | declared | inherited | info palette shade 400 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.info.50` | `--p-info-50` | scale | — | `color-mix(in srgb, var(--p-info) 5%, white)` | `color-mix(in srgb, var(--p-info) 5%, white)` | `color-mix(in srgb, var(--p-info) 5%, white)` | declared | inherited | info palette shade 50 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.info.500` | `--p-info-500` | scale | — | `var(--p-info)` | `var(--p-info)` | `var(--p-info)` | declared | inherited | info palette shade 500 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.info.600` | `--p-info-600` | scale | — | `color-mix(in srgb, var(--p-info) 80%, black)` | `color-mix(in srgb, var(--p-info) 80%, black)` | `color-mix(in srgb, var(--p-info) 80%, black)` | declared | inherited | info palette shade 600 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.info.700` | `--p-info-700` | scale | — | `color-mix(in srgb, var(--p-info) 70%, black)` | `color-mix(in srgb, var(--p-info) 70%, black)` | `color-mix(in srgb, var(--p-info) 70%, black)` | declared | inherited | info palette shade 700 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.info.800` | `--p-info-800` | scale | — | `color-mix(in srgb, var(--p-info) 60%, black)` | `color-mix(in srgb, var(--p-info) 60%, black)` | `color-mix(in srgb, var(--p-info) 60%, black)` | declared | declared-unconsumed | info palette shade 800 | none recorded | none recorded | public generated |
| `token.info.900` | `--p-info-900` | scale | — | `color-mix(in srgb, var(--p-info) 50%, black)` | `color-mix(in srgb, var(--p-info) 50%, black)` | `color-mix(in srgb, var(--p-info) 50%, black)` | declared | declared-unconsumed | info palette shade 900 | none recorded | none recorded | public generated |
| `token.info.950` | `--p-info-950` | scale | — | `color-mix(in srgb, var(--p-info) 40%, black)` | `color-mix(in srgb, var(--p-info) 40%, black)` | `color-mix(in srgb, var(--p-info) 40%, black)` | declared | inherited | info palette shade 950 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.info.active.color` | `--p-info-active-color` | alias | — | `var(--p-info-700)` | `var(--p-info-700)` | `var(--p-info-200)` | declared | declared-unconsumed | info active color | none recorded | none recorded | public generated |
| `token.info.color` | `--p-info-color` | alias | — | `var(--p-info-500)` | `var(--p-info-500)` | `var(--p-info-400)` | declared | declared-unconsumed | info color | none recorded | none recorded | public generated |
| `token.info.contrast.color` | `--p-info-contrast-color` | alias | — | `var(--p-surface-0)` | `var(--p-surface-0)` | `var(--p-surface-900)` | declared | declared-unconsumed | info contrast color | none recorded | none recorded | public generated |
| `token.info.hover.color` | `--p-info-hover-color` | alias | — | `var(--p-info-600)` | `var(--p-info-600)` | `var(--p-info-300)` | declared | declared-unconsumed | info hover color | none recorded | none recorded | public generated |
| `token.primary` | `--p-primary` | base | — | `rgb(0, 95, 178)` | `rgb(0, 95, 178)` | `rgb(0, 125, 178)` | declared | declared-unconsumed | primary palette base | none recorded | none recorded | public generated |
| `token.primary.100` | `--p-primary-100` | scale | — | `color-mix(in srgb, var(--p-primary) 10%, white)` | `color-mix(in srgb, var(--p-primary) 10%, white)` | `color-mix(in srgb, var(--p-primary) 10%, white)` | declared | inherited | primary palette shade 100 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.primary.200` | `--p-primary-200` | scale | — | `color-mix(in srgb, var(--p-primary) 20%, white)` | `color-mix(in srgb, var(--p-primary) 20%, white)` | `color-mix(in srgb, var(--p-primary) 20%, white)` | declared | inherited | primary palette shade 200 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.primary.300` | `--p-primary-300` | scale | — | `color-mix(in srgb, var(--p-primary) 30%, white)` | `color-mix(in srgb, var(--p-primary) 30%, white)` | `color-mix(in srgb, var(--p-primary) 30%, white)` | declared | declared-unconsumed | primary palette shade 300 | none recorded | none recorded | public generated |
| `token.primary.400` | `--p-primary-400` | scale | — | `color-mix(in srgb, var(--p-primary) 40%, white)` | `color-mix(in srgb, var(--p-primary) 40%, white)` | `color-mix(in srgb, var(--p-primary) 40%, white)` | declared | declared-unconsumed | primary palette shade 400 | none recorded | none recorded | public generated |
| `token.primary.50` | `--p-primary-50` | scale | — | `color-mix(in srgb, var(--p-primary) 5%, white)` | `color-mix(in srgb, var(--p-primary) 5%, white)` | `color-mix(in srgb, var(--p-primary) 5%, white)` | declared | inherited | primary palette shade 50 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.primary.500` | `--p-primary-500` | scale | — | `var(--p-primary)` | `var(--p-primary)` | `var(--p-primary)` | declared | declared-unconsumed | primary palette shade 500 | none recorded | none recorded | public generated |
| `token.primary.600` | `--p-primary-600` | scale | — | `color-mix(in srgb, var(--p-primary) 80%, black)` | `color-mix(in srgb, var(--p-primary) 80%, black)` | `color-mix(in srgb, var(--p-primary) 80%, black)` | declared | declared-unconsumed | primary palette shade 600 | none recorded | none recorded | public generated |
| `token.primary.700` | `--p-primary-700` | scale | — | `color-mix(in srgb, var(--p-primary) 70%, black)` | `color-mix(in srgb, var(--p-primary) 70%, black)` | `color-mix(in srgb, var(--p-primary) 70%, black)` | declared | inherited | primary palette shade 700 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.primary.800` | `--p-primary-800` | scale | — | `color-mix(in srgb, var(--p-primary) 60%, black)` | `color-mix(in srgb, var(--p-primary) 60%, black)` | `color-mix(in srgb, var(--p-primary) 60%, black)` | declared | declared-unconsumed | primary palette shade 800 | none recorded | none recorded | public generated |
| `token.primary.900` | `--p-primary-900` | scale | — | `color-mix(in srgb, var(--p-primary) 50%, black)` | `color-mix(in srgb, var(--p-primary) 50%, black)` | `color-mix(in srgb, var(--p-primary) 50%, black)` | declared | declared-unconsumed | primary palette shade 900 | none recorded | none recorded | public generated |
| `token.primary.950` | `--p-primary-950` | scale | — | `color-mix(in srgb, var(--p-primary) 40%, black)` | `color-mix(in srgb, var(--p-primary) 40%, black)` | `color-mix(in srgb, var(--p-primary) 40%, black)` | declared | declared-unconsumed | primary palette shade 950 | none recorded | none recorded | public generated |
| `token.primary.active.color` | `--p-primary-active-color` | alias | — | `var(--p-primary-700)` | `var(--p-primary-700)` | `var(--p-primary-200)` | declared | inherited | primary active color | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.primary.color` | `--p-primary-color` | alias | — | `var(--p-primary-500)` | `var(--p-primary-500)` | `var(--p-primary-400)` | declared | inherited | primary color | npm/@wippy-fe--theme/primevue/inputtext.css, npm/@wippy-fe--theme/primevue/toggleswitch.css, npm/@wippy-fe--theme/primevue/button.css | primevue.toggleswitch.portable-appearance:track.selected-background | public generated |
| `token.primary.contrast.color` | `--p-primary-contrast-color` | alias | — | `var(--p-surface-0)` | `var(--p-surface-0)` | `var(--p-surface-900)` | declared | inherited | primary contrast color | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.primary.hover.color` | `--p-primary-hover-color` | alias | — | `var(--p-primary-600)` | `var(--p-primary-600)` | `var(--p-primary-300)` | declared | inherited | primary hover color | npm/@wippy-fe--theme/primevue/toggleswitch.css, npm/@wippy-fe--theme/primevue/button.css | primevue.toggleswitch.portable-appearance:track.selected-hover-background | public generated |
| `token.secondary` | `--p-secondary` | base | — | `#6f7385` | `#6f7385` | `#6f7385` | declared | declared-unconsumed | secondary palette base | none recorded | none recorded | public generated |
| `token.secondary.100` | `--p-secondary-100` | scale | — | `color-mix(in srgb, var(--p-secondary) 10%, white)` | `color-mix(in srgb, var(--p-secondary) 10%, white)` | `color-mix(in srgb, var(--p-secondary) 10%, white)` | declared | declared-unconsumed | secondary palette shade 100 | none recorded | none recorded | public generated |
| `token.secondary.200` | `--p-secondary-200` | scale | — | `color-mix(in srgb, var(--p-secondary) 20%, white)` | `color-mix(in srgb, var(--p-secondary) 20%, white)` | `color-mix(in srgb, var(--p-secondary) 20%, white)` | declared | declared-unconsumed | secondary palette shade 200 | none recorded | none recorded | public generated |
| `token.secondary.300` | `--p-secondary-300` | scale | — | `color-mix(in srgb, var(--p-secondary) 35%, white)` | `color-mix(in srgb, var(--p-secondary) 35%, white)` | `color-mix(in srgb, var(--p-secondary) 35%, white)` | declared | declared-unconsumed | secondary palette shade 300 | none recorded | none recorded | public generated |
| `token.secondary.400` | `--p-secondary-400` | scale | — | `color-mix(in srgb, var(--p-secondary) 65%, white)` | `color-mix(in srgb, var(--p-secondary) 65%, white)` | `color-mix(in srgb, var(--p-secondary) 65%, white)` | declared | declared-unconsumed | secondary palette shade 400 | none recorded | none recorded | public generated |
| `token.secondary.50` | `--p-secondary-50` | scale | — | `color-mix(in srgb, var(--p-secondary) 5%, white)` | `color-mix(in srgb, var(--p-secondary) 5%, white)` | `color-mix(in srgb, var(--p-secondary) 5%, white)` | declared | declared-unconsumed | secondary palette shade 50 | none recorded | none recorded | public generated |
| `token.secondary.500` | `--p-secondary-500` | scale | — | `var(--p-secondary)` | `var(--p-secondary)` | `var(--p-secondary)` | declared | declared-unconsumed | secondary palette shade 500 | none recorded | none recorded | public generated |
| `token.secondary.600` | `--p-secondary-600` | scale | — | `color-mix(in srgb, var(--p-secondary) 80%, black)` | `color-mix(in srgb, var(--p-secondary) 80%, black)` | `color-mix(in srgb, var(--p-secondary) 80%, black)` | declared | declared-unconsumed | secondary palette shade 600 | none recorded | none recorded | public generated |
| `token.secondary.700` | `--p-secondary-700` | scale | — | `color-mix(in srgb, var(--p-secondary) 65%, black)` | `color-mix(in srgb, var(--p-secondary) 65%, black)` | `color-mix(in srgb, var(--p-secondary) 65%, black)` | declared | declared-unconsumed | secondary palette shade 700 | none recorded | none recorded | public generated |
| `token.secondary.800` | `--p-secondary-800` | scale | — | `color-mix(in srgb, var(--p-secondary) 55%, black)` | `color-mix(in srgb, var(--p-secondary) 55%, black)` | `color-mix(in srgb, var(--p-secondary) 55%, black)` | declared | declared-unconsumed | secondary palette shade 800 | none recorded | none recorded | public generated |
| `token.secondary.900` | `--p-secondary-900` | scale | — | `color-mix(in srgb, var(--p-secondary) 50%, black)` | `color-mix(in srgb, var(--p-secondary) 50%, black)` | `color-mix(in srgb, var(--p-secondary) 50%, black)` | declared | declared-unconsumed | secondary palette shade 900 | none recorded | none recorded | public generated |
| `token.secondary.950` | `--p-secondary-950` | scale | — | `color-mix(in srgb, var(--p-secondary) 30%, black)` | `color-mix(in srgb, var(--p-secondary) 30%, black)` | `color-mix(in srgb, var(--p-secondary) 30%, black)` | declared | declared-unconsumed | secondary palette shade 950 | none recorded | none recorded | public generated |
| `token.secondary.active.color` | `--p-secondary-active-color` | alias | — | `var(--p-secondary-700)` | `var(--p-secondary-700)` | `var(--p-secondary-200)` | declared | declared-unconsumed | secondary active color | none recorded | none recorded | public generated |
| `token.secondary.color` | `--p-secondary-color` | alias | — | `var(--p-secondary-500)` | `var(--p-secondary-500)` | `var(--p-secondary-400)` | declared | declared-unconsumed | secondary color | none recorded | none recorded | public generated |
| `token.secondary.contrast.color` | `--p-secondary-contrast-color` | alias | — | `var(--p-surface-0)` | `var(--p-surface-0)` | `var(--p-surface-900)` | declared | declared-unconsumed | secondary contrast color | none recorded | none recorded | public generated |
| `token.secondary.hover.color` | `--p-secondary-hover-color` | alias | — | `var(--p-secondary-600)` | `var(--p-secondary-600)` | `var(--p-secondary-300)` | declared | declared-unconsumed | secondary hover color | none recorded | none recorded | public generated |
| `token.success` | `--p-success` | base | — | `rgb(34, 197, 94)` | `rgb(34, 197, 94)` | `rgb(34, 197, 94)` | declared | declared-unconsumed | success palette base | none recorded | none recorded | public generated |
| `token.success.100` | `--p-success-100` | scale | — | `color-mix(in srgb, var(--p-success) 10%, white)` | `color-mix(in srgb, var(--p-success) 10%, white)` | `color-mix(in srgb, var(--p-success) 10%, white)` | declared | inherited | success palette shade 100 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.success.200` | `--p-success-200` | scale | — | `color-mix(in srgb, var(--p-success) 20%, white)` | `color-mix(in srgb, var(--p-success) 20%, white)` | `color-mix(in srgb, var(--p-success) 20%, white)` | declared | inherited | success palette shade 200 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.success.300` | `--p-success-300` | scale | — | `color-mix(in srgb, var(--p-success) 30%, white)` | `color-mix(in srgb, var(--p-success) 30%, white)` | `color-mix(in srgb, var(--p-success) 30%, white)` | declared | inherited | success palette shade 300 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.success.400` | `--p-success-400` | scale | — | `color-mix(in srgb, var(--p-success) 40%, white)` | `color-mix(in srgb, var(--p-success) 40%, white)` | `color-mix(in srgb, var(--p-success) 40%, white)` | declared | inherited | success palette shade 400 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.success.50` | `--p-success-50` | scale | — | `color-mix(in srgb, var(--p-success) 5%, white)` | `color-mix(in srgb, var(--p-success) 5%, white)` | `color-mix(in srgb, var(--p-success) 5%, white)` | declared | inherited | success palette shade 50 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.success.500` | `--p-success-500` | scale | — | `var(--p-success)` | `var(--p-success)` | `var(--p-success)` | declared | inherited | success palette shade 500 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.success.600` | `--p-success-600` | scale | — | `color-mix(in srgb, var(--p-success) 80%, black)` | `color-mix(in srgb, var(--p-success) 80%, black)` | `color-mix(in srgb, var(--p-success) 80%, black)` | declared | inherited | success palette shade 600 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.success.700` | `--p-success-700` | scale | — | `color-mix(in srgb, var(--p-success) 70%, black)` | `color-mix(in srgb, var(--p-success) 70%, black)` | `color-mix(in srgb, var(--p-success) 70%, black)` | declared | inherited | success palette shade 700 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.success.800` | `--p-success-800` | scale | — | `color-mix(in srgb, var(--p-success) 60%, black)` | `color-mix(in srgb, var(--p-success) 60%, black)` | `color-mix(in srgb, var(--p-success) 60%, black)` | declared | declared-unconsumed | success palette shade 800 | none recorded | none recorded | public generated |
| `token.success.900` | `--p-success-900` | scale | — | `color-mix(in srgb, var(--p-success) 50%, black)` | `color-mix(in srgb, var(--p-success) 50%, black)` | `color-mix(in srgb, var(--p-success) 50%, black)` | declared | declared-unconsumed | success palette shade 900 | none recorded | none recorded | public generated |
| `token.success.950` | `--p-success-950` | scale | — | `color-mix(in srgb, var(--p-success) 40%, black)` | `color-mix(in srgb, var(--p-success) 40%, black)` | `color-mix(in srgb, var(--p-success) 40%, black)` | declared | inherited | success palette shade 950 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.success.active.color` | `--p-success-active-color` | alias | — | `var(--p-success-700)` | `var(--p-success-700)` | `var(--p-success-200)` | declared | declared-unconsumed | success active color | none recorded | none recorded | public generated |
| `token.success.color` | `--p-success-color` | alias | — | `var(--p-success-500)` | `var(--p-success-500)` | `var(--p-success-400)` | declared | declared-unconsumed | success color | none recorded | none recorded | public generated |
| `token.success.contrast.color` | `--p-success-contrast-color` | alias | — | `var(--p-surface-0)` | `var(--p-surface-0)` | `var(--p-surface-900)` | declared | declared-unconsumed | success contrast color | none recorded | none recorded | public generated |
| `token.success.hover.color` | `--p-success-hover-color` | alias | — | `var(--p-success-600)` | `var(--p-success-600)` | `var(--p-success-300)` | declared | declared-unconsumed | success hover color | none recorded | none recorded | public generated |
| `token.surface.0` | `--p-surface-0` | surface | — | `#ffffff` | `#ffffff` | `#fff` | declared | inherited | surface 0 | npm/@wippy-fe--theme/primevue/inputtext.css, npm/@wippy-fe--theme/primevue/toggleswitch.css, npm/@wippy-fe--theme/primevue/button.css | primevue.toggleswitch.portable-appearance:handle.default-background, primevue.toggleswitch.portable-appearance:handle.selected-background | public generated |
| `token.surface.100` | `--p-surface-100` | surface | — | `#f5f5f5` | `#f5f5f5` | `#f4f4f5` | declared | inherited | surface 100 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.surface.200` | `--p-surface-200` | surface | — | `#e5e5e5` | `#e5e5e5` | `#e4e4e7` | declared | inherited | surface 200 | npm/@wippy-fe--theme/primevue/inputtext.css, npm/@wippy-fe--theme/primevue/toggleswitch.css, npm/@wippy-fe--theme/primevue/button.css | primevue.toggleswitch.portable-appearance:track.disabled-background | public generated |
| `token.surface.300` | `--p-surface-300` | surface | — | `#d4d4d4` | `#d4d4d4` | `#d4d4d8` | declared | inherited | surface 300 | npm/@wippy-fe--theme/primevue/inputtext.css, npm/@wippy-fe--theme/primevue/toggleswitch.css, npm/@wippy-fe--theme/primevue/button.css | primevue.toggleswitch.portable-appearance:track.default-background | public generated |
| `token.surface.400` | `--p-surface-400` | surface | — | `#a3a3a3` | `#a3a3a3` | `#a1a1aa` | declared | inherited | surface 400 | npm/@wippy-fe--theme/primevue/inputtext.css, npm/@wippy-fe--theme/primevue/toggleswitch.css, npm/@wippy-fe--theme/primevue/button.css | primevue.toggleswitch.portable-appearance:track.hover-background, primevue.toggleswitch.portable-appearance:handle.default-background | public generated |
| `token.surface.50` | `--p-surface-50` | surface | — | `#fafafa` | `#fafafa` | `#fafafa` | declared | inherited | surface 50 | npm/@wippy-fe--theme/primevue/inputtext.css, npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.surface.500` | `--p-surface-500` | surface | — | `#737373` | `#737373` | `#71717a` | declared | inherited | surface 500 | npm/@wippy-fe--theme/primevue/inputtext.css, npm/@wippy-fe--theme/primevue/toggleswitch.css, npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.surface.600` | `--p-surface-600` | surface | — | `#525252` | `#525252` | `#545250` | declared | inherited | surface 600 | npm/@wippy-fe--theme/primevue/inputtext.css, npm/@wippy-fe--theme/primevue/toggleswitch.css, npm/@wippy-fe--theme/primevue/button.css | primevue.toggleswitch.portable-appearance:track.hover-background, primevue.toggleswitch.portable-appearance:track.disabled-background | public generated |
| `token.surface.700` | `--p-surface-700` | surface | — | `#404040` | `#404040` | `#403e3c` | declared | inherited | surface 700 | npm/@wippy-fe--theme/primevue/inputtext.css, npm/@wippy-fe--theme/primevue/toggleswitch.css, npm/@wippy-fe--theme/primevue/button.css | primevue.toggleswitch.portable-appearance:track.default-background, primevue.toggleswitch.portable-appearance:handle.disabled-background | public generated |
| `token.surface.800` | `--p-surface-800` | surface | — | `#262626` | `#262626` | `#2b2927` | declared | inherited | surface 800 | npm/@wippy-fe--theme/primevue/inputtext.css, npm/@wippy-fe--theme/primevue/toggleswitch.css, npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.surface.850` | `--p-surface-850` | surface | — | `color-mix(in srgb, var(--p-surface-800) 50%, var(--p-surface-900))` | `color-mix(in srgb, var(--p-surface-800) 50%, var(--p-surface-900))` | `color-mix(in srgb, var(--p-surface-800) 50%, var(--p-surface-900))` | declared | declared-unconsumed | surface 850 | none recorded | none recorded | public generated |
| `token.surface.900` | `--p-surface-900` | surface | — | `#171717` | `#171717` | `#1c1a19` | declared | inherited | surface 900 | npm/@wippy-fe--theme/primevue/toggleswitch.css, npm/@wippy-fe--theme/primevue/button.css | primevue.toggleswitch.portable-appearance:handle.selected-background, primevue.toggleswitch.portable-appearance:handle.disabled-background | public generated |
| `token.surface.950` | `--p-surface-950` | surface | — | `#0a0a0a` | `#0a0a0a` | `#0f0e0d` | declared | inherited | surface 950 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.surface.D` | `--p-surface-D` | legacy | — | — | — | `#fff` | declared | legacy | surface D | none recorded | none recorded | legacy |
| `token.text.color` | `--p-text-color` | semantic | — | `var(--p-surface-700)` | `var(--p-surface-700)` | `var(--p-surface-0)` | declared | declared-unconsumed | text color | none recorded | none recorded | public generated |
| `token.text.hover.color` | `--p-text-hover-color` | semantic | — | `var(--p-surface-800)` | `var(--p-surface-800)` | `var(--p-surface-0)` | declared | declared-unconsumed | text hover color | none recorded | none recorded | public generated |
| `token.text.hover.muted.color` | `--p-text-hover-muted-color` | semantic | — | `var(--p-surface-600)` | `var(--p-surface-600)` | `var(--p-surface-300)` | declared | declared-unconsumed | text hover muted color | none recorded | none recorded | public generated |
| `token.text.muted.color` | `--p-text-muted-color` | semantic | — | `var(--p-surface-500)` | `var(--p-surface-500)` | `var(--p-surface-400)` | declared | declared-unconsumed | text muted color | none recorded | none recorded | public generated |
| `component.toggleswitch.border-radius` | `--p-toggleswitch-border-radius` | component | `toggleswitch.border.radius` | `30px` | `30px` | `30px` | inherited | inherited | toggleswitch border radius | primevue/toggleswitch.css, npm/@wippy-fe--theme/primevue/toggleswitch.css | primevue.toggleswitch.portable-appearance:input.border-radius, primevue.toggleswitch.portable-appearance:track.border-radius | public reviewed |
| `component.toggleswitch.border-width` | `--p-toggleswitch-border-width` | component | `toggleswitch.border.width` | `1px` | `1px` | `1px` | inherited | inherited | toggleswitch border width | primevue/toggleswitch.css, npm/@wippy-fe--theme/primevue/toggleswitch.css | primevue.toggleswitch.portable-appearance:track.border-width | public reviewed |
| `component.toggleswitch.gap` | `--p-toggleswitch-gap` | component | `toggleswitch.gap` | `0.25rem` | `0.25rem` | `0.25rem` | inherited | inherited | toggleswitch gap | primevue/toggleswitch.css, npm/@wippy-fe--theme/primevue/toggleswitch.css | primevue.toggleswitch.portable-appearance:handle.offset | public reviewed |
| `component.toggleswitch.handle-border-radius` | `--p-toggleswitch-handle-border-radius` | component | `toggleswitch.handle.border.radius` | `9999px` | `9999px` | `9999px` | inherited | inherited | toggleswitch handle border radius | primevue/toggleswitch.css, npm/@wippy-fe--theme/primevue/toggleswitch.css | primevue.toggleswitch.portable-appearance:handle.border-radius | public reviewed |
| `component.toggleswitch.handle-size` | `--p-toggleswitch-handle-size` | component | `toggleswitch.handle.size` | `1rem` | `1rem` | `1rem` | inherited | inherited | toggleswitch handle size | primevue/toggleswitch.css, npm/@wippy-fe--theme/primevue/toggleswitch.css | primevue.toggleswitch.portable-appearance:handle.width, primevue.toggleswitch.portable-appearance:handle.height | public reviewed |
| `component.toggleswitch.height` | `--p-toggleswitch-height` | component | `toggleswitch.height` | `1.5rem` | `1.5rem` | `1.5rem` | inherited | inherited | toggleswitch height | primevue/toggleswitch.css, npm/@wippy-fe--theme/primevue/toggleswitch.css | primevue.toggleswitch.portable-appearance:root.height | public reviewed |
| `component.toggleswitch.slide-duration` | `--p-toggleswitch-slide-duration` | component | `toggleswitch.slide.duration` | `0.2s` | `0.2s` | `0.2s` | inherited | inherited | toggleswitch slide duration | primevue/toggleswitch.css, npm/@wippy-fe--theme/primevue/toggleswitch.css | primevue.toggleswitch.portable-appearance:handle.transition-duration | public reviewed |
| `component.toggleswitch.transition-duration` | `--p-toggleswitch-transition-duration` | component | `toggleswitch.transition.duration` | `0.2s` | `0.2s` | `0.2s` | inherited | inherited | toggleswitch transition duration | primevue/toggleswitch.css, npm/@wippy-fe--theme/primevue/toggleswitch.css | primevue.toggleswitch.portable-appearance:track.transition-duration | public reviewed |
| `component.toggleswitch.width` | `--p-toggleswitch-width` | component | `toggleswitch.width` | `2.5rem` | `2.5rem` | `2.5rem` | inherited | inherited | toggleswitch width | primevue/toggleswitch.css, npm/@wippy-fe--theme/primevue/toggleswitch.css | primevue.toggleswitch.portable-appearance:root.width | public reviewed |
| `token.warn` | `--p-warn` | base | — | `rgb(249, 115, 22)` | `rgb(249, 115, 22)` | `rgb(249, 115, 22)` | declared | declared-unconsumed | warn palette base | none recorded | none recorded | public generated |
| `token.warn.100` | `--p-warn-100` | scale | — | `color-mix(in srgb, var(--p-warn) 10%, white)` | `color-mix(in srgb, var(--p-warn) 10%, white)` | `color-mix(in srgb, var(--p-warn) 10%, white)` | declared | inherited | warn palette shade 100 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.warn.200` | `--p-warn-200` | scale | — | `color-mix(in srgb, var(--p-warn) 20%, white)` | `color-mix(in srgb, var(--p-warn) 20%, white)` | `color-mix(in srgb, var(--p-warn) 20%, white)` | declared | inherited | warn palette shade 200 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.warn.300` | `--p-warn-300` | scale | — | `color-mix(in srgb, var(--p-warn) 30%, white)` | `color-mix(in srgb, var(--p-warn) 30%, white)` | `color-mix(in srgb, var(--p-warn) 30%, white)` | declared | inherited | warn palette shade 300 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.warn.400` | `--p-warn-400` | scale | — | `color-mix(in srgb, var(--p-warn) 40%, white)` | `color-mix(in srgb, var(--p-warn) 40%, white)` | `color-mix(in srgb, var(--p-warn) 40%, white)` | declared | inherited | warn palette shade 400 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.warn.50` | `--p-warn-50` | scale | — | `color-mix(in srgb, var(--p-warn) 5%, white)` | `color-mix(in srgb, var(--p-warn) 5%, white)` | `color-mix(in srgb, var(--p-warn) 5%, white)` | declared | inherited | warn palette shade 50 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.warn.500` | `--p-warn-500` | scale | — | `var(--p-warn)` | `var(--p-warn)` | `var(--p-warn)` | declared | inherited | warn palette shade 500 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.warn.600` | `--p-warn-600` | scale | — | `color-mix(in srgb, var(--p-warn) 80%, black)` | `color-mix(in srgb, var(--p-warn) 80%, black)` | `color-mix(in srgb, var(--p-warn) 80%, black)` | declared | inherited | warn palette shade 600 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.warn.700` | `--p-warn-700` | scale | — | `color-mix(in srgb, var(--p-warn) 70%, black)` | `color-mix(in srgb, var(--p-warn) 70%, black)` | `color-mix(in srgb, var(--p-warn) 70%, black)` | declared | inherited | warn palette shade 700 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.warn.800` | `--p-warn-800` | scale | — | `color-mix(in srgb, var(--p-warn) 60%, black)` | `color-mix(in srgb, var(--p-warn) 60%, black)` | `color-mix(in srgb, var(--p-warn) 60%, black)` | declared | declared-unconsumed | warn palette shade 800 | none recorded | none recorded | public generated |
| `token.warn.900` | `--p-warn-900` | scale | — | `color-mix(in srgb, var(--p-warn) 50%, black)` | `color-mix(in srgb, var(--p-warn) 50%, black)` | `color-mix(in srgb, var(--p-warn) 50%, black)` | declared | declared-unconsumed | warn palette shade 900 | none recorded | none recorded | public generated |
| `token.warn.950` | `--p-warn-950` | scale | — | `color-mix(in srgb, var(--p-warn) 40%, black)` | `color-mix(in srgb, var(--p-warn) 40%, black)` | `color-mix(in srgb, var(--p-warn) 40%, black)` | declared | inherited | warn palette shade 950 | npm/@wippy-fe--theme/primevue/button.css | none recorded | public generated |
| `token.warn.active.color` | `--p-warn-active-color` | alias | — | `var(--p-warn-700)` | `var(--p-warn-700)` | `var(--p-warn-200)` | declared | declared-unconsumed | warn active color | none recorded | none recorded | public generated |
| `token.warn.color` | `--p-warn-color` | alias | — | `var(--p-warn-500)` | `var(--p-warn-500)` | `var(--p-warn-400)` | declared | declared-unconsumed | warn color | none recorded | none recorded | public generated |
| `token.warn.contrast.color` | `--p-warn-contrast-color` | alias | — | `var(--p-surface-0)` | `var(--p-surface-0)` | `var(--p-surface-900)` | declared | declared-unconsumed | warn contrast color | none recorded | none recorded | public generated |
| `token.warn.hover.color` | `--p-warn-hover-color` | alias | — | `var(--p-warn-600)` | `var(--p-warn-600)` | `var(--p-warn-300)` | declared | declared-unconsumed | warn hover color | none recorded | none recorded | public generated |



#### ToggleSwitch: `primevue.toggleswitch.portable-appearance`


Contract hash: `72ae32064ab3b4f9d79486dfd63362f1a54d973010330c11431c9dde76697344`.

| Property | Part | CSS property | Classification | Published source |
|---|---|---|---|---|
| `root.width` | `root` | `width` | `shared-runtime` | `{"kind":"css-variable","name":"--p-toggleswitch-width"}` |
| `root.height` | `root` | `height` | `shared-runtime` | `{"kind":"css-variable","name":"--p-toggleswitch-height"}` |
| `input.border-radius` | `input` | `border-radius` | `shared-runtime` | `{"kind":"css-variable","name":"--p-toggleswitch-border-radius"}` |
| `track.border-width` | `track` | `border-width` | `shared-runtime` | `{"kind":"css-variable","name":"--p-toggleswitch-border-width"}` |
| `track.border-radius` | `track` | `border-radius` | `shared-runtime` | `{"kind":"css-variable","name":"--p-toggleswitch-border-radius"}` |
| `track.shadow` | `track` | `box-shadow` | `shared-runtime` | `{"kind":"css-variable","name":"--p-form-field-shadow"}` |
| `track.transition-duration` | `track` | `transition-duration` | `shared-runtime` | `{"kind":"css-variable","name":"--p-toggleswitch-transition-duration"}` |
| `handle.width` | `handle` | `width` | `shared-runtime` | `{"kind":"css-variable","name":"--p-toggleswitch-handle-size"}` |
| `handle.height` | `handle` | `height` | `shared-runtime` | `{"kind":"css-variable","name":"--p-toggleswitch-handle-size"}` |
| `handle.offset` | `handle` | `inset-inline-start` | `shared-runtime` | `{"kind":"css-variable","name":"--p-toggleswitch-gap"}` |
| `handle.border-radius` | `handle` | `border-radius` | `shared-runtime` | `{"kind":"css-variable","name":"--p-toggleswitch-handle-border-radius"}` |
| `handle.transition-duration` | `handle` | `transition-duration` | `shared-runtime` | `{"kind":"css-variable","name":"--p-toggleswitch-slide-duration"}` |
| `focus.width` | `track` | `outline-width` | `shared-runtime` | `{"kind":"css-variable","name":"--p-focus-ring-width"}` |
| `focus.style` | `track` | `outline-style` | `shared-runtime` | `{"kind":"css-variable","name":"--p-focus-ring-style"}` |
| `focus.color` | `track` | `outline-color` | `shared-runtime` | `{"kind":"css-variable","name":"--p-focus-ring-color"}` |
| `focus.offset` | `track` | `outline-offset` | `shared-runtime` | `{"kind":"css-variable","name":"--p-focus-ring-offset"}` |
| `track.default-background` | `track` | `background-color` | `shared-runtime` | `{"kind":"tailwind-utilities","names":["bg-surface-300","dark:bg-surface-700"]}` |
| `track.hover-background` | `track` | `background-color` | `shared-runtime` | `{"kind":"tailwind-utilities","names":["bg-surface-400","dark:bg-surface-600"]}` |
| `track.selected-background` | `track` | `background-color` | `shared-runtime` | `{"kind":"tailwind-utilities","names":["bg-primary"]}` |
| `track.selected-hover-background` | `track` | `background-color` | `shared-runtime` | `{"kind":"tailwind-utilities","names":["bg-primary-emphasis"]}` |
| `track.disabled-background` | `track` | `background-color` | `shared-runtime` | `{"kind":"tailwind-utilities","names":["bg-surface-200","dark:bg-surface-600"]}` |
| `track.invalid-border` | `track` | `border-color` | `shared-runtime` | `{"kind":"tailwind-utilities","names":["border-danger-400","dark:border-danger-300"]}` |
| `handle.default-background` | `handle` | `background-color` | `shared-runtime` | `{"kind":"tailwind-utilities","names":["bg-surface-0","dark:bg-surface-400"]}` |
| `handle.selected-background` | `handle` | `background-color` | `shared-runtime` | `{"kind":"tailwind-utilities","names":["bg-surface-0","dark:bg-surface-900"]}` |
| `handle.disabled-background` | `handle` | `background-color` | `shared-runtime` | `{"kind":"tailwind-utilities","names":["bg-surface-700","dark:bg-surface-900"]}` |
| `root.disabled-opacity` | `root` | `opacity` | `platform-invariant` | `{"kind":"tailwind-utility","name":"opacity-100"}` |
| `input.positioning` | `input` | — | `implementation-private` | `not exported` |
| `handle.positioning` | `handle` | — | `implementation-private` | `not exported` |




### First-slice effective contract


| ID | Component | Source location | Selector / PrimeVue path | Property or consumer | Current / emitted value | Runtime dependencies | Semantic review | Mutation | Disposition |
|---|---|---|---|---|---|---|---|---|---|
| `semantic.form-field.padding-x` | form-field | `Aura.semantic.formField.paddingX` | `form.field.padding.x` | `--p-form-field-padding-x` | `0.75rem` | --p-form-field-padding-x | `review-required` | `pending-browser-proof` | `official-semantic-gap-used` |
| `semantic.form-field.padding-y` | form-field | `Aura.semantic.formField.paddingY` | `form.field.padding.y` | `--p-form-field-padding-y` | `0.5rem` | --p-form-field-padding-y | `review-required` | `pending-browser-proof` | `official-semantic-gap-used` |
| `semantic.form-field.sm-padding-x` | form-field | `Aura.semantic.formField.sm.paddingX` | `form.field.sm.padding.x` | `--p-form-field-sm-padding-x` | `0.625rem` | --p-form-field-sm-padding-x | `review-required` | `pending-browser-proof` | `official-semantic-gap-used` |
| `semantic.form-field.sm-padding-y` | form-field | `Aura.semantic.formField.sm.paddingY` | `form.field.sm.padding.y` | `--p-form-field-sm-padding-y` | `0.375rem` | --p-form-field-sm-padding-y | `review-required` | `pending-browser-proof` | `official-semantic-gap-used` |
| `semantic.form-field.lg-padding-x` | form-field | `Aura.semantic.formField.lg.paddingX` | `form.field.lg.padding.x` | `--p-form-field-lg-padding-x` | `0.875rem` | --p-form-field-lg-padding-x | `review-required` | `pending-browser-proof` | `official-semantic-gap-used` |
| `semantic.form-field.lg-padding-y` | form-field | `Aura.semantic.formField.lg.paddingY` | `form.field.lg.padding.y` | `--p-form-field-lg-padding-y` | `0.625rem` | --p-form-field-lg-padding-y | `review-required` | `pending-browser-proof` | `official-semantic-gap-used` |
| `semantic.form-field.border-radius` | form-field | `Aura.semantic.formField.borderRadius` | `form.field.border.radius` | `--p-form-field-border-radius` | `0.375rem` | --p-form-field-border-radius | `review-required` | `pending-browser-proof` | `official-semantic-gap-used` |
| `semantic.form-field.transition-duration` | form-field | `Aura.semantic.formField.transitionDuration` | `form.field.transition.duration` | `--p-form-field-transition-duration` | `0.2s` | --p-form-field-transition-duration | `review-required` | `pending-browser-proof` | `official-semantic-gap-used` |
| `semantic.form-field.shadow` | form-field | `Aura.components.inputtext.root.shadow` | `form.field.shadow` | `--p-form-field-shadow` | `var(--tw-ring-offset-shadow, 0 0 #0000), var(--tw-ring-shadow, 0 0 #0000), 0 1px 2px 0 rgba(18, 18, 23, 0.05)` | --p-form-field-shadow | `review-required` | `pending-browser-proof` | `official-semantic-gap-used` |
| `semantic.focus-ring.width` | focus-ring | `Aura.semantic.focusRing.width` | `focus.ring.width` | `--p-focus-ring-width` | `1px` | --p-focus-ring-width | `review-required` | `pending-browser-proof` | `official-semantic-gap-used` |
| `semantic.focus-ring.style` | focus-ring | `Aura.semantic.focusRing.style` | `focus.ring.style` | `--p-focus-ring-style` | `solid` | --p-focus-ring-style | `review-required` | `pending-browser-proof` | `official-semantic-gap-used` |
| `semantic.focus-ring.color` | focus-ring | `Aura.semantic.focusRing.color` | `focus.ring.color` | `--p-focus-ring-color` | `color-mix(in srgb, var(--p-primary-color) 100%, transparent)` | --p-focus-ring-color | `review-required` | `pending-browser-proof` | `official-semantic-gap-used` |
| `semantic.focus-ring.offset` | focus-ring | `Aura.semantic.focusRing.offset` | `focus.ring.offset` | `--p-focus-ring-offset` | `2px` | --p-focus-ring-offset | `review-required` | `pending-browser-proof` | `official-semantic-gap-used` |
| `component.toggleswitch.width` | toggleswitch | `Aura.components.toggleswitch.root.width` | `toggleswitch.width` | `--p-toggleswitch-width` | `2.5rem` | --p-toggleswitch-width | `review-required` | `pending-browser-proof` | `official-component-gap-used` |
| `component.toggleswitch.height` | toggleswitch | `Aura.components.toggleswitch.root.height` | `toggleswitch.height` | `--p-toggleswitch-height` | `1.5rem` | --p-toggleswitch-height | `review-required` | `pending-browser-proof` | `official-component-gap-used` |
| `component.toggleswitch.border-radius` | toggleswitch | `Aura.components.toggleswitch.root.borderRadius` | `toggleswitch.border.radius` | `--p-toggleswitch-border-radius` | `30px` | --p-toggleswitch-border-radius | `review-required` | `pending-browser-proof` | `official-component-gap-used` |
| `component.toggleswitch.gap` | toggleswitch | `Aura.components.toggleswitch.root.gap` | `toggleswitch.gap` | `--p-toggleswitch-gap` | `0.25rem` | --p-toggleswitch-gap | `review-required` | `pending-browser-proof` | `official-component-gap-used` |
| `component.toggleswitch.border-width` | toggleswitch | `Aura.components.toggleswitch.root.borderWidth` | `toggleswitch.border.width` | `--p-toggleswitch-border-width` | `1px` | --p-toggleswitch-border-width | `review-required` | `pending-browser-proof` | `official-component-gap-used` |
| `component.toggleswitch.transition-duration` | toggleswitch | `Aura.components.toggleswitch.root.transitionDuration` | `toggleswitch.transition.duration` | `--p-toggleswitch-transition-duration` | `0.2s` | --p-toggleswitch-transition-duration | `review-required` | `pending-browser-proof` | `official-component-gap-used` |
| `component.toggleswitch.slide-duration` | toggleswitch | `Aura.components.toggleswitch.root.slideDuration` | `toggleswitch.slide.duration` | `--p-toggleswitch-slide-duration` | `0.2s` | --p-toggleswitch-slide-duration | `review-required` | `pending-browser-proof` | `official-component-gap-used` |
| `component.toggleswitch.handle-size` | toggleswitch | `Aura.components.toggleswitch.handle.size` | `toggleswitch.handle.size` | `--p-toggleswitch-handle-size` | `1rem` | --p-toggleswitch-handle-size | `review-required` | `pending-browser-proof` | `official-component-gap-used` |
| `component.toggleswitch.handle-border-radius` | toggleswitch | `Aura.components.toggleswitch.handle.borderRadius` | `toggleswitch.handle.border.radius` | `--p-toggleswitch-handle-border-radius` | `9999px` | --p-toggleswitch-handle-border-radius | `review-required` | `pending-browser-proof` | `official-component-gap-used` |
| `css.inputtext.0338b40c783c0991` | InputText | `npm/@wippy-fe--theme/primevue/inputtext.css` | `.p-inputtext` | `border-radius` | `var(--p-form-field-border-radius)` | --p-form-field-border-radius | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.inputtext.dc074296c7a8a74f` | InputText | `npm/@wippy-fe--theme/primevue/inputtext.css` | `.p-inputtext` | `padding` | `var(--p-form-field-padding-y) var(--p-form-field-padding-x)` | --p-form-field-padding-y, --p-form-field-padding-x | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.inputtext.4969a70262c72283` | InputText | `npm/@wippy-fe--theme/primevue/inputtext.css` | `.p-inputtext` | `transition-duration` | `var(--p-form-field-transition-duration)` | --p-form-field-transition-duration | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.inputtext.cc6a27fdbcc084fa` | InputText | `npm/@wippy-fe--theme/primevue/inputtext.css` | `.p-inputtext` | `box-shadow` | `var(--p-form-field-shadow)` | --p-form-field-shadow | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.inputtext.dac8bdcbe504c31f` | InputText | `npm/@wippy-fe--theme/primevue/inputtext.css` | `.p-inputtext-sm` | `padding` | `var(--p-form-field-sm-padding-y) var(--p-form-field-sm-padding-x)` | --p-form-field-sm-padding-y, --p-form-field-sm-padding-x | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.inputtext.833b1ed4ceedc781` | InputText | `npm/@wippy-fe--theme/primevue/inputtext.css` | `.p-inputtext-lg` | `padding` | `var(--p-form-field-lg-padding-y) var(--p-form-field-lg-padding-x)` | --p-form-field-lg-padding-y, --p-form-field-lg-padding-x | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.inputtext.ad9be662dc5c59f7` | InputText | `npm/@wippy-fe--theme/primevue/inputtext.css` | `.p-inputtext` | `appearance-none` | `appearance-none` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.inputtext.c4c4dd53df56282c` | InputText | `npm/@wippy-fe--theme/primevue/inputtext.css` | `.p-inputtext` | `border` | `border` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.inputtext.bfff7b6f9de45f83` | InputText | `npm/@wippy-fe--theme/primevue/inputtext.css` | `.p-inputtext` | `border-surface-300` | `border-surface-300` | --p-surface-300 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.inputtext.a4abbb4be67ea036` | InputText | `npm/@wippy-fe--theme/primevue/inputtext.css` | `.p-inputtext` | `dark:border-surface-700` | `dark:border-surface-700` | --p-surface-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.inputtext.254715fa55350d80` | InputText | `npm/@wippy-fe--theme/primevue/inputtext.css` | `.p-inputtext` | `enabled:hover:border-surface-400` | `enabled:hover:border-surface-400` | --p-surface-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.inputtext.14059b7611c899fe` | InputText | `npm/@wippy-fe--theme/primevue/inputtext.css` | `.p-inputtext` | `dark:enabled:hover:border-surface-600` | `dark:enabled:hover:border-surface-600` | --p-surface-600 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.inputtext.ec33a00acdcc9ac1` | InputText | `npm/@wippy-fe--theme/primevue/inputtext.css` | `.p-inputtext` | `enabled:focus:border-primary` | `enabled:focus:border-primary` | --p-primary-color | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.inputtext.3f6116c8bd2680a2` | InputText | `npm/@wippy-fe--theme/primevue/inputtext.css` | `.p-inputtext` | `dark:enabled:focus:border-primary` | `dark:enabled:focus:border-primary` | --p-primary-color | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.inputtext.d200dda0561a26b6` | InputText | `npm/@wippy-fe--theme/primevue/inputtext.css` | `.p-inputtext` | `bg-surface-0` | `bg-surface-0` | --p-surface-0 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.inputtext.2a24e012309228ab` | InputText | `npm/@wippy-fe--theme/primevue/inputtext.css` | `.p-inputtext` | `dark:bg-surface-800` | `dark:bg-surface-800` | --p-surface-800 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.inputtext.92840b4b6b68370b` | InputText | `npm/@wippy-fe--theme/primevue/inputtext.css` | `.p-inputtext` | `text-surface-700` | `text-surface-700` | --p-surface-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.inputtext.e756422eb511878f` | InputText | `npm/@wippy-fe--theme/primevue/inputtext.css` | `.p-inputtext` | `dark:text-surface-0` | `dark:text-surface-0` | --p-surface-0 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.inputtext.404ab7fd158e5b05` | InputText | `npm/@wippy-fe--theme/primevue/inputtext.css` | `.p-inputtext` | `disabled:bg-surface-200` | `disabled:bg-surface-200` | --p-surface-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.inputtext.463133126585f2d7` | InputText | `npm/@wippy-fe--theme/primevue/inputtext.css` | `.p-inputtext` | `disabled:text-surface-500` | `disabled:text-surface-500` | --p-surface-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.inputtext.657bbbf7ab99862a` | InputText | `npm/@wippy-fe--theme/primevue/inputtext.css` | `.p-inputtext` | `dark:disabled:bg-surface-700` | `dark:disabled:bg-surface-700` | --p-surface-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.inputtext.128c3c4fb4d6a248` | InputText | `npm/@wippy-fe--theme/primevue/inputtext.css` | `.p-inputtext` | `dark:disabled:text-surface-400` | `dark:disabled:text-surface-400` | --p-surface-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.inputtext.e9257c3c58db90ea` | InputText | `npm/@wippy-fe--theme/primevue/inputtext.css` | `.p-inputtext` | `disabled:opacity-100` | `disabled:opacity-100` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.inputtext.192a19cb14e3b643` | InputText | `npm/@wippy-fe--theme/primevue/inputtext.css` | `.p-inputtext` | `placeholder:text-surface-500` | `placeholder:text-surface-500` | --p-surface-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.inputtext.a60e4f3de77a1d6e` | InputText | `npm/@wippy-fe--theme/primevue/inputtext.css` | `.p-inputtext` | `dark:placeholder:text-surface-400` | `dark:placeholder:text-surface-400` | --p-surface-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.inputtext.725a91841167d487` | InputText | `npm/@wippy-fe--theme/primevue/inputtext.css` | `.p-inputtext` | `transition-colors` | `transition-colors` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.inputtext.04e89cffc055e3fc` | InputText | `npm/@wippy-fe--theme/primevue/inputtext.css` | `.p-inputtext` | `outline-none` | `outline-none` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.inputtext.ae1368568b06700e` | InputText | `npm/@wippy-fe--theme/primevue/inputtext.css` | `.p-inputtext.p-invalid` | `border-danger-400` | `border-danger-400` | --p-danger-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.inputtext.6e3cb5954502b00f` | InputText | `npm/@wippy-fe--theme/primevue/inputtext.css` | `.p-inputtext.p-invalid` | `dark:border-danger-300` | `dark:border-danger-300` | --p-danger-300 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.inputtext.6339a1c39c65d090` | InputText | `npm/@wippy-fe--theme/primevue/inputtext.css` | `.p-inputtext.p-variant-filled` | `bg-surface-50` | `bg-surface-50` | --p-surface-50 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.inputtext.2a4649365d95d456` | InputText | `npm/@wippy-fe--theme/primevue/inputtext.css` | `.p-inputtext.p-variant-filled` | `dark:bg-surface-800` | `dark:bg-surface-800` | --p-surface-800 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.inputtext.7249b0094b624384` | InputText | `npm/@wippy-fe--theme/primevue/inputtext.css` | `.p-inputtext-sm` | `text-sm` | `text-sm` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.inputtext.d7ec60f52ba9c5ea` | InputText | `npm/@wippy-fe--theme/primevue/inputtext.css` | `.p-inputtext-xs` | `text-xs` | `text-xs` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.inputtext.fda95aa08353e04f` | InputText | `npm/@wippy-fe--theme/primevue/inputtext.css` | `.p-inputtext-xs` | `px-2` | `px-2` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.inputtext.56c0b667256f9aa0` | InputText | `npm/@wippy-fe--theme/primevue/inputtext.css` | `.p-inputtext-xs` | `py-1` | `py-1` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.inputtext.81a5be18e0c3316f` | InputText | `npm/@wippy-fe--theme/primevue/inputtext.css` | `.p-inputtext-lg` | `text-lg` | `text-lg` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.inputtext.9a7d1d25d7107022` | InputText | `npm/@wippy-fe--theme/primevue/inputtext.css` | `.p-inputtext-fluid` | `w-full` | `w-full` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.toggleswitch.656e69fe326a1d42` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch` | `width` | `var(--p-toggleswitch-width)` | --p-toggleswitch-width | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.71052d4be813f828` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch` | `height` | `var(--p-toggleswitch-height)` | --p-toggleswitch-height | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.b5a56abcf6f74116` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-input` | `border-radius` | `var(--p-toggleswitch-border-radius)` | --p-toggleswitch-border-radius | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.4b020d70fbbe11b3` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-slider` | `border-style` | `solid` | none | `review-required` | `not-applicable-until-runtime` | `literal-needs-contract` |
| `css.toggleswitch.14523a1d495b4ea8` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-slider` | `border-width` | `var(--p-toggleswitch-border-width)` | --p-toggleswitch-border-width | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.52693e435978c65e` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-slider` | `border-radius` | `var(--p-toggleswitch-border-radius)` | --p-toggleswitch-border-radius | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.dbbd16a658193823` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-slider` | `box-shadow` | `var(--p-form-field-shadow)` | --p-form-field-shadow | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.c9f9806d4764585c` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-slider` | `transition-duration` | `var(--p-toggleswitch-transition-duration)` | --p-toggleswitch-transition-duration | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.553de57c1fbb1f1e` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-handle` | `width` | `var(--p-toggleswitch-handle-size)` | --p-toggleswitch-handle-size | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.8299a1b337b2470d` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-handle` | `height` | `var(--p-toggleswitch-handle-size)` | --p-toggleswitch-handle-size | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.396ca73da82845ba` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-handle` | `inset-inline-start` | `var(--p-toggleswitch-gap)` | --p-toggleswitch-gap | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.97b0d6e2f6472c2a` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-handle` | `margin-top` | `calc(var(--p-toggleswitch-handle-size) / -2)` | --p-toggleswitch-handle-size | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.8d72021cde5f3f4c` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-handle` | `border-radius` | `var(--p-toggleswitch-handle-border-radius)` | --p-toggleswitch-handle-border-radius | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.4e716f05e5bfafde` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-handle` | `transition-duration` | `var(--p-toggleswitch-slide-duration)` | --p-toggleswitch-slide-duration | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.127e7c1fd409ec44` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch.p-toggleswitch-checked .p-toggleswitch-handle` | `inset-inline-start` | `calc(var(--p-toggleswitch-width) - var(--p-toggleswitch-handle-size) - var(--p-toggleswitch-gap))` | --p-toggleswitch-width, --p-toggleswitch-handle-size, --p-toggleswitch-gap | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.4c03ecb90feb1072` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch:not(.p-disabled):has(.p-toggleswitch-input:focus-visible) .p-toggleswitch-slider` | `outline-width` | `var(--p-focus-ring-width)` | --p-focus-ring-width | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.bed9e2d0d2e05800` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch:not(.p-disabled):has(.p-toggleswitch-input:focus-visible) .p-toggleswitch-slider` | `outline-style` | `var(--p-focus-ring-style)` | --p-focus-ring-style | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.038877b587b692af` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch:not(.p-disabled):has(.p-toggleswitch-input:focus-visible) .p-toggleswitch-slider` | `outline-color` | `var(--p-focus-ring-color)` | --p-focus-ring-color | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.5a2a9b62a1816733` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch:not(.p-disabled):has(.p-toggleswitch-input:focus-visible) .p-toggleswitch-slider` | `outline-offset` | `var(--p-focus-ring-offset)` | --p-focus-ring-offset | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.f2a4049beaa2d841` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch` | `inline-block` | `inline-block` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.toggleswitch.f2f747f863ddb7d2` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-input` | `cursor-pointer` | `cursor-pointer` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.toggleswitch.2d1cd11f3aaba99f` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-input` | `disabled:cursor-default` | `disabled:cursor-default` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.toggleswitch.79ed37abe03c3255` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-input` | `appearance-none` | `appearance-none` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.toggleswitch.d60e61ed78b41674` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-input` | `absolute` | `absolute` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.toggleswitch.f2f8be977deb3acb` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-input` | `top-0` | `top-0` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.toggleswitch.a84f8beeae1f666b` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-input` | `start-0` | `start-0` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.toggleswitch.784663883eea65bb` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-input` | `w-full` | `w-full` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.toggleswitch.d7970b2a0571efa4` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-input` | `h-full` | `h-full` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.toggleswitch.f3d6bf37da9c55a6` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-input` | `m-0` | `m-0` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.toggleswitch.f9d53893eab3088c` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-input` | `p-0` | `p-0` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.toggleswitch.20b496527edd35b3` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-input` | `opacity-0` | `opacity-0` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.toggleswitch.b0b3447a71a4133a` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-input` | `z-10` | `z-10` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.toggleswitch.bfec9d5f99a4e129` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-slider` | `inline-block` | `inline-block` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.toggleswitch.73abe04d540d23de` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-slider` | `w-full` | `w-full` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.toggleswitch.85aabd0eb8483d6a` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-slider` | `h-full` | `h-full` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.toggleswitch.c41b5547d4389702` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-slider` | `bg-surface-300` | `bg-surface-300` | --p-surface-300 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.b14b8ccf5347e54c` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-slider` | `dark:bg-surface-700` | `dark:bg-surface-700` | --p-surface-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.962489b4a13cd1c1` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-slider` | `border-transparent` | `border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.toggleswitch.c9cb3bc4f6670cbe` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-slider` | `transition-colors` | `transition-colors` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.toggleswitch.b56a3027b4e386ad` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-handle` | `absolute` | `absolute` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.toggleswitch.f0c52fe4850a5b6a` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-handle` | `top-1/2` | `top-1/2` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.toggleswitch.93e469e2ced72c1d` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-handle` | `flex` | `flex` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.toggleswitch.4b24d12fe90c42a9` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-handle` | `justify-center` | `justify-center` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.toggleswitch.44667274a33c2c8f` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-handle` | `items-center` | `items-center` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.toggleswitch.6aad6ec51e29b1fb` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-handle` | `bg-surface-0` | `bg-surface-0` | --p-surface-0 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.c2ab5622c9bf1be9` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-handle` | `dark:bg-surface-400` | `dark:bg-surface-400` | --p-surface-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.e641ff80c0ae754d` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-handle` | `text-surface-500` | `text-surface-500` | --p-surface-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.3ec6771b6de2e573` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-handle` | `dark:text-surface-900` | `dark:text-surface-900` | --p-surface-900 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.7241897b35caa190` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch-handle` | `transition-[background,color,left]` | `transition-[background,color,left]` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.toggleswitch.d5ae5fa1e38cf094` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch.p-toggleswitch-checked .p-toggleswitch-slider` | `bg-primary` | `bg-primary` | --p-primary-color | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.1312416c0eb05091` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch.p-toggleswitch-checked .p-toggleswitch-handle` | `bg-surface-0` | `bg-surface-0` | --p-surface-0 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.ae17b36cf15367a4` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch.p-toggleswitch-checked .p-toggleswitch-handle` | `dark:bg-surface-900` | `dark:bg-surface-900` | --p-surface-900 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.91553c06844afddf` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch.p-toggleswitch-checked .p-toggleswitch-handle` | `text-primary` | `text-primary` | --p-primary-color | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.43f0cc5465f96d92` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch:not(.p-disabled):has(.p-toggleswitch-input:hover) .p-toggleswitch-slider` | `bg-surface-400` | `bg-surface-400` | --p-surface-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.857916863c939432` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch:not(.p-disabled):has(.p-toggleswitch-input:hover) .p-toggleswitch-slider` | `dark:bg-surface-600` | `dark:bg-surface-600` | --p-surface-600 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.d0f5294cc651d868` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch:not(.p-disabled):has(.p-toggleswitch-input:hover) .p-toggleswitch-handle` | `bg-surface-0` | `bg-surface-0` | --p-surface-0 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.65b15d26f03409b3` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch:not(.p-disabled):has(.p-toggleswitch-input:hover) .p-toggleswitch-handle` | `dark:bg-surface-300` | `dark:bg-surface-300` | --p-surface-300 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.0bf67c72f46ed75a` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch:not(.p-disabled):has(.p-toggleswitch-input:hover) .p-toggleswitch-handle` | `text-surface-700` | `text-surface-700` | --p-surface-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.09be19c35a14359c` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch:not(.p-disabled):has(.p-toggleswitch-input:hover) .p-toggleswitch-handle` | `dark:text-surface-800` | `dark:text-surface-800` | --p-surface-800 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.7525a606b2b5702f` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch:not(.p-disabled):has(.p-toggleswitch-input:hover).p-toggleswitch-checked .p-toggleswitch-slider` | `bg-primary-emphasis` | `bg-primary-emphasis` | --p-primary-hover-color | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.80111ae4ac9803cf` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch:not(.p-disabled):has(.p-toggleswitch-input:hover).p-toggleswitch-checked .p-toggleswitch-handle` | `bg-surface-0` | `bg-surface-0` | --p-surface-0 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.39d5b719acd24010` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch:not(.p-disabled):has(.p-toggleswitch-input:hover).p-toggleswitch-checked .p-toggleswitch-handle` | `dark:bg-surface-900` | `dark:bg-surface-900` | --p-surface-900 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.9d3cc9e93fb6a2d0` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch:not(.p-disabled):has(.p-toggleswitch-input:hover).p-toggleswitch-checked .p-toggleswitch-handle` | `text-primary-emphasis` | `text-primary-emphasis` | --p-primary-hover-color | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.a570d383422bf613` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch.p-invalid > .p-toggleswitch-slider` | `border-danger-400` | `border-danger-400` | --p-danger-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.0daf6c45723d548d` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch.p-invalid > .p-toggleswitch-slider` | `dark:border-danger-300` | `dark:border-danger-300` | --p-danger-300 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.8194547a19e020b0` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch.p-disabled` | `opacity-100` | `opacity-100` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.toggleswitch.a476b310f31f45c0` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch.p-disabled .p-toggleswitch-slider` | `bg-surface-200` | `bg-surface-200` | --p-surface-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.963dff6830b5eae6` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch.p-disabled .p-toggleswitch-slider` | `dark:bg-surface-600` | `dark:bg-surface-600` | --p-surface-600 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.2f6fbe905dd809fb` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch.p-disabled .p-toggleswitch-handle` | `bg-surface-700` | `bg-surface-700` | --p-surface-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.toggleswitch.f0e1040eb978fcca` | ToggleSwitch | `npm/@wippy-fe--theme/primevue/toggleswitch.css` | `.p-toggleswitch.p-disabled .p-toggleswitch-handle` | `dark:bg-surface-900` | `dark:bg-surface-900` | --p-surface-900 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.e300ce98dc285fd9` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button` | `inline-flex` | `inline-flex` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.5bf15b2552a2edbf` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button` | `cursor-pointer` | `cursor-pointer` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.3ac07d3260b7fb30` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button` | `select-none` | `select-none` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.818f48b8506bebd3` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button` | `items-center` | `items-center` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.c2936cab65d7f899` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button` | `justify-center` | `justify-center` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.030fd938a976c3cd` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button` | `overflow-hidden` | `overflow-hidden` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.a022ae3bea2b95f0` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button` | `relative` | `relative` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.fadd4de3ef6e887d` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button` | `bg-primary` | `bg-primary` | --p-primary-color | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.c0831b10d8af7c30` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button` | `enabled:hover:bg-primary-emphasis` | `enabled:hover:bg-primary-emphasis` | --p-primary-hover-color | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.0d03d248eb88dfa4` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button` | `enabled:active:bg-primary-emphasis-alt` | `enabled:active:bg-primary-emphasis-alt` | --p-primary-active-color | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.94e14698a8fb18f8` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button` | `text-primary-contrast` | `text-primary-contrast` | --p-primary-contrast-color | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.9b7c92ff5a9c33ec` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button` | `border` | `border` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.a83ff5c1b7c1f3a6` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button` | `border-primary` | `border-primary` | --p-primary-color | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.9d603ad32c159b20` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button` | `enabled:hover:border-primary-emphasis` | `enabled:hover:border-primary-emphasis` | --p-primary-hover-color | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.4f7400d5e91507c4` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button` | `enabled:active:border-primary-emphasis-alt` | `enabled:active:border-primary-emphasis-alt` | --p-primary-active-color | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.e4fb1f54c028ef53` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button` | `focus-visible:outline` | `focus-visible:outline` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.cf30681ab2a4e5b1` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button` | `focus-visible:outline-1` | `focus-visible:outline-1` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.448ca3e50cc032ff` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button` | `focus-visible:outline-offset-2` | `focus-visible:outline-offset-2` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.e054567a25763e2a` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button` | `focus-visible:outline-primary` | `focus-visible:outline-primary` | --p-primary-color | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.c2c22e6aa6085c9c` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button` | `px-3` | `px-3` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.3ef35aaf4531bbc1` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button` | `py-2` | `py-2` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.a5c3e1af81a444c4` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button` | `transition-colors` | `transition-colors` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.5790d4cf8f91bef3` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button` | `duration-200` | `duration-200` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.e45c9c66eacfb8bc` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button` | `gap-2` | `gap-2` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.a7407cd3bcca8bae` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button` | `rounded-md` | `rounded-md` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.f194c3072ccbb405` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button` | `disabled:cursor-default` | `disabled:cursor-default` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.0401b9b83320acd9` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-icon-right` | `order-1` | `order-1` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.7d78b24bb9a7b581` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-icon-right:dir(rtl)` | `order-[-1]` | `order-[-1]` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.8864aa554eb99006` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button:not(.p-button-vertical) .p-button-icon:not(.p-button-icon-right):dir(rtl)` | `order-1` | `order-1` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.feca0b6ec5e0bfd8` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-icon-bottom` | `order-2` | `order-2` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.51c93a03b10409e8` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-icon-only` | `w-10` | `w-10` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.797533e3a3539c6b` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-icon-only` | `px-0` | `px-0` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.36c942bc4f3e3c85` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-icon-only` | `gap-0` | `gap-0` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.04ad5e27715ad93f` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-icon-only.p-button-rounded` | `rounded-full` | `rounded-full` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.ca3eba5b1a4252b5` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-icon-only.p-button-rounded` | `h-10` | `h-10` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.884c9e1ac687aeeb` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-icon-only .p-button-label` | `invisible` | `invisible` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.f855331872dfec33` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-icon-only .p-button-label` | `w-0` | `w-0` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.485983c01464bf58` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-sm` | `text-sm` | `text-sm` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.da5f8f7d0e1c2045` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-sm` | `px-[0.625rem]` | `px-[0.625rem]` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.c2d1e2ed45f2111d` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-sm` | `py-[0.375rem]` | `py-[0.375rem]` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.c667148b128855c4` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-sm .p-button-icon` | `text-sm` | `text-sm` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.d200107ab7ac9ebb` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-xs` | `text-xs` | `text-xs` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.7ed8d80715623f8c` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-xs` | `px-2` | `px-2` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.ff532345fa5306de` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-xs` | `py-1` | `py-1` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.dede684672037616` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-xs .p-button-icon` | `text-xs` | `text-xs` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.68089bd5763d2183` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-lg` | `text-[1.125rem]` | `text-[1.125rem]` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.4f4254ba1baa6423` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-lg` | `px-[0.875rem]` | `px-[0.875rem]` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.4d85fc817e53a8cd` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-lg` | `py-[0.625rem]` | `py-[0.625rem]` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.6c6d114da1485dc0` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-lg .p-button-icon` | `text-[1.125rem]` | `text-[1.125rem]` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.bc5f37d0a36d9750` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-vertical` | `flex-col` | `flex-col` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.96f2a0193e2cfbd0` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-label` | `font-medium` | `font-medium` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.1d2bf14278f67725` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-fluid` | `w-full` | `w-full` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.305fee3dd7246324` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-fluid.p-button-icon-only` | `w-10` | `w-10` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.d4f1dc235131749d` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button .p-badge` | `min-w-4` | `min-w-4` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.18f873e1c7a4b474` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button .p-badge` | `h-4` | `h-4` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.715be697bfedd115` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button .p-badge` | `leading-4` | `leading-4` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.f3e0d5ff1ccea67b` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-raised` | `shadow-[0_3px_1px_-2px_rgba(0,0,0,0.2),0_2px_2px_0_rgba(0,0,0,0.14),0_1px_5px_0_rgba(0,0,0,0.12)]` | `shadow-[0_3px_1px_-2px_rgba(0,0,0,0.2),0_2px_2px_0_rgba(0,0,0,0.14),0_1px_5px_0_rgba(0,0,0,0.12)]` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.cec5f7d0122056c3` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-rounded` | `rounded-[2rem]` | `rounded-[2rem]` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.f3a0090461379d75` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-secondary` | `bg-surface-100` | `bg-surface-100` | --p-surface-100 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.0e27a7a6310aca35` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-secondary` | `enabled:hover:bg-surface-200` | `enabled:hover:bg-surface-200` | --p-surface-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.7b1c3265f0879876` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-secondary` | `enabled:active:bg-surface-300` | `enabled:active:bg-surface-300` | --p-surface-300 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.52e51466fc464b1d` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-secondary` | `border-surface-100` | `border-surface-100` | --p-surface-100 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.48faf9d73201eb80` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-secondary` | `enabled:hover:border-surface-200` | `enabled:hover:border-surface-200` | --p-surface-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.322827e050542471` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-secondary` | `enabled:active:border-surface-300` | `enabled:active:border-surface-300` | --p-surface-300 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.e48845908fa1db9e` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-secondary` | `text-surface-600` | `text-surface-600` | --p-surface-600 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.dca22c1a884aaf42` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-secondary` | `enabled:hover:text-surface-700` | `enabled:hover:text-surface-700` | --p-surface-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.6ba06a0992d4d147` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-secondary` | `enabled:active:text-surface-800` | `enabled:active:text-surface-800` | --p-surface-800 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.50094ad5980d0b08` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-secondary` | `dark:bg-surface-800` | `dark:bg-surface-800` | --p-surface-800 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.f7aeb4b82dc86138` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-secondary` | `dark:enabled:hover:bg-surface-700` | `dark:enabled:hover:bg-surface-700` | --p-surface-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.ee4fc54fb200e375` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-secondary` | `dark:enabled:active:bg-surface-600` | `dark:enabled:active:bg-surface-600` | --p-surface-600 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.4401d7d7c4c71ed0` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-secondary` | `dark:border-surface-800` | `dark:border-surface-800` | --p-surface-800 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.60cb07a29813654d` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-secondary` | `dark:enabled:hover:border-surface-700` | `dark:enabled:hover:border-surface-700` | --p-surface-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.1b18ed5b75f4250a` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-secondary` | `dark:enabled:active:border-surface-600` | `dark:enabled:active:border-surface-600` | --p-surface-600 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.cfed47226765583e` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-secondary` | `dark:text-surface-300` | `dark:text-surface-300` | --p-surface-300 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.07b9fe86b3014248` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-secondary` | `dark:enabled:hover:text-surface-200` | `dark:enabled:hover:text-surface-200` | --p-surface-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.09355c1c3d8a34dc` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-secondary` | `dark:enabled:active:text-surface-100` | `dark:enabled:active:text-surface-100` | --p-surface-100 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.2a5f185e65084df4` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-secondary` | `focus-visible:outline` | `focus-visible:outline` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.f47e6f1196cfead2` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-secondary` | `focus-visible:outline-1` | `focus-visible:outline-1` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.ef90210ddeb97fc3` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-secondary` | `focus-visible:outline-offset-2` | `focus-visible:outline-offset-2` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.75f764c5278baeda` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-secondary` | `focus-visible:outline-surface-600` | `focus-visible:outline-surface-600` | --p-surface-600 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.95df42173a9000ee` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-secondary` | `dark:focus-visible:outline-surface-300` | `dark:focus-visible:outline-surface-300` | --p-surface-300 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.46411809f629c48a` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-success` | `bg-success-500` | `bg-success-500` | --p-success-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.90254eb20de45d11` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-success` | `enabled:hover:bg-success-600` | `enabled:hover:bg-success-600` | --p-success-600 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.6ab3dcff3271a078` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-success` | `enabled:active:bg-success-700` | `enabled:active:bg-success-700` | --p-success-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.4fc014a2430b933e` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-success` | `border-success-500` | `border-success-500` | --p-success-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.9dc77c6bf87af09b` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-success` | `enabled:hover:border-success-600` | `enabled:hover:border-success-600` | --p-success-600 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.be3ba97a7a30b13a` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-success` | `enabled:active:border-success-700` | `enabled:active:border-success-700` | --p-success-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.f2a8dcc17cb20702` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-success` | `text-white` | `text-white` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.0356873e7f84bd7d` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-success` | `enabled:hover:text-white` | `enabled:hover:text-white` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.06854bc78d52d3d0` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-success` | `enabled:active:text-white` | `enabled:active:text-white` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.ce85cde6efe8dcd0` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-success` | `dark:bg-success-400` | `dark:bg-success-400` | --p-success-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.5e5e265d5798de8e` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-success` | `dark:enabled:hover:bg-success-300` | `dark:enabled:hover:bg-success-300` | --p-success-300 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.fa63ac9ef8cd0f36` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-success` | `dark:enabled:active:bg-success-200` | `dark:enabled:active:bg-success-200` | --p-success-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.03c838e4f2602664` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-success` | `dark:border-success-400` | `dark:border-success-400` | --p-success-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.b356d36fa9e222f1` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-success` | `dark:enabled:hover:border-success-300` | `dark:enabled:hover:border-success-300` | --p-success-300 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.e020f731aa154a43` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-success` | `dark:enabled:active:border-success-200` | `dark:enabled:active:border-success-200` | --p-success-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.2eaf7d4d667f74ac` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-success` | `dark:text-success-950` | `dark:text-success-950` | --p-success-950 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.70dfed9bddfc8faa` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-success` | `dark:enabled:hover:text-success-950` | `dark:enabled:hover:text-success-950` | --p-success-950 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.4437ab4335cfc545` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-success` | `dark:enabled:active:text-success-950` | `dark:enabled:active:text-success-950` | --p-success-950 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.5796bc33d13d24a4` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-success` | `focus-visible:outline` | `focus-visible:outline` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.0af65770fa73b6bd` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-success` | `focus-visible:outline-1` | `focus-visible:outline-1` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.a733f167f02d55e0` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-success` | `focus-visible:outline-offset-2` | `focus-visible:outline-offset-2` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.dea1d4ca9f5d971a` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-success` | `focus-visible:outline-success-500` | `focus-visible:outline-success-500` | --p-success-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.d3c092ee49eacc10` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-success` | `dark:focus-visible:outline-success-400` | `dark:focus-visible:outline-success-400` | --p-success-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.7441d6f5c2242cb7` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-info` | `bg-info-500` | `bg-info-500` | --p-info-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.74f1ef10d3fa509b` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-info` | `enabled:hover:bg-info-600` | `enabled:hover:bg-info-600` | --p-info-600 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.9af98d9b85576299` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-info` | `enabled:active:bg-info-700` | `enabled:active:bg-info-700` | --p-info-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.aa6237734a02e58e` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-info` | `border-info-500` | `border-info-500` | --p-info-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.e4f1c81db29062b6` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-info` | `enabled:hover:border-info-600` | `enabled:hover:border-info-600` | --p-info-600 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.d6e27c4479984919` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-info` | `enabled:active:border-info-700` | `enabled:active:border-info-700` | --p-info-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.0324b00dcce66931` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-info` | `text-white` | `text-white` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.4e02b98372aa885e` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-info` | `enabled:hover:text-white` | `enabled:hover:text-white` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.53d174b2a1aa9f74` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-info` | `enabled:active:text-white` | `enabled:active:text-white` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.e8e5a22909e1d79d` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-info` | `dark:bg-info-400` | `dark:bg-info-400` | --p-info-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.f7395c6ca94f7e98` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-info` | `dark:enabled:hover:bg-info-300` | `dark:enabled:hover:bg-info-300` | --p-info-300 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.e45e562417b73095` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-info` | `dark:enabled:active:bg-info-200` | `dark:enabled:active:bg-info-200` | --p-info-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.95d8191173a424ef` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-info` | `dark:border-info-400` | `dark:border-info-400` | --p-info-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.ab6c18a88fda4e29` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-info` | `dark:enabled:hover:border-info-300` | `dark:enabled:hover:border-info-300` | --p-info-300 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.a196a13f00f123a9` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-info` | `dark:enabled:active:border-info-200` | `dark:enabled:active:border-info-200` | --p-info-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.3adcc0d5a50e628d` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-info` | `dark:text-info-950` | `dark:text-info-950` | --p-info-950 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.c450c90cb2669359` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-info` | `dark:enabled:hover:text-info-950` | `dark:enabled:hover:text-info-950` | --p-info-950 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.077e436bb145ed1a` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-info` | `dark:enabled:active:text-info-950` | `dark:enabled:active:text-info-950` | --p-info-950 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.c20fb8bc3727d629` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-info` | `focus-visible:outline` | `focus-visible:outline` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.1ab6040132bddd7e` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-info` | `focus-visible:outline-1` | `focus-visible:outline-1` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.cd4a2ddb9f4971b9` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-info` | `focus-visible:outline-offset-2` | `focus-visible:outline-offset-2` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.1d5eb780f8fa48c4` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-info` | `focus-visible:outline-info-500` | `focus-visible:outline-info-500` | --p-info-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.6f7c4cc456fbbaaa` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-info` | `dark:focus-visible:outline-info-400` | `dark:focus-visible:outline-info-400` | --p-info-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.56df882ae33d3c15` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-warn` | `bg-warn-500` | `bg-warn-500` | --p-warn-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.b36145aaa3d101dd` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-warn` | `enabled:hover:bg-warn-600` | `enabled:hover:bg-warn-600` | --p-warn-600 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.e5099c8fc11a35f4` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-warn` | `enabled:active:bg-warn-700` | `enabled:active:bg-warn-700` | --p-warn-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.a9a70f159589d4eb` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-warn` | `border-warn-500` | `border-warn-500` | --p-warn-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.dcaf598c6c6c3e03` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-warn` | `enabled:hover:border-warn-600` | `enabled:hover:border-warn-600` | --p-warn-600 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.067ef77a8dadd0fb` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-warn` | `enabled:active:border-warn-700` | `enabled:active:border-warn-700` | --p-warn-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.42a15acb0485b741` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-warn` | `text-white` | `text-white` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.d8467cf09f5c9129` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-warn` | `enabled:hover:text-white` | `enabled:hover:text-white` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.570ab3fd64aafb88` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-warn` | `enabled:active:text-white` | `enabled:active:text-white` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.48df4506ef83041b` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-warn` | `dark:bg-warn-400` | `dark:bg-warn-400` | --p-warn-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.b22d217b3854afa6` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-warn` | `dark:enabled:hover:bg-warn-300` | `dark:enabled:hover:bg-warn-300` | --p-warn-300 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.7ce91612531ecd0a` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-warn` | `dark:enabled:active:bg-warn-200` | `dark:enabled:active:bg-warn-200` | --p-warn-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.c1012a439db61dd7` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-warn` | `dark:border-warn-400` | `dark:border-warn-400` | --p-warn-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.3301d15bc75d6a1e` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-warn` | `dark:enabled:hover:border-warn-300` | `dark:enabled:hover:border-warn-300` | --p-warn-300 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.19e76be8974ee70b` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-warn` | `dark:enabled:active:border-warn-200` | `dark:enabled:active:border-warn-200` | --p-warn-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.349eceed70a91f7a` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-warn` | `dark:text-warn-950` | `dark:text-warn-950` | --p-warn-950 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.e97cebad1bde7c41` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-warn` | `dark:enabled:hover:text-warn-950` | `dark:enabled:hover:text-warn-950` | --p-warn-950 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.7a4cd84b3606871e` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-warn` | `dark:enabled:active:text-warn-950` | `dark:enabled:active:text-warn-950` | --p-warn-950 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.f9155b7f756e4623` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-warn` | `focus-visible:outline` | `focus-visible:outline` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.d17a62535aecb638` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-warn` | `focus-visible:outline-1` | `focus-visible:outline-1` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.07bce4ef9c2c7389` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-warn` | `focus-visible:outline-offset-2` | `focus-visible:outline-offset-2` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.28c78b5d1bf3c5b7` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-warn` | `focus-visible:outline-warn-500` | `focus-visible:outline-warn-500` | --p-warn-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.3d47ec6128035bb1` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-warn` | `dark:focus-visible:outline-warn-400` | `dark:focus-visible:outline-warn-400` | --p-warn-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.aecf0d2c3b87555f` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-help` | `bg-help-500` | `bg-help-500` | --p-help-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.7b34ea86a8c6aa62` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-help` | `enabled:hover:bg-help-600` | `enabled:hover:bg-help-600` | --p-help-600 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.3b59b1860b8cca7c` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-help` | `enabled:active:bg-help-700` | `enabled:active:bg-help-700` | --p-help-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.93e8f9e7aaf0d5c4` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-help` | `border-help-500` | `border-help-500` | --p-help-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.e5a5a8f531bba5c4` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-help` | `enabled:hover:border-help-600` | `enabled:hover:border-help-600` | --p-help-600 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.173fede3c1c46e33` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-help` | `enabled:active:border-help-700` | `enabled:active:border-help-700` | --p-help-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.73592223dc6b014b` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-help` | `text-white` | `text-white` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.418a5e014b9869d3` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-help` | `enabled:hover:text-white` | `enabled:hover:text-white` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.56fb4fb76620d23e` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-help` | `enabled:active:text-white` | `enabled:active:text-white` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.7e700b705ec9f024` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-help` | `dark:bg-help-400` | `dark:bg-help-400` | --p-help-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.663b016f0bdc5fc3` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-help` | `dark:enabled:hover:bg-help-300` | `dark:enabled:hover:bg-help-300` | --p-help-300 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.3ace853e26bfd13f` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-help` | `dark:enabled:active:bg-help-200` | `dark:enabled:active:bg-help-200` | --p-help-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.9baf84680edeb2e5` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-help` | `dark:border-help-400` | `dark:border-help-400` | --p-help-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.4a2a6121ab485bdf` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-help` | `dark:enabled:hover:border-help-300` | `dark:enabled:hover:border-help-300` | --p-help-300 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.3fb7719fa6305b5a` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-help` | `dark:enabled:active:border-help-200` | `dark:enabled:active:border-help-200` | --p-help-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.49cfa25ad2da2186` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-help` | `dark:text-help-950` | `dark:text-help-950` | --p-help-950 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.eafa24e31764769b` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-help` | `dark:enabled:hover:text-help-950` | `dark:enabled:hover:text-help-950` | --p-help-950 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.4752eb09d9587b78` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-help` | `dark:enabled:active:text-help-950` | `dark:enabled:active:text-help-950` | --p-help-950 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.df0483eb05220544` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-help` | `focus-visible:outline` | `focus-visible:outline` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.ff02b2be5ec56891` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-help` | `focus-visible:outline-1` | `focus-visible:outline-1` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.36450eba2b9edfc7` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-help` | `focus-visible:outline-offset-2` | `focus-visible:outline-offset-2` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.1989bba262fd25ff` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-help` | `focus-visible:outline-help-500` | `focus-visible:outline-help-500` | --p-help-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.5ca43554d184d160` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-help` | `dark:focus-visible:outline-help-400` | `dark:focus-visible:outline-help-400` | --p-help-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.3d4da28fce8be822` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-danger` | `bg-danger-500` | `bg-danger-500` | --p-danger-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.211bf376e1030aaf` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-danger` | `enabled:hover:bg-danger-600` | `enabled:hover:bg-danger-600` | --p-danger-600 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.86383fab5663822e` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-danger` | `enabled:active:bg-danger-700` | `enabled:active:bg-danger-700` | --p-danger-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.bc32192628c231ee` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-danger` | `border-danger-500` | `border-danger-500` | --p-danger-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.d632db58dbe9b347` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-danger` | `enabled:hover:border-danger-600` | `enabled:hover:border-danger-600` | --p-danger-600 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.72806725ec659e48` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-danger` | `enabled:active:border-danger-700` | `enabled:active:border-danger-700` | --p-danger-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.7fd9d6ed73b2196e` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-danger` | `text-white` | `text-white` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.45bb8acb9898fa56` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-danger` | `enabled:hover:text-white` | `enabled:hover:text-white` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.cdb13d7f37e04bdc` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-danger` | `enabled:active:text-white` | `enabled:active:text-white` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.9305d329dd5fd07e` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-danger` | `dark:bg-danger-400` | `dark:bg-danger-400` | --p-danger-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.fc3cd55e22b21e95` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-danger` | `dark:enabled:hover:bg-danger-300` | `dark:enabled:hover:bg-danger-300` | --p-danger-300 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.97b01394d0ab7289` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-danger` | `dark:enabled:active:bg-danger-200` | `dark:enabled:active:bg-danger-200` | --p-danger-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.3559ddb3497a1c44` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-danger` | `dark:border-danger-400` | `dark:border-danger-400` | --p-danger-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.cdd8e8c5a01fe43e` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-danger` | `dark:enabled:hover:border-danger-300` | `dark:enabled:hover:border-danger-300` | --p-danger-300 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.d75c909d73e966d6` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-danger` | `dark:enabled:active:border-danger-200` | `dark:enabled:active:border-danger-200` | --p-danger-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.9e15c3d64b829ad3` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-danger` | `dark:text-danger-950` | `dark:text-danger-950` | --p-danger-950 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.82f29917482fa68d` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-danger` | `dark:enabled:hover:text-danger-950` | `dark:enabled:hover:text-danger-950` | --p-danger-950 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.74298b8fe826e208` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-danger` | `dark:enabled:active:text-danger-950` | `dark:enabled:active:text-danger-950` | --p-danger-950 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.e1407c7d6b9331eb` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-danger` | `focus-visible:outline` | `focus-visible:outline` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.2decde517a12e421` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-danger` | `focus-visible:outline-1` | `focus-visible:outline-1` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.4ea8e26dd9987057` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-danger` | `focus-visible:outline-offset-2` | `focus-visible:outline-offset-2` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.92d85a7a7ce018fb` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-danger` | `focus-visible:outline-danger-500` | `focus-visible:outline-danger-500` | --p-danger-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.7820af92338a75c8` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-danger` | `dark:focus-visible:outline-danger-400` | `dark:focus-visible:outline-danger-400` | --p-danger-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.b625ad4aaad582b3` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-contrast` | `bg-surface-950` | `bg-surface-950` | --p-surface-950 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.a7a24485c89809a3` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-contrast` | `enabled:hover:bg-surface-900` | `enabled:hover:bg-surface-900` | --p-surface-900 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.c498ec6805a78aed` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-contrast` | `enabled:active:bg-surface-800` | `enabled:active:bg-surface-800` | --p-surface-800 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.6abf73bfab3b84fc` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-contrast` | `border-surface-950` | `border-surface-950` | --p-surface-950 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.3199179acb414983` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-contrast` | `enabled:hover:border-surface-900` | `enabled:hover:border-surface-900` | --p-surface-900 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.5311e182e2596035` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-contrast` | `enabled:active:border-surface-800` | `enabled:active:border-surface-800` | --p-surface-800 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.2b38b43801182674` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-contrast` | `text-white` | `text-white` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.9dfdad0edd7c123d` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-contrast` | `enabled:hover:text-white` | `enabled:hover:text-white` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.e5ef62d26c4e2fdd` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-contrast` | `enabled:active:text-white` | `enabled:active:text-white` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.e4ff628c6e6e1542` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-contrast` | `dark:bg-surface-0` | `dark:bg-surface-0` | --p-surface-0 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.ee5d7cdbca63502d` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-contrast` | `dark:enabled:hover:bg-surface-100` | `dark:enabled:hover:bg-surface-100` | --p-surface-100 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.377c8faeb93ffeab` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-contrast` | `dark:enabled:active:bg-surface-200` | `dark:enabled:active:bg-surface-200` | --p-surface-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.0c8fdd9c7b9767f6` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-contrast` | `dark:border-surface-100` | `dark:border-surface-100` | --p-surface-100 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.913868f25e1673d7` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-contrast` | `dark:enabled:hover:border-surface-200` | `dark:enabled:hover:border-surface-200` | --p-surface-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.1717e58368d4457e` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-contrast` | `dark:enabled:active:border-surface-300` | `dark:enabled:active:border-surface-300` | --p-surface-300 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.c07b2c1040cc98ad` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-contrast` | `dark:text-surface-950` | `dark:text-surface-950` | --p-surface-950 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.8dbea69ba670b051` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-contrast` | `dark:enabled:hover:text-surface-950` | `dark:enabled:hover:text-surface-950` | --p-surface-950 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.7c7fa25dd15ea042` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-contrast` | `dark:enabled:active:text-surface-950` | `dark:enabled:active:text-surface-950` | --p-surface-950 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.64cf0108ce8e80ac` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-contrast` | `focus-visible:outline` | `focus-visible:outline` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.d238710385d932a2` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-contrast` | `focus-visible:outline-1` | `focus-visible:outline-1` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.b5f408e5542aa6ad` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-contrast` | `focus-visible:outline-offset-2` | `focus-visible:outline-offset-2` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.311a1232b2f6f875` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-contrast` | `focus-visible:outline-surface-950` | `focus-visible:outline-surface-950` | --p-surface-950 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.464b11f82dd27dcd` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-contrast` | `dark:focus-visible:outline-surface-0` | `dark:focus-visible:outline-surface-0` | --p-surface-0 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.60ef5d966c686969` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined` | `bg-transparent` | `bg-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.601b9e32fd290bde` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined` | `enabled:hover:bg-primary-50` | `enabled:hover:bg-primary-50` | --p-primary-50 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.abcccd46b9d0e06f` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined` | `enabled:active:bg-primary-100` | `enabled:active:bg-primary-100` | --p-primary-100 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.70b47fdc74b7bf86` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined` | `border-primary-200` | `border-primary-200` | --p-primary-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.86108eb0f7f50a16` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined` | `enabled:hover:border-primary-200` | `enabled:hover:border-primary-200` | --p-primary-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.511a13b32cb1cd8b` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined` | `enabled:active:border-primary-200` | `enabled:active:border-primary-200` | --p-primary-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.2f7466f8c3b1b083` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined` | `text-primary` | `text-primary` | --p-primary-color | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.b334ff743aefe540` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined` | `enabled:hover:text-primary` | `enabled:hover:text-primary` | --p-primary-color | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.44da83920b57c915` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined` | `enabled:active:text-primary` | `enabled:active:text-primary` | --p-primary-color | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.c873a1638e004c13` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined` | `dark:bg-transparent` | `dark:bg-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.da4b5b3d0cb20dd0` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined` | `dark:enabled:hover:bg-primary/5` | `dark:enabled:hover:bg-primary/5` | --p-primary-color | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.86e39e261463b89c` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined` | `dark:enabled:active:bg-primary/15` | `dark:enabled:active:bg-primary/15` | --p-primary-color | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.adef20def9fef261` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined` | `dark:border-primary-700` | `dark:border-primary-700` | --p-primary-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.db786d3b0c6d9631` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined` | `dark:enabled:hover:border-primary-700` | `dark:enabled:hover:border-primary-700` | --p-primary-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.5b0720ada464a9fb` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined` | `dark:enabled:active:border-primary-700` | `dark:enabled:active:border-primary-700` | --p-primary-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.781e852269e44d56` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined` | `dark:text-primary` | `dark:text-primary` | --p-primary-color | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.73090202dead99f4` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined` | `dark:enabled:hover:text-primary` | `dark:enabled:hover:text-primary` | --p-primary-color | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.d761bb50e4b6198c` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined` | `dark:enabled:active:text-primary` | `dark:enabled:active:text-primary` | --p-primary-color | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.71aaa510dfc6e262` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-secondary` | `bg-transparent` | `bg-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.d726eed4934554a3` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-secondary` | `enabled:hover:bg-surface-50` | `enabled:hover:bg-surface-50` | --p-surface-50 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.3444f5b05c74b4f7` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-secondary` | `enabled:active:bg-surface-100` | `enabled:active:bg-surface-100` | --p-surface-100 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.eb55b5030c39d0fb` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-secondary` | `border-surface-200` | `border-surface-200` | --p-surface-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.0c0b18f4c89447a5` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-secondary` | `enabled:hover:border-surface-200` | `enabled:hover:border-surface-200` | --p-surface-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.4116491fef2ca533` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-secondary` | `enabled:active:border-surface-200` | `enabled:active:border-surface-200` | --p-surface-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.63741901946fa562` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-secondary` | `text-surface-500` | `text-surface-500` | --p-surface-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.e21bde8e4553b562` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-secondary` | `enabled:hover:text-surface-500` | `enabled:hover:text-surface-500` | --p-surface-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.4495691378787ad8` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-secondary` | `enabled:active:text-surface-500` | `enabled:active:text-surface-500` | --p-surface-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.2b1670ee8f674205` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-secondary` | `dark:bg-transparent` | `dark:bg-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.70d85ea86957e299` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-secondary` | `dark:enabled:hover:bg-white/5` | `dark:enabled:hover:bg-white/5` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.becf45fb5f567de1` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-secondary` | `dark:enabled:active:bg-white/15` | `dark:enabled:active:bg-white/15` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.67ed0f0897e05caa` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-secondary` | `dark:border-surface-700` | `dark:border-surface-700` | --p-surface-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.dafcf3c66fb40262` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-secondary` | `dark:enabled:hover:border-surface-700` | `dark:enabled:hover:border-surface-700` | --p-surface-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.3096677e3e043581` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-secondary` | `dark:enabled:active:border-surface-700` | `dark:enabled:active:border-surface-700` | --p-surface-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.3e970b7322324d89` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-secondary` | `dark:text-surface-400` | `dark:text-surface-400` | --p-surface-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.2c50931f95e7da30` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-secondary` | `dark:enabled:hover:text-surface-400` | `dark:enabled:hover:text-surface-400` | --p-surface-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.9810d6ec152c3fd7` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-secondary` | `dark:enabled:active:text-surface-400` | `dark:enabled:active:text-surface-400` | --p-surface-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.a52d50651e3b83a7` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-success` | `bg-transparent` | `bg-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.45e49e82d24e01be` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-success` | `enabled:hover:bg-success-50` | `enabled:hover:bg-success-50` | --p-success-50 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.35c7ae1793521aca` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-success` | `enabled:active:bg-success-100` | `enabled:active:bg-success-100` | --p-success-100 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.cd34c3ccbd9edc5e` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-success` | `border-success-200` | `border-success-200` | --p-success-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.ca8a675c0e973757` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-success` | `enabled:hover:border-success-200` | `enabled:hover:border-success-200` | --p-success-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.ad8e806b69c5c4df` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-success` | `enabled:active:border-success-200` | `enabled:active:border-success-200` | --p-success-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.631679943d6519a5` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-success` | `text-success-500` | `text-success-500` | --p-success-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.34eac8353c22495b` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-success` | `enabled:hover:text-success-500` | `enabled:hover:text-success-500` | --p-success-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.af8c14e34829a7d7` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-success` | `enabled:active:text-success-500` | `enabled:active:text-success-500` | --p-success-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.b588da55bc992897` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-success` | `dark:bg-transparent` | `dark:bg-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.c6ccf6edaf96cbd4` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-success` | `dark:enabled:hover:bg-success-400/5` | `dark:enabled:hover:bg-success-400/5` | --p-success-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.fd29ea30c64c1adf` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-success` | `dark:enabled:active:bg-success-400/15` | `dark:enabled:active:bg-success-400/15` | --p-success-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.668355232736e2af` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-success` | `dark:border-success-700` | `dark:border-success-700` | --p-success-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.c77c8e6a340453ac` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-success` | `dark:enabled:hover:border-success-700` | `dark:enabled:hover:border-success-700` | --p-success-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.4bcde5d9899b4ad9` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-success` | `dark:enabled:active:border-success-700` | `dark:enabled:active:border-success-700` | --p-success-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.62a22382c1e59f82` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-success` | `dark:text-success-400` | `dark:text-success-400` | --p-success-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.234740062c4374b1` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-success` | `dark:enabled:hover:text-success-400` | `dark:enabled:hover:text-success-400` | --p-success-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.43c3bc773c596247` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-success` | `dark:enabled:active:text-success-400` | `dark:enabled:active:text-success-400` | --p-success-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.6ead057b823ff7ad` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-info` | `bg-transparent` | `bg-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.259b19b1fc1f7df6` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-info` | `enabled:hover:bg-info-50` | `enabled:hover:bg-info-50` | --p-info-50 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.411d54e01918c9c8` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-info` | `enabled:active:bg-info-100` | `enabled:active:bg-info-100` | --p-info-100 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.de7a356cd29f8d1e` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-info` | `border-info-200` | `border-info-200` | --p-info-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.6e9ee321d8aacf81` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-info` | `enabled:hover:border-info-200` | `enabled:hover:border-info-200` | --p-info-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.c83b82e97e2902b5` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-info` | `enabled:active:border-info-200` | `enabled:active:border-info-200` | --p-info-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.3d675101ce952f65` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-info` | `text-info-500` | `text-info-500` | --p-info-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.458dd56f8fe17c97` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-info` | `enabled:hover:text-info-500` | `enabled:hover:text-info-500` | --p-info-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.e4137b97676665fb` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-info` | `enabled:active:text-info-500` | `enabled:active:text-info-500` | --p-info-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.651b02ec2bb0a880` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-info` | `dark:bg-transparent` | `dark:bg-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.f0da61e85aff849f` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-info` | `dark:enabled:hover:bg-info-400/5` | `dark:enabled:hover:bg-info-400/5` | --p-info-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.0a1a5e04683f6c08` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-info` | `dark:enabled:active:bg-info-400/15` | `dark:enabled:active:bg-info-400/15` | --p-info-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.4f57bf9085a9b913` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-info` | `dark:border-info-700` | `dark:border-info-700` | --p-info-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.82cf1ed4fe6cd3fe` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-info` | `dark:enabled:hover:border-info-700` | `dark:enabled:hover:border-info-700` | --p-info-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.3087ea4db19fbb75` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-info` | `dark:enabled:active:border-info-700` | `dark:enabled:active:border-info-700` | --p-info-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.dd798534bb0064f5` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-info` | `dark:text-info-400` | `dark:text-info-400` | --p-info-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.be317a93b717b741` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-info` | `dark:enabled:hover:text-info-400` | `dark:enabled:hover:text-info-400` | --p-info-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.14ca2794bbc3a07c` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-info` | `dark:enabled:active:text-info-400` | `dark:enabled:active:text-info-400` | --p-info-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.9a68c6199dc76382` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-warn` | `bg-transparent` | `bg-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.7614db44b7bf90b5` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-warn` | `enabled:hover:bg-warn-50` | `enabled:hover:bg-warn-50` | --p-warn-50 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.ae2ff385dbd43ede` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-warn` | `enabled:active:bg-warn-100` | `enabled:active:bg-warn-100` | --p-warn-100 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.d67a4f8c96fcd0b3` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-warn` | `border-warn-200` | `border-warn-200` | --p-warn-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.a7a9569376060094` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-warn` | `enabled:hover:border-warn-200` | `enabled:hover:border-warn-200` | --p-warn-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.4056b83d1adeb6cc` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-warn` | `enabled:active:border-warn-200` | `enabled:active:border-warn-200` | --p-warn-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.5161345ae56cb998` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-warn` | `text-warn-500` | `text-warn-500` | --p-warn-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.a189ac0aea1c454a` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-warn` | `enabled:hover:text-warn-500` | `enabled:hover:text-warn-500` | --p-warn-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.72c6276be2cbc778` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-warn` | `enabled:active:text-warn-500` | `enabled:active:text-warn-500` | --p-warn-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.4707396c799cc17d` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-warn` | `dark:bg-transparent` | `dark:bg-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.d6654c9c231f1cb8` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-warn` | `dark:enabled:hover:bg-warn-400/5` | `dark:enabled:hover:bg-warn-400/5` | --p-warn-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.8cf4a6b389cb1c83` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-warn` | `dark:enabled:active:bg-warn-400/15` | `dark:enabled:active:bg-warn-400/15` | --p-warn-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.5898dfe5d130300d` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-warn` | `dark:border-warn-700` | `dark:border-warn-700` | --p-warn-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.7ade639a40e73936` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-warn` | `dark:enabled:hover:border-warn-700` | `dark:enabled:hover:border-warn-700` | --p-warn-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.f8477a3482b93616` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-warn` | `dark:enabled:active:border-warn-700` | `dark:enabled:active:border-warn-700` | --p-warn-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.6f65377cf3851931` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-warn` | `dark:text-warn-400` | `dark:text-warn-400` | --p-warn-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.da92e71af375cb52` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-warn` | `dark:enabled:hover:text-warn-400` | `dark:enabled:hover:text-warn-400` | --p-warn-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.24f9137359eefa17` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-warn` | `dark:enabled:active:text-warn-400` | `dark:enabled:active:text-warn-400` | --p-warn-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.0e15038c452b3805` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-help` | `bg-transparent` | `bg-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.45991dcc44aa1da2` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-help` | `enabled:hover:bg-help-50` | `enabled:hover:bg-help-50` | --p-help-50 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.72d717969fbee859` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-help` | `enabled:active:bg-help-100` | `enabled:active:bg-help-100` | --p-help-100 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.0bdbf6ba2a048629` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-help` | `border-help-200` | `border-help-200` | --p-help-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.7121f26cc0667913` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-help` | `enabled:hover:border-help-200` | `enabled:hover:border-help-200` | --p-help-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.7f8ce33914c57a08` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-help` | `enabled:active:border-help-200` | `enabled:active:border-help-200` | --p-help-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.6698fbc9b08aa58d` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-help` | `text-help-500` | `text-help-500` | --p-help-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.5387fc5fbc1f84a2` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-help` | `enabled:hover:text-help-500` | `enabled:hover:text-help-500` | --p-help-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.9be5ca2c4fa4a8b3` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-help` | `enabled:active:text-help-500` | `enabled:active:text-help-500` | --p-help-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.f5ad80cba331950c` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-help` | `dark:bg-transparent` | `dark:bg-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.227cc442db6b3304` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-help` | `dark:enabled:hover:bg-help-400/5` | `dark:enabled:hover:bg-help-400/5` | --p-help-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.5bde4c8cbab95139` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-help` | `dark:enabled:active:bg-help-400/15` | `dark:enabled:active:bg-help-400/15` | --p-help-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.cf23a97d69116a82` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-help` | `dark:border-help-700` | `dark:border-help-700` | --p-help-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.1289d47c13457f54` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-help` | `dark:enabled:hover:border-help-700` | `dark:enabled:hover:border-help-700` | --p-help-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.4245795b76421420` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-help` | `dark:enabled:active:border-help-700` | `dark:enabled:active:border-help-700` | --p-help-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.0d9a71252f03694e` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-help` | `dark:text-help-400` | `dark:text-help-400` | --p-help-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.4d9779f9e03f81fc` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-help` | `dark:enabled:hover:text-help-400` | `dark:enabled:hover:text-help-400` | --p-help-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.7c7e5edba655bd5d` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-help` | `dark:enabled:active:text-help-400` | `dark:enabled:active:text-help-400` | --p-help-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.7773d876138dca9b` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-danger` | `bg-transparent` | `bg-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.8cd45c52725a8321` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-danger` | `enabled:hover:bg-danger-50` | `enabled:hover:bg-danger-50` | --p-danger-50 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.d4cdd302e626dbf1` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-danger` | `enabled:active:bg-danger-100` | `enabled:active:bg-danger-100` | --p-danger-100 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.622ca8add70a9ce8` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-danger` | `border-danger-200` | `border-danger-200` | --p-danger-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.e7154731a21774e2` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-danger` | `enabled:hover:border-danger-200` | `enabled:hover:border-danger-200` | --p-danger-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.c5da6709873c3454` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-danger` | `enabled:active:border-danger-200` | `enabled:active:border-danger-200` | --p-danger-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.f629d5481cb5e938` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-danger` | `text-danger-500` | `text-danger-500` | --p-danger-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.9131dac5a279a066` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-danger` | `enabled:hover:text-danger-500` | `enabled:hover:text-danger-500` | --p-danger-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.7d4d94729df7d0d4` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-danger` | `enabled:active:text-danger-500` | `enabled:active:text-danger-500` | --p-danger-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.d8a8e5333d264844` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-danger` | `dark:bg-transparent` | `dark:bg-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.cbe7206444cb65e8` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-danger` | `dark:enabled:hover:bg-danger-400/5` | `dark:enabled:hover:bg-danger-400/5` | --p-danger-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.d537362683805ca2` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-danger` | `dark:enabled:active:bg-danger-400/15` | `dark:enabled:active:bg-danger-400/15` | --p-danger-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.c73da174b2db4693` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-danger` | `dark:border-danger-700` | `dark:border-danger-700` | --p-danger-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.861ae527be371769` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-danger` | `dark:enabled:hover:border-danger-700` | `dark:enabled:hover:border-danger-700` | --p-danger-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.f250393055ed6aa8` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-danger` | `dark:enabled:active:border-danger-700` | `dark:enabled:active:border-danger-700` | --p-danger-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.a283dbadc0527d02` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-danger` | `dark:text-danger-400` | `dark:text-danger-400` | --p-danger-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.a28bc4c5428c6610` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-danger` | `dark:enabled:hover:text-danger-400` | `dark:enabled:hover:text-danger-400` | --p-danger-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.17ec418cfd80e9c4` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-danger` | `dark:enabled:active:text-danger-400` | `dark:enabled:active:text-danger-400` | --p-danger-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.4b4be45891a8fa06` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-contrast` | `bg-transparent` | `bg-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.7446fdc5fb430b53` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-contrast` | `enabled:hover:bg-surface-50` | `enabled:hover:bg-surface-50` | --p-surface-50 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.b55d8eec7cae6e9d` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-contrast` | `enabled:active:bg-surface-100` | `enabled:active:bg-surface-100` | --p-surface-100 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.36b6b509c2dc26d3` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-contrast` | `border-surface-700` | `border-surface-700` | --p-surface-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.a2687a81f685e5bb` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-contrast` | `enabled:hover:border-surface-700` | `enabled:hover:border-surface-700` | --p-surface-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.d52c09b0ab83dc09` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-contrast` | `enabled:active:border-surface-700` | `enabled:active:border-surface-700` | --p-surface-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.ef80371aca522ad0` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-contrast` | `text-surface-950` | `text-surface-950` | --p-surface-950 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.3f9c97bb42c2b473` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-contrast` | `enabled:hover:text-surface-950` | `enabled:hover:text-surface-950` | --p-surface-950 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.acd35b9e14e5b10e` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-contrast` | `enabled:active:text-surface-950` | `enabled:active:text-surface-950` | --p-surface-950 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.0b82b67226f24206` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-contrast` | `dark:bg-transparent` | `dark:bg-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.7188d2aa0634a83d` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-contrast` | `dark:enabled:hover:bg-surface-800` | `dark:enabled:hover:bg-surface-800` | --p-surface-800 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.8ba56d6cf0bac77c` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-contrast` | `dark:enabled:active:bg-surface-700` | `dark:enabled:active:bg-surface-700` | --p-surface-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.6e14b013484929e2` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-contrast` | `dark:border-surface-500` | `dark:border-surface-500` | --p-surface-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.2dd2ef76f1a403af` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-contrast` | `dark:enabled:hover:border-surface-500` | `dark:enabled:hover:border-surface-500` | --p-surface-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.aaf31698ef68526f` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-contrast` | `dark:enabled:active:border-surface-500` | `dark:enabled:active:border-surface-500` | --p-surface-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.ba4cc8536049a123` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-contrast` | `dark:text-surface-0` | `dark:text-surface-0` | --p-surface-0 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.3a840c71b2fc865a` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-contrast` | `dark:enabled:hover:text-surface-0` | `dark:enabled:hover:text-surface-0` | --p-surface-0 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.2eb69f72a4f99af9` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-contrast` | `dark:enabled:active:text-surface-0` | `dark:enabled:active:text-surface-0` | --p-surface-0 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.dd5bde7faa6018de` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-plain` | `bg-transparent` | `bg-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.7b404aa57b6bc736` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-plain` | `enabled:hover:bg-surface-50` | `enabled:hover:bg-surface-50` | --p-surface-50 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.738af27c1e149422` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-plain` | `enabled:active:bg-surface-100` | `enabled:active:bg-surface-100` | --p-surface-100 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.170e99ca60fed01d` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-plain` | `border-surface-200` | `border-surface-200` | --p-surface-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.48f422aa26a9820a` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-plain` | `enabled:hover:border-surface-200` | `enabled:hover:border-surface-200` | --p-surface-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.aa53e86989207147` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-plain` | `enabled:active:border-surface-200` | `enabled:active:border-surface-200` | --p-surface-200 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.397551171fa6751c` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-plain` | `text-surface-700` | `text-surface-700` | --p-surface-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.e1df09df69742a6d` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-plain` | `enabled:hover:text-surface-700` | `enabled:hover:text-surface-700` | --p-surface-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.e690a8baad252036` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-plain` | `enabled:active:text-surface-700` | `enabled:active:text-surface-700` | --p-surface-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.738dd767034acff5` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-plain` | `dark:bg-transparent` | `dark:bg-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.3ffc0eb8029ba98e` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-plain` | `dark:enabled:hover:bg-surface-800` | `dark:enabled:hover:bg-surface-800` | --p-surface-800 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.98a77938c88346e6` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-plain` | `dark:enabled:active:bg-surface-700` | `dark:enabled:active:bg-surface-700` | --p-surface-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.6c641d811c0069c6` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-plain` | `dark:border-surface-600` | `dark:border-surface-600` | --p-surface-600 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.b83e73c6966d434c` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-plain` | `dark:enabled:hover:border-surface-600` | `dark:enabled:hover:border-surface-600` | --p-surface-600 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.b54c99a4695053b5` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-plain` | `dark:enabled:active:border-surface-600` | `dark:enabled:active:border-surface-600` | --p-surface-600 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.a0cc5d7bdbb469a2` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-plain` | `dark:text-surface-0` | `dark:text-surface-0` | --p-surface-0 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.f3596b0c5cbd75d6` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-plain` | `dark:enabled:hover:text-surface-0` | `dark:enabled:hover:text-surface-0` | --p-surface-0 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.2621a7907deb9763` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-outlined.p-button-plain` | `dark:enabled:active:text-surface-0` | `dark:enabled:active:text-surface-0` | --p-surface-0 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.baadd54d11d4cc9b` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text` | `bg-transparent` | `bg-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.c81682dd3438da41` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text` | `enabled:hover:bg-primary-50` | `enabled:hover:bg-primary-50` | --p-primary-50 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.c7c518951a6a7a8e` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text` | `enabled:active:bg-primary-100` | `enabled:active:bg-primary-100` | --p-primary-100 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.f65a741b5bbf6e31` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text` | `border-transparent` | `border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.db9dff9e5352816f` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text` | `enabled:hover:border-transparent` | `enabled:hover:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.e4149b57859ef736` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text` | `enabled:active:border-transparent` | `enabled:active:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.4e3b309510197c4e` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text` | `text-primary` | `text-primary` | --p-primary-color | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.98c6c4e7362a82a1` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text` | `enabled:hover:text-primary` | `enabled:hover:text-primary` | --p-primary-color | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.7614bccecfac763c` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text` | `enabled:active:text-primary` | `enabled:active:text-primary` | --p-primary-color | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.f9cc45499d63f329` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text` | `dark:bg-transparent` | `dark:bg-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.3b964b15c1d9db35` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text` | `dark:enabled:hover:bg-primary/5` | `dark:enabled:hover:bg-primary/5` | --p-primary-color | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.b77629a57b638b91` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text` | `dark:enabled:active:bg-primary/15` | `dark:enabled:active:bg-primary/15` | --p-primary-color | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.03908df4f9e976c7` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text` | `dark:border-transparent` | `dark:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.70a5ebf1db456cc5` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text` | `dark:enabled:hover:border-transparent` | `dark:enabled:hover:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.07e93bebd3ba5b18` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text` | `dark:enabled:active:border-transparent` | `dark:enabled:active:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.855b0cb84af983e5` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text` | `dark:text-primary` | `dark:text-primary` | --p-primary-color | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.9e790198a1b14b3a` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text` | `dark:enabled:hover:text-primary` | `dark:enabled:hover:text-primary` | --p-primary-color | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.216562148db2315f` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text` | `dark:enabled:active:text-primary` | `dark:enabled:active:text-primary` | --p-primary-color | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.6a78981a558db2cc` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-secondary` | `bg-transparent` | `bg-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.fce3065d96d6decc` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-secondary` | `enabled:hover:bg-surface-50` | `enabled:hover:bg-surface-50` | --p-surface-50 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.67be73ae696f6c37` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-secondary` | `enabled:active:bg-surface-100` | `enabled:active:bg-surface-100` | --p-surface-100 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.486c9fd0e8eaf62c` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-secondary` | `border-transparent` | `border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.d066fb85744f84ea` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-secondary` | `enabled:hover:border-transparent` | `enabled:hover:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.b6150bb05c68b816` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-secondary` | `enabled:active:border-transparent` | `enabled:active:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.528559df63c37cf5` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-secondary` | `text-surface-500` | `text-surface-500` | --p-surface-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.11537afaae75d5d8` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-secondary` | `enabled:hover:text-surface-500` | `enabled:hover:text-surface-500` | --p-surface-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.a646108345e92d92` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-secondary` | `enabled:active:text-surface-500` | `enabled:active:text-surface-500` | --p-surface-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.7548ea1b567a9a69` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-secondary` | `dark:bg-transparent` | `dark:bg-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.f191312f4bad8321` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-secondary` | `dark:enabled:hover:bg-surface-800` | `dark:enabled:hover:bg-surface-800` | --p-surface-800 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.8149db793ec6184e` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-secondary` | `dark:enabled:active:bg-surface-700` | `dark:enabled:active:bg-surface-700` | --p-surface-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.d60209cc7a2e7e9e` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-secondary` | `dark:border-transparent` | `dark:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.c67b9294e11b0680` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-secondary` | `dark:enabled:hover:border-transparent` | `dark:enabled:hover:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.1521fdd1ee7e7eb5` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-secondary` | `dark:enabled:active:border-transparent` | `dark:enabled:active:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.54c5e7e4a25bf052` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-secondary` | `dark:text-surface-400` | `dark:text-surface-400` | --p-surface-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.e1a06758292438fb` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-secondary` | `dark:enabled:hover:text-surface-400` | `dark:enabled:hover:text-surface-400` | --p-surface-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.b46c682be87e5956` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-secondary` | `dark:enabled:active:text-surface-400` | `dark:enabled:active:text-surface-400` | --p-surface-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.836a942ed4ab5dea` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-success` | `bg-transparent` | `bg-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.187e1f5b5074a6f3` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-success` | `enabled:hover:bg-success-50` | `enabled:hover:bg-success-50` | --p-success-50 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.9f09dadf097c0fa1` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-success` | `enabled:active:bg-success-100` | `enabled:active:bg-success-100` | --p-success-100 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.65da302ab3240ed9` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-success` | `border-transparent` | `border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.41dcf91a7ee7b9f8` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-success` | `enabled:hover:border-transparent` | `enabled:hover:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.08a0187076dca37e` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-success` | `enabled:active:border-transparent` | `enabled:active:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.918f0cc2baf32c6d` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-success` | `text-success-500` | `text-success-500` | --p-success-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.857248557daa1324` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-success` | `enabled:hover:text-success-500` | `enabled:hover:text-success-500` | --p-success-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.87b0253764364b0b` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-success` | `enabled:active:text-success-500` | `enabled:active:text-success-500` | --p-success-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.f8cca53d356130dc` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-success` | `dark:bg-transparent` | `dark:bg-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.25ffa2c805f9bdb3` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-success` | `dark:enabled:hover:bg-success-400/5` | `dark:enabled:hover:bg-success-400/5` | --p-success-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.aaa647c056c1d565` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-success` | `dark:enabled:active:bg-success-400/15` | `dark:enabled:active:bg-success-400/15` | --p-success-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.659daae82b23b1b1` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-success` | `dark:border-transparent` | `dark:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.28d2a1b820f5b0a7` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-success` | `dark:enabled:hover:border-transparent` | `dark:enabled:hover:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.b732530e3b9cb30a` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-success` | `dark:enabled:active:border-transparent` | `dark:enabled:active:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.e5c92a5d96c3ace5` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-success` | `dark:text-success-400` | `dark:text-success-400` | --p-success-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.88dbf192ed455e78` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-success` | `dark:enabled:hover:text-success-400` | `dark:enabled:hover:text-success-400` | --p-success-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.12c08be41321fa6f` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-success` | `dark:enabled:active:text-success-400` | `dark:enabled:active:text-success-400` | --p-success-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.36b2b2c3c3e7bb91` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-info` | `bg-transparent` | `bg-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.c2d98946626fdfcd` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-info` | `enabled:hover:bg-info-50` | `enabled:hover:bg-info-50` | --p-info-50 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.5c19b1f63caa2600` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-info` | `enabled:active:bg-info-100` | `enabled:active:bg-info-100` | --p-info-100 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.a72e5987b4d2b904` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-info` | `border-transparent` | `border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.c544af7e6631947f` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-info` | `enabled:hover:border-transparent` | `enabled:hover:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.a042379654b910a5` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-info` | `enabled:active:border-transparent` | `enabled:active:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.687a1db4fd384406` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-info` | `text-info-500` | `text-info-500` | --p-info-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.0852caeeed023347` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-info` | `enabled:hover:text-info-500` | `enabled:hover:text-info-500` | --p-info-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.13f8953e422458c5` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-info` | `enabled:active:text-info-500` | `enabled:active:text-info-500` | --p-info-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.bfb5ea09ed48870e` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-info` | `dark:bg-transparent` | `dark:bg-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.8a73817c610fa9fe` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-info` | `dark:enabled:hover:bg-info-400/5` | `dark:enabled:hover:bg-info-400/5` | --p-info-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.6a34d11aad5f89bb` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-info` | `dark:enabled:active:bg-info-400/15` | `dark:enabled:active:bg-info-400/15` | --p-info-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.52334d4d019dfa6c` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-info` | `dark:border-transparent` | `dark:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.a48323e721afd6a7` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-info` | `dark:enabled:hover:border-transparent` | `dark:enabled:hover:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.d418b2df18267019` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-info` | `dark:enabled:active:border-transparent` | `dark:enabled:active:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.a4550b6642034213` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-info` | `dark:text-info-400` | `dark:text-info-400` | --p-info-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.b862a4de5d07b2e2` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-info` | `dark:enabled:hover:text-info-400` | `dark:enabled:hover:text-info-400` | --p-info-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.7e80d2d919d6e763` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-info` | `dark:enabled:active:text-info-400` | `dark:enabled:active:text-info-400` | --p-info-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.56e049a6dc7a5c9e` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-warn` | `bg-transparent` | `bg-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.cffd90542e7324d6` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-warn` | `enabled:hover:bg-warn-50` | `enabled:hover:bg-warn-50` | --p-warn-50 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.858d8fe1808e5541` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-warn` | `enabled:active:bg-warn-100` | `enabled:active:bg-warn-100` | --p-warn-100 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.19d8c29951ae4b3a` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-warn` | `border-transparent` | `border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.778af78c63afe9e9` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-warn` | `enabled:hover:border-transparent` | `enabled:hover:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.6b65f3dcb5ec6c02` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-warn` | `enabled:active:border-transparent` | `enabled:active:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.f9d0098936c20dcd` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-warn` | `text-warn-500` | `text-warn-500` | --p-warn-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.8bc8c8e0465d92af` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-warn` | `enabled:hover:text-warn-500` | `enabled:hover:text-warn-500` | --p-warn-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.6efc4bec2534b1f1` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-warn` | `enabled:active:text-warn-500` | `enabled:active:text-warn-500` | --p-warn-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.9468e787eccdd337` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-warn` | `dark:bg-transparent` | `dark:bg-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.1729fc6c484b6406` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-warn` | `dark:enabled:hover:bg-warn-400/5` | `dark:enabled:hover:bg-warn-400/5` | --p-warn-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.b371c206fd2644d9` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-warn` | `dark:enabled:active:bg-warn-400/15` | `dark:enabled:active:bg-warn-400/15` | --p-warn-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.8982853a9b994ef9` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-warn` | `dark:border-transparent` | `dark:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.3a409e6d276d430b` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-warn` | `dark:enabled:hover:border-transparent` | `dark:enabled:hover:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.a1fb55ab60e7a516` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-warn` | `dark:enabled:active:border-transparent` | `dark:enabled:active:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.cdfed09d1562b0a4` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-warn` | `dark:text-warn-400` | `dark:text-warn-400` | --p-warn-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.51bda6272908f727` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-warn` | `dark:enabled:hover:text-warn-400` | `dark:enabled:hover:text-warn-400` | --p-warn-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.08f1c8e499095193` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-warn` | `dark:enabled:active:text-warn-400` | `dark:enabled:active:text-warn-400` | --p-warn-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.83a8294f8eee231d` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-help` | `bg-transparent` | `bg-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.402120b28bbf39dc` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-help` | `enabled:hover:bg-help-50` | `enabled:hover:bg-help-50` | --p-help-50 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.501631c207ec94eb` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-help` | `enabled:active:bg-help-100` | `enabled:active:bg-help-100` | --p-help-100 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.6a8bffe2482db6aa` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-help` | `border-transparent` | `border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.73eae9faff1d9355` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-help` | `enabled:hover:border-transparent` | `enabled:hover:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.4eb9127f7d3f5dde` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-help` | `enabled:active:border-transparent` | `enabled:active:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.5aec7153f41d8e35` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-help` | `text-help-500` | `text-help-500` | --p-help-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.6c080da086bdbabb` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-help` | `enabled:hover:text-help-500` | `enabled:hover:text-help-500` | --p-help-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.f5c1f8f22c7eb2bd` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-help` | `enabled:active:text-help-500` | `enabled:active:text-help-500` | --p-help-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.48dca476c6d18904` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-help` | `dark:bg-transparent` | `dark:bg-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.6cbd1aada9144b47` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-help` | `dark:enabled:hover:bg-help-400/5` | `dark:enabled:hover:bg-help-400/5` | --p-help-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.9051bf9b4177f62b` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-help` | `dark:enabled:active:bg-help-400/15` | `dark:enabled:active:bg-help-400/15` | --p-help-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.8356bfae3250ec46` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-help` | `dark:border-transparent` | `dark:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.6093e955e29ad13e` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-help` | `dark:enabled:hover:border-transparent` | `dark:enabled:hover:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.a5e73572d40fb2aa` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-help` | `dark:enabled:active:border-transparent` | `dark:enabled:active:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.b9cc407df026d081` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-help` | `dark:text-help-400` | `dark:text-help-400` | --p-help-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.a2448c6a13f336c2` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-help` | `dark:enabled:hover:text-help-400` | `dark:enabled:hover:text-help-400` | --p-help-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.bc0adb50638cfffb` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-help` | `dark:enabled:active:text-help-400` | `dark:enabled:active:text-help-400` | --p-help-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.e0e2a30f7e4a3997` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-danger` | `bg-transparent` | `bg-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.6aa1a8f2bac12311` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-danger` | `enabled:hover:bg-danger-50` | `enabled:hover:bg-danger-50` | --p-danger-50 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.7095cd1e2f88fe91` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-danger` | `enabled:active:bg-danger-100` | `enabled:active:bg-danger-100` | --p-danger-100 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.4f24cabd482b616d` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-danger` | `border-transparent` | `border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.350a59f5f1881c06` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-danger` | `enabled:hover:border-transparent` | `enabled:hover:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.af51157b404ef156` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-danger` | `enabled:active:border-transparent` | `enabled:active:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.b1410ae84ca361cf` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-danger` | `text-danger-500` | `text-danger-500` | --p-danger-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.0166db4158cda84b` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-danger` | `enabled:hover:text-danger-500` | `enabled:hover:text-danger-500` | --p-danger-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.4ecaa3009893aa93` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-danger` | `enabled:active:text-danger-500` | `enabled:active:text-danger-500` | --p-danger-500 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.a41d9fe4721a1ecc` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-danger` | `dark:bg-transparent` | `dark:bg-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.e84382a19b673132` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-danger` | `dark:enabled:hover:bg-danger-400/5` | `dark:enabled:hover:bg-danger-400/5` | --p-danger-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.0c413b6d1c51f1ea` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-danger` | `dark:enabled:active:bg-danger-400/15` | `dark:enabled:active:bg-danger-400/15` | --p-danger-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.0171b67383eb2854` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-danger` | `dark:border-transparent` | `dark:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.b46303484489b659` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-danger` | `dark:enabled:hover:border-transparent` | `dark:enabled:hover:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.d54b50f1fb8ac799` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-danger` | `dark:enabled:active:border-transparent` | `dark:enabled:active:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.2a05fc5f1f7c88c0` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-danger` | `dark:text-danger-400` | `dark:text-danger-400` | --p-danger-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.ff7d91043d235cc7` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-danger` | `dark:enabled:hover:text-danger-400` | `dark:enabled:hover:text-danger-400` | --p-danger-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.d8dc070dd10133ec` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-danger` | `dark:enabled:active:text-danger-400` | `dark:enabled:active:text-danger-400` | --p-danger-400 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.5d1eb07d9233a54a` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-plain` | `bg-transparent` | `bg-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.6cccaf1ded8599be` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-plain` | `enabled:hover:bg-surface-50` | `enabled:hover:bg-surface-50` | --p-surface-50 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.4602aebccab039b8` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-plain` | `enabled:active:bg-surface-100` | `enabled:active:bg-surface-100` | --p-surface-100 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.6170398aec32862e` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-plain` | `border-transparent` | `border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.c49341b14bf3f40e` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-plain` | `enabled:hover:border-transparent` | `enabled:hover:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.57deb7846960723a` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-plain` | `enabled:active:border-transparent` | `enabled:active:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.1be7b410b5f5a73f` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-plain` | `text-surface-700` | `text-surface-700` | --p-surface-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.5ec35b77ade67770` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-plain` | `enabled:hover:text-surface-700` | `enabled:hover:text-surface-700` | --p-surface-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.0a8bb18a9a73e14b` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-plain` | `enabled:active:text-surface-700` | `enabled:active:text-surface-700` | --p-surface-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.32cd46760771f0fa` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-plain` | `dark:bg-transparent` | `dark:bg-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.9453cca52bfcb69c` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-plain` | `dark:enabled:hover:bg-surface-800` | `dark:enabled:hover:bg-surface-800` | --p-surface-800 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.ef49fc7e76e3ae6e` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-plain` | `dark:enabled:active:bg-surface-700` | `dark:enabled:active:bg-surface-700` | --p-surface-700 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.8857a18fa977ddab` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-plain` | `dark:border-transparent` | `dark:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.0e17299269a40184` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-plain` | `dark:enabled:hover:border-transparent` | `dark:enabled:hover:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.ade4864853dde1a3` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-plain` | `dark:enabled:active:border-transparent` | `dark:enabled:active:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.af0900f867265314` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-plain` | `dark:text-surface-0` | `dark:text-surface-0` | --p-surface-0 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.f5c2d61976e01383` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-plain` | `dark:enabled:hover:text-surface-0` | `dark:enabled:hover:text-surface-0` | --p-surface-0 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.83e6929462ab4c99` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-text.p-button-plain` | `dark:enabled:active:text-surface-0` | `dark:enabled:active:text-surface-0` | --p-surface-0 | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.15b751b1abdffd76` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-link` | `bg-transparent` | `bg-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.bda7a7a6475b7494` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-link` | `enabled:hover:bg-transparent` | `enabled:hover:bg-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.3c3d3ce43b0d7a5c` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-link` | `enabled:active:bg-transparent` | `enabled:active:bg-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.3c03cd1d45a290e1` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-link` | `border-transparent` | `border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.8e63d74f7086dcb2` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-link` | `enabled:hover:border-transparent` | `enabled:hover:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.ebf003a2ce405e38` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-link` | `enabled:active:border-transparent` | `enabled:active:border-transparent` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
| `css.button.6aa51f91d55cad16` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-link` | `text-primary` | `text-primary` | --p-primary-color | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.b134d8b7f29b214c` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-link` | `enabled:hover:text-primary` | `enabled:hover:text-primary` | --p-primary-color | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.fe4a7926de6a9750` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-link` | `enabled:active:text-primary` | `enabled:active:text-primary` | --p-primary-color | `review-required` | `pending-browser-proof` | `runtime-covered-existing` |
| `css.button.c1e80326cbab7282` | Button | `npm/@wippy-fe--theme/primevue/button.css` | `.p-button-link:not(:disabled):hover .p-button-label` | `underline` | `underline` | none | `review-required` | `not-applicable-until-runtime` | `compile-baseline-insufficient` |
<!-- GENERATED:TOKEN-CATALOGUE:END -->



---

# "Theming: Micro Frontend Apps"

## Theming: Micro Frontend Apps


**Classification: configuration reference with partial recipes.** The YAML,
package metadata, and runtime snippets each show one layer of the theme
contract; combine them with a complete `view.page` project and facade entry.

Micro frontend apps receive the same effective child theme through
engine-specific CSS delivery. See [Theme Authoring](./theming.md) for the
shared authoring contract.

---



### How the theme reaches your app


With iframe delivery, the host injects CSS through the proxy pipeline and puts
custom variables and CSS in document-level adopted stylesheets. With Web
Fragment delivery, the framework gateway supplies the platform CSS and the
fragment adapter puts custom variables and CSS in the reflected head as
ordinary `<style>` elements. The current runtime schema is `wippy-context-2.0`:
facade theming is represented as `theming.global`, `theming.host`, and
`theming.children`; either page engine receives its effective child-facing
theme as `config.theming.global`.



#### L1 — Global (facade level)


CSS variables set in the facade's global theming scope reach the host and child
pages through the engine's CSS-delivery path. Use this scope for the brand
palette, accent color, and styling that must apply consistently everywhere.

```yaml
- name: css_variables
  value: '{"--p-primary":"#4f8ef7","--p-secondary":"#6f7385","--p-danger":"#dc2626"}'
```



#### L2 — Scoped (host or children scope)


The facade exposes separate current-schema scopes for the host chrome and for child pages:

| Schema scope | Reaches | Use for |
|---|---|---|
| `theming.host` | Host UI chrome only | Sidebar, chat messages, splitter — host BEM overrides |
| `theming.children` | Child pages only | CSS that applies inside child apps but must not leak into the host |

CSS set in `children_css_variables` or `children_custom_css` reaches your micro frontend app; host-scoped vars target the Web Host chrome only.



#### L3 — Per-page (`config_overrides` in registry YAML)


Give a page its own theme by setting `config_overrides.customization.cssVariables` / `customCSS` in the page's registry entry YAML. The override is projected into the page's `theming.global`, so it themes the page **and everything the page embeds**. Nested `<w-artifact>` / `<w-iframe>` / `html.inject` content is built from the page's already-merged config and inherits the theme recursively. Use this for a **self-themed sub-tree**, such as an admin module whose theme propagates to its artifacts and sub-apps. It does not affect sibling pages or the rest of the app shell.

```yaml
- name: iframe-demo-themed
  kind: registry.entry
  meta:
    type: view.page
    config_overrides:
      customization:
        cssVariables:
          "--p-primary": "#9c59d1"
          "@light":
            "--p-content-background": "#faf5ff"
          "@dark":
            "--p-content-background": "#1a0d22"
        customCSS: |
          .demo-banner { background: var(--p-primary-color); color: var(--p-primary-contrast-color); }
```

Top-level entries apply in every theme mode. `@dark` and `@light` replace selected entries and compile to both Auto-mode media blocks and forced `.w-theme-dark` / `.w-theme-light` selectors. The host owns those classes; applications do not invent a parallel `data-theme` protocol.

A `package.json` mirror under `wippy.configOverrides` provides the same shape for host-less rendering (standalone development preview and unit tests). Keep both synchronized; the YAML takes precedence when a host is present.

---



### Enabling iframe CSS injection


For iframe-hosted and host-less rendering, configure which injections your
micro frontend app requests in the `package.json` `wippy` block:

```jsonc
"wippy": {
  "type": "page",
  "proxy": {
    "injections": {
      "css": {
        "themeConfig":      true,   // --p-* CSS vars (theme-config.css)
        "primevue":         true,   // PrimeVue component CSS and Tailwind utilities
        "markdown":         false,  // .data-body markdown styles
        "iframe":           true,   // Scrollbar styling
        "customCss":        true,   // Child-projected theming.global.customCSS
        "customVariables":  true    // Child-projected theming.global.cssVariables
      },
      "tailwindConfig": false       // LEGACY runtime-Tailwind only; leave false for Vite builds
    }
  }
}
```

The iframe proxy has broad runtime defaults when flags are omitted. **Enable these flags to receive theme CSS** in your micro frontend app (a theming-focused recap, not the authoritative flag list):

- `css.themeConfig` — the full `--p-*` CSS variable system (`theme-config.css`). Enable to inherit the theme palette.
- `css.primevue` — PrimeVue component styles. Enable for apps using PrimeVue.
- `css.customCss` — the host-composed child-facing custom CSS: facade **global + children** custom CSS merged into `config.theming.global.customCSS`, plus any per-page override. The flag gates this injection rather than naming a single scope. Enable to receive facade/per-page custom CSS.
- `css.customVariables` — child-projected `config.theming.global.cssVariables` as effective base, Auto-light, Auto-dark, forced Light, and forced Dark blocks. Enable to receive theme variable overrides.
- `css.markdown` — `.data-body` markdown styles. Enable only if your page renders markdown content.

Full flag reference and runtime defaults: [CSS Injection](../web-host/css-injection.md).

Web Fragment delivery does not use these flags to gate its fixed host CSS. The
framework gateway injects those assets, and the fragment adapter applies the
effective custom variables and CSS after it receives AppConfig.

> **Development mode:** The development overlay starts with `themeConfig`, `primevue`, `markdown`, and `iframe` disabled. Enable them to preview the injected theme locally. Select "Auto-accept on reload" to preserve the selection across reloads.

---



### Merge order — what overrides what


When the host applies AppConfig (last writer wins):

1. `theme-config.css` defaults (dev-time fallback)
2. Facade `theming.global` and child-facing `theming.children`
3. Page `wippy.configOverrides` (declarative, baked into the page)
4. `window.__WIPPY_CONFIG_OVERRIDES__` (runtime, if set before proxy loads)

For `cssVariables`: the override map **replaces** the inherited child map — write the full set you want. For `icons`/`iconSets`: additive merge. For `axiosDefaults`, `routePrefix`, and `apiRoutes`: the host applies the current `AppConfigOverrides` merge rules for those fields.



#### Runtime overrides (`window.__WIPPY_CONFIG_OVERRIDES__`)


For query-param or feature-flag–driven theming, set
`window.__WIPPY_CONFIG_OVERRIDES__` before `proxy.js` runs.

This pre-proxy global is an embedding/host-less integration escape hatch. In a hosted child, `window.location` belongs to the selected page engine—`about:srcdoc` under iframe delivery—and is not host route or query context. Use declarative page `config_overrides` or AppConfig supplied by the host. Never infer host state from child or parent browser locations.

---



### Verifying


To confirm CSS variables are active in your running page, select its execution
realm in DevTools—an inner frame for iframe delivery, or the reframed fragment
realm for Web Fragment delivery—then run:

```js
getComputedStyle(document.documentElement).getPropertyValue('--p-primary-color')
```

A non-empty result proves only that some theme CSS loaded. Compare the exact configured value at the page root, WC host, WC inner root, and rendered semantic color; verify every configured family. Full workflow: [Debugging](./debugging.md).

---



### Related docs


- [theming.md](./theming.md) — CSS variable catalog and anti-patterns
- [web-component-theming.md](./web-component-theming.md) — theming for web components (shadow DOM)
- [micro-frontend-app.md](./micro-frontend-app.md) — full micro frontend app development guide
- [host-less-mode.md](./host-less-mode.md) — dev overlay and CSS injection in host-less mode
- [compliance-checklist.md](./compliance-checklist.md) — full REJECT/WARN rules for theming



---

# "Theming: Web Components"

## Theming: Web Components


[Theming reference](./theming.md) covers the full CSS variable catalog. This doc covers how a web component receives the theme through shadow DOM.

---



### How the theme reaches your component


Shadow DOM blocks CSS cascade — stylesheets written outside your component do not apply inside it. However, CSS custom properties (variables) **do** cross the shadow boundary. This means:

- Custom properties inherit across the shadow boundary. WippyElement also bridges every configured variable name through its forced-theme inner root, so locally loaded `theme-config.css` defaults cannot reset configured values.
- PrimeVue component styles, Tailwind utilities, and other rule-based stylesheets do **not** cascade in — you must load them explicitly via `hostCssKeys`.

---



### Customization levels


**L1 — Global:** CSS custom properties cross the shadow boundary. WippyElement enumerates the effective global/children/page variable maps, including `@light` / `@dark`, and installs a generic inheritance bridge before the injected custom CSS layer.

**L2 — Scoped:** Same as L1 for custom properties. Stylesheet-based CSS (PrimeVue, Tailwind) does not cascade — use `hostCssKeys` to load these explicitly into the shadow root.

**L3 — Per-page config_overrides:** CSS vars set via operator `config_overrides` reach the WC host and inner theme root through the same generic bridge.

**Facade `custom_css` reaches the shadow root (Web Host 1.0.43+, opt-out).** Selector rules do not cascade across the boundary, so the runtime injects composed global + children custom CSS.

The configured-variable bridge is independent of the frontend `customCss` opt-out and remains active. Ordering is platform theme defaults → configured-variable inheritance bridge → injected custom CSS.

> **Before Web Host 1.0.43**, facade `custom_css` rules did not reach a component's shadow root — only custom properties inherited. On older hosts, replay the rule inside the WC's own styles or lift it to a `--p-*` token form.

---



### Receiving theme CSS


JavaScript externalization follows the complete pinned Web Host `import-map.json`, including for `@wippy-fe/theme`. CSS delivery is separate: a shadow root receives rule-based theme assets only through `hostCssKeys` or bundled/inline CSS.



#### `hostCssKeys` — runtime CSS loading


Declare which host-served CSS assets the WC runtime should inject into your shadow root. Add to `wippyConfig.hostCssKeys`:

```typescript
static get wippyConfig(): WippyElementConfig<ComponentProps> {
  return {
    propsSchema: pkg.wippy.props as WippyPropsSchema,
    hostCssKeys: ['themeConfigUrl', 'iframeCssUrl'] as const,
    inlineCss: stylesText,
  }
}
```

| Key | What it loads | Size | When to include |
|---|---|---|---|
| `themeConfigUrl` | `theme-config.css` — the full `--p-*` CSS variable system | ~8 KB | When the WC consumes host semantic tokens, dark mode, or themed chrome. A presentation-neutral canvas/SVG/chart can omit it. |
| `primeVueCssUrl` | All PrimeVue component CSS (unstyled mode) | ~455 KB | Only if the WC renders PrimeVue components (`<Button>`, `<Dialog>`, etc.) inside its shadow root. |
| `markdownCssUrl` | `.data-body` markdown styles | ~5 KB | Only if the WC renders markdown content. |
| `iframeCssUrl` | Default themed scrollbar styling; the name is historical | ~1 KB | Required for any WC that can scroll, for scrollbar consistency. |

`preflightCssUrl` is not in the `HostCssKey` union. If you genuinely need Tailwind v3 preflight inside the shadow root, call `hostCss.preflightCssUrl` + `loadCss()` imperatively. In practice this is rarely needed.



##### Bundle-size guidance


| `hostCssKeys` | Total CSS pulled |
|---|---|
| `['themeConfigUrl']` | ~8 KB |
| `['themeConfigUrl', 'iframeCssUrl']` | ~9 KB |
| `['themeConfigUrl', 'markdownCssUrl', 'iframeCssUrl']` | ~14 KB |
| `['themeConfigUrl', 'primeVueCssUrl', 'iframeCssUrl']` | ~464 KB |

Choose independently:

- A presentation-neutral canvas/SVG/chart with no standard product controls, host semantic tokens, or utility classes may omit PrimeVue, the theme asset, and Tailwind.
- Any button, input, form, table, dialog, menu, tag, tooltip, or feedback control requires its PrimeVue equivalent, `PrimeVuePlugin`, and `primeVueCssUrl`.
- Host semantic tokens, dark mode, or themed chrome require `themeConfigUrl`.
- Tailwind is required when source authors Tailwind utility classes.
- Scrollable content requires `iframeCssUrl`.



#### `inlineCss` — build-time CSS


Compile your Tailwind/SCSS at build time and inject it into the shadow root via `inlineCss`. Use Vite's `?inline` import:

```typescript
import stylesText from './styles.css?inline'

static get wippyConfig() {
  return {
    hostCssKeys: ['themeConfigUrl'] as const,
    inlineCss: stylesText,
  }
}
```



#### Local dev fallback


For local development without a host, import `theme-config.css` directly in your `styles.css` to get fallback variable values:

```css
/* src/styles.css */
@import "@wippy-fe/theme/theme-config.css";

:host {
  color: var(--p-text-color);
  background: var(--p-content-background);
}
```

This provides the default `--p-*` values so your component renders correctly in host-less mode. At runtime the real theme is delivered via `hostCssKeys: ['themeConfigUrl']` and takes precedence.

---



### Writing component CSS


Request `themeConfigUrl`, consume semantic vars, and do not redeclare inherited palette defaults. Semantic aliases switch with Auto and forced modes:

```css
:host {
  color: var(--p-text-color);
  background: var(--p-content-background);
  border: 1px solid var(--p-content-border-color);
}

.danger-indicator {
  color: var(--p-danger-500);
}
```

Do not use `var(--p-surface-N)` for theme-dependent colors — the numbered surface scale does not flip with dark mode. Use semantic aliases (`--p-text-color`, `--p-content-background`, `--p-text-muted-color`, `--p-content-border-color`) instead.

For derived shades: `color-mix(in srgb, var(--p-content-background) 85%, var(--p-text-color) 15%)`.



#### Defensive fallbacks


WCs may run in host-less dev mode (no parent page), so a fallback is acceptable:

```css
/* OK in WCs — dev preview fallback only */
color: var(--p-text-color, #404040);
```

Limit fallbacks to one per logical color, document them as "dev preview only", and never use them in micro frontend apps (where the host always provides the vars).



#### Reading vars into JS


When passing theme values to non-CSS contexts (D3, Canvas, mermaid):

```typescript
const styles = getComputedStyle(this.$el)
const primaryColor = styles.getPropertyValue('--p-primary-500').trim()
const background = styles.getPropertyValue('--p-content-background').trim()
// pass to mermaid.init or D3.scaleOrdinal
```

---



### Common patterns


```typescript
// Presentation-neutral chart-only WC: no controls, host tokens, utilities, or scroll:
hostCssKeys: [] as const

// WC that renders PrimeVue components inside Shadow DOM:
hostCssKeys: ['themeConfigUrl', 'primeVueCssUrl', 'iframeCssUrl'] as const

// WC that renders markdown:
hostCssKeys: ['themeConfigUrl', 'markdownCssUrl', 'iframeCssUrl'] as const

// Reference: mermaid WC — renders SVG directly, only needs --p-* vars:
hostCssKeys: ['themeConfigUrl'] as const
```

---



### Anti-patterns specific to WCs


- Hardcoding hex inside `:host { … }` — use `var(--p-*)` instead.
- `<style>` blocks with `@media (prefers-color-scheme: dark)` that hardcode dark-mode colors — the vars in `theme-config.css` retune themselves for dark; if you reference `var(--p-*)` correctly, dark mode is free.
- Requesting `primeVueCssUrl` when the WC doesn't render PrimeVue — adds a large stylesheet for zero benefit.
- Setting PrimeVue overlays to `appendTo: 'self'` as a routine fix. Install `PrimeVuePlugin` and keep the default target; it redirects to a pinned overlay layer in the owning shadow root. Explicit `self` is inline placement and can clip in scrolling overlays.
- Forgetting `bubbles: true, composed: true` on `CustomEvent` dispatch — events won't escape shadow DOM.
- Choosing `@wippy-fe/theme` externalization from CSS assumptions instead of the complete pinned Web Host import map.

---



### Verifying


Do not stop at a non-empty token. Compare the exact configured value on the element host and inner theme root, then verify the browser-resolved color used by the rendered control:

```js
const el = document.querySelector('your-element')
const inner = el.shadowRoot.querySelector('[data-wippy-theme-root]')
getComputedStyle(el).getPropertyValue('--p-primary-color')
getComputedStyle(inner).getPropertyValue('--p-primary-color')
```

Repeat across every configured family in Auto-light, Auto-dark, forced Light, and forced Dark. A WC requests `themeConfigUrl` and consumes semantic tokens; it does not redeclare inherited palette defaults.

Full debugging workflow: [Debugging](./debugging.md).

---



### Related docs


- [theming.md](./theming.md) — CSS variable catalog and anti-patterns
- [micro-frontend-app-theming.md](./micro-frontend-app-theming.md) — theming for micro frontend apps (iframe injection)
- [web-component.md](./web-component.md) — full web component development guide
- [host-less-mode.md](./host-less-mode.md) — dev overlay and host-less mode
- [compliance-checklist.md](./compliance-checklist.md) — full REJECT/WARN rules for theming



---

# "Build and Dependency Contract"

### Canonical Wippy project build contract


In a Wippy application or module repository launched by `wippy.exe`, invoke the
repository Make target. Do not run package-manager or Vite build commands
directly.

The Makefile recipe for every production frontend target uses:

```text
npm run build -- --outDir <target> --emptyOutDir
```

The deployment build owns `<target>`. `vite.config.ts` must not hardcode a deployment output directory.

Platform/package source repositories that are not launched by `wippy.exe`, such
as Web Host source, use the exact scripts and arguments declared by that
repository's `package.json`. The Wippy module `--outDir <target>
--emptyOutDir` recipe does not apply to package-source repositories unless
their own declared script explicitly documents those arguments.



#### Makefile


```makefile
FRONTEND_OUTPUT := $(abspath app/src/app/static/example)

.PHONY: frontend-example
frontend-example:
	cd frontend/example && npm run build -- --outDir "$(FRONTEND_OUTPUT)" --emptyOutDir
```



#### make.ps1


Windows users invoke the matching target through `make.bat`. `make.ps1`
implements the Makefile target for Windows; it is not a separate public build
interface.

```powershell
param(
  [Parameter(Position = 0)]
  [string]$Target = "help"
)

$ErrorActionPreference = "Stop"
$targets = @("frontend-example")
if ($Target -notin $targets) {
  throw "Unknown target '$Target'. Available targets: $($targets -join ', ')"
}

$Output = "app/src/app/static/example"
$resolvedOutput = [System.IO.Path]::GetFullPath(
  [System.IO.Path]::Combine($PSScriptRoot, $Output)
)
Push-Location (Join-Path $PSScriptRoot "frontend/example")
try {
  npm.cmd run build -- --outDir $resolvedOutput --emptyOutDir
  if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
}
finally {
  Pop-Location
}
```



#### make.bat


`make.bat` only delegates to its PowerShell counterpart, forwards arguments, and returns its exit code.
For the example target, Windows users run `make.bat frontend-example`.

```bat
@powershell.exe -NoProfile -ExecutionPolicy Bypass -File "%~dp0make.ps1" %*
@exit /b %ERRORLEVEL%
```



### Import-map snapshot algorithm


The target Web Host release defines host-provided modules.

1. Resolve the target Web Host release tag.
2. Fetch
   `https://web-host.wippy.ai/<release-tag>/import-map.json` once during
   development.
3. Store the release tag, exact resolved URL, complete `imports` object, and
   lowercase SHA-256 of the exact fetched import-map payload bytes.
4. Externalize every key in that `imports` object.
5. Use the same complete snapshot for host-less mode.
6. Re-fetch when the host release changes or when a newly added dependency may now be host-provided.
7. Inspect the built output and reject bare imports absent from the snapshot.

Do not maintain a hand-written package list. Do not mirror the full external set into peer dependencies.

```ts
import hostImportMap from './wippy-import-map.json'

export default {
  build: {
    rollupOptions: {
      external: Object.keys(hostImportMap.imports),
    },
  },
}
```

The snapshot must include its provenance and hash. A dependency absent from the snapshot is bundled unless another documented build rule applies.

For the Web Host 1.0.56 baseline, the canonical snapshot URL is
`https://web-host.wippy.ai/webcomponents-1.0.56/import-map.json`. Do not substitute the local
application URL, an unpinned `latest` URL, or a manually reconstructed package
list.



---

# "Configuration and Casing"

## Configuration and Casing


**Classification: schema-boundary reference.** The YAML block is a shape
excerpt, not a complete registry entry.

Casing follows the schema boundary. Never recursively convert a configuration object.

| Boundary | Rule | Examples |
|---|---|---|
| Backend facade requirement names | top-level `lower_case_with_underscore` | `custom_css`, `css_variables` |
| Registry fields | each field follows its documented registry schema | `base_path`, `entry_point`, `tag_name` |
| Nested frontend configuration carried by backend YAML | preserve lower camelCase | `customCSS`, `themeConfig`, `iconifyIcons` |
| Frontend AppConfig and package metadata | lower camelCase | `configOverrides`, `hostCssKeys` |

```yaml
config_overrides:
  customization:
    customCSS: ""
    cssVariables: {}
  routePrefix: /admin

proxy:
  injections:
    css:
      themeConfig: true
      customCss: true
      iframe: true
```

Only the backend wrapper keys are snake case in this example. Nested frontend objects are passed through and retain their defined casing.



### `mountRoute` casing exception


The current view registry schema reads `meta.mountRoute` and stores it in the registry's internal `mount_route` field; API output uses `mountRoute` again. Treat the authored lower-camel-case field as one documented exception, not evidence that registry or backend fields are generally camelCase.



---

# "Custom Composites"

## Custom Composites


**Classification: normative exception-contract reference.** The JSON block is
a placeholder-bearing schema example, not a valid contract or evidence bundle.

Custom controls are exceptions, not an alternative component library.



### Admission test


A custom control is accepted only when:

1. PrimeVue cannot provide or compose the intended semantics, interaction, and affordance.
2. The exception records rejected PrimeVue compositions.
3. It names an exact generated PrimeVue sibling contract and contract hash.
4. Every property that sibling contract classifies `shared-runtime` has an exact source mapping.
5. A fixed utility is accepted only when the sibling contract classifies that exact property `platform-invariant`.
6. Novel geometry and behavior are isolated and documented.
7. Accessibility and visual evidence pass.

Data-shape equivalence is not affordance equivalence. A multi-option `SelectButton` may represent three values but does not look or behave like a sliding three-position toggle. Conversely, do not invent a `positions` prop for `ToggleSwitch`. Build a reviewed custom sibling only when the affordance requirement is real.



### Module contract


Store a reviewed exception in module-root `wippy-fe.contract.json`:

```json
{
  "schemaVersion": "generated-by-selected-contract-tool",
  "exceptions": [
    {
      "id": "module.control.example",
      "source": "src/components/ExampleControl.vue",
      "sourceSha256": "generated-from-source",
      "semanticRole": "documented-role",
      "requiredAffordance": "documented-affordance",
      "rejectedPrimeVueCompositions": [
        {
          "components": ["SelectButton"],
          "reason": "The reviewed sliding affordance cannot be preserved."
        }
      ],
      "visualSibling": {
        "component": "ToggleSwitch",
        "contractId": "primevue.toggleswitch.portable-appearance",
        "contractHash": "generated-from-selected-theme-contract"
      },
      "sharedAppearanceMappings": [
        {
          "contractProperty": "root.width",
          "part": "root",
          "selector": ".example-control",
          "source": {
            "kind": "css-variable",
            "name": "--p-toggleswitch-width"
          }
        }
      ],
      "platformInvariantUtilities": [],
      "moduleLocalProperties": [],
      "accessibilityEvidence": {
        "manifest": ".local/evidence/accessibility-manifest.json",
        "scenarioId": "module.control.example.keyboard",
        "resultId": "module.control.example.keyboard.passed",
        "build": {
          "head": "generated-candidate-commit",
          "trackedFrontendDiffSha256": "generated-diff-hash"
        }
      },
      "visualEvidence": {
        "manifest": ".local/evidence/visual-manifest.json",
        "scenarioId": "module.control.example.light.default",
        "captureId": "module.control.example.light.default.component",
        "build": {
          "head": "generated-candidate-commit",
          "trackedFrontendDiffSha256": "generated-diff-hash"
        }
      }
    }
  ]
}
```

The values shown are schema placeholders, not valid evidence. The complete
mapping is generated from the selected sibling contract; the one-row excerpt is
not a valid exception by itself. Tooling generates the source and contract
hashes. A changed source hash or sibling-contract hash invalidates review.

This page defines the normative fields; it is not a JSON Schema and the
documentation checker only proves that this example retains the required
shape. A module compliance implementation must validate a real contract
against the selected theme manifest, verify the hashes and complete property
set, and check that every evidence reference resolves to the named passing
result or capture from the same candidate build. The public `@wippy-fe/*`
0.0.56 package family does not provide a module-compliance CLI. Accessibility
evidence binds the
component `sourceSha256`, hashed files, zero unexpected console errors, and a
passed result. Visual evidence binds canonical before/after/diff files, hashes,
recomputed metrics and disposition, and the matching candidate build. A
string, missing file, missing scenario/result/capture, stale build hash,
`pending`, or unreviewed result does not satisfy the evidence requirement.

`platformInvariantUtilities` and `moduleLocalProperties` may be empty. Never
invent `gap-2`, `w-10`, `rounded-md`, or another fixed utility merely to make a
contract field nonempty. In particular, a ToggleSwitch sibling cannot relabel
width, height, radius, focus geometry, or motion as invariant when its selected
sibling contract classifies those properties `shared-runtime`.

The sibling manifest classifies properties as:

- `shared-runtime`: every custom sibling maps and consumes the published token
  or runtime-backed semantic utility.
- `platform-invariant`: a fixed value is permitted only for this exact
  property.
- `implementation-private`: internal PrimeVue mechanics do not become
  requirements for a custom sibling.

If the required runtime semantic does not exist, fix the shared theme contract first. Never copy the current sibling dimensions or invent a token name.

`sharedAppearanceMappings` is exhaustive, not illustrative: it contains exactly
one mapping for every `shared-runtime` property in the selected sibling
contract, no additional property IDs, the contract part, a stable module
selector, and the exact published source kind and name. The selected compliance
implementation must use the selector, part, CSS property, and published source
to prove the mapping structurally with PostCSS; a token name in a comment or
unrelated selector does not count. A Tailwind-backed mapping also records unique, exact
`utilityClasses`; after normalization that set must equal the selected sibling
contract source set. `platformInvariantUtilities` contains
`{ "contractProperty": "...", "utility": "..." }` records whose utility equals
the selected sibling contract source. `moduleLocalProperties`, when nonempty,
contains structured property IDs and review reasons rather than a free-form CSS
bag.

No shared `@wippy-fe/ui` package is created for a single exception. Promotion becomes eligible only after a second independent consumer proves the same behavior and portability requirements.



---

# "Host-less Mode"

## Host-less Mode


Host-less mode lets a Wippy micro frontend app or web component build, run, and test **without** the Wippy Web Host wrapping it.

> **Default injection state:** The dev overlay starts with `themeConfig`, `primevue`, `markdown`, and `iframe` **disabled**, but `customCss` and `customVariables` **enabled**. So an app that relies only on custom overrides may appear to work, while one that expects the platform theme variables or PrimeVue styles will render unstyled until you enable those injections. Open the overlay FAB → enable the injections you need → check "Auto-accept on reload" to persist across reloads.

---



### Table of contents


- [Mental model — apps and WCs are intentionally standalone-aware](#mental-model-apps-and-wcs-are-standalone-aware)
- [The `@wippy/scripts` switchpoint — one tag, two boot paths](#the-wippyscripts-switchpoint-one-tag-two-boot-paths)
- [What `dev-proxy.js` actually does](#what-dev-proxyjs-actually-does)
- [The dev overlay (config modal)](#the-dev-overlay-config-modal)
- [Host stubs — the standalone `host` API](#host-stubs-the-standalone-host-api)
- [Web components — host-less playground and tests](#web-components-host-less-playground-and-tests)
- [Common deviations and how to spot them](#common-deviations-and-how-to-spot-them)
- [Troubleshooting](#troubleshooting)
- [Related docs](#related-docs)

---



### Mental model — apps and WCs are standalone-aware


Every Wippy micro frontend app and web component follows one runtime constraint:

> **The runtime contract is the proxy API surface.**

What that means in practice:

- The only thing an app or WC touches at runtime is the proxy API surface: the sync getters imported from `@wippy-fe/proxy` (`host`, `api`, `on`, `config`, `state`, `ws`, `logger`). Both apps and WCs use the same imports; under the hood they resolve to the same `ProxyApiInstance` that the runtime installs as internal globals (`window.$W`, `window.__WIPPY_APP_API__` — never read these directly).
- Apps and WCs do **not** import code from neighboring apps, the parent
  module's Lua side, the Wippy Web Host, or another project module. They live
  in their own folder. Vite derives every Rollup external from the pinned
  target-host `import-map.json`; `package.json` declares only the npm
  dependencies and peer roots the artifact actually imports.
- The same `app.ts` (or WC `index.ts`) boots correctly in two environments:
  1. **Hosted** — inside a Wippy Web Host that injects `proxy.js`, AppConfig, importmap, and CSS.
  2. **Host-less** — running its `app.html` through a Vite dev server, a unit-test page, a Storybook-style playground, or another HTTP development host.

Each app or WC is a small program with a standardized I/O surface. The host is one possible runtime; standalone is another. Application code does not need to distinguish between them.

This design supports:
- Local frontend iteration without starting a full Wippy backend.
- Isolated WC unit tests under Vitest and jsdom.
- Apps shared between Wippy modules; every micro frontend app and web component builds with the same toolchain regardless of which module ships it.
- Customer-specific overlays that let operators patch metadata (theming, import map, and environment) without rebuilding the frontend bundle.

---



### The `@wippy/scripts` switchpoint — one tag, two boot paths


Every canonical app's `app.html` ships with **one** script tag that decides the boot path at load time:

This is an abbreviated body/boot example. Insert the complete valid import-map
response described by the [Import-map snapshot algorithm](./build-system.md#import-map-snapshot-algorithm),
updated when the pinned Web Host tag changes.

```html
<!-- URL MUST include a release-tag segment: https://web-host.wippy.ai/<release-tag>/dev-proxy.js -->
<script
    src="https://web-host.wippy.ai/<release-tag>/dev-proxy.js"
    data-role="@wippy/scripts"
></script>
```

Full `app.html` scaffold in [Micro Frontend App](./micro-frontend-app.md).

Two attributes on that one tag carry the entire dual-mode contract:

| Attribute | Role | Used by |
|---|---|---|
| `data-role="@wippy/scripts"` | Marker for the host. When present, the host removes this `<script>` element before serving the iframe and injects its own `loading.js` + `proxy.js` + importmap + AppConfig **before** the marker. The element disappears in hosted mode. | Wippy Web Host |
| `src="…/dev-proxy.js"` | Fallback URL. Used when no host is present — the browser loads `dev-proxy.js` directly and that script bootstraps the page. The `src=` attribute is irrelevant in hosted mode (the `<script>` element no longer exists). | Standalone browser load |

**Choose a URL that matches your environment.** The Web Host URL requires a release-tag segment in the path and must match the release used by the facade's `fe_facade_url`. `/dev-proxy.js` directly under the host root is not valid; pin a specific build at `/<release-tag>/dev-proxy.js`. The same bundle works for local iteration, CI, and shareable preview links.

| Environment | Sample `src=` value |
|---|---|
| Public CDN (standard) | `https://web-host.wippy.ai/<release-tag>/dev-proxy.js` |
| Self-hosted Wippy deployment | `https://<your-wippy-host>/<release-tag>/dev-proxy.js` |

The same HTML element is both the host's script-injection anchor and the host-less fallback boot.



#### What goes in the importmap?


Fetch the complete map once during development, using the same tag as `fe_facade_url` and `dev-proxy.js`:

```bash
curl.exe -fsS "https://web-host.wippy.ai/<release-tag>/import-map.json" -o import-map.json
```

Set the text of the `app.html` `<script type="importmap">` element to the
fetched JSON response verbatim. Do not put comments, ellipsis placeholders, or
hand-written substitutions inside that JSON. The
[Build and Dependency Contract](./build-system.md#import-map-snapshot-algorithm)
defines the snapshot and provenance requirements; the fetched release response
provides the exact `imports` object.

Conventions:
- Put **every fetched key** in Rollup externals, including currently unused keys.
- Keep the same complete key/value object in `app.html`; do not reconstruct it with `esm.sh`.
- Bundle an imported specifier only when its exact key is absent.
- Re-fetch when the Web Host tag changes or a new dependency is added, to check whether that exact specifier can be external.

Standalone `app.html` resolves the complete copied map. Hosted mode uses the map delivered by the same pinned release.



#### Exposing `package.json` to dev-proxy (canonical scaffold)


Every Wippy app's `package.json` carries metadata that determines runtime defaults — proxy injections (`wippy.proxy.injections.css.*`), per-page theming overrides (`wippy.configOverrides.customization`), iconify icon collections, etc. In hosted mode the host reads these from the registry. In host-less mode dev-proxy needs the same data to apply the same defaults.

The canonical pattern is `wippyPagePlugin()` from the coherent current `@wippy-fe/vite-plugin` family (`0.0.56` at publication), added once to your `vite.config.ts`. The plugin reads your `package.json` at build time and does **two** things:

1. **Resolves `file://` references** in the `wippy` block (any string value of the form `"file://<relative>"` is replaced with the referenced file's UTF-8 contents — see `*.do-not-link.<ext>` naming convention in [build-system.md](./build-system.md)).
2. **Emits two outputs** with the resolved JSON:
   - `<head>`-injected `<script type="application/json" data-role="@wippy/package">` for host-less / dev-proxy boot.
   - `wippy-meta.json` in the actual Vite output directory for wippy-hosted mode.

```ts
// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { wippyPagePlugin } from '@wippy-fe/vite-plugin'

export default defineConfig({
  plugins: [
    vue(),
    wippyPagePlugin(),
  ],
  // …
})
```

**For web components** (`view.component`, ESM-only — no HTML entry to inject into) use `wippyComponentPlugin()` from the same package. It only emits `wippy-meta.json` in the actual output directory; no `transformIndexHtml` step.

```ts
// vite.config.ts for a web component
import { wippyComponentPlugin } from '@wippy-fe/vite-plugin'
export default defineConfig({ plugins: [wippyComponentPlugin()] })
```

> `wippyPackagePlugin` remains a deprecated compatibility alias. New page code uses `wippyPagePlugin()`; component-only builds use `wippyComponentPlugin()`.

The plugin emits this into the top of `<head>` in the built `app.html`:

```html
<script type="application/json" data-role="@wippy/package">
{ "name": "@wippy/your-app", "version": "1.0.0", "wippy": { "proxy": {...}, "configOverrides": {...} } }
</script>
```

dev-proxy.js reads this synchronously at boot via
`document.querySelector('script[data-role="@wippy/package"]')` and uses `wippy.proxy.injections` to seed the proxy-config defaults and `wippy.configOverrides.customization` to seed `appConfig.theming.global`. The data-role string `@wippy/package` is exported as `WIPPY_PACKAGE_DATA_ROLE` from `@wippy-fe/shared` so both sides of the boundary share the constant.

This shape has the following properties:
- **Single source.** The plugin reads `package.json` at build time; source files do not import it.
- **Synchronous access.** Inline metadata is available to `dev-proxy.js` before application code runs.
- **Defined ordering.** The plugin injects the metadata at the top of `<head>`, before any script tag. Dev-proxy is a synchronous UMD script; module scripts are deferred.
- **Plugin-owned template update.** The plugin injects the metadata without a hand-maintained block in `app.html`.
- **Shared constant.** `@wippy-fe/shared` exports the `'@wippy/package'` value as `WIPPY_PACKAGE_DATA_ROLE`; dev-proxy and the plugin import it from there.
- **Hosted compatibility.** Hosted processing reads package metadata from the registry server-side. The inline JSON tag is only consumed by the standalone development path and is otherwise inert.

Dev-proxy reads the JSON during `resolveDevConfig()` and uses it to populate the development-overlay defaults. If the script tag is absent, dev-proxy falls back to `getDefaultProxyConfig()`, so older apps continue with the generic defaults.

> **Why a plugin and not a runtime `window` global?** Dev-proxy.js is a non-module synchronous script that runs early during `<head>` parsing — before any module script (including your `app.ts`) has loaded. So `app.ts` cannot set a global *before* dev-proxy reads it. A build-time HTML transform places the data in the DOM up-front, available the instant dev-proxy executes.

> **Why one tag and not two?** A second `<script>` block (e.g. an `if (!window.__WIPPY__) load dev-proxy`) would only run after the host's injection completes; if the marker is gone, the conditional has nothing to attach to. The single-tag pattern means the marker is *always* in the source HTML, and the host's job is exactly "delete this marker and replace it." The standalone case happens precisely when nobody deleted it.

The host contract requires that the HTML file specified in `wippy.path` include a `<script data-role="@wippy/scripts">` element where additional scripts will be injected. The `data-role` marker is the selector; `type="text/javascript"` is optional because a classic script is the HTML default.

Canonical app templates include the `src="…/dev-proxy.js"` value. **Include the `src=` fallback** unless the application cannot run host-less and records that limitation.

---



### What `dev-proxy.js` actually does


`dev-proxy.js` is the host-less boot bundle, served from the Wippy Web Host CDN at `https://web-host.wippy.ai/<release-tag>/dev-proxy.js`.

Its job is to make the `@wippy-fe/proxy` getters resolve correctly without any host — by installing the same internal globals (`window.$W`, `window.__WIPPY_APP_API__`) the real host would. App and WC code never touches those globals; it just imports from `@wippy-fe/proxy` and the getters work. dev-proxy does this in roughly five steps:

1. **Install history guard** (`installHistoryGuard()`) — stubs `pushState` / `replaceState` so vue-router doesn't try to mutate browser history outside an iframe-srcdoc context.
2. **Resolve a config** (`resolveDevConfig()` in `src/proxy/dev/resolve-dev.ts`):
   - Read `localStorage['@wippy-dev/config']` and `localStorage['@wippy-dev/proxy-config']`.
   - If `localStorage['@wippy-dev/auto-accept'] === 'true'` AND a stored config exists → use it immediately, render the overlay in monitoring mode.
   - Otherwise → render the overlay in *waiting* mode (FAB pulses blue, "Accept config to continue loading" speech bubble) and block boot until the developer clicks Accept.
3. **Build a fake `ProxyApiInstance`** wired to:
   - The accepted `ChildAppConfig` (what `config` from `@wippy-fe/proxy` returns).
   - A nanoevents emitter for `on(...)` subscriptions and `@history` / `@visibility` simulations.
   - `host` stubs that console-log every method (`createDevHostAPI()` in `src/proxy/dev/host-stubs.ts`).
   - A real axios instance backing `api` from `@wippy-fe/proxy`, configured against the URL the developer entered (`env.APP_API_URL` defaults to `${location.origin}/api`).
   - The standard logger plus the production-shaped state and WebSocket
     host-message bridges. Without a real host responder, calls that require a
     reply cannot complete; only the `host` API gets the standalone stub layer
     described below.
4. **Apply CSS injection** based on the proxy config the developer chose:
   - `themeConfig: true` → injects `theme-config.css` from `@wippy-fe/theme`.
   - `iframe`, `primevue`, `markdown` → ditto, the inline-CSS bundles from `src/proxy/dev/css-inline.ts`.
   - `customCss` / `customVariables` → applies `appConfig.theming.global.customCSS` / `cssVariables` (including the `@dark`/`@light` blocks described in [micro-frontend-app-theming.md](./micro-frontend-app-theming.md#l3-per-page-config_overrides-in-registry-yaml)).
5. **Install the internal proxy globals** with the same shape as `entry.iframe.ts`, so the `@wippy-fe/proxy` getters (`config`, `host`, `api`, `on`, `logger`, `state`, `ws`, `loadWebComponent`) resolve. Any app or WC code that imports from `@wippy-fe/proxy` works unchanged. (The globals themselves — `window.$W` et al. — are internal; see [Proxy & Isolation § Internals](../web-host/proxy-isolation.md#internals-do-not-read-or-override).)

Default `ChildAppConfig` (from `getDefaultConfig()` in `config-store.ts`):

```ts
{
  $schema: '<built schema URL>',
  auth: { token: 'dev-token', expiresAt: '' },
  env: {
    APP_API_URL: `${location.origin}/api`,
    APP_AUTH_API_URL: `${location.origin}/api`,
    APP_WEBSOCKET_URL: `${location.origin.replace(/^http/, 'ws')}/ws`,
  },
  theming: { global: {} },
  context: { resourceId: '', resourceType: 'page' },
}
```

You override any of this in the modal (or by editing `localStorage['@wippy-dev/config']`).

---



### The dev overlay (config modal)


The development overlay is a shadow-DOM web component (`<wippy-dev-overlay>`) that renders:

- A FAB (floating action button) in the bottom-right corner — the only visible affordance until clicked.
- A **speech bubble** in waiting mode: "Accept config to continue loading."
- A **panel** that opens when the FAB is clicked. The panel has three sections:
  - **Monitor** — live readout of current path, document title, viewport size; "Trigger Refresh" button that fires `@visibility(true)` so the app can re-fetch.
  - **Configuration (collapsible)**:
    - `App Config (JSON)` — full `ChildAppConfig` as editable JSON. Validates on Accept.
    - `Proxy Injections` — checkboxes for every proxy injection flag (`themeConfig`, `iframe`, `primevue`, `markdown`, `customCss`, `customVariables`, `tailwindConfig`, `resizeObserver`, `preventLinkClicks`, `iconifyIcons`, `refreshWhenVisible`, `historyPolyfill`, `errorCapture`).
    - `Options` — "Auto-accept on reload" checkbox (writes the auto-accept flag to localStorage).
  - **Footer** — Reset (clears all `@wippy-dev/*` localStorage keys), Accept (saves config + resolves the boot promise).

LocalStorage keys it uses (defined in `src/proxy/dev/config-store.ts`):

| Key | What it stores |
|---|---|
| `@wippy-dev/config` | The accepted `ChildAppConfig` JSON |
| `@wippy-dev/proxy-config` | The accepted partial `ProxyConfig` (injection flags) |
| `@wippy-dev/auto-accept` | `'true'` to skip the manual accept step on reload |

With auto-accept enabled, a refresh boots the app immediately with the last accepted config. The FAB remains available for monitoring and changes.

---



### Host stubs — the standalone `host` API


The `host` API (`import { host } from '@wippy-fe/proxy'`) is the surface the app uses to ask the host to do things — toast, navigate, open a session, set context, format URLs, etc. With no real host, dev-proxy substitutes a stub layer in `src/proxy/dev/host-stubs.ts`:

| Method | Standalone behavior |
|---|---|
| `host.toast(message)` | Console-log only |
| `host.confirm({ message })` | Browser `window.confirm()` |
| `host.startChat(token, options)` | Console-log |
| `host.openSession(uuid, options)` | Console-log |
| `host.openArtifact(uuid, options)` | Console-log |
| `host.navigate(url)` | Console-log + emits `@history` so the child router picks it up + updates the overlay path readout |
| `host.onRouteChanged(path)` | Console-log + updates the overlay path readout |
| `host.handleError(code, error)` | `console.error` |
| `host.setContext(context, sessionUUID, source)` | Console-log |
| `host.formatUrl(rel)` | Returns `${appConfig.routePrefix || ''}${rel}` |
| `host.classifyLink(href)` | Real implementation — uses `mountRoutes` / `routePrefix` from the accepted config |
| `host.layout.*` | No-op stubs that satisfy the type contract |
| `host.surface` | Standalone `host` surface descriptor; reports zero width, content sizing, and no optional surface capabilities |
| `host.bridge.post/on/request` | `post` logs, `on` is a no-op subscription, and `request` rejects because the bridge is unavailable |
| `host.setThemeMode(mode)` / `host.getThemeMode()` | Stores and reports the selected mode locally and emits the theme event |
| `host.logout()` | Console-log only |

The stubs log requested host side effects to the console. If application correctness depends on an effect, such as `host.openSession` opening a session, test that path under a host; the stubs do not perform it.

---



### Web components — host-less playground and tests


Web components share the same dual-mode design but are loaded as ES modules instead of iframes. The proxy contract for WCs is `import { api, host, on, ... } from '@wippy-fe/proxy'` — and that import resolves at runtime by reading `window.__WIPPY_APP_API__` (set by either the real proxy or dev-proxy).



#### Playground / demo HTML page


```html
<!-- demo.html in your WC project -->
<!DOCTYPE html>
<html>
<head>
    <!-- Required complete import-map script omitted from this abbreviated example. -->
    <script src="https://web-host.wippy.ai/webcomponents-1.0.56/dev-proxy.js" data-role="@wippy/scripts"></script>
</head>
<body>
    <my-component prop1="value"></my-component>
    <script type="module" src="./src/index.ts"></script>
</body>
</html>
```

Same switchpoint, same dev overlay. Your WC's `index.ts` calls `define(import.meta.url, ...)` and the element registers itself; dev-proxy provides the host stubs.

If `dev-proxy.js` fails to load (or you forget to include it), `entry.web-component.ts` throws an explicit error:

> `@wippy-fe/proxy: Proxy globals not found. For dev/testing without the Wippy host, add <script src="dev-proxy.js"></script> to your HTML.`

That error indicates that the host-less boot script is missing.



#### Partial Vitest / jsdom test excerpt


For unit tests the dev overlay is unnecessary — tests don't have a UI to interact with. The pattern is to **fake the host context directly** by attaching the wrapper object the host would attach:

The excerpt below assumes a `jsdom` test environment and a setup file loaded
before the test module. That setup must stub `window.__WIPPY_APP_API__` and
`window.__WIPPY_APP_CONFIG__`; for jsdom versions whose `ElementInternals`
lacks `states`, it must also provide that `CustomStateSet` surface. This is the
component-level assertion, not a complete Vitest project.

```ts
import { describe, expect, it } from 'vitest'
import { WippyElement } from '@wippy-fe/webcomponent-core'

class TestEl extends WippyElement {
  static get wippyConfig() {
    return { propsSchema: { properties: {} }, hostCssKeys: [] }
  }
  protected onMount(): void {}
  protected onUnmount(): void {}
}

const TAG = 'wippy-test-el'
customElements.define(TAG, TestEl)

it('reads host wrapper attached by resolver as __wippyHost', () => {
  const el = document.createElement(TAG) as TestEl
  const fakeHost = { layout: { broadcast: () => {} } }
  ;(el as any).__wippyHost = fakeHost
  expect(el.host).toBe(fakeHost)
})
```

The `__wippyHost` property is the contract the managed-layout host uses. Tests that need API or proxy globals can either mount dev-proxy via a vitest setup file, or stub `window.__WIPPY_APP_API__` themselves:

```ts
// vitest.setup.ts
;(window as any).__WIPPY_APP_API__ = {
  api: mockApi,
  host: mockHost,
  on: mockOn,
  // ...other ProxyApiInstance fields
}
```

In both approaches, test-owned code satisfies the proxy contract instead of a Wippy server.

---



### Common deviations and how to spot them


When an app or WC has drifted from the standalone-aware contract, the symptoms are predictable:

| Symptom | Probable cause | Fix |
|---|---|---|
| `app.html` has `<script data-role="@wippy/scripts"></script>` with no `src=` | Page cannot boot on an HTTP development host without Wippy injection. The proxy runtime never initializes, so application modules error when they evaluate `@wippy-fe/proxy`. | Add `src="https://web-host.wippy.ai/<release-tag>/dev-proxy.js"` to the tag — the URL always requires a release-tag segment. |
| `app.html` has the dev-proxy `<script src=…>` but **no `<script type="importmap">`** above it | Browser can't resolve external bare specifiers. The first module-script load fails with `Failed to resolve module specifier`. | Fetch `<release-tag>/import-map.json`, copy its complete `imports` object into `<head>` before dev-proxy, and use all keys as Rollup externals. |
| `app.html` body has a custom SVG spinner / `<div>Loading…</div>` instead of `<wippy-loading title="…">` | Pre-bootstrap loader doesn't match the canonical Wippy idiom. The custom markup keeps showing while the WC ecosystem (which would render a styled, theme-aware loader) is fully booted. | Replace with `<wippy-loading title="Loading..."></wippy-loading>`. The `<wippy-loading>` web component is registered by `dev-proxy.js` (it imports `@wippy-fe/loading` synchronously) before the `<body>` parses, so the element resolves correctly even at very early page load. |
| `import` from a sibling app's source files | Shared code is being copy-pasted across module boundaries. | Extract to a workspace package or duplicate intentionally; never reach across app folders. |
| Hardcoded `fetch('/api/…')` calls | Bypasses the axios instance the proxy provides; won't pick up `env.APP_API_URL` overrides. | Use `useApi()` (apps) or `import { api } from '@wippy-fe/proxy'` (WCs). |
| `new EventSource(...)` for live data | Bypasses the host's auth/relay bridge; standalone mode has no equivalent. | Use `on('your.topic', cb)` — works in both modes (in standalone the topic just doesn't fire unless you simulate it). |
| `document.documentElement.setAttribute('data-theme', ...)` for theme switch | `data-theme` is not the Wippy theme protocol. | Use Auto mode or the host-managed `.w-theme-light` / `.w-theme-dark` classes. Configured `@light` / `@dark` values support both paths. See [micro-frontend-app-theming.md](./micro-frontend-app-theming.md#l3-per-page-config_overrides-in-registry-yaml). |
| `import '@wippy-fe/theme/theme-config.css'` in `app.ts` | Redundant — the host injects theme-config via `themeConfig: true` proxy injection. In host-less mode dev-proxy injects it too. | Remove the import. |
| Hardcoded API base URLs in api/ modules | Won't work in host-less mode against a different env. | Read from `appConfig.env.APP_API_URL` via `useApi()`. |

---



### Troubleshooting


**"Proxy globals not found" error.**
The WC bundle ran but neither real proxy nor dev-proxy initialized `window.__WIPPY_APP_API__`. Check that `<script src=".../dev-proxy.js" data-role="@wippy/scripts">` is in the page and the URL is reachable. In production-host mode this error means the host failed to inject proxy.js — check the host logs.

**Dev overlay never appears.**
The overlay is a shadow-DOM custom element appended to `document.body` after `DOMContentLoaded`. If you load `dev-proxy.js` from inside `<head>` and the body is missing or has `display: none`, the overlay can't render. Move the script to the bottom of the body, or unhide the body.

**Auto-accept "stuck" with bad config.**
If the stored config is broken and auto-accept is on, the overlay still renders (in monitoring mode); click the FAB → Reset to clear all `@wippy-dev/*` localStorage keys, then reload.

**Theme is wrong in dev mode.**
By default `getDefaultProxyConfig()` enables `customCss` and `customVariables` but disables `themeConfig`, `iframe`, `primevue`, `markdown`. If your app expects PrimeVue's theme-config CSS, toggle those checkboxes in the panel. Auto-accept will remember.

**Importmap mismatch between hosted and standalone.**
Re-fetch the pinned release's `import-map.json`, replace the complete host-less `imports` object, and regenerate the Rollup external keys from it. Do not patch individual entries or maintain a curated subset.

**WC test fails with "host getter returned null".**
Tests need to set `el.__wippyHost = fakeWrapper` *before* `connectedCallback` fires. Either set it before `document.body.appendChild(el)`, or fake the wrapper through whatever resolver pattern your suite uses.

---



### Related docs


- [proxy-api.md](./proxy-api.md) — full `@wippy-fe/proxy` reference (works identically in hosted and host-less mode)
- [micro-frontend-app.md](./micro-frontend-app.md) — building micro frontend apps (the boot path is the dual-mode `app.html` pattern this doc covers)
- [web-component.md](./web-component.md) — building web components (`WippyVueElement`, `define()`, host-less playground/tests)
- [theming.md](./theming.md) — per-page theme overrides via `config_overrides` (also feed dev-proxy via `theming.global.cssVariables` / `customCSS`)
- [compliance-checklist.md](./compliance-checklist.md) — §9 Host-less mode checklist with full REJECT rules



---

# "Frontend Compliance Rule Index"

## Frontend Compliance Rule Index


This page is an index, not a second copy of the contract. The
[Portable UI Contract](../portable-ui-contract.md) owns the normative rule
statements; the links below provide detailed implementation guidance.

| Rule | Detailed guidance | Deterministic result |
|---|---|---|
| FE-PORT-001 | [Portable UI Contract](../portable-ui-contract.md) | Reject private portability assumptions |
| FE-UI-001 | [Portable UI Contract](../portable-ui-contract.md) | Reject raw or hand-rolled standard controls |
| FE-UI-002 | [Portable UI Contract](../portable-ui-contract.md) | Require affordance analysis |
| FE-UI-003 | [Portable UI Contract](../portable-ui-contract.md) | Require sibling contract and alternate-theme evidence |
| FE-UI-004 | [Portable UI Contract](../portable-ui-contract.md) | Require PrimeVue setup when controls exist |
| FE-UI-005 | [Portable UI Contract](../portable-ui-contract.md) | Reject invented props and APIs |
| FE-TW-001 | [Tailwind Contract](./tailwind-contract.md) | Resolve selected Wippy preset |
| FE-TW-002 | [Tailwind Contract](./tailwind-contract.md) | Reject compile-time values documented as runtime |
| FE-TW-003 | [Tailwind Contract](./tailwind-contract.md) | Reject fixed sibling values without invariant classification |
| FE-TW-004 | [Tailwind Contract](./tailwind-contract.md) | Reject protected mapping overrides |
| FE-TOKEN-001 | [Token Catalogue](./token-catalogue.md) | Reject undeclared `--p-*` references |
| FE-TOKEN-002 | [Token Catalogue](./token-catalogue.md) | Reject inferred or invented token names |
| FE-STYLE-001 | [Theme Authoring](./theming.md) | Reject private facade classes and module-local `.p-*` theming |
| FE-A11Y-001 | [Portable UI Contract](../portable-ui-contract.md) | Reject invalid or inaccessible custom controls |



### Required checker groups


- Token CSS parsed with PostCSS; generated token snapshot compared byte-for-byte.
- Actual Tailwind configuration resolved and representative utilities compiled.
- Emitted declarations classified as runtime variable, compiled constant, arbitrary literal, or internal/transient.
- Raw controls, missing PrimeVue setup, protected mapping overrides, undeclared tokens, private facade dependencies, and contract hash drift rejected.
- Import-map externals compared with the complete pinned snapshot.
- Build output checked against the configured registry and served asset.
- Theme switching uses `host.setThemeMode()` and verifies propagated AppConfig
  state; direct theme-class manipulation and internal proxy wires are rejected.
- Generated catalogues checked for provenance, version tuple, and source hashes.
- Copyable examples parsed, built where applicable, and checked for nested interactive content.
- Project-bound mode returns exactly `UNSUPPORTED`, and standard CI fails.

Promptmap may generate leads. It is not evidence for token existence, utility resolution, reachability, or deletion.



### Generated publication gates


The generated token and Tailwind sections may not contain a pending marker at publication. Every new runtime token needs a real Wippy CSS consumer, a computed-style mutation test, and a documented portable-consumer purpose.

Publication keeps runtime evidence outside the repository. Set:

- `WIPPY_THEME_ROOT` to the selected `@wippy-fe/theme` package.
- `WIPPY_FE_EVIDENCE_ROOT` to the release evidence directory containing
  `runtime-acceptance-evidence.json`, `visual-evidence-index.json`, their
  relative scenario manifests, and screenshots.
- `WIPPY_FE_RUNTIME_EVIDENCE_SHA256` to the lowercase SHA-256 of the exact
  `runtime-acceptance-evidence.json` bytes.

`FRONTEND_DOCS_PUBLICATION=1 node scripts/check-frontend-docs.mjs` invokes the
selected theme's canonical acceptance checker with that evidence path and hash,
then validates and recomputes the visual evidence. Normal documentation
freshness checks do not require local release evidence.



### Deterministic visual verification


Every component affected by an appearance change has a scenario manifest and
immutable before/after/diff evidence. The baseline and candidate use the same
browser build, device-pixel ratio, fonts, fixture data, theme, viewport, reduced
motion setting, and settling rule. Capture all applicable states, including
light and dark themes, interaction states, overlays, disabled/error states, and
the desktop layouts the product supports. Do not invent a narrow/mobile
requirement for a desktop-only product.

Each scenario captures the component crop and surrounding application context.
It also captures the full page when an overlay, overflow, or page layout can be
affected. A component index declares the complete applicable matrix and points
to one immutable manifest per scenario:

```json
{
  "schemaVersion": "1.0.0",
  "componentId": "module.component",
  "applicability": {
    "themes": ["light", "dark"],
    "viewports": [{ "id": "desktop", "width": 1440, "height": 900 }],
    "states": ["default"],
    "overlay": false
  },
  "finalBuild": {
    "candidateCommit": "generated-candidate-commit",
    "candidateBuildHash": "sha256:generated-candidate-build-hash",
    "recapturedAfterBuild": true
  },
  "scenarios": [
    {
      "scenarioId": "module.component.light.default",
      "theme": "light",
      "viewport": "desktop",
      "state": "default",
      "manifest": "scenarios/module.component.light.default.json"
    },
    {
      "scenarioId": "module.component.dark.default",
      "theme": "dark",
      "viewport": "desktop",
      "state": "default",
      "manifest": "scenarios/module.component.dark.default.json"
    }
  ]
}
```

The checker expands the applicability cross-product and fails if any declared
theme, viewport, or state has no unique scenario. When `overlay` is true, every
scenario also requires the `full-page` capture scope. The final build commit and
hash must match every scenario's candidate and
`recapturedAfterBuild` must be true.

Each scenario manifest records hashes rather than trusting filenames:

```json
{
  "schemaVersion": "1.0.0",
  "scenarioId": "module.component.light.default",
  "componentId": "module.component",
  "state": {
    "theme": "light",
    "viewport": { "width": 1440, "height": 900 },
    "interaction": "default"
  },
  "runtime": {
    "browserVersion": "pinned-browser-version",
    "devicePixelRatio": 1,
    "fontsHash": "sha256:generated-font-set-hash",
    "fixtureHash": "sha256:generated-fixture-hash"
  },
  "baseline": {
    "commit": "generated-baseline-commit",
    "buildHash": "sha256:generated-baseline-build-hash"
  },
  "candidate": {
    "commit": "generated-candidate-commit",
    "buildHash": "sha256:generated-candidate-build-hash",
    "recapturedAfterBuild": true
  },
  "requiredScopes": ["component", "context"],
  "captures": [
    {
      "scope": "component",
      "before": {
        "artifactId": "component-before",
        "path": "screenshots/component-before.png",
        "sha256": "sha256:generated-before-hash"
      },
      "after": {
        "artifactId": "component-after",
        "path": "screenshots/component-after.png",
        "sha256": "sha256:generated-after-hash"
      },
      "diff": {
        "artifactId": "component-diff",
        "path": "screenshots/component-diff.png",
        "sha256": "sha256:generated-diff-hash"
      }
    },
    {
      "scope": "context",
      "before": {
        "artifactId": "context-before",
        "path": "screenshots/context-before.png",
        "sha256": "sha256:generated-before-hash"
      },
      "after": {
        "artifactId": "context-after",
        "path": "screenshots/context-after.png",
        "sha256": "sha256:generated-after-hash"
      },
      "diff": {
        "artifactId": "context-diff",
        "path": "screenshots/context-diff.png",
        "sha256": "sha256:generated-diff-hash"
      }
    }
  ],
  "diff": {
    "changedPixels": 0,
    "totalPixels": 1296000,
    "changedRatio": 0,
    "pixelDeltaThreshold": 8,
    "changedRatioThreshold": 0.001,
    "disposition": "within-threshold",
    "result": "passed",
    "waiver": null
  },
  "console": { "unexpectedErrors": [] },
  "fixtureCleanup": { "temporaryArtifactsRemaining": [], "verified": true }
}
```

The values above show the required shape, not valid evidence. Publication fails
when a changed component or required state has no scenario, a required capture
scope is absent, a referenced image or hash is missing, builds are stale,
unexpected console errors remain, temporary fixture code remains, or the diff
exceeds tolerance without a reviewed design waiver. A waiver records the exact
changed pixels, design reason, reviewer, and affected scenario; it cannot waive
missing captures, console errors, or fixture cleanup.



---

# "Unsupported Project-Bound Modules"

## Unsupported Project-Bound Modules


**Classification: normative policy reference.** It defines the marker and
required result for a project-selected compliance workflow; the public package
family does not provide that workflow as a runnable CLI.

Wippy’s supported frontend contract is portable. A module that intentionally requires project-private facade CSS, private classes, or another deployment-specific frontend assumption is `UNSUPPORTED`.

This is not a normal exception. The project compliance workflow must enforce
these results:

- Standard compliance returns exactly `UNSUPPORTED`.
- Standard CI fails.
- Reuse, theme portability, upgrades, and support are not guaranteed.
- The module owner is responsible for every consuming facade and migration.

Do not label this mode “discouraged,” “partially compliant,” or “non-compliant but accepted.” The canonical status is `UNSUPPORTED`.

Project-bound mode is advanced-only and is not presented in Quickstart or standard recipes. It cannot waive accessibility, HTML validity, security, or backend schema requirements.

An entire project being intended for one deployment does not silently relax the contract. The unsupported status must be explicit in project policy and module metadata, with the standard CI failure deliberately handled outside Wippy’s supported compliance workflow.

Declare the status in the module-root `wippy-fe.contract.json` with the exact
field and value below:

```json
{
  "portability": "project-bound"
}
```

`mode` and other aliases are not accepted. The compliance workflow must make
this marker return `UNSUPPORTED` and exit unsuccessfully; it does not grant an
exemption. The public `@wippy-fe/*` 0.0.56 package family does not ship an
application-compliance CLI, so the project must implement this gate in its
selected compliance workflow.



---

# "Debugging Wippy FE"

## Debugging Wippy FE


Use these checks to isolate common Wippy frontend failures before changing application code.



### Blank screen on load


**1. Check the Console first:**
- `Failed to resolve module specifier 'vue'` — the page externalized a specifier that its active import map does not provide. In hosted mode inspect the import map actually served by the target Web Host release; in host-less mode inspect the map in `app.html`. Compare every Rollup external against that exact map instead of assuming a canonical package list or merge precedence.
- `Proxy globals not found` (or your `@wippy-fe/proxy` imports come back undefined) — `proxy.js` / `dev-proxy.js` did not load before your app script ran, so the runtime never installed its internal globals. Check that `dev-proxy.js` is referenced with `data-role="@wippy/scripts"` in `app.html`.
- Silent hang (no errors, no app) — in host-less mode, the dev overlay may be waiting for you to click **Accept**. Confirm that its FAB (floating button) appeared. If it did not, `proxy.js` / `dev-proxy.js` failed to load or install its globals; follow the `Proxy globals not found` check above.

Hosted iframe pages and host-less pages receive config synchronously before the
proxy boots. Web Fragment pages use the fragment adapter's
`GetConfig`/`SetConfig` handshake, as does the host-level manual
`iframe.html?waitForCustomConfig` embedding.

**2. Check the Network tab:**
- Confirm `dev-proxy.js` (host-less) or `proxy.js` (hosted) loaded with status 200.
- If 404: the `src` in your `<script data-role="@wippy/scripts">` tag points to the wrong URL.

**3. Check the runtime installed its globals (internal diagnostic):**
```javascript
// Internal globals — app code never reads these; this is only a console smoke test
// that the proxy runtime mounted. App/WC code uses `import { ... } from '@wippy-fe/proxy'`.
window.$W              // should be an object, not undefined
window.__WIPPY_APP_API__ // the resolved proxy instance — present once the runtime installed
```
The `@wippy-fe/proxy` getters read these globals (`window.__WIPPY_APP_API__` is the live host instance); that is separate from how the module URL resolves. If the globals exist but imports fail, inspect the active import map and the network response for the exact `@wippy-fe/proxy` specifier. Fix the map or externalization decision in the environment that serves the page; do not infer hosted behavior from a successful host-less boot.



### Web component never appears


**1. Verify the three gates:**

Run from your backend:
```bash
curl /api/public/components/list?auto_register=true
```
Your component's `tag_name` must appear in the response. If not:
- `announced: true` missing in `_index.yaml` → add it
- `auto_register: true` missing → add it
- Component is not registered with `wippy/views` → check your module deps

**2. Check the Console:**
```javascript
customElements.get('your-tag-name')  // undefined means the element was not registered
```

**3. Check the Network tab:**
- Filter for your component's `index.js` URL
- The URL should contain `?declare-tag=your-tag-name` — this is how the element registers itself
- If the URL has no `?declare-tag=` query: `define(import.meta.url, MyElement)` was not retained in the entry chunk. Set `build.rollupOptions.preserveEntrySignatures` to `'strict'`; `false` can move the registration side effect out of the entry. See [Build System](./build-system.md)



### API calls failing / 401


**1. In host-less mode:**
- The `dev-token` stub in the proxy config is not a real credential and normally must be replaced before calling an authenticated backend
- Open the dev overlay → find the `auth.token` field in the JSON config → paste a real bearer token
- Confirm `APP_API_URL` in the overlay config points to the running backend (not localhost if your backend is elsewhere)

**2. In hosted mode:**
- Use the proxy `api` client. For eligible same-origin 401 responses it single-flights and calls `host.handleError('auth-expired', error)` automatically.
- If all API calls 401, check the Host config and session-token injection. Call `host.handleError` manually only for a request path that deliberately bypasses the standard proxy client and therefore cannot receive its automatic handling.



### Theme looks wrong


**1. In host-less mode:**
The dev overlay starts with `themeConfig`, `primevue`, `markdown`, and `iframe`
injection **disabled by default**. The base theme, PrimeVue, Markdown, and
scrollbar sheets are therefore absent until you enable them; `customCss` and
`customVariables` remain enabled by default.

Open the dev overlay FAB → toggle the CSS injections you need → check "Auto-accept on reload".

**2. Compare the complete effective chain:**

A non-empty token is not sufficient. Use distinct values so a stock-palette reset or accidental family alias is obvious:

```yaml
css_variables:
  "--p-primary": "#dc2626"
  "--p-secondary": "#7c3aed"
  "--p-accent": "#0d9488"
  "--p-danger": "#be123c"
  "--p-success": "#15803d"
  "--p-warn": "#c2410c"
  "--p-info": "#0369a1"
  "--p-help": "#9333ea"
  "--theme-diagnostic-sentinel": "#123456"
```

Then compare, in this order:

1. **Effective configured map:** inspect `config.theming.global.cssVariables` and confirm the base plus the active `@light` / `@dark` replacements.
2. **Page root:** read the exact token with `getComputedStyle(document.documentElement).getPropertyValue(name).trim()`.
3. **WC host:** read the same token from `getComputedStyle(customElement)`.
4. **WC inner root:** read it from `getComputedStyle(customElement.shadowRoot.querySelector('[data-wippy-theme-root]'))`.
5. **Rendered semantic color:** put `background-color: var(--p-<family>-color)` on a probe and compare its computed `backgroundColor`; this resolves `color-mix()` in the browser.

Repeat in Auto-light, Auto-dark, forced Light, and forced Dark. For each configured family verify its base, all 50–950 shades, `color`, `contrast-color`, `hover-color`, and `active-color`; also verify a direct shade/alias override, a surface token, and the sentinel. Page, host, and inner values must agree.

Interpret the first divergence: wrong effective map means configuration/merge; wrong page root means variable compilation/injection; correct page but wrong WC host means host propagation; correct WC host but wrong inner root means the forced-theme bridge or local defaults; equal tokens but wrong rendered color means the consuming selector or semantic alias is wrong.

**3. Web component specific:**
- If the platform defaults are absent, check that `hostCssKeys` includes `'themeConfigUrl'`.
- If the host is correct but the inner root resets to stock values, verify a current `@wippy-fe/webcomponent-core`; do not copy a palette into component CSS.
- If PrimeVue components render unstyled, add `'primeVueCssUrl'` to `hostCssKeys`.

See [Theming: Micro Frontend Apps](./micro-frontend-app-theming.md) or [Theming: Web Components](./web-component-theming.md) for the full injection pipeline.



### Host URL bar doesn't update


Portable micro frontend apps must use the `createAppRouter()` factory from `@wippy-fe/router`. The package owns both directions of host synchronization; application code must not reproduce `router.afterEach` and `@history` wiring.

**Check:**
```typescript
import { createAppRouter } from '@wippy-fe/router'
import { config } from '@wippy-fe/proxy'
import { routes } from './routes'

const router = createAppRouter(routes, {
  initialPath: config.context?.route ?? '/',
})
```

If the host URL still does not update, confirm the current `@wippy-fe/router` family is installed coherently and that no local wrapper replaces the factory. In host-less mode, the dev overlay Monitor tab shows the route the package reports.



### Works locally, breaks when hosted


**1. Check relative asset resolution for the selected engine:**

For iframe delivery, inspect:

```javascript
document.baseURI  // should be <url>/<base_path>/ from your registry entry
```

If it is wrong, the `<base>` tag was not injected correctly. Check that
`base_path` in `_index.yaml` matches the actual directory structure of the
built output.

Web Fragment delivery deliberately does not inject a `<base>` element. Inspect
the reflected head and body instead: relative `href="./…"` and `src="./…"`
attributes should be rewritten to the fragment gateway's asset URLs.

**2. Check proxy globals (internal diagnostic):**
```javascript
window.__WIPPY_PROXY_CONFIG__  // internal — must exist in iframe-hosted mode
```
Undefined means the proxy was not injected before your app ran. App code never reads this directly; see [Proxy & Isolation § Internals](../web-host/proxy-isolation.md#internals-do-not-read-or-override).

**3. Confirm `base: ''` in vite.config.ts:**
Without `base: ''`, Vite emits absolute asset paths. The app loads fine on your local dev server (which serves from `/`) but 404s when served from a CDN subdirectory.

**4. Import map mismatch:**
Re-fetch `<version-tag>/import-map.json` from the Web Host release pinned by
`fe_facade_url`. Replace the complete `imports` object in host-less `app.html`
and regenerate Vite externals from all of its keys. Do not remove the host-less
map or patch individual entries. Bundle a newly imported exact specifier only
when it is absent from the fetched map.



### Using the logger as a debugging tool


`logger.debug()` and `logger.info()` output appears in the browser Console during development — not just in production transports. Use it to trace the boot sequence:

```typescript
import { logger, config, host, api } from '@wippy-fe/proxy'

export function createMainApp() {
  logger.debug('App bootstrap started')
  logger.debug('Host services resolved', { hasConfig: !!config })
  // ... use config, host, api directly
}
```

`logger.captureException(error)` also logs to Console in dev mode and is caught by the host's error capture system in production.



---

# "Temporal Integration"

## Temporal Integration


This page is a configuration reference for Temporal clients and workers. The final registry fragment shows how the entries connect; it is not a standalone project.

The `temporal.client` and `temporal.worker` entry kinds connect Wippy workflows and activities to [Temporal](https://temporal.io).



### Client Configuration


The `temporal.client` entry kind defines a connection to a Temporal server.

```yaml
- name: temporal_client
  kind: temporal.client
  address: "localhost:7233"
  namespace: "default"
  lifecycle:
    auto_start: true
```



#### Required Fields


| Field | Description |
|-------|-------------|
| `address` | Temporal server address (host:port) |



#### Optional Fields


| Field | Default | Description |
|-------|---------|-------------|
| `namespace` | "default" | Temporal namespace |
| `tq_prefix` | "" | Task queue name prefix for all operations |
| `connection_timeout` | "10s" | Connection timeout |
| `keep_alive_time` | "30s" | Keep-alive interval |
| `keep_alive_timeout` | "10s" | Keep-alive timeout |



##### No Authentication


```yaml
- name: temporal_client
  kind: temporal.client
  address: "localhost:7233"
  auth:
    type: none
```



##### API Key (Temporal Cloud)


Provide the API key via one of these methods:

```yaml


## Direct value

- name: temporal_client
  kind: temporal.client
  address: "your-namespace.tmprl.cloud:7233"
  namespace: "your-namespace"
  auth:
    type: api_key
    api_key: "your-api-key"



## From environment variable

- name: temporal_client
  kind: temporal.client
  address: "your-namespace.tmprl.cloud:7233"
  namespace: "your-namespace"
  auth:
    type: api_key
    api_key: ${env:TEMPORAL_API_KEY}



## From file

- name: temporal_client
  kind: temporal.client
  address: "your-namespace.tmprl.cloud:7233"
  namespace: "your-namespace"
  auth:
    type: api_key
    api_key_file: "/etc/secrets/temporal-api-key"
```

Auth and credential fields resolve `${env:NAME}` placeholders through the [environment registry](system/env.md) at decode time. The legacy `api_key_env` / `key_pem_env` directives resolve the same way but are deprecated; prefer `api_key: ${env:NAME}` / `key_pem: ${env:NAME}`.



##### mTLS


```yaml
- name: temporal_client
  kind: temporal.client
  address: "temporal.example.com:7233"
  namespace: "production"
  auth:
    type: mtls
    cert_file: "/path/to/client.pem"
    key_file: "/path/to/client.key"
  tls:
    enabled: true
    ca_file: "/path/to/ca.pem"
```

Certificate and key can also be provided as PEM strings or from environment:

```yaml
auth:
  type: mtls
  cert_pem: |
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----
  key_pem: ${env:TEMPORAL_CLIENT_KEY}
```



#### TLS Configuration


```yaml
tls:
  enabled: true
  ca_file: "/path/to/ca.pem"
  server_name: "temporal.example.com"    # Override server name verification
  insecure_skip_verify: false            # Skip verification (dev only)
```



#### Health Checks


```yaml
health_check:
  enabled: true
  interval: "30s"
```



#### Security Context Propagation


Wippy propagates the calling actor and scope to workflows and activities as a signed Temporal header. Signing is HMAC-SHA256 with a key held by the client entry:

```yaml
- name: temporal_client
  kind: temporal.client
  address: "localhost:7233"
  security_hmac_key: ${env:TEMPORAL_SECURITY_KEY}
  security_hmac_previous_keys:
    - ${env:TEMPORAL_SECURITY_KEY_PREVIOUS}
```

| Field | Description |
|-------|-------------|
| `security_hmac_key` | Base64-encoded signing key; must decode to at least 32 bytes |
| `security_hmac_previous_keys` | Base64-encoded keys still accepted for verification, for rotation |

Both fields are base64 in YAML because they are byte fields. A key shorter than 32 decoded bytes is rejected at config validation, as is declaring `security_hmac_previous_keys` without `security_hmac_key`. New headers are always signed with `security_hmac_key`; every listed previous key is tried when verifying, so rotation is: add the new key as `security_hmac_key`, move the old one into `security_hmac_previous_keys`, then drop it once no in-flight execution carries it.

**Starting a workflow under an actor or scope requires the key.** If the caller has a security context and the client has no signing key, the header cannot be signed and the start fails. A client with no key can only start workflows from a context that carries neither an actor nor a scope.

The worker acquires the keys from the client entry it references, so a worker inherits signing and verification from `client:` without configuring anything itself. See [Workflows](temporal/workflows.md#security-context) and [Activities](temporal/activities.md).



### Worker Configuration


The `temporal.worker` entry kind defines a worker that executes workflows and activities.

```yaml
- name: worker
  kind: temporal.worker
  client: app:temporal_client
  task_queue: "my-app-queue"
  lifecycle:
    auto_start: true
    requires:
      - app:temporal_client
```



#### Required Fields


| Field | Description |
|-------|-------------|
| `client` | Reference to a `temporal.client` entry |
| `task_queue` | Task queue name |



#### Worker Options


Configure worker behavior:

```yaml
- name: worker
  kind: temporal.worker
  client: app:temporal_client
  task_queue: "my-app-queue"
  worker_options:
    # Identity
    identity: ""                          # Worker identity (appears in Temporal UI)

    # Concurrency
    max_concurrent_activity_execution_size: 1000
    max_concurrent_workflow_task_execution_size: 1000
    max_concurrent_local_activity_execution_size: 1000
    max_concurrent_session_execution_size: 1000
    max_concurrent_eager_activity_execution_size: 0

    # Pollers
    max_concurrent_activity_task_pollers: 20
    max_concurrent_workflow_task_pollers: 20

    # Rate limiting
    worker_activities_per_second: 0        # 0 = unlimited
    worker_local_activities_per_second: 0
    task_queue_activities_per_second: 0

    # Timeouts
    sticky_schedule_to_start_timeout: "5s"
    worker_stop_timeout: "0s"
    deadlock_detection_timeout: "0s"
    max_heartbeat_throttle_interval: "0s"
    default_heartbeat_throttle_interval: "0s"

    # Feature flags
    enable_logging_in_replay: false
    enable_session_worker: false
    disable_workflow_worker: false
    local_activity_worker_only: false
    disable_eager_activities: false
    disable_registration_aliasing: false

    # Versioning
    deployment_name: ""
    build_id: ${env:BUILD_ID}              # Read from env registry
    use_versioning: false
    default_versioning_behavior: "pinned" # or "auto_upgrade"
```

Credential and identifier fields resolve `${env:NAME}` placeholders through the [environment registry](system/env.md) at decode time. The legacy `build_id_env` directive resolves the same way but is deprecated; prefer `build_id: ${env:NAME}`.



#### Versioning Behavior


`default_versioning_behavior` controls how new workflow runs pick a worker build ID when `use_versioning` is enabled:

| Value | Behavior |
|-------|----------|
| `pinned` | Workflow stays on the build ID it started on for its entire run |
| `auto_upgrade` | Workflow may resume on the latest compatible build ID after each task |

`build_id: ${env:NAME}` reads the build ID from the env registry when a literal `build_id` is not supplied.



#### Session Worker


`enable_session_worker: true` lets the worker run Temporal Sessions: a series of activities pinned to a single worker (useful when activities share local state like a temp directory or open connection). `max_concurrent_session_execution_size` caps concurrent sessions on the worker.



#### Concurrency Defaults


| Option | Default |
|--------|---------|
| `max_concurrent_activity_execution_size` | 1000 |
| `max_concurrent_workflow_task_execution_size` | 1000 |
| `max_concurrent_local_activity_execution_size` | 1000 |
| `max_concurrent_session_execution_size` | 1000 |
| `max_concurrent_activity_task_pollers` | 20 |
| `max_concurrent_workflow_task_pollers` | 20 |
| `sticky_schedule_to_start_timeout` | 5s |



### Configuration Example


This registry fragment connects one workflow and one activity to a worker. It assumes a reachable Temporal server at `localhost:7233` and the two referenced Lua source files; see the workflow and activity pages for their implementations.

```yaml
version: "1.0"
namespace: app

entries:
  - name: temporal_client
    kind: temporal.client
    address: "localhost:7233"
    namespace: "default"
    lifecycle:
      auto_start: true

  - name: worker
    kind: temporal.worker
    client: app:temporal_client
    task_queue: "orders"
    lifecycle:
      auto_start: true
      requires:
        - app:temporal_client

  - name: order_workflow
    kind: workflow.lua
    source: file://order_workflow.lua
    method: main
    modules:
      - funcs
      - time
    meta:
      temporal:
        workflow:
          worker: app:worker

  - name: charge_payment
    kind: function.lua
    source: file://payment.lua
    method: charge
    modules:
      - env
      - errors
      - http_client
      - json
    meta:
      temporal:
        activity:
          worker: app:worker
```



### See Also


- [Activities](temporal/activities.md) - Activity definitions
- [Workflows](temporal/workflows.md) - Workflow implementation



---

# "Activities"

## Activities


Temporal activities execute non-deterministic operations. Register a `function.lua` or `process.lua` entry as an activity through its metadata.

The snippets are API recipes. The payment example is illustrative and requires an application-owned environment entry, `env.get` permission for the credential, `http_client.request` permission for the provider URL, and a payment-provider contract.



### Registering Activities


Add `meta.temporal.activity` to register a function as an activity:

```yaml
- name: charge_payment
  kind: function.lua
  source: file://payment.lua
  method: charge
  modules:
    - env
    - errors
    - http_client
    - json
  meta:
    temporal:
      activity:
        worker: app:worker
```



#### Metadata Fields


| Field | Required | Description |
|-------|----------|-------------|
| `worker` | Yes | Reference to `temporal.worker` entry |
| `local` | No | Execute as local activity (default: false) |
| `name` | No | Custom activity type name (defaults to entry ID) |



### Implementation


Activities are regular Lua functions. Keep credentials out of workflow inputs because Temporal persists those inputs in workflow history. This example reads the payment key from the environment registry inside the activity. Its placeholder provider accepts a JSON charge request and returns a JSON response. The status mapping is an application-owned policy: replace the URL, request fields, response fields, and failure mapping with your provider's contract.

```lua
-- payment.lua
local http = require("http_client")
local json = require("json")
local env = require("env")
local errors = require("errors")

local function payment_error(status)
    if status == 408 then
        return errors.new({kind = errors.TIMEOUT, message = "payment provider timed out", retryable = true})
    elseif status == 429 then
        return errors.new({kind = errors.RATE_LIMITED, message = "payment provider rate limited the request", retryable = true})
    elseif status >= 500 then
        return errors.new({kind = errors.UNAVAILABLE, message = "payment provider is unavailable", retryable = true})
    end
    return errors.new({kind = errors.INVALID, message = "payment request was rejected", retryable = false})
end

local function charge(input)
    local api_key, env_err = env.get("PAYMENTS_API_KEY")
    if env_err then return nil, env_err end

    local body, encode_err = json.encode({
        amount = input.amount,
        currency = input.currency,
        payment_token = input.payment_token
    })
    if encode_err then
        return nil, encode_err
    end

    local response, err = http.post("https://payments.example.com/v1/charges", {
        headers = {
            ["Authorization"] = "Bearer " .. api_key,
            ["Content-Type"] = "application/json"
        },
        body = body
    })

    if err then
        return nil, err
    end

    if response.status_code >= 400 then
        return nil, payment_error(response.status_code)
    end

    return json.decode(response.body)
end

return { charge = charge }
```



### Calling Activities


From workflows, use the `funcs` module:

```lua
local funcs = require("funcs")

local result, err = funcs.call("app:charge_payment", {
    amount = 5000,
    currency = "usd",
    payment_token = "payment-token-123"
})

if err then
    return nil, err
end
```



### Activity Options


Configure timeouts, retry behavior, and other execution parameters using the executor builder:

```lua
local funcs = require("funcs")

local executor = funcs.new():with_options({
    ["activity.start_to_close_timeout"] = "30s",
    ["activity.schedule_to_close_timeout"] = "5m",
    ["activity.heartbeat_timeout"] = "10s",
    ["activity.retry_policy"] = {
        maximum_attempts = 3,
        initial_interval = 1000,
        backoff_coefficient = 2.0,
        maximum_interval = 60000,
    }
})

local result, err = executor:call("app:charge_payment", input)
```

The executor is immutable and reusable. Build it once and use it for multiple calls:

```lua
local reliable = funcs.new():with_options({
    ["activity.start_to_close_timeout"] = "60s",
    ["activity.retry_policy"] = {
        maximum_attempts = 5,
        initial_interval = 2000,
        backoff_coefficient = 2.0,
        maximum_interval = 120000,
    }
})

local a, err = reliable:call("app:step_one", input)
if err then
    return nil, err
end
local b, err = reliable:call("app:step_two", a)
if err then
    return nil, err
end
```



#### Options Reference


| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `activity.start_to_close_timeout` | duration | 10m | Max time for activity execution |
| `activity.schedule_to_close_timeout` | duration | - | Max time from scheduling to completion |
| `activity.schedule_to_start_timeout` | duration | - | Max time before activity starts |
| `activity.heartbeat_timeout` | duration | - | Max time between heartbeats |
| `activity.id` | string | - | Custom activity execution ID |
| `activity.task_queue` | string | - | Override task queue for this call |
| `activity.wait_for_cancellation` | boolean | false | Wait for activity cancellation |
| `activity.disable_eager_execution` | boolean | false | Disable eager execution |
| `activity.retry_policy` | table | - | Retry configuration (see below) |
| `activity.name` | string | - | Activity type name to call, when it differs from the registry ID |
| `activity.summary` | string | - | Human-readable summary shown in the Temporal UI |
| `activity.priority` | table | - | Task priority: `priority_key` (number), `fairness_key` (string), `fairness_weight` (number) |
| `activity.versioning_intent` | string | - | `compatible` (inherit the build ID) or `default` (use assignment rules) |

Duration values accept strings (`"5s"`, `"10m"`, `"1h"`) or milliseconds as numbers.

Use the canonical `activity.*` names for new code. Legacy `temporal.activity.*` aliases remain accepted for compatibility.

```lua
local executor = funcs.new():with_options({
    ["activity.summary"] = "Charge the order payment",
    ["activity.priority"] = {
        priority_key = 10,
        fairness_key = "customer-123",
        fairness_weight = 1.0,
    },
    ["activity.name"] = "charge-payment",
    ["activity.versioning_intent"] = "use_assignment_rules",
})
```



#### Retry Policy


Configure automatic retry behavior for failed activities:

```lua
["activity.retry_policy"] = {
    initial_interval = 1000,         -- ms before first retry
    backoff_coefficient = 2.0,       -- multiplier for each retry
    maximum_interval = 300000,       -- max interval between retries (ms)
    maximum_attempts = 10,           -- max retry attempts (0 = unlimited)
    non_retryable_error_types = {    -- errors that skip retries
        "Invalid",
        "PermissionDenied"
    }
}
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `initial_interval` | number | 1000 | Milliseconds before first retry |
| `backoff_coefficient` | number | 2.0 | Multiplier applied to interval each retry |
| `maximum_interval` | number | - | Cap on retry interval (ms) |
| `maximum_attempts` | number | 0 | Max attempts (0 = unlimited) |
| `non_retryable_error_types` | array | - | Error kinds that bypass retries |



#### Timeout Relationships


```
|--- schedule_to_close_timeout --------------------------------|
|--- schedule_to_start_timeout ---|--- start_to_close_timeout -|
     (waiting in queue)                (executing)
```

- `start_to_close_timeout`: How long the activity itself can run. This is the most commonly used timeout.
- `schedule_to_close_timeout`: Total time from when the activity is scheduled until it completes, including queue wait time and retries.
- `schedule_to_start_timeout`: Max time the activity can wait in the task queue before a worker picks it up.
- `heartbeat_timeout`: For long-running activities, the max time between heartbeat reports.



### Local Activities


The `local` field is accepted on an activity:

```yaml
- name: validate_input
  kind: function.lua
  source: file://validate.lua
  method: validate
  modules:
    - json
  meta:
    temporal:
      activity:
        worker: app:worker
        local: true
```

Currently `local: true` is parsed but behaves identically to a regular activity: it is registered and executed through the standard activity path. There is no distinct local-activity execution yet, so it does not change latency, task queue behavior, or heartbeating.



### Activity Naming


Activities are registered with their full entry ID as the name:

```yaml
namespace: app
entries:
  - name: charge_payment
    kind: function.lua
    # ...
```

Activity name: `app:charge_payment`



### Context Propagation


Context values set when spawning the workflow are available inside activities:

```lua
-- Spawner sets context
local spawner = process.with_context({
    user_id = "user-1",
    tenant = "tenant-1",
})
local pid, err = spawner:spawn("app:order_workflow", "app:worker", order)
if err then
    return nil, err
end
```

```lua
-- Activity reads context
local ctx = require("ctx")

local function process_order(input)
    local user_id, user_err = ctx.get("user_id")   -- "user-1"
    if user_err then return nil, user_err end
    local tenant, tenant_err = ctx.get("tenant")   -- "tenant-1"
    if tenant_err then return nil, tenant_err end
    -- use context for authorization, logging, etc.
end
```

Activities called from a workflow with `funcs.new():with_context()` also propagate context:

```lua
-- Inside workflow
local executor = funcs.new():with_context({trace_id = "abc-123"})
local result, err = executor:call("app:charge_payment", input)
```



#### Security Context


An activity scheduled under a security context receives the signed `wippy-security` header, audienced to the activity ID. The worker verifies the signature and audience, then merges the propagated `ctx` values and the security payload onto a fresh frame before the activity function runs.

That merge is all-or-nothing and **fatal to the activity if it fails**: the activity returns an error before its code executes, so it never runs with partial context or with an unverified actor. A merge fails when the signature or audience does not verify, when the envelope is inconsistent (an actor without a scope, or policies without an actor), or when a policy named in the envelope does not resolve in the local security registry — which is the common operational cause: the worker's deployment is missing a policy entry the caller had.

The worker takes its signing and verification keys from the `temporal.client` entry it references. See [Security context propagation](temporal/overview.md#security-context-propagation).



### Error Handling


Return errors via the standard Lua pattern:

```lua
local errors = require("errors")

-- Replace this mapping with the payment provider's documented error contract.
local function payment_error(status)
    if status == 408 then
        return errors.new({kind = errors.TIMEOUT, message = "payment provider timed out", retryable = true})
    elseif status == 429 then
        return errors.new({kind = errors.RATE_LIMITED, message = "payment provider rate limited the request", retryable = true})
    elseif status >= 500 then
        return errors.new({kind = errors.UNAVAILABLE, message = "payment provider is unavailable", retryable = true})
    end
    return errors.new({kind = errors.INVALID, message = "payment request was rejected", retryable = false})
end

local function charge(input)
    if not input.amount or input.amount <= 0 then
        return nil, errors.new({ kind = errors.INVALID, message = "amount must be positive" })
    end

    local response, err = http.post(url, options)
    if err then
        return nil, errors.wrap(err, "payment API failed")
    end

    if response.status_code >= 400 then
        return nil, payment_error(response.status_code)
    end

    return json.decode(response.body)
end
```



#### Error Objects


Activity errors propagated to workflows carry structured metadata:

```lua
local result, err = funcs.call("app:charge_payment", input)
if err then
    err:kind()       -- error classification string
    err:retryable()  -- boolean, whether retry makes sense
    err:message()    -- human-readable error message
end
```



#### Failure Modes


| Failure | Error Kind | Retryable | Description |
|---------|------------|-----------|-------------|
| Application error | Whatever the activity returned | Inherited from the returned error | Error returned by activity code via `return nil, err` |
| Runtime crash | `Internal` | false | Unhandled Lua error in activity |
| Missing activity | `NotFound` | false | Activity not registered with worker |
| Timeout | `Timeout` | false | Activity exceeded configured timeout |
| Security verification | `Internal` | true | Signature, audience, or envelope check failed on the propagated security header |
| Security policy missing | `Internal` | true | A policy named in the security envelope does not resolve on this worker |

Both security failures happen during context merge, before the activity function runs. They are not marked non-retryable, so the activity retry policy keeps re-attempting them; retries do not help, because neither a bad signature nor a missing policy entry changes between attempts. Cap `maximum_attempts` on activities you want to fail fast, and read a repeating `Internal` failure with no activity log output as a context-merge failure rather than a fault in the activity.

```lua
local executor = funcs.new():with_options({
    ["activity.retry_policy"] = {maximum_attempts = 1}
})

local result, err = executor:call("app:missing_activity", input)
if err then
    print(err:kind())      -- "NotFound"
    print(err:retryable())  -- false
end
```



### Process Activities


`process.lua` entries can also be registered as activities for long-running operations:

```yaml
- name: long_task
  kind: process.lua
  source: file://long_task.lua
  method: main
  modules:
    - http_client
  meta:
    temporal:
      activity:
        worker: app:worker
```



### See Also


- [Overview](temporal/overview.md) - Configuration
- [Workflows](temporal/workflows.md) - Workflow implementation
- [Functions](lua/core/funcs.md) - Function module
- [Error Handling](lua/core/errors.md) - Error types and patterns



---

# "Workflows"

## Workflows


A `workflow.lua` entry defines a durable Temporal workflow that orchestrates activities and maintains state across failures and restarts.

This page is an API reference with partial recipes. Entry declarations, worker registration, activity implementations, security policies, and surrounding application data are shown only where they are relevant to a specific contract.



### Definition


```yaml
- name: order_workflow
  kind: workflow.lua
  source: file://order_workflow.lua
  method: main
  modules:
    - funcs
    - time
    - workflow
  meta:
    temporal:
      workflow:
        worker: app:worker
```



#### Metadata Fields


| Field | Required | Description |
|-------|----------|-------------|
| `worker` | Yes | Reference to `temporal.worker` entry |
| `name` | No | Custom workflow type name (defaults to entry ID) |



### Basic Implementation


```lua
local funcs = require("funcs")
local time = require("time")

local function main(order)
    local payment, err = funcs.call("app:charge_payment", {
        amount = order.total,
        customer = order.customer_id
    })
    if err then
        return {status = "failed", error = tostring(err)}
    end

    time.sleep("1h")

    local shipment, err = funcs.call("app:ship_order", {
        order_id = order.id,
        address = order.shipping_address
    })
    if err then
        local _, refund_err = funcs.call("app:refund_payment", payment.id)
        if refund_err then
            return {
                status = "failed",
                error = tostring(err),
                compensation_error = tostring(refund_err)
            }
        end
        return {status = "failed", error = tostring(err)}
    end

    return {
        status = "completed",
        payment_id = payment.id,
        tracking = shipment.tracking_number
    }
end

return { main = main }
```



### Workflow Module


The `workflow` module provides workflow-specific operations.



#### workflow.info()


Get workflow execution information:

```lua
local workflow = require("workflow")

local info, info_err = workflow.info()
if info_err then return nil, info_err end
print(info.workflow_id)    -- Workflow execution ID
print(info.run_id)         -- Current run ID
print(info.workflow_type)  -- Workflow type name
print(info.task_queue)     -- Task queue name
print(info.namespace)      -- Temporal namespace
print(info.attempt)        -- Current attempt number
print(info.history_length) -- Number of history events
print(info.history_size)   -- History size in bytes
```



#### workflow.exec()


Execute a child workflow synchronously and wait for its result:

```lua
local result, err = workflow.exec("app:child_workflow", input_data)
if err then
    return nil, err
end
```

Use this form when the parent must wait for the child result inline.



#### workflow.version()


Handle code changes with deterministic versioning:

```lua
local version, err = workflow.version("payment-v2", 1, 2)
if err then
    return nil, err
end

if version == 1 then
    return funcs.call("app:old_payment", input)
else
    return funcs.call("app:new_payment", input)
end
```

Parameters:
- `change_id` - Unique identifier for this change
- `min_supported` - Minimum supported version
- `max_supported` - Maximum (current) version

The version number is deterministic per workflow execution. Existing in-flight workflows continue using their recorded version, while new workflows use `max_supported`.



#### workflow.attrs()


Update search attributes and memo:

```lua
local updated, err = workflow.attrs({
    search = {
        status = "processing",
        customer_id = order.customer_id,
        order_total = order.total
    },
    memo = {
        notes = "Priority customer",
        source = "web"
    }
})
if err then
    return nil, err
end
```

Search attributes are indexed and queryable via Temporal visibility APIs. Memo is arbitrary non-indexed data attached to the workflow.



#### workflow.history_length() / workflow.history_size()


Monitor workflow history growth:

```lua
local length, length_err = workflow.history_length()
if length_err then return nil, length_err end
local size, size_err = workflow.history_size()
if size_err then return nil, size_err end

if length > 10000 then
    -- Consider continue-as-new to reset history
end
```



#### Basic Spawn


Start a workflow from any code using `process.spawn()`:

```lua
local pid, err = process.spawn(
    "app:order_workflow",    -- workflow entry
    "app:worker",            -- temporal worker
    {order_id = "123"}       -- input
)
if err then
    return nil, err
end
```

The host parameter is the temporal worker (not a process host). The workflow runs durably on Temporal infrastructure.



#### Spawn with Monitoring


Monitor workflows to receive EXIT events when they complete:

```lua
local pid, err = process.spawn_monitored(
    "app:order_workflow",
    "app:worker",
    {order_id = "123"}
)
if err then
    return nil, err
end

local events = process.events()
local event, open = events:receive()
if not open then
    return nil, errors.new({kind = errors.INTERNAL, message = "process event channel closed"})
end

if event.kind == process.event.EXIT then
    local result = event.result.value
    local error = event.result.error
end
```



#### Spawn with Name


Assign a name to a workflow for idempotent starts:

```lua
local spawner = process
    .with_options({})
    :with_name("order-" .. order.id)

local pid, err = spawner:spawn_monitored(
    "app:order_workflow",
    "app:worker",
    {order_id = order.id}
)
if err then
    return nil, err
end
```

When a name is provided, Temporal uses it to deduplicate workflow starts. Spawning with the same name while a workflow is running returns the existing workflow's PID by default.



#### Spawn with Explicit Workflow ID


Set a specific Temporal workflow ID:

```lua
local spawner = process
    .with_options({
        ["workflow.id"] = "order-" .. order.id,
    })

local pid, err = spawner:spawn_monitored(
    "app:order_workflow",
    "app:worker",
    order
)
if err then
    return nil, err
end
```



#### ID Conflict Policies


Control behavior when spawning a workflow with an ID that already exists:

```lua
-- Fail if workflow already exists
local spawner = process
    .with_options({
        ["workflow.id"] = "order-123",
        ["workflow.id_conflict_policy"] = "fail",
    })

local pid, err = spawner:spawn("app:order_workflow", "app:worker", order)
if err then
    -- Workflow already running with this ID
end
```

```lua
-- Error when already started (alternative approach)
local spawner = process
    .with_options({
        ["workflow.id"] = "order-123",
        ["workflow.execution_error_when_already_started"] = true,
    })

local pid, err = spawner:spawn("app:order_workflow", "app:worker", order)
if err then return nil, err end
```

```lua
-- Reuse existing (default behavior with explicit ID)
local spawner = process
    .with_options({
        ["workflow.id"] = "order-123",
    })

local pid, err = spawner:spawn("app:order_workflow", "app:worker", order)
if err then return nil, err end
-- Returns existing workflow PID if already running
```

| Policy | Behavior |
|--------|----------|
| `"use_existing"` | Return existing workflow PID (default with explicit ID) |
| `"fail"` | Return error if workflow exists |
| `"terminate_existing"` | Terminate existing and start new |



#### Workflow Start Options


Pass Temporal workflow options via `with_options()`:

```lua
local spawner = process.with_options({
    ["workflow.id"] = "order-123",
    ["workflow.execution_timeout"] = "24h",
    ["workflow.run_timeout"] = "1h",
    ["workflow.task_timeout"] = "30s",
    ["workflow.id_conflict_policy"] = "fail",
    ["workflow.retry_policy"] = {
        initial_interval = 1000,
        backoff_coefficient = 2.0,
        maximum_interval = 300000,
        maximum_attempts = 3,
    },
    ["workflow.cron_schedule"] = "0 */6 * * *",
    ["workflow.search_attributes"] = {
        customer_id = "cust-123"
    },
    ["workflow.memo"] = {
        source = "api"
    },
    ["workflow.start_delay"] = "5m",
    ["workflow.parent_close_policy"] = "terminate",
})
```



##### Options Reference


| Option | Type | Description |
|--------|------|-------------|
| `temporal.workflow.id` | string | Explicit workflow execution ID |
| `temporal.workflow.task_queue` | string | Override task queue |
| `temporal.workflow.execution_timeout` | duration | Total workflow execution timeout |
| `temporal.workflow.run_timeout` | duration | Single run timeout |
| `temporal.workflow.task_timeout` | duration | Workflow task processing timeout |
| `temporal.workflow.id_conflict_policy` | string | `use_existing`, `fail`, `terminate_existing` |
| `temporal.workflow.id_reuse_policy` | string | `allow_duplicate`, `allow_duplicate_failed_only`, `reject_duplicate` |
| `temporal.workflow.execution_error_when_already_started` | boolean | Error if workflow already running |
| `temporal.workflow.retry_policy` | table | Retry policy (see below) |
| `temporal.workflow.cron_schedule` | string | Cron expression for recurring workflows |
| `temporal.workflow.memo` | table | Non-indexed workflow metadata |
| `temporal.workflow.search_attributes` | table | Indexed queryable attributes |
| `temporal.workflow.enable_eager_start` | boolean | Start execution immediately |
| `temporal.workflow.start_delay` | duration | Delay before workflow starts |
| `temporal.workflow.parent_close_policy` | string | Child behavior on parent close |
| `temporal.workflow.wait_for_cancellation` | boolean | Wait for cancellation to finish |
| `temporal.workflow.namespace` | string | Temporal namespace override |
| `temporal.workflow.name` | string | Workflow type name to start, when it differs from the registry ID |
| `temporal.workflow.versioning_intent` | string | `compatible` (inherit the build ID) or `default` (use assignment rules) |
| `temporal.workflow.priority` | table | Task priority: `priority_key` (number), `fairness_key` (string), `fairness_weight` (number) |
| `workflow.summary` | string | Human-readable summary shown in the Temporal UI |
| `workflow.details` | string | Human-readable details shown in the Temporal UI |
| `workflow.versioning_override` | table | Worker versioning override: `mode` is `auto_upgrade`, or `pinned` with `deployment_name` and `build_id` |

Every option is also accepted under its short key (`workflow.id`, `workflow.task_queue`, ...); the `temporal.workflow.` prefix is a legacy alias. `summary` and `details` have no `temporal.workflow.` alias.

Duration values accept strings (`"5s"`, `"10m"`, `"1h"`) or milliseconds as numbers.

Legacy `temporal.workflow.*` aliases remain accepted for compatibility. New code should use the canonical `workflow.*` names shown above.

A pinned version override requires both the mode and deployment version:

```lua
["workflow.versioning_override"] = {
    mode = "pinned",
    version = {
        deployment_name = "orders",
        build_id = "orders-v2",
    },
}
```

Use the string `"auto_upgrade"` for an auto-upgrade override.



##### Parent Close Policy


Controls what happens to child workflows when the parent closes:

| Policy | Behavior |
|--------|----------|
| `"terminate"` | Terminate child workflow |
| `"abandon"` | Let child continue independently |
| `"request_cancel"` | Send cancellation request to child |



#### Startup Messages


Queue signals with a workflow start. The first non-empty startup message is sent atomically with the start. Remaining startup messages are sent sequentially in builder order after the workflow starts, but they can interleave with signals sent concurrently by other callers:

```lua
local spawner = process
    .with_options({})
    :with_name("counter-workflow")
    :with_message("increment", {amount = 2})
    :with_message("increment", {amount = 1})
    :with_message("increment", {amount = 4})

local pid, err = spawner:spawn_monitored(
    "app:counter_workflow",
    "app:worker",
    {initial = 0}
)
if err then return nil, err end
```

With the `use_existing` conflict policy, startup messages are still delivered when a second spawn resolves to an existing workflow:

```lua
-- First spawn starts the workflow with initial messages
local first = process
    .with_options({})
    :with_name("my-counter")
    :with_message("increment", {amount = 3})

local pid, first_err = first:spawn("app:counter_workflow", "app:worker", {initial = 0})
if first_err then return nil, first_err end

-- Second spawn reuses existing workflow and delivers new messages
local second = process
    .with_options({})
    :with_name("my-counter")
    :with_message("increment", {amount = 2})

local pid2, second_err = second:spawn("app:counter_workflow", "app:worker", {initial = 999})
if second_err then return nil, second_err end
-- pid2 == pid (same workflow), input {initial = 999} is ignored
-- But the increment message with amount=2 is delivered
```



#### Context Propagation


Pass context values that are accessible inside the workflow and its activities:

```lua
local spawner = process.with_context({
    user_id = "user-1",
    tenant = "tenant-1",
    request_id = "req-abc",
})

local pid, err = spawner:spawn_monitored(
    "app:order_workflow",
    "app:worker",
    order
)
if err then return nil, err end
```

Inside the workflow (or any activity it calls), read context via the `ctx` module:

```lua
local ctx = require("ctx")

local user_id, user_err = ctx.get("user_id")       -- "user-1"
if user_err then return nil, user_err end
local tenant, tenant_err = ctx.get("tenant")       -- "tenant-1"
if tenant_err then return nil, tenant_err end
local all, err = ctx.all()               -- {user_id="user-1", tenant="tenant-1", request_id="req-abc"}
if err then
    return nil, err
end
```



#### Security Context


The actor and scope of the caller travel with the workflow, separately from `ctx` values and under stronger rules. They are carried in two Temporal headers:

| Header | Content |
|--------|---------|
| `wippy-security` | JSON envelope: actor ID, actor metadata, policy IDs, and the audience |
| `wippy-security-signature` | HMAC-SHA256 over that envelope, keyed by the client's `security_hmac_key` |

The audience is the ID of the execution the header was minted for — the workflow ID for a start or a signal, the activity ID for an activity. A header replayed against a different execution fails the audience check, so a captured header cannot be reused elsewhere.

Verification happens before the workflow body runs. The signature must match one of the client's keys, the audience must equal this execution's ID, and every policy named in the envelope must resolve in the local security registry. **Any of those failing fails the workflow execution** — it is not a warning and the workflow does not run with a reduced context. The same is true of an envelope that is internally inconsistent, such as an actor without a scope or policies without an actor.

Configure the keys on the [`temporal.client`](temporal/overview.md#security-context-propagation) entry. Starting a workflow from a context that has an actor or a scope requires a signing key; without one the start fails rather than proceeding unsigned.



##### Secured workflows reject unsigned signals


A workflow running under a security context requires every incoming signal to carry a signed relay ticket — headers `wippy-relay-signal` and `wippy-relay-signal-signature` — bound to that workflow ID and that signal name. An unsigned or mis-addressed signal is rejected instead of delivered. Signals sent by Wippy processes through `process.send` are signed automatically. Signals injected from outside Wippy — the Temporal CLI, `tctl`, or another SDK — carry no ticket and therefore fail against a secured workflow. Drive a secured workflow only from Wippy.



##### Deterministic child and activity IDs


Under a security context, a child workflow or activity started without an explicit ID gets a derived one instead of a random one, because the ID is the audience the header is signed for and must be reproducible on replay:

| Started from a secured workflow | Generated ID |
|---------------------------------|--------------|
| Child workflow | `<parentWorkflowID>-<parentRunID>-child-<N>` |
| Activity | `<parentWorkflowID>-<parentRunID>-activity-<N>` |

`N` counts within the workflow execution. An explicitly supplied `temporal.workflow.id` or activity ID is used as-is and becomes the audience. Without a security context, IDs are left to Temporal as before.



#### From HTTP Handlers


```lua
local function handler()
    local req, req_err = http.request()
    if req_err then
        return nil, req_err
    end

    local body, body_err = req:body()
    if body_err then
        return nil, body_err
    end
    local order, decode_err = json.decode(body)
    if decode_err then
        return nil, decode_err
    end

    local request_id, header_err = req:header("X-Request-ID")
    if header_err then
        return nil, header_err
    end

    local spawner = process
        .with_context({request_id = request_id})
        :with_options({
            ["workflow.id"] = "order-" .. order.id,
            ["workflow.id_conflict_policy"] = "fail",
        })

    local pid, err = spawner:spawn(
        "app:order_workflow",
        "app:worker",
        order
    )

    local res, res_err = http.response()
    if res_err then
        return nil, res_err
    end
    if err then
        local status_err = res:set_status(409)
        if status_err then
            return nil, status_err
        end
        local write_err = res:write_json({error = tostring(err)})
        if write_err then return nil, write_err end
        return true
    end

    local status_err = res:set_status(202)
    if status_err then
        return nil, status_err
    end
    local write_err = res:write_json({
        workflow_id = tostring(pid),
        status = "started"
    })
    if write_err then return nil, write_err end
    return true
end
```



### Signals


Workflows receive signals via the process messaging system. Signals are durable - they survive workflow replays.



#### Inbox Pattern


Receive all messages through the process inbox:

```lua
local function main(order)
    local inbox = process.inbox()

    while true do
        local msg, open = inbox:receive()
        if not open then
            return nil, errors.new({kind = errors.INTERNAL, message = "workflow inbox closed"})
        end
        local topic = msg:topic()

        if topic == "approve" then
            break
        elseif topic == "cancel" then
            local payload = msg:payload()
            local data
            if payload then
                local payload_err
                data, payload_err = payload:data()
                if payload_err then return nil, payload_err end
            end
            local reason = type(data) == "table" and data.reason or nil
            return {status = "cancelled", reason = reason}
        end
    end

    return process_order(order)
end
```



#### Topic-Based Subscription


Subscribe to specific topics using `process.listen()`:

```lua
local function main(input)
    local results = {}
    local job_ch, job_err = process.listen("add_job")
    if job_err then return nil, job_err end
    local exit_ch, exit_err = process.listen("exit")
    if exit_err then return nil, exit_err end

    while true do
        local result = channel.select{
            job_ch:case_receive(),
            exit_ch:case_receive()
        }

        if result.channel == exit_ch then
            break
        elseif result.channel == job_ch then
            if not result.ok then
                break
            end
            local job_data = result.value
            local activity_result, err = funcs.call(
                "app:echo_activity",
                {job_id = job_data.id, data = job_data}
            )
            if err then
                return nil, err
            end
            table.insert(results, {
                job_id = job_data.id,
                result = activity_result
            })
        end
    end

    return {total_jobs = #results, results = results}
end
```

By default, `process.listen()` returns raw payload data. Use `{message = true}` to receive Message objects with sender information:

```lua
local ch, err = process.listen("request", {message = true})
if err then return nil, err end
local msg, open = ch:receive()
if not open then
    return nil, errors.new({kind = errors.INTERNAL, message = "request channel closed"})
end
local sender = msg:from()
local payload = msg:payload()
local data
if payload then
    local payload_err
    data, payload_err = payload:data()
    if payload_err then return nil, payload_err end
end
```



#### Serialized Signal Handling


Use one `channel.select()` loop when signals mutate shared workflow state. This preserves deterministic mutation order and lets the `finish` branch return without leaving blocked handler coroutines:

```lua
local function main(input)
    local counter = input.initial or 0

    local function send_reply(pid, topic, payload)
        local sent, err = process.send(pid, topic, payload)
        if err then error(err) end
        return sent
    end

    local function message_data(msg)
        local payload = msg:payload()
        if not payload then return nil end
        return payload:data()
    end

    local increment_ch, increment_err = process.listen("increment", {message = true})
    if increment_err then return nil, increment_err end
    local decrement_ch, decrement_err = process.listen("decrement", {message = true})
    if decrement_err then return nil, decrement_err end
    local finish_ch, finish_err = process.listen("finish", {message = true})
    if finish_err then return nil, finish_err end

    while true do
        local result = channel.select{
            increment_ch:case_receive(),
            decrement_ch:case_receive(),
            finish_ch:case_receive()
        }
        if not result.ok then
            return nil, errors.new({kind = errors.INTERNAL, message = "signal channel closed"})
        end

        local msg = result.value
        local reply_to = msg:from()

        if result.channel == finish_ch then
            send_reply(reply_to, "ack")
            send_reply(reply_to, "ok", {message = "finishing", value = counter})
            return {final_counter = counter}
        end

        local data, payload_err = message_data(msg)
        if payload_err then return nil, payload_err end

        if type(data) ~= "table" or type(data.amount) ~= "number" then
            send_reply(reply_to, "nak", "amount must be a number")
        elseif result.channel == decrement_ch and counter - data.amount < 0 then
            send_reply(reply_to, "nak", "would result in negative value")
        else
            send_reply(reply_to, "ack")
            if result.channel == increment_ch then
                counter = counter + data.amount
            else
                counter = counter - data.amount
            end
            send_reply(reply_to, "ok", {value = counter})
        end
    end
end
```



#### Signal Acknowledgment


Implement request-reply patterns by sending responses back to the sender:

```lua
-- Workflow side
local ch, err = process.listen("get_status", {message = true})
if err then return nil, err end
local msg, open = ch:receive()
if not open then return nil, errors.new({kind = errors.INTERNAL, message = "status channel closed"}) end
local sent, send_err = process.send(msg:from(), "status_response", {status = "processing", progress = 75})
if send_err then return nil, send_err end
```

```lua
-- Caller side
local response_ch, listen_err = process.listen("status_response")
if listen_err then return nil, listen_err end
local sent, send_err = process.send(workflow_pid, "get_status", {})
if send_err then return nil, send_err end

local timeout, timeout_err = time.after("5s")
if timeout_err then return nil, timeout_err end
local result = channel.select{
    response_ch:case_receive(),
    timeout:case_receive()
}

if result.channel == response_ch then
    if not result.ok then
        return nil, errors.new({kind = errors.INTERNAL, message = "status response channel closed"})
    end
    return result.value
end

if not result.ok then
    return nil, errors.new({kind = errors.INTERNAL, message = "status timeout channel closed"})
end
return nil, errors.new({kind = errors.TIMEOUT, message = "status request timed out", retryable = true})
```



#### Cross-Workflow Signaling


Workflows can send signals to other workflows using their PID:

```lua
-- Sender workflow
local function main(input)
    local target_pid = input.target
    local response_ch, listen_err = process.listen("cross_host_pong")
    if listen_err then return nil, listen_err end

    local ok, err = process.send(target_pid, "cross_host_ping", {data = "hello"})
    if err then
        return {ok = false, error = tostring(err)}
    end

    local response, open = response_ch:receive()
    if not open then
        return {ok = false, error = "cross_host_pong channel closed"}
    end
    return {ok = true, received = response}
end
```



#### Synchronous Child (workflow.exec)


Execute a child workflow and wait for the result:

```lua
local result, err = workflow.exec("app:child_workflow", input_data)
if err then
    return nil, err
end
```



#### Asynchronous Child (process.spawn)


Spawn a child workflow without blocking, then wait for its completion via events:

```lua
local events_ch = process.events()

local child_pid, err = process.spawn(
    "app:child_workflow",
    "app:worker",
    {message = "hello from parent"}
)
if err then
    return {status = "spawn_failed", error = tostring(err)}
end

-- Wait for child EXIT event
local event, open = events_ch:receive()
if not open then
    return nil, errors.new({kind = errors.INTERNAL, message = "process event channel closed"})
end

if event.kind == process.event.EXIT then
    local child_result = event.result.value
    local child_error = event.result.error
end
```



#### Error Propagation from Children


When a child workflow returns an error, it appears in the EXIT event:

```lua
local events_ch = process.events()
local child_pid, err = process.spawn(
    "app:error_child_workflow",
    "app:worker"
)
if err then
    return nil, err
end

local event, open = events_ch:receive()
if not open then
    return nil, errors.new({kind = errors.INTERNAL, message = "process event channel closed"})
end
if event.result.error then
    local child_err = event.result.error
    -- Error objects have kind(), retryable(), message() methods
    print(child_err:kind())       -- e.g. "NotFound"
    print(child_err:retryable())  -- false
    print(child_err:message())    -- error message text
end
```



#### Executing Workflows Synchronously (process.exec)


Run a workflow and wait for its result in one call:

```lua
local result, err = process.exec(
    "app:hello_workflow",
    "app:worker",
    {name = "world"}
)
if err then
    return nil, err
end
-- result contains the workflow return value
```



#### Post-Start Monitoring


Monitor a workflow after it has already started:

```lua
local pid, err = process.spawn(
    "app:long_workflow",
    "app:worker",
    {iterations = 100}
)
if err then
    return nil, err
end

-- Monitor later
local ok, monitor_err = process.monitor(pid)
if monitor_err then
    return nil, monitor_err
end

local events_ch = process.events()
local event, open = events_ch:receive()  -- EXIT when workflow completes
if not open then
    return nil, errors.new({kind = errors.INTERNAL, message = "process event channel closed"})
end
```



#### Post-Start Linking


Link to a running workflow to receive LINK_DOWN on abnormal termination:

```lua
local ok, err = process.set_options({trap_links = true})
if err then
    return nil, err
end

local pid, err = process.spawn(
    "app:long_workflow",
    "app:worker",
    {iterations = 100}
)
if err then
    return nil, err
end

-- Link after workflow has started
time.sleep("200ms")
local linked, link_err = process.link(pid)
if link_err then return nil, link_err end

-- If workflow is terminated, receive LINK_DOWN
local terminated, terminate_err = process.terminate(pid)
if terminate_err then return nil, terminate_err end

local events_ch = process.events()
local event, open = events_ch:receive()
if not open then
    return nil, errors.new({kind = errors.INTERNAL, message = "process event channel closed"})
end
-- event.kind == process.event.LINK_DOWN
```

LINK_DOWN events require `trap_links = true` in process options. Without it, a linked process termination propagates the failure.



#### Unmonitor / Unlink


Remove monitoring or linking:

```lua
local unmonitored, unmonitor_err = process.unmonitor(pid)
if unmonitor_err then return nil, unmonitor_err end
local unlinked, unlink_err = process.unlink(pid)
if unlink_err then return nil, unlink_err end
```

After unmonitoring or unlinking, events for that process are no longer delivered.



#### Terminate


Force-terminate a running workflow:

```lua
local ok, err = process.terminate(workflow_pid)
```

Monitored callers receive an EXIT event with an error.



#### Cancel


Request graceful cancellation with an optional reason:

```lua
local ok, err = process.cancel(workflow_pid, "cancelled by operator")
```



### Concurrent Work


Use `coroutine.spawn()` and channels for parallel work inside workflows:

```lua
local function main(input)
    local worker_count = input.workers or 3
    local job_count = input.jobs or 6

    local work_queue = channel.new(10)
    local results = channel.new(10)

    for w = 1, worker_count do
        coroutine.spawn(function()
            while true do
                local job, ok = work_queue:receive()
                if not ok then break end
                time.sleep(10 * time.MILLISECOND)
                results:send({worker = w, job = job, result = job * 2})
            end
        end)
    end

    for j = 1, job_count do
        work_queue:send(j)
    end
    work_queue:close()

    local total = 0
    local processed = {}
    for _ = 1, job_count do
        local r, open = results:receive()
        if not open then
            return nil, errors.new({kind = errors.INTERNAL, message = "results channel closed"})
        end
        total = total + r.result
        table.insert(processed, r)
    end

    return {total = total, processed = processed}
end
```

All channel operations and sleeps inside coroutines are replay-safe.



### Timers


Durable timers survive restarts:

```lua
local time = require("time")

time.sleep("24h")
time.sleep("5m")
time.sleep("30s")
time.sleep(100 * time.MILLISECOND)
```

Track elapsed time:

```lua
local start = time.now()
time.sleep("1s")
local elapsed = time.now():sub(start):milliseconds()
```



### Determinism


Workflow code must be deterministic. The same inputs must produce the same sequence of commands.



#### Replay-Safe Operations


These operations are automatically intercepted and their results recorded. On replay, recorded values are returned:

```lua
-- Activity calls
local data = funcs.call("app:fetch_data", id)

-- Durable sleep
time.sleep("1h")

-- Current time
local now = time.now()

-- UUID generation
local id = uuid.v4()

-- Crypto operations
local bytes = crypto.random.bytes(32)

-- Child workflows
local result = workflow.exec("app:child", input)

-- Versioning
local v = workflow.version("change-1", 1, 2)
```



#### Non-Deterministic (Avoid)


```lua
-- Don't use wall clock time
local now = os.time()              -- non-deterministic

-- Don't use random directly
local r = math.random()            -- non-deterministic

-- Don't do I/O in workflow code
local file = io.open("data.txt")   -- non-deterministic

-- Don't use global mutable state
counter = counter + 1               -- non-deterministic across replays
```



#### Activity Errors


Activity errors carry structured metadata:

```lua
local result, err = funcs.call("app:risky_activity", order)
if err then
    print(err:kind())       -- error classification (e.g. "NotFound", "Internal")
    print(err:retryable())  -- whether the error is retryable
    print(err:message())    -- human-readable error message
end
```



#### Activity Failure Modes


Configure retry behavior for activity calls:

```lua
local executor = funcs.new():with_options({
    ["activity.retry_policy"] = {
        maximum_attempts = 1,
    }
})

local result, err = executor:call("app:unreliable_activity", input)
if err then
    local kind = err:kind()         -- "Internal" for runtime errors
    local retryable = err:retryable()
end
```



#### Child Workflow Errors


Errors from child workflows (via `process.exec` or EXIT events) carry the same metadata:

```lua
local result, err = process.exec("app:error_workflow", "app:worker")
if err then
    print(err:kind())       -- e.g. "NotFound"
    print(err:retryable())  -- false
    print(err:message())    -- error details
end
```



### Compensation Pattern (Saga)


```lua
local function run_compensations(compensations)
    local first_err
    for _, comp in ipairs(compensations) do
        local _, err = funcs.call(comp.action, comp.args)
        if err and not first_err then
            first_err = err
        end
    end
    if first_err then return nil, first_err end
    return true
end

local function main(order)
    local compensations = {}

    local reservation, err = funcs.call("app:reserve_inventory", order.items)
    if err then
        return {status = "failed", step = "inventory", error = tostring(err)}
    end
    table.insert(compensations, 1, {
        action = "app:release_inventory",
        args = reservation.id
    })

    local payment, err = funcs.call("app:charge_payment", order.payment)
    if err then
        local _, compensation_err = run_compensations(compensations)
        if compensation_err then
            return {status = "failed", step = "payment", error = tostring(err), compensation_error = tostring(compensation_err)}
        end
        return {status = "failed", step = "payment", error = tostring(err)}
    end
    table.insert(compensations, 1, {
        action = "app:refund_payment",
        args = payment.id
    })

    local shipment, err = funcs.call("app:ship_order", order.shipping)
    if err then
        local _, compensation_err = run_compensations(compensations)
        if compensation_err then
            return {status = "failed", step = "shipping", error = tostring(err), compensation_error = tostring(compensation_err)}
        end
        return {status = "failed", step = "shipping", error = tostring(err)}
    end

    return {status = "completed", tracking = shipment.tracking}
end
```

Compensations run in reverse registration order. If more than one compensation
fails, the workflow still attempts the remaining actions and reports the first
failure through `compensation_error`.



### See Also


- [Overview](temporal/overview.md) - Client and worker configuration
- [Activities](temporal/activities.md) - Activity definitions and options
- [Process](lua/core/process.md) - Process management API
- [Functions](lua/core/funcs.md) - Function invocation
- [Channels](lua/core/channel.md) - Channel operations



---

# "Process Host"

## Process Host


A `process.host` runs Lua and WebAssembly processes on a work-stealing scheduler. This page is a configuration and lifecycle reference; the YAML block is an entry fragment.

<note>
Each host schedules processes independently. Load is not distributed between hosts automatically.
</note>



### Entry Kind


| Kind | Description |
|------|-------------|
| `process.host` | Process execution host with scheduler |



### Configuration


```yaml
- name: main_host
  kind: process.host
  host:
    workers: 8
    queue_size: 1024
    local_queue_size: 256
  lifecycle:
    auto_start: true
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `workers` | int | NumCPU | Worker goroutines |
| `queue_size` | int | 1024 | Initial global queue capacity |
| `local_queue_size` | int | 256 | Initial per-worker local deque capacity |

Both queues grow when their initial capacity is exhausted. Values must be
positive after defaults are applied. The global queue clamps its effective
initial capacity to at least 16; each local deque rounds its capacity up to a
power of two.



### Lifecycle


A process host is a supervisor-managed service. `lifecycle.auto_start` defaults
to `false`; a host that has not started rejects process spawns. The standard
lifecycle fields also apply, including `requires`, `startup`, `start_timeout`,
`stop_timeout`, `stable_threshold`, `restart`, and `security`.

Stopping a host is terminal for that host instance. The scheduler sends a
cancellation event to each process, waits for them to drain until the stop
context expires, then cancels and closes any remaining processes.

Live updates may resize `host.workers`. Changes to queue sizes or lifecycle
configuration are rejected and require replacing the host. When CPU affinity
manages the worker set, the worker count cannot be changed live either.



### Scheduler


The scheduler uses work-stealing: each worker has a local deque, and idle workers steal from the global queue or other workers. This balances load automatically.

- **Workers** execute processes concurrently.
- **Global queue** holds pending processes when all workers are busy.
- **Local queues** reduce contention by keeping work close to workers.



### Process Types


Process hosts execute entries of these kinds:

| Kind | Description |
|------|-------------|
| `process.lua` | Source-based Lua process |
| `process.lua.bc` | Precompiled Lua bytecode |
| `process.wasm` | WebAssembly process (experimental) |

Processes run independently with their own frame context and communicate via
messages. Security configured on the process entry is applied to that process
frame before execution. Monitors, links, and application supervisors can react
to failure; the process host does not automatically restart every failed
process.



### See Also


- [Process Module](lua/core/process.md) - Spawn and manage processes from Lua
- [WASM Processes](wasm/processes.md) - Configuring `process.wasm` entries
- [Process Model](concepts/process-model.md) - Lifecycle and supervision concepts
- [Supervision](guides/supervision.md) - Building supervision trees



---

# "Process Groups"

## Process Groups


A `pg.scope` lets processes join named groups and receive broadcasts addressed to a group. The model follows Erlang/OTP `pg`: groups are created on first join, a process can belong to many groups and join one group multiple times, and each cluster node maintains its own membership state and reconciles with peers over the internode mesh. This page is a configuration and behavior reference; the YAML blocks are entry fragments.

The Lua API is documented in [Process Groups](lua/core/pg.md); this page covers the scope entry kind and its configuration. See the [Cluster Guide](guides/cluster.md) for the surrounding membership model.



### Entry Kind


| Kind | Description |
|------|-------------|
| `pg.scope` | An independent process-group namespace with its own membership state and cluster mesh |

Each scope is isolated: groups and members in one scope are invisible to another. A process opens a scope by its entry ID (`pg.open("app:pg")`) and operates within it.

```yaml
- name: pg
  kind: pg.scope
  lifecycle:
    auto_start: true
```



### Configuration


All fields are optional. The table lists their defaults.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `protocol_timeout` | duration | 5s | Timeout for inter-node sync/discover operations |
| `broadcast_timeout` | duration | 5s | Timeout for delivering a broadcast to a single member |
| `anti_entropy_interval` | duration | 30s | Cadence of the reconcile loop; one peer is synced per tick |
| `circuit_breaker_failures` | int | 3 | Consecutive send failures to a node before its circuit opens |
| `circuit_breaker_reset_time` | duration | 10s | Wait before an open circuit moves to half-open for a test send |
| `max_retries` | int | 3 | Retry attempts for a failed broadcast |
| `retry_base_delay` | duration | 100ms | Initial backoff delay between retries |
| `retry_max_delay` | duration | 1s | Maximum backoff delay |
| `action_queue_size` | int | 256 | Depth at which an "approaching capacity" warning is logged |
| `action_queue_max_size` | int | 1024 | Hard capacity of the internal event-loop queue; operations are dropped when full |
| `monitor_buffer` | int | 64 | Per-subscription event channel capacity; events drop for a subscriber whose buffer fills |
| `max_groups` | int | 0 | Maximum distinct groups (0 = unlimited) |
| `max_members_per_group` | int | 0 | Maximum members per group, counting multi-joins (0 = unlimited) |

```yaml
- name: pg
  kind: pg.scope
  anti_entropy_interval: 30s
  circuit_breaker_failures: 3
  max_members_per_group: 10000
  lifecycle:
    auto_start: true
```



### How It Works


**Single-writer state.** Each scope runs a single-goroutine event loop (the gen_server pattern). All mutations are serialized through it; reads of members and groups are served from atomically-published snapshots, so they never block the loop.

**Join/leave propagation.** A local join or leave is applied to the loop and then fanned out to the union of the live membership peers and any previously-discovered remote nodes. Sending to that union ensures a freshly joined or not-yet-converged node still receives the change.

**Broadcast.** `broadcast` snapshots the full cross-cluster member list inside the loop, then delivers to each member outside the loop so a slow recipient cannot stall the scope. `broadcast_local` does the same but only for members on the local node.

**Monitor and events.** Subscribing and snapshotting the current members happen in one event-loop tick, so a subscriber never misses or double-counts a change that races the subscription. Subscribers receive `member.joined` / `member.left` events; a leave for a process that joined N times reports the PID N times, preserving multiplicity.

**Anti-entropy and discovery.** On start, a scope sends discover messages to a small random subset of peers (capped to avoid an N² storm when many nodes restart at once). When a node joins, it receives a full state sync. The anti-entropy loop then periodically pushes a full sync to one peer at a time, so any broadcast a peer missed eventually converges. The receiver applies a differential sync — only members actually added or removed emit events.

**Circuit breakers.** A per-node circuit breaker tracks consecutive send failures. After `circuit_breaker_failures` failures it opens and sends to that node are skipped until `circuit_breaker_reset_time` elapses, when one test send is allowed. Join/leave broadcasts that hit an open breaker are retried with exponential backoff up to `max_retries`.



### Observability


A liveness health check (`pg.broadcast_recent.<scope>`) reports unhealthy if a scope sees no broadcast traffic for an extended period, surfacing a wedged event loop or a persistent partition. See the [Observability Guide](guides/observability.md).



### See Also


- [Process Groups](lua/core/pg.md) - The Lua API
- [Cluster](guides/cluster.md) - Membership and the clustering model
- [Process Model](concepts/process-model.md) - Processes, PIDs, and messaging



---

# "Terminal"

## Terminal


A `terminal.host` executes Lua scripts with standard input, output, and error streams. This page is a configuration reference; the Lua block is a handler fragment that assumes it is running through that host.

<note>
A terminal host runs exactly one process at a time. The process itself is a regular Lua process with access to terminal I/O context.
</note>



### Entry Kind


| Kind | Description |
|------|-------------|
| `terminal.host` | Terminal session host |



### Configuration


```yaml
- name: cli_host
  kind: terminal.host
  hide_logs: false
  lifecycle:
    auto_start: true
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `hide_logs` | bool | false | Stream logs to the event bus while suppressing downstream log propagation |



### Terminal Context


Scripts running on a terminal host receive a terminal context with:

- **stdin** — Standard input reader
- **stdout** — Standard output writer
- **stderr** — Standard error writer
- **args** — Command-line arguments



### Composable Terminals


The terminal a process sees is a port, not a device. That makes terminal ownership composable.

A process on a terminal host holds the physical port. It calls `tty.surface()` to take the port's presentation lease and publishes complete frames — it owns the whole screen.

A shell process hosts other processes by creating virtual terminals with `tty.viewport()`. It passes `viewport:grant()` to a child through the `terminal` spawn option; the child resolves that grant into an ordinary terminal port and runs unchanged, unaware that it is not attached to a device. The shell reads the child's frames with `viewport:snapshot()`, places them anywhere in its own layout, and translates input into the child's coordinates with `viewport:send()`.

```lua
local view = assert(tty.viewport({width = 78, height = 20}))
local child = assert(process.with_options({terminal = assert(view:grant())})
    :spawn_monitored("app:child", "app:workers"))
```

A grant is one-shot: process admission consumes it, a rejected start leaves it unresolved, and a host that cannot attach terminals rejects the spawn rather than dropping the option.

Byte-oriented programs join the same model through `exec`. A child allocates a PTY process and calls `process:attach_terminal()`; that adapter owns PTY emulation, input encoding, resize, and termination, and presents onto whichever port the child holds — physical or virtual.

```text
physical terminal -> shell surface -> viewport -> child process -> PTY proxy
```



### Lua API


The [IO Module](lua/system/io.md) provides line-oriented terminal operations:

```lua
local io = require("io")

local _, write_err = io.write("Enter name: ")
if write_err then return nil, write_err end

local name, read_err = io.readline()
if read_err then return nil, read_err end

local _, print_err = io.print("Hello, " .. name)
if print_err then return nil, print_err end

local args = io.args()
```

`io.write`, `io.print`, and `io.readline` return errors outside a terminal context. `io.args()` returns an empty table when no terminal context is available.

For raw input events, styled rendering, surfaces, and viewports, see [TTY](lua/system/tty.md). For PTY processes and terminal sessions, see [Command Execution](lua/dynamic/exec.md).



### See Also


- [Terminal I/O](lua/system/io.md) — stdin/stdout/stderr operations
- [TTY](lua/system/tty.md) — Input events, surfaces, canvases, and viewports
- [Command Execution](lua/dynamic/exec.md) — PTY processes and terminal sessions
- [Terminal UI](tutorials/tty.md) — build a shell that hosts a child in a viewport



---

# "Database System"

## Database System


Wippy provides pooled SQL database entries for PostgreSQL and MySQL, plus a single-connection SQLite entry.

This page is a configuration reference. Unless a fence includes `version`, `namespace`, and `entries`, treat it as a fragment to place inside an existing entry list.



### Entry Kinds


| Kind | Description |
|------|-------------|
| `db.sql.postgres` | PostgreSQL database |
| `db.sql.mysql` | MySQL database |
| `db.sql.sqlite` | SQLite database |



#### Standard Databases (PostgreSQL, MySQL)


```yaml


## src/data/_index.yaml

version: "1.0"
namespace: app.data

entries:
  - name: main_db
    kind: db.sql.postgres
    host: "localhost"
    port: 5432
    database: "myapp"
    username: "dbuser"
    password: ${env:app.secrets:db_password}
    pool:
      max_open: 25
      max_idle: 5
      max_lifetime: "1h"
    options:
      sslmode: "disable"
    lifecycle:
      auto_start: true
```



#### SQLite


```yaml
  - name: cache_db
    kind: db.sql.sqlite
    file: "/var/data/cache.db"  # Use :memory: for in-memory
    pool:
      max_open: 4
      max_idle: 2
      max_lifetime: "1h"
    lifecycle:
      auto_start: true
```

<note>
A private in-memory SQLite database (<code>file: ":memory:"</code>) is scoped to one physical connection, so <code>max_open</code> and <code>max_idle</code> are forced to <code>1</code>. A file-backed database honors the configured <code>pool</code> settings, which a CDC snapshot read transaction needs so it does not consume the only writer connection. Journal mode is always <code>WAL</code>.
</note>



#### Standard Database Fields


| Field | Type | Description |
|-------|------|-------------|
| `host` | string | Database host address |
| `port` | int | Database port number |
| `database` | string | Database name |
| `username` | string | Database user |
| `password` | string | Database password |
| `pool` | object | Connection pool settings |
| `options` | map | Database-specific options |
| `lifecycle` | object | Lifecycle configuration |



#### SQLite Fields


| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `file` | string | required | Database file path or `:memory:` |
| `pool` | object | - | Connection pool settings; `max_open` and `max_idle` are forced to `1` for `:memory:` |
| `max_mutation_changes` | int | 100000 | Rows one transaction may hold in the committed-mutation observer |
| `max_mutation_bytes` | int | 67108864 | Logical bytes one transaction may hold in the observer (64 MiB) |
| `options` | map | - | Accepted but ignored |
| `lifecycle` | object | - | Lifecycle configuration |

`max_mutation_changes` and `max_mutation_bytes` bound the in-memory committed-mutation observer that feeds a [`db.cdc.sqlite`](system/cdc.md) source. Zero on either field selects the default; negative values are rejected. The bounds are conservative rather than exact: SQLite delivers a complete row to the pre-update hook, so one row can materialize before the bound rejects the candidate.



#### Secret and Environment Values


Pull connection values from the [environment registry](system/env.md) with `${env:NAME}` placeholders, resolved at decode time. `NAME` is a registered variable's public name or its entry ID (e.g. `app.secrets:db_password`); it is not a raw OS env var.

```yaml
- name: prod_db
  kind: db.sql.postgres
  host: ${env:DB_HOST}
  port: ${env:DB_PORT|5432}
  database: ${env:DB_NAME}
  username: ${env:DB_USER}
  password: ${env:app.secrets:db_password}
```

<note>
Older configurations use a sibling <code>&lt;field&gt;_env</code> directive (<code>host_env</code>, <code>port_env</code>, <code>database_env</code>, <code>username_env</code>, <code>password_env</code>) that resolves the same way. This form is <b>deprecated</b> — migrate it to the <code>${env:NAME}</code> placeholder shown above.
</note>

<warning>
Avoid hardcoding passwords in configuration. Use <code>env.variable</code> entries for credentials. See <a href="./env.md">Environment</a> for secret configuration.
</warning>



### Connection Pool


Configure connection pooling behavior. Pool settings map to Go's [database/sql connection pool](https://pkg.go.dev/database/sql#DB.SetMaxOpenConns).

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `max_open` | int | 0 | Maximum open connections (0 = unlimited) |
| `max_idle` | int | 0 | Maximum idle connections (0 = no idle connections retained) |
| `max_lifetime` | duration | 1h | Maximum connection lifetime |

```yaml
pool:
  max_open: 25      # Limit concurrent connections
  max_idle: 5       # Keep 5 connections ready
  max_lifetime: "30m"  # Recycle connections every 30 minutes
```

<tip>
Set <code>max_idle</code> less than or equal to <code>max_open</code>. Connections exceeding <code>max_lifetime</code> are closed and replaced, helping recover from stale connections.
</tip>



### DSN Formats


Each database type constructs a DSN from configuration. Any `options` are appended (sorted by key); none are included by default.



#### PostgreSQL {id="dsn-postgresql"}


```
host='host' port=port user='username' password='password' dbname='database' [option='value' ...]
```

Every value except the port is single-quoted, and embedded `'` and `\` are backslash-escaped, so hosts, passwords and option values containing spaces or quotes are passed through intact.



#### MySQL {id="dsn-mysql"}


```
username:password@tcp(host:port)/database[?option=value&...]
```



#### SQLite {id="dsn-sqlite"}


```
file:/path/to/database.db?mode=rwc
:memory:
```



### Database Options


Common database-specific options:



#### PostgreSQL {id="options-postgresql"}


```yaml
options:
  sslmode: "require"      # disable, require, verify-ca, verify-full
  connect_timeout: "10"   # Connection timeout in seconds
  application_name: "myapp"
```



#### MySQL {id="options-mysql"}


```yaml
options:
  charset: "utf8mb4"
  parseTime: "true"       # Parse time values to time.Time
  loc: "Local"            # Timezone
```



#### SQLite {id="options-sqlite"}


SQLite does not apply the `options` map to its DSN. File databases always open with `mode=rwc`, and journal mode is always set to `WAL`. The `options` field is accepted but ignored.



#### PostgreSQL with SSL


```yaml
- name: secure_postgres
  kind: db.sql.postgres
  host: "db.example.com"
  port: 5432
  database: "production"
  username: "app_user"
  password: ${env:app.secrets:db_password}
  pool:
    max_open: 50
    max_idle: 10
    max_lifetime: "1h"
  options:
    sslmode: "verify-full"
    sslcert: "/certs/client.crt"
    sslkey: "/certs/client.key"
    sslrootcert: "/certs/ca.crt"
  lifecycle:
    auto_start: true
```



#### MySQL Read Replica


```yaml
- name: mysql_replica
  kind: db.sql.mysql
  host: "replica.db.example.com"
  port: 3306
  database: "app"
  username: "readonly"
  password: ${env:app.secrets:replica_password}
  pool:
    max_open: 20
    max_idle: 5
    max_lifetime: "30m"
  options:
    charset: "utf8mb4"
    parseTime: "true"
    readTimeout: "30s"
```



#### SQLite In-Memory


```yaml
- name: test_db
  kind: db.sql.sqlite
  file: ":memory:"
```



#### Multiple Database Setup


```yaml
entries:
  # Primary database
  - name: users_db
    kind: db.sql.postgres
    host: ${env:USERS_DB_HOST}
    port: 5432
    database: "users"
    username: ${env:USERS_DB_USER}
    password: ${env:app.secrets:users_db_password}
    lifecycle:
      auto_start: true

  # Analytics database
  - name: analytics_db
    kind: db.sql.mysql
    host: ${env:ANALYTICS_DB_HOST}
    port: 3306
    database: "analytics"
    username: ${env:ANALYTICS_DB_USER}
    password: ${env:app.secrets:analytics_db_password}
    lifecycle:
      auto_start: true

  # Local cache
  - name: cache
    kind: db.sql.sqlite
    file: "/var/cache/app.db"
    lifecycle:
      auto_start: true
```



### Runtime Registration


Databases can be registered at runtime using the [registry module](lua/core/registry.md).



### Lua API


See [SQL Module](lua/storage/sql.md) for query, transaction, and connection operations.



### See Also


- [SQL Module](lua/storage/sql.md) - Lua API reference
- [Store](system/store.md) - Key-value store backed by a `db.sql.*` database
- [Queue](system/queue.md) - SQL-backed queue handler
- [Change Data Capture](system/cdc.md) - Streaming row-level changes from a `db.sql.sqlite` or Postgres database



---

# "Change Data Capture"

## Change Data Capture


Stream row-level changes from a database. A CDC source captures inserts, updates and deletes, optionally hands each subscriber a consistent snapshot of existing rows first, and delivers everything as driver-neutral change events. Sources are addressable by their entry ID and consumed from Lua via the [`cdc` module](lua/storage/cdc.md).



### Entry Kinds


| Kind | Description |
|------|-------------|
| `db.cdc.postgres` | Postgres logical replication (`pgoutput` plugin) |
| `db.cdc.sqlite` | SQLite writes observed through a `db.sql.sqlite` resource |

Both kinds expose the same Lua API, the same source info record and the same change event shape. What differs is the guarantee set, published per source as [capabilities](#capabilities).



### Postgres Configuration


```yaml
- name: pg_cdc
  kind: db.cdc.postgres
  host: ${env:DB_HOST}
  port: 5432
  database: app
  username: ${env:DB_USER}
  password: ${env:app.secrets:db_password}
  slot_name: wippy_slot
  publication: wippy_pub
  tables:
    - public.users
    - public.orders
  snapshot: true
  streaming: true
  standby_interval: "10s"
  status_interval: "10s"
  lifecycle:
    auto_start: true
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `host` | string | required | Postgres host |
| `port` | int | required | Postgres port (must be > 0) |
| `database` | string | required | Database name |
| `username` | string | required | Replication user (must have `REPLICATION` privilege) |
| `password` | string | required | Password (inline or `${env:NAME}`) |
| `slot_name` | string | required | Logical replication slot name |
| `publication` | string | - | Postgres publication; required when `tables` is empty |
| `tables` | []string | - | Tables to capture (`schema.table`); omit to use the publication's tables |
| `snapshot` | bool | false | Entry default for the per-subscriber snapshot handoff |
| `streaming` | bool | false | Use the streaming `pgoutput` protocol version |
| `temporary` | bool | false | Use a temporary replication slot (removed on disconnect) |
| `failover` | bool | false | Enable failover slot mode (mutually exclusive with `temporary`) |
| `standby_interval` | duration | `10s` | Standby status message interval (e.g. `10s`) |
| `status_interval` | duration | `30s` | Status update interval to the server |
| `snapshot_fetch_size` | int | 1000 | Rows fetched per snapshot batch (must be >= 0) |
| `max_transaction_changes` | int | 1000000 | Maximum changes buffered while decoding one transaction |
| `max_transaction_bytes` | int | 268435456 | Maximum logical bytes buffered while decoding one transaction (256 MiB) |
| `max_inflight_changes` | int | 1000000 | Maximum changes held across all in-flight transactions |
| `max_inflight_bytes` | int | 268435456 | Maximum logical bytes held across all in-flight transactions (256 MiB) |
| `subscriptions` | object | - | Subscription admission limits, see [Subscription Limits](#subscription-limits) |
| `options` | map | - | Extra connection options |
| `lifecycle` | object | - | Lifecycle configuration |

Zero on any `max_*` field selects the default; the decoder is never unbounded. Negative values are rejected.

Credentials resolve `${env:NAME}` placeholders through the [environment registry](system/env.md) at decode time.



### SQLite Configuration


A SQLite source does not open its own database. It borrows an existing [`db.sql.sqlite`](system/database.md) resource and subscribes to that resource's committed-mutation observer, so it captures exactly the writes made through that Wippy SQL resource — writes by another process, another connection or an external tool are not observed.

```yaml
- name: cdcdb
  kind: db.sql.sqlite
  file: /var/data/app.db
  lifecycle:
    auto_start: true

- name: changes
  kind: db.cdc.sqlite
  db_resource: app:cdcdb
  tables:
    - users
    - orders
  snapshot: true
  status_interval: "30s"
  lifecycle:
    auto_start: true
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `db_resource` | string | required | Entry ID of the `db.sql.sqlite` resource to observe |
| `name` | string | - | Accepted; the source name is always the entry ID |
| `tables` | []string | - | Tables to capture; omit for all tables |
| `snapshot` | bool | false | Entry default for the per-subscriber snapshot handoff |
| `status_interval` | duration | `30s` | Status update interval |
| `subscriptions` | object | - | Subscription admission limits, see [Subscription Limits](#subscription-limits) |
| `lifecycle` | object | - | Lifecycle configuration |

The source declares the SQL resource as a lifecycle requirement, so the supervisor starts the database first and restarts the source when the database generation is replaced.

<note>
SQLite capture requires a runtime built with the <code>sqlite_preupdate_hook</code> build tag. Official builds include it. Without the tag the driver fails closed: creating a <code>db.cdc.sqlite</code> entry returns <code>sqlite cdc requires the sqlite_preupdate_hook build tag</code> rather than starting a source that captures nothing.
</note>



### Subscription Limits


Each source admits a bounded number of subscribers and reserves their worst-case backlog up front. A snapshot slot stays reserved until the snapshot-enabled stream closes.

```yaml
subscriptions:
  max_subscriptions: 1024
  max_snapshot_subscriptions: 4
  max_bytes: 268435456
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `max_subscriptions` | int | 1024 | Concurrent subscriptions admitted by the source |
| `max_snapshot_subscriptions` | int | 4 | Concurrent snapshot-enabled subscriptions |
| `max_bytes` | int | 268435456 | Total reserved subscriber backlog bytes (256 MiB) |

Zero selects the default; negative values are rejected. Exhausting a limit fails the subscription with a retryable `errors.UNAVAILABLE`.



### How It Works


1. A Postgres source connects as a replication user and creates (or resumes) the slot named by `slot_name`. A SQLite source borrows its `db_resource` and subscribes to that resource's committed-mutation observer.
2. Row changes are decoded into driver-neutral change events with `op` of `insert`, `update`, `delete` or `truncate`.
3. A subscriber whose stream has `snapshot` enabled — from the entry's `snapshot` field or from `opts.snapshot` on the stream — first receives the existing rows as events with `op = "snapshot"`, then continues into live changes with no gap between the two.
4. A Postgres source periodically acknowledges the LSN so the server can release WAL segments (`standby_interval`).
5. The source registers under its entry ID; Lua code subscribes with [`cdc.stream`](lua/storage/cdc.md).



### Capabilities


Every source publishes what it guarantees, so consumers branch on capabilities rather than on the entry kind.

| Capability | `db.cdc.postgres` | `db.cdc.sqlite` | Meaning |
|------------|:-----------------:|:---------------:|---------|
| `snapshot` | yes | yes | Supports the atomic snapshot/live handoff |
| `capture_resume` | yes, unless `temporary` | no | Source progress survives a reconnect |
| `replayable` | no | no | Individual subscribers can replay past events |
| `captures_external_writes` | yes | no | Captures writes made outside this runtime |
| `before_images` | no | yes | Guarantees a full pre-change row image on `update` and `delete` |
| `coalesced` | no | yes | Repeated writes to a row within a transaction may arrive coalesced |

Capability flags describe source progress, not durable delivery: no driver replays events for an individual subscriber that fell behind or disconnected.



### Source Info


Each source is described by an info record, returned by `cdc.source` and `cdc.list_sources`.

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Entry ID |
| `kind` | string | `db.cdc.postgres` or `db.cdc.sqlite` |
| `name` | string | Source name (the entry ID) |
| `state` | string | `unknown`, `starting`, `running`, `faulted` or `stopped` |
| `generation` | string | Current source generation; changes when the source is replaced |
| `epoch` | string | Same value as `generation` |
| `engine` | string | Engine name (`sqlite`) |
| `db_resource` | string | Observed SQL resource entry ID (`db.cdc.sqlite`) |
| `slot` | string | Replication slot name (`db.cdc.postgres`) |
| `publication` | string | Postgres publication, when configured |
| `tables` | []string | Captured tables, when configured |
| `streaming` | bool | Whether the source is currently running |
| `failover` | bool | Failover slot mode (`db.cdc.postgres`) |
| `temporary` | bool | Temporary slot (`db.cdc.postgres`) |
| `snapshot` | bool | Entry-level snapshot default |
| `faulted` | bool | Whether the source is in the `faulted` state |
| `error` | string | Last source error, when one is recorded |
| `admission` | object | `active`, `snapshots`, `reserved_bytes`, `rejected` |
| `capabilities` | object | See [Capabilities](#capabilities) |

`admission` counts reservations, not queue fill: `active` is the admitted subscription count, `snapshots` the snapshot-enabled subset, `reserved_bytes` the reserved backlog budget, and `rejected` the cumulative number of subscriptions refused by the limits.



### Permissions


| Action | Resource | Description |
|--------|----------|-------------|
| `cdc.source` | Source entry ID | Read source info; also filters `cdc.list_sources` |
| `cdc.subscribe` | Source entry ID | Open a change stream |

CDC authority is separate from database access: a source can expose every captured row, including before images. Stream filters narrow delivery only; they never grant access to a source.

```yaml
- name: cdc_reader
  kind: security.policy
  policy:
    effect: allow
    actions: [cdc.source, cdc.subscribe]
    resources: [app:changes]
```



### See Also


- [CDC Module](lua/storage/cdc.md) - Lua streaming API
- [Database](system/database.md) - SQL database services
- [Environment](system/env.md) - Resolving credentials via `${env:NAME}`
- [Security](system/security.md) - Policies and actions



---

# "Store (Key-Value)"

## Store (Key-Value)


Wippy provides TTL-aware key-value stores backed by memory, SQL, Raft, or a CRDT.

This page is an entry-configuration reference. The YAML fences are fragments for an existing entry list, and the SQL fence is schema setup that must run before a `store.sql` entry starts.



### Entry Kinds


| Kind | Description |
|------|-------------|
| `store.memory` | In-memory store with automatic cleanup |
| `store.sql` | SQL-backed store with persistence |
| `store.kv.raft` | Cluster-replicated, strongly-consistent KV on the shared Raft |
| `store.kv.crdt` | Cluster-replicated, eventually-consistent KV over gossip (CRDT) |



### Memory Store


```yaml
- name: sessions
  kind: store.memory
  max_size: 10000
  cleanup_interval: "5m"
  lifecycle:
    auto_start: true
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `max_size` | int | 10000 | Maximum entries; 0 is replaced with the default (10000) |
| `cleanup_interval` | duration | 5m | Expired entry cleanup interval |

When `max_size` is reached, new entries are rejected. Data is lost on restart.



### SQL Store


```yaml
- name: cache
  kind: store.sql
  database: app:postgres
  table_name: kv_store
  cleanup_interval: "10m"
  lifecycle:
    auto_start: true
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `database` | reference | required | Database entry reference |
| `table_name` | string | required | Table name for storage |
| `id_column_name` | string | key | Column for keys |
| `payload_column_name` | string | value | Column for values |
| `expire_column_name` | string | expires_at | Column for expiration |
| `cleanup_interval` | duration | 0 | Expired entry cleanup interval |

Column names are validated against SQL injection. The following prerequisite is PostgreSQL DDL; use the equivalent binary/blob and timestamp types for MySQL or SQLite:

```sql
CREATE TABLE kv_store (
    key VARCHAR(255) PRIMARY KEY,
    value BYTEA NOT NULL,
    expires_at TIMESTAMPTZ NULL
);

CREATE INDEX idx_expires_at ON kv_store(expires_at) WHERE expires_at IS NOT NULL;
```



### Cluster KV Stores


`store.kv.raft` and `store.kv.crdt` replicate key-value data across cluster nodes. Both require [clustering](guides/cluster.md) to be enabled and reuse the same [Store Module](lua/storage/store.md) Lua API. Each entry is a namespaced view into one node-wide engine; `namespace` isolates this entry's keys and must match `^[a-z][a-z0-9._-]*$` (it may not start with `_`).



#### Raft (strong consistency)


```yaml
- name: deployments
  kind: store.kv.raft
  namespace: deploy
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `namespace` | string | Yes | Key namespace in the shared engine |

Writes are proposed through the shared Raft (followers forward to the leader); reads are linearizable. Conditional writes (`put` with `only_if_absent`/`if_version`) are supported. Raft state is fs-durable by default under `cluster.raft.data_dir` (default `~/.wippy/store`); see [Configuration](guides/configuration.md#cluster).



#### CRDT (eventual consistency)


```yaml
- name: sessions
  kind: store.kv.crdt
  namespace: sess
  durable: false
```

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `namespace` | string | Yes | - | Key namespace |
| `durable` | bool | No | false | Persist fs snapshots so the namespace survives a full-cluster restart |

Writes mutate local state and disseminate over gossip; conflicting concurrent writes converge last-writer-wins. Reads are local. Conditional writes are not supported. With `durable: false` the store is in-memory and reconstructs from peers; with `durable: true` it snapshots to `<data_dir>/_sys/kvcrdt`.

<note>
<code>data_dir</code> is node-level (<code>cluster.raft.data_dir</code>), not per-entry. The shared Raft state and durable CRDT snapshots live under <code>&lt;data_dir&gt;/_sys/</code>.
</note>



### TTL Behavior


All four store kinds accept time-to-live values, but expiry visibility differs by backend.

- `store.memory` treats an expired key as missing on read and removes expired entries on its `cleanup_interval`, which defaults to `5m`. A configured zero value is replaced by that default.
- `store.sql` filters expired rows on read and removes them on `cleanup_interval`; its default of `0` disables background cleanup without making expired rows readable.
- `store.kv.raft` attaches expiring keys to leader-driven leases. The roughly one-second lease sweep proposes the deletion through Raft, so a key may remain readable until that consensus-applied removal lands.
- `store.kv.crdt` also removes expired keys during its roughly one-second lease sweep, then gossips the resulting tombstone. The lease deadline itself is local to the node that accepted the write; if that origin fails before expiry, another node does not independently reproduce the deadline and the key can remain until later state or administrative cleanup removes it.



### Lua API


See [Store Module](lua/storage/store.md) for operations: `get`, `set`, `has`, `delete`, plus `put`, `entry`, `list`, and `info` for versioned and conditional access.



### See Also


- [Store Module](lua/storage/store.md) - Lua API reference
- [Database](system/database.md) - SQL backing for `store.sql`



---

# "Queue"

## Queue


The queue system connects asynchronous message publishers, drivers, queues, consumers, and handler functions.

This page is a configuration and behavior reference. YAML fences are fragments for an existing entry list unless they show a complete document; external-driver examples assume the broker or AWS-compatible service already exists.



### Architecture


```mermaid
flowchart LR
    P[Publisher] --> D[Driver]
    D --> Q[Queue]
    Q --> C[Consumer]
    C --> W[Worker Pool]
    W --> F[Function]
```

- **Driver** — Backend implementation (memory, AMQP, or SQS)
- **Queue** — Logical queue bound to a driver
- **Consumer** — Connects a queue to a handler with concurrency settings
- **Worker pool** — Concurrent message processors

Multiple queues can share a driver. Multiple consumers can process from the same queue.



### Entry Kinds


| Kind | Description |
|------|-------------|
| `queue.driver.memory` | In-memory queue driver |
| `queue.driver.amqp` | AMQP (RabbitMQ) driver |
| `queue.driver.sqs` | AWS SQS driver (also LocalStack, ElasticMQ) |
| `queue.queue` | Queue declaration with driver reference |
| `queue.consumer` | Consumer that processes messages |



#### Memory Driver


The in-process driver is intended for development and single-node deployments and has no external dependencies.

```yaml
- name: memory_driver
  kind: queue.driver.memory
  lifecycle:
    auto_start: true
```



#### AMQP Driver


For RabbitMQ and AMQP 0-9-1 compatible brokers.

```yaml
- name: amqp_driver
  kind: queue.driver.amqp
  url: "amqp://guest:guest@localhost:5672/"
  vhost: "/"
  connection_name: "wippy-service"
  heartbeat: "10s"
  connection_timeout: "30s"
  reconnect_delay: "1s"
  reconnect_max_delay: "30s"
  default_message_ttl: "1h"
  default_queue_expiry: "24h"
  prefetch_count: 10
  lifecycle:
    auto_start: true
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `url` | string | `amqp://guest:guest@localhost:5672/` | Broker URL |
| `vhost` | string | - | Virtual host override |
| `connection_name` | string | - | Identifier shown in broker UI |
| `auth_mechanism` | string | `PLAIN` | `PLAIN`, `EXTERNAL` (mTLS), or `AMQPLAIN` |
| `heartbeat` | duration | - | Keep-alive interval |
| `connection_timeout` | duration | - | Dial timeout |
| `reconnect_delay` | duration | `1s` | Initial reconnect backoff |
| `reconnect_max_delay` | duration | `30s` | Max reconnect backoff |
| `default_message_ttl` | duration | - | Per-message expiration used when a publisher does not set one |
| `default_queue_ttl` | duration | - | Default queue-level message TTL (`x-message-ttl`) |
| `default_queue_expiry` | duration | - | Default unused-queue expiration (`x-expires`) |
| `prefetch_count` | int | - | Channel-level prefetch ceiling |
| `frame_size` | int | - | AMQP frame size limit |
| `channel_max` | int | - | Max channels per connection |
| `tls` | object | - | TLS settings (see below) |

Configure TLS under `tls`:

```yaml
  tls:
    enabled: true
    server_name: "rabbit.example.com"
    cert: ${env:app.env:amqp_cert}
    key:  ${env:app.env:amqp_key}
    ca:   ${env:app.env:amqp_ca}
    insecure_skip_verify: false
```

`cert`/`key`/`ca` carry PEM content — inline, via `file://`, or via a `${env:NAME}` placeholder resolved through the [env registry](system/env.md). `insecure_skip_verify` disables certificate verification (development only). Legacy `cert_env`/`key_env`/`ca_env` directives also read the environment registry, but preserve an inline or zero value when the lookup is missing or empty; modern placeholders without defaults fail on missing variables. The legacy directives are deprecated.



#### SQS Driver


For AWS SQS and SQS-compatible endpoints (LocalStack, ElasticMQ). Credentials, region, and other AWS SDK settings come from a shared `config.aws` resource.

```yaml
- name: aws_config
  kind: config.aws
  region: us-east-1
  access_key_id: ${env:app:AWS_ACCESS_KEY_ID}
  secret_access_key: ${env:app:AWS_SECRET_ACCESS_KEY}

- name: sqs_driver
  kind: queue.driver.sqs
  config: app:aws_config
  endpoint: "http://localhost:9324"
  message_retention_period: 86400
  default_delay_seconds: 0
  lifecycle:
    auto_start: true
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `config` | Registry ID | required | `config.aws` resource providing region and credentials |
| `endpoint` | string | - | Custom endpoint URL (LocalStack, ElasticMQ); omit for real AWS |
| `message_retention_period` | int | - | Queue-level retention in seconds (60–1209600), set as a queue attribute on create. Omit to leave the AWS default of 345600 (4 days). |
| `default_delay_seconds` | int | `0` | Default delivery delay applied on CreateQueue (0–900) |
| `disable_message_checksum_validation` | bool | `false` | Disable SQS message checksum checks on send/receive |
| `use_fips` | bool | `false` | Use FIPS-compliant endpoints |
| `use_dual_stack` | bool | `false` | Use dual-stack (IPv4 + IPv6) endpoints |

Queues are auto-created by the driver on first use. Use SQS-prefixed headers to address SQS-specific fields on publish: `sqs.delay_seconds`, `sqs.message_group_id`, and `sqs.message_deduplication_id` map to typed SQS message fields. All other headers (neutral keys like `correlation_id` and `content_type`, plus any `sqs.message_attributes.*` keys) are carried verbatim as SQS message attributes.



### Queue Configuration


```yaml
- name: tasks
  kind: queue.queue
  driver: app.queue:memory_driver
  codec: json/plain
  queue_name: "app_tasks"
  driver_options:
    memory:
      max_length: 500
  dead_letter:
    queue: app.queue:tasks_dlq
    max_attempts: 5
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `driver` | Registry ID | Yes | Queue driver |
| `codec` | string | No | Wire encoding for message bodies. Defaults to `json/plain` (see [Codecs](#codecs)) |
| `queue_name` | string | No | External queue name (defaults to entry name) |
| `driver_options` | object | No | Per-driver sub-bag, keyed by driver kind |
| `dead_letter.queue` | Registry ID | No | Queue ID for failed messages (accepted but not yet enforced by any built-in driver) |
| `dead_letter.max_attempts` | int | No | Attempts before routing to DLQ (accepted but not yet enforced by any built-in driver) |



#### Driver Options


Keys under `driver_options` are scoped by driver name. A driver reads only its own sub-bag — other keys are dormant, which lets a single queue entry declare settings for multiple drivers if needed.

**memory:**

| Key | Description |
|-----|-------------|
| `max_length` | Bounded buffer size (0 or unset = default 1000) |

**amqp:**

| Key | Description |
|-----|-------------|
| `durable` | Survive broker restart |
| `auto_delete` | Delete when last consumer detaches |
| `message_ttl` | Per-queue message TTL override |
| `queue_expiry` | Unused-queue expiration |
| `max_length` | Max messages retained |



#### Codecs


The `codec` selects how a message body is serialized before it is handed to the broker. It is a payload format string and defaults to `json/plain`:

| Codec | Format |
|-------|--------|
| `json/plain` | JSON (default) |
| `application/msgpack` | MessagePack |

The AMQP driver sets a matching `content-type` (`application/json` or `application/msgpack`) on published messages. An unknown codec fails when the queue is declared, not at publish time.



### Consumer Configuration


```yaml
- name: task_consumer
  kind: queue.consumer
  queue: app.queue:tasks
  func: app.queue:task_handler
  concurrency: 4
  prefetch: 20
  auto_ack: false
  driver_options:
    amqp:
      consumer_tag: "worker-1"
      exclusive: false
  lifecycle:
    auto_start: true
    requires:
      - app.queue:tasks
```

| Field | Default | Description |
|-------|---------|-------------|
| `queue` | required | Queue registry ID |
| `func` | required | Handler function registry ID |
| `concurrency` | 1 | Parallel worker count |
| `prefetch` | 10 | Shared delivery-buffer size; AMQP also applies it as the channel QoS prefetch count |
| `auto_ack` | false | Backend-specific auto-ack option; for AMQP, `true` asks the broker to acknowledge on delivery |
| `driver_options` | - | Per-driver sub-bag (same structure as queue) |

**amqp consumer options:**

| Key | Description |
|-----|-------------|
| `exclusive` | Single-consumer queue access |
| `no_local` | Reject messages published on the same connection |
| `no_wait` | Don't wait for broker confirmation on subscribe |
| `consumer_tag` | Identifier for this subscription |

<tip>
Consumers respect call context and can be subject to security policies. Configure actor and policies at the lifecycle level. See <a href="./security.md">Security</a>.
</tip>



#### Worker Pool


Workers run concurrently:

```
concurrency: 3, prefetch: 10

1. Driver delivers up to 10 messages to the shared buffer
2. 3 workers pull from the buffer and can each hold an active delivery
3. As workers finish, buffer refills
4. Backpressure when all workers busy and buffer full
```



### Handler Function


Consumer handlers receive the decoded message body as the first argument. Use `queue.message()` to access delivery metadata (id, headers).

```lua
local queue = require("queue")
local logger = require("logger")

local function main(body)
    local msg, msg_err = queue.message()
    if msg_err then return nil, msg_err end
    local message_id, id_err = msg:id()
    if id_err then return nil, id_err end
    local correlation_id, header_err = msg:header("correlation_id")
    if header_err then return nil, header_err end

    logger:info("processing", {
        id = message_id,
        correlation_id = correlation_id
    })

    local ok, err = process_task(body)
    if err then
        return nil, err  -- nack: redelivery per driver
    end
    return true          -- ack: remove from queue
end

return { main = main }
```

```yaml
- name: task_handler
  kind: function.lua
  source: file://task_handler.lua
  method: main
  modules:
    - queue
    - logger
```



#### Acknowledgment


Unless the handler settles explicitly, the consumer settles from the function invocation result:

| Handler Result | Action |
|----------------|--------|
| Any plain return value (including `false`) | Ack |
| `nil, err` return | Nack (redeliver per driver) |
| Raised error | Nack |

Ordinary return values, including `false`, do not select acknowledgment behavior. Call `msg:ack()` or `msg:nack()` to settle explicitly. Settlement is single-shot: whichever call lands first wins.



#### Dead-Letter Routing


Dead-letter routing is not yet implemented. The `dead_letter` block (see [Queue Configuration](#queue-configuration)) is accepted in config, but no built-in driver currently counts attempts, routes nacked messages to the configured DLQ, or sets `x_dead_letter_*` headers. A nacked message is redelivered per the driver's own policy. The `x_*` header namespace is reserved for future DLQ bookkeeping, so publishers should avoid setting `x_*` headers.



### Publishing Messages


From Lua code:

```lua
local queue = require("queue")

local published, publish_err = queue.publish("app.queue:tasks", {
    id = "task-123",
    action = "process",
    data = payload
})
if publish_err then return nil, publish_err end
return published
```

See [Queue Module](lua/storage/queue.md) for the Lua publishing and message API.



### Graceful Shutdown


On consumer stop:

1. Stop accepting new deliveries
2. Cancel worker contexts
3. Wait for in-flight messages (with timeout)
4. Return error if workers don't finish in time



### See Also


- [Queue Module](lua/storage/queue.md) - Lua API reference
- [Queue Consumers Guide](guides/queue-consumers.md) - Consumer patterns and worker pools
- [Supervision](guides/supervision.md) - Consumer lifecycle management



---

# "Network Overlays"

## Network Overlays


Network overlay entries route outbound connections or bind listeners through SOCKS5, Tor, Tailscale, or I2P. A selected overlay propagates across function, process, and HTTP boundaries.

This page is a configuration reference. The YAML fences are entry or application-config fragments and assume the external proxy, tailnet, or I2P SAM service already exists.



### Entry Kinds


| Kind | Description |
|------|-------------|
| `network.socks5` | Generic SOCKS5 proxy (also covers Tor's SOCKS5 listener) |
| `network.tailscale` | Tailscale tsnet overlay node |
| `network.i2p` | I2P SAM v3 bridge |



### SOCKS5


```yaml
- name: proxy
  kind: network.socks5
  host: 127.0.0.1
  port: 1080
  username: "optional"
  password: "optional"
  isolate_streams: false
```

| Field | Type | Description |
|-------|------|-------------|
| `host` | string | Proxy host |
| `port` | int | Proxy port (1-65535) |
| `username` | string | Optional SOCKS5 auth |
| `password` | string | Optional SOCKS5 auth |
| `isolate_streams` | bool | Per-connection random credentials (Tor stream isolation) |

`host` and `port` are required. `isolate_streams` defaults to `false`. When
isolation is enabled, the runtime generates a new username and password for
each dial instead of using the configured credentials.



### Tailscale


```yaml
- name: tailnet
  kind: network.tailscale
  hostname: "wippy-node"
  auth_key: ${env:TS_AUTHKEY}
  ephemeral: false
  control_url: ""
```

| Field | Type | Description |
|-------|------|-------------|
| `hostname` | string | tsnet node name (used in per-node state directory) |
| `auth_key` | string | Tailnet auth key — inline or `${env:NAME}` resolved via the [env registry](system/env.md) |
| `state_dir` | string | Override for tsnet state directory |
| `control_url` | string | Alternate coordination server |
| `ephemeral` | bool | Register as an ephemeral tailnet node |

`auth_key` is required (supply it directly or via `${env:NAME}`). The legacy `auth_key_env` directive resolves the same way but is deprecated; prefer `auth_key: ${env:NAME}`.

The tsnet hostname defaults to `wippy`. When `state_dir` is omitted, the runtime
uses `<network_service.state_dir>/tailscale/<node>`, where `<node>` is the
configured hostname or, if no hostname is configured, the registry entry name.



### I2P


```yaml
- name: i2p_bridge
  kind: network.i2p
  host: 127.0.0.1
  port: 7656
  session_name: "wippy"
```

| Field | Type | Description |
|-------|------|-------------|
| `host` | string | SAM v3 bridge host |
| `port` | int | SAM v3 bridge port |
| `session_name` | string | Optional session identifier |

`host` and `port` are required. `session_name` defaults to `wippy` and is used
as the prefix for per-dial and per-listener SAM session IDs.



#### On `http.service`


Bind the server listener through an overlay (Tailscale, I2P):

```yaml
- name: gateway
  kind: http.service
  addr: ":8080"
  network: app.net:tailnet
```

SOCKS5 does not support inbound listening — use it only for outbound dials.



#### From Lua


Route a called function or spawned process through an overlay using `with_options`:

```lua
local funcs = require("funcs")

local caller, err = funcs.new():with_options({ network = "app.net:proxy" })
if err then return nil, err end
local result, call_err = caller:call("app.api:fetch_data")
if call_err then return nil, call_err end
```

```lua
local process = require("process")

local pid, err = process.with_options({ network = "app.net:tailnet" })
    :spawn_monitored("app.workers:probe", "app:processes")
if err then return nil, err end
```

Constructing the process spawner with custom options also requires `process.context` on `context`. A denial raises a Lua error before the spawner is returned; `network.select` is then checked separately for the selected network ID.

The `http_client` module accepts the same overlay selection on per-call options under the key `overlay_network`.



### Inheritance


Overlay selection propagates through the call stack. A function called through
`funcs.new():with_options({network=...})` uses the overlay for inner dials,
nested calls, and spawned processes unless a new boundary selects another
overlay. An empty `network` option means "no override"; it does not clear an
inherited overlay or the application default.

For a function call, runtime options override the function entry's
`meta.options` before network selection. At a new function or process boundary,
a non-empty `options.network` is selected first. If it is absent,
`network_service.default_network` is selected when configured; if neither is
present, the inherited frame selection remains. A selected ID must already be
registered. An unknown ID fails the call or spawn instead of falling back to
the host network.

Ambient inheritance bypasses the descendant's own `network.select` deny rules. Only explicit selection at a Lua edge is gated.



### App Configuration


Overlay drivers read app-wide settings from a `network_service:` block in `.wippy.yaml`:

```yaml
network_service:
  state_dir: .wippy/net          # base dir for driver state (Tailscale keys, etc.)
  default_network: app.net:tailnet  # overlay applied when no call sets one
```

| Field | Default | Description |
|-------|---------|-------------|
| `state_dir` | `.wippy/net` | Driver state directory. Relative paths resolve against the boot config dir. |
| `default_network` | — | Registry ID of an overlay applied to any task or process that does not pin its own network via options. |



### Raw Dials


Overlay selection is not limited to Lua edges. Dials made through the runtime network service — the WASM [`socket` host](wasm/hosts.md#socket) and the `wasi:sockets` dispatcher — read the overlay off the frame and route through it, whether it was set by `with_options`, by `meta.options.network` on the entry, or by `network_service.default_network`.

The private-IP gate behaves differently on that path. A direct dial resolves the target and checks every resulting address against `socket.private_ip`. With an overlay selected, only a literal IP address in the target is checked; host names are handed to the overlay to resolve, so the local resolver is never consulted and no check is made on what it would have returned.

When an overlay is selected but the context carries no network registry, the dial fails with `network "<id>" selected without a network registry`.



### Updating Overlays


Overlay entries are replaced on registry update. The driver builds the replacement before switching to it; if creation fails, the existing overlay continues running. A successful swap is atomic for new lookups, then the previous service is closed. Work already using the previous service can therefore observe that closure.



### Permissions


| Action | Resource | Description |
|--------|----------|-------------|
| `network.select` | Network registry ID | Explicit overlay selection at `funcs.call`, `process.spawn`, `http_client` |
| `network.bind` | Network registry ID | Binding an `http.service` listener through an overlay (the `network:` field) |
| `socket.connect` | `host:port` | Any outbound dial through the network service |
| `socket.listen` | `host:port` | Binding a TCP listener or a UDP socket through the network service |
| `socket.resolve` | Host name | DNS resolution through the network service |
| `socket.private_ip` | IP address | Reaching a loopback, private, link-local or unspecified address |

Deny `network.select` on a scope to stop code inside it from choosing an overlay explicitly. Inherited overlays are unaffected — they were authorized at the caller. `network.bind` is checked when a server with a `network:` overlay starts its listener.

The `socket.*` permissions are checked by the network service itself. `socket.connect`, `socket.listen` and `socket.resolve` are checked before any overlay routing, so they apply equally to clearnet and overlay traffic; `socket.private_ip` narrows to literal addresses once an overlay is selected, as described under [Raw Dials](system/network.md#raw-dials).



### See Also


- [Security](system/security.md) - Policies and actors
- [HTTP Service](http/server.md) - Server binding
- [HTTP Client](lua/http/client.md) - Per-call overlay selection
- [Host Functions](wasm/hosts.md) - WASM socket imports



---

# "Filesystem"

## Filesystem


Filesystem entries expose directory-backed or read-only embedded storage to runtime modules. This page is a configuration reference; its YAML blocks are individual entry fragments rather than complete projects.



### Entry Kinds


| Kind | Description |
|------|-------------|
| `fs.directory` | Directory-based filesystem |
| `fs.embed` | Read-only embedded filesystem |



### Directory Filesystem


```yaml
- name: uploads
  kind: fs.directory
  directory: "/var/data/uploads"
  auto_init: true
  mode: "0755"
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `directory` | string | required | Root path |
| `auto_init` | bool | false | Create directory if missing |
| `mode` | string | 0755 | Unix permission mode (octal) |
| `base` | string | - | Relative-path base: `project` (process working directory) or `module` (owning module load root) |

Absolute paths are used as given, whatever `base` says.

For a relative path, `base: project` keeps it relative to the process working directory. Both `base: module` and an unset `base` resolve it against the load root of the module that owns the entry, looked up through the entry's registry owner. When the entry has no owning module, or that module has no resolvable resource root, the path stays relative to the process working directory.

Any other value is rejected with `invalid directory base`.

The mode restricts all file operations. Execute bits are added automatically when all read bits are set and no execute bit is.

<note>
Paths are normalized and validated. It is not possible to access files outside the configured root directory.
</note>



### Embedded Filesystem


```yaml
- name: static
  kind: fs.embed
```

Embedded filesystems load from pack resources using the entry ID. They are read-only.

<warning>
Embedded filesystems are used internally and normally do not require manual configuration.
</warning>



### Operations


Both filesystem types implement:

| Operation | Directory | Embed |
|-----------|-----------|-------|
| Open/Read | Yes | Yes |
| Stat | Yes | Yes |
| Lstat | Yes | Yes |
| ReadDir | Yes | Yes |
| OpenFile (write) | Yes | No |
| Remove | Yes | No |
| Mkdir | Yes | No |
| Rename | Yes | No |

Write operations on embedded filesystems return an error.



### Lua API


See [Filesystem Module](lua/storage/filesystem.md) for file operations.



### See Also


- [Filesystem Module](lua/storage/filesystem.md) - Lua API reference
- [Cloud Storage](system/cloudstorage.md) - S3-compatible object storage
- [Template](system/template.md) - Templates loaded from filesystems



---

# "Cloud Storage"

## Cloud Storage

<secondary-label ref="external"/>

S3-compatible object storage with presigned URLs, multipart uploads and ranged reads.



### Entry Kinds


| Kind | Description |
|------|-------------|
| `config.aws` | AWS credentials and region configuration |
| `cloudstorage.s3` | S3 bucket connection |



### AWS Configuration


```yaml
- name: aws_config
  kind: config.aws
  region: ${env:AWS_REGION}
  access_key_id: ${env:AWS_ACCESS_KEY_ID}
  secret_access_key: ${env:AWS_SECRET_ACCESS_KEY}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `region` | string | Yes | AWS region. Supply via `${env:NAME}` when it differs per deployment |
| `access_key_id` | string | No | AWS access key ID (inline or `${env:NAME}`) |
| `secret_access_key` | string | No | AWS secret access key (inline or `${env:NAME}`) |

Credentials resolve from the [environment registry](system/env.md) at decode time. Both `access_key_id` and `secret_access_key` must resolve to non-empty values for static credentials to apply; otherwise the AWS SDK default credential chain is used (IAM roles, instance profiles, etc.).

Requests are signed with AWS Signature Version 4 by the AWS SDK using the resolved credentials. No signing configuration is required.

<note>
Older configurations use a sibling <code>&lt;field&gt;_env</code> directive (<code>region_env</code>, <code>access_key_id_env</code>, <code>secret_access_key_env</code>) that resolves the same way. This form is <b>deprecated</b> — migrate it to the <code>${env:NAME}</code> placeholder shown above.
</note>

<note>
A single <code>config.aws</code> entry can be reused across AWS-backed services. <code>queue.driver.sqs</code> references the same entry via its <code>config:</code> field.
</note>



### S3 Storage


```yaml
- name: files
  kind: cloudstorage.s3
  bucket: "my-bucket"
  config: app.infra:aws_config
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `bucket` | string | Conditional | S3 bucket name. Supply via `${env:NAME}` when it differs per deployment |
| `config` | reference | Yes | AWS config entry reference |
| `endpoint` | string | No | Custom endpoint for S3-compatible services (inline or `${env:NAME}`) |



#### S3-Compatible Services


For MinIO or other S3-compatible services, set a custom endpoint:

```yaml
- name: local_storage
  kind: cloudstorage.s3
  bucket: "local-bucket"
  config: app.infra:aws_config
  endpoint: "http://localhost:9000"
```

When an endpoint is provided, path-style access is enabled automatically.



### Multipart Uploads


Presigned multipart uploads are a provider capability, not a runtime feature. The `cloudstorage.s3` kind implements them; a provider that does not support the multipart protocol fails `create_multipart_upload`, `presigned_part_urls`, `complete_multipart_upload` and `abort_multipart_upload` with `errors.UNAVAILABLE`.

Parts of an upload that is never completed or aborted stay stored and billed. Applications abort on every failure path, but a crashed client leaves nothing to run that abort. Configure an `AbortIncompleteMultipartUpload` lifecycle rule on the bucket as the backstop:

```json
{
  "Rules": [
    {
      "ID": "abort-incomplete-multipart",
      "Status": "Enabled",
      "Filter": { "Prefix": "" },
      "AbortIncompleteMultipartUpload": { "DaysAfterInitiation": 7 }
    }
  ]
}
```



### Ranged Reads


`open_reader` reads an object through ranged GETs and pins the object's ETag with `If-Match` on every read. A provider that does not return an ETag on the initial stat fails the call with `errors.UNAVAILABLE`, and a provider that ignores `If-Match` loses the overwrite protection - the read then cannot detect that it mixed two object generations.



### Lua API


See [Cloud Storage Module](lua/storage/cloud.md) for operations (list, upload, download, delete, presigned URLs, multipart uploads, ranged readers).



### See Also


- [Cloud Storage Module](lua/storage/cloud.md) - Lua API reference
- [Filesystem](system/filesystem.md) - Local filesystem entries
- [Queue](system/queue.md) - SQS handler shares the same `config.aws` entries



---

# "Environment System"

## Environment System


Environment entries let runtime code reference configuration by public variable name or registry entry ID.

This page is a configuration reference. Its YAML fences are entry fragments unless they show an enclosing document.



### Storage and Access


The model separates storage from access:

- **Storages** - Where values are stored (OS, files, memory)
- **Variables** - Named references to values in storages

Variables can be referenced by:
- **Public name** - The `variable` field value
- **Entry ID** - Full `namespace:name` reference

Omit the `variable` field when a variable should be accessible only by entry ID.
The first variable to claim a public name keeps that shortcut. A later variable
with the same public name is still registered and remains accessible by entry ID,
but does not replace the existing shortcut.



### Entry Kinds


| Kind | Description |
|------|-------------|
| `env.storage.memory` | In-memory key-value storage |
| `env.storage.file` | File-based storage (.env format) |
| `env.storage.os` | Read-only OS environment access |
| `env.storage.static` | Read-only static key-value storage |
| `env.storage.router` | Chains multiple storages |
| `env.variable` | Named variable referencing a storage |



#### Memory Storage


Volatile in-memory storage.

```yaml
- name: runtime_env
  kind: env.storage.memory
```



#### File Storage


Persistent storage using a simple `KEY=VALUE` format. Blank lines and lines that
start with `#` are ignored; text after `#` on a value line is treated as a comment.
Quoted values and escape sequences are not parsed specially.

```yaml
- name: app_config
  kind: env.storage.file
  file_path: /etc/app/config.env
  auto_create: true
  file_mode: 0600
  dir_mode: 0700
```

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `file_path` | string | required | Path to .env file |
| `auto_create` | boolean | false | Create file if missing |
| `file_mode` | integer | 0644 | File permissions |
| `dir_mode` | integer | 0755 | Directory permissions |



#### OS Storage


Read-only access to operating system environment variables.

```yaml
- name: os_env
  kind: env.storage.os
```

Always read-only. Set operations return `PERMISSION_DENIED`.



#### Static Storage


Static storage defines values directly in configuration. The values are part of the entry, are read-only at runtime, and can hold public constants shipped with a module or pack.

```yaml
- name: defaults
  kind: env.storage.static
  values:
    PUBLIC_API_HOST: "https://api.example.com"
    PUBLIC_WS_HOST: "wss://api.example.com/ws"
    APP_ENV: "production"
```

| Property | Type | Description |
|----------|------|-------------|
| `values` | map | Key-value pairs (string to string) |

Always read-only. Set operations return `PERMISSION_DENIED`.



#### Router Storage


A router chains several storages. On a cache miss, reads search them in order until a value is found; a successful value is cached by the router, so direct changes in a backing storage are not visible through that router afterward. An error other than `NOT_FOUND` stops the fallback search. Writes target only the first storage.

```yaml
- name: config
  kind: env.storage.router
  storages:
    - app.config:memory    # Primary (writes here)
    - app.config:file      # Fallback
    - app.config:os        # Fallback
```

| Property | Type | Description |
|----------|------|-------------|
| `storages` | array | Required, non-empty ordered list of storage references |



### Variables


Variables map public names or entry IDs to values in a storage backend.

```yaml
- name: DATABASE_URL
  kind: env.variable
  variable: DATABASE_URL
  storage: app.config:file
  default: postgres://localhost/app
  readonly: false
```

| Property | Type | Description |
|----------|------|-------------|
| `variable` | string | Optional public variable name |
| `storage` | string | Required storage reference (`namespace:name`) |
| `default` | string | Default value if not found |
| `readonly` | boolean | Prevent modifications |



#### Variable Naming


Variable names must contain only: `a-z`, `A-Z`, `0-9`, `_`



#### Access Patterns


```yaml


## Public variable - accessible by name "PORT"

- name: port_var
  kind: env.variable
  variable: PORT
  storage: app.config:os
  default: "8080"



## Private variable - accessible only by ID "app.config:internal_key"

- name: internal_key
  kind: env.variable
  storage: app.config:secrets
```



### Placeholder Interpolation


Registered variables are pulled into entry configuration with `${env:NAME}` placeholders, resolved centrally at decode time against this registry. Entry configuration strings are resolved unless their entry kind marks a field as opaque. Source fields such as `template.jet.source` are opaque so template or program text is not rewritten.

| Syntax | Meaning |
|--------|---------|
| `${env:NAME}` | Resolve `NAME` through the env registry; error if unset and no default |
| `${env:NAME\|default}` | Resolve `NAME`, falling back to `default` when unset |
| `${NAME\|default}` | Shorthand; `NAME` must be upper-snake (`A-Z0-9_`) and the `\|default` is required — bare `${VAR}` is left untouched so embedded shell/template spans are not mistaken for references |
| `$${` | Literal `${` (escape) |

`NAME` is a registered variable's public name or its entry ID (registry-id form with dots/colons, e.g. `app.env:tls_cert`). It is **not** a raw OS environment variable: an OS value is reachable only when an `env.storage.os`-backed variable is registered under that name.

```yaml
- name: api
  kind: http.service
  addr: ":443"
  tls:
    mode: manual
    cert: ${env:app.env:tls_cert}
    key:  ${env:app.env:tls_key}
```

A field whose entire value is a single placeholder takes the type of its inline default. For example, `${env:PORT|8080}` produces an integer and coerces a stored value to an integer, while `${env:PORT|"8080"}` remains a string. A placeholder mixed with surrounding text always produces a string. A variable's own `default` is honored before the placeholder's inline `|default`. A reference that resolves to nothing and has no default fails decoding.

Resolution happens at decode time only: the stored registry entry keeps the raw placeholders, so resolved secrets never appear in `registry.get` results or persisted state. Entries referencing a variable by entry ID (`${env:ns:name}`) automatically order after that variable at boot; a reference by public name creates no dependency edge.

<note>
Older configurations use a sibling <code>&lt;field&gt;_env</code> directive (for example <code>cert_env: app.env:tls_cert</code>) that resolves the same way. This form is <b>deprecated</b> — migrate it to the <code>${env:NAME}</code> placeholder. A <code>&lt;field&gt;_env</code> key naming an unregistered variable is not treated as a directive and is left as-is; one naming a registered but empty variable keeps the inline <code>&lt;field&gt;</code> value. Only an explicit <code>${env:NAME}</code> without a default hard-fails on a missing variable.
</note>



### Errors


| Condition | Kind | Retryable |
|-----------|------|-----------|
| Variable not found | `errors.NOT_FOUND` | no |
| Storage not found | `errors.NOT_FOUND` | no |
| Variable is read-only | `errors.PERMISSION_DENIED` | no |
| Storage is read-only | `errors.PERMISSION_DENIED` | no |
| Invalid variable name | `errors.INVALID` | no |



### Runtime Access


- [env module](lua/system/env.md) - Lua runtime access



### See Also


- [Security Model](system/security.md) - Access control for environment variables
- [Configuration Guide](guides/configuration.md) - Application configuration patterns



---

# "Template Engine"

## Template Engine

<secondary-label ref="external"/>

Template entries configure [CloudyKit Jet](https://github.com/CloudyKit/jet) sets and template sources.

This page is a configuration reference. Its YAML fences are fragments for an existing entry list; combine each template with the referenced `template.set` in the same project or installed module graph.



### Entry Kinds


| Kind | Description |
|------|-------------|
| `template.set` | Template set with shared configuration |
| `template.jet` | Individual template |



### Template Sets


A set is a namespace containing related templates. Templates within a set share configuration and can reference each other by name.

```yaml
- name: views
  kind: template.set
```

All template-set configuration is optional:

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `engine.development_mode` | bool | false | Disable template caching |
| `engine.delimiters.left` | string | `{{` | Variable opening delimiter |
| `engine.delimiters.right` | string | `}}` | Variable closing delimiter |
| `engine.delimiters.comment_left` | string | `{*` | Validated only; comments always use Jet's `{*` |
| `engine.delimiters.comment_right` | string | `*}` | Validated only; comments always use Jet's `*}` |
| `engine.extensions` | string[] | `[.jet, .html.jet, .jet.html]` | Validated only; name lookup always tries Jet's built-in `.jet`, `.html.jet`, `.jet.html` |
| `engine.globals` | map | - | Variables available to all templates |

At runtime `development_mode`, the left and right expression delimiters, and
`globals` configure the Jet set. The comment-delimiter and extension fields are
accepted and validated in this release, but are not applied by the in-memory
Jet loader. Changing them does not alter parsing or discover templates.



### Templates


Templates belong to a set and are identified by name for internal resolution.

```yaml
- name: layout
  kind: template.jet
  set: app.views:views
  source: |
    <html>
    <body>{{ yield content() }}</body>
    </html>

- name: home
  kind: template.jet
  set: app.views:views
  source: |
    {{ extends "layout" }}
    {{ block content() }}
      <h1>Welcome, {{ name }}</h1>
    {{ end }}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `set` | reference | Yes | Parent template set |
| `source` | string | Yes | Inline template content or a manifest-relative `file://` reference |

A relative `file://` reference is loaded relative to the manifest containing
the entry and cannot escape that manifest filesystem. Environment placeholders
inside the resulting template source are preserved as template text rather than
resolved by the environment system.



### Template Resolution


Templates reference one another by name rather than registry ID. Names are resolved within the set:

1. By default, the registry entry name (`entry.ID.Name`) becomes the template name
2. Override with `meta.name` for custom naming:

```yaml
- name: email-welcome-v2
  kind: template.jet
  set: app.emails:templates
  meta:
    name: welcome
  source: |
    {{ include "header" }}
    Hello {{ user }}!
```

This template is registered as `welcome` in the set, so other templates use `{{ include "welcome" }}` or `{{ extends "welcome" }}`.



### Inheritance


Templates can extend parent templates and override blocks:

```yaml


## Parent defines yield points

- name: base
  kind: template.jet
  set: app.views:views
  source: |
    <html>
    <head><title>{{ yield title() }}</title></head>
    <body>{{ yield body() }}</body>
    </html>



## Child extends and fills blocks

- name: page
  kind: template.jet
  set: app.views:views
  source: |
    {{ extends "base" }}
    {{ block title() }}My Page{{ end }}
    {{ block body() }}<p>Content here</p>{{ end }}
```



### Lua API


See [Template Module](lua/text/template.md) for rendering operations.



### See Also


- [Template Module](lua/text/template.md) - Lua API reference
- [Filesystem](system/filesystem.md) - Loading templates from disk
- [HTTP Endpoint](http/endpoint.md) - Rendering templates from request handlers



---

# "Security Model"

## Security Model


Wippy implements attribute-based access control with actors and policy scopes. Policies evaluate actions and resources using actor and resource metadata.

This page is a configuration and API reference. Complete examples name their required registry entries; shorter Lua and YAML fences illustrate one operation or configuration fragment in an existing security context.

```mermaid
flowchart LR
    A[Actor + Scope] --> PE[Policy Evaluation] --> AD[Allow/Deny]
    A -.->|Identity<br/>Metadata| PE
    PE -.->|Conditions<br/>actor, resource, action| AD
```



### Entry Kinds


| Kind | Description |
|------|-------------|
| `security.policy` | Declarative policy with conditions |
| `security.policy.expr` | Expression-based policy |
| `security.token_store` | Token storage and validation |



### Actors


An actor identifies the principal performing an action.

```lua
local security = require("security")

-- Create actor with metadata
local actor = security.new_actor("user:123", {
    role = "admin",
    team = "backend",
    department = "engineering",
    clearance = 3
})

-- Access actor properties
local id = actor:id()        -- "user:123"
local meta = actor:meta()    -- {role="admin", ...}
```



#### Actor in Context


```lua
-- Get current actor from context
local errors = require("errors")

local actor = security.actor()
if not actor then
    return nil, errors.new({ kind = errors.PERMISSION_DENIED, message = "No actor in context" })
end
```



### Policies


Policies define access rules with actions, resources, conditions, and effects.



#### Declarative Policy


```yaml


## src/security/_index.yaml

version: "1.0"
namespace: app.security

entries:
  # Admin full access
  - name: admin_policy
    kind: security.policy
    policy:
      actions: "*"
      resources: "*"
      effect: allow
      conditions:
        - field: actor.meta.role
          operator: eq
          value: admin
    groups:
      - admin

  # Read-only access
  - name: readonly_policy
    kind: security.policy
    policy:
      actions:
        - "*.read"
        - "*.get"
        - "*.list"
      resources: "*"
      effect: allow
    groups:
      - default

  # Resource owner access
  - name: owner_policy
    kind: security.policy
    policy:
      actions:
        - read
        - write
        - delete
      resources: "document:*"
      effect: allow
      conditions:
        - field: meta.owner
          operator: eq
          value_from: actor.id
    groups:
      - default

  # Deny confidential without clearance
  - name: deny_confidential
    kind: security.policy
    policy:
      actions: "*"
      resources: "document:*"
      effect: deny
      conditions:
        - field: meta.classification
          operator: eq
          value: confidential
        - field: actor.meta.clearance
          operator: lt
          value: 3
    groups:
      - security
```



#### Policy Structure


```text
policy:
  actions: "*" | "action" | ["action1", "action2"]
  resources: "*" | "resource" | ["res1", "res2"]
  effect: allow | deny
  conditions:  # Optional
    - field: "field.path"
      operator: "eq"
      value: "static_value"
      # OR
      value_from: "other.field.path"
```



#### Expression-Based Policy


For complex logic, use expression policies:

```yaml
- name: flexible_access
  kind: security.policy.expr
  policy:
    actions:
      - read
      - write
    resources: "file:*"
    effect: allow
    expression: |
      (actor.meta.role == "editor" && action == "write") ||
      (action == "read" && meta.public == true) ||
      actor.id == meta.owner
  groups:
    - editors
```



### Conditions


Conditions evaluate actor, action, resource, and metadata fields at runtime.



#### Field Paths


| Path | Description |
|------|-------------|
| `actor.id` | Actor's unique identifier |
| `actor.meta.*` | Actor metadata (supports nesting) |
| `action` | The action being performed |
| `resource` | The resource identifier |
| `meta.*` | Resource metadata |



#### Operators


| Operator | Description | Example |
|----------|-------------|---------|
| `eq` | Equals | `actor.meta.role eq "admin"` |
| `ne` | Not equals | `meta.status ne "deleted"` |
| `lt` | Less than | `meta.priority lt 5` |
| `gt` | Greater than | `actor.meta.clearance gt 2` |
| `lte` | Less than or equal | `meta.size lte 1000` |
| `gte` | Greater than or equal | `actor.meta.level gte 3` |
| `in` | Value in array | `action in ["read", "write"]` |
| `nin` | Value not in array | `meta.status nin ["deleted", "archived"]` |
| `exists` | Field exists | `meta.owner exists true` |
| `nexists` | Field not exists | `meta.deleted nexists true` |
| `contains` | String contains | `resource contains "sensitive"` |
| `ncontains` | String not contains | `resource ncontains "public"` |
| `matches` | Regex match | `resource matches "^doc:.*"` |
| `nmatches` | Regex not match | `actor.id nmatches "^system:.*"` |



#### Condition Examples


```yaml


## Match actor role

conditions:
  - field: actor.meta.role
    operator: eq
    value: admin



## Compare fields

conditions:
  - field: meta.owner
    operator: eq
    value_from: actor.id



## Numeric comparison

conditions:
  - field: actor.meta.clearance
    operator: gte
    value: 3



## Array membership

conditions:
  - field: actor.meta.role
    operator: in
    value:
      - admin
      - moderator



## Pattern matching

conditions:
  - field: resource
    operator: matches
    value: "^api:/v[0-9]+/admin/.*"



## Multiple conditions (AND)

conditions:
  - field: actor.meta.department
    operator: eq
    value: engineering
  - field: meta.environment
    operator: eq
    value: production
```



### Scopes


A scope combines policies into a security context.

```lua
local security = require("security")

-- Get policies
local admin_policy, admin_err = security.policy("app.security:admin_policy")
if admin_err then return nil, admin_err end
local readonly_policy, readonly_err = security.policy("app.security:readonly_policy")
if readonly_err then return nil, readonly_err end

-- Create scope with policies
local scope = security.new_scope()
scope = scope:with(admin_policy)
scope = scope:with(readonly_policy)

-- Scopes are immutable - :with() returns new scope
```



#### Named Scopes (Policy Groups)


Load the policies assigned to a group:

```lua
-- Load scope with all policies in group
local scope, err = security.named_scope("app.security:admin")
if err then return nil, err end
```

Policies are assigned to groups via the `groups` field:

```yaml
- name: admin_policy
  kind: security.policy
  policy:
    # ...
  groups:
    - admin      # This policy is in "admin" group
    - default    # Can be in multiple groups
```



#### Scope Operations


```lua
-- Add policy
local new_scope = scope:with(policy)

-- Remove policy
local new_scope = scope:without("app.security:temp_policy")

-- Check if policy is in scope
local has = scope:contains("app.security:admin_policy")

-- Get all policies
local policies = scope:policies()
```



#### Module Permissions


Strict mode applies permission checks to actor, policy, and scope construction as well as token operations:

| Action | Resource | Used by | Denial behavior |
|--------|----------|---------|-----------------|
| `security.actor.create` | Actor ID | `security.new_actor` | Raises a Lua error |
| `security.policy.get` | Policy registry ID | `security.policy` | Returns `nil, error` |
| `security.policy_group.get` | Policy-group ID | `security.named_scope` | Returns `nil, error` |
| `security.scope.create` | `custom`, `with`, or `without` | `security.new_scope`, `scope:with`, `scope:without` respectively | Raises a Lua error |

Grant only the operations and IDs a caller needs. The actor, scope, and token examples on this page assume these permissions are present in addition to their operation-specific token permissions.



#### Evaluation Flow


```
1. No actor or no scope in context → strict mode decides (deny by default)
2. Check each policy in scope
3. If ANY policy returns Deny → Result is Deny
4. If at least one Allow and no Deny → Result is Allow
5. No applicable policies → Result is Undefined
```

An access check passes only on `Allow`. `Undefined` denies access, exactly like `Deny` — strict mode plays no part once an actor and a scope are both present.



#### Evaluation Results


| Result | Meaning |
|--------|---------|
| `allow` | Access granted |
| `deny` | Access explicitly denied |
| `undefined` | No policy matched |

```lua
local errors = require("errors")

-- Evaluate directly
local result = scope:evaluate(actor, "read", "document:123", {
    owner = "user:456",
    classification = "internal"
})

if result == "deny" then
    return nil, errors.new({ kind = errors.PERMISSION_DENIED, message = "Access denied" })
elseif result == "undefined" then
    -- No policy matched - access checks treat this as denied
end
```



#### Quick Permission Check


```lua
local errors = require("errors")

-- Check against current context's actor and scope
local allowed = security.can("read", "document:123", {
    owner = "user:456"
})

if not allowed then
    return nil, errors.new({ kind = errors.PERMISSION_DENIED, message = "Access denied" })
end
```



### Token Stores


Token stores create, validate, and revoke authentication tokens.

The Lua operations are permission-gated. The active scope must allow
`security.token_store.get` for acquisition and `security.token.create`,
`security.token.validate`, or `security.token.revoke` for the corresponding
operation. This applies in the default strict mode as well as in explicitly
configured security contexts. Examples that create an actor or load a named
scope also require `security.actor.create` and `security.policy_group.get`.



#### Configuration


```yaml


## src/auth/_index.yaml

version: "1.0"
namespace: app.auth

entries:
  # Register environment variable
  - name: os_env
    kind: env.storage.os

  - name: AUTH_SECRET_KEY
    kind: env.variable
    variable: AUTH_SECRET_KEY
    storage: app.auth:os_env

  # Backing store for tokens
  - name: token_data
    kind: store.memory
    lifecycle:
      auto_start: true

  # Token store
  - name: tokens
    kind: security.token_store
    store: app.auth:token_data
    token_length: 32
    default_expiration: "24h"
    token_key: ${env:AUTH_SECRET_KEY}
```



#### Token Store Options


| Option | Default | Description |
|--------|---------|-------------|
| `store` | required | Backing key-value store reference |
| `token_length` | 32 | Token size in bytes (256 bits) |
| `default_expiration` | 24h | Default token TTL |
| `token_key` | none | HMAC-SHA256 signing key (direct value, or `${env:NAME}` to pull from the [env registry](system/env.md)) |

Use `token_key: ${env:NAME}` in production to avoid embedding secrets in entries. The legacy `token_key_env` directive also reads the environment registry but preserves the inline or zero value for a missing or empty lookup; a modern placeholder without a default fails when its variable is missing. The legacy directive is deprecated.



#### Creating Tokens


```lua
local security = require("security")

-- Get token store
local store, err = security.token_store("app.auth:tokens")
if err then
    return nil, err
end

-- Create actor and scope
local actor = security.new_actor("user:123", {
    role = "user",
    email = "user@example.com"
})

local scope, scope_err = security.named_scope("app.security:default")
if scope_err then
    store:close()
    return nil, scope_err
end

-- Create token
local token, create_err = store:create(actor, scope, {
    expiration = "7d",  -- Override default expiration
    meta = {
        device = "mobile",
        ip = "192.168.1.1"
    }
})
store:close()
if create_err then return nil, create_err end
return token

-- Token format: base64_token.hmac_signature (if token_key set)
-- Example: "dGVzdHRva2VuMTIz.a1b2c3d4e5f6"
```



#### Validating Tokens


```lua
local errors = require("errors")

-- Validate token
local actor, scope, err = store:validate(token)
store:close()
if err then
    return nil, errors.new({ kind = errors.PERMISSION_DENIED, message = "Invalid token" })
end

-- Actor and scope are reconstructed from stored data
print(actor:id())  -- "user:123"
```



#### Revoking Tokens


```lua
-- Revoke single token
local ok, err = store:revoke(token)
if err then
    store:close()
    return nil, err
end

-- Close store when done
store:close()
return ok
```



### Context Flow


Actor and scope are inheritable frame context. Function calls and spawned
processes inherit both unless the caller supplies a replacement context.
Explicitly changing a spawned process's actor or scope requires the
`process.security` permission. Changing the security context of a function call
through `funcs.new():with_actor(...)` or `:with_scope(...)` instead requires
`funcs.security` on `security`.



#### Setting Context


```lua
local funcs = require("funcs")

-- Call function with security context
local caller, err = funcs.new():with_actor(actor)
if err then return nil, err end
caller, err = caller:with_scope(scope)
if err then return nil, err end
local result, call_err = caller:call("app.api:protected_endpoint", data)
if call_err then return nil, call_err end
```



#### Context Inheritance


| Component | Inherits |
|-----------|----------|
| Actor | Yes - passes to child calls and spawned processes |
| Scope | Yes - passes to child calls and spawned processes |
| Strict mode | No - application-wide |

Functions and spawned processes both inherit the caller's security context. A spawned process starts on a frame forked from the spawner's, which carries the spawner's actor and scope, and the `security:` block on its own entry modifies that inherited context. When the entry declares no block, the process keeps the spawner's actor and scope unchanged; a spawner that has neither produces a child with neither, which strict mode denies. A declared block that names an `actor` replaces the inherited actor, and its `policies` and `groups` are merged into the inherited scope; a block that omits `actor` keeps the spawner's actor, and one that omits both `policies` and `groups` keeps the spawner's scope.



### Declaring Security on Entries


A security block is the same shape everywhere it appears:

| Field | Type | Description |
|-------|------|-------------|
| `actor.id` | string | Actor identity; replaces the inherited actor |
| `actor.meta` | map | Actor attributes policies evaluate |
| `policies` | list | Policy registry IDs, merged into the scope |
| `groups` | list | Policy group registry IDs, whose policies are merged into the scope |

`policies` and `groups` are **registry IDs in `namespace:name` form**. A bare name does not resolve — unlike the `groups:` field on a policy entry, which defaults to the policy's own namespace, these references carry no default namespace.

Resolution is atomic and fail-closed. Every listed policy and group is resolved before anything is installed; if any one of them is missing, empty, or contains no policies, the whole configuration fails and no actor and no partial scope is applied. A caller therefore never crosses a boundary holding half a context.



#### Process Entries


`process.lua`, `process.lua.bc`, `function.lua`, and `function.lua.bc` entries take a top-level `security:` block that applies to every execution of that entry:

```yaml
- name: worker_process
  kind: process.lua
  source: file://worker.lua
  method: main
  security:
    actor:
      id: "service:worker"
      meta:
        role: worker
        service: true
    policies:
      - app.security:worker_policy
    groups:
      - app.security:workers
```

The block is applied when the process starts, on both `process.host` and `terminal.host`. A resolution failure aborts the spawn rather than starting the process with a weaker context.



#### Service Lifecycle


Supervised services take the same block under `lifecycle`, resolved once when the service controller is created and sealed for the life of the service:

```yaml
- name: worker
  kind: process.service
  process: app:worker_process
  host: app:processes
  lifecycle:
    auto_start: true
    security:
      actor:
        id: "service:worker"
      groups:
        - app.security:workers
```



#### CLI Commands


A command entry declares `meta.command.security`, applied only when the entry is launched as a CLI command — the operator running `wippy run <name>` is the trust anchor for that context. It never affects an ordinary spawn of the same entry. The block is validated strictly: unknown fields are rejected, an empty block is rejected, and `security` without a command `name` is rejected. See [Command security](guides/cli.md#command-security).



### Strict Mode


Strict mode decides what happens when a request carries no actor and no scope. It is **on by default**, so an incomplete context is denied. Turning it off is an explicit choice, made in the runtime config file (`.wippy.yaml`), not in the module manifest `wippy.yaml`:

```yaml


## .wippy.yaml

security:
  strict_mode: false
```

| `strict_mode` | Missing Context | Behavior |
|------|-----------------|----------|
| Strict (default) | No actor/scope | Deny |
| Permissive (`strict_mode: false`) | No actor/scope | Allow |

Strict mode changes nothing once an actor and a scope are present: evaluation is deny-by-default either way. It only governs the incomplete case, which is why a process that runs without a declared security context fails every check under the default. Give such a process a `security:` block, or start it through a path that supplies one.



### Authentication Flow


Token validation in an HTTP handler:

```lua
local http = require("http")
local security = require("security")

local function protected_handler()
    local req, req_err = http.request()
    if req_err then return nil, req_err end
    local res, res_err = http.response()
    if res_err then return nil, res_err end

    local function respond(status, body)
        local content_type_err = res:set_header("Content-Type", "application/json")
        if content_type_err then return nil, content_type_err end
        local status_err = res:set_status(status)
        if status_err then return nil, status_err end
        local write_err = res:write_json(body)
        if write_err then return nil, write_err end
        return true
    end

    -- Extract and validate token
    local auth, header_err = req:header("Authorization")
    if header_err then return nil, header_err end
    if not auth then
        return respond(http.STATUS.UNAUTHORIZED, {error = "Missing authorization"})
    end

    local token = auth:match("^Bearer%s+(.+)$")
    if not token then
        return respond(http.STATUS.UNAUTHORIZED, {error = "Expected a bearer token"})
    end
    local store, store_err = security.token_store("app.auth:tokens")
    if store_err then
        return respond(http.STATUS.INTERNAL_ERROR, {error = "Token store unavailable"})
    end

    local actor, scope, validate_err = store:validate(token)
    store:close()
    if validate_err then
        return respond(http.STATUS.UNAUTHORIZED, {error = "Invalid token"})
    end

    -- Evaluate the actor and scope reconstructed from this token.
    if scope:evaluate(actor, "api.users.read", "users") ~= "allow" then
        return respond(http.STATUS.FORBIDDEN, {error = "Forbidden"})
    end

    return respond(http.STATUS.OK, {user = actor:id()})
end

return { handler = protected_handler }
```

Token creation during login:

```lua
local actor = security.new_actor("user:" .. user.id, {role = user.role})
local scope, scope_err = security.named_scope("app.security:" .. user.role)
if scope_err then return nil, scope_err end

local store, store_err = security.token_store("app.auth:tokens")
if store_err then return nil, store_err end
local token, token_err = store:create(actor, scope, {expiration = "24h"})
store:close()
if token_err then return nil, token_err end
return token
```



### Runtime Trust Boundaries


Policy evaluation governs what code may do. Three separate mechanisms govern what code is admitted and where a context may travel.



#### Module Integrity


Every module in `wippy.lock` carries an artifact digest. At boot, a download is verified against both the digest pinned in the lock and the digest the hub served, and already-vendored packs are re-verified against the lock before they are loaded; a mismatch is a non-retryable integrity failure that is not worked around — the module is not loaded. `wippy install` verifies a fresh download only against the digest and size the hub served, deletes the file and fails on mismatch, and then writes the served digest back into the lock, so a pinned digest is re-established by install rather than enforced by it; only packs already in the vendor directory are checked against the lock's digest. Extracted module directories carry their own recorded digest and tree digest and are checked the same way, so a modified vendored tree is detected rather than trusted. See [Dependency Management](guides/dependency-management.md#integrity-verification).



#### Cluster Internode Identity


Nodes in a cluster authenticate each other. Each node holds an ed25519 identity key and the map of peer public keys it trusts; the mesh handshake is mutual, binding an HMAC over the shared gossip secret to an ed25519 signature over a transcript covering both node IDs and both nonces. A peer that is not in the trusted map, or whose gossip-advertised key disagrees with the trusted entry, is rejected. There is no unauthenticated mode: a node without an identity cannot join the mesh. See [Internode identity](guides/cluster.md#internode-identity).



#### Temporal Propagation


A security context that crosses into Temporal is carried as a signed header rather than as plain workflow input. The actor, its metadata, and the policy IDs are serialized into a `wippy-security` envelope and signed with the client's HMAC key, audienced to the specific workflow or activity ID. The receiving worker verifies the signature and the audience and resolves every named policy locally before the workflow or activity runs; any failure fails the execution. A workflow running under a security context also refuses unsigned signals, so an external Temporal client cannot drive it. See [Workflows](temporal/workflows.md#security-context) and [Temporal overview](temporal/overview.md#security-context-propagation).



### Best Practices


1. **Least privilege** - Grant minimum required permissions
2. **Deny by default** - Use explicit allow policies, enable strict mode
3. **Use policy groups** - Organize policies by role/function
4. **Sign tokens** - Always set `token_key` from an `${env:NAME}` reference in production
5. **Short expiration** - Use shorter token lifetimes for sensitive operations
6. **Condition on context** - Use dynamic conditions over static policies
7. **Audit sensitive actions** - Log security-relevant operations



### Security Module Reference


| Function | Description |
|----------|-------------|
| `security.actor()` | Get current actor from context |
| `security.scope()` | Get current scope from context |
| `security.can(action, resource, meta?)` | Check permission |
| `security.new_actor(id, meta?)` | Create new actor |
| `security.new_scope(policies?)` | Create empty or seeded scope |
| `security.policy(id)` | Get policy by ID |
| `security.named_scope(group_id)` | Get scope with all group policies |
| `security.token_store(id)` | Get token store |



---

# "Executor"

## Executor


Executor entries run external commands as native operating-system processes or in Docker containers.

This page is a configuration and API reference. Entry fences are fragments for an existing entry list; the Lua example assumes an executor named `app:shell` and an allowed `git status` command.



### Entry Kinds


| Kind | Description |
|------|-------------|
| `exec.native` | Execute commands directly on the host OS |
| `exec.docker` | Execute commands inside Docker containers |



### Native Executor


The native executor runs commands directly on the host operating system.

```yaml
- name: shell
  kind: exec.native
  default_work_dir: /app
  default_env:
    PATH: /usr/local/bin:/usr/bin:/bin
    LANG: en_US.UTF-8
  command_whitelist:
    - git status
    - git diff
    - npm run build
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `default_work_dir` | string | - | Working directory for all commands |
| `default_env` | map | - | Environment variables (merged with per-command env) |
| `command_whitelist` | string[] | - | If set, only these exact commands are allowed |

<note>
Native executors use a clean environment by default. Only explicitly configured environment variables are passed to child processes.
</note>

Commands are parsed into an executable and argument list; they are not run
through a shell. Pipes, redirects, variable expansion, and other shell syntax
have no special meaning. To run a shell expression, allow and invoke the shell
explicitly, including its command flag and the expression as arguments.



### Docker Executor


The Docker executor runs commands inside Docker containers.

Docker commands are also parsed directly into an executable and arguments and
assigned as the container command. They do not receive shell expansion unless
the command explicitly invokes a shell.

```yaml
- name: sandbox
  kind: exec.docker
  image: python:3.11-slim
  default_work_dir: /workspace
  network_mode: none
  memory_limit: 536870912
  cpu_quota: 50000
  auto_remove: true
  read_only_rootfs: true
  no_new_privileges: true
  cap_drop:
    - ALL
  tmpfs:
    /tmp: rw,noexec,nosuid,size=64m
  volumes:
    - /app/data:/workspace/data:ro
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `image` | string | **required** | Docker image to use |
| `host` | string | Docker client default | Docker daemon URL; when omitted, the client uses its environment and platform default |
| `default_work_dir` | string | - | Working directory inside container |
| `default_env` | map | - | Environment variables |
| `command_whitelist` | string[] | - | Allowed commands (exact match) |
| `network_mode` | string | Docker default | Docker network mode, such as `host`, `bridge`, or `none` |
| `volumes` | string[] | - | Volume mounts: `host:container[:ro]` |
| `user` | string | - | User to run as inside container |
| `memory_limit` | int | 0 | Memory limit in bytes (0 = unlimited) |
| `cpu_quota` | int | 0 | CPU quota (100000 = 1 CPU, 0 = unlimited) |
| `auto_remove` | bool | false | Remove container after exit |
| `read_only_rootfs` | bool | false | Make root filesystem read-only |
| `no_new_privileges` | bool | false | Prevent privilege escalation |
| `cap_drop` | string[] | - | Linux capabilities to drop |
| `cap_add` | string[] | - | Linux capabilities to add |
| `pids_limit` | int | 0 | Max processes (0 = unlimited) |
| `tmpfs` | map | - | Tmpfs mounts for writable paths |



### Command Whitelist


Both executor types support command allowlists. When the list is non-empty,
only exact matches of the original command string are allowed:

```yaml
command_whitelist:
  - ls -la
  - cat /etc/passwd
```

Commands absent from the allowlist are rejected with an error.

An omitted or empty allowlist permits any command that passes security policy.
The Lua API separately checks `exec.get` for the executor ID and `exec.run` for
the exact command string.



### Lua API


The [Exec Module](lua/dynamic/exec.md) provides command execution:

```lua
local exec = require("exec")

local executor, err = exec.get("app:shell")
if err then return nil, err end

local proc, proc_err = executor:exec("git status", {
    work_dir = "/app/repo"
})
if proc_err then
    executor:release()
    return nil, proc_err
end

local stdout, stream_err = proc:stdout_stream()
if stream_err then
    proc:close()
    executor:release()
    return nil, stream_err
end

local ok, start_err = proc:start()
if start_err then
    stdout:close()
    proc:close()
    executor:release()
    return nil, start_err
end

local chunks = {}
while true do
    local chunk, read_err = stdout:read(4096)
    if read_err then
        stdout:close()
        proc:close(true)
        executor:release()
        return nil, read_err
    end
    if chunk == nil then break end
    chunks[#chunks + 1] = chunk
end

local exit_code, wait_err = proc:wait()
local _, stream_close_err = stdout:close()
local _, release_err = executor:release()

if wait_err then return nil, wait_err end
if stream_close_err then return nil, stream_close_err end
if release_err then return nil, release_err end
return table.concat(chunks), exit_code
```



### See Also


- [Exec Module](lua/dynamic/exec.md) - Lua API reference
- [Process Host](system/process-host.md) - Host that runs Wippy processes
- [Filesystem](system/filesystem.md) - Filesystem entries used as work directories



---

# "HTTP Server"

## HTTP Server


An `http.service` owns a listener and hosts routers, endpoints, and static file handlers.

**Classification: server configuration reference.** Blocks are partial registry
fragments unless they define every referenced network, environment, filesystem,
router, certificate, actor, and policy entry.



### Configuration


```yaml
- name: gateway
  kind: http.service
  addr: ":8080"
  timeouts:
    read: "5s"
    write: "30s"
    idle: "60s"
  host:
    buffer_size: 1024
    worker_count: 4
  lifecycle:
    auto_start: true
    security:
      actor:
        id: "http-gateway"
      policies:
        - app:http_policy
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `addr` | string | required | Listen address (`:8080`, `0.0.0.0:443`) |
| `timeouts.read` | duration | - | Request read timeout |
| `timeouts.write` | duration | - | Response write timeout |
| `timeouts.idle` | duration | - | Keep-alive connection timeout |
| `host.buffer_size` | int | 1024 | Message relay buffer size |
| `host.worker_count` | int | NumCPU | Message relay workers |
| `network` | Registry ID | - | Bind listener through a [network overlay](system/network.md) (e.g. Tailscale, I2P) |
| `tls` | object | - | TLS termination (see [TLS](#tls)) |



### Timeouts


Configure timeouts to prevent resource exhaustion:

```yaml
timeouts:
  read: "10s"    # Max time to read the entire request (headers + body)
  write: "60s"   # Max time to write response
  idle: "120s"   # Keep-alive timeout
```

- `read` — Short (5–10 seconds) for APIs, longer for uploads
- `write` — Match the expected response generation time
- `idle` — Balance connection reuse against resource usage

<note>
Duration format: <code>30s</code>, <code>1m</code>, <code>2h15m</code>. Use <code>0</code> to disable.
</note>



### Host Configuration


The `host` section configures the server's internal message relay used by components like WebSocket relay:

```yaml
host:
  buffer_size: 2048
  worker_count: 8
```

| Field | Default | Description |
|-------|---------|-------------|
| `buffer_size` | 1024 | Message queue capacity per worker |
| `worker_count` | NumCPU | Parallel message processing goroutines |

<tip>
Increase these values for high-throughput WebSocket applications. The message relay handles async delivery between HTTP components and processes.
</tip>



### Security


HTTP servers can have a default security context applied through the lifecycle configuration:

```yaml
lifecycle:
  auto_start: true
  security:
    actor:
      id: "gateway-service"
    policies:
      - app:http_access_policy
```

This sets a baseline actor and policies for all requests. For authenticated requests, the [token_auth middleware](http/middleware.md) overrides the actor based on the validated token, allowing per-user security policies.



### Lifecycle


Servers are managed by the supervisor:

```yaml
lifecycle:
  auto_start: true
  start_timeout: 30s
  stop_timeout: 60s
  requires:
    - app:database
```

| Field | Description |
|-------|-------------|
| `auto_start` | Start when application starts |
| `start_timeout` | Max time to wait for server to start |
| `stop_timeout` | Max time for graceful shutdown |
| `requires` | Start after these entries are ready (`depends_on` is the legacy spelling) |



### Connecting Components


Routers and static handlers reference the server via metadata:

```yaml
entries:
  - name: gateway
    kind: http.service
    addr: ":8080"

  - name: api
    kind: http.router
    meta:
      server: gateway
    prefix: /api

  - name: static
    kind: http.static
    meta:
      server: gateway
    path: /
    fs: app:public
```



### Multiple Servers


Run separate servers for different purposes:

```yaml
entries:
  # Public API
  - name: public
    kind: http.service
    addr: ":8080"
    lifecycle:
      auto_start: true

  # Admin (localhost only)
  - name: admin
    kind: http.service
    addr: "127.0.0.1:9090"
    lifecycle:
      auto_start: true
```



### TLS


The server can terminate TLS directly. Set `tls.mode` to `manual` (supply your own certificate) or `auto` (certificate provided by an overlay network driver, e.g. `network.tailscale`). Plain clearnet listeners do not support `auto`. Omit `tls` or leave the mode empty to run plain HTTP.

In `auto` mode the server must not specify `cert`/`key` — the network driver provides them.



#### Manual certificate


Under `mode: manual`, `cert` and `key` carry PEM content. Supply that content in one of three ways (pick one per field, never mix):

1. **Inline PEM** — the literal PEM string.
2. **`file://` reference** — manifest-relative path, resolved and inlined at load time (traversal-safe).
3. **Environment registry reference** — pull the PEM from a registered [env variable](system/env.md) at decode time, using a `${env:NAME}` placeholder.

```yaml
- name: api
  kind: http.service
  addr: ":443"
  tls:
    mode: manual
    cert: file://./certs/server.pem
    key:  file://./certs/server.key
```

```yaml
- name: api
  kind: http.service
  addr: ":443"
  tls:
    mode: manual
    cert: ${env:app.env:tls_cert}
    key:  ${env:app.env:tls_key}
```

The `${env:NAME}` placeholder resolves `NAME` through the [environment registry](system/env.md) — a registered variable's public name or its entry ID (e.g. `app.env:tls_cert`). It is not a raw OS environment variable; an OS value is only reachable when an `env.storage.os`-backed variable is registered under that name. A default can be supplied with `${env:NAME|default}`.

<note>
The legacy <code>cert_env</code> / <code>key_env</code> companion fields still resolve through the environment registry the same way, but are <b>deprecated</b> — prefer the <code>${env:NAME}</code> placeholder shown above.
</note>

| Field | Description |
|-------|-------------|
| `mode` | `""` (off), `auto`, or `manual` |
| `cert` / `key` | PEM content — inline, `file://` reference, or `${env:NAME}` placeholder |



#### Mutual TLS (mTLS)


Under `mode: manual` the server can additionally verify client certificates:

```yaml
tls:
  mode: manual
  cert: ${env:app.env:tls_cert}
  key:  ${env:app.env:tls_key}
  client_ca: file://./certs/clients-ca.pem
  client_auth: require_and_verify
```

`client_ca` accepts the same three forms as `cert`/`key` (inline PEM, `file://`, or `${env:NAME}`). The legacy `client_ca_env` companion field is likewise deprecated in favor of `client_ca: ${env:NAME}`.

| Field | Description |
|-------|-------------|
| `client_auth` | `request`, `require_any`, `verify_if_given`, `require_and_verify` |
| `client_ca` | PEM bundle of trusted client CAs (inline, `file://`, or `${env:NAME}`) |

`verify_if_given` and `require_and_verify` require a CA. `request` and `require_any` accept any client cert without CA verification.



### See Also


- [Routing](http/router.md) - Routers and endpoints
- [Static Files](http/static.md) - Static file serving
- [Middleware](http/middleware.md) - Available middleware
- [Security](system/security.md) - Security policies
- [WebSocket Relay](http/websocket-relay.md) - WebSocket messaging



---

# "Routing"

## Routing


An `http.router` groups endpoints under a URL prefix and applies shared middleware. Each `http.endpoint` defines an HTTP handler.

**Classification: routing reference.** Configuration blocks are partial registry
fragments unless they include a namespace and every referenced entry. Handler
blocks use application-owned function IDs rather than defining a data layer.



### Architecture


```mermaid
flowchart TB
    S[http.service<br/>:8080] --> R1[http.router<br/>/api]
    S --> R2[http.router<br/>/admin]
    S --> ST[http.static<br/>/]

    R1 --> E1[GET /users]
    R1 --> E2[POST /users]
    R1 --> E3["GET /users/{id}"]

    R2 --> E4[GET /stats]
    R2 --> E5[POST /config]
```

Entries reference parents via metadata:

- Routers: `meta.server: app:gateway`
- Endpoints: `meta.router: app:api`



### Router Configuration


```yaml
- name: api
  kind: http.router
  meta:
    server: gateway
  prefix: /api/v1
  middleware:
    - cors
    - compress
  options:
    cors.allow.origins: "*"
  post_middleware:
    - endpoint_firewall
```

| Field | Type | Description |
|-------|------|-------------|
| `meta.server` | Registry ID | Parent HTTP server |
| `prefix` | string | URL prefix for all routes |
| `middleware` | []string | Pre-match middleware |
| `options` | map | Middleware options |
| `post_middleware` | []string | Post-match middleware |
| `post_options` | map | Post-match middleware options |



### Endpoint Configuration


```yaml
- name: get_user
  kind: http.endpoint
  meta:
    router: api
  method: GET
  path: /users/{id}
  func: app.users:get_user
```

| Field | Type | Description |
|-------|------|-------------|
| `meta.router` | Registry ID | Parent router |
| `method` | string | HTTP method: `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`, `OPTIONS`, `TRACE`, or `*` for any method |
| `path` | string | URL path pattern (starts with `/`) |
| `func` | Registry ID | Handler function |



### Path Parameters


Use `{param}` syntax for URL parameters:

```yaml
- name: get_post
  kind: http.endpoint
  meta:
    router: api
  method: GET
  path: /users/{user_id}/posts/{post_id}
  func: get_user_post
```

Access in handler:

```lua
local http = require("http")

local function handler()
    local req, req_err = http.request()
    if req_err then return nil, req_err end
    local user_id, user_err = req:param("user_id")
    if user_err then return nil, user_err end
    local post_id, post_err = req:param("post_id")
    if post_err then return nil, post_err end

    return {user_id = user_id, post_id = post_id}
end
```



#### Wildcard Paths


Capture remaining path segments with `{param...}`:

```yaml
- name: serve_files
  kind: http.endpoint
  meta:
    router: api
  method: GET
  path: /files/{filepath...}
  func: serve_file
```

The wildcard matches the remaining segments, so a request like `GET /api/v1/files/docs/guides/readme.md` is dispatched to the handler. The captured tail is read with `req:param` under the name without the trailing dots:

```lua
local filepath = req:param("filepath")  -- "docs/guides/readme.md"
```

The wildcard must be the last segment in the path.



### Route Precedence


All routers register their endpoints into a single pattern set, prefixed by the router's `prefix`, and Go's `ServeMux` decides which pattern serves a request. Its rules apply unchanged:

- The most specific pattern wins. A pattern is more specific than another when it matches a strict subset of that pattern's requests, so `/users/admin` beats `/users/{id}`, and `/files/{name}` beats `/files/{path...}`.
- A pattern with a method is more specific than the same path without one, so a `GET` endpoint takes precedence over a `*` endpoint on the same path for `GET` requests.
- A trailing `{path...}` or `/` matches an entire subtree and loses to any pattern that matches a subset of it.
- Matching is on the cleaned, decoded path; specificity never depends on registration order.

Two patterns can also conflict outright: neither is more specific than the other, yet they overlap, as with `/users/{id}/settings` and `/users/admin/{section}`. This is a configuration error. The router surfaces it when it rebuilds, the rebuild fails, and the previous route set stays in service.



### Handler Functions


Endpoint handlers use the `http` module to access request and response objects. See [HTTP Module](lua/http/http.md) for the request and response API reference.

```lua
local http = require("http")
local funcs = require("funcs")

local function handler()
    local req, req_err = http.request()
    if req_err then return nil, req_err end
    local res, res_err = http.response()
    if res_err then return nil, res_err end

    local user_id, param_err = req:param("id")
    if param_err then return nil, param_err end
    local user, call_err = funcs.call("app.users:get_user", user_id)
    if call_err then return nil, call_err end

    local status_err = res:set_status(http.STATUS.OK)
    if status_err then return nil, status_err end
    local write_err = res:write_json(user)
    if write_err then return nil, write_err end
    return true
end

return { handler = handler }
```



### Middleware Options


Middleware options use dot notation with the middleware name as prefix:

```yaml
middleware:
  - cors
  - ratelimit
  - token_auth
options:
  cors.allow.origins: "https://app.example.com"
  cors.allow.methods: "GET,POST,PUT,DELETE"
  ratelimit.requests: "100"
  ratelimit.window: "1m"
  token_auth.store: "app:tokens"
  token_auth.header.name: "Authorization"
```

Post-match middleware uses `post_options`:

```yaml
post_middleware:
  - endpoint_firewall
post_options:
  endpoint_firewall.action: "access"
```



### Pre-Handler and Post-Match Middleware


**Pre-handler** (`middleware`) runs after the server selects a route but before route parameters and endpoint metadata are attached to the request context:
- CORS (handles OPTIONS preflight)
- Compression
- Rate limiting
- Real IP detection
- Token authentication (context enrichment)

**Post-match** (`post_middleware`) runs after route parameters and endpoint metadata are attached:
- Endpoint firewall (needs route info for authorization)
- Resource firewall
- WebSocket relay

```yaml
middleware:        # Before endpoint metadata: matched routes only
  - cors
  - compress
  - token_auth     # Enriches context with actor/scope

post_middleware:   # Post-match: matched routes only
  - endpoint_firewall  # Uses actor from token_auth
```

<tip>
Token authentication belongs in the pre-handler chain because it enriches the request context before authorization. Authorization middleware such as <code>endpoint_firewall</code> belongs in the post-match chain because it needs the matched endpoint ID. Unmatched requests do not run either router chain.
</tip>



### Router and Endpoint Wiring


This example defines the list handler entry. The `app:get_user_by_id` and `app:create_user` function IDs refer to handlers defined elsewhere in the same namespace.

```yaml
version: "1.0"
namespace: app

entries:
  # Server
  - name: gateway
    kind: http.service
    addr: ":8080"
    lifecycle:
      auto_start: true

  # API Router
  - name: api
    kind: http.router
    meta:
      server: gateway
    prefix: /api/v1
    middleware:
      - cors
      - compress
      - ratelimit
    options:
      cors.allow.origins: "https://app.example.com"
      ratelimit.requests: "100"
      ratelimit.window: "1m"

  # Handler function
  - name: get_users
    kind: function.lua
    source: file://handlers/users.lua
    method: list
    modules:
      - http
      - json
      - sql

  # Endpoints
  - name: list_users
    kind: http.endpoint
    meta:
      router: api
    method: GET
    path: /users
    func: get_users

  - name: get_user
    kind: http.endpoint
    meta:
      router: api
    method: GET
    path: /users/{id}
    func: app:get_user_by_id

  - name: create_user
    kind: http.endpoint
    meta:
      router: api
    method: POST
    path: /users
    func: app:create_user
```



### Protected Routes


The following configuration separates public routes from routes that require authentication and authorization:

```yaml
entries:
  # Public routes (no auth)
  - name: public
    kind: http.router
    meta:
      server: gateway
    prefix: /api/public
    middleware:
      - cors

  # Protected routes
  - name: protected
    kind: http.router
    meta:
      server: gateway
    prefix: /api
    middleware:
      - cors
      - token_auth
    options:
      token_auth.store: app:tokens
    post_middleware:
      - endpoint_firewall
```



### See Also


- [Server](http/server.md) - HTTP server configuration
- [Static Files](http/static.md) - Static file serving
- [Middleware](http/middleware.md) - Available middleware
- [HTTP Module](lua/http/http.md) - Lua HTTP API



---

# "HTTP Endpoints"

## HTTP Endpoints


An `http.endpoint` maps an HTTP method and path to a Lua handler function.

**Classification: configuration and API reference.** YAML blocks are registry
fragments that assume the referenced server, router, middleware, function
entries, and security policies already exist. Lua blocks focus on handler
contracts and identify application calls explicitly.



### Definition


```yaml
- name: get_user
  kind: http.endpoint
  meta:
    router: app:api_router
  method: GET
  path: /users/{id}
  func: app.users:get_user
```



### Configuration


| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `meta.router` | registry.ID | Yes | Parent router (referenced by registry ID). |
| `method` | string | Yes | HTTP method, or `"*"` for any method |
| `path` | string | Yes | URL path pattern |
| `func` | registry.ID | Yes | Function to execute |



### HTTP Methods


Supported methods:

| Method | Use Case |
|--------|----------|
| `GET` | Retrieve resources |
| `POST` | Create resources |
| `PUT` | Replace resources |
| `PATCH` | Partial update |
| `DELETE` | Remove resources |
| `HEAD` | Headers only |
| `OPTIONS` | CORS preflight (auto-handled) |
| `TRACE` | Diagnostic loopback |
| `*` | Any method |

Method names are uppercase; `method` is required, and any value outside this set is rejected as a configuration error.



#### Method-agnostic Endpoints


`method: "*"` registers the path for every HTTP method, and the handler reads the actual method with `req:method()`:

```yaml
- name: proxy
  kind: http.endpoint
  method: "*"
  path: /proxy/{path...}
  func: proxy_handler
```

For a normal endpoint the router also registers an `OPTIONS` handler on the same path, so CORS middleware can answer a preflight without the endpoint running. A `*` endpoint gets no such handler: it already matches `OPTIONS`. Router middleware still wraps it, so configured CORS middleware answers an allowed preflight with `204` before the endpoint runs; any other `OPTIONS` request reaches the endpoint function itself, which must answer it.



### Path Parameters


Use `{param}` syntax for URL parameters:

```yaml
- name: get_user
  kind: http.endpoint
  meta:
    router: api
  method: GET
  path: /users/{id}
  func: get_user

- name: get_user_post
  kind: http.endpoint
  meta:
    router: api
  method: GET
  path: /users/{user_id}/posts/{post_id}
  func: get_user_post
```

Access in handler:

```lua
local http = require("http")

local function handler()
    local req, req_err = http.request()
    if req_err then return nil, req_err end
    local user_id, user_err = req:param("user_id")
    if user_err then return nil, user_err end
    local post_id, post_err = req:param("post_id")
    if post_err then return nil, post_err end
    return {user_id = user_id, post_id = post_id}
end
```



### Wildcard Paths


Use `{path...}` to match any remaining path segments:

```yaml
- name: file_handler
  kind: http.endpoint
  method: GET
  path: /files/{path...}
  func: serve_file
```

This catch-all segment makes the route match requests like `/files/docs/readme.md`. The captured tail is read like any other parameter, under the name without the trailing dots:

```lua
local req = http.request()
local tail = req:param("path")  -- "docs/readme.md"
```



### Handler Function


Endpoint functions obtain request and response objects from the `http` module:

```lua
local http = require("http")
local funcs = require("funcs")

local function handler()
    local req, req_err = http.request()
    if req_err then return nil, req_err end
    local res, res_err = http.response()
    if res_err then return nil, res_err end

    local user_id, param_err = req:param("id")
    if param_err then return nil, param_err end

    local user, call_err = funcs.call("app.users:get_user", user_id)
    if call_err then return nil, call_err end

    local type_err = res:set_content_type(http.CONTENT.JSON)
    if type_err then return nil, type_err end
    local status_err = res:set_status(http.STATUS.OK)
    if status_err then return nil, status_err end
    local write_err = res:write_json(user)
    if write_err then return nil, write_err end
    return true
end

return { handler = handler }
```



#### Request Object


| Method | Returns | Description |
|--------|---------|-------------|
| `req:method()` | string | HTTP method |
| `req:path()` | string | Request path |
| `req:param(name)` | string | URL parameter |
| `req:params()` | table | All path parameters |
| `req:query(name)` | string | Query parameter |
| `req:query_params()` | table | All query parameters |
| `req:header(name)` | string | Request header |
| `req:headers()` | table | All request headers |
| `req:body()` | string | Request body |
| `req:body_json()` | table, error | Parse JSON body |
| `req:has_body()` | boolean | Check if body exists |
| `req:content_type()` | string | Content type |
| `req:content_length()` | number | Body size in bytes |
| `req:host()` | string | Hostname |
| `req:remote_addr()` | string | Client IP address |
| `req:accepts(type)` | boolean | Content negotiation |
| `req:is_content_type(type)` | boolean | Check content type |
| `req:stream()` | Stream | Body as stream for large files |
| `req:parse_multipart(max?)` | table, error | Parse multipart form |



#### Response Object


| Method | Description |
|--------|-------------|
| `res:set_status(code)` | Set HTTP status code; returns an error if headers were sent |
| `res:set_header(name, value)` | Set response header; returns an error if headers were sent |
| `res:set_content_type(type)` | Set content type; returns an error if headers were sent |
| `res:write(data)` | Write raw body; returns an error on failure |
| `res:write_json(data)` | Write a JSON response; returns an error on failure |
| `res:write_event(data)` | Send and flush an SSE event; returns an error on failure |
| `res:set_transfer(encoding)` | Set `chunked` or `sse` transfer mode; returns an error if headers were sent |
| `res:flush()` | Flush the response; returns an error value |



### JSON API Pattern


A JSON API handler can parse the request body, reject invalid input, and write a JSON result:

```lua
local http = require("http")
local funcs = require("funcs")

local function handler()
    local req, req_err = http.request()
    if req_err then return nil, req_err end
    local res, res_err = http.response()
    if res_err then return nil, res_err end

    local data, err = req:body_json()
    if err then
        local status_err = res:set_status(http.STATUS.BAD_REQUEST)
        if status_err then return nil, status_err end
        local write_err = res:write_json({error = "Invalid JSON"})
        if write_err then return nil, write_err end
        return true
    end

    local result, process_err = funcs.call("app.api:process_request", data)
    if process_err then return nil, process_err end

    local status_err = res:set_status(http.STATUS.OK)
    if status_err then return nil, status_err end
    local write_err = res:write_json(result)
    if write_err then return nil, write_err end
    return true
end

return { handler = handler }
```



### Error Responses


```lua
local http = require("http")
local funcs = require("funcs")

local function api_error(res, status, code, message)
    local status_err = res:set_status(status)
    if status_err then return nil, status_err end
    local write_err = res:write_json({
        error = {
            code = code,
            message = message
        }
    })
    if write_err then return nil, write_err end
    return true
end

local function handler()
    local req, req_err = http.request()
    if req_err then return nil, req_err end
    local res, res_err = http.response()
    if res_err then return nil, res_err end

    local user_id, param_err = req:param("id")
    if param_err then return nil, param_err end
    local user, err = funcs.call("app.users:get_user", user_id)

    if err then
        if errors.is(err, errors.NOT_FOUND) then
            return api_error(res, http.STATUS.NOT_FOUND, "USER_NOT_FOUND", "User not found")
        end
        return api_error(res, http.STATUS.INTERNAL_ERROR, "INTERNAL_ERROR", "Server error")
    end

    local status_err = res:set_status(http.STATUS.OK)
    if status_err then return nil, status_err end
    local write_err = res:write_json(user)
    if write_err then return nil, write_err end
    return true
end

return { handler = handler }
```



#### CRUD Endpoints


```yaml
entries:
  - name: users_router
    kind: http.router
    meta:
      server: gateway
    prefix: /api/users
    middleware:
      - cors
      - compress

  - name: list_users
    kind: http.endpoint
    meta:
      router: users_router
    method: GET
    path: /
    func: app.users:list

  - name: get_user
    kind: http.endpoint
    meta:
      router: users_router
    method: GET
    path: /{id}
    func: app.users:get

  - name: create_user
    kind: http.endpoint
    meta:
      router: users_router
    method: POST
    path: /
    func: app.users:create

  - name: update_user
    kind: http.endpoint
    meta:
      router: users_router
    method: PUT
    path: /{id}
    func: app.users:update

  - name: delete_user
    kind: http.endpoint
    meta:
      router: users_router
    method: DELETE
    path: /{id}
    func: app.users:delete
```



#### Protected Endpoint


Authorization middleware is configured on the parent router, not on the endpoint. Post-match middleware (such as `endpoint_firewall`) runs after route matching and applies to every endpoint under the router:

```yaml
- name: admin_router
  kind: http.router
  meta:
    server: gateway
  prefix: /admin
  middleware:
    - cors
    - token_auth
  post_middleware:
    - endpoint_firewall
  post_options:
    endpoint_firewall.action: "admin"

- name: admin_endpoint
  kind: http.endpoint
  meta:
    router: admin_router
  method: POST
  path: /settings
  func: app.admin:update_settings
```



### See Also


- [Router](http/router.md) - Route grouping
- [HTTP Module](lua/http/http.md) - Request/response API
- [Middleware](http/middleware.md) - Request processing



---

# "HTTP Middleware"

## HTTP Middleware


HTTP middleware runs in one of two router chains: before endpoint metadata is attached, or after the route has supplied its parameters and endpoint ID.

**Classification: middleware reference.** Each YAML block is a router fragment;
it assumes the named middleware is registered and any referenced token store,
filesystem, endpoint, actor, and policy entries exist.



### How Middleware Works


Each middleware receives an options map and returns a handler wrapper:

```yaml
middleware:
  - cors
  - ratelimit
options:
  cors.allow.origins: "https://example.com"
  ratelimit.requests: "100"
```

Options use dot notation: `middleware_name.option.name`. Legacy underscore format is supported for backward compatibility.



### Pre-Handler and Post-Match


<tip>
<b>Pre-handler</b> middleware runs after the server selects a route but before route metadata is attached—for concerns such as CORS and compression.
<b>Post-match</b> middleware runs after route metadata is attached—for authorization that needs the endpoint ID.
Neither chain runs for an unmatched request.
</tip>

```yaml
middleware:        # Before endpoint metadata
  - cors
  - compress
options:
  cors.allow.origins: "*"

post_middleware:   # Post-match
  - endpoint_firewall
post_options:
  endpoint_firewall.action: "access"
```

---



#### CORS {#cors}


<note>Pre-handler</note>

Cross-Origin Resource Sharing for browser requests.

```yaml
middleware:
  - cors
options:
  cors.allow.origins: "https://app.example.com"
  cors.allow.credentials: "true"
```

| Option | Default | Description |
|--------|---------|-------------|
| `cors.allow.origins` | `*` | Allowed origins (comma-separated, supports `*.example.com`) |
| `cors.allow.methods` | `GET,POST,PUT,DELETE,OPTIONS,PATCH` | Allowed methods |
| `cors.allow.headers` | `Origin,Content-Type,Accept,Authorization,X-Requested-With` | Allowed request headers |
| `cors.expose.headers` | - | Headers exposed to client |
| `cors.allow.credentials` | `false` | Allow cookies/auth |
| `cors.max.age` | `86400` | Preflight cache (seconds) |
| `cors.allow.private.network` | `false` | Private network access |

OPTIONS preflight requests are handled automatically.

---



#### Rate Limiting {#ratelimit}


<note>Pre-handler</note>

Token bucket rate limiting with per-key tracking.

```yaml
middleware:
  - ratelimit
options:
  ratelimit.requests: "100"
  ratelimit.window: "1m"
  ratelimit.key: "ip"
```

| Option | Default | Description |
|--------|---------|-------------|
| `ratelimit.requests` | `100` | Requests per window |
| `ratelimit.window` | `1m` | Time window |
| `ratelimit.burst` | `20` | Burst capacity |
| `ratelimit.key` | `ip` | Key strategy |
| `ratelimit.cleanup_interval` | `5m` | Cleanup frequency |
| `ratelimit.entry_ttl` | `10m` | Entry expiration |
| `ratelimit.max_entries` | `100000` | Max tracked keys |

**Key strategies:** `ip`, `header:X-API-Key`, `query:api_key`

Returns `429 Too Many Requests` with headers: `X-RateLimit-Limit`, `X-RateLimit-Window`.

---



#### Compression {#compress}


<note>Pre-handler</note>

Gzip compression for responses.

```yaml
middleware:
  - compress
options:
  compress.level: "default"
  compress.min.length: "1024"
```

| Option | Default | Description |
|--------|---------|-------------|
| `compress.level` | `default` | `fastest`, `default`, or `best` |
| `compress.min.length` | `1024` | Minimum response size (bytes) |

Only compresses when client sends `Accept-Encoding: gzip`.

---



#### Real IP {#real_ip}


<note>Pre-handler</note>

Extract client IP from proxy headers.

```yaml
middleware:
  - real_ip
options:
  real_ip.trusted.subnets: "10.0.0.0/8,172.16.0.0/12"
```

| Option | Default | Description |
|--------|---------|-------------|
| `real_ip.trusted.subnets` | Loopback, RFC 1918, link-local, CGNAT and IPv6 local ranges | Trusted proxy CIDRs |
| `real_ip.trust_all` | `false` | Trust all sources (insecure) |

**Header priority:** `True-Client-IP` > `X-Real-IP` > `X-Forwarded-For`

---



#### Token Auth {#token_auth}


<note>Pre-handler</note>

Token-based authentication. See [Security](system/security.md) for token store configuration.

```yaml
middleware:
  - token_auth
options:
  token_auth.store: "app:tokens"
```

| Option | Default | Description |
|--------|---------|-------------|
| `token_auth.store` | required | Token store registry ID |
| `token_auth.header.name` | `Authorization` | Header name |
| `token_auth.header.prefix` | `Bearer ` | Header prefix |
| `token_auth.query.param` | `x-auth-token` | Query parameter fallback |
| `token_auth.cookie.name` | `x-auth-token` | Cookie fallback |

Sets actor and security scope in context for downstream middleware. Does not block requests—authorization happens in firewall middleware.

---



#### Metrics {#metrics}


<note>Pre-handler</note>

Prometheus-style HTTP metrics. This middleware is registered only when a metrics collector is available, and it has no configuration options.

```yaml
middleware:
  - metrics
```

| Metric | Type | Description |
|--------|------|-------------|
| `wippy_http_requests_total` | Counter | Total requests |
| `wippy_http_request_duration_seconds` | Histogram | Request latency |
| `wippy_http_requests_in_flight` | Gauge | Concurrent requests |

---



#### Endpoint Firewall {#endpoint_firewall}


<warning>Post-match</warning>

Authorization based on the matched endpoint. It requires an actor and security scope in the request context; `token_auth` is one way to supply them.

```yaml
post_middleware:
  - endpoint_firewall
post_options:
  endpoint_firewall.action: "access"
```

| Option | Default | Description |
|--------|---------|-------------|
| `endpoint_firewall.action` | `access` | Permission action to check |

Returns `401 Unauthorized` (no actor) or `403 Forbidden` (permission denied).

---



#### Resource Firewall {#resource_firewall}


<warning>Post-match</warning>

Protect specific resources by ID. Useful at router level.

```yaml
post_middleware:
  - resource_firewall
post_options:
  resource_firewall.action: "admin"
  resource_firewall.target: "app:admin-panel"
```

| Option | Default | Description |
|--------|---------|-------------|
| `resource_firewall.action` | `access` | Permission action |
| `resource_firewall.target` | required | Resource registry ID |

---



#### Sendfile {#sendfile}


<note>Pre-handler</note>

Serve files via `X-Sendfile` header from handlers.

```yaml
middleware:
  - sendfile
options:
  sendfile.fs: "app:downloads"
```

Handler sets headers to trigger file serving:

| Header | Description |
|--------|-------------|
| `X-Sendfile` | File path within filesystem |
| `X-File-Name` | Download filename |

Supports range requests for resumable downloads.

---



#### WebSocket Relay {#websocket_relay}


<warning>Post-match</warning>

Relay WebSocket connections to processes. See [WebSocket Relay](http/websocket-relay.md).

```yaml
post_middleware:
  - websocket_relay
post_options:
  wsrelay.allowed.origins: "https://app.example.com"
```

---



#### SSE Relay {#sse_relay}


<warning>Post-match</warning>

Stream Server-Sent Events from processes. See [Server-Sent Events](http/sse.md).

```yaml
post_middleware:
  - sse_relay
post_options:
  sserelay.allowed.origins: "https://app.example.com"
```

---



#### OpenTelemetry {#otel}


<note>Pre-handler</note>

Records OpenTelemetry server spans for incoming requests. Always registered; acts as a no-op when OTel or its HTTP instrumentation is disabled.

```yaml
middleware:
  - otel
```

Takes no options. Works alongside the `metrics` middleware; enable both when you need Prometheus counters and OTel traces.

---



### Middleware Order


For requests, middleware executes in listed order; response handling unwinds in reverse order. Recommended sequence:

```yaml
middleware:
  - real_ip       # 1. Extract real IP first
  - cors          # 2. Handle CORS preflight
  - compress      # 3. Set up response compression
  - ratelimit     # 4. Check rate limits
  - metrics       # 5. Record metrics
  - token_auth    # 6. Authenticate requests

post_middleware:
  - endpoint_firewall  # Authorize after route match
```



### See Also


- [Routing](http/router.md) - Router configuration
- [Security](system/security.md) - Token stores and policies
- [WebSocket Relay](http/websocket-relay.md) - WebSocket handling
- [Server-Sent Events](http/sse.md) - SSE streaming
- [Terminal](system/terminal.md) - Terminal service



---

# "Static Files"

## Static Files


An `http.static` handler mounts directly on a server and serves SPAs, assets, or user uploads from a filesystem entry.

**Classification: static-handler reference.** The YAML blocks assume the named
HTTP server exists. In these host-authored examples, relative `fs.directory`
paths are resolved from the project working directory. Module-owned entries
instead resolve relative paths from the owning module's source root unless
configured with `base: project`. The referenced files must be created separately.



### Configuration


```yaml
- name: static
  kind: http.static
  meta:
    server: gateway
  path: /
  fs: app:public
  static_options:
    spa: true
    index: index.html
    cache: "public, max-age=3600"
```

| Field | Type | Description |
|-------|------|-------------|
| `meta.server` | Registry ID | Parent HTTP server |
| `path` | string | URL mount path (must start with `/`) |
| `fs` | Registry ID | Filesystem entry to serve from |
| `static_options.spa` | bool | SPA mode - serve index for unmatched paths |
| `static_options.index` | string | Index file (required when `spa=true`) |
| `static_options.cache` | string | Cache-Control header value |
| `middleware` | []string | Middleware chain |
| `options` | map | Middleware options (dot notation) |

<tip>
Static handlers can be mounted to any path on the server. Multiple handlers can coexist—mount assets at <code>/static</code> and an SPA at <code>/</code>.
</tip>



### Filesystem Integration


Static files are served from filesystem entries. Any filesystem type works:

```yaml
entries:
  # Local directory
  - name: public
    kind: fs.directory
    directory: ./public

  # Static handler
  - name: static
    kind: http.static
    meta:
      server: gateway
    path: /static
    fs: public
```

Request `/static/css/style.css` serves `./public/css/style.css`.

To serve a subdirectory, point the `fs` reference at a filesystem entry rooted there—for example an `fs.directory` with `directory:` set to the subdirectory:

```yaml
entries:
  - name: content
    kind: fs.directory
    directory: ./app/documentation/html

  - name: docs
    kind: http.static
    meta:
      server: gateway
    path: /docs
    fs: content
```



### SPA Mode


Single Page Applications need all routes to serve the same index file for client-side routing:

```yaml
- name: spa
  kind: http.static
  meta:
    server: gateway
  path: /
  fs: app:frontend
  static_options:
    spa: true
    index: index.html
```

| Request | Response |
|---------|----------|
| `/app.js` | Serves `app.js` (file exists) |
| `/users/123` | Serves `index.html` (SPA fallback) |
| `/api/data` | Serves `index.html` (SPA fallback) |

<note>
When <code>spa: true</code>, the <code>index</code> file is required. Existing files are served directly; all other paths return the index file.
</note>



### Cache Control


Set appropriate caching for different asset types:

```yaml
entries:
  - name: app_fs
    kind: fs.directory
    directory: ./dist

  # Versioned assets - cache forever
  - name: assets
    kind: http.static
    meta:
      server: gateway
    path: /assets
    fs: app_fs
    static_options:
      cache: "public, max-age=31536000, immutable"

  # HTML - short cache, must revalidate
  - name: app
    kind: http.static
    meta:
      server: gateway
    path: /
    fs: app_fs
    static_options:
      spa: true
      index: index.html
      cache: "public, max-age=0, must-revalidate"
```

Common cache patterns:

- **Versioned assets**: `public, max-age=31536000, immutable`
- **HTML/index**: `public, max-age=0, must-revalidate`
- **User uploads**: `private, max-age=3600`



### Middleware


Apply middleware for compression, CORS, or other processing:

```yaml
- name: static
  kind: http.static
  meta:
    server: gateway
  path: /
  fs: app:public
  middleware:
    - compress
    - cors
  options:
    compress.level: "best"
    cors.allow.origins: "*"
```

Middleware wraps the static handler in order—requests pass through each middleware before reaching the file server.

<warning>
Path matching is prefix-based. A handler at <code>/</code> catches all unmatched requests. Use routers for API endpoints to avoid conflicts.
</warning>



### See Also


- [Server](http/server.md) - HTTP server configuration
- [Routing](http/router.md) - Routers and endpoints
- [Filesystem](lua/storage/filesystem.md) - Filesystem module
- [Middleware](http/middleware.md) - Available middleware



---

# "WebSocket Relay"

## WebSocket Relay


The `websocket_relay` middleware upgrades an HTTP connection and relays WebSocket messages to a target process.

**Classification: protocol reference with partial integration recipes.** The
blocks assume an HTTP server, router, process host, target process, and security
context. Application message handlers and client-state cleanup remain
application-owned.



### How It Works


1. HTTP handler sets `X-WS-Relay` header with target process PID
2. Middleware upgrades connection to WebSocket
3. Relay attaches to the target process and monitors it
4. Messages flow bidirectionally between client and process



### Process Semantics


WebSocket connections are full processes with their own PID. They integrate with the process system:

- **Addressable** → Any process can send messages to a WebSocket PID
- **Monitorable** → Processes can monitor WebSocket connections for exit events
- **Linkable** → WebSocket connections can be linked to other processes
- **EXIT events** → When connection closes, monitors receive exit notifications

```lua
-- Monitor a WebSocket connection from another process
local _, monitor_err = process.monitor(websocket_pid)
if monitor_err then return nil, monitor_err end

-- Send a message to the WebSocket client from any process.
-- The relay wraps it as {topic, data} JSON; the topic name is arbitrary.
local _, send_err = process.send(websocket_pid, "update", "hello")
if send_err then return nil, send_err end
```

<tip>
The relay monitors the target process. If the target exits, the WebSocket connection closes automatically and the client receives a close frame.
</tip>



### Connection Transfer


Connections can be transferred to a different process by sending a control message:

```lua
local _, transfer_err = process.send(websocket_pid, "ws.control", {
    target_pid = new_process_pid,
    message_topic = "ws.message"
})
if transfer_err then return nil, transfer_err end
```



### Configuration


Add as post-match middleware on a router:

```yaml
- name: ws_router
  kind: http.router
  meta:
    server: gateway
  prefix: /ws
  post_middleware:
    - websocket_relay
  post_options:
    wsrelay.allowed.origins: "https://app.example.com"
```

| Option | Description |
|--------|-------------|
| `wsrelay.allowed.origins` | Comma-separated allowed origins |

<note>
If no origins configured, only same-origin requests are allowed.
</note>



### Handler Setup


The HTTP handler spawns a process and configures the relay:

```lua
local http = require("http")
local json = require("json")

local function handler()
    local req, req_err = http.request()
    if req_err then return nil, req_err end
    local res, res_err = http.response()
    if res_err then return nil, res_err end

    local user_id, query_err = req:query("user_id")
    if query_err then return nil, query_err end

    -- Spawn handler process
    local pid, spawn_err = process.spawn("app.ws:handler", "app:processes")
    if spawn_err then return nil, spawn_err end

    -- Configure relay
    local relay_config, encode_err = json.encode({
        target_pid = tostring(pid),
        message_topic = "ws.message",
        heartbeat_interval = "30s",
        metadata = {
            user_id = user_id
        }
    })
    if encode_err then
        local _, terminate_err = process.terminate(pid)
        return nil, terminate_err or encode_err
    end

    local header_err = res:set_header("X-WS-Relay", relay_config)
    if header_err then
        local _, terminate_err = process.terminate(pid)
        return nil, terminate_err or header_err
    end
end
```



#### Relay Config Fields


| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `target_pid` | string | required | Process PID to receive messages |
| `message_topic` | string | `ws.message` | Topic for client messages |
| `heartbeat_interval` | duration | `30s` | Heartbeat frequency (e.g. `30s`) |
| `metadata` | object | - | Attached to join/leave/heartbeat messages |



### Message Topics


The relay sends these messages to the target process:

| Topic | When | Payload |
|-------|------|---------|
| `ws.join` | Client connects | JSON `{client_pid, metadata}` |
| `ws.message` (or your `message_topic`) | Client sends message | Raw client payload (text frame → String format, binary frame → Bytes format); `payload:data()` returns a Lua string for either format, and the source PID is the client PID |
| `ws.heartbeat` | Periodic (every 30s by default; interval overridable via `heartbeat_interval`) | JSON `{client_pid, uptime, message_count, metadata}` |
| `ws.leave` | Client disconnects | JSON `{client_pid, metadata}` |



### Receiving Messages


```lua
local function handler()
    local inbox = process.inbox()

    while true do
        local msg, ok = inbox:receive()
        if not ok then break end

        local topic = msg:topic()
        local from = msg:from()                -- client connection PID

        if topic == "ws.join" then
            -- Client connected — payload is {client_pid, metadata}
            local data, payload_err = msg:payload():data()
            if payload_err then return nil, payload_err end
            local client_pid = data.client_pid

        elseif topic == "ws.message" then
            -- Raw client message; from() is the client PID
            local incoming = msg:payload()
            local frame_format = incoming:get_format()     -- "text/plain" or "application/octet-stream"
            local body, payload_err = incoming:data()      -- Lua string in either case
            if payload_err then return nil, payload_err end
            -- Decode or dispatch `body` according to `frame_format` and the
            -- application's protocol.

        elseif topic == "ws.leave" then
            -- Client disconnected — payload is {client_pid, metadata}
            -- Release application state associated with `from`.
        end
    end
end
```



### Sending to Client


Send messages back using the client PID. Any topic you choose is wrapped as `{topic, data}` JSON and forwarded to the WebSocket. Every server-to-client message is sent as a single WebSocket text frame containing the wrapper. Tables remain JSON objects in `data`; strings remain strings. Payloads that reach the relay in Bytes format are base64-encoded into `data`; they are not sent as separate binary frames. Lua `process.send` exports its arguments as Lua-format payloads, so a Lua string does not take the Bytes-format branch.

```lua
-- Send a structured message (any topic name)
process.send(client_pid, "update", json.encode({event = "update", value = 42}))

-- Close connection (payload is the close reason string)
local _, close_err = process.send(client_pid, "ws.close", "Session ended")
if close_err then return nil, close_err end
```

The reserved topics from server → client are `ws.control` (relay reconfiguration) and `ws.close` (close the connection).



### Broadcasting


Track client PIDs to broadcast to multiple clients:

```lua
local clients = {}

-- On join
clients[client_pid] = true

-- On leave
clients[client_pid] = nil

-- Broadcast
local function broadcast(message)
    for pid, _ in pairs(clients) do
        local _, send_err = process.send(pid, "broadcast", message)
        if send_err then return nil, send_err end
    end
    return true
end
```

<tip>
For complex multi-room scenarios, spawn a separate handler process per room or use a central manager process that tracks room memberships.
</tip>



### See Also


- [Middleware](http/middleware.md) - Middleware configuration
- [Process](lua/core/process.md) - Process messaging
- [WebSocket Client](lua/http/websocket.md) - Outbound WebSocket connections



---

# "Server-Sent Events"

## Server-Sent Events


The SSE middleware streams events from the server to HTTP clients using the [Server-Sent Events](https://html.spec.whatwg.org/multipage/server-sent-events.html) protocol.

Two mechanisms are available: **direct streaming** from an HTTP handler, and **process-backed relay** via the `sse_relay` middleware.

**Classification: protocol reference with partial integration recipes.** The
relay blocks assume an HTTP server, router, process host, target process, and
security context already exist. Application callbacks and client behavior are
outside these snippets.



### Direct Streaming


Use `res:write_event()` to send SSE events directly from an HTTP handler. The response automatically switches to SSE mode on the first call, setting appropriate headers.

```lua
local http = require("http")

local function handler()
    local res, res_err = http.response()
    if res_err then return nil, res_err end

    local err = res:write_event({name = "status", data = {state = "started"}})
    if err then return nil, err end
    err = res:write_event({name = "progress", data = {percent = 50}})
    if err then return nil, err end
    err = res:write_event({name = "status", data = {state = "complete"}})
    if err then return nil, err end
    return true
end
```

Each event requires a `name` and `data` field. The `data` value is JSON-encoded automatically.

<tip>
Direct streaming is suitable for short-lived request-response flows like progress updates. For long-lived connections managed by background processes, use the SSE Relay.
</tip>



### SSE Relay


The SSE Relay middleware creates long-lived SSE streams backed by processes. It follows the same relay pattern as [WebSocket Relay](http/websocket-relay.md).



#### How It Works


1. HTTP handler sets `X-SSE-Relay` header with a JSON relay configuration
2. Middleware intercepts the response and creates an SSE session
3. Session registers as a process with its own PID
4. Messages sent to the session PID are forwarded as SSE events to the client



### Process Semantics


SSE streams are full processes with their own PID. They integrate with the process system:

- **Addressable** — Any process can send messages to a stream PID
- **Monitorable** — Processes can monitor SSE streams for exit events
- **Linkable** — SSE streams can be linked to other processes
- **EXIT events** — When a stream closes, monitors receive exit notifications

```lua
-- Send event to SSE client from any process
local _, send_err = process.send(stream_pid, "sse.message", {event = "update", value = 42})
if send_err then return nil, send_err end

-- Monitor an SSE stream
local _, monitor_err = process.monitor(stream_pid)
if monitor_err then return nil, monitor_err end
```

<tip>
The relay monitors the target process. If the target exits, the SSE stream closes automatically and the client receives a `done` event.
</tip>



### Configuration


Add as post-match middleware on a router:

```yaml
- name: sse_router
  kind: http.router
  meta:
    server: gateway
  prefix: /sse
  post_middleware:
    - sse_relay
  post_options:
    sserelay.allowed.origins: "https://app.example.com"
```

| Option | Description |
|--------|-------------|
| `sserelay.allowed.origins` | Comma-separated allowed origins (supports wildcards) |

<note>
If no origins are configured, only same-origin requests are allowed.
</note>



### Handler Setup


The HTTP handler spawns a process and configures the relay:

```lua
local http = require("http")
local json = require("json")

local function handler()
    local req, req_err = http.request()
    if req_err then return nil, req_err end
    local res, res_err = http.response()
    if res_err then return nil, res_err end

    local user_id, query_err = req:query("user_id")
    if query_err then return nil, query_err end

    -- Spawn handler process
    local pid, spawn_err = process.spawn("app.sse:handler", "app:processes")
    if spawn_err then return nil, spawn_err end

    -- Configure relay
    local relay_config, encode_err = json.encode({
        target_pid = tostring(pid),
        message_topic = "sse.message",
        heartbeat_interval = "30s",
        metadata = {
            user_id = user_id
        }
    })
    if encode_err then
        local _, terminate_err = process.terminate(pid)
        return nil, terminate_err or encode_err
    end

    local header_err = res:set_header("X-SSE-Relay", relay_config)
    if header_err then
        local _, terminate_err = process.terminate(pid)
        return nil, terminate_err or header_err
    end
end
```



#### Relay Config Fields


| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `target_pid` | string | — | Process PID to receive messages (omit for detached mode) |
| `message_topic` | string | `sse.message` | Topic filter for forwarded events |
| `heartbeat_interval` | duration | `30s` | Heartbeat frequency (e.g. `30s`, `1m`) |
| `idle_timeout` | duration | — | Close stream after inactivity |
| `hard_timeout` | duration | — | Close stream after absolute duration |
| `metadata` | object | — | Attached to join/leave/heartbeat messages |



#### Managed Mode


When `target_pid` is set, the relay operates in managed mode:

- Monitors the target process
- Sends `sse.join` on connect and `sse.leave` on disconnect
- Closes the stream automatically if the target exits



#### Detached Mode


When `target_pid` is omitted, the relay starts in detached mode:

- Emits a `ready` event to the client with `stream_pid` and `message_topic`
- No process is monitored initially
- A process can attach later by sending an `sse.control` message

Inside a handler that has imported `json` and obtained the response object as
`res`, set up detached mode and check both operations:

```lua
-- Detached setup: no target_pid
local relay_config, encode_err = json.encode({
    heartbeat_interval = "30s"
})
if encode_err then return nil, encode_err end

local header_err = res:set_header("X-SSE-Relay", relay_config)
if header_err then return nil, header_err end
```

The client receives a `ready` event:

```json
{"stream_pid": "{n1@app:gateway|0x0002a}", "message_topic": "sse.message"}
```



### Message Topics


The relay uses these topics for communication between the stream and target process:

| Topic | Direction | When | Payload |
|-------|-----------|------|---------|
| `sse.join` | stream → target | Client connects | `client_pid`, `metadata` |
| `sse.message` | target → stream | Default event topic | Forwarded as SSE event |
| `sse.heartbeat` | stream → target | Periodic (every 30s by default) | `client_pid`, `uptime`, `message_count`, `metadata` |
| `sse.leave` | stream → target | Client disconnects | `client_pid`, `metadata` |
| `sse.control` | any → stream | Control command | Relay config fields |
| `sse.close` | any → stream | Force close | Optional reason string |



### Receiving in Target Process


```lua
local function handler()
    local inbox = process.inbox()

    while true do
        local msg, ok = inbox:receive()
        if not ok then break end

        local topic = msg:topic()
        local data, payload_err = msg:payload():data()
        if payload_err then return nil, payload_err end

        if topic == "sse.join" then
            local client_pid = data.client_pid

        elseif topic == "sse.heartbeat" then
            -- Periodic health check

        elseif topic == "sse.leave" then
            -- Release application state associated with data.client_pid.
        end
    end
end
```



### Sending Events


Send events to the client by messaging the stream PID:

```lua
-- Send on the default message topic
local _, send_err = process.send(stream_pid, "sse.message", {
    event = "update",
    value = 42
})
if send_err then return nil, send_err end

-- Force close the stream
local _, close_err = process.send(stream_pid, "sse.close", "session expired")
if close_err then return nil, close_err end
```

Events sent on the configured `message_topic` are forwarded to the client as SSE events. The topic name becomes the SSE event name.



### Connection Transfer


Send a control message to change the target process, topic filter, or timeouts dynamically:

```lua
local _, transfer_err = process.send(stream_pid, "sse.control", {
    target_pid = tostring(new_pid),
    message_topic = "custom.topic",
    idle_timeout = "5m"
})
if transfer_err then return nil, transfer_err end
```

When the target changes, the relay first monitors and sends `sse.join` to the new target, then stops monitoring and sends `sse.leave` to the old one. Set `target_pid` to an empty string to detach without reattaching.



### See Also


- [Middleware](http/middleware.md) — Middleware configuration
- [WebSocket Relay](http/websocket-relay.md) — WebSocket equivalent
- [Process](lua/core/process.md) — Process messaging



---

# "Hello World"

## Hello World


Your first Wippy application - a simple HTTP API that returns JSON.



### What We're Building


A minimal web API with one endpoint:

```
GET /hello → {"message": "hello world"}
```



### Project Structure


```
hello-world/
├── wippy.lock           # Generated lock file
└── src/
    ├── _index.yaml      # Entry definitions
    └── hello.lua        # Handler code
```



### Step 1: Create Project Directory


```bash
mkdir hello-world && cd hello-world
mkdir src
```



### Step 2: Entry Definitions


Create `src/_index.yaml`:

```yaml
version: "1.0"
namespace: app

entries:
  # HTTP server
  - name: gateway
    kind: http.service
    addr: ":8080"
    lifecycle:
      auto_start: true

  # Router
  - name: api
    kind: http.router
    meta:
      server: app:gateway
    prefix: /

  # Handler function
  - name: hello
    kind: function.lua
    source: file://hello.lua
    method: handler
    modules:
      - http

  # Endpoint
  - name: hello.endpoint
    kind: http.endpoint
    meta:
      router: app:api
    method: GET
    func: app:hello
    path: /hello
```

**Four entries work together:**

1. `gateway` - HTTP server listening on port 8080
2. `api` - Router attached to gateway via `meta.server`
3. `hello` - Lua function that handles requests
4. `hello.endpoint` - Routes `GET /hello` to the function



### Step 3: Handler Code


Create `src/hello.lua`:

```lua
local http = require("http")

local function handler()
    local res = http.response()

    res:set_content_type(http.CONTENT.JSON)
    res:set_status(http.STATUS.OK)
    res:write_json({message = "hello world"})
end

return {
    handler = handler
}
```

The `http` module provides access to request/response objects. The function returns a table with the exported `handler` method.



### Step 4: Initialize and Run


```bash


## Generate lock file from source

wippy init



## Start the runtime (-c for colorful console output)

wippy run -c
```

You'll see output like:

```
╦ ╦╦╔═╗╔═╗╦ ╦  Adaptive Application Runtime https://wippy.ai
║║║║╠═╝╠═╝╚╦╝  v0.3.40a
╚╩╝╩╩  ╩   ╩   by Spiral Scout

0.00s  INFO  run          runtime ready
0.11s  INFO  core         service app:gateway is running  {"details": "service listening on :8080"}
```



### Step 5: Test It


```bash
curl http://localhost:8080/hello
```

Response:

```json
{"message":"hello world"}
```



### How It Works


1. `gateway` accepts the TCP connection on port 8080
2. `api` router matches the path prefix `/`
3. `hello.endpoint` matches `GET /hello`
4. `hello` function executes and writes JSON response



### CLI Reference


| Command | Description |
|---------|-------------|
| `wippy init` | Generate lock file from `src/` |
| `wippy run` | Start runtime from lock file |
| `wippy run -c` | Start with colorful console output |
| `wippy run -v` | Start with verbose debug logging |
| `wippy run -s` | Start in silent mode (no console logs) |



### Next Steps


- [Echo Service](tutorials/echo-service.md) - Handle request parameters
- [Task Queue](tutorials/task-queue.md) - REST API with background processing
- [HTTP Router](http/router.md) - Routing patterns



---

# "CLI Applications"

## CLI Applications


Build a command-line process that writes to the terminal, then extend it with input, color, system information, and named commands.

**Classification:** Runnable tutorial. The greeting application is complete. The
later sections are optional replacements for `src/cli.lua` or the `app:cli` entry,
as stated in each section.



### What We're Building


A CLI process that prints a greeting:

```
$ wippy run -x app:cli
Hello from CLI!
```



### Prerequisites


- Wippy runtime `v0.3.32a` available as `wippy`. Confirm it with
  `wippy version --short`.
- An interactive terminal. Input examples require stdin, and color examples require
  a terminal that displays ANSI escape sequences.



### Project Structure


```
cli-app/
├── wippy.lock
└── src/
    ├── _index.yaml
    └── cli.lua
```



### Step 1: Create Project


```bash
mkdir cli-app && cd cli-app
mkdir src
```



### Step 2: Entry Definitions


Create `src/_index.yaml`:

```yaml
version: "1.0"
namespace: app

entries:
  # Terminal host connects processes to stdin/stdout
  - name: terminal
    kind: terminal.host
    lifecycle:
      auto_start: true

  # CLI process
  - name: cli
    kind: process.lua
    source: file://cli.lua
    method: main
    modules:
      - io
```

<tip>
The <code>terminal.host</code> bridges your Lua process to the terminal. Without it, <code>io.print()</code> has nowhere to write.
</tip>



### Step 3: CLI Code


Create `src/cli.lua`:

```lua
local io = require("io")

local function main()
    io.print("Hello from CLI!")
    return 0
end

return { main = main }
```



### Step 4: Run It


```bash
wippy init
wippy run -x app:cli
```

Expected output:

```
Hello from CLI!
```

<note>
The <code>-x</code> flag runs the process as a command. It auto-detects the only
<code>terminal.host</code> in the registry; use <code>--host</code> when more than one
terminal host exists. With no logging flag, command mode suppresses runtime logs so
the process output stays readable.
</note>



### Reading User Input


Replace `src/cli.lua` with this version. It reports terminal read and write errors
instead of treating them as empty input:

```lua
local io = require("io")

local function main()
    local _, write_err = io.write("Enter your name: ")
    if write_err then
        io.eprint("Cannot write prompt:", write_err)
        return 1
    end

    local _, flush_err = io.flush()
    if flush_err then
        io.eprint("Cannot flush prompt:", flush_err)
        return 1
    end

    local name, read_err = io.readline()
    if read_err then
        io.eprint("Cannot read input:", read_err)
        return 1
    end

    if name and #name > 0 then
        io.print("Hello, " .. name .. "!")
    else
        io.print("Hello, stranger!")
    end

    return 0
end

return { main = main }
```



### Colored Output


Replace `src/cli.lua` with this version to use ANSI escape codes for colors:

```lua
local io = require("io")

local reset = "\027[0m"
local function red(s) return "\027[31m" .. s .. reset end
local function green(s) return "\027[32m" .. s .. reset end
local function yellow(s) return "\027[33m" .. s .. reset end
local function cyan(s) return "\027[36m" .. s .. reset end
local function bold(s) return "\027[1m" .. s .. reset end

local function main()
    io.print(bold(cyan("Welcome!")))
    local _, write_err = io.write(yellow("Enter a number: "))
    if write_err then
        io.eprint("Cannot write prompt:", write_err)
        return 1
    end

    local _, flush_err = io.flush()
    if flush_err then
        io.eprint("Cannot flush prompt:", flush_err)
        return 1
    end

    local input, read_err = io.readline()
    if read_err then
        io.eprint("Cannot read input:", read_err)
        return 1
    end
    local n = tonumber(input)

    if n then
        io.print("Squared: " .. green(tostring(n * n)))
        return 0
    else
        io.print(red("Error: ") .. "not a number")
        return 1
    end
end

return { main = main }
```



### System Information


Access runtime stats with the `system` module. Every read is guarded by the `system.read` action, so the process also needs a policy that allows it:

```yaml
  # Add to entries
  - name: system_read
    kind: security.policy
    policy:
      actions:
        - system.read
      resources: "*"
      effect: allow

  # Update the CLI entry
  - name: cli
    kind: process.lua
    source: file://cli.lua
    method: main
    security:
      policies:
        - app:system_read
    modules:
      - io
      - system
```

Then replace `src/cli.lua`:

```lua
local io = require("io")
local system = require("system")

local function main()
    local hostname, hostname_err = system.process.hostname()
    if hostname_err then
        io.eprint("Cannot read hostname:", hostname_err)
        return 1
    end

    local cpu_count, cpu_err = system.runtime.cpu_count()
    if cpu_err then
        io.eprint("Cannot read CPU count:", cpu_err)
        return 1
    end

    local goroutines, goroutine_err = system.runtime.goroutines()
    if goroutine_err then
        io.eprint("Cannot read goroutine count:", goroutine_err)
        return 1
    end

    local mem, memory_err = system.memory.stats()
    if memory_err then
        io.eprint("Cannot read memory stats:", memory_err)
        return 1
    end

    io.print("Host: " .. hostname)
    io.print("CPUs: " .. cpu_count)
    io.print("Goroutines: " .. goroutines)
    io.print("Memory: " .. string.format("%.1f MB", mem.heap_alloc / 1024 / 1024))

    return 0
end

return { main = main }
```



### Named Commands


To invoke the process by name instead of using `-x app:cli`, add command metadata:

Replace the `app:cli` entry with this version. Keep the `terminal.host` entry from
the base project.

```yaml
  - name: cli
    kind: process.lua
    meta:
      command:
        name: greet
        short: Greet the user
    source: file://cli.lua
    method: main
    modules:
      - io
```

Run the named command:

```bash
wippy run greet
```

List all available commands:

```bash
wippy run list
```

```
Available commands:

  greet  Greet the user  (app:cli)

Run with: wippy run <command>
```



### Exit Codes


Return a number from `main()` to set the process exit code:

```lua
local function main()
    if error_occurred then
        return 1  -- Error
    end
    return 0      -- Success
end
```



### I/O Reference


| Function | Returns | Description |
|----------|---------|-------------|
| `io.print(...)` | `boolean` or `nil, error` without terminal context | Write to stdout with tabs and a trailing newline |
| `io.write(...)` | `boolean, error` | Write to stdout without separators or a newline |
| `io.eprint(...)` | `boolean` or `nil, error` without terminal context | Write to stderr with tabs and a trailing newline |
| `io.readline()` | `string, error` | Read a line without its trailing newline; EOF with no data is an error |
| `io.flush()` | `boolean, error` | Flush stdout when the stream supports it |



### CLI Flags


| Flag | Description |
|------|-------------|
| `wippy run -x app:cli` | Run CLI process (auto-detects terminal.host) |
| `wippy run -x app:cli --host app:terminal` | Explicit terminal host |
| `wippy run -x app:cli -v` | With verbose logging |



### Troubleshooting and Cleanup


- `no terminal host found` means the registry has no `terminal.host`; use the entry
  from Step 2. If multiple hosts exist, pass `--host app:terminal`.
- `no terminal context` means the process was not launched through a terminal host.
  Use `wippy run -x app:cli`, not a background `process.service`.
- Input errors at EOF are expected when stdin is closed. Run the command in an
  interactive terminal for the input examples.
- If ANSI sequences appear as literal characters, use the non-color example or a
  terminal with ANSI support.
- The command exits after `main()` returns. After leaving the directory, delete
  `cli-app/` if it was only a disposable exercise.



### Next Steps


- [I/O Module](lua/system/io.md) — I/O API reference
- [System Module](lua/system/system.md) — Runtime and system information
- [Echo Service](tutorials/echo-service.md) — Build a multi-process application



---

# "Terminal UI"

## Terminal UI


Build a terminal application that owns the screen, draws styled frames, and hosts another process inside a bordered region of its own layout.



### What We're Building


A shell process runs on a terminal host and takes the physical terminal's presentation lease. It paints a header, a status bar, and a border. Inside that border it hosts a second process, which runs an interactive Bash through a pseudo-terminal.

```text
physical terminal -> shell surface -> viewport -> child process -> PTY proxy
```

The shell decides where the child appears and translates input into the child's coordinates. The child sees an ordinary terminal port and never learns that it is framed.



### Project Structure


```
tty-app/
├── wippy.lock
└── src/
    ├── _index.yaml
    ├── shell.lua
    └── child.lua
```

```bash
mkdir tty-app && cd tty-app
mkdir src
```



### Step 1: Entry Definitions


Create `src/_index.yaml`:

```yaml
version: "1.0"
namespace: app

entries:
  - name: policy
    kind: security.policy
    policy:
      actions:
        - process.context
        - process.spawn
        - process.spawn.monitored
        - process.host
        - process.terminate
        - exec.get
        - exec.run
      resources: "*"
      effect: allow

  # Runs the child process
  - name: workers
    kind: process.host
    host:
      workers: 2
    lifecycle:
      auto_start: true

  # Owns the physical terminal
  - name: terminal
    kind: terminal.host
    hide_logs: true
    lifecycle:
      auto_start: true

  - name: exec
    kind: exec.native

  - name: child
    kind: process.lua
    source: file://child.lua
    method: main
    modules: [channel, exec, tty]
    security:
      policies: [app:policy]

  - name: shell
    kind: process.lua
    source: file://shell.lua
    method: main
    modules: [channel, process, time, tty]
    meta:
      command:
        name: shell
        short: Run the terminal shell
        security:
          actor: {id: app:shell}
          policies: [app:policy]
```

<note>
<code>hide_logs: true</code> redirects log output to the event bus instead of the terminal. A process that owns a surface publishes complete frames, so anything else writing to the same terminal corrupts them.
</note>



### Step 2: The Input Loop


Create `src/shell.lua`. Subscribe to events first, then start input delivery, so no event arrives before there is a consumer:

```lua
local tty = require("tty")

local function main()
    local events = assert(tty.events())
    assert(tty.start())
    assert(tty.mouse(true))

    local width, height = tty.screen_size()
    width = math.max(20, math.floor(width or 80))
    height = math.max(8, math.floor(height or 24))

    while true do
        local ev = events:receive()
        if not ev then break end

        if ev.type == "resize" then
            width, height = ev.width, ev.height
        elseif ev.type == "key" and ev.ctrl and ev.key == "q" then
            break
        end
    end

    assert(tty.stop())
end

return {main = main}
```

Events are records discriminated by `type`. For a printable key, `key_type` is `"runes"` and `key` holds the text; for a named key, both `key_type` and `key` hold the name (`"enter"`, `"backspace"`, `"space"`, `"up"`). Coordinates in mouse events are one-based.



### Step 3: Drawing Frames


A `Surface` is the terminal's presentation lease: it takes complete row arrays and diffs them against the last frame. A `Canvas` composes those rows from styled text without emitting terminal control sequences of its own.

Add styles and a padding helper at the top of `shell.lua`:

```lua
local tty = require("tty")

local header_style = tty.style():bold():foreground("#eceff4"):background("#5e81ac")
local status_style = tty.style():foreground("#a3be8c")
local prompt_style = tty.style():foreground("#88c0d0")

local function fit(text, width)
    local clipped = tty.text.truncate(text, width)
    return clipped .. string.rep(" ", math.max(0, width - tty.text.width(clipped)))
end
```

`tty.text.truncate` and `tty.text.width` are ANSI-aware, so styled text is measured and clipped by printable cells rather than bytes.

Now open a surface and publish a frame with a header, a scrollable body, a status bar, and an input line pinned to the last row:

```lua
local function main()
    local events = assert(tty.events())
    assert(tty.start())
    assert(tty.mouse(true))

    local surface = assert(tty.surface({
        alternate_screen = true,
        hide_cursor = true,
        synchronized_output = true,
    }))

    local width, height = tty.screen_size()
    width = math.max(20, math.floor(width or 80))
    height = math.max(8, math.floor(height or 24))
    local canvas = tty.canvas(width, height)

    local lines, scroll, input = {}, 0, ""

    local function draw()
        local body_height = height - 3
        canvas:clear()
        canvas:put(1, 1, header_style:render(fit(" wippy tui — Ctrl+Q to quit ", width)))

        local first = math.max(1, #lines - body_height + 1 - scroll)
        for row = 1, body_height do
            local line = lines[first + row - 1]
            if line then
                canvas:put(2, row + 1, line, width - 2)
            end
        end

        canvas:put(1, height - 1, status_style:render(fit(
            string.format(" %d lines   scroll %d   %dx%d", #lines, scroll, width, height), width)))
        canvas:put(1, height, prompt_style:render("> ") .. input)

        assert(surface:present(canvas:rows(), {
            cursor = {x = math.min(width, 3 + tty.text.width(input)), y = height, visible = true},
        }))
    end

    draw()
    while true do
        local ev = events:receive()
        if not ev then break end

        if ev.type == "resize" then
            width = math.max(20, ev.width)
            height = math.max(8, ev.height)
            canvas = tty.canvas(width, height)
            surface:invalidate()
        elseif ev.type == "key" and ev.ctrl and ev.key == "q" then
            break
        elseif ev.type == "key" and ev.action == "press" then
            if ev.key == "enter" then
                lines[#lines + 1] = "> " .. input
                input, scroll = "", 0
            elseif ev.key == "backspace" then
                input = input:sub(1, -2)
            elseif ev.key == "space" and not ev.ctrl and not ev.alt then
                input = input .. " "
            elseif ev.key_type == "runes" and not ev.ctrl and not ev.alt then
                input = input .. ev.key
            end
        elseif ev.type == "mouse" and ev.action == "wheel" then
            if ev.button == "wheel_up" then
                scroll = scroll + 1
            elseif ev.button == "wheel_down" then
                scroll = math.max(0, scroll - 1)
            end
        end
        draw()
    end

    assert(surface:close())
    assert(tty.stop())
end
```

Each `present` publishes the whole frame; the backend writes only the rows that changed and reports `rows`, `changed_rows`, and `bytes_written`. `invalidate()` forgets that comparison state, which is what you want after the outer terminal resized under you.



### Step 4: Hosting a Child


A `Viewport` is a virtual terminal port. The shell creates one, hands the child its grant, and reads back the frames the child presents.

Replace the body of the layout with a bordered region and put the viewport rows inside it:

```lua
local channel = require("channel")
local process = require("process")
local tty = require("tty")

local BODY_X, BODY_Y = 2, 3            -- top-left cell inside the border
local CHROME_ROWS = 5                  -- header, two border rows, status, hint

local border_style = tty.style():foreground("#4c566a")
local hint_style = tty.style():faint()
```

Create the viewport, spawn the child with its grant, and subscribe to update watermarks:

```lua
    local inner_width = math.max(1, width - 2)
    local inner_height = math.max(1, height - CHROME_ROWS)

    local viewport = assert(tty.viewport({width = inner_width, height = inner_height}))
    local updates = assert(viewport:updates())
    local child = assert(process.with_options({terminal = assert(viewport:grant())})
        :spawn_monitored("app:child", "app:workers", "/bin/bash --noprofile --norc"))
```

The grant is one-shot. Admission consumes it: a rejected start leaves it unresolved, and a host that cannot attach terminals rejects the spawn instead of silently dropping the option.

Draw the border yourself and place the child's rows inside it with `put_rows`, which validates every row before drawing anything:

```lua
    local function draw()
        canvas:clear()
        canvas:put(1, 1, header_style:render(fit(" wippy shell — Ctrl+Q to quit ", width)))
        canvas:put(1, 2, border_style:render("┌" .. string.rep("─", inner_width) .. "┐"))
        for row = 1, inner_height do
            canvas:put(1, BODY_Y + row - 1, border_style:render("│"))
            canvas:put(width, BODY_Y + row - 1, border_style:render("│"))
        end
        canvas:put_rows(BODY_X, BODY_Y, frame.rows, inner_width)
        canvas:put(1, BODY_Y + inner_height,
            border_style:render("└" .. string.rep("─", inner_width) .. "┘"))
        canvas:put(1, height - 1, status_style:render(fit(" " .. status, width)))
        canvas:put(1, height, hint_style:render(fit(
            string.format(" child viewport %dx%d", inner_width, inner_height), width)))

        local cursor = {x = 1, y = height, visible = false}
        if frame.cursor then
            cursor = {
                x = math.min(width, BODY_X + frame.cursor.x - 1),
                y = math.min(height, BODY_Y + frame.cursor.y - 1),
                visible = frame.cursor.visible,
            }
        end
        assert(surface:present(canvas:rows(), {cursor = cursor}))
    end
```

The child publishes into the viewport; the shell learns about it through `updates`, then reads state with `snapshot`:

```lua
        if selected.channel == updates then
            local next_frame = viewport:snapshot(revision)
            if next_frame then
                frame, revision = next_frame, next_frame.revision
                if #frame.rows > 0 then ready = true end
                draw()
            end
        end
```

Updates are coalesced watermarks, not an event log: a slow shell gets only the newest one and must call `snapshot()` for the actual rows. Passing the last revision makes `snapshot` return `nil` when nothing changed. A new revision does not mean the child has drawn: `viewport:resize` bumps it as well, and until the first frame the snapshot carries no rows. That is why `ready` keys on `rows` rather than on the revision.

Input goes the other way through `viewport:send`. Key events pass through unchanged; mouse coordinates have to be moved into the child's one-based space, and events outside the region are dropped:

```lua
    local function translate(event)
        if event.type ~= "mouse" then
            return event
        end
        local x, y = event.x - BODY_X + 1, event.y - BODY_Y + 1
        if x < 1 or y < 1 or x > inner_width or y > inner_height then
            return nil
        end
        return {
            type = "mouse", action = event.action, button = event.button,
            x = x, y = y, alt = event.alt, ctrl = event.ctrl, shift = event.shift,
        }
    end
```

`send` requires the producer to have called `tty.start()`, so the shell waits for the first frame before forwarding anything. That is what the `ready` flag tracks.



### Step 5: The Child


Create `src/child.lua`. The child receives an ordinary terminal port, so it uses the same `tty` module — but instead of drawing itself, it hands its port to a PTY-backed process.

```lua
local channel = require("channel")
local exec = require("exec")
local tty = require("tty")

local function main(command)
    local events = assert(tty.events())
    assert(tty.start())

    local executor = assert(exec.get("app:exec"))
    local proc = assert(executor:exec(command or "/bin/bash --noprofile --norc", {
        pty = {term = "xterm-256color"},
    }))
    local session = assert(proc:attach_terminal())
    local done = session:done()

    while true do
        local selected = channel.select({
            events:case_receive(),
            done:case_receive(),
        })
        if not selected.ok or selected.channel == done then break end

        local event = selected.value
        if event.type == "close" then break end
        assert(session:send(event))
    end

    assert(session:close())
    assert(executor:release())
    assert(tty.stop())
end

return {main = main}
```

`attach_terminal()` consumes the unstarted PTY process and returns a `TerminalSession` that owns it: PTY emulation, input encoding, resize, termination, and reaping. The session opens the surface on whichever port the child holds, so the same code works whether the child runs on a terminal host or inside a viewport.

Everything the child forwards — keys, mouse, paste, focus, and the `resize` events the shell generates — becomes terminal input for Bash. A `close` event is the shell asking for a graceful exit.



### Step 6: Resize, Shutdown, and Cleanup


A resize of the outer terminal changes three things: the shell's own geometry, the viewport's geometry, and the backend's idea of what is already on screen.

```lua
            if event.type == "resize" then
                width = math.max(20, math.floor(event.width))
                height = math.max(8, math.floor(event.height))
                inner_width = math.max(1, width - 2)
                inner_height = math.max(1, height - CHROME_ROWS)
                canvas = tty.canvas(width, height)
                assert(viewport:resize(inner_width, inner_height))
                surface:invalidate()
                draw()
            end
```

`viewport:resize` bumps the revision for viewers and delivers a `resize` event to the child, which forwards it to its terminal session, which resizes the PTY. One shell-side call reaches all the way down.

Ctrl+Q asks the child to stop and arms a deadline, so an unresponsive child cannot hang the shell:

```lua
            elseif event.type == "key" and event.ctrl and event.key == "q" then
                if not closing then
                    closing = true
                    status = "closing child"
                    if ready then
                        assert(viewport:send({type = "close"}))
                    else
                        assert(process.terminate(child))
                    end
                    deadline = time.after("3s")
                    draw()
                end
```

The loop watches lifecycle events for the child's exit, and the deadline channel for the case where it never comes:

```lua
        elseif selected.channel == lifecycle then
            local event = selected.value
            if event.kind == process.event.EXIT and event.from == child then break end
        elseif deadline and selected.channel == deadline then
            assert(process.terminate(child))
            deadline = nil
```

Tear down inside out: detach the viewer, release the presentation lease, then stop input.

```lua
    assert(viewport:close())
    assert(surface:close())
    assert(tty.stop())
```

Closing a viewport detaches only that viewer; it never kills the producer. Closing the surface restores the terminal modes it acquired — the alternate screen and the cursor.



### Complete Shell


`src/shell.lua`:

```lua
local channel = require("channel")
local process = require("process")
local time = require("time")
local tty = require("tty")

local BODY_X, BODY_Y = 2, 3
local CHROME_ROWS = 5

local header_style = tty.style():bold():foreground("#eceff4"):background("#5e81ac")
local border_style = tty.style():foreground("#4c566a")
local status_style = tty.style():foreground("#a3be8c")
local hint_style = tty.style():faint()

local function fit(text, width)
    local clipped = tty.text.truncate(text, width)
    return clipped .. string.rep(" ", math.max(0, width - tty.text.width(clipped)))
end

local function main()
    local events = assert(tty.events())
    local lifecycle = assert(process.events())
    assert(tty.start())
    assert(tty.mouse(true))

    local surface = assert(tty.surface({
        alternate_screen = true,
        hide_cursor = true,
        synchronized_output = true,
    }))

    local width, height = tty.screen_size()
    width = math.max(20, math.floor(width or 80))
    height = math.max(8, math.floor(height or 24))
    local inner_width = math.max(1, width - 2)
    local inner_height = math.max(1, height - CHROME_ROWS)
    local canvas = tty.canvas(width, height)

    local viewport = assert(tty.viewport({width = inner_width, height = inner_height}))
    local updates = assert(viewport:updates())
    local child = assert(process.with_options({terminal = assert(viewport:grant())})
        :spawn_monitored("app:child", "app:workers", "/bin/bash --noprofile --norc"))

    local frame = {rows = {}}
    local revision = -1
    local ready, closing = false, false
    local status = "starting child"
    local deadline

    local function draw()
        canvas:clear()
        canvas:put(1, 1, header_style:render(fit(" wippy shell — Ctrl+Q to quit ", width)))
        canvas:put(1, 2, border_style:render("┌" .. string.rep("─", inner_width) .. "┐"))
        for row = 1, inner_height do
            canvas:put(1, BODY_Y + row - 1, border_style:render("│"))
            canvas:put(width, BODY_Y + row - 1, border_style:render("│"))
        end
        canvas:put_rows(BODY_X, BODY_Y, frame.rows, inner_width)
        canvas:put(1, BODY_Y + inner_height,
            border_style:render("└" .. string.rep("─", inner_width) .. "┘"))
        canvas:put(1, height - 1, status_style:render(fit(" " .. status, width)))
        canvas:put(1, height, hint_style:render(fit(
            string.format(" child viewport %dx%d", inner_width, inner_height), width)))

        local cursor = {x = 1, y = height, visible = false}
        if frame.cursor then
            cursor = {
                x = math.min(width, BODY_X + frame.cursor.x - 1),
                y = math.min(height, BODY_Y + frame.cursor.y - 1),
                visible = frame.cursor.visible,
            }
        end
        assert(surface:present(canvas:rows(), {cursor = cursor}))
    end

    local function translate(event)
        if event.type ~= "mouse" then
            return event
        end
        local x, y = event.x - BODY_X + 1, event.y - BODY_Y + 1
        if x < 1 or y < 1 or x > inner_width or y > inner_height then
            return nil
        end
        return {
            type = "mouse", action = event.action, button = event.button,
            x = x, y = y, alt = event.alt, ctrl = event.ctrl, shift = event.shift,
        }
    end

    draw()
    while true do
        local cases = {
            events:case_receive(),
            lifecycle:case_receive(),
            updates:case_receive(),
        }
        if deadline then
            cases[#cases + 1] = deadline:case_receive()
        end

        local selected = channel.select(cases)
        if not selected.ok then break end

        if selected.channel == updates then
            local next_frame = viewport:snapshot(revision)
            if next_frame then
                frame, revision = next_frame, next_frame.revision
                if #frame.rows > 0 then ready = true end
                if not closing then
                    status = "child running"
                end
                draw()
            end
        elseif selected.channel == lifecycle then
            local event = selected.value
            if event.kind == process.event.EXIT and event.from == child then break end
        elseif deadline and selected.channel == deadline then
            assert(process.terminate(child))
            deadline = nil
        else
            local event = selected.value
            if event.type == "resize" then
                width = math.max(20, math.floor(event.width))
                height = math.max(8, math.floor(event.height))
                inner_width = math.max(1, width - 2)
                inner_height = math.max(1, height - CHROME_ROWS)
                canvas = tty.canvas(width, height)
                assert(viewport:resize(inner_width, inner_height))
                surface:invalidate()
                draw()
            elseif event.type == "key" and event.ctrl and event.key == "q" then
                if not closing then
                    closing = true
                    status = "closing child"
                    if ready then
                        assert(viewport:send({type = "close"}))
                    else
                        assert(process.terminate(child))
                    end
                    deadline = time.after("3s")
                    draw()
                end
            elseif not closing and ready and event.type ~= "start" then
                local forwarded = translate(event)
                if forwarded then
                    assert(viewport:send(forwarded))
                end
            end
        end
    end

    assert(viewport:close())
    assert(surface:close())
    assert(tty.stop())
end

return {main = main}
```



### Run It


```bash
wippy init
wippy run shell
```

Type in the framed Bash normally — arrow keys, tab completion, and full-screen programs such as `htop` or `vim` all work, because the child is talking to a real PTY. Resize the terminal window and the border, the status bar, and the child's geometry follow. Press Ctrl+Q to close the child and restore the terminal.



### Where to Go Next


- Create a second viewport and split the body between two children, forwarding input only to the focused one.
- Call `viewport:handle()` and pass the handle to another process, which attaches with `tty.attach(handle)` and renders the same child in its own layout.
- Replace the Bash child with a Lua process that draws its own surface: the shell does not change, because the viewport is the only contract between them.



### See Also


- [TTY](lua/system/tty.md) — events, surfaces, canvases, viewports, styles, and text utilities
- [Command Execution](lua/dynamic/exec.md) — PTY options, `attach_terminal`, and terminal sessions
- [Terminal](system/terminal.md) — terminal host configuration and the composable terminal model
- [Processes](lua/core/process.md) — spawn options, monitoring, and lifecycle events
- [CLI Applications](tutorials/cli.md) — line-oriented terminal programs



---

# "Echo Service"

## Echo Service


Build a CLI echo service that uses multiple Wippy processes, channels, coroutines, message passing, and process monitoring.

**Classification:** Runnable tutorial. It provides the complete registry and Lua
sources for a local, single-node CLI application, plus startup and verification
steps.



### Overview


This tutorial creates a CLI client that sends messages to a relay service, which spawns workers to process each message. It demonstrates:

- **Process spawning** — Create child processes dynamically
- **Message passing** — Communicate between processes with send and receive operations
- **Channels and select** — Wait on multiple event sources
- **Coroutines** — Run concurrent work within a process
- **Process registration** — Find processes by name
- **Monitoring** — Track child-process lifecycles



### Prerequisites


- Wippy runtime `v0.3.32a` available as `wippy`. Confirm it with
  `wippy version --short`.
- An interactive terminal.
- An empty working directory. Create the project and source directory before adding
  the files below:

  ```bash
  mkdir echo-service
  cd echo-service
  mkdir src
  ```



### Architecture


```mermaid
flowchart TB
    subgraph terminal["terminal.host"]
        CLI["CLI Process"]
    end

    subgraph processes["process.host"]
        Relay["Relay Process<br/>(+ stats coroutine)"]
        W1["Worker 1"]
        W2["Worker 2"]
        W3["Worker N"]
    end

    CLI -->|"send('relay', 'echo', msg)"| Relay
    Relay -->|"spawn_monitored(worker)"| W1
    Relay -->|"spawn_monitored(...)"| W2
    Relay -->|"spawn_monitored(...)"| W3
    W1 -->|"send(sender, 'echo_response')"| CLI
    W2 -->|"send(...)"| CLI
    W3 -->|"send(...)"| CLI
```



### Project Structure


```
echo-service/
├── wippy.lock
└── src/
    ├── _index.yaml
    ├── cli.lua
    ├── relay.lua
    └── worker.lua
```



### Entry Definitions


Create `src/_index.yaml`:

```yaml
version: "1.0"
namespace: app

entries:
  - name: policy
    kind: security.policy
    policy:
      actions:
        - process.send
        - process.spawn
        - process.spawn.monitored
        - process.registry.register
      resources: "*"
      effect: allow

  - name: terminal
    kind: terminal.host
    lifecycle:
      auto_start: true

  - name: processes
    kind: process.host
    lifecycle:
      auto_start: true

  - name: cli
    kind: process.lua
    source: file://cli.lua
    method: main
    modules:
      - io
      - time
    security:
      policies: [app:policy]

  - name: relay
    kind: process.lua
    source: file://relay.lua
    method: main
    modules:
      - logger
      - time
    security:
      policies: [app:policy]

  - name: relay-service
    kind: process.service
    process: app:relay
    host: app:processes
    lifecycle:
      auto_start: true

  - name: worker
    kind: process.lua
    source: file://worker.lua
    method: main
    modules:
      - time
    security:
      policies: [app:policy]
```

Security is deny-by-default, so each process carries a `security:` block naming the policy that grants the actions it performs: registering a name, sending messages, and spawning monitored workers.



### The Relay Process


The relay registers itself, handles messages, spawns workers, and runs a stats coroutine.

Create `src/relay.lua`:

```lua
local logger = require("logger")
local time = require("time")

local stats = {
    messages = 0,
    workers_spawned = 0
}

local function stats_reporter()
    while true do
        time.sleep("5s")
        logger:info("stats", {
            messages = stats.messages,
            workers_spawned = stats.workers_spawned
        })
    end
end

local function main()
    local inbox = process.inbox()
    local events = process.events()

    local _, register_err = process.registry.register("relay")
    if register_err then
        error("cannot register relay: " .. tostring(register_err))
    end
    logger:info("relay started", {pid = process.pid()})

    coroutine.spawn(stats_reporter)

    while true do
        local r = channel.select {
            inbox:case_receive(),
            events:case_receive()
        }

        if r.channel == events then
            local event = r.value
            if event.kind == process.event.CANCEL then
                logger:info("relay stopping", stats)
                return
            elseif event.kind == process.event.EXIT then
                logger:info("worker exited", {
                    from = event.from,
                    result = event.result
                })
            end
        else
            local msg = r.value
            if msg:topic() == "echo" then
                local echo = msg:payload():data()
                stats.messages = stats.messages + 1

                local worker_pid, err = process.spawn_monitored(
                    "app:worker",
                    "app:processes",
                    echo.sender,
                    echo.data
                )

                if err then
                    logger:error("spawn failed", {error = tostring(err)})
                else
                    stats.workers_spawned = stats.workers_spawned + 1
                end
            end
        end
    end
end

return { main = main }
```



#### Key Patterns {id="relay-key-patterns"}


**Coroutine Spawning**

```lua
coroutine.spawn(stats_reporter)
```

This starts a coroutine that shares memory with the main function. Coroutines yield at I/O operations such as `time.sleep`.

**Channel Select**

```lua
local r = channel.select {
    inbox:case_receive(),
    events:case_receive()
}
```

Waits on multiple channels. `r.channel` identifies which fired, `r.value` contains the data. The `CANCEL` event arrives on the same events channel when the runtime shuts the service down; returning from `main` there lets the host stop cleanly instead of waiting out its stop timeout.

**Payload Extraction**

```lua
local echo = msg:payload():data()
```

Messages have `msg:topic()` for the topic string and `msg:payload():data()` for the payload.

**Spawn with Monitoring**

```lua
local worker_pid, err = process.spawn_monitored("app:worker", "app:processes", ...)
```

This spawns the worker and starts monitoring it. When the worker exits, the relay receives an `EXIT` event.



### The Worker Process


Workers receive arguments directly and send responses to the sender.

Create `src/worker.lua`:

```lua
local function main(sender_pid, data)
    local response = {
        data = string.upper(data),
        worker = process.pid()
    }

    local _, send_err = process.send(sender_pid, "echo_response", response)
    if send_err then
        error("cannot send echo response: " .. tostring(send_err))
    end

    return 0
end

return { main = main }
```



### The CLI Process


The CLI sends messages to the relay's registered name and waits for each response with a timeout.

Create `src/cli.lua`:

```lua
local io = require("io")
local time = require("time")

local reset = "\027[0m"
local function dim(s) return "\027[2m" .. s .. reset end
local function green(s) return "\027[32m" .. s .. reset end
local function yellow(s) return "\027[33m" .. s .. reset end
local function cyan(s) return "\027[36m" .. s .. reset end

local function main()
    local inbox = process.inbox()

    -- Wait for relay to register its name
    local deadline = time.after("5s")
    while not process.registry.lookup("relay") do
        local tick = time.after("50ms")
        local r = channel.select { deadline:case_receive(), tick:case_receive() }
        if r.channel == deadline then
            io.print("relay not ready")
            return 1
        end
    end

    io.print(cyan("Echo Client"))
    io.print(dim("Type messages to echo. Ctrl+C to exit.\n"))

    while true do
        local _, write_err = io.write(yellow("> "))
        if write_err then
            io.eprint("cannot write prompt:", write_err)
            return 1
        end

        local _, flush_err = io.flush()
        if flush_err then
            io.eprint("cannot flush prompt:", flush_err)
            return 1
        end

        local input, read_err = io.readline()
        if read_err then
            io.eprint("cannot read input:", read_err)
            return 1
        end

        if not input or #input == 0 then
            break
        end

        local msg = {
            sender = process.pid(),
            data = input
        }
        local _, err = process.send("relay", "echo", msg)
        if err then
            io.print(dim("  error: " .. tostring(err)))
        else
            local timeout = time.after("2s")
            local r = channel.select {
                inbox:case_receive(),
                timeout:case_receive()
            }

            if r.channel == timeout then
                io.print(dim("  timeout"))
            else
                local msg = r.value
                if msg:topic() == "echo_response" then
                    local resp = msg:payload():data()
                    io.print(green("  " .. resp.data))
                    io.print(dim("  from worker: " .. resp.worker))
                end
            end
        end
    end

    io.print("\nGoodbye!")
    return 0
end

return { main = main }
```



#### Key Patterns {id="cli-key-patterns"}


**Send by Name**

```lua
process.send("relay", "echo", msg)
```

`process.send` accepts a registered name as its target and returns an error when that name cannot be resolved.

**Timeout Pattern**

```lua
local timeout = time.after("2s")
local r = channel.select {
    inbox:case_receive(),
    timeout:case_receive()
}
if r.channel == timeout then
    -- timed out
end
```



### Running


```bash
wippy init
wippy run -x app:cli
```

Example output:

```
Echo Client
Type messages to echo. Ctrl+C to exit.

> hello world
  HELLO WORLD
  from worker: {c49e0627-fcdf-53ec-a95d-6f84bc3715f3@app:processes|0x00005}
```

The worker PID is generated at runtime and will differ. Enter several lines to
confirm that each response is uppercase. Submit an empty line to exit cleanly.



### Troubleshooting and Cleanup


- `relay not ready` means the auto-started relay did not register within five
  seconds. Check the runtime log for a relay startup, policy, or registry error.
- `not allowed to spawn` or `not allowed to send` means the process entries do not
  have the `app:process-policy` security context shown above.
- `no terminal host found` means the `terminal.host` entry is missing. If your
  project has multiple terminal hosts, add `--host app:terminal` to the run command.
- A timeout after sending means the worker did not return a response. Check the
  relay log for a spawn failure and confirm `app:worker` and `app:processes` match
  the entry names.
- Submit an empty line to exit the CLI. Press Ctrl+C if the runtime remains active;
  after leaving the directory, delete `echo-service/` if it was only a disposable
  exercise.



### Next Steps


- [Process Management](lua/core/process.md) — Process API reference
- [Channels](lua/core/channel.md) — Channel API reference
- [Time and Duration](lua/core/time.md) — Time API reference



---

# "Channels and Concurrency Primer"

## Channels and Concurrency Primer


This page introduces channels for coordinating coroutines within a process. The examples cover buffering, selection, producer-consumer flows, fan-out, fan-in, and channel closure.

**Classification:** Reference/API primer. The snippets are independent examples,
not a standalone application.



### Context and Dependencies


Run these snippets inside an exported function of an executable Lua entry such as
`process.lua`. The `channel` and `coroutine` APIs are ambient globals in that
execution context; they do not need `require()` calls or `modules` declarations.
Each snippet creates its own channels and should be evaluated separately.

This page is a primer: each snippet shows one API in isolation. Paste them into the `main` function of a `process.lua` entry to run them, as set up in the [CLI Applications](tutorials/cli.md) tutorial.



### Creating Channels


Channels pass values between coroutines. Create one with `channel.new(capacity)`:

```lua
local ch = channel.new(1)  -- buffered channel, capacity 1
```



#### Buffered Channels


A send to a buffered channel blocks only when its buffer is full:

```lua
local ch = channel.new(3)  -- buffer holds 3 items

-- Send without blocking
ch:send(1)
ch:send(2)
ch:send(3)

-- Receive in FIFO order
local v1, ok1 = ch:receive()  -- 1, true
local v2, ok2 = ch:receive()  -- 2, true
local v3, ok3 = ch:receive()  -- 3, true
```



#### Unbuffered Channels


Unbuffered channels (capacity 0) synchronize sender and receiver:

```lua
local ch = channel.new(0)  -- unbuffered
local done = channel.new(1)

coroutine.spawn(function()
    ch:send("from spawn")  -- blocks until receiver ready
    done:send(true)
end)

local val = ch:receive()  -- receives "from spawn"
local completed = done:receive()
```



### Channel Select


`channel.select` waits on multiple channel operations and returns the first one that is ready:

```lua
local ch1 = channel.new(1)
local ch2 = channel.new(1)

ch1:send("ch1_value")

local result = channel.select{
    ch1:case_receive(),
    ch2:case_receive()
}

-- result is a table with: channel, value, ok
result.channel == ch1  -- true
result.value           -- "ch1_value"
result.ok              -- true
```



#### Select with Send


Use `case_send` to offer a send inside a select. The case is chosen once the channel can accept the value:

```lua
local ch = channel.new(1)

local result = channel.select{
    ch:case_send("sent"),
    default = true
}

if not result.default then
    result.ok  -- true (send succeeded)
end

local v = ch:receive()  -- "sent"
```

Select blocks until one of its cases is ready. Add `default = true` to the case table to return immediately instead, with `result.default` set to true when nothing was ready:

```lua
local full = channel.new(1)
full:send("first")

local result = channel.select{
    full:case_send("second"),
    default = true
}

result.default  -- true (buffer full, nothing sent)
```



### Producer-Consumer Pattern


Single producer, single consumer:

```lua
local ch = channel.new(5)
local done = channel.new(1)
local consumed = 0

-- Consumer
coroutine.spawn(function()
    while true do
        local v, ok = ch:receive()
        if not ok then break end
        consumed = consumed + 1
    end
    done:send(consumed)
end)

-- Producer
for i = 1, 10 do
    ch:send(i)
end
ch:close()

local total = done:receive()  -- 10
```



#### Ping-Pong Pattern


Synchronize two coroutines:

```lua
local ping = channel.new(0)
local pong = channel.new(0)
local rounds_done = channel.new(1)

coroutine.spawn(function()
    for i = 1, 5 do
        ping:receive()
        pong:send("pong")
    end
    rounds_done:send(true)
end)

for i = 1, 5 do
    ping:send("ping")
    pong:receive()
end

local completed = rounds_done:receive()
```



### Fan-Out Pattern


One producer, multiple consumers:

```lua
local work = channel.new(10)
local results = channel.new(10)

-- Spawn 3 workers
for w = 1, 3 do
    coroutine.spawn(function()
        while true do
            local job, ok = work:receive()
            if not ok then break end
            results:send(job * 2)
        end
    end)
end

-- Send work
for i = 1, 6 do
    work:send(i)
end
work:close()

-- Collect results
local sum = 0
for i = 1, 6 do
    local r = results:receive()
    sum = sum + r
end
-- sum = (1+2+3+4+5+6)*2 = 42
```



### Fan-In Pattern


Multiple producers, single consumer:

```lua
local output = channel.new(10)
local producer_count = 4
local items_per_producer = 5

-- Spawn producers
for p = 1, producer_count do
    local producer_id = p
    coroutine.spawn(function()
        for i = 1, items_per_producer do
            output:send({producer = producer_id, item = i})
        end
    end)
end

-- Collect all messages
local received = {}
for i = 1, producer_count * items_per_producer do
    local msg = output:receive()
    table.insert(received, msg)
end

-- Verify all producers sent their items
local counts = {}
for _, msg in ipairs(received) do
    counts[msg.producer] = (counts[msg.producer] or 0) + 1
end
```



### Closing Channels


Close channels to signal completion. Receivers get `ok = false` when channel is closed and empty:

```lua
local ch = channel.new(5)
local done = channel.new(1)

coroutine.spawn(function()
    local count = 0
    while true do
        local v, ok = ch:receive()
        if not ok then break end  -- channel closed
        count = count + 1
    end
    done:send(count)
end)

for i = 1, 10 do
    ch:send(i)
end
ch:close()  -- signal no more values

local total = done:receive()
```



### Channel Methods


Channel operations:

- `channel.new(capacity)` — Create a channel with the specified buffer size
- `ch:send(value)` — Send a value, blocking if the buffer is full; sending to a closed channel raises an error
- `ch:receive()` — Receive a value and return `value, ok`
- `ch:close()` — Close the channel; closing it again raises an error
- `ch:case_send(value)` — Create a send case for `select`
- `ch:case_receive()` — Create a receive case for `select`
- `channel.select{cases...}` — Wait on multiple operations and return `channel`, `value`, and `ok`
- `channel.select{cases..., default = true}` — Return `{default = true, ok = true}` immediately when no case is ready



### Next Steps


- [Channel Module Reference](lua/core/channel.md) — Channel API documentation
- [Processes](tutorials/processes.md) — Inter-process communication



---

# "Processes and Messaging Primer"

## Processes and Messaging Primer


Learn the process APIs for spawning isolated work, exchanging messages, monitoring lifecycles, linking failures, and registering process names.



### Overview


Processes provide isolated execution units that communicate through message passing. Each process has its own inbox and can subscribe to specific message topics.

**Classification:** Reference/API primer. Each snippet illustrates one operation in
isolation; the page is not a standalone project. For a complete application that
combines spawning, monitoring, and messaging, see the [Echo Service](tutorials/echo-service.md)
tutorial.



### Context and Dependencies


The examples assume they run inside an executable Lua entry and that a running
`process.host` is registered as `app:processes`. Entry IDs such as
`app.test.process:echo_worker` are placeholders for process entries that your
project must define. The `process` and `channel` APIs are ambient globals; direct
`process.*` access is idiomatic, and `require("process")` also resolves without a
module declaration. Snippets that call `time.after()` require
`local time = require("time")` and `time` in the entry's `modules` list.

Spawning, sending, monitoring, linking, cancellation, termination, and registry
mutation are guarded operations. Give the executing entry an actor and policies
for only the operations and resources it needs; otherwise strict mode denies them.

Key concepts:

- Spawn processes with `process.spawn()` and its variants.
- Send topic-based messages to PIDs or registered names.
- Receive messages with `process.listen()` or `process.inbox()`.
- Monitor process lifecycles with events.
- Link processes for coordinated failure handling.



### Permissions


Process operations are permission-checked against the calling entry's security policy. Declare a `security.policy` entry granting the actions used below, and attach it to every entry that spawns, sends, monitors, links, or registers names:

```yaml
  - name: policy
    kind: security.policy
    policy:
      actions:
        - process.spawn
        - process.spawn.monitored
        - process.spawn.linked
        - process.host
        - process.send
        - process.monitor
        - process.unmonitor
        - process.link
        - process.unlink
        - process.registry.register
        - process.registry.unregister
      resources: "*"
      effect: allow

  - name: worker
    kind: process.lua
    source: file://worker.lua
    method: main
    modules:
      - process
    security:
      policies: [app:policy]
```

Without the grant these calls return errors such as `not allowed to spawn process: app.test.process:echo_worker`. The full action list is in the [Permission Reference](lua/core/process.md).



### Spawning Processes


Spawn a new process from an entry reference.

```lua
local pid, err = process.spawn("app.test.process:echo_worker", "app:processes", "hello")
if err then
    return false, "spawn failed: " .. tostring(err)
end

-- pid is a string identifier for the spawned process
print("Started worker:", pid)
```

Parameters:
- Entry reference (e.g., `"app.test.process:echo_worker"`)
- Host reference (e.g., `"app:processes"`)
- Optional arguments passed to worker's main function



#### Getting Your Own PID


```lua
local my_pid = process.pid()
-- Returns string PID of current process
```



### Message Passing


Messages use a topic-based routing system. Send messages to PIDs with a topic, then receive via topic subscription or inbox.



#### Sending Messages


```lua
-- Send to process by PID
local sent, err = process.send(worker_pid, "messages", "hello from parent")
if err then
    return false, "send failed: " .. tostring(err)
end

-- send returns (bool, error)
```



#### Receiving via Topic Subscription


Subscribe to specific topics using `process.listen()`:

```lua
-- Worker that listens for messages on "messages" topic
local function main()
    local ch = process.listen("messages")

    local msg, ok = ch:receive()
    if ok then
        -- msg is the payload directly
        print("Received:", msg)
        return true
    end

    return false
end

return { main = main }
```



#### Receiving via Inbox


Inbox receives messages that don't match any topic listener:

```lua
local function main()
    local inbox_ch = process.inbox()
    local specific_ch = process.listen("specific_topic")

    while true do
        local result = channel.select({
            specific_ch:case_receive(),
            inbox_ch:case_receive()
        })

        if result.channel == specific_ch then
            -- Messages to "specific_topic" arrive here
            local payload = result.value
        elseif result.channel == inbox_ch then
            -- Messages to any OTHER topic arrive here
            local msg = result.value
            print("Inbox got:", msg:topic(), msg:payload():data())
        end
    end
end

return { main = main }
```



#### Message Mode for Sender Info


Use `{ message = true }` to access sender PID and topic:

```lua
-- Worker that echoes messages back to sender
local function main()
    local ch = process.listen("echo", { message = true })

    local msg = ch:receive()
    if msg then
        local sender = msg:from()
        local data = msg:payload():data()

        if sender then
            local _, send_err = process.send(sender, "reply", data)
            if send_err then
                return false, "reply failed: " .. tostring(send_err)
            end
        end
        return true
    end

    return false
end

return { main = main }
```



### Monitoring Processes


Monitor processes to receive EXIT events when they terminate.



#### Spawn with Monitoring


```lua
local events_ch = process.events()

local worker_pid, err = process.spawn_monitored(
    "app.test.process:events_exit_worker",
    "app:processes"
)
if err then
    return false, "spawn failed: " .. tostring(err)
end

-- Wait for EXIT event
local timeout = time.after("3s")
local result = channel.select {
    events_ch:case_receive(),
    timeout:case_receive(),
}

if result.channel == timeout then
    return false, "timeout waiting for EXIT event"
end

local event = result.value
if event.kind == process.event.EXIT then
    print("Worker exited:", event.from)
    if event.result and event.result.error then
        print("Exit error:", event.result.error)
    elseif event.result then
        print("Return value:", event.result.value)
    end
end
```



#### Explicit Monitoring


Monitor an already running process:

```lua
local events_ch = process.events()

-- Spawn without monitoring
local worker_pid, err = process.spawn("app.test.process:long_worker", "app:processes")
if err then
    return false, "spawn failed: " .. tostring(err)
end

-- Add monitoring explicitly
local ok, monitor_err = process.monitor(worker_pid)
if monitor_err then
    return false, "monitor failed: " .. tostring(monitor_err)
end

-- Now will receive EXIT events for this worker
```

Stop monitoring:

```lua
local ok, err = process.unmonitor(worker_pid)
if err then
    return false, "unmonitor failed: " .. tostring(err)
end
```



### Process Linking


Link processes for coordinated lifecycle management. An abnormal exit terminates linked peers by default. A peer with `trap_links=true` remains running and receives a `LINK_DOWN` event instead.



#### Spawn Linked Process


```lua
-- Child terminates if parent crashes (unless trap_links is set)
local pid, err = process.spawn_linked("app.test.process:child_worker", "app:processes")
if err then
    return false, "spawn_linked failed: " .. tostring(err)
end
```



#### Explicit Linking


```lua
-- Link to existing process
local ok, err = process.link(target_pid)
if err then
    return false, "link failed: " .. tostring(err)
end

-- Unlink
local ok, err = process.unlink(target_pid)
if err then
    return false, "unlink failed: " .. tostring(err)
end
```



#### Handling LINK_DOWN Events


By default, an abnormal exit of a linked peer terminates the current process; no
Lua `LINK_DOWN` event is delivered. Enable `trap_links` to remain running and
receive that event instead:

```lua
local function main()
    -- Enable trap_links to receive LINK_DOWN events instead of crashing
    local ok, err = process.set_options({ trap_links = true })
    if not ok then
        return false, "set_options failed: " .. tostring(err)
    end

    -- Verify trap_links is enabled
    local opts = process.get_options()
    if not opts.trap_links then
        return false, "trap_links should be true"
    end

    local events_ch = process.events()

    -- Spawn a linked process that will fail
    local error_pid, err2 = process.spawn_linked(
        "app.test.process:error_exit_worker",
        "app:processes"
    )
    if err2 then
        return false, "spawn error worker failed: " .. tostring(err2)
    end

    -- Wait for LINK_DOWN event
    local timeout = time.after("2s")
    local result = channel.select {
        events_ch:case_receive(),
        timeout:case_receive(),
    }

    if result.channel == timeout then
        return false, "timeout waiting for LINK_DOWN"
    end

    local event = result.value
    if event.kind == process.event.LINK_DOWN then
        print("Linked process died:", event.from)
        -- Handle gracefully instead of crashing
        return true
    end

    return false, "expected LINK_DOWN, got: " .. tostring(event.kind)
end

return { main = main }
```



### Process Registry


Register names for processes to enable name-based lookups and messaging.



#### Registering Names


```lua
local function main()
    local test_name = "my_service_" .. tostring(os.time())

    -- Register current process with a name
    local ok, err = process.registry.register(test_name)
    if err then
        return false, "register failed: " .. tostring(err)
    end

    -- Lookup the registered name
    local pid, lookup_err = process.registry.lookup(test_name)
    if lookup_err then
        return false, "lookup failed: " .. tostring(lookup_err)
    end

    -- Verify it resolves to our PID
    if pid ~= process.pid() then
        return false, "lookup returned wrong pid"
    end

    return true
end

return { main = main }
```



#### Unregistering Names


```lua
-- Unregister explicitly
local unregistered = process.registry.unregister(test_name)
if not unregistered then
    print("Name was not registered")
end

-- Lookup after unregister returns nil + error
local pid, err = process.registry.lookup(test_name)
-- pid will be nil, err will be non-nil
```

Names are automatically released when the process exits.



### Example: Monitored Worker Pool


This partial example illustrates a parent process spawning multiple monitored
workers and tracking their completion. To use it, define the parent and
`app.test.process:task_worker` entries, the `app:processes` host, the required
process policies, and `time` in both entries' module lists.

```lua
-- Parent process
local time = require("time")

local function main()
    local events_ch = process.events()

    -- Track spawned workers
    local workers = {}
    local worker_count = 5

    -- Spawn multiple monitored workers
    for i = 1, worker_count do
        local worker_pid, err = process.spawn_monitored(
            "app.test.process:task_worker",
            "app:processes",
            { task_id = i, value = i * 10 }
        )

        if err then
            return false, "spawn worker " .. i .. " failed: " .. tostring(err)
        end

        workers[worker_pid] = { task_id = i, started = os.time() }
    end

    -- Wait for all workers to complete
    local completed = 0
    local timeout = time.after("10s")

    while completed < worker_count do
        local result = channel.select {
            events_ch:case_receive(),
            timeout:case_receive(),
        }

        if result.channel == timeout then
            return false, "timeout waiting for workers"
        end

        local event = result.value
        if event.kind == process.event.EXIT then
            local worker = workers[event.from]
            if worker then
                if event.result and event.result.error then
                    print("Worker " .. worker.task_id .. " failed:", event.result.error)
                else
                    print("Worker " .. worker.task_id .. " completed:", event.result and event.result.value)
                end
                completed = completed + 1
            end
        end
    end

    return true
end

return { main = main }
```

Worker process:

```lua
-- task_worker.lua
local time = require("time")

local function main(task)
    -- Simulate work
    time.sleep("100ms")

    -- Process task
    local result = task.value * 2

    return result
end

return { main = main }
```



### Next Steps


- [Process Module Reference](lua/core/process.md) — Process API documentation
- [Channels](tutorials/channels.md) — Channel operations for message handling



---

# "Process Supervision Recipes"

## Process Supervision Recipes


Use monitoring and linking to observe process exits, propagate failures, handle cancellation, and restart workers.

**Classification:** Partial recipe. The lifecycle snippets are independent, and the
worker-pool section supplies its core entries but not the separate control process
needed to trigger and verify a restart.



### Context and Dependencies


The snippets target Wippy runtime `v0.3.32a` and assume an executable Lua entry, a
running `process.host` named `app:processes`, and project-defined worker entries such
as `app.workers:task_worker`. The `process` and `channel` APIs are ambient globals.
Any snippet that calls `time.*` requires the `time` module in its entry and
`local time = require("time")` in its source.

Process spawn, host selection, monitoring, linking, sending, cancellation, and
termination are guarded operations. Attach an actor and narrowly scoped allow
policies to each executable entry that uses them. The worker-pool configuration
below includes the policies needed by that recipe; the isolated snippets do not.



### Monitoring vs Linking


**Monitoring** provides one-way observation:

- A parent monitors a child.
- When the child exits, the parent receives an `EXIT` event.
- The parent continues running.

**Linking** creates bidirectional fate-sharing:

- A parent and child are linked.
- If either process exits abnormally, the other also terminates.
- Setting `trap_links=true` changes failures into events that the process can handle.

```mermaid
flowchart TB
    subgraph Monitoring["MONITORING (one-way)"]
        direction TB
        P1[Parent monitors] -->|EXIT event<br/>parent continues| C1[Child exits]
    end

    subgraph Linking["LINKING (bidirectional)"]
        direction TB
        P2[Parent linked] <-->|abnormal exit<br/>fate sharing| C2[Child fails]
    end
```



#### Spawn with Monitoring


Use `process.spawn_monitored()` to spawn and monitor in one call:

```lua
local function main()
    local events_ch = process.events()

    -- Spawn worker and start monitoring
    local worker_pid, err = process.spawn_monitored(
        "app.workers:task_worker",
        "app:processes"
    )
    if err then
        return nil, "spawn failed: " .. tostring(err)
    end

    -- Wait for worker to complete
    local event = events_ch:receive()

    if event.kind == process.event.EXIT then
        print("Worker exited:", event.from)
        if event.result then
            print("Result:", event.result.value)
        end
        if event.result and event.result.error then
            print("Error:", event.result.error)
        end
    end
end
```



#### Monitor Existing Process


Call `process.monitor()` to start monitoring an already-running process:

```lua
local function main()
    local time = require("time")
    local events_ch = process.events()

    -- Spawn without monitoring
    local worker_pid, err = process.spawn(
        "app.workers:long_worker",
        "app:processes"
    )
    if err then
        return nil, "spawn failed: " .. tostring(err)
    end

    -- Start monitoring later
    local ok, monitor_err = process.monitor(worker_pid)
    if monitor_err then
        return nil, "monitor failed: " .. tostring(monitor_err)
    end

    -- Cancel the worker
    time.sleep("5ms")
    local _, cancel_err = process.cancel(worker_pid)
    if cancel_err then
        return nil, "cancel failed: " .. tostring(cancel_err)
    end

    -- Receive EXIT event
    local event = events_ch:receive()
    if event.kind == process.event.EXIT then
        print("Worker terminated:", event.from)
    end
end
```



#### Stop Monitoring


Use `process.unmonitor()` to stop receiving EXIT events:

```lua
local function main()
    local time = require("time")
    local events_ch = process.events()

    -- Spawn and monitor
    local worker_pid, err = process.spawn_monitored(
        "app.workers:long_worker",
        "app:processes"
    )
    if err then
        return nil, "spawn failed: " .. tostring(err)
    end

    time.sleep("5ms")

    -- Stop monitoring
    local ok, unmon_err = process.unmonitor(worker_pid)
    if unmon_err then
        return nil, "unmonitor failed: " .. tostring(unmon_err)
    end

    -- Cancel worker
    local _, cancel_err = process.cancel(worker_pid)
    if cancel_err then
        return nil, "cancel failed: " .. tostring(cancel_err)
    end

    -- No EXIT event will be received (we unmonitored)
    local timeout = time.after("200ms")
    local result = channel.select {
        events_ch:case_receive(),
        timeout:case_receive(),
    }

    if result.channel == events_ch then
        return nil, "should not receive event after unmonitor"
    end
end
```



#### Explicit Linking


Use `process.link()` to create a bidirectional link:

```lua
-- Worker that links to a target process
local function worker_main()
    local time = require("time")
    local events_ch = process.events()
    local inbox_ch = process.inbox()

    -- Enable trap_links to receive LINK_DOWN events
    local _, options_err = process.set_options({ trap_links = true })
    if options_err then
        return nil, "set_options failed: " .. tostring(options_err)
    end

    -- Receive target PID from sender
    local msg = inbox_ch:receive()
    local target_pid = msg:payload():data()
    local sender = msg:from()

    -- Create bidirectional link
    local ok, err = process.link(target_pid)
    if err then
        return nil, "link failed: " .. tostring(err)
    end

    -- Notify sender we're linked
    local _, send_err = process.send(sender, "linked", process.pid())
    if send_err then
        return nil, "confirmation failed: " .. tostring(send_err)
    end

    -- Wait for LINK_DOWN when target exits with an error
    local timeout = time.after("3s")
    local result = channel.select {
        events_ch:case_receive(),
        timeout:case_receive(),
    }

    if result.channel == events_ch then
        local event = result.value
        if event.kind == process.event.LINK_DOWN then
            return "LINK_DOWN_RECEIVED"
        end
    end

    return nil, "no LINK_DOWN received"
end
```



#### Spawn with Link


Use `process.spawn_linked()` to spawn and link in one call:

```lua
local function parent_main()
    -- Enable trap_links to handle child death
    local _, options_err = process.set_options({ trap_links = true })
    if options_err then
        return nil, "set_options failed: " .. tostring(options_err)
    end

    local events_ch = process.events()

    -- Spawn and link to child
    local child_pid, err = process.spawn_linked(
        "app.workers:child_worker",
        "app:processes"
    )
    if err then
        return nil, "spawn_linked failed: " .. tostring(err)
    end

    -- If the child exits with an error, we receive LINK_DOWN
    local event = events_ch:receive()
    if event.kind == process.event.LINK_DOWN then
        print("Child died:", event.from)
    end
end
```

The target or child must exit abnormally for these examples to receive
`LINK_DOWN`; the explicit-link example also requires that failure to occur within
its three-second wait window. Normal completion does not emit this event.



### Trap Links


By default, when a linked process fails, the current process also fails. Set `trap_links=true` to receive LINK_DOWN events instead.



#### Default Behavior (trap_links=false)


Without `trap_links`, linked process failure terminates the current process:

```lua
local function worker_main()
    local events_ch = process.events()

    -- trap_links is false by default
    local opts = process.get_options()
    print("trap_links:", opts.trap_links)  -- false

    -- Spawn linked worker that will fail
    local child_pid, err = process.spawn_linked(
        "app.workers:error_worker",
        "app:processes"
    )
    if err then
        return nil, "spawn_linked failed: " .. tostring(err)
    end

    -- When child errors, THIS process terminates
    -- We never reach this point
    local event = events_ch:receive()
end
```



#### With trap_links=true


Enable `trap_links` to receive LINK_DOWN events and survive:

```lua
local function worker_main()
    -- Enable trap_links
    local _, options_err = process.set_options({ trap_links = true })
    if options_err then
        return nil, "set_options failed: " .. tostring(options_err)
    end

    local events_ch = process.events()

    -- Spawn linked worker that will fail
    local child_pid, err = process.spawn_linked(
        "app.workers:error_worker",
        "app:processes"
    )
    if err then
        return nil, "spawn_linked failed: " .. tostring(err)
    end

    -- Wait for LINK_DOWN event
    local event = events_ch:receive()

    if event.kind == process.event.LINK_DOWN then
        print("Child failed, handling gracefully")
        return "LINK_DOWN_RECEIVED"
    end
end
```



#### Send Cancel Signal


Use `process.cancel()` to request graceful cancellation from a process:

```lua
local function main()
    local time = require("time")
    local events_ch = process.events()

    -- Spawn and monitor worker
    local worker_pid, err = process.spawn_monitored(
        "app.workers:long_worker",
        "app:processes"
    )
    if err then
        return nil, "spawn failed: " .. tostring(err)
    end

    time.sleep("5ms")

    -- Cancel the worker
    local ok, cancel_err = process.cancel(worker_pid)
    if cancel_err then
        return nil, "cancel failed: " .. tostring(cancel_err)
    end

    -- Wait for EXIT event
    local event = events_ch:receive()
    if event.kind == process.event.EXIT then
        print("Worker cancelled:", event.from)
    end
end
```



#### Handle Cancellation


The worker receives the `CANCEL` event through `process.events()`:

`cleanup()` and `handle_message()` below are application callbacks that the recipe
does not define.

```lua
local function worker_main()
    local events_ch = process.events()
    local inbox_ch = process.inbox()

    while true do
        local result = channel.select {
            inbox_ch:case_receive(),
            events_ch:case_receive(),
        }

        if result.channel == events_ch then
            local event = result.value
            if event.kind == process.event.CANCEL then
                -- Cleanup resources
                cleanup()
                return "cancelled gracefully"
            end
        else
            -- Process inbox message
            handle_message(result.value)
        end
    end
end
```



#### Star Topology


A parent can coordinate multiple children that link back to it:

```lua
-- Parent worker spawns children that link TO parent
local function star_parent_main()
    local time = require("time")
    local events_ch = process.events()
    local child_count = 10

    -- Enable trap_links to see children die
    local _, options_err = process.set_options({ trap_links = true })
    if options_err then
        error("set_options failed: " .. tostring(options_err))
    end

    local children = {}

    -- Spawn children
    for i = 1, child_count do
        local child_pid, err = process.spawn(
            "app.workers:linker_child",
            "app:processes"
        )
        if err then
            error("spawn child failed: " .. tostring(err))
        end

        -- Send parent PID to child
        local _, send_err = process.send(child_pid, "inbox", process.pid())
        if send_err then
            error("send parent PID failed: " .. tostring(send_err))
        end
        children[child_pid] = true
    end

    -- Wait for all children to confirm link
    for i = 1, child_count do
        local msg = process.inbox():receive()
        if msg:topic() ~= "linked" then
            error("expected linked confirmation")
        end
    end

    -- Trigger failure - all children should receive LINK_DOWN
    error("PARENT_STAR_FAILURE")
end
```

Child worker that links to parent:

```lua
local function linker_child_main()
    -- Enable trap_links to receive LINK_DOWN events
    local _, options_err = process.set_options({ trap_links = true })
    if options_err then
        return nil, "set_options failed: " .. tostring(options_err)
    end

    local events_ch = process.events()
    local inbox_ch = process.inbox()

    -- Receive parent PID
    local msg = inbox_ch:receive()
    local parent_pid = msg:payload():data()

    -- Link to parent
    local _, link_err = process.link(parent_pid)
    if link_err then
        return nil, "link failed: " .. tostring(link_err)
    end

    -- Confirm link
    local _, send_err = process.send(parent_pid, "linked", process.pid())
    if send_err then
        return nil, "confirmation failed: " .. tostring(send_err)
    end

    -- Wait for LINK_DOWN when parent dies
    local event = events_ch:receive()
    if event.kind == process.event.LINK_DOWN then
        return "parent_died"
    end
end
```



#### Chain Topology


In a linear chain, each node links to its parent:

```lua
-- Chain root: A -> B -> C -> D -> E
local function chain_root_main()
    local time = require("time")

    -- Spawn first child
    local child_pid, err = process.spawn_linked(
        "app.workers:chain_node",
        "app:processes",
        4  -- depth remaining
    )
    if err then
        error("spawn failed: " .. tostring(err))
    end

    -- Wait for chain to build
    time.sleep("100ms")

    -- Trigger cascade - all linked processes die
    error("CHAIN_ROOT_FAILURE")
end
```

Chain node spawns next node and links:

```lua
local function chain_node_main(depth)
    if depth > 0 then
        -- Spawn next in chain
        local child_pid, err = process.spawn_linked(
            "app.workers:chain_node",
            "app:processes",
            depth - 1
        )
        if err then
            error("spawn failed: " .. tostring(err))
        end
    end

    -- Block until parent death kills us via LINK_DOWN (default trap_links=false)
    process.inbox():receive()
end
```



#### Configuration


```yaml


## src/_index.yaml

version: "1.0"
namespace: app

entries:
  - name: supervision-policy
    kind: security.policy
    policy:
      actions:
        - process.host
        - process.send
        - process.spawn
        - process.spawn.linked
      resources: "*"
      effect: allow

  - name: processes
    kind: process.host
    host:
      workers: 16
    lifecycle:
      auto_start: true
```

```yaml


## src/supervisor/_index.yaml

version: "1.0"
namespace: app.supervisor

entries:
  - name: pool
    kind: process.lua
    source: file://pool.lua
    method: main
    modules:
      - time

  - name: pool-service
    kind: process.service
    process: app.supervisor:pool
    host: app:processes
    lifecycle:
      auto_start: true
      security:
        actor:
          id: "service:supervisor"
        groups:
          - app.security:supervisors
```

Strict mode is on by default, so a service that declares no security context is denied every check, including `process.spawn`. Grant the pool the actions it and its workers use:

```yaml


## src/security/_index.yaml

version: "1.0"
namespace: app.security

entries:
  - name: supervisor_policy
    kind: security.policy
    policy:
      actions:
        - process.spawn
        - process.spawn.linked
        - process.host
        - process.registry.register
        - process.terminate
      resources: "*"
      effect: allow
    groups:
      - supervisors
```

Workers inherit the actor and scope of the pool that spawns them, so they need no block of their own.



#### Supervisor Implementation


```lua
-- src/supervisor/pool.lua
local function main(worker_count)
    local time = require("time")
    worker_count = worker_count or 4

    -- Enable trap_links to handle worker deaths
    local _, options_err = process.set_options({ trap_links = true })
    if options_err then
        error("set_options failed: " .. tostring(options_err))
    end

    local events_ch = process.events()
    local workers = {}

    local function start_worker(id)
        local pid, err = process.spawn_linked(
            "app.workers:task_worker",
            "app:processes",
            id
        )
        if err then
            print("Failed to start worker " .. id .. ": " .. tostring(err))
            return nil
        end

        workers[pid] = {id = id, started_at = os.time()}
        print("Worker " .. id .. " started: " .. pid)
        return pid
    end

    -- Start initial pool
    for i = 1, worker_count do
        start_worker(i)
    end

    print("Supervisor started with " .. worker_count .. " workers")

    -- Supervision loop
    while true do
        local timeout = time.after("60s")
        local result = channel.select {
            events_ch:case_receive(),
            timeout:case_receive(),
        }

        if result.channel == timeout then
            -- Periodic health check
            local count = 0
            for _ in pairs(workers) do count = count + 1 end
            print("Health check: " .. count .. " active workers")

        elseif result.channel == events_ch then
            local event = result.value

            if event.kind == process.event.CANCEL then
                return "supervisor stopped"
            end

            if event.kind == process.event.LINK_DOWN then
                local dead_worker = workers[event.from]
                if dead_worker then
                    workers[event.from] = nil
                    local uptime = os.time() - dead_worker.started_at
                    print("Worker " .. dead_worker.id .. " died after " .. uptime .. "s, restarting")

                    -- Brief delay before restart
                    time.sleep("100ms")
                    start_worker(dead_worker.id)
                end
            end
        end
    end
end

return { main = main }
```



#### Worker Definition


```yaml


## src/workers/_index.yaml

version: "1.0"
namespace: app.workers

entries:
  - name: task_worker
    kind: process.lua
    source: file://task_worker.lua
    method: main
    modules:
      - time
    security:
      actor:
        id: app.workers:task_worker
      policies:
        - app:supervision-policy
```



#### Worker Implementation


```lua
-- src/workers/task_worker.lua
local function main(worker_id)
    local time = require("time")
    local events_ch = process.events()
    local inbox_ch = process.inbox()

    -- Register under a name so other processes can reach this worker
    process.registry.register("worker-" .. worker_id)

    print("Task worker " .. worker_id .. " started")

    while true do
        local timeout = time.after("5s")
        local result = channel.select {
            inbox_ch:case_receive(),
            events_ch:case_receive(),
            timeout:case_receive(),
        }

        if result.channel == events_ch then
            local event = result.value
            if event.kind == process.event.CANCEL then
                print("Worker " .. worker_id .. " cancelled")
                return "cancelled"
            elseif event.kind == process.event.LINK_DOWN then
                print("Worker " .. worker_id .. " linked process died")
                return nil, "linked_process_died"
            end

        elseif result.channel == inbox_ch then
            local msg = result.value
            local topic = msg:topic()
            local payload = msg:payload():data()

            if topic == "work" then
                print("Worker " .. worker_id .. " processing: " .. payload)
                time.sleep("100ms")
                local _, send_err = process.send(msg:from(), "result", "completed: " .. payload)
                if send_err then
                    return nil, "send result failed: " .. tostring(send_err)
                end
            end

        elseif result.channel == timeout then
            -- Idle timeout
            print("Worker " .. worker_id .. " idle")
        end
    end
end

return { main = main }
```



### Process Host Settings


The `app:processes` entry defined in [Configuration](#configuration) uses the
following host setting:

```yaml


## Within the app:processes entry in src/_index.yaml

host:
  workers: 16  # Worker goroutines (default: NumCPU)
```

The `workers` setting:

- Controls parallelism for CPU-bound work.
- Is typically set to the number of CPU cores.
- Applies to the scheduler pool shared by all processes on the host.



### Event Types


| Event | Triggered By | Required Setup |
|-------|--------------|----------------|
| `EXIT` | Monitored process exits | `spawn_monitored()` or `monitor()` |
| `LINK_DOWN` | Linked process fails | `spawn_linked()` or `link()` with `trap_links=true` |
| `CANCEL` | `process.cancel()` called | The target consumes `process.events()` |



### Using the Supervisor Pool Recipe


The displayed pool starts and supervises workers, but it is not a complete runnable
tutorial: it intentionally omits a control process, that process's termination
policy, and a deterministic assertion of the restart. After incorporating the recipe
into an application, initialize and run that application normally:

```bash
wippy init
wippy run
```

The supervisor autostarts, spawns four workers, and logs `Worker N started` for each. `LINK_DOWN` is only delivered when a linked process exits with an error, so trigger a restart by forcefully terminating a worker. The terminating code has to run inside the same runtime, so add it as an ad-hoc service:

```yaml


## src/chaos/_index.yaml

version: "1.0"
namespace: app.chaos

entries:
  - name: killer
    kind: process.lua
    source: file://killer.lua
    method: main
    modules:
      - time

  - name: killer-service
    kind: process.service
    process: app.chaos:killer
    host: app:processes
    lifecycle:
      auto_start: true
      security:
        actor:
          id: "service:chaos"
        groups:
          - app.security:supervisors
```

```lua
-- src/chaos/killer.lua
local function main()
    local time = require("time")

    time.sleep("2s")
    process.terminate("worker-1")

    return "terminated"
end

return { main = main }
```

Run `wippy init` again to pick up the new entries, then `wippy run`. Two seconds in, the pool receives `LINK_DOWN`, waits 100 ms, and respawns the worker under the same id:

```
INFO  Worker 1 died after 2s, restarting
INFO  Worker 1 started: {...@app:processes|0x00009}
INFO  Task worker 1 started
```

A graceful `process.cancel()` lets the worker exit cleanly, which does not raise `LINK_DOWN` and therefore does not trigger a restart — that is why the supervision loop returns on `CANCEL` rather than treating shutdown as a worker failure.



### Next Steps


- [Processes](tutorials/processes.md) — Process fundamentals
- [Channels](tutorials/channels.md) — Message-passing patterns
- [Process Module](lua/core/process.md) — Process API reference



---

# "Task Queue"

## Task Queue


Build a REST API that publishes tasks to an in-memory queue, processes them in background workers, and stores completed results in SQLite.

**Classification:** Runnable tutorial. The page provides the complete registry, Lua
sources, startup commands, and HTTP checks for a local single-node demo.



### Overview


This tutorial creates a task management API demonstrating:

- **REST endpoints** — Submit tasks and list results
- **Queue publishing** — Dispatch jobs asynchronously
- **Queue consumers** — Process jobs in background workers
- **Database persistence** — Store completed results in SQLite
- **Schema setup** — Create the database table in a one-shot process

```mermaid
flowchart LR
    subgraph api["HTTP Server"]
        POST["/tasks POST"]
        GET["/tasks GET"]
    end

    subgraph queue["Queue"]
        Q[("tasks queue")]
    end

    subgraph workers["Workers"]
        W1["Consumer 1"]
        W2["Consumer 2"]
    end

    subgraph storage["Storage"]
        DB[(SQLite)]
    end

    POST -->|publish| Q
    Q --> W1
    Q --> W2
    W1 -->|INSERT| DB
    W2 -->|INSERT| DB
    GET -->|SELECT| DB
```



### Prerequisites


- Wippy runtime `v0.3.32a`.
- `curl` or another HTTP client.
- An empty working directory. Create the project and source directory before adding
  the files below:

  ```bash
  mkdir task-queue
  cd task-queue
  mkdir src
  ```



### Project Structure


```
task-queue/
├── wippy.lock
├── data/                    # created before startup
└── src/
    ├── _index.yaml
    ├── migrate.lua
    ├── create_task.lua
    ├── list_tasks.lua
    └── process_task.lua
```



### Entry Definitions


Create `src/_index.yaml`:

```yaml
version: "1.0"
namespace: app

entries:
  # Capabilities used by the tutorial's Lua entries in strict mode
  - name: runtime_policy
    kind: security.policy
    policy:
      actions:
        - db.get
        - queue.publish
        - queue.publish.queue
      resources: "*"
      effect: allow

  # SQLite database
  - name: db
    kind: db.sql.sqlite
    file: "./data/tasks.db"
    lifecycle:
      auto_start: true

  # Access policy for handlers, workers, and the migration
  - name: task_policy
    kind: security.policy
    policy:
      actions:
        - db.get
        - queue.publish
        - queue.publish.queue
      resources: "*"
      effect: allow

  # Memory queue driver
  - name: queue_driver
    kind: queue.driver.memory
    lifecycle:
      auto_start: true

  # Tasks queue
  - name: tasks_queue
    kind: queue.queue
    driver: app:queue_driver

  # HTTP server
  - name: gateway
    kind: http.service
    addr: ":8080"
    lifecycle:
      auto_start: true

  # Router
  - name: router
    kind: http.router
    meta:
      server: app:gateway

  # Migration process (runs once, exits)
  - name: migrate
    kind: process.lua
    source: file://migrate.lua
    method: main
    modules:
      - sql
      - logger
    security:
      actor:
        id: "service:migrate"
      policies:
        - app:task_policy

  # Migration service (auto-starts, exits on success)
  - name: migrate-service
    kind: process.service
    process: app:migrate
    host: app:processes
    lifecycle:
      auto_start: true

  # Process host
  - name: processes
    kind: process.host
    lifecycle:
      auto_start: true

  # API handlers
  - name: create_task
    kind: function.lua
    source: file://create_task.lua
    method: handler
    modules:
      - http
      - queue
      - uuid
    security:
      actor:
        id: "service:api"
      policies:
        - app:task_policy

  - name: list_tasks
    kind: function.lua
    source: file://list_tasks.lua
    method: handler
    modules:
      - http
      - sql
    security:
      actor:
        id: "service:api"
      policies:
        - app:task_policy

  # Queue worker
  - name: process_task
    kind: function.lua
    source: file://process_task.lua
    method: main
    modules:
      - sql
      - logger
      - json
    security:
      actor:
        id: "service:worker"
      policies:
        - app:task_policy

  # Endpoints
  - name: create_task.endpoint
    kind: http.endpoint
    meta:
      router: app:router
    method: POST
    path: /tasks
    func: app:create_task

  - name: list_tasks.endpoint
    kind: http.endpoint
    meta:
      router: app:router
    method: GET
    path: /tasks
    func: app:list_tasks

  # Queue consumer
  - name: task_consumer
    kind: queue.consumer
    queue: app:tasks_queue
    func: app:process_task
    concurrency: 2
    prefetch: 5
    lifecycle:
      auto_start: true
```

<tip>
Strict mode is on by default, so an entry that reaches the database or the queue needs an actor and a scope. The `security:` block on each Lua entry supplies both from `app:task_policy`. See [Security Model](system/security.md).
</tip>



### Migration Process


Create `src/migrate.lua`:

```lua
local sql = require("sql")
local logger = require("logger")

local function main()
    local db, err = sql.get("app:db")
    if err then
        logger:error("failed to connect", {error = tostring(err)})
        error("failed to connect: " .. tostring(err))
    end

    local _, exec_err = db:execute([[
        CREATE TABLE IF NOT EXISTS tasks (
            id TEXT PRIMARY KEY,
            payload TEXT NOT NULL,
            status TEXT NOT NULL DEFAULT 'pending',
            result TEXT,
            created_at INTEGER NOT NULL,
            processed_at INTEGER
        )
    ]])

    db:release()

    if exec_err then
        logger:error("migration failed", {error = tostring(exec_err)})
        error("migration failed: " .. tostring(exec_err))
    end

    logger:info("migration complete")
    return 0
end

return { main = main }
```

<tip>
A normal return ends a `process.service` child without a restart; the supervisor
retries only when the process raises an error. Returning `0` also maps to a successful
exit status when the same process is launched as a CLI command.
</tip>



### Create Task Endpoint


Create `src/create_task.lua`:

```lua
local http = require("http")
local queue = require("queue")
local uuid = require("uuid")

local function handler()
    local req = http.request()
    local res = http.response()

    local body, parse_err = req:body_json()
    if parse_err then
        res:set_status(http.STATUS.BAD_REQUEST)
        res:write_json({error = "invalid JSON"})
        return
    end

    if not body.action then
        res:set_status(http.STATUS.BAD_REQUEST)
        res:write_json({error = "action required"})
        return
    end

    local task_id = uuid.v4()
    local task = {
        id = task_id,
        action = body.action,
        data = body.data or {},
        created_at = os.time()
    }

    local ok, err = queue.publish("app:tasks_queue", task)
    if err then
        res:set_status(http.STATUS.INTERNAL_ERROR)
        res:write_json({error = "failed to queue task"})
        return
    end

    res:set_status(http.STATUS.ACCEPTED)
    res:write_json({
        id = task_id,
        status = "queued"
    })
end

return { handler = handler }
```



### List Tasks Endpoint


Create `src/list_tasks.lua`:

```lua
local http = require("http")
local sql = require("sql")

local function handler()
    local req = http.request()
    local res = http.response()

    local db, db_err = sql.get("app:db")
    if db_err then
        res:set_status(http.STATUS.INTERNAL_ERROR)
        res:write_json({error = "database unavailable"})
        return
    end

    local status_filter = req:query("status")

    local query = sql.builder.select("id", "payload", "status", "result", "created_at", "processed_at")
        :from("tasks")
        :order_by("created_at DESC")
        :limit(100)

    if status_filter then
        query = query:where({status = status_filter})
    end

    local rows, query_err = query:run_with(db):query()
    db:release()

    if query_err then
        res:set_status(http.STATUS.INTERNAL_ERROR)
        res:write_json({error = "query failed"})
        return
    end

    res:set_status(http.STATUS.OK)
    res:write_json({
        tasks = rows,
        count = #rows
    })
end

return { handler = handler }
```



### Queue Worker


Create `src/process_task.lua`:

```lua
local sql = require("sql")
local logger = require("logger")
local json = require("json")

local function main(task)
    logger:info("processing task", {
        id = task.id,
        action = task.action
    })

    local result
    if task.action == "uppercase" then
        result = {output = string.upper(task.data.text or "")}
    elseif task.action == "sum" then
        local nums = task.data.numbers or {}
        local total = 0
        for _, n in ipairs(nums) do
            total = total + n
        end
        result = {output = total}
    else
        result = {output = "processed"}
    end

    local db, db_err = sql.get("app:db")
    if db_err then
        error("database unavailable: " .. tostring(db_err))
    end

    local _, exec_err = db:execute(
        "INSERT OR REPLACE INTO tasks (id, payload, status, result, created_at, processed_at) VALUES (?, ?, ?, ?, ?, ?)",
        { task.id, json.encode(task), "completed", json.encode(result), task.created_at, os.time() }
    )
    db:release()

    if exec_err then
        error("failed to store result: " .. tostring(exec_err))
    end

    logger:info("task completed", {id = task.id})
end

return { main = main }
```

<note>
The consumer auto-acks when the handler returns normally and auto-nacks when it raises an error. Call `msg:ack()` or `msg:nack()` via `queue.message()` only when you need explicit control before the handler ends.
</note>



### Running the Service


Create the data directory, initialize the project, and start the runtime:

```bash
mkdir data
wippy init
wippy run
```

Leave the runtime running while you use a second terminal for the HTTP checks. Wait
until the logs report that the HTTP service is listening and the migration completed;
the one-shot migration and the HTTP service start independently during boot.

Submit a task and query its result:

```bash


## Create a task

curl -X POST http://localhost:8080/tasks \
  -H "Content-Type: application/json" \
  -d '{"action": "uppercase", "data": {"text": "hello world"}}'



## Wait a moment for processing, then list tasks

curl http://localhost:8080/tasks



## Filter by status

curl "http://localhost:8080/tasks?status=completed"
```

The returned row should have `status: "completed"`; its `result` field is a JSON
string containing `{"output":"HELLO WORLD"}`. The in-memory queue is intentionally
non-durable, but completed rows survive restarts in `data/tasks.db`.



### Troubleshooting and Cleanup


- `no such table: tasks` means the request reached SQLite before the migration
  finished. Wait for `migration complete` and retry. A migration error stops the
  migration service and is shown in the runtime logs.
- `failed to queue task` usually means `app:queue_driver` or
  `app:task_consumer` did not start. Check the startup logs for the first resource
  error rather than retrying the request.
- `address already in use` means another process owns port 8080. Stop it or change
  `app:gateway.addr` and use the same port in the `curl` commands.
- Stop the runtime with Ctrl+C. Remove `data/tasks.db` to reset the tutorial data;
  the next start recreates the schema.



### Message Flow


1. **POST /tasks** receives the request, generates a UUID, and publishes the task.
2. A **queue consumer** receives the message; up to two handlers run concurrently.
3. The **worker** processes the task and writes its result to SQLite.
4. **GET /tasks** reads completed tasks from the database.



### Next Steps


- [HTTP Module](lua/http/http.md) — Request and response handling
- [Queue Module](lua/storage/queue.md) — Message queue operations
- [SQL Module](lua/storage/sql.md) — Database access
- [Queue Consumers](guides/queue-consumers.md) — Queue configuration



---

# "Testing"

## Testing


Write and run tests for your Lua code with the `wippy/test` framework — a BDD-style
runner with assertions, lifecycle hooks, and mocking, executed by the `wippy test`
command.



### What You'll Build


A small library and a test suite that covers it:

1. A `calc` library with `add` and `div` functions.
2. A test entry that describes cases, asserts behavior, and skips a pending case.
3. A green test run via `wippy test`.



### Prerequisites


- A Wippy project (clone [app-template](https://github.com/wippyai/app-template), or
  `wippy init` in an empty directory).
- The test framework installed:

  ```bash
  wippy add wippy/test
  wippy install
  ```

  The runner renders a live terminal UI on `wippy/terminal`, which `wippy/test`
  pulls in for you.



### The Code Under Test


```lua
-- src/calc.lua
local function add(a, b)
    return a + b
end

local function div(a, b)
    if b == 0 then
        return nil, "division by zero"
    end
    return a / b
end

return { add = add, div = div }
```



### The Test


A test is an ordinary `function.lua` entry tagged with `meta.type: test`. Its method
returns the value produced by `test.run_cases(...)`, which the runner invokes:

```lua
-- src/calc_test.lua
local test = require("test")
local calc = require("calc")

local function define_tests()
    test.describe("calculator", function()
        local started = false

        test.before_all(function()
            started = true
        end)

        test.it("setup ran", function()
            test.is_true(started)
        end)

        test.it("adds numbers", function()
            test.eq(calc.add(2, 3), 5)
        end)

        test.it("returns error on divide by zero", function()
            local result, err = calc.div(1, 0)
            test.has_error(result, err)
            test.contains(err, "division by zero")
        end)

        test.it_skip("not implemented yet", function()
            test.fail("should not run")
        end)
    end)
end

return { run = test.run_cases(define_tests) }
```

Register both entries. Discovery keys off `meta.type: test`; `meta.suite` groups the
results in the output:

```yaml


## src/_index.yaml

version: "1.0"
namespace: app

entries:
  - name: test_framework
    kind: ns.dependency
    component: wippy/test
    version: "*"

  - name: calc
    kind: library.lua
    source: file://calc.lua

  - name: calc_test
    kind: function.lua
    meta:
      name: Calculator Test
      type: test
      suite: calculator
    source: file://calc_test.lua
    method: run
    imports:
      test: wippy.test:test
      calc: app:calc
```

The `ns.dependency` entry is what mounts `wippy/test` into the application; without
it the framework namespace never reaches the registry and `wippy.test:test` fails to
resolve. The `imports` map controls what `require(...)` resolves to inside the test:
`test` binds the framework, `calc` binds the unit under test.



### Run It


```bash
wippy test
```

Output for the suite above:

```
  Running Tests

  1 tests in 1 suites

    o setup ran <1ms
    o adds numbers <1ms
    o returns error on divide by zero <1ms
    - not implemented yet (skipped)
  o calculator (4) 3/4 1 skipped 21ms

  PASSED  ██████████████████░░░░░░░

  3 tests  1 skipped  26ms
```

`wippy test` exits `0` when every case passes and `1` on any failure, so it drops
straight into CI.



### Assertions


Each assertion raises on failure; the type guards also return the validated value.

| Assertion | Checks |
|---|---|
| `test.eq(a, b)` / `test.neq(a, b)` | Equality / inequality |
| `test.ok(v)` / `test.fail(msg)` | Truthy / force a failure |
| `test.is_nil(v)` / `test.not_nil(v)` | Nil / non-nil |
| `test.is_true(v)` / `test.is_false(v)` | Boolean value |
| `test.is_string/number/table/function/boolean(v)` | Type guards (return `v`) |
| `test.contains(str, sub)` / `test.matches(str, pattern)` | Substring / Lua pattern |
| `test.has_key(tbl, key)` / `test.len(v, n)` | Map key / length |
| `test.gt/gte/lt/lte(a, b)` | Numeric comparison |
| `test.throws(fn)` / `test.has_error(val, err)` / `test.no_error(val, err)` | Error handling |

All take an optional trailing message argument.



### Lifecycle and Mocking


Call these inside a `describe` block:

- `test.before_all` / `test.after_all` — run once per block.
- `test.before_each` / `test.after_each` — run around every case.
- `test.mock("module.field", fn)` — replace a function for the current case;
  mocks restore automatically after each case. Use `test.restore_all_mocks()` to
  clear them early.

Nested `describe` blocks inherit parent hooks (outer `before_*` first, inner
`after_*` first).



### Next Steps


- [Hello World](tutorials/hello-world.md) — the minimal project layout
- [Entry Kinds](guides/entry-kinds.md) — `function.lua`, `library.lua`, and friends
- [Test Framework](framework/testing.md) — full reference for the runner and event protocol



---

# "Crypto Ticker"

## Crypto Ticker


Build a streaming ticker demo with API-key authentication and WebSocket delivery. The example covers token-based security, middleware configuration, and process-based connection handling.

**Classification:** Runnable local tutorial. It includes the registry, Lua sources,
browser client, ordered startup commands, and browser verification. Its permissive
policies and in-memory token store are deliberately limited to a loopback demo.



### Overview


- **API-key exchange** — Submit an API key and receive an HMAC-signed bearer token
- **Token middleware** — Validate a bearer token and restore its security context; the endpoint rejects requests without an actor
- **WebSocket fan-out** — Broadcast from one ticker process to multiple connection handlers
- **Static assets** — Serve the browser client with `http.static`
- **Storage** — Keep API keys in SQLite and token data in memory



### Prerequisites


- Wippy runtime `v0.3.32a`.
- A browser with WebSocket support.
- An empty working directory. Create the project directories before adding the
  files below:

  ```bash
  mkdir auth-ticker
  cd auth-ticker
  mkdir -p src/public data
  ```

  In PowerShell:

  ```powershell
  New-Item -ItemType Directory -Path auth-ticker\src\public -Force
  New-Item -ItemType Directory -Path auth-ticker\data -Force
  Set-Location auth-ticker
  ```



### Project Structure


```
auth-ticker/
├── data/
├── wippy.lock
└── src/
    ├── _index.yaml
    ├── auth_token.lua
    ├── ws_ticker.lua
    ├── ws_handler.lua
    ├── ticker.lua
    ├── migrate.lua
    └── public/
        └── index.html
```



### Architecture


```mermaid
flowchart TB
    subgraph Clients
        Browser[Browser Client]
        API[API Client]
    end

    subgraph "HTTP Layer"
        Server[http.service<br/>gateway :8081]
        Static[http.static<br/>public/]

        subgraph "Public Router"
            CORS1[cors middleware]
            AuthEndpoint[auth_token<br/>POST /auth/token]
        end

        subgraph "WS Router /ws"
            CORS2[cors middleware]
            TokenAuth[token_auth middleware]
            WSEndpoint[ws_ticker<br/>GET /ws/ticker]
            WSRelay[websocket_relay]
        end
    end

    subgraph "Security Layer"
        TokenStore[security.token_store<br/>tokens]
        Policy[security.policy<br/>user_policy]
        SysPolicy[security.policy<br/>system_policy]
        MemStore[store.memory<br/>token_data]
    end

    subgraph "Storage"
        DB[db.sql.sqlite<br/>auth.db]
    end

    subgraph "Process Layer"
        Supervisor[process.host<br/>processes]
        WSHandler[ws_handler<br/>per-connection]
        Ticker[ticker<br/>singleton]
    end

    %% Client connections
    Browser -->|"GET /"| Static
    API -->|"POST /auth/token"| CORS1
    Browser -->|"WS /ws/ticker"| CORS2

    %% API flow
    CORS1 --> AuthEndpoint
    AuthEndpoint -->|validate| TokenStore
    AuthEndpoint -->|"issue token"| API

    %% WS flow
    CORS2 --> TokenAuth
    TokenAuth -->|validate| TokenStore
    TokenAuth --> WSEndpoint
    WSEndpoint -->|spawn| Supervisor
    Supervisor --> WSHandler
    WSEndpoint --> WSRelay
    WSRelay <-->|"messages"| WSHandler

    %% Token store deps
    MemStore --> TokenStore
    Policy -->|attached to token| TokenStore
    SysPolicy -->|"actor + scope"| AuthEndpoint
    SysPolicy -->|"actor + scope"| Ticker

    %% Auth uses DB for API keys
    AuthEndpoint -->|lookup API key| DB

    %% Process communication
    WSHandler -->|subscribe| Ticker
    Ticker -->|broadcast| WSHandler
    WSRelay <-->|"ws frames"| Browser
```



### Security Flow


1. **API-key exchange:** The client posts an API key to `/auth/token`. The handler validates it against the database, creates an actor with `user_policy`, and issues an HMAC-signed token.

2. **Token authentication:** WebSocket connections pass through `token_auth`, which validates the bearer token and restores its actor and policies.

3. **Process spawning:** The WebSocket endpoint spawns a handler process. The token's `user_policy` authorizes the spawn.

4. **Message routing:** The `websocket_relay` middleware routes WebSocket frames to the handler process as messages.



### Configuration


Create `src/_index.yaml`:

```yaml
version: "1.0"
namespace: app

entries:
  # Database for API keys
  - name: db
    kind: db.sql.sqlite
    file: "./data/auth.db"
    lifecycle:
      auto_start: true

  # Token backing store
  - name: token_data
    kind: store.memory
    lifecycle:
      auto_start: true

  # Token store with HMAC signing
  - name: tokens
    kind: security.token_store
    store: app:token_data
    token_length: 32
    default_expiration: "1h"
    token_key: "local-demo-signing-key-do-not-deploy"

  # Security policy for authenticated users
  - name: user_policy
    kind: security.policy
    policy:
      actions: "*"
      resources: "*"
      effect: allow
    groups:
      - user

  # Policy for internal code that runs without an end-user actor
  - name: system_policy
    kind: security.policy
    policy:
      actions:
        - db.get
        - security.actor.create
        - security.policy.get
        - security.scope.create
        - security.token_store.get
        - security.token.create
        - process.registry.register
        - process.send
        - process.monitor
      resources: "*"
      effect: allow

  # Process host
  - name: processes
    kind: process.host
    lifecycle:
      auto_start: true

  # Terminal host used by `wippy run -x app:migrate`
  - name: terminal
    kind: terminal.host
    lifecycle:
      auto_start: true

  # Database migration
  - name: migrate
    kind: process.lua
    source: file://migrate.lua
    method: main
    modules: [sql, logger, crypto]
    security:
      actor:
        id: "service:migrate"
      policies:
        - app:system_policy

  - name: migrate-service
    kind: process.service
    process: app:migrate
    host: app:processes
    lifecycle:
      auto_start: true

  # Ticker broadcaster
  - name: ticker
    kind: process.lua
    source: file://ticker.lua
    method: main
    modules: [logger, time, crypto]
    security:
      actor:
        id: "service:ticker"
      policies:
        - app:system_policy

  - name: ticker-service
    kind: process.service
    process: app:ticker
    host: app:processes
    lifecycle:
      auto_start: true

  # WebSocket handler (spawned per connection)
  - name: ws_handler
    kind: process.lua
    source: file://ws_handler.lua
    method: main
    modules: [logger, json]

  # HTTP server
  - name: gateway
    kind: http.service
    addr: "127.0.0.1:8081"
    lifecycle:
      auto_start: true
      requires:
        - app:ticker-service

  # Public router (no auth)
  - name: public_router
    kind: http.router
    meta:
      server: app:gateway
    middleware:
      - cors
    options:
      cors.allow.origins: "http://127.0.0.1:8081"

  # WebSocket router (with auth)
  - name: ws_router
    kind: http.router
    meta:
      server: app:gateway
    prefix: /ws
    middleware:
      - cors
      - token_auth
    options:
      cors.allow.origins: "http://127.0.0.1:8081"
      token_auth.store: "app:tokens"
    post_middleware:
      - websocket_relay
    post_options:
      wsrelay.allowed.origins: "http://127.0.0.1:8081"

  # Static files
  - name: public_fs
    kind: fs.directory
    directory: ./src/public

  - name: static
    kind: http.static
    meta:
      server: app:gateway
    path: /
    fs: app:public_fs
    static_options:
      spa: true
      index: index.html

  # Auth token exchange
  - name: auth_token
    kind: function.lua
    source: file://auth_token.lua
    method: handler
    modules: [http, sql, crypto, security, json]
    security:
      actor:
        id: "service:auth"
      policies:
        - app:system_policy

  - name: auth_token.endpoint
    kind: http.endpoint
    meta:
      router: app:public_router
    method: POST
    path: /auth/token
    func: app:auth_token

  # WebSocket ticker endpoint
  - name: ws_ticker
    kind: function.lua
    source: file://ws_ticker.lua
    method: handler
    modules: [http, json, security, logger]

  - name: ws_ticker.endpoint
    kind: http.endpoint
    meta:
      router: app:ws_router
    method: GET
    path: /ticker
    func: app:ws_ticker
```

`user_policy` rides inside every issued token and covers what an authenticated connection does. `system_policy` covers the code that runs before any token exists — the migration, the ticker, and the token exchange itself — because a gated call made without an actor and a scope is denied.

For production, read the HMAC key from an environment variable with a placeholder (`token_key: ${env:TOKEN_KEY}`) instead of hardcoding it. See [Environment System](system/env.md).



### Token Exchange


`auth_token.lua` validates API keys and issues HMAC-signed tokens:

```lua
local http = require("http")
local sql = require("sql")
local security = require("security")

local function handler()
    local req = http.request()
    local res = http.response()

    local body, parse_err = req:body_json()
    if parse_err then
        res:set_status(http.STATUS.BAD_REQUEST)
        res:write_json({error = "invalid JSON"})
        return
    end

    local api_key = body.api_key
    if not api_key or #api_key == 0 then
        res:set_status(http.STATUS.BAD_REQUEST)
        res:write_json({error = "api_key required"})
        return
    end

    local db, db_err = sql.get("app:db")
    if db_err then
        res:set_status(http.STATUS.INTERNAL_ERROR)
        res:write_json({error = "database unavailable"})
        return
    end

    local rows, query_err = db:query(
        "SELECT user_id, role FROM api_keys WHERE api_key = ?",
        {api_key}
    )
    db:release()

    if query_err then
        res:set_status(http.STATUS.INTERNAL_ERROR)
        res:write_json({error = "lookup failed"})
        return
    end
    if #rows == 0 then
        res:set_status(http.STATUS.UNAUTHORIZED)
        res:write_json({error = "invalid API key"})
        return
    end

    local user = rows[1]

    -- Create actor with user identity
    local actor = security.new_actor("user:" .. user.user_id, {
        role = user.role,
        user_id = user.user_id
    })

    -- Attach user_policy to the scope
    local policy, _ = security.policy("app:user_policy")
    local scope = policy and security.new_scope({policy}) or security.new_scope()

    -- Issue HMAC-signed token
    local store, store_err = security.token_store("app:tokens")
    if store_err then
        res:set_status(http.STATUS.INTERNAL_ERROR)
        res:write_json({error = "token store unavailable"})
        return
    end

    local token, token_err = store:create(actor, scope, {
        expiration = "1h",
        meta = {ip = req:remote_addr()}
    })
    store:close()

    if token_err then
        res:set_status(http.STATUS.INTERNAL_ERROR)
        res:write_json({error = "token creation failed"})
        return
    end

    res:write_json({
        token = token,
        user_id = user.user_id,
        role = user.role,
        expires_in = 3600
    })
end

return { handler = handler }
```



### WebSocket Endpoint


`ws_ticker.lua` spawns a handler process for each authenticated connection:

```lua
local http = require("http")
local json = require("json")
local security = require("security")
local logger = require("logger")

local function handler()
    local req = http.request()
    local res = http.response()

    if req:method() ~= http.METHOD.GET then
        res:set_status(http.STATUS.METHOD_NOT_ALLOWED)
        res:write_json({error = "method not allowed"})
        return
    end

    -- Actor is set by token_auth middleware
    local actor = security.actor()
    if not actor then
        res:set_status(http.STATUS.UNAUTHORIZED)
        res:write_json({error = "authentication required"})
        return
    end

    local user_id = actor:id()

    -- Spawn handler process (authorized by user_policy in token)
    local pid, err = process.spawn("app:ws_handler", "app:processes", user_id)
    if err then
        logger:error("spawn failed", {error = tostring(err)})
        res:set_status(http.STATUS.INTERNAL_ERROR)
        res:write_json({error = "failed to create handler"})
        return
    end

    -- Configure websocket_relay to route messages to handler
    res:set_header("X-WS-Relay", json.encode({
        target_pid = tostring(pid),
        metadata = {user_id = user_id, auth_time = os.time()}
    }))
end

return { handler = handler }
```



### Connection Handler


The `websocket_relay` middleware automatically sends lifecycle messages to the handler process:
- `ws.join` - Connection established, includes `client_pid` for sending responses
- `ws.message` - Client sent a message; the payload is the raw frame (a string for text frames)
- `ws.leave` - Connection closed (sent automatically on disconnect)

Messages sent the other way, to the client PID, reach the browser as a single JSON text frame shaped `{topic, data}`. The topic is yours to pick and the payload arrives as `data`.

`ws_handler.lua` - handles these lifecycle messages:

```lua
local logger = require("logger")
local json = require("json")

local function main(user_id)
    local inbox = process.inbox()
    local client_pid = nil
    local subscribed = false

    logger:info("handler started", {user_id = user_id})

    while true do
        local msg, ok = inbox:receive()
        if not ok then break end

        local topic = msg:topic()
        local data = msg:payload():data()

        if topic == "ws.join" then
            client_pid = data.client_pid

            -- Subscribe with our PID for crash monitoring
            local _, subscribe_err = process.send("ticker", "subscribe", {
                client_pid = client_pid,
                handler_pid = process.pid()
            })
            if subscribe_err then
                error("failed to subscribe to ticker: " .. tostring(subscribe_err))
            end
            subscribed = true

            -- Send welcome
            process.send(client_pid, "welcome", {user_id = user_id})

            logger:info("client joined", {user_id = user_id, client_pid = client_pid})

        elseif topic == "ws.message" then
            local content = json.decode(data)
            if content and content.type == "ping" then
                process.send(client_pid, "pong", {})
            end

        elseif topic == "ws.leave" then
            -- Relay sends this automatically on disconnect
            logger:info("client left", {user_id = user_id, client_pid = data.client_pid})
            if subscribed then
                process.send("ticker", "unsubscribe", {handler_pid = process.pid()})
            end
            break
        end
    end

    return 0
end

return { main = main }
```



### Broadcasting


`ticker.lua` maintains subscriptions and broadcasts locally simulated price updates;
the tutorial does not call an external market-data service:

```lua
local logger = require("logger")
local time = require("time")
local crypto = require("crypto")

-- handler_pid -> client_pid mapping
local subscriptions = {}

local prices = {
    ["BTC-USD"] = 42000.00,
    ["ETH-USD"] = 2500.00,
    ["SOL-USD"] = 95.00
}

local function broadcast(updates)
    for _, client_pid in pairs(subscriptions) do
        process.send(client_pid, "ticker", updates)
    end
end

local function update_prices()
    for symbol, price in pairs(prices) do
        local bytes, random_err = crypto.random.bytes(2)
        if random_err then
            error("failed to generate price movement: " .. tostring(random_err))
        end
        local rand = (bytes:byte(1) * 256 + bytes:byte(2)) / 65535.0
        local factor = (rand - 0.5) * 0.002
        prices[symbol] = price * (1 + factor)
        prices[symbol] = tonumber(string.format("%.2f", prices[symbol]))
    end
end

local function get_updates()
    local updates = {}
    for symbol, price in pairs(prices) do
        table.insert(updates, {symbol = symbol, price = price, timestamp = os.time()})
    end
    return updates
end

local function main()
    local inbox = process.inbox()
    local events = process.events()

    local ticker, ticker_err = time.ticker("1s")
    if ticker_err then
        logger:error("failed to create ticker", {error = tostring(ticker_err)})
        error("failed to create ticker: " .. tostring(ticker_err))
    end
    local tick_ch = ticker:response()

    local _, register_err = process.registry.register("ticker")
    if register_err then
        error("failed to register ticker: " .. tostring(register_err))
    end
    logger:info("ticker started", {pid = process.pid()})

    while true do
        local r = channel.select {
            inbox:case_receive(),
            events:case_receive(),
            tick_ch:case_receive()
        }

        if r.channel == tick_ch then
            update_prices()
            if next(subscriptions) then
                broadcast(get_updates())
            end

        elseif r.channel == events then
            local event = r.value
            if event.kind == process.event.CANCEL then
                ticker:stop()
                logger:info("ticker stopping")
                return 0
            elseif event.kind == process.event.EXIT then
                -- Handler exited, remove subscription
                if subscriptions[event.from] then
                    logger:info("handler exited", {handler_pid = event.from})
                    subscriptions[event.from] = nil
                end
            end

        else
            local msg = r.value
            local topic = msg:topic()
            local data = msg:payload():data()

            if topic == "subscribe" then
                local handler_pid = data.handler_pid
                local client_pid = data.client_pid

                subscriptions[handler_pid] = client_pid
                process.monitor(handler_pid)

                logger:info("subscribed", {handler_pid = handler_pid, client_pid = client_pid})

                process.send(client_pid, "ticker", get_updates())

            elseif topic == "unsubscribe" then
                subscriptions[data.handler_pid] = nil
                logger:info("unsubscribed", {handler_pid = data.handler_pid})
            end
        end
    end
end

return { main = main }
```



### Database Migration


`migrate.lua` creates the API-keys table and generates a demo key:

```lua
local sql = require("sql")
local logger = require("logger")
local crypto = require("crypto")

local function main()
    local db, err = sql.get("app:db")
    if err then
        logger:error("failed to connect", {error = tostring(err)})
        error("failed to connect: " .. tostring(err))
    end

    local _, exec_err = db:execute([[
        CREATE TABLE IF NOT EXISTS api_keys (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            api_key TEXT UNIQUE NOT NULL,
            user_id TEXT NOT NULL,
            role TEXT NOT NULL DEFAULT 'user',
            created_at INTEGER NOT NULL
        )
    ]])

    if exec_err then
        db:release()
        logger:error("migration failed", {error = tostring(exec_err)})
        error("migration failed: " .. tostring(exec_err))
    end

    -- Create one random local-demo key. It is printed only on first creation.
    local rows, query_err = db:query(
        "SELECT api_key FROM api_keys WHERE user_id = ?",
        {"demo"}
    )
    if query_err then
        db:release()
        error("failed to query demo API key: " .. tostring(query_err))
    end

    if #rows == 0 then
        local demo_key, key_err = crypto.random.string(32)
        if key_err then
            db:release()
            error("failed to generate demo API key: " .. tostring(key_err))
        end

        local _, insert_err = db:execute(
            "INSERT INTO api_keys (api_key, user_id, role, created_at) VALUES (?, ?, ?, ?)",
            {demo_key, "demo", "user", os.time()}
        )
        if insert_err then
            db:release()
            error("failed to store demo API key: " .. tostring(insert_err))
        end
        logger:info("demo API key created", {api_key = demo_key})
    else
        logger:info("demo API key already exists; use the value saved from its first creation")
    end

    db:release()
    return 0
end

return { main = main }
```



### Browser Client


`public/index.html` - exchanges the API key for a token, then streams prices. A browser cannot set headers on a WebSocket handshake, so the token travels in the `x-auth-token` query parameter that `token_auth` also reads:

```html
<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <title>Crypto Ticker</title>
  <style>
    body { font-family: system-ui, sans-serif; max-width: 40rem; margin: 3rem auto; }
    table { border-collapse: collapse; width: 100%; margin-top: 1rem; }
    th, td { text-align: left; padding: .4rem .6rem; border-bottom: 1px solid #ddd; }
    #status { color: #666; }
  </style>
</head>
<body>
  <h1>Crypto Ticker</h1>
  <input id="key" placeholder="demo API key" size="40">
  <button id="connect">Connect</button>
  <p id="status">disconnected</p>
  <table><thead><tr><th>Symbol</th><th>Price</th></tr></thead><tbody id="rows"></tbody></table>

  <script>
    const status = document.getElementById("status");
    const rows = document.getElementById("rows");

    document.getElementById("connect").onclick = async () => {
      const res = await fetch("/auth/token", {
        method: "POST",
        headers: {"Content-Type": "application/json"},
        body: JSON.stringify({api_key: document.getElementById("key").value})
      });
      if (!res.ok) { status.textContent = "auth failed"; return; }
      const {token} = await res.json();

      const url = `ws://${location.host}/ws/ticker?x-auth-token=${encodeURIComponent(token)}`;
      const ws = new WebSocket(url);

      ws.onopen = () => {
        status.textContent = "connected";
        ws.send(JSON.stringify({type: "ping"}));
      };
      ws.onclose = () => { status.textContent = "disconnected"; };

      ws.onmessage = (evt) => {
        const msg = JSON.parse(evt.data);
        if (msg.topic !== "ticker") return;
        rows.innerHTML = "";
        for (const quote of msg.data) {
          rows.insertAdjacentHTML("beforeend",
            `<tr><td>${quote.symbol}</td><td>${quote.price.toFixed(2)}</td></tr>`);
        }
      };
    };
  </script>
</body>
</html>
```



### Running


Initialize the lock, run the migration to completion, then start the long-running
services. Running the migration as a separate command prevents the token endpoint
from racing the table creation.

```bash
mkdir -p data
wippy init
wippy run -x app:migrate
wippy run
```

Open `http://127.0.0.1:8081` and enter the demo API key from the migration log. The
page should show `Connected as demo`, followed by BTC, ETH, and SOL prices that update
once per second.

You can also verify the exchange before opening the browser:

```bash
curl -X POST http://127.0.0.1:8081/auth/token \
  -H "Content-Type: application/json" \
  -d '{"api_key":"<demo-key-from-migration>"}'
```

In PowerShell:

```powershell
Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8081/auth/token `
  -ContentType 'application/json' `
  -Body '{"api_key":"<demo-key-from-migration>"}'
```

A successful response contains `token`, `user_id: "demo"`, `role: "user"`, and
`expires_in: 3600`. An invalid key returns HTTP 401.



### Troubleshooting and Cleanup


- `no such table: api_keys` means the migration command was skipped or failed. Stop
  the runtime and rerun `wippy run -x app:migrate` before starting it again.
- A 401 from `/auth/token` means the API key does not match the row in
  `data/auth.db`. Reset the database if the one-time log value was lost.
- A 401 or immediate close on the WebSocket usually means the query parameter was
  removed or the in-memory token store was reset by a runtime restart. Exchange the
  API key again after every restart.
- An origin rejection means the browser URL does not exactly match
  `http://127.0.0.1:8081`; use that URL or update both origin options together.
- Stop the runtime with Ctrl+C. Delete `data/auth.db` to remove the demo API key.



### Next Steps


- [WebSocket Relay](http/websocket-relay.md) — Middleware configuration
- [Security Module](lua/security/security.md) — Actors, policies, and token stores
- [Process Management](lua/core/process.md) — Process spawning and messaging



---

# "Frontend Facade"

## Frontend Facade


Use `wippy/facade` to serve the Wippy Web Host from a backend application. The facade loads the frontend bundle from a CDN and configures it through a JSON endpoint served by the application, without requiring a frontend build step. Dependency parameters control branding, theming, and feature flags.

**Classification:** Partial integration recipe. It completely configures and verifies
the facade shell and config endpoint, but it does not invent an authentication system
or the application APIs consumed by the Web Host.



### What You'll Build


A backend app that serves the Wippy UI:

1. An HTTP server and public router.
2. A `wippy/facade` dependency connected to the server and router, with custom branding.
3. The facade shell at `/` and its configuration at `/api/public/facade/config`.



### Prerequisites


- Wippy runtime `v0.3.32a` and a project created with `wippy init` or the
  [Wippy application template](https://github.com/wippyai/app).
- For browser rendering, a same-origin login flow that obtains a real backend token
  and stores `{"token":"..."}` under the localStorage key `@wippy_token_info`.
  The facade does not issue or validate that token.
- The facade installed:

  ```bash
  wippy add wippy/facade@0.6.37
  wippy install
  ```



### How It Works


1. The shell is rendered from the facade's template and served at `/` by your HTTP
   server; its assets and the deep-link fallback come from a static mount on the same server.
2. On load it fetches `GET /api/public/facade/config`.
3. It reads `@wippy_token_info` from `localStorage`, redirecting to `login_path`
   only when the item is absent or cannot be parsed as JSON.
4. It imports the Web Host bundle from the CDN (`facade_url + '/module.js'`) and calls
   `initWippyApp(...)` with the config.

The application serves the shell and its configuration; the UI bundle comes from the CDN.



### Dependencies


The facade requires an `http.service` for the shell and an `http.router` for its configuration endpoint. Other parameters customize branding and behavior.

```yaml
version: "1.0"
namespace: app

entries:
  - name: gateway
    kind: http.service
    addr: ":8087"
    lifecycle:
      auto_start: true

  - name: api.public
    kind: http.router
    meta:
      server: app:gateway
    prefix: /api/public

  - name: facade
    kind: ns.dependency
    component: wippy/facade
    version: "*"
    parameters:
      - name: server
        value: app:gateway
      - name: router
        value: app:api.public
      - name: app_title
        value: Verify App
```

The shell requests its config, theme script, and CSS variables under
`/api/public/facade/`, so the public router's prefix must be `/api/public`.



### Run It


```bash
wippy run
```

The shell is served at the server root, and the config endpoint returns the runtime
configuration:

```bash
curl http://localhost:8087/api/public/facade/config
```

Selected fields from the response are shown below:

```json
{
  "facade_url": "https://web-host.wippy.ai/webcomponents-1.0.58",
  "iframe_origin": "https://web-host.wippy.ai",
  "iframe_url": "https://web-host.wippy.ai/webcomponents-1.0.58/iframe.html?waitForCustomConfig",
  "module_file": "/module.js",
  "mode": "compat",
  "login_path": "/login.html",
  "themeMode": "auto",
  "themePersist": "none",
  "themeStorageKey": "@wippy-theme-mode",
  "env": { "APP_API_URL": "", "APP_AUTH_API_URL": "", "APP_WEBSOCKET_URL": "" },
  "themeMode": "auto",
  "themePersist": "none",
  "themeStorageKey": "@wippy-theme-mode",
  "theming": {
    "host": { "i18n": { "app": { "title": "Verify App", "icon": "wippy:logo", "appName": "Wippy AI" } } }
  },
  "hostConfig": {
    "showAdmin": true, "allowSelectModel": false, "hideNavBar": false,
    "disableRightPanel": false, "startNavOpen": false, "hideSessionSelector": false,
    "renderEngine": "iframe", "session": { "type": "non-persistent" }, "history": "hash"
  }
}
```

The `app_title` parameter appears as `theming.host.i18n.app.title` in the response.

Also fetch the root document:

```bash
curl http://localhost:8087/
```

It should return an HTML shell that fetches the config endpoint and checks
`@wippy_token_info`. These two HTTP checks verify the recipe without bypassing auth.



### Browser Authentication and Rendering


The facade's localStorage contract is origin-scoped. A login page on another port or
hostname cannot populate the token for `http://localhost:8087`. After a successful
same-origin token exchange, the login page writes the real token and returns to the
shell:

```js
localStorage.setItem('@wippy_token_info', JSON.stringify({token: result.token}));
window.location.assign('/');
```

The shell reads the token, imports
`https://web-host.wippy.ai/webcomponents-1.0.56/module.js`, and passes the token to the
Host. Rendering is complete only when the browser shows the Host without redirecting
and its API requests authenticate successfully. Do not use a placeholder token merely
to suppress the redirect: the shell does not validate it, so the failure only moves to
the first protected API request.



### Configuration


Parameters are passed as dependency `parameters` (values are strings; JSON values are
JSON-encoded strings). Common ones:

| Parameter | Purpose |
|---|---|
| `server` / `router` | _(required)_ HTTP server and public router |
| `app_title` / `app_name` / `app_icon` | Branding (icon is an Iconify ref) |
| `show_admin` / `hide_nav_bar` | Feature flags (`"true"` / `"false"`) |
| `login_path` | Where the shell redirects when no auth token is present |
| `session_type` | `non-persistent` or `cookie` |
| `history_mode` | `hash` or `browser` |
| `css_variables` | JSON string of CSS custom properties, e.g. `'{"--p-primary":"#6366f1"}'` |
| `fe_facade_url` | CDN bundle URL (pinned per facade release; leave default unless overriding) |

Two values are derived at runtime from `PUBLIC_API_URL` rather than parameters: the API
base URL and the WebSocket URL (`http`→`ws`, `https`→`wss`). The facade reads it through
the env registry, so declare it as an `env.variable` in your app. If unset, the browser
falls back to `window.location.origin`.



### Limitations


- The facade does not provide authentication. It expects an auth flow that writes a
  token to `localStorage`; without one it redirects to `login_path`. Pair it with
  `userspace/users` or your own auth.
- The UI bundle loads from the CDN (`fe_facade_url`), so the user's browser must be
  able to reach that URL.



### Troubleshooting


- A redirect loop to `/login.html` means the current origin has no parseable
  `@wippy_token_info` item. Complete the real login flow on the same origin. A
  parseable object with a missing or empty `token` suppresses this redirect but
  still fails when the Host reaches a protected API.
- HTTP 404 from `/api/public/facade/config` means the router prefix is not
  `/api/public` or the `router` dependency parameter points at another entry.
- A config response with the right values but a blank shell usually means the browser
  cannot load `facade_url + module_file`; check the browser network panel and CDN
  policy.
- Authenticated API errors after the Host renders belong to the application's API and
  token validation layer, not to the facade shell.



### Next Steps


- [Hello World](tutorials/hello-world.md) — Minimal project layout
- [Authentication](tutorials/auth.md) — Add the login flow expected by the shell
- [HTTP Endpoints](http/endpoint.md) — Routers, static files, and handlers



---

# "Network Overlays"

## Network Overlays


Configure a SOCKS5 overlay for outbound HTTP calls, then review inheritance, inbound listeners, application defaults, and permissions.

**Classification:** Runnable SOCKS5 tutorial with a partial Tailscale recipe.
The direct/Tor probe is complete once an external Tor listener is available. The
Tailscale section explains Wippy wiring but intentionally defers account provisioning
to Tailscale. For I2P configuration, use the network-system reference linked below.



### Overview


Wippy represents overlay networks as registry entries. Code can select an overlay for a call, and that selection propagates to nested calls until a descendant overrides it.

Wippy supports three overlay entry kinds:

- `network.socks5` — generic SOCKS5 proxy (also Tor's SOCKS5 listener)
- `network.tailscale` — tsnet overlay node
- `network.i2p` — I2P SAM v3 bridge



### Prerequisites


- Wippy runtime `v0.3.32a`.
- `curl` and outbound HTTPS access to `api.ipify.org`.
- A Tor daemon exposing SOCKS5 on `127.0.0.1:9050`. Install a supported package from
  the [Tor Project download page](https://www.torproject.org/download/tor/), start it,
  and verify the listener before
  running Wippy:

  ```bash
  curl --socks5-hostname 127.0.0.1:9050 https://api.ipify.org?format=json
  ```

  A successful check returns JSON containing an IP address. Tor Browser commonly
  uses port 9150 instead; if that is the listener you are intentionally using,
  change the registry entry and the verification command together.
- An empty working directory:

  ```bash
  mkdir netdemo
  cd netdemo
  mkdir src
  ```



### Project Structure


```
netdemo/
├── wippy.lock
└── src/
    ├── _index.yaml
    └── probe.lua
```



### Step 1: Define an Overlay


Create `src/_index.yaml`:

```yaml
version: "1.0"
namespace: app

entries:
  - name: net_policy
    kind: security.policy
    policy:
      actions:
        - http_client.request
        - network.select
      resources: "*"
      effect: allow

  - name: processes
    kind: process.host
    lifecycle:
      auto_start: true

  - name: terminal
    kind: terminal.host
    lifecycle:
      auto_start: true

  # SOCKS5 proxy entry (Tor exposes one at 127.0.0.1:9050 by default)
  - name: tor
    kind: network.socks5
    host: 127.0.0.1
    port: 9050
    isolate_streams: true

  - name: probe
    kind: process.lua
    meta:
      command:
        name: probe
        short: Check outbound IP through overlays
        security:
          actor:
            id: system.probe
          policies:
            - app:net_policy
    source: file://probe.lua
    method: main
    modules:
      - io
      - http_client
      - json
```

With `isolate_streams: true`, the SOCKS5 driver creates random credentials for each connection so Tor can open a fresh circuit for each dial.

Security is strict by default, so the command carries the actor and policy its launch runs under. `http_client.request` covers the outbound call and `network.select` covers the explicit overlay choice; without them every check fails closed.



### Step 2: Route Outbound Calls


Create `src/probe.lua`:

```lua
local io = require("io")
local http_client = require("http_client")
local json = require("json")

local function fetch_ip(overlay)
    local options = { timeout = "15s" }
    if overlay then
        options.overlay_network = overlay
    end

    local resp, err = http_client.get("https://api.ipify.org?format=json", options)
    if err then
        return nil, tostring(err)
    end
    if resp.status_code ~= 200 then
        return nil, "HTTP " .. resp.status_code
    end

    local body = json.decode(resp.body or "")
    return body and body.ip, nil
end

local function main()
    local direct, d_err = fetch_ip(nil)
    if d_err then
        io.print("direct failed: " .. d_err)
    else
        io.print("direct IP: " .. direct)
    end

    local routed, r_err = fetch_ip("app:tor")
    if r_err then
        io.print("tor failed: " .. r_err)
    else
        io.print("tor IP:    " .. routed)
    end

    return 0
end

return { main = main }
```

The `overlay_network` option selects the overlay for that HTTP call. Without it, the dial uses the process default: `network_service.default_network` from `.wippy.yaml`, or a direct connection when no default is set.



### Step 3: Run It


```bash
wippy init
wippy run probe
```

With Tor running locally:

```
direct IP: <your public IP>
tor IP:    <Tor exit IP>
```

Both lines must contain valid IP addresses. They should normally differ; the important
proof is that the routed request succeeds only through the configured SOCKS listener.

If Tor is not running, the `tor IP` line will report a dial error — the SOCKS5 overlay does not silently fall back to a direct connection.



### Inheritance


Overlay selection propagates through nested calls. Selecting an overlay at a `funcs.call` or `process.spawn` boundary applies it to nested HTTP calls, function calls, and process spawns until one explicitly overrides it:

```lua
local funcs = require("funcs")

local result, err = funcs.new()
    :with_options({ network = "app:tor" })
    :call("app:scrape_site", url)
```

```lua
local pid, err = process.with_options({ network = "app:tor" })
    :spawn_monitored("app.workers:probe", "app:processes")
```

The nested function or spawned process sees the overlay on every outgoing dial without passing it explicitly.



### Binding a Listener


Tailscale can also accept HTTP listeners. Attach the overlay to the `http.service`
instead of the client:

```yaml
  - name: bind_policy
    kind: security.policy
    policy:
      actions: "network.bind"
      resources: "*"
      effect: allow

  - name: tailnet
    kind: network.tailscale
    hostname: wippy-node
    auth_key_env: TS_AUTHKEY
    ephemeral: true

  - name: gateway
    kind: http.service
    addr: ":8080"
    network: app:tailnet
    lifecycle:
      auto_start: true
      security:
        actor:
          id: system.gateway
        policies:
          - app:bind_policy
```

`auth_key` resolves through the [env registry](system/env.md), so `TS_AUTHKEY` is a registered variable — an OS value needs an `env.variable` backed by `env.storage.os`.

Binding through an overlay is gated by `network.bind`, checked when the listener starts, so the service declares a scope that allows it. The server binds on the tailnet interface; clients reach it via the Tailscale address. SOCKS5 is outbound-only — assigning it to `http.service` fails the listener with `inbound listeners are not exposed over SOCKS5`.



### App-wide Default


Set a default overlay in `.wippy.yaml` so every call uses it unless overridden:

```yaml
network_service:
  state_dir: .wippy/net
  default_network: app:tor
```



### Permissions


The `network.select` action gates explicit overlay selection. Deny it on a scope to stop code from choosing an overlay:

```yaml
  - name: deny_network
    kind: security.policy
    policy:
      actions: "network.select"
      resources: "*"
      effect: deny
    groups:
      - untrusted
```

Inherited overlays bypass this check — they were authorized at the caller's edge. Only explicit re-selection at a Lua boundary is gated.



### Troubleshooting and Cleanup


- `connection refused` on `127.0.0.1:9050` means Tor is not listening on the
  configured port. Verify Tor with the prerequisite `curl` command before debugging
  Wippy.
- A direct request failure and a routed success usually indicate local DNS, proxy, or
  firewall rules affecting the direct path. The two calls are independent.
- `access denied` for the routed call means the command security context lacks
  `network.select` for `app:tor`; keep `app:probe_policy` attached under
  `meta.command.security`.
- The SOCKS5 driver never falls back to a direct connection. Do not remove the error
  merely to make the demo continue.
- Stop the Wippy command when it exits and stop the Tor daemon only if you started it
  solely for this tutorial. The SOCKS5 example creates no persistent network state.
  A Tailscale entry can persist node state under `.wippy/net/tailscale/`; remove the
  `.wippy/net` state directory only after stopping Wippy and only when you intend to
  discard that local tailnet identity.



### Next Steps


- [Network System](system/network.md) — Entry-kind reference
- [HTTP Client](lua/http/client.md) — Per-call overlay options
- [Security Model](system/security.md) — Policies and scopes
- [Authentication](tutorials/auth.md) — Token-based security



---

# "Running Rust on Wippy"

## Running Rust on Wippy


Build a Rust WebAssembly component, register it with Wippy, and expose it through function, CLI, and HTTP entries.

**Classification:** Runnable tutorial with an external Rust component toolchain. The
page supplies the WIT, Rust implementation, Wippy registry, integrity-hash workflow,
commands, expected results, and failure checks.



### What We're Building


A Rust component with four exported functions:

- **greet** — Accepts a name and returns a greeting
- **add** — Adds two integers
- **fibonacci** — Computes the nth Fibonacci number
- **list-files** — Lists files in a mounted directory

The Wippy application registers these exports as callable functions, CLI commands, and an HTTP endpoint.



### Prerequisites


- Wippy runtime `v0.3.32a`.
- [Rust toolchain](https://rustup.rs/) with the `wasm32-wasip1` target.
- A working C toolchain. On Linux, `cargo-component` also requires OpenSSL development
  libraries.
- [cargo-component 0.21.1](https://github.com/bytecodealliance/cargo-component/releases/tag/v0.21.1),
  the release used by this tutorial.

```bash
rustup target add wasm32-wasip1
cargo install cargo-component --version 0.21.1 --locked
```

Create the generated component scaffold and Wippy directories:

```bash
mkdir rust-wasm-demo
cd rust-wasm-demo
cargo component new --lib demo
mkdir -p app/src/demo/wasm
```

In PowerShell:

```powershell
New-Item -ItemType Directory -Path rust-wasm-demo
Set-Location rust-wasm-demo
cargo component new --lib demo
New-Item -ItemType Directory -Path app\src\demo\wasm -Force
```

`cargo component new` writes a compatible `Cargo.toml`, `src/lib.rs`, WIT file, and
later regenerates `src/bindings.rs`. Keep the generated `wit-bindgen-rt` version paired
with the installed `cargo-component`; the tool describes that interface as experimental
and does not guarantee generated-code compatibility across versions.



### Project Structure


```
rust-wasm-demo/
├── demo/                    # Rust component
│   ├── Cargo.toml
│   ├── wit/
│   │   └── world.wit       # WIT interface
│   └── src/
│       ├── bindings.rs      # generated by cargo-component
│       └── lib.rs           # implementation
└── app/                     # Wippy application
    ├── wippy.lock
    └── src/
        ├── _index.yaml      # Infrastructure
        └── demo/
            ├── _index.yaml  # CLI processes
            └── wasm/
                ├── _index.yaml          # WASM entries
                └── demo_component.wasm  # Compiled binary
```



### Step 1: Create the WIT Interface


WebAssembly Interface Types (WIT) defines the contract between the host and guest component.

Create `demo/wit/world.wit`:

```wit
package component:demo;

world demo {
    export greet: func(name: string) -> string;
    export add: func(a: s32, b: s32) -> s32;
    export fibonacci: func(n: u32) -> u64;
    export list-files: func(path: string) -> string;
}
```

Each export becomes a function that Wippy can call.



### Step 2: Implement in Rust


Keep the generated `demo/Cargo.toml`. Its package metadata must target
`component:demo`, matching the WIT package, and its library crate type must remain
`cdylib`.

Create `demo/src/lib.rs`:

```rust
#[allow(warnings)]
mod bindings;

use bindings::Guest;

struct Component;

impl Guest for Component {
    fn greet(name: String) -> String {
        format!("Hello, {}!", name)
    }

    fn add(a: i32, b: i32) -> i32 {
        a + b
    }

    fn fibonacci(n: u32) -> u64 {
        if n <= 1 {
            return n as u64;
        }
        let (mut a, mut b) = (0u64, 1u64);
        for _ in 2..=n {
            let next = a + b;
            a = b;
            b = next;
        }
        b
    }

    fn list_files(path: String) -> String {
        let mut result = String::new();
        match std::fs::read_dir(&path) {
            Ok(entries) => {
                for entry in entries {
                    match entry {
                        Ok(e) => {
                            let name = e.file_name().to_string_lossy().to_string();
                            let meta = e.metadata();
                            let (kind, size) = match meta {
                                Ok(m) => {
                                    let kind = if m.is_dir() { "dir" } else { "file" };
                                    (kind, m.len())
                                }
                                Err(_) => ("?", 0),
                            };
                            let line = format!("{:<6} {:>8}  {}", kind, size, name);
                            println!("{}", line);
                            result.push_str(&line);
                            result.push('\n');
                        }
                        Err(e) => {
                            let line = format!("error: {}", e);
                            eprintln!("{}", line);
                            result.push_str(&line);
                            result.push('\n');
                        }
                    }
                }
            }
            Err(e) => {
                let line = format!("cannot read {}: {}", path, e);
                eprintln!("{}", line);
                result.push_str(&line);
                result.push('\n');
            }
        }
        result
    }
}

bindings::export!(Component with_types_in bindings);
```

The `bindings` module is generated by `cargo-component` from the WIT definition.



### Step 3: Build the Component


```bash
cd demo
cargo component build --release
```

This produces `target/wasm32-wasip1/release/demo.wasm`. Copy it to your Wippy app:

```bash
mkdir -p ../app/src/demo/wasm
cp target/wasm32-wasip1/release/demo.wasm ../app/src/demo/wasm/demo_component.wasm
```

In PowerShell:

```powershell
New-Item -ItemType Directory -Path ..\app\src\demo\wasm -Force
Copy-Item -LiteralPath target\wasm32-wasip1\release\demo.wasm `
  -Destination ..\app\src\demo\wasm\demo_component.wasm
```

Get the SHA-256 hash for integrity verification:

```bash
sha256sum ../app/src/demo/wasm/demo_component.wasm
```

On PowerShell, use:

```powershell
(Get-FileHash ..\app\src\demo\wasm\demo_component.wasm -Algorithm SHA256).Hash.ToLowerInvariant()
```

Copy the 64 lowercase hexadecimal characters into every `YOUR_HASH_HERE` below. The
final field must have the form `sha256:<64-hex-characters>`; it is the hash of the
copied binary, not the Rust source or the original build path.



#### Infrastructure


Create `app/src/_index.yaml`:

```yaml
version: "1.0"
namespace: demo

entries:
  - name: gateway
    kind: http.service
    meta:
      comment: HTTP server
    addr: ":8090"
    lifecycle:
      auto_start: true

  - name: api
    kind: http.router
    meta:
      comment: Public API router
      server: demo:gateway
    prefix: /

  - name: processes
    kind: process.host
    lifecycle:
      auto_start: true

  - name: terminal
    kind: terminal.host
    lifecycle:
      auto_start: true

  - name: policy
    kind: security.policy
    meta:
      comment: Grants access to mounted filesystems and WASM functions
    policy:
      actions:
        - fs.get
        - funcs.call
      resources: "*"
      effect: allow
```

Mounting a filesystem into a WASM module and calling a WASM function are both guarded actions. The policy grants them; entries that need them reference it.



#### WASM Functions


Create `app/src/demo/wasm/_index.yaml`:

```yaml
version: "1.0"
namespace: demo.wasm

entries:
  - name: assets
    kind: fs.directory
    meta:
      comment: Filesystem with WASM binaries
    directory: ./src/demo/wasm

  - name: greet_function
    kind: function.wasm
    meta:
      comment: Greet function via payload transport
    fs: demo.wasm:assets
    path: /demo_component.wasm
    hash: sha256:YOUR_HASH_HERE
    method: greet
    pool:
      type: inline

  - name: add_function
    kind: function.wasm
    meta:
      comment: Add function via payload transport
    fs: demo.wasm:assets
    path: /demo_component.wasm
    hash: sha256:YOUR_HASH_HERE
    method: add
    pool:
      type: inline

  - name: fibonacci_function
    kind: function.wasm
    meta:
      comment: Fibonacci function via payload transport
    fs: demo.wasm:assets
    path: /demo_component.wasm
    hash: sha256:YOUR_HASH_HERE
    method: fibonacci
    pool:
      type: inline
```

Key points:

- A single `fs.directory` entry provides the WASM binary.
- Multiple functions reference the same binary with different `method` values.
- The `hash` field verifies binary integrity at load time.
- The `inline` pool serializes calls through one warm instance. It resets per-call
  execution state between synchronous calls; use another pool type when you need
  concurrent workers.



#### Functions with WASI


The `list-files` function accesses the filesystem, so it needs WASI imports:

```yaml
  - name: list_files_function
    kind: function.wasm
    meta:
      comment: Filesystem listing with WASI mounts
    fs: demo.wasm:assets
    path: /demo_component.wasm
    hash: sha256:YOUR_HASH_HERE
    method: list-files
    imports:
      - wasi:cli
      - wasi:io
      - wasi:clocks
      - wasi:filesystem
    wasi:
      mounts:
        - fs: demo.wasm:assets
          guest: /data
    pool:
      type: inline
```

The `wasi.mounts` section maps a Wippy filesystem entry to a guest path. Inside the WASM module, `/data` points to the `demo.wasm:assets` directory.



#### CLI Commands


Create `app/src/demo/_index.yaml`:

```yaml
version: "1.0"
namespace: demo.cli

entries:
  - name: wasm_cli_policy
    kind: security.policy
    policy:
      actions:
        - fs.get
      resources:
        - demo.wasm:assets
      effect: allow

  - name: ls
    kind: process.wasm
    meta:
      comment: List files from mounted WASI filesystem
      command:
        name: ls
        short: List files from mounted directory
        security:
          actor: {id: demo.cli:ls}
          policies: [demo:policy]
    fs: demo.wasm:assets
    path: /demo_component.wasm
    hash: sha256:YOUR_HASH_HERE
    method: list-files
    imports:
      - wasi:cli
      - wasi:io
      - wasi:clocks
      - wasi:filesystem
    wasi:
      mounts:
        - fs: demo.wasm:assets
          guest: /data
```

The `meta.command` block registers the process as a named CLI command. The `greet` command needs no WASI imports since it only uses string operations. The `ls` command needs filesystem access, so it also carries the security context that grants the mount.



#### HTTP Endpoint


Add to `app/src/demo/wasm/_index.yaml`:

```yaml
  - name: http_greet
    kind: function.wasm
    meta:
      comment: Greet exposed via wasi-http transport
    fs: demo.wasm:assets
    path: /demo_component.wasm
    hash: sha256:YOUR_HASH_HERE
    method: greet
    transport: wasi-http
    pool:
      type: inline

  - name: http_greet_endpoint
    kind: http.endpoint
    meta:
      comment: HTTP POST endpoint for WASM greet
      router: demo:api
    method: POST
    path: /greet
    func: http_greet
```

The `wasi-http` transport maps HTTP request/response context to WASM arguments and results.



### Step 5: Initialize and Run


```bash
cd app
wippy init
```



#### Run CLI Commands


```bash


## List available commands

wippy run list
```

```
Available commands:

  greet  Greet someone via WASM  (demo.cli:greet)
  ls  List files from mounted directory  (demo.cli:ls)

Run with: wippy run <command>
```

Arguments after the command name are passed to the exported function as string parameters, so each command takes exactly the arguments its WIT signature declares:

```bash


## Run greet

wippy run greet World
```

```
Hello, World!
```

```bash


## Run ls to list mounted directory

wippy run ls /data
```

The command should print at least `demo_component.wasm` with its file size and exit
with status 0. Wippy does not print arbitrary `process.wasm` return payloads, which is
why the CLI example uses the Rust function that writes to WASI stdout.



#### Run as a Service


```bash
wippy run
```

This starts the HTTP server on port 8090. The `wasi-http` transport passes the request body as the function's single string argument:

```bash
curl -X POST http://localhost:8090/greet -d 'World'
```

```
Hello, World!
```



#### Call from Lua


WASM functions are called the same way as Lua functions. The calling process needs `funcs.call` on the target, which `demo:policy` grants:

```lua
local funcs = require("funcs")

local greeting, err = funcs.call("demo.wasm:greet_function", "World")
-- greeting: "Hello, World!"

local sum, err = funcs.call("demo.wasm:add_function", 6, 7)
-- sum: 13

local fib, err = funcs.call("demo.wasm:fibonacci_function", 10)
-- fib: 55
```



### Troubleshooting and Cleanup


- If `cargo component` is unknown, install it and rerun `cargo component build`; plain
  `cargo build` does not generate the same bindings/component output for this setup.
- A missing `src/bindings.rs` before the first build is expected. A missing file after
  `cargo component build` indicates the WIT package or component metadata could not be
  resolved; fix that build error before copying a binary.
- `WASM hash mismatch` means the binary changed after the documented digest was
  calculated or one placeholder remains. Recopy the release binary, recompute the
  digest, and update every entry that references it.
- An import-instantiation error means the component imports a host profile omitted by
  the entry. Keep the documented `wasi:cli`, `wasi:io`, `wasi:clocks`, and
  `wasi:filesystem` imports on the filesystem examples.
- `cannot read /data` means the `wasi.mounts` guest path or its filesystem entry does
  not match the registry.
- Stop the HTTP runtime with Ctrl+C. Rust build output remains under `demo/target/`;
  remove that directory and the copied `.wasm` file to clean generated artifacts.



### Next Steps


- [WASM Overview](wasm/overview.md) — WebAssembly runtime overview
- [WASM Functions](wasm/functions.md) — Function configuration reference
- [WASM Processes](wasm/processes.md) — Process configuration reference
- [Host Functions](wasm/hosts.md) — Available WASI imports
- [CLI Reference](guides/cli.md) — CLI command documentation



---

# "LLM Agent"

## LLM Agent


Build a terminal chat agent in five phases, from a single LLM call to streaming responses and tool execution.

**Classification: runnable tutorial with an external provider.** Each phase is a
cumulative edit to the same project and is runnable before you continue. The Wippy
contracts and local control flow are testable without credentials; generation requires
network access and a valid `OPENAI_API_KEY`.



### What We're Building


A terminal chat agent that:

- Generates text with an LLM.
- Maintains multi-turn conversations.
- Streams responses incrementally.
- Calls registered tools.



### Project Structure


```
llm-agent/
├── wippy.lock
└── src/
    ├── _index.yaml
    ├── ask.lua
    ├── chat.lua
    └── tools/
        ├── _index.yaml
        ├── current_time.lua
        └── calculate.lua
```



### Phase 1: Simple Generation


Start with a basic function that calls `llm.generate()` with a string prompt.

Start in a Wippy project whose source directory is `./src`. Set `OPENAI_API_KEY`
in the environment that starts Wippy. This tutorial declares its model explicitly;
do not also copy a second entry with the same model name from another application.



#### Entry Definitions


Create `src/_index.yaml`:

```yaml
version: "1.0"
namespace: app

entries:
  - name: policy
    kind: security.policy
    policy:
      actions: "*"
      resources: "*"
      effect: allow

  - name: os_env
    kind: env.storage.os

  - name: processes
    kind: process.host
    lifecycle:
      auto_start: true

  - name: dep.llm
    kind: ns.dependency
    component: wippy/llm
    version: "*"
    parameters:
      - name: env_storage
        value: app:os_env
      - name: process_host
        value: app:processes

  - name: dep.terminal
    kind: ns.dependency
    component: wippy/terminal
    version: "*"

  - name: ask
    kind: process.lua
    meta:
      command:
        name: ask
        short: Ask a single question
        security:
          actor:
            id: app:ask
          policies:
            - app:policy
    source: file://ask.lua
    method: main
    modules:
      - io
    imports:
      llm: wippy.llm:llm
```

The LLM module needs two infrastructure entries:

- `env.storage.os` provides API keys from environment variables.
- `process.host` provides the process runtime used internally by the LLM module.

The `wippy/terminal` dependency provides the `terminal.host` that commands execute on and where `io.print` writes.

`meta.command` gives the process a name so `wippy run ask` launches it with the remaining arguments as string payloads. Its `security` block installs the actor and policy scope for that launch: the LLM module resolves models from the registry, and a command launched without a scope reads nothing from it.



#### Generation Code


Create `src/ask.lua`:

```lua
local io = require("io")
local llm = require("llm")

local function main(input)
    local response, err = llm.generate(input, {
        model = "gpt-4.1-nano",
        temperature = 0.7,
        max_tokens = 512,
    })

    if err then
        io.print("Error: " .. tostring(err))
        return 1
    end

    io.print(response.result)
    return 0
end

return { main = main }
```



#### Model Definition


The LLM module resolves models from the registry. Add a model entry to `_index.yaml`:

```yaml
  - name: gpt-4o-mini
    kind: registry.entry
    meta:
      name: gpt-4o-mini
      type: llm.model
      title: GPT-4o mini
      comment: Fast, affordable model
      capabilities:
        - generate
        - tool_use
        - structured_output
      class:
        - fast
      priority: 100
    max_tokens: 128000
    output_tokens: 16384
    pricing:
      input: 0.15
      output: 0.6
    providers:
      - id: wippy.llm.openai:provider
        provider_model: gpt-4o-mini
```



#### Initialize and Test


```bash
wippy init
wippy run ask "What is the capital of France?"
```

This runs the `ask` process on the terminal host with the question as its argument and prints the result. The model definition tells the LLM module which provider to use and what model name to send to the API.



### Phase 2: Conversations


Upgrade from a single call to a multi-turn conversation using the prompt builder. Register the process as a named command.



#### Update Entry Definitions


Replace the `ask` entry with a `chat` process:

```yaml
  - name: chat
    kind: process.lua
    meta:
      command:
        name: chat
        short: Start a terminal chat
        security:
          actor:
            id: app:chat
          policies:
            - app:policy
    source: file://chat.lua
    method: main
    modules:
      - io
    imports:
      llm: wippy.llm:llm
      prompt: wippy.llm:prompt
```

Executable Lua entries receive `process` as an ambient runtime module, so it is used
directly in the code below and does not belong in the entry's `modules` list.



#### Chat Process


Create `src/chat.lua`:

```lua
local io = require("io")
local llm = require("llm")
local prompt = require("prompt")

local function main()
    io.print("Chat (type 'quit' to exit)")
    io.print("")

    local conversation = prompt.new()
    conversation:add_system("You are a helpful assistant. Be concise and direct.")

    while true do
        io.write("> ")
        io.flush()
        local input = io.readline()
        if not input or input == "quit" or input == "exit" then break end
        if input == "" then goto continue end

        conversation:add_user(input)

        local response, err = llm.generate(conversation, {
            model = "gpt-4o-mini",
            temperature = 0.7,
            max_tokens = 1024,
        })

        if err then
            io.print("Error: " .. tostring(err))
            goto continue
        end

        io.print(response.result)
        io.print("")
        conversation:add_assistant(response.result)

        ::continue::
    end

    io.print("Bye!")
end

return { main = main }
```



#### Run It


```bash
wippy update
wippy install
wippy run chat
```

The prompt builder maintains the full conversation history. Each turn appends the user message and assistant response, giving the model context of prior exchanges.



### Phase 3: Agent Framework


The agent module defines prompts, models, and tools declaratively, then loads and executes the resulting agent through a context and runner.



#### Add Agent Dependency


Add to `_index.yaml`:

```yaml
  - name: dep.agent
    kind: ns.dependency
    component: wippy/agent
    version: "*"
    parameters:
      - name: process_host
        value: app:processes
```



#### Define an Agent


Add an agent entry:

```yaml
  - name: assistant
    kind: registry.entry
    meta:
      type: agent.gen1
      name: assistant
      title: Assistant
      comment: Terminal chat agent
    prompt: |
      You are a helpful terminal assistant. Be concise and direct.
      Answer questions clearly. If you don't know something, say so.
      Do not use emoji in responses.
    model: gpt-4o-mini
    max_tokens: 1024
    temperature: 0.7
```



#### Update the Chat Process


Switch to the agent framework. Update the entry imports:

```yaml
  - name: chat
    kind: process.lua
    meta:
      command:
        name: chat
        short: Start a terminal chat
        security:
          actor:
            id: app:chat
          policies:
            - app:policy
    source: file://chat.lua
    method: main
    modules:
      - io
    imports:
      prompt: wippy.llm:prompt
      agent_context: wippy.agent:context
```

Update `src/chat.lua`:

```lua
local io = require("io")
local prompt = require("prompt")
local agent_context = require("agent_context")

local function main()
    io.print("Chat (type 'quit' to exit)")
    io.print("")

    local ctx = agent_context.new()
    local runner, err = ctx:load_agent("app:assistant")
    if err then
        io.print("Failed to load agent: " .. tostring(err))
        return
    end

    local conversation = prompt.new()

    while true do
        io.write("> ")
        io.flush()
        local input = io.readline()
        if not input or input == "quit" or input == "exit" then break end
        if input == "" then goto continue end

        conversation:add_user(input)

        local response, gen_err = runner:step(conversation)
        if gen_err then
            io.print("Error: " .. tostring(gen_err))
            goto continue
        end

        io.print(response.result)
        io.print("")
        conversation:add_assistant(response.result)

        ::continue::
    end

    io.print("Bye!")
end

return { main = main }
```

The agent definition contains the prompt, model, and parameters, while the process controls execution. A context can add tools or override the model at runtime.

Resolve the newly added agent dependency, then run this phase:

```bash
wippy update
wippy install
wippy run chat
```



### Phase 4: Streaming


Process response chunks as they arrive instead of waiting for the full response.



#### Streaming Implementation


Update `src/chat.lua`:

```lua
local io = require("io")
local prompt = require("prompt")
local agent_context = require("agent_context")

local STREAM_TOPIC = "stream"
local stream_sequence = 0

local function stream_response(runner, conversation)
    stream_sequence = stream_sequence + 1
    local topic = STREAM_TOPIC .. ":" .. tostring(stream_sequence)
    local stream_ch = process.listen(topic)
    local done_ch = channel.new(1)

    coroutine.spawn(function()
        local response, err = runner:step(conversation, {
            stream_target = {
                reply_to = process.pid(),
                topic = topic,
            },
        })
        done_ch:send({ response = response, err = err })
    end)

    local full_text = ""
    local response_result = nil
    local stream_done = false

    local function finish(text, response, err)
        process.unlisten(stream_ch)
        return text, response, err
    end

    while true do
        local result = channel.select({
            stream_ch:case_receive(),
            done_ch:case_receive(),
        })
        if not result.ok then break end

        if result.channel == done_ch then
            response_result = result.value
        else
            local chunk = result.value
            if chunk.type == "chunk" then
                io.write(chunk.content or "")
                full_text = full_text .. (chunk.content or "")
            elseif chunk.type == "done" then
                stream_done = true
            elseif chunk.type == "error" then
                return finish(nil, nil, chunk.error and chunk.error.message or "stream error")
            end
        end

        if response_result and response_result.err then
            return finish(full_text, response_result.response, response_result.err)
        end

        if response_result and stream_done then
            return finish(full_text, response_result.response, response_result.err)
        end
    end

    return finish(full_text, nil, nil)
end

local function main()
    io.print("Chat (type 'quit' to exit)")
    io.print("")

    local ctx = agent_context.new()
    local runner, err = ctx:load_agent("app:assistant")
    if err then
        io.print("Failed to load agent: " .. tostring(err))
        return
    end

    local conversation = prompt.new()
    while true do
        io.write("> ")
        io.flush()
        local input = io.readline()
        if not input or input == "quit" or input == "exit" then break end
        if input == "" then goto continue end

        conversation:add_user(input)

        local text, _, gen_err = stream_response(runner, conversation)
        if gen_err then
            io.print("Error: " .. tostring(gen_err))
            goto continue
        end

        io.print("")
        if text and text ~= "" then
            conversation:add_assistant(text)
        end

        ::continue::
    end

    io.print("Bye!")
end

return { main = main }
```

Key patterns:

- `coroutine.spawn` runs `runner:step()` separately so the main coroutine can process stream chunks.
- `channel.select` waits on both the stream channel and completion channel.
- Each turn uses a unique topic and removes its listener after both the runner and
  that turn's stream report completion.
- The process accumulates streamed text for the conversation history.

Run the streaming phase with the same command:

```bash
wippy run chat
```



### Phase 5: Tools


Give the agent tools it can call to access external capabilities.



#### Define Tools


Create `src/tools/_index.yaml`:

```yaml
version: "1.0"
namespace: app.tools

entries:
  - name: current_time
    kind: function.lua
    meta:
      type: tool
      title: Current Time
      input_schema: |
        { "type": "object", "properties": {}, "additionalProperties": false }
      llm_alias: get_current_time
      llm_description: Get the current date and time in UTC.
    source: file://current_time.lua
    modules: [time]
    method: handler

  - name: calculate
    kind: function.lua
    meta:
      type: tool
      title: Calculate
      input_schema: |
        {
          "type": "object",
          "properties": {
            "expression": {
              "type": "string",
              "description": "Math expression to evaluate"
            }
          },
          "required": ["expression"],
          "additionalProperties": false
        }
      llm_alias: calculate
      llm_description: Evaluate a mathematical expression and return the result.
    source: file://calculate.lua
    modules: [expr]
    method: handler
```

Tool metadata describes the callable interface to the LLM:

- `input_schema` defines the arguments with JSON Schema.
- `llm_alias` is the function name presented to the LLM.
- `llm_description` explains when to use the tool.



#### Implement Tools


Create `src/tools/current_time.lua`:

```lua
local time = require("time")

local function handler()
    local now = time.now()
    return {
        utc = now:format("2006-01-02T15:04:05Z"),
        unix = now:unix(),
    }
end

return { handler = handler }
```

Create `src/tools/calculate.lua`:

```lua
local expr = require("expr")

local function handler(args)
    local result, err = expr.eval(args.expression)
    if err then
        return { error = tostring(err) }
    end
    return { result = result }
end

return { handler = handler }
```



#### Register Tools with the Agent


Update the agent entry in `src/_index.yaml` to reference the tools:

```yaml
  - name: assistant
    kind: registry.entry
    meta:
      type: agent.gen1
      name: assistant
      title: Assistant
      comment: Terminal chat agent
    prompt: |
      You are a helpful terminal assistant. Be concise and direct.
      Answer questions clearly. If you don't know something, say so.
      Use tools when they help answer the question.
      Do not use emoji in responses.
    model: gpt-4o-mini
    max_tokens: 1024
    temperature: 0.7
    tools:
      - app.tools:current_time
      - app.tools:calculate
```



#### Add Tool Execution


Update the chat process modules to include `json` and `funcs`:

```yaml
    modules:
      - io
      - json
      - funcs
```

Update `src/chat.lua` with tool execution:

```lua
local io = require("io")
local json = require("json")
local funcs = require("funcs")
local prompt = require("prompt")
local agent_context = require("agent_context")

local STREAM_TOPIC = "stream"
local stream_sequence = 0

local function stream_response(runner, conversation)
    stream_sequence = stream_sequence + 1
    local topic = STREAM_TOPIC .. ":" .. tostring(stream_sequence)
    local stream_ch = process.listen(topic)
    local done_ch = channel.new(1)

    coroutine.spawn(function()
        local response, err = runner:step(conversation, {
            stream_target = {
                reply_to = process.pid(),
                topic = topic,
            },
        })
        done_ch:send({ response = response, err = err })
    end)

    local full_text = ""
    local response_result = nil
    local stream_done = false

    local function finish(text, response, err)
        process.unlisten(stream_ch)
        return text, response, err
    end

    while true do
        local result = channel.select({
            stream_ch:case_receive(),
            done_ch:case_receive(),
        })
        if not result.ok then break end

        if result.channel == done_ch then
            response_result = result.value
        else
            local chunk = result.value
            if chunk.type == "chunk" then
                io.write(chunk.content or "")
                full_text = full_text .. (chunk.content or "")
            elseif chunk.type == "done" then
                stream_done = true
            elseif chunk.type == "error" then
                return finish(nil, nil, chunk.error and chunk.error.message or "stream error")
            end
        end

        if response_result and response_result.err then
            return finish(full_text, response_result.response, response_result.err)
        end

        if response_result and stream_done then
            return finish(full_text, response_result.response, response_result.err)
        end
    end

    return finish(full_text, nil, nil)
end

local function execute_tools(tool_calls)
    local results = {}
    for _, tc in ipairs(tool_calls) do
        local args = tc.arguments
        if type(args) == "string" then
            args = json.decode(args) or {}
        end

        io.write("[" .. tc.name .. "] ")
        io.flush()

        local result, err = funcs.call(tc.registry_id, args)
        if err then
            results[tc.id] = { error = tostring(err) }
            io.print("error")
        else
            results[tc.id] = result
            io.print("done")
        end
    end
    return results
end

local function run_turn(runner, conversation)
    while true do
        local text, response, err = stream_response(runner, conversation)
        if err then
            io.print("")
            return nil, err
        end

        if text and text ~= "" then
            io.print("")
        end

        local tool_calls = response and response.tool_calls
        if not tool_calls or #tool_calls == 0 then
            return text, nil
        end

        if text and text ~= "" then
            conversation:add_assistant(text)
        end

        local results = execute_tools(tool_calls)

        for _, tc in ipairs(tool_calls) do
            local result = results[tc.id]
            local result_str = json.encode(result) or "{}"
            conversation:add_function_call(tc.name, tc.arguments, tc.id)
            conversation:add_function_result(tc.name, result_str, tc.id)
        end
    end
end

local function main()
    io.print("Terminal Agent (type 'quit' to exit)")
    io.print("")

    local ctx = agent_context.new()
    local runner, err = ctx:load_agent("app:assistant")
    if err then
        io.print("Failed to load agent: " .. tostring(err))
        return
    end

    local conversation = prompt.new()
    while true do
        io.write("> ")
        io.flush()
        local input = io.readline()
        if not input or input == "quit" or input == "exit" then break end
        if input == "" then goto continue end

        conversation:add_user(input)

        local text, gen_err = run_turn(runner, conversation)
        if gen_err then
            io.print("Error: " .. tostring(gen_err))
            goto continue
        end
        if text and text ~= "" then
            conversation:add_assistant(text)
        end

        ::continue::
    end

    io.print("Bye!")
end

return { main = main }
```

The tool-execution loop:

1. Call `runner:step()` with streaming.
2. If the response contains `tool_calls`, execute each tool with `funcs.call()`.
3. Add the tool calls and results to the conversation.
4. Call the runner again so it can incorporate the results.
5. Return the final text when the response contains no more tool calls.



#### Run the Agent


```bash
wippy update
wippy install
wippy run chat
```

```
Terminal Agent (type 'quit' to exit)

> what time is it?
[get_current_time] done
The current time is 17:20 UTC on February 12, 2026.
> what is 125 * 16?
[calculate] done
125 * 16 = 2000.
> quit
Bye!
```



### Completeness and Limits


- The page contains every authored Lua file and registry entry needed by the five
  phases. `wippy.lock` and installed modules are generated by the commands above.
- Model output, token usage, tool-choice order, and wording are provider-dependent;
  the displayed interaction is illustrative rather than an assertion of exact text.
- The calculator is intentionally a small arithmetic parser, not a general expression
  evaluator. Treat every real tool as an authority boundary and attach narrow security
  policies before exposing side effects.



### Next Steps


- [LLM Module](framework/llm.md) — LLM API reference
- [Agent Module](framework/agents.md) — Agent framework reference
- [CLI Applications](tutorials/cli.md) — Terminal I/O patterns
- [Processes](tutorials/processes.md) — Process model and communication



---

# "Micro AGI"

## Micro AGI


Study an agent that reads documentation, generates Lua tools, registers them at runtime, and loads them into its active session.

**Classification: reference implementation walkthrough.** The snippets explain the
published `wippy/micro-agi` module but are intentionally not a complete source tree.
Run the Hub module to exercise the implementation; use the LLM Agent tutorial when
you need a self-contained build.



### What the Package Demonstrates


A terminal agent that:

- Streams answers from an LLM.
- Searches Wippy documentation for APIs.
- Inspects the registry for existing capabilities.
- Creates and loads tools when a capability is missing.
- Compresses conversation history when it approaches the context limit.

```mermaid
flowchart LR
    User -->|prompt| Agent
    Agent -->|step| LLM[Configured model]
    LLM -->|tool_calls| Agent
    Agent -->|funcs.call| Tools
    Tools -->|result| Agent
    Agent -->|text| User

    subgraph Tools
        doc_search
        registry_list
        registry_read
        create_tool
        load_tool
    end
```



### Architecture


The agent runs as a Wippy process with access to the registry. When the LLM decides it needs a capability it doesn't have, it uses the self-modification loop:

```mermaid
sequenceDiagram
    participant U as User
    participant A as Agent
    participant L as LLM
    participant R as Registry

    U->>A: "what time is it?"
    A->>L: step(conversation)
    L->>A: tool_call: doc_search("lua/core/time")
    A->>A: execute doc_search
    A->>L: step(conversation + tool result)
    L->>A: tool_call: create_tool(name, source, schema)
    A->>R: apply namespace denylist + changeset create
    R->>A: ok
    A->>L: step(conversation + tool result)
    L->>A: tool_call: load_tool("app.generated:current_time")
    A->>A: ctx:add_tools() + reload agent
    A->>L: step(conversation + tool result)
    L->>A: tool_call: current_time()
    A->>A: execute new tool
    A->>L: step(conversation + tool result)
    L->>A: text: "The current time is..."
    A->>U: stream response
```

Tools are registry entries. To create one, the agent writes a `function.lua` entry with inline Lua source in `data.source`; the runtime then compiles and loads that entry.



### Published Package Structure


The package owns all of these files. This page reproduces `doc_search.lua` and the
contracts that matter to the architecture, but abbreviates the registry helpers,
changeset plumbing, dynamic-loader helpers, and the agent loop. In particular, the
`create_tool`, `load_tool`, and `agent.lua` sections are excerpts, not files that can
be copied verbatim. The complete registry definitions for `registry_list` and
`registry_read` also remain in the published module.

```
micro-agi/
├── .wippy.yaml
├── wippy.lock
└── src/
    ├── _index.yaml
    ├── README.md
    ├── agent.lua
    └── tools/
        ├── _index.yaml
        ├── doc_search.lua
        ├── registry_list.lua
        ├── registry_read.lua
        ├── create_tool.lua
        └── load_tool.lua
```



### Infrastructure


The package uses this `.wippy.yaml` configuration:

```yaml
version: "1.0"

logger:
  encoding: console
```



### Entry Definitions


The following selected `src/_index.yaml` entries show the infrastructure, security
policies, models, agent, and process:

```yaml
version: "1.0"
namespace: app

entries:
  - name: definition
    kind: ns.definition
    readme: file://README.md
    meta:
      title: Micro AGI
      description: Self-modifying development agent that builds its own tools at runtime
      depends_on: [wippy/llm, wippy/agent]

  - name: os_env
    kind: env.storage.os

  - name: processes
    kind: process.host
    lifecycle:
      auto_start: true

  - name: __dep.llm
    kind: ns.dependency
    component: wippy/llm
    version: "*"
    parameters:
      - name: env_storage
        value: app:os_env
      - name: process_host
        value: app:processes

  - name: __dep.agent
    kind: ns.dependency
    component: wippy/agent
    version: "*"
    parameters:
      - name: process_host
        value: app:processes

  - name: __dep.security
    kind: ns.dependency
    component: wippy/security
    version: "*"
```

`wippy/security` provides the `wippy.security:process` policy group that the LLM module's background services run under; without it they fail to start.



#### Security Policies


Two `security.policy` entries form an application-level namespace denylist:

```yaml
  - name: deny_core_ns
    kind: security.policy
    policy:
      actions: "*"
      resources: "app:*"
      effect: deny
    groups:
      - agent_security

  - name: deny_tools_ns
    kind: security.policy
    policy:
      actions: "*"
      resources: "app.tools:*"
      effect: deny
    groups:
      - agent_security
```

These policies are loaded as a named scope (`app:agent_security`) by
`create_tool`. The helper rejects an explicit `deny` for `app:*` (core entries,
models, and the agent definition) or `app.tools:*` (built-in tools), but treats
the unmatched `undefined` result for `app.generated:*` as passing its bespoke
filter. This is not Wippy runtime authorization: guarded operations require an
explicit `allow` from the execution context, including the security-module
operations shown below and `registry.apply` inside `changes:apply()`.

A third policy grants the process itself access to the registry. A process launched without a security context is denied every registry read, so the `agent` command carries this policy as its own scope:

```yaml
  - name: agent_policy
    kind: security.policy
    policy:
      actions: "*"
      resources: "*"
      effect: allow
```

See [Security Model](system/security.md) for details on policy evaluation.



#### Models


Two models serve different purposes:

```yaml
  - name: gpt-5.1
    kind: registry.entry
    meta:
      name: gpt-5.1
      type: llm.model
      title: GPT-5.1
      comment: Reasoning model
      capabilities: [generate, tool_use, structured_output, vision, thinking]
      class: [reasoning]
      priority: 210
    max_tokens: 400000
    output_tokens: 128000
    pricing:
      input: 1.25
      output: 10
    providers:
      - id: wippy.llm.openai:provider
        options:
          reasoning_model_request: true
        provider_model: gpt-5.1

  - name: gpt-4.1-nano
    kind: registry.entry
    meta:
      name: gpt-4.1-nano
      type: llm.model
      title: GPT-4.1 Nano
      comment: Compression model
      capabilities: [generate, tool_use, structured_output]
      class: [fast]
      priority: 100
    max_tokens: 1047576
    output_tokens: 32768
    pricing:
      input: 0.1
      output: 0.4
    providers:
      - id: wippy.llm.openai:provider
        provider_model: gpt-4.1-nano
```

GPT-5.1 handles reasoning and tool use. GPT-4.1 Nano handles context compression.



#### Agent Definition


```yaml
  - name: dev_assistant
    kind: registry.entry
    meta:
      type: agent.gen1
      name: dev_assistant
      title: Dev Assistant
      comment: Wippy development assistant
    prompt: |
      Self-modifying Wippy development agent. You run inside Wippy runtime
      with access to docs, registry, and dynamic tool creation.

      Rules:
      - NEVER fabricate, guess, or hallucinate facts. If you need real data,
        use or build a tool to get it. Only state what a tool actually returned.
      - Maximum 2-3 sentences per response. No bullet lists. No disclaimers.
      - Never say "I can't" or "I don't have". Build the tool and do it.
      - Act first, explain only if asked.

      To gain new capabilities: doc_search the API, create_tool with Lua source,
      load_tool, call it. All in one turn.
    model: gpt-5.1
    thinking_effort: 10
    max_tokens: 2048
    tools:
      - "app.tools:*"
```

The prompt gives the agent three operating rules:

- **Use retrieved data** — use tools for external facts.
- **Create missing capabilities** — build a tool when an allowed capability is absent.
- **Prioritize actions** — perform the requested operation before explaining it.



#### Process


```yaml
  - name: agent
    kind: process.lua
    meta:
      command:
        name: agent
        short: Start dev assistant
        security:
          actor:
            id: app:agent
          policies:
            - app:agent_policy
    source: file://agent.lua
    method: main
    modules: [io, json, funcs, registry, time, security]
    imports:
      prompt: wippy.llm:prompt
      agent_context: wippy.agent:context
      compress: wippy.llm.util:compress
```

The process runs as a terminal command. `meta.command.security` gives it the actor and scope it runs under — without it `registry.get` fails with `not allowed to access entry` and the agent never loads. Security enforcement for writes happens inside `create_tool`, which loads the `agent_security` policy group and evaluates it before writing.

Imports:

- `prompt` — Conversation builder
- `agent_context` — Agent loading and dynamic tool management
- `compress` — LLM-based text compression for context management



### Tools


Create `src/tools/_index.yaml` with five tools:



#### doc_search


Fetches Wippy documentation via the `wippy.ai/llm` API. Supports two modes: fetch a page by path, or search by query.

```lua
local http_client = require("http_client")
local json = require("json")

local BASE_URL = "https://wippy.ai/llm"
local MAX_CHARS = 8000

local function fetch_page(path)
    local url = BASE_URL .. "/path/en/" .. path
    local resp, err = http_client.get(url, {
        headers = { ["User-Agent"] = "wippy-agent/1.0" },
    })
    if err then
        return nil, tostring(err)
    end
    if resp.status_code ~= 200 then
        return nil, "HTTP " .. resp.status_code
    end

    local body = resp.body or ""
    if #body > MAX_CHARS then
        body = body:sub(1, MAX_CHARS) .. "\n... (truncated)"
    end
    return body, nil
end

local function search_docs(query)
    local url = BASE_URL .. "/search?q=" .. http_client.encode_uri(query)
    local resp, err = http_client.get(url, {
        headers = { ["User-Agent"] = "wippy-agent/1.0" },
    })
    if err then
        return { error = tostring(err) }
    end
    if resp.status_code ~= 200 then
        return { error = "HTTP " .. resp.status_code }
    end

    local body = resp.body or ""
    if #body > MAX_CHARS then
        body = body:sub(1, MAX_CHARS) .. "\n... (truncated)"
    end

    return { results = body }
end

local function handler(input)
    if input.path then
        local content, err = fetch_page(input.path)
        if err then
            return { error = err }
        end
        return { path = input.path, content = content }
    end

    if input.query then
        return search_docs(input.query)
    end

    return { error = "provide either 'path' or 'query'" }
end

return { handler = handler }
```



#### create_tool


This tool evaluates the package's namespace denylist and creates a
`function.lua` registry entry with inline Lua source.

The `modules` field on the generated entry controls which non-ambient runtime modules the
tool can require. The `process` module is ambient for every executable Lua entry, so
omitting it is not a security boundary; process operations still rely on runtime security
policies.

```lua
local registry = require("registry")
local json = require("json")
local security = require("security")

local NAMESPACE = "app.generated"
local MAX_SOURCE_LEN = 16000
local MAX_NAME_LEN = 64

local ALLOWED_MODULES = {
    time = true, json = true, http_client = true, expr = true,
    text = true, base64 = true, yaml = true, crypto = true,
    hash = true, uuid = true,
}
```

**Denylist evaluation** — `create_tool` loads the `agent_security` named scope.
Writes to `app:*` or `app.tools:*` are rejected when the scope returns `deny`;
an unmatched `app.generated:*` target returns `undefined` and passes this
application filter:

```lua
local actor = security.new_actor("service:agent", { role = "agent" })
local scope, scope_err = security.named_scope("app:agent_security")
if scope_err then
    return { error = "failed to load security scope: " .. tostring(scope_err) }
end

local result = scope:evaluate(actor, action, id)
if result == "deny" then
    return { error = "policy denied: " .. action .. " on " .. id }
end
```

This check does not authorize the registry mutation. The current command also
needs a runtime actor and scope that explicitly allow the security-module calls
and `registry.apply`.

**Registry write** — the entry is written with source in `data.source` and only the allowed modules:

```lua
local entry = {
    id = id,
    kind = "function.lua",
    meta = {
        type = "tool",
        title = input.name,
        comment = input.description,
        input_schema = schema,
        llm_alias = input.name,
        llm_description = input.description,
    },
    data = {
        source = input.source,
        modules = modules,
        method = "handler",
    },
}

local snap = registry.snapshot()
local changes = snap:changes()
if existing then
    changes:update(entry)
else
    changes:create(entry)
end
local _, apply_err = changes:apply()
if apply_err then
    return { error = "failed to apply registry change: " .. tostring(apply_err) }
end
```

The generated tool is stored in the registry rather than written to a source file.



#### load_tool


Validates the entry is a tool and signals the agent loop to reload:

```lua
local function handler(input)
    local entry, err = registry.get(input.id)
    if err then
        return { error = tostring(err) }
    end
    if not entry then
        return { error = "not found: " .. input.id }
    end
    if not entry.meta or entry.meta.type ~= "tool" then
        return { error = "not a tool (meta.type != 'tool'): " .. input.id }
    end

    return {
        loaded = true,
        id = entry.id,
        alias = entry.meta.llm_alias or input.id,
        description = entry.meta.llm_description or "",
    }
end
```

The agent loop detects `loaded = true` in the result and calls `ctx:add_tools(id)` followed by `ctx:load_agent()` to recompile the agent with the new tool.



### Agent Loop


The agent loop in `src/agent.lua` handles streaming, tool execution, dynamic loading, and context compression.



#### Streaming


Uses the same coroutine + channel pattern from the [LLM Agent tutorial](tutorials/llm-agent.md):

```lua
coroutine.spawn(function()
    local response, err = session.runner:step(session.conversation, {
        stream_target = {
            reply_to = process.pid(),
            topic = STREAM_TOPIC,
        },
    })
    done_ch:send({ response = response, err = err })
end)
```



#### Tool Execution


Tools are called via `funcs.call()`. `pcall` catches raised Lua errors, while the normal
second return from `funcs.call()` carries invocation errors:

```lua
local ok, result, call_err = pcall(funcs.call, tc.registry_id, args)
if not ok then
    results[tc.id] = { error = tostring(result) }
elseif call_err then
    results[tc.id] = { error = tostring(call_err) }
else
    results[tc.id] = result
end
```



#### Dynamic Tool Loading


When `load_tool` returns `loaded = true`, the agent reloads itself:

```mermaid
flowchart TD
    A[load_tool returns loaded=true] --> B[ctx:add_tools id]
    B --> C[ctx:load_agent]
    C --> D[New runner with added tool]
    D --> E[Conversation preserved]
    E --> F[Next LLM step sees new tool]
```

```lua
local function handle_tool_loading(tool_calls, results)
    local reload_needed = false
    for _, tc in ipairs(tool_calls) do
        if tc.name == "load_tool" then
            local result = results[tc.id]
            if result and result.loaded then
                session.ctx:add_tools(result.id)
                reload_needed = true
            end
        end
    end
    if reload_needed then
        reload_agent()
    end
end
```

The conversation is preserved across reloads because it lives in the prompt builder, not in the runner.



#### Context Compression


When prompt tokens exceed 300K (75% of the 400K context window), the conversation is compressed using GPT-4.1 Nano:

```lua
if response.tokens and response.tokens.prompt_tokens
    and response.tokens.prompt_tokens > PROMPT_TOKEN_LIMIT then
    try_compress()
end
```

Compression extracts message content, calls `compress.to_size()` targeting 4000 characters, and replaces the conversation with a summary:

```lua
local summary, compress_err = compress.to_size(COMPRESS_MODEL, full_text, COMPRESS_TARGET)
if compress_err then
    return nil, compress_err
end
session.conversation = prompt.new()
session.conversation:add_system("Conversation summary:\n\n" .. summary)
```



### Security Model


An application denylist and module-level access controls constrain generated
tools, but they do not replace runtime authorization.

```mermaid
flowchart TD
    LLM[LLM generates tool] --> P{Application Namespace Denylist}
    P -->|scope:evaluate| Check{Target namespace?}
    Check -->|app.generated:*| OK[No deny match]
    Check -->|app:* or app.tools:*| Deny[Policy Denied]

    OK --> M{Non-ambient Module Allowlist}
    M -->|only listed non-ambient modules| R[Registry write]
    M -->|unknown module requested| Err[Rejected]
    R --> A[Ambient process API remains available]
```



#### Namespace Denylist


| Policy | Resources | Effect |
|--------|-----------|--------|
| `deny_core_ns` | `app:*` | deny |
| `deny_tools_ns` | `app.tools:*` | deny |

`create_tool` loads the `agent_security` policy group and evaluates the target
entry ID. It deliberately treats `undefined` as "not denied" for this
application-level filter. Wippy's guarded authorization does not: it permits an
operation only on explicit `allow`. The context that runs this code must still
carry the required runtime permissions.

This prevents the agent from:
- Modifying its own prompt or agent definition (`app:dev_assistant`)
- Overwriting its built-in tools (`app.tools:*`)
- Changing infrastructure entries (`app:processes`, etc.)



#### Module Access Control


Generated tools declare non-ambient capabilities in `data.modules`, and `create_tool`
accepts only names from `ALLOWED_MODULES`. An undeclared non-ambient module cannot be
required. The runtime still injects `process` into every executable Lua entry, including a
generated tool, so process operations must be constrained with security policies rather
than by omitting `process` from `data.modules`.

This tutorial does not define policies for `process.spawn` or `process.exec`. Its generated
tools are therefore not a complete sandbox: add runtime policies for ambient process
operations before allowing untrusted tool source.



### Run and Current Package Limitation


The published artifact is the Hub module. Start in a fresh empty directory that
does not contain `wippy.lock`; Hub bootstrap rejects an unrelated or multi-root
lock. The first run creates the deployment lock, and later runs from the same
directory reuse that matching lock.

```bash
mkdir micro-agi-deploy
cd micro-agi-deploy
wippy run wippy/micro-agi agent
```

The command downloads the selected module version, resolves its declared
dependencies, and invokes its `agent` command.

It still requires the provider credentials and model configuration expected by
that module, plus registry/network access for Hub download and documentation
search. This page does not provide a local clone or lockfile, so it does not
claim a reproducible source build.

At the reviewed release, `wippy/micro-agi` v0.3.1 declares no
`meta.command.security` context for `agent`. With default strict mode, the
guarded tool paths—including `funcs.call`, registry reads and writes, and the
documentation search HTTP request—do not receive the explicit allows they
require. The tool and self-modification flows above are therefore reference
designs, not successful default-strict-mode runs. Do not disable strict mode to
make an untrusted code generator work; the package should first add a least-
privilege command scope for its required actions.



### Next Steps


- [LLM Agent](tutorials/llm-agent.md) — Build a basic agent from scratch
- [Agent Module](framework/agents.md) — Agent framework reference
- [Registry](concepts/registry.md) — Registry concepts
- [Security Model](system/security.md) — Declarative security policies
- [Entry Kinds](guides/entry-kinds.md) — Available entry types



---

# "Keeper over MCP"

## Keeper over MCP


Wippy Keeper is the control plane for a running Wippy app — a registry workbench,
filesystem↔registry governance, agent/task orchestration, Hub install, knowledge base,
logs and process inspection, and a Git review/push flow, all behind a built-in UI. Its
defining feature is that it exposes those operator capabilities to AI clients (Claude,
Codex, …) over **MCP (Model Context Protocol)**. This page adds Keeper to an app and
connects an MCP client to it.



### What You'll Build


1. Keeper added to an app scaffolded from `app-template`.
2. The Keeper UI at `/app/keeper` and the MCP endpoint at `/keeper-mcp/`.
3. A scoped MCP token, and an MCP client configured to drive the app through Keeper.



### Prerequisites


- An app from [app-template](https://github.com/wippyai/app-template). It already
  provides everything Keeper binds to: `app:gateway`, `app:api`, `app:db`,
  `app:processes`, `app.security:admin`, and `app.env:store`.
- The Keeper module installed:

  ```bash
  wippy add keeper/keeper
  wippy install
  ```



### Add Keeper


Declare the dependency and bind it to the app's resources. Only `admin_scope` is
required (no default); the rest default to the names `app-template` already uses, shown
here explicitly for clarity:

```yaml


## src/app/deps/_index.yaml

- name: keeper
  kind: ns.dependency
  component: keeper/keeper
  version: '>=v0.5.18'
  parameters:
    - { name: app_db,         value: app:db }
    - { name: admin_scope,    value: app.security:admin }
    - { name: env_storage,    value: app.env:store }
    - { name: public_gateway, value: app:gateway }   # hosts /keeper-mcp/
    - { name: mcp_route,      value: /keeper-mcp/ }
    - { name: ui_server,      value: app:gateway }
    - { name: process_host,   value: app:processes }
```

Start the app:

```bash
wippy run
```

Keeper auto-mounts three surfaces:

- **UI** — `/app/keeper`
- **MCP transport** — `/keeper-mcp/` on the public gateway
- **Token API** — on `app:api` (`/keeper/mcp/tokens`, `/keeper/mcp/scopes`)

The MCP transport is gated by the `MCP_ENABLED` environment variable (default `true`);
set it to `false` to close the endpoint.



### Mint an MCP Token


Tokens are issued by an admin user, scoped, and shown exactly once. Create one via the
token API (or the MCP page in the Keeper UI):

```bash
curl -X POST http://localhost:8080/api/v1/keeper/mcp/tokens \
  -H 'Authorization: Bearer <admin-session-token>' \
  -H 'Content-Type: application/json' \
  -d '{"label": "claude-dev", "preset": "developer"}'


## -> { "success": true, "token": { "token": "wkmcp_<64 hex>", ... } }

```

`preset` bundles a set of scopes. Available presets: `root`, `developer`,
`wippy_operator`, `observer`, `knowledge_manager`, `explorer_tools_only`. For
finer control, pass an explicit `scopes` array instead (e.g. `registry.read`,
`state.write`, `git.pr`, `tasks.run`, `knowledge.read`). The raw `wkmcp_...` token is
returned once and stored only as a hash — copy it immediately.



### Connect a Client


Point an MCP client at the endpoint with the token as a bearer header. For Claude Code /
Codex, an `.mcp.json` in the project root:

```json
{
  "mcpServers": {
    "keeper": {
      "type": "http",
      "url": "http://localhost:8080/keeper-mcp/",
      "headers": { "Authorization": "Bearer wkmcp_<token>" }
    }
  }
}
```

Use the app's public base URL in place of `http://localhost:8080` in a deployed
environment.



### How the MCP Surface Works


Keeper does not expose a flat, fixed tool list. It presents a few **meta-tools** plus
**traits** that activate concrete tools on demand, so the surface stays small until you
opt into a capability:

- `session_info` — always available; reports the session's scopes and active traits.
- `list_traits` / `describe_trait` — discover what's available.
- `use_trait` / `drop_trait` (and `set_traits`) — activate or remove a trait; this emits
  an MCP `notifications/tools/list_changed`, so the visible tools change live.
- `list_tools` — enumerate the tools a trait materialized, with their schemas.
- `call_tool` — invoke any registry tool by id; visible only to a token holding
  `mcp.root`.

What a token can activate is bounded by its **scopes** — roughly `registry.*`,
`state.*`, `hub.*`, `knowledge.*`, `git.*`, `components.*`, `tasks.*`, `agents.*`,
`tests.run`, `logger.*`, `env.*`, `functions.call`, `app.ui` (plus `mcp.root` for full
admin bypass). The token's `access_mode` (`any` / `traits` / `tools_only`) further
constrains how it may call tools.



### Notes


- **Governance scope** — set `GOV_MANAGED_NAMESPACES=app` so Keeper's
  filesystem↔registry sync only governs your app's namespace. Do not add `keeper`,
  `wippy`, or `userspace` unless you are developing those modules.
- **Security** — tokens are bound to the issuing admin identity and a scope set, stored
  as SHA-256, and revocable via `POST /keeper/mcp/tokens/revoke`. The `/keeper-mcp/`
  route runs no auth middleware; the handler enforces the bearer token itself.
- **Reference app** — `app-keeper` is the worked example that wires Keeper into an app
  shell; copy its `src/app/deps/_index.yaml` block if you want a known-good setup.



### Next Steps


- [Hello World](tutorials/hello-world.md) — the minimal project layout
- [Authentication](tutorials/auth.md) — the admin identity that issues tokens
- [Agents](framework/agents.md) — the agents and tools Keeper traits expose



---

# "Dataflow: Local Knowledge Base"

## Dataflow: Local Knowledge Base


Build a knowledge base on your own machine — create the vector store, then chunk and
ingest documents into it. This is the data-creation companion to the
[RAG tutorial](tutorials/rag.md): here you stand up and fill a local KB; there you
retrieve from it and generate answers. Both use the `wippy/embeddings` module backed by
a local SQLite vector store.



### What You'll Build


1. A local app whose database holds a 512-dimension vector store.
2. The migration that creates the `embeddings_512` table on startup.
3. An ingest function that chunks markdown and writes embeddings into the store.



### Prerequisites


- A Wippy project (clone [app-template](https://github.com/wippyai/app-template), or
  `wippy init`).
- An LLM provider with an embedding model configured (e.g. `text-embedding-3-small`) —
  see [LLM Framework](framework/llm.md). The vector store is created locally without it,
  but ingesting (which calls `llm.embed`) needs a configured provider.

Install the dependencies:

```bash
wippy add wippy/embeddings
wippy add wippy/migration
wippy add wippy/bootloader
wippy add wippy/security
wippy add wippy/llm
wippy install
```



### Create the Store


The KB lives in a local SQLite database. `wippy/embeddings` ships a migration that
creates the vector table; the bootloader runs it at startup. Wire the pieces together:

```yaml


## src/_index.yaml

version: "1.0"
namespace: app

entries:
  - name: db
    kind: db.sql.sqlite
    file: ./data/app.db
    lifecycle:
      auto_start: true

  - name: processes
    kind: process.host
    host:
      workers: 8

  - name: embeddings
    kind: ns.dependency
    component: wippy/embeddings
    version: "*"
    parameters:
      - name: target_db
        value: app:db

  - name: migration
    kind: ns.dependency
    component: wippy/migration
    version: "*"
    parameters:
      - name: app_db
        value: app:db

  - name: bootloader
    kind: ns.dependency
    component: wippy/bootloader
    version: "*"
    parameters:
      - name: application_host
        value: app:processes
      - name: app_db
        value: app:db
      - name: env_storage
        value: app.env:store

  - name: security
    kind: ns.dependency
    component: wippy/security
    version: "*"

  - name: process_access
    kind: security.policy
    groups:
      - wippy.security:process
    policy:
      resources: '*'
      actions: '*'
      effect: allow
```

The bootloader and the provider services run under the `wippy.security:process`
policy group, so `wippy/security` and a policy in that group are part of the wiring.

The bootloader needs an environment store; add the standard one in its own namespace:

```yaml


## src/env/_index.yaml

version: "1.0"
namespace: app.env

entries:
  - name: file
    kind: env.storage.file
    auto_create: true
    file_path: .env
    lifecycle:
      auto_start: true

  - name: os
    kind: env.storage.os
    lifecycle:
      auto_start: true

  - name: store
    kind: env.storage.router
    lifecycle:
      auto_start: true
    storages:
      - app.env:file
      - app.env:os
```

Create the data directory and start the app:

```bash
mkdir -p data
wippy run
```

On boot the migration runs and the store appears in `data/app.db`:

```
$ sqlite3 data/app.db ".tables"
_migrations            embeddings_512         embeddings_512_chunks
embeddings_512_info    embeddings_512_rowids  embeddings_512_vector_chunks00
...
```

`embeddings_512` is a SQLite `vec0` virtual table; the `embeddings_512_*` shadow tables
hold its chunks, row ids, and metadata. (On PostgreSQL the same migration uses
`pgvector` instead.)



### Ingest Documents


Ingestion is two steps: split text into chunks with the `text` module, then write them
with `embeddings.add_batch`, which embeds and persists each chunk.

```lua
-- src/ingest.lua
local text = require("text")
local embeddings = require("embeddings")

local function ingest(doc_id, title, markdown)
    local splitter, err = text.splitter.markdown({
        chunk_size = 800,
        chunk_overlap = 100,
        heading_hierarchy = true,
        code_blocks = true,
    })
    if err then return nil, err end

    local chunks, split_err = splitter:split_text(markdown)
    if split_err then return nil, split_err end

    local batch = {}
    for i, chunk in ipairs(chunks) do
        table.insert(batch, {
            content = chunk,
            content_type = "doc_chunk",
            origin_id = doc_id,
            context_id = tostring(i),
            meta = { title = title, chunk = i },
        })
    end

    return embeddings.add_batch(batch)
end

return { ingest = ingest }
```

Register the function:

```yaml
- name: ingest
  kind: function.lua
  source: file://ingest.lua
  method: ingest
  modules:
    - text
  imports:
    embeddings: wippy.embeddings:embeddings
```

Key points:

- `origin_id` groups all chunks from one source document — delete and re-ingest per
  document with `embedding_repo.delete_by_origin(doc_id)`.
- `content_type` lets you keep distinct corpora (`doc_chunk`, `faq`, `code_snippet`) in
  one store and filter at query time.
- `add_batch` auto-splits when the batch exceeds the 8000-token request limit.



### Verify the Contents


Once documents are ingested, confirm rows landed and run a similarity search:

```lua
local embeddings = require("embeddings")

local results, err = embeddings.search("how do I configure TLS?", {
    content_type = "doc_chunk",
    limit = 5,
})
-- results[i].content, .similarity, .meta, .origin_id, .context_id
```

From there, the [RAG tutorial](tutorials/rag.md) shows how to feed these results to an
LLM for grounded answers.



### Operational Notes


- **Chunk size**: `chunk_size` and `chunk_overlap` count characters, not tokens;
  2000–4000 characters is a good default. Use `chunk_overlap` (~10–20% of chunk size) so
  sentences aren't cut across boundaries.
- **Dimensions**: `text-embedding-3-small` at 512 dimensions is cost-efficient and
  matches the `embeddings_512` table. Larger vectors mean larger storage and slower
  search.
- **Local vs. shared**: SQLite (`vec0`) keeps the whole KB in one local file — ideal for
  development and single-node apps. Point `target_db` at a `db.sql.postgres` with
  `pgvector` for a shared, production store; the ingest code is unchanged.



### Next Steps


- [RAG](tutorials/rag.md) — retrieve from this store and generate grounded answers
- [LLM Framework](framework/llm.md) — `llm.embed`, embedding models, providers
- [Text Module](lua/text/text.md) — splitters and tokenization



---

# "Retrieval-Augmented Generation (RAG)"

## Retrieval-Augmented Generation (RAG)


Build a knowledge base that answers questions from your own documents. This tutorial uses the `wippy/embeddings` module for vector search and the LLM framework for generation.



### What You'll Build


A minimal RAG pipeline:

1. Ingest markdown documents — split into chunks, embed, persist.
2. Retrieve — vector search returns the most relevant chunks for a query.
3. Generate — an LLM call uses the retrieved chunks as grounding context.



### Prerequisites


- A database: `db.sql.sqlite` (includes `vec0` support) or `db.sql.postgres` with the `pgvector` extension.
- `OPENAI_API_KEY` in the environment — the embedding and generation calls go through it.

Create the project and install the modules:

```bash
mkdir rag && cd rag
mkdir -p src/app data
wippy init
wippy add wippy/embeddings
wippy add wippy/migration
wippy add wippy/bootloader
wippy add wippy/security
wippy install
```

```
rag/
├── wippy.lock
├── data/
└── src/
    ├── _index.yaml
    ├── env/
    │   └── _index.yaml
    └── app/
        ├── ingest.lua
        ├── answer.lua
        ├── answer_http.lua
        └── seed.lua
```



### Dependencies


Declare the `wippy/embeddings` dependency and point it at your database. The `target_db` parameter is the registry ID of the database entry the embeddings table will live in. `wippy/embeddings` pulls in `wippy/llm` and the migration that creates the `embeddings_512` table, so `wippy/migration` and `wippy/bootloader` need wiring too — the bootloader runs the migration at startup, and both it and the LLM module run processes under the `wippy.security:process` policy group shipped by `wippy/security`:

```yaml


## src/_index.yaml

version: "1.0"
namespace: app

entries:
  - name: db
    kind: db.sql.sqlite
    file: ./data/app.db
    lifecycle:
      auto_start: true

  - name: processes
    kind: process.host
    lifecycle:
      auto_start: true

  - name: embeddings
    kind: ns.dependency
    component: wippy/embeddings
    version: "*"
    parameters:
      - name: target_db
        value: app:db

  - name: migration
    kind: ns.dependency
    component: wippy/migration
    version: "*"
    parameters:
      - name: app_db
        value: app:db

  - name: bootloader
    kind: ns.dependency
    component: wippy/bootloader
    version: "*"
    parameters:
      - name: application_host
        value: app:processes
      - name: env_storage
        value: app.env:store

  - name: security
    kind: ns.dependency
    component: wippy/security
    version: "*"
```

The bootloader persists a generated `ENCRYPTION_KEY`, so it needs a writable environment store:

```yaml


## src/env/_index.yaml

version: "1.0"
namespace: app.env

entries:
  - name: file
    kind: env.storage.file
    auto_create: true
    file_path: .env
    lifecycle:
      auto_start: true

  - name: os
    kind: env.storage.os
    lifecycle:
      auto_start: true

  - name: store
    kind: env.storage.router
    lifecycle:
      auto_start: true
    storages:
      - app.env:file
      - app.env:os
```



### Models


`wippy/embeddings` calls `llm.embed` with `text-embedding-3-small`, and generation below uses `gpt-4o-mini`. Both are resolved from the registry, so declare them in `src/_index.yaml` as well:

```yaml
  - name: text-embedding-3-small
    kind: registry.entry
    meta:
      name: text-embedding-3-small
      type: llm.model
      title: Text Embedding 3 Small
      capabilities:
        - embed
    dimensions: 512
    max_tokens: 8191
    pricing:
      input: 0.02
      output: 0
    providers:
      - id: wippy.llm.openai:provider
        provider_model: text-embedding-3-small

  - name: gpt-4o-mini
    kind: registry.entry
    meta:
      name: gpt-4o-mini
      type: llm.model
      title: GPT-4o mini
      capabilities:
        - generate
    max_tokens: 128000
    output_tokens: 16384
    pricing:
      input: 0.15
      output: 0.6
    providers:
      - id: wippy.llm.openai:provider
        provider_model: gpt-4o-mini
```

The OpenAI provider reads `OPENAI_API_KEY` from the OS environment by default. See [LLM Framework](framework/llm.md) for other providers and model fields.



### Ingest Documents


Splitting is handled by the `text` module; embedding and persistence by the `embeddings` library.

```lua
-- src/app/ingest.lua
local text = require("text")
local embeddings = require("embeddings")

local function ingest(doc_id: string, title: string, markdown: string)
    local splitter, err = text.splitter.markdown({
        chunk_size = 800,
        chunk_overlap = 100,
        heading_hierarchy = true,
        code_blocks = true,
    })
    if err then return nil, err end

    local chunks, split_err = splitter:split_text(markdown)
    if split_err then return nil, split_err end

    local batch = {}
    for i, chunk in ipairs(chunks) do
        table.insert(batch, {
            content = chunk,
            content_type = "doc_chunk",
            origin_id = doc_id,
            context_id = tostring(i),
            meta = { title = title, chunk = i },
        })
    end

    return embeddings.add_batch(batch)
end

return { ingest = ingest }
```

Register the function and its imports:

```yaml
- name: ingest
  kind: function.lua
  source: file://app/ingest.lua
  method: ingest
  modules:
    - text
  imports:
    embeddings: wippy.embeddings:embeddings
```

Key points:

- `origin_id` groups chunks that belong to the same source document.
- `context_id` is an optional sub-key (section, page, chunk index).
- `add_batch` auto-splits if total tokens exceed the 8000-token request limit.



### Retrieve


Vector search returns the most similar chunks to the query, along with similarity scores:

```lua
local embeddings = require("embeddings")

local results, err = embeddings.search("how do I configure TLS?", {
    content_type = "doc_chunk",
    limit = 5,
})

-- results[i].content, .similarity, .meta, .origin_id, .context_id
```

Filter by origin when you want to ground the answer in a specific document:

```lua
local hits = embeddings.find_by_origin("refund policy", "doc-42", { limit = 3 })
```



### Generate an Answer


Compose the retrieved chunks into a prompt and call the LLM. Here the retrieved text is appended to the system prompt; the user's question becomes the user turn:

```lua
-- src/app/answer.lua
local embeddings = require("embeddings")
local llm = require("llm")
local prompt = require("prompt")

local SYSTEM = [[
Answer using only the provided context. If the context does not contain
the answer, say you don't know. Cite the chunk title for each claim.
]]

local function format_context(hits)
    local parts = {}
    for i, h in ipairs(hits) do
        local title = h.meta and h.meta.title or h.origin_id
        table.insert(parts,
            string.format("[%d] %s\n%s", i, title, h.content))
    end
    return table.concat(parts, "\n\n")
end

local function answer(question: string)
    local hits, err = embeddings.search(question, { limit = 4 })
    if err then return nil, err end

    local p = prompt.new()
    p:add_system(SYSTEM)
    p:add_system("Context:\n\n" .. format_context(hits))
    p:add_user(question)

    local response, gen_err = llm.generate(p, { model = "gpt-4o-mini" })
    if gen_err then return nil, gen_err end

    return {
        answer = response.result,
        sources = hits,
    }
end

return { answer = answer }
```

```yaml
- name: answer
  kind: function.lua
  source: file://app/answer.lua
  method: answer
  imports:
    embeddings: wippy.embeddings:embeddings
    llm: wippy.llm:llm
    prompt: wippy.llm:prompt
```



### End-to-End Example


Putting it together behind an HTTP endpoint. Append these entries to `src/_index.yaml`:

```yaml
  - name: ingest
    kind: function.lua
    source: file://app/ingest.lua
    method: ingest
    modules:
      - text
    imports:
      embeddings: wippy.embeddings:embeddings

  - name: answer
    kind: function.lua
    source: file://app/answer.lua
    method: answer
    imports:
      embeddings: wippy.embeddings:embeddings
      llm: wippy.llm:llm
      prompt: wippy.llm:prompt

  - name: seed
    kind: process.lua
    meta:
      command:
        name: seed
        short: Ingest the sample document
        security:
          groups:
            - wippy.security:process
    source: file://app/seed.lua
    method: main
    modules:
      - funcs
      - io

  - name: gateway
    kind: http.service
    addr: ":8080"
    lifecycle:
      auto_start: true
      security:
        actor:
          id: gateway
        groups:
          - wippy.security:process

  - name: api
    kind: http.router
    meta:
      server: app:gateway
    prefix: /api

  - name: ask
    kind: http.endpoint
    meta:
      router: app:api
    method: POST
    path: /ask
    func: app:answer_http

  - name: answer_http
    kind: function.lua
    source: file://app/answer_http.lua
    method: handler
    modules:
      - http
    imports:
      answer: app:answer
```

The server declares a security context because retrieval resolves the embedding model from the registry, and a request without an actor and scope reads no entries at all — model resolution then fails with `Model or class not found`.

```lua
-- src/app/answer_http.lua
local http = require("http")
local answer = require("answer")

local function handler()
    local req = http.request()
    local res = http.response()

    local body, err = req:body_json()
    if err or not body or not body.question then
        res:set_status(http.STATUS.BAD_REQUEST)
        res:write_json({ error = "question is required" })
        return
    end

    local result, ans_err = answer.answer(tostring(body.question))
    if ans_err then
        res:set_status(http.STATUS.INTERNAL_ERROR)
        res:write_json({ error = ans_err })
        return
    end

    res:write_json(result)
end

return { handler = handler }
```

Seed the index from a CLI command. `meta.command` makes the process runnable as `wippy run seed`, and its `security` block gives it the scope needed to call `app:ingest`:

```lua
-- src/app/seed.lua
local funcs = require("funcs")
local io = require("io")

local DOC = [[


## TLS Configuration


Wippy servers terminate TLS when the `tls` block is present on the
`http.service` entry. Set `cert_file` and `key_file` to PEM paths.



### Refund Policy


Refunds are issued within 14 days of purchase.
]]

local function main()
    local res, err = funcs.call("app:ingest", "doc-42", "Handbook", DOC)
    if err then
        io.print("ingest failed: " .. tostring(err))
        return
    end
    io.print("ingested " .. tostring(res.count) .. " chunks")
end

return { main = main }
```

The first `wippy run` creates `data/app.db` and applies the embeddings migration. Seed the index, then start the server and query it:

```bash
wippy run seed


## ingested 2 chunks


wippy run
```

```bash
curl -X POST http://localhost:8080/api/ask \
    -H 'Content-Type: application/json' \
    -d '{"question":"how do I configure TLS?"}'
```

```json
{
  "answer": "You can configure TLS by adding a `tls` block to the `http.service` entry. Set `cert_file` and `key_file` to the paths of your PEM files. (See: Handbook, TLS Configuration)",
  "sources": [
    {
      "entry_id": "52fafcc0-2d18-40d9-8a6e-7662ef9d9bea",
      "origin_id": "doc-42",
      "context_id": "1",
      "content_type": "doc_chunk",
      "content": "# TLS Configuration\nWippy servers terminate TLS when the `tls` block is present on the\n`http.service` entry. Set `cert_file` and `key_file` to PEM paths.",
      "meta": { "title": "Handbook", "chunk": 1 },
      "similarity": 0.0736
    }
  ]
}
```



### Operational Notes


- **Chunk size**: `chunk_size` and `chunk_overlap` count characters, not tokens (the splitter measures length with `utf8.RuneCountInString`). Roughly 2000–4000 characters is a good starting point. Too small loses local context; too large dilutes similarity scores. Use `chunk_overlap` (~10–20% of chunk size) to preserve sentences across boundaries.
- **Content types**: Use distinct `content_type` values (`doc_chunk`, `faq`, `code_snippet`) so search can filter by type.
- **Re-indexing**: Delete and re-ingest per document via `embedding_repo.delete_by_origin(doc_id)` before adding new chunks. The repository is a separate library — import it as `embedding_repo: wippy.embeddings:embedding_repo`.
- **Hybrid search**: For exact-term recall (names, IDs), combine vector search with full-text search over your source table and re-rank.
- **Model choice**: `wippy/embeddings` is fixed to `text-embedding-3-small` at 512 dimensions, and the `embeddings_512` table stores `vector(512)`/`float[512]`. A different model or vector size means changing the library constants and the migration table.



### Next Steps


- [LLM Framework](framework/llm.md) — `llm.generate`, `llm.embed`, prompt construction
- [Agents](framework/agents.md) — wrap the retriever as an agent tool
- [SQL Module](lua/storage/sql.md) — underlying database access
- [Text Module](lua/text/text.md) — splitters and tokenization



---

# "Architecture"

## Architecture


Wippy is a layered system built on Go. Components initialize in dependency order, communicate through an event bus, and execute Lua processes via a work-stealing scheduler.

This is an implementation reference. The diagrams and Go types describe runtime internals rather than application registry entries or extension APIs.



### Layers


| Layer | Components |
|-------|------------|
| Application | Lua processes, functions, workflows |
| Runtime | Lua engine (wippyai/go-lua), 40+ modules |
| Services | HTTP, Queue, Storage, Temporal |
| System | Topology, Factory, Functions, Contracts |
| Core | Scheduler, Registry, Dispatcher, EventBus, Relay |
| Infrastructure | AppContext, Logger, Transcoder |

Each layer depends only on layers below it. The Core layer provides fundamental primitives, while Services build higher-level abstractions on top.



### Boot Sequence


Application startup proceeds through four phases.



#### Phase 1: Infrastructure


Creates core infrastructure before any components load:

| Component | Purpose |
|-----------|---------|
| AppContext | Sealed dictionary for component references |
| EventBus | Pub/sub for inter-component communication |
| Transcoder | Payload serialization (JSON, YAML, Lua) |
| Logger | Structured logging with event streaming |
| Relay | Message routing (Node, Router, Mailbox) |



#### Phase 2: Component Loading


The Loader resolves dependencies via topological sort and loads components level by level, one component at a time.

Dependency edges determine the levels; package groups such as Core and System
do not impose a separate global order. Components with no dependency edge may
therefore load in the same level regardless of package group.

Each component attaches itself to context during Load, making services available to dependent components.



#### Phase 3: Activation


After all components load:

1. **Start runtime services** - Calls `StartRuntimeServices(ctx)`
2. **Freeze Dispatcher** - Locks command handler registry for lock-free lookups
3. **Seal AppContext** - No more writes allowed, enables lock-free reads
4. **Start Components** - Calls `Start()` on each component with `Starter` interface



#### Phase 4: Entry Loading


Registry entries from `_index.json`, `_index.yaml`, and `_index.yml` project
manifests are loaded and validated:

1. Entries parsed from project files
2. Pipeline stages transform entries (override, link, bytecode)
3. Services marked `auto_start: true` begin running
4. Supervisor monitors registered services



### Components


Components are Go services that participate in application lifecycle.



#### Lifecycle Phases


| Phase | Method | Purpose |
|-------|--------|---------|
| Load | `Load(ctx) (ctx, error)` | Initialize and attach to context |
| Start | `Start(ctx) error` | Begin active operation |
| Stop | `Stop(ctx) error` | Graceful shutdown |

Components declare dependencies. The loader builds a directed acyclic graph and executes in topological order. Shutdown occurs in reverse order.



#### Standard Components


| Component | Dependencies | Purpose |
|-----------|--------------|---------|
| PIDGen | none | Process ID generation |
| Dispatcher | none | Command handler dispatch |
| Registry | Artifact | Entry storage and versioning |
| Finder | Registry | Entry lookup and search |
| Supervisor | Registry | Service restart policies |
| Topology | none | Process parent/child tree |
| Lifecycle | Topology | Service lifecycle management |
| Factory | none | Process spawning |
| Functions | Registry | Pooled function execution |



### Event Bus


Asynchronous pub/sub for inter-component communication.



#### Design


- Single dispatcher goroutine processes all events
- Publishers enqueue actions without waiting for subscriber delivery
- Pattern matching supports exact values, `*`, `**`, and segment alternation
- Context-based lifecycle ties subscriptions to cancellation



#### Event Flow


```mermaid
sequenceDiagram
    participant P as Publisher
    participant B as EventBus
    participant S as Subscribers

    P->>B: Send(ctx, Event)
    B->>B: Match patterns
    B->>S: Deliver on subscriber channel
    S->>S: Execute callback
```



#### Common Topics


Every event carries a `System` and a `Kind`. The built-in systems publish:

| System | Kind | Purpose |
|--------|------|---------|
| `registry` | `entry.create`, `entry.update`, `entry.delete`, `entry.accept`, `entry.reject` | Entry mutations |
| `registry` | `registry.begin`, `registry.commit`, `registry.discard` | Transaction boundaries |
| `process` | `factory.register`, `factory.delete`, `factory.accept`, `factory.reject` | Factory registration for process kinds |
| `supervisor` | `service.register`, `service.remove`, `service.update`, `service.start`, `service.stop` | Service lifecycle |



### Registry


Versioned storage for entry definitions.



#### Features


- **Versioned State** - Each mutation creates new version
- **History** - In-memory history by default; optional SQLite-backed history for a durable audit trail (history_type: sqlite)
- **Event-driven** - Publishes events on mutations



#### Entry Lifecycle


```mermaid
flowchart LR
    YAML[YAML Files] --> Parser
    Parser --> Stages[Pipeline Stages]
    Stages --> Registry
    Registry --> Validation
    Validation --> Active
```

Pipeline stages transform entries:

| Stage | Purpose |
|-------|---------|
| Override | Apply config overrides |
| Disable | Remove entries by pattern |
| Link | Resolve requirements and dependencies |
| Bytecode | Compile Lua to bytecode |
| EmbedFS | Collect filesystem entries |



### Relay


Message routing between processes across nodes.



#### Three-Tier Routing


```mermaid
flowchart LR
    subgraph Router
        Local[Local Node] --> Peer[Registered Peers]
        Peer --> Inter[Internode]
    end

    Local -.- L[This node]
    Peer -.- P[Registered peer receiver]
    Inter -.- I[Other cluster nodes]
```

1. **Local** - Direct delivery within same node
2. **Peer** - Deliver to a receiver registered for that node ID (an external peer such as a Temporal worker)
3. **Internode** - Fall back to the cluster internode transport, installed by the cluster component after boot



#### Mailbox


Each node has a mailbox with worker pool:

- FNV-1a hashing assigns senders to workers
- Preserves per-sender message ordering
- Workers process messages concurrently
- Back-pressure when queue fills



### AppContext


Sealed dictionary for component references.

| Property | Behavior |
|----------|----------|
| Before seal | Single-threaded writes during boot |
| After seal | Lock-free reads, panics on write |
| Duplicate keys | Panic |
| Type safety | Typed getter functions |

Components attach services during the Load phase. After boot completes, AppContext is sealed, allowing lock-free reads and preventing further writes.



### Shutdown


Graceful shutdown proceeds in reverse dependency order:

1. SIGINT/SIGTERM triggers shutdown
2. Supervisor stops managed services
3. Components with `Stopper` interface receive `Stop()`
4. Infrastructure cleanup

Second signal forces immediate exit.



### See Also


- [Scheduler](internals/scheduler.md) - Process execution
- [Event Bus](internals/events.md) - Pub/sub system
- [Registry](internals/registry.md) - State management
- [Command Dispatch](internals/dispatch.md) - Yield handling



---

# "Registry Internals"

## Registry Internals


The registry stores versioned entry state, supports transactions and history, and propagates changes through the event bus.

The Go and query fragments on this page document internal data structures and finder syntax; they are not standalone application examples.



### Entry Storage


Entries are stored as an ordered slice with a hash map index for O(1) lookups:

```go
type Entry struct {
    ID       ID              // namespace:name
    Kind     Kind            // Entry type
    Meta     attrs.Bag       // Author metadata
    Data     payload.Payload // Content
    Registry EntryMetadata   // Registry-owned provenance
}

type EntryMetadata struct {
    Owner string // Deployment source that supplied the entry
    Root  bool   // Dependency declaration selected by the deployment
}
```

Entry IDs use Go's `unique` package for interning—identical IDs share memory.

`Registry` is owned by the registry, not the entry author. `Owner` is assigned from the deployment source; `Root` is set from the `dependency_root` write-side field on an `ns.dependency` entry. The ordinary entry APIs return only `ID`, `Kind`, `Meta` and `Data`; provenance is read through the snapshot state API.



### Snapshot


`Registry.Snapshot()` returns one atomic view: the version, the entries at that version, and the registry-owned state metadata for that same version.

```go
type Snapshot struct {
    Registry StateMetadata
    Version  Version
    Entries  State
}

type StateMetadata struct {
    Resolution *DependencyResolution
}
```

Reading version, entries and resolution as one value prevents a caller from pairing entries with a resolution from a different version. The selected module graph is stored once per snapshot rather than repeated on every entry.



### Overlays


`OverlayWriter` is an optional registry capability for process-local entries:

```go
type OverlayWriter interface {
    ApplyOverlay(context.Context, string, uint64, ChangeSet) (uint64, error)
    GetOverlay(string) (State, uint64, error)
}
```

Overlay entries are grouped under a logical owner string. They join effective state and pass through the same topology sort and handler transitions as durable entries, so services start and stop for them normally, but they never produce a history version. They are empty after a cold boot and must be reconciled by their owning control service.

Writes are optimistically concurrent: `GetOverlay` returns the owner's current generation, and `ApplyOverlay` commits only if that generation is still current, otherwise it returns a retryable `Conflict`. Each successful apply issues a new process-unique generation, and a tombstone is retained for owners that mutated so an ABA sequence cannot be mistaken for an unchanged overlay.

The composition rules validated on every apply:

- An entry may be created only if no durable entry and no overlay entry holds its ID.
- Only the owning identity may update or delete its overlay entries.
- Overlay entries may not carry registry-owned metadata, and may not use kinds claimed by registry directives.
- A delete may not remove an entry that a surviving entry depends on.
- Dependency edges may not cross owner boundaries, and durable entries may not depend on overlay entries.



### Version Chain


Each version points to its parent. Path computation uses a graph algorithm to find the shortest route between any two versions:

```mermaid
flowchart LR
    v0[v0] --> v1[v1] --> v2[v2] --> v3[v3] --> vN[vN]
```



### ChangeSets


A changeset is an ordered list of operations transforming one state to another:

| Operation | OriginalEntry | Purpose |
|-----------|---------------|---------|
| Create | nil | Add new entry |
| Update | old value | Modify existing |
| Delete | deleted value | Remove entry |

`OriginalEntry` enables reversal—updates store the previous value, deletes store what was removed.



#### Building Deltas


`BuildDelta(oldState, newState)` generates minimal operations:

1. Compare states, identify changes
2. Sort deletes in reverse dependency order (dependents first)
3. Sort creates/updates in forward dependency order (dependencies first)



#### Squashing


Multiple changesets merge by tracking final state per entry:

```
Create + Update = Create (with updated value)
Create + Delete = ∅ (cancel out)
Update + Delete = Delete
Delete + Create = Update
```



### Transactions


```mermaid
sequenceDiagram
    participant R as Registry
    participant B as EventBus
    participant H as Handlers

    R->>B: registry.begin
    loop Each Operation
        R->>B: entry.create/update/delete
        B->>H: dispatch to listeners
        H-->>B: accept or reject
        B-->>R: confirmation
    end
    alt All accepted
        R->>B: registry.commit
    else Any rejected
        R->>B: registry.discard
        R->>R: rollback
    end
```

By default, the registry waits 30 seconds for listeners to accept or reject each operation. `registry.event_wait_timeout` changes this per-operation timeout. On rejection, the registry rolls back by computing and applying the inverse delta.



#### Non-propagating Entries


The following kinds skip the event bus by default:
- `registry.entry` - Application configs
- `ns.requirement` - Namespace requirements
- `ns.dependency` - Module dependencies
- `ns.definition` - Module metadata (readme, wiki, license, authors)

This is the default set; `registry.dispatch_internal_kinds` in the runtime config replaces it.



### Dependency Resolution


Entries can declare dependencies on other entries. The resolver extracts dependencies via registered patterns:

```go
resolver.RegisterPattern(registry.DependencyPattern{
    Path:          "meta.server",
    AllowWildcard: true,
})
```

Dependencies are extracted from entry Meta and Data fields, then used for topological sorting during state transitions.



#### Dependency Access Policy


External dependency access is a request-scoped context value, not a global flag:

| Policy | Effect |
|--------|--------|
| `DependencyAccessUnspecified` | Callers choose; the caller's own default applies |
| `DependencyAccessOnline` | External resolution and artifact download are permitted |
| `DependencyAccessVerifiedOffline` | External access is forbidden; resolution uses locked manifests and locally present artifacts |

`LoadState()` defaults to verified-offline when the context specifies nothing, so boot replays a stored graph without reaching the network. Restoring a deployment baseline switches the context to online because it must fetch the modules that baseline names. Under verified-offline a manifest provider serving only locked modules replaces the hub provider, and a missing artifact fails as missing evidence rather than triggering a download.



### Version History


History backends:

| Implementation | Use Case |
|----------------|----------|
| SQLite | Production persistence |
| PostgreSQL | Production persistence, shared across nodes |
| Memory | Default when `history_type` is unset; testing |
| Nil | No history |

SQLite uses WAL mode with tables for versions, changesets (MessagePack encoded), and metadata. PostgreSQL is selected with `registry.history_type: postgres` plus `history_dsn`/`history_schema` (see [Configuration](guides/configuration.md#registry)).

History also persists the exact dependency resolution for each version: when an `ns.dependency` change is applied, the resolved module graph is stored content-addressed alongside the changeset. Boot and rollback replay the stored graph instead of re-solving, so a version always reconciles with the versions it was resolved with. The history schema migrates automatically on first boot after an upgrade; a pre-existing version is resolved once on first visit and checkpointed.



#### Navigation


Path computation finds the shortest route between versions:

```go
Path(v0, v3) = [v1, v2, v3]  // Apply changesets forward
Path(v3, v1) = [v2, v1]      // Apply reversed changesets
```

`LoadState()` replays history from a baseline without creating new versions—used during boot.



### Finder


Query engine with LRU caching for searching entries:

| Operator | Prefix | Example |
|----------|--------|---------|
| Root-field glob | `.` root field | `.kind=function.*` |
| Regex | `~` | `~meta.path=/api/.*` |
| Contains | `*` | `*meta.tags=backend` |
| Prefix | `^` | `^meta.name=user` |
| Suffix | `$` | `$meta.path=Handler` |

Cache invalidates on version change.

Glob matching applies to the root fields `.kind`, `.name`, `.ns`, and `.id`. Unprefixed `meta.*` criteria use equality matching.



### See Also


- [Registry](concepts/registry.md) - High-level concepts
- [Events](internals/events.md) - Event bus details



---

# "Scheduler"

## Scheduler


The scheduler executes processes on workers with local deques, inject queues, a global queue, and work stealing.

This is an implementation reference. Its Go structures and diagrams describe the pinned runtime scheduler, not APIs implemented by application code.



### Process Interface


The scheduler works with any type implementing the `Process` interface:

```go
type Process interface {
    Init(ctx context.Context, method string, input payload.Payloads) error
    Step(events []Event, out *StepOutput) error
    Close()
}
```

| Method | Purpose |
|--------|---------|
| `Init` | Prepare process with entry method name and input arguments |
| `Step` | Advance state machine with incoming events, write yields to output |
| `Close` | Release resources |

The `method` parameter in `Init` specifies which entry point to invoke. A process instance can expose multiple entry points, and the caller selects which one to execute.

The scheduler calls `Step()` repeatedly, passing events (yield completions, messages) and collecting yields (commands to dispatch). The process writes its status and any yields to the `StepOutput` buffer.

```go
type Event struct {
    Type  EventType  // EventYieldComplete or EventMessage
    Tag   uint64     // Correlation tag for yield completions
    Data  any        // Result data or message payload
    Error error      // Error if yield failed
}
```



### Structure


The scheduler spawns `GOMAXPROCS` workers by default. Each worker has a local deque for cache-friendly LIFO access and a per-worker MPSC inject queue for requeued work that has affinity to that worker, including yield completions and message wakes. A global FIFO queue handles new submissions and affinity-less re-queues. Processes are tracked by PID for message routing.



### Work Finding


```mermaid
flowchart TD
    W[Worker needs work] --> L{Local deque?}
    L -->|has items| LP[Pop from bottom LIFO]
    L -->|empty| I{Inject queue?}
    I -->|has items| IP[Pop + drain up to 16 to local]
    I -->|empty| G{Global queue?}
    G -->|has items| GP[Pop + batch transfer up to 16]
    G -->|empty| S[Scan other workers from rotating start]
    S --> SH[Steal up to half, capped at 32]
```

Workers check sources in priority order:

| Priority | Source | Pattern |
|----------|--------|---------|
| 1 | Local deque | LIFO pop, lock-free, cache-friendly |
| 2 | Inject queue | MPSC pop of affine requeues/events, drain up to 16 to local |
| 3 | Global queue | FIFO pop with batch transfer |
| 4 | Other workers | Scan from a rotating start index and steal up to half, capped at 32 items per attempt |

When popping from the inject or global queue, workers take one item and move up to 16 more to their local deque.



### Chase-Lev Deque


Each worker owns a Chase-Lev work-stealing deque:

```go
type Deque struct {
    buffer atomic.Pointer[dequeBuffer]
    top    atomic.Int64  // Thieves steal from here (CAS)
    bottom atomic.Int64  // Owner pushes/pops here
}
```

The owner pushes and pops from the bottom (LIFO) without a mutex; popping the
last item uses CAS to coordinate with thieves. Thieves steal from the top (FIFO)
using CAS. This gives the owner cache-friendly access to recently-pushed items
while distributing older work to stealers.

`StealHalfInto` takes up to half the available items in one CAS operation,
limited by the destination buffer. Worker steal attempts use a 32-item buffer.



### Adaptive Spinning


Before blocking on the condition variable, workers spin adaptively:

| Spin Count | Action |
|------------|--------|
| < 4 | Tight loop |
| 4-15 | Yield thread (`runtime.Gosched`) |
| >= 16 | Block on condition variable |



### Process States


```mermaid
stateDiagram-v2
    [*] --> Ready: Submit
    Ready --> Running: CAS by worker
    Running --> Complete: done
    Running --> Blocked: yields commands
    Running --> Idle: waiting for messages
    Blocked --> Ready: CompleteYield
    Idle --> Ready: Send arrives
```

| State | Description |
|-------|-------------|
| Ready | Queued for execution |
| Running | Worker is executing Step() |
| Blocked | Waiting for yield completion |
| Idle | Waiting for messages |
| Complete | Execution finished |

A wakeup flag handles races: if a handler calls `CompleteYield` while the worker still owns the process (Running), it sets the flag. The worker checks the flag after dispatching and re-queues if set.



### Event Queue


Each process has an MPSC (multi-producer, single-consumer) event queue:

- **Producers**: Command handlers (`CompleteYield`), message senders (`Send`)
- **Consumer**: Worker drains events in `Step()`

A generation counter guards the queue. Every producer binds to the generation it observed; `Reset` bumps it, so a sender left over from a previous execution cannot push into a reused queue.

Ordinary event traffic is unbounded. Accounting is opt-in per message: a message that carries `MaxItems` or `MaxBytes` is admitted against a per-topic budget, and the tightest limit seen for a topic wins. A message holds its reservation until the consuming process releases it, and terminals never consume backlog capacity.

When a topic's budget is exhausted, the queue appends one synthetic message in the overflowing message's place, carrying `message queue limit exceeded` followed by a terminal payload. Further traffic on that topic is discarded until the queue is reset, so a bounded subscription ends with an error terminal rather than growing without bound.



### Message Routing


The scheduler implements `relay.Receiver` to route messages to processes. `Send` delegates to `SendContext` with a background context; `SendContext` checks cancellation before the target lookup and before admission, because admission itself is non-blocking and irreversible once it succeeds.

Both look up the target PID in the `byPID` map and push the package onto the process queue under the processor's current generation. Admission is three-way:

| Result | Meaning | Package ownership |
|--------|---------|-------------------|
| Accepted | The queue took the package | Queue, released by the scheduler after processing |
| Dropped | A per-topic budget overflowed and the queue retained nothing but its own overflow terminal | Caller, released immediately |
| Rejected | The queue is closed or the generation is stale | Caller; `SendContext` returns `ErrProcessClosed` |

An accepted or dropped push then wakes the process if it is idle or blocked. It re-queues via injectOrGlobal, which pushes to the last worker's per-worker inject queue when the process has a known worker affinity, and falls back to the global queue otherwise.



### Shutdown


On shutdown, the scheduler sends cancel events to all tracked processes and waits for them to complete or timeout. Workers exit once no work remains.



### See Also


- [Command Dispatch](internals/dispatch.md) - How yields reach handlers
- [Process Model](concepts/process-model.md) - High-level concepts



---

# "Command Dispatch"

## Command Dispatch


Command dispatch routes process yields to handlers and returns correlated results through process event queues.

This is an extension and implementation reference. The custom command and dispatcher fragments assume an existing Go package, boot graph, command API, and service-specific error handling.



### Flow


```mermaid
sequenceDiagram
    participant P as Process
    participant W as Worker
    participant R as Registry
    participant H as Handler

    P->>W: yield(command, tag)
    W->>R: getHandler(cmdID)
    R-->>W: handler
    W->>H: Handle(cmd, tag, receiver)
    H-->>H: async work
    H->>W: CompleteYield(tag, result)
    W->>P: queue event, wake
    P->>P: resume with result
```



### Command Registry


The registry stores handlers in a hybrid structure:

```go
type Registry struct {
    handlers [256]Handler         // System commands: O(1) index
    extended map[CommandID]Handler // Extended commands: map lookup
    frozen   atomic.Bool          // Lock-free after boot
}
```

System commands (0-255) use array indexing. Extended commands use map lookup. After `Freeze()`, all lookups are lock-free.



#### Command ID Ranges


| Range | Module | Examples |
|-------|--------|----------|
| 1-9 | process | Send, Spawn, Terminate, Cancel, Monitor, Unmonitor, Link, Unlink, Exec |
| 10-29 | clock | Sleep, Ticker, Timer |
| 30-39 | socket | Connect, Listen, Accept, Bind, Resolve |
| 50-59 | stream | Read, Write, Close, Seek |
| 60-69 | http | Request, RequestBatch |
| 70-79 | tty | terminal I/O |
| 80-89 | websocket | Connect, Send, Receive |
| 90-99 | event | Subscribe, Send |
| 100-119 | sql | Query, Execute, Prepare, Stmt, Tx ops |
| 120-129 | store | Get, Set, Delete, Has |
| 130-139 | security | ValidateToken, CreateToken |
| 140-149 | function | Call, AsyncStart, AsyncCancel |
| 150-159 | exec | ProcessWait |
| 160-169, 173-174 | cloudstorage | Upload, Download, List, Presigned URLs, Multipart, OpenReader |
| 170-171 | eval | Compile, Run |
| 172 | cdc | Subscribe |
| 180-189 | workflow | SideEffect, Exec, Version, UpsertAttrs |
| 190-199 | contract | Open, Call, AsyncCall, AsyncCancel |
| 200-211 | pg (process group) | Join, Leave, GetMembers, GetLocalMembers, WhichGroups, Broadcast, BroadcastLocal, WhichLocalGroups, Monitor, Events, JoinGroups, LeaveGroups |
| 256+ | custom | User-defined services |

Packages reserve command-ID ownership from `init()` with
`MustRegisterCommands()`; ownership collisions panic while packages initialize.
During component loading, each service binds its handlers through
`Registrar.Register`. The dispatcher is frozen only after those handlers have
been installed.



### Defining Commands


Commands are data structures with a unique `CommandID`:

```go
const MyCommand dispatcher.CommandID = 256

type MyCmd struct {
    Input  string
    Option int
}

func (c *MyCmd) CmdID() dispatcher.CommandID { return MyCommand }
```

Reserve the command ID at package initialization:

```go
func init() {
    dispatcher.MustRegisterCommands("myservice", MyCommand)
}
```



### Dispatchers


A dispatcher groups related handlers. It implements `RegisterAll` to register handlers and lifecycle methods for setup/teardown:

```go
type Handler interface {
    Handle(ctx context.Context, cmd Command, tag uint64, receiver ResultReceiver) error
}

type ResultReceiver interface {
    CompleteYield(tag uint64, data any, err error)
}
```

```go
type Dispatcher struct {
    // service state
}

func (d *Dispatcher) RegisterAll(register func(id dispatcher.CommandID, h dispatcher.Handler)) {
    register(myapi.MyCommand, dispatcher.HandlerFunc(d.handleMyCommand))
}

func (d *Dispatcher) handleMyCommand(ctx context.Context, cmd Command, tag uint64, receiver ResultReceiver) error {
    c := cmd.(*myapi.MyCmd)
    go func() {
        result := doWork(c)
        if ctx.Err() == nil {
            receiver.CompleteYield(tag, result, nil)
        }
    }()
    return nil
}
```

Register as a boot component:

```go
func MyDispatcher() boot.Component {
    return boot.New(boot.P{
        Name:      "dispatcher.myservice",
        DependsOn: []boot.Name{DispatcherName},
        Load: func(ctx context.Context) (context.Context, error) {
            reg := dispatcher.GetRegistrar(ctx)
            svc := myservice.NewDispatcher()
            svc.RegisterAll(reg.Register)
            return ctx, nil
        },
    })
}
```



### Yields and Correlation


When a process needs async work, it yields a command with a correlation tag:

```go
type Yield struct {
    Cmd Command
    Tag uint64    // Process-local counter for correlation
}
```

The worker extracts yields from `StepOutput` after each step and dispatches them to handlers. Each tag uniquely identifies the request so results can be matched back.



### See Also


- [Scheduler](internals/scheduler.md) - Process execution
- [Modules](internals/modules.md) - Lua module integration
- [Process Model](concepts/process-model.md) - High-level concepts



---

# "Event Bus"

## Event Bus


The event bus processes queued pub/sub actions on one dispatcher goroutine and delivers matching events to subscriber channels.

The Go snippets are implementation and extension fragments. They assume an existing component context, logger, handlers, and application event types.



### Event Structure


```go
type Event struct {
    System string  // Component/module (e.g., "registry", "process")
    Kind   string  // Event type (e.g., "create", "update", "exit")
    Path   string  // Entity identifier
    Data   any     // Payload
    Aux    any     // In-process dispatcher context; not propagated to processes
}
```



### Bus Architecture


```mermaid
flowchart LR
    subgraph Publishers
        P1[Component]
        P2[Component]
    end

    subgraph Bus
        Q[actionQueue]
        D[dispatcher goroutine]
        S[subscribers map]
    end

    subgraph Subscribers
        S1[chan Event]
        S2[chan Event]
    end

    P1 & P2 -->|enqueue| Q
    Q -->|signal| D
    D -->|match & deliver| S1 & S2
    D <-->|manage| S
```

The bus stores state in a simple structure:

```go
type Bus struct {
    subscribers       map[SubscriberID]sub
    subscriberCounter uint64
    maxSubscribers    int

    actionQueue []action
    spareQueue  []action
    actionMu    sync.Mutex
    actionReady chan struct{}  // buffered=1

    closed atomic.Bool
}
```

All mutations go through the dispatcher goroutine, eliminating race conditions without complex locking.



### Actions


Four action types flow through the queue:

| Action | Behavior |
|--------|----------|
| Subscribe | Adds subscriber to map, responds on done channel |
| Unsubscribe | Removes subscriber, responds on done channel |
| Send | Delivers event to matching subscribers |
| Stop | Clears subscribers, drains queue, exits loop |

Subscribe and Unsubscribe block until the dispatcher confirms. Send is fire-and-forget. The bus accepts at most `DefaultMaxSubscribers` subscriptions (4096 by default); subscriptions beyond the cap fail with `ErrSubscribersCapReached`.

`Subscribe` is rejected with `ErrSubscribersCapReached` once the bus holds `DefaultMaxSubscribers` (4096) active subscriptions.

`Subscribe` fails immediately when the subscription context is already canceled, and again at the dispatcher if it is canceled before the ownership decision is made — the bus never takes a channel it did not install.

`Unsubscribe` is an ownership barrier, not a best-effort hint. It returns only after the dispatcher acknowledges, so the caller can release the channel knowing the bus holds no in-flight send reference. When it arrives after `Stop`, the acknowledgement waits for the dispatcher to finish delivering the batch it already drained.

`Stop` is likewise terminal: a second concurrent `Stop` does not return early on the already-closed flag but waits for the dispatcher to drain and exit.



### Queue Swapping


The dispatcher uses slice swapping to avoid allocations in steady state:

```go
func (b *Bus) processActions() bool {
    b.actionMu.Lock()
    actions := b.actionQueue
    b.actionQueue = b.spareQueue[:0]
    b.spareQueue = nil
    b.actionMu.Unlock()

    for i := range actions {
        // process action
    }

    clear(actions)
    b.actionMu.Lock()
    b.spareQueue = actions[:0]
    b.actionMu.Unlock()
    return true
}
```

Two slices alternate: one for processing, one for new arrivals. The `actionReady` channel is buffered to 1, so signaling never blocks and multiple enqueues coalesce into one wakeup.



### Pattern Matching


Subscriptions compile patterns once at subscribe time:

```go
type sub struct {
    subID   SubscriberID
    ctx     context.Context
    system  *wildcard.Wildcard
    kind    *wildcard.Wildcard
    eventCh chan<- Event
}
```

The wildcard package supports four pattern types:

| Pattern | Matches |
|---------|---------|
| `registry` | Exact match only |
| `*` | Any single segment |
| `**` | Zero or more segments |
| `(a\|b)` | Alternation within segment |

Patterns split on `.` so `registry.*` matches `registry.create` but not `registry.entry.create`. The pattern `registry.**` matches all three of `registry`, `registry.create`, and `registry.entry.create`.



### Event Delivery


During Send processing, the dispatcher iterates subscribers:

```go
for id, s := range b.subscribers {
    if s.system != nil && !s.system.Match(a.event.System) {
        continue
    }
    if s.kind != nil && !s.kind.Match(a.event.Kind) {
        continue
    }

    select {
    case <-a.ctx.Done():
        goto cleanup
    case <-s.ctx.Done():
        expiredSubs = append(expiredSubs, id)
    case s.eventCh <- a.event:
    }
}
```

If a subscriber's context is canceled, it's marked for removal during that delivery pass. The event context can also cancel delivery mid-iteration.



### Lua Process Bridge


The events dispatcher bridges Go events to Lua processes. It subscribes once to all events (`"**"`) and routes internally based on process subscriptions:

```go
type Dispatcher struct {
    bus    event.Bus
    node   relay.Node
    subID  SubscriberID
    eventC chan event.Event

    mu   sync.RWMutex
    subs map[string]*subscription  // topic -> subscription
}
```

When a Lua process subscribes via `events.subscribe()`, the dispatcher stores the pattern and target PID. Matching events are packaged and sent via relay:

```go
func (d *Dispatcher) routeEvent(evt event.Event) {
    d.mu.RLock()
    defer d.mu.RUnlock()

    for _, sub := range d.subs {
        if !matchPattern(sub.system, evt.System) {
            continue
        }
        if sub.kind != "" && sub.kind != "*" && !matchPattern(sub.kind, evt.Kind) {
            continue
        }

        data := map[string]any{
            "system": evt.System,
            "kind":   evt.Kind,
            "path":   evt.Path,
        }
        if evt.Data != nil {
            data["data"] = evt.Data
        }

        pkg := relay.NewPackage(pid.PID{}, sub.pid, sub.topic, payload.New(data))
        d.node.Send(pkg)
    }
}
```



#### Subscriber


Wraps channel subscription with a callback:

```go
handler, err := eventbus.NewSubscriber(ctx, bus, "registry", "entry.*",
    func(evt Event) {
        // handle
    })
if err != nil {
    return err
}
defer handler.Close()
```

Spawns two goroutines: one reads events and calls the handler, another waits for context cancellation to unsubscribe.



#### EventRouter


Manages multiple handlers with centralized lifecycle:

```go
router, err := eventbus.StartRouter(ctx, bus,
    WithHandlers(handler1, handler2),
    WithLogger(log))
if err != nil {
    return err
}
defer router.Stop()
```

Each handler implements `Pattern()` and `Handle()`. The router creates a Subscriber for each and closes all on Stop.



#### AwaitService


Request-response over pub/sub. It keeps a single subscription per `(system, kind)` pair and routes events to waiters by `Path`:

```go
svc := eventbus.NewAwaitService(bus)
if err := svc.Start(ctx); err != nil {
    return err
}
defer svc.Stop()

waiter, err := svc.Prepare(ctx, "test", "response.(accept|reject)", "test/path", 5*time.Second)
if err != nil {
    return err
}
defer waiter.Close()

bus.Send(ctx, triggeringEvent)

result := waiter.Wait()  // returns AwaitResult{Event, Accepted, Error}
```

`Prepare` registers the waiter before the triggering event is sent, avoiding the race where the response arrives before the wait is registered. `Wait` blocks until a matching `Path` event arrives or the timeout (default `DefaultAwaitTimeout`, 30s, when non-positive) expires. `Accepted` is true when the event kind is `accept`, `*.accept`, or `*.accepted`; otherwise the kind is treated as a rejection and any `error` in `Data` surfaces as `Error`. The convenience `Await(ctx, system, kind, path, timeout)` combines Prepare and Wait. The boot infrastructure registers an AwaitService on the context (`event.GetAwaitService`).



### Shutdown


1. `Stop()` atomically sets closed flag and enqueues Stop action
2. Dispatcher clears subscriber map
3. Remaining queued actions are drained:
   - Subscribe requests get "bus is closed" error
   - Unsubscribe requests complete immediately
   - Send events are dropped
4. WaitGroup completes



### See Also


- [Registry](internals/registry.md) - Primary event producer
- [Command Dispatch](internals/dispatch.md) - Process-to-handler routing



---

# "Lua Modules"

## Lua Modules


Runtime modules extend the Lua environment with new functionality. Modules can provide deterministic utilities, I/O operations, or async commands that yield to external systems.

> The Lua runtime implementation may change in future versions.



### Module Definition


Every module uses `luaapi.ModuleDef`:

```go
var Module = &luaapi.ModuleDef{
    Name:        "mymodule",
    Description: "My custom module",
    Class:       []string{luaapi.ClassDeterministic},
    Types:       ModuleTypes,  // Type definitions for tooling
    Build: func() (*lua.LTable, []luaapi.YieldType) {
        mod := lua.CreateTable(0, 2)
        mod.RawSetString("hello", lua.LGoFunc(helloFunc))
        mod.RawSetString("greet", lua.LGoFunc(greetFunc))
        mod.Immutable = true
        return mod, nil
    },
}
```

The `Build` function returns:
- Module table with exported functions
- List of yield types for async operations (or nil)

Module tables are built once and cached for reuse across all Lua states.



### Module Classification


The `Class` field determines where the module can be used:

| Class | Description |
|-------|-------------|
| `ClassDeterministic` | Same input always produces same output |
| `ClassNondeterministic` | Output varies (time, random) |
| `ClassIO` | External I/O operations |
| `ClassNetwork` | Network operations |
| `ClassEncoding` | Serialization and encoding |
| `ClassTime` | Clock and timer access |
| `ClassProcess` | Process control |
| `ClassSecurity` | Security context and tokens |
| `ClassStorage` | Data persistence |
| `ClassWorkflow` | Workflow-safe operations |

Workflow processes are compiled with `ClassDeterministic` and `ClassWorkflow` as the allowed classes: a module is available to workflows if it carries at least one of them, otherwise it is restricted to functions and processes.



### Exposing Functions


Functions have signature `func(l *lua.LState) int` where the return value is the number of values pushed onto the stack:

```go
func greetFunc(l *lua.LState) int {
    name := l.CheckString(1)           // Required argument
    greeting := l.OptString(2, "Hello") // Optional with default

    l.Push(lua.LString(greeting + ", " + name + "!"))
    return 1
}
```

| Method | Description |
|--------|-------------|
| `l.CheckString(n)` | Required string at position n |
| `l.CheckInt(n)` | Required integer |
| `l.CheckNumber(n)` | Required number |
| `l.CheckTable(n)` | Required table |
| `l.OptString(n, def)` | Optional string with default |
| `l.OptInt(n, def)` | Optional int with default |



### Tables


Tables passed between Go and Lua are mutable by default. Module export tables should be marked immutable:

```go
mod := lua.CreateTable(0, 5)
mod.RawSetString("func1", lua.LGoFunc(func1))
mod.Immutable = true  // Prevent Lua from modifying exports
```

Data tables remain mutable for normal use:

```go
result := l.CreateTable(0, 3)
result.RawSetString("name", lua.LString("value"))
result.RawSetString("count", lua.LNumber(42))
l.Push(result)
```



### Type System


Modules use two separate but complementary typing mechanisms.



#### Type Definitions (Tooling)


The `Types` field provides type signatures for IDE support and documentation. Types are built with the `typ` package's fluent builders:

```go
import (
    "github.com/wippyai/go-lua/types/io"
    "github.com/wippyai/go-lua/types/typ"
)

func ModuleTypes() *io.Manifest {
    m := io.NewManifest("mymodule")

    objectType := typ.NewInterface("mymodule.Object", []typ.Method{
        {Name: "get_value", Type: typ.Func().Param("self", typ.Self).
            Returns(typ.String, typ.NewOptional(typ.LuaError)).Build()},
        {Name: "set_value", Type: typ.Func().Param("self", typ.Self).
            Param("value", typ.String).Returns(typ.NewOptional(typ.LuaError)).Build()},
    })

    m.DefineType("Object", objectType)
    m.SetExport(objectType)
    return m
}
```

**Available type constructs:**

| Type | Description |
|------|-------------|
| `typ.String` | String primitive |
| `typ.Number` | Numeric value |
| `typ.Integer` | Integer value |
| `typ.Boolean` | Boolean value |
| `typ.Any` | Any Lua value |
| `typ.Self` | Receiver type for methods |
| `typ.LuaError` | Error type |
| `typ.NewOptional(t)` | Optional value of type t |
| `typ.NewInterface(name, methods)` | Object with methods |
| `typ.Func()` | Function signature builder |
| `typ.NewRecord()` | Struct-like type builder (fields via `.Field`/`.OptField`) |
| `typ.NewArray(t)` | Array of element type t |
| `typ.NewMap(k, v)` | Map with key/value types |

Function builders chain `Param`, `OptParam`, `Variadic`, and `Returns`:

```go
// (string, ...any) -> (string, error?)
typ.Func().
    Param("first", typ.String).
    Variadic(typ.Any).
    Returns(typ.String, typ.NewOptional(typ.LuaError)).
    Build()
```

Records declare fields with `Field` (required) and `OptField` (optional):

```go
typ.NewRecord().
    Field("key", typ.String).
    Field("value", typ.Any).
    OptField("ttl", typ.Number).
    Build()
```

See the `typ` package in go-lua for the complete type system.



#### UserData Bindings (Runtime)


`RegisterTypeMethods` creates the actual Go-to-Lua bindings:

```go
func init() {
    value.RegisterTypeMethods(nil, "mymodule.Object",
        map[string]lua.LGoFunc{
            "__tostring": objectToString,  // Metamethods
        },
        map[string]lua.LGoFunc{
            "get_value": objectGetValue,   // Regular methods
            "set_value": objectSetValue,
        },
    )
}
```

Metatables are immutable and cached globally for thread-safe reuse.

| System | Purpose | Defines |
|--------|---------|---------|
| Type Definitions | IDE, docs, type checking | Signatures |
| UserData Bindings | Runtime method calls | Executable functions |



### Async Operations


For operations that wait on external systems, return a yield instead of a result. The yield is dispatched to a Go handler and the process resumes when the handler completes.



#### Defining Yields


Declare yield types in the module's `Build` function:

```go
Build: func() (*lua.LTable, []luaapi.YieldType) {
    mod := lua.CreateTable(0, 1)
    mod.RawSetString("fetch", lua.LGoFunc(fetchFunc))
    mod.Immutable = true

    yields := []luaapi.YieldType{
        {Sample: &FetchYield{}, CmdID: myapi.FetchCommand},
    }

    return mod, yields
}
```



#### Creating a Yield


Return -1 to signal a yield instead of normal return values:

```go
func fetchFunc(l *lua.LState) int {
    url := l.CheckString(1)

    yield := AcquireFetchYield()
    yield.URL = url

    l.Push(yield)
    return -1  // Signal yield, not stack count
}
```



#### Yield Implementation


Yields bridge Lua values and dispatcher commands:

```go
type FetchYield struct {
    *myapi.FetchCmd
}

func (y *FetchYield) String() string              { return "<fetch_yield>" }
func (y *FetchYield) Type() lua.LValueType        { return lua.LTUserData }
func (y *FetchYield) CmdID() dispatcher.CommandID { return myapi.FetchCommand }
func (y *FetchYield) ToCommand() dispatcher.Command { return y.FetchCmd }
func (y *FetchYield) Release() { releaseFetchYield(y) }

func (y *FetchYield) HandleResult(l *lua.LState, data any, err error) []lua.LValue {
    if err != nil {
        return []lua.LValue{lua.LNil, lua.NewLuaError(l, err.Error())}
    }
    resp := data.(*myapi.FetchResponse)
    return []lua.LValue{lua.LString(resp.Body), lua.LNil}
}
```

The dispatcher routes the command to a handler. See [Command Dispatch](internals/dispatch.md) for implementing handlers.



### Error Handling


Return errors as the second value using structured errors:

```go
func myFunc(l *lua.LState) int {
    result, err := doSomething()
    if err != nil {
        lerr := lua.NewLuaError(l, err.Error()).
            WithKind(lua.Internal).
            WithRetryable(true)
        l.Push(lua.LNil)
        l.Push(lerr)
        return 2
    }

    l.Push(lua.LString(result))
    l.Push(lua.LNil)
    return 2
}
```



### Security


Check permissions before performing sensitive operations:

```go
func myFunc(l *lua.LState) int {
    ctx := l.Context()

    if !security.IsAllowed(ctx, "mymodule.action", resource, nil) {
        l.Push(lua.LNil)
        l.Push(lua.NewLuaError(l, "permission denied").WithKind(lua.PermissionDenied))
        return 2
    }

    // Proceed with operation
}
```



### Testing


Basic module tests verify structure and synchronous functions:

```go
func TestModule(t *testing.T) {
    l := lua.NewState()
    defer l.Close()

    mod, _ := Module.Build()
    l.SetGlobal("mymodule", mod)

    err := l.DoString(`
        local m = mymodule
        assert(m.hello() == "Hello, World!")
    `)
    if err != nil {
        t.Fatal(err)
    }
}
```



#### Testing Modules with Yields


To test Lua code that uses yielding functions, create a minimal scheduler with the required dispatchers:

```go
type testScheduler struct {
    *actor.Scheduler
    clock   *clock.Dispatcher
    mu      sync.Mutex
    pending map[string]chan *runtime.Result
}

func newTestScheduler() *testScheduler {
    ts := &testScheduler{pending: make(map[string]chan *runtime.Result)}
    reg := scheduler.NewRegistry()

    // Register dispatchers for yields your module uses
    clockSvc := clock.NewDispatcher()
    clockSvc.RegisterAll(func(id dispatcher.CommandID, h dispatcher.Handler) {
        reg.Register(id, h)
    })
    ts.clock = clockSvc

    ts.Scheduler = actor.NewScheduler(reg, actor.WithWorkers(4), actor.WithLifecycle(ts))
    return ts
}

// Stop wraps Scheduler.Stop, which requires a context.
func (ts *testScheduler) Stop() {
    ts.Scheduler.Stop(context.Background())
}

// OnStart satisfies process.Lifecycle alongside OnComplete.
func (ts *testScheduler) OnStart(context.Context, pid.PID, process.Process) error { return nil }

func (ts *testScheduler) OnComplete(_ context.Context, p pid.PID, result *runtime.Result) {
    ts.mu.Lock()
    ch, ok := ts.pending[p.UniqID]
    delete(ts.pending, p.UniqID)
    ts.mu.Unlock()
    if ok {
        ch <- result
    }
}

func (ts *testScheduler) Execute(ctx context.Context, p pid.PID, proc process.Process,
    method string, input payload.Payloads) (*runtime.Result, error) {
    resultCh := make(chan *runtime.Result, 1)
    ts.mu.Lock()
    ts.pending[p.UniqID] = resultCh
    ts.mu.Unlock()

    _, err := ts.Scheduler.Submit(ctx, p, proc, method, input)
    if err != nil {
        return nil, err
    }

    select {
    case result := <-resultCh:
        return result, nil
    case <-ctx.Done():
        return nil, ctx.Err()
    }
}
```

Create processes from Lua scripts with the modules you're testing:

```go
func bindMyModule(l *lua.LState) error {
    tbl, _ := mymodule.Module.Build()
    l.SetGlobal(mymodule.Module.Name, tbl)
    return nil
}

func newLuaProcess(script string) *engine.Process {
    proto, _ := lua.CompileString(script, "test.lua")
    proc, _ := engine.NewProcess(
        engine.WithProto(proto),
        engine.WithModuleBinder(bindMyModule),
    )
    return proc
}

func TestMyModuleYields(t *testing.T) {
    sched := newTestScheduler()
    sched.Start()
    defer sched.Stop()

    script := `
        local result = mymodule.fetch("http://example.com")
        return result.status
    `

    ctx, _ := ctxapi.OpenFrameContext(context.Background())
    proc := newLuaProcess(script)

    result, err := sched.Execute(ctx, pid.PID{UniqID: "test"}, proc, "", nil)
    if err != nil {
        t.Fatal(err)
    }
    // Assert on result
}
```

See `runtime/lua/modules/time/integration_test.go` for a complete example.



### See Also


- [Command Dispatch](internals/dispatch.md) - Handling yield commands
- [Scheduler](internals/scheduler.md) - Process execution



---

# "Entry Listeners and Observers"

## Entry Listeners and Observers


Entry listeners and observers process registry mutations for matching entry-kind patterns.

This is a Go extension reference. The registration and configuration snippets assume an existing boot component, manager, transcoder, and application config type.



### How It Works


Boot collects listeners and observers with their kind patterns. When an entry changes:

1. Registry emits event (`entry.create`, `entry.update`, `entry.delete`)
2. Each listener wrapper matches the entry kind against its registered pattern
3. Matching handlers receive the entry
4. Handlers process or reject the entry



### Kind Patterns


Handlers subscribe using patterns:

| Pattern | Matches |
|---------|---------|
| `http.service` | Exact match only |
| `http.*` | `http.service`, `http.router`, `http.endpoint` |
| `function.**` | `function.lua`, `function.lua.bc` |



### Entry Listener Interface


Handlers implement `registry.EntryListener`:

```go
type EntryListener interface {
    Add(ctx context.Context, entry Entry) error
    Update(ctx context.Context, entry Entry) error
    Delete(ctx context.Context, entry Entry) error
}
```

Returning an error from `Add`, `Update`, or `Delete` rejects that operation.



### Listener vs Observer


| Type | Purpose | Can Reject |
|------|---------|------------|
| Listener | Primary handler | Yes |
| Observer | Secondary handler (logging, metrics) | No |

```go
handlers.RegisterListener("http.*", httpManager)
handlers.RegisterObserver("function.*", metricsCollector)
```

Observer errors from `Add`, `Update`, and `Delete` are ignored and do not emit an accept or reject event. A listener or observer that also implements `TransactionListener` participates in transaction barriers, where an error from `Begin`, `Commit`, or `Discard` rejects that transaction phase.



### Registering Handlers


Register handlers during boot:

```go
func MyService() boot.Component {
    return boot.New(boot.P{
        Name:      "myservice",
        DependsOn: []boot.Name{core.RegistryName},
        Load: func(ctx context.Context) (context.Context, error) {
            handlers := bootpkg.GetHandlerRegistry(ctx)
            handlers.RegisterListener("myservice.*", manager)
            return ctx, nil
        },
    })
}
```



### Decoding Entry Data


Use `entry.DecodeEntryConfig` from `system/entry` to unmarshal entry data. `DecodeEntryConfigFromContext` takes the transcoder from the context instead of an argument, and `DecodeEntryConfigRaw` skips placeholder resolution:

```go
func (m *Manager) Add(ctx context.Context, ent registry.Entry) error {
    cfg, err := entry.DecodeEntryConfig[ComponentConfig](ctx, m.dtt, ent)
    if err != nil {
        return err
    }
    // Process cfg...
    return nil
}
```

The decoder:
1. Resolves `${env:...}` placeholders and `*_env` companion fields against the environment registry
2. Unmarshals `entry.Data` into your config struct
3. Populates `ID` and `Meta` from the entry when the struct leaves them empty
4. Calls `InitDefaults()` if implemented
5. Calls `Validate()` if implemented



### Config Structure


Entry configs typically include:

```go
type ComponentConfig struct {
    ID      registry.ID `json:"id"`
    Meta    attrs.Bag   `json:"meta"`
    Name    string      `json:"name"`
    Timeout int         `json:"timeout,omitempty"`
}

func (c *ComponentConfig) InitDefaults() {
    if c.Timeout == 0 {
        c.Timeout = 30
    }
}

func (c *ComponentConfig) Validate() error {
    if c.Name == "" {
        return fmt.Errorf("name is required")
    }
    return nil
}
```



### Transaction Support


For atomic operations across multiple entries, implement `TransactionListener`:

```go
type TransactionListener interface {
    Begin(ctx context.Context) error
    Commit(ctx context.Context) error
    Discard(ctx context.Context) error
}
```

The registry calls `Begin` before processing a batch, then `Commit` on success or `Discard` on failure.



### See Also


- [Registry](internals/registry.md) - Entry storage
- [Architecture](internals/architecture.md) - Boot sequence



---

# "Contributing"

## Contributing


Wippy is developed in the public [wippyai GitHub organization](https://github.com/wippyai). The runtime release line is currently alpha.



### Stability


The runtime release line is alpha, and the public repositories do not publish a
separate compatibility or migration policy. Pin the runtime and module versions
used by an application, and review release notes and documentation before
upgrading.



### Issues and Pull Requests


Open documentation issues and pull requests in the [documentation repository](https://github.com/wippyai/docs). The public runtime repository currently accepts [pull requests](https://github.com/wippyai/runtime/pulls) but not issues. For a runtime defect report or proposal that does not include a patch, use the published organization contact, [support@wippy.ai](mailto:support@wippy.ai).

Contributions must follow the organization [Code of Conduct](https://github.com/wippyai/.github/blob/main/.github/CODE_OF_CONDUCT.md).



### Security


The documentation and runtime repositories do not currently publish a dedicated security policy. Report security-sensitive issues privately to [support@wippy.ai](mailto:support@wippy.ai) instead of opening a public issue.



### Support


Contact [support@wippy.ai](mailto:support@wippy.ai).



---

# "License"

## License


This documentation repository and the Wippy runtime are released under the Mozilla Public License 2.0. Individual Wippy modules and components may use different licenses; the `LICENSE` file in each repository is authoritative.



### Mozilla Public License 2.0


Read the exact license in the [documentation repository](https://github.com/wippyai/docs/blob/main/LICENSE) or [runtime repository](https://github.com/wippyai/runtime/blob/main/LICENSE).



### What This Means


MPL-2.0 permits commercial use, modification, and distribution. Modified MPL-covered files remain under MPL-2.0, while those files can be combined with separately licensed code in a larger work.

When distributing modified MPL-covered files, you must make the source form of those files available under MPL-2.0. Refer to the license text for the complete terms.



### Dependencies


Dependencies retain their own licenses. The current public [`wippyai/wasm-runtime`](https://github.com/wippyai/wasm-runtime/blob/main/LICENSE) repository, for example, is licensed under MIT rather than MPL-2.0.



---

# "LLM Brief"

## LLM Brief


Use this brief as the starting context when generating code for a Wippy project.

**Classification: generation reference.** The blocks below are focused contract
patterns, not one runnable project. Registry IDs, schemas, policies, and
application-specific values such as `user_id`, `config`, and `content` must be
defined by the project that uses them.



### What Wippy Is


Wippy is a single-binary application runtime built on the actor model. It runs Lua code in isolated processes that communicate through messages rather than shared memory. Its three compute models are functions (stateless and request-scoped), processes (long-lived actors with state), and workflows (durable actors backed by Temporal). Registry-backed behavior can be added or updated without redeploying the runtime.



### Mental Model


Everything in Wippy is a **registry entry**. An entry has an ID (`namespace:name`), a kind that determines its behavior, metadata, and data. YAML files are one way to declare entries, but the registry is the runtime source of truth. Entries can also be created, updated, or deleted while the system is running.

Kinds determine what an entry does:

- `function.lua` — stateless callable function
- `process.lua` — long-running actor
- `workflow.lua` — durable workflow (Temporal)
- `http.service` — HTTP server
- `http.router` — route group with middleware
- `http.endpoint` — HTTP handler
- `db.sql.postgres` / `mysql` / `sqlite` — database connection
- `store.memory` / `store.sql` — key-value store
- `queue.queue` — message queue
- `process.host` — process execution host
- `process.service` — supervised process
- `contract.definition` / `contract.binding` — typed service interfaces
- `registry.entry` — configuration data



### Project Structure


```
myapp/
├── .wippy.yaml              # Runtime configuration
├── wippy.lock               # Source directories
└── src/
    ├── _index.yaml          # Entry definitions (namespace: app)
    ├── api/
    │   ├── _index.yaml      # namespace: app.api
    │   └── handler.lua
    └── workers/
        ├── _index.yaml      # namespace: app.workers
        └── task.lua
```

Entry definitions live in `_index.yaml` files:

```yaml
version: "1.0"
namespace: app.api

entries:
  - name: get_user
    kind: function.lua
    source: file://handler.lua
    method: get_user
    modules: [sql]

  - name: get_user.endpoint
    kind: http.endpoint
    meta:
      router: app:api_router
    method: GET
    path: /users/{id}
    func: app.api:get_user
```



### Writing Functions


Functions are stateless: they receive arguments, perform work, and return results. They inherit the caller's context and are canceled when the caller is canceled.

```lua
local sql = require("sql")

local function get_user(id)
    local db, err = sql.get("app:main_db")
    if err then return nil, err end

    local rows, err = db:query("SELECT * FROM users WHERE id = $1", {id})
    if err then return nil, err end
    if #rows == 0 then return nil, errors.new({kind = errors.NOT_FOUND, message = "user not found"}) end

    return rows[1]
end

return get_user
```

For HTTP handlers, use the `http` module:

```lua
local http = require("http")
local json = require("json")
local funcs = require("funcs")

local function handler()
    local req, req_err = http.request()
    if req_err then return nil, req_err end
    local res, res_err = http.response()
    if res_err then return nil, res_err end

    local id, param_err = req:param("id")
    if param_err then return nil, param_err end
    local user, err = funcs.call("app.api:get_user", id)
    if err then
        local status_err
        if errors.is(err, errors.NOT_FOUND) then
            status_err = res:set_status(404)
        else
            status_err = res:set_status(500)
        end
        if status_err then return nil, status_err end
        local write_err = res:write_json({error = err:message()})
        if write_err then return nil, write_err end
        return true
    end

    local write_err = res:write_json(user)
    if write_err then return nil, write_err end
    return true
end

return handler
```



### Writing Processes


Processes are actors. Each process has a PID, receives messages through an inbox, and can maintain state across messages. Processes yield while waiting for I/O so other processes can run.

```lua
local function worker(initial_config)
    local inbox = process.inbox()
    local events = process.events()

    while true do
        local r = channel.select {
            inbox:case_receive(),
            events:case_receive()
        }

        if not r.ok then break end

        if r.channel == events then
            local ev = r.value
            if ev.kind == process.event.CANCEL then
                break
            end
        elseif r.channel == inbox then
            local msg = r.value
            local topic = msg:topic()
            local data, err = msg:payload():data()
            if err then return nil, err end

            if topic == "work" then
                -- Perform the application-specific work here.
                print(data.item_id)
            end
        end
    end
end

return worker
```

Spawn processes from other code:

```lua
local pid, err = process.spawn("app.workers:task", "app:process_host", config)
if err then return nil, err end

local ok, send_err = process.send(pid, "work", {item_id = 123})
if send_err then return nil, send_err end
return ok
```



### Writing Workflows


Workflows persist execution history so they can resume after crashes or restarts. Workflow code uses normal Lua syntax, while the runtime records function results, sleeps, and random values for deterministic replay.

Each `funcs.call()` target below must be registered as an activity on the same
Temporal worker through `meta.temporal.activity.worker`. See
[Activities](../temporal/activities.md) for the required function metadata.

```lua
local funcs = require("funcs")

local function compensate(inventory, payment)
    local _, refund_err = funcs.call("app:refund_payment", payment.id)
    local _, release_err = funcs.call("app:release_inventory", inventory.id)
    return refund_err or release_err
end

local function order_flow(order)
    local inventory, err = funcs.call("app:reserve_inventory", order.items)
    if err then return nil, err end

    local payment, payment_err = funcs.call("app:charge_payment", order.total)
    if payment_err then
        local _, release_err = funcs.call("app:release_inventory", inventory.id)
        return nil, release_err or payment_err
    end

    -- Wait for approval signal (can block for days)
    local msg, open = process.inbox():receive()
    if not open then
        local compensation_err = compensate(inventory, payment)
        return nil, compensation_err or errors.new("workflow inbox closed")
    end

    local decision, payload_err = msg:payload():data()
    if payload_err then
        local compensation_err = compensate(inventory, payment)
        return nil, compensation_err or payload_err
    end
    if not decision.approved then
        local compensation_err = compensate(inventory, payment)
        return nil, compensation_err or errors.new("rejected")
    end

    return funcs.call("app:fulfill_order", order.id)
end

return order_flow
```



#### Calling Functions


```lua
local funcs = require("funcs")

-- Synchronous
local result, err = funcs.call("namespace:function_name", arg1, arg2)
if err then return nil, err end

-- Asynchronous (returns Future)
local future, future_err = funcs.async("namespace:function_name", arg1)
if future_err then return nil, future_err end
local response_ch = future:response()
local _, response_open = response_ch:receive()
if not response_open then
    return nil, errors.new("future response channel closed")
end
local async_payload, async_err = future:result()
if async_err then return nil, async_err end
local async_result, decode_err = async_payload:data()
if decode_err then return nil, decode_err end

-- With context
local contextual_exec, contextual_err = funcs.new():with_context({user_id = "123"})
if contextual_err then return nil, contextual_err end
local contextual_result, contextual_err = contextual_exec:call("namespace:function_name")
if contextual_err then return nil, contextual_err end
```



#### Process Communication


```lua
-- Send message (fire-and-forget)
local ok, err = process.send(pid, "topic", data)
if err then return nil, err end

-- Receive messages
local inbox = process.inbox()
local msg, ok = inbox:receive()
if not ok then return nil, errors.new("process inbox closed") end
local topic = msg:topic()
local data, payload_err = msg:payload():data()
if payload_err then return nil, payload_err end

-- Monitor another process (receive EXIT on death)
local monitored, monitor_err = process.monitor(pid)
if monitor_err then return nil, monitor_err end

-- Link processes (bidirectional failure notification)
local linked_pid, spawn_err = process.spawn_linked("namespace:name", "host")
if spawn_err then return nil, spawn_err end
```



#### Channels


Go-style channels for coroutine communication:

```lua
local ch = channel.new(10)  -- buffered
ch:send(value)
local val, ok = ch:receive()

-- Select on multiple channels
local r = channel.select {
    ch1:case_receive(),
    ch2:case_receive(),
    timeout:case_receive()
}
```



#### Error Handling


Functions return `result, error` pairs. Errors are typed objects:

```lua
local result, err = some_operation()
if err then
    if errors.is(err, errors.NOT_FOUND) then
        -- handle not found
    end
    return nil, errors.wrap(err, "context message")
end
```

Error kinds: `UNKNOWN`, `INVALID`, `NOT_FOUND`, `ALREADY_EXISTS`, `PERMISSION_DENIED`, `TIMEOUT`, `CANCELED`, `UNAVAILABLE`, `INTERNAL`, `CONFLICT`, `RATE_LIMITED`.



#### Data Access


```lua
-- SQL
local sql = require("sql")
local db = sql.get("app:main_db")
local rows, err = db:query("SELECT * FROM users WHERE active = $1", {true})
db:execute("INSERT INTO users (name) VALUES ($1)", {name})

-- Key-value store
local store = require("store")
local cache, cache_err = store.get("app:cache")
if cache_err then return nil, cache_err end
local stored, set_err = cache:set("key", value, 3600)  -- TTL in seconds
if set_err then
    cache:release()
    return nil, set_err
end
local val, get_err = cache:get("key")
cache:release()
if get_err then return nil, get_err end

-- Queue
local queue = require("queue")
local published, publish_err = queue.publish("app:tasks", {task = "process", id = 123})
if publish_err then return nil, publish_err end

-- Filesystem
local fs = require("fs")
local vol, volume_err = fs.get("app:storage")
if volume_err then return nil, volume_err end
local data, read_err = vol:readfile("path/to/file.txt")
if read_err then return nil, read_err end
local written, write_err = vol:writefile("output.txt", content)
if write_err then return nil, write_err end
```



#### HTTP Client


```lua
local http_client = require("http_client")

local resp, err = http_client.get("https://api.example.com/data", {
    headers = {Authorization = "Bearer token"},
    timeout = "10s"
})
if err then return nil, err end
local body = resp.body
```



#### Security


```lua
local security = require("security")

local actor = security.actor()       -- who is calling
local scope = security.scope()       -- what permissions apply
if not actor then return nil, errors.new("security actor unavailable") end
if not scope then return nil, errors.new("security scope unavailable") end
local allowed = security.can("read", "resource:users")

-- Token management
local ts, store_err = security.token_store("app:tokens")
if store_err then return nil, store_err end
local token, create_err = ts:create(actor, scope, {expiration = "24h"})
if create_err then
    ts:close()
    return nil, create_err
end
local validated_actor, validated_scope, validate_err = ts:validate(token)
ts:close()
if validate_err then return nil, validate_err end
```



#### Time


```lua
local time = require("time")

time.sleep("5s")
local now = time.now()
local timeout = time.after("30s")  -- channel that fires once
local ticker = time.ticker("10s")  -- ticker:channel() fires every interval
```



#### Registry


```lua
local registry = require("registry")

local entry, entry_err = registry.get("app.api:get_user")
if entry_err then return nil, entry_err end
local tests, find_err = registry.find({["meta.type"] = "test"})
if find_err then return nil, find_err end

-- Create entries at runtime
local snap, snapshot_err = registry.snapshot()
if snapshot_err then return nil, snapshot_err end
local changes, changes_err = snap:changes()
if changes_err then return nil, changes_err end
local _, create_err = changes:create({id = "app:new_func", kind = "function.lua", data = {...}})
if create_err then return nil, create_err end
local version, apply_err = changes:apply()
if apply_err then return nil, apply_err end
```



#### Events


```lua
local events = require("events")

-- Publish
local sent, send_err = events.send("orders", "order.created", "/orders/123", {order_id = "123"})
if send_err then return nil, send_err end

-- Subscribe (wildcards supported)
local sub, subscribe_err = events.subscribe("orders.*")
if subscribe_err then return nil, subscribe_err end
local ch = sub:channel()
local evt, open = ch:receive()
sub:close()
if not open then return nil, errors.new("event subscription closed") end
```



### Module Access Control


Each entry receives the restricted base environment and standard libraries, and executable entries also receive the ambient `process` module. Add non-ambient runtime modules to `modules:` and registry-backed libraries to `imports:`. Undeclared non-ambient modules are unavailable. Host Lua facilities such as `os.execute`, `io.open`, `debug.*`, native module loading, and arbitrary `package.path` resolution are not exposed as opt-in runtime modules. The runtime controls availability through its module loader rather than by scanning source code.

```yaml
modules: [sql, json, http, time, funcs, store]
```

Workflow entries receive only deterministic modules. The runtime intercepts `time.now()`, `uuid.v4()`, and other non-deterministic calls at the module level, recording results for replay.



### Framework Modules


Framework capabilities are distributed as dependencies:

- **wippy/llm** — LLM integration (OpenAI, Anthropic, Google). `llm.generate()`, structured output, embeddings, streaming.
- **wippy/agent** — Agent framework with tool use, delegation, traits, memory. Agents defined as registry entries.
- **wippy/test** — BDD testing. `describe/it` blocks, assertions, mocking.
- **wippy/dataflow** — DAG-based workflow orchestration. Function, agent, cycle, parallel nodes.
- **wippy/relay** — WebSocket relay with central hub, per-user hubs, plugin routing.
- **wippy/views** — Page and component system with template rendering.
- **wippy/facade** — Frontend facade and authentication bridge for iframe and Web Fragment pages.



### Conventions


- Entry IDs use `namespace:name` format
- Names use dots for semantic separation, underscores for words: `get_user.endpoint`
- Fallible APIs return `result, error` — always check the error
- Processes communicate via message passing, never shared state
- Use `channel.select` to multiplex multiple event sources
- Let supervision trees handle process failures instead of adding local recovery around every operation
- Context (trace IDs, user info, security) propagates automatically through function calls
- Workflows must not use non-deterministic operations directly — the runtime handles this for `funcs.call`, `time.sleep`, `uuid.v4`, `time.now`



### Documentation


Full documentation is available at [docs.wippy.ai](https://docs.wippy.ai). LLM-friendly endpoints:

- Browse structure: `https://wippy.ai/llm/toc`
- Search: `https://wippy.ai/llm/search?q=query`
- Fetch page: `https://wippy.ai/llm/path/en/<path>`
- Batch fetch: `https://wippy.ai/llm/context?paths=path1,path2`



---