Merged
Conversation
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.
PSP1 Review via GPT-5 Pro, Grok 4, Gemini 2.5 Pro, Claude Sonnet 4.5 - Semantics, Syntax and Structure
Author
|
Pipeline Attempt on 18666625976 for 00bc978 https://github.com/MatrixAI/Polykey-Docs/actions/runs/18666625976 |
Author
|
Pipeline Succeeded on 18666625976 for 00bc978 https://github.com/MatrixAI/Polykey-Docs/actions/runs/18666625976 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This is an automatic PR generated by the CI/CD pipeline. This will be automatically fast-forward merged if successful.