From 0c510fc7a2c06609c8e96c0f645ca1ee02096a45 Mon Sep 17 00:00:00 2001
From: Roger Qiu <roger.qiu@polyhack.io>
Date: Tue, 2 Sep 2025 19:28:23 +1000
Subject: [PATCH 1/9] wip: adding cap-01 spec and clearing mental hurdles

---
 docs/reference/specifications/README.mdx      |   5 +
 .../specifications/acceptance/TAP-01.mdx      |   0
 docs/reference/specifications/cap/CAP-01.mdx  | 280 ++++++++++++++++++
 .../specifications/receipts/RSC-01.mdx        |   0
 docs/theory/clearing-mental-hurdles.md        |  98 ++++++
 docs/theory/receipt-rails-operational-flow.md |   7 +-
 docusaurus.config.ts                          |   2 +
 sidebars.ts                                   |  12 +
 8 files changed, 401 insertions(+), 3 deletions(-)
 create mode 100644 docs/reference/specifications/README.mdx
 create mode 100644 docs/reference/specifications/acceptance/TAP-01.mdx
 create mode 100644 docs/reference/specifications/cap/CAP-01.mdx
 create mode 100644 docs/reference/specifications/receipts/RSC-01.mdx
 create mode 100644 docs/theory/clearing-mental-hurdles.md

