How each chapter is structured
Every chapter answers the same six questions, in the same order:- What it is. One paragraph, plain language.
- Why it was built. The real problem, usually quoted from the source’s own comments.
- How it works. Traced to real files, usually with line numbers.
- How it enables things, with an example. A real tutorial or test that proves the behavior, or an honest note that none exists yet.
- How to validate it yourself. The exact files to open.
- Integration requirements, where applicable: env vars, config, external dependencies.
Chapter 1: Trust Model and Domain Model
Chapter 2: Configuration and Bootstrapping
Chapter 3: Cryptography
Chapter 4: The Policy Engine and Evaluation
Chapter 5: Signal Binding and State Verification
Chapter 6: Capability and Policy Binding
Chapter 7: Policy Governance and the Maker-Checker Flow
Chapter 8: The Runtime Pipeline
Chapter 9: The Execution Authorization Envelope
Chapter 10: The Execution Gateway
Chapter 11: Credential Isolation
Chapter 12: Connectors
Chapter 13: The Storage Layer
Chapter 14: The API and HTTP Boundary
Chapter 15: Caller Authentication and Scoping
Chapter 16: Rate Limiting
Chapter 17: Audit and Evidence Trails
Chapter 18: Independent Verification
Chapter 19: Health and Readiness
Chapter 20: Integrating Parmana
Chapter 21: Deployment
Chapter 22: Testing Philosophy
Chapter 23: History and Open Questions
Corrections found while writing this book
Every chapter above was written by reading the actual current source, not by trusting existing documentation, tutorial comments, or.env.example. That process surfaced real
places where something written down elsewhere in this repository no longer matches the
code:
.env.exampleclaimsKEY_PROVIDER=aws-kms“does nothing.” False, see Chapters 2 and 3.- A live
.envsetsKMS_REGION/KMS_KEY_ALIAS, neither of which is read anywhere inpackages/*/src. The real variables areAWS_REGIONandAWS_ROLE_ARN. See Chapters 2 and 21. KeyBootstrapis effectively legacy, per its own siblingSignerBootstrap.ts’s comment. See Chapter 2.- A prior architecture assumption placed
ExecutionGatewayat a path that does not exist. The real location ispackages/execution-gateway/src/ExecutionGateway.ts. See Chapter 10. - An older claim that both
@parmana/replayand@parmana/receiptare unwired is only half true, receipt functionality is real and production-wired inside@parmana/crypto. See Chapter 18.
Other formats
Read it in the repository
Plain markdown, chapter by chapter, alongside the code it documents.
Download the PDF
Single-file download. Just an email address, no verification step.