Skip to content

docs: make gate zero ratification-only #1915

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
ascorbic merged 2 commits into from
Jul 10, 2026
Merged

docs: make gate zero ratification-only #1915

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
08cddbb
docs: make gate zero ratification-only
ascorbic Jul 10, 2026
6b347ef
docs: align gate zero with RFC decisions
ascorbic Jul 10, 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
61 changes: 38 additions & 23 deletions .opencode/plans/delegated-release-service/implementation-plan.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,23 @@

Companion: [Implementation spec](./spec.md)

Status: execution plan pending Gate 0 decisions and feasibility results
Status: execution plan pending Gate 0 external validation

This plan turns the delegated release service spec into independently deliverable workstreams. It defines ownership boundaries, dependencies, integration gates, and completion criteria. It intentionally contains no time estimates.

## Stage Deliverables

| Stage | Deliverable | Repository change allowed |
| ------ | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| Gate 0 | RFC implementation clarifications, supported-platform matrix, and documented external research conclusions | Spec and plan updates only |
| Gate 1 | Experimental lexicons, generated types, and one shared verification contract | Production contract code and tests |
| Gate 2 | Secure delegated release service vertical slice | Service, client, and installer code and tests |
| Gate 3 | Independent install and minimum discovery enforcement | Installer and aggregator code and tests |
| Gate 4 | Hosted beta product and operational readiness | Console, notifications, tooling, operations, and conformance code |
| Gate 5 | Accurate historical policy enforcement and production launch evidence | Aggregator history implementation and production verification |

Gate 0 is deliberately not an implementation stage. RFC #1870 is the product and protocol decision; Gate 0 records only implementation clarifications and external validation required to begin implementation. Do not reopen RFC decisions unless its text is ambiguous, contradicts an existing constraint, or an external result makes it impossible. Do not add test harnesses, prototype services, package dependencies, root scripts, CI wiring, or production code for Gate 0. If external research changes an assumption, commit only the resulting spec or plan update.

## Outcomes

The implementation is complete when:
Expand Down Expand Up @@ -38,7 +51,7 @@ The implementation is complete when:

| ID | Workstream | Primary output |
| ----- | ------------------------------------- | ----------------------------------------------------------- |
| `W0` | Decisions and feasibility | Ratified contracts and proved platform assumptions |
| `W0` | Clarification and external validation | RFC-derived acceptance criteria and platform assumptions |
| `W1` | Protocol and lexicons | Profile policy and release provenance records |
| `W2` | Shared verification | One verification implementation for all consumers |
| `W3` | OAuth, crypto, and passkeys | Secure identity, grant custody, and approval primitives |
Expand Down Expand Up @@ -118,16 +131,18 @@ W0 record/auth/provenance feasibility

Required before protocol or service implementation is treated as production work:

- Package profile extension and repository anchor are ratified.
- Release baseline and declared-access escalation semantics are ratified.
- Public CLI spelling is decided.
- Package profile extension and repository anchor have an implementation acceptance table derived from the RFC.
- Release baseline and declared-access escalation semantics have an implementation acceptance table derived from the RFC.
- Public CLI spelling is `emdash-plugin`.
- Create-only repo scope works on each supported PDS without broad fallback.
- Confidential OAuth sessions can be restored and refreshed safely in workerd.
- The selected Sigstore implementation verifies a real GitHub provenance bundle in workerd.
- An aggregator event source can recover intermediate profile values with verifiable ordering.

Gate owner: `W0`.

Gate 0 evidence is an implementation-clarification note in the tracked spec/plan and, where useful, a link to an external reproduction or upstream issue. It is not a repository test suite. The umbrella PR records the accepted external-validation summary before implementation begins.

### Gate 1: Protocol and Verification Foundation

- New profile and release extension fixtures round-trip through generated lexicon types.
Expand Down Expand Up @@ -175,11 +190,11 @@ Gate owners: `W10`, `W12`.

## Workstream W0: Decisions and Feasibility

This workstream closes the implementation blockers in the spec. Its outputs are executable fixtures and recorded decisions, not exploratory prose alone.
This workstream closes the implementation blockers in the spec. Its outputs are RFC-derived acceptance criteria and concise research conclusions. It does not land product code, test fixtures, package dependencies, or internal prototypes.

### `W0.1` Ratify the record shape
### `W0.1` Record the profile contract acceptance criteria

Decide and update RFC #1870 with:
Extract from RFC #1870:

- Exact profile extension NSID.
- Exact location and canonical form of the signed repository URL.
Expand All @@ -188,13 +203,13 @@ Decide and update RFC #1870 with:
- Stable treatment of unknown provenance predicates.
- Experimental-to-stable NSID migration consequences for OAuth grants.

Output: accepted RFC text and matching JSON examples.
Output: an implementation acceptance table and matching JSON examples. Do not reopen the RFC decision unless its text is contradictory or ambiguous.

Dependencies: none.

### `W0.2` Ratify escalation semantics
### `W0.2` Record escalation acceptance criteria

Decide:
Extract from RFC #1870:

- Highest-semver current release as the baseline.
- First release uses empty access.
Expand All @@ -203,13 +218,13 @@ Decide:
- Unknown constraint changes are conservatively escalating.
- Which baseline changes invalidate an approval.

Output: decision table consumed directly by `W2.4` tests.
Output: an implementation acceptance table consumed directly by `W2.4` tests. Do not reopen the RFC decision unless its text is contradictory or ambiguous.

Dependencies: none.

### `W0.3` Prove create-only PDS support

Build a minimal confidential client and test:
Validate externally, against the candidate PDS implementations:

- `atproto repo:<experimental-release-nsid>?action=create` authorization.
- Successful release create.
Expand All @@ -219,13 +234,13 @@ Build a minimal confidential client and test:

Targets: Bluesky-hosted PDS and at least one alternative implementation intended for support.

Output: committed integration fixture or reproducible test harness plus compatibility matrix.
Output: a supported-PDS compatibility matrix and any required RFC/spec correction. Commit only the resulting spec/plan update; keep disposable clients and accounts outside this repository.

Dependencies: `W0.1` draft NSID.

### `W0.4` Prove confidential OAuth custody in workerd

Exercise real `@atcute/oauth-node-client` behavior with:
Research the real `@atcute/oauth-node-client` behavior needed by the future service:

- Private-key JWT and published JWKS.
- Separate client assertion and DPoP keys.
Expand All @@ -234,13 +249,13 @@ Exercise real `@atcute/oauth-node-client` behavior with:
- Concurrent refresh attempts under a D1 lease.
- Rotating refresh tokens and client assertion keys.

Output: service-auth prototype and exact persisted session requirements.
Output: exact persisted session requirements, lock expectations, key-rotation constraints, and any incompatible upstream behavior. Commit only a concise spec/plan update when the result changes the design.

Dependencies: none.

### `W0.5` Prove Sigstore verification in workerd

Use a real `actions/attest-build-provenance` bundle to map and verify:
Inspect a real `actions/attest-build-provenance` bundle and validate, outside this repository:

- Sigstore signature and transparency evidence.
- Artifact subject digest.
Expand All @@ -249,29 +264,29 @@ Use a real `actions/attest-build-provenance` bundle to map and verify:
- Workflow identity and SLSA builder fields.
- RFC `sourceRepository` and `builderId` mapping.

Output: Workers-compatible verifier choice, fixture, and field-mapping contract.
Output: a Workers-compatible verifier choice and exact field-mapping contract. Commit only the resulting spec/plan decision; fixture acquisition and experimentation remain external until `W2.5` implements the verifier.

Dependencies: `W0.1` provenance draft.

### `W0.6` Prove historical aggregator input

Publish profile states `strict -> relaxed -> strict` before the aggregator queue drains, with a release between transitions. Prove the chosen source can recover all values, ordering keys, CIDs, revisions, and commit proof material.
Determine whether an event source can recover profile states `strict -> relaxed -> strict`, with a release between transitions, after queue delay. The selected source must provide event-specific record values, ordering keys, CIDs, revisions, and verifiable commit proof material.

Output: selected event source and ingest prototype. If no source can provide this, return to the RFC before implementing cooldown semantics.
Output: a source-selection decision and explicit W10.1 constraints. If no source can provide this, return to the RFC before implementing cooldown semantics. Do not add an aggregator prototype to this repository.

Dependencies: none.

### `W0.7` Decide public CLI shape

Resolve `emdash-plugin` versus `emdash plugin`, including compatibility policy and documentation naming.
Use `emdash-plugin` as the v1 public command. A future `emdash plugin` alias is additive work, not a Gate 0 blocker.

Output: one command spelling used by `W8` and RFC examples.
Output: update the RFC examples and implementation documentation to use `emdash-plugin`.

Dependencies: none.

### W0 Completion

Gate 0 passes. Any failed feasibility spike changes the RFC or architecture before downstream work proceeds.
Gate 0 passes after `W0.1`, `W0.2`, and `W0.7` accurately reflect the RFC and established command decision, and the recorded conclusions for `W0.3` through `W0.6` reveal no incompatible external constraint. Any incompatible external result changes the RFC or architecture before downstream work proceeds.

## Workstream W1: Protocol and Lexicons

Expand Down
17 changes: 9 additions & 8 deletions .opencode/plans/delegated-release-service/spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Delegated Release Service Implementation Spec

Status: design draft pending RFC record-shape ratification and Phase 0 feasibility results
Status: design draft pending Phase 0 external validation

Source: [RFC PR #1870](https://github.com/emdash-cms/emdash/pull/1870), Attested Automated Publishing

Expand Down Expand Up @@ -1040,15 +1040,16 @@ Run a second suite against real GitHub OIDC and a real supported PDS in a contro

## Delivery Plan

### Phase 0: Feasibility spikes
### Phase 0: RFC clarification and external validation

- Prove create-only permission support on target PDSes.
- Prove confidential `private_key_jwt` OAuth with persistent DPoP session restoration in workerd.
- Prove distributed refresh locking under concurrent Worker requests.
- Prove Sigstore/SLSA verification in workerd.
- Resolve and prototype the aggregator historical-event source needed for policy-at-publication ordering. The prototype must recover two intermediate profile values changed before queue drain, not only their event metadata.
- Record implementation acceptance criteria for the profile extension, repository anchor, release provenance, and escalation contracts already decided by RFC #1870.
- Validate create-only permission support on target PDSes outside this repository.
- Confirm atcute confidential-client persistence, refresh-lock, and key-rotation constraints through external research or a disposable reproduction.
- Inspect a real GitHub provenance bundle and select the Workers-compatible Sigstore verifier plus exact field mapping.
- Select an aggregator history source that can retain event-specific signed profile values; document the constraints for the later W10.1 implementation.
- Use `emdash-plugin` as the v1 public command and update RFC examples accordingly.

Exit criterion: no unresolved platform blocker. These are spikes, not production shortcuts.
Exit criterion: implementation acceptance criteria accurately reflect RFC #1870 and external validation reveals no incompatible constraint. Gate 0 adds no repository harnesses, production code, test scripts, package dependencies, or CI wiring. If research changes an assumption, commit only the corresponding spec or plan update.

### Phase 1: Protocol and verification foundation

Expand Down
Loading