diff --git a/docs/reference/specifications/README.mdx b/docs/reference/specifications/README.mdx
new file mode 100644
index 00000000..45af6fde
--- /dev/null
+++ b/docs/reference/specifications/README.mdx
@@ -0,0 +1,5 @@
+import DocCardList from '@theme/DocCardList';
+
+# How-To Guides
+
+<DocCardList />
diff --git a/docs/reference/specifications/acceptance/TAP-01.mdx b/docs/reference/specifications/acceptance/TAP-01.mdx
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/reference/specifications/cap/CAP-01.mdx b/docs/reference/specifications/cap/CAP-01.mdx
new file mode 100644
index 00000000..70677d25
--- /dev/null
+++ b/docs/reference/specifications/cap/CAP-01.mdx
@@ -0,0 +1,280 @@
+# CAP-01 - Capability Grammar
+
+<details>
+  <summary>Metadata</summary>
+  <dl>
+    <dt>Status:</dt><dd>Draft</dd>
+    <dt>Edition:</dt><dd>2025-09-02</dd>
+    <dt>Extends:</dt><dd>-</dd>
+    <dt>Updates:</dt><dd>-</dd>
+    <dt>Obsoletes:</dt><dd>-</dd>
+    <dt>Depends on:</dt><dd>SIGCHAIN-01, RSC-01, PRIVACY-01</dd>
+  </dl>
+</details>
+
+## Abstract
+
+CAP-01 defines the portable, verifiable capability model used by Polykey to express delegated authority. It specifies the structure and semantics of Grants (capability tokens) and Presentations (ephemeral proofs of capability), including verbs, resource addressing, binding constraints, attenuation, and revocation. CAP-01 ensures capabilities are composable, attenuable (never broadened), and safely enforceable at CEPs (Capability Enforcement Points), producing settlement-grade receipts (RSC-01).
+
+## Terminology
+
+- Principal (P): Originator of authority; issues a Grant to a Subject.
+- Subject (S): Holder that exercises the capability by creating a Presentation.
+- Resource (R): Target of the action; may host a native CEP (CEP(R)).
+- CEP: Capability Enforcement Point at P/S/R that verifies Presentations and enforces capabilities (writes the Access PoAR).
+- Grant (G): A signed, portable capability issued by P to S.
+- Presentation (Π): An ephemeral, proof-of-possession token created by S that references a Grant with context and channel binding. Not stored on-chain.
+- Bind: Binding constraints inside a Grant that restrict its use (audience, purpose, time, context, etc.).
+- Attenuation: Narrowing a capability when delegating; derived Grants must be a subset of their parent capability.
+- Verification (Σ): The verification handshake at the enforcing CEP. `Σ = verify(Π, G, Bind, Channel, TTL, Attenuation?, Lease?)`
+- Lease: The upstream authority relationship to a non-native SoA; referenced via leaseRef in PoAR (RSC-01).
+- PoAR: Proof-of-Action receipt written by the enforcing CEP (RSC-01).
+
+## Overview and Goals
+
+CAP-01 provides:
+
+- A minimal, expressive grammar for capabilities (verbs over resources with constraints).
+- A binding system (Bind) to tie capability use to audience, purpose, context, and time.
+- A safe delegation model: capabilities can be attenuated and re-delegated without ever broadening power.
+- A secure, ephemeral Presentation that is resistant to theft and replay (PoP + channel binding).
+- Clear interoperability with CEP enforcement and receipt minting (RSC-01).
+
+Design goals:
+
+- Portable: Grants and Presentations are verifiable across boundaries.
+- Minimal: Core fields are few and clearly defined; extensions via vocabularies.
+- Attenuable: Derived Grants must shrink authority; verifiable at enforcement.
+- Secure by default: Holder-of-key + channel binding; short TTLs for Presentations.
+- Receipt-ready: CEPS capture a bind_snapshot in PoAR.
+
+## Verbs and Resources
+
+### Verb grammar
+
+Verbs are strings, recommended namespaced for clarity:
+
+- Format: namespace:verb or domain:action
+  - Examples:
+    - deploy:to_env
+    - access:open
+    - energy:curtail
+    - secret:read, secret:derive
+    - data:export, model:infer
+
+Verb semantics must be documented in a public or private registry (with versioned definitions). TAP profiles may whitelist verb sets per domain.
+
+### Resource addressing
+
+Resources are 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`
+
+TAP profiles may restrict acceptable schemes per domain and verb.
+
+## Grant Structure and Rules
+
+A Grant is a signed claim on P's sigchain that authorizes S to perform actions (verbs) on resources, subject to Bind constraints.
+
+Required fields:
+
+- id: opaque identifier (hash of canonicalized claim)
+- type: "grant"
+- issuer: DID of P
+- subject: DID of S
+- action: verb (string)
+- resource: resource URI
+- bind: Bind object (Section 5)
+- expiry: timestamp (notAfter)
+- prev: previous claim hash (sigchain link)
+- sig: signature by issuer's key
+
+Normative rules:
+
+- Grants MUST be written on the issuer's (P's) sigchain.
+- expiry MUST be present and enforced; Presentations beyond expiry are invalid.
+- action/resource MUST be specific; wildcards SHOULD be avoided unless constrained by Bind.
+- bind MUST be enforceable by CEPs and included in the PoAR bind_snapshot.
+- A Grant MAY be revoked (Section 8).
+
+Minimal JSON skeleton:
+
+```json
+{
+  "type": "grant",
+  "id": "hash(...)",
+  "issuer": "did:pk:P",
+  "subject": "did:pk:S",
+  "action": "deploy:to_env",
+  "resource": "k8s://ns/prod",
+  "bind": { ... },
+  "expiry": "2025-09-10T10:00:00Z",
+  "prev": "hash(prev)",
+  "sig": "..."
+}
+```
+
+Bind constrains how a capability may be exercised. CEPs MUST enforce Bind and include a bind_snapshot in PoAR.
+
+Recommended fields:
+
+- audience: list of DIDs of acceptable enforcers (e.g., ["did:pk:P","did:pk:R"])
+- purpose: semantic hash or descriptor of intent (e.g., hash of artifact H, “door-visit-123”)
+- context: structured k/v describing runtime context (e.g., `{"pod":"runner-xyz","ns":"ci"}`)
+- time_window: `{ notBefore, notAfter }` narrower than Grant expiry
+- ttl: maximum Presentation TTL (e.g., "120s")
+- maxUses: optional counter for total uses (enforced by CEP capable of maintaining state)
+- geofence / net: optional constraints (e.g., CIDR, region, location)
+
+Subset rule (for attenuation, Section 6): child.bind MUST be a subset (narrower or equal) of parent.bind on every dimension (audience, purpose scope, time, ttl, etc.).
+
+```json
+"bind": {
+  "audience": ["did:pk:P"],
+  "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"
+}
+```
+
+## Attenuation and Delegation
+
+A capability MAY be delegated by S to S2 by issuing a derived Grant on the delegator's sigchain, provided:
+
+- The derived Grant's action/resource are identical or narrower (subset).
+- The derived Grant's bind is a subset of the parent Grant's bind on all dimensions.
+- The chain of custody (P → S → S2) is provable via sigchains.
+- No broadening: delegation MUST NOT increase the set of allowed enforcers, time, scope, or resource coverage.
+
+Normative subset checks (examples):
+
+- `time_window.child` ⊆ `time_window.parent`
+- `audience.child` ⊆ `audience.parent`
+- `ttl.child` ≤ `ttl.parent`
+- `resource.child` narrower (e.g., specific door vs building-wide)
+- `purpose.child` equals or narrower (e.g., same artifact hash or a stricter descriptor)
+
+CEPs SHOULD verify chain attenuation if presented with a chain (Grant_ref may include a chain; otherwise, single-hop P→S is verified).
+
+## Presentation
+
+A Presentation is an ephemeral proof by S that it holds a Grant and is using it now, in this context, on this channel. Presentations are NOT written to sigchains.
+
+Required fields:
+- grant_ref: hash of Grant (or terminal of a chain)
+- holder: DID of S
+- pop_sig: signature by S’s private key over the presentation payload
+- channelBinding: exporter-derived key for the live TLS/mTLS session (or equivalent)
+- ctx: runtime context (subset of bind.context)
+- ttl: small (e.g., 120s)
+- nonce: unique value to prevent replay
+
+Normative rules:
+- Presentations MUST be bound to holder’s key (PoP) and to the transport/session (channelBinding).
+- Presentation ttl MUST be enforced by CEPs.
+- Presentations MUST include binding to Grant_ref and context; CEPs MUST check bind subset.
+- CEPs MUST reject Presentations beyond Grant expiry or outside bind.time_window.
+
+Minimal JSON skeleton (often conveyed as a signed JWT/DSSE):
+```
+{
+  "type": "presentation",
+  "grant_ref": "hash(G)",
+  "holder": "did:pk:S",
+  "channelBinding": "base64url(exporter)",
+  "ctx": { "ns": "ci", "pod": "runner-xyz" },
+  "ttl": "120s",
+  "nonce": "uuid-...",
+  "pop_sig": "sig_by_S"
+}
+```
+
+## 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/receipts/RSC-01.mdx b/docs/reference/specifications/receipts/RSC-01.mdx
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/theory/clearing-mental-hurdles.md b/docs/theory/clearing-mental-hurdles.md
new file mode 100644
index 00000000..8247dc57
--- /dev/null
+++ b/docs/theory/clearing-mental-hurdles.md
@@ -0,0 +1,98 @@
+# Clearing the Mental Hurdles
+
+## The Universal Hurdle (The One Thing Everyone Will Struggle With) (Security as Centralized Internal Problem vs Security as a Network/Utility)
+
+Before breaking it down by audience, it's crucial to name the single, universal educational hurdle that underpins all the others.
+
+The biggest hurdle is transitioning people's thinking from a Fortress Mentality to a Verifiable Ledger Mentality.
+
+- **The Fortress Mentality (The Old World):** "How do I build walls to prevent bad things from happening?" This worldview is about prevention, perimeters, and control. Risk is managed by trying to achieve a perfect, static state of security. This is the world of firewalls, antivirus, and centralized access control.
+- **The Verifiable Ledger Mentality (Your New World):** "Bad things (and good things) are inevitable. How do I create an indisputable, portable, and settlement-grade record of what actually happened?" This worldview is about proof, resilience, and accountability. Risk is managed by making the system transparent, auditable, and capable of rapid, fair settlement after an event.
+
+Every conversation you have is, at its core, an attempt to pull someone from the first worldview into the second.
+
+## Logging vs Receipts - The Value of Tradable Assets in a Network
+
+The biggest educational hurdle for all parties is understanding that you are not selling them a product; you are introducing them to a new economic and operational physics. Their existing mental models are insufficient because they are based on a world of centralized, high-trust, and opaque systems.
+Here are the specific conceptual leaps you must guide them through:
+From "Data" to "Asset": The most difficult shift is getting people to see a "receipt" not as a piece of data (like a log entry), but as a negotiable, valuable, and self-contained asset. A log is a liability to be stored; a receipt is an asset to be traded, insured, or settled. This requires them to mentally move from the world of IT (managing data) to the world of finance (managing assets).
+From "Centralized Control" to "Federated Governance": Stakeholders, especially CISOs and regulators, are conditioned to think in terms of a central authority (a PDP, a root CA, a government body). Your model of an Accredited Trust Network (ATN) is a federated one, where trust is an emergent property of a network of peers adhering to a shared standard (the TAP). The hurdle is teaching them that resilience can come from a well-governed federation, not just from a bigger fortress.
+From "Point-in-Time" to "Lifecycle": Most systems think about events as isolated points in time (e.g., an API call, a user login). Your system thinks in terms of lifecycles—the entire causal chain from the origination of authority (the Grant), to its use (the PoAR), to its result (the VOR), and its termination (revocation). This requires a shift from static, state-based thinking to dynamic, event-sourced, systems thinking.
+Your core challenge is not to teach them about cryptography; it is to teach them a new way to see the structure of trust and value in a networked world.
+
+For Insurance/Audit/Regulatory (The Acceptance Layer)
+Biggest hurdle: Understanding that receipts can be binding evidence rather than just "nice documentation."
+They're used to: PDFs, screenshots, manual attestations, trusted third-party reports
+They need to learn: Cryptographic receipts with tamper-evidence can actually reduce their verification costs and legal risk
+Education approach: Show them the cost delta. "This receipt format cuts dispute resolution time from 6 weeks to 6 days because the evidence is self-verifying and the chain of custody is cryptographically assured."
+
+For Enterprise IT/DevOps (The Integration Layer)
+Biggest hurdle: Thinking this is "just another compliance framework" instead of seeing it as infrastructure that pays for itself.
+They're used to: Compliance as pure cost center; logs that live in silos; audit prep as manual hell
+They need to learn: Receipts that flow automatically into insurance/audit processes can actually reduce their operational burden
+Education approach: "Your CI/CD pipeline already generates logs. We're just changing the format so those logs automatically satisfy your SOC2 auditor AND reduce your cyber insurance premium."
+
+For OT/Industrial (The Resource Edge)
+Biggest hurdle: Fear that "blockchain/crypto stuff" is complex, unreliable, or inappropriate for critical systems.
+They're used to: Simple, deterministic control systems; "if it ain't broke, don't fix it"
+They need to learn: This makes their existing systems more reliable by providing better fault detection and automated compliance
+Education approach: "This isn't replacing your PLC logic. It's just adding a receipt printer to prove your demand response actually happened, so you get paid faster."
+
+For Financial/Legal Teams (The Settlement Layer)
+Biggest hurdle: Understanding how cryptographic proofs map to legal admissibility and contract enforcement.
+They're used to: Traditional evidence rules; notarized documents; expert witnesses
+They need to learn: How digital signatures and hash chains can be stronger evidence than traditional methods
+Education approach: "This receipt is like a notarized document, but the 'notary' is mathematics instead of a human, so it can't be bribed or make mistakes."
+
+The Meta-Hurdle: Category Creation
+The deepest challenge is that you're creating a new category: "Settlement-grade operational evidence."
+People will try to fit this into existing mental models:
+"It's just better logging" (IT perspective)
+"It's blockchain for enterprise" (crypto perspective)
+"It's another audit tool" (compliance perspective)
+"It's IoT data management" (OT perspective)
+None of these framings capture the real value: turning operational events into financial/legal instruments.
+
+## Capability vs Tokens (CP vs DP)
+
+Hurdle: “Bearer tokens are enough” vs “Asymmetric-only purity.”
+Fix: Control-plane = identity-bound capabilities (CapTok + Presentation); data-plane = symmetric session efficiency. Mediate/Derive/Reveal modes make this safe in the real world. Don’t fight the dualism—govern it, then prove it.
+
+“This replaces IAM.” No—capabilities bridge IAM/OPA across boundaries and produce receipts.
+
+The single biggest educational hurdle is convincing each party that your system is not just theoretically better, but practically superior at solving a problem they are paid to solve today. They don't care about the grand narrative until you can prove it reduces their immediate friction or increases their immediate profit.
+Here are the specific hurdles and the plays to overcome them:
+For Developers: The "Friction vs. Reward" Hurdle.
+Their Default: "This sounds complicated. A JWT and a log entry is faster. My job is to ship features, not to re-architect global trust."
+The Education Needed: You must prove that your "Trojan Horse" (the vault) is a better, faster, more secure way to handle their immediate secret management pain than their current workflow. Only then will they be receptive to the "vitamin" of receipts. The hurdle is overcoming their justifiable intolerance for new friction.
+For CISOs & Compliance: The "Checklist vs. Reality" Hurdle.
+Their Default: "This isn't in my SOC2/ISO 27001 checklist. Where do I put this in my risk register? My auditor has never heard of a 'Verifiable Outcome Receipt'."
+The Education Needed: You must provide them with the exact language and evidence to satisfy their auditors. This is where the Receipt Acceptance Memo (RAM) is your weapon. You don't teach them the whole system; you give them the signed memo from an auditor that says, "This is an acceptable form of evidence for control XY-1." The hurdle is bridging the gap between your advanced system and their legacy compliance framework.
+For Insurers & Financiers: The "Actuarial vs. Evidentiary" Hurdle.
+Their Default: "Our models are based on statistical losses over time. We don't know how to price a 'cryptographic receipt'."
+The Education Needed: You must show them, with a concrete pilot, how your receipts reduce their single biggest cost: dispute resolution and fraud investigation. Frame it in their language: "Our receipts reduce loss adjustment expenses by 50% for this class of claims." The hurdle is translating cryptographic integrity into a measurable reduction in financial risk.
+Your educational strategy must be ruthlessly pragmatic. Lead with a product that solves an immediate pain, and provide pre-packaged "translation layers" (like the RAM) that allow each stakeholder to plug your superior system into their existing, imperfect worldview.
+
+## Compliance vs Composability
+
+Hurdle: “Who says your receipts count?”
+Fix: TAP is the rulebook; RAM is the co-signed letter from the payer. One RAM per wedge flips the market. This is not “trust us,” it’s “they accept this for money/compliance.”
+
+The biggest educational hurdle is overcoming a deep-seated human bias: people trust familiar processes, even when they know they are broken. You are not just selling a new technology; you are asking people to change how they think about proof, trust, and agreement.
+Here are the human-centric hurdles you need to navigate:
+The "Who Do I Sue?" Hurdle: Centralized systems provide a clear "throat to choke." If something goes wrong with your bank, you know who to call. A decentralized, federated network feels amorphous and risky to many business leaders.
+The Education Needed: Your narrative must emphasize the "Accredited" part of the ATN. You need to tell a story about a well-governed ecosystem with clear roles, responsibilities, and a defined dispute resolution process (the "Dispute Ladder"). You must show them that decentralization doesn't mean chaos; it means a different, more resilient form of order.
+The "Show Me, Don't Tell Me" Hurdle: The concepts of "capability tokens," "sigchains," and "verifiable receipts" are abstract. For most people, they are just noise until they see them solve a real, relatable problem.
+The Education Needed: You need a "Golden Demo"—a single, powerful, end-to-end story. The Zeta House identity wedge is perfect for this. The story is simple: "A new resident needs access. We verify their status without ever seeing their private documents. They get a temporary, revocable capability to open the door. Every access event creates an immutable receipt. When they move out, the capability is provably revoked." This is a story people can understand and feel.
+The "This Feels Like a Cult" Hurdle: When you talk about a grand, civilizational mission and a new economic physics, you risk sounding like a utopian out of touch with reality.
+The Education Needed: Your communication must be relentlessly grounded in the pragmatic and the profitable. Always start with the pain. "Managing access for a 50-unit building is a nightmare of lost keys and liability." "Settling a demand-response event takes 90 days of spreadsheet arguments." Lead with the mundane, painful reality, and then present your elegant, systemic solution. The grand narrative should be the context, not the opening line.
+
+## This is just a Blockchain
+
+“This is blockchain.” No—edge-native, off-chain, portable receipts. Optional hash anchors only.
+
+## This is Surveillance - Is there a Privacy Tradeoff?
+
+“This centralizes logs.” No—per-identity shards; selective replication; escrow pinning; ViewReceipts; no raw dumps.
+“This leaks PII.” No—claims are non-PII; evidence encrypted; redactions + crypto-erasure; TAP privacy.
+
diff --git a/docs/theory/receipt-rails-operational-flow.md b/docs/theory/receipt-rails-operational-flow.md
index aea0ee5c..3556adec 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<br>this is effectively native (colocated)<br>bridging=false, PoAR still on P's sigchain
     S ->> P: Present capability (Presentation)
+    Note over P: Σ = verify(Presentation, Grant, Bind, channel, ttl,<br>attenuation?, lease?, allowed-surface?)
     break Verification fails at P
       Note over P: Deny path<br>Mint DenyReceipt with reason code<br>(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<br>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,<br>attenuation?)
     break Verification fails at R
       Note over R: Deny path<br>Mint DenyReceipt with reason code<br>(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,<br>attenuation?)
     break Verification fails at S
       Note over S: Deny path<br>Mint DenyReceipt with reason code<br>(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,<br>attenuation?, lease?, allowed-surface? for mediate)
     break Verification fails at S
       Note over S: Deny path<br>Mint DenyReceipt with reason code<br>(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 c38e53b0..eba6f797 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/sidebars.ts b/sidebars.ts
index c9134bd8..ee47fd4c 100644
--- a/sidebars.ts
+++ b/sidebars.ts
@@ -77,6 +77,7 @@ const sidebars: SidebarsConfig = {
         id: 'theory/README',
       },
       items: [
+        'theory/clearing-mental-hurdles',
         'theory/trust-operating-system',
         'theory/receipt-rails-operational-flow',
         'theory/secrets-management',
@@ -94,6 +95,17 @@ const sidebars: SidebarsConfig = {
         id: 'reference/README',
       },
       items: [
+        {
+          type: 'category',
+          label: 'Specifications',
+          link: {
+            type: 'doc',
+            id: 'reference/specifications/README'
+          },
+          items: [
+            'reference/specifications/cap/CAP-01'
+          ],
+        },
         {
           type: 'category',
           label: 'Architecture',

From e91f85d175f306a4db68e4bdf30485183805c855 Mon Sep 17 00:00:00 2001
From: Roger Qiu <roger.qiu@polyhack.io>
Date: Tue, 2 Sep 2025 21:04:47 +1000
Subject: [PATCH 2/9] wip: clearing mental hurdles

---
 docs/reference/specifications/cap/CAP-01.mdx | 170 ++++++---
 docs/theory/clearing-mental-hurdles.md       | 350 ++++++++++++++-----
 flake.lock                                   |  14 +-
 flake.nix                                    |   2 +-
 4 files changed, 380 insertions(+), 156 deletions(-)

diff --git a/docs/reference/specifications/cap/CAP-01.mdx b/docs/reference/specifications/cap/CAP-01.mdx
index 70677d25..71f59f66 100644
--- a/docs/reference/specifications/cap/CAP-01.mdx
+++ b/docs/reference/specifications/cap/CAP-01.mdx
@@ -3,41 +3,63 @@
 <details>
   <summary>Metadata</summary>
   <dl>
-    <dt>Status:</dt><dd>Draft</dd>
-    <dt>Edition:</dt><dd>2025-09-02</dd>
-    <dt>Extends:</dt><dd>-</dd>
-    <dt>Updates:</dt><dd>-</dd>
-    <dt>Obsoletes:</dt><dd>-</dd>
-    <dt>Depends on:</dt><dd>SIGCHAIN-01, RSC-01, PRIVACY-01</dd>
+    <dt>Status:</dt>
+    <dd>Draft</dd>
+    <dt>Edition:</dt>
+    <dd>2025-09-02</dd>
+    <dt>Extends:</dt>
+    <dd>-</dd>
+    <dt>Updates:</dt>
+    <dd>-</dd>
+    <dt>Obsoletes:</dt>
+    <dd>-</dd>
+    <dt>Depends on:</dt>
+    <dd>SIGCHAIN-01, RSC-01, PRIVACY-01</dd>
   </dl>
 </details>
 
 ## Abstract
 
-CAP-01 defines the portable, verifiable capability model used by Polykey to express delegated authority. It specifies the structure and semantics of Grants (capability tokens) and Presentations (ephemeral proofs of capability), including verbs, resource addressing, binding constraints, attenuation, and revocation. CAP-01 ensures capabilities are composable, attenuable (never broadened), and safely enforceable at CEPs (Capability Enforcement Points), producing settlement-grade receipts (RSC-01).
+CAP-01 defines the portable, verifiable capability model used by Polykey to
+express delegated authority. It specifies the structure and semantics of Grants
+(capability tokens) and Presentations (ephemeral proofs of capability),
+including verbs, resource addressing, binding constraints, attenuation, and
+revocation. CAP-01 ensures capabilities are composable, attenuable (never
+broadened), and safely enforceable at CEPs (Capability Enforcement Points),
+producing settlement-grade receipts (RSC-01).
 
 ## Terminology
 
 - Principal (P): Originator of authority; issues a Grant to a Subject.
 - Subject (S): Holder that exercises the capability by creating a Presentation.
 - Resource (R): Target of the action; may host a native CEP (CEP(R)).
-- CEP: Capability Enforcement Point at P/S/R that verifies Presentations and enforces capabilities (writes the Access PoAR).
+- CEP: Capability Enforcement Point at P/S/R that verifies Presentations and
+  enforces capabilities (writes the Access PoAR).
 - Grant (G): A signed, portable capability issued by P to S.
-- Presentation (Π): An ephemeral, proof-of-possession token created by S that references a Grant with context and channel binding. Not stored on-chain.
-- Bind: Binding constraints inside a Grant that restrict its use (audience, purpose, time, context, etc.).
-- Attenuation: Narrowing a capability when delegating; derived Grants must be a subset of their parent capability.
-- Verification (Σ): The verification handshake at the enforcing CEP. `Σ = verify(Π, G, Bind, Channel, TTL, Attenuation?, Lease?)`
-- Lease: The upstream authority relationship to a non-native SoA; referenced via leaseRef in PoAR (RSC-01).
+- Presentation (Π): An ephemeral, proof-of-possession token created by S that
+  references a Grant with context and channel binding. Not stored on-chain.
+- Bind: Binding constraints inside a Grant that restrict its use (audience,
+  purpose, time, context, etc.).
+- Attenuation: Narrowing a capability when delegating; derived Grants must be a
+  subset of their parent capability.
+- Verification (Σ): The verification handshake at the enforcing CEP.
+  `Σ = verify(Π, G, Bind, Channel, TTL, Attenuation?, Lease?)`
+- Lease: The upstream authority relationship to a non-native SoA; referenced via
+  leaseRef in PoAR (RSC-01).
 - PoAR: Proof-of-Action receipt written by the enforcing CEP (RSC-01).
 
 ## Overview and Goals
 
 CAP-01 provides:
 
-- A minimal, expressive grammar for capabilities (verbs over resources with constraints).
-- A binding system (Bind) to tie capability use to audience, purpose, context, and time.
-- A safe delegation model: capabilities can be attenuated and re-delegated without ever broadening power.
-- A secure, ephemeral Presentation that is resistant to theft and replay (PoP + channel binding).
+- A minimal, expressive grammar for capabilities (verbs over resources with
+  constraints).
+- A binding system (Bind) to tie capability use to audience, purpose, context,
+  and time.
+- A safe delegation model: capabilities can be attenuated and re-delegated
+  without ever broadening power.
+- A secure, ephemeral Presentation that is resistant to theft and replay (PoP +
+  channel binding).
 - Clear interoperability with CEP enforcement and receipt minting (RSC-01).
 
 Design goals:
@@ -45,7 +67,8 @@ Design goals:
 - Portable: Grants and Presentations are verifiable across boundaries.
 - Minimal: Core fields are few and clearly defined; extensions via vocabularies.
 - Attenuable: Derived Grants must shrink authority; verifiable at enforcement.
-- Secure by default: Holder-of-key + channel binding; short TTLs for Presentations.
+- Secure by default: Holder-of-key + channel binding; short TTLs for
+  Presentations.
 - Receipt-ready: CEPS capture a bind_snapshot in PoAR.
 
 ## Verbs and Resources
@@ -62,7 +85,8 @@ Verbs are strings, recommended namespaced for clarity:
     - secret:read, secret:derive
     - data:export, model:infer
 
-Verb semantics must be documented in a public or private registry (with versioned definitions). TAP profiles may whitelist verb sets per domain.
+Verb semantics must be documented in a public or private registry (with
+versioned definitions). TAP profiles may whitelist verb sets per domain.
 
 ### Resource addressing
 
@@ -78,7 +102,8 @@ TAP profiles may restrict acceptable schemes per domain and verb.
 
 ## Grant Structure and Rules
 
-A Grant is a signed claim on P's sigchain that authorizes S to perform actions (verbs) on resources, subject to Bind constraints.
+A Grant is a signed claim on P's sigchain that authorizes S to perform actions
+(verbs) on resources, subject to Bind constraints.
 
 Required fields:
 
@@ -97,7 +122,8 @@ Normative rules:
 
 - Grants MUST be written on the issuer's (P's) sigchain.
 - expiry MUST be present and enforced; Presentations beyond expiry are invalid.
-- action/resource MUST be specific; wildcards SHOULD be avoided unless constrained by Bind.
+- action/resource MUST be specific; wildcards SHOULD be avoided unless
+  constrained by Bind.
 - bind MUST be enforceable by CEPs and included in the PoAR bind_snapshot.
 - A Grant MAY be revoked (Section 8).
 
@@ -118,19 +144,25 @@ Minimal JSON skeleton:
 }
 ```
 
