Introduction

Aperture is a fine-grained access-control engine for the frankbardon/* family of services. It answers one question — "is this principal allowed to do this thing to this resource, and why?" — consistently across every surface that asks it.

Library-first

Aperture is library-first: the public Go packages at the module root (github.com/frankbardon/aperture) are the product. Every other surface — the aperture CLI, the Twirp/HTTP RPC API, the MCP server, and the admin UI — is a thin translator over a single decision engine. There is exactly one place a decision is made, so the answer a script gets from the CLI is the same answer a service gets over RPC and an agent gets over MCP.

The decision API

The engine exposes three operations, each available in a single and a bulk-batched form:

Explain is a first-class citizen, not a debugging afterthought: access decisions are auditable by construction.

What's inside

Aperture models principals (identity), the resource/object model (model, scope), and object providers (provider) that resolve live attributes. Decisions flow through the engine, driven by a rules layer (rules) that compiles a rule AST to an expr-lang/expr expression and evaluates it in-process — pure-Go, no external policy service. Grants come in several flavors (direct, delegation, impersonation), reads are narrowed by scoped visibility (filter), and every decision can be recorded to an audit log (audit). Persistence sits behind one Storage interface with a hand-written SQL / modernc.org/sqlite implementation and an in-memory twin.

Design tenets

• Pure-Go, CGO_ENABLED=0 end to end. No CGO, no external policy engine.
• Coded errors. Every failure is an APERTURE_* error carrying a stable code and an actionable fixup — never a bare string.
• No cross-account leakage. Decisions and error messages never expose data from an account the caller cannot see.
• One engine, many surfaces. CLI, RPC, MCP, and UI are adapters; the decision logic lives once, in the library.

Where to go next

• Getting Started — install Aperture and run your first check.
• CLI & Library — the aperture command tree and the Go embedding API.
• Service Surfaces — the Twirp/HTTP RPC API, MCP server, and admin UI.
• Concepts — identities, the object model, scopes, rules, grants, and audit.
• Reference — error codes, configuration, and the CLI/RPC surface tables.
• Operations — deployment, storage, and running the engine in production.
• Internals — architecture, package layout, and extension points.
• Contributing — conventions and the Update-Demand rule.

Getting Started

This section is the on-ramp. In four short pages you install Aperture, learn the vocabulary the rest of the book assumes, and make your first access-control decision two ways — from the command line and from Go.

Everything here runs against Aperture's embedded example model, a self-contained fixture for the tenant acme. You need nothing but the built binary; there is no store to provision and no data to load.

Read in order

1. Installation — build bin/aperture from source (Go 1.26.1, pure-Go, CGO_ENABLED=0).
2. Concepts primer — principals, actions, objects, patterns and specificity, rules, scopes, and accounts: enough to read any later chapter.
3. First decision (CLI) — a runnable aperture check walkthrough showing an allow, a default deny, and a deny-override.
4. Library quickstart — the same decision from a minimal Go program embedding the engine.

Already know what Aperture is? Skip to Installation. Want the big picture first? See the Introduction.

Installation

Aperture ships as a single, statically linked binary with no runtime dependencies. It is pure Go with CGO_ENABLED=0 end to end — there is no C toolchain, no external policy engine, and nothing to install alongside it. Build it from source and you get one file, bin/aperture, that runs anywhere the Go build targets.

Prerequisites

Build from source

Clone the repository and build the binary with the provided target:

git clone https://github.com/frankbardon/aperture.git
cd aperture
make build

make build compiles the aperture command with CGO_ENABLED=0, -trimpath, and -ldflags="-s -w", writing the result to bin/aperture. Confirm the binary works:

bin/aperture --version

aperture version <version>

Build directly with go

If you prefer not to use make, the equivalent invocation is:

CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o bin/aperture ./cmd/aperture

The cmd/aperture/main.go entrypoint is a thin adapter: it only stamps the version and hands off to the CLI command tree. All behavior lives in the library packages at the module root.

Put it on your PATH (optional)

The examples in this book invoke the binary as bin/aperture from the repository root. To run aperture from anywhere, copy the binary onto your PATH:

cp bin/aperture /usr/local/bin/aperture
aperture --version

Verify the toolchain

Aperture keeps CGO_ENABLED=0 and stays free of any CGO dependency (no geo/h3, no SQLite C bindings — the SQLite backend uses the pure-Go modernc.org/sqlite). If a build fails complaining about a C compiler, an environment variable is forcing CGO on; clear it and rebuild:

CGO_ENABLED=0 make build

Where to go next

• Concepts — the vocabulary the rest of the book assumes.
• First decision (CLI) — run aperture check against the built-in example model.
• Library quickstart — embed the decision engine in a Go program.

Concepts primer

Aperture answers one question — "is this principal allowed to do this action to this object, and why?" This page defines the vocabulary that question is built from. It is deliberately brief: enough to read any later chapter. Each term links forward to its full treatment in the Concepts section of the book.

Every example on this page is drawn from the committed example model (account acme), the same fixture the First decision (CLI) walkthrough uses.

Principal

A principal is the actor a decision is made for — a user, a service, or any other identity that can attempt an action. In the example model, alice and bob are principals. Each principal has a stable id, a kind, an identity string (such as user:alice), and a set of roles and group memberships that carry its grants. The identity package owns this model.

Action

An action is the verb being attempted — read, write, delete, share. Actions are declared per object type: a document in the example model permits read, write, delete, and share. A decision always names exactly one action.

Object

An object is the resource an action targets, named by a canonical object-identity string. Identities are hierarchical, path-like, and always rooted at an account. In the example model a document is written as:

account:acme/project:atlas/document:42

Each type:id segment narrows the path. This structure is what lets a single grant cover a whole subtree while a more specific grant overrides it for one object. The model package defines object types and identities; live object attributes are resolved by object providers (the provider package).

Identity patterns and specificity

A pattern is an object-identity with wildcards, used by a grant to cover many objects at once. ** matches any remaining path; a plain segment matches exactly. In the example model:

account:acme/project:atlas/**              # every object under project atlas
account:acme/project:atlas/document:secret # exactly one document

Specificity decides which grant wins when several match. A more specific pattern (one that matches fewer objects) outranks a broader one. That is how the example model seals a single document: a broad allow on account:acme/project:atlas/** lets engineering read everything, while a narrower deny on account:acme/project:atlas/document:secret overrides it for that one object. Deny-overrides plus specificity is the core resolution rule.

Grant

A grant binds a subject (a principal, role, or group), a permission (an object-type + action pair), and an object pattern, with an effect of allow or deny. Grants are the raw material of every decision. They come in several flavors: direct grants, time-bounded delegations (delegation), and impersonation grants that let one principal act as another (impersonation).

Rule

A rule is a conditional predicate that gates a grant on the attributes of the request — the principal, the object, or the environment. Rules are authored as an AST that Aperture compiles to an expr-lang/expr expression and evaluates in-process; there is no external policy service and no Pulse dependency. The rules package owns compilation and caching.

Scope

A scope narrows what a principal can see or act on within an account — Aperture's mechanism for row-level and subtree-level visibility. Scoped reads are narrowed by the filter package so a listing never returns objects the caller is not entitled to see. The scope package defines the scoping model.

Account

An account is the top-level tenant boundary. Every object identity is rooted at an account (account:acme/...), every grant is stamped to an account, and every decision is scoped to one active account. Accounts are hard isolation boundaries: a decision or an error message never leaks data from an account the caller cannot see. Principals join an account through a membership, which the engine can optionally enforce (a non-member is denied). Accounts are modeled as entities in the model package.

How they fit together

A Check takes an account, a principal, an action, and an object. Aperture gathers every grant whose subject includes the principal and whose pattern matches the object, evaluates any attached rules, applies deny-overrides by specificity, and returns a verdict plus a reason naming the deciding grants. The same resolution drives Enumerate (which objects a principal may act on) and Explain (the full decision trace).

Where to go next

• First decision (CLI) — see these terms resolve into a real verdict.
• Library quickstart — ask the same question from Go.
• The Concepts section of this book expands each term above into its own chapter (identities, the object model, patterns and specificity, rules, scopes, grants, and accounts).

First decision (CLI)

This walkthrough makes real access-control decisions with the aperture binary. It needs nothing beyond the build from Installation: every command below runs against Aperture's embedded example model — a self-contained fixture for the account acme — so there is no store to set up and no data to load.

The example model

When you do not pass --seed, aperture check loads the committed example fixture. It models one tenant, acme, with a project atlas full of documents, and three grants:

alice is an editor in engineering; bob is a viewer in engineering. That is enough to see an allow, a default deny, and a deny-override.

The command

aperture check <principal> <action> <object>

check takes three positional arguments and prints a one-word verdict plus a reason. The process exit code carries the verdict — 0 for allow, non-zero for deny — so a check composes in a shell pipeline (aperture check … && deploy).

Relevant flags:

The full flag reference lives in the CLI chapter later in this book; the three above are all this walkthrough needs.

Allow: engineering reads a document

alice is in engineering, and g-eng-read-atlas lets engineering read everything under atlas:

bin/aperture check alice read account:acme/project:atlas/document:42

allow
reason: allowed by grant g-eng-read-atlas (allow account:acme/project:atlas/**) at specificity 39300; 1 matching grant(s) considered

The command exits 0. The reason names the deciding grant and its specificity — a broad ** pattern scores low.

Allow: an editor writes

alice also holds the editor role, so g-editor-write-atlas permits a write:

bin/aperture check alice write account:acme/project:atlas/document:42

allow
reason: allowed by grant g-editor-write-atlas (allow account:acme/project:atlas/**) at specificity 39300; 1 matching grant(s) considered

Default deny: no grant matches

bob is only a viewer — nothing grants him write — so the decision falls through to a fail-closed default deny:

bin/aperture check bob write account:acme/project:atlas/document:42

deny
reason: default deny: no grant matched action "write" on "account:acme/project:atlas/document:42" for principal "bob" in account "acme"

The command exits non-zero. A decision with no matching grant is always a deny — Aperture fails closed.

Deny by override: specificity wins

g-deny-secret-read seals one document. Even though g-eng-read-atlas would allow the read, the deny is more specific and overrides it:

bin/aperture check alice read account:acme/project:atlas/document:secret

deny
reason: denied by grant g-deny-secret-read (deny account:acme/project:atlas/document:secret) at specificity 60300; 2 matching grant(s) considered

Two grants matched; the deny at specificity 60300 outranks the allow at 39300. This is deny-overrides by specificity — see the Concepts primer.

Why? — explain

check gives the verdict; explain gives the whole trace. It takes the same three arguments:

bin/aperture explain alice read account:acme/project:atlas/document:secret

Explain alice/read on account:acme/project:atlas/document:secret in account acme
  subjects: principal:alice, role:editor, group:engineering
  grants considered (3):
     g-eng-read-atlas [allow account:acme/project:atlas/**] allow covers the object via literal scope at specificity 39300
     g-editor-write-atlas [allow account:acme/project:atlas/**] action "write" does not match the requested "read"
   * g-deny-secret-read [deny account:acme/project:atlas/document:secret] deny covers the object via literal scope at specificity 60300
  verdict: DENY (top specificity 60300)
  reason: denied by grant g-deny-secret-read (deny account:acme/project:atlas/document:secret) at specificity 60300; 2 matching grant(s) considered

The * marks the deciding grant. explain is a first-class operation, not a debug afterthought — every decision is auditable by construction.

A note on the acting principal

For check, enumerate, and explain, the principal is a positional argument — the subject of the question. The write commands (put, bestow, revoke, impersonate, …) are different: they need to know who is acting, and take that principal from the --principal flag or the APERTURE_PRINCIPAL environment variable. For example, bestow reads the delegating principal from APERTURE_PRINCIPAL:

export APERTURE_PRINCIPAL=alice
bin/aperture bestow --help

Setting APERTURE_PRINCIPAL once in your shell saves passing the flag to every mutation. The read decisions above never consult it — they ask about a principal you name explicitly.

Where to go next

• Library quickstart — make the same decision from Go.
• Concepts primer — the vocabulary behind the verdicts.
• The CLI section of this book documents every command and flag in full.

Library quickstart

Aperture is library-first: the CLI, the RPC API, the MCP server, and the admin UI are all thin adapters over the same Go packages. This page embeds the decision engine directly and asks it the same question the First decision (CLI) walkthrough asked — this time from Go.

The pieces

A decision needs three collaborators, wired by hand (Aperture uses manual dependency injection — no wire/fx/dig):

A minimal program

Save this as main.go inside a module that requires github.com/frankbardon/aperture:

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/frankbardon/aperture/engine"
	"github.com/frankbardon/aperture/seed"
	"github.com/frankbardon/aperture/service"
	"github.com/frankbardon/aperture/storage/memory"
)

func main() {
	ctx := context.Background()

	// Build an in-memory store and load the embedded example model (account "acme").
	store := memory.New()
	if err := store.Setup(ctx); err != nil {
		log.Fatal(err)
	}
	if err := seed.Load(ctx, store, seed.Example, seed.FormatYAML); err != nil {
		log.Fatal(err)
	}

	// The service facade is the single entry point every surface uses.
	svc := service.New(engine.New(store))

	res, err := svc.Check(ctx, service.Query{
		Account:   seed.ExampleAccount, // "acme"
		Principal: "alice",
		Action:    "read",
		Object:    "account:acme/project:atlas/document:42",
	})
	if err != nil {
		log.Fatalf("check failed: %v", err)
	}

	fmt.Printf("allow=%v\n", res.Allow)
	fmt.Printf("reason: %s\n", res.Reason)
	fmt.Printf("deciding grants: %v\n", res.DecidingGrantIDs)
}

Run it:

go run .

allow=true
reason: allowed by grant g-eng-read-atlas (allow account:acme/project:atlas/**) at specificity 39300; 1 matching grant(s) considered
deciding grants: [g-eng-read-atlas]

That is the identical decision, reason, and deciding grant the CLI printed — because it is the same code path. There is one engine; every surface is a translator over it.

The request and result types

service.Check takes a service.Query and returns a service.Result:

type Query struct {
	Account   string // active account the decision is scoped to
	Principal string // id of the principal asking
	Action    string // the verb being attempted
	Object    string // canonical object-identity string
}

type Result struct {
	Allow            bool     // the verdict
	Reason           string   // human-readable explanation
	DecidingGrantIDs []string // grant ids that produced the verdict
}

Result never surfaces raw errors as denies inconsistently: an operational failure fails closed (Allow: false) with the cause in Reason, while a malformed request returns a non-nil error carrying an APERTURE_* code. Recover that code with errors.CodeOf from the errors package.

Errors are coded

Every failure Aperture returns across a package boundary is an APERTURE_* coded error, not a bare string. When Check returns a non-nil error — for example, a malformed object identity — inspect the code rather than the message:

import aerr "github.com/frankbardon/aperture/errors"

if err != nil {
	switch aerr.CodeOf(err) {
	case aerr.APERTURE_INVALID_INPUT:
		// the query was malformed — fix the caller
	default:
		// something operational went wrong
	}
}

Beyond Check

The facade exposes the whole read API — Enumerate (which objects a principal may act on), Explain (the full decision trace), and batch forms of each — plus, when constructed with the right options, the mutation path (entity CRUD, grants, delegation, impersonation). A read-only service.New(eng) returns APERTURE_UNIMPLEMENTED from any mutation, so a decision-only surface stays minimal.

Where to go next

• Concepts primer — the vocabulary behind Query and Result.
• The CLI & Library section of this book covers the full Go embedding API.
• The Reference section lists every APERTURE_* error code and its fixups.

CLI overview

Audience: operators and integrators driving Aperture from a shell.

aperture is the command-line face of the same decision engine the library, the RPC/HTTP server, and the MCP surface all call. Every subcommand is a thin adapter: it parses flags, hand-wires the storage → engine → service graph, makes exactly one call into the library, and maps the result to output plus an exit code. There is no CLI-only behaviour — a check from the shell resolves through the identical code path a Check RPC does.

This part of the book is the narrative CLI guide, grouped by what each command family is for. It links into the generated Command-Line Reference, which is produced from the live urfave/cli command tree and holds the authoritative, per-command flag tables. When you want the exact flags for a command, follow the link on that command's name — this guide never re-tabulates them, so the two never drift.

Command families

The embedded example model

Every command runs against a model. When you pass neither --seed nor --store, Aperture loads a committed example fixture — a self-contained model for the account acme — so the read commands below work with no setup. The fixture, its grants, and its principals are walked through in First decision (CLI). The examples in this guide use that fixture unless they say otherwise, and never reference data from any other account.

Two ways to select a model

The commonly shared options — --seed, --store, --account, and --principal — are defined per command, not as root persistent flags, and they mean the same thing everywhere they appear. They are documented once in Global options; each family page below links back to that page rather than re-explaining them.

Related

• Global options — --seed / --store / --account / --principal.
• Command-Line Reference — the generated per-command flag tables.
• First decision (CLI) — the example model, end to end.
• Library overview — the same engine, embedded in Go.

Global options

Audience: operators and integrators driving Aperture from a shell.

aperture declares no persistent global flags. The five options that recur across the command tree — --seed, --store, --account, --principal, and --enumerate-limit — are defined per command, so they appear in each command's flag table in the Command-Line Reference. They carry the same meaning wherever they appear; this page is the single explanation the family pages link back to.

Selecting a model: --seed and --store

Every command resolves its model from these two options, in this order:

Use --seed to point at your own model file for a one-shot decision, and --store when you want changes to persist across invocations.

What an omitted --seed means

It depends on --store, and the difference is deliberate.

Applying a seed document upserts the entire model — accounts, principals, roles, groups, grants, rules. On an in-memory store there is nothing to overwrite and the fixture is the only model there could be. On a database there usually is: it is somebody's production model, or a model a sibling instance provisioned. So Aperture never guesses. Writing model state is an explicit act — --seed, import, or a mutation command — and never a side effect of starting up.

That is what lets a second instance boot against a database it does not own:

# Reads the model another process provisioned. Writes nothing on startup.
bin/aperture serve --store 'postgres://aperture@db/aperture'

# Decide against a model file, no persistence:
bin/aperture check alice read account:acme/project:atlas/document:42 \
  --seed ./my-model.yaml

# Provision a SQLite store from a document, then persist mutations to it:
bin/aperture put grant --principal root --account acme \
  --store ./aperture.db --seed ./my-model.yaml --file ./grant.json

Note that --seed is re-applied on every invocation, not just the first, so a multi-step session against a persistent store should pass the document once and then drop the flag — otherwise each step's deletions are undone by the next step's seed.

It means the same thing for wiring

A seed document carries two kinds of section, and the table above is about the first: the ten model-state sections, which --seed applies to storage. The other six are runtime wiring — providers:, objects:, field_types:, connections:, attributes: and attribute_providers: — which say where a decision reads object metadata and subject attribute bags from. Those are never written to storage by --seed, so the file is read a second time for them.

An omitted --seed means the same thing for both halves:

So aperture serve --store 'postgres://aperture@db/aperture' with no --seed reads its object providers, field types and attribute slots out of the database it opened. When those tables are empty — which is every deployment that has never run aperture wiring push — the local seed file's wiring is used exactly as it always was. There is no flag for this and nothing to configure.

With both, the database wins and the file may only ADD

An instance can have wiring rows and a --seed file, and most will: some wiring cannot be shared at all. A kind: csv provider's data source is a filesystem path, so aperture wiring push refuses one outright, and a Go host's hand-written providers are code no document describes.

So the two compose, additively:

• The database is authoritative. Every pushed entry is built.
• The local file may ADD an object type or an attribute slot the database never declared. It is built exactly as it would be on an instance that has never been pushed to, kind: csv and all.
• A local wiring entry for an object type or slot the database already declares fails the boot with APERTURE_WIRING_LOCAL_COLLISION, naming the entry and both sections.
• The two inline data sections are the exception, and they answer differently because the two seams resolve an overlap differently. A local objects: entry for a type the database serves is refused (APERTURE_CONFIG_INVALID naming the type): the object rule is a type-level discard, so a push on another host would switch off metadata checked into this instance's file. A local attributes: block for a slot the database declares is layered under it, not refused — the pushed row is the slot's shared layer, the inline bags its local one, the shared layer wins every key both serve and nothing is dropped, so a contested key reads the same on every instance. See Precedence: two layers, and the shared layer wins.

The collision is refused rather than resolved because both resolutions are silent and both change what a decision reads: the database winning would discard wiring somebody checked into this instance's file, and the file winning would mean one instance in the fleet answers from a source its peers cannot see. Neither shows up as an error later — it shows up as a different verdict. Fix it by deleting the local declaration, or by pushing a wiring document that omits the shared one.

connections: is the exception, in both directions: a local entry under a shared name is that name's route (see below) and not a competing declaration, and a local entry under a name the shared manifest never mentions is the route for a connection only this instance's own added providers reach. Both are carried.

A host that registers its own providers in Go gets the same answer from the same place — provider.Registry.Register refuses a second provider for a type it already serves, with APERTURE_PROVIDER_INVALID. The rule is about the registry, not about which syntax declared the entry.

A shared connection carries its name and nothing else: no DSN, no credential, not even the dsn_env: variable name. Each instance supplies its own route for a name, in one of three ways — a Go host's seed.WithConnectionOpener, a connections: entry under the same name in this instance's own seed file, or the conventional environment variable APERTURE_CONNECTION_<NAME>_DSN (every character that is not a letter or digit becomes an underscore, so main reads APERTURE_CONNECTION_MAIN_DSN). A name with no route at all refuses the boot with APERTURE_WIRING_CONNECTION_UNROUTED, naming the connection and the variable it wanted — every unrouted name in one refusal, so a new instance is configured in one pass rather than one restart per connection.

The wiring is read once, unless you ask for more

The read above happens at startup and only at startup. A aperture wiring push from another host is picked up by restarting the instances — which is what a deploy pipeline does anyway, and it is the whole story for a deployment with one instance.

A long-lived instance can be told to notice a push and adopt it instead, with serve --wiring-poll or APERTURE_WIRING_POLL. It is off unless configured, and off means no background reader and no periodic query, so an instance that cannot use it pays nothing for it. When it is on, an adopted push rebuilds the provider registry, the field types and the attribute providers as one version, a request pins one version at its entry, and the connection name set stays frozen for the life of the process — see What a swap replaces.

Unlike --enumerate-limit, it is not carried by every command that decides: it configures a process that outlives a decision, and there is no tick in the life of aperture check for one to happen on. It is declared on serve, and the whole account of it — the interval vocabulary, how a change is detected, what it costs, and what a shutdown does with a refresh still in flight — is on that page.

An instance will not start on wiring it cannot construct

A pushed entry whose kind: this instance cannot build from a row refuses the boot with APERTURE_WIRING_KIND_UNSHAREABLE, naming the object type or the attribute slot. In practice that is a stored kind: csv — aperture wiring push refuses one, so reaching a boot means the row was written by hand or by an older build, and there is no path: to add because the shared tables have no column for one. The other refusals a boot can raise come from the seed builders and already name the entry they refused: an incomplete statement set, an unparseable ttl:, a references: target no provider serves, a field_types: word outside date/datetime.

Refusing to start is the deliberate choice, and degrading is not the gentler option. An object type with no working provider does not error on a decision — a rule reading object.tier reads a missing path. An attribute slot with no working provider is worse: the leniency contract collapses the failure to an empty bag, so a rule that excluded on an attribute it can no longer see stops excluding, and the grant widens. Nothing in the resulting verdict, trace or note says a provider was missing. A per-decision refusal was rejected for the same reason: it would let a misconfigured instance keep serving traffic for the types it happened to have, so two instances that look identically configured answer one question two ways.

Scoping a decision: --account

--account names the active account a decision or mutation is scoped to. Its behaviour differs by command family:

• On the decision commands (check, enumerate, explain), --account defaults to acme (the example account) and bounds which grants the decision considers.
• On mutation, provisioning, and portability commands, --account has no default and is the active account used to resolve the acting principal's admin tier (account-admin vs system-admin). Several of those commands require it.

Aperture never lets one account's data surface in another account's decision, and error messages never leak cross-account detail.

The acting principal: --principal

This is the option most worth getting right.

On the read decision commands, the principal is a positional argument — the subject of the question you are asking:

bin/aperture check alice read account:acme/project:atlas/document:42
#                  ^^^^^ the subject principal, positional — NOT --principal

On the write / mutation commands (put, delete, bestow, revoke, impersonate, template, bulk, export, import), --principal is a flag that names the authenticated caller performing the mutation — who is acting, not who is being asked about. It is sourced from the APERTURE_PRINCIPAL environment variable, so you can set it once per shell:

export APERTURE_PRINCIPAL=root
bin/aperture put role --account acme --file ./role.json
bin/aperture delete grant g-old --account acme

A mutation with no --principal (and no APERTURE_PRINCIPAL) fails with APERTURE_UNAUTHENTICATED. A few commands name the acting principal with a purpose-specific flag instead — bestow/revoke use --delegator, and impersonate uses --operator — but each of those still reads from APERTURE_PRINCIPAL as its default source.

The deployment's enumeration ceiling: --enumerate-limit

--enumerate-limit (env APERTURE_ENUMERATE_LIMIT, default 1000) is the maximum number of object ids one enumeration may return, and the ceiling a larger request limit is clamped down to. It also bounds the scope member gather, so one number governs both halves of an enumeration.

It configures the process, not the command. Every command that decides carries it — check, enumerate, identifiers, explain, serve, mcp — and all of them resolve it identically, so one binary can never answer 1500 over HTTP and 1000 at the shell. Set it once in the environment:

export APERTURE_ENUMERATE_LIMIT=1500
bin/aperture enumerate alice list 'account:acme/**' --seed ./my-model.yaml
bin/aperture serve --seed ./my-model.yaml

The flag wins over the variable when both are given. A value that is not a whole number greater than zero — banana, 0, -5 — fails the command with APERTURE_CONFIG_INVALID naming the setting and the value it rejected, rather than silently falling back to 1000. To get the default, omit the setting.

On enumerate this is distinct from --limit, which caps a single request and is itself clamped by this ceiling. See Decisions.

Related

• Command-Line Reference — every command's full flag table.
• Decisions — where the principal is positional.
• Mutations — where --principal is the acting caller.
• First decision (CLI) — the note on subject vs actor, worked through.

Decisions

Audience: operators and integrators asking and auditing access-control questions from a shell.

The decision commands are the read-only core of the CLI. They never change the model — they ask a question of it. All three of check, enumerate, and explain take the subject principal as a positional argument (the principal the question is about), not a --principal flag; see Global options for why the write commands differ. identifiers inspects an object type's source.

All four build the same decision stack aperture serve does, so a question asked in a shell resolves exactly as it does over HTTP — see Rule-backed permissions.

check — decide one question

aperture check [options] <principal> <action> <object>

check prints a one-word verdict (allow / deny) and a reason, and carries the verdict in its exit code — 0 for allow, non-zero for deny — so it composes in a pipeline (aperture check … && deploy).

bin/aperture check alice read account:acme/project:atlas/document:42

allow
reason: allowed by grant g-eng-read-atlas (allow account:acme/project:atlas/**) at specificity 39300; 1 matching grant(s) considered

A question with no matching grant is always a deny — Aperture fails closed:

bin/aperture check bob write account:acme/project:atlas/document:42

deny
reason: default deny: no grant matched action "write" on "account:acme/project:atlas/document:42" for principal "bob" in account "acme"

Full flags: check.

Rule-backed permissions decide the same here as on the server

check, enumerate, identifiers and explain build the same decision stack aperture serve does: the object metadata declared in the seed's providers: and objects: sections, the rules engine over the stored rules, and scope resolution. A permission whose scope strategy is rule-backed (inclusive;rule=… / exclusive;rule=…) is therefore evaluated identically from the shell and over HTTP.

This was not always true. Before the shared stack landed, the one-shot commands wired no rules engine, so a rule-backed permission had no evaluator, the scope resolver reported APERTURE_SCOPE_RULE_UNCONFIGURED and the fail-closed policy turned that into a deny. If you scripted against the old behaviour, those checks now return the verdict the rule implies — which may be allow.

explain — why a decision resolved

aperture explain [options] <principal> <action> <object>

explain takes the same three arguments as check and prints the whole decision trace: the subject set, every grant considered, why each did or did not apply, and the deciding grant (marked *). It is a first-class operation, not a debug afterthought.

bin/aperture explain alice read account:acme/project:atlas/document:secret

Explain alice/read on account:acme/project:atlas/document:secret in account acme
  subjects: principal:alice, role:editor, group:engineering
  grants considered (3):
     g-eng-read-atlas [allow account:acme/project:atlas/**] allow covers the object via literal scope at specificity 39300
     g-editor-write-atlas [allow account:acme/project:atlas/**] action "write" does not match the requested "read"
   * g-deny-secret-read [deny account:acme/project:atlas/document:secret] deny covers the object via literal scope at specificity 60300
  verdict: DENY (top specificity 60300)
  reason: denied by grant g-deny-secret-read (deny account:acme/project:atlas/document:secret) at specificity 60300; 2 matching grant(s) considered

When a grant's scope is decided by a rule, the trace also carries the evaluation notes that rule recorded — a metadata field read with the wrong shape, or a match that happened only because the field was absent:

  evaluation notes (1):
     g-viewer-read [rule public-documents]: object.tags: expected collection, got string

Notes are diagnostic only; they never change a verdict, and they name paths and shapes, never metadata values.

Full flags: explain.

enumerate — list objects a principal may act on

aperture enumerate [options] <principal> <action> <pattern>

enumerate turns the question around: instead of one object, it lists the object ids under a <pattern> that the principal may take <action> on, one id per line. --limit caps the result count for this request, within the deployment's own ceiling — see --limit and the deployment's ceiling. Enumeration expands objects from the object sources the model declares — providers: (a file- or database-backed provider per type) and objects: (metadata declared inline) — so a model with neither (like the embedded example) yields an empty list. Run enumerate against a seed that declares an object source for the type.

bin/aperture enumerate alice read 'account:acme/project:atlas/document:*' \
  --seed ./model-with-providers.yaml --limit 100

--limit and the deployment's ceiling

Two numbers bound one enumeration, and they are not the same kind of thing:

The ceiling always wins:

• A --limit above the ceiling is clamped down to it.
• A --limit at or below the ceiling is honoured as asked.
• A --limit of zero or less asks for the ceiling. It does not mean "unlimited", and there is no spelling that does — enumerate never materialises an unbounded set.

# ask for 100 of the deployment's 1000
bin/aperture enumerate alice read 'account:acme/project:atlas/document:*' \
  --seed ./model.yaml --limit 100

# ask for 5000 against the default ceiling: you get 1000, not 5000
bin/aperture enumerate alice read 'account:acme/project:atlas/document:*' \
  --seed ./model.yaml --limit 5000

# raise the ceiling, then ask for all of it
bin/aperture enumerate alice read 'account:acme/project:atlas/document:*' \
  --seed ./model.yaml --enumerate-limit 2000 --limit 2000

The ceiling is the same number aperture serve honours — it configures the process, not the command — so the CLI and the server can never be bounded differently. check, explain, identifiers and mcp carry the same flag for that reason. See The deployment's enumeration ceiling.

A full-looking result may be a truncated one. Nothing in the output marks the difference: a list that stops at the ceiling looks exactly like a population that happened to end there. When a result comes back holding exactly its effective bound the engine logs a WARN naming that bound, so an unexpectedly round result is a reason to check the log and re-ask with a higher --enumerate-limit. The warning is a hint, not proof — a complete set of that size raises it too.

--limit is not the cheap knob. It shortens only the second half of the work: the candidate set is gathered against the ceiling first, and --limit then caps what survives the access decision. --limit 10 against a ceiling of 1000 still pays for ~1000 candidates. The number that moves the cost is --enumerate-limit, and Performance carries the measured price of raising it.

A value for --enumerate-limit that is not a whole number greater than zero — banana, 0, -5 — fails the command with APERTURE_CONFIG_INVALID naming the setting and the value it rejected, before any store is opened. To get the default, omit it.

Narrowing by object metadata

--field and --fields-json filter the listing by the objects' metadata — "which of the datasets I may list carry brand Y?". They apply on top of the access decision, so they can only ever remove objects from the list; an object a check would deny is never returned however the predicate is written.

The predicate is typed: a field matches only when its value equals the wanted value and is of the same kind, so the string "5" never matches the number 5. A shell flag only carries a string, and guessing which strings are "really" numbers would make enumerate return objects check then denies — so there are two flags rather than one, and each says what it sends:

Both may be given. --fields-json is merged first and --field entries then override it by key, so a stored JSON body can be reused with one value swapped from the shell.

# a string field
bin/aperture enumerate alice list 'account:acme/**' --seed ./model.yaml \
  --field tier=premium

# a list field, matched by MEMBERSHIP — "datasets carrying brand Y"
bin/aperture enumerate alice list 'account:acme/**' --seed ./model.yaml \
  --field brands=brand:Y

# seats is a NUMBER, so it needs the JSON spelling; --field seats=5 matches nothing
bin/aperture enumerate alice list 'account:acme/**' --seed ./model.yaml \
  --fields-json '{"seats":5,"active":true}'

# merged: seats from JSON, tier overridden from the shell
bin/aperture enumerate alice list 'account:acme/**' --seed ./model.yaml \
  --fields-json '{"seats":5,"tier":"basic"}' --field tier=premium

The rules the listing obeys:

• Predicates are ANDed — every one must hold.
• A list-valued field matches by membership; a whole list in --fields-json is a container compared by equality.
• A field the object does not carry never matches — not even against null.
• Filtering happens before --limit. --field tier=premium --limit 10 gives the first ten premium objects, not the premium ones among the first ten candidates.

A malformed predicate is a usage error (APERTURE_INVALID_INPUT) naming the offending text — a --field with no =, an empty key, a --fields-json that is not JSON or is JSON but not an object. It is never silently skipped: a dropped predicate would widen the result, and a filter that silently widens is a filter that authorizes. Parsing happens before the store is opened, so a usage error never boots a decision stack.

Filtering needs an object source for the type, exactly as enumeration itself does. A model that declares none reports APERTURE_PROVIDER_UNREGISTERED rather than printing nothing — an empty list would read as "no access". (Because the predicate is applied per candidate, you only see that error once the principal is allowed at least one object under the pattern.)

Restricting to what a reference names

--via asks the other direction. --field asks "which datasets contain brand Y?"; --via asks "which brands does dataset X list?".

bin/aperture enumerate alice read 'account:acme/brand:*' --seed ./model.yaml \
  --via account:acme/dataset:x.current_brands

It restricts the listing to the identities held in a declared reference field on one holder object — a references: block in the seed document (Declaring a reference) is what makes the field dereferenceable.

The two are not interchangeable, and the asymmetry is the reason --via exists. The dataset holds current_brands, so a predicate on dataset expresses "which datasets contain brand Y?" — that is --field. A brand holds no field naming its datasets, so no predicate on brand can express "which brands belong to dataset X?" at all. --field is a filter; --via is a dereference.

The spelling is <holder-identity>.<field>, split on the last . — a . is legal inside an identity component (dataset:2026.q1) while a reference field is a single metadata key, so the final dot is the only unambiguous boundary. The holder's type is deliberately not spelled: it is the identity's last segment type, which the engine derives itself, so the two cannot disagree.

The rules the restriction obeys:

• Repeatable, and edges are ANDed. Two --via flags give "the brands in dataset x and in campaign spring".
• It composes with --field, and both apply before --limit.
• It only subtracts. Restriction runs on candidates that still go through the access decision, so --via can never surface an object check would deny.
• Exactly one hop. The brands a dataset names are not themselves dereferenced, however many references brand declares.

A holder you may not read prints nothing and exits 0. That is deliberate, not a bug: "you may not see dataset X" and "dataset X lists nothing you may see" must not be tellable apart, or --via becomes a way to probe for objects you were never allowed to know about. The same goes for a holder in another account — empty whether or not it exists — and for a principal who is not a member of --account.

An absent holder is APERTURE_NOT_FOUND only when it is inside --account and the principal is a member of it. That is the ergonomics a typo deserves, confined to someone already inside the account.

A wiring fault stays loud rather than printing nothing: a field with no references: declaration is APERTURE_PROVIDER_REFERENCE_INVALID, and a holder type with no provider is APERTURE_PROVIDER_UNREGISTERED. A malformed --via — no ., an empty holder, an empty field — is APERTURE_INVALID_INPUT naming the offending text, rejected before the store is opened.

If a --via returns nothing you expected, check the server log first: a referenced identity the provider no longer serves is skipped with a warning naming it, and the commonest cause is an identity composed in the wrong shape (brand:1 where the deployment yields account:acme/brand:1).

Full flags: enumerate.

search — find an object by the name a person types

aperture search [options] <principal> <action> <pattern> <query>

search ranks every object under <pattern> that <principal> may take <action> on by how well its metadata matches <query>, best match first. It is the name-to-id lookup a surface does when a question arrives in a person's own words.

bin/aperture search alice read 'account:acme/brand:*' nike --seed ./catalogue.yaml
bin/aperture search alice read 'account:acme/brand:*' nike --in label --limit 5 --scores

Every result is one check would allow: candidates are decided before they are scored, by the same walk enumerate uses, so the output is always a subset of what enumerate returns for the same principal, action and pattern. A score ranks; it authorizes nothing.

Matching is case- and punctuation-insensitive (Nike, Inc. matches nike inc) and tolerates a typo or a transposition on tokens long enough for one to be unambiguous. Only text is matched — a string field and the string elements of a list field; match a number, bool or date with --field instead.

Aperture has no notion of a "label": a label is an ordinary metadata field whose name your host chose. Every field holding text is searched by default; --in names the fields to search, and --scores prints the score plus the field and value that produced each match — which is what tells a hit on an alias apart from a hit on a display name.

account:acme/brand:3	0.875	label=Nike, Inc.
account:acme/brand:1	0.800	label=Nike Air Max Collection

--field / --fields-json and --via mean exactly what they mean on enumerate, and they compose with the query: the predicate and the reference edge narrow the candidate set, the query ranks what is left. "The brand called Nike in dataset X" is one command.

--min-score drops weak matches (default 0.4). Raising it narrows the shortlist; it never widens what the principal may see.

--limit caps how many matches come back — the top of a finished ranking, not a bound on the scan, so you get the best N rather than the first N found. The scan itself runs to the deployment's --enumerate-limit ceiling; a scan that fills that ceiling is logged, because a better match may lie past it.

Because it needs object metadata to match against, search errors with APERTURE_PROVIDER_UNREGISTERED against a model that declares no object source — an empty list would read as "you may see nothing" and hide the misconfiguration.

Full flags: search.

identifiers — a type's valid instance ids

aperture identifiers [options] <object_type>

identifiers lists every valid instance id of an object type, read from the object source the model binds to that type — a providers: entry (a CSV file today, a data source later) or inline objects: metadata. --exclude drops ids from the result — this is how an exclusive "all except these" allowance expands into a positive allow-list. Because it needs a source, identifiers errors with APERTURE_PROVIDER_UNREGISTERED against a model that declares none, so run it against a seed that binds the type:

bin/aperture identifiers document --seed ./model-with-providers.yaml
bin/aperture identifiers document --seed ./model-with-providers.yaml --exclude secret

Full flags: identifiers.

Related

• Global options — --seed / --store / --account, and why the principal is positional here.
• First decision (CLI) — the same commands walked through against the example model.
• Mutations — change the grants these decisions read.
• Performance & the NFR — what the deployment's enumeration ceiling costs, measured.
• Command-Line Reference — the generated flag tables.

Mutations

Audience: administrators changing the Aperture model from a shell.

The mutation commands read and change the model: generic entity CRUD (put, get, list, delete), delegation (bestow, revoke), and impersonation (impersonate). Each builds the fully-wired facade — the same storage → engine → gate → delegation → impersonation → service graph the serve command mounts — so a CLI mutation is gated exactly as the HTTP/Twirp surface gates it. There is no CLI-only write path.

Every write command needs an acting principal: the authenticated caller performing the change, taken from --principal (or APERTURE_PRINCIPAL) — not a positional argument. The reads (get, list) need no actor. See Global options for the subject-vs-actor distinction, and set it once per shell:

export APERTURE_PRINCIPAL=root

Entity bodies are the canonical JSON encoding of the corresponding model.* struct — the same shape the Twirp entity_json field carries. Supply one with --json, --file, or on stdin (in that order).

Entity CRUD: put, get, list, delete

put <kind> creates or updates one entity; the admin tier it requires depends on the kind. It prints put <kind> ok.

bin/aperture put grant --account acme --json '{
  "id": "g-analyst-read",
  "accountId": "acme",
  "subject": {"kind": "role", "id": "analyst"},
  "permissionId": "perm-doc-read",
  "object": "account:acme/project:atlas/**",
  "effect": "allow"
}'

get <kind> <id> reads one entity as pretty JSON (no actor, no tier):

bin/aperture get grant g-eng-read-atlas

{
  "ID": "g-eng-read-atlas",
  "AccountID": "acme",
  "Subject": { "Kind": "group", "ID": "engineering" },
  "PermissionID": "perm-doc-read",
  "Object": "account:acme/project:atlas/**",
  "Effect": "allow"
}

list <kind> lists entities of a kind as JSON. Listing grants requires --account (grants are per-account); the other kinds do not:

bin/aperture list principals
bin/aperture list grants --account acme

delete <kind> <id> removes one entity, gated by the kind's tier; it prints delete <kind> <id> ok. Memberships are keyed by (principal, account) rather than a single id, so delete membership takes --principal-id and --account-id instead:

bin/aperture delete grant g-analyst-read --account acme
bin/aperture delete membership --account acme \
  --principal-id bob --account-id acme

Full flags: put, get, list, delete.

Delegation: bestow and revoke

bestow lets a principal delegate a grant it already holds to another principal. Unlike put grant, it is not gated by an admin tier — it enforces the delegation subset rule: you can only bestow authority you hold, over a delegatable permission. The delegating principal is named by --delegator (env APERTURE_PRINCIPAL); the grant body is a normal grant JSON. It prints bestow <grant-id> ok.

bin/aperture bestow --delegator alice --json '{
  "id": "g-bob-read-42",
  "accountId": "acme",
  "subject": {"kind": "principal", "id": "bob"},
  "permissionId": "perm-doc-read",
  "object": "account:acme/project:atlas/document:42",
  "effect": "allow"
}'

revoke is the inverse: it removes a grant the delegator previously bestowed, by id. It prints revoke <grant-id> ok.

bin/aperture revoke --delegator alice --grant g-bob-read-42

Full flags: bestow, revoke.

Impersonation: impersonate

impersonate starts a time-boxed session in which an --operator acts as a --target within --account, and prints the session as JSON. --mode is augment (add the target's authority to the operator's — the default) or become (resolve purely as the target). It is guarded: an operator with no right covering the target is denied with APERTURE_IMPERSONATION_DENIED.

bin/aperture impersonate --operator root --target alice --account acme --mode augment

Full flags: impersonate.

Related

• Global options — --principal / --account / --seed / --store.
• Decisions — check the effect of a grant you just changed.
• Provisioning — apply many grants at once via templates or bulk.
• Portability — move a whole model between stores.
• Command-Line Reference — the generated flag tables.

Provisioning

Audience: administrators granting access at scale from a shell.

The provisioning commands turn repeated grant-making into one transactional call: template manages and applies parameterized grant bundles, and bulk applies or removes many grants atomically. Both build the same fully-wired, tier-gated facade the mutation commands use, and both need an acting principal via --principal (or APERTURE_PRINCIPAL) plus, in most cases, --account. Set the principal once:

export APERTURE_PRINCIPAL=root

template — parameterized grant bundles

aperture template <put|get|list|delete|apply>

A template is a named, versioned bundle of grants with named parameters. The subcommands split into CRUD and apply:

template apply binds --param name=value (repeatable) into the template and writes the resulting grants in one transaction; --id-prefix prefixes the generated grant ids, and --version 0 (the default) applies the latest. It prints the applied grants as JSON.

# Define a template (system-admin tier):
bin/aperture template put --account acme --file ./project-onboarding.json

# Apply it into an account, binding parameters (account-admin tier):
bin/aperture template apply --account acme \
  --name project-onboarding \
  --param project=atlas \
  --param team=engineering \
  --id-prefix onboard-

Full flags: template.

bulk — many grants in one transaction

aperture bulk <grant|revoke>

bulk grant applies a JSON array of grant bodies atomically — either all land or none do — from --json, --file, or stdin. It prints bulk grant <n> ok.

bin/aperture bulk grant --account acme --json '[
  {"id":"g-a","accountId":"acme","subject":{"kind":"role","id":"analyst"},"permissionId":"perm-doc-read","object":"account:acme/project:atlas/**","effect":"allow"},
  {"id":"g-b","accountId":"acme","subject":{"kind":"role","id":"analyst"},"permissionId":"perm-doc-write","object":"account:acme/project:atlas/document:42","effect":"allow"}
]'

bulk revoke deletes many grants atomically by id. Ids come from repeated --grant flags, positional arguments, or both; it prints bulk revoke <n> ok.

bin/aperture bulk revoke --account acme --grant g-a --grant g-b
# or positionally:
bin/aperture bulk revoke --account acme g-a g-b

Both bulk subcommands are account-admin tier.

Full flags: bulk.

Related

• Global options — --principal / --account / --seed / --store.
• Mutations — single-entity put / delete and delegation.
• Portability — export/import a whole model at once.
• Command-Line Reference — the generated flag tables.

Portability

Audience: administrators moving or backing up a whole Aperture model.

export and import are the declarative-state commands: export serializes the entire model to a single JSON/YAML state file, and import applies such a file back as an idempotent, transactional upsert. Both are system-admin tier and drive exactly the path the Twirp Export / Import RPCs drive, so they need an acting principal via --principal (or APERTURE_PRINCIPAL) and --account for authority resolution:

export APERTURE_PRINCIPAL=root

export — serialize the whole model

aperture export [options]

export writes the full model to stdout by default, or to --out <path>. The format is JSON unless you pass --format yaml (or --out a .yaml/.yml path). Writing to a file prints a one-line summary; writing to stdout emits the raw document.

# To stdout as JSON:
bin/aperture export --account acme --principal root > model.json

# To a YAML file (format inferred from the extension):
bin/aperture export --account acme --principal root --out model.yaml

exported <model summary> -> model.yaml

Full flags: export.

import — apply a state file

aperture import [options]

import reads a state file from --file <path> or, when no file is given, from stdin (treated as JSON). It applies the document as an idempotent upsert in one transaction — re-importing the same file is a no-op — and prints a one-line summary. The file format is inferred from the --file extension.

# From a file:
bin/aperture import --account acme --principal root --file model.yaml

# From stdin (JSON):
bin/aperture export --account acme --principal root \
  | bin/aperture import --account acme --principal root

imported <model summary>

Round-tripping through export | import — or between two --store DSNs — is the supported way to snapshot, back up, or migrate a model. Because both ends run as a system-admin actor scoped to --account, no cross-account data crosses the boundary implicitly.

Full flags: import.

Related

• Global options — --principal / --account / --store for the source/target store.
• Provisioning — apply incremental grants rather than a whole model.
• Mutations — single-entity edits.
• Command-Line Reference — the generated flag tables.

Attributes

Audience: operators who need to know which host directories a deployment reads principal.* and account.* out of — and how fast a revocation lands.

An attribute slot is a host directory: the user table, the service-account registry, the tenant catalogue. There are exactly three — user, machine, and account — and each caches the bags it has fetched, with its own ttl: and max_size:. See Providers for the seam itself and Seed & portability for the YAML that wires it.

aperture attributes <slots|query|invalidate>

All three read through the same wiring builder every other command uses, so the slots a listing reports are the slots a decision resolves through: the CLI cannot describe a wiring it does not itself run. All three therefore take --seed (and --store) exactly as check does.

The cache window is a security property

Object metadata going stale for a TTL is usually tolerable — a document's category is a fact about a thing. An attribute bag is the asker's standing: the clearance, the department, the plan. Until a cached bag expires, every decision about that subject keeps evaluating against access the host may have already taken away, so a revocation that takes effect ttl: later is a revocation that has not happened yet.

That is the frame for both of the interesting columns below and for the whole of invalidate: pick a slot's ttl: for how fast its revocations must land, read back what the deployment is actually running, and close the window explicitly when you cannot wait.

slots — what is wired, where from, and how stale it may be

bin/aperture attributes slots --seed ./seed.yaml --store 'postgres://…/acme'

slot     layer   source                ttl    max-size  cached
user     shared  sql (shared wiring)   1m0s   10000     15
user     local   inline (--seed file)  never  10000     -
machine  shared  csv (--seed file)     30s    10000     0
account  -       (unwired)             -      -         -

One row per LAYER, not per slot. A slot has two registration layers and each one caches on its own declaration, so a single row could only report one of two revocation windows — and it reported the winner's, which is the wrong number for every key only the other layer serves. The layers are printed in precedence order, highest first.

• layer is shared or local. An attribute_providers: entry fills the shared layer and an attributes: block fills the local one; a fetch reads their merge and the shared layer wins every key both serve, so nothing is discarded and the inline bags still contribute the keys the external source does not carry. A slot with no source at all reads -.
• source names the kind and the place: sql/csv for an attribute_providers: entry, inline for the attributes: block, then (shared wiring) for a row in the deployment's database — put there by aperture wiring push and read by every instance — or (--seed file) for this instance's own document. (host) is a provider the binary embedding Aperture registered in Go, which no document describes. (unwired) is a slot this deployment declares nothing for: not an error, and not an empty directory — every decision for it resolves the floor bag and proceeds.
• ttl is the revocation window, and there is one per layer. never means a fetched bag is dropped only by eviction or by an explicit invalidate — correct for a fixed inline block, dangerous for a live directory. Two layers are two caches and never an average: a shared directory on a one-minute window beside an inline block that never expires leaves every key only the inline block serves cached indefinitely, and a listing that reported 1m for the slot would tell an operator who had just revoked something that the window was closed.
• cached counts this process, for the whole slot. The counters are kept per slot and summed across its layers — a subject both layers serve is held twice, because it is cached twice, and two ttls will expire it — so the number appears once, on the slot's first row, and reads - on the second layer's. A one-shot invocation starts cold and reads 0; it is the number that matters in a long-running serve.

slots needs no actor. It discloses nothing the caller did not already supply: it reads the seed file named on the command line, the shared wiring rows in the --store named beside it, and the cache configuration this process built from the two. It contacts no provider, names no key, and prints no bag. Requiring system-admin authority to read back a file you just passed in would only mean nobody could diagnose "is the user slot even wired?" without already holding the authority the diagnosis exists to explain — and the wiring half needs no gate for the reason aperture wiring show needs none: the --store credential already grants full write access to those rows.

When a deployment declares one slot in both attribute_providers: and attributes: — in one file, or with the entry pushed and the block local — every command that builds the stack prints a warning naming the affected slots. Nothing is discarded: the attribute_providers: entry is that slot's shared layer, the inline bags layer under it, and the shared layer wins every key both serve. The warning exists to say which layer answers a contested key — the one thing no verdict, trace or note says. Only slot names are named, never keys. See Precedence: two layers, and the shared layer wins.

query — read a directory (system-admin)

bin/aperture attributes query user \
  --principal alice --account acme \
  --field department=eng --fields-json '{"clearance":3}' --limit 100

Prints a JSON array of {id, attributes}.

Unfiltered, this returns the head of the host's user table — keys and bags together — so it is a system-tier read: --principal must hold system-admin authority in --account. A refusal returns nothing: no partial page, no count, and no way to tell an empty slot from a full one or from an unwired one. That is deliberate — the authority check runs before the slot name is even parsed, so a refused caller cannot use the error to probe which directories a deployment wires. If a refusal is unexpected, ask aperture explain about your own authority.

--field and --fields-json narrow by attribute, on exactly the predicate aperture enumerate applies to object metadata: predicates are ANDed, a field the bag does not carry never matches, a list-valued field matches by membership, and everything else matches by typed equality, so the string "5" never matches the number 5. --field always sends a string; reach for --fields-json when a number, bool, or list is genuinely meant. Given both, --fields-json is merged first and --field entries override it by key.

A slot whose attribute_providers: entry declares no get_all: is fetch-only by design — it answers the decision path without exposing the whole table to an enumeration — and query reports that provider's coded refusal rather than an empty page.

invalidate — close the window now (system-admin)

bin/aperture attributes invalidate user --id alice --principal root --account acme
bin/aperture attributes invalidate user --principal root --account acme
bin/aperture attributes invalidate --all --principal root --account acme

The three forms — one subject, one slot, everything — are mutually exclusive, and a conflict is refused rather than resolved by precedence: "--all plus a slot" has two plausible readings, and guessing the broader one would clear caches the operator did not ask to clear.

"Nothing was cached" is reported, not silently succeeded (no cached user bag for "alice"): an operator invalidating a subject they believe is cached wants to know their key did not match. Note that --id takes the bare subject id — alice, never user:alice.

Every form clears both layers of every slot it names. A slot fed by an external source and an inline block caches each independently, and dropping one would leave the revoked value still being read out of the other — a window reported shut with half of it open.

It is gated for the same reason query is, even though it writes nothing and discloses no bag: the result says whether this process had that key cached, which is a fact about who has recently been decided about, and clearing a large slot costs the next wave of decisions a provider round-trip each. invalidate --all names no slot, so it cannot be used to probe which exist.

Invalidation is process-local. It clears the caches of the process that runs it. That makes it exact for a host embedding Aperture, and self-contained for a one-shot CLI invocation (which starts cold and exits cold) — but it cannot reach a running aperture serve. The controls that reach that process's cache are the slot's ttl: and a restart.

Full flags: attributes.

Related

• Global options — --principal / --account / --seed / --store.
• Providers — the attribute seam, its leniency contract, and why enumerating a slot can never be scope resolution.
• Seed & portability — the attributes: and attribute_providers: blocks these commands report on.
• Rules engine — what a rule reads when a slot answers nothing.
• Command-Line Reference — the generated flag tables.

wiring

Audience: operators who deploy Aperture, and anyone answering "is what is deployed what is in the repository?".

aperture wiring is the operator's window onto shared wiring: the part of a seed document that belongs to the deployment rather than to one instance. Push it once and every instance sharing that database reads the same wiring — including an instance that has no seed file at all.

Four subcommands, and the tree is complete:

All four take --store and no acting principal. The store credential is the authority, exactly as it is for import, and the three read commands restate wiring that credential already grants full write access to. --store has no default on any of them: an in-memory store is private to the process that opened it, so there is nothing shared about its wiring to write or to read.

Throughout, the deployment is the house example: one account, acme, whose objects are spelled account:acme/project:atlas/document:42.

Four sections are shared and two are local

A seed document's ten model-state sections are applied by --seed (or import). Its six wiring sections say where a decision reads object metadata and subject attribute bags from, and they split four/two:

The line is a pointer to data versus the data itself. A providers: or attribute_providers: entry says where to read metadata or an attribute bag from; a field_types: entry says how to read a field; a connections: name says which pool an entry cites. All four describe the deployment and all four are safe to copy to a second host. An objects: entry carries the metadata and an attributes: entry carries the bag — and Aperture's own database is never the source of truth for a host's domain data. Those two are not waiting for a later release; there is nowhere for them to go.

Wiring is also not model state, and the two are pushed by different commands. aperture export emits the model and no wiring; aperture wiring pull emits the wiring and no model. Wiring for a model that is not there is refused rather than stored — see push.

What is never stored

No DSN, no credential, not even the name of the environment variable holding one, and no filesystem path. This is a property of the schema — there is no column for any of it — rather than of a validator, and it is the reason the surface is safe at all:

• A row is copied to a second instance that resolves its own credentials, so a secret column would put a credential in every backup of this database.
• A path column would be a guess about another host's disk. A relative path: is resolved against the seed file's directory, which database-sourced wiring has none of.

kind: csv is therefore refused by push (APERTURE_WIRING_KIND_UNSHAREABLE), and stays perfectly legal in a local seed file — the instance that reads the path is the instance the path belongs to.

A shared connection carries its name, and each instance supplies its own route for that name: seed.WithConnectionOpener in a Go host, a connections: entry under the same name in this instance's own seed file, or the conventional APERTURE_CONNECTION_<NAME>_DSN. That is why a pulled document comes back with an empty dsn_env: for every connection: it is re-pushable but not bootable until the routes are filled in. The three routes are set out in full under It means the same thing for wiring.

push — deploy a document's shared wiring

aperture wiring push --store <dsn> --seed <file>

Reads providers:, field_types:, connections: and attribute_providers: out of --seed, validates every entry, and replaces the store's wiring with them in one transaction. The document's other sections are not read: no model state is applied, and the two local wiring sections are untouched.

bin/aperture wiring push --store 'postgres://…/acme' --seed model.yaml

The push is all or nothing. Every rule is checked before anything is written, so a refusal leaves the deployed wiring exactly as it was. Wiring is only meaningful whole — an entry citing a connection the manifest does not list is not half-valid wiring, it is broken wiring — and an instance booting against a half-written set would build a registry missing exactly the entries whose write failed, while reporting nothing.

It replaces rather than merges. An entry dropped from the document is dropped from the store. Push the whole wiring every time. There is deliberately no per-row edit.

A push is refused when:

An all-empty document is refused

Because a push replaces, a document with no wiring in it is not "nothing to do" — it retires every entry the deployment is running. All five tables are emptied and every instance goes back to building its wiring from its own --seed file; an instance with no --seed file, which is the shape this whole feature exists to enable, then builds none. It still starts, with an empty object registry and an empty attribute registry. Every attribute slot is unregistered, an unregistered slot answers with an empty bag, and a rule that excluded on an attribute it can no longer see stops excluding — so the grant widens, with nothing in a verdict, a trace or a note to say so. Under --wiring-poll it lands without a restart.

The two documents that produce an empty set are indistinguishable from the store's side and both are usually mistakes: the wrong --seed path, and a file whose section key is mistyped. provider: for providers: is not an error — the seed reader does not refuse unknown keys, so the section is simply not there.

Retiring a deployment's wiring is a legitimate act, so --allow-empty says it deliberately; the summary then spells out what was retired, because five zeroes read as a summary rather than as a retirement.

A key that names no section is reported

The refusal above only fires when the document has no wiring at all. A partial retirement — one mistyped key in a document that still declares other sections, so the set is not empty and the push legitimately proceeds — is invisible to it, and from the store's side indistinguishable from deliberately dropping an entry.

So push warns about every top-level key that names no section, before it writes:

warning: wiring.yaml carries 1 top-level key(s) that name no section: provider
         Nothing was read from them. If one is a mistyped wiring section, the push below
         retires that section for every instance of the deployment.

It is a warning and never a refusal, because a document may legitimately carry keys Aperture does not know — another tool's section, or a key from a newer Aperture than the binary reading it — and refusing those would break files that work today. Only the key names are printed: a value under an unknown key could be anything, including a credential somebody put in the wrong place.

diff is the other half, and the one that catches a section dropped without a typo.

A push is audited: one WiringPush mutation record against model.AccountWildcard, carrying the per-section counts and the deployed connection names, object types and attribute slots. All of that is deployment-wide wiring vocabulary; none of it is account data.

Full flags: wiring push.

show — read what is deployed

aperture wiring show --store <dsn>

Prints the five shared-wiring tables, one table per section, so "what is this deployment actually wired to?" is answerable without a database client. It takes no --seed: a listing that merged the document on the command line would answer "what would a push deploy?" while looking like it answered this question.

bin/aperture wiring show --store 'postgres://…/acme'

An empty store is an answer, not an error. A store nothing has been pushed to says so plainly, and every instance booting against it builds its wiring from its own --seed file instead. It is also what a mistyped --store looks like, because a DSN naming a database that does not exist yet is one Setup creates — so check the DSN before concluding a push was lost.

Two columns are spelled as words rather than left blank. ttl and max-size read (default) when the entry sets neither, because the registry's own default applies and 0 would read as "caches nothing". The declared key set distinguishes three states: (not declared) is a slot that opted out of key enforcement entirely, (declared empty) is a slot that opted in and permits no keys at all, and a list is the keys the slot guarantees.

Full flags: wiring show.

pull — snapshot what is deployed to a file

aperture wiring pull --store <dsn> --out <path> [--format json|yaml] [--force]

Reads the deployed wiring in one atomic snapshot and writes it as the same four sections a push reads. The file is a seed document push accepts unchanged, so push → pull → push deploys identical wiring, and two pulls of an unchanged deployment are byte-identical.

bin/aperture wiring pull --store 'postgres://…/acme' --out deployed.yaml
diff -u model.yaml deployed.yaml

show is the better command for reading; this one produces a file for a tool. Three behaviours are worth knowing before you script it:

• The file is re-pushable but not bootable. Every connection comes back with an empty dsn_env:, because shared wiring holds a name and nothing else. Fill the routes in from your own deployment's environment before booting an instance from the file; one built from it as written refuses at registry build and names the unset variable.
• An existing --out file is refused unless --force is given (APERTURE_WIRING_OUTPUT_EXISTS). The likeliest thing at that path is the version-controlled document the pull is meant to be compared with. The path is checked before the store is opened, so the refusal reads nothing.
• A store with no wiring deployed is refused (APERTURE_WIRING_NOTHING_DEPLOYED) — the one place pull disagrees with show. A pull's file exists to be pushed back, and an empty one pushed back replaces the deployment's wiring with nothing.

Full flags: wiring pull.

diff — compare the deployment against the repository

aperture wiring diff --store <dsn> --seed <file>

Names, per section and per entry, what is only deployed, what is only local, and what differs. The section column is the document's own section key, so a reported entry is one you can go and find. Nothing is written, to the store or to a file.

bin/aperture wiring diff --store 'postgres://…/acme' --seed model.yaml

It is meant for a pipeline, and the exit codes are the interface:

Drift is the answer to the question asked, not a failure to answer it, so it carries no APERTURE_* code — there is no remedy for a report, and which side is wrong is your call. It follows check's precedent: a clean DENY prints its verdict and exits non-zero, because a verdict is not an error either.

The code is 2 and not 1, and that is the useful half. Every coded refusal this binary makes exits 1, so a gate that failed closed on 1 and 2 alike would report drift for a typo in its own DSN.

Two more properties keep a gate green when it should be:

• Formatting is never drift. Both sides are compared as wiring, in the one canonical order a read returns, so re-ordering the document's entries, re-ordering a fields: or references: map, or re-indenting the file changes nothing. The push timestamps are excluded too — a stamp is a fact about the last push, not about the wiring.
• A kind: csv entry is reported as local-only by design, not as drift and not as an error. No push can make the deployment match it, so counting it as drift would leave a permanently red gate on every deployment that legitimately keeps a local csv provider — and a gate that cannot go green is a gate somebody switches off.

Make the deployment agree with the document by pushing it.

Full flags: wiring diff.

Booting against pushed wiring

An instance reads the shared wiring at startup, and what it does with what it finds is documented once, under Global options:

• Empty tables mean "use the local file" — an answer, not a failure, and the state of every deployment that has never pushed.
• With both, the database wins and the file may only ADD — a collision is refused in both directions with APERTURE_WIRING_LOCAL_COLLISION, because either precedence is silent and either one changes what a decision reads.
• An instance will not start on wiring it cannot construct — refusing to boot beats degrading, because a missing provider does not error on a decision and a missing attribute bag widens an exclusive grant.
• The wiring is read once, unless you ask for more — serve --wiring-poll is opt-in and off unless configured; see Noticing a push without a restart.

Related

• Two instances, one store — the four steps of standing up a second instance against a database that already has one.
• Seed & portability — the six sections, and the three read-backs that answer three different questions.
• Storage — the five apt_wiring_* tables and what they may never carry.
• Global options — --seed / --store, and what an omitted --seed means for wiring.
• Portability — export / import, the model half of the same story.
• Command-Line Reference — the generated per-command flag tables.

serve

Audience: operators running Aperture as a long-lived service.

aperture serve [options]

serve hand-wires the full dependency graph (storage → engine → service → HTTP handler) and boots a net/http server exposing the HTTP + Twirp API and the admin UI. It shuts down gracefully on SIGINT / SIGTERM, draining in-flight requests within a 10-second window. This is the same fully-wired facade the mutation CLI commands build — the server just puts it behind a listener and an authenticator.

bin/aperture serve --addr :8080

aperture serving on :8080

Press Ctrl-C to trigger a graceful shutdown (shutting down...).

What the flags control

• --addr — the TCP address to listen on (default :8080).

• --seed / --store — the model to serve, exactly as elsewhere (see Global options). With no --store, the server runs against an in-memory model seeded from --seed or, when that is omitted too, the embedded example — the zero-flag demo. With a --store DSN and no --seed, nothing is seeded: the server reads the model already in that database and writes no model rows on startup. See Booting against a database below.

• --auth — the authenticator adapter that maps each request to a principal: dev (the default — the bearer token is the principal id, no external IdP), oidc, or parsec. It overrides the APERTURE_AUTH_MODE env var. Because the default is dev, serve runs with no external identity provider out of the box; oidc and parsec are opt-in.

• --enforce-membership — defence-in-depth: deny any decision whose principal is not a member of the active account before grants are consulted. This lets a single shared role (manager, analyst, …) be reused across accounts without one account's grants leaking to another's members. Also settable via APERTURE_ENFORCE_MEMBERSHIP.

• --wiring-poll — re-read the shared wiring tables on an interval instead of only at startup, so a aperture wiring push from another host is picked up without a restart. Omitted means off, and off means off: no background reader is started and no periodic query is made. Also settable via APERTURE_WIRING_POLL; the flag wins when both are given. See Noticing a push without a restart below.

• --enumerate-limit — the ceiling one Enumerate is bounded by: the number a request with a non-positive limit receives, and the number a larger request limit is clamped down to. It also bounds the scope member gather, so the gather and the result cap are one value. Unset leaves the engine on its documented default of 1000. Also settable via APERTURE_ENUMERATE_LIMIT; the flag wins when both are given.

  bin/aperture serve --enumerate-limit 1500
  APERTURE_ENUMERATE_LIMIT=1500 bin/aperture serve
  

  It is not a serve flag. It describes the deployment, not the server, so the same flag and the same variable are carried by check, enumerate, identifiers, explain and mcp, and all of them resolve it identically — one binary cannot be configured to answer 1500 over HTTP and 1000 on the command line. The wiring lives in the decision stack every command builds, not in serve's own options (which hold only --enforce-membership, a posture that really is the server's alone).

  APERTURE_ENUMERATE_LIMIT=1500 bin/aperture enumerate alice list 'account:acme/**'
  

  A value that is not a whole number greater than zero fails the command with APERTURE_CONFIG_INVALID naming the setting and the value it rejected — under serve, before the store is opened — rather than quietly serving the default. That covers banana, and it covers 0 and -5 too: the engine's WithEnumerateLimit normalises a non-positive bound to the default, which is the right answer for a Go embedder passing a computed number and the wrong one for a human who typed one. An operator who wrote -5 would be served 1000 while believing otherwise, so the CLI refuses at the boundary what the library would have absorbed. To get the default, omit the setting.

Booting against a database

serve with a --store DSN and no --seed seeds nothing. It runs Setup (which creates missing tables and never migrates), reads the model that is already there, and writes no model rows of its own.

# A second instance, against a database another process provisioned:
bin/aperture serve --store 'postgres://aperture@db/aperture'

This is what makes a long-lived deployment safe and what lets two instances share one database. Passing a --seed alongside a durable --store still applies that document in full, on every boot — which is how you provision a database on purpose, and which two instances pointed at the same database must not both do, or each restart re-asserts one instance's model over the other's.

# Provisioning, deliberately and once:
bin/aperture serve --store 'postgres://aperture@db/aperture' --seed ./model.yaml

Where its wiring comes from

Seeding nothing is not the same as being wired by nothing. After Setup, serve reads the shared wiring tables and builds its object providers, field types and attribute slots from them — so an instance with a --store DSN and no seed file on disk at all is a fully wired instance.

When those tables hold no rows — every deployment that has never run aperture wiring push — the local seed file's wiring is used exactly as it always was. There is no flag and nothing to configure; see What an omitted --seed means for the whole rule, including how a shared connection name is routed to this instance's own DSN.

With both — wiring rows and a --seed file — the database is authoritative and the local file may only ADD. A local providers:, field_types:, attribute_providers: or attributes: entry for an object type or slot the database never declared is built normally, which is how a kind: csv provider (a path cannot be shared wiring) and a Go host's hand-written providers survive a push. A local wiring entry for one the database already declares fails the boot with APERTURE_WIRING_LOCAL_COLLISION naming it, rather than one side quietly winning — with one exception: a local inline attributes: block for a slot the database declares is layered under the pushed row rather than refused, because the shared layer wins every key both serve and nothing is dropped. See With both, the database wins and the file may only ADD.

Noticing a push without a restart

The wiring read above happens once, at startup. That is the whole behaviour unless you ask for more, and for most deployments it is the right one: a wiring push is picked up by restarting the instances, which is what a deploy pipeline already does.

--wiring-poll (env APERTURE_WIRING_POLL) turns on a background re-read:

bin/aperture serve --store 'postgres://aperture@db/aperture' --wiring-poll 30s
bin/aperture serve --store 'postgres://aperture@db/aperture' --wiring-poll on
APERTURE_WIRING_POLL=2m bin/aperture serve --store 'postgres://aperture@db/aperture'

Anything else — banana, -5m — fails the command with APERTURE_CONFIG_INVALID naming the setting and the value it rejected, before any connection is made, so a typo costs nothing but the typo.

When it is on, the instance reports it on stderr at startup and reports each change it sees:

wiring poll: re-reading the shared wiring every 30s; a change will be adopted and reported here
wiring poll: the deployed wiring CHANGED (3f9a1c72 -> 8b40e5de) and this instance
ADOPTED it; decisions already in flight finish on the wiring they started with

What a swap replaces, and what it does not

An adopted change rebuilds everything a decision reads: the object provider registry, the field-type declarations folded into it, the attribute providers, the rules engine over them, the decision engine and the service facade. They are built as one version and installed with a single pointer store, so a decision either sees all of a push or none of it — never half.

• A request pins one version at its entry and finishes on it. A push landing mid-request does not change what that request decides.
• A decision never blocks on a wiring read. The rebuild happens on the poll goroutine; a request pays one atomic load.
• Attribute caches do not survive a swap. Each version gets fresh per-slot caches, so a rebuilt slot never answers from an entry fetched under the old configuration's ttl: — which is the window a revoked clearance would otherwise keep authorizing for.
• The connection name set is frozen for the life of the process — see below.
• The local --seed file is RE-READ. A rebuild goes through the same builder the boot did, and that builder parses the file from disk again. So the two local sections — inline objects: metadata and inline attributes: bags — and the declared attribute-key sets taken from them are whatever the file says now, not what it said at startup. A file rewritten in place since the boot (a ConfigMap volume remount, a redeploy that only updates a mounted file) therefore takes effect on the next swap instead of needing a restart. That is usually what you want, and it is worth knowing it is not opt-in: the trigger is any shared push, so an unrelated push is what makes a local edit live.
• A failed rebuild installs nothing. The instance keeps the wiring it has and goes on deciding, the digest does not advance, and the next tick tries again:

wiring poll: the deployed wiring CHANGED (3f9a1c72 -> 8b40e5de) but this instance
could not adopt it, so it keeps the wiring it has and goes on deciding: [...]

The listener, the authenticator and the HTTP server itself are built once and are untouched by a swap; only what sits beneath them is replaced.

Two digests: the shared set, and this instance's own file

WiringPosture.Digest, and the two short hashes in the lines above, are digests of the shared wiring — the five tables — and of nothing else. That is exactly the right handle for "did this instance get the push?", and comparable with what aperture wiring diff reports. Nothing local is folded into it, ever: a value mixed with per-instance content would match neither a push nor a wiring diff.

WiringPosture.LocalDigest is the other half: a digest of the local document the version this instance is deciding through was built from — its own --seed file — and empty when it has none, which is every instance wired only from the shared tables. It exists because a rebuild re-reads that file, and the file decides things (inline objects: metadata, inline attributes: bags, the declared key sets taken from them, and on a deployment that has pushed nothing at all the whole of the wiring). Without it, two instances could report the identical Digest and still return different verdicts.

So the fleet sweep is on both:

Two properties of LocalDigest are worth knowing before you build a check on it:

• It tracks the version this instance is RUNNING, not the file as it is on disk right now and not what the process booted on. A local edit is adopted on the next swap (see above), and the digest moves at that moment — which is what makes it honest: it always names the document the current answers are coming from.
• It is a content digest. A reformatted, re-indented or comment-stripped file that means the same thing digests the same, so a pipeline that regenerates the document does not show up as drift. Both digests are hashes and carry no path, no account, no principal and no object data.

The connection name set needs a restart

The shared tables carry a connection's name and nothing else. Which server, which credential, how big a pool and how long a statement may take are per-instance facts, and this instance resolves them once, at boot — from a Go host's seed.WithConnectionOpener, from a connections: entry in its own --seed file, or from the conventional APERTURE_CONNECTION_<NAME>_DSN. See Where its wiring comes from.

That makes the name set a boot-time contract between the shared manifest and the routes this instance can supply locally, and not a runtime one. A running process cannot conjure a route for a name that appeared while it was working, and draining a pool for a name that vanished is a different problem from adopting wiring. So the name set is frozen for the life of the process, and a push that changes it in either direction is detected, reported, and not applied:

wiring poll: the deployed wiring CHANGED (3f9a1c72 -> 8b40e5de) but this instance
could not adopt it, so it keeps the wiring it has and goes on deciding:
[APERTURE_WIRING_RESTART_REQUIRED] cli: the deployed wiring changes this
instance's connection NAME SET — it adds connection name "replica" — and that set
is FIXED for the life of a process: [...] RESTART THIS INSTANCE to adopt the push.

Three things follow, and they are the whole of the behaviour:

• The rest of the push is held, not applied. A push is adopted whole or not at all, so the providers, field types and attribute providers deployed alongside a connection change stay outstanding with it. Applying the parts that happen to fit would leave this instance running a wiring version that was nobody's.
• Nothing is torn down. A name the push removed keeps its pool, and this instance goes on deciding through it. The pools belong to the boot and are closed once, on shutdown.
• The instance keeps deciding, and keeps re-reporting. The digest does not advance, so the condition is re-detected on every tick until the push is adopted or corrected — which is the noisy direction on purpose.

The remedy is a restart, after supplying a route for each added name — in that order, which is why it is a three-step rollout and not a push: Refreshing wiring on a live fleet. Read what the deployment expects with aperture wiring show; the fixups on APERTURE_WIRING_RESTART_REQUIRED name each added and dropped name, and the ones on the boot-time APERTURE_WIRING_CONNECTION_UNROUTED list the three routes.

Choosing an interval

The interval is the window a fleet is allowed to disagree with itself: from the push until this instance re-reads and adopts, it is still answering from the wiring it booted on. That makes it the same kind of number as an attribute slot's ttl: — a bound on how long a revoked thing keeps being honoured — and not a performance knob.

Longer is the more tempting mistake and the worse one. At five minutes a push reads as having had no effect, and the operator reaches for the rolling restart that polling exists to remove. Shorter buys nothing measurable: a push is a human act at human cadence, and a one-second interval has every instance in the fleet query five tables every second, forever, against wiring that changes perhaps weekly. The default of 30s sits where readiness probes do, so "within half a minute of the push" needs no new unit of trust.

There is deliberately no minimum. A very short interval is a cost you can read about here rather than a refusal you cannot override.

What a tick costs, and what it cannot miss

A tick is one GetWiring — the same single, consistent snapshot of the five tables the boot takes — followed by a comparison of a content digest against the digest this instance was wired from. The read is full and the comparison is cheap; nothing is reconstructed to find out whether it needed to be.

A cheaper probe was considered and rejected, because every one available can be wrong in the direction that matters, and a change an instance does not see is an instance that is silently stale while reporting itself healthy:

• A newest-timestamp probe would trust the clock of whichever host ran the push. A push from a host whose clock lags writes rows older than the ones it replaced, and the probe reports "unchanged".
• A row-count probe misses every change that keeps the count — a re-pointed statement, a narrowed declared key set, a renamed connection.
• Four per-section reads can straddle a concurrent push and compose a wiring set that never existed.

The digest ignores the created_at / updated_at stamps on purpose. A push rewrites every row, so an identical re-push — the same pipeline running twice — is not a change, and is not reported as one.

What a shutdown does with a tick in flight

SIGINT / SIGTERM cancels the reader at once, so a loop waiting for its next tick is gone before graceful shutdown even starts. A tick that is already inside a rebuild is different: a rebuild re-reads the seed file and opens every declared CSV, and none of that is interruptible. A rebuild that has not begun declines to start; one that has is waited for, for five seconds, and then abandoned:

wiring poll: a wiring refresh is still in flight; waiting up to 5s for it before
this process exits
wiring poll: the refresh in flight did not finish within 5s, so this process stops
without waiting for it; a wiring version is installed whole or not at all, so it
installed nothing

Five seconds against the ten of graceful shutdown keeps the worst case of the two together inside the 30-second termination grace an orchestrator gives by default — which is the point: before it was bounded, a rebuild on a stalled mount could hold the process open for minutes after the HTTP server had finished draining, and say nothing. Abandoning is safe: a version is installed whole or not at all, so the abandoned rebuild installed nothing, and the next process to start re-reads the wiring from scratch. A shutdown that made no such wait is silent.

Under serve, the facade is wired with everything the other surfaces expect: the admin gate, delegation and impersonation mutators, the append-only audit trail, the rules engine over a storage-backed rule source, and the object providers the wiring declares. A rule saved through the admin UI takes effect on the next decision with no separate rule store.

Full flags: serve.

Related

• Global options — --seed / --store.
• Refreshing wiring on a live fleet — the same machinery from the operator's side: what a push does to a fleet that is already running, how a stale instance surfaces, and what the swap costs.
• mcp — the read-only stdio surface, for MCP clients rather than HTTP.
• Command-Line Reference — the generated flag table.

mcp

Audience: integrators wiring Aperture into an MCP client (an AI assistant or agent runtime).

aperture mcp [options]

mcp serves Aperture's read-only decision surface over stdio — the transport an MCP client uses when it spawns Aperture as a subprocess. It exposes the decision API (check / enumerate / explain, single and bulk), a read-only what-if simulator, and model inspection as MCP tools. No tool mutates. The command wires the facade with storage for inspection and what-if reads, but deliberately not the gate, delegation, or impersonation mutators — the surface can never write.

Because it speaks the MCP protocol over stdio, you normally don't run mcp interactively; an MCP client launches it. A minimal client configuration points at the binary and the model to serve:

{
  "mcpServers": {
    "aperture": {
      "command": "bin/aperture",
      "args": ["mcp", "--store", "./aperture.db"]
    }
  }
}

On start it prints one line to stderr (stdout is reserved for the protocol):

aperture mcp: serving read-only MCP surface over stdio

What the flags control

• --seed / --store — the model the surface reads, exactly as elsewhere (see Global options). With neither, it serves the embedded example model over an in-memory store.

There are no other flags: the surface is read-only by construction, so it needs no acting principal, account, or auth adapter.

Full flags: mcp.

Related

• Global options — --seed / --store.
• serve — the read/write HTTP + Twirp surface.
• Decisions — the same check/enumerate/explain questions from a shell.
• Command-Line Reference — the generated flag table.

Library overview

Aperture is library-first: the public Go packages at the module root are the product, and every other surface — the CLI, the RPC/HTTP API, the MCP server, and the admin UI — is a thin translator over them. This part of the book is the reference for embedding Aperture directly in a Go host program.

If you have not run the Library quickstart yet, start there: it wires a store, an engine, and the facade end to end and asks one Check. This section then documents the full decision API those pieces expose.

Two layers, one decision

A host program drives Aperture through two collaborating packages:

The engine answers the pure question; the facade is where the surface-facing policy lives (how an operational error becomes a rendered deny, when a decision is audited, how a what-if overlay is layered). A host that wants the raw PDP can call the engine; a host that is building its own surface should call the facade, so it inherits the same fail-closed contract every built-in surface has.

import (
	"github.com/frankbardon/aperture/engine"
	"github.com/frankbardon/aperture/service"
	"github.com/frankbardon/aperture/storage/memory"
)

store := memory.New()
_ = store.Setup(ctx)

eng := engine.New(store)     // the PDP
svc := service.New(eng)      // the facade every surface calls

engine.New(store, opts...) and service.New(eng, opts...) both take functional options; see Constructing the engine and The service facade for the options each exposes.

The decision API

Both layers expose the same three operations, in single and bulk-batched forms, with an impersonation-aware variant of each on the engine:

The pages that follow cover each cluster:

• Decision API — the single Check / Enumerate / Explain operations: real signatures, input and result shapes, and when to reach for each.
• Batch operations — CheckBatch / EnumerateBatch / ExplainBatch and the generic BatchResult[T] type that keeps one bad query from failing a whole batch.
• Impersonation — CheckAs / EnumerateAs / ExplainAs and the ImpersonationContext decorator that steers which subject set a decision resolves over.
• The service facade — how surfaces call the facade, its fail-closed rendering, and the read-only Simulate / SimulateExplain what-if path with a worked example.

Errors are always coded

Every failure Aperture returns across a package boundary is an APERTURE_* coded error, never a bare string. Recover the code with errors.CodeOf rather than matching on the message:

import aerr "github.com/frankbardon/aperture/errors"

if err != nil {
	switch aerr.CodeOf(err) {
	case aerr.APERTURE_INVALID_INPUT:
		// the query was malformed — a caller bug
	case aerr.APERTURE_NOT_FOUND:
		// an unknown principal, permission, or entity
	default:
		// an operational failure (storage, an unresolvable strategy, ...)
	}
}

The engine and the facade differ in how they treat these errors — the engine returns them, while the facade folds operational failures into a fail-closed deny. The distinction is spelled out per operation on the pages below and in The service facade. The full catalog lives in the Error Codes reference.

The vocabulary these operations are built from — principal, action, object, pattern, specificity, grant, account — is defined in the Concepts primer and expanded in the Concepts section of this book.

Decision API

The engine package is Aperture's Policy Decision Point. It exposes three single operations — Check, Enumerate, and Explain — on *engine.Engine. This page gives their real signatures, input and result shapes, and the rule for choosing between them. Their bulk and impersonation-aware forms live in Batch operations and Impersonation.

All three are methods on an engine you construct once and reuse. The engine is stateless beyond its storage handle and safe for concurrent use to whatever degree the underlying Storage is.

Constructing the engine

func New(store model.Storage, opts ...Option) *Engine

With no options the engine uses the literal identity-pattern coverer — a grant's object pattern is matched directly against the requested object. The options extend that behaviour:

Two further seams return a shallow copy of the engine rather than mutating it, for the read-only what-if paths: (*Engine).WithStore(store) re-points the copy at a different (e.g. overlay) store, and (*Engine).WithRuleEvaluator(re) redirects rule-backed scope strategies at a different rule evaluator. Both leave the original engine untouched, so a live engine and a transient what-if engine never interfere. The facade's Simulate path is built on exactly these.

Check

func (e *Engine) Check(ctx context.Context, req Request) (Decision, error)

Check resolves a single authorization decision: may this principal take this action on this one object, in this account?

Request

Request is a value type; every field is mandatory.

type Request struct {
	Account   string // active account the decision is scoped to
	Principal string // id of the principal requesting access
	Action    string // the verb being attempted, e.g. "read"
	Object    string // canonical object-identity string
}

Principal is a principal id (the key storage and the subject set are keyed on), not the principal's identity string. Object is a canonical object-identity string such as account:acme/project:atlas/document:42. Grants stamped to any account other than Account are never consulted (the sole exception is a grant stamped to the account wildcard *, which spans all tenancies).

Decision

type Decision struct {
	Allow            bool                  // the verdict: true permits, false denies
	Reason           string                // human-readable explanation naming the deciding grant(s)
	DecidingGrantIDs []string              // ids of the grant(s) that produced the verdict, sorted; empty on a default-deny
	Impersonation    *ImpersonationContext // non-nil only under an active impersonation session (see Impersonation)
}

Reason names the deciding grant(s), their specificity, and how many grants were considered. DecidingGrantIDs is sorted for determinism and is empty on a default-deny. Impersonation is nil on the ordinary path.

Error contract

Check never returns an allow-on-error. Any operational failure — a malformed request, an unknown principal, a storage fault — is returned as an APERTURE_* coded error and the caller treats it as a non-decision. A well-formed request that simply matches no grant is a clean default-deny (Allow: false, no error). Default-deny is the floor: with no candidate grant the answer is DENY.

dec, err := eng.Check(ctx, engine.Request{
	Account:   "acme",
	Principal: "alice",
	Action:    "read",
	Object:    "account:acme/project:atlas/document:42",
})
if err != nil {
	// operational failure — not a decision
	return err
}
fmt.Println(dec.Allow, dec.Reason)

Building your own surface? Prefer the facade's Service.Check, which folds operational errors into a fail-closed deny so a decision point can never fail open. The raw engine.Check here returns those errors for the facade to render.

Enumerate

func (e *Engine) Enumerate(ctx context.Context, req EnumerateRequest) ([]string, error)

Enumerate is the inverse of Check: it returns the object ids under a pattern that the principal may take the action on, in the active account. Every id it returns is one Check would allow — a denied object is never returned — so the two operations agree by construction.

EnumerateRequest

type EnumerateRequest struct {
	Account    string          // active account the enumeration is scoped to
	Principal  string          // id of the principal whose access is enumerated
	Action     string          // the verb being enumerated, e.g. "read"
	Pattern    string          // identity pattern bounding the search
	Fields     map[string]any  // optional object-metadata predicates; nil/empty filters nothing
	References []ReferenceEdge // optional reference edges; nil/empty restricts nothing
	Limit      int             // caps the number of returned ids; <= 0 means the configured bound
}

Pattern both bounds the candidate set and is intersected with each grant's own scope — for example account:acme/** (everything in the account) or account:acme/document:* (every document at the account root). Limit caps the result; a non-positive Limit (or one above the bound) is clamped to the bound the engine was configured with, so an enumeration can never materialise an unbounded set. That bound is engine.WithEnumerateLimit's value, or engine.DefaultEnumerateLimit (1000) on an engine built without it. Object order is deterministic (sorted by canonical id).

ids, err := eng.Enumerate(ctx, engine.EnumerateRequest{
	Account:   "acme",
	Principal: "alice",
	Action:    "read",
	Pattern:   "account:acme/project:atlas/**",
	Limit:     100,
})

An operational failure — a storage fault, an unresolvable scope strategy, or an unconfigured object lister an implicit/exclusive grant needs — is returned as a coded error, never a silent partial set.

A result on the bound is a warning

A truncated result and a complete one are the same []string. When an enumeration comes back holding exactly its effective bound, the engine therefore says so through WithLogger (slog.Default() when none is wired):

WARN engine: enumeration returned exactly its bound; the result may be truncated
  bound=100 configured_bound=1000 requested_limit=100
  account=acme action=read pattern=account:acme/project:atlas/**

bound is the cap this enumeration actually ran under — your own Limit when that was the smaller of the two — and configured_bound is the engine's ceiling. A result below the bound logs nothing.

The wording is deliberate: this is a hint, not an assertion. A complete set that happens to be exactly that size is indistinguishable from a truncated one here, so the line never claims anything was dropped. Enumerate's return shape is unchanged — there is no truncation flag, and a caller still cannot tell the two apart. The intended response is an operator's, not a caller's: raise the bound (or the request Limit) and ask again.

It is raised at the engine only. One bound governs the engine clamp, the scope member gather (scope.Deps.MaxMembers) and the provider list alike, so a starve further down surfaces here as a result sitting on the bound.

Filtering by object metadata

Fields is an optional set of object-metadata predicates. An allowed candidate is returned only when its metadata satisfies all of them; a nil or empty map (the default) filters nothing and never touches a metadata source, so an unfiltered enumeration costs exactly what it always did.

ids, err := eng.Enumerate(ctx, engine.EnumerateRequest{
	Account:   "acme",
	Principal: "alice",
	Action:    "read",
	Pattern:   "account:acme/**",
	Fields:    map[string]any{"tier": "premium", "brands": "brand:Y"},
	Limit:     10,
})

The meaning is provider.Filter's Fields contract verbatim, evaluated by the same provider.MatchFields a provider's own Query calls — so an enumeration filtered here and one filtered inside a provider select the same objects. AND across keys; a collection field matches by membership; an absent field never matches, not even a nil want; and comparison is typed (int64(5) matches a float64(5) want, "5" does not match 5).

Two orderings are load-bearing:

1. Deny first. The predicate runs on candidates that already survived deny-overrides and specificity, so it can only subtract from the allowed set. A denied object is never returned, whatever the predicate says.
2. Filter before Limit. The candidate set is predicated before it is truncated, so asking for the first 10 objects tagged brand:Y searches every candidate rather than tagging the first 10 candidates and returning the few that stuck.

Metadata is read through engine.WithMetadata(fetcher), whose seam (MetadataFetcher) has the signature of *provider.Registry.Fetch — the same registry that backs the scope lister and the rule evaluator, so a candidate is served from the per-type cache — warmed by the enumeration itself when the provider promises its listed bags are its fetched bags (FetchCompleteLister), and by the candidate's own Fetch otherwise:

eng := engine.New(store,
	engine.WithScopeResolution(nil, engine.ScopeDeps{Lister: reg, Rules: rulesEngine}),
	engine.WithMetadata(reg))

Failure is deliberately asymmetric — an enumeration returning fewer objects reads as "no access", one returning more is an authorization bug:

• no metadata source wired, or no provider for the candidate's object-type → APERTURE_PROVIDER_UNREGISTERED, never a silently empty result. The predicate runs per candidate, so this only surfaces once the enumeration has at least one allowed candidate; an empty allowed set returns empty regardless of wiring.
• the object has no metadata row (APERTURE_NOT_FOUND from Fetch) → every field is absent, absent never matches, so the object is excluded.
• any other provider failure → returned verbatim.

EnumerateBatch and EnumerateAs carry Fields through the same path.

Restricting through a declared reference

References restricts the enumeration to the identities a holder object's declared reference field contains — "the brands in dataset X". Nil or empty (the default) restricts nothing.

ids, err := eng.Enumerate(ctx, engine.EnumerateRequest{
	Account:   "acme",
	Principal: "alice",
	Action:    "read",
	Pattern:   "account:acme/brand:*",
	References: []engine.ReferenceEdge{{
		HolderID: "account:acme/dataset:x", // HolderType is optional
		Field:    "current_brands",         // must be a DECLARED reference
	}},
})

It is a dereference, not a filter, and the distinction is the whole reason it exists. Fields answers "which datasets contain brand Y?" because the dataset holds current_brands. A brand holds no field naming its datasets — references are declared on the holding side only — so no predicate on brand can express "which brands belong to dataset X?" at all.

Composition mirrors the filter's: several edges AND, an edge composes with Fields, both apply before Limit, and the restriction can only subtract from the allowed set. Exactly one hop is taken — the identities an edge yields are never themselves dereferenced. The whole restriction is resolved once per enumeration, before candidates are gathered, against the same grants and subject set the candidates are decided with; that is what makes EnumerateAs check the holder with the impersonated authority.

The failure modes are asymmetric, and the asymmetry is the security model:

Wire the source alongside the metadata source; it is the same registry:

eng := engine.New(store,
	engine.WithScopeResolution(nil, engine.ScopeDeps{Lister: reg, Rules: rulesEngine}),
	engine.WithMetadata(reg),
	engine.WithReferences(reg),
	engine.WithLogger(logger))

A rules-engine dereference is deliberately not supported: Check owes a p99 under a millisecond, and following a reference inside rule evaluation is a join on the decision hot path with a recursive cache-miss path behind it. Enumeration computes the restriction once, off that path.

EnumerateBatch and EnumerateAs carry References through the same path.

Search

Search resolves a name to an id. It is the operation to reach for when a question arrives in a person's own words and every step after it needs ids.

matches, err := eng.Search(ctx, engine.SearchRequest{
	Account:   "acme",
	Principal: "alice",
	Action:    "read",
	Pattern:   "account:acme/brand:*",
	Query:     "nike",
	Limit:     5,
})
// matches[0].Object   "account:acme/brand:42"
// matches[0].Score    0.875
// matches[0].Field    "label"
// matches[0].Value    "Nike, Inc."
// matches[0].Metadata map[string]any{"label": "Nike, Inc.", "sector": "Footwear"}

It is a ranking over Enumerate, not a second answer

Search does not re-derive who may see what. It walks the same candidate gather, the same deny-overrides decision, the same reference restriction and the same Fields predicate Enumerate walks, and only scores what survived. Decide, then match — so a score can only ever subtract, and the result is always a subset of what Enumerate would return for the same subject, action and pattern.

That ordering is the feature. Composing the pieces yourself — enumerate a type, fetch each id's metadata, match in your own process — puts the unscoped set across the boundary first and narrows it second, so any bug in your filter turns your surface into an oracle for every object in the system.

Search selects; it never authorizes. A score is a ranking hint for whoever is choosing between candidates. Nothing in Aperture reads one, and a caller that acts on a selected id still Checks it.

What matches

Matching is case- and punctuation-insensitive ("Nike, Inc." matches "nike inc") and tolerates a typo or a transposition on tokens long enough for one to be unambiguous. Only string material is matched — a string field and the string elements of a list field — because filtering by a number, bool or date is what Fields is for.

Aperture has no notion of a "label": a label is an ordinary metadata field whose name your host chose. Every field holding text is searched unless MatchFields names some, and each match reports the Field and Value that produced it, so a hit on an alias is distinguishable from a hit on a display name.

Options

Limit caps the ranking; the bound caps the scan

These are two different numbers. The scan runs under the engine's configured enumeration bound (WithEnumerateLimit), over the same candidate set Enumerate covers. Limit then takes the top of the finished ranking.

Bounding the scan by Limit would return the first N objects that matched at all rather than the N best — an arbitrary prefix with a score column, not a ranking.

A scan that comes back holding exactly its bound is warned about through WithLogger. That hint matters more here than for Enumerate: a truncated enumeration returns a visibly short list, while a truncated search returns a full, confidently ranked shortlist whose best entry may simply be the best among the candidates that fit. As with Enumerate's warning it cannot be an assertion — a complete set of exactly that size is indistinguishable.

Requirements and failure modes

Search requires an object-metadata source (WithMetadata), unlike the Fields predicate, which is only consulted when a request carries one. Without it the answer is APERTURE_PROVIDER_UNREGISTERED rather than an empty result, because an empty result reads as "you may see nothing" and would hide the misconfiguration behind a plausible answer.

A principal who is not a member of the account gets an empty result and no error; so does an invisible reference holder. A candidate with no metadata row is skipped — there is nothing there to name.

SearchAs is the impersonation-aware sibling, and SearchBatch resolves many names in one call.

Explain

func (e *Engine) Explain(ctx context.Context, req Request) (Trace, error)

Explain resolves the request exactly as Check does but records the full derivation instead of only the verdict. Use it as a diagnostic — the "why" behind a verdict — not as an enforcement gate. It takes the same Request as Check.

Trace

Trace is a stable public contract: the RPC surface, the MCP inspect tool, and the what-if simulator all serialize it, so its fields are part of the API.

type Trace struct {
	Request        Request               // the question that was asked
	Subjects       []model.Subject       // the principal's expanded subject set (itself, roles, groups)
	Considered     []GrantEvaluation     // every grant loaded, each tagged with how it fared
	MaxSpecificity int                   // top specificity among covering candidates; 0 when nothing covered
	Notes          []EvaluationNote      // diagnostics rule evaluation recorded; empty when no rule ran
	Attributes     TraceAttributes       // the `principal` and `account` bags the rules read; zero when no rule ran
	Now            time.Time             // the reference instant rule evaluation resolved against; zero when no rule ran
	Decision       Decision              // the final verdict — identical to what Check returns
	Impersonation  *ImpersonationContext // non-nil only under an active impersonation session
}

Each entry in Considered is a GrantEvaluation recording one grant's contribution — its subject, permission, effect, object pattern, whether its action matched, whether it covered the object and at what specificity, which scope strategy it used, whether it was a deciding grant, and a short human-readable Outcome. A grant that failed the action match is still listed (with ActionMatched: false) so the trace shows what was ruled out.

Evaluation notes

Notes is where a rule-backed scope explains itself. A rule can decide false for a reason the verdict never shows — the metadata field it reads is the wrong shape (a string where an array was meant), or it matched only because the field is absent. Both are deny-safe by policy: a collection operator over a non-collection evaluates to false rather than raising APERTURE_RULE_EVAL, so one mistyped field cannot break every decision that touches it. See Rules.

type EvaluationNote struct {
	GrantID  string // the grant whose scope resolution recorded it
	Rule     string // the rule reference that was evaluated
	Kind     string // "shape_mismatch" | "absent_field" | "date_invalid" |
	                //   "date_bounds_inverted" | "dangling_reference" | "attributes_floor_only"
	Op       string // the comparison operator ("hasAll", …)
	Path     string // the dotted variable path ("object.tags")
	Expected string // the shape the operator requires ("collection")
	Actual   string // the shape found ("string")
	Message  string // "object.tags: expected collection, got string"
}

Six kinds are recorded today: shape_mismatch, absent_field, date_invalid, date_bounds_inverted, dangling_reference (an enumeration skipped a declared reference whose target no longer exists), and attributes_floor_only (a rule read a host-defined field off principal or account while that root carried nothing but the engine's floor, so every such comparison was false).

Three rules govern them:

1. Diagnostic only — a note never influences a verdict.
2. Explain only — Check and Enumerate install no collector, so they record nothing, allocate nothing, and behave exactly as before.
3. Shape and path only — never a metadata value, never anything that could cross an account boundary, the same discipline error messages follow.

The attribute bags

Attributes carries the principal and account roots this decision's rules were evaluated against — the host's bag with the engine's floor stamped over it, exactly as a rule read it:

type TraceAttributes struct {
	Principal map[string]any `json:"principal,omitempty"`
	Account   map[string]any `json:"account,omitempty"`
}

Both are nil on a decision that evaluated no rule, and Account is also nil for a decision made at the account wildcard "*" — that is not an account, so no bag is resolved for it and none is invented here.

This field deliberately discloses VALUES, and it is the one place a Trace does. It is not an oversight to fix, and it does not contradict rule 3 above: a note is produced by a comparison against an object's metadata, on whatever objects a wide decision happened to sweep, while these two bags are the subjects of the very question being asked — the principal in Request.Principal and the account in Request.Account. A trace that discloses them tells the asker about their own decision and nothing else.

The disclosure is also the point: "why was this denied?" is unanswerable from a grant list when the deciding comparison was principal.tier == "gold" and the operator cannot see that the tier is "silver", or absent entirely. So do not redact these into a note, and do not widen them past those two subjects. The wider-audience rule what-if preview takes the opposite side on purpose and supplies no principal or account input at all, so a rule author's editor cannot become a directory read oracle.

Trace implements String(), which renders an operator-readable, deterministic report:

tr, err := eng.Explain(ctx, engine.Request{
	Account:   "acme",
	Principal: "alice",
	Action:    "read",
	Object:    "account:acme/project:atlas/document:42",
})
if err != nil {
	return err
}
fmt.Print(tr.String())

tr.Decision is byte-for-byte the decision Check returns for the same request, so a surface can render a verdict and its explanation from a single Explain call. The rendered report prints each non-empty attribute root as one key-sorted line before the grants — they are the input the grants' rules were judged against — and stays byte-identical for the same decision.

When to use each

Check is the allocation-conscious hot path; reach for it in enforcement. Enumerate is the most cache-sensitive op and is deliberately bounded — use it to answer "what can they see", not as a substitute for repeated Checks on a known object. Search is Enumerate plus a ranking, so it costs at least as much — reach for it when the input is a name and for nothing else; when you already hold the ids, Check or Enumerate is the cheaper question. Explain does the same work as Check plus recording the derivation, so use it when a human (or a machine) needs to understand the verdict, not on every hot-path call.

Related

• Batch operations — resolve many of these in one call.
• Impersonation — the *As variants that resolve over an elevated subject set.
• The service facade — the fail-closed wrapper surfaces call.
• Concepts primer — deny-overrides, specificity, and the subject set these operations resolve over.

Batch operations

Each of the three single decision operations has a bulk form that resolves many requests in one call: CheckBatch, EnumerateBatch, and ExplainBatch. They exist so a surface — the RPC bulk RPCs, the MCP tools, the what-if simulator — can answer a list of questions in one round trip while keeping each answer isolated: one bad query never fails the whole batch.

The batch forms live on both layers with the same shape. This page shows the engine methods; the facade exposes the same three over its surface-neutral Query / EnumerateQuery types.

BatchResult[T]

Every batch op returns a slice of BatchResult[T], aligned by index with the input: result[i] is the outcome of reqs[i].

type BatchResult[T any] struct {
	Result T     // the item's answer when Err is nil; the zero value otherwise
	Err    error // the item's coded error when it failed, or nil on success
}

Exactly one of the two fields is meaningful per item. When Err is non-nil the Result is the zero value and the caller reads Err; otherwise Result holds the answer. The generic parameter is the per-op result type: Decision for CheckBatch, []string for EnumerateBatch, and Trace for ExplainBatch.

Iterate a batch by checking each item's Err before reading its Result:

for i, item := range results {
	if item.Err != nil {
		log.Printf("query %d failed: %v", i, item.Err)
		continue
	}
	use(item.Result)
}

CheckBatch

func (e *Engine) CheckBatch(ctx context.Context, reqs []Request) []BatchResult[Decision]

Resolves many Check requests, returning []BatchResult[Decision] aligned with reqs. A request that errors yields an item with Err set and a zero Decision; its siblings are unaffected. A nil reqs yields a nil result.

results := eng.CheckBatch(ctx, []engine.Request{
	{Account: "acme", Principal: "alice", Action: "read", Object: "account:acme/project:atlas/document:42"},
	{Account: "acme", Principal: "alice", Action: "write", Object: "account:acme/project:atlas/document:42"},
})
for i, item := range results {
	if item.Err != nil {
		continue // a malformed request — item.Result is the zero Decision
	}
	fmt.Printf("query %d: allow=%v\n", i, item.Result.Allow)
}

EnumerateBatch

func (e *Engine) EnumerateBatch(ctx context.Context, reqs []EnumerateRequest) []BatchResult[[]string]

Resolves many Enumerate requests, aligned with reqs — result[i] is the id list for reqs[i]. A request that errors yields an item with Err set and a nil list; the rest are unaffected.

results := eng.EnumerateBatch(ctx, []engine.EnumerateRequest{
	{Account: "acme", Principal: "alice", Action: "read", Pattern: "account:acme/project:atlas/**"},
	{Account: "acme", Principal: "alice", Action: "read", Pattern: "account:acme/project:nimbus/**"},
})

ExplainBatch

func (e *Engine) ExplainBatch(ctx context.Context, reqs []Request) []BatchResult[Trace]

Resolves many Explain requests, aligned with reqs. A request that errors yields an item with Err set and a zero Trace; the rest are unaffected.

Facade batch forms

The service facade exposes the same three over its surface-neutral query types, so a surface never touches the engine's Request type:

func (s *Service) CheckBatch(ctx context.Context, qs []Query) []engine.BatchResult[Result]
func (s *Service) EnumerateBatch(ctx context.Context, qs []EnumerateQuery) []engine.BatchResult[[]string]
func (s *Service) ExplainBatch(ctx context.Context, qs []Query) []engine.BatchResult[engine.Trace]

Note where the fail-closed contract lands. Service.CheckBatch renders each item exactly as Service.Check: an operational failure folds into a deny Result (with Err nil), while an input-validation failure sets the item's Err. So a CheckBatch item's Err is only ever a caller-bug error, never a storage fault — the storage fault already became a fail-closed deny. EnumerateBatch and ExplainBatch carry engine errors verbatim in each item's Err. See The service facade for the full rendering rules.

Like the engine forms, every facade batch method returns nil for a nil input slice.

Related

• Decision API — the single operations these batch.
• The service facade — the fail-closed rendering the facade batch forms inherit.

Impersonation

The engine exposes an impersonation-aware sibling of each decision operation: CheckAs, EnumerateAs, and ExplainAs. They resolve a decision over an effective subject set — the target's authority, borrowed by an operator — while recording the real operator for audit. They never mutate stored grants; an ImpersonationContext only steers which subject set the engine resolves over.

ImpersonationContext

The decorator that carries a session into the engine:

type ImpersonationContext struct {
	RealActor        string    // the operator's principal id (the audit identity)
	EffectiveSubject string    // the target's principal id (whose authority is used)
	Mode             Mode      // augment or become (or none, which is inert)
	ExpiresAt        time.Time // the session's hard expiry instant
}

• RealActor is the operator — the principal that truly issued the request and under whose identity audit attributes the action.
• EffectiveSubject is the target — the principal whose authority the decision borrows.
• Mode selects augment vs become (below).
• ExpiresAt is a hard time-box the engine enforces with its injected clock. A presented-but-expired context fails closed to no elevation (the operator's own authority), never to the target's.

Mode

const (
	ModeNone    Mode = ""        // no impersonation — the inert zero value
	ModeAugment Mode = "augment" // ADD the target's permissions to the operator's own
	ModeBecome  Mode = "become"  // FULLY assume the target's identity for the decision
)

• ModeAugment resolves over the union of the operator's and the target's subject sets, but the operator keeps acting under its own identity. Use it to "see what they can see" while retaining your own authority.
• ModeBecome resolves over the target's subject set alone, as if the target had asked — the operator's own grants do not apply. Become is the strictly stronger mode and is gated by a stronger right (see the impersonation package). The audit trail still records the real operator.
• ModeNone is the inert default: a zero ImpersonationContext confers no elevation, and the *As operation delegates straight to its plain sibling.

Mode.Valid() reports whether a mode is recognised (none counts as valid).

The operations

func (e *Engine) CheckAs(ctx context.Context, req Request, ic ImpersonationContext) (Decision, error)
func (e *Engine) EnumerateAs(ctx context.Context, req EnumerateRequest, ic ImpersonationContext) ([]string, error)
func (e *Engine) ExplainAs(ctx context.Context, req Request, ic ImpersonationContext) (Trace, error)

Each takes the same request its plain sibling takes, plus the ImpersonationContext. Behaviour is identical to the plain operation except for the subject set the decision resolves over.

Rules for an active session

An ImpersonationContext is active when its mode is augment or become and its ExpiresAt is still in the future (per the engine's clock). For an active session:

• The request's principal must be the operator: req.Principal == ic.RealActor. A mismatch is a caller bug and surfaces as APERTURE_INVALID_INPUT, not a deny.
• Augment resolves over operator ∪ target subjects; become resolves over the target alone.
• A rule-backed scope strategy is told about the effective subject: under become the rule's principal.id is the target's id and the target's kind picks the attribute slot principal.* is read from; under augment both are the operator's, because the operator keeps acting under its own identity. The rule and the grant set therefore always describe the same principal — see Under become, principal.* is the target.
• The operator and the target must both be members of the active account, else the decision is a fail-closed deny — cross-account impersonation is refused. (CheckAs/ExplainAs return a deny with no deciding grant; EnumerateAs returns the empty set.)
• The returned Decision / Trace carries ic on its Impersonation field for audit. In a Trace, Subjects is the effective subject set while Request.Principal remains the real operator — so a trace shows both who asked and whose authority answered.

Under become, principal.* is the target

The subject set and the rule must describe the same principal. A decision whose grants are the target's and whose rule is about the operator answers a question nobody asked, and nothing in a trace reveals it.

principal.id therefore changes meaning under become: a rule comparing principal.id == object.owner asks whether the target owns the object, which is what "as if the target had asked" means. The target's kind also picks the attribute slot, so principal.tier is read from the target's directory.

Audit is unaffected in both modes. Request.Principal is still the operator — it is what the deny reason names and what a Trace records — and Decision.Impersonation / Trace.Impersonation still carry the real actor. The rule sees whose authority answered; the audit trail sees who acted.

The change is free: the target's kind arrives with the subject-set expansion a become decision already performs, so it buys no extra storage read.

Inert sessions fail closed

When ic is inert — mode none, or an expired session — the *As operation delegates straight to its plain sibling. An expired become session therefore resolves as the operator's own authority with no elevation, never as the target's. Elevation never outlives its time-box.

ic := engine.ImpersonationContext{
	RealActor:        "alice",  // the operator issuing the request
	EffectiveSubject: "bob",    // the target whose access is borrowed
	Mode:             engine.ModeBecome,
	ExpiresAt:        time.Now().Add(15 * time.Minute),
}

dec, err := eng.CheckAs(ctx, engine.Request{
	Account:   "acme",
	Principal: "alice", // MUST equal ic.RealActor
	Action:    "read",
	Object:    "account:acme/project:atlas/document:42",
}, ic)
if err != nil {
	return err
}
// dec resolves over bob's authority; dec.Impersonation records alice as the real actor.
fmt.Println(dec.Allow, dec.Impersonation.RealActor)

Carrying impersonation on the context

The engine also exposes context helpers so a middleware layer — most importantly the audit layer — can read the real actor and effective subject of any decision made while a session is set:

func WithImpersonation(ctx context.Context, ic ImpersonationContext) context.Context
func ImpersonationFromContext(ctx context.Context) (ImpersonationContext, bool)

The *As entry points set this on the context they evaluate under; a surface may also set it before calling so audit middleware wrapping the engine sees it.

Related

• Decision API — the plain operations these mirror.
• The service facade — surfaces reach impersonation through the facade's impersonation service (wired with WithImpersonation).
• The impersonation package — session issuance and the rights that gate augment vs become.

The service facade

The service package is the thin decision facade every surface calls instead of touching the engine directly — the CLI check command, the HTTP /check endpoint, the Twirp service, and the MCP read subset. It exists so those surfaces share one code path with one fail-closed policy: the rule for turning an engine error into a rendered decision lives here, not duplicated per surface.

If you are embedding Aperture to build your own surface, call the facade rather than the raw engine — you inherit its fail-closed contract, decision auditing, and the what-if Simulate path for free.

Constructing the facade

func New(eng *engine.Engine, opts ...Option) *Service

With no options a Service is read-only: it carries the decision API (Check / Enumerate / Explain and their batch forms) always, and returns APERTURE_UNIMPLEMENTED from any mutation. Options wire the additional dependencies:

The serve command builds the fully-wired facade so HTTP, Twirp, and the CLI all drive one mutation path. A decision-only surface can stay minimal with service.New(eng).

Surface-neutral query types

The facade takes Query / EnumerateQuery — surface-neutral mirrors of the engine's request types — so the CLI and HTTP layers marshal to and from these and the engine's Request stays an engine-internal concern.

type Query struct {
	Account   string
	Principal string
	Action    string
	Object    string
}

type Result struct {
	Allow            bool     // the verdict
	Reason           string   // names the deciding grants, or the fail-closed cause
	DecidingGrantIDs []string // empty on a default-deny or a fail-closed deny
}

type EnumerateQuery struct {
	Account    string
	Principal  string
	Action     string
	Pattern    string
	Fields     map[string]any // optional object-metadata predicates; nil filters nothing
	References []ReferenceEdge // optional reference edges; nil restricts nothing
	Limit      int
}

type ReferenceEdge struct {
	HolderType string // optional; empty means HolderID's terminal segment type
	HolderID   string // "account:acme/dataset:7"
	Field      string // a DECLARED reference field on the holder
}

EnumerateQuery.Fields — the object-metadata filter

Fields narrows an enumeration by object metadata: an object the principal is allowed to act on is returned only when its metadata satisfies every predicate. Nil or empty — the default — filters nothing and does not consult a metadata source at all, so existing callers are unaffected.

The facade passes the map to the engine unchanged. It parses nothing, coerces nothing, and normalises nothing, and it never rewrites the caller's map. That is deliberate: the predicate's meaning is provider.Filter's Fields contract, evaluated in exactly one place (provider.MatchFields). A surface that re-interpreted a value on the way in — parsing "5" into a number, say — would make an enumeration select objects a Check then denies.

ids, err := svc.Enumerate(ctx, service.EnumerateQuery{
	Account:   "acme",
	Principal: "alice",
	Action:    "read",
	Pattern:   "account:acme/**",
	Fields:    map[string]any{"tier": "premium", "brands": "brand:Y"},
	Limit:     10,
})

The semantics a caller must know:

• AND across keys. Every predicate must hold.
• Collections match by membership. A list-valued metadata field matches when it contains the wanted value; a list-valued want is a container compared by equality.
• An absent field never matches — not even against a nil want.
• Comparison is typed. int(5) and float64(5) are one value; "5" is not 5.
• The filter runs before Limit. Candidates are decided, then filtered, then truncated — so "the first 10 objects tagged brand:Y" searches every candidate. Truncating first would return a silently wrong answer.
• The filter only subtracts. It applies to candidates that already survived deny-overrides, so no predicate can surface an object Check would deny.

Failure is asymmetric on purpose, because a short answer reads as "no access":

Wire the source alongside the scope lister — it is the same registry:

eng := engine.New(store,
	engine.WithScopeResolution(nil, engine.ScopeDeps{Lister: reg, Rules: rulesEngine}),
	engine.WithMetadata(reg))

Two notes for anyone refactoring this field:

• Over Twirp, Fields rides as map<string, google.protobuf.Value>, which carries every number as a double. An integer beyond 2^53 loses precision in transit and must be sent (and stored) as a string; a non-finite number (NaN, ±Inf) is rejected as APERTURE_INVALID_INPUT. See the RPC reference.
• Fields carries json and jsonschema struct tags — the only tagged field on any service type. The MCP surface aliases this struct (mcp.EnumerateIn) and reflects its tool schema off it, so the omitempty is load-bearing: without it the reflected schema marks the predicate required and an agent cannot ask an unfiltered question at all.

EnumerateQuery.References — the reference edges

References restricts an enumeration to the identities a holder object's declared reference field contains — "the brands in dataset X". Nil or empty — the default — restricts nothing.

ids, err := svc.Enumerate(ctx, service.EnumerateQuery{
	Account:   "acme",
	Principal: "alice",
	Action:    "read",
	Pattern:   "account:acme/brand:*",
	References: []service.ReferenceEdge{{
		HolderID: "account:acme/dataset:x",
		Field:    "current_brands",
	}},
})

It is a dereference, not a predicate, which is why it is not spelled through Fields: a brand carries no field naming its datasets, so no predicate on brand can express the question. Fields answers the mirror image ("which datasets contain brand Y?") because that side holds the field. The declaration side is Declared references.

The facade carries the edges to the engine unchanged — it does not parse a holder identity, infer a holder type, or check that a field is declared. Every one of those is a decision with a disclosure consequence, and a surface that made it separately would be a second place for the answer to differ.

• HolderType is optional. Empty means "whatever HolderID's terminal segment type is"; when given it must agree with HolderID, and the engine — not this type — enforces that.
• Several edges AND, an edge composes with Fields, and both precede Limit.
• Exactly one hop. The identities an edge yields are never themselves dereferenced.
• The restriction is computed once per enumeration, against the same grants and subject set the candidates are decided with — so EnumerateAs checks the holder with the impersonated authority, not the operator's.

The failure modes are asymmetric on purpose, and the asymmetry is the security model:

Wire the source alongside the metadata source — it is the same registry again:

eng := engine.New(store,
	engine.WithScopeResolution(nil, engine.ScopeDeps{Lister: reg, Rules: rulesEngine}),
	engine.WithMetadata(reg),
	engine.WithReferences(reg),
	engine.WithLogger(logger)) // where a dangling reference is reported

References carries the same json / jsonschema tags Fields does, for the same MCP-reflection reason: omitempty on the slice keeps the edges optional, while HolderID and Field are required properties of an edge and HolderType is not.

SearchQuery — resolving a name to an id

SearchQuery is EnumerateQuery plus a name, and Search returns []SearchMatch:

matches, err := svc.Search(ctx, service.SearchQuery{
	Account: "acme", Principal: "alice", Action: "read",
	Pattern: "account:acme/brand:*",
	Query:   "nike",
	Limit:   5,
})

Each SearchMatch carries Object, Score, the Field and Value that produced the score, and the object's full Metadata inline — so labelling a result set costs no further call.

The facade passes every field to the engine unchanged. In particular no surface normalises the query text: case folding, punctuation stripping and tokenising happen in exactly one place, so a name typed at the CLI, sent over MCP, and passed in Go score identically.

Two properties are worth restating because they are what make the surface safe: candidates are decided before they are scored, so a result is always a subset of Enumerate's for the same subject; and a score ranks but never authorizes, so a caller acting on a selected id still Checks it. Search requires engine.WithMetadata — without it the answer is APERTURE_PROVIDER_UNREGISTERED, never an empty list. See the decision API.

ObjectMetadata and ObjectMetadataBatch

ObjectMetadata(objectID) returns one object's provider metadata; ObjectMetadataBatch(objectIDs) returns many, aligned by index as []engine.BatchResult[map[string]any], so a malformed or absent id carries its own error without failing its siblings. Both require WithProviders.

Neither authorizes or filters — they label ids a caller already holds. The path that produces ids a subject may see is Enumerate, or Search when the input is a name; and since Search already returns metadata inline, most callers never need the batch at all.

Fail-closed rendering

The facade's reason for existing is one shared policy for turning an engine outcome into a rendered decision:

This rule is applied per operation as follows.

Check (fail-closed)

func (s *Service) Check(ctx context.Context, q Query) (Result, error)

Check returns an error only for a genuine input-validation failure; every other engine failure folds into a fail-closed deny Result with a nil error. On a clean render the decision is audited (sampled, asynchronous, off the hot path).

res, err := svc.Check(ctx, service.Query{
	Account:   "acme",
	Principal: "alice",
	Action:    "read",
	Object:    "account:acme/project:atlas/document:42",
})
if err != nil {
	// only a malformed query reaches here (APERTURE_INVALID_INPUT / _IDENTITY_INVALID)
	return err
}
fmt.Println(res.Allow, res.Reason) // an operational failure is res.Allow == false, err == nil

Enumerate and Explain (verbatim errors)

func (s *Service) Enumerate(ctx context.Context, q EnumerateQuery) ([]string, error)
func (s *Service) Explain(ctx context.Context, q Query) (engine.Trace, error)

Enumerate and Explain return engine errors verbatim for the surface to map to a status. Enumerate cannot fail open by construction — every id it returns is one Check allows — so an operational failure is a returned error, not a silent partial set. Explain is a diagnostic, not an enforcement gate; its engine.Trace is the public contract surfaces serialize.

That trace carries Notes — six kinds today: shape_mismatch, absent_field, date_invalid, date_bounds_inverted, dangling_reference, and attributes_floor_only — and it carries Attributes, the principal and account bags the rules were evaluated against, values included. That is a deliberate disclosure and the one place a trace carries values: the two bags are the subjects of the very request being explained. Callers gate Explain accordingly.

Batch forms

CheckBatch, EnumerateBatch, and ExplainBatch return per-item engine.BatchResult[T] aligned with their queries. CheckBatch renders each item exactly as Check (operational error → deny Result; input-validation error → item Err); the other two carry engine errors verbatim per item. See Batch operations.

Simulate — what-if

The facade adds a read-only what-if surface: Simulate and SimulateExplain answer "what would the decision be if these hypothetical entities existed?" without ever persisting them. It is the seam the MCP Simulate tool and the what-if simulator UI drive.

func (s *Service) Simulate(ctx context.Context, ov Overlay, q Query) (Result, error)
func (s *Service) SimulateExplain(ctx context.Context, ov Overlay, q Query) (engine.Trace, error)

Both require the entity surface (WithStorage) so there is a base store to overlay. Simulate carries the same fail-closed contract as Check; SimulateExplain returns the trace verbatim like Explain. Nothing is written and nothing is audited — a simulation is not a real decision.

The overlay

Overlay is the set of hypothetical entities a run layers over the live model. Every field is additive and optional; an overlay entity with the same id as a stored one shadows it (so a what-if can model an edited grant or a re-roled principal), and ids absent from the overlay fall through to storage.

type Overlay struct {
	Principals  []model.Principal  // hypothetical or shadowing principals
	Groups      []model.Group      // hypothetical groups (union with stored memberships)
	Permissions []model.Permission // hypothetical or shadowing permissions
	Grants      []model.Grant      // the hypothetical grants — the common what-if input
	Memberships []model.Membership // hypothetical account memberships (consulted under enforcement)
	Rules       []model.Rule       // an unsaved rule being previewed (needs WithRuleSource)
}

The mechanism is structural, not conventional: Simulate builds a transient engine (e.WithStore(overlay) — same coverer, membership policy, and clock as the live engine, just a different read source) whose overlay store's writes are all inert. A simulation physically cannot persist through it.

Worked example: "what if I bestowed this grant?"

Suppose bob currently cannot read document:42, and you want to preview the effect of a new allow grant before bestowing it. Layer the hypothetical grant (and the permission it references, if not already stored) into an Overlay and ask SimulateExplain — the trace shows which hypothetical grant decided the verdict.

import (
	"github.com/frankbardon/aperture/model"
	"github.com/frankbardon/aperture/service"
)

ov := service.Overlay{
	Grants: []model.Grant{{
		ID:           "sim-grant-1",
		AccountID:    "acme",
		Subject:      model.Subject{Kind: model.SubjectPrincipal, ID: "bob"},
		PermissionID: "perm-doc-read",
		Effect:       model.EffectAllow,
		Object:       "account:acme/project:atlas/**",
	}},
}

tr, err := svc.SimulateExplain(ctx, ov, service.Query{
	Account:   "acme",
	Principal: "bob",
	Action:    "read",
	Object:    "account:acme/project:atlas/document:42",
})
if err != nil {
	return err
}
fmt.Print(tr.String()) // shows sim-grant-1 as the deciding grant — nothing was written

Because Simulate reuses the engine's exact resolution, a hypothetical deny overlay grant correctly carves out a stored allow, and a shadowing principal models "what if alice had role X" — all without a write.

SimulateExplain returns the same engine.Trace Explain does, attribute bags included, because it runs the live engine over an overlay store. One nuance: when the overlay carries unsaved rules, those rules are evaluated through a transient rule engine built for the overlay alone, which carries no attribute resolvers — so a previewed rule reads the floor bags (principal.{id, kind}, account.{id}) and nothing else, and earns an attributes_floor_only note if it names a host-defined field. A simulation cannot inject an attribute bag either: Overlay has no field for one.

Related what-if reads

Two adjacent reads support the rule-builder's what-if and require WithProviders:

• ObjectMetadata(ctx, objectID) (map[string]any, error) — the provider metadata a rule preview evaluates against.

• EvaluateRule(ctx, ast *rules.Node, objectID) (bool, map[string]any, error) — compiles an unsaved rule AST and evaluates it against one object's metadata, returning the boolean result and the metadata snapshot it saw.

• EvaluateRulePreview(ctx, ast *rules.Node, objectID) (RulePreview, error) — the same evaluation with the diagnostics a rule builder renders: Result, Object, Now (the reference instant, from the facade clock), Bounds (each relative-date operand and the concrete date it resolved to at Now), and Notes (the evaluation's deny-safe observations). EvaluateRule is its narrow projection.

  Unlike Check / Enumerate / Explain, this path compiles the AST directly instead of going through the decision engine, so it must supply the reference instant itself — a rules.Input with a zero Now has none, and every relative date correctly resolves to nothing.

  It also supplies no principal and no account input at all — not even the engine's floor. A rule reading principal.tier in the preview sees nothing, and no attributes_floor_only note is recorded, because there is no resolver behind it whose silence could be reported. This is the disclosure boundary of the whole preview surface: it is the wider-audience one (a rule author's editor), and handing it a principal bag would turn "evaluate this draft rule" into a read oracle for the principal directory — name a subject, compare a field, read the answer off the verdict. Explain takes the opposite side on purpose.

ObjectIdentifiers(ctx, objectType, exclude...) (also WithProviders) enumerates a type's complete instance set minus any excluded ids — the positive allow-list an exclusive allowance materialises to.

The attribute directory — a system-tier read

WithAttributes adds the one administrative door onto an attribute slot. Listing the user slot returns the host's whole user table, keys and bags together, so every method here is gated directly through authz.Gate.RequireSystemAdmin — the shape Export uses — rather than through a mutation tier. Nothing here writes, and nothing here is audited.

recs, err := svc.ListAttributes(ctx, actor, "user", provider.AttributeFilter{
	Fields: map[string]any{"department": "eng"},
	Limit:  100,
})

Three properties are contract, not implementation:

• The gate runs before the slot is parsed. A refused caller gets the identical APERTURE_AUTHZ_DENIED — nil slice, no count, no partial page — for a populated slot, an unregistered slot, and a slot name that does not exist, so a refusal cannot be used to probe which directories a deployment wires. A system-admin does get the real diagnostics.
• No gate wired means APERTURE_UNIMPLEMENTED, never "unrestricted": a bulk directory read has no narrower fallback to degrade to.
• The decision path's fetch is not gated, and must never be. A decision resolves one bag for a subject it already named, through the rules engine's resolvers — never through this option. The two paths reach the same registry through different seams.

Invalidation is a security control, not a performance knob: a slot's TTL is the window a revoked clearance keeps authorizing for, and these methods are how an operator closes it now instead of waiting it out. They clear the caches of this process only.

The wiring posture — a system-tier read

An instance can be told to re-read the shared wiring tables on an interval (--wiring-poll), so a aperture wiring push from another host is noticed without a restart. That re-read can fail: the store is unreachable, the rows it returns cannot be turned into a working registry, or a connection name in them is one this host has no route for.

When it fails the instance keeps the wiring it already has and keeps deciding. It has to — Aperture is embedded in-process in its first real host, so an access engine that stops answering takes the whole host down with it, and a fleet that stops answering because one operator pushed a bad row is worse than a fleet answering from wiring one push behind.

The price is staleness, and staleness is never silent. Every failure emits an APERTURE_* coded alarm, and the state is readable without touching a log:

p, err := svc.WiringPosture(ctx, actor)   // system-admin
if p.Stale {
	log.Printf("wiring stale for %s (%d failures, %s)", p.StaleFor, p.Failures, p.Code)
}

Two digests, and why they are two fields

Digest answers "did this instance get the push?" and has to stay comparable with what aperture wiring push wrote and with what aperture wiring diff reports, so nothing local may be folded into it. But a rebuild also re-reads this instance's own document, and that document decides things — inline objects: metadata, inline attributes: bags, the declared attribute-key sets taken from them, and on a deployment that has pushed nothing at all the whole of the wiring. So Digest alone left two instances able to report the identical value and return different verdicts.

LocalDigest is the second value that closes it. Sweep both: equal Digest means the same push landed; equal Digest and equal LocalDigest means the two instances were built from the same configuration.

Three things to know about it:

• It moves with an ADOPTION, exactly as Digest does. It names the document the RUNNING version was built from, not whatever is on disk now and not what the process booted on — a value captured once at boot would be wrong in precisely the case the field exists to expose.
• The two advance together or not at all. They are recorded as one pair (service.WiringDigests), taken from the version that was installed, so a posture can never name a combination no version was built from. A failed refresh moves neither.
• It is a content digest and carries nothing. It digests the parsed document, so a reformatted-but-equivalent file digests the same; it is a hash, so it carries no path, no account, no principal, no object id and no attribute key or value.

Five properties are contract, not implementation:

• It is not part of Capabilities, deliberately. Capabilities is an open, unauthenticated call because it carries booleans of immutable boot-time configuration and cannot fail. This is mutable runtime state about a fault whose useful half is a duration, and "this instance has been enforcing configuration its operator already replaced, for four hours" is operational intelligence for the operator, not for every anonymous caller. Adding a boolean there and keeping the duration here would be theatre — the boolean carries the disclosure.
• The gate runs before the recorder is consulted. A refused caller's error is identical for a healthy instance, one that does not poll, and one four hours stale, so a refusal cannot be used to probe whether an instance is degraded.
• An unwired recorder is an answer, not a refusal. Every deployment that has not opted into polling reports not-polling / not-stale, which is true. Refusing would make the read unusable as a fleet-wide probe.
• Recovery clears it completely. Any completed refresh — one that observed no change, which is almost every tick, or one that adopted a change — resets the window, the count and the code. An alarm that latches past its own remedy trains an operator to ignore the channel.
• A refresh that read the tables and then refused to ADOPT them has completed nothing. It keeps the alarm, and the window keeps its original start, so a push refused for four hours reports four hours and four failures rather than one failure a tick old. Clearing on the strength of the read alone is the subtle version of reporting a knowingly-superseded instance as healthy: the alarm still fires, but the number the operator escalates on is reset on every tick.

Over Twirp this is WiringPosture, which takes an Actor (system-admin authority resolves in an active account) and renders durations as Go duration text and instants as RFC3339.

Related

• Decision API — the raw engine operations the facade wraps.
• Batch operations — the facade's per-item batch rendering.
• Impersonation — the engine's *As operations.
• Library quickstart — the facade wired end to end.

RPC / HTTP overview

Audience: engineers integrating a non-CLI consumer (a service, a script, or the admin UI) against a running aperture serve.

Aperture exposes its full access-control API over HTTP as a Twirp service. Twirp is a plain request/response RPC framework: every method is an HTTP POST to a fixed URL, with a JSON (or protobuf) body and a JSON (or protobuf) reply. There is no streaming, no custom verbs, and no URL-encoded parameters — just one POST per call. This makes the surface trivially reachable from curl, any HTTP client, or a generated Twirp stub.

The service facade is the one code path

Everything on the wire is a thin translation onto the service.Service facade — the same facade the CLI drives and the same one the admin UI calls. HTTP / Twirp / CLI therefore share one decision engine, one mutation path, and one auth + admin-tier policy. A handler decodes the request, calls exactly one facade method, and encodes the result; there is no business logic in the transport layer (internal/server/).

Concretely, internal/server/twirp.go implements the generated rpc.ApertureService interface, and each method body is a few lines: decode, call h.svc.<Method>(...), encode. If a behaviour is not described here, it is governed by the facade and documented under The service facade.

Transport and endpoints

The Twirp service is mounted on a net/http ServeMux in internal/server/server.go, under a fixed base path:

/twirp/aperture.ApertureService/<Method>

• Method is the RPC name exactly as it appears in the proto (Check, PutGrant, Enumerate, …).
• Content-Type selects the codec: application/json for JSON bodies (the form shown throughout these docs) or application/protobuf for the binary form. Both are the standard Twirp codecs; the JSON encoding is identical to the library's own JSON.
• HTTP status is always 200 for a successful call — including a decision of deny, which is a successful answer, not an error. Failures map an Aperture coded error onto a Twirp error code and its HTTP status (see Errors below).

Two smaller routes share the same mux for convenience:

The server is started by aperture serve, which listens on --addr (default :8080) and wraps the whole mux in the authentication middleware.

service.proto is the source of truth

The canonical, machine-readable contract is internal/wire/rpc/service.proto. It declares roughly 60 RPCs and every request/response message. The committed service.pb.go / service.twirp.go are generated from it (make proto).

The reference in the next page is hand-authored: generating a page from the proto is out of scope, so the catalog summarises each RPC's purpose and points back to the proto for exact field lists. When in doubt about a field name or a message shape, read the proto — it is authoritative. If an RPC is added to the proto and this chapter is not updated, the proto wins; treat any discrepancy as a docs bug, not a contract change.

Auth model

Authentication is applied as net/http middleware (server.Authenticate, internal/server/middleware.go), wired in front of the whole mux by the serve command. It reads a bearer credential from the Authorization header and, on success, attaches the resolved Aperture principal to the request context:

• No credential → the request proceeds anonymously (no principal in context).
• A valid credential → the resolved principal is attached and the request proceeds as that identity.
• A bad credential → the request is refused 401 with a coded error (APERTURE_INVALID_TOKEN / APERTURE_UNAUTHENTICATED). A bad token is a hard failure, never silently downgraded to anonymous.

The authenticator adapter is chosen by --auth / APERTURE_AUTH_MODE; the default dev adapter treats the bearer token as the principal id, so Aperture runs with no external IdP out of the box (oidc and parsec are opt-in). See serve.

On top of that, each RPC enforces its own requirement, owned by the Twirp handler and the facade gate:

The actor is always the authenticated principal. For any mutation, the principal a change is attributed to and authorized against is the identity the middleware resolved from the request — never a value taken from the request body. The wire Actor.account field is honoured (it selects the active account), but a caller cannot act as someone else by editing the body.

The two administrative tiers themselves are ordinary in-scheme authority (documented in authz/): SYSTEM authority is a holder of system:* (or broader); ACCOUNT authority is a holder of account:<acct>/admin:* within one account, and is confined to that account. System supersedes account for account-tier mutations.

Errors and status codes

Every failure is an APERTURE_* coded error. The handler maps the code onto a Twirp error code (and thus an HTTP status) and attaches the canonical code as meta["code"] so a client can dispatch without parsing the message:

See Error Codes for the full registry.

APERTURE_RULE_UNDECLARED_ATTRIBUTE sits with the other rule-authoring codes at 400 rather than in the internal default, because the fault is in the submitted rule — it names an attribute key the deployment's wiring does not declare — so no retry of the identical request can succeed, and the rule editor renders it on the canvas beside the structural and type errors.

Why those two are 412 and not 500

Both are mapped out of the internal default on purpose, and the argument is the same in each case: nothing is broken, so nothing should page.

APERTURE_ENTITY_UNMANAGED means the deployment does not manage the entity kind the write targeted — a switch an operator set, working exactly as configured.

APERTURE_STORAGE_CONSTRAINT means the storage layer refused a write that would have broken referential integrity, overwhelmingly a delete whose children are still there: a role a principal still holds, a permission a role still bundles, an account with live memberships or grants. The caller is usually a fully privileged admin who took the teardown steps out of order. A 500 would page an on-call for a mistake the caller made and can fix, and would invite the one thing that can never work — retrying the identical request. A 400 would be closer but still wrong: the request is valid in isolation and becomes legal the moment the children are gone, so the fault is in the deployment's state, not in the message.

412 says exactly that, and the canonical code still rides in meta["code"], so a client dispatching on the code can look up the fixups — which enumerate the children to remove first. See Error Codes and the troubleshooting table.

A first call

An anonymous decision needs no credential:

curl -s -X POST http://localhost:8080/twirp/aperture.ApertureService/Check \
  -H 'Content-Type: application/json' \
  -d '{"account":"acme","principal":"alice","action":"read","object":"doc:42"}'

{ "allow": true, "reason": "grant g-123 allows read", "deciding_grant_ids": ["g-123"] }

A mutation needs a bearer token that resolves to a principal with the required tier — here, a system-admin creating an object type:

curl -s -X POST http://localhost:8080/twirp/aperture.ApertureService/PutObjectType \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer root' \
  -d '{"actor":{"account":"acme"},"entity_json":"{\"ID\":\"doc\",\"Actions\":[\"read\",\"write\"]}"}'

{}

Related

• RPC reference — the endpoint catalog by area.
• The service facade — the single code path every surface shares.
• serve — running the server; --addr, --auth, --store.
• Error Codes — the APERTURE_* registry.

RPC reference

Audience: engineers wiring specific calls against aperture serve.

This is a hand-authored catalog of the ApertureService RPCs, grouped by area. It summarises each method's purpose, its request/response messages, and its auth requirement. The canonical, exact field lists live in internal/wire/rpc/service.proto — read it for message shapes; this page is maintained by hand and may lag the proto (the proto wins on any discrepancy).

Every method is a POST to /twirp/aperture.ApertureService/<Method> with a JSON body. See the overview for transport, auth, and error mapping. Auth shorthand used below:

• open — no authenticated principal required.
• auth — requires an authenticated principal.
• system — requires system-admin authority (system:*).
• account — requires account-admin authority in the target account (system supersedes).
• own rule — not gated by the admin tiers; carries its own delegation / impersonation authorization.

Wire-shape convention

Simple hot-path messages (Check, Enumerate) carry their fields directly. Rich or recursive shapes — the model entities with their timestamps, the Explain trace, the rule AST — ride as a canonical JSON string in a *_json field rather than being modelled in proto. That JSON is identical to the library's own encoding of the corresponding model.* struct. So an EntityRequest.entity_json is just the JSON of a model.ObjectType, model.Grant, etc., and an EntityResponse.entity_json is the same on the way back.

Mutations carry an Actor { principal, account }. On the wire the principal is ignored — the authenticated identity from the middleware is always used — while account selects the active account. Reads that are account-scoped resolve their authority from the authenticated principal directly.

Decision RPCs (open)

The core decision API, single and bulk. These are open (no principal required) and always answer fail-closed.

curl -s -X POST http://localhost:8080/twirp/aperture.ApertureService/Enumerate \
  -H 'Content-Type: application/json' \
  -d '{"account":"acme","principal":"alice","action":"read","pattern":"doc:*","limit":50}'

{ "object_ids": ["doc:42", "doc:77"] }

SearchRequest — resolving a name to an id

Search is the call to make when a question arrives in a person's own words and every step after it needs ids.

curl -s -X POST http://localhost:8080/twirp/aperture.ApertureService/Search \
  -H 'Content-Type: application/json' \
  -d '{"account":"acme","principal":"alice","action":"read",
       "pattern":"account:acme/brand:*","query":"nike","limit":5}'

{ "matches": [
    { "object": "account:acme/brand:42", "score": 0.875,
      "field": "label", "value": "Nike, Inc.",
      "metadata": { "label": "Nike, Inc.", "sector": "Footwear" } }
] }

The result is already scoped — do not filter it client-side. Candidates are decided before they are scored, by the same walk Enumerate uses, so the matches are always a subset of what Enumerate would return for the same account, principal, action and pattern. The alternative shape — enumerate a type over the wire, then match in your client — puts the unscoped set across the boundary first and narrows it second, and any bug in that client-side filter turns your surface into an enumeration oracle for every object in the system.

A score ranks; it never authorizes. Nothing in Aperture reads one. A client that acts on a returned id still calls Check.

Matching is case- and punctuation-insensitive (Nike, Inc. matches nike inc) and tolerates a typo or transposition. Only text is matched — a string field and the string elements of a list field; match a number, bool or date through fields instead.

Each match's metadata is the object's full bag, encoded exactly like EnumerateRequest.fields and carrying the same caveat: a google.protobuf.Value holds a number as a double, so an integer beyond 2^53 loses precision in transit. It rides along so labelling a result set costs no further round-trip.

Search requires the deployment to have an object-metadata source wired. Without one the answer is APERTURE_PROVIDER_UNREGISTERED, never an empty matches list — an empty list reads as "you may see nothing" and would hide the misconfiguration.

EnumerateRequest.fields — the object-metadata filter

EnumerateRequest carries an optional fields map (field 6, map<string, google.protobuf.Value>) that narrows the result by object metadata. Omitting it filters nothing, so an existing client is unaffected.

curl -s -X POST http://localhost:8080/twirp/aperture.ApertureService/Enumerate \
  -H 'Content-Type: application/json' \
  -d '{"account":"acme","principal":"alice","action":"read","pattern":"account:acme/**",
       "fields":{"tier":"premium","seats":5,"brands":"brand:Y"},"limit":50}'

Semantics — the same contract a provider's own Filter.Fields obeys, evaluated by the same code, so a filtered enumeration and a provider-side query select the same objects:

Why Value and not a JSON string. The predicate compares by type, so the string/number/bool/list distinction has to be visible in the schema — a JSON blob in a string field would be opaque to every generated client and unvalidatable at the boundary. Each Value kind maps to exactly one shape, recursively, with no coercion between kinds: null→absent-ish nil, number→float64, string→string, bool→bool, list→array, struct→object.

Caveat: integers beyond 2^53. google.protobuf.Value carries every number as a double, so an integer larger than 2^53 loses precision in transit. Send such a key as a string and store it as a string in metadata. Nothing in the conversion can repair the loss — it is a property of Value itself. (internal/wire/rpc's TestFieldsRoundTrip_LargeIntegerLosesPrecision pins this, and fails loudly if it ever stops holding.)

Rejections are APERTURE_INVALID_INPUT / 400, never a dropped predicate — a dropped predicate widens the result, and a filter that silently widens is a filter that authorizes:

• a non-finite number (NaN, ±Inf). It would otherwise become the string "NaN", an unsatisfiable predicate that reads as "no access". Note protojson cannot marshal a non-finite Value at all, so only the binary codec can reach this guard;
• a Value with no kind set (unreachable from a generated client, reachable from a hand-rolled one).

In EnumerateBatch a malformed predicate fails only its own item — that item carries the error code/message and never an empty object_ids, and the rest of the batch runs.

Wiring: the server must have an object-metadata source (the same provider registry that backs object listing). Filtering a type with no registered provider, or with no source configured at all, is APERTURE_PROVIDER_UNREGISTERED / 404 rather than an empty list — an empty list would read as "no access" and hide the misconfiguration. Because the predicate runs per candidate, that error only appears when the enumeration has at least one allowed candidate. An object the provider has no row for is simply excluded (every field absent, and absent never matches).

EnumerateRequest.references — the reference edges

EnumerateRequest also carries an optional references list (field 7, repeated ReferenceEdge) that restricts the result to the identities a holder object's declared reference field contains — "the brands in dataset X". Omitting it restricts nothing, so an existing client is unaffected. EnumerateBatchRequest embeds EnumerateRequest, so edges ride per query.

message ReferenceEdge {
  string holder_type = 1;  // OPTIONAL; empty means holder_id's terminal segment type
  string holder_id   = 2;  // required — "account:acme/dataset:7"
  string field       = 3;  // required — a DECLARED reference field
}

curl -s -X POST http://localhost:8080/twirp/aperture.ApertureService/Enumerate \
  -H 'Content-Type: application/json' \
  -d '{"account":"acme","principal":"alice","action":"read","pattern":"account:acme/brand:*",
       "references":[{"holder_id":"account:acme/dataset:x","field":"current_brands"}]}'

It is a dereference, not a filter, and the two are not interchangeable. fields answers "which datasets contain brand Y?" — the dataset holds the field, so a predicate on dataset expresses it. references answers the mirror image, "which brands belong to dataset X?" — a brand holds no field naming its datasets (references are declared on the holding side only), so no predicate on brand can express it at all.

The security semantics are the point, and they are asserted over a real JSON round trip — a boundary that turned an empty result into a 404, or a 404 into an empty list, would silently change what the server discloses about objects it never let the caller see:

APERTURE_PROVIDER_REFERENCE_INVALID is a 400, not the 500 the default mapping would give it: the only way a client reaches it is an edge naming an undeclared field — its own input, which no retry can fix — and 5xx is the one class a client is entitled to retry and an alert rule is entitled to page on. The Aperture code is in meta["code"] either way.

In EnumerateBatch each item keeps its own answer: one query's 404 never becomes another's, and a fail-closed empty result is reported as an empty list rather than an error.

See Object references for the declaration side, and the CLI's --via for the same query from a terminal.

Entity CRUD

Full create/read/list/delete for each model entity. The write body is entity_json (a model.* struct as JSON); reads return entity_json (single) or entities_json (list). List RPCs accept an optional server-side Filter (field predicates ANDed or ORed) applied before the response is returned.

Writes are system-tier (managing the global schema); reads require auth.

¹ ListPrincipals and ListAccounts resolve read visibility against the caller's admin authority, so an account-admin sees only what their tier permits.

Requests: PutX uses EntityRequest { actor, entity_json }; GetX/DeleteX use GetRequest/DeleteRequest { actor, id }; ListX uses ListRequest { filter }. Responses: EntityResponse / EntityListResponse / Empty.

ObjectIdentifiers (ObjectIdentifiersRequest → ObjectIdentifiersResponse, auth) enumerates every instance id of an object type from its provider, optionally minus an exclude list — an admin/config read over all objects of a type.

curl -s -X POST http://localhost:8080/twirp/aperture.ApertureService/PutGrant \
  -H 'Content-Type: application/json' -H 'Authorization: Bearer acme-admin' \
  -d '{"actor":{"account":"acme"},"entity_json":"{\"ID\":\"g-1\",\"Account\":\"acme\",\"Principal\":\"alice\",\"Action\":\"read\",\"Object\":\"doc:*\",\"Effect\":\"allow\"}"}'

Grants and memberships (account-tier)

Grants and memberships are account-scoped: writes require account-admin in the target account; reads resolve against the caller's authority.

Rules (definition writes system; reads auth)

Rules are global schema: named, persisted rule-AST definitions the node editor authors and the rule-backed scope strategies resolve. The AST rides as a model.Rule JSON in rule_json.

What-if / simulation (auth)

Read-only previews. Nothing is written and nothing is audited.

Templates

Reusable grant bundles. Definition writes are system-tier; apply is account-tier (it materialises grants into a target account).

Bulk grant / revoke (account-tier)

Transactional multi-grant mutations, both account-tier.

Declarative state (system-tier)

Whole-model portability.

Audit query (gated read)

Deployment posture and health

WiringPosture is the deliberate counterpart to Capabilities: the same kind of question, the opposite answer about who may ask. It is gated, and not a field on CapabilitiesResponse, because it carries mutable runtime state about a FAULT whose useful half is a duration — and because "this instance has been enforcing configuration its operator already replaced, for four hours" tells an anonymous caller that the enforced policy is not the intended policy, and how long the window has been open.

It takes an Actor rather than Empty for the reason every other system-tier call does: system-admin authority resolves in the caller's active account, and only the caller knows which of its accounts that is. The principal on the wire is ignored as always.

Sweep both. Equal digest across a fleet means the same push landed; equal digest and equal local_digest means the two instances were built from the same configuration. Neither field carries a path, an account, a principal or an object — both are hashes.

Every field is empty or false on a healthy instance, so "nothing is wrong" needs no interpretation. An instance that does not poll — and a server whose facade was built without a recorder — answers with polling: false, stale: false rather than refusing, so the read is usable as a fleet-wide probe. Nothing here carries model data: digests, durations, counts and coded errors only.

Delegation (own rule)

Not admin-gated; authorized by the delegation subset rule, with the actor = the authenticated delegator.

Impersonation (own rule)

Not admin-gated; authorized by the impersonation guardrails, with the actor = the authenticated operator. Sessions are stateless, time-boxed values.

Related

• RPC / HTTP overview — transport, auth model, error mapping.
• service.proto — the canonical contract.
• The service facade — the shared code path.
• Error Codes — the APERTURE_* registry.

MCP surface

Audience: authors integrating Aperture into an MCP client (an AI assistant or agent runtime) as a tool provider.

Aperture exposes its decision API and model inspection as Model Context Protocol tools. An MCP client spawns aperture mcp as a subprocess, speaks MCP over stdio, and calls the Aperture tools the same way it calls any other tool server.

Read-only by construction

The MCP surface is read-only. Every tool calls a read or decision method on the single service.Service facade — Check / Enumerate / Explain, the what-if Simulate, and the Get* / List* inspectors. No tool mutates. No tool name carries a mutating verb (put / create / add / set / delete / remove / update / write / bestow / revoke / grant / …), and a test (mcp.TestNoMutatingTool, mirrored at the wire level in the adapter) fails if one ever does. The aperture mcp command deliberately wires the facade with storage for inspection and what-if reads but not the gate, delegation, or impersonation mutators, so the surface cannot write even by accident.

Everything on the surface is a thin translation onto the same facade the CLI and the HTTP/Twirp surface drive — one decision engine, one code path. If a behaviour is not described here it is governed by the facade and documented under The service facade.

The tool catalog

The catalog is stable and ordered. Tool names are aperture_-prefixed, snake_cased, and defined once in mcp/toolmeta (the single source of truth for tool identity), so the SDK-free core and the SDK adapter never drift.

Decision API (single + bulk)

What a trace discloses about attributes

ExplainOut — and SimulateOut — are type aliases for engine.Trace, so every one of these tools serializes the trace verbatim. That includes its Attributes field: the principal and account bags the decision's rules were evaluated against, values included.

That is a deliberate disclosure, and it reached this surface with no mcp/ code change at all — which is exactly why it is written down here. The two bags are the subjects of the very request being explained (the principal and account named in the query), so a trace tells the asker about their own decision and nothing else; see the attribute bags. Gate the MCP surface accordingly: an agent that may call aperture_explain on an arbitrary (account, principal) pair can read that principal's attribute bag for that account.

There is deliberately no attribute tool. Listing a slot returns the host's whole user table, and MCP is where an agent doing that is least defensible, so the directory read stays a system-tier CLI operation (aperture attributes) and never becomes a tool.

aperture_enumerate's Fields filter

Fields is an optional object of metadata predicates that narrows the listing — "which of the datasets alice may list carry brand Y?". Omit it to filter nothing; it is not a required property, so an unfiltered enumerate is a valid call for a schema-validating client.

{
  "Account": "acme", "Principal": "alice", "Action": "list",
  "Pattern": "account:acme/**",
  "Fields": { "tier": "premium", "seats": 5, "brands": "brand:Y" }
}

The predicates are ANDed; a field the object does not carry never matches; a list-valued field matches by membership; everything else is typed equality, so "5" never matches 5. The filter runs on objects the principal is already allowed — it can only remove ids, never add one — and it is applied before Limit, so Limit: 10 returns the first ten matches.

The schema is reflected straight off service.EnumerateQuery, so the tool input and the Go facade query are the same type; the semantics above are carried in the property description an agent reads.

aperture_enumerate's References edges

References is an optional list of reference edges that restricts the listing to the identities a holder object's declared reference field contains — "which brands belong to dataset X?". Omit it to restrict nothing; like Fields, it is not a required property.

{
  "Account": "acme", "Principal": "alice", "Action": "read",
  "Pattern": "account:acme/brand:*",
  "References": [{ "HolderID": "account:acme/dataset:x", "Field": "current_brands" }]
}

HolderID and Field are required properties of an edge; HolderType is optional and, when given, must agree with HolderID's last segment type.

This is not the same thing as Fields, and an agent that treats them as interchangeable will get the wrong answer. Fields is a filter — "which datasets contain brand Y?" — and works because the dataset holds the field. References is a dereference — "which brands belong to dataset X?" — and exists because a brand holds no field naming its datasets, so no filter can express that question at all.

Several edges are ANDed, an edge composes with Fields, both apply before Limit, and exactly one hop is taken.

The answers an agent must not over-read:

• A holder the principal may not see returns an empty list, not an error. Emptiness here means "nothing you may see", and it is deliberately indistinguishable from "you may not see the holder" — do not report it as a permission failure.
• An absent holder is APERTURE_NOT_FOUND only when it is inside the request's account and the principal is a member of it. Out of account, or for a non-member, the answer is empty.
• An edge naming a field that is not a declared reference is a loud APERTURE_PROVIDER_REFERENCE_INVALID, never an empty list — it means the deployment is not wired for that question, not that access was denied.

What-if simulation (read-only, never persisted)

Model inspection

Surface documentation

Grants are account-scoped by design: aperture_list_grants requires an account argument and never returns another account's grants, so the surface cannot leak cross-account data.

Name resolution, and the two things an agent must not assume

aperture_search exists because an agent receives questions in a person's words and needs ids. Two properties are stated in the tool's own description, because an agent has no other source of truth and both failure modes are silent:

1. A score is not a permission. It ranks candidates so the agent can pick one or ask which was meant. An id still goes through aperture_check before it is acted on.
2. The result is already scoped. There is nothing to filter afterwards, and an object missing from the result is one this principal may not see — not a matching failure to work around by enumerating the type and filtering locally. That workaround is precisely the bare-enumeration shape the surface exists to remove.

Query is required; there is no "match everything". For the whole entitled set the tool is aperture_enumerate. Each match carries the object's full metadata inline, so an agent should not follow up with per-id metadata reads to label what it found.

Inputs, outputs, and errors

Each tool carries an input and output JSON Schema (draft 2020-12), reflected at package-init time from the typed Go contract in mcp/schema.go and mcp/contract.go. The In/Out types alias the facade's own surface-neutral types (for example aperture_check's input is service.Query and its output is service.Result), so the schema advertised to the client is exactly the shape the facade decides on. A client discovers these schemas through the standard MCP tools/list call — no Aperture-specific schema fetch is needed.

Argument handling and error surfacing:

• Parameterless tools (the list_* inspectors, aperture_skills_list) accept an empty argument blob.
• A missing required argument (for example id on a get_* tool) returns a plain validation tool-error, surfaced to the model so it can self-correct — it is intentionally not a coded error.
• A coded facade error (an APERTURE_* error) is returned verbatim; the adapter renders it as a structured {code, message, details} envelope rather than a flattened string.
• In the batch tools, a per-item failure is folded into that item's error field (a string); the rest of the batch is unaffected.

The mcp/ core and the SDK firewall

The core lives in the root mcp/ package and is SDK-free: it imports no MCP protocol SDK. Its files divide the surface cleanly:

The core depends only on the decision facade (service), the domain types it returns (engine, model), the coded-errors package (errors), the embedded skill docs (mcp/skills, stdlib-only), and the schema reflector (google/jsonschema-go). It carries the schema as json.RawMessage specifically so a consumer can import the contract without pulling in any MCP SDK.

The adapter is the only SDK importer

The one package permitted to import the protocol SDK (github.com/modelcontextprotocol/go-sdk) is the thin mcp/gosdk adapter. gosdk.Register(server, svc, cfg) mounts the core's ToolDescriptor catalog onto a caller-supplied go-sdk server via the low-level Server.AddTool path — which accepts any value that marshals to a valid 2020-12 schema, exactly the json.RawMessage the core emits. Register mounts onto the server it is given; it never constructs, serves, or owns the server lifecycle. An embedder that already runs its own go-sdk server can mount the full Aperture surface the same way.

firewall_test.go makes the guarantee load-bearing

mcp/firewall_test.go enforces the boundary so it is a fact, not an aspiration:

• TestMCPCore_NoSDKImport runs go list -deps over the core packages (mcp, mcp/toolmeta, mcp/skills) and fails if the MCP SDK module appears anywhere in their transitive dependency graph. Moving an SDK import into any core package makes this test fail with the exact offending dependency line.
• TestMCPCore_AllowedDepsReachable asserts the documented allow-list (service, engine, model, errors, mcp/skills, mcp/toolmeta, google/jsonschema-go) is reachable from the core, proving the firewall is inspecting a real, populated graph rather than passing vacuously.

The adapter (mcp/gosdk) is deliberately excluded from the firewall's package list — the SDK is allowed there and nowhere else. This keeps the promise a client author relies on: importing the Aperture MCP contract never drags in a protocol SDK.

Running it

aperture mcp hand-wires the read-only dependency graph (storage → engine → service), constructs the go-sdk server, mounts the SDK-free catalog through the gosdk adapter, and serves over stdio — the transport an MCP client uses when it spawns Aperture as a subprocess:

aperture mcp [--seed <path>] [--store <dsn>]

• --seed — path to a JSON/YAML seed model to apply on startup. Omitting it loads the embedded example for the in-memory store and seeds nothing for a --store DSN (see Global options).
• --store — DSN for the backing store (defaults to in-memory).

With neither flag it serves the embedded example model over an in-memory store. There are no other flags: the surface is read-only by construction, so it needs no acting principal, account, or auth adapter.

On start it prints one line to stderr — stdout is reserved for the MCP protocol:

aperture mcp: serving read-only MCP surface over stdio

Connecting a client

You normally don't launch aperture mcp interactively; an MCP client spawns it over stdio. A minimal client configuration points at the binary and the model to serve:

{
  "mcpServers": {
    "aperture": {
      "command": "bin/aperture",
      "args": ["mcp", "--store", "./aperture.db"]
    }
  }
}

The server advertises its identity as aperture with the binary's build version during the MCP initialize handshake, then answers tools/list with the full catalog above and tools/call for each tool.

Related

• aperture mcp — the command-level reference and flags.
• The service facade — the one code path behind every tool.
• Decision API — the same check/enumerate/explain questions from Go.
• RPC / HTTP overview — the read/write Twirp surface served by aperture serve.

Admin UI shell

Audience: operators who want to browse and edit the access-control model from a browser instead of the CLI or raw RPC.

Aperture ships a small embedded admin UI — a static, single-page frontend served from the root of a running aperture serve. It is not a separate service: the HTML, CSS, and JavaScript are compiled into the binary and mounted at /, so starting the server is all it takes to reach the UI. Every screen is a thin client over the same Twirp / HTTP surface; the shell holds no access-control logic of its own — it decodes what the server returns and posts mutations back through the facade.

What it is built from

The shell is deliberately dependency-light and builds with no Node pipeline. Its assets are pre-built, committed blobs embedded via //go:embed all:static (see internal/server/static.go), so the binary stays self-contained in dev and CI.

The full frontend lives under internal/server/static/ (index.html, css/, js/, and vendor/). Vendored blobs (Alpine, Tailwind, DaisyUI) are pinned and documented in internal/server/static/vendor/README.md. The Rete.js bundle is the one asset regenerated by a manual make vendor-rete target — it is never rebuilt in CI. Treat all of these as committed artifacts, not build outputs.

How to reach it

Start the server and open the listen address in a browser:

aperture serve            # listens on :8080 by default

• Default address: :8080 (override with --addr). See the serve command for all flags.
• The UI is mounted last on the mux at /. More specific routes — the Twirp path prefix, POST /check, GET /healthz — take precedence, so the frontend never shadows the API.

Auth expectation

Aperture's authentication is external — the shell never issues credentials. Every request the UI makes is routed through a single apiFetch wrapper that attaches an Authorization: Bearer <token> header, and a 401 clears the token and re-opens the sign-in affordance.

With the default dev authenticator (aperture serve with no --auth override), the bearer token is the principal id: "signing in" through the UI just names which principal your session presents. Switching to the oidc or parsec adapters changes how that bearer is obtained, but the shell's behaviour is unchanged — it still only carries whatever token it holds. A global account switcher in the top bar picks the active account shared by every screen; the server scopes the account list to what the signed-in principal may see (ListAccounts).

Screen tour

The left-hand nav routes by URL hash (#/crud, #/grants, …). Each screen is one Alpine component in static/js/, and each drives a small set of Twirp RPCs on aperture.ApertureService.

Model (CRUD) — #/crud

The model editor. Browse and mutate the core entities — principals, roles, groups, permissions, object types, and accounts — plus account memberships. It lists each entity type (ListPrincipals, ListRoles, ListGroups, ListPermissions, ListObjectTypes, ListAccounts), creates/updates via the matching Put*, and removes via Delete*; memberships use PutMembership / DeleteMembership. It probes the viewer's admin tier with the open Check RPC and can Export the model.

Grants — #/grants

Bestowed grants, delegation, and grant templates. Lists and edits grants (ListGrants, PutGrant, DeleteGrant), issues and rescinds authority (Bestow, Revoke), and manages templates (ListTemplates, PutTemplate, DeleteTemplate, ApplyTemplate) with a bulk path (BulkPutGrants). It uses Check to resolve the viewer's tier.

Graph — #/graph

A force-directed map of the whole model rendered on a <canvas>. It pulls the entire declarative model with a single Export RPC (seeding an account via ListAccounts first) and derives every node and edge — subjects, grants, objects, memberships, roles, and reachability — from that one document, so the picture always reflects the live store. The layout is a small self-contained simulation; no external graph library is used here.

Rules — #/rules

The rule-blueprint editor. This is where Rete.js is used: rules are edited as a node graph on a Rete canvas, then serialized to Aperture's rule AST. It loads and saves rules (ListRules, GetRule, PutRule), lists object types (ListObjectTypes) and object identifiers (ObjectIdentifiers), and validates or dry-runs an expression against the live model (ValidateRule, EvaluateRule, Check).

The what-if preview shows more than the verdict: the reference instant the evaluation resolved against, what each relative-date operand became at that instant, and the deny-safe notes explaining a false. Dates are rendered verbatim, Z included — the editor never constructs a JavaScript Date, which would restate a stored UTC instant in the viewer's own zone.

What-if — #/whatif

A read-only decision simulator. Ask "would principal P be allowed action A on object O?" and see both the verdict and the full explain trace — the expanded subject set, every grant considered with its per-grant outcome, and the deciding grant(s). It drives the open Check and Explain RPCs (no mutation), listing accounts via ListAccounts. It runs a hypothetical against the live model without writing anything.

Audit — #/audit

A queryable table over the append-only audit trail via the QueryAudit RPC. Every mutation, impersonation, and delegation is always recorded; decisions are sampled. Read access is tier-gated — a system-admin reads everything, an account-admin reads only events scoped to their own account — and the screen probes both tiers with Check (using ListAccounts for scope). A viewer with neither tier is told why the table is empty.

Import / export (portability) — #/portability

Download the declarative model file or import one with a preview diff. It exports the whole model (Export), and imports a supplied document (Import) after resolving the viewer's tier with Check and scoping with ListAccounts.

Related

• RPC / HTTP overview and the RPC reference — the surface every screen calls.
• serve command — flags, listen address, and auth adapter.
• The service facade — the one code path behind every RPC the UI drives.

Identity patterns & specificity

Everything Aperture decides is expressed in one primitive: a uniform, hierarchical identity. The same type describes principals (the actor a decision is made for) and objects (the resource an action targets), so there is no second addressing scheme to learn. This chapter defines that primitive, the pattern grammar a grant uses to cover many identities at once, the Contains containment test delegation relies on, and the specificity score that resolves overlapping matches.

If you have not read the Concepts primer, skim it first — it fixes the vocabulary (principal, object, grant, effect) this page builds on. The code lives in the identity package.

The identity primitive

An identity is an ordered path of typed segments. Each segment is a type:id pair; segments are joined by /:

account:acme/project:atlas/document:42

Read left to right, each segment narrows the path: account acme, then project atlas within it, then document 42 within that. A principal is written the same way — user:alice or account:acme/team:eng — because principals and objects share the type.

The grammar is intentionally strict, and matching runs on the Check hot path (the NFR target is p99 < 1 ms), so parsing validates without regular expressions and stores segments pre-split so a match never re-parses:

• A segment's type and id are each non-empty.
• Allowed characters in a component are ASCII letters, digits, and -._~@+ — enough for slugs, UUIDs, and qualified ids, while excluding the structural delimiters / and :, whitespace, and the * wildcard sentinel.
• An empty string, an empty segment (a leading, trailing, or doubled /), a segment missing its :, or an illegal character is rejected as an APERTURE_IDENTITY_INVALID coded error.

identity.Parse builds an Identity from its canonical string and round-trips losslessly (Parse(s).String() == s); identity.New builds one from segments a caller already holds. The identity package depends on nothing but the root errors/ package, so it stays a leaf every other layer resolves against.

id, err := identity.Parse("account:acme/project:atlas/document:42")
if err != nil {
    // APERTURE_IDENTITY_INVALID
}
id.Len()        // 3
id.Segments()   // []Segment{{account,acme}, {project,atlas}, {document,42}}

Patterns

A single grant rarely names one object. A pattern is an identity with wildcards that describes a set of concrete identities; a grant's object scope is a pattern. Build one with identity.ParsePattern. Beyond the concrete-identity grammar, a pattern segment may be:

A component set lets one grant scope to several ids without a wildcard, so brand:{1,5,23} covers exactly three brands and nothing else. The set must be non-empty ({} is rejected); duplicate members are dropped, preserving order.

How a pattern matches

Pattern.Matches(identity) is anchored at both ends: every identity segment must be consumed and every pattern segment satisfied. A literal or single * each consume exactly one identity segment; ** consumes one-or-more via backtracking. The matcher slices into the pre-compiled segments and does not allocate.

Pattern                                     Matches?
account:acme/project:atlas/**               account:acme/project:atlas/document:42   ✓ (** = "document:42")
account:acme/project:atlas/**               account:acme/project:atlas               ✗ (** needs ≥1 segment)
account:acme/project:*/document:42          account:acme/project:atlas/document:42   ✓ (project id wildcard)
account:acme/brand:{1,5,23}                 account:acme/brand:5                     ✓ (5 ∈ set)
account:acme/brand:{1,5,23}                 account:acme/brand:9                     ✗ (9 ∉ set)

