diff --git a/docs/reference/specifications/PSP-1 - Capability Model and Grammar.mdx b/docs/reference/specifications/PSP-1 - Capability Model and Grammar.mdx
new file mode 100644
index 0000000..dd97de3
--- /dev/null
+++ b/docs/reference/specifications/PSP-1 - Capability Model and Grammar.mdx
@@ -0,0 +1,559 @@
+# PSP-1 - Capability Model and Grammar
+
+
+ Metadata
+
+ - Status:
+ - Draft
+ - Edition:
+ - 2025-09-04
+ - Extends:
+ - -
+ - Updates:
+ - -
+ - Obsoletes:
+ - -
+ - Depends on:
+ - PSP-2, PSP-3
+
+
+
+## Abstract
+
+PSP-1 defines the portable, verifiable capability model used by Polykey to express delegated authority. It specifies the structure and semantics of identity-bound authority Grants and Presentations which are ephemeral proofs of capability. In this model, capabilities are canonical, monotone programs evaluated by Capability Enforcement Points (CEPs). Delegation is achieved by syntactic attenuation along a delegation chain: derived Grants may only add checks or shrink finite action/resource scopes and never broaden authority. Programs are normalized into a Program Canonical Form (PCF) and deterministically encoded to derive stable content identifiers, enabling portable verification and anchored delegation chains. PSP-1 specifies the capability program model, multi-scope declarations (finite action/resource sets), delegation/attenuation semantics, revocation checks, and CEP verification behavior. Transport/envelope bindings and sigchain framing are defined in PSP-3; receipt formats and proof traces are defined in PSP-2; enforcement placement/modes are defined in the CEP/BA specification; acceptance and governance live in TAP/RAM and related profiles.
+
+## Terminology
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
+
+- **Principal (P):** Originator of authority; issues a Grant to a Subject.
+- **Subject (S):** Holder of a Grant that exercises the capability by creating a Presentation.
+- **Resource (R):** Target of the action; may host a native CEP (CEP(R)).
+- **Capability Enforcement Point (CEP):** An agent at P/S/R that verifies Presentations and enforces capabilities.
+- **Grant (G):** A durable, signed statement on a sigchain that carries a capability program; issued by P to S.
+- **Presentation (Π):** An ephemeral proof-of-possession (PoP) token created by S that references a Grant by its canonical digest (grant_ref, per PSP-3). It is bound to a live channel and runtime context and is NOT stored on sigchains.
+- **Channel binding:** A cryptographic binding of a Presentation to the live transport/session per a declared binding profile (e.g., TLS exporter, DPoP). It proves the Presentation was minted for, and presented on, the specific session being enforced.
+- **Verification (Σ):** The CEP's verification event; it validates PoP and channel binding, verifies custody and syntactic attenuation along any delegation chain (and anchoring where required), and evaluates the capability program under bounded resources. On success, enforcement MAY proceed and, in derive-style enforcement variants, MAY result in creation of a session-scoped authority.
+- **Lease:** The upstream authority relationship to a non-native Source of Authority (SoA). If a Grant touches a non-native SoA, the enforcing CEP MUST verify Lease freshness per TAP policy.
+- **Program (CPL/0):** A monotone policy evaluated by CEPs, composed of Checks (OR of Queries), Queries (AND of Literals), and Literals (Atoms or pure, bounded Builtins) over typed Terms (Sym/Str/Int/Bytes/Bool/Var).
+- **Declarations:** Finite sets/relations used by programs: PairSet of (action, resource), ActionSet, and ResourceSet.
+- **Program Canonical Form (PCF):** The normalized, deterministically encoded representation of a Program used for hashing/signing.
+- **Attenuation:** Delegation that only adds checks/tightens literals and shrinks declared sets; never broadens authority.
+- **Builtins Registry:** Versioned, content-addressed set of pure, bounded builtins (time/ttl, channel lattice, resource subset, etc.).
+- **Anchoring:** A TAP-approved method that binds the root issuer of a delegation chain to a resource domain.
+- **Access PoAR:** The Proof-of-Action receipt written by the enforcing CEP (defined in PSP-2).
+
+## Overview and Goals
+
+PSP-1 provides the core capability model for Polykey: the program model and verification semantics that allow independent parties to mint, hold, present, and verify capabilities across boundaries.
+
+What PSP-1 defines:
+
+- Capability Program (CPL/0): a monotone program with finite Declarations (PairSet/ActionSet/ResourceSet), normalized into a Program Canonical Form (PCF) for stable digests.
+- Grants and Presentations: Grants are signed, durable sigchain statements that carry the Program; Presentations are ephemeral PoP tokens bound to a live channel/context that reference a Grant.
+- Delegation & attenuation: syntactic attenuation along a delegation chain (add checks, shrink finite sets; never broaden authority).
+- CEP verification (high level): validate PoP and channel binding, verify custody/attenuation (and anchoring where required), then evaluate the Program under bounded resources.
+
+Design goals:
+
+- Portable: Grants and Presentations are verifiable across organizational and network boundaries.
+- Minimal: monotone fragment; finite, subset-checkable declarations; versioned content-addressed registries.
+- Attenuable: Derived Grants MUST be subsets of their parents; attenuation is verifiable at enforcement.
+- Secure by default: Holder-of-key (PoP) + channel binding; short TTLs for Presentations; pure, bounded builtins only.
+- Receipt-ready: CEPs can emit Access PoARs with program projection/proof traces (see PSP-2).
+
+Non-goals (out of scope for PSP-01):
+
+- Enforcement placement/modes: CEP/BA placements (P/S/R) and mediate/derive/reveal semantics are specified in the CEP/BA spec.
+- Lease lifecycle/rotation: Lease issuance and rotation policies are defined elsewhere; PSP-1 only requires Lease freshness to be verified when Grants touch non-native SoA (enforced by CEP per TAP).
+- Receipt schemas: All receipt formats (PoAR/VOR/View) are specified in PSP-2.
+- Transport/envelope and sigchain framing (JOSE/COSE/DSSE, canonical bytes): specified in PSP-3.
+- Channel-binding mechanisms: Concrete binding profiles (e.g., TLS exporter, DPoP) are profiled elsewhere; PSP-1 only requires a verified binding.
+- Global time/ordering: PSP-01 does not require a global clock or total order. Acceptance (TAP) specifies clock sources and tolerances.
+- Secret issuance/derivation/aggregation crypto and interactive evaluation flows.
+- No ZK/succinct delegation proofs in core; no signature aggregation (e.g., BLS).
+- No recursion or negation-as-failure in the Program (monotone only).
+- No geo polygons beyond finite region sets; no policy graph solvers.
+- No regex/unbounded wildcards in resource comparators (prefix/finite models only).
+- No network I/O in builtins; all builtins MUST be pure, deterministic, and bounded.
+
+## Registries
+
+This section establishes the minimal, versioned dependencies that capability evaluation relies on, and what a Grant MUST pin so verifiers reach the same decision everywhere. PSP-4 defines the registry entries. PSP-3 defines the concrete fields and canonical bytes.
+
+### Scope
+
+Capability evaluation depends on small, versioned rulebooks ("registries"):
+
+- Verbs: namespaced action strings and documentation.
+- Resource Schemes: normalization and subset comparators per scheme.
+- Channel Lattices: partial order used by channel_geq.
+- Builtins: the available operations (opcodes), their types, and tightening rules.
+
+A registry ID is a content-addressed identifier (e.g., a CID/multihash) for a specific, immutable entry or snapshot in one of these registries.
+
+### Definitions
+
+Channel lattice and channel_lattice_id
+
+- A channel lattice defines a partial order over channel profiles (e.g., mtls:v1 ≥ tls_exporter:v1 ≥ dpop:v1 ≥ bearer:v1). It is the rulebook used by the builtin channel_geq(channel, floor).
+- channel_lattice_id is the content-addressed ID of the specific lattice used to interpret "≥". It is required whenever a Program uses channel_geq.
+
+Builtins and builtins_id
+
+- The builtins registry defines each opcode's semantics, types, and attenuation tightening rules (e.g., within_time, ttl_ok, in_pairset, channel_geq, ctx_eq, presenter_is).
+- builtins_id is the content-addressed ID of the exact builtin set the Program uses.
+
+Resource schemes:
+
+- Each resource scheme (vault:, net:, k8s:, …) has a registry entry that defines normalization and a decidable subset comparator. In PSP-1, comparators are selected by scheme name; no per-scheme ID is pinned.
+
+Verbs
+
+- Verbs are namespaced strings (e.g., secret:read). Evaluation treats them as strings for equality. TAP may govern allowlists; PSP-1 does not require pinning a verbs set.
+
+### Pinning in Grants
+
+A Grant MUST include references to the exact rulebooks its Program depends on:
+
+- lang_version: Evaluator version string for CPL/0 (e.g., "cpl/0@1").
+- builtins_id: ID of the Builtins set used by the Program.
+- channel_lattice_id: REQUIRED if the Program contains channel_geq; otherwise OPTIONAL.
+- Resource Schemes: selected by the scheme name present in each resource string; no extra per-scheme ID is required in v0.1.
+- Verbs: treated as strings for equality; pinning a verbs set is OPTIONAL and governed by TAP, not required by PSP-1.
+
+PSP-3 specifies how these IDs appear on the wire and how they are included in the signed object.
+
+### Delegation Compatibility
+
+In a delegation chain, a child Grant MUST use the same rulebooks as its parent:
+
+- lang_version must equal the parent's value.
+- builtins_id must equal the parent's value.
+- channel_lattice_id, when present in either parent or child, must be equal.
+- For each resource scheme name appearing in resources, the same comparator semantics must apply consistently across the chain. If a scheme is unknown or its comparator cannot be applied, verification MUST fail.
+
+These constraints ensure attenuation is checked and evaluated under identical semantics across all hops.
+
+### Fail-Closed Requirements
+
+A CEP MUST deny if any of the following holds:
+
+- builtins_id is missing, unknown, or cannot be loaded from the Builtins registry.
+- The Program uses channel_geq but channel_lattice_id is missing or unknown.
+- Any resource string's scheme has no recognized comparator in the Scheme registry.
+- The Program references a builtin not present in the pinned builtins_id.
+- In a delegation chain, any of the compatibility requirements above are violated.
+- Any required registry entry cannot be loaded or applied at verification time.
+
+### Rationale
+
+Pinning registry IDs makes verification deterministic and auditable across time and organizations. It prevents semantic drift (e.g., boundary changes in within_time, reordered channel strengths) from altering the meaning of an already-issued Grant.
+
+## Data Model
+
+This section specifies the capability language used by Grants and Presentations. It defines the CPL/0 abstract syntax and semantics, the CEP-provided evaluation environment, and the declaration objects (PairSet). It does not define envelope fields, sigchain framing, or canonical bytes. Those appear in PSP-3 (bindings and digests). Registry contents (verbs, schemes, lattices, builtins) appear in PSP-4.
+
+### Frame & Canonical Bytes
+
+- PSP-1 uses neutral, semantic objects (Program, Declarations) and does not specify field name representations. Envelope mappings (issuer, subject, created_at, not_before, not_after, statement_id, prev, signatures) to JOSE/COSE are defined in PSP-3.
+- Identity of the Program is derived from canonical bytes defined in PSP-3:
+ - program_bytes = ENCODE(PCF(Program))
+ - program_id = multihash(program_bytes)
+- Normative: Implementations MUST construct PCF(Program) before deriving identity. Any mismatch between a carried program_id and program_bytes MUST cause verification failure.
+
+### Capability Program
+
+This subsection defines the capability language evaluated by CEPs. It specifies abstract structure and semantics only. Builtins, comparators, and lattices are referenced via registries (see Registries and PSP-4).
+
+#### Language Model
+
+- Structure
+ - Program = all(Check*)
+ - Check = any(Query+)
+ - Query = and(Literal+)
+ - A Program succeeds if and only if every Check succeeds.
+ - A Check succeeds if and only if at least one of its Queries succeeds.
+ - A Query succeeds if and only if all of its Literals succeed.
+- Literals and Terms
+ - Uses builtin literals only: Builtin(op_id, [arg…]).
+ - Terms are ground: Str | Int | Bool | Bytes. No variables. No user-defined atoms.
+ - Int is arbitrary-precision integer. Floats are not permitted.
+- Monotonicity and purity (normative)
+ - Programs MUST be monotone. Adding Checks or adding Literals can only narrow authority.
+ - Builtins MUST be pure, deterministic, and resource-bounded (time/memory). No network I/O or ambient mutable state.
+
+#### Evaluation Environment
+
+At verification, the CEP supplies an environment of facts. Builtins may reference these facts by name.
+
+- Required environment facts (normative)
+ - action: Str — verb being attempted (e.g., "secret:read").
+ - resource: Str — target resource identifier (scheme-normalized).
+ - now: Int — NumericDate (Unix seconds) at enforcement.
+ - iat: Int — NumericDate (Unix seconds) carried by the Presentation.
+ - presenter: Str — DID of the presenting Subject.
+ - enforcer: Str — DID/identifier of the enforcing CEP (audience).
+ - channel: Str — profile representing the live session's binding.
+ - ctx: `Map` - runtime context (e.g., `{"ns":"prod","pod":"runner-42"}`).
+- Optional environment facts (TAP‑gated)
+ - lease_status - opaque assurance/freshness input for lease checks (no I/O in the builtin).
+- Missing facts (normative)
+ - If a builtin present in the Program requires an environment fact that is missing, evaluation MUST fail closed.
+
+#### Bultins and registries
+
+- Each builtin op_id, its type signature, and its tightening rule are defined in the Builtins registry (PSP-4). The exact set in use is pinned by builtins_id in the Grant.
+- Channel comparisons (e.g., channel_geq) consult a pinned channel_lattice_id when present.
+- Resource subset checks in declaration-aware builtins (e.g., in_pairset) consult the scheme comparator selected by the resource's scheme name.
+- If a builtin, lattice, or comparator required by the Program is unknown or unavailable, evaluation MUST fail closed.
+
+#### Typing, totality and failure modes
+
+- Builtins MUST validate argument types at evaluation time. Ill-typed invocations MUST fail closed.
+- Strings MUST be considered in NFC for comparison purposes; Bytes are compared as exact octets.
+- Evaluation MUST be performed under CEP-enforced limits (CPU/steps/memory). Exceeding limits MUST result in deny.
+
+#### Relationship with Biscuit Datalog (Informative)
+
+- CPL/0 intentionally defines the checks-only, monotone fragment (no user atoms, variables, rules, recursion, or negation). This fragment maps 1:1 to Biscuit checks:
+ - Program (all of Checks) ≅ multiple Biscuit check blocks (all must pass).
+ - Check (any of Queries) ≅ a Biscuit check with multiple queries (OR).
+ - Query (and of Literals) ≅ a Biscuit query's conjunction.
+- Rationale: simple PCF and stable program_id; syntactic attenuation; deterministic, μs-class verification and compact proof traces.
+- Interop: Biscuit tokens in the checks-only fragment can be normalized into CPL/0. If rules are required in a wedge, precompute finite sets and ship a CPL/0 guard, or use a TAP-gated profile that supplies a compiled guard or an approved verifier runtime.
+
+### Declarations
+
+### Program Canonical Format (PCF) & Digest
+
+### Verbs & Resources
+
+
+
+---
+
+## Verbs and Resources
+
+### Verb grammar
+
+Verbs express permitted actions. They are strings and SHOULD be namespaced for clarity and collision avoidance.
+
+- Format: namespace:verb or domain:action
+ - Examples:
+ - deploy:to_env
+ - access:open
+ - energy:curtail
+ - secret:read, secret:derive
+ - data:export, model:infer
+
+Normative requirements:
+
+- Verb semantics MUST be documented in a public or private registry with versioned definitions.
+- Verbs' registry entries MUST declare expected resource scheme(s) and required Bind dimensions (e.g., time_window, channel, policyRef if mediation is required). A CEP MUST deny if a required Bind dimension is missing.
+- TAP profiles MAY whitelist verb sets per domain and MUST reference stable, versioned entries.
+- Implementations MUST treat unknown verbs as non-permitted unless explicitly allowed by TAP.
+
+Extensions and vocabularies:
+
+- Registries SHOULD be content-addressed (schemaRef/vocabRefs) to support anti-ossification and late-bound meaning.
+- Aliases/mappings MAY be provided via lenses in Views (per PSP-2), not in PSP-1.
+- Implementations resolve verb semantics via the versioned registry entries referenced by TAP and/or vocabRefs in Grants; unknown or mismatched entries MUST be denied unless TAP explicitly provides an alias/mapping.
+
+### Resource addressing
+
+Resources identify the target(s) of an action. They SHOULD be expressed as URIs (or URI-like identifiers) with scheme-specific rules.
+
+- `k8s://ns/prod`
+- `door:building-12:lock-3`
+- `meter:utility:site-42`
+- `api:https://api.vendor.com/path`
+- `vault:secret://org/team/service/key-id`
+
+Normative requirements
+
+- Scheme registry: Each resource scheme MUST be documented in a registry entry that defines normalization, comparison, and subset/narrowing semantics. Registries SHOULD be content-addressed (schemaRef/vocabRefs).
+- Specificity: Grants SHOULD use specific resources. If a scheme permits selectors or wildcards, their use MUST be constrained by Bind and the scheme's registry rules.
+- Attenuation check: For a derived Grant, resource.child MUST be a subset of resource.parent under the scheme's subset relation.
+- Unknown schemes: If a CEP cannot resolve a scheme or its comparator, it MUST deny.
+- Bounded selectors: Patterns/selectors (when allowed) MUST be finite or safely bounded (e.g., explicit sets, bounded prefixes/namespaces) with a defined subset proof. Unbounded globs/regex MUST NOT be permitted unless the registry specifies a safe comparator and proof strategy.
+- TAP scoping: TAP profiles MAY restrict acceptable schemes per domain and verb, and MAY further constrain resource forms (e.g., disallow selectors).
+
+Interaction with Bind (informative):
+
+- If Bind includes policyRef (e.g., an Allowed-Surface for mediated flows), the effective scope is the intersection of the resource addressing semantics and the policyRef constraints. Bind.channel and time_window still apply; if any required Bind dimension (as declared by the verb's registry entry) is missing, the CEP MUST deny.
+
+## Grant Structure and Rules
+
+A Grant is a signed claim on the issuer's (P's) sigchain that authorizes a Subject (S) to perform an action (verb) on a resource, subject to Bind constraints. It is composed of an envelope and a payload. The envelope carries identity, timing, linkage, and signatures. The payload carries capability semantics.
+
+Provided by the Envelope (per SIGCHAIN-01):
+
+- jti (JWT ID): The primary, unique identifier for this claim on its sigchain (e.g., an IdSortable/UUIDv7).
+- iss (Issuer): The DID of the Principal (P) issuing the Grant.
+- sub (Subject): The DID of the Subject (S) receiving the Grant.
+- exp (Expiration Time): The timestamp after which the Grant is invalid.
+- iat (Issued At) / nbf (Not Before): Timestamps for issuance and validity start time.
+- prevClaimId / prevDigest: Linkage to the previous claim on the sigchain, as defined by SIGCHAIN-01.
+- Signatures: At least one valid signature per SIGCHAIN-01 (e.g., JWS with protected headers). Multiple signatures are allowed.
+- Canonical digest: A content-addressed hash of the canonicalized claim MUST be derivable per SIGCHAIN-01 for stable cross-references (e.g., grant_ref). Implementations MAY materialize/store it; it is not a payload field.
+
+Provided by the Grant Payload (PCAP-01):
+
+- typ (Type): A string identifying the claim type. For a Grant, this MUST be "ClaimGrant".
+- action: A single verb string (e.g., "deploy:to_env").
+- resource: A single resource identifier (e.g., a URI).
+- bind: The Bind object containing capability constraints.
+
+Normative rules:
+
+- Grants MUST be written on the issuer's (P's) sigchain.
+- The envelope MUST include iss, sub, exp, and a valid signature per SIGCHAIN-01; Presentations beyond exp are invalid.
+- payload.typ MUST be "ClaimGrant".
+- A Grant MUST carry exactly one action (verb) and exactly one resource.
+- action MUST reference a registered verb; for attenuation, child.action MUST equal parent.action unless the verb registry defines a subset sub-verb accepted by TAP.
+- resource MUST conform to a registered scheme; for attenuation, resource.child MUST be a subset of resource.parent per the scheme's subset relation.
+- bind MUST be enforceable by CEPs and MUST be included as a bind_snapshot in the Access PoAR (PRSC-01).
+- Required Bind dimensions declared by the verb's registry entry (e.g., nbf/exp, channel, policyRef) MUST be present; otherwise the CEP MUST deny.
+- Unknown verbs, unknown resource schemes, or unresolvable scheme comparators MUST cause deny.
+- CEPs MUST check revocation status (see Revocation) before enforcement.
+- Presentations MUST reference the Grant via its canonical digest (grant_ref) derived per SIGCHAIN-01.
+
+Minimal JSON skeleton (illustrative):
+
+```json
+{
+ "typ": "ClaimGrant",
+ "action": "namespace:verb",
+ "resource": "scheme://...",
+ "bind": { ... },
+}
+```
+
+Bind constrains how a capability may be exercised. CEPs MUST enforce Bind and MUST include a bind_snapshot in the Access PoAR.
+
+Recommended fields:
+
+- aud: DID or array of DIDs of acceptable enforcers (e.g., `"did:pk:P"` or `["did:pk:P","did:pk:R"]`)
+- purpose: semantic hash or descriptor of intent (e.g., `"sha256:artifact-H"`, `"door-visit-123"`)
+- context: structured k/v describing runtime context (e.g., `{"pod":"runner-xyz","ns":"ci"}`)
+- nbf, exp: NumericDate (Unix seconds) defining the enforceable window; if the envelope also carries nbf/exp, CEPs MUST enforce the intersection
+- ttl: maximum Presentation lifetime in seconds (e.g., 120)
+- maxUses: optional counter for total uses (enforced only by stateful CEPs)
+- geofence / net: optional constraints (e.g., CIDR, region, location)
+- channel: required channel-binding profile id (e.g., "tls_exporter:v1", "dpop:v1")
+- policyRef: OPTIONAL content-addressed “affordance bundle” for mediated flows (e.g., Allowed-Surface); structure/enforcement in CEP/BA spec
+
+Subset rule (for attenuation): child.bind MUST be a subset (narrower or equal) of parent.bind across all relevant dimensions (e.g., audience, purpose, time_window, ttl, geofence/net, channel, policyRef), as declared by the verb's registry entry.
+
+```json
+"bind": {
+ "aud": ["did:pk:P"],
+ "purpose": "sha256:artifact-H",
+ "context": { "ns": "prod", "app": "web" },
+ "nbf": 1768099200,
+ "exp": 1768102800,
+ "ttl": 120,
+ "channel": "tls_exporter:v1",
+ "policyRef": "cid://allowed-surface/http@1.0",
+ "caveat": {
+ "profile": "cap-caveat:biscuit-v1",
+ "data": "..." // profile-defined encoding
+ }
+}
+```
+
+Bind semantics:
+
+- bind is REQUIRED as a container; its contents are not. Which bind keys are REQUIRED for a given verb/domain is determined by the verb's registry entry and/or TAP.
+- If a bind key is present, the CEP MUST enforce it and MUST include it in bind_snapshot in the Access PoAR.
+- Caveat (reserved for profiles)
+ - bind.caveat is OPTIONAL and reserved for profile-typed logic constraints.
+ - In v0.1, TAP MUST NOT require caveats. If bind.caveat is present and the TAP does not explicitly authorize its profile, CEPs MUST deny.
+ - Structure:
+ - profile: string profile identifier (e.g., "cap-caveat:biscuit-v1")
+ - data: opaque to PCAP-01; interpreted by the profile
+ - Safety (when enabled by TAP): Caveats MUST be attenuating, decidable, deterministic, bounded in runtime/memory, and side-effect free. Evaluation failure MUST result in deny unless TAP specifies a safe fallback.
+
+## Attenuation and Delegation
+
+A capability MAY be delegated by a holder S to a new Subject S2 by issuing a derived Grant on the delegator's sigchain, provided all of the following hold.
+
+Normative rules:
+
+- Delegation issuer: The derived Grant's issuer MUST be the delegator (the parent Grant's subject); the derived Grant MUST be written on the delegator's sigchain.
+- Chain of custody: Custody from a trusted Principal to the delegator MUST be provable (e.g., via a grant_chain presented at verification); CEPs MUST verify custody before enforcement.
+- Single action/resource: The derived Grant MUST carry exactly one action and one resource (same as parent, or narrower).
+- No broadening: Delegation MUST NOT broaden any dimension required by the verb registry or TAP (enforcers, time bounds, resource, ttl, channel, policyRef, geofence/net, purpose, context).
+- Verb: child.action MUST equal parent.action unless the verb registry defines a recognized sub-verb with subset semantics accepted by TAP.
+- Resource: resource.child MUST be a subset of resource.parent under the scheme's registered subset relation; unknown comparators MUST cause deny.
+- Bind (general): bind.child MUST be a subset (narrower or equal) of bind.parent across all required dimensions; if a required comparator is unknown or cannot be evaluated, CEP MUST deny.
+- Depth/loops: TAP MAY cap maximum delegation depth; CEPs MUST detect and reject cycles in grant chains.
+
+Verification guidance (informative):
+
+- Presentations SHOULD convey a grant_chain (ordered leaf→root grant_ref digests) and either embed the grants (self-contained) or provide resolvable references per TAP; CEPs verify signatures, custody (issuer=previous subject), and apply subset checks along the chain.
+- If only a single-hop P→S grant is presented, CEPs enforce that grant as-is (no delegation chain to check).
+
+Examples of subset checks (informative):
+
+- aud: `["did:pk:P"] ⊇ ["did:pk:P"] ⊇ []`.
+- time: parent nbf=1000, exp=2000; child nbf=1200, exp=1800 (valid). child nbf=900 or exp=2200 (invalid).
+- ttl: parent 120; child 60 (valid). child 180 (invalid).
+- resource: `door:building-12:* ⊇ door:building-12:lock-3` (valid).
+- channel: equality unless TAP declares a “stronger-or-equal” lattice and child uses a profile ≥ parent.
+
+## Presentation
+
+A Presentation is an ephemeral proof by S that it possesses a Grant and is using it now, on this channel, in this context. Presentations are NOT written to sigchains.
+
+Required fields:
+
+- grant_ref: canonical digest of the leaf Grant (per SIGCHAIN-01).
+- iss: DID of the Subject presenting.
+- pop_sig: holder's proof-of-possession signature over the presentation payload.
+- channelBinding: proof bound to the live transport/session per the required binding profile in bind.channel (e.g., TLS exporter, DPoP).
+- ctx: runtime context; MUST include at least the key/values in Grant.bind.context (may include more).
+- iss, exp, nbf: Presentation lifetime in seconds.
+- nonce: unique value to prevent replay.
+
+Delegation material (per TAP; one is REQUIRED):
+
+- grants: embedded serialized grants sufficient to verify custody and attenuation locally (RECOMMENDED for offline/air-gapped CEPs), or
+- grant_refs (+ resolvers): digests (and, if needed, resolvers via issuers' DID endpoints) allowing the CEP to fetch and verify custody; TAP MAY forbid network fetches.
+
+Normative rules:
+
+- Presentations MUST be PoP-bound to the holder's key and channel-bound to the live session; CEPs MUST verify both.
+- Presentation ttl MUST be enforced by CEPs; now < (presentation_iat + ttl).
+- Presentations MUST reference grant_ref and include ctx; CEPs MUST verify that bind.context ⊆ ctx (all parent k/v pairs preserved).
+- CEPs MUST reject Presentations outside the enforceable time window: within Grant bind.nbf/exp (if present) AND, if the envelope carries nbf/exp, within that window too; all applicable fences MUST pass.
+- If the leaf grant's issuer is not directly trusted, the Presentation MUST carry (or allow resolution of) a grant_chain sufficient to verify signatures, chain custody (issuer=previous subject), and attenuation across the chain; unknown or unevaluable comparators MUST cause deny.
+- Presentations MUST NOT be stored on sigchains.
+
+Minimal JSON skeleton (illustrative):
+
+```json
+{
+ "iss": "did:pk:S", // holder DID (Subject presenting)
+ "jti": "uuid-...", // nonce
+ "iat": 1768099200, // NumericDate (Unix seconds)
+ "exp": 1768099320, // iat + ttl; MUST satisfy exp - iat ≤ Grant.bind.ttl
+ "grant_ref": "cid://G_leaf", // digest per SIGCHAIN-01
+ "ctx": {
+ "ns": "ci",
+ "pod": "runner-xyz"
+ }, // MUST preserve required bind.context keys
+ "cb": { // channel binding (profile + value)
+ "profile": "tls_exporter:v1",
+ "value": "base64url(exporter)"
+ },
+ "grants": [ /* OPTIONAL: embed leaf/parents for self-contained verification */ ],
+ "chain": [ "cid://G_parent", "cid://G_root" ] // OPTIONAL: hints if CEP may resolve */
+}
+```
+
+---
+
+## 8. Revocation and rotation
+
+### 8.1 Revocation
+
+A Grant MAY be revoked by its issuer with a signed revocation claim on P’s
+sigchain:
+
+- type: "revoke", target: grant_id/hash(G), reason(optional), time, sig
+- CEPs MUST check for revocation before enforcing.
+- ViewReceipts SHOULD include knowledge of revocation state at time of action
+ (via bind_snapshot + revocation check in PoAR).
+
+### 8.2 Rotation
+
+For secret-bound flows (PS-BA/SS-BA), upstream leases and secrets MUST be
+rotated per TAP policy. PoAR includes leaseRef (freshness proof). Rotation
+receipts may be recorded per SIGCHAIN-01 (optional).
+
+## 9. CEP enforcement (normative algorithm)
+
+Given a Presentation p from S and an asserted Grant G:
+
+1. Verify issuer signature of G (P’s sigchain), subject DID, action/resource.
+2. Check expiry and revocation of G.
+3. Verify Presentation:
+ - pop_sig by holder S
+ - channelBinding matches live session (mTLS/DPoP)
+ - ttl within bind.ttl and current time within bind.time_window
+ - ctx consistent and bind subset satisfied
+4. If Grant is a derived chain: verify attenuation (child bind/resource/action ⊆
+ parent).
+5. If enforcement passes, enforce per placement/mode and write PoAR:
+ - Include bind_snapshot (canonical copy of bind at enforcement), cepRef,
+ exposureMode, time_source, requestDigest (if mediate).
+ - Deliver PoAR to S.
+6. If any check fails, mint DenyReceipt with reason_code and deliver to S.
+
+## 10. Security considerations
+
+- Holder-of-key (PoP) + channel binding prevent token theft and replay.
+- Presentations MUST be short-lived; CEPs SHOULD reject stale nonces (optional
+ stateful defense).
+- Bind MUST be enforced; failure to snapshot bind in PoAR weakens auditability.
+- Delegation MUST be attenuating; TAP SHOULD disallow broadening by policy.
+- Reveal is dangerous; exposureMode="reveal" MUST follow strict TAP guardrails
+ (tiny ttl/scope, dual-control, immediate revoke/rotate).
+- Privacy: Do not include raw PII in Grants/Presentations; use DIDs and
+ contextual claims; ViewReceipts handle selective disclosure.
+
+## 11. Examples (JSON)
+
+Grant (P → S; deploy to prod for artifact H)
+
+```
+{
+ "type": "grant",
+ "id": "hash(G)",
+ "issuer": "did:pk:cmcdragonkai",
+ "subject": "did:pk:ci-runner-prod-01",
+ "action": "deploy:to_env",
+ "resource": "k8s://ns/prod",
+ "bind": {
+ "audience": ["did:pk:cmcdragonkai"],
+ "purpose": "sha256:artifact-H",
+ "context": { "ns": "prod", "app": "web" },
+ "time_window": { "notBefore": "2025-09-10T09:00:00Z", "notAfter": "2025-09-10T10:00:00Z" },
+ "ttl": "120s"
+ },
+ "expiry": "2025-09-10T10:00:00Z",
+ "prev": "hash(prev)",
+ "sig": "..."
+}
+```
+
+Presentation (S → CEP)
+
+```
+{
+ "type": "presentation",
+ "grant_ref": "hash(G)",
+ "holder": "did:pk:ci-runner-prod-01",
+ "channelBinding": "base64url(exporter)",
+ "ctx": { "ns": "prod", "pod": "runner-xyz" },
+ "ttl": "120s",
+ "nonce": "b1b2c3-...",
+ "pop_sig": "..."
+}
+```
+
+## Revision history
+
+- 2025-09-02: Initial draft edition (holder-of-key + channel binding; Bind
+ subset rules; attenuation; revocation; CEP enforcement algorithm; examples).
+
+Notes:
+
+- Registries (verbs, resource schemes) MAY be maintained as content-addressed
+ vocabularies; TAP profiles SHOULD reference accepted vocab ids.
+- RSC-01 specifies how bind_snapshot, cepRef, exposureMode, leaseRef, and
+ requestDigest appear in PoAR.
+- SIGCHAIN-01 and STORAGE-01 specify durability/archival; PRIVACY-01 covers
+ ViewReceipts/redactions/crypto-erasure.
diff --git a/docs/reference/specifications/PSP-2 - Receipt Model.mdx b/docs/reference/specifications/PSP-2 - Receipt Model.mdx
new file mode 100644
index 0000000..85196b9
--- /dev/null
+++ b/docs/reference/specifications/PSP-2 - Receipt Model.mdx
@@ -0,0 +1 @@
+# PSP-2 - Receipt Model
diff --git a/docs/reference/specifications/PSP-3 - Sigchain and Envelope.mdx b/docs/reference/specifications/PSP-3 - Sigchain and Envelope.mdx
new file mode 100644
index 0000000..acc936b
--- /dev/null
+++ b/docs/reference/specifications/PSP-3 - Sigchain and Envelope.mdx
@@ -0,0 +1 @@
+# PSP-3 - Sigchain and Envelope
diff --git a/docs/reference/specifications/PSP-6 - TAP.mdx b/docs/reference/specifications/PSP-6 - TAP.mdx
new file mode 100644
index 0000000..e69de29
diff --git a/docs/reference/specifications/README.mdx b/docs/reference/specifications/README.mdx
new file mode 100644
index 0000000..45af6fd
--- /dev/null
+++ b/docs/reference/specifications/README.mdx
@@ -0,0 +1,5 @@
+import DocCardList from '@theme/DocCardList';
+
+# How-To Guides
+
+
diff --git a/docs/reference/wedges/README.md b/docs/reference/wedges/README.md
new file mode 100644
index 0000000..9e1b3ce
--- /dev/null
+++ b/docs/reference/wedges/README.md
@@ -0,0 +1,67 @@
+# Wedge Portfolio
+
+Trust Graphs
+
+Multiplayer Utility - the layer 5 software-system.
+
+> The Artifact is Everything: The core gap in the market is not another dashboard or security agent. The gap is the lack of signed, time-anchored, portable, and settlement-grade receipts. Your competitors are building USB agents, but they are still thinking in terms of "logs," not "evidence." This is your key differentiator.
+> The Wedge is Real and It's Top-Down: Your initial intuition was right, but your time at SEMICON and analyzing the OT landscape has confirmed a critical detail: the adoption of "Receipt Rails" in high-value industrial sectors will be driven top-down by compliance and standards, not bottom-up by individual developers. The key is to align with emerging standards like ISA/IEC 62443 and SEMI E187/E188 and sell to the Tier-1 fabs, OSATs, and utilities who are forced to comply. The "singleplayer utility" is selling them a tool that makes this compliance auditable and less painful.
+
+
+
+- Blockchain Wallet Reputation
+- Email Sender Reputation
+- Sayari Supply Chain Trust
+- DevOps Authority Tracing
+
+- Energy DR/curtailment
+ - Verifier: utility/auditor/insurer
+ - Value: kW×Δt “receipts” → faster payouts, lower disputes
+ - T1R: 4–8 weeks (site + meter/EMS hookup)
+- Fisheries/cold-chain
+ - Verifier: export compliance, buyer’s QA, insurer
+ - Value: catch + temperature receipts → export finance, fewer chargebacks
+ - T1R: 6–10 weeks (boat + sensor pack + buyer)
+- Disaster logistics corridors (UAV/USV + mesh)
+ - Verifier: NGO/agency auditors
+ - Value: movement/hand-off receipts → audit time −50%
+ - T1R: 4–8 weeks (pilot corridor + NGO)
+- Informal delivery fleets (motorbike)
+ - Verifier: micro-insurer/financier
+ - Value: delivery/outcome receipts → eligibility for insurance/credit
+ - T1R: 4–6 weeks (fleet partner + phone app)
+- Reverse logistics (RMA)
+ - Verifier: finance/audit/ERP; sustainability reporting
+ - Value: RMA state-machine “receipts rail” → refunds/chargebacks clarity, refurb analytics
+ - T1R: 4–8 weeks (one brand + 3PL)
+- Internal HR compliance (Fair Work–style dispute trail)
+ - Verifier: regulator/tribunal; corporate audit
+ - Value: standardized settlement-grade artifacts for legal discovery → faster resolution -> prevents "lack of documentation" - because process is admin-heavy
+ - T1R: 4–6 weeks (one HR/legal team)
+
+---
+
+DevOps authority tracking - this is like SSO (and that user onramp/offramp) extended to the entire devops enterprise resources
+
+I need a way to "write down" or audit log a change to authority.
+
+I just changed my GitHub CI/CD NIXPKGS_PRIVATE_PAT to a new one.
+
+Why?
+
+Because after offboarding an employee, it turns out that while she was responsible for setting up infrastructure, she had injected her own PAT there. And it worke while her account was active.
+
+After offboarding her accounts, the CI/CD failed. It failed (late) rather than (early) because we don't early warning that a particular token that is used somewhere is now invalid because of a state change somewhere else (this the action at a distance problem, or cache-coherency/state-sync/foreign-key integrity problem applied to configuration/and secrets).
+
+To fix this, I generated a new token - but I had to:
+
+1. Figure why it was failing?
+2. Trace to the root cause that was due to an invalid token.
+3. Backtrack through business-tacit-knowledge realising that she was responsible for this technology domain, and therefore maybe it was her token.
+4. Figure out how to "recreate" this token - because it's not 100% clear what exactly this token was capable of.
+5. Inferring from the name, it's a token designed to access only a single repository with read-only permissions of the contents.
+6. Therefore, replacing it with a token that has that exact authority - but under a new more durable principal rather than any single user's account.
+7. But now we have a repeat problem. The point problem is fixed, but a long term problem remains. There is no audit log, and this problem can happen again. The token will expire eventually and we will have this problem again.
+
+An audit log is not enough. I could write it into a log. But it's not composable, not automated, not open. It's not "connected" the Source of Authority, the User of Authority and Target of Authority.
+
diff --git a/docs/theory/clarifying-mental-models.md b/docs/theory/clarifying-mental-models.md
new file mode 100644
index 0000000..24e03e6
--- /dev/null
+++ b/docs/theory/clarifying-mental-models.md
@@ -0,0 +1,258 @@
+# Clarifying Mental Models
+
+You may be using Polykey to solve a practical problem, like managing secrets in
+a CI/CD pipeline. But beneath that toolset lies a fundamental shift in how to
+think about security and trust.
+
+This shift is from a **Fortress Mentality** to a **Verifiable Ledger
+Mentality**. The old world is about prevention: building walls to stop bad
+things from happening. Our world is about proof: creating an indisputable,
+portable, and settlement-grade record of what actually happened.
+
+Because this approach creates a new category of infrastructure: **Receipt
+Rails**, it's easy to miscast. You might ask: Is this just better logging? A
+private blockchain? Another IAM tool? The answer is no.
+
+This page is the bridge from the 'how' to the 'why'. It is a reference for both
+the engineer wondering why we mint 'receipts' instead of logs, and the architect
+evaluating the entire system. Use it to clear the common hurdles and understand
+how we turn operational events into verifiable, economic assets.
+
+## The Universal Hurdle: Prevention → Provability
+
+The single most important shift to understand is moving from a **Fortress
+Mentality** to a **Verifiable Ledger Mentality**. This isn't an upgrade; it's a
+change in the fundamental physics of how you manage risk and create value.
+
+- **The Fortress Mentality (The old world):** This worldview is about
+ _prevention_. It asks, "How do I build walls to prevent bad things from
+ happening?" Risk is managed by trying to achieve a perfect, static state of
+ control. Its primary artifacts are firewalls, access policies, and siloed
+ logs. In this model, security is an internal cost center.
+- **The Verifiable Ledger Mentality (the new world):** This worldview is about
+ **proof**. It assumes events—both good and bad—are inevitable and asks, "How
+ do I create an indisputable, portable, and settlement-grade record of what
+ actually happened?" Risk is managed by making the system transparent,
+ auditable, and capable of rapid, fair settlement. In this model, security
+ becomes an external revenue enabler.
+
+This explains why we are obsessed with **Receipts**. A log entry is a passive
+liability you store in case something goes wrong. A cryptographic receipt, like
+a Proof-of-Action Receipt (PoAR), is an active **asset**. It is a
+self-contained, verifiable, and portable piece of evidence designed to be
+shared, insured, and settled upon. With this shift, your systems can stop being
+a cost center for storing logs and start being a value creator that mints
+tradable proof.
+
+## Name the Category: Receipt Rails, Not Better Logging
+
+Because the "Verifiable Ledger Mentality" is new, people will try to fit it into
+old categories. The deepest challenge is that we are creating a new category:
+**"Settlement-grade operational evidence,"** delivered via **Receipt Rails.**
+
+If you mis-categorize the system, its value is obscured. Here are the most
+common misfits:
+
+- **"It's just better logging."** No. A log is a liability—data to be stored and
+ searched reactively. A receipt is an asset—a cryptographic instrument designed
+ to be proactively shared and settled. It has a defined lifecycle, value, and
+ is understood by multiple parties.
+- **"It's blockchain for enterprise."** No. This is not about consensus or a
+ single global ledger. Receipts are generated at the edge, off-chain, and
+ stored in per-identity ledgers (Sigchains). It is designed for performance and
+ privacy, using optional hash-anchoring only when public timestamping is
+ required.
+- **"It's another IAM/audit tool."** No. It's the infrastructure that makes your
+ IAM and audit systems interoperable and their outputs valuable. It doesn't
+ replace your identity provider; it gives it a way to issue portable
+ **Capabilities**. It doesn't replace your audit framework; it feeds it with
+ verifiable proof that dramatically lowers your cost of compliance.
+
+The core product of this new category is the **Verifiable Outcome Receipt
+(VOR)** and its supporting artifacts. Think of it not as a tool you install, but
+as a utility you connect to—a set of rails for moving verifiable truth between
+organizations.
+
+## Governance People Trust: The ATN, TAP, and RAM
+
+Centralized systems feel safe because they offer a single "throat to choke." A
+federated network can feel amorphous and risky. This is why our model is not
+just a protocol; it's a governed ecosystem.
+
+The core hurdle is overcoming the fear that decentralization means chaos. Our
+answer is the **Accredited Trust Network (ATN)**, a framework that creates
+resilience and accountability through three key instruments:
+
+- **The ATN (Accredited Trust Network):** This isn't a free-for-all. It's a
+ well-governed federation of participants who agree to operate by a shared set
+ of rules. Think of it like the network of banks that agree to honor Visa
+ transactions—they don't have a single central operator, but they have a shared
+ standard that makes the whole system work.
+- **The TAP (Threat & Acceptance Profile):** This is the **rulebook**. For any
+ given use case (like DevOps or energy grid management), the TAP defines what
+ constitutes a valid, secure, and acceptable receipt. It's the technical and
+ operational standard that participants in that wedge agree to.
+- **The RAM (Receipt Acceptance Memo):** This is the **social contract**. A RAM
+ is a signed memo from a key Verifier (an insurer, auditor, or regulator)
+ stating, "We will accept any receipt that conforms to TAP-01 as binding
+ evidence for settling claims or satisfying compliance."
+
+This model fundamentally changes the conversation. The question is no longer,
+"Do I trust Polykey?" The question becomes, "Does this receipt conform to the
+TAP that my insurer has already signed off on in a RAM?" It replaces vendor
+trust with verifiable, contractual acceptance.
+
+## Dual‑Plane Reality: Capabilities Govern Tokens
+
+A common technical hurdle is the tension between cryptographic purity and
+real-world practicality. Our architecture is explicitly dual-plane. We don't
+fight this dualism; we govern it.
+
+- **The Control Plane (The Authority Fabric):** This is the elegant, "vitamin"
+ part of our system. It is **asymmetric and identity-bound.** It operates on
+ **Capabilities**, granular, signed grants of authority that are presented with
+ proof-of-possession. This is where identity, attenuation, and revocation live.
+- **The Data Plane (The Secret Store):** This is the pragmatic, "painkiller"
+ part of our system. It acknowledges that the world still runs on **symmetric,
+ secret-bound authority** (bearer tokens, API keys). The Polykey Vault is
+ designed to be best-in-class cold storage for these secrets.
+
+The magic is how the control plane governs the data plane. An actor presents an
+identity-bound **Capability** to a **Capability Enforcement Point (CEP)**. The
+CEP verifies the capability and _then_ safely interacts with the secret-bound
+world on the actor's behalf. It does this in one of three modes:
+
+1. **Mediate:** The CEP holds the secret and makes the API call for you. No
+ secret is ever exposed.
+2. **Derive:** The CEP uses its master secret to create a short-lived,
+ narrowly-scoped token for you.
+3. **Reveal:** In rare, break-glass scenarios, the CEP can reveal the raw
+ secret, but this action creates an urgent, high-priority receipt for
+ immediate audit.
+
+This architecture allows you to get the security, audit, and portability
+benefits of an identity-bound system while still safely interacting with every
+secret-bound tool in your existing DevOps workflow.
+
+## Compliance vs. Composability: "Who Says This Counts?"
+
+A cryptographically perfect system is commercially useless if no one accepts its
+outputs. The most critical hurdle is answering the skeptic who asks, "This is
+all great theory, but who actually _says_ your receipts are valid? Does my
+auditor, my insurer, or my lawyer care?"
+
+Our system is designed to bridge the gap between what is technically possible
+(**composability**) and what is commercially required (**compliance**). The
+answer to "Who says this counts?" is never "Trust the math." It is, "The people
+you already pay for compliance and risk transfer say it counts."
+
+This is achieved through our go-to-market strategy, which is centered on the
+**Receipt Acceptance Memo (RAM)**:
+
+- **The Wedge Strategy:** We don't try to boil the ocean. We focus on a
+ specific, high-value "wedge," like satisfying a particular SOC 2 control for
+ DevOps workflows.
+- **Acceptance Diplomacy:** We work with the key verifiers in that wedge—the
+ auditors, the insurers—to co-author a **Threat & Acceptance Profile (TAP)**
+ that defines exactly what a valid receipt needs to contain to serve as
+ evidence for that control.
+- **The RAM Flips the Market:** The final step is getting that verifier to sign
+ a RAM. This memo makes acceptance explicit. It says, "We, the auditor, will
+ accept any receipt conforming to this TAP as sufficient evidence for this
+ control."
+
+This approach fundamentally helps your organization. Instead of pushing a new,
+unproven technology to a compliance department, the system arrives with
+pre-approved acceptance from their own auditors. One RAM in one wedge creates
+the beachhead that proves the economic and legal value of the entire system for
+everyone involved.
+
+You may be using Polykey to solve a practical problem, like managing secrets in
+a CI/CD pipeline. But beneath that toolset lies a fundamental shift in how to
+think about security and trust.
+
+This shift is from a Fortress Mentality to a Verifiable Ledger Mentality. The
+old world is about prevention: building walls to stop bad things from happening.
+This model is about proof: creating an indisputable, portable, and
+settlement-grade record of what actually happened.
+
+Because this approach creates a new category of infrastructure: Receipt Rails.
+It's easy to miscast it. You might ask: Is this just better logging? A private
+blockchain? Another IAM tool? The answer is no.
+
+This page is the bridge from the 'how' to the 'why'. It is a reference for both
+the engineer wondering why we mint 'receipts' instead of logs, and the architect
+evaluating the entire system. Use it to clear the common hurdles and understand
+how we turn operational events into verifiable, economic assets.
+
+## Value by Role: Show Me, Don’t Tell Me
+
+The grand narrative is powerful, but you will likely adopt this system because
+it solves an immediate, painful problem. The key is to translate the abstract
+benefits of provability into concrete value for each stakeholder in your
+organization.
+
+- **For Developers & DevOps: The "Friction vs. Reward" Hurdle** **Their
+ Default:** _"This sounds complicated. A JWT and a log entry is faster."_ **The
+ Value:** The immediate entry point is the **Polykey Vault**. It solves the
+ practical, painful problem of secret management more securely and efficiently
+ than ad-hoc workflows. This provides the "painkiller" first; the powerful
+ benefits of verifiable receipts become a seamless byproduct of solving a
+ problem you already have.
+- **For CISOs & Compliance: The "Checklist vs. Reality" Hurdle** **Their
+ Default:** _"This isn't on my SOC 2 checklist. My auditor has never heard of a
+ VOR."_ **The Value:** The **Receipt Acceptance Memo (RAM)** is the answer for
+ your compliance teams. It bridges the gap between this advanced system and
+ legacy frameworks by providing pre-negotiated, signed approval from auditors,
+ stating that these receipts are an acceptable form of evidence.
+- **For Insurers & Auditors: The "Actuarial vs. Evidentiary" Hurdle** **Their
+ Default:** _"Our models are based on statistical losses. We don't know how to
+ price a cryptographic receipt."_ **The Value:** For the verifiers in your
+ ecosystem, the value is a measurable reduction in their single biggest cost:
+ dispute resolution and fraud investigation. Receipts provide a stronger,
+ cheaper, and faster way to verify what happened, directly impacting their loss
+ adjustment expenses.
+- **For Legal & Finance: The "Admissibility vs. Settlement" Hurdle** **Their
+ Default:** _"How does this map to traditional evidence rules and contract
+ enforcement?"_ **The Value:** A simple analogy is powerful for your legal
+ teams. A cryptographic receipt is like a notarized document, but the "notary"
+ is mathematics. It provides a cryptographically assured chain of custody that
+ is stronger, and therefore more admissible, than many traditional methods.
+
+## Privacy Without Surveillance
+
+A system that creates a verifiable record of every important action can be
+misconstrued as a surveillance tool. This is a fundamental misreading of the
+architecture, which is designed for **proof with privacy**. The goal is to give
+you, the data owner, granular control over who sees what, when, and why.
+
+- **"This centralizes all our logs."** No. The system is federated by design.
+ Receipts are written to **per-identity ledgers (Sigchains)**, not a single,
+ monolithic database. There is no central aggregator with a god's-eye view.
+ Data is replicated selectively based on rules you help define in the TAP.
+- **"This is going to leak PII."** No. The protocol is designed to separate
+ claims from evidence. Receipts can make verifiable claims (e.g., "this user is
+ over 21") without revealing the underlying PII (their date of birth). Evidence
+ can be encrypted, redacted, and selectively disclosed using **ViewReceipts**,
+ ensuring a verifier only gets the minimum information necessary.
+
+The governing principle is simple: the system is built to prove facts, not to
+expose your data.
+
+## FAQ: The Usual Misframings
+
+- **“This is just blockchain.”** No. It is an edge-native, off-chain system.
+ Receipts are generated and stored on per-identity ledgers without requiring a
+ distributed consensus mechanism. It is built for performance and privacy, with
+ optional hash anchors to a public chain only for specific timestamping use
+ cases.
+- **“This replaces our IAM.”** No. It makes your existing IAM/OPA systems
+ interoperable and their outputs far more valuable. It consumes the identity
+ from your provider to issue portable **Capabilities** that can cross trust
+ boundaries, and then it generates the **Receipts** that prove how that
+ identity was used.
+- **“This is too complex for our critical OT/industrial systems.”** This isn't
+ about replacing deterministic PLC logic. It's about adding a "receipt printer"
+ to it. It provides a simple, reliable way to prove that a critical action
+ (like a demand response event) actually happened, so you or your partners can
+ get paid or satisfy compliance faster and with less dispute.
diff --git a/docs/theory/receipt-rails-operational-flow.md b/docs/theory/receipt-rails-operational-flow.md
index aea0ee5..3556ade 100644
--- a/docs/theory/receipt-rails-operational-flow.md
+++ b/docs/theory/receipt-rails-operational-flow.md
@@ -137,18 +137,17 @@ sequenceDiagram
alt Principal-side CEP (placement=P, bridging=true) [PS-BA]
Note over P: If P and R are the same trust boundary
this is effectively native (colocated)
bridging=false, PoAR still on P's sigchain
S ->> P: Present capability (Presentation)
+ Note over P: Σ = verify(Presentation, Grant, Bind, channel, ttl,
attenuation?, lease?, allowed-surface?)
break Verification fails at P
Note over P: Deny path
Mint DenyReceipt with reason code
(binding_mismatch, lease_stale, surface_violation, rate_limit)
Note over P: Write DenyReceipt on P's sigchain
P ->> S: Deliver DenyReceipt
end
alt Mediate at P
- Note over P: Verify Presentation + Bind + fresh LeaseRef
Record requestDigest vs Allowed-Surface
P ->> R: ToA API call
R -->> P: Result
P -->> S: Result (if requester expects data)
else Derive at P
- Note over P: Verify Presentation + Bind + fresh LeaseRef
P ->> S: Short-scope token (session-bound)
S ->> R: ToA API call (using token)
R -->> S: Result
@@ -163,12 +162,12 @@ sequenceDiagram
else Resource-side CEP (placement=R, bridging=false) [native]
S ->> R: Present capability (Presentation)
+ Note over R: Σ = verify(Presentation, Grant, Bind, channel, ttl,
attenuation?)
break Verification fails at R
Note over R: Deny path
Mint DenyReceipt with reason code
(binding_mismatch, lease_stale, surface_violation, rate_limit)
Note over R: Write DenyReceipt on R's sigchain
R ->> S: Deliver DenyReceipt
end
- Note over R: Enforce at Resource CEP
R -->> S: Result (if requester expects data)
Note over R: Write Access PoAR on R's sigchain
R ->> S: Deliver PoAR
@@ -176,6 +175,7 @@ sequenceDiagram
else Subject-side CEP (placement=S, bridging=false) [SSA wallet/session]
Note over S: S does not hold long-lived upstream lease.
S ->> S: Present capability (internal Presentation)
+ Note over S: Σ = verify(Presentation, Grant, Bind, channel, ttl,
attenuation?)
break Verification fails at S
Note over S: Deny path
Mint DenyReceipt with reason code
(binding_mismatch, lease_stale, surface_violation, rate_limit)
Note over S: Write DenyReceipt on S's sigchain
@@ -189,6 +189,7 @@ sequenceDiagram
else Subject-side CEP (placement=S, bridging=true) [SS-BA, rare]
S ->> S: Present capability (internal Presentation)
+ Note over S: Σ = verify(Presentation, Grant, Bind, channel, ttl,
attenuation?, lease?, allowed-surface? for mediate)
break Verification fails at S
Note over S: Deny path
Mint DenyReceipt with reason code
(binding_mismatch, lease_stale, surface_violation, rate_limit)
Note over S: Write DenyReceipt on S's sigchain
diff --git a/docusaurus.config.ts b/docusaurus.config.ts
index c38e53b..eba6f79 100644
--- a/docusaurus.config.ts
+++ b/docusaurus.config.ts
@@ -59,6 +59,8 @@ const pluginDocs: [string, PluginDocsOptions] = [
sidebarPath: './sidebars.ts',
include: ['**/*.md', '**/*.mdx'],
exclude: ['**/_*.{js,jsx,ts,tsx,md,mdx}', '**/_*/**', '**/.**'],
+ showLastUpdateAuthor: true,
+ showLastUpdateTime: true
},
];
diff --git a/flake.lock b/flake.lock
index 5c7bdc9..cf87269 100644
--- a/flake.lock
+++ b/flake.lock
@@ -20,17 +20,17 @@
},
"nixpkgs": {
"locked": {
- "lastModified": 1736139540,
- "narHash": "sha256-39Iclrd+9tPLmvuFVyoG63WnHZJ9kCOC6eRytRYLAWw=",
+ "lastModified": 1754214453,
+ "narHash": "sha256-Q/I2xJn/j1wpkGhWkQnm20nShYnG7TI99foDBpXm1SY=",
"owner": "NixOS",
"repo": "nixpkgs",
- "rev": "8ab83a21276434aaf44969b8dd0bc0e65b97a240",
+ "rev": "5b09dc45f24cf32316283e62aec81ffee3c3e376",
"type": "github"
},
"original": {
"owner": "NixOS",
"repo": "nixpkgs",
- "rev": "8ab83a21276434aaf44969b8dd0bc0e65b97a240",
+ "rev": "5b09dc45f24cf32316283e62aec81ffee3c3e376",
"type": "github"
}
},
@@ -39,11 +39,11 @@
"nixpkgs": "nixpkgs"
},
"locked": {
- "lastModified": 1736140072,
- "narHash": "sha256-MgtcAA+xPldS0WlV16TjJ0qgFzGvKuGM9p+nPUxpUoA=",
+ "lastModified": 1754379606,
+ "narHash": "sha256-ivaveQQFYryrIf9HlpKGHq82m1NHKnTwDo6mGflSoxA=",
"owner": "MatrixAI",
"repo": "nixpkgs-matrix",
- "rev": "029084026bc4a35bce81bac898aa695f41993e18",
+ "rev": "c8338a89f5f2936e233f475b3f018ecba61f89bc",
"type": "github"
},
"original": {
diff --git a/flake.nix b/flake.nix
index e66a6a6..86d1d86 100644
--- a/flake.nix
+++ b/flake.nix
@@ -15,7 +15,7 @@
shell = { ci ? false }:
with pkgs;
mkShell {
- nativeBuildInputs = [ nodejs shellcheck patchelf gitAndTools.gh ];
+ nativeBuildInputs = [ nodejs shellcheck patchelf gitAndTools.gh yek ];
shellHook = ''
echo "Entering $(npm pkg get name)"
set -o allexport
diff --git a/sidebars.ts b/sidebars.ts
index c9134bd..1c1dabf 100644
--- a/sidebars.ts
+++ b/sidebars.ts
@@ -77,6 +77,7 @@ const sidebars: SidebarsConfig = {
id: 'theory/README',
},
items: [
+ 'theory/clarifying-mental-models',
'theory/trust-operating-system',
'theory/receipt-rails-operational-flow',
'theory/secrets-management',
@@ -94,6 +95,19 @@ const sidebars: SidebarsConfig = {
id: 'reference/README',
},
items: [
+ {
+ type: 'category',
+ label: 'Specifications',
+ link: {
+ type: 'doc',
+ id: 'reference/specifications/README'
+ },
+ items: [
+ 'reference/specifications/PSP-1 - Capability Model and Grammar',
+ 'reference/specifications/PSP-2 - Receipt Model',
+ 'reference/specifications/PSP-3 - Sigchain and Envelope'
+ ],
+ },
{
type: 'category',
label: 'Architecture',