-Bind constrains how a capability may be exercised. CEPs MUST enforce Bind and include a bind_snapshot in PoAR.
+Bind constrains how a capability may be exercised. CEPs MUST enforce Bind and
+include a bind_snapshot in PoAR.
 
 Recommended fields:
 
 - audience: list of DIDs of acceptable enforcers (e.g., ["did:pk:P","did:pk:R"])
-- purpose: semantic hash or descriptor of intent (e.g., hash of artifact H, “door-visit-123”)
-- context: structured k/v describing runtime context (e.g., `{"pod":"runner-xyz","ns":"ci"}`)
+- purpose: semantic hash or descriptor of intent (e.g., hash of artifact H,
+  “door-visit-123”)
+- context: structured k/v describing runtime context (e.g.,
+  `{"pod":"runner-xyz","ns":"ci"}`)
 - time_window: `{ notBefore, notAfter }` narrower than Grant expiry
 - ttl: maximum Presentation TTL (e.g., "120s")
-- maxUses: optional counter for total uses (enforced by CEP capable of maintaining state)
+- maxUses: optional counter for total uses (enforced by CEP capable of
+  maintaining state)
 - geofence / net: optional constraints (e.g., CIDR, region, location)
 
-Subset rule (for attenuation, Section 6): child.bind MUST be a subset (narrower or equal) of parent.bind on every dimension (audience, purpose scope, time, ttl, etc.).
+Subset rule (for attenuation, Section 6): child.bind MUST be a subset (narrower
+or equal) of parent.bind on every dimension (audience, purpose scope, time, ttl,
+etc.).
 
 ```json
 "bind": {
@@ -144,12 +176,15 @@ Subset rule (for attenuation, Section 6): child.bind MUST be a subset (narrower
 
 ## Attenuation and Delegation
 
-A capability MAY be delegated by S to S2 by issuing a derived Grant on the delegator's sigchain, provided:
+A capability MAY be delegated by S to S2 by issuing a derived Grant on the
+delegator's sigchain, provided:
 
 - The derived Grant's action/resource are identical or narrower (subset).
-- The derived Grant's bind is a subset of the parent Grant's bind on all dimensions.
+- The derived Grant's bind is a subset of the parent Grant's bind on all
+  dimensions.
 - The chain of custody (P → S → S2) is provable via sigchains.
-- No broadening: delegation MUST NOT increase the set of allowed enforcers, time, scope, or resource coverage.
+- No broadening: delegation MUST NOT increase the set of allowed enforcers,
+  time, scope, or resource coverage.
 
 Normative subset checks (examples):
 
@@ -157,30 +192,41 @@ Normative subset checks (examples):
 - `audience.child` ⊆ `audience.parent`
 - `ttl.child` ≤ `ttl.parent`
 - `resource.child` narrower (e.g., specific door vs building-wide)
-- `purpose.child` equals or narrower (e.g., same artifact hash or a stricter descriptor)
+- `purpose.child` equals or narrower (e.g., same artifact hash or a stricter
+  descriptor)
 
-CEPs SHOULD verify chain attenuation if presented with a chain (Grant_ref may include a chain; otherwise, single-hop P→S is verified).
+CEPs SHOULD verify chain attenuation if presented with a chain (Grant_ref may
+include a chain; otherwise, single-hop P→S is verified).
 
 ## Presentation
 
-A Presentation is an ephemeral proof by S that it holds a Grant and is using it now, in this context, on this channel. Presentations are NOT written to sigchains.
+A Presentation is an ephemeral proof by S that it holds a Grant and is using it
+now, in this context, on this channel. Presentations are NOT written to
+sigchains.
 
 Required fields:
+
 - grant_ref: hash of Grant (or terminal of a chain)
 - holder: DID of S
 - pop_sig: signature by S’s private key over the presentation payload
-- channelBinding: exporter-derived key for the live TLS/mTLS session (or equivalent)
+- channelBinding: exporter-derived key for the live TLS/mTLS session (or
+  equivalent)
 - ctx: runtime context (subset of bind.context)
 - ttl: small (e.g., 120s)
 - nonce: unique value to prevent replay
 
 Normative rules:
-- Presentations MUST be bound to holder’s key (PoP) and to the transport/session (channelBinding).
+
+- Presentations MUST be bound to holder’s key (PoP) and to the transport/session
+  (channelBinding).
 - Presentation ttl MUST be enforced by CEPs.
-- Presentations MUST include binding to Grant_ref and context; CEPs MUST check bind subset.
-- CEPs MUST reject Presentations beyond Grant expiry or outside bind.time_window.
+- Presentations MUST include binding to Grant_ref and context; CEPs MUST check
+  bind subset.
+- CEPs MUST reject Presentations beyond Grant expiry or outside
+  bind.time_window.
 
 Minimal JSON skeleton (often conveyed as a signed JWT/DSSE):
+
 ```
 {
   "type": "presentation",
@@ -197,42 +243,56 @@ Minimal JSON skeleton (often conveyed as a signed JWT/DSSE):
 ## 8. Revocation and rotation
 
 ### 8.1 Revocation
-A Grant MAY be revoked by its issuer with a signed revocation claim on P’s sigchain:
+
+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).
+- 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).
+
+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:
+
+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).
+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.
+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).
+- 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.
+- 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",
@@ -271,10 +331,14 @@ Presentation (S → CEP)
 
 ## Revision history
 
-- 2025-09-02: Initial draft edition (holder-of-key + channel binding; Bind subset rules; attenuation; revocation; CEP enforcement algorithm; examples).
+- 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.
+- 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/theory/clearing-mental-hurdles.md b/docs/theory/clearing-mental-hurdles.md
index 8247dc57..c95b026c 100644
--- a/docs/theory/clearing-mental-hurdles.md
+++ b/docs/theory/clearing-mental-hurdles.md
@@ -1,98 +1,258 @@
 # Clearing the Mental Hurdles
 