Because ** must consume at least one segment, a pattern is never shorter than the identities it matches minus its wildcard expansion — a trailing ** matches any non-empty remainder but not the empty one.

Enumerating a finite pattern

When a pattern contains no * or ** anywhere — every segment is a literal whose components are plain literals or explicit sets — its language is finite. Pattern.Expand() returns that concrete set as the deterministic cross-product of each segment's members (segment order, then written member order), reporting ok=false for any pattern with a wildcard (whose language is unbounded or provider-dependent). This lets a set-scoped grant like brand:{1,5,23} list its three concrete objects without consulting a provider.

Specificity: resolving overlaps

Two grants can both match the same object with different effects — a broad allow on account:acme/project:atlas/** and a narrow deny on account:acme/project:atlas/document:secret. Aperture resolves this with deny-overrides ranked by specificity: the more specific pattern wins, and on a genuine tie deny beats allow. identity.Specificity(pattern) produces the deterministic score that drives the tiebreak.

The score is a single weighted integer (paths are short, so there is no overflow risk) built from three signals:

A type:id literal contributes up to two literal components; a component wildcard (*) or a bare * segment contributes none (only its pinned position). The result is that the pattern a human would call "more specific" — more fixed components, fewer and shallower wildcards — always scores strictly higher.

Pattern                                        Specificity
account:acme/project:atlas/document:secret     6 literals·10000 + 3 segs·100      = 60300
account:acme/project:atlas/**                  4 literals·10000 + 3 segs·100 − 1000 = 39300
account:acme/**                                2 literals·10000 + 2 segs·100 − 1000 = 19200

identity.Compare(a, b) returns +1 / -1 / 0 as a total, deterministic order (safe as a sort key), and identity.MoreSpecific(a, b) reports whether a ranks strictly above b. The decision engine consumes these directly; this package never applies deny-overrides itself — it only supplies the ranking.

flowchart TD
    O["object: account:acme/project:atlas/document:secret"]
    O --> G1["grant A · allow<br/>account:acme/project:atlas/** · spec 39300"]
    O --> G2["grant B · deny<br/>account:acme/…/document:secret · spec 60300"]
    G1 --> R{"both match —<br/>rank by specificity"}
    G2 --> R
    R -->|"B is more specific"| D["deny wins"]

Containment: Contains

Delegation asks a different question: is one grant's authority a subset of another's? identity.Contains(outer, inner) answers it structurally — it reports whether outer's language is a superset of inner's, i.e. every concrete identity inner matches, outer matches too. Equivalently, inner is "equal-or-more-specific / contained within" outer. outer.Contains(inner) is the method form.

The test is sound and conservative: it never reports containment that does not hold, but — because it is a structural check rather than a full language inclusion decision over the one-or-more ** — it may return false for some genuinely-contained pairs. Delegation fails closed, so a false negative merely rejects a bestow that could in principle have been allowed; it never permits an escalation. It is reflexive (a pattern contains itself).

Contains(account:acme/**,           account:acme/project:atlas/document:42)  = true
Contains(account:acme/brand:{1,5},  account:acme/brand:5)                    = true
Contains(account:acme/brand:{1,5},  account:acme/brand:{5,9})                = false (9 ∉ {1,5})
Contains(account:acme/*,            account:acme/**)                         = false (single can't cover ≥1)

For a component, an outer wildcard covers anything, an inner wildcard is never subsumed by a fixed outer, and otherwise both reduce to finite value sets where outer must contain every inner value — so {1,5,23} subsumes 5 and {1,5} but not 3 or {5,9}.

Where this leads

Patterns bound what a grant covers, but membership within that bound can be more than literal matching — a grant can cover "every object of this type" or "these ids only" or "whatever a rule selects." That is the job of scopes and scope strategies. The attributes a rule reads about an object are supplied by the host through providers. For the end-to-end decision flow that consumes specificity, see the library Decision API.

Rules engine

A grant can be gated on the attributes of a request — deny a read unless the object's classification is public, allow a share only for principals above a clearance tier. Aperture expresses those conditions as rules. A rule is a small, typed AST that Aperture compiles once to an expression program and evaluates in-process against the object's metadata plus the principal/action context.

Aperture evaluates rules with expr-lang/expr directly. It renders each rule AST to an expr-lang expression and compiles it with expr-lang's pure-Go evaluator, in-process. There is no external policy service and no dependency on Pulse — any documentation that says "Pulse expression" is stale. The rules package imports github.com/expr-lang/expr; that is the whole engine.

The code lives in the rules package, in three layers: the AST (ast.go), the compiler and cache (compiler.go, cache.go), and the engine (engine.go).

The rule AST

A rule is a tree of rules.Node values. The node set is deliberately small and closed so a node editor can map its palette one-to-one onto it, and so the JSON form is a stable contract that round-trips byte-identically (marshal → unmarshal → marshal). There is no second rule format.

The operators carried in compare.Op are covered in the operator vocabulary below.

Constructor helpers build the tree in Go — And, Or, Not, Compare, Unary, Var, Lit, List, Call. This rule says the object is public, or the principal's tier is one of gold/platinum:

ast := rules.Or(
    rules.Compare(rules.OpEq, rules.Var("object.classification"), rules.Lit("public")),
    rules.Compare(rules.OpIn, rules.Var("principal.tier"),
        rules.List(rules.Lit("gold"), rules.Lit("platinum"))),
)

Its canonical JSON — the shape the editor and the state file persist — omits every zero field, keeping the serialized form minimal:

{
  "type": "or",
  "children": [
    {"type": "compare", "op": "eq",
     "left": {"type": "var", "name": "object.classification"},
     "right": {"type": "literal", "value": "public"}},
    {"type": "compare", "op": "in",
     "left": {"type": "var", "name": "principal.tier"},
     "right": {"type": "list", "items": [
       {"type": "literal", "value": "gold"},
       {"type": "literal", "value": "platinum"}]}}
  ]
}

The evaluation context

A rule reads from a closed set of four roots, and only those — a reference to anything else is an unknown variable:

The three metadata roots are map[string]any so a rule reads host-defined fields dynamically; action is a typed string so misusing it (action.foo) is a type error. This closed environment is enforced twice — structurally by Validate (below) and again by the expr-lang type-checker at compile time.

The operator vocabulary

There are eleven comparison operators beyond the six scalar ones. All of them are values of compare.Op — none is editor-only sugar, because the AST is the editor's serialization target and the state file's persisted form: a rule authored as has all must read back as has all.

Scalar comparisons

Both operands are required and either may be any operand node.

Collection operators

Left is the collection being tested (for exists, any path at all). Right is the operand — and the last three operators are unary: they reuse the same compare node with Right omitted, rather than introducing a new node type.

// "tagged both a and b, in no blocked region, and it actually has an owner"
rules.And(
    rules.Compare(rules.OpHasAll, rules.Var("object.tags"),
        rules.List(rules.Lit("a"), rules.Lit("b"))),
    rules.Compare(rules.OpHasNone, rules.Var("object.regions"),
        rules.Var("account.blockedRegions")),
    rules.Unary(rules.OpExists, rules.Var("object.owner.dept")),
)

rules.Unary(op, left) builds a unary node; it is still a compare node, and its JSON simply carries no right key:

{"type":"compare","op":"isEmpty","left":{"type":"var","name":"object.tags"}}

That omission is part of the contract. Validate requires Right == nil for exactly isEmpty, isNotEmpty and exists and rejects a supplied one, so there is only ever one spelling of a unary rule and the JSON round-trips byte-identically. Every other operator still requires both operands.

How each operator compiles

expr.DisableAllBuiltins() is in force, so nothing may be assumed reachable. Each operator makes a deliberate choice:

has and hasKey need no new machinery because expr's in is element membership over an array and key membership over a map — "dept" in object.owner is already the hasKey semantics, so the operator is pure spelling. exists leans on the optional chaining var already renders, which is what makes object.owner.dept exists false rather than a runtime error when owner is missing.

The six with no native spelling are backed by functions in the curated pure set. Each is deterministic and side-effect-free, so the purity guarantee holds: they read their arguments and nothing else.

The guarded row overrides the other four. A collection operator whose collection operand is not statically known to be a collection — anything but a list literal, so in practice any operand that reads metadata — renders to the internal dispatcher $op instead, which applies the shape policy and records a note. The common object.region in ["us","eu"] keeps its native in: a list literal is an array by construction and cannot mismatch, so the decision path pays nothing for a guard it does not need.

Neither $op nor the __notes sink it reads is reachable from a rule. $ is outside the identifier grammar Validate enforces for a call name, and __notes is not one of the four exposed context roots — so the guard is compiler-only by construction, with no denylist to keep in sync.

Predicate builtins are denied

expr.DisableAllBuiltins() does not do everything its name suggests. expr's fifteen predicate builtins — all, any, none, one, filter, map, count, sum, find, findIndex, findLast, findLastIndex, groupBy, sortBy, reduce — are resolved by the parser before it consults the disabled table, so all(...) still compiles under Aperture's option set while len(...) genuinely does not. Nothing in the AST emits expr's # pointer, so none is reachable through a well-formed rule today — but a call node renders name(args…) verbatim, so Call("all", …) would compile. Validate therefore rejects those names outright with APERTURE_RULE_INVALID, and a test pins the callable set against expr's own builtin registry.

Missing fields and nested access

Metadata is host-defined and ragged: one object carries an owner, the next does not. Two behaviors follow from that, and both matter for whether a rule grants.

Nested access is nil-safe

A var may read a nested path — object.owner.dept. Aperture renders every segment after the root with optional chaining, so that path compiles to object?.owner?.dept. If owner is absent the read yields nil, the enclosing comparison goes false, and the rule simply does not select.

This matters because the un-chained form is not nil-safe: in expr-lang, object.owner.dept against an object with no owner is a runtime error (cannot fetch dept from <nil>), which would surface as APERTURE_RULE_EVAL at Check time. A rule that works against every object carrying an owner would otherwise blow up on the one object that lacks it — in production, not in dev. Optional chaining makes that uniform and deny-safe, so no rule author has to write a guard. A path through a present intermediate behaves exactly as before; ?. differs from . only when the receiver is nil.

// Selects only for objects that actually carry owner.dept == "eng".
// An object with no owner at all evaluates to false, never an error.
rules.Compare(rules.OpEq, rules.Var("object.owner.dept"), rules.Lit("eng"))

⚠️ nin over a field the object lacks grants

in and nin over a missing field do not error — but they are not symmetric in their consequences:

x not in <nil> evaluating to true is the correct logical dual, and it is expr-lang's pre-existing behavior, not something Aperture introduces. But the practical effect is a trap: a deny-list rule written with nin passes every object that is simply missing the column. A typo'd field name, a CSV without that header, or a nested path through an absent intermediate all read as nil — and the rule grants.

List-valued and nested metadata make this far easier to hit than it used to be. If a rule must not select for objects lacking the field, require the field explicitly:

rules.And(
    rules.Compare(rules.OpNe, rules.Var("object.blocklist"), rules.Lit(nil)),
    rules.Compare(rules.OpNin, rules.Var("principal.id"), rules.Var("object.blocklist")),
)

Collection operators: an absent field reads as an empty collection

Every collection operator applies the same rule — an absent array or object is not an error, it is an empty one. Which way that falls out depends on the operator's polarity, and the negative operators grant exactly the way nin does:

hasNone and subsetOf are the ones to watch: no forbidden tag and only allowed tags are both trivially satisfied by an object that carries no tags at all. Pair them with exists (or isNotEmpty) when the field must be present:

rules.And(
    rules.Unary(rules.OpIsNotEmpty, rules.Var("object.tags")),
    rules.Compare(rules.OpHasNone, rules.Var("object.tags"),
        rules.List(rules.Lit("restricted"))),
)

Wrong-shaped fields deny, and are recorded

A field of the wrong shape — has over a string, hasAll over a number, isEmpty over a bool — makes the comparison false. Every collection operator, no exceptions, including the negative ones: nin over a string is false, not true. A mismatch never matches, whatever the operator's polarity, so mistyped data can only ever deny.

expr-lang on its own is not like this. "a" in object.missing is false, but "a" in object.title is the runtime error operator "in" not defined on string — so inheriting expr's behavior would mean one mistyped field breaks every Check that touches it. Load-time validation of the value model stops mistyped data from the CSV and inline loaders, but it cannot cover a host-implemented ObjectProvider or the principal attribute bag, which bypass loaders entirely. Hence a runtime policy as well.

Note the asymmetry with the absent-field table above, and that it is deliberate:

Treating a mismatch as an empty collection would have been more uniform, but it would make nin / hasNone / subsetOf grant on mistyped data. Deny-safety wins the tiebreak.

Which shapes each operator accepts:

Evaluation notes

A silent false is how an access-control bug hides. So the mismatch is recorded and surfaced in Explain, on every decision surface:

Explain alice/read on account:acme/document:9 in account acme
  subjects: principal:alice
  grants considered (1):
     g-doc [allow account:acme/**] inclusive scope does not cover the object
  evaluation notes (1):
     g-doc [rule tagged]: object.tags: expected collection, got string
  verdict: DENY (top specificity 0)

A second kind of note covers the other invisible case: an operator that matched because the field is missing — the nin / hasNone / subsetOf / isEmpty grant described above.

     g-doc [rule tagged]: object.tags: absent; hasNone matched because the field is missing

Notes carry shape and path only — never a metadata value, because a trace crosses account boundaries the same way an error message does. They are diagnostic only and never influence a verdict, and only Explain collects them: Check and Enumerate install no collector, so the decision hot path records nothing and allocates nothing.

Library callers reach the same channel directly:

ctx, notes := rules.WithNoteCollector(ctx)
allowed, err := compiled.Eval(ctx, in)
for _, n := range notes.Notes() {
    log.Println(n) // object.tags: expected collection, got string
}

Other missing-field behavior

• Equality against a missing field is false (nil never equals a scalar).
• Ordered comparison (lt le gt ge) against a missing field is a runtime error — APERTURE_RULE_EVAL. The rule assumes a field the object does not carry; the scope resolver treats that as a non-decision, not a silent select.

Validation

Node.Validate() checks that a node and its subtree are structurally well-formed — the closed node set, the correct arities (and/or need ≥ 2 children, not exactly 1, compare the operands its operator calls for), a known comparison operator, a scalar literal, and a variable whose first path segment is one of the four roots. It returns APERTURE_RULE_INVALID for a malformed node and APERTURE_RULE_UNKNOWN_VARIABLE for a variable outside the exposed roots.

Validation is pure structure — it does not type-check and never touches the expression engine. Beyond arity it enforces, per operator:

• A literal carries a scalar (arrays and objects are rejected; use a list node for collections).
• isEmpty / isNotEmpty / exists carry no right operand; every other operator carries one.
• in nin hasAll hasAny hasNone subsetOf take a list or a var on the right.
• has / hasKey take a single element on the right — a list there is an error that points at hasAll/hasAny/hasNone.
• A call may not name one of expr's predicate builtins.

For the deep check — structure plus a full compile pass that surfaces type errors and unknown functions — call rules.ValidateAST(raw). It decodes a JSON AST and compiles it against a shared package-level validator (nil source, nil fetcher — it resolves no references and fetches no metadata), returning nil for a compilable rule and an APERTURE_RULE_* code otherwise. This is what a save/validate surface runs before persisting a rule.

Compilation and caching

Node.Expr() renders the validated AST to an expr-lang expression string. The rendering is direct and injection-free (variable paths are Go-style identifiers, string literals are quoted, integers keep their exact form via json.Number):

((object?.classification == "public") || (principal?.tier in ["gold", "platinum"]))

Every path segment after the root renders with expr-lang's optional chaining (?.); the root itself is a typed environment field and needs none. That is what makes nested reads nil-safe — see Missing fields and nested access below. The AST is unchanged: a var node still stores the plain dotted path (object.owner.dept), so the JSON form the editor and the state file share carries no ?.

Compiler.Compile(node) validates, renders, and compiles that expression to a reusable *vm.Program via expr.Compile. Every compiler fixes the same options:

• expr.Env(evalEnv{}) — the typed four-root environment, so any other top-level identifier is an unknown name at compile time.
• expr.AsBool() — a rule must evaluate to a boolean.
• expr.DisableAllBuiltins() — expr-lang's builtin library is off, so no wall-clock or random function is reachable and evaluation stays deterministic. It does not cover the predicate builtins; Validate denies those by name.
• The curated pure function set — lower, upper, contains, startsWith, endsWith, len, plus the collection-operator backings hasAll, hasAny, hasNone, subsetOf, isEmpty, isNotEmpty. A host adds its own deterministic, side-effect-free functions with rules.Function(name, fn) / Engine WithFunction; these join (and can shadow) the curated set. An unknown function is caught at compile time. Note that contains, startsWith and endsWith are reserved as infix operators by expr's grammar, so they are registered but cannot be reached through a call node; the other nine can.

A compile failure that survives validation is a type mismatch, a non-boolean result, or a call to an unregistered function — all surfaced as APERTURE_RULE_TYPE_ERROR, with the evaluator's own message preserved in context. A Compiled is immutable and safe for concurrent evaluation; it carries the canonical Source() and its Hash() (sha256 of the source).

The compiled-rule cache

Compiling an expression is the expensive step, and Check runs on a tight latency budget, so a compile happens once per canonical form. The engine keys a compiledCache by the rule's canonical hash. Two different rule references whose ASTs render to the same expression share a single compiled program.

flowchart TD
    A["rule AST (Node)"] --> V["Validate<br/>structure + roots"]
    V --> R["render → expr-lang source"]
    R --> H["hash = sha256(source)"]
    H --> C{"cache hit<br/>for hash?"}
    C -->|"hit"| P["reuse *vm.Program"]
    C -->|"miss"| K["expr.Compile → program"]
    K --> S["cache.put"]
    S --> P
    P --> E["Eval(Input) → bool"]

The cache is concurrency-safe and exposes Hits / Misses / Evictions / Entries via Engine.CacheStats(). An optional TTL (WithCacheTTL, with an injectable Clock for deterministic tests) bounds entry lifetime; TTL ≤ 0 keeps entries until explicit invalidation. When a rule's definition changes underneath a cached compilation, a host calls Engine.Invalidate(node) (drop one) or Engine.InvalidateAll() (clear).

Evaluation and the engine

Compiled.Eval(ctx, Input) runs the program against an Input — Object, Principal, and Account maps plus the Action string (a nil map reads as empty). Evaluation is pure: it reads only the input, mutates nothing (the object metadata snapshot is treated read-only), and exposes no nondeterministic function. A runtime failure or a non-boolean result is APERTURE_RULE_EVAL.

rules.Engine ties the pieces together. It is built over a RuleSource (which resolves an opaque rule reference to its Rule definition — MapSource is the in-memory default; a missing reference yields APERTURE_RULE_NOT_FOUND) and a MetadataFetcher (whose signature matches *provider.Registry.Fetch, so a provider registry wires in directly as the object-metadata source without the rules package importing provider). An optional PrincipalResolver supplies principal attributes, keyed by Attributes(ctx, kind, principal). A resolver returns the host's bag alone; returning nil is a complete answer, because the engine stamps the floor over whatever comes back. The kind is model.PrincipalKind's spelling ("user" / "machine") carried as a string, so one resolver can dispatch to a different attribute source per kind — a human directory and a service-account registry are rarely the same store. An empty kind means the caller did not have the principal's record in hand: treat it as unknown, never as a default, or a machine gets answered for out of the human directory.

An optional AccountResolver supplies the active account's attributes, keyed by AccountAttributes(ctx, account). It is the same contract one root over: the host's bag alone, nil is a complete answer, the engine stamps the floor. The method is spelled AccountAttributes rather than Attributes so that one *provider.AttributeRegistry can satisfy both seams — Go has no overloading, and the registry already holds both directories and both caches.

The floor bag, and principal.kind

principal always carries {id, kind}, whatever is wired. The floor is stamped last, so a host bag with its own id or kind key cannot shadow it — the realistic collision is innocent (a directory with an internal id column), and a floor that can be shadowed silently changes what principal.id == object.owner compares. An unknown kind is published as the empty string rather than omitted, so "unknown" is a value a rule can compare against.

kind is published because attribute providers are registered per kind, which makes a rule silently kind-dependent: a rule reading the user directory finds nothing for a machine principal. In an inclusive grant that denies safely; in an exclusive one — where being selected means being excluded — a rule that quietly stops selecting widens access. principal.kind is how an author states the dependence instead of hiding it:

principal.kind == "user" && principal.tier == "gold"

The account floor, and the wildcard

account always carries {id} — the active account, the tenancy the decision is being made in, never the account a grant happens to be stamped to. A wildcard-stamped grant is evaluated inside whatever account is active, so reading its attributes off the stamp would give one tenant's decision another tenant's plan.

The floor is {id} and deliberately not {id, kind}: there is one account slot, so a kind key would be the same constant in every bag in every deployment, and a value that can never discriminate is noise a rule author would eventually compare against. As with principal, the floor is stamped last, so a host account table with its own internal id column cannot silently change what account.id == object.account compares.

"*" — the all-accounts grant sentinel — is never an attribute fetch key. There is no account row for it (ValidateAccount refuses to store one), and the only bag that could answer "the attributes of every account" is one tenant's data served as every other's. It is nonetheless a live active account: platform-tier authority is anchored there, so authz.Gate.RequireSystemAdmin really does run a Check with it. A decision made at platform scope therefore sees the floor and nothing else — account.id is "*", which truthfully says "not scoped to a tenant", and every host-defined field is absent exactly as it is for an unwired slot. The engine short-circuits before any resolver is consulted, so a rule-backed grant guarding the system anchor stays decidable; presenting "*" to provider.AttributeRegistry directly is APERTURE_ATTRIBUTE_PROVIDER_INVALID, which makes that refusal a backstop rather than the mechanism.

Wiring a *provider.AttributeRegistry

A provider.AttributeRegistry — the host seam that maps each of the three attribute slots (user, machine, account) to a provider plus a per-slot cache — is both a PrincipalResolver and an AccountResolver as it stands, structurally, with provider importing nothing from rules:

attrs := provider.NewAttributeRegistry()
attrs.MustRegister(provider.AttributeSlotUser, userDirectory)
attrs.MustRegister(provider.AttributeSlotAccount, tenantDirectory)
eng := rules.NewEngine(source, objects,
    rules.WithPrincipalResolver(attrs),
    rules.WithAccountResolver(attrs))

The kind picks the slot: "user" resolves the user slot, "machine" the machine slot. "account" is a real slot but is not a principal kind, so it never resolves through WithPrincipalResolver — a tenant's bag must never be served as a principal's. WithAccountResolver is the only door to it, and it is keyed on the active account, not on any principal.

A deployment that has no directory to point at declares the bags in the seed file instead, under attributes:, and Document.BuildAttributeRegistry returns exactly the registry above — so aperture check decides on principal attributes with no Go written by the host.

A missing source is not a failed decision. A slot with no registered provider, and a registered provider with no record for the key, both yield the floor and no error, so a deployment with a human directory and no machine directory keeps deciding normally. Everything else — an unreachable directory, a bag the value model rejects — surfaces verbatim with its code and fixups intact and is treated as a non-decision, because an outage must not read as "this principal has no attributes".

Engine.Selected(ctx, rule, object, account, principalKind, principal, action) is the full path:

1. resolve the rule reference through the RuleSource;
2. compile-and-cache its AST;
3. fetch the object's metadata (empty when no fetcher is configured);
4. resolve the principal's attributes for its kind, and stamp the floor over them into a fresh map (the resolver's bag may be cached and shared, and is read-only, transitively);
5. resolve the active account's attributes the same way, through the same read-only contract, and stamp {id} over them into a fresh map;
6. build the Input and evaluate.

Any step's failure is an APERTURE_* coded error, and the caller treats it as a non-decision — there is no select-on-error. That signature is exactly scope.RuleEvaluator, which is how the rule-backed inclusive/exclusive scope strategies get their variant: the engine is wired as scope.Deps{Rules: engine}.

One bag per decision

principal and account are constant for the whole decision, so they are resolved once and memoized for it, exactly as the reference instant NOW is snapshotted once. The decision engine opens that scope at the same three boundaries it opens the instant's — Check, Enumerate, Explain.

It is a correctness property, not only a cost one: a bag is served through a cache with a TTL, and a TTL expiring halfway through an enumeration would judge the first candidates against one version of the principal and the last against another — a result set no single view of the principal justifies, with no error anywhere. An absence memoizes (an unwired slot, or a directory with no record, is a complete answer describing a steady state, so a 1,000-object enumeration performs one resolution); a failure does not, and that costs almost nothing, because a failure ends the decision.

The memo is keyed by the subject each bag was resolved for and re-resolves on a mismatch, so a scope travelling somewhere its author did not picture cannot serve one principal's attributes as another's. There is no API to hand a bag in: a caller-supplied principal bag would be a caller-supplied answer to "who is asking".

Under impersonation, principal.* is the effective subject

When a decision resolves under an active impersonation session, the rule is told about the effective subject — the target under become, the operator under augment — which is the same principal the resolved grant set describes. become resolves the target's id and the target's kind, so principal.* is read from the target's directory.

The invariant is that the rule and the grant set always describe the same principal. A decision resolving the target's grants while reading the operator's attributes is an authorization bug that leaves no mark in a trace.

Audit is unaffected: the request and the decision still name the real operator, and the trace still records the session. An inert or expired session elevates nothing and reads the operator's own bag. Note that principal.id therefore changes meaning under become — a rule comparing principal.id == object.owner asks "does the target own it", which is what that mode means.

Where this leads

Rules are one of two ways a scope strategy can decide object membership; the other is an explicit id-list. See scopes & scope strategies for how the inclusive and exclusive strategies consult a rule. The object.* fields a rule reads come from providers.

Scopes & scope strategies

A grant's pattern bounds which objects the grant can reach. But "reach" is not always "every match" — a grant might cover every object of a type in that scope, or only a named id-list, or everything except a few, or whatever a rule selects. That choice is the grant's scope strategy, and this chapter covers the pluggable resolvers that implement it. The code lives in the scope package.

The key separation: the pattern bounds the scope and supplies the specificity the engine's deny-overrides tiebreak consumes; the strategy decides membership within that bound. A resolver never computes specificity — that stays the pattern's job in the engine, so the resolution semantics from literal-only grants are untouched.

The four strategies

literal is owned natively by the decision engine and is not in the registry. The scope package ships the other three plus a registry for host-defined strategies. Membership always composes with the pattern: a listed object that falls outside the grant pattern is not covered.

The scope reference and Spec

A permission carries its strategy as an opaque string reference; the engine parses it into a typed scope.Spec with ParseSpec. The grammar is a strategy key optionally followed by ;-separated name=value params. Identity strings never contain ;, =, or ,, so those separators never collide with id-list values:

implicit
inclusive;ids=account:acme/document:42,account:acme/document:99
exclusive;ids=account:acme/document:7
inclusive;rule=quarantine-rule

ParseSpec yields Spec{Strategy, IDs, Rule}. An empty reference (or the explicit literal) parses to the literal strategy, so grants that carry no strategy keep their literal behaviour. Parsing validates structure only — known params (ids, rule), non-empty values, no duplicates — and does not consult the registry, so a custom strategy key parses cleanly and is resolved by whatever the host registered. Anything malformed is APERTURE_SCOPE_INVALID.

The resolver contract

Each strategy is a ScopeResolver, constructed per evaluation from a GrantContext (the already-parsed pattern, the permission's object type, the parsed Spec, and the account/principal/action context) plus runtime Deps:

type ScopeResolver interface {
    // hot path — "is this concrete object a member?" — never enumerates.
    Contains(ctx context.Context, object identity.Identity) (bool, error)
    // bounded enumeration for Enumerate-style callers.
    Members(ctx context.Context, pattern identity.Pattern) ([]identity.Identity, error)
}

Contains answers the Check hot-path question and never needs to list objects. Members performs a bounded enumeration for Enumerate-style callers, capped by the Deps.MaxMembers the resolver was constructed with — the engine's configured enumeration bound, or DefaultMaxMembers (1000) when a wiring configures none. Resolver construction is cheap — small value structs, id-list membership by linear scan, no per-evaluation map allocation — and holds no cache.

Two seam dependencies

Strategies that need to enumerate "all objects of a type", or evaluate a rule, reach two seams through scope.Deps. Both default to an inert implementation so a zero Deps is usable:

RuleEvaluator.Selected(ctx, rule, object, account, principalKind, principal, action) is exactly rules.Engine.Selected — that shared signature is how the rule-backed path is wired without scope importing rules.

account and principalKind come straight off the GrantContext. They are there because a rule-backed strategy asks about attributes, and an attribute only means something once you know whose it is and which account it is read in. They are parameters rather than context values on purpose: a missing ctx value degrades silently to an empty account — a quiet allow-or-deny nobody wrote — where a parameter is a compile-time obligation on every caller. principalKind is model.PrincipalKind's spelling ("user" / "machine") carried as a string, since scope imports no model; empty means unknown, never a default.

How each strategy decides Contains

flowchart TD
    O["object"] --> M{"pattern matches?"}
    M -->|no| N["not a member"]
    M -->|yes| S{"strategy"}
    S -->|implicit| T1{"terminal type ==<br/>object type?"}
    S -->|inclusive| L1{"in id-list?"}
    S -->|exclusive| T2{"terminal type match?"}
    T1 -->|yes| Y["member"]
    T1 -->|no| N
    L1 -->|yes| Y
    L1 -->|"no, rule set"| RS{"rule Selected?"}
    L1 -->|"no, no rule"| N
    RS -->|yes| Y
    RS -->|no| N
    T2 -->|no| N
    T2 -->|"yes, in minus-list"| N
    T2 -->|"yes, rule excludes"| N
    T2 -->|"yes, otherwise"| Y

implicit — membership is the conjunction of the pattern match and a terminal-type check (the object's last segment is of the permission's object type). It takes no configuration; supplying an ids list or a rule is a misconfiguration and is rejected so it cannot silently mask intent. Members must list the type, so it depends on the ObjectLister.

inclusive — an opt-in. It must declare an id-list or a rule; neither is a misconfiguration. Contains first requires the pattern match, then: the object's canonical id is in the list (exact string equality), or — only when a rule is declared — the RuleEvaluator selects it. A pure list-backed grant never touches the rule dependency. Members returns the union of the two halves, with both patterns applied to each and no identity repeated — it has to, or Check and Enumerate would disagree about the same grant. The list half needs no lister (the members are the listed ids within both patterns). The rule half is list-then-filter, exactly as exclusive does it: list the type through the ObjectLister and keep what Contains selects. There is no reverse index and no attempt to invert the rule — a rule is an arbitrary expression over object metadata and is not invertible in general. A rule-backed grant enumerated with no ObjectLister therefore reports APERTURE_SCOPE_LISTER_UNCONFIGURED rather than returning nothing, because an empty member list is a legitimate answer; with no RuleEvaluator it reports APERTURE_SCOPE_RULE_UNCONFIGURED.

exclusive — an opt-out. It requires a minus id-list or a rule (declaring neither would make it identical to implicit). Contains requires the pattern match and the terminal-type check, then is a member unless the object is in the minus-list or the rule excludes it. Members enumerates all-of-type in scope via the ObjectLister and drops the excluded ones through Contains.

The registry

scope.Registry maps strategy keys to Factory functions. DefaultRegistry() preloads the three built-ins (implicit, inclusive, exclusive); literal stays native to the engine and is intentionally absent. A host adds its own with Register / MustRegister (rejecting an empty key, a nil factory, or a duplicate with APERTURE_SCOPE_INVALID).

Registry.Resolve(grantContext, deps) builds the resolver for the spec's strategy, validating the spec via the strategy's factory. An unregistered strategy yields APERTURE_SCOPE_UNKNOWN_STRATEGY; a spec the strategy rejects yields APERTURE_SCOPE_INVALID.

reg := scope.DefaultRegistry()

spec, _ := scope.ParseSpec("exclusive;ids=account:acme/document:7")
gc := scope.GrantContext{
    Pattern:       identity.MustParsePattern("account:acme/document:*"),
    ObjectType:    "document",
    Spec:          spec,
    Account:       "acme",
    PrincipalKind: "user",
    Principal:     "user:alice",
    Action:        "read",
}
resolver, _ := reg.Resolve(gc, scope.Deps{Lister: providerReg /* , Rules: rulesEngine */})
ok, _ := resolver.Contains(ctx, identity.MustParse("account:acme/document:42"))
// true: matches the pattern, is a document, and is not in the minus-list.

