Skip to content

Gate 16 remediation — remove stale execution chronology from durable decisions #16

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Maatify merged 2 commits into from
Sep 29, 2026
Merged

Gate 16 remediation — remove stale execution chronology from durable decisions #16

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6f94695
docs: remove stale decision execution chronology
megyptm Sep 29, 2026
7656565
docs: finish decision chronology cleanup
megyptm Sep 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/decisions/DEC-002-SINGLE-CAPABILITY-SOURCE-TOPOLOGY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
35 changes: 11 additions & 24 deletions docs/decisions/DEC-003-STATELESS-SIGNED-RETURN-TARGET-RUNTIME-SECURITY-BOUNDARY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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
Expand All @@ -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

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -317,20 +317,16 @@ 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

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

Expand Down Expand Up @@ -452,7 +448,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
Expand Down Expand Up @@ -872,7 +868,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/
Expand Down Expand Up @@ -902,8 +898,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
Expand Down Expand Up @@ -973,7 +967,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.
Expand All @@ -985,17 +979,10 @@ 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.

## 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 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.
Loading