-## The Universal Hurdle (The One Thing Everyone Will Struggle With) (Security as Centralized Internal Problem vs Security as a Network/Utility)
-
-Before breaking it down by audience, it's crucial to name the single, universal educational hurdle that underpins all the others.
-
-The biggest hurdle is transitioning people's thinking from a Fortress Mentality to a Verifiable Ledger Mentality.
-
-- **The Fortress Mentality (The Old World):** "How do I build walls to prevent bad things from happening?" This worldview is about prevention, perimeters, and control. Risk is managed by trying to achieve a perfect, static state of security. This is the world of firewalls, antivirus, and centralized access control.
-- **The Verifiable Ledger Mentality (Your New World):** "Bad things (and good things) are inevitable. How do I create an indisputable, portable, and settlement-grade record of what actually happened?" This worldview is about proof, resilience, and accountability. Risk is managed by making the system transparent, auditable, and capable of rapid, fair settlement after an event.
-
-Every conversation you have is, at its core, an attempt to pull someone from the first worldview into the second.
-
-## Logging vs Receipts - The Value of Tradable Assets in a Network
-
-The biggest educational hurdle for all parties is understanding that you are not selling them a product; you are introducing them to a new economic and operational physics. Their existing mental models are insufficient because they are based on a world of centralized, high-trust, and opaque systems.
-Here are the specific conceptual leaps you must guide them through:
-From "Data" to "Asset": The most difficult shift is getting people to see a "receipt" not as a piece of data (like a log entry), but as a negotiable, valuable, and self-contained asset. A log is a liability to be stored; a receipt is an asset to be traded, insured, or settled. This requires them to mentally move from the world of IT (managing data) to the world of finance (managing assets).
-From "Centralized Control" to "Federated Governance": Stakeholders, especially CISOs and regulators, are conditioned to think in terms of a central authority (a PDP, a root CA, a government body). Your model of an Accredited Trust Network (ATN) is a federated one, where trust is an emergent property of a network of peers adhering to a shared standard (the TAP). The hurdle is teaching them that resilience can come from a well-governed federation, not just from a bigger fortress.
-From "Point-in-Time" to "Lifecycle": Most systems think about events as isolated points in time (e.g., an API call, a user login). Your system thinks in terms of lifecycles—the entire causal chain from the origination of authority (the Grant), to its use (the PoAR), to its result (the VOR), and its termination (revocation). This requires a shift from static, state-based thinking to dynamic, event-sourced, systems thinking.
-Your core challenge is not to teach them about cryptography; it is to teach them a new way to see the structure of trust and value in a networked world.
-
-For Insurance/Audit/Regulatory (The Acceptance Layer)
-Biggest hurdle: Understanding that receipts can be binding evidence rather than just "nice documentation."
-They're used to: PDFs, screenshots, manual attestations, trusted third-party reports
-They need to learn: Cryptographic receipts with tamper-evidence can actually reduce their verification costs and legal risk
-Education approach: Show them the cost delta. "This receipt format cuts dispute resolution time from 6 weeks to 6 days because the evidence is self-verifying and the chain of custody is cryptographically assured."
-
-For Enterprise IT/DevOps (The Integration Layer)
-Biggest hurdle: Thinking this is "just another compliance framework" instead of seeing it as infrastructure that pays for itself.
-They're used to: Compliance as pure cost center; logs that live in silos; audit prep as manual hell
-They need to learn: Receipts that flow automatically into insurance/audit processes can actually reduce their operational burden
-Education approach: "Your CI/CD pipeline already generates logs. We're just changing the format so those logs automatically satisfy your SOC2 auditor AND reduce your cyber insurance premium."
-
-For OT/Industrial (The Resource Edge)
-Biggest hurdle: Fear that "blockchain/crypto stuff" is complex, unreliable, or inappropriate for critical systems.
-They're used to: Simple, deterministic control systems; "if it ain't broke, don't fix it"
-They need to learn: This makes their existing systems more reliable by providing better fault detection and automated compliance
-Education approach: "This isn't replacing your PLC logic. It's just adding a receipt printer to prove your demand response actually happened, so you get paid faster."
-
-For Financial/Legal Teams (The Settlement Layer)
-Biggest hurdle: Understanding how cryptographic proofs map to legal admissibility and contract enforcement.
-They're used to: Traditional evidence rules; notarized documents; expert witnesses
-They need to learn: How digital signatures and hash chains can be stronger evidence than traditional methods
-Education approach: "This receipt is like a notarized document, but the 'notary' is mathematics instead of a human, so it can't be bribed or make mistakes."
-
-The Meta-Hurdle: Category Creation
-The deepest challenge is that you're creating a new category: "Settlement-grade operational evidence."
-People will try to fit this into existing mental models:
-"It's just better logging" (IT perspective)
-"It's blockchain for enterprise" (crypto perspective)
-"It's another audit tool" (compliance perspective)
-"It's IoT data management" (OT perspective)
-None of these framings capture the real value: turning operational events into financial/legal instruments.
-
-## Capability vs Tokens (CP vs DP)
-
-Hurdle: “Bearer tokens are enough” vs “Asymmetric-only purity.”
-Fix: Control-plane = identity-bound capabilities (CapTok + Presentation); data-plane = symmetric session efficiency. Mediate/Derive/Reveal modes make this safe in the real world. Don’t fight the dualism—govern it, then prove it.
-
-“This replaces IAM.” No—capabilities bridge IAM/OPA across boundaries and produce receipts.
-
-The single biggest educational hurdle is convincing each party that your system is not just theoretically better, but practically superior at solving a problem they are paid to solve today. They don't care about the grand narrative until you can prove it reduces their immediate friction or increases their immediate profit.
-Here are the specific hurdles and the plays to overcome them:
-For Developers: The "Friction vs. Reward" Hurdle.
-Their Default: "This sounds complicated. A JWT and a log entry is faster. My job is to ship features, not to re-architect global trust."
-The Education Needed: You must prove that your "Trojan Horse" (the vault) is a better, faster, more secure way to handle their immediate secret management pain than their current workflow. Only then will they be receptive to the "vitamin" of receipts. The hurdle is overcoming their justifiable intolerance for new friction.
-For CISOs & Compliance: The "Checklist vs. Reality" Hurdle.
-Their Default: "This isn't in my SOC2/ISO 27001 checklist. Where do I put this in my risk register? My auditor has never heard of a 'Verifiable Outcome Receipt'."
-The Education Needed: You must provide them with the exact language and evidence to satisfy their auditors. This is where the Receipt Acceptance Memo (RAM) is your weapon. You don't teach them the whole system; you give them the signed memo from an auditor that says, "This is an acceptable form of evidence for control XY-1." The hurdle is bridging the gap between your advanced system and their legacy compliance framework.
-For Insurers & Financiers: The "Actuarial vs. Evidentiary" Hurdle.
-Their Default: "Our models are based on statistical losses over time. We don't know how to price a 'cryptographic receipt'."
-The Education Needed: You must show them, with a concrete pilot, how your receipts reduce their single biggest cost: dispute resolution and fraud investigation. Frame it in their language: "Our receipts reduce loss adjustment expenses by 50% for this class of claims." The hurdle is translating cryptographic integrity into a measurable reduction in financial risk.
-Your educational strategy must be ruthlessly pragmatic. Lead with a product that solves an immediate pain, and provide pre-packaged "translation layers" (like the RAM) that allow each stakeholder to plug your superior system into their existing, imperfect worldview.
-
-## Compliance vs Composability
-
-Hurdle: “Who says your receipts count?”
-Fix: TAP is the rulebook; RAM is the co-signed letter from the payer. One RAM per wedge flips the market. This is not “trust us,” it’s “they accept this for money/compliance.”
-
-The biggest educational hurdle is overcoming a deep-seated human bias: people trust familiar processes, even when they know they are broken. You are not just selling a new technology; you are asking people to change how they think about proof, trust, and agreement.
-Here are the human-centric hurdles you need to navigate:
-The "Who Do I Sue?" Hurdle: Centralized systems provide a clear "throat to choke." If something goes wrong with your bank, you know who to call. A decentralized, federated network feels amorphous and risky to many business leaders.
-The Education Needed: Your narrative must emphasize the "Accredited" part of the ATN. You need to tell a story about a well-governed ecosystem with clear roles, responsibilities, and a defined dispute resolution process (the "Dispute Ladder"). You must show them that decentralization doesn't mean chaos; it means a different, more resilient form of order.
-The "Show Me, Don't Tell Me" Hurdle: The concepts of "capability tokens," "sigchains," and "verifiable receipts" are abstract. For most people, they are just noise until they see them solve a real, relatable problem.
-The Education Needed: You need a "Golden Demo"—a single, powerful, end-to-end story. The Zeta House identity wedge is perfect for this. The story is simple: "A new resident needs access. We verify their status without ever seeing their private documents. They get a temporary, revocable capability to open the door. Every access event creates an immutable receipt. When they move out, the capability is provably revoked." This is a story people can understand and feel.
-The "This Feels Like a Cult" Hurdle: When you talk about a grand, civilizational mission and a new economic physics, you risk sounding like a utopian out of touch with reality.
-The Education Needed: Your communication must be relentlessly grounded in the pragmatic and the profitable. Always start with the pain. "Managing access for a 50-unit building is a nightmare of lost keys and liability." "Settling a demand-response event takes 90 days of spreadsheet arguments." Lead with the mundane, painful reality, and then present your elegant, systemic solution. The grand narrative should be the context, not the opening line.
-
-## This is just a Blockchain
-
-“This is blockchain.” No—edge-native, off-chain, portable receipts. Optional hash anchors only.
-
-## This is Surveillance - Is there a Privacy Tradeoff?
-
-“This centralizes logs.” No—per-identity shards; selective replication; escrow pinning; ViewReceipts; no raw dumps.
-“This leaks PII.” No—claims are non-PII; evidence encrypted; redactions + crypto-erasure; TAP privacy.
+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/flake.lock b/flake.lock
index 5c7bdc98..cf872697 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 e66a6a68..86d1d866 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

From 8febbe7e6c61e7a9b8f5e2ec0a6363f716a4d59b Mon Sep 17 00:00:00 2001
From: Roger Qiu <roger.qiu@polyhack.io>
Date: Tue, 2 Sep 2025 21:06:28 +1000
Subject: [PATCH 3/9] wip: clearing mental hurdles

---
 .../{clearing-mental-hurdles.md => clarifying-mental-models.md} | 2 +-
 sidebars.ts                                                     | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)
 rename docs/theory/{clearing-mental-hurdles.md => clarifying-mental-models.md} (99%)