Where this leads

The ObjectLister that every non-list-backed enumeration depends on is the provider Registry; the RuleEvaluator the rule-backed paths consult is the rules Engine. For how the decision engine assembles grants, resolvers, and specificity into a verdict, see the library Decision API.

Providers

A rule reads object.classification; an exclusive scope enumerates "every document in this account." Both need domain data Aperture does not own. That data belongs to the host application — its database, its API, its source of truth — and Aperture reaches it through providers. A host implements one ObjectProvider per object-type; a Registry binds each type to its provider plus a per-type cache and is the seam every consumer resolves through. The code lives in the provider package; csvprovider (a file) and sqlprovider (a database) are the two concrete worked examples.

There are two provider seams, and this page covers both. An ObjectProvider describes the thing being acted on; an AttributeProvider describes the party asking — the principal and the account a rule reads principal.* and account.* out of. They share one value model and one cache design, and differ in everything that follows from an attribute key being a bare opaque id rather than a segmented identity.

A load-bearing rule: Aperture never persists provider data as a source of truth. The host owns it; Aperture only ever caches a copy. Cached metadata is handed back by reference and treated read-only — the cache never copies a map on read (allocation matters on the Check hot path), so a provider must return a fresh map per object and callers must never write to a returned map. Because a value may nest, that contract is transitive; see the read-only contract below.

