Concepts and glossary

Sill is agent governance infrastructure: the layer between an arriving AI agent and a merchant’s commerce stack. Its job is to answer three questions about every agent interaction — who is calling (identity), what they are trying to do (intent), and what record remains (proof). This page is the working glossary for the rest of the docs: every entity below maps to a concrete object in Sill’s data model, with a link to the deeper page that covers it.

The three-question model

Sill’s entire surface area is organized around three questions. Each one has a signed object:

Identity — who is the visitor? Established by a signed agent card per site, and (in Transactional mode) by an agent registry entry that pins a registered ed25519 public key.
Intent — what are they trying to do? Expressed in Transactional mode as a signed mandate: a bounded authorization request the agent signs.
Proof — what record remains? Written to an append-only, signed, Merkle-chained audit envelope. Every signed surface Sill publishes can be verified independently against the public JWKS.

flowchart LR
  A[Agent arrives] -->|Identity| B[Agent card<br/>signed]
  A -->|Intent| C[Mandate<br/>signed by agent]
  C --> D[Policy engine<br/>rules evaluated]
  D -->|approve / escalate / reject| E[Audit record<br/>signed, Merkle-chained]
  B --> E

Core entities

Each entity below is the wire shape served by Sill’s APIs and persisted in its data model. Identifier conventions are fixed: ULIDs for account_id and site_id; prefixed strings for domain objects (mnd_… for mandate ids, agent_… for agent ids); snake_case field names; ISO-8601 UTC timestamps.

Account

The top-level merchant tenant. Carries a billing customer reference and a regional placement (Phase 1 is US-East only). Status is one of active, past_due, suspended, or closed. An Account owns one or more Sites and one or more Users.

Site

A registered domain. The unit of installation, and the unit of policy: each Site has exactly one active Policy version at any time. A Site carries a site_key (the public credential the embed script and the per-site signed endpoints use) and a site_key_hash (the URL-bound public identifier — a one-way SHA-256 of the raw key, also published on the storefront DOM).

Site lifecycle is a four-state machine driven by domain proofs:

pending_proof — site exists, no proof recorded yet.
discovery_active — first valid HTTP-challenge proof recorded; audit writes enabled.
transactional_active — additionally has an OAuth domain-match proof; mandate dispatch enabled.
suspended — ops action only.

A capability tier (T0 through T3, plus a legacy_T0 migration state) records which proofs are on file and which surfaces the Site is allowed to publish.

Skill

A capability the merchant exposes to agents. Sill ships seven default skills:

browse_catalog — search and browse products.
check_availability — real-time stock.
place_order — requires auth; in Transactional mode, requires a signed mandate.
order_status — look up an order.
track_shipment — track an order’s shipment.
request_refund — requires auth; in Transactional mode, requires a signed mandate.
recommend — product recommendations.

Only skills with a wired backing (a connected integration that can execute them) appear in the agent card and the MCP server. Unwired skills fall back to discovery / observe-only.

Agent

A non-human caller. Registered in Sill’s identity registry, identified by a stable agent_id (agent_…), and (when Phase 2 signed surfaces apply) by an array of ed25519 public_keys[] with rotation overlap (one active: true key plus zero-or-more retained active: false keys for the rotation grace window).

Phase 1 seeds the registry with the three vendor families — Anthropic, OpenAI, Google — and a long tail of other crawlers and agents matched via user_agent_pattern. A revoked_at timestamp on the agent record signals revocation: identification still records the visit (so the audit log still shows “saw a known but revoked agent”), but Phase 2 verifiers must not trust any signed claim from a revoked agent.

See Identifying agents.

Agent card

The per-site signed JSON document Sill publishes at https://edge.sill.so/v1/agent-card/{site_key}.json. A2A-compatible (protocol_version: "a2a/1.2"), with an A2A-conformant skills[] array, transport-flag capabilities, and an mcp_endpoint pointer. The card is signed with an ed25519 envelope using the foyer/edge/card-signing-v1 key, independently verifiable against the public JWKS.

The advertised skills[] are backing-filtered (only wired skills appear), so the card is a discovery surface, not an overclaim. See Agent card and Verify a signature.

Mandate

A signed authorization request — the central object in Transactional mode. The agent signs canonicalize(signed) (RFC 8785 JCS) with its registered ed25519 key, prefixed by the 'sill-mandate-v1\x00' domain-separation tag. The wire shape splits the signed body (which the signature binds) from an envelope (which carries the signature, key id, and algorithm — themselves not signed).

The signed body carries: mandate_id, site_id, agent_id, issued_at, expires_at, principal, intent, protocol_context, an optional delegation_chain, a 16-byte random nonce, and a replay_window_seconds integer. Every field enters the signing input — intermediaries cannot mutate any of them without invalidating the signature. See Signed mandates.

Policy

A versioned, ordered set of Rules. Exactly one Policy is active per Site at any time. When the merchant publishes a new policy version, the previous version becomes inactive but stays on file (audit records pin the policy_version they were evaluated against, so historical replay is exact).

See Guardrails and Policy engine.

Rule

A single guardrail. Each Rule has a stable type slug (r01 … r29, r30, r_custom, plus the c01 … c04 catalog-eligibility family), a category (one of agent_identity, rate_limit, spend, scope, dark_pattern, prompt_injection, custom, catalog), strongly-typed params, an action_on_match of allow, reject, or escalate, an order, and an enabled flag. The seven categories map to the OWASP LLM Top 10 and OWASP Top 10 for Agentic Applications classes Sill mitigates.

A few canonical rule types, to make the shape concrete:

r01 — allowlisted agents only. Params: allowlisted_agent_ids: AgentId[].
r05 — per-transaction spend cap, per-currency. Params: caps: Record<currency, amount>, on_unlisted_currency: 'reject' | 'allow'.
r07 — human-in-the-loop on destructive actions, per-currency.
r23 — mandate validity-window cap (max_validity_seconds).
r28 — emergency kill switch (predicate always fails when enabled).
r_custom — merchant-authored DSL expression.

The evaluator runs Rules in order. A failed predicate fires the rule’s action_on_match; a passed predicate moves on. The first non-allow outcome wins.

Audit record

The signed output of a mandate evaluation, or of a discovery interaction. Append-only and Merkle-chained: every record carries a prev_record_hash and a merkle_root, and the envelope is signed with the same ed25519 family that signs agent cards and the ARD catalog.

Decision values:

observed — Discovery mode; the embed script identified an agent visit, no mandate was evaluated (mandate_id is absent).
approved — Transactional; the policy passed and the rail authorized.
rejected — Transactional; a rule fired reject.
escalated_approved / escalated_rejected — Transactional; a rule fired escalate, then a reviewer resolved the queued escalation.
verification_rejected — the edge verifier rejected the signature shape or expiry; the record is sanitized (only format-validated identity fields, never attacker-controlled intent / principal / signature bytes).
rejected_post_verify — the edge approved but the origin’s idempotent insert collided with a prior record for the same (site_id, mandate_id).

Records are stored under a retention class (short_term_30d, standard_3y, long_term_7y) and can be exported as a signed audit bundle. See Audit envelope.

User and roles

A human dashboard user, scoped to one Account. (Supersedes the earlier Operator entity, per the May-2026 schema evolution.)

Roles:

owner — full control, billing, can delete the Account.
admin — full configuration, can manage Users.
reviewer — can resolve human-in-the-loop escalations and read all audit data.
viewer — read-only.

Lifecycle:

invited — invitation sent, not yet accepted.
active — accepted and signed in.
suspended — temporarily blocked by an admin.
deactivated — permanently removed.

Sign-in is magic link only in Phase 1. SSO is Phase 4. See Users and roles.

Principal

The party an agent acts for. Carried on the mandate’s signed.principal block. Type is one of:

human — a specific person; the merchant typically supplies a stable user_ref (an opaque internal id or email — hashed into a non-PII user_key before any rule sees it) and a session_id.
organization — an org / B2B principal.
none — no principal context (autonomous agent action).

The verification field records how that principal was established: delegated (the agent received a signed AP2 IntentMandate from the user), direct, or none. Per-user policy rules (for example r06 — daily spend cap per user, or r17 — per-customer data scoping) key on the derived user key, not on the raw identifier.

Identifier conventions

Kind	Shape	Examples
`account_id`, `site_id`, `user_id`, `session_id`	ULID	`01KSTV3FCR3HQ8GSJ62G9WA4TE`
`mandate_id`	`mnd_` + ULID-shaped tail	`mnd_01EXAMPLE00000000000000000`
`agent_id`	`agent_` + slug	`agent_anthropic_claude`
`rule_id`	closed slug	`r01`, `r05`, `r_custom`
Timestamps	ISO-8601 UTC	`2026-06-22T14:03:21Z`
Field naming	snake_case	`agent_id`, `signed_envelope`

How the pieces compose

A concrete example walks through the model end-to-end. An AI agent navigates to a merchant site that runs Sill’s embed script:

sequenceDiagram
  autonumber
  participant Agent as AI agent
  participant Edge as Sill edge
  participant Origin as Sill origin
  participant Rail as Stripe rail
  Agent->>Edge: GET /v1/agent-card/{site_key}.json
  Edge-->>Agent: Signed agent card (Identity)
  Agent->>Edge: POST mandate (signed by agent)
  Edge->>Edge: Verify signature, run Policy
  alt approved
    Edge->>Rail: Authorize charge (Transactional only)
    Rail-->>Edge: Charge id
    Edge->>Origin: Enqueue signed audit record
  else rejected / escalated
    Edge->>Origin: Enqueue signed audit record
  end
  Origin-->>Origin: Merkle-chain into audit envelope (Proof)

In Discovery mode the same flow runs without the mandate step: the embed script identifies the agent against the registry, writes an observed audit record, and exits. There is no policy evaluation, no payment authorization, no signed mandate — just identity and a signed proof of the visit.

Common questions

Is a Site the same as a domain? One Site corresponds to one verified apex domain. A merchant with multiple storefronts on separate domains adds them as separate Sites under the same Account, each with its own site_key, policy, and audit chain.

Can one Account have policies that differ per Site? Yes. Policy versions are scoped to a Site. Two Sites under the same Account can run completely different rule sets.

Do agents need an account with Sill? No. Identification is one-way: agents are matched against the registry by user_agent_pattern (and, in Phase 2, by the registered public key the mandate signature resolves to). The registry seed ships in the edge worker; merchants do not configure it directly.

Where do mandate signatures live, exactly? The signed mandate is { signed, envelope }. signed is the bytes the agent signs (every field enters JCS canonicalization). envelope carries the ed25519 signature, the agent’s declared key_id, and the locked algorithm: 'ed25519'. The verifier resolves (agent_id, key_id) against the registry.

What ties an audit record back to a mandate? The mandate_id field on the audit record. The record also pins the exact policy_version it was evaluated against, the per-rule outcomes (rules_evaluated[]), the agent identification result, and the verified intent_summary. The whole record is signed and chained into the Merkle log.

Where do I verify a Sill signature? Fetch the public JWKS at https://edge.sill.so/.well-known/jwks.json and follow the recipe in Verify a signature. No Sill SDK is required — RFC 8037 EdDSA plus an off-the-shelf ed25519 verifier is enough.