From 6f94695198eabe889334d3011f4ee495ed65b2db Mon Sep 17 00:00:00 2001 From: Mohamed Abdulalim Date: Tue, 29 Sep 2026 21:21:57 +0300 Subject: [PATCH 1/2] docs: remove stale decision execution chronology --- ...C-002-SINGLE-CAPABILITY-SOURCE-TOPOLOGY.md | 4 ++-- ...RETURN-TARGET-RUNTIME-SECURITY-BOUNDARY.md | 23 +++++++------------ 2 files changed, 10 insertions(+), 17 deletions(-) diff --git a/docs/decisions/DEC-002-SINGLE-CAPABILITY-SOURCE-TOPOLOGY.md b/docs/decisions/DEC-002-SINGLE-CAPABILITY-SOURCE-TOPOLOGY.md index 1a9ea84..91bef04 100644 --- a/docs/decisions/DEC-002-SINGLE-CAPABILITY-SOURCE-TOPOLOGY.md +++ b/docs/decisions/DEC-002-SINGLE-CAPABILITY-SOURCE-TOPOLOGY.md @@ -22,14 +22,14 @@ **Source Topology: Single Capability** -When `src/` is materialized in a future Runtime Work Unit, it will follow: +The package source tree follows: ```text src/ └── {Responsibility}/ ``` -Responsibilities will be introduced only when supported by actual runtime responsibilities. No future Responsibility names are decided here. +The `src/` structure remains responsibility-based. Responsibilities are represented only where they correspond to an actual package responsibility; this decision does not create a Domain or Capability root. ## Rationale diff --git a/docs/decisions/DEC-003-STATELESS-SIGNED-RETURN-TARGET-RUNTIME-SECURITY-BOUNDARY.md b/docs/decisions/DEC-003-STATELESS-SIGNED-RETURN-TARGET-RUNTIME-SECURITY-BOUNDARY.md index cbfb928..28c2692 100644 --- a/docs/decisions/DEC-003-STATELESS-SIGNED-RETURN-TARGET-RUNTIME-SECURITY-BOUNDARY.md +++ b/docs/decisions/DEC-003-STATELESS-SIGNED-RETURN-TARGET-RUNTIME-SECURITY-BOUNDARY.md @@ -16,9 +16,9 @@ ## Context -`maatify/php-return-target` is currently a `Development / Unpublished` standalone package. It has no Public Runtime API implemented, no materialized `src/` directory, and no persistence or database behavior. `DEC-002` has closed the source topology as `Single Capability`. +`maatify/php-return-target` is a standalone package with an implemented Public Runtime API and a materialized `src/` directory. It has no persistence or database behavior. `DEC-002` has closed the source topology as `Single Capability`. -Before the first Runtime Work Unit, the material architecture, security boundary, Public Contract, crypto integration boundary, extensibility boundary, and persistence boundary must be recorded. Earlier implementations in Host projects are evidence for discussion only; they are not this package's contract. +The material architecture, security boundary, Public Contract, crypto integration boundary, extensibility boundary, and persistence boundary are recorded here. Earlier implementations in Host projects are evidence for discussion only; they are not this package's contract. The decision is designed to consume stable reusable capabilities rather than duplicate them: @@ -317,15 +317,13 @@ Because `maatify/crypto v1.0.0` does not expose a stable generic signing/HMAC Pu The canonical Runtime directly uses the Hash extension for HMAC operations and the JSON extension for canonical token payload serialization/deserialization and the `JsonSerializable` result contract. -When Runtime implementation begins under this `ACTIVE` decision, the package must declare: +The package declares the following direct Runtime requirements: ```text ext-hash * ext-json * ``` -as direct Runtime requirements. - This decision does not modify `composer.json`. ### 14. Clock @@ -452,7 +450,7 @@ Construction throws `InvalidReturnTargetConfigurationException` when: A successfully constructed `ReturnTargetConfig` is therefore valid canonical configuration and does not require service-level exception handling for these invariants. -Its future canonical placement is: +Its canonical placement is: ```text src/Config/ReturnTargetConfig.php @@ -872,7 +870,7 @@ The canonical package implementation does not own HTTP, PSR-7, framework integra This decision does not change `DEC-002`. Under this `ACTIVE` decision, the package remains `Source Topology: Single Capability`. -Future responsibilities may be materialized only when supported by real Runtime responsibilities: +The implemented Runtime uses these responsibility-based directories: ```text src/ @@ -902,8 +900,6 @@ src/DTO/VerifiedTokenPayloadDTO.php Interfaces are placed with the responsibility they describe when a more specific responsibility owns them. No root generic `Contract/` directory is created by default. -This Work Unit creates no source files. - The internal `VerifiedTokenPayloadDTO` belongs to the `DTO/` responsibility and does not expand the Public DTO contract. ### 34. Alternatives Considered @@ -973,7 +969,7 @@ Unknown-key classification relies only on the public `KeyProviderInterface` cont - Canonical verification validates the strict single-active-key invariant before key resolution. - Provider/infrastructure failures are not silently converted into unknown-token rejection. - Canonical issuance never returns an empty-`kid` or over-4096-byte token. -- Package exception hierarchy and stable error-code behavior are fixed before Runtime implementation. +- Package exception hierarchy and stable error-code behavior are fixed by this decision. - The canonical `rt1` payload has one deterministic JSON wire representation with exact member order and strict scalar types. - Canonical verification authenticates the literal received payload representation before JSON semantic processing and rejects non-canonical JSON representations. - The decoded HMAC-SHA256 signature must be exactly 32 bytes. @@ -985,10 +981,7 @@ Unknown-key classification relies only on the public `KeyProviderInterface` cont - Host-specific restrictions are possible through a restrict-only policy. - Hosts with materially different requirements can replace the service implementation entirely. - Canonical security guarantees do not automatically extend to custom implementations. -- The first Runtime source must be a real implementation, not a placeholder. -- `FILE-05` may be closed only with real Runtime code and PHPStan configuration. -- Composer dependencies remain unchanged until Runtime implementation begins. -- The Package Reference becomes the canonical current Public Contract after implementation. +- The Package Reference is the canonical current Public Contract. - README, usage examples, CI, and testing must follow the actual implemented behavior. - Any material boundary change after activation requires formal reopen or supersession. @@ -998,4 +991,4 @@ This record is indexed under `Active Decisions`. `DEC-001` and `DEC-002` remain ## Activation Status -Owner approval on `2026-09-28` activates this record. It is now implementation authority for the recorded scope. Dependent Runtime work may proceed only through bounded Work Units and the repository's normal Direct Lead Review process. This activation does not authorize Merge to `main`; every Merge still requires separate explicit Owner authorization. +Owner approval on `2026-09-28` activates this record. It is implementation authority for the recorded scope. Changes within this scope remain subject to bounded review and the repository's normal Direct Lead Review process. This activation does not authorize Merge to `main`; every Merge still requires separate explicit Owner authorization. From 7656565069962061d8df49a710cfe5947199a13a Mon Sep 17 00:00:00 2001 From: Mohamed Abdulalim Date: Tue, 29 Sep 2026 21:28:57 +0300 Subject: [PATCH 2/2] docs: finish decision chronology cleanup --- ...GNED-RETURN-TARGET-RUNTIME-SECURITY-BOUNDARY.md | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/docs/decisions/DEC-003-STATELESS-SIGNED-RETURN-TARGET-RUNTIME-SECURITY-BOUNDARY.md b/docs/decisions/DEC-003-STATELESS-SIGNED-RETURN-TARGET-RUNTIME-SECURITY-BOUNDARY.md index 28c2692..b49a497 100644 --- a/docs/decisions/DEC-003-STATELESS-SIGNED-RETURN-TARGET-RUNTIME-SECURITY-BOUNDARY.md +++ b/docs/decisions/DEC-003-STATELESS-SIGNED-RETURN-TARGET-RUNTIME-SECURITY-BOUNDARY.md @@ -30,7 +30,7 @@ The decision is designed to consume stable reusable capabilities rather than dup ### 1. Package Capability -`maatify/php-return-target` will be a standalone, framework-agnostic library responsible for this bounded flow: +`maatify/php-return-target` is a standalone, framework-agnostic library responsible for this bounded flow: ```text Untrusted internal return target @@ -40,7 +40,7 @@ Untrusted internal return target → verified internal return target ``` -The package will not execute redirects. +The package does not execute redirects. ### 2. Dual Integration Path @@ -192,7 +192,7 @@ The exact original representation remains the representation stored in the token ### 8. Stateless and Persistence Boundary -The package will be stateless. It will not own or require PDO, SQL, MySQL/MariaDB, Redis, a database, schema, migrations, a Repository, token persistence, nonce persistence, session persistence, or a one-time-token registry. It will not depend on `maatify/persistence`. +The package is stateless. It does not own or require PDO, SQL, MySQL/MariaDB, Redis, a database, schema, migrations, a Repository, token persistence, nonce persistence, session persistence, or a one-time-token registry. It does not depend on `maatify/persistence`. A token may be verified more than once while valid. A return-target token is not an authentication or authorization credential. One-time consumption is outside v1. @@ -324,11 +324,9 @@ ext-hash * ext-json * ``` -This decision does not modify `composer.json`. - ### 14. Clock -The canonical implementation will depend on `maatify/shared-common ^1.0` and consume `Maatify\SharedCommon\Contracts\ClockInterface`. It will not create a local Clock abstraction, and canonical expiry behavior will not use `time()` as its source. +The canonical implementation depends on `maatify/shared-common ^1.0` and consumes `Maatify\SharedCommon\Contracts\ClockInterface`. It does not create a local Clock abstraction, and canonical expiry behavior does not use `time()` as its source. ### 15. Exceptions @@ -988,7 +986,3 @@ Unknown-key classification relies only on the public `KeyProviderInterface` cont ## Decision Index Relationship This record is indexed under `Active Decisions`. `DEC-001` and `DEC-002` remain unchanged. This decision does not supersede either active decision. - -## Activation Status - -Owner approval on `2026-09-28` activates this record. It is implementation authority for the recorded scope. Changes within this scope remain subject to bounded review and the repository's normal Direct Lead Review process. This activation does not authorize Merge to `main`; every Merge still requires separate explicit Owner authorization.