ObjectProvider: the host seam

A host implements this once per object-type. It is a pull source — Aperture asks, the host answers — and must be safe for concurrent use:

type ObjectProvider interface {
    Fetch(ctx context.Context, id identity.Identity) (Metadata, error)
    List(ctx context.Context) ([]Object, error)
    Query(ctx context.Context, filter Filter) ([]Object, error)
}

• Fetch returns one object's metadata; a missing object yields an APERTURE_NOT_FOUND coded error, so the Registry can tell "absent" from an operational failure.
• List is the unfiltered enumeration of the type.
• Query returns the objects matching a Filter — an optional Pattern (bounds results to matching identities), a set of Fields predicates, and a Limit. The zero Filter selects everything (equivalent to List).

Metadata is map[string]any — an alias, not a named type — so the rules engine reads each field straight into its expression environment with no conversion layer. An Object pairs an identity with its metadata; the identity's terminal segment type is the object-type the provider is registered under.

The Filter.Fields contract

A provider evaluates Fields, but it does not get to define it. Query is how scope enumeration bounds itself, so two providers disagreeing about what Fields{"tags": "premium"} selects is two different answers to the same authorization question. The rule is stated once on provider.Filter and implemented once in provider.MatchFields; an implementation either calls that helper or reproduces it exactly (by pushing the predicate into SQL, say).

