Commit 365875c
committed
feat(psp-1): Major structural and terminological overhaul
This commit introduces a major refactoring of PSP-1 to improve clarity, precision, and implementer experience. The document has been restructured to separate normative statements from informative content, a consistent naming convention has been adopted, and several key concepts have been expanded and clarified.
A primary motivation is to make the specification more directly implementable by providing a clear normative kernel, explicit algorithms, and unambiguous terminology.
- **New Document Structure:**
- Introduced a "Normative Kernel" section (4) to consolidate all core verification logic.
- Added a new top-level "Artifacts" section (5) to provide detailed normative descriptions of `Grants`, `Presentations`, and `Delegation & Attenuation`.
- Massively expanded the "Motivation and Rationale" section (3) with detailed design principles, a threat model, and rationale for key design choices.
- Added a dedicated "Examples and Conformance Test Vectors" section (9).
- **Standardized Naming Convention:**
- All specification identifiers (builtin `op` names, pin IDs, context keys, conceptual fields) have been standardized to `lower-camelCase`.
- Examples: `grant_ref` -> `grantRef`, `builtins_id` -> `builtinsId`, `within_time` -> `withinTime`, `ctx_eq` -> `ctxEq`.
- Added a new section `2.3 Identifier & casing convention` to make this rule explicit.
- **Enhanced Semantic Pinning (BREAKING CHANGE):**
- **`schemesSnapshotId` Pin:** Grants **MUST** now include a `schemesSnapshotId` pin. This is a content-addressed manifest that maps resource schemes (e.g., `vault:`) to their exact comparator snapshot, preventing comparator drift. This was previously implicit and is now a required, verifiable pin.
- The "Semantic Pinning" section (4.4) has been completely rewritten to be more normative and precise about a Grant's required pins and delegation compatibility rules.
- **Expanded Definitions:**
- **New Terminology:** Added formal definitions for `Local Availability`, `CEP Placement Variants` (`CEP(R)`, `CEP(P)`, `CEP(S)`), and `Bridge Adapter (BA)`.
- **Pin:** The definition of a `Pin` is now more generic and detailed, covering CIDs and URIs.
- **Improved Normative Clarity:**
- **Verification Algorithm:** Rewritten into a more precise, step-by-step algorithm in section `4.6`.
- **Fail-Closed Catalogue:** Added a comprehensive table (`4.8`) summarizing all conditions that **MUST** result in a denial.
- **Time Model:** Added a dedicated section `4.7` to clarify the "single time capture" rule and the use of half-open intervals.
- **Documentation & Examples:**
- Added section `2.4 Interpretation of JSON Projections` to clarify that JSON examples are non-normative.
- Narrative examples in section `9.1` are now much more detailed, including illustrative Grant/Presentation projections and a CEP evaluation outline.
- Conformance test vectors are now integrated into the main body in section `9.2`.
- **PSP Dependencies:**
- `PSP-4` is now listed as a formal dependency.
- `PSP-2` is now listed as an "Informative reference" rather than a hard dependency for the core model.
- **Minor Changes:**
- Added a "Backwards Compatibility" section (7).
- Merged old "Overview and Goals" into the new "Motivation and Rationale" section.
- The CDDL grammar and builtin operator tables have been updated to reflect the new `camelCase` naming.
- Removed "Appendix D - Suggested Reason Codes" in favor of the fail-closed catalogue.
BREAKING CHANGE: This commit introduces significant breaking changes.
1. **Naming Convention:** All identifiers are now `lower-camelCase`. Implementations must update field names, builtin operator calls, and pin lookups.
2. **Required `schemesSnapshotId` Pin:** All Grants must now include the `schemesSnapshotId` pin. Verification logic must be updated to check for its presence and enforce compatibility across delegation chains.1 parent ab24200 commit 365875c
1 file changed
+1265
-989
lines changed
0 commit comments