diff --git a/docs/theory/clearing-mental-hurdles.md b/docs/theory/clarifying-mental-models.md
similarity index 99%
rename from docs/theory/clearing-mental-hurdles.md
rename to docs/theory/clarifying-mental-models.md
index c95b026c..24e03e65 100644
--- a/docs/theory/clearing-mental-hurdles.md
+++ b/docs/theory/clarifying-mental-models.md
@@ -1,4 +1,4 @@
-# Clearing the Mental Hurdles
+# 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
diff --git a/sidebars.ts b/sidebars.ts
index ee47fd4c..9215da64 100644
--- a/sidebars.ts
+++ b/sidebars.ts
@@ -77,7 +77,7 @@ const sidebars: SidebarsConfig = {
         id: 'theory/README',
       },
       items: [
-        'theory/clearing-mental-hurdles',
+        'theory/clarifying-mental-models',
         'theory/trust-operating-system',
         'theory/receipt-rails-operational-flow',
         'theory/secrets-management',

From 6d7e7047b1401ca21a6678ee25c2903996a9357c Mon Sep 17 00:00:00 2001
From: Roger Qiu <roger.qiu@polyhack.io>
Date: Thu, 4 Sep 2025 22:09:13 +1000
Subject: [PATCH 4/9] wip: iterating PCAP-01

---
 docs/reference/specifications/cap/CAP-01.mdx  | 344 ---------------
 .../specifications/capabilities/PCAP-01.mdx   | 399 ++++++++++++++++++
 sidebars.ts                                   |   2 +-
 3 files changed, 400 insertions(+), 345 deletions(-)
 delete mode 100644 docs/reference/specifications/cap/CAP-01.mdx
 create mode 100644 docs/reference/specifications/capabilities/PCAP-01.mdx

diff --git a/docs/reference/specifications/cap/CAP-01.mdx b/docs/reference/specifications/cap/CAP-01.mdx
deleted file mode 100644
index 71f59f66..00000000
--- a/docs/reference/specifications/cap/CAP-01.mdx
+++ /dev/null
@@ -1,344 +0,0 @@
-# CAP-01 - Capability Grammar
-
-<details>
-  <summary>Metadata</summary>
-  <dl>
-    <dt>Status:</dt>
-    <dd>Draft</dd>
-    <dt>Edition:</dt>
-    <dd>2025-09-02</dd>
-    <dt>Extends:</dt>
-    <dd>-</dd>
-    <dt>Updates:</dt>
-    <dd>-</dd>
-    <dt>Obsoletes:</dt>
-    <dd>-</dd>
-    <dt>Depends on:</dt>
-    <dd>SIGCHAIN-01, RSC-01, PRIVACY-01</dd>
-  </dl>
-</details>
-
-## Abstract
-
-CAP-01 defines the portable, verifiable capability model used by Polykey to
-express delegated authority. It specifies the structure and semantics of Grants
-(capability tokens) and Presentations (ephemeral proofs of capability),
-including verbs, resource addressing, binding constraints, attenuation, and
-revocation. CAP-01 ensures capabilities are composable, attenuable (never
-broadened), and safely enforceable at CEPs (Capability Enforcement Points),
-producing settlement-grade receipts (RSC-01).
-
-## Terminology
-
-- Principal (P): Originator of authority; issues a Grant to a Subject.
-- Subject (S): Holder that exercises the capability by creating a Presentation.
-- Resource (R): Target of the action; may host a native CEP (CEP(R)).
-- CEP: Capability Enforcement Point at P/S/R that verifies Presentations and
-  enforces capabilities (writes the Access PoAR).
-- Grant (G): A signed, portable capability issued by P to S.
-- Presentation (Π): An ephemeral, proof-of-possession token created by S that
-  references a Grant with context and channel binding. Not stored on-chain.
-- Bind: Binding constraints inside a Grant that restrict its use (audience,
-  purpose, time, context, etc.).
-- Attenuation: Narrowing a capability when delegating; derived Grants must be a
-  subset of their parent capability.
-- Verification (Σ): The verification handshake at the enforcing CEP.
-  `Σ = verify(Π, G, Bind, Channel, TTL, Attenuation?, Lease?)`
-- Lease: The upstream authority relationship to a non-native SoA; referenced via
-  leaseRef in PoAR (RSC-01).
-- PoAR: Proof-of-Action receipt written by the enforcing CEP (RSC-01).
-
-## Overview and Goals
-
-CAP-01 provides:
-
-- A minimal, expressive grammar for capabilities (verbs over resources with
-  constraints).
-- A binding system (Bind) to tie capability use to audience, purpose, context,
-  and time.
-- A safe delegation model: capabilities can be attenuated and re-delegated
-  without ever broadening power.
-- A secure, ephemeral Presentation that is resistant to theft and replay (PoP +
-  channel binding).
-- Clear interoperability with CEP enforcement and receipt minting (RSC-01).
-
-Design goals:
-
-- Portable: Grants and Presentations are verifiable across boundaries.
-- Minimal: Core fields are few and clearly defined; extensions via vocabularies.
-- Attenuable: Derived Grants must shrink authority; verifiable at enforcement.
-- Secure by default: Holder-of-key + channel binding; short TTLs for
-  Presentations.
-- Receipt-ready: CEPS capture a bind_snapshot in PoAR.
-
-## Verbs and Resources
-
-### Verb grammar
-
-Verbs are strings, recommended namespaced for clarity:
-
-- Format: namespace:verb or domain:action
-  - Examples:
-    - deploy:to_env
-    - access:open
-    - energy:curtail
-    - secret:read, secret:derive
-    - data:export, model:infer
-
-Verb semantics must be documented in a public or private registry (with
-versioned definitions). TAP profiles may whitelist verb sets per domain.
-
-### Resource addressing
-
-Resources are 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`
-
-TAP profiles may restrict acceptable schemes per domain and verb.
-
-## Grant Structure and Rules
-
-A Grant is a signed claim on P's sigchain that authorizes S to perform actions
-(verbs) on resources, subject to Bind constraints.
-
-Required fields:
-
-- id: opaque identifier (hash of canonicalized claim)
-- type: "grant"
-- issuer: DID of P
-- subject: DID of S
-- action: verb (string)
-- resource: resource URI
-- bind: Bind object (Section 5)
-- expiry: timestamp (notAfter)
-- prev: previous claim hash (sigchain link)
-- sig: signature by issuer's key
-
-Normative rules:
-
-- Grants MUST be written on the issuer's (P's) sigchain.
-- expiry MUST be present and enforced; Presentations beyond expiry are invalid.
-- action/resource MUST be specific; wildcards SHOULD be avoided unless
-  constrained by Bind.
-- bind MUST be enforceable by CEPs and included in the PoAR bind_snapshot.
-- A Grant MAY be revoked (Section 8).
-
-Minimal JSON skeleton:
-
-```json
-{
-  "type": "grant",
-  "id": "hash(...)",
-  "issuer": "did:pk:P",
-  "subject": "did:pk:S",
-  "action": "deploy:to_env",
-  "resource": "k8s://ns/prod",
-  "bind": { ... },
-  "expiry": "2025-09-10T10:00:00Z",
-  "prev": "hash(prev)",
-  "sig": "..."
-}
-```
-
-Bind constrains how a capability may be exercised. CEPs MUST enforce Bind and
-include a bind_snapshot in PoAR.
-
-Recommended fields:
-
-- audience: list of DIDs of acceptable enforcers (e.g., ["did:pk:P","did:pk:R"])
-- purpose: semantic hash or descriptor of intent (e.g., hash of artifact H,
-  “door-visit-123”)
-- context: structured k/v describing runtime context (e.g.,
-  `{"pod":"runner-xyz","ns":"ci"}`)
-- time_window: `{ notBefore, notAfter }` narrower than Grant expiry
-- ttl: maximum Presentation TTL (e.g., "120s")
-- maxUses: optional counter for total uses (enforced by CEP capable of
-  maintaining state)
-- geofence / net: optional constraints (e.g., CIDR, region, location)
-
-Subset rule (for attenuation, Section 6): child.bind MUST be a subset (narrower
-or equal) of parent.bind on every dimension (audience, purpose scope, time, ttl,
-etc.).
-
-```json
-"bind": {
-  "audience": ["did:pk:P"],
-  "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"
-}
-```
-
-## Attenuation and Delegation
-
-A capability MAY be delegated by S to S2 by issuing a derived Grant on the
-delegator's sigchain, provided:
-
-- The derived Grant's action/resource are identical or narrower (subset).
-- The derived Grant's bind is a subset of the parent Grant's bind on all
-  dimensions.
-- The chain of custody (P → S → S2) is provable via sigchains.
-- No broadening: delegation MUST NOT increase the set of allowed enforcers,
-  time, scope, or resource coverage.
-
-Normative subset checks (examples):
-
-- `time_window.child` ⊆ `time_window.parent`
-- `audience.child` ⊆ `audience.parent`
-- `ttl.child` ≤ `ttl.parent`
-- `resource.child` narrower (e.g., specific door vs building-wide)
-- `purpose.child` equals or narrower (e.g., same artifact hash or a stricter
-  descriptor)
-
-CEPs SHOULD verify chain attenuation if presented with a chain (Grant_ref may
-include a chain; otherwise, single-hop P→S is verified).
-
-## Presentation
-
-A Presentation is an ephemeral proof by S that it holds a Grant and is using it
-now, in this context, on this channel. Presentations are NOT written to
-sigchains.
-
-Required fields:
-
-- grant_ref: hash of Grant (or terminal of a chain)
-- holder: DID of S
-- pop_sig: signature by S’s private key over the presentation payload
-- channelBinding: exporter-derived key for the live TLS/mTLS session (or
-  equivalent)
-- ctx: runtime context (subset of bind.context)
-- ttl: small (e.g., 120s)
-- nonce: unique value to prevent replay
-
-Normative rules:
-
-- Presentations MUST be bound to holder’s key (PoP) and to the transport/session
-  (channelBinding).
-- Presentation ttl MUST be enforced by CEPs.
-- Presentations MUST include binding to Grant_ref and context; CEPs MUST check
-  bind subset.
-- CEPs MUST reject Presentations beyond Grant expiry or outside
-  bind.time_window.
-
-Minimal JSON skeleton (often conveyed as a signed JWT/DSSE):
-
-```
-{
-  "type": "presentation",
-  "grant_ref": "hash(G)",
-  "holder": "did:pk:S",
-  "channelBinding": "base64url(exporter)",
-  "ctx": { "ns": "ci", "pod": "runner-xyz" },
-  "ttl": "120s",
-  "nonce": "uuid-...",
-  "pop_sig": "sig_by_S"
-}
-```
-
-## 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/capabilities/PCAP-01.mdx b/docs/reference/specifications/capabilities/PCAP-01.mdx
new file mode 100644
index 00000000..46ce57f5
--- /dev/null
+++ b/docs/reference/specifications/capabilities/PCAP-01.mdx
@@ -0,0 +1,399 @@
+# PCAP-01 - Polykey Capability Grammar
+
+<details>
+  <summary>Metadata</summary>
+  <dl>
+    <dt>Status:</dt>
+    <dd>Draft</dd>
+    <dt>Edition:</dt>
+    <dd>2025-09-04</dd>
+    <dt>Extends:</dt>
+    <dd>-</dd>
+    <dt>Updates:</dt>
+    <dd>-</dd>
+    <dt>Obsoletes:</dt>
+    <dd>-</dd>
+    <dt>Depends on:</dt>
+    <dd>SIGCHAIN-01, PRSC-01, PRIVACY-01</dd>
+  </dl>
+</details>
+
+## Abstract
+
+PCAP-01 defines the portable, verifiable capability model used by the Polykey to express delegated authority. It specifies the structure and semantics of identity-bound authority Grants (capability tokens) and Presentations (ephemeral proofs of capability), including verbs, resource addressing, binding constraints, attenuation, and revocation. PCAP-01 ensures capabilities are composable, attenuable (never broadened), aggregable, and safely verifiable at enforcement points. Enforcement behavior, receipt formats, channel-binding profiles, and lease rotation are specified in separate documents; this document defines the core data model and verification semantics.
+
+## 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 signed, portable capability token issued by P to S.
+- **Presentation (Π):** An ephemeral, proof-of-possession token created by S that references a Grant with context and channel binding. It is NOT stored on-chain.
+- **Bind:** Binding constraints inside a Grant that restrict its use (e.g., audience, purpose, time, context, channel).
+- **Attenuation:** The act of narrowing a capability when delegating. A derived Grant MUST be a subset of its parent capability.
+- **Verification (Σ):** The set of checks performed by a CEP to validate a Presentation against a Grant and its Bind constraints. As shown in diagrams, this is represented as: `Σ = verify(Π, G, Bind, Channel, TTL, Attenuation?, Lease?)`. A successful verification implicitly establishes a session for enforcement.
+- **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.
+- **Access PoAR:** The Proof-of-Action receipt written by the enforcing CEP (defined in PRSC-01).
+- **Caveat:** A declarative, safety-preserving constraint embedded in or referenced by a Grant. Caveats MUST be attenuating, decidable, bounded in runtime, and side-effect free. Evaluation is performed by CEPs. Unknown or unsupported caveats MUST cause deny unless a TAP explicitly specifies a safe fallback.
+- **Authority:** The identity-bound permission represented by a Grant; the effective authority for a use is the intersection of the Grants presented and any caveats.
+- **Secret:** A bearer credential (e.g., token/key) used in the data plane. Secret issuance/derivation/aggregation and exposure semantics are specified in the CEP/BA spec, not in PCAP-01.
+
+## Overview and Goals
+
+PCAP-01 provides the core capability model for Polykey: the data structures and verification semantics that allow independent parties to mint, hold, present, and verify capabilities across boundaries.
+
+What PCAP-01 defines:
+
+- A minimal, expressive grammar for capabilities: verbs over resources constrained by Bind.
+- Bind (binding constraints) to tie capability use to audience, purpose, time, context, and channel.
+- A safe delegation model: capabilities can be attenuated and re-delegated, but MUST NEVER broaden authority.
+- Ephemeral Presentations that are resistant to theft and replay via proof-of-possession and channel binding.
+- Verification semantics (Σ): the set of checks a CEP performs to validate a Presentation against a Grant and Bind.
+
+Design goals:
+
+- Portable: Grants and Presentations are verifiable across organizational and network boundaries.
+- Minimal: Core fields are few and clearly defined; extensibility via content-addressed vocabularies/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; explicit time windows.
+- Receipt-ready: Verification requires a stable Bind snapshot so that CEPs can record bind_snapshot in Access PoARs (per PRSC-01).
+
+Non-goals (out of scope for PCAP-01):
+
+- Enforcement placement/modes: CEP/BA placements (P/S/R) and mediate/derive/reveal semantics are specified in the CEP/BA spec.
+- Receipt schemas: All receipt formats (PoAR/VOR/View) are specified in PRSC-01.
+- Channel-binding mechanisms: Concrete binding profiles (e.g., TLS exporter, DPoP) are profiled elsewhere; PCAP-01 only requires a verified binding.
+- Lease lifecycle/rotation: Lease issuance and rotation policies are defined elsewhere; PCAP-01 only requires Lease freshness to be verified when Grants touch non-native SoA (enforced by CEP per TAP).
+- Global time/ordering: PCAP-01 does not require a global clock or total order. Acceptance (TAP) specifies clock sources and tolerances.
+- Transport and messaging: PCAP-01 is transport-agnostic.
+- Serialization and envelope formats (e.g., JSON+JWS, CBOR+COSE, DSSE) are out of scope; see binding profiles and SIGCHAIN-01 for canonicalization/signatures.
+- Caveat languages are out of scope; CAP only defines the caveats extension point and safety properties. TAP/binding profiles MAY specify concrete caveat profiles.
+- Secret derivation/aggregation cryptography and interactive evaluation flows are specified in the CEP/BA spec (not PCAP-01). PCAP-01 only models authority attenuation and (optional) composite/threshold caveats over Grants.
+
+## 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 PRSC-01), not in PCAP-01.
+- 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/sidebars.ts b/sidebars.ts
index 9215da64..e6d098f6 100644
--- a/sidebars.ts
+++ b/sidebars.ts
@@ -103,7 +103,7 @@ const sidebars: SidebarsConfig = {
             id: 'reference/specifications/README'
           },
           items: [
-            'reference/specifications/cap/CAP-01'
+            'reference/specifications/capabilities/PCAP-01'
           ],
         },
         {

From 774be66c2ef918b0b1b6a114953e28b0f6f74667 Mon Sep 17 00:00:00 2001
From: Roger Qiu <roger.qiu@polyhack.io>
Date: Tue, 16 Sep 2025 14:40:32 +1000
Subject: [PATCH 5/9] wip: iterating cap-01 to psp-1

---
 ... PSP-1 - Capability Model and Grammar.mdx} | 220 +++++++++++++++---
 .../specifications/PSP-2 - Receipt Model.mdx  |   1 +
 .../PSP-3 - Sigchain and Envelope.md          |   1 +
 .../TAP-01.mdx => PSP-6 - TAP.mdx}            |   0
 .../specifications/receipts/RSC-01.mdx        |   0
 docs/reference/wedges/README.md               |  37 +++
 6 files changed, 229 insertions(+), 30 deletions(-)
 rename docs/reference/specifications/{capabilities/PCAP-01.mdx => PSP-1 - Capability Model and Grammar.mdx} (57%)
 create mode 100644 docs/reference/specifications/PSP-2 - Receipt Model.mdx
 create mode 100644 docs/reference/specifications/PSP-3 - Sigchain and Envelope.md
 rename docs/reference/specifications/{acceptance/TAP-01.mdx => PSP-6 - TAP.mdx} (100%)
 delete mode 100644 docs/reference/specifications/receipts/RSC-01.mdx
 create mode 100644 docs/reference/wedges/README.md

diff --git a/docs/reference/specifications/capabilities/PCAP-01.mdx b/docs/reference/specifications/PSP-1 - Capability Model and Grammar.mdx
similarity index 57%
rename from docs/reference/specifications/capabilities/PCAP-01.mdx
rename to docs/reference/specifications/PSP-1 - Capability Model and Grammar.mdx
index 46ce57f5..1334371c 100644
--- a/docs/reference/specifications/capabilities/PCAP-01.mdx
+++ b/docs/reference/specifications/PSP-1 - Capability Model and Grammar.mdx	
@@ -1,4 +1,4 @@
-# PCAP-01 - Polykey Capability Grammar
+# PSP-1 - Capability Model and Grammar
 
 <details>
   <summary>Metadata</summary>
@@ -14,13 +14,13 @@
     <dt>Obsoletes:</dt>
     <dd>-</dd>
     <dt>Depends on:</dt>
-    <dd>SIGCHAIN-01, PRSC-01, PRIVACY-01</dd>
+    <dd>PSP-2, PSP-3</dd>
   </dl>
 </details>
 
 ## Abstract
 
-PCAP-01 defines the portable, verifiable capability model used by the Polykey to express delegated authority. It specifies the structure and semantics of identity-bound authority Grants (capability tokens) and Presentations (ephemeral proofs of capability), including verbs, resource addressing, binding constraints, attenuation, and revocation. PCAP-01 ensures capabilities are composable, attenuable (never broadened), aggregable, and safely verifiable at enforcement points. Enforcement behavior, receipt formats, channel-binding profiles, and lease rotation are specified in separate documents; this document defines the core data model and verification semantics.
+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
 
@@ -30,48 +30,208 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S
 - **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 signed, portable capability token issued by P to S.
-- **Presentation (Π):** An ephemeral, proof-of-possession token created by S that references a Grant with context and channel binding. It is NOT stored on-chain.
-- **Bind:** Binding constraints inside a Grant that restrict its use (e.g., audience, purpose, time, context, channel).
-- **Attenuation:** The act of narrowing a capability when delegating. A derived Grant MUST be a subset of its parent capability.
-- **Verification (Σ):** The set of checks performed by a CEP to validate a Presentation against a Grant and its Bind constraints. As shown in diagrams, this is represented as: `Σ = verify(Π, G, Bind, Channel, TTL, Attenuation?, Lease?)`. A successful verification implicitly establishes a session for enforcement.
+- **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.
-- **Access PoAR:** The Proof-of-Action receipt written by the enforcing CEP (defined in PRSC-01).
-- **Caveat:** A declarative, safety-preserving constraint embedded in or referenced by a Grant. Caveats MUST be attenuating, decidable, bounded in runtime, and side-effect free. Evaluation is performed by CEPs. Unknown or unsupported caveats MUST cause deny unless a TAP explicitly specifies a safe fallback.
-- **Authority:** The identity-bound permission represented by a Grant; the effective authority for a use is the intersection of the Grants presented and any caveats.
-- **Secret:** A bearer credential (e.g., token/key) used in the data plane. Secret issuance/derivation/aggregation and exposure semantics are specified in the CEP/BA spec, not in PCAP-01.
+- **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
 
-PCAP-01 provides the core capability model for Polykey: the data structures and verification semantics that allow independent parties to mint, hold, present, and verify capabilities across boundaries.
+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 PCAP-01 defines:
 
-- A minimal, expressive grammar for capabilities: verbs over resources constrained by Bind.
-- Bind (binding constraints) to tie capability use to audience, purpose, time, context, and channel.
-- A safe delegation model: capabilities can be attenuated and re-delegated, but MUST NEVER broaden authority.
-- Ephemeral Presentations that are resistant to theft and replay via proof-of-possession and channel binding.
-- Verification semantics (Σ): the set of checks a CEP performs to validate a Presentation against a Grant and Bind.
+- 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: Core fields are few and clearly defined; extensibility via content-addressed vocabularies/registries.
+- 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; explicit time windows.
-- Receipt-ready: Verification requires a stable Bind snapshot so that CEPs can record bind_snapshot in Access PoARs (per PRSC-01).
+- 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 PCAP-01):
+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.
-- Receipt schemas: All receipt formats (PoAR/VOR/View) are specified in PRSC-01.
-- Channel-binding mechanisms: Concrete binding profiles (e.g., TLS exporter, DPoP) are profiled elsewhere; PCAP-01 only requires a verified binding.
-- Lease lifecycle/rotation: Lease issuance and rotation policies are defined elsewhere; PCAP-01 only requires Lease freshness to be verified when Grants touch non-native SoA (enforced by CEP per TAP).
-- Global time/ordering: PCAP-01 does not require a global clock or total order. Acceptance (TAP) specifies clock sources and tolerances.
-- Transport and messaging: PCAP-01 is transport-agnostic.
-- Serialization and envelope formats (e.g., JSON+JWS, CBOR+COSE, DSSE) are out of scope; see binding profiles and SIGCHAIN-01 for canonicalization/signatures.
-- Caveat languages are out of scope; CAP only defines the caveats extension point and safety properties. TAP/binding profiles MAY specify concrete caveat profiles.
-- Secret derivation/aggregation cryptography and interactive evaluation flows are specified in the CEP/BA spec (not PCAP-01). PCAP-01 only models authority attenuation and (optional) composite/threshold caveats over Grants.
+- 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<Str, Term>` - 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
 
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 00000000..85196b9b
--- /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.md b/docs/reference/specifications/PSP-3 - Sigchain and Envelope.md
new file mode 100644
index 00000000..acc936b6
--- /dev/null
+++ b/docs/reference/specifications/PSP-3 - Sigchain and Envelope.md	
@@ -0,0 +1 @@
+# PSP-3 - Sigchain and Envelope
diff --git a/docs/reference/specifications/acceptance/TAP-01.mdx b/docs/reference/specifications/PSP-6 - TAP.mdx
similarity index 100%
rename from docs/reference/specifications/acceptance/TAP-01.mdx
rename to docs/reference/specifications/PSP-6 - TAP.mdx
diff --git a/docs/reference/specifications/receipts/RSC-01.mdx b/docs/reference/specifications/receipts/RSC-01.mdx
deleted file mode 100644
index e69de29b..00000000
diff --git a/docs/reference/wedges/README.md b/docs/reference/wedges/README.md
new file mode 100644
index 00000000..c32cfe51
--- /dev/null
+++ b/docs/reference/wedges/README.md
@@ -0,0 +1,37 @@
+# Wedge Portfolio
+
+Trust Graphs
+
+- Blockchain Wallet Reputation
+- Email Sender Reputation
+- Sayari Supply Chain Trust
+
+- 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 compliance (Fair Work–style dispute trail)
+  - Verifier: regulator/tribunal; corporate audit
+  - Value: standardized settlement-grade artifacts → faster resolution
+  - T1R: 4–6 weeks (one HR/legal team)
+
+
+
+
+

From cb9fa69269b4170c13788a0c32b253176d6ee348 Mon Sep 17 00:00:00 2001
From: Roger Qiu <roger.qiu@polyhack.io>
Date: Tue, 16 Sep 2025 14:47:55 +1000
Subject: [PATCH 6/9] wip

---
 .../specifications/PSP-1 - Capability Model and Grammar.mdx   | 4 ++--
 ...hain and Envelope.md => PSP-3 - Sigchain and Envelope.mdx} | 0
 sidebars.ts                                                   | 4 +++-
 3 files changed, 5 insertions(+), 3 deletions(-)
 rename docs/reference/specifications/{PSP-3 - Sigchain and Envelope.md => PSP-3 - Sigchain and Envelope.mdx} (100%)

diff --git a/docs/reference/specifications/PSP-1 - Capability Model and Grammar.mdx b/docs/reference/specifications/PSP-1 - Capability Model and Grammar.mdx
index 1334371c..dd97de34 100644
--- a/docs/reference/specifications/PSP-1 - Capability Model and Grammar.mdx	
+++ b/docs/reference/specifications/PSP-1 - Capability Model and Grammar.mdx	
@@ -47,7 +47,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S
 
 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 PCAP-01 defines:
+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.
@@ -257,7 +257,7 @@ Normative requirements:
 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 PRSC-01), not in PCAP-01.
+- 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
diff --git a/docs/reference/specifications/PSP-3 - Sigchain and Envelope.md b/docs/reference/specifications/PSP-3 - Sigchain and Envelope.mdx
similarity index 100%
rename from docs/reference/specifications/PSP-3 - Sigchain and Envelope.md
rename to docs/reference/specifications/PSP-3 - Sigchain and Envelope.mdx
diff --git a/sidebars.ts b/sidebars.ts
index e6d098f6..1c1dabf9 100644
--- a/sidebars.ts
+++ b/sidebars.ts
@@ -103,7 +103,9 @@ const sidebars: SidebarsConfig = {
             id: 'reference/specifications/README'
           },
           items: [
-            'reference/specifications/capabilities/PCAP-01'
+            'reference/specifications/PSP-1 - Capability Model and Grammar',
+            'reference/specifications/PSP-2 - Receipt Model',
+            'reference/specifications/PSP-3 - Sigchain and Envelope'
           ],
         },
         {

From da257191851bf01c21e3c16761289f3feee097e9 Mon Sep 17 00:00:00 2001
From: Roger Qiu <roger.qiu@polyhack.io>
Date: Wed, 8 Oct 2025 15:29:54 +1100
Subject: [PATCH 7/9] wip: wedges

---
 docs/reference/wedges/README.md | 34 +++++++++++++++++++++++++++++++--
 1 file changed, 32 insertions(+), 2 deletions(-)

diff --git a/docs/reference/wedges/README.md b/docs/reference/wedges/README.md
index c32cfe51..9e1b3ce4 100644
--- a/docs/reference/wedges/README.md
+++ b/docs/reference/wedges/README.md
@@ -2,9 +2,17 @@
 
 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
@@ -26,12 +34,34 @@ Trust Graphs
   - 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 compliance (Fair Work–style dispute trail)
+- Internal HR compliance (Fair Work–style dispute trail)
   - Verifier: regulator/tribunal; corporate audit
-  - Value: standardized settlement-grade artifacts → faster resolution
+  - 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.
 

From 02b4cb589df3ae13f534c9db1f57c063b6dd14b2 Mon Sep 17 00:00:00 2001
From: Roger Qiu <roger.qiu@polyhack.io>
Date: Thu, 9 Oct 2025 23:44:45 -0500
Subject: [PATCH 8/9] wip: almost onto Grants now

---
 .../PSP-1 - Capability Model and Grammar.mdx  | 154 +++++++++++++++++-
 .../specifications/PSP-4 - Registries.mdx     |   1 +
 .../specifications/PSP-5 - Attestations.mdx   |   1 +
 .../specifications/PSP-6 - TAP and RAM.mdx    |   1 +
 docs/reference/specifications/PSP-6 - TAP.mdx |   0
 ...SP-7 - CEP and Bridge Adapter Profiles.mdx |   1 +
 6 files changed, 152 insertions(+), 6 deletions(-)
 create mode 100644 docs/reference/specifications/PSP-4 - Registries.mdx
 create mode 100644 docs/reference/specifications/PSP-5 - Attestations.mdx
 create mode 100644 docs/reference/specifications/PSP-6 - TAP and RAM.mdx
 delete mode 100644 docs/reference/specifications/PSP-6 - TAP.mdx
 create mode 100644 docs/reference/specifications/PSP-7 - CEP and Bridge Adapter Profiles.mdx

diff --git a/docs/reference/specifications/PSP-1 - Capability Model and Grammar.mdx b/docs/reference/specifications/PSP-1 - Capability Model and Grammar.mdx
index dd97de34..654f126d 100644
--- a/docs/reference/specifications/PSP-1 - Capability Model and Grammar.mdx	
+++ b/docs/reference/specifications/PSP-1 - Capability Model and Grammar.mdx	
@@ -89,17 +89,18 @@ Capability evaluation depends on small, versioned rulebooks ("registries"):
 - 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.
+- PSP-4 MAY also define domain verb/resource registries (e.g., energy verbs; asset:/bacnet:/ocpp: schemes) and TAP-referenced trust registries (e.g., notary key lists, DKIM selector archives, origin key policies). CEPs do not consume these artifacts directly; if used, their outputs appear as environment facts and are asserted in Programs (e.g., via ctx_eq).
 
 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
+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
+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.
@@ -108,7 +109,7 @@ 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:
 
 - 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.
 
@@ -196,23 +197,26 @@ At verification, the CEP supplies an environment of facts. Builtins may referenc
   - enforcer: Str — DID/identifier of the enforcing CEP (audience).
   - channel: Str — profile representing the live session's binding.
   - ctx: `Map<Str, Term>` - runtime context (e.g., `{"ns":"prod","pod":"runner-42"}`).
-- Optional environment facts (TAP‑gated)
+- Optional environment facts (TAP-gated)
   - lease_status - opaque assurance/freshness input for lease checks (no I/O in the builtin).
+  - TAP MAY require additional environment facts (e.g., provenance labels, jurisdiction tags, or digest references) and define how they are obtained and verified. PSP-1 does not enumerate these; Programs assert them via equality (e.g., ctx_eq).
 - Missing facts (normative)
   - If a builtin present in the Program requires an environment fact that is missing, evaluation MUST fail closed.
 
-#### Bultins and registries
+#### Builtins 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.
+- Programs may constrain the live session's profile using `channel_geq(channel, "…")` as defined by the pinned channel lattice. Programs may also assert runtime or provenance context via equality over environment facts (e.g., ctx_eq("k","v")). How those environment facts are obtained or validated — including the presentation binding to a live session - is outside the CPL/0 language and governed by TAP and PSP-2.
 
 #### 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.
+- The `now: Int` fact is CEP-provided and subject to TAP time-discipline; PSP-1 is agnostic to the time source.
 
 #### Relationship with Biscuit Datalog (Informative)
 
@@ -225,9 +229,147 @@ At verification, the CEP supplies an environment of facts. Builtins may referenc
 
 ### Declarations
 
+Declarations are finite, canonical datasets that a Grant carries alongside the Program. Programs consult Declarations via builtins under pure, bounded evaluation (no network I/O). Declarations exist to express scope allowlists compactly and to make attenuation (subset) checks mechanical and fast.
+
+- Declarations MUST be finite, deterministically canonicalized (normalize, sort, deduplicate), and content-addressed (e.g., with a content identifier).
+- Declarations referenced by a Program MUST be bundled in the Grant so CEPs can evaluate without external fetches.
+- A CEP MUST deny if a Program references an unknown declaration kind or if a required scheme comparator is unavailable.
+
+#### PairSet
+
+- Definition: PairSet is a finite set of (action: Str, resource: Str) pairs.
+- Purpose: express an allowlist of "what actions on which resources" a capability can authorize.
+- Canonicalization:
+  - Normalize each resource string per its scheme's registry entry (PSP-4).
+  - Sort pairs lexicographically (e.g., by action, then by normalized resource bytes).
+  - Deduplicate exact duplicates.
+  - Content-address the canonical bytes to get a stable identifier (CID).
+- Portability: PairSets are bundled in the Grant payload (PSP-3 binds bytes) so a CEP can evaluate without network I/O.
+
+Use PairSet when the allowlist is irregular (different actions per resource) and a simple factorization would be incorrect.
+
+#### ActionSet
+
+ActionSet is a finite set of actions. It factorizes "what" independently of "where."
+
+- Canonicalization:
+  - Actions MUST be normalized as strings, sorted deterministically, and deduplicated.
+  - The canonical bytes MUST be content-addressed; the content address identifies the ActionSet.
+- Program use
+  - in_actionset(action, Actions#CID) evaluates to true if and only if action ∈ ActionSet(CID).
+- Attenuation
+  - For a derived Grant, the child ActionSet MUST be a subset of the parent ActionSet.
+
+#### ResourceSet
+
+ResourceSet is a finite set of resources (scheme-qualified strings) with scheme-defined subset semantics.
+
+- Canonicalization
+  - Each resource MUST be normalized per its scheme's registry entry.
+  - The set MUST be sorted deterministically and deduplicated.
+  - The canonical bytes MUST be content-addressed; the content address identifies the ResourceSet.
+- Program use
+  - in_resourceset(resource, Resources#CID) evaluates to true if and only if there exists r_sel ∈ ResourceSet(CID) with resource ⊆ r_sel under the scheme's registered subset comparator.
+- Attenuation
+  - For a derived Grant, the child ResourceSet MUST be a subset of the parent ResourceSet (under set inclusion, using the same normalization and comparator).
+
+Use ActionSet * ResourceSet when the policy is truly a cross-product ("any action in A over any resource in R"). Use PairSet when the matrix is irregular.
+
+#### Program Use
+
+- Declarations are data sources invoked via builtins; Programs combine these with other literals (within_time, ttl_ok, channel_geq, ctx_eq, presenter_is).
+- Actions appear as strings; resources are scheme-qualified strings; subset relations are defined per scheme in the registry (no unbounded regex/globs; selectors MUST be finite or safely bounded with a decidable comparator).
+- Unknown declaration kinds, schemes, or comparators MUST cause deny.
+
+#### Attenuation over Declarations
+
+- Delegation MUST NOT broaden Declarations.
+  - PairSet_child ⊆ PairSet_parent.
+  - ActionSet_child ⊆ ActionSet_parent.
+  - ResourceSet_child ⊆ ResourceSet_parent.
+- CEPs MUST verify subset relations hop-by-hop along the delegation chain using the same normalization and comparators; failures or unknowns MUST cause deny.
+
+#### Profiles
+
+- This specification standardizes exactly three Declaration kinds: PairSet, ActionSet, ResourceSet. Profiles MAY further constrain their usage (e.g., disallow ResourceSet for certain verbs) or prescribe default comparators per scheme. A CEP MUST deny if a Program references a declaration kind not supported by the active profile or if a required comparator is not available.
+
 ### Program Canonical Format (PCF) & Digest
 
-### Verbs & Resources
+Programs MUST be normalized to a canonical tree and deterministically encoded before deriving identity. Canonicalization ensures portable, stable program identifiers across implementations and platforms. The canonical bytes and multihash parameters are specified by PSP-3; this section defines the abstract normalization rules (PCF).
+
+#### Purpose
+
+- PCF yields a unique representation for a Program so syntactic permutations or duplicate literals do not change identity.
+- Canonicalization applies to the abstract Program (Checks, Queries, Literals and their arguments), independent of transport/envelope.
+
+#### Normalization rules
+
+- Literals within a Query MUST be sorted by a total order over:
+  - literal kind (e.g., Builtin before Atom if Atoms are present),
+  - operator/predicate identifier (text in NFC, bytewise),
+  - arguments tuple under canonical term order.
+- Duplicate Literals within a Query MUST be removed.
+- Queries within a Check MUST be sorted lexicographically by their canonical literal lists and duplicates removed.
+- Checks within a Program MUST be sorted lexicographically by their canonical query lists and duplicates removed.
+
+#### Canonical term order
+
+- Strings MUST be NFC-normalized and compared/encoded as exact bytes.
+- Integers MUST be arbitrary-precision, with no float encodings.
+- Bytes MUST be exact octets, ordered lexicographically.
+- Booleans MUST use canonical forms, with false < true for ordering.
+- Environment and declaration references (e.g., "action", "resource", "Pairs#CID") MUST be encoded deterministically and consistently wherever they appear.
+
+#### Prohibited/non-canonical forms
+
+- Floating-point numbers MUST NOT appear in Programs.
+- Indefinite-length encodings and non-normalized strings MUST NOT appear in canonical bytes (see PSP-3 for encoding constraints).
+- Any literal or term introducing non-determinism or network I/O MUST NOT be part of a Program.
+
+#### Deterministic encoding and identity
+
+- program_bytes = ENCODE(PCF(Program)) as specified by PSP-3.
+- program_id = multihash(program_bytes) as specified by PSP-3.
+- A Grant carrying program_bytes and program_id MUST be rejected if recomputation does not match.
+
+#### Failure handling
+
+- Canonicalization MUST fail, and verification MUST deny, if a Program contains an unknown operator, ill-typed arguments under a builtin's signature, non-normalized strings, prohibited numbers, or otherwise cannot be normalized.
+- Unknown builtins, schemes, or comparators referenced by the Program MUST cause deny during evaluation; if their presence prevents deterministic term encodings, identity derivation MUST fail.
+
+#### Stability and tests
+
+- Canonicalization is part of the trusted computing base. Implementations SHOULD cross-test that semantically identical Programs (after literal reordering, duplicate removal, and string normalization) yield identical program_bytes and program_id across platforms and versions.
+
+#### Informative guidance
+
+Keep operator identifiers stable and registry-pinned to avoid PCF instability from renaming.
+When referencing Declarations by content address (e.g., “Pairs#CID”), ensure the reference syntax and encoding are deterministic and consistent.
+
+### Verbs & Resources (Reader Guidance)
+
+Verbs are namespaced strings (e.g., “secret:read”, “deploy:to_env”, “energy:curtail”). They appear as the action fact and as elements inside Declarations (PairSet/ActionSet). Verb semantics MUST be documented in a registry with versioned definitions. Registry entries SHOULD declare expected resource scheme(s) and any required constraints (e.g., time window, channel profile, mediated surface references). A CEP MUST deny if a required constraint is not asserted by the Program. TAP MAY whitelist verbs per domain; unknown verbs default to non‑permitted unless TAP specifies otherwise.
+
+Resources are scheme‑qualified identifiers (URI‑like) that denote targets (e.g., “vault:secret://org/team/key”, “k8s://ns/prod”, “asset:building‑12:rtu‑3”, “api:https://vendor.com/path”). They appear as the resource fact and as elements inside Declarations (PairSet/ResourceSet). Each resource scheme MUST have a registry entry defining normalization and a decidable subset comparator. Grants SHOULD use specific resources. If a scheme permits selectors, their use MUST be finite or safely bounded with a defined subset proof. Unknown schemes or unavailable comparators MUST cause deny. TAP MAY restrict acceptable schemes or forms per domain and verb.
+
+Delegation subset: For derived Grants, resource.child MUST be a subset of resource.parent under the scheme’s comparator; for Declarations, child sets MUST be subsets of parent sets.
+
+Programs consult finite allowlists via Declarations and evaluate constraints using builtins. Verb and scheme registries define documentation and comparators; unknowns fail closed.
+
+---
+
+## Grants
+
+## Presentations
+
+## Delegation && Attenuation
+
+## Verification Algorithm
+
+## Security Considerations
+
+
+
 
 
 
diff --git a/docs/reference/specifications/PSP-4 - Registries.mdx b/docs/reference/specifications/PSP-4 - Registries.mdx
new file mode 100644
index 00000000..f3f86122
--- /dev/null
+++ b/docs/reference/specifications/PSP-4 - Registries.mdx	
@@ -0,0 +1 @@
+# PSP-4 - Registries
diff --git a/docs/reference/specifications/PSP-5 - Attestations.mdx b/docs/reference/specifications/PSP-5 - Attestations.mdx
new file mode 100644
index 00000000..048e0038
--- /dev/null
+++ b/docs/reference/specifications/PSP-5 - Attestations.mdx	
@@ -0,0 +1 @@
+# PSP-5 - Attestations
diff --git a/docs/reference/specifications/PSP-6 - TAP and RAM.mdx b/docs/reference/specifications/PSP-6 - TAP and RAM.mdx
new file mode 100644
index 00000000..1f13ad88
--- /dev/null
+++ b/docs/reference/specifications/PSP-6 - TAP and RAM.mdx	
@@ -0,0 +1 @@
+# PSP-6 - TAP and RAM
diff --git a/docs/reference/specifications/PSP-6 - TAP.mdx b/docs/reference/specifications/PSP-6 - TAP.mdx
deleted file mode 100644
index e69de29b..00000000
diff --git a/docs/reference/specifications/PSP-7 - CEP and Bridge Adapter Profiles.mdx b/docs/reference/specifications/PSP-7 - CEP and Bridge Adapter Profiles.mdx
new file mode 100644
index 00000000..c64ad288
--- /dev/null
+++ b/docs/reference/specifications/PSP-7 - CEP and Bridge Adapter Profiles.mdx	
@@ -0,0 +1 @@
+# PSP-7 - CEP and Bridge Adapter Profiles

From 694c02c0e019bbf4d1510a4092bff4736e67030b Mon Sep 17 00:00:00 2001
From: Roger Qiu <roger.qiu@polyhack.io>
Date: Fri, 10 Oct 2025 14:53:12 -0500
Subject: [PATCH 9/9] wip: finally ready to work on grants for PSP1

---
 .../PSP-1 - Capability Model and Grammar.mdx  | 276 +++++++++++++-----
 1 file changed, 206 insertions(+), 70 deletions(-)

diff --git a/docs/reference/specifications/PSP-1 - Capability Model and Grammar.mdx b/docs/reference/specifications/PSP-1 - Capability Model and Grammar.mdx
index 654f126d..e3fad430 100644
--- a/docs/reference/specifications/PSP-1 - Capability Model and Grammar.mdx	
+++ b/docs/reference/specifications/PSP-1 - Capability Model and Grammar.mdx	
@@ -35,6 +35,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S
 - **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.
+- **CPL**: Capability Programming Language.
 - **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.
@@ -225,7 +226,9 @@ At verification, the CEP supplies an environment of facts. Builtins may referenc
   - 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.
+- Interop: Biscuit tokens in the checks-only fragment can be normalized into CPL/0. If rules are required in a domain, 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.
+
+Because CPL/0 is checks-only over ground terms with pure, bounded builtins, CEPs evaluate Programs deterministically and emit minimal proof traces (which check, which query, which literals). This keeps receipts auditable without a general Datalog engine. If richer inference is required in a domain, issuers or attestors SHOULD precompute finite sets (content-addressed) and reference them from the Program; alternative profiles that carry ruleful logic MUST remain TAP-gated and provide either a compiled CPL/0 guard or an approved verifier runtime.
 
 ### Declarations
 
@@ -235,10 +238,57 @@ Declarations are finite, canonical datasets that a Grant carries alongside the P
 - Declarations referenced by a Program MUST be bundled in the Grant so CEPs can evaluate without external fetches.
 - A CEP MUST deny if a Program references an unknown declaration kind or if a required scheme comparator is unavailable.
 
+There are 2 kinds of literals in declarations: actions and resources.
+
+#### Actions
+
+Actions are namespaced strings. They appear as elements inside PairSet/ActionSet.
+
+- deploy:to_env
+- access:open
+- energy:curtail
+- secret:read
+- secret:derive
+- data:export
+- model:infer
+
+Normative requirements:
+
+- Action semantics MUST be documented in a public or private registry with versioned definitions.
+- An action's registry entry SHOULD declare expected resource scheme(s) and any required Program constraints (e.g., time window, channel profile, mediated-surface references); a CEP MUST deny if a required constraint is not asserted by the Program.
+- TAP profiles MAY whitelist action sets per domain and MUST reference stable, versioned entries.
+- Implementations MUST treat unknown actions as non-permitted unless explicitly allowed by TAP.
+
+Extensions and vocabularies:
+
+- Registries SHOULD be content-addressed 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 action semantics via versioned registry entries referenced by TAP; unknown or mismatched entries MUST be denied unless TAP explicitly provides an alias/mapping.
+
+#### Resources
+
+Resources identify targets and SHOULD be expressed as URIs (or URI-like identifiers) with scheme-specific rules. They appear as elements inside PairSet/ResourceSet.
+
+- `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`
+- `asset:building-12:rtu-3`
+
+Normative requirements
+
+- Scheme registry: Each resource scheme MUST be documented in a registry entry that defines normalization and a decidable subset/narrowing comparator. Registries SHOULD be content-addressed.
+- Specificity: Grants SHOULD use specific resources. If a scheme permits selectors or wildcards, their use MUST be constrained by Program constraints 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 registered 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).
+
 #### PairSet
 
-- Definition: PairSet is a finite set of (action: Str, resource: Str) pairs.
-- Purpose: express an allowlist of "what actions on which resources" a capability can authorize.
+PairSet is a finite set of (action: Str, resource: Str) pairs. It enumerates exactly which action/resource combinations are authorized.
+
 - Canonicalization:
   - Normalize each resource string per its scheme's registry entry (PSP-4).
   - Sort pairs lexicographically (e.g., by action, then by normalized resource bytes).
@@ -277,7 +327,7 @@ Use ActionSet * ResourceSet when the policy is truly a cross-product ("any actio
 
 #### Program Use
 
-- Declarations are data sources invoked via builtins; Programs combine these with other literals (within_time, ttl_ok, channel_geq, ctx_eq, presenter_is).
+- Programs consult Declarations via builtins (in_pairset, in_actionset, in_resourceset) using the environment's action and resource facts, combined with other literals (within_time, ttl_ok, channel_geq, ctx_eq, presenter_is).
 - Actions appear as strings; resources are scheme-qualified strings; subset relations are defined per scheme in the registry (no unbounded regex/globs; selectors MUST be finite or safely bounded with a decidable comparator).
 - Unknown declaration kinds, schemes, or comparators MUST cause deny.
 
@@ -291,7 +341,7 @@ Use ActionSet * ResourceSet when the policy is truly a cross-product ("any actio
 
 #### Profiles
 
-- This specification standardizes exactly three Declaration kinds: PairSet, ActionSet, ResourceSet. Profiles MAY further constrain their usage (e.g., disallow ResourceSet for certain verbs) or prescribe default comparators per scheme. A CEP MUST deny if a Program references a declaration kind not supported by the active profile or if a required comparator is not available.
+This specification standardizes exactly three Declaration kinds: PairSet, ActionSet, ResourceSet. Profiles MAY further constrain their usage (e.g., disallow ResourceSet for certain verbs) or prescribe default comparators per scheme. A CEP MUST deny if a Program references a declaration kind not supported by the active profile or if a required comparator is not available.
 
 ### Program Canonical Format (PCF) & Digest
 
@@ -344,19 +394,7 @@ Programs MUST be normalized to a canonical tree and deterministically encoded be
 #### Informative guidance
 
 Keep operator identifiers stable and registry-pinned to avoid PCF instability from renaming.
-When referencing Declarations by content address (e.g., “Pairs#CID”), ensure the reference syntax and encoding are deterministic and consistent.
-
-### Verbs & Resources (Reader Guidance)
-
-Verbs are namespaced strings (e.g., “secret:read”, “deploy:to_env”, “energy:curtail”). They appear as the action fact and as elements inside Declarations (PairSet/ActionSet). Verb semantics MUST be documented in a registry with versioned definitions. Registry entries SHOULD declare expected resource scheme(s) and any required constraints (e.g., time window, channel profile, mediated surface references). A CEP MUST deny if a required constraint is not asserted by the Program. TAP MAY whitelist verbs per domain; unknown verbs default to non‑permitted unless TAP specifies otherwise.
-
-Resources are scheme‑qualified identifiers (URI‑like) that denote targets (e.g., “vault:secret://org/team/key”, “k8s://ns/prod”, “asset:building‑12:rtu‑3”, “api:https://vendor.com/path”). They appear as the resource fact and as elements inside Declarations (PairSet/ResourceSet). Each resource scheme MUST have a registry entry defining normalization and a decidable subset comparator. Grants SHOULD use specific resources. If a scheme permits selectors, their use MUST be finite or safely bounded with a defined subset proof. Unknown schemes or unavailable comparators MUST cause deny. TAP MAY restrict acceptable schemes or forms per domain and verb.
-
-Delegation subset: For derived Grants, resource.child MUST be a subset of resource.parent under the scheme’s comparator; for Declarations, child sets MUST be subsets of parent sets.
-
-Programs consult finite allowlists via Declarations and evaluate constraints using builtins. Verb and scheme registries define documentation and comparators; unknowns fail closed.
-
----
+When referencing Declarations by content address (e.g., "Pairs#CID"), ensure the reference syntax and encoding are deterministic and consistent.
 
 ## Grants
 
@@ -364,7 +402,7 @@ Programs consult finite allowlists via Declarations and evaluate constraints usi
 
 ## Delegation && Attenuation
 
-## Verification Algorithm
+## CEP Verification Algorithm
 
 ## Security Considerations
 
@@ -375,57 +413,38 @@ Programs consult finite allowlists via Declarations and evaluate constraints usi
 
 ---
 
-## 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
+## Grants Revised...?
+
+Action:
+If this is legacy (bind‑first), either:
+Replace with a short “Grants carry Program (PCF bytes) and Declarations; envelope is PSP‑3; attenuation is syntactic,” or
+Keep this section as an informative projection, but add a banner note: “This ‘bind’ projection reflects an earlier model; the authoritative policy is the Program. Required dimensions per verb/domain are enforced via Program literals and registries.”
+Remove “caveat” from core; if needed, mark it as “reserved for profiles; TAP‑forbidden by default.”
+
+Purpose: define define what a Grant carries (Program + Declarations), how it’s framed (PSP‑3), and the core attenuation rule for derived Grants.
+Suggested structure and content:
+Scope and framing
+A Grant is a durable, signed statement on the issuer issuer’s sigchain carrying:
+program_bytes (PCF(Program) per PSP‑3),
+program_id (multihash(program_bytes) per PSP‑3),
+declarations (content‑addressed tables referenced by by the Program).
+The envelope (issuer, subject, times, prev, signatures) and canonical bytes are specified in PSP‑3.
+Payload requirements (normative)
+MUST carry program_bytes and program_id; recomputation MUST match.
+If the Program references any Declaration content id, the corresponding declaration MUST be bundled in the Grant (no network fetch at evaluation).
+MUST pin lang_version and builtins_id; MUST pin channel_lattice_id if channel_geq is used.
+Attenuation by derivation (preview; full rules in Delegation section)
+Any derived Grant MUST carry and Declarations that are syntactically narrower:
+add checks and/or tighten constants (see Builtins tightening),
+Declarations child ⊆ parent (PairSet/ActionSet/ResourceSet),
+action/resource constraints only narrow (viavia literals and declarations).
+Fail‑closed on unknowns
+Unknown builtins, registry entries (verbs/schemes), lattices, or unsupported declaration kinds MUST cause deny at verification.
+Informative projection (optional)
+Show a small JSON projection with:
+program_id, program (base64url of PCF bytes bytes), decl: { pairsets/actions/resources }, envelope fields (issuer, subject, times) as placeholders with a note: “binding to JOSE/COSE/DSSE per PSP‑3.”
 
-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
+## Grants
 
 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.
 
@@ -595,9 +614,53 @@ Minimal JSON skeleton (illustrative):
 }
 ```
 
+## Presentations Revised
+
+Purpose: define the ephemeral token that proves holder‑of‑key and binds to the live session; it references a Grant and carries runtime ctx.
+Suggested structure and content:
+Structure and fields (normative)
+Required: grant_ref, iss (presenter DID), iat, exp (Presentation lifetime), jti (nonce), channel binding { profile, value }, ctx { k:v }.
+Delegation material: embedded grants (preferred for offline) or grant_refs with resolvers (TAP‑controlled).
+MUST NOT be written to sigchains.
+Verification requirements (normative)
+CEP MUST verify:
+PoP (presenter’s signature),
+channel binding matches the live session,
+exp − iat within acceptable Presentation TTL (as constrained by the Program),
+ctx includes at least the Program‑required key/values (ctx superset),
+grant_ref resolves to a valid Grant and, if a chain is present, custody and syntactic attenuation verify.
+Fail‑closed
+Unknown binding profile, missing required ctx keys, invalid grant_ref or custody, or expired/early use MUST cause deny.
+Minimal example (projection)
+Keep a short JSON fragment (similar to the one you already have) with grant_ref, channel binding, ctx, iat/exp/jti.
+
+## Delegation & Attenuation
+
+Purpose: define the rules for deriving a Grant from from a parent and how CEPs check a chain.
+Suggested structure and content:
+Chain custody (normative)
+issuer(child) == subject(parent) per hop; signatures and prev linking per PSP‑3; cycles denied; TAP MAY cap max depth.
+Syntactic attenuation (normative)
+Checks_child ⊇ Checks_parent (adding checks narrows authority).
+For any parent Query selected, child Query literals ⊇ parent literals; constants only tighten per builtins’ tightening rules.
+Declarations_child ⊆ Declarations_parent (PairSet, ActionSet, ResourceSet).
+Context keys: parent ctx_eq(k,v) requirements MUST be preserved or further constrained; Presentation.ctx MUST be a superset (equal values) at enforcement.
+Registry pins across the chain (normative)
+lang_version, builtins_id, and (if used) channel_lattice_id MUST match across all hops; unknown or mismatched registry entries MUST cause deny.
+Anchoring and TAP
+Root issuer anchoring for the target resource domain is governed by TAP; verification MUST fail if no applicable anchoring method exists.
+Informative example
+Show a 2‑hop chain (P→S→S2) where the child shrinks PairSet and shortens time.
+
+## Attenuation and Delegation Revised...?
+
+Action:
+Add explicit ctx rule: “Any ctx_eq(k,v) in parent must be preserved or tightened in child; at enforcement, Presentation.ctx ⊇ required keys with equal values.”
+Add profile clause: “If a profile introduces PolicyBundle declarations, child bundles MUST be subsets of parent bundles under the registry comparator.”
+
 ---
 
-## 8. Revocation and rotation
+## Revocation and rotation
 
 ### 8.1 Revocation
 
@@ -609,6 +672,9 @@ sigchain:
 - ViewReceipts SHOULD include knowledge of revocation state at time of action
   (via bind_snapshot + revocation check in PoAR).
 
+Regarding vote delegation on ethereum (profile/adapter)
+Revocation is a first‑class claim in PSP‑3; the CEP MUST check revocation before enforcement. If an on‑chain delegation registry (e.g., delegate.cash) is used, treat it as an attested input surfaced to the CEP (no network I/O in builtins).
+
 ### 8.2 Rotation
 
 For secret-bound flows (PS-BA/SS-BA), upstream leases and secrets MUST be
@@ -634,6 +700,21 @@ Given a Presentation p from S and an asserted Grant G:
    - Deliver PoAR to S.
 6. If any check fails, mint DenyReceipt with reason_code and deliver to S.
 
+## CEP Verification Algorithm Revised
+
+Purpose: a stepwise, normative checklist for CEPs at enforcement.
+Suggested structure and content (short and crisp):
+Parse Presentation; extract grant_ref and any embedded chain; verify PoP and channel binding.
+Resolve/verify the leaf Grant:
+Signature(s), issuer/subject, times, revocation (per PSP‑3).
+If chain present:
+Verify custody hop‑by‑hop; prev linkage; registry pin compatibility; syntactic attenuation; anchoring at root per TAP.
+Build environment facts (action, resource, now, iat, presenter, enforcer, channel, ctx) and load declarations from the Grant.
+Evaluate Program with bounded resources:
+within_time, ttl_ok, channel_geq, ctx_eq, in_pairset/in_actionset/in_resourceset; unknowns fail closed.
+On success, enforce and emit an Access PoAR (per PSP‑2); on failure, emit a DenyReceipt (per PSP‑2).
+Note: Keep it consistent with your existing Section 9 algorithm. Only add the explicit ctx superset phrasing if not present.
+
 ## 10. Security considerations
 
 - Holder-of-key (PoP) + channel binding prevent token theft and replay.
@@ -646,6 +727,9 @@ Given a Presentation p from S and an asserted Grant G:
 - Privacy: Do not include raw PII in Grants/Presentations; use DIDs and
   contextual claims; ViewReceipts handle selective disclosure.
 
+“Canonicalization and registry pinning are part of the trusted computing base; implementers SHOULD cross‑test PCF stability and reject Programs that cannot be normalized or reference unknown registry entries.”
+
+
 ## 11. Examples (JSON)
 
 Grant (P → S; deploy to prod for artifact H)
@@ -686,6 +770,58 @@ Presentation (S → CEP)
 }
 ```
 
+Dispatch‑bound energy curtail: Program with in_pairset, within_time, ttl_ok, channel_geq, ctx_eq("site","Zeta"), ctx_eq("instruction_digest","sha256:…"); declaration PairSet; a child Grant narrowing time and PairSet; a Presentation binding to TLS exporter.
+DevOps secrets read: Program with in_resourceset or in_pairset for vault:secret paths; ctx_eq("ns","prod"); channel_geq("mtls:v1"); short TTL.
+
+## Appendices
+
+ADT CDDL (informative) for CPL/0 Program and Declarations (non‑wire).
+Builtins table with tightening rules (within_time interval tightening; ttl_ok ≤; channel_geq floor ≥; in_pairset/resource subset; ctx_eq equality).
+Scheme comparator requirements (normalization steps, subset comparator shape, ban on unbounded regex/globs).
+
+## Profiles/Adapters
+
+Profiles above is sometimes mentioned but not explicitly explained what these are. We talk about TAP/RAM profiles and stuff and channel profiles, but it's not clear if some reason there's implications in relation to the PSP1 from a profile. Consider this example talking about how eth vote delegations might apply to PSP1:
+
+```
+Principal/Subject/delegation
+Cold wallet (P) issues a Grant to the hot wallet (S), optionally allowing S to delegate further (S → S2) under attenuation (never broaden).
+Scope and semantics
+Use PairSet to enumerate allowed actions/resources, e.g. ("airdrop:claim", "eth://1/0xAirdropContract/*") or ("nft:transfer", "eth://1/0xNFT/Token#1234").
+Add time/TTL/channel/context via builtins: within_time, ttl_ok, channel_geq (for the web/app CEP), ctx_eq("app","airdrop-portal").
+Custody and PoP
+Presentation is PoP‑bound to the hot wallet’s DID/key (or an ERC‑1271 smart account key) and channel‑bound (e.g., TLS exporter) when interacting off-chain.
+Revocation
+Revocation is a first‑class claim in PSP‑3; the CEP MUST check revocation before enforcement. If an on‑chain delegation registry (e.g., delegate.cash) is used, treat it as an attested input surfaced to the CEP (no network I/O in builtins).
+On‑chain integration
+Represent on‑chain targets via a resource scheme (eth://<chainId>/<contract>[/tokenId]); the resource comparator is defined in the Schemes registry (PSP‑4).
+Any on‑chain “isDelegated” check is performed by an adapter/attestor; the CEP consumes a verified fact in ctx (e.g., ctx_eq("eth_delegated","true")).
+```
+
+It might be good to explicitly explain what we mean here. Especially since the PSP1 shouldn't change or be
+extendeed without explicitly explaining what we mean by a profile.
+
+Another example was this:
+
+```
+“CPL/0 v0.1 is a builtins‑only, ground‑term language. It does not include user‑defined atoms, variables, or rules. This keeps evaluation decidable with a small TCB and simple canonicalization. Delegation remains syntactic attenuation (adding checks, tightening constants, shrinking declarations). A future profile MAY introduce a Datalog‑like surface (atoms/variables/rules) without changing the core verification model; such a profile would be TAP‑gated and would define additional PCF normalization steps (e.g., variable alpha‑renaming).”
+```
+
+Take note the idea of "a future profile"... like what? Are we saying there's going to be a new PSP-X that eventually extends PSP-1 and introduces more biscuit/datalog style programs.
+
+## Other random stuff
+
+PolicyBundle??
+PolicyRef??
+No v0.1 that's stupid. We operate by PSP1,2,3,4... etc.
+
+6.3 Declarations — keep core PairSet; point to future sets
+Keep PairSet as the only core declaration in v0.1.
+Add one sentence:
+Generic finite string sets (e.g., JurisdictionSet, RegionSet) MAY be introduced by a PSP‑4 profile; until then, use ctx_eq equality or embed such constraints within PairSet resource schemes where appropriate.
+
+If the original intention was that declarations could have arbitrary new sets. I think this is problematic. Since at that point, it's just sets of strings. The only relevant set that has some special structure is the PairSet and there's an builtin meaning to it, being actions and resources, along with actionset and resourceset. If we need arbitrary other data, they isn't any special meaning associated with them unless there's also builtin operators like `in_jurisdictionset`. Wouldn't that end up implying additional operators. That's where I'm confused on whether this means user-defined atoms is possible here or whatever?
+
 ## Revision history
 
 - 2025-09-02: Initial draft edition (holder-of-key + channel binding; Bind