Three properties are worth stating outright, because each one closes a failure mode:

• A collection field matches by membership. Equality against a whole array is never what a caller filtering on a tag list means, and the predicate this replaced compared against the array's literal rendering ([premium launch]), so a tag filter could not match anything useful.
• Comparison is typed, not stringly. Numbers compare across Go numeric types by value (int(5), int64(5), float64(5) are one value), but a number never equals "5" and a string equals only a string. These are the rules engine's own comparison semantics, so Enumerate cannot select an object that a Check over the same value then denies. provider.ValuesEqual is the exported leaf comparison, and csvprovider's membership_equivalence_test.go runs it against a real compiled rule to keep the two from drifting.
• Every predicate must hold (the map is an AND), and an object field is compared by equality, never by key membership — so a scalar want against one is a plain false, not a panic and not an accidental rendering match.

The contract reaches past Query. Enumerate's own metadata filter (engine.EnumerateRequest.Fields, and its EnumerateQuery.Fields / --field / --fields-json / Twirp fields / MCP Fields spellings) is evaluated by this same provider.MatchFields, so an enumeration filtered by the engine and one filtered inside a provider select the same objects. There the filter runs on candidates that already survived deny-overrides, and it runs before the enumeration's Limit — see the decision API.

Because provider is a strict leaf (identity + errors + stdlib), ValuesEqual reimplements the evaluator's equality rather than importing expr-lang. It agrees with it on every value the metadata value model admits; the two documented divergences — time.Time/time.Duration, and a uint64 above math.MaxInt64 — are both outside that model.

The text-match contract

Fields answers "which objects hold exactly this value?". The properties that make it trustworthy — exact, typed, coercion-free — are precisely what stop it answering the other question a caller has: "which objects are people naming when they type nike?", where Nike, nike, Nike, Inc. and a typo are one intent and none of them is an exact value.

provider.MatchText(md, query, fields) is that second question, and it lives beside MatchFields for the same reason: a host that can push a search down into its own storage — a SQL LIKE, a trigram index, an external search engine — must be able to rank the way Aperture would, or the ids it proposes and the ids Aperture would have proposed are two different answers to one question. provider.ScoreText and provider.NormalizeText are exported for exactly that.

It reads the same value model, and only the string material in it:

Both sides are normalised first — lower case, every non-alphanumeric rune a separator, runs collapsed — which is what makes "Nike, Inc." and "nike inc" the same string. Each query token then scores its best match against any candidate token in descending tiers (exact, prefix, substring, approximate), the base score is their mean, and that is scaled by how much of the candidate the query accounts for, so "nike" ranks Nike Inc above Nike Air Max Collection. Approximate matching uses Damerau-Levenshtein distance, so a transposition counts as the one slip it is; tokens shorter than four runes must be spelled exactly or be a prefix, because one edit in three characters would let IBM answer for IBN.

Nothing in Aperture ever decides on a score. The surface that consumes this — Search — applies it only to candidates the engine has already decided the subject may act on. See object search.

The metadata value model

Metadata is an alias, so the type constrains nothing. The shape of a field value is constrained anyway, and deliberately so: metadata goes into the expression evaluator untranslated, which means a wrong shape is not a false decision — it is a runtime evaluation error on the Check hot path (operator "in" not defined on string). Catching that at load is the whole point of the model.

A